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.
- package/CHANGELOG.md +56 -0
- package/README.md +132 -0
- package/package.json +15 -7
- package/skills/pi-browser-harness/SKILL.md +89 -2
- package/src/cdp/commands.ts +205 -14
- package/src/cdp/console-buffer.ts +37 -23
- package/src/cdp/discovery.ts +57 -25
- package/src/cdp/events.ts +9 -3
- package/src/cdp/network-buffer.ts +38 -32
- package/src/cdp/ownership.ts +22 -4
- package/src/cdp/record-store.ts +2 -2
- package/src/cdp/session.ts +358 -216
- package/src/cdp/target-factory.ts +34 -15
- package/src/cdp/types.ts +17 -1
- package/src/client.ts +127 -54
- package/src/daemon/bridge.ts +110 -349
- package/src/daemon/connection.ts +323 -0
- package/src/daemon/index.ts +77 -48
- package/src/daemon/lines.ts +40 -0
- package/src/daemon/main.ts +12 -0
- package/src/daemon/protocol.ts +55 -25
- package/src/daemon/server.ts +100 -63
- package/src/daemon/socket.ts +10 -0
- package/src/daemon/spawn.ts +21 -22
- package/src/daemon/transport.ts +80 -49
- package/src/domains/ax-tree.ts +27 -8
- package/src/domains/cdp-call.ts +14 -7
- package/src/domains/click.ts +2 -2
- package/src/domains/concurrency.ts +50 -0
- package/src/domains/console.ts +20 -64
- package/src/domains/drag.ts +26 -28
- package/src/domains/element-call.ts +102 -68
- package/src/domains/files.ts +13 -9
- package/src/domains/form-batch.ts +13 -10
- package/src/domains/form.ts +78 -107
- package/src/domains/headers.ts +2 -2
- package/src/domains/history.ts +4 -4
- package/src/domains/io.ts +35 -0
- package/src/domains/isolated-tab.ts +6 -12
- package/src/domains/js.ts +67 -46
- package/src/domains/keyboard.ts +14 -11
- package/src/domains/navigate.ts +102 -66
- package/src/domains/network.ts +55 -95
- package/src/domains/page/fill.page.ts +139 -0
- package/src/domains/page/form.page.ts +61 -0
- package/src/domains/page/inject.ts +37 -0
- package/src/domains/page/keyboard.page.ts +16 -0
- package/src/domains/page/live-value.page.ts +10 -0
- package/src/domains/page/read-page.page.ts +51 -0
- package/src/domains/page/recipe.page.ts +82 -0
- package/src/domains/page/serp.page.ts +42 -0
- package/src/domains/page.ts +18 -51
- package/src/domains/poll.ts +42 -0
- package/src/domains/readpage/read-page.ts +48 -53
- package/src/domains/ref-resolve.ts +43 -29
- package/src/domains/ref-signature.ts +11 -0
- package/src/domains/render.ts +12 -23
- package/src/domains/screenshot-capture.ts +4 -2
- package/src/domains/screenshot.ts +13 -10
- package/src/domains/scroll.ts +4 -4
- package/src/domains/search/google-serp.ts +78 -8
- package/src/domains/search/redirect-resolver.ts +41 -0
- package/src/domains/search/web-search.ts +103 -40
- package/src/domains/snapshot.ts +81 -78
- package/src/domains/tab-resolve.ts +36 -0
- package/src/domains/tabs.ts +18 -69
- package/src/domains/target.ts +1 -1
- package/src/index.ts +101 -33
- package/src/profile/bind.ts +45 -14
- package/src/profile/browser-process.ts +50 -12
- package/src/profile/command.ts +20 -12
- package/src/profile/launch.ts +13 -9
- package/src/profile/list.ts +9 -13
- package/src/profile/store.ts +2 -1
- package/src/prompt.ts +34 -8
- package/src/recipes/command.ts +96 -0
- package/src/recipes/compile.ts +198 -0
- package/src/recipes/find.ts +49 -0
- package/src/recipes/journal.ts +125 -0
- package/src/recipes/recipe.ts +215 -0
- package/src/recipes/recordable.ts +359 -0
- package/src/recipes/replay.ts +354 -0
- package/src/recipes/run-tool.ts +132 -0
- package/src/recipes/save-tool.ts +247 -0
- package/src/recipes/store.ts +103 -0
- package/src/recipes/trust.ts +172 -0
- package/src/registry.ts +69 -4
- package/src/schemas/parse.ts +2 -2
- package/src/setup.ts +28 -19
- package/src/state.ts +2 -1
- package/src/util/debug.ts +7 -1
- package/src/util/guards.ts +3 -0
- package/src/util/js-source.ts +28 -0
- package/src/util/mutex.ts +1 -1
- package/src/util/paths.ts +3 -2
- package/src/util/result.ts +8 -0
- package/src/util/sharp-shim.ts +18 -11
- package/src/util/sleep.ts +18 -0
- package/src/util/tool.ts +185 -114
- package/src/util/truncate.ts +1 -1
- package/tsconfig.json +2 -1
- package/src/domains/fill-engine.ts +0 -80
package/src/domains/scroll.ts
CHANGED
|
@@ -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
|
|
30
|
-
if ("dialog"
|
|
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 =
|
|
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 (
|
|
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 = (
|
|
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 =
|
|
66
|
-
if (
|
|
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 {
|
|
16
|
-
import {
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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({
|
|
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
|
|
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
|
|
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,
|
|
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 =
|
|
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
|
|
111
|
-
const
|
|
112
|
-
|
|
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:
|
|
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
|
|
141
|
-
return renderExpandableText(
|
|
201
|
+
renderResult(result, expanded) {
|
|
202
|
+
return renderExpandableText(result.details.render, expanded);
|
|
142
203
|
},
|
|
143
204
|
});
|
|
205
|
+
|
|
206
|
+
export const webSearchTool = createWebSearchTool({ resolveRedirect: fetchRedirectTarget });
|