pi-browser-harness 0.2.0 → 0.3.1

package/src/cdp/types.ts

@@ -0,0 +1,72 @@
+export type CdpEvent = {
+  readonly method: string;
+  readonly params: unknown;
+  readonly sessionId?: string;
+};
+
+export type CdpRawMessage = {
+  readonly id?: number;
+  readonly method?: string;
+  readonly params?: Record<string, unknown>;
+  readonly result?: unknown;
+  readonly error?: { readonly message: string; readonly code?: number };
+  readonly sessionId?: string;
+};
+
+export type DialogInfo = {
+  readonly type: "alert" | "confirm" | "prompt" | "beforeunload";
+  readonly message: string;
+  readonly defaultPrompt?: string;
+};
+
+export type TabInfo = {
+  readonly targetId: string;
+  readonly title: string;
+  readonly url: string;
+};
+
+export type PageInfo = {
+  readonly url: string;
+  readonly title: string;
+  readonly width: number;
+  readonly height: number;
+  readonly scrollX: number;
+  readonly scrollY: number;
+  readonly pageWidth: number;
+  readonly pageHeight: number;
+};
+
+export type DaemonStatus = {
+  readonly alive: boolean;
+  readonly sessionId: string | null;
+  readonly namespace: string;
+  readonly remoteBrowserId?: string;
+};
+
+const INTERNAL_PREFIXES: ReadonlyArray<string> = [
+  "chrome://", "chrome-untrusted://", "devtools://", "chrome-extension://", "about:",
+];
+
+export const isInternalUrl = (url: string): boolean =>
+  INTERNAL_PREFIXES.some((p) => url.startsWith(p));
+
+const isObject = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+export const isCdpRawMessage = (v: unknown): v is CdpRawMessage => {
+  if (!isObject(v)) return false;
+  const id = v["id"];
+  if (id !== undefined && typeof id !== "number") return false;
+  const method = v["method"];
+  if (method !== undefined && typeof method !== "string") return false;
+  const sessionId = v["sessionId"];
+  if (sessionId !== undefined && typeof sessionId !== "string") return false;
+  const errVal = v["error"];
+  if (errVal !== undefined) {
+    if (!isObject(errVal)) return false;
+    if (typeof errVal["message"] !== "string") return false;
+    const code = errVal["code"];
+    if (code !== undefined && typeof code !== "number") return false;
+  }
+  return true;
+};

package/src/client.ts

@@ -0,0 +1,232 @@
+import { type Result, err, ok } from "./util/result";
+import { safeJs } from "./util/js-template";
+import { discoverWsUrl } from "./cdp/discovery";
+import { type CdpError, cdpError } from "./cdp/errors";
+import type { CdpTransport } from "./cdp/transport";
+import { createCdpTransport } from "./cdp/transport";
+import { type CdpSession, createCdpSession } from "./cdp/session";
+import type { DaemonStatus, DialogInfo, PageInfo, TabInfo } from "./cdp/types";
+
+export type BrowserClientOptions = {
+  readonly namespace: string;
+  readonly remote?: { readonly cdpUrl: string; readonly browserId: string };
+};
+
+export type BrowserClient = {
+  readonly namespace: string;
+  ensureAlive(): Promise<Result<void, CdpError>>;
+  status(): DaemonStatus;
+  start(): Promise<Result<void, CdpError>>;
+  stop(): Promise<void>;
+  evaluateJs(expression: string, sessionId?: string): Promise<Result<unknown, CdpError>>;
+  pageInfo(): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>>;
+  takeDialog(): DialogInfo | null;
+  listTabs(includeInternal?: boolean): Promise<Result<ReadonlyArray<TabInfo>, CdpError>>;
+  switchTab(targetId: string): Promise<Result<void, CdpError>>;
+  newTab(url?: string): Promise<Result<string, CdpError>>;
+  current(): { readonly sessionId: string; readonly targetId: string } | null;
+  session(): CdpSession;
+  transport(): CdpTransport;
+};
+
+const HEALTH_TTL_MS = 30_000;
+const PAGE_INFO_TTL_MS = 1_000;
+
+const parsePageInfoPayload = (v: unknown): Result<PageInfo, CdpError> => {
+  if (typeof v !== "object" || v === null) {
+    return err(cdpError("invalid_response", "page info payload is not an object"));
+  }
+  const o = v as Readonly<Record<string, unknown>>;
+  const fields: ReadonlyArray<readonly [string, "string" | "number"]> = [
+    ["url", "string"], ["title", "string"],
+    ["w", "number"], ["h", "number"],
+    ["sx", "number"], ["sy", "number"],
+    ["pw", "number"], ["ph", "number"],
+  ];
+  for (const [k, t] of fields) {
+    if (typeof o[k] !== t) {
+      return err(cdpError("invalid_response", `page info field ${k} has wrong type (expected ${t})`));
+    }
+  }
+  return ok({
+    url: o["url"] as string,
+    title: o["title"] as string,
+    width: o["w"] as number,
+    height: o["h"] as number,
+    scrollX: o["sx"] as number,
+    scrollY: o["sy"] as number,
+    pageWidth: o["pw"] as number,
+    pageHeight: o["ph"] as number,
+  });
+};
+
+export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient => {
+  const transport = createCdpTransport();
+  const session = createCdpSession(transport);
+  let lastHealth = 0;
+  let pageCache: { readonly info: PageInfo; readonly at: number } | null = null;
+  let remote: BrowserClientOptions["remote"] | null = opts.remote ?? null;
+
+  const start = async (): Promise<Result<void, CdpError>> => {
+    if (transport.state() === "open" && session.current()) return ok(undefined);
+    const envUrl = process.env["BU_CDP_WS"];
+    let wsUrl: string;
+    if (remote?.cdpUrl) {
+      wsUrl = remote.cdpUrl;
+    } else if (envUrl) {
+      wsUrl = envUrl;
+    } else {
+      const discovered = await discoverWsUrl();
+      if (!discovered.success) return discovered;
+      wsUrl = discovered.data;
+    }
+    const connected = await transport.connect(wsUrl, { timeoutMs: 10_000 });
+    if (!connected.success) return connected;
+    if (!remote) {
+      remote = { cdpUrl: wsUrl, browserId: wsUrl.split("/").pop() ?? "unknown" };
+    }
+    const attached = await session.attachFirstPage();
+    if (!attached.success) {
+      await transport.close();
+      return attached;
+    }
+    lastHealth = Date.now();
+    pageCache = null;
+    return ok(undefined);
+  };
+
+  const stop = async (): Promise<void> => {
+    await transport.close();
+    pageCache = null;
+    lastHealth = 0;
+  };
+
+  const ensureAlive = async (): Promise<Result<void, CdpError>> => {
+    if (transport.state() !== "open" || !session.current()) {
+      await stop();
+      return start();
+    }
+    if (Date.now() - lastHealth < HEALTH_TTL_MS) return ok(undefined);
+    const probe = await transport.request("Target.getTargets", {}, { sessionId: null, timeoutMs: 2_000 });
+    if (!probe.success) {
+      await stop();
+      return start();
+    }
+    lastHealth = Date.now();
+    // Verify the page session is still responsive (handles the case where the
+    // browser transport is alive but the page target crashed, e.g. localhost died).
+    const jsProbe = await session.call("Runtime.evaluate", {
+      expression: "1", returnByValue: true,
+    }, { timeoutMs: 2_000 });
+    if (!jsProbe.success && jsProbe.error.kind === "session_not_found") {
+      const reattached = await session.attachFirstPage();
+      if (reattached.success) {
+        pageCache = null;
+        return ok(undefined);
+      }
+      await stop();
+      return start();
+    }
+    return ok(undefined);
+  };
+
+  const evaluateJs = async (expression: string, sessionId?: string): Promise<Result<unknown, CdpError>> => {
+    // Heuristic IIFE wrap: legacy convenience that lets agents write
+    // `return foo` instead of `(() => foo)()`. False-positive on substring
+    // `"return "` inside string literals or comments — agents that hit this
+    // can pass an explicit IIFE instead.
+    const wrapped = expression.includes("return ") && !expression.trim().startsWith("(")
+      ? `(function(){${expression}})()`
+      : expression;
+    const r = sessionId
+      ? await session.callOnTarget("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true }, sessionId)
+      : await session.call("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true });
+    if (!r.success) return r;
+    const data = r.data as { result?: { value?: unknown }; exceptionDetails?: unknown };
+    if (data.exceptionDetails) {
+      return err(cdpError("remote_error", `JS evaluation failed: ${JSON.stringify(data.exceptionDetails)}`, "Runtime.evaluate"));
+    }
+    return ok(data.result?.value);
+  };
+
+  const readPageInfo = async (): Promise<Result<PageInfo, CdpError>> => {
+    const dirty = session.drainPageInfoInvalidations();
+    if (pageCache && !dirty && Date.now() - pageCache.at < PAGE_INFO_TTL_MS) return ok(pageCache.info);
+    const expr = safeJs`JSON.stringify({url:location.href,title:document.title,w:innerWidth,h:innerHeight,sx:scrollX,sy:scrollY,pw:document.documentElement.scrollWidth,ph:document.documentElement.scrollHeight})`;
+    const raw = await evaluateJs(expr);
+    if (!raw.success) return raw;
+    if (typeof raw.data !== "string") return err(cdpError("invalid_response", "page info evaluation did not return a string"));
+    let parsedRaw: unknown;
+    try {
+      parsedRaw = JSON.parse(raw.data);
+    } catch (e) {
+      return err(cdpError("invalid_response", `page info JSON.parse failed: ${e instanceof Error ? e.message : String(e)}`));
+    }
+    const info = parsePageInfoPayload(parsedRaw);
+    if (!info.success) return info;
+    pageCache = { info: info.data, at: Date.now() };
+    return ok(info.data);
+  };
+
+  const pageInfo = async (): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>> => {
+    const d = session.takeDialog();
+    if (d) return ok({ dialog: d });
+    return readPageInfo();
+  };
+
+  const listTabs = async (includeInternal = true): Promise<Result<ReadonlyArray<TabInfo>, CdpError>> => {
+    const r = await session.callBrowser("Target.getTargets");
+    if (!r.success) return r;
+    const data = r.data as { targetInfos: ReadonlyArray<{ targetId: string; type: string; title: string; url: string }> };
+    const tabs = data.targetInfos
+      .filter((t) => t.type === "page")
+      .filter((t) => includeInternal || !t.url.startsWith("chrome://"))
+      .map((t): TabInfo => ({ targetId: t.targetId, title: t.title, url: t.url }));
+    return ok(tabs);
+  };
+
+  const switchTab = async (targetId: string): Promise<Result<void, CdpError>> => {
+    const r = await session.switchTo(targetId);
+    if (!r.success) return r;
+    pageCache = null;
+    // Best-effort: mark the tab title with a green circle so the user can
+    // see which tab the agent attached to. CSP or detached frames may
+    // block the eval; we don't surface that as a switchTab failure.
+    await session.call("Runtime.evaluate", {
+      expression: safeJs`if(!document.title.startsWith('🟢'))document.title='🟢 '+document.title`,
+    });
+    return ok(undefined);
+  };
+
+  const newTab = async (url?: string): Promise<Result<string, CdpError>> => {
+    const created = await session.callBrowser("Target.createTarget", { url: "about:blank" });
+    if (!created.success) return created;
+    const c = created.data as { targetId: string };
+    const switched = await switchTab(c.targetId);
+    if (!switched.success) return switched;
+    if (url && url !== "about:blank") {
+      const nav = await session.call("Page.navigate", { url });
+      if (!nav.success) return nav;
+      pageCache = null;
+    }
+    return ok(c.targetId);
+  };
+
+  const status = (): DaemonStatus => ({
+    alive: transport.state() === "open" && session.current() !== null,
+    sessionId: session.current()?.sessionId ?? null,
+    namespace: opts.namespace,
+    ...(remote?.browserId !== undefined ? { remoteBrowserId: remote.browserId } : {}),
+  });
+
+  return {
+    namespace: opts.namespace,
+    ensureAlive, status, start, stop,
+    evaluateJs, pageInfo,
+    takeDialog: () => session.takeDialog(),
+    listTabs, switchTab, newTab,
+    current: () => session.current(),
+    session: () => session,
+    transport: () => transport,
+  };
+};

package/src/domains/click.ts

@@ -0,0 +1,73 @@
+import { Type, type Static } from "typebox";
+import { Text } from "@mariozechner/pi-tui";
+import type { BrowserClient } from "../client";
+import { Coords, MouseButton } from "../schemas/common";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr } from "../util/tool";
+import { captureWithCrosshair } from "./screenshot";
+
+const ClickArgs = Type.Object({
+  ...Coords.properties,
+  button: Type.Optional(MouseButton),
+  count: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 3,
+      default: 1,
+      description: "Number of clicks (1 = single, 2 = double). Default: 1",
+    }),
+  ),
+});
+type ClickArgsT = Static<typeof ClickArgs>;
+
+const dispatchClick = async (
+  client: BrowserClient,
+  args: ClickArgsT,
+): Promise<Result<void, ToolErr>> => {
+  const button = args.button ?? "left";
+  const count = args.count ?? 1;
+  const pressed = await client.session().call("Input.dispatchMouseEvent", {
+    type: "mousePressed", x: args.x, y: args.y, button, clickCount: count,
+  });
+  if (!pressed.success) return err({ kind: "cdp_error", message: pressed.error.message });
+  const released = await client.session().call("Input.dispatchMouseEvent", {
+    type: "mouseReleased", x: args.x, y: args.y, button, clickCount: count,
+  });
+  if (!released.success) return err({ kind: "cdp_error", message: released.error.message });
+  return ok(undefined);
+};
+
+export const clickTool = defineBrowserTool({
+  name: "browser_click",
+  label: "Browser Click",
+  description:
+    "Click at viewport CSS-pixel coordinates. Compositor-level click works through iframes, shadow DOM, and cross-origin content. Use browser_screenshot first to find coordinates.",
+  promptSnippet: "Click at pixel coordinates (x, y) on the page",
+  promptGuidelines: [
+    "Use browser_click for all clicks. Coordinates are viewport CSS pixels (not device pixels).",
+    "Capture a browser_screenshot BEFORE clicking to find the right coordinates.",
+    "Capture another browser_screenshot AFTER clicking to verify the action worked.",
+    "Compositor-level clicks pass through iframes, shadow DOM, and cross-origin content — no selector needed.",
+    "If a click doesn't register, try setting BH_DEBUG_CLICKS=1 to get annotated screenshots showing exact click positions.",
+    "For React/Vue components that don't respond to clicks, try browser_dispatch_key to send DOM-level events.",
+  ],
+  parameters: ClickArgs,
+  renderCall: (a) => new Text(`🖱️ Click at (${a.x}, ${a.y})`, 0, 0),
+  async handler(args, { client }) {
+    const clicked = await dispatchClick(client, args);
+    if (!clicked.success) return clicked;
+    if (process.env["BH_DEBUG_CLICKS"]) {
+      const debug = await captureWithCrosshair(client, { x: args.x, y: args.y });
+      if (debug.success) {
+        return ok({
+          text: `Clicked at (${args.x}, ${args.y})\n[DEBUG] Overlay screenshot: ${debug.data.path}`,
+          details: { debugScreenshotPath: debug.data.path, x: args.x, y: args.y },
+        });
+      }
+    }
+    return ok({
+      text: `Clicked at (${args.x}, ${args.y})`,
+      details: { x: args.x, y: args.y },
+    });
+  },
+});

package/src/domains/dialog.ts

@@ -0,0 +1,31 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+
+const HandleDialogArgs = Type.Object({
+  accept: Type.Boolean({ description: "true = accept, false = dismiss" }),
+  promptText: Type.Optional(Type.String({ description: "Text to type if dialog is a prompt()" })),
+});
+
+export const handleDialogTool = defineBrowserTool({
+  name: "browser_handle_dialog",
+  label: "Browser Handle Dialog",
+  description:
+    "Accept or dismiss the currently open JS dialog (alert/confirm/prompt/beforeunload).",
+  promptSnippet: "Accept or dismiss a JS dialog",
+  promptGuidelines: [
+    "Use after browser_page_info reports a dialog is open. Until handled, no other browser action will work.",
+    "For prompt() dialogs, supply promptText with the value to submit.",
+  ],
+  parameters: HandleDialogArgs,
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const params: Record<string, unknown> = { accept: args.accept };
+    if (args.promptText !== undefined) params["promptText"] = args.promptText;
+    const r = await client.session().call("Page.handleJavaScriptDialog", params);
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    return ok({
+      text: `Dialog ${args.accept ? "accepted" : "dismissed"}`,
+      details: { accept: args.accept },
+    });
+  },
+});

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 } });
+  },
+});