Harness

harness

The harness is the durable turn loop that wires session-manager, llm-router, and context-manager into an agent. A consumer stays thin: it kicks off a turn, renders the conversation from the session transcript, and reacts to turn boundaries and human-gated calls. The harness streams the assistant message into the session as it generates, so you watch the session, not the harness — there is no agent::events stream, and harness::status is a point-in-time recovery read, not a render feed.

Every invocation is a trigger (iii.trigger({ function_id, payload })); there is no separate "call" verb. Tool dispatch is deny-by-default: a send with no options.functions.allow is a plain chat loop and every model-requested call is refused until you allow globs per send. Sessions are minted by the harness (s_<uuid>) or supplied by you; a send into a running turn folds in as steering (merged: true) instead of erroring, and a repeated idempotency_key returns the original turn without appending.

A session-creating send names a model, or only a provider: the harness then starts on that provider's declared default model (default_model in router::provider::list, checked against its live catalog; a provider that reports none fails the send as before). A new session that names neither thinking_level nor provider_options also starts on the provider's default_thinking_level; an explicit level wins, and later sends into the session inherit the prior turn's as usual. thinking_level is off, minimal, low, medium, high or xhigh; off is honoured only on models whose catalog entry says supports_thinking_off: true; elsewhere the fallback is the provider's own (most send their lowest effort and warn, Kimi ignores the level).

Prerequisites: session-manager (required — transcript store and change feed) and llm-router (required — generation and the model catalog) must be present. context-manager (token budgeting and compaction) is a soft dependency — absent it, the harness sends raw history. approval-gate (the human-in-the-loop gate) is optional; without it no call is held and every allowed call runs un-gated.

When to Use

• Start or steer an agent turn and return immediately (harness::send).
• Cancel an in-flight turn (harness::stop) or read coarse turn state for recovery and guards (harness::status).
• Chain turns or react to outcomes by binding harness::turn-completed.
• Drive a turn from an arbitrary inbound event (cron tick, webhook, sensor) by translating it into a harness::send.

Boundaries

• Not a transcript feed. Render from session-manager's session::message-added / message-updated / status-changed (reconcile by revision); do not poll harness::status for content.
• Not the approvals engine. The harness ships only the gate mechanics; the policy, decision RPCs (approval::resolve), inbox (approval::list-pending), and prompt triggers live in approval-gate.
• Not a chain guard. options.max_turns bounds a single turn, not a send-completed-send loop; carry your own stop condition.
• Do not trigger the internal functions (below) — they forge call ids and turn progress, so calling them out of band corrupts the turn record.
• An in-run agent cannot start turns: send / run / turn / stop are denied to the model by policy. harness::spawn is the only turn-starter an agent calls directly, and it self-enforces depth, fan-out, and policy subsetting. The other path is event-driven: an agent binds engine::register_trigger straight to harness::spawn (see Reactive triggers), with the spawn spec in the registration metadata, and the engine spawns the sub-agent when the event fires.

Functions

Consumer-facing:

• harness::send — ensure the session, persist the incoming message, and kick off a turn; returns fast or merges into a running turn (steering).
• harness::stop — request cancellation of an in-flight turn; cascades to spawned children.
• harness::status — read the current turn state for a session; null when no turn ever ran. For recovery and guards, not rendering.
• harness::spawn — spawn a sub-agent in a child session. Model-facing (invoked through agent_trigger), not a consumer entry point.
• harness::ask — put a decision with discrete options to the user as a clickable card (1–4 questions, 2–4 options each). Model-facing (invoked through agent_trigger) and answered by the turn loop itself: the turn ends on the question and the answer arrives as the user's next message. Refused in sub-agents, structured-output turns, and for a second ask in one step.

Internal — the harness drives these; never trigger them directly: harness::turn (the durable loop step), harness::function::trigger / harness::function::resolve (dispatch and parked-call settle), harness::sweep-pending (cron expiry), and harness::on-config-change (hot-reload).

Filesystem scope

options.metadata.fs_scope.root on a send is the session's working directory; a later send that omits fs_scope keeps it. The harness stamps a trusted fs_scope { root, grants, boundary } onto every shell::* / coder::* call and strips any the model supplies. boundary decides what root means to the ide worker:

• workspace — coder::*, shell::fs::* and an exec cwd stay inside root plus the session's grants (harness::filesystem::grant).
• configured_roots — root only anchors relative paths; the worker's own roots apply. The model's prompt says so ("default directory, not an access boundary").

The filesystem_boundary config picks it: auto (the default) is workspace only while approval-gate's access watch is bound; workspace or configured_roots pins it. harness::filesystem::info reports the boundary in effect. A sub-agent spawned in a turn into a new session starts with a copy of its parent's grants; later grants to the parent do not reach it. Under workspace, an in-turn spawn's options.filesystem_root must lie inside the parent's root or grants. What an exec'd process itself writes is the ide worker's fs.exec_confinement switch.