@parcha/pi-browser 0.1.0-beta.35 → 0.1.0-beta.37

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 (46) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +20 -25
  3. package/dist/core/driving-guard.d.ts +1 -1
  4. package/dist/core/driving-guard.js +1 -1
  5. package/dist/core/host.d.ts +1 -12
  6. package/dist/core/images.d.ts +32 -4
  7. package/dist/core/images.js +81 -16
  8. package/dist/core/page-scan.d.ts +69 -0
  9. package/dist/core/page-scan.js +467 -10
  10. package/dist/core/public-fetch.js +3 -0
  11. package/dist/core/read-page.js +20 -4
  12. package/dist/core/tools.js +4 -1
  13. package/dist/core/vault.d.ts +0 -10
  14. package/dist/core/vault.js +0 -13
  15. package/dist/driver/cdp.js +3 -3
  16. package/dist/driver/page-driver.js +7 -3
  17. package/dist/durable/store.d.ts +1 -1
  18. package/dist/durable.d.ts +6 -1
  19. package/dist/durable.js +24 -5
  20. package/dist/index.d.ts +1 -0
  21. package/dist/index.js +3 -0
  22. package/dist/live-view/index.d.ts +2 -0
  23. package/dist/live-view/index.js +4 -0
  24. package/dist/live-view/server.d.ts +11 -0
  25. package/dist/live-view/server.js +13 -2
  26. package/dist/providers/cdp.js +2 -2
  27. package/dist/providers/profiles.d.ts +1 -15
  28. package/dist/providers/profiles.js +1 -64
  29. package/dist/providers/shared.d.ts +1 -47
  30. package/dist/providers/shared.js +1 -82
  31. package/dist/providers/worker-extension.js +1 -1
  32. package/dist/testing/backend.d.ts +4 -3
  33. package/dist/testing/backend.js +6 -5
  34. package/dist/vault-session.d.ts +4 -7
  35. package/dist/vault-session.js +26 -81
  36. package/dist/vendor/browser-use-pi/page.d.ts +3 -12
  37. package/dist/vendor/browser-use-pi/page.js +6 -19
  38. package/package.json +7 -20
  39. package/dist/providers/browserbase-net.d.ts +0 -12
  40. package/dist/providers/browserbase-net.js +0 -95
  41. package/dist/providers/browserbase.d.ts +0 -138
  42. package/dist/providers/browserbase.js +0 -294
  43. package/dist/providers/kernel.d.ts +0 -58
  44. package/dist/providers/kernel.js +0 -291
  45. /package/dist/{providers → core}/cdp-call.d.ts +0 -0
  46. /package/dist/{providers → core}/cdp-call.js +0 -0
@@ -1,294 +0,0 @@
1
- // Credentials come from the host's env and live in this module's memory only: a ref is `{ id, tag }`, and the connect
2
- // URL (it carries a signing key) is held here, found again by `retrieve` after a restart.
3
- import { createReadStream } from "node:fs";
4
- import { isRefusal } from "../core/failures.js";
5
- import { resolvePrices } from "../core/usage.js";
6
- import { cdpCall } from "./cdp-call.js";
7
- import { applyBrowserbaseNoProxy, bindConnectDial, installWebSocketWrapper, rewriteConnectUrl, unbindConnectDial } from "./browserbase-net.js";
8
- import { directFetch } from "./http.js";
9
- import { claimWriter, fileProfileStore, freeWriter, isWriter, noteWriter } from "./profiles.js";
10
- import { accountKey, assertTag, browserbaseHoldings, defaultSleep, DEFAULT_CONFIRM, extensionArchive, nonEmpty, releaseAndConfirm, tagValue, uploadOnce } from "./shared.js";
11
- export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
12
- export { fileProfileStore, memoryProfileStore } from "./profiles.js";
13
- /** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
14
- export const setDownloadBehavior = (url, options = {}) => cdpCall(url, "Browser.setDownloadBehavior", { behavior: "allow", downloadPath: options.downloadPath ?? "downloads", eventsEnabled: true }, options.timeoutMs);
15
- const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, profiles: true, extension: "uploaded-per-launch", settings: { proxies: true, verified: true, geolocation: true, region: true, context: true },
16
- // A session is created with `allowedDomains` from the policy's allow list, which Browserbase enforces.
17
- navigationAllow: true };
18
- const notFound = (e) => e?.status === 404;
19
- /** One signal for whichever of these there is (a store may call `make` without its limit). */
20
- const stopWhen = (...signals) => { const some = signals.filter((s) => s !== undefined); return some.length > 1 ? AbortSignal.any(some) : some[0]; };
21
- /** ISO alpha-2 country, US state abbreviation, upper-case city; no two-letter country, no geolocation. */
22
- export function browserbaseGeolocation(raw) {
23
- const country = nonEmpty(raw?.country).toUpperCase();
24
- if (!/^[A-Z]{2}$/.test(country))
25
- return null;
26
- const out = { country };
27
- const state = nonEmpty(raw?.state).toUpperCase();
28
- if (/^[A-Z]{2}$/.test(state))
29
- out.state = state;
30
- const city = nonEmpty(raw?.city).toUpperCase().replace(/[\s-]+/g, "_").replace(/[^A-Z_]/g, "");
31
- if (city)
32
- out.city = city;
33
- return out;
34
- }
35
- export function proxiesField(proxies) {
36
- if (!proxies)
37
- return false;
38
- const geo = typeof proxies === "object" ? browserbaseGeolocation(proxies.geolocation) : null;
39
- return geo ? [{ type: "browserbase", geolocation: geo }] : true;
40
- }
41
- export function sessionCreateBody(spec, extra = {}) {
42
- const settings = {
43
- solveCaptchas: spec.captcha,
44
- viewport: spec.viewport,
45
- ...(spec.verified ? { verified: true } : {}),
46
- ...(extra.context ? { context: extra.context } : spec.contextId ? { context: { id: spec.contextId, persist: true } } : {}),
47
- ...(spec.navigation?.allow?.length ? { allowedDomains: spec.navigation.allow } : {}),
48
- };
49
- const userMetadata = Object.fromEntries(Object.entries(spec.metadata).map(([k, v]) => [k, tagValue(v)]));
50
- return {
51
- proxies: proxiesField(spec.proxies),
52
- timeout: spec.maxLifetimeS,
53
- // Without keepAlive Browserbase ends a session when any CDP client disconnects (a crash, a second client, a closed
54
- // observer); with it only an explicit release or the timeout does.
55
- keepAlive: true,
56
- browserSettings: settings,
57
- userMetadata: { ...userMetadata, agentrun_tag: spec.tag },
58
- ...(spec.region ? { region: spec.region } : {}),
59
- ...(extra.extensionId ? { extensionId: extra.extensionId } : {}),
60
- ...(extra.projectId ? { projectId: extra.projectId } : {}),
61
- };
62
- }
63
- const { connectUrls, settings, opening, uploads } = browserbaseHoldings;
64
- const endSetting = (id) => { settings.get(id)?.close(); settings.delete(id); };
65
- const forget = (id) => { const url = connectUrls.get(id); if (url)
66
- unbindConnectDial(url); connectUrls.delete(id); };
67
- export function browserbaseProvider(options = {}) {
68
- const env = options.env ?? process.env;
69
- const apiKey = nonEmpty(env.BROWSERBASE_API_KEY) || nonEmpty(env.BB_API_KEY);
70
- const baseUrl = nonEmpty(env.BROWSERBASE_BASE_URL) || undefined;
71
- const connectBase = nonEmpty(env.BROWSERBASE_CONNECT_BASE_URL) || null;
72
- const account = accountKey(baseUrl ?? "", apiKey);
73
- const held = (id) => `${account}|${id}`;
74
- const sleep = options.sleep ?? defaultSleep;
75
- const confirm = options.confirm ?? DEFAULT_CONFIRM;
76
- const prices = resolvePrices(options.prices);
77
- const profiles = options.profiles ?? fileProfileStore();
78
- /** The context each live session of this provider runs on, by tag: what a session vault may keep. */
79
- const contexts = new Map();
80
- let sdk = null;
81
- const client = () => (sdk ??= options.client ? Promise.resolve(options.client) : (async () => {
82
- applyBrowserbaseNoProxy(env);
83
- const mod = await import(["@browserbasehq", "sdk"].join("/"));
84
- const Browserbase = mod.default ?? mod.Browserbase;
85
- return new Browserbase({ apiKey, baseURL: baseUrl, fetch: await directFetch() });
86
- })());
87
- const extension = () => options.extensionId
88
- ? options.extensionId()
89
- : uploadOnce(uploads, account, async () => (await (await client()).extensions.create({ file: createReadStream(extensionArchive()) }, { maxRetries: 0 })).id);
90
- const contextFor = (name, projectId, signal) => profiles.resolve(held(`profile:${name}`), async (limit) => (await (await client()).contexts.create({ ...(projectId && !baseUrl && !connectBase ? { projectId } : {}) }, { maxRetries: 0, signal: stopWhen(signal, limit) })).id);
91
- const rows = async (sessionId) => {
92
- const all = [];
93
- for (let offset = 0;;) {
94
- const page = await (await client()).get("/v1/downloads", { query: { sessionId, limit: 100, offset } });
95
- const got = Array.isArray(page?.downloads) ? page.downloads : [];
96
- all.push(...got);
97
- offset += got.length;
98
- if (!got.length || offset >= Number(page?.total ?? 0))
99
- return all;
100
- }
101
- };
102
- const settling = new Set();
103
- const running = (ref) => async (signal) => { if (settling.has(ref.tag))
104
- return true; const now = await status(ref, signal); return now === "running" || now === "pending"; };
105
- /** A saving session's context is written back after it ends, and the next session must not read it before then. */
106
- const finished = async (ref) => {
107
- forget(held(ref.id));
108
- if (isWriter(ref.tag)) {
109
- settling.add(ref.tag);
110
- try {
111
- await sleep(options.profileSettleMs ?? 5_000);
112
- }
113
- finally {
114
- settling.delete(ref.tag);
115
- }
116
- }
117
- freeWriter(ref.tag);
118
- };
119
- const status = async (ref, signal) => {
120
- try {
121
- const found = await (await client()).sessions.retrieve(ref.id, { signal, timeout: 5_000 });
122
- return found.status === "RUNNING" ? "running" : found.status === "PENDING" ? "pending" : "stopped";
123
- }
124
- catch (error) {
125
- if (notFound(error))
126
- return "gone";
127
- throw error;
128
- }
129
- };
130
- return {
131
- name: "browserbase",
132
- caps: CAPS,
133
- vault: { kind: "context", provider: "browserbase", contextIdsInClear: profiles.clear === true, contextOf: (ref) => contexts.get(ref.tag) ?? null },
134
- async create(spec, signal) {
135
- const projectId = nonEmpty(env.BROWSERBASE_PROJECT_ID);
136
- if (spec.profile?.save)
137
- await claimWriter(held(`profile:${spec.profile.name}`), spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
138
- // A context given by id (a vault's kept one) is written back at the end like a profile's: one session at a time saves to it, and the next waits for the write. The id is a capability, so the refusal names no id.
139
- else if (!spec.profile && spec.contextId)
140
- await claimWriter(held(`context:${spec.contextId}`), "the kept context", spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
141
- let body;
142
- try {
143
- const context = spec.profile ? { id: await contextFor(spec.profile.name, projectId, signal), persist: spec.profile.save } : undefined;
144
- const usedContext = context?.id ?? spec.contextId;
145
- if (usedContext)
146
- contexts.set(spec.tag, usedContext);
147
- // Behind the credential proxy the project is inferred from the injected key and must never be named; a direct key
148
- // must name it.
149
- body = sessionCreateBody(spec, { extensionId: await extension(), ...(projectId && !baseUrl && !connectBase ? { projectId } : {}), ...(context ? { context } : {}) });
150
- }
151
- catch (error) {
152
- freeWriter(spec.tag);
153
- throw error;
154
- }
155
- // At most once: an SDK retry of a create the server already served would open a second paid browser. A failed send keeps
156
- // the profile's claim until findByTag has looked: the session may exist. A refusal (401, 403) made none, so it frees the claim.
157
- const created = await (await client()).sessions.create(body, { maxRetries: 0, signal }).catch((error) => {
158
- if (isRefusal(error))
159
- freeWriter(spec.tag);
160
- throw error;
161
- });
162
- connectUrls.set(held(created.id), created.connectUrl);
163
- noteWriter(spec.tag, running({ id: created.id, tag: spec.tag }), () => sleep(options.profileSettleMs ?? 5_000));
164
- return { id: created.id, tag: spec.tag };
165
- },
166
- async findByTag(tag, signal) {
167
- assertTag(tag);
168
- // `q` alone makes Browserbase answer 504 after 75 s; with a status it answers in about 150 ms. A create whose
169
- // answer was lost may have left the session PENDING, which still bills once it runs, so both statuses are asked.
170
- const q = `user_metadata['agentrun_tag']:'${tag}'`;
171
- const asked = await Promise.all(["RUNNING", "PENDING"].map(async (status) => (await client()).sessions.list({ status, q }, { signal })));
172
- // The query is the provider's, the match is ours: a lane that ignores `q` must never hand back someone else's
173
- // session. Both queries must answer: custody releases exactly these ids, so a failed status throws.
174
- const seen = new Set();
175
- const found = asked.flat().filter((r) => r.userMetadata?.agentrun_tag === tag && !seen.has(r.id) && seen.add(r.id)).map((r) => ({ id: r.id, tag }));
176
- if (!found.length)
177
- freeWriter(tag);
178
- for (const ref of found)
179
- if (isWriter(ref.tag))
180
- noteWriter(ref.tag, running(ref), () => sleep(options.profileSettleMs ?? 5_000));
181
- return found;
182
- },
183
- status,
184
- async attach(ref, signal) {
185
- let url = connectUrls.get(held(ref.id));
186
- if (!url) {
187
- url = (await (await client()).sessions.retrieve(ref.id, { signal })).connectUrl;
188
- if (!url)
189
- throw new Error("Browserbase session is not available for connection");
190
- connectUrls.set(held(ref.id), url);
191
- }
192
- // No `extensionId` on connect: the extension rides the create (given the upload id, connect waited 60 s for a
193
- // worker that never came).
194
- bindConnectDial(url, connectBase);
195
- if (connectBase)
196
- installWebSocketWrapper();
197
- const dial = connectBase ? rewriteConnectUrl(url, connectBase) : url;
198
- // Browserbase syncs a download only when the browser was told to save into `downloads`, which lasts as long as
199
- // that socket: one socket per session is held until release. A failure costs the files, not the session.
200
- const key = held(ref.id);
201
- if (!settings.get(key)?.open) {
202
- let pending = opening.get(key);
203
- if (!pending) {
204
- pending = (async () => { const setting = await (options.downloadBehavior ?? setDownloadBehavior)(dial).catch(() => undefined); if (setting)
205
- settings.set(key, setting); })().finally(() => opening.delete(key));
206
- opening.set(key, pending);
207
- }
208
- await pending;
209
- }
210
- return { sdkCdpUrl: url, ...(connectBase ? { dial: { url: dial } } : {}) };
211
- },
212
- async release(ref, signal) {
213
- contexts.delete(ref.tag);
214
- await opening.get(held(ref.id));
215
- endSetting(held(ref.id));
216
- await releaseAndConfirm({
217
- request: async () => {
218
- try {
219
- await (await client()).sessions.update(ref.id, { status: "REQUEST_RELEASE" }, { maxRetries: 0, signal });
220
- }
221
- catch (error) {
222
- if (notFound(error))
223
- return "gone";
224
- throw error;
225
- }
226
- },
227
- status: () => status(ref, signal),
228
- forget: () => finished(ref),
229
- confirm,
230
- sleep,
231
- stillRunning: `Browserbase session ${ref.id} still running after a release request`,
232
- });
233
- },
234
- async liveView(ref) {
235
- try {
236
- const live = await (await client()).sessions.debug(ref.id);
237
- return {
238
- fullscreen: live.debuggerFullscreenUrl ?? null,
239
- framed: live.debuggerUrl ?? null,
240
- pages: (live.pages ?? []).map((p) => ({ id: p.id ?? null, url: p.url ?? null, title: p.title ?? null, fullscreen: p.debuggerFullscreenUrl ?? null })),
241
- };
242
- }
243
- catch {
244
- return null;
245
- }
246
- },
247
- downloads: {
248
- // Browserbase suffixes each name with a timestamp, so a name is unique in a session.
249
- async list(ref) {
250
- return (await rows(ref.id)).map((d) => ({ name: d.filename, sizeBytes: d.size, modifiedAt: d.createdAt ?? null }));
251
- },
252
- async read(ref, name, maxBytes) {
253
- const row = (await rows(ref.id)).find((d) => d.filename === name);
254
- if (!row)
255
- throw new Error(`no download ${name} for session ${ref.id}`);
256
- const response = await (await client()).get(`/v1/downloads/${encodeURIComponent(row.id)}`, { headers: { Accept: "application/octet-stream" }, __binaryResponse: true });
257
- if (!response?.body)
258
- throw new Error("the download came back empty");
259
- return (async function* () {
260
- let total = 0;
261
- for await (const chunk of response.body) {
262
- total += chunk.byteLength;
263
- if (total > maxBytes)
264
- throw new Error(`larger than the ${maxBytes}-byte limit`);
265
- yield chunk;
266
- }
267
- })();
268
- },
269
- },
270
- recordings: {
271
- // One entry per rendered tab MP4 of an ended session; asking renders them, so a caller polls `list` until it
272
- // fills.
273
- async list(ref) {
274
- const rec = (await client()).sessions.recording?.downloads;
275
- if (!rec)
276
- return [];
277
- let downloads = (await rec.list(ref.id)).downloads ?? [];
278
- if (!downloads.length || downloads.some((d) => d.status === "NOT_REQUESTED"))
279
- downloads = (await rec.create(ref.id)).downloads ?? downloads;
280
- return downloads.filter((d) => d.status === "COMPLETED" && d.downloadUrl).map((d) => ({ id: String(d.pageId), startedAt: null, durationS: null }));
281
- },
282
- async open(ref, id) {
283
- const rec = (await client()).sessions.recording?.downloads;
284
- const found = (await rec?.list(ref.id))?.downloads?.find((d) => String(d.pageId) === id && d.status === "COMPLETED" && d.downloadUrl);
285
- if (!found?.downloadUrl)
286
- throw new Error(`no rendered recording ${id} for session ${ref.id}`);
287
- const response = await (await directFetch())(found.downloadUrl);
288
- if (!response.ok || !response.body)
289
- throw new Error(`recording download answered ${response.status}`);
290
- return response.body;
291
- },
292
- },
293
- };
294
- }
@@ -1,58 +0,0 @@
1
- import type { BrowserProvider, SessionSpec } from "../core/host.js";
2
- export declare const KERNEL_BASE_URL = "https://api.onkernel.com";
3
- export declare const KERNEL_IDLE_MIN_S = 10;
4
- export declare const KERNEL_IDLE_MAX_S = 259200;
5
- /** What the provider reads of a reply: the global fetch's Response and undici's both have it. */
6
- type HttpReply = {
7
- ok: boolean;
8
- status: number;
9
- headers: {
10
- get(name: string): string | null;
11
- };
12
- text(): Promise<string>;
13
- };
14
- type HttpFetch = (input: string, init: {
15
- method: string;
16
- headers: Record<string, string>;
17
- body?: Uint8Array | string;
18
- signal?: AbortSignal;
19
- }) => Promise<HttpReply>;
20
- export type KernelOptions = {
21
- /** KERNEL_API_KEY and KERNEL_BASE_URL (default https://api.onkernel.com). Default: process.env. */
22
- env?: NodeJS.ProcessEnv;
23
- /** Kernel's stealth mode, which also turns on its CAPTCHA solver and its stealth proxy. Default false. */
24
- stealth?: boolean;
25
- headless?: boolean;
26
- /** Default: one stored with the same bytes, else uploaded once per process and account. */
27
- extension?: () => Promise<KernelExtensionRef>;
28
- confirm?: {
29
- polls: number;
30
- intervalMs: number;
31
- };
32
- sleep?: (ms: number) => Promise<void>;
33
- /** Default: a direct undici Agent that never uses HTTP(S)_PROXY; a host behind a proxy passes its own. */
34
- fetch?: HttpFetch;
35
- };
36
- export type KernelProvider = BrowserProvider & {
37
- readonly name: "kernel";
38
- };
39
- export type KernelExtensionRef = {
40
- id: string;
41
- } | {
42
- name: string;
43
- };
44
- /** The call and the HTTP status, plus Kernel's error code when it is a plain identifier. Kernel's message is never
45
- * copied: an echo of the request could carry the key or a URL. */
46
- export declare class KernelError extends Error {
47
- readonly status: number | undefined;
48
- constructor(call: string, status: number | undefined, code?: string, options?: {
49
- cause?: unknown;
50
- });
51
- }
52
- export declare function kernelCreateBody(spec: SessionSpec, options?: {
53
- stealth?: boolean;
54
- headless?: boolean;
55
- extension?: KernelExtensionRef;
56
- }): Record<string, unknown>;
57
- export declare function kernelProvider(options?: KernelOptions): KernelProvider;
58
- export {};
@@ -1,291 +0,0 @@
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 { isRefusal } from "../core/failures.js";
6
- import { directFetch } from "./http.js";
7
- import { claimWriter, freeWriter, isWriter, noteWriter } from "./profiles.js";
8
- import { accountKey, assertTag, defaultSleep, DEFAULT_CONFIRM, extensionArchive, kernelHoldings, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
9
- export const KERNEL_BASE_URL = "https://api.onkernel.com";
10
- export const KERNEL_IDLE_MIN_S = 10;
11
- export const KERNEL_IDLE_MAX_S = 259_200;
12
- // Kernel ends a session after `timeout_seconds` with no CDP or live-view connection and sets no wall-clock limit, so
13
- // the lifetime cap is its largest idle timeout.
14
- const CAPS = { timeoutModel: "inactivity", maxLifetimeS: KERNEL_IDLE_MAX_S, survivesDisconnect: true, releaseIsAsync: false, profiles: true, extension: "uploaded-per-launch", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
15
- /** The call and the HTTP status, plus Kernel's error code when it is a plain identifier. Kernel's message is never
16
- * copied: an echo of the request could carry the key or a URL. */
17
- export class KernelError extends Error {
18
- status;
19
- constructor(call, status, code, options) {
20
- super(status === undefined ? `Kernel ${call} could not be reached` : `Kernel ${call} answered ${status}${code ? ` (${code})` : ""}`, options);
21
- this.name = "KernelError";
22
- this.status = status;
23
- }
24
- }
25
- const CODE = /^[a-z][a-z_.-]{0,47}$/i;
26
- export function kernelCreateBody(spec, options = {}) {
27
- const tags = Object.fromEntries(Object.entries(spec.metadata).map(([k, v]) => [k, tagValue(v)]));
28
- return {
29
- headless: options.headless ?? false,
30
- stealth: options.stealth ?? false,
31
- // Explicit, never Kernel's default (60 s): a crashed host's browser stops costing money on its own while custody's
32
- // release is pending.
33
- timeout_seconds: Math.min(KERNEL_IDLE_MAX_S, Math.max(KERNEL_IDLE_MIN_S, Math.round(spec.idleTimeoutS) || KERNEL_IDLE_MIN_S)),
34
- viewport: { width: spec.viewport.width, height: spec.viewport.height },
35
- tags: { ...tags, agentrun_tag: spec.tag },
36
- ...(spec.profile ? { profile: { name: spec.profile.name, save_changes: spec.profile.save } } : {}),
37
- ...(options.extension ? { extensions: [options.extension] } : {}),
38
- };
39
- }
40
- const { cdpUrls, liveUrls, uploads } = kernelHoldings;
41
- export function kernelProvider(options = {}) {
42
- const env = options.env ?? process.env;
43
- const apiKey = nonEmpty(env.KERNEL_API_KEY);
44
- const baseUrl = (nonEmpty(env.KERNEL_BASE_URL) || KERNEL_BASE_URL).replace(/\/+$/, "");
45
- const account = accountKey(baseUrl, apiKey);
46
- const held = (id) => `${account}|${id}`;
47
- const sleep = options.sleep ?? defaultSleep;
48
- const confirm = options.confirm ?? DEFAULT_CONFIRM;
49
- let client = null;
50
- const http = () => (client ??= options.fetch ? Promise.resolve(options.fetch) : directFetch());
51
- /** One request, never retried: a create served twice would be a second paid browser. On failure only Kernel's `code`
52
- * survives; a transport failure keeps its cause chain under a message that names the call alone. */
53
- async function call(method, route, init = {}) {
54
- if (!apiKey)
55
- throw new Error("the kernel provider needs KERNEL_API_KEY in the env it is given; none is set");
56
- const name = `${method} ${route.replace(/\/browsers\/[^/?]+/, "/browsers/{id}").replace(/\/extensions\/[^/?]+/, "/extensions/{name}").replace(/\/profiles\/[^/?]+/, "/profiles/{name}")}`;
57
- const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
58
- let body;
59
- if (init.raw) {
60
- headers["Content-Type"] = init.raw.type;
61
- body = init.raw.body;
62
- }
63
- else if (init.body !== undefined) {
64
- headers["Content-Type"] = "application/json";
65
- body = JSON.stringify(init.body);
66
- }
67
- let response;
68
- try {
69
- const query = init.query?.toString();
70
- response = await (await http())(`${baseUrl}${route}${query ? `?${query}` : ""}`, { method, headers, ...(body !== undefined ? { body } : {}), ...(init.signal ? { signal: init.signal } : {}) });
71
- }
72
- catch (error) {
73
- if (error?.name === "AbortError")
74
- throw error;
75
- throw new KernelError(name, undefined, undefined, { cause: error });
76
- }
77
- // A success must be read whole: a body that breaks off or is not JSON is a failure, never an empty answer (an empty
78
- // session list would let a release finish without deleting).
79
- let text = "";
80
- try {
81
- text = await response.text();
82
- }
83
- catch (error) {
84
- if (error?.name === "AbortError")
85
- throw error;
86
- if (response.ok)
87
- throw new KernelError(name, response.status, "unreadable_body", { cause: error });
88
- }
89
- let json = null;
90
- try {
91
- json = text ? JSON.parse(text) : null;
92
- }
93
- catch {
94
- if (response.ok)
95
- throw new KernelError(name, response.status, "not_json");
96
- }
97
- if (!response.ok && response.status !== 404)
98
- throw new KernelError(name, response.status, typeof json?.code === "string" && CODE.test(json.code) ? json.code : undefined);
99
- return { status: response.status, json, headers: response.headers };
100
- }
101
- /** Null only when the whole list was read and none matches: a list cut short is a failure, since a missed copy means
102
- * a refused upload or a duplicate. */
103
- const storedWith = async (sha) => {
104
- for (let offset = 0, pages = 0; pages < 100; pages += 1) {
105
- const page = await call("GET", "/extensions", { query: new URLSearchParams({ limit: "100", offset: String(offset) }) });
106
- if (!Array.isArray(page.json))
107
- throw new KernelError("GET /extensions", page.status, "not_a_list");
108
- const found = page.json.find((e) => e?.checksum === sha);
109
- if (found)
110
- return nonEmpty(found.name) ? { name: nonEmpty(found.name) } : { id: nonEmpty(found.id) };
111
- if (page.headers.get("x-has-more") !== "true")
112
- return null;
113
- const next = Number(page.headers.get("x-next-offset"));
114
- if (!Number.isInteger(next) || next <= offset)
115
- throw new KernelError("GET /extensions", page.status, "no_next_offset");
116
- offset = next;
117
- }
118
- throw new Error("Kernel kept answering more pages of stored extensions");
119
- };
120
- /** A stored extension with the same bytes serves whatever its name (a plan may store only one, perhaps another
121
- * tool's); otherwise one upload per process and account, named by its SHA-256, and a failed one is forgotten. */
122
- const extension = () => options.extension ? options.extension() : uploadOnce(uploads, account, async () => {
123
- const zip = await readFile(extensionArchive());
124
- const sha = createHash("sha256").update(zip).digest("hex");
125
- const stored = await storedWith(sha);
126
- if (stored)
127
- return stored;
128
- const name = `agentrun-stagehand-${sha.slice(0, 16)}`;
129
- const boundary = `agentrun-${randomUUID()}`;
130
- const part = (headers) => Buffer.from(`--${boundary}\r\n${headers}\r\n\r\n`);
131
- const body = Buffer.concat([
132
- part(`Content-Disposition: form-data; name="name"`), Buffer.from(`${name}\r\n`),
133
- part(`Content-Disposition: form-data; name="file"; filename="stagehand-extension.zip"\r\nContent-Type: application/zip`), zip, Buffer.from(`\r\n--${boundary}--\r\n`),
134
- ]);
135
- try {
136
- const done = await call("POST", "/extensions", { raw: { body, type: `multipart/form-data; boundary=${boundary}` } });
137
- if (done.status === 404)
138
- throw new KernelError("POST /extensions", 404);
139
- }
140
- catch (error) {
141
- // Another process stored the same archive meanwhile: that copy serves.
142
- const raced = error.status === 409 ? await storedWith(sha) : null;
143
- if (raced)
144
- return raced;
145
- throw error;
146
- }
147
- return { name };
148
- });
149
- const lookup = async (id, signal) => call("GET", `/browsers/${encodeURIComponent(id)}`, { signal });
150
- const forget = (id) => { cdpUrls.delete(held(id)); liveUrls.delete(held(id)); };
151
- const status = async (ref, signal) => {
152
- const found = await lookup(ref.id, signal);
153
- const state = found.status === 404 ? "gone" : found.json?.deleted_at ? "stopped" : "running";
154
- if (state !== "running")
155
- forget(ref.id);
156
- return state;
157
- };
158
- const running = (ref) => async (signal) => { const now = await status(ref, signal); return now === "running" || now === "pending"; };
159
- /** A browser can only name a profile Kernel knows. Creating it first is safe to race: a 409 means another process just did. */
160
- const ensureProfile = async (name, signal) => {
161
- if ((await call("GET", `/profiles/${encodeURIComponent(name)}`, { signal })).status !== 404)
162
- return;
163
- try {
164
- await call("POST", "/profiles", { body: { name }, signal });
165
- }
166
- catch (error) {
167
- if (error.status !== 409)
168
- throw error;
169
- }
170
- };
171
- /** The saved profile each live session of this provider runs on, by tag: what a session vault may keep. */
172
- const profilesUsed = new Map();
173
- return {
174
- name: "kernel",
175
- caps: CAPS,
176
- vault: { kind: "context", provider: "kernel", contextIdsInClear: false, contextOf: (ref) => profilesUsed.get(ref.tag) ?? null },
177
- async create(spec, signal) {
178
- // The upload is shared by every create on the account: a cancelled caller stops waiting, the upload goes on for
179
- // the rest.
180
- signal?.throwIfAborted();
181
- if (spec.profile)
182
- profilesUsed.set(spec.tag, spec.profile.name);
183
- if (spec.profile?.save)
184
- await claimWriter(`${account}|profile:${spec.profile.name}`, spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
185
- let body;
186
- try {
187
- if (spec.profile)
188
- await ensureProfile(spec.profile.name, signal);
189
- body = kernelCreateBody(spec, { stealth: options.stealth, headless: options.headless, extension: await untilAborted(extension(), signal) });
190
- }
191
- catch (error) {
192
- freeWriter(spec.tag);
193
- throw error;
194
- }
195
- // At most once: a lost answer is found again by its tag (findByTag), never by a second create. A failed send keeps the
196
- // profile's claim until findByTag has looked: the browser may exist. A refusal (401, 403) made none, so it frees the claim.
197
- const created = await call("POST", "/browsers", { body, signal }).catch((error) => {
198
- if (isRefusal(error))
199
- freeWriter(spec.tag);
200
- throw error;
201
- });
202
- const id = nonEmpty(created.json?.session_id);
203
- const url = nonEmpty(created.json?.cdp_ws_url);
204
- if (created.status === 404 || !id || !url)
205
- throw new KernelError("POST /browsers", created.status, "no_session");
206
- cdpUrls.set(held(id), url);
207
- noteWriter(spec.tag, running({ id, tag: spec.tag }));
208
- const live = nonEmpty(created.json?.browser_live_view_url);
209
- if (live)
210
- liveUrls.set(held(id), live);
211
- return { id, tag: spec.tag };
212
- },
213
- async findByTag(tag, signal) {
214
- assertTag(tag);
215
- // The filter is Kernel's, the match is ours: a lane that ignores it must never hand back someone else's session.
216
- // Every page must answer: custody releases exactly these ids, so a failed page throws.
217
- const out = [];
218
- const seen = new Set();
219
- for (let offset = 0, pages = 0; pages < 100; pages += 1) {
220
- const query = new URLSearchParams({ status: "active", [`tags[agentrun_tag]`]: tag, limit: "100", offset: String(offset) });
221
- const page = await call("GET", "/browsers", { query, signal });
222
- // A list is never "not found": a 404 here is a wrong base URL, and an empty answer would orphan the tag's
223
- // sessions.
224
- if (page.status === 404)
225
- throw new KernelError("GET /browsers", 404);
226
- if (!Array.isArray(page.json))
227
- throw new KernelError("GET /browsers", page.status, "not_a_list");
228
- const rows = page.json;
229
- for (const row of rows) {
230
- const id = nonEmpty(row?.session_id);
231
- if (id && row?.tags?.agentrun_tag === tag && !row?.deleted_at && !seen.has(id)) {
232
- seen.add(id);
233
- out.push({ id, tag });
234
- }
235
- }
236
- // Kernel pages by headers: X-Has-More, and X-Next-Offset as the next page's absolute start.
237
- if (page.headers.get("x-has-more") !== "true") {
238
- if (!out.length)
239
- freeWriter(tag);
240
- for (const ref of out)
241
- if (isWriter(ref.tag))
242
- noteWriter(ref.tag, running(ref));
243
- return out;
244
- }
245
- // More pages with no usable next offset would truncate the set custody releases: a failure, never a partial
246
- // answer.
247
- const next = Number(page.headers.get("x-next-offset"));
248
- if (!Number.isInteger(next) || next <= offset)
249
- throw new Error("Kernel reported more sessions for the tag without the next page's offset");
250
- offset = next;
251
- }
252
- throw new Error("Kernel kept answering more pages of sessions for one tag");
253
- },
254
- status,
255
- async attach(ref, signal) {
256
- let url = cdpUrls.get(held(ref.id));
257
- if (!url) {
258
- const found = await lookup(ref.id, signal);
259
- url = found.status === 404 || found.json?.deleted_at ? "" : nonEmpty(found.json?.cdp_ws_url);
260
- if (!url)
261
- throw new Error("Kernel session is not available for connection");
262
- cdpUrls.set(held(ref.id), url);
263
- }
264
- return { sdkCdpUrl: url };
265
- },
266
- async liveView(ref) {
267
- try {
268
- let url = liveUrls.get(held(ref.id));
269
- if (!url) {
270
- const found = await lookup(ref.id);
271
- url = found.status === 404 || found.json?.deleted_at ? "" : nonEmpty(found.json?.browser_live_view_url);
272
- }
273
- return url ? { fullscreen: url, framed: null, pages: [] } : null;
274
- }
275
- catch {
276
- return null;
277
- }
278
- },
279
- async release(ref, signal) {
280
- profilesUsed.delete(ref.tag);
281
- await releaseAndConfirm({
282
- request: async () => ((await call("DELETE", `/browsers/${encodeURIComponent(ref.id)}`, { signal })).status === 404 ? "gone" : undefined),
283
- status: () => status(ref, signal),
284
- forget: () => { forget(ref.id); freeWriter(ref.tag); },
285
- confirm,
286
- sleep,
287
- stillRunning: `Kernel session ${ref.id} still running after its delete`,
288
- });
289
- },
290
- };
291
- }
File without changes
File without changes