Workflow Server

Hierarchical dispatch

Workflows run through three agent layers — meta orchestrator, workflow orchestrator, and activity workers — kept apart by what they must not share: user conversation, workflow state, and task context.

Layer key: L0 = user-facing meta orchestrator · L1 = workflow orchestrator (state owner) · L2 = activity worker (task executor).

Canonical source: docs/dispatch.md.

The three orchestration layers Level zero, the meta orchestrator, is the user-facing agent. It dispatches level one, the workflow orchestrator, creating a child session with a new session index. The workflow orchestrator dispatches level two, an activity worker, which shares the orchestrator's session index. All three layers call the workflow server. L0 · Meta orchestrator — user-facing discovers workflows, presents checkpoints to you, never does domain work L1 · Workflow orchestrator — background, persistent relays exits, dispatches workers, relays checkpoints up L2 · Activity worker — background, ephemeral executes one activity's steps with domain tools, yields at checkpoints Workflow Server one canonical session.json per session_index dispatch child session — new session_index spawn worker — same session_index
The three orchestration layers. Dispatching a workflow (L0 → L1) creates a child session with its own session_index; dispatching a worker (L1 → L2) shares the orchestrator's index, so both read the same canonical session.json on the server. All layers talk to the same server.

Responsibilities per layer

LayerLifetimeKey toolsNever does
L0 Meta orchestratorthe conversationdiscover, list_workflows, start_session, present_checkpoint, respond_checkpoint, get_workflow_statusdomain work; detailed state tracking
L1 Workflow orchestratorone workflow runget_workflow, next_activity, get_workflow_status, dispatch_childprompting the user directly
L2 Activity workerone activityget_activity, get_technique, get_resource, yield_checkpoint, resume_checkpointpresenting checkpoints; advancing the session

Dispatch mechanics

Each session is identified by a 6-character base32 session_index, derived deterministically from the planning folder's path under the server's signing key. Agents pass the index — never a token — on every authenticated call; the canonical state lives in the server-owned session.json.

The two hand-offs differ in one important way. Starting a workflow (L0 → L1) creates a child session: the child's session is embedded in the parent's under triggeredWorkflows, placed by its position in the file, and the child gets its own index. Spawning a worker (L1 → L2) shares the session: the worker uses the orchestrator's index directly, so both agents see a single canonical state. A worker carries a bounded run of activities and is then replaced, so task context stays short-lived without a fresh context being established for every activity; embedded child sessions keep the whole work package in one resumable session.json despite the layering. The actual spawning uses whatever sub-agent mechanism the host provides (Cursor's Task tool, for example); paused sub-agents are woken with the host's resume primitive.

The meta orchestrator can poll a dispatched workflow with get_workflow_status: blocked when a checkpoint is active, completed or aborted once the session has ended, active otherwise.

Inline fallback

Hosts without background sub-agents run the same model inline: a single agent adopts each persona in turn within one conversation. The server's enforcement — checkpoint gates, manifests, traces — works identically; only the persona-switching mechanism changes. Portability across MCP clients mattered more than mandating a particular execution topology.

Checkpoints bubble up through these same layers — see checkpoints. Session state and the session.json file are covered in state.