feat: add image utilities and improve web crawl token handling (#2892)

rules/git-workflow.md

@@ -82,6 +82,16 @@ gh api repos/dyad-sh/dyad/issues/{PR_NUMBER}/labels -f "labels[]=label-name"
 
 In CI, `claude-code-action` restricts file access to the repo working directory (e.g., `/home/runner/work/dyad/dyad`). Skills that save intermediate files (like PR diffs) must use `./filename` (current working directory), **never** `/tmp/`. Using `/tmp/` causes errors like: `cat in '/tmp/pr_*_diff.patch' was blocked. For security, Claude Code may only concatenate files from the allowed working directories`.
 
+## Force-pushing after rebase with split-remote origin
+
+When `origin` has separate fetch and push URLs (e.g., fetch → `dyad-sh/dyad`, push → `wwwillchen-bot/dyad`), `git push --force-with-lease` fails with **"stale info"** after a rebase because the local tracking ref was refreshed from the fetch URL but does not reflect the push URL's state. In this specific split-remote configuration, use `git push --force origin HEAD`:
+
+```bash
+git push --force origin HEAD
+```
+
+**Note:** Plain `--force` can overwrite others' remote commits. Only use this in the split-remote scenario described above, where `--force-with-lease` cannot work. In normal setups, always prefer `--force-with-lease`.
+
 ## Rebase workflow and conflict resolution
 
 ### Handling unstaged changes during rebase

src/__tests__/image_dimension_utils.test.ts

+import { describe, it, expect } from "vitest";
+import {
+  getImageDimensionsFromDataUrl,
+  exceedsMaxDimension,
+  validateImageDimensions,
+  MAX_IMAGE_DIMENSION,
+} from "@/pro/main/ipc/handlers/local_agent/tools/image_utils";
+
+describe("image_dimension_utils", () => {
+  describe("getImageDimensionsFromDataUrl", () => {
+    it("returns null for non-data URLs", () => {
+      expect(
+        getImageDimensionsFromDataUrl("https://example.com/image.png"),
+      ).toBeNull();
+    });
+
+    it("returns null for invalid data URL format", () => {
+      expect(
+        getImageDimensionsFromDataUrl("data:text/plain;base64,SGVsbG8="),
+      ).toBeNull();
+    });
+
+    it("parses PNG dimensions correctly", () => {
+      // 1x1 PNG image
+      const png1x1 =
+        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+      const dimensions = getImageDimensionsFromDataUrl(png1x1);
+      expect(dimensions).toEqual({ width: 1, height: 1 });
+    });
+
+    it("parses 2x2 PNG dimensions correctly", () => {
+      // 2x2 PNG image
+      const png2x2 =
+        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEklEQVR42mNk+M9QzwAEjDAGACHSA/0Xj1nMAAAAAElFTkSuQmCC";
+      const dimensions = getImageDimensionsFromDataUrl(png2x2);
+      expect(dimensions).toEqual({ width: 2, height: 2 });
+    });
+
+    it("parses JPEG dimensions correctly", () => {
+      // 1x1 JPEG image (minimal valid JPEG)
+      const jpeg1x1 =
+        "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAn/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBEQCEAwEPwAB//9k=";
+      const dimensions = getImageDimensionsFromDataUrl(jpeg1x1);
+      expect(dimensions).toEqual({ width: 1, height: 1 });
+    });
+
+    it("parses GIF dimensions correctly", () => {
+      const gifHeader = Buffer.from([
+        // "GIF89a"
+        0x47, 0x49, 0x46, 0x38, 0x39, 0x61,
+        // Width: 10 (little-endian)
+        0x0a, 0x00,
+        // Height: 20 (little-endian)
+        0x14, 0x00,
+      ]);
+      const dataUrl = `data:image/gif;base64,${gifHeader.toString("base64")}`;
+      const dimensions = getImageDimensionsFromDataUrl(dataUrl);
+      expect(dimensions).toEqual({ width: 10, height: 20 });
+    });
+
+    it("returns null for truncated PNG", () => {
+      // Truncated PNG (too short to contain dimensions)
+      const truncatedPng = "data:image/png;base64,iVBORw0KGgo=";
+      expect(getImageDimensionsFromDataUrl(truncatedPng)).toBeNull();
+    });
+
+    it("returns null for invalid PNG signature", () => {
+      // Invalid PNG (wrong signature)
+      const invalidPng =
+        "data:image/png;base64,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+      expect(getImageDimensionsFromDataUrl(invalidPng)).toBeNull();
+    });
+
+    it("handles case-insensitive MIME types", () => {
+      // 1x1 PNG with uppercase MIME type
+      const png1x1 =
+        "data:image/PNG;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+      const dimensions = getImageDimensionsFromDataUrl(png1x1);
+      expect(dimensions).toEqual({ width: 1, height: 1 });
+    });
+  });
+
+  describe("exceedsMaxDimension", () => {
+    it("returns false for dimensions within limit", () => {
+      expect(exceedsMaxDimension({ width: 1920, height: 1080 })).toBe(false);
+      expect(exceedsMaxDimension({ width: 8000, height: 8000 })).toBe(false);
+    });
+
+    it("returns true when width exceeds limit", () => {
+      expect(exceedsMaxDimension({ width: 8001, height: 1080 })).toBe(true);
+      expect(exceedsMaxDimension({ width: 10000, height: 100 })).toBe(true);
+    });
+
+    it("returns true when height exceeds limit", () => {
+      expect(exceedsMaxDimension({ width: 1920, height: 8001 })).toBe(true);
+      expect(exceedsMaxDimension({ width: 100, height: 10000 })).toBe(true);
+    });
+
+    it("returns true when both dimensions exceed limit", () => {
+      expect(exceedsMaxDimension({ width: 9000, height: 9000 })).toBe(true);
+    });
+
+    it("respects custom max dimension", () => {
+      expect(exceedsMaxDimension({ width: 1500, height: 1500 }, 1000)).toBe(
+        true,
+      );
+      expect(exceedsMaxDimension({ width: 800, height: 800 }, 1000)).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("validateImageDimensions", () => {
+    it("returns valid for non-data URLs", () => {
+      // Can't parse dimensions from regular URLs, so we let them through
+      const result = validateImageDimensions("https://example.com/image.png");
+      expect(result.isValid).toBe(true);
+      expect(result.dimensions).toBeUndefined();
+    });
+
+    it("returns valid for images within dimension limits", () => {
+      // 1x1 PNG
+      const png1x1 =
+        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+      const result = validateImageDimensions(png1x1);
+      expect(result.isValid).toBe(true);
+      expect(result.dimensions).toEqual({ width: 1, height: 1 });
+    });
+
+    it("returns invalid with error message for oversized images", () => {
+      // Build a minimal PNG header with width=8001, height=100
+      const pngHeader = Buffer.from([
+        0x89,
+        0x50,
+        0x4e,
+        0x47,
+        0x0d,
+        0x0a,
+        0x1a,
+        0x0a, // PNG signature
+        0x00,
+        0x00,
+        0x00,
+        0x0d,
+        0x49,
+        0x48,
+        0x44,
+        0x52, // IHDR length + type
+        0x00,
+        0x00,
+        0x1f,
+        0x41, // width = 8001 (big-endian)
+        0x00,
+        0x00,
+        0x00,
+        0x64, // height = 100 (big-endian)
+        0x08,
+        0x02,
+        0x00,
+        0x00,
+        0x00,
+        0x00,
+        0x00,
+        0x00,
+        0x00,
+      ]);
+      const dataUrl = `data:image/png;base64,${pngHeader.toString("base64")}`;
+      const result = validateImageDimensions(dataUrl);
+      expect(result.isValid).toBe(false);
+      expect(result.dimensions).toEqual({ width: 8001, height: 100 });
+      expect(result.errorMessage).toContain("8001x100");
+      expect(result.errorMessage).toContain(String(MAX_IMAGE_DIMENSION));
+    });
+
+    it("returns valid for unparseable images (letting LLM provider handle them)", () => {
+      // Truncated/invalid image data - we let these through
+      const invalidData = "data:image/png;base64,notvalidbase64";
+      const result = validateImageDimensions(invalidData);
+      expect(result.isValid).toBe(true);
+    });
+  });
+
+  describe("MAX_IMAGE_DIMENSION constant", () => {
+    it("is set to 8000", () => {
+      expect(MAX_IMAGE_DIMENSION).toBe(8000);
+    });
+  });
+});

src/__tests__/image_utils.test.ts

+import { describe, it, expect } from "vitest";
+import {
+  getImageDimensionsFromDataUrl,
+  isImageTooLarge,
+  MAX_IMAGE_DIMENSION,
+} from "@/pro/main/ipc/handlers/local_agent/tools/image_utils";
+
+describe("image_utils", () => {
+  describe("getImageDimensionsFromDataUrl", () => {
+    it("returns null for invalid data URL format", () => {
+      expect(getImageDimensionsFromDataUrl("not a data url")).toBeNull();
+      expect(
+        getImageDimensionsFromDataUrl("data:text/plain;base64,abc"),
+      ).toBeNull();
+      expect(getImageDimensionsFromDataUrl("")).toBeNull();
+    });
+
+    it("extracts dimensions from a valid PNG data URL", () => {
+      // Minimal 1x1 PNG (red pixel)
+      const png1x1 =
+        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+      const result = getImageDimensionsFromDataUrl(png1x1);
+      expect(result).toEqual({ width: 1, height: 1 });
+    });
+
+    it("extracts dimensions from a 100x50 PNG", () => {
+      // 100x50 PNG (minimal valid header)
+      // PNG signature + IHDR chunk with width=100, height=50
+      const pngHeader = Buffer.from([
+        // PNG signature
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+        // IHDR chunk length (13 bytes)
+        0x00, 0x00, 0x00, 0x0d,
+        // "IHDR"
+        0x49, 0x48, 0x44, 0x52,
+        // Width: 100 (big-endian)
+        0x00, 0x00, 0x00, 0x64,
+        // Height: 50 (big-endian)
+        0x00, 0x00, 0x00, 0x32,
+        // Bit depth, color type, compression, filter, interlace
+        0x08, 0x02, 0x00, 0x00, 0x00,
+        // CRC (dummy)
+        0x00, 0x00, 0x00, 0x00,
+      ]);
+      const dataUrl = `data:image/png;base64,${pngHeader.toString("base64")}`;
+      const result = getImageDimensionsFromDataUrl(dataUrl);
+      expect(result).toEqual({ width: 100, height: 50 });
+    });
+
+    it("extracts dimensions from a GIF data URL", () => {
+      // Minimal GIF with 10x20 dimensions
+      const gifHeader = Buffer.from([
+        // "GIF89a"
+        0x47, 0x49, 0x46, 0x38, 0x39, 0x61,
+        // Width: 10 (little-endian)
+        0x0a, 0x00,
+        // Height: 20 (little-endian)
+        0x14, 0x00,
+      ]);
+      const dataUrl = `data:image/gif;base64,${gifHeader.toString("base64")}`;
+      const result = getImageDimensionsFromDataUrl(dataUrl);
+      expect(result).toEqual({ width: 10, height: 20 });
+    });
+
+    it("returns null for truncated image data", () => {
+      // PNG signature only, no IHDR
+      const truncated = Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+      ]);
+      const dataUrl = `data:image/png;base64,${truncated.toString("base64")}`;
+      const result = getImageDimensionsFromDataUrl(dataUrl);
+      expect(result).toBeNull();
+    });
+
+    it("returns null for corrupted PNG signature", () => {
+      const corrupted = Buffer.from([
+        // Invalid signature
+        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+        // IHDR chunk
+        0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x64,
+        0x00, 0x00, 0x00, 0x32, 0x08, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+        0x00,
+      ]);
+      const dataUrl = `data:image/png;base64,${corrupted.toString("base64")}`;
+      const result = getImageDimensionsFromDataUrl(dataUrl);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("isImageTooLarge", () => {
+    it("returns false for images within limits", () => {
+      expect(isImageTooLarge({ width: 1000, height: 1000 })).toBe(false);
+      expect(isImageTooLarge({ width: 8000, height: 8000 })).toBe(false);
+      expect(isImageTooLarge({ width: 1, height: 1 })).toBe(false);
+    });
+
+    it("returns true when width exceeds limit", () => {
+      expect(isImageTooLarge({ width: 8001, height: 1000 })).toBe(true);
+      expect(isImageTooLarge({ width: 10000, height: 100 })).toBe(true);
+    });
+
+    it("returns true when height exceeds limit", () => {
+      expect(isImageTooLarge({ width: 1000, height: 8001 })).toBe(true);
+      expect(isImageTooLarge({ width: 100, height: 10000 })).toBe(true);
+    });
+
+    it("returns true when both dimensions exceed limit", () => {
+      expect(isImageTooLarge({ width: 9000, height: 9000 })).toBe(true);
+    });
+
+    it("respects custom max dimension", () => {
+      expect(isImageTooLarge({ width: 500, height: 500 }, 400)).toBe(true);
+      expect(isImageTooLarge({ width: 300, height: 300 }, 400)).toBe(false);
+    });
+  });
+
+  describe("MAX_IMAGE_DIMENSION", () => {
+    it("is set to 8000", () => {
+      expect(MAX_IMAGE_DIMENSION).toBe(8000);
+    });
+  });
+});

src/__tests__/prepare_step_utils.test.ts

@@ -53,6 +53,31 @@ describe("prepare_step_utils", () => {
         "https://example.com/image.png?width=100&height=200",
       );
     });
+
+    it("passes through valid-sized base64 PNG images", () => {
+      // 1x1 PNG - well under the 8000px limit
+      const png1x1 =
+        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
+      const part: UserMessageContentPart = {
+        type: "image-url",
+        url: png1x1,
+      };
+      const result = transformContentPart(part);
+
+      expect(result.type).toBe("image");
+      expect((result as { type: "image"; image: URL }).image.href).toBe(png1x1);
+    });
+
+    it("passes through non-data URLs without validation (cannot determine dimensions)", () => {
+      // For regular URLs, we can't determine dimensions, so we pass them through
+      const part: UserMessageContentPart = {
+        type: "image-url",
+        url: "https://example.com/potentially-large-image.png",
+      };
+      const result = transformContentPart(part);
+
+      expect(result.type).toBe("image");
+    });
   });
 
   describe("processPendingMessages", () => {

src/pro/main/ipc/handlers/local_agent/prepare_step_utils.ts

@@ -8,6 +8,7 @@
 import { ImagePart, ModelMessage, TextPart, UserModelMessage } from "ai";
 import type { UserMessageContentPart, Todo } from "./tools/types";
 import { cleanMessage } from "@/ipc/utils/ai_messages_utils";
+import { validateImageDimensions } from "./tools/image_utils";
 
 /**
  * Check if a single todo is incomplete (pending or in_progress).
@@ -55,6 +56,8 @@ export interface InjectedMessage {
 
 /**
  * Transform a UserMessageContentPart to the format expected by the AI SDK.
+ * For images, validates dimensions and returns a text message if the image
+ * exceeds the maximum allowed size (8000px in any dimension).
  */
 export function transformContentPart(
   part: UserMessageContentPart,
@@ -63,6 +66,15 @@ export function transformContentPart(
     return { type: "text", text: part.text };
   }
   // part.type === "image-url"
+  // Validate image dimensions before sending to LLM
+  const validation = validateImageDimensions(part.url);
+  if (!validation.isValid && validation.errorMessage) {
+    // Return a text explanation instead of the oversized image
+    return {
+      type: "text",
+      text: `[Image omitted: ${validation.errorMessage}]`,
+    };
+  }
   return { type: "image", image: new URL(part.url) };
 }
 

src/pro/main/ipc/handlers/local_agent/tools/image_utils.ts

+/**
+ * Utility functions for handling images in the local agent context.
+ */
+
+/**
+ * Maximum allowed image dimension (width or height) in pixels.
+ * LLM APIs typically reject images exceeding this size.
+ */
+export const MAX_IMAGE_DIMENSION = 8000;
+
+/**
+ * Image dimension information
+ */
+export interface ImageDimensions {
+  width: number;
+  height: number;
+}
+
+/**
+ * Extract image dimensions from a base64 data URL.
+ * Supports PNG, JPEG/JPG, GIF, and WebP formats.
+ *
+ * @param dataUrl - A base64 data URL (e.g., "data:image/png;base64,...")
+ * @returns The image dimensions, or null if unable to determine
+ */
+export function getImageDimensionsFromDataUrl(
+  dataUrl: string,
+): ImageDimensions | null {
+  try {
+    // Parse the data URL
+    const match = dataUrl.match(/^data:image\/([^;]+);base64,(.+)$/i);
+    if (!match) {
+      return null;
+    }
+
+    const [, mimeSubtype, base64Data] = match;
+    const buffer = Buffer.from(base64Data, "base64");
+
+    // Route to appropriate parser based on image type
+    const type = mimeSubtype.toLowerCase();
+    if (type === "png") {
+      return getPngDimensions(buffer);
+    } else if (type === "jpeg" || type === "jpg") {
+      return getJpegDimensions(buffer);
+    } else if (type === "gif") {
+      return getGifDimensions(buffer);
+    } else if (type === "webp") {
+      return getWebpDimensions(buffer);
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if image dimensions exceed the maximum allowed size.
+ *
+ * @param dimensions - The image dimensions to check
+ * @param maxDimension - Maximum allowed dimension (default: MAX_IMAGE_DIMENSION)
+ * @returns true if either dimension exceeds the max
+ */
+export function isImageTooLarge(
+  dimensions: ImageDimensions,
+  maxDimension: number = MAX_IMAGE_DIMENSION,
+): boolean {
+  return dimensions.width > maxDimension || dimensions.height > maxDimension;
+}
+
+/**
+ * Check if an image's dimensions exceed the maximum allowed size.
+ * Alias for isImageTooLarge, used by image_dimension_utils consumers.
+ */
+export function exceedsMaxDimension(
+  dimensions: ImageDimensions,
+  maxDimension: number = MAX_IMAGE_DIMENSION,
+): boolean {
+  return dimensions.width > maxDimension || dimensions.height > maxDimension;
+}
+
+/**
+ * Validate an image data URL and return validation result.
+ *
+ * @param dataUrl - The image data URL to validate
+ * @returns Object with validation result and optional dimensions/error message
+ */
+export function validateImageDimensions(dataUrl: string): {
+  isValid: boolean;
+  dimensions?: ImageDimensions;
+  errorMessage?: string;
+} {
+  const dimensions = getImageDimensionsFromDataUrl(dataUrl);
+
+  if (!dimensions) {
+    // If we can't parse dimensions, let it through - the LLM provider will handle it
+    return { isValid: true };
+  }
+
+  if (exceedsMaxDimension(dimensions)) {
+    return {
+      isValid: false,
+      dimensions,
+      errorMessage: `Image dimensions (${dimensions.width}x${dimensions.height}) exceed the maximum allowed size of ${MAX_IMAGE_DIMENSION}px. The image has been omitted to prevent processing errors.`,
+    };
+  }
+
+  return { isValid: true, dimensions };
+}
+
+/**
+ * Get dimensions from a PNG image buffer.
+ * PNG stores dimensions in the IHDR chunk at bytes 16-23.
+ */
+function getPngDimensions(buffer: Buffer): ImageDimensions | null {
+  // PNG signature is 8 bytes, followed by IHDR chunk
+  // IHDR starts at byte 8: 4 bytes length, 4 bytes "IHDR", then 4 bytes width, 4 bytes height
+  if (buffer.length < 24) {
+    return null;
+  }
+
+  // Verify PNG signature
+  const pngSignature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+  for (let i = 0; i < 8; i++) {
+    if (buffer[i] !== pngSignature[i]) {
+      return null;
+    }
+  }
+
+  // Read width and height from IHDR chunk (big-endian)
+  const width = buffer.readUInt32BE(16);
+  const height = buffer.readUInt32BE(20);
+
+  return { width, height };
+}
+
+/**
+ * Get dimensions from a JPEG image buffer.
+ * JPEG stores dimensions in SOF (Start of Frame) markers.
+ */
+function getJpegDimensions(buffer: Buffer): ImageDimensions | null {
+  if (buffer.length < 2) {
+    return null;
+  }
+
+  // Verify JPEG signature (SOI marker)
+  if (buffer[0] !== 0xff || buffer[1] !== 0xd8) {
+    return null;
+  }
+
+  let offset = 2;
+
+  while (offset < buffer.length - 1) {
+    // Find next marker
+    if (buffer[offset] !== 0xff) {
+      offset++;
+      continue;
+    }
+
+    const marker = buffer[offset + 1];
+
+    // Skip padding bytes
+    if (marker === 0xff) {
+      offset++;
+      continue;
+    }
+
+    // SOF markers (Start of Frame) contain dimensions
+    // SOF0 (0xC0) through SOF15 (0xCF), excluding DHT (0xC4), DAC (0xCC)
+    if (
+      marker >= 0xc0 &&
+      marker <= 0xcf &&
+      marker !== 0xc4 &&
+      marker !== 0xc8 &&
+      marker !== 0xcc
+    ) {
+      if (offset + 9 > buffer.length) {
+        return null;
+      }
+      // SOF structure: marker (2) + length (2) + precision (1) + height (2) + width (2)
+      const height = buffer.readUInt16BE(offset + 5);
+      const width = buffer.readUInt16BE(offset + 7);
+      return { width, height };
+    }
+
+    // Skip to next segment
+    if (offset + 3 >= buffer.length) {
+      return null;
+    }
+    const segmentLength = buffer.readUInt16BE(offset + 2);
+    if (segmentLength < 2) {
+      return null;
+    }
+    offset += 2 + segmentLength;
+  }
+
+  return null;
+}
+
+/**
+ * Get dimensions from a GIF image buffer.
+ * GIF stores dimensions at bytes 6-9 (little-endian).
+ */
+function getGifDimensions(buffer: Buffer): ImageDimensions | null {
+  if (buffer.length < 10) {
+    return null;
+  }
+
+  // Verify GIF signature ("GIF87a" or "GIF89a")
+  const signature = buffer.toString("ascii", 0, 6);
+  if (signature !== "GIF87a" && signature !== "GIF89a") {
+    return null;
+  }
+
+  // Read width and height (little-endian)
+  const width = buffer.readUInt16LE(6);
+  const height = buffer.readUInt16LE(8);
+
+  return { width, height };
+}
+
+/**
+ * Get dimensions from a WebP image buffer.
+ * WebP has multiple formats (VP8, VP8L, VP8X) with different dimension locations.
+ */
+function getWebpDimensions(buffer: Buffer): ImageDimensions | null {
+  if (buffer.length < 30) {
+    return null;
+  }
+
+  // Verify RIFF header and WEBP signature
+  const riff = buffer.toString("ascii", 0, 4);
+  const webp = buffer.toString("ascii", 8, 12);
+  if (riff !== "RIFF" || webp !== "WEBP") {
+    return null;
+  }
+
+  const chunkType = buffer.toString("ascii", 12, 16);
+
+  if (chunkType === "VP8 ") {
+    // Lossy WebP - dimensions at byte 26-29
+    if (buffer.length < 30) return null;
+    // Skip frame tag (3 bytes) and start code (3 bytes)
+    const width = buffer.readUInt16LE(26) & 0x3fff;
+    const height = buffer.readUInt16LE(28) & 0x3fff;
+    return { width, height };
+  } else if (chunkType === "VP8L") {
+    // Lossless WebP - dimensions encoded in first 4 bytes after signature
+    if (buffer.length < 25) return null;
+    // Signature byte + 4 bytes containing dimensions
+    const bits = buffer.readUInt32LE(21);
+    const width = (bits & 0x3fff) + 1;
+    const height = ((bits >> 14) & 0x3fff) + 1;
+    return { width, height };
+  } else if (chunkType === "VP8X") {
+    // Extended WebP - dimensions at bytes 24-29
+    if (buffer.length < 30) return null;
+    // Canvas dimensions are stored as 24-bit values
+    const width = (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16)) + 1;
+    const height = (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16)) + 1;
+    return { width, height };
+  }
+
+  return null;
+}

src/pro/main/ipc/handlers/local_agent/tools/web_crawl.ts

@@ -2,6 +2,11 @@ import { z } from "zod";
 import log from "electron-log";
 import { ToolDefinition, escapeXmlContent, AgentContext } from "./types";
 import { engineFetch } from "./engine_fetch";
+import {
+  getImageDimensionsFromDataUrl,
+  isImageTooLarge,
+  MAX_IMAGE_DIMENSION,
+} from "./image_utils";
 
 const logger = log.scope("web_crawl");
 
@@ -30,7 +35,7 @@ Trigger a crawl ONLY if BOTH conditions are true:
    - Do not require 'http://' or 'https://'.
 `;
 
-const CLONE_INSTRUCTIONS = `
+const CLONE_INSTRUCTIONS_WITH_SCREENSHOT = `
 
 Replicate the website from the provided screenshot image and markdown.
 
@@ -54,6 +59,30 @@ Replicate the website from the provided screenshot image and markdown.
 Always include the placeholder.svg file in your output file tree.
 `;
 
+const CLONE_INSTRUCTIONS_WITHOUT_SCREENSHOT = `
+
+Replicate the website from the provided markdown snapshot.
+
+**Use the markdown snapshot below as your reference** to understand the page structure, content, and layout of the website.
+
+**IMPORTANT: Image Handling**
+- Do NOT use or reference real external image URLs.
+- Instead, create a file named "placeholder.svg" at "/public/assets/placeholder.svg".
+- The file must be included in the output as its own code block.
+- The SVG should be a simple neutral gray rectangle, like:
+  \`\`\`svg
+  <svg width="400" height="300" xmlns="http://www.w3.org/2000/svg">
+    <rect width="100%" height="100%" fill="#e2e2e2"/>
+  </svg>
+  \`\`\`
+
+**When generating code:**
+- Replace all \`<img src="...">\` with: \`<img src="/assets/placeholder.svg" alt="placeholder" />\`
+- If using Next.js Image component: \`<Image src="/assets/placeholder.svg" alt="placeholder" width={400} height={300} />\`
+
+Always include the placeholder.svg file in your output file tree.
+`;
+
 async function callWebCrawl(
   url: string,
   ctx: Pick<AgentContext, "dyadRequestId">,
@@ -113,14 +142,43 @@ export const webCrawlTool: ToolDefinition<z.infer<typeof webCrawlSchema>> = {
     }
     logger.log(`Web crawl completed for URL: ${args.url}`);
 
-    ctx.appendUserMessage([
-      { type: "text", text: CLONE_INSTRUCTIONS },
-      { type: "image-url", url: result.screenshot },
-      {
+    // Check image dimensions before sending to LLM
+    const imageDimensions = getImageDimensionsFromDataUrl(result.screenshot);
+    const imageExceedsSizeLimit =
+      imageDimensions && isImageTooLarge(imageDimensions);
+
+    if (imageExceedsSizeLimit) {
+      logger.warn(
+        `Screenshot dimensions (${imageDimensions.width}x${imageDimensions.height}) exceed max allowed size (${MAX_IMAGE_DIMENSION}px). Omitting image.`,
+      );
+    }
+
+    const includeScreenshot = !imageExceedsSizeLimit;
+    const instructions = includeScreenshot
+      ? CLONE_INSTRUCTIONS_WITH_SCREENSHOT
+      : CLONE_INSTRUCTIONS_WITHOUT_SCREENSHOT;
+
+    const messageContent: Parameters<typeof ctx.appendUserMessage>[0] = [
+      { type: "text", text: instructions },
+    ];
+
+    if (includeScreenshot) {
+      // Add the screenshot image
+      messageContent.push({ type: "image-url", url: result.screenshot });
+    } else {
+      // Add explanation instead of the image
+      messageContent.push({
         type: "text",
-        text: formatSnippet("Markdown snapshot:", result.markdown, "markdown"),
-      },
-    ]);
+        text: `[Screenshot omitted: Image dimensions (${imageDimensions!.width}x${imageDimensions!.height}px) exceed the maximum allowed size of ${MAX_IMAGE_DIMENSION}px. Please rely on the markdown snapshot below to understand the page structure and content.]`,
+      });
+    }
+
+    messageContent.push({
+      type: "text",
+      text: formatSnippet("Markdown snapshot:", result.markdown, "markdown"),
+    });
+
+    ctx.appendUserMessage(messageContent);
 
     return "Web crawl completed.";
   },
@@ -129,12 +187,14 @@ export const webCrawlTool: ToolDefinition<z.infer<typeof webCrawlSchema>> = {
 const MAX_TEXT_SNIPPET_LENGTH = 16_000;
 
 // Format a code snippet with a label and language, truncating if necessary.
+// Sanitizes triple backticks in content to prevent code block breakout.
 export function formatSnippet(
   label: string,
   value: string,
   lang: string,
 ): string {
-  return `${label}:\n\`\`\`${lang}\n${truncateText(value)}\n\`\`\``;
+  const sanitized = truncateText(value).replace(/```/g, "` ` `");
+  return `${label}:\n\`\`\`${lang}\n${sanitized}\n\`\`\``;
 }
 
 function truncateText(value: string): string {