Skip to content
Sign in

workflow

v0.3.0

Deterministic, crash-resumable multi-agent workflow orchestrator over harness turns.

Install

bash
iii trigger compose::add worker=workflow@0.3.0

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

Functions11

workflow-result::submit

Function

Deliver this workflow node's result: call it once with {"result": <the JSON value your node's output schema requires>}. An error names what to fix: call it again. Once it is accepted, end your turn with one short line, not the JSON. Only a workflow node's own session can call it.

Request
  • caller_session_idstring

    Stamped from the calling session by the workflow's pre-call hook; a supplied value is overwritten.

  • resultunknownrequired

    The node's result: the JSON value its output schema requires.

Response
  • acceptedbooleanrequired
  • nodestringrequired

    The node uid the result was stored for.

workflow::inject-guidance

Function

Internal pre_generate hook: appends workflow orchestration guidance to the agent system prompt. The target of the worker's harness::hook::on-pre-generate observer; not called directly.

Request
  • generateobject
    • system_promptstring

      The system prompt assembled so far (base + any prior hook's mutation).

Response
  • mutationsobjectrequired

    The harness applies `system_prompt` only when the key is present (`HookRunner`'s `parse_mutations`), so `None` serializes to an empty object: the safe no-op that preserves the harness's assembled prompt.

    • system_promptstring

      Full replacement system prompt (base + appended guidance). The harness overwrites, it does not merge.

workflow::node-result

Function

Fetch the stored JSON result of one node: `node_uid` is the node id, '{node_id}#{i}' for a fanout item, or '{node_id}#it{k}' for loop pass k ('#it0' is the first pass; the bare id of a node in a loop is its last pass; workflow::status lists the done passes under `node_results`). Returns {result: null} when that node is not done.

Request
  • node_uidstringrequired

    The node id, `"{node_id}#{i}"` for a fanout item, or `"{node_id}#it{k}"` for loop pass k (`#it0` is the first pass); the bare id of a loop node or body node returns its last pass. `uid` is accepted as an alias.

  • run_idstringrequired

    The `run_id` returned by `workflow::start`.

Response
  • resultunknown

    The node's stored JSON result, or null if the node has not completed (or produced no stored result). Always serialized — even when absent it is an explicit `{ "result": null }`, so callers never special-case a missing key.

workflow::on-run-completed

Function

A workflow run reached a terminal state (completed, failed or cancelled); the event is {run_id, status, result, result_error, failed_nodes}. To wait for one run, observe it with args {run_id}: a run that already ended is replayed at once, and an unknown or collected run is refused with UNKNOWN_RUN. Without args it reports every run; `filters` on input.run_id or input.status narrow that but get no replay, so never wait for one run with filters. Delivery is at-least-once: dedup on run_id. A replay reaches a call target as the bare event, not the observed envelope. A notification ending in `…(truncated)`, or with an array ending in an `…N more entries omitted` string, is incomplete: call workflow::status once for the run. If the wake expires unfired, observe again the same way. Called by the workflow worker only.

Request
  • failed_nodesstring[]

    `node '<uid>': <error>` per node that failed in a completed run (a tolerated `on_error: continue` failure); omitted when none.

  • resultunknown

    The run's result; null unless it completed.

  • result_errorstring

    Why the run failed; null otherwise.

  • run_idstringrequired
  • statusstringrequiredenum running, awaiting_nodes, completed, failed, cancelled
Response
  • failed_nodesstring[]

    `node '<uid>': <error>` per node that failed in a completed run (a tolerated `on_error: continue` failure); omitted when none.

  • resultunknown

    The run's result; null unless it completed.

  • result_errorstring

    Why the run failed; null otherwise.

  • run_idstringrequired
  • statusstringrequiredenum running, awaiting_nodes, completed, failed, cancelled

workflow::stamp-reply

Function

Internal pre_call hook on workflow::start: stamps the caller's session and folder into the arguments. Always continues; not called directly.

Request
  • callany of
    any of (2)
    Variant 1
    • argumentsunknown
    • idstring
    Variant 2
    valuenull
  • metadataunknown

    Caller turn's `options.metadata`; its `fs_scope.root` is the caller's folder, stamped as `caller_fs_root`.

  • session_idstring
  • turn_idstring
Response
  • decisionstringrequired

    Always `"continue"` — this hook never denies or holds a call.

  • mutationsany of
    any of (2)
    Variant 1
    • argumentsunknownrequired

      The call's arguments, rewritten with the caller's stamped session and folder (any supplied `caller_fs_root` removed).

    Variant 2
    valuenull

workflow::status

Function

Return a snapshot of a workflow run (status, per-node state with unstarted nodes as pending, node_errors, node_results, phases, result, result_error), or null if not found. `details: true` adds node_details: label, phase, model, session, timings, live usage and harness status per node (at most 100 nodes). Each call costs a turn: do not poll in a loop; observe `workflow::on-run-completed` with args `{run_id}`, or pass `notify` to workflow::start, to be pushed the outcome.

Request
  • detailsboolean

    Also return `node_details` (at most 100 nodes: running first, then pending, failed, cancelled, done). Reads each node's usage and harness status live.

  • run_idstringrequired

    The `run_id` returned by `workflow::start`.

Response
any of (2)
Variant 1
  • created_atinteger· int64required
  • details_truncatedboolean

    `node_details` was cut at 100 nodes.

  • node_detailsobject

    Only with `details: true`: per-node detail keyed by node uid.

  • node_errorsobject

    Errors for nodes that failed, keyed by node uid — e.g. "no provider registered for model …". Present so a caller can diagnose a `failed` run without digging into stored state. Omitted when no node carries an error.

  • node_resultsobject

    Nodes that have a stored result: node uid → result_ref (its key in state). Fetch the value with `workflow::node-result { run_id, node_uid }`. Lets a caller recover partial work from a run that failed partway (the run-level `result` is only set on a Completed run). Omitted when empty.

  • nodesobjectrequired

    Per-node state keyed by node uid. Definition nodes that have not started are `pending`; an unexpanded fanout is listed once under its node id.

  • phasesobject

    Node uid counts per definition `phase` (`failed` includes cancelled); nodes without a phase are left out. Omitted when empty.

  • resultunknown
  • result_errorstring

    Run-level failure summary (set when `status == failed`).

  • run_idstringrequired
  • statusstringrequiredenum running, awaiting_nodes, completed, failed, cancelled
  • updated_atinteger· int64required
Variant 2
valuenull

workflow::stop

Function

Cancel a workflow run, cascading harness::stop to each live node session.

Request
  • run_idstringrequired
Response
  • stoppingbooleanrequired

workflow::sweep

Function

Internal cron sweep: reconcile AwaitingNodes runs and time out nodes past their deadline. Not called directly.

Request
  • expressionstring

    The expression that fired.

  • scheduled_timestring

    RFC 3339, UTC.

Response
  • okbooleanrequired
  • sweptinteger· uint64requiredmin 0

    Number of runs touched (reconciled and/or timed out) this sweep.

workflow::tick

Function

Internal durable workflow step.

Request
  • run_idstringrequired
  • stepinteger· uint64min 0
  • wakeboolean

    Sent by `workflow::wake`: runs even below the step floor.

Response
  • skippedbooleanrequired

workflow::validate-result

Function

Internal post_turn hook on workflow node sessions: a JSON node's turn that delivered no result with workflow-result::submit (and whose final message is not a valid result either) is denied, so the harness re-prompts it; a turn that ends with a wake armed passes. Not called directly.

Request
  • resultunknown

    The turn's result: the final message's text under a text contract.

  • session_idstring
Response
  • decisionstringrequired

    `continue`, or `deny` to re-prompt the turn.

  • reasonstring

workflow::wake

Function

Internal: on a harness::on-turn-completed event, wake the owning run with a tick. Best-effort latency optimization; the cron sweep is the durable backstop. Not called directly.

Request
  • activation_idstringrequired
  • callerany of
    any of (2)
    Variant 1
    • function_idstring

      The handler the call was made from; absent for a top-level call.

    • invocation_idstring
    • parentany of

      The caller of that handler, one level only.

      Show 2 nested
      any of (2)
      Variant 1
      • function_idstring
      • invocation_idstring
      • worker_idstring
      • worker_namestring
      Variant 2
      valuenull
    • worker_idstring
    • worker_namestring
    Variant 2
    valuenull
  • duration_msnumber· doublerequired
  • errorany of
    any of (2)
    Variant 1
    • codestringrequired
    • messagestringrequired
    Variant 2
    valuenull
  • function_idstringrequired
  • inputunknown
  • invocation_idstringrequired
  • metadataunknown
  • namespacestring
  • observer_idstringrequired
  • outputany of
    any of (2)
    Variant 1
    • session_idstring
    Variant 2
    valuenull
  • started_at_msinteger· uint64requiredmin 0
  • statusstringrequiredenum success, error
Response
  • wokebooleanrequired

Search the registry

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