@parcha/pi-browser 0.1.0-beta.27 → 0.1.0-beta.29

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 (57) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +29 -8
  3. package/dist/coding-agent-local.d.ts +3 -7
  4. package/dist/coding-agent-local.js +12 -80
  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 +11 -4
  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/entities.d.ts +3 -0
  13. package/dist/core/entities.js +68 -0
  14. package/dist/core/guard.d.ts +3 -0
  15. package/dist/core/guard.js +5 -0
  16. package/dist/core/host.d.ts +24 -6
  17. package/dist/core/page-classifier.d.ts +77 -0
  18. package/dist/core/page-classifier.js +92 -0
  19. package/dist/core/page-markdown.d.ts +5 -0
  20. package/dist/core/page-markdown.js +151 -0
  21. package/dist/core/page-scan.d.ts +95 -0
  22. package/dist/core/page-scan.js +542 -0
  23. package/dist/core/public-fetch.d.ts +32 -0
  24. package/dist/core/public-fetch.js +134 -0
  25. package/dist/core/read-page-worker.d.ts +8 -0
  26. package/dist/core/read-page-worker.js +32 -0
  27. package/dist/core/read-page.d.ts +46 -0
  28. package/dist/core/read-page.js +96 -0
  29. package/dist/core/tools.d.ts +9 -2
  30. package/dist/core/tools.js +56 -31
  31. package/dist/core/vault.d.ts +68 -0
  32. package/dist/core/vault.js +79 -0
  33. package/dist/core/web.d.ts +33 -0
  34. package/dist/core/web.js +155 -16
  35. package/dist/driver/stagehand.js +2 -1
  36. package/dist/durable/web.d.ts +7 -1
  37. package/dist/durable/web.js +4 -1
  38. package/dist/durable.d.ts +2 -1
  39. package/dist/durable.js +58 -10
  40. package/dist/index.d.ts +4 -0
  41. package/dist/index.js +4 -0
  42. package/dist/providers/browserbase.d.ts +1 -1
  43. package/dist/providers/browserbase.js +11 -1
  44. package/dist/providers/cdp-session.d.ts +28 -0
  45. package/dist/providers/cdp-session.js +153 -0
  46. package/dist/providers/cdp.d.ts +6 -0
  47. package/dist/providers/cdp.js +52 -2
  48. package/dist/providers/chrome-args.d.ts +3 -1
  49. package/dist/providers/chrome-args.js +3 -2
  50. package/dist/providers/kernel.js +6 -0
  51. package/dist/providers/profiles.d.ts +4 -0
  52. package/dist/providers/profiles.js +10 -0
  53. package/dist/providers/worker-extension.d.ts +14 -0
  54. package/dist/providers/worker-extension.js +63 -0
  55. package/dist/vault-session.d.ts +58 -0
  56. package/dist/vault-session.js +219 -0
  57. package/package.json +5 -1
package/dist/durable.js CHANGED
@@ -7,7 +7,8 @@ import { EffectObserver, effectDecider, observerFailure } from "./core/effects.j
7
7
  import { browserFailure, classifyBrowserError } from "./core/failures.js";
8
8
  import { workspaceFiles } from "./core/files.js";
9
9
  import { drivingGuarded } from "./core/driving-guard.js";
10
- import { drivingGates, keptReason, personOn, rearmWhenLeft } from "./core/driving.js";
10
+ import { drivingGates, keptFor, keptReason, personOn, rearmWhenLeft } from "./core/driving.js";
11
+ import { captureFor, planRestore, untilQuiet, vaultRuntime } from "./vault-session.js";
11
12
  import { pageTools } from "./core/tools.js";
12
13
  import { useWebsite, useWebsiteContract } from "./core/sites.js";
13
14
  import { leaseTag } from "./core/lease.js";
@@ -63,10 +64,16 @@ class Attachments {
63
64
  observer(tag) {
64
65
  return this.observers.get(tag);
65
66
  }
66
- attach(tag, driver, observer) {
67
+ captures = new Map();
68
+ attach(tag, driver, observer, capture = null) {
67
69
  this.observers.set(tag, observer);
68
70
  this.drivers.set(tag, driver);
71
+ if (capture && !this.captures.has(tag))
72
+ this.captures.set(tag, capture);
69
73
  }
74
+ /** The vault capture of this session, if it has one: run while its browser still exists. It outlives the driver's attachment (a session held for a person has none) and ends with the session's release. */
75
+ async capture(tag) { await this.captures.get(tag)?.(); }
76
+ dropCapture(tag) { this.captures.delete(tag); }
70
77
  async detach(tag) {
71
78
  const driver = this.drivers.get(tag);
72
79
  this.drivers.delete(tag);
@@ -166,11 +173,14 @@ async function attachLive(c, scope, record, bound) {
166
173
  return null;
167
174
  }
168
175
  }
169
- async function connect(c, scope, provider, ref) {
176
+ async function connect(c, scope, provider, ref, afterAttach = null, vaulted = true, holdBack) {
170
177
  const config = await scopeConfig(c, scope);
171
178
  const { actions: policy, batchTimeoutMs } = config.policy;
172
179
  c.owned.set(ref.tag, { cid: scope.cid, provider, ref });
173
180
  const target = await provider.attach(ref, scope.signal);
181
+ // A kept sign-in is put back before the driver, and so before any page, attaches.
182
+ if (afterAttach)
183
+ await afterAttach(target);
174
184
  const driver = await c.options.driver(target, scope.signal, { batchTimeoutMs });
175
185
  let unattached = null;
176
186
  // A healthy observer that outlived its driver's connection is kept, not opened a second time.
@@ -182,7 +192,19 @@ async function connect(c, scope, provider, ref) {
182
192
  await closeDriver(driver);
183
193
  throw new BrowserFailureError(browserFailure("browser_unavailable", "The browser's request observer could not attach, and this run's action policy needs it to hold requests; the browser is not used without it.", { retryable: true }));
184
194
  }
185
- c.held.attach(ref.tag, driver, observer);
195
+ // The capture reads the conversation's CURRENT vault target when it runs, not the one at create: a host may set it mid-run, once it knows the site, and may take it away
196
+ // (a read that succeeds and finds none means "do not keep this session"). Only a read that fails falls back to the target the session was created with.
197
+ const currentVault = async () => {
198
+ if (!c.opened)
199
+ return config.vault;
200
+ try {
201
+ return (await c.opened.harness.snapshot(c.Config, scope.cid, c.opened.context))?.vault;
202
+ }
203
+ catch {
204
+ return config.vault;
205
+ }
206
+ };
207
+ c.held.attach(ref.tag, driver, observer, c.vault ? captureFor(c.vault, currentVault, provider, ref, { vaulted, ...(holdBack ? { holdBack } : {}), gate: () => personOn(c.options.gates ?? drivingGates, ref.tag) }) : null);
186
208
  if (policy === "allow" && !observer)
187
209
  await emitObserver(c, { conversationId: scope.cid, label: config.label, tag: ref.tag, session_id: ref.id, policy, code: observerFailure(unattached) });
188
210
  return driver;
@@ -217,6 +239,8 @@ async function create(c, scope, overrides, presetTag) {
217
239
  const unsupported = profileRefusal(spec, provider.caps) ?? navigationRefusal(spec, provider);
218
240
  if (unsupported)
219
241
  throw new BrowserFailureError(unsupported);
242
+ // The vault may name a context or profile for the provider; the record stored below is made from the spec WITHOUT it, so no context id reaches the store.
243
+ const plan = await planRestore(c.vault, config.vault, provider, spec);
220
244
  const record = newSessionRecord({ plane: scope.plane, tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
221
245
  const row = rowOf(scope.cid, record);
222
246
  await scope.commit(async (tx) => {
@@ -226,7 +250,7 @@ async function create(c, scope, overrides, presetTag) {
226
250
  await c.store.begin(tx, row);
227
251
  });
228
252
  // An answer lost on the way back is not a session that never started: it is settled by its tag.
229
- const ref = await provider.create(spec, scope.signal).then(async (made) => {
253
+ const ref = await provider.create(plan.spec, scope.signal).then(async (made) => {
230
254
  // Owned before it is recorded: a store that cannot record it still lets close release it.
231
255
  c.owned.set(tag, { cid: scope.cid, provider, ref: made });
232
256
  await scope.commit((tx) => c.store.move(tx, row, { state: "live", resourceId: made.id, at: now() }));
@@ -241,7 +265,10 @@ async function create(c, scope, overrides, presetTag) {
241
265
  });
242
266
  const live = { ...record, state: "live", resourceId: ref.id };
243
267
  try {
244
- const driver = await connect(c, scope, provider, ref);
268
+ const driver = await connect(c, scope, provider, ref, plan.afterAttach, plan.vaulted, plan.holdBack);
269
+ // A context made for this session is given to the vault now, so a restart that loses the provider's memory of it still finds it.
270
+ if (plan.fresh)
271
+ await c.held.capture(ref.tag);
245
272
  await emit(c, scope.cid, config.label, live, "launched", provider);
246
273
  return { record: live, driver };
247
274
  }
@@ -299,9 +326,20 @@ function replacedOf(state, plane, current) {
299
326
  return reason === "idle" || reason === "close" || reason === "lost" ? { reason, at: before.endedAt, lastUrl: before.lastUrl } : null;
300
327
  }
301
328
  async function releaseRecord(c, scope, record, reason) {
329
+ await captureSession(c, record.tag);
302
330
  await scope.commit((tx) => c.store.requestRelease(tx, rowOf(scope.cid, record), reason, now()));
303
331
  await c.held.detach(record.tag);
304
332
  }
333
+ /** The vault capture of one session while its browser exists, skipped while a person is driving it (a capture reads only once they have handed back). Never throws. */
334
+ async function captureSession(c, tag, wait = false) {
335
+ if (!c.vault)
336
+ return;
337
+ const gate = personOn(c.options.gates ?? drivingGates, tag);
338
+ // At a handoff's end the person has just let go: their last input is within the driving window, so it is waited out (bounded) before the browser is read.
339
+ if (!(wait ? await untilQuiet(gate) : !gate || keptFor(gate) !== "person_driving"))
340
+ return;
341
+ await c.held.capture(tag);
342
+ }
305
343
  const editState = (c, scope, edit) => scope.commit(async (tx) => edit(await tx.doc(c.Sessions, scope.cid)));
306
344
  async function relaunchOn(c, scope, api, slot, overrides) {
307
345
  const config = await scopeConfig(c, scope);
@@ -528,6 +566,10 @@ function portFor(c, api, context) {
528
566
  const { state } = await api.waitForTask(task, context);
529
567
  if (state.outcome.status === "completed" && state.outcome.result) {
530
568
  const { outcome } = state.outcome.result;
569
+ // A sign-in just happened and the person has handed back: kept now, so a crash after it does not lose it.
570
+ const current = currentRecord(await stateOf(c, scope), scope.plane);
571
+ if (current)
572
+ await captureSession(c, current.tag, true);
531
573
  const told = notices.handedBack(outcome, ask.completionCondition);
532
574
  if ((await stateOf(c, scope)).notice?.includes(told)) {
533
575
  await editState(c, scope, (sessions) => { sessions.notice = sessions.notice?.replace(told, "").replace(/\s+/g, " ").trim() || null; });
@@ -590,6 +632,8 @@ async function releasePlane(c, conversation, reason, context, still = () => true
590
632
  const kept = { gate: null, tag: "" };
591
633
  const released = await c.serial.run(key, async () => {
592
634
  const mine = () => c.held.tags().filter((tag) => c.owned.get(tag)?.cid === conversation.id);
635
+ // Kept before anything closes: the browser is still there, and a release that is cancelled (a call since) only made one capture more.
636
+ await Promise.all(leasesOf(c, conversation.id).map((tag) => captureSession(c, tag)));
593
637
  // Closing a driver needs nothing from the store, so a release other than idle's starts closing the conversation's
594
638
  // drivers first and never waits for the commit to do it; the commit runs alongside, so the release task starts as
595
639
  // early as before. An idle release leaves it to the commit, which can find a call since or a person on the live view.
@@ -787,7 +831,10 @@ function endingOf(harness) {
787
831
  }
788
832
  export function createBrowserExtension(options) {
789
833
  const name = options.name ?? "browser";
790
- const redact = createRedactor(() => providerKeyValues(process.env, options.redact?.values));
834
+ // Secrets the package itself comes to hold (a vault's provider context id): registered as they are seen, so no output can carry one.
835
+ const tracked = new Set();
836
+ const redact = createRedactor(() => [...providerKeyValues(process.env, options.redact?.values), ...tracked]);
837
+ const vault = vaultRuntime(options, (secret) => { tracked.add(secret); }, (message) => process.emitWarning(`pi-browser: ${redact(message)}`, { code: "PI_BROWSER_VAULT" }));
791
838
  const Config = defineDoc({ kind: `${name}.config`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => structuredClone(UNCONFIGURED) });
792
839
  const Children = defineDoc({ kind: `${name}.children`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => ({ byRequest: {} }) });
793
840
  // A fork starts with no sessions: it never shares a live browser.
@@ -815,6 +862,7 @@ export function createBrowserExtension(options) {
815
862
  leaving.get(record.tag)?.();
816
863
  leaving.delete(record.tag);
817
864
  owned.delete(record.tag);
865
+ c.held.dropCapture(record.tag);
818
866
  }
819
867
  return emit(readers, cid, label, record, change);
820
868
  },
@@ -822,7 +870,7 @@ export function createBrowserExtension(options) {
822
870
  handedBack: (tag, fence) => c.fences.set(tag, { fence, failure: HANDED_BACK }),
823
871
  });
824
872
  const c = {
825
- ...readers, name, Sessions, Children, store, meter, held: new Attachments(), fences: new Map(), leaving, serial: keyedSerializer(), childTurns: oneAtATime(), guards: new Map(), owned, failed: false, ending: null, opened: null, incarnation: randomUUID(),
873
+ ...readers, name, Sessions, Children, store, meter, held: new Attachments(), vault, fences: new Map(), leaving, serial: keyedSerializer(), childTurns: oneAtATime(), guards: new Map(), owned, failed: false, ending: null, opened: null, incarnation: randomUUID(),
826
874
  idle: idleTracker({ idleMs: DEFAULT_BROWSER_POLICY.idleReleaseS * 1000, onIdle: (cid, fired, idleMs) => void releaseIdle(c, cid, fired, idleMs).catch(() => undefined) }),
827
875
  };
828
876
  // Every browser tool is a model call on its session's driving gate: refused while a person drives the live view, and the viewer's input is held while it runs. The host's own
@@ -851,8 +899,8 @@ export function createBrowserExtension(options) {
851
899
  c.leaving.clear();
852
900
  // A session whose driver was let go and not yet replaced still has its observer attached: close both kinds.
853
901
  await Promise.all(c.held.tags().map((tag) => c.held.detach(tag)));
854
- // A store that failed runs no release task again, so what this process still holds is released at the provider
855
- //. Over a healthy store it is kept, for the next run to resume or reconcile.
902
+ // A store that failed runs no release task again, so what this process still holds is released at the provider.
903
+ // Over a healthy store it is kept, for the next run to resume or reconcile.
856
904
  if (c.failed || (c.ending?.closing && await settleWithin(c.ending.failed, FAILED_END_MS, false)))
857
905
  await releaseDirectly(c, [...c.owned.keys()]);
858
906
  c.owned.clear();
package/dist/index.d.ts CHANGED
@@ -12,6 +12,9 @@ export * from "./core/guard.js";
12
12
  export * from "./core/host.js";
13
13
  export * from "./core/images.js";
14
14
  export * from "./core/lease.js";
15
+ export * from "./core/page-classifier.js";
16
+ export { isPrivateAddress, pinnedLookup, PUBLIC_MAX_BYTES, publicFetch, type PublicAnswer, type PublicFetchOptions } from "./core/public-fetch.js";
17
+ export { READ_DEADLINE_MS, READ_MAX_CHARS, readPage, type PageRead, type ReadPageOptions } from "./core/read-page.js";
15
18
  export * from "./core/receipts.js";
16
19
  export * from "./core/redact.js";
17
20
  export * from "./core/sites.js";
@@ -19,3 +22,4 @@ export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
19
22
  export * from "./core/tools.js";
20
23
  export * from "./core/usage.js";
21
24
  export * from "./core/web.js";
25
+ export * from "./core/vault.js";
package/dist/index.js CHANGED
@@ -13,6 +13,9 @@ export * from "./core/guard.js";
13
13
  export * from "./core/host.js";
14
14
  export * from "./core/images.js";
15
15
  export * from "./core/lease.js";
16
+ export * from "./core/page-classifier.js";
17
+ export { isPrivateAddress, pinnedLookup, PUBLIC_MAX_BYTES, publicFetch } from "./core/public-fetch.js";
18
+ export { READ_DEADLINE_MS, READ_MAX_CHARS, readPage } from "./core/read-page.js";
16
19
  export * from "./core/receipts.js";
17
20
  export * from "./core/redact.js";
18
21
  export * from "./core/sites.js";
@@ -20,3 +23,4 @@ export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
20
23
  export * from "./core/tools.js";
21
24
  export * from "./core/usage.js";
22
25
  export * from "./core/web.js";
26
+ export * from "./core/vault.js";
@@ -2,7 +2,7 @@ import type { BrowserProvider, Geo, PriceTable, SessionSpec } from "../core/host
2
2
  import { type CdpSession } from "./cdp-call.js";
3
3
  import { type ProfileStore } from "./profiles.js";
4
4
  export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
5
- export { fileProfileStore, type ProfileStore } from "./profiles.js";
5
+ export { fileProfileStore, memoryProfileStore, type ProfileStore } from "./profiles.js";
6
6
  export declare const SEARCH_QUERY_MAX = 200;
7
7
  export declare const SEARCH_RESULTS_MAX = 25;
8
8
  export type BrowserbaseSdk = {
@@ -8,7 +8,7 @@ import { directFetch } from "./http.js";
8
8
  import { claimWriter, fileProfileStore, freeWriter, isWriter, noteWriter } from "./profiles.js";
9
9
  import { accountKey, assertTag, browserbaseHoldings, defaultSleep, DEFAULT_CONFIRM, extensionArchive, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
10
10
  export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
11
- export { fileProfileStore } from "./profiles.js";
11
+ export { fileProfileStore, memoryProfileStore } from "./profiles.js";
12
12
  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. */
@@ -76,6 +76,8 @@ export function browserbaseProvider(options = {}) {
76
76
  const confirm = options.confirm ?? DEFAULT_CONFIRM;
77
77
  const prices = resolvePrices(options.prices);
78
78
  const profiles = options.profiles ?? fileProfileStore();
79
+ /** The context each live session of this provider runs on, by tag: what a session vault may keep. */
80
+ const contexts = new Map();
79
81
  let sdk = null;
80
82
  const client = () => (sdk ??= options.client ? Promise.resolve(options.client) : (async () => {
81
83
  applyBrowserbaseNoProxy(env);
@@ -129,13 +131,20 @@ export function browserbaseProvider(options = {}) {
129
131
  return {
130
132
  name: "browserbase",
131
133
  caps: CAPS,
134
+ vault: { kind: "context", provider: "browserbase", contextIdsInClear: profiles.clear === true, contextOf: (ref) => contexts.get(ref.tag) ?? null },
132
135
  async create(spec, signal) {
133
136
  const projectId = nonEmpty(env.BROWSERBASE_PROJECT_ID);
134
137
  if (spec.profile?.save)
135
138
  await claimWriter(held(`profile:${spec.profile.name}`), spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
139
+ // A context given by id (a vault's kept one) is written back at the end like a profile's: one session at a time saves to it, and the next waits for the write. The id is a capability, so the refusal names no id.
140
+ else if (!spec.profile && spec.contextId)
141
+ await claimWriter(held(`context:${spec.contextId}`), "the kept context", spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
136
142
  let body;
137
143
  try {
138
144
  const context = spec.profile ? { id: await contextFor(spec.profile.name, projectId, signal), persist: spec.profile.save } : undefined;
145
+ const usedContext = context?.id ?? spec.contextId;
146
+ if (usedContext)
147
+ contexts.set(spec.tag, usedContext);
139
148
  // Behind the credential proxy the project is inferred from the injected key and must never be named; a direct key
140
149
  // must name it.
141
150
  body = sessionCreateBody(spec, { extensionId: await extension(), ...(projectId && !baseUrl && !connectBase ? { projectId } : {}), ...(context ? { context } : {}) });
@@ -198,6 +207,7 @@ export function browserbaseProvider(options = {}) {
198
207
  return { sdkCdpUrl: url, ...(connectBase ? { dial: { url: dial } } : {}) };
199
208
  },
200
209
  async release(ref, signal) {
210
+ contexts.delete(ref.tag);
201
211
  await opening.get(held(ref.id));
202
212
  endSetting(held(ref.id));
203
213
  await releaseAndConfirm({
@@ -0,0 +1,28 @@
1
+ import { type CapturedState } from "../core/vault.js";
2
+ export interface CdpLink {
3
+ send(method: string, params?: object, sessionId?: string): Promise<any>;
4
+ on(listener: (event: {
5
+ method?: string;
6
+ params?: any;
7
+ sessionId?: string;
8
+ }) => void): () => void;
9
+ close(): void;
10
+ }
11
+ /** One websocket to the browser (its `sdkCdpUrl`). */
12
+ export declare function connectCdp(url: string, timeoutMs?: number): Promise<CdpLink>;
13
+ /** The allowed origins' cookies and local storage, now. The cookies filtered to the origins before they leave this function. */
14
+ export declare function captureCdpState(link: CdpLink, origins: readonly string[], now?: Date): Promise<Extract<CapturedState, {
15
+ kind: "cdp";
16
+ }>>;
17
+ export type RestoreCounts = {
18
+ cookies: number;
19
+ origins: number;
20
+ droppedExpired: number;
21
+ droppedAged: number;
22
+ droppedOutside: number;
23
+ };
24
+ /** Puts a captured state into a browser that has opened no page yet: cookies first (browser level), then each origin's local storage. Only what
25
+ * the requested origins allow is put back, and a cookie is dropped when it expired, or is a session cookie older than the age cap. Returns counts only. */
26
+ export declare function restoreCdpState(link: CdpLink, state: Extract<CapturedState, {
27
+ kind: "cdp";
28
+ }>, origins: readonly string[], now?: Date, maxSessionCookieAgeMs?: number): Promise<RestoreCounts>;
@@ -0,0 +1,153 @@
1
+ // Capture and restore of a local Chrome's signed-in state over the browser's own DevTools websocket, from the harness side: never through the
2
+ // page facade, never reachable by a model. What is captured is what the host's allowed origins would be sent: the cookies by domain, and
3
+ // each origin's localStorage. It stays in memory and goes to the host's vault port; nothing here logs or returns a value.
4
+ // Local storage needs a frame on its origin: a short-lived target is made at the origin and every request it makes is answered locally
5
+ // (Fetch.fulfillRequest with an empty document), so nothing goes to the network and no script of the site runs.
6
+ import { clampSessionCookieAgeMs, cookieKept, vaultOrigins } from "../core/vault.js";
7
+ /** One websocket to the browser (its `sdkCdpUrl`). */
8
+ export async function connectCdp(url, timeoutMs = 10_000) {
9
+ const socket = new WebSocket(url);
10
+ // A socket nobody receives is closed: a handshake that finishes after the deadline, or a setup that fails, leaves no connection open.
11
+ try {
12
+ await new Promise((resolve, reject) => {
13
+ const timer = setTimeout(() => reject(new Error("the browser did not open its DevTools socket")), timeoutMs);
14
+ socket.onopen = () => { clearTimeout(timer); resolve(); };
15
+ socket.onerror = () => { clearTimeout(timer); reject(new Error("the browser's DevTools socket failed")); };
16
+ });
17
+ }
18
+ catch (error) {
19
+ try {
20
+ socket.close();
21
+ }
22
+ catch { /* already closed */ }
23
+ throw error;
24
+ }
25
+ let next = 0;
26
+ const waiting = new Map();
27
+ const listeners = new Set();
28
+ socket.onmessage = (message) => {
29
+ let data;
30
+ try {
31
+ data = JSON.parse(String(message.data));
32
+ }
33
+ catch {
34
+ return;
35
+ }
36
+ if (data.id !== undefined && waiting.has(data.id)) {
37
+ const wait = waiting.get(data.id);
38
+ waiting.delete(data.id);
39
+ if (data.error)
40
+ wait.reject(new Error(String(data.error.message ?? "refused")));
41
+ else
42
+ wait.resolve(data.result);
43
+ }
44
+ else
45
+ for (const listener of listeners)
46
+ listener(data);
47
+ };
48
+ socket.onclose = () => { for (const wait of waiting.values())
49
+ wait.reject(new Error("the DevTools socket closed")); waiting.clear(); };
50
+ return {
51
+ send: (method, params = {}, sessionId) => new Promise((resolve, reject) => {
52
+ const id = ++next;
53
+ const timer = setTimeout(() => { waiting.delete(id); reject(new Error(`the browser did not answer ${method}`)); }, 15_000);
54
+ waiting.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v); }, reject: (e) => { clearTimeout(timer); reject(e); } });
55
+ socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
56
+ }),
57
+ on: (listener) => { listeners.add(listener); return () => listeners.delete(listener); },
58
+ close: () => socket.close(),
59
+ };
60
+ }
61
+ const EMPTY_DOCUMENT = btoa("<!doctype html><title></title>");
62
+ const PATH = "/__pi-browser-vault__";
63
+ /** Runs `use` with a session on a page at `origin` whose every request to that origin was answered locally. */
64
+ async function atOrigin(link, origin, use) {
65
+ const { targetId } = await link.send("Target.createTarget", { url: "about:blank" });
66
+ try {
67
+ const { sessionId } = await link.send("Target.attachToTarget", { targetId, flatten: true });
68
+ const send = (method, params) => link.send(method, params, sessionId);
69
+ const stop = link.on((event) => {
70
+ if (event.sessionId === sessionId && event.method === "Fetch.requestPaused") {
71
+ void send("Fetch.fulfillRequest", { requestId: event.params.requestId, responseCode: 200, responseHeaders: [{ name: "content-type", value: "text/html" }], body: EMPTY_DOCUMENT }).catch(() => undefined);
72
+ }
73
+ });
74
+ try {
75
+ await send("Page.enable");
76
+ await send("Fetch.enable", { patterns: [{ urlPattern: `${origin}/*` }] });
77
+ const loaded = new Promise((resolve) => { const off = link.on((event) => { if (event.sessionId === sessionId && event.method === "Page.loadEventFired") {
78
+ off();
79
+ resolve();
80
+ } }); setTimeout(() => { off(); resolve(); }, 8000); });
81
+ await send("Page.navigate", { url: `${origin}${PATH}` });
82
+ await loaded;
83
+ await send("DOMStorage.enable");
84
+ return await use(send);
85
+ }
86
+ finally {
87
+ stop();
88
+ }
89
+ }
90
+ finally {
91
+ await link.send("Target.closeTarget", { targetId }).catch(() => undefined);
92
+ }
93
+ }
94
+ const toVaultCookie = (cookie) => ({
95
+ name: cookie.name, value: cookie.value, domain: cookie.domain, path: cookie.path ?? "/",
96
+ ...(cookie.session || !(cookie.expires > 0) ? {} : { expires: cookie.expires }),
97
+ httpOnly: cookie.httpOnly === true, secure: cookie.secure === true,
98
+ ...(cookie.sameSite === "Strict" || cookie.sameSite === "Lax" || cookie.sameSite === "None" ? { sameSite: cookie.sameSite } : {}),
99
+ });
100
+ /** The allowed origins' cookies and local storage, now. The cookies filtered to the origins before they leave this function. */
101
+ export async function captureCdpState(link, origins, now = new Date()) {
102
+ const allowed = vaultOrigins(origins);
103
+ const { cookies } = await link.send("Storage.getCookies", {});
104
+ const kept = cookies.filter((cookie) => cookieKept(cookie, allowed)).map(toVaultCookie);
105
+ const localStorage = {};
106
+ for (const origin of allowed) {
107
+ const entries = await atOrigin(link, origin, async (send) => (await send("DOMStorage.getDOMStorageItems", { storageId: { securityOrigin: origin, isLocalStorage: true } })).entries);
108
+ if (entries.length)
109
+ localStorage[origin] = Object.fromEntries(entries);
110
+ }
111
+ return { kind: "cdp", capturedAt: now.toISOString(), cookies: kept, localStorage };
112
+ }
113
+ /** Puts a captured state into a browser that has opened no page yet: cookies first (browser level), then each origin's local storage. Only what
114
+ * the requested origins allow is put back, and a cookie is dropped when it expired, or is a session cookie older than the age cap. Returns counts only. */
115
+ export async function restoreCdpState(link, state, origins, now = new Date(), maxSessionCookieAgeMs) {
116
+ const allowed = vaultOrigins(origins);
117
+ const cap = clampSessionCookieAgeMs(maxSessionCookieAgeMs);
118
+ const counts = { cookies: 0, origins: 0, droppedExpired: 0, droppedAged: 0, droppedOutside: 0 };
119
+ const capturedAt = Date.parse(state.capturedAt);
120
+ const params = [];
121
+ for (const cookie of state.cookies) {
122
+ if (!cookieKept(cookie, allowed)) {
123
+ counts.droppedOutside += 1;
124
+ continue;
125
+ }
126
+ if (cookie.expires !== undefined) {
127
+ if (cookie.expires * 1000 <= now.getTime()) {
128
+ counts.droppedExpired += 1;
129
+ continue;
130
+ }
131
+ }
132
+ else if (!Number.isFinite(capturedAt) || now.getTime() - capturedAt > cap) {
133
+ counts.droppedAged += 1;
134
+ continue;
135
+ }
136
+ params.push({ name: cookie.name, value: cookie.value, domain: cookie.domain, path: cookie.path, secure: cookie.secure, httpOnly: cookie.httpOnly, ...(cookie.sameSite ? { sameSite: cookie.sameSite } : {}), ...(cookie.expires !== undefined ? { expires: cookie.expires } : {}) });
137
+ }
138
+ if (params.length)
139
+ await link.send("Storage.setCookies", { cookies: params });
140
+ counts.cookies = params.length;
141
+ for (const origin of allowed) {
142
+ const items = state.localStorage[origin];
143
+ if (!items || !Object.keys(items).length)
144
+ continue;
145
+ await atOrigin(link, origin, async (send) => { for (const [key, value] of Object.entries(items))
146
+ await send("DOMStorage.setDOMStorageItem", { storageId: { securityOrigin: origin, isLocalStorage: true }, key, value }); });
147
+ counts.origins += 1;
148
+ }
149
+ for (const origin of Object.keys(state.localStorage))
150
+ if (!allowed.includes(origin))
151
+ counts.droppedOutside += 1;
152
+ return counts;
153
+ }
@@ -5,6 +5,8 @@ export type CdpOptions =
5
5
  {
6
6
  endpoint: string;
7
7
  extensionId?: string;
8
+ /** The host asserts this endpoint is the run's OWN browser (the launcher that owns its process and its stop started it for this run alone), not one other runs or people share. Only then is a session of it offered to a session vault. Never set it for a shared browser. */
9
+ ownBrowser?: boolean;
8
10
  }
9
11
  /** Start Chrome under `profileRoot/<tag>` on a loopback port Chrome picks; release kills that process by exact pid. */
10
12
  | {
@@ -16,6 +18,10 @@ export type CdpOptions =
16
18
  /** Chrome's own sandbox, on unless `false`; absent, `PI_BROWSER_NO_SANDBOX=1` turns it off. Turn it off only where
17
19
  * Chrome cannot start its sandbox (root, a container, confined user namespaces), never because a run is in CI. */
18
20
  sandbox?: boolean;
21
+ /** The extension this Chrome is given is a copy whose pages and worker may connect to nothing but the browser's own DevTools
22
+ * socket (default true). `false` gives Stagehand's own directory, unconfined: for tests of the layer beneath. Without a private
23
+ * TMPDIR for the lease (Windows, a long temp path) the extension is Stagehand's own either way. */
24
+ confineExtension?: boolean;
19
25
  };
20
26
  };
21
27
  /** 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
@@ -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),