floe-guard 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -64,6 +64,23 @@ declare namespace pricing {
  * same epsilon handling, same fail-closed default.
  */
 
+/**
+ * A two-dimensional in-flight hold (USD + tokens) returned by
+ * {@link BudgetGuard.reserve} when a token ceiling or an active
+ * {@link BudgetGuard.step} is involved. A dumb value handle — pass it straight
+ * back to {@link BudgetGuard.settle} / {@link BudgetGuard.release}. When neither
+ * tokens nor a step are involved, `reserve` returns a plain `number` instead
+ * (byte-for-byte the old behaviour), so {@link ReservationHandle} is the union.
+ */
+interface BudgetReservation {
+    readonly usd: number;
+    readonly tokens: number;
+}
+/**
+ * A plain `number` when USD-only (backward compatible); a
+ * {@link BudgetReservation} when a token ceiling or an active step is in play.
+ */
+type ReservationHandle = number | BudgetReservation;
 /**
  * One priced spend event in the guard's per-call ledger.
  *
@@ -103,7 +120,9 @@ interface BudgetGuardOptions {
     /**
      * Optional callback invoked with `(spentUsd, limitUsd)` right before
      * {@link BudgetExceeded} is thrown. Defaults to printing the
-     * `BUDGET EXCEEDED — call blocked` banner to stderr.
+     * `BUDGET EXCEEDED — call blocked` banner to stderr. Fires on **USD** ceiling
+     * crossings only; a token-ceiling block ({@link TokenBudgetExceeded}, aggregate
+     * or step) is thrown without invoking it, since the callback is dollar-shaped.
      */
     onBlock?: (spentUsd: number, limitUsd: number) => void;
     /**
@@ -118,6 +137,11 @@ interface BudgetGuardOptions {
      * unaffected. Default: keep every event.
      */
     maxLogEvents?: number;
+    /**
+     * Aggregate token ceiling. `null`/undefined disables the token dimension
+     * entirely (a pure USD guard, unchanged). `0` blocks the first token.
+     */
+    tokenLimit?: number;
 }
 /**
  * A context-aware spend signal for the single local budget.
@@ -142,6 +166,35 @@ interface BudgetAdvisory {
     spentUsd: number;
     /** Hosted reports the tightest cap across all scopes; local is always "local". */
     scope: "local";
+    /**
+     * The guard's own next-call estimate (the costlier of the last LLM and last
+     * tool call — the same value the default reservation uses). 0 until the first
+     * call is recorded, so a planner can't divide by a cold estimate.
+     *
+     * Optional so adding it stays a non-breaking, additive change for any code
+     * that constructs a `BudgetAdvisory` literal; `advisory()` always sets it.
+     */
+    expectedCost?: number;
+    /**
+     * How many more calls the remaining budget buys at expectedCost:
+     * floor(remainingUsd / expectedCost). null when expectedCost is 0 (no call
+     * recorded yet) — unknown, not zero. Optional for the same additive reason as
+     * expectedCost; `advisory()` always sets it.
+     */
+    estCallsRemaining?: number | null;
+    /**
+     * Aggregate token utilization in basis points (0..10000), mirroring usedBps
+     * for the token ceiling. null when no `tokenLimit` is set (nothing to signal).
+     */
+    tokenUsedBps?: number | null;
+    /** Tokens left before the aggregate token ceiling. null when no `tokenLimit`. */
+    remainingTokens?: number | null;
+    /**
+     * Per-step headroom for the innermost active step — present (non-null) ONLY
+     * while a step() is active AND that dimension is capped. null otherwise.
+     */
+    stepRemainingUsd?: number | null;
+    stepRemainingTokens?: number | null;
 }
 declare class BudgetGuard {
     readonly limitUsd: number;
@@ -149,6 +202,14 @@ declare class BudgetGuard {
     priceOverrides?: Record<string, ManualPrice>;
     failClosed: boolean;
     nearLimitBps: number;
+    /** Aggregate token ceiling, or null when the token dimension is disabled. */
+    readonly tokenLimit: number | null;
+    /** Aggregate tokens accrued (prompt + completion + cache buckets). */
+    spentTokens: number;
+    /** Tokens held in-flight — the token twin of `reserved`. */
+    private reservedTokens;
+    /** Step stack: innermost step is last. Empty when no step() is active. */
+    private readonly steps;
     private readonly onBlock;
     /**
      * Costs of the most recent priced LLM call and tool call, tracked
@@ -187,7 +248,9 @@ declare class BudgetGuard {
      * Note: `check` is a non-binding peek. For parallel calls, use `reserve()` /
      * `settle()`, which hold the estimate across the await.
      */
-    check(estimatedNextCost?: number): void;
+    check(estimatedNextCost?: number, options?: {
+        estimatedTokens?: number;
+    }): void;
     /**
      * Atomically check the ceiling AND hold the estimated cost in flight.
      *
@@ -199,7 +262,9 @@ declare class BudgetGuard {
      * `estimatedCost` defaults to the costlier of the last LLM call and the last
      * tool call.
      */
-    reserve(estimatedCost?: number): number;
+    reserve(estimatedCost?: number, options?: {
+        estimatedTokens?: number;
+    }): ReservationHandle;
     /**
      * Release a reservation and record the actual cost. `record` is `settle` with
      * no reservation. Returns the USD cost of this call; unpriceable-model handling
@@ -210,7 +275,7 @@ declare class BudgetGuard {
      * in lockstep with `spentUsd`.
      */
     settle(model: string, promptTokens: number, completionTokens: number, options?: {
-        reserved?: number;
+        reserved?: ReservationHandle;
         price?: ManualPrice;
         label?: string;
     }): number;
@@ -242,7 +307,7 @@ declare class BudgetGuard {
      * worth falling back to. Pass the returned handle to
      * {@link BudgetGuard.settleTool}, or {@link BudgetGuard.release} on failure.
      */
-    reserveTool(estimatedCost: number): number;
+    reserveTool(estimatedCost: number): ReservationHandle;
     /**
      * Release a reservation and record a tool call's actual cost.
      *
@@ -258,7 +323,7 @@ declare class BudgetGuard {
      * Returns `costUsd`.
      */
     settleTool(tool: string, costUsd: number, options?: {
-        reserved?: number;
+        reserved?: ReservationHandle;
         label?: string;
     }): number;
     /**
@@ -276,7 +341,7 @@ declare class BudgetGuard {
      * Drop an in-flight reservation without recording spend (e.g. the call failed
      * before producing usage). Safe to call with `0`.
      */
-    release(reserved: number): void;
+    release(reserved: ReservationHandle): void;
     /** USD left before the ceiling, net of in-flight reservations (never negative). */
     get remainingUsd(): number;
     /**
@@ -322,6 +387,50 @@ declare class BudgetGuard {
      * responsibility.
      */
     private consumeReservation;
+    /**
+     * The USD amount of a handle, validated. Both shapes are checked — a raw
+     * number and a {@link BudgetReservation}'s `usd`/`tokens` fields — so a bad
+     * hand-rolled handle can't corrupt the in-flight tally.
+     */
+    /**
+     * Validate a caller-supplied token estimate. Rejects a fraction, NaN,
+     * Infinity, or boolean (via `Number.isInteger`) so it can't disable the
+     * integer token hard-stops or corrupt the in-flight token tally. `undefined`
+     * (the default) is fine; a negative integer is clamped by `Math.max(0, ...)`,
+     * matching the lenient USD estimate. Mirrors Python's `_validate_token_estimate`.
+     */
+    private validateTokenEstimate;
+    private reservedUsdOf;
+    /**
+     * Accrue a settled call into the innermost active step (no-op when none).
+     * Sequential-loop contract: the innermost step owns the call.
+     */
+    private accrueStep;
+    /**
+     * The ONE choke point, across two dimensions and two scopes. Returns the first
+     * ceiling that blocks as `[dimension, scope]` — dimension `"usd" | "tokens"`,
+     * scope `"aggregate" | "step"` — or `null` if the call fits everywhere.
+     * Aggregate is checked before step (the guard-wide ceiling is the hard limit).
+     */
+    private blockingCross;
+    /** Notify + throw the right error for a [dimension, scope] block. */
+    private raiseBlock;
+    /**
+     * Scope a per-step USD and/or token cap for a **sequential agent loop**.
+     *
+     * Runs `fn` with a step pushed onto the guard's stack; the
+     * enforcement/accrual path honours the innermost active step *on top of* the
+     * aggregate ceilings. A call that would cross the step's `maxUsd` / `maxTokens`
+     * is hard-blocked ({@link BudgetExceeded} / {@link TokenBudgetExceeded} with
+     * `scope: "step"`) even if the aggregate budget has room. `fn` receives the
+     * SAME guard, so no adapter needs to know about steps. The step is popped when
+     * `fn` settles or throws. **Not for concurrent parallel steps on one guard** —
+     * that's out of scope for issue #46; use one guard per parallel branch.
+     */
+    step<T>(options: {
+        maxUsd?: number;
+        maxTokens?: number;
+    }, fn: (guard: BudgetGuard) => T): T;
     private appendEvent;
     /**
      * Context-aware spend advisory for this budget — see {@link BudgetAdvisory}.
@@ -426,7 +535,25 @@ declare class FloeGuardError extends Error {
 declare class BudgetExceeded extends FloeGuardError {
     readonly spentUsd: number;
     readonly limitUsd: number;
-    constructor(spentUsd: number, limitUsd: number);
+    constructor(spentUsd: number, limitUsd: number, message?: string);
+}
+/**
+ * Thrown before a call that would cross a token ceiling (aggregate or step).
+ *
+ * The token twin of {@link BudgetExceeded} — it extends it so the same retry
+ * logic that treats a USD block as terminal (`!(error instanceof
+ * BudgetExceeded)`) treats a token block as terminal too, with no extra wiring.
+ * `spentUsd` / `limitUsd` are inherited but not meaningful here; the token
+ * fields are the payload.
+ *
+ * `scope` is `"aggregate"` (the guard-wide `tokenLimit`) or `"step"` (the
+ * innermost active {@link BudgetGuard.step} cap).
+ */
+declare class TokenBudgetExceeded extends BudgetExceeded {
+    readonly spentTokens: number;
+    readonly limitTokens: number;
+    readonly scope: "aggregate" | "step";
+    constructor(spentTokens: number, limitTokens: number, scope: "aggregate" | "step");
 }
 /**
  * Thrown when a model cannot be priced and the guard is fail-closed.
@@ -543,4 +670,4 @@ interface BudgetRetryOptions<T> {
  */
 declare function withBudgetRetry<T>(guard: BudgetGuard, call: () => T | Promise<T>, options?: BudgetRetryOptions<T>): Promise<T>;
 
-export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, type BudgetRetryOptions, DeadlineExceeded, FloeGuardError, type LatencyAdvisory, LatencyBudget, type LatencyBudgetOptions, type ManualPrice, type PricedModel, type RetryPlan, type SpendEvent, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice, withBudgetRetry };
+export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, type BudgetReservation, type BudgetRetryOptions, DeadlineExceeded, FloeGuardError, type LatencyAdvisory, LatencyBudget, type LatencyBudgetOptions, type ManualPrice, type PricedModel, type ReservationHandle, type RetryPlan, type SpendEvent, TokenBudgetExceeded, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice, withBudgetRetry };

package/dist/index.d.ts

@@ -64,6 +64,23 @@ declare namespace pricing {
  * same epsilon handling, same fail-closed default.
  */
 
+/**
+ * A two-dimensional in-flight hold (USD + tokens) returned by
+ * {@link BudgetGuard.reserve} when a token ceiling or an active
+ * {@link BudgetGuard.step} is involved. A dumb value handle — pass it straight
+ * back to {@link BudgetGuard.settle} / {@link BudgetGuard.release}. When neither
+ * tokens nor a step are involved, `reserve` returns a plain `number` instead
+ * (byte-for-byte the old behaviour), so {@link ReservationHandle} is the union.
+ */
+interface BudgetReservation {
+    readonly usd: number;
+    readonly tokens: number;
+}
+/**
+ * A plain `number` when USD-only (backward compatible); a
+ * {@link BudgetReservation} when a token ceiling or an active step is in play.
+ */
+type ReservationHandle = number | BudgetReservation;
 /**
  * One priced spend event in the guard's per-call ledger.
  *
@@ -103,7 +120,9 @@ interface BudgetGuardOptions {
     /**
      * Optional callback invoked with `(spentUsd, limitUsd)` right before
      * {@link BudgetExceeded} is thrown. Defaults to printing the
-     * `BUDGET EXCEEDED — call blocked` banner to stderr.
+     * `BUDGET EXCEEDED — call blocked` banner to stderr. Fires on **USD** ceiling
+     * crossings only; a token-ceiling block ({@link TokenBudgetExceeded}, aggregate
+     * or step) is thrown without invoking it, since the callback is dollar-shaped.
      */
     onBlock?: (spentUsd: number, limitUsd: number) => void;
     /**
@@ -118,6 +137,11 @@ interface BudgetGuardOptions {
      * unaffected. Default: keep every event.
      */
     maxLogEvents?: number;
+    /**
+     * Aggregate token ceiling. `null`/undefined disables the token dimension
+     * entirely (a pure USD guard, unchanged). `0` blocks the first token.
+     */
+    tokenLimit?: number;
 }
 /**
  * A context-aware spend signal for the single local budget.
@@ -142,6 +166,35 @@ interface BudgetAdvisory {
     spentUsd: number;
     /** Hosted reports the tightest cap across all scopes; local is always "local". */
     scope: "local";
+    /**
+     * The guard's own next-call estimate (the costlier of the last LLM and last
+     * tool call — the same value the default reservation uses). 0 until the first
+     * call is recorded, so a planner can't divide by a cold estimate.
+     *
+     * Optional so adding it stays a non-breaking, additive change for any code
+     * that constructs a `BudgetAdvisory` literal; `advisory()` always sets it.
+     */
+    expectedCost?: number;
+    /**
+     * How many more calls the remaining budget buys at expectedCost:
+     * floor(remainingUsd / expectedCost). null when expectedCost is 0 (no call
+     * recorded yet) — unknown, not zero. Optional for the same additive reason as
+     * expectedCost; `advisory()` always sets it.
+     */
+    estCallsRemaining?: number | null;
+    /**
+     * Aggregate token utilization in basis points (0..10000), mirroring usedBps
+     * for the token ceiling. null when no `tokenLimit` is set (nothing to signal).
+     */
+    tokenUsedBps?: number | null;
+    /** Tokens left before the aggregate token ceiling. null when no `tokenLimit`. */
+    remainingTokens?: number | null;
+    /**
+     * Per-step headroom for the innermost active step — present (non-null) ONLY
+     * while a step() is active AND that dimension is capped. null otherwise.
+     */
+    stepRemainingUsd?: number | null;
+    stepRemainingTokens?: number | null;
 }
 declare class BudgetGuard {
     readonly limitUsd: number;
@@ -149,6 +202,14 @@ declare class BudgetGuard {
     priceOverrides?: Record<string, ManualPrice>;
     failClosed: boolean;
     nearLimitBps: number;
+    /** Aggregate token ceiling, or null when the token dimension is disabled. */
+    readonly tokenLimit: number | null;
+    /** Aggregate tokens accrued (prompt + completion + cache buckets). */
+    spentTokens: number;
+    /** Tokens held in-flight — the token twin of `reserved`. */
+    private reservedTokens;
+    /** Step stack: innermost step is last. Empty when no step() is active. */
+    private readonly steps;
     private readonly onBlock;
     /**
      * Costs of the most recent priced LLM call and tool call, tracked
@@ -187,7 +248,9 @@ declare class BudgetGuard {
      * Note: `check` is a non-binding peek. For parallel calls, use `reserve()` /
      * `settle()`, which hold the estimate across the await.
      */
-    check(estimatedNextCost?: number): void;
+    check(estimatedNextCost?: number, options?: {
+        estimatedTokens?: number;
+    }): void;
     /**
      * Atomically check the ceiling AND hold the estimated cost in flight.
      *
@@ -199,7 +262,9 @@ declare class BudgetGuard {
      * `estimatedCost` defaults to the costlier of the last LLM call and the last
      * tool call.
      */
-    reserve(estimatedCost?: number): number;
+    reserve(estimatedCost?: number, options?: {
+        estimatedTokens?: number;
+    }): ReservationHandle;
     /**
      * Release a reservation and record the actual cost. `record` is `settle` with
      * no reservation. Returns the USD cost of this call; unpriceable-model handling
@@ -210,7 +275,7 @@ declare class BudgetGuard {
      * in lockstep with `spentUsd`.
      */
     settle(model: string, promptTokens: number, completionTokens: number, options?: {
-        reserved?: number;
+        reserved?: ReservationHandle;
         price?: ManualPrice;
         label?: string;
     }): number;
@@ -242,7 +307,7 @@ declare class BudgetGuard {
      * worth falling back to. Pass the returned handle to
      * {@link BudgetGuard.settleTool}, or {@link BudgetGuard.release} on failure.
      */
-    reserveTool(estimatedCost: number): number;
+    reserveTool(estimatedCost: number): ReservationHandle;
     /**
      * Release a reservation and record a tool call's actual cost.
      *
@@ -258,7 +323,7 @@ declare class BudgetGuard {
      * Returns `costUsd`.
      */
     settleTool(tool: string, costUsd: number, options?: {
-        reserved?: number;
+        reserved?: ReservationHandle;
         label?: string;
     }): number;
     /**
@@ -276,7 +341,7 @@ declare class BudgetGuard {
      * Drop an in-flight reservation without recording spend (e.g. the call failed
      * before producing usage). Safe to call with `0`.
      */
-    release(reserved: number): void;
+    release(reserved: ReservationHandle): void;
     /** USD left before the ceiling, net of in-flight reservations (never negative). */
     get remainingUsd(): number;
     /**
@@ -322,6 +387,50 @@ declare class BudgetGuard {
      * responsibility.
      */
     private consumeReservation;
+    /**
+     * The USD amount of a handle, validated. Both shapes are checked — a raw
+     * number and a {@link BudgetReservation}'s `usd`/`tokens` fields — so a bad
+     * hand-rolled handle can't corrupt the in-flight tally.
+     */
+    /**
+     * Validate a caller-supplied token estimate. Rejects a fraction, NaN,
+     * Infinity, or boolean (via `Number.isInteger`) so it can't disable the
+     * integer token hard-stops or corrupt the in-flight token tally. `undefined`
+     * (the default) is fine; a negative integer is clamped by `Math.max(0, ...)`,
+     * matching the lenient USD estimate. Mirrors Python's `_validate_token_estimate`.
+     */
+    private validateTokenEstimate;
+    private reservedUsdOf;
+    /**
+     * Accrue a settled call into the innermost active step (no-op when none).
+     * Sequential-loop contract: the innermost step owns the call.
+     */
+    private accrueStep;
+    /**
+     * The ONE choke point, across two dimensions and two scopes. Returns the first
+     * ceiling that blocks as `[dimension, scope]` — dimension `"usd" | "tokens"`,
+     * scope `"aggregate" | "step"` — or `null` if the call fits everywhere.
+     * Aggregate is checked before step (the guard-wide ceiling is the hard limit).
+     */
+    private blockingCross;
+    /** Notify + throw the right error for a [dimension, scope] block. */
+    private raiseBlock;
+    /**
+     * Scope a per-step USD and/or token cap for a **sequential agent loop**.
+     *
+     * Runs `fn` with a step pushed onto the guard's stack; the
+     * enforcement/accrual path honours the innermost active step *on top of* the
+     * aggregate ceilings. A call that would cross the step's `maxUsd` / `maxTokens`
+     * is hard-blocked ({@link BudgetExceeded} / {@link TokenBudgetExceeded} with
+     * `scope: "step"`) even if the aggregate budget has room. `fn` receives the
+     * SAME guard, so no adapter needs to know about steps. The step is popped when
+     * `fn` settles or throws. **Not for concurrent parallel steps on one guard** —
+     * that's out of scope for issue #46; use one guard per parallel branch.
+     */
+    step<T>(options: {
+        maxUsd?: number;
+        maxTokens?: number;
+    }, fn: (guard: BudgetGuard) => T): T;
     private appendEvent;
     /**
      * Context-aware spend advisory for this budget — see {@link BudgetAdvisory}.
@@ -426,7 +535,25 @@ declare class FloeGuardError extends Error {
 declare class BudgetExceeded extends FloeGuardError {
     readonly spentUsd: number;
     readonly limitUsd: number;
-    constructor(spentUsd: number, limitUsd: number);
+    constructor(spentUsd: number, limitUsd: number, message?: string);
+}
+/**
+ * Thrown before a call that would cross a token ceiling (aggregate or step).
+ *
+ * The token twin of {@link BudgetExceeded} — it extends it so the same retry
+ * logic that treats a USD block as terminal (`!(error instanceof
+ * BudgetExceeded)`) treats a token block as terminal too, with no extra wiring.
+ * `spentUsd` / `limitUsd` are inherited but not meaningful here; the token
+ * fields are the payload.
+ *
+ * `scope` is `"aggregate"` (the guard-wide `tokenLimit`) or `"step"` (the
+ * innermost active {@link BudgetGuard.step} cap).
+ */
+declare class TokenBudgetExceeded extends BudgetExceeded {
+    readonly spentTokens: number;
+    readonly limitTokens: number;
+    readonly scope: "aggregate" | "step";
+    constructor(spentTokens: number, limitTokens: number, scope: "aggregate" | "step");
 }
 /**
  * Thrown when a model cannot be priced and the guard is fail-closed.
@@ -543,4 +670,4 @@ interface BudgetRetryOptions<T> {
  */
 declare function withBudgetRetry<T>(guard: BudgetGuard, call: () => T | Promise<T>, options?: BudgetRetryOptions<T>): Promise<T>;
 
-export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, type BudgetRetryOptions, DeadlineExceeded, FloeGuardError, type LatencyAdvisory, LatencyBudget, type LatencyBudgetOptions, type ManualPrice, type PricedModel, type RetryPlan, type SpendEvent, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice, withBudgetRetry };
+export { type BudgetAdvisory, BudgetExceeded, BudgetGuard, type BudgetGuardMiddleware, type BudgetGuardOptions, type BudgetReservation, type BudgetRetryOptions, DeadlineExceeded, FloeGuardError, type LatencyAdvisory, LatencyBudget, type LatencyBudgetOptions, type ManualPrice, type PricedModel, type ReservationHandle, type RetryPlan, type SpendEvent, TokenBudgetExceeded, UnpriceableModelError, budgetGuardMiddleware, priceTokens, pricing, resolvePrice, withBudgetRetry };