@crewhaus/tool-image 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@crewhaus/tool-image",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ReadImage tool — validates magic bytes and returns Anthropic base64 image content blocks",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/tool-builder": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "0.0.0",
+    "@crewhaus/tool-permission-matcher": "0.0.0",
+    "@crewhaus/tool-validate": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-image"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-image#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ToolPermissionError, detectMediaType, readImage } from "./index";
+
+// 1×1 transparent PNG — minimal valid PNG. Hand-encoded to avoid pulling in
+// a generator dep just for tests.
+const TINY_PNG = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+  0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4,
+  0x89, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0x00, 0x01, 0x00, 0x00,
+  0x05, 0x00, 0x01, 0x0d, 0x0a, 0x2d, 0xb4, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae,
+  0x42, 0x60, 0x82,
+]);
+
+const TINY_JPEG_HEADER = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46]);
+const TINY_GIF = Buffer.from([0x47, 0x49, 0x46, 0x38, 0x39, 0x61]);
+const TINY_WEBP = Buffer.from([
+  0x52, 0x49, 0x46, 0x46, 0x1a, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50, 0x56, 0x50, 0x38, 0x4c,
+]);
+const PDF_MAGIC = Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34]); // %PDF-1.4
+
+let tmp: string;
+let originalCwd: string;
+beforeEach(() => {
+  originalCwd = process.cwd();
+  tmp = mkdtempSync(join(tmpdir(), "tool-image-"));
+  process.chdir(tmp);
+});
+afterEach(() => {
+  process.chdir(originalCwd);
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("ReadImage — registered tool metadata", () => {
+  test("name + flags", () => {
+    expect(readImage.name).toBe("ReadImage");
+    expect(readImage.readOnly).toBe(true);
+    expect(readImage.destructive).toBe(false);
+    expect(readImage.concurrencySafe).toBe(false);
+  });
+});
+
+describe("detectMediaType — magic bytes", () => {
+  test("recognises PNG", () => {
+    expect(detectMediaType(new Uint8Array(TINY_PNG))).toBe("image/png");
+  });
+  test("recognises JPEG", () => {
+    expect(detectMediaType(new Uint8Array(TINY_JPEG_HEADER))).toBe("image/jpeg");
+  });
+  test("recognises GIF", () => {
+    expect(detectMediaType(new Uint8Array(TINY_GIF))).toBe("image/gif");
+  });
+  test("recognises WebP", () => {
+    expect(detectMediaType(new Uint8Array(TINY_WEBP))).toBe("image/webp");
+  });
+  test("returns null for an unknown signature", () => {
+    expect(detectMediaType(new Uint8Array(PDF_MAGIC))).toBeNull();
+  });
+  test("returns null for too-short input", () => {
+    expect(detectMediaType(new Uint8Array([0x89, 0x50]))).toBeNull();
+  });
+});
+
+describe("ReadImage — happy path", () => {
+  test("returns an Anthropic image content block for a PNG", async () => {
+    writeFileSync(join(tmp, "tiny.png"), TINY_PNG);
+    const result = await readImage.execute({ path: "./tiny.png" });
+    expect(Array.isArray(result)).toBe(true);
+    if (typeof result === "string") throw new Error("expected content array");
+    expect(result.length).toBe(1);
+    const block = result[0];
+    if (block?.type !== "image") throw new Error("expected image block");
+    expect(block.source.type).toBe("base64");
+    expect(block.source.media_type).toBe("image/png");
+    // base64 round-trips back to the original bytes.
+    expect(Buffer.from(block.source.data, "base64").equals(TINY_PNG)).toBe(true);
+  });
+
+  test("works without leading ./", async () => {
+    writeFileSync(join(tmp, "tiny.png"), TINY_PNG);
+    const result = await readImage.execute({ path: "tiny.png" });
+    if (typeof result === "string") throw new Error("expected content array");
+    const block = result[0];
+    if (block?.type !== "image") throw new Error("expected image block");
+    expect(block.source.media_type).toBe("image/png");
+  });
+});
+
+describe("T8 — path traversal", () => {
+  test("rejects ../../etc/passwd", async () => {
+    await expect(readImage.execute({ path: "../../etc/passwd" })).rejects.toBeInstanceOf(
+      ToolPermissionError,
+    );
+  });
+
+  test("rejects an absolute path outside cwd", async () => {
+    await expect(readImage.execute({ path: "/etc/passwd" })).rejects.toBeInstanceOf(
+      ToolPermissionError,
+    );
+  });
+
+  test("rejects a path that resolves outside cwd via ..", async () => {
+    await expect(readImage.execute({ path: "subdir/../../escape.png" })).rejects.toBeInstanceOf(
+      ToolPermissionError,
+    );
+  });
+});
+
+describe("T8 — magic-byte spoof", () => {
+  test("rejects a PDF renamed to .png", async () => {
+    writeFileSync(join(tmp, "evil.png"), PDF_MAGIC);
+    await expect(readImage.execute({ path: "./evil.png" })).rejects.toThrow(
+      /unrecognized image format/,
+    );
+  });
+
+  test("rejects a tiny text file with a .jpg extension", async () => {
+    writeFileSync(join(tmp, "fake.jpg"), Buffer.from("hello world"));
+    await expect(readImage.execute({ path: "./fake.jpg" })).rejects.toThrow(
+      /unrecognized image format/,
+    );
+  });
+});
+
+describe("T8 — oversize cap", () => {
+  test("rejects a file over 5 MB", async () => {
+    // Build a "PNG" larger than 5 MB by padding the valid header with zero bytes.
+    // Magic-bytes check happens AFTER the size check, so this test specifically
+    // exercises the size cap.
+    const big = Buffer.alloc(6 * 1024 * 1024);
+    TINY_PNG.copy(big, 0);
+    writeFileSync(join(tmp, "huge.png"), big);
+    await expect(readImage.execute({ path: "./huge.png" })).rejects.toThrow(/exceeds/);
+  });
+});
+
+describe("T8 — missing file", () => {
+  test("rejects a path that does not exist", async () => {
+    await expect(readImage.execute({ path: "./nope.png" })).rejects.toBeInstanceOf(
+      ToolPermissionError,
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,144 @@
+import * as path from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+import { buildTool } from "@crewhaus/tool-builder";
+import type { RegisteredTool, ToolResultContent } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+
+/**
+ * Section 14 — `ReadImage(path)`. Loads an image from the workspace and
+ * returns an Anthropic `image` content block (base64) so the model can
+ * actually see the image, not a base64 string of it.
+ *
+ * Defenses:
+ *   - Path resolved against `process.cwd()` and rejected if it escapes.
+ *     Mirrors `tool-fs`'s `resolveSafe` — duplicated here rather than
+ *     extracting to a shared util because there are only two consumers.
+ *   - Magic-byte validation on the first 12 bytes — rejects extension
+ *     spoofing (e.g. `evil.png` whose actual content is a PDF).
+ *   - 5 MB per-image cap.
+ *
+ * Deferred (Section 14.5 / 15): a 20-images-per-turn cap. Today there is
+ * no per-turn state shared between tools and runtime — `ToolExecuteContext`
+ * exposes `signal` + opaque `bridge` only. When `RunContext.turnMetrics`
+ * lands we will gate further calls on `imageCount >= 20`.
+ *
+ * Layer R4. Pairs with the `target-cli` codegen contract — `BUILTIN_TOOL_MAP`
+ * has `readImage: { package: "@crewhaus/tool-image", export: "readImage" }`.
+ */
+
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+
+export class ToolPermissionError extends CrewhausError {
+  override readonly name = "ToolPermissionError";
+  readonly toolName: string;
+  readonly path: string;
+  constructor(toolName: string, attemptedPath: string, reason?: string) {
+    super(
+      "tool",
+      `tool "${toolName}" rejected path "${attemptedPath}"${reason ? `: ${reason}` : ": resolved location escapes the workspace root"}`,
+    );
+    this.toolName = toolName;
+    this.path = attemptedPath;
+  }
+}
+
+function resolveSafe(toolName: string, rel: string, root: string = process.cwd()): string {
+  const rootResolved = path.resolve(root);
+  const abs = path.resolve(rootResolved, rel);
+  if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+    throw new ToolPermissionError(toolName, rel);
+  }
+  return abs;
+}
+
+export type ImageMediaType = "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+
+/**
+ * Sniff the first 12 bytes for a known image magic-byte signature. Returns
+ * the canonical media type or `null` for anything else. Tools using this
+ * MUST treat `null` as a hard reject — never trust the file extension.
+ */
+export function detectMediaType(bytes: Uint8Array): ImageMediaType | null {
+  if (bytes.length < 4) return null;
+  // PNG: 89 50 4E 47 0D 0A 1A 0A
+  if (
+    bytes.length >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47 &&
+    bytes[4] === 0x0d &&
+    bytes[5] === 0x0a &&
+    bytes[6] === 0x1a &&
+    bytes[7] === 0x0a
+  ) {
+    return "image/png";
+  }
+  // JPEG: FF D8 FF
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return "image/jpeg";
+  }
+  // GIF: 47 49 46 38 (GIF87a / GIF89a)
+  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38) {
+    return "image/gif";
+  }
+  // WebP: "RIFF" .... "WEBP"
+  if (
+    bytes.length >= 12 &&
+    bytes[0] === 0x52 &&
+    bytes[1] === 0x49 &&
+    bytes[2] === 0x46 &&
+    bytes[3] === 0x46 &&
+    bytes[8] === 0x57 &&
+    bytes[9] === 0x45 &&
+    bytes[10] === 0x42 &&
+    bytes[11] === 0x50
+  ) {
+    return "image/webp";
+  }
+  return null;
+}
+
+const readImageSchema = z.object({ path: z.string().min(1) });
+
+export const readImage: RegisteredTool = buildTool({
+  name: "ReadImage",
+  description:
+    "Read an image file (PNG, JPEG, GIF, or WebP) from the workspace and return it as a base64 image block the model can see. Path is resolved relative to the project root; escaping the root is rejected. Per-image limit: 5 MB.",
+  inputSchema: readImageSchema,
+  readOnly: true,
+  // Not concurrency-safe today: see deferred per-turn image counter above —
+  // when that lands, parallel calls would race on the counter. Mark serial
+  // until the runtime exposes a shared turn store.
+  execute: async (input): Promise<string | ToolResultContent> => {
+    const abs = resolveSafe("ReadImage", input.path);
+    const file = Bun.file(abs);
+    if (!(await file.exists())) {
+      throw new ToolPermissionError("ReadImage", input.path, "file not found");
+    }
+    const size = file.size;
+    if (size > MAX_IMAGE_BYTES) {
+      throw new ToolPermissionError(
+        "ReadImage",
+        input.path,
+        `image is ${size} bytes — exceeds the ${MAX_IMAGE_BYTES}-byte cap`,
+      );
+    }
+    const buf = new Uint8Array(await file.arrayBuffer());
+    const mediaType = detectMediaType(buf);
+    if (mediaType === null) {
+      throw new ToolPermissionError(
+        "ReadImage",
+        input.path,
+        "unrecognized image format (only PNG, JPEG, GIF, WebP supported)",
+      );
+    }
+    const data = Buffer.from(buf).toString("base64");
+    return [
+      {
+        type: "image",
+        source: { type: "base64", media_type: mediaType, data },
+      },
+    ];
+  },
+});