Skip to content
Registry

harness

v1.2.0

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

Used in 1 kitagentautonomousharnessloop

Install

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

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

Functions19

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

  • messageall ofrequired

    The replacement message (string sugar or a full user/custom message).

    all of (1)
    Variant 1
    any of (2)
    Variant 1
    valuestring
    Variant 2
    any of (4)
    Variant 1
    • contentone of[]required
      Show 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • 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 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • 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 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • contentunknown[]required
      • function_call_idstringrequired
      • is_errorboolean
      • typestringrequiredenum function_result
    • custom_typestringrequired
    • detailsunknown
    • displaystring
    • rolestringrequiredenum custom
    • timestampinteger· int64required
    Variant 4
    • contentone of[]required
      Show 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • contentunknown[]required
      • function_call_idstringrequired
      • is_errorboolean
      • typestringrequiredenum function_result
    • rolestringrequiredenum user
    • timestampinteger· int64required
  • 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
  • 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 (6)
    Variant 1
    • textstringrequired
    • typestringrequiredenum text
    Variant 2
    • datastringrequired
    • mimestringrequired
    • typestringrequiredenum image
    Variant 3
    • signaturestring
    • textstringrequired
    • typestringrequiredenum thinking
    Variant 4
    • datastringrequired
    • typestringrequiredenum redacted_thinking
    Variant 5
    • argumentsunknownrequired
    • function_idstringrequired
    • idstringrequired
    • typestringrequiredenum function_call
    Variant 6
    • 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 (6)
    Variant 1
    • textstringrequired
    • typestringrequiredenum text
    Variant 2
    • datastringrequired
    • mimestringrequired
    • typestringrequiredenum image
    Variant 3
    • signaturestring
    • textstringrequired
    • typestringrequiredenum thinking
    Variant 4
    • datastringrequired
    • typestringrequiredenum redacted_thinking
    Variant 5
    • argumentsunknownrequired
    • function_idstringrequired
    • idstringrequired
    • typestringrequiredenum function_call
    Variant 6
    • 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::notify_agent

Function

Internal: the shared subscription fire handler — injects a notification into the owning session (resolved from the local subscription registry). Not called directly.

Request
valuenull
Response
  • okbooleanrequired

harness::on-config-change

Function

Internal: hot-reload harness from the authoritative configuration when it changes — re-binds the cron pending-sweep on a sweep_expression change and swaps the per-call tuning snapshot otherwise.

Request
  • idstring

    Configuration id that changed (advisory; the handler re-fetches).

Response
  • okbooleanrequired

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::react

Function

Internal trigger bridge: reshape a subscribed event into a harness::spawn (a sub-agent), optionally behind a join barrier. Not called directly — THE way to spin up sub-agents on events and callbacks: bind it via engine::register_trigger with the sub-agent spec in `metadata`.

Request
valuenull
Response
  • child_session_idstring

    The spawned sub-agent's child session id, when spawn returned one.

  • notestring

    Why nothing spawned (missing spec, join not yet complete, already fired, error). Present iff `!spawned`.

  • spawnedbooleanrequired

    Whether a `harness::spawn` was dispatched this call.

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.

  • messageall ofrequired

    The incoming message; a string is sugar for a user text message. The role must be `user` or `custom`.

    all of (1)
    Variant 1
    any of (2)
    Variant 1
    valuestring
    Variant 2
    any of (4)
    Variant 1
    • contentone of[]required
      Show 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • 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 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • 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 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • contentunknown[]required
      • function_call_idstringrequired
      • is_errorboolean
      • typestringrequiredenum function_result
    • custom_typestringrequired
    • detailsunknown
    • displaystring
    • rolestringrequiredenum custom
    • timestampinteger· int64required
    Variant 4
    • contentone of[]required
      Show 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • contentunknown[]required
      • function_call_idstringrequired
      • is_errorboolean
      • typestringrequiredenum function_result
    • rolestringrequiredenum user
    • timestampinteger· int64required
  • modelstringrequired
  • optionsany of
    any of (2)
    Variant 1
    • functionsany of

      The fail-closed dispatch policy; omit to deny every call.

      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_turnsinteger· uint32min 0
    • metadataunknown

      Tracing passthrough.

    • modeany of
      Show 2 nested
      any of (2)
      Variant 1
      valuestringenum plan, ask, agent
      Variant 2
      valuenull
    • 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
    • system_promptstring
    • system_prompt_strategyall of

      How `system_prompt` combines with the built-in prompt: `override` replaces it; `enrich` (default) appends to it.

      Show 1 nested
      all of (1)
      Variant 1
      one of (2)
      Variant 1
      valuestringenum override
      Variant 2
      valuestringenum enrich
    • thinking_levelany of
      Show 2 nested
      any of (2)
      Variant 1
      valuestringenum minimal, low, medium, high, xhigh
      Variant 2
      valuenull
    Variant 2
    valuenull
  • providerstring
  • sessionany of

    Applied when this send creates/ensures the session.

    any of (2)
    Variant 1
    • 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.

  • session_idstringrequired
  • turn_idstringrequired

harness::spawn

Function

Spawn a sub-agent in a child session; the model-facing pending trigger — parks the calling turn until the child resolves. Call it directly ONLY when the current turn needs the child's answer; for callbacks, follow-up stages, and fan-in, register the reaction via engine::register_trigger -> harness::react instead.

Request
  • modelstring
  • optionsany of
    any of (2)
    Variant 1
    • filesystem_rootstring

      Absolute filesystem root for the child turn (e.g. an isolated `worktree::create` checkout), written to the child's `metadata.fs_scope.root`. When set it overrides the inherited scope for this child; when absent the child inherits its direct parent's root unchanged.

    • functionsany of

      Intersected with the parent policy — narrow, never escalate.

      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_turnsinteger· uint32min 0

      Capped at the parent's remaining turn budget.

    • modeany of
      Show 2 nested
      any of (2)
      Variant 1
      valuestringenum plan, ask, agent
      Variant 2
      valuenull
    • 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
    • pending_timeout_msinteger· uint64min 0

      Parent-side wait guard for this child.

    • system_promptstring
    • system_prompt_strategyall of

      How `system_prompt` combines with the built-in prompt: `override` replaces it; `enrich` (default) appends to it.

      Show 1 nested
      all of (1)
      Variant 1
      one of (2)
      Variant 1
      valuestringenum override
      Variant 2
      valuestringenum enrich
    • thinking_levelany of
      Show 2 nested
      any of (2)
      Variant 1
      valuestringenum minimal, low, medium, high, xhigh
      Variant 2
      valuenull
    Variant 2
    valuenull
  • parent_session_idstring

    Display-only parent for the console session tree, used when there is no live parent turn (e.g. a trigger-fired spawn from `harness::react`). Writes `SessionMeta.metadata.parent_session_id` so the console nests this child; it does NOT grant policy inheritance or parent-call resolution. Ignored when the dispatcher injects a real parent link (an in-turn spawn).

  • providerstring
  • reactive_depthinteger· uint32min 0

    Stamped by `harness::react` (not caller-supplied): reactive-chain depth, echoed on this turn's `turn-completed` event so react can cap runaway chains at `MAX_REACTIVE_DEPTH`.

  • session_idstring

    Spawn into this session, creating it if it does not exist (e.g. a fork, or a pre-chosen id to filter `turn-completed` subscriptions on); default: create fresh.

  • spawned_by_subscription_idstring

    Stamped by `harness::react` (not caller-supplied): the subscription that spawned this turn. Its completion event is never delivered back to that same subscription (self-edge loop breaker).

  • taskall ofrequired

    The child's goal — its opening user message.

    all of (1)
    Variant 1
    any of (2)
    Variant 1
    valuestring
    Variant 2
    any of (4)
    Variant 1
    • contentone of[]required
      Show 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • 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 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • 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 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • contentunknown[]required
      • function_call_idstringrequired
      • is_errorboolean
      • typestringrequiredenum function_result
    • custom_typestringrequired
    • detailsunknown
    • displaystring
    • rolestringrequiredenum custom
    • timestampinteger· int64required
    Variant 4
    • contentone of[]required
      Show 6 nested
      one of (6)
      Variant 1
      • textstringrequired
      • typestringrequiredenum text
      Variant 2
      • datastringrequired
      • mimestringrequired
      • typestringrequiredenum image
      Variant 3
      • signaturestring
      • textstringrequired
      • typestringrequiredenum thinking
      Variant 4
      • datastringrequired
      • typestringrequiredenum redacted_thinking
      Variant 5
      • argumentsunknownrequired
      • function_idstringrequired
      • idstringrequired
      • typestringrequiredenum function_call
      Variant 6
      • contentunknown[]required
      • function_call_idstringrequired
      • is_errorboolean
      • typestringrequiredenum function_result
    • rolestringrequiredenum user
    • timestampinteger· int64required
Response
  • child_session_idstringrequired
  • child_turn_idstringrequired

harness::status

Function

Read the current turn status for a session.

Request
  • session_idstringrequired
Response
any of (2)
Variant 1
  • childrenobject[]required
    • function_call_idstringrequired
    • session_idstringrequired
    • turn_idstringrequired
  • depthinteger· uint32requiredmin 0
  • max_turnsinteger· uint32requiredmin 0
  • pending_function_callsstring[]required
  • queuedobject[]

    Messages queued while a step streams, in arrival order; they land in the transcript when the stream ends.

    • entry_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 6 nested
        one of (6)
        Variant 1
        • textstringrequired
        • typestringrequiredenum text
        Variant 2
        • datastringrequired
        • mimestringrequired
        • typestringrequiredenum image
        Variant 3
        • signaturestring
        • textstringrequired
        • typestringrequiredenum thinking
        Variant 4
        • datastringrequired
        • typestringrequiredenum redacted_thinking
        Variant 5
        • argumentsunknownrequired
        • function_idstringrequired
        • idstringrequired
        • typestringrequiredenum function_call
        Variant 6
        • 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 6 nested
        one of (6)
        Variant 1
        • textstringrequired
        • typestringrequiredenum text
        Variant 2
        • datastringrequired
        • mimestringrequired
        • typestringrequiredenum image
        Variant 3
        • signaturestring
        • textstringrequired
        • typestringrequiredenum thinking
        Variant 4
        • datastringrequired
        • typestringrequiredenum redacted_thinking
        Variant 5
        • argumentsunknownrequired
        • function_idstringrequired
        • idstringrequired
        • typestringrequiredenum function_call
        Variant 6
        • 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 6 nested
        one of (6)
        Variant 1
        • textstringrequired
        • typestringrequiredenum text
        Variant 2
        • datastringrequired
        • mimestringrequired
        • typestringrequiredenum image
        Variant 3
        • signaturestring
        • textstringrequired
        • typestringrequiredenum thinking
        Variant 4
        • datastringrequired
        • typestringrequiredenum redacted_thinking
        Variant 5
        • argumentsunknownrequired
        • function_idstringrequired
        • idstringrequired
        • typestringrequiredenum function_call
        Variant 6
        • contentunknown[]required
        • function_call_idstringrequired
        • is_errorboolean
        • typestringrequiredenum function_result
      • custom_typestringrequired
      • detailsunknown
      • displaystring
      • rolestringrequiredenum custom
      • timestampinteger· int64required
      Variant 4
      • contentone of[]required
        Show 6 nested
        one of (6)
        Variant 1
        • textstringrequired
        • typestringrequiredenum text
        Variant 2
        • datastringrequired
        • mimestringrequired
        • typestringrequiredenum image
        Variant 3
        • signaturestring
        • textstringrequired
        • typestringrequiredenum thinking
        Variant 4
        • datastringrequired
        • typestringrequiredenum redacted_thinking
        Variant 5
        • argumentsunknownrequired
        • function_idstringrequired
        • idstringrequired
        • typestringrequiredenum function_call
        Variant 6
        • 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
  • turn_countinteger· uint32requiredmin 0
  • turn_idstring
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 so a parked turn never wedges. Not called directly.

Request
  • scheduled_atinteger· int64
Response
  • okbooleanrequired
  • resolvedinteger· uint64requiredmin 0

    Number of expired pending calls resolved this sweep.

harness::turn

Function

Internal durable loop step (enqueued onto the default queue); not called directly.

Request
  • depthinteger· uint32min 0

    Sub-agent depth carried from the turn record (0 = top-level), so the step can stamp the `iii.tag.kind` baggage (`harness.turn` / `harness.subagent`) before any state read. Defaults to 0 so stale in-flight payloads from before this field existed still classify as top-level turns.

  • message_previewstring

    Preview carried from the turn record so the step can stamp the `iii.tag.message` baggage before any state read.

  • session_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::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.

Triggers8

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_*, fail_open for post_*).

  • priorityinteger· int64

    Chain order: ascending, ties broken by function_id (default 0).

  • 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_*, fail_open for post_*).

  • priorityinteger· int64

    Chain order: ascending, ties broken by function_id (default 0).

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

Invocation
  • functionsstring[]

    pre/post_trigger only: target function_id globs to consult on.

  • on_errorstring

    Failure policy (default fail_closed for pre_*, fail_open for post_*).

  • priorityinteger· int64

    Chain order: ascending, ties broken by function_id (default 0).

  • 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_*, fail_open for post_*).

  • priorityinteger· int64

    Chain order: ascending, ties broken by function_id (default 0).

  • 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_*, fail_open for post_*).

  • priorityinteger· int64

    Chain order: ascending, ties broken by function_id (default 0).

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

Search the registry

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