@parcha/pi-browser 0.1.0-beta.23 → 0.1.0-beta.27

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 (48) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +15 -0
  3. package/dist/coding-agent-local.js +7 -6
  4. package/dist/coding-agent.js +25 -22
  5. package/dist/core/clip.js +2 -2
  6. package/dist/core/contract.d.ts +7 -0
  7. package/dist/core/contract.js +3 -0
  8. package/dist/core/custody.d.ts +9 -0
  9. package/dist/core/custody.js +22 -5
  10. package/dist/core/downloads.js +2 -2
  11. package/dist/core/driving.d.ts +6 -0
  12. package/dist/core/driving.js +8 -0
  13. package/dist/core/failures.d.ts +10 -0
  14. package/dist/core/failures.js +22 -15
  15. package/dist/core/host.d.ts +6 -0
  16. package/dist/core/redact.d.ts +5 -0
  17. package/dist/core/redact.js +4 -0
  18. package/dist/core/sites.js +2 -1
  19. package/dist/core/tools.js +7 -8
  20. package/dist/core/web.d.ts +1 -6
  21. package/dist/core/web.js +8 -4
  22. package/dist/driver/extension-worker.js +149 -118
  23. package/dist/driver/sealed.d.ts +16 -0
  24. package/dist/driver/sealed.js +47 -0
  25. package/dist/driver/stagehand.js +7 -43
  26. package/dist/durable/journal.d.ts +31 -0
  27. package/dist/durable/journal.js +105 -0
  28. package/dist/{durable-result.d.ts → durable/result.d.ts} +1 -1
  29. package/dist/{store.d.ts → durable/store.d.ts} +2 -2
  30. package/dist/{store.js → durable/store.js} +1 -1
  31. package/dist/{web.d.ts → durable/web.d.ts} +4 -4
  32. package/dist/{web.js → durable/web.js} +5 -5
  33. package/dist/durable.d.ts +2 -2
  34. package/dist/durable.js +39 -131
  35. package/dist/providers/assigned.js +2 -3
  36. package/dist/providers/browserbase.js +5 -4
  37. package/dist/providers/cdp.js +7 -36
  38. package/dist/providers/chrome-args.d.ts +18 -0
  39. package/dist/providers/chrome-args.js +66 -0
  40. package/dist/providers/http.d.ts +4 -1
  41. package/dist/providers/http.js +5 -8
  42. package/dist/providers/kernel.d.ts +10 -1
  43. package/dist/providers/kernel.js +1 -1
  44. package/dist/providers/profiles.js +6 -6
  45. package/dist/providers/shared.d.ts +9 -0
  46. package/dist/providers/shared.js +5 -1
  47. package/package.json +7 -3
  48. /package/dist/{durable-result.js → durable/result.js} +0 -0
@@ -1,4 +1,4 @@
1
- import { BrowserFailureError, FenceRefusal, loadedNoPage, passedThrough } from "./custody.js";
1
+ import { BrowserFailureError, FenceRefusal, refusedError, loadedNoPage, passedThrough } from "./custody.js";
2
2
  import { defaultInline } from "./evidence.js";
3
3
  import { fetchDownloads } from "./downloads.js";
4
4
  import { browserFailure, classifyBrowserError, transportFactOf } from "./failures.js";
@@ -26,7 +26,6 @@ const pause = (ms, signal) => new Promise((resolve) => {
26
26
  });
27
27
  const text = (value, isError = false) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) }], ...(isError ? { isError: true } : {}) });
28
28
  const withNews = (news, body) => (news ? `${news}\n\n${body}` : body);
29
- const refused = (message) => ({ ok: false, code: "refused", retryable: false, effect: "none", message });
30
29
  /** A read of a browser that has loaded no page yet: it is fresh, and the next step is to navigate, to the replaced
31
30
  * session's last page when there is one. */
32
31
  function freshBrowser(replaced) {
@@ -404,19 +403,19 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT }
404
403
  const asked = typeof args?.path === "string" ? args.path : "";
405
404
  const selector = typeof args?.selector === "string" ? args.selector.trim() : "";
406
405
  if (!call.files)
407
- return text(refused("This host gives the browser no workspace to upload from."), true);
406
+ return text(browserFailure("refused", "This host gives the browser no workspace to upload from."), true);
408
407
  if (!selector)
409
- return text(refused("selector must name the page's file input."), true);
408
+ return text(browserFailure("refused", "selector must name the page's file input."), true);
410
409
  // The host resolves the path before any browser call, so a refused file never reaches the page.
411
410
  const file = await call.files.resolve(asked);
412
411
  if ("refused" in file)
413
- return text(refused(`browser_upload refused the file: ${file.refused}.`), true);
412
+ return text(browserFailure("refused", `browser_upload refused the file: ${file.refused}.`), true);
414
413
  const uploaded = { name: file.name, bytes: file.bytes.byteLength, sha256: sha256Hex(file.bytes) };
415
414
  const codeSha = sha256Hex(JSON.stringify({ upload: selector, sha256: uploaded.sha256 }));
416
415
  // A page can send the file once its input changes: an upload is journaled like a run and never repeated.
417
416
  return perform("browser_upload", { path: asked, selector }, port, call, { effect: codeSha }, async (s, news) => {
418
417
  if (!s.driver.setInputFiles)
419
- throw new BrowserFailureError(refused("This browser driver cannot set a file input."));
418
+ throw refusedError("This browser driver cannot set a file input.");
420
419
  const sent = [];
421
420
  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); });
422
421
  try {
@@ -431,9 +430,9 @@ export function pageTools({ guards = new Map(), reconnect: timings = RECONNECT }
431
430
  },
432
431
  browser_downloads: (args, port, call) => perform("browser_downloads", {}, port, call, "read", async (s, news) => {
433
432
  if (!call.workspace)
434
- throw new BrowserFailureError(refused("This host gives the browser no workspace to copy downloads into."));
433
+ throw refusedError("This host gives the browser no workspace to copy downloads into.");
435
434
  if (!s.downloads)
436
- throw new BrowserFailureError(refused("This browser provider cannot list the files its sessions download."));
435
+ throw refusedError("This browser provider cannot list the files its sessions download.");
437
436
  const result = await fetchDownloads({ provider: { downloads: s.downloads }, ref: { id: s.sessionId, tag: s.tag }, session: s.sessionId, workspace: call.workspace, redact: call.redact });
438
437
  return { content: [{ type: "text", text: JSON.stringify({ ok: true, ...result, ...(news ? { notice: news } : {}) }) }], details: { downloads: result } };
439
438
  }),
@@ -1,6 +1,6 @@
1
1
  import type { Decisions, PageVerdict, WallClass } from "./decisions.js";
2
2
  import { type EvidenceSink } from "./evidence.js";
3
- import { type BrowserFailure } from "./failures.js";
3
+ import { type BrowserFailure, type Next } from "./failures.js";
4
4
  import { type FetchRequest, type FetchResult, type PriceTable, type SearchRequest, type SearchResult } from "./host.js";
5
5
  export declare const WEB_SEARCH_QUERY_MAX = 200;
6
6
  export declare const WEB_SEARCH_RESULTS_MAX = 25;
@@ -62,13 +62,8 @@ export type WebToolsOptions = {
62
62
  timeoutMs?: number;
63
63
  };
64
64
  };
65
- export type Next = {
66
- action: "drive_page" | "other_source" | "browser_relaunch";
67
- note: string;
68
- };
69
65
  export type WebFailure = BrowserFailure & {
70
66
  wall?: WallClass;
71
- next?: Next;
72
67
  };
73
68
  export type WebOutcome = {
74
69
  text: string;
package/dist/core/web.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { createHash } from "node:crypto";
2
+ import { BrowserFailureError } from "./custody.js";
2
3
  import { defaultInline } from "./evidence.js";
3
- import { classifyBrowserError, transportFactOf } from "./failures.js";
4
+ import { browserFailure, classifyBrowserError, transportFactOf } from "./failures.js";
4
5
  import { createRepeatGuard } from "./guard.js";
5
6
  import { LIST_PRICES } from "./host.js";
6
7
  import { createRedactor, scrubFetchedUrl, scrubPageUrl } from "./redact.js";
@@ -77,6 +78,9 @@ export function createWebTools(options) {
77
78
  const guardOf = (conversation) => guards.get(conversation) ?? guards.set(conversation, createRepeatGuard(redact)).get(conversation);
78
79
  const fail = (failure) => ({ text: JSON.stringify(failure, (_k, v) => (typeof v === "string" ? redact(v) : v)), isError: true, details: { code: failure.code }, usd: 0 });
79
80
  const failureOf = (error, tool, signal) => {
81
+ // A typed failure (a backup that refuses a private host, a non-text page or one over its size) is told as it is.
82
+ if (error instanceof BrowserFailureError && !signal?.aborted)
83
+ return error.failure;
80
84
  const base = classifyBrowserError(error, false, { aborted: signal?.aborted === true, redact });
81
85
  const status = transportFactOf(error).status;
82
86
  if (base.code === "aborted")
@@ -118,7 +122,7 @@ export function createWebTools(options) {
118
122
  }
119
123
  catch { }
120
124
  if (!parsed || !/^https?:$/.test(parsed.protocol) || parsed.username || parsed.password)
121
- return fail({ ok: false, code: "refused", retryable: false, effect: "none", message: "web_fetch needs an absolute http(s) URL with no credentials in it." });
125
+ return fail(browserFailure("refused", "web_fetch needs an absolute http(s) URL with no credentials in it."));
122
126
  let usd = 0;
123
127
  let guardLine;
124
128
  const file = async (record, body) => options.evidence.file(label, { tool: "web_fetch", ...record, facts: { requested_url: redact(url), sha256: sha256(body), ...record.facts, ...(guardLine ? { page_guard: guardLine } : {}) }, body }).catch(() => null);
@@ -265,7 +269,7 @@ export function createWebTools(options) {
265
269
  }
266
270
  if (signal?.aborted || primary?.code === "aborted")
267
271
  return { ...fail(ABORTED), usd };
268
- const base = primary ?? { ok: false, code: "refused", retryable: false, effect: "none", message: "No source can fetch pages in this run." };
272
+ const base = primary ?? browserFailure("refused", "No source can fetch pages in this run.");
269
273
  const others = tried.filter((name) => name !== primaryVia);
270
274
  const final = { ...base, message: `${base.message}${others.length ? ` Also tried: ${others.join(", ")}.` : ""}${base.next ? "" : " Drive the page with run and snapshot in a live session, or try a different URL."}` };
271
275
  await file({ args: { url: redact(url), via: primaryVia }, status: "failed", facts: { via: primaryVia } }, redact(`${final.message}\n${final.detail ?? ""}`));
@@ -281,7 +285,7 @@ export function createWebTools(options) {
281
285
  if (refused)
282
286
  return fail(refused);
283
287
  if (!query || !options.search)
284
- return fail({ ok: false, code: "refused", retryable: false, effect: "none", message: query ? "No search provider is configured for this run." : "web_search needs a query." });
288
+ return fail(browserFailure("refused", query ? "No search provider is configured for this run." : "web_search needs a query."));
285
289
  try {
286
290
  const { results } = await options.search({ query, n }, signal);
287
291
  guard.note("web_search", guardArgs, null);
@@ -10,6 +10,143 @@ const RESET_ID = 2_147_000_000;
10
10
  class TargetsUnlistedError extends Error {
11
11
  constructor() { super(`the browser did not list its targets within ${DISCOVERY_MS} ms, so a Stagehand runtime it may hold could not be freed`); }
12
12
  }
13
+ /** One attach's CDP socket, open for `lifeMs` at most and closed at once on an abort. A call settles empty when the
14
+ * browser does not answer within `ms` (the deadline, unless shorter), and every call settles empty once the socket
15
+ * closes (an abort, the browser, the end of its life). */
16
+ class Cdp {
17
+ deadline;
18
+ signal;
19
+ /** Settles when the socket opens; rejects when it fails to open or closes first. */
20
+ opened;
21
+ socket;
22
+ timer;
23
+ stop = () => this.socket.close();
24
+ pending = new Map();
25
+ listeners = new Set();
26
+ next = 0;
27
+ isClosed = false;
28
+ constructor(cdpUrl, deadline, lifeMs, signal) {
29
+ this.deadline = deadline;
30
+ this.signal = signal;
31
+ this.socket = new WebSocket(cdpUrl);
32
+ this.timer = setTimeout(() => this.socket.close(), lifeMs);
33
+ signal?.addEventListener("abort", this.stop, { once: true });
34
+ this.opened = new Promise((resolve, reject) => {
35
+ this.socket.onopen = () => resolve();
36
+ // A refused connection raises `error` and, on Node 22, never `close`: waiting for `close` alone would hang the attach.
37
+ this.socket.onerror = () => reject(new Error("Failed to open CDP WebSocket"));
38
+ this.socket.onclose = () => { this.onClose(); reject(new Error("the CDP socket closed")); };
39
+ this.socket.onmessage = (event) => this.onMessage(event.data);
40
+ });
41
+ }
42
+ /** A send on a closed socket neither throws nor is ever answered (Node 24): once closed, every call settles empty. */
43
+ call(method, params = {}, sessionId, ms = this.deadline - Date.now()) {
44
+ return new Promise((resolve) => {
45
+ if (this.isClosed || this.socket.readyState !== WebSocket.OPEN || ms <= 0)
46
+ return resolve(undefined);
47
+ const id = ++this.next;
48
+ const settle = (result) => { clearTimeout(wait); this.pending.delete(id); resolve(result); };
49
+ const wait = setTimeout(() => settle(undefined), ms);
50
+ this.pending.set(id, settle);
51
+ this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
52
+ });
53
+ }
54
+ listen(listener) { this.listeners.add(listener); }
55
+ closed() { return this.isClosed; }
56
+ end() { clearTimeout(this.timer); this.signal?.removeEventListener("abort", this.stop); this.socket.close(); }
57
+ onClose() {
58
+ this.isClosed = true;
59
+ for (const settle of [...this.pending.values()])
60
+ settle(undefined);
61
+ for (const listener of this.listeners)
62
+ listener({ method: "closed" });
63
+ }
64
+ /** A throw in a socket listener ends the process: a frame that is not JSON is dropped. */
65
+ onMessage(data) {
66
+ try {
67
+ const message = JSON.parse(String(data));
68
+ if (message?.id !== undefined)
69
+ this.pending.get(message.id)?.(message.result);
70
+ else if (message)
71
+ for (const listener of this.listeners)
72
+ listener(message);
73
+ }
74
+ catch { }
75
+ }
76
+ }
77
+ /** The one enabled Stagehand extension's id; null when there is none, or more than one. */
78
+ async function stagehandExtensionId(cdp) {
79
+ const extensions = (await cdp.call("Extensions.getExtensions"))?.extensions ?? [];
80
+ const enabled = extensions.filter((extension) => extension.name === STAGEHAND_EXTENSION && extension.enabled);
81
+ return enabled.length === 1 ? enabled[0].id : null;
82
+ }
83
+ /** The extension's workers; null when the browser gave no list, which is not a list without one. */
84
+ async function extensionWorkers(cdp, id) {
85
+ const infos = (await cdp.call("Target.getTargets"))?.targetInfos;
86
+ return infos?.filter((target) => target.type === "service_worker" && target.url.startsWith(`chrome-extension://${id}/`)).map((target) => target.targetId) ?? null;
87
+ }
88
+ /** With no worker running nothing is held, and the worker is woken until it is listed. Every wake page opened stays
89
+ * listed here until a close of it is answered. None is opened within CLEANUP_MS of the deadline, an opening's reply is
90
+ * awaited into the first half of that second, and the socket outlives the deadline by CLEANUP_MS, so the last pages are
91
+ * closed on it. */
92
+ async function wakeWorker(cdp, id, deadline) {
93
+ const wakes = new Set();
94
+ const closeWakes = async (ms) => { for (const page of [...wakes])
95
+ if ((await cdp.call("Target.closeTarget", { targetId: page }, undefined, ms)) !== undefined)
96
+ wakes.delete(page); };
97
+ for (let tries = 0; !cdp.closed() && Date.now() < deadline && tries < WAKE_TRIES && ((await extensionWorkers(cdp, id))?.length ?? 0) === 0; tries += 1) {
98
+ if (tries % 10 === 0 && deadline - Date.now() > CLEANUP_MS) {
99
+ await closeWakes();
100
+ const page = (await cdp.call("Target.createTarget", { url: `chrome-extension://${id}/wake-service-worker.html` }, undefined, deadline + CLEANUP_MS / 2 - Date.now()))?.targetId;
101
+ if (page)
102
+ wakes.add(page);
103
+ }
104
+ await new Promise((r) => setTimeout(r, 100));
105
+ }
106
+ await closeWakes(deadline + CLEANUP_MS - Date.now());
107
+ }
108
+ /** A binding call on `sessionId` that carries the reply to the close (its id is RESET_ID). */
109
+ function isResetReply(event, sessionId) {
110
+ if (event.method !== "Runtime.bindingCalled" || event.sessionId !== sessionId || event.params?.name !== SEND_TO_HOST)
111
+ return false;
112
+ try {
113
+ return JSON.parse(event.params.payload ?? "")?.id === RESET_ID;
114
+ }
115
+ catch {
116
+ return false;
117
+ }
118
+ }
119
+ /** Settles on the runtime's reply to the close, at once when the socket closes, and after `replyMs` at most. */
120
+ function resetReplied(cdp, sessionId, replyMs) {
121
+ return new Promise((resolve) => {
122
+ const wait = setTimeout(resolve, replyMs);
123
+ cdp.listen((event) => {
124
+ if (event.method === "closed" || isResetReply(event, sessionId)) {
125
+ clearTimeout(wait);
126
+ resolve();
127
+ }
128
+ });
129
+ });
130
+ }
131
+ /** The held runtime's close, sent through the worker's own RPC, and its reply awaited for up to `replyMs`; the worker
132
+ * keeps running. */
133
+ async function closeHeldRuntime(cdp, worker, replyMs) {
134
+ const sessionId = (await cdp.call("Target.attachToTarget", { targetId: worker, flatten: true }))?.sessionId;
135
+ if (!sessionId)
136
+ return;
137
+ try {
138
+ await cdp.call("Runtime.enable", {}, sessionId);
139
+ await cdp.call("Runtime.addBinding", { name: SEND_TO_HOST }, sessionId);
140
+ const replied = resetReplied(cdp, sessionId, replyMs);
141
+ const close = JSON.stringify({ jsonrpc: "2.0", id: RESET_ID, method: "stagehand.close", params: {} });
142
+ const sent = await cdp.call("Runtime.evaluate", { expression: `void globalThis.__stagehandReceiveFromHost(${JSON.stringify(close)}); true`, returnByValue: true }, sessionId);
143
+ if (sent && !sent.exceptionDetails)
144
+ await replied;
145
+ }
146
+ finally {
147
+ await cdp.call("Target.detachFromTarget", { sessionId });
148
+ }
149
+ }
13
150
  /** A held extension runtime keeps one Stagehand instance until that instance's close, which a dead process never sent,
14
151
  * so a new attach would be refused. The close is sent here through the worker's own RPC, and the worker keeps running:
15
152
  * a worker closed under load is sometimes never restarted, and its attach waits out Stagehand's 60 s init deadline.
@@ -18,127 +155,23 @@ class TargetsUnlistedError extends Error {
18
155
  * runtime's reply. An init still running in the extension answers it only once that init ends, since the runtime runs
19
156
  * both one after the other; the socket outlives the deadline by that much more. */
20
157
  export async function installedExtension(cdpUrl, signal, known, replyMs = CLOSE_REPLY_MS) {
21
- const socket = new WebSocket(cdpUrl);
22
158
  const deadline = Date.now() + DISCOVERY_MS;
23
- const timer = setTimeout(() => socket.close(), DISCOVERY_MS + CLEANUP_MS - CLOSE_REPLY_MS + replyMs);
24
- const stop = () => socket.close();
25
- signal?.addEventListener("abort", stop, { once: true });
26
- // A call the browser does not answer within `ms` (the deadline, unless shorter) settles empty, as does every call once
27
- // the socket closes (an abort, the browser).
28
- const pending = new Map();
29
- const listeners = new Set();
30
- let next = 0;
31
- let closed = false;
32
- // A send on a closed socket neither throws nor is ever answered (Node 24): once closed, every call settles empty.
33
- const call = (method, params = {}, sessionId, ms = deadline - Date.now()) => new Promise((resolve) => {
34
- if (closed || socket.readyState !== WebSocket.OPEN || ms <= 0)
35
- return resolve(undefined);
36
- const id = ++next;
37
- const settle = (result) => { clearTimeout(wait); pending.delete(id); resolve(result); };
38
- const wait = setTimeout(() => settle(undefined), ms);
39
- pending.set(id, settle);
40
- socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
41
- });
159
+ const cdp = new Cdp(cdpUrl, deadline, DISCOVERY_MS + CLEANUP_MS - CLOSE_REPLY_MS + replyMs, signal);
42
160
  try {
43
- await new Promise((resolve, reject) => {
44
- socket.onopen = () => resolve();
45
- // A refused connection raises `error` and, on Node 22, never `close`: waiting for `close` alone would hang the
46
- // attach.
47
- socket.onerror = () => reject(new Error("Failed to open CDP WebSocket"));
48
- socket.onclose = () => {
49
- closed = true;
50
- for (const settle of [...pending.values()])
51
- settle(undefined);
52
- for (const listener of listeners)
53
- listener({ method: "closed" });
54
- reject(new Error("the CDP socket closed"));
55
- };
56
- // A throw in a socket listener ends the process: a frame that is not JSON is dropped.
57
- socket.onmessage = (event) => {
58
- try {
59
- const message = JSON.parse(String(event.data));
60
- if (message?.id !== undefined)
61
- pending.get(message.id)?.(message.result);
62
- else
63
- for (const listener of listeners)
64
- listener(message);
65
- }
66
- catch { }
67
- };
68
- });
69
- let id = known ?? null;
70
- if (!id) {
71
- const extensions = (await call("Extensions.getExtensions"))?.extensions ?? [];
72
- const enabled = extensions.filter((extension) => extension.name === STAGEHAND_EXTENSION && extension.enabled);
73
- if (enabled.length !== 1)
74
- return null;
75
- id = enabled[0].id;
76
- }
77
- /** The extension's workers; null when the browser gave no list, which is not a list without one. */
78
- const workers = async () => {
79
- const infos = (await call("Target.getTargets"))?.targetInfos;
80
- return infos?.filter((target) => target.type === "service_worker" && target.url.startsWith(`chrome-extension://${id}/`)).map((target) => target.targetId) ?? null;
81
- };
82
- const running = await workers();
161
+ await cdp.opened;
162
+ const id = known || (await stagehandExtensionId(cdp));
163
+ if (!id)
164
+ return null;
165
+ const running = await extensionWorkers(cdp, id);
83
166
  if (running === null) {
84
- if (signal?.aborted || closed)
167
+ if (signal?.aborted || cdp.closed())
85
168
  return id;
86
169
  throw new TargetsUnlistedError();
87
170
  }
88
- if (running.length === 0) {
89
- // Every wake page opened stays listed here until a close of it is answered. None is opened within CLEANUP_MS of the
90
- // deadline, an opening's reply is awaited into the first half of that second, and the socket outlives the deadline
91
- // by CLEANUP_MS, so the last pages are closed on it.
92
- const wakes = new Set();
93
- const closeWakes = async (ms) => { for (const page of [...wakes])
94
- if ((await call("Target.closeTarget", { targetId: page }, undefined, ms)) !== undefined)
95
- wakes.delete(page); };
96
- for (let tries = 0; !closed && Date.now() < deadline && tries < WAKE_TRIES && ((await workers())?.length ?? 0) === 0; tries += 1) {
97
- if (tries % 10 === 0 && deadline - Date.now() > CLEANUP_MS) {
98
- await closeWakes();
99
- const page = (await call("Target.createTarget", { url: `chrome-extension://${id}/wake-service-worker.html` }, undefined, deadline + CLEANUP_MS / 2 - Date.now()))?.targetId;
100
- if (page)
101
- wakes.add(page);
102
- }
103
- await new Promise((r) => setTimeout(r, 100));
104
- }
105
- await closeWakes(deadline + CLEANUP_MS - Date.now());
106
- return id;
107
- }
108
- const sessionId = (await call("Target.attachToTarget", { targetId: running[0], flatten: true }))?.sessionId;
109
- if (!sessionId)
110
- return id;
111
- try {
112
- await call("Runtime.enable", {}, sessionId);
113
- await call("Runtime.addBinding", { name: SEND_TO_HOST }, sessionId);
114
- const replied = new Promise((resolve) => {
115
- const wait = setTimeout(resolve, replyMs);
116
- listeners.add((event) => {
117
- if (event.method === "closed") {
118
- clearTimeout(wait);
119
- return resolve();
120
- }
121
- if (event.method !== "Runtime.bindingCalled" || event.sessionId !== sessionId || event.params?.name !== SEND_TO_HOST)
122
- return;
123
- let reply = null;
124
- try {
125
- reply = JSON.parse(event.params.payload);
126
- }
127
- catch { }
128
- if (reply?.id === RESET_ID) {
129
- clearTimeout(wait);
130
- resolve();
131
- }
132
- });
133
- });
134
- const close = JSON.stringify({ jsonrpc: "2.0", id: RESET_ID, method: "stagehand.close", params: {} });
135
- const sent = await call("Runtime.evaluate", { expression: `void globalThis.__stagehandReceiveFromHost(${JSON.stringify(close)}); true`, returnByValue: true }, sessionId);
136
- if (sent && !sent.exceptionDetails)
137
- await replied;
138
- }
139
- finally {
140
- await call("Target.detachFromTarget", { sessionId });
141
- }
171
+ if (running.length === 0)
172
+ await wakeWorker(cdp, id, deadline);
173
+ else
174
+ await closeHeldRuntime(cdp, running[0], replyMs);
142
175
  return id;
143
176
  }
144
177
  catch (error) {
@@ -147,8 +180,6 @@ export async function installedExtension(cdpUrl, signal, known, replyMs = CLOSE_
147
180
  return known ?? null;
148
181
  }
149
182
  finally {
150
- clearTimeout(timer);
151
- signal?.removeEventListener("abort", stop);
152
- socket.close();
183
+ cdp.end();
153
184
  }
154
185
  }
@@ -0,0 +1,16 @@
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
+ /** A failed attach step names where it went: Stagehand reports a failed open as "[object Object]", and the socket's error
8
+ * has no address. */
9
+ 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. */
11
+ 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>;
@@ -0,0 +1,47 @@
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
+ };
14
+ /** A failed attach step names where it went: Stagehand reports a failed open as "[object Object]", and the socket's error
15
+ * has no address. */
16
+ export const attachStep = (host) => (step) => step.catch((error) => {
17
+ throw new Error(`attaching to the browser at ${host} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
18
+ });
19
+ /** A cancelled call never starts an init of its own, however the wait ended. */
20
+ export function throwIfCancelled(signal) {
21
+ if (signal?.aborted)
22
+ throw signal.reason instanceof Error ? signal.reason : Object.assign(new Error("the attach was cancelled"), { name: "AbortError" });
23
+ }
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 }));
46
+ }
47
+ }
@@ -1,9 +1,6 @@
1
- // Stagehand is created sealed: no inference leaves through it (act, extract and observe are refused), nothing is cached
2
- // server side, and the driver never ends the browser: custody releases it through the provider.
3
- import { BrowserFailureError } from "../core/custody.js";
4
- import { browserFailure } from "../core/failures.js";
5
1
  import { installedExtension } from "./extension-worker.js";
6
2
  import { pageDriver } from "./page-driver.js";
3
+ import { attachStep, createSealed, IN_FLIGHT_INIT_MS, INIT_IN_PROGRESS } from "./sealed.js";
7
4
  /** A closed loopback port, so no span leaves the host: Stagehand 4.1.0 cannot turn its trace exporter off. */
8
5
  export const STAGEHAND_TELEMETRY = { traces: { endpoint: "http://127.0.0.1:9/v1/traces" } };
9
6
  export const STAGEHAND_INFERENCE_REFUSED = "Stagehand inference is off in this harness: act, extract and observe are unavailable. Drive the page with run code or snapshot IDs.";
@@ -14,50 +11,17 @@ export const SEALED_STAGEHAND = {
14
11
  telemetry: STAGEHAND_TELEMETRY,
15
12
  };
16
13
  /** What Stagehand's extension answers an init while another is still running in it. */
17
- export const STAGEHAND_INIT_IN_PROGRESS = "Stagehand initialization is already in progress";
18
- /** Stagehand's own init deadline: an init the extension is still running has ended by then. */
19
- const IN_FLIGHT_INIT_MS = 60_000;
20
- const initInProgress = (error) => {
21
- const cause = error?.cause;
22
- return !!cause && typeof cause === "object" && typeof cause.code === "number" && cause.message === STAGEHAND_INIT_IN_PROGRESS;
23
- };
14
+ export const STAGEHAND_INIT_IN_PROGRESS = INIT_IN_PROGRESS;
24
15
  /** The batch deadline comes from `DriverOptions`; a caller that passes none gets the facade's 60 s. */
25
16
  export function stagehandDriver() {
26
17
  return async (target, signal, options) => {
27
18
  const { localBrowser, Stagehand } = await import("@browserbasehq/stagehand");
28
- // An id the provider supplies names a held extension too, so its worker is reset as well.
29
- // A failed open names where it went: Stagehand reports it as "[object Object]" and the socket's error has no
30
- // address.
31
19
  const host = new URL(target.dial?.url ?? target.sdkCdpUrl).host;
32
- const named = (step) => step.catch((error) => { throw new Error(`attaching to the browser at ${host} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); });
33
- const extensionId = await named(installedExtension(target.sdkCdpUrl, signal, target.extensionId));
34
- const browser = await named(localBrowser.connect({ cdpUrl: target.sdkCdpUrl, ...(extensionId ? { extensionId } : {}) }));
35
- let stagehand;
36
- try {
37
- stagehand = await Stagehand.create({ browser, ...SEALED_STAGEHAND });
38
- }
39
- catch (error) {
40
- if (!initInProgress(error))
41
- throw error;
42
- // A cancelled call never starts an init of its own, however the wait ended.
43
- const stopIfCancelled = () => {
44
- if (signal?.aborted)
45
- throw signal.reason instanceof Error ? signal.reason : Object.assign(new Error("the attach was cancelled"), { name: "AbortError" });
46
- };
47
- stopIfCancelled();
48
- // An attach that gave up (a dropped connection, a deadline) left its init running in the extension. A close
49
- // queues behind that init, so its reply means the init has ended; this attach then inits once more.
50
- await named(installedExtension(target.sdkCdpUrl, signal, extensionId ?? undefined, IN_FLIGHT_INIT_MS));
51
- stopIfCancelled();
52
- try {
53
- stagehand = await Stagehand.create({ browser, ...SEALED_STAGEHAND });
54
- }
55
- catch (again) {
56
- if (!initInProgress(again))
57
- throw again;
58
- 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 }));
59
- }
60
- }
20
+ const step = attachStep(host);
21
+ // An id the provider supplies names a held extension too, so its worker is reset as well.
22
+ const extensionId = await step(installedExtension(target.sdkCdpUrl, signal, target.extensionId));
23
+ const browser = await step(localBrowser.connect({ cdpUrl: target.sdkCdpUrl, ...(extensionId ? { extensionId } : {}) }));
24
+ const stagehand = await createSealed(() => Stagehand.create({ browser, ...SEALED_STAGEHAND }), () => step(installedExtension(target.sdkCdpUrl, signal, extensionId ?? undefined, IN_FLIGHT_INIT_MS)), host, signal);
61
25
  return pageDriver(stagehand, { batchMs: options?.batchTimeoutMs ?? 60_000 });
62
26
  };
63
27
  }
@@ -0,0 +1,31 @@
1
+ import { type ConversationDocToken, type ConversationId, type Tx } from "@earendil-works/pi-durable";
2
+ import type { PendingEffect, SessionsState } from "../core/host.js";
3
+ /** What the journal reads of custody: the conversation's sessions and this process's incarnation. */
4
+ type Journal = {
5
+ Sessions: ConversationDocToken<SessionsState>;
6
+ incarnation: string;
7
+ };
8
+ /** What the journal reads of a tool call: its conversation and plane, and a commit. */
9
+ type JournalScope = {
10
+ cid: ConversationId;
11
+ plane: string;
12
+ commit<T>(change: (tx: Tx) => Promise<T>): Promise<T>;
13
+ };
14
+ export declare const journalOf: (state: SessionsState, plane: string) => PendingEffect | null;
15
+ /** The entry with this call's id in a journal chain: the entry itself or one it carries as `prior`. */
16
+ export declare const inChain: (entry: PendingEffect | null | undefined, callId: string) => PendingEffect | undefined;
17
+ /** Settles one entry of a journal chain; the entries it carried stay. */
18
+ export declare const clearJournal: (c: Journal, scope: JournalScope, callId: string) => Promise<void>;
19
+ /** The entries of a journal chain whose warning is still owed, as a chain: each an earlier process wrote that is a cut (not
20
+ * finished with a saved answer) and has not been told by a saved answer. An entry of this process is never a cut, and a told
21
+ * one whose telling answer was saved was delivered. */
22
+ export declare function owed(c: Journal, scope: JournalScope, entry: PendingEffect | null | undefined): Promise<PendingEffect | null>;
23
+ /** A journaled action's own answer as pi committed it: true for a success, false for an error, null for none yet. */
24
+ export declare function answerOf(scope: JournalScope, pending: PendingEffect): Promise<boolean | null>;
25
+ /** Every cut in a journal chain, oldest first. An entry a later action replaced counts only while its warning is still owed:
26
+ * once a saved answer told it, the later action replaced it, as it would have with no chain. */
27
+ export declare function cutsOf(c: Journal, scope: JournalScope, entry: PendingEffect | null | undefined, newest?: boolean): Promise<PendingEffect[]>;
28
+ /** The cut a call answers for: the oldest whose warning is still owed (an entry a later action replaced before the telling
29
+ * of it was saved comes first), else the newest. */
30
+ export declare const cutOf: (cuts: PendingEffect[]) => PendingEffect | null;
31
+ export {};