Skip to content
Registry

harness

v1.8.47

Thin durable turn loop that wires session-manager, context-manager, and llm-router into an agent loop; spawns sub-agents as child sessions.

license: Apache-2.0Used in 1 kitagentautonomousharnessloop

Install

bash
iii trigger compose::add worker=harness@1.8.47

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions33

harness::ask

Function

Ask the user for a decision between discrete options: 1-4 questions, 2-4 options each; the UI adds a free-text "Other" choice, so do not include one. The questions are shown as a clickable card in the chat, your turn ends, and the answer arrives as the user's next message, so do not repeat the questions in text. Not available to sub-agents or structured-output turns.

Request
  • questionsobject[]required1…4 items

    1-4 questions shown together on one card; the answer arrives as the user's next message, one line per question.

    • headerstringrequired1…16 chars

      Short chip label such as `Approach`, 1-16 characters; prefixes the answer line (`Approach: <label>`).

    • multi_selectboolean

      Let the user pick several options (checkboxes) instead of one.

    • optionsobject[]required2…4 items

      2-4 discrete choices; do not add an "Other" option, the UI adds a free-text one.

      • descriptionstring

        Optional one-line explanation shown under the label.

      • labelstringrequired1…80 chars

        The choice as the user sees and sends it, 1-80 characters, unique within its question.

    • questionstringrequiredmin 1 chars

      The full question text shown above the options.

Response
  • question_idstringrequired

    The function-call id of this ask.

  • questionsobject[]required

    The questions as shown, in request order.

    • headerstringrequired1…16 chars

      Short chip label such as `Approach`, 1-16 characters; prefixes the answer line (`Approach: <label>`).

    • multi_selectboolean

      Let the user pick several options (checkboxes) instead of one.

    • optionsobject[]required2…4 items

      2-4 discrete choices; do not add an "Other" option, the UI adds a free-text one.

      • descriptionstring

        Optional one-line explanation shown under the label.

      • labelstringrequired1…80 chars

        The choice as the user sees and sends it, 1-80 characters, unique within its question.

    • questionstringrequiredmin 1 chars

      The full question text shown above the options.

  • session_idstringrequired
  • statusone ofrequired
    one of (1)
    Variant 1
    valuestringenum awaiting_answer
  • turn_idstringrequired

    The turn that asked; once the session's current turn differs, the question has been answered.

harness::context-policy

Function

Return the Harness context-pruning policy for a destination model without making a model request.

Request
  • modelstringrequired
Response
  • allow_prunebooleanrequired

    Whether aged function results may be pruned for this model.

harness::delete-session-tree

Function

Durably cancel and delete only the selected session subtree; returns an operation snapshot.

Request
  • session_idstringrequired
Response
  • 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

Function

Internal queued subtree deletion continuation.

Request
  • operation_idstringrequired
Response
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

Function

Read a durable session subtree deletion snapshot, or null if unknown.

Request
  • operation_idstringrequired
Response
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

Function

Internal control-plane: edit a still-parked queued message in place by entry_id, preserving its queue position.

Request
  • entry_idstringrequired

    The queued row to edit (its client-visible `entry_id`).

  • messagestringrequired

    The replacement user message text.

  • session_idstringrequired
Response
  • updatedbooleanrequired

    False when no still-parked row matched — already drained or unknown.

harness::filesystem::grant

Function

Internal control-plane: grant a session access to an additional filesystem root.

Request
  • rootstringrequired
  • session_idstringrequired
Response
  • rootsstring[]required
  • session_idstringrequired

harness::filesystem::grants

Function

Internal control-plane: list additional filesystem roots granted to a session.

Request
  • session_idstringrequired
Response
  • rootsstring[]required
  • session_idstringrequired

harness::filesystem::info

Function

Internal control-plane: the default working-directory root new sessions are scoped to.

Request
Empty object
Response
  • 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 1
    valuestringenum 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

Function

Internal control-plane: revoke a session's access to an additional filesystem root.

Request
  • rootstringrequired
  • session_idstringrequired
Response
  • rootsstring[]required
  • session_idstringrequired

harness::function::resolve

Function

Internal: settle a pending call's result (or release a held call) and resume the parked turn.

Request
  • 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 2
    valuenull
  • function_call_idstringrequired
  • is_errorboolean
  • session_idstringrequired
  • turn_idstringrequired
Response
  • 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

Function

Internal: invoke one iii function (unwrapped from agent_trigger), enforce the dispatch policy, and capture the normalised result — or report it pending.

Request
  • callobjectrequired
    • argumentsunknownrequired
    • function_idstringrequired

      The iii function to invoke (already unwrapped from `agent_trigger`).

    • idstringrequired

      function_call id, echoed into the result.

  • session_idstringrequired
Response
any of (2)
Variant 1
  • contentone of[]required
    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
  • 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

Function

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.

Request
one of (2)
Variant 1
Empty object
Variant 2
Empty object
Response
  • 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 nested
        • hook_guidanceinteger· uint64min 0
        • messagesobjectrequired

          Estimated tokens of the assembled window's messages, by role.

          Show 4 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
      • prefix_divergencesobject[]

        Already-sent rows this session's requests rewrote, newest last (at most [`MAX_PREFIX_DIVERGENCES`]), carried from step to step.

        Show 9 nested
        • cache_readinteger· uint64min 0

          `usage.cache_read` of the rewriting request: what the provider still reused.

        • call_idstring
        • causestring

          What rewrote the row, as far as the harness can tell: `prune` (context-manager pruned or reduced function results to fit the budget that step) or `system_prompt` (row 0: a compaction summary or a prompt change).

        • indexinteger· uint64min 0

          First row (0 = system prompt, then one per message) that differs from the session's previous request. Absent when only the provider's wire mapping changed.

        • prev_leninteger· uint64min 0

          Rows the previous request carried.

        • provider_notestring

          The provider's own wire-level finding, cause included, when it reported one (a final-message warning starting with [`PROVIDER_PREFIX_NOTE`]).

        • rolestring
        • stepinteger· uint64requiredmin 0
        • turn_idstringrequired
      • 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 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 2
        valuenull
      Variant 2
      valuenull
    • 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 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 2
    valuenull

harness::on-functions-change

Function

Internal: refresh the cached function-registry snapshot when functions are registered/unregistered (driven by the engine::functions-available trigger).

Request
  • eventstring

    Engine event tag (advisory; the handler re-fetches the full list).

Response
  • okbooleanrequired

harness::on-session-deleted

Function

Internal: drop a deleted session's ephemeral subscriptions. Not called directly.

Request
  • session_idstringrequired
Response
  • okbooleanrequired
  • removedinteger· uint64requiredmin 0

harness::on-skills-change

Function

Internal: refresh the cached model-invocable skill catalog.

Request
  • opstring
Response
  • okbooleanrequired

harness::projects::delete

Function

Internal control-plane: remove a project directory from the durable catalog.

Request
  • pathstringrequired
Response
  • deletedbooleanrequired

harness::projects::list

Function

Internal control-plane: list the operator's durable project catalog.

Request
Empty object
Response
  • projectsobject[]required
    • last_used_atinteger· int64required
    • namestringrequired
    • pathstringrequired

harness::projects::upsert

Function

Internal control-plane: remember, touch, or rename a project directory.

Request
  • 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
Response
  • projectobjectrequired
    • last_used_atinteger· int64required
    • namestringrequired
    • pathstringrequired

harness::send

Function

Entry point: ensure the session, persist the incoming message, and kick off a turn; returns fast (or merges into a running turn).

Request
  • 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 of
    any 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 nested
      any of (2)
      Variant 1
      • allowstring[]
      • denystring[]
      • exposeall of
        Show 1 nested
        all of (1)
        Variant 1
        valuestringenum agent_trigger, native
      Variant 2
      valuenull
    • 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 nested
      any of (2)
      Variant 1
      one of (2)
      Variant 1
      • typestringrequiredenum text
      Variant 2
      • schemaunknown
      • typestringrequiredenum json
      Variant 2
      valuenull
    • provider_optionsobject

      Provider-native per-call options, namespaced by provider id.

    • reasoningany of

      Ask the harness to pick the effort from the model's catalog row instead of naming one: `lowest` is the model's lowest reasoning effort (never `off`), or the provider default when the model offers no effort choices. Exclusive with `thinking_level` and `provider_options`; the choice is returned as `reasoning` on the send response.

      Show 2 nested
      any of (2)
      Variant 1
      valuestringenum lowest
      Variant 2
      valuenull
    • 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 nested
      any of (2)
      Variant 1
      one of (3)
      Variant 1
      valuestringenum override
      Variant 2
      valuestringenum enrich
      Variant 3
      valuestringenum disabled
      Variant 2
      valuenull
    • 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 nested
      any of (2)
      Variant 1
      one of (2)
      Variant 1
      valuestringenum minimal, low, medium, high, xhigh
      Variant 2
      valuestringenum off
      Variant 2
      valuenull
    Variant 2
    valuenull
  • 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 2
    valuenull
  • session_idstring

    Omit to create a new session.

Response
  • 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.

  • reasoningany of

    What `options.reasoning` resolved to; absent when the send named none.

    any of (2)
    Variant 1
    • reasoning_effortstring
    • thinking_levelany of
      Show 2 nested
      any of (2)
      Variant 1
      one of (2)
      Variant 1
      valuestringenum minimal, low, medium, high, xhigh
      Variant 2
      valuestringenum off
      Variant 2
      valuenull
    Variant 2
    valuenull
  • session_idstringrequired
  • turn_idstringrequired

harness::session-tree

Function

Read the durable root-and-descendant session tree for one harness run.

Request
  • root_session_idstringrequired
Response
  • completebooleanrequired
  • root_session_idstringrequired
  • sessionsobject[]required
    • depthinteger· uint32requiredmin 0
    • parent_session_idstring
    • parent_turn_idstring
    • session_idstringrequired

harness::spawn

Function

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.

Request
  • 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 nested
      any of (2)
      Variant 1
      valuestringenum neutral, blue, purple, teal, green, amber, …
      Variant 2
      valuenull
    • iconany of
      Show 2 nested
      any of (2)
      Variant 1
      valuestringenum agent, code, search, terminal, database, test, …
      Variant 2
      valuenull
    • namestringrequired1…48 chars

      Short functional name such as `Frontend`, 1-48 characters after trimming.

    Variant 2
    valuenull
  • modelstring
  • optionsany of
    any 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 nested
      any of (2)
      Variant 1
      • allowstring[]
      • denystring[]
      • exposeall of
        Show 1 nested
        all of (1)
        Variant 1
        valuestringenum agent_trigger, native
      Variant 2
      valuenull
    • 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 nested
      any of (2)
      Variant 1
      one of (2)
      Variant 1
      • typestringrequiredenum text
      Variant 2
      • schemaunknown
      • typestringrequiredenum json
      Variant 2
      valuenull
    • 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 nested
      all of (1)
      Variant 1
      one of (3)
      Variant 1
      valuestringenum override
      Variant 2
      valuestringenum enrich
      Variant 3
      valuestringenum disabled
    • thinking_levelany of
      Show 2 nested
      any of (2)
      Variant 1
      one of (2)
      Variant 1
      valuestringenum minimal, low, medium, high, xhigh
      Variant 2
      valuestringenum off
      Variant 2
      valuenull
    Variant 2
    valuenull
  • 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).

Response
  • 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

Function

Read a session's current turn. Returns a lean summary by default; pass verbose: true for the full runtime report and untruncated result.

Request
  • session_idstringrequired
  • verboseboolean

    Include the full runtime report and unmodified result.

Response
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 nested
      • hook_guidanceinteger· uint64min 0
      • messagesobjectrequired

        Estimated tokens of the assembled window's messages, by role.

        Show 4 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
    • prefix_divergencesobject[]

      Already-sent rows this session's requests rewrote, newest last (at most [`MAX_PREFIX_DIVERGENCES`]), carried from step to step.

      Show 9 nested
      • cache_readinteger· uint64min 0

        `usage.cache_read` of the rewriting request: what the provider still reused.

      • call_idstring
      • causestring

        What rewrote the row, as far as the harness can tell: `prune` (context-manager pruned or reduced function results to fit the budget that step) or `system_prompt` (row 0: a compaction summary or a prompt change).

      • indexinteger· uint64min 0

        First row (0 = system prompt, then one per message) that differs from the session's previous request. Absent when only the provider's wire mapping changed.

      • prev_leninteger· uint64min 0

        Rows the previous request carried.

      • provider_notestring

        The provider's own wire-level finding, cause included, when it reported one (a final-message warning starting with [`PROVIDER_PREFIX_NOTE`]).

      • rolestring
      • stepinteger· uint64requiredmin 0
      • turn_idstringrequired
    • 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 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 2
      valuenull
    Variant 2
    valuenull
  • 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 nested
      any of (4)
      Variant 1
      • contentone of[]required
        Show 7 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 nested
        any of (2)
        Variant 1
        valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent
        Variant 2
        valuenull
      • error_messagestring
      • modelstringrequired
      • native_stop_reasonstring
      • providerstringrequired
      • rolestringrequiredenum assistant
      • stop_reasonstringrequiredenum end, length, function_call, aborted, error
      • timestampinteger· int64required
      • usageany of
        Show 2 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 2
        valuenull
      • warningsstring[]
      Variant 2
      • contentone of[]required
        Show 7 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 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 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

Function

Request cancellation of an in-flight turn (cascades to spawned children).

Request
  • session_idstringrequired
  • turn_idstring

    Omit to stop the current turn.

Response
  • stoppingbooleanrequired

harness::sweep-pending

Function

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; then move finished turn records' inline prompts to shared bodies and delete unused bodies. Not called directly.

Request
  • scheduled_atinteger· int64
Response
  • convertedinteger· uint64min 0

    Finished turn records rewritten with prompt refs.

  • okbooleanrequired
  • prompts_collectedinteger· uint64min 0

    Unreferenced prompt bodies deleted.

  • 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

Function

Preview the system prompt layers a session will use without making a model request.

Request
  • default_onlyboolean

    Return only the built-in default layer, without session, runtime, registry, or hook layers.

  • filesystem_rootstring
  • selected_promptany of
    any of (2)
    Variant 1
    • bodystringrequired
    • namestringrequired
    • strategyall of
      Show 1 nested
      all of (1)
      Variant 1
      one of (3)
      Variant 1
      valuestringenum override
      Variant 2
      valuestringenum enrich
      Variant 3
      valuestringenum disabled
    Variant 2
    valuenull
  • session_idstringrequired
Response
  • partsobject[]required
    • bodystringrequired
    • kindstringrequiredenum built_in, selected, skills, runtime, injected
    • namestring

harness::teardown

Function

Internal control-plane: remove trigger bindings owned by a root harness session tree.

Request
  • root_session_idstringrequired
Response
  • removedinteger· uint64requiredmin 0

harness::trigger::deliver

Function

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.

Request
valuenull
Response
  • 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

Function

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`.

Request
  • session_idstring

    Owner session whose bindings to list; in-turn calls may omit it (the calling session is injected).

Response
  • 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

Function

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.

Request
  • 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).

Response
  • removedbooleanrequired

    False when no record existed (already retired) — honest, not an error.

harness::turn

Function

Internal durable loop step (enqueued onto the harness-turn queue); not called directly.

Request
  • 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
Response
  • 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

Function

Serve the harness worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).

Request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

harness::unqueue

Function

Internal control-plane: remove a still-parked queued message by entry_id (the console's edit-queued path).

Request
  • 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
Response
  • removedbooleanrequired

    False when no still-parked row matched — already drained or unknown.

Triggers13

harness::hook::post-generate

Trigger

Synchronous hook: after the final assistant message update. Observe only.

Invocation
  • 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).

Return
valueunknown

harness::hook::post-trigger

Trigger

Synchronous hook: after the target returns, before the result is appended. May rewrite content/details/is_error.

Invocation
  • 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).

Return
valueunknown

harness::hook::post-turn

Trigger

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.

Invocation
  • 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).

Return
valueunknown

harness::hook::pre-generate

Trigger

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.

Invocation
  • 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).

Return
valueunknown

harness::hook::pre-trigger

Trigger

Synchronous hook: after the allow/deny policy passes, before the target is invoked. May deny, hold, or rewrite arguments.

Invocation
  • 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).

Return
valueunknown

harness::hook::pre-turn

Trigger

Synchronous hook: first step of a turn, before any model spend. May veto.

Invocation
  • 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).

Return
valueunknown

harness::message-queued

Trigger

A message parked in a session's server-side queue while its turn streams.

Invocation
  • parent_session_idstring

    Only deliver sub-agent events whose parent is this session.

  • session_idstring

    Only deliver events for this session.

Return
valueunknown

harness::ready

Trigger

The harness completed boot and can accept turns.

Invocation
Empty object
Return
valueunknown

harness::session-tree-deletion

Trigger

A subtree deletion changed status; subscribe before requesting deletion and recover once by operation_id.

Invocation
  • operation_idstring
  • session_idstring
Return
  • 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

Trigger

A session's trigger-binding set or fire count changed — refetch harness::triggers::list.

Invocation
  • parent_session_idstring

    Only deliver sub-agent events whose parent is this session.

  • session_idstring

    Only deliver events for this session.

Return
valueunknown

harness::turn-completed

Trigger

A harness turn reached a terminal status (completed/cancelled/failed).

Invocation
  • parent_session_idstring

    Only deliver sub-agent events whose parent is this session.

  • session_idstring

    Only deliver events for this session.

Return
valueunknown

harness::turn-started

Trigger

A harness turn began executing (first loop step).

Invocation
  • parent_session_idstring

    Only deliver sub-agent events whose parent is this session.

  • session_idstring

    Only deliver events for this session.

Return
valueunknown

timer

Trigger

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`.

Invocation
valueunknown
Return
valueunknown

Search the registry

Find workers, kits and executables, or jump to a page.