pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/domains/network.ts

@@ -0,0 +1,301 @@
+import { Type } from "typebox";
+import { Markdown, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { type Result, err, ok } from "../util/result";
+import { formatBytes } from "../util/truncate";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+import { applyTruncation } from "../util/truncate";
+import { asArrayOf, asBoolean, asNumber, asRecord, asString } from "../util/guards";
+import type { NetworkRecord } from "../cdp/network-buffer";
+
+const HttpGetArgs = Type.Object({
+  url: Type.String({ description: "URL to GET" }),
+  headers: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Optional HTTP headers" })),
+  timeout: Type.Optional(
+    Type.Number({ default: 20, minimum: 1, maximum: 120, description: "Total seconds (covers headers AND body)" }),
+  ),
+});
+
+export const httpGetTool = defineBrowserTool({
+  name: "browser_http_get",
+  label: "Browser HTTP GET",
+  description:
+    "Fetch a URL outside the browser (faster than browser_navigate for APIs and static pages). Timeout covers headers AND body read.",
+  promptSnippet: "HTTP GET (outside browser; for APIs/static pages)",
+  promptGuidelines: [
+    "Faster than navigate+execute_js for JSON/HTML APIs.",
+    "No JS rendering — for SPAs use browser_navigate.",
+  ],
+  parameters: HttpGetArgs,
+  concurrency: "parallel",
+  ensureAlive: false,
+  async handler(args): Promise<Result<ToolOk, ToolErr>> {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), (args.timeout ?? 20) * 1000);
+    try {
+      const fetchInit: RequestInit = { signal: ac.signal };
+      if (args.headers !== undefined) fetchInit.headers = args.headers;
+      const res = await fetch(args.url, fetchInit);
+      const body = await res.text();
+      clearTimeout(timer);
+      const ct = res.headers.get("content-type") ?? "";
+      const truncated = await applyTruncation(body, "http");
+      return ok({
+        text: `HTTP ${res.status} ${ct}\n${truncated.text}`,
+        details: truncated.fullOutputPath !== undefined
+          ? { status: res.status, contentType: ct, length: body.length, fullOutputPath: truncated.fullOutputPath, wasTruncated: truncated.wasTruncated }
+          : { status: res.status, contentType: ct, length: body.length, wasTruncated: truncated.wasTruncated },
+      });
+    } catch (e) {
+      clearTimeout(timer);
+      const msg = e instanceof Error ? e.message : String(e);
+      const kind: ToolErr["kind"] = msg.toLowerCase().includes("abort") ? "timeout" : "io_error";
+      return err({ kind, message: msg });
+    }
+  },
+});
+
+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." }),
+  ),
+});
+
+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 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}`;
+  }
+
+  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;
+};
+
+const asNetworkRecord = (v: unknown): NetworkRecord | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const method = asString(o["method"]);
+  const url = asString(o["url"]);
+  const type = asString(o["type"]);
+  if (method === undefined || url === undefined || type === undefined) return undefined;
+  const status = asNumber(o["status"]);
+  const statusText = asString(o["statusText"]);
+  const mimeType = asString(o["mimeType"]);
+  const durationMs = asNumber(o["durationMs"]);
+  const responseBodySize = asNumber(o["responseBodySize"]);
+  const failed = asBoolean(o["failed"]);
+  const errorText = asString(o["errorText"]);
+  const bodyRaw = o["body"];
+  const body = typeof bodyRaw === "string" || bodyRaw === null ? bodyRaw : undefined;
+  return {
+    requestId: asString(o["requestId"]) ?? "",
+    method,
+    url,
+    type,
+    requestStartedMs: asNumber(o["requestStartedMs"]) ?? 0,
+    requestBodySize: asNumber(o["requestBodySize"]) ?? 0,
+    ...(status !== undefined ? { status } : {}),
+    ...(statusText !== undefined ? { statusText } : {}),
+    ...(mimeType !== undefined ? { mimeType } : {}),
+    ...(durationMs !== undefined ? { durationMs } : {}),
+    ...(responseBodySize !== undefined ? { responseBodySize } : {}),
+    ...(failed !== undefined ? { failed } : {}),
+    ...(errorText !== undefined ? { errorText } : {}),
+    ...(body !== undefined ? { body } : {}),
+  };
+};
+
+const asNetworkDetails = (v: unknown): NetworkDetails | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const requests = asArrayOf(o["requests"], asNetworkRecord);
+  if (requests === undefined) return undefined;
+  const fullOutputPath = asString(o["fullOutputPath"]);
+  return {
+    total: asNumber(o["total"]) ?? requests.length,
+    returned: asNumber(o["returned"]) ?? requests.length,
+    bufferOverflowed: asBoolean(o["bufferOverflowed"]) ?? false,
+    truncated: asBoolean(o["truncated"]) ?? false,
+    requests,
+    includeBodies: asBoolean(o["includeBodies"]) ?? false,
+    ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
+  };
+};
+
+export const networkRequestsTool = defineBrowserTool({
+  name: "browser_network_requests",
+  label: "Browser Network Requests",
+  description:
+    "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: [
+    "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: NetworkRequestsArgs,
+  concurrency: "parallel",
+
+  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 cdpCall(client, "Network.getResponseBody", { requestId: r.requestId });
+        if (!bodyRes.success) {
+          r.body = null;
+          return;
+        }
+        const b = bodyRes.data;
+        let body = b.base64Encoded ? Buffer.from(b.body, "base64").toString("utf8") : b.body;
+        if (body.length > PER_BODY_CAP) body = body.slice(0, PER_BODY_CAP) + "…";
+        r.body = body;
+      });
+      await Promise.allSettled(fills);
+      clearTimeout(timer);
+    }
+
+    const text = renderNetworkMarkdown(drained.records, {
+      includeBodies: args.includeResponseBodies ?? false,
+      total: drained.total,
+      bufferOverflowed: drained.bufferOverflowed,
+      expanded: true,
+    });
+    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 = asNetworkDetails(result.details);
+    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/extensions/browser-harness/domains/page.ts

@@ -0,0 +1,154 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { evalJs } from "./cdp-call";
+import { safeJs } from "../util/js-template";
+
+const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+
+export const pageInfoTool = defineBrowserTool({
+  name: "browser_page_info",
+  label: "Browser Page Info",
+  description:
+    "Get current page state: URL, title, viewport size, scroll position, page dimensions. If a JS dialog is open, returns dialog info instead.",
+  promptSnippet: "Get current page URL, title, viewport, and scroll position",
+  promptGuidelines: [
+    "Use browser_page_info to quickly check what page you're on and whether a JS dialog is blocking interaction.",
+    "If browser_page_info returns a dialog, use browser_handle_dialog before any other browser actions.",
+    "JS dialogs freeze the page's JS thread, so no other interaction works until the dialog is handled.",
+    "browser_page_info auto-detects alert, confirm, prompt, and beforeunload dialogs.",
+  ],
+  parameters: Type.Object({}),
+  concurrency: "parallel",
+  async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await client.pageInfo();
+    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    if ("dialog" in r.data) {
+      const d = r.data.dialog;
+      return ok({
+        text: `⚠️  DIALOG OPEN: ${d.type}\nMessage: ${d.message}${d.defaultPrompt ? `\nDefault: ${d.defaultPrompt}` : ""}\n\nUse browser_handle_dialog to accept or dismiss.`,
+        details: { dialog: d },
+      });
+    }
+    const i = r.data;
+    return ok({
+      text: `URL: ${i.url}\nTitle: ${i.title}\nViewport: ${i.width}x${i.height}\nScroll: (${i.scrollX}, ${i.scrollY})\nPage size: ${i.pageWidth}x${i.pageHeight}`,
+      details: { ...i },
+    });
+  },
+});
+
+const WaitArgs = Type.Object({
+  seconds: Type.Number({ minimum: 0, maximum: 60, description: "Seconds to wait" }),
+});
+
+export const waitTool = defineBrowserTool({
+  name: "browser_wait",
+  label: "Browser Wait",
+  description: "Wait N seconds before continuing.",
+  promptSnippet: "Wait N seconds",
+  promptGuidelines: ["Use sparingly — prefer browser_wait_for_load when waiting for a page load."],
+  parameters: WaitArgs,
+  concurrency: "parallel",
+  async handler(args, { signal }): Promise<Result<ToolOk, ToolErr>> {
+    try {
+      await sleep(Math.round(args.seconds * 1000), signal);
+      return ok({ text: `Waited ${args.seconds}s` });
+    } catch (e) {
+      return err({ kind: "internal", message: e instanceof Error ? e.message : String(e) });
+    }
+  },
+});
+
+const WaitForLoadArgs = Type.Object({
+  timeout: Type.Optional(Type.Number({ default: 15, minimum: 1, maximum: 120, description: "Max seconds to wait. Default: 15." })),
+});
+
+export const waitForLoadTool = defineBrowserTool({
+  name: "browser_wait_for_load",
+  label: "Browser Wait For Load",
+  description:
+    "Poll until the current page reports document.readyState === 'complete'. Returns a typed timeout error if the deadline elapses.",
+  promptSnippet: "Wait for the page to finish loading",
+  promptGuidelines: [
+    "Call after browser_navigate / browser_open_urls before extracting data.",
+    "Returns when readyState becomes 'complete' OR the timeout elapses.",
+  ],
+  parameters: WaitForLoadArgs,
+  concurrency: "serialized",
+  async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
+    const timeoutMs = (args.timeout ?? 15) * 1000;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
+      const r = await evalJs(client, safeJs`document.readyState`);
+      if (r.success && r.data === "complete") {
+        const ms = Date.now() - start;
+        return ok({ text: `Page loaded in ${Math.round(ms / 100) / 10}s`, details: { ms } });
+      }
+      await new Promise((res) => setTimeout(res, 50));
+    }
+    return err({ kind: "timeout", message: `Page did not finish loading in ${args.timeout ?? 15}s` });
+  },
+});
+
+const WaitForArgs = Type.Object({
+  selector: Type.Optional(Type.String({ description: "CSS selector to wait for (or wait to disappear with gone:true)" })),
+  text: Type.Optional(Type.String({ description: "Wait until this text appears anywhere in document.body" })),
+  gone: Type.Optional(Type.Boolean({ default: false, description: "If true with a selector, wait until it is absent instead of present" })),
+  timeout: Type.Optional(Type.Number({ default: 5, minimum: 1, maximum: 60, description: "Max seconds to wait. Default: 5." })),
+});
+
+export const waitForTool = defineBrowserTool({
+  name: "browser_wait_for",
+  label: "Browser Wait For",
+  description:
+    "Poll until a condition holds: a selector appears (or disappears with gone:true), or text appears in the page. Returns a typed timeout error if the deadline elapses. Use to wait for SPA content to render before interacting.",
+  promptSnippet: "Wait for an element or text to appear (or an element to disappear)",
+  promptGuidelines: [
+    "Use before browser_fill / browser_click on dynamic pages so you act after the element renders.",
+    "Provide selector (default: wait until present; gone:true: wait until absent) or text.",
+    "Returns a typed timeout error if the condition isn't met within the timeout.",
+  ],
+  parameters: WaitForArgs,
+  concurrency: "parallel",
+  async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
+    if (args.selector === undefined && args.text === undefined) {
+      return err({ kind: "invalid_state", message: "Provide a selector or text to wait for." });
+    }
+    const gone = args.gone ?? false;
+    const timeoutMs = (args.timeout ?? 5) * 1000;
+    const expr =
+      args.selector !== undefined
+        ? safeJs`(() => { const found = !!document.querySelector(${args.selector}); return ${gone} ? !found : found; })()`
+        : safeJs`(() => { const t = document.body ? document.body.innerText : ""; return t.includes(${args.text}); })()`;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
+      const r = await evalJs(client, expr);
+      if (r.success && r.data === true) {
+        const ms = Date.now() - start;
+        const what = args.selector !== undefined ? `${args.selector}${gone ? " gone" : ""}` : `text "${args.text}"`;
+        return ok({ text: `Condition met (${what}) in ${Math.round(ms / 100) / 10}s`, details: { ms } });
+      }
+      await sleep(50, signal);
+    }
+    const what = args.selector !== undefined ? `${args.selector}${gone ? " to disappear" : ""}` : `text "${args.text}"`;
+    return err({ kind: "timeout", message: `Timed out after ${args.timeout ?? 5}s waiting for ${what}` });
+  },
+});

package/extensions/browser-harness/domains/readpage/read-page.ts

@@ -0,0 +1,174 @@
+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 { cdpCallBrowser, evalJs } from "../cdp-call";
+import {
+  closeIsolatedTab,
+  evalInIsolatedTab,
+  isJsonText,
+  type IsolatedTab,
+  navigateIsolatedTab,
+  openIsolatedTab,
+  waitForIsolatedLoad,
+} from "../isolated-tab";
+import { renderExpandableText } from "../render";
+import { extractReadable, type PageCapture, type ReadablePage } from "./readability";
+
+const LOAD_TIMEOUT_MS = 15_000;
+
+const ReadPageArgs = Type.Object({
+  url: Type.Optional(Type.String({ description: "URL to open in an isolated tab, read, then close." })),
+  targetId: Type.Optional(
+    Type.String({ description: "Read an already-open tab this session owns instead of opening a URL." }),
+  ),
+});
+
+const ContentBlockSchema = Type.Object({
+  kind: Type.Union([
+    Type.Literal("paragraph"),
+    Type.Literal("heading"),
+    Type.Literal("listitem"),
+    Type.Literal("blockquote"),
+    Type.Literal("other"),
+  ]),
+  text: Type.String(),
+  linkTextLength: Type.Number(),
+  inBoilerplate: Type.Boolean(),
+});
+
+const PageCaptureSchema = Type.Object({
+  url: Type.String(),
+  title: Type.String(),
+  blocks: Type.Array(ContentBlockSchema),
+  bodyText: Type.String(),
+});
+
+const pageCaptureValidator = Compile(PageCaptureSchema);
+
+const BODY_TEXT_LIMIT = 20_000;
+
+const buildPageCaptureExpr = (): string => `
+  (() => {
+    const BOILERPLATE = new Set(['NAV', 'HEADER', 'FOOTER', 'ASIDE']);
+    const inBoilerplate = (el) => {
+      for (let n = el; n; n = n.parentElement) {
+        if (BOILERPLATE.has(n.tagName)) return true;
+        const role = n.getAttribute && n.getAttribute('role');
+        if (role === 'navigation' || role === 'banner' || role === 'contentinfo') return true;
+      }
+      return false;
+    };
+    const kindOf = (tag) => {
+      if (/^H[1-6]$/.test(tag)) return 'heading';
+      if (tag === 'LI') return 'listitem';
+      if (tag === 'BLOCKQUOTE') return 'blockquote';
+      if (tag === 'P') return 'paragraph';
+      return 'other';
+    };
+    const selector = 'p, h1, h2, h3, h4, h5, h6, li, blockquote';
+    const root = document.querySelector('article, main, [role=main]') || document.body;
+    const blocks = [];
+    for (const el of root.querySelectorAll(selector)) {
+      const text = (el.innerText || '').replace(/\\s+/g, ' ').trim();
+      if (!text) continue;
+      let linkTextLength = 0;
+      for (const a of el.querySelectorAll('a')) linkTextLength += (a.innerText || '').length;
+      blocks.push({ kind: kindOf(el.tagName), text, linkTextLength, inBoilerplate: inBoilerplate(el) });
+    }
+    const bodyText = (document.body.innerText || '').replace(/\\n{3,}/g, '\\n\\n').slice(0, ${BODY_TEXT_LIMIT});
+    return JSON.stringify({ url: location.href, title: document.title, blocks, bodyText });
+  })()
+`;
+
+const toPageCapture = (raw: unknown): PageCapture | undefined => {
+  if (typeof raw === "string") {
+    const parsed = parseJson(raw, pageCaptureValidator);
+    return parsed.success ? parsed.data : undefined;
+  }
+  return pageCaptureValidator.Check(raw) ? raw : undefined;
+};
+
+const captureToResult = async (raw: unknown): Promise<Result<ToolOk, ToolErr>> => {
+  const parsed = toPageCapture(raw);
+  if (parsed === undefined) return err({ kind: "internal", message: "page capture returned an unexpected shape" });
+  const page: ReadablePage = extractReadable(parsed);
+  const header = `# ${page.title}\n${page.url}\n(${page.wordCount} words)\n\n`;
+  const truncated = await applyTruncation(header + page.text, "readpage");
+  const summary = `${page.title} · ${page.wordCount} words`;
+  return ok({
+    text: truncated.text,
+    details: {
+      title: page.title,
+      url: page.url,
+      wordCount: page.wordCount,
+      render: {
+        summary,
+        body: page.text,
+        ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+      },
+      ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+    },
+  });
+};
+
+const readOpenedUrl = async (
+  client: Parameters<typeof openIsolatedTab>[0],
+  url: string,
+  signal: AbortSignal | undefined,
+): Promise<Result<ToolOk, ToolErr>> => {
+  const opened = await openIsolatedTab(client);
+  if (!opened.success) return err(opened.error);
+  const tab: IsolatedTab = opened.data;
+  try {
+    const navigated = await navigateIsolatedTab(client, tab, url);
+    if (!navigated.success) return err(navigated.error);
+    const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
+    if (!loaded.success) return err(loaded.error);
+    const captured = await evalInIsolatedTab(client, tab, buildPageCaptureExpr(), isJsonText);
+    if (!captured.success) return err(captured.error);
+    return captureToResult(captured.data);
+  } finally {
+    await closeIsolatedTab(client, tab);
+  }
+};
+
+const readOwnedTab = async (
+  client: Parameters<typeof openIsolatedTab>[0],
+  targetId: string,
+): Promise<Result<ToolOk, ToolErr>> => {
+  if (!client.owns(targetId)) {
+    return err({ kind: "invalid_state", message: `Tab ${targetId} is not owned by this session.` });
+  }
+  const attached = await cdpCallBrowser(client, "Target.attachToTarget", { targetId, flatten: true });
+  if (!attached.success) return attached;
+  const sessionId = attached.data.sessionId;
+  const captured = await evalJs(client, buildPageCaptureExpr(), sessionId);
+  if (!captured.success) return captured;
+  return captureToResult(captured.data);
+};
+
+export const readPageTool = defineBrowserTool({
+  name: "browser_read_page",
+  label: "Browser Read Page",
+  description:
+    "Read a page as clean article text — main content with nav/ads/boilerplate stripped. Pass a url (opened in an isolated tab, read, then closed) or a targetId of an owned tab. Reader-mode counterpart to browser_web_search.",
+  promptSnippet: "Read a page's main content as clean text",
+  promptGuidelines: [
+    "Pass url to read an arbitrary page (opened + closed in its own tab, never disturbing your current tab), or targetId to read an already-open owned tab.",
+    "Returns readable main-article text — use this over browser_snapshot/browser_execute_js when you want an article's content for reading or research.",
+    "Boilerplate-heavy or structure-less pages fall back to bounded body text rather than erroring.",
+  ],
+  parameters: ReadPageArgs,
+  concurrency: "parallel",
+  async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
+    if (args.url !== undefined && args.url.length > 0) return readOpenedUrl(client, args.url, signal);
+    if (args.targetId !== undefined && args.targetId.length > 0) return readOwnedTab(client, args.targetId);
+    return err({ kind: "invalid_state", message: "provide either url or targetId" });
+  },
+  renderResult(result, expanded, theme) {
+    return renderExpandableText("read_page", result, expanded, theme);
+  },
+});