pi-browser-harness 0.12.0 → 0.14.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 (102) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +132 -0
  3. package/package.json +15 -7
  4. package/skills/pi-browser-harness/SKILL.md +89 -2
  5. package/src/cdp/commands.ts +205 -14
  6. package/src/cdp/console-buffer.ts +37 -23
  7. package/src/cdp/discovery.ts +57 -25
  8. package/src/cdp/events.ts +9 -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 +358 -216
  13. package/src/cdp/target-factory.ts +34 -15
  14. package/src/cdp/types.ts +17 -1
  15. package/src/client.ts +127 -54
  16. package/src/daemon/bridge.ts +110 -349
  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 +21 -22
  25. package/src/daemon/transport.ts +80 -49
  26. package/src/domains/ax-tree.ts +27 -8
  27. package/src/domains/cdp-call.ts +14 -7
  28. package/src/domains/click.ts +2 -2
  29. package/src/domains/concurrency.ts +50 -0
  30. package/src/domains/console.ts +20 -64
  31. package/src/domains/drag.ts +26 -28
  32. package/src/domains/element-call.ts +102 -68
  33. package/src/domains/files.ts +13 -9
  34. package/src/domains/form-batch.ts +13 -10
  35. package/src/domains/form.ts +78 -107
  36. package/src/domains/headers.ts +2 -2
  37. package/src/domains/history.ts +4 -4
  38. package/src/domains/io.ts +35 -0
  39. package/src/domains/isolated-tab.ts +6 -12
  40. package/src/domains/js.ts +67 -46
  41. package/src/domains/keyboard.ts +14 -11
  42. package/src/domains/navigate.ts +102 -66
  43. package/src/domains/network.ts +55 -95
  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/recipe.page.ts +82 -0
  51. package/src/domains/page/serp.page.ts +42 -0
  52. package/src/domains/page.ts +18 -51
  53. package/src/domains/poll.ts +42 -0
  54. package/src/domains/readpage/read-page.ts +48 -53
  55. package/src/domains/ref-resolve.ts +43 -29
  56. package/src/domains/ref-signature.ts +11 -0
  57. package/src/domains/render.ts +12 -23
  58. package/src/domains/screenshot-capture.ts +4 -2
  59. package/src/domains/screenshot.ts +13 -10
  60. package/src/domains/scroll.ts +4 -4
  61. package/src/domains/search/google-serp.ts +78 -8
  62. package/src/domains/search/redirect-resolver.ts +41 -0
  63. package/src/domains/search/web-search.ts +103 -40
  64. package/src/domains/snapshot.ts +81 -78
  65. package/src/domains/tab-resolve.ts +36 -0
  66. package/src/domains/tabs.ts +18 -69
  67. package/src/domains/target.ts +1 -1
  68. package/src/index.ts +101 -33
  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 +34 -8
  76. package/src/recipes/command.ts +96 -0
  77. package/src/recipes/compile.ts +198 -0
  78. package/src/recipes/find.ts +49 -0
  79. package/src/recipes/journal.ts +125 -0
  80. package/src/recipes/recipe.ts +215 -0
  81. package/src/recipes/recordable.ts +359 -0
  82. package/src/recipes/replay.ts +354 -0
  83. package/src/recipes/run-tool.ts +132 -0
  84. package/src/recipes/save-tool.ts +247 -0
  85. package/src/recipes/store.ts +103 -0
  86. package/src/recipes/trust.ts +172 -0
  87. package/src/registry.ts +69 -4
  88. package/src/schemas/parse.ts +2 -2
  89. package/src/setup.ts +28 -19
  90. package/src/state.ts +2 -1
  91. package/src/util/debug.ts +7 -1
  92. package/src/util/guards.ts +3 -0
  93. package/src/util/js-source.ts +28 -0
  94. package/src/util/mutex.ts +1 -1
  95. package/src/util/paths.ts +3 -2
  96. package/src/util/result.ts +8 -0
  97. package/src/util/sharp-shim.ts +18 -11
  98. package/src/util/sleep.ts +18 -0
  99. package/src/util/tool.ts +185 -114
  100. package/src/util/truncate.ts +1 -1
  101. package/tsconfig.json +2 -1
  102. package/src/domains/fill-engine.ts +0 -80
@@ -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" })),
@@ -25,9 +25,9 @@ export const scrollTool = defineBrowserTool({
25
25
  parameters: ScrollArgs,
26
26
  concurrency: "serialized",
27
27
  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
28
- const info = await client.pageInfo();
29
- if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
30
- 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") {
31
31
  return err({
32
32
  kind: "invalid_state",
33
33
  message: `Dialog open: ${info.data.dialog.type} — ${info.data.dialog.message}`,
@@ -2,6 +2,8 @@ export type SerpAnchor = {
2
2
  readonly href: string;
3
3
  readonly heading: string;
4
4
  readonly snippet: string;
5
+ // Visible breadcrumb url ("https://host › path › seg"); the only place the target survives once Google wraps hrefs in /goto.
6
+ readonly cite?: string;
5
7
  };
6
8
 
7
9
  export type SerpExtraction = {
@@ -16,7 +18,7 @@ export type SearchResult = {
16
18
  readonly rank: number;
17
19
  };
18
20
 
19
- export type SerpVerdict = "ok" | "captcha" | "no_results";
21
+ export type SerpVerdict = "ok" | "captcha" | "no_results" | "extraction_mismatch";
20
22
 
21
23
  const CAPTCHA_MARKERS: ReadonlyArray<string> = [
22
24
  "unusual traffic",
@@ -29,19 +31,81 @@ const CAPTCHA_MARKERS: ReadonlyArray<string> = [
29
31
  ];
30
32
 
31
33
  const unwrapRedirect = (href: string): string => {
32
- const wrapper = href.match(/^(?:https?:\/\/[^/]*google\.[^/]*)?\/url\?/i);
34
+ const wrapper = /^(?:https?:\/\/[^/]*google\.[^/]*)?\/url\?/i.exec(href);
33
35
  if (!wrapper) return href;
34
36
  const query = href.slice(href.indexOf("?") + 1);
35
37
  const target = new URLSearchParams(query).get("q");
36
38
  return target ?? href;
37
39
  };
38
40
 
41
+ const CITE_SEPARATOR = /\s*›\s*/;
42
+ const TRUNCATION = /(?:\.\.\.|…)/;
43
+
44
+ // Rebuilds a url from Google's visible breadcrumb cite. Segments after a truncation marker are unknowable, so the
45
+ // path stops at the last complete segment rather than guessing.
46
+ export const urlFromCite = (cite: string): string | undefined => {
47
+ const segments = cite
48
+ .trim()
49
+ .split(CITE_SEPARATOR)
50
+ .map((segment) => segment.trim())
51
+ .filter((segment) => segment.length > 0);
52
+ const origin = segments[0];
53
+ if (origin === undefined || TRUNCATION.test(origin)) return undefined;
54
+ // A cite naming any other scheme (ftp:, mailto:) is not a web result; prefixing it would forge a bogus https url.
55
+ if (/^[a-z][a-z0-9+.-]*:/i.test(origin) && !/^https?:\/\//i.test(origin)) return undefined;
56
+ const withScheme = /^https?:\/\//i.test(origin) ? origin : `https://${origin}`;
57
+ const path: string[] = [];
58
+ for (const segment of segments.slice(1)) {
59
+ if (TRUNCATION.test(segment)) break;
60
+ path.push(segment);
61
+ }
62
+ const url = [withScheme.replace(/\/$/, ""), ...path].join("/");
63
+ return isExternalResult(url) ? url : undefined;
64
+ };
65
+
66
+ // Only a real Google /goto url counts: the daemon fetches these, so a look-alike host, userinfo, a port or http
67
+ // must never qualify. Hosts are google.com or www.google.<tld>, nothing else.
68
+ const GOOGLE_GOTO_HOST = /^(?:www\.)?google\.[a-z]{2,3}(?:\.[a-z]{2})?$/;
69
+ export const isGotoRedirect = (href: string): boolean => {
70
+ try {
71
+ const u = new URL(href);
72
+ return (
73
+ u.protocol === "https:" &&
74
+ u.username === "" &&
75
+ u.password === "" &&
76
+ u.port === "" &&
77
+ GOOGLE_GOTO_HOST.test(u.hostname.toLowerCase()) &&
78
+ u.pathname === "/goto"
79
+ );
80
+ } catch {
81
+ return false;
82
+ }
83
+ };
84
+
85
+ export type ResolvedTargets = ReadonlyMap<string, string>;
86
+
87
+ // Direct external hrefs win. A /goto wrapper is opaque: the server-resolved redirect target is exact, and the cite is
88
+ // a display breadcrumb that only approximates the path, so it is the fallback when no target was resolved.
89
+ const resolveResultUrl = (anchor: SerpAnchor, resolved: ResolvedTargets): string | undefined => {
90
+ if (!isGotoRedirect(anchor.href)) {
91
+ const unwrapped = unwrapRedirect(anchor.href);
92
+ return isExternalResult(unwrapped) ? unwrapped : undefined;
93
+ }
94
+ const target = resolved.get(anchor.href);
95
+ if (target !== undefined && isExternalResult(target)) return target;
96
+ if (anchor.cite !== undefined && anchor.cite.trim() !== "") return urlFromCite(anchor.cite);
97
+ return undefined;
98
+ };
99
+
100
+ // Any Google property, on any TLD (google.com, google.co.uk, consent.google.de, googleusercontent.com), is never a
101
+ // result: a sorry or consent page is where a rate-limited /goto redirect lands.
102
+ const GOOGLE_PROPERTY = /(?:^|\.)google(?:usercontent)?\.(?:com?\.[a-z]{2}|[a-z]{2,3})$/;
103
+
39
104
  const isExternalResult = (url: string): boolean => {
40
105
  if (!/^https?:\/\//i.test(url)) return false;
41
106
  try {
42
107
  const host = new URL(url).hostname.toLowerCase();
43
- if (host === "google.com" || host.endsWith(".google.com")) return false;
44
- if (host === "googleusercontent.com" || host.endsWith(".googleusercontent.com")) return false;
108
+ if (GOOGLE_PROPERTY.test(host)) return false;
45
109
  return true;
46
110
  } catch {
47
111
  return false;
@@ -57,13 +121,17 @@ const dedupeKey = (url: string): string => {
57
121
  }
58
122
  };
59
123
 
60
- export const parseGoogleSerp = (anchors: ReadonlyArray<SerpAnchor>, limit: number): ReadonlyArray<SearchResult> => {
124
+ export const parseGoogleSerp = (
125
+ anchors: ReadonlyArray<SerpAnchor>,
126
+ limit: number,
127
+ resolved: ResolvedTargets = new Map(),
128
+ ): ReadonlyArray<SearchResult> => {
61
129
  const seen = new Set<string>();
62
130
  const results: SearchResult[] = [];
63
131
  for (const anchor of anchors) {
64
132
  if (results.length >= limit) break;
65
- const url = unwrapRedirect(anchor.href);
66
- if (!isExternalResult(url)) continue;
133
+ const url = resolveResultUrl(anchor, resolved);
134
+ if (url === undefined) continue;
67
135
  const key = dedupeKey(url);
68
136
  if (seen.has(key)) continue;
69
137
  seen.add(key);
@@ -77,9 +145,11 @@ export const parseGoogleSerp = (anchors: ReadonlyArray<SerpAnchor>, limit: numbe
77
145
  return results;
78
146
  };
79
147
 
80
- export const classifySerp = (pageText: string, resultCount: number): SerpVerdict => {
148
+ export const classifySerp = (pageText: string, resultCount: number, anchorCount: number): SerpVerdict => {
81
149
  if (resultCount > 0) return "ok";
82
150
  const lower = pageText.toLowerCase();
83
151
  if (CAPTCHA_MARKERS.some((marker) => lower.includes(marker))) return "captcha";
152
+ // Anchors were found but every one was filtered out: the markup changed, not the result set.
153
+ if (anchorCount > 0) return "extraction_mismatch";
84
154
  return "no_results";
85
155
  };
@@ -0,0 +1,41 @@
1
+ // Resolves one Google /goto?url=<opaque blob> link to its target by reading the server's redirect, without
2
+ // following it. The blob cannot be decoded client-side and the page's <cite> is only a display breadcrumb, so this
3
+ // is the one source of the exact url. Google answers the redirect to a cookie-less GET; HEAD returns 200 instead.
4
+
5
+ import { isGotoRedirect } from "./google-serp";
6
+
7
+ const REDIRECT_STATUSES: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
8
+
9
+ const USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/154.0.0.0 Safari/537.36";
10
+
11
+ export type RedirectResolver = (href: string, signal: AbortSignal) => Promise<string | undefined>;
12
+
13
+ export type ResolveOptions = {
14
+ // Defence in depth: the parser already filters to /goto hrefs, and the resolver refuses anything else again so a
15
+ // caller bug cannot turn it into a generic url fetcher. Tests against a local server opt out explicitly.
16
+ readonly requireGoto?: boolean;
17
+ };
18
+
19
+ export const fetchRedirectTarget = async (
20
+ href: string,
21
+ signal: AbortSignal,
22
+ opts: ResolveOptions = {},
23
+ ): Promise<string | undefined> => {
24
+ if ((opts.requireGoto ?? true) && !isGotoRedirect(href)) return undefined;
25
+ try {
26
+ const response = await fetch(href, {
27
+ method: "GET",
28
+ redirect: "manual",
29
+ signal,
30
+ headers: { "user-agent": USER_AGENT, accept: "text/html" },
31
+ });
32
+ // The body is never read; cancelling it releases the socket without waiting for Google to finish sending.
33
+ await response.body?.cancel().catch(() => undefined);
34
+ if (!REDIRECT_STATUSES.has(response.status)) return undefined;
35
+ const location = response.headers.get("location");
36
+ if (location === null || location === "") return undefined;
37
+ return new URL(location, href).toString();
38
+ } catch {
39
+ return undefined;
40
+ }
41
+ };
@@ -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,10 +12,51 @@ import {
12
12
  openIsolatedTab,
13
13
  waitForIsolatedLoad,
14
14
  } from "../isolated-tab";
15
- import { renderExpandableText } from "../render";
16
- import { classifySerp, parseGoogleSerp, type SearchResult, type SerpExtraction } from "./google-serp";
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";
19
+ import { deadlineSignal, runLimited } from "../concurrency";
20
+ import {
21
+ classifySerp,
22
+ isGotoRedirect,
23
+ parseGoogleSerp,
24
+ type ResolvedTargets,
25
+ type SearchResult,
26
+ type SerpExtraction,
27
+ } from "./google-serp";
28
+ import { fetchRedirectTarget, type RedirectResolver } from "./redirect-resolver";
17
29
 
18
30
  const LOAD_TIMEOUT_MS = 15_000;
31
+ const RESOLVE_BUDGET_MS = 5_000;
32
+ const RESOLVE_CONCURRENCY = 5;
33
+
34
+ export type WebSearchDeps = {
35
+ readonly resolveRedirect: RedirectResolver;
36
+ readonly resolveBudgetMs?: number;
37
+ };
38
+
39
+ // Resolves every /goto anchor in parallel under one time budget; a slot that fails or runs out of time is simply
40
+ // absent from the map, and the parser falls back to that anchor's cite.
41
+ const resolveGotoTargets = async (
42
+ anchors: ReadonlyArray<SerpExtraction["anchors"][number]>,
43
+ deps: WebSearchDeps,
44
+ signal: AbortSignal | undefined,
45
+ ): Promise<ResolvedTargets> => {
46
+ const hrefs = anchors.map((a) => a.href).filter(isGotoRedirect);
47
+ if (hrefs.length === 0) return new Map();
48
+ const deadline = deadlineSignal(deps.resolveBudgetMs ?? RESOLVE_BUDGET_MS, signal);
49
+ const targets = await runLimited(hrefs, { limit: RESOLVE_CONCURRENCY, signal: deadline.signal }, (href, s) =>
50
+ deps.resolveRedirect(href, s),
51
+ );
52
+ deadline.clear();
53
+ const resolved = new Map<string, string>();
54
+ hrefs.forEach((href, i) => {
55
+ const target = targets[i];
56
+ if (target !== undefined) resolved.set(href, target);
57
+ });
58
+ return resolved;
59
+ };
19
60
 
20
61
  const WebSearchArgs = Type.Object({
21
62
  query: Type.String({ description: "The search query." }),
@@ -26,51 +67,57 @@ const WebSearchArgs = Type.Object({
26
67
 
27
68
  const PAGE_TEXT_LIMIT = 4000;
28
69
 
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
- `;
70
+ // The page function declares the extraction shape it produces; this pins it to the shape the SERP parser consumes,
71
+ // so the two cannot drift apart silently (the runtime validator below still guards the actual wire value).
72
+ type Pinned<T extends SerpExtraction> = T;
73
+ export type ExtractionFromPage = Pinned<extracted.SerpExtraction>;
74
+
75
+ // Built once: stringifying the page function per call was the only cost of the thunk.
76
+ const SERP_EXTRACTION_EXPR = pageCallExpression(extractSerp, PAGE_TEXT_LIMIT);
55
77
 
56
78
  const buildSerpUrl = (query: string, limit: number): string =>
57
79
  `https://www.google.com/search?q=${encodeURIComponent(query)}&num=${limit}&hl=en`;
58
80
 
59
81
  const SerpExtractionSchema = Type.Object({
60
82
  anchors: Type.Array(
61
- Type.Object({ href: Type.String(), heading: Type.String(), snippet: Type.String() }),
83
+ Type.Object({
84
+ href: Type.String(),
85
+ heading: Type.String(),
86
+ snippet: Type.String(),
87
+ cite: Type.Optional(Type.String()),
88
+ }),
62
89
  ),
63
90
  pageText: Type.String(),
64
91
  });
65
92
 
66
93
  const serpExtractionValidator = Compile(SerpExtractionSchema);
67
94
 
95
+ export const parseSerpExtraction = (raw: string): Result<SerpExtraction, string> =>
96
+ parseJson(raw, serpExtractionValidator);
97
+
98
+ const SearchResultSchema = Type.Object({
99
+ title: Type.String(),
100
+ url: Type.String(),
101
+ snippet: Type.String(),
102
+ rank: Type.Number(),
103
+ });
104
+
105
+ const WebSearchDetailsSchema = Type.Object({
106
+ results: Type.Array(SearchResultSchema),
107
+ engine: Type.Literal("google"),
108
+ query: Type.String(),
109
+ render: ExpandableTextSchema,
110
+ fullOutputPath: Type.Optional(Type.String()),
111
+ });
112
+
113
+ export type WebSearchDetails = DetailsOf<typeof WebSearchDetailsSchema>;
114
+
68
115
  const formatResults = (query: string, results: ReadonlyArray<SearchResult>): string => {
69
116
  const lines = results.map((r) => `${r.rank}. ${r.title}\n ${r.url}\n ${r.snippet}`);
70
117
  return `${results.length} result(s) for "${query}":\n\n${lines.join("\n\n")}`;
71
118
  };
72
119
 
73
- export const webSearchTool = defineBrowserTool({
120
+ export const createWebSearchTool = (deps: WebSearchDeps) => defineBrowserTool({
74
121
  name: "browser_web_search",
75
122
  label: "Browser Web Search",
76
123
  description:
@@ -79,11 +126,13 @@ export const webSearchTool = defineBrowserTool({
79
126
  promptGuidelines: [
80
127
  "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.",
81
128
  "On zero results it fails with details.reason:'no_results' — rephrase the query and try again.",
129
+ "If results were on the page but none could be parsed it fails with details.reason:'extraction_mismatch' (plus anchorCount) — Google's markup changed; report it rather than retrying.",
82
130
  "Runs in its own isolated tab and never disturbs the user's current tab.",
83
131
  ],
84
132
  parameters: WebSearchArgs,
133
+ details: WebSearchDetailsSchema,
85
134
  concurrency: "serialized",
86
- async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
135
+ async handler(args, { client, signal }): Promise<Result<ToolOk<WebSearchDetails>, ToolErr>> {
87
136
  const limit = args.limit ?? 10;
88
137
  const serpUrl = buildSerpUrl(args.query, limit);
89
138
 
@@ -98,24 +147,36 @@ export const webSearchTool = defineBrowserTool({
98
147
  const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
99
148
  if (!loaded.success) return err(loaded.error);
100
149
 
101
- const extracted = await evalInIsolatedTab(client, tab, buildSerpExtractionExpr(), isJsonText);
150
+ const extracted = await evalInIsolatedTab(client, tab, SERP_EXTRACTION_EXPR, isJsonText);
102
151
  if (!extracted.success) return err(extracted.error);
103
152
 
104
- const parsedJson = parseJson(extracted.data, serpExtractionValidator);
153
+ const parsedJson = parseSerpExtraction(extracted.data);
105
154
  if (!parsedJson.success) {
106
155
  return err({ kind: "internal", message: `SERP extraction returned an unexpected shape: ${parsedJson.error}` });
107
156
  }
108
157
  const extraction: SerpExtraction = parsedJson.data;
109
158
 
110
- const results = parseGoogleSerp(extraction.anchors, limit);
111
- const verdict = classifySerp(extraction.pageText, results.length);
112
- if (verdict !== "ok") {
159
+ const resolved = await resolveGotoTargets(extraction.anchors, deps, signal);
160
+ const results = parseGoogleSerp(extraction.anchors, limit, resolved);
161
+ const anchorCount = extraction.anchors.length;
162
+ const verdict = classifySerp(extraction.pageText, results.length, anchorCount);
163
+ if (verdict === "captcha") {
113
164
  return err({
114
165
  kind: "invalid_state",
115
- message: verdict === "captcha" ? "Google served a CAPTCHA / bot wall" : "no results found",
166
+ message: "Google served a CAPTCHA / bot wall",
116
167
  details: { reason: verdict, serpUrl },
117
168
  });
118
169
  }
170
+ if (verdict === "extraction_mismatch") {
171
+ return err({
172
+ kind: "invalid_state",
173
+ message: `found ${anchorCount} result anchor(s) but none parsed to an external url (Google markup may have changed)`,
174
+ details: { reason: verdict, anchorCount, serpUrl },
175
+ });
176
+ }
177
+ if (verdict === "no_results") {
178
+ return err({ kind: "invalid_state", message: "no results found", details: { reason: verdict, serpUrl } });
179
+ }
119
180
 
120
181
  const body = formatResults(args.query, results);
121
182
  const truncated = await applyTruncation(body, "search");
@@ -137,7 +198,9 @@ export const webSearchTool = defineBrowserTool({
137
198
  await closeIsolatedTab(client, tab);
138
199
  }
139
200
  },
140
- renderResult(result, expanded, theme) {
141
- return renderExpandableText("web_search", result, expanded, theme);
201
+ renderResult(result, expanded) {
202
+ return renderExpandableText(result.details.render, expanded);
142
203
  },
143
204
  });
205
+
206
+ export const webSearchTool = createWebSearchTool({ resolveRedirect: fetchRedirectTarget });