Glossary
The words used in Tsugumi’s documents and screens. See each row’s link for details.
Assembling processing
| Term | Meaning |
|---|---|
| Workflow | A graph of Cards connected by wires. The same thing a person draws, the Agent edits and the runtime executes (Rationale) |
| Card | A unit of processing, with input and output ports and settings (Cards and Workflows) |
| Code Card | A Card whose environment is defined in default.nix and whose processing is in src/ or its Nix run script (Your first Card) |
| Built-in Card | A Card without code, such as a Trigger, Input, Fork, Branch, Merge or Collect |
| Draft | An unimplemented Card with only a name and content. Wire Drafts up to draw a plan (their ports follow the wires) and have the Agent implement them |
| Card in Card (child Workflow) | A Card with a Workflow inside. From outside it looks like one Card; open it to go inside |
| Definition | The folder definitions/<id>/ that is a Card’s substance. One per Card |
| Port | A Card’s input or output. Output types are written in _outputs.fbs; input types are derived from the connected outputs |
allInputs / eachInput |
How inputs are awaited. allInputs waits for all required inputs; eachInput consumes arrivals independently (Execution semantics) |
maxRuns |
The most times a Card can be triggered in one Run. A trigger can start multiple invocations when it uses a run list or receives a batch |
Running and recording
| Term | Meaning |
|---|---|
| Run | One execution of a Workflow. Records the version (commit) at its start |
| Invocation | One execution of a Card within a Run. In a loop, the same Card is invoked many times |
| Batch | An ordered set of values sent together on one wire. A run list or batch input can produce several invocations for one trigger |
| Stage | A step within an invocation: SDK preparation, Nix evaluation, build, run, output validation, saving (Inspect a stage) |
skipped |
Downstream of a branch that was not taken. Not a failure |
blocked |
A Card that cannot run because of a failed, blocked or cancelled upstream Card, or missing required inputs. Comes with a reason. Drafts and paths requiring their outputs receive no execution state |
interrupted |
A run that was in progress when the process ended abnormally or restarted |
| Partial run (single run) | Running only the chosen Cards, or “from here”. Uses saved inputs (Rerunning from the middle) |
| Saved inputs | The full set of inputs of the latest trigger, including any batches. Partial runs use these inputs independently of recordIO |
recordIO |
A setting that keeps the input and output values of every invocation of a Card in the history (off by default) |
retainArtifact |
A setting that keeps a Card’s artifacts |
| Artifact | A file or folder a Card output |
| Display | The result a Card shows on screen: text, a table, an image, a chart and so on (Visualisation) |
| Version | A commit of the project’s git. A named version is an annotated tag (Versions) |
The runtime
| Term | Meaning |
|---|---|
tsugumi-agentd |
Host service owning Agent runs, settings, Skills, providers, execution authorization and project environment lifecycles (Architecture) |
tsugumid (the core) |
A process, one per project, that handles the document, the scheduler, Nix evaluation and history |
| RPC | The contract by which the UI, the Web and the Agent talk to tsugumid (Protocol.md) |
op_id |
The ID of a request that changes something. A resend with the same ID is applied only once |
| rev | The document’s revision. A save is based on it, and a save based on an old one is refused as a conflict |
| Shared VM | The one Linux VM that the Mac app and the Mac’s tsugumi command share. The signed helper holds vm.lock and agentd manages its resident project environments (Architecture) |
tsugumi-vmd |
The managing process inside the VM. Starts each project’s tsugumid with its own uid, namespaces and cgroup |
| Worker | The process that runs a Card’s code. Can stay resident across runs (Worker state) |
| bubblewrap / Seatbelt | How Cards are isolated: bubblewrap inside the VM and on Linux, Seatbelt in a Web UI run directly on a Mac from the repository |
| pkgsPath | The nixpkgs that Cards use, pinned (tsugumi.json) |
Agent
| Term | Meaning |
|---|---|
| Agent | A chat connected to a model that makes and runs Cards with tools derived from the RPC (the Agent in Features) |
| Helper | A child Agent the Agent uses to split up independent work |
| The thrush (Tsugumi) | The bird of the chat and the guide. Flies around the screen to explain |
Approval (approval_required) |
Asking the user to confirm when an Agent’s save widens a Card’s permissions (The Agent’s permission boundary) |
| Skill | A bundle of instructions called with $ |