skip to content
iii / worker
$worker

harness

v1.1.8

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

iiiverified
406 installs112 in 7d28 today
install
$iii worker add harness@1.1.8
binaryagentharnessloopautonomous
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64 · x86
16functions7triggers1skills14depsv1.1.8version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

16

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

      … expand 2 nested
      any of (2)
      variant 1
      • allowstring[]
      • denystring[]
      • exposeall of
        … expand 1 nested
        all of (1)
        variant 1
        valuestringenum: agent_trigger, native
      variant 2
      valuenull
    • max_turnsinteger· uint32min 0
    • metadataunknown

      Tracing passthrough.

    • modeany of
      … expand 2 nested
      any of (2)
      variant 1
      valuestringenum: plan, ask, agent
      variant 2
      valuenull
    • outputany of

      The turn's deliverable; default `{ type: "text" }`.

      … expand 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.

      … expand 1 nested
      all of (1)
      variant 1
      one of (2)
      variant 1
      valuestringenum: override
      variant 2
      valuestringenum: enrich
    • thinking_levelany of
      … expand 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 — 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.

      … expand 2 nested
      any of (2)
      variant 1
      • allowstring[]
      • denystring[]
      • exposeall of
        … expand 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
      … expand 2 nested
      any of (2)
      variant 1
      valuestringenum: plan, ask, agent
      variant 2
      valuenull
    • outputany of

      The child's deliverable: text / json / json+schema.

      … expand 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.

      … expand 1 nested
      all of (1)
      variant 1
      one of (2)
      variant 1
      valuestringenum: override
      variant 2
      valuestringenum: enrich
    • thinking_levelany of
      … expand 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
      … expand 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
      … expand 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
      … expand 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
      … expand 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
      … expand 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
      … expand 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
  • 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.

triggers

7

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