Merge pull request #37 from Floe-Labs/latency-budget

feat: LatencyBudget — cumulative tool-chain deadline sibling to Budge…

Author: shivamfloe

CHANGELOG.md

@@ -10,6 +10,20 @@ both packages adhere to [Semantic Versioning](https://semver.org/).
 
 ## Unreleased
 
+## py 0.5.0 / js 0.4.0 — 2026-07-16
+
+### Added (py + js)
+
+- **`LatencyBudget`** — BudgetGuard's sibling for time: tracks cumulative
+  elapsed time across an agentic tool chain against an end-user SLA.
+  `check(expected_ms)` raises the new `DeadlineExceeded` before a call whose
+  projected duration would blow the SLA; `remaining_ms` is the readable
+  mid-chain signal for router fallback/truncation; `advisory()` returns
+  `near_deadline` / `used_bps` / `remaining_ms`, symmetric to the budget
+  advisory's `near_limit`. Monotonic clock (`time.monotonic` /
+  `performance.now`); cooperative by design — the guard supplies the deadline
+  signal, killing a stalled in-flight call remains the framework's job.
+
 ## py 0.4.0 — 2026-07-15
 
 ### Added (py)

README.md

@@ -175,6 +175,41 @@ cost_usd, label?, reserved?}` — identical to the TS package's `exportLog()`, s
 every agent produces the same shape regardless of stack and the streams can be
 concatenated and analysed together.
 
+## LatencyBudget — deadlines, the same way
+
+Money isn't the only budget an agent burns. `LatencyBudget` is `BudgetGuard`'s
+sibling for **time**: it tracks cumulative elapsed time across a tool chain
+against an end-user SLA and stops the *next* call before it would blow it.
+
+```python
+from floe_guard import LatencyBudget, DeadlineExceeded
+
+deadline = LatencyBudget(sla_ms=5000)          # the user is promised 5s
+
+for step in plan:
+    deadline.check(expected_ms=step.est_ms)    # raises DeadlineExceeded when projected over
+    model = DEFAULT_MODEL
+    if deadline.advisory().near_deadline:      # 80% consumed by default —
+        model = FAST_FALLBACK                  # downshift BEFORE the wall
+    run(step, model, timeout_ms=deadline.remaining_ms)
+```
+
+Same shape in TypeScript: `new LatencyBudget(5000)`, `check(expectedMs)`,
+`remainingMs`, `advisory().nearDeadline`.
+
+Honest scope, mirroring the rest of this package:
+
+- **Monotonic clock** (`time.monotonic()` / `performance.now()`) — NTP steps
+  and DST can't corrupt the budget.
+- **Cooperative, not preemptive.** The guard supplies the deadline *signal*;
+  killing an already-running stalled call is your framework's job (asyncio
+  cancellation, `AbortSignal`). `check()` prevents the next call from starting.
+- **Advisory symmetry.** `near_deadline` / `used_bps` / `remaining_ms` are the
+  latency twin of the budget advisory's `near_limit` / `used_bps` /
+  `remaining_usd` — taper logic written against one ports to the other.
+- **In-process.** One instance per request/run; distributed/server-side latency
+  tracking is out of scope.
+
 ## Request-sized estimates and mid-stream enforcement
 
 Two gaps in last-cost prediction, closed in 0.4.0 (Python):

js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "floe-guard",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A local budget guardrail for AI agents — hard-stops your agent before its next LLM call crosses a USD ceiling. Vercel AI SDK middleware.",
   "type": "module",
   "license": "MIT",

js/src/errors.ts

@@ -57,3 +57,37 @@ export class UnpriceableModelError extends FloeGuardError {
     this.model = model;
   }
 }
+
+/**
+ * Thrown before a call whose projected duration would blow the SLA.
+ *
+ * The latency twin of {@link BudgetExceeded}: `LatencyBudget.check()` throws this
+ * *instead of* letting the next tool/model call start, so the chain sheds work or
+ * falls back to a faster path rather than violating the end-user SLA. Cooperative —
+ * killing an already-running stalled call is the framework's job (AbortSignal),
+ * not the guard's.
+ *
+ * Mirrors `DeadlineExceeded` in `src/floe_guard/errors.py` — message format is
+ * kept byte-for-byte identical so both adapters read the same.
+ */
+/** Shared millisecond rounding for cross-language message parity: `toFixed(0)`
+ *  rounds half-up while Python's `:.0f` rounds half-to-even, so tie values
+ *  would break the byte-for-byte contract. Both packages use floor(x + 0.5)
+ *  (see `_round_half_up` in `src/floe_guard/errors.py`). */
+function roundHalfUp(ms: number): number {
+  return Math.floor(ms + 0.5);
+}
+
+export class DeadlineExceeded extends FloeGuardError {
+  readonly elapsedMs: number;
+  readonly slaMs: number;
+
+  constructor(elapsedMs: number, slaMs: number) {
+    super(
+      `DEADLINE EXCEEDED — call blocked (elapsed ${roundHalfUp(elapsedMs)}ms of ${roundHalfUp(slaMs)}ms SLA)`,
+    );
+    this.name = "DeadlineExceeded";
+    this.elapsedMs = elapsedMs;
+    this.slaMs = slaMs;
+  }
+}

js/src/index.ts

@@ -12,9 +12,15 @@ export {
   type BudgetAdvisory,
   type SpendEvent,
 } from "./guard.js";
+export {
+  LatencyBudget,
+  type LatencyBudgetOptions,
+  type LatencyAdvisory,
+} from "./latency.js";
 export {
   FloeGuardError,
   BudgetExceeded,
+  DeadlineExceeded,
   UnpriceableModelError,
 } from "./errors.js";
 export {

js/src/latency.ts

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+
+import { DeadlineExceeded } from "./errors.js";
+
+/** A context-aware deadline signal — the latency twin of {@link BudgetAdvisory}.
+ *  Soft by design; the hard-stop is {@link LatencyBudget.check}. */
+export interface LatencyAdvisory {
+  nearDeadline: boolean;
+  /** SLA consumed, basis points 0..10000 (8500 = 85%). */
+  usedBps: number;
+  remainingMs: number;
+  slaMs: number;
+  elapsedMs: number;
+}
+
+export 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;
+}
+
+export class LatencyBudget {
+  readonly slaMs: number;
+  readonly nearDeadlineBps: number;
+  private readonly onBlock?: (elapsedMs: number, slaMs: number) => void;
+  private readonly clock: () => number;
+  private readonly startedAt: number;
+
+  /** The budget starts counting at construction — build it when the request
+   *  (and its SLA) starts. */
+  constructor(slaMs: number, options: LatencyBudgetOptions = {}) {
+    if (!(Number.isFinite(slaMs) && slaMs > 0)) {
+      throw new RangeError("slaMs must be > 0");
+    }
+    const nearDeadlineBps = options.nearDeadlineBps ?? 8000;
+    if (!Number.isInteger(nearDeadlineBps) || nearDeadlineBps < 0 || nearDeadlineBps > 10000) {
+      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(): number {
+    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(): number {
+    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): void {
+    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(): LatencyAdvisory {
+    const elapsed = this.elapsedMs;
+    // round (not floor) — matches the Python twin; float clock arithmetic can
+    // land a hair under an exact boundary.
+    const usedBps = elapsed > 0 ? Math.min(10000, Math.round((elapsed * 10000) / this.slaMs)) : 0;
+    return {
+      nearDeadline: usedBps >= this.nearDeadlineBps,
+      usedBps,
+      remainingMs: Math.max(0, this.slaMs - elapsed),
+      slaMs: this.slaMs,
+      elapsedMs: elapsed,
+    };
+  }
+}

js/test/latency.test.ts

@@ -0,0 +1,101 @@
+/**
+ * LatencyBudget — cumulative tool-chain deadline (FLO-624).
+ *
+ * Mirrors tests/test_latency.py; an injectable fake clock keeps every test
+ * sleep-free.
+ */
+
+import { describe, it, expect } from "vitest";
+import { LatencyBudget, DeadlineExceeded } from "../src/index.js";
+
+function make(slaMs = 5000, options: Record<string, unknown> = {}) {
+  let now = 100_000; // arbitrary origin — only deltas matter
+  const clock = () => now;
+  const advanceMs = (ms: number) => {
+    now += ms;
+  };
+  const budget = new LatencyBudget(slaMs, { clock, ...options });
+  return { budget, advanceMs };
+}
+
+describe("LatencyBudget", () => {
+  it("check passes with headroom and blocks when projected over", () => {
+    const { budget, advanceMs } = make(5000);
+    advanceMs(3000);
+    expect(() => budget.check(1000)).not.toThrow(); // 3000 + 1000 <= 5000
+
+    expect(() => budget.check(2500)).toThrow(DeadlineExceeded); // projected over
+    try {
+      budget.check(2500);
+    } catch (e) {
+      expect((e as DeadlineExceeded).slaMs).toBe(5000);
+      expect((e as DeadlineExceeded).elapsedMs).toBeCloseTo(3000);
+    }
+  });
+
+  it("check without an estimate gates on elapsed only", () => {
+    const { budget, advanceMs } = make(1000);
+    advanceMs(999);
+    expect(() => budget.check()).not.toThrow();
+    advanceMs(2);
+    expect(() => budget.check()).toThrow(DeadlineExceeded);
+  });
+
+  it("remainingMs is readable mid-chain and floors at zero", () => {
+    const { budget, advanceMs } = make(5000);
+    advanceMs(1500);
+    expect(budget.remainingMs).toBeCloseTo(3500);
+    advanceMs(9000);
+    expect(budget.remainingMs).toBe(0);
+  });
+
+  it("advisory is symmetric to BudgetGuard's (nearDeadline at the 80% default)", () => {
+    const { budget, advanceMs } = make(5000);
+    advanceMs(2500);
+    const mid = budget.advisory();
+    expect(mid.usedBps).toBe(5000);
+    expect(mid.nearDeadline).toBe(false);
+    expect(mid.remainingMs).toBeCloseTo(2500);
+
+    advanceMs(1600); // 4100/5000 = 82%
+    const late = budget.advisory();
+    expect(late.usedBps).toBe(8200);
+    expect(late.nearDeadline).toBe(true);
+
+    advanceMs(9000);
+    expect(budget.advisory().usedBps).toBe(10000); // capped
+  });
+
+  it("onBlock fires before the throw", () => {
+    const calls: Array<[number, number]> = [];
+    const { budget, advanceMs } = make(1000, { onBlock: (e: number, s: number) => calls.push([e, s]) });
+    advanceMs(1500);
+    expect(() => budget.check()).toThrow(DeadlineExceeded);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]![1]).toBe(1000);
+  });
+
+  it("validates constructor and check inputs", () => {
+    expect(() => new LatencyBudget(0)).toThrow(RangeError);
+    expect(() => new LatencyBudget(5000, { nearDeadlineBps: 20000 })).toThrow(RangeError);
+    const { budget } = make();
+    expect(() => budget.check(-1)).toThrow(RangeError);
+  });
+
+  it("rejects non-finite inputs (inf would disable the deadline; NaN slips comparisons)", () => {
+    expect(() => new LatencyBudget(Infinity)).toThrow(RangeError);
+    expect(() => new LatencyBudget(NaN)).toThrow(RangeError);
+    const { budget } = make();
+    expect(() => budget.check(NaN)).toThrow(RangeError);
+    expect(() => budget.check(Infinity)).toThrow(RangeError);
+  });
+
+  it("deadline message uses the shared half-up rounding (byte-parity with Python)", () => {
+    expect(new DeadlineExceeded(0.5, 5000.5).message).toBe(
+      "DEADLINE EXCEEDED — call blocked (elapsed 1ms of 5001ms SLA)",
+    );
+    expect(new DeadlineExceeded(-0.5, 1000).message).toBe(
+      "DEADLINE EXCEEDED — call blocked (elapsed 0ms of 1000ms SLA)",
+    );
+  });
+});

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "floe-guard"
-version = "0.4.0"
+version = "0.5.0"
 description = "Local budget guardrail for AI agents — hard-stops a runaway loop before its next LLM call crosses a spend ceiling. No account, no network."
 readme = "README.md"
 requires-python = ">=3.10"

src/floe_guard/__init__.py

@@ -15,25 +15,30 @@
 
 from .errors import (
     BudgetExceeded,
+    DeadlineExceeded,
     FloeGuardError,
     HostedEnforcementError,
     UnpriceableModelError,
     UnpriceableModelWarning,
 )
 from .guard import BudgetAdvisory, BudgetGuard, SpendEvent
 from .hosted import hosted_enforcement_available, hosted_remaining_usd
+from .latency import LatencyAdvisory, LatencyBudget
 from .pricing import ManualPrice, PricedModel, price_tokens, resolve_price
 from .stream import StreamGuard, guard_stream
 
-__version__ = "0.4.0"  # keep in lockstep with pyproject.toml
+__version__ = "0.5.0"  # keep in lockstep with pyproject.toml
 
 __all__ = [
     "BudgetGuard",
     "BudgetAdvisory",
     "SpendEvent",
+    "LatencyBudget",
+    "LatencyAdvisory",
     "StreamGuard",
     "guard_stream",
     "BudgetExceeded",
+    "DeadlineExceeded",
     "FloeGuardError",
     "HostedEnforcementError",
     "UnpriceableModelError",