Skip to content
Sign in

workflow

v0.2.1

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

license: Apache-2.0Used in 1 kitautomationdurablemulti-agentorchestrationworkflow

Install

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

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

workflow worker

A deterministic DAG orchestrator running over the iii harness. Accepts workflow::start / workflow::tick / workflow::stop calls; persists run state in state; fans out nodes as child harness sessions with deterministic ids so duplicate deliveries are idempotent.

The two always-on harness observers (harness::on-turn-completed → wake, harness::hook::on-pre-call → stamp-reply) are created once at startup. An observer created before the harness is up stays pending and becomes active when the harness registers its function, and again after a harness restart. The third — harness::hook::on-pre-generate → inject-guidance — follows the inject_guidance knob in the workflow configuration entry (ON by default): turning it off shrinks prompts (the harness's # Granted functions catalog still advertises the workflow::* ids) and the worker observes or disposes it hot, no restart.


Getting the result back (don't poll)

workflow::start returns a run_id immediately. There are a few ways to learn the outcome; prefer push over polling workflow::status in a loop.

  1. Reply into your session (for an AGENT caller). Set reply_to: {} on workflow::start. When the run reaches a terminal state the worker posts the outcome into your session as a new message (via harness::send), so your next turn just sees it — no polling, no callback wiring:

    workflow::start {
      "definition": { /* ... */ },
      "reply_to": { "template": "Naming run done — pick the winner:" }  // template optional
    }

    You pass NO session id: a pre_call hook auto-stamps your real session_id / model / provider (an agent cannot target another session). Delivery is at-least-once; a deterministic idempotency_key (wfreply_<run_id>) makes a re-fire a no-op.

  2. Completion callback (push), for a WORKER caller. Pass notify to workflow::start. When the run reaches a terminal state the worker calls your function once with {run_id, status, result, result_error}:

    workflow::start {
      "definition": { /* ... */ },
      "input": { /* ... */ },
      "notify": { "function_id": "myworker::wf-done" }  // optional "queue", defaults to "default"
    }

    Delivery is durable (enqueued) and at-least-once — make the handler idempotent and dedup on run_id. This is the push path; no polling.

  3. Observe every run. Every terminal run also calls workflow::on-run-completed. Observe it to see all runs, e.g. for audit (see Events).

    iii.observe(
      { function_id: 'workflow::on-run-completed', filters: { 'input.status': { $eq: 'failed' } }, deliver: 'output' },
      'audit::workflow-failed',
    )

workflow::status remains for one-off inspection, but a live tracker should use reply_to (agents) or notify (workers) rather than a status loop.


Events

Function Args Filter on Event
workflow::on-run-completed none input.run_id, input.status RunCompletedEvent { run_id, status: completed | failed | cancelled, result, result_error }

The function is private (only this worker calls it; anyone may observe it) and returns the event it is called with. The worker calls it once per terminal run, at least once (a crash mid-finalize re-fires it), and only while something observes it; dedup on run_id.

Observers

Observed function Args / filters Target Target receives
cron::on-tick args { expression: <sweep_expression> } workflow::sweep the tick (deliver: output)
harness::on-turn-completed none workflow::wake TurnCompletedEvent (deliver: output); non-workflow sessions are ignored
harness::hook::on-pre-call args { functions: ["workflow::start"], on_error: "fail_open", timeout_ms: 30000 } workflow::stamp-reply the pre-call hook input; returns the hook decision
harness::hook::on-pre-generate args { on_error: "fail_open", inject_prompt: <workflow guidance> }, only while inject_guidance is on workflow::inject-guidance not called: the harness joins inject_prompt into the system prompt
configuration::on-updated filters on input.id and input.event_type (through iii-config-client) workflow::on-config-change the configuration event (deliver: output)

A sweep_expression change observes the new expression first, then disposes the old observer; if the cron worker refuses the new expression (INVALID_CRON_EXPRESSION), the old observer and schedule stay.


Scaling & concurrency

Single-writer-per-run (the correctness model)

Every path that reads, mutates, and writes a run record — workflow::tick, reconcile, the pending-timeout sweep, and workflow::stop — holds the per-run WorkflowLocks guard before touching state. This serialises writes within one process and closes the read-modify-write race.

Idempotency for duplicate event deliveries is provided by deterministic ids: the child session id (wf_<run_id>_<node_uid>@r<attempt>) and the workflow_node_result/<run_id>/<node_uid> key are stable, so a re-delivered tick that re-fires an already-running node is a no-op at the harness layer.

One instance per namespace

A function id has one host per namespace: the engine rejects a second registration of the same id with FUNCTION_NAMESPACE_CONFLICT. The worker registers every workflow::* function, workflow::on-run-completed included, so the first instance in a namespace hosts them all and the per-run WorkflowLocks live in that one process. A second instance in the same namespace gets every registration rejected while its observers (the sweep and the harness hooks) still deliver to the first instance's functions, so each sweep and hook runs twice. Run one workflow worker per namespace.

No record-level CAS available

state exposes state::get, state::set, state::delete, state::list, and state::update (atomic per-field ops). None carry a precondition or version check — state::set is an unconditional overwrite. There is no state::cas or if_match parameter.

WorkflowRunRecord therefore carries no version field; pretending one enforces optimistic concurrency would be misleading.

Blocked prerequisite for true multi-writer-per-run

Whole-record optimistic concurrency (allowing two instances to safely race on the same run) requires an upstream iii engine operation: a state::set with an expected/if_match argument, or a dedicated state::cas call. Until that engine op exists, every run has one writer: the single instance (above).

Action: file an engine feature request for state::set with if_match / state::cas. Do not build a fake CAS on top of the current unconditional set.

Search the registry

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