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_model.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 evaluates transitions, dispatches workers, relays checkpoints upward 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_checkpointchoosing the next activity

Dispatch mechanics

Each session is identified by a 6-character base32 session_index, deterministically derived from the planning-folder slug. 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 server snapshots the parent's session under the child's parentSession field for trace correlation, 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. Fresh workers per activity keep task context disposable; 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 when no activities remain, 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 the checkpoint model. Session state and the session.json file are covered in state management.