Praecise Harness v1.1.0 Get started

Documentation · Building

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.

ts
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.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.