pi-browser-harness 0.8.3 → 0.9.0

package/src/domains/isolated-tab.ts

@@ -0,0 +1,121 @@
+/**
+ * Isolated-attach tab lifecycle (ADR-0002 v1). Opens a harness-owned tab,
+ * attaches to it by its own CDP sessionId, and drives it via callOnTarget /
+ * evaluateJs(expr, sid) WITHOUT ever touching the global "current" tab — so a
+ * search or page-read never disturbs the tab the user is looking at, even when
+ * several subagents run concurrently.
+ *
+ * Mirrors the create/attach sequence in browser_open_urls
+ * (src/domains/navigate.ts:84-139). Every page evaluation is bounded by a
+ * timeout, so a JS dialog on the (uninstrumented) isolated tab surfaces as a
+ * typed timeout rather than hanging — see the dialog-hang caveat in plan.md.
+ */
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import { safeJs } from "../util/js-template";
+import { bindHarnessWindowId } from "../cdp/window-binding";
+import type { ToolErr } from "../util/tool";
+
+/** A tab attached by its own sessionId, ready to drive via callOnTarget. */
+export type IsolatedTab = {
+  readonly targetId: string;
+  readonly sessionId: string;
+};
+
+const EVAL_TIMEOUT_MS = 15_000;
+const READY_POLL_INTERVAL_MS = 50;
+
+const toToolErr = (message: string, kind: ToolErr["kind"] = "cdp_error"): ToolErr => ({ kind, message });
+
+/**
+ * Open a harness-owned tab and attach to it, returning its targetId + private
+ * sessionId. Does not navigate. The caller MUST `closeIsolatedTab` when done.
+ */
+export const openIsolatedTab = async (client: BrowserClient): Promise<Result<IsolatedTab, ToolErr>> => {
+  const hw = client.ownership().harnessWindow();
+  const createParams: Record<string, unknown> = hw
+    ? { url: "about:blank", openerId: hw }
+    : { url: "about:blank", newWindow: true };
+
+  const created = await client.session().callBrowser("Target.createTarget", createParams);
+  if (!created.success) return err(toToolErr(created.error.message));
+  const { targetId } = created.data as { targetId: string };
+
+  if (createParams["newWindow"]) {
+    client.ownership().setHarnessWindow(targetId);
+    await bindHarnessWindowId(client, targetId);
+  }
+  client.ownership().add(targetId);
+
+  const attached = await client.session().callBrowser("Target.attachToTarget", { targetId, flatten: true });
+  if (!attached.success) {
+    await client.closeTab(targetId);
+    return err(toToolErr(attached.error.message));
+  }
+  const { sessionId } = attached.data as { sessionId: string };
+
+  const enabled = await client.session().callOnTarget("Page.enable", {}, sessionId);
+  if (!enabled.success) {
+    await client.closeTab(targetId);
+    return err(toToolErr(enabled.error.message));
+  }
+  return ok({ targetId, sessionId });
+};
+
+/** Navigate an isolated tab to a URL (does not wait for load). */
+export const navigateIsolatedTab = async (
+  client: BrowserClient,
+  tab: IsolatedTab,
+  url: string,
+): Promise<Result<void, ToolErr>> => {
+  const nav = await client.session().callOnTarget("Page.navigate", { url }, tab.sessionId, {
+    timeoutMs: EVAL_TIMEOUT_MS,
+  });
+  if (!nav.success) return err(toToolErr(nav.error.message));
+  return ok(undefined);
+};
+
+/** Poll the isolated tab until document.readyState === 'complete' or timeout. */
+export const waitForIsolatedLoad = async (
+  client: BrowserClient,
+  tab: IsolatedTab,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<Result<void, ToolErr>> => {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (signal?.aborted) return err(toToolErr("aborted", "internal"));
+    const r = await client.evaluateJs(safeJs`document.readyState`, tab.sessionId);
+    if (r.success && r.data === "complete") return ok(undefined);
+    await new Promise((res) => setTimeout(res, READY_POLL_INTERVAL_MS));
+  }
+  return err(toToolErr(`page did not finish loading in ${Math.round(timeoutMs / 1000)}s`, "timeout"));
+};
+
+/**
+ * Evaluate an expression in the isolated tab and return the raw value. Bounds
+ * the eval with a timeout so a blocking dialog cannot hang the tool.
+ */
+export const evalInIsolatedTab = async (
+  client: BrowserClient,
+  tab: IsolatedTab,
+  expression: string,
+): Promise<Result<unknown, ToolErr>> => {
+  const r = await client.session().callOnTarget(
+    "Runtime.evaluate",
+    { expression, returnByValue: true, awaitPromise: true },
+    tab.sessionId,
+    { timeoutMs: EVAL_TIMEOUT_MS },
+  );
+  if (!r.success) return err(toToolErr(r.error.message, r.error.kind === "timeout" ? "timeout" : "cdp_error"));
+  const data = r.data as { result?: { value?: unknown }; exceptionDetails?: unknown };
+  if (data.exceptionDetails) {
+    return err(toToolErr(`page evaluation failed: ${JSON.stringify(data.exceptionDetails)}`));
+  }
+  return ok(data.result?.value);
+};
+
+/** Close an isolated tab and drop its ownership. Best-effort; never throws. */
+export const closeIsolatedTab = async (client: BrowserClient, tab: IsolatedTab): Promise<void> => {
+  await client.closeTab(tab.targetId).catch(() => {});
+};

package/src/domains/navigate.ts

@@ -4,6 +4,7 @@ import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { applyTruncation } from "../util/truncate";
 import { safeJs } from "../util/js-template";
+import { bindHarnessWindowId } from "../cdp/window-binding";
 
 const NavigateArgs = Type.Object({
   url: Type.String({ description: "Full URL to navigate to (e.g. https://github.com)" }),
@@ -75,7 +76,7 @@ export const openUrlsTool = defineBrowserTool({
   description: "Open multiple URLs in parallel new tabs. Returns per-URL outcomes.",
   promptSnippet: "Open multiple URLs in new tabs (parallel)",
   promptGuidelines: [
-    "Use after web_search to open citations in parallel.",
+    "Use after browser_web_search to open citations in parallel.",
     "After opening, use browser_list_tabs / browser_switch_tab to navigate, then browser_snapshot to inspect each tab.",
     "Use browser_wait_for_load on a tab before extracting data from SPAs.",
   ],
@@ -83,17 +84,31 @@ export const openUrlsTool = defineBrowserTool({
   renderCall: (a) => new Text(`🌐 Opening ${a.urls.length} URL${a.urls.length !== 1 ? "s" : ""}…`, 0, 0),
   async handler(args, { client, onUpdate }): Promise<Result<ToolOk, ToolErr>> {
     const total = args.urls.length;
-    // Phase 1: create tabs in parallel.  Own them so they appear in
-    // browser_list_tabs scope:'owned' and group in the harness window.
-    const hw = client.ownership().harnessWindow();
-    const created = await Promise.all(args.urls.map(async (url): Promise<TabResult> => {
-      const params: Record<string, unknown> = { url: "about:blank" };
-      if (hw) params["openerId"] = hw;
-      else params["newWindow"] = true;
-      const r = await client.session().callBrowser("Target.createTarget", params);
+    // Phase 1: create tabs. All must land in ONE window. If the harness window
+    // already exists, open every url as its child in parallel. If it doesn't
+    // (fresh/closed), create the FIRST url as a new dedicated window (binding
+    // its windowId) and open the rest as children of it — a parallel
+    // newWindow:true per url would otherwise scatter tabs across N windows.
+    let seed = client.ownership().harnessWindow();
+    let seedResult: TabResult | undefined;
+    if (!seed) {
+      const url0 = args.urls[0];
+      if (url0 === undefined) return err({ kind: "invalid_state", message: "no URLs provided" });
+      const r0 = await client.session().callBrowser("Target.createTarget", { url: "about:blank", newWindow: true });
+      if (!r0.success) return err({ kind: "cdp_error", message: r0.error.message });
+      seed = (r0.data as { targetId: string }).targetId;
+      client.ownership().setHarnessWindow(seed);
+      await bindHarnessWindowId(client, seed);
+      client.ownership().add(seed);
+      seedResult = { url: url0, targetId: seed, ok: true };
+    }
+    const seededWindow = seed;
+    const created = await Promise.all(args.urls.map(async (url, i): Promise<TabResult> => {
+      // Reuse the seed tab (created above) for the first url instead of duplicating it.
+      if (i === 0 && seedResult) return seedResult;
+      const r = await client.session().callBrowser("Target.createTarget", { url: "about:blank", openerId: seededWindow });
       if (!r.success) return { url, targetId: "", ok: false, error: r.error.message };
       const c = r.data as { targetId: string };
-      if (params["newWindow"]) client.ownership().setHarnessWindow(c.targetId);
       client.ownership().add(c.targetId);
       return { url, targetId: c.targetId, ok: true };
     }));

package/src/domains/readpage/capture.ts

@@ -0,0 +1,46 @@
+/**
+ * The JavaScript source evaluated in a loaded page to capture candidate content
+ * blocks + metadata for the pure readability extractor (readability.ts). Crosses
+ * the CDP boundary via Runtime.evaluate (returnByValue) and returns a JSON
+ * string shaped like PageCapture.
+ *
+ * The DOM walk lives here (unavoidable); all scoring/selection is pure and lives
+ * in readability.ts, so the decision logic stays unit-testable.
+ */
+
+/** Max bytes of body-text fallback captured for thin/structure-less pages. */
+const BODY_TEXT_LIMIT = 20_000;
+
+/** Build the capture expression. No interpolated values ⇒ no injection surface. */
+export 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 });
+  })()
+`;

package/src/domains/readpage/read-page.ts

@@ -0,0 +1,119 @@
+import { Type } from "typebox";
+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,
+  type IsolatedTab,
+  navigateIsolatedTab,
+  openIsolatedTab,
+  waitForIsolatedLoad,
+} from "../isolated-tab";
+import { renderExpandableText } from "../render";
+import { buildPageCaptureExpr } from "./capture";
+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 isPageCapture = (value: unknown): value is PageCapture => {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v["url"] === "string" && typeof v["title"] === "string" && Array.isArray(v["blocks"]) && typeof v["bodyText"] === "string";
+};
+
+const safeParse = (text: string): unknown => {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+};
+
+const captureToResult = async (raw: unknown): Promise<Result<ToolOk, ToolErr>> => {
+  const parsed = typeof raw === "string" ? safeParse(raw) : raw;
+  if (!isPageCapture(parsed)) 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());
+    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 client.session().callBrowser("Target.attachToTarget", { targetId, flatten: true });
+  if (!attached.success) return err({ kind: "cdp_error", message: attached.error.message });
+  const sessionId = (attached.data as { sessionId: string }).sessionId;
+  const captured = await client.evaluateJs(buildPageCaptureExpr(), sessionId);
+  if (!captured.success) return err({ kind: "cdp_error", message: captured.error.message });
+  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,
+  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);
+  },
+});

package/src/domains/readpage/readability.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure reader-mode extraction — no CDP, no DOM. The in-page script
+ * (see capture.ts) serializes candidate content blocks; these pure functions
+ * score them and assemble clean article text, so the selection logic is
+ * unit-testable against saved fixtures (test/deep-research/readability-test.ts).
+ *
+ * Dependency-free by design (no jsdom / Readability): the harness ships no new
+ * runtime deps. The heuristic favors blocks with high text density and low link
+ * density, which is what separates article body from nav/ads/boilerplate.
+ */
+
+/** One candidate content block captured in-page. */
+export type ContentBlock = {
+  /** Semantic tag: paragraph | heading | listitem | blockquote | other. */
+  readonly kind: "paragraph" | "heading" | "listitem" | "blockquote" | "other";
+  readonly text: string;
+  /** Chars of text that sit inside <a> tags — high ratio ⇒ nav/menu, not prose. */
+  readonly linkTextLength: number;
+  /** True when an ancestor is nav/header/footer/aside — structural boilerplate. */
+  readonly inBoilerplate: boolean;
+};
+
+/** The JSON payload capture.ts returns from the page. */
+export type PageCapture = {
+  readonly url: string;
+  readonly title: string;
+  readonly blocks: ReadonlyArray<ContentBlock>;
+  /** Bounded innerText fallback when block extraction finds nothing usable. */
+  readonly bodyText: string;
+};
+
+/** The tool's public output shape. */
+export type ReadablePage = {
+  readonly title: string;
+  readonly url: string;
+  readonly text: string;
+  readonly wordCount: number;
+};
+
+const MIN_PARAGRAPH_CHARS = 25;
+const MAX_LINK_DENSITY = 0.5;
+const MIN_ARTICLE_WORDS = 40;
+
+const linkDensity = (block: ContentBlock): number => {
+  if (block.text.length === 0) return 1;
+  return block.linkTextLength / block.text.length;
+};
+
+/** A block is article prose if it is substantive, text-dense, and not chrome. */
+const isArticleBlock = (block: ContentBlock): boolean => {
+  if (block.inBoilerplate) return false;
+  if (linkDensity(block) > MAX_LINK_DENSITY) return false;
+  if (block.kind === "heading" || block.kind === "blockquote" || block.kind === "listitem") {
+    return block.text.trim().length > 0;
+  }
+  return block.text.trim().length >= MIN_PARAGRAPH_CHARS;
+};
+
+const render = (block: ContentBlock): string => {
+  const text = block.text.trim();
+  if (block.kind === "heading") return `\n## ${text}\n`;
+  if (block.kind === "listitem") return `- ${text}`;
+  if (block.kind === "blockquote") return `> ${text}`;
+  return text;
+};
+
+const wordCountOf = (text: string): number => {
+  const trimmed = text.trim();
+  return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+};
+
+/**
+ * Assemble readable article text from a page capture. Keeps text-dense,
+ * non-boilerplate blocks; falls back to the bounded body text when the article
+ * is too thin (e.g. a page with no clear content structure).
+ */
+export const extractReadable = (capture: PageCapture): ReadablePage => {
+  const articleText = capture.blocks.filter(isArticleBlock).map(render).join("\n\n").replace(/\n{3,}/g, "\n\n").trim();
+
+  const useFallback = wordCountOf(articleText) < MIN_ARTICLE_WORDS;
+  const text = useFallback ? capture.bodyText.trim() : articleText;
+
+  return {
+    title: capture.title.trim(),
+    url: capture.url,
+    text,
+    wordCount: wordCountOf(text),
+  };
+};

package/src/domains/render.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared TUI renderer for text-heavy tool output (browser_web_search,
+ * browser_read_page). Gives the native pi expand/collapse (Ctrl+O) behavior:
+ * a compact preview by default, the full body when expanded — mirroring the
+ * pattern in browser_execute_js (src/domains/js.ts:81-109).
+ *
+ * The full text always goes to the LLM via ToolOk.text; this only governs the
+ * human-facing TUI view.
+ */
+import { Markdown, Text } from "@mariozechner/pi-tui";
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+
+const COMPACT_PREVIEW_LINES = 6;
+
+/** Structured payload a text-heavy tool stores so renderResult can rebuild views. */
+export type ExpandableText = {
+  /** One-line summary shown above the body in both states (e.g. "5 results · google"). */
+  readonly summary: string;
+  /** The full rendered body (markdown/plain). */
+  readonly body: string;
+  /** Path to the on-disk full output when the LLM text was truncated, if any. */
+  readonly fullOutputPath?: string;
+};
+
+const isExpandableText = (value: unknown): value is ExpandableText => {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v["summary"] === "string" && typeof v["body"] === "string";
+};
+
+const extractRender = (details: unknown): unknown => {
+  if (typeof details !== "object" || details === null) return undefined;
+  return (details as Record<string, unknown>)["render"];
+};
+
+/**
+ * Build a renderResult over an ExpandableText stored in `details.render`.
+ * `label` names the tool for the error fallback (e.g. "web_search").
+ */
+export const renderExpandableText = (
+  label: string,
+  result: { readonly details?: unknown },
+  expanded: boolean,
+  theme: Theme,
+): Component => {
+  const render = extractRender(result.details);
+  if (!isExpandableText(render)) return new Text(theme.fg("error", `${label}: no details`), 0, 0);
+
+  if (!expanded) {
+    const lines = render.body.split("\n");
+    const preview = lines.slice(0, COMPACT_PREVIEW_LINES).join("\n");
+    const more = lines.length > COMPACT_PREVIEW_LINES ? `\n… ${lines.length - COMPACT_PREVIEW_LINES} more lines` : "";
+    const md = `**${render.summary}**\n\n${preview}${more}\n\n${keyHint("app.tools.expand", "to expand")}`;
+    return new Markdown(md, 0, 0, getMarkdownTheme());
+  }
+
+  const tail = render.fullOutputPath
+    ? `\n\nFull output at \`${render.fullOutputPath}\` · ${keyHint("app.tools.expand", "to collapse")}`
+    : `\n\n${keyHint("app.tools.expand", "to collapse")}`;
+  const md = `**${render.summary}**\n\n${render.body}${tail}`;
+  return new Markdown(md, 0, 0, getMarkdownTheme());
+};

package/src/domains/search/extract.ts

@@ -0,0 +1,44 @@
+/**
+ * The JavaScript source evaluated inside the Google SERP page to capture raw
+ * anchors + page text. This string crosses the CDP boundary via
+ * Runtime.evaluate (returnByValue) and returns a JSON string that
+ * `parseGoogleSerp` / `classifySerp` consume on the harness side.
+ *
+ * ADR-0001: anchors are selected structurally (a link carrying an <h3>), not by
+ * Google CSS class names, so cosmetic markup churn does not break extraction.
+ */
+
+/** Max bytes of page text captured for CAPTCHA / no-results classification. */
+const PAGE_TEXT_LIMIT = 4000;
+
+/**
+ * Build the extraction expression. Takes no interpolated values, so it is a
+ * fixed source string (no injection surface). Returns
+ * `JSON.stringify({ anchors, pageText })`.
+ */
+export 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 });
+  })()
+`;

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

@@ -0,0 +1,114 @@
+/**
+ * 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;
+  readonly snippet: string;
+  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> = [
+  "unusual traffic",
+  "not a robot",
+  "recaptcha",
+  "detected unusual",
+  "systems have detected",
+  "before you continue to google",
+  "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;
+  const query = href.slice(href.indexOf("?") + 1);
+  const target = new URLSearchParams(query).get("q");
+  return target ?? href;
+};
+
+const isExternalResult = (url: string): boolean => {
+  if (!/^https?:\/\//i.test(url)) return false;
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    if (host === "google.com" || host.endsWith(".google.com")) return false;
+    if (host === "googleusercontent.com" || host.endsWith(".googleusercontent.com")) return false;
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Normalized key for dedupe: origin + pathname, trailing slash and hash removed. */
+const dedupeKey = (url: string): string => {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname.replace(/\/$/, "")}`.toLowerCase();
+  } catch {
+    return url.toLowerCase();
+  }
+};
+
+/**
+ * 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[] = [];
+  for (const anchor of anchors) {
+    if (results.length >= limit) break;
+    const url = unwrapRedirect(anchor.href);
+    if (!isExternalResult(url)) continue;
+    const key = dedupeKey(url);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    results.push({
+      title: anchor.heading.trim(),
+      url,
+      snippet: anchor.snippet.trim(),
+      rank: results.length + 1,
+    });
+  }
+  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();
+  if (CAPTCHA_MARKERS.some((marker) => lower.includes(marker))) return "captcha";
+  return "no_results";
+};