@parcha/pi-browser 0.0.0-stage → 0.1.0-beta.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +33 -0
  4. package/README.md +348 -2
  5. package/dist/coding-agent-local.d.ts +16 -0
  6. package/dist/coding-agent-local.js +138 -0
  7. package/dist/coding-agent.d.ts +79 -0
  8. package/dist/coding-agent.js +448 -0
  9. package/dist/core/contract.d.ts +26 -0
  10. package/dist/core/contract.js +154 -0
  11. package/dist/core/custody.d.ts +117 -0
  12. package/dist/core/custody.js +126 -0
  13. package/dist/core/decisions.d.ts +43 -0
  14. package/dist/core/decisions.js +4 -0
  15. package/dist/core/downloads.d.ts +35 -0
  16. package/dist/core/downloads.js +131 -0
  17. package/dist/core/effects.d.ts +63 -0
  18. package/dist/core/effects.js +256 -0
  19. package/dist/core/evidence.d.ts +43 -0
  20. package/dist/core/evidence.js +6 -0
  21. package/dist/core/failures.d.ts +36 -0
  22. package/dist/core/failures.js +68 -0
  23. package/dist/core/find.d.ts +32 -0
  24. package/dist/core/find.js +179 -0
  25. package/dist/core/guard.d.ts +6 -0
  26. package/dist/core/guard.js +25 -0
  27. package/dist/core/host.d.ts +328 -0
  28. package/dist/core/host.js +2 -0
  29. package/dist/core/images.d.ts +37 -0
  30. package/dist/core/images.js +60 -0
  31. package/dist/core/lease.d.ts +16 -0
  32. package/dist/core/lease.js +30 -0
  33. package/dist/core/receipts.d.ts +19 -0
  34. package/dist/core/receipts.js +22 -0
  35. package/dist/core/redact.d.ts +13 -0
  36. package/dist/core/redact.js +83 -0
  37. package/dist/core/session-control.d.ts +25 -0
  38. package/dist/core/session-control.js +75 -0
  39. package/dist/core/sites.d.ts +33 -0
  40. package/dist/core/sites.js +102 -0
  41. package/dist/core/tools.d.ts +72 -0
  42. package/dist/core/tools.js +200 -0
  43. package/dist/core/uri.d.ts +11 -0
  44. package/dist/core/uri.js +37 -0
  45. package/dist/core/usage.d.ts +19 -0
  46. package/dist/core/usage.js +44 -0
  47. package/dist/core/web.d.ts +98 -0
  48. package/dist/core/web.js +327 -0
  49. package/dist/driver/extension-worker.d.ts +6 -0
  50. package/dist/driver/extension-worker.js +121 -0
  51. package/dist/driver/stagehand.d.ts +25 -0
  52. package/dist/driver/stagehand.js +91 -0
  53. package/dist/durable-result.d.ts +6 -0
  54. package/dist/durable-result.js +2 -0
  55. package/dist/durable.d.ts +79 -0
  56. package/dist/durable.js +582 -0
  57. package/dist/index.d.ts +19 -0
  58. package/dist/index.js +20 -0
  59. package/dist/providers/browserbase-net.d.ts +13 -0
  60. package/dist/providers/browserbase-net.js +96 -0
  61. package/dist/providers/browserbase.d.ts +152 -0
  62. package/dist/providers/browserbase.js +262 -0
  63. package/dist/providers/cdp-call.d.ts +6 -0
  64. package/dist/providers/cdp-call.js +25 -0
  65. package/dist/providers/cdp.d.ts +55 -0
  66. package/dist/providers/cdp.js +423 -0
  67. package/dist/providers/http.d.ts +2 -0
  68. package/dist/providers/http.js +21 -0
  69. package/dist/providers/kernel.d.ts +49 -0
  70. package/dist/providers/kernel.js +246 -0
  71. package/dist/providers/shared.d.ts +47 -0
  72. package/dist/providers/shared.js +82 -0
  73. package/dist/recorder/credential.d.ts +9 -0
  74. package/dist/recorder/credential.js +49 -0
  75. package/dist/recorder/follow.d.ts +26 -0
  76. package/dist/recorder/follow.js +138 -0
  77. package/dist/recorder/frames.d.ts +80 -0
  78. package/dist/recorder/frames.js +309 -0
  79. package/dist/recorder/index.d.ts +4 -0
  80. package/dist/recorder/index.js +7 -0
  81. package/dist/recorder/jpeg.d.ts +8 -0
  82. package/dist/recorder/jpeg.js +70 -0
  83. package/dist/recorder/track.d.ts +107 -0
  84. package/dist/recorder/track.js +259 -0
  85. package/dist/store.d.ts +56 -0
  86. package/dist/store.js +196 -0
  87. package/dist/testing/backend.d.ts +231 -0
  88. package/dist/testing/backend.js +414 -0
  89. package/dist/testing/driver.d.ts +28 -0
  90. package/dist/testing/driver.js +32 -0
  91. package/dist/testing/index.d.ts +4 -0
  92. package/dist/testing/index.js +4 -0
  93. package/dist/testing/pages.d.ts +3 -0
  94. package/dist/testing/pages.js +10 -0
  95. package/dist/testing/sentinels.d.ts +29 -0
  96. package/dist/testing/sentinels.js +38 -0
  97. package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
  98. package/dist/vendor/stagehand-facade/contract.js +155 -0
  99. package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
  100. package/dist/vendor/stagehand-facade/runtime.js +1640 -0
  101. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
  102. package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
  103. package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
  104. package/dist/vendor/stagehand-facade/tools.js +139 -0
  105. package/dist/web.d.ts +41 -0
  106. package/dist/web.js +38 -0
  107. package/package.json +123 -4
  108. package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
@@ -0,0 +1,423 @@
1
+ import { execFile, spawn } from "node:child_process";
2
+ import { readFileSync } from "node:fs";
3
+ import { mkdir, mkdtemp, open, readdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
4
+ import os from "node:os";
5
+ import path from "node:path";
6
+ import { BrowserFailureError } from "../core/custody.js";
7
+ import { cdpCall } from "./cdp-call.js";
8
+ /** Stagehand 4.1.0's DEFAULT_CHROME_FLAGS (packages/sdk-ts/src/browser/localBrowser.ts, MIT, see NOTICE). Without them
9
+ * Stagehand.create takes about 24 s on a local Chrome instead of under 100 ms. */
10
+ const CHROME_FLAGS = [
11
+ "--disable-features=Translate,OptimizationHints,MediaRouter,DialMediaRouteProvider,CalculateNativeWinOcclusion,InterestFeedContentSuggestions,CertificateTransparencyComponentUpdater,AutofillServerCommunication,PrivacySandboxSettings4,RenderDocument",
12
+ "--disable-component-extensions-with-background-pages",
13
+ "--disable-background-networking",
14
+ "--disable-component-update",
15
+ "--disable-client-side-phishing-detection",
16
+ "--disable-sync",
17
+ "--metrics-recording-only",
18
+ "--disable-default-apps",
19
+ "--mute-audio",
20
+ "--no-default-browser-check",
21
+ "--no-first-run",
22
+ "--disable-backgrounding-occluded-windows",
23
+ "--disable-renderer-backgrounding",
24
+ "--disable-background-timer-throttling",
25
+ "--disable-ipc-flooding-protection",
26
+ "--password-store=basic",
27
+ "--use-mock-keychain",
28
+ "--force-fieldtrials=*BackgroundTracing/default/",
29
+ "--disable-hang-monitor",
30
+ "--disable-prompt-on-repost",
31
+ "--disable-domain-reliability",
32
+ "--propagate-iph-for-testing",
33
+ "--enable-unsafe-extension-debugging",
34
+ "--remote-allow-origins=*",
35
+ "--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
36
+ ];
37
+ const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, extension: "loaded-locally", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
38
+ const downloadsDir = (profileRoot, tag) => path.join(profileDir(profileRoot, tag) + ".downloads");
39
+ const READY_MS = 20_000;
40
+ /** The browser is gone and directories it used are not: a profile left behind holds the session's cookies, so a release that cannot remove
41
+ * one says so, naming every one still there (`dirs`, the first as `dir`), and is asked again. `original` is the failure of the launch that
42
+ * was being undone, when there was one. */
43
+ export class ProfileNotRemovedError extends Error {
44
+ dirs;
45
+ cause;
46
+ original;
47
+ code = "profile_not_removed";
48
+ dir;
49
+ constructor(dirs, cause, original) {
50
+ super(`the browser is gone but ${dirs.length === 1 ? "its directory" : "its directories"} ${dirs.join(" and ")} could not be removed (${cause instanceof Error ? cause.message : String(cause)}); ${dirs.length === 1 ? "it" : "they"} may hold the session's cookies, so remove ${dirs.length === 1 ? "it" : "them"} by hand${original === undefined ? "" : `; the launch had also failed: ${original instanceof Error ? original.message : String(original)}`}`);
51
+ this.dirs = dirs;
52
+ this.cause = cause;
53
+ this.original = original;
54
+ this.name = "ProfileNotRemovedError";
55
+ this.dir = dirs[0];
56
+ }
57
+ }
58
+ /** What a retry can cure: a file that arrived in the directory, or a handle or lock that is let go (the codes Node's own rm retries). */
59
+ const RETRYABLE = new Set(["ENOTEMPTY", "EBUSY", "EMFILE", "ENFILE", "EPERM"]);
60
+ const REMOVAL_RETRIES = 5;
61
+ const REMOVAL_DELAY_MS = 100;
62
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
63
+ /** Removes a directory tree; what is still there afterwards is the caller's to report, never to swallow. A browser's last writes can land after its
64
+ * process is killed (its other processes are still exiting), and a directory a file arrives in while it is being removed fails with ENOTEMPTY: the
65
+ * removal is tried again, waiting a little longer each time (100, 200, ... 500 ms, about a second and a half in all). A failure a retry cannot cure
66
+ * (EACCES, say) is reported at once. (A link is unlinked, not followed.) */
67
+ async function removeTree(dir, remove) {
68
+ for (let attempt = 0;; attempt += 1) {
69
+ try {
70
+ await remove(dir, { recursive: true, force: true });
71
+ return null;
72
+ }
73
+ catch (failure) {
74
+ const error = failure instanceof Error ? failure : new Error(String(failure));
75
+ if (attempt >= REMOVAL_RETRIES || !RETRYABLE.has(error.code ?? ""))
76
+ return { dir, error };
77
+ await sleep(REMOVAL_DELAY_MS * (attempt + 1));
78
+ }
79
+ }
80
+ }
81
+ /** Every directory is tried, whatever the others did; what is left is reported together. */
82
+ async function removeAll(dirs, remove) {
83
+ const left = [];
84
+ for (const dir of dirs) {
85
+ const stuck = await removeTree(dir, remove);
86
+ if (stuck)
87
+ left.push(stuck);
88
+ }
89
+ return left.length > 0 ? { dirs: left.map((l) => l.dir), error: left[0].error } : null;
90
+ }
91
+ /** The extension inside the browser dials the URL it is given, so it must be a `ws://` debugger URL. */
92
+ async function debuggerUrl(endpoint, signal) {
93
+ if (/^wss?:/i.test(endpoint))
94
+ return endpoint;
95
+ const found = await (await fetch(new URL("/json/version", endpoint), signal ? { signal } : {})).json();
96
+ if (!found.webSocketDebuggerUrl)
97
+ throw new Error("the endpoint did not report a debugger URL");
98
+ return found.webSocketDebuggerUrl;
99
+ }
100
+ /** Only the Chrome running on that profile writes `DevToolsActivePort`, so it names that Chrome and no other browser on
101
+ * a port. */
102
+ async function ownDebugger(profile) {
103
+ const [port, browser] = (await readFile(path.join(profile, "DevToolsActivePort"), "utf8").catch(() => "")).split("\n");
104
+ return /^\d+$/.test(port ?? "") && browser?.startsWith("/devtools/browser/") ? { port: Number(port), path: browser.trim() } : null;
105
+ }
106
+ const answeringPath = async (port) => debuggerUrl(`http://127.0.0.1:${port}`).then((url) => new URL(url).pathname, () => null);
107
+ /** A port that takes the probe and does not answer within this may still be a live browser's. */
108
+ const PROBE_MS = 2_000;
109
+ /** A release that does not own the lease's browser left its profile: the port the profile names took the probe and did
110
+ * not answer, so a live browser may still run on it. Asked again once that port answers or closes, the release decides. */
111
+ export class ProfileOwnershipUnclearError extends Error {
112
+ dir;
113
+ port;
114
+ code = "profile_ownership_unclear";
115
+ constructor(dir, port) {
116
+ super(`the profile ${dir} was left: port ${port}, which it names, took the browser probe and did not answer within ${PROBE_MS} ms, so a live browser may still run on it; release again once that port answers or closes`);
117
+ this.dir = dir;
118
+ this.port = port;
119
+ this.name = "ProfileOwnershipUnclearError";
120
+ }
121
+ }
122
+ /** `local:<pid>:<port>:<tag>`. The pid is signalled only while the browser on that port reports it as its own, and the
123
+ * profile removed is the id's own tag's, so a ref pairing one lease's id with another's tag touches nothing. */
124
+ const parse = (id) => { const m = /^local:(\d+):(\d+):([A-Za-z0-9_.-]+)$/.exec(id); return m ? { pid: Number(m[1]), port: Number(m[2]), tag: m[3] } : null; };
125
+ /** A lease tag names a directory under the profile root, so it is one path segment: no separators, never `.` or `..`. */
126
+ const SAFE_TAG = /^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}$/;
127
+ const profileDir = (root, tag) => {
128
+ if (!SAFE_TAG.test(tag))
129
+ throw new Error("a cdp lease tag is one path segment of [A-Za-z0-9_.-]");
130
+ return path.join(root, tag);
131
+ };
132
+ /** Chrome writes temp entries under its TMPDIR (its singleton socket directory, its url_fetcher entries) and a Chrome that is killed removes none of
133
+ * them, so each lease's Chrome gets a TMPDIR of its own, made under the host's, named in the profile (`.pib-tmpdir`) and removed with the lease: what
134
+ * Chrome writes there never lands in the host's TMPDIR. The directory carries an owner file naming the lease's tag, and only a directory that names the
135
+ * tag asked for is ever removed, so a profile that names another path (a copied or hand-written one) removes nothing. Chrome aborts when its socket path
136
+ * passes 107 bytes, so a host TMPDIR too long to leave room for the private directory's name and the socket's is left as it is (Chrome inherits it). Not
137
+ * made on Windows, where Chrome's temp directory is not TMPDIR. */
138
+ const TMP_MARKER = ".pib-tmpdir";
139
+ const TMP_OWNER = ".pib-owner";
140
+ const TMP_NAME = /^pib-[A-Za-z0-9]{6}$/;
141
+ const SOCKET_PATH_MAX = 107;
142
+ const SOCKET_PATH_TAIL = "/.org.chromium.Chromium.XXXXXX/SingletonSocket".length;
143
+ async function makePrivateTmp(tag, profile, remove) {
144
+ if (process.platform === "win32")
145
+ return null;
146
+ const base = os.tmpdir();
147
+ if (Buffer.byteLength(path.join(base, "pib-XXXXXX")) + SOCKET_PATH_TAIL > SOCKET_PATH_MAX)
148
+ return null;
149
+ const dir = await mkdtemp(path.join(base, "pib-"));
150
+ try {
151
+ await writeFile(path.join(dir, TMP_OWNER), tag);
152
+ await writeFile(path.join(profile, TMP_MARKER), dir);
153
+ }
154
+ catch (error) {
155
+ // The directory is not recorded anywhere yet, so a setup that fails here removes it, and names it if it cannot.
156
+ const left = await removeTree(dir, remove);
157
+ throw left ? new ProfileNotRemovedError([dir], left.error, error) : error;
158
+ }
159
+ return dir;
160
+ }
161
+ /** The private directory the profile names, when it is one this provider made for this tag. */
162
+ async function ownedTmp(profile, tag) {
163
+ const named = (await readFile(path.join(profile, TMP_MARKER), "utf8").catch(() => "")).trim();
164
+ if (!named || !path.isAbsolute(named) || !TMP_NAME.test(path.basename(named)))
165
+ return null;
166
+ return (await readFile(path.join(named, TMP_OWNER), "utf8").catch(() => null)) === tag ? named : null;
167
+ }
168
+ /** Signal 0 only asks; EPERM means the process exists under another user. */
169
+ const alive = (pid) => { try {
170
+ process.kill(pid, 0);
171
+ return true;
172
+ }
173
+ catch (error) {
174
+ return error.code === "EPERM";
175
+ } };
176
+ /** The browser entry of `SystemInfo.getProcessInfo`, which every OS gives (a /proc command line exists only on Linux). */
177
+ async function browserPid(port, timeoutMs = 2_000) {
178
+ try {
179
+ const url = await Promise.race([debuggerUrl(`http://127.0.0.1:${port}`), sleep(timeoutMs).then(() => { throw new Error("no answer"); })]);
180
+ const session = await cdpCall(url, "SystemInfo.getProcessInfo", {}, timeoutMs);
181
+ session.close();
182
+ const browser = session.result?.processInfo?.find((p) => p.type === "browser");
183
+ return typeof browser?.id === "number" ? browser.id : null;
184
+ }
185
+ catch {
186
+ return null;
187
+ }
188
+ }
189
+ /** Chrome's singleton socket directory under TMPDIR outlives every Chrome exit, a clean one included; the profile's link
190
+ * names it. */
191
+ async function singletonDir(profile) {
192
+ const socket = await readlink(path.join(profile, "SingletonSocket")).catch(() => null);
193
+ const dir = socket && path.basename(socket) === "SingletonSocket" ? path.dirname(socket) : null;
194
+ return dir && /^\.?(org\.chromium\.Chromium|com\.google\.Chrome)\.[A-Za-z0-9]{6}$/.test(path.basename(dir)) ? dir : null;
195
+ }
196
+ /** Whether `pid` leads its own process group (Chrome is started detached, so it does); null where there is no /proc to ask. */
197
+ function leadsOwnGroup(pid) {
198
+ if (process.platform !== "linux")
199
+ return null;
200
+ try {
201
+ const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
202
+ // pid (comm) state ppid pgrp ...: the name may hold spaces and brackets, so the fields are counted from its last ")".
203
+ return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[2]) === pid;
204
+ }
205
+ catch {
206
+ return false;
207
+ }
208
+ }
209
+ /** A pid reaches here from a ref's id, which a restart reads back from a record: `kill(-1)` signals every process the user can,
210
+ * `kill(0)` this process's own group, so neither a pid below 2 nor our own is ever signalled, and a negative pid (a whole group)
211
+ * only for a process that leads one. */
212
+ export async function killTree(pid, io = {}) {
213
+ if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid)
214
+ return;
215
+ if (process.platform === "win32")
216
+ return void (await new Promise((resolve) => execFile("taskkill", ["/pid", String(pid), "/T", "/F"], () => resolve())));
217
+ const kill = io.kill ?? ((target, signal) => process.kill(target, signal));
218
+ if ((io.leadsGroup ?? leadsOwnGroup)(pid) !== false) {
219
+ try {
220
+ return kill(-pid, "SIGKILL");
221
+ }
222
+ catch { /* no such group: the process alone */ }
223
+ }
224
+ try {
225
+ kill(pid, "SIGKILL");
226
+ }
227
+ catch { /* already gone */ }
228
+ }
229
+ /** `internals` is for tests: the removal a release uses. */
230
+ export function cdpProvider(options, internals = {}) {
231
+ const remove = internals.remove ?? ((dir, opts) => rm(dir, opts));
232
+ const downloads = "chrome" in options ? localDownloads(options.chrome.profileRoot) : undefined;
233
+ // So a release can wait for the exit it caused: an unreaped child still answers `kill 0`.
234
+ const children = new Map();
235
+ /** Directories besides the profile (Chrome's socket directory, the lease's private TMPDIR) that a release could not remove: the profile that named
236
+ * them may go first, so the next release of the lease in this process is told them here. (A restarted process has the report's text.) */
237
+ const extrasLeft = new Map();
238
+ /** The private TMPDIR of each lease this provider started, by tag: the profile's marker is the only record a restarted process has, and a profile
239
+ * that something else removed first takes it along. */
240
+ const privateTmps = new Map();
241
+ /** A spawned Chrome whose handle we hold is ours (a handle cannot name a recycled pid); after a restart, only while
242
+ * the browser on the recorded port reports that pid. */
243
+ const isOurs = async ({ pid, port }) => {
244
+ const child = children.get(pid);
245
+ if (child)
246
+ return child.exitCode === null && child.signalCode === null;
247
+ return alive(pid) && (await browserPid(port)) === pid;
248
+ };
249
+ return {
250
+ name: "cdp",
251
+ caps: CAPS,
252
+ ...(downloads ? { downloads } : {}),
253
+ async create(spec) {
254
+ if ("endpoint" in options)
255
+ return { id: `endpoint:${spec.tag}`, tag: spec.tag };
256
+ const { executablePath, profileRoot, headless = true, args = [] } = options.chrome;
257
+ const sandbox = options.chrome.sandbox ?? process.env.PI_BROWSER_NO_SANDBOX !== "1";
258
+ const dir = profileDir(profileRoot, spec.tag);
259
+ await mkdir(path.join(dir, "Default"), { recursive: true });
260
+ await mkdir(downloadsDir(profileRoot, spec.tag), { recursive: true });
261
+ await writeFile(path.join(dir, "Default", "Preferences"), JSON.stringify({ download: { default_directory: downloadsDir(profileRoot, spec.tag), prompt_for_download: false }, savefile: { default_directory: downloadsDir(profileRoot, spec.tag) } }));
262
+ // A file left by an earlier Chrome on this profile names a browser that is not this one.
263
+ await rm(path.join(dir, "DevToolsActivePort"), { force: true });
264
+ const tmp = await makePrivateTmp(spec.tag, dir, remove);
265
+ if (tmp)
266
+ privateTmps.set(spec.tag, tmp);
267
+ const child = spawn(executablePath, [
268
+ ...CHROME_FLAGS, ...(sandbox ? [] : ["--no-sandbox"]), ...(headless ? ["--headless=new"] : []), "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${dir}`,
269
+ `--window-size=${spec.viewport.width},${spec.viewport.height}`, ...args, "about:blank",
270
+ ], { stdio: "ignore", detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
271
+ // A Chrome that cannot start emits `error`, which unhandled would end the host: it rejects create instead.
272
+ let failed = null;
273
+ child.once("error", (error) => { failed = error; });
274
+ child.once("exit", (code, signal) => {
275
+ // A Chrome that cannot start its sandbox aborts (SIGABRT) before it opens a port: the signal is the fact, never
276
+ // Chrome's words.
277
+ failed ??= sandbox && signal === "SIGABRT"
278
+ ? new BrowserFailureError({ ok: false, code: "browser_unavailable", retryable: false, effect: "none", message: `Chrome exited before it opened its debugging port (SIGABRT); on a system that cannot start Chrome's sandbox (root, a container, restricted user namespaces) start it with sandbox: false or PI_BROWSER_NO_SANDBOX=1` })
279
+ : new Error(`Chrome exited before it opened its debugging port (${signal ?? code})`);
280
+ });
281
+ if (child.pid === undefined) {
282
+ await sleep(0);
283
+ const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), ...(tmp ? [tmp] : [])], remove);
284
+ privateTmps.delete(spec.tag);
285
+ const why = failed ?? new Error("Chrome could not be started");
286
+ throw left ? new ProfileNotRemovedError(left.dirs, left.error, why) : why;
287
+ }
288
+ child.unref();
289
+ children.set(child.pid, child);
290
+ // The lease is that Chrome only once the browser answering on the port is the one its profile file names, so a
291
+ // port another browser holds is never taken for it.
292
+ try {
293
+ for (const deadline = Date.now() + READY_MS;; await sleep(100)) {
294
+ if (failed)
295
+ throw failed;
296
+ const own = await ownDebugger(dir);
297
+ if (own && (await answeringPath(own.port)) === own.path)
298
+ return { id: `local:${child.pid}:${own.port}:${spec.tag}`, tag: spec.tag };
299
+ if (Date.now() > deadline)
300
+ throw new Error("Chrome did not open its debugging port");
301
+ }
302
+ }
303
+ catch (error) {
304
+ const kept = await this.release({ id: `local:${child.pid}:0:${spec.tag}`, tag: spec.tag }).then(() => null, (failure) => failure);
305
+ const left = await removeAll([downloadsDir(profileRoot, spec.tag)], remove);
306
+ if (kept && !(kept instanceof ProfileNotRemovedError))
307
+ throw kept;
308
+ const dirs = [...(kept instanceof ProfileNotRemovedError ? kept.dirs : []), ...(left?.dirs ?? [])];
309
+ throw dirs.length > 0 ? new ProfileNotRemovedError(dirs, kept instanceof ProfileNotRemovedError ? kept.cause : left.error, error) : error;
310
+ }
311
+ },
312
+ async findByTag() { return []; },
313
+ async status(ref) {
314
+ const local = parse(ref.id);
315
+ // A local-shaped id this provider cannot read names no process it can vouch for: gone, never "running" unchecked.
316
+ if (!local)
317
+ return ref.id.startsWith("local:") ? "gone" : "running";
318
+ return (await isOurs(local)) ? "running" : "gone";
319
+ },
320
+ async attach(ref) {
321
+ if ("endpoint" in options)
322
+ return { sdkCdpUrl: await debuggerUrl(options.endpoint), ...(options.extensionId ? { extensionId: options.extensionId } : {}) };
323
+ const local = parse(ref.id);
324
+ if (!local)
325
+ throw new Error("not a cdp lease");
326
+ const own = await ownDebugger(profileDir(options.chrome.profileRoot, local.tag));
327
+ if (!own || own.port !== local.port)
328
+ throw new Error("this lease's profile records a different browser than the one its id names");
329
+ const url = await debuggerUrl(`http://127.0.0.1:${local.port}`);
330
+ if (new URL(url).pathname !== own.path)
331
+ throw new Error(`the browser on port ${local.port} is not the browser this lease's profile records`);
332
+ return { sdkCdpUrl: url };
333
+ },
334
+ async release(ref) {
335
+ const local = parse(ref.id);
336
+ if (!local || local.tag !== ref.tag)
337
+ return;
338
+ const ours = await isOurs(local);
339
+ // A profile that a live browser this ref does not name still runs on is that browser's: nothing is removed. A port
340
+ // that holds the probe past PROBE_MS cannot be ruled out, so the profile stays and the release says so.
341
+ if (!ours && !("endpoint" in options) && SAFE_TAG.test(local.tag)) {
342
+ const dir = profileDir(options.chrome.profileRoot, local.tag);
343
+ const own = await ownDebugger(dir);
344
+ if (own) {
345
+ const answer = await debuggerUrl(`http://127.0.0.1:${own.port}`, AbortSignal.timeout(PROBE_MS))
346
+ .then((url) => new URL(url).pathname, (error) => (error instanceof Error && error.name === "TimeoutError" ? undefined : null));
347
+ if (answer === own.path)
348
+ return;
349
+ if (answer === undefined)
350
+ throw new ProfileOwnershipUnclearError(dir, own.port);
351
+ }
352
+ }
353
+ if (ours) {
354
+ await killTree(local.pid);
355
+ const child = children.get(local.pid);
356
+ children.delete(local.pid);
357
+ // The child is unref'd, so a bare wait on its exit could let a process whose last await is this release end
358
+ // early (exit 13): a timer keeps the loop alive. Without a handle the pid is polled until gone.
359
+ if (child && child.exitCode === null && child.signalCode === null)
360
+ await new Promise((resolve) => { const timer = setTimeout(resolve, 5_000); child.once("exit", () => { clearTimeout(timer); resolve(); }); });
361
+ else
362
+ for (const deadline = Date.now() + 5_000; alive(local.pid) && Date.now() < deadline;)
363
+ await sleep(50);
364
+ }
365
+ // The profile goes even after a crash; a tag that is not one path segment names nothing this provider made, so
366
+ // nothing is removed.
367
+ if (!("endpoint" in options) && SAFE_TAG.test(local.tag)) {
368
+ const dir = profileDir(options.chrome.profileRoot, local.tag);
369
+ const socketDir = await singletonDir(dir);
370
+ const tmp = privateTmps.get(local.tag) ?? await ownedTmp(dir, local.tag);
371
+ // All are always tried, the profile first named: the profile's link and marker are the only places the other directories' names are read, so
372
+ // they are reported here with the profile's, not left for a later release to miss.
373
+ const extras = [...new Set([...(socketDir ? [socketDir] : []), ...(tmp ? [tmp] : []), ...(extrasLeft.get(local.tag) ?? [])])];
374
+ const left = await removeAll([dir, ...extras], remove);
375
+ const stuck = extras.filter((extra) => left?.dirs.includes(extra));
376
+ if (stuck.length > 0)
377
+ extrasLeft.set(local.tag, stuck);
378
+ else
379
+ extrasLeft.delete(local.tag);
380
+ if (!tmp || !stuck.includes(tmp))
381
+ privateTmps.delete(local.tag);
382
+ if (left)
383
+ throw new ProfileNotRemovedError(left.dirs, left.error);
384
+ }
385
+ },
386
+ };
387
+ }
388
+ /** Finished files only: Chrome writes `.crdownload` while it works. */
389
+ function localDownloads(profileRoot) {
390
+ const inside = (ref, name) => { if (name !== path.basename(name) || !name)
391
+ throw new Error("not a download name"); return path.join(downloadsDir(profileRoot, ref.tag), name); };
392
+ return {
393
+ async list(ref) {
394
+ const dir = downloadsDir(profileRoot, ref.tag);
395
+ const rows = [];
396
+ for (const name of await readdir(dir).catch(() => [])) {
397
+ if (name.endsWith(".crdownload") || name.startsWith("."))
398
+ continue;
399
+ const info = await stat(path.join(dir, name)).catch(() => null);
400
+ if (info?.isFile())
401
+ rows.push({ name, sizeBytes: info.size, modifiedAt: info.mtime.toISOString() });
402
+ }
403
+ return rows.sort((a, b) => a.name.localeCompare(b.name));
404
+ },
405
+ async read(ref, name, maxBytes) {
406
+ const file = await open(inside(ref, name), "r");
407
+ return (async function* () {
408
+ try {
409
+ let total = 0;
410
+ for await (const chunk of file.createReadStream()) {
411
+ total += chunk.byteLength;
412
+ if (total > maxBytes)
413
+ throw new Error(`larger than the ${maxBytes}-byte limit`);
414
+ yield chunk;
415
+ }
416
+ }
417
+ finally {
418
+ await file.close().catch(() => undefined);
419
+ }
420
+ })();
421
+ },
422
+ };
423
+ }
@@ -0,0 +1,2 @@
1
+ export declare function directFetch(): Promise<((input: any, init?: any) => Promise<any>) | undefined>;
2
+ export declare function closeDirectFetch(): Promise<void>;
@@ -0,0 +1,21 @@
1
+ import nodeModule from "node:module";
2
+ const require = nodeModule.createRequire(import.meta.url);
3
+ let undiciModule;
4
+ /** Loaded on first use, so a process that never reaches a provider never loads undici. */
5
+ const undiciDoor = () => (undiciModule ??= require("undici"));
6
+ let directAgent;
7
+ export async function directFetch() {
8
+ try {
9
+ const undici = undiciDoor();
10
+ // Userland undici refuses a request body it must stream (the extension upload's multipart file) without `duplex`.
11
+ return (input, init = {}) => undici.fetch(input, { ...init, dispatcher: (directAgent ??= new undici.Agent()), ...(init.body ? { duplex: "half" } : {}) });
12
+ }
13
+ catch {
14
+ return undefined;
15
+ }
16
+ }
17
+ export async function closeDirectFetch() {
18
+ const agent = directAgent;
19
+ directAgent = undefined;
20
+ await agent?.close();
21
+ }
@@ -0,0 +1,49 @@
1
+ import type { BrowserProvider, SessionSpec } from "../core/host.js";
2
+ export declare const KERNEL_BASE_URL = "https://api.onkernel.com";
3
+ export declare const KERNEL_IDLE_MIN_S = 10;
4
+ export declare const KERNEL_IDLE_MAX_S = 259200;
5
+ type HttpFetch = (input: string, init: {
6
+ method: string;
7
+ headers: Record<string, string>;
8
+ body?: Uint8Array | string;
9
+ signal?: AbortSignal;
10
+ }) => Promise<Response>;
11
+ export type KernelOptions = {
12
+ /** KERNEL_API_KEY and KERNEL_BASE_URL (default https://api.onkernel.com). Default: process.env. */
13
+ env?: NodeJS.ProcessEnv;
14
+ /** Kernel's stealth mode, which also turns on its CAPTCHA solver and its stealth proxy. Default false. */
15
+ stealth?: boolean;
16
+ headless?: boolean;
17
+ /** Default: one stored with the same bytes, else uploaded once per process and account. */
18
+ extension?: () => Promise<KernelExtensionRef>;
19
+ confirm?: {
20
+ polls: number;
21
+ intervalMs: number;
22
+ };
23
+ sleep?: (ms: number) => Promise<void>;
24
+ /** Default: a direct undici Agent that never uses HTTP(S)_PROXY; a host behind a proxy passes its own. */
25
+ fetch?: HttpFetch;
26
+ };
27
+ export type KernelProvider = BrowserProvider & {
28
+ readonly name: "kernel";
29
+ };
30
+ export type KernelExtensionRef = {
31
+ id: string;
32
+ } | {
33
+ name: string;
34
+ };
35
+ /** The call and the HTTP status, plus Kernel's error code when it is a plain identifier. Kernel's message is never
36
+ * copied: an echo of the request could carry the key or a URL. */
37
+ export declare class KernelError extends Error {
38
+ readonly status: number | undefined;
39
+ constructor(call: string, status: number | undefined, code?: string, options?: {
40
+ cause?: unknown;
41
+ });
42
+ }
43
+ export declare function kernelCreateBody(spec: SessionSpec, options?: {
44
+ stealth?: boolean;
45
+ headless?: boolean;
46
+ extension?: KernelExtensionRef;
47
+ }): Record<string, unknown>;
48
+ export declare function kernelProvider(options?: KernelOptions): KernelProvider;
49
+ export {};