pi-browser-harness 0.10.2 → 0.11.0

package/src/{cdp/daemon-transport.ts → daemon/transport.ts}

@@ -1,32 +1,17 @@
-/**
- * DaemonTransport — CdpTransport backed by a Unix socket to the browser daemon.
- *
- * Satisfies the exact CdpTransport interface so BrowserClient, CdpSession, and
- * all domain tools work without changes. Internally uses newline-delimited JSON
- * over a Unix domain socket instead of a WebSocket to Chrome.
- *
- * References:
- *   - CdpTransport interface: src/cdp/transport.ts
- *   - net.createConnection IPC: https://nodejs.org/docs/latest-v22.x/api/net.html#netcreateconnection
- *   - readline.createInterface: https://nodejs.org/docs/latest-v22.x/api/readline.html#readlinecreateinterfaceoptions
- */
-
 import { createConnection, type Socket } from "node:net";
 import { createInterface } from "node:readline";
 import { type Result, err, ok } from "../util/result";
-import { type CdpError, cdpError } from "../cdp/errors";
-import type { CdpTransport } from "../cdp/transport";
+import { type CdpError, cdpError, classifyRemoteError } from "../cdp/errors";
+import { DEFAULT_TIMEOUT_MS, type CdpTransport } from "../cdp/types";
 import type { CdpEvent } from "../cdp/types";
-import { type Pending, makeEventQueue, makeOnClose, rejectAllPending, sendWithTimeout } from "./event-queue";
+import { type Pending, makeEventQueue, makeOnClose, rejectAllPending, sendWithTimeout } from "./queue";
 import {
   DAEMON_SOCKET_PATH,
   type WireRequest,
   type WireControl,
   deserialize,
   serialize,
-} from "../daemon/protocol";
-
-// ── Implementation ─────────────────────────────────────────────────────────────
+} from "./protocol";
 
 export const createDaemonTransport = (clientId: string): CdpTransport => {
   let socket: Socket | null = null;
@@ -49,10 +34,7 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
     for (const cb of closeListeners) cb();
   };
 
-  // ── Connect ────────────────────────────────────────────────────────────
-
   const connect = (_url: string, opts?: { timeoutMs?: number }): Promise<Result<void, CdpError>> => {
-    // url is ignored — we always connect to the daemon socket
     const timeoutMs = opts?.timeoutMs ?? 10_000;
 
     if (socket && !socket.destroyed && registered) {
@@ -67,21 +49,23 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
         resolve(r);
       };
 
+      let sock: Socket;
       try {
-        socket = createConnection(DAEMON_SOCKET_PATH);
+        sock = createConnection(DAEMON_SOCKET_PATH);
       } catch (e) {
         settle(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e))));
         return;
       }
+      socket = sock;
 
       const connectTimer = setTimeout(() => {
         cleanup("Connection timeout");
         settle(err(cdpError("timeout", `Daemon connection timed out after ${timeoutMs}ms`)));
       }, timeoutMs);
 
-      socket.on("connect", () => {
+      sock.on("connect", () => {
         clearTimeout(connectTimer);
-        rl = createInterface({ input: socket!, crlfDelay: Infinity });
+        rl = createInterface({ input: sock, crlfDelay: Infinity });
 
         rl.on("line", (line: string) => {
           const msg = deserialize(line);
@@ -107,13 +91,7 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
             clearTimeout(p.timer);
 
             if (msg.error) {
-              p.resolve(err(cdpError(
-                msg.error.message.includes("Session with given id not found")
-                  ? "session_not_found"
-                  : "remote_error",
-                msg.error.message,
-                p.method,
-              )));
+              p.resolve(err(cdpError(classifyRemoteError(msg.error.message), msg.error.message, p.method)));
             } else {
               p.resolve(ok(msg.result));
             }
@@ -130,23 +108,19 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
           }
         });
 
-        socket!.on("error", () => {
-          // Errors are surfaced via 'close'
-        });
+        sock.on("error", () => {});
 
-        socket!.on("close", () => {
+        sock.on("close", () => {
           clearTimeout(connectTimer);
           cleanup("Daemon socket closed");
-          // If connect hasn't settled yet, settle with error
           settle(err(cdpError("transport_closed", "Daemon socket closed before registration")));
         });
 
-        // Send registration
         const regMsg: WireControl = { type: "control", action: "register", clientId };
-        socket!.write(serialize(regMsg) + "\n");
+        sock.write(serialize(regMsg) + "\n");
       });
 
-      socket.on("error", (e: NodeJS.ErrnoException) => {
+      sock.on("error", (e: NodeJS.ErrnoException) => {
         clearTimeout(connectTimer);
         const msg = e.code === "ENOENT"
           ? "Daemon not running — socket not found"
@@ -156,8 +130,6 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
     });
   };
 
-  // ── Close ──────────────────────────────────────────────────────────────
-
   const close = async (): Promise<void> => {
     if (registered && socket && !socket.destroyed) {
       const dereg: WireControl = { type: "control", action: "deregister", clientId };
@@ -166,17 +138,16 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
     cleanup("close() called");
   };
 
-  // ── Request ────────────────────────────────────────────────────────────
-
   const request = (
     method: string,
     params: Record<string, unknown>,
     opts?: { sessionId?: string | null; timeoutMs?: number },
   ): Promise<Result<unknown, CdpError>> => {
-    const timeoutMs = opts?.timeoutMs ?? 15_000;
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const sessionId = opts?.sessionId ?? null;
 
-    if (!socket || socket.destroyed || !registered) {
+    const sock = socket;
+    if (sock === null || sock.destroyed || !registered) {
       return Promise.resolve(err(cdpError("transport_closed", "Daemon not connected", method)));
     }
 
@@ -189,15 +160,11 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
       ...(sessionId !== null && sessionId !== undefined ? { sessionId } : {}),
     };
 
-    return sendWithTimeout(pending, id, method, timeoutMs, "Daemon", () => socket!.write(serialize(req) + "\n"));
+    return sendWithTimeout(pending, id, method, timeoutMs, "Daemon", () => sock.write(serialize(req) + "\n"));
   };
 
-  // ── Events ─────────────────────────────────────────────────────────────
-
   const events = (): AsyncIterable<CdpEvent> => queue.iter;
 
-  // ── State ──────────────────────────────────────────────────────────────
-
   const state = (): "open" | "closed" | "connecting" => {
     if (!socket) return "closed";
     if (!registered) return "connecting";

package/src/domains/ax-tree.ts

@@ -0,0 +1,179 @@
+import type { AxNodeResult } from "../cdp/commands";
+import type { BrowserClient } from "../client";
+import type { Box } from "./box";
+import { cdpCall } from "./cdp-call";
+
+export type RawAxNode = AxNodeResult;
+type AxValue = NonNullable<RawAxNode["role"]>;
+
+export type SlimNode = {
+  role: string;
+  name?: string;
+  value?: string;
+  description?: string;
+  state?: string;
+  children: SlimNode[];
+  _backendId?: number;
+  ref?: string;
+  box?: Box;
+};
+
+export const INTERACTIVE_ROLES = new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "menuitem",
+  "tab",
+  "switch",
+  "slider",
+  "searchbox",
+  "spinbutton",
+]);
+
+// The AX `value` is stale for freshly-typed or controlled inputs, so for these roles the live DOM property is read instead.
+export const VALUE_ROLES = new Set([
+  "textbox",
+  "searchbox",
+  "spinbutton",
+  "combobox",
+  "checkbox",
+  "radio",
+  "switch",
+  "slider",
+]);
+
+const stringOf = (v: AxValue | undefined): string | undefined => {
+  const x = v?.value;
+  if (typeof x === "string" && x !== "") return x;
+  if (typeof x === "number") return String(x);
+  return undefined;
+};
+
+const collectState = (props: RawAxNode["properties"]): string | undefined => {
+  if (!props || props.length === 0) return undefined;
+  const flags: string[] = [];
+  for (const p of props) {
+    const name = p.name;
+    if (!name) continue;
+    const raw = p.value?.value;
+    if (raw === true && (name === "focused" || name === "required" || name === "disabled" || name === "checked" || name === "expanded" || name === "selected" || name === "pressed" || name === "modal")) {
+      flags.push(name);
+    }
+    if (typeof raw === "number" && name === "level") flags.push(`level ${raw}`);
+  }
+  return flags.length > 0 ? flags.join(", ") : undefined;
+};
+
+export const buildTree = (
+  rawNodes: ReadonlyArray<RawAxNode>,
+  opts: { interestingOnly: boolean; maxNodes: number },
+): SlimNode[] => {
+  const byId = new Map<string, RawAxNode>();
+  for (const n of rawNodes) byId.set(n.nodeId, n);
+
+  const rootIds: string[] = [];
+  for (const n of rawNodes) {
+    if (!n.parentId || !byId.has(n.parentId)) rootIds.push(n.nodeId);
+  }
+
+  let budget = opts.maxNodes;
+
+  const slim = (node: RawAxNode): SlimNode | undefined => {
+    if (budget <= 0) return undefined;
+    if (opts.interestingOnly && node.ignored) {
+      // Chrome often ignores wrapper divs while their descendants remain meaningful, so recurse through an ignored node's children.
+      const out: SlimNode[] = [];
+      for (const cid of node.childIds ?? []) {
+        const child = byId.get(cid);
+        if (!child) continue;
+        const slimChild = slim(child);
+        if (slimChild) out.push(slimChild);
+      }
+      return out.length > 0 ? { role: "_hoist", children: out } : undefined;
+    }
+    budget--;
+    const role = stringOf(node.role) ?? "unknown";
+    const name = stringOf(node.name);
+    const value = stringOf(node.value);
+    const description = stringOf(node.description);
+    const state = collectState(node.properties);
+    const children: SlimNode[] = [];
+    for (const cid of node.childIds ?? []) {
+      const child = byId.get(cid);
+      if (!child) continue;
+      const slimChild = slim(child);
+      if (!slimChild) continue;
+      if (slimChild.role === "_hoist") children.push(...slimChild.children);
+      else children.push(slimChild);
+    }
+    const out: SlimNode = { role, children };
+    if (name !== undefined) out.name = name;
+    if (value !== undefined) out.value = value;
+    if (description !== undefined) out.description = description;
+    if (state !== undefined) out.state = state;
+    if (node.backendDOMNodeId !== undefined) out._backendId = node.backendDOMNodeId;
+    return out;
+  };
+
+  const result: SlimNode[] = [];
+  for (const rid of rootIds) {
+    const root = byId.get(rid);
+    if (!root) continue;
+    const s = slim(root);
+    if (!s) continue;
+    if (s.role === "_hoist") result.push(...s.children);
+    else result.push(s);
+  }
+  return result;
+};
+
+export const countNodes = (nodes: ReadonlyArray<SlimNode>): number => {
+  let n = 0;
+  for (const node of nodes) n += 1 + countNodes(node.children);
+  return n;
+};
+
+export const stripInternals = (nodes: ReadonlyArray<SlimNode>): SlimNode[] =>
+  nodes.map((n) => {
+    const { _backendId: _bid, ...rest } = n;
+    return { ...rest, children: stripInternals(n.children) };
+  });
+
+export const collectInteractiveTargets = (
+  nodes: ReadonlyArray<SlimNode>,
+): Array<{ node: SlimNode; backendId: number }> => {
+  const out: Array<{ node: SlimNode; backendId: number }> = [];
+  const walk = (ns: ReadonlyArray<SlimNode>): void => {
+    for (const n of ns) {
+      if (n._backendId !== undefined && INTERACTIVE_ROLES.has(n.role)) {
+        out.push({ node: n, backendId: n._backendId });
+      }
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return out;
+};
+
+export const liveValue = async (client: BrowserClient, backendId: number): Promise<string | undefined> => {
+  const resolved = await cdpCall(client, "DOM.resolveNode", { backendNodeId: backendId });
+  if (!resolved.success) return undefined;
+  const objectId = resolved.data.object.objectId;
+  if (!objectId) return undefined;
+  const fn = `function () {
+    if (this.type === "checkbox" || this.type === "radio") return this.checked ? "checked" : "unchecked";
+    if (typeof this.value === "string") return this.value;
+    return null;
+  }`;
+  const r = await cdpCall(client, "Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: fn,
+    returnByValue: true,
+  });
+  if (!r.success) return undefined;
+  const value = r.data.result.value;
+  return typeof value === "string" ? value : undefined;
+};

package/src/domains/box.ts

@@ -0,0 +1,51 @@
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+
+export type Box = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly cx: number;
+  readonly cy: number;
+};
+
+type BoxModel = {
+  readonly content: ReadonlyArray<number>;
+  readonly width: number;
+  readonly height: number;
+};
+
+export const centreOf = (model: BoxModel): Box => {
+  const x = model.content[0] ?? 0;
+  const y = model.content[1] ?? 0;
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    width: Math.round(model.width),
+    height: Math.round(model.height),
+    cx: Math.round(x + model.width / 2),
+    cy: Math.round(y + model.height / 2),
+  };
+};
+
+export const boxOf = async (
+  client: BrowserClient,
+  backendNodeId: number,
+): Promise<Result<Box, ToolErr>> => {
+  const r = await cdpCall(client, "DOM.getBoxModel", { backendNodeId });
+  if (!r.success) return r;
+  const model = r.data.model;
+  if (model.content.length < 8) {
+    return err({ kind: "invalid_state", message: "DOM.getBoxModel returned an incomplete content quad" });
+  }
+  if (model.width <= 0 || model.height <= 0) {
+    return err({
+      kind: "invalid_state",
+      message: "element has a zero-size box and cannot be clicked",
+    });
+  }
+  return ok(centreOf(model));
+};

package/src/domains/cdp-call.ts

@@ -0,0 +1,55 @@
+import type { BrowserClient } from "../client";
+import type { CdpMethod, ParamsOf, ResultOf } from "../cdp/commands";
+import type { CdpError } from "../cdp/errors";
+import { type Result, err } from "../util/result";
+import type { ToolErr } from "../util/tool";
+
+export const cdpErrToToolErr = (e: CdpError, method: string): ToolErr => ({
+  kind: e.kind === "timeout" ? "timeout" : "cdp_error",
+  message: e.message,
+  details: { method },
+});
+
+export const cdpCall = async <M extends CdpMethod>(
+  client: BrowserClient,
+  method: M,
+  params: ParamsOf<M>,
+  opts?: { timeoutMs?: number },
+): Promise<Result<ResultOf<M>, ToolErr>> => {
+  const r = await client.session().call(method, params, opts);
+  if (!r.success) return err(cdpErrToToolErr(r.error, method));
+  return r;
+};
+
+export const cdpCallOnTarget = async <M extends CdpMethod>(
+  client: BrowserClient,
+  method: M,
+  params: ParamsOf<M>,
+  sessionId: string,
+  opts?: { timeoutMs?: number },
+): Promise<Result<ResultOf<M>, ToolErr>> => {
+  const r = await client.session().callOnTarget(method, params, sessionId, opts);
+  if (!r.success) return err(cdpErrToToolErr(r.error, method));
+  return r;
+};
+
+export const cdpCallBrowser = async <M extends CdpMethod>(
+  client: BrowserClient,
+  method: M,
+  params?: ParamsOf<M>,
+  opts?: { timeoutMs?: number },
+): Promise<Result<ResultOf<M>, ToolErr>> => {
+  const r = await client.session().callBrowser(method, params, opts);
+  if (!r.success) return err(cdpErrToToolErr(r.error, method));
+  return r;
+};
+
+export const evalJs = async (
+  client: BrowserClient,
+  expression: string,
+  sessionId?: string,
+): Promise<Result<unknown, ToolErr>> => {
+  const r = await client.evaluateJs(expression, sessionId);
+  if (!r.success) return err(cdpErrToToolErr(r.error, "Runtime.evaluate"));
+  return r;
+};

package/src/domains/click.ts

@@ -2,10 +2,13 @@ import { Type } from "typebox";
 import { Text } from "@mariozechner/pi-tui";
 import type { BrowserClient } from "../client";
 import { Coords, MouseButton } from "../schemas/common";
-import { type Result, err, ok } from "../util/result";
+import { type Result, ok } from "../util/result";
+import { debugClicksEnabled } from "../util/debug";
 import { defineBrowserTool, type ToolErr } from "../util/tool";
-import { captureWithCrosshair } from "./screenshot";
-import { interactiveDiff, resolveRefToBox } from "./ref-resolve";
+import { cdpCall } from "./cdp-call";
+import { captureWithCrosshair } from "./screenshot-capture";
+import { interactiveDiff } from "./ref-resolve";
+import { resolveTarget } from "./target";
 
 const ClickArgs = Type.Object({
   ref: Type.Optional(
@@ -34,21 +37,17 @@ const dispatchClick = async (
   button: "left" | "right" | "middle",
   count: number,
 ): Promise<Result<void, ToolErr>> => {
-  // Move the pointer to the target first. Some focus/hover handlers (and React
-  // synthetic events) only fire when a mousemove precedes the press, so without
-  // it a click can land without focusing the element.
-  const moved = await client.session().call("Input.dispatchMouseEvent", {
-    type: "mouseMoved", x, y,
-  });
-  if (!moved.success) return err({ kind: "cdp_error", message: moved.error.message });
-  const pressed = await client.session().call("Input.dispatchMouseEvent", {
+  // Some focus/hover handlers and React synthetic events only fire when a mousemove precedes the press, so without it a click lands without focusing.
+  const moved = await cdpCall(client, "Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+  if (!moved.success) return moved;
+  const pressed = await cdpCall(client, "Input.dispatchMouseEvent", {
     type: "mousePressed", x, y, button, clickCount: count,
   });
-  if (!pressed.success) return err({ kind: "cdp_error", message: pressed.error.message });
-  const released = await client.session().call("Input.dispatchMouseEvent", {
+  if (!pressed.success) return pressed;
+  const released = await cdpCall(client, "Input.dispatchMouseEvent", {
     type: "mouseReleased", x, y, button, clickCount: count,
   });
-  if (!released.success) return err({ kind: "cdp_error", message: released.error.message });
+  if (!released.success) return released;
   return ok(undefined);
 };
 
@@ -64,36 +63,24 @@ export const clickTool = defineBrowserTool({
     "A 'ref is stale' error means the page changed — re-run browser_snapshot to get fresh refs.",
     "After clicking, read the appended page-changes diff to confirm the action landed before moving on (no separate snapshot needed for a quick check).",
     "Coordinates are viewport CSS pixels (not device pixels). Compositor-level clicks pass through iframes, shadow DOM, and cross-origin content.",
-    "If a click doesn't register, set BH_DEBUG_CLICKS=1 to get annotated screenshots (debug only). For React/Vue components ignoring clicks, try browser_dispatch_key.",
+    "If a click doesn't register, run pi with --browser-debug-clicks (or set BH_DEBUG_CLICKS=1) to get annotated screenshots. For React/Vue components ignoring clicks, try browser_dispatch_key.",
   ],
   parameters: ClickArgs,
+  concurrency: "serialized",
   renderCall: (a) => new Text(`🖱️ Click ${a.ref ? `[${a.ref}]` : `(${a.x}, ${a.y})`}`, 0, 0),
   async handler(args, { client }) {
     const button = args.button ?? "left";
     const count = args.count ?? 1;
 
-    // Resolve the click point: ref re-resolves to the element's CURRENT box
-    // (so re-renders don't matter); otherwise use the literal x/y.
-    let x: number;
-    let y: number;
-    if (args.ref !== undefined) {
-      const box = await resolveRefToBox(client, args.ref);
-      if (!box.success) return box;
-      x = box.data.cx;
-      y = box.data.cy;
-    } else if (args.x !== undefined && args.y !== undefined) {
-      x = args.x;
-      y = args.y;
-    } else {
-      return err({ kind: "invalid_state", message: "Provide either `ref` or both `x` and `y`." });
-    }
+    const resolved = await resolveTarget(client, args);
+    if (!resolved.success) return resolved;
+    const { x, y, label: target } = resolved.data;
 
     const clicked = await dispatchClick(client, x, y, button, count);
     if (!clicked.success) return clicked;
 
-    const target = args.ref !== undefined ? `[${args.ref}] (${x}, ${y})` : `(${x}, ${y})`;
     const diff = await interactiveDiff(client);
-    if (process.env["BH_DEBUG_CLICKS"]) {
+    if (debugClicksEnabled()) {
       const debug = await captureWithCrosshair(client, { x, y });
       if (debug.success) {
         return ok({

package/src/domains/console.ts

@@ -5,6 +5,7 @@ import { type Result, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
 import type { ConsoleRecord, ConsoleLevel } from "../cdp/console-buffer";
+import { asArrayOf, asBoolean, asNumber, asRecord, asString } from "../util/guards";
 
 const ConsoleArgs = Type.Object({
   levels: Type.Optional(
@@ -106,6 +107,50 @@ type ConsoleDetails = {
   nextCursor?: number;
 };
 
+const CONSOLE_LEVELS: ReadonlyArray<ConsoleLevel> = ["log", "info", "warn", "error", "debug"];
+
+const asConsoleLevel = (v: unknown): ConsoleLevel | undefined =>
+  CONSOLE_LEVELS.find((l) => l === v);
+
+const asConsoleRecord = (v: unknown): ConsoleRecord | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const level = asConsoleLevel(o["level"]);
+  const text = asString(o["text"]);
+  if (level === undefined || text === undefined) return undefined;
+  const url = asString(o["url"]);
+  const lineNumber = asNumber(o["lineNumber"]);
+  const stackTrace = asString(o["stackTrace"]);
+  return {
+    seq: asNumber(o["seq"]) ?? 0,
+    timestampMs: asNumber(o["timestampMs"]) ?? 0,
+    level,
+    text,
+    source: o["source"] === "log-entry" ? "log-entry" : "console-api",
+    ...(url !== undefined ? { url } : {}),
+    ...(lineNumber !== undefined ? { lineNumber } : {}),
+    ...(stackTrace !== undefined ? { stackTrace } : {}),
+  };
+};
+
+const asConsoleDetails = (v: unknown): ConsoleDetails | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const records = asArrayOf(o["records"], asConsoleRecord);
+  if (records === undefined) return undefined;
+  const fullOutputPath = asString(o["fullOutputPath"]);
+  const nextCursor = asNumber(o["nextCursor"]);
+  return {
+    total: asNumber(o["total"]) ?? records.length,
+    returned: asNumber(o["returned"]) ?? records.length,
+    bufferOverflowed: asBoolean(o["bufferOverflowed"]) ?? false,
+    truncated: asBoolean(o["truncated"]) ?? false,
+    records,
+    ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
+    ...(nextCursor !== undefined ? { nextCursor } : {}),
+  };
+};
+
 export const consoleTool = defineBrowserTool({
   name: "browser_console",
   label: "Browser Console",
@@ -119,6 +164,7 @@ export const consoleTool = defineBrowserTool({
     "Don't use as a default observation tool — prefer browser_snapshot for page structure.",
   ],
   parameters: ConsoleArgs,
+  concurrency: "parallel",
 
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const session = client.session();
@@ -136,7 +182,7 @@ export const consoleTool = defineBrowserTool({
     const text = renderConsoleMarkdown(drained.records, {
       total: drained.total,
       bufferOverflowed: drained.bufferOverflowed,
-      expanded: true, // full text always returned to the LLM; renderResult handles compact view for humans
+      expanded: true,
       nextCursor,
     });
     const trunc = await applyTruncation(text, "console");
@@ -155,7 +201,7 @@ export const consoleTool = defineBrowserTool({
   },
 
   renderResult(result, expanded, theme) {
-    const details = result.details as ConsoleDetails | undefined;
+    const details = asConsoleDetails(result.details);
     if (!details) return new Text(theme.fg("error", "console: no details"), 0, 0);
 
     const md = renderConsoleMarkdown(details.records, {

package/src/domains/dialog.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
-import { type Result, err, ok } from "../util/result";
+import { type Result, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
 
 const HandleDialogArgs = Type.Object({
   accept: Type.Boolean({ description: "true = accept, false = dismiss" }),
@@ -18,11 +19,13 @@ export const handleDialogTool = defineBrowserTool({
     "For prompt() dialogs, supply promptText with the value to submit.",
   ],
   parameters: HandleDialogArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const params: Record<string, unknown> = { accept: args.accept };
-    if (args.promptText !== undefined) params["promptText"] = args.promptText;
-    const r = await client.session().call("Page.handleJavaScriptDialog", params);
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const r = await cdpCall(client, "Page.handleJavaScriptDialog", {
+      accept: args.accept,
+      ...(args.promptText !== undefined ? { promptText: args.promptText } : {}),
+    });
+    if (!r.success) return r;
     return ok({
       text: `Dialog ${args.accept ? "accepted" : "dismissed"}`,
       details: { accept: args.accept },