Skip to content
Registry

harness

v1.1.1

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

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

Functions12

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

  • session_idstringrequired
  • turn_idstringrequired

harness::spawn

Function

Spawn a sub-agent in a child session; the model-facing pending trigger.

Request
  • modelstring
  • optionsany of
    any of (2)
    Variant 1
    • 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
  • providerstring
  • session_idstring

    Spawn into an existing session (e.g. a fork); default: create fresh.

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

Triggers7

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