pi-browser-harness 0.10.2 → 0.12.0

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);
 };
 
@@ -59,41 +58,24 @@ export const clickTool = defineBrowserTool({
     "Click an element. PREFERRED: pass `ref` (e.g. 'e12') from browser_snapshot — it re-resolves the element's position at click time, so it works even after the page re-renders and moves things. Fallback: pass viewport CSS-pixel `x`/`y`. Compositor-level click works through iframes, shadow DOM, and cross-origin content. After clicking, a compact diff of page changes is appended.",
   promptSnippet: "Click an element by ref (preferred) or pixel coordinates",
   promptGuidelines: [
-    "PREFER `ref` from browser_snapshot (the outline shows '[eN]' for every interactive element) — it survives re-renders, unlike coordinates which go stale after a save/edit reflows the page.",
-    "Fallback: pass (x, y) from the snapshot's '@(x,y)' hint when there's no ref.",
-    "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",
@@ -113,12 +158,11 @@ export const consoleTool = defineBrowserTool({
     "Read JS errors and console messages from the active tab. Diagnostic — use when an action looks broken or silent.",
   promptSnippet: "Read JS errors / console output on the current tab",
   promptGuidelines: [
-    "Use after a click, submit, or navigate produced no visible change — errors often explain it.",
-    "Pass `sinceSeq` from the previous call's `nextCursor` to see only new messages after an action.",
     "Buffer is reset on tab switch (capacity 500 records). bufferOverflowed:true means older entries were dropped.",
     "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 +180,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 +199,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 },

package/src/domains/drag.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 DragArgs = Type.Object({
   startX: Type.Number(),
@@ -24,6 +25,7 @@ export const dragAndDropTool = defineBrowserTool({
     "dataTransfer is an optional MIME→data map (e.g., { 'text/plain': 'hello' }).",
   ],
   parameters: DragArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const data = args.dataTransfer
       ? {
@@ -34,12 +36,11 @@ export const dragAndDropTool = defineBrowserTool({
           dragOperationsMask: 1,
         }
       : { items: [], dragOperationsMask: 1 };
-    const cdp = client.session();
-    const calls: ReadonlyArray<readonly [string, Record<string, unknown>]> = [
+    type InputCall = readonly ["Input.dispatchMouseEvent" | "Input.dispatchDragEvent", Record<string, unknown>];
+    const calls: ReadonlyArray<InputCall> = [
       ["Input.dispatchMouseEvent", { type: "mousePressed", x: args.startX, y: args.startY, button: "left", clickCount: 1 }],
       ["Input.dispatchDragEvent", { type: "dragEnter", x: args.startX, y: args.startY, data, modifiers: 0 }],
-      // 5 interpolated dragOver steps from start → end so the page sees a smooth drag.
-      ...Array.from({ length: 5 }, (_, i): readonly [string, Record<string, unknown>] => {
+      ...Array.from({ length: 5 }, (_, i): InputCall => {
         const t = (i + 1) / 5;
         return [
           "Input.dispatchDragEvent",
@@ -56,8 +57,8 @@ export const dragAndDropTool = defineBrowserTool({
       ["Input.dispatchMouseEvent", { type: "mouseReleased", x: args.endX, y: args.endY, button: "left", clickCount: 1 }],
     ];
     for (const [method, params] of calls) {
-      const r = await cdp.call(method, params);
-      if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+      const r = await cdpCall(client, method, params);
+      if (!r.success) return r;
     }
     return ok({
       text: `Dragged from (${args.startX},${args.startY}) to (${args.endX},${args.endY})`,

package/src/domains/element-call.ts

@@ -0,0 +1,117 @@
+import type { BrowserClient } from "../client";
+import { safeJs } from "../util/js-template";
+import { type Result, err, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { cdpCall, evalJs } from "./cdp-call";
+import { resolveRefToObjectId } from "./ref-resolve";
+
+export type PageResult = {
+  readonly ok: boolean;
+  readonly reason?: string;
+  readonly kind?: string;
+  readonly value?: unknown;
+  readonly text?: string;
+  readonly checked?: boolean;
+  readonly changed?: boolean;
+  readonly tag?: string;
+  readonly options?: ReadonlyArray<{ value: string; text: string }>;
+};
+
+const isOption = (v: unknown): v is { readonly value: string; readonly text: string } =>
+  typeof v === "object" && v !== null
+  && "value" in v && typeof v.value === "string"
+  && "text" in v && typeof v.text === "string";
+
+export const isPageResult = (v: unknown): v is PageResult => {
+  if (typeof v !== "object" || v === null) return false;
+  if (!("ok" in v) || typeof v.ok !== "boolean") return false;
+  if ("reason" in v && typeof v.reason !== "string") return false;
+  if ("kind" in v && typeof v.kind !== "string") return false;
+  if ("text" in v && typeof v.text !== "string") return false;
+  if ("checked" in v && typeof v.checked !== "boolean") return false;
+  if ("changed" in v && typeof v.changed !== "boolean") return false;
+  if ("tag" in v && typeof v.tag !== "string") return false;
+  if ("options" in v && !(Array.isArray(v.options) && v.options.every(isOption))) return false;
+  return true;
+};
+
+export const runOnElement = async (
+  client: BrowserClient,
+  opts: {
+    ref?: string | undefined;
+    selector?: string | undefined;
+    fnBody: string;
+    arg: unknown;
+    notFound?: unknown;
+  },
+): Promise<Result<unknown, ToolErr>> => {
+  if (opts.ref !== undefined) {
+    const objectId = await resolveRefToObjectId(client, opts.ref);
+    if (!objectId.success) return objectId;
+    const r = await cdpCall(client, "Runtime.callFunctionOn", {
+      objectId: objectId.data,
+      functionDeclaration: `function (arg) { ${opts.fnBody} }`,
+      arguments: [{ value: opts.arg }],
+      returnByValue: true,
+    });
+    if (!r.success) return r;
+    if (r.data.exceptionDetails !== undefined) {
+      return err({
+        kind: "cdp_error",
+        message: `page function threw: ${r.data.exceptionDetails.text}`,
+        details: { ref: opts.ref },
+      });
+    }
+    return ok(r.data.result.value);
+  }
+  if (opts.selector === undefined) {
+    return err({ kind: "invalid_state", message: "Provide either `ref` or `selector`." });
+  }
+  // fnBody is harness-authored, not user input; only the selector and value are interpolated, and those go through safeJs.
+  const prelude = safeJs`
+    (() => {
+      const el = document.querySelector(${opts.selector});
+      if (!el) return ${opts.notFound ?? { status: "not_found" }};
+      const __arg = ${opts.arg};
+      return (function (arg) {`;
+  const expr = `${prelude} ${opts.fnBody} }).call(el, __arg); })()`;
+  const r = await evalJs(client, expr);
+  if (!r.success) return r;
+  return ok(r.data);
+};
+
+export const resolveAndCall = async (
+  client: BrowserClient,
+  ref: string,
+  functionDeclaration: string,
+  args: ReadonlyArray<unknown>,
+): Promise<Result<PageResult, ToolErr>> => {
+  const objectId = await resolveRefToObjectId(client, ref);
+  if (!objectId.success) return objectId;
+  const handle = objectId.data;
+  try {
+    const called = await cdpCall(client, "Runtime.callFunctionOn", {
+      objectId: handle,
+      functionDeclaration,
+      arguments: args.map((v) => ({ value: v })),
+      returnByValue: true,
+      awaitPromise: true,
+    });
+    if (!called.success) return err({ ...called.error, details: { ref } });
+    if (called.data.exceptionDetails !== undefined) {
+      return err({ kind: "cdp_error", message: `page function threw: ${JSON.stringify(called.data.exceptionDetails)}`, details: { ref } });
+    }
+    const value = called.data.result.value;
+    if (!isPageResult(value)) {
+      return err({ kind: "internal", message: "page function returned no result object", details: { ref } });
+    }
+    return ok(value);
+  } finally {
+    await cdpCall(client, "Runtime.releaseObject", { objectId: handle });
+  }
+};
+
+export const detailsOf = (ref: string, res: PageResult, extra?: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> => {
+  const { ok: _ok, ...rest } = res;
+  return { ref, ...rest, ...(extra ?? {}) };
+};

package/src/domains/files.ts

@@ -6,6 +6,7 @@ import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { safeJs } from "../util/js-template";
 import { pdfPath } from "../util/paths";
+import { cdpCall, cdpCallBrowser, evalJs } from "./cdp-call";
 import { resolveRefToBackendId } from "./ref-resolve";
 
 const UploadArgs = Type.Object({
@@ -16,15 +17,13 @@ const UploadArgs = Type.Object({
   filePath: Type.String({ description: "Absolute path to the file to upload" }),
 });
 
-// Ref path: set files directly on the resolved backendNodeId via CDP — simplest
-// and most reliable, no selector needed.
 const tryRefUpload = async (
   client: BrowserClient,
   backendId: number,
   filePath: string,
 ): Promise<Result<void, ToolErr>> => {
-  const set = await client.session().call("DOM.setFileInputFiles", { files: [filePath], backendNodeId: backendId });
-  if (!set.success) return err({ kind: "cdp_error", message: set.error.message });
+  const set = await cdpCall(client, "DOM.setFileInputFiles", { files: [filePath], backendNodeId: backendId });
+  if (!set.success) return set;
   return ok(undefined);
 };
 
@@ -45,19 +44,16 @@ const tryCdpUpload = async (
   selector: string,
   filePath: string,
 ): Promise<Result<void, ToolErr>> => {
-  const doc = await client.session().call("DOM.getDocument", { depth: -1 });
-  if (!doc.success) return err({ kind: "cdp_error", message: doc.error.message });
-  // CDP boundary cast: DOM.getDocument returns { root: { nodeId: number } }
-  const root = (doc.data as { root: { nodeId: number } }).root;
-  const q = await client.session().call("DOM.querySelector", { nodeId: root.nodeId, selector });
-  if (!q.success) return err({ kind: "cdp_error", message: q.error.message });
-  // CDP boundary cast: DOM.querySelector returns { nodeId: number }
-  const nodeId = (q.data as { nodeId: number }).nodeId;
+  const doc = await cdpCall(client, "DOM.getDocument", { depth: -1 });
+  if (!doc.success) return doc;
+  const q = await cdpCall(client, "DOM.querySelector", { nodeId: doc.data.root.nodeId, selector });
+  if (!q.success) return q;
+  const nodeId = q.data.nodeId;
   if (!nodeId) return err({ kind: "invalid_state", message: `Selector matched 0 file inputs: ${selector}` });
-  const set = await client.session().call("DOM.setFileInputFiles", { files: [filePath], nodeId });
-  if (!set.success) return err({ kind: "cdp_error", message: set.error.message });
-  const verify = await client.evaluateJs(safeJs`document.querySelector(${selector})?.files?.length || 0`);
-  if (!verify.success) return err({ kind: "cdp_error", message: verify.error.message });
+  const set = await cdpCall(client, "DOM.setFileInputFiles", { files: [filePath], nodeId });
+  if (!set.success) return set;
+  const verify = await evalJs(client, safeJs`document.querySelector(${selector})?.files?.length || 0`);
+  if (!verify.success) return verify;
   if (Number(verify.data ?? 0) === 0) {
     return err({ kind: "invalid_state", message: "CDP upload reported success but file count is 0" });
   }
@@ -96,8 +92,8 @@ const jsFallbackUpload = async (
       return input.files.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;
   if (!Number(r.data ?? 0)) return err({ kind: "invalid_state", message: "JS fallback set 0 files" });
   return ok(undefined);
 };
@@ -108,15 +104,15 @@ export const uploadFileTool = defineBrowserTool({
   description: "Set files on a file <input> via CDP, with a JS-DataTransfer fallback for stubborn pages. PREFERRED: pass `ref` from browser_snapshot; fallback: a CSS `selector`.",
   promptSnippet: "Upload a file to a file input by ref (preferred) or selector",
   promptGuidelines: [
-    "PREFER `ref` from browser_snapshot over a CSS selector — survives re-renders. (File inputs are often hidden; snapshot still surfaces them.)",
+    "File inputs are often hidden; browser_snapshot still surfaces them.",
     "File path must be absolute and readable.",
   ],
   parameters: UploadArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const readable = await verifyReadable(args.filePath);
     if (!readable.success) return readable;
 
-    // Ref path: resolve to backendNodeId and set files directly via CDP.
     if (args.ref !== undefined) {
       const backendId = resolveRefToBackendId(client, args.ref);
       if (!backendId.success) return backendId;
@@ -149,21 +145,70 @@ export const uploadFileTool = defineBrowserTool({
   },
 });
 
+// Chrome stores the override in its default browser context, so it outlives this client and
+// silently redirects the user's own downloads. Track it, so session teardown can undo it.
+// The flag only records what THIS process set: the daemon is shared by every pi process on the
+// machine and the CDP primitive is last-writer-wins, so another session may have reset or
+// re-pointed it since. A crashed or killed session never reaches teardown, so the override can
+// also outlive the process that set it.
+let activeDownloadOverride: string | undefined;
+
+// Shutdown must not block on a browser that is already gone: a pending restore against a
+// disconnected daemon would otherwise trigger the one-shot reconnect (and Chrome's consent
+// prompt) that 0.11.1 confined to explicit tool calls, and wait up to the connect timeout.
+const SHUTDOWN_RESTORE_TIMEOUT_MS = 2_000;
+
+export const restoreDownloadBehavior = async (client: BrowserClient): Promise<Result<void, ToolErr>> => {
+  const pending = activeDownloadOverride;
+  if (pending === undefined) return ok(undefined);
+  if (!client.status().alive) {
+    return err({ kind: "not_connected", message: `browser not connected; downloads may keep going to ${pending} until Chrome restarts` });
+  }
+  const r = await cdpCallBrowser(client, "Browser.setDownloadBehavior", { behavior: "default" }, { timeoutMs: SHUTDOWN_RESTORE_TIMEOUT_MS });
+  if (!r.success) {
+    return err({ ...r.error, message: `${r.error.message} (downloads may keep going to ${pending})` });
+  }
+  activeDownloadOverride = undefined;
+  return ok(undefined);
+};
+
 const DownloadArgs = Type.Object({
-  downloadPath: Type.String({ description: "Absolute path to a writable directory where downloads should be saved" }),
+  downloadPath: Type.Optional(
+    Type.String({ description: "Absolute path to a writable directory where downloads should be saved" }),
+  ),
+  restore: Type.Optional(
+    Type.Boolean({
+      description:
+        "Undo a previous browser_download: reset Chrome's download behavior back to the user's own default.",
+    }),
+  ),
 });
 
 export const downloadTool = defineBrowserTool({
   name: "browser_download",
   label: "Browser Download",
-  description: "Configure Chrome's download behavior: set the save directory and disable the save-as prompt.",
+  description:
+    "Configure Chrome's download behavior: set the save directory and disable the save-as prompt, or restore the user's default. Restored automatically when this session shuts down cleanly.",
   promptSnippet: "Configure download directory",
   promptGuidelines: [
     "Pass an absolute path to an existing writable directory.",
-    "Affects all subsequent downloads on this browser.",
+    "The override applies to the user's own downloads too, not just yours, and only a clean session shutdown undoes it. Call browser_download({restore:true}) as soon as you are done.",
   ],
   parameters: DownloadArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    if (args.restore === true) {
+      if (args.downloadPath !== undefined) {
+        return err({ kind: "invalid_state", message: "Pass either downloadPath or restore, not both" });
+      }
+      const r = await cdpCallBrowser(client, "Browser.setDownloadBehavior", { behavior: "default" });
+      if (!r.success) return r;
+      activeDownloadOverride = undefined;
+      return ok({ text: "Downloads restored to Chrome's default location", details: { restored: true } });
+    }
+    if (args.downloadPath === undefined) {
+      return err({ kind: "invalid_state", message: "Provide downloadPath to set a directory, or restore:true to undo" });
+    }
     try {
       await mkdir(args.downloadPath, { recursive: true });
     } catch (e) {
@@ -184,12 +229,13 @@ export const downloadTool = defineBrowserTool({
         message: `Download path unusable: ${e instanceof Error ? e.message : String(e)}`,
       });
     }
-    const r = await client.session().callBrowser("Browser.setDownloadBehavior", {
+    const r = await cdpCallBrowser(client, "Browser.setDownloadBehavior", {
       behavior: "allow",
       downloadPath: args.downloadPath,
       eventsEnabled: true,
     });
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    if (!r.success) return r;
+    activeDownloadOverride = args.downloadPath;
     return ok({
       text: `Downloads will save to: ${args.downloadPath}`,
       details: { downloadPath: args.downloadPath },
@@ -208,16 +254,15 @@ export const printToPdfTool = defineBrowserTool({
   promptSnippet: "Print the current page to PDF",
   promptGuidelines: ["Default output path is in tmpdir; pass outputPath to control."],
   parameters: PrintPdfArgs,
+  concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const r = await client.session().call("Page.printToPDF", {
+    const r = await cdpCall(client, "Page.printToPDF", {
       printBackground: true,
       preferCSSPageSize: true,
     });
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
-    // CDP boundary cast: Page.printToPDF returns { data: string } (base64-encoded PDF)
-    const data = (r.data as { data: string }).data;
+    if (!r.success) return r;
     const path = args.outputPath ?? pdfPath(client.namespace);
-    await writeFile(path, Buffer.from(data, "base64"));
+    await writeFile(path, Buffer.from(r.data.data, "base64"));
     return ok({ text: `PDF saved: ${path}`, details: { path } });
   },
 });