@parcha/pi-browser 0.1.0-beta.14 → 0.1.0-beta.16

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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,11 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.1.0-beta.15 (2026-10-16)
6
+
7
+ - `@parcha/pi-browser`: a session can ask for a named saved profile. `SessionSpec` and `BrowserPolicy` take `profile: { name, save }`, `ProviderCaps` gains `profiles`, and the session record names the profile (the name only; older records read as none). The local Chrome (`cdp`) keeps a named profile in its own directory, and a session can work from a copy that is never saved; Kernel keeps one through its own profiles (created on first use, one saver per profile); Browserbase keeps one as a context made on first use and remembered by name. A provider that cannot keep a profile, a profile beside a context id and a bad name are refused with the typed envelope before any session or record is made. A host can pass an optional `crossing` callback that is called at the two page-action moments a kill sweep needs (after one page action's answer is committed and before the next is dispatched; after a page action's driver call returned and before its answer is committed). `use_website` calls in one turn now run at once, each child in its own browser. `browser_release` on a session that already ended, or is ending, answers `already_released: { reason, at }` and one sentence beside `released`, which keeps its meaning.
8
+ - `@parcha/pi-browser`: a `snapshot` or `browser_read` that lands in a document a navigation replaced waits for the new one and reads once more, instead of failing with Chrome's "Cannot find context with specified id". The held-runtime reset (Stagehand's extension) fails on a target list the browser never gives, instead of reading it as "nothing held", and closes its last wake page before the socket goes, so a runtime still held no longer refuses the next attach. `exportFrameTracks` bounds each blob read by the session's deadline and the abort signal.
9
+
5
10
  ## 0.1.0-beta.14 (2026-10-16)
6
11
 
7
12
  - Accept pi 1.3: the `@earendil-works/pi-durable` and `@earendil-works/chord` peer ranges now end below 1.4, with the floors unchanged (1.0.4, and 1.1.0 for `@parcha/pi-browser`). pi 1.3.0 pins its own packages to exact versions, so an install is all 1.2 or all 1.3; CI runs every package's whole suite on a 1.3.0 family as well as on 1.2.0.
package/README.md CHANGED
@@ -28,6 +28,8 @@ Stagehand, undici, zod and the two HTML packages are dependencies. Four optional
28
28
 
29
29
  The pi peers are `@earendil-works/pi-durable` and `chord` `>=1.1.0 <1.4.0`, and `@earendil-works/pi-coding-agent` at any version, as pi's package guidance asks of the packages it supplies. The suite passes on pi 1.1, 1.2 and 1.3, and the coding-agent entry's tests also pass on a pi 1.0.4 family.
30
30
 
31
+ pi 1.0.4 or 1.1.x users: pin `@earendil-works/pi-codemode` to the same version as `@earendil-works/pi-coding-agent` (`@1.0.4`, or `@1.1.0`), because pi-codemode 1.2.0 removed an export those versions import, or use pi 1.2.
32
+
31
33
  ## Quick start
32
34
 
33
35
  A local Chrome, one page, one snapshot. It needs Chrome or Chromium; `CHROME_PATH` names it.
@@ -32,6 +32,8 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
32
32
  private live;
33
33
  /** Browsers that are gone whose directories are not: each is released again as cleanup, never kept as the live session. */
34
34
  private leftovers;
35
+ /** The last session this custody released, so a release asked after it can say how and when it ended. */
36
+ private lastReleased;
35
37
  private seq;
36
38
  private notice;
37
39
  private readonly queue;
@@ -62,6 +64,10 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
62
64
  release(): Promise<{
63
65
  released: boolean;
64
66
  sessionId: string | null;
67
+ ended?: {
68
+ reason: ReleaseReason;
69
+ at: string | null;
70
+ };
65
71
  }>;
66
72
  /** Releases without failing the caller; idempotent. */
67
73
  close(reason: ReleaseReason): Promise<void>;
@@ -4,7 +4,7 @@ import { mkdtemp, rm } from "node:fs/promises";
4
4
  import os from "node:os";
5
5
  import path from "node:path";
6
6
  import { BROWSER_TOOLS, WEB_TOOLS, browserSection } from "./core/contract.js";
7
- import { BrowserFailureError, closeDriver, custodyTools, newSessionRecord, notices, sessionSpec, } from "./core/custody.js";
7
+ import { BrowserFailureError, closeDriver, custodyTools, newSessionRecord, notices, profileRefusal, sessionSpec, } from "./core/custody.js";
8
8
  import { browserFailure, classifyBrowserError } from "./core/failures.js";
9
9
  import { leaseTag } from "./core/lease.js";
10
10
  import { createRedactor, redactDeep, scrubPageUrl } from "./core/redact.js";
@@ -26,6 +26,8 @@ export class LocalCustody {
26
26
  live = null;
27
27
  /** Browsers that are gone whose directories are not: each is released again as cleanup, never kept as the live session. */
28
28
  leftovers = [];
29
+ /** The last session this custody released, so a release asked after it can say how and when it ended. */
30
+ lastReleased = null;
29
31
  seq = 0;
30
32
  notice = null;
31
33
  queue = keyedSerializer();
@@ -41,7 +43,7 @@ export class LocalCustody {
41
43
  return this.queue.run(this.d.config.label, run);
42
44
  }
43
45
  save(record) {
44
- this.d.keep(SESSION_ENTRY, { tag: record.tag, resourceId: record.resourceId, state: record.state, reason: record.releaseReason });
46
+ this.d.keep(SESSION_ENTRY, { tag: record.tag, resourceId: record.resourceId, state: record.state, reason: record.releaseReason, ...(record.endedAt ? { endedAt: record.endedAt } : {}) });
45
47
  }
46
48
  failure(error, signal) {
47
49
  return error instanceof BrowserFailureError ? error : new BrowserFailureError(classifyBrowserError(error, false, { aborted: signal?.aborted === true }));
@@ -84,6 +86,9 @@ export class LocalCustody {
84
86
  const provider = await this.d.provider();
85
87
  const tag = leaseTag("pib", this.d.config.run, randomUUID().slice(0, 8), ++this.seq);
86
88
  const spec = sessionSpec(this.d.config, tag, overrides);
89
+ const unsupported = profileRefusal(spec, provider.caps);
90
+ if (unsupported)
91
+ throw new BrowserFailureError(unsupported);
87
92
  const record = newSessionRecord({ plane: "browser", tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
88
93
  this.save(record);
89
94
  const signal = AbortSignal.any([this.d.signal, AbortSignal.timeout(CREATE_DEADLINE_MS)]);
@@ -106,7 +111,8 @@ export class LocalCustody {
106
111
  if (!(await provider.release(ref).then(() => true, () => false)))
107
112
  released = false;
108
113
  if (released) {
109
- Object.assign(record, { state: "released", releaseReason: "create_failed" });
114
+ Object.assign(record, { state: "released", releaseReason: "create_failed", endedAt: now() });
115
+ this.lastReleased = record;
110
116
  this.save(record);
111
117
  }
112
118
  throw this.failure(error, signal);
@@ -131,13 +137,15 @@ export class LocalCustody {
131
137
  this.live = null;
132
138
  live.driver = null;
133
139
  Object.assign(live.record, { state: "releasing", releaseReason: reason });
140
+ this.lastReleased = live.record;
134
141
  this.save(live.record);
135
142
  this.leftovers.push(live);
136
143
  throw this.failure(error);
137
144
  }
138
145
  if (this.live === live)
139
146
  this.live = null;
140
- Object.assign(live.record, { state: "released", releaseReason: reason });
147
+ Object.assign(live.record, { state: "released", releaseReason: reason, endedAt: now() });
148
+ this.lastReleased = live.record;
141
149
  this.save(live.record);
142
150
  }
143
151
  /** Releases again each browser that is gone and whose directory was left; one that still cannot be removed stays for the next time, and the
@@ -154,7 +162,7 @@ export class LocalCustody {
154
162
  stillLeft = error;
155
163
  continue;
156
164
  }
157
- Object.assign(live.record, { state: "released" });
165
+ Object.assign(live.record, { state: "released", endedAt: now() });
158
166
  this.save(live.record);
159
167
  }
160
168
  return stillLeft;
@@ -185,14 +193,15 @@ export class LocalCustody {
185
193
  release() {
186
194
  return this.serial(async () => {
187
195
  const live = this.live;
188
- if (live)
196
+ if (live) {
189
197
  await this.finish(live, "tool");
190
- else {
191
- const stillLeft = await this.sweepLeftovers();
192
- if (stillLeft)
193
- throw this.failure(stillLeft);
194
- } // no browser, but a directory an earlier release left
195
- return { released: !!live, sessionId: live?.ref.id ?? null };
198
+ return { released: true, sessionId: live.ref.id };
199
+ }
200
+ const stillLeft = await this.sweepLeftovers(); // no browser, but a directory an earlier release left
201
+ if (stillLeft)
202
+ throw this.failure(stillLeft);
203
+ const last = this.lastReleased;
204
+ return last ? { released: false, sessionId: last.resourceId, ended: { reason: last.releaseReason ?? "tool", at: last.endedAt } } : { released: false, sessionId: null };
196
205
  });
197
206
  }
198
207
  /** Releases without failing the caller; idempotent. */
@@ -342,6 +351,9 @@ export function createBrowserExtension(options = {}) {
342
351
  let opening = null;
343
352
  let webSearchRegistered = false;
344
353
  let sitesRegistered = false;
354
+ // Children on one existing browser (--browser-endpoint) would drive the same pages, so there they take turns.
355
+ let turn = Promise.resolve();
356
+ const inTurn = (run) => { const mine = turn.then(run, run); turn = mine.catch(() => undefined); return mine; };
345
357
  pi.registerFlag("browser-provider", { type: "string", description: "Browser provider: cdp (a local Chrome, the default), browserbase (needs BROWSERBASE_API_KEY) or kernel (needs KERNEL_API_KEY)" });
346
358
  pi.registerFlag("browser-endpoint", { type: "string", description: "Attach to a Chrome DevTools endpoint (http://host:port or ws://...) instead of starting Chrome" });
347
359
  pi.registerFlag("browser-chrome", { type: "string", description: "Path to the Chrome or Chromium to start" });
@@ -432,7 +444,10 @@ export function createBrowserExtension(options = {}) {
432
444
  annotations: { readOnlyHint: false, openWorldHint: true },
433
445
  async execute(_callId, params, signal, _onUpdate, ctx) {
434
446
  const rt = await runtimeOf(ctx);
435
- const out = await useWebsite(params, port, listing, { signal: signal ?? new AbortController().signal, runChild: (task, childSignal) => childSession(ctx, task.prompt, childSignal) });
447
+ const out = await useWebsite(params, port, listing, { signal: signal ?? new AbortController().signal, runChild: (task, childSignal) => {
448
+ const run = () => childSession(ctx, task.prompt, childSignal);
449
+ return flagOf(pi, "browser-endpoint", env.PI_BROWSER_ENDPOINT) ? inTurn(run) : run();
450
+ } });
436
451
  return { content: out.content.map((item) => item.type === "text" ? { ...item, text: rt.redact(item.text) } : item), details: undefined, ...(out.isError ? { isError: true } : {}) };
437
452
  },
438
453
  });
@@ -38,9 +38,14 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
38
38
  /** A rerun finds the session it launched. */
39
39
  relaunch(overrides: Overrides): Promise<AttachedSession<D>>;
40
40
  /** No session, or one already released, is not an error. */
41
+ /** `ended`: the session was released, or is being released, before this call: by what and when (null while in flight). */
41
42
  release(): Promise<{
42
43
  released: boolean;
43
44
  sessionId: string | null;
45
+ ended?: {
46
+ reason: ReleaseReason;
47
+ at: string | null;
48
+ };
44
49
  }>;
45
50
  /** Committed before the `run` is dispatched. */
46
51
  dispatching(effect: {
@@ -102,7 +107,9 @@ export declare function moveRecord(record: SessionRecord, next: {
102
107
  reason?: ReleaseReason;
103
108
  at: string;
104
109
  }): void;
110
+ export declare const PROFILE_NAME: RegExp;
105
111
  export declare function sessionSpec(config: BrowserConfig, tag: string, overrides?: Overrides): SessionSpec;
112
+ export declare function profileRefusal(spec: SessionSpec, caps: ProviderCaps): BrowserFailure | null;
106
113
  /** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
107
114
  * silently. */
108
115
  export declare function relaunchRefusal(policy: BrowserConfig["policy"], overrides: Overrides): BrowserFailure | null;
@@ -38,7 +38,7 @@ export function newSessionRecord(input) {
38
38
  settings: {
39
39
  proxies, verified: spec.verified && honours.verified !== false,
40
40
  geolocation: proxies && honours.geolocation !== false && typeof spec.proxies === "object" ? spec.proxies.geolocation : null,
41
- region: honours.region === false ? null : spec.region ?? null, contextId: honours.context === false ? null : spec.contextId ?? null,
41
+ region: honours.region === false ? null : spec.region ?? null, contextId: honours.context === false ? null : spec.contextId ?? null, profile: spec.profile?.name ?? null,
42
42
  },
43
43
  navigation: [], lastUrl: null, pendingEffect: null, spent: startSpent(input.at),
44
44
  };
@@ -56,8 +56,14 @@ export function moveRecord(record, next) {
56
56
  if (next.state === "released" || next.state === "lost")
57
57
  record.endedAt = next.at;
58
58
  }
59
+ export const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
60
+ const refused = (message) => ({ ok: false, code: "refused", retryable: false, effect: "none", message });
59
61
  export function sessionSpec(config, tag, overrides = {}) {
60
62
  const { policy } = config;
63
+ if (policy.profile && !PROFILE_NAME.test(policy.profile.name))
64
+ throw new BrowserFailureError(refused("browser profile: a profile name is 1 to 64 characters of letters, digits, dot, underscore and dash, starting with a letter or digit. No session was started."));
65
+ if (policy.profile && policy.contextId)
66
+ throw new BrowserFailureError(refused("browser profile: a saved profile and a context id are two ways to ask for the same saved state; set one. No session was started."));
61
67
  const geolocation = overrides.geolocation === undefined ? policy.geolocation : overrides.geolocation;
62
68
  return {
63
69
  tag, maxLifetimeS: policy.sessionTimeoutS, idleTimeoutS: policy.idleReleaseS,
@@ -66,10 +72,14 @@ export function sessionSpec(config, tag, overrides = {}) {
66
72
  ...(policy.region ? { region: policy.region } : {}),
67
73
  viewport: { ...VIEWPORT },
68
74
  ...(policy.contextId ? { contextId: policy.contextId } : {}),
75
+ ...(policy.profile ? { profile: { name: policy.profile.name, save: policy.profile.save } } : {}),
69
76
  ...(policy.navigation ? { navigation: policy.navigation } : {}),
70
77
  metadata: { run: config.run, label: config.label },
71
78
  };
72
79
  }
80
+ export function profileRefusal(spec, caps) {
81
+ return spec.profile && !caps.profiles ? refused(`browser profile: this browser provider cannot keep a saved sign-in, so profile "${spec.profile.name}" cannot be used. No session was started.`) : null;
82
+ }
73
83
  /** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
74
84
  * silently. */
75
85
  export function relaunchRefusal(policy, overrides) {
@@ -103,8 +113,11 @@ const failed = (error) => {
103
113
  export const custodyTools = {
104
114
  async browser_release(_args, port) {
105
115
  try {
106
- const { released, sessionId } = await port.release();
107
- return text({ ok: true, released, session_id: sessionId, ...(sessionId === null ? { note: "no open browser session" } : {}) });
116
+ const { released, sessionId, ended } = await port.release();
117
+ const note = ended
118
+ ? `The session was already ${ended.at ? `released (${ended.reason}, at ${ended.at})` : `being released (${ended.reason})`} before this call; there was nothing more to release.`
119
+ : sessionId === null ? "no open browser session" : null;
120
+ return text({ ok: true, released, session_id: sessionId, ...(ended ? { already_released: ended } : {}), ...(note ? { note } : {}) });
108
121
  }
109
122
  catch (error) {
110
123
  return failed(error);
@@ -23,6 +23,7 @@ export type DownloadsResult = {
23
23
  };
24
24
  /** A name that stays inside `downloads/`: the last path segment, no control characters, not hidden, not the manifest. */
25
25
  export declare function safeDownloadName(remote: string): string;
26
+ export declare function withLock<T>(file: string, run: () => Promise<T>, what?: string): Promise<T>;
26
27
  /** Skips what the workspace already holds; one failing file is skipped with its reason. */
27
28
  export declare function fetchDownloads(options: {
28
29
  provider: Pick<BrowserProvider, "downloads">;
@@ -19,7 +19,7 @@ const sameRemote = (row, session, file) => row.session === session && row.remote
19
19
  const exists = (file) => stat(file).then((s) => s.isFile(), () => false);
20
20
  const hashOf = async (file) => createHash("sha256").update(await readFile(file)).digest("hex");
21
21
  const withRow = (rows, row) => [...rows.filter((r) => r.path !== row.path || (r.sha256 === row.sha256 && !(r.session === row.session && r.remote.name === row.remote.name))), row];
22
- async function withLock(file, run) {
22
+ export async function withLock(file, run, what = "downloads/manifest.json") {
23
23
  for (const deadline = Date.now() + 10_000;; await new Promise((r) => setTimeout(r, 25 + Math.random() * 50))) {
24
24
  try {
25
25
  await (await open(file, "wx")).close();
@@ -31,7 +31,7 @@ async function withLock(file, run) {
31
31
  if (Date.now() - (await stat(file).then((s) => s.mtimeMs, () => Date.now())) > 30_000)
32
32
  await rm(file, { force: true });
33
33
  else if (Date.now() > deadline)
34
- throw new Error("downloads/manifest.json is locked by another fetch");
34
+ throw new Error(`${what} is locked by another writer`);
35
35
  }
36
36
  }
37
37
  try {
@@ -29,6 +29,11 @@ export type BrowserConfig = {
29
29
  run: string;
30
30
  policy: BrowserPolicy;
31
31
  };
32
+ /** A named saved sign-in; `save` keeps the session's changes. One saver per profile within a process; across processes the last to end wins. */
33
+ export type SavedProfile = {
34
+ name: string;
35
+ save: boolean;
36
+ };
32
37
  export type BrowserPolicy = {
33
38
  proxies: boolean;
34
39
  verified: boolean;
@@ -36,6 +41,7 @@ export type BrowserPolicy = {
36
41
  geolocation: Geo | null;
37
42
  region: string | null;
38
43
  contextId: string | null;
44
+ profile?: SavedProfile;
39
45
  sessionTimeoutS: number;
40
46
  idleReleaseS: number;
41
47
  batchTimeoutMs: number;
@@ -61,6 +67,7 @@ export type SessionSpec = {
61
67
  height: number;
62
68
  };
63
69
  contextId?: string;
70
+ profile?: SavedProfile;
64
71
  navigation?: {
65
72
  allow?: string[];
66
73
  block?: string[];
@@ -82,6 +89,7 @@ export type ProviderCaps = {
82
89
  maxLifetimeS: number;
83
90
  survivesDisconnect: boolean;
84
91
  releaseIsAsync: boolean;
92
+ profiles: boolean;
85
93
  extension: "uploaded-per-launch" | "preinstalled" | "loaded-locally";
86
94
  /** The session settings this provider applies; a setting left out is applied. */
87
95
  settings?: Partial<SessionSettingsSupport>;
@@ -212,6 +220,7 @@ export type SessionRecord = {
212
220
  geolocation: Geo | null;
213
221
  region: string | null;
214
222
  contextId: string | null;
223
+ profile: string | null;
215
224
  };
216
225
  /** Every page the session moved to, in order; the last 500 kept. */
217
226
  navigation: Array<{
@@ -12,6 +12,7 @@ export function useWebsiteContract(sites) {
12
12
  "Hand a task to an agent that works on one of these websites in its own browser, and get back what it found or did:",
13
13
  ...sites.map((site) => `- ${site.site}: ${site.title}. ${site.description}`),
14
14
  "Give a new request_id (a UUID) for each new task. Calling again with the request_id of a finished task answers its result without running it again; a task that failed runs again, and may repeat what it already did on the site.",
15
+ "Several calls in one turn run at once, each agent in its own browser.",
15
16
  ].join("\n"),
16
17
  parameters: {
17
18
  type: "object", additionalProperties: false, required: ["site", "request_id", "instructions"],
@@ -21,7 +22,7 @@ export function useWebsiteContract(sites) {
21
22
  instructions: { type: "string", maxLength: MAX_SITE_INSTRUCTIONS, description: "What to do on the website and what to report back." },
22
23
  },
23
24
  },
24
- effect: "effect", replay: "safe", executionMode: "sequential", evidence: "none", listedWhen: "sites",
25
+ effect: "effect", replay: "safe", executionMode: "parallel", evidence: "none", listedWhen: "sites",
25
26
  };
26
27
  }
27
28
  /** Only the declared shape crosses back to the model: a port's extra fields, such as capabilities or URLs, are dropped
@@ -2,5 +2,6 @@ export declare const STAGEHAND_EXTENSION = "Stagehand Runtime";
2
2
  /** A held extension runtime keeps one Stagehand instance until that instance's close, which a dead process never sent,
3
3
  * so a new attach would be refused. The close is sent here through the worker's own RPC, and the worker keeps running:
4
4
  * a worker closed under load is sometimes never restarted, and its attach waits out Stagehand's 60 s init deadline.
5
- * With no worker running nothing is held, and the worker is woken until it is listed. */
5
+ * With no worker running nothing is held, and the worker is woken until it is listed. A target list the browser does
6
+ * not give by DISCOVERY_MS is not a list without a worker: the attach fails. */
6
7
  export declare function installedExtension(cdpUrl: string, signal?: AbortSignal, known?: string): Promise<string | null>;
@@ -1,29 +1,41 @@
1
1
  export const STAGEHAND_EXTENSION = "Stagehand Runtime";
2
2
  const DISCOVERY_MS = 10_000;
3
+ /** Kept past the deadline so the last wake page is closed on the same socket. */
4
+ const CLEANUP_MS = 1_000;
3
5
  const WAKE_TRIES = 60;
4
6
  const CLOSE_REPLY_MS = 3_000;
5
7
  const SEND_TO_HOST = "__stagehandSendToHost";
6
8
  const RESET_ID = 2_147_000_000;
9
+ /** The browser did not list its targets by the deadline, so a runtime it may hold could not be freed. */
10
+ class TargetsUnlistedError extends Error {
11
+ constructor() { super(`the browser did not list its targets within ${DISCOVERY_MS} ms, so a Stagehand runtime it may hold could not be freed`); }
12
+ }
7
13
  /** A held extension runtime keeps one Stagehand instance until that instance's close, which a dead process never sent,
8
14
  * so a new attach would be refused. The close is sent here through the worker's own RPC, and the worker keeps running:
9
15
  * a worker closed under load is sometimes never restarted, and its attach waits out Stagehand's 60 s init deadline.
10
- * With no worker running nothing is held, and the worker is woken until it is listed. */
16
+ * With no worker running nothing is held, and the worker is woken until it is listed. A target list the browser does
17
+ * not give by DISCOVERY_MS is not a list without a worker: the attach fails. */
11
18
  export async function installedExtension(cdpUrl, signal, known) {
12
19
  const socket = new WebSocket(cdpUrl);
13
- const timer = setTimeout(() => socket.close(), DISCOVERY_MS);
20
+ const deadline = Date.now() + DISCOVERY_MS;
21
+ const timer = setTimeout(() => socket.close(), DISCOVERY_MS + CLEANUP_MS);
14
22
  const stop = () => socket.close();
15
23
  signal?.addEventListener("abort", stop, { once: true });
16
- // A call the browser never answers settles empty when the socket closes (the deadline, an abort, the browser).
24
+ // A call the browser does not answer within `ms` (the deadline, unless shorter) settles empty, as does every call once
25
+ // the socket closes (an abort, the browser).
17
26
  const pending = new Map();
18
27
  const listeners = new Set();
19
28
  let next = 0;
20
29
  let closed = false;
21
30
  // A send on a closed socket neither throws nor is ever answered (Node 24): once closed, every call settles empty.
22
- const call = (method, params = {}, sessionId) => new Promise((resolve) => {
23
- if (closed || socket.readyState !== WebSocket.OPEN)
31
+ const call = (method, params = {}, sessionId, ms = deadline - Date.now()) => new Promise((resolve) => {
32
+ if (closed || socket.readyState !== WebSocket.OPEN || ms <= 0)
24
33
  return resolve(undefined);
25
- pending.set(++next, resolve);
26
- socket.send(JSON.stringify({ id: next, method, params, ...(sessionId ? { sessionId } : {}) }));
34
+ const id = ++next;
35
+ const settle = (result) => { clearTimeout(wait); pending.delete(id); resolve(result); };
36
+ const wait = setTimeout(() => settle(undefined), ms);
37
+ pending.set(id, settle);
38
+ socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
27
39
  });
28
40
  try {
29
41
  await new Promise((resolve, reject) => {
@@ -33,7 +45,7 @@ export async function installedExtension(cdpUrl, signal, known) {
33
45
  socket.onerror = () => reject(new Error("Failed to open CDP WebSocket"));
34
46
  socket.onclose = () => {
35
47
  closed = true;
36
- for (const settle of pending.values())
48
+ for (const settle of [...pending.values()])
37
49
  settle(undefined);
38
50
  for (const listener of listeners)
39
51
  listener({ method: "closed" });
@@ -56,22 +68,35 @@ export async function installedExtension(cdpUrl, signal, known) {
56
68
  return null;
57
69
  id = enabled[0].id;
58
70
  }
59
- const workers = async () => ((await call("Target.getTargets"))?.targetInfos ?? [])
60
- .filter((target) => target.type === "service_worker" && target.url.startsWith(`chrome-extension://${id}/`))
61
- .map((target) => target.targetId);
71
+ /** The extension's workers; null when the browser gave no list, which is not a list without one. */
72
+ const workers = async () => {
73
+ const infos = (await call("Target.getTargets"))?.targetInfos;
74
+ return infos?.filter((target) => target.type === "service_worker" && target.url.startsWith(`chrome-extension://${id}/`)).map((target) => target.targetId) ?? null;
75
+ };
62
76
  const running = await workers();
77
+ if (running === null) {
78
+ if (signal?.aborted || closed)
79
+ return id;
80
+ throw new TargetsUnlistedError();
81
+ }
63
82
  if (running.length === 0) {
64
- let wake = null;
65
- for (let tries = 0; !closed && tries < WAKE_TRIES && (await workers()).length === 0; tries += 1) {
66
- if (tries % 10 === 0) {
67
- if (wake)
68
- await call("Target.closeTarget", { targetId: wake });
69
- wake = (await call("Target.createTarget", { url: `chrome-extension://${id}/wake-service-worker.html` }))?.targetId ?? null;
83
+ // Every wake page opened stays listed here until a close of it is answered. None is opened within CLEANUP_MS of the
84
+ // deadline, an opening's reply is awaited into the first half of that second, and the socket outlives the deadline
85
+ // by CLEANUP_MS, so the last pages are closed on it.
86
+ const wakes = new Set();
87
+ const closeWakes = async (ms) => { for (const page of [...wakes])
88
+ if ((await call("Target.closeTarget", { targetId: page }, undefined, ms)) !== undefined)
89
+ wakes.delete(page); };
90
+ for (let tries = 0; !closed && Date.now() < deadline && tries < WAKE_TRIES && ((await workers())?.length ?? 0) === 0; tries += 1) {
91
+ if (tries % 10 === 0 && deadline - Date.now() > CLEANUP_MS) {
92
+ await closeWakes();
93
+ const page = (await call("Target.createTarget", { url: `chrome-extension://${id}/wake-service-worker.html` }, undefined, deadline + CLEANUP_MS / 2 - Date.now()))?.targetId;
94
+ if (page)
95
+ wakes.add(page);
70
96
  }
71
97
  await new Promise((r) => setTimeout(r, 100));
72
98
  }
73
- if (wake)
74
- await call("Target.closeTarget", { targetId: wake });
99
+ await closeWakes(deadline + CLEANUP_MS - Date.now());
75
100
  return id;
76
101
  }
77
102
  const sessionId = (await call("Target.attachToTarget", { targetId: running[0], flatten: true }))?.sessionId;
@@ -110,7 +135,9 @@ export async function installedExtension(cdpUrl, signal, known) {
110
135
  }
111
136
  return id;
112
137
  }
113
- catch {
138
+ catch (error) {
139
+ if (error instanceof TargetsUnlistedError)
140
+ throw error;
114
141
  return known ?? null;
115
142
  }
116
143
  finally {
@@ -0,0 +1,26 @@
1
+ /** Chrome's answer to an evaluate sent with a document's context id after a navigation replaced it. Stagehand's extension
2
+ * relays it as a JSON-RPC error with this text, and the facade's code runs rebuild it as a plain Error with the same
3
+ * text and no cause. Matched by identity. */
4
+ export declare const CONTEXT_GONE = "-32000 Cannot find context with specified id";
5
+ /** A read that lands in a document a navigation has just replaced waits for the new one, then reads once more. The
6
+ * wait's own failure is not the read's: the second read's answer, or its error, is what comes back. */
7
+ export declare function readOnNewDocument<T>(read: () => Promise<T>, waitForDocument: () => Promise<unknown>): Promise<T>;
8
+ type Facade = {
9
+ snapshot(options?: {
10
+ includeIframes?: boolean;
11
+ }): Promise<string>;
12
+ run(code: string): Promise<unknown>;
13
+ };
14
+ /** The driver's snapshot and page reads, each read once more on the new document when a navigation replaced its own. */
15
+ export declare function documentReads(facade: Facade, waitForDocument: () => Promise<unknown>): {
16
+ snapshot: (options?: {
17
+ includeIframes?: boolean;
18
+ }) => Promise<string>;
19
+ page: () => Promise<{
20
+ url: string;
21
+ title: string;
22
+ text: string;
23
+ html: string;
24
+ }>;
25
+ };
26
+ export {};
@@ -0,0 +1,40 @@
1
+ /** Chrome's answer to an evaluate sent with a document's context id after a navigation replaced it. Stagehand's extension
2
+ * relays it as a JSON-RPC error with this text, and the facade's code runs rebuild it as a plain Error with the same
3
+ * text and no cause. Matched by identity. */
4
+ export const CONTEXT_GONE = "-32000 Cannot find context with specified id";
5
+ const contextGone = (error) => {
6
+ if (!(error instanceof Error))
7
+ return false;
8
+ const cause = error.cause;
9
+ if (cause && typeof cause === "object")
10
+ return typeof cause.code === "number" && cause.message === CONTEXT_GONE;
11
+ return error.message === CONTEXT_GONE;
12
+ };
13
+ /** A read that lands in a document a navigation has just replaced waits for the new one, then reads once more. The
14
+ * wait's own failure is not the read's: the second read's answer, or its error, is what comes back. */
15
+ export async function readOnNewDocument(read, waitForDocument) {
16
+ try {
17
+ return await read();
18
+ }
19
+ catch (error) {
20
+ if (!contextGone(error))
21
+ throw error;
22
+ await waitForDocument().catch(() => undefined);
23
+ return await read();
24
+ }
25
+ }
26
+ // A page's address is its document's (location.href): page.url() names a goto's target once Chrome starts it, so a
27
+ // receipt could cite a page it does not hold. One evaluate reads all four, so they are one document's.
28
+ const PAGE_CODE = `return await page.evaluate(() => ({
29
+ url: location.href,
30
+ title: document.title,
31
+ text: document.body ? document.body.innerText : "",
32
+ html: document.documentElement ? document.documentElement.outerHTML : "",
33
+ }));`;
34
+ /** The driver's snapshot and page reads, each read once more on the new document when a navigation replaced its own. */
35
+ export function documentReads(facade, waitForDocument) {
36
+ return {
37
+ snapshot: (options) => readOnNewDocument(() => facade.snapshot(options), waitForDocument),
38
+ page: async () => await readOnNewDocument(() => facade.run(PAGE_CODE), waitForDocument),
39
+ };
40
+ }
@@ -1,5 +1,6 @@
1
1
  import { StagehandFacadeTools } from "../vendor/stagehand-facade/tools.js";
2
2
  import { installedExtension } from "./extension-worker.js";
3
+ import { documentReads } from "./new-document.js";
3
4
  /** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
4
5
  export const STAGEHAND_TELEMETRY = { traces: { endpoint: "http://127.0.0.1:9/v1/traces" } };
5
6
  export const STAGEHAND_INFERENCE_REFUSED = "Stagehand inference is off in this harness: act, extract and observe are unavailable. Drive the page with run code or snapshot IDs.";
@@ -9,15 +10,9 @@ export const SEALED_STAGEHAND = {
9
10
  model: { generate: async () => { throw new Error(STAGEHAND_INFERENCE_REFUSED); } },
10
11
  telemetry: STAGEHAND_TELEMETRY,
11
12
  };
12
- // A page's address is its document's (location.href): page.url() names a goto's target once Chrome starts it, so a
13
- // receipt could cite a page it does not hold. One evaluate reads all four, so they are one document's.
14
- const PAGE_CODE = `return await page.evaluate(() => ({
15
- url: location.href,
16
- title: document.title,
17
- text: document.body ? document.body.innerText : "",
18
- html: document.documentElement ? document.documentElement.outerHTML : "",
19
- }));`;
20
13
  const URL_READ_MS = 2_000;
14
+ /** How long a read that landed in a document a navigation replaced waits for the new one's DOMContentLoaded. */
15
+ const NEW_DOCUMENT_MS = 15_000;
21
16
  /** In a batch of its own, which the browser runs after any batch still running, so the read never lands inside a
22
17
  * pending navigation (a page call issued then never returns). Past URL_READ_MS, Stagehand's page.url(). */
23
18
  async function documentUrl(stagehand, page) {
@@ -71,8 +66,11 @@ export function stagehandDriver() {
71
66
  throw new Error("Stagehand has no active page.");
72
67
  return page;
73
68
  };
69
+ // In a batch of its own, which the browser runs once the new document is its page's.
70
+ const newDocument = async () => stagehand.experimentalBatch(async (batch, input) => { await batch.page.waitForLoadState("domcontentloaded", input.ms); }, { ms: NEW_DOCUMENT_MS }, { page: await active(), timeout: NEW_DOCUMENT_MS + 1_000 });
71
+ const reads = documentReads(facade, newDocument);
74
72
  return {
75
- snapshot: (snapshotOptions) => facade.snapshot(snapshotOptions),
73
+ snapshot: (snapshotOptions) => reads.snapshot(snapshotOptions),
76
74
  run: (input) => input.actions !== undefined ? facade.runActions(input.actions) : facade.run(input.code ?? ""),
77
75
  url: async () => documentUrl(stagehand, await active()),
78
76
  screenshot: async ({ type = "png", quality, fullPage, scale }) => {
@@ -83,7 +81,7 @@ export function stagehandDriver() {
83
81
  });
84
82
  return { data: Buffer.from(bytes).toString("base64"), mimeType: type === "jpeg" ? "image/jpeg" : "image/png" };
85
83
  },
86
- page: async () => await facade.run(PAGE_CODE),
84
+ page: () => reads.page(),
87
85
  // Stagehand's own close keeps the browser for another attach; the browser's close would end it.
88
86
  close: () => stagehand.close(),
89
87
  };
package/dist/durable.d.ts CHANGED
@@ -47,7 +47,14 @@ export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = {
47
47
  createDeadlineMs?: number;
48
48
  /** How the request observer attaches (default `EffectObserver.open`); a seam for tests that have no Chrome. */
49
49
  openObserver?: typeof EffectObserver.open;
50
+ /** Called synchronously at two moments of a page action, for a host that kills the process there to test a resume:
51
+ * `browser.between-actions` once a page action's answer is committed, before the next page action dispatches, and
52
+ * `browser.action-returned` once the driver call returned (or threw) and the action's entry is marked finished,
53
+ * before pi commits its answer. A throw, or a rejected promise, is a process warning (`PI_BROWSER_CROSSING`) and
54
+ * never changes the call. */
55
+ crossing?: (point: Crossing) => void;
50
56
  };
57
+ type Crossing = "browser.between-actions" | "browser.action-returned";
51
58
  export type BrowserExtensionHandle = {
52
59
  /** Install once per Harness, before `resume()`; select per conversation. */
53
60
  extension: Extension;