workflow
v0.2.2Deterministic, crash-resumable multi-agent workflow orchestrator over harness turns.
Install
iii trigger compose::add worker=workflow@0.2.2Run 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.
Reply into your session (for an AGENT caller). Set
reply_to: {}onworkflow::start. When the run reaches a terminal state the worker posts the outcome into your session as a new message (viaharness::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_callhook auto-stamps your realsession_id/model/provider(an agent cannot target another session). Delivery is at-least-once; a deterministicidempotency_key(wfreply_<run_id>) makes a re-fire a no-op.Completion callback (push), for a WORKER caller. Pass
notifytoworkflow::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.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' } }, capture: ['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 (capture: [output], read as payload.output) |
harness::on-turn-completed |
none | workflow::wake |
TurnCompletedEvent (capture: [output], read as payload.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 (capture: [output], read as payload.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.