flint-agent 1.14.0

package/src/agent/tool-guard.js

@@ -0,0 +1,201 @@
+// Who decides which tools a turn gets, and when that decision is not trusted.
+//
+// The classifier runs BEFORE the agent has read the task, and its picks are a
+// guess. On 2026-09-29 the guess took the tools away from the task three times
+// in one evening and nobody was told:
+//
+//   "Read <brief> and do what it says"        -> file_read  (1 tool, 3 steps)
+//   "so why did you stop"                     -> chat       (0 tools)
+//   "Continue the task: write the fix and the
+//    tests as files ..., run them with npx
+//    vitest, commit."                         -> chat       (0 tools)
+//
+// The third one is the worst: a turn that arrives in the middle of work, or
+// that points at a file holding the instructions, has by definition not
+// described all the work. A class list and a one-sentence paraphrase are not
+// enough to decide that read_file is all it needs, and no one was shown the
+// narrowing.
+//
+// Two rules, both about trust rather than about wording:
+//
+//   1. A guess is never the whole reason a turn loses its tools. When the
+//      message is mid-task (tools already ran in this session) or points at a
+//      file with instructions, the turn gets the full built-in surface and the
+//      classifier's class is kept only for display.
+//   2. Whatever narrowing does happen is visible: the operator is told which
+//      class it was and how many tools survived. A silent narrowing is what
+//      makes a turn that could not be done look like a turn that gave up.
+//
+// Widening costs tokens — the fallback is every built-in tool, not the core
+// set. That is the direction to pay in: a narrow turn that cannot do the task
+// is worth more than the tokens it saved, and the price is only paid on the
+// messages where the guess is known to be unsafe.
+
+// What a message pointing at instructions usually looks like. Extensions only:
+// a path with one of these is a thing someone wrote down, which is the whole
+// reason the request cannot be read off its first line.
+const INSTRUCTION_FILE = /[\w./\\-]*\.(?:md|markdown|txt|rst|adoc|brief|task|todo|instructions)\b/i;
+
+// Phrases that hand the work to something outside the message itself.
+const INSTRUCTION_PHRASES = [
+  /\bdo (?:what|as) (?:it|this|the file|the brief) says\b/i,
+  /\bas (?:it|the file|the brief) says\b/i,
+  /\bfollow (?:the )?(?:instructions?|steps?|directions?) in\b/i,
+  /\b(?:according to|per) the (?:instructions?|brief|file)\b/i,
+  /\bsee (?:the )?file\b.*\bfor\b/i,
+  /\bin (?:the|this) file\b/i,
+];
+
+/**
+ * Does this message hand the work to something else — a file, a brief, a
+ * list of instructions somewhere on disk?
+ *
+ * @param {string} text
+ * @returns {null | {kind: "file"|"phrase", path?: string}} null when it does not
+ */
+export function pointsAtInstructions(text) {
+  const s = String(text || "");
+  if (!s.trim()) return null;
+  const fileMatch = s.match(INSTRUCTION_FILE);
+  if (fileMatch) return { kind: "file", path: fileMatch[0] };
+  if (INSTRUCTION_PHRASES.some((re) => re.test(s))) return { kind: "phrase" };
+  return null;
+}
+
+/**
+ * Is this message arriving in the middle of work?
+ *
+ * `priorToolCalls` is the fact that matters, not the number of messages: if
+ * this session already ran a tool, the operator is in the middle of a task,
+ * and a bare message in the middle of a task is a continuation, not a new
+ * subject. `priorTurns` is kept for the softer case — a second message with no
+ * tool yet is usually a follow-up of the first ("why?").
+ *
+ * @param {object} ctx - { priorToolCalls?: boolean, priorTurns?: number }
+ * @returns {boolean}
+ */
+export function isMidTask(ctx = {}) {
+  if (ctx.priorToolCalls) return true;
+  return (ctx.priorTurns || 0) > 0;
+}
+
+// Below this, a tool set cannot do a task that involves writing, running and
+// checking anything — which is what a mid-task message almost always is.
+const MIN_TRUSTWORTHY_TOOLS = 6;
+
+/**
+ * Is the classifier's tool set good enough to act on for this message?
+ *
+ * @param {object} args
+ * @param {object} args.manifest   — the classifier's manifest
+ * @param {string} args.message    — the user's message
+ * @param {object} [args.ctx]      — { priorToolCalls, priorTurns }
+ * @returns {null | {untrusted: true, reason: string}} null when the set is trusted
+ */
+export function untrustedToolSet({ manifest, message, ctx = {} }) {
+  const picked = Array.isArray(manifest?.tools) ? manifest.tools.length : 0;
+  const midTask = isMidTask(ctx);
+  const pointer = pointsAtInstructions(message);
+
+  if (pointer) {
+    return {
+      untrusted: true,
+      reason: `the message points at instructions (${pointer.path || pointer.kind}), so the request is not in the message`,
+    };
+  }
+  if (picked === 0 && midTask) {
+    return { untrusted: true, reason: "a text-only class for a mid-task message" };
+  }
+  if (picked === 0 && pointer) {
+    return { untrusted: true, reason: "a text-only class for a message that points at instructions" };
+  }
+  if (midTask && picked < MIN_TRUSTWORTHY_TOOLS) {
+    return {
+      untrusted: true,
+      reason: `only ${picked} tool${picked === 1 ? "" : "s"} for a message that arrives mid-task`,
+    };
+  }
+  return null;
+}
+
+/**
+ * One line for the operator about what this turn can do.
+ *
+ * Returns "" when nothing was narrowed: a turn with every tool is the normal
+ * case and a line about it would be noise on every message. When something
+ * was narrowed, the class and the count are both stated, because the count is
+ * the part that decides whether the task is possible.
+ *
+ * @param {object} args - { manifest, allDefs, tools }
+ * @returns {string}
+ */
+export function describeToolScope({ manifest, allDefs = [], tools = [] } = {}) {
+  if (!manifest) return "";
+  const total = allDefs.length;
+  const names = tools.map((t) => t.function?.name || t.name).filter(Boolean);
+  if (!total) return "";
+  // Full surface is the normal case and a line about it would be noise on every
+  // message; anything else, including zero tools, is stated.
+  if (names.length >= total) return "";
+  const shown = names.slice(0, 8).join(", ");
+  const more = names.length > 8 ? `, +${names.length - 8} more` : "";
+  const list = names.length ? `(${shown}${more})` : "(none)";
+  return `mode ${manifest.intent}: ${names.length} of ${total} tools ${list}`;
+}
+
+/**
+ * The tool list this turn actually gets, and one line about it for the
+ * operator.
+ *
+ * The assessment gate wins over everything: a `dangerous` classification is a
+ * deliberate refusal to hand over the tools, and this module is not entitled
+ * to overrule it. That is the difference between a guess that may be wrong
+ * (the classifier's tool picks) and a decision that was made on purpose.
+ *
+ * The fallback shape is the built-in surface rather than every live tool, for
+ * the same reason fallbackManifest uses it: MCP schemas cost 33k tokens a call
+ * and the MCP tools can be fetched by tool_search when the turn finds it needs
+ * them. Measured in src/agent/intent.js.
+ *
+ * @param {object} args
+ * @param {object} args.manifest      — the classifier's manifest
+ * @param {Array}  args.allDefs       — every live tool definition
+ * @param {Array}  [args.narrowedTools] — what filterToolsByManifest returned
+ * @param {boolean} [args.blockTools] — the assessment gate took the tools
+ * @param {string} [args.message]     — the user's message
+ * @param {object} [args.ctx]         — { priorToolCalls, priorTurns }
+ * @returns {{tools: Array, note: string, widened: boolean}}
+ */
+export function decideToolScope({
+  manifest,
+  allDefs = [],
+  narrowedTools = [],
+  blockTools = false,
+  message = "",
+  ctx = {},
+} = {}) {
+  const defs = Array.isArray(allDefs) ? allDefs : [];
+  const nameOf = (t) => t.function?.name || t.name;
+
+  if (blockTools) {
+    return { tools: [], note: describeToolScope({ manifest, allDefs: defs, tools: [] }), widened: false };
+  }
+
+  const trust = untrustedToolSet({ manifest, message, ctx });
+  if (!trust) {
+    return { tools: narrowedTools, note: describeToolScope({ manifest, allDefs: defs, tools: narrowedTools }), widened: false };
+  }
+
+  const builtin = defs.filter((t) => !String(nameOf(t) || "").startsWith("mcp_"));
+  const widened = builtin.length > 0 ? builtin : defs;
+  // The count is always stated, including when the widened set is every tool:
+  // "all 13 tools" and "1 of 13 tools" are different facts to the operator, and
+  // the whole point of this line is that the difference is no longer invisible.
+  const names = widened.map(nameOf).filter(Boolean);
+  const shown = names.slice(0, 8).join(", ");
+  const more = names.length > 8 ? `, +${names.length - 8} more` : "";
+  const scopeText = `mode ${manifest?.intent || "unknown"}: ${names.length} of ${defs.length} tools`;
+  const note = `[${manifest?.intent || "unknown"}] ${scopeText}${shown ? ` (${shown}${more})` : ""}` +
+    ` — the tools were widened: ${trust.reason}. Nothing is lost; if this turns out to be the wrong read, say so.`;
+  return { tools: widened, note, widened: true };
+}

package/src/agent/toolcall-text.js

@@ -0,0 +1,162 @@
+// Tool calls the model wrote as text.
+//
+// On 2026-09-29 a turn classified `chat` (0 tools, 1 step) had the model write
+// its tool calls into the answer:
+//
+//   <tool_call><function=edit_file>... 9 KB of it ...
+//
+// Nothing ran it. The text streamed to the console as if it were progress, the
+// operator saw nine kilobytes of a diff scroll past, and the only thing that
+// recovered the session was /new.
+//
+// Two things were wrong with that, and they are separate:
+//
+//   1. The text was printed as progress. Whatever the model meant, a turn that
+//      cannot run what it wrote must not LOOK like it ran it.
+//   2. Nothing said so. The answer came back as `done`, and a task that
+//      changed nothing reads exactly like a task that finished.
+//
+// So: find the calls, and either Flint can run them or the operator is told
+// that the model answered in a form Flint could not run. Never neither.
+
+// One model puts a zero-width space inside the tag so that markdown renderers
+// leave it alone. It is written as an escape here rather than as the character,
+// because a literal invisible character inside a regex is unreadable and gets
+// eaten by every editor that reformats a file.
+const ZW = "\\u200b";
+
+// No `g` on the two detectors. With it, `.test()` advances `lastIndex` and the
+// next call starts mid-string, so the same answer is detected on one call and
+// missed on the next -- a detector that alternates is worse than none. The
+// scanning regexes keep `g` because they are always used with matchAll, which
+// does not share that state.
+const TOOL_CALL_TAG = new RegExp(`<\\s*${ZW}?\\s*tool_call\\s*>`, "i");
+// Two shapes need the same pattern matched two ways, and the difference is
+// not cosmetic: String.match() with a `g` flag returns the full matches and
+// throws the capture groups away, so `fn[1]` — the tool name — comes back
+// undefined. A scan regex and a single-match regex, both built from one source.
+const FUNCTION_SRC = `<\\s*${ZW}?\\s*function\\s*=\\s*([A-Za-z0-9_.-]+)\\s*>`;
+const FUNCTION_TAG = new RegExp(FUNCTION_SRC, "gi");   // matchAll
+const FUNCTION_ONE = new RegExp(FUNCTION_SRC, "i");    // .match(), keeps groups
+const FUNCTION_OPEN = new RegExp(`<\\s*${ZW}?\\s*function\\s*=`, "i");
+// The closing tag carries the same zero-width character as the opening one, so
+// it has to be built the same way. Without this the body ran to end-of-answer
+// and every JSON-body call came back truncated — which the "unreadable" branch
+// reported honestly, but the tool name was lost with it.
+const CLOSE_TAG = new RegExp(`<\\s*${ZW}?\\s*\\/\\s*(?:tool_call|function)\\s*>`, "i");
+
+/**
+ * Does this text contain a tool call written as text?
+ *
+ * Cheap and prefix-friendly, so it can be run on a growing stream buffer: it
+ * answers "has this started?", not "is it complete?".
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function looksLikeTextToolCall(text) {
+  const s = String(text || "");
+  if (!s) return false;
+  return TOOL_CALL_TAG.test(s) || FUNCTION_OPEN.test(s);
+}
+
+/**
+ * Pull the tool calls out of an answer that wrote them as text.
+ *
+ * Both shapes seen in the wild:
+ *   <tool_call><function=edit_file>{"path":"a.js"}</tool_call>   (function tag)
+ *   <tool_call>{"name":"edit_file","arguments":{...}}</tool_call>  (JSON body)
+ *
+ * Arguments are reported as the raw text that followed the name: Flint does not
+ * run them (they may be truncated mid-JSON by the model's own output limits),
+ * and a half-written argument string is exactly what the operator needs to see
+ * named as unrunnable rather than silently dropped.
+ *
+ * @param {string} text
+ * @returns {Array<{name: string, args: string}>} possibly empty
+ */
+export function findTextToolCalls(text) {
+  const s = String(text || "");
+  if (!looksLikeTextToolCall(s)) return [];
+
+  const calls = [];
+  // One pass over the opening tags, not one pass per shape.
+  //
+  // The two shapes nest: `<tool_call><function=edit_file>{...}</tool_call>`
+  // is a tool_call whose body is a function tag. Scanning for both
+  // independently counts it twice, and a greedy body scan then swallows the
+  // NEXT call, so the second one comes back as "unreadable". Both shapes were
+  // counted wrong before this: one call reported as two, then two reported as
+  // one good and one unreadable.
+  // matchAll requires the g flag, so the scan gets its own copy rather than
+  // the detector being reused with state attached to it.
+  const OPEN_SCAN = new RegExp(TOOL_CALL_TAG.source, "gi");
+  OPEN_SCAN.lastIndex = 0;
+  for (const open of s.matchAll(OPEN_SCAN)) {
+    const rest = s.slice(open.index + open[0].length);
+    const close = rest.search(CLOSE_TAG);
+    // No closing tag means the model was cut off mid-call. The rest of the
+    // answer IS the body, which is the 9 KB case.
+    const body = (close === -1 ? rest : rest.slice(0, close)).trim();
+
+    // Shape A: a function tag, with the name in the tag.
+    const fn = body.match(FUNCTION_ONE);
+    if (fn) {
+      const after = body.slice(body.indexOf(fn[0]) + fn[0].length);
+      const inner = after.trim();
+      calls.push({ name: fn[1], args: inner || "" });
+      continue;
+    }
+
+    // Shape B: a JSON body carrying its own name.
+    if (!body) {
+      // The tag opened and the model stopped before writing anything.
+      calls.push({ name: "(unreadable)", args: "" });
+      continue;
+    }
+    const brace = body.indexOf("{");
+    const json = brace === -1 ? body : body.slice(brace);
+    try {
+      const parsed = JSON.parse(json);
+      const name = parsed.name || parsed.function?.name || parsed.tool;
+      calls.push({
+        name: name ? String(name) : "(unreadable)",
+        args: JSON.stringify(parsed.arguments ?? parsed.args ?? {}),
+      });
+    } catch {
+      calls.push({ name: "(unreadable)", args: json.slice(0, 200) });
+    }
+  }
+
+  // A function tag with no enclosing tool_call, which is the shape seen in the
+  // logs with the outer tag missing.
+  if (calls.length === 0) {
+    FUNCTION_TAG.lastIndex = 0;
+    for (const m of s.matchAll(FUNCTION_TAG)) {
+      const rest = s.slice(m.index + m[0].length);
+      const close = rest.search(CLOSE_TAG);
+      calls.push({ name: m[1], args: (close === -1 ? rest : rest.slice(0, close)).trim() });
+    }
+  }
+
+  return calls;
+}
+
+/**
+ * What the operator is told when the model wrote tool calls as text.
+ *
+ * Says what Flint could not run and what to do, and never says the work was
+ * done. Short on purpose: this line replaces nine kilobytes of text nobody can
+ * act on.
+ *
+ * @param {Array<{name: string, args: string}>} calls
+ * @param {object} [opts] - { attempts?: number }
+ * @returns {string}
+ */
+export function toolCallTextNote(calls, { attempts = 0 } = {}) {
+  const names = [...new Set((calls || []).map((c) => c.name))];
+  const list = names.length ? names.join(", ") : "(no name readable)";
+  const again = attempts > 0 ? ` It wrote it as text ${attempts + 1} times in a row.` : "";
+  return `Stopped: the model wrote its tool call as text instead of calling the tool, so nothing ran. ` +
+    `Tool(s) written as text: ${list}. This answer did no work: read it, then tell me what to carry out.${again}`;
+}

package/src/agent/usage.js

@@ -0,0 +1,297 @@
+// Usage accounting: the one place that decides what an API call cost, and the
+// one place that refuses the next one when the money is gone.
+//
+// WHY the refusal lives HERE and not at each ceiling: there were three
+// guards reading three different numbers. agent.js priced the turn itself with
+// the local formula below, and checked it AFTER the turn; the session total in
+// the store was only topped up once the turn ended, so a ceiling consulted mid
+// turn could not see what the classifier and the fact extractor had already
+// spent; auto mode read a lagging delta of that same total. Three notebooks,
+// and four modules spending outside all of them. It leaked twice in two days,
+// in opposite directions.
+//
+// Now every call to the provider goes through src/api/client.js, and that door
+// asks this module two questions in order: may I, and then here is what it
+// cost. Nobody adds anything up, so nobody can forget to.
+//
+// WHY this exists: the cost was computed locally as
+// promptTokens * pricing.prompt + completionTokens * pricing.completion.
+// That is wrong by more than 2x on any model with prompt caching, because a
+// cache read costs ~120x less than a miss ($0.0036/M vs $0.435/M on
+// mimo-v2.5-pro), and the local table knows nothing about which tokens were
+// read from cache. The number is what the "is this expensive?" decision is
+// made on, so a wrong instrument is worse than none: on 2026-09-19 it led to
+// the conclusion that caching was broken when it was working.
+//
+// OpenRouter already returns the exact charge in `usage.cost` on every call,
+// streaming included, WITHOUT any request-body flag. So: take the provider's
+// number when it is there, estimate only when it is not, and never let an
+// estimate pass itself off as a fact.
+
+import { createLogger } from "../logging/logger.js";
+
+const log = createLogger("usage");
+
+// Where the fallback rate card comes from when the provider reports no cost.
+// Injected at startup (bootstrap.js) rather than imported, so this module stays
+// free of the store and can be exercised on its own.
+//
+// It is the MAIN model's card, and a side call may run on a cheaper model, so
+// what it produces is a ceiling, not a price. That is why it is reached only
+// when `usage.cost` is absent, and why everything it touches comes back
+// flagged `estimated`.
+let pricingSource = () => null;
+
+/** The model's context window in tokens, when the rate card knows it. */
+export function contextWindow() {
+  return pricingSource()?.contextLength || null;
+}
+
+export function setPricingSource(fn) {
+  pricingSource = typeof fn === "function" ? fn : () => null;
+}
+
+// `facts` is not on wip/judge-4758: the branch instrumented the classifier and
+// the extractor and missed memory/extract-facts.js, which agent.js fires on
+// every user message. Keep it when merging the rest of that branch's work.
+// `outcome` is the one question asked out of band: which of the three
+// things happened on a turn that changed nothing. It is a model call like any
+// other, so it has to show up in the bill, or the fix is invisible money.
+export const USAGE_SOURCES = ["agent", "classifier", "judge", "extractor", "facts", "outcome", "swap"];
+
+/**
+ * Normalize a provider `usage` object into the fields we account on.
+ * Understands the OpenAI/OpenRouter shape; the Anthropic adapter maps its
+ * own field names into the same shape before returning.
+ *
+ * @returns {null | {promptTokens, completionTokens, cachedTokens, cacheWriteTokens, cost}}
+ *   `cost` is null when the provider did not report one.
+ */
+export function readUsage(usage) {
+  if (!usage) return null;
+  const details = usage.prompt_tokens_details || {};
+  return {
+    promptTokens: usage.prompt_tokens || 0,
+    completionTokens: usage.completion_tokens || 0,
+    cachedTokens: details.cached_tokens || 0,
+    cacheWriteTokens: details.cache_write_tokens || 0,
+    cost: typeof usage.cost === "number" ? usage.cost : null,
+  };
+}
+
+/**
+ * What did this call cost, and do we actually know?
+ *
+ * Provider number wins. The fallback estimate still prices cached tokens at
+ * the cache-read rate when the model publishes one, so it is at least the
+ * right shape, but it is returned flagged, and every surface shows the flag.
+ *
+ * @returns {{cost: number, estimated: boolean}}
+ */
+export function priceUsage(u, pricing) {
+  if (!u) return { cost: 0, estimated: false };
+  if (u.cost != null) return { cost: u.cost, estimated: false };
+  if (!pricing) return { cost: 0, estimated: true };
+
+  // Cached tokens are included in prompt_tokens, so bill them once, cheaply.
+  const uncached = Math.max(0, u.promptTokens - u.cachedTokens);
+  const cacheRate = pricing.cacheRead != null ? pricing.cacheRead : pricing.prompt;
+  const cost =
+    uncached * pricing.prompt +
+    u.cachedTokens * cacheRate +
+    u.completionTokens * pricing.completion;
+  return { cost, estimated: true };
+}
+
+function emptyEntry() {
+  return {
+    calls: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    cachedTokens: 0,
+    cacheWriteTokens: 0,
+    cost: 0,
+    estimated: false,
+  };
+}
+
+function emptyLedger() {
+  // Built FROM the list, not repeated by hand. Repeating it cost eleven model
+  // calls: `outcome` was added to USAGE_SOURCES, the ledger was not touched,
+  // and recordUsage dropped every one of them on the floor because the entry
+  // did not exist. The list is the one place a source is declared.
+  const ledger = {};
+  for (const source of USAGE_SOURCES) {
+    ledger[source] = emptyEntry();
+  }
+  return ledger;
+}
+
+// What has been spent since the last drain, by source. `agent` has a row like
+// everything else: the main loop is not a special kind of money. Before, it
+// was priced separately by agent.js with the local formula, which is how the
+// per-turn ceiling ended up guarding a number that was wrong by more than 2x on
+// a cached model.
+let ledger = emptyLedger();
+
+// The three running totals, in dollars. They are three WINDOWS onto the same
+// stream of calls, not three tallies: every recorded call moves all three.
+//
+//   action   one turn. Reset by beginAction().
+//   session  everything since the session was opened or resumed.
+//   run      one autonomous run. Counted only while a run is open, because a
+//            run's ceiling is its own budget, not the session's history.
+//
+// Draining the by-source ledger for display does NOT touch them. A total that
+// resets when somebody looks at it is not a total.
+let spend = { action: 0, session: 0, run: 0 };
+let runOpen = false;
+let runLimit = 0;
+
+/** Thrown by the door instead of making the call. */
+export class BudgetExceededError extends Error {
+  constructor({ scope, spent, limit }) {
+    super(`Budget exhausted (${scope}): $${spent.toFixed(4)} of $${limit.toFixed(2)}`);
+    this.name = "BudgetExceededError";
+    this.isBudgetError = true;
+    this.scope = scope;
+    this.spent = spent;
+    this.limit = limit;
+  }
+}
+
+/** @returns {{action: number, session: number, run: number}} dollars spent */
+export function getSpend() {
+  return { ...spend };
+}
+
+/** A new turn starts. The per-action ceiling counts from here. */
+export function beginAction() {
+  spend.action = 0;
+}
+
+/**
+ * An autonomous run starts, with its own ceiling.
+ * @param {number} limit dollars; 0 or less means no ceiling of its own
+ */
+export function beginRun(limit = 0) {
+  spend.run = 0;
+  runLimit = limit > 0 ? limit : 0;
+  runOpen = true;
+}
+
+export function endRun() {
+  runOpen = false;
+  runLimit = 0;
+}
+
+/** Restore the session total when a saved session is reopened. */
+export function seedSessionSpend(cost) {
+  spend.session = typeof cost === "number" && cost > 0 ? cost : 0;
+}
+
+/** Start a fresh session: the session window goes back to zero, the run closes. */
+export function resetSessionSpend() {
+  spend = { action: 0, session: 0, run: 0 };
+  endRun();
+  ledger = emptyLedger();
+}
+
+/**
+ * Which ceiling, if any, has already been reached. The per-action and session
+ * ceilings are read from config by the caller (they can change mid-session via
+ * /budget), the run ceiling belongs to the open run.
+ *
+ * A ceiling of 0 means unlimited, which is the default for both config values.
+ *
+ * @returns {null | {scope: "action"|"session"|"run", spent: number, limit: number}}
+ */
+export function overBudget({ perAction = 0, session = 0 } = {}) {
+  if (perAction > 0 && spend.action >= perAction) {
+    return { scope: "action", spent: spend.action, limit: perAction };
+  }
+  if (session > 0 && spend.session >= session) {
+    return { scope: "session", spent: spend.session, limit: session };
+  }
+  if (runOpen && runLimit > 0 && spend.run >= runLimit) {
+    return { scope: "run", spent: spend.run, limit: runLimit };
+  }
+  return null;
+}
+
+/** overBudget, but it refuses instead of reporting. Throws BudgetExceededError. */
+export function assertWithinBudget(limits) {
+  const over = overBudget(limits);
+  if (over) {
+    log.warn("budget refusal", over);
+    throw new BudgetExceededError(over);
+  }
+}
+
+/**
+ * Record one call to the provider. Called by the door, by nobody else: a
+ * caller that has to remember this is a caller that will forget.
+ * Safe with a missing/!ok usage object.
+ * @param {"agent"|"classifier"|"judge"|"extractor"|"facts"|"outcome"} source
+ */
+export function recordUsage(source, usage, pricing = null) {
+  const entry = ledger[source];
+  if (!entry) {
+    // A source that is spent but not declared is money leaving with no row to
+    // show it. Say so loudly instead of returning quietly, which is how the
+    // `outcome` calls went missing in the first place.
+    log.error("usage for an unknown source", { source, known: Object.keys(ledger) });
+    return null;
+  }
+  const u = readUsage(usage);
+  if (!u) {
+    // The call happened and we cannot say what it cost. Saying nothing would
+    // silently understate the session, so mark the whole source as estimated.
+    entry.calls += 1;
+    entry.estimated = true;
+    return null;
+  }
+  const { cost, estimated } = priceUsage(u, pricing || pricingSource());
+  entry.calls += 1;
+  entry.promptTokens += u.promptTokens;
+  entry.completionTokens += u.completionTokens;
+  entry.cachedTokens += u.cachedTokens;
+  entry.cacheWriteTokens += u.cacheWriteTokens;
+  entry.cost += cost;
+  if (estimated) entry.estimated = true;
+
+  spend.action += cost;
+  spend.session += cost;
+  if (runOpen) spend.run += cost;
+
+  log.debug("usage", { source, promptTokens: u.promptTokens, cached: u.cachedTokens, cost, estimated });
+  return { ...u, cost, estimated };
+}
+
+/**
+ * Take everything recorded since the last drain, for the surfaces that display
+ * it. The running totals are deliberately left alone.
+ */
+export function drainUsage() {
+  const drained = ledger;
+  ledger = emptyLedger();
+  return drained;
+}
+
+/** Sum of a by-source map, for the totals line. */
+export function sumUsage(bySource) {
+  const total = emptyEntry();
+  for (const entry of Object.values(bySource || {})) {
+    if (!entry) continue;
+    total.calls += entry.calls || 0;
+    total.promptTokens += entry.promptTokens || 0;
+    total.completionTokens += entry.completionTokens || 0;
+    total.cachedTokens += entry.cachedTokens || 0;
+    total.cacheWriteTokens += entry.cacheWriteTokens || 0;
+    total.cost += entry.cost || 0;
+    if (entry.estimated) total.estimated = true;
+  }
+  return total;
+}
+
+export { emptyEntry };