pi-browser-harness 0.2.0 → 0.3.1

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

package/src/domains/navigate.ts

@@ -0,0 +1,146 @@
+import { Type } from "typebox";
+import { Text } from "@mariozechner/pi-tui";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { applyTruncation } from "../util/truncate";
+
+const NavigateArgs = Type.Object({
+  url: Type.String({ description: "Full URL to navigate to (e.g. https://github.com)" }),
+});
+
+export 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,
+  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 client.session().call("Page.navigate", { url: args.url });
+      if (!nav.success) return err({ kind: "cdp_error", message: nav.error.message });
+      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 web_search to open citations in parallel.",
+    "After opening, use browser_list_tabs / browser_switch_tab / browser_screenshot to interact.",
+    "Use browser_wait_for_load on a tab before extracting data from SPAs.",
+  ],
+  parameters: OpenUrlsArgs,
+  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;
+    // Phase 1: create tabs in parallel.
+    const created = await Promise.all(args.urls.map(async (url): Promise<TabResult> => {
+      const r = await client.session().callBrowser("Target.createTarget", { url: "about:blank" });
+      if (!r.success) return { url, targetId: "", ok: false, error: r.error.message };
+      const c = r.data as { targetId: string }; // CDP boundary cast: Target.createTarget returns { targetId: string }
+      return { url, targetId: c.targetId, ok: true };
+    }));
+    // Phase 2: attach + navigate each created tab in parallel.
+    let completed = 0;
+    const settled = await Promise.all(
+      created.filter((t) => t.ok).map(async (tab): Promise<TabResult> => {
+        try {
+          const attached = await client.session().callBrowser("Target.attachToTarget", { targetId: tab.targetId, flatten: true });
+          if (!attached.success) return { ...tab, ok: false, error: attached.error.message };
+          const sid = (attached.data as { sessionId: string }).sessionId; // CDP boundary cast: Target.attachToTarget returns { sessionId: string }
+          const enabled = await client.session().callOnTarget("Page.enable", {}, sid);
+          if (!enabled.success) return { ...tab, ok: false, error: enabled.error.message };
+          const nav = await client.session().callOnTarget("Page.navigate", { url: tab.url }, sid);
+          if (!nav.success) return { ...tab, ok: false, error: nav.error.message };
+          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 { /* swallow */ }
+        }
+      }),
+    );
+    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);
+    // Phase 3: activate the last successfully-opened tab so the user sees something.
+    if (okTabs.length > 0) {
+      const last = okTabs[okTabs.length - 1];
+      if (last) {
+        await client.session().callBrowser("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 } }),
+    });
+  },
+});

package/src/domains/network.ts

@@ -0,0 +1,80 @@
+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";
+
+const HttpGetArgs = Type.Object({
+  url: Type.String({ description: "URL to GET" }),
+  headers: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Optional HTTP headers" })),
+  timeout: Type.Optional(
+    Type.Number({ default: 20, minimum: 1, maximum: 120, description: "Total seconds (covers headers AND body)" }),
+  ),
+});
+
+export const httpGetTool = defineBrowserTool({
+  name: "browser_http_get",
+  label: "Browser HTTP GET",
+  description:
+    "Fetch a URL outside the browser (faster than browser_navigate for APIs and static pages). Timeout covers headers AND body read.",
+  promptSnippet: "HTTP GET (outside browser; for APIs/static pages)",
+  promptGuidelines: [
+    "Faster than navigate+execute_js for JSON/HTML APIs.",
+    "No JS rendering — for SPAs use browser_navigate.",
+  ],
+  parameters: HttpGetArgs,
+  ensureAlive: false,
+  async handler(args): Promise<Result<ToolOk, ToolErr>> {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), (args.timeout ?? 20) * 1000);
+    try {
+      const fetchInit: RequestInit = { signal: ac.signal };
+      if (args.headers !== undefined) fetchInit.headers = args.headers;
+      const res = await fetch(args.url, fetchInit);
+      const body = await res.text();
+      clearTimeout(timer);
+      const ct = res.headers.get("content-type") ?? "";
+      const truncated = await applyTruncation(body, "http");
+      return ok({
+        text: `HTTP ${res.status} ${ct}\n${truncated.text}`,
+        details: truncated.fullOutputPath !== undefined
+          ? { status: res.status, contentType: ct, length: body.length, fullOutputPath: truncated.fullOutputPath, wasTruncated: truncated.wasTruncated }
+          : { status: res.status, contentType: ct, length: body.length, wasTruncated: truncated.wasTruncated },
+      });
+    } catch (e) {
+      clearTimeout(timer);
+      const msg = e instanceof Error ? e.message : String(e);
+      const kind: ToolErr["kind"] = msg.toLowerCase().includes("abort") ? "timeout" : "io_error";
+      return err({ kind, message: msg });
+    }
+  },
+});
+
+const NetLogArgs = Type.Object({
+  eventTypes: Type.Optional(
+    Type.Array(Type.String(), { description: "CDP event names to filter (e.g., ['Network.requestWillBeSent'])" }),
+  ),
+  limit: Type.Optional(Type.Integer({ default: 50, minimum: 1, maximum: 500 })),
+});
+
+export const getNetworkLogTool = defineBrowserTool({
+  name: "browser_get_network_log",
+  label: "Browser Get Network Log",
+  description:
+    "Read buffered Network.* CDP events. NOTE: in v0.3 the event stream is consumed internally by the session manager; this tool is a placeholder. Use browser_execute_js with PerformanceObserver as a workaround.",
+  promptSnippet: "Get buffered network events (DEPRECATED in v0.3 — use browser_execute_js with PerformanceObserver instead)",
+  promptGuidelines: [
+    "v0.3 routes CDP events through an internal AsyncIterable; a synchronous drain API isn't exposed yet.",
+    "For now, use browser_execute_js with PerformanceObserver, performance.getEntries(), or fetch interceptors.",
+  ],
+  parameters: NetLogArgs,
+  async handler(args): Promise<Result<ToolOk, ToolErr>> {
+    return ok({
+      text: "browser_get_network_log: in v0.3 the CDP event stream is consumed by the session; use browser_execute_js with PerformanceObserver or performance.getEntries() to inspect network activity.",
+      details: {
+        deprecated: true,
+        eventTypes: args.eventTypes ?? null,
+        limit: args.limit ?? null,
+      },
+    });
+  },
+});