floe-guard 0.2.1 → 0.4.0

package/dist/index.d.cts

@@ -64,6 +64,32 @@ declare namespace pricing {
  * same epsilon handling, same fail-closed default.
  */
 
+/**
+ * One priced spend event in the guard's per-call ledger.
+ *
+ * Every {@link BudgetGuard.record} / {@link BudgetGuard.settle} /
+ * {@link BudgetGuard.recordTool} that accrues spend appends exactly one event, so
+ * the ledger's costs sum to `spentUsd` (unless a `maxLogEvents` ring buffer has
+ * evicted old events). The schema is identical in the Python
+ * package (`SpendEvent` in `src/floe_guard/guard.py`) and
+ * {@link BudgetGuard.exportLog} serialises it with the same snake_case keys in
+ * both languages, so every agent emits the same shape regardless of stack.
+ */
+interface SpendEvent {
+    /** Unix epoch seconds (UTC). */
+    readonly timestamp: number;
+    readonly kind: "llm" | "tool";
+    readonly modelOrTool: string;
+    /** `null` for tool events. */
+    readonly promptTokens: number | null;
+    /** `null` for tool events. */
+    readonly completionTokens: number | null;
+    readonly costUsd: number;
+    /** Caller-supplied tag (agent/task name). */
+    readonly label?: string;
+    /** The reservation settled by this call, if any. */
+    readonly reserved?: number;
+}
 interface BudgetGuardOptions {
     /** Per-model manual prices for models the bundled cost map cannot price. */
     priceOverrides?: Record<string, ManualPrice>;
@@ -84,6 +110,13 @@ interface BudgetGuardOptions {
      * flags `nearLimit` so an agent can taper before the hard-stop. Default 8000.
      */
     nearLimitBps?: number;
+    /**
+     * Optional cap on the per-call spend ledger ({@link BudgetGuard.spendLog}).
+     * When set, the ledger is a ring buffer keeping the most recent N events so a
+     * long-running agent's memory stays bounded; the running totals are
+     * unaffected. Default: keep every event.
+     */
+    maxLogEvents?: number;
 }
 /**
  * A context-aware spend signal for the single local budget.
@@ -120,6 +153,9 @@ declare class BudgetGuard {
     private lastCost;
     /** USD held for in-flight calls (reserved, not yet settled). Counts toward the ceiling. */
     private reserved;
+    /** Per-call ledger, oldest first; a ring buffer when maxLogEvents is set. */
+    private readonly spendEvents;
+    private readonly maxLogEvents?;
     /**
      * @param limitUsd the spend ceiling, in USD. `0` blocks the very first call.
      */
@@ -152,11 +188,15 @@ declare class BudgetGuard {
      * 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: string, promptTokens: number, completionTokens: number, options?: {
         reserved?: number;
         price?: ManualPrice;
+        label?: string;
     }): number;
     /**
      * Price one response's tokens offline and add the cost to the total.
@@ -167,6 +207,21 @@ declare class BudgetGuard {
      */
     record(model: string, promptTokens: number, completionTokens: number, options?: {
         price?: ManualPrice;
+        label?: string;
+    }): number;
+    /**
+     * 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: string, costUsd: number, options?: {
+        label?: string;
     }): number;
     /**
      * Drop an in-flight reservation without recording spend (e.g. the call failed
@@ -175,6 +230,24 @@ declare class BudgetGuard {
     release(reserved: number): void;
     /** USD left before the ceiling, net of in-flight reservations (never negative). */
     get remainingUsd(): number;
+    /**
+     * 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(): SpendEvent[];
+    /**
+     * 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(): string;
+    private appendEvent;
     /**
      * Context-aware spend advisory for this budget — see {@link BudgetAdvisory}.
      *
@@ -185,6 +258,77 @@ declare class BudgetGuard {
     advisory(): BudgetAdvisory;
 }
 
+/**
+ * LatencyBudget — a cumulative tool-chain deadline, sibling to BudgetGuard.
+ *
+ * BudgetGuard stops an agent before its next call crosses a USD ceiling;
+ * LatencyBudget stops it before the next call would blow an end-user SLA:
+ *
+ * ```ts
+ * const deadline = new LatencyBudget(5000);
+ * ...
+ * deadline.check(800);                       // throws DeadlineExceeded when projected over
+ * if (deadline.advisory().nearDeadline) useFasterModel();
+ * router.pick({ maxLatencyMs: deadline.remainingMs });
+ * ```
+ *
+ * Design notes (mirroring `src/floe_guard/latency.py`):
+ * - **Monotonic clock** — `performance.now()`, never wall time.
+ * - **Cooperative, not preemptive** — the guard provides the deadline signal;
+ *   aborting a stalled in-flight call is the framework's job (AbortSignal).
+ *   `check()` prevents the NEXT call from starting.
+ * - **Advisory symmetry** — `nearDeadline` / `usedBps` / `remainingMs` are the
+ *   latency twin of BudgetGuard's `nearLimit` / `usedBps` / `remainingUsd`.
+ * - **In-process scope** — one instance per request/run; distributed latency
+ *   tracking is out of scope.
+ */
+/** A context-aware deadline signal — the latency twin of {@link BudgetAdvisory}.
+ *  Soft by design; the hard-stop is {@link LatencyBudget.check}. */
+interface LatencyAdvisory {
+    nearDeadline: boolean;
+    /** SLA consumed, basis points 0..10000 (8500 = 85%). */
+    usedBps: number;
+    remainingMs: number;
+    slaMs: number;
+    elapsedMs: number;
+}
+interface LatencyBudgetOptions {
+    /**
+     * Utilization (basis points, 0..10000) at which {@link LatencyBudget.advisory}
+     * flags `nearDeadline` so an agent can downshift to a faster path before the
+     * wall. Default 8000 (80%), matching BudgetGuard's `nearLimitBps`.
+     */
+    nearDeadlineBps?: number;
+    /** Invoked with `(elapsedMs, slaMs)` right before {@link DeadlineExceeded} is thrown. */
+    onBlock?: (elapsedMs: number, slaMs: number) => void;
+    /** Milliseconds-returning monotonic clock, injectable for tests. Defaults to `performance.now`. */
+    clock?: () => number;
+}
+declare class LatencyBudget {
+    readonly slaMs: number;
+    readonly nearDeadlineBps: number;
+    private readonly onBlock?;
+    private readonly clock;
+    private readonly startedAt;
+    /** The budget starts counting at construction — build it when the request
+     *  (and its SLA) starts. */
+    constructor(slaMs: number, options?: LatencyBudgetOptions);
+    /** Milliseconds since construction (monotonic). */
+    get elapsedMs(): number;
+    /** Milliseconds left before the SLA, floored at 0 — the readable signal a
+     *  router uses to pick a faster fallback or truncate work mid-chain. */
+    get remainingMs(): number;
+    /**
+     * Throw {@link DeadlineExceeded} when the projected elapsed time (now +
+     * `expectedMs` for the upcoming call) would blow the SLA. Call it
+     * immediately before each tool/model call; pass 0 to only gate on time
+     * already spent.
+     */
+    check(expectedMs?: number): void;
+    /** The soft near-deadline signal — symmetric to `BudgetGuard.advisory()`. */
+    advisory(): LatencyAdvisory;
+}
+
 /**
  * Exceptions for floe-guard.
  *
@@ -220,6 +364,11 @@ declare class UnpriceableModelError extends FloeGuardError {
     readonly model: string;
     constructor(model: string);
 }
+declare class DeadlineExceeded extends FloeGuardError {
+    readonly elapsedMs: number;
+    readonly slaMs: number;
+    constructor(elapsedMs: number, slaMs: number);
+}
 
 /**
  * Vercel AI SDK middleware that enforces a {@link BudgetGuard} in the call path.
@@ -290,4 +439,4 @@ interface BudgetGuardMiddleware {
  */
 declare function budgetGuardMiddleware(guard: BudgetGuard): BudgetGuardMiddleware;
 
-export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, FloeGuardError, type ManualPrice, type PricedModel, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice };
+export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, DeadlineExceeded, FloeGuardError, type LatencyAdvisory, LatencyBudget, type LatencyBudgetOptions, type ManualPrice, type PricedModel, type SpendEvent, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice };

package/dist/index.d.ts

@@ -64,6 +64,32 @@ declare namespace pricing {
  * same epsilon handling, same fail-closed default.
  */
 
+/**
+ * One priced spend event in the guard's per-call ledger.
+ *
+ * Every {@link BudgetGuard.record} / {@link BudgetGuard.settle} /
+ * {@link BudgetGuard.recordTool} that accrues spend appends exactly one event, so
+ * the ledger's costs sum to `spentUsd` (unless a `maxLogEvents` ring buffer has
+ * evicted old events). The schema is identical in the Python
+ * package (`SpendEvent` in `src/floe_guard/guard.py`) and
+ * {@link BudgetGuard.exportLog} serialises it with the same snake_case keys in
+ * both languages, so every agent emits the same shape regardless of stack.
+ */
+interface SpendEvent {
+    /** Unix epoch seconds (UTC). */
+    readonly timestamp: number;
+    readonly kind: "llm" | "tool";
+    readonly modelOrTool: string;
+    /** `null` for tool events. */
+    readonly promptTokens: number | null;
+    /** `null` for tool events. */
+    readonly completionTokens: number | null;
+    readonly costUsd: number;
+    /** Caller-supplied tag (agent/task name). */
+    readonly label?: string;
+    /** The reservation settled by this call, if any. */
+    readonly reserved?: number;
+}
 interface BudgetGuardOptions {
     /** Per-model manual prices for models the bundled cost map cannot price. */
     priceOverrides?: Record<string, ManualPrice>;
@@ -84,6 +110,13 @@ interface BudgetGuardOptions {
      * flags `nearLimit` so an agent can taper before the hard-stop. Default 8000.
      */
     nearLimitBps?: number;
+    /**
+     * Optional cap on the per-call spend ledger ({@link BudgetGuard.spendLog}).
+     * When set, the ledger is a ring buffer keeping the most recent N events so a
+     * long-running agent's memory stays bounded; the running totals are
+     * unaffected. Default: keep every event.
+     */
+    maxLogEvents?: number;
 }
 /**
  * A context-aware spend signal for the single local budget.
@@ -120,6 +153,9 @@ declare class BudgetGuard {
     private lastCost;
     /** USD held for in-flight calls (reserved, not yet settled). Counts toward the ceiling. */
     private reserved;
+    /** Per-call ledger, oldest first; a ring buffer when maxLogEvents is set. */
+    private readonly spendEvents;
+    private readonly maxLogEvents?;
     /**
      * @param limitUsd the spend ceiling, in USD. `0` blocks the very first call.
      */
@@ -152,11 +188,15 @@ declare class BudgetGuard {
      * 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: string, promptTokens: number, completionTokens: number, options?: {
         reserved?: number;
         price?: ManualPrice;
+        label?: string;
     }): number;
     /**
      * Price one response's tokens offline and add the cost to the total.
@@ -167,6 +207,21 @@ declare class BudgetGuard {
      */
     record(model: string, promptTokens: number, completionTokens: number, options?: {
         price?: ManualPrice;
+        label?: string;
+    }): number;
+    /**
+     * 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: string, costUsd: number, options?: {
+        label?: string;
     }): number;
     /**
      * Drop an in-flight reservation without recording spend (e.g. the call failed
@@ -175,6 +230,24 @@ declare class BudgetGuard {
     release(reserved: number): void;
     /** USD left before the ceiling, net of in-flight reservations (never negative). */
     get remainingUsd(): number;
+    /**
+     * 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(): SpendEvent[];
+    /**
+     * 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(): string;
+    private appendEvent;
     /**
      * Context-aware spend advisory for this budget — see {@link BudgetAdvisory}.
      *
@@ -185,6 +258,77 @@ declare class BudgetGuard {
     advisory(): BudgetAdvisory;
 }
 
+/**
+ * LatencyBudget — a cumulative tool-chain deadline, sibling to BudgetGuard.
+ *
+ * BudgetGuard stops an agent before its next call crosses a USD ceiling;
+ * LatencyBudget stops it before the next call would blow an end-user SLA:
+ *
+ * ```ts
+ * const deadline = new LatencyBudget(5000);
+ * ...
+ * deadline.check(800);                       // throws DeadlineExceeded when projected over
+ * if (deadline.advisory().nearDeadline) useFasterModel();
+ * router.pick({ maxLatencyMs: deadline.remainingMs });
+ * ```
+ *
+ * Design notes (mirroring `src/floe_guard/latency.py`):
+ * - **Monotonic clock** — `performance.now()`, never wall time.
+ * - **Cooperative, not preemptive** — the guard provides the deadline signal;
+ *   aborting a stalled in-flight call is the framework's job (AbortSignal).
+ *   `check()` prevents the NEXT call from starting.
+ * - **Advisory symmetry** — `nearDeadline` / `usedBps` / `remainingMs` are the
+ *   latency twin of BudgetGuard's `nearLimit` / `usedBps` / `remainingUsd`.
+ * - **In-process scope** — one instance per request/run; distributed latency
+ *   tracking is out of scope.
+ */
+/** A context-aware deadline signal — the latency twin of {@link BudgetAdvisory}.
+ *  Soft by design; the hard-stop is {@link LatencyBudget.check}. */
+interface LatencyAdvisory {
+    nearDeadline: boolean;
+    /** SLA consumed, basis points 0..10000 (8500 = 85%). */
+    usedBps: number;
+    remainingMs: number;
+    slaMs: number;
+    elapsedMs: number;
+}
+interface LatencyBudgetOptions {
+    /**
+     * Utilization (basis points, 0..10000) at which {@link LatencyBudget.advisory}
+     * flags `nearDeadline` so an agent can downshift to a faster path before the
+     * wall. Default 8000 (80%), matching BudgetGuard's `nearLimitBps`.
+     */
+    nearDeadlineBps?: number;
+    /** Invoked with `(elapsedMs, slaMs)` right before {@link DeadlineExceeded} is thrown. */
+    onBlock?: (elapsedMs: number, slaMs: number) => void;
+    /** Milliseconds-returning monotonic clock, injectable for tests. Defaults to `performance.now`. */
+    clock?: () => number;
+}
+declare class LatencyBudget {
+    readonly slaMs: number;
+    readonly nearDeadlineBps: number;
+    private readonly onBlock?;
+    private readonly clock;
+    private readonly startedAt;
+    /** The budget starts counting at construction — build it when the request
+     *  (and its SLA) starts. */
+    constructor(slaMs: number, options?: LatencyBudgetOptions);
+    /** Milliseconds since construction (monotonic). */
+    get elapsedMs(): number;
+    /** Milliseconds left before the SLA, floored at 0 — the readable signal a
+     *  router uses to pick a faster fallback or truncate work mid-chain. */
+    get remainingMs(): number;
+    /**
+     * Throw {@link DeadlineExceeded} when the projected elapsed time (now +
+     * `expectedMs` for the upcoming call) would blow the SLA. Call it
+     * immediately before each tool/model call; pass 0 to only gate on time
+     * already spent.
+     */
+    check(expectedMs?: number): void;
+    /** The soft near-deadline signal — symmetric to `BudgetGuard.advisory()`. */
+    advisory(): LatencyAdvisory;
+}
+
 /**
  * Exceptions for floe-guard.
  *
@@ -220,6 +364,11 @@ declare class UnpriceableModelError extends FloeGuardError {
     readonly model: string;
     constructor(model: string);
 }
+declare class DeadlineExceeded extends FloeGuardError {
+    readonly elapsedMs: number;
+    readonly slaMs: number;
+    constructor(elapsedMs: number, slaMs: number);
+}
 
 /**
  * Vercel AI SDK middleware that enforces a {@link BudgetGuard} in the call path.
@@ -290,4 +439,4 @@ interface BudgetGuardMiddleware {
  */
 declare function budgetGuardMiddleware(guard: BudgetGuard): BudgetGuardMiddleware;
 
-export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, FloeGuardError, type ManualPrice, type PricedModel, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice };
+export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, DeadlineExceeded, FloeGuardError, type LatencyAdvisory, LatencyBudget, type LatencyBudgetOptions, type ManualPrice, type PricedModel, type SpendEvent, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice };

package/dist/index.js

@@ -34,6 +34,21 @@ var UnpriceableModelError = class extends FloeGuardError {
     this.model = model;
   }
 };
+function roundHalfUp(ms) {
+  return Math.floor(ms + 0.5);
+}
+var DeadlineExceeded = class extends FloeGuardError {
+  elapsedMs;
+  slaMs;
+  constructor(elapsedMs, slaMs) {
+    super(
+      `DEADLINE EXCEEDED \u2014 call blocked (elapsed ${roundHalfUp(elapsedMs)}ms of ${roundHalfUp(slaMs)}ms SLA)`
+    );
+    this.name = "DeadlineExceeded";
+    this.elapsedMs = elapsedMs;
+    this.slaMs = slaMs;
+  }
+};
 
 // src/pricing.ts
 var pricing_exports = {};
@@ -952,6 +967,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.
    */
@@ -967,7 +985,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;
@@ -1029,7 +1053,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;
@@ -1066,6 +1093,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;
   }
   /**
@@ -1078,9 +1117,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`.
@@ -1096,6 +1166,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}.
    *
@@ -1127,6 +1237,68 @@ function defaultOnBlock(spentUsd, limitUsd) {
   );
 }
 
+// src/latency.ts
+var LatencyBudget = class {
+  slaMs;
+  nearDeadlineBps;
+  onBlock;
+  clock;
+  startedAt;
+  /** The budget starts counting at construction — build it when the request
+   *  (and its SLA) starts. */
+  constructor(slaMs, options = {}) {
+    if (!(Number.isFinite(slaMs) && slaMs > 0)) {
+      throw new RangeError("slaMs must be > 0");
+    }
+    const nearDeadlineBps = options.nearDeadlineBps ?? 8e3;
+    if (!Number.isInteger(nearDeadlineBps) || nearDeadlineBps < 0 || nearDeadlineBps > 1e4) {
+      throw new RangeError("nearDeadlineBps must be an integer 0..10000");
+    }
+    this.slaMs = slaMs;
+    this.nearDeadlineBps = nearDeadlineBps;
+    this.onBlock = options.onBlock;
+    this.clock = options.clock ?? (() => performance.now());
+    this.startedAt = this.clock();
+  }
+  /** Milliseconds since construction (monotonic). */
+  get elapsedMs() {
+    return this.clock() - this.startedAt;
+  }
+  /** Milliseconds left before the SLA, floored at 0 — the readable signal a
+   *  router uses to pick a faster fallback or truncate work mid-chain. */
+  get remainingMs() {
+    return Math.max(0, this.slaMs - this.elapsedMs);
+  }
+  /**
+   * Throw {@link DeadlineExceeded} when the projected elapsed time (now +
+   * `expectedMs` for the upcoming call) would blow the SLA. Call it
+   * immediately before each tool/model call; pass 0 to only gate on time
+   * already spent.
+   */
+  check(expectedMs = 0) {
+    if (!(Number.isFinite(expectedMs) && expectedMs >= 0)) {
+      throw new RangeError("expectedMs must be >= 0");
+    }
+    const elapsed = this.elapsedMs;
+    if (elapsed + expectedMs > this.slaMs) {
+      this.onBlock?.(elapsed, this.slaMs);
+      throw new DeadlineExceeded(elapsed, this.slaMs);
+    }
+  }
+  /** The soft near-deadline signal — symmetric to `BudgetGuard.advisory()`. */
+  advisory() {
+    const elapsed = this.elapsedMs;
+    const usedBps = elapsed > 0 ? Math.min(1e4, Math.round(elapsed * 1e4 / this.slaMs)) : 0;
+    return {
+      nearDeadline: usedBps >= this.nearDeadlineBps,
+      usedBps,
+      remainingMs: Math.max(0, this.slaMs - elapsed),
+      slaMs: this.slaMs,
+      elapsedMs: elapsed
+    };
+  }
+};
+
 // src/middleware.ts
 function usageTokens(modelId, usage) {
   const u = usage;
@@ -1219,7 +1391,9 @@ function budgetGuardMiddleware(guard) {
 export {
   BudgetExceeded,
   BudgetGuard,
+  DeadlineExceeded,
   FloeGuardError,
+  LatencyBudget,
   UnpriceableModelError,
   budgetGuardMiddleware,
   priceTokens,