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, Codex, Claude, or Copilot. 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 its core fields and rejects unknown fields; one harness, provider, and size apply to the whole graph.
Connection declarations name permitted secret fields; another private path supplies their values. Environment preparation is a separate run-submission setting and is not part of RuntimePlan.
RuntimePlanharness · provider · size · nodesopenai · openrouter · bedrock · gatewayanthropic · openrouter · bedrock · gatewaygithubmodel · effort · sessionScope · connectionsconnectionsDocument fields
harness | Selects the required agent program: codex, claude, or copilot. |
|---|---|
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_.-]*. |
Setup and startup
Open Environments, choose User or Org, and select a repository to create setup and startup definitions. Several environments can serve the same repository. Choose Default, Base, or a saved environment when submitting a run. Default uses the user repository default, then the organization repository default, then Base. Clearing or deleting a default allows that fallback; Base explicitly skips saved defaults. Profiles contain no environment. New runs resolve the latest selected definition. Accepted runs and resumes keep their captured copy. Direct Docker APIs accept a concrete environment beside runtime in the submission. The CLI accepts --environment FILE with the definition's fields directly in the JSON file, without an environment wrapper. Use --no-environment to select Base; omit both flags to use Cloud's repository default. The CLI does not select saved environments by name or ID.
setup | Optional Bash script. Runs as root before source checkout or workspace restoration. |
|---|---|
startup | Optional Bash script. Runs as the workspace user in the project directory, before graph execution. |
variables | Optional mapping of non-secret names to string values, passed to hooks and agents. |
connections | Optional named connection fields made available to preparation scripts; values stay private. |
Install operating-system packages in setup. Install shared command-line tools under $ZEROSHOT_TOOLS; its bin directory is already on PATH for scripts and agents. Install repository dependencies in the workspace during startup. Scripts can invoke checked-in installation scripts after checkout. An export in a script affects only that shell; use variables for values that agents need later. Setup, startup, and agent sessions have separate home directories, so shared tools belong in $ZEROSHOT_TOOLS.
For a complete environment file and a checksum-verified Node 22 installation, use the setup and startup example. Paste its scripts into the Cloud editor or pass the file with --environment.
Each new run attempt executes setup, checks out or restores the workspace, then executes startup. Both hooks run again on resume. Startup must be idempotent with respect to existing workspace files: do not overwrite restored work. Checkpoints restore files and graph state; startup recreates any needed services. Workers and reviewers use the same tools, dependencies, services, Docker access, and workspace throughout the attempt. Checkpoints do not capture running services, Docker resources, database transactions, or agent conversations. Use application-managed exports when background services write files that need consistent recovery.
Hooks use Bash with fail-fast and pipeline failure handling. Each hook has a fifteen-minute limit within a thirty-minute preparation budget. Preparation output appears in the run log while the run shows Preparing environment. Failure or timeout ends the attempt before graph execution; it does not consume an agent's repair attempts. Stop cancels preparation and cleans up the run. Review the log, correct the environment, and submit a new run after a setup or startup failure.
Do not put secrets in scripts or variables: environments and run definitions retain them. Declare secret field names in environment.connections instead. PATH, HOME, temporary paths, and harness home directories are managed by the runtime.
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 | bedrock | gateway, size, nodes }. |
|---|---|
claude | { harness: claude, provider: anthropic | openrouter | bedrock | gateway, size, nodes }. |
copilot | { harness: copilot, provider: github, 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 are free-form provider identifiers rather than choices 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.
- Workers and reviewers share a writable workspace. Parallel branches must coordinate their writes. Git delivery must run after every agent that can modify the delivered workspace.
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.