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

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,13 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.1.0-beta.14 (2026-10-16)
6
+
7
+ - 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.
8
+ - 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.
9
+ - `@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.
10
+ - `@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`.
11
+
5
12
  ## 0.1.0-beta.13 (2026-10-14)
6
13
 
7
14
  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,7 @@ 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
30
 
31
31
  ## Quick start
32
32
 
@@ -206,6 +206,7 @@ const harness = await Harness.open(storage, { models, registry }, context);
206
206
  await browser.reconcile(harness, () => true, context); // settles what a dead process left
207
207
  // A conversation selects the extension and writes its BrowserConfig in its creating commit (`browser.docs.Config`);
208
208
  // when it ends: `await browser.release(conversation, "close", context)`.
209
+ // Before `harness.close()`: `await browser.drain(harness, context)`, so the releases reach the provider.
209
210
  ```
210
211
 
211
212
  `createBrowserExtension` takes no key and sends nothing anywhere but the provider you give it. The options:
@@ -226,10 +227,12 @@ await browser.reconcile(harness, () => true, context); // settles what a dead
226
227
  Per conversation, the host writes a `BrowserConfig` (`label`, `run`, and the policy: proxies, verified, captcha, geolocation,
227
228
  region, a raw context id, the session timeout, the idle release and the batch timeout; `DEFAULT_BROWSER_POLICY` holds the
228
229
  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.
230
+ selects the extensions for it, and calls `handle.release(conversation, "close", ctx)` when the conversation ends. Releases run
231
+ as background tasks, which `waitForIdle` skips and closing the harness aborts: before it closes, a host calls
232
+ `handle.drain(harness, ctx, signal?)`, which resolves once none is live. At run open, after the extensions are installed and
233
+ before anything resumes, it calls `handle.reconcile(harness, isActive, ctx)`, and every session a dead process left is bound,
234
+ kept or released. The host wraps the tools (`handle.tools`) with its own policy: pause, call records, a result cap, media for
235
+ the route.
233
236
 
234
237
  A host with its own provider implements `BrowserProvider`: `name`, `caps`, `create` (at most once, the tag stamped on the
235
238
  provider's side), `findByTag`, `status`, `attach`, `release`, and optionally `liveView`, `recordings`, `downloads`, `fetch`
@@ -281,8 +284,7 @@ A session is captured from the moment it is created or reattached (so after a ki
281
284
  - **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
285
  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
286
  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
287
+ 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
288
  fields, `one-time-code` fields and fields named like a code (name, id, `<label>`, `aria-labelledby`, `aria-label` or placeholder says otp, totp,
287
289
  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
290
  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 +298,24 @@ A session is captured from the moment it is created or reattached (so after a ki
296
298
  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
299
  - `frames.watch(...).release` ends the capture, and writes the `session_released` gap, once the provider has released the session: a release it
298
300
  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.
301
+ - **`frame.track`** (a WebM per session with an index) is made at export, from the recorded frames, by `exportFrameTracks`:
302
+
303
+ ```js
304
+ import { exportFrameTracks } from "@parcha/pi-browser/recorder";
305
+ const tracks = await exportFrameTracks({ lines, readBlob: (sha256) => bytesOfBlob(sha256), endAt: recordingEndMs, fps: 10 });
306
+ for (const { line, blobs } of tracks) { /* line is the frame.track line; blobs holds the WebM and its index by sha256 */ }
307
+ ```
308
+
309
+ 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
310
+ 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
311
+ `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
312
+ 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
313
+ `{ kind: "frame.track", t: <the track's end>, conv, data: { session, fps, from, to }, blobs: [<webm sha256>, <index sha256>] }`; the index (JSON) lists every
314
+ 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
315
+ 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`.
316
+ 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`
317
+ only, with fixed arguments and no URL, a timeout (`timeoutMs`, 120 s) and an `AbortSignal`; a failure is a `TrackExportError` (`ffmpeg_missing`,
318
+ `ffmpeg_failed`, `ffmpeg_timeout`, `aborted`) and writes nothing.
300
319
 
301
320
  ## How it compares
302
321
 
@@ -67,6 +67,7 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
67
67
  close(reason: ReleaseReason): Promise<void>;
68
68
  dispatching(): Promise<void>;
69
69
  journal(): Promise<void>;
70
+ mark(): Promise<void>;
70
71
  settle(): Promise<void>;
71
72
  navigated(url: string): Promise<void>;
72
73
  ended(): Promise<boolean>;
@@ -5,7 +5,7 @@ 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
7
  import { BrowserFailureError, closeDriver, custodyTools, newSessionRecord, notices, sessionSpec, } from "./core/custody.js";
8
- import { classifyBrowserError } from "./core/failures.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";
@@ -84,7 +84,7 @@ export class LocalCustody {
84
84
  const provider = await this.d.provider();
85
85
  const tag = leaseTag("pib", this.d.config.run, randomUUID().slice(0, 8), ++this.seq);
86
86
  const spec = sessionSpec(this.d.config, tag, overrides);
87
- const record = newSessionRecord({ plane: "browser", tag, provider: provider.name, spec, at: now() });
87
+ const record = newSessionRecord({ plane: "browser", tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
88
88
  this.save(record);
89
89
  const signal = AbortSignal.any([this.d.signal, AbortSignal.timeout(CREATE_DEADLINE_MS)]);
90
90
  let live = null;
@@ -206,6 +206,7 @@ export class LocalCustody {
206
206
  }
207
207
  async dispatching() { }
208
208
  async journal() { }
209
+ async mark() { }
209
210
  async settle() { }
210
211
  async navigated(url) { if (this.live)
211
212
  this.live.record.lastUrl = scrubPageUrl(url, this.d.redact); }
@@ -334,6 +335,7 @@ function registerTool(pi, contract, runtimeOf) {
334
335
  export function createBrowserExtension(options = {}) {
335
336
  const env = options.env ?? process.env;
336
337
  const policy = { ...DEFAULT_BROWSER_POLICY, ...(env.PI_BROWSER_PROXIES === "1" ? { proxies: true } : {}), ...options.policy };
338
+ // pi checks a call's arguments against the tool's schema before execute, so each implementation receives its own shape.
337
339
  const impls = { ...custodyTools, ...pageTools() };
338
340
  return function piBrowser(pi) {
339
341
  let runtime = null;
@@ -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;
@@ -47,9 +48,13 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
47
48
  codeSha: string;
48
49
  url: string | null;
49
50
  observed: boolean;
51
+ watched: boolean;
50
52
  }): Promise<void>;
51
53
  journal(row: SentEffect): Promise<void>;
52
- settle(): Promise<void>;
54
+ /** A journal entry's next step, by its call: the action returned, its cut was told, or an identical action was refused. */
55
+ mark(step: "finished" | "told" | "refused", callId: string): Promise<void>;
56
+ /** Clears the journal entry of that call only: another action's entry, journaled meanwhile, stays. */
57
+ settle(callId: string): Promise<void>;
53
58
  navigated(url: string): Promise<void>;
54
59
  /** When the provider reports the session ended, custody records it and the next call opens a fresh one. */
55
60
  ended(): Promise<boolean>;
@@ -89,6 +94,7 @@ export declare function newSessionRecord(input: {
89
94
  provider: string;
90
95
  spec: SessionSpec;
91
96
  at: string;
97
+ honours?: ProviderCaps["settings"];
92
98
  }): SessionRecord;
93
99
  export declare function moveRecord(record: SessionRecord, next: {
94
100
  state: LeaseState;
@@ -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,
42
+ },
43
+ navigation: [], lastUrl: null, pendingEffect: null, spent: startSpent(input.at),
40
44
  };
41
45
  }
42
46
  export function moveRecord(record, next) {
@@ -71,7 +75,7 @@ export function sessionSpec(config, tag, overrides = {}) {
71
75
  export function relaunchRefusal(policy, overrides) {
72
76
  if (!overrides.geolocation || policy.proxies)
73
77
  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." };
78
+ 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
79
  }
76
80
  /** An ISO alpha-2 country, a US state abbreviation, a city in capitals; null when the country is not two letters. */
77
81
  export function normalizeGeolocation(raw) {
@@ -109,7 +113,7 @@ export const custodyTools = {
109
113
  async browser_relaunch(args, port) {
110
114
  const geolocation = args.geolocation === undefined ? undefined : normalizeGeolocation(args.geolocation);
111
115
  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);
116
+ return text(browserFailure("refused", 'browser_relaunch: geolocation needs a two-letter ISO country code (e.g. {country: "GB"}).'), true);
113
117
  try {
114
118
  // A relaunch that names no `verified` keeps the run's policy: an omitted flag never downgrades a Verified session.
115
119
  const { sessionId, record } = await port.relaunch({ ...(args.verified !== undefined ? { verified: args.verified === true } : {}), ...(geolocation ? { geolocation } : {}) });
@@ -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")
@@ -1,5 +1,23 @@
1
1
  import type { LeaseRef, LeaseState, ResourceStatus } from "./lease.js";
2
- import type { PriceState, ToolUsage } from "./usage.js";
2
+ export type PriceState = "priced" | "unpriced" | "invalid";
3
+ export type PiUsage = {
4
+ input: 0;
5
+ output: 0;
6
+ cacheRead: 0;
7
+ cacheWrite: 0;
8
+ totalTokens: 0;
9
+ cost: {
10
+ input: 0;
11
+ output: 0;
12
+ cacheRead: 0;
13
+ cacheWrite: 0;
14
+ total: number;
15
+ };
16
+ };
17
+ export type ToolUsage = {
18
+ usage: PiUsage;
19
+ state: PriceState;
20
+ };
3
21
  export type Geo = {
4
22
  country: string;
5
23
  state?: string;
@@ -65,6 +83,15 @@ export type ProviderCaps = {
65
83
  survivesDisconnect: boolean;
66
84
  releaseIsAsync: boolean;
67
85
  extension: "uploaded-per-launch" | "preinstalled" | "loaded-locally";
86
+ /** The session settings this provider applies; a setting left out is applied. */
87
+ settings?: Partial<SessionSettingsSupport>;
88
+ };
89
+ export type SessionSettingsSupport = {
90
+ proxies: boolean;
91
+ verified: boolean;
92
+ geolocation: boolean;
93
+ region: boolean;
94
+ context: boolean;
68
95
  };
69
96
  export type LiveView = {
70
97
  fullscreen: string | null;
@@ -216,7 +243,10 @@ export type SentEffect = {
216
243
  held: "pending" | "allowed" | "denied" | null;
217
244
  irreversible: number | null;
218
245
  };
219
- /** `observed`: a holding observer committed each request before it left the browser. */
246
+ /** A replay-unsafe page action's journal entry. `observed`: a holding observer committed each request before it left the
247
+ * browser; `watched`: an observer recorded the requests it sent, holding them or not. `incarnation`: the custody process that wrote it; an entry from an earlier one belongs to a resumed run.
248
+ * `after`: the conversation's newest entry when it was journaled, where a resumed run's look for its answer starts.
249
+ * `finished`: the action returned. `told` and `refused`: how far a cut has been answered. */
220
250
  export type PendingEffect = {
221
251
  callId: string;
222
252
  codeSha: string;
@@ -224,6 +254,25 @@ export type PendingEffect = {
224
254
  at: string;
225
255
  observed?: boolean;
226
256
  sent?: SentEffect[];
257
+ watched?: boolean;
258
+ incarnation?: string;
259
+ after?: number;
260
+ finished?: boolean;
261
+ told?: boolean;
262
+ refused?: boolean;
263
+ };
264
+ /** A cut action's facts, beside the notice in the call's `details.pendingEffect`. `sent` is null when no observer ran, so
265
+ * an unknown never reads as none. */
266
+ export type PendingEffectFacts = {
267
+ callId: string;
268
+ urlAtDispatch: string | null;
269
+ urlNow: string;
270
+ observed: boolean;
271
+ sent: Array<{
272
+ method: string;
273
+ url: string;
274
+ held: SentEffect["held"];
275
+ }> | null;
227
276
  };
228
277
  export type SessionsState = {
229
278
  /** Index into `sessions` of each plane's current session. */
@@ -1,8 +1,10 @@
1
1
  import { type BrowserDriver, type CustodyPort, type ToolOutput } from "./custody.js";
2
2
  import { type EvidenceSink } from "./evidence.js";
3
3
  import type { Decisions } from "./decisions.js";
4
+ import { type RepeatGuard } from "./guard.js";
4
5
  import { type ScreenshotOptions } from "./images.js";
5
6
  import { type Redact } from "./redact.js";
7
+ import type { Geo } from "./host.js";
6
8
  export type PageDriver = BrowserDriver & {
7
9
  snapshot(options?: {
8
10
  includeIframes?: boolean;
@@ -33,5 +35,38 @@ export type ToolCall = {
33
35
  evidence: EvidenceSink;
34
36
  classifyPage?: Decisions["classifyPage"];
35
37
  };
36
- export type ToolImpl<D extends BrowserDriver = BrowserDriver> = (args: any, port: CustodyPort<D>, call: ToolCall) => Promise<ToolOutput>;
37
- export declare function pageTools(): Record<"snapshot" | "run" | "screenshot" | "browser_read", ToolImpl<PageDriver>>;
38
+ export type ToolImpl<D extends BrowserDriver = BrowserDriver, A = unknown> = (args: A, port: CustodyPort<D>, call: ToolCall) => Promise<ToolOutput>;
39
+ /** Each browser tool's arguments, as its contract's schema admits them. */
40
+ export type BrowserToolArgs = {
41
+ snapshot: {
42
+ includeIframes?: boolean;
43
+ };
44
+ run: {
45
+ code?: string;
46
+ actions?: unknown[];
47
+ };
48
+ screenshot: {
49
+ fullPage?: boolean;
50
+ type?: "png" | "jpeg";
51
+ quality?: number;
52
+ ask?: string;
53
+ };
54
+ browser_read: {
55
+ what?: (typeof WHATS)[number];
56
+ };
57
+ browser_release: Record<string, never>;
58
+ browser_relaunch: {
59
+ verified?: boolean;
60
+ geolocation?: Geo;
61
+ };
62
+ browser_downloads: Record<string, never>;
63
+ };
64
+ export type BrowserToolImpls<D extends BrowserDriver = BrowserDriver> = {
65
+ [K in keyof BrowserToolArgs]: ToolImpl<D, BrowserToolArgs[K]>;
66
+ };
67
+ declare const WHATS: readonly ["markdown", "text", "html", "url", "title"];
68
+ /** `guards` holds each conversation's repeat guard; a host that owns the conversation's lifecycle passes it to evict one. */
69
+ export declare function pageTools({ guards }?: {
70
+ guards?: Map<number, RepeatGuard>;
71
+ }): Pick<BrowserToolImpls<PageDriver>, "snapshot" | "run" | "screenshot" | "browser_read">;
72
+ export {};