@parcha/pi-browser 0.1.0-beta.34 → 0.1.0-beta.36

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 (54) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +23 -44
  3. package/dist/core/contract.d.ts +9 -6
  4. package/dist/core/contract.js +8 -29
  5. package/dist/core/driving-guard.d.ts +1 -1
  6. package/dist/core/driving-guard.js +1 -1
  7. package/dist/core/evidence.d.ts +1 -1
  8. package/dist/core/files.d.ts +3 -0
  9. package/dist/core/files.js +4 -1
  10. package/dist/core/host.d.ts +1 -75
  11. package/dist/core/images.d.ts +32 -4
  12. package/dist/core/images.js +81 -16
  13. package/dist/core/redact.d.ts +0 -2
  14. package/dist/core/redact.js +0 -32
  15. package/dist/core/session-control.d.ts +0 -2
  16. package/dist/core/session-control.js +0 -5
  17. package/dist/core/tools.js +4 -1
  18. package/dist/core/usage.d.ts +0 -2
  19. package/dist/core/usage.js +0 -2
  20. package/dist/core/vault.d.ts +0 -10
  21. package/dist/core/vault.js +0 -13
  22. package/dist/core/web.d.ts +2 -111
  23. package/dist/core/web.js +0 -443
  24. package/dist/driver/cdp.js +3 -3
  25. package/dist/driver/page-driver.js +7 -3
  26. package/dist/durable.d.ts +6 -12
  27. package/dist/durable.js +31 -84
  28. package/dist/index.d.ts +1 -1
  29. package/dist/index.js +3 -1
  30. package/dist/providers/cdp.js +2 -2
  31. package/dist/providers/profiles.d.ts +1 -15
  32. package/dist/providers/profiles.js +1 -64
  33. package/dist/providers/shared.d.ts +1 -47
  34. package/dist/providers/shared.js +1 -82
  35. package/dist/providers/worker-extension.js +1 -1
  36. package/dist/testing/backend.d.ts +6 -24
  37. package/dist/testing/backend.js +7 -30
  38. package/dist/vault-session.d.ts +4 -7
  39. package/dist/vault-session.js +26 -81
  40. package/dist/vendor/browser-use-pi/page.d.ts +3 -12
  41. package/dist/vendor/browser-use-pi/page.js +6 -19
  42. package/package.json +3 -16
  43. package/dist/core/sites.d.ts +0 -33
  44. package/dist/core/sites.js +0 -104
  45. package/dist/durable/web.d.ts +0 -47
  46. package/dist/durable/web.js +0 -41
  47. package/dist/providers/browserbase-net.d.ts +0 -12
  48. package/dist/providers/browserbase-net.js +0 -95
  49. package/dist/providers/browserbase.d.ts +0 -169
  50. package/dist/providers/browserbase.js +0 -319
  51. package/dist/providers/kernel.d.ts +0 -58
  52. package/dist/providers/kernel.js +0 -291
  53. /package/dist/{providers → core}/cdp-call.d.ts +0 -0
  54. /package/dist/{providers → core}/cdp-call.js +0 -0
@@ -35,7 +35,7 @@ export function fakeImage(type, width, height) {
35
35
  ihdr[9] = 2;
36
36
  return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk("IHDR", ihdr), chunk("IEND", Buffer.alloc(0))]);
37
37
  }
38
- const DEFAULT_CAPS = { timeoutModel: "inactivity", maxLifetimeS: 3600, survivesDisconnect: false, releaseIsAsync: false, profiles: false, extension: "loaded-locally" };
38
+ const DEFAULT_CAPS = { profiles: false };
39
39
  export class FakeBackend {
40
40
  sentinels;
41
41
  pages;
@@ -62,8 +62,6 @@ export class FakeBackend {
62
62
  this.opts = {
63
63
  ...options,
64
64
  start: options.start ?? "about:blank",
65
- fetches: options.fetches ?? {},
66
- search: options.search ?? [],
67
65
  downloads: options.downloads ?? {},
68
66
  connections: options.connections ?? [{ name: "demo", startUrl: "https://login.sentinel.test/", fields: [{ name: "username", type: "text" }, { name: "password", type: "password" }, { name: "otp", type: "totp" }], allowedOrigins: ["https://login.sentinel.test"], enrollment: true }],
69
67
  };
@@ -104,7 +102,7 @@ export class FakeBackend {
104
102
  const count = (op) => this.ledger.filter((r) => r.op === op).length;
105
103
  return {
106
104
  creates: count("create"), findByTag: count("findByTag"), status: count("status"), attaches: count("attach"), releases: count("release"), releaseNoops: count("release-noop"),
107
- fetches: count("fetch"), searches: count("search"), dispatches: this.dispatched.filter((d) => d.op === "run").length, reads: this.dispatched.filter((d) => d.op === "read").length,
105
+ dispatches: this.dispatched.filter((d) => d.op === "run").length, reads: this.dispatched.filter((d) => d.op === "read").length,
108
106
  peakLive: this.peak, liveAtEnd: this.liveCount(),
109
107
  };
110
108
  }
@@ -211,26 +209,6 @@ export class FakeBackend {
211
209
  const view = b.sentinels.bbLiveViewUrl;
212
210
  return { fullscreen: view, framed: `${view}&framed=1`, pages: [{ id: "p1", url: s.url, title: b.pages[s.url]?.title ?? "", fullscreen: view }] };
213
211
  },
214
- async fetch(request, signal) {
215
- await b.before("fetch", signal);
216
- b.record("fetch", { url: request.url });
217
- await b.after("fetch");
218
- const entry = b.opts.fetches[request.url];
219
- if (entry === undefined)
220
- throw new FakeProviderError(`fetch ${request.url}: 404`, 404);
221
- if (typeof entry === "string")
222
- return { finalUrl: request.url, statusCode: 200, contentType: "text/markdown", content: entry };
223
- const answer = entry[request.format === "raw" ? "raw" : "markdown"];
224
- if (!answer || "status" in answer)
225
- throw new FakeProviderError(`fetch ${request.url}: ${answer?.status ?? 404}`, answer?.status ?? 404);
226
- return { finalUrl: request.url, statusCode: 200, contentType: answer.contentType, content: answer.content };
227
- },
228
- async search(request, signal) {
229
- await b.before("search", signal);
230
- b.record("search", { query: request.query });
231
- await b.after("search");
232
- return { results: b.opts.search.slice(0, request.n) };
233
- },
234
212
  downloads: {
235
213
  async list(_ref) { return Object.entries(b.opts.downloads).map(([name, body]) => ({ name, sizeBytes: Buffer.byteLength(body), modifiedAt: null })); },
236
214
  async read(_ref, fileName, maxBytes) {
@@ -299,8 +277,6 @@ export function remoteProvider(url, options = {}) {
299
277
  attach: (ref, signal) => call("attach", [ref], signal),
300
278
  release: (ref, signal) => call("release", [ref], signal),
301
279
  liveView: (ref) => call("liveView", [ref]),
302
- fetch: (request, signal) => call("fetch", [request], signal),
303
- search: (request, signal) => call("search", [request], signal),
304
280
  };
305
281
  }
306
282
  /** Counts a fill before the provider is touched and never repeats an unknown one; its failures carry only codes. */
@@ -393,13 +369,14 @@ export class FakeDriverFace {
393
369
  await this.b.before("driver.url");
394
370
  return this.session(id).url;
395
371
  }
396
- /** Header-only image of the viewport (or full page) times the device scale; each capture is a dispatched row. */
372
+ /** Header-only image of the viewport (or full page) times the device scale and the asked scale, rounded as Chrome
373
+ * rounds; each capture is a dispatched row. */
397
374
  async screenshot(id, options = {}) {
398
375
  await this.call(id, "screenshot", "screenshot", { options });
399
376
  const { viewport = { width: 1288, height: 711 }, fullPageHeight = 8319, deviceScale = 1 } = this.b.opts;
400
- const factor = options.scale === "css" ? 1 : deviceScale;
401
- const width = (options.clip ? options.clip.width : viewport.width) * factor;
402
- const height = (options.clip ? options.clip.height : options.fullPage ? fullPageHeight : viewport.height) * factor;
377
+ const factor = deviceScale * (options.scale ?? 1);
378
+ const width = Math.round((options.clip ? options.clip.width : viewport.width) * factor);
379
+ const height = Math.round((options.clip ? options.clip.height : options.fullPage ? fullPageHeight : viewport.height) * factor);
403
380
  const type = options.type ?? "jpeg";
404
381
  await this.b.after("driver.screenshot");
405
382
  return { data: fakeImage(type, width, height).toString("base64"), mimeType: `image/${type}`, width, height };
@@ -28,23 +28,20 @@ export declare function vaultRuntime(options: VaultOptions, track: (secret: stri
28
28
  }): VaultRuntime | null;
29
29
  /** Waits, up to `ms`, for a person to stop driving a session: a capture reads only once they have handed back. True when the gate is free. */
30
30
  export declare function untilQuiet(gate: DrivingGate | null, ms?: number): Promise<boolean>;
31
- /** `vaulted`: this session was created under the host's vault plan (a context kind asked the provider for a saved context or profile), so it may be captured; a session that
32
- * started with no target cannot be given one later, because its provider holds no context for it. `fresh`: nothing was kept, so a new context was made and its id is
33
- * given to the vault right after the create (a restart then still finds it). */
31
+ /** `vaulted`: this session was created under the host's vault plan, with a target. */
34
32
  export type RestorePlan = {
35
33
  spec: SessionSpec;
36
34
  afterAttach: ((target: AttachTarget) => Promise<void>) | null;
37
35
  vaulted: boolean;
38
- fresh: boolean;
39
36
  /** Set when the vault may hold a saved sign-in this session did not take (the read failed, or what it holds could not be used here): this session is NOT captured, so it
40
37
  * can never replace what is saved. The text is the warning given once at the first capture. */
41
38
  holdBack?: string;
42
39
  };
43
- /** What the create does with the vault: the spec the provider is asked for (a kept context or profile for Browserbase and Kernel) and a step that runs after the
44
- * browser is attached and before the driver is (a local Chrome's cookies and local storage). The record the adapter stores is made from the ORIGINAL spec, never this one. */
40
+ /** What the create does with the vault: a step that runs after the browser is attached and before the driver is (a local Chrome's cookies and local storage).
41
+ * The spec is the one given, and the record the adapter stores is made from it. */
45
42
  export declare function planRestore(rt: VaultRuntime | null, target: VaultTarget | undefined, provider: BrowserProvider, spec: SessionSpec): Promise<RestorePlan>;
46
43
  export type CaptureOptions = {
47
- /** Whether the session was created under the vault plan (RestorePlan.vaulted). A context kind session that was not cannot be captured. */
44
+ /** Whether the session was created under the vault plan (RestorePlan.vaulted). */
48
45
  vaulted: boolean;
49
46
  /** The session's driving gate, read when the capture runs: a person who begins driving while the browser is being read voids that read. */
50
47
  gate?: () => DrivingGate | null;
@@ -1,13 +1,11 @@
1
1
  // How an adapter uses a host's session vault (core/vault.ts): restore a kept sign-in when a session is created, before the driver attaches, and capture
2
- // it when the session is released or a person hands it back. The state stays in memory and crosses only the host's port: nothing here logs a value, and
3
- // a provider's context id is registered with the run's redactor the moment it is seen. A restore or capture that fails never fails the browser: the session
2
+ // it when the session is released or a person hands it back. Only a local Chrome's state is kept (its cookies and local storage, over CDP). The state
3
+ // stays in memory and crosses only the host's port: nothing here logs a value. A restore or capture that fails never fails the browser: the session
4
4
  // starts signed out, or ends without a fresh capture, and a process warning says which, with no value in it.
5
- import { randomBytes } from "node:crypto";
6
5
  import { BrowserFailureError } from "./core/custody.js";
7
6
  import { browserFailure } from "./core/failures.js";
8
- import { MIN_REDACTED_VALUE_LENGTH } from "./core/redact.js";
9
7
  import { keptFor } from "./core/driving.js";
10
- import { clampSessionCookieAgeMs, coversEveryOrigin, vaultTarget } from "./core/vault.js";
8
+ import { clampSessionCookieAgeMs, vaultTarget } from "./core/vault.js";
11
9
  import { captureCdpState, connectCdp, restoreCdpState } from "./providers/cdp-session.js";
12
10
  /** `null` when the host gave no vault. A bad age cap throws here, so a host learns at setup. */
13
11
  export function vaultRuntime(options, track, warn, now = () => new Date(), limits = {}) {
@@ -37,21 +35,12 @@ async function within(work, ms, onTimeout = () => { }) {
37
35
  }
38
36
  }
39
37
  const refused = (message) => new BrowserFailureError(browserFailure("refused", message));
40
- /** A secret too short for the redactor to scrub is not used as one: the redactor ignores values under its minimum, so it would leak. */
41
- function trackSecret(rt, secret, what) {
42
- if (secret.length < MIN_REDACTED_VALUE_LENGTH) {
43
- rt.warn(`the session vault's ${what} is too short for the redactor to scrub, so it is not used`);
44
- return false;
45
- }
46
- rt.track(secret);
47
- return true;
48
- }
49
38
  const HELD_FAILED = "the vault could not be read at the start, so a saved sign-in may exist under this key and is left untouched: this session's sign-in is not captured";
50
39
  const HELD_UNUSED = "the vault holds a saved sign-in this session could not use, and it is left untouched: this session's sign-in is not captured";
51
- /** What the create does with the vault: the spec the provider is asked for (a kept context or profile for Browserbase and Kernel) and a step that runs after the
52
- * browser is attached and before the driver is (a local Chrome's cookies and local storage). The record the adapter stores is made from the ORIGINAL spec, never this one. */
40
+ /** What the create does with the vault: a step that runs after the browser is attached and before the driver is (a local Chrome's cookies and local storage).
41
+ * The spec is the one given, and the record the adapter stores is made from it. */
53
42
  export async function planRestore(rt, target, provider, spec) {
54
- const plain = { spec, afterAttach: null, vaulted: false, fresh: false };
43
+ const plain = { spec, afterAttach: null, vaulted: false };
55
44
  if (!rt || !target)
56
45
  return plain;
57
46
  let checked;
@@ -66,8 +55,6 @@ export async function planRestore(rt, target, provider, spec) {
66
55
  rt.warn("this browser provider cannot keep a session in a vault (a Chrome attached by endpoint is offered only when the host sets ownBrowser: true), so nothing was restored or will be captured");
67
56
  return plain;
68
57
  }
69
- if (vault.kind === "context" && vault.contextIdsInClear)
70
- throw refused("browser vault: this provider writes its context ids to a clear file, so a vault cannot use it. Give it a profile store that keeps ids in memory (memoryProfileStore). No session was started.");
71
58
  // A vault that stops answering never holds the session back: it starts signed out.
72
59
  let kept = null;
73
60
  let holdBack;
@@ -78,40 +65,17 @@ export async function planRestore(rt, target, provider, spec) {
78
65
  holdBack = HELD_FAILED;
79
66
  rt.warn(`the session vault could not restore (${kindOf(error)}); the session starts signed out`);
80
67
  }
81
- if (vault.kind === "context") {
82
- if (kept && (kept.kind !== "provider-context" || kept.provider !== vault.provider)) {
83
- rt.warn(`the vault holds a ${kept.kind} state this ${vault.provider} provider cannot use; it was ignored`);
84
- kept = null;
85
- holdBack = HELD_UNUSED;
86
- }
87
- // A context is a whole browser profile: it comes back only for a request that covers every origin it was saved for, never for some of them.
88
- if (kept?.kind === "provider-context" && !coversEveryOrigin(checked.origins, kept.origins)) {
89
- rt.warn("the vault holds a context whose saved origins this request does not cover every origin of (or records none); it was not restored");
90
- kept = null;
91
- holdBack = HELD_UNUSED;
92
- }
93
- if (kept?.kind === "provider-context" && !trackSecret(rt, kept.contextId, "context id")) {
94
- kept = null;
95
- holdBack = HELD_UNUSED;
96
- }
97
- if (kept?.kind === "provider-context")
98
- return { spec: vault.provider === "browserbase" ? { ...spec, contextId: kept.contextId, profile: undefined } : { ...spec, profile: { name: kept.contextId, save: true } }, afterAttach: null, vaulted: true, fresh: false };
99
- // A saved sign-in may exist that this session did not take: nothing persists for it, and it is never captured.
100
- if (holdBack)
101
- return { spec, afterAttach: null, vaulted: true, fresh: false, holdBack };
102
- // Nothing kept: a context that persists is made for this session, its id held in memory and given to the vault right after the create.
103
- return { spec: { ...spec, contextId: undefined, profile: { name: `vault-${randomBytes(9).toString("hex")}`, save: true } }, afterAttach: null, vaulted: true, fresh: true };
104
- }
105
68
  if (!kept)
106
69
  return { ...plain, vaulted: true, ...(holdBack ? { holdBack } : {}) };
107
- if (kept.kind !== "cdp") {
108
- rt.warn(`the vault holds a ${kept.kind} state a local Chrome cannot use; it was ignored`);
70
+ // A host's vault may hold a state of a kind this package does not keep (a hosted vendor's context, from before): left untouched, never replaced.
71
+ const kind = kept.kind;
72
+ if (kind !== "cdp") {
73
+ rt.warn(`the vault holds a ${typeof kind === "string" ? kind.slice(0, 40) : "different"} state a local Chrome cannot use; it was ignored`);
109
74
  return { ...plain, vaulted: true, holdBack: HELD_UNUSED };
110
75
  }
111
76
  return {
112
77
  spec,
113
78
  vaulted: true,
114
- fresh: false,
115
79
  afterAttach: async (attached) => {
116
80
  let link;
117
81
  try {
@@ -148,13 +112,6 @@ export function captureFor(rt, target, provider, ref, options = { vaulted: true
148
112
  }
149
113
  return;
150
114
  }
151
- if (vault.kind === "context" && !options.vaulted) {
152
- if (!warnedLate) {
153
- warnedLate = true;
154
- rt.warn("this session started with no vault target, so its provider holds no saved context for it: its sign-in cannot be kept. Set the target before the session starts");
155
- }
156
- return;
157
- }
158
115
  const stop = new AbortController();
159
116
  let link;
160
117
  // Numbered when it starts: an older capture that is still reading when a newer one of the same key begins writes nothing.
@@ -168,38 +125,26 @@ export function captureFor(rt, target, provider, ref, options = { vaulted: true
168
125
  if ((rt.latest.get(key) ?? 0) < attempt)
169
126
  rt.latest.set(key, attempt);
170
127
  const capturedAt = rt.now();
128
+ const gate = options.gate?.() ?? null;
129
+ let interrupted = false;
171
130
  let state;
172
- if (vault.kind === "context") {
173
- const id = vault.contextOf(ref);
174
- if (!id) {
175
- rt.warn("this provider no longer knows the context this session runs on (the run restarted), so its sign-in was not captured; the context the vault holds stands");
131
+ const off = gate?.onChange((now) => { if (now === "person")
132
+ interrupted = true; });
133
+ try {
134
+ const attached = await provider.attach(ref, stop.signal);
135
+ link = await connectCdp(attached.sdkCdpUrl);
136
+ if (stop.signal.aborted) {
137
+ link.close();
176
138
  return;
177
139
  }
178
- if (!trackSecret(rt, id, "context id"))
179
- return;
180
- state = { kind: "provider-context", capturedAt: capturedAt.toISOString(), provider: vault.provider, contextId: id, origins: [...checked.origins] };
140
+ state = await captureCdpState(link, checked.origins, capturedAt);
181
141
  }
182
- else {
183
- const gate = options.gate?.() ?? null;
184
- let interrupted = false;
185
- const off = gate?.onChange((now) => { if (now === "person")
186
- interrupted = true; });
187
- try {
188
- const attached = await provider.attach(ref, stop.signal);
189
- link = await connectCdp(attached.sdkCdpUrl);
190
- if (stop.signal.aborted) {
191
- link.close();
192
- return;
193
- }
194
- state = await captureCdpState(link, checked.origins, capturedAt);
195
- }
196
- finally {
197
- off?.();
198
- }
199
- if (interrupted || (gate && keptFor(gate) === "person_driving")) {
200
- rt.warn("a person began driving while the session was being read, so that capture was discarded; the last capture stands");
201
- return;
202
- }
142
+ finally {
143
+ off?.();
144
+ }
145
+ if (interrupted || (gate && keptFor(gate) === "person_driving")) {
146
+ rt.warn("a person began driving while the session was being read, so that capture was discarded; the last capture stands");
147
+ return;
203
148
  }
204
149
  // Nothing is written once the deadline has passed or a newer capture of this key has begun: an older read never replaces a newer one.
205
150
  if (stop.signal.aborted || rt.latest.get(key) !== attempt)
@@ -1,3 +1,4 @@
1
+ import { type ScreenshotOptions } from "../../core/images.js";
1
2
  import type { CDP } from "./cdp.js";
2
3
  /** The schemes a page is sent to: the web and the blank page, never a file of this machine or the browser's own pages. */
3
4
  export declare const NAVIGABLE: RegExp;
@@ -23,16 +24,6 @@ export declare class Page {
23
24
  }): Promise<void>;
24
25
  clickAt(x: number, y: number): Promise<void>;
25
26
  moveTo(x: number, y: number): Promise<void>;
26
- /** `clip` in CSS pixels from the viewport's corner, as the page tools give it; the browser's own is from the document's. */
27
- screenshot(options?: {
28
- type?: "png" | "jpeg";
29
- quality?: number;
30
- fullPage?: boolean;
31
- clip?: {
32
- x: number;
33
- y: number;
34
- width: number;
35
- height: number;
36
- };
37
- }): Promise<string>;
27
+ /** The driver's options as core/images.ts captureParams makes them CDP's, on the page's layout as it is now. */
28
+ screenshot(options?: ScreenshotOptions): Promise<string>;
38
29
  }
@@ -2,9 +2,10 @@
2
2
  // e7007f219b10fa2c2baae1bf3e2f902a5a2706fd, src/page.ts. MIT License, Copyright (c) 2026 Browser Use contributors; the
3
3
  // license's full text is in this package's NOTICE, and UPSTREAM.json beside this file records the source.
4
4
  // Changes: the Page class only (no Tabs, no snapshot of its own: ax.ts's is the driver's); goto refuses a scheme other
5
- // than http, https and about:blank; screenshot takes the driver's format, quality, clip and full-page options; untyped
6
- // CDP params and results.
5
+ // than http, https and about:blank; screenshot takes the driver's options (format, quality, clip, full page and scale),
6
+ // sent as core/images.ts captureParams makes them; untyped CDP params and results.
7
7
  import { setTimeout as delay } from "node:timers/promises";
8
+ import { captureParams } from "../../core/images.js";
8
9
  const contextLost = /Execution context was destroyed|Cannot find context|Cannot find default execution context/;
9
10
  /** The schemes a page is sent to: the web and the blank page, never a file of this machine or the browser's own pages. */
10
11
  export const NAVIGABLE = /^(https?:\/\/|about:blank$)/i;
@@ -89,24 +90,10 @@ export class Page {
89
90
  throw new Error("Coordinates must be finite.");
90
91
  await this.cdp("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
91
92
  }
92
- /** `clip` in CSS pixels from the viewport's corner, as the page tools give it; the browser's own is from the document's. */
93
+ /** The driver's options as core/images.ts captureParams makes them CDP's, on the page's layout as it is now. */
93
94
  async screenshot(options = {}) {
94
- const type = options.type ?? "png";
95
- let clip;
96
- if (options.clip) {
97
- const scroll = await this.evaluate(() => ({ x: scrollX, y: scrollY })).catch(() => ({ x: 0, y: 0 }));
98
- clip = { ...options.clip, x: options.clip.x + scroll.x, y: options.clip.y + scroll.y, scale: 1 };
99
- }
100
- else if (options.fullPage) {
101
- const { cssContentSize } = await this.cdp("Page.getLayoutMetrics");
102
- clip = { x: 0, y: 0, width: Math.ceil(cssContentSize.width), height: Math.ceil(cssContentSize.height), scale: 1 };
103
- }
104
- const { data } = await this.cdp("Page.captureScreenshot", {
105
- format: type,
106
- ...(type === "jpeg" && options.quality !== undefined ? { quality: Math.round(options.quality) } : {}),
107
- ...(options.fullPage && !options.clip ? { captureBeyondViewport: true } : {}),
108
- ...(clip ? { clip } : {}),
109
- });
95
+ const layout = await this.cdp("Page.getLayoutMetrics");
96
+ const { data } = await this.cdp("Page.captureScreenshot", captureParams(options, layout));
110
97
  return data;
111
98
  }
112
99
  }
package/package.json CHANGED
@@ -1,18 +1,17 @@
1
1
  {
2
2
  "name": "@parcha/pi-browser",
3
- "version": "0.1.0-beta.34",
3
+ "version": "0.1.0-beta.36",
4
4
  "description": "Your agent gets its own browser, and you can take over and hand it back.",
5
5
  "keywords": [
6
6
  "pi-durable",
7
7
  "browser",
8
- "stagehand",
9
- "browserbase"
8
+ "stagehand"
10
9
  ],
11
10
  "type": "module",
12
11
  "license": "Apache-2.0",
13
12
  "author": "Parcha Labs, Inc.",
14
13
  "engines": {
15
- "node": ">=24.11.0"
14
+ "node": ">=24.22.3"
16
15
  },
17
16
  "exports": {
18
17
  ".": {
@@ -27,10 +26,6 @@
27
26
  "types": "./dist/live-view/index.d.ts",
28
27
  "import": "./dist/live-view/index.js"
29
28
  },
30
- "./providers/browserbase": {
31
- "types": "./dist/providers/browserbase.d.ts",
32
- "import": "./dist/providers/browserbase.js"
33
- },
34
29
  "./providers/cdp": {
35
30
  "types": "./dist/providers/cdp.d.ts",
36
31
  "import": "./dist/providers/cdp.js"
@@ -43,10 +38,6 @@
43
38
  "types": "./dist/providers/chrome-args.d.ts",
44
39
  "import": "./dist/providers/chrome-args.js"
45
40
  },
46
- "./providers/kernel": {
47
- "types": "./dist/providers/kernel.d.ts",
48
- "import": "./dist/providers/kernel.js"
49
- },
50
41
  "./driver/stagehand": {
51
42
  "types": "./dist/driver/stagehand.d.ts",
52
43
  "import": "./dist/driver/stagehand.js"
@@ -87,14 +78,10 @@
87
78
  "zod": "~4.6.6"
88
79
  },
89
80
  "peerDependencies": {
90
- "@browserbasehq/sdk": ">=2.20.0 <3",
91
81
  "@earendil-works/chord": "1.5.0",
92
82
  "@earendil-works/pi-durable": "1.5.0"
93
83
  },
94
84
  "peerDependenciesMeta": {
95
- "@browserbasehq/sdk": {
96
- "optional": true
97
- },
98
85
  "@earendil-works/chord": {
99
86
  "optional": true
100
87
  },
@@ -1,33 +0,0 @@
1
- import type { ToolContract } from "./contract.js";
2
- import type { ToolOutput } from "./custody.js";
3
- import type { ChildRunner, SiteInfo, SiteRunPort } from "./host.js";
4
- export declare const MAX_SITE_INSTRUCTIONS = 16000;
5
- /** The site enum and the description render from the listing, which is configuration: every request sends the same
6
- * text and keeps the prompt cache. */
7
- export declare function useWebsiteContract(sites: readonly SiteInfo[]): ToolContract;
8
- /** Only the declared shape crosses back to the model: a port's extra fields, such as capabilities or URLs, are dropped
9
- * here, and an answer with both shapes or neither is no answer. */
10
- export declare function siteAnswer(raw: unknown): {
11
- run: {
12
- id: string;
13
- state: string;
14
- };
15
- } | {
16
- report: string;
17
- } | null;
18
- export declare function useWebsite(args: {
19
- site?: unknown;
20
- request_id?: unknown;
21
- instructions?: unknown;
22
- }, port: SiteRunPort, sites: readonly SiteInfo[], ctx: {
23
- signal: AbortSignal;
24
- runChild: ChildRunner;
25
- }): Promise<ToolOutput>;
26
- export type LocalSite = {
27
- title: string;
28
- description: string;
29
- startUrl: string;
30
- };
31
- /** `use_website` for a plain pi user: each task runs a child agent through the adapter's `runChild` and answers its
32
- * report. A request_id runs once; a failed run may be asked again. */
33
- export declare function localSites(sites: Record<string, LocalSite>): SiteRunPort;
@@ -1,104 +0,0 @@
1
- import { browserFailure } from "./failures.js";
2
- export const MAX_SITE_INSTRUCTIONS = 16_000;
3
- const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
4
- const RUN_ID = /^[A-Za-z0-9_.:-]{1,200}$/;
5
- const RUN_STATE = /^[a-z_]{1,40}$/;
6
- /** The site enum and the description render from the listing, which is configuration: every request sends the same
7
- * text and keeps the prompt cache. */
8
- export function useWebsiteContract(sites) {
9
- return {
10
- name: "use_website",
11
- label: "Use a website",
12
- description: [
13
- "Hand a task to an agent that works on one of these websites in its own browser, and get back what it found or did:",
14
- ...sites.map((site) => `- ${site.site}: ${site.title}. ${site.description}`),
15
- "Give a new request_id (a UUID) for each new task. Calling again with the request_id of a finished task answers its result without running it again; a task that failed runs again, and may repeat what it already did on the site.",
16
- "Several calls in one turn run at once, each agent in its own browser.",
17
- ].join("\n"),
18
- parameters: {
19
- type: "object", additionalProperties: false, required: ["site", "request_id", "instructions"],
20
- properties: {
21
- site: { type: "string", enum: sites.map((site) => site.site), description: "The website to use." },
22
- request_id: { type: "string", description: "A UUID you choose for this task." },
23
- instructions: { type: "string", maxLength: MAX_SITE_INSTRUCTIONS, description: "What to do on the website and what to report back." },
24
- },
25
- },
26
- effect: "effect", replay: "safe", executionMode: "parallel", evidence: "none", listedWhen: "sites",
27
- };
28
- }
29
- /** Only the declared shape crosses back to the model: a port's extra fields, such as capabilities or URLs, are dropped
30
- * here, and an answer with both shapes or neither is no answer. */
31
- export function siteAnswer(raw) {
32
- if (!raw || typeof raw !== "object")
33
- return null;
34
- const { run, report } = raw;
35
- if ((run === undefined) === (report === undefined))
36
- return null;
37
- if (report !== undefined)
38
- return typeof report === "string" ? { report } : null;
39
- const { id, state } = (run ?? {});
40
- return typeof id === "string" && RUN_ID.test(id) && typeof state === "string" && RUN_STATE.test(state) ? { run: { id, state } } : null;
41
- }
42
- const siteOutput = (body, isError = false) => ({ content: [{ type: "text", text: JSON.stringify(body) }], ...(isError ? { isError: true } : {}) });
43
- const siteRefusal = (message) => siteOutput(browserFailure("refused", message), true);
44
- export async function useWebsite(args, port, sites, ctx) {
45
- const site = sites.find((known) => known.site === args.site);
46
- if (!site)
47
- return siteRefusal(`site is one of: ${sites.map((known) => known.site).join(", ")}`);
48
- if (typeof args.request_id !== "string" || !UUID.test(args.request_id))
49
- return siteRefusal("request_id is a UUID you choose for this task");
50
- const instructions = typeof args.instructions === "string" ? args.instructions.trim() : "";
51
- if (!instructions || instructions.length > MAX_SITE_INSTRUCTIONS)
52
- return siteRefusal(`instructions say what to do on the site, in at most ${MAX_SITE_INSTRUCTIONS} characters`);
53
- const head = { ok: true, site: site.site, request_id: args.request_id };
54
- let raw;
55
- try {
56
- raw = await port.use({ site: site.site, requestId: args.request_id, instructions }, ctx);
57
- }
58
- catch {
59
- // A port's error text can carry its grant or a URL: none of it is forwarded.
60
- if (ctx.signal.aborted)
61
- return siteOutput({ ok: false, code: "aborted", retryable: true, effect: "possibly_effected", message: "The call was cancelled, and the site's task may already have changed the site. Calling again with the same request_id runs an unfinished task again, and it may repeat what it did." }, true);
62
- return siteOutput({ ok: false, code: "command_failed", retryable: true, effect: "possibly_effected", message: `The ${site.site} task failed, and may already have changed the site. Calling use_website again with the same request_id runs it again, and it may repeat what it did.` }, true);
63
- }
64
- const parsed = siteAnswer(raw);
65
- if (!parsed)
66
- return siteOutput({ ok: false, code: "command_failed", retryable: false, effect: "possibly_effected", message: `The ${site.site} runner answered neither a started task nor a report.` }, true);
67
- if ("report" in parsed)
68
- return siteOutput({ ...head, report: parsed.report });
69
- return siteOutput({ ...head, run: parsed.run, next: "The site's task was started; its result arrives through your host. Do not call use_website again for this request." });
70
- }
71
- const childPrompt = (site, entry, instructions) => [
72
- `You are doing one task on ${entry.title} (${site}) for another agent, in your own browser.`,
73
- `Start at ${entry.startUrl}.`,
74
- `Task: ${instructions}`,
75
- "Use the browser tools. Do not ask questions. Finish with a short report of what you found or did.",
76
- ].join("\n");
77
- /** `use_website` for a plain pi user: each task runs a child agent through the adapter's `runChild` and answers its
78
- * report. A request_id runs once; a failed run may be asked again. */
79
- export function localSites(sites) {
80
- for (const [site, entry] of Object.entries(sites)) {
81
- if (!/^https?:\/\//.test(entry.startUrl))
82
- throw new Error(`site ${site}: startUrl must be an http or https URL`);
83
- }
84
- const runs = new Map();
85
- return {
86
- async list() {
87
- return Object.entries(sites).map(([site, entry]) => ({ site, title: entry.title, description: entry.description }));
88
- },
89
- async use({ site, requestId, instructions }, { signal, runChild }) {
90
- const entry = Object.hasOwn(sites, site) ? sites[site] : undefined;
91
- if (!entry)
92
- throw new Error(`no site named ${site}`);
93
- const key = `${site}\u0000${requestId}`;
94
- let run = runs.get(key);
95
- if (!run) {
96
- run = runChild({ site, requestId, prompt: childPrompt(site, entry, instructions) }, signal);
97
- runs.set(key, run);
98
- run.catch(() => { if (runs.get(key) === run)
99
- runs.delete(key); });
100
- }
101
- return { report: await run };
102
- },
103
- };
104
- }
@@ -1,47 +0,0 @@
1
- import { defineExtension, type ConversationId, type ToolRegistration } from "@earendil-works/pi-durable";
2
- import type { Decisions } from "../core/decisions.js";
3
- import type { EvidenceSink } from "../core/evidence.js";
4
- import type { FetchRequest, FetchResult, PriceTable, SearchRequest, SearchResult } from "../core/host.js";
5
- import { type FetchSource, type RenderedPage, type SearchSource, type WebBackup, type WebToolsOptions } from "../core/web.js";
6
- export type WebExtensionOptions = {
7
- providers: {
8
- /** Names the source in `via` (`<name>_fetch`, `<name>_search`); default "provider". */
9
- name?: string;
10
- fetch?: (request: FetchRequest, signal?: AbortSignal) => Promise<FetchResult>;
11
- search?: (request: SearchRequest, signal?: AbortSignal) => Promise<SearchResult>;
12
- };
13
- /** Searches tried before `providers.search`, in order (see `SearchSource`). */
14
- searchSources?: readonly SearchSource[];
15
- /** Readers tried before `providers.fetch` for a markdown read, in order (see `FetchSource`). */
16
- fetchSources?: readonly FetchSource[];
17
- evidence: EvidenceSink;
18
- /** Per use: evidence label and proxies. Default: label "web", proxies on. */
19
- scope?: (conversationId: ConversationId) => {
20
- label: string;
21
- proxies: boolean;
22
- } | Promise<{
23
- label: string;
24
- proxies: boolean;
25
- }>;
26
- prices?: Partial<PriceTable>;
27
- redact?: {
28
- values: () => readonly string[];
29
- };
30
- /** The host's fallback fetchers, tried in order when the provider cannot fetch a page. */
31
- backups?: ReadonlyArray<WebBackup>;
32
- decisions?: Pick<Decisions, "classifyPage">;
33
- render?: {
34
- enabled: boolean;
35
- read(url: string, signal?: AbortSignal): Promise<RenderedPage>;
36
- };
37
- pdf?: WebToolsOptions["pdf"];
38
- /** How long the screening of a search answer's snippets may take in all (see `WebToolsOptions`). */
39
- snippetScreenMs?: number;
40
- section?: {
41
- addendum?: string;
42
- };
43
- };
44
- export declare function createWebExtension(options: WebExtensionOptions): {
45
- extension: ReturnType<typeof defineExtension>;
46
- tools: readonly ToolRegistration[];
47
- };
@@ -1,41 +0,0 @@
1
- import { defineExtension, defineTool } from "@earendil-works/pi-durable";
2
- import { WEB_TOOLS } from "../core/contract.js";
3
- import { providerKeyValues } from "../core/session-control.js";
4
- import { toolUsage } from "../core/usage.js";
5
- import { createWebTools } from "../core/web.js";
6
- import { forModel } from "./result.js";
7
- export function createWebExtension(options) {
8
- const tools = createWebTools({
9
- name: options.providers.name ?? "provider",
10
- fetch: options.providers.fetch,
11
- search: options.providers.search,
12
- searchSources: options.searchSources,
13
- fetchSources: options.fetchSources,
14
- evidence: options.evidence,
15
- scope: options.scope ?? (() => ({ label: "web", proxies: true })),
16
- prices: options.prices,
17
- redact: { values: () => providerKeyValues(process.env, options.redact?.values) },
18
- backups: options.backups,
19
- classifyPage: options.decisions?.classifyPage,
20
- render: options.render,
21
- pdf: options.pdf,
22
- snippetScreenMs: options.snippetScreenMs,
23
- });
24
- const run = { web_fetch: tools.fetch, web_search: tools.search };
25
- const result = ({ text, isError, details, usd }) => ({ ...forModel([{ type: "text", text }]), isError, details: details, usage: toolUsage(usd).usage });
26
- const registrations = WEB_TOOLS
27
- .filter((tool) => (tool.listedWhen === "fetch" ? options.providers.fetch || options.render?.enabled || options.backups?.length || options.fetchSources?.length : options.providers.search || options.searchSources?.length))
28
- .map((tool) => defineTool({
29
- name: tool.name,
30
- description: tool.description,
31
- parameters: tool.parameters,
32
- replay: tool.replay,
33
- executionMode: tool.executionMode,
34
- execute: async (args, api, context) => result(await run[tool.name](api.conversationId, args, context.abortSignal)),
35
- }));
36
- // Matched by name: another extension's tool registered under the same name would carry the text too.
37
- const names = new Set(registrations.map((tool) => tool.name));
38
- const addendum = options.section?.addendum;
39
- const sections = addendum ? [{ key: "web", render: async (input) => (input.agent.tools.some((tool) => names.has(tool.name)) ? addendum : undefined) }] : [];
40
- return { extension: defineExtension({ name: "web", tools: registrations, sections }), tools: registrations };
41
- }