@tyvm/knowhow 0.0.158 → 0.0.160

package/tests/processors/Base64ImageDetector.test.ts

@@ -1,979 +0,0 @@
-import {
-  Base64ImageProcessor,
-  globalBase64ImageDetector,
-} from "../../src/processors/Base64ImageDetector";
-import { Message, MessageContent } from "../../src/clients/types";
-import { ToolsService } from "../../src/services/Tools";
-import * as fs from "fs";
-
-describe("Base64ImageDetector", () => {
-  let detector: Base64ImageProcessor;
-
-  beforeEach(() => {
-    detector = new Base64ImageProcessor();
-  });
-
-  describe("Constructor", () => {
-    it("should create instance with default parameters", () => {
-      const instance = new Base64ImageProcessor();
-      expect(instance).toBeInstanceOf(Base64ImageProcessor);
-    });
-
-    it("should create instance with custom image detail", () => {
-      const instance = new Base64ImageProcessor();
-      instance.setImageDetail("high");
-      expect(instance).toBeInstanceOf(Base64ImageProcessor);
-    });
-
-    it("should create instance with custom supported formats", () => {
-      const instance = new Base64ImageProcessor();
-      instance.setImageDetail("low");
-      instance.setSupportedFormats(["png", "jpeg"]);
-      expect(instance).toBeInstanceOf(Base64ImageProcessor);
-    });
-  });
-
-  describe("Configuration methods", () => {
-    it("should allow setting image detail", () => {
-      detector.setImageDetail("high");
-      expect(() => detector.setImageDetail("high")).not.toThrow();
-    });
-
-    it("should allow setting supported formats", () => {
-      detector.setSupportedFormats(["png", "jpeg"]);
-      expect(() => detector.setSupportedFormats(["png", "jpeg"])).not.toThrow();
-    });
-  });
-
-  describe("createProcessor", () => {
-    it("should return a function", () => {
-      const processor = detector.createProcessor();
-      expect(typeof processor).toBe("function");
-    });
-
-    it("should process messages without throwing", () => {
-      const processor = detector.createProcessor();
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [];
-      expect(() => processor(originalMessages, modifiedMessages)).not.toThrow();
-    });
-  });
-  describe("String content processing", () => {
-    const validPngBase64 =
-      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
-    const validJpegBase64 =
-      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD//gA7Q1JFQVR";
-    const plainBase64 =
-      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
-    const regularText = "This is just regular text";
-
-    it("should convert data URL base64 string to image content", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: validPngBase64,
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      expect(Array.isArray(modifiedMessages[0].content)).toBe(true);
-      const content = modifiedMessages[0].content as any[];
-      expect(content[0]).toEqual({
-        type: "image_url",
-        image_url: {
-          url: validPngBase64,
-          detail: "auto",
-        },
-      });
-    });
-    it("should convert plain base64 PNG to image content", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content:
-            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      // The plain base64 detection might not work in test environment due to atob limitations
-      // If it's converted to array, check the conversion; if not, that's also acceptable behavior
-      if (Array.isArray(modifiedMessages[0].content)) {
-        const content = modifiedMessages[0].content as any[];
-        expect(content[0].type).toBe("image_url");
-        expect(content[0].image_url.url).toContain("data:image/png;base64,");
-      } else {
-        // Plain base64 detection may not work in all environments
-        expect(typeof modifiedMessages[0].content).toBe("string");
-      }
-    });
-
-    it("should not process regular text as image", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: regularText,
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      expect(modifiedMessages[0].content).toBe(regularText);
-    });
-    it("should only process user messages for content", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "assistant",
-          content: validPngBase64,
-        },
-        {
-          role: "system",
-          content: validPngBase64,
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      expect(modifiedMessages[0].content).toBe(validPngBase64);
-      expect(modifiedMessages[1].content).toBe(validPngBase64);
-    });
-
-    it("should process tool messages with JSON string containing image_url", () => {
-      const imageDataUrl =
-        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
-      
-      const toolResponseJson = JSON.stringify({
-        type: "image_url",
-        image_url: {
-          url: imageDataUrl,
-          detail: "auto",
-        },
-      });
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: toolResponseJson,
-          tool_call_id: "call_123",
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      // Tool message content should be converted from JSON string to array
-      expect(Array.isArray(modifiedMessages[0].content)).toBe(true);
-      const content = modifiedMessages[0].content as any[];
-      expect(content).toHaveLength(1);
-      expect(content[0]).toEqual({
-        type: "image_url",
-        image_url: {
-          url: imageDataUrl,
-          detail: "auto",
-        },
-      });
-    });
-
-    it("should process tool messages with JSON string containing an ARRAY of image_url parts", () => {
-      // Computer-use screenshot tools and loadWebpage(mode:"screenshot") return
-      // an array of parts, not a single object. This shape was previously missed
-      // by the single-object check, leaving the model to see a raw base64 string.
-      const imageDataUrl =
-        "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k=";
-
-      const toolResponseJson = JSON.stringify([
-        {
-          type: "image_url",
-          image_url: { url: imageDataUrl },
-        },
-      ]);
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: toolResponseJson,
-          tool_call_id: "call_arr",
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      // Tool message content should become a real multimodal array so the model
-      // actually receives the image instead of a base64 JSON string.
-      expect(Array.isArray(modifiedMessages[0].content)).toBe(true);
-      const content = modifiedMessages[0].content as any[];
-      expect(content).toHaveLength(1);
-      expect(content[0].type).toBe("image_url");
-      expect(content[0].image_url.url).toBe(imageDataUrl);
-    });
-
-    it("should process an image result that is not the newest parallel tool result", () => {
-      const imageDataUrl =
-        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: JSON.stringify({
-            type: "image_url",
-            image_url: { url: imageDataUrl, detail: "high" },
-          }),
-          tool_call_id: "call_image",
-        },
-        {
-          role: "tool",
-          content: "A later readFile result",
-          tool_call_id: "call_file",
-        },
-        {
-          role: "user",
-          content: "A pending workflow update",
-        },
-      ];
-
-      detector.createProcessor()([], modifiedMessages);
-
-      expect(Array.isArray(modifiedMessages[0].content)).toBe(true);
-      expect((modifiedMessages[0].content as any[])[0]).toEqual({
-        type: "image_url",
-        image_url: { url: imageDataUrl, detail: "high" },
-      });
-    });
-
-    it("should not promote a compressed image URL placeholder to image content", () => {
-      const toolResponseJson = JSON.stringify({
-        type: "image_url",
-        image_url: {
-          url: "[COMPRESSED_JSON_PROPERTY - 24614 tokens]\nKey: compressed_image_url",
-          detail: "high",
-        },
-      });
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: toolResponseJson,
-          tool_call_id: "call_compressed_image",
-        },
-      ];
-
-      detector.createProcessor()([], modifiedMessages);
-
-      expect(modifiedMessages[0].content).toBe(toolResponseJson);
-    });
-
-    it("should process tool messages with plain base64 string", () => {
-      const validPngBase64 =
-        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: validPngBase64,
-          tool_call_id: "call_456",
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      // Should convert to array if it's detected as an image
-      if (Array.isArray(modifiedMessages[0].content)) {
-        const content = modifiedMessages[0].content as any[];
-        expect(content[0].type).toBe("image_url");
-      }
-    });
-
-    it("should not process tool messages with regular text", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: "Tool completed successfully",
-          tool_call_id: "call_789",
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      expect(modifiedMessages[0].content).toBe("Tool completed successfully");
-    });
-
-    it("should use custom image detail setting", () => {
-      detector.setImageDetail("high");
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: validPngBase64,
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as any[];
-      expect(content[0].image_url.detail).toBe("high");
-    });
-  });
-  describe("Array content processing", () => {
-    const validPngBase64 =
-      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
-
-    it("should process text items in content array", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: [
-            { type: "text", text: "Here is an image:" },
-            { type: "text", text: validPngBase64 },
-            { type: "text", text: "And some more text" },
-          ],
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as any[];
-      expect(content).toHaveLength(3);
-      expect(content[0].type).toBe("text");
-      expect(content[1].type).toBe("image_url");
-      expect(content[2].type).toBe("text");
-    });
-    it("should preserve existing image_url items in array", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: [
-            { type: "text", text: "Some text" },
-            {
-              type: "image_url",
-              image_url: { url: "http://example.com/image.png" },
-            },
-          ],
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as any[];
-      expect(content).toHaveLength(2);
-      expect(content[0].type).toBe("text");
-      expect(content[1].type).toBe("image_url");
-      expect(content[1].image_url.url).toBe("http://example.com/image.png");
-    });
-
-    it("should handle empty content array", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: [],
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      expect(() => processor(originalMessages, modifiedMessages)).not.toThrow();
-      expect(Array.isArray(modifiedMessages[0].content)).toBe(true);
-    });
-  });
-  describe("Tool call argument processing", () => {
-    const validPngBase64 =
-      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
-
-    it("should process base64 images in tool call arguments", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "assistant",
-          content: "Using a tool",
-          tool_calls: [
-            {
-              id: "call_123",
-              type: "function",
-              function: {
-                name: "analyze_image",
-                arguments: JSON.stringify({
-                  image: validPngBase64,
-                  description: "Test image",
-                }),
-              },
-            },
-          ],
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      const toolCall = modifiedMessages[0].tool_calls![0];
-      const args = JSON.parse(toolCall.function.arguments);
-      expect(args.image).toContain("[CONVERTED TO IMAGE:");
-      expect(args.description).toBe("Test image");
-    });
-    it("should handle nested objects in tool call arguments", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "assistant",
-          content: "Using a tool",
-          tool_calls: [
-            {
-              id: "call_123",
-              type: "function",
-              function: {
-                name: "complex_tool",
-                arguments: JSON.stringify({
-                  data: {
-                    images: [validPngBase64, "regular text"],
-                    metadata: {
-                      thumbnail: validPngBase64,
-                    },
-                  },
-                }),
-              },
-            },
-          ],
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      const toolCall = modifiedMessages[0].tool_calls![0];
-      const args = JSON.parse(toolCall.function.arguments);
-      expect(args.data.images[0]).toContain("[CONVERTED TO IMAGE:");
-      expect(args.data.images[1]).toBe("regular text");
-      expect(args.data.metadata.thumbnail).toContain("[CONVERTED TO IMAGE:");
-    });
-    it("should handle invalid JSON in tool call arguments", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "assistant",
-          content: "Using a tool",
-          tool_calls: [
-            {
-              id: "call_123",
-              type: "function",
-              function: {
-                name: "tool_with_plain_text",
-                arguments: validPngBase64,
-              },
-            },
-          ],
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      const toolCall = modifiedMessages[0].tool_calls![0];
-      expect(toolCall.function.arguments).toContain("[CONVERTED TO IMAGE:");
-    });
-
-    it("should handle messages without tool calls", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "assistant",
-          content: "Just a regular message",
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      expect(() => processor(originalMessages, modifiedMessages)).not.toThrow();
-    });
-  });
-  describe("Edge cases and error handling", () => {
-    it("should handle empty messages array", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [];
-
-      const processor = detector.createProcessor();
-      expect(() => processor(originalMessages, modifiedMessages)).not.toThrow();
-    });
-
-    it("should handle null and undefined content", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: null as any,
-        },
-        {
-          role: "user",
-          content: undefined as any,
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      expect(() => processor(originalMessages, modifiedMessages)).not.toThrow();
-    });
-
-    it("should handle unsupported image formats", () => {
-      detector.setSupportedFormats(["png"]);
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content:
-            "data:image/bmp;base64,Qk1GAAAAAAAAADYAAAAoAAAAAQAAAAEAAAABACAAAAAAAAAAAAATCwAAEwsAAAAAAAAAAAAA/////wA=",
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      expect(typeof modifiedMessages[0].content).toBe("string");
-    });
-    it("should handle short base64 strings", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: "SGVsbG8=", // "Hello" in base64, but too short to be an image
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      expect(modifiedMessages[0].content).toBe("SGVsbG8=");
-    });
-
-    it("should handle malformed data URLs", () => {
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "user",
-          content: "data:image/png;base64", // Missing comma and data
-        },
-      ];
-
-      const processor = detector.createProcessor();
-      processor(originalMessages, modifiedMessages);
-
-      expect(modifiedMessages[0].content).toBe("data:image/png;base64");
-    });
-  });
-
-  describe("Global instance", () => {
-    it("should provide global instance", () => {
-      expect(globalBase64ImageDetector).toBeInstanceOf(Base64ImageProcessor);
-    });
-  });
-
-  describe("loadImageAsBase64 tool", () => {
-    let toolsService: ToolsService;
-    let testImagePath: string;
-
-    beforeEach(() => {
-      toolsService = new ToolsService();
-      detector.registerTool(toolsService);
-
-      // Create a minimal test PNG image (1x1 red pixel)
-      testImagePath = "/tmp/test-image.png";
-      const pngBuffer = Buffer.from(
-        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==",
-        "base64"
-      );
-      fs.writeFileSync(testImagePath, pngBuffer);
-    });
-
-    afterEach(() => {
-      // Clean up test file
-      if (fs.existsSync(testImagePath)) {
-        fs.unlinkSync(testImagePath);
-      }
-    });
-
-    it("should register loadImageAsBase64 tool", () => {
-      const tools = toolsService.getTools();
-      const loadImageTool = tools.find(
-        (t) => t.function.name === "loadImageAsBase64"
-      );
-
-      expect(loadImageTool).toBeDefined();
-      expect(loadImageTool?.function.name).toBe("loadImageAsBase64");
-      expect(loadImageTool?.function.description).toContain(
-        "Load an image file"
-      );
-    });
-
-    it("should have function implementation", () => {
-      const func = toolsService.getFunction("loadImageAsBase64");
-      expect(func).toBeDefined();
-      expect(typeof func).toBe("function");
-    });
-
-    it("should load image and return base64 data URL", async () => {
-      const func = toolsService.getFunction("loadImageAsBase64");
-      const result = await func(testImagePath);
-
-      expect(typeof result).toBe("string");
-      const parsed = JSON.parse(result);
-      expect(parsed.type).toBe("image_url");
-      expect(parsed.image_url.url).toContain("data:image/png;base64,");
-      expect(parsed.image_url.detail).toBe("auto");
-    });
-
-    it("should accept custom detail parameter", async () => {
-      const func = toolsService.getFunction("loadImageAsBase64");
-      const result = await func(testImagePath, "high");
-
-      const parsed = JSON.parse(result);
-      expect(parsed.image_url.detail).toBe("high");
-    });
-
-    it("should throw error for non-existent file", async () => {
-      const func = toolsService.getFunction("loadImageAsBase64");
-
-      await expect(func("/path/to/nonexistent.png")).rejects.toThrow(
-        "File not found"
-      );
-    });
-
-    it("should throw error for unsupported format", async () => {
-      const txtPath = "/tmp/test-file.txt";
-      fs.writeFileSync(txtPath, "test content");
-
-      const func = toolsService.getFunction("loadImageAsBase64");
-
-      try {
-        await expect(func(txtPath)).rejects.toThrow("Unsupported image format");
-      } finally {
-        fs.unlinkSync(txtPath);
-      }
-    });
-
-    it("should throw error for directory path", async () => {
-      const dirPath = "/tmp/test-dir";
-      if (!fs.existsSync(dirPath)) {
-        fs.mkdirSync(dirPath);
-      }
-
-      const func = toolsService.getFunction("loadImageAsBase64");
-
-      try {
-        await expect(func(dirPath)).rejects.toThrow("Path is not a file");
-      } finally {
-        fs.rmdirSync(dirPath);
-      }
-    });
-  });
-});
-
-describe("Base64ImageDetector - image path hint detection", () => {
-  let detector: Base64ImageProcessor;
-  let processor: ReturnType<Base64ImageProcessor["createProcessor"]>;
-
-  beforeEach(() => {
-    detector = new Base64ImageProcessor();
-    processor = detector.createProcessor();
-  });
-
-  /**
-   * Simulates the actual output from the Playwright MCP browser_take_screenshot tool.
-   * When an agent calls browser_take_screenshot, the tool message content looks like:
-   *
-   *   ### Result
-   *   - [Screenshot of viewport](./hackernews-screenshot.png)
-   *   ### Ran Playwright code
-   *   ...
-   *
-   * The Base64ImageDetector should detect the .png path in this text and add a hint
-   * telling the model it can call loadImageAsBase64 to actually view the image.
-   */
-  describe("browser screenshot tool response", () => {
-    it("should detect image path from a browser screenshot tool message and add hint", () => {
-      // This is the exact format returned by the browser MCP take_screenshot tool
-      const screenshotToolResponse =
-        "### Result\n- [Screenshot of viewport](./hackernews-screenshot.png)\n### Ran Playwright code\n```js\nawait page.screenshot({ path: './hackernews-screenshot.png', scale: 'css', type: 'png' });\n```";
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: screenshotToolResponse,
-          tool_call_id: "call_abc123",
-        },
-      ];
-
-      processor(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as string;
-      expect(typeof content).toBe("string");
-      // Should still contain the original text
-      expect(content).toContain("Screenshot of viewport");
-      expect(content).toContain("./hackernews-screenshot.png");
-      // Should contain the hint
-      expect(content).toContain("[TIP:");
-      expect(content).toContain("loadImageAsBase64");
-      expect(content).toContain("./hackernews-screenshot.png");
-    });
-
-    it("should include the exact file path in the hint", () => {
-      const screenshotPath = "./hackernews-screenshot.png";
-      const toolResponse = `### Result\n- [Screenshot of viewport](${screenshotPath})\n`;
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: toolResponse,
-          tool_call_id: "call_xyz789",
-        },
-      ];
-
-      processor(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as string;
-      // The hint should reference the exact path
-      expect(content).toContain(`loadImageAsBase64("${screenshotPath}")`);
-    });
-
-    it("should not add hint when message contains no image paths", () => {
-      const toolResponse = "The page has been loaded successfully.";
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: toolResponse,
-          tool_call_id: "call_noimages",
-        },
-      ];
-
-      processor(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as string;
-      expect(content).toBe(toolResponse);
-      expect(content).not.toContain("[TIP:");
-    });
-
-    it("should detect absolute paths like /tmp/page-123.png", () => {
-      const toolResponse =
-        "Screenshot saved to /tmp/page-2026-01-01T12-00-00.png for review.";
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: toolResponse,
-          tool_call_id: "call_abs",
-        },
-      ];
-
-      processor(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as string;
-      expect(content).toContain("[TIP:");
-      expect(content).toContain("loadImageAsBase64");
-      expect(content).toContain("/tmp/page-2026-01-01T12-00-00.png");
-    });
-
-    it("should detect multiple image paths and hint about all of them", () => {
-      const toolResponse =
-        "Before: ./before.png\nAfter: ./after.jpg\nDiff: ./diff.png";
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: toolResponse,
-          tool_call_id: "call_multi",
-        },
-      ];
-
-      processor(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as string;
-      expect(content).toContain("[TIP:");
-      expect(content).toContain("./before.png");
-      expect(content).toContain("./after.jpg");
-      expect(content).toContain("./diff.png");
-    });
-
-    it("should not add hint to messages that are actual base64 image data (already converted)", () => {
-      const validPngBase64 =
-        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [
-        {
-          role: "tool",
-          content: validPngBase64,
-          tool_call_id: "call_base64",
-        },
-      ];
-
-      processor(originalMessages, modifiedMessages);
-
-      // Should be converted to image array, not get a text hint
-      const content = modifiedMessages[0].content;
-      if (Array.isArray(content)) {
-        // Good - was converted to image content, no hint needed
-        expect(content[0]).toHaveProperty("type", "image_url");
-      } else {
-        // If kept as string, the hint should NOT be about a file path
-        // because base64 data URLs don't contain file paths
-        expect(content as string).not.toMatch(/loadImageAsBase64\("data:/);
-      }
-    });
-  });
-
-  describe("Cache-busting prevention", () => {
-    /**
-     * These tests verify that the image-path hint processor does NOT cause
-     * cache-busting on Anthropic's prefix cache. The processor must be
-     * idempotent: calling it N times on the same message array must produce
-     * byte-identical content for all prior messages.
-     */
-
-    it("DEMONSTRATES BUG (pre-fix): hint accumulates on repeated processor calls", () => {
-      // This test documents the original cache-busting behaviour.
-      // After the fix it should pass (hint appears exactly once regardless of
-      // how many times the processor is called).
-      const processor = new Base64ImageProcessor();
-      const processorFn = processor.createProcessor();
-
-      const toolMessage: Message = {
-        role: "tool",
-        content: "Screenshot saved to ./fandango-search.png",
-        tool_call_id: "call_screenshot",
-      };
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [toolMessage];
-
-      // Call the processor 3 times, simulating 3 agent loop turns where the
-      // same historical message is present in modifiedMessages.
-      processorFn(originalMessages, modifiedMessages);
-      processorFn(originalMessages, modifiedMessages);
-      processorFn(originalMessages, modifiedMessages);
-
-      const content = modifiedMessages[0].content as string;
-      const occurrences = (content.match(/\[TIP:/g) || []).length;
-
-      // After the fix the hint must appear exactly once (not 3 times).
-      expect(occurrences).toBe(1);
-    });
-
-    it("hint appears exactly once on the last message even after multiple processor calls", () => {
-      const processor = new Base64ImageProcessor();
-      const processorFn = processor.createProcessor();
-
-      const toolMessage: Message = {
-        role: "tool",
-        content: "Screenshot saved to ./screenshot.png",
-        tool_call_id: "call_1",
-      };
-
-      const originalMessages: Message[] = [];
-      const modifiedMessages: Message[] = [toolMessage];
-
-      // Simulate the processor running 5 times (5 agent turns)
-      for (let i = 0; i < 5; i++) {
-        processorFn(originalMessages, modifiedMessages);
-      }
-
-      const content = modifiedMessages[0].content as string;
-      const tipCount = (content.match(/\[TIP:/g) || []).length;
-      expect(tipCount).toBe(1);
-      expect(content).toContain("loadImageAsBase64");
-    });
-
-    it("historical messages are NOT modified when a new message is added", () => {
-      const processor = new Base64ImageProcessor();
-      const processorFn = processor.createProcessor();
-
-      // Turn 1: tool message with image path
-      const toolMsg: Message = {
-        role: "tool",
-        content: "Saved to ./turn1.png",
-        tool_call_id: "call_t1",
-      };
-      const modifiedMessages: Message[] = [toolMsg];
-      processorFn([], modifiedMessages);
-
-      const contentAfterTurn1 = modifiedMessages[0].content as string;
-      expect(contentAfterTurn1).toContain("[TIP:");
-
-      // Turn 2: a new user message is appended — the OLD tool message must
-      // remain byte-identical so Anthropic's prefix cache is preserved.
-      const userMsg: Message = {
-        role: "user",
-        content: "Okay I see it, now do something else.",
-      };
-      modifiedMessages.push(userMsg);
-      processorFn([], modifiedMessages);
-
-      // The historical tool message must be unchanged
-      expect(modifiedMessages[0].content).toBe(contentAfterTurn1);
-    });
-
-    it("no processor causes hint duplication across two successive calls", () => {
-      // General regression: verify the processor is fully idempotent for tool,
-      // assistant, and user messages that contain image paths.
-      const processor = new Base64ImageProcessor();
-      const processorFn = processor.createProcessor();
-
-      const messages: Message[] = [
-        {
-          role: "tool",
-          content: "See ./result.png for details",
-          tool_call_id: "c1",
-        },
-      ];
-
-      processorFn([], messages);
-      const snapshotAfterFirst = messages[0].content;
-
-      processorFn([], messages);
-      const snapshotAfterSecond = messages[0].content;
-
-      // Content must be byte-identical between calls (cache-safe)
-      expect(snapshotAfterSecond).toBe(snapshotAfterFirst);
-    });
-
-    it("hint is not added to messages that already have the hint (idempotent string)", () => {
-      const processor = new Base64ImageProcessor();
-      const processorFn = processor.createProcessor();
-
-      const messages: Message[] = [
-        {
-          role: "tool",
-          content:
-            "Screenshot at ./page.png\n\n[TIP: An image file path was detected: ./page.png. Use the `loadImageAsBase64` tool with this path to load and view the image: loadImageAsBase64(\"./page.png\") to view the image at ./page.png]",
-          tool_call_id: "c2",
-        },
-      ];
-
-      processorFn([], messages);
-
-      const content = messages[0].content as string;
-      const tipCount = (content.match(/\[TIP:/g) || []).length;
-      expect(tipCount).toBe(1);
-    });
-  });
-});