Status: Stable.
Normative home:
selfHostedRunner,subWorkflow,loopback,multiAgent,agents.
Why this exists
A step can run on a user's machine, in a child run, or under a supervisor loop; the host stays the orchestration, persistence and replay authority.
selfHostedRunner
A runner is a user-operated process that dials out, holds credentials the host cannot reach, receives dispatch frames over SSE on host-defined paths, and POSTs results of single model or tool steps. A host MUST NOT advertise selfHostedRunner unless it accepts registrations, routes matching dispatch and delivers results.
- Records. A registration (
schemas/v2/self-hosted-runner-registration.schema.json) MUST NOT appear in discovery.dispatchKindslistsmodel,toolor both. - Subject isolation. A host MUST NOT route a step to a runner its run's subject does not own, and MUST match on subject before capability.
- Credentials. A runner credential MUST NOT transit the host or appear in any frame, event, result, debug bundle or log. The runner bearer MUST NOT be a provider credential.
- Untrusted output. Runner output re-entering an agent loop MUST be fenced as untrusted.
- At most once. A frame's
seqis a per-runner cursor, resumed byLast-Event-ID, and MUST NOT be conflated with eventsequence. The host MUST drop, not re-dispatch, a{runId, stepId}already persisted; the runner MUST answer under the pair it received. - Liveness. Dispatch to a departed runner MUST fail with retriable
runner_unavailable, never hang. - Replay and fork. Replay MUST NOT re-dispatch. A fork MUST NOT pin later dispatch to the original
runnerId.
subWorkflow
core.subWorkflow starts a child run of another workflow and waits for its terminal status.
workflowId. A host MUST refuse the parent run withnode_config_invalidwhen that workflow is not loaded.waitForCompletiondefaults totrue; a host MAY refusefalsewithvalidation_error.onChildFailure.fail-parent(default) fails the node and the run;absorbrecords the failure and continues.- Output.
node.completedMUST carryoutputs.childRunIdandoutputs.childStatus(completed | failed | cancelled), and MAY add fields. A child'sskippedTerminalsMUST arrive asoutputs.childSkippedTerminals;onChildFailuredoes not apply. inputMapping(childVar → parentVar) seeds the child once, at creation, after and over itsvariables[].defaultValue, which MUST seed first. An unset parent variable MUST arrive undefined, never an error ornull. A host not advertisingsubWorkflow.inputMappingMUST refuse a non-emptyinputMappingat registration withvalidation_error, naming it indetails.requiredCapability.outputMapping(parentVar → childVar). After the child completes, the host MUST copy each mapped variable into the parent, without throwing on or copying an undefined one.propagateCancellation(defaulttrue) cancels the child with its parent.- Parent link. Where
getRunAncestryis served, the child'sparentMUST be the parent run, withcause: "core.subWorkflow".parentRunIdis fork lineage, not this link.
loopback
A loopback edge runs from an approval gate back to an ancestor of it; a refine resolution re-runs that region and asks the gate again under a new key (workflow-definition.schema.json $defs/EdgeLoopback).
- Admission. A host advertising
loopbackMUST refuse a definition whose loopback breaks the region rules there, or whosemaxIterationsexceeds its advertisedloopback.maxIterations. A host that does not advertise it MUST NOT run a loopback edge as a plain cycle. - Re-arm. The gate's
node.completedMUST carry theloopbackmarker, and replay and fork MUST re-arm from it. - History. The
historyInputport MUST receive the round history rebuilt from the log. An entry whose JCS size exceedsloopback.maxHistoryEntryBytescarries atruncatedmarker.
multiAgent
multiAgent.executionModel.version is cumulative: a host advertising N MUST implement levels 1 through N. Each level adds:
- the supervisor loop and worker handoff;
- confidence escalation, and memory across sub-runs;
- cross-host causation;
- replay determinism under nondeterministic models;
- stateful loop lifecycle and context budget;
- verifier turn and convergence.
At level 1, a workflow whose core.orchestrator.supervisor feeds core.dispatch runs this loop:
- Each turn records one decision as
runOrchestrator.decided.terminatecompletes the run;clarifyandescalatesuspend on aclarificationorapprovalinterrupt;next-workerdispatches each ofnextWorkerIds[]as a child run, and the next turn waits for all of them. - The loop MUST be re-entrant: replay from any iteration MUST reproduce its state.
- A worker moves
pending → dispatching → running → harvested, or endsfailedorcancelled. Each transition that occurs MUST emitcore.workflowChain.eventwhosecausationIdnames the prior transition, firstrunOrchestrator.decided. A host MUST NOT synthesize a phase it never produces. output.harvestedfires exactly when a child completes with a non-emptyoutputMapping.- A host not advertising
executionModelMUST NOT emitcore.workflowChain.event.
At level 2:
- A
next-workerorterminatedecision whoseconfidenceis below the floor (confidenceEscalationFloor, else0.5) MUST NOT execute silently. The host MUST recordcore.workflowChain.confidence-escalated, then fire aclarificationinterrupt (preferred) or anapprovalinterrupt, both before anydispatch.beganfor that decision. An absentconfidenceMUST NOT trigger escalation. - With
memoryalso advertised, a child ofcore.dispatchorcore.subWorkflowMUST keep memory scoped per(tenantId, scopeId)(host-services.md §memory). When it shares its parent's scope, its writes are visible to the parent from its completion and on later supervisor turns, and an entry'sttlMUST run from the child's write time. - The host MUST serialize sibling children's writes to the shared scope per parent run. A host advertising
crossChildMemoryConcurrency: "advisory"is exempt, and SHOULD document last-write-wins. - The host MUST persist memory snapshots by log index: before
fromSeq, a fork's memory reads MUST return the source run's memory as offromSeq, or the fork is refused (replay.md).
At level 3, which requires crossHostCausation:
- An event whose
causationIdnames an event on another host MUST carrycausationHostId, equal to that host'scrossHostCausation.hostId; a same-host one MUST NOT. - The host MUST propagate the run's trace context into every outbound MCP request and A2A message, and adopt an inbound one, per interop.md.
- Under
ancestryEndpointSupportedthe host MUST servegetRunAncestry(runs.md); otherwise it returns404and clients walkcausationHostId.
At level 4, every LLM-calling node MUST meet replay.md's invocation key, refusal-divergence and observable-result rules.
At level 5:
- Every
runOrchestrator.decidedMUST carryiteration, 1-based and incremented by exactly 1 per turn;maxLoopIterationsbounds it (runs.md). - Turn i's inputs MUST be reproducible on replay: memory as of its log index, the workspace snapshot when
workspaceis advertised, and the log tail bounded bytranscriptWindow. A turn's writes MUST become visible to turn i+1, never to turn i. - Under
statefulResume, a resumed loop MUST continue at the sameiterationwith the same snapshot lineage. A heartbeat MAY enqueue a fresh loop run and MUST NOT advance a suspended one. contextBudgetbounds that transcript in tokens, per itsschemas/v2/capabilities.schema.jsondescriptions andcontext.summarized. A replay MUST reuse a recorded summary, never re-summarize.
At level 6, with verifier advertised:
- A critic MUST emit content-free
agent.verifiedover a prior result: anagent.decidedevent, a child run or a tool call. - Under
verifier.gating, afailMUST NOT be merged orterminateas success, and areviseSHOULD route back to an actor turn withinmaxLoopIterations. A missing verdict is not a failure. Withoutgating, verdicts are observational. - A consumer MUST NOT treat a
terminatewhosesuccessCriteriahas amet: falseentry as goal-satisfied.
agents
agents and each of its facets are optional; a client MUST tolerate their absence. A host advertising agents serves RunSnapshot.agent and runOrchestrator, emits the agent.* family, and suspends a low-confidence agent.decided. Each facet's rules are its description in spec/v2/facets/agents.schema.json, with the records it names under schemas/v2/:
| Facets | Records |
|---|---|
profile, modelClasses, orchestratorPattern, orchestrator, dispatch, dispatchMapping, fanOut, reasoning, subRunAttestation | dispatch-config |
manifestRuntime, liveRuntime | agent-manifest, agent-inventory-response |
memoryBackends, memoryConsolidation, commitments | memory-entry (host-services.md) |
evalSuite | agent-eval-suite, eval-summary |
deployment | agent-deployment, agent-deployment-transition, agent-ref |
roster, orgChart | agent-roster-entry, agent-org-chart |
proposals, goals | proposal, goal |
A host MUST NOT advertise liveRuntime or roster without manifestRuntime, orgChart without roster, or memoryConsolidation without long-term in memoryBackends. roster.installScope MUST equal manifestRuntime.installScope; orgChart.installScope SHOULD equal it.
Sources: RFCs 0002, 0007, 0022, 0037, 0039, 0040, 0041, 0061, 0068, 0077, 0086, 0087, 0090, 0111, 0122, 0228.