@hiper2d/ai-agents 0.2.0 → 0.2.1

package/dist/index.d.mts

@@ -1092,8 +1092,20 @@ declare class AgentFactory {
     private static validateLlmTypeAndGet;
 }
 
+type CacheTtl = '5m' | '1h';
 declare class ClaudeAgent extends AbstractAgent {
     private readonly 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: CacheTtl;
     private get defaultParams();
     private readonly logTemplates;
     private readonly errorMessages;
@@ -1150,6 +1162,7 @@ declare class ClaudeAgent extends AbstractAgent {
 
 declare class Gpt5Agent extends AbstractAgent {
     private readonly client;
+    private readonly promptCacheKey;
     private readonly logTemplates;
     private readonly errorMessages;
     constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);

package/dist/index.d.ts

@@ -1092,8 +1092,20 @@ declare class AgentFactory {
     private static validateLlmTypeAndGet;
 }
 
+type CacheTtl = '5m' | '1h';
 declare class ClaudeAgent extends AbstractAgent {
     private readonly 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: CacheTtl;
     private get defaultParams();
     private readonly logTemplates;
     private readonly errorMessages;
@@ -1150,6 +1162,7 @@ declare class ClaudeAgent extends AbstractAgent {
 
 declare class Gpt5Agent extends AbstractAgent {
     private readonly client;
+    private readonly promptCacheKey;
     private readonly logTemplates;
     private readonly errorMessages;
     constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);

package/dist/index.js

@@ -2176,6 +2176,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 +2193,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 +2209,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 +2218,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 +2297,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 +2359,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 +2384,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 +2489,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;
       }
     }