@parcha/pi-browser 0.1.0-beta.13 → 0.1.0-beta.15

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 (43) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +29 -8
  3. package/dist/coding-agent.d.ts +7 -0
  4. package/dist/coding-agent.js +33 -16
  5. package/dist/core/contract.js +1 -1
  6. package/dist/core/custody.d.ts +16 -3
  7. package/dist/core/custody.js +28 -11
  8. package/dist/core/downloads.d.ts +1 -0
  9. package/dist/core/downloads.js +2 -2
  10. package/dist/core/failures.d.ts +8 -0
  11. package/dist/core/failures.js +18 -9
  12. package/dist/core/guard.d.ts +1 -1
  13. package/dist/core/guard.js +2 -1
  14. package/dist/core/host.d.ts +60 -2
  15. package/dist/core/sites.js +2 -1
  16. package/dist/core/tools.d.ts +37 -2
  17. package/dist/core/tools.js +84 -54
  18. package/dist/core/usage.d.ts +1 -20
  19. package/dist/driver/extension-worker.d.ts +7 -0
  20. package/dist/driver/extension-worker.js +148 -0
  21. package/dist/driver/new-document.d.ts +26 -0
  22. package/dist/driver/new-document.js +40 -0
  23. package/dist/driver/stagehand.js +9 -61
  24. package/dist/durable.d.ts +14 -3
  25. package/dist/durable.js +507 -369
  26. package/dist/index.d.ts +1 -0
  27. package/dist/index.js +1 -0
  28. package/dist/providers/browserbase.d.ts +17 -0
  29. package/dist/providers/browserbase.js +49 -8
  30. package/dist/providers/cdp.d.ts +14 -0
  31. package/dist/providers/cdp.js +270 -66
  32. package/dist/providers/kernel.js +40 -6
  33. package/dist/providers/profiles.d.ts +19 -0
  34. package/dist/providers/profiles.js +124 -0
  35. package/dist/providers/shared.d.ts +1 -1
  36. package/dist/recorder/index.d.ts +1 -0
  37. package/dist/recorder/index.js +1 -0
  38. package/dist/recorder/jpeg.d.ts +3 -0
  39. package/dist/recorder/jpeg.js +36 -0
  40. package/dist/recorder/track.d.ts +107 -0
  41. package/dist/recorder/track.js +280 -0
  42. package/dist/testing/backend.js +2 -2
  43. package/package.json +3 -3
package/CHANGELOG.md CHANGED
@@ -2,6 +2,18 @@
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
+
10
+ ## 0.1.0-beta.14 (2026-10-16)
11
+
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.
13
+ - On pi-ai 1.3, a tool call whose arguments are not a JSON object reaches no tool: pi-durable refuses it and shows the model the text it sent. A durable node's `submit` then spends none of its submissions. Before 1.3 the tool ran with `{}`, so `submit` answered with the schema's violations and counted one submission.
14
+ - `@parcha/pi-browser/recorder`: `exportFrameTracks` turns the recorded frames into one `frame.track` line per session: a WebM (VP9, constant `fps`, default 10) plus an index that maps run time to video time across gaps, with a slate while a gap lasts. `handle.drain(harness, ctx, signal?)` on the pi-durable adapter's handle resolves once no browser release is still running, so a host waits for it before it closes the harness. The index exports custody's vocabulary by name (`CustodyPort`, `AttachedSession`, `ToolOutput`, `BrowserFailureError`, `BrowserDriver`, `DriverFactory`, `DriverOptions`, `Overrides`) so a host can write its own tool.
15
+ - `@parcha/pi-browser`: a `cdp` kill never signals pid 1, pid 0, its own pid, or a process group the pid does not lead. A session's record and `browser_relaunch`'s answer name only the settings the provider applied (Browserbase applies proxies, verified, geolocation, region and context; Kernel and local Chrome none). A screenshot's `ask` comes back in `details.media.ask`. A classified failure names the browser provider, not Browserbase. A conversation's close evicts its repeat guard and idle entry. A page action's journal entry outlives its answer, and an identical retry waits for a look. Stagehand's extension losing its own CDP connection is a dropped browser, not the model's code error: a read reconnects and runs once more, a run is not repeated. A held Stagehand runtime is freed through its own close and never by closing its service worker, which under load was sometimes never restarted. Every Chrome the `cdp` provider starts gets a temporary directory of its own, removed with the lease, so Chrome's leftover entries no longer land in the host's `TMPDIR`.
16
+
5
17
  ## 0.1.0-beta.13 (2026-10-14)
6
18
 
7
19
  First release of `@parcha/pi-browser`. It is versioned with the other packages of the repository it is published from; the release PR dates this section and gives it the workspace version.
package/README.md CHANGED
@@ -26,7 +26,9 @@ Stagehand, undici, zod and the two HTML packages are dependencies. Four optional
26
26
  | `@earendil-works/pi-durable` and `@earendil-works/chord` | `/durable`, the adapter for a pi-durable Harness. |
27
27
  | `@browserbasehq/sdk` | the Browserbase provider. Kernel needs no SDK. |
28
28
 
29
- The pi peers are `@earendil-works/pi-durable` and `chord` `>=1.1.0 <1.3.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 and 1.2, and the coding-agent entry's tests also pass on a pi 1.0.4 family.
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
+
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.
30
32
 
31
33
  ## Quick start
32
34
 
@@ -206,6 +208,7 @@ const harness = await Harness.open(storage, { models, registry }, context);
206
208
  await browser.reconcile(harness, () => true, context); // settles what a dead process left
207
209
  // A conversation selects the extension and writes its BrowserConfig in its creating commit (`browser.docs.Config`);
208
210
  // when it ends: `await browser.release(conversation, "close", context)`.
211
+ // Before `harness.close()`: `await browser.drain(harness, context)`, so the releases reach the provider.
209
212
  ```
210
213
 
211
214
  `createBrowserExtension` takes no key and sends nothing anywhere but the provider you give it. The options:
@@ -226,10 +229,12 @@ await browser.reconcile(harness, () => true, context); // settles what a dead
226
229
  Per conversation, the host writes a `BrowserConfig` (`label`, `run`, and the policy: proxies, verified, captcha, geolocation,
227
230
  region, a raw context id, the session timeout, the idle release and the batch timeout; `DEFAULT_BROWSER_POLICY` holds the
228
231
  package's defaults to spread and override) in the conversation's creating commit,
229
- selects the extensions for it, and calls `handle.release(conversation, "close", ctx)` when the conversation ends. At run open,
230
- after the extensions are installed and before anything resumes, it calls `handle.reconcile(harness, isActive, ctx)`, and every
231
- session a dead process left is bound, kept or released. The host wraps the tools (`handle.tools`) with its own policy: pause,
232
- call records, a result cap, media for the route.
232
+ selects the extensions for it, and calls `handle.release(conversation, "close", ctx)` when the conversation ends. Releases run
233
+ as background tasks, which `waitForIdle` skips and closing the harness aborts: before it closes, a host calls
234
+ `handle.drain(harness, ctx, signal?)`, which resolves once none is live. At run open, after the extensions are installed and
235
+ before anything resumes, it calls `handle.reconcile(harness, isActive, ctx)`, and every session a dead process left is bound,
236
+ kept or released. The host wraps the tools (`handle.tools`) with its own policy: pause, call records, a result cap, media for
237
+ the route.
233
238
 
234
239
  A host with its own provider implements `BrowserProvider`: `name`, `caps`, `create` (at most once, the tag stamped on the
235
240
  provider's side), `findByTag`, `status`, `attach`, `release`, and optionally `liveView`, `recordings`, `downloads`, `fetch`
@@ -281,8 +286,7 @@ A session is captured from the moment it is created or reattached (so after a ki
281
286
  - **No frame is kept while a credential or a code is on the page**, and anything the recorder cannot read counts as one being there. A frame is
282
287
  judged against the page the moment it arrives (one check, standing for the page at its capture) and again when its turn to be kept comes (both
283
288
  checks go through one pace per session: each is sent at least 50 ms after the last, so a session sends at most 20 `Runtime.evaluate` in any
284
- second, however fast frames arrive); a
285
- credential seen in either drops it, and a frame held across a navigation or a move to another page is not kept. The check looks at password
289
+ second, however fast frames arrive); a credential seen in either drops it, and a frame held across a navigation or a move to another page is not kept. The check looks at password
286
290
  fields, `one-time-code` fields and fields named like a code (name, id, `<label>`, `aria-labelledby`, `aria-label` or placeholder says otp, totp,
287
291
  2fa, passcode, ...) that hold a value, in the page, open shadow roots and same-origin frames; a value typed and cleared between two checks is
288
292
  still seen (the page keeps a flag, `window.__piFramesSecret`, set by the fields' own `input` events). A page that nests deeper than the check
@@ -296,7 +300,24 @@ A session is captured from the moment it is created or reattached (so after a ki
296
300
  call: that line is dropped and counted in `frames.stats()`, and a frame that was not saved never becomes the point a later gap starts from.
297
301
  - `frames.watch(...).release` ends the capture, and writes the `session_released` gap, once the provider has released the session: a release it
298
302
  refuses leaves the capture running.
299
- - `frame.track` (a WebM per session with an index) is made at export, from the frames, by a step of its own.
303
+ - **`frame.track`** (a WebM per session with an index) is made at export, from the recorded frames, by `exportFrameTracks`:
304
+
305
+ ```js
306
+ import { exportFrameTracks } from "@parcha/pi-browser/recorder";
307
+ const tracks = await exportFrameTracks({ lines, readBlob: (sha256) => bytesOfBlob(sha256), endAt: recordingEndMs, fps: 10 });
308
+ for (const { line, blobs } of tracks) { /* line is the frame.track line; blobs holds the WebM and its index by sha256 */ }
309
+ ```
310
+
311
+ One track per session that has a frame. The video is VP9 at a constant `fps` (default 10) on one canvas, the largest frame in even numbers (a smaller
312
+ frame is centred on it); each frame is shown until the next one, and while a gap lasts the video shows a slate: from the moment a
313
+ `credential_on_page` or `session_released` gap was written, and from the last frame the earlier process saved for a `process_killed` gap (nothing is
314
+ known after it). The track runs from the session's first frame to `endAt` (default: the last line, a lone frame lasting one frame's time). The line is
315
+ `{ kind: "frame.track", t: <the track's end>, conv, data: { session, fps, from, to }, blobs: [<webm sha256>, <index sha256>] }`; the index (JSON) lists every
316
+ frame with its `t` and its `ms` offset into the video, and every gap with `from`, `to`, `reason` and `detail`, so a viewer maps a time in the recording to a
317
+ time in the video (`t - from`). A frame whose blob is missing, does not hash to its name or is not a JPEG shows the slate and is reported in `skipped`.
318
+ The step starts `ffmpeg` (`ffmpeg` option: a path; default the one on the PATH) in a private temporary directory with `PATH`, `LANG`, `LC_ALL` and `HOME`
319
+ only, with fixed arguments and no URL, a timeout (`timeoutMs`, 120 s) and an `AbortSignal`; a failure is a `TrackExportError` (`ffmpeg_missing`,
320
+ `ffmpeg_failed`, `ffmpeg_timeout`, `aborted`) and writes nothing.
300
321
 
301
322
  ## How it compares
302
323
 
@@ -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,11 +64,16 @@ 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>;
68
74
  dispatching(): Promise<void>;
69
75
  journal(): Promise<void>;
76
+ mark(): Promise<void>;
70
77
  settle(): Promise<void>;
71
78
  navigated(url: string): Promise<void>;
72
79
  ended(): Promise<boolean>;
@@ -4,8 +4,8 @@ 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";
8
- import { classifyBrowserError } from "./core/failures.js";
7
+ import { BrowserFailureError, closeDriver, custodyTools, newSessionRecord, notices, profileRefusal, sessionSpec, } from "./core/custody.js";
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";
11
11
  import { useWebsite, useWebsiteContract } from "./core/sites.js";
@@ -17,7 +17,7 @@ export { findChrome } from "./coding-agent-local.js";
17
17
  export const SESSION_ENTRY = "browser.session";
18
18
  const CONVERSATION = 1;
19
19
  const BROWSER_FLAGS = ["browser-provider", "browser-endpoint", "browser-chrome", "browser-headed", "browser-no-sandbox"];
20
- const refused = (message, code = "browser_unavailable") => new BrowserFailureError({ ok: false, code, retryable: false, effect: "none", message });
20
+ const refused = (message, code = "browser_unavailable") => new BrowserFailureError(browserFailure(code, message));
21
21
  const now = () => new Date().toISOString();
22
22
  /** The provider released the browser and could not remove a directory it left (`ProfileNotRemovedError`'s code, read without importing the provider). */
23
23
  const directoryLeft = (error) => error?.code === "profile_not_removed";
@@ -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,7 +86,10 @@ 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);
87
- const record = newSessionRecord({ plane: "browser", tag, provider: provider.name, spec, at: now() });
89
+ const unsupported = profileRefusal(spec, provider.caps);
90
+ if (unsupported)
91
+ throw new BrowserFailureError(unsupported);
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)]);
90
95
  let live = null;
@@ -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. */
@@ -206,6 +215,7 @@ export class LocalCustody {
206
215
  }
207
216
  async dispatching() { }
208
217
  async journal() { }
218
+ async mark() { }
209
219
  async settle() { }
210
220
  async navigated(url) { if (this.live)
211
221
  this.live.record.lastUrl = scrubPageUrl(url, this.d.redact); }
@@ -334,12 +344,16 @@ function registerTool(pi, contract, runtimeOf) {
334
344
  export function createBrowserExtension(options = {}) {
335
345
  const env = options.env ?? process.env;
336
346
  const policy = { ...DEFAULT_BROWSER_POLICY, ...(env.PI_BROWSER_PROXIES === "1" ? { proxies: true } : {}), ...options.policy };
347
+ // pi checks a call's arguments against the tool's schema before execute, so each implementation receives its own shape.
337
348
  const impls = { ...custodyTools, ...pageTools() };
338
349
  return function piBrowser(pi) {
339
350
  let runtime = null;
340
351
  let opening = null;
341
352
  let webSearchRegistered = false;
342
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; };
343
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)" });
344
358
  pi.registerFlag("browser-endpoint", { type: "string", description: "Attach to a Chrome DevTools endpoint (http://host:port or ws://...) instead of starting Chrome" });
345
359
  pi.registerFlag("browser-chrome", { type: "string", description: "Path to the Chrome or Chromium to start" });
@@ -430,7 +444,10 @@ export function createBrowserExtension(options = {}) {
430
444
  annotations: { readOnlyHint: false, openWorldHint: true },
431
445
  async execute(_callId, params, signal, _onUpdate, ctx) {
432
446
  const rt = await runtimeOf(ctx);
433
- 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
+ } });
434
451
  return { content: out.content.map((item) => item.type === "text" ? { ...item, text: rt.redact(item.text) } : item), details: undefined, ...(out.isError ? { isError: true } : {}) };
435
452
  },
436
453
  });
@@ -49,7 +49,7 @@ const screenshot = {
49
49
  fullPage: { type: "boolean" },
50
50
  type: { type: "string", enum: ["png", "jpeg"] },
51
51
  quality: { type: "number", minimum: 0, maximum: 100 },
52
- ask: { type: "string", description: "What you want to know from this capture. Answered from the pixels when your model cannot see them; echoed back when it can." },
52
+ ask: { type: "string", description: "What you want to know from this capture. It travels with the image, so a host can answer it from the pixels when your model cannot see them." },
53
53
  }),
54
54
  effect: "read", replay: "safe", executionMode: "sequential", evidence: "image", listedWhen: "always",
55
55
  };
@@ -1,6 +1,6 @@
1
- import type { BrowserFailure } from "./failures.js";
1
+ import { type BrowserFailure } from "./failures.js";
2
2
  import type { EffectObserver } from "./effects.js";
3
- import type { AttachTarget, BrowserConfig, Geo, ReleaseReason, SentEffect, SessionRecord, SessionSpec, SessionsState } from "./host.js";
3
+ import type { AttachTarget, BrowserConfig, Geo, ProviderCaps, ReleaseReason, SentEffect, SessionRecord, SessionSpec, SessionsState } from "./host.js";
4
4
  import { type LeaseState } from "./lease.js";
5
5
  export type BrowserDriver = {
6
6
  close(): Promise<void>;
@@ -27,6 +27,7 @@ export type AttachedSession<D> = {
27
27
  sessionId: string;
28
28
  record: SessionRecord;
29
29
  notice: string | null;
30
+ /** The cut this call answers for: a journal entry an earlier custody process left without a committed answer. */
30
31
  interrupted: SessionRecord["pendingEffect"];
31
32
  recorded: boolean;
32
33
  effects: Pick<EffectObserver, "record" | "flush" | "holding"> | null;
@@ -37,9 +38,14 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
37
38
  /** A rerun finds the session it launched. */
38
39
  relaunch(overrides: Overrides): Promise<AttachedSession<D>>;
39
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). */
40
42
  release(): Promise<{
41
43
  released: boolean;
42
44
  sessionId: string | null;
45
+ ended?: {
46
+ reason: ReleaseReason;
47
+ at: string | null;
48
+ };
43
49
  }>;
44
50
  /** Committed before the `run` is dispatched. */
45
51
  dispatching(effect: {
@@ -47,9 +53,13 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
47
53
  codeSha: string;
48
54
  url: string | null;
49
55
  observed: boolean;
56
+ watched: boolean;
50
57
  }): Promise<void>;
51
58
  journal(row: SentEffect): Promise<void>;
52
- settle(): Promise<void>;
59
+ /** A journal entry's next step, by its call: the action returned, its cut was told, or an identical action was refused. */
60
+ mark(step: "finished" | "told" | "refused", callId: string): Promise<void>;
61
+ /** Clears the journal entry of that call only: another action's entry, journaled meanwhile, stays. */
62
+ settle(callId: string): Promise<void>;
53
63
  navigated(url: string): Promise<void>;
54
64
  /** When the provider reports the session ended, custody records it and the next call opens a fresh one. */
55
65
  ended(): Promise<boolean>;
@@ -89,6 +99,7 @@ export declare function newSessionRecord(input: {
89
99
  provider: string;
90
100
  spec: SessionSpec;
91
101
  at: string;
102
+ honours?: ProviderCaps["settings"];
92
103
  }): SessionRecord;
93
104
  export declare function moveRecord(record: SessionRecord, next: {
94
105
  state: LeaseState;
@@ -96,7 +107,9 @@ export declare function moveRecord(record: SessionRecord, next: {
96
107
  reason?: ReleaseReason;
97
108
  at: string;
98
109
  }): void;
110
+ export declare const PROFILE_NAME: RegExp;
99
111
  export declare function sessionSpec(config: BrowserConfig, tag: string, overrides?: Overrides): SessionSpec;
112
+ export declare function profileRefusal(spec: SessionSpec, caps: ProviderCaps): BrowserFailure | null;
100
113
  /** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
101
114
  * silently. */
102
115
  export declare function relaunchRefusal(policy: BrowserConfig["policy"], overrides: Overrides): BrowserFailure | null;
@@ -1,4 +1,6 @@
1
+ import { browserFailure } from "./failures.js";
1
2
  import { isLeaseTransition } from "./lease.js";
3
+ import { startSpent } from "./usage.js";
2
4
  /** A Stagehand close after a dropped and reconnected connection can hang forever; the provider ends the session anyway. */
3
5
  export const DRIVER_CLOSE_MS = 5_000;
4
6
  export async function closeDriver(driver) {
@@ -16,10 +18,7 @@ export class BrowserFailureError extends Error {
16
18
  }
17
19
  export const NAVIGATION_CAP = 500;
18
20
  export const VIEWPORT = Object.freeze({ width: 1288, height: 711 });
19
- export const SESSION_REPLACED = {
20
- ok: false, code: "session_replaced", retryable: true, effect: "none",
21
- message: "The browser session this call was using ended in an interruption, so its page is gone. Navigate again with run, or take a snapshot, to continue in a fresh session.",
22
- };
21
+ export const SESSION_REPLACED = browserFailure("session_replaced", "The browser session this call was using ended in an interruption, so its page is gone. Navigate again with run, or take a snapshot, to continue in a fresh session.", { retryable: true });
23
22
  export const notices = {
24
23
  kept: (url) => `Your browser session survived an interruption and is still open${url ? ` on ${url}` : ""}. Take a snapshot before acting again.`,
25
24
  lost: (url) => `Your browser session ended during an interruption. The next browser call opens a fresh session with no cookies or page state${url ? `; the last page was ${url}` : ""}.`,
@@ -31,12 +30,17 @@ export function currentRecord(state, plane) {
31
30
  return index === null || index === undefined ? null : state.sessions[index] ?? null;
32
31
  }
33
32
  export function newSessionRecord(input) {
34
- const { spec } = input;
33
+ const { spec, honours = {} } = input;
34
+ const proxies = spec.proxies !== false && honours.proxies !== false;
35
35
  return {
36
36
  tag: input.tag, state: "creating", resourceId: null, createdAt: input.at, endedAt: null, releaseReason: null,
37
37
  plane: input.plane, provider: input.provider,
38
- settings: { proxies: spec.proxies !== false, verified: spec.verified, geolocation: typeof spec.proxies === "object" ? spec.proxies.geolocation : null, region: spec.region ?? null, contextId: spec.contextId ?? null },
39
- navigation: [], lastUrl: null, pendingEffect: null, spent: { seconds: 0, usd: 0, chargedThrough: input.at },
38
+ settings: {
39
+ proxies, verified: spec.verified && honours.verified !== false,
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, profile: spec.profile?.name ?? null,
42
+ },
43
+ navigation: [], lastUrl: null, pendingEffect: null, spent: startSpent(input.at),
40
44
  };
41
45
  }
42
46
  export function moveRecord(record, next) {
@@ -52,8 +56,14 @@ export function moveRecord(record, next) {
52
56
  if (next.state === "released" || next.state === "lost")
53
57
  record.endedAt = next.at;
54
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 });
55
61
  export function sessionSpec(config, tag, overrides = {}) {
56
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."));
57
67
  const geolocation = overrides.geolocation === undefined ? policy.geolocation : overrides.geolocation;
58
68
  return {
59
69
  tag, maxLifetimeS: policy.sessionTimeoutS, idleTimeoutS: policy.idleReleaseS,
@@ -62,16 +72,20 @@ export function sessionSpec(config, tag, overrides = {}) {
62
72
  ...(policy.region ? { region: policy.region } : {}),
63
73
  viewport: { ...VIEWPORT },
64
74
  ...(policy.contextId ? { contextId: policy.contextId } : {}),
75
+ ...(policy.profile ? { profile: { name: policy.profile.name, save: policy.profile.save } } : {}),
65
76
  ...(policy.navigation ? { navigation: policy.navigation } : {}),
66
77
  metadata: { run: config.run, label: config.label },
67
78
  };
68
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
+ }
69
83
  /** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
70
84
  * silently. */
71
85
  export function relaunchRefusal(policy, overrides) {
72
86
  if (!overrides.geolocation || policy.proxies)
73
87
  return null;
74
- return { ok: false, code: "refused", retryable: false, effect: "none", message: "browser_relaunch: geolocation needs a proxy, and this run's browser policy has proxies off, so no session can browse from a chosen place. Nothing was relaunched and your session is unchanged; browser_relaunch can still change verified, with geolocation left out." };
88
+ return browserFailure("refused", "browser_relaunch: geolocation needs a proxy, and this run's browser policy has proxies off, so no session can browse from a chosen place. Nothing was relaunched and your session is unchanged; browser_relaunch can still change verified, with geolocation left out.");
75
89
  }
76
90
  /** An ISO alpha-2 country, a US state abbreviation, a city in capitals; null when the country is not two letters. */
77
91
  export function normalizeGeolocation(raw) {
@@ -99,8 +113,11 @@ const failed = (error) => {
99
113
  export const custodyTools = {
100
114
  async browser_release(_args, port) {
101
115
  try {
102
- const { released, sessionId } = await port.release();
103
- 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 } : {}) });
104
121
  }
105
122
  catch (error) {
106
123
  return failed(error);
@@ -109,7 +126,7 @@ export const custodyTools = {
109
126
  async browser_relaunch(args, port) {
110
127
  const geolocation = args.geolocation === undefined ? undefined : normalizeGeolocation(args.geolocation);
111
128
  if (geolocation === null)
112
- return text({ ok: false, code: "refused", retryable: false, effect: "none", message: 'browser_relaunch: geolocation needs a two-letter ISO country code (e.g. {country: "GB"}).' }, true);
129
+ return text(browserFailure("refused", 'browser_relaunch: geolocation needs a two-letter ISO country code (e.g. {country: "GB"}).'), true);
113
130
  try {
114
131
  // A relaunch that names no `verified` keeps the run's policy: an omitted flag never downgrades a Verified session.
115
132
  const { sessionId, record } = await port.relaunch({ ...(args.verified !== undefined ? { verified: args.verified === true } : {}), ...(geolocation ? { geolocation } : {}) });
@@ -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 {
@@ -9,6 +9,11 @@ export type BrowserFailure = {
9
9
  /** Provider or page text, at most 2,000 characters; redacted before it reaches the model. */
10
10
  detail?: string;
11
11
  };
12
+ export declare const browserFailure: (code: FailureCode, message: string, options?: {
13
+ retryable?: boolean;
14
+ effect?: BrowserFailure["effect"];
15
+ detail?: string;
16
+ }) => BrowserFailure;
12
17
  /** `timedOut`: the call ran to the driver's batch deadline, which Stagehand reports as a plain Error. */
13
18
  export type FailureFacts = {
14
19
  sessionEnded?: boolean;
@@ -18,6 +23,9 @@ export type FailureFacts = {
18
23
  export declare const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
19
24
  export declare const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
20
25
  export declare const STALE_SNAPSHOT_ID_ERROR = "Snapshot ID \"${id}\" is stale or not actionable; call snapshot again.";
26
+ /** Stagehand's extension lost its own CDP connection to the browser (a refusal constant of Stagehand's, matched by identity): its
27
+ * host rethrows it with the extension's JSON-RPC internal error (-32603) as the cause. The driver is gone, not the session. */
28
+ export declare const STAGEHAND_LOOPBACK_DISCONNECTED = "Stagehand loopback CDP is disconnected";
21
29
  export type TransportFact = {
22
30
  status?: number;
23
31
  errorName?: string;
@@ -4,12 +4,21 @@ export const FAILURE_CODES = Object.freeze([
4
4
  "browser_unavailable", "auth", "timeout", "aborted", "refused", "stale_snapshot", "session_ended",
5
5
  "session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited",
6
6
  ]);
7
+ export const browserFailure = (code, message, options = {}) => ({ ok: false, code, retryable: options.retryable ?? false, effect: options.effect ?? "none", message, ...(options.detail === undefined ? {} : { detail: options.detail }) });
7
8
  export const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
8
9
  export const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
9
10
  export const STALE_SNAPSHOT_ID_ERROR = 'Snapshot ID "${id}" is stale or not actionable; call snapshot again.';
10
11
  const [STALE_ID_HEAD, STALE_ID_TAIL] = STALE_SNAPSHOT_ID_ERROR.split("${id}");
11
12
  const isStaleSnapshot = (message) => message === NO_HYDRATED_SNAPSHOT_ERROR || message === NAVIGATED_SNAPSHOT_ERROR
12
13
  || (message.startsWith(STALE_ID_HEAD) && message.endsWith(STALE_ID_TAIL) && message.length > STALE_ID_HEAD.length + STALE_ID_TAIL.length);
14
+ /** Stagehand's extension lost its own CDP connection to the browser (a refusal constant of Stagehand's, matched by identity): its
15
+ * host rethrows it with the extension's JSON-RPC internal error (-32603) as the cause. The driver is gone, not the session. */
16
+ export const STAGEHAND_LOOPBACK_DISCONNECTED = "Stagehand loopback CDP is disconnected";
17
+ const JSONRPC_INTERNAL_ERROR = -32603;
18
+ const lostLoopback = (error) => {
19
+ const cause = error?.cause;
20
+ return !!cause && typeof cause === "object" && cause.code === JSONRPC_INTERNAL_ERROR && cause.message === STAGEHAND_LOOPBACK_DISCONNECTED;
21
+ };
13
22
  const UNREACHABLE_CAUSES = new Set(["ECONNREFUSED", "ENOTFOUND", "ECONNRESET", "EAI_AGAIN", "EPIPE", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT"]);
14
23
  const UNREACHABLE_NAMES = new Set(["CDPConnectionClosedError"]);
15
24
  /** A throw site's `transport` record, else class name, `code` and `status` down the cause chain; first found wins. */
@@ -42,18 +51,18 @@ export function classifyBrowserError(error, effectful, facts = {}) {
42
51
  const effect = effectful ? "possibly_effected" : "none";
43
52
  const detail = message.slice(0, 2_000);
44
53
  if (facts.aborted || fact.errorName === "AbortError")
45
- return { ok: false, code: "aborted", retryable: false, effect, message: "The browser call was cancelled by the run.", detail };
54
+ return browserFailure("aborted", "The browser call was cancelled by the run.", { effect, detail });
46
55
  if (status === 401)
47
- return { ok: false, code: "auth", retryable: false, effect: "none", message: "Browserbase refused the credential (401). The browser plane is unavailable for this run; use fetch (executor tools).", detail };
56
+ return browserFailure("auth", "The browser provider refused the credential (401). The browser plane is unavailable for this run; use fetch (executor tools).", { detail });
48
57
  if (status === 403)
49
- return { ok: false, code: "auth", retryable: false, effect: "none", message: "Browserbase refused this session type (403). Retry without `verified`, or use web_fetch.", detail };
58
+ return browserFailure("auth", "The browser provider refused this session type (403). Retry without `verified`, or use web_fetch.", { detail });
50
59
  if (facts.sessionEnded)
51
- return { ok: false, code: "session_ended", retryable: true, effect, message: "The browser session ended (Browserbase closes a session at its timeout, or the browser died). Your next browser call opens a fresh session automatically; the old tabs, page state and cookies are gone — navigate to the page again with run, then continue from there.", detail };
60
+ return browserFailure("session_ended", "The browser session ended (the provider closed it at its timeout, or the browser died). Your next browser call opens a fresh session automatically; the old tabs, page state and cookies are gone — navigate to the page again with run, then continue from there.", { retryable: true, effect, detail });
52
61
  if (facts.timedOut || fact.errorName === "TimeoutError")
53
- return { ok: false, code: "timeout", retryable: true, effect, message: "The browser call timed out. Take a fresh snapshot before acting again; split a long `run` into smaller batches; if the page never loads, use web_fetch or another source.", detail };
62
+ return browserFailure("timeout", "The browser call timed out. Take a fresh snapshot before acting again; split a long `run` into smaller batches; if the page never loads, use web_fetch or another source.", { retryable: true, effect, detail });
54
63
  if (isStaleSnapshot(own))
55
- return { ok: false, code: "stale_snapshot", retryable: true, effect: "none", message, detail };
56
- if ((fact.causeCode && UNREACHABLE_CAUSES.has(fact.causeCode)) || (fact.errorName && UNREACHABLE_NAMES.has(fact.errorName)))
57
- return { ok: false, code: "browser_unavailable", retryable: false, effect, message: "The browser could not be reached on this lane. The browser plane is unavailable for this run; use web_fetch or executor tools.", detail };
58
- return { ok: false, code: effectful ? "code_error" : "command_failed", retryable: true, effect, message: effectful ? `Your browser code threw: ${message.slice(0, 600)}` : `The browser call failed: ${message.slice(0, 600)}`, detail };
64
+ return browserFailure("stale_snapshot", message, { retryable: true, detail });
65
+ if ((fact.causeCode && UNREACHABLE_CAUSES.has(fact.causeCode)) || (fact.errorName && UNREACHABLE_NAMES.has(fact.errorName)) || lostLoopback(error))
66
+ return browserFailure("browser_unavailable", "The browser could not be reached on this lane. The browser plane is unavailable for this run; use web_fetch or executor tools.", { effect, detail });
67
+ return browserFailure(effectful ? "code_error" : "command_failed", effectful ? `Your browser code threw: ${message.slice(0, 600)}` : `The browser call failed: ${message.slice(0, 600)}`, { retryable: true, effect, detail });
59
68
  }
@@ -1,4 +1,4 @@
1
- import type { BrowserFailure } from "./failures.js";
1
+ import { type BrowserFailure } from "./failures.js";
2
2
  export type RepeatGuard = {
3
3
  check(tool: string, args: unknown): BrowserFailure | null;
4
4
  note(tool: string, args: unknown, failure: BrowserFailure | null): void;
@@ -1,3 +1,4 @@
1
+ import { browserFailure } from "./failures.js";
1
2
  export function createRepeatGuard() {
2
3
  const strikes = new Map();
3
4
  const keyOf = (tool, args) => `${tool}:${JSON.stringify(args ?? {})}`;
@@ -6,7 +7,7 @@ export function createRepeatGuard() {
6
7
  const prior = strikes.get(keyOf(tool, args));
7
8
  if (!prior || prior.count < 2)
8
9
  return null;
9
- return { ok: false, code: "refused", retryable: false, effect: "none", message: `Refused: ${tool} with these exact arguments already failed ${prior.count} times with the same error ("${prior.error.slice(0, 200)}"). Change approach: snapshot again and use current IDs, change the code or the URL, browser_relaunch({verified:true}) if the site blocks you, or fall back to web_fetch.` };
10
+ return browserFailure("refused", `Refused: ${tool} with these exact arguments already failed ${prior.count} times with the same error ("${prior.error.slice(0, 200)}"). Change approach: snapshot again and use current IDs, change the code or the URL, browser_relaunch({verified:true}) if the site blocks you, or fall back to web_fetch.`);
10
11
  },
11
12
  note(tool, args, failure) {
12
13
  if (failure?.code === "aborted")