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

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 (71) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/NOTICE +30 -0
  3. package/README.md +33 -199
  4. package/dist/core/contract.d.ts +9 -6
  5. package/dist/core/contract.js +22 -34
  6. package/dist/core/custody.d.ts +6 -0
  7. package/dist/core/custody.js +6 -0
  8. package/dist/core/driving-guard.js +17 -2
  9. package/dist/core/evidence.d.ts +1 -1
  10. package/dist/core/files.d.ts +3 -0
  11. package/dist/core/files.js +4 -1
  12. package/dist/core/host.d.ts +0 -63
  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.d.ts +9 -0
  18. package/dist/core/usage.d.ts +0 -2
  19. package/dist/core/usage.js +0 -2
  20. package/dist/core/web.d.ts +2 -111
  21. package/dist/core/web.js +0 -443
  22. package/dist/driver/cdp.d.ts +6 -0
  23. package/dist/driver/cdp.js +245 -0
  24. package/dist/driver/page-driver.js +29 -3
  25. package/dist/durable/store.js +13 -4
  26. package/dist/durable.d.ts +2 -12
  27. package/dist/durable.js +9 -80
  28. package/dist/index.d.ts +0 -1
  29. package/dist/index.js +0 -1
  30. package/dist/live-view/provider.d.ts +2 -2
  31. package/dist/live-view/provider.js +2 -2
  32. package/dist/live-view/server.d.ts +1 -1
  33. package/dist/providers/browserbase.d.ts +0 -31
  34. package/dist/providers/browserbase.js +2 -27
  35. package/dist/providers/chrome-args.d.ts +3 -0
  36. package/dist/providers/chrome-args.js +13 -2
  37. package/dist/testing/backend.d.ts +2 -21
  38. package/dist/testing/backend.js +1 -25
  39. package/dist/vendor/browser-use-pi/ax.d.ts +106 -0
  40. package/dist/vendor/browser-use-pi/ax.js +642 -0
  41. package/dist/vendor/browser-use-pi/cdp.d.ts +19 -0
  42. package/dist/vendor/browser-use-pi/cdp.js +106 -0
  43. package/dist/vendor/browser-use-pi/page.d.ts +38 -0
  44. package/dist/vendor/browser-use-pi/page.js +112 -0
  45. package/package.json +7 -25
  46. package/src/vendor/browser-use-pi/UPSTREAM.json +25 -0
  47. package/src/vendor/stagehand-facade/UPSTREAM.json +0 -4
  48. package/dist/coding-agent-local.d.ts +0 -12
  49. package/dist/coding-agent-local.js +0 -72
  50. package/dist/coding-agent.d.ts +0 -135
  51. package/dist/coding-agent.js +0 -641
  52. package/dist/core/sites.d.ts +0 -33
  53. package/dist/core/sites.js +0 -104
  54. package/dist/durable/web.d.ts +0 -47
  55. package/dist/durable/web.js +0 -41
  56. package/dist/providers/assigned.d.ts +0 -18
  57. package/dist/providers/assigned.js +0 -75
  58. package/dist/recorder/credential.d.ts +0 -9
  59. package/dist/recorder/credential.js +0 -49
  60. package/dist/recorder/follow.d.ts +0 -36
  61. package/dist/recorder/follow.js +0 -163
  62. package/dist/recorder/frames.d.ts +0 -87
  63. package/dist/recorder/frames.js +0 -377
  64. package/dist/recorder/index.d.ts +0 -4
  65. package/dist/recorder/index.js +0 -7
  66. package/dist/recorder/jpeg.d.ts +0 -8
  67. package/dist/recorder/jpeg.js +0 -70
  68. package/dist/recorder/track.d.ts +0 -107
  69. package/dist/recorder/track.js +0 -280
  70. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +0 -15
  71. package/dist/vendor/stagehand-facade/screenshot-transport.js +0 -51
@@ -2,16 +2,14 @@
2
2
  // URL (it carries a signing key) is held here, found again by `retrieve` after a restart.
3
3
  import { createReadStream } from "node:fs";
4
4
  import { isRefusal } from "../core/failures.js";
5
- import { fetchUsage, resolvePrices, searchUsage } from "../core/usage.js";
5
+ import { resolvePrices } from "../core/usage.js";
6
6
  import { cdpCall } from "./cdp-call.js";
7
7
  import { applyBrowserbaseNoProxy, bindConnectDial, installWebSocketWrapper, rewriteConnectUrl, unbindConnectDial } from "./browserbase-net.js";
8
8
  import { directFetch } from "./http.js";
9
9
  import { claimWriter, fileProfileStore, freeWriter, isWriter, noteWriter } from "./profiles.js";
10
- import { accountKey, assertTag, browserbaseHoldings, defaultSleep, DEFAULT_CONFIRM, extensionArchive, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
10
+ import { accountKey, assertTag, browserbaseHoldings, defaultSleep, DEFAULT_CONFIRM, extensionArchive, nonEmpty, releaseAndConfirm, tagValue, uploadOnce } from "./shared.js";
11
11
  export { rewriteConnectUrl, browserbaseNoProxyHosts, applyBrowserbaseNoProxy } from "./browserbase-net.js";
12
12
  export { fileProfileStore, memoryProfileStore } from "./profiles.js";
13
- export const SEARCH_QUERY_MAX = 200;
14
- export const SEARCH_RESULTS_MAX = 25;
15
13
  /** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
16
14
  export const setDownloadBehavior = (url, options = {}) => cdpCall(url, "Browser.setDownloadBehavior", { behavior: "allow", downloadPath: options.downloadPath ?? "downloads", eventsEnabled: true }, options.timeoutMs);
17
15
  const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, profiles: true, extension: "uploaded-per-launch", settings: { proxies: true, verified: true, geolocation: true, region: true, context: true },
@@ -292,28 +290,5 @@ export function browserbaseProvider(options = {}) {
292
290
  return response.body;
293
291
  },
294
292
  },
295
- async fetch(request, signal) {
296
- signal?.throwIfAborted();
297
- const result = await untilAborted((async () => (await client()).fetchAPI.create({ url: request.url, proxies: request.proxies, allowRedirects: true, format: request.format }, { signal }))(), signal);
298
- // The Fetch API reports no final URL.
299
- 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) };
300
- },
301
- async search(request, signal) {
302
- signal?.throwIfAborted();
303
- // The facade validates strictly (query 1 to 200 characters, 1 to 25 results): clamp, so a long query degrades and
304
- // never throws.
305
- const query = request.query.slice(0, SEARCH_QUERY_MAX);
306
- const numResults = Math.max(1, Math.min(SEARCH_RESULTS_MAX, Math.floor(request.n) || 10));
307
- const result = await untilAborted((async () => (await client()).search.web({ query, numResults }, { signal }))(), signal);
308
- const rows = Array.isArray(result?.results) ? result.results : Array.isArray(result) ? result : [];
309
- 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) };
310
- },
311
293
  };
312
294
  }
313
- function contentText(content) {
314
- if (typeof content === "string")
315
- return content;
316
- if (Array.isArray(content))
317
- return content.map((c) => (typeof c === "string" ? c : typeof c?.text === "string" ? c.text : JSON.stringify(c))).join("\n");
318
- return content && typeof content === "object" ? JSON.stringify(content) : "";
319
- }
@@ -1,3 +1,6 @@
1
+ /** The local Chrome to start: the one `PI_BROWSER_CHROME` or `CHROME_PATH` names when it exists, else the first install found
2
+ * on PATH or at a fixed place; null when there is none. */
3
+ export declare function findChrome(env?: NodeJS.ProcessEnv, exists?: (file: string) => boolean): string | null;
1
4
  /** The directory Stagehand loads its extension from in a local Chrome (`Extensions.loadUnpacked`), resolved as Stagehand does. */
2
5
  export declare function extensionDirectory(): string;
3
6
  /** The Origin the extension's own DevTools socket carries. Chrome names an unpacked extension by the SHA-256 of its real path: the
@@ -1,12 +1,23 @@
1
1
  // The arguments the cdp provider starts a local Chrome with, in one place, so a host that starts its own Chrome for Stagehand can
2
- // take the same list rather than copy it.
2
+ // take the same list rather than copy it; and where that Chrome is installed (findChrome).
3
3
  import { createHash } from "node:crypto";
4
- import { realpathSync } from "node:fs";
4
+ import { existsSync, realpathSync } from "node:fs";
5
5
  import path from "node:path";
6
6
  import { fileURLToPath } from "node:url";
7
7
  import { BrowserFailureError } from "../core/custody.js";
8
8
  import { browserFailure } from "../core/failures.js";
9
9
  import { nonEmpty } from "./shared.js";
10
+ const LINUX_NAMES = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"];
11
+ /** The local Chrome to start: the one `PI_BROWSER_CHROME` or `CHROME_PATH` names when it exists, else the first install found
12
+ * on PATH or at a fixed place; null when there is none. */
13
+ export function findChrome(env = process.env, exists = existsSync) {
14
+ for (const named of [env.PI_BROWSER_CHROME, env.CHROME_PATH])
15
+ if (named && exists(named))
16
+ return named;
17
+ const onPath = (env.PATH ?? "").split(path.delimiter).filter(Boolean).flatMap((dir) => LINUX_NAMES.map((name) => path.join(dir, name)));
18
+ const fixed = ["/opt/google/chrome/chrome", "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"];
19
+ return [...onPath, ...fixed].find((file) => exists(file)) ?? null;
20
+ }
10
21
  /** Stagehand 4.1.0's DEFAULT_CHROME_FLAGS (packages/sdk-ts/src/browser/localBrowser.ts, MIT, see NOTICE), less its
11
22
  * `--remote-allow-origins=*`, which the launch below narrows to the extension's own Origin. Without them
12
23
  * Stagehand.create takes about 24 s on a local Chrome instead of under 100 ms. */
@@ -1,20 +1,6 @@
1
1
  import { EventEmitter } from "node:events";
2
- import type { AttachTarget, BrowserProvider, ProviderCaps, RemoteFile, SearchResult } from "../core/host.js";
2
+ import type { AttachTarget, BrowserProvider, ProviderCaps, RemoteFile } from "../core/host.js";
3
3
  import { type Sentinels } from "./sentinels.js";
4
- export type FakeFetchByFormat = {
5
- markdown?: {
6
- contentType: string;
7
- content: string;
8
- } | {
9
- status: number;
10
- };
11
- raw?: {
12
- contentType: string;
13
- content: string;
14
- } | {
15
- status: number;
16
- };
17
- };
18
4
  /** A vendor SDK's failure: the HTTP status is on the error, never inside the text. */
19
5
  export declare class FakeProviderError extends Error {
20
6
  readonly status: number;
@@ -63,9 +49,6 @@ export type FakeBackendOptions = {
63
49
  caps?: Partial<ProviderCaps>;
64
50
  start?: string;
65
51
  pages?: Record<string, FixturePage>;
66
- /** A URL not listed is a 404; an object answers markdown and raw apart. */
67
- fetches?: Record<string, string | FakeFetchByFormat>;
68
- search?: SearchResult["results"];
69
52
  /** Every ledger row is also appended here as JSONL, so a killed process leaves its calls behind. */
70
53
  logFile?: string;
71
54
  connections?: BrokerConnection[];
@@ -128,7 +111,7 @@ export declare class FakeBackend {
128
111
  private delays;
129
112
  private peak;
130
113
  private echoOn;
131
- readonly opts: Required<Pick<FakeBackendOptions, "start" | "fetches" | "search" | "connections" | "downloads">> & FakeBackendOptions;
114
+ readonly opts: Required<Pick<FakeBackendOptions, "start" | "connections" | "downloads">> & FakeBackendOptions;
132
115
  constructor(options?: FakeBackendOptions);
133
116
  /** The next call of `op` is applied and recorded, then never answered. */
134
117
  hold(op: string): void;
@@ -155,8 +138,6 @@ export declare class FakeBackend {
155
138
  attaches: number;
156
139
  releases: number;
157
140
  releaseNoops: number;
158
- fetches: number;
159
- searches: number;
160
141
  dispatches: number;
161
142
  reads: number;
162
143
  peakLive: number;
@@ -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. */
@@ -0,0 +1,106 @@
1
+ import type { CDP } from "./cdp.js";
2
+ import type { Page } from "./page.js";
3
+ type Probe = {
4
+ idle: number;
5
+ ready: string;
6
+ url: string;
7
+ title: string;
8
+ n: number;
9
+ doc: number;
10
+ };
11
+ /** A snapshot id is stale or never was: the driver turns it into the package's own words. */
12
+ export declare class UnknownIdError extends Error {
13
+ readonly id: string;
14
+ constructor(id: string);
15
+ }
16
+ /** Snapshot and id-based actions on Chrome's accessibility tree. */
17
+ export declare class AxHelpers {
18
+ private page;
19
+ private browser;
20
+ constructor(page: () => Page, browser: () => CDP);
21
+ private inflight;
22
+ private lastNet;
23
+ private tracked;
24
+ private dialogs;
25
+ private observing;
26
+ /** Role and name of every backend id in the last snapshot: marks new ids and names targets in action lines. */
27
+ private last;
28
+ /** The last snapshot's displayed ids, each to its backend node id; none before the first snapshot or after forget(). */
29
+ private ids;
30
+ /** The document and address the last snapshot was taken on. */
31
+ taken: {
32
+ doc: number;
33
+ url: string;
34
+ } | undefined;
35
+ /** Track in-flight requests per page session from CDP Network events (no page patching), and accept dialogs. */
36
+ private trackNetwork;
37
+ /** URL, title, document identity, a counter of DOM mutations (style aside) and form input/change events. */
38
+ probe(page?: Page): Promise<Probe>;
39
+ /**
40
+ * Event-based wait, never a fixed sleep: document parsed, no fresh in-flight requests (older than 1.5 s are treated as
41
+ * long-poll/analytics), and no DOM mutation for quietMs. Bounded by capMs.
42
+ */
43
+ settle(options?: {
44
+ capMs?: number;
45
+ quietMs?: number;
46
+ page?: Page;
47
+ since?: number;
48
+ }): Promise<{
49
+ why: string;
50
+ pending: number;
51
+ ms: number;
52
+ probe: Probe;
53
+ } | {
54
+ why: string;
55
+ pending: number;
56
+ ms: number;
57
+ probe?: undefined;
58
+ }>;
59
+ private flushDialogs;
60
+ /**
61
+ * Text actually shown, lowercased with whitespace collapsed. The AX tree keeps opacity:0 text (pre-rendered success
62
+ * banners), which agents then report as success; checkVisibility with checkOpacity drops it.
63
+ */
64
+ private visibleText;
65
+ /**
66
+ * AX trees of the main frame and, with `frames`, of every same-process child frame. A child frame whose tree cannot be
67
+ * read (a cross-origin frame Chrome runs in another process) is returned as `unread`, never dropped unsaid.
68
+ */
69
+ private capture;
70
+ /** The page as one list in page order: `[frame-node] role "name" = value states`, ## headings and visible text. */
71
+ snapshot(options?: {
72
+ includeIframes?: boolean;
73
+ max?: number;
74
+ }): Promise<string>;
75
+ /** Drops the snapshot's ids: an action by any of them then fails as a stale snapshot. */
76
+ forget(): void;
77
+ /** Whether there is a snapshot to act on. */
78
+ get hydrated(): boolean;
79
+ /** The backend node id a displayed id names in the latest snapshot; throws UnknownIdError for any other. */
80
+ nodeOf(id: string): number;
81
+ private onNode;
82
+ private describe;
83
+ /** Scroll into view and return a clickable, unobstructed center point, or throw a precise reason. */
84
+ point(page: Page, id: number, editableCover?: boolean): Promise<{
85
+ x: number;
86
+ y: number;
87
+ covered: boolean;
88
+ }>;
89
+ /** Runs one action on a displayed id and returns one line: navigated to <url> / page changed / no change. */
90
+ private act;
91
+ change(before: Probe | undefined, after?: Probe): Promise<string>;
92
+ click(display: string): Promise<string>;
93
+ hover(display: string): Promise<string>;
94
+ /** Picks a native select's option by its label or value, or each of several in a multiple select. */
95
+ select(display: string, values: string | string[]): Promise<string>;
96
+ /** Replaces a field's text (Pi's type): a native date or time input by its value, any other by click, select-all and keys. */
97
+ fill(display: string, text: string): Promise<string>;
98
+ /** Types at the end of a field's whole text, as keys would; `delayMs` between characters, as paced typing asks. */
99
+ type(display: string, text: string, delayMs?: number): Promise<string>;
100
+ /** Clicks the element, then presses a key on it: a name (Enter, Tab, Escape, ArrowDown, ...) or one character, each
101
+ * with any of the modifiers Shift, Control (Ctrl), Alt and Meta (Command, Cmd) before it: Shift+Tab, Control+A. */
102
+ press(display: string, key: string): Promise<string>;
103
+ private enter;
104
+ private key;
105
+ }
106
+ export {};