@parcha/pi-browser 0.0.0-stage → 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.
Files changed (108) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +33 -0
  4. package/README.md +348 -2
  5. package/dist/coding-agent-local.d.ts +16 -0
  6. package/dist/coding-agent-local.js +138 -0
  7. package/dist/coding-agent.d.ts +79 -0
  8. package/dist/coding-agent.js +448 -0
  9. package/dist/core/contract.d.ts +26 -0
  10. package/dist/core/contract.js +154 -0
  11. package/dist/core/custody.d.ts +117 -0
  12. package/dist/core/custody.js +126 -0
  13. package/dist/core/decisions.d.ts +43 -0
  14. package/dist/core/decisions.js +4 -0
  15. package/dist/core/downloads.d.ts +35 -0
  16. package/dist/core/downloads.js +131 -0
  17. package/dist/core/effects.d.ts +63 -0
  18. package/dist/core/effects.js +256 -0
  19. package/dist/core/evidence.d.ts +43 -0
  20. package/dist/core/evidence.js +6 -0
  21. package/dist/core/failures.d.ts +36 -0
  22. package/dist/core/failures.js +68 -0
  23. package/dist/core/find.d.ts +32 -0
  24. package/dist/core/find.js +179 -0
  25. package/dist/core/guard.d.ts +6 -0
  26. package/dist/core/guard.js +25 -0
  27. package/dist/core/host.d.ts +328 -0
  28. package/dist/core/host.js +2 -0
  29. package/dist/core/images.d.ts +37 -0
  30. package/dist/core/images.js +60 -0
  31. package/dist/core/lease.d.ts +16 -0
  32. package/dist/core/lease.js +30 -0
  33. package/dist/core/receipts.d.ts +19 -0
  34. package/dist/core/receipts.js +22 -0
  35. package/dist/core/redact.d.ts +13 -0
  36. package/dist/core/redact.js +83 -0
  37. package/dist/core/session-control.d.ts +25 -0
  38. package/dist/core/session-control.js +75 -0
  39. package/dist/core/sites.d.ts +33 -0
  40. package/dist/core/sites.js +102 -0
  41. package/dist/core/tools.d.ts +72 -0
  42. package/dist/core/tools.js +200 -0
  43. package/dist/core/uri.d.ts +11 -0
  44. package/dist/core/uri.js +37 -0
  45. package/dist/core/usage.d.ts +19 -0
  46. package/dist/core/usage.js +44 -0
  47. package/dist/core/web.d.ts +98 -0
  48. package/dist/core/web.js +327 -0
  49. package/dist/driver/extension-worker.d.ts +6 -0
  50. package/dist/driver/extension-worker.js +121 -0
  51. package/dist/driver/stagehand.d.ts +25 -0
  52. package/dist/driver/stagehand.js +91 -0
  53. package/dist/durable-result.d.ts +6 -0
  54. package/dist/durable-result.js +2 -0
  55. package/dist/durable.d.ts +79 -0
  56. package/dist/durable.js +582 -0
  57. package/dist/index.d.ts +19 -0
  58. package/dist/index.js +20 -0
  59. package/dist/providers/browserbase-net.d.ts +13 -0
  60. package/dist/providers/browserbase-net.js +96 -0
  61. package/dist/providers/browserbase.d.ts +152 -0
  62. package/dist/providers/browserbase.js +262 -0
  63. package/dist/providers/cdp-call.d.ts +6 -0
  64. package/dist/providers/cdp-call.js +25 -0
  65. package/dist/providers/cdp.d.ts +55 -0
  66. package/dist/providers/cdp.js +423 -0
  67. package/dist/providers/http.d.ts +2 -0
  68. package/dist/providers/http.js +21 -0
  69. package/dist/providers/kernel.d.ts +49 -0
  70. package/dist/providers/kernel.js +246 -0
  71. package/dist/providers/shared.d.ts +47 -0
  72. package/dist/providers/shared.js +82 -0
  73. package/dist/recorder/credential.d.ts +9 -0
  74. package/dist/recorder/credential.js +49 -0
  75. package/dist/recorder/follow.d.ts +26 -0
  76. package/dist/recorder/follow.js +138 -0
  77. package/dist/recorder/frames.d.ts +80 -0
  78. package/dist/recorder/frames.js +309 -0
  79. package/dist/recorder/index.d.ts +4 -0
  80. package/dist/recorder/index.js +7 -0
  81. package/dist/recorder/jpeg.d.ts +8 -0
  82. package/dist/recorder/jpeg.js +70 -0
  83. package/dist/recorder/track.d.ts +107 -0
  84. package/dist/recorder/track.js +259 -0
  85. package/dist/store.d.ts +56 -0
  86. package/dist/store.js +196 -0
  87. package/dist/testing/backend.d.ts +231 -0
  88. package/dist/testing/backend.js +414 -0
  89. package/dist/testing/driver.d.ts +28 -0
  90. package/dist/testing/driver.js +32 -0
  91. package/dist/testing/index.d.ts +4 -0
  92. package/dist/testing/index.js +4 -0
  93. package/dist/testing/pages.d.ts +3 -0
  94. package/dist/testing/pages.js +10 -0
  95. package/dist/testing/sentinels.d.ts +29 -0
  96. package/dist/testing/sentinels.js +38 -0
  97. package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
  98. package/dist/vendor/stagehand-facade/contract.js +155 -0
  99. package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
  100. package/dist/vendor/stagehand-facade/runtime.js +1640 -0
  101. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
  102. package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
  103. package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
  104. package/dist/vendor/stagehand-facade/tools.js +139 -0
  105. package/dist/web.d.ts +41 -0
  106. package/dist/web.js +38 -0
  107. package/package.json +123 -4
  108. package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
@@ -0,0 +1,246 @@
1
+ // The key lives in this module's memory only, and the CDP URL (it carries Kernel's token) is held here, never in a ref.
2
+ // No error carries the key, the URL or Kernel's text: only the call, the status and the code.
3
+ import { createHash, randomUUID } from "node:crypto";
4
+ import { readFile } from "node:fs/promises";
5
+ import { directFetch } from "./http.js";
6
+ import { accountKey, assertTag, defaultSleep, DEFAULT_CONFIRM, extensionArchive, kernelHoldings, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
7
+ export const KERNEL_BASE_URL = "https://api.onkernel.com";
8
+ export const KERNEL_IDLE_MIN_S = 10;
9
+ export const KERNEL_IDLE_MAX_S = 259_200;
10
+ // Kernel ends a session after `timeout_seconds` with no CDP or live-view connection and sets no wall-clock limit, so
11
+ // the lifetime cap is its largest idle timeout.
12
+ const CAPS = { timeoutModel: "inactivity", maxLifetimeS: KERNEL_IDLE_MAX_S, survivesDisconnect: true, releaseIsAsync: false, extension: "uploaded-per-launch", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
13
+ /** The call and the HTTP status, plus Kernel's error code when it is a plain identifier. Kernel's message is never
14
+ * copied: an echo of the request could carry the key or a URL. */
15
+ export class KernelError extends Error {
16
+ status;
17
+ constructor(call, status, code, options) {
18
+ super(status === undefined ? `Kernel ${call} could not be reached` : `Kernel ${call} answered ${status}${code ? ` (${code})` : ""}`, options);
19
+ this.name = "KernelError";
20
+ this.status = status;
21
+ }
22
+ }
23
+ const CODE = /^[a-z][a-z_.-]{0,47}$/i;
24
+ export function kernelCreateBody(spec, options = {}) {
25
+ const tags = Object.fromEntries(Object.entries(spec.metadata).map(([k, v]) => [k, tagValue(v)]));
26
+ return {
27
+ headless: options.headless ?? false,
28
+ stealth: options.stealth ?? false,
29
+ // Explicit, never Kernel's default (60 s): a crashed host's browser stops costing money on its own while custody's
30
+ // release is pending.
31
+ timeout_seconds: Math.min(KERNEL_IDLE_MAX_S, Math.max(KERNEL_IDLE_MIN_S, Math.round(spec.idleTimeoutS) || KERNEL_IDLE_MIN_S)),
32
+ viewport: { width: spec.viewport.width, height: spec.viewport.height },
33
+ tags: { ...tags, agentrun_tag: spec.tag },
34
+ ...(options.extension ? { extensions: [options.extension] } : {}),
35
+ };
36
+ }
37
+ const { cdpUrls, liveUrls, uploads } = kernelHoldings;
38
+ export function kernelProvider(options = {}) {
39
+ const env = options.env ?? process.env;
40
+ const apiKey = nonEmpty(env.KERNEL_API_KEY);
41
+ const baseUrl = (nonEmpty(env.KERNEL_BASE_URL) || KERNEL_BASE_URL).replace(/\/+$/, "");
42
+ const account = accountKey(baseUrl, apiKey);
43
+ const held = (id) => `${account}|${id}`;
44
+ const sleep = options.sleep ?? defaultSleep;
45
+ const confirm = options.confirm ?? DEFAULT_CONFIRM;
46
+ let client = null;
47
+ const http = () => (client ??= options.fetch ? Promise.resolve(options.fetch) : directFetch().then((f) => (f ?? fetch)));
48
+ /** One request, never retried: a create served twice would be a second paid browser. On failure only Kernel's `code`
49
+ * survives; a transport failure keeps its cause chain under a message that names the call alone. */
50
+ async function call(method, route, init = {}) {
51
+ if (!apiKey)
52
+ throw new Error("the kernel provider needs KERNEL_API_KEY in the env it is given; none is set");
53
+ const name = `${method} ${route.replace(/\/browsers\/[^/?]+/, "/browsers/{id}").replace(/\/extensions\/[^/?]+/, "/extensions/{name}")}`;
54
+ const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
55
+ let body;
56
+ if (init.raw) {
57
+ headers["Content-Type"] = init.raw.type;
58
+ body = init.raw.body;
59
+ }
60
+ else if (init.body !== undefined) {
61
+ headers["Content-Type"] = "application/json";
62
+ body = JSON.stringify(init.body);
63
+ }
64
+ let response;
65
+ try {
66
+ const query = init.query?.toString();
67
+ response = await (await http())(`${baseUrl}${route}${query ? `?${query}` : ""}`, { method, headers, ...(body !== undefined ? { body } : {}), ...(init.signal ? { signal: init.signal } : {}) });
68
+ }
69
+ catch (error) {
70
+ if (error?.name === "AbortError")
71
+ throw error;
72
+ throw new KernelError(name, undefined, undefined, { cause: error });
73
+ }
74
+ // A success must be read whole: a body that breaks off or is not JSON is a failure, never an empty answer (an empty
75
+ // session list would let a release finish without deleting).
76
+ let text = "";
77
+ try {
78
+ text = await response.text();
79
+ }
80
+ catch (error) {
81
+ if (error?.name === "AbortError")
82
+ throw error;
83
+ if (response.ok)
84
+ throw new KernelError(name, response.status, "unreadable_body", { cause: error });
85
+ }
86
+ let json = null;
87
+ try {
88
+ json = text ? JSON.parse(text) : null;
89
+ }
90
+ catch {
91
+ if (response.ok)
92
+ throw new KernelError(name, response.status, "not_json");
93
+ }
94
+ if (!response.ok && response.status !== 404)
95
+ throw new KernelError(name, response.status, typeof json?.code === "string" && CODE.test(json.code) ? json.code : undefined);
96
+ return { status: response.status, json, headers: response.headers };
97
+ }
98
+ /** Null only when the whole list was read and none matches: a list cut short is a failure, since a missed copy means
99
+ * a refused upload or a duplicate. */
100
+ const storedWith = async (sha) => {
101
+ for (let offset = 0, pages = 0; pages < 100; pages += 1) {
102
+ const page = await call("GET", "/extensions", { query: new URLSearchParams({ limit: "100", offset: String(offset) }) });
103
+ if (!Array.isArray(page.json))
104
+ throw new KernelError("GET /extensions", page.status, "not_a_list");
105
+ const found = page.json.find((e) => e?.checksum === sha);
106
+ if (found)
107
+ return nonEmpty(found.name) ? { name: nonEmpty(found.name) } : { id: nonEmpty(found.id) };
108
+ if (page.headers.get("x-has-more") !== "true")
109
+ return null;
110
+ const next = Number(page.headers.get("x-next-offset"));
111
+ if (!Number.isInteger(next) || next <= offset)
112
+ throw new KernelError("GET /extensions", page.status, "no_next_offset");
113
+ offset = next;
114
+ }
115
+ throw new Error("Kernel kept answering more pages of stored extensions");
116
+ };
117
+ /** A stored extension with the same bytes serves whatever its name (a plan may store only one, perhaps another
118
+ * tool's); otherwise one upload per process and account, named by its SHA-256, and a failed one is forgotten. */
119
+ const extension = () => options.extension ? options.extension() : uploadOnce(uploads, account, async () => {
120
+ const zip = await readFile(extensionArchive());
121
+ const sha = createHash("sha256").update(zip).digest("hex");
122
+ const stored = await storedWith(sha);
123
+ if (stored)
124
+ return stored;
125
+ const name = `agentrun-stagehand-${sha.slice(0, 16)}`;
126
+ const boundary = `agentrun-${randomUUID()}`;
127
+ const part = (headers) => Buffer.from(`--${boundary}\r\n${headers}\r\n\r\n`);
128
+ const body = Buffer.concat([
129
+ part(`Content-Disposition: form-data; name="name"`), Buffer.from(`${name}\r\n`),
130
+ part(`Content-Disposition: form-data; name="file"; filename="stagehand-extension.zip"\r\nContent-Type: application/zip`), zip, Buffer.from(`\r\n--${boundary}--\r\n`),
131
+ ]);
132
+ try {
133
+ const done = await call("POST", "/extensions", { raw: { body, type: `multipart/form-data; boundary=${boundary}` } });
134
+ if (done.status === 404)
135
+ throw new KernelError("POST /extensions", 404);
136
+ }
137
+ catch (error) {
138
+ // Another process stored the same archive meanwhile: that copy serves.
139
+ const raced = error.status === 409 ? await storedWith(sha) : null;
140
+ if (raced)
141
+ return raced;
142
+ throw error;
143
+ }
144
+ return { name };
145
+ });
146
+ const lookup = async (id, signal) => call("GET", `/browsers/${encodeURIComponent(id)}`, { signal });
147
+ const forget = (id) => { cdpUrls.delete(held(id)); liveUrls.delete(held(id)); };
148
+ const status = async (ref, signal) => {
149
+ const found = await lookup(ref.id, signal);
150
+ const state = found.status === 404 ? "gone" : found.json?.deleted_at ? "stopped" : "running";
151
+ if (state !== "running")
152
+ forget(ref.id);
153
+ return state;
154
+ };
155
+ return {
156
+ name: "kernel",
157
+ caps: CAPS,
158
+ async create(spec, signal) {
159
+ // The upload is shared by every create on the account: a cancelled caller stops waiting, the upload goes on for
160
+ // the rest.
161
+ signal?.throwIfAborted();
162
+ const body = kernelCreateBody(spec, { stealth: options.stealth, headless: options.headless, extension: await untilAborted(extension(), signal) });
163
+ // At most once: a lost answer is found again by its tag (findByTag), never by a second create.
164
+ const created = await call("POST", "/browsers", { body, signal });
165
+ const id = nonEmpty(created.json?.session_id);
166
+ const url = nonEmpty(created.json?.cdp_ws_url);
167
+ if (created.status === 404 || !id || !url)
168
+ throw new KernelError("POST /browsers", created.status, "no_session");
169
+ cdpUrls.set(held(id), url);
170
+ const live = nonEmpty(created.json?.browser_live_view_url);
171
+ if (live)
172
+ liveUrls.set(held(id), live);
173
+ return { id, tag: spec.tag };
174
+ },
175
+ async findByTag(tag, signal) {
176
+ assertTag(tag);
177
+ // The filter is Kernel's, the match is ours: a lane that ignores it must never hand back someone else's session.
178
+ // Every page must answer: custody releases exactly these ids, so a failed page throws.
179
+ const out = [];
180
+ const seen = new Set();
181
+ for (let offset = 0, pages = 0; pages < 100; pages += 1) {
182
+ const query = new URLSearchParams({ status: "active", [`tags[agentrun_tag]`]: tag, limit: "100", offset: String(offset) });
183
+ const page = await call("GET", "/browsers", { query, signal });
184
+ // A list is never "not found": a 404 here is a wrong base URL, and an empty answer would orphan the tag's
185
+ // sessions.
186
+ if (page.status === 404)
187
+ throw new KernelError("GET /browsers", 404);
188
+ if (!Array.isArray(page.json))
189
+ throw new KernelError("GET /browsers", page.status, "not_a_list");
190
+ const rows = page.json;
191
+ for (const row of rows) {
192
+ const id = nonEmpty(row?.session_id);
193
+ if (id && row?.tags?.agentrun_tag === tag && !row?.deleted_at && !seen.has(id)) {
194
+ seen.add(id);
195
+ out.push({ id, tag });
196
+ }
197
+ }
198
+ // Kernel pages by headers: X-Has-More, and X-Next-Offset as the next page's absolute start.
199
+ if (page.headers.get("x-has-more") !== "true")
200
+ return out;
201
+ // More pages with no usable next offset would truncate the set custody releases: a failure, never a partial
202
+ // answer.
203
+ const next = Number(page.headers.get("x-next-offset"));
204
+ if (!Number.isInteger(next) || next <= offset)
205
+ throw new Error("Kernel reported more sessions for the tag without the next page's offset");
206
+ offset = next;
207
+ }
208
+ throw new Error("Kernel kept answering more pages of sessions for one tag");
209
+ },
210
+ status,
211
+ async attach(ref, signal) {
212
+ let url = cdpUrls.get(held(ref.id));
213
+ if (!url) {
214
+ const found = await lookup(ref.id, signal);
215
+ url = found.status === 404 || found.json?.deleted_at ? "" : nonEmpty(found.json?.cdp_ws_url);
216
+ if (!url)
217
+ throw new Error("Kernel session is not available for connection");
218
+ cdpUrls.set(held(ref.id), url);
219
+ }
220
+ return { sdkCdpUrl: url };
221
+ },
222
+ async liveView(ref) {
223
+ try {
224
+ let url = liveUrls.get(held(ref.id));
225
+ if (!url) {
226
+ const found = await lookup(ref.id);
227
+ url = found.status === 404 || found.json?.deleted_at ? "" : nonEmpty(found.json?.browser_live_view_url);
228
+ }
229
+ return url ? { fullscreen: url, framed: null, pages: [] } : null;
230
+ }
231
+ catch {
232
+ return null;
233
+ }
234
+ },
235
+ async release(ref, signal) {
236
+ await releaseAndConfirm({
237
+ request: async () => ((await call("DELETE", `/browsers/${encodeURIComponent(ref.id)}`, { signal })).status === 404 ? "gone" : undefined),
238
+ status: () => status(ref, signal),
239
+ forget: () => forget(ref.id),
240
+ confirm,
241
+ sleep,
242
+ stillRunning: `Kernel session ${ref.id} still running after its delete`,
243
+ });
244
+ },
245
+ };
246
+ }
@@ -0,0 +1,47 @@
1
+ import type { ResourceStatus } from "../core/lease.js";
2
+ import type { CdpSession } from "./cdp-call.js";
3
+ export declare const nonEmpty: (v: unknown) => string;
4
+ /** Values are `[A-Za-z0-9._:-]`, at most 60 characters; the tag is exact, since a query matches it whole. */
5
+ export declare const tagValue: (v: string) => string;
6
+ export declare function assertTag(tag: string): void;
7
+ export declare function extensionArchive(): string;
8
+ export declare const accountKey: (origin: string, apiKey: string) => string;
9
+ export declare const defaultSleep: (ms: number) => Promise<void>;
10
+ export declare const DEFAULT_CONFIRM: {
11
+ polls: number;
12
+ intervalMs: number;
13
+ };
14
+ /** The work itself goes on when `signal` fires: another caller may be waiting for it. */
15
+ export declare function untilAborted<T>(work: Promise<T>, signal?: AbortSignal): Promise<T>;
16
+ /** One upload per process and account; a failed upload is forgotten so the next create tries again. */
17
+ export declare function uploadOnce<T>(uploads: Map<string, Promise<T>>, account: string, upload: () => Promise<T>): Promise<T>;
18
+ /** The request is asked twice at most; released means the provider says the session is no longer running, not that the
19
+ * request was sent. `request` answers "gone" when the provider no longer knows the session. */
20
+ export declare function releaseAndConfirm(o: {
21
+ request: () => Promise<"gone" | void>;
22
+ status: () => Promise<ResourceStatus>;
23
+ forget: () => void;
24
+ confirm: {
25
+ polls: number;
26
+ intervalMs: number;
27
+ };
28
+ sleep: (ms: number) => Promise<void>;
29
+ stillRunning: string;
30
+ }): Promise<void>;
31
+ export declare const browserbaseHoldings: {
32
+ connectUrls: Map<string, string>;
33
+ settings: Map<string, Pick<CdpSession, "close" | "open">>;
34
+ opening: Map<string, Promise<void>>;
35
+ uploads: Map<string, Promise<string>>;
36
+ boundDials: Map<string, string>;
37
+ };
38
+ export declare const kernelHoldings: {
39
+ cdpUrls: Map<string, string>;
40
+ liveUrls: Map<string, string>;
41
+ uploads: Map<string, Promise<{
42
+ id: string;
43
+ } | {
44
+ name: string;
45
+ }>>;
46
+ };
47
+ export declare function resetProviderHoldings(): void;
@@ -0,0 +1,82 @@
1
+ import { createHash } from "node:crypto";
2
+ import path from "node:path";
3
+ import { fileURLToPath } from "node:url";
4
+ export const nonEmpty = (v) => String(v ?? "").trim();
5
+ /** Values are `[A-Za-z0-9._:-]`, at most 60 characters; the tag is exact, since a query matches it whole. */
6
+ export const tagValue = (v) => String(v || "").replace(/[^A-Za-z0-9._:-]+/g, "_").slice(0, 60) || "unknown";
7
+ export function assertTag(tag) {
8
+ if (!/^[A-Za-z0-9_.-]+$/.test(tag))
9
+ throw new Error("a session tag is [A-Za-z0-9_.-]");
10
+ }
11
+ export function extensionArchive() {
12
+ return nonEmpty(process.env.STAGEHAND_EXTENSION_ARCHIVE_PATH) || path.join(path.dirname(fileURLToPath(import.meta.resolve("@browserbasehq/stagehand"))), "assets", "stagehand-extension.zip");
13
+ }
14
+ export const accountKey = (origin, apiKey) => `${origin}|${createHash("sha256").update(apiKey).digest("hex").slice(0, 16)}`;
15
+ export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
16
+ export const DEFAULT_CONFIRM = { polls: 6, intervalMs: 500 };
17
+ /** The work itself goes on when `signal` fires: another caller may be waiting for it. */
18
+ export function untilAborted(work, signal) {
19
+ if (!signal)
20
+ return work;
21
+ return new Promise((resolve, reject) => {
22
+ const abort = () => reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
23
+ // The outcome is taken first, so a failure after the caller left is handled, never unhandled.
24
+ work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
25
+ if (signal.aborted)
26
+ return abort();
27
+ signal.addEventListener("abort", abort, { once: true });
28
+ });
29
+ }
30
+ /** One upload per process and account; a failed upload is forgotten so the next create tries again. */
31
+ export function uploadOnce(uploads, account, upload) {
32
+ let up = uploads.get(account);
33
+ if (!up) {
34
+ up = upload();
35
+ uploads.set(account, up);
36
+ up.catch(() => uploads.delete(account));
37
+ }
38
+ return up;
39
+ }
40
+ /** The request is asked twice at most; released means the provider says the session is no longer running, not that the
41
+ * request was sent. `request` answers "gone" when the provider no longer knows the session. */
42
+ export async function releaseAndConfirm(o) {
43
+ let failure;
44
+ for (let attempt = 0; attempt < 2; attempt += 1) {
45
+ try {
46
+ if ((await o.request()) === "gone")
47
+ return o.forget();
48
+ failure = undefined;
49
+ break;
50
+ }
51
+ catch (error) {
52
+ failure = error;
53
+ }
54
+ }
55
+ for (let poll = 0;; poll += 1) {
56
+ const now = await o.status();
57
+ if (now !== "running" && now !== "pending")
58
+ return o.forget();
59
+ if (poll >= o.confirm.polls)
60
+ throw failure ?? new Error(o.stillRunning);
61
+ await o.sleep(o.confirm.intervalMs);
62
+ }
63
+ }
64
+ // Process-wide on purpose: a provider built later (custody builds one for the release) must still close the attach socket,
65
+ // drop the dial binding and reuse the account's upload. The URLs carry tokens and are never written anywhere.
66
+ export const browserbaseHoldings = {
67
+ connectUrls: new Map(),
68
+ settings: new Map(),
69
+ opening: new Map(),
70
+ uploads: new Map(),
71
+ boundDials: new Map(),
72
+ };
73
+ export const kernelHoldings = {
74
+ cdpUrls: new Map(),
75
+ liveUrls: new Map(),
76
+ uploads: new Map(),
77
+ };
78
+ export function resetProviderHoldings() {
79
+ for (const holdings of [browserbaseHoldings, kernelHoldings])
80
+ for (const map of Object.values(holdings))
81
+ map.clear();
82
+ }
@@ -0,0 +1,9 @@
1
+ /** Run in the page: whether any field holding a credential or a one-time code has a value. It looks at password fields, fields that say
2
+ * `one-time-code`, and fields whose name, id, label (a `<label>` for it or around it, or `aria-labelledby`), `aria-label` or placeholder names
3
+ * a code (otp, totp, 2fa, passcode, ...), in the document, in open shadow roots and in same-origin frames. The answer is `true` when one holds
4
+ * a value now (`why: "field"`), or held one since the last check (`why: "typed"`: the page keeps a flag, set by the fields' own `input` events,
5
+ * that a check reports once and clears). Anything it cannot read counts as a credential being present: a page that nests deeper than it reads
6
+ * (`why: "too_deep"`) and a visible frame whose content it cannot reach, a cross-origin frame such as a payment or sign-in widget
7
+ * (`why: "unreadable_frame"`). A frame with no box on the page is not a picture of anything and is not counted. The answer is `{ hold, why }`.
8
+ * What it cannot see at all (a closed shadow root, a value set by script with no event) is the host's to pause with `frames.pause`. (Elements are told by tag, not by class: a frame's elements are of its own realm.) */
9
+ export declare const CREDENTIAL_PROBE = "(() => {\n const named = /(^|[^a-z])(otp|totp|2fa|mfa|passcode|one[-_ ]?time|verification[-_ ]?code|security[-_ ]?code|auth(entication)?[-_ ]?code)([^a-z]|$)/i;\n const words = (el) => {\n let text = [el.name, el.id, el.getAttribute(\"aria-label\") || \"\", el.placeholder || \"\"].join(\" \");\n try { for (const label of el.labels || []) text += \" \" + label.textContent; } catch (error) { /* no labels */ }\n const ids = el.getAttribute(\"aria-labelledby\");\n if (ids) { const root = el.getRootNode(); for (const id of ids.split(/s+/)) { const node = root.getElementById ? root.getElementById(id) : null; if (node) text += \" \" + node.textContent; } }\n return text;\n };\n const like = (el) => el.localName === \"input\" && (el.type === \"password\" || el.autocomplete === \"one-time-code\" || named.test(words(el)));\n const state = window.__piFramesSecret || (window.__piFramesSecret = { seen: false });\n if (!state.listening) {\n state.listening = true;\n addEventListener(\"input\", (event) => { const el = event.target; if (el && el.localName === \"input\" && el.value !== \"\" && like(el)) state.seen = true; }, true);\n }\n let blind = null;\n const shown = (el) => { const style = getComputedStyle(el); return el.clientWidth >= 2 && el.clientHeight >= 2 && style.display !== \"none\" && style.visibility !== \"hidden\"; };\n const scan = (root, depth) => {\n for (const el of root.querySelectorAll(\"*\")) {\n if (el.localName === \"input\" && el.value !== \"\" && like(el)) return true;\n const shadow = el.shadowRoot;\n const frame = el.localName === \"iframe\";\n if (!shadow && !frame) continue;\n if (depth >= 8) { blind = blind || \"too_deep\"; continue; }\n if (shadow && scan(shadow, depth + 1)) return true;\n if (frame) {\n let inside = null;\n try { inside = el.contentDocument; } catch (error) { inside = null; }\n if (inside) { if (scan(inside, depth + 1)) return true; }\n else if (shown(el)) blind = blind || \"unreadable_frame\";\n }\n }\n return false;\n };\n const found = scan(document, 0);\n const seen = state.seen;\n state.seen = false;\n if (found) return { hold: true, why: \"field\" };\n if (seen) return { hold: true, why: \"typed\" };\n return blind ? { hold: true, why: blind } : { hold: false, why: null };\n})()";
@@ -0,0 +1,49 @@
1
+ /** Run in the page: whether any field holding a credential or a one-time code has a value. It looks at password fields, fields that say
2
+ * `one-time-code`, and fields whose name, id, label (a `<label>` for it or around it, or `aria-labelledby`), `aria-label` or placeholder names
3
+ * a code (otp, totp, 2fa, passcode, ...), in the document, in open shadow roots and in same-origin frames. The answer is `true` when one holds
4
+ * a value now (`why: "field"`), or held one since the last check (`why: "typed"`: the page keeps a flag, set by the fields' own `input` events,
5
+ * that a check reports once and clears). Anything it cannot read counts as a credential being present: a page that nests deeper than it reads
6
+ * (`why: "too_deep"`) and a visible frame whose content it cannot reach, a cross-origin frame such as a payment or sign-in widget
7
+ * (`why: "unreadable_frame"`). A frame with no box on the page is not a picture of anything and is not counted. The answer is `{ hold, why }`.
8
+ * What it cannot see at all (a closed shadow root, a value set by script with no event) is the host's to pause with `frames.pause`. (Elements are told by tag, not by class: a frame's elements are of its own realm.) */
9
+ export const CREDENTIAL_PROBE = `(() => {
10
+ const named = /(^|[^a-z])(otp|totp|2fa|mfa|passcode|one[-_ ]?time|verification[-_ ]?code|security[-_ ]?code|auth(entication)?[-_ ]?code)([^a-z]|$)/i;
11
+ const words = (el) => {
12
+ let text = [el.name, el.id, el.getAttribute("aria-label") || "", el.placeholder || ""].join(" ");
13
+ try { for (const label of el.labels || []) text += " " + label.textContent; } catch (error) { /* no labels */ }
14
+ const ids = el.getAttribute("aria-labelledby");
15
+ if (ids) { const root = el.getRootNode(); for (const id of ids.split(/\s+/)) { const node = root.getElementById ? root.getElementById(id) : null; if (node) text += " " + node.textContent; } }
16
+ return text;
17
+ };
18
+ const like = (el) => el.localName === "input" && (el.type === "password" || el.autocomplete === "one-time-code" || named.test(words(el)));
19
+ const state = window.__piFramesSecret || (window.__piFramesSecret = { seen: false });
20
+ if (!state.listening) {
21
+ state.listening = true;
22
+ addEventListener("input", (event) => { const el = event.target; if (el && el.localName === "input" && el.value !== "" && like(el)) state.seen = true; }, true);
23
+ }
24
+ let blind = null;
25
+ const shown = (el) => { const style = getComputedStyle(el); return el.clientWidth >= 2 && el.clientHeight >= 2 && style.display !== "none" && style.visibility !== "hidden"; };
26
+ const scan = (root, depth) => {
27
+ for (const el of root.querySelectorAll("*")) {
28
+ if (el.localName === "input" && el.value !== "" && like(el)) return true;
29
+ const shadow = el.shadowRoot;
30
+ const frame = el.localName === "iframe";
31
+ if (!shadow && !frame) continue;
32
+ if (depth >= 8) { blind = blind || "too_deep"; continue; }
33
+ if (shadow && scan(shadow, depth + 1)) return true;
34
+ if (frame) {
35
+ let inside = null;
36
+ try { inside = el.contentDocument; } catch (error) { inside = null; }
37
+ if (inside) { if (scan(inside, depth + 1)) return true; }
38
+ else if (shown(el)) blind = blind || "unreadable_frame";
39
+ }
40
+ }
41
+ return false;
42
+ };
43
+ const found = scan(document, 0);
44
+ const seen = state.seen;
45
+ state.seen = false;
46
+ if (found) return { hold: true, why: "field" };
47
+ if (seen) return { hold: true, why: "typed" };
48
+ return blind ? { hold: true, why: blind } : { hold: false, why: null };
49
+ })()`;
@@ -0,0 +1,26 @@
1
+ export type FollowHandlers = {
2
+ /** One screencast frame of the followed page: JPEG bytes and the page's own width and height as the browser reports them. */
3
+ frame(bytes: Buffer, page: {
4
+ deviceWidth: number;
5
+ deviceHeight: number;
6
+ epoch: number;
7
+ }): void;
8
+ /** The followed page's main frame navigated. */
9
+ navigated(): void;
10
+ /** The socket ended and was not asked to. */
11
+ closed(): void;
12
+ };
13
+ export type Follower = {
14
+ /** Runs an expression in the followed page and gives its value; rejects when there is no page, the page errors or nothing answers in `ms`. */
15
+ evaluate(expression: string, ms?: number): Promise<unknown>;
16
+ /** Which page, at which moment of its life, the capture is on: it changes when the capture moves to another page and at every main-frame
17
+ * navigation, so a frame held across a change can be told from one of the page now shown. */
18
+ epoch(): number;
19
+ close(): void;
20
+ };
21
+ export type FollowOptions = {
22
+ maxWidth: number;
23
+ maxHeight: number;
24
+ quality: number;
25
+ };
26
+ export declare function followPage(url: string, handlers: FollowHandlers, options: FollowOptions): Follower;
@@ -0,0 +1,138 @@
1
+ // A read-only screencast of the page an agent is using, over a browser's DevTools socket. It attaches beside whatever else is
2
+ // connected (the driver, the effect observer); every frame is acknowledged at once, whatever is done with it.
3
+ export function followPage(url, handlers, options) {
4
+ const socket = new WebSocket(url);
5
+ let seq = 0;
6
+ let closing = false;
7
+ let current = null;
8
+ let epoch = 0;
9
+ /** Every page the browser has: its address, and when it was last opened or moved (an arrival counter, not a clock). */
10
+ const pages = new Map();
11
+ let moves = 0;
12
+ const waiting = new Map();
13
+ const send = (method, params = {}, sessionId) => {
14
+ const id = ++seq;
15
+ if (socket.readyState === 1)
16
+ socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
17
+ return id;
18
+ };
19
+ const follow = (targetId, url) => {
20
+ if (current?.targetId === targetId)
21
+ return;
22
+ epoch += 1;
23
+ if (current?.sessionId)
24
+ send("Target.detachFromTarget", { sessionId: current.sessionId });
25
+ current = { targetId, sessionId: null, url };
26
+ send("Target.attachToTarget", { targetId, flatten: true });
27
+ };
28
+ /** The page in use: the one most recently opened or moved to an address, a blank one only when no other exists. The browser lists its
29
+ * pages in no order that says which the agent is on, so arrival is what is read. */
30
+ const choose = () => {
31
+ let best = null;
32
+ for (const [id, page] of pages) {
33
+ const blank = page.url === "about:blank" || page.url === "";
34
+ const bestBlank = best !== null && (best.url === "about:blank" || best.url === "");
35
+ if (best === null || (bestBlank && !blank) || (bestBlank === blank && page.moved > best.moved))
36
+ best = { id, url: page.url, moved: page.moved };
37
+ }
38
+ if (best)
39
+ follow(best.id, best.url);
40
+ };
41
+ socket.onopen = () => { send("Target.setDiscoverTargets", { discover: true }); };
42
+ socket.onmessage = (event) => {
43
+ let message;
44
+ try {
45
+ message = JSON.parse(String(event.data));
46
+ }
47
+ catch {
48
+ return;
49
+ }
50
+ if (message.id !== undefined && waiting.has(message.id)) {
51
+ const entry = waiting.get(message.id);
52
+ waiting.delete(message.id);
53
+ clearTimeout(entry.timer);
54
+ if (message.error)
55
+ entry.reject(new Error(message.error.message ?? "the browser refused"));
56
+ else if (message.result?.exceptionDetails)
57
+ entry.reject(new Error("the page threw"));
58
+ else
59
+ entry.resolve(message.result?.result?.value);
60
+ return;
61
+ }
62
+ const { method, params, sessionId } = message;
63
+ if (method === "Target.targetCreated" && params.targetInfo.type === "page") {
64
+ pages.set(params.targetInfo.targetId, { url: params.targetInfo.url, moved: (moves += 1) });
65
+ choose();
66
+ }
67
+ else if (method === "Target.targetInfoChanged" && params.targetInfo.type === "page") {
68
+ const known = pages.get(params.targetInfo.targetId);
69
+ // A page that moved to a new address is the one in use; a new title on the same address is not a move.
70
+ if (!known)
71
+ pages.set(params.targetInfo.targetId, { url: params.targetInfo.url, moved: (moves += 1) });
72
+ else if (known.url !== params.targetInfo.url) {
73
+ known.url = params.targetInfo.url;
74
+ known.moved = (moves += 1);
75
+ }
76
+ choose();
77
+ }
78
+ else if (method === "Target.attachedToTarget") {
79
+ const page = current;
80
+ if (!page || params.targetInfo.targetId !== page.targetId) {
81
+ send("Target.detachFromTarget", { sessionId: params.sessionId });
82
+ return;
83
+ }
84
+ page.sessionId = params.sessionId;
85
+ send("Page.enable", {}, params.sessionId);
86
+ send("Page.startScreencast", { format: "jpeg", quality: options.quality, maxWidth: options.maxWidth, maxHeight: options.maxHeight }, params.sessionId);
87
+ }
88
+ else if (method === "Page.screencastFrame") {
89
+ send("Page.screencastFrameAck", { sessionId: params.sessionId }, sessionId);
90
+ if (sessionId !== current?.sessionId)
91
+ return;
92
+ handlers.frame(Buffer.from(String(params.data), "base64"), { deviceWidth: Number(params.metadata?.deviceWidth) || 0, deviceHeight: Number(params.metadata?.deviceHeight) || 0, epoch });
93
+ }
94
+ else if (method === "Page.frameNavigated" && sessionId === current?.sessionId && !params.frame?.parentId) {
95
+ epoch += 1;
96
+ handlers.navigated();
97
+ }
98
+ else if (method === "Target.targetDestroyed") {
99
+ pages.delete(params.targetId);
100
+ if (params.targetId === current?.targetId) {
101
+ current = null;
102
+ epoch += 1;
103
+ }
104
+ choose();
105
+ }
106
+ };
107
+ socket.onerror = () => { };
108
+ socket.onclose = () => {
109
+ for (const entry of waiting.values()) {
110
+ clearTimeout(entry.timer);
111
+ entry.reject(new Error("the browser's socket closed"));
112
+ }
113
+ waiting.clear();
114
+ if (!closing)
115
+ handlers.closed();
116
+ };
117
+ return {
118
+ evaluate(expression, ms = 1_500) {
119
+ const sessionId = current?.sessionId;
120
+ if (!sessionId || socket.readyState !== 1)
121
+ return Promise.reject(new Error("no page to ask"));
122
+ return new Promise((resolve, reject) => {
123
+ const id = send("Runtime.evaluate", { expression, returnByValue: true }, sessionId);
124
+ const timer = setTimeout(() => { waiting.delete(id); reject(new Error("the page did not answer")); }, ms);
125
+ timer.unref?.();
126
+ waiting.set(id, { resolve, reject, timer });
127
+ });
128
+ },
129
+ epoch: () => epoch,
130
+ close() { closing = true; for (const entry of waiting.values()) {
131
+ clearTimeout(entry.timer);
132
+ entry.reject(new Error("closed"));
133
+ } waiting.clear(); try {
134
+ socket.close();
135
+ }
136
+ catch { /* already closed */ } },
137
+ };
138
+ }