repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(chrome-cdp): add extension-owned Chrome CDP tools

6fffc4a4bfa4941a3c8ab5299c9acb32f62e8c32

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (19)

README.md

Modified
67 67 | --- | --- | --- |
68 68 | `angel` | Tool-using investigative advisor backed by a configured model. | [README](extensions/angel/README.md) |
69 69 | `ask` | Structured single- and multiple-choice questions for humans. | [README](extensions/ask/README.md) |
70 +| `chrome-cdp` | Raw CDP commands, captures, and traces against extension-owned Chrome. | [README](extensions/chrome-cdp/README.md) |
70 71 | `context-size` | Context-window usage telemetry. | [README](extensions/context-size/README.md) |
71 72 | `continuity` | Continues unfinished work after context compaction. | [README](extensions/continuity/README.md) |
72 73 | `cost` | Token and spend telemetry. | [README](extensions/cost/README.md) |

extensions/chrome-cdp/README.md

Added
new file mode 100644
1 +# chrome-cdp
3 +Drive one extension-owned Chrome process from Pi using raw Chrome DevTools Protocol JSON.
4 +The root `pi-ext` package loads this extension; no separate package install is needed.
6 +## Usage
8 +- `/chrome` toggles the `chrome_cdp` tool and checks for a Chrome binary without launching it; first tool call starts Chrome with a temporary profile and random loopback debugging port.
9 +- Start Pi with `--chrome` to enable the tool at startup.
10 +- `/chrome close` stops Chrome and deactivates the tool; a sole managed `close` operation stops it without deactivating the tool.
11 +- Page-scoped CDP methods need an explicit `sessionId` from the returned status or `Target.attachToTarget`; browser-scoped methods omit it.
12 +- `operations` runs sequentially and stops on error; failed batches include `failedOperation` with zero-based `operation` and `kind`, plus zero-based `skipped` operations; use labeled replies as whole-value references such as `{{label.result.path}}`.
13 +- Managed operations include waits, screenshots, WebM video, performance traces, status, and close.
14 +- A labeled command supports one `wait` in each batch; use distinct labeled commands for separate waits.
15 +- Chrome's `/json/protocol` URL appears in status; consult it for the running browser's command schema.
17 +## Configuration
19 +Project `.pi/settings.json` overrides user settings per property under `"chrome-cdp"`:
21 +```json
23 + "chrome-cdp": {
24 + "profile": "work",
25 + "executablePath": "/path/to/chrome",
26 + "artifactDir": "/path/to/captures",
27 + "flags": []
28 + }
30 +```
32 +A named profile lives in extension-owned OS application data; omitting `profile` uses a disposable profile.
33 +Managed captures default to OS Downloads unless `artifactDir` is set; browser downloads use a separate temporary directory.
34 +`ffmpeg` is needed only for WebM recording.
35 +Set `PI_CHROME_CDP_DEBUG` to an owner-private JSONL path for bounded metadata-only diagnostics.
37 +Raw CDP is unrestricted and may access local URLs, browser data, or override download settings; managed capture paths are not a sandbox.
38 +Events, traces, browser profiles, and captures can contain secrets.
39 +Spool paths returned by a batch remain until its next batch starts or Chrome closes; when current-batch files consume the 16 MiB spool quota, later responses fail rather than deleting returned files.
40 +Replay returns only event files containing events after `replayFrom`; an evicted in-memory event returns `lost: true` without `spooled`, while `status.gaps` counts discarded spool data.
41 +Linux real-Chrome checks exist; macOS and Windows launch paths are not empirically verified.
43 +## Verification
45 +- `mise run //extensions/chrome-cdp:lint`
46 +- `mise run //extensions/chrome-cdp:test`
47 +- `mise run //extensions/chrome-cdp:check`
48 +- `mise run //extensions/chrome-cdp:e2e` runs real-Chrome acceptance checks and writes temporary profiles, test captures, and a named test profile outside this repository.
49 +- `mise run //extensions/chrome-cdp:bench -- 60 compare` measures large labeled-response handling; see [benchmark methodology](__bench__/README.md).

extensions/chrome-cdp/__bench__/README.md

Added
new file mode 100644
1 +# Chrome CDP batch benchmark
3 +Scope: in-process handling of 16 labeled CDP replies of 512 KiB each with a fake transport, including JSON serialization and private spool writes.
4 +Browser launch, network latency, capture encoding, and small replies are excluded.
6 +Run `mise run //extensions/chrome-cdp:bench -- 60 compare` for interleaved old-cost/current pairs, alternating order each pair.
7 +Run `mise run //extensions/chrome-cdp:profile` for a Node V8 CPU profile under `.pi/tmp/chrome-cdp-bench/profiles`.
8 +The script creates and removes a fresh spool directory for each sample; five untimed warmups precede sampling.
9 +It checks every frame is spooled; `__tests__/events.test.ts` checks exact file bytes, metadata, and small-response label caching.
11 +The `compare` mode reproduces the former extra label-size serialization immediately before returning the fake reply; the current branch skips that extra serialization.
12 +This is an approximation of the former production path, not a second copy of the old implementation.
13 +Each reported sample divides a 16-reply batch by 16, in milliseconds per reply.
14 +The two-sided exact sign test counts per-pair wins; it does not assume normally distributed timings.
16 +Node v26.9.0, x64 Linux, Ryzen 5 5600X, 60 pairs per run:
18 +| Run | Old-cost median | Current median | Per-run SD old/current | Wins | Sign-test p |
19 +| --- | ---: | ---: | ---: | ---: | ---: |
20 +| 1 | 0.478 ms | 0.289 ms | 0.093/0.065 ms | 48/60 | 3.18e-6 |
21 +| 2 | 0.420 ms | 0.302 ms | 0.133/0.089 ms | 50/60 | 1.62e-7 |
23 +Before the change, two independent unpaired full-batch runs gave medians of 0.441 and 0.413 ms; candidate runs gave 0.473 and 0.457 ms.
24 +Those unpaired measurements are inconclusive because filesystem and machine drift exceed the difference.
25 +The interleaved comparison isolates the removed serialization and supports a CPU improvement for large labeled replies, not an end-to-end speed claim.
26 +An unlabeled-spool control had before medians of 0.353 and 0.377 ms and after medians of 0.390 and 0.338 ms; no consistent regression detected.
27 +V8 `--cpu-prof` before the change sampled `executeOperations` 320 times and `spoolFrame` 159 times during the batch workload; both serialized the same labeled response.
28 +The optimization passes the serialized frame from the cache-size check to `spoolFrame`, preserving exact spool bytes and cache threshold while avoiding the second stringify.
29 +Profile sample counts are diagnostic, not a cross-run performance statistic.
31 +Deferred spooling was not adopted.
32 +It cannot eliminate writes because returned paths must exist before the tool result returns.
33 +It would retain up to the full batch of large replies in memory before checking disk capacity, weakening the 16 MiB quota and making write failure arrive after more work.
34 +Current measurements target the only removed cost with equivalent path, bytes, and quota behavior: redundant serialization before immediate bounded spool writes.

extensions/chrome-cdp/__bench__/spool.bench.ts

Added
new file mode 100644
1 +import { mkdir, mkdtemp, rm } from "node:fs/promises";
2 +import { join, resolve } from "node:path";
3 +import { performance } from "node:perf_hooks";
4 +import { Browser, executeOperations } from "../browser.ts";
6 +const root = resolve(import.meta.dirname, "../../../.pi/tmp/chrome-cdp-bench");
7 +const samples = Number(process.argv[2] ?? 30);
8 +const workload = process.argv[3] ?? "batch";
9 +const frameCount = 16;
10 +if (workload !== "batch" && workload !== "spool" && workload !== "compare")
11 + throw new Error("workload must be batch, spool, or compare");
12 +if (!Number.isInteger(samples) || samples < 3 || samples > 200) {
13 + throw new Error("samples must be an integer between 3 and 200");
15 +await mkdir(root, { recursive: true });
16 +await mkdir(join(root, "profiles"), { recursive: true });
17 +const frame = { id: 7, result: { data: "x".repeat(512 * 1024) } };
19 +async function measure(extraSerialization = false): Promise<number> {
20 + const b = new Browser();
21 + b.spoolDir = await mkdtemp(join(root, "spool-"));
22 + try {
23 + const start = performance.now();
24 + if (workload !== "spool") {
25 + // Reproduce the former label size probe without changing production code.
26 + b.send = async () => {
27 + if (extraSerialization) Buffer.byteLength(JSON.stringify(frame));
28 + return frame;
29 + };
30 + const result = await executeOperations(
31 + b,
32 + Array.from({ length: frameCount }, (_, i) => ({
33 + kind: "cdp",
34 + method: "Browser.getVersion",
35 + label: `reply${i}`,
36 + })),
37 + );
38 + if (
39 + result.failure ||
40 + result.output.length !== frameCount ||
41 + result.output.some((item) => !("path" in (item as { raw: object }).raw))
42 + )
43 + throw new Error("batch response mismatch");
44 + } else {
45 + for (let i = 0; i < frameCount; i++) {
46 + const result = await b.spoolFrame(frame);
47 + if (!("path" in result) || result.bytes < 512 * 1024)
48 + throw new Error("oversized frame not spooled");
49 + }
50 + }
51 + return (performance.now() - start) / frameCount;
52 + } finally {
53 + await rm(b.spoolDir, { recursive: true, force: true });
54 + }
57 +const stats = (times: number[]) => {
58 + const sorted = [...times].sort((a, b) => a - b);
59 + const mean = times.reduce((a, b) => a + b, 0) / times.length;
60 + return {
61 + meanMs: mean,
62 + medianMs: sorted[Math.floor(sorted.length / 2)],
63 + sdMs: Math.sqrt(
64 + times.reduce((a, b) => a + (b - mean) ** 2, 0) / times.length,
65 + ),
66 + minMs: sorted[0],
67 + maxMs: sorted.at(-1),
68 + };
69 +};
70 +if (workload === "compare") {
71 + for (let i = 0; i < 5; i++) {
72 + await measure(true);
73 + await measure(false);
74 + }
75 + const old: number[] = [],
76 + current: number[] = [];
77 + for (let i = 0; i < samples; i++) {
78 + if (i % 2 === 0) {
79 + old.push(await measure(true));
80 + current.push(await measure(false));
81 + } else {
82 + current.push(await measure(false));
83 + old.push(await measure(true));
84 + }
85 + }
86 + const wins = old.filter((value, i) => value > current[i]).length;
87 + const tail = Math.min(wins, samples - wins);
88 + let term = 2 ** -samples,
89 + p = term;
90 + for (let k = 1; k <= tail; k++) {
91 + term *= (samples - k + 1) / k;
92 + p += term;
93 + }
94 + console.log(
95 + JSON.stringify({
96 + workload: "batch/512KiB",
97 + node: process.version,
98 + samples,
99 + framesPerSample: frameCount,
100 + old: stats(old),
101 + current: stats(current),
102 + pairedWins: wins,
103 + signTestP: Math.min(1, 2 * p),
104 + oldMs: old,
105 + currentMs: current,
106 + }),
107 + );
108 +} else {
109 + for (let i = 0; i < 5; i++) await measure();
110 + const times: number[] = [];
111 + for (let i = 0; i < samples; i++) times.push(await measure());
112 + console.log(
113 + JSON.stringify({
114 + workload: `${workload}/512KiB`,
115 + node: process.version,
116 + samples,
117 + framesPerSample: frameCount,
118 + ...stats(times),
119 + samplesMs: times,
120 + }),
121 + );

extensions/chrome-cdp/__e2e__/browser.test.ts

Added
new file mode 100644
1 +import assert from "node:assert/strict";
2 +import { execFileSync } from "node:child_process";
3 +import { once } from "node:events";
4 +import { existsSync } from "node:fs";
5 +import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
6 +import { createServer } from "node:http";
7 +import { tmpdir } from "node:os";
8 +import { join } from "node:path";
9 +import { test } from "vitest";
10 +import { Browser, executeOperations } from "../browser.ts";
11 +import { dataRoot } from "../lib.ts";
13 +const html =
14 + '<!doctype html><title>Chrome CDP fixture</title><main><h1>Ready</h1><button id="go">Go</button></main><script>console.error("fixture-error");document.querySelector("button").onclick=()=>{document.querySelector("h1").textContent="Done"};</script>';
16 +test("debug trace aggregates noisy events without logging payloads", () => {
17 + const b = new Browser();
18 + const logs: { event: string; method?: string; count?: number }[] = [];
19 + b.diagnostic = (entry) => logs.push(entry);
20 + for (let i = 0; i < 200; i++)
21 + b.onMessage(
22 + JSON.stringify({
23 + method: "Network.requestWillBeSent",
24 + params: { request: { url: "private.example" } },
25 + }),
26 + );
27 + assert.deepEqual(logs, [
28 + { event: "cdp.events", method: "Network.requestWillBeSent", count: 200 },
29 + ]);
30 +});
32 +test("real Chrome: raw, events, captures, trace, persistent profile, headed and public smoke", {
33 + timeout: 180000,
34 +}, async () => {
35 + const server = createServer((_req, res) => {
36 + res.setHeader("Content-Type", "text/html");
37 + res.end(html);
38 + });
39 + server.listen(0, "127.0.0.1");
40 + await once(server, "listening");
41 + const address = server.address();
42 + if (!address || typeof address === "string") throw new Error("no port");
43 + const url = `http://127.0.0.1:${address.port}`;
44 + const profile = join(dataRoot(), "google-chrome-stable", "pi-cdp-test");
45 + const root = await mkdtemp(join(tmpdir(), "pi-chrome-cdp-"));
46 + let b: Browser | undefined;
47 + let ownsProfile = false;
48 + if (existsSync(profile))
49 + throw new Error(
50 + `test profile already exists; refusing to delete or reuse: ${profile}`,
51 + );
52 + try {
53 + b = await Browser.launch({ artifactDir: root });
54 + const sid = b.initialSession;
55 + const first = await executeOperations(b, [
56 + {
57 + kind: "cdp",
58 + method: "Page.navigate",
59 + sessionId: sid,
60 + params: { url },
61 + label: "nav",
62 + },
63 + {
64 + kind: "cdp",
65 + method: "Runtime.evaluate",
66 + sessionId: sid,
67 + params: { expression: "document.title", returnByValue: true },
68 + label: "title",
69 + },
70 + {
71 + kind: "cdp",
72 + method: "Runtime.evaluate",
73 + sessionId: sid,
74 + params: {
75 + expression: "40+2",
76 + returnByValue: true,
77 + contextId: "{{title.result.result.executionContextId}}",
78 + },
79 + },
80 + ]);
81 + // Missing reference stops the batch before the dependent command is sent.
82 + assert.match(first.failure || "", /missing reference/);
83 + const good = await executeOperations(b, [
84 + {
85 + kind: "cdp",
86 + method: "Runtime.evaluate",
87 + sessionId: sid,
88 + params: { expression: "document.title", returnByValue: true },
89 + label: "title2",
90 + },
91 + {
92 + kind: "cdp",
93 + method: "Runtime.evaluate",
94 + sessionId: sid,
95 + params: {
96 + expression: "{{title2.result.result.value}}",
97 + returnByValue: true,
98 + },
99 + },
100 + { kind: "screenshot", sessionId: sid },
101 + ]);
102 + assert.equal(good.failure, undefined);
103 + assert.equal(good.images.length, 1);
104 + assert.ok(
105 + [...first.events, ...good.events].some(
106 + (e) => e.method === "Runtime.consoleAPICalled",
107 + ),
108 + );
109 + assert.equal(
110 + (good.output[2] as { file: string }).file.startsWith(root),
111 + true,
112 + );
113 + assert.ok(
114 + (await stat((good.output[2] as { file: string }).file)).size > 100,
115 + );
116 + const v = await executeOperations(b, [
117 + { kind: "videoStart", sessionId: sid },
118 + { kind: "cdp", method: "Page.reload", sessionId: sid },
119 + ]);
120 + assert.equal(v.failure, undefined);
121 + const animated = await b.send(
122 + "Runtime.evaluate",
124 + expression:
125 + "window.__cdpTestAnimation = setInterval(() => { if (document.body) document.body.style.backgroundColor = Date.now() % 2 ? '#fff' : '#eef'; }, 16)",
126 + },
127 + sid,
128 + );
129 + assert.equal(animated.error, undefined);
130 + const recordingStart = Date.now();
131 + await new Promise((resolve) => setTimeout(resolve, 1500));
132 + const recordingMs = Date.now() - recordingStart;
133 + const stopped = await executeOperations(b, [
134 + { kind: "videoStop" },
136 + kind: "cdp",
137 + method: "Runtime.evaluate",
138 + sessionId: sid,
139 + params: { expression: "clearInterval(window.__cdpTestAnimation)" },
140 + },
141 + { kind: "traceStart" },
142 + { kind: "cdp", method: "Page.reload", sessionId: sid },
143 + { kind: "traceStop" },
144 + ]);
145 + assert.equal(stopped.failure, undefined, JSON.stringify(stopped));
146 + const videoFile = (stopped.output[0] as { file: string }).file;
147 + const traceFile = (stopped.output[2] as { file: string }).file;
148 + assert.ok((await stat(videoFile)).size > 50);
149 + const duration = Number(
150 + execFileSync(
151 + "ffprobe",
153 + "-v",
154 + "error",
155 + "-show_entries",
156 + "format=duration",
157 + "-of",
158 + "default=noprint_wrappers=1:nokey=1",
159 + videoFile,
160 + ],
161 + { encoding: "utf8" },
162 + ).trim(),
163 + );
164 + assert.ok(
165 + Math.abs(duration - recordingMs / 1000) < 0.75,
166 + `WebM duration ${duration}s must track capture ${recordingMs}ms`,
167 + );
168 + const traceData = JSON.parse(await readFile(traceFile, "utf8"));
169 + assert.ok(traceData && typeof traceData === "object");
170 + assert.equal(b.status().uncertain, false);
171 + const cancelled = new AbortController();
172 + const stuck = executeOperations(
173 + b,
176 + kind: "cdp",
177 + method: "Runtime.evaluate",
178 + sessionId: sid,
179 + params: { expression: "new Promise(() => {})", awaitPromise: true },
180 + },
181 + ],
182 + cancelled.signal,
183 + );
184 + setTimeout(() => cancelled.abort(), 50);
185 + const canceledResult = await stuck;
186 + assert.match(canceledResult.failure || "", /canceled/);
187 + const refused = await executeOperations(b, [
188 + { kind: "cdp", method: "Browser.getVersion" },
189 + ]);
190 + assert.match(refused.failure || "", /uncertain/);
191 + const resync = await executeOperations(b, [
192 + { kind: "status" },
193 + { kind: "cdp", method: "Browser.getVersion" },
194 + ]);
195 + assert.equal(resync.failure, undefined, JSON.stringify(resync));
196 + const savedPath = process.env.PATH;
197 + try {
198 + process.env.PATH = "/nonexistent";
199 + const noEncoder = await executeOperations(b, [
200 + { kind: "videoStart", sessionId: sid },
201 + ]);
202 + assert.match(noEncoder.failure || "", /ENOENT|ffmpeg/);
203 + } finally {
204 + process.env.PATH = savedPath;
206 + const chain = await executeOperations(b, [
208 + kind: "cdp",
209 + method: "Target.createTarget",
210 + params: { url: "about:blank" },
211 + label: "newTab",
212 + },
214 + kind: "cdp",
215 + method: "Target.attachToTarget",
216 + params: { targetId: "{{newTab.result.targetId}}", flatten: true },
217 + label: "attached",
218 + },
220 + kind: "cdp",
221 + method: "Runtime.evaluate",
222 + sessionId: "{{attached.result.sessionId}}",
223 + params: { expression: "6*7", returnByValue: true },
224 + },
225 + ]);
226 + assert.equal(chain.failure, undefined, JSON.stringify(chain));
227 + assert.match(JSON.stringify(chain.output[2]), /42/);
228 + const smoke = await executeOperations(b, [
230 + kind: "cdp",
231 + method: "Page.navigate",
232 + sessionId: sid,
233 + params: { url: "https://example.com" },
234 + label: "publicNav",
235 + },
237 + kind: "wait",
238 + after: "publicNav",
239 + event: "Page.loadEventFired",
240 + sessionId: sid,
241 + timeoutMs: 10000,
242 + },
244 + kind: "cdp",
245 + method: "Runtime.evaluate",
246 + sessionId: sid,
247 + params: { expression: "document.title", returnByValue: true },
248 + },
249 + ]);
250 + if (
251 + smoke.failure ||
252 + !JSON.stringify(smoke.output).includes("Example Domain")
254 + console.warn(
255 + `public site verification unavailable: ${smoke.failure || JSON.stringify(smoke.output).slice(0, 500)}`,
256 + );
257 + else assert.match(JSON.stringify(smoke.output), /Example Domain/);
258 + await b.close();
259 + b = undefined;
261 + const saved = await Browser.launch({
262 + profile: "pi-cdp-test",
263 + artifactDir: root,
264 + });
265 + b = saved;
266 + ownsProfile = true;
267 + await assert.rejects(
268 + Browser.launch({ profile: "pi-cdp-test", artifactDir: root }),
269 + /profile locked/,
270 + );
271 + const writeCookie = await executeOperations(saved, [
273 + kind: "cdp",
274 + method: "Page.navigate",
275 + sessionId: saved.initialSession,
276 + params: { url },
277 + label: "persistNav",
278 + },
280 + kind: "wait",
281 + after: "persistNav",
282 + event: "Page.loadEventFired",
283 + sessionId: saved.initialSession,
284 + },
286 + kind: "cdp",
287 + method: "Runtime.evaluate",
288 + sessionId: saved.initialSession,
289 + params: {
290 + expression: 'document.cookie="test=kept; Max-Age=3600; Path=/"',
291 + },
292 + },
294 + kind: "cdp",
295 + method: "Runtime.evaluate",
296 + sessionId: saved.initialSession,
297 + params: {
298 + expression: 'location.href+" :: "+document.cookie',
299 + returnByValue: true,
300 + },
301 + },
302 + ]);
303 + assert.equal(writeCookie.failure, undefined, JSON.stringify(writeCookie));
304 + assert.match(
305 + JSON.stringify(writeCookie.output),
306 + /test=kept/,
307 + JSON.stringify(writeCookie),
308 + );
309 + await saved.close();
310 + b = undefined;
311 + b = await Browser.launch({
312 + profile: "pi-cdp-test",
313 + artifactDir: root,
314 + headed: true,
315 + });
316 + const persisted = await executeOperations(b, [
318 + kind: "cdp",
319 + method: "Page.navigate",
320 + sessionId: b.initialSession,
321 + params: { url },
322 + label: "restoreNav",
323 + },
325 + kind: "wait",
326 + after: "restoreNav",
327 + event: "Page.loadEventFired",
328 + sessionId: b.initialSession,
329 + },
331 + kind: "cdp",
332 + method: "Runtime.evaluate",
333 + sessionId: b.initialSession,
334 + params: { expression: "document.cookie", returnByValue: true },
335 + },
336 + ]);
337 + assert.match(JSON.stringify(persisted.output), /test=kept/);
338 + await b.close();
339 + b = undefined;
340 + await writeFile(join(profile, ".pi-chrome-cdp-version"), "999.0.0.0");
341 + await assert.rejects(
342 + Browser.launch({ profile: "pi-cdp-test", artifactDir: root }),
343 + /downgrade refused/,
344 + );
345 + } finally {
346 + if (b) await b.close();
347 + server.close();
348 + await rm(root, { recursive: true, force: true });
349 + if (ownsProfile)
350 + await rm(profile, {
351 + recursive: true,
352 + force: true,
353 + maxRetries: 10,
354 + retryDelay: 100,
355 + });
357 +});

extensions/chrome-cdp/__e2e__/cleanup.test.ts

Added
new file mode 100644
1 +import assert from "node:assert/strict";
2 +import { existsSync } from "node:fs";
3 +import { mkdtemp, rm, writeFile } from "node:fs/promises";
4 +import { test } from "vitest";
5 +import { Browser } from "../browser.ts";
6 +import { TMP_PREFIX } from "../lib.ts";
8 +test("only tagged dead-owner temporary directories are reclaimed", async () => {
9 + const stale = await mkdtemp(TMP_PREFIX);
10 + const unknown = await mkdtemp(TMP_PREFIX);
11 + try {
12 + await writeFile(
13 + `${stale}/.pi-chrome-cdp-owner.json`,
14 + JSON.stringify({
15 + tag: "pi-chrome-cdp-v1",
16 + ownerPid: 2147483647,
17 + browserPid: 0,
18 + }),
19 + );
20 + const b = await Browser.launch({});
21 + await b.close();
22 + assert.equal(existsSync(stale), false);
23 + assert.equal(existsSync(unknown), true);
24 + } finally {
25 + await rm(stale, { recursive: true, force: true });
26 + await rm(unknown, { recursive: true, force: true });
27 + }
28 +});

extensions/chrome-cdp/__e2e__/extension.test.ts

Added
new file mode 100644
1 +import assert from "node:assert/strict";
2 +import { randomUUID } from "node:crypto";
3 +import { readFile, rm } from "node:fs/promises";
4 +import { tmpdir } from "node:os";
5 +import { join } from "node:path";
6 +import { initTheme } from "@earendil-works/pi-coding-agent";
7 +import { test } from "vitest";
8 +import chromeExtension from "../index.ts";
10 +test("Pi registration, /chrome toggle, raw command, screenshot, agent close", {
11 + timeout: 60000,
12 +}, async () => {
13 + initTheme("default", false);
14 + const handlers: Record<string, Function> = {};
15 + let tool:
16 + | {
17 + execute: Function;
18 + renderCall: Function;
19 + renderResult: Function;
20 + description: string;
21 + promptSnippet: string;
22 + promptGuidelines: string[];
23 + parameters: { properties: Record<string, unknown> };
24 + constrainedSampling: unknown;
25 + }
26 + | undefined;
27 + let names: string[] = [];
28 + let chromeFlag = false;
29 + const notices: string[] = [];
30 + const pi = {
31 + getActiveTools: () => names,
32 + setActiveTools: (next: string[]) => {
33 + names = next;
34 + },
35 + registerCommand: (name: string, command: { handler: Function }) => {
36 + handlers[name] = command.handler;
37 + },
38 + registerTool: (value: NonNullable<typeof tool>) => {
39 + tool = value;
40 + },
41 + registerFlag: (name: string, options: { type: string }) => {
42 + assert.equal(name, "chrome");
43 + assert.equal(options.type, "boolean");
44 + },
45 + getFlag: (name: string) => {
46 + assert.equal(name, "chrome");
47 + return chromeFlag;
48 + },
49 + on: (name: string, fn: Function) => {
50 + handlers[name] = fn;
51 + },
52 + };
53 + chromeExtension(pi as never);
54 + const ctx = {
55 + cwd: process.cwd(),
56 + ui: { notify: (message: string) => notices.push(message) },
57 + };
58 + await handlers.session_start();
59 + assert.equal(names.includes("chrome_cdp"), false);
60 + chromeFlag = true;
61 + await handlers.session_start();
62 + assert.equal(names.includes("chrome_cdp"), true);
63 + chromeFlag = false;
64 + await handlers.session_start();
65 + assert.equal(names.includes("chrome_cdp"), false);
66 + const logFile = join(tmpdir(), `chrome-debug-${randomUUID()}.jsonl`);
67 + const oldDebug = process.env.PI_CHROME_CDP_DEBUG;
68 + process.env.PI_CHROME_CDP_DEBUG = logFile;
69 + await handlers.session_start(undefined, ctx);
70 + await handlers.chrome("", ctx);
71 + assert.equal(names.includes("chrome_cdp"), true);
72 + assert.equal(handlers.resources_discover, undefined);
73 + assert.ok(tool);
74 + assert.match(tool.description, /status\.protocol/);
75 + assert.match(tool.promptSnippet, /raw CDP/);
76 + assert.ok(tool.parameters.properties.operations);
77 + assert.deepEqual(tool.constrainedSampling, {
78 + type: "json_schema",
79 + strict: "prefer",
80 + });
81 + assert.match(tool.description, /chromedevtools\.github\.io/);
82 + assert.ok(
83 + tool.promptGuidelines.some((guideline) => guideline.includes("sessionId")),
84 + );
85 + const theme = {
86 + fg: (_color: string, value: string) => value,
87 + bold: (value: string) => value,
88 + };
89 + const call = tool.renderCall(
90 + {
91 + operations: [
92 + {
93 + kind: "cdp",
94 + method: "Browser.getVersion",
95 + params: { secret: "private" },
96 + },
97 + { kind: "status" },
98 + ],
99 + },
100 + theme,
101 + { expanded: true },
102 + );
103 + assert.match(call.render(100).join(" "), /Browser.getVersion/);
104 + assert.doesNotMatch(call.render(100).join(" "), /private/);
105 + const partial = tool.renderResult(
107 + content: [],
108 + details: {
109 + progress: { completed: 1, total: 2, active: "wait", elapsedMs: 1200 },
110 + },
111 + },
112 + { expanded: false, isPartial: true },
113 + theme,
114 + { isError: false },
115 + );
116 + assert.match(partial.render(100).join(" "), /1\/2 ops; wait \(1s\)/);
117 + let file: string | undefined;
118 + try {
119 + const updates: {
120 + content: { text: string }[];
121 + details: { progress: { completed: number; elapsedMs: number } };
122 + }[] = [];
123 + const res = await tool.execute(
124 + "test",
126 + operations: [
127 + { kind: "cdp", method: "Browser.getVersion", label: "version" },
128 + { kind: "screenshot", sessionId: "{{missing.result.sessionId}}" },
129 + ],
130 + },
131 + new AbortController().signal,
132 + (update: (typeof updates)[number]) => updates.push(update),
133 + ctx,
134 + );
135 + assert.ok(updates.length >= 2);
136 + assert.equal(updates[0].details.progress.completed, 0);
137 + assert.ok(
138 + updates.some((update) => update.details.progress.completed === 1),
139 + );
140 + assert.ok(
141 + updates.every((update) => !JSON.stringify(update).includes("Chrome/")),
142 + );
143 + const output = JSON.parse(res.content[0].text);
144 + assert.match(JSON.stringify(output.output[0]), /Chrome/);
145 + assert.ok(output.failure);
146 + const capture = await tool.execute(
147 + "test",
149 + operations: [
150 + { kind: "screenshot", sessionId: output.status.initialSession },
151 + ],
152 + },
153 + new AbortController().signal,
154 + undefined,
155 + ctx,
156 + );
157 + assert.equal(capture.content[1].type, "image");
158 + file = JSON.parse(capture.content[0].text).output[0].file;
159 + assert.ok(file?.includes("chrome-cdp-"));
160 + const compact = tool.renderResult(
161 + capture,
162 + { expanded: false, isPartial: false },
163 + theme,
164 + { isError: false },
165 + );
166 + const expanded = tool.renderResult(
167 + capture,
168 + { expanded: true, isPartial: false },
169 + theme,
170 + { isError: false },
171 + );
172 + assert.match(compact.render(100).join(" "), /✓ 1\/1 operation · 1 file/);
173 + assert.doesNotMatch(compact.render(100).join(" "), /chrome-cdp-/);
174 + assert.match(expanded.render(100).join(" "), /chrome-cdp-/);
175 + assert.match(expanded.render(100).join(" "), /Result preview/);
176 + const waited: typeof updates = [];
177 + const waitResult = await tool.execute(
178 + "test",
180 + operations: [
181 + { kind: "cdp", method: "Browser.getVersion", label: "waitProbe" },
183 + kind: "wait",
184 + after: "waitProbe",
185 + event: "Page.neverOccurs",
186 + sessionId: output.status.initialSession,
187 + timeoutMs: 1150,
188 + },
189 + ],
190 + },
191 + new AbortController().signal,
192 + (update: (typeof updates)[number]) => waited.push(update),
193 + ctx,
194 + );
195 + assert.match(
196 + JSON.parse(waitResult.content[0].text).failure,
197 + /wait timed out/,
198 + );
199 + assert.ok(
200 + waited.some((update) => update.details.progress.elapsedMs >= 900),
201 + );
202 + const closed = await tool.execute(
203 + "test",
204 + { operations: [{ kind: "close" }] },
205 + new AbortController().signal,
206 + undefined,
207 + ctx,
208 + );
209 + assert.equal(JSON.parse(closed.content[0].text).output[0].closed, true);
210 + await tool.execute(
211 + "test",
212 + { operations: [{ kind: "cdp", method: "Browser.getVersion" }] },
213 + new AbortController().signal,
214 + undefined,
215 + ctx,
216 + );
217 + await handlers.chrome("close", ctx);
218 + assert.equal(notices.at(-1), "Chrome stopped; tool off");
219 + const alreadyClosed = await tool.execute(
220 + "test",
221 + { operations: [{ kind: "close" }] },
222 + new AbortController().signal,
223 + undefined,
224 + ctx,
225 + );
226 + assert.equal(JSON.parse(alreadyClosed.content[0].text).closed, true);
227 + } finally {
228 + await handlers.session_shutdown();
229 + if (oldDebug === undefined) delete process.env.PI_CHROME_CDP_DEBUG;
230 + else process.env.PI_CHROME_CDP_DEBUG = oldDebug;
231 + if (file) await rm(file, { force: true });
233 + const logs = (await readFile(logFile, "utf8"))
234 + .trim()
235 + .split("\n")
236 + .map((line) => JSON.parse(line));
237 + assert.ok(
238 + logs.some(
239 + (line) =>
240 + line.event === "cdp.send" && line.method === "Browser.getVersion",
241 + ),
242 + );
243 + assert.ok(
244 + logs.some(
245 + (line) => line.event === "operation.end" && line.outcome === "error",
246 + ),
247 + );
248 + assert.ok(logs.some((line) => line.event === "session.end"));
249 + assert.ok(
250 + logs.every(
251 + (line) =>
252 + !("params" in line) && !("result" in line) && !("frame" in line),
253 + ),
254 + );
255 + await rm(logFile);
256 + await handlers.chrome("close", ctx);
257 + assert.equal(names.includes("chrome_cdp"), false);
258 +});

extensions/chrome-cdp/__tests__/debug.test.ts

Added
new file mode 100644
1 +import assert from "node:assert/strict";
2 +import { randomUUID } from "node:crypto";
3 +import { readFile, rm, writeFile } from "node:fs/promises";
4 +import { tmpdir } from "node:os";
5 +import { join } from "node:path";
6 +import { test } from "vitest";
7 +import { DebugLog } from "../debug.ts";
9 +test("private debug log redacts non-CDP methods and refuses readable files", async () => {
10 + const path = join(tmpdir(), `debug-${randomUUID()}.jsonl`);
11 + try {
12 + await writeFile(path, "", { mode: 0o644 });
13 + await assert.rejects(DebugLog.open(path), /group or others/);
14 + await rm(path);
15 + const log = await DebugLog.open(path);
16 + log.record({
17 + event: "cdp.send",
18 + method: "https://secret.example/key",
19 + sessionId: "secret/path",
20 + });
21 + await log.close();
22 + const [row] = (await readFile(path, "utf8"))
23 + .trim()
24 + .split("\n")
25 + .map((line) => JSON.parse(line));
26 + assert.equal(row.method, undefined);
27 + assert.equal(row.sessionId, undefined);
28 + assert.equal(row.event, "cdp.send");
29 + } finally {
30 + await rm(path, { force: true });
31 + }
32 +});

extensions/chrome-cdp/__tests__/events.test.ts

Added
new file mode 100644
1 +import assert from "node:assert/strict";
2 +import { existsSync } from "node:fs";
3 +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
4 +import { test } from "vitest";
5 +import { Browser, executeOperations } from "../browser.ts";
6 +import { type Frame, TMP_PREFIX } from "../lib.ts";
8 +test("wait before its labeled command fails before sending anything", async () => {
9 + const b = new Browser();
10 + const result = await executeOperations(b, [
11 + {
12 + kind: "wait",
13 + after: "nav",
14 + event: "Page.loadEventFired",
15 + sessionId: "session",
16 + },
17 + {
18 + kind: "cdp",
19 + method: "Page.navigate",
20 + label: "nav",
21 + sessionId: "session",
22 + params: { url: "about:blank" },
23 + },
24 + ]);
25 + assert.match(result.failure || "", /wait must follow a labeled cdp command/);
26 + assert.deepEqual(result.output, []);
27 +});
29 +test("batch failure identifies failed operation and skipped operations", async () => {
30 + const b = new Browser();
31 + const sent: string[] = [];
32 + b.send = async (method): Promise<Frame> => {
33 + sent.push(method);
34 + return method === "Browser.fail"
35 + ? { id: sent.length, error: { code: -1, message: "expected failure" } }
36 + : { id: sent.length, result: {} };
37 + };
38 + const result = await executeOperations(b, [
39 + { kind: "cdp", method: "Browser.getVersion" },
40 + { kind: "cdp", method: "Browser.fail" },
41 + { kind: "status" },
42 + ]);
43 + assert.equal(result.failure, "expected failure");
44 + assert.deepEqual(result.failedOperation, { operation: 1, kind: "cdp" });
45 + assert.deepEqual(result.skipped, [{ operation: 2, kind: "status" }]);
46 + assert.deepEqual(sent, ["Browser.getVersion", "Browser.fail"]);
47 + await b.close();
48 +});
50 +test("multiple waits sharing an after label fail before sending", async () => {
51 + const b = new Browser();
52 + let sent = 0;
53 + b.send = async (): Promise<Frame> => {
54 + sent++;
55 + return { id: sent, result: {} };
56 + };
57 + const result = await executeOperations(b, [
58 + { kind: "cdp", method: "Browser.getVersion", label: "ready" },
59 + {
60 + kind: "wait",
61 + after: "ready",
62 + event: "Page.loadEventFired",
63 + sessionId: "s",
64 + },
65 + {
66 + kind: "wait",
67 + after: "ready",
68 + event: "Page.frameStoppedLoading",
69 + sessionId: "s",
70 + },
71 + ]);
72 + assert.match(result.failure || "", /multiple waits use after label: ready/);
73 + assert.deepEqual(result.failedOperation, { operation: 2, kind: "wait" });
74 + assert.deepEqual(result.skipped, []);
75 + assert.equal(sent, 0);
76 + await b.close();
77 +});
79 +test("multiple batch waits match their events and release their observers", async () => {
80 + const b = new Browser();
81 + let id = 0;
82 + b.send = async (): Promise<Frame> => {
83 + b.onMessage(
84 + JSON.stringify({
85 + method: "Page.loadEventFired",
86 + sessionId: "s",
87 + params: { number: ++id },
88 + }),
89 + );
90 + return { id, result: {} };
91 + };
92 + const result = await executeOperations(b, [
93 + { kind: "cdp", method: "Page.navigate", sessionId: "s", label: "first" },
94 + {
95 + kind: "wait",
96 + after: "first",
97 + event: "Page.loadEventFired",
98 + sessionId: "s",
99 + },
100 + { kind: "cdp", method: "Page.navigate", sessionId: "s", label: "second" },
102 + kind: "wait",
103 + after: "second",
104 + event: "Page.loadEventFired",
105 + sessionId: "s",
106 + },
107 + ]);
108 + assert.equal(result.failure, undefined);
109 + assert.deepEqual(
110 + [result.output[1], result.output[3]].map(
111 + (item) => (item as { wait: { seq: number } }).wait.seq,
112 + ),
113 + [1, 2],
114 + );
115 + assert.equal(b.watchers.length, 0);
116 +});
118 +test("event overflow spools exact messages and reports path", async () => {
119 + const b = new Browser();
120 + b.spoolDir = await mkdtemp(TMP_PREFIX);
121 + try {
122 + for (let i = 0; i < 230; i++)
123 + b.onMessage(
124 + JSON.stringify({
125 + method: "Log.entryAdded",
126 + sessionId: "s",
127 + params: { text: `entry-${i}` },
128 + }),
129 + );
130 + const res = await executeOperations(b, []);
131 + assert.ok(res.overflow.length > 0);
132 + assert.ok(res.events.length < 230);
133 + assert.match(await readFile(res.overflow[0], "utf8"), /entry-0/);
134 + b.onMessage(
135 + JSON.stringify({
136 + method: "Log.entryAdded",
137 + sessionId: "s",
138 + params: { text: "x".repeat(18000) },
139 + }),
140 + );
141 + const big = await executeOperations(b, []);
142 + assert.equal(big.events.at(-1)?.frame, undefined);
143 + assert.match(await readFile(big.overflow[0], "utf8"), /"text":"xxx/);
144 + const path = big.overflow[0];
145 + await b.close();
146 + assert.equal(existsSync(path), false);
147 + } finally {
148 + await b.close();
149 + await rm(b.spoolDir, { recursive: true, force: true });
151 +});
153 +test("labeled small replies remain referencable; large replies spool unchanged", async () => {
154 + const b = new Browser();
155 + b.spoolDir = await mkdtemp(TMP_PREFIX);
156 + const small: Frame = { id: 1, result: { value: 42 } };
157 + const large: Frame = { id: 2, result: { data: "x".repeat(512 * 1024) } };
158 + b.send = async (method) => (method === "Browser.getVersion" ? small : large);
159 + try {
160 + const result = await executeOperations(b, [
161 + { kind: "cdp", method: "Browser.getVersion", label: "small" },
162 + { kind: "cdp", method: "Browser.getHistograms", label: "large" },
163 + ]);
164 + assert.equal(result.failure, undefined);
165 + assert.deepEqual((result.output[0] as { raw: Frame }).raw, small);
166 + assert.deepEqual(b.results.get("small"), small);
167 + assert.equal(b.results.has("large"), false);
168 + const output = (
169 + result.output[1] as {
170 + raw: { path: string; bytes: number; preview: string };
172 + ).raw;
173 + assert.equal(await readFile(output.path, "utf8"), JSON.stringify(large));
174 + assert.equal(output.bytes, Buffer.byteLength(JSON.stringify(large)));
175 + assert.equal(output.preview, JSON.stringify(large).slice(0, 512));
176 + } finally {
177 + await b.close();
179 +});
181 +test("payload spooling expires old event files absent from this response", async () => {
182 + const b = new Browser();
183 + b.spoolDir = await mkdtemp(TMP_PREFIX);
184 + const response: Frame = {
185 + id: 1,
186 + result: { data: "r".repeat(40 * 1024) },
187 + };
188 + b.send = async (): Promise<Frame> => response;
189 + try {
190 + b.onMessage(
191 + JSON.stringify({
192 + method: "Log.entryAdded",
193 + sessionId: "s",
194 + params: { text: "e".repeat(16 * 1024 * 1024 - 128 * 1024) },
195 + }),
196 + );
197 + await b.spoolWrites;
198 + const eventPath = b.events[0]?.spooled;
199 + assert.ok(eventPath);
200 + b.cursor = b.seq;
201 + const result = await executeOperations(b, [
202 + { kind: "cdp", method: "Browser.getVersion" },
203 + { kind: "cdp", method: "Browser.getVersion" },
204 + { kind: "cdp", method: "Browser.getVersion" },
205 + { kind: "cdp", method: "Browser.getVersion" },
206 + ]);
207 + assert.deepEqual(result.overflow, []);
208 + assert.equal(JSON.stringify(result).includes(eventPath), false);
209 + const { images: _images, ...text } = result;
210 + const resultSpool = await b.spoolPayload(JSON.stringify(text));
211 + assert.equal(existsSync(eventPath), false);
212 + assert.equal(existsSync(resultSpool), true);
213 + } finally {
214 + await b.close();
215 + await rm(b.spoolDir, { recursive: true, force: true });
217 +});
219 +test("replay reports event files evicted between batches as lost", async () => {
220 + const b = new Browser();
221 + b.spoolDir = await mkdtemp(TMP_PREFIX);
222 + try {
223 + b.onMessage(
224 + JSON.stringify({
225 + method: "Log.entryAdded",
226 + sessionId: "s",
227 + params: { text: "e".repeat(9 * 1024 * 1024) },
228 + }),
229 + );
230 + await b.spoolWrites;
231 + const eventPath = b.events[0]?.spooled;
232 + assert.ok(eventPath);
233 + b.cursor = b.seq;
234 + await executeOperations(b, []);
235 + await b.spoolPayload("p".repeat(9 * 1024 * 1024));
236 + assert.equal(existsSync(eventPath), false);
237 + const replay = await executeOperations(b, [], undefined, 0);
238 + assert.deepEqual(replay.overflow, []);
239 + assert.equal(replay.events[0]?.lost, true);
240 + assert.equal(replay.events[0]?.spooled, undefined);
241 + } finally {
242 + await b.close();
243 + await rm(b.spoolDir, { recursive: true, force: true });
245 +});
247 +test("replayed event spool paths survive response quota exhaustion", async () => {
248 + const b = new Browser();
249 + b.spoolDir = await mkdtemp(TMP_PREFIX);
250 + const eventData = "e".repeat(2 * 1024 * 1024);
251 + const response: Frame = {
252 + id: 1,
253 + result: { data: "r".repeat(15 * 1024 * 1024) },
254 + };
255 + b.send = async (): Promise<Frame> => response;
256 + try {
257 + b.onMessage(
258 + JSON.stringify({
259 + method: "Log.entryAdded",
260 + sessionId: "s",
261 + params: { text: eventData },
262 + }),
263 + );
264 + await b.spoolWrites;
265 + const eventPath = b.events[0]?.spooled;
266 + assert.ok(eventPath);
267 + b.cursor = b.seq;
268 + const result = await executeOperations(
269 + b,
270 + [{ kind: "cdp", method: "Browser.getVersion" }],
271 + undefined,
272 + 0,
273 + );
274 + assert.match(result.failure || "", /available spool quota/);
275 + assert.equal(result.events[0]?.spooled, eventPath);
276 + assert.equal(existsSync(eventPath), true);
277 + } finally {
278 + await b.close();
279 + await rm(b.spoolDir, { recursive: true, force: true });
281 +});
283 +test("queued event spooling remains protected when a batch starts", async () => {
284 + const b = new Browser();
285 + b.spoolDir = await mkdtemp(TMP_PREFIX);
286 + const response: Frame = {
287 + id: 1,
288 + result: { data: "r".repeat(15 * 1024 * 1024) },
289 + };
290 + b.send = async (): Promise<Frame> => response;
291 + try {
292 + b.onMessage(
293 + JSON.stringify({
294 + method: "Log.entryAdded",
295 + sessionId: "s",
296 + params: { text: "e".repeat(2 * 1024 * 1024) },
297 + }),
298 + );
299 + const result = await executeOperations(b, [
300 + { kind: "cdp", method: "Browser.getVersion" },
301 + ]);
302 + assert.match(result.failure || "", /available spool quota/);
303 + const eventPath = result.events[0]?.spooled;
304 + assert.ok(eventPath);
305 + assert.equal(existsSync(eventPath), true);
306 + } finally {
307 + await b.close();
308 + await rm(b.spoolDir, { recursive: true, force: true });
310 +});
312 +test("current batch spool paths survive quota exhaustion", async () => {
313 + const b = new Browser();
314 + b.spoolDir = await mkdtemp(TMP_PREFIX);
315 + const frame: Frame = { id: 1, result: { data: "x".repeat(9 * 1024 * 1024) } };
316 + let calls = 0;
317 + b.send = async (): Promise<Frame> => ({ ...frame, id: ++calls });
318 + try {
319 + const result = await executeOperations(b, [
320 + { kind: "cdp", method: "Browser.getVersion", label: "first" },
321 + { kind: "cdp", method: "Browser.getVersion", label: "second" },
322 + { kind: "status" },
323 + ]);
324 + assert.match(result.failure || "", /available spool quota/);
325 + assert.deepEqual(result.failedOperation, { operation: 1, kind: "cdp" });
326 + assert.deepEqual(result.skipped, [{ operation: 2, kind: "status" }]);
327 + const first = (result.output[0] as { raw: { path: string } }).raw.path;
328 + assert.equal(existsSync(first), true);
329 + assert.equal(
330 + (await readFile(first, "utf8")).length > 9 * 1024 * 1024,
331 + true,
332 + );
333 + } finally {
334 + await b.close();
335 + await rm(b.spoolDir, { recursive: true, force: true });
337 +});
339 +test("video size cap does not throw in event handler", async () => {
340 + const b = new Browser();
341 + b.spoolDir = await mkdtemp(TMP_PREFIX);
342 + try {
343 + let stopped = false;
344 + b.video = {
345 + sessionId: "s",
346 + size: 256 * 1024 * 1024,
347 + droppedFrames: 0,
348 + file: "ignored",
349 + process: { stdin: { writable: false } } as never,
350 + done: Promise.resolve(0),
351 + timer: setTimeout(() => {}, 100),
352 + };
353 + b.stopVideo = async () => {
354 + stopped = true;
355 + b.video = undefined;
356 + return "ignored";
357 + };
358 + assert.doesNotThrow(() =>
359 + b.onMessage(
360 + JSON.stringify({
361 + method: "Page.screencastFrame",
362 + sessionId: "s",
363 + params: { data: Buffer.from("abc").toString("base64"), sessionId: 1 },
364 + }),
365 + ),
366 + );
367 + await new Promise((resolve) => setImmediate(resolve));
368 + assert.equal(stopped, true);
369 + } finally {
370 + await b.close();
371 + await rm(b.spoolDir, { recursive: true, force: true });
373 +});
375 +test("concurrent video finalization and close share encoder completion", async () => {
376 + const b = new Browser();
377 + b.spoolDir = await mkdtemp(TMP_PREFIX);
378 + const file = `${b.spoolDir}/capture.webm`;
379 + await writeFile(file, "partial");
380 + let finish!: (code: number) => void;
381 + const done = new Promise<number>((resolve) => {
382 + finish = resolve;
383 + });
384 + let ends = 0;
385 + b.video = {
386 + file,
387 + sessionId: "s",
388 + size: 5,
389 + droppedFrames: 0,
390 + timer: setTimeout(() => {}, 5000),
391 + process: {
392 + stdin: {
393 + end: () => {
394 + ends++;
395 + },
396 + },
397 + } as never,
398 + done,
399 + };
400 + try {
401 + const a = b.stopVideo();
402 + const second = b.stopVideo();
403 + const closing = b.close();
404 + assert.equal(ends, 1);
405 + finish(0);
406 + assert.equal(await a, file);
407 + assert.equal(await second, file);
408 + await closing;
409 + assert.equal(ends, 1);
410 + assert.equal(b.closed, true);
411 + } finally {
412 + await b.close();
413 + await rm(b.spoolDir, { recursive: true, force: true });
415 +});
417 +test("concurrent trace stops share one Tracing.end and one stream", async () => {
418 + const b = new Browser();
419 + b.spoolDir = await mkdtemp(TMP_PREFIX);
420 + const file = `${b.spoolDir}/trace.json`;
421 + let complete!: (v: Record<string, unknown>) => void;
422 + let ends = 0,
423 + reads = 0,
424 + closes = 0;
425 + b.trace = {
426 + file,
427 + timer: setTimeout(() => {}, 5000),
428 + done: new Promise((resolve) => {
429 + complete = resolve as typeof complete;
430 + }),
431 + finish: (v) => complete(v),
432 + };
433 + b.send = async (method, params): Promise<Frame> => {
434 + if (method === "Tracing.end") ends++;
435 + if (method === "IO.close") closes++;
436 + if (method === "IO.read") {
437 + assert.deepEqual(params, { handle: "trace-stream", size: 1024 * 1024 });
438 + return {
439 + id: 1,
440 + result: reads++
441 + ? {
442 + data: Buffer.from("[]}").toString("base64"),
443 + base64Encoded: true,
444 + eof: true,
446 + : { data: '{"traceEvents":' },
447 + };
449 + return { id: 1, result: {} };
450 + };
451 + try {
452 + const a = b.stopTrace();
453 + const second = b.stopTrace();
454 + await new Promise((resolve) => setImmediate(resolve));
455 + complete({ stream: "trace-stream" });
456 + assert.equal(await a, file);
457 + assert.equal(await second, file);
458 + assert.equal(ends, 1);
459 + assert.equal(reads, 2);
460 + assert.equal(closes, 1);
461 + assert.deepEqual(JSON.parse(await readFile(file, "utf8")), {
462 + traceEvents: [],
463 + });
464 + } finally {
465 + await b.close();
466 + await rm(b.spoolDir, { recursive: true, force: true });
468 +});
470 +test("failed trace export closes the CDP stream and removes incomplete file", async () => {
471 + const b = new Browser();
472 + b.spoolDir = await mkdtemp(TMP_PREFIX);
473 + const file = `${b.spoolDir}/incomplete.json`;
474 + let closed = 0,
475 + reads = 0;
476 + b.trace = {
477 + file,
478 + timer: setTimeout(() => {}, 5000),
479 + done: Promise.resolve({ stream: "trace-stream" }),
480 + finish: () => {},
481 + };
482 + b.send = async (method): Promise<Frame> => {
483 + if (method === "IO.close") closed++;
484 + if (method === "IO.read")
485 + return reads++
486 + ? { id: 1, error: { code: -1, message: "stream lost" } }
487 + : { id: 1, result: { data: '{"traceEvents":' } };
488 + return { id: 1, result: {} };
489 + };
490 + try {
491 + await assert.rejects(b.stopTrace(), /stream lost/);
492 + assert.equal(closed, 1);
493 + assert.equal(existsSync(file), false);
494 + } finally {
495 + await b.close();
496 + await rm(b.spoolDir, { recursive: true, force: true });
498 +});

extensions/chrome-cdp/__tests__/harness.test.ts

Added
new file mode 100644
1 +import { resolve } from "node:path";
2 +import { initTheme, keyHint } from "@earendil-works/pi-coding-agent";
3 +import { afterEach, beforeAll, describe, expect, it } from "vitest";
4 +import { createTestSession, type TestSession } from "../../../test/harness";
6 +const extensionPath = resolve(import.meta.dirname, "../index.ts");
8 +describe("chrome-cdp Pi integration", () => {
9 + let t: TestSession | undefined;
11 + beforeAll(() => initTheme("default", false));
13 + afterEach(() => {
14 + t?.dispose();
15 + t = undefined;
16 + });
18 + it("registers an inactive tool and toggles it without starting Chrome", async () => {
19 + t = await createTestSession({ extensions: [extensionPath] });
20 + const runner = t.session.extensionRunner;
21 + const extension = runner.extensions[0];
22 + expect(extension?.path).toBe(extensionPath);
23 + const tool = extension?.tools.get("chrome_cdp")?.definition;
24 + expect(tool?.description).toContain("Chrome DevTools Protocol");
25 + expect(
26 + tool?.promptGuidelines?.some((line) => line.includes("sessionId")),
27 + ).toBe(true);
28 + expect(t.session.getActiveToolNames()).not.toContain("chrome_cdp");
30 + const command = runner.getCommand("chrome");
31 + expect(command).toBeDefined();
32 + const ctx = {
33 + ...runner.createCommandContext(),
34 + mode: "print" as const,
35 + hasUI: false,
36 + };
37 + await command?.handler("", ctx);
38 + expect(t.session.getActiveToolNames()).toContain("chrome_cdp");
39 + await command?.handler("", ctx);
40 + expect(t.session.getActiveToolNames()).not.toContain("chrome_cdp");
41 + await command?.handler("close", ctx);
42 + expect(t.session.getActiveToolNames()).not.toContain("chrome_cdp");
43 + });
45 + it("warns cheaply when Chrome binary is unavailable", async () => {
46 + t = await createTestSession({
47 + extensions: [extensionPath],
48 + env: { PATH: "/nonexistent" },
49 + });
50 + const runner = t.session.extensionRunner;
51 + const command = runner.getCommand("chrome");
52 + const ctx = {
53 + ...runner.createCommandContext(),
54 + mode: "print" as const,
55 + hasUI: false,
56 + };
57 + await command?.handler("", ctx);
58 + expect(t.session.getActiveToolNames()).toContain("chrome_cdp");
59 + const notifications = t.events.uiCallsFor("notify");
60 + expect(String(notifications.at(-2)?.args[0])).toContain(
61 + "Chrome unavailable: Chrome not found",
62 + );
63 + expect(notifications.at(-2)?.args[1]).toBe("warning");
64 + });
66 + it("renders commands without exposing CDP parameters", async () => {
67 + t = await createTestSession({ extensions: [extensionPath] });
68 + const tool =
69 + t.session.extensionRunner.extensions[0]?.tools.get(
70 + "chrome_cdp",
71 + )?.definition;
72 + const theme = {
73 + fg: (_color: string, value: string) => value,
74 + bold: (value: string) => value,
75 + };
76 + const call = tool?.renderCall?.(
77 + {
78 + operations: [
79 + {
80 + kind: "cdp",
81 + method: "Browser.getVersion",
82 + params: { marker: "private-value" },
83 + },
84 + ],
85 + },
86 + theme as never,
87 + { expanded: true } as never,
88 + );
89 + const text = call?.render(100).join("\n");
90 + expect(text).toContain("Browser.getVersion");
91 + expect(text).not.toContain("private-value");
92 + });
94 + it("labels batches, advertises expansion, and previews results only when expanded", async () => {
95 + t = await createTestSession({ extensions: [extensionPath] });
96 + const tool =
97 + t.session.extensionRunner.extensions[0]?.tools.get(
98 + "chrome_cdp",
99 + )?.definition;
100 + expect(tool).toBeDefined();
101 + const theme = {
102 + fg: (_color: string, value: string) => value,
103 + bold: (value: string) => value,
104 + };
105 + const args = {
106 + operations: [
108 + kind: "cdp",
109 + method: "Page.navigate",
110 + params: { url: "https://private.example" },
111 + },
112 + { kind: "wait", event: "Page.loadEventFired" },
113 + ],
114 + };
115 + const call = (expanded: boolean) =>
116 + tool
117 + ?.renderCall?.(args as never, theme as never, { expanded } as never)
118 + .render(100)
119 + .join("\n");
120 + expect(call(false)).toContain(" Chrome");
121 + expect(call(false)).toContain("Page.navigate");
122 + expect(call(false)).toContain("wait Page.loadEventFired");
123 + expect(call(false)).toContain(keyHint("app.tools.expand", "to expand"));
124 + expect(call(false)).not.toContain("private.example");
125 + expect(call(true)).not.toContain("to expand");
127 + const result = {
128 + content: [
130 + type: "text" as const,
131 + text: JSON.stringify({
132 + output: [
134 + command: "Browser.getVersion",
135 + raw: { id: 2, result: { product: "Chrome/154" } },
136 + },
137 + ],
138 + events: [],
139 + }),
140 + },
141 + ],
142 + details: {
143 + completed: 1,
144 + total: 1,
145 + eventCount: 0,
146 + operations: ["Browser.getVersion"],
147 + },
148 + };
149 + const rendered = (expanded: boolean) =>
150 + tool
151 + ?.renderResult?.(
152 + result,
153 + { expanded, isPartial: false } as never,
154 + theme as never,
155 + { isError: false } as never,
157 + .render(100)
158 + .join("\n");
159 + expect(rendered(false)).not.toContain("Chrome/154");
160 + expect(rendered(true)).toContain("Chrome/154");
161 + expect(rendered(true)).toContain("Browser.getVersion");
163 + const status = {
164 + ...result,
165 + details: {
166 + ...result.details,
167 + operations: ["status"],
168 + browser: "Chrome/154",
169 + pages: 2,
170 + },
171 + };
172 + const statusText = tool
173 + ?.renderResult?.(
174 + status,
175 + { expanded: false, isPartial: false } as never,
176 + theme as never,
177 + { isError: false } as never,
179 + .render(100)
180 + .join("\n");
181 + expect(statusText).toContain("Chrome/154 · 2 pages");
182 + });
183 +});

extensions/chrome-cdp/__tests__/lib.test.ts

Added
new file mode 100644
1 +import assert from "node:assert/strict";
2 +import { test } from "vitest";
3 +import {
4 + artifactPath,
5 + binaryKey,
6 + dataRoot,
7 + downloads,
8 + type Frame,
9 + profileName,
10 + ref,
11 + validateFlags,
12 +} from "../lib.ts";
14 +test("names and managed file destinations reject traversal and aliases", () => {
15 + for (const bad of ["A", "../bad", "con", "foo/bar", "x\\y", "", "."])
16 + assert.throws(() => profileName(bad));
17 + assert.equal(profileName("pi-cdp-test"), "pi-cdp-test");
18 + assert.throws(() => artifactPath("/tmp/a", "../secret"));
19 + assert.throws(() => artifactPath("/tmp/a", "nested/file.png"));
20 + assert.equal(artifactPath("/tmp/a", "shot.png"), "/tmp/a/shot.png");
21 + for (const flag of [
22 + "--user-data-dir=/tmp/other",
23 + "--remote-debugging-port=9222",
24 + "--remote-debugging-address=0.0.0.0",
25 + "--remote-debugging-pipe",
26 + ])
27 + assert.throws(() => validateFlags([flag]));
28 +});
30 +test("typed result references and literal escape", () => {
31 + const results = new Map<string, Frame>([
32 + [
33 + "tab",
34 + { id: 1, result: { targetId: "T", size: 42, nested: { a: true } } },
35 + ],
36 + ]);
37 + assert.deepEqual(
38 + ref(
39 + {
40 + id: "{{tab.result.targetId}}",
41 + size: "{{tab.result.size}}",
42 + object: "{{tab.result.nested}}",
43 + literal: "\\{{tab.result.size}}",
44 + },
45 + results,
46 + ),
47 + { id: "T", size: 42, object: { a: true }, literal: "{{tab.result.size}}" },
48 + );
49 + assert.throws(() => ref("{{tab.result.missing}}", results));
50 +});
52 +test("platform data roots and binary namespaces", () => {
53 + assert.equal(
54 + dataRoot("linux", { XDG_DATA_HOME: "/home/a/data" }, "/home/a"),
55 + "/home/a/data/chrome-cdp/profiles",
56 + );
57 + assert.equal(
58 + dataRoot("darwin", {}, "/Users/a"),
59 + "/Users/a/Library/Application Support/chrome-cdp/profiles",
60 + );
61 + assert.equal(
62 + dataRoot(
63 + "win32",
64 + { LOCALAPPDATA: "C:\\Users\\a\\AppData\\Local" },
65 + "C:\\Users\\a",
66 + ).endsWith("chrome-cdp\\profiles"),
67 + true,
68 + );
69 + assert.equal(downloads("darwin", {}, "/Users/a"), "/Users/a/Downloads");
70 + assert.equal(binaryKey("chrome-for-testing"), "chrome-for-testing");
71 + assert.equal(binaryKey("chromium"), "chromium");
72 +});

extensions/chrome-cdp/browser.ts

Added
new file mode 100644
1 +import { type ChildProcess, execFileSync, spawn } from "node:child_process";
2 +import { randomUUID } from "node:crypto";
3 +import { existsSync } from "node:fs";
4 +import {
5 + appendFile,
6 + lstat,
7 + mkdir,
8 + mkdtemp,
9 + open,
10 + readdir,
11 + readFile,
12 + rm,
13 + writeFile,
14 +} from "node:fs/promises";
15 +import { tmpdir } from "node:os";
16 +import { join } from "node:path";
17 +import type { Diagnostic } from "./debug.ts";
18 +import {
19 + artifactPath,
20 + binaryKey,
21 + dataRoot,
22 + downloads,
23 + type Frame,
24 + findExecutable,
25 + type Json,
26 + profileName,
27 + ref,
28 + TMP_PREFIX,
29 + validateFlags,
30 +} from "./lib.ts";
32 +const COMMAND_MS = 30_000,
33 + INLINE = 64 * 1024,
34 + SPOOL_LIMIT = 16 * 1024 * 1024;
35 +const EVENTS = 200,
36 + VIDEO_MAX = 5 * 60_000,
37 + VIDEO_BYTES = 256 * 1024 * 1024;
38 +const traceCategories =
39 + "devtools.timeline,blink.user_timing,loading,disabled-by-default-devtools.timeline";
41 +export type Operation = {
42 + kind:
43 + | "cdp"
44 + | "wait"
45 + | "status"
46 + | "close"
47 + | "screenshot"
48 + | "videoStart"
49 + | "videoStop"
50 + | "traceStart"
51 + | "traceStop";
52 + method?: string;
53 + params?: Json;
54 + sessionId?: string;
55 + label?: string;
56 + after?: string;
57 + targetId?: string;
58 + event?: string;
59 + timeoutMs?: number;
60 + filename?: string;
61 + fullPage?: boolean;
62 +};
63 +export type Options = {
64 + headed?: boolean;
65 + executablePath?: string;
66 + profile?: string;
67 + flags?: string[];
68 + artifactDir?: string;
69 + diagnostic?: (entry: Diagnostic) => void;
70 +};
71 +type Event = {
72 + seq: number;
73 + time: string;
74 + sessionId?: string;
75 + method: string;
76 + frame?: Record<string, Json>;
77 + spooled?: string;
78 + bytes?: number;
79 + lost?: boolean;
80 +};
81 +type Watcher = {
82 + method: string;
83 + sessionId: string;
84 + since: number;
85 + hit?: Event;
86 +};
87 +type Video = {
88 + process: ChildProcess;
89 + sessionId: string;
90 + file: string;
91 + size: number;
92 + droppedFrames: number;
93 + timer: NodeJS.Timeout;
94 + sampleTimer?: NodeJS.Timeout;
95 + lastFrame?: Buffer;
96 + samples?: number;
97 + done: Promise<number | null>;
98 +};
99 +type Trace = {
100 + file: string;
101 + done: Promise<Record<string, Json>>;
102 + finish: (v: Record<string, Json>) => void;
103 + timer: NodeJS.Timeout;
106 +function alive(pid: number): boolean {
107 + if (!Number.isSafeInteger(pid) || pid <= 0) return false;
108 + try {
109 + process.kill(pid, 0);
110 + return true;
111 + } catch (e) {
112 + return (e as NodeJS.ErrnoException).code === "EPERM";
116 +async function markOwned(dir: string, browserPid = 0): Promise<void> {
117 + await writeFile(
118 + join(dir, ".pi-chrome-cdp-owner.json"),
119 + JSON.stringify({
120 + tag: "pi-chrome-cdp-v1",
121 + ownerPid: process.pid,
122 + browserPid,
123 + }),
124 + { mode: 0o600 },
125 + );
128 +async function cleanupStale(): Promise<void> {
129 + for (const name of await readdir(tmpdir())) {
130 + if (!/^pi-chrome-cdp-[A-Za-z0-9_-]+$/.test(name)) continue;
131 + const path = join(tmpdir(), name);
132 + try {
133 + if (!(await lstat(path)).isDirectory()) continue;
134 + const marker = JSON.parse(
135 + await readFile(join(path, ".pi-chrome-cdp-owner.json"), "utf8"),
136 + ) as { tag?: string; ownerPid?: number; browserPid?: number };
137 + if (
138 + marker.tag !== "pi-chrome-cdp-v1" ||
139 + alive(marker.ownerPid || 0) ||
140 + alive(marker.browserPid || 0)
142 + continue;
143 + await rm(path, {
144 + recursive: true,
145 + force: true,
146 + maxRetries: 5,
147 + retryDelay: 100,
148 + });
149 + } catch {
150 + /* unknown ownership or active filesystem use: leave untouched */
155 +async function saveNew(file: string, bytes: Buffer | string): Promise<void> {
156 + const f = await open(file, "wx", 0o600);
157 + try {
158 + await f.writeFile(bytes);
159 + } finally {
160 + await f.close();
164 +async function waitExit(child: ChildProcess, ms = 3000): Promise<boolean> {
165 + if (child.exitCode !== null || child.signalCode !== null) return true;
166 + return new Promise((resolve) => {
167 + const t = setTimeout(() => {
168 + child.off("exit", onExit);
169 + resolve(false);
170 + }, ms);
171 + const onExit = () => {
172 + clearTimeout(t);
173 + resolve(true);
174 + };
175 + child.once("exit", onExit);
176 + });
179 +export class Browser {
180 + child!: ChildProcess;
181 + socket!: WebSocket;
182 + port = 0;
183 + endpoint = "";
184 + profileDir = "";
185 + spoolDir = "";
186 + artifactDir = "";
187 + persistent = false;
188 + ownedLock = false;
189 + lockToken = randomUUID();
190 + headed = false;
191 + binary = "";
192 + version = "";
193 + viewport = "unknown";
194 + observedTargets: Json[] = [];
195 + generation = randomUUID();
196 + initialTarget = "";
197 + initialSession = "";
198 + nextId = 1;
199 + seq = 0;
200 + cursor = 0;
201 + uncertain = false;
202 + monitor = new Map<string, boolean>();
203 + autoAttach = true;
204 + sessions = new Map<string, string>();
205 + results = new Map<string, Frame>();
206 + pending = new Map<number, (f: Frame) => void>();
207 + events: Event[] = [];
208 + watchers: Watcher[] = [];
209 + lateResponses: Frame[] = [];
210 + gaps = 0;
211 + notices: string[] = [];
212 + spoolFiles: {
213 + file: string;
214 + bytes: number;
215 + firstEventSeq?: number;
216 + lastEventSeq?: number;
217 + }[] = [];
218 + spoolBytes = 0;
219 + eventChunk = 0;
220 + spoolWrites: Promise<void> = Promise.resolve();
221 + queuedSpoolBytes = 0;
222 + private protectedSpoolFiles = new Set<string>();
223 + private batchSpooling = false;
224 + video?: Video;
225 + videoStopping?: Promise<string>;
226 + trace?: Trace;
227 + traceStopping?: Promise<string>;
228 + busy: Promise<void> = Promise.resolve();
229 + closed = false;
230 + diagnostic?: (entry: Diagnostic) => void;
231 + private eventCounts = new Map<string, number>();
232 + private eventCount = 0;
234 + private flushEventCounts(): void {
235 + for (const [method, count] of this.eventCounts)
236 + this.diagnostic?.({ event: "cdp.events", method, count });
237 + this.eventCounts.clear();
238 + this.eventCount = 0;
241 + static async launch(opts: Options): Promise<Browser> {
242 + await cleanupStale();
243 + const b = new Browser();
244 + b.diagnostic = opts.diagnostic;
245 + b.diagnostic?.({ event: "browser.launch.start" });
246 + b.binary = findExecutable(opts.executablePath);
247 + b.headed = opts.headed ?? false;
248 + validateFlags(opts.flags || []);
249 + b.artifactDir = opts.artifactDir || downloads();
250 + b.persistent = !!opts.profile;
251 + try {
252 + if (opts.profile) {
253 + const name = profileName(opts.profile);
254 + b.profileDir = join(dataRoot(), binaryKey(b.binary), name);
255 + await mkdir(b.profileDir, { recursive: true, mode: 0o700 });
256 + const marker = join(b.profileDir, ".pi-chrome-cdp-version");
257 + const lock = join(b.profileDir, ".pi-chrome-cdp-lock");
258 + if (existsSync(lock))
259 + throw new Error(`profile locked: ${name}; close other owner first`);
260 + const version = await Browser.binaryMajor(b.binary);
261 + const entries = await readdir(b.profileDir);
262 + if (!existsSync(marker) && entries.length)
263 + throw new Error(
264 + "profile version marker absent; refusing existing profile",
265 + );
266 + await saveNew(
267 + lock,
268 + JSON.stringify({ pid: process.pid, token: b.lockToken }),
269 + );
270 + b.ownedLock = true;
271 + if (existsSync(marker)) {
272 + const previous = (await readFile(marker, "utf8")).trim();
273 + if (!/^\d+\.\d+\.\d+\.\d+$/.test(previous))
274 + throw new Error("corrupt profile version marker");
275 + const a = previous.split(".").map(Number),
276 + bver = version.split(".").map(Number);
277 + if (
278 + a.some(
279 + (n, i) =>
280 + n > bver[i] && a.slice(0, i).every((v, j) => v === bver[j]),
283 + throw new Error(
284 + `profile downgrade refused: ${previous} → ${version}`,
285 + );
287 + const staged = `${marker}.${randomUUID()}`;
288 + await writeFile(staged, version, { flag: "wx", mode: 0o600 });
289 + await import("node:fs/promises").then((fs) =>
290 + fs.rename(staged, marker),
291 + );
292 + } else {
293 + b.profileDir = await mkdtemp(TMP_PREFIX);
294 + await markOwned(b.profileDir);
296 + b.spoolDir = await mkdtemp(TMP_PREFIX);
297 + await markOwned(b.spoolDir);
298 + const args = [
299 + "--remote-debugging-port=0",
300 + "--remote-debugging-address=127.0.0.1",
301 + `--user-data-dir=${b.profileDir}`,
302 + "--no-first-run",
303 + "--window-size=1280,720",
304 + ...(b.headed ? [] : ["--headless=new"]),
305 + ...(opts.flags || []),
306 + "about:blank",
307 + ];
308 + const active = join(b.profileDir, "DevToolsActivePort");
309 + await rm(active, { force: true });
310 + b.child = spawn(b.binary, args, { stdio: "ignore" });
311 + let spawnFailure: Error | undefined;
312 + b.child.on("error", (e) => {
313 + spawnFailure = e;
314 + });
315 + if (!b.persistent) await markOwned(b.profileDir, b.child.pid);
316 + await markOwned(b.spoolDir, b.child.pid);
317 + let found = false;
318 + for (let i = 0; i < 200; i++) {
319 + if (existsSync(active)) {
320 + const [port] = (await readFile(active, "utf8")).split("\n");
321 + b.port = Number(port);
322 + if (Number.isInteger(b.port) && b.port > 0) {
323 + found = true;
324 + break;
327 + if (spawnFailure) throw spawnFailure;
328 + if (b.child.exitCode !== null || b.child.signalCode !== null)
329 + throw new Error(
330 + `Chrome exited during launch (${b.child.exitCode ?? b.child.signalCode})`,
331 + );
332 + await new Promise((r) => setTimeout(r, 100));
334 + if (!found)
335 + throw new Error("Chrome did not publish DevToolsActivePort within 20s");
336 + const address = `http://127.0.0.1:${b.port}`;
337 + let meta: { webSocketDebuggerUrl: string; Browser: string } | undefined;
338 + for (let attempt = 0; attempt < 50; attempt++) {
339 + try {
340 + meta = (await (
341 + await fetch(`${address}/json/version`, {
342 + signal: AbortSignal.timeout(1000),
343 + })
344 + ).json()) as typeof meta;
345 + break;
346 + } catch {
347 + if (spawnFailure) throw spawnFailure;
348 + if (b.child.exitCode !== null || b.child.signalCode !== null)
349 + throw new Error("Chrome exited before HTTP endpoint became ready");
350 + await new Promise((r) => setTimeout(r, 100));
353 + if (!meta) throw new Error("Chrome HTTP discovery endpoint unavailable");
354 + if (
355 + !meta.webSocketDebuggerUrl?.startsWith(
356 + `ws://127.0.0.1:${b.port}/devtools/browser/`,
357 + ) &&
358 + !meta.webSocketDebuggerUrl?.startsWith(
359 + `ws://localhost:${b.port}/devtools/browser/`,
362 + throw new Error("unexpected Chrome debug endpoint");
363 + b.endpoint = address;
364 + b.version = meta.Browser;
365 + b.socket = new WebSocket(meta.webSocketDebuggerUrl);
366 + await new Promise<void>((resolve, reject) => {
367 + const timer = setTimeout(
368 + () => reject(new Error("Chrome WebSocket timeout")),
369 + 5000,
370 + );
371 + b.socket.onopen = () => {
372 + clearTimeout(timer);
373 + resolve();
374 + };
375 + b.socket.onerror = () => {
376 + clearTimeout(timer);
377 + reject(new Error("Chrome WebSocket failed"));
378 + };
379 + });
380 + b.socket.onmessage = (e) => b.onMessage(String(e.data));
381 + b.socket.onclose = () => {
382 + for (const [id, pending] of b.pending)
383 + pending({
384 + id,
385 + error: { code: -1, message: "Chrome connection closed" },
386 + transportError: true,
387 + });
388 + b.pending.clear();
389 + b.uncertain = true;
390 + };
391 + const dir = await mkdtemp(TMP_PREFIX);
392 + // Browser downloads belong to a private disposable workspace.
393 + await markOwned(dir, b.child.pid);
394 + b.spoolFiles.push({ file: dir, bytes: 0 });
395 + const download = await b.send("Browser.setDownloadBehavior", {
396 + behavior: "allow",
397 + downloadPath: dir,
398 + eventsEnabled: true,
399 + });
400 + if (download.error)
401 + throw new Error(`cannot contain downloads: ${download.error.message}`);
402 + const auto = await b.send("Target.setAutoAttach", {
403 + autoAttach: true,
404 + waitForDebuggerOnStart: false,
405 + flatten: true,
406 + });
407 + if (auto.error)
408 + throw new Error(`cannot attach targets: ${auto.error.message}`);
409 + const target = await b.send("Target.createTarget", {
410 + url: "about:blank",
411 + });
412 + if (target.error) throw new Error(target.error.message);
413 + b.initialTarget = String(
414 + (target.result as Record<string, Json>).targetId,
415 + );
416 + const attach = await b.send("Target.attachToTarget", {
417 + targetId: b.initialTarget,
418 + flatten: true,
419 + });
420 + if (attach.error) throw new Error(attach.error.message);
421 + b.initialSession = String(
422 + (attach.result as Record<string, Json>).sessionId,
423 + );
424 + b.sessions.set(b.initialSession, b.initialTarget);
425 + for (const method of ["Runtime.enable", "Log.enable", "Page.enable"]) {
426 + const result = await b.send(method, {}, b.initialSession);
427 + b.monitor.set(
428 + `${b.initialSession}:${method.split(".")[0]}`,
429 + !result.error,
430 + );
432 + await b.refreshStatus();
433 + b.diagnostic?.({ event: "browser.launch.end", outcome: "ok" });
434 + return b;
435 + } catch (e) {
436 + b.diagnostic?.({ event: "browser.launch.end", outcome: "error" });
437 + await b.close();
438 + throw e;
442 + static async binaryMajor(file: string): Promise<string> {
443 + const text = execFileSync(file, ["--version"], {
444 + encoding: "utf8",
445 + timeout: 3000,
446 + });
447 + const version = text.match(/\b(\d+\.\d+\.\d+\.\d+)\b/)?.[1];
448 + if (!version)
449 + throw new Error(`cannot parse Chrome version: ${text.trim()}`);
450 + return version;
453 + onMessage(text: string): void {
454 + let frame: Record<string, Json>;
455 + try {
456 + frame = JSON.parse(text);
457 + } catch {
458 + return;
460 + if (typeof frame.id === "number") {
461 + const callback = this.pending.get(frame.id);
462 + if (callback) {
463 + this.pending.delete(frame.id);
464 + callback(frame as Frame);
465 + } else {
466 + const size = Buffer.byteLength(text);
467 + this.lateResponses.push(
468 + size > 16384
469 + ? {
470 + id: frame.id,
471 + error: {
472 + code: -5,
473 + message: `late response of ${size} bytes omitted from memory`,
474 + },
475 + transportError: true,
477 + : (frame as Frame),
478 + );
479 + if (size > 16384) this.gaps++;
480 + while (this.lateResponses.length > 4) this.lateResponses.shift();
482 + return;
484 + const method = frame.method;
485 + const params = frame.params as Record<string, Json> | undefined;
486 + if (method !== "Page.screencastFrame" && this.diagnostic) {
487 + const name = String(method);
488 + if (
489 + /^(Runtime\.exceptionThrown|Log\.entryAdded|Target\.(attachedToTarget|detachedFromTarget)|Page\.(frameNavigated|loadEventFired)|Network\.loadingFailed|Tracing\.tracingComplete)$/.test(
490 + name,
492 + ) {
493 + this.diagnostic({
494 + event: "cdp.event",
495 + method: name,
496 + sessionId:
497 + typeof frame.sessionId === "string" ? frame.sessionId : undefined,
498 + });
499 + } else {
500 + this.eventCounts.set(name, (this.eventCounts.get(name) || 0) + 1);
501 + if (++this.eventCount >= 200) this.flushEventCounts();
504 + if (
505 + method === "Page.screencastFrame" &&
506 + this.video &&
507 + frame.sessionId === this.video.sessionId &&
508 + params
509 + ) {
510 + const data = String(params.data || "");
511 + const bytes = Buffer.from(data, "base64");
512 + this.video.size += bytes.length;
513 + const video = this.video;
514 + if (video.size > VIDEO_BYTES && !this.videoStopping)
515 + void this.stopVideo().catch((e) => {
516 + this.notices.push(`video finalize failed: ${String(e)}`);
517 + });
518 + else if (!this.videoStopping) video.lastFrame = bytes;
519 + if (this.video === video)
520 + void this.send(
521 + "Page.screencastFrameAck",
522 + { sessionId: params.sessionId },
523 + video.sessionId,
524 + ).catch(() => {});
525 + return;
527 + if (method === "Tracing.tracingComplete" && this.trace && params)
528 + this.trace.finish(params);
529 + if (method === "Target.attachedToTarget" && params) {
530 + const sid = String(params.sessionId || "");
531 + const info = params.targetInfo as Record<string, Json> | undefined;
532 + if (sid && info?.targetId) {
533 + this.sessions.set(sid, String(info.targetId));
534 + if (
535 + info.type === "page" ||
536 + info.type === "worker" ||
537 + info.type === "service_worker" ||
538 + info.type === "iframe"
539 + ) {
540 + void this.send(
541 + "Target.setAutoAttach",
542 + { autoAttach: true, waitForDebuggerOnStart: false, flatten: true },
543 + sid,
544 + ).catch(() => {});
545 + for (const m of [
546 + ...(info.type === "page" ? ["Page.enable"] : []),
547 + "Runtime.enable",
548 + "Log.enable",
549 + ])
550 + void this.send(m, {}, sid)
551 + .then((r) =>
552 + this.monitor.set(`${sid}:${m.split(".")[0]}`, !r.error),
554 + .catch(() => {});
558 + if (method === "Target.detachedFromTarget" && params)
559 + this.sessions.delete(String(params.sessionId || ""));
560 + if (this.events.length >= EVENTS) {
561 + const removed = this.events.shift();
562 + if (removed) this.queueEventSpool(removed);
564 + const raw = JSON.stringify(frame);
565 + const size = Buffer.byteLength(raw);
566 + const event: Event = {
567 + seq: ++this.seq,
568 + time: new Date().toISOString(),
569 + sessionId: frame.sessionId as string | undefined,
570 + method: String(method),
571 + ...(size > 16384 ? { bytes: size } : { frame }),
572 + };
573 + if (size > 16384) this.queueEventSpool(event, frame);
574 + for (const watcher of this.watchers)
575 + if (
576 + !watcher.hit &&
577 + event.seq > watcher.since &&
578 + event.method === watcher.method &&
579 + event.sessionId === watcher.sessionId
581 + watcher.hit = event;
582 + this.events.push(event);
585 + private queueSpool<T>(write: () => Promise<T>): Promise<T> {
586 + const task = this.spoolWrites.then(write);
587 + this.spoolWrites = task.then(
588 + () => {},
589 + () => {},
590 + );
591 + return task;
594 + queueEventSpool(e: Event, frame?: Record<string, Json>): void {
595 + const item = frame ? { ...e, frame } : e;
596 + const bytes = Buffer.byteLength(JSON.stringify(item));
597 + if (this.queuedSpoolBytes + bytes > SPOOL_LIMIT) {
598 + e.lost = true;
599 + this.gaps++;
600 + return;
602 + this.queuedSpoolBytes += bytes;
603 + void this.queueSpool(async () => {
604 + e.spooled = await this.writeSpoolEvent(item);
605 + })
606 + .catch(() => {
607 + e.lost = true;
608 + this.gaps++;
609 + })
610 + .finally(() => {
611 + this.queuedSpoolBytes -= bytes;
612 + });
615 + beginBatchSpool(startSeq: number): void {
616 + this.protectedSpoolFiles.clear();
617 + this.batchSpooling = true;
618 + for (const event of this.events)
619 + if (event.seq > startSeq && event.spooled && !event.lost)
620 + this.protectSpoolFile(event.spooled);
623 + private async makeSpoolRoom(bytes: number): Promise<boolean> {
624 + while (this.spoolBytes + bytes > SPOOL_LIMIT) {
625 + const oldest = this.spoolFiles.find(
626 + (f) => f.bytes > 0 && !this.protectedSpoolFiles.has(f.file),
627 + );
628 + if (!oldest) return false;
629 + this.spoolFiles.splice(this.spoolFiles.indexOf(oldest), 1);
630 + await rm(oldest.file, { force: true });
631 + if (oldest.firstEventSeq !== undefined) {
632 + this.eventChunk++;
633 + for (const event of this.events)
634 + if (event.spooled === oldest.file) {
635 + delete event.spooled;
636 + event.lost = true;
639 + this.spoolBytes -= oldest.bytes;
640 + this.gaps++;
642 + return true;
645 + protectSpoolFile(file: string): void {
646 + if (this.batchSpooling) this.protectedSpoolFiles.add(file);
649 + private async writeSpoolEvent(e: Event): Promise<string> {
650 + const bytes = JSON.stringify(e) + "\n";
651 + const size = Buffer.byteLength(bytes);
652 + if (!(await this.makeSpoolRoom(size))) {
653 + e.lost = true;
654 + this.gaps++;
655 + return "";
657 + const path = join(
658 + this.spoolDir,
659 + `events-${this.generation}-${this.eventChunk}.jsonl`,
660 + );
661 + await appendFile(path, bytes, { mode: 0o600 });
662 + let entry = this.spoolFiles.find((f) => f.file === path);
663 + if (!entry) {
664 + entry = {
665 + file: path,
666 + bytes: 0,
667 + firstEventSeq: e.seq,
668 + lastEventSeq: e.seq,
669 + };
670 + this.spoolFiles.push(entry);
672 + entry.bytes += size;
673 + entry.firstEventSeq ??= e.seq;
674 + entry.lastEventSeq = e.seq;
675 + this.spoolBytes += size;
676 + this.protectSpoolFile(path);
677 + return path;
680 + spoolEvent(e: Event): Promise<string> {
681 + return this.queueSpool(() => this.writeSpoolEvent(e));
684 + send(
685 + method: string,
686 + params: Json = {},
687 + sessionId?: string,
688 + signal?: AbortSignal,
689 + timeoutMs = COMMAND_MS,
690 + ): Promise<Frame> {
691 + if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
692 + return Promise.reject(new Error("Chrome socket not open"));
693 + const id = this.nextId++;
694 + const started = Date.now();
695 + if (method !== "Page.screencastFrameAck")
696 + this.diagnostic?.({ event: "cdp.send", method, wireId: id, sessionId });
697 + return new Promise((resolve) => {
698 + let done = false;
699 + const finish = (frame: Frame) => {
700 + if (done) return;
701 + done = true;
702 + clearTimeout(timer);
703 + signal?.removeEventListener("abort", abort);
704 + this.pending.delete(id);
705 + if (method !== "Page.screencastFrameAck")
706 + this.diagnostic?.({
707 + event: "cdp.reply",
708 + method,
709 + wireId: id,
710 + elapsedMs: Date.now() - started,
711 + code: frame.error?.code,
712 + outcome: frame.transportError
713 + ? "transport"
714 + : frame.error
715 + ? "cdp-error"
716 + : "ok",
717 + });
718 + resolve(frame);
719 + };
720 + const abort = () => {
721 + this.uncertain = true;
722 + finish({
723 + id,
724 + error: { code: -2, message: "canceled; effects may have applied" },
725 + transportError: true,
726 + });
727 + };
728 + const timer = setTimeout(() => {
729 + this.uncertain = true;
730 + finish({
731 + id,
732 + error: {
733 + code: -3,
734 + message: `timeout after ${timeoutMs}ms; effects may have applied`,
735 + },
736 + transportError: true,
737 + });
738 + }, timeoutMs);
739 + if (signal?.aborted) {
740 + abort();
741 + return;
743 + signal?.addEventListener("abort", abort, { once: true });
744 + this.pending.set(id, finish);
745 + try {
746 + this.socket.send(
747 + JSON.stringify({
748 + id,
749 + method,
750 + params,
751 + ...(sessionId ? { sessionId } : {}),
752 + }),
753 + );
754 + } catch (e) {
755 + finish({
756 + id,
757 + error: { code: -4, message: String(e) },
758 + transportError: true,
759 + });
761 + });
764 + async refreshStatus(): Promise<void> {
765 + const targets = await this.send("Target.getTargets");
766 + if (targets.error)
767 + throw new Error(`status unavailable: ${targets.error.message}`);
768 + this.observedTargets =
769 + ((targets.result as Record<string, Json>).targetInfos as Json[]) || [];
770 + const metrics = await this.send(
771 + "Page.getLayoutMetrics",
772 + {},
773 + this.initialSession,
774 + );
775 + if (!metrics.error) {
776 + const viewport = (metrics.result as Record<string, Json>)
777 + .cssVisualViewport as Record<string, Json> | undefined;
778 + if (viewport)
779 + this.viewport = `${viewport.clientWidth}x${viewport.clientHeight}`;
781 + this.uncertain = false;
784 + status() {
785 + return {
786 + generation: this.generation,
787 + pid: this.child?.pid,
788 + port: this.port,
789 + endpoint: this.endpoint,
790 + protocol: `${this.endpoint}/json/protocol`,
791 + version: this.version,
792 + binary: this.binary,
793 + headed: this.headed,
794 + viewport: this.viewport,
795 + profile: this.persistent ? "named" : "temporary",
796 + initialTarget: this.initialTarget,
797 + initialSession: this.initialSession,
798 + targets: this.observedTargets,
799 + sessions: Object.fromEntries(this.sessions),
800 + monitor: Object.fromEntries(this.monitor),
801 + autoAttach: this.autoAttach,
802 + uncertain: this.uncertain,
803 + notices: this.notices.slice(-8),
804 + lateResponses: this.lateResponses,
805 + video: this.video?.file,
806 + droppedVideoFrames: this.video?.droppedFrames,
807 + trace: this.trace?.file,
808 + gaps: this.gaps,
809 + };
812 + async outputFile(filename: string | undefined, ext: string): Promise<string> {
813 + await mkdir(this.artifactDir, { recursive: true, mode: 0o700 });
814 + const name =
815 + filename ||
816 + `chrome-cdp-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomUUID()}.${ext}`;
817 + const path = artifactPath(this.artifactDir, name);
818 + if (existsSync(path)) throw new Error(`artifact already exists: ${path}`);
819 + return path;
822 + async screenshot(
823 + sid: string,
824 + filename?: string,
825 + fullPage = false,
826 + ): Promise<{ file: string; data: string }> {
827 + const response = await this.send(
828 + "Page.captureScreenshot",
829 + { format: "png", captureBeyondViewport: fullPage, fromSurface: true },
830 + sid,
831 + );
832 + if (response.error) throw new Error(response.error.message);
833 + const data = String((response.result as Record<string, Json>).data || "");
834 + const file = await this.outputFile(filename, "png");
835 + await saveNew(file, Buffer.from(data, "base64"));
836 + return { file, data };
839 + async startVideo(sid: string, filename?: string): Promise<string> {
840 + if (this.video) throw new Error("video already running");
841 + const file = await this.outputFile(filename, "webm");
842 + if (!file.endsWith(".webm"))
843 + throw new Error("video filename must end in .webm");
844 + const ffmpeg = spawn(
845 + "ffmpeg",
847 + "-loglevel",
848 + "error",
849 + "-f",
850 + "image2pipe",
851 + "-framerate",
852 + "8",
853 + "-vcodec",
854 + "mjpeg",
855 + "-i",
856 + "pipe:0",
857 + "-an",
858 + "-c:v",
859 + "libvpx-vp9",
860 + "-n",
861 + file,
862 + ],
863 + { stdio: ["pipe", "ignore", "pipe"] },
864 + );
865 + await new Promise<void>((resolve, reject) => {
866 + ffmpeg.once("spawn", () => resolve());
867 + ffmpeg.once("error", reject);
868 + });
869 + let error = "";
870 + ffmpeg.stderr?.on("data", (data) => {
871 + error = (error + String(data)).slice(-2048);
872 + });
873 + ffmpeg.stdin?.on("error", () => {
874 + /* encoder exit is reported by stopVideo */
875 + });
876 + const done = new Promise<number | null>((resolve) =>
877 + ffmpeg.once("exit", (code) => resolve(code)),
878 + );
879 + const timer = setTimeout(
880 + () =>
881 + void this.stopVideo().catch((e) => {
882 + this.notices.push(`video finalize failed: ${String(e)}`);
883 + }),
884 + VIDEO_MAX,
885 + );
886 + const video: Video = {
887 + file,
888 + process: ffmpeg,
889 + sessionId: sid,
890 + size: 0,
891 + droppedFrames: 0,
892 + done,
893 + timer,
894 + };
895 + this.video = video;
896 + const r = await this.send(
897 + "Page.startScreencast",
898 + { format: "jpeg", quality: 75, everyNthFrame: 1 },
899 + sid,
900 + );
901 + if (r.error) {
902 + await this.stopVideo();
903 + throw new Error(r.error.message);
905 + // ffmpeg's image pipe has no timestamps; sample at its declared 8 fps rather than
906 + // treating every incoming (variable-rate) CDP frame as 125 ms of playback.
907 + video.sampleTimer = setInterval(() => {
908 + if (!video.lastFrame) return;
909 + if (
910 + video.process.stdin?.writable &&
911 + video.process.stdin.writableLength < 2 * 1024 * 1024
912 + ) {
913 + video.process.stdin.write(video.lastFrame);
914 + video.samples = (video.samples || 0) + 1;
915 + } else video.droppedFrames++;
916 + }, 125);
917 + return file;
920 + async stopVideo(issueStop = true): Promise<string> {
921 + if (this.videoStopping) return this.videoStopping;
922 + const v = this.video;
923 + if (!v) throw new Error("no managed video running");
924 + this.videoStopping = (async () => {
925 + clearTimeout(v.timer);
926 + if (v.sampleTimer) clearInterval(v.sampleTimer);
927 + if (issueStop && this.socket?.readyState === WebSocket.OPEN)
928 + await this.send("Page.stopScreencast", {}, v.sessionId).catch(() => {});
929 + v.process.stdin?.end();
930 + let guard: NodeJS.Timeout | undefined;
931 + const code = await Promise.race([
932 + v.done,
933 + new Promise<null>((resolve) => {
934 + guard = setTimeout(() => resolve(null), 5000);
935 + }),
936 + ]);
937 + if (guard) clearTimeout(guard);
938 + if (code === null) {
939 + v.process.kill("SIGKILL");
940 + await v.done;
942 + if (this.video === v) this.video = undefined;
943 + if (code !== 0 || !existsSync(v.file))
944 + throw new Error(`ffmpeg failed (${code ?? "timeout"}); ${v.file}`);
945 + return v.file;
946 + })();
947 + try {
948 + return await this.videoStopping;
949 + } finally {
950 + this.videoStopping = undefined;
954 + async startTrace(filename?: string): Promise<string> {
955 + if (this.trace) throw new Error("trace already running");
956 + const file = await this.outputFile(filename, "json");
957 + let finish!: (v: Record<string, Json>) => void;
958 + const done = new Promise<Record<string, Json>>((resolve) => {
959 + finish = resolve;
960 + });
961 + const timer = setTimeout(
962 + () =>
963 + void this.stopTrace().catch((e) => {
964 + this.notices.push(`trace finalize failed: ${String(e)}`);
965 + }),
966 + VIDEO_MAX,
967 + );
968 + this.trace = { file, done, finish, timer };
969 + const result = await this.send("Tracing.start", {
970 + categories: traceCategories,
971 + transferMode: "ReturnAsStream",
972 + });
973 + if (result.error) {
974 + clearTimeout(timer);
975 + this.trace = undefined;
976 + throw new Error(result.error.message);
978 + return file;
981 + async stopTrace(issueEnd = true): Promise<string> {
982 + if (this.traceStopping) return this.traceStopping;
983 + const trace = this.trace;
984 + if (!trace) throw new Error("no managed trace running");
985 + this.traceStopping = (async () => {
986 + clearTimeout(trace.timer);
987 + try {
988 + if (issueEnd) {
989 + const end = await this.send("Tracing.end");
990 + if (end.error) throw new Error(end.error.message);
992 + let guard: NodeJS.Timeout | undefined;
993 + const completion = await Promise.race([
994 + trace.done,
995 + new Promise<null>((resolve) => {
996 + guard = setTimeout(() => resolve(null), 15000);
997 + }),
998 + ]);
999 + if (guard) clearTimeout(guard);
1000 + if (!completion?.stream) throw new Error("trace stream not returned");
1001 + const stream = String(completion.stream);
1002 + let out: Awaited<ReturnType<typeof open>> | undefined;
1003 + let finished = false;
1004 + let bytes = 0;
1005 + try {
1006 + out = await open(trace.file, "wx", 0o600);
1007 + while (true) {
1008 + const r = await this.send("IO.read", {
1009 + handle: stream,
1010 + size: 1024 * 1024,
1011 + });
1012 + if (r.error) throw new Error(r.error.message);
1013 + const data = r.result as Record<string, Json>;
1014 + const chunk = data.base64Encoded
1015 + ? Buffer.from(String(data.data), "base64")
1016 + : Buffer.from(String(data.data || ""));
1017 + bytes += chunk.length;
1018 + if (bytes > VIDEO_BYTES)
1019 + throw new Error("trace size limit reached");
1020 + await out.writeFile(chunk);
1021 + if (data.eof) break;
1023 + finished = true;
1024 + } finally {
1025 + try {
1026 + await out?.close();
1027 + } finally {
1028 + await this.send("IO.close", { handle: stream }).catch(() => {});
1029 + if (out && !finished) await rm(trace.file, { force: true });
1032 + return trace.file;
1033 + } finally {
1034 + if (this.trace === trace) this.trace = undefined;
1036 + })();
1037 + try {
1038 + return await this.traceStopping;
1039 + } finally {
1040 + this.traceStopping = undefined;
1044 + spoolPayload(text: string): Promise<string> {
1045 + return this.queueSpool(async () => {
1046 + const bytes = Buffer.byteLength(text);
1047 + if (bytes > SPOOL_LIMIT)
1048 + throw new Error("tool result exceeds spool quota");
1049 + if (!(await this.makeSpoolRoom(bytes)))
1050 + throw new Error(
1051 + "tool result exceeds available spool quota; current batch files are retained",
1052 + );
1053 + const file = join(this.spoolDir, `batch-${randomUUID()}.json`);
1054 + await saveNew(file, text);
1055 + this.spoolFiles.push({ file, bytes });
1056 + this.spoolBytes += bytes;
1057 + this.protectSpoolFile(file);
1058 + return file;
1059 + });
1062 + spoolFrame(
1063 + frame: Frame,
1064 + text = JSON.stringify(frame),
1065 + ): Promise<{ path: string; bytes: number; preview: string } | Frame> {
1066 + return this.queueSpool(async () => {
1067 + const bytes = Buffer.byteLength(text);
1068 + if (bytes <= INLINE) return frame;
1069 + if (bytes > SPOOL_LIMIT)
1070 + throw new Error(`response ${bytes} bytes exceeds spool quota`);
1071 + if (!(await this.makeSpoolRoom(bytes)))
1072 + throw new Error(
1073 + `response ${bytes} bytes exceeds available spool quota; current batch files are retained`,
1074 + );
1075 + const file = join(
1076 + this.spoolDir,
1077 + `response-${frame.id}-${randomUUID()}.json`,
1078 + );
1079 + await saveNew(file, text);
1080 + this.spoolFiles.push({ file, bytes });
1081 + this.spoolBytes += bytes;
1082 + this.protectSpoolFile(file);
1083 + return { path: file, bytes, preview: text.slice(0, 512) };
1084 + });
1087 + async close(): Promise<void> {
1088 + if (this.closed) return;
1089 + this.flushEventCounts();
1090 + this.diagnostic?.({ event: "browser.close.start" });
1091 + const failed = (type: string) => (e: unknown) => {
1092 + this.notices.push(`${type} finalize failed: ${String(e)}`);
1093 + };
1094 + if (this.videoStopping) await this.videoStopping.catch(failed("video"));
1095 + else if (this.video) await this.stopVideo().catch(failed("video"));
1096 + if (this.traceStopping) await this.traceStopping.catch(failed("trace"));
1097 + else if (this.trace) await this.stopTrace().catch(failed("trace"));
1098 + if (
1099 + this.child &&
1100 + this.child.exitCode === null &&
1101 + this.child.signalCode === null &&
1102 + this.socket?.readyState === WebSocket.OPEN
1103 + ) {
1104 + try {
1105 + this.socket.send(
1106 + JSON.stringify({
1107 + id: this.nextId++,
1108 + method: "Browser.close",
1109 + params: {},
1110 + }),
1111 + );
1112 + } catch {
1113 + /* fall back to SIGTERM */
1115 + await waitExit(this.child);
1117 + this.socket?.close();
1118 + if (
1119 + this.child &&
1120 + this.child.exitCode === null &&
1121 + this.child.signalCode === null
1122 + ) {
1123 + this.child.kill("SIGTERM");
1124 + if (!(await waitExit(this.child))) {
1125 + this.child.kill("SIGKILL");
1126 + if (!(await waitExit(this.child)))
1127 + throw new Error("Chrome remains alive; profile and lock preserved");
1130 + if (!this.persistent && this.profileDir)
1131 + await rm(this.profileDir, { recursive: true, force: true });
1132 + if (this.spoolDir)
1133 + await rm(this.spoolDir, { recursive: true, force: true });
1134 + for (const f of this.spoolFiles)
1135 + if (!f.bytes) await rm(f.file, { recursive: true, force: true });
1136 + if (this.persistent && this.ownedLock) {
1137 + const lock = join(this.profileDir, ".pi-chrome-cdp-lock");
1138 + const current = JSON.parse(await readFile(lock, "utf8")) as {
1139 + token?: string;
1140 + };
1141 + if (current.token !== this.lockToken)
1142 + throw new Error("profile lock ownership changed; refusing release");
1143 + await rm(lock);
1144 + this.ownedLock = false;
1146 + this.closed = true;
1147 + this.diagnostic?.({ event: "browser.close.end", outcome: "ok" });
1151 +export async function executeOperations(
1152 + b: Browser,
1153 + ops: Operation[],
1154 + signal?: AbortSignal,
1155 + replayFrom?: number,
1156 + onProgress?: (completed: number, active: string) => void,
1157 +): Promise<{
1158 + output: unknown[];
1159 + images: { data: string; mimeType: string }[];
1160 + events: Event[];
1161 + overflow: string[];
1162 + status: ReturnType<Browser["status"]>;
1163 + cursor: number;
1164 + failure?: string;
1165 + failedOperation?: { operation: number; kind: Operation["kind"] };
1166 + skipped?: { operation: number; kind: Operation["kind"] }[];
1167 +}> {
1168 + const results: unknown[] = [],
1169 + images: { data: string; mimeType: string }[] = [];
1170 + let failure: string | undefined;
1171 + let failedOperation:
1172 + | { operation: number; kind: Operation["kind"] }
1173 + | undefined;
1174 + const skipped = (from: number) =>
1175 + ops.slice(from).map((op, index) => ({
1176 + operation: from + index,
1177 + kind: op.kind,
1178 + }));
1179 + const startSeq = replayFrom ?? b.cursor;
1180 + const closeIndex = ops.findIndex((op) => op.kind === "close");
1181 + if (closeIndex >= 0 && ops.length !== 1)
1182 + return {
1183 + output: [],
1184 + images,
1185 + events: [],
1186 + overflow: [],
1187 + status: b.status(),
1188 + cursor: b.cursor,
1189 + failure: "close must be the only operation in its call",
1190 + failedOperation: { operation: closeIndex, kind: "close" },
1191 + skipped: skipped(closeIndex + 1),
1192 + };
1193 + const waits = new Map<string, Watcher>();
1194 + const knownLabels = new Set<string>();
1195 + for (const [index, op] of ops.entries()) {
1196 + if (op.kind === "cdp" && op.label) knownLabels.add(op.label);
1197 + if (op.kind === "wait") {
1198 + if (!op.after || !knownLabels.has(op.after) || !op.event || !op.sessionId)
1199 + return {
1200 + output: [],
1201 + images,
1202 + events: [],
1203 + overflow: [],
1204 + status: b.status(),
1205 + cursor: b.cursor,
1206 + failure:
1207 + "wait must follow a labeled cdp command in the same batch and include after, event, and sessionId",
1208 + failedOperation: { operation: index, kind: "wait" },
1209 + skipped: skipped(index + 1),
1210 + };
1211 + if (waits.has(op.after))
1212 + return {
1213 + output: [],
1214 + images,
1215 + events: [],
1216 + overflow: [],
1217 + status: b.status(),
1218 + cursor: b.cursor,
1219 + failure: `multiple waits use after label: ${op.after}; use distinct labeled cdp commands`,
1220 + failedOperation: { operation: index, kind: "wait" },
1221 + skipped: skipped(index + 1),
1222 + };
1223 + waits.set(op.after, {
1224 + method: op.event,
1225 + sessionId: op.sessionId,
1226 + since: 0,
1227 + });
1230 + b.beginBatchSpool(startSeq);
1231 + const session = (op: Operation): string | undefined => {
1232 + if (!op.sessionId) return undefined;
1233 + const sid = ref(op.sessionId, b.results);
1234 + if (typeof sid !== "string")
1235 + throw new Error("sessionId reference must resolve to a string");
1236 + return sid;
1237 + };
1238 + try {
1239 + for (let i = 0; i < ops.length; i++) {
1240 + const op = ops[i];
1241 + const started = Date.now();
1242 + b.diagnostic?.({
1243 + event: "operation.start",
1244 + operation: i,
1245 + kind: op.kind,
1246 + method: op.kind === "cdp" ? op.method : undefined,
1247 + });
1248 + onProgress?.(i, op.kind === "cdp" ? `cdp ${op.method ?? ""}` : op.kind);
1249 + try {
1250 + if (signal?.aborted) {
1251 + b.uncertain = true;
1252 + throw new Error("canceled before next operation");
1254 + if (b.uncertain && op.kind !== "status" && op.kind !== "close")
1255 + throw new Error("browser state uncertain; call managed status first");
1256 + if (op.kind === "cdp") {
1257 + if (!op.method) throw new Error("method required");
1258 + const sid = session(op);
1259 + if (
1260 + !sid &&
1261 + /^(Page|DOM|Runtime|Log|Network|CSS|Input|Accessibility|Performance|Emulation|Fetch)\./.test(
1262 + op.method,
1265 + throw new Error("page command requires sessionId");
1266 + if (op.label) {
1267 + if (!/^[a-zA-Z][\w-]*$/.test(op.label))
1268 + throw new Error("invalid command label");
1269 + if (b.results.has(op.label))
1270 + throw new Error(`duplicate label: ${op.label}`);
1272 + if (op.label && waits.has(op.label)) {
1273 + const watcher = waits.get(op.label);
1274 + if (!watcher) throw new Error("wait not armed");
1275 + watcher.sessionId =
1276 + session({ ...op, sessionId: watcher.sessionId }) || "";
1277 + watcher.since = b.seq;
1278 + b.watchers.push(watcher);
1280 + const p = ref(op.params ?? {}, b.results);
1281 + const frame = await b.send(
1282 + op.method,
1283 + p,
1284 + sid,
1285 + signal,
1286 + op.timeoutMs || COMMAND_MS,
1287 + );
1288 + const serialized =
1289 + op.label && !frame.error ? JSON.stringify(frame) : undefined;
1290 + if (
1291 + op.label &&
1292 + serialized &&
1293 + Buffer.byteLength(serialized) <= INLINE
1294 + ) {
1295 + b.results.set(op.label, frame);
1296 + if (b.results.size > 128) {
1297 + const oldest = b.results.keys().next().value;
1298 + if (oldest !== undefined) b.results.delete(oldest);
1301 + if (
1302 + sid &&
1303 + /^(Runtime|Log)\.(enable|disable)$/.test(op.method) &&
1304 + !frame.error
1306 + b.monitor.set(
1307 + `${sid}:${op.method.split(".")[0]}`,
1308 + op.method.endsWith("enable"),
1309 + );
1310 + const entry: Record<string, unknown> = {
1311 + operation: i,
1312 + command: op.method,
1313 + ...(frame.transportError
1314 + ? { transport: frame }
1315 + : { raw: await b.spoolFrame(frame, serialized) }),
1316 + };
1317 + results.push(entry);
1318 + if (frame.error) throw new Error(frame.error.message);
1319 + if (
1320 + op.method === "Target.setAutoAttach" &&
1321 + p &&
1322 + typeof p === "object" &&
1323 + !Array.isArray(p) &&
1324 + p.autoAttach === false
1325 + ) {
1326 + b.autoAttach = false;
1327 + entry.interference = "managed descendant monitoring disabled";
1329 + if (
1330 + (op.method === "Page.stopScreencast" ||
1331 + op.method === "Page.startScreencast") &&
1332 + sid &&
1333 + b.video?.sessionId === sid
1334 + ) {
1335 + entry.interference = "managed video interrupted";
1336 + entry.partialFile = await b.stopVideo(false);
1338 + if (op.method === "Tracing.end" && b.trace) {
1339 + entry.interference = "managed trace ended by raw command";
1340 + entry.partialFile = await b.stopTrace(false);
1342 + } else if (op.kind === "status") {
1343 + await b.refreshStatus();
1344 + results.push({
1345 + operation: i,
1346 + status: b.status(),
1347 + note: "observed status; earlier unconfirmed command may still take effect",
1348 + });
1349 + } else if (op.kind === "wait") {
1350 + const watcher = op.after ? waits.get(op.after) : undefined;
1351 + if (!watcher) throw new Error("wait not armed");
1352 + let hit = watcher.hit;
1353 + const end = Date.now() + (op.timeoutMs || 5000);
1354 + while (!hit && Date.now() < end && !signal?.aborted) {
1355 + await new Promise((r) => setTimeout(r, 20));
1356 + hit = watcher.hit;
1358 + if (signal?.aborted) {
1359 + b.uncertain = true;
1360 + throw new Error("wait canceled; command effects uncertain");
1362 + if (!hit)
1363 + throw new Error(
1364 + `wait timed out: ${op.event} on ${watcher.sessionId}`,
1365 + );
1366 + results.push({ operation: i, wait: hit });
1367 + } else if (op.kind === "screenshot") {
1368 + const sid = session(op);
1369 + if (!sid) throw new Error("screenshot requires sessionId");
1370 + const image = await b.screenshot(sid, op.filename, op.fullPage);
1371 + images.push({ data: image.data, mimeType: "image/png" });
1372 + results.push({ operation: i, file: image.file });
1373 + } else if (op.kind === "videoStart") {
1374 + const sid = session(op);
1375 + if (!sid) throw new Error("videoStart requires sessionId");
1376 + results.push({
1377 + operation: i,
1378 + file: await b.startVideo(sid, op.filename),
1379 + });
1380 + } else if (op.kind === "videoStop")
1381 + results.push({ operation: i, file: await b.stopVideo() });
1382 + else if (op.kind === "traceStart")
1383 + results.push({ operation: i, file: await b.startTrace(op.filename) });
1384 + else if (op.kind === "traceStop")
1385 + results.push({ operation: i, file: await b.stopTrace() });
1386 + else if (op.kind === "close") {
1387 + await b.close();
1388 + results.push({ operation: i, closed: true });
1389 + break;
1390 + } else throw new Error(`unknown operation: ${String(op.kind)}`);
1391 + } catch (error) {
1392 + failure = error instanceof Error ? error.message : String(error);
1393 + failedOperation = { operation: i, kind: op.kind };
1394 + b.diagnostic?.({
1395 + event: "operation.end",
1396 + operation: i,
1397 + kind: op.kind,
1398 + elapsedMs: Date.now() - started,
1399 + outcome: "error",
1400 + });
1401 + break;
1403 + b.diagnostic?.({
1404 + event: "operation.end",
1405 + operation: i,
1406 + kind: op.kind,
1407 + elapsedMs: Date.now() - started,
1408 + outcome: "ok",
1409 + });
1410 + onProgress?.(i + 1, "");
1412 + } finally {
1413 + const owned = new Set(waits.values());
1414 + b.watchers = b.watchers.filter((w) => !owned.has(w));
1416 + if (b.closed)
1417 + return {
1418 + output: results,
1419 + images,
1420 + events: [],
1421 + overflow: [],
1422 + status: b.status(),
1423 + cursor: b.seq,
1424 + ...(failure
1425 + ? {
1426 + failure,
1427 + failedOperation,
1428 + skipped: skipped((failedOperation?.operation || 0) + 1),
1430 + : {}),
1431 + };
1432 + await b.spoolWrites;
1433 + const candidates = b.events.filter((e) => e.seq > startSeq);
1434 + const events: Event[] = [];
1435 + let eventBytes = 0;
1436 + for (let i = candidates.length - 1; i >= 0; i--) {
1437 + const e = candidates[i];
1438 + const size = Buffer.byteLength(JSON.stringify(e));
1439 + if (eventBytes + size <= 65536) {
1440 + events.unshift(e);
1441 + eventBytes += size;
1442 + } else await b.spoolEvent(e);
1444 + const overflow = b.spoolFiles
1445 + .filter(
1446 + (f) =>
1447 + f.bytes > 0 &&
1448 + f.lastEventSeq !== undefined &&
1449 + f.lastEventSeq > startSeq,
1451 + .map((f) => {
1452 + b.protectSpoolFile(f.file);
1453 + return f.file;
1454 + });
1455 + b.cursor = b.seq;
1456 + return {
1457 + output: results,
1458 + images,
1459 + events,
1460 + overflow,
1461 + status: b.status(),
1462 + cursor: b.cursor,
1463 + ...(failure
1464 + ? {
1465 + failure,
1466 + failedOperation,
1467 + skipped: skipped((failedOperation?.operation || 0) + 1),
1469 + : {}),
1470 + };

extensions/chrome-cdp/debug.ts

Added
new file mode 100644
1 +import { constants } from "node:fs";
2 +import { type FileHandle, open } from "node:fs/promises";
4 +// Metadata only: never log CDP params, responses, events, screenshots, cookies, or URLs.
5 +export type Diagnostic = {
6 + event: string;
7 + operation?: number;
8 + kind?: string;
9 + method?: string;
10 + wireId?: number;
11 + sessionId?: string;
12 + elapsedMs?: number;
13 + bytes?: number;
14 + count?: number;
15 + code?: number;
16 + outcome?: string;
17 +};
19 +export class DebugLog {
20 + private writes = Promise.resolve();
21 + private bytes = 0;
22 + private error?: Error;
23 + private readonly limit = 8 * 1024 * 1024;
24 + private readonly file: FileHandle;
26 + private constructor(file: FileHandle) {
27 + this.file = file;
28 + }
30 + static async open(path: string): Promise<DebugLog> {
31 + const file = await open(
32 + path,
33 + constants.O_WRONLY |
34 + constants.O_APPEND |
35 + constants.O_CREAT |
36 + (constants.O_NOFOLLOW || 0),
37 + 0o600,
38 + );
39 + try {
40 + const info = await file.stat();
41 + if (!info.isFile()) throw new Error("debug path is not a regular file");
42 + if ((info.mode & 0o077) !== 0)
43 + throw new Error("debug log must not be accessible by group or others");
44 + if (info.size >= 8 * 1024 * 1024)
45 + throw new Error("debug log reached 8 MiB limit; choose a new file");
46 + const log = new DebugLog(file);
47 + log.bytes = info.size;
48 + return log;
49 + } catch (e) {
50 + await file.close();
51 + throw e;
52 + }
53 + }
55 + record(data: Diagnostic): void {
56 + if (this.error || this.bytes >= this.limit) return;
57 + const row =
58 + JSON.stringify({
59 + time: new Date().toISOString(),
60 + ...data,
61 + method:
62 + data.method && /^[A-Za-z][A-Za-z0-9_.]*$/.test(data.method)
63 + ? data.method
64 + : undefined,
65 + sessionId:
66 + data.sessionId && /^[A-Za-z0-9_-]{1,128}$/.test(data.sessionId)
67 + ? data.sessionId
68 + : undefined,
69 + }) + "\n";
70 + const size = Buffer.byteLength(row);
71 + if (this.bytes + size + 128 > this.limit) {
72 + const notice =
73 + JSON.stringify({
74 + time: new Date().toISOString(),
75 + event: "debug.limit",
76 + bytes: this.bytes,
77 + }) + "\n";
78 + this.writes = this.writes
79 + .then(async () => {
80 + await this.file.write(notice);
81 + })
82 + .catch((e) => {
83 + this.error = e instanceof Error ? e : new Error(String(e));
84 + });
85 + this.bytes = this.limit;
86 + return;
87 + }
88 + this.bytes += size;
89 + this.writes = this.writes
90 + .then(async () => {
91 + await this.file.write(row);
92 + })
93 + .catch((e) => {
94 + this.error = e instanceof Error ? e : new Error(String(e));
95 + });
96 + }
98 + async close(): Promise<void> {
99 + await this.writes;
100 + await this.file.close();
101 + if (this.error) throw this.error;

extensions/chrome-cdp/index.ts

Added
new file mode 100644
1 +import { resolve } from "node:path";
2 +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
3 +import { keyHint, SettingsManager } from "@earendil-works/pi-coding-agent";
4 +import { Text } from "@earendil-works/pi-tui";
5 +import { Type } from "typebox";
6 +import {
7 + Browser,
8 + executeOperations,
9 + type Operation,
10 + type Options,
11 +} from "./browser.ts";
12 +import { DebugLog } from "./debug.ts";
13 +import { findExecutable } from "./lib.ts";
15 +const OP = Type.Object({
16 + kind: Type.Union(
17 + [
18 + "cdp",
19 + "wait",
20 + "status",
21 + "close",
22 + "screenshot",
23 + "videoStart",
24 + "videoStop",
25 + "traceStart",
26 + "traceStop",
27 + ].map((v) => Type.Literal(v)),
28 + {
29 + description:
30 + "cdp sends a raw method; wait watches an event; status resynchronizes; close stops Chrome; capture kinds save files.",
31 + },
32 + ),
33 + method: Type.Optional(
34 + Type.String({
35 + description:
36 + "Raw CDP method for kind=cdp, e.g. Page.navigate or Browser.getVersion.",
37 + }),
38 + ),
39 + params: Type.Optional(
40 + Type.Record(Type.String(), Type.Unknown(), {
41 + description:
42 + "Raw CDP params object for kind=cdp; whole values may use {{label.result.path}}.",
43 + }),
44 + ),
45 + sessionId: Type.Optional(
46 + Type.String({
47 + description:
48 + "CDP session for page commands, waits, screenshots, and video; omit for browser commands. Accepts a result reference.",
49 + }),
50 + ),
51 + label: Type.Optional(
52 + Type.String({
53 + description:
54 + "Name this cdp response for later {{label.result.path}} references or a wait.after.",
55 + }),
56 + ),
57 + after: Type.Optional(
58 + Type.String({
59 + description:
60 + "For kind=wait: label of an earlier command; observation starts before that command is sent.",
61 + }),
62 + ),
63 + event: Type.Optional(
64 + Type.String({
65 + description: "For kind=wait: CDP event method, e.g. Page.loadEventFired.",
66 + }),
67 + ),
68 + timeoutMs: Type.Optional(
69 + Type.Integer({
70 + minimum: 1,
71 + maximum: 300000,
72 + description: "Command or wait timeout in milliseconds.",
73 + }),
74 + ),
75 + filename: Type.Optional(
76 + Type.String({
77 + description:
78 + "For captures: basename under configured artifact directory or OS Downloads; never an absolute path.",
79 + }),
80 + ),
81 + fullPage: Type.Optional(
82 + Type.Boolean({
83 + description:
84 + "For kind=screenshot: capture beyond viewport when true; default false.",
85 + }),
86 + ),
87 +});
88 +const PARAMS = Type.Object({
89 + operations: Type.Array(OP, {
90 + maxItems: 50,
91 + description:
92 + "Sequential operations; stop on first error. Use status to resynchronize after uncertain effects.",
93 + }),
94 + launch: Type.Optional(
95 + Type.Object(
96 + {
97 + headed: Type.Optional(
98 + Type.Boolean({
99 + description:
100 + "Show Chrome window on first launch; default headless, cannot change until close.",
101 + }),
102 + ),
103 + },
105 + description:
106 + "Chrome launch options, applied only when starting a new process.",
107 + },
108 + ),
109 + ),
110 + replayFrom: Type.Optional(
111 + Type.Integer({
112 + minimum: 0,
113 + description: "Replay retained events after this returned event cursor.",
114 + }),
115 + ),
116 +});
118 +type Progress = {
119 + completed: number;
120 + total: number;
121 + active: string;
122 + elapsedMs: number;
124 +type ChromeDetails = {
125 + progress?: Progress;
126 + completed?: number;
127 + total?: number;
128 + failure?: string;
129 + failedOperation?: { operation: number; kind: string };
130 + skipped?: { operation: number; kind: string }[];
131 + eventCount?: number;
132 + files?: string[];
133 + resultSpool?: string;
134 + operations?: string[];
135 + browser?: string;
136 + pages?: number;
139 +const display = (value: string, limit = 120) =>
140 + value.replace(/[\x00-\x1f\x7f-\x9f]/g, "?").slice(0, limit);
141 +const operationName = (op: Operation) =>
142 + op.kind === "cdp"
143 + ? display(op.method ?? "CDP command", 64)
144 + : op.kind === "wait"
145 + ? `wait ${display(op.event ?? "event", 64)}`
146 + : op.kind;
148 +function resultPreview(text: string): string {
149 + let formatted = text;
150 + if (text.length <= 16_000) {
151 + try {
152 + const value = JSON.parse(text) as { output?: unknown[] };
153 + formatted = JSON.stringify(value.output ?? value, null, 2);
154 + } catch {
155 + // Tool errors may not be JSON.
158 + const safe = formatted.replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "?");
159 + const lines = safe.split("\n");
160 + const preview = lines.slice(0, 24).join("\n").slice(0, 2400);
161 + return preview.length < safe.length
162 + ? `${preview}\n… UI preview truncated`
163 + : preview;
166 +function config(cwd: string): Options {
167 + const settings = SettingsManager.create(cwd);
168 + const project = (settings.getProjectSettings() as Record<string, unknown>)[
169 + "chrome-cdp"
170 + ];
171 + const global = (settings.getGlobalSettings() as Record<string, unknown>)[
172 + "chrome-cdp"
173 + ];
174 + const p =
175 + project && typeof project === "object"
176 + ? (project as Record<string, unknown>)
177 + : {};
178 + const g =
179 + global && typeof global === "object"
180 + ? (global as Record<string, unknown>)
181 + : {};
182 + const get = (key: string) => p[key] ?? g[key];
183 + const executablePath = get("executablePath");
184 + const profile = get("profile");
185 + const artifactDir = get("artifactDir");
186 + const flags = get("flags");
187 + return {
188 + executablePath:
189 + typeof executablePath === "string" ? executablePath : undefined,
190 + profile: typeof profile === "string" ? profile : undefined,
191 + artifactDir: typeof artifactDir === "string" ? artifactDir : undefined,
192 + flags:
193 + Array.isArray(flags) && flags.every((x) => typeof x === "string")
194 + ? flags
195 + : undefined,
196 + };
199 +export default function chromeExtension(pi: ExtensionAPI) {
200 + pi.registerFlag("chrome", {
201 + description: "Enable chrome_cdp at startup",
202 + type: "boolean",
203 + default: false,
204 + });
205 + let browser: Browser | undefined;
206 + let debug: DebugLog | undefined;
207 + let debugError: Error | undefined;
208 + let queue: Promise<unknown> = Promise.resolve();
209 + const exclusive = <T>(task: () => Promise<T>): Promise<T> => {
210 + const next = queue.then(task, task);
211 + queue = next.catch(() => {});
212 + return next;
213 + };
214 + const close = async () => {
215 + const old = browser;
216 + if (old) {
217 + await old.close();
218 + browser = undefined;
220 + };
221 + const active = () => pi.getActiveTools().includes("chrome_cdp");
222 + pi.registerCommand("chrome", {
223 + description: "Toggle chrome_cdp; /chrome close stops owned Chrome",
224 + handler: async (args, ctx) => {
225 + if (args.trim() === "close") {
226 + await exclusive(close);
227 + pi.setActiveTools(
228 + pi.getActiveTools().filter((x) => x !== "chrome_cdp"),
229 + );
230 + ctx.ui.notify("Chrome stopped; tool off", "info");
231 + return;
233 + const enable = !active();
234 + pi.setActiveTools(
235 + enable
236 + ? [...pi.getActiveTools(), "chrome_cdp"]
237 + : pi.getActiveTools().filter((x) => x !== "chrome_cdp"),
238 + );
239 + if (enable)
240 + try {
241 + findExecutable(config(ctx.cwd).executablePath);
242 + } catch (e) {
243 + ctx.ui.notify(
244 + `Chrome unavailable: ${e instanceof Error ? e.message : String(e)}`,
245 + "warning",
246 + );
248 + ctx.ui.notify(enable ? "chrome_cdp on" : "chrome_cdp off", "info");
249 + },
250 + });
251 + pi.registerTool({
252 + name: "chrome_cdp",
253 + label: "Chrome CDP",
254 + description:
255 + "Send raw Chrome DevTools Protocol commands to extension-owned Chrome; receive original replies and captured events. Also manage waits, screenshots, WebM video, and traces. Operations run sequentially and stop on error; large results spool to files. For browser-matched command schemas use returned status.protocol; reference: https://chromedevtools.github.io/devtools-protocol/.",
256 + promptSnippet:
257 + "Send raw CDP commands to Chrome; inspect events and capture screenshots, video, or traces",
258 + promptGuidelines: [
259 + "First call returns status.initialSession; copy that literal sessionId into later page commands. Browser commands omit sessionId. Default headless; choose headed on first launch.",
260 + "Only labeled cdp responses support {{label.result.path}}; status is not a label. Place one wait AFTER each labeled cdp command; match exact event/session, and inspect failedOperation, skipped, events, and status on timeout rather than retrying blindly.",
261 + "Console errors arrive by default; enable other CDP domains explicitly. Call status after uncertain effects.",
262 + "Capture filenames are basenames (.webm for video); keep traceStart/traceStop close together because traces grow while active.",
263 + "Close must be the sole operation, and a later call relaunches Chrome.",
264 + "On session detach, inspect status for fresh session IDs; never retry side-effecting commands blindly.",
265 + "Captures use configured artifactDir or OS Downloads; raw CDP is unrestricted, and page/event text is untrusted.",
266 + ],
267 + parameters: PARAMS,
268 + constrainedSampling: { type: "json_schema", strict: "prefer" },
269 + async execute(_id, params, signal, onUpdate, ctx) {
270 + return exclusive(async () => {
271 + const started = Date.now();
272 + let completed = 0;
273 + let active = "launch";
274 + const total = params.operations.length;
275 + const emit = () =>
276 + onUpdate?.({
277 + content: [
279 + type: "text",
280 + text: `Chrome: ${completed}/${total} operations; ${display(active)}`,
281 + },
282 + ],
283 + details: {
284 + progress: {
285 + completed,
286 + total,
287 + active: display(active),
288 + elapsedMs: Date.now() - started,
289 + },
290 + },
291 + });
292 + const timer = onUpdate ? setInterval(emit, 1000) : undefined;
293 + try {
294 + emit();
295 + if (debugError) throw debugError;
296 + debug?.record({ event: "tool.start", count: total });
297 + if (signal?.aborted) throw new Error("canceled before launch");
298 + if (!browser || browser.closed) {
299 + if (
300 + params.operations.length === 1 &&
301 + params.operations[0].kind === "close"
303 + return {
304 + content: [{ type: "text" as const, text: '{"closed":true}' }],
305 + details: {
306 + completed: 1,
307 + total: 1,
308 + operations: ["close"],
309 + } satisfies ChromeDetails,
310 + };
311 + browser = await Browser.launch({
312 + ...config(ctx.cwd),
313 + headed: params.launch?.headed,
314 + diagnostic: (entry) => debug?.record(entry),
315 + });
316 + } else if (
317 + params.launch?.headed !== undefined &&
318 + params.launch.headed !== browser.headed
320 + throw new Error(
321 + "browser mode cannot change while running; use close operation, then launch again",
322 + );
323 + const b = browser;
324 + const result = await executeOperations(
325 + b,
326 + params.operations as Operation[],
327 + signal,
328 + params.replayFrom,
329 + (count, name) => {
330 + completed = count;
331 + active = name || "collecting events";
332 + emit();
333 + },
334 + );
335 + if (b.closed) browser = undefined;
336 + const { images, ...text } = result;
337 + let payload = JSON.stringify(text);
338 + let resultSpool: string | undefined;
339 + if (Buffer.byteLength(payload) > 128 * 1024) {
340 + resultSpool = await b.spoolPayload(payload);
341 + payload = JSON.stringify({
342 + status: result.status,
343 + cursor: result.cursor,
344 + resultSpool,
345 + failure: result.failure,
346 + });
348 + debug?.record({
349 + event: "tool.end",
350 + count: result.output.length,
351 + outcome: result.failure ? "failure" : "ok",
352 + });
353 + const files = result.output
354 + .flatMap((item) => {
355 + const entry = item as {
356 + file?: unknown;
357 + partialFile?: unknown;
358 + raw?: { path?: unknown };
359 + };
360 + return [entry.file, entry.partialFile, entry.raw?.path].filter(
361 + (file): file is string => typeof file === "string",
362 + );
363 + })
364 + .concat(result.overflow);
365 + const operations = result.output.map((item) => {
366 + const entry = item as {
367 + command?: string;
368 + wait?: unknown;
369 + file?: unknown;
370 + closed?: unknown;
371 + };
372 + return (
373 + entry.command ??
374 + (entry.wait
375 + ? "wait"
376 + : entry.file
377 + ? "capture"
378 + : entry.closed
379 + ? "close"
380 + : "status")
381 + );
382 + });
383 + return {
384 + content: [
385 + { type: "text" as const, text: payload },
386 + ...images.map((image) => ({ type: "image" as const, ...image })),
387 + ],
388 + details: {
389 + completed: result.output.length,
390 + total,
391 + failure: result.failure,
392 + failedOperation: result.failedOperation,
393 + skipped: result.skipped,
394 + eventCount: result.events.length,
395 + files,
396 + resultSpool,
397 + operations,
398 + browser: result.status.version,
399 + pages: result.status.targets.filter(
400 + (target) => (target as { type?: string }).type === "page",
401 + ).length,
402 + } satisfies ChromeDetails,
403 + };
404 + } catch (e) {
405 + debug?.record({ event: "tool.end", outcome: "error" });
406 + throw new Error(e instanceof Error ? e.message : String(e));
407 + } finally {
408 + if (timer) clearInterval(timer);
410 + });
411 + },
412 + renderCall(args, theme, context) {
413 + const ops = args.operations as Operation[];
414 + let text = theme.fg("toolTitle", theme.bold(" Chrome"));
415 + if (context.expanded) {
416 + text += theme.fg(
417 + "dim",
418 + ` · ${ops.length} operation${ops.length === 1 ? "" : "s"}`,
419 + );
420 + for (const [index, op] of ops.slice(0, 12).entries())
421 + text += `\n${theme.fg("dim", `${index + 1}. `)}${theme.fg("accent", operationName(op))}`;
422 + if (ops.length > 12)
423 + text += `\n${theme.fg("muted", `+${ops.length - 12} more`)}`;
424 + } else {
425 + const names = ops.slice(0, 2).map(operationName).join(" → ");
426 + text += theme.fg("accent", ` · ${names || "no operations"}`);
427 + if (ops.length > 2) text += theme.fg("dim", ` +${ops.length - 2}`);
428 + text += theme.fg(
429 + "dim",
430 + ` (${keyHint("app.tools.expand", "to expand")})`,
431 + );
433 + return new Text(text, 0, 0);
434 + },
435 + renderResult(result, { expanded, isPartial }, theme, { isError }) {
436 + const details = result.details as ChromeDetails | undefined;
437 + if (isPartial) {
438 + const p = details?.progress;
439 + return new Text(
440 + theme.fg(
441 + "warning",
443 + ? `${p.completed}/${p.total} ops; ${display(p.active)} (${Math.floor(p.elapsedMs / 1000)}s)`
444 + : "Running Chrome...",
445 + ),
446 + 0,
447 + 0,
448 + );
450 + const content = result.content.find((c) => c.type === "text");
451 + if (isError) {
452 + const message =
453 + content?.type === "text" ? content.text : "Chrome failed";
454 + return new Text(
455 + theme.fg(
456 + "error",
457 + expanded ? resultPreview(message) : display(message, 200),
458 + ),
459 + 0,
460 + 0,
461 + );
463 + const count = details?.completed ?? 0;
464 + const total = details?.total ?? 0;
465 + let text = theme.fg(
466 + details?.failure ? "error" : "success",
467 + details?.failure
468 + ? `✗ ${count}/${total} operations`
469 + : `✓ ${count}/${total} operation${total === 1 ? "" : "s"}`,
470 + );
471 + if (details?.operations?.includes("status") && details.browser)
472 + text += theme.fg(
473 + "dim",
474 + ` · ${display(details.browser, 40)} · ${details.pages ?? 0} pages`,
475 + );
476 + if (details?.files?.length)
477 + text += theme.fg(
478 + "dim",
479 + ` · ${details.files.length} file${details.files.length === 1 ? "" : "s"}`,
480 + );
481 + if (details?.failure)
482 + text += theme.fg("error", ` · ${display(details.failure, 180)}`);
483 + if (expanded) {
484 + if (details?.eventCount)
485 + text += theme.fg("dim", ` · ${details.eventCount} events`);
486 + for (const file of details?.files?.slice(0, 8) ?? [])
487 + text += `\n${theme.fg("accent", display(file, 240))}`;
488 + if (details?.resultSpool)
489 + text += `\n${theme.fg("accent", `Full result: ${display(details.resultSpool, 240)}`)}`;
490 + if (content?.type === "text") {
491 + text += `\n${theme.fg("dim", "Result preview (raw CDP may contain page data):")}`;
492 + text += `\n${resultPreview(content.text)
493 + .split("\n")
494 + .map((line) => theme.fg("toolOutput", line))
495 + .join("\n")}`;
498 + return new Text(text, 0, 0);
499 + },
500 + });
501 + pi.on("session_start", async (_event, ctx) => {
502 + await exclusive(close);
503 + if (debug) {
504 + debug.record({ event: "session.end" });
505 + await debug.close();
506 + debug = undefined;
508 + debugError = undefined;
509 + pi.setActiveTools(
510 + pi.getFlag("chrome")
511 + ? [...new Set([...pi.getActiveTools(), "chrome_cdp"])]
512 + : pi.getActiveTools().filter((x) => x !== "chrome_cdp"),
513 + );
514 + if (process.env.PI_CHROME_CDP_DEBUG) {
515 + try {
516 + debug = await DebugLog.open(
517 + resolve(ctx.cwd, process.env.PI_CHROME_CDP_DEBUG),
518 + );
519 + debug.record({ event: "session.start" });
520 + } catch (e) {
521 + debugError = e instanceof Error ? e : new Error(String(e));
524 + });
525 + pi.on("session_shutdown", async () => {
526 + try {
527 + await exclusive(close);
528 + } finally {
529 + if (debug) {
530 + debug.record({ event: "session.end" });
531 + await debug.close();
532 + debug = undefined;
535 + });

extensions/chrome-cdp/lib.ts

Added
new file mode 100644
1 +import { accessSync, constants, readFileSync, statSync } from "node:fs";
2 +import { homedir, platform, tmpdir } from "node:os";
3 +import { basename, join, resolve, sep, win32 } from "node:path";
5 +export type Json =
6 + | null
7 + | boolean
8 + | number
9 + | string
10 + | Json[]
11 + | { [key: string]: Json };
12 +export type Frame = {
13 + id: number;
14 + result?: Json;
15 + error?: { code: number; message: string; data?: Json };
16 + transportError?: boolean;
17 + [key: string]: Json | undefined;
18 +};
20 +export function profileName(name: string): string {
21 + if (
22 + !/^[a-z0-9][a-z0-9_-]{0,47}$/.test(name) ||
23 + /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(name)
24 + )
25 + throw new Error(
26 + "profile name must be 1-48 lowercase ASCII letters, digits, _ or -, starting with letter/digit; reserved device names are invalid",
27 + );
28 + return name;
31 +export function dataRoot(
32 + os = platform(),
33 + env = process.env,
34 + home = homedir(),
35 +): string {
36 + if (os === "win32")
37 + return win32.join(
38 + env.LOCALAPPDATA || win32.join(home, "AppData", "Local"),
39 + "chrome-cdp",
40 + "profiles",
41 + );
42 + if (os === "darwin")
43 + return join(
44 + home,
45 + "Library",
46 + "Application Support",
47 + "chrome-cdp",
48 + "profiles",
49 + );
50 + return join(
51 + env.XDG_DATA_HOME || join(home, ".local", "share"),
52 + "chrome-cdp",
53 + "profiles",
54 + );
57 +export function downloads(
58 + os = platform(),
59 + env = process.env,
60 + home = homedir(),
61 +): string {
62 + if (os === "win32") return win32.join(env.USERPROFILE || home, "Downloads");
63 + if (os !== "darwin") {
64 + try {
65 + const file = readFileSync(
66 + join(env.XDG_CONFIG_HOME || join(home, ".config"), "user-dirs.dirs"),
67 + "utf8",
68 + );
69 + const found = file.match(/^XDG_DOWNLOAD_DIR="([^"\n]+)"/m)?.[1];
70 + if (found) return found.replace(/^\$HOME(?=\/|$)/, home);
71 + } catch {
72 + /* default */
73 + }
74 + }
75 + return join(home, "Downloads");
78 +export function artifactPath(root: string, filename: string): string {
79 + if (
80 + basename(filename) !== filename ||
81 + filename === "." ||
82 + filename === ".." ||
83 + /[\\/\0]/.test(filename)
84 + )
85 + throw new Error(
86 + "artifact filename must be a basename inside configured artifact directory",
87 + );
88 + const dest = resolve(root, filename);
89 + if (!dest.startsWith(resolve(root) + sep))
90 + throw new Error("artifact path escapes root");
91 + return dest;
94 +export function ref(value: Json, results: Map<string, Frame>): Json {
95 + if (typeof value === "string") {
96 + if (value.startsWith("\\{{")) return value.slice(1);
97 + const match = /^\{\{([a-zA-Z][\w-]*)(\.\w+(?:\.\w+)*)\}\}$/.exec(value);
98 + if (!match) return value;
99 + let node: unknown = results.get(match[1]);
100 + if (!node) throw new Error(`unknown result label: ${match[1]}`);
101 + for (const key of match[2].slice(1).split(".")) {
102 + if (node === null || typeof node !== "object" || !(key in node))
103 + throw new Error(`missing reference: ${value}`);
104 + node = (node as Record<string, unknown>)[key];
106 + return node as Json;
108 + if (Array.isArray(value)) return value.map((x) => ref(x, results));
109 + if (value && typeof value === "object")
110 + return Object.fromEntries(
111 + Object.entries(value).map(([k, v]) => [k, ref(v, results)]),
112 + );
113 + return value;
116 +export function executableCandidates(os = platform()): string[] {
117 + if (os === "win32")
118 + return ["chrome-for-testing.exe", "chrome.exe", "chromium.exe"];
119 + if (os === "darwin")
120 + return [
121 + "chrome-for-testing",
122 + "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
123 + `${homedir()}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`,
124 + "/Applications/Chromium.app/Contents/MacOS/Chromium",
125 + ];
126 + return [
127 + "chrome-for-testing",
128 + "google-chrome-stable",
129 + "google-chrome",
130 + "chromium",
131 + "chromium-browser",
132 + ];
135 +export function findExecutable(
136 + explicit?: string,
137 + os = platform(),
138 + env = process.env,
139 +): string {
140 + const candidates = explicit ? [explicit] : executableCandidates(os);
141 + const paths = (env.PATH || "").split(os === "win32" ? ";" : ":");
142 + if (!explicit && os === "win32") {
143 + for (const root of [
144 + env.PROGRAMFILES,
145 + env["PROGRAMFILES(X86)"],
146 + env.LOCALAPPDATA,
147 + ]) {
148 + if (root)
149 + candidates.push(
150 + win32.join(root, "Google", "Chrome", "Application", "chrome.exe"),
151 + );
154 + for (const c of candidates) {
155 + for (const path of c.includes("/") || c.includes("\\") ? [""] : paths) {
156 + const file = path ? join(path, c) : c;
157 + try {
158 + accessSync(file, os === "win32" ? constants.F_OK : constants.X_OK);
159 + if (statSync(file).isFile()) return resolve(file);
160 + } catch {
161 + /* try next candidate */
165 + throw new Error(
166 + `Chrome not found; set chrome-cdp.executablePath (checked: ${candidates.join(", ")})`,
167 + );
170 +export function binaryKey(file: string): string {
171 + const name = basename(file).toLowerCase();
172 + return name.includes("testing")
173 + ? "chrome-for-testing"
174 + : name.includes("chromium")
175 + ? "chromium"
176 + : "google-chrome-stable";
179 +export function validateFlags(flags: string[]): void {
180 + const forbidden =
181 + /^--(?:user-data-dir|remote-debugging-(?:port|address|pipe)|headless|window-size|disable-web-security|no-sandbox|download-default-directory|profile-directory|incognito|guest)(?:=|$)/;
182 + for (const flag of flags)
183 + if (forbidden.test(flag))
184 + throw new Error(`conflicting Chrome flag: ${flag}`);
187 +export const TMP_PREFIX = join(tmpdir(), "pi-chrome-cdp-");

extensions/chrome-cdp/mise.toml

Added
new file mode 100644
1 +[tasks.fmt]
2 +description = "Format chrome-cdp extension"
3 +depends = ["//:install"]
4 +run = [
5 + "biome check --write --config-path ../.. .",
6 + "rumdl fmt --config ../../.rumdl.toml .",
7 + "taplo format --config ../../.taplo.toml mise.toml",
8 +]
10 +[tasks.lint]
11 +description = "Lint chrome-cdp extension"
12 +depends = ["//:install"]
13 +run = [
14 + "biome ci --config-path ../.. .",
15 + "rumdl check --config ../../.rumdl.toml .",
16 + "taplo format --check --config ../../.taplo.toml mise.toml",
19 +[tasks.test]
20 +description = "Test chrome-cdp extension"
21 +depends = ["//:install"]
22 +run = [
23 + { task = "//:test", args = ["extensions/chrome-cdp"] },
26 +[tasks.check]
27 +description = "Check chrome-cdp extension"
28 +depends = ["//:install"]
29 +run = [
30 + { task = "//:build", args = ["chrome-cdp"] },
33 +[tasks.e2e]
34 +description = "Run real-Chrome acceptance tests (writes browser profiles and captures)"
35 +depends = ["//:install"]
36 +run = "npm exec -- vitest run --config vitest.e2e.config.ts"
38 +[tasks.bench]
39 +description = "Benchmark large CDP response spooling without a browser"
40 +depends = ["//:install"]
41 +usage = '''
42 +arg "[samples]" default="30"
43 +arg "[mode]" default="batch"
44 +'''
45 +run = "node --no-warnings --experimental-strip-types __bench__/spool.bench.ts {{ usage.samples }} {{ usage.mode }}"
47 +[tasks.profile]
48 +description = "Profile large CDP response spooling with Node CPU profiler"
49 +depends = ["//:install"]
50 +run = "node --cpu-prof --cpu-prof-dir ../../.pi/tmp/chrome-cdp-bench/profiles --no-warnings --experimental-strip-types __bench__/spool.bench.ts 80"

extensions/chrome-cdp/package.json

Added
new file mode 100644
1 +{
2 + "name": "@bugabinga/pi-ext-chrome-cdp",
3 + "private": true,
4 + "type": "module",
5 + "main": "index.ts",
6 + "license": "MIT",
7 + "description": "Drive an extension-owned Chrome with raw CDP commands from Pi.",
8 + "keywords": [
9 + "pi",
10 + "pi-extension",
11 + "chrome",
12 + "cdp"
13 + ],
14 + "peerDependencies": {
15 + "@earendil-works/pi-coding-agent": "*",
16 + "@earendil-works/pi-tui": "*",
17 + "typebox": "*"
18 + },
19 + "devDependencies": {
20 + "@marcfargas/pi-test-harness": "^0.6.1",
21 + "vitest": "^4.1.9"
22 + },
23 + "pi": {
24 + "extensions": [
25 + "index.ts"
26 + ]
27 + }

extensions/chrome-cdp/vitest.e2e.config.ts

Added
new file mode 100644
1 +import { defineConfig } from "vitest/config";
3 +export default defineConfig({
4 + test: {
5 + include: ["__e2e__/*.test.ts"],
6 + fileParallelism: false,
7 + testTimeout: 180_000,
8 + },
9 +});

package-lock.json

Modified
67 67 "@earendil-works/pi-coding-agent": "*"
70 + "extensions/chrome-cdp": {
71 + "name": "@bugabinga/pi-ext-chrome-cdp",
72 + "license": "MIT",
73 + "devDependencies": {
74 + "@marcfargas/pi-test-harness": "^0.6.1",
75 + "vitest": "^4.1.9"
76 + },
77 + "peerDependencies": {
78 + "@earendil-works/pi-coding-agent": "*",
79 + "@earendil-works/pi-tui": "*",
80 + "typebox": "*"
81 + }
82 + },
70 83 "extensions/context-size": {
71 84 "name": "@bugabinga/pi-ext-context-size",
72 85 "license": "MIT",
1312 1325 "resolved": "extensions/bak",
1313 1326 "link": true
1328 + "node_modules/@bugabinga/pi-ext-chrome-cdp": {
1329 + "resolved": "extensions/chrome-cdp",
1330 + "link": true
1331 + },
1315 1332 "node_modules/@bugabinga/pi-ext-context-size": {
1316 1333 "resolved": "extensions/context-size",
1317 1334 "link": true