pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/domains/readpage/readability.ts

@@ -0,0 +1,65 @@
+export type ContentBlock = {
+  readonly kind: "paragraph" | "heading" | "listitem" | "blockquote" | "other";
+  readonly text: string;
+  readonly linkTextLength: number;
+  readonly inBoilerplate: boolean;
+};
+
+export type PageCapture = {
+  readonly url: string;
+  readonly title: string;
+  readonly blocks: ReadonlyArray<ContentBlock>;
+  readonly bodyText: string;
+};
+
+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;
+};
+
+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;
+};
+
+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/extensions/browser-harness/domains/ref-resolve.ts

@@ -0,0 +1,118 @@
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { type Box, boxOf } from "./box";
+import { cdpCall } from "./cdp-call";
+import { buildTree, collectInteractiveTargets, type SlimNode } from "./ax-tree";
+
+const staleErr = (ref: string): ToolErr => ({
+  kind: "invalid_state",
+  message: `Ref ${ref} is unknown or stale — re-run browser_snapshot to get fresh refs.`,
+  details: { ref },
+});
+
+export const resolveRefToObjectId = async (
+  client: BrowserClient,
+  ref: string,
+): Promise<Result<string, ToolErr>> => {
+  const backendId = client.session().resolveRef(ref);
+  if (backendId === undefined) return err(staleErr(ref));
+  const resolved = await cdpCall(client, "DOM.resolveNode", { backendNodeId: backendId });
+  if (!resolved.success) {
+    return err(staleErr(ref));
+  }
+  const objectId = resolved.data.object.objectId;
+  if (!objectId) return err(staleErr(ref));
+  return ok(objectId);
+};
+
+export const resolveRefToBackendId = (client: BrowserClient, ref: string): Result<number, ToolErr> => {
+  const backendId = client.session().resolveRef(ref);
+  if (backendId === undefined) return err(staleErr(ref));
+  return ok(backendId);
+};
+
+export const resolveRefToBox = async (
+  client: BrowserClient,
+  ref: string,
+): Promise<Result<Box, ToolErr>> => {
+  const backendId = client.session().resolveRef(ref);
+  if (backendId === undefined) return err(staleErr(ref));
+  const box = await boxOf(client, backendId);
+  if (!box.success) return err(staleErr(ref));
+  return ok(box.data);
+};
+
+const sigOf = (n: SlimNode): string => `${n.role}|${n.name ?? ""}|${n.value ?? ""}|${n.state ?? ""}`;
+const keyOf = (n: SlimNode): string => `${n.role}|${n.name ?? ""}`;
+
+export const interactiveDiff = async (client: BrowserClient): Promise<string> => {
+  const session = client.session();
+  const prev = session.refSignatures();
+
+  const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
+  if (!axRes.success) return "";
+  const rawNodes = axRes.data.nodes;
+  const slim = buildTree(rawNodes, { interestingOnly: true, maxNodes: 1000 });
+  const targets = collectInteractiveTargets(slim);
+
+  const priorRefs = session.refMappings();
+  const refByBackendId = new Map<number, string>();
+  for (const [ref, backendId] of priorRefs) refByBackendId.set(backendId, ref);
+  let nextIndex = 1;
+  for (const ref of priorRefs.keys()) {
+    const digits = /^e(\d+)$/.exec(ref)?.[1];
+    if (digits !== undefined) nextIndex = Math.max(nextIndex, Number(digits) + 1);
+  }
+  const refMap = new Map<string, number>();
+  const refSig = new Map<string, string>();
+  const taken = new Set<string>();
+  for (const { node, backendId } of targets) {
+    const prior = refByBackendId.get(backendId);
+    const ref = prior !== undefined && !taken.has(prior) ? prior : `e${nextIndex++}`;
+    taken.add(ref);
+    node.ref = ref;
+    refMap.set(ref, backendId);
+    refSig.set(ref, sigOf(node));
+  }
+  session.setRefMap(refMap, refSig);
+
+  const prevByKey = new Map<string, string>();
+  for (const sig of prev.values()) {
+    const parts = sig.split("|");
+    prevByKey.set(`${parts[0]}|${parts[1]}`, sig);
+  }
+  const curByKey = new Map<string, { ref: string; sig: string }>();
+  for (const { node } of targets) {
+    if (node.ref) curByKey.set(keyOf(node), { ref: node.ref, sig: sigOf(node) });
+  }
+
+  const appeared: string[] = [];
+  const changed: string[] = [];
+  for (const [key, { ref, sig }] of curByKey) {
+    const before = prevByKey.get(key);
+    if (before === undefined) {
+      appeared.push(`  *[${ref}] ${key.replace("|", ' "')}"`);
+    } else if (before !== sig) {
+      const va = before.split("|")[2] ?? "";
+      const vb = sig.split("|")[2] ?? "";
+      const sa = before.split("|")[3] ?? "";
+      const sb = sig.split("|")[3] ?? "";
+      const detail = va !== vb ? `value ${JSON.stringify(va)} → ${JSON.stringify(vb)}` : `state ${JSON.stringify(sa)} → ${JSON.stringify(sb)}`;
+      changed.push(`  [${ref}] ${key.replace("|", ' "')}": ${detail}`);
+    }
+  }
+  const removed: string[] = [];
+  for (const key of prevByKey.keys()) {
+    if (!curByKey.has(key)) removed.push(`  ${key.replace("|", ' "')}"`);
+  }
+
+  if (appeared.length === 0 && changed.length === 0 && removed.length === 0) return "";
+  const lines: string[] = ["", "Page changes (re-snapshot for full tree):"];
+  if (changed.length) lines.push("Changed:", ...changed.slice(0, 12));
+  if (appeared.length) lines.push("New (*):", ...appeared.slice(0, 12));
+  if (removed.length) lines.push("Removed:", ...removed.slice(0, 8));
+  const overflow = Math.max(0, changed.length - 12) + Math.max(0, appeared.length - 12) + Math.max(0, removed.length - 8);
+  if (overflow > 0) lines.push(`  …and ${overflow} more (browser_snapshot for full state)`);
+  return lines.join("\n");
+};

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

@@ -0,0 +1,43 @@
+import { Markdown, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "../util/guards";
+
+const COMPACT_PREVIEW_LINES = 6;
+
+type ExpandableText = {
+  readonly summary: string;
+  readonly body: string;
+  readonly fullOutputPath?: string;
+};
+
+const isExpandableText = (value: unknown): value is ExpandableText =>
+  isRecord(value) && typeof value["summary"] === "string" && typeof value["body"] === "string";
+
+const extractRender = (details: unknown): unknown =>
+  isRecord(details) ? details["render"] : undefined;
+
+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/extensions/browser-harness/domains/screenshot-capture.ts

@@ -0,0 +1,80 @@
+import { rename, writeFile } from "node:fs/promises";
+import type { BrowserClient } from "../client";
+import { type Result, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { screenshotPath } from "../util/paths";
+import { loadSharp } from "../util/sharp-shim";
+import { safeJs } from "../util/js-template";
+import { cdpCall, evalJs } from "./cdp-call";
+
+export type CaptureArgs = {
+  readonly fullPage?: boolean;
+  readonly format?: "png" | "jpeg";
+  readonly quality?: number;
+};
+
+export const captureBase = async (
+  client: BrowserClient,
+  args: CaptureArgs,
+): Promise<Result<{ readonly path: string; readonly format: "png" | "jpeg" }, ToolErr>> => {
+  const format = args.format ?? "png";
+  const quality = args.quality ?? 80;
+  const path = screenshotPath(client.namespace, format);
+  const r = await cdpCall(client, "Page.captureScreenshot", {
+    format,
+    captureBeyondViewport: args.fullPage ?? false,
+    ...(format === "jpeg" ? { quality } : {}),
+  });
+  if (!r.success) return r;
+  await writeFile(path, Buffer.from(r.data.data, "base64"));
+  return ok({ path, format });
+};
+
+export const resizeIfNeeded = async (
+  path: string,
+  maxDim: number,
+): Promise<{ readonly note: string }> => {
+  const load = await loadSharp();
+  if (load.kind === "missing") return { note: " (maxDim ignored: install sharp for auto-resize)" };
+  if (load.kind === "error") return { note: ` (maxDim ignored: sharp failed to load: ${load.message})` };
+  try {
+    const meta = await load.sharp(path).metadata();
+    const w = meta.width ?? 0;
+    const h = meta.height ?? 0;
+    if (Math.max(w, h) <= maxDim) return { note: "" };
+    const tmp = `${path}.resized`;
+    await load.sharp(path).resize(maxDim, maxDim, { fit: "inside" }).toFile(tmp);
+    await rename(tmp, path);
+    return { note: ` (resized to fit ${maxDim}px)` };
+  } catch (e) {
+    return { note: ` (maxDim ignored: sharp threw: ${e instanceof Error ? e.message : String(e)})` };
+  }
+};
+
+export const captureWithCrosshair = async (
+  client: BrowserClient,
+  args: { readonly x: number; readonly y: number; readonly format?: "png" | "jpeg"; readonly quality?: number },
+): Promise<Result<{ readonly path: string }, ToolErr>> => {
+  const cap = await captureBase(client, args);
+  if (!cap.success) return cap;
+  const load = await loadSharp();
+  if (load.kind !== "ok") return ok({ path: cap.data.path });
+  try {
+    const dprR = await evalJs(client, safeJs`window.devicePixelRatio`);
+    const dpr = dprR.success && typeof dprR.data === "number" ? dprR.data : 1;
+    const meta = await load.sharp(cap.data.path).metadata();
+    const w = meta.width ?? 0;
+    const h = meta.height ?? 0;
+    const px = Math.round(args.x * dpr);
+    const py = Math.round(args.y * dpr);
+    const r = Math.round(15 * dpr);
+    const stroke = Math.max(2, Math.round(3 * dpr));
+    const svg = `<svg width="${w}" height="${h}"><circle cx="${px}" cy="${py}" r="${r}" fill="none" stroke="red" stroke-width="${stroke}" opacity="0.8"/><line x1="${px - r - 5}" y1="${py}" x2="${px + r + 5}" y2="${py}" stroke="red" stroke-width="${Math.max(1, stroke - 1)}" opacity="0.8"/><line x1="${px}" y1="${py - r - 5}" x2="${px}" y2="${py + r + 5}" stroke="red" stroke-width="${Math.max(1, stroke - 1)}" opacity="0.8"/></svg>`;
+    const tmp = `${cap.data.path}.debug`;
+    await load.sharp(cap.data.path).composite([{ input: Buffer.from(svg), top: 0, left: 0 }]).toFile(tmp);
+    await rename(tmp, cap.data.path);
+    return ok({ path: cap.data.path });
+  } catch {
+    return ok({ path: cap.data.path });
+  }
+};

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

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import { Type } from "typebox";
+import { Image, type ImageTheme, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { type Result, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { asRecord, asString } from "../util/guards";
+import { captureBase, resizeIfNeeded } from "./screenshot-capture";
+
+const ScreenshotArgs = Type.Object({
+  fullPage: Type.Optional(Type.Boolean({ default: false, description: "Capture beyond viewport" })),
+  format: Type.Optional(Type.Union([Type.Literal("png"), Type.Literal("jpeg")], { default: "png" })),
+  quality: Type.Optional(Type.Integer({ minimum: 1, maximum: 100, default: 80, description: "JPEG quality 1-100" })),
+  maxDim: Type.Optional(Type.Integer({ minimum: 100, maximum: 8000, description: "If max(w,h) exceeds this, resize via sharp." })),
+});
+
+export const screenshotTool = defineBrowserTool({
+  name: "browser_screenshot",
+  label: "Browser Screenshot",
+  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: [
+    "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,
+  concurrency: "parallel",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const cap = await captureBase(client, args);
+    if (!cap.success) return cap;
+    let note = "";
+    if (args.maxDim !== undefined) {
+      const resized = await resizeIfNeeded(cap.data.path, args.maxDim);
+      note = resized.note;
+    }
+    return ok({
+      text: `Screenshot saved: ${cap.data.path}${note}`,
+      details: { path: cap.data.path, format: cap.data.format, attached: false },
+    });
+  },
+
+  renderResult(result, _expanded, theme) {
+    const raw = asRecord(result.details);
+    const filePath = raw === undefined ? undefined : asString(raw["path"]);
+    if (!filePath) {
+      return new Text(theme.fg("error", "Screenshot path missing"), 0, 0);
+    }
+    const format = raw === undefined ? undefined : asString(raw["format"]);
+    try {
+      const buf = readFileSync(filePath);
+      const b64 = buf.toString("base64");
+      const mimeType = format === "jpeg" ? "image/jpeg" : "image/png";
+      const imageTheme: ImageTheme = {
+        fallbackColor: (str: string) => theme.fg("dim", str),
+      };
+      const image = new Image(b64, mimeType, imageTheme, {
+        maxWidthCells: 80,
+        maxHeightCells: 24,
+        filename: filePath,
+      });
+      // Image's text fallback does not respect the rendered width, so an unwrapped long path can blow past the terminal width and crash the host TUI.
+      return {
+        invalidate: () => image.invalidate(),
+        render: (width: number) =>
+          image.render(width).map((line) =>
+            visibleWidth(line) > width ? truncateToWidth(line, width) : line,
+          ),
+      };
+    } catch {
+      return new Text(theme.fg("warning", `Screenshot saved: ${filePath}`), 0, 0);
+    }
+  },
+});

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

@@ -0,0 +1,59 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+
+const ScrollArgs = Type.Object({
+  x: Type.Optional(Type.Number({ description: "X coordinate where to scroll. Default: viewport center" })),
+  y: Type.Optional(Type.Number({ description: "Y coordinate where to scroll. Default: viewport center" })),
+  deltaX: Type.Optional(Type.Number({ default: 0, description: "Horizontal scroll delta (CSS pixels). Positive = right." })),
+  deltaY: Type.Optional(Type.Number({
+    default: 300,
+    description: "Vertical scroll delta (CSS pixels). Positive = down, negative = up (W3C wheel-event convention). Default: 300 (scroll down).",
+  })),
+});
+
+export const scrollTool = defineBrowserTool({
+  name: "browser_scroll",
+  label: "Browser Scroll",
+  description:
+    "Scroll the page at given coordinates. deltaY follows W3C wheel-event convention: positive = scroll down, negative = scroll up. Default scrolls down (deltaY = 300).",
+  promptSnippet: "Scroll the page (deltaY positive=down, negative=up)",
+  promptGuidelines: [
+    "Default behavior scrolls down 300px (deltaY=300). Pass a negative deltaY to scroll up.",
+    "Pass x/y to target a specific scrollable region (e.g., a div with overflow); otherwise scrolls the page at viewport center.",
+  ],
+  parameters: ScrollArgs,
+  concurrency: "serialized",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const info = await client.pageInfo();
+    if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
+    if ("dialog" in info.data) {
+      return err({
+        kind: "invalid_state",
+        message: `Dialog open: ${info.data.dialog.type} — ${info.data.dialog.message}`,
+      });
+    }
+    const cx = args.x ?? Math.round(info.data.width / 2);
+    const cy = args.y ?? Math.round(info.data.height / 2);
+    const dx = args.deltaX ?? 0;
+    const dy = args.deltaY ?? 300;
+    // The page target must be focused or Input events are dropped silently: mouseWheel hangs and synthesizeScrollGesture returns ok without scrolling.
+    const front = await cdpCall(client, "Page.bringToFront", {});
+    if (!front.success) return front;
+    // Establish compositor mouse position first, or CDP sometimes drops the wheel event with a timeout.
+    const moved = await cdpCall(client, "Input.dispatchMouseEvent", {
+      type: "mouseMoved", x: cx, y: cy, button: "none", buttons: 0,
+    });
+    if (!moved.success) return moved;
+    const wheel = await cdpCall(client, "Input.dispatchMouseEvent", {
+      type: "mouseWheel", x: cx, y: cy, deltaX: dx, deltaY: dy,
+      button: "none", buttons: 0, pointerType: "mouse",
+    });
+    if (!wheel.success) return wheel;
+    return ok({
+      text: `Scrolled at (${cx}, ${cy}) by (${dx}, ${dy})`,
+      details: { x: cx, y: cy, deltaX: dx, deltaY: dy },
+    });
+  },
+});

package/extensions/browser-harness/domains/search/google-serp.ts

@@ -0,0 +1,85 @@
+export type SerpAnchor = {
+  readonly href: string;
+  readonly heading: string;
+  readonly snippet: string;
+};
+
+export type SerpExtraction = {
+  readonly anchors: ReadonlyArray<SerpAnchor>;
+  readonly pageText: string;
+};
+
+export type SearchResult = {
+  readonly title: string;
+  readonly url: string;
+  readonly snippet: string;
+  readonly rank: number;
+};
+
+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",
+];
+
+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;
+  }
+};
+
+const dedupeKey = (url: string): string => {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname.replace(/\/$/, "")}`.toLowerCase();
+  } catch {
+    return url.toLowerCase();
+  }
+};
+
+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;
+};
+
+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";
+};

package/extensions/browser-harness/domains/search/web-search.ts

@@ -0,0 +1,144 @@
+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 { classifySerp, parseGoogleSerp, type SearchResult, type SerpExtraction } from "./google-serp";
+
+const LOAD_TIMEOUT_MS = 15_000;
+
+const WebSearchArgs = Type.Object({
+  query: Type.String({ description: "The search query." }),
+  limit: Type.Optional(
+    Type.Integer({ default: 10, minimum: 1, maximum: 30, description: "Max results to return. Default: 10." }),
+  ),
+});
+
+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 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}`);
+  return `${results.length} result(s) for "${query}":\n\n${lines.join("\n\n")}`;
+};
+
+export const webSearchTool = defineBrowserTool({
+  name: "browser_web_search",
+  label: "Browser Web Search",
+  description:
+    "Search the web and return ranked results (title, url, snippet, rank). Scrapes a Google results page in the real Chrome — no API key. Returns links only; use browser_read_page to read a result's content.",
+  promptSnippet: "Search the web for a query",
+  promptGuidelines: [
+    "Returns ranked {title, url, snippet, rank} — links only, no page content. Follow up with browser_read_page.",
+    "On a CAPTCHA / bot wall the call fails with kind:'invalid_state' and details.reason:'captcha' (plus serpUrl) — surface it to the user; do not retry in a tight loop.",
+    "On zero results it fails with details.reason:'no_results' — rephrase the query and try again.",
+    "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);
+
+    const opened = await openIsolatedTab(client);
+    if (!opened.success) return err(opened.error);
+    const tab = opened.data;
+
+    try {
+      const navigated = await navigateIsolatedTab(client, tab, serpUrl);
+      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 extracted = await evalInIsolatedTab(client, tab, buildSerpExtractionExpr(), isJsonText);
+      if (!extracted.success) return err(extracted.error);
+
+      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(extraction.anchors, limit);
+      const verdict = classifySerp(extraction.pageText, results.length);
+      if (verdict !== "ok") {
+        return err({
+          kind: "invalid_state",
+          message: verdict === "captcha" ? "Google served a CAPTCHA / bot wall" : "no results found",
+          details: { reason: verdict, serpUrl },
+        });
+      }
+
+      const body = formatResults(args.query, results);
+      const truncated = await applyTruncation(body, "search");
+      return ok({
+        text: truncated.text,
+        details: {
+          results,
+          engine: "google",
+          query: args.query,
+          render: {
+            summary: `${results.length} result(s) · google · "${args.query}"`,
+            body,
+            ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+          },
+          ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+        },
+      });
+    } finally {
+      await closeIsolatedTab(client, tab);
+    }
+  },
+  renderResult(result, expanded, theme) {
+    return renderExpandableText("web_search", result, expanded, theme);
+  },
+});