shadow-claw 1.32.0 → 1.33.0

package/src/subsystems/providers/providers.test.ts

@@ -7,6 +7,7 @@ import {
   getContextLimit,
   normalizeMeshLlmResult,
   parseResponse,
+  supportsPromptCaching,
 } from "./providers.js";
 
 describe("providers.js", () => {
@@ -935,6 +936,334 @@ describe("providers.js", () => {
       expect(result.tools[0].cache_control).toBeUndefined();
       expect(result.system).toBe("System prompt");
     });
+
+    it("should allow prompt caching to be enabled explicitly for any non-legacy model", () => {
+      const tools = [
+        {
+          name: "test_tool",
+          description: "A tool",
+          input_schema: { type: "object" },
+        },
+      ];
+
+      const result = formatRequest(
+        anthropicProvider,
+        [{ role: "user", content: "hello" }],
+        tools,
+        {
+          model: "custom-unlisted-model",
+          maxTokens: 1000,
+          system: "System prompt",
+          promptCaching: true,
+        } as any,
+      );
+
+      expect(result.tools[0].cache_control).toEqual({ type: "ephemeral" });
+      expect(result.system).toEqual([
+        {
+          type: "text",
+          text: "System prompt",
+          cache_control: { type: "ephemeral" },
+        },
+      ]);
+    });
+
+    it("should guard against prompt caching for legacy models even when promptCaching: true is set", () => {
+      const tools = [
+        {
+          name: "test_tool",
+          description: "A tool",
+          input_schema: { type: "object" },
+        },
+      ];
+
+      const result = formatRequest(
+        anthropicProvider,
+        [{ role: "user", content: "hello" }],
+        tools,
+        {
+          model: "claude-2.1",
+          maxTokens: 1000,
+          system: "System prompt",
+          promptCaching: true,
+        } as any,
+      );
+
+      expect(result.tools[0].cache_control).toBeUndefined();
+      expect(result.system).toBe("System prompt");
+    });
+
+    it("should guard against prompt caching for dot-delimited legacy model IDs when promptCaching: true is set", () => {
+      const tools = [
+        {
+          name: "test_tool",
+          description: "A tool",
+          input_schema: { type: "object" },
+        },
+      ];
+
+      const result = formatRequest(
+        anthropicProvider,
+        [{ role: "user", content: "hello" }],
+        tools,
+        {
+          model: "claude.2.1",
+          maxTokens: 1000,
+          system: "System prompt",
+          promptCaching: true,
+        } as any,
+      );
+
+      expect(result.tools[0].cache_control).toBeUndefined();
+      expect(result.system).toBe("System prompt");
+    });
+
+    it("should place cache_control on the last user turn in multi-turn conversations", () => {
+      const tools = [
+        {
+          name: "test_tool",
+          description: "A tool",
+          input_schema: { type: "object" },
+        },
+      ];
+
+      const messages = [
+        { role: "user", content: "First turn" },
+        { role: "assistant", content: "Assistant response" },
+        { role: "user", content: "Second turn" },
+      ];
+
+      const result = formatRequest(anthropicProvider, messages, tools, {
+        model: "claude-3-5-sonnet-20241022",
+        maxTokens: 1000,
+        system: "System prompt",
+      } as any);
+
+      expect(result.messages[0].content).toBe("First turn");
+      expect(result.messages[2].content).toEqual([
+        {
+          type: "text",
+          text: "Second turn",
+          cache_control: { type: "ephemeral" },
+        },
+      ]);
+    });
+
+    it("should never mutate caller input message objects or arrays", () => {
+      const originalUserTurn = { role: "user", content: "First turn" };
+      const originalAssistantTurn = {
+        role: "assistant",
+        content: "Assistant response",
+      };
+      const originalSecondUserTurn = { role: "user", content: "Second turn" };
+      const callerMessages = [
+        originalUserTurn,
+        originalAssistantTurn,
+        originalSecondUserTurn,
+      ];
+
+      const result = formatRequest(anthropicProvider, callerMessages, [], {
+        model: "claude-3-5-sonnet-20241022",
+        maxTokens: 1000,
+        system: "System prompt",
+      } as any);
+
+      // Caller objects must be unchanged
+      expect(originalUserTurn.content).toBe("First turn");
+      expect(originalSecondUserTurn.content).toBe("Second turn");
+      expect((originalSecondUserTurn as any).cache_control).toBeUndefined();
+      expect(callerMessages[0]).toBe(originalUserTurn);
+      expect(callerMessages[2]).toBe(originalSecondUserTurn);
+
+      // Formatted result gets the cache breakpoint
+      expect(result.messages[2].content).toEqual([
+        {
+          type: "text",
+          text: "Second turn",
+          cache_control: { type: "ephemeral" },
+        },
+      ]);
+    });
+
+    it("should dynamically enable prompt caching when ModelRegistry metadata specifies support", () => {
+      modelRegistry.registerModelInfo("arbitrary-proxy-model", {
+        contextWindow: 100000,
+        maxOutput: 4096,
+        supportsPromptCaching: true,
+      });
+
+      const tools = [
+        {
+          name: "test_tool",
+          description: "A tool",
+          input_schema: { type: "object" },
+        },
+      ];
+
+      const result = formatRequest(
+        anthropicProvider,
+        [{ role: "user", content: "hello" }],
+        tools,
+        {
+          model: "arbitrary-proxy-model",
+          maxTokens: 1000,
+          system: "System prompt",
+        } as any,
+      );
+
+      expect(result.tools[0].cache_control).toEqual({ type: "ephemeral" });
+    });
+
+    it("should dynamically disable prompt caching when ModelRegistry metadata specifies false", () => {
+      modelRegistry.registerModelInfo("claude-3-5-sonnet-cached", {
+        contextWindow: 200000,
+        maxOutput: 8192,
+        supportsPromptCaching: false,
+      });
+
+      const tools = [
+        {
+          name: "test_tool",
+          description: "A tool",
+          input_schema: { type: "object" },
+        },
+      ];
+
+      const result = formatRequest(
+        anthropicProvider,
+        [{ role: "user", content: "hello" }],
+        tools,
+        {
+          model: "claude-3-5-sonnet-cached",
+          maxTokens: 1000,
+          system: "System prompt",
+        } as any,
+      );
+
+      expect(result.tools[0].cache_control).toBeUndefined();
+    });
+
+    it("should guard against prompt caching when ModelRegistry explicitly specifies false even if promptCaching: true is set", () => {
+      modelRegistry.registerModelInfo("explicit-no-cache-model", {
+        contextWindow: 128000,
+        maxOutput: 4096,
+        supportsPromptCaching: false,
+      });
+
+      const tools = [
+        {
+          name: "test_tool",
+          description: "A tool",
+          input_schema: { type: "object" },
+        },
+      ];
+
+      const result = formatRequest(
+        anthropicProvider,
+        [{ role: "user", content: "hello" }],
+        tools,
+        {
+          model: "explicit-no-cache-model",
+          maxTokens: 1000,
+          system: "System prompt",
+          promptCaching: true,
+        } as any,
+      );
+
+      expect(result.tools[0].cache_control).toBeUndefined();
+      expect(result.system).toBe("System prompt");
+    });
+
+    it("should preserve pre-existing cache_control on content blocks during mapAnthropicContent", () => {
+      const messages = [
+        {
+          role: "user",
+          content: [
+            {
+              type: "text",
+              text: "Explicitly tagged block",
+              cache_control: { type: "ephemeral" },
+            },
+          ],
+        },
+      ];
+
+      const result = formatRequest(anthropicProvider, messages, [], {
+        model: "claude-3-5-sonnet-20241022",
+        maxTokens: 1000,
+        system: "",
+      } as any);
+
+      expect(result.messages[0].content[0]).toEqual({
+        type: "text",
+        text: "Explicitly tagged block",
+        cache_control: { type: "ephemeral" },
+      });
+    });
+  });
+
+  describe("supportsPromptCaching", () => {
+    it("returns false for empty or non-string inputs", () => {
+      expect(supportsPromptCaching("")).toBe(false);
+      expect(supportsPromptCaching("   ")).toBe(false);
+      expect(supportsPromptCaching(null as any)).toBe(false);
+      expect(supportsPromptCaching(undefined as any)).toBe(false);
+    });
+
+    it("identifies Claude 3.5 models (with dashes and dots)", () => {
+      expect(supportsPromptCaching("claude-3-5-sonnet-20241022")).toBe(true);
+      expect(supportsPromptCaching("claude-3-5-sonnet-latest")).toBe(true);
+      expect(supportsPromptCaching("claude-3.5-sonnet")).toBe(true);
+      expect(supportsPromptCaching("claude-3-5-haiku-20241022")).toBe(true);
+      expect(supportsPromptCaching("claude-3.5-haiku")).toBe(true);
+    });
+
+    it("identifies Claude 3.7 models (with dashes and dots)", () => {
+      expect(supportsPromptCaching("claude-3-7-sonnet-20250219")).toBe(true);
+      expect(supportsPromptCaching("claude-3.7-sonnet")).toBe(true);
+      expect(
+        supportsPromptCaching("anthropic/claude-3.7-sonnet:thinking"),
+      ).toBe(true);
+    });
+
+    it("identifies Claude 3 Haiku and Claude 3 Opus", () => {
+      expect(supportsPromptCaching("claude-3-haiku-20240307")).toBe(true);
+      expect(supportsPromptCaching("claude-3-haiku")).toBe(true);
+      expect(supportsPromptCaching("claude-3-opus-20240229")).toBe(true);
+      expect(supportsPromptCaching("claude-3-opus")).toBe(true);
+    });
+
+    it("identifies Claude 4+ and Claude 5+ standard families", () => {
+      expect(supportsPromptCaching("claude-sonnet-4")).toBe(true);
+      expect(supportsPromptCaching("claude-opus-4")).toBe(true);
+      expect(supportsPromptCaching("claude-haiku-4")).toBe(true);
+      expect(supportsPromptCaching("claude-4-sonnet")).toBe(true);
+      expect(supportsPromptCaching("claude-sonnet-5")).toBe(true);
+      expect(supportsPromptCaching("claude-opus-5")).toBe(true);
+    });
+
+    it("identifies AWS Bedrock inference profile IDs", () => {
+      expect(
+        supportsPromptCaching("anthropic.claude-3-5-sonnet-20241022-v2:0"),
+      ).toBe(true);
+      expect(
+        supportsPromptCaching("us.anthropic.claude-3-7-sonnet-20250219-v1:0"),
+      ).toBe(true);
+      expect(
+        supportsPromptCaching("eu.anthropic.claude-3-5-haiku-20241022-v1:0"),
+      ).toBe(true);
+    });
+
+    it("rejects non-Anthropic models, legacy Claude models, and unspecified families", () => {
+      expect(supportsPromptCaching("amazon.nova-pro-v1:0")).toBe(false);
+      expect(supportsPromptCaching("claude-2.1")).toBe(false);
+      expect(supportsPromptCaching("claude-2.0")).toBe(false);
+      expect(supportsPromptCaching("claude-2")).toBe(false);
+      expect(supportsPromptCaching("anthropic.claude-v2")).toBe(false);
+      expect(supportsPromptCaching("claude-instant-1.2")).toBe(false);
+      expect(supportsPromptCaching("claude-1.3")).toBe(false);
+      expect(supportsPromptCaching("gpt-4o")).toBe(false);
+    });
   });
 
   describe("Anthropic response parsing", () => {

package/src/subsystems/providers/providers.ts

@@ -183,22 +183,92 @@ function mapOpenAiUserContent(blocks: any[], model: string): any[] {
   return content;
 }
 
-function supportsPromptCaching(model: string): boolean {
+function normalizeModelId(model: string): string {
   if (typeof model !== "string" || model.trim().length === 0) {
-    return false;
+    return "";
   }
 
-  const id = model.toLowerCase();
+  return model
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function isLegacyClaudeModel(model: string): boolean {
+  const id = normalizeModelId(model);
+  if (!id) {
+    return false;
+  }
 
   return (
-    id.includes("claude-3-5-sonnet") ||
-    id.includes("claude-3-7-sonnet") ||
-    id.includes("claude-opus-4") ||
-    id.includes("claude-sonnet-4") ||
-    id.includes("claude-haiku-4")
+    id.includes("claude-1") ||
+    id.includes("claude-2") ||
+    id.includes("claude-v1") ||
+    id.includes("claude-v2") ||
+    id.includes("claude-instant")
   );
 }
 
+/**
+ * Check if a model supports Anthropic/Bedrock prompt caching.
+ *
+ * 1. Checks ModelRegistry for dynamic capability metadata (e.g. from OpenRouter
+ *    `supported_parameters` or explicit registration).
+ * 2. Normalizes model identifiers (handling dots, slashes, uppercase).
+ * 3. Rejects legacy models (Claude 1, 2, instant).
+ * 4. Matches modern Claude 3, 3.5, 3.7, 4+, 5+ families.
+ */
+export function supportsPromptCaching(model: string): boolean {
+  if (typeof model !== "string" || model.trim().length === 0) {
+    return false;
+  }
+
+  // 1. Dynamic metadata lookup (avoids hardcoded strings when provider supplies capabilities)
+  const modelInfo = modelRegistry.getModelInfo(model);
+  if (typeof modelInfo?.supportsPromptCaching === "boolean") {
+    return modelInfo.supportsPromptCaching;
+  }
+
+  // 2. Normalize model identifier (lowercased, non-alphanumeric converted to hyphens)
+  const id = normalizeModelId(model);
+
+  // Legacy Claude models that explicitly do NOT support prompt caching
+  if (isLegacyClaudeModel(id)) {
+    return false;
+  }
+
+  // Claude 3.5 & 3.7 families (Sonnet, Haiku)
+  if (
+    id.includes("claude-3-5-sonnet") ||
+    id.includes("claude-3-5-haiku") ||
+    id.includes("claude-3-7-sonnet")
+  ) {
+    return true;
+  }
+
+  // Claude 3 Haiku & Claude 3 Opus
+  if (id.includes("claude-3-haiku") || id.includes("claude-3-opus")) {
+    return true;
+  }
+
+  // Claude 4+ & 5+ families (Sonnet 4+, Opus 4+, Haiku 4+, Sonnet 5, Opus 5, etc.)
+  // Matches "claude-sonnet-4", "claude-opus-4", "claude-haiku-4", "claude-sonnet-5", "claude-4-sonnet", etc.
+  if (
+    /claude-(?:sonnet|opus|haiku)-[4-9]/.test(id) ||
+    /claude-[4-9]-(?:sonnet|opus|haiku)/.test(id)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Maps incoming content blocks to Anthropic Messages format.
+ * Preserves caller-specified `cache_control` blocks if already present on incoming blocks
+ * (e.g. from orchestrators or replayed conversation history).
+ */
 function mapAnthropicContent(blocks: any[], model: string): any[] {
   const content: any[] = [];
   const canSendImages = canSendNativeImage(model);
@@ -210,7 +280,11 @@ function mapAnthropicContent(blocks: any[], model: string): any[] {
         continue;
       }
 
-      content.push({ type: "text", text });
+      content.push({
+        type: "text",
+        text,
+        ...(block.cache_control && { cache_control: block.cache_control }),
+      });
 
       continue;
     }
@@ -269,6 +343,7 @@ function mapAnthropicContent(blocks: any[], model: string): any[] {
             media_type: block.mimeType,
             data: block.data,
           },
+          ...(block.cache_control && { cache_control: block.cache_control }),
         });
       } else if (
         block.mediaType === "document" &&
@@ -283,11 +358,13 @@ function mapAnthropicContent(blocks: any[], model: string): any[] {
             media_type: "application/pdf",
             data: block.data,
           },
+          ...(block.cache_control && { cache_control: block.cache_control }),
         });
       } else {
         content.push({
           type: "text",
           text: formatAttachmentFallbackText(block),
+          ...(block.cache_control && { cache_control: block.cache_control }),
         });
       }
     }
@@ -600,16 +677,22 @@ class AnthropicAdapter extends BaseAdapter {
     },
   ): any {
     const { model, maxTokens, system, reasoning } = options;
+    const modelInfo = modelRegistry.getModelInfo(model);
+    const explicitlyUnsupported =
+      isLegacyClaudeModel(model) || modelInfo?.supportsPromptCaching === false;
     const cacheEnabled =
-      options.promptCaching !== false && supportsPromptCaching(model);
+      !explicitlyUnsupported &&
+      (options.promptCaching === true ||
+        (options.promptCaching !== false && supportsPromptCaching(model)));
 
     // Messages are already in Anthropic format internally.
     // Filter out system messages (system is passed separately).
+    // Always clone message objects so formatting never mutates the caller's array.
     const filteredMessages = messages
       .filter((msg) => msg.role !== "system")
       .map((msg) => {
         if (!Array.isArray(msg.content)) {
-          return msg;
+          return { ...msg };
         }
 
         return {
@@ -635,6 +718,47 @@ class AnthropicAdapter extends BaseAdapter {
         ? [{ type: "text", text: system, cache_control: { type: "ephemeral" } }]
         : system;
 
+    // For multi-turn conversations, place a cache breakpoint on the last user turn (up to 4 total checkpoints).
+    // Mutates only the newly cloned message objects in filteredMessages, leaving caller references untouched.
+    if (cacheEnabled && filteredMessages.length > 1) {
+      for (let i = filteredMessages.length - 1; i >= 0; i--) {
+        const msg = filteredMessages[i];
+        if (msg.role === "user") {
+          if (typeof msg.content === "string") {
+            filteredMessages[i] = {
+              ...msg,
+              content: [
+                {
+                  type: "text",
+                  text: msg.content,
+                  cache_control: { type: "ephemeral" },
+                },
+              ],
+            };
+          } else if (Array.isArray(msg.content) && msg.content.length > 0) {
+            const updated = [...msg.content];
+            const lastIdx = updated.length - 1;
+            const lastBlock = updated[lastIdx];
+            if (
+              lastBlock &&
+              typeof lastBlock === "object" &&
+              !lastBlock.cache_control
+            ) {
+              updated[lastIdx] = {
+                ...lastBlock,
+                cache_control: { type: "ephemeral" },
+              };
+              filteredMessages[i] = {
+                ...msg,
+                content: updated,
+              };
+            }
+          }
+          break;
+        }
+      }
+    }
+
     const request: any = {
       model,
       max_tokens: maxTokens,