Commitment Queue — execution persistence for agents

Your agent hits a rate limit at 3am. Or a schema changes. Or a credential expires, or the network blips. It stops. Nothing remembers what it was doing, nothing watches for the condition to clear, nothing resumes. In the morning you replay it by hand.

The commitment queue fixes exactly that, and nothing else.

import { CommitmentQueue } from "./commitment-queue.ts";
import { FileStore } from "./store-file.ts";

const queue = new CommitmentQueue({
  store: new FileStore(".agent-state"),          // survives the process
  handlers: {
    ingest: async ({ payload }) => {
      const res = await fetch(payload.url);
      if (res.status === 429) {
        // not a failure — a state of the world. Costs no attempt.
        return { status: "blocked", reason: "rate limited", retryAfterMs: 60_000 };
      }
      return { status: "done", result: await res.json() };
    },
  },
});

await queue.commit({ type: "ingest", payload: { url } });  // durable BEFORE it runs
await queue.run();                                          // resumes across restarts

Kill the process mid-run. Start it again. The work continues.

What it guarantees

Each line is enforced by a test in conformance.test.ts / store-file.test.ts (29 passing):

• Commit is durable before execution. A crash on the next instruction loses nothing.
• Commit is idempotent. The same intent never duplicates.
• Waiting is not failing. A blocked outcome consumes no attempt, so an agent can wait a week on a missing credential without exhausting its retry budget.
• Resume is conditional, never hopeful. A blocked commitment returns to the queue only when a named condition you registered reads true — or the kernel closes its gap. An unknown condition means it stays blocked. The queue never guesses.
• A crashed worker strands nothing. Claims are leases; an expired lease is reclaimed and the work runs exactly once.
• Concurrency is safe. Many workers, one store, one execution per commitment.
• Terminal states are honest. Exhausted budgets and passed deadlines abandon with the real reason attached, including what it was waiting on.
• Writes are atomic. Temp-file + rename, so a record is never half-written.
• Observers can't break execution. A throwing event listener is contained.

Portability

commitment-queue.ts has zero imports and does no I/O — it runs unchanged on Node, Deno, Bun, workers, and edge runtimes. Time and randomness are injected, so behavior is deterministic and testable. Storage is a port:

| Store | Use | |---|---| | MemoryStore (in core) | tests, ephemeral workers | | FileStore (store-file.ts) | any runtime with a filesystem | | your own | implement four methods: put, get, list, delete |

The same queue, machine-to-machine

A commitment can block on a confidence gap — a machine-readable statement of what must become true. Hand the queue a resolver and the identical mechanism negotiates across agents:

import { createLaenGapResolver, gapFromFailure } from "./laen-bridge.ts";

const queue = new CommitmentQueue({
  store, handlers,
  resolveGap: createLaenGapResolver({
    resolvers: [myPaymentResolver],   // YOUR wallet, YOUR policy
  }),
});

// in a handler:
return { status: "blocked", reason: "provenance unverified",
         gap: gapFromFailure({ identifier: "api.example.com" }) };

The bridge queries LAEN's public blocker feed (free, read-only), attaches the published terms — endpoint, price, network, recipient — and stops. It never spends. Only a resolver you supply, holding your wallet under your policy, can settle. Until then the commitment stays blocked with an honest status (PAYMENT_REQUIRED, AUTHORITY_REQUIRED, …).

Evidence is accepted only if verify() returns true — an independent check against something outside the resolver that produced it. A resolver's claim of success is worth nothing on its own.

Run the suite

node --test

Status

New code, tested but not yet proven under production load. The guarantees above are mechanically verified; longevity in the wild is not yet evidence. Issues and reports welcome.