next

Takes the next request a workflow run is waiting on, and claims it for the caller in the same call, so two agents cannot answer the same question. Pass runner, a name recorded on the claim, and optionally run to take only from one run (an unknown run, or one that has ended, raises naming its state). Returns nil when nothing is waiting.

The result carries request, run, phase, step, schema (the shape the answer must have), prompt_path and prompt_bytes, lease_seconds, expires_in and renew_with. The prompt is kept in a file rather than returned: it is one agent's whole job, so hand the file at prompt_path to a subagent and answer with what it returns. prompt itself is returned only when the run could not keep it in a file. The claim is held for lease_seconds from the claiming session's last tool call on the engine; renew it with workflow.renew before a stretch with no engine calls. A claim left to run out returns to the queue. Finish with workflow.answer or workflow.fail.

workflow.next("me")