pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/domains/js.ts

@@ -0,0 +1,241 @@
+import { readFile } from "node:fs/promises";
+import { resolve, isAbsolute } from "node:path";
+import { isPathWithin } from "../util/paths";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+import { Type } from "typebox";
+import { Markdown, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { type Result, err, ok } from "../util/result";
+import { formatBytes } from "../util/truncate";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { evalJs } from "./cdp-call";
+import { applyTruncation } from "../util/truncate";
+import { asNumber, asRecord, asString, isRecord } from "../util/guards";
+
+const COMPACT_PREVIEW_BYTES = 120;
+
+// The AsyncFunction constructor is the documented way to compile user source; a plain `unknown` cast would lose the constructor signature, so this typed cast stays.
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as
+  new (...args: ReadonlyArray<string>) => (...args: ReadonlyArray<unknown>) => Promise<unknown>;
+
+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:
+    "Surgical reads from the DOM. The cheapest, most precise way to extract a specific element's text, attribute, value, or geometry. Prefer over browser_screenshot for ANY data extraction or coordinate lookup. `return X` is auto-wrapped in an IIFE. Always use safeJs / JSON.stringify when interpolating untrusted strings.",
+  promptSnippet: "Execute JS in the page — surgical DOM reads (preferred over screenshot)",
+  promptGuidelines: [
+    "DEFAULT for extracting a specific value: `document.querySelector('.price').innerText`, `input.value`, `el.getAttribute('aria-label')`, etc.",
+    "For click coordinates not already in browser_snapshot: `JSON.stringify(document.querySelector('SELECTOR').getBoundingClientRect())` — beats a screenshot every time.",
+    "For 'is this element visible / enabled / checked / focused', a one-liner here beats a screenshot every time.",
+    "DO NOT call browser_screenshot to read a value or check element state. Use this tool.",
+    "`return foo` is auto-wrapped in an IIFE — both `foo` and `(() => foo)()` work.",
+    "For iframes, first run `Object.values(document.querySelectorAll('iframe'))` to find the iframe, then pass its targetId.",
+    "Result must be JSON-serializable (Runtime.evaluate returnByValue=true).",
+  ],
+  parameters: ExecuteJsArgs,
+  concurrency: "parallel",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await evalJs(client, args.expression, args.targetId);
+    if (!r.success) return r;
+    const valueStr = r.data === undefined ? "undefined" : JSON.stringify(r.data);
+    const truncated = await applyTruncation(valueStr, "js");
+    let pretty: string | undefined;
+    try {
+      const parsed: unknown = JSON.parse(valueStr);
+      pretty = JSON.stringify(parsed, null, 2);
+    } catch {
+      pretty = undefined;
+    }
+    return ok({
+      text: truncated.text,
+      details: {
+        valueLength: valueStr.length,
+        full: valueStr.length > 200_000 ? valueStr.slice(0, 200_000) : valueStr,
+        ...(pretty !== undefined ? { pretty: pretty.length > 200_000 ? pretty.slice(0, 200_000) : pretty } : {}),
+        ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+      },
+    });
+  },
+
+  renderResult(result, expanded, theme) {
+    const raw = asRecord(result.details);
+    if (raw === undefined) return new Text(theme.fg("error", "execute_js: no details"), 0, 0);
+    const details = {
+      valueLength: asNumber(raw["valueLength"]),
+      full: asString(raw["full"]),
+      pretty: asString(raw["pretty"]),
+      fullOutputPath: asString(raw["fullOutputPath"]),
+    };
+
+    const len = details.valueLength ?? 0;
+    const full = details.full ?? "";
+    const isJson = details.pretty !== undefined;
+
+    if (!expanded) {
+      const preview = full.length > COMPACT_PREVIEW_BYTES ? full.slice(0, COMPACT_PREVIEW_BYTES) + "…" : full;
+      const md = [
+        `**${formatBytes(len)}** ${isJson ? "JSON" : "value"}`,
+        "```",
+        preview,
+        "```",
+        keyHint("app.tools.expand", "to expand"),
+      ].join("\n");
+      return new Markdown(md, 0, 0, getMarkdownTheme());
+    }
+
+    const body = details.pretty ?? full;
+    const fence = isJson ? "```json" : "```";
+    const tail = details.fullOutputPath
+      ? `\n\nFull value at \`${details.fullOutputPath}\` · ${keyHint("app.tools.expand", "to collapse")}`
+      : `\n\n${keyHint("app.tools.expand", "to collapse")}`;
+    const md = [`**${formatBytes(len)}** ${isJson ? "JSON" : "value"}`, fence, body, "```", tail].join("\n");
+    return new Markdown(md, 0, 0, getMarkdownTheme());
+  },
+});
+
+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 => allowedRoots().some((root) => isPathWithin(root, p));
+
+const MAX_SOURCE_BYTES = 1_000_000;
+
+type ContentItem = { readonly type: "text"; readonly text: string };
+
+const isContentItem = (v: unknown): v is ContentItem =>
+  isRecord(v) && v["type"] === "text" && typeof v["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,
+  concurrency: "parallel",
+  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,
+        requireFromHere,
+        ac.signal,
+        (u: unknown) => {
+          if (!isRecord(u)) return;
+          const content = u["content"];
+          if (!Array.isArray(content) || content.length === 0) return;
+          const first: unknown = content[0];
+          if (!isRecord(first)) return;
+          const txt = first["text"];
+          if (typeof txt !== "string") return;
+          try { onUpdate({ text: txt }); } catch {}
+        },
+        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 (!isRecord(result)) {
+        return err({ kind: "invalid_state", message: `Script must return an object; got ${JSON.stringify(result)}` });
+      }
+      const content = result["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["details"];
+      return isRecord(details) ? ok({ text: textOut, details }) : 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/extensions/browser-harness/domains/keyboard.ts

@@ -0,0 +1,197 @@
+import { Type } from "typebox";
+import { safeJs } from "../util/js-template";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall, evalJs } from "./cdp-call";
+import { resolveRefToObjectId } from "./ref-resolve";
+
+const VIRTUAL_KEY_CODES: Readonly<Record<string, number>> = {
+  Enter: 13, Tab: 9, Backspace: 8, Escape: 27, Delete: 46, " ": 32,
+  ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40,
+  Home: 36, End: 35, PageUp: 33, PageDown: 34,
+};
+
+const virtualKeyCode = (key: string): number =>
+  VIRTUAL_KEY_CODES[key] ?? (key.length === 1 ? key.charCodeAt(0) : 0);
+
+const TypeArgs = Type.Object({
+  text: Type.String({ description: "Text to type" }),
+});
+
+type FocusProbe = { readonly ok: boolean; readonly tag: string | null };
+
+const isFocusProbe = (v: unknown): v is FocusProbe =>
+  typeof v === "object" && v !== null
+  && "ok" in v && typeof v.ok === "boolean"
+  && "tag" in v && (typeof v.tag === "string" || v.tag === null);
+
+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,
+  concurrency: "serialized",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const focused = await evalJs(client, safeJs`
+      (() => {
+        const el = document.activeElement;
+        const ok = !!el && el !== document.body &&
+          (el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.isContentEditable);
+        return { ok, tag: el ? el.tagName : null };
+      })()
+    `);
+    if (focused.success) {
+      const f: FocusProbe = isFocusProbe(focused.data) ? focused.data : { ok: false, tag: null };
+      if (!f.ok) {
+        return err({
+          kind: "invalid_state",
+          message:
+            "No editable element is focused — typed text would be lost. Click the field with browser_click first, or use browser_fill with a selector.",
+          details: { activeElement: f.tag },
+        });
+      }
+    }
+    const r = await cdpCall(client, "Input.insertText", { text: args.text });
+    if (!r.success) return r;
+    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,
+  concurrency: "serialized",
+  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 cdpCall(client, "Input.dispatchKeyEvent", downParams);
+    if (!down.success) return down;
+    // A printable character needs a `char` event for the page to receive keypress/textInput and actually insert it; Shift (8) still counts as printable.
+    const hasCommandModifier = (modifiers & (1 | 2 | 4)) !== 0;
+    if (isChar && !hasCommandModifier) {
+      const charEv = await cdpCall(client, "Input.dispatchKeyEvent", { type: "char", text: k, key: k });
+      if (!charEv.success) return charEv;
+    }
+    const up = await cdpCall(client, "Input.dispatchKeyEvent", { type: "keyUp", key: k, code: k, modifiers });
+    if (!up.success) return up;
+    return ok({ text: `Pressed: ${k}${modifiers ? ` (modifiers=${modifiers})` : ""}` });
+  },
+});
+
+const DispatchKeyArgs = Type.Object({
+  ref: Type.Optional(
+    Type.String({ description: "Stable element ref from browser_snapshot (e.g. 'e7'). PREFERRED over selector." }),
+  ),
+  selector: Type.Optional(Type.String({ description: "CSS selector of the target element (fallback when no ref)" })),
+  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. PREFERRED: pass `ref` from browser_snapshot; fallback: a CSS `selector`. Use for React/Vue components that listen to synthetic events more reliably than CDP input.",
+  promptSnippet: "Dispatch a DOM KeyboardEvent on an element by ref (preferred) or selector",
+  promptGuidelines: [
+    "PREFER `ref` from browser_snapshot over a CSS selector — survives re-renders.",
+    "Dispatches a synthetic DOM KeyboardEvent — for React/Vue synthetic event listeners. Does NOT insert text (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 event carries keyCode/which (e.g. 13 for Enter) for legacy handlers, but is untrusted (isTrusted === false) — a few libraries may still ignore it.",
+    "eventType defaults to 'keydown'.",
+  ],
+  parameters: DispatchKeyArgs,
+  concurrency: "serialized",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const eventType = args.eventType ?? "keydown";
+    const target = args.ref ?? args.selector ?? "";
+    // Legacy handlers branch on e.keyCode/e.which rather than e.key, so populate both.
+    const code = virtualKeyCode(args.key);
+    if (args.ref !== undefined) {
+      const objectId = await resolveRefToObjectId(client, args.ref);
+      if (!objectId.success) return objectId;
+      const r = await cdpCall(client, "Runtime.callFunctionOn", {
+        objectId: objectId.data,
+        functionDeclaration: `function (type, key, keyCode) { this.dispatchEvent(new KeyboardEvent(type, { key, keyCode, which: keyCode, bubbles: true, cancelable: true })); return 1; }`,
+        arguments: [{ value: eventType }, { value: args.key }, { value: code }],
+        returnByValue: true,
+      });
+      if (!r.success) return r;
+      return ok({
+        text: `Dispatched ${eventType}('${args.key}') on ${target}`,
+        details: { matched: 1, ref: args.ref },
+      });
+    }
+    if (args.selector === undefined) {
+      return err({ kind: "invalid_state", message: "Provide either `ref` or `selector`." });
+    }
+    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}, keyCode: ${code}, which: ${code}, bubbles: true, cancelable: true }));
+        }
+        return els.length;
+      })()
+    `;
+    const r = await evalJs(client, expr);
+    if (!r.success) return r;
+    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 },
+    });
+  },
+});

package/extensions/browser-harness/domains/navigate.ts

@@ -0,0 +1,161 @@
+import { Type } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { applyTruncation } from "../util/truncate";
+import { safeJs } from "../util/js-template";
+import { ensureHarnessWindow, openHarnessTab } from "../cdp/target-factory";
+import { cdpCall, cdpCallBrowser, cdpCallOnTarget, evalJs } from "./cdp-call";
+
+const NavigateArgs = Type.Object({
+  url: Type.String({ description: "Full URL to navigate to (e.g. https://github.com)" }),
+});
+
+type NavOutcome =
+  | { readonly kind: "in_place"; readonly targetId: string }
+  | { readonly kind: "new_tab_created"; readonly targetId: string; readonly reason: "no_tabs" };
+
+export const navigateTool = defineBrowserTool({
+  name: "browser_navigate",
+  label: "Browser Navigate",
+  description:
+    "Navigate to a URL. Creates a new tab on first call (when no real tabs exist). Otherwise navigates the current tab in place.",
+  promptSnippet: "Navigate to a URL",
+  promptGuidelines: [
+    "Use browser_navigate to go to URLs.",
+    "Use browser_wait_for_load after browser_navigate to wait for the page to finish loading.",
+    "For extracting data from a page you already navigated to, use browser_execute_js or browser_http_get (faster for APIs).",
+    "Note: Google and some sites with strict anti-bot detection may reject CDP navigation. Use browser_http_get for search results.",
+  ],
+  parameters: NavigateArgs,
+  concurrency: "serialized",
+  renderCall: (a) => new Text(`🌐 Navigate to ${a.url}`, 0, 0),
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const tabs = await client.listTabs(false);
+    if (!tabs.success) return err({ kind: "cdp_error", message: tabs.error.message });
+    let outcome: NavOutcome;
+    if (tabs.data.length === 0) {
+      const created = await client.newTab(args.url);
+      if (!created.success) return err({ kind: "cdp_error", message: created.error.message });
+      outcome = { kind: "new_tab_created", targetId: created.data, reason: "no_tabs" };
+    } else {
+      const nav = await cdpCall(client, "Page.navigate", { url: args.url });
+      if (!nav.success) return nav;
+      const cur = client.current();
+      if (!cur) return err({ kind: "internal", message: "navigate succeeded but no current target tracked" });
+      outcome = { kind: "in_place", targetId: cur.targetId };
+    }
+    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: `Navigated to ${args.url}\nTarget: ${outcome.targetId}\n⚠️  Dialog open: ${info.data.dialog.type} — "${info.data.dialog.message}"\nUse browser_handle_dialog.`,
+        details: { outcome, dialog: info.data.dialog },
+      });
+    }
+    const prefix = outcome.kind === "new_tab_created" ? "New tab: " : "";
+    return ok({
+      text: `${prefix}Navigated to: ${info.data.url}\nTitle: ${info.data.title}\nViewport: ${info.data.width}x${info.data.height}\nTarget: ${outcome.targetId}`,
+      details: { outcome, page: info.data },
+    });
+  },
+});
+
+const OpenUrlsArgs = Type.Object({
+  urls: Type.Array(Type.String(), { description: "Array of URLs to open in new tabs" }),
+});
+
+type TabResult = {
+  readonly url: string;
+  readonly targetId: string;
+  readonly ok: boolean;
+  readonly error?: string;
+};
+
+export const openUrlsTool = defineBrowserTool({
+  name: "browser_open_urls",
+  label: "Browser Open URLs",
+  description: "Open multiple URLs in parallel new tabs. Returns per-URL outcomes.",
+  promptSnippet: "Open multiple URLs in new tabs (parallel)",
+  promptGuidelines: [
+    "Use after browser_web_search to open citations in parallel.",
+    "After opening, use browser_list_tabs / browser_switch_tab to navigate, then browser_snapshot to inspect each tab.",
+    "Use browser_wait_for_load on a tab before extracting data from SPAs.",
+  ],
+  parameters: OpenUrlsArgs,
+  concurrency: "serialized",
+  renderCall: (a) => new Text(`🌐 Opening ${a.urls.length} URL${a.urls.length !== 1 ? "s" : ""}…`, 0, 0),
+  async handler(args, { client, onUpdate }): Promise<Result<ToolOk, ToolErr>> {
+    const total = args.urls.length;
+    // All tabs must land in ONE window: a parallel newWindow:true per url would scatter them across N windows, so the first url creates the window and the rest open as its children.
+    const url0 = args.urls[0];
+    if (url0 === undefined) return err({ kind: "invalid_state", message: "no URLs provided" });
+    const window = await ensureHarnessWindow(client);
+    if (!window.success) return err({ kind: "cdp_error", message: window.error.message });
+    const seededWindow = window.data.targetId;
+    const seedResult: TabResult | undefined = window.data.freshlyCreated
+      ? { url: url0, targetId: seededWindow, ok: true }
+      : undefined;
+    const created = await Promise.all(args.urls.map(async (url, i): Promise<TabResult> => {
+      if (i === 0 && seedResult) return seedResult;
+      const r = await openHarnessTab(client, seededWindow);
+      if (!r.success) return { url, targetId: "", ok: false, error: r.error.message };
+      return { url, targetId: r.data, ok: true };
+    }));
+    let completed = 0;
+    const settled = await Promise.all(
+      created.filter((t) => t.ok).map(async (tab): Promise<TabResult> => {
+        try {
+          const attached = await client.session().attach(tab.targetId);
+          if (!attached.success) return { ...tab, ok: false, error: attached.error.message };
+          const sid = attached.data;
+          const enabled = await cdpCallOnTarget(client, "Page.enable", {}, sid);
+          if (!enabled.success) return { ...tab, ok: false, error: enabled.error.message };
+          const nav = await cdpCallOnTarget(client, "Page.navigate", { url: tab.url }, sid);
+          if (!nav.success) return { ...tab, ok: false, error: nav.error.message };
+          evalJs(
+            client,
+            safeJs`if(!document.title.startsWith('🟢'))document.title='🟢 '+document.title`,
+            sid
+          ).catch(() => {});
+          return tab;
+        } finally {
+          completed++;
+          // onUpdate must never escape: a renderer crash would otherwise tear down the tool call.
+          try {
+            onUpdate({ text: `Opening URLs… ${completed}/${created.filter((t) => t.ok).length} navigated` });
+          } catch {}
+        }
+      }),
+    );
+    const failures = created.filter((t) => !t.ok);
+    const all: ReadonlyArray<TabResult> = [...settled, ...failures];
+    const okTabs = all.filter((r) => r.ok);
+    const failTabs = all.filter((r) => !r.ok);
+    if (okTabs.length > 0) {
+      const last = okTabs[okTabs.length - 1];
+      if (last) {
+        await cdpCallBrowser(client, "Target.activateTarget", { targetId: last.targetId });
+      }
+    }
+    const lines: string[] = [];
+    if (okTabs.length) {
+      lines.push(`✅ ${okTabs.length}/${total} tabs opened:`, ...okTabs.map((t, i) => `  [${i}] ${t.url} → ${t.targetId}`));
+    }
+    if (failTabs.length) {
+      lines.push(`❌ ${failTabs.length}/${total} failed:`, ...failTabs.map((t) => `  ${t.url}: ${t.error ?? "unknown"}`));
+    }
+    const truncated = await applyTruncation(lines.join("\n"), "urls");
+    if (okTabs.length === 0) {
+      return err({
+        kind: "cdp_error",
+        message: `All ${total} URLs failed`,
+        ...(truncated.fullOutputPath ? { details: { tabs: all, fullOutputPath: truncated.fullOutputPath } } : { details: { tabs: all } }),
+      });
+    }
+    return ok({
+      text: truncated.text,
+      ...(truncated.fullOutputPath ? { details: { tabs: all, fullOutputPath: truncated.fullOutputPath } } : { details: { tabs: all } }),
+    });
+  },
+});