pi-browser-harness 0.10.2 → 0.12.0

package/src/domains/isolated-tab.ts

@@ -1,22 +1,11 @@
-/**
- * Isolated-attach tab lifecycle (ADR-0002 v1). Opens a harness-owned tab,
- * attaches to it by its own CDP sessionId, and drives it via callOnTarget /
- * evaluateJs(expr, sid) WITHOUT ever touching the global "current" tab — so a
- * search or page-read never disturbs the tab the user is looking at, even when
- * several subagents run concurrently.
- *
- * Mirrors the create/attach sequence in browser_open_urls
- * (src/domains/navigate.ts:84-139). Every page evaluation is bounded by a
- * timeout, so a JS dialog on the (uninstrumented) isolated tab surfaces as a
- * typed timeout rather than hanging — see the dialog-hang caveat in plan.md.
- */
 import type { BrowserClient } from "../client";
 import { type Result, err, ok } from "../util/result";
 import { safeJs } from "../util/js-template";
 import { ensureHarnessWindow, openHarnessTab } from "../cdp/target-factory";
+import { evaluateJson } from "../cdp/session";
 import type { ToolErr } from "../util/tool";
+import { cdpCallBrowser, cdpCallOnTarget, cdpErrToToolErr, evalJs } from "./cdp-call";
 
-/** A tab attached by its own sessionId, ready to drive via callOnTarget. */
 export type IsolatedTab = {
   readonly targetId: string;
   readonly sessionId: string;
@@ -25,56 +14,46 @@ export type IsolatedTab = {
 const EVAL_TIMEOUT_MS = 15_000;
 const READY_POLL_INTERVAL_MS = 50;
 
-const toToolErr = (message: string, kind: ToolErr["kind"] = "cdp_error"): ToolErr => ({ kind, message });
-
-/**
- * Open a harness-owned tab and attach to it, returning its targetId + private
- * sessionId. Does not navigate. The caller MUST `closeIsolatedTab` when done.
- */
 export const openIsolatedTab = async (client: BrowserClient): Promise<Result<IsolatedTab, ToolErr>> => {
-  // Routed through the target factory so an isolated tab lands in the pinned
-  // profile like every other harness tab — otherwise a search or page read
-  // would run with a different profile's cookies than the visible tabs.
+  // Routed through the target factory so an isolated tab lands in the pinned profile, not another profile's cookies.
   const window = await ensureHarnessWindow(client);
-  if (!window.success) return err(toToolErr(window.error.message));
+  if (!window.success) return err(cdpErrToToolErr(window.error, "Target.createTarget"));
   let targetId: string;
   if (window.data.freshlyCreated) {
     targetId = window.data.targetId;
   } else {
     const opened = await openHarnessTab(client, window.data.targetId);
-    if (!opened.success) return err(toToolErr(opened.error.message));
+    if (!opened.success) return err(cdpErrToToolErr(opened.error, "Target.createTarget"));
     targetId = opened.data;
   }
 
-  const attached = await client.session().callBrowser("Target.attachToTarget", { targetId, flatten: true });
+  const attached = await cdpCallBrowser(client, "Target.attachToTarget", { targetId, flatten: true });
   if (!attached.success) {
     await client.closeTab(targetId);
-    return err(toToolErr(attached.error.message));
+    return attached;
   }
-  const { sessionId } = attached.data as { sessionId: string };
+  const { sessionId } = attached.data;
 
-  const enabled = await client.session().callOnTarget("Page.enable", {}, sessionId);
+  const enabled = await cdpCallOnTarget(client, "Page.enable", {}, sessionId);
   if (!enabled.success) {
     await client.closeTab(targetId);
-    return err(toToolErr(enabled.error.message));
+    return enabled;
   }
   return ok({ targetId, sessionId });
 };
 
-/** Navigate an isolated tab to a URL (does not wait for load). */
 export const navigateIsolatedTab = async (
   client: BrowserClient,
   tab: IsolatedTab,
   url: string,
 ): Promise<Result<void, ToolErr>> => {
-  const nav = await client.session().callOnTarget("Page.navigate", { url }, tab.sessionId, {
+  const nav = await cdpCallOnTarget(client, "Page.navigate", { url }, tab.sessionId, {
     timeoutMs: EVAL_TIMEOUT_MS,
   });
-  if (!nav.success) return err(toToolErr(nav.error.message));
+  if (!nav.success) return nav;
   return ok(undefined);
 };
 
-/** Poll the isolated tab until document.readyState === 'complete' or timeout. */
 export const waitForIsolatedLoad = async (
   client: BrowserClient,
   tab: IsolatedTab,
@@ -83,38 +62,30 @@ export const waitForIsolatedLoad = async (
 ): Promise<Result<void, ToolErr>> => {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    if (signal?.aborted) return err(toToolErr("aborted", "internal"));
-    const r = await client.evaluateJs(safeJs`document.readyState`, tab.sessionId);
+    if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
+    const r = await evalJs(client, safeJs`document.readyState`, tab.sessionId);
     if (r.success && r.data === "complete") return ok(undefined);
     await new Promise((res) => setTimeout(res, READY_POLL_INTERVAL_MS));
   }
-  return err(toToolErr(`page did not finish loading in ${Math.round(timeoutMs / 1000)}s`, "timeout"));
+  return err({ kind: "timeout", message: `page did not finish loading in ${Math.round(timeoutMs / 1000)}s` });
 };
 
-/**
- * Evaluate an expression in the isolated tab and return the raw value. Bounds
- * the eval with a timeout so a blocking dialog cannot hang the tool.
- */
-export const evalInIsolatedTab = async (
+export const isJsonText = (v: unknown): v is string => typeof v === "string";
+
+export const evalInIsolatedTab = async <T>(
   client: BrowserClient,
   tab: IsolatedTab,
   expression: string,
-): Promise<Result<unknown, ToolErr>> => {
-  const r = await client.session().callOnTarget(
-    "Runtime.evaluate",
-    { expression, returnByValue: true, awaitPromise: true },
-    tab.sessionId,
-    { timeoutMs: EVAL_TIMEOUT_MS },
-  );
-  if (!r.success) return err(toToolErr(r.error.message, r.error.kind === "timeout" ? "timeout" : "cdp_error"));
-  const data = r.data as { result?: { value?: unknown }; exceptionDetails?: unknown };
-  if (data.exceptionDetails) {
-    return err(toToolErr(`page evaluation failed: ${JSON.stringify(data.exceptionDetails)}`));
-  }
-  return ok(data.result?.value);
+  check: (v: unknown) => v is T,
+): Promise<Result<T, ToolErr>> => {
+  const r = await evaluateJson(client.session(), expression, check, {
+    sessionId: tab.sessionId,
+    timeoutMs: EVAL_TIMEOUT_MS,
+  });
+  if (!r.success) return err(cdpErrToToolErr(r.error, "Runtime.evaluate"));
+  return ok(r.data);
 };
 
-/** Close an isolated tab and drop its ownership. Best-effort; never throws. */
 export const closeIsolatedTab = async (client: BrowserClient, tab: IsolatedTab): Promise<void> => {
   await client.closeTab(tab.targetId).catch(() => {});
 };

package/src/domains/js.ts

@@ -1,33 +1,24 @@
 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 "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/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;
 
-const formatBytes = (n: number): string => {
-  if (n >= 1_048_576) return `${(n / 1_048_576).toFixed(1)} MB`;
-  if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
-  return `${n} B`;
-};
-
-// 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.
+// 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>;
 
-// 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({
@@ -45,22 +36,19 @@ export const executeJsTool = defineBrowserTool({
     "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 client.evaluateJs(args.expression, args.targetId);
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    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");
-    // If the value is JSON, pretty-print for the expanded TUI view. Falls back
-    // to the raw string if parse fails (e.g. value is "undefined" sentinel).
     let pretty: string | undefined;
     try {
-      const parsed = JSON.parse(valueStr);
+      const parsed: unknown = JSON.parse(valueStr);
       pretty = JSON.stringify(parsed, null, 2);
     } catch {
       pretty = undefined;
@@ -69,8 +57,6 @@ export const executeJsTool = defineBrowserTool({
       text: truncated.text,
       details: {
         valueLength: valueStr.length,
-        // Full value for the expanded renderer. Capped at 200 KB so a giant
-        // dump doesn't bloat the conversation transcript on disk.
         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 } : {}),
@@ -79,10 +65,14 @@ export const executeJsTool = defineBrowserTool({
   },
 
   renderResult(result, expanded, theme) {
-    const details = result.details as
-      | { valueLength?: number; full?: string; pretty?: string; fullOutputPath?: string }
-      | undefined;
-    if (!details) return new Text(theme.fg("error", "execute_js: no details"), 0, 0);
+    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 ?? "";
@@ -130,19 +120,14 @@ const allowedRoots = (): ReadonlyArray<string> => {
   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 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 =>
-  typeof v === "object" && v !== null
-    && (v as Readonly<Record<string, unknown>>)["type"] === "text"
-    && typeof (v as Readonly<Record<string, unknown>>)["text"] === "string";
+  isRecord(v) && v["type"] === "text" && typeof v["text"] === "string";
 
 export const runScriptTool = defineBrowserTool({
   name: "browser_run_script",
@@ -151,13 +136,12 @@ export const runScriptTool = defineBrowserTool({
     "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).",
+    "Write the script with the write tool first; pass its absolute path. Use the OS temp directory rather than hardcoding /tmp.",
     "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" });
@@ -205,18 +189,18 @@ export const runScriptTool = defineBrowserTool({
     try {
       const scriptPromise = executeFn(
         args.params ?? {},
-        client,                     // bound as `daemon` — name preserved for back-compat
+        client,
         requireFromHere,
         ac.signal,
         (u: unknown) => {
-          if (typeof u !== "object" || u === null) return;
-          const content = (u as Readonly<Record<string, unknown>>)["content"];
+          if (!isRecord(u)) return;
+          const content = u["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"];
+          const first: unknown = content[0];
+          if (!isRecord(first)) return;
+          const txt = first["text"];
           if (typeof txt !== "string") return;
-          try { onUpdate({ text: txt }); } catch { /* swallow */ }
+          try { onUpdate({ text: txt }); } catch {}
         },
         extensionCtx ?? { cwd: process.cwd() },
         console, fetch, JSON, Buffer, setTimeout, clearTimeout,
@@ -228,10 +212,10 @@ export const runScriptTool = defineBrowserTool({
       clearTimeout(timeoutTimer);
       if (signal !== undefined) signal.removeEventListener("abort", onAbort);
 
-      if (typeof result !== "object" || result === null) {
+      if (!isRecord(result)) {
         return err({ kind: "invalid_state", message: `Script must return an object; got ${JSON.stringify(result)}` });
       }
-      const content = (result as Readonly<Record<string, unknown>>)["content"];
+      const content = result["content"];
       if (!Array.isArray(content)) {
         return err({ kind: "invalid_state", message: "Script return value must have a content array" });
       }
@@ -239,11 +223,8 @@ export const runScriptTool = defineBrowserTool({
         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 });
+      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);

package/src/domains/keyboard.ts

@@ -1,30 +1,42 @@
 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";
+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>> {
-    // Guard against silent text loss: Input.insertText succeeds regardless of
-    // whether an editable element is focused, so without this check typed text
-    // can vanish into the void with no error. Fail loudly with an actionable
-    // message instead. IIFE starts with "(" so evaluateJs returns it directly.
-    const focused = await client.evaluateJs(safeJs`
+    const focused = await evalJs(client, safeJs`
       (() => {
         const el = document.activeElement;
         const ok = !!el && el !== document.body &&
@@ -33,7 +45,7 @@ export const typeTool = defineBrowserTool({
       })()
     `);
     if (focused.success) {
-      const f = focused.data as { ok: boolean; tag: string | null };
+      const f: FocusProbe = isFocusProbe(focused.data) ? focused.data : { ok: false, tag: null };
       if (!f.ok) {
         return err({
           kind: "invalid_state",
@@ -43,8 +55,8 @@ export const typeTool = defineBrowserTool({
         });
       }
     }
-    const r = await client.session().call("Input.insertText", { text: args.text });
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const r = await cdpCall(client, "Input.insertText", { text: args.text });
+    if (!r.success) return r;
     return ok({ text: `Typed: "${args.text}"` });
   },
 });
@@ -71,11 +83,10 @@ export const pressKeyTool = defineBrowserTool({
   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.",
+    "browser_press_key modifiers 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);
@@ -89,18 +100,16 @@ export const pressKeyTool = defineBrowserTool({
       ...(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 });
-    // For a printable character with no command modifier (Ctrl/Meta/Alt = 1|2|4),
-    // emit a `char` event so the page receives keypress/textInput and the
-    // character is actually inserted. Shift (8) is allowed (capitals/symbols).
+    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 client.session().call("Input.dispatchKeyEvent", { type: "char", text: k, key: k });
-      if (!charEv.success) return err({ kind: "cdp_error", message: charEv.error.message });
+      const charEv = await cdpCall(client, "Input.dispatchKeyEvent", { type: "char", text: k, key: k });
+      if (!charEv.success) return charEv;
     }
-    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 });
+    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})` : ""}` });
   },
 });
@@ -126,32 +135,27 @@ export const dispatchKeyTool = defineBrowserTool({
     "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).",
+    "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 commonly branch on e.keyCode/e.which (e.g. === 13 for
-    // Enter) rather than e.key, so populate both. virtualKeyCode maps named
-    // keys and single chars; 0 for anything unknown.
+    // Legacy handlers branch on e.keyCode/e.which rather than e.key, so populate both.
     const code = virtualKeyCode(args.key);
-    // Ref path: dispatch on the single resolved node. Selector path: dispatch on
-    // all matches (preserves the original multi-match behavior).
     if (args.ref !== undefined) {
       const objectId = await resolveRefToObjectId(client, args.ref);
       if (!objectId.success) return objectId;
-      const r = await client.session().call("Runtime.callFunctionOn", {
+      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 err({ kind: "cdp_error", message: r.error.message });
+      if (!r.success) return r;
       return ok({
         text: `Dispatched ${eventType}('${args.key}') on ${target}`,
         details: { matched: 1, ref: args.ref },
@@ -170,8 +174,8 @@ export const dispatchKeyTool = defineBrowserTool({
         return els.length;
       })()
     `;
-    const r = await client.evaluateJs(expr);
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const r = await evalJs(client, expr);
+    if (!r.success) return r;
     const matched = Number(r.data ?? 0);
     if (matched === 0) {
       return err({

package/src/domains/navigate.ts

@@ -5,12 +5,13 @@ 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)" }),
 });
 
-export type NavOutcome =
+type NavOutcome =
   | { readonly kind: "in_place"; readonly targetId: string }
   | { readonly kind: "new_tab_created"; readonly targetId: string; readonly reason: "no_tabs" };
 
@@ -21,12 +22,11 @@ export const navigateTool = defineBrowserTool({
     "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);
@@ -37,8 +37,8 @@ export const navigateTool = defineBrowserTool({
       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 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 };
@@ -78,59 +78,50 @@ export const openUrlsTool = defineBrowserTool({
   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;
-    // Phase 1: create tabs. All must land in ONE window. If the harness window
-    // already exists, open every url as its child in parallel. If it doesn't
-    // (fresh/closed), create the FIRST url as a new dedicated window (binding
-    // its windowId) and open the rest as children of it — a parallel
-    // newWindow:true per url would otherwise scatter tabs across N windows.
+    // 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;
-    // A freshly created window's seed tab serves as the first URL's tab.
     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> => {
-      // Reuse the seed tab (created above) for the first url instead of duplicating it.
       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 };
     }));
-    // 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 });
+          const attached = await client.session().attach(tab.targetId);
           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);
+          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 client.session().callOnTarget("Page.navigate", { url: tab.url }, sid);
+          const nav = await cdpCallOnTarget(client, "Page.navigate", { url: tab.url }, sid);
           if (!nav.success) return { ...tab, ok: false, error: nav.error.message };
-          // Mark the tab with a green circle so the user can see which
-          // tabs the agent opened. Best-effort; don't fail on CSP blocks.
-          client.evaluateJs(
+          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.
+          // 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 */ }
+          } catch {}
         }
       }),
     );
@@ -138,11 +129,10 @@ export const openUrlsTool = defineBrowserTool({
     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 });
+        await cdpCallBrowser(client, "Target.activateTarget", { targetId: last.targetId });
       }
     }
     const lines: string[] = [];