Deterministic Replay & Crash Recovery

In the middle of a long-running agent run, the process crashes, a deploy restarts it, or a tool suspends while waiting for approval (see human-in-loop-approvals). A classic generateText knows nothing past that point — you'd have to regenerate the conversation and every tool result. runDurable writes every model step and every tool call's result to the journal; when called again with the same runId (or via resumeRun), it does NOT re-ask the model for steps that were already produced — it reads them from the journal and continues from where it left off. Result: a side-effecting tool (e.g. a payment charge) doesn't run a second time after a crash, and the model doesn't spend the same tokens twice.

The package is exported from a single entry point — no subpath needed (only the persistent storage adapters @gnldev/durable/sqlite and @gnldev/durable/postgres are separate exports, see storage-adapters).

import { runDurable, resumeRun, InMemoryJournal } from '@gnldev/durable';

The example below is taken from a real test scenario: a tool call requesting a charge of 5000 units is routed to approval (require-approval) by the guard — the run suspends. The prompt is never rewritten anywhere; resumeRun is called with only the runId and the approval information.

const journal = new InMemoryJournal();

const r1 = await runDurable({
  runId: 'o1',
  journal,
  model: makeModel(),
  tools: makeTools(counter),
  guard,
  prompt: 'charge 5000',
  stopWhen: stepCountIs(6),
});

// nothing has been charged yet — the guard suspended it
console.log(counter.charges);       // 0
console.log(r1.interrupts.length);  // 1

const r2 = await resumeRun('o1', {
  journal,
  model: makeModel(),
  tools: makeTools(counter),
  guard,
  approvals: { 'call-c': true },
  stopWhen: stepCountIs(6),
});

console.log(counter.charges); // 1 — exactly once
console.log(r2.text);         // 'Done.'

Internally, resumeRun reads the input (prompt/messages/system) that was written to the journal on the first call and calls runDurable again with the same runId — that's what makes resume self-contained. If there's no recorded input (an unknown runId), it throws a meaningful error.