fix(agents): keep safe tool images without native backend

vincentkoc · vincentkoc · commit 6b2af6c1ee01 · 2026-06-06T05:11:55.000-07:00
diff --git a/src/agents/tool-images.backend-unavailable.test.ts b/src/agents/tool-images.backend-unavailable.test.ts
@@ -0,0 +1,86 @@
+// Tool image backend-unavailable tests cover safe pass-through when native
+// image processing cannot load on constrained Linux/Termux platforms.
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { backendUnavailableError, getImageMetadataMock, readImageMetadataFromHeaderMock } =
+  vi.hoisted(() => ({
+    backendUnavailableError: new Error("missing image backend"),
+    getImageMetadataMock: vi.fn(),
+    readImageMetadataFromHeaderMock: vi.fn(),
+  }));
+
+const PNG_BASE64 = "iVBORw0KGgo=";
+
+async function importSanitizer() {
+  vi.resetModules();
+  vi.doMock("../media/media-services.js", () => ({
+    IMAGE_REDUCE_QUALITY_STEPS: [85, 75],
+    MAX_IMAGE_INPUT_PIXELS: 25_000_000,
+    buildImageResizeSideGrid: () => [1200],
+    getImageMetadata: getImageMetadataMock,
+    isImageProcessorUnavailableError: (error: unknown) => error === backendUnavailableError,
+    readImageMetadataFromHeader: readImageMetadataFromHeaderMock,
+    resizeToJpeg: async () => {
+      throw backendUnavailableError;
+    },
+  }));
+  return await import("./tool-images.js");
+}
+
+describe("tool image sanitizer without native image backend", () => {
+  beforeEach(() => {
+    getImageMetadataMock.mockReset();
+    readImageMetadataFromHeaderMock.mockReset();
+  });
+
+  it("keeps small header-verified images without probing the backend", async () => {
+    readImageMetadataFromHeaderMock.mockReturnValueOnce({ width: 32, height: 24 });
+    getImageMetadataMock.mockRejectedValueOnce(backendUnavailableError);
+    const { sanitizeContentBlocksImages } = await importSanitizer();
+
+    const out = await sanitizeContentBlocksImages(
+      [{ type: "image" as const, data: PNG_BASE64, mimeType: "image/png" }],
+      "test",
+      { maxDimensionPx: 64, maxBytes: 1024 },
+    );
+
+    expect(out).toStrictEqual([{ type: "image", data: PNG_BASE64, mimeType: "image/png" }]);
+    expect(getImageMetadataMock).not.toHaveBeenCalled();
+  });
+
+  it("drops images that need resizing when the backend is unavailable", async () => {
+    readImageMetadataFromHeaderMock.mockReturnValueOnce({ width: 128, height: 24 });
+    const { sanitizeContentBlocksImages } = await importSanitizer();
+
+    const out = await sanitizeContentBlocksImages(
+      [{ type: "image" as const, data: PNG_BASE64, mimeType: "image/png" }],
+      "test",
+      { maxDimensionPx: 64, maxBytes: 1024 },
+    );
+
+    expect(out).toStrictEqual([
+      {
+        type: "text",
+        text: "[test] omitted image payload: Error: missing image backend",
+      },
+    ]);
+  });
+
+  it("does not pass through compressed images over the pixel cap", async () => {
+    readImageMetadataFromHeaderMock.mockReturnValueOnce({ width: 6000, height: 6000 });
+    const { sanitizeContentBlocksImages } = await importSanitizer();
+
+    const out = await sanitizeContentBlocksImages(
+      [{ type: "image" as const, data: PNG_BASE64, mimeType: "image/png" }],
+      "test",
+      { maxDimensionPx: 6000, maxBytes: 1024 },
+    );
+
+    expect(out).toStrictEqual([
+      {
+        type: "text",
+        text: "[test] omitted image payload: Error: missing image backend",
+      },
+    ]);
+  });
+});
diff --git a/src/agents/tool-images.ts b/src/agents/tool-images.ts
@@ -12,7 +12,10 @@ import {
   getImageMetadata,
   IMAGE_REDUCE_QUALITY_STEPS,
   isImageProcessorUnavailableError,
+  MAX_IMAGE_INPUT_PIXELS,
+  readImageMetadataFromHeader,
   resizeToJpeg,
+  type ImageMetadata,
 } from "../media/media-services.js";
 import {
   DEFAULT_IMAGE_MAX_BYTES,
@@ -64,6 +67,26 @@ function inferMimeTypeFromBase64(base64: string): string | undefined {
   return undefined;
 }
 
+function imageWithinLimits(
+  buffer: Buffer,
+  metadata: ImageMetadata | null,
+  maxDimensionPx: number,
+  maxBytes: number,
+): metadata is ImageMetadata {
+  const width = metadata?.width;
+  const height = metadata?.height;
+  return (
+    typeof width === "number" &&
+    typeof height === "number" &&
+    width > 0 &&
+    height > 0 &&
+    buffer.byteLength <= maxBytes &&
+    width <= maxDimensionPx &&
+    height <= maxDimensionPx &&
+    width * height <= MAX_IMAGE_INPUT_PIXELS
+  );
+}
+
 function formatBytesShort(bytes: number): string {
   if (!Number.isFinite(bytes) || bytes < 1024) {
     return `${Math.max(0, Math.round(bytes))}B`;
@@ -147,19 +170,24 @@ async function resizeImageBase64IfNeeded(params: {
   height?: number;
 }> {
   const buf = Buffer.from(params.base64, "base64");
-  const meta = await getImageMetadata(buf);
+  const headerMeta = readImageMetadataFromHeader(buf);
+  if (imageWithinLimits(buf, headerMeta, params.maxDimensionPx, params.maxBytes)) {
+    return {
+      base64: params.base64,
+      mimeType: params.mimeType,
+      resized: false,
+      width: headerMeta.width,
+      height: headerMeta.height,
+    };
+  }
+  const meta = headerMeta ?? (await getImageMetadata(buf));
   const width = meta?.width;
   const height = meta?.height;
   const overBytes = buf.byteLength > params.maxBytes;
   const hasDimensions = typeof width === "number" && typeof height === "number";
   const overDimensions =
     hasDimensions && (width > params.maxDimensionPx || height > params.maxDimensionPx);
-  if (
-    hasDimensions &&
-    !overBytes &&
-    width <= params.maxDimensionPx &&
-    height <= params.maxDimensionPx
-  ) {
+  if (imageWithinLimits(buf, meta, params.maxDimensionPx, params.maxBytes)) {
     return {
       base64: params.base64,
       mimeType: params.mimeType,
