Technical contracts / execution
RuntimePlan
RuntimePlan chooses how each GraphSpec step and verifier runs. It contains execution settings and connection declarations, never secret values.
What RuntimePlan controls
Use this reference while editing runtime.json. GraphSpec names the executable nodes and says what they do, so RuntimePlan must contain one matching binding for every step and verifier; this page explains those bindings and model choices.
A harness is the agent program, either Codex or Claude. The provider serves the model, while size selects the host's run-level resource class. Each node binding then chooses its model, effort, session behavior, and permitted connection fields.
For the built-in software-change graph, the plan binds nodes such as worker, acceptance, and code. Delivery uses a separate git_delivery binding when --pr or --ship adds it.
RuntimePlan contract
RuntimePlan is a closed mapping from executable graph node names to runtime bindings. Here, closed means RuntimePlan requires every document field and rejects unknown fields; one harness, provider, and size apply to the whole graph.
The plan can select execution behavior, but it cannot add commands, credentials, or environment values. Connection declarations name permitted fields; another private path supplies their values.
RuntimePlanharness · provider · size · nodesopenai · openrouteranthropic · openroutermodel · effort · sessionScope · connectionsconnectionsDocument fields
harness | Selects the required agent program: codex or claude. |
|---|---|
provider | Selects one required provider supported by that harness. |
size | Selects the required run-level class: small, medium, or large. |
nodes | Maps exact GraphSpec executable node names to required bindings. Keys are 1–128 bytes and match [A-Za-z_][A-Za-z0-9_.-]*. |
Harness contracts
Choose one supported harness-provider pair for the run. The host decides the concrete CPU, memory, and other resources behind the selected size class.
codex | { harness: codex, provider: openai | openrouter, size, nodes }. |
|---|---|
claude | { harness: claude, provider: anthropic | openrouter, size, nodes }. |
size | small · medium · large. The host defines concrete resources. |
Model, effort, session scope, and connection declarations remain per-node choices, even though harness, provider, and size cover the complete graph.
Node binding contracts
The kind field selects one of two binding shapes. Zeroshot rejects fields that do not belong to the selected kind.
agent
kind | Uses the required literal agent. |
|---|---|
model | Provides a required ModelId of 1–128 non-control bytes. |
effort | Optionally selects low, medium, high, xhigh, or max. |
sessionScope | Optionally selects execution or node_instance. Defaults to execution. |
connections | Optionally maps each connection key to its exact environment-name list. Defaults to empty. |
git_delivery
kind | Uses the required literal git_delivery. |
|---|---|
connections | Optionally maps each connection key to its exact environment-name list. Defaults to empty. |
git_delivery has no model, effort, or session scope. Zeroshot accepts it only for a verifier using builtin.git-delivery.pr@1 or builtin.git-delivery.merge@1. That verifier cannot have authored instructions.
The nodes map contains exactly one binding for every GraphSpec step and verifier, using the graph node name as its key. Structural and terminal nodes do not get bindings.
With the software-change template, --pr or --ship inserts the template-owned delivery binding. Custom graphs author delivery in both GraphSpec and RuntimePlan.
Model and effort
Model names come from the provider rather than from a Zeroshot catalog. Check the selected harness and provider before choosing an effort value that the pair may not support.
model | Provider-owned identifier: Zeroshot passes it unchanged to the selected harness. |
|---|---|
effort | Zeroshot accepts low, medium, high, xhigh, or max. When omitted, it remains unset. |
Zeroshot passes both values to the harness and provider. It does not validate model-effort compatibility.
Session scope
Session scope decides whether repeated dispatches share provider conversation state. It does not change GraphSpec state or data bindings.
execution | Open a fresh provider session for each dispatch, then close it. |
|---|---|
node_instance | Reuse one session for the same logical node instance, including loop revisits. |
If a reusable session is lost, Zeroshot does not silently replace it.
How Zeroshot checks the plan
- 1. IndexCollect every GraphSpec step and verifier by name.
- 2. MatchRequire exactly one binding for each executable node and no extra keys.
- 3. ValidateCheck runtime roles, binding shapes, instructions, delivery, connections, and concurrency.
- 4. NormalizeKeep the provider-owned model and optional effort in the admitted RuntimePlan.
- Agent bindings require authored GraphSpec instructions.
- A reused worker reference must keep the same executable contract and runtime role.
- The complete run may declare at most 64 distinct environment names.
- Steps and Git delivery are writers; ordinary verifiers are read-only. A writer cannot overlap another executable across parallel branches, and a map with
maxItems > 1cannot contain a writer.
Connection authority
RuntimePlan maps connection keys to permitted environment names, never values. Names match [A-Za-z_][A-Za-z0-9_]*, are at most 128 bytes, cannot appear under two keys in one binding, and each binding allows at most 64 names.
Values in the invoking process become explicit connections for that run. For a wholly omitted key, the target checks its connection store and then gives each node only the fields declared in that node's binding. RuntimePlan, profiles, and OECP never contain the values.