floe-guard 0.4.0 → 0.6.0

package/README.md

@@ -4,9 +4,10 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../LICENSE)
 
 **A local budget guardrail for AI agents** — the TypeScript counterpart to the
-[Python `floe-guard`](../README.md). It hard-stops your agent *before its next LLM
-call* when it would cross a USD spend ceiling. No account, no signup, no network.
-Runs in your process.
+[Python `floe-guard`](../README.md). It hard-stops your agent *before its next
+LLM or paid tool call* when it would cross a USD spend ceiling — tokens and
+tool calls under one local ceiling. No account, no signup, no network. Runs in
+your process.
 
 Works with both **AI SDK v4 and v5** (`ai@4` / `ai@5`).
 
@@ -63,6 +64,21 @@ const adv = guard.advisory();
 const model = adv.nearLimit ? openai("gpt-4o-mini") : openai("gpt-4o");
 ```
 
+## Tool spend under the same ceiling
+
+Paid tool calls (Apollo, Exa, scrapers) burn the same budget as tokens. The
+full reserve/settle contract applies — and the price is known *before* the
+call, so the pre-call hard-stop is exact:
+
+```ts
+const handle = guard.reserveTool(0.02); // throws BudgetExceeded BEFORE the call
+const result = await apollo.peopleLookup(...);
+guard.settleTool("apollo.people_lookup", 0.02, { reserved: handle });
+
+guard.recordTool("exa.search", 0.004); // post-hoc, for metered APIs
+guard.toolCosts; // { "apollo.people_lookup": 0.42, "exa.search": 0.11 }
+```
+
 ## Per-call spend log
 
 The guard keeps a typed, in-memory ledger of everything it priced: each

package/dist/index.cjs

@@ -304,6 +304,222 @@ var cost_map_default = {
     litellm_provider: "openai",
     mode: "chat"
   },
+  "gemini-2.0-flash": {
+    input_cost_per_token: 1e-7,
+    output_cost_per_token: 4e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.0-flash-001": {
+    input_cost_per_token: 1e-7,
+    output_cost_per_token: 4e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.0-flash-lite": {
+    input_cost_per_token: 75e-9,
+    output_cost_per_token: 3e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.0-flash-lite-001": {
+    input_cost_per_token: 75e-9,
+    output_cost_per_token: 3e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-computer-use-preview-10-2025": {
+    input_cost_per_token: 125e-8,
+    output_cost_per_token: 1e-5,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-flash": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-flash-lite": {
+    input_cost_per_token: 1e-7,
+    output_cost_per_token: 4e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-flash-lite-preview-06-17": {
+    input_cost_per_token: 1e-7,
+    output_cost_per_token: 4e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-flash-lite-preview-09-2025": {
+    input_cost_per_token: 1e-7,
+    output_cost_per_token: 4e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-flash-native-audio-latest": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-flash-native-audio-preview-09-2025": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-flash-native-audio-preview-12-2025": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-flash-preview-09-2025": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-pro": {
+    input_cost_per_token: 125e-8,
+    output_cost_per_token: 1e-5,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-2.5-pro-preview-tts": {
+    input_cost_per_token: 125e-8,
+    output_cost_per_token: 1e-5,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3-flash-preview": {
+    input_cost_per_token: 5e-7,
+    output_cost_per_token: 3e-6,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3-pro-preview": {
+    input_cost_per_token: 2e-6,
+    output_cost_per_token: 12e-6,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3.1-flash-lite": {
+    input_cost_per_token: 25e-8,
+    output_cost_per_token: 15e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3.1-flash-lite-preview": {
+    input_cost_per_token: 25e-8,
+    output_cost_per_token: 15e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3.1-flash-live-preview": {
+    input_cost_per_token: 75e-8,
+    output_cost_per_token: 45e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3.1-pro-preview": {
+    input_cost_per_token: 2e-6,
+    output_cost_per_token: 12e-6,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3.1-pro-preview-customtools": {
+    input_cost_per_token: 2e-6,
+    output_cost_per_token: 12e-6,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3.5-flash": {
+    input_cost_per_token: 15e-7,
+    output_cost_per_token: 9e-6,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3.5-flash-lite": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-3.6-flash": {
+    input_cost_per_token: 15e-7,
+    output_cost_per_token: 75e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-embedding-001": {
+    input_cost_per_token: 15e-8,
+    output_cost_per_token: 0,
+    litellm_provider: "gemini",
+    mode: "embedding"
+  },
+  "gemini-embedding-2": {
+    input_cost_per_token: 2e-7,
+    output_cost_per_token: 0,
+    litellm_provider: "gemini",
+    mode: "embedding"
+  },
+  "gemini-embedding-2-preview": {
+    input_cost_per_token: 2e-7,
+    output_cost_per_token: 0,
+    litellm_provider: "gemini",
+    mode: "embedding"
+  },
+  "gemini-exp-1206": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-flash-latest": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-flash-lite-latest": {
+    input_cost_per_token: 1e-7,
+    output_cost_per_token: 4e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-gemma-2-27b-it": {
+    input_cost_per_token: 35e-8,
+    output_cost_per_token: 105e-8,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-gemma-2-9b-it": {
+    input_cost_per_token: 35e-8,
+    output_cost_per_token: 105e-8,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-omni-flash-preview": {
+    input_cost_per_token: 15e-7,
+    output_cost_per_token: 9e-6,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-pro-latest": {
+    input_cost_per_token: 125e-8,
+    output_cost_per_token: 1e-5,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
+  "gemini-robotics-er-1.5-preview": {
+    input_cost_per_token: 3e-7,
+    output_cost_per_token: 25e-7,
+    litellm_provider: "gemini",
+    mode: "chat"
+  },
   "gpt-3.5-turbo": {
     input_cost_per_token: 5e-7,
     output_cost_per_token: 15e-7,
@@ -478,18 +694,6 @@ var cost_map_default = {
     litellm_provider: "openai",
     mode: "chat"
   },
-  "gpt-4o-mini-realtime-preview": {
-    input_cost_per_token: 6e-7,
-    output_cost_per_token: 24e-7,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
-  "gpt-4o-mini-realtime-preview-2024-12-17": {
-    input_cost_per_token: 6e-7,
-    output_cost_per_token: 24e-7,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
   "gpt-4o-mini-search-preview": {
     input_cost_per_token: 15e-8,
     output_cost_per_token: 6e-7,
@@ -502,24 +706,6 @@ var cost_map_default = {
     litellm_provider: "openai",
     mode: "chat"
   },
-  "gpt-4o-realtime-preview": {
-    input_cost_per_token: 5e-6,
-    output_cost_per_token: 2e-5,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
-  "gpt-4o-realtime-preview-2024-12-17": {
-    input_cost_per_token: 5e-6,
-    output_cost_per_token: 2e-5,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
-  "gpt-4o-realtime-preview-2025-06-03": {
-    input_cost_per_token: 5e-6,
-    output_cost_per_token: 2e-5,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
   "gpt-4o-search-preview": {
     input_cost_per_token: 25e-7,
     output_cost_per_token: 1e-5,
@@ -742,60 +928,6 @@ var cost_map_default = {
     litellm_provider: "openai",
     mode: "chat"
   },
-  "gpt-realtime": {
-    input_cost_per_token: 4e-6,
-    output_cost_per_token: 16e-6,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
-  "gpt-realtime-1.5": {
-    input_cost_per_token: 4e-6,
-    output_cost_per_token: 16e-6,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
-  "gpt-realtime-2": {
-    input_cost_per_token: 4e-6,
-    output_cost_per_token: 16e-6,
-    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,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
-  "gpt-realtime-mini": {
-    input_cost_per_token: 6e-7,
-    output_cost_per_token: 24e-7,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
-  "gpt-realtime-mini-2025-10-06": {
-    input_cost_per_token: 6e-7,
-    output_cost_per_token: 24e-7,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
-  "gpt-realtime-mini-2025-12-15": {
-    input_cost_per_token: 6e-7,
-    output_cost_per_token: 24e-7,
-    litellm_provider: "openai",
-    mode: "chat"
-  },
   "llama-3.1-8b-instant": {
     input_cost_per_token: 5e-8,
     output_cost_per_token: 8e-8,
@@ -992,13 +1124,26 @@ var BudgetGuard = class {
   failClosed;
   nearLimitBps;
   onBlock;
-  /** Cost of the most recent priced call, used to predict the next one. */
-  lastCost = 0;
+  /**
+   * Costs of the most recent priced LLM call and tool call, tracked
+   * SEPARATELY: the default next-call prediction is the max of the two, so a
+   * cheap tool call can't shrink the estimate right before an expensive LLM
+   * call (or vice versa) — conservative beats one-call-too-late.
+   */
+  lastLlmCost = 0;
+  lastToolCost = 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;
+  /**
+   * Per-tool running totals (settleTool/recordTool) — the tool side of the one
+   * shared ceiling, exposed via the toolCosts getter. null-prototype: tool
+   * names are caller-supplied strings, so a "__proto__" name is stored as
+   * plain data instead of mutating the object's prototype.
+   */
+  toolCostTotals = /* @__PURE__ */ Object.create(null);
   /**
    * @param limitUsd the spend ceiling, in USD. `0` blocks the very first call.
    */
@@ -1030,7 +1175,8 @@ var BudgetGuard = class {
    * Throw {@link BudgetExceeded} if the next call would cross the ceiling.
    *
    * Call this immediately before each LLM request. The "next call" is estimated
-   * from the last recorded call's cost (override with `estimatedNextCost`); the
+   * conservatively as the costlier of the last LLM call and the last tool call
+   * (override with `estimatedNextCost`); the
    * first call is always allowed unless the ceiling is already met. In-flight
    * reservations count toward the total, so this stays correct alongside
    * {@link BudgetGuard.reserve}.
@@ -1039,7 +1185,7 @@ var BudgetGuard = class {
    * `settle()`, which hold the estimate across the await.
    */
   check(estimatedNextCost) {
-    const rawEstimate = estimatedNextCost === void 0 ? this.lastCost : estimatedNextCost;
+    const rawEstimate = estimatedNextCost === void 0 ? this.defaultEstimate() : estimatedNextCost;
     if (!Number.isFinite(rawEstimate)) {
       throw new RangeError(
         `estimatedNextCost must be a finite number, got ${rawEstimate}`
@@ -1060,10 +1206,11 @@ var BudgetGuard = class {
    * the same stale total. Throws {@link BudgetExceeded} (without reserving) if
    * the reservation would cross the ceiling. Returns the reservation handle to
    * pass to {@link BudgetGuard.settle} (or {@link BudgetGuard.release} on error).
-   * `estimatedCost` defaults to the last call's cost.
+   * `estimatedCost` defaults to the costlier of the last LLM call and the last
+   * tool call.
    */
   reserve(estimatedCost) {
-    const rawEstimate = estimatedCost === void 0 ? this.lastCost : estimatedCost;
+    const rawEstimate = estimatedCost === void 0 ? this.defaultEstimate() : estimatedCost;
     if (!Number.isFinite(rawEstimate)) {
       throw new RangeError(
         `estimatedCost must be a finite number, got ${rawEstimate}`
@@ -1115,13 +1262,13 @@ var BudgetGuard = class {
       throw err;
     }
     if (reserved) {
-      this.reserved = Math.max(0, this.reserved - reserved);
+      this.consumeReservation(reserved);
     }
     this.spentUsd += cost;
     if (this.spentUsd - this.limitUsd > 0 && this.spentUsd - this.limitUsd < EPS) {
       this.spentUsd = this.limitUsd;
     }
-    this.lastCost = cost;
+    this.lastLlmCost = cost;
     this.appendEvent({
       timestamp: Date.now() / 1e3,
       kind: "llm",
@@ -1151,24 +1298,64 @@ var BudgetGuard = class {
     });
   }
   /**
-   * Accrue a non-LLM cost (a paid tool/API call) against the same ceiling.
+   * Atomically check the ceiling AND hold a tool call's cost in flight.
    *
-   * 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`.
+   * The tool-spend counterpart of {@link BudgetGuard.reserve} — and STRONGER
+   * than the LLM path, because a paid tool's price is usually known exactly
+   * before the call, so the pre-call hard-stop is precise rather than
+   * estimated:
+   *
+   *     const handle = guard.reserveTool(0.02);   // throws BEFORE Apollo runs
+   *     const result = await apollo.peopleLookup(...);
+   *     guard.settleTool("apollo.people_lookup", 0.02, { reserved: handle });
+   *
+   * Throws {@link BudgetExceeded} (without reserving) if the call would cross
+   * the ceiling. The estimate is required — tools have no last-cost prediction
+   * worth falling back to. Pass the returned handle to
+   * {@link BudgetGuard.settleTool}, or {@link BudgetGuard.release} on failure.
    */
-  recordTool(tool, costUsd, options = {}) {
+  reserveTool(estimatedCost) {
+    if (estimatedCost === void 0) {
+      throw new RangeError("reserveTool requires an estimated cost, got undefined");
+    }
+    if (!Number.isFinite(estimatedCost) || estimatedCost < 0) {
+      throw new RangeError(
+        `estimatedCost must be a finite, non-negative number, got ${estimatedCost}`
+      );
+    }
+    return this.reserve(estimatedCost);
+  }
+  /**
+   * Release a reservation and record a tool call's actual cost.
+   *
+   * `recordTool` is `settleTool` with no reservation. The caller supplies the
+   * cost — tools have no token usage to price. Accrues into the same
+   * `spentUsd` ceiling as tokens, tallies the per-tool total
+   * ({@link BudgetGuard.toolCosts}), updates the tool side of the next-call
+   * estimate (tracked separately from the LLM side; the default prediction is
+   * the max of the two, so a tool-hammering loop's plain `check()` stops
+   * BEFORE the crossing call without a cheap tool shrinking the LLM
+   * prediction), and appends
+   * a `kind: "tool"` {@link SpendEvent} to {@link BudgetGuard.spendLog}.
+   * Returns `costUsd`.
+   */
+  settleTool(tool, costUsd, options = {}) {
     if (!Number.isFinite(costUsd) || costUsd < 0) {
       throw new RangeError(`costUsd must be a finite, non-negative number, got ${costUsd}`);
     }
+    const reserved = options.reserved ?? 0;
+    if (!Number.isFinite(reserved) || reserved < 0) {
+      throw new RangeError(`reserved must be a finite, non-negative number, got ${reserved}`);
+    }
+    if (reserved) {
+      this.consumeReservation(reserved);
+    }
     this.spentUsd += costUsd;
     if (this.spentUsd - this.limitUsd > 0 && this.spentUsd - this.limitUsd < EPS) {
       this.spentUsd = this.limitUsd;
     }
+    this.lastToolCost = costUsd;
+    this.toolCostTotals[tool] = (this.toolCostTotals[tool] ?? 0) + costUsd;
     this.appendEvent({
       timestamp: Date.now() / 1e3,
       kind: "tool",
@@ -1176,10 +1363,22 @@ var BudgetGuard = class {
       promptTokens: null,
       completionTokens: null,
       costUsd,
-      ...options.label !== void 0 ? { label: options.label } : {}
+      ...options.label !== void 0 ? { label: options.label } : {},
+      ...reserved ? { reserved } : {}
     });
     return costUsd;
   }
+  /**
+   * Accrue a non-LLM cost (a paid tool/API call) against the same ceiling.
+   *
+   * Post-hoc accrual for costs only known after the call (metered APIs); when
+   * the price is known up front, {@link BudgetGuard.reserveTool} /
+   * {@link BudgetGuard.settleTool} give the stronger pre-call hard-stop. See
+   * `settleTool` for the full contract. Returns `costUsd`.
+   */
+  recordTool(tool, costUsd, options = {}) {
+    return this.settleTool(tool, costUsd, { reserved: 0, label: options.label });
+  }
   /**
    * Drop an in-flight reservation without recording spend (e.g. the call failed
    * before producing usage). Safe to call with `0`.
@@ -1189,16 +1388,25 @@ var BudgetGuard = class {
       throw new RangeError(`reserved must be a finite, non-negative number, got ${reserved}`);
     }
     if (!reserved) return;
-    this.reserved = Math.max(0, this.reserved - reserved);
+    this.consumeReservation(reserved);
   }
   /** USD left before the ceiling, net of in-flight reservations (never negative). */
   get remainingUsd() {
     return Math.max(0, this.limitUsd - this.spentUsd - this.reserved);
   }
+  /**
+   * Per-tool running USD totals, keyed by the name given to `settleTool()` /
+   * `recordTool()` — e.g. `{"apollo.people_lookup": 0.42, "exa.search": 0.11}`.
+   * Makes the token/tool split of the one shared ceiling inspectable
+   * (`spentUsd - sum of toolCosts` is the token side). Returns a snapshot copy.
+   */
+  get toolCosts() {
+    return { ...this.toolCostTotals };
+  }
   /**
    * 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.
+   * `record()` / `settle()` / `recordTool()` / `settleTool()`. Returns a
+   * snapshot copy: mutating it cannot corrupt the ledger.
    */
   get spendLog() {
     return [...this.spendEvents];
@@ -1229,6 +1437,34 @@ var BudgetGuard = class {
 `;
     }).join("");
   }
+  /**
+   * The default next-call prediction when the caller supplies no estimate.
+   * Conservative: the costlier of the last LLM call and the last tool call — a
+   * mixed loop predicts the pricier kind, which at worst blocks one call early
+   * (fail-closed) rather than letting a crossing call through because the LAST
+   * event happened to be cheap.
+   */
+  defaultEstimate() {
+    return Math.max(this.lastLlmCost, this.lastToolCost);
+  }
+  /**
+   * Subtract a settled/released hold from the in-flight tally. A handle larger
+   * than EVERYTHING currently held cannot have come from a matching
+   * `reserve()` — throwing beats silently clamping, which would free OTHER
+   * callers' holds and fail the ceiling open. The epsilon absorbs float dust
+   * from accumulating and draining many holds; per-caller over-release (a
+   * handle within the total but larger than the caller's own hold) is
+   * undetectable without per-handle tracking and remains the caller's
+   * responsibility.
+   */
+  consumeReservation(reserved) {
+    if (reserved > this.reserved + EPS) {
+      throw new RangeError(
+        `reserved handle (${reserved}) exceeds total in-flight reservations (${this.reserved}) \u2014 a handle must come from a matching reserve()`
+      );
+    }
+    this.reserved = Math.max(0, this.reserved - reserved);
+  }
   appendEvent(event) {
     this.spendEvents.push(Object.freeze(event));
     if (this.maxLogEvents !== void 0 && this.spendEvents.length > this.maxLogEvents) {