floe-guard 0.10.0 → 0.11.0

package/dist/index.cjs

@@ -27,10 +27,16 @@ __export(index_exports, {
   LatencyBudget: () => LatencyBudget,
   TokenBudgetExceeded: () => TokenBudgetExceeded,
   UnpriceableModelError: () => UnpriceableModelError,
+  UnpriceableVoiceError: () => UnpriceableVoiceError,
   budgetGuardMiddleware: () => budgetGuardMiddleware,
+  gates: () => gates_exports,
+  lookupVoiceRate: () => lookupVoiceRate,
   priceTokens: () => priceTokens,
+  priceVoiceLeg: () => priceVoiceLeg,
   pricing: () => pricing_exports,
   resolvePrice: () => resolvePrice,
+  resolveVoiceRate: () => resolveVoiceRate,
+  voiceLegCost: () => voiceLegCost,
   withBudgetRetry: () => withBudgetRetry
 });
 module.exports = __toCommonJS(index_exports);
@@ -81,6 +87,19 @@ var UnpriceableModelError = class extends FloeGuardError {
     this.model = model;
   }
 };
+var UnpriceableVoiceError = class extends FloeGuardError {
+  vendor;
+  mode;
+  constructor(vendor, mode) {
+    const shown = vendor === null ? "None" : `'${vendor}'`;
+    super(
+      `Cannot price ${mode} vendor ${shown}: not in the bundled voice cost map (or its entry has the wrong unit for a ${mode} leg) and no per-unit override was given. The guard cannot enforce a budget on spend it cannot measure. Pass a per-unit rate to enable enforcement.`
+    );
+    this.name = "UnpriceableVoiceError";
+    this.vendor = vendor;
+    this.mode = mode;
+  }
+};
 function roundHalfUp(ms) {
   return Math.floor(ms + 0.5);
 }
@@ -1239,6 +1258,12 @@ function isReservation(h) {
 var BudgetGuard = class {
   limitUsd;
   spentUsd = 0;
+  /**
+   * Wall-clock start (ms since epoch) of this guard's spend window, for the $/min
+   * burn rate (advisory().burnRateUsdPerMin). One guard per call/turn ⇒ a per-call
+   * rate. Set at construction; tests set it directly to control elapsed time.
+   */
+  createdAtMs = Date.now();
   priceOverrides;
   failClosed;
   nearLimitBps;
@@ -1779,6 +1804,8 @@ var BudgetGuard = class {
     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;
+    const elapsedMin = (Date.now() - this.createdAtMs) / 6e4;
+    const burnRateUsdPerMin = elapsedMin > 0 ? this.spentUsd / elapsedMin : null;
     let tokenUsedBps = null;
     let remainingTokens = null;
     let nearToken = false;
@@ -1832,7 +1859,8 @@ var BudgetGuard = class {
       tokenUsedBps,
       remainingTokens,
       stepRemainingUsd,
-      stepRemainingTokens
+      stepRemainingTokens,
+      burnRateUsdPerMin
     };
   }
 };
@@ -2031,6 +2059,107 @@ async function nextPlan(guard, error, current, onDegrade) {
   guard.check(current.estimatedCost);
   return current;
 }
+
+// src/voice-pricing.ts
+var VOICE_MAP = cost_map_default["__voice__"] ?? {};
+var unitForMode = {
+  stt: "usd_per_second",
+  tts: "usd_per_1k_chars",
+  telephony: "usd_per_minute"
+};
+function finiteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function lookupVoiceRate(model, mode) {
+  if (model === null || model === void 0) return null;
+  const entry = Object.prototype.hasOwnProperty.call(VOICE_MAP, model) ? VOICE_MAP[model] : void 0;
+  if (!entry) return null;
+  if (entry.mode !== mode) return null;
+  if (entry.unit !== unitForMode[mode]) return null;
+  const rate = entry.rate;
+  if (!finiteNonNegative(rate)) return null;
+  return rate;
+}
+function resolveVoiceRate(model, mode, override) {
+  if (override !== void 0 && override !== null) {
+    if (!finiteNonNegative(override)) {
+      throw new RangeError(
+        `voice ${mode} override must be a finite, non-negative number, got ${override}`
+      );
+    }
+    return { mode, unit: unitForMode[mode], rate: override, source: "override" };
+  }
+  const rate = lookupVoiceRate(model, mode);
+  if (rate === null) throw new UnpriceableVoiceError(model ?? null, mode);
+  return { mode, unit: unitForMode[mode], rate, source: "cost_map" };
+}
+function voiceLegCost(mode, quantity, rate) {
+  if (!Number.isFinite(quantity)) {
+    throw new RangeError(`voice ${mode} quantity must be a finite number, got ${quantity}`);
+  }
+  const q = Math.max(0, quantity);
+  if (mode === "stt") return q * rate;
+  if (mode === "tts") return q / 1e3 * rate;
+  if (mode === "telephony") return q * rate;
+  throw new RangeError(`unknown voice mode ${mode}`);
+}
+function priceVoiceLeg(mode, quantity, options = {}) {
+  const model = options.model ?? null;
+  const override = options.override ?? null;
+  if (model === null && override === null) return null;
+  const resolved = resolveVoiceRate(model, mode, override);
+  return voiceLegCost(mode, quantity, resolved.rate);
+}
+
+// src/gates.ts
+var gates_exports = {};
+__export(gates_exports, {
+  budgetExhausted: () => budgetExhausted,
+  preCall: () => preCall,
+  retell: () => retell,
+  vapi: () => vapi
+});
+function budgetExhausted(guard, options = {}) {
+  const estimatedCallUsd = options.estimatedCallUsd === void 0 ? 0 : options.estimatedCallUsd;
+  if (!Number.isFinite(estimatedCallUsd) || estimatedCallUsd < 0) {
+    throw new RangeError(
+      `estimatedCallUsd must be a finite, non-negative number, got ${estimatedCallUsd}`
+    );
+  }
+  const remainingUsd = guard.remainingUsd;
+  return remainingUsd <= 0 || remainingUsd < estimatedCallUsd;
+}
+function preCall(guard, options = {}) {
+  return !budgetExhausted(guard, options);
+}
+function retell(guard, options = {}) {
+  if (budgetExhausted(guard, { estimatedCallUsd: options.estimatedCallUsd })) {
+    return { call_inbound: { reject: true } };
+  }
+  const safeAdmit = { ...options.admit ?? {} };
+  delete safeAdmit.reject;
+  return { call_inbound: safeAdmit };
+}
+function vapi(guard, options = {}) {
+  const {
+    assistant,
+    assistantId,
+    errorMessage = "Sorry, this agent is out of budget right now.",
+    estimatedCallUsd
+  } = options;
+  if (budgetExhausted(guard, { estimatedCallUsd })) {
+    return { error: errorMessage };
+  }
+  if (assistantId !== void 0 && assistantId !== null) {
+    return { assistantId };
+  }
+  if (assistant !== void 0 && assistant !== null) {
+    return { assistant };
+  }
+  throw new RangeError(
+    "vapi() admitted the call but has nothing to return: pass assistant or assistantId for the admit path."
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BudgetExceeded,
@@ -2040,10 +2169,16 @@ async function nextPlan(guard, error, current, onDegrade) {
   LatencyBudget,
   TokenBudgetExceeded,
   UnpriceableModelError,
+  UnpriceableVoiceError,
   budgetGuardMiddleware,
+  gates,
+  lookupVoiceRate,
   priceTokens,
+  priceVoiceLeg,
   pricing,
   resolvePrice,
+  resolveVoiceRate,
+  voiceLegCost,
   withBudgetRetry
 });
 //# sourceMappingURL=index.cjs.map