$worker

harness

Name: harness
Author: iii

v1.0.3

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

iiiverified

405 installs111 in 7d27 today

install

$iii worker add harness@1.0.3

binaryagent harness loop autonomous

macOS: arm64 · x64
Linux: arm64 · armv7 · x64
Windows: arm64 · x64 · x86

9functions 7triggers 1skills 13deps v1.0.3version

repoiii-hq/workers

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

functions

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::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::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 nestedcollapse
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 nestedcollapse
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 nestedcollapse
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 nestedcollapse
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 nestedcollapse
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 nestedcollapse
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 nestedcollapse
any of (2)
variant 1
allowstring[]
denystring[]
exposeall of
… expand 1 nestedcollapse
all of (1)
variant 1
valuestringenum: agent_trigger, native
variant 2
valuenull
max_turnsinteger· uint32min 0
metadataunknown
Tracing passthrough.
modeany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: plan, ask, agent
variant 2
valuenull
outputany of
The turn's deliverable; default `{ type: "text" }`.
… expand 2 nestedcollapse
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 nestedcollapse
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: override
variant 2
valuestringenum: enrich
thinking_levelany of
… expand 2 nestedcollapse
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.
… expand 2 nestedcollapse
any of (2)
variant 1
allowstring[]
denystring[]
exposeall of
… expand 1 nestedcollapse
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 nestedcollapse
any of (2)
variant 1
valuestringenum: plan, ask, agent
variant 2
valuenull
outputany of
The child's deliverable: text / json / json+schema.
… expand 2 nestedcollapse
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 nestedcollapse
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: override
variant 2
valuestringenum: enrich
thinking_levelany of
… expand 2 nestedcollapse
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
… expand 6 nestedcollapse
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 nestedcollapse
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 nestedcollapse
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 nestedcollapse
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 nestedcollapse
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 nestedcollapse
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.

triggers

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