pi-browser-harness 0.10.2 → 0.11.0

package/src/domains/js.ts

@@ -6,28 +6,18 @@ 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({
@@ -51,16 +41,15 @@ export const executeJsTool = defineBrowserTool({
     "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 +58,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 +66,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 ?? "";
@@ -140,9 +131,7 @@ 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",
@@ -158,6 +147,7 @@ export const runScriptTool = defineBrowserTool({
     "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 +195,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 +218,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 +229,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,14 +1,30 @@
 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",
@@ -19,12 +35,9 @@ export const typeTool = defineBrowserTool({
     "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 +46,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 +56,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}"` });
   },
 });
@@ -76,6 +89,7 @@ export const pressKeyTool = defineBrowserTool({
     "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);
@@ -89,18 +103,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})` : ""}` });
   },
 });
@@ -133,25 +145,22 @@ export const dispatchKeyTool = defineBrowserTool({
     "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 +179,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" };
 
@@ -27,6 +28,7 @@ export const navigateTool = defineBrowserTool({
     "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 +39,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 };
@@ -81,56 +83,48 @@ export const openUrlsTool = defineBrowserTool({
     "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 +132,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[] = [];

package/src/domains/network.ts

@@ -2,8 +2,11 @@ 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 { cdpCall } from "./cdp-call";
 import { applyTruncation } from "../util/truncate";
+import { asArrayOf, asBoolean, asNumber, asRecord, asString } from "../util/guards";
 import type { NetworkRecord } from "../cdp/network-buffer";
 
 const HttpGetArgs = Type.Object({
@@ -25,6 +28,7 @@ export const httpGetTool = defineBrowserTool({
     "No JS rendering — for SPAs use browser_navigate.",
   ],
   parameters: HttpGetArgs,
+  concurrency: "parallel",
   ensureAlive: false,
   async handler(args): Promise<Result<ToolOk, ToolErr>> {
     const ac = new AbortController();
@@ -96,11 +100,6 @@ const renderNetworkMarkdown = (
 
   const failed = records.filter((r) => r.failed || (r.status !== undefined && r.status >= 500)).length;
   const totalBytes = records.reduce((s, r) => s + (r.responseBodySize ?? 0), 0);
-  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`;
-  };
   const showWindow = (() => {
     const finished = records.filter((r) => r.durationMs !== undefined);
     if (finished.length === 0) return "";
@@ -129,7 +128,6 @@ const renderNetworkMarkdown = (
     return `${headerLines.join("\n")}\n\n${rows}${more}`;
   }
 
-  // Expanded: full table + optional body sections.
   const tableHeader = `| # | Method | Status | URL | Type | ms |\n|---|---|---|---|---|---|`;
   const tableRows = records
     .map((r, i) => {
@@ -167,6 +165,57 @@ type NetworkDetails = {
   includeBodies: boolean;
 };
 
+const asNetworkRecord = (v: unknown): NetworkRecord | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const method = asString(o["method"]);
+  const url = asString(o["url"]);
+  const type = asString(o["type"]);
+  if (method === undefined || url === undefined || type === undefined) return undefined;
+  const status = asNumber(o["status"]);
+  const statusText = asString(o["statusText"]);
+  const mimeType = asString(o["mimeType"]);
+  const durationMs = asNumber(o["durationMs"]);
+  const responseBodySize = asNumber(o["responseBodySize"]);
+  const failed = asBoolean(o["failed"]);
+  const errorText = asString(o["errorText"]);
+  const bodyRaw = o["body"];
+  const body = typeof bodyRaw === "string" || bodyRaw === null ? bodyRaw : undefined;
+  return {
+    requestId: asString(o["requestId"]) ?? "",
+    method,
+    url,
+    type,
+    requestStartedMs: asNumber(o["requestStartedMs"]) ?? 0,
+    requestBodySize: asNumber(o["requestBodySize"]) ?? 0,
+    ...(status !== undefined ? { status } : {}),
+    ...(statusText !== undefined ? { statusText } : {}),
+    ...(mimeType !== undefined ? { mimeType } : {}),
+    ...(durationMs !== undefined ? { durationMs } : {}),
+    ...(responseBodySize !== undefined ? { responseBodySize } : {}),
+    ...(failed !== undefined ? { failed } : {}),
+    ...(errorText !== undefined ? { errorText } : {}),
+    ...(body !== undefined ? { body } : {}),
+  };
+};
+
+const asNetworkDetails = (v: unknown): NetworkDetails | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const requests = asArrayOf(o["requests"], asNetworkRecord);
+  if (requests === undefined) return undefined;
+  const fullOutputPath = asString(o["fullOutputPath"]);
+  return {
+    total: asNumber(o["total"]) ?? requests.length,
+    returned: asNumber(o["returned"]) ?? requests.length,
+    bufferOverflowed: asBoolean(o["bufferOverflowed"]) ?? false,
+    truncated: asBoolean(o["truncated"]) ?? false,
+    requests,
+    includeBodies: asBoolean(o["includeBodies"]) ?? false,
+    ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
+  };
+};
+
 export const networkRequestsTool = defineBrowserTool({
   name: "browser_network_requests",
   label: "Browser Network Requests",
@@ -180,6 +229,7 @@ export const networkRequestsTool = defineBrowserTool({
     "If bufferOverflowed:true in the result, older events were dropped (capacity 500 records/tab).",
   ],
   parameters: NetworkRequestsArgs,
+  concurrency: "parallel",
 
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const session = client.session();
@@ -197,12 +247,12 @@ export const networkRequestsTool = defineBrowserTool({
       const timer = setTimeout(() => ac.abort(), BODY_BUDGET_MS);
       const fills = drained.records.map(async (r) => {
         if (ac.signal.aborted) return;
-        const bodyRes = await session.call("Network.getResponseBody", { requestId: r.requestId });
+        const bodyRes = await cdpCall(client, "Network.getResponseBody", { requestId: r.requestId });
         if (!bodyRes.success) {
           r.body = null;
           return;
         }
-        const b = bodyRes.data as { body: string; base64Encoded?: boolean };
+        const b = bodyRes.data;
         let body = b.base64Encoded ? Buffer.from(b.body, "base64").toString("utf8") : b.body;
         if (body.length > PER_BODY_CAP) body = body.slice(0, PER_BODY_CAP) + "…";
         r.body = body;
@@ -215,7 +265,7 @@ export const networkRequestsTool = defineBrowserTool({
       includeBodies: args.includeResponseBodies ?? false,
       total: drained.total,
       bufferOverflowed: drained.bufferOverflowed,
-      expanded: true, // full text always returned to the LLM; renderResult handles compact view for humans
+      expanded: true,
     });
     const trunc = await applyTruncation(text, "network");
 
@@ -233,7 +283,7 @@ export const networkRequestsTool = defineBrowserTool({
   },
 
   renderResult(result, expanded, theme) {
-    const details = result.details as NetworkDetails | undefined;
+    const details = asNetworkDetails(result.details);
     if (!details) return new Text(theme.fg("error", "network: no details"), 0, 0);
 
     const md = renderNetworkMarkdown(details.requests, {

package/src/domains/page.ts

@@ -1,9 +1,26 @@
 import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
-import { sleep } from "../util/time";
+import { evalJs } from "./cdp-call";
 import { safeJs } from "../util/js-template";
 
+const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+
 export const pageInfoTool = defineBrowserTool({
   name: "browser_page_info",
   label: "Browser Page Info",
@@ -17,6 +34,7 @@ export const pageInfoTool = defineBrowserTool({
     "browser_page_info auto-detects alert, confirm, prompt, and beforeunload dialogs.",
   ],
   parameters: Type.Object({}),
+  concurrency: "parallel",
   async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const r = await client.pageInfo();
     if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
@@ -46,6 +64,7 @@ export const waitTool = defineBrowserTool({
   promptSnippet: "Wait N seconds",
   promptGuidelines: ["Use sparingly — prefer browser_wait_for_load when waiting for a page load."],
   parameters: WaitArgs,
+  concurrency: "parallel",
   async handler(args, { signal }): Promise<Result<ToolOk, ToolErr>> {
     try {
       await sleep(Math.round(args.seconds * 1000), signal);
@@ -71,12 +90,13 @@ export const waitForLoadTool = defineBrowserTool({
     "Returns when readyState becomes 'complete' OR the timeout elapses.",
   ],
   parameters: WaitForLoadArgs,
+  concurrency: "serialized",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     const timeoutMs = (args.timeout ?? 15) * 1000;
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
       if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
-      const r = await client.evaluateJs(safeJs`document.readyState`);
+      const r = await evalJs(client, safeJs`document.readyState`);
       if (r.success && r.data === "complete") {
         const ms = Date.now() - start;
         return ok({ text: `Page loaded in ${Math.round(ms / 100) / 10}s`, details: { ms } });
@@ -106,6 +126,7 @@ export const waitForTool = defineBrowserTool({
     "Returns a typed timeout error if the condition isn't met within the timeout.",
   ],
   parameters: WaitForArgs,
+  concurrency: "parallel",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     if (args.selector === undefined && args.text === undefined) {
       return err({ kind: "invalid_state", message: "Provide a selector or text to wait for." });
@@ -119,7 +140,7 @@ export const waitForTool = defineBrowserTool({
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
       if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
-      const r = await client.evaluateJs(expr);
+      const r = await evalJs(client, expr);
       if (r.success && r.data === true) {
         const ms = Date.now() - start;
         const what = args.selector !== undefined ? `${args.selector}${gone ? " gone" : ""}` : `text "${args.text}"`;