The dispatch lifecycle
The other pages in this group describe the orchestrator and the workers as standing parts. This page threads them together: it follows one session from the call that starts it to the result that ends it, naming each mechanism as the session reaches it. It is the spine that connects the two planes.
Start: one transport, one workflow
Section titled “Start: one transport, one workflow”A session begins with a StartSession call. It can arrive three ways — a gRPC SDK
client, a REST route, or the desktop console (which itself calls the gRPC surface) —
and all of them converge on the same transport-blind workflow. The transport’s only
job is to authenticate the caller into a TenantContext and translate its wire format;
from there a REST session and a gRPC session are the same session, running identical
substrate code. The workflow mints the session id, registers the session’s
cancellation token and settings, appends the durable SessionStarted bootstrap event
(the record a restart rehydrates from), spawns the session actor, and returns the id.
The driver can now tail the session’s events live from the start.
Compose: what the session is built from
Section titled “Compose: what the session is built from”Before any model call, the session’s shape is composed. The workflow resolves the agent’s bindings — its prompt fragments, tool selections, skills, supervisor strategy, and defaults — and the coordination loop it will run under. That loop can be named by the launch request, or locked by a published agent; the resolution precedence and the loop catalog are the Coordination loops group, and the agent’s configurable surface is the agent-configuration plane. Whatever is resolved is pinned into the durable bootstrap so a resume rebuilds the exact same agent, never whatever the registries hold later.
Plan: in-process decomposition
Section titled “Plan: in-process decomposition”The coordinator’s first phase is PLAN. The planner is the one tier that never
goes to a worker — it runs in-process in the orchestrator, reads the goal, and emits a
structured plan of sub-tasks. Each planner call runs through the two-plane
context plane: compaction bounds the planner’s accumulated
history, then a pure prompt transformer compiles the actual call, and both decisions
are recorded on the log so a replay reconstructs the exact prompt.
Dispatch: what rides the envelope
Section titled “Dispatch: what rides the envelope”For each sub-task the coordinator spawns a child agent and dispatches it. The dispatch envelope carries everything a worker needs to run that agent in isolation: the agent’s full state (its tier, goal, budget, tools, composed prompt, and memory bindings), a deadline, any affinity ticket, the session id, the seed working memory, and — only when the worker hop is proven secure — the tool credentials the orchestrator resolved for this tenant. Tenant scope rides implicitly on the agent’s opaque reference; there is no tenant field a caller could forge. The secret hop is transient and off the log by design — its contract is the credential plane.
Stream: events flow back onto the log
Section titled “Stream: events flow back onto the log”The worker runs its tool-use loop and streams events back over the dial-in connection as it goes: streaming chunks, cost events, tool results, working-memory checkpoints, and lifecycle transitions. The orchestrator appends each to the event log, and the driver’s live tail is reading that same log — over gRPC streaming or REST server-sent events. Nothing observable bypasses the log; a signal that isn’t on it does not exist for audit or replay. See The event log.
Verify: gating the result
Section titled “Verify: gating the result”When a sub-task wave completes, the coordinator runs VERIFY. Validator-tier agents
grade the workers’ outputs — against predicates, a rubric, or an LLM judge, depending
on the loop — and their verdicts are aggregated. A validator’s target is a peer
worker’s output, so validators run after the workers they check, separated by a hard
barrier. A satisfied result proceeds to synthesis; an unsatisfied one re-enters PLAN
with the failure feedback so the next plan addresses what fell short. The
VMAO loop describes this generate-critic structure in full.
Fail: the supervision decision
Section titled “Fail: the supervision decision”A dispatch that fails does not just retry in place. Its failure is typed, and the agent’s supervisor strategy turns that type into a bounded decision — retry with backoff, retry with revision, re-acquire a worker, pause for a human, or escalate up the parent chain. A worker that goes silent mid-dispatch is detected by missed heartbeats and re-acquired; a journaled side-effecting call is replayed rather than re-run. The full vocabulary lives on the orchestrator page.
Synthesize: the terminal outcome
Section titled “Synthesize: the terminal outcome”When verification is satisfied and no replan is pending, the coordinator runs its final
phase: it composes the sub-task outputs into one session-level result and appends a
terminal Done outcome. Replanning is bounded by distinct caps — one on replan
iterations, one on coverage iterations — each with its own failure signal, so an
operator can tell why a session stopped rather than looping forever. The terminal
event closes the session; the driver’s wait-for-completion returns, and the whole run
remains reconstructible from the log it left behind.
Where this shows up
Section titled “Where this shows up”- Operate: The operator console shows this lifecycle live — planning, dispatches, verification, and terminal state.
- Build: The Python SDK starts a session and iterates its event tail; REST & SSE is the same flow over HTTP.
- Reference: the orchestrator workflow and coordinator modules under Reference.