harness::context-policy
Return the Harness context-pruning policy for a destination model without making a model request.
- modelstringrequired
- allow_prunebooleanrequired
Whether aged function results may be pruned for this model.
harness
v1.8.40Thin durable turn loop that wires session-manager, context-manager, and llm-router into an agent loop; spawns sub-agents as child sessions.
Install
bash
iii trigger compose::add worker=harness@1.8.40Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.
Functions32
Function
harness::delete-session-tree
Durably cancel and delete only the selected session subtree; returns an operation snapshot.
- session_idstringrequired
- attemptinteger· uint32requiredmin 1
Initial attempt is 1; only an explicit failed-operation retry increments it.
- deleted_session_idsstring[]required
- errorstring
- operation_idstringrequired
- session_idstringrequired
- statusstringrequiredenum deleting, completed, failed
harness::delete-session-tree-run
Internal queued subtree deletion continuation.
- operation_idstringrequired
any of (2)
Variant 1
- attemptinteger· uint32requiredmin 1
Initial attempt is 1; only an explicit failed-operation retry increments it.
- deleted_session_idsstring[]required
- errorstring
- operation_idstringrequired
- session_idstringrequired
- statusstringrequiredenum deleting, completed, failed
Variant 2
valuenull
harness::delete-session-tree-status
Read a durable session subtree deletion snapshot, or null if unknown.
- operation_idstringrequired
any of (2)
Variant 1
- attemptinteger· uint32requiredmin 1
Initial attempt is 1; only an explicit failed-operation retry increments it.
- deleted_session_idsstring[]required
- errorstring
- operation_idstringrequired
- session_idstringrequired
- statusstringrequiredenum deleting, completed, failed
Variant 2
valuenull
harness::edit_queued
Internal control-plane: edit a still-parked queued message in place by entry_id, preserving its queue position.
- entry_idstringrequired
The queued row to edit (its client-visible `entry_id`).
- messagestringrequired
The replacement user message text.
- session_idstringrequired
- updatedbooleanrequired
False when no still-parked row matched — already drained or unknown.
harness::filesystem::grant
Internal control-plane: grant a session access to an additional filesystem root.
- rootstringrequired
- session_idstringrequired
- rootsstring[]required
- session_idstringrequired
harness::filesystem::grants
Internal control-plane: list additional filesystem roots granted to a session.
- session_idstringrequired
- rootsstring[]required
- session_idstringrequired
harness::filesystem::info
Internal control-plane: the default working-directory root new sessions are scoped to.
Empty object
- boundaryall ofrequired
Effective per-session boundary for shell/coder calls. `workspace` when the filesystem approval hook can widen it, otherwise `configured_roots`.
all of (1)Variant 1valuestringenum workspace, configured_roots - 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.
harness::filesystem::revoke
Internal control-plane: revoke a session's access to an additional filesystem root.
- rootstringrequired
- session_idstringrequired
- rootsstring[]required
- session_idstringrequired
harness::function::resolve
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 (7)Variant 1
- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
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.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- detailsunknown
- fs_scopeany of
execute only: one-shot additional roots trusted by the caller and unioned with the session's durable filesystem grants.
any of (2)Variant 1- grantsstring[]
Variant 2valuenull - function_call_idstringrequired
- is_errorboolean
- session_idstringrequired
- turn_idstringrequired
- resolvedbooleanrequired
False when the call is unknown, already done, or (execute) not held.
- turn_resumedbooleanrequired
True when this resolve re-enqueued the turn.
harness::function::trigger
Internal: invoke one iii function (unwrapped from agent_trigger), enforce the dispatch policy, and capture the normalised result — or report it pending.
- callobjectrequired
- argumentsunknownrequired
- function_idstringrequired
The iii function to invoke (already unwrapped from `agent_trigger`).
- idstringrequired
function_call id, echoed into the result.
- session_idstringrequired
any of (2)
Variant 1
- contentone of[]requiredone of (7)Variant 1
- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
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.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- detailsunknownrequired
- duration_msinteger· uint64requiredmin 0
- function_call_idstringrequired
- function_idstringrequired
- is_errorbooleanrequired
Variant 2
- function_call_idstringrequired
- function_idstringrequired
- pendingbooleanrequired
- pending_timeout_msinteger· uint64min 0
harness::metrics
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.
one of (2)
Variant 1
Empty object
Variant 2
Empty object
- by_sessionobject[]required
- cache_read_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- cache_write_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- contextany of
The session's latest per-generation context snapshot (categories, budget, usage) — absent for sessions that have not generated since snapshots landed.
any of (2)Variant 1- categoriesobjectrequired
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.
Show 6 nestedHide nested
- hook_guidanceinteger· uint64min 0
- messagesobjectrequired
Estimated tokens of the assembled window's messages, by role.
Show 4 nestedHide nested
- assistantinteger· uint64requiredmin 0
- custominteger· uint64requiredmin 0
- function_resultinteger· uint64requiredmin 0
- userinteger· uint64requiredmin 0
- overheadinteger· uint64requiredmin 0
Provider framing plus response_format / provider_options fields.
- skillsinteger· uint64min 0
Selected skill bodies contained in the system prompt.
- system_promptinteger· uint64requiredmin 0
Final assembled system prompt excluding tokens attributed to `skills`: identity, per-step aids, and any compaction summary section.
- toolsinteger· uint64requiredmin 0
Function schemas exposed to the model.
- compactedbooleanrequired
The context carries a conversation summary: compacted on this step, or anchored on an earlier compaction entry (a previous step, the console's `/compact`). The summary's tokens count in `system_prompt`.
- effective_max_output_tokensinteger· uint64requiredmin 0
Output allocation `usable` was derived against.
- estimatorstring
Which estimator produced the numbers (`heuristic` until the context-manager resolves a real tokenizer). Absent when the context-manager predates the breakdown response.
- freeinteger· uint64requiredmin 0
- modelstringrequired
- prompt_sections_fallbackstring
Why no shared prefix went out: `disabled` (config), `no_stable_prefix` (empty identity prompt) or `prefix_rewritten` (a pre_generate hook replaced the prompt head; its prompt still wins, it just shares nothing).
- prompt_surface_digeststring
Identity of the shared prompt prefix this generation went out with (`sha256:` of the stable section) — present only when the request carried `system_sections`. A local identity, never a provider hit; `usage.cache_read` is the reuse signal.
- providerstring
- session_cost_usdnumber· double
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.
- session_idstringrequired
- stepinteger· uint64requiredmin 0
- summarized_head_tokensinteger· uint64min 0
Size of the history that summary replaced.
- timestampinteger· int64required
- totalinteger· uint64requiredmin 0
Final request estimate: categories plus post-assembly growth.
- turn_idstringrequired
- usableinteger· uint64requiredmin 0
The input budget the window was fit into.
- usageany of
Actual provider usage for this generation, stamped after the terminal frame; absent when the provider returned none (or the generation never completed).
Show 2 nestedHide nested
any of (2)Variant 1- cache_readinteger· uint64min 0
- cache_writeinteger· uint64min 0
- cost_usdnumber· double
- inputinteger· uint64min 0
- outputinteger· uint64min 0
- reasoninginteger· uint64min 0
Variant 2valuenull
Variant 2valuenull - cost_usdnumber· doublerequired
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- depthinteger· uint32requiredmin 0
- function_call_errorsinteger· uint64requiredmin 0
- function_callsinteger· uint64requiredmin 0
- input_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- output_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- parent_session_idstring
- reasoning_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- session_idstringrequired
- turnsinteger· uint64requiredmin 0
- completebooleanrequired
- root_session_idstringrequired
- totalsobjectrequired
- cache_read_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- cache_write_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- cost_usdnumber· doublerequired
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- function_call_errorsinteger· uint64requiredmin 0
- function_callsinteger· uint64requiredmin 0
- input_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- output_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- reasoning_tokensinteger· uint64requiredmin 0
Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.
- sessionsinteger· uint64requiredmin 0
- turnsinteger· uint64requiredmin 0
- tracesany of
Trace/span aggregates when the engine's in-memory observability exporter is available. Usage metrics remain available when it is not.
any of (2)Variant 1- by_sessionobject[]required
Show 7 nestedHide nested
- depthinteger· uint32requiredmin 0
- duration_msinteger· uint64requiredmin 0
Elapsed window from the session's first observed span to its last.
- error_span_countinteger· uint64requiredmin 0
- parent_session_idstring
- session_idstringrequired
- span_countinteger· uint64requiredmin 0
- trace_countinteger· uint64requiredmin 0
- duration_msinteger· uint64requiredmin 0
Elapsed window from the first observed span to the last observed span.
- error_span_countinteger· uint64requiredmin 0
- span_countinteger· uint64requiredmin 0
- trace_countinteger· uint64requiredmin 0
Distinct traces across the root session and all descendants.
Variant 2valuenull
harness::on-functions-change
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).
- okbooleanrequired
harness::on-session-deleted
Internal: drop a deleted session's ephemeral subscriptions. Not called directly.
- session_idstringrequired
- okbooleanrequired
- removedinteger· uint64requiredmin 0
harness::on-skills-change
Internal: refresh the cached model-invocable skill catalog.
- opstring
- okbooleanrequired
harness::projects::delete
Internal control-plane: remove a project directory from the durable catalog.
- pathstringrequired
- deletedbooleanrequired
harness::projects::list
Internal control-plane: list the operator's durable project catalog.
Empty object
- projectsobject[]required
- last_used_atinteger· int64required
- namestringrequired
- pathstringrequired
harness::projects::upsert
Internal control-plane: remember, touch, or rename a project directory.
- namestring
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.
- pathstringrequired
- projectobjectrequired
- last_used_atinteger· int64required
- namestringrequired
- pathstringrequired
harness::send
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.
- messagestringrequired
The incoming user message text.
- modelstring
Required on a new session unless `options.agent` supplies a model; an existing session inherits its last turn's model when omitted.
- optionsany ofany of (2)Variant 1
- agentstring
Directory agent profile id (`directory::agents::*`) replacing the built-in identity; new sessions only, refused with a prompt field.
- functionsany of
Fail-closed dispatch policy; omitted means deny all on a new session and inherit on an existing one (`{ allow: [] }` strips explicitly).
Show 2 nestedHide nested
any of (2)Variant 1- allowstring[]
- denystring[]
- exposeall of
Show 1 nestedHide nested
all of (1)Variant 1valuestringenum agent_trigger, native
Variant 2valuenull - max_cost_usdnumber· double
Hard USD budget for the complete root-and-subagent session tree. Every model used by the tree must advertise catalog pricing.
- max_output_tokensinteger· uint64min 0
Per-generation output-token ceiling forwarded to the router.
- max_total_tokensinteger· uint64min 0
Hard input-plus-output token budget for the complete root-and-subagent session tree.
- max_turnsinteger· uint32min 0
- max_validation_retriesinteger· uint32min 0
Per-turn override of the validation-retry budget.
- metadataunknown
Tracing passthrough.
- outputany of
The turn's deliverable; default `{ type: "text" }`.
Show 2 nestedHide nested
any of (2)Variant 1one of (2)Variant 1- typestringrequiredenum text
Variant 2- schemaunknown
- typestringrequiredenum json
Variant 2valuenull - provider_optionsobject
Provider-native per-call options, namespaced by provider id.
- skillsstring[]
Exact skill ids advertised to the model; omitted or empty means all on a new session (existing: omitted inherits, empty resets).
- system_promptstring
- system_prompt_strategyany of
How `system_prompt` combines with the built-in prompt; omitting both prompt fields on an existing session inherits the prior prompt.
Show 2 nestedHide nested
any of (2)Variant 1one of (3)Variant 1valuestringenum overrideVariant 2valuestringenum enrichVariant 3valuestringenum disabledVariant 2valuenull - thinking_levelany of
Omitting both reasoning fields on an existing session inherits the prior turn's; naming either resolves fresh (`provider_options: {}` resets to the provider default).
Show 2 nestedHide nested
any of (2)Variant 1valuestringenum minimal, low, medium, high, xhighVariant 2valuenull
Variant 2valuenull - providerstring
- sessionany of
Applied when this send creates/ensures the session.
any of (2)Variant 1- kindstring
Session kind stored on creation: `user` (default), `automation` or `e2e`. Opaque to the harness; validated by session-manager.
- metadataunknown
- titlestring
Variant 2valuenull - session_idstring
Omit to create a new session.
- acceptedbooleanrequired
- 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_idstringrequired
- turn_idstringrequired
harness::session-tree
Read the durable root-and-descendant session tree for one harness run.
- root_session_idstringrequired
- completebooleanrequired
- root_session_idstringrequired
- sessionsobject[]required
- depthinteger· uint32requiredmin 0
- parent_session_idstring
- parent_turn_idstring
- session_idstringrequired
harness::spawn
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.
- agentstring
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).
- displayany of
Display-only name/icon/color for the child session; never affects ids, policy, or routing.
any of (2)Variant 1- colorany of
Show 2 nestedHide nested
any of (2)Variant 1valuestringenum neutral, blue, purple, teal, green, amber, …Variant 2valuenull - iconany of
Show 2 nestedHide nested
any of (2)Variant 1valuestringenum agent, code, search, terminal, database, test, …Variant 2valuenull - namestringrequired1…48 chars
Short functional name such as `Frontend`, 1-48 characters after trimming.
Variant 2valuenull - modelstring
- optionsany ofany of (2)Variant 1
- filesystem_rootstring
Absolute filesystem root for the child turn; omit to inherit the parent's.
- functionsany of
Dispatch policy for the child, intersected with the parent's (narrow, never escalate).
Show 2 nestedHide nested
any of (2)Variant 1- allowstring[]
- denystring[]
- exposeall of
Show 1 nestedHide nested
all of (1)Variant 1valuestringenum agent_trigger, native
Variant 2valuenull - max_childreninteger· uint32min 0
Fan-out guard for the child's own spawns.
- max_output_tokensinteger· uint64min 0
Inherits the parent's ceiling unless explicitly narrowed/overridden.
- max_turnsinteger· uint32min 0
Turn cap for the child, capped at the parent's remaining budget; omit unless required (small values strand the child).
- max_validation_retriesinteger· uint32min 0
Override of the child's validation-retry budget.
- orchestratorboolean
Let the child spawn, send, and register triggers (still capped by the parent's policy); default false makes it a leaf.
- outputany of
The child's deliverable: text / json / json+schema.
Show 2 nestedHide nested
any of (2)Variant 1one of (2)Variant 1- typestringrequiredenum text
Variant 2- schemaunknown
- typestringrequiredenum json
Variant 2valuenull - skillsstring[]
Exact skill ids advertised to the child; omitted or empty means all (a reused child inherits when omitted).
- system_promptstring
- system_prompt_strategyall of
How `system_prompt` combines with the built-in prompt.
Show 1 nestedHide nested
all of (1)Variant 1one of (3)Variant 1valuestringenum overrideVariant 2valuestringenum enrichVariant 3valuestringenum disabled - thinking_levelany of
Show 2 nestedHide nested
any of (2)Variant 1valuestringenum minimal, low, medium, high, xhighVariant 2valuenull
Variant 2valuenull - parent_session_idstring
Display-only parent for the console tree when there is no live parent turn; grants no policy inheritance.
- providerstring
- session_idstring
Session id to spawn into, created if absent; an existing id may be reused only inside the caller's own tree.
- taskstringrequired
The child's self-contained goal, its opening user message; name every required resource selector literally (the child cannot infer them).
- child_session_idstringrequired
- child_turn_idstringrequired
- reusedboolean
The named session already existed and was reused — its prior transcript and parent linkage were retained (only possible with an explicit `session_id`).
harness::status
Read a session's current turn. Returns a lean summary by default; pass verbose: true for the full runtime report and untruncated result.
- session_idstringrequired
- verboseboolean
Include the full runtime report and unmodified result.
any of (2)
Variant 1
- armed_wakesobject[]
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.
- configunknown
- created_atinteger· int64required
- expires_atinteger· int64
- subscription_idstringrequired
- trigger_typestring
The registered trigger's type/config, read from the canonicalised registration request. Absent on records that predate it.
- childrenobject[]required
- function_call_idstringrequired
- session_idstringrequired
- turn_idstringrequired
- contextany of
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.
any of (2)Variant 1- categoriesobjectrequired
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.
Show 6 nestedHide nested
- hook_guidanceinteger· uint64min 0
- messagesobjectrequired
Estimated tokens of the assembled window's messages, by role.
Show 4 nestedHide nested
- assistantinteger· uint64requiredmin 0
- custominteger· uint64requiredmin 0
- function_resultinteger· uint64requiredmin 0
- userinteger· uint64requiredmin 0
- overheadinteger· uint64requiredmin 0
Provider framing plus response_format / provider_options fields.
- skillsinteger· uint64min 0
Selected skill bodies contained in the system prompt.
- system_promptinteger· uint64requiredmin 0
Final assembled system prompt excluding tokens attributed to `skills`: identity, per-step aids, and any compaction summary section.
- toolsinteger· uint64requiredmin 0
Function schemas exposed to the model.
- compactedbooleanrequired
The context carries a conversation summary: compacted on this step, or anchored on an earlier compaction entry (a previous step, the console's `/compact`). The summary's tokens count in `system_prompt`.
- effective_max_output_tokensinteger· uint64requiredmin 0
Output allocation `usable` was derived against.
- estimatorstring
Which estimator produced the numbers (`heuristic` until the context-manager resolves a real tokenizer). Absent when the context-manager predates the breakdown response.
- freeinteger· uint64requiredmin 0
- modelstringrequired
- prompt_sections_fallbackstring
Why no shared prefix went out: `disabled` (config), `no_stable_prefix` (empty identity prompt) or `prefix_rewritten` (a pre_generate hook replaced the prompt head; its prompt still wins, it just shares nothing).
- prompt_surface_digeststring
Identity of the shared prompt prefix this generation went out with (`sha256:` of the stable section) — present only when the request carried `system_sections`. A local identity, never a provider hit; `usage.cache_read` is the reuse signal.
- providerstring
- session_cost_usdnumber· double
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.
- session_idstringrequired
- stepinteger· uint64requiredmin 0
- summarized_head_tokensinteger· uint64min 0
Size of the history that summary replaced.
- timestampinteger· int64required
- totalinteger· uint64requiredmin 0
Final request estimate: categories plus post-assembly growth.
- turn_idstringrequired
- usableinteger· uint64requiredmin 0
The input budget the window was fit into.
- usageany of
Actual provider usage for this generation, stamped after the terminal frame; absent when the provider returned none (or the generation never completed).
Show 2 nestedHide nested
any of (2)Variant 1- cache_readinteger· uint64min 0
- cache_writeinteger· uint64min 0
- cost_usdnumber· double
- inputinteger· uint64min 0
- outputinteger· uint64min 0
- reasoninginteger· uint64min 0
Variant 2valuenull
Variant 2valuenull - depthinteger· uint32min 0
- expects_wakeboolean
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.
- max_transient_resumesinteger· uint32min 0
- max_turnsinteger· uint32min 0
- max_validation_retriesinteger· uint32min 0
- partial_result_availableboolean
- pending_function_callsstring[]
- queuedobject[]
Messages queued while a step streams, in arrival order; they land in the transcript when the stream ends.
- entry_idstringrequired
Deterministic transcript entry id the drain appends under, so a redelivered drain is a no-op.
- idstringrequired
- messageany ofrequired
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).
Show 4 nestedHide nested
any of (4)Variant 1- contentone of[]required
Show 7 nestedHide nested
one of (7)Variant 1- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
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.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- error_kindany of
Show 2 nestedHide nested
any of (2)Variant 1valuestringenum auth_expired, rate_limited, context_overflow, transient, permanentVariant 2valuenull - error_messagestring
- modelstringrequired
- native_stop_reasonstring
- providerstringrequired
- rolestringrequiredenum assistant
- stop_reasonstringrequiredenum end, length, function_call, aborted, error
- timestampinteger· int64required
- usageany of
Show 2 nestedHide nested
any of (2)Variant 1- cache_readinteger· uint64min 0
- cache_writeinteger· uint64min 0
- cost_usdnumber· double
- inputinteger· uint64min 0
- outputinteger· uint64min 0
- reasoninginteger· uint64min 0
Variant 2valuenull - warningsstring[]
Variant 2- contentone of[]required
Show 7 nestedHide nested
one of (7)Variant 1- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
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.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- detailsunknownrequired
- function_call_idstringrequired
- function_idstringrequired
- is_errorbooleanrequired
- rolestringrequiredenum function_result
- timestampinteger· int64required
Variant 3- contentone of[]required
Show 7 nestedHide nested
one of (7)Variant 1- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
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.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- custom_typestringrequired
- detailsunknown
- displaystring
- rolestringrequiredenum custom
- timestampinteger· int64required
Variant 4- contentone of[]required
Show 7 nestedHide nested
one of (7)Variant 1- textstringrequired
- typestringrequiredenum text
Variant 2- attachment_idstring
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.
- datastringrequired
- mimestringrequired
- typestringrequiredenum image
Variant 3- attachment_idstringrequired
- mimestringrequired
- namestringrequired
- sizeinteger· uint64requiredmin 0
- typestringrequiredenum file
Variant 4- signaturestring
- textstringrequired
- typestringrequiredenum thinking
Variant 5- datastringrequired
- typestringrequiredenum redacted_thinking
Variant 6- argumentsunknownrequired
- function_idstringrequired
- idstringrequired
- typestringrequiredenum function_call
Variant 7- contentunknown[]required
- function_call_idstringrequired
- is_errorboolean
- typestringrequiredenum function_result
- rolestringrequiredenum user
- timestampinteger· int64required
- originunknown
- queued_atinteger· int64required
- session_idstringrequired
- resultunknown
- result_errorstring
- session_idstringrequired
- statusstringrequiredenum 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· uint64requiredmin 0
- stop_reasonstring
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.
- transient_resumesinteger· uint32min 0
- turn_countinteger· uint32requiredmin 0
- turn_idstring
- validation_retriesinteger· uint32min 0
Variant 2
valuenull
harness::stop
Request cancellation of an in-flight turn (cascades to spawned children).
- session_idstringrequired
- turn_idstring
Omit to stop the current turn.
- stoppingbooleanrequired
harness::sweep-pending
Internal cron sweep: resolve pending function calls past their timeout and re-enqueue the step of running turns left without one, so a turn never wedges. Not called directly.
- scheduled_atinteger· int64
- okbooleanrequired
- redriveninteger· uint64min 0
Number of orphaned running turns whose step was re-enqueued.
- resolvedinteger· uint64requiredmin 0
Number of expired pending calls resolved this sweep.
harness::system-prompt::get
Preview the system prompt layers a session will use without making a model request.
- default_onlyboolean
Return only the built-in default layer, without session, runtime, registry, or hook layers.
- filesystem_rootstring
- selected_promptany ofany of (2)Variant 1
- bodystringrequired
- namestringrequired
- strategyall of
Show 1 nestedHide nested
all of (1)Variant 1one of (3)Variant 1valuestringenum overrideVariant 2valuestringenum enrichVariant 3valuestringenum disabled
Variant 2valuenull - session_idstringrequired
- partsobject[]required
- bodystringrequired
- kindstringrequiredenum built_in, selected, skills, runtime, injected
- namestring
harness::teardown
Internal control-plane: remove trigger bindings owned by a root harness session tree.
- root_session_idstringrequired
- removedinteger· uint64requiredmin 0
harness::trigger::deliver
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.
valuenull
- deliveredbooleanrequired
Whether the target was dispatched this fire.
- gatestring
Which gate or condition stopped it. Present iff `!delivered`.
- notestring
Why. Present iff `!delivered`.
harness::triggers::list
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`.
- session_idstring
Owner session whose bindings to list; in-turn calls may omit it (the calling session is injected).
- subscriptionsobject[]required
- actionstring
Human-readable event text declared as `metadata.action`.
- conditionsobject[]
- configunknown
- function_idstringrequired
- configunknown
- created_atinteger· int64required
- expires_atinteger· int64
- firesinteger· uint64requiredmin 0
- labelstring
- max_firesinteger· uint64min 0
- oncebooleanrequired
- subscription_idstringrequired
- targetstring
The function a fire calls. Absent for a wake — the fire notifies the owner session.
- trigger_idstring
The engine's own trigger id (absent only in the brief window before the engine acknowledged the registration).
- trigger_typestring
harness::triggers::unregister
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.
- session_idstring
The binding's owner session; in-turn calls may omit it (the calling session is injected).
- subscription_idstringrequired
The subscription to remove (`id` is accepted as an alias).
- removedbooleanrequired
False when no record existed (already retired) — honest, not an error.
harness::turn
Internal durable loop step (enqueued onto the harness-turn queue); not called directly.
- depthinteger· uint32min 0
Sub-agent depth carried from the turn record (0 = top-level).
- message_previewstring
Preview carried from the turn record so the step can stamp the `iii.tag.message` baggage before any state read.
- session_idstringrequired
- stepinteger· uint64requiredmin 0
- turn_idstringrequired
- next_stepinteger· uint64min 0
- session_idstringrequired
- skippedboolean
True when a redelivered/stale step was acked and dropped.
- statusstringrequiredenum 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.
harness::ui-content
Serve the harness worker's injected console UI assets (content function for its console:script / console:style triggers).
- pathstringrequired
The asset path from the trigger config (e.g. `state/page.js`).
- contentstringrequired
The asset source, verbatim.
- content_typestringrequired
MIME type the console should serve the asset with.
harness::unqueue
Internal control-plane: remove a still-parked queued message by entry_id (the console's edit-queued path).
- entry_idstringrequired
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_idstringrequired
- removedbooleanrequired
False when no still-parked row matched — already drained or unknown.
Triggers13
harness::hook::post-generate
Synchronous hook: after the final assistant message update. Observe only.
- functionsstring[]
pre/post_trigger only: target function_id globs to consult on.
- on_errorstring
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
- payloadunknown
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`).
- priorityinteger· int64
Chain order: ascending, ties broken by function_id (default 0).
- result_intostring
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
- retry_promptstring
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.
- sessionsstring[]
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
- timeout_msinteger· uint64min 0
Per-invocation timeout (default 5000ms).
valueunknown
harness::hook::post-trigger
Synchronous hook: after the target returns, before the result is appended. May rewrite content/details/is_error.
- functionsstring[]
pre/post_trigger only: target function_id globs to consult on.
- on_errorstring
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
- payloadunknown
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`).
- priorityinteger· int64
Chain order: ascending, ties broken by function_id (default 0).
- result_intostring
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
- retry_promptstring
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.
- sessionsstring[]
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
- timeout_msinteger· uint64min 0
Per-invocation timeout (default 5000ms).
valueunknown
harness::hook::post-turn
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.
- functionsstring[]
pre/post_trigger only: target function_id globs to consult on.
- on_errorstring
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
- payloadunknown
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`).
- priorityinteger· int64
Chain order: ascending, ties broken by function_id (default 0).
- result_intostring
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
- retry_promptstring
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.
- sessionsstring[]
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
- timeout_msinteger· uint64min 0
Per-invocation timeout (default 5000ms).
valueunknown
harness::hook::pre-generate
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.
- functionsstring[]
pre/post_trigger only: target function_id globs to consult on.
- on_errorstring
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
- payloadunknown
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`).
- priorityinteger· int64
Chain order: ascending, ties broken by function_id (default 0).
- result_intostring
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
- retry_promptstring
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.
- sessionsstring[]
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
- timeout_msinteger· uint64min 0
Per-invocation timeout (default 5000ms).
valueunknown
harness::hook::pre-trigger
Synchronous hook: after the allow/deny policy passes, before the target is invoked. May deny, hold, or rewrite arguments.
- functionsstring[]
pre/post_trigger only: target function_id globs to consult on.
- on_errorstring
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
- payloadunknown
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`).
- priorityinteger· int64
Chain order: ascending, ties broken by function_id (default 0).
- result_intostring
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
- retry_promptstring
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.
- sessionsstring[]
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
- timeout_msinteger· uint64min 0
Per-invocation timeout (default 5000ms).
valueunknown
harness::hook::pre-turn
Synchronous hook: first step of a turn, before any model spend. May veto.
- functionsstring[]
pre/post_trigger only: target function_id globs to consult on.
- on_errorstring
Failure policy (default fail_closed for pre_* and post_turn, fail_open for the other post_*).
- payloadunknown
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`).
- priorityinteger· int64
Chain order: ascending, ties broken by function_id (default 0).
- result_intostring
post_turn template mode: JSON pointer where the result lands in `payload` (default `/value`).
- retry_promptstring
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.
- sessionsstring[]
pre_turn/post_turn: session_id globs this hook applies to (omit = all).
- timeout_msinteger· uint64min 0
Per-invocation timeout (default 5000ms).
valueunknown
harness::message-queued
A message parked in a session's server-side queue while its turn streams.
- parent_session_idstring
Only deliver sub-agent events whose parent is this session.
- session_idstring
Only deliver events for this session.
valueunknown
harness::ready
The harness completed boot and can accept turns.
Empty object
valueunknown
harness::session-tree-deletion
A subtree deletion changed status; subscribe before requesting deletion and recover once by operation_id.
- operation_idstring
- session_idstring
- attemptinteger· uint32requiredmin 1
Initial attempt is 1; only an explicit failed-operation retry increments it.
- deleted_session_idsstring[]required
- errorstring
- operation_idstringrequired
- session_idstringrequired
- statusstringrequiredenum deleting, completed, failed
harness::triggers-changed
A session's trigger-binding set or fire count changed — refetch harness::triggers::list.
- parent_session_idstring
Only deliver sub-agent events whose parent is this session.
- session_idstring
Only deliver events for this session.
valueunknown
harness::turn-completed
A harness turn reached a terminal status (completed/cancelled/failed).
- parent_session_idstring
Only deliver sub-agent events whose parent is this session.
- session_idstring
Only deliver events for this session.
valueunknown
harness::turn-started
A harness turn began executing (first loop step).
- parent_session_idstring
Only deliver sub-agent events whose parent is this session.
- session_idstring
Only deliver events for this session.
valueunknown
timer
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`.
valueunknown
valueunknown