@parcha/pi-browser 0.1.0-beta.13 → 0.1.0-beta.15

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 (43) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +29 -8
  3. package/dist/coding-agent.d.ts +7 -0
  4. package/dist/coding-agent.js +33 -16
  5. package/dist/core/contract.js +1 -1
  6. package/dist/core/custody.d.ts +16 -3
  7. package/dist/core/custody.js +28 -11
  8. package/dist/core/downloads.d.ts +1 -0
  9. package/dist/core/downloads.js +2 -2
  10. package/dist/core/failures.d.ts +8 -0
  11. package/dist/core/failures.js +18 -9
  12. package/dist/core/guard.d.ts +1 -1
  13. package/dist/core/guard.js +2 -1
  14. package/dist/core/host.d.ts +60 -2
  15. package/dist/core/sites.js +2 -1
  16. package/dist/core/tools.d.ts +37 -2
  17. package/dist/core/tools.js +84 -54
  18. package/dist/core/usage.d.ts +1 -20
  19. package/dist/driver/extension-worker.d.ts +7 -0
  20. package/dist/driver/extension-worker.js +148 -0
  21. package/dist/driver/new-document.d.ts +26 -0
  22. package/dist/driver/new-document.js +40 -0
  23. package/dist/driver/stagehand.js +9 -61
  24. package/dist/durable.d.ts +14 -3
  25. package/dist/durable.js +507 -369
  26. package/dist/index.d.ts +1 -0
  27. package/dist/index.js +1 -0
  28. package/dist/providers/browserbase.d.ts +17 -0
  29. package/dist/providers/browserbase.js +49 -8
  30. package/dist/providers/cdp.d.ts +14 -0
  31. package/dist/providers/cdp.js +270 -66
  32. package/dist/providers/kernel.js +40 -6
  33. package/dist/providers/profiles.d.ts +19 -0
  34. package/dist/providers/profiles.js +124 -0
  35. package/dist/providers/shared.d.ts +1 -1
  36. package/dist/recorder/index.d.ts +1 -0
  37. package/dist/recorder/index.js +1 -0
  38. package/dist/recorder/jpeg.d.ts +3 -0
  39. package/dist/recorder/jpeg.js +36 -0
  40. package/dist/recorder/track.d.ts +107 -0
  41. package/dist/recorder/track.js +280 -0
  42. package/dist/testing/backend.js +2 -2
  43. package/package.json +3 -3
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from "./core/contract.js";
2
+ export { BrowserFailureError, type AttachedSession, type BrowserDriver, type CustodyPort, type DriverFactory, type DriverOptions, type Overrides, type ToolOutput } from "./core/custody.js";
2
3
  export * from "./core/decisions.js";
3
4
  export * from "./core/downloads.js";
4
5
  export * from "./core/effects.js";
package/dist/index.js CHANGED
@@ -1,5 +1,6 @@
1
1
  // The host-neutral core: it imports no pi package and no host, only Node's builtins and the package's own dependencies.
2
2
  export * from "./core/contract.js";
3
+ export { BrowserFailureError } from "./core/custody.js";
3
4
  export * from "./core/decisions.js";
4
5
  export * from "./core/downloads.js";
5
6
  export * from "./core/effects.js";
@@ -1,6 +1,8 @@
1
1
  import type { BrowserProvider, Geo, PriceTable, SessionSpec } from "../core/host.js";
2
2
  import { type CdpSession } from "./cdp-call.js";
3
+ import { type ProfileStore } from "./profiles.js";
3
4
  export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
5
+ export { fileProfileStore, type ProfileStore } from "./profiles.js";
4
6
  export declare const SEARCH_QUERY_MAX = 200;
5
7
  export declare const SEARCH_RESULTS_MAX = 25;
6
8
  export type BrowserbaseSdk = {
@@ -53,6 +55,13 @@ export type BrowserbaseSdk = {
53
55
  id: string;
54
56
  }>;
55
57
  };
58
+ contexts: {
59
+ create(body: {
60
+ projectId?: string;
61
+ }, options?: RequestOptions): Promise<{
62
+ id: string;
63
+ }>;
64
+ };
56
65
  fetchAPI: {
57
66
  create(body: {
58
67
  url: string;
@@ -130,6 +139,10 @@ export type BrowserbaseOptions = {
130
139
  intervalMs: number;
131
140
  };
132
141
  sleep?: (ms: number) => Promise<void>;
142
+ /** Where profile names find their Browserbase contexts. Default: a file under the user's config directory. */
143
+ profiles?: ProfileStore;
144
+ /** How long a release that saved a profile waits for Browserbase to write the context back. */
145
+ profileSettleMs?: number;
133
146
  };
134
147
  /** `Browser.setDownloadBehavior` lasts only as long as the socket that sent it, so the socket stays open until
135
148
  * `close()`. */
@@ -148,5 +161,9 @@ export declare function proxiesField(proxies: SessionSpec["proxies"]): boolean |
148
161
  export declare function sessionCreateBody(spec: SessionSpec, extra?: {
149
162
  extensionId?: string;
150
163
  projectId?: string;
164
+ context?: {
165
+ id: string;
166
+ persist: boolean;
167
+ };
151
168
  }): BrowserbaseSessionBody;
152
169
  export declare function browserbaseProvider(options?: BrowserbaseOptions): BrowserbaseProvider;
@@ -5,14 +5,18 @@ import { fetchUsage, resolvePrices, searchUsage } from "../core/usage.js";
5
5
  import { cdpCall } from "./cdp-call.js";
6
6
  import { applyBrowserbaseNoProxy, bindConnectDial, installWebSocketWrapper, rewriteConnectUrl, unbindConnectDial } from "./browserbase-net.js";
7
7
  import { directFetch } from "./http.js";
8
+ import { claimWriter, fileProfileStore, freeWriter, isWriter, noteWriter } from "./profiles.js";
8
9
  import { accountKey, assertTag, browserbaseHoldings, defaultSleep, DEFAULT_CONFIRM, extensionArchive, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
9
10
  export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
11
+ export { fileProfileStore } from "./profiles.js";
10
12
  export const SEARCH_QUERY_MAX = 200;
11
13
  export const SEARCH_RESULTS_MAX = 25;
12
14
  /** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
13
15
  export const setDownloadBehavior = (url, options = {}) => cdpCall(url, "Browser.setDownloadBehavior", { behavior: "allow", downloadPath: options.downloadPath ?? "downloads", eventsEnabled: true }, options.timeoutMs);
14
- const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, extension: "uploaded-per-launch" };
16
+ const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, profiles: true, extension: "uploaded-per-launch", settings: { proxies: true, verified: true, geolocation: true, region: true, context: true } };
15
17
  const notFound = (e) => e?.status === 404;
18
+ /** One signal for whichever of these there is (a store may call `make` without its limit). */
19
+ const stopWhen = (...signals) => { const some = signals.filter((s) => s !== undefined); return some.length > 1 ? AbortSignal.any(some) : some[0]; };
16
20
  /** ISO alpha-2 country, US state abbreviation, upper-case city; no two-letter country, no geolocation. */
17
21
  export function browserbaseGeolocation(raw) {
18
22
  const country = nonEmpty(raw?.country).toUpperCase();
@@ -38,7 +42,7 @@ export function sessionCreateBody(spec, extra = {}) {
38
42
  solveCaptchas: spec.captcha,
39
43
  viewport: spec.viewport,
40
44
  ...(spec.verified ? { verified: true } : {}),
41
- ...(spec.contextId ? { context: { id: spec.contextId, persist: true } } : {}),
45
+ ...(extra.context ? { context: extra.context } : spec.contextId ? { context: { id: spec.contextId, persist: true } } : {}),
42
46
  ...(spec.navigation?.allow?.length ? { allowedDomains: spec.navigation.allow } : {}),
43
47
  };
44
48
  const userMetadata = Object.fromEntries(Object.entries(spec.metadata).map(([k, v]) => [k, tagValue(v)]));
@@ -69,6 +73,7 @@ export function browserbaseProvider(options = {}) {
69
73
  const sleep = options.sleep ?? defaultSleep;
70
74
  const confirm = options.confirm ?? DEFAULT_CONFIRM;
71
75
  const prices = resolvePrices(options.prices);
76
+ const profiles = options.profiles ?? fileProfileStore();
72
77
  let sdk = null;
73
78
  const client = () => (sdk ??= options.client ? Promise.resolve(options.client) : (async () => {
74
79
  applyBrowserbaseNoProxy(env);
@@ -80,6 +85,7 @@ export function browserbaseProvider(options = {}) {
80
85
  const extension = () => options.extensionId
81
86
  ? options.extensionId()
82
87
  : uploadOnce(uploads, account, async () => (await (await client()).extensions.create({ file: createReadStream(extensionArchive()) }, { maxRetries: 0 })).id);
88
+ const contextFor = (name, projectId, signal) => profiles.resolve(held(`profile:${name}`), async (limit) => (await (await client()).contexts.create({ ...(projectId && !baseUrl && !connectBase ? { projectId } : {}) }, { maxRetries: 0, signal: stopWhen(signal, limit) })).id);
83
89
  const rows = async (sessionId) => {
84
90
  const all = [];
85
91
  for (let offset = 0;;) {
@@ -91,6 +97,23 @@ export function browserbaseProvider(options = {}) {
91
97
  return all;
92
98
  }
93
99
  };
100
+ const settling = new Set();
101
+ const running = (ref) => async (signal) => { if (settling.has(ref.tag))
102
+ return true; const now = await status(ref, signal); return now === "running" || now === "pending"; };
103
+ /** A saving session's context is written back after it ends, and the next session must not read it before then. */
104
+ const finished = async (ref) => {
105
+ forget(held(ref.id));
106
+ if (isWriter(ref.tag)) {
107
+ settling.add(ref.tag);
108
+ try {
109
+ await sleep(options.profileSettleMs ?? 5_000);
110
+ }
111
+ finally {
112
+ settling.delete(ref.tag);
113
+ }
114
+ }
115
+ freeWriter(ref.tag);
116
+ };
94
117
  const status = async (ref, signal) => {
95
118
  try {
96
119
  const found = await (await client()).sessions.retrieve(ref.id, { signal, timeout: 5_000 });
@@ -107,12 +130,24 @@ export function browserbaseProvider(options = {}) {
107
130
  caps: CAPS,
108
131
  async create(spec, signal) {
109
132
  const projectId = nonEmpty(env.BROWSERBASE_PROJECT_ID);
110
- // Behind the credential proxy the project is inferred from the injected key and must never be named; a direct key
111
- // must name it.
112
- const body = sessionCreateBody(spec, { extensionId: await extension(), ...(projectId && !baseUrl && !connectBase ? { projectId } : {}) });
113
- // At most once: an SDK retry of a create the server already served would open a second paid browser.
133
+ if (spec.profile?.save)
134
+ await claimWriter(held(`profile:${spec.profile.name}`), spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
135
+ let body;
136
+ try {
137
+ const context = spec.profile ? { id: await contextFor(spec.profile.name, projectId, signal), persist: spec.profile.save } : undefined;
138
+ // Behind the credential proxy the project is inferred from the injected key and must never be named; a direct key
139
+ // must name it.
140
+ body = sessionCreateBody(spec, { extensionId: await extension(), ...(projectId && !baseUrl && !connectBase ? { projectId } : {}), ...(context ? { context } : {}) });
141
+ }
142
+ catch (error) {
143
+ freeWriter(spec.tag);
144
+ throw error;
145
+ }
146
+ // At most once: an SDK retry of a create the server already served would open a second paid browser. A failed send keeps
147
+ // the profile's claim until findByTag has looked: the session may exist.
114
148
  const created = await (await client()).sessions.create(body, { maxRetries: 0, signal });
115
149
  connectUrls.set(held(created.id), created.connectUrl);
150
+ noteWriter(spec.tag, running({ id: created.id, tag: spec.tag }), () => sleep(options.profileSettleMs ?? 5_000));
116
151
  return { id: created.id, tag: spec.tag };
117
152
  },
118
153
  async findByTag(tag, signal) {
@@ -124,7 +159,13 @@ export function browserbaseProvider(options = {}) {
124
159
  // The query is the provider's, the match is ours: a lane that ignores `q` must never hand back someone else's
125
160
  // session. Both queries must answer: custody releases exactly these ids, so a failed status throws.
126
161
  const seen = new Set();
127
- return asked.flat().filter((r) => r.userMetadata?.agentrun_tag === tag && !seen.has(r.id) && seen.add(r.id)).map((r) => ({ id: r.id, tag }));
162
+ const found = asked.flat().filter((r) => r.userMetadata?.agentrun_tag === tag && !seen.has(r.id) && seen.add(r.id)).map((r) => ({ id: r.id, tag }));
163
+ if (!found.length)
164
+ freeWriter(tag);
165
+ for (const ref of found)
166
+ if (isWriter(ref.tag))
167
+ noteWriter(ref.tag, running(ref), () => sleep(options.profileSettleMs ?? 5_000));
168
+ return found;
128
169
  },
129
170
  status,
130
171
  async attach(ref, signal) {
@@ -170,7 +211,7 @@ export function browserbaseProvider(options = {}) {
170
211
  }
171
212
  },
172
213
  status: () => status(ref, signal),
173
- forget: () => forget(held(ref.id)),
214
+ forget: () => finished(ref),
174
215
  confirm,
175
216
  sleep,
176
217
  stillRunning: `Browserbase session ${ref.id} still running after a release request`,
@@ -1,3 +1,4 @@
1
+ import { type ChildProcess } from "node:child_process";
1
2
  import type { BrowserProvider } from "../core/host.js";
2
3
  export type CdpOptions =
3
4
  /** An existing browser: `http://host:port` or a `ws://` debugger URL. Release leaves it running. */
@@ -41,6 +42,19 @@ export declare class ProfileOwnershipUnclearError extends Error {
41
42
  readonly code = "profile_ownership_unclear";
42
43
  constructor(dir: string, port: number);
43
44
  }
45
+ /** A copy of a profile another Chrome is writing: that Chrome renames, truncates and deletes its journals and temp files
46
+ * all the time. A file gone by the time it is reached is skipped. `fs.cp` fails the whole copy on it, and `fs.copyFile`
47
+ * never returns for a file truncated while it copies (libuv's sendfile loop makes no progress and does not stop), so
48
+ * files go through streams, which end where the file ends. A cancelled `signal` stops the copy at the next file or chunk. */
49
+ export declare function copyProfile(from: string, to: string, signal?: AbortSignal): Promise<void>;
50
+ export declare function closeGracefully(port: number, pid: number, children: Map<number, ChildProcess>): Promise<void>;
51
+ /** 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,
52
+ * `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)
53
+ * only for a process that leads one. */
54
+ export declare function killTree(pid: number, io?: {
55
+ kill?: (pid: number, signal: "SIGKILL") => void;
56
+ leadsGroup?: (pid: number) => boolean | null;
57
+ }): Promise<void>;
44
58
  /** `internals` is for tests: the removal a release uses. */
45
59
  export declare function cdpProvider(options: CdpOptions, internals?: {
46
60
  remove?: RemoveDir;
@@ -1,8 +1,12 @@
1
1
  import { execFile, spawn } from "node:child_process";
2
- import { mkdir, open, readdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
2
+ import { createReadStream, createWriteStream, readFileSync } from "node:fs";
3
+ import { lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rm, stat, symlink, writeFile } from "node:fs/promises";
4
+ import os from "node:os";
5
+ import { pipeline } from "node:stream/promises";
3
6
  import path from "node:path";
4
- import { BrowserFailureError } from "../core/custody.js";
7
+ import { BrowserFailureError, PROFILE_NAME } from "../core/custody.js";
5
8
  import { cdpCall } from "./cdp-call.js";
9
+ import { claimWriter, freeWriter, noteWriter } from "./profiles.js";
6
10
  /** Stagehand 4.1.0's DEFAULT_CHROME_FLAGS (packages/sdk-ts/src/browser/localBrowser.ts, MIT, see NOTICE). Without them
7
11
  * Stagehand.create takes about 24 s on a local Chrome instead of under 100 ms. */
8
12
  const CHROME_FLAGS = [
@@ -32,7 +36,7 @@ const CHROME_FLAGS = [
32
36
  "--remote-allow-origins=*",
33
37
  "--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
34
38
  ];
35
- const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, extension: "loaded-locally" };
39
+ const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, profiles: false, extension: "loaded-locally", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
36
40
  const downloadsDir = (profileRoot, tag) => path.join(profileDir(profileRoot, tag) + ".downloads");
37
41
  const READY_MS = 20_000;
38
42
  /** 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
@@ -101,7 +105,8 @@ async function ownDebugger(profile) {
101
105
  const [port, browser] = (await readFile(path.join(profile, "DevToolsActivePort"), "utf8").catch(() => "")).split("\n");
102
106
  return /^\d+$/.test(port ?? "") && browser?.startsWith("/devtools/browser/") ? { port: Number(port), path: browser.trim() } : null;
103
107
  }
104
- const answeringPath = async (port) => debuggerUrl(`http://127.0.0.1:${port}`).then((url) => new URL(url).pathname, () => null);
108
+ /** Bounded: a Chrome that takes the connection and never answers must not hold a start past its deadline. */
109
+ const answeringPath = async (port) => debuggerUrl(`http://127.0.0.1:${port}`, AbortSignal.timeout(2_000)).then((url) => new URL(url).pathname, () => null);
105
110
  /** A port that takes the probe and does not answer within this may still be a live browser's. */
106
111
  const PROBE_MS = 2_000;
107
112
  /** A release that does not own the lease's browser left its profile: the port the profile names took the probe and did
@@ -127,6 +132,107 @@ const profileDir = (root, tag) => {
127
132
  throw new Error("a cdp lease tag is one path segment of [A-Za-z0-9_.-]");
128
133
  return path.join(root, tag);
129
134
  };
135
+ const savedDir = (root, name) => path.join(root, ".profiles", name);
136
+ const refusal = (message) => new BrowserFailureError({ ok: false, code: "refused", retryable: false, effect: "none", message });
137
+ /** A copy of a profile another Chrome is writing: that Chrome renames, truncates and deletes its journals and temp files
138
+ * all the time. A file gone by the time it is reached is skipped. `fs.cp` fails the whole copy on it, and `fs.copyFile`
139
+ * never returns for a file truncated while it copies (libuv's sendfile loop makes no progress and does not stop), so
140
+ * files go through streams, which end where the file ends. A cancelled `signal` stops the copy at the next file or chunk. */
141
+ export async function copyProfile(from, to, signal) {
142
+ signal?.throwIfAborted();
143
+ await mkdir(to, { recursive: true });
144
+ const entries = await readdir(from, { withFileTypes: true }).catch((error) => { if (error.code === "ENOENT")
145
+ return []; throw error; });
146
+ for (const entry of entries) {
147
+ signal?.throwIfAborted();
148
+ if (/^(Singleton|DevToolsActivePort|lockfile)/.test(entry.name) || entry.name === TMP_MARKER)
149
+ continue;
150
+ const source = path.join(from, entry.name);
151
+ const target = path.join(to, entry.name);
152
+ try {
153
+ if (entry.isDirectory())
154
+ await copyProfile(source, target, signal);
155
+ else if (entry.isSymbolicLink())
156
+ await symlink(await readlink(source), target);
157
+ else if (entry.isFile())
158
+ await pipeline(createReadStream(source), createWriteStream(target, { mode: (await stat(source)).mode & 0o777 }), signal ? { signal } : {});
159
+ }
160
+ catch (error) {
161
+ if (error.code !== "ENOENT" || signal?.aborted)
162
+ throw error;
163
+ }
164
+ }
165
+ }
166
+ /** A saved profile lives in `.profiles/<name>`, which no lease tag can name. Saving, the lease's own directory is a link to
167
+ * it, so release removes the link and never the profile; not saving, it is a copy that leaves the profile as it was. */
168
+ async function prepareProfile(root, dir, profile, tag, owner, signal, remove) {
169
+ if (!PROFILE_NAME.test(profile.name))
170
+ throw refusal("browser profile: a profile name is 1 to 64 characters of letters, digits, dot, underscore and dash, starting with a letter or digit. No session was started.");
171
+ const saved = savedDir(root, profile.name);
172
+ await rm(dir, { recursive: true, force: true });
173
+ if (!profile.save) {
174
+ const exists = await stat(saved).then((s) => s.isDirectory(), () => false);
175
+ if (exists) {
176
+ // A copy cut short (cancelled, a full disk) is no lease: nothing else knows this directory, so it goes here, and is said if it stays.
177
+ try {
178
+ await copyProfile(saved, dir, signal);
179
+ }
180
+ catch (error) {
181
+ const left = await removeAll([dir], remove);
182
+ throw left ? new ProfileNotRemovedError(left.dirs, left.error, error) : error;
183
+ }
184
+ }
185
+ return;
186
+ }
187
+ await claimWriter(`${path.resolve(root)}|${profile.name}`, profile.name, tag, owner, signal);
188
+ try {
189
+ const lock = await readlink(path.join(saved, "SingletonLock")).then((value) => /^(.*)-(\d+)$/.exec(value), () => null);
190
+ if (lock && lock[1] === os.hostname() && alive(Number(lock[2])))
191
+ throw refusal(`browser profile "${profile.name}": a Chrome process (${lock[2]}) is using this profile. No session was started.`);
192
+ await mkdir(path.join(saved, "Default"), { recursive: true });
193
+ await symlink(path.resolve(saved), dir, "dir");
194
+ }
195
+ catch (error) {
196
+ freeWriter(tag);
197
+ throw error;
198
+ }
199
+ }
200
+ /** Chrome writes temp entries under its TMPDIR (its singleton socket directory, its url_fetcher entries) and a Chrome that is killed removes none of
201
+ * 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
202
+ * 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
203
+ * 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
204
+ * 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
205
+ * made on Windows, where Chrome's temp directory is not TMPDIR. */
206
+ const TMP_MARKER = ".pib-tmpdir";
207
+ const TMP_OWNER = ".pib-owner";
208
+ const TMP_NAME = /^pib-[A-Za-z0-9]{6}$/;
209
+ const SOCKET_PATH_MAX = 107;
210
+ const SOCKET_PATH_TAIL = "/.org.chromium.Chromium.XXXXXX/SingletonSocket".length;
211
+ async function makePrivateTmp(tag, profile, remove) {
212
+ if (process.platform === "win32")
213
+ return null;
214
+ const base = os.tmpdir();
215
+ if (Buffer.byteLength(path.join(base, "pib-XXXXXX")) + SOCKET_PATH_TAIL > SOCKET_PATH_MAX)
216
+ return null;
217
+ const dir = await mkdtemp(path.join(base, "pib-"));
218
+ try {
219
+ await writeFile(path.join(dir, TMP_OWNER), tag);
220
+ await writeFile(path.join(profile, TMP_MARKER), dir);
221
+ }
222
+ catch (error) {
223
+ // The directory is not recorded anywhere yet, so a setup that fails here removes it, and names it if it cannot.
224
+ const left = await removeTree(dir, remove);
225
+ throw left ? new ProfileNotRemovedError([dir], left.error, error) : error;
226
+ }
227
+ return dir;
228
+ }
229
+ /** The private directory the profile names, when it is one this provider made for this tag. */
230
+ async function ownedTmp(profile, tag) {
231
+ const named = (await readFile(path.join(profile, TMP_MARKER), "utf8").catch(() => "")).trim();
232
+ if (!named || !path.isAbsolute(named) || !TMP_NAME.test(path.basename(named)))
233
+ return null;
234
+ return (await readFile(path.join(named, TMP_OWNER), "utf8").catch(() => null)) === tag ? named : null;
235
+ }
130
236
  /** Signal 0 only asks; EPERM means the process exists under another user. */
131
237
  const alive = (pid) => { try {
132
238
  process.kill(pid, 0);
@@ -155,18 +261,51 @@ async function singletonDir(profile) {
155
261
  const dir = socket && path.basename(socket) === "SingletonSocket" ? path.dirname(socket) : null;
156
262
  return dir && /^\.?(org\.chromium\.Chromium|com\.google\.Chrome)\.[A-Za-z0-9]{6}$/.test(path.basename(dir)) ? dir : null;
157
263
  }
158
- async function killTree(pid) {
159
- if (process.platform === "win32")
160
- return void (await new Promise((resolve) => execFile("taskkill", ["/pid", String(pid), "/T", "/F"], () => resolve())));
264
+ /** Whether `pid` leads its own process group (Chrome is started detached, so it does); null where there is no /proc to ask. */
265
+ function leadsOwnGroup(pid) {
266
+ if (process.platform !== "linux")
267
+ return null;
161
268
  try {
162
- process.kill(-pid, "SIGKILL");
269
+ const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
270
+ // pid (comm) state ppid pgrp ...: the name may hold spaces and brackets, so the fields are counted from its last ")".
271
+ return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[2]) === pid;
163
272
  }
164
273
  catch {
274
+ return false;
275
+ }
276
+ }
277
+ export async function closeGracefully(port, pid, children) {
278
+ try {
279
+ const session = await cdpCall(await debuggerUrl(`http://127.0.0.1:${port}`, AbortSignal.timeout(2_000)), "Browser.close", {}, 2_000);
280
+ session.close();
281
+ }
282
+ catch { /* the browser may close its socket before it answers */ }
283
+ const child = children.get(pid);
284
+ for (const deadline = Date.now() + 8_000; Date.now() < deadline;) {
285
+ if (child ? child.exitCode !== null || child.signalCode !== null : !alive(pid))
286
+ return;
287
+ await sleep(50);
288
+ }
289
+ }
290
+ /** 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,
291
+ * `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)
292
+ * only for a process that leads one. */
293
+ export async function killTree(pid, io = {}) {
294
+ if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid)
295
+ return;
296
+ if (process.platform === "win32")
297
+ return void (await new Promise((resolve) => execFile("taskkill", ["/pid", String(pid), "/T", "/F"], () => resolve())));
298
+ const kill = io.kill ?? ((target, signal) => process.kill(target, signal));
299
+ if ((io.leadsGroup ?? leadsOwnGroup)(pid) !== false) {
165
300
  try {
166
- process.kill(pid, "SIGKILL");
301
+ return kill(-pid, "SIGKILL");
167
302
  }
168
- catch { }
303
+ catch { /* no such group: the process alone */ }
169
304
  }
305
+ try {
306
+ kill(pid, "SIGKILL");
307
+ }
308
+ catch { /* already gone */ }
170
309
  }
171
310
  /** `internals` is for tests: the removal a release uses. */
172
311
  export function cdpProvider(options, internals = {}) {
@@ -174,9 +313,12 @@ export function cdpProvider(options, internals = {}) {
174
313
  const downloads = "chrome" in options ? localDownloads(options.chrome.profileRoot) : undefined;
175
314
  // So a release can wait for the exit it caused: an unreaped child still answers `kill 0`.
176
315
  const children = new Map();
177
- /** A socket directory a release could not remove: the profile's link that named it may go with the profile, so the next release of the
178
- * lease in this process is told it here. (A restarted process has the report's text.) */
179
- const socketsLeft = new Map();
316
+ /** Directories besides the profile (Chrome's socket directory, the lease's private TMPDIR) that a release could not remove: the profile that named
317
+ * 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.) */
318
+ const extrasLeft = new Map();
319
+ /** 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
320
+ * that something else removed first takes it along. */
321
+ const privateTmps = new Map();
180
322
  /** A spawned Chrome whose handle we hold is ours (a handle cannot name a recycled pid); after a restart, only while
181
323
  * the browser on the recorded port reports that pid. */
182
324
  const isOurs = async ({ pid, port }) => {
@@ -187,61 +329,101 @@ export function cdpProvider(options, internals = {}) {
187
329
  };
188
330
  return {
189
331
  name: "cdp",
190
- caps: CAPS,
332
+ caps: { ...CAPS, profiles: "chrome" in options },
191
333
  ...(downloads ? { downloads } : {}),
192
- async create(spec) {
334
+ async create(spec, signal) {
193
335
  if ("endpoint" in options)
194
336
  return { id: `endpoint:${spec.tag}`, tag: spec.tag };
195
337
  const { executablePath, profileRoot, headless = true, args = [] } = options.chrome;
196
338
  const sandbox = options.chrome.sandbox ?? process.env.PI_BROWSER_NO_SANDBOX !== "1";
197
339
  const dir = profileDir(profileRoot, spec.tag);
198
- await mkdir(path.join(dir, "Default"), { recursive: true });
199
- await mkdir(downloadsDir(profileRoot, spec.tag), { recursive: true });
200
- 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) } }));
201
- // A file left by an earlier Chrome on this profile names a browser that is not this one.
202
- await rm(path.join(dir, "DevToolsActivePort"), { force: true });
203
- const child = spawn(executablePath, [
204
- ...CHROME_FLAGS, ...(sandbox ? [] : ["--no-sandbox"]), ...(headless ? ["--headless=new"] : []), "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${dir}`,
205
- `--window-size=${spec.viewport.width},${spec.viewport.height}`, ...args, "about:blank",
206
- ], { stdio: "ignore", detached: true });
207
- // A Chrome that cannot start emits `error`, which unhandled would end the host: it rejects create instead.
208
- let failed = null;
209
- child.once("error", (error) => { failed = error; });
210
- child.once("exit", (code, signal) => {
211
- // A Chrome that cannot start its sandbox aborts (SIGABRT) before it opens a port: the signal is the fact, never
212
- // Chrome's words.
213
- failed ??= sandbox && signal === "SIGABRT"
214
- ? 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` })
215
- : new Error(`Chrome exited before it opened its debugging port (${signal ?? code})`);
216
- });
217
- if (child.pid === undefined) {
218
- await sleep(0);
219
- const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag)], remove);
220
- const why = failed ?? new Error("Chrome could not be started");
221
- throw left ? new ProfileNotRemovedError(left.dirs, left.error, why) : why;
222
- }
223
- child.unref();
224
- children.set(child.pid, child);
225
- // The lease is that Chrome only once the browser answering on the port is the one its profile file names, so a
226
- // port another browser holds is never taken for it.
340
+ if (spec.profile)
341
+ await prepareProfile(profileRoot, dir, spec.profile, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal, remove);
227
342
  try {
228
- for (const deadline = Date.now() + READY_MS;; await sleep(100)) {
229
- if (failed)
230
- throw failed;
231
- const own = await ownDebugger(dir);
232
- if (own && (await answeringPath(own.port)) === own.path)
233
- return { id: `local:${child.pid}:${own.port}:${spec.tag}`, tag: spec.tag };
234
- if (Date.now() > deadline)
235
- throw new Error("Chrome did not open its debugging port");
343
+ signal?.throwIfAborted();
344
+ await mkdir(path.join(dir, "Default"), { recursive: true });
345
+ await mkdir(downloadsDir(profileRoot, spec.tag), { recursive: true });
346
+ const prefsFile = path.join(dir, "Default", "Preferences");
347
+ const prefs = await readFile(prefsFile, "utf8").then((text) => { try {
348
+ return JSON.parse(text);
349
+ }
350
+ catch {
351
+ return {};
352
+ } }, () => ({}));
353
+ // A saved profile is a browser the next session picks up. A session cookie (no Expires, like rack.session) survives a restart only when Chrome is told to
354
+ // "continue where you left off" (session.restore_on_startup = 1) before it starts, so a profile that is kept sets it; the other keys stay as they are.
355
+ const keeping = spec.profile ? { session: { ...prefs.session, restore_on_startup: 1 } } : {};
356
+ // "Continue where you left off" would also reopen the previous tabs, and each would load its old URL at launch, before the driver, its navigation policy or an
357
+ // egress guard is attached. The tab-restore files are removed before Chrome starts (the session cookies live in the cookie store, not in them), so only the
358
+ // startup page opens. Chrome writes them again as it closes, and they are removed again at the next start.
359
+ if (spec.profile) {
360
+ await rm(path.join(dir, "Default", "Sessions"), { recursive: true, force: true });
361
+ for (const legacy of ["Current Session", "Current Tabs", "Last Session", "Last Tabs"])
362
+ await rm(path.join(dir, "Default", legacy), { force: true });
363
+ }
364
+ await writeFile(prefsFile, JSON.stringify({ ...prefs, ...keeping, download: { ...prefs.download, default_directory: downloadsDir(profileRoot, spec.tag), prompt_for_download: false }, savefile: { ...prefs.savefile, default_directory: downloadsDir(profileRoot, spec.tag) } }));
365
+ // A file left by an earlier Chrome on this profile names a browser that is not this one.
366
+ await rm(path.join(dir, "DevToolsActivePort"), { force: true });
367
+ const tmp = await makePrivateTmp(spec.tag, dir, remove);
368
+ if (tmp)
369
+ privateTmps.set(spec.tag, tmp);
370
+ const child = spawn(executablePath, [
371
+ ...CHROME_FLAGS, ...(sandbox ? [] : ["--no-sandbox"]), ...(headless ? ["--headless=new"] : []), "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${dir}`,
372
+ `--window-size=${spec.viewport.width},${spec.viewport.height}`, ...args, "about:blank",
373
+ ], { stdio: "ignore", detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
374
+ // A Chrome that cannot start emits `error`, which unhandled would end the host: it rejects create instead.
375
+ let failed = null;
376
+ child.once("error", (error) => { failed = error; });
377
+ child.once("exit", (code, signal) => {
378
+ // A Chrome that cannot start its sandbox aborts (SIGABRT) before it opens a port: the signal is the fact, never
379
+ // Chrome's words.
380
+ failed ??= sandbox && signal === "SIGABRT"
381
+ ? 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` })
382
+ : new Error(`Chrome exited before it opened its debugging port (${signal ?? code})`);
383
+ });
384
+ if (child.pid === undefined) {
385
+ await sleep(0);
386
+ const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), ...(tmp ? [tmp] : [])], remove);
387
+ privateTmps.delete(spec.tag);
388
+ const why = failed ?? new Error("Chrome could not be started");
389
+ throw left ? new ProfileNotRemovedError(left.dirs, left.error, why) : why;
390
+ }
391
+ child.unref();
392
+ children.set(child.pid, child);
393
+ // The lease is that Chrome only once the browser answering on the port is the one its profile file names, so a
394
+ // port another browser holds is never taken for it.
395
+ try {
396
+ for (const deadline = Date.now() + READY_MS;; await sleep(100)) {
397
+ if (failed)
398
+ throw failed;
399
+ const own = await ownDebugger(dir);
400
+ if (own && (await answeringPath(own.port)) === own.path) {
401
+ const pid = child.pid;
402
+ noteWriter(spec.tag, () => isOurs({ pid, port: own.port }));
403
+ return { id: `local:${pid}:${own.port}:${spec.tag}`, tag: spec.tag };
404
+ }
405
+ if (Date.now() > deadline)
406
+ throw new Error("Chrome did not open its debugging port");
407
+ }
408
+ }
409
+ catch (error) {
410
+ const kept = await this.release({ id: `local:${child.pid}:0:${spec.tag}`, tag: spec.tag }).then(() => null, (failure) => failure);
411
+ const left = await removeAll([downloadsDir(profileRoot, spec.tag)], remove);
412
+ if (kept && !(kept instanceof ProfileNotRemovedError))
413
+ throw kept;
414
+ const dirs = [...(kept instanceof ProfileNotRemovedError ? kept.dirs : []), ...(left?.dirs ?? [])];
415
+ throw dirs.length > 0 ? new ProfileNotRemovedError(dirs, kept instanceof ProfileNotRemovedError ? kept.cause : left.error, error) : error;
236
416
  }
237
417
  }
238
418
  catch (error) {
239
- const kept = await this.release({ id: `local:${child.pid}:0:${spec.tag}`, tag: spec.tag }).then(() => null, (failure) => failure);
240
- const left = await removeAll([downloadsDir(profileRoot, spec.tag)], remove);
241
- if (kept && !(kept instanceof ProfileNotRemovedError))
242
- throw kept;
243
- const dirs = [...(kept instanceof ProfileNotRemovedError ? kept.dirs : []), ...(left?.dirs ?? [])];
244
- throw dirs.length > 0 ? new ProfileNotRemovedError(dirs, kept instanceof ProfileNotRemovedError ? kept.cause : left.error, error) : error;
419
+ freeWriter(spec.tag);
420
+ if (spec.profile) {
421
+ // A reader's copy of the saved cookies stays on disk when this fails: the caller is told, with the start's own failure kept.
422
+ const left = await removeAll([dir], remove);
423
+ if (left)
424
+ throw new ProfileNotRemovedError(error instanceof ProfileNotRemovedError ? [...error.dirs, ...left.dirs] : left.dirs, left.error, error);
425
+ }
426
+ throw error;
245
427
  }
246
428
  },
247
429
  async findByTag() { return []; },
@@ -271,6 +453,7 @@ export function cdpProvider(options, internals = {}) {
271
453
  if (!local || local.tag !== ref.tag)
272
454
  return;
273
455
  const ours = await isOurs(local);
456
+ const saved = !("endpoint" in options) && SAFE_TAG.test(local.tag) && (await lstat(profileDir(options.chrome.profileRoot, local.tag)).then((info) => info.isSymbolicLink(), () => false));
274
457
  // A profile that a live browser this ref does not name still runs on is that browser's: nothing is removed. A port
275
458
  // that holds the probe past PROBE_MS cannot be ruled out, so the profile stays and the release says so.
276
459
  if (!ours && !("endpoint" in options) && SAFE_TAG.test(local.tag)) {
@@ -279,13 +462,28 @@ export function cdpProvider(options, internals = {}) {
279
462
  if (own) {
280
463
  const answer = await debuggerUrl(`http://127.0.0.1:${own.port}`, AbortSignal.timeout(PROBE_MS))
281
464
  .then((url) => new URL(url).pathname, (error) => (error instanceof Error && error.name === "TimeoutError" ? undefined : null));
282
- if (answer === own.path)
465
+ if (answer === own.path) {
466
+ if (!saved)
467
+ return;
468
+ // A saved lease's directory is a link to the profile the live browser runs on, so that browser is another lease's (a replacement
469
+ // for a crashed one): this lease's own link and private TMPDIR are still its to remove, and nothing the browser holds is.
470
+ freeWriter(local.tag);
471
+ const mine = privateTmps.get(local.tag);
472
+ const left = await removeAll([dir, ...(mine ? [mine] : [])], remove);
473
+ if (!mine || !left?.dirs.includes(mine))
474
+ privateTmps.delete(local.tag);
475
+ if (left)
476
+ throw new ProfileNotRemovedError(left.dirs, left.error);
283
477
  return;
478
+ }
284
479
  if (answer === undefined)
285
480
  throw new ProfileOwnershipUnclearError(dir, own.port);
286
481
  }
287
482
  }
288
483
  if (ours) {
484
+ // Chrome writes its cookies out on a timer and when it exits on its own: a saved profile gets the chance, then the kill.
485
+ if (saved)
486
+ await closeGracefully(local.port, local.pid, children);
289
487
  await killTree(local.pid);
290
488
  const child = children.get(local.pid);
291
489
  children.delete(local.pid);
@@ -299,16 +497,22 @@ export function cdpProvider(options, internals = {}) {
299
497
  }
300
498
  // The profile goes even after a crash; a tag that is not one path segment names nothing this provider made, so
301
499
  // nothing is removed.
500
+ freeWriter(local.tag);
302
501
  if (!("endpoint" in options) && SAFE_TAG.test(local.tag)) {
303
502
  const dir = profileDir(options.chrome.profileRoot, local.tag);
304
- const socketDir = (await singletonDir(dir)) ?? socketsLeft.get(local.tag) ?? null;
305
- // Both are always tried, the profile first named: the profile's link is the only place the socket directory's name is read, so it is
306
- // reported here with the profile's, not left for a later release to miss.
307
- const left = await removeAll([dir, ...(socketDir ? [socketDir] : [])], remove);
308
- if (socketDir && left?.dirs.includes(socketDir))
309
- socketsLeft.set(local.tag, socketDir);
503
+ const socketDir = await singletonDir(dir);
504
+ const tmp = privateTmps.get(local.tag) ?? await ownedTmp(dir, local.tag);
505
+ // 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
506
+ // they are reported here with the profile's, not left for a later release to miss.
507
+ const extras = [...new Set([...(socketDir ? [socketDir] : []), ...(tmp ? [tmp] : []), ...(extrasLeft.get(local.tag) ?? [])])];
508
+ const left = await removeAll([dir, ...extras], remove);
509
+ const stuck = extras.filter((extra) => left?.dirs.includes(extra));
510
+ if (stuck.length > 0)
511
+ extrasLeft.set(local.tag, stuck);
310
512
  else
311
- socketsLeft.delete(local.tag);
513
+ extrasLeft.delete(local.tag);
514
+ if (!tmp || !stuck.includes(tmp))
515
+ privateTmps.delete(local.tag);
312
516
  if (left)
313
517
  throw new ProfileNotRemovedError(left.dirs, left.error);
314
518
  }