@parcha/pi-browser 0.1.0-beta.27 → 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
@@ -2,7 +2,7 @@ import { defineExtension, type ConversationId, type ToolRegistration } from "@ea
2
2
  import type { Decisions } from "../core/decisions.js";
3
3
  import type { EvidenceSink } from "../core/evidence.js";
4
4
  import type { FetchRequest, FetchResult, PriceTable, SearchRequest, SearchResult } from "../core/host.js";
5
- import { type RenderedPage, type WebBackup, type WebToolsOptions } from "../core/web.js";
5
+ import { type FetchSource, type RenderedPage, type SearchSource, type WebBackup, type WebToolsOptions } from "../core/web.js";
6
6
  export type WebExtensionOptions = {
7
7
  providers: {
8
8
  /** Names the source in `via` (`<name>_fetch`, `<name>_search`); default "provider". */
@@ -10,6 +10,10 @@ export type WebExtensionOptions = {
10
10
  fetch?: (request: FetchRequest, signal?: AbortSignal) => Promise<FetchResult>;
11
11
  search?: (request: SearchRequest, signal?: AbortSignal) => Promise<SearchResult>;
12
12
  };
13
+ /** Searches tried before `providers.search`, in order (see `SearchSource`). */
14
+ searchSources?: readonly SearchSource[];
15
+ /** Readers tried before `providers.fetch` for a markdown read, in order (see `FetchSource`). */
16
+ fetchSources?: readonly FetchSource[];
13
17
  evidence: EvidenceSink;
14
18
  /** Per use: evidence label and proxies. Default: label "web", proxies on. */
15
19
  scope?: (conversationId: ConversationId) => {
@@ -31,6 +35,8 @@ export type WebExtensionOptions = {
31
35
  read(url: string, signal?: AbortSignal): Promise<RenderedPage>;
32
36
  };
33
37
  pdf?: WebToolsOptions["pdf"];
38
+ /** How long the screening of a search answer's snippets may take in all (see `WebToolsOptions`). */
39
+ snippetScreenMs?: number;
34
40
  section?: {
35
41
  addendum?: string;
36
42
  };
@@ -9,6 +9,8 @@ export function createWebExtension(options) {
9
9
  name: options.providers.name ?? "provider",
10
10
  fetch: options.providers.fetch,
11
11
  search: options.providers.search,
12
+ searchSources: options.searchSources,
13
+ fetchSources: options.fetchSources,
12
14
  evidence: options.evidence,
13
15
  scope: options.scope ?? (() => ({ label: "web", proxies: true })),
14
16
  prices: options.prices,
@@ -17,11 +19,12 @@ export function createWebExtension(options) {
17
19
  classifyPage: options.decisions?.classifyPage,
18
20
  render: options.render,
19
21
  pdf: options.pdf,
22
+ snippetScreenMs: options.snippetScreenMs,
20
23
  });
21
24
  const run = { web_fetch: tools.fetch, web_search: tools.search };
22
25
  const result = ({ text, isError, details, usd }) => ({ ...forModel([{ type: "text", text }]), isError, details: details, usage: toolUsage(usd).usage });
23
26
  const registrations = WEB_TOOLS
24
- .filter((tool) => (tool.listedWhen === "fetch" ? options.providers.fetch || options.render?.enabled || options.backups?.length : options.providers.search))
27
+ .filter((tool) => (tool.listedWhen === "fetch" ? options.providers.fetch || options.render?.enabled || options.backups?.length || options.fetchSources?.length : options.providers.search || options.searchSources?.length))
25
28
  .map((tool) => defineTool({
26
29
  name: tool.name,
27
30
  description: tool.description,
package/dist/durable.d.ts CHANGED
@@ -4,12 +4,13 @@ import { type DriverFactory } from "./core/custody.js";
4
4
  import type { Decisions } from "./core/decisions.js";
5
5
  import type { EvidenceSink } from "./core/evidence.js";
6
6
  import { EffectObserver } from "./core/effects.js";
7
+ import { type VaultOptions } from "./vault-session.js";
7
8
  import type { DrivingGates } from "./live-view/protocol.js";
8
9
  import { type BrowserToolImpls, type PageDriver } from "./core/tools.js";
9
10
  import type { BrowserConfig, BrowserProvider, InventoryRow, ObserverRow, PriceTable, ReconcileReport, ReleaseReason, SessionChange, SessionRow, SessionsState, SiteInfo, SiteRunPort, HandoffPort, WorkspaceFiles } from "./core/host.js";
10
11
  export type { BrowserToolArgs, BrowserToolImpls, PageDriver, ToolCall, ToolImpl } from "./core/tools.js";
11
12
  export type { DriverFactory, DriverOptions } from "./core/custody.js";
12
- export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = {
13
+ export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = VaultOptions & {
13
14
  /** Default "browser"; a second plane installs a second extension under another name. */
14
15
  name?: string;
15
16
  /** Called per use: the provider for this conversation's plane. Holds the credentials in its closure; nothing it
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,7 @@ 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 { isPrivateAddress, pinnedLookup, PUBLIC_MAX_BYTES, publicFetch, readPage, type PublicAnswer, type PublicFetchOptions } from "./core/public-fetch.js";
15
16
  export * from "./core/receipts.js";
16
17
  export * from "./core/redact.js";
17
18
  export * from "./core/sites.js";
@@ -19,3 +20,4 @@ export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
19
20
  export * from "./core/tools.js";
20
21
  export * from "./core/usage.js";
21
22
  export * from "./core/web.js";
23
+ export * from "./core/vault.js";
package/dist/index.js CHANGED
@@ -13,6 +13,7 @@ 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 { isPrivateAddress, pinnedLookup, PUBLIC_MAX_BYTES, publicFetch, readPage } from "./core/public-fetch.js";
16
17
  export * from "./core/receipts.js";
17
18
  export * from "./core/redact.js";
18
19
  export * from "./core/sites.js";
@@ -20,3 +21,4 @@ export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
20
21
  export * from "./core/tools.js";
21
22
  export * from "./core/usage.js";
22
23
  export * from "./core/web.js";
24
+ 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