Leaf envelope and result
Preview. Describes
POST /v1/runsonmainas of 2026-11-12 (harness/src/run-leaf.ts). A leaf is one unit of agent work an orchestrator dispatches (glossary). This page replaces the file-based "volume envelope" of the early specs, which no longer exists in the code.
What changed from the volume envelope​
The first leaf contract passed inputs and results as files on a shared volume (inputsRef,
resultRef, doneMarkerRef, gateRef, decisionRef, a /work PVC). The FS-free redesign
(P1 spec, ADR-0020) replaced it: inputs and the
gate decision are inline in the request, the result is the response body, and a copy is stored
in Redis for polling. The harness does no filesystem I/O of its own.
Nothing checks for the old fields by name. An envelope without the inline fields (the old file-ref shape
has no item, problemStatement or prompt) is rejected with 400 envelope_invalid; an envelope that has
the old fields plus a valid inline shape is accepted and the old fields are ignored. A leaf's tools
still run in a sandbox with its own filesystem, and workspaceRef is a path inside that sandbox.
Request​
POST /v1/runs with a JSON envelope of one of three kinds, chosen by kind:
| Kind | Required fields | Behavior |
|---|---|---|
Verdict (kind absent or converge) | sessionId, item | Produces a structured verdict with a submit_verdict tool; resumable; supports a human gate |
solve | sessionId, problemStatement, repoUrl, ref | Works a problem in a fresh per-session workspace and returns a patch. Needs a sandbox pool |
prompt | sessionId, prompt | Leases a sandbox and runs the prompt as a turn on the session |
item is {item_id: string, file: string, pattern: string, require_approval?: boolean}.
Optional fields on any envelope: decision, model, provider, workspaceRef, repoUrl, ref,
maxTurns (verdict leaf only), tenant, configRef, problemStatement, prompt, env_key.
configRef names a config bundle (sha256: plus 64 lowercase hex
characters). It applies to prompt and solve leaves only; a verdict leaf never reads it and runs without the
bundle's skills, with no warning. It must be in the envelope: /runs does not use the session's bound
bundle (unlike /turn). At request time only a non-blank string is required (null counts as absent; a
blank or non-string value is 400 configRef_invalid); the digest format is checked when the bundle is
resolved, and a bad digest comes back as a 200 failed result with reason error, not a 400.
tenant is accepted only from unauthenticated callers: an authenticated /runs that sends it gets
400 tenant_not_allowed.
workloadId runs a synchronous prompt on that workload's frozen context (see
Context Service and workloads). An async run that names one, and any
run while workloads are off, returns 501 workload_runs_unavailable, unless the deployment requires
a token and none was sent (401 token_required first). contextWritable: true gives that run its
own writable copy of the context, discarded when the run ends. It must be a boolean (400
context_writable_invalid), and true needs a workloadId (400
context_writable_requires_workload); false is ignored.
sessionId is mapped to a safe internal id: a tenant/ prefix if any, every character outside
[A-Za-z0-9._-] becomes -, and leading and trailing non-alphanumerics are trimmed.
Result​
The 200 body is a LeafResult:
status | Other fields |
|---|---|
done | verdict: {item_id, verdict: "FLAGGED" or "CLEAR", reason} |
paused | gateId (number), gate: {summary, proposed_action} |
aborted | |
solved | patch, usage? |
responded | text, usage? |
failed | reason: no_verdict, invalid_verdict, bad_inputs, error, saturated or owner_lost (reaper-written only, #558); message? |
A failed result is returned as HTTP 200 on the sync path, not as a 4xx or 5xx, except saturated,
which becomes 503 with Retry-After. Every non-saturated outcome is stored at leaf:result:<id> with
a TTL of LEAF_RESULT_TTL_SECONDS (default 604800, seven days); the last write wins. GET /runs/status?sessionId=
returns a reduced view of that record, not the whole result: no message on failed (the stored
record keeps none either), no usage on solved and responded, and paused repeats gateId at the top
level and inside gate. A session with no record yet, or none at all, answers 200 {status: "queued"},
and the lookup takes tenant as a query parameter (unauthenticated callers only).
Idempotency and resume​
- Verdict leaf: resumable. If a session exists, it is reopened from its checkpoint; if a verdict was
already recorded it is returned without running the agent or leasing a sandbox. To retry, re-invoke
the same
sessionId. - Prompt leaf: there is no fast path; re-invoking runs the prompt again as a new turn on the existing session.
- Solve leaf: reopens an existing session but re-prompts; the workspace is created fresh and cleaned up afterwards.
The human gate​
A verdict leaf whose item.require_approval is true is told to call request_approval once and stop.
submit_verdict is withheld until a decision exists. The run then returns
{status: "paused", gateId, gate: {summary, proposed_action}} (also stored, and shown by
/runs/status in its reduced view). There is no awaiting_approval status in the current code.
To resolve it, re-POST the same envelope to /v1/runs with an inline decision:
{
"sessionId": "run-1/item-1",
"item": { "item_id": "a", "file": "x.py", "pattern": "p", "require_approval": true },
"decision": { "gateId": 0, "action": "approve", "feedback": "ok" }
}
| Field | Notes |
|---|---|
gateId | Non-negative integer, 0-based; must match the pending gate |
action | approve, reject or abort |
feedback | Optional string |
- A decision that is invalid is ignored, and the run stays paused. A decision for the wrong
gateIdalso leaves it paused; repeating an already-recorded decision appends nothing. abortreturns{status: "aborted"}.approveorrejectcontinues the agent with a prompt that carries the decision.- There is no harness-side timeout while paused; the result record's TTL is the only bound.
- Gates exist only on the verdict leaf, not on solve or prompt leaves and not on
/turn.
Async and scheduled dispatch​
async: true on this route and the cron on-ramp were both removed with the Knative/KEDA path
(ADR-0041): a /runs request with async: true returns 400 async_removed, and the field is gone
from the envelope type. Async dispatch has a replacement on the control plane, not here:
POST /v1/sessions/{id}/turns with async: true (ADR-0047), authenticated and owner-scoped, which
records a turn and queues its id. The queue carries a turn id and nothing else — no envelope, no
credential, no bearer token — and the worker rebuilds the envelope from the record at dequeue. The
drain loop that does so runs on P6 today, opt-in behind SH_ASYNC_DRAIN and
MOCA_TENANCY=single; see dispatch archetypes. Its result is
written per turn and read back with GET /v1/sessions/{id}/turns/{turnId}, so /runs/status — this
route's own status endpoint — never reports an async turn: it answers queued forever, or returns
the session's last synchronous result as if it were the answer. Cron still has no P6 equivalent
(#536).
Spec drift​
- The human-gate design still describes the file-based
design (
decisionRef,gateRef, anawaiting_approvalmarker). This page follows the code. - The P1 spec lists failure reasons without
saturated, and statuses withoutsolvedandresponded. - Prompt-leaf session ids are inconsistent. The turn is opened under the raw
sessionId(no tenant prefix, no sanitising), while the sandbox lease, the promoted config and the result record use the sanitized id (harness/src/run-leaf.ts,server.ts). Verdict and solve leaves use the sanitized id throughout. Treat the two as different keys for a prompt leaf until the code is aligned.