Cap your agent's spend — and see exactly where the money went

Drop one wrapper around your LLM client and you get three things the raw SDK doesn't: a hard cap that actually holds under concurrency, a per-agent spend breakdown, and an early pause when a loop goes runaway.

What you get

• (a) A hard cap that holds under concurrency — not one that N parallel workers each slip past and collectively blow through.
• (b) A per-source spend breakdown — which agent / session / worker burned the most, in dollars.
• (c) An early pause on runaway burn — a $/min alarm that stops a stuck loop before it drains the budget.

See it do the job

node report.js

No network, zero dependencies. It runs a small fleet of named agents under a $50 cap — including one that slips into a runaway loop — and prints the answer you actually want: where the money went, whether the cap held, and that the runaway was stopped.

Use it in your code

const { SpendGovernor } = require('./governor');

const gov = new SpendGovernor({
  hardCapUsd: 25,
  burnSoftUsdPerMin: 30,
  onBurnAlert: (info) => notifyHumans(info),      // pause-and-ask hook
});

const answer = await gov.run({
  provider: 'openai',
  source: 'research-agent',                     // who to bill -> shows in the breakdown
  worstCaseUsd: 0.05,                          // max-output-token price
  invoke: async () => {
    const resp = await openai.chat.completions.create({ /* ... */ });
    return { costUsd: priceOf(resp.usage), result: resp };  // reconcile to actual
  },
});

const spend = gov.report();  // { totalSpentUsd, capHeld, bySource, topSpender, ... }

The same gov in front of an anthropic SDK call shares one ceiling and one breakdown — it sits at the call boundary, above every provider.

The real problem this solves

You set a cap. It looks right. The fleet crosses it anyway, by a wide margin — because a cap that increments after the call is racing itself the moment work runs concurrently.

• dam-agents/dam#3428 — a spend cap that doesn't hold under concurrent workers.
• anthropics/claude-code#73795 — “$1,771 in 4h against a $25 cap.”

Cited as motivation. This code is not affiliated with, and makes no claim about, those projects.

How it works

1. The cap holds under concurrency — reserve-before / reconcile-after

The naive cap reads the cumulative total, awaits the call, then adds the cost. Between the read and the add, every in-flight worker reads the same stale total, sees headroom, and proceeds — N workers each pass the cap and collectively overshoot by up to N × (largest call). The fix reserves the worst-case cost before dispatching, in one atomic add-and-check with no await in between, then reconciles to the real cost after.

// RESERVE (atomic, no await between read and write) — like Redis INCRBY.
const afterReserve = this.reserved.add(worst);
if (afterReserve > this.hardCap) {
  this.reserved.add(-worst); throw new SpendCapExceeded(...);
}
const { costUsd, result } = await invoke();   // the real call
this.reserved.add(usd(costUsd) - worst);      // RECONCILE to actual
this._charge(source, usd(costUsd));           // attribute to the source

node demo.js proves it directly: 20 concurrent workers, a $25 cap — the naive version overshoots to ~$78, the governor holds the ceiling.

2. The per-source breakdown

Every run({ source }) attributes the reconciled cost to that source, so report() tells you who spent what — the difference between “we spent too much” and “the research-agent's retry loop spent too much.”

3. Early pause on runaway burn

A cumulative-$ or per-call check is blind to a loop whose total is nowhere near the cap but whose $/minute is screaming. A sliding-window burn meter fires a “pause and ask” before the hard cap is approached — a loop bug caught in seconds instead of at the ceiling.

Adapt to prod

• Shared counter: add(delta) → INCRBY key delta; value → GET key. One key per budget window, TTL to the window.
• Crash safety: append each reserve/reconcile to a ledger; a reaper releases reservations older than the max call timeout.
• Distributed burn meter: a Redis sorted set keyed by timestamp (ZADD / ZREMRANGEBYSCORE) gives the same window across processes.
• Per-tenant caps: one key namespace per tenant; the boundary wrapper is the natural place to pick it.

Get the code