@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,179 @@
1
+ export const FIND_CHUNK_CHARS = 2_000;
2
+ export const FIND_MAX_RANKED = 200;
3
+ export const FIND_SHOWN_CHUNKS = 8;
4
+ export const FIND_SHOWN_CHARS = 8_000;
5
+ const PATH_KEEP = 4;
6
+ const sameParent = (a, b) => a.length === b.length && a.every((part, i) => part === b[i]);
7
+ function pack(raws, max) {
8
+ const out = [];
9
+ for (const raw of raws) {
10
+ const last = out.at(-1);
11
+ if (last && last.to === raw.from && sameParent(last.path, raw.path) && last.size + raw.size + 1 <= max) {
12
+ last.to = raw.to;
13
+ last.size += raw.size + 1;
14
+ }
15
+ else
16
+ out.push({ ...raw });
17
+ }
18
+ return out;
19
+ }
20
+ /** At a line break in its second half when there is one, else at `room`; never inside a surrogate pair. */
21
+ function cutAt(text, room) {
22
+ let at = Math.min(room, text.length);
23
+ const newline = text.lastIndexOf("\n", at - 1);
24
+ if (at < text.length && newline > at / 2)
25
+ at = newline + 1;
26
+ if (/[\uDC00-\uDFFF]/.test(text[at] ?? ""))
27
+ at -= 1;
28
+ return at;
29
+ }
30
+ function pieces(text, max) {
31
+ const out = [];
32
+ for (let rest = text; rest;) {
33
+ const at = cutAt(rest, max);
34
+ out.push(rest.slice(0, at));
35
+ rest = rest.slice(at);
36
+ }
37
+ return out.length ? out : [""];
38
+ }
39
+ /** Snapshot lines (` [0-14] link: Go to page B`, two spaces a level) cut into subtrees of at most `max` characters. */
40
+ export function chunkTree(tree, max = FIND_CHUNK_CHARS) {
41
+ const entries = [];
42
+ for (const line of tree.split("\n")) {
43
+ const node = /^( *)\[([^\]\s]+)\]/.exec(line);
44
+ if (!node && entries.length)
45
+ entries[entries.length - 1].text += `\n${line}`;
46
+ else
47
+ entries.push({ depth: node ? Math.floor(node[1].length / 2) : 0, id: node?.[2] ?? null, text: line });
48
+ }
49
+ const n = entries.length;
50
+ const end = new Array(n);
51
+ for (let i = n - 1; i >= 0; i -= 1) {
52
+ let j = i + 1;
53
+ while (j < n && entries[j].depth > entries[i].depth)
54
+ j = end[j];
55
+ end[i] = j;
56
+ }
57
+ const upTo = [0];
58
+ for (const e of entries)
59
+ upTo.push(upTo.at(-1) + e.text.length + 1);
60
+ const raws = [];
61
+ const visit = (i, path) => {
62
+ const size = upTo[end[i]] - upTo[i];
63
+ if (size <= max || end[i] === i + 1) {
64
+ raws.push({ from: i, to: end[i], path, size });
65
+ return;
66
+ }
67
+ const here = [...path, entries[i].text.split("\n")[0].trim()].slice(-PATH_KEEP);
68
+ for (let j = i + 1; j < end[i]; j = end[j])
69
+ visit(j, here);
70
+ };
71
+ for (let i = 0; i < n; i = end[i])
72
+ visit(i, []);
73
+ // An oversize leaf is split into pieces that each carry the node's ID, so none of its text is out of the ranker's
74
+ // sight.
75
+ return pack(raws, max).flatMap(({ from, to, path }) => {
76
+ const slice = entries.slice(from, to);
77
+ const ids = slice.flatMap((e) => (e.id ? [e.id] : []));
78
+ const head = slice[0].text.split("\n")[0].trim().slice(0, 80);
79
+ return pieces(slice.map((e) => e.text).join("\n"), max).map((text, i) => ({ text, path: i && slice.length === 1 && ids.length ? [...path, head] : path, ids }));
80
+ }).map((chunk, index) => ({ ...chunk, index }));
81
+ }
82
+ /** Sections under the headings (a `#` inside a code fence is not one); an oversize section is cut further. */
83
+ export function chunkPage(markdown, max = FIND_CHUNK_CHARS) {
84
+ const sections = [{ path: [], lines: [] }];
85
+ const stack = [];
86
+ let fence = null;
87
+ for (const line of markdown.split("\n")) {
88
+ const mark = /^\s*(```|~~~)/.exec(line)?.[1];
89
+ if (mark)
90
+ fence = fence === null ? mark : fence === mark ? null : fence;
91
+ const heading = fence === null && !mark ? /^(#{1,6})\s+(\S.*?)\s*#*\s*$/.exec(line) : null;
92
+ if (heading) {
93
+ while (stack.length && stack.at(-1).level >= heading[1].length)
94
+ stack.pop();
95
+ sections.push({ path: stack.map((h) => h.title).slice(-PATH_KEEP), lines: [line] });
96
+ stack.push({ level: heading[1].length, title: heading[2] });
97
+ }
98
+ else
99
+ sections[sections.length - 1].lines.push(line);
100
+ }
101
+ // Parts keep the page's own characters, blank lines and section breaks included: joined, they are the page.
102
+ const parts = [];
103
+ let first = true;
104
+ for (const { path, lines } of sections) {
105
+ if (!lines.length)
106
+ continue;
107
+ let lead = first ? "" : "\n";
108
+ first = false;
109
+ let current = "";
110
+ const flush = () => { parts.push({ text: current, path, lead }); lead = ""; current = ""; };
111
+ const units = lines.join("\n").split(/(\n\s*\n)/).reduce((acc, token, i) => { if (i % 2)
112
+ acc[acc.length - 1] += token;
113
+ else
114
+ acc.push(token); return acc; }, []);
115
+ for (const unit of units) {
116
+ for (let rest = unit; rest;) {
117
+ const room = max - current.length;
118
+ if (rest.length <= room) {
119
+ current += rest;
120
+ break;
121
+ }
122
+ if (current && (rest.length <= max || room < max / 4)) {
123
+ flush();
124
+ continue;
125
+ }
126
+ const at = cutAt(rest, room);
127
+ current += rest.slice(0, at);
128
+ rest = rest.slice(at);
129
+ flush();
130
+ }
131
+ }
132
+ if (current || !parts.some((part) => part.path === path))
133
+ flush();
134
+ }
135
+ const raws = pack(parts.map((part, i) => ({ from: i, to: i + 1, path: part.path, size: part.text.length })), max);
136
+ return raws.map(({ from, to, path }, index) => ({ index, text: parts.slice(from, to).reduce((acc, part, i) => acc + (i ? part.lead : "") + part.text, ""), path, ids: [] }));
137
+ }
138
+ const quote = (query) => JSON.stringify(query.length > 120 ? `${query.slice(0, 120)}…` : query);
139
+ /** Without a usable ranker the whole source comes back with a line saying find was not applied: never a silent cut. */
140
+ export async function findInText(source, query, options) {
141
+ const whole = (why) => ({ text: `find ${quote(query)} was not applied: ${why}. The whole ${options.kind === "tree" ? "snapshot" : "page"} follows.\n${source}`, applied: false, chunks: 0, shown: [], ids: [] });
142
+ if (!options.rank)
143
+ return whole("this host has no ranker");
144
+ let max = options.maxChars ?? FIND_CHUNK_CHARS;
145
+ let chunks = (options.kind === "tree" ? chunkTree : chunkPage)(source, max);
146
+ while (chunks.length > FIND_MAX_RANKED && max < 64_000) {
147
+ max *= 2;
148
+ chunks = (options.kind === "tree" ? chunkTree : chunkPage)(source, max);
149
+ }
150
+ if (!chunks.some((chunk) => chunk.text.trim()))
151
+ return whole("there is nothing to search");
152
+ const inputs = chunks.map((chunk) => (chunk.path.length ? `${chunk.path.join(" > ")}\n${chunk.text}` : chunk.text));
153
+ const batches = Array.from({ length: Math.ceil(inputs.length / FIND_MAX_RANKED) }, (_, i) => inputs.slice(i * FIND_MAX_RANKED, (i + 1) * FIND_MAX_RANKED));
154
+ let answers = [];
155
+ try {
156
+ answers = await Promise.all(batches.map((batch) => options.rank(query, batch)));
157
+ }
158
+ catch { }
159
+ if (answers.length !== batches.length || answers.some((answer) => !answer))
160
+ return whole("the ranker gave no answer");
161
+ if (answers.some((answer, i) => answer.length !== batches[i].length || answer.some((score) => !Number.isFinite(score))))
162
+ return whole("the ranker's answer did not match the chunks");
163
+ const scores = answers.flat();
164
+ const best = chunks.map((chunk) => chunk.index).sort((a, b) => scores[b] - scores[a] || a - b);
165
+ const kept = [];
166
+ let chars = 0;
167
+ for (const index of best) {
168
+ if (kept.length >= (options.shownChunks ?? FIND_SHOWN_CHUNKS) || (kept.length && chars + chunks[index].text.length > (options.shownChars ?? FIND_SHOWN_CHARS)))
169
+ break;
170
+ kept.push(index);
171
+ chars += chunks[index].text.length;
172
+ }
173
+ kept.sort((a, b) => a - b);
174
+ const left = chunks.length - kept.length;
175
+ const rest = left === 0 ? "" : options.filedAt ? `; the whole ${options.kind === "tree" ? "snapshot" : "page"} is filed at ${options.filedAt}` : `; take ${options.kind === "tree" ? "a snapshot without find" : "browser_read without find"} for everything`;
176
+ const head = `find ${quote(query)}: ${kept.length} of ${chunks.length} chunks shown, ${left} left out${rest}. Ask a narrower find if the answer is not here.`;
177
+ const body = kept.map((index) => `${chunks[index].path.length ? `--- under: ${chunks[index].path.join(" > ")}` : "---"}\n${chunks[index].text}`).join("\n");
178
+ return { text: `${head}\n${body}`, applied: true, chunks: chunks.length, shown: kept, ids: kept.flatMap((index) => chunks[index].ids) };
179
+ }
@@ -0,0 +1,6 @@
1
+ import { type BrowserFailure } from "./failures.js";
2
+ export type RepeatGuard = {
3
+ check(tool: string, args: unknown): BrowserFailure | null;
4
+ note(tool: string, args: unknown, failure: BrowserFailure | null): void;
5
+ };
6
+ export declare function createRepeatGuard(): RepeatGuard;
@@ -0,0 +1,25 @@
1
+ import { browserFailure } from "./failures.js";
2
+ export function createRepeatGuard() {
3
+ const strikes = new Map();
4
+ const keyOf = (tool, args) => `${tool}:${JSON.stringify(args ?? {})}`;
5
+ return {
6
+ check(tool, args) {
7
+ const prior = strikes.get(keyOf(tool, args));
8
+ if (!prior || prior.count < 2)
9
+ return null;
10
+ return browserFailure("refused", `Refused: ${tool} with these exact arguments already failed ${prior.count} times with the same error ("${prior.error.slice(0, 200)}"). Change approach: snapshot again and use current IDs, change the code or the URL, browser_relaunch({verified:true}) if the site blocks you, or fall back to web_fetch.`);
11
+ },
12
+ note(tool, args, failure) {
13
+ if (failure?.code === "aborted")
14
+ return;
15
+ const key = keyOf(tool, args);
16
+ if (!failure) {
17
+ strikes.delete(key);
18
+ return;
19
+ }
20
+ const error = `${failure.code}:${(failure.detail || failure.message).slice(0, 300)}`;
21
+ const prior = strikes.get(key);
22
+ strikes.set(key, prior && prior.error === error ? { error, count: prior.count + 1 } : { error, count: 1 });
23
+ },
24
+ };
25
+ }
@@ -0,0 +1,328 @@
1
+ import type { LeaseRef, LeaseState, ResourceStatus } from "./lease.js";
2
+ export type PriceState = "priced" | "unpriced" | "invalid";
3
+ export type PiUsage = {
4
+ input: 0;
5
+ output: 0;
6
+ cacheRead: 0;
7
+ cacheWrite: 0;
8
+ totalTokens: 0;
9
+ cost: {
10
+ input: 0;
11
+ output: 0;
12
+ cacheRead: 0;
13
+ cacheWrite: 0;
14
+ total: number;
15
+ };
16
+ };
17
+ export type ToolUsage = {
18
+ usage: PiUsage;
19
+ state: PriceState;
20
+ };
21
+ export type Geo = {
22
+ country: string;
23
+ state?: string;
24
+ city?: string;
25
+ };
26
+ export type BrowserConfig = {
27
+ /** The host's name for the conversation's work; names evidence directories. */
28
+ label: string;
29
+ run: string;
30
+ policy: BrowserPolicy;
31
+ };
32
+ export type BrowserPolicy = {
33
+ proxies: boolean;
34
+ verified: boolean;
35
+ captcha: boolean;
36
+ geolocation: Geo | null;
37
+ region: string | null;
38
+ contextId: string | null;
39
+ sessionTimeoutS: number;
40
+ idleReleaseS: number;
41
+ batchTimeoutMs: number;
42
+ navigation?: {
43
+ allow?: string[];
44
+ block?: string[];
45
+ };
46
+ /** A request judged irreversible (or not judged) is sent, refused or put to the host. Absent: no observer. */
47
+ actions?: "allow" | "deny" | "ask";
48
+ };
49
+ export type SessionSpec = {
50
+ tag: string;
51
+ maxLifetimeS: number;
52
+ idleTimeoutS: number;
53
+ proxies: boolean | {
54
+ geolocation: Geo;
55
+ };
56
+ verified: boolean;
57
+ captcha: boolean;
58
+ region?: string;
59
+ viewport: {
60
+ width: number;
61
+ height: number;
62
+ };
63
+ contextId?: string;
64
+ navigation?: {
65
+ allow?: string[];
66
+ block?: string[];
67
+ };
68
+ metadata: Record<string, string>;
69
+ };
70
+ /** The driver may be handed one URL while the process dials another (a credential proxy, a broker relay). Held in
71
+ * memory only. */
72
+ export type AttachTarget = {
73
+ sdkCdpUrl: string;
74
+ dial?: {
75
+ url: string;
76
+ headers?: Record<string, string>;
77
+ };
78
+ extensionId?: string;
79
+ };
80
+ export type ProviderCaps = {
81
+ timeoutModel: "wall-clock" | "inactivity";
82
+ maxLifetimeS: number;
83
+ survivesDisconnect: boolean;
84
+ releaseIsAsync: boolean;
85
+ extension: "uploaded-per-launch" | "preinstalled" | "loaded-locally";
86
+ /** The session settings this provider applies; a setting left out is applied. */
87
+ settings?: Partial<SessionSettingsSupport>;
88
+ };
89
+ export type SessionSettingsSupport = {
90
+ proxies: boolean;
91
+ verified: boolean;
92
+ geolocation: boolean;
93
+ region: boolean;
94
+ context: boolean;
95
+ };
96
+ export type LiveView = {
97
+ fullscreen: string | null;
98
+ framed: string | null;
99
+ pages: Array<{
100
+ id: string | null;
101
+ url: string | null;
102
+ title: string | null;
103
+ fullscreen: string | null;
104
+ }>;
105
+ };
106
+ export type Recording = {
107
+ id: string;
108
+ startedAt: string | null;
109
+ durationS: number | null;
110
+ };
111
+ export type RemoteFile = {
112
+ name: string;
113
+ sizeBytes: number;
114
+ modifiedAt: string | null;
115
+ };
116
+ export type FetchRequest = {
117
+ url: string;
118
+ format: "markdown" | "raw";
119
+ proxies: boolean;
120
+ };
121
+ export type FetchResult = {
122
+ finalUrl: string | null;
123
+ statusCode: number | null;
124
+ contentType: string | null;
125
+ content: string;
126
+ usage?: ToolUsage;
127
+ };
128
+ export type SearchRequest = {
129
+ query: string;
130
+ n: number;
131
+ };
132
+ export type SearchResult = {
133
+ results: Array<{
134
+ url: string;
135
+ title: string | null;
136
+ author?: string | null;
137
+ published?: string | null;
138
+ }>;
139
+ usage?: ToolUsage;
140
+ };
141
+ export interface BrowserProvider {
142
+ readonly name: string;
143
+ readonly caps: ProviderCaps;
144
+ /** At most once: SDK retries off, and `spec.tag` stamped provider-side so `findByTag` finds a session whose create
145
+ * answer was lost. */
146
+ create(spec: SessionSpec, signal: AbortSignal): Promise<LeaseRef>;
147
+ findByTag(tag: string, signal?: AbortSignal): Promise<LeaseRef[]>;
148
+ status(ref: LeaseRef, signal?: AbortSignal): Promise<ResourceStatus>;
149
+ /** Held in memory, never committed. */
150
+ attach(ref: LeaseRef, signal?: AbortSignal): Promise<AttachTarget>;
151
+ /** Idempotent; a session already gone counts as released. */
152
+ release(ref: LeaseRef, signal?: AbortSignal): Promise<void>;
153
+ /** The host channel only (`onSession`); never in a result, a document or a log. */
154
+ liveView?(ref: LeaseRef): Promise<LiveView | null>;
155
+ recordings?: {
156
+ list(ref: LeaseRef): Promise<Recording[]>;
157
+ open(ref: LeaseRef, id: string): Promise<ReadableStream<Uint8Array>>;
158
+ };
159
+ downloads?: {
160
+ list(ref: LeaseRef): Promise<RemoteFile[]>;
161
+ read(ref: LeaseRef, name: string, maxBytes: number): Promise<AsyncIterable<Uint8Array>>;
162
+ };
163
+ fetch?(request: FetchRequest, signal?: AbortSignal): Promise<FetchResult>;
164
+ search?(request: SearchRequest, signal?: AbortSignal): Promise<SearchResult>;
165
+ }
166
+ /** A site use_website can open: configuration, never model input. */
167
+ export type SiteInfo = {
168
+ site: string;
169
+ title: string;
170
+ description: string;
171
+ };
172
+ /** Runs one child agent that has the browser tools and no use_website, and answers its final text. The adapter supplies
173
+ * it: a pi session for the coding agent, a task-owned conversation for pi-durable. */
174
+ export type ChildRunner = (task: {
175
+ site: string;
176
+ requestId: string;
177
+ prompt: string;
178
+ }, signal: AbortSignal) => Promise<string>;
179
+ /** Runs a granted site's task and reports it, idempotent by `requestId`: exactly one of `run` (a task started elsewhere)
180
+ * or `report` (the result). A port that runs the child itself uses `ctx.runChild`; a broker ignores it. */
181
+ export interface SiteRunPort {
182
+ list(signal: AbortSignal): Promise<SiteInfo[]>;
183
+ use(input: {
184
+ site: string;
185
+ requestId: string;
186
+ instructions: string;
187
+ }, ctx: {
188
+ signal: AbortSignal;
189
+ runChild: ChildRunner;
190
+ }): Promise<{
191
+ run: {
192
+ id: string;
193
+ state: string;
194
+ };
195
+ } | {
196
+ report: string;
197
+ }>;
198
+ }
199
+ export type ReleaseReason = "tool" | "idle" | "relaunch" | "close" | "ended" | "lost" | "create_failed";
200
+ export type SessionRecord = {
201
+ tag: string;
202
+ state: LeaseState;
203
+ resourceId: string | null;
204
+ createdAt: string;
205
+ endedAt: string | null;
206
+ releaseReason: ReleaseReason | null;
207
+ plane: string;
208
+ provider: string;
209
+ settings: {
210
+ proxies: boolean;
211
+ verified: boolean;
212
+ geolocation: Geo | null;
213
+ region: string | null;
214
+ contextId: string | null;
215
+ };
216
+ /** Every page the session moved to, in order; the last 500 kept. */
217
+ navigation: Array<{
218
+ at: string;
219
+ url: string;
220
+ }>;
221
+ lastUrl: string | null;
222
+ pendingEffect: PendingEffect | null;
223
+ spent: {
224
+ seconds: number;
225
+ usd: number;
226
+ chargedThrough: string; /** Set by the release's charge: nothing is charged after it. */
227
+ final?: true;
228
+ /** An unpriced or invalid price records seconds and no dollars, shown as unknown, never $0. */
229
+ state?: PriceState;
230
+ /** The sub-picodollar remainder carried to the next charge, so one rate's total is exact however many calls charged
231
+ * it. */
232
+ carry?: number;
233
+ };
234
+ };
235
+ /** A request a `run` sent that can change something: method, origin, path, the hold's decision. Never a body, a header
236
+ * or a query value. */
237
+ export type SentEffect = {
238
+ requestId: string;
239
+ method: string;
240
+ origin: string;
241
+ path: string;
242
+ at: string;
243
+ held: "pending" | "allowed" | "denied" | null;
244
+ irreversible: number | null;
245
+ };
246
+ /** A replay-unsafe page action's journal entry. `observed`: a holding observer committed each request before it left the
247
+ * browser; `watched`: an observer recorded the requests it sent, holding them or not. `incarnation`: the custody process that wrote it; an entry from an earlier one belongs to a resumed run.
248
+ * `after`: the conversation's newest entry when it was journaled, where a resumed run's look for its answer starts.
249
+ * `finished`: the action returned. `told` and `refused`: how far a cut has been answered. */
250
+ export type PendingEffect = {
251
+ callId: string;
252
+ codeSha: string;
253
+ url: string | null;
254
+ at: string;
255
+ observed?: boolean;
256
+ sent?: SentEffect[];
257
+ watched?: boolean;
258
+ incarnation?: string;
259
+ after?: number;
260
+ finished?: boolean;
261
+ told?: boolean;
262
+ refused?: boolean;
263
+ };
264
+ /** A cut action's facts, beside the notice in the call's `details.pendingEffect`. `sent` is null when no observer ran, so
265
+ * an unknown never reads as none. */
266
+ export type PendingEffectFacts = {
267
+ callId: string;
268
+ urlAtDispatch: string | null;
269
+ urlNow: string;
270
+ observed: boolean;
271
+ sent: Array<{
272
+ method: string;
273
+ url: string;
274
+ held: SentEffect["held"];
275
+ }> | null;
276
+ };
277
+ export type SessionsState = {
278
+ /** Index into `sessions` of each plane's current session. */
279
+ current: Record<string, number | null>;
280
+ sessions: SessionRecord[];
281
+ /** Told to the model on its next browser call, then cleared. */
282
+ notice: string | null;
283
+ };
284
+ export type InventoryRow = {
285
+ tag: string;
286
+ conversationId: number;
287
+ plane: string;
288
+ provider: string;
289
+ resourceId: string | null;
290
+ state: SessionRecord["state"];
291
+ };
292
+ export type SessionRow = {
293
+ conversationId: number;
294
+ label: string;
295
+ session: SessionRecord;
296
+ liveView: LiveView | null;
297
+ };
298
+ export type SessionChange = "launched" | "updated" | "released";
299
+ /** A code, never text: an attach error's message can hold the endpoint it dialed, whose URL carries a token.
300
+ * attach_refused: never opened; cdp_closed: closed in setup; cdp_error: a setup command failed. */
301
+ export type ObserverFailure = "attach_refused" | "cdp_closed" | "cdp_error" | "attach_failed";
302
+ /** Sent once per attach when the observer cannot attach under `allow` (`deny` and `ask` fail the call instead). Scalars
303
+ * only, no free text. */
304
+ export type ObserverRow = {
305
+ conversationId: number;
306
+ label: string;
307
+ tag: string;
308
+ session_id: string;
309
+ policy: "allow";
310
+ code: ObserverFailure;
311
+ };
312
+ /** released: conversation done; kept: same session; lost: ended or never created; unreachable: left as is. */
313
+ export type ReconcileReport = {
314
+ released: string[];
315
+ kept: string[];
316
+ lost: string[];
317
+ unreachable: string[];
318
+ };
319
+ /** A null price records the quantity unpriced. */
320
+ export type PriceTable = {
321
+ sessionUsdPerHour: number | null;
322
+ sessionMinimumS: number;
323
+ fetchUsd: number;
324
+ fetchProxiedUsd: number;
325
+ searchUsd: number;
326
+ };
327
+ /** Browserbase list prices as of 2026-10-06: the Developer overage rate, one-minute minimum. */
328
+ export declare const LIST_PRICES: PriceTable;
@@ -0,0 +1,2 @@
1
+ /** Browserbase list prices as of 2026-10-06: the Developer overage rate, one-minute minimum. */
2
+ export const LIST_PRICES = Object.freeze({ sessionUsdPerHour: 0.12, sessionMinimumS: 60, fetchUsd: 0.001, fetchProxiedUsd: 0.004, searchUsd: 0.007 });
@@ -0,0 +1,37 @@
1
+ export declare const SCREENSHOT_MAX_EDGE_PX = 2000;
2
+ export declare const SCREENSHOT_MAX_BASE64_BYTES = 900000;
3
+ export type ImageSize = {
4
+ type: "png" | "jpeg";
5
+ width: number;
6
+ height: number;
7
+ };
8
+ export declare function imageSize(bytes: Uint8Array): ImageSize | null;
9
+ /** `scale: "css"` takes one image pixel per CSS pixel, so a high-density display does not double the size. */
10
+ export type ScreenshotOptions = {
11
+ fullPage?: boolean;
12
+ type?: "png" | "jpeg";
13
+ quality?: number;
14
+ scale?: "css" | "device";
15
+ };
16
+ export type Capture = (options: ScreenshotOptions) => Promise<{
17
+ data: string;
18
+ mimeType: string;
19
+ }>;
20
+ export type BudgetedScreenshot = {
21
+ data: string;
22
+ mimeType: string;
23
+ size: ImageSize;
24
+ options: ScreenshotOptions;
25
+ adjusted: {
26
+ why: "long_edge" | "base64_bytes";
27
+ first: ImageSize | null;
28
+ } | null;
29
+ };
30
+ export declare class ScreenshotBudgetError extends Error {
31
+ name: string;
32
+ }
33
+ /** Over budget, retakes as a viewport JPEG at CSS scale, quality 40, 25, 10; throws ScreenshotBudgetError. */
34
+ export declare function captureWithinBudget(capture: Capture, requested: ScreenshotOptions, budget?: {
35
+ maxEdgePx: number;
36
+ maxBase64Bytes: number;
37
+ }): Promise<BudgetedScreenshot>;
@@ -0,0 +1,60 @@
1
+ // Tool images are stored verbatim and resent on every later request, and routes reject oversize ones: a capture is held
2
+ // to a long edge and a base64 size.
3
+ export const SCREENSHOT_MAX_EDGE_PX = 2_000;
4
+ export const SCREENSHOT_MAX_BASE64_BYTES = 900_000;
5
+ const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
6
+ /** JPEG start-of-frame markers; C4 (DHT), C8 (JPG) and CC (DAC) are not frames. */
7
+ const JPEG_SOF = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
8
+ export function imageSize(bytes) {
9
+ const u16 = (at) => (bytes[at] << 8) | bytes[at + 1];
10
+ const u32 = (at) => ((bytes[at] << 24) >>> 0) + ((bytes[at + 1] << 16) | (bytes[at + 2] << 8) | bytes[at + 3]);
11
+ if (bytes.length >= 24 && PNG_SIGNATURE.every((byte, i) => bytes[i] === byte) && String.fromCharCode(...bytes.subarray(12, 16)) === "IHDR") {
12
+ return { type: "png", width: u32(16), height: u32(20) };
13
+ }
14
+ if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
15
+ return null;
16
+ let at = 2;
17
+ while (at + 3 < bytes.length) {
18
+ if (bytes[at] !== 0xff)
19
+ return null;
20
+ const marker = bytes[at + 1];
21
+ if (marker === 0xff) {
22
+ at += 1;
23
+ continue;
24
+ }
25
+ if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
26
+ at += 2;
27
+ continue;
28
+ }
29
+ if (marker === 0xd9 || marker === 0xda)
30
+ return null;
31
+ if (JPEG_SOF.has(marker))
32
+ return at + 8 < bytes.length ? { type: "jpeg", height: u16(at + 5), width: u16(at + 7) } : null;
33
+ at += 2 + u16(at + 2);
34
+ }
35
+ return null;
36
+ }
37
+ export class ScreenshotBudgetError extends Error {
38
+ name = "ScreenshotBudgetError";
39
+ }
40
+ /** Over budget, retakes as a viewport JPEG at CSS scale, quality 40, 25, 10; throws ScreenshotBudgetError. */
41
+ export async function captureWithinBudget(capture, requested, budget = { maxEdgePx: SCREENSHOT_MAX_EDGE_PX, maxBase64Bytes: SCREENSHOT_MAX_BASE64_BYTES }) {
42
+ const ceiling = requested.type === "png" ? 40 : (requested.quality ?? 40);
43
+ const ladder = [
44
+ { fullPage: requested.fullPage ?? false, type: requested.type ?? "jpeg", ...(requested.type === "png" ? {} : { quality: requested.quality ?? 40 }), ...(requested.scale ? { scale: requested.scale } : {}) },
45
+ ...[40, 25, 10].map((quality) => ({ fullPage: false, type: "jpeg", quality: Math.min(ceiling, quality), scale: "css" })),
46
+ ];
47
+ const key = (o) => `${o.fullPage}:${o.type}:${o.quality}:${o.scale}`;
48
+ const attempts = ladder.filter((o, i) => ladder.findIndex((other) => key(other) === key(o)) === i);
49
+ let adjusted = null;
50
+ for (const options of attempts) {
51
+ const image = await capture(options);
52
+ const size = imageSize(Buffer.from(image.data, "base64"));
53
+ const why = size === null || Math.max(size.width, size.height) > budget.maxEdgePx ? "long_edge"
54
+ : Buffer.byteLength(image.data, "utf8") > budget.maxBase64Bytes ? "base64_bytes" : null;
55
+ if (why === null && size)
56
+ return { data: image.data, mimeType: image.mimeType, size, options, adjusted };
57
+ adjusted ??= { why: why ?? "long_edge", first: size };
58
+ }
59
+ throw new ScreenshotBudgetError(`The screenshot stays over ${budget.maxEdgePx} px on its long edge or ${budget.maxBase64Bytes} base64 bytes after viewport JPEG retakes at CSS scale and quality 40, 25 and 10.`);
60
+ }
@@ -0,0 +1,16 @@
1
+ export type LeaseState = "creating" | "live" | "releasing" | "released" | "lost";
2
+ /** `gone`: the provider no longer knows the session, which counts as released. */
3
+ export type ResourceStatus = "pending" | "running" | "stopped" | "gone";
4
+ /** Written to documents, so never a secret: a provider keeps connect URLs and keys in its own memory, found again by
5
+ * `id`. */
6
+ export type LeaseRef = {
7
+ readonly id: string;
8
+ readonly tag: string;
9
+ };
10
+ /** Each change is one commit, and a provider call sits between two commits, never inside one. `lost` ends custody of a
11
+ * resource the provider no longer answers for and that was never confirmed released. */
12
+ export declare const LEASE_TRANSITIONS: Readonly<Record<LeaseState | "none", readonly LeaseState[]>>;
13
+ export declare function isLeaseTransition(from: LeaseState | "none", to: LeaseState): boolean;
14
+ /** At most 60 characters of `[A-Za-z0-9_.-]`: Browserbase holds metadata values to 60, and a tag query quotes it
15
+ * unescaped. */
16
+ export declare function leaseTag(prefix: string, run: string, conversation: string | number, seq: number): string;