pi-browser-harness 0.3.2 → 0.5.0

package/src/domains/network.ts

@@ -1,7 +1,10 @@
 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 { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
+import type { NetworkRecord } from "../cdp/network-buffer";
 
 const HttpGetArgs = Type.Object({
   url: Type.String({ description: "URL to GET" }),
@@ -49,32 +52,200 @@ export const httpGetTool = defineBrowserTool({
   },
 });
 
-const NetLogArgs = Type.Object({
-  eventTypes: Type.Optional(
-    Type.Array(Type.String(), { description: "CDP event names to filter (e.g., ['Network.requestWillBeSent'])" }),
+const NetworkRequestsArgs = Type.Object({
+  urlPattern: Type.Optional(
+    Type.String({ description: "Substring match by default. Wrap in slashes (e.g. /api\\\\.example/) for regex." }),
+  ),
+  methodFilter: Type.Optional(
+    Type.Array(Type.String(), { description: 'HTTP methods to include, e.g. ["GET","POST"].' }),
+  ),
+  statusFilter: Type.Optional(
+    Type.Object(
+      {
+        min: Type.Optional(Type.Integer({ minimum: 100, maximum: 599 })),
+        max: Type.Optional(Type.Integer({ minimum: 100, maximum: 599 })),
+      },
+      { description: "Inclusive HTTP status range." },
+    ),
+  ),
+  resourceTypes: Type.Optional(
+    Type.Array(Type.String(), { description: 'CDP resource types: "Document","Stylesheet","Image","Media","Font","Script","TextTrack","XHR","Fetch","EventSource","WebSocket","Manifest","SignedExchange","Ping","CSPViolationReport","Preflight","Other".' }),
+  ),
+  sinceMs: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Only requests started in the last N ms." }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({ default: 50, minimum: 1, maximum: 500, description: "Max records to return." }),
+  ),
+  includeResponseBodies: Type.Optional(
+    Type.Boolean({ default: false, description: "Fetch response bodies via Network.getResponseBody. Costs one CDP call per matched request." }),
   ),
-  limit: Type.Optional(Type.Integer({ default: 50, minimum: 1, maximum: 500 })),
 });
 
-export const getNetworkLogTool = defineBrowserTool({
-  name: "browser_get_network_log",
-  label: "Browser Get Network Log",
+const BODY_BUDGET_MS = 5_000;
+const PER_BODY_CAP = 50_000;
+
+const renderNetworkMarkdown = (
+  records: ReadonlyArray<NetworkRecord>,
+  opts: { includeBodies: boolean; total: number; bufferOverflowed: boolean; expanded: boolean },
+): string => {
+  if (records.length === 0) {
+    if (opts.bufferOverflowed) return "_No matching requests. (Buffer overflowed since last drain — some events were dropped.)_";
+    return "_No matching requests captured yet._";
+  }
+
+  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 "";
+    const span = Math.max(...records.map((r) => r.requestStartedMs)) - Math.min(...records.map((r) => r.requestStartedMs));
+    return ` · ${(span / 1000).toFixed(1)}s window`;
+  })();
+
+  const headerLines: string[] = [
+    `**${records.length} requests** · ${failed} failed · ${formatBytes(totalBytes)}${showWindow}`,
+  ];
+  if (opts.bufferOverflowed) headerLines.push("⚠ buffer overflowed since last drain — older events dropped");
+  if (opts.total > records.length) headerLines.push(`(${records.length} of ${opts.total} matches shown — increase \`limit\` for more)`);
+
+  const compactRows = (records.length > 5 && !opts.expanded ? records.slice(0, 5) : records).map((r) => {
+    const status = r.failed ? "ERR" : r.status !== undefined ? String(r.status) : "—";
+    const warn = r.failed || (r.status !== undefined && r.status >= 500) ? " ⚠" : "";
+    const ms = r.durationMs !== undefined ? `${r.durationMs} ms` : "—";
+    const url = r.url.length > 60 ? r.url.slice(0, 57) + "…" : r.url;
+    return `\`${r.method.padEnd(4)} ${status.padStart(3)}\`  ${url}  _${ms}_${warn}`;
+  });
+
+  const rows = compactRows.join("\n");
+
+  if (!opts.expanded) {
+    const more = records.length > 5 ? `\n  … ${records.length - 5} more` : "";
+    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) => {
+      const status = r.failed ? "ERR" : r.status !== undefined ? String(r.status) : "—";
+      const ms = r.durationMs !== undefined ? String(r.durationMs) : "—";
+      const url = r.url.length > 80 ? r.url.slice(0, 77) + "…" : r.url;
+      return `| ${i + 1} | ${r.method} | ${status} | \`${url}\` | ${r.type} | ${ms} |`;
+    })
+    .join("\n");
+
+  let bodySections = "";
+  if (opts.includeBodies) {
+    const sections: string[] = [];
+    records.forEach((r, i) => {
+      if (r.body === undefined) return;
+      const sizes = `${r.requestBodySize} B → ${r.responseBodySize ?? 0} B`;
+      const status = r.failed ? "failed" : r.status ?? "?";
+      const header = `── #${i + 1} ${r.method} ${r.url} (${status}, ${r.durationMs ?? "?"} ms, ${r.type}, ${sizes}) ──`;
+      const bodyText = r.body === null ? "_(body unavailable — already GC'd by Chrome)_" : "```\n" + r.body + "\n```";
+      sections.push(`${header}\n\n${bodyText}`);
+    });
+    if (sections.length > 0) bodySections = "\n\n" + sections.join("\n\n");
+  }
+
+  return [headerLines.join("\n"), "", tableHeader, tableRows, bodySections].filter((s) => s !== "").join("\n");
+};
+
+type NetworkDetails = {
+  total: number;
+  returned: number;
+  bufferOverflowed: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  requests: ReadonlyArray<NetworkRecord>;
+  includeBodies: boolean;
+};
+
+export const networkRequestsTool = defineBrowserTool({
+  name: "browser_network_requests",
+  label: "Browser Network Requests",
   description:
-    "Read buffered Network.* CDP events. NOTE: in v0.3 the event stream is consumed internally by the session manager; this tool is a placeholder. Use browser_execute_js with PerformanceObserver as a workaround.",
-  promptSnippet: "Get buffered network events (DEPRECATED in v0.3 — use browser_execute_js with PerformanceObserver instead)",
+    "List recent network requests captured on the current tab since attach. Filter by URL pattern, method, status, resource type, or recency. Optionally include response bodies.",
+  promptSnippet: "Inspect recent network requests on the current page",
   promptGuidelines: [
-    "v0.3 routes CDP events through an internal AsyncIterable; a synchronous drain API isn't exposed yet.",
-    "For now, use browser_execute_js with PerformanceObserver, performance.getEntries(), or fetch interceptors.",
+    "Buffer is reset on tab switch — only requests on the current tab since attach are visible.",
+    'urlPattern is a substring; wrap in slashes for regex (e.g. "/\\\\.json$/").',
+    "includeResponseBodies:true costs an extra CDP call per matched request — use only when you need payloads.",
+    "If bufferOverflowed:true in the result, older events were dropped (capacity 500 records/tab).",
   ],
-  parameters: NetLogArgs,
-  async handler(args): Promise<Result<ToolOk, ToolErr>> {
-    return ok({
-      text: "browser_get_network_log: in v0.3 the CDP event stream is consumed by the session; use browser_execute_js with PerformanceObserver or performance.getEntries() to inspect network activity.",
-      details: {
-        deprecated: true,
-        eventTypes: args.eventTypes ?? null,
-        limit: args.limit ?? null,
-      },
+  parameters: NetworkRequestsArgs,
+
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const session = client.session();
+    const drained = session.drainNetworkBuffer({
+      ...(args.urlPattern !== undefined ? { urlPattern: args.urlPattern } : {}),
+      ...(args.methodFilter !== undefined ? { methodFilter: args.methodFilter } : {}),
+      ...(args.statusFilter !== undefined ? { statusFilter: args.statusFilter } : {}),
+      ...(args.resourceTypes !== undefined ? { resourceTypes: args.resourceTypes } : {}),
+      ...(args.sinceMs !== undefined ? { sinceMs: args.sinceMs } : {}),
+      limit: args.limit ?? 50,
     });
+
+    if (args.includeResponseBodies) {
+      const ac = new AbortController();
+      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 });
+        if (!bodyRes.success) {
+          r.body = null;
+          return;
+        }
+        const b = bodyRes.data as { body: string; base64Encoded?: boolean };
+        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;
+      });
+      await Promise.allSettled(fills);
+      clearTimeout(timer);
+    }
+
+    const text = renderNetworkMarkdown(drained.records, {
+      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
+    });
+    const trunc = await applyTruncation(text, "network");
+
+    const details: NetworkDetails = {
+      total: drained.total,
+      returned: drained.records.length,
+      bufferOverflowed: drained.bufferOverflowed,
+      truncated: trunc.wasTruncated,
+      requests: drained.records,
+      includeBodies: args.includeResponseBodies ?? false,
+    };
+    if (trunc.fullOutputPath !== undefined) details.fullOutputPath = trunc.fullOutputPath;
+
+    return ok({ text: trunc.text, details });
+  },
+
+  renderResult(result, expanded, theme) {
+    const details = result.details as NetworkDetails | undefined;
+    if (!details) return new Text(theme.fg("error", "network: no details"), 0, 0);
+
+    const md = renderNetworkMarkdown(details.requests, {
+      includeBodies: details.includeBodies && expanded,
+      total: details.total,
+      bufferOverflowed: details.bufferOverflowed,
+      expanded,
+    });
+    const tail = expanded
+      ? `\n\n${keyHint("app.tools.expand", "to collapse")}${details.fullOutputPath ? ` · full payload at \`${details.fullOutputPath}\`` : ""}`
+      : `\n\n${keyHint("app.tools.expand", "to expand")}`;
+
+    return new Markdown(md + tail, 0, 0, getMarkdownTheme());
   },
 });

package/src/domains/screenshot.ts

@@ -63,12 +63,15 @@ const resizeIfNeeded = async (
 export const screenshotTool = defineBrowserTool({
   name: "browser_screenshot",
   label: "Browser Screenshot",
-  description: "Capture the current page as PNG or JPEG. JPEG is 2-5x smaller — prefer it for photo-heavy pages.",
-  promptSnippet: "Capture a screenshot of the current page",
+  description:
+    "Capture the page as a JPEG/PNG image. NOT a default exploration tool. Use ONLY when (a) you need to verify visual properties (layout, color, spacing, rendered text legibility), or (b) browser_snapshot and browser_execute_js cannot answer your question. For understanding what's on the page use browser_snapshot. For specific element values use browser_execute_js. For click coordinates use the @(x,y) hints in browser_snapshot's outline.",
+  promptSnippet: "Capture a screenshot — visual verification only",
   promptGuidelines: [
-    "Use BEFORE clicks/scrolls to find coordinates; AFTER to verify the action.",
-    "Pass format='jpeg' with a quality (60-90) for smaller files on photo-heavy pages.",
-    "Set maxDim if the page is huge and you want to fit under LLM image-size limits.",
+    "DO NOT use as a default exploration tool. browser_snapshot is the default for understanding page structure — far cheaper and more reliable.",
+    "DO NOT use to find click coordinates. browser_snapshot already includes @(x,y) for every interactive element. If a target isn't there, use browser_execute_js with element.getBoundingClientRect().",
+    "DO use to verify visual rendering after an action: did the modal animate in correctly, did the chart render, are colors right, did the layout reflow as expected.",
+    "DO use as a debugging fallback when browser_execute_js or browser_snapshot return surprising results and you suspect the rendered page differs from the DOM.",
+    "format='jpeg' with quality 60-90 keeps screenshots small for photo-heavy pages. Use maxDim if the page is huge.",
   ],
   parameters: ScreenshotArgs,
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {

package/src/domains/snapshot.ts

@@ -0,0 +1,421 @@
+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 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";
+
+const SnapshotArgs = Type.Object({
+  includeScreenshot: Type.Optional(
+    Type.Boolean({ default: false, description: "Also capture a JPEG screenshot of the current viewport." }),
+  ),
+  interestingOnly: Type.Optional(
+    Type.Boolean({ default: true, description: "Drop nodes the AX engine marked uninteresting (generic containers, inline text, etc.)." }),
+  ),
+  maxNodes: Type.Optional(
+    Type.Integer({ default: 1000, minimum: 1, maximum: 5000, description: "Cap on slim nodes returned." }),
+  ),
+  format: Type.Optional(
+    Type.Union(
+      [Type.Literal("outline"), Type.Literal("json")],
+      { default: "outline", description: "'outline' = indented markdown bullet tree; 'json' = raw slim structure." },
+    ),
+  ),
+});
+
+// Raw shapes from CDP Accessibility.getFullAXTree. Cast at this boundary only.
+type AxValue = { value?: unknown };
+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 };
+
+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;
+  /** 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",
+]);
+
+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;
+};
+
+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 => {
+    for (const n of ns) {
+      counts.set(n.role, (counts.get(n.role) ?? 0) + 1);
+      walk(n.children);
+    }
+  };
+  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;
+  const buttons = counts.get("button") ?? 0;
+  const inputs = (counts.get("textbox") ?? 0) + (counts.get("combobox") ?? 0) + (counts.get("checkbox") ?? 0);
+  const links = counts.get("link") ?? 0;
+  const parts: string[] = [];
+  if (landmarks > 0) parts.push(`${landmarks} landmark${landmarks === 1 ? "" : "s"}`);
+  if (buttons > 0) parts.push(`${buttons} button${buttons === 1 ? "" : "s"}`);
+  if (inputs > 0) parts.push(`${inputs} input${inputs === 1 ? "" : "s"}`);
+  if (links > 0) parts.push(`${links} link${links === 1 ? "" : "s"}`);
+  return parts.join(" · ");
+};
+
+const renderOutline = (nodes: ReadonlyArray<SlimNode>): string => {
+  const lines: string[] = [];
+  const walk = (ns: ReadonlyArray<SlimNode>, depth: number): void => {
+    for (const n of ns) {
+      const indent = "  ".repeat(depth);
+      let line = `${indent}- ${n.role}`;
+      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 click coordinates for interactive nodes — agents can pass these
+      // straight to browser_click without a screenshot round-trip.
+      if (n.box && INTERACTIVE_ROLES.has(n.role)) {
+        line += ` @(${n.box.cx},${n.box.cy})`;
+      }
+      lines.push(line);
+      walk(n.children, depth + 1);
+    }
+  };
+  walk(nodes, 0);
+  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.
+ */
+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;
+};
+
+type SnapshotDetails = {
+  nodeCount: number;
+  truncated: boolean;
+  fullOutputPath?: string;
+  screenshotPath?: string;
+  url: string;
+  title: string;
+};
+
+export const snapshotTool = defineBrowserTool({
+  name: "browser_snapshot",
+  label: "Browser Snapshot",
+  description:
+    "DEFAULT tool for understanding what is on the page. Returns the structured accessibility tree (roles, names, states, hierarchy) plus click coordinates for every interactive element as @(x,y). Use this BEFORE deciding whether you need a screenshot — almost always sufficient on its own and far cheaper. Pair with browser_execute_js for surgical reads of specific element values.",
+  promptSnippet: "Get accessibility-tree snapshot of the current page (default for page inspection)",
+  promptGuidelines: [
+    "DEFAULT — use this whenever you need to know what's on a page, what's clickable, or how the page is structured.",
+    "Click coordinates come for free: every interactive element shows '@(x,y)' in the outline. Pass these straight to browser_click. NO screenshot round-trip needed.",
+    "DO NOT call browser_screenshot just to understand the page. This tool already gives you structure, labels, states, and click targets.",
+    "Pass includeScreenshot:true ONLY if you also need to verify visual rendering (rare).",
+    "format:'json' returns the raw slim structure (with `box` per node) for programmatic use; default 'outline' is human/LLM-readable.",
+  ],
+  parameters: SnapshotArgs,
+
+  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;
+
+    // 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);
+    if (targets.length > 0) {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), 1_500);
+      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),
+          };
+        }),
+      );
+      clearTimeout(timer);
+    }
+
+    const stripped = stripInternals(slim);
+    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 });
+      if (shot.success) {
+        const data = (shot.data as { data: string }).data;
+        shotPath = screenshotPath(client.namespace, "jpeg");
+        writeFileSync(shotPath, Buffer.from(data, "base64"));
+      }
+    }
+
+    const details: SnapshotDetails = {
+      nodeCount: countNodes(slim),
+      truncated: trunc.wasTruncated,
+      url: pageUrl,
+      title: pageTitle,
+    };
+    if (trunc.fullOutputPath !== undefined) details.fullOutputPath = trunc.fullOutputPath;
+    if (shotPath !== undefined) details.screenshotPath = shotPath;
+
+    return ok({ text: trunc.text, details: { ...details, summary: summarize(slim) } });
+  },
+
+  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 titleLine = details.title ? ` "${details.title}"` : "";
+    const summary = details.summary ?? "";
+    const screenshotNote = details.screenshotPath ? "screenshot attached" : "screenshot omitted";
+    const truncNote = details.truncated && details.fullOutputPath ? `\n\nFull tree at \`${details.fullOutputPath}\`` : "";
+
+    if (!expanded) {
+      const md = [
+        `**AX tree:** ${details.nodeCount} nodes · \`${details.url || "(no url)"}\``,
+        `${titleLine ? "  " + titleLine : ""}`,
+        summary ? `  • ${summary}` : "",
+        `  ${keyHint("app.tools.expand", "to expand")} · ${screenshotNote}`,
+      ].filter((l) => l !== "").join("\n");
+      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 : "";
+
+    const headerMd = [
+      `**AX tree:** ${details.nodeCount} nodes · \`${details.url || "(no url)"}\``,
+      titleLine ? `  ${titleLine}` : "",
+      "",
+      "```",
+      treeText,
+      "```",
+      truncNote,
+      "",
+      `${keyHint("app.tools.expand", "to collapse")}`,
+    ].filter((l) => l !== "").join("\n");
+
+    const treeBlock = new Markdown(headerMd, 0, 0, getMarkdownTheme());
+
+    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");
+      const imageTheme: ImageTheme = { fallbackColor: (s: string) => theme.fg("dim", s) };
+      const image = new Image(b64, "image/jpeg", imageTheme, {
+        maxWidthCells: 80,
+        maxHeightCells: 24,
+        filename: details.screenshotPath,
+      });
+      const safeImage = {
+        invalidate: () => image.invalidate(),
+        render: (width: number) =>
+          image.render(width).map((line) => (visibleWidth(line) > width ? truncateToWidth(line, width) : line)),
+      };
+      const container = new Container();
+      container.addChild(treeBlock);
+      container.addChild(safeImage);
+      return container;
+    } catch {
+      return treeBlock;
+    }
+  },
+});