@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.
- package/CHANGELOG.md +23 -0
- package/LICENSE +202 -0
- package/NOTICE +33 -0
- package/README.md +348 -2
- package/dist/coding-agent-local.d.ts +16 -0
- package/dist/coding-agent-local.js +138 -0
- package/dist/coding-agent.d.ts +79 -0
- package/dist/coding-agent.js +448 -0
- package/dist/core/contract.d.ts +26 -0
- package/dist/core/contract.js +154 -0
- package/dist/core/custody.d.ts +117 -0
- package/dist/core/custody.js +126 -0
- package/dist/core/decisions.d.ts +43 -0
- package/dist/core/decisions.js +4 -0
- package/dist/core/downloads.d.ts +35 -0
- package/dist/core/downloads.js +131 -0
- package/dist/core/effects.d.ts +63 -0
- package/dist/core/effects.js +256 -0
- package/dist/core/evidence.d.ts +43 -0
- package/dist/core/evidence.js +6 -0
- package/dist/core/failures.d.ts +36 -0
- package/dist/core/failures.js +68 -0
- package/dist/core/find.d.ts +32 -0
- package/dist/core/find.js +179 -0
- package/dist/core/guard.d.ts +6 -0
- package/dist/core/guard.js +25 -0
- package/dist/core/host.d.ts +328 -0
- package/dist/core/host.js +2 -0
- package/dist/core/images.d.ts +37 -0
- package/dist/core/images.js +60 -0
- package/dist/core/lease.d.ts +16 -0
- package/dist/core/lease.js +30 -0
- package/dist/core/receipts.d.ts +19 -0
- package/dist/core/receipts.js +22 -0
- package/dist/core/redact.d.ts +13 -0
- package/dist/core/redact.js +83 -0
- package/dist/core/session-control.d.ts +25 -0
- package/dist/core/session-control.js +75 -0
- package/dist/core/sites.d.ts +33 -0
- package/dist/core/sites.js +102 -0
- package/dist/core/tools.d.ts +72 -0
- package/dist/core/tools.js +200 -0
- package/dist/core/uri.d.ts +11 -0
- package/dist/core/uri.js +37 -0
- package/dist/core/usage.d.ts +19 -0
- package/dist/core/usage.js +44 -0
- package/dist/core/web.d.ts +98 -0
- package/dist/core/web.js +327 -0
- package/dist/driver/extension-worker.d.ts +6 -0
- package/dist/driver/extension-worker.js +121 -0
- package/dist/driver/stagehand.d.ts +25 -0
- package/dist/driver/stagehand.js +91 -0
- package/dist/durable-result.d.ts +6 -0
- package/dist/durable-result.js +2 -0
- package/dist/durable.d.ts +79 -0
- package/dist/durable.js +582 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +20 -0
- package/dist/providers/browserbase-net.d.ts +13 -0
- package/dist/providers/browserbase-net.js +96 -0
- package/dist/providers/browserbase.d.ts +152 -0
- package/dist/providers/browserbase.js +262 -0
- package/dist/providers/cdp-call.d.ts +6 -0
- package/dist/providers/cdp-call.js +25 -0
- package/dist/providers/cdp.d.ts +55 -0
- package/dist/providers/cdp.js +423 -0
- package/dist/providers/http.d.ts +2 -0
- package/dist/providers/http.js +21 -0
- package/dist/providers/kernel.d.ts +49 -0
- package/dist/providers/kernel.js +246 -0
- package/dist/providers/shared.d.ts +47 -0
- package/dist/providers/shared.js +82 -0
- package/dist/recorder/credential.d.ts +9 -0
- package/dist/recorder/credential.js +49 -0
- package/dist/recorder/follow.d.ts +26 -0
- package/dist/recorder/follow.js +138 -0
- package/dist/recorder/frames.d.ts +80 -0
- package/dist/recorder/frames.js +309 -0
- package/dist/recorder/index.d.ts +4 -0
- package/dist/recorder/index.js +7 -0
- package/dist/recorder/jpeg.d.ts +8 -0
- package/dist/recorder/jpeg.js +70 -0
- package/dist/recorder/track.d.ts +107 -0
- package/dist/recorder/track.js +259 -0
- package/dist/store.d.ts +56 -0
- package/dist/store.js +196 -0
- package/dist/testing/backend.d.ts +231 -0
- package/dist/testing/backend.js +414 -0
- package/dist/testing/driver.d.ts +28 -0
- package/dist/testing/driver.js +32 -0
- package/dist/testing/index.d.ts +4 -0
- package/dist/testing/index.js +4 -0
- package/dist/testing/pages.d.ts +3 -0
- package/dist/testing/pages.js +10 -0
- package/dist/testing/sentinels.d.ts +29 -0
- package/dist/testing/sentinels.js +38 -0
- package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
- package/dist/vendor/stagehand-facade/contract.js +155 -0
- package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
- package/dist/vendor/stagehand-facade/runtime.js +1640 -0
- package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
- package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
- package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
- package/dist/vendor/stagehand-facade/tools.js +139 -0
- package/dist/web.d.ts +41 -0
- package/dist/web.js +38 -0
- package/package.json +123 -4
- package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export * from "./core/contract.js";
|
|
2
|
+
export { BrowserFailureError, type AttachedSession, type BrowserDriver, type CustodyPort, type DriverFactory, type DriverOptions, type Overrides, type ToolOutput } from "./core/custody.js";
|
|
3
|
+
export * from "./core/decisions.js";
|
|
4
|
+
export * from "./core/downloads.js";
|
|
5
|
+
export * from "./core/effects.js";
|
|
6
|
+
export * from "./core/evidence.js";
|
|
7
|
+
export * from "./core/failures.js";
|
|
8
|
+
export * from "./core/find.js";
|
|
9
|
+
export * from "./core/guard.js";
|
|
10
|
+
export * from "./core/host.js";
|
|
11
|
+
export * from "./core/images.js";
|
|
12
|
+
export * from "./core/lease.js";
|
|
13
|
+
export * from "./core/receipts.js";
|
|
14
|
+
export * from "./core/redact.js";
|
|
15
|
+
export * from "./core/sites.js";
|
|
16
|
+
export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
|
|
17
|
+
export * from "./core/tools.js";
|
|
18
|
+
export * from "./core/usage.js";
|
|
19
|
+
export * from "./core/web.js";
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
// The host-neutral core: it imports no pi package and no host, only Node's builtins and the package's own dependencies.
|
|
2
|
+
export * from "./core/contract.js";
|
|
3
|
+
export { BrowserFailureError } from "./core/custody.js";
|
|
4
|
+
export * from "./core/decisions.js";
|
|
5
|
+
export * from "./core/downloads.js";
|
|
6
|
+
export * from "./core/effects.js";
|
|
7
|
+
export * from "./core/evidence.js";
|
|
8
|
+
export * from "./core/failures.js";
|
|
9
|
+
export * from "./core/find.js";
|
|
10
|
+
export * from "./core/guard.js";
|
|
11
|
+
export * from "./core/host.js";
|
|
12
|
+
export * from "./core/images.js";
|
|
13
|
+
export * from "./core/lease.js";
|
|
14
|
+
export * from "./core/receipts.js";
|
|
15
|
+
export * from "./core/redact.js";
|
|
16
|
+
export * from "./core/sites.js";
|
|
17
|
+
export { DEFAULT_BROWSER_POLICY } from "./core/session-control.js";
|
|
18
|
+
export * from "./core/tools.js";
|
|
19
|
+
export * from "./core/usage.js";
|
|
20
|
+
export * from "./core/web.js";
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export { directFetch, closeDirectFetch } from "./http.js";
|
|
2
|
+
/** Rewrite a Browserbase connect URL onto the credential proxy: only `*.browserbase.com` hosts, the signing query kept. */
|
|
3
|
+
export declare function rewriteConnectUrl(connectUrl: string, connectBaseUrl: string | undefined | null): string;
|
|
4
|
+
/** Direct, never through the HTTP(S) env proxy: it rejects CONNECT and the CDP WebSocket cannot ride it. Under `node
|
|
5
|
+
* --use-env-proxy` NO_PROXY is re-read per request, so listing these hosts bypasses it. */
|
|
6
|
+
export declare function browserbaseNoProxyHosts(env: NodeJS.ProcessEnv): string[];
|
|
7
|
+
export declare function applyBrowserbaseNoProxy(env?: NodeJS.ProcessEnv): string[];
|
|
8
|
+
/** A second provider binding the same URL to a different proxy is refused, never switched: the signed URL would go to
|
|
9
|
+
* it. */
|
|
10
|
+
export declare function bindConnectDial(connectUrl: string, connectBaseUrl: string | null): void;
|
|
11
|
+
export declare function unbindConnectDial(connectUrl: string): void;
|
|
12
|
+
export declare function connectDialUrl(url: string): string;
|
|
13
|
+
export declare function installWebSocketWrapper(): void;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { browserbaseHoldings } from "./shared.js";
|
|
2
|
+
export { directFetch, closeDirectFetch } from "./http.js";
|
|
3
|
+
/** Rewrite a Browserbase connect URL onto the credential proxy: only `*.browserbase.com` hosts, the signing query kept. */
|
|
4
|
+
export function rewriteConnectUrl(connectUrl, connectBaseUrl) {
|
|
5
|
+
if (!connectUrl || !connectBaseUrl)
|
|
6
|
+
return connectUrl;
|
|
7
|
+
try {
|
|
8
|
+
const target = new URL(connectBaseUrl);
|
|
9
|
+
const u = new URL(connectUrl);
|
|
10
|
+
if (!/(?:^|\.)browserbase\.com$/i.test(u.hostname))
|
|
11
|
+
return connectUrl;
|
|
12
|
+
u.protocol = target.protocol;
|
|
13
|
+
u.host = target.host;
|
|
14
|
+
u.pathname = target.pathname.replace(/\/$/, "") + u.pathname;
|
|
15
|
+
return u.toString();
|
|
16
|
+
}
|
|
17
|
+
catch {
|
|
18
|
+
return connectUrl;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
/** Direct, never through the HTTP(S) env proxy: it rejects CONNECT and the CDP WebSocket cannot ride it. Under `node
|
|
22
|
+
* --use-env-proxy` NO_PROXY is re-read per request, so listing these hosts bypasses it. */
|
|
23
|
+
export function browserbaseNoProxyHosts(env) {
|
|
24
|
+
const hosts = new Set();
|
|
25
|
+
for (const key of ["BROWSERBASE_BASE_URL", "BROWSERBASE_CONNECT_BASE_URL"]) {
|
|
26
|
+
const raw = String(env[key] || "").trim();
|
|
27
|
+
if (!raw)
|
|
28
|
+
continue;
|
|
29
|
+
try {
|
|
30
|
+
hosts.add(new URL(raw).hostname);
|
|
31
|
+
}
|
|
32
|
+
catch { }
|
|
33
|
+
}
|
|
34
|
+
if (!String(env.BROWSERBASE_CONNECT_BASE_URL || "").trim())
|
|
35
|
+
hosts.add(".browserbase.com");
|
|
36
|
+
return [...hosts];
|
|
37
|
+
}
|
|
38
|
+
export function applyBrowserbaseNoProxy(env = process.env) {
|
|
39
|
+
const hosts = browserbaseNoProxyHosts(env);
|
|
40
|
+
if (!hosts.length)
|
|
41
|
+
return hosts;
|
|
42
|
+
for (const target of env === process.env ? [env] : [env, process.env]) {
|
|
43
|
+
for (const key of ["NO_PROXY", "no_proxy"]) {
|
|
44
|
+
const merged = String(target[key] || "").split(",").map((h) => h.trim()).filter(Boolean);
|
|
45
|
+
for (const h of hosts)
|
|
46
|
+
if (!merged.includes(h))
|
|
47
|
+
merged.push(h);
|
|
48
|
+
target[key] = merged.join(",");
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return hosts;
|
|
52
|
+
}
|
|
53
|
+
/** The driver keeps the raw connect URL (the extension in the cloud browser dials it back and reaches only
|
|
54
|
+
* Browserbase); this process's socket dials the proxy, so the rewrite happens at dial time, never in a record. */
|
|
55
|
+
/** Per-socket targets, so two providers with different proxies never send one's signed URL to the other's proxy. */
|
|
56
|
+
const { boundDials } = browserbaseHoldings;
|
|
57
|
+
/** A second provider binding the same URL to a different proxy is refused, never switched: the signed URL would go to
|
|
58
|
+
* it. */
|
|
59
|
+
export function bindConnectDial(connectUrl, connectBaseUrl) {
|
|
60
|
+
const target = connectBaseUrl?.trim() ?? "";
|
|
61
|
+
const bound = boundDials.get(connectUrl);
|
|
62
|
+
if (bound !== undefined && bound !== target)
|
|
63
|
+
throw new Error("this Browserbase session is already attached through another credential proxy");
|
|
64
|
+
boundDials.set(connectUrl, target);
|
|
65
|
+
}
|
|
66
|
+
export function unbindConnectDial(connectUrl) {
|
|
67
|
+
boundDials.delete(connectUrl);
|
|
68
|
+
if (![...boundDials.values()].some(Boolean))
|
|
69
|
+
restoreWebSocket();
|
|
70
|
+
}
|
|
71
|
+
export function connectDialUrl(url) {
|
|
72
|
+
const bound = boundDials.get(url);
|
|
73
|
+
if (bound !== undefined)
|
|
74
|
+
return bound ? rewriteConnectUrl(url, bound) : url;
|
|
75
|
+
return url;
|
|
76
|
+
}
|
|
77
|
+
/** Wraps the process WebSocket only while a session is bound to a proxy; the native one returns with the last binding. A wrapper
|
|
78
|
+
* installed on top cannot be removed, so ours stays under it and, with no bindings, passes every URL through. */
|
|
79
|
+
let wrapped = null;
|
|
80
|
+
export function installWebSocketWrapper() {
|
|
81
|
+
if (typeof globalThis.WebSocket !== "function" || (wrapped && globalThis.WebSocket === wrapped.wrapper))
|
|
82
|
+
return;
|
|
83
|
+
const original = globalThis.WebSocket;
|
|
84
|
+
const wrapper = function (url, protocols) { return new original(connectDialUrl(String(url)), protocols); };
|
|
85
|
+
wrapper.prototype = original.prototype;
|
|
86
|
+
for (const k of ["CONNECTING", "OPEN", "CLOSING", "CLOSED"])
|
|
87
|
+
wrapper[k] = original[k];
|
|
88
|
+
globalThis.WebSocket = wrapper;
|
|
89
|
+
wrapped = { original, wrapper };
|
|
90
|
+
}
|
|
91
|
+
function restoreWebSocket() {
|
|
92
|
+
if (!wrapped || globalThis.WebSocket !== wrapped.wrapper)
|
|
93
|
+
return;
|
|
94
|
+
globalThis.WebSocket = wrapped.original;
|
|
95
|
+
wrapped = null;
|
|
96
|
+
}
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
import type { BrowserProvider, Geo, PriceTable, SessionSpec } from "../core/host.js";
|
|
2
|
+
import { type CdpSession } from "./cdp-call.js";
|
|
3
|
+
export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
|
|
4
|
+
export declare const SEARCH_QUERY_MAX = 200;
|
|
5
|
+
export declare const SEARCH_RESULTS_MAX = 25;
|
|
6
|
+
export type BrowserbaseSdk = {
|
|
7
|
+
sessions: {
|
|
8
|
+
create(body: BrowserbaseSessionBody, options?: RequestOptions): Promise<{
|
|
9
|
+
id: string;
|
|
10
|
+
connectUrl: string;
|
|
11
|
+
}>;
|
|
12
|
+
list(query: {
|
|
13
|
+
q?: string;
|
|
14
|
+
status?: string;
|
|
15
|
+
}, options?: RequestOptions): Promise<Array<{
|
|
16
|
+
id: string;
|
|
17
|
+
status?: string;
|
|
18
|
+
userMetadata?: Record<string, unknown>;
|
|
19
|
+
}>>;
|
|
20
|
+
retrieve(id: string, options?: RequestOptions): Promise<{
|
|
21
|
+
id: string;
|
|
22
|
+
status?: string;
|
|
23
|
+
connectUrl?: string;
|
|
24
|
+
}>;
|
|
25
|
+
update(id: string, body: {
|
|
26
|
+
status: "REQUEST_RELEASE";
|
|
27
|
+
}, options?: RequestOptions): Promise<unknown>;
|
|
28
|
+
debug(id: string, options?: RequestOptions): Promise<{
|
|
29
|
+
debuggerFullscreenUrl?: string;
|
|
30
|
+
debuggerUrl?: string;
|
|
31
|
+
pages?: Array<{
|
|
32
|
+
id?: string;
|
|
33
|
+
url?: string;
|
|
34
|
+
title?: string;
|
|
35
|
+
debuggerFullscreenUrl?: string;
|
|
36
|
+
}>;
|
|
37
|
+
}>;
|
|
38
|
+
recording?: {
|
|
39
|
+
downloads: {
|
|
40
|
+
create(id: string): Promise<{
|
|
41
|
+
downloads?: RecordingDownload[];
|
|
42
|
+
}>;
|
|
43
|
+
list(id: string): Promise<{
|
|
44
|
+
downloads?: RecordingDownload[];
|
|
45
|
+
}>;
|
|
46
|
+
};
|
|
47
|
+
};
|
|
48
|
+
};
|
|
49
|
+
extensions: {
|
|
50
|
+
create(body: {
|
|
51
|
+
file: unknown;
|
|
52
|
+
}, options?: RequestOptions): Promise<{
|
|
53
|
+
id: string;
|
|
54
|
+
}>;
|
|
55
|
+
};
|
|
56
|
+
fetchAPI: {
|
|
57
|
+
create(body: {
|
|
58
|
+
url: string;
|
|
59
|
+
allowRedirects?: boolean;
|
|
60
|
+
proxies?: boolean;
|
|
61
|
+
format?: string;
|
|
62
|
+
}, options?: RequestOptions): Promise<FetchApiResult>;
|
|
63
|
+
};
|
|
64
|
+
search: {
|
|
65
|
+
web(body: {
|
|
66
|
+
query: string;
|
|
67
|
+
numResults?: number;
|
|
68
|
+
}, options?: RequestOptions): Promise<SearchApiResult>;
|
|
69
|
+
};
|
|
70
|
+
get<T = unknown>(path: string, options?: RequestOptions & {
|
|
71
|
+
query?: Record<string, unknown>;
|
|
72
|
+
headers?: Record<string, string>;
|
|
73
|
+
__binaryResponse?: boolean;
|
|
74
|
+
}): Promise<T>;
|
|
75
|
+
};
|
|
76
|
+
type FetchApiResult = {
|
|
77
|
+
statusCode?: unknown;
|
|
78
|
+
contentType?: unknown;
|
|
79
|
+
content?: unknown;
|
|
80
|
+
} | null | undefined;
|
|
81
|
+
type SearchRow = {
|
|
82
|
+
url?: unknown;
|
|
83
|
+
title?: string | null;
|
|
84
|
+
author?: string | null;
|
|
85
|
+
publishedDate?: string | null;
|
|
86
|
+
published?: string | null;
|
|
87
|
+
};
|
|
88
|
+
type SearchApiResult = {
|
|
89
|
+
results?: SearchRow[];
|
|
90
|
+
} | null | undefined;
|
|
91
|
+
type BrowserbaseSessionBody = {
|
|
92
|
+
proxies: boolean | Array<Record<string, unknown>>;
|
|
93
|
+
timeout: number;
|
|
94
|
+
keepAlive: boolean;
|
|
95
|
+
browserSettings: {
|
|
96
|
+
solveCaptchas: boolean;
|
|
97
|
+
viewport: SessionSpec["viewport"];
|
|
98
|
+
verified?: boolean;
|
|
99
|
+
context?: {
|
|
100
|
+
id: string;
|
|
101
|
+
persist: boolean;
|
|
102
|
+
};
|
|
103
|
+
allowedDomains?: string[];
|
|
104
|
+
};
|
|
105
|
+
userMetadata: Record<string, string>;
|
|
106
|
+
region?: string;
|
|
107
|
+
extensionId?: string;
|
|
108
|
+
projectId?: string;
|
|
109
|
+
};
|
|
110
|
+
type RequestOptions = {
|
|
111
|
+
maxRetries?: number;
|
|
112
|
+
timeout?: number;
|
|
113
|
+
signal?: AbortSignal;
|
|
114
|
+
};
|
|
115
|
+
type RecordingDownload = {
|
|
116
|
+
pageId?: string;
|
|
117
|
+
status?: string;
|
|
118
|
+
downloadUrl?: string;
|
|
119
|
+
};
|
|
120
|
+
export type BrowserbaseOptions = {
|
|
121
|
+
/** Reads BROWSERBASE_API_KEY (or BB_API_KEY), _BASE_URL, _CONNECT_BASE_URL, _PROJECT_ID. Default: process.env. */
|
|
122
|
+
env?: NodeJS.ProcessEnv;
|
|
123
|
+
client?: BrowserbaseSdk;
|
|
124
|
+
/** The Stagehand extension's Browserbase id. Default: uploaded once per process. */
|
|
125
|
+
extensionId?: () => Promise<string>;
|
|
126
|
+
prices?: Partial<PriceTable>;
|
|
127
|
+
downloadBehavior?: (dialUrl: string) => Promise<DownloadSetting | void>;
|
|
128
|
+
confirm?: {
|
|
129
|
+
polls: number;
|
|
130
|
+
intervalMs: number;
|
|
131
|
+
};
|
|
132
|
+
sleep?: (ms: number) => Promise<void>;
|
|
133
|
+
};
|
|
134
|
+
/** `Browser.setDownloadBehavior` lasts only as long as the socket that sent it, so the socket stays open until
|
|
135
|
+
* `close()`. */
|
|
136
|
+
export type DownloadSetting = Pick<CdpSession, "close" | "open">;
|
|
137
|
+
/** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
|
|
138
|
+
export declare const setDownloadBehavior: (url: string, options?: {
|
|
139
|
+
downloadPath?: string;
|
|
140
|
+
timeoutMs?: number;
|
|
141
|
+
}) => Promise<DownloadSetting>;
|
|
142
|
+
export type BrowserbaseProvider = BrowserProvider & {
|
|
143
|
+
readonly name: "browserbase";
|
|
144
|
+
};
|
|
145
|
+
/** ISO alpha-2 country, US state abbreviation, upper-case city; no two-letter country, no geolocation. */
|
|
146
|
+
export declare function browserbaseGeolocation(raw: Partial<Geo> | null | undefined): Geo | null;
|
|
147
|
+
export declare function proxiesField(proxies: SessionSpec["proxies"]): boolean | Array<Record<string, unknown>>;
|
|
148
|
+
export declare function sessionCreateBody(spec: SessionSpec, extra?: {
|
|
149
|
+
extensionId?: string;
|
|
150
|
+
projectId?: string;
|
|
151
|
+
}): BrowserbaseSessionBody;
|
|
152
|
+
export declare function browserbaseProvider(options?: BrowserbaseOptions): BrowserbaseProvider;
|
|
@@ -0,0 +1,262 @@
|
|
|
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 { fetchUsage, resolvePrices, searchUsage } from "../core/usage.js";
|
|
5
|
+
import { cdpCall } from "./cdp-call.js";
|
|
6
|
+
import { applyBrowserbaseNoProxy, bindConnectDial, installWebSocketWrapper, rewriteConnectUrl, unbindConnectDial } from "./browserbase-net.js";
|
|
7
|
+
import { directFetch } from "./http.js";
|
|
8
|
+
import { accountKey, assertTag, browserbaseHoldings, defaultSleep, DEFAULT_CONFIRM, extensionArchive, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
|
|
9
|
+
export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
|
|
10
|
+
export const SEARCH_QUERY_MAX = 200;
|
|
11
|
+
export const SEARCH_RESULTS_MAX = 25;
|
|
12
|
+
/** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
|
|
13
|
+
export const setDownloadBehavior = (url, options = {}) => cdpCall(url, "Browser.setDownloadBehavior", { behavior: "allow", downloadPath: options.downloadPath ?? "downloads", eventsEnabled: true }, options.timeoutMs);
|
|
14
|
+
const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, extension: "uploaded-per-launch", settings: { proxies: true, verified: true, geolocation: true, region: true, context: true } };
|
|
15
|
+
const notFound = (e) => e?.status === 404;
|
|
16
|
+
/** ISO alpha-2 country, US state abbreviation, upper-case city; no two-letter country, no geolocation. */
|
|
17
|
+
export function browserbaseGeolocation(raw) {
|
|
18
|
+
const country = nonEmpty(raw?.country).toUpperCase();
|
|
19
|
+
if (!/^[A-Z]{2}$/.test(country))
|
|
20
|
+
return null;
|
|
21
|
+
const out = { country };
|
|
22
|
+
const state = nonEmpty(raw?.state).toUpperCase();
|
|
23
|
+
if (/^[A-Z]{2}$/.test(state))
|
|
24
|
+
out.state = state;
|
|
25
|
+
const city = nonEmpty(raw?.city).toUpperCase().replace(/[\s-]+/g, "_").replace(/[^A-Z_]/g, "");
|
|
26
|
+
if (city)
|
|
27
|
+
out.city = city;
|
|
28
|
+
return out;
|
|
29
|
+
}
|
|
30
|
+
export function proxiesField(proxies) {
|
|
31
|
+
if (!proxies)
|
|
32
|
+
return false;
|
|
33
|
+
const geo = typeof proxies === "object" ? browserbaseGeolocation(proxies.geolocation) : null;
|
|
34
|
+
return geo ? [{ type: "browserbase", geolocation: geo }] : true;
|
|
35
|
+
}
|
|
36
|
+
export function sessionCreateBody(spec, extra = {}) {
|
|
37
|
+
const settings = {
|
|
38
|
+
solveCaptchas: spec.captcha,
|
|
39
|
+
viewport: spec.viewport,
|
|
40
|
+
...(spec.verified ? { verified: true } : {}),
|
|
41
|
+
...(spec.contextId ? { context: { id: spec.contextId, persist: true } } : {}),
|
|
42
|
+
...(spec.navigation?.allow?.length ? { allowedDomains: spec.navigation.allow } : {}),
|
|
43
|
+
};
|
|
44
|
+
const userMetadata = Object.fromEntries(Object.entries(spec.metadata).map(([k, v]) => [k, tagValue(v)]));
|
|
45
|
+
return {
|
|
46
|
+
proxies: proxiesField(spec.proxies),
|
|
47
|
+
timeout: spec.maxLifetimeS,
|
|
48
|
+
// Without keepAlive Browserbase ends a session when any CDP client disconnects (a crash, a second client, a closed
|
|
49
|
+
// observer); with it only an explicit release or the timeout does.
|
|
50
|
+
keepAlive: true,
|
|
51
|
+
browserSettings: settings,
|
|
52
|
+
userMetadata: { ...userMetadata, agentrun_tag: spec.tag },
|
|
53
|
+
...(spec.region ? { region: spec.region } : {}),
|
|
54
|
+
...(extra.extensionId ? { extensionId: extra.extensionId } : {}),
|
|
55
|
+
...(extra.projectId ? { projectId: extra.projectId } : {}),
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
const { connectUrls, settings, opening, uploads } = browserbaseHoldings;
|
|
59
|
+
const endSetting = (id) => { settings.get(id)?.close(); settings.delete(id); };
|
|
60
|
+
const forget = (id) => { const url = connectUrls.get(id); if (url)
|
|
61
|
+
unbindConnectDial(url); connectUrls.delete(id); };
|
|
62
|
+
export function browserbaseProvider(options = {}) {
|
|
63
|
+
const env = options.env ?? process.env;
|
|
64
|
+
const apiKey = nonEmpty(env.BROWSERBASE_API_KEY) || nonEmpty(env.BB_API_KEY);
|
|
65
|
+
const baseUrl = nonEmpty(env.BROWSERBASE_BASE_URL) || undefined;
|
|
66
|
+
const connectBase = nonEmpty(env.BROWSERBASE_CONNECT_BASE_URL) || null;
|
|
67
|
+
const account = accountKey(baseUrl ?? "", apiKey);
|
|
68
|
+
const held = (id) => `${account}|${id}`;
|
|
69
|
+
const sleep = options.sleep ?? defaultSleep;
|
|
70
|
+
const confirm = options.confirm ?? DEFAULT_CONFIRM;
|
|
71
|
+
const prices = resolvePrices(options.prices);
|
|
72
|
+
let sdk = null;
|
|
73
|
+
const client = () => (sdk ??= options.client ? Promise.resolve(options.client) : (async () => {
|
|
74
|
+
applyBrowserbaseNoProxy(env);
|
|
75
|
+
const mod = await import(["@browserbasehq", "sdk"].join("/"));
|
|
76
|
+
const Browserbase = mod.default ?? mod.Browserbase;
|
|
77
|
+
const fetch = await directFetch();
|
|
78
|
+
return new Browserbase({ apiKey, baseURL: baseUrl, ...(fetch ? { fetch } : {}) });
|
|
79
|
+
})());
|
|
80
|
+
const extension = () => options.extensionId
|
|
81
|
+
? options.extensionId()
|
|
82
|
+
: uploadOnce(uploads, account, async () => (await (await client()).extensions.create({ file: createReadStream(extensionArchive()) }, { maxRetries: 0 })).id);
|
|
83
|
+
const rows = async (sessionId) => {
|
|
84
|
+
const all = [];
|
|
85
|
+
for (let offset = 0;;) {
|
|
86
|
+
const page = await (await client()).get("/v1/downloads", { query: { sessionId, limit: 100, offset } });
|
|
87
|
+
const got = Array.isArray(page?.downloads) ? page.downloads : [];
|
|
88
|
+
all.push(...got);
|
|
89
|
+
offset += got.length;
|
|
90
|
+
if (!got.length || offset >= Number(page?.total ?? 0))
|
|
91
|
+
return all;
|
|
92
|
+
}
|
|
93
|
+
};
|
|
94
|
+
const status = async (ref, signal) => {
|
|
95
|
+
try {
|
|
96
|
+
const found = await (await client()).sessions.retrieve(ref.id, { signal, timeout: 5_000 });
|
|
97
|
+
return found.status === "RUNNING" ? "running" : found.status === "PENDING" ? "pending" : "stopped";
|
|
98
|
+
}
|
|
99
|
+
catch (error) {
|
|
100
|
+
if (notFound(error))
|
|
101
|
+
return "gone";
|
|
102
|
+
throw error;
|
|
103
|
+
}
|
|
104
|
+
};
|
|
105
|
+
return {
|
|
106
|
+
name: "browserbase",
|
|
107
|
+
caps: CAPS,
|
|
108
|
+
async create(spec, signal) {
|
|
109
|
+
const projectId = nonEmpty(env.BROWSERBASE_PROJECT_ID);
|
|
110
|
+
// Behind the credential proxy the project is inferred from the injected key and must never be named; a direct key
|
|
111
|
+
// must name it.
|
|
112
|
+
const body = sessionCreateBody(spec, { extensionId: await extension(), ...(projectId && !baseUrl && !connectBase ? { projectId } : {}) });
|
|
113
|
+
// At most once: an SDK retry of a create the server already served would open a second paid browser.
|
|
114
|
+
const created = await (await client()).sessions.create(body, { maxRetries: 0, signal });
|
|
115
|
+
connectUrls.set(held(created.id), created.connectUrl);
|
|
116
|
+
return { id: created.id, tag: spec.tag };
|
|
117
|
+
},
|
|
118
|
+
async findByTag(tag, signal) {
|
|
119
|
+
assertTag(tag);
|
|
120
|
+
// `q` alone makes Browserbase answer 504 after 75 s; with a status it answers in about 150 ms. A create whose
|
|
121
|
+
// answer was lost may have left the session PENDING, which still bills once it runs, so both statuses are asked.
|
|
122
|
+
const q = `user_metadata['agentrun_tag']:'${tag}'`;
|
|
123
|
+
const asked = await Promise.all(["RUNNING", "PENDING"].map(async (status) => (await client()).sessions.list({ status, q }, { signal })));
|
|
124
|
+
// The query is the provider's, the match is ours: a lane that ignores `q` must never hand back someone else's
|
|
125
|
+
// session. Both queries must answer: custody releases exactly these ids, so a failed status throws.
|
|
126
|
+
const seen = new Set();
|
|
127
|
+
return asked.flat().filter((r) => r.userMetadata?.agentrun_tag === tag && !seen.has(r.id) && seen.add(r.id)).map((r) => ({ id: r.id, tag }));
|
|
128
|
+
},
|
|
129
|
+
status,
|
|
130
|
+
async attach(ref, signal) {
|
|
131
|
+
let url = connectUrls.get(held(ref.id));
|
|
132
|
+
if (!url) {
|
|
133
|
+
url = (await (await client()).sessions.retrieve(ref.id, { signal })).connectUrl;
|
|
134
|
+
if (!url)
|
|
135
|
+
throw new Error("Browserbase session is not available for connection");
|
|
136
|
+
connectUrls.set(held(ref.id), url);
|
|
137
|
+
}
|
|
138
|
+
// No `extensionId` on connect: the extension rides the create (given the upload id, connect waited 60 s for a
|
|
139
|
+
// worker that never came).
|
|
140
|
+
bindConnectDial(url, connectBase);
|
|
141
|
+
if (connectBase)
|
|
142
|
+
installWebSocketWrapper();
|
|
143
|
+
const dial = connectBase ? rewriteConnectUrl(url, connectBase) : url;
|
|
144
|
+
// Browserbase syncs a download only when the browser was told to save into `downloads`, which lasts as long as
|
|
145
|
+
// that socket: one socket per session is held until release. A failure costs the files, not the session.
|
|
146
|
+
const key = held(ref.id);
|
|
147
|
+
if (!settings.get(key)?.open) {
|
|
148
|
+
let pending = opening.get(key);
|
|
149
|
+
if (!pending) {
|
|
150
|
+
pending = (async () => { const setting = await (options.downloadBehavior ?? setDownloadBehavior)(dial).catch(() => undefined); if (setting)
|
|
151
|
+
settings.set(key, setting); })().finally(() => opening.delete(key));
|
|
152
|
+
opening.set(key, pending);
|
|
153
|
+
}
|
|
154
|
+
await pending;
|
|
155
|
+
}
|
|
156
|
+
return { sdkCdpUrl: url, ...(connectBase ? { dial: { url: dial } } : {}) };
|
|
157
|
+
},
|
|
158
|
+
async release(ref, signal) {
|
|
159
|
+
await opening.get(held(ref.id));
|
|
160
|
+
endSetting(held(ref.id));
|
|
161
|
+
await releaseAndConfirm({
|
|
162
|
+
request: async () => {
|
|
163
|
+
try {
|
|
164
|
+
await (await client()).sessions.update(ref.id, { status: "REQUEST_RELEASE" }, { maxRetries: 0, signal });
|
|
165
|
+
}
|
|
166
|
+
catch (error) {
|
|
167
|
+
if (notFound(error))
|
|
168
|
+
return "gone";
|
|
169
|
+
throw error;
|
|
170
|
+
}
|
|
171
|
+
},
|
|
172
|
+
status: () => status(ref, signal),
|
|
173
|
+
forget: () => forget(held(ref.id)),
|
|
174
|
+
confirm,
|
|
175
|
+
sleep,
|
|
176
|
+
stillRunning: `Browserbase session ${ref.id} still running after a release request`,
|
|
177
|
+
});
|
|
178
|
+
},
|
|
179
|
+
async liveView(ref) {
|
|
180
|
+
try {
|
|
181
|
+
const live = await (await client()).sessions.debug(ref.id);
|
|
182
|
+
return {
|
|
183
|
+
fullscreen: live.debuggerFullscreenUrl ?? null,
|
|
184
|
+
framed: live.debuggerUrl ?? null,
|
|
185
|
+
pages: (live.pages ?? []).map((p) => ({ id: p.id ?? null, url: p.url ?? null, title: p.title ?? null, fullscreen: p.debuggerFullscreenUrl ?? null })),
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
catch {
|
|
189
|
+
return null;
|
|
190
|
+
}
|
|
191
|
+
},
|
|
192
|
+
downloads: {
|
|
193
|
+
// Browserbase suffixes each name with a timestamp, so a name is unique in a session.
|
|
194
|
+
async list(ref) {
|
|
195
|
+
return (await rows(ref.id)).map((d) => ({ name: d.filename, sizeBytes: d.size, modifiedAt: d.createdAt ?? null }));
|
|
196
|
+
},
|
|
197
|
+
async read(ref, name, maxBytes) {
|
|
198
|
+
const row = (await rows(ref.id)).find((d) => d.filename === name);
|
|
199
|
+
if (!row)
|
|
200
|
+
throw new Error(`no download ${name} for session ${ref.id}`);
|
|
201
|
+
const response = await (await client()).get(`/v1/downloads/${encodeURIComponent(row.id)}`, { headers: { Accept: "application/octet-stream" }, __binaryResponse: true });
|
|
202
|
+
if (!response?.body)
|
|
203
|
+
throw new Error("the download came back empty");
|
|
204
|
+
return (async function* () {
|
|
205
|
+
let total = 0;
|
|
206
|
+
for await (const chunk of response.body) {
|
|
207
|
+
total += chunk.byteLength;
|
|
208
|
+
if (total > maxBytes)
|
|
209
|
+
throw new Error(`larger than the ${maxBytes}-byte limit`);
|
|
210
|
+
yield chunk;
|
|
211
|
+
}
|
|
212
|
+
})();
|
|
213
|
+
},
|
|
214
|
+
},
|
|
215
|
+
recordings: {
|
|
216
|
+
// One entry per rendered tab MP4 of an ended session; asking renders them, so a caller polls `list` until it
|
|
217
|
+
// fills.
|
|
218
|
+
async list(ref) {
|
|
219
|
+
const rec = (await client()).sessions.recording?.downloads;
|
|
220
|
+
if (!rec)
|
|
221
|
+
return [];
|
|
222
|
+
let downloads = (await rec.list(ref.id)).downloads ?? [];
|
|
223
|
+
if (!downloads.length || downloads.some((d) => d.status === "NOT_REQUESTED"))
|
|
224
|
+
downloads = (await rec.create(ref.id)).downloads ?? downloads;
|
|
225
|
+
return downloads.filter((d) => d.status === "COMPLETED" && d.downloadUrl).map((d) => ({ id: String(d.pageId), startedAt: null, durationS: null }));
|
|
226
|
+
},
|
|
227
|
+
async open(ref, id) {
|
|
228
|
+
const rec = (await client()).sessions.recording?.downloads;
|
|
229
|
+
const found = (await rec?.list(ref.id))?.downloads?.find((d) => String(d.pageId) === id && d.status === "COMPLETED" && d.downloadUrl);
|
|
230
|
+
if (!found?.downloadUrl)
|
|
231
|
+
throw new Error(`no rendered recording ${id} for session ${ref.id}`);
|
|
232
|
+
const response = await ((await directFetch()) ?? fetch)(found.downloadUrl);
|
|
233
|
+
if (!response.ok || !response.body)
|
|
234
|
+
throw new Error(`recording download answered ${response.status}`);
|
|
235
|
+
return response.body;
|
|
236
|
+
},
|
|
237
|
+
},
|
|
238
|
+
async fetch(request, signal) {
|
|
239
|
+
signal?.throwIfAborted();
|
|
240
|
+
const result = await untilAborted((async () => (await client()).fetchAPI.create({ url: request.url, proxies: request.proxies, allowRedirects: true, format: request.format }, { signal }))(), signal);
|
|
241
|
+
// The Fetch API reports no final URL.
|
|
242
|
+
return { finalUrl: null, statusCode: Number(result?.statusCode) || null, contentType: typeof result?.contentType === "string" ? result.contentType : null, content: contentText(result?.content), usage: fetchUsage(prices, request.proxies) };
|
|
243
|
+
},
|
|
244
|
+
async search(request, signal) {
|
|
245
|
+
signal?.throwIfAborted();
|
|
246
|
+
// The facade validates strictly (query 1 to 200 characters, 1 to 25 results): clamp, so a long query degrades and
|
|
247
|
+
// never throws.
|
|
248
|
+
const query = request.query.slice(0, SEARCH_QUERY_MAX);
|
|
249
|
+
const numResults = Math.max(1, Math.min(SEARCH_RESULTS_MAX, Math.floor(request.n) || 10));
|
|
250
|
+
const result = await untilAborted((async () => (await client()).search.web({ query, numResults }, { signal }))(), signal);
|
|
251
|
+
const rows = Array.isArray(result?.results) ? result.results : Array.isArray(result) ? result : [];
|
|
252
|
+
return { results: rows.filter((r) => typeof r?.url === "string").map((r) => ({ url: r.url, title: r.title ?? null, author: r.author ?? null, published: r.publishedDate ?? r.published ?? null })), usage: searchUsage(prices) };
|
|
253
|
+
},
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
function contentText(content) {
|
|
257
|
+
if (typeof content === "string")
|
|
258
|
+
return content;
|
|
259
|
+
if (Array.isArray(content))
|
|
260
|
+
return content.map((c) => (typeof c === "string" ? c : typeof c?.text === "string" ? c.text : JSON.stringify(c))).join("\n");
|
|
261
|
+
return content && typeof content === "object" ? JSON.stringify(content) : "";
|
|
262
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export function cdpCall(url, method, params = {}, timeoutMs = 5_000) {
|
|
2
|
+
return new Promise((resolve, reject) => {
|
|
3
|
+
const socket = new WebSocket(url);
|
|
4
|
+
let settled = false;
|
|
5
|
+
// One outcome only: closing a socket that never opened raises `error` again on some Node lines, which would loop.
|
|
6
|
+
const finish = (error, result) => {
|
|
7
|
+
if (settled)
|
|
8
|
+
return;
|
|
9
|
+
settled = true;
|
|
10
|
+
clearTimeout(timer);
|
|
11
|
+
socket.onerror = null;
|
|
12
|
+
if (error) {
|
|
13
|
+
socket.close();
|
|
14
|
+
reject(error);
|
|
15
|
+
}
|
|
16
|
+
else
|
|
17
|
+
resolve({ result, close: () => socket.close(), get open() { return socket.readyState === 1; } });
|
|
18
|
+
};
|
|
19
|
+
const timer = setTimeout(() => finish(new Error(`the browser did not answer ${method}`)), timeoutMs);
|
|
20
|
+
socket.onopen = () => socket.send(JSON.stringify({ id: 1, method, params }));
|
|
21
|
+
socket.onmessage = (event) => { const reply = JSON.parse(String(event.data)); if (reply.id === 1)
|
|
22
|
+
finish(reply.error ? new Error(String(reply.error.message ?? "refused")) : null, reply.result); };
|
|
23
|
+
socket.onerror = () => finish(new Error(`the CDP socket to ${new URL(url).host} failed`));
|
|
24
|
+
});
|
|
25
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import type { BrowserProvider } from "../core/host.js";
|
|
2
|
+
export type CdpOptions =
|
|
3
|
+
/** An existing browser: `http://host:port` or a `ws://` debugger URL. Release leaves it running. */
|
|
4
|
+
{
|
|
5
|
+
endpoint: string;
|
|
6
|
+
extensionId?: string;
|
|
7
|
+
}
|
|
8
|
+
/** Start Chrome under `profileRoot/<tag>` on a loopback port Chrome picks; release kills that process by exact pid. */
|
|
9
|
+
| {
|
|
10
|
+
chrome: {
|
|
11
|
+
executablePath: string;
|
|
12
|
+
profileRoot: string;
|
|
13
|
+
headless?: boolean;
|
|
14
|
+
args?: string[];
|
|
15
|
+
/** Chrome's own sandbox, on unless `false`; absent, `PI_BROWSER_NO_SANDBOX=1` turns it off. Turn it off only where
|
|
16
|
+
* Chrome cannot start its sandbox (root, a container, confined user namespaces), never because a run is in CI. */
|
|
17
|
+
sandbox?: boolean;
|
|
18
|
+
};
|
|
19
|
+
};
|
|
20
|
+
/** The browser is gone and directories it used are not: a profile left behind holds the session's cookies, so a release that cannot remove
|
|
21
|
+
* one says so, naming every one still there (`dirs`, the first as `dir`), and is asked again. `original` is the failure of the launch that
|
|
22
|
+
* was being undone, when there was one. */
|
|
23
|
+
export declare class ProfileNotRemovedError extends Error {
|
|
24
|
+
readonly dirs: readonly string[];
|
|
25
|
+
readonly cause: unknown;
|
|
26
|
+
readonly original?: unknown | undefined;
|
|
27
|
+
readonly code = "profile_not_removed";
|
|
28
|
+
readonly dir: string;
|
|
29
|
+
constructor(dirs: readonly string[], cause: unknown, original?: unknown | undefined);
|
|
30
|
+
}
|
|
31
|
+
/** The removal a provider uses; a test hands in its own to fail it in a controlled way. */
|
|
32
|
+
type RemoveDir = (dir: string, options: {
|
|
33
|
+
recursive: true;
|
|
34
|
+
force: true;
|
|
35
|
+
}) => Promise<void>;
|
|
36
|
+
/** A release that does not own the lease's browser left its profile: the port the profile names took the probe and did
|
|
37
|
+
* not answer, so a live browser may still run on it. Asked again once that port answers or closes, the release decides. */
|
|
38
|
+
export declare class ProfileOwnershipUnclearError extends Error {
|
|
39
|
+
readonly dir: string;
|
|
40
|
+
readonly port: number;
|
|
41
|
+
readonly code = "profile_ownership_unclear";
|
|
42
|
+
constructor(dir: string, port: number);
|
|
43
|
+
}
|
|
44
|
+
/** A pid reaches here from a ref's id, which a restart reads back from a record: `kill(-1)` signals every process the user can,
|
|
45
|
+
* `kill(0)` this process's own group, so neither a pid below 2 nor our own is ever signalled, and a negative pid (a whole group)
|
|
46
|
+
* only for a process that leads one. */
|
|
47
|
+
export declare function killTree(pid: number, io?: {
|
|
48
|
+
kill?: (pid: number, signal: "SIGKILL") => void;
|
|
49
|
+
leadsGroup?: (pid: number) => boolean | null;
|
|
50
|
+
}): Promise<void>;
|
|
51
|
+
/** `internals` is for tests: the removal a release uses. */
|
|
52
|
+
export declare function cdpProvider(options: CdpOptions, internals?: {
|
|
53
|
+
remove?: RemoveDir;
|
|
54
|
+
}): BrowserProvider;
|
|
55
|
+
export {};
|