@parcha/pi-browser 0.1.0-beta.31 → 0.1.0-beta.32

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 (47) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/NOTICE +4 -4
  3. package/README.md +38 -12
  4. package/dist/coding-agent.d.ts +1 -0
  5. package/dist/coding-agent.js +2 -2
  6. package/dist/core/contract.js +1 -1
  7. package/dist/core/custody.d.ts +7 -2
  8. package/dist/core/custody.js +7 -3
  9. package/dist/core/downloads.d.ts +7 -0
  10. package/dist/core/downloads.js +13 -1
  11. package/dist/core/driving-guard.d.ts +20 -0
  12. package/dist/core/driving-guard.js +175 -23
  13. package/dist/core/driving.d.ts +56 -2
  14. package/dist/core/driving.js +189 -10
  15. package/dist/core/effects.d.ts +80 -6
  16. package/dist/core/effects.js +374 -41
  17. package/dist/core/failures.d.ts +15 -1
  18. package/dist/core/failures.js +7 -0
  19. package/dist/core/host.d.ts +11 -2
  20. package/dist/core/tools.d.ts +14 -0
  21. package/dist/core/tools.js +42 -8
  22. package/dist/driver/page-driver.js +77 -4
  23. package/dist/driver/sealed.d.ts +4 -12
  24. package/dist/driver/sealed.js +23 -37
  25. package/dist/driver/stagehand.d.ts +10 -15
  26. package/dist/driver/stagehand.js +19 -17
  27. package/dist/durable/result.d.ts +1 -2
  28. package/dist/durable/result.js +2 -2
  29. package/dist/durable/store.d.ts +4 -1
  30. package/dist/durable/store.js +16 -11
  31. package/dist/durable.d.ts +14 -1
  32. package/dist/durable.js +39 -12
  33. package/dist/live-view/index.d.ts +2 -1
  34. package/dist/live-view/index.js +1 -0
  35. package/dist/live-view/protocol.d.ts +38 -6
  36. package/dist/live-view/protocol.js +2 -0
  37. package/dist/live-view/server.d.ts +24 -1
  38. package/dist/live-view/server.js +131 -11
  39. package/dist/live-view/stream.js +16 -3
  40. package/dist/live-view/viewer.js +106 -13
  41. package/dist/providers/cdp.d.ts +0 -1
  42. package/dist/providers/cdp.js +33 -11
  43. package/dist/providers/worker-extension.d.ts +6 -0
  44. package/dist/providers/worker-extension.js +17 -4
  45. package/package.json +10 -10
  46. package/dist/driver/extension-worker.d.ts +0 -9
  47. package/dist/driver/extension-worker.js +0 -185
@@ -4,7 +4,10 @@ export type BrowserFailure = {
4
4
  ok: false;
5
5
  code: FailureCode;
6
6
  retryable: boolean;
7
- effect: "none" | "possibly_effected";
7
+ /** `partial`: a run of several actions stopped partway, the first `completed` of them done. */
8
+ effect: "none" | "possibly_effected" | "partial";
9
+ /** With `partial`: how many of the run's actions ran before it stopped. */
10
+ completed?: number;
8
11
  message: string;
9
12
  /** Provider or page text, at most 2,000 characters; redacted before it reaches the model. */
10
13
  detail?: string;
@@ -17,6 +20,17 @@ export type Next = {
17
20
  action: "drive_page" | "other_source" | "browser_relaunch";
18
21
  note: string;
19
22
  };
23
+ /** A run of several actions that stopped partway on an error a call's own handling must still see as it is (a dropped
24
+ * connection, whose driver is let go): the error is passed on as it is, marked with how many of the run's actions ran. */
25
+ export declare const PARTIAL: unique symbol;
26
+ export type PartialRun = {
27
+ completed: number;
28
+ of: number;
29
+ };
30
+ /** The mark PARTIAL left on `error`, if any. */
31
+ export declare const partialOf: (error: unknown) => PartialRun | undefined;
32
+ /** `failure` as a run stopped partway says it: partial, with how many ran, before its own words. */
33
+ export declare const asPartial: (failure: BrowserFailure, partial: PartialRun) => BrowserFailure;
20
34
  export declare const browserFailure: (code: FailureCode, message: string, options?: {
21
35
  retryable?: boolean;
22
36
  effect?: BrowserFailure["effect"];
@@ -5,6 +5,13 @@ export const FAILURE_CODES = Object.freeze([
5
5
  "browser_unavailable", "auth", "timeout", "aborted", "refused", "stale_snapshot", "session_ended",
6
6
  "session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited", "waiting_for_human",
7
7
  ]);
8
+ /** A run of several actions that stopped partway on an error a call's own handling must still see as it is (a dropped
9
+ * connection, whose driver is let go): the error is passed on as it is, marked with how many of the run's actions ran. */
10
+ export const PARTIAL = Symbol.for("pi-browser.partial");
11
+ /** The mark PARTIAL left on `error`, if any. */
12
+ export const partialOf = (error) => (error !== null && typeof error === "object" ? error[PARTIAL] : undefined);
13
+ /** `failure` as a run stopped partway says it: partial, with how many ran, before its own words. */
14
+ export const asPartial = (failure, partial) => ({ ...failure, effect: "partial", completed: partial.completed, message: `${partial.completed} of the ${partial.of} actions ran, then this one failed: ${failure.message}` });
8
15
  export const browserFailure = (code, message, options = {}) => ({ ok: false, code, retryable: options.retryable ?? false, effect: options.effect ?? "none", message, ...(options.detail === undefined ? {} : { detail: options.detail }) });
9
16
  /** The vendored facade's refusal texts (vendor/stagehand-facade/contract.ts), copied so the root entry does not load the facade; a test pins
10
17
  * them to the facade's own. */
@@ -86,7 +86,10 @@ export type AttachTarget = {
86
86
  headers?: Record<string, string>;
87
87
  expiresAt?: number;
88
88
  };
89
- extensionId?: string;
89
+ /** The browser's own DevTools URL, which Stagehand's extension inside the browser dials for its own connection; absent, it
90
+ * dials `sdkCdpUrl`. A proxy in front of the driver then carries both, and a drop that cuts both leaves the extension
91
+ * holding a client it can no longer see leave: Stagehand 4.4 then refuses every attach until its worker restarts. */
92
+ extensionCdpUrl?: string;
90
93
  };
91
94
  export type ProviderCaps = {
92
95
  timeoutModel: "wall-clock" | "inactivity";
@@ -127,10 +130,12 @@ export type Recording = {
127
130
  startedAt: string | null;
128
131
  durationS: number | null;
129
132
  };
133
+ /** `downloading`: the browser is still writing it; it is listed so the caller can say so, and is not read. */
130
134
  export type RemoteFile = {
131
135
  name: string;
132
136
  sizeBytes: number;
133
137
  modifiedAt: string | null;
138
+ downloading?: true;
134
139
  };
135
140
  export type FetchRequest = {
136
141
  url: string;
@@ -259,7 +264,11 @@ export interface HandoffPort {
259
264
  } | {
260
265
  refused: string;
261
266
  }>;
262
- outcome(interactionId: string, signal: AbortSignal): Promise<"pending" | HandoffOutcome>;
267
+ /** With `reason`: why, in the host's words, for the model (an ask the host ended at its spend cap). */
268
+ outcome(interactionId: string, signal: AbortSignal): Promise<"pending" | HandoffOutcome | {
269
+ outcome: HandoffOutcome;
270
+ reason: string;
271
+ }>;
263
272
  }
264
273
  export type ReleaseReason = "tool" | "idle" | "relaunch" | "close" | "ended" | "lost" | "create_failed";
265
274
  export type SessionRecord = {
@@ -41,15 +41,22 @@ export type PageDriver = BrowserDriver & {
41
41
  snapshot(options?: {
42
42
  includeIframes?: boolean;
43
43
  }): Promise<string>;
44
+ /** `checked`: an action after the first of a run of several, sent alone (driving-guard sends a batch one action at a time)
45
+ * after the whole batch was checked against the page's snapshot: the page's address, which the batch's own earlier
46
+ * actions may have moved (a same-page link), is not checked against the snapshot again. Its ids still are. */
44
47
  run(input: {
45
48
  code?: string;
46
49
  actions?: RunAction[];
50
+ checked?: true;
47
51
  }): Promise<unknown>;
48
52
  /** The page's URL, cheaply: no page content is read. */
49
53
  url(): Promise<string>;
50
54
  /** Drops every snapshot's element ids, so an action by an old id fails as a stale snapshot (a person changed the page, whatever its URL). Optional:
51
55
  * a driver without ids has none to drop. */
52
56
  forgetSnapshots?(): void;
57
+ /** Checks a run's actions against the page's latest snapshot (every id there, the page still its address) without
58
+ * sending any, failing as `run` would. Optional: a driver without it sends a run's actions as one batch. */
59
+ checkActions?(actions: RunAction[]): Promise<void>;
53
60
  screenshot(options: ScreenshotOptions): Promise<{
54
61
  data: string;
55
62
  mimeType: string;
@@ -134,6 +141,13 @@ type ReconnectTimings = {
134
141
  tryMs: number;
135
142
  backoffMs: readonly number[];
136
143
  };
144
+ type Lost = {
145
+ method: string;
146
+ url: string;
147
+ };
148
+ /** Told to a call whose page sent requests the browser lost before they left it (Chrome's network service restarted under
149
+ * them): they were not sent, so the model may send them again. */
150
+ export declare const lostRequests: (lost: readonly Lost[]) => string;
137
151
  export declare function pageTools({ guards, reconnect: timings, readDeadlineMs }?: {
138
152
  /** Each conversation's repeat guard; a host that owns the conversation's lifecycle passes it to evict one. */
139
153
  guards?: Map<number, RepeatGuard>;
@@ -2,7 +2,7 @@ import { setImmediate as yieldToLoop } from "node:timers/promises";
2
2
  import { BrowserFailureError, FenceRefusal, refusedError, loadedNoPage, passedThrough } from "./custody.js";
3
3
  import { defaultInline } from "./evidence.js";
4
4
  import { fetchDownloads } from "./downloads.js";
5
- import { browserFailure, classifyBrowserError, transportFactOf } from "./failures.js";
5
+ import { asPartial, browserFailure, classifyBrowserError, partialOf, transportFactOf } from "./failures.js";
6
6
  import { createRepeatGuard } from "./guard.js";
7
7
  import { regionOf } from "./clip.js";
8
8
  import { captureWithinBudget } from "./images.js";
@@ -57,6 +57,18 @@ const pause = (ms, signal) => new Promise((resolve) => {
57
57
  });
58
58
  const text = (value, isError = false) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) }], ...(isError ? { isError: true } : {}) });
59
59
  const withNews = (news, body) => (news ? `${news}\n\n${body}` : body);
60
+ const LOST = Symbol("lost requests");
61
+ /** An action's error carries the requests its call lost (`lost` is filled by the flush in the `finally` that follows the
62
+ * throw), so the failure answer still tells them. */
63
+ const withLost = (error, lost) => {
64
+ const carrier = error !== null && typeof error === "object" ? error : Object.assign(new Error(String(error)), { cause: error });
65
+ Object.defineProperty(carrier, LOST, { value: lost, configurable: true });
66
+ return carrier;
67
+ };
68
+ const lostOf = (error) => (error !== null && typeof error === "object" ? (error[LOST] ?? []) : []);
69
+ /** Told to a call whose page sent requests the browser lost before they left it (Chrome's network service restarted under
70
+ * them): they were not sent, so the model may send them again. */
71
+ export const lostRequests = (lost) => `The browser lost ${lost.length === 1 ? "a request" : `${lost.length} requests`} your page made before ${lost.length === 1 ? "the request" : "they"} left the browser: ${lost.map((r) => `${r.method} ${r.url}`).join(", ")}. Chrome's network service restarted while ${lost.length === 1 ? "it was" : "they were"} on ${lost.length === 1 ? "its" : "their"} way, so ${lost.length === 1 ? "the request was" : "the requests were"} not sent. Make ${lost.length === 1 ? "it" : "them"} again if you still need ${lost.length === 1 ? "it" : "them"}.`;
60
72
  /** A read of a browser that has loaded no page yet: it is fresh, and the next step is to navigate, to the replaced
61
73
  * session's last page when there is one. */
62
74
  function freshBrowser(replaced) {
@@ -207,8 +219,8 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
207
219
  if (call.signal?.aborted)
208
220
  break;
209
221
  }
210
- // The try's attach is bounded by what is left of the budget: one that waits on the browser (an earlier init still
211
- // finishing in it) stops there instead of running past it. The timer is a ref'd one, cleared when the try ends, so a
222
+ // The try's attach is bounded by what is left of the budget: one that waits on the browser (a connection held on
223
+ // the way) stops there instead of running past it. The timer is a ref'd one, cleared when the try ends, so a
212
224
  // reconnect in progress keeps the process alive (AbortSignal.timeout's timer does not, and Node 22 then drains).
213
225
  const deadline = new AbortController();
214
226
  const timer = setTimeout(() => deadline.abort(new DOMException("the reconnect's budget ran out", "TimeoutError")), Math.max(0, until - Date.now()));
@@ -257,7 +269,17 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
257
269
  const tell = (out) => (facts || previous ? { ...out, details: { ...out.details, ...(facts ? { pendingEffect: facts } : {}), ...(previous ? { previous_session: previous } : {}) } } : out);
258
270
  const done = (out) => { guard.note(tool, args, null); return tell(out); };
259
271
  // The notice leads a failure, never after its own keys: a call told nothing else first reads it.
260
- const fail = (failure) => { guard.note(tool, args, failure); return tell(text(news ? { notice: news, ...(previous ? { previous_session: previous } : {}), ...failure } : failure, true)); };
272
+ // A run of several actions that dropped partway (driving-guard's partway): its failure says how many ran.
273
+ let partial;
274
+ // Requests the failed action's call lost: told in the failure's message and listed in details, as on success.
275
+ let lostOnError = [];
276
+ const fail = (given) => {
277
+ const failure = partial ? asPartial(given, partial) : given;
278
+ guard.note(tool, args, failure);
279
+ const told = lostOnError.length ? { ...failure, message: `${failure.message} ${lostRequests(lostOnError)}` } : failure;
280
+ const out = tell(text(news ? { notice: news, ...(previous ? { previous_session: previous } : {}), ...told } : told, true));
281
+ return lostOnError.length ? { ...out, details: { ...out.details, lost: lostOnError } } : out;
282
+ };
261
283
  let cuts = [];
262
284
  // A look after a refusal settles every refused cut in the chain whose warning a saved answer had already told; one this call is
263
285
  // telling stays until a later look, so a process that dies before this answer is saved tells it again.
@@ -314,6 +336,8 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
314
336
  return await looked(effect === null ? await body(s, news) : await dispatched(tool, port, call, s, effect, () => body(s, news)));
315
337
  }
316
338
  catch (error) {
339
+ partial = partialOf(error);
340
+ lostOnError = lostOf(error);
317
341
  const failure = await failureOf(error, effectful, port, call, action);
318
342
  if (failure.code !== "browser_unavailable" || error instanceof BrowserFailureError)
319
343
  return fail(failure);
@@ -362,11 +386,15 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
362
386
  const codeSha = sha256Hex(JSON.stringify(args.code ?? args.actions));
363
387
  return perform("run", args, port, call, { effect: codeSha }, async (s, news) => {
364
388
  const sent = [];
365
- const stop = s.effects?.record((row) => { sent.push({ method: row.method, url: call.redact(`${row.origin}${row.path}`), held: row.held }); return port.journal(row); });
389
+ const lost = [];
390
+ const stop = s.effects?.record((row) => { sent.push({ method: row.method, url: call.redact(`${row.origin}${row.path}`), held: row.held }); return port.journal(row); }, (request) => { lost.push({ method: request.method, url: call.redact(`${request.origin}${request.path}`) }); });
366
391
  let value;
367
392
  try {
368
393
  value = await s.driver.run(args.code !== undefined ? { code: runnableCode(args.code) } : { actions: args.actions });
369
394
  }
395
+ catch (error) {
396
+ throw withLost(error, lost);
397
+ }
370
398
  finally {
371
399
  await s.effects?.flush(call.signal).catch(() => undefined);
372
400
  stop?.();
@@ -379,7 +407,8 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
379
407
  }
380
408
  const reported = args.actions !== undefined && value && typeof value === "object" && typeof value.url === "string" ? { ...value, url: pageUrl(call, value.url) } : value;
381
409
  const shown = typeof reported === "string" ? reported : reported === undefined ? "(run completed; the code returned no value: end it with `return <value>` to get one back)" : JSON.stringify(reported, null, 2) ?? String(reported);
382
- return { ...text(withNews(news, shown)), ...(sent.length ? { details: { sent } } : {}) };
410
+ const told = lost.length ? `${shown}\n\n${lostRequests(lost)}` : shown;
411
+ return { ...text(withNews(news, told)), ...(sent.length || lost.length ? { details: { ...(sent.length ? { sent } : {}), ...(lost.length ? { lost } : {}) } } : {}) };
383
412
  });
384
413
  },
385
414
  screenshot: (args, port, call) => {
@@ -442,15 +471,20 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT,
442
471
  if (!s.driver.setInputFiles)
443
472
  throw refusedError("This browser driver cannot set a file input.");
444
473
  const sent = [];
445
- const stop = s.effects?.record((row) => { sent.push({ method: row.method, url: call.redact(`${row.origin}${row.path}`), held: row.held }); return port.journal(row); });
474
+ const lost = [];
475
+ const stop = s.effects?.record((row) => { sent.push({ method: row.method, url: call.redact(`${row.origin}${row.path}`), held: row.held }); return port.journal(row); }, (request) => { lost.push({ method: request.method, url: call.redact(`${request.origin}${request.path}`) }); });
446
476
  try {
447
477
  await s.driver.setInputFiles(selector, { name: file.name, mimeType: file.mime, buffer: file.bytes });
448
478
  }
479
+ catch (error) {
480
+ throw withLost(error, lost);
481
+ }
449
482
  finally {
450
483
  await s.effects?.flush(call.signal).catch(() => undefined);
451
484
  stop?.();
452
485
  }
453
- return { content: [{ type: "text", text: JSON.stringify({ ok: true, uploaded, selector, ...(news ? { notice: news } : {}) }) }], details: { uploaded, ...(sent.length ? { sent } : {}) } };
486
+ const notice = [news, lost.length ? lostRequests(lost) : ""].filter(Boolean).join(" ");
487
+ return { content: [{ type: "text", text: JSON.stringify({ ok: true, uploaded, selector, ...(notice ? { notice } : {}) }) }], details: { uploaded, ...(sent.length ? { sent } : {}), ...(lost.length ? { lost } : {}) } };
454
488
  });
455
489
  },
456
490
  browser_downloads: (args, port, call) => perform("browser_downloads", {}, port, call, "read", async (s, news) => {
@@ -68,6 +68,8 @@ function bounded(stagehand, deadlines) {
68
68
  browser: overriding(stagehand.browser, { context: overriding(context, { activePage: async () => { const active = await context.activePage(); return active ? page(active) : active; } }) }),
69
69
  });
70
70
  }
71
+ /** How long a page has to say which document it shows before it is taken not to know. */
72
+ const DOCUMENT_MS = 5_000;
71
73
  /** `batchMs` bounds every run batch; the page calls' own deadlines are fixed but for tests. */
72
74
  export function pageDriver(stagehand, deadlines) {
73
75
  const host = bounded(stagehand, { snapshotMs: SNAPSHOT_MS, screenshotMs: SCREENSHOT_MS, ...deadlines });
@@ -82,9 +84,78 @@ export function pageDriver(stagehand, deadlines) {
82
84
  // In a batch of its own, which the browser runs once the new document is its page's.
83
85
  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 });
84
86
  const reads = documentReads(facade, newDocument);
87
+ const kept = () => facade.snapshotsByPage;
88
+ /** The document a page shows, by its own performance.timeOrigin: new on every navigation to a new document and on a
89
+ * reload, the same across a #hash change or history.pushState/replaceState (Chrome's per-document loaderId, which
90
+ * neither Stagehand's page nor a batch's page can be asked for). Null when the page does not say. */
91
+ const documentOf = async (page) => {
92
+ let timer;
93
+ try {
94
+ const late = new Promise((resolve) => { timer = setTimeout(() => resolve(null), DOCUMENT_MS); });
95
+ const origin = await Promise.race([Promise.resolve(page.evaluate("performance.timeOrigin")).catch(() => null), late]);
96
+ return typeof origin === "number" ? origin : null;
97
+ }
98
+ catch {
99
+ return null;
100
+ }
101
+ finally {
102
+ clearTimeout(timer);
103
+ }
104
+ };
105
+ /** By page, the document each snapshot was taken on (read once the snapshot is), and that snapshot's ids, to know it is
106
+ * still the facade's. Read beside the snapshot, never holding it up: a batch awaits it. */
107
+ const snapshotDocuments = new Map();
108
+ /** An action after the first of a batch checked as one (driving-guard): run by the facade with the snapshot taken as at
109
+ * the page's address now, for this action only, so an address the batch's own earlier actions moved is not a stale
110
+ * snapshot; then the snapshot's own address again, so a later call on the moved page is told to snapshot again. */
111
+ const afterChecked = async (actions) => {
112
+ const page = await active();
113
+ const snapshot = kept().get(page.pageId);
114
+ // Only on the snapshot's own document: an earlier action that loaded a new one (a link to another page, a reload)
115
+ // leaves the snapshot's ids pointing at nothing of this page's, so the batch stops before this action, as stale.
116
+ if (snapshot) {
117
+ const taken = snapshotDocuments.get(page.pageId);
118
+ const was = taken && taken.xpathById === snapshot.xpathById ? await taken.document : null;
119
+ const document = was === null ? null : await documentOf(page);
120
+ if (was === null || document !== was)
121
+ throw new Error(NAVIGATED_SNAPSHOT_ERROR);
122
+ }
123
+ const now = snapshot ? await page.url() : undefined;
124
+ if (!snapshot || now === snapshot.url)
125
+ return facade.runActions(actions);
126
+ kept().set(page.pageId, { ...snapshot, url: now });
127
+ try {
128
+ return await facade.runActions(actions);
129
+ }
130
+ finally {
131
+ const current = kept().get(page.pageId);
132
+ if (current && current.xpathById === snapshot.xpathById)
133
+ kept().set(page.pageId, { ...current, url: snapshot.url });
134
+ }
135
+ };
85
136
  return {
86
- snapshot: (snapshotOptions) => reads.snapshot(snapshotOptions),
87
- run: (input) => input.actions !== undefined ? facade.runActions(input.actions) : facade.run(input.code ?? ""),
137
+ snapshot: async (snapshotOptions) => {
138
+ const tree = await reads.snapshot(snapshotOptions);
139
+ const page = await active().catch(() => null);
140
+ const taken = page ? kept().get(page.pageId) : undefined;
141
+ if (page && taken)
142
+ snapshotDocuments.set(page.pageId, { xpathById: taken.xpathById, document: documentOf(page) });
143
+ return tree;
144
+ },
145
+ run: (input) => input.actions !== undefined ? (input.checked ? afterChecked(input.actions) : facade.runActions(input.actions)) : facade.run(input.code ?? ""),
146
+ // As the facade's own batch checks a run's actions before it sends any (runActionsNow): the active page's snapshot,
147
+ // the page still at its address, and every id in it. Read from the facade's snapshots, as forgetSnapshots does.
148
+ checkActions: async (actions) => {
149
+ const page = await active();
150
+ const snapshot = facade.snapshotsByPage.get(page.pageId);
151
+ if (!snapshot)
152
+ throw new Error(NO_HYDRATED_SNAPSHOT_ERROR);
153
+ if ((await page.url()) !== snapshot.url)
154
+ throw new Error(NAVIGATED_SNAPSHOT_ERROR);
155
+ for (const action of actions)
156
+ if (!snapshot.xpathById[action.id])
157
+ throw new Error(staleSnapshotIdError(action.id));
158
+ },
88
159
  url: async () => documentUrl(stagehand, await active()),
89
160
  // The facade keeps each page's last snapshot's ids for its own actions; with none, an action by id fails NO_HYDRATED (a stale snapshot).
90
161
  forgetSnapshots: () => { facade.snapshotsByPage.clear(); },
@@ -122,7 +193,9 @@ export function pageDriver(stagehand, deadlines) {
122
193
  page: () => reads.page(),
123
194
  // An upload is effectful: past its deadline it fails as unanswered, and the page tools tell it as possibly applied.
124
195
  setInputFiles: async (selector, file) => { await withinDeadline((await active()).locator(selector).setInputFiles({ name: file.name, mimeType: file.mimeType, buffer: file.buffer }), uploadMs, "locator.setInputFiles"); },
125
- // Stagehand's own close keeps the browser for another attach; the browser's close would end it.
126
- close: () => stagehand.close(),
196
+ // Stagehand 4.4 lets one client attach to a browser at a time, and its close leaves this client attached: disconnect closes
197
+ // the instance (waiting 10 s at most), detaches the client and closes the socket, so the next attach is allowed. The
198
+ // browser keeps running; the browser's own close would end it.
199
+ close: () => stagehand.browser.disconnect(),
127
200
  };
128
201
  }
@@ -1,16 +1,8 @@
1
- /** What Stagehand's extension answers an init while another is still running in it. */
2
- export declare const INIT_IN_PROGRESS = "Stagehand initialization is already in progress";
3
- /** Stagehand's own init deadline: an init the extension is still running has ended by then. */
4
- export declare const IN_FLIGHT_INIT_MS = 60000;
5
- /** The extension refused an init because another is still running in it (its JSON-RPC error, as Stagehand's cause). */
6
- export declare const initInProgress: (error: unknown) => boolean;
7
1
  /** A failed attach step names where it went: Stagehand reports a failed open as "[object Object]", and the socket's error
8
2
  * has no address. */
9
3
  export declare const attachStep: (host: string) => <T>(step: Promise<T>) => Promise<T>;
10
- /** A cancelled call never starts an init of its own, however the wait ended. */
4
+ /** A cancelled call never starts a step of its own, however the wait ended. */
11
5
  export declare function throwIfCancelled(signal?: AbortSignal): void;
12
- /** The sealed Stagehand, created once more when the extension is still running an earlier attach's init: an attach that
13
- * gave up (a dropped connection, a deadline) left its init running there, and `waitForThatInit` (a close, which queues
14
- * behind that init, so its reply means the init has ended) waits it out first. A second refusal is the browser still
15
- * busy, retryable. */
16
- export declare function createSealed<S>(create: () => Promise<S>, waitForThatInit: () => Promise<unknown>, host: string, signal?: AbortSignal): Promise<S>;
6
+ /** `step`, or the cancel when `signal` ends first: the call stops at once, and a step that still succeeds later is handed to
7
+ * `release` (Stagehand's own steps take no signal, and one left attached would refuse the next attach). */
8
+ export declare function untilCancelled<T>(step: Promise<T>, signal: AbortSignal | undefined, release: (late: T) => unknown): Promise<T>;
@@ -1,47 +1,33 @@
1
- // The steps of attaching a sealed Stagehand that can fail on their own: naming where a failed step went, stopping a
2
- // cancelled attach, and creating the instance once more when the extension is still running an earlier attach's init.
3
- import { BrowserFailureError } from "../core/custody.js";
4
- import { browserFailure } from "../core/failures.js";
5
- /** What Stagehand's extension answers an init while another is still running in it. */
6
- export const INIT_IN_PROGRESS = "Stagehand initialization is already in progress";
7
- /** Stagehand's own init deadline: an init the extension is still running has ended by then. */
8
- export const IN_FLIGHT_INIT_MS = 60_000;
9
- /** The extension refused an init because another is still running in it (its JSON-RPC error, as Stagehand's cause). */
10
- export const initInProgress = (error) => {
11
- const cause = error?.cause;
12
- return !!cause && typeof cause === "object" && typeof cause.code === "number" && cause.message === INIT_IN_PROGRESS;
13
- };
1
+ // The steps of attaching a sealed Stagehand that can fail on their own: naming where a failed step went, and stopping a
2
+ // cancelled attach without leaving anything attached to the browser.
14
3
  /** A failed attach step names where it went: Stagehand reports a failed open as "[object Object]", and the socket's error
15
4
  * has no address. */
16
5
  export const attachStep = (host) => (step) => step.catch((error) => {
17
6
  throw new Error(`attaching to the browser at ${host} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
18
7
  });
19
- /** A cancelled call never starts an init of its own, however the wait ended. */
8
+ const cancelled = (signal) => signal.reason instanceof Error ? signal.reason : Object.assign(new Error("the attach was cancelled"), { name: "AbortError" });
9
+ /** A cancelled call never starts a step of its own, however the wait ended. */
20
10
  export function throwIfCancelled(signal) {
21
11
  if (signal?.aborted)
22
- throw signal.reason instanceof Error ? signal.reason : Object.assign(new Error("the attach was cancelled"), { name: "AbortError" });
12
+ throw cancelled(signal);
23
13
  }
24
- /** The sealed Stagehand, created once more when the extension is still running an earlier attach's init: an attach that
25
- * gave up (a dropped connection, a deadline) left its init running there, and `waitForThatInit` (a close, which queues
26
- * behind that init, so its reply means the init has ended) waits it out first. A second refusal is the browser still
27
- * busy, retryable. */
28
- export async function createSealed(create, waitForThatInit, host, signal) {
29
- try {
30
- return await create();
31
- }
32
- catch (error) {
33
- if (!initInProgress(error))
34
- throw error;
35
- }
36
- throwIfCancelled(signal);
37
- await waitForThatInit();
38
- throwIfCancelled(signal);
39
- try {
40
- return await create();
41
- }
42
- catch (again) {
43
- if (!initInProgress(again))
44
- throw again;
45
- throw new BrowserFailureError(browserFailure("browser_unavailable", `The browser at ${host} is still finishing an earlier connection after ${IN_FLIGHT_INIT_MS / 1_000} s. Call again in a moment, or call browser_relaunch for a fresh session.`, { retryable: true }));
14
+ /** `step`, or the cancel when `signal` ends first: the call stops at once, and a step that still succeeds later is handed to
15
+ * `release` (Stagehand's own steps take no signal, and one left attached would refuse the next attach). */
16
+ export function untilCancelled(step, signal, release) {
17
+ if (!signal)
18
+ return step;
19
+ if (signal.aborted) {
20
+ step.then((late) => release(late), () => undefined).catch(() => undefined);
21
+ return Promise.reject(cancelled(signal));
46
22
  }
23
+ return new Promise((resolve, reject) => {
24
+ let over = false;
25
+ const onAbort = () => { over = true; reject(cancelled(signal)); };
26
+ signal.addEventListener("abort", onAbort, { once: true });
27
+ step.then((value) => { signal.removeEventListener("abort", onAbort); if (over)
28
+ Promise.resolve().then(() => release(value)).catch(() => undefined);
29
+ else
30
+ resolve(value); }, (error) => { signal.removeEventListener("abort", onAbort); if (!over)
31
+ reject(error); });
32
+ });
47
33
  }
@@ -1,12 +1,7 @@
1
1
  import { type DriverFactory } from "../core/custody.js";
2
2
  import type { PageDriver } from "../core/tools.js";
3
- /** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
4
- export declare const STAGEHAND_TELEMETRY: {
5
- readonly traces: {
6
- readonly endpoint: "http://127.0.0.1:9/v1/traces";
7
- };
8
- };
9
3
  export declare 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.";
4
+ /** No telemetry is given, and Stagehand 4.4 starts its trace exporter only for an endpoint it is given: no span is sent. */
10
5
  export declare const SEALED_STAGEHAND: {
11
6
  readonly logging: {
12
7
  readonly level: "off";
@@ -15,13 +10,13 @@ export declare const SEALED_STAGEHAND: {
15
10
  readonly model: {
16
11
  readonly generate: () => Promise<never>;
17
12
  };
18
- readonly telemetry: {
19
- readonly traces: {
20
- readonly endpoint: "http://127.0.0.1:9/v1/traces";
21
- };
22
- };
23
13
  };
24
- /** What Stagehand's extension answers an init while another is still running in it. */
25
- export declare const STAGEHAND_INIT_IN_PROGRESS = "Stagehand initialization is already in progress";
26
- /** The batch deadline comes from `DriverOptions`; a caller that passes none gets the facade's 60 s. */
27
- export declare function stagehandDriver(): DriverFactory<PageDriver>;
14
+ type StagehandModule = Pick<typeof import("@browserbasehq/stagehand"), "localBrowser" | "Stagehand">;
15
+ /** The batch deadline comes from `DriverOptions`; a caller that passes none gets the facade's 60 s. Stagehand allows one
16
+ * client per browser: an attach that fails or is cancelled after it connected disconnects again, and only then fails, so
17
+ * the next attach never meets its slot still taken (Stagehand bounds the disconnect: 10 s for the detach). `internals` is
18
+ * for tests: the Stagehand module the driver uses. */
19
+ export declare function stagehandDriver(internals?: {
20
+ stagehand?: () => Promise<StagehandModule>;
21
+ }): DriverFactory<PageDriver>;
22
+ export {};
@@ -1,28 +1,30 @@
1
- import { INERT_TRACE_ENDPOINT } from "../core/effects.js";
2
- import { installedExtension } from "./extension-worker.js";
3
1
  import { pageDriver } from "./page-driver.js";
4
- import { attachStep, createSealed, IN_FLIGHT_INIT_MS, INIT_IN_PROGRESS } from "./sealed.js";
5
- /** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
6
- export const STAGEHAND_TELEMETRY = { traces: { endpoint: INERT_TRACE_ENDPOINT } };
2
+ import { attachStep, throwIfCancelled, untilCancelled } from "./sealed.js";
7
3
  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.";
4
+ /** No telemetry is given, and Stagehand 4.4 starts its trace exporter only for an endpoint it is given: no span is sent. */
8
5
  export const SEALED_STAGEHAND = {
9
6
  logging: { level: "off" },
10
7
  cache: false,
11
8
  model: { generate: async () => { throw new Error(STAGEHAND_INFERENCE_REFUSED); } },
12
- telemetry: STAGEHAND_TELEMETRY,
13
9
  };
14
- /** What Stagehand's extension answers an init while another is still running in it. */
15
- export const STAGEHAND_INIT_IN_PROGRESS = INIT_IN_PROGRESS;
16
- /** The batch deadline comes from `DriverOptions`; a caller that passes none gets the facade's 60 s. */
17
- export function stagehandDriver() {
10
+ /** The batch deadline comes from `DriverOptions`; a caller that passes none gets the facade's 60 s. Stagehand allows one
11
+ * client per browser: an attach that fails or is cancelled after it connected disconnects again, and only then fails, so
12
+ * the next attach never meets its slot still taken (Stagehand bounds the disconnect: 10 s for the detach). `internals` is
13
+ * for tests: the Stagehand module the driver uses. */
14
+ export function stagehandDriver(internals = {}) {
18
15
  return async (target, signal, options) => {
19
- const { localBrowser, Stagehand } = await import("@browserbasehq/stagehand");
16
+ const { localBrowser, Stagehand } = await (internals.stagehand ?? (() => import("@browserbasehq/stagehand")))();
20
17
  const host = new URL(target.dial?.url ?? target.sdkCdpUrl).host;
21
- const step = attachStep(host);
22
- // An id the provider supplies names a held extension too, so its worker is reset as well.
23
- const extensionId = await step(installedExtension(target.sdkCdpUrl, signal, target.extensionId));
24
- const browser = await step(localBrowser.connect({ cdpUrl: target.sdkCdpUrl, ...(extensionId ? { extensionId } : {}) }));
25
- const stagehand = await createSealed(() => Stagehand.create({ browser, ...SEALED_STAGEHAND }), () => step(installedExtension(target.sdkCdpUrl, signal, extensionId ?? undefined, IN_FLIGHT_INIT_MS)), host, signal);
26
- return pageDriver(stagehand, { batchMs: options?.batchTimeoutMs ?? 60_000 });
18
+ throwIfCancelled(signal);
19
+ const connecting = localBrowser.connect({ cdpUrl: target.sdkCdpUrl, ...(target.extensionCdpUrl ? { extensionCdpUrl: target.extensionCdpUrl } : {}) });
20
+ const browser = await untilCancelled(attachStep(host)(connecting), signal, (late) => late.disconnect());
21
+ try {
22
+ const stagehand = await untilCancelled(Stagehand.create({ browser, ...SEALED_STAGEHAND }), signal, () => undefined);
23
+ return pageDriver(stagehand, { batchMs: options?.batchTimeoutMs ?? 60_000 });
24
+ }
25
+ catch (error) {
26
+ await browser.disconnect().catch(() => undefined);
27
+ throw error;
28
+ }
27
29
  };
28
30
  }
@@ -1,6 +1,5 @@
1
1
  import type { ToolOutput } from "../core/custody.js";
2
- /** pi-durable 1.0 and 1.1 read a tool result's `content`; 1.2 reads `output` and treats a result that lacks it as empty. The model's text goes under both keys. */
2
+ /** A tool result's blocks as pi-durable reads them: its `output`. */
3
3
  export declare const forModel: (content: ToolOutput["content"]) => {
4
- content: ToolOutput["content"];
5
4
  output: ToolOutput["content"];
6
5
  };
@@ -1,2 +1,2 @@
1
- /** pi-durable 1.0 and 1.1 read a tool result's `content`; 1.2 reads `output` and treats a result that lacks it as empty. The model's text goes under both keys. */
2
- export const forModel = (content) => ({ content, output: content });
1
+ /** A tool result's blocks as pi-durable reads them: its `output`. */
2
+ export const forModel = (content) => ({ output: content });
@@ -39,6 +39,7 @@ export type HandoffInput = {
39
39
  };
40
40
  type HandoffResult = {
41
41
  outcome: HandoffOutcome;
42
+ reason?: string;
42
43
  };
43
44
  export type StoreDeps = {
44
45
  name: string;
@@ -56,8 +57,10 @@ export type StoreDeps = {
56
57
  handoff?: HandoffPort;
57
58
  /** A handoff's session came back under `fence`. */
58
59
  handedBack?(tag: string, fence: number): void;
60
+ /** A release task (an attempt, or its abort handler) had the provider release `tag`'s session, and the provider answered. */
61
+ stopped?(tag: string): void;
59
62
  };
60
- export declare function custodyStore({ name, Config, Sessions, providerOf, emit, meter, bill, scrubbed, createDeadlineMs, handoff, handedBack }: StoreDeps): {
63
+ export declare function custodyStore({ name, Config, Sessions, providerOf, emit, meter, bill, scrubbed, createDeadlineMs, handoff, handedBack, stopped: stoppedHook }: StoreDeps): {
61
64
  Inventory: import("@earendil-works/pi-durable").SessionDocToken<{
62
65
  rows: Record<string, InventoryRow>;
63
66
  }>;