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
@@ -0,0 +1,61 @@
1
+ // Page-side code for browser_focus, browser_select_option and browser_set_checked. See fill.page.ts for the rules.
2
+ import type { FormControl, PageResult } from "./fill.page";
3
+
4
+ export type FocusResult = { readonly status: "ok"; readonly tag: string } | { readonly status: "not_focusable"; readonly tag: string };
5
+
6
+ export function focusElement(el: Element & { focus?: () => void }): FocusResult {
7
+ if (typeof el.focus !== "function") return { status: "not_focusable", tag: el.tagName };
8
+ el.focus();
9
+ return document.activeElement === el ? { status: "ok", tag: el.tagName } : { status: "not_focusable", tag: el.tagName };
10
+ }
11
+
12
+ export type SelectOption = { readonly value: string; readonly label: string };
13
+
14
+ export type SelectResult =
15
+ | { readonly status: "ok"; readonly value: string; readonly label: string }
16
+ | { readonly status: "not_select"; readonly tag: string }
17
+ | { readonly status: "no_match"; readonly options: ReadonlyArray<SelectOption> };
18
+
19
+ // null sentinels distinguish "not provided" from a real empty-string match.
20
+ export type SelectWanted = {
21
+ readonly wv: string | null;
22
+ readonly wl: string | null;
23
+ readonly wi: number | null;
24
+ };
25
+
26
+ export function selectOption(el: FormControl, arg: SelectWanted): SelectResult {
27
+ if (el.tagName !== "SELECT" || el.options === undefined) return { status: "not_select", tag: el.tagName };
28
+ const opts = Array.from(el.options);
29
+ const wv = arg.wv, wl = arg.wl, wi = arg.wi;
30
+ let opt: HTMLOptionElement | null = null;
31
+ if (wi !== null) opt = opts[wi] ?? null;
32
+ else if (wv !== null) opt = opts.find((o) => o.value === wv) ?? null;
33
+ else if (wl !== null) opt = opts.find((o) => o.text === wl) ?? null;
34
+ if (!opt) return { status: "no_match", options: opts.map((o) => ({ value: o.value, label: o.text })) };
35
+ el.value = opt.value;
36
+ el.dispatchEvent(new Event("input", { bubbles: true }));
37
+ el.dispatchEvent(new Event("change", { bubbles: true }));
38
+ return { status: "ok", value: opt.value, label: opt.text };
39
+ }
40
+
41
+ export function setChecked(el: FormControl, checked: boolean): PageResult {
42
+ const tag = el.tagName.toLowerCase();
43
+ const type = (el.type ?? "").toLowerCase();
44
+ if (tag !== "input" || (type !== "checkbox" && type !== "radio")) return { ok: false, reason: "ref is not a checkbox or radio" };
45
+ if (el.disabled) return { ok: false, reason: "element is disabled" };
46
+ const want = checked;
47
+ let changed = false;
48
+ if (el.checked !== want) {
49
+ try {
50
+ el.click();
51
+ } catch {
52
+ /* a click handler may throw; the direct write below still applies the state */
53
+ }
54
+ if (el.checked !== want) {
55
+ el.checked = want;
56
+ el.dispatchEvent(new Event("change", { bubbles: true }));
57
+ }
58
+ changed = true;
59
+ }
60
+ return { ok: true, kind: type, checked: el.checked, changed, tag: el.tagName };
61
+ }
@@ -0,0 +1,37 @@
1
+ // The node-side half of the page-function scheme.
2
+ //
3
+ // Page code lives in `*.page.ts` modules next to this file, type-checked by tsconfig.page.json against the DOM lib
4
+ // only. At runtime those modules are plain TypeScript functions that pi's loader (jiti) or tsx strips the types from,
5
+ // so `fn.toString()` is the exact JavaScript to ship into Chrome. Two consequences shape this file:
6
+ // - a page function must be a `function` declaration, not an arrow: tsx emits `x=>...` for single-parameter arrows,
7
+ // which is not a valid Runtime.callFunctionOn declaration, and jiti and tsx must agree on the leading token
8
+ // - a page function must be self-contained (no module-scope references), because only its own text travels;
9
+ // test/domains/page-functions-test.ts checks that for every exported page function
10
+ import { safeJs } from "../../util/js-template";
11
+
12
+ // Any page function. `this`-typed functions (the element handed over by Runtime.callFunctionOn) satisfy this too.
13
+ export type PageFunction = (...args: never[]) => unknown;
14
+
15
+ const DECLARATION = /^function\b/;
16
+
17
+ // The source text of a page function, as the `functionDeclaration` of Runtime.callFunctionOn. Throws at import time
18
+ // (callers evaluate it into module constants) when the loader has produced something other than a function declaration.
19
+ export const pageFunctionSource = (fn: PageFunction): string => {
20
+ const source = fn.toString();
21
+ if (!DECLARATION.test(source)) {
22
+ throw new Error(
23
+ `page function ${fn.name || "(anonymous)"} must be a \`function\` declaration; the loader produced: ${source.slice(0, 60)}`,
24
+ );
25
+ }
26
+ return source;
27
+ };
28
+
29
+ // The `functionDeclaration` for Runtime.callFunctionOn of an ELEMENT function: one whose first parameter is the element.
30
+ // CDP hands the element over as `this`, so this wrapper forwards it as the first argument, keeping the page functions
31
+ // free of `this` (plain to type, plain to call in tests).
32
+ export const elementFunctionSource = (fn: PageFunction): string =>
33
+ "function (...args) { return (" + pageFunctionSource(fn) + ")(this, ...args); }";
34
+
35
+ // An expression for Runtime.evaluate that calls the page function with `args`, each JSON-encoded through safeJs.
36
+ export const pageCallExpression = (fn: PageFunction, ...args: ReadonlyArray<unknown>): string =>
37
+ "(" + pageFunctionSource(fn) + ")(" + args.map((a) => safeJs`${a}`).join(", ") + ")";
@@ -0,0 +1,16 @@
1
+ // Page-side code for browser_dispatch_key. See fill.page.ts for the rules.
2
+
3
+ export type KeyEventSpec = {
4
+ readonly type: string;
5
+ readonly key: string;
6
+ // Legacy handlers branch on e.keyCode/e.which rather than e.key, so both are populated from this.
7
+ readonly code: number;
8
+ };
9
+
10
+ // Dispatches a synthetic KeyboardEvent on `el`; returns the number of elements hit (always 1 here).
11
+ export function dispatchKeyEvent(el: Element, spec: KeyEventSpec): number {
12
+ el.dispatchEvent(
13
+ new KeyboardEvent(spec.type, { key: spec.key, keyCode: spec.code, which: spec.code, bubbles: true, cancelable: true }),
14
+ );
15
+ return 1;
16
+ }
@@ -0,0 +1,10 @@
1
+ // Page-side code for the snapshot's live value read. See fill.page.ts for the rules.
2
+
3
+ // The AX `value` is stale for freshly-typed or controlled inputs, so the live DOM property is read instead.
4
+ export function liveValue(el: Element): string | null {
5
+ if ("type" in el && (el.type === "checkbox" || el.type === "radio")) {
6
+ return "checked" in el && el.checked ? "checked" : "unchecked";
7
+ }
8
+ if ("value" in el && typeof el.value === "string") return el.value;
9
+ return null;
10
+ }
@@ -0,0 +1,51 @@
1
+ // Page-side code for browser_read_page. See fill.page.ts for the rules.
2
+
3
+ export type ContentBlockKind = "paragraph" | "heading" | "listitem" | "blockquote" | "other";
4
+
5
+ export type ContentBlock = {
6
+ readonly kind: ContentBlockKind;
7
+ readonly text: string;
8
+ readonly linkTextLength: number;
9
+ readonly inBoilerplate: boolean;
10
+ };
11
+
12
+ export type PageCapture = {
13
+ readonly url: string;
14
+ readonly title: string;
15
+ readonly blocks: ReadonlyArray<ContentBlock>;
16
+ readonly bodyText: string;
17
+ };
18
+
19
+ // Returns the capture as JSON text (not an object) so the isolated-tab evaluator can keep its string guard.
20
+ export function capturePage(bodyTextLimit: number): string {
21
+ const BOILERPLATE = new Set(["NAV", "HEADER", "FOOTER", "ASIDE"]);
22
+ const selector = "p, h1, h2, h3, h4, h5, h6, li, blockquote";
23
+ const root = document.querySelector("article, main, [role=main]") ?? document.body;
24
+ const blocks: ContentBlock[] = [];
25
+ for (const el of root.querySelectorAll<HTMLElement>(selector)) {
26
+ const text = el.innerText.replace(/\s+/g, " ").trim();
27
+ if (!text) continue;
28
+ let linkTextLength = 0;
29
+ for (const a of el.querySelectorAll("a")) linkTextLength += a.innerText.length;
30
+ const tag = el.tagName;
31
+ const kind: ContentBlockKind = /^H[1-6]$/.test(tag)
32
+ ? "heading"
33
+ : tag === "LI"
34
+ ? "listitem"
35
+ : tag === "BLOCKQUOTE"
36
+ ? "blockquote"
37
+ : tag === "P"
38
+ ? "paragraph"
39
+ : "other";
40
+ // Inside nav/header/footer/aside (by tag or landmark role) at any depth.
41
+ let inBoilerplate = false;
42
+ for (let n: Element | null = el; n && !inBoilerplate; n = n.parentElement) {
43
+ const role = n.getAttribute("role");
44
+ inBoilerplate = BOILERPLATE.has(n.tagName) || role === "navigation" || role === "banner" || role === "contentinfo";
45
+ }
46
+ blocks.push({ kind, text, linkTextLength, inBoilerplate });
47
+ }
48
+ const bodyText = document.body.innerText.replace(/\n{3,}/g, "\n\n").slice(0, bodyTextLimit);
49
+ const capture: PageCapture = { url: location.href, title: document.title, blocks, bodyText };
50
+ return JSON.stringify(capture);
51
+ }
@@ -0,0 +1,39 @@
1
+ // Page-side code for browser_web_search: pulls the organic result anchors off a Google results page. See fill.page.ts for the rules.
2
+
3
+ export type SerpAnchor = {
4
+ readonly href: string;
5
+ readonly heading: string;
6
+ readonly snippet: string;
7
+ };
8
+
9
+ export type SerpExtraction = {
10
+ readonly anchors: ReadonlyArray<SerpAnchor>;
11
+ readonly pageText: string;
12
+ };
13
+
14
+ // Returns the extraction as JSON text (not an object) so the isolated-tab evaluator can keep its string guard.
15
+ export function extractSerp(pageTextLimit: number): string {
16
+ const main = document.querySelector<HTMLElement>("#search, #rso, #main") ?? document.body;
17
+ const headings = Array.from(main.querySelectorAll<HTMLElement>("a h3"));
18
+ const seen = new Set<string>();
19
+ const anchors: SerpAnchor[] = [];
20
+ for (const h3 of headings) {
21
+ const a = h3.closest<HTMLAnchorElement>("a[href]");
22
+ if (!a) continue;
23
+ const href = a.href;
24
+ if (!href || seen.has(href)) continue;
25
+ seen.add(href);
26
+ const container: HTMLElement | null =
27
+ a.closest<HTMLElement>("div.g") ??
28
+ a.closest<HTMLElement>("div[data-hveid]") ??
29
+ a.parentElement?.parentElement ??
30
+ a.parentElement;
31
+ const containerText = container ? container.innerText : "";
32
+ const heading = h3.innerText || h3.textContent;
33
+ const snippet = containerText.replace(heading, "").replace(/\s+/g, " ").trim().slice(0, 500);
34
+ anchors.push({ href, heading, snippet });
35
+ }
36
+ const pageText = document.body.innerText.slice(0, pageTextLimit);
37
+ const extraction: SerpExtraction = { anchors, pageText };
38
+ return JSON.stringify(extraction);
39
+ }
@@ -1,25 +1,9 @@
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 { evalJs } from "./cdp-call";
4
+ import { fromClient } from "./cdp-call";
5
5
  import { safeJs } from "../util/js-template";
6
-
7
- const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
8
- new Promise((resolve, reject) => {
9
- if (signal?.aborted) {
10
- reject(signal.reason ?? new Error("aborted"));
11
- return;
12
- }
13
- const onAbort = (): void => {
14
- clearTimeout(timer);
15
- reject(signal?.reason ?? new Error("aborted"));
16
- };
17
- const timer = setTimeout(() => {
18
- signal?.removeEventListener("abort", onAbort);
19
- resolve();
20
- }, ms);
21
- signal?.addEventListener("abort", onAbort, { once: true });
22
- });
6
+ import { pollUntil, READY_STATE_COMPLETE, sleep } from "./poll";
23
7
 
24
8
  export const pageInfoTool = defineBrowserTool({
25
9
  name: "browser_page_info",
@@ -28,17 +12,14 @@ export const pageInfoTool = defineBrowserTool({
28
12
  "Get current page state: URL, title, viewport size, scroll position, page dimensions. If a JS dialog is open, returns dialog info instead.",
29
13
  promptSnippet: "Get current page URL, title, viewport, and scroll position",
30
14
  promptGuidelines: [
31
- "Use browser_page_info to quickly check what page you're on and whether a JS dialog is blocking interaction.",
32
- "If browser_page_info returns a dialog, use browser_handle_dialog before any other browser actions.",
33
- "JS dialogs freeze the page's JS thread, so no other interaction works until the dialog is handled.",
34
- "browser_page_info auto-detects alert, confirm, prompt, and beforeunload dialogs.",
15
+ "If browser_page_info returns a dialog, call browser_handle_dialog before any other browser actions: dialogs freeze the page's JS thread.",
35
16
  ],
36
17
  parameters: Type.Object({}),
37
18
  concurrency: "parallel",
38
19
  async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
39
- const r = await client.pageInfo();
40
- if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
41
- if ("dialog" in r.data) {
20
+ const r = fromClient(await client.pageInfo(), "pageInfo");
21
+ if (!r.success) return r;
22
+ if (r.data.kind === "dialog") {
42
23
  const d = r.data.dialog;
43
24
  return ok({
44
25
  text: `⚠️ DIALOG OPEN: ${d.type}\nMessage: ${d.message}${d.defaultPrompt ? `\nDefault: ${d.defaultPrompt}` : ""}\n\nUse browser_handle_dialog to accept or dismiss.`,
@@ -66,12 +47,9 @@ export const waitTool = defineBrowserTool({
66
47
  parameters: WaitArgs,
67
48
  concurrency: "parallel",
68
49
  async handler(args, { signal }): Promise<Result<ToolOk, ToolErr>> {
69
- try {
70
- await sleep(Math.round(args.seconds * 1000), signal);
71
- return ok({ text: `Waited ${args.seconds}s` });
72
- } catch (e) {
73
- return err({ kind: "internal", message: e instanceof Error ? e.message : String(e) });
74
- }
50
+ await sleep(Math.round(args.seconds * 1000), signal);
51
+ if (signal?.aborted) return err({ kind: "timeout", message: `Aborted before ${args.seconds}s elapsed` });
52
+ return ok({ text: `Waited ${args.seconds}s` });
75
53
  },
76
54
  });
77
55
 
@@ -87,23 +65,15 @@ export const waitForLoadTool = defineBrowserTool({
87
65
  promptSnippet: "Wait for the page to finish loading",
88
66
  promptGuidelines: [
89
67
  "Call after browser_navigate / browser_open_urls before extracting data.",
90
- "Returns when readyState becomes 'complete' OR the timeout elapses.",
91
68
  ],
92
69
  parameters: WaitForLoadArgs,
93
70
  concurrency: "serialized",
94
71
  async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
95
72
  const timeoutMs = (args.timeout ?? 15) * 1000;
96
- const start = Date.now();
97
- while (Date.now() - start < timeoutMs) {
98
- if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
99
- const r = await evalJs(client, safeJs`document.readyState`);
100
- if (r.success && r.data === "complete") {
101
- const ms = Date.now() - start;
102
- return ok({ text: `Page loaded in ${Math.round(ms / 100) / 10}s`, details: { ms } });
103
- }
104
- await new Promise((res) => setTimeout(res, 50));
105
- }
106
- return err({ kind: "timeout", message: `Page did not finish loading in ${args.timeout ?? 15}s` });
73
+ const r = await pollUntil(client, READY_STATE_COMPLETE, { timeoutMs, signal, what: "page load" });
74
+ if (!r.success) return r;
75
+ const ms = r.data.elapsedMs;
76
+ return ok({ text: `Page loaded in ${Math.round(ms / 100) / 10}s`, details: { ms } });
107
77
  },
108
78
  });
109
79
 
@@ -122,14 +92,12 @@ export const waitForTool = defineBrowserTool({
122
92
  promptSnippet: "Wait for an element or text to appear (or an element to disappear)",
123
93
  promptGuidelines: [
124
94
  "Use before browser_fill / browser_click on dynamic pages so you act after the element renders.",
125
- "Provide selector (default: wait until present; gone:true: wait until absent) or text.",
126
- "Returns a typed timeout error if the condition isn't met within the timeout.",
127
95
  ],
128
96
  parameters: WaitForArgs,
129
97
  concurrency: "parallel",
130
98
  async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
131
99
  if (args.selector === undefined && args.text === undefined) {
132
- return err({ kind: "invalid_state", message: "Provide a selector or text to wait for." });
100
+ return err({ kind: "invalid_args", message: "Provide a selector or text to wait for." });
133
101
  }
134
102
  const gone = args.gone ?? false;
135
103
  const timeoutMs = (args.timeout ?? 5) * 1000;
@@ -137,18 +105,11 @@ export const waitForTool = defineBrowserTool({
137
105
  args.selector !== undefined
138
106
  ? safeJs`(() => { const found = !!document.querySelector(${args.selector}); return ${gone} ? !found : found; })()`
139
107
  : safeJs`(() => { const t = document.body ? document.body.innerText : ""; return t.includes(${args.text}); })()`;
140
- const start = Date.now();
141
- while (Date.now() - start < timeoutMs) {
142
- if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
143
- const r = await evalJs(client, expr);
144
- if (r.success && r.data === true) {
145
- const ms = Date.now() - start;
146
- const what = args.selector !== undefined ? `${args.selector}${gone ? " gone" : ""}` : `text "${args.text}"`;
147
- return ok({ text: `Condition met (${what}) in ${Math.round(ms / 100) / 10}s`, details: { ms } });
148
- }
149
- await sleep(50, signal);
150
- }
151
108
  const what = args.selector !== undefined ? `${args.selector}${gone ? " to disappear" : ""}` : `text "${args.text}"`;
152
- return err({ kind: "timeout", message: `Timed out after ${args.timeout ?? 5}s waiting for ${what}` });
109
+ const r = await pollUntil(client, expr, { timeoutMs, signal, what });
110
+ if (!r.success) return r;
111
+ const ms = r.data.elapsedMs;
112
+ const met = args.selector !== undefined ? `${args.selector}${gone ? " gone" : ""}` : `text "${args.text}"`;
113
+ return ok({ text: `Condition met (${met}) in ${Math.round(ms / 100) / 10}s`, details: { ms } });
153
114
  },
154
115
  });
@@ -0,0 +1,42 @@
1
+ import { sleep } from "../util/sleep";
2
+ import type { BrowserClient } from "../client";
3
+ import { type Result, err, ok } from "../util/result";
4
+ import type { ToolErr } from "../util/tool";
5
+ import { evalJs } from "./cdp-call";
6
+
7
+ export type PollOptions = {
8
+ readonly timeoutMs: number;
9
+ readonly signal?: AbortSignal | undefined;
10
+ readonly sessionId?: string | undefined;
11
+ readonly intervalMs?: number | undefined;
12
+ // Names the condition in the timeout message, e.g. "page load".
13
+ readonly what?: string | undefined;
14
+ };
15
+
16
+ const DEFAULT_INTERVAL_MS = 50;
17
+
18
+ export { sleep } from "../util/sleep";
19
+
20
+ // Evaluates `expression` in the page until it yields `true`. A deadline or an abort both surface as kind "timeout";
21
+ // evaluation errors (e.g. mid-navigation) are retried until the deadline.
22
+ export const pollUntil = async (
23
+ client: BrowserClient,
24
+ expression: string,
25
+ opts: PollOptions,
26
+ ): Promise<Result<{ readonly elapsedMs: number }, ToolErr>> => {
27
+ const start = Date.now();
28
+ const interval = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
29
+ const what = opts.what ?? "condition";
30
+ const seconds = Math.round(opts.timeoutMs / 100) / 10;
31
+ while (Date.now() - start < opts.timeoutMs) {
32
+ if (opts.signal?.aborted) {
33
+ return err({ kind: "timeout", message: `Aborted while waiting for ${what}` });
34
+ }
35
+ const r = await evalJs(client, expression, opts.sessionId);
36
+ if (r.success && r.data === true) return ok({ elapsedMs: Date.now() - start });
37
+ await sleep(interval, opts.signal);
38
+ }
39
+ return err({ kind: "timeout", message: `Timed out after ${seconds}s waiting for ${what}` });
40
+ };
41
+
42
+ export const READY_STATE_COMPLETE = `document.readyState === "complete"`;
@@ -1,10 +1,15 @@
1
+ import { borrowSession } from "../../cdp/target-factory";
1
2
  import { Type } from "typebox";
2
3
  import { Compile } from "typebox/compile";
3
4
  import { parseJson } from "../../schemas/parse";
4
5
  import { type Result, err, ok } from "../../util/result";
5
6
  import { applyTruncation } from "../../util/truncate";
6
- import { defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
7
- import { cdpCallBrowser, evalJs } from "../cdp-call";
7
+ import { type DetailsOf, defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
8
+ import type { BrowserClient } from "../../client";
9
+ import { evalJs, fromClient } from "../cdp-call";
10
+ import { pageCallExpression } from "../page/inject";
11
+ import { capturePage } from "../page/read-page.page";
12
+ import type * as captured from "../page/read-page.page";
8
13
  import {
9
14
  closeIsolatedTab,
10
15
  evalInIsolatedTab,
@@ -14,7 +19,7 @@ import {
14
19
  openIsolatedTab,
15
20
  waitForIsolatedLoad,
16
21
  } from "../isolated-tab";
17
- import { renderExpandableText } from "../render";
22
+ import { ExpandableTextSchema, renderExpandableText } from "../render";
18
23
  import { extractReadable, type PageCapture, type ReadablePage } from "./readability";
19
24
 
20
25
  const LOAD_TIMEOUT_MS = 15_000;
@@ -48,42 +53,28 @@ const PageCaptureSchema = Type.Object({
48
53
 
49
54
  const pageCaptureValidator = Compile(PageCaptureSchema);
50
55
 
56
+ const ReadPageDetailsSchema = Type.Object({
57
+ title: Type.String(),
58
+ url: Type.String(),
59
+ wordCount: Type.Number(),
60
+ render: ExpandableTextSchema,
61
+ fullOutputPath: Type.Optional(Type.String()),
62
+ });
63
+
64
+ export type ReadPageDetails = DetailsOf<typeof ReadPageDetailsSchema>;
65
+
51
66
  const BODY_TEXT_LIMIT = 20_000;
52
67
 
53
- const buildPageCaptureExpr = (): string => `
54
- (() => {
55
- const BOILERPLATE = new Set(['NAV', 'HEADER', 'FOOTER', 'ASIDE']);
56
- const inBoilerplate = (el) => {
57
- for (let n = el; n; n = n.parentElement) {
58
- if (BOILERPLATE.has(n.tagName)) return true;
59
- const role = n.getAttribute && n.getAttribute('role');
60
- if (role === 'navigation' || role === 'banner' || role === 'contentinfo') return true;
61
- }
62
- return false;
63
- };
64
- const kindOf = (tag) => {
65
- if (/^H[1-6]$/.test(tag)) return 'heading';
66
- if (tag === 'LI') return 'listitem';
67
- if (tag === 'BLOCKQUOTE') return 'blockquote';
68
- if (tag === 'P') return 'paragraph';
69
- return 'other';
70
- };
71
- const selector = 'p, h1, h2, h3, h4, h5, h6, li, blockquote';
72
- const root = document.querySelector('article, main, [role=main]') || document.body;
73
- const blocks = [];
74
- for (const el of root.querySelectorAll(selector)) {
75
- const text = (el.innerText || '').replace(/\\s+/g, ' ').trim();
76
- if (!text) continue;
77
- let linkTextLength = 0;
78
- for (const a of el.querySelectorAll('a')) linkTextLength += (a.innerText || '').length;
79
- blocks.push({ kind: kindOf(el.tagName), text, linkTextLength, inBoilerplate: inBoilerplate(el) });
80
- }
81
- const bodyText = (document.body.innerText || '').replace(/\\n{3,}/g, '\\n\\n').slice(0, ${BODY_TEXT_LIMIT});
82
- return JSON.stringify({ url: location.href, title: document.title, blocks, bodyText });
83
- })()
84
- `;
68
+ // The page function declares the capture shape it produces; this pins it to the shape the readability pass consumes,
69
+ // so the two cannot drift apart silently (the runtime validator above still guards the actual wire value).
70
+ type Pinned<T extends PageCapture> = T;
71
+ export type CaptureFromPage = Pinned<captured.PageCapture>;
85
72
 
86
- const toPageCapture = (raw: unknown): PageCapture | undefined => {
73
+ // Built once: stringifying the page function per call was the only cost of the thunk.
74
+ const PAGE_CAPTURE_EXPR = pageCallExpression(capturePage, BODY_TEXT_LIMIT);
75
+
76
+ // Accepts the capture either as JSON text (isolated tab) or as the already-decoded value (owned tab).
77
+ export const toPageCapture = (raw: unknown): PageCapture | undefined => {
87
78
  if (typeof raw === "string") {
88
79
  const parsed = parseJson(raw, pageCaptureValidator);
89
80
  return parsed.success ? parsed.data : undefined;
@@ -91,7 +82,7 @@ const toPageCapture = (raw: unknown): PageCapture | undefined => {
91
82
  return pageCaptureValidator.Check(raw) ? raw : undefined;
92
83
  };
93
84
 
94
- const captureToResult = async (raw: unknown): Promise<Result<ToolOk, ToolErr>> => {
85
+ const captureToResult = async (raw: unknown): Promise<Result<ToolOk<ReadPageDetails>, ToolErr>> => {
95
86
  const parsed = toPageCapture(raw);
96
87
  if (parsed === undefined) return err({ kind: "internal", message: "page capture returned an unexpected shape" });
97
88
  const page: ReadablePage = extractReadable(parsed);
@@ -115,10 +106,10 @@ const captureToResult = async (raw: unknown): Promise<Result<ToolOk, ToolErr>> =
115
106
  };
116
107
 
117
108
  const readOpenedUrl = async (
118
- client: Parameters<typeof openIsolatedTab>[0],
109
+ client: BrowserClient,
119
110
  url: string,
120
111
  signal: AbortSignal | undefined,
121
- ): Promise<Result<ToolOk, ToolErr>> => {
112
+ ): Promise<Result<ToolOk<ReadPageDetails>, ToolErr>> => {
122
113
  const opened = await openIsolatedTab(client);
123
114
  if (!opened.success) return err(opened.error);
124
115
  const tab: IsolatedTab = opened.data;
@@ -127,27 +118,30 @@ const readOpenedUrl = async (
127
118
  if (!navigated.success) return err(navigated.error);
128
119
  const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
129
120
  if (!loaded.success) return err(loaded.error);
130
- const captured = await evalInIsolatedTab(client, tab, buildPageCaptureExpr(), isJsonText);
121
+ const captured = await evalInIsolatedTab(client, tab, PAGE_CAPTURE_EXPR, isJsonText);
131
122
  if (!captured.success) return err(captured.error);
132
- return captureToResult(captured.data);
123
+ return await captureToResult(captured.data);
133
124
  } finally {
134
125
  await closeIsolatedTab(client, tab);
135
126
  }
136
127
  };
137
128
 
138
129
  const readOwnedTab = async (
139
- client: Parameters<typeof openIsolatedTab>[0],
130
+ client: BrowserClient,
140
131
  targetId: string,
141
- ): Promise<Result<ToolOk, ToolErr>> => {
132
+ ): Promise<Result<ToolOk<ReadPageDetails>, ToolErr>> => {
142
133
  if (!client.owns(targetId)) {
143
134
  return err({ kind: "invalid_state", message: `Tab ${targetId} is not owned by this session.` });
144
135
  }
145
- const attached = await cdpCallBrowser(client, "Target.attachToTarget", { targetId, flatten: true });
146
- if (!attached.success) return attached;
147
- const sessionId = attached.data.sessionId;
148
- const captured = await evalJs(client, buildPageCaptureExpr(), sessionId);
149
- if (!captured.success) return captured;
150
- return captureToResult(captured.data);
136
+ const borrowed = await borrowSession(client, targetId);
137
+ if (!borrowed.success) return fromClient(borrowed, "Target.attachToTarget");
138
+ try {
139
+ const captured = await evalJs(client, PAGE_CAPTURE_EXPR, borrowed.data.sessionId);
140
+ if (!captured.success) return captured;
141
+ return await captureToResult(captured.data);
142
+ } finally {
143
+ await borrowed.data.release();
144
+ }
151
145
  };
152
146
 
153
147
  export const readPageTool = defineBrowserTool({
@@ -157,18 +151,18 @@ export const readPageTool = defineBrowserTool({
157
151
  "Read a page as clean article text — main content with nav/ads/boilerplate stripped. Pass a url (opened in an isolated tab, read, then closed) or a targetId of an owned tab. Reader-mode counterpart to browser_web_search.",
158
152
  promptSnippet: "Read a page's main content as clean text",
159
153
  promptGuidelines: [
160
- "Pass url to read an arbitrary page (opened + closed in its own tab, never disturbing your current tab), or targetId to read an already-open owned tab.",
161
154
  "Returns readable main-article text — use this over browser_snapshot/browser_execute_js when you want an article's content for reading or research.",
162
155
  "Boilerplate-heavy or structure-less pages fall back to bounded body text rather than erroring.",
163
156
  ],
164
157
  parameters: ReadPageArgs,
158
+ details: ReadPageDetailsSchema,
165
159
  concurrency: "parallel",
166
- async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
160
+ async handler(args, { client, signal }): Promise<Result<ToolOk<ReadPageDetails>, ToolErr>> {
167
161
  if (args.url !== undefined && args.url.length > 0) return readOpenedUrl(client, args.url, signal);
168
162
  if (args.targetId !== undefined && args.targetId.length > 0) return readOwnedTab(client, args.targetId);
169
- return err({ kind: "invalid_state", message: "provide either url or targetId" });
163
+ return err({ kind: "invalid_args", message: "provide either url or targetId" });
170
164
  },
171
- renderResult(result, expanded, theme) {
172
- return renderExpandableText("read_page", result, expanded, theme);
165
+ renderResult(result, expanded) {
166
+ return renderExpandableText(result.details.render, expanded);
173
167
  },
174
168
  });