@parcha/pi-browser 0.1.0-beta.21 → 0.1.0-beta.26

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 (58) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +38 -7
  3. package/dist/coding-agent-local.js +7 -6
  4. package/dist/coding-agent.js +32 -28
  5. package/dist/core/clip.js +2 -2
  6. package/dist/core/contract.d.ts +7 -0
  7. package/dist/core/contract.js +3 -0
  8. package/dist/core/custody.d.ts +13 -4
  9. package/dist/core/custody.js +23 -6
  10. package/dist/core/downloads.js +2 -2
  11. package/dist/core/driving.d.ts +6 -0
  12. package/dist/core/driving.js +8 -0
  13. package/dist/core/failures.d.ts +13 -3
  14. package/dist/core/failures.js +22 -15
  15. package/dist/core/host.d.ts +6 -0
  16. package/dist/core/redact.d.ts +9 -0
  17. package/dist/core/redact.js +9 -0
  18. package/dist/core/sites.js +2 -1
  19. package/dist/core/tools.d.ts +2 -2
  20. package/dist/core/tools.js +7 -10
  21. package/dist/core/web.d.ts +1 -6
  22. package/dist/core/web.js +8 -4
  23. package/dist/driver/extension-worker.js +149 -118
  24. package/dist/driver/page-driver.d.ts +2 -1
  25. package/dist/driver/sealed.d.ts +16 -0
  26. package/dist/driver/sealed.js +47 -0
  27. package/dist/driver/stagehand.js +7 -43
  28. package/dist/durable/journal.d.ts +31 -0
  29. package/dist/durable/journal.js +105 -0
  30. package/dist/{durable-result.d.ts → durable/result.d.ts} +1 -1
  31. package/dist/{store.d.ts → durable/store.d.ts} +2 -2
  32. package/dist/{store.js → durable/store.js} +1 -1
  33. package/dist/{web.d.ts → durable/web.d.ts} +4 -4
  34. package/dist/{web.js → durable/web.js} +5 -5
  35. package/dist/durable.d.ts +2 -2
  36. package/dist/durable.js +42 -135
  37. package/dist/live-view/provider.d.ts +1 -1
  38. package/dist/live-view/provider.js +1 -1
  39. package/dist/live-view/server.d.ts +2 -2
  40. package/dist/live-view/server.js +1 -3
  41. package/dist/providers/assigned.js +2 -3
  42. package/dist/providers/browserbase-net.d.ts +0 -1
  43. package/dist/providers/browserbase-net.js +0 -1
  44. package/dist/providers/browserbase.js +5 -4
  45. package/dist/providers/cdp.js +38 -43
  46. package/dist/providers/chrome-args.d.ts +18 -0
  47. package/dist/providers/chrome-args.js +66 -0
  48. package/dist/providers/chrome-stderr.d.ts +21 -0
  49. package/dist/providers/chrome-stderr.js +108 -0
  50. package/dist/providers/http.d.ts +4 -1
  51. package/dist/providers/http.js +5 -8
  52. package/dist/providers/kernel.d.ts +10 -1
  53. package/dist/providers/kernel.js +1 -1
  54. package/dist/providers/profiles.js +6 -6
  55. package/dist/providers/shared.d.ts +9 -0
  56. package/dist/providers/shared.js +5 -1
  57. package/package.json +7 -3
  58. /package/dist/{durable-result.js → durable/result.js} +0 -0
@@ -1,6 +1,6 @@
1
1
  import type { BrowserProvider } from "../core/host.js";
2
2
  import type { LiveViewHost } from "./server.js";
3
- /** The provider with a live view: `liveView(ref)` reports the viewer's URL (to the host's `onSession`, the one place it goes), and a release kills the
3
+ /** The provider with a live view: `liveView(ref)` reports the viewer's URL (to the host only: its `onSession` and a handoff's `request`), and a release kills the
4
4
  * token before the provider's own release runs, so a session that is going away cannot be driven. Wrap the cdp provider with it, as the frame recorder
5
5
  * wraps a provider with `watch`; the provider's own methods are untouched. */
6
6
  export declare function liveViewProvider(provider: BrowserProvider, host: LiveViewHost): BrowserProvider;
@@ -1,4 +1,4 @@
1
- /** The provider with a live view: `liveView(ref)` reports the viewer's URL (to the host's `onSession`, the one place it goes), and a release kills the
1
+ /** The provider with a live view: `liveView(ref)` reports the viewer's URL (to the host only: its `onSession` and a handoff's `request`), and a release kills the
2
2
  * token before the provider's own release runs, so a session that is going away cannot be driven. Wrap the cdp provider with it, as the frame recorder
3
3
  * wraps a provider with `watch`; the provider's own methods are untouched. */
4
4
  export function liveViewProvider(provider, host) {
@@ -30,8 +30,8 @@ export type LiveViewHost = {
30
30
  handle(req: IncomingMessage, res: ServerResponse): boolean;
31
31
  /** Takes a WebSocket upgrade for a viewer; true when the request was this host's. A bad Origin or an unknown path id is refused here. */
32
32
  upgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
33
- /** The viewer's URL for one session, with its token in the fragment. Idempotent per tag: the same URL until `release`. Only the host's `onSession`
34
- * ever receives it. Nothing starts until a viewer authenticates. */
33
+ /** The viewer's URL for one session, with its token in the fragment. Idempotent per tag: the same URL until `release`. Only the host receives it (its
34
+ * `onSession`, and a handoff's `request`), never the model. Nothing starts until a viewer authenticates. */
35
35
  open(tag: string, cdpUrl: string): Promise<LiveView>;
36
36
  /** The view `open` gave for a tag, or null: for a caller that must not start anything (`liveViewProvider` asks before it attaches). */
37
37
  known(tag: string): LiveView | null;
@@ -10,11 +10,11 @@ const ID = /^[A-Za-z0-9_-]{22}$/;
10
10
  const SLOW_VIEWER_BYTES = 512 * 1024;
11
11
  /** Input messages are tiny: a whole message, fragments included, over this ends the connection (1009). */
12
12
  const MAX_MESSAGE_BYTES = 64 * 1024;
13
- /** A viewer whose messages the protocol does not know: one is dropped with a notice, and past this many within the window the connection is closed. */
14
13
  /** While a person's command runs, their driving turn is renewed this often (the gate's window is 3 s by default). */
15
14
  const KEEP_DRIVING_MS = 1_000;
16
15
  /** Messages a viewer may have waiting behind the browser command that is running; the rest are dropped with `held busy`, and a viewer that keeps doing it is closed. */
17
16
  const MAX_QUEUED_INPUT = 32;
17
+ /** A viewer whose messages the protocol does not know: one is dropped with a notice, and past this many within the window the connection is closed. */
18
18
  const MAX_BAD_MESSAGES = 20;
19
19
  const BAD_WINDOW_MS = 10_000;
20
20
  export function createLiveView(options) {
@@ -31,8 +31,6 @@ export function createLiveView(options) {
31
31
  /** The opens waiting for the server, by tag: a `release` or a `close` that comes meanwhile marks them cancelled, and each open takes its own mark off when it ends, so
32
32
  * nothing is kept for a tag that has no open in flight. */
33
33
  const opening = new Map();
34
- const need = (value, what) => { if (value === undefined)
35
- throw new Error(`the live view has no ${what}`); return value; };
36
34
  const send = (conn, message) => { conn.send(JSON.stringify(message)); };
37
35
  const refuse = (conn, reason) => { send(conn, { type: "refused", reason }); conn.close(CLOSE_CODES[reason], reason); };
38
36
  /** The request's path, or null when its target cannot be read as one (`//[`): such a request is nobody's, so it is not this host's and nothing is thrown into the
@@ -4,9 +4,8 @@
4
4
  // custody releases at a failed launch, an orphan sweep or a conversation's end, and the session is the task's, not the
5
5
  // conversation's. The host takes it back itself, once, when the task's browser closes; after that the session's own
6
6
  // failure() answers every create. A second create while another custody holds it is a refusal: the run has one browser.
7
- import { BrowserFailureError } from "../core/custody.js";
7
+ import { BrowserFailureError, refusedError } from "../core/custody.js";
8
8
  import { FAILURE_CODES } from "../core/failures.js";
9
- const refused = (message) => new BrowserFailureError({ ok: false, code: "refused", retryable: false, effect: "none", message });
10
9
  /** A host session types a failure the model should read as an error carrying `failure`; the tool loop takes it as is. */
11
10
  function typed(error) {
12
11
  const failure = error?.failure;
@@ -42,7 +41,7 @@ export function assignedSessionProvider(input) {
42
41
  if (ended)
43
42
  throw new BrowserFailureError(ended);
44
43
  if (assignedCustody.heldBy !== null && assignedCustody.heldBy !== spec.tag)
45
- throw refused("This task has one browser, the website session assigned to it, and it is already open; keep using it.");
44
+ throw refusedError("This task has one browser, the website session assigned to it, and it is already open; keep using it.");
46
45
  assignedCustody.heldBy = spec.tag;
47
46
  assignedCustody.letGo.delete(spec.tag);
48
47
  return { id: session.id, tag: spec.tag };
@@ -1,4 +1,3 @@
1
- export { directFetch, closeDirectFetch } from "./http.js";
2
1
  /** Rewrite a Browserbase connect URL onto the credential proxy: only `*.browserbase.com` hosts, the signing query kept. */
3
2
  export declare function rewriteConnectUrl(connectUrl: string, connectBaseUrl: string | undefined | null): string;
4
3
  /** Direct, never through the HTTP(S) env proxy: it rejects CONNECT and the CDP WebSocket cannot ride it. Under `node
@@ -1,5 +1,4 @@
1
1
  import { browserbaseHoldings } from "./shared.js";
2
- export { directFetch, closeDirectFetch } from "./http.js";
3
2
  /** Rewrite a Browserbase connect URL onto the credential proxy: only `*.browserbase.com` hosts, the signing query kept. */
4
3
  export function rewriteConnectUrl(connectUrl, connectBaseUrl) {
5
4
  if (!connectUrl || !connectBaseUrl)
@@ -13,7 +13,9 @@ export const SEARCH_QUERY_MAX = 200;
13
13
  export const SEARCH_RESULTS_MAX = 25;
14
14
  /** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
15
15
  export const setDownloadBehavior = (url, options = {}) => cdpCall(url, "Browser.setDownloadBehavior", { behavior: "allow", downloadPath: options.downloadPath ?? "downloads", eventsEnabled: true }, options.timeoutMs);
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 } };
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 },
17
+ // A session is created with `allowedDomains` from the policy's allow list, which Browserbase enforces.
18
+ navigationAllow: true };
17
19
  const notFound = (e) => e?.status === 404;
18
20
  /** One signal for whichever of these there is (a store may call `make` without its limit). */
19
21
  const stopWhen = (...signals) => { const some = signals.filter((s) => s !== undefined); return some.length > 1 ? AbortSignal.any(some) : some[0]; };
@@ -79,8 +81,7 @@ export function browserbaseProvider(options = {}) {
79
81
  applyBrowserbaseNoProxy(env);
80
82
  const mod = await import(["@browserbasehq", "sdk"].join("/"));
81
83
  const Browserbase = mod.default ?? mod.Browserbase;
82
- const fetch = await directFetch();
83
- return new Browserbase({ apiKey, baseURL: baseUrl, ...(fetch ? { fetch } : {}) });
84
+ return new Browserbase({ apiKey, baseURL: baseUrl, fetch: await directFetch() });
84
85
  })());
85
86
  const extension = () => options.extensionId
86
87
  ? options.extensionId()
@@ -270,7 +271,7 @@ export function browserbaseProvider(options = {}) {
270
271
  const found = (await rec?.list(ref.id))?.downloads?.find((d) => String(d.pageId) === id && d.status === "COMPLETED" && d.downloadUrl);
271
272
  if (!found?.downloadUrl)
272
273
  throw new Error(`no rendered recording ${id} for session ${ref.id}`);
273
- const response = await ((await directFetch()) ?? fetch)(found.downloadUrl);
274
+ const response = await (await directFetch())(found.downloadUrl);
274
275
  if (!response.ok || !response.body)
275
276
  throw new Error(`recording download answered ${response.status}`);
276
277
  return response.body;
@@ -1,41 +1,15 @@
1
1
  import { execFile, spawn } from "node:child_process";
2
- import { createReadStream, createWriteStream, readFileSync } from "node:fs";
2
+ import { closeSync, createReadStream, createWriteStream, readFileSync } from "node:fs";
3
3
  import { lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rm, stat, symlink, writeFile } from "node:fs/promises";
4
4
  import os from "node:os";
5
5
  import { pipeline } from "node:stream/promises";
6
6
  import path from "node:path";
7
- import { BrowserFailureError, PROFILE_NAME } from "../core/custody.js";
7
+ import { BrowserFailureError, PROFILE_NAME, refusedError } from "../core/custody.js";
8
+ import { browserFailure } from "../core/failures.js";
8
9
  import { cdpCall } from "./cdp-call.js";
10
+ import { chromeTail, openChromeStderr, watchChromeStderr } from "./chrome-stderr.js";
9
11
  import { claimWriter, freeWriter, noteWriter } from "./profiles.js";
10
- /** Stagehand 4.1.0's DEFAULT_CHROME_FLAGS (packages/sdk-ts/src/browser/localBrowser.ts, MIT, see NOTICE). Without them
11
- * Stagehand.create takes about 24 s on a local Chrome instead of under 100 ms. */
12
- const CHROME_FLAGS = [
13
- "--disable-features=Translate,OptimizationHints,MediaRouter,DialMediaRouteProvider,CalculateNativeWinOcclusion,InterestFeedContentSuggestions,CertificateTransparencyComponentUpdater,AutofillServerCommunication,PrivacySandboxSettings4,RenderDocument",
14
- "--disable-component-extensions-with-background-pages",
15
- "--disable-background-networking",
16
- "--disable-component-update",
17
- "--disable-client-side-phishing-detection",
18
- "--disable-sync",
19
- "--metrics-recording-only",
20
- "--disable-default-apps",
21
- "--mute-audio",
22
- "--no-default-browser-check",
23
- "--no-first-run",
24
- "--disable-backgrounding-occluded-windows",
25
- "--disable-renderer-backgrounding",
26
- "--disable-background-timer-throttling",
27
- "--disable-ipc-flooding-protection",
28
- "--password-store=basic",
29
- "--use-mock-keychain",
30
- "--force-fieldtrials=*BackgroundTracing/default/",
31
- "--disable-hang-monitor",
32
- "--disable-prompt-on-repost",
33
- "--disable-domain-reliability",
34
- "--propagate-iph-for-testing",
35
- "--enable-unsafe-extension-debugging",
36
- "--remote-allow-origins=*",
37
- "--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
38
- ];
12
+ import { chromeArgs } from "./chrome-args.js";
39
13
  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 } };
40
14
  const downloadsDir = (profileRoot, tag) => path.join(profileDir(profileRoot, tag) + ".downloads");
41
15
  const READY_MS = 20_000;
@@ -133,7 +107,6 @@ const profileDir = (root, tag) => {
133
107
  return path.join(root, tag);
134
108
  };
135
109
  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
110
  /** A copy of a profile another Chrome is writing: that Chrome renames, truncates and deletes its journals and temp files
138
111
  * 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
112
  * never returns for a file truncated while it copies (libuv's sendfile loop makes no progress and does not stop), so
@@ -171,7 +144,7 @@ export async function copyProfile(from, to, signal) {
171
144
  * it, so release removes the link and never the profile; not saving, it is a copy that leaves the profile as it was. */
172
145
  async function prepareProfile(root, dir, profile, tag, owner, signal, remove) {
173
146
  if (!PROFILE_NAME.test(profile.name))
174
- 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.");
147
+ throw refusedError("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.");
175
148
  const saved = savedDir(root, profile.name);
176
149
  await rm(dir, { recursive: true, force: true });
177
150
  if (!profile.save) {
@@ -192,7 +165,7 @@ async function prepareProfile(root, dir, profile, tag, owner, signal, remove) {
192
165
  try {
193
166
  const lock = await readlink(path.join(saved, "SingletonLock")).then((value) => /^(.*)-(\d+)$/.exec(value), () => null);
194
167
  if (lock && lock[1] === os.hostname() && alive(Number(lock[2])))
195
- throw refusal(`browser profile "${profile.name}": a Chrome process (${lock[2]}) is using this profile. No session was started.`);
168
+ throw refusedError(`browser profile "${profile.name}": a Chrome process (${lock[2]}) is using this profile. No session was started.`);
196
169
  await mkdir(path.join(saved, "Default"), { recursive: true });
197
170
  await symlink(path.resolve(saved), dir, "dir");
198
171
  }
@@ -253,6 +226,7 @@ async function ownedBy(named, tag) {
253
226
  return null;
254
227
  return (await readFile(path.join(named, TMP_OWNER), "utf8").catch(() => null)) === tag ? named : null;
255
228
  }
229
+ const SANDBOX_HINT = "On a system that cannot start Chrome's sandbox (root, a container, restricted user namespaces), set sandbox: false or PI_BROWSER_NO_SANDBOX=1.";
256
230
  /** Signal 0 only asks; EPERM means the process exists under another user. */
257
231
  const alive = (pid) => { try {
258
232
  process.kill(pid, 0);
@@ -392,19 +366,37 @@ export function cdpProvider(options, internals = {}) {
392
366
  const tmp = await makePrivateTmp(spec.tag, dir, spec.profile?.save ? leaseRecord(profileRoot, spec.tag) : null, remove);
393
367
  if (tmp)
394
368
  privateTmps.set(spec.tag, tmp);
395
- const child = spawn(executablePath, [
396
- ...CHROME_FLAGS, ...(sandbox ? [] : ["--no-sandbox"]), ...(headless ? ["--headless=new"] : []), "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${dir}`,
397
- `--window-size=${spec.viewport.width},${spec.viewport.height}`, ...args, "about:blank",
398
- ], { stdio: "ignore", detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
369
+ const stderrFd = openChromeStderr(tmp);
370
+ let child;
371
+ try {
372
+ child = spawn(executablePath, [
373
+ ...chromeArgs({ userDataDir: dir, viewport: spec.viewport, headless, sandbox }), ...args, "about:blank",
374
+ ], { stdio: ["ignore", "ignore", stderrFd ?? "ignore"], detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
375
+ }
376
+ catch (error) {
377
+ // A spawn that throws (an argument with a null byte) starts no child, so nothing else will remove what this start made.
378
+ const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), ...(tmp ? [tmp] : [])], remove);
379
+ await forgetTmp(profileRoot, spec.tag);
380
+ throw left ? new ProfileNotRemovedError(left.dirs, left.error, error) : error;
381
+ }
382
+ finally {
383
+ // The parent's copy is closed whether or not spawn threw.
384
+ if (stderrFd !== null)
385
+ closeSync(stderrFd);
386
+ }
399
387
  // A Chrome that cannot start emits `error`, which unhandled would end the host: it rejects create instead.
400
388
  let failed = null;
401
389
  child.once("error", (error) => { failed = error; });
402
390
  child.once("exit", (code, signal) => {
403
- // A Chrome that cannot start its sandbox aborts (SIGABRT) before it opens a port: the signal is the fact, never
404
- // Chrome's words.
405
- failed ??= sandbox && signal === "SIGABRT"
406
- ? 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` })
407
- : new Error(`Chrome exited before it opened its debugging port (${signal ?? code})`);
391
+ // Whatever Chrome said goes into the failure. The sandbox hint goes with it when the sandbox is on and either Chrome
392
+ // aborted before it opened a port (SIGABRT, how some builds fail it) or its own words name the sandbox (others exit 1).
393
+ if (failed)
394
+ return;
395
+ const tail = chromeTail(tmp);
396
+ const message = `Chrome exited before it opened its debugging port (${signal ?? code})${tail ? `\nChrome said:\n${tail.split("\n").map((line) => ` ${line}`).join("\n")}` : ""}`;
397
+ failed = sandbox && (signal === "SIGABRT" || /sandbox/i.test(tail))
398
+ ? new BrowserFailureError(browserFailure("browser_unavailable", `${message}\n${SANDBOX_HINT}`))
399
+ : new Error(message);
408
400
  });
409
401
  if (child.pid === undefined) {
410
402
  await sleep(0);
@@ -425,6 +417,7 @@ export function cdpProvider(options, internals = {}) {
425
417
  if (own && (await answeringPath(own.port)) === own.path) {
426
418
  const pid = child.pid;
427
419
  noteWriter(spec.tag, () => isOurs({ pid, port: own.port }));
420
+ watchChromeStderr(tmp, pid);
428
421
  return { id: `local:${pid}:${own.port}:${spec.tag}`, tag: spec.tag };
429
422
  }
430
423
  if (Date.now() > deadline)
@@ -471,6 +464,8 @@ export function cdpProvider(options, internals = {}) {
471
464
  const url = await debuggerUrl(`http://127.0.0.1:${local.port}`);
472
465
  if (new URL(url).pathname !== own.path)
473
466
  throw new Error(`the browser on port ${local.port} is not the browser this lease's profile records`);
467
+ // A Chrome this host did not start outlived the host that did: its stderr file is bounded here too.
468
+ watchChromeStderr(privateTmps.get(local.tag) ?? await recordedTmp(options.chrome.profileRoot, local.tag) ?? await ownedTmp(profileDir(options.chrome.profileRoot, local.tag), local.tag), local.pid);
474
469
  return { sdkCdpUrl: url };
475
470
  },
476
471
  async release(ref) {
@@ -0,0 +1,18 @@
1
+ /** The directory Stagehand loads its extension from in a local Chrome (`Extensions.loadUnpacked`), resolved as Stagehand does. */
2
+ export declare function extensionDirectory(): string;
3
+ /** The Origin the extension's own DevTools socket carries. Chrome names an unpacked extension by the SHA-256 of its real path: the
4
+ * first 32 hex digits, each written as a letter a to p. A directory that cannot be resolved refuses the launch: the socket is never
5
+ * opened to every Origin instead. */
6
+ export declare function extensionOrigin(directory?: string): string;
7
+ /** Every argument a local Chrome is started with, but the page to open. The DevTools socket is the whole browser: Stagehand's own
8
+ * launcher allows every Origin (`*`), so a page the agent visits could drive the browser if it learned the socket's URL. Only the
9
+ * extension's socket carries an Origin (Node's clients send none), so only that Origin is allowed. */
10
+ export declare function chromeArgs(options: {
11
+ userDataDir: string;
12
+ viewport: {
13
+ width: number;
14
+ height: number;
15
+ };
16
+ headless?: boolean;
17
+ sandbox: boolean;
18
+ }): string[];
@@ -0,0 +1,66 @@
1
+ // The arguments the cdp provider starts a local Chrome with, in one place, so a host that starts its own Chrome for Stagehand can
2
+ // take the same list rather than copy it.
3
+ import { createHash } from "node:crypto";
4
+ import { realpathSync } from "node:fs";
5
+ import path from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+ import { BrowserFailureError } from "../core/custody.js";
8
+ import { browserFailure } from "../core/failures.js";
9
+ import { nonEmpty } from "./shared.js";
10
+ /** Stagehand 4.1.0's DEFAULT_CHROME_FLAGS (packages/sdk-ts/src/browser/localBrowser.ts, MIT, see NOTICE), less its
11
+ * `--remote-allow-origins=*`, which the launch below narrows to the extension's own Origin. Without them
12
+ * Stagehand.create takes about 24 s on a local Chrome instead of under 100 ms. */
13
+ const CHROME_FLAGS = [
14
+ "--disable-features=Translate,OptimizationHints,MediaRouter,DialMediaRouteProvider,CalculateNativeWinOcclusion,InterestFeedContentSuggestions,CertificateTransparencyComponentUpdater,AutofillServerCommunication,PrivacySandboxSettings4,RenderDocument",
15
+ "--disable-component-extensions-with-background-pages",
16
+ "--disable-background-networking",
17
+ "--disable-component-update",
18
+ "--disable-client-side-phishing-detection",
19
+ "--disable-sync",
20
+ "--metrics-recording-only",
21
+ "--disable-default-apps",
22
+ "--mute-audio",
23
+ "--no-default-browser-check",
24
+ "--no-first-run",
25
+ "--disable-backgrounding-occluded-windows",
26
+ "--disable-renderer-backgrounding",
27
+ "--disable-background-timer-throttling",
28
+ "--disable-ipc-flooding-protection",
29
+ "--password-store=basic",
30
+ "--use-mock-keychain",
31
+ "--force-fieldtrials=*BackgroundTracing/default/",
32
+ "--disable-hang-monitor",
33
+ "--disable-prompt-on-repost",
34
+ "--disable-domain-reliability",
35
+ "--propagate-iph-for-testing",
36
+ "--enable-unsafe-extension-debugging",
37
+ "--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
38
+ ];
39
+ /** The directory Stagehand loads its extension from in a local Chrome (`Extensions.loadUnpacked`), resolved as Stagehand does. */
40
+ export function extensionDirectory() {
41
+ return nonEmpty(process.env.STAGEHAND_EXTENSION_DIRECTORY_PATH) || path.join(path.dirname(fileURLToPath(import.meta.resolve("@browserbasehq/stagehand"))), "extension");
42
+ }
43
+ /** The Origin the extension's own DevTools socket carries. Chrome names an unpacked extension by the SHA-256 of its real path: the
44
+ * first 32 hex digits, each written as a letter a to p. A directory that cannot be resolved refuses the launch: the socket is never
45
+ * opened to every Origin instead. */
46
+ export function extensionOrigin(directory = extensionDirectory()) {
47
+ let real;
48
+ try {
49
+ real = realpathSync(directory);
50
+ }
51
+ catch (error) {
52
+ throw new BrowserFailureError(browserFailure("browser_unavailable", `Stagehand's extension directory ${directory} cannot be resolved (${error.code ?? "unreadable"}), so the browser's DevTools socket cannot be limited to the extension's Origin; no browser was started.`));
53
+ }
54
+ const hex = createHash("sha256").update(real).digest("hex").slice(0, 32);
55
+ return `chrome-extension://${[...hex].map((digit) => String.fromCharCode(97 + parseInt(digit, 16))).join("")}`;
56
+ }
57
+ /** Every argument a local Chrome is started with, but the page to open. The DevTools socket is the whole browser: Stagehand's own
58
+ * launcher allows every Origin (`*`), so a page the agent visits could drive the browser if it learned the socket's URL. Only the
59
+ * extension's socket carries an Origin (Node's clients send none), so only that Origin is allowed. */
60
+ export function chromeArgs(options) {
61
+ return [
62
+ ...CHROME_FLAGS, ...(options.sandbox ? [] : ["--no-sandbox"]), ...(options.headless ? ["--headless=new"] : []),
63
+ "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--remote-allow-origins=${extensionOrigin()}`,
64
+ `--user-data-dir=${options.userDataDir}`, `--window-size=${options.viewport.width},${options.viewport.height}`,
65
+ ];
66
+ }
@@ -0,0 +1,21 @@
1
+ /** What a Chrome that exits before its port opens said on stderr. Chrome writes to a file in the lease's private
2
+ * directory, not a pipe: a pipe would end Chrome's writes when this host dies, and the host's death is a case this
3
+ * package survives. The failure carries the last lines only, with control characters dropped and the common key shapes
4
+ * redacted: a model reads it. */
5
+ export declare const CHROME_STDERR = "chrome-stderr.log";
6
+ /** Once the port is open the start-up lines have done their work: the file is emptied then, and again whenever it passes
7
+ * this size, so a Chrome that logs heavily through `args` cannot fill the disk. */
8
+ export declare const KEEP_BYTES: number;
9
+ /** The file Chrome's stderr goes to, open for append; null when there is no private directory or it cannot be opened. */
10
+ export declare function openChromeStderr(dir: string | null): number | null;
11
+ /** The last lines Chrome wrote. A read that starts inside a line drops that partial line, and each whole line is redacted
12
+ * before it is shortened: a key cut by either would no longer match its shape. */
13
+ export declare function chromeTail(dir: string | null): string;
14
+ /** Empties the file when it is over `limit`. Chrome holds it open for append, so what it writes next lands at the new end. */
15
+ export declare function trimChromeStderr(dir: string | null, limit?: number): boolean;
16
+ /** From the moment the port is open (or a host recovers that Chrome) until that process or its file is gone, once per
17
+ * directory. A timer never keeps this host alive, and it is by pid, not by child: a recovered Chrome is no child of this host. */
18
+ export declare function watchChromeStderr(dir: string | null, pid: number, everyMs?: number): void;
19
+ /** For tests: how many directories are watched, and a way to stop them all. */
20
+ export declare const watchedChromeStderr: () => number;
21
+ export declare function stopWatchingChromeStderr(): void;
@@ -0,0 +1,108 @@
1
+ import { closeSync, fstatSync, openSync, readSync, statSync, truncateSync } from "node:fs";
2
+ import path from "node:path";
3
+ import { createRedactor } from "../core/redact.js";
4
+ /** What a Chrome that exits before its port opens said on stderr. Chrome writes to a file in the lease's private
5
+ * directory, not a pipe: a pipe would end Chrome's writes when this host dies, and the host's death is a case this
6
+ * package survives. The failure carries the last lines only, with control characters dropped and the common key shapes
7
+ * redacted: a model reads it. */
8
+ export const CHROME_STDERR = "chrome-stderr.log";
9
+ const TAIL_BYTES = 4096;
10
+ const TAIL_LINES = 10;
11
+ const LINE_CHARS = 300;
12
+ /** Once the port is open the start-up lines have done their work: the file is emptied then, and again whenever it passes
13
+ * this size, so a Chrome that logs heavily through `args` cannot fill the disk. */
14
+ export const KEEP_BYTES = 256 * 1024;
15
+ const TRIM_EVERY_MS = 60_000;
16
+ const redact = createRedactor();
17
+ /** The file Chrome's stderr goes to, open for append; null when there is no private directory or it cannot be opened. */
18
+ export function openChromeStderr(dir) {
19
+ if (!dir)
20
+ return null;
21
+ try {
22
+ return openSync(path.join(dir, CHROME_STDERR), "a", 0o600);
23
+ }
24
+ catch {
25
+ return null;
26
+ }
27
+ }
28
+ /** The last lines Chrome wrote. A read that starts inside a line drops that partial line, and each whole line is redacted
29
+ * before it is shortened: a key cut by either would no longer match its shape. */
30
+ export function chromeTail(dir) {
31
+ if (!dir)
32
+ return "";
33
+ let fd = null;
34
+ try {
35
+ fd = openSync(path.join(dir, CHROME_STDERR), "r");
36
+ const size = fstatSync(fd).size, from = Math.max(0, size - TAIL_BYTES), buf = Buffer.alloc(size - from);
37
+ readSync(fd, buf, 0, buf.length, from);
38
+ let text = buf.toString("utf8");
39
+ if (from > 0) {
40
+ // The read began inside a line. With no newline in the whole window it is one partial line, and none of it can be trusted to redact.
41
+ const newline = text.indexOf("\n");
42
+ if (newline === -1)
43
+ return "";
44
+ text = text.slice(newline + 1);
45
+ }
46
+ return text.replace(/[^\S\n]+/g, " ").replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, "").split("\n")
47
+ .map((line) => redact(line.trim())).filter(Boolean).slice(-TAIL_LINES)
48
+ .map((line) => (line.length > LINE_CHARS ? `${line.slice(0, LINE_CHARS)}...` : line)).join("\n");
49
+ }
50
+ catch {
51
+ return "";
52
+ }
53
+ finally {
54
+ if (fd !== null)
55
+ closeSync(fd);
56
+ }
57
+ }
58
+ /** Empties the file when it is over `limit`. Chrome holds it open for append, so what it writes next lands at the new end. */
59
+ export function trimChromeStderr(dir, limit = KEEP_BYTES) {
60
+ if (!dir)
61
+ return false;
62
+ const file = path.join(dir, CHROME_STDERR);
63
+ try {
64
+ if (statSync(file).size <= limit)
65
+ return false;
66
+ truncateSync(file, 0);
67
+ return true;
68
+ }
69
+ catch {
70
+ return false;
71
+ }
72
+ }
73
+ const watching = new Map();
74
+ const alive = (pid) => { try {
75
+ process.kill(pid, 0);
76
+ return true;
77
+ }
78
+ catch (error) {
79
+ return error.code === "EPERM";
80
+ } };
81
+ /** From the moment the port is open (or a host recovers that Chrome) until that process or its file is gone, once per
82
+ * directory. A timer never keeps this host alive, and it is by pid, not by child: a recovered Chrome is no child of this host. */
83
+ export function watchChromeStderr(dir, pid, everyMs = TRIM_EVERY_MS) {
84
+ if (!dir || watching.has(dir))
85
+ return;
86
+ trimChromeStderr(dir, 0);
87
+ const timer = setInterval(() => {
88
+ if (!alive(pid) || !statSyncOk(path.join(dir, CHROME_STDERR))) {
89
+ clearInterval(timer);
90
+ watching.delete(dir);
91
+ return;
92
+ }
93
+ trimChromeStderr(dir);
94
+ }, everyMs);
95
+ timer.unref();
96
+ watching.set(dir, timer);
97
+ }
98
+ const statSyncOk = (file) => { try {
99
+ statSync(file);
100
+ return true;
101
+ }
102
+ catch {
103
+ return false;
104
+ } };
105
+ /** For tests: how many directories are watched, and a way to stop them all. */
106
+ export const watchedChromeStderr = () => watching.size;
107
+ export function stopWatchingChromeStderr() { for (const timer of watching.values())
108
+ clearInterval(timer); watching.clear(); }
@@ -1,2 +1,5 @@
1
- export declare function directFetch(): Promise<((input: any, init?: any) => Promise<any>) | undefined>;
1
+ import type * as Undici from "undici";
2
+ /** fetch over the package's own undici agent: direct, never through the HTTP(S) env proxy. undici is a dependency, so a load that
3
+ * fails is a broken install and throws; there is no fallback to the global fetch, which would follow the proxy. */
4
+ export declare function directFetch(): Promise<typeof Undici.fetch>;
2
5
  export declare function closeDirectFetch(): Promise<void>;
@@ -4,15 +4,12 @@ let undiciModule;
4
4
  /** Loaded on first use, so a process that never reaches a provider never loads undici. */
5
5
  const undiciDoor = () => (undiciModule ??= require("undici"));
6
6
  let directAgent;
7
+ /** fetch over the package's own undici agent: direct, never through the HTTP(S) env proxy. undici is a dependency, so a load that
8
+ * fails is a broken install and throws; there is no fallback to the global fetch, which would follow the proxy. */
7
9
  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
- }
10
+ const undici = undiciDoor();
11
+ // Userland undici refuses a request body it must stream (the extension upload's multipart file) without `duplex`.
12
+ return (input, init = {}) => undici.fetch(input, { ...init, dispatcher: (directAgent ??= new undici.Agent()), ...(init.body ? { duplex: "half" } : {}) });
16
13
  }
17
14
  export async function closeDirectFetch() {
18
15
  const agent = directAgent;
@@ -2,12 +2,21 @@ import type { BrowserProvider, SessionSpec } from "../core/host.js";
2
2
  export declare const KERNEL_BASE_URL = "https://api.onkernel.com";
3
3
  export declare const KERNEL_IDLE_MIN_S = 10;
4
4
  export declare const KERNEL_IDLE_MAX_S = 259200;
5
+ /** What the provider reads of a reply: the global fetch's Response and undici's both have it. */
6
+ type HttpReply = {
7
+ ok: boolean;
8
+ status: number;
9
+ headers: {
10
+ get(name: string): string | null;
11
+ };
12
+ text(): Promise<string>;
13
+ };
5
14
  type HttpFetch = (input: string, init: {
6
15
  method: string;
7
16
  headers: Record<string, string>;
8
17
  body?: Uint8Array | string;
9
18
  signal?: AbortSignal;
10
- }) => Promise<Response>;
19
+ }) => Promise<HttpReply>;
11
20
  export type KernelOptions = {
12
21
  /** KERNEL_API_KEY and KERNEL_BASE_URL (default https://api.onkernel.com). Default: process.env. */
13
22
  env?: NodeJS.ProcessEnv;
@@ -46,7 +46,7 @@ export function kernelProvider(options = {}) {
46
46
  const sleep = options.sleep ?? defaultSleep;
47
47
  const confirm = options.confirm ?? DEFAULT_CONFIRM;
48
48
  let client = null;
49
- const http = () => (client ??= options.fetch ? Promise.resolve(options.fetch) : directFetch().then((f) => (f ?? fetch)));
49
+ const http = () => (client ??= options.fetch ? Promise.resolve(options.fetch) : directFetch());
50
50
  /** One request, never retried: a create served twice would be a second paid browser. On failure only Kernel's `code`
51
51
  * survives; a transport failure keeps its cause chain under a message that names the call alone. */
52
52
  async function call(method, route, init = {}) {
@@ -2,12 +2,12 @@ import { randomBytes } from "node:crypto";
2
2
  import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
3
3
  import os from "node:os";
4
4
  import path from "node:path";
5
- import { BrowserFailureError } from "../core/custody.js";
5
+ import { refusedError } from "../core/custody.js";
6
6
  import { withLock } from "../core/downloads.js";
7
- const writers = new Map();
7
+ import { profileHoldings } from "./shared.js";
8
+ const writers = profileHoldings.writers;
8
9
  const WAIT_MS = 20_000;
9
10
  const PROBE_MS = 2_000;
10
- const refusal = (message) => new BrowserFailureError({ ok: false, code: "refused", retryable: false, effect: "none", message });
11
11
  /** True when `work` finishes within `ms`; false at the deadline; rejects when `signal` aborts, leaving `work` to finish alone. */
12
12
  async function waitFor(work, signal, ms) {
13
13
  let timer;
@@ -43,15 +43,15 @@ export async function claimWriter(key, name, tag, owner, signal) {
43
43
  }
44
44
  if (held.running && !(await held.running(AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(PROBE_MS)])).catch(() => true))) {
45
45
  if (held.settle && !(await waitFor(held.settle(), signal, end - Date.now())))
46
- throw refusal(`browser profile "${name}": the session that was saving to it is still ending. Try again in a moment. No session was started.`);
46
+ throw refusedError(`browser profile "${name}": the session that was saving to it is still ending. Try again in a moment. No session was started.`);
47
47
  if (writers.get(key) === held)
48
48
  writers.delete(key);
49
49
  continue;
50
50
  }
51
51
  if (held.owner !== owner)
52
- throw refusal(`browser profile "${name}": one session at a time may save to a profile, and another session is saving to it now. Wait for it to end, or start without saving. No session was started.`);
52
+ throw refusedError(`browser profile "${name}": one session at a time may save to a profile, and another session is saving to it now. Wait for it to end, or start without saving. No session was started.`);
53
53
  if (Date.now() > end)
54
- throw refusal(`browser profile "${name}": the session that was saving to it is still ending. Try again in a moment. No session was started.`);
54
+ throw refusedError(`browser profile "${name}": the session that was saving to it is still ending. Try again in a moment. No session was started.`);
55
55
  signal?.throwIfAborted();
56
56
  await new Promise((resolve) => setTimeout(resolve, 100));
57
57
  }
@@ -44,4 +44,13 @@ export declare const kernelHoldings: {
44
44
  name: string;
45
45
  }>>;
46
46
  };
47
+ /** Which session may save to a named profile now, by profile: claimed by both cloud providers (providers/profiles.ts). */
48
+ export declare const profileHoldings: {
49
+ writers: Map<string, {
50
+ tag: string;
51
+ owner: string;
52
+ running?: (signal: AbortSignal) => Promise<boolean>;
53
+ settle?: () => Promise<void>;
54
+ }>;
55
+ };
47
56
  export declare function resetProviderHoldings(): void;
@@ -75,8 +75,12 @@ export const kernelHoldings = {
75
75
  liveUrls: new Map(),
76
76
  uploads: new Map(),
77
77
  };
78
+ /** Which session may save to a named profile now, by profile: claimed by both cloud providers (providers/profiles.ts). */
79
+ export const profileHoldings = {
80
+ writers: new Map(),
81
+ };
78
82
  export function resetProviderHoldings() {
79
- for (const holdings of [browserbaseHoldings, kernelHoldings])
83
+ for (const holdings of [browserbaseHoldings, kernelHoldings, profileHoldings])
80
84
  for (const map of Object.values(holdings))
81
85
  map.clear();
82
86
  }