badgr-agent-resume

Add step-level checkpoints to agent runs so they survive crashes, timeouts, and restarts — without repeating completed steps.

import { agentRun } from "badgr-agent-resume";

await agentRun("support-agent", async (run) => {
  const plan  = await run.step("create-plan",   generatePlan);
  const order = await run.step("fetch-order",   () => fetchOrder(plan.id));
  return      await run.step("write-response", () => generateReply(order));
});

Free. No signup required. Checkpoints are saved to .badgr/runs/ on your machine.

The problem it solves

Multi-step agents crash mid-run and restart from scratch. A 20-minute agent that fails at step 8 of 10 wastes 18 minutes of compute and re-runs side effects. badgr-agent-resume wraps each step with a checkpoint — if the run crashes, the next execution skips completed steps and picks up exactly where it left off.

Quick start

npm install badgr-agent-resume

import { agentRun } from "badgr-agent-resume";

await agentRun("my-agent", async (run) => {
  // Each step is checkpointed. On re-run, completed steps are skipped.
  const data    = await run.step("fetch-data",    () => fetchFromApi());
  const summary = await run.step("summarize",     () => callLlm(data));
  return         await run.step("send-email",     () => sendEmail(summary));
});
// Checkpoints saved to: .badgr/runs/my-agent-<timestamp>.json

If summarize crashes, re-running the script skips fetch-data (already done) and resumes from summarize.

How checkpointing works

Each run.step(name, fn) call:

1. Checks .badgr/runs/ for an existing run with this name
2. If the step was completed in a previous run, returns the saved output immediately
3. If not, executes fn, saves the output, and marks the step complete
4. If fn throws, the step is marked failed and the error is rethrown

Steps are identified by name, so renaming a step invalidates its checkpoint.

API

agentRun(name, fn, options?)

Runs an agent with checkpointing. Returns the final value of fn.

await agentRun(
  "my-agent",          // run name — used to find existing checkpoints
  async (run) => {
    return await run.step("step-name", async () => {
      // your step logic
    });
  },
  {
    stateDir?: string; // where to save checkpoints (default: .badgr/runs)
  }
);

run.step(name, fn)

Executes a step with checkpointing. If the step completed in a previous run, fn is not called — the saved output is returned instead.

run.timeline()

Returns a human-readable timeline of all steps:

create-plan    completed  1.2s
fetch-order    completed  0.4s
write-response running    ...

run.state()

Returns the full run state as a typed object.

CLI — inspect a saved run

# Show the status of a saved run and resume instructions
npx badgr-agent-resume resume <run-id>

# Machine-readable JSON
npx badgr-agent-resume resume <run-id> --json

# Show optional hosted run history link
npx badgr-agent-resume connect

TypeScript API

import { agentRun, loadRun, formatTimeline } from "badgr-agent-resume";

// Load a saved run by ID
const state = await loadRun("my-agent-1718000000000");

// Format the timeline
console.log(formatTimeline(state));
// create-plan    completed  1.2s
// fetch-order    completed  0.4s
// write-response failed     0.1s  Error: API timeout

Types:

interface AgentRunState {
  id: string;
  name: string;
  createdAt: string;
  updatedAt: string;
  steps: RecordedStep[];
  result?: unknown;
}

interface RecordedStep<T = unknown> {
  name: string;
  status: "completed" | "failed" | "running";
  startedAt: string;
  finishedAt?: string;
  output?: T;
  error?: string;
}

Requirements

• Node.js 18+
• TypeScript 5+ (for type definitions)