pi-browser-harness 0.10.2 → 0.11.0

package/src/domains/search/google-serp.ts

@@ -1,27 +1,14 @@
-/**
- * Pure Google SERP parsing — no CDP, no browser. Everything here is a pure
- * function over data captured from the page, so it is unit-testable against
- * saved fixtures (see test/deep-research/serp-parser-test.ts).
- *
- * ADR-0001: results are extracted by structure/semantics (anchors carrying an
- * <h3> heading in the main results column), never by brittle Google CSS class
- * names, and Google redirect wrappers are unwound to the real target URL.
- */
-
-/** One raw anchor captured in-page: a link with a heading and nearby snippet. */
 export type SerpAnchor = {
   readonly href: string;
   readonly heading: string;
   readonly snippet: string;
 };
 
-/** The JSON payload the in-page extraction expression returns. */
 export type SerpExtraction = {
   readonly anchors: ReadonlyArray<SerpAnchor>;
   readonly pageText: string;
 };
 
-/** A parsed, ranked search result — the tool's public output shape. */
 export type SearchResult = {
   readonly title: string;
   readonly url: string;
@@ -29,7 +16,6 @@ export type SearchResult = {
   readonly rank: number;
 };
 
-/** Why a SERP yielded no usable results, or that it did. */
 export type SerpVerdict = "ok" | "captcha" | "no_results";
 
 const CAPTCHA_MARKERS: ReadonlyArray<string> = [
@@ -42,10 +28,6 @@ const CAPTCHA_MARKERS: ReadonlyArray<string> = [
   "our systems have detected unusual traffic",
 ];
 
-/**
- * Decode a Google redirect wrapper (`/url?q=<real>&sa=...`) to its target.
- * Returns the input unchanged when it is not a wrapper.
- */
 const unwrapRedirect = (href: string): string => {
   const wrapper = href.match(/^(?:https?:\/\/[^/]*google\.[^/]*)?\/url\?/i);
   if (!wrapper) return href;
@@ -66,7 +48,6 @@ const isExternalResult = (url: string): boolean => {
   }
 };
 
-/** Normalized key for dedupe: origin + pathname, trailing slash and hash removed. */
 const dedupeKey = (url: string): string => {
   try {
     const u = new URL(url);
@@ -76,11 +57,6 @@ const dedupeKey = (url: string): string => {
   }
 };
 
-/**
- * Parse captured anchors into ranked results: unwrap redirects, keep only
- * external http(s) links, dedupe by normalized url (first wins), rank by input
- * order, cap to `limit`.
- */
 export const parseGoogleSerp = (anchors: ReadonlyArray<SerpAnchor>, limit: number): ReadonlyArray<SearchResult> => {
   const seen = new Set<string>();
   const results: SearchResult[] = [];
@@ -101,11 +77,6 @@ export const parseGoogleSerp = (anchors: ReadonlyArray<SerpAnchor>, limit: numbe
   return results;
 };
 
-/**
- * Decide whether the SERP is usable, blocked by a CAPTCHA, or genuinely empty.
- * `resultCount` is the number of parsed results; `pageText` is a bounded slice
- * of the page's visible text.
- */
 export const classifySerp = (pageText: string, resultCount: number): SerpVerdict => {
   if (resultCount > 0) return "ok";
   const lower = pageText.toLowerCase();

package/src/domains/search/web-search.ts

@@ -1,16 +1,18 @@
 import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../../schemas/parse";
 import { type Result, err, ok } from "../../util/result";
 import { applyTruncation } from "../../util/truncate";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
 import {
   closeIsolatedTab,
   evalInIsolatedTab,
+  isJsonText,
   navigateIsolatedTab,
   openIsolatedTab,
   waitForIsolatedLoad,
 } from "../isolated-tab";
 import { renderExpandableText } from "../render";
-import { buildSerpExtractionExpr } from "./extract";
 import { classifySerp, parseGoogleSerp, type SearchResult, type SerpExtraction } from "./google-serp";
 
 const LOAD_TIMEOUT_MS = 15_000;
@@ -22,14 +24,46 @@ const WebSearchArgs = Type.Object({
   ),
 });
 
+const PAGE_TEXT_LIMIT = 4000;
+
+const buildSerpExtractionExpr = (): string => `
+  (() => {
+    const main = document.querySelector('#search, #rso, #main') || document.body;
+    const headings = Array.from(main.querySelectorAll('a h3'));
+    const seen = new Set();
+    const anchors = [];
+    for (const h3 of headings) {
+      const a = h3.closest('a[href]');
+      if (!a) continue;
+      const href = a.href;
+      if (!href || seen.has(href)) continue;
+      seen.add(href);
+      const container =
+        a.closest('div.g') ||
+        a.closest('div[data-hveid]') ||
+        a.parentElement?.parentElement ||
+        a.parentElement;
+      const containerText = container ? container.innerText || '' : '';
+      const heading = h3.innerText || h3.textContent || '';
+      const snippet = containerText.replace(heading, '').replace(/\\s+/g, ' ').trim().slice(0, 500);
+      anchors.push({ href, heading, snippet });
+    }
+    const pageText = (document.body.innerText || '').slice(0, ${PAGE_TEXT_LIMIT});
+    return JSON.stringify({ anchors, pageText });
+  })()
+`;
+
 const buildSerpUrl = (query: string, limit: number): string =>
   `https://www.google.com/search?q=${encodeURIComponent(query)}&num=${limit}&hl=en`;
 
-const isSerpExtraction = (value: unknown): value is SerpExtraction => {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  return Array.isArray(v["anchors"]) && typeof v["pageText"] === "string";
-};
+const SerpExtractionSchema = Type.Object({
+  anchors: Type.Array(
+    Type.Object({ href: Type.String(), heading: Type.String(), snippet: Type.String() }),
+  ),
+  pageText: Type.String(),
+});
+
+const serpExtractionValidator = Compile(SerpExtractionSchema);
 
 const formatResults = (query: string, results: ReadonlyArray<SearchResult>): string => {
   const lines = results.map((r) => `${r.rank}. ${r.title}\n   ${r.url}\n   ${r.snippet}`);
@@ -49,6 +83,7 @@ export const webSearchTool = defineBrowserTool({
     "Runs in its own isolated tab and never disturbs the user's current tab.",
   ],
   parameters: WebSearchArgs,
+  concurrency: "serialized",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     const limit = args.limit ?? 10;
     const serpUrl = buildSerpUrl(args.query, limit);
@@ -64,16 +99,17 @@ export const webSearchTool = defineBrowserTool({
       const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
       if (!loaded.success) return err(loaded.error);
 
-      const extracted = await evalInIsolatedTab(client, tab, buildSerpExtractionExpr());
+      const extracted = await evalInIsolatedTab(client, tab, buildSerpExtractionExpr(), isJsonText);
       if (!extracted.success) return err(extracted.error);
 
-      const parsedJson = typeof extracted.data === "string" ? safeParse(extracted.data) : extracted.data;
-      if (!isSerpExtraction(parsedJson)) {
-        return err({ kind: "internal", message: "SERP extraction returned an unexpected shape" });
+      const parsedJson = parseJson(extracted.data, serpExtractionValidator);
+      if (!parsedJson.success) {
+        return err({ kind: "internal", message: `SERP extraction returned an unexpected shape: ${parsedJson.error}` });
       }
+      const extraction: SerpExtraction = parsedJson.data;
 
-      const results = parseGoogleSerp(parsedJson.anchors, limit);
-      const verdict = classifySerp(parsedJson.pageText, results.length);
+      const results = parseGoogleSerp(extraction.anchors, limit);
+      const verdict = classifySerp(extraction.pageText, results.length);
       if (verdict !== "ok") {
         return err({
           kind: "invalid_state",
@@ -106,11 +142,3 @@ export const webSearchTool = defineBrowserTool({
     return renderExpandableText("web_search", result, expanded, theme);
   },
 });
-
-const safeParse = (text: string): unknown => {
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    return undefined;
-  }
-};

package/src/domains/setup.ts

@@ -1,11 +1,3 @@
-/**
- * browser_setup tool — agent-callable browser initialization.
- *
- * The agent can call this directly when browser tools fail with
- * "not initialized" instead of asking the user. Idempotent: safe
- * to call even when already connected.
- */
-
 import { Type } from "typebox";
 import { Text } from "@mariozechner/pi-tui";
 import type { Result } from "../util/result";
@@ -28,12 +20,10 @@ export const setupTool = defineBrowserTool({
     "After browser_setup succeeds, retry the browser tool that failed.",
   ],
   parameters: SetupArgs,
-  // ensureAlive:false — this tool IS the setup; it must bypass the socket guard
+  concurrency: "parallel",
   ensureAlive: false,
   renderCall: () => new Text("🔧 Initializing browser...", 0, 0),
   async handler(_args, { client, extensionCtx }): Promise<Result<ToolOk, ToolErr>> {
-    // extensionCtx carries the UI, so the agent calling browser_setup gets the
-    // same first-run profile picker the user gets from /browser-setup.
     const result = await performSetup(client, extensionCtx);
     if (result.success) {
       return ok({ text: result.data });

package/src/domains/snapshot.ts

@@ -2,11 +2,23 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { Type } from "typebox";
 import { Container, Image, type ImageTheme, Markdown, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
-import type { CdpSession } from "../cdp/session";
+import { boxOf } from "./box";
+import { cdpCall } from "./cdp-call";
+import {
+  buildTree,
+  collectInteractiveTargets,
+  countNodes,
+  INTERACTIVE_ROLES,
+  liveValue,
+  type SlimNode,
+  stripInternals,
+  VALUE_ROLES,
+} from "./ax-tree";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
 import { screenshotPath } from "../util/paths";
+import { asBoolean, asNumber, asRecord, asString } from "../util/guards";
 
 const SnapshotArgs = Type.Object({
   includeScreenshot: Type.Optional(
@@ -26,168 +38,6 @@ const SnapshotArgs = Type.Object({
   ),
 });
 
-// Raw shapes from CDP Accessibility.getFullAXTree. Cast at this boundary only.
-type AxValue = { value?: unknown };
-export type RawAxNode = {
-  nodeId: string;
-  parentId?: string;
-  childIds?: ReadonlyArray<string>;
-  ignored?: boolean;
-  role?: AxValue;
-  name?: AxValue;
-  value?: AxValue;
-  description?: AxValue;
-  properties?: ReadonlyArray<{ name?: string; value?: AxValue }>;
-  backendDOMNodeId?: number;
-};
-
-type Box = { x: number; y: number; width: number; height: number; cx: number; cy: number };
-
-export type SlimNode = {
-  role: string;
-  name?: string;
-  value?: string;
-  description?: string;
-  state?: string;
-  children: SlimNode[];
-  /** Internal: kept for the post-build box fetch. Stripped before returning to the LLM. */
-  _backendId?: number;
-  /** Stable handle (e.g. "e12") for interaction tools. Survives re-renders via backendNodeId. */
-  ref?: string;
-  /** Click target — center of the element's bounding box, in viewport CSS pixels. */
-  box?: Box;
-};
-
-const INTERACTIVE_ROLES = new Set([
-  "button",
-  "link",
-  "textbox",
-  "checkbox",
-  "radio",
-  "combobox",
-  "menuitem",
-  "tab",
-  "switch",
-  "slider",
-  "searchbox",
-  "spinbutton",
-]);
-
-// Roles whose live DOM value/checked state should override the (often stale)
-// AX-tree value. The AX `value` is unreliable for freshly-typed or controlled
-// inputs, so for these we read the real DOM property at snapshot time.
-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;
-    // Boolean flags worth surfacing in the outline.
-    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[] => {
-  // Index for parent/child lookups.
-  const byId = new Map<string, RawAxNode>();
-  for (const n of rawNodes) byId.set(n.nodeId, n);
-
-  // CDP doesn't mark a single root explicitly; the root nodes are the ones
-  // whose parentId isn't in the index (typically just one — RootWebArea).
-  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) {
-      // Skip the ignored node but recurse through its children — Chrome often
-      // ignores wrapper divs but the meaningful descendants are still there.
-      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);
-      }
-      // Hoist children into the parent. We return undefined; the parent's
-      // recursion will see them by re-walking — but that double-counts. Instead
-      // we handle hoisting at the parent level. So here just signal "skip me"
-      // by returning undefined; the parent will hoist by checking ignored flag.
-      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;
-      // Hoist any synthetic _hoist nodes' children into this level.
-      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;
-};
-
-const countNodes = (nodes: ReadonlyArray<SlimNode>): number => {
-  let n = 0;
-  for (const node of nodes) n += 1 + countNodes(node.children);
-  return n;
-};
-
 const summarize = (nodes: ReadonlyArray<SlimNode>): string => {
   const counts = new Map<string, number>();
   const walk = (ns: ReadonlyArray<SlimNode>): void => {
@@ -197,7 +47,6 @@ const summarize = (nodes: ReadonlyArray<SlimNode>): string => {
     }
   };
   walk(nodes);
-  // Group landmarks (roles that are top-level structural).
   const landmarkRoles = new Set(["banner", "navigation", "main", "complementary", "contentinfo", "search", "form", "region"]);
   let landmarks = 0;
   for (const [role, c] of counts) if (landmarkRoles.has(role)) landmarks += c;
@@ -221,8 +70,6 @@ const renderOutline = (nodes: ReadonlyArray<SlimNode>): string => {
       if (n.name) line += ` "${n.name}"`;
       if (n.value && n.value !== n.name) line += ` = ${JSON.stringify(n.value)}`;
       if (n.state) line += ` (${n.state})`;
-      // Surface the stable ref + click coordinates for interactive nodes. Agents
-      // pass `ref` to interaction tools (survives re-renders); @(x,y) is a fallback.
       if (n.ref) line += ` [${n.ref}]`;
       if (n.box && INTERACTIVE_ROLES.has(n.role)) {
         line += ` @(${n.box.cx},${n.box.cy})`;
@@ -235,61 +82,6 @@ const renderOutline = (nodes: ReadonlyArray<SlimNode>): string => {
   return lines.join("\n");
 };
 
-/** Strip internal _backendId from a slim tree before returning to callers. */
-const stripInternals = (nodes: ReadonlyArray<SlimNode>): SlimNode[] =>
-  nodes.map((n) => {
-    const { _backendId: _bid, ...rest } = n;
-    return { ...rest, children: stripInternals(n.children) };
-  });
-
-/**
- * Walk all slim nodes and collect (slimNode, backendId) pairs for interactive
- * roles. Caller fetches DOM.getBoxModel for each and writes box back into the
- * slim node by reference.
- */
-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;
-};
-
-/**
- * Read the live DOM value for a form control by backend node id. Resolves the
- * node to a JS object then reads the property that matters for its type:
- * `.value` for inputs/selects/textareas, `.checked` (→ "checked"/"unchecked")
- * for checkboxes/radios. Returns undefined on any failure so the caller falls
- * back to the AX value. Mirrors the box-fetch error handling: never throws.
- */
-const liveValue = async (session: CdpSession, backendId: number): Promise<string | undefined> => {
-  const resolved = await session.call("DOM.resolveNode", { backendNodeId: backendId });
-  if (!resolved.success) return undefined;
-  const objectId = (resolved.data as { object?: { objectId?: string } }).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 session.call("Runtime.callFunctionOn", {
-    objectId,
-    functionDeclaration: fn,
-    returnByValue: true,
-  });
-  if (!r.success) return undefined;
-  const value = (r.data as { result?: { value?: unknown } }).result?.value;
-  return typeof value === "string" ? value : undefined;
-};
-
 type SnapshotDetails = {
   nodeCount: number;
   truncated: boolean;
@@ -314,37 +106,27 @@ export const snapshotTool = defineBrowserTool({
     "format:'json' returns the raw slim structure (with `ref` and `box` per node) for programmatic use; default 'outline' is human/LLM-readable.",
   ],
   parameters: SnapshotArgs,
+  concurrency: "parallel",
 
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     const session = client.session();
 
-    // 1. AX tree
-    const axRes = await session.call("Accessibility.getFullAXTree", {});
-    if (!axRes.success) return err({ kind: "cdp_error", message: axRes.error.message });
-    const rawNodes = (axRes.data as { nodes: ReadonlyArray<RawAxNode> }).nodes;
+    const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
+    if (!axRes.success) return axRes;
+    const rawNodes = axRes.data.nodes;
 
-    // 2. Page url/title
     const piRes = await client.pageInfo();
     if (!piRes.success) return err({ kind: "cdp_error", message: piRes.error.message });
     const pageUrl = "dialog" in piRes.data ? "" : piRes.data.url;
     const pageTitle = "dialog" in piRes.data ? "" : piRes.data.title;
 
-    // 3. Slim + format
     const slim = buildTree(rawNodes, {
       interestingOnly: args.interestingOnly ?? true,
       maxNodes: args.maxNodes ?? 1000,
     });
 
-    // 4. Fetch bounding boxes for interactive nodes so the agent can click
-    //    without a screenshot round-trip. Capped budget so a slow page can't
-    //    wedge the call.
     const targets = collectInteractiveTargets(slim);
 
-    // Assign stable refs (e1, e2, …) to every interactive target. Interaction
-    // tools resolve these refs to backendNodeIds at call time, so they stay
-    // valid across re-renders. The ref → backendNodeId map (and the per-ref
-    // signature baseline for the post-mutation diff) is published below, after
-    // the box/live-value fetch so the signature reflects the live DOM value.
     const refMap = new Map<string, number>();
     targets.forEach(({ node, backendId }, i) => {
       const ref = `e${i + 1}`;
@@ -358,42 +140,18 @@ export const snapshotTool = defineBrowserTool({
       await Promise.allSettled(
         targets.map(async ({ node, backendId }) => {
           if (ac.signal.aborted) return;
-          const r = await session.call("DOM.getBoxModel", { backendNodeId: backendId });
-          if (!r.success) return;
-          // CDP boundary cast: DOM.getBoxModel
-          const data = r.data as { model?: { content?: ReadonlyArray<number>; width?: number; height?: number } };
-          const content = data.model?.content;
-          if (!content || content.length < 8) return;
-          // content is [x1,y1, x2,y1, x2,y2, x1,y2] in viewport CSS pixels.
-          const x = content[0]!;
-          const y = content[1]!;
-          const width = data.model!.width ?? 0;
-          const height = data.model!.height ?? 0;
-          // Skip zero-size and off-viewport boxes — they can't be clicked.
-          if (width <= 0 || height <= 0 || x < 0 || y < 0) return;
-          node.box = {
-            x: Math.round(x),
-            y: Math.round(y),
-            width: Math.round(width),
-            height: Math.round(height),
-            cx: Math.round(x + width / 2),
-            cy: Math.round(y + height / 2),
-          };
-          // Override the AX value with the live DOM property for form controls.
-          // The AX `value` is stale for freshly-typed / controlled inputs, so the
-          // agent can't trust it as a read-back signal. Reading .value/.checked
-          // from the actual element fixes that.
+          const box = await boxOf(client, backendId);
+          if (!box.success) return;
+          if (box.data.x < 0 || box.data.y < 0) return;
+          node.box = box.data;
           if (ac.signal.aborted || !VALUE_ROLES.has(node.role)) return;
-          const live = await liveValue(session, backendId);
+          const live = await liveValue(client, backendId);
           if (live !== undefined) node.value = live;
         }),
       );
       clearTimeout(timer);
     }
 
-    // Publish refs to the active tab. The signature (role|name|value|state) is
-    // the baseline the post-mutation auto-diff compares against, so it must use
-    // the live values resolved above.
     const refSig = new Map<string, string>();
     for (const { node } of targets) {
       if (node.ref === undefined) continue;
@@ -405,14 +163,12 @@ export const snapshotTool = defineBrowserTool({
     const text = (args.format ?? "outline") === "outline" ? renderOutline(slim) : JSON.stringify(stripped, null, 2);
     const trunc = await applyTruncation(text, "snapshot");
 
-    // 4. Optional screenshot — JPEG q=80 to match screenshotTool's default.
     let shotPath: string | undefined;
     if (args.includeScreenshot) {
-      const shot = await session.call("Page.captureScreenshot", { format: "jpeg", quality: 80 });
+      const shot = await cdpCall(client, "Page.captureScreenshot", { format: "jpeg", quality: 80 });
       if (shot.success) {
-        const data = (shot.data as { data: string }).data;
         shotPath = screenshotPath(client.namespace, "jpeg");
-        writeFileSync(shotPath, Buffer.from(data, "base64"));
+        writeFileSync(shotPath, Buffer.from(shot.data.data, "base64"));
       }
     }
 
@@ -429,10 +185,17 @@ export const snapshotTool = defineBrowserTool({
   },
 
   renderResult(result, expanded, theme) {
-    const details = result.details as
-      | (SnapshotDetails & { summary?: string; ok?: boolean })
-      | undefined;
-    if (!details) return new Text(theme.fg("error", "snapshot: no details"), 0, 0);
+    const raw = asRecord(result.details);
+    if (raw === undefined) return new Text(theme.fg("error", "snapshot: no details"), 0, 0);
+    const details = {
+      nodeCount: asNumber(raw["nodeCount"]),
+      truncated: asBoolean(raw["truncated"]),
+      fullOutputPath: asString(raw["fullOutputPath"]),
+      screenshotPath: asString(raw["screenshotPath"]),
+      url: asString(raw["url"]),
+      title: asString(raw["title"]),
+      summary: asString(raw["summary"]),
+    };
 
     const titleLine = details.title ? ` "${details.title}"` : "";
     const summary = details.summary ?? "";
@@ -449,9 +212,6 @@ export const snapshotTool = defineBrowserTool({
       return new Markdown(md, 0, 0, getMarkdownTheme());
     }
 
-    // Expanded view: read truncated text from result.content (the spilled file
-    // is too large to inline) — the same `text` we returned from handler is in
-    // result.content[0]. Fall back to a placeholder if shape is unexpected.
     const content = result.content[0];
     const treeText = content && content.type === "text" ? content.text : "";
 
@@ -471,7 +231,6 @@ export const snapshotTool = defineBrowserTool({
 
     if (!details.screenshotPath) return treeBlock;
 
-    // Mirror screenshotTool's width-clamp wrapper for the inline image.
     try {
       const buf = readFileSync(details.screenshotPath);
       const b64 = buf.toString("base64");