@crewhaus/tool-mouse-keyboard 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@crewhaus/tool-mouse-keyboard",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Click / Type / Key / Scroll tools — destructive: true (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-mouse-keyboard"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-mouse-keyboard#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,118 @@
+import { describe, expect, test } from "bun:test";
+import type { Driver } from "@crewhaus/computer-use-driver";
+import {
+  createAllMouseKeyboardTools,
+  createClickTool,
+  createKeyTool,
+  createScrollTool,
+  createTypeTool,
+} from "./index.js";
+
+function recordingDriver(): { driver: Driver; calls: string[] } {
+  const calls: string[] = [];
+  const driver: Driver = {
+    backend: "chromium",
+    async connect() {},
+    async goto() {},
+    async screenshot() {
+      return new Uint8Array();
+    },
+    async click(x, y, button = "left") {
+      calls.push(`click ${button} ${x} ${y}`);
+    },
+    async type(text) {
+      calls.push(`type ${text}`);
+    },
+    async key(combo) {
+      calls.push(`key ${combo}`);
+    },
+    async scroll(dx, dy) {
+      calls.push(`scroll ${dx} ${dy}`);
+    },
+    async getViewport() {
+      return { width: 800, height: 600, devicePixelRatio: 1 };
+    },
+    async disconnect() {},
+  };
+  return { driver, calls };
+}
+
+describe("Mouse + keyboard tools (T1 wrapping)", () => {
+  test("Click forwards (x, y, button) to driver.click", async () => {
+    const { driver, calls } = recordingDriver();
+    const tool = createClickTool({ driver });
+    const r = await tool.execute({ x: 100, y: 200, button: "left" }, {});
+    expect(calls).toEqual(["click left 100 200"]);
+    expect(typeof r === "string" && r.includes("Clicked left at (100, 200)")).toBe(true);
+  });
+
+  test("Click default button is left", async () => {
+    const { driver, calls } = recordingDriver();
+    const tool = createClickTool({ driver });
+    await tool.execute({ x: 1, y: 2 }, {});
+    expect(calls).toEqual(["click left 1 2"]);
+  });
+
+  test("Type forwards text", async () => {
+    const { driver, calls } = recordingDriver();
+    const tool = createTypeTool({ driver });
+    await tool.execute({ text: "hello" }, {});
+    expect(calls).toEqual(["type hello"]);
+  });
+
+  test("Key forwards combo", async () => {
+    const { driver, calls } = recordingDriver();
+    const tool = createKeyTool({ driver });
+    await tool.execute({ combo: "Enter" }, {});
+    expect(calls).toEqual(["key Enter"]);
+  });
+
+  test("Scroll forwards dx/dy", async () => {
+    const { driver, calls } = recordingDriver();
+    const tool = createScrollTool({ driver });
+    await tool.execute({ dx: 0, dy: 100 }, {});
+    expect(calls).toEqual(["scroll 0 100"]);
+  });
+
+  test("All four tools are destructive: true (T8 — permission floor)", () => {
+    const { driver } = recordingDriver();
+    const tools = createAllMouseKeyboardTools({ driver });
+    expect(tools.click.destructive).toBe(true);
+    expect(tools.type.destructive).toBe(true);
+    expect(tools.key.destructive).toBe(true);
+    expect(tools.scroll.destructive).toBe(true);
+  });
+
+  test("createAllMouseKeyboardTools returns the four named tools", () => {
+    const { driver } = recordingDriver();
+    const tools = createAllMouseKeyboardTools({ driver });
+    expect(tools.click.name).toBe("Click");
+    expect(tools.type.name).toBe("Type");
+    expect(tools.key.name).toBe("Key");
+    expect(tools.scroll.name).toBe("Scroll");
+  });
+
+  test("driver errors are surfaced as tool result strings (not thrown)", async () => {
+    const driver: Driver = {
+      backend: "chromium",
+      async connect() {},
+      async goto() {},
+      async screenshot() {
+        return new Uint8Array();
+      },
+      async click() {
+        throw new Error("driver explosion");
+      },
+      async type() {},
+      async key() {},
+      async scroll() {},
+      async getViewport() {
+        return { width: 0, height: 0, devicePixelRatio: 1 };
+      },
+      async disconnect() {},
+    };
+    const tool = createClickTool({ driver });
+    const r = await tool.execute({ x: 1, y: 1 }, {});
+    expect(typeof r === "string" && r.includes("[Click error]")).toBe(true);
+  });
+});

package/src/index.ts

@@ -0,0 +1,159 @@
+/**
+ * Catalog R4 `tool-mouse-keyboard` — Section 25 BROW.
+ *
+ * Wraps `computer-use-driver` mouse + keyboard methods 1:1 as
+ * registered tools. ALL FOUR are `destructive: true` so the §3
+ * permission-engine refuses to grant `allow` in default mode without
+ * an explicit `alwaysAllow` rule. The smoke's permission-floor probe
+ * exercises this path: same spec WITHOUT alwaysAllow rules → denial
+ * cites the destructive flag + missing rule.
+ *
+ * Tools:
+ *   - `Click(x, y, button?)` — `left | right | middle` click.
+ *   - `Type(text)`           — typed input.
+ *   - `Key(combo)`           — special-key combos ("Enter", "Tab", "Control+a").
+ *   - `Scroll(dx, dy)`       — wheel scroll in pixels.
+ */
+import type { Driver, MouseButton } from "@crewhaus/computer-use-driver";
+import { CrewhausError } from "@crewhaus/errors";
+import { buildTool } from "@crewhaus/tool-builder";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+
+export class MouseKeyboardError extends CrewhausError {
+  override readonly name = "MouseKeyboardError";
+  constructor(message: string, cause?: unknown) {
+    super("tool", message, cause);
+  }
+}
+
+export type CreateMouseKeyboardToolsOptions = {
+  readonly driver: Driver;
+};
+
+const clickSchema = z
+  .object({
+    x: z.number().int().min(0),
+    y: z.number().int().min(0),
+    button: z.enum(["left", "right", "middle"]).optional(),
+  })
+  .strict();
+
+const typeSchema = z.object({ text: z.string() }).strict();
+
+const keySchema = z
+  .object({
+    combo: z
+      .string()
+      .min(1)
+      .describe(
+        "Single key or combo, e.g. 'Enter', 'Tab', 'Control+a'. Uses Playwright's key naming.",
+      ),
+  })
+  .strict();
+
+const scrollSchema = z
+  .object({
+    dx: z.number().int(),
+    dy: z.number().int(),
+  })
+  .strict();
+
+export function createClickTool(opts: CreateMouseKeyboardToolsOptions): RegisteredTool {
+  return buildTool({
+    name: "Click",
+    description:
+      "Click at viewport pixel coordinates (x, y). Defaults to left button. Use FindElement(description) to get coordinates from a natural-language target. DESTRUCTIVE: requires explicit alwaysAllow rule.",
+    inputSchema: clickSchema,
+    readOnly: false,
+    destructive: true,
+    concurrencySafe: false,
+    classifyOutput: false,
+    execute: async (input) => {
+      const button: MouseButton = input.button ?? "left";
+      try {
+        await opts.driver.click(input.x, input.y, button);
+      } catch (err) {
+        return `[Click error] ${(err as Error).message ?? String(err)}`;
+      }
+      return `Clicked ${button} at (${input.x}, ${input.y}).`;
+    },
+  });
+}
+
+export function createTypeTool(opts: CreateMouseKeyboardToolsOptions): RegisteredTool {
+  return buildTool({
+    name: "Type",
+    description:
+      "Type text at the focused input. Click an input first to focus it. DESTRUCTIVE: requires explicit alwaysAllow rule.",
+    inputSchema: typeSchema,
+    readOnly: false,
+    destructive: true,
+    concurrencySafe: false,
+    classifyOutput: false,
+    execute: async (input) => {
+      try {
+        await opts.driver.type(input.text);
+      } catch (err) {
+        return `[Type error] ${(err as Error).message ?? String(err)}`;
+      }
+      return `Typed ${input.text.length} chars.`;
+    },
+  });
+}
+
+export function createKeyTool(opts: CreateMouseKeyboardToolsOptions): RegisteredTool {
+  return buildTool({
+    name: "Key",
+    description:
+      "Press a single key or combo (e.g. 'Enter', 'Tab', 'Control+a'). Uses Playwright's key naming. DESTRUCTIVE: requires explicit alwaysAllow rule.",
+    inputSchema: keySchema,
+    readOnly: false,
+    destructive: true,
+    concurrencySafe: false,
+    classifyOutput: false,
+    execute: async (input) => {
+      try {
+        await opts.driver.key(input.combo);
+      } catch (err) {
+        return `[Key error] ${(err as Error).message ?? String(err)}`;
+      }
+      return `Pressed ${input.combo}.`;
+    },
+  });
+}
+
+export function createScrollTool(opts: CreateMouseKeyboardToolsOptions): RegisteredTool {
+  return buildTool({
+    name: "Scroll",
+    description:
+      "Scroll by pixel deltas. Positive dy scrolls down. DESTRUCTIVE: requires explicit alwaysAllow rule.",
+    inputSchema: scrollSchema,
+    readOnly: false,
+    destructive: true,
+    concurrencySafe: false,
+    classifyOutput: false,
+    execute: async (input) => {
+      try {
+        await opts.driver.scroll(input.dx, input.dy);
+      } catch (err) {
+        return `[Scroll error] ${(err as Error).message ?? String(err)}`;
+      }
+      return `Scrolled (${input.dx}, ${input.dy}).`;
+    },
+  });
+}
+
+export function createAllMouseKeyboardTools(opts: CreateMouseKeyboardToolsOptions): {
+  click: RegisteredTool;
+  type: RegisteredTool;
+  key: RegisteredTool;
+  scroll: RegisteredTool;
+} {
+  return {
+    click: createClickTool(opts),
+    type: createTypeTool(opts),
+    key: createKeyTool(opts),
+    scroll: createScrollTool(opts),
+  };
+}