When a run stops badly
A workflow that waits for a human is the easy case. The hard cases are a process that died and a decision that turned out to be wrong, and they need different answers.
import { resumeRun, recoverRun, forkRun } from "@praecise/harness";
// a human answered the gate — the decision is the argument, not a flag
await resumeRun(runId, { approved: true, approver: "ada", channel: "cli" }, spec, deps);
// the process driving the run died; re-drive it from the journal
await recoverRun(runId, spec, deps);
// ask what would have happened if an earlier step had decided differently
await forkRun(runId, spec, deps, { after: "sorted", patch: { sorted: { category: "refund" } } });resumeRun answers a gate. It refuses a run still marked running, because
something may still be driving it.
recoverRun exists for exactly that refusal. A crash leaves a running status
behind with nobody driving, and the journal is the only way back. Calling it asserts
the driver is dead — the store records state, not processes, so that assertion is
yours to make. Completed steps are replayed from the journal and never re-executed.
A step interrupted mid-side-effect is the case neither can resolve alone. It is marked inflight, and recovery refuses to repeat it: nothing in the journal can prove the effect did not already happen, and a charge issued twice is worse than a run that stopped. Resolve it and clear the entry, or retry under the same idempotency key.
forkRun is for the counterfactual. It copies the journal up to a point and
nothing past it, so the original stays readable exactly as it happened, beside the
one that might have. patch is what makes it worth having: edit an earlier step's
output and watch what follows change — asking what the run would have done if the
classifier had said refund, without pretending it did. Every patched value is
recorded as patched.
Stopping a run is app.cancelWorkflow(runId, { reason, by }), or
POST /api/runs/<id>/cancel. A run in flight is interrupted where it stands and
one waiting at a gate or for an event is ended there; either is recorded as
cancelled. A function hears it as signal in its second argument, and
startWorkflow(name, input, { signal }) ties a run to a signal of the caller's.
A passes check that is running a command is not interrupted, and a run streamed
over AG-UI reports its cancellation as RUN_ERROR. There is no CLI command for
it.
A ceiling in money. limits: { spend: { amount: 2, currency: "USD" } } in the
config stops a run that has spent that much, counted from the prices its
endpoints declared. A run that reaches a model with no declared price, or one
priced in another currency, is stopped and told why instead of being counted as
free.