floe-guard 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -258,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.
  *
@@ -293,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.
@@ -363,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, type SpendEvent, 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

@@ -258,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.
  *
@@ -293,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.
@@ -363,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, type SpendEvent, 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 = {};
@@ -1222,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;
@@ -1314,7 +1391,9 @@ function budgetGuardMiddleware(guard) {
 export {
   BudgetExceeded,
   BudgetGuard,
+  DeadlineExceeded,
   FloeGuardError,
+  LatencyBudget,
   UnpriceableModelError,
   budgetGuardMiddleware,
   priceTokens,