floe-guard 0.2.0 → 0.3.0

package/README.md

@@ -63,6 +63,27 @@ const adv = guard.advisory();
 const model = adv.nearLimit ? openai("gpt-4o-mini") : openai("gpt-4o");
 ```
 
+## Per-call spend log
+
+The guard keeps a typed, in-memory ledger of everything it priced: each
+`record()` / `settle()` appends one `SpendEvent`, and `recordTool()` lets paid
+non-LLM calls spend the same budget and land in the same log. The events sum to
+`spentUsd` (unless a `maxLogEvents` ring buffer has evicted old ones).
+
+```ts
+const guard = new BudgetGuard(1.0); // { maxLogEvents: N } caps memory
+guard.record("gpt-4o", 1_200, 350, { label: "researcher" });
+guard.recordTool("serpapi.search", 0.01, { label: "researcher" });
+
+guard.spendLog; // [{ timestamp, kind: "llm", modelOrTool: "gpt-4o", … }, …]
+process.stdout.write(guard.exportLog()); // JSONL, one event per line
+```
+
+`exportLog()` emits a stable snake_case schema —
+`{timestamp, kind: llm|tool, model_or_tool, prompt_tokens, completion_tokens,
+cost_usd, label?, reserved?}` — identical to the Python package's
+`export_log()`, so every agent produces the same shape regardless of stack.
+
 ## Compatibility
 
 `ai` is declared as a peer dependency with the range `>=4.0.0 <6.0.0`:

package/dist/index.cjs

@@ -209,6 +209,12 @@ var cost_map_default = {
     litellm_provider: "anthropic",
     mode: "chat"
   },
+  "claude-sonnet-5": {
+    input_cost_per_token: 2e-6,
+    output_cost_per_token: 1e-5,
+    litellm_provider: "anthropic",
+    mode: "chat"
+  },
   "ft:gpt-3.5-turbo": {
     input_cost_per_token: 3e-6,
     output_cost_per_token: 6e-6,
@@ -659,6 +665,30 @@ var cost_map_default = {
     litellm_provider: "openai",
     mode: "chat"
   },
+  "gpt-5.6": {
+    input_cost_per_token: 5e-6,
+    output_cost_per_token: 3e-5,
+    litellm_provider: "openai",
+    mode: "chat"
+  },
+  "gpt-5.6-luna": {
+    input_cost_per_token: 1e-6,
+    output_cost_per_token: 6e-6,
+    litellm_provider: "openai",
+    mode: "chat"
+  },
+  "gpt-5.6-sol": {
+    input_cost_per_token: 5e-6,
+    output_cost_per_token: 3e-5,
+    litellm_provider: "openai",
+    mode: "chat"
+  },
+  "gpt-5.6-terra": {
+    input_cost_per_token: 25e-7,
+    output_cost_per_token: 15e-6,
+    litellm_provider: "openai",
+    mode: "chat"
+  },
   "gpt-audio": {
     input_cost_per_token: 25e-7,
     output_cost_per_token: 1e-5,
@@ -713,6 +743,18 @@ var cost_map_default = {
     litellm_provider: "openai",
     mode: "chat"
   },
+  "gpt-realtime-2.1": {
+    input_cost_per_token: 4e-6,
+    output_cost_per_token: 24e-6,
+    litellm_provider: "openai",
+    mode: "chat"
+  },
+  "gpt-realtime-2.1-mini": {
+    input_cost_per_token: 6e-7,
+    output_cost_per_token: 24e-7,
+    litellm_provider: "openai",
+    mode: "chat"
+  },
   "gpt-realtime-2025-08-28": {
     input_cost_per_token: 4e-6,
     output_cost_per_token: 16e-6,
@@ -803,6 +845,24 @@ var cost_map_default = {
     litellm_provider: "openai",
     mode: "chat"
   },
+  "openai/gpt-oss-120b": {
+    input_cost_per_token: 15e-8,
+    output_cost_per_token: 6e-7,
+    litellm_provider: "groq",
+    mode: "chat"
+  },
+  "openai/gpt-oss-20b": {
+    input_cost_per_token: 75e-9,
+    output_cost_per_token: 3e-7,
+    litellm_provider: "groq",
+    mode: "chat"
+  },
+  "openai/gpt-oss-safeguard-20b": {
+    input_cost_per_token: 75e-9,
+    output_cost_per_token: 3e-7,
+    litellm_provider: "groq",
+    mode: "chat"
+  },
   "qwen/qwen3-32b": {
     input_cost_per_token: 29e-8,
     output_cost_per_token: 59e-8,
@@ -837,39 +897,64 @@ var cost_map_default = {
 
 // src/pricing.ts
 var COST_MAP = cost_map_default;
-function bareModel(model) {
+var PROVIDER_PREFIXES = /* @__PURE__ */ new Set(["groq"]);
+var DATE_SUFFIX = /-(?:\d{8}|\d{4}-\d{2}-\d{2})$/;
+function candidateGroups(model) {
   const m = model.trim();
-  const slash = m.lastIndexOf("/");
-  return slash === -1 ? m : m.slice(slash + 1);
+  const base = [m];
+  const firstSlash = m.indexOf("/");
+  if (firstSlash !== -1 && PROVIDER_PREFIXES.has(m.slice(0, firstSlash))) {
+    base.push(m.slice(firstSlash + 1));
+  }
+  const lastSlash = m.lastIndexOf("/");
+  if (lastSlash !== -1) {
+    base.push(m.slice(lastSlash + 1));
+  }
+  const exact = [];
+  for (const cand of base) {
+    if (cand && !exact.includes(cand)) exact.push(cand);
+  }
+  const stripped = [];
+  for (const cand of exact) {
+    const c = cand.replace(DATE_SUFFIX, "");
+    if (c && !exact.includes(c) && !stripped.includes(c)) stripped.push(c);
+  }
+  return [exact, stripped];
 }
 function bothFinite(a, b) {
   return typeof a === "number" && typeof b === "number" && Number.isFinite(a) && Number.isFinite(b);
 }
 function resolvePrice(model, overrides) {
-  const bare = bareModel(model);
-  if (overrides) {
-    const ov = overrides[bare] ?? overrides[model.trim()];
-    if (ov !== void 0) {
-      if (bothFinite(ov.inputCostPerToken, ov.outputCostPerToken)) {
-        return {
-          inputCostPerToken: ov.inputCostPerToken,
-          outputCostPerToken: ov.outputCostPerToken,
-          source: "override"
-        };
+  for (const cands of candidateGroups(model)) {
+    if (overrides) {
+      for (const cand of cands) {
+        const ov = Object.prototype.hasOwnProperty.call(overrides, cand) ? overrides[cand] : void 0;
+        if (ov !== void 0) {
+          if (bothFinite(ov.inputCostPerToken, ov.outputCostPerToken)) {
+            return {
+              inputCostPerToken: ov.inputCostPerToken,
+              outputCostPerToken: ov.outputCostPerToken,
+              source: "override"
+            };
+          }
+          return null;
+        }
       }
-      return null;
+    }
+    for (const cand of cands) {
+      const entry = Object.prototype.hasOwnProperty.call(COST_MAP, cand) ? COST_MAP[cand] : void 0;
+      if (!entry) continue;
+      const input = entry.input_cost_per_token;
+      const output = entry.output_cost_per_token;
+      if (!bothFinite(input, output)) return null;
+      return {
+        inputCostPerToken: input,
+        outputCostPerToken: output,
+        source: "cost_map"
+      };
     }
   }
-  const entry = COST_MAP[bare] ?? COST_MAP[model.trim()];
-  if (!entry) return null;
-  const input = entry.input_cost_per_token;
-  const output = entry.output_cost_per_token;
-  if (!bothFinite(input, output)) return null;
-  return {
-    inputCostPerToken: input,
-    outputCostPerToken: output,
-    source: "cost_map"
-  };
+  return null;
 }
 function priceTokens(priced, promptTokens, completionTokens) {
   const p = Math.max(0, promptTokens);
@@ -894,6 +979,9 @@ var BudgetGuard = class {
   lastCost = 0;
   /** USD held for in-flight calls (reserved, not yet settled). Counts toward the ceiling. */
   reserved = 0;
+  /** Per-call ledger, oldest first; a ring buffer when maxLogEvents is set. */
+  spendEvents = [];
+  maxLogEvents;
   /**
    * @param limitUsd the spend ceiling, in USD. `0` blocks the very first call.
    */
@@ -909,7 +997,13 @@ var BudgetGuard = class {
         `nearLimitBps must be an integer in 0..10000, got ${nearLimitBps}`
       );
     }
+    if (options.maxLogEvents !== void 0 && (!Number.isInteger(options.maxLogEvents) || options.maxLogEvents < 0)) {
+      throw new RangeError(
+        `maxLogEvents must be a non-negative integer, got ${options.maxLogEvents}`
+      );
+    }
     this.limitUsd = limitUsd;
+    this.maxLogEvents = options.maxLogEvents;
     this.priceOverrides = options.priceOverrides;
     this.failClosed = options.failClosed ?? true;
     this.onBlock = options.onBlock ?? defaultOnBlock;
@@ -971,7 +1065,10 @@ var BudgetGuard = class {
    * Release a reservation and record the actual cost. `record` is `settle` with
    * no reservation. Returns the USD cost of this call; unpriceable-model handling
    * matches {@link BudgetGuard.record}, and any held reservation is released even
-   * on the warn-and-skip path.
+   * on the warn-and-skip path. A priced call appends one {@link SpendEvent} to
+   * {@link BudgetGuard.spendLog} (`label` tags it, e.g. with an agent/task name);
+   * the warn-and-skip path accrues nothing and logs nothing, so the ledger stays
+   * in lockstep with `spentUsd`.
    */
   settle(model, promptTokens, completionTokens, options = {}) {
     const reserved = options.reserved ?? 0;
@@ -1008,6 +1105,18 @@ var BudgetGuard = class {
       this.spentUsd = this.limitUsd;
     }
     this.lastCost = cost;
+    this.appendEvent({
+      timestamp: Date.now() / 1e3,
+      kind: "llm",
+      modelOrTool: model,
+      promptTokens,
+      completionTokens,
+      costUsd: cost,
+      ...options.label !== void 0 ? { label: options.label } : {},
+      // 0 means "no reservation" (the plain record() path) — omit rather than
+      // log a meaningless zero.
+      ...reserved ? { reserved } : {}
+    });
     return cost;
   }
   /**
@@ -1020,9 +1129,40 @@ var BudgetGuard = class {
   record(model, promptTokens, completionTokens, options = {}) {
     return this.settle(model, promptTokens, completionTokens, {
       reserved: 0,
-      price: options.price
+      price: options.price,
+      label: options.label
     });
   }
+  /**
+   * Accrue a non-LLM cost (a paid tool/API call) against the same ceiling.
+   *
+   * Tools with direct dollar costs — search APIs, scrapers, sandboxes — spend the
+   * same budget the LLM calls do; `recordTool` folds them into `spentUsd` (so
+   * `check()` / `reserve()` see them) and appends a `kind: "tool"`
+   * {@link SpendEvent} to {@link BudgetGuard.spendLog}. The caller supplies the
+   * cost: tools have no token usage to price. Deliberately does NOT update the
+   * next-call estimate — that predicts the next *LLM* call, and a tool's price
+   * would skew it. Returns `costUsd`.
+   */
+  recordTool(tool, costUsd, options = {}) {
+    if (!Number.isFinite(costUsd) || costUsd < 0) {
+      throw new RangeError(`costUsd must be a finite, non-negative number, got ${costUsd}`);
+    }
+    this.spentUsd += costUsd;
+    if (this.spentUsd - this.limitUsd > 0 && this.spentUsd - this.limitUsd < EPS) {
+      this.spentUsd = this.limitUsd;
+    }
+    this.appendEvent({
+      timestamp: Date.now() / 1e3,
+      kind: "tool",
+      modelOrTool: tool,
+      promptTokens: null,
+      completionTokens: null,
+      costUsd,
+      ...options.label !== void 0 ? { label: options.label } : {}
+    });
+    return costUsd;
+  }
   /**
    * Drop an in-flight reservation without recording spend (e.g. the call failed
    * before producing usage). Safe to call with `0`.
@@ -1038,6 +1178,46 @@ var BudgetGuard = class {
   get remainingUsd() {
     return Math.max(0, this.limitUsd - this.spentUsd - this.reserved);
   }
+  /**
+   * The per-call spend ledger, oldest first — one {@link SpendEvent} per priced
+   * `record()` / `settle()` / `recordTool()`. Returns a snapshot copy: mutating
+   * it cannot corrupt the ledger.
+   */
+  get spendLog() {
+    return [...this.spendEvents];
+  }
+  /**
+   * The spend ledger as JSONL — one event per line, newline-terminated.
+   *
+   * The schema is stable and language-independent (snake_case keys, fixed order;
+   * optional fields omitted when absent), identical to the Python package's
+   * `export_log()`, so heterogeneous agents produce logs you can concatenate and
+   * analyse as one stream. (The *schema* is the contract, not the bytes: the two
+   * runtimes may render the same float differently, e.g. JS `0.0000025` vs
+   * Python `2.5e-06`.) Empty ledger yields `""`.
+   */
+  exportLog() {
+    return this.spendEvents.map((e) => {
+      const row = {
+        timestamp: e.timestamp,
+        kind: e.kind,
+        model_or_tool: e.modelOrTool,
+        prompt_tokens: e.promptTokens,
+        completion_tokens: e.completionTokens,
+        cost_usd: e.costUsd
+      };
+      if (e.label !== void 0) row.label = e.label;
+      if (e.reserved !== void 0) row.reserved = e.reserved;
+      return `${JSON.stringify(row)}
+`;
+    }).join("");
+  }
+  appendEvent(event) {
+    this.spendEvents.push(Object.freeze(event));
+    if (this.maxLogEvents !== void 0 && this.spendEvents.length > this.maxLogEvents) {
+      this.spendEvents.splice(0, this.spendEvents.length - this.maxLogEvents);
+    }
+  }
   /**
    * Context-aware spend advisory for this budget — see {@link BudgetAdvisory}.
    *