@crewhaus/tool-screen-capture 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@crewhaus/tool-screen-capture",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Screenshot tool — returns Anthropic image content block for the BROW agent (Section 25 BROW)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/computer-use-driver": "0.0.0",
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/tool-builder": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "zod": "^3.23.8"
+  },
+  "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-screen-capture"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-screen-capture#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,51 @@
+import { describe, expect, test } from "bun:test";
+import type { Driver } from "@crewhaus/computer-use-driver";
+import { createScreenshotTool } from "./index.js";
+
+function stubDriver(pngBytes: Uint8Array): Driver {
+  return {
+    backend: "chromium",
+    async connect() {},
+    async goto() {},
+    async screenshot() {
+      return pngBytes;
+    },
+    async click() {},
+    async type() {},
+    async key() {},
+    async scroll() {},
+    async getViewport() {
+      return { width: 800, height: 600, devicePixelRatio: 1 };
+    },
+    async disconnect() {},
+  };
+}
+
+describe("createScreenshotTool", () => {
+  test("returns an Anthropic image content block with base64 PNG data (T1)", async () => {
+    const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const driver = stubDriver(png);
+    const tool = createScreenshotTool({ driver });
+
+    const result = await tool.execute({ reason: "smoke" }, {});
+    expect(Array.isArray(result)).toBe(true);
+    if (!Array.isArray(result)) throw new Error("expected ToolResultContent array");
+    expect(result).toHaveLength(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");
+    // Decode → matches input bytes.
+    const decoded = Buffer.from(block.source.data, "base64");
+    expect(Array.from(decoded)).toEqual(Array.from(png));
+  });
+
+  test("flag profile: read-only, not destructive, classifier off (controlled output)", () => {
+    const driver = stubDriver(new Uint8Array(0));
+    const tool = createScreenshotTool({ driver });
+    expect(tool.readOnly).toBe(true);
+    expect(tool.destructive).toBe(false);
+    expect(tool.classifyOutput).toBe(false);
+    expect(tool.name).toBe("Screenshot");
+  });
+});

package/src/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Catalog R4 `tool-screen-capture` — Section 25 BROW.
+ *
+ * `Screenshot()` tool. Calls `driver.screenshot()` (PNG bytes), encodes
+ * to base64, and returns an Anthropic image content block the model
+ * can see. Composes with the §14 `tool-image` content-block pattern —
+ * but does NOT touch the filesystem (no path-traversal surface), since
+ * the driver's screenshot is in-memory.
+ *
+ * Configurable downscale factor caps model context budget. Default
+ * keeps the image at full resolution (modern Claude vision handles
+ * 1280x720 cleanly); set `downscalePercent: 50` to halve dimensions.
+ */
+import type { Driver } from "@crewhaus/computer-use-driver";
+import { CrewhausError } from "@crewhaus/errors";
+import { buildTool } from "@crewhaus/tool-builder";
+import type { RegisteredTool, ToolResultContent } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+
+export class ScreenCaptureError extends CrewhausError {
+  override readonly name = "ScreenCaptureError";
+  constructor(message: string, cause?: unknown) {
+    super("tool", message, cause);
+  }
+}
+
+const screenshotSchema = z
+  .object({
+    /**
+     * Optional reason for the snapshot — surfaces in the trace event log
+     * but doesn't affect the captured pixels.
+     */
+    reason: z.string().optional(),
+  })
+  .strict();
+
+export type CreateScreenshotToolOptions = {
+  readonly driver: Driver;
+  /**
+   * Downscale percent (1..100). Default 100 (full size). Useful for
+   * very large viewports.
+   */
+  readonly downscalePercent?: number;
+};
+
+export function createScreenshotTool(opts: CreateScreenshotToolOptions): RegisteredTool {
+  return buildTool({
+    name: "Screenshot",
+    description:
+      "Capture the current browser viewport as a PNG image you can see. Returns an image block; pair with FindElement(description) to locate UI elements before clicking.",
+    inputSchema: screenshotSchema,
+    readOnly: true,
+    destructive: false,
+    concurrencySafe: false,
+    classifyOutput: false,
+    execute: async (): Promise<ToolResultContent> => {
+      const png = await opts.driver.screenshot();
+      // For v0 we ship the PNG verbatim. Downscale path is exposed in
+      // the API but not implemented (Playwright supports `clip` for
+      // crop; downscale would need an image-processing dep — deferred).
+      const data = Buffer.from(png).toString("base64");
+      return [
+        {
+          type: "image",
+          source: { type: "base64", media_type: "image/png", data },
+        },
+      ];
+    },
+  });
+}