workflow

The workflow runtime: it runs a workflow's body in the engine and keeps the book of every run. The workflow toolbox (workflow.start, next, answer, status, ...) is how an agent drives a run; the workflow asset type starts one by name; an editor view reads the book to show the runs.

local Workflow = require("@builtin::modules.workflow")

A run

startJs(source, opts?) and startLuau(body, opts?) start a run and return it at once, already executing. The body is handed phase, log, agent, parallel, pipeline and args; agent(prompt, { label, phase, schema }) parks the body on a request until somebody answers it.

Field	What it holds
id, workflow	The run's id (run-<8 hex>) and the workflow's name.
state	running, finished, failed or cancelled.
phase	The phase the body is in now.
started_at, ended_at	Wall-clock seconds.
started_by	The caller whose call started it: { id, stable, agent, connection, name, account }, each as vfs.currentAuthor() named it; nil for engine-started work.
origin	Where it was started from, as the host that started it stated it with setOrigin (a conversation, a panel); nil until one does.
cancelled_by	The caller whose call cancelled it.
log	{ at, phase, text, runtime?, entered? } lines: the body's own (entered = true on the line phase() wrote), and the runtime's (runtime = true) about a lapse, a resume or its ending.
requests	Every request it asked, oldest first.
result, error	What a finished body returned; why a run failed or was cancelled.
restored	How many times an engine read it back from its record.

A request carries id (call-<8 hex>), label, phase, state (waiting, claimed, answered, failed, cancelled), asked_at, waiting_since (when it was asked, or when a claim on it ran out), settled_at, claimed_by (the runner name the claim was taken under), claimed_at, lapses (claims that ran out), corrections, answer, error, and prompt_path, the file its prompt is kept in. leaseLeft(req) is how long a claim has left, in seconds.

Reading the book

Call	Answers
list()	Every run this engine holds, oldest first.
get(id)	One run, or nil.
phases(run)	The phases it entered, in order, each { name, asked, waiting, claimed, answered, failed, cancelled }.
waiting()	Every request waiting to be taken, oldest first.
revision()	A number that advances with every change to the book.
onChange(fn)	Calls fn(runId) after every change (runId nil when the book as a whole changed), and returns the function that stops it. fn runs inside the call that made the change: mark what you show as stale and read the run when you next draw.

A change is a run starting, entering a phase, logging, asking, a request being claimed, renewed, answered, corrected, failed or offered again after its claim ran out, the run ending, being read back from its record, or being unloaded.

Acting on a run

Call	Does
cancel(id, reason?)	Ends a running run cancelled: every request it still waits on is cancelled with it, an answer to one is refused, and the run says so once on the notice feed. The body is stopped at its next call of agent, phase or log, each of which raises once a run has ended, so a body parked on a request unwinds there. Raises for an id no run holds or a run that has ended.
setOrigin(id, origin)	States where the run was started from (a table of fields, copied); kept with its record.
claim, renew, answer, correct, fail	The runner's verbs, which the workflow toolbox carries.

Kept across restarts

Each run keeps its record under STORE (/zero/source/local/workflow_runs/), which this machine keeps for the world and the user. When the engine comes back on the world, restore() reads every record: an ended run is listed as it ended, and a running one runs its body again from the top, each agent() call taking the answer or the claim its request already has.