@hiper2d/ai-agents 0.2.0 → 0.3.0

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,6 +140,8 @@ __export(index_exports, {
   needsPromptBasedSchema: () => needsPromptBasedSchema,
   parseAndValidateLlmJson: () => parseAndValidateLlmJson,
   pcmToWav: () => pcmToWav,
+  periodEnd: () => periodEnd,
+  periodKey: () => periodKey,
   safeValidateResponse: () => safeValidateResponse,
   setLlmLogger: () => setLlmLogger,
   stableHashHex: () => stableHashHex,
@@ -2026,6 +2036,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;
@@ -2176,6 +2332,11 @@ var import_openai3 = __toESM(require("openai"));
 var import_zod2 = require("openai/helpers/zod");
 var Gpt5Agent = class extends AbstractAgent {
   client;
+  // Routing hint for OpenAI's prefix cache (same scheme as the Mistral/Grok agents): one
+  // key per agent+instruction, so an agent's own calls group together instead of every
+  // agent that shares a static prefix hashing to the same route. Keys influence routing
+  // only; they do not guarantee a hit.
+  promptCacheKey;
   // Log message templates
   logTemplates = {
     error: (name, error) => `Error in ${name} agent: ${error}`
@@ -2188,6 +2349,8 @@ var Gpt5Agent = class extends AbstractAgent {
   };
   constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
     super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    this.promptCacheKey = stableHashHex(`${name}
+${instruction}`);
     this.client = new import_openai3.default({
       apiKey
     });
@@ -2202,10 +2365,7 @@ var Gpt5Agent = class extends AbstractAgent {
     try {
       this.logAsking(messages);
       this.logMessages(messages);
-      const input = [
-        `System: ${this.instruction}`,
-        ...this.prepareMessages(messages).map((msg) => `${msg.role === "user" ? "User" : "Assistant"}: ${msg.content}`)
-      ].join("\n\n");
+      const input = this.prepareMessages(messages).map((msg) => `${msg.role === "user" ? "User" : "Assistant"}: ${msg.content}`).join("\n\n");
       const schemaToSend = zodSchema;
       let response;
       try {
@@ -2214,6 +2374,7 @@ var Gpt5Agent = class extends AbstractAgent {
           instructions: this.instruction,
           input,
           max_output_tokens: this.maxOutputTokens,
+          prompt_cache_key: this.promptCacheKey,
           text: {
             format: (0, import_zod2.zodTextFormat)(schemaToSend, "response_schema")
           }
@@ -2292,15 +2453,13 @@ var Gpt5Agent = class extends AbstractAgent {
     try {
       this.logAsking(messages);
       this.logMessages(messages);
-      const input = [
-        `System: ${this.instruction}`,
-        ...this.prepareMessages(messages).map((msg) => `${msg.role === "user" ? "User" : "Assistant"}: ${msg.content}`)
-      ].join("\n\n");
+      const input = this.prepareMessages(messages).map((msg) => `${msg.role === "user" ? "User" : "Assistant"}: ${msg.content}`).join("\n\n");
       const response = await this.client.responses.create({
         model: this.model,
         instructions: this.instruction,
         input,
-        max_output_tokens: this.maxOutputTokens
+        max_output_tokens: this.maxOutputTokens,
+        prompt_cache_key: this.promptCacheKey
       });
       const content = response.output_text;
       if (!content) {
@@ -2356,13 +2515,24 @@ var Gpt5Agent = class extends AbstractAgent {
 var import_sdk = require("@anthropic-ai/sdk");
 var ClaudeAgent = class extends AbstractAgent {
   client;
+  /**
+   * TTL for every breakpoint this agent places (system tiers and the message anchor).
+   * Anthropic bills a 5m write at 1.25x input, a 1h write at 2x, reads at 0.1x, and a read
+   * refreshes the timer on either TTL. Default '1h' because the main consumer runs at human
+   * pace: consecutive calls for one agent measured 12-78 minutes apart, so 5m entries
+   * expired before they were ever read (0-16% hit rate over 30 days, hits only on gaps
+   * under five minutes). Set '5m' for continuous traffic where every call lands inside the
+   * window; there the cheaper write wins. One knob for all breakpoints on purpose: Anthropic
+   * requires 1h entries to precede 5m ones, and a single TTL keeps that trivially true.
+   */
+  cacheTtl = "1h";
   // System-prompt breakpoints, one per cache tier (see CACHE_TIER_MARKER):
-  //   block 1 — shared static rules, byte-identical across all bots and games with the
-  //             same rule set, so one org-level entry serves everyone and ANY bot's call
-  //             refreshes its TTL;
-  //   block 2 — per-bot identity + game state + summaries, byte-stable from the start of
-  //             a game day through the end of its night (deaths/role knowledge/summaries
-  //             only change in startNewDay), so every call within a day reads it.
+  //   block 1 - shared static rules, byte-identical across all bots and games with the
+  //             same rule set. Caches are scoped per model, so one entry serves every bot
+  //             ON THAT MODEL (not the whole lobby), and any of their calls refreshes it;
+  //   block 2 - per-bot identity + game state + summaries, byte-stable between the game's
+  //             state writes (a lynch, the night resolution, the summary rewrite, the new
+  //             day), so every call inside one of those windows reads it.
   // GM prompts have no marker → single block, same behavior as before. Haiku 4.5 needs a
   // 4096-token cacheable prefix, so tiers below that silently no-op on Haiku — expected.
   // A getter, not a field: `maxOutputTokens` can be raised after construction, and a field
@@ -2370,7 +2540,7 @@ var ClaudeAgent = class extends AbstractAgent {
   get defaultParams() {
     return {
       max_tokens: this.maxOutputTokens,
-      system: this.instructionParts.map((part) => ({ type: "text", text: part, cache_control: { type: "ephemeral" } })),
+      system: this.instructionParts.map((part) => ({ type: "text", text: part, cache_control: { type: "ephemeral", ttl: this.cacheTtl } })),
       model: this.model
     };
   }
@@ -2475,14 +2645,14 @@ var ClaudeAgent = class extends AbstractAgent {
     const anchor = messages[messages.length - 2];
     if (typeof anchor.content === "string") {
       if (anchor.content.length > 0) {
-        anchor.content = [{ type: "text", text: anchor.content, cache_control: { type: "ephemeral" } }];
+        anchor.content = [{ type: "text", text: anchor.content, cache_control: { type: "ephemeral", ttl: this.cacheTtl } }];
       }
       return;
     }
     for (let i = anchor.content.length - 1; i >= 0; i--) {
       const block = anchor.content[i];
       if (block.type === "text" && block.text.length > 0) {
-        block.cache_control = { type: "ephemeral" };
+        block.cache_control = { type: "ephemeral", ttl: this.cacheTtl };
         return;
       }
     }
@@ -4741,6 +4911,8 @@ var AgentFactory = class {
   AbstractAgent,
   AgentFactory,
   BotResponseError,
+  BudgetController,
+  BudgetExceededError,
   CACHE_TIER_MARKER,
   ClaudeAgent,
   DEEPSEEK_PEAK_SCHEDULE,
@@ -4758,6 +4930,7 @@ var AgentFactory = class {
   GoogleVoiceAgent,
   Gpt5Agent,
   GrokAgent,
+  InMemorySpendStore,
   KimiAgent,
   LLM_CONSTANTS,
   MESSAGE_ROLE,
@@ -4784,6 +4957,7 @@ var AgentFactory = class {
   VOICE_PROVIDER_API_KEY,
   VoiceAgentFactory,
   ZodSchemaConverter,
+  applySpend,
   buildGoogleTtsPrompt,
   calculateAnthropicCost,
   calculateCost,
@@ -4802,6 +4976,7 @@ var AgentFactory = class {
   cleanResponse,
   createCatalog,
   createVoiceAgent,
+  evaluateBudget,
   extractAnthropicTokenUsage,
   extractAnthropicTokenUsageFromResponse,
   extractDeepSeekTokenUsage,
@@ -4819,6 +4994,7 @@ var AgentFactory = class {
   extractOpenAITokenUsageFromResponse,
   extractTokenUsage,
   extractUsageAndCalculateCost,
+  firstRefusal,
   generateGoogleTtsAudio,
   generateOpenAiTtsAudio,
   generateSchemaInstructions,
@@ -4827,10 +5003,12 @@ var AgentFactory = class {
   getModelProviderName,
   getModelTags,
   getProviderSignatureFields,
+  isBudgetExceededError,
   isHybridThinkingModel,
   isInPeakWindow,
   isPeakBilling,
   isWeekendAt,
+  ledgerSpend,
   logger,
   mergeThinking,
   modelHasTag,
@@ -4838,6 +5016,8 @@ var AgentFactory = class {
   needsPromptBasedSchema,
   parseAndValidateLlmJson,
   pcmToWav,
+  periodEnd,
+  periodKey,
   safeValidateResponse,
   setLlmLogger,
   stableHashHex,