Thin durable turn loop that wires session-manager, context-manager, and llm-router into an agent loop; spawns sub-agents as child sessions.
iiiverifiedexact versions are immutable; binary and bundle artifacts are digest-pinned.
Internal control-plane: edit a still-parked queued message in place by entry_id, preserving its queue position.
The queued row to edit (its client-visible `entry_id`).
The replacement user message text.
False when no still-parked row matched — already drained or unknown.
Internal control-plane: grant a session access to an additional filesystem root.
Internal control-plane: list additional filesystem roots granted to a session.
Internal control-plane: the default working-directory root new sessions are scoped to.
Effective per-session boundary for shell/coder calls. `workspace` when the filesystem approval hook can widen it, otherwise `configured_roots`.
Working-directory root stamped onto the first turn of a session whose send carries no explicit `fs_scope.root`; `null` when defaulting is disabled (`default_filesystem_root: "off"`) or the cwd is unreadable.
Internal control-plane: revoke a session's access to an additional filesystem root.
Internal: settle a pending call's result (or release a held call) and resume the parked turn.
`deliver` (default) supplies the result; `execute` releases a hook-held call through the remaining trigger pipeline.
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
execute only: one-shot additional roots trusted by the caller and unioned with the session's durable filesystem grants.
False when the call is unknown, already done, or (execute) not held.
True when this resolve re-enqueued the turn.
Internal: invoke one iii function (unwrapped from agent_trigger), enforce the dispatch policy, and capture the normalised result — or report it pending.
The iii function to invoke (already unwrapped from `agent_trigger`).
function_call id, echoed into the result.
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
Aggregate durable model usage, function outcomes, and available trace/span observability for the session tree `root_session_id` belongs to (`session_id` is accepted as an alias, and a sub-agent id is resolved to its root). `complete` is true only after every session in the durable tree has reached a terminal turn.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
The session's latest per-generation context snapshot (categories, budget, usage) — absent for sessions that have not generated since snapshots landed.
Where the request's tokens sit. Categories are assembly-time estimates; `hook_guidance` is the measured growth after assembly (pre-generate hook appends and orphan-repair patches), 0 when the request left assembly unchanged.
Estimated tokens of the assembled window's messages, by role.
Provider framing plus response_format / provider_options fields.
Selected skill bodies contained in the system prompt.
Final assembled system prompt excluding tokens attributed to `skills`: identity, per-step aids, and any compaction summary section.
Function schemas exposed to the model.
Output allocation `usable` was derived against.
Which estimator produced the numbers (`heuristic` until the context-manager resolves a real tokenizer). Absent when the context-manager predates the breakdown response.
Running cost of the whole session in USD, accumulated across every generation step. `usage.cost_usd` is one step's bill — on providers with steep cache discounts the per-step number swings two orders of magnitude, so a chip showing it alone reads as a bouncing total.
Final request estimate: categories plus post-assembly growth.
The input budget the window was fit into.
Actual provider usage for this generation, stamped after the terminal frame; absent when the provider returned none (or the generation never completed).
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Summed over every generation that reported it. `null` means at least one generation did not report the counter (a provider that omits it, or a turn that failed before usage came back) — never a measured zero, so the key is always present and a reader can tell the two apart.
Trace/span aggregates when the engine's in-memory observability exporter is available. Usage metrics remain available when it is not.
Elapsed window from the session's first observed span to its last.
Elapsed window from the first observed span to the last observed span.
Distinct traces across the root session and all descendants.
Internal: refresh the cached function-registry snapshot when functions are registered/unregistered (driven by the engine::functions-available trigger).
Engine event tag (advisory; the handler re-fetches the full list).
Internal: drop a deleted session's ephemeral subscriptions. Not called directly.
Internal: refresh the cached model-invocable skill catalog.
Internal control-plane: remove a project directory from the durable catalog.
Internal control-plane: list the operator's durable project catalog.
Internal control-plane: remember, touch, or rename a project directory.
A custom display name. Omit to keep the current name (or use the folder name for a new project); pass blank to reset to the folder name.
Entry point: ensure the session, persist the incoming message, and kick off a turn; returns fast (or merges into a running turn).
Webhook dedupe: a repeated key returns the original `{session_id, turn_id}` and appends nothing.
The incoming user message text.
Required on a new session unless `options.agent` supplies a model; an existing session inherits its last turn's model when omitted.
Directory agent profile id (`directory::agents::*`) replacing the built-in identity; new sessions only, refused with a prompt field.
Fail-closed dispatch policy; omitted means deny all on a new session and inherit on an existing one (`{ allow: [] }` strips explicitly).
Hard USD budget for the complete root-and-subagent session tree. Every model used by the tree must advertise catalog pricing.
Per-generation output-token ceiling forwarded to the router.
Hard input-plus-output token budget for the complete root-and-subagent session tree.
Per-turn override of the validation-retry budget.
Tracing passthrough.
The turn's deliverable; default `{ type: "text" }`.
Provider-native per-call options, namespaced by provider id.
Exact skill ids advertised to the model; omitted or empty means all on a new session (existing: omitted inherits, empty resets).
How `system_prompt` combines with the built-in prompt; omitting both prompt fields on an existing session inherits the prior prompt.
Applied when this send creates/ensures the session.
Omit to create a new session.
True when `idempotency_key` matched an earlier send.
True when folded into an in-flight turn (steering).
True when the message was queued while a step was streaming; it lands in the transcript when the stream ends.
Read the durable root-and-descendant session tree for one harness run.
Spawn a sub-agent in a child session (never a trigger target) and return { child_session_id, child_turn_id } immediately; the child's outcome reaches you only through whatever destination its task names. Check `harness::status` for child health; children are leaves unless options.orchestrator is true.
Directory agent profile id (`directory::agents::*`) supplying the child's prompt, skills, model, and display; refused with `options.system_prompt`. Omitted, an in-turn spawn continues the parent turn's profile (name `options.system_prompt` for a child that needs a different identity).
Display-only name/icon/color for the child session; never affects ids, policy, or routing.
Short functional name such as `Frontend`, 1-48 characters after trimming.
Absolute filesystem root for the child turn; omit to inherit the parent's.
Dispatch policy for the child, intersected with the parent's (narrow, never escalate).
Fan-out guard for the child's own spawns.
Inherits the parent's ceiling unless explicitly narrowed/overridden.
Turn cap for the child, capped at the parent's remaining budget; omit unless required (small values strand the child).
Override of the child's validation-retry budget.
Let the child spawn, send, and register triggers (still capped by the parent's policy); default false makes it a leaf.
The child's deliverable: text / json / json+schema.
Exact skill ids advertised to the child; omitted or empty means all (a reused child inherits when omitted).
How `system_prompt` combines with the built-in prompt.
Display-only parent for the console tree when there is no live parent turn; grants no policy inheritance.
Session id to spawn into, created if absent; an existing id may be reused only inside the caller's own tree.
The child's self-contained goal, its opening user message; name every required resource selector literally (the child cannot infer them).
The named session already existed and was reused — its prior transcript and parent linkage were retained (only possible with an explicit `session_id`).
Read a session's current turn. Returns a lean summary by default; pass verbose: true for the full runtime report and untruncated result.
Include the full runtime report and unmodified result.
WHAT the session is parked on, when `expects_wake`: each armed wake's watch and deadline, so "parked 12m on state operation_meta/status — never written" is readable from the outside instead of the session just looking quietly done.
The registered trigger's type/config, read from the canonicalised registration request. Absent on records that predate it.
The last generate step's context accounting (budget, categories, provider-exact usage once it lands) — what a UI meter should show instead of re-estimating the transcript. Verbose only; absent before the first generate.
Where the request's tokens sit. Categories are assembly-time estimates; `hook_guidance` is the measured growth after assembly (pre-generate hook appends and orphan-repair patches), 0 when the request left assembly unchanged.
Estimated tokens of the assembled window's messages, by role.
Provider framing plus response_format / provider_options fields.
Selected skill bodies contained in the system prompt.
Final assembled system prompt excluding tokens attributed to `skills`: identity, per-step aids, and any compaction summary section.
Function schemas exposed to the model.
Output allocation `usable` was derived against.
Which estimator produced the numbers (`heuristic` until the context-manager resolves a real tokenizer). Absent when the context-manager predates the breakdown response.
Running cost of the whole session in USD, accumulated across every generation step. `usage.cost_usd` is one step's bill — on providers with steep cache discounts the per-step number swings two orders of magnitude, so a chip showing it alone reads as a bouncing total.
Final request estimate: categories plus post-assembly growth.
The input budget the window was fit into.
Actual provider usage for this generation, stamped after the terminal frame; absent when the provider returned none (or the generation never completed).
The session owns an armed wake (a one-shot notify subscription): a completed turn here is NOT the run's outcome — a later turn in this session carries it. Mirrors the `terminal` flag on `harness::turn-completed` (`expects_wake == !terminal`). Pollers (e.g. workflow reconcile) must treat `completed && expects_wake` as still running.
Messages queued while a step streams, in arrival order; they land in the transcript when the stream ends.
Deterministic transcript entry id the drain appends under, so a redelivered drain is a no-op.
The canonical transcript message union. Untagged: the single-variant role tags disambiguate deserialization (assistant/function_result/custom are tried before user so their required fields gate the match).
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.
The coarse, harness-internal turn lifecycle (harness.md § API Reference). Finer-grained than the session's `status`, which the loop derives from it.
Why a `completed` turn stopped when the model did not end it itself (`max_turns`). Present in the lean report too: a poller that reads `completed` with no error must still be able to tell an exhausted budget from a finished task.
Request cancellation of an in-flight turn (cascades to spawned children).
Omit to stop the current turn.
Internal cron sweep: resolve pending function calls past their timeout so a parked turn never wedges. Not called directly.
Number of expired pending calls resolved this sweep.
Preview the system prompt layers a session will use without making a model request.
Return only the built-in default layer, without session, runtime, registry, or hook layers.
Internal control-plane: remove trigger bindings owned by a root harness session tree.
Internal fire handler for a harness-registered trigger binding: evaluates the binding's conditions, projects the event into the target's payload, and dispatches it (a wake into the owner session, or a plain function call). Never called directly — register bindings with engine::register_trigger.
Whether the target was dispatched this fire.
Which gate or condition stopped it. Present iff `!delivered`.
Why. Present iff `!delivered`.
List the trigger bindings a session owns: subscription id, trigger type/config, target (absent = notifies the owner), label, conditions, lifecycle, and fire count. In-turn calls may omit `session_id`.
Owner session whose bindings to list; in-turn calls may omit it (the calling session is injected).
Human-readable event text declared as `metadata.action`.
The function a fire calls. Absent for a wake — the fire notifies the owner session.
The engine's own trigger id (absent only in the brief window before the engine acknowledged the registration).
Tear down one trigger binding by subscription id (engine trigger and durable record); a still-armed wake notifies its parked owner. `session_id` must name the owner; in-turn calls may omit it.
The binding's owner session; in-turn calls may omit it (the calling session is injected).
The subscription to remove (`id` is accepted as an alias).
False when no record existed (already retired) — honest, not an error.
Internal durable loop step (enqueued onto the harness-turn queue); not called directly.
Sub-agent depth carried from the turn record (0 = top-level).
Preview carried from the turn record so the step can stamp the `iii.tag.message` baggage before any state read.
True when a redelivered/stale step was acked and dropped.
The coarse, harness-internal turn lifecycle (harness.md § API Reference). Finer-grained than the session's `status`, which the loop derives from it.
Serve the harness worker's injected console UI assets (content function for its console:script / console:style triggers).
The asset path from the trigger config (e.g. `state/page.js`).
The asset source, verbatim.
MIME type the console should serve the asset with.
Internal control-plane: remove a still-parked queued message by entry_id (the console's edit-queued path).
The queued row's transcript entry id, as surfaced by `harness::status` → `queued[].entry_id`. Stable and client-visible (the internal row id is not), so removals target it.
False when no still-parked row matched — already drained or unknown.
Synchronous hook: after the final assistant message update. Observe only.
pre/post_trigger only: target function_id globs to consult on.
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
post_turn only: template mode — send THIS argument object to the bound function instead of the hook envelope, with the turn's parsed result injected at `result_into`. Lets a plain composition function (`fp::pipe`) validate turns without speaking the hook contract; its receipt is read as the verdict (`valid`, or `short_circuited`).
Chain order: ascending, ties broken by function_id (default 0).
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
post_turn only: custom corrective prompt sent VERBATIM when this validator denies (replaces the generic "result was not accepted" wrapper). Placeholders: `{value}` = the validator's measured value (fp::pipe receipt `value_preview`), `{reason}` = the deny reason. Validator ERRORS keep the generic text — a task-shaped prompt must not mask a broken validator.
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
Per-invocation timeout (default 5000ms).
Synchronous hook: after the target returns, before the result is appended. May rewrite content/details/is_error.
pre/post_trigger only: target function_id globs to consult on.
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
post_turn only: template mode — send THIS argument object to the bound function instead of the hook envelope, with the turn's parsed result injected at `result_into`. Lets a plain composition function (`fp::pipe`) validate turns without speaking the hook contract; its receipt is read as the verdict (`valid`, or `short_circuited`).
Chain order: ascending, ties broken by function_id (default 0).
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
post_turn only: custom corrective prompt sent VERBATIM when this validator denies (replaces the generic "result was not accepted" wrapper). Placeholders: `{value}` = the validator's measured value (fp::pipe receipt `value_preview`), `{reason}` = the deny reason. Validator ERRORS keep the generic text — a task-shaped prompt must not mask a broken validator.
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
Per-invocation timeout (default 5000ms).
Synchronous hook: at finalize, after the output contract validated the result, before the turn completes. Deny re-prompts the turn (bounded by max_validation_retries). Config `sessions` globs scope it; config `payload`+`result_into` bind a plain composition function (fp::pipe) as the validator.
pre/post_trigger only: target function_id globs to consult on.
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
post_turn only: template mode — send THIS argument object to the bound function instead of the hook envelope, with the turn's parsed result injected at `result_into`. Lets a plain composition function (`fp::pipe`) validate turns without speaking the hook contract; its receipt is read as the verdict (`valid`, or `short_circuited`).
Chain order: ascending, ties broken by function_id (default 0).
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
post_turn only: custom corrective prompt sent VERBATIM when this validator denies (replaces the generic "result was not accepted" wrapper). Placeholders: `{value}` = the validator's measured value (fp::pipe receipt `value_preview`), `{reason}` = the deny reason. Validator ERRORS keep the generic text — a task-shaped prompt must not mask a broken validator.
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
Per-invocation timeout (default 5000ms).
Synchronous hook: after context assembly, before generation. May extend the system prompt, append messages, or veto. Static-only bindings may declare their exact contribution as metadata.inject_prompt.
pre/post_trigger only: target function_id globs to consult on.
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
post_turn only: template mode — send THIS argument object to the bound function instead of the hook envelope, with the turn's parsed result injected at `result_into`. Lets a plain composition function (`fp::pipe`) validate turns without speaking the hook contract; its receipt is read as the verdict (`valid`, or `short_circuited`).
Chain order: ascending, ties broken by function_id (default 0).
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
post_turn only: custom corrective prompt sent VERBATIM when this validator denies (replaces the generic "result was not accepted" wrapper). Placeholders: `{value}` = the validator's measured value (fp::pipe receipt `value_preview`), `{reason}` = the deny reason. Validator ERRORS keep the generic text — a task-shaped prompt must not mask a broken validator.
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
Per-invocation timeout (default 5000ms).
Synchronous hook: after the allow/deny policy passes, before the target is invoked. May deny, hold, or rewrite arguments.
pre/post_trigger only: target function_id globs to consult on.
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
post_turn only: template mode — send THIS argument object to the bound function instead of the hook envelope, with the turn's parsed result injected at `result_into`. Lets a plain composition function (`fp::pipe`) validate turns without speaking the hook contract; its receipt is read as the verdict (`valid`, or `short_circuited`).
Chain order: ascending, ties broken by function_id (default 0).
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
post_turn only: custom corrective prompt sent VERBATIM when this validator denies (replaces the generic "result was not accepted" wrapper). Placeholders: `{value}` = the validator's measured value (fp::pipe receipt `value_preview`), `{reason}` = the deny reason. Validator ERRORS keep the generic text — a task-shaped prompt must not mask a broken validator.
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
Per-invocation timeout (default 5000ms).
Synchronous hook: first step of a turn, before any model spend. May veto.
pre/post_trigger only: target function_id globs to consult on.
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
post_turn only: template mode — send THIS argument object to the bound function instead of the hook envelope, with the turn's parsed result injected at `result_into`. Lets a plain composition function (`fp::pipe`) validate turns without speaking the hook contract; its receipt is read as the verdict (`valid`, or `short_circuited`).
Chain order: ascending, ties broken by function_id (default 0).
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
post_turn only: custom corrective prompt sent VERBATIM when this validator denies (replaces the generic "result was not accepted" wrapper). Placeholders: `{value}` = the validator's measured value (fp::pipe receipt `value_preview`), `{reason}` = the deny reason. Validator ERRORS keep the generic text — a task-shaped prompt must not mask a broken validator.
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
Per-invocation timeout (default 5000ms).
A message parked in a session's server-side queue while its turn streams.
Only deliver sub-agent events whose parent is this session.
Only deliver events for this session.
The harness completed boot and can accept turns.
A session's trigger-binding set or fire count changed — refetch harness::triggers::list.
Only deliver sub-agent events whose parent is this session.
Only deliver events for this session.
A harness turn reached a terminal status (completed/cancelled/failed).
Only deliver sub-agent events whose parent is this session.
Only deliver events for this session.
A harness turn began executing (first loop step).
Only deliver sub-agent events whose parent is this session.
Only deliver events for this session.
One-shot deadline: fires exactly once at `at` (epoch ms). Register with { "in_ms": <relative ms> } — resolved to an absolute `at` at registration — or { "at": <epoch ms> }. The natural second leg of any armed wake or fan-in gate: 'wake me when X happens, or tell me at T that it did not'. Fires once and retires; for recurrence use `cron`.
