@hiper2d/ai-agents 0.2.1 → 0.3.0

package/dist/index.mjs

@@ -1875,6 +1875,152 @@ function createVoiceAgent(provider, apiKey) {
   return VoiceAgentFactory.createAgent(provider, apiKey);
 }
 
+// src/budget/index.ts
+function round6(n) {
+  return parseFloat((Number(n) || 0).toFixed(6));
+}
+function periodKey(timestamp, window) {
+  const d = new Date(timestamp);
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, "0");
+  if (window === "month") {
+    return `${y}-${m}`;
+  }
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+function periodEnd(timestamp, window) {
+  const d = new Date(timestamp);
+  if (window === "month") {
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1);
+  }
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+}
+function normalizeLedger(ledger, period) {
+  if (!ledger || ledger.period !== period) {
+    return { period, totalUSD: 0, buckets: {} };
+  }
+  const buckets = {};
+  for (const [k, v] of Object.entries(ledger.buckets ?? {})) {
+    buckets[k] = round6(v);
+  }
+  return { period, totalUSD: round6(ledger.totalUSD ?? 0), buckets };
+}
+function applySpend(ledger, input) {
+  const timestamp = input.timestamp ?? Date.now();
+  const period = periodKey(timestamp, input.window);
+  const current2 = normalizeLedger(ledger, period);
+  const amount = round6(input.amountUSD);
+  if (!(amount > 0)) {
+    return current2;
+  }
+  const buckets = { ...current2.buckets };
+  if (input.bucket) {
+    buckets[input.bucket] = round6((buckets[input.bucket] ?? 0) + amount);
+  }
+  return { period, totalUSD: round6(current2.totalUSD + amount), buckets };
+}
+function ledgerSpend(ledger, window, timestamp = Date.now(), bucket) {
+  const current2 = normalizeLedger(ledger, periodKey(timestamp, window));
+  return bucket ? current2.buckets[bucket] ?? 0 : current2.totalUSD;
+}
+function evaluateBudget(spentUSD, limit, timestamp = Date.now()) {
+  const spent = round6(spentUSD);
+  const unlimited = !Number.isFinite(limit.limitUSD);
+  const remaining = unlimited ? Number.POSITIVE_INFINITY : Math.max(0, round6(limit.limitUSD - spent));
+  return {
+    allowed: unlimited || spent < limit.limitUSD,
+    window: limit.window,
+    ...limit.bucket ? { bucket: limit.bucket } : {},
+    limitUSD: limit.limitUSD,
+    spentUSD: spent,
+    remainingUSD: remaining,
+    resetsAt: periodEnd(timestamp, limit.window)
+  };
+}
+function firstRefusal(verdicts) {
+  return verdicts.find((v) => !v.allowed);
+}
+var BudgetExceededError = class _BudgetExceededError extends Error {
+  verdict;
+  subject;
+  constructor(verdict, subject, message) {
+    super(message ?? _BudgetExceededError.describe(verdict));
+    this.name = "BudgetExceededError";
+    this.verdict = verdict;
+    this.subject = subject;
+  }
+  static describe(v) {
+    const when = v.window === "day" ? "daily" : "monthly";
+    return `${when} budget of $${v.limitUSD} exhausted ($${v.spentUSD} spent); resets at ${new Date(v.resetsAt).toISOString()}`;
+  }
+};
+function isBudgetExceededError(err) {
+  return err instanceof BudgetExceededError || typeof err === "object" && err !== null && err.name === "BudgetExceededError" && !!err.verdict;
+}
+var InMemorySpendStore = class {
+  ledgers = /* @__PURE__ */ new Map();
+  async read(subject) {
+    return { ...this.ledgers.get(subject) ?? {} };
+  }
+  async update(subject, fn) {
+    const next = fn({ ...this.ledgers.get(subject) ?? {} });
+    this.ledgers.set(subject, next);
+    return { ...next };
+  }
+};
+var BudgetController = class {
+  constructor(store, options) {
+    this.store = store;
+    this.limits = options.limits;
+    this.bucket = options.bucket;
+    this.clock = options.clock ?? (() => Date.now());
+  }
+  store;
+  limits;
+  bucket;
+  clock;
+  verdicts(ledgers, now) {
+    return this.limits.map((limit) => {
+      const spent = ledgerSpend(ledgers[limit.window], limit.window, now, limit.bucket ?? this.bucket);
+      return evaluateBudget(spent, limit, now);
+    });
+  }
+  async check(subject) {
+    return this.verdicts(await this.store.read(subject), this.clock());
+  }
+  async assertWithinBudget(subject) {
+    const refused = firstRefusal(await this.check(subject));
+    if (refused) {
+      throw new BudgetExceededError(refused, subject);
+    }
+  }
+  /**
+   * Record `amountUSD` against every limited window. Re-checks the limits on the
+   * ledgers as they are at write time and throws `BudgetExceededError` (writing
+   * nothing) if any window is already exhausted.
+   */
+  async record(subject, amountUSD) {
+    const now = this.clock();
+    return this.store.update(subject, (current2) => {
+      const refused = firstRefusal(this.verdicts(current2, now));
+      if (refused) {
+        throw new BudgetExceededError(refused, subject);
+      }
+      const next = { ...current2 };
+      for (const limit of this.limits) {
+        next[limit.window] = applySpend(current2[limit.window], {
+          window: limit.window,
+          amountUSD,
+          bucket: limit.bucket ?? this.bucket,
+          timestamp: now
+        });
+      }
+      return next;
+    });
+  }
+};
+
 // src/agents/abstract-agent.ts
 var AbstractAgent = class {
   name;
@@ -4603,6 +4749,8 @@ export {
   AbstractAgent,
   AgentFactory,
   BotResponseError,
+  BudgetController,
+  BudgetExceededError,
   CACHE_TIER_MARKER,
   ClaudeAgent,
   DEEPSEEK_PEAK_SCHEDULE,
@@ -4620,6 +4768,7 @@ export {
   GoogleVoiceAgent,
   Gpt5Agent,
   GrokAgent,
+  InMemorySpendStore,
   KimiAgent,
   LLM_CONSTANTS,
   MESSAGE_ROLE,
@@ -4646,6 +4795,7 @@ export {
   VOICE_PROVIDER_API_KEY,
   VoiceAgentFactory,
   ZodSchemaConverter,
+  applySpend,
   buildGoogleTtsPrompt,
   calculateAnthropicCost,
   calculateCost,
@@ -4664,6 +4814,7 @@ export {
   cleanResponse,
   createCatalog,
   createVoiceAgent,
+  evaluateBudget,
   extractAnthropicTokenUsage,
   extractTokenUsageFromResponse5 as extractAnthropicTokenUsageFromResponse,
   extractDeepSeekTokenUsage,
@@ -4681,6 +4832,7 @@ export {
   extractTokenUsageFromResponse as extractOpenAITokenUsageFromResponse,
   extractTokenUsage,
   extractUsageAndCalculateCost,
+  firstRefusal,
   generateGoogleTtsAudio,
   generateOpenAiTtsAudio,
   generateSchemaInstructions,
@@ -4689,10 +4841,12 @@ export {
   getModelProviderName,
   getModelTags,
   getProviderSignatureFields,
+  isBudgetExceededError,
   isHybridThinkingModel,
   isInPeakWindow,
   isPeakBilling,
   isWeekendAt,
+  ledgerSpend,
   logger,
   mergeThinking,
   modelHasTag,
@@ -4700,6 +4854,8 @@ export {
   needsPromptBasedSchema,
   parseAndValidateLlmJson,
   pcmToWav,
+  periodEnd,
+  periodKey,
   safeValidateResponse,
   setLlmLogger,
   stableHashHex,