-
Notifications
You must be signed in to change notification settings - Fork 0
Concepts
Five terms cover everything the rest of these docs say.
One unit of work: a real child session with its own agent, context window, and tools. A node declares which agent runs it (worker_type), its prompt (inline text or a template id), what it depends on, and optionally a timeout, a retry budget, and a structured-output contract.
Two things a node is not: it is not a function call (it can use every tool the main agent can), and it is not a prompt fragment (it never shares a context window with its siblings — that isolation is the point).
The set of nodes whose dependencies are all satisfied. A wave runs in parallel up to the concurrency limit (max_concurrency, default 5). When a wave completes, the next one admits. A 100-node fan-out with one dependency each does not create 100 sessions at once — sessions materialize only when a concurrency permit is held.
A node whose job is judgment rather than production: review, verification, arbitration. Gates emit verdicts (ACCEPT / REVISE / REJECT / BLOCKED), and downstream nodes can be conditioned on the verdict. The disposal contract says the parent agent must act on a non-ACCEPT verdict in the same wake — extend, replan, or stop with reasons. Summarizing the verdict and ending the turn counts as an orchestration failure.
Graphs get rewritten. When the parent agent replaces a failed segment, the replaced nodes are marked superseded and the workflow's revision counter bumps. Every view — status output, HTTP API, TUI inspector, summary counts — renders the current revision only. Completed nodes and their outputs survive into the new revision untouched. Live failures on the current graph stay visible until they are actually fixed.
The durable history is not erased: superseded nodes remain queryable through the result store by node id, which is how an agent audits its own rewrites. The TUI simply has no entry to it.
The DAG runtime is per-directory, but the durable store is process-global. Every workflow row therefore carries a directory stamp, taken from the session that created it and re-read from the database on every ownership check. Sibling worktrees of one project share a project id — the stamp is what stops them adopting, waking, or spawning for each other's workflows. When a session moves directories, the stamp moves with it, in the same transaction.
With these five, the engine internals are mostly detail: how waves are scheduled, how state is persisted, and what happens when things crash.