@hiper2d/ai-agents 0.2.1 → 0.3.1

package/dist/index.js

@@ -35,6 +35,8 @@ __export(index_exports, {
   AbstractAgent: () => AbstractAgent,
   AgentFactory: () => AgentFactory,
   BotResponseError: () => BotResponseError,
+  BudgetController: () => BudgetController,
+  BudgetExceededError: () => BudgetExceededError,
   CACHE_TIER_MARKER: () => CACHE_TIER_MARKER,
   ClaudeAgent: () => ClaudeAgent,
   DEEPSEEK_PEAK_SCHEDULE: () => DEEPSEEK_PEAK_SCHEDULE,
@@ -52,6 +54,7 @@ __export(index_exports, {
   GoogleVoiceAgent: () => GoogleVoiceAgent,
   Gpt5Agent: () => Gpt5Agent,
   GrokAgent: () => GrokAgent,
+  InMemorySpendStore: () => InMemorySpendStore,
   KimiAgent: () => KimiAgent,
   LLM_CONSTANTS: () => LLM_CONSTANTS,
   MESSAGE_ROLE: () => MESSAGE_ROLE,
@@ -78,6 +81,7 @@ __export(index_exports, {
   VOICE_PROVIDER_API_KEY: () => VOICE_PROVIDER_API_KEY,
   VoiceAgentFactory: () => VoiceAgentFactory,
   ZodSchemaConverter: () => ZodSchemaConverter,
+  applySpend: () => applySpend,
   buildGoogleTtsPrompt: () => buildGoogleTtsPrompt,
   calculateAnthropicCost: () => calculateAnthropicCost,
   calculateCost: () => calculateCost,
@@ -96,6 +100,7 @@ __export(index_exports, {
   cleanResponse: () => cleanResponse,
   createCatalog: () => createCatalog,
   createVoiceAgent: () => createVoiceAgent,
+  evaluateBudget: () => evaluateBudget,
   extractAnthropicTokenUsage: () => extractAnthropicTokenUsage,
   extractAnthropicTokenUsageFromResponse: () => extractTokenUsageFromResponse5,
   extractDeepSeekTokenUsage: () => extractDeepSeekTokenUsage,
@@ -113,6 +118,7 @@ __export(index_exports, {
   extractOpenAITokenUsageFromResponse: () => extractTokenUsageFromResponse,
   extractTokenUsage: () => extractTokenUsage,
   extractUsageAndCalculateCost: () => extractUsageAndCalculateCost,
+  firstRefusal: () => firstRefusal,
   generateGoogleTtsAudio: () => generateGoogleTtsAudio,
   generateOpenAiTtsAudio: () => generateOpenAiTtsAudio,
   generateSchemaInstructions: () => generateSchemaInstructions,
@@ -121,10 +127,12 @@ __export(index_exports, {
   getModelProviderName: () => getModelProviderName,
   getModelTags: () => getModelTags,
   getProviderSignatureFields: () => getProviderSignatureFields,
+  isBudgetExceededError: () => isBudgetExceededError,
   isHybridThinkingModel: () => isHybridThinkingModel,
   isInPeakWindow: () => isInPeakWindow,
   isPeakBilling: () => isPeakBilling,
   isWeekendAt: () => isWeekendAt,
+  ledgerSpend: () => ledgerSpend,
   logger: () => logger,
   mergeThinking: () => mergeThinking,
   modelHasTag: () => modelHasTag,
@@ -132,7 +140,10 @@ __export(index_exports, {
   needsPromptBasedSchema: () => needsPromptBasedSchema,
   parseAndValidateLlmJson: () => parseAndValidateLlmJson,
   pcmToWav: () => pcmToWav,
+  periodEnd: () => periodEnd,
+  periodKey: () => periodKey,
   safeValidateResponse: () => safeValidateResponse,
+  setBeforeAskHook: () => setBeforeAskHook,
   setLlmLogger: () => setLlmLogger,
   stableHashHex: () => stableHashHex,
   stripInlineThinking: () => stripInlineThinking,
@@ -2026,7 +2037,157 @@ 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 beforeAskHook;
+function setBeforeAskHook(hook) {
+  beforeAskHook = hook;
+}
 var AbstractAgent = class {
   name;
   gameId;
@@ -2078,6 +2239,7 @@ var AbstractAgent = class {
    * must NOT override these.
    */
   async askWithZodSchema(zodSchema, messages) {
+    if (beforeAskHook) await beforeAskHook(this);
     const startedAt = Date.now();
     try {
       const [result, thinking, usage, signature] = await this.doAskWithZodSchema(zodSchema, messages);
@@ -2088,6 +2250,7 @@ var AbstractAgent = class {
     }
   }
   async askText(messages) {
+    if (beforeAskHook) await beforeAskHook(this);
     const startedAt = Date.now();
     try {
       const [content, thinking, usage, signature] = await this.doAskText(messages);
@@ -4755,6 +4918,8 @@ var AgentFactory = class {
   AbstractAgent,
   AgentFactory,
   BotResponseError,
+  BudgetController,
+  BudgetExceededError,
   CACHE_TIER_MARKER,
   ClaudeAgent,
   DEEPSEEK_PEAK_SCHEDULE,
@@ -4772,6 +4937,7 @@ var AgentFactory = class {
   GoogleVoiceAgent,
   Gpt5Agent,
   GrokAgent,
+  InMemorySpendStore,
   KimiAgent,
   LLM_CONSTANTS,
   MESSAGE_ROLE,
@@ -4798,6 +4964,7 @@ var AgentFactory = class {
   VOICE_PROVIDER_API_KEY,
   VoiceAgentFactory,
   ZodSchemaConverter,
+  applySpend,
   buildGoogleTtsPrompt,
   calculateAnthropicCost,
   calculateCost,
@@ -4816,6 +4983,7 @@ var AgentFactory = class {
   cleanResponse,
   createCatalog,
   createVoiceAgent,
+  evaluateBudget,
   extractAnthropicTokenUsage,
   extractAnthropicTokenUsageFromResponse,
   extractDeepSeekTokenUsage,
@@ -4833,6 +5001,7 @@ var AgentFactory = class {
   extractOpenAITokenUsageFromResponse,
   extractTokenUsage,
   extractUsageAndCalculateCost,
+  firstRefusal,
   generateGoogleTtsAudio,
   generateOpenAiTtsAudio,
   generateSchemaInstructions,
@@ -4841,10 +5010,12 @@ var AgentFactory = class {
   getModelProviderName,
   getModelTags,
   getProviderSignatureFields,
+  isBudgetExceededError,
   isHybridThinkingModel,
   isInPeakWindow,
   isPeakBilling,
   isWeekendAt,
+  ledgerSpend,
   logger,
   mergeThinking,
   modelHasTag,
@@ -4852,7 +5023,10 @@ var AgentFactory = class {
   needsPromptBasedSchema,
   parseAndValidateLlmJson,
   pcmToWav,
+  periodEnd,
+  periodKey,
   safeValidateResponse,
+  setBeforeAskHook,
   setLlmLogger,
   stableHashHex,
   stripInlineThinking,