floe-guard 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -142,6 +142,22 @@ 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;
 }
 declare class BudgetGuard {
     readonly limitUsd: number;
@@ -514,4 +530,33 @@ interface BudgetGuardMiddleware {
  */
 declare function budgetGuardMiddleware(guard: BudgetGuard): BudgetGuardMiddleware;
 
-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 };
+interface RetryPlan<T> {
+    /** Operation to run for this retry attempt. */
+    call: () => T | Promise<T>;
+    /**
+     * Estimated retry cost passed to `guard.check()` before the retry runs.
+     * Leave undefined to use the guard's default last-call estimate.
+     */
+    estimatedCost?: number;
+}
+interface BudgetRetryOptions<T> {
+    /** Estimated cost for retrying the original call. */
+    estimatedCost?: number;
+    /** Total attempts, including the first call. Default: 2. */
+    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. */
+    retryIf?: (error: unknown) => boolean;
+}
+/**
+ * Run `call` with budget-aware retries.
+ *
+ * The first attempt runs unchanged. If it fails with a retryable error, the
+ * helper retries as-is with ample budget, asks `onDegrade` for a cheaper plan
+ * when near the limit, and always calls `guard.check(estimatedCost)` before a
+ * retry so an over-budget retry is blocked before it runs.
+ */
+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 };

package/dist/index.d.ts

@@ -142,6 +142,22 @@ 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;
 }
 declare class BudgetGuard {
     readonly limitUsd: number;
@@ -514,4 +530,33 @@ interface BudgetGuardMiddleware {
  */
 declare function budgetGuardMiddleware(guard: BudgetGuard): BudgetGuardMiddleware;
 
-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 };
+interface RetryPlan<T> {
+    /** Operation to run for this retry attempt. */
+    call: () => T | Promise<T>;
+    /**
+     * Estimated retry cost passed to `guard.check()` before the retry runs.
+     * Leave undefined to use the guard's default last-call estimate.
+     */
+    estimatedCost?: number;
+}
+interface BudgetRetryOptions<T> {
+    /** Estimated cost for retrying the original call. */
+    estimatedCost?: number;
+    /** Total attempts, including the first call. Default: 2. */
+    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. */
+    retryIf?: (error: unknown) => boolean;
+}
+/**
+ * Run `call` with budget-aware retries.
+ *
+ * The first attempt runs unchanged. If it fails with a retryable error, the
+ * helper retries as-is with ample budget, asks `onDegrade` for a cheaper plan
+ * when near the limit, and always calls `guard.check(estimatedCost)` before a
+ * retry so an over-budget retry is blocked before it runs.
+ */
+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 };

package/dist/index.js

@@ -1451,6 +1451,9 @@ var BudgetGuard = class {
    */
   advisory() {
     const usedBps = this.limitUsd <= 0 ? 1e4 : Math.max(0, Math.min(1e4, Math.floor(this.spentUsd / this.limitUsd * 1e4 + 1e-9)));
+    const remainingUsd = Math.max(0, this.limitUsd - this.spentUsd);
+    const expectedCost = Math.max(this.lastLlmCost, this.lastToolCost);
+    const estCallsRemaining = expectedCost > 0 ? Math.floor(remainingUsd / expectedCost + 1e-9) : null;
     return {
       nearLimit: usedBps >= this.nearLimitBps,
       usedBps,
@@ -1458,10 +1461,12 @@ var BudgetGuard = class {
       // in-flight reservations. Unlike the remainingUsd getter (which subtracts
       // `reserved`), the advisory is a soft utilization signal about money already
       // spent, while the getter reports what a new call can still claim.
-      remainingUsd: Math.max(0, this.limitUsd - this.spentUsd),
+      remainingUsd,
       limitUsd: this.limitUsd,
       spentUsd: this.spentUsd,
-      scope: "local"
+      scope: "local",
+      expectedCost,
+      estCallsRemaining
     };
   }
 };
@@ -1624,6 +1629,42 @@ function budgetGuardMiddleware(guard) {
     }
   };
 }
+
+// src/retry.ts
+function defaultRetryIf(error) {
+  return !(error instanceof BudgetExceeded);
+}
+async function withBudgetRetry(guard, call, options = {}) {
+  const maxAttempts = options.maxAttempts ?? 2;
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new RangeError(`maxAttempts must be an integer >= 1, got ${maxAttempts}`);
+  }
+  const retryIf = options.retryIf ?? defaultRetryIf;
+  let plan = { call, estimatedCost: options.estimatedCost };
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      return await plan.call();
+    } catch (error) {
+      if (attempt >= maxAttempts || !retryIf(error)) {
+        throw error;
+      }
+      plan = await nextPlan(guard, error, plan, options.onDegrade);
+    }
+  }
+  throw new Error("unreachable");
+}
+async function nextPlan(guard, error, current, onDegrade) {
+  const advisory = guard.advisory();
+  if (advisory.nearLimit && onDegrade !== void 0) {
+    const degraded = await onDegrade(error, advisory);
+    if (degraded !== void 0) {
+      guard.check(degraded.estimatedCost);
+      return degraded;
+    }
+  }
+  guard.check(current.estimatedCost);
+  return current;
+}
 export {
   BudgetExceeded,
   BudgetGuard,
@@ -1634,6 +1675,7 @@ export {
   budgetGuardMiddleware,
   priceTokens,
   pricing_exports as pricing,
-  resolvePrice
+  resolvePrice,
+  withBudgetRetry
 };
 //# sourceMappingURL=index.js.map