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.
- package/CHANGELOG.md +62 -0
- package/README.md +102 -1
- package/package.json +13 -7
- package/skills/pi-browser-harness/SKILL.md +84 -0
- package/src/cdp/commands.ts +204 -14
- package/src/cdp/console-buffer.ts +37 -23
- package/src/cdp/discovery.ts +72 -37
- package/src/cdp/events.ts +8 -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 +320 -217
- package/src/cdp/target-factory.ts +34 -15
- package/src/cdp/types.ts +17 -1
- package/src/client.ts +76 -43
- package/src/daemon/bridge.ts +115 -191
- 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 +84 -27
- package/src/daemon/transport.ts +88 -52
- package/src/domains/ax-tree.ts +8 -8
- package/src/domains/cdp-call.ts +14 -7
- package/src/domains/click.ts +2 -7
- package/src/domains/concurrency.ts +50 -0
- package/src/domains/console.ts +20 -66
- package/src/domains/drag.ts +26 -28
- package/src/domains/element-call.ts +102 -68
- package/src/domains/files.ts +64 -11
- package/src/domains/form-batch.ts +13 -11
- package/src/domains/form.ts +79 -116
- package/src/domains/headers.ts +89 -0
- package/src/domains/history.ts +7 -7
- package/src/domains/io.ts +35 -0
- package/src/domains/isolated-tab.ts +6 -12
- package/src/domains/js.ts +68 -53
- package/src/domains/keyboard.ts +16 -18
- package/src/domains/navigate.ts +102 -69
- package/src/domains/network.ts +56 -98
- 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/serp.page.ts +39 -0
- package/src/domains/page.ts +19 -58
- package/src/domains/poll.ts +42 -0
- package/src/domains/readpage/read-page.ts +48 -54
- 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 -14
- package/src/domains/scroll.ts +4 -5
- package/src/domains/search/google-serp.ts +1 -1
- package/src/domains/search/web-search.ts +38 -34
- package/src/domains/setup.ts +0 -2
- package/src/domains/snapshot.ts +72 -77
- package/src/domains/tab-resolve.ts +36 -0
- package/src/domains/tabs.ts +19 -78
- package/src/domains/target.ts +1 -1
- package/src/domains/viewport.ts +0 -1
- package/src/index.ts +100 -39
- 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 +42 -117
- package/src/registry.ts +68 -4
- package/src/schemas/parse.ts +2 -2
- package/src/setup.ts +28 -19
- package/src/state.ts +33 -2
- package/src/util/debug.ts +7 -1
- package/src/util/guards.ts +3 -0
- package/src/util/mutex.ts +1 -1
- package/src/util/paths.ts +12 -1
- 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 +163 -114
- package/src/util/truncate.ts +1 -1
- package/tsconfig.json +2 -1
- 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
|
|
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
|
-
|
|
47
|
-
|
|
47
|
+
export type RefRefresh = {
|
|
48
|
+
readonly prev: ReadonlyMap<string, RefSignature>;
|
|
49
|
+
readonly cur: ReadonlyMap<string, RefSignature>;
|
|
50
|
+
};
|
|
48
51
|
|
|
49
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
80
|
+
cur.set(ref, signatureOf(node));
|
|
77
81
|
}
|
|
78
|
-
session.setRefMap(refMap,
|
|
82
|
+
session.setRefMap(refMap, cur);
|
|
83
|
+
return ok({ prev, cur });
|
|
84
|
+
};
|
|
79
85
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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}] ${
|
|
96
|
-
} else if (before !== sig) {
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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
|
|
107
|
-
if (!curByKey.has(key)) removed.push(` ${
|
|
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
|
+
});
|
package/src/domains/render.ts
CHANGED
|
@@ -1,32 +1,21 @@
|
|
|
1
|
-
import {
|
|
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 {
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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,
|
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" })),
|
|
@@ -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
|
|
31
|
-
if ("dialog"
|
|
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 =
|
|
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 {
|
|
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
|
-
|
|
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
|
-
`;
|
|
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
|
|
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,
|
|
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 =
|
|
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
|
|
142
|
-
return renderExpandableText(
|
|
145
|
+
renderResult(result, expanded) {
|
|
146
|
+
return renderExpandableText(result.details.render, expanded);
|
|
143
147
|
},
|
|
144
148
|
});
|
package/src/domains/setup.ts
CHANGED
|
@@ -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,
|