pi-browser-harness 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/README.md +102 -1
  3. package/package.json +13 -7
  4. package/skills/pi-browser-harness/SKILL.md +84 -0
  5. package/src/cdp/commands.ts +204 -14
  6. package/src/cdp/console-buffer.ts +37 -23
  7. package/src/cdp/discovery.ts +72 -37
  8. package/src/cdp/events.ts +8 -3
  9. package/src/cdp/network-buffer.ts +38 -32
  10. package/src/cdp/ownership.ts +22 -4
  11. package/src/cdp/record-store.ts +2 -2
  12. package/src/cdp/session.ts +320 -217
  13. package/src/cdp/target-factory.ts +34 -15
  14. package/src/cdp/types.ts +17 -1
  15. package/src/client.ts +76 -43
  16. package/src/daemon/bridge.ts +115 -191
  17. package/src/daemon/connection.ts +323 -0
  18. package/src/daemon/index.ts +77 -48
  19. package/src/daemon/lines.ts +40 -0
  20. package/src/daemon/main.ts +12 -0
  21. package/src/daemon/protocol.ts +55 -25
  22. package/src/daemon/server.ts +100 -63
  23. package/src/daemon/socket.ts +10 -0
  24. package/src/daemon/spawn.ts +84 -27
  25. package/src/daemon/transport.ts +88 -52
  26. package/src/domains/ax-tree.ts +8 -8
  27. package/src/domains/cdp-call.ts +14 -7
  28. package/src/domains/click.ts +2 -7
  29. package/src/domains/concurrency.ts +50 -0
  30. package/src/domains/console.ts +20 -66
  31. package/src/domains/drag.ts +26 -28
  32. package/src/domains/element-call.ts +102 -68
  33. package/src/domains/files.ts +64 -11
  34. package/src/domains/form-batch.ts +13 -11
  35. package/src/domains/form.ts +79 -116
  36. package/src/domains/headers.ts +89 -0
  37. package/src/domains/history.ts +7 -7
  38. package/src/domains/io.ts +35 -0
  39. package/src/domains/isolated-tab.ts +6 -12
  40. package/src/domains/js.ts +68 -53
  41. package/src/domains/keyboard.ts +16 -18
  42. package/src/domains/navigate.ts +102 -69
  43. package/src/domains/network.ts +56 -98
  44. package/src/domains/page/fill.page.ts +139 -0
  45. package/src/domains/page/form.page.ts +61 -0
  46. package/src/domains/page/inject.ts +37 -0
  47. package/src/domains/page/keyboard.page.ts +16 -0
  48. package/src/domains/page/live-value.page.ts +10 -0
  49. package/src/domains/page/read-page.page.ts +51 -0
  50. package/src/domains/page/serp.page.ts +39 -0
  51. package/src/domains/page.ts +19 -58
  52. package/src/domains/poll.ts +42 -0
  53. package/src/domains/readpage/read-page.ts +48 -54
  54. package/src/domains/ref-resolve.ts +43 -29
  55. package/src/domains/ref-signature.ts +11 -0
  56. package/src/domains/render.ts +12 -23
  57. package/src/domains/screenshot-capture.ts +4 -2
  58. package/src/domains/screenshot.ts +13 -14
  59. package/src/domains/scroll.ts +4 -5
  60. package/src/domains/search/google-serp.ts +1 -1
  61. package/src/domains/search/web-search.ts +38 -34
  62. package/src/domains/setup.ts +0 -2
  63. package/src/domains/snapshot.ts +72 -77
  64. package/src/domains/tab-resolve.ts +36 -0
  65. package/src/domains/tabs.ts +19 -78
  66. package/src/domains/target.ts +1 -1
  67. package/src/domains/viewport.ts +0 -1
  68. package/src/index.ts +100 -39
  69. package/src/profile/bind.ts +45 -14
  70. package/src/profile/browser-process.ts +50 -12
  71. package/src/profile/command.ts +20 -12
  72. package/src/profile/launch.ts +13 -9
  73. package/src/profile/list.ts +9 -13
  74. package/src/profile/store.ts +2 -1
  75. package/src/prompt.ts +42 -117
  76. package/src/registry.ts +68 -4
  77. package/src/schemas/parse.ts +2 -2
  78. package/src/setup.ts +28 -19
  79. package/src/state.ts +33 -2
  80. package/src/util/debug.ts +7 -1
  81. package/src/util/guards.ts +3 -0
  82. package/src/util/mutex.ts +1 -1
  83. package/src/util/paths.ts +12 -1
  84. package/src/util/result.ts +8 -0
  85. package/src/util/sharp-shim.ts +18 -11
  86. package/src/util/sleep.ts +18 -0
  87. package/src/util/tool.ts +163 -114
  88. package/src/util/truncate.ts +1 -1
  89. package/tsconfig.json +2 -1
  90. package/src/domains/fill-engine.ts +0 -80
@@ -3,7 +3,8 @@ import { type Result, err, ok } from "../util/result";
3
3
  import type { ToolErr } from "../util/tool";
4
4
  import { type Box, boxOf } from "./box";
5
5
  import { cdpCall } from "./cdp-call";
6
- import { buildTree, collectInteractiveTargets, type SlimNode } from "./ax-tree";
6
+ import { buildTree, collectInteractiveTargets } from "./ax-tree";
7
+ import { type RefSignature, signatureOf } from "./ref-signature";
7
8
 
8
9
  const staleErr = (ref: string): ToolErr => ({
9
10
  kind: "invalid_state",
@@ -43,17 +44,20 @@ export const resolveRefToBox = async (
43
44
  return ok(box.data);
44
45
  };
45
46
 
46
- const sigOf = (n: SlimNode): string => `${n.role}|${n.name ?? ""}|${n.value ?? ""}|${n.state ?? ""}`;
47
- const keyOf = (n: SlimNode): string => `${n.role}|${n.name ?? ""}`;
47
+ export type RefRefresh = {
48
+ readonly prev: ReadonlyMap<string, RefSignature>;
49
+ readonly cur: ReadonlyMap<string, RefSignature>;
50
+ };
48
51
 
49
- export const interactiveDiff = async (client: BrowserClient): Promise<string> => {
52
+ // Re-reads the AX tree and republishes the session's ref map: an element seen before keeps its ref, a new one gets
53
+ // the next unused index. Returns the signatures before and after so the caller can diff them.
54
+ export const refreshRefs = async (client: BrowserClient): Promise<Result<RefRefresh, ToolErr>> => {
50
55
  const session = client.session();
51
56
  const prev = session.refSignatures();
52
57
 
53
58
  const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
54
- if (!axRes.success) return "";
55
- const rawNodes = axRes.data.nodes;
56
- const slim = buildTree(rawNodes, { interestingOnly: true, maxNodes: 1000 });
59
+ if (!axRes.success) return axRes;
60
+ const slim = buildTree(axRes.data.nodes, { interestingOnly: true, maxNodes: 1000 });
57
61
  const targets = collectInteractiveTargets(slim);
58
62
 
59
63
  const priorRefs = session.refMappings();
@@ -65,7 +69,7 @@ export const interactiveDiff = async (client: BrowserClient): Promise<string> =>
65
69
  if (digits !== undefined) nextIndex = Math.max(nextIndex, Number(digits) + 1);
66
70
  }
67
71
  const refMap = new Map<string, number>();
68
- const refSig = new Map<string, string>();
72
+ const cur = new Map<string, RefSignature>();
69
73
  const taken = new Set<string>();
70
74
  for (const { node, backendId } of targets) {
71
75
  const prior = refByBackendId.get(backendId);
@@ -73,38 +77,40 @@ export const interactiveDiff = async (client: BrowserClient): Promise<string> =>
73
77
  taken.add(ref);
74
78
  node.ref = ref;
75
79
  refMap.set(ref, backendId);
76
- refSig.set(ref, sigOf(node));
80
+ cur.set(ref, signatureOf(node));
77
81
  }
78
- session.setRefMap(refMap, refSig);
82
+ session.setRefMap(refMap, cur);
83
+ return ok({ prev, cur });
84
+ };
79
85
 
80
- const prevByKey = new Map<string, string>();
81
- for (const sig of prev.values()) {
82
- const parts = sig.split("|");
83
- prevByKey.set(`${parts[0]}|${parts[1]}`, sig);
84
- }
85
- const curByKey = new Map<string, { ref: string; sig: string }>();
86
- for (const { node } of targets) {
87
- if (node.ref) curByKey.set(keyOf(node), { ref: node.ref, sig: sigOf(node) });
88
- }
86
+ const identityKey = (s: RefSignature): string => JSON.stringify([s.role, s.name]);
87
+ const describe = (s: RefSignature): string => `${s.role} "${s.name}"`;
88
+
89
+ // Pure: renders what changed between two signature sets, keyed by role+name. Empty string when nothing changed.
90
+ export const diffSignatures = (
91
+ prev: ReadonlyMap<string, RefSignature>,
92
+ cur: ReadonlyMap<string, RefSignature>,
93
+ ): string => {
94
+ const prevByKey = new Map<string, RefSignature>();
95
+ for (const sig of prev.values()) prevByKey.set(identityKey(sig), sig);
96
+ const curByKey = new Map<string, { readonly ref: string; readonly sig: RefSignature }>();
97
+ for (const [ref, sig] of cur) curByKey.set(identityKey(sig), { ref, sig });
89
98
 
90
99
  const appeared: string[] = [];
91
100
  const changed: string[] = [];
92
101
  for (const [key, { ref, sig }] of curByKey) {
93
102
  const before = prevByKey.get(key);
94
103
  if (before === undefined) {
95
- appeared.push(` *[${ref}] ${key.replace("|", ' "')}"`);
96
- } else if (before !== sig) {
97
- const va = before.split("|")[2] ?? "";
98
- const vb = sig.split("|")[2] ?? "";
99
- const sa = before.split("|")[3] ?? "";
100
- const sb = sig.split("|")[3] ?? "";
101
- const detail = va !== vb ? `value ${JSON.stringify(va)} → ${JSON.stringify(vb)}` : `state ${JSON.stringify(sa)} → ${JSON.stringify(sb)}`;
102
- changed.push(` [${ref}] ${key.replace("|", ' "')}": ${detail}`);
104
+ appeared.push(` *[${ref}] ${describe(sig)}`);
105
+ } else if (before.value !== sig.value) {
106
+ changed.push(` [${ref}] ${describe(sig)}: value ${JSON.stringify(before.value)} → ${JSON.stringify(sig.value)}`);
107
+ } else if (before.state !== sig.state) {
108
+ changed.push(` [${ref}] ${describe(sig)}: state ${JSON.stringify(before.state)} → ${JSON.stringify(sig.state)}`);
103
109
  }
104
110
  }
105
111
  const removed: string[] = [];
106
- for (const key of prevByKey.keys()) {
107
- if (!curByKey.has(key)) removed.push(` ${key.replace("|", ' "')}"`);
112
+ for (const [key, sig] of prevByKey) {
113
+ if (!curByKey.has(key)) removed.push(` ${describe(sig)}`);
108
114
  }
109
115
 
110
116
  if (appeared.length === 0 && changed.length === 0 && removed.length === 0) return "";
@@ -116,3 +122,11 @@ export const interactiveDiff = async (client: BrowserClient): Promise<string> =>
116
122
  if (overflow > 0) lines.push(` …and ${overflow} more (browser_snapshot for full state)`);
117
123
  return lines.join("\n");
118
124
  };
125
+
126
+ // Convenience for action tools: refresh refs and append a diff to the action's text. A failed refresh is reported
127
+ // inline rather than failing the action that already happened.
128
+ export const interactiveDiff = async (client: BrowserClient): Promise<string> => {
129
+ const refreshed = await refreshRefs(client);
130
+ if (!refreshed.success) return `\n(page diff unavailable: ${refreshed.error.message})`;
131
+ return diffSignatures(refreshed.data.prev, refreshed.data.cur);
132
+ };
@@ -0,0 +1,11 @@
1
+ import type { RefSignature } from "../cdp/types";
2
+ import type { SlimNode } from "./ax-tree";
3
+
4
+ export type { RefSignature };
5
+
6
+ export const signatureOf = (n: SlimNode): RefSignature => ({
7
+ role: n.role,
8
+ name: n.name ?? "",
9
+ value: n.value ?? "",
10
+ state: n.state ?? "",
11
+ });
@@ -1,32 +1,21 @@
1
- import { Markdown, Text } from "@mariozechner/pi-tui";
1
+ import { Type } from "typebox";
2
+ import { Markdown } from "@mariozechner/pi-tui";
2
3
  import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
3
4
  import type { Component } from "@mariozechner/pi-tui";
4
- import type { Theme } from "@mariozechner/pi-coding-agent";
5
- import { isRecord } from "../util/guards";
5
+ import type { DetailsOf } from "../util/tool";
6
6
 
7
7
  const COMPACT_PREVIEW_LINES = 6;
8
8
 
9
- type ExpandableText = {
10
- readonly summary: string;
11
- readonly body: string;
12
- readonly fullOutputPath?: string;
13
- };
14
-
15
- const isExpandableText = (value: unknown): value is ExpandableText =>
16
- isRecord(value) && typeof value["summary"] === "string" && typeof value["body"] === "string";
17
-
18
- const extractRender = (details: unknown): unknown =>
19
- isRecord(details) ? details["render"] : undefined;
9
+ // A tool whose details embed this under `render` gets a compact/expanded text view for free.
10
+ export const ExpandableTextSchema = Type.Object({
11
+ summary: Type.String(),
12
+ body: Type.String(),
13
+ fullOutputPath: Type.Optional(Type.String()),
14
+ });
20
15
 
21
- export const renderExpandableText = (
22
- label: string,
23
- result: { readonly details?: unknown },
24
- expanded: boolean,
25
- theme: Theme,
26
- ): Component => {
27
- const render = extractRender(result.details);
28
- if (!isExpandableText(render)) return new Text(theme.fg("error", `${label}: no details`), 0, 0);
16
+ export type ExpandableText = DetailsOf<typeof ExpandableTextSchema>;
29
17
 
18
+ export const renderExpandableText = (render: ExpandableText, expanded: boolean): Component => {
30
19
  if (!expanded) {
31
20
  const lines = render.body.split("\n");
32
21
  const preview = lines.slice(0, COMPACT_PREVIEW_LINES).join("\n");
@@ -35,7 +24,7 @@ export const renderExpandableText = (
35
24
  return new Markdown(md, 0, 0, getMarkdownTheme());
36
25
  }
37
26
 
38
- const tail = render.fullOutputPath
27
+ const tail = render.fullOutputPath !== undefined
39
28
  ? `\n\nFull output at \`${render.fullOutputPath}\` · ${keyHint("app.tools.expand", "to collapse")}`
40
29
  : `\n\n${keyHint("app.tools.expand", "to collapse")}`;
41
30
  const md = `**${render.summary}**\n\n${render.body}${tail}`;
@@ -1,4 +1,4 @@
1
- import { rename, writeFile } from "node:fs/promises";
1
+ import { rename } from "node:fs/promises";
2
2
  import type { BrowserClient } from "../client";
3
3
  import { type Result, ok } from "../util/result";
4
4
  import type { ToolErr } from "../util/tool";
@@ -6,6 +6,7 @@ import { screenshotPath } from "../util/paths";
6
6
  import { loadSharp } from "../util/sharp-shim";
7
7
  import { safeJs } from "../util/js-template";
8
8
  import { cdpCall, evalJs } from "./cdp-call";
9
+ import { writeFileResult } from "./io";
9
10
 
10
11
  export type CaptureArgs = {
11
12
  readonly fullPage?: boolean;
@@ -26,7 +27,8 @@ export const captureBase = async (
26
27
  ...(format === "jpeg" ? { quality } : {}),
27
28
  });
28
29
  if (!r.success) return r;
29
- await writeFile(path, Buffer.from(r.data.data, "base64"));
30
+ const written = await writeFileResult(path, Buffer.from(r.data.data, "base64"));
31
+ if (!written.success) return written;
30
32
  return ok({ path, format });
31
33
  };
32
34
 
@@ -2,8 +2,7 @@ import { readFileSync } from "node:fs";
2
2
  import { Type } from "typebox";
3
3
  import { Image, type ImageTheme, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
4
4
  import { type Result, ok } from "../util/result";
5
- import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
6
- import { asRecord, asString } from "../util/guards";
5
+ import { type DetailsOf, defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
7
6
  import { captureBase, resizeIfNeeded } from "./screenshot-capture";
8
7
 
9
8
  const ScreenshotArgs = Type.Object({
@@ -13,6 +12,14 @@ const ScreenshotArgs = Type.Object({
13
12
  maxDim: Type.Optional(Type.Integer({ minimum: 100, maximum: 8000, description: "If max(w,h) exceeds this, resize via sharp." })),
14
13
  });
15
14
 
15
+ const ScreenshotDetailsSchema = Type.Object({
16
+ path: Type.String(),
17
+ format: Type.Union([Type.Literal("png"), Type.Literal("jpeg")]),
18
+ attached: Type.Boolean(),
19
+ });
20
+
21
+ export type ScreenshotDetails = DetailsOf<typeof ScreenshotDetailsSchema>;
22
+
16
23
  export const screenshotTool = defineBrowserTool({
17
24
  name: "browser_screenshot",
18
25
  label: "Browser Screenshot",
@@ -20,15 +27,12 @@ export const screenshotTool = defineBrowserTool({
20
27
  "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.",
21
28
  promptSnippet: "Capture a screenshot — visual verification only",
22
29
  promptGuidelines: [
23
- "DO NOT use as a default exploration tool. browser_snapshot is the default for understanding page structure — far cheaper and more reliable.",
24
- "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().",
25
- "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.",
26
- "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.",
27
30
  "format='jpeg' with quality 60-90 keeps screenshots small for photo-heavy pages. Use maxDim if the page is huge.",
28
31
  ],
29
32
  parameters: ScreenshotArgs,
33
+ details: ScreenshotDetailsSchema,
30
34
  concurrency: "parallel",
31
- async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
35
+ async handler(args, { client }): Promise<Result<ToolOk<ScreenshotDetails>, ToolErr>> {
32
36
  const cap = await captureBase(client, args);
33
37
  if (!cap.success) return cap;
34
38
  let note = "";
@@ -43,12 +47,7 @@ export const screenshotTool = defineBrowserTool({
43
47
  },
44
48
 
45
49
  renderResult(result, _expanded, theme) {
46
- const raw = asRecord(result.details);
47
- const filePath = raw === undefined ? undefined : asString(raw["path"]);
48
- if (!filePath) {
49
- return new Text(theme.fg("error", "Screenshot path missing"), 0, 0);
50
- }
51
- const format = raw === undefined ? undefined : asString(raw["format"]);
50
+ const { path: filePath, format } = result.details;
52
51
  try {
53
52
  const buf = readFileSync(filePath);
54
53
  const b64 = buf.toString("base64");
@@ -63,7 +62,7 @@ export const screenshotTool = defineBrowserTool({
63
62
  });
64
63
  // 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.
65
64
  return {
66
- invalidate: () => image.invalidate(),
65
+ invalidate: () => { image.invalidate(); },
67
66
  render: (width: number) =>
68
67
  image.render(width).map((line) =>
69
68
  visibleWidth(line) > width ? truncateToWidth(line, width) : line,
@@ -1,7 +1,7 @@
1
1
  import { Type } from "typebox";
2
2
  import { type Result, err, ok } from "../util/result";
3
3
  import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
4
- import { cdpCall } from "./cdp-call";
4
+ import { cdpCall, fromClient } from "./cdp-call";
5
5
 
6
6
  const ScrollArgs = Type.Object({
7
7
  x: Type.Optional(Type.Number({ description: "X coordinate where to scroll. Default: viewport center" })),
@@ -20,15 +20,14 @@ export const scrollTool = defineBrowserTool({
20
20
  "Scroll the page at given coordinates. deltaY follows W3C wheel-event convention: positive = scroll down, negative = scroll up. Default scrolls down (deltaY = 300).",
21
21
  promptSnippet: "Scroll the page (deltaY positive=down, negative=up)",
22
22
  promptGuidelines: [
23
- "Default behavior scrolls down 300px (deltaY=300). Pass a negative deltaY to scroll up.",
24
23
  "Pass x/y to target a specific scrollable region (e.g., a div with overflow); otherwise scrolls the page at viewport center.",
25
24
  ],
26
25
  parameters: ScrollArgs,
27
26
  concurrency: "serialized",
28
27
  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
29
- const info = await client.pageInfo();
30
- if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
31
- if ("dialog" in info.data) {
28
+ const info = fromClient(await client.pageInfo(), "pageInfo");
29
+ if (!info.success) return info;
30
+ if (info.data.kind === "dialog") {
32
31
  return err({
33
32
  kind: "invalid_state",
34
33
  message: `Dialog open: ${info.data.dialog.type} — ${info.data.dialog.message}`,
@@ -29,7 +29,7 @@ const CAPTCHA_MARKERS: ReadonlyArray<string> = [
29
29
  ];
30
30
 
31
31
  const unwrapRedirect = (href: string): string => {
32
- const wrapper = href.match(/^(?:https?:\/\/[^/]*google\.[^/]*)?\/url\?/i);
32
+ const wrapper = /^(?:https?:\/\/[^/]*google\.[^/]*)?\/url\?/i.exec(href);
33
33
  if (!wrapper) return href;
34
34
  const query = href.slice(href.indexOf("?") + 1);
35
35
  const target = new URLSearchParams(query).get("q");
@@ -3,7 +3,7 @@ import { Compile } from "typebox/compile";
3
3
  import { parseJson } from "../../schemas/parse";
4
4
  import { type Result, err, ok } from "../../util/result";
5
5
  import { applyTruncation } from "../../util/truncate";
6
- import { defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
6
+ import { type DetailsOf, defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
7
7
  import {
8
8
  closeIsolatedTab,
9
9
  evalInIsolatedTab,
@@ -12,7 +12,10 @@ import {
12
12
  openIsolatedTab,
13
13
  waitForIsolatedLoad,
14
14
  } from "../isolated-tab";
15
- import { renderExpandableText } from "../render";
15
+ import { pageCallExpression } from "../page/inject";
16
+ import { extractSerp } from "../page/serp.page";
17
+ import type * as extracted from "../page/serp.page";
18
+ import { ExpandableTextSchema, renderExpandableText } from "../render";
16
19
  import { classifySerp, parseGoogleSerp, type SearchResult, type SerpExtraction } from "./google-serp";
17
20
 
18
21
  const LOAD_TIMEOUT_MS = 15_000;
@@ -26,32 +29,13 @@ const WebSearchArgs = Type.Object({
26
29
 
27
30
  const PAGE_TEXT_LIMIT = 4000;
28
31
 
29
- const buildSerpExtractionExpr = (): string => `
30
- (() => {
31
- const main = document.querySelector('#search, #rso, #main') || document.body;
32
- const headings = Array.from(main.querySelectorAll('a h3'));
33
- const seen = new Set();
34
- const anchors = [];
35
- for (const h3 of headings) {
36
- const a = h3.closest('a[href]');
37
- if (!a) continue;
38
- const href = a.href;
39
- if (!href || seen.has(href)) continue;
40
- seen.add(href);
41
- const container =
42
- a.closest('div.g') ||
43
- a.closest('div[data-hveid]') ||
44
- a.parentElement?.parentElement ||
45
- a.parentElement;
46
- const containerText = container ? container.innerText || '' : '';
47
- const heading = h3.innerText || h3.textContent || '';
48
- const snippet = containerText.replace(heading, '').replace(/\\s+/g, ' ').trim().slice(0, 500);
49
- anchors.push({ href, heading, snippet });
50
- }
51
- const pageText = (document.body.innerText || '').slice(0, ${PAGE_TEXT_LIMIT});
52
- return JSON.stringify({ anchors, pageText });
53
- })()
54
- `;
32
+ // The page function declares the extraction shape it produces; this pins it to the shape the SERP parser consumes,
33
+ // so the two cannot drift apart silently (the runtime validator below still guards the actual wire value).
34
+ type Pinned<T extends SerpExtraction> = T;
35
+ export type ExtractionFromPage = Pinned<extracted.SerpExtraction>;
36
+
37
+ // Built once: stringifying the page function per call was the only cost of the thunk.
38
+ const SERP_EXTRACTION_EXPR = pageCallExpression(extractSerp, PAGE_TEXT_LIMIT);
55
39
 
56
40
  const buildSerpUrl = (query: string, limit: number): string =>
57
41
  `https://www.google.com/search?q=${encodeURIComponent(query)}&num=${limit}&hl=en`;
@@ -65,6 +49,26 @@ const SerpExtractionSchema = Type.Object({
65
49
 
66
50
  const serpExtractionValidator = Compile(SerpExtractionSchema);
67
51
 
52
+ export const parseSerpExtraction = (raw: string): Result<SerpExtraction, string> =>
53
+ parseJson(raw, serpExtractionValidator);
54
+
55
+ const SearchResultSchema = Type.Object({
56
+ title: Type.String(),
57
+ url: Type.String(),
58
+ snippet: Type.String(),
59
+ rank: Type.Number(),
60
+ });
61
+
62
+ const WebSearchDetailsSchema = Type.Object({
63
+ results: Type.Array(SearchResultSchema),
64
+ engine: Type.Literal("google"),
65
+ query: Type.String(),
66
+ render: ExpandableTextSchema,
67
+ fullOutputPath: Type.Optional(Type.String()),
68
+ });
69
+
70
+ export type WebSearchDetails = DetailsOf<typeof WebSearchDetailsSchema>;
71
+
68
72
  const formatResults = (query: string, results: ReadonlyArray<SearchResult>): string => {
69
73
  const lines = results.map((r) => `${r.rank}. ${r.title}\n ${r.url}\n ${r.snippet}`);
70
74
  return `${results.length} result(s) for "${query}":\n\n${lines.join("\n\n")}`;
@@ -77,14 +81,14 @@ export const webSearchTool = defineBrowserTool({
77
81
  "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.",
78
82
  promptSnippet: "Search the web for a query",
79
83
  promptGuidelines: [
80
- "Returns ranked {title, url, snippet, rank} — links only, no page content. Follow up with browser_read_page.",
81
84
  "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.",
82
85
  "On zero results it fails with details.reason:'no_results' — rephrase the query and try again.",
83
86
  "Runs in its own isolated tab and never disturbs the user's current tab.",
84
87
  ],
85
88
  parameters: WebSearchArgs,
89
+ details: WebSearchDetailsSchema,
86
90
  concurrency: "serialized",
87
- async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
91
+ async handler(args, { client, signal }): Promise<Result<ToolOk<WebSearchDetails>, ToolErr>> {
88
92
  const limit = args.limit ?? 10;
89
93
  const serpUrl = buildSerpUrl(args.query, limit);
90
94
 
@@ -99,10 +103,10 @@ export const webSearchTool = defineBrowserTool({
99
103
  const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
100
104
  if (!loaded.success) return err(loaded.error);
101
105
 
102
- const extracted = await evalInIsolatedTab(client, tab, buildSerpExtractionExpr(), isJsonText);
106
+ const extracted = await evalInIsolatedTab(client, tab, SERP_EXTRACTION_EXPR, isJsonText);
103
107
  if (!extracted.success) return err(extracted.error);
104
108
 
105
- const parsedJson = parseJson(extracted.data, serpExtractionValidator);
109
+ const parsedJson = parseSerpExtraction(extracted.data);
106
110
  if (!parsedJson.success) {
107
111
  return err({ kind: "internal", message: `SERP extraction returned an unexpected shape: ${parsedJson.error}` });
108
112
  }
@@ -138,7 +142,7 @@ export const webSearchTool = defineBrowserTool({
138
142
  await closeIsolatedTab(client, tab);
139
143
  }
140
144
  },
141
- renderResult(result, expanded, theme) {
142
- return renderExpandableText("web_search", result, expanded, theme);
145
+ renderResult(result, expanded) {
146
+ return renderExpandableText(result.details.render, expanded);
143
147
  },
144
148
  });
@@ -15,8 +15,6 @@ export const setupTool = defineBrowserTool({
15
15
  "Call when browser tools fail with 'Browser harness not initialized'. Idempotent.",
16
16
  promptSnippet: "Initialize browser connection",
17
17
  promptGuidelines: [
18
- "Call browser_setup when you get a 'Browser harness not initialized' error from any browser tool.",
19
- "This tool is idempotent — calling it when already connected is harmless.",
20
18
  "After browser_setup succeeds, retry the browser tool that failed.",
21
19
  ],
22
20
  parameters: SetupArgs,