harness::edit_queued
functionInternal control-plane: edit a still-parked queued message in place by entry_id, preserving its queue position.
entry_idstring*required
The queued row to edit (its client-visible `entry_id`).
messageall of*required
The replacement message (string sugar or a full user/custom message).
all of (1)
variant 1
any of (2)
variant 2
any of (4)
variant 1
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
timestampinteger· int64*required
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
function_call_idstring*required
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
variant 3
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
rolestring*requiredenum: custom
timestampinteger· int64*required
variant 4
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
session_idstring*required
updatedboolean*required
False when no still-parked row matched — already drained or unknown.
Internal control-plane: grant a session access to an additional filesystem root.
session_idstring*required
session_idstring*required
Internal control-plane: list additional filesystem roots granted to a session.
session_idstring*required
session_idstring*required
Internal control-plane: the default working-directory root new sessions are scoped to.
default_rootstring
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.
session_idstring*required
session_idstring*required
Internal: settle a pending call's result (or release a held call) and resume the parked turn.
actionstring
`deliver` (default) supplies the result; `execute` releases a hook-held call through the remaining trigger pipeline.
contentone of[]
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
fs_scopeany of
execute only: one-shot additional roots trusted by the caller and unioned with the session's durable filesystem grants.
function_call_idstring*required
session_idstring*required
resolvedboolean*required
False when the call is unknown, already done, or (execute) not held.
turn_resumedboolean*required
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.
callobject*required
argumentsunknown*required
function_idstring*required
The iii function to invoke (already unwrapped from `agent_trigger`).
idstring*required
function_call id, echoed into the result.
session_idstring*required
any of (2)
variant 1
contentone of[]*required
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
duration_msinteger· uint64*requiredmin 0
function_call_idstring*required
function_idstring*required
variant 2
function_call_idstring*required
function_idstring*required
pending_timeout_msinteger· uint64min 0
harness::notify_agent
functionInternal: the shared subscription fire handler — injects a notification into the owning session (resolved from the local subscription registry). Not called directly.
Internal: hot-reload harness from the authoritative configuration when it changes — re-binds the cron pending-sweep on a sweep_expression change and swaps the per-call tuning snapshot otherwise.
idstring
Configuration id that changed (advisory; the handler re-fetches).
Internal: refresh the cached function-registry snapshot when functions are registered/unregistered (driven by the engine::functions-available trigger).
eventstring
Engine event tag (advisory; the handler re-fetches the full list).
Internal: drop a deleted session's ephemeral subscriptions. Not called directly.
session_idstring*required
removedinteger· uint64*requiredmin 0
Internal trigger bridge: reshape a subscribed event into a harness::spawn (a sub-agent), optionally behind a join barrier. Not called directly — THE way to spin up sub-agents on events and callbacks: bind it via engine::register_trigger with the sub-agent spec in `metadata`.
child_session_idstring
The spawned sub-agent's child session id, when spawn returned one.
notestring
Why nothing spawned (missing spec, join not yet complete, already fired, error). Present iff `!spawned`.
spawnedboolean*required
Whether a `harness::spawn` was dispatched this call.
Entry point: ensure the session, persist the incoming message, and kick off a turn; returns fast (or merges into a running turn).
idempotency_keystring
Webhook dedupe: a repeated key returns the original `{session_id, turn_id}` and appends nothing.
messageall of*required
The incoming message; a string is sugar for a user text message. The role must be `user` or `custom`.
all of (1)
variant 1
any of (2)
variant 2
any of (4)
variant 1
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
timestampinteger· int64*required
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
function_call_idstring*required
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
variant 3
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
rolestring*requiredenum: custom
timestampinteger· int64*required
variant 4
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
optionsany of
any of (2)
variant 1
functionsany of
The fail-closed dispatch policy; omit to deny every call.
… expand 2 nestedcollapse
any of (2)
variant 1
exposeall of
… expand 1 nestedcollapse
all of (1)
variant 1
valuestringenum: agent_trigger, native
max_turnsinteger· uint32min 0
metadataunknown
Tracing passthrough.
modeany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: plan, ask, agent
outputany of
The turn's deliverable; default `{ type: "text" }`.
… expand 2 nestedcollapse
any of (2)
variant 1
one of (2)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: json
system_prompt_strategyall of
How `system_prompt` combines with the built-in prompt: `override` replaces it; `enrich` (default) appends to it.
… expand 1 nestedcollapse
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: override
variant 2
valuestringenum: enrich
thinking_levelany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: minimal, low, medium, high, xhigh
sessionany of
Applied when this send creates/ensures the session.
session_idstring
Omit to create a new session.
deduplicatedboolean
True when `idempotency_key` matched an earlier send.
mergedboolean
True when folded into an in-flight turn (steering).
queuedboolean
True when the message was queued while a step was streaming; it lands in the transcript when the stream ends.
session_idstring*required
Spawn a sub-agent in a child session; the model-facing pending trigger — parks the calling turn until the child resolves. Call it directly ONLY when the current turn needs the child's answer; for callbacks, follow-up stages, and fan-in, register the reaction via engine::register_trigger -> harness::react instead.
optionsany of
any of (2)
variant 1
filesystem_rootstring
Absolute filesystem root for the child turn (e.g. an isolated `worktree::create` checkout), written to the child's `metadata.fs_scope.root`. When set it overrides the inherited scope for this child; when absent the child inherits its direct parent's root unchanged.
functionsany of
Intersected with the parent policy — narrow, never escalate.
… expand 2 nestedcollapse
any of (2)
variant 1
exposeall of
… expand 1 nestedcollapse
all of (1)
variant 1
valuestringenum: agent_trigger, native
max_childreninteger· uint32min 0
Fan-out guard for the child's own spawns.
max_turnsinteger· uint32min 0
Capped at the parent's remaining turn budget.
modeany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: plan, ask, agent
outputany of
The child's deliverable: text / json / json+schema.
… expand 2 nestedcollapse
any of (2)
variant 1
one of (2)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: json
pending_timeout_msinteger· uint64min 0
Parent-side wait guard for this child.
system_prompt_strategyall of
How `system_prompt` combines with the built-in prompt: `override` replaces it; `enrich` (default) appends to it.
… expand 1 nestedcollapse
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: override
variant 2
valuestringenum: enrich
thinking_levelany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: minimal, low, medium, high, xhigh
parent_session_idstring
Display-only parent for the console session tree, used when there is no live parent turn (e.g. a trigger-fired spawn from `harness::react`). Writes `SessionMeta.metadata.parent_session_id` so the console nests this child; it does NOT grant policy inheritance or parent-call resolution. Ignored when the dispatcher injects a real parent link (an in-turn spawn).
reactive_depthinteger· uint32min 0
Stamped by `harness::react` (not caller-supplied): reactive-chain depth, echoed on this turn's `turn-completed` event so react can cap runaway chains at `MAX_REACTIVE_DEPTH`.
session_idstring
Spawn into this session, creating it if it does not exist (e.g. a fork, or a pre-chosen id to filter `turn-completed` subscriptions on); default: create fresh.
spawned_by_subscription_idstring
Stamped by `harness::react` (not caller-supplied): the subscription that spawned this turn. Its completion event is never delivered back to that same subscription (self-edge loop breaker).
taskall of*required
The child's goal — its opening user message.
all of (1)
variant 1
any of (2)
variant 2
any of (4)
variant 1
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
timestampinteger· int64*required
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
function_call_idstring*required
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
variant 3
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
rolestring*requiredenum: custom
timestampinteger· int64*required
variant 4
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
child_session_idstring*required
child_turn_idstring*required
Read the current turn status for a session.
session_idstring*required
any of (2)
variant 1
childrenobject[]*required
function_call_idstring*required
session_idstring*required
depthinteger· uint32*requiredmin 0
max_turnsinteger· uint32*requiredmin 0
pending_function_callsstring[]*required
queuedobject[]
Messages queued while a step streams, in arrival order; they land in the transcript when the stream ends.
entry_idstring*required
Deterministic transcript entry id the drain appends under, so a redelivered drain is a no-op.
messageany of*required
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).
… expand 4 nestedcollapse
any of (4)
variant 1
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
rolestring*requiredenum: assistant
stop_reasonstring*requiredenum: end, length, function_call, aborted, error
timestampinteger· int64*required
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
function_call_idstring*required
function_idstring*required
rolestring*requiredenum: function_result
timestampinteger· int64*required
variant 3
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
custom_typestring*required
rolestring*requiredenum: custom
timestampinteger· int64*required
variant 4
contentone of[]*required
… expand 6 nestedcollapse
one of (6)
variant 1
typestring*requiredenum: text
variant 2
typestring*requiredenum: image
variant 3
typestring*requiredenum: thinking
variant 4
typestring*requiredenum: redacted_thinking
variant 5
argumentsunknown*required
function_idstring*required
typestring*requiredenum: function_call
variant 6
contentunknown[]*required
function_call_idstring*required
typestring*requiredenum: function_result
rolestring*requiredenum: user
timestampinteger· int64*required
queued_atinteger· int64*required
session_idstring*required
session_idstring*required
statusstring*requiredenum: running, awaiting_functions, completed, cancelled, failed
The coarse, harness-internal turn lifecycle (harness.md § API Reference). Finer-grained than the session's `status`, which the loop derives from it.
stepinteger· uint64*requiredmin 0
turn_countinteger· uint32*requiredmin 0
Request cancellation of an in-flight turn (cascades to spawned children).
session_idstring*required
turn_idstring
Omit to stop the current turn.
harness::sweep-pending
functionInternal cron sweep: resolve pending function calls past their timeout so a parked turn never wedges. Not called directly.
scheduled_atinteger· int64
resolvedinteger· uint64*requiredmin 0
Number of expired pending calls resolved this sweep.
Internal durable loop step (enqueued onto the default queue); not called directly.
depthinteger· uint32min 0
Sub-agent depth carried from the turn record (0 = top-level), so the step can stamp the `iii.tag.kind` baggage (`harness.turn` / `harness.subagent`) before any state read. Defaults to 0 so stale in-flight payloads from before this field existed still classify as top-level turns.
message_previewstring
Preview carried from the turn record so the step can stamp the `iii.tag.message` baggage before any state read.
session_idstring*required
stepinteger· uint64*requiredmin 0
next_stepinteger· uint64min 0
session_idstring*required
skippedboolean
True when a redelivered/stale step was acked and dropped.
statusstring*requiredenum: running, awaiting_functions, completed, cancelled, failed
The coarse, harness-internal turn lifecycle (harness.md § API Reference). Finer-grained than the session's `status`, which the loop derives from it.
Internal control-plane: remove a still-parked queued message by entry_id (the console's edit-queued path).
entry_idstring*required
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.
session_idstring*required
removedboolean*required
False when no still-parked row matched — already drained or unknown.
