pi-browser-harness 0.2.0 → 0.3.2

package/src/domains/drag.ts

@@ -0,0 +1,66 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+
+const DragArgs = Type.Object({
+  startX: Type.Number(),
+  startY: Type.Number(),
+  endX: Type.Number(),
+  endY: Type.Number(),
+  dataTransfer: Type.Optional(
+    Type.Record(Type.String(), Type.String(), {
+      description: "Optional MIME → data map for DataTransfer (e.g., { 'text/plain': 'hello' })",
+    }),
+  ),
+});
+
+export const dragAndDropTool = defineBrowserTool({
+  name: "browser_drag_and_drop",
+  label: "Browser Drag & Drop",
+  description: "Drag from (startX, startY) to (endX, endY) using CDP Input.dispatchDragEvent.",
+  promptSnippet: "Drag and drop between two coordinates",
+  promptGuidelines: [
+    "Coordinates in CSS pixels.",
+    "dataTransfer is an optional MIME→data map (e.g., { 'text/plain': 'hello' }).",
+  ],
+  parameters: DragArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const data = args.dataTransfer
+      ? {
+          items: Object.entries(args.dataTransfer).map(([mimeType, payload]) => ({
+            mimeType,
+            data: Buffer.from(payload).toString("base64"),
+          })),
+          dragOperationsMask: 1,
+        }
+      : { items: [], dragOperationsMask: 1 };
+    const cdp = client.session();
+    const calls: ReadonlyArray<readonly [string, Record<string, unknown>]> = [
+      ["Input.dispatchMouseEvent", { type: "mousePressed", x: args.startX, y: args.startY, button: "left", clickCount: 1 }],
+      ["Input.dispatchDragEvent", { type: "dragEnter", x: args.startX, y: args.startY, data, modifiers: 0 }],
+      // 5 interpolated dragOver steps from start → end so the page sees a smooth drag.
+      ...Array.from({ length: 5 }, (_, i): readonly [string, Record<string, unknown>] => {
+        const t = (i + 1) / 5;
+        return [
+          "Input.dispatchDragEvent",
+          {
+            type: "dragOver",
+            x: Math.round(args.startX + (args.endX - args.startX) * t),
+            y: Math.round(args.startY + (args.endY - args.startY) * t),
+            data,
+            modifiers: 0,
+          },
+        ];
+      }),
+      ["Input.dispatchDragEvent", { type: "drop", x: args.endX, y: args.endY, data, modifiers: 0 }],
+      ["Input.dispatchMouseEvent", { type: "mouseReleased", x: args.endX, y: args.endY, button: "left", clickCount: 1 }],
+    ];
+    for (const [method, params] of calls) {
+      const r = await cdp.call(method, params);
+      if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    }
+    return ok({
+      text: `Dragged from (${args.startX},${args.startY}) to (${args.endX},${args.endY})`,
+    });
+  },
+});

package/src/domains/files.ts

@@ -0,0 +1,194 @@
+import { mkdir, access, constants, stat, readFile, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { Type } from "typebox";
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { safeJs } from "../util/js-template";
+import { pdfPath } from "../util/paths";
+
+const UploadArgs = Type.Object({
+  selector: Type.String({ description: "CSS selector of the file <input>" }),
+  filePath: Type.String({ description: "Absolute path to the file to upload" }),
+});
+
+const verifyReadable = async (filePath: string): Promise<Result<void, ToolErr>> => {
+  try {
+    await access(filePath, constants.R_OK);
+    return ok(undefined);
+  } catch (e) {
+    return err({
+      kind: "io_error",
+      message: `Cannot read file: ${filePath} (${e instanceof Error ? e.message : String(e)})`,
+    });
+  }
+};
+
+const tryCdpUpload = async (
+  client: BrowserClient,
+  selector: string,
+  filePath: string,
+): Promise<Result<void, ToolErr>> => {
+  const doc = await client.session().call("DOM.getDocument", { depth: -1 });
+  if (!doc.success) return err({ kind: "cdp_error", message: doc.error.message });
+  // CDP boundary cast: DOM.getDocument returns { root: { nodeId: number } }
+  const root = (doc.data as { root: { nodeId: number } }).root;
+  const q = await client.session().call("DOM.querySelector", { nodeId: root.nodeId, selector });
+  if (!q.success) return err({ kind: "cdp_error", message: q.error.message });
+  // CDP boundary cast: DOM.querySelector returns { nodeId: number }
+  const nodeId = (q.data as { nodeId: number }).nodeId;
+  if (!nodeId) return err({ kind: "invalid_state", message: `Selector matched 0 file inputs: ${selector}` });
+  const set = await client.session().call("DOM.setFileInputFiles", { files: [filePath], nodeId });
+  if (!set.success) return err({ kind: "cdp_error", message: set.error.message });
+  const verify = await client.evaluateJs(safeJs`document.querySelector(${selector})?.files?.length || 0`);
+  if (!verify.success) return err({ kind: "cdp_error", message: verify.error.message });
+  if (Number(verify.data ?? 0) === 0) {
+    return err({ kind: "invalid_state", message: "CDP upload reported success but file count is 0" });
+  }
+  return ok(undefined);
+};
+
+const inferMime = (name: string): string => {
+  if (name.endsWith(".png")) return "image/png";
+  if (name.endsWith(".jpg") || name.endsWith(".jpeg")) return "image/jpeg";
+  if (name.endsWith(".pdf")) return "application/pdf";
+  if (name.endsWith(".json")) return "application/json";
+  return "text/plain";
+};
+
+const jsFallbackUpload = async (
+  client: BrowserClient,
+  selector: string,
+  filePath: string,
+): Promise<Result<void, ToolErr>> => {
+  const buf = await readFile(filePath);
+  const st = await stat(filePath);
+  const name = basename(filePath);
+  const mime = inferMime(name);
+  const expr = safeJs`
+    (() => {
+      const input = document.querySelector(${selector});
+      if (!input || input.type !== 'file') throw new Error('File input not found');
+      const bin = atob(${buf.toString("base64")});
+      const bytes = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+      const file = new File([bytes], ${name}, { type: ${mime}, lastModified: ${st.mtimeMs} });
+      const dt = new DataTransfer();
+      dt.items.add(file);
+      input.files = dt.files;
+      input.dispatchEvent(new Event('change', { bubbles: true }));
+      return input.files.length;
+    })()
+  `;
+  const r = await client.evaluateJs(expr);
+  if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+  if (!Number(r.data ?? 0)) return err({ kind: "invalid_state", message: "JS fallback set 0 files" });
+  return ok(undefined);
+};
+
+export const uploadFileTool = defineBrowserTool({
+  name: "browser_upload_file",
+  label: "Browser Upload File",
+  description: "Set files on a file <input> via CDP, with a JS-DataTransfer fallback for stubborn pages.",
+  promptSnippet: "Upload a file to a file input",
+  promptGuidelines: [
+    "File path must be absolute and readable.",
+    "Selector must match a file input.",
+  ],
+  parameters: UploadArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const readable = await verifyReadable(args.filePath);
+    if (!readable.success) return readable;
+    const cdp = await tryCdpUpload(client, args.selector, args.filePath);
+    if (cdp.success) {
+      return ok({
+        text: `Uploaded ${args.filePath} via CDP`,
+        details: { mode: "cdp", filePath: args.filePath },
+      });
+    }
+    const js = await jsFallbackUpload(client, args.selector, args.filePath);
+    if (js.success) {
+      return ok({
+        text: `Uploaded ${args.filePath} via JS DataTransfer`,
+        details: { mode: "js", filePath: args.filePath },
+      });
+    }
+    return err({
+      kind: "cdp_error",
+      message: `Both CDP and JS fallback failed. CDP: ${cdp.error.message}; JS: ${js.error.message}`,
+    });
+  },
+});
+
+const DownloadArgs = Type.Object({
+  downloadPath: Type.String({ description: "Absolute path to a writable directory where downloads should be saved" }),
+});
+
+export const downloadTool = defineBrowserTool({
+  name: "browser_download",
+  label: "Browser Download",
+  description: "Configure Chrome's download behavior: set the save directory and disable the save-as prompt.",
+  promptSnippet: "Configure download directory",
+  promptGuidelines: [
+    "Pass an absolute path to an existing writable directory.",
+    "Affects all subsequent downloads on this browser.",
+  ],
+  parameters: DownloadArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    try {
+      await mkdir(args.downloadPath, { recursive: true });
+    } catch (e) {
+      return err({
+        kind: "io_error",
+        message: `Cannot create download directory: ${args.downloadPath} (${e instanceof Error ? e.message : String(e)})`,
+      });
+    }
+    try {
+      const s = await stat(args.downloadPath);
+      if (!s.isDirectory()) {
+        return err({ kind: "io_error", message: `Not a directory: ${args.downloadPath}` });
+      }
+      await access(args.downloadPath, constants.W_OK);
+    } catch (e) {
+      return err({
+        kind: "io_error",
+        message: `Download path unusable: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+    const r = await client.session().callBrowser("Browser.setDownloadBehavior", {
+      behavior: "allow",
+      downloadPath: args.downloadPath,
+      eventsEnabled: true,
+    });
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    return ok({
+      text: `Downloads will save to: ${args.downloadPath}`,
+      details: { downloadPath: args.downloadPath },
+    });
+  },
+});
+
+const PrintPdfArgs = Type.Object({
+  outputPath: Type.Optional(Type.String({ description: "Where to save the PDF. Default: tmpdir + uuid." })),
+});
+
+export const printToPdfTool = defineBrowserTool({
+  name: "browser_print_to_pdf",
+  label: "Browser Print to PDF",
+  description: "Print the current page to a PDF file using Chrome's Page.printToPDF.",
+  promptSnippet: "Print the current page to PDF",
+  promptGuidelines: ["Default output path is in tmpdir; pass outputPath to control."],
+  parameters: PrintPdfArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await client.session().call("Page.printToPDF", {
+      printBackground: true,
+      preferCSSPageSize: true,
+    });
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    // CDP boundary cast: Page.printToPDF returns { data: string } (base64-encoded PDF)
+    const data = (r.data as { data: string }).data;
+    const path = args.outputPath ?? pdfPath(client.namespace);
+    await writeFile(path, Buffer.from(data, "base64"));
+    return ok({ text: `PDF saved: ${path}`, details: { path } });
+  },
+});

package/src/domains/history.ts

@@ -0,0 +1,76 @@
+import { Type } from "typebox";
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+
+type HistoryEntry = { readonly id: number; readonly url: string; readonly title: string };
+type History = { readonly entries: ReadonlyArray<HistoryEntry>; readonly currentIndex: number };
+
+const fetchHistory = async (client: BrowserClient): Promise<Result<History, ToolErr>> => {
+  const r = await client.session().call("Page.getNavigationHistory");
+  if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+  return ok(r.data as History);
+};
+
+export const goBackTool = defineBrowserTool({
+  name: "browser_go_back",
+  label: "Browser Go Back",
+  description: "Navigate back one page in history.",
+  promptSnippet: "Go back one page",
+  promptGuidelines: ["Use to return to the previous page after navigating."],
+  parameters: Type.Object({}),
+  async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const h = await fetchHistory(client);
+    if (!h.success) return h;
+    if (h.data.currentIndex <= 0) return ok({ text: "Already at the beginning of history." });
+    const target = h.data.entries[h.data.currentIndex - 1];
+    if (!target) return err({ kind: "internal", message: "history entry missing at index" });
+    const nav = await client.session().call("Page.navigateToHistoryEntry", { entryId: target.id });
+    if (!nav.success) return err({ kind: "cdp_error", message: nav.error.message });
+    return ok({ text: `Navigated back to: ${target.url}`, details: { url: target.url } });
+  },
+});
+
+export const goForwardTool = defineBrowserTool({
+  name: "browser_go_forward",
+  label: "Browser Go Forward",
+  description: "Navigate forward one page in history.",
+  promptSnippet: "Go forward one page",
+  promptGuidelines: ["Use to undo a browser_go_back."],
+  parameters: Type.Object({}),
+  async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const h = await fetchHistory(client);
+    if (!h.success) return h;
+    if (h.data.currentIndex >= h.data.entries.length - 1) return ok({ text: "Already at the end of history." });
+    const target = h.data.entries[h.data.currentIndex + 1];
+    if (!target) return err({ kind: "internal", message: "history entry missing at index" });
+    const nav = await client.session().call("Page.navigateToHistoryEntry", { entryId: target.id });
+    if (!nav.success) return err({ kind: "cdp_error", message: nav.error.message });
+    return ok({ text: `Navigated forward to: ${target.url}`, details: { url: target.url } });
+  },
+});
+
+export const reloadTool = defineBrowserTool({
+  name: "browser_reload",
+  label: "Browser Reload",
+  description: "Reload the current page.",
+  promptSnippet: "Reload the page",
+  promptGuidelines: ["Use to refresh the page, e.g. after server-side changes."],
+  parameters: Type.Object({}),
+  async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await client.session().call("Page.reload");
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const info = await client.pageInfo();
+    if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
+    if ("dialog" in info.data) {
+      return ok({
+        text: `Reloaded. ⚠️ Dialog open: ${info.data.dialog.type}`,
+        details: { dialog: info.data.dialog },
+      });
+    }
+    return ok({
+      text: `Reloaded: ${info.data.title} (${info.data.url})`,
+      details: { page: info.data },
+    });
+  },
+});

package/src/domains/js.ts

@@ -0,0 +1,197 @@
+import { readFile } from "node:fs/promises";
+import { resolve, isAbsolute } from "node:path";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+import { Type } from "typebox";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { applyTruncation } from "../util/truncate";
+
+// AsyncFunction constructor — the documented Node.js mechanism for compiling
+// arbitrary user-supplied source. Equivalent to `new Function` but produces an
+// async function we can `await`. The full RCE risk is contained at the source
+// boundary: see the path allowlist + timeout below. A plain `unknown` cast
+// would lose the constructor signature; we keep this single typed cast.
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as
+  new (...args: ReadonlyArray<string>) => (...args: ReadonlyArray<unknown>) => Promise<unknown>;
+
+// ESNext module — bare `require` is not in scope. createRequire provides the
+// CJS resolver anchored to this file's URL so scripts can require() builtins
+// and installed CJS packages.
+const requireFromHere = createRequire(import.meta.url);
+
+const ExecuteJsArgs = Type.Object({
+  expression: Type.String({ description: "JavaScript expression. `return X` is auto-wrapped in an IIFE." }),
+  targetId: Type.Optional(Type.String({ description: "Optional iframe targetId; default = current page." })),
+});
+
+export const executeJsTool = defineBrowserTool({
+  name: "browser_execute_js",
+  label: "Browser Execute JS",
+  description:
+    "Run JavaScript in the page (or a specific iframe target). `return X` gets auto-wrapped in an IIFE for convenience. Always use safeJs / JSON.stringify when interpolating untrusted strings into source.",
+  promptSnippet: "Execute JS in the page (or iframe)",
+  promptGuidelines: [
+    "`return foo` is auto-wrapped in an IIFE — both `foo` and `(() => foo)()` work.",
+    "For iframes, get a targetId via browser_execute_js with `Object.values(document.querySelectorAll('iframe'))` then call browser_execute_js with targetId.",
+    "Result must be JSON-serializable (Runtime.evaluate returnByValue=true).",
+  ],
+  parameters: ExecuteJsArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await client.evaluateJs(args.expression, args.targetId);
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const valueStr = r.data === undefined ? "undefined" : JSON.stringify(r.data);
+    const truncated = await applyTruncation(valueStr, "js");
+    return ok({
+      text: truncated.text,
+      details: truncated.fullOutputPath !== undefined
+        ? { valueLength: valueStr.length, fullOutputPath: truncated.fullOutputPath }
+        : { valueLength: valueStr.length },
+    });
+  },
+});
+
+const RunScriptArgs = Type.Object({
+  path: Type.String({ description: "Absolute path to the script file (.js or .mjs)" }),
+  params: Type.Optional(
+    Type.Object({}, { additionalProperties: true, description: "Args passed to the script as `params`" }),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      default: 60_000,
+      minimum: 100,
+      maximum: 600_000,
+      description: "Hard timeout in ms. Default 60s, max 600s.",
+    }),
+  ),
+});
+
+const allowedRoots = (): ReadonlyArray<string> => {
+  const env = process.env["BH_SCRIPT_DIR"];
+  return [tmpdir(), process.cwd(), ...(env !== undefined ? [env] : [])].map((d) => resolve(d));
+};
+
+const isPathAllowed = (p: string): boolean => {
+  const abs = resolve(p);
+  return allowedRoots().some((root) => abs === root || abs.startsWith(`${root}/`));
+};
+
+const MAX_SOURCE_BYTES = 1_000_000;
+
+type ContentItem = { readonly type: "text"; readonly text: string };
+
+const isContentItem = (v: unknown): v is ContentItem =>
+  typeof v === "object" && v !== null
+    && (v as Readonly<Record<string, unknown>>)["type"] === "text"
+    && typeof (v as Readonly<Record<string, unknown>>)["text"] === "string";
+
+export const runScriptTool = defineBrowserTool({
+  name: "browser_run_script",
+  label: "Browser Run Script",
+  description:
+    "Execute a temporary JavaScript script with full Node.js + browser-daemon access. Path must be inside tmpdir, cwd, or BH_SCRIPT_DIR. Mandatory timeout. The script is full RCE on the harness's process — only invoke scripts you wrote and reviewed.",
+  promptSnippet: "Run a temporary script with daemon + Node access (security-bounded)",
+  promptGuidelines: [
+    "Write the script with the write tool first; pass its absolute path.",
+    "Path must be inside tmpdir, cwd, or BH_SCRIPT_DIR — otherwise rejected.",
+    "Default timeout is 60s; pass timeoutMs to extend (max 600s).",
+    "Script bindings: params, daemon, require, signal, onUpdate, ctx, console, fetch, JSON, Buffer, setTimeout, clearTimeout.",
+    "Script MUST return { content: [{ type: 'text', text: '...' }], details?: {...} }. Throw on errors.",
+  ],
+  parameters: RunScriptArgs,
+  async handler(args, { client, signal, onUpdate, extensionCtx }): Promise<Result<ToolOk, ToolErr>> {
+    if (!isAbsolute(args.path)) {
+      return err({ kind: "invalid_state", message: "Script path must be absolute" });
+    }
+    if (!isPathAllowed(args.path)) {
+      return err({
+        kind: "invalid_state",
+        message: `Script path outside allowed directories (allowed: ${allowedRoots().join(", ")})`,
+      });
+    }
+    let source: string;
+    try {
+      source = await readFile(args.path, "utf8");
+    } catch (e) {
+      return err({
+        kind: "io_error",
+        message: `Failed to read script: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+    if (source.length === 0) return err({ kind: "invalid_state", message: "Script is empty" });
+    if (source.length > MAX_SOURCE_BYTES) {
+      return err({ kind: "invalid_state", message: `Script exceeds ${MAX_SOURCE_BYTES}B size cap` });
+    }
+
+    let executeFn: (...a: ReadonlyArray<unknown>) => Promise<unknown>;
+    try {
+      executeFn = new AsyncFunction(
+        "params", "daemon", "require", "signal", "onUpdate", "ctx",
+        "console", "fetch", "JSON", "Buffer", "setTimeout", "clearTimeout",
+        `"use strict";\n${source}`,
+      );
+    } catch (e) {
+      return err({
+        kind: "invalid_state",
+        message: `Syntax error: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+
+    const timeoutMs = args.timeoutMs ?? 60_000;
+    const ac = new AbortController();
+    const onAbort = (): void => ac.abort();
+    if (signal !== undefined) signal.addEventListener("abort", onAbort, { once: true });
+    const timeoutTimer = setTimeout(() => ac.abort(), timeoutMs);
+
+    try {
+      const scriptPromise = executeFn(
+        args.params ?? {},
+        client,                     // bound as `daemon` — name preserved for back-compat
+        requireFromHere,
+        ac.signal,
+        (u: unknown) => {
+          if (typeof u !== "object" || u === null) return;
+          const content = (u as Readonly<Record<string, unknown>>)["content"];
+          if (!Array.isArray(content) || content.length === 0) return;
+          const first = content[0];
+          if (typeof first !== "object" || first === null) return;
+          const txt = (first as Readonly<Record<string, unknown>>)["text"];
+          if (typeof txt !== "string") return;
+          try { onUpdate({ text: txt }); } catch { /* swallow */ }
+        },
+        extensionCtx ?? { cwd: process.cwd() },
+        console, fetch, JSON, Buffer, setTimeout, clearTimeout,
+      );
+      const abortPromise = new Promise<never>((_, reject) => {
+        ac.signal.addEventListener("abort", () => reject(new Error("script aborted (timeout or cancellation)")), { once: true });
+      });
+      const result = await Promise.race([scriptPromise, abortPromise]);
+      clearTimeout(timeoutTimer);
+      if (signal !== undefined) signal.removeEventListener("abort", onAbort);
+
+      if (typeof result !== "object" || result === null) {
+        return err({ kind: "invalid_state", message: `Script must return an object; got ${JSON.stringify(result)}` });
+      }
+      const content = (result as Readonly<Record<string, unknown>>)["content"];
+      if (!Array.isArray(content)) {
+        return err({ kind: "invalid_state", message: "Script return value must have a content array" });
+      }
+      if (!content.every(isContentItem)) {
+        return err({ kind: "invalid_state", message: "Script content array must contain { type: 'text', text: string } items" });
+      }
+      const textOut = content.map((c) => c.text).join("\n");
+      const details = (result as Readonly<Record<string, unknown>>)["details"];
+      const isPlainObject = typeof details === "object" && details !== null && !Array.isArray(details);
+      return isPlainObject
+        ? ok({ text: textOut, details: details as Readonly<Record<string, unknown>> })
+        : ok({ text: textOut });
+    } catch (e) {
+      clearTimeout(timeoutTimer);
+      if (signal !== undefined) signal.removeEventListener("abort", onAbort);
+      return err({
+        kind: "internal",
+        message: `Script execution failed: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  },
+});

package/src/domains/keyboard.ts

@@ -0,0 +1,127 @@
+import { Type } from "typebox";
+import { safeJs } from "../util/js-template";
+import { virtualKeyCode } from "../util/keycodes";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+
+const TypeArgs = Type.Object({
+  text: Type.String({ description: "Text to type" }),
+});
+
+export const typeTool = defineBrowserTool({
+  name: "browser_type",
+  label: "Browser Type",
+  description: "Type text into the currently focused element. Use browser_click first to focus an input field.",
+  promptSnippet: "Type text into the focused element",
+  promptGuidelines: [
+    "Use browser_type to enter text. Click on an input field with browser_click first to focus it.",
+    "For special keys (Enter, Tab, Escape, arrows), use browser_press_key instead.",
+  ],
+  parameters: TypeArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await client.session().call("Input.insertText", { text: args.text });
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    return ok({ text: `Typed: "${args.text}"` });
+  },
+});
+
+const PressKeyArgs = Type.Object({
+  key: Type.String({
+    description:
+      'Key to press. Special keys: Enter, Tab, Backspace, Escape, Delete, ArrowLeft/Up/Right/Down, Home, End, PageUp, PageDown. Space as " "',
+  }),
+  modifiers: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      maximum: 15,
+      description: "Modifier bitfield: 1=Alt, 2=Ctrl, 4=Meta(Cmd), 8=Shift. Combine with OR.",
+    }),
+  ),
+});
+
+export const pressKeyTool = defineBrowserTool({
+  name: "browser_press_key",
+  label: "Browser Press Key",
+  description:
+    "Press a keyboard key. Supports special keys (Enter, Tab, Backspace, Escape, Delete, arrows, Home, End, PageUp, PageDown, Space as ' ') and regular characters. Optional modifier bitfield: 1=Alt, 2=Ctrl, 4=Meta/Cmd, 8=Shift.",
+  promptSnippet: "Press a key (Enter, Tab, Escape, arrows, or any character)",
+  promptGuidelines: [
+    "Use browser_press_key for keyboard shortcuts and navigation keys.",
+    "Special key names: Enter, Tab, Backspace, Escape, Delete, ArrowLeft, ArrowUp, ArrowRight, ArrowDown, Home, End, PageUp, PageDown.",
+    "Use Space as ' ' (a single space character).",
+    "Modifiers: 1=Alt, 2=Ctrl, 4=Meta(Cmd), 8=Shift. Combine with bitwise OR: Ctrl+Shift = 2|8 = 10.",
+  ],
+  parameters: PressKeyArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const k = args.key;
+    const code = virtualKeyCode(k);
+    const modifiers = args.modifiers ?? 0;
+    const isChar = k.length === 1;
+    const downParams: Record<string, unknown> = {
+      type: "keyDown",
+      key: k,
+      code: k,
+      modifiers,
+      ...(code ? { windowsVirtualKeyCode: code, nativeVirtualKeyCode: code } : {}),
+      ...(isChar ? { text: k, unmodifiedText: k } : {}),
+    };
+    const down = await client.session().call("Input.dispatchKeyEvent", downParams);
+    if (!down.success) return err({ kind: "cdp_error", message: down.error.message });
+    const up = await client.session().call("Input.dispatchKeyEvent", { type: "keyUp", key: k, code: k, modifiers });
+    if (!up.success) return err({ kind: "cdp_error", message: up.error.message });
+    return ok({ text: `Pressed: ${k}${modifiers ? ` (modifiers=${modifiers})` : ""}` });
+  },
+});
+
+const DispatchKeyArgs = Type.Object({
+  selector: Type.String({ description: "CSS selector of the target element" }),
+  key: Type.String({ description: "Key value (e.g., 'Enter', 'a')" }),
+  eventType: Type.Optional(
+    Type.Union(
+      [Type.Literal("keydown"), Type.Literal("keyup"), Type.Literal("keypress")],
+      { default: "keydown", description: "Event type to dispatch. Default: keydown" },
+    ),
+  ),
+});
+
+export const dispatchKeyTool = defineBrowserTool({
+  name: "browser_dispatch_key",
+  label: "Browser Dispatch Key",
+  description:
+    "Dispatch a DOM KeyboardEvent on a specific element via JS injection. Use for React/Vue components that listen to synthetic events more reliably than CDP input.",
+  promptSnippet: "Dispatch a DOM KeyboardEvent on a specific element",
+  promptGuidelines: [
+    "Dispatches a synthetic DOM KeyboardEvent — for React/Vue synthetic event listeners. Does NOT insert text into inputs (use browser_type or browser_press_key for actual typing).",
+    "Try browser_press_key first; only use browser_dispatch_key when the page ignores raw CDP key events.",
+    "The selector must match exactly one or more elements; zero matches is reported as an error.",
+    "eventType defaults to 'keydown'.",
+  ],
+  parameters: DispatchKeyArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const eventType = args.eventType ?? "keydown";
+    const expr = safeJs`
+      (() => {
+        const els = document.querySelectorAll(${args.selector});
+        if (els.length === 0) return 0;
+        for (const el of els) {
+          el.dispatchEvent(new KeyboardEvent(${eventType}, { key: ${args.key}, bubbles: true, cancelable: true }));
+        }
+        return els.length;
+      })()
+    `;
+    const r = await client.evaluateJs(expr);
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const matched = Number(r.data ?? 0);
+    if (matched === 0) {
+      return err({
+        kind: "invalid_state",
+        message: `Selector matched 0 elements: ${args.selector}`,
+        details: { matched: 0, selector: args.selector },
+      });
+    }
+    return ok({
+      text: `Dispatched ${eventType}('${args.key}') on ${matched} element(s)`,
+      details: { matched, selector: args.selector },
+    });
+  },
+});