floe-guard 0.13.0 → 0.13.2

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BudgetGuard, b as BudgetAdvisory } from './guard-BXtXoark.cjs';
-export { a as BudgetExceeded, c as BudgetGuardOptions, d as BudgetReservation, D as DeadlineExceeded, F as FloeGuardError, L as LedgerSyncError, M as ManualPrice, P as PricedModel, R as ReservationHandle, S as SpendEvent, T as TokenBudgetExceeded, U as UnpriceableModelError, e as UnpriceableVoiceError, p as priceTokens, f as pricing, r as resolvePrice } from './guard-BXtXoark.cjs';
+import { B as BudgetGuard, b as BudgetAdvisory } from './guard-Ct38zQZS.cjs';
+export { a as BudgetExceeded, c as BudgetGuardOptions, d as BudgetReservation, D as DeadlineExceeded, F as FloeGuardError, L as LedgerSyncError, M as ManualPrice, P as PricedModel, R as ReservationHandle, S as SpendEvent, T as TokenBudgetExceeded, U as UnpriceableModelError, e as UnpriceableVoiceError, p as priceTokens, f as pricing, r as resolvePrice } from './guard-Ct38zQZS.cjs';
 
 /**
  * LatencyBudget — a cumulative tool-chain deadline, sibling to BudgetGuard.
@@ -142,7 +142,9 @@ declare function pushLedger(jsonl: string, apiKey?: string, opts?: {
  * Reserving before the await is what makes parallel calls (`Promise.all` over
  * several generations) honour the ceiling: each holds its slice instead of all
  * reading the same stale total (issue #18). The reservation is released if the
- * call throws, or if a stream ends without reporting usage.
+ * call throws, is cancelled by the consumer, or if a stream completes without a
+ * usage-bearing finish part — in the last case the stream is also rejected with
+ * an error rather than treated as a free ($0) call (fail-closed).
  *
  * The model id used for pricing comes from `model.modelId`.
  */
@@ -205,7 +207,14 @@ interface BudgetRetryOptions<T> {
     maxAttempts?: number;
     /** Choose a cheaper retry plan when `guard.advisory().nearLimit` is true. */
     onDegrade?: (error: unknown, advisory: BudgetAdvisory) => RetryPlan<T> | Promise<RetryPlan<T> | undefined> | undefined;
-    /** Decide whether an error is retryable. Defaults to all non-budget errors. */
+    /**
+     * Decide whether an error is retryable.
+     *
+     * Defaults to all non-{@link FloeGuardError} errors — every
+     * {@link FloeGuardError} (including {@link BudgetExceeded} and
+     * {@link UnpriceableModelError}) is treated as terminal because retrying a
+     * deterministic guard error cannot fix it and would only multiply LLM spend.
+     */
     retryIf?: (error: unknown) => boolean;
 }
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BudgetGuard, b as BudgetAdvisory } from './guard-BXtXoark.js';
-export { a as BudgetExceeded, c as BudgetGuardOptions, d as BudgetReservation, D as DeadlineExceeded, F as FloeGuardError, L as LedgerSyncError, M as ManualPrice, P as PricedModel, R as ReservationHandle, S as SpendEvent, T as TokenBudgetExceeded, U as UnpriceableModelError, e as UnpriceableVoiceError, p as priceTokens, f as pricing, r as resolvePrice } from './guard-BXtXoark.js';
+import { B as BudgetGuard, b as BudgetAdvisory } from './guard-Ct38zQZS.js';
+export { a as BudgetExceeded, c as BudgetGuardOptions, d as BudgetReservation, D as DeadlineExceeded, F as FloeGuardError, L as LedgerSyncError, M as ManualPrice, P as PricedModel, R as ReservationHandle, S as SpendEvent, T as TokenBudgetExceeded, U as UnpriceableModelError, e as UnpriceableVoiceError, p as priceTokens, f as pricing, r as resolvePrice } from './guard-Ct38zQZS.js';
 
 /**
  * LatencyBudget — a cumulative tool-chain deadline, sibling to BudgetGuard.
@@ -142,7 +142,9 @@ declare function pushLedger(jsonl: string, apiKey?: string, opts?: {
  * Reserving before the await is what makes parallel calls (`Promise.all` over
  * several generations) honour the ceiling: each holds its slice instead of all
  * reading the same stale total (issue #18). The reservation is released if the
- * call throws, or if a stream ends without reporting usage.
+ * call throws, is cancelled by the consumer, or if a stream completes without a
+ * usage-bearing finish part — in the last case the stream is also rejected with
+ * an error rather than treated as a free ($0) call (fail-closed).
  *
  * The model id used for pricing comes from `model.modelId`.
  */
@@ -205,7 +207,14 @@ interface BudgetRetryOptions<T> {
     maxAttempts?: number;
     /** Choose a cheaper retry plan when `guard.advisory().nearLimit` is true. */
     onDegrade?: (error: unknown, advisory: BudgetAdvisory) => RetryPlan<T> | Promise<RetryPlan<T> | undefined> | undefined;
-    /** Decide whether an error is retryable. Defaults to all non-budget errors. */
+    /**
+     * Decide whether an error is retryable.
+     *
+     * Defaults to all non-{@link FloeGuardError} errors — every
+     * {@link FloeGuardError} (including {@link BudgetExceeded} and
+     * {@link UnpriceableModelError}) is treated as terminal because retrying a
+     * deterministic guard error cannot fix it and would only multiply LLM spend.
+     */
     retryIf?: (error: unknown) => boolean;
 }
 /**

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   priceVoiceLeg,
   resolveVoiceRate,
   voiceLegCost
-} from "./chunk-5Q5VQC6J.js";
+} from "./chunk-TAK6I7CN.js";
 
 // src/sync.ts
 var FLOE_API_KEY_ENV = "FLOE_API_KEY";
@@ -772,19 +772,21 @@ var BudgetGuard = class {
   }
   /**
    * 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).
+   * ceiling that blocks as `[dimension, scope, spent, limit]` — 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). `spent` / `limit` are captured here so `raiseBlock`
+   * (called outside the lock) reads no shared state and stays race-free.
    */
   blockingCross(estimateUsd, estimateTokens) {
     const committed = this.spentUsd + this.reserved;
     if (committed > this.limitUsd - EPS || committed + estimateUsd > this.limitUsd + EPS) {
-      return ["usd", "aggregate"];
+      return ["usd", "aggregate", this.spentUsd, this.limitUsd];
     }
     if (this.tokenLimit !== null) {
       const committedT = this.spentTokens + this.reservedTokens;
       if (committedT >= this.tokenLimit || committedT + estimateTokens > this.tokenLimit) {
-        return ["tokens", "aggregate"];
+        return ["tokens", "aggregate", committedT, this.tokenLimit];
       }
     }
     const step = this.steps.length ? this.steps[this.steps.length - 1] : null;
@@ -792,36 +794,26 @@ var BudgetGuard = class {
       if (step.maxUsd !== null) {
         const sCommitted = step.spentUsd + step.reservedUsd;
         if (sCommitted > step.maxUsd - EPS || sCommitted + estimateUsd > step.maxUsd + EPS) {
-          return ["usd", "step"];
+          return ["usd", "step", sCommitted, step.maxUsd];
         }
       }
       if (step.maxTokens !== null) {
         const sCommittedT = step.spentTokens + step.reservedTokens;
         if (sCommittedT >= step.maxTokens || sCommittedT + estimateTokens > step.maxTokens) {
-          return ["tokens", "step"];
+          return ["tokens", "step", sCommittedT, step.maxTokens];
         }
       }
     }
     return null;
   }
-  /** Notify + throw the right error for a [dimension, scope] block. */
+  /** Notify + throw the right error for a [dimension, scope, spent, limit] block. */
   raiseBlock(blocked) {
-    const [dimension, scope] = blocked;
+    const [dimension, scope, spent, limit] = blocked;
     if (dimension === "usd") {
-      this.onBlock(this.spentUsd, this.limitUsd);
-      throw new BudgetExceeded(this.spentUsd, this.limitUsd);
+      this.onBlock(spent, limit);
+      throw new BudgetExceeded(spent, limit);
     }
-    let spentT;
-    let limitT;
-    if (scope === "step") {
-      const step = this.steps[this.steps.length - 1];
-      spentT = step.spentTokens + step.reservedTokens;
-      limitT = step.maxTokens ?? 0;
-    } else {
-      spentT = this.spentTokens + this.reservedTokens;
-      limitT = this.tokenLimit ?? 0;
-    }
-    throw new TokenBudgetExceeded(spentT, limitT, scope);
+    throw new TokenBudgetExceeded(Math.trunc(spent), Math.trunc(limit), scope);
   }
   /**
    * Scope a per-step USD and/or token cap for a **sequential agent loop**.
@@ -1090,6 +1082,9 @@ function budgetGuardMiddleware(guard) {
             if (!handled) {
               handled = true;
               guard.release(reserved);
+              throw new Error(
+                `Model '${model.modelId}' stream completed without a token-usage finish part \u2014 the budget guard cannot meter spend it cannot see, so this call is rejected rather than treated as free.`
+              );
             }
           },
           cancel() {
@@ -1109,7 +1104,7 @@ function budgetGuardMiddleware(guard) {
 
 // src/retry.ts
 function defaultRetryIf(error) {
-  return !(error instanceof BudgetExceeded);
+  return !(error instanceof FloeGuardError);
 }
 async function withBudgetRetry(guard, call, options = {}) {
   const maxAttempts = options.maxAttempts ?? 2;