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

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 (41) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +19 -5
  3. package/dist/coding-agent-local.d.ts +1 -6
  4. package/dist/coding-agent-local.js +9 -79
  5. package/dist/coding-agent.d.ts +10 -1
  6. package/dist/coding-agent.js +45 -10
  7. package/dist/core/contract.d.ts +2 -0
  8. package/dist/core/contract.js +7 -1
  9. package/dist/core/decisions.d.ts +3 -1
  10. package/dist/core/effects.d.ts +8 -0
  11. package/dist/core/effects.js +54 -5
  12. package/dist/core/host.d.ts +24 -6
  13. package/dist/core/public-fetch.d.ts +39 -0
  14. package/dist/core/public-fetch.js +159 -0
  15. package/dist/core/vault.d.ts +68 -0
  16. package/dist/core/vault.js +79 -0
  17. package/dist/core/web.d.ts +31 -0
  18. package/dist/core/web.js +145 -14
  19. package/dist/driver/stagehand.js +2 -1
  20. package/dist/durable/web.d.ts +7 -1
  21. package/dist/durable/web.js +4 -1
  22. package/dist/durable.d.ts +2 -1
  23. package/dist/durable.js +58 -10
  24. package/dist/index.d.ts +2 -0
  25. package/dist/index.js +2 -0
  26. package/dist/providers/browserbase.d.ts +1 -1
  27. package/dist/providers/browserbase.js +11 -1
  28. package/dist/providers/cdp-session.d.ts +28 -0
  29. package/dist/providers/cdp-session.js +153 -0
  30. package/dist/providers/cdp.d.ts +6 -0
  31. package/dist/providers/cdp.js +52 -2
  32. package/dist/providers/chrome-args.d.ts +3 -1
  33. package/dist/providers/chrome-args.js +3 -2
  34. package/dist/providers/kernel.js +6 -0
  35. package/dist/providers/profiles.d.ts +4 -0
  36. package/dist/providers/profiles.js +10 -0
  37. package/dist/providers/worker-extension.d.ts +14 -0
  38. package/dist/providers/worker-extension.js +63 -0
  39. package/dist/vault-session.d.ts +58 -0
  40. package/dist/vault-session.js +219 -0
  41. package/package.json +5 -1
@@ -10,6 +10,7 @@ import { cdpCall } from "./cdp-call.js";
10
10
  import { chromeTail, openChromeStderr, watchChromeStderr } from "./chrome-stderr.js";
11
11
  import { claimWriter, freeWriter, noteWriter } from "./profiles.js";
12
12
  import { chromeArgs } from "./chrome-args.js";
13
+ import { COPY, copyExtension, copyId, isLoaded, loadConfined } from "./worker-extension.js";
13
14
  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 } };
14
15
  const downloadsDir = (profileRoot, tag) => path.join(profileDir(profileRoot, tag) + ".downloads");
15
16
  const READY_MS = 20_000;
@@ -313,6 +314,8 @@ export function cdpProvider(options, internals = {}) {
313
314
  /** 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
314
315
  * that something else removed first takes it along. */
315
316
  const privateTmps = new Map();
317
+ /** The confined extension each lease has been given, by tag, loaded on its first attach: its id is handed to Stagehand as the attach target's extension. */
318
+ const extensionIds = new Map();
316
319
  /** A lease whose private TMPDIR is gone (or never made) keeps neither its map entry nor its record. */
317
320
  const forgetTmp = async (root, tag) => {
318
321
  privateTmps.delete(tag);
@@ -320,15 +323,42 @@ export function cdpProvider(options, internals = {}) {
320
323
  };
321
324
  /** A spawned Chrome whose handle we hold is ours (a handle cannot name a recycled pid); after a restart, only while
322
325
  * the browser on the recorded port reports that pid. */
326
+ /** The endpoint leases this provider has released. An endpoint is left running, so a released lease has no process to look at: it is over because it was released. */
327
+ const endpointReleased = new Set();
323
328
  const isOurs = async ({ pid, port }) => {
324
329
  const child = children.get(pid);
325
330
  if (child)
326
331
  return child.exitCode === null && child.signalCode === null;
327
332
  return alive(pid) && (await browserPid(port)) === pid;
328
333
  };
334
+ /** The lease's confined extension, loaded from its copy on the first attach (an earlier attach, here or in a process that restarted, may have loaded it
335
+ * already); null when the lease was started without one. A load that fails fails the attach: Stagehand is never left to load its own, unconfined, directory
336
+ * (and the browser's socket is open to the copy's Origin only). */
337
+ const confinedExtension = (tag, devtoolsUrl) => {
338
+ if (!("chrome" in options) || options.chrome.confineExtension === false)
339
+ return Promise.resolve(null);
340
+ const { profileRoot } = options.chrome;
341
+ const known = extensionIds.get(tag);
342
+ if (known)
343
+ return known;
344
+ const loading = (async () => {
345
+ const dir = profileDir(profileRoot, tag);
346
+ const tmp = privateTmps.get(tag) ?? await recordedTmp(profileRoot, tag) ?? await ownedTmp(dir, tag);
347
+ const copy = tmp ? path.join(tmp, COPY) : null;
348
+ if (!copy || !(await lstat(copy).then(() => true, () => false)))
349
+ return null;
350
+ const own = copyId(copy);
351
+ return (await isLoaded(devtoolsUrl, own)) ? own : await loadConfined(copy, devtoolsUrl);
352
+ })();
353
+ extensionIds.set(tag, loading);
354
+ loading.catch(() => { if (extensionIds.get(tag) === loading)
355
+ extensionIds.delete(tag); });
356
+ return loading;
357
+ };
329
358
  return {
330
359
  name: "cdp",
331
360
  caps: { ...CAPS, profiles: "chrome" in options, ...("endpoint" in options ? { sharedBrowser: true } : {}) },
361
+ ...("chrome" in options || options.ownBrowser === true ? { vault: { kind: "cdp" } } : {}),
332
362
  ...(downloads ? { downloads } : {}),
333
363
  async create(spec, signal) {
334
364
  if ("endpoint" in options)
@@ -366,11 +396,23 @@ export function cdpProvider(options, internals = {}) {
366
396
  const tmp = await makePrivateTmp(spec.tag, dir, spec.profile?.save ? leaseRecord(profileRoot, spec.tag) : null, remove);
367
397
  if (tmp)
368
398
  privateTmps.set(spec.tag, tmp);
399
+ // The copy is made before Chrome starts: its path names the extension, and so the one Origin the browser's socket is opened to.
400
+ let copy = null;
401
+ if (tmp && options.chrome.confineExtension !== false) {
402
+ try {
403
+ copy = await copyExtension(tmp);
404
+ }
405
+ catch (error) {
406
+ const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), tmp], remove);
407
+ await forgetTmp(profileRoot, spec.tag);
408
+ throw left ? new ProfileNotRemovedError(left.dirs, left.error, error) : error;
409
+ }
410
+ }
369
411
  const stderrFd = openChromeStderr(tmp);
370
412
  let child;
371
413
  try {
372
414
  child = spawn(executablePath, [
373
- ...chromeArgs({ userDataDir: dir, viewport: spec.viewport, headless, sandbox }), ...args, "about:blank",
415
+ ...chromeArgs({ userDataDir: dir, viewport: spec.viewport, headless, sandbox, ...(copy ? { extensionDir: copy } : {}) }), ...args, "about:blank",
374
416
  ], { stdio: ["ignore", "ignore", stderrFd ?? "ignore"], detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
375
417
  }
376
418
  catch (error) {
@@ -446,6 +488,8 @@ export function cdpProvider(options, internals = {}) {
446
488
  },
447
489
  async findByTag() { return []; },
448
490
  async status(ref) {
491
+ if (ref.id.startsWith("endpoint:"))
492
+ return endpointReleased.has(ref.id) ? "gone" : "running";
449
493
  const local = parse(ref.id);
450
494
  // A local-shaped id this provider cannot read names no process it can vouch for: gone, never "running" unchecked.
451
495
  if (!local)
@@ -466,9 +510,14 @@ export function cdpProvider(options, internals = {}) {
466
510
  throw new Error(`the browser on port ${local.port} is not the browser this lease's profile records`);
467
511
  // A Chrome this host did not start outlived the host that did: its stderr file is bounded here too.
468
512
  watchChromeStderr(privateTmps.get(local.tag) ?? await recordedTmp(options.chrome.profileRoot, local.tag) ?? await ownedTmp(profileDir(options.chrome.profileRoot, local.tag), local.tag), local.pid);
469
- return { sdkCdpUrl: url };
513
+ const extensionId = await confinedExtension(local.tag, url);
514
+ return { sdkCdpUrl: url, ...(extensionId ? { extensionId } : {}) };
470
515
  },
471
516
  async release(ref) {
517
+ if (ref.id.startsWith("endpoint:")) {
518
+ endpointReleased.add(ref.id);
519
+ return;
520
+ }
472
521
  const local = parse(ref.id);
473
522
  if (!local || local.tag !== ref.tag)
474
523
  return;
@@ -519,6 +568,7 @@ export function cdpProvider(options, internals = {}) {
519
568
  // The profile goes even after a crash; a tag that is not one path segment names nothing this provider made, so
520
569
  // nothing is removed.
521
570
  freeWriter(local.tag);
571
+ extensionIds.delete(local.tag);
522
572
  if (!("endpoint" in options) && SAFE_TAG.test(local.tag)) {
523
573
  const dir = profileDir(options.chrome.profileRoot, local.tag);
524
574
  const socketDir = await singletonDir(dir);
@@ -6,7 +6,8 @@ export declare function extensionDirectory(): string;
6
6
  export declare function extensionOrigin(directory?: string): string;
7
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
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. */
9
+ * extension's socket carries an Origin (Node's clients send none), so only that Origin is allowed. `extensionDir`: the directory the
10
+ * browser will load the extension from, when it is not Stagehand's own (the cdp provider's per-lease copy). */
10
11
  export declare function chromeArgs(options: {
11
12
  userDataDir: string;
12
13
  viewport: {
@@ -15,4 +16,5 @@ export declare function chromeArgs(options: {
15
16
  };
16
17
  headless?: boolean;
17
18
  sandbox: boolean;
19
+ extensionDir?: string;
18
20
  }): string[];
@@ -56,11 +56,12 @@ export function extensionOrigin(directory = extensionDirectory()) {
56
56
  }
57
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
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. */
59
+ * extension's socket carries an Origin (Node's clients send none), so only that Origin is allowed. `extensionDir`: the directory the
60
+ * browser will load the extension from, when it is not Stagehand's own (the cdp provider's per-lease copy). */
60
61
  export function chromeArgs(options) {
61
62
  return [
62
63
  ...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
+ "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--remote-allow-origins=${extensionOrigin(options.extensionDir)}`,
64
65
  `--user-data-dir=${options.userDataDir}`, `--window-size=${options.viewport.width},${options.viewport.height}`,
65
66
  ];
66
67
  }
@@ -167,13 +167,18 @@ export function kernelProvider(options = {}) {
167
167
  throw error;
168
168
  }
169
169
  };
170
+ /** The saved profile each live session of this provider runs on, by tag: what a session vault may keep. */
171
+ const profilesUsed = new Map();
170
172
  return {
171
173
  name: "kernel",
172
174
  caps: CAPS,
175
+ vault: { kind: "context", provider: "kernel", contextIdsInClear: false, contextOf: (ref) => profilesUsed.get(ref.tag) ?? null },
173
176
  async create(spec, signal) {
174
177
  // The upload is shared by every create on the account: a cancelled caller stops waiting, the upload goes on for
175
178
  // the rest.
176
179
  signal?.throwIfAborted();
180
+ if (spec.profile)
181
+ profilesUsed.set(spec.tag, spec.profile.name);
177
182
  if (spec.profile?.save)
178
183
  await claimWriter(`${account}|profile:${spec.profile.name}`, spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
179
184
  let body;
@@ -267,6 +272,7 @@ export function kernelProvider(options = {}) {
267
272
  }
268
273
  },
269
274
  async release(ref, signal) {
275
+ profilesUsed.delete(ref.tag);
270
276
  await releaseAndConfirm({
271
277
  request: async () => ((await call("DELETE", `/browsers/${encodeURIComponent(ref.id)}`, { signal })).status === 404 ? "gone" : undefined),
272
278
  status: () => status(ref, signal),
@@ -11,7 +11,11 @@ export declare function isWriter(tag: string): boolean;
11
11
  * `resolve` returns the name's context, calling `make` only when there is none, and no two callers may both make one. */
12
12
  export type ProfileStore = {
13
13
  resolve(key: string, make: (signal: AbortSignal) => Promise<string>): Promise<string>;
14
+ /** True when the store writes the ids it holds to a clear file (the default one does). A session vault refuses a provider whose store does. */
15
+ readonly clear?: boolean;
14
16
  };
17
+ /** Context ids kept in this process only: for a host that moves them into its own vault, so none lands on disk. */
18
+ export declare function memoryProfileStore(): ProfileStore;
15
19
  /** A JSON file, read, extended and written under one lock, so two processes' first uses of a name make one context; a file that is
16
20
  * not this format, or cannot be read, is never overwritten. */
17
21
  export declare function fileProfileStore(file?: string, options?: {
@@ -74,6 +74,15 @@ export function isWriter(tag) {
74
74
  return true;
75
75
  return false;
76
76
  }
77
+ /** Context ids kept in this process only: for a host that moves them into its own vault, so none lands on disk. */
78
+ export function memoryProfileStore() {
79
+ const ids = new Map();
80
+ return { clear: false, resolve: (key, make) => { let known = ids.get(key); if (!known) {
81
+ known = make(AbortSignal.timeout(20_000));
82
+ ids.set(key, known);
83
+ known.catch(() => ids.delete(key));
84
+ } return known; } };
85
+ }
77
86
  const SCHEMA = "pi-browser.profiles.v1";
78
87
  const defaultProfilesFile = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "pi-browser", "profiles.json");
79
88
  const notOurs = (file) => new Error(`the profiles file ${path.basename(file)} is not a pi-browser profiles file, so it was left as it is`);
@@ -103,6 +112,7 @@ export function fileProfileStore(file = defaultProfilesFile(), options = {}) {
103
112
  // to run past the lock that protects it.
104
113
  const makeLimitMs = options.makeLimitMs ?? 20_000;
105
114
  return {
115
+ clear: true,
106
116
  async resolve(key, make) {
107
117
  await mkdir(path.dirname(file), { recursive: true });
108
118
  return withLock(`${file}.lock`, async () => {
@@ -0,0 +1,14 @@
1
+ export declare const COPY = "stagehand-extension";
2
+ /** `<into>/stagehand-extension`, a copy of Stagehand's extension directory. */
3
+ export declare function copyExtension(into: string, source?: string): Promise<string>;
4
+ /** The policy for the extension's pages and worker: its own files, and the browser's DevTools socket by its whole URL path. A
5
+ * manifest that already sets one is left alone only when it is exactly this one (an earlier load of this copy wrote it and failed
6
+ * before the browser took it, so a retry is safe); any other is not guessed at. */
7
+ export declare function connectPolicy(manifest: Record<string, unknown>, devtoolsUrl: string): Record<string, unknown>;
8
+ /** The id Chrome gives the unpacked extension at `copy`: the Origin the browser's socket was opened to, without its scheme. */
9
+ export declare const copyId: (copy: string) => string;
10
+ /** Writes the policy into the copy and loads it into the running browser; answers the extension's id. */
11
+ export declare function loadConfined(copy: string, devtoolsUrl: string): Promise<string>;
12
+ /** Whether the browser already holds, enabled, the extension with this id: the one a copy's path implies, never another that
13
+ * merely carries Stagehand's name (an earlier, unconfined copy would be taken for the lease's own). */
14
+ export declare function isLoaded(devtoolsUrl: string, id: string): Promise<boolean>;
@@ -0,0 +1,63 @@
1
+ // The Stagehand extension a local launched Chrome is given: a copy in the lease's private TMPDIR whose pages and worker may
2
+ // connect to nothing but the extension's own files and the browser's DevTools socket. Run code executes in that worker with
3
+ // the extension's host permissions, so the browser itself refuses what the observer can only watch. A copy, because the
4
+ // manifest is Stagehand's bytes and a directory shared by every lease cannot name this lease's socket; created before the
5
+ // browser starts, because its path decides the extension's id and so the one Origin the browser's socket is opened to.
6
+ import { cp, readFile, writeFile } from "node:fs/promises";
7
+ import path from "node:path";
8
+ import { cdpCall } from "./cdp-call.js";
9
+ import { extensionDirectory, extensionOrigin } from "./chrome-args.js";
10
+ export const COPY = "stagehand-extension";
11
+ const LOAD_MS = 20_000;
12
+ /** `<into>/stagehand-extension`, a copy of Stagehand's extension directory. */
13
+ export async function copyExtension(into, source = extensionDirectory()) {
14
+ const copy = path.join(into, COPY);
15
+ await cp(source, copy, { recursive: true, dereference: true });
16
+ return copy;
17
+ }
18
+ /** The policy for the extension's pages and worker: its own files, and the browser's DevTools socket by its whole URL path. A
19
+ * manifest that already sets one is left alone only when it is exactly this one (an earlier load of this copy wrote it and failed
20
+ * before the browser took it, so a retry is safe); any other is not guessed at. */
21
+ export function connectPolicy(manifest, devtoolsUrl) {
22
+ const socket = new URL(devtoolsUrl);
23
+ if (socket.protocol !== "ws:" && socket.protocol !== "wss:")
24
+ throw new Error("the browser's DevTools URL is not a WebSocket URL");
25
+ const policy = { extension_pages: `script-src 'self'; object-src 'self'; connect-src 'self' ${socket.protocol}//${socket.host}${socket.pathname}` };
26
+ if (manifest.content_security_policy === undefined)
27
+ return { ...manifest, content_security_policy: policy };
28
+ if (JSON.stringify(manifest.content_security_policy) === JSON.stringify(policy))
29
+ return manifest;
30
+ throw new Error("Stagehand's extension manifest already sets a content security policy, so its connections cannot be limited");
31
+ }
32
+ /** The id Chrome gives the unpacked extension at `copy`: the Origin the browser's socket was opened to, without its scheme. */
33
+ export const copyId = (copy) => extensionOrigin(copy).slice("chrome-extension://".length);
34
+ /** Writes the policy into the copy and loads it into the running browser; answers the extension's id. */
35
+ export async function loadConfined(copy, devtoolsUrl) {
36
+ const file = path.join(copy, "manifest.json");
37
+ const manifest = JSON.parse(await readFile(file, "utf8"));
38
+ await writeFile(file, JSON.stringify(connectPolicy(manifest, devtoolsUrl), null, 2));
39
+ const session = await cdpCall(devtoolsUrl, "Extensions.loadUnpacked", { path: copy }, LOAD_MS);
40
+ try {
41
+ const id = session.result?.id;
42
+ if (typeof id !== "string" || !id)
43
+ throw new Error("the browser did not return the extension's id");
44
+ // The socket is open to the Origin the copy's path implies: an extension named otherwise could not use it.
45
+ if (id !== copyId(copy))
46
+ throw new Error("the browser named the loaded extension differently than its directory implies");
47
+ return id;
48
+ }
49
+ finally {
50
+ session.close();
51
+ }
52
+ }
53
+ /** Whether the browser already holds, enabled, the extension with this id: the one a copy's path implies, never another that
54
+ * merely carries Stagehand's name (an earlier, unconfined copy would be taken for the lease's own). */
55
+ export async function isLoaded(devtoolsUrl, id) {
56
+ const session = await cdpCall(devtoolsUrl, "Extensions.getExtensions", {}, LOAD_MS);
57
+ try {
58
+ return (session.result?.extensions ?? []).some((e) => e.id === id && e.enabled);
59
+ }
60
+ finally {
61
+ session.close();
62
+ }
63
+ }
@@ -0,0 +1,58 @@
1
+ import type { AttachTarget, BrowserProvider, SessionSpec } from "./core/host.js";
2
+ import type { LeaseRef } from "./core/lease.js";
3
+ import { type DrivingGate } from "./core/driving.js";
4
+ import { type SessionVaultPort, type VaultTarget } from "./core/vault.js";
5
+ export type VaultOptions = {
6
+ /** Keeps a signed-in browser session for the host (encrypted, per-item keys). Absent: nothing is captured or restored. */
7
+ sessionVault?: SessionVaultPort;
8
+ /** The oldest a session cookie may be at restore. Absent, 24 h; above 24 h it is clamped to 24 h; zero or negative is refused when the extension is made. */
9
+ sessionVaultMaxSessionCookieAgeMs?: number;
10
+ };
11
+ export type VaultRuntime = {
12
+ port: SessionVaultPort;
13
+ maxAgeMs: number;
14
+ track(secret: string): void;
15
+ warn(message: string): void;
16
+ now(): Date; /** The newest capture attempt per vault key: an older one that is still reading when a newer one starts writes nothing. */
17
+ latest: Map<string, number>;
18
+ attempts: {
19
+ next: number;
20
+ }; /** How long a restore, and a capture, may take (20 s each); tests shorten them. */
21
+ restoreMs: number;
22
+ captureMs: number;
23
+ };
24
+ /** `null` when the host gave no vault. A bad age cap throws here, so a host learns at setup. */
25
+ export declare function vaultRuntime(options: VaultOptions, track: (secret: string) => void, warn: (message: string) => void, now?: () => Date, limits?: {
26
+ restoreMs?: number;
27
+ captureMs?: number;
28
+ }): VaultRuntime | null;
29
+ /** Waits, up to `ms`, for a person to stop driving a session: a capture reads only once they have handed back. True when the gate is free. */
30
+ export declare function untilQuiet(gate: DrivingGate | null, ms?: number): Promise<boolean>;
31
+ /** `vaulted`: this session was created under the host's vault plan (a context kind asked the provider for a saved context or profile), so it may be captured; a session that
32
+ * started with no target cannot be given one later, because its provider holds no context for it. `fresh`: nothing was kept, so a new context was made and its id is
33
+ * given to the vault right after the create (a restart then still finds it). */
34
+ export type RestorePlan = {
35
+ spec: SessionSpec;
36
+ afterAttach: ((target: AttachTarget) => Promise<void>) | null;
37
+ vaulted: boolean;
38
+ fresh: boolean;
39
+ /** Set when the vault may hold a saved sign-in this session did not take (the read failed, or what it holds could not be used here): this session is NOT captured, so it
40
+ * can never replace what is saved. The text is the warning given once at the first capture. */
41
+ holdBack?: string;
42
+ };
43
+ /** What the create does with the vault: the spec the provider is asked for (a kept context or profile for Browserbase and Kernel) and a step that runs after the
44
+ * browser is attached and before the driver is (a local Chrome's cookies and local storage). The record the adapter stores is made from the ORIGINAL spec, never this one. */
45
+ export declare function planRestore(rt: VaultRuntime | null, target: VaultTarget | undefined, provider: BrowserProvider, spec: SessionSpec): Promise<RestorePlan>;
46
+ export type CaptureOptions = {
47
+ /** Whether the session was created under the vault plan (RestorePlan.vaulted). A context kind session that was not cannot be captured. */
48
+ vaulted: boolean;
49
+ /** The session's driving gate, read when the capture runs: a person who begins driving while the browser is being read voids that read. */
50
+ gate?: () => DrivingGate | null;
51
+ /** RestorePlan.holdBack: a saved sign-in may exist that this session did not take, so it is never captured; the text is warned once. */
52
+ holdBack?: string;
53
+ };
54
+ /** A capture of one session, to run while its browser still exists. Never throws: a failure is a warning. Bounded in time from its first step: the target, the
55
+ * browser's DevTools socket and the host's port all sit inside the deadline, and when it passes the socket is closed and nothing more is read or written.
56
+ * `target` is read AT THE CAPTURE, so a host that learns the site and its origins mid-run (the person is asked to sign in first) is captured under what it set
57
+ * last; a target that reads as absent means the host no longer wants this session kept, and nothing is captured. */
58
+ export declare function captureFor(rt: VaultRuntime, target: VaultTarget | undefined | (() => Promise<VaultTarget | undefined> | VaultTarget | undefined), provider: BrowserProvider, ref: LeaseRef, options?: CaptureOptions): () => Promise<void>;
@@ -0,0 +1,219 @@
1
+ // How an adapter uses a host's session vault (core/vault.ts): restore a kept sign-in when a session is created, before the driver attaches, and capture
2
+ // it when the session is released or a person hands it back. The state stays in memory and crosses only the host's port: nothing here logs a value, and
3
+ // a provider's context id is registered with the run's redactor the moment it is seen. A restore or capture that fails never fails the browser: the session
4
+ // starts signed out, or ends without a fresh capture, and a process warning says which, with no value in it.
5
+ import { randomBytes } from "node:crypto";
6
+ import { BrowserFailureError } from "./core/custody.js";
7
+ import { browserFailure } from "./core/failures.js";
8
+ import { MIN_REDACTED_VALUE_LENGTH } from "./core/redact.js";
9
+ import { keptFor } from "./core/driving.js";
10
+ import { clampSessionCookieAgeMs, coversEveryOrigin, vaultTarget } from "./core/vault.js";
11
+ import { captureCdpState, connectCdp, restoreCdpState } from "./providers/cdp-session.js";
12
+ /** `null` when the host gave no vault. A bad age cap throws here, so a host learns at setup. */
13
+ export function vaultRuntime(options, track, warn, now = () => new Date(), limits = {}) {
14
+ if (!options.sessionVault)
15
+ return null;
16
+ return { port: options.sessionVault, maxAgeMs: clampSessionCookieAgeMs(options.sessionVaultMaxSessionCookieAgeMs), track, warn, now, latest: new Map(), attempts: { next: 0 }, restoreMs: limits.restoreMs ?? RESTORE_MS, captureMs: limits.captureMs ?? CAPTURE_MS };
17
+ }
18
+ /** Waits, up to `ms`, for a person to stop driving a session: a capture reads only once they have handed back. True when the gate is free. */
19
+ export async function untilQuiet(gate, ms = 5000) {
20
+ const until = Date.now() + ms;
21
+ while (gate && keptFor(gate) === "person_driving" && Date.now() < until)
22
+ await new Promise((resolve) => setTimeout(resolve, 200));
23
+ return !gate || keptFor(gate) !== "person_driving";
24
+ }
25
+ const kindOf = (error) => (error instanceof Error ? error.name : "Error");
26
+ const CAPTURE_MS = 20_000;
27
+ const RESTORE_MS = 20_000;
28
+ /** `work`'s value, or a TimeoutError once `ms` pass (`onTimeout` runs then, to stop what `work` is still doing). The work is never left holding a caller. */
29
+ async function within(work, ms, onTimeout = () => { }) {
30
+ let timer;
31
+ try {
32
+ return await Promise.race([work, new Promise((_, reject) => { timer = setTimeout(() => { onTimeout(); reject(Object.assign(new Error("timed out"), { name: "TimeoutError" })); }, ms); })]);
33
+ }
34
+ finally {
35
+ clearTimeout(timer);
36
+ work.catch(() => undefined);
37
+ }
38
+ }
39
+ const refused = (message) => new BrowserFailureError(browserFailure("refused", message));
40
+ /** A secret too short for the redactor to scrub is not used as one: the redactor ignores values under its minimum, so it would leak. */
41
+ function trackSecret(rt, secret, what) {
42
+ if (secret.length < MIN_REDACTED_VALUE_LENGTH) {
43
+ rt.warn(`the session vault's ${what} is too short for the redactor to scrub, so it is not used`);
44
+ return false;
45
+ }
46
+ rt.track(secret);
47
+ return true;
48
+ }
49
+ const HELD_FAILED = "the vault could not be read at the start, so a saved sign-in may exist under this key and is left untouched: this session's sign-in is not captured";
50
+ const HELD_UNUSED = "the vault holds a saved sign-in this session could not use, and it is left untouched: this session's sign-in is not captured";
51
+ /** What the create does with the vault: the spec the provider is asked for (a kept context or profile for Browserbase and Kernel) and a step that runs after the
52
+ * browser is attached and before the driver is (a local Chrome's cookies and local storage). The record the adapter stores is made from the ORIGINAL spec, never this one. */
53
+ export async function planRestore(rt, target, provider, spec) {
54
+ const plain = { spec, afterAttach: null, vaulted: false, fresh: false };
55
+ if (!rt || !target)
56
+ return plain;
57
+ let checked;
58
+ try {
59
+ checked = vaultTarget(target);
60
+ }
61
+ catch (error) {
62
+ throw refused(`browser vault: ${error instanceof Error ? error.message : "a bad target"}. No session was started.`);
63
+ }
64
+ const vault = provider.vault;
65
+ if (!vault) {
66
+ rt.warn("this browser provider cannot keep a session in a vault (a Chrome attached by endpoint is offered only when the host sets ownBrowser: true), so nothing was restored or will be captured");
67
+ return plain;
68
+ }
69
+ if (vault.kind === "context" && vault.contextIdsInClear)
70
+ throw refused("browser vault: this provider writes its context ids to a clear file, so a vault cannot use it. Give it a profile store that keeps ids in memory (memoryProfileStore). No session was started.");
71
+ // A vault that stops answering never holds the session back: it starts signed out.
72
+ let kept = null;
73
+ let holdBack;
74
+ try {
75
+ kept = await within(Promise.resolve().then(() => rt.port.restore(checked)), rt.restoreMs);
76
+ }
77
+ catch (error) {
78
+ holdBack = HELD_FAILED;
79
+ rt.warn(`the session vault could not restore (${kindOf(error)}); the session starts signed out`);
80
+ }
81
+ if (vault.kind === "context") {
82
+ if (kept && (kept.kind !== "provider-context" || kept.provider !== vault.provider)) {
83
+ rt.warn(`the vault holds a ${kept.kind} state this ${vault.provider} provider cannot use; it was ignored`);
84
+ kept = null;
85
+ holdBack = HELD_UNUSED;
86
+ }
87
+ // A context is a whole browser profile: it comes back only for a request that covers every origin it was saved for, never for some of them.
88
+ if (kept?.kind === "provider-context" && !coversEveryOrigin(checked.origins, kept.origins)) {
89
+ rt.warn("the vault holds a context whose saved origins this request does not cover every origin of (or records none); it was not restored");
90
+ kept = null;
91
+ holdBack = HELD_UNUSED;
92
+ }
93
+ if (kept?.kind === "provider-context" && !trackSecret(rt, kept.contextId, "context id")) {
94
+ kept = null;
95
+ holdBack = HELD_UNUSED;
96
+ }
97
+ if (kept?.kind === "provider-context")
98
+ return { spec: vault.provider === "browserbase" ? { ...spec, contextId: kept.contextId, profile: undefined } : { ...spec, profile: { name: kept.contextId, save: true } }, afterAttach: null, vaulted: true, fresh: false };
99
+ // A saved sign-in may exist that this session did not take: nothing persists for it, and it is never captured.
100
+ if (holdBack)
101
+ return { spec, afterAttach: null, vaulted: true, fresh: false, holdBack };
102
+ // Nothing kept: a context that persists is made for this session, its id held in memory and given to the vault right after the create.
103
+ return { spec: { ...spec, contextId: undefined, profile: { name: `vault-${randomBytes(9).toString("hex")}`, save: true } }, afterAttach: null, vaulted: true, fresh: true };
104
+ }
105
+ if (!kept)
106
+ return { ...plain, vaulted: true, ...(holdBack ? { holdBack } : {}) };
107
+ if (kept.kind !== "cdp") {
108
+ rt.warn(`the vault holds a ${kept.kind} state a local Chrome cannot use; it was ignored`);
109
+ return { ...plain, vaulted: true, holdBack: HELD_UNUSED };
110
+ }
111
+ return {
112
+ spec,
113
+ vaulted: true,
114
+ fresh: false,
115
+ afterAttach: async (attached) => {
116
+ let link;
117
+ try {
118
+ await within((async () => {
119
+ link = await connectCdp(attached.sdkCdpUrl);
120
+ const counts = await restoreCdpState(link, kept, checked.origins, rt.now(), rt.maxAgeMs);
121
+ rt.warn(`the session vault restored ${counts.cookies} cookies and ${counts.origins} origins of local storage (dropped: ${counts.droppedExpired} expired, ${counts.droppedAged} aged, ${counts.droppedOutside} outside the origins)`);
122
+ })(), rt.restoreMs, () => link?.close());
123
+ }
124
+ catch (error) {
125
+ // Cookies are written before local storage, so a failure part-way leaves what was written: the session may be signed in only in part.
126
+ rt.warn(`the session vault restore failed (${kindOf(error)}); the session may start signed out, or signed in only in part`);
127
+ }
128
+ finally {
129
+ link?.close();
130
+ }
131
+ },
132
+ };
133
+ }
134
+ /** A capture of one session, to run while its browser still exists. Never throws: a failure is a warning. Bounded in time from its first step: the target, the
135
+ * browser's DevTools socket and the host's port all sit inside the deadline, and when it passes the socket is closed and nothing more is read or written.
136
+ * `target` is read AT THE CAPTURE, so a host that learns the site and its origins mid-run (the person is asked to sign in first) is captured under what it set
137
+ * last; a target that reads as absent means the host no longer wants this session kept, and nothing is captured. */
138
+ export function captureFor(rt, target, provider, ref, options = { vaulted: true }) {
139
+ let warnedLate = false;
140
+ return async () => {
141
+ const vault = provider.vault;
142
+ if (!vault)
143
+ return;
144
+ if (options.holdBack) {
145
+ if (!warnedLate) {
146
+ warnedLate = true;
147
+ rt.warn(options.holdBack);
148
+ }
149
+ return;
150
+ }
151
+ if (vault.kind === "context" && !options.vaulted) {
152
+ if (!warnedLate) {
153
+ warnedLate = true;
154
+ rt.warn("this session started with no vault target, so its provider holds no saved context for it: its sign-in cannot be kept. Set the target before the session starts");
155
+ }
156
+ return;
157
+ }
158
+ const stop = new AbortController();
159
+ let link;
160
+ // Numbered when it starts: an older capture that is still reading when a newer one of the same key begins writes nothing.
161
+ const attempt = ++rt.attempts.next;
162
+ const work = (async () => {
163
+ const wanted = typeof target === "function" ? await target() : target;
164
+ if (!wanted)
165
+ return;
166
+ const checked = vaultTarget(wanted);
167
+ const key = checked.sessionKey;
168
+ if ((rt.latest.get(key) ?? 0) < attempt)
169
+ rt.latest.set(key, attempt);
170
+ const capturedAt = rt.now();
171
+ let state;
172
+ if (vault.kind === "context") {
173
+ const id = vault.contextOf(ref);
174
+ if (!id) {
175
+ rt.warn("this provider no longer knows the context this session runs on (the run restarted), so its sign-in was not captured; the context the vault holds stands");
176
+ return;
177
+ }
178
+ if (!trackSecret(rt, id, "context id"))
179
+ return;
180
+ state = { kind: "provider-context", capturedAt: capturedAt.toISOString(), provider: vault.provider, contextId: id, origins: [...checked.origins] };
181
+ }
182
+ else {
183
+ const gate = options.gate?.() ?? null;
184
+ let interrupted = false;
185
+ const off = gate?.onChange((now) => { if (now === "person")
186
+ interrupted = true; });
187
+ try {
188
+ const attached = await provider.attach(ref, stop.signal);
189
+ link = await connectCdp(attached.sdkCdpUrl);
190
+ if (stop.signal.aborted) {
191
+ link.close();
192
+ return;
193
+ }
194
+ state = await captureCdpState(link, checked.origins, capturedAt);
195
+ }
196
+ finally {
197
+ off?.();
198
+ }
199
+ if (interrupted || (gate && keptFor(gate) === "person_driving")) {
200
+ rt.warn("a person began driving while the session was being read, so that capture was discarded; the last capture stands");
201
+ return;
202
+ }
203
+ }
204
+ // Nothing is written once the deadline has passed or a newer capture of this key has begun: an older read never replaces a newer one.
205
+ if (stop.signal.aborted || rt.latest.get(key) !== attempt)
206
+ return;
207
+ await rt.port.capture({ ...checked, state });
208
+ })();
209
+ try {
210
+ await within(work, rt.captureMs, () => { stop.abort(); link?.close(); });
211
+ }
212
+ catch (error) {
213
+ rt.warn(`the session vault could not capture this session (${kindOf(error)}); the last capture stands`);
214
+ }
215
+ finally {
216
+ link?.close();
217
+ }
218
+ };
219
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/pi-browser",
3
- "version": "0.1.0-beta.26",
3
+ "version": "0.1.0-beta.28",
4
4
  "description": "Your agent gets its own browser, and you can take over and hand it back.",
5
5
  "keywords": [
6
6
  "pi-package",
@@ -40,6 +40,10 @@
40
40
  "types": "./dist/providers/cdp.d.ts",
41
41
  "import": "./dist/providers/cdp.js"
42
42
  },
43
+ "./providers/cdp-session": {
44
+ "types": "./dist/providers/cdp-session.d.ts",
45
+ "import": "./dist/providers/cdp-session.js"
46
+ },
43
47
  "./providers/chrome-args": {
44
48
  "types": "./dist/providers/chrome-args.d.ts",
45
49
  "import": "./dist/providers/chrome-args.js"