Skip to content
Sign in

workflow

v0.3.5

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

Install

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

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

Functions14

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. The node is finished once the turn ends: submit last. 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::list

Function

List the workflow runs started from `caller_session_id` or any session in its tree (sub-agents included), newest first: {runs: [{run_id, status, title?, created_at, updated_at}]}. An agent's call lists its own session's runs. Inspect one with workflow::status.

Request
  • caller_session_idstringrequired

    The session whose runs are listed; the stamp hook overwrites it with an agent caller's own session.

Response
  • runsobject[]required

    Newest `created_at` first.

    • created_atinteger· int64required
    • run_idstringrequired
    • statusstringrequiredenum running, awaiting_nodes, completed, failed, cancelled
    • titlestring

      The run's display title, when it has one.

    • updated_atinteger· int64required

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, workflow::list and workflow-result::submit: stamps the caller's session and folder into the arguments. Always continues; not called directly.

Request
  • callany of
    any of (2)
    Variant 1
    • argumentsunknown
    • descriptionstring

      The `agent_call` wrapper's description of the call, when given.

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

Function

Run a multi-agent workflow and return {run_id, next} immediately. Declarative DAG: fan-out, barrier/join, durable, crash-resumable. Shape: {"nodes":{"a":{"task":"…"},"b":{"task":"…","reads":"a"}}}; a node omits `model` to run on your model. To get the result make the `harness::observe` call that `next` gives and END YOUR TURN — it arrives as a `[notification]` when the run ends; workers pass `notify`. Never poll workflow::status in a loop.

Request
  • caller_fs_rootstring

    Caller's folder. On a call from an agent turn the `workflow::stamp-reply` hook replaces it with the turn's `metadata.fs_scope.root`; the harness refuses `workflow::start` as a binding target and `fp` as a pipe step, since both skip that hook. Every node session runs in it. Omit it to use the harness default folder.

  • caller_session_idstring

    Orchestrator session, stamped by the `workflow::stamp-reply` hook from the caller's turn; never trusted from the agent.

  • default_functionsunknown

    Dispatch policy inherited by every node that omits `functions` (same shape); when unset those nodes get everything except `workflow::*`, `configuration::*`, `approval::*`, `harness::hook::*` and `harness::send`.

  • idempotency_keystring

    Dedupe key; a repeated key returns the original `run_id` instead of launching a duplicate run.

  • inputunknown

    Any JSON value. Every node without `reads` or `fanout` receives it.

  • max_concurrencyinteger· uint32min 0

    At most this many node sessions live at once (running, or reserved for a send); further ready nodes wait for a slot. At least 1; unset means no cap.

  • nodesobjectrequired

    One sub-agent session per node, keyed by node id; an id must not contain `#`, `.` or `/`.

  • notifyany of

    Completion callback called once when the run reaches a terminal state, instead of polling `workflow::status`.

    any of (2)
    Variant 1
    • function_idstringrequired

      Function id to call on terminal state, e.g. `"myworker::wf-done"`.

    • queuestring

      Queue for durable delivery; defaults to the worker's `"workflow-notify"` queue.

    Variant 2
    valuenull
  • outputany of

    What the run returns: a node id returns that node's result as is, an array of ids an object keyed by id. A node of a loop, the loop node or a body node, returns its last pass. Omit it to return every node no other node reads (one such node: its result as is).

    any of (2)
    Variant 1
    any of (2)
    Variant 1
    valuestring
    Variant 2
    itemsstring[]
    Variant 2
    valuenull
  • titlestring

    Display title of the run, trimmed and cut to 80 characters. Omitted on a call from an agent turn, the `workflow::stamp-reply` hook fills it from the call's description.

Response
  • nextunknown

    For an agent caller: the `harness::observe` call that delivers the run's outcome to this session. Make it exactly as given, then end the turn.

  • run_idstringrequired

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

    The run's display title, when it has one.

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

Function

Serve the workflow worker's injected console UI assets (the target of its ade::ui::asset observers; the console calls it through each asset's observer with {path}).

Request
  • pathstringrequired

    The asset path from the observer's args (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

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.