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

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 (49) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/NOTICE +30 -0
  3. package/README.md +28 -178
  4. package/dist/core/contract.js +14 -5
  5. package/dist/core/custody.d.ts +6 -0
  6. package/dist/core/custody.js +6 -0
  7. package/dist/core/driving-guard.js +17 -2
  8. package/dist/core/host.d.ts +2 -2
  9. package/dist/core/tools.d.ts +9 -0
  10. package/dist/driver/cdp.d.ts +6 -0
  11. package/dist/driver/cdp.js +245 -0
  12. package/dist/driver/page-driver.js +29 -3
  13. package/dist/durable/store.js +13 -4
  14. package/dist/durable.d.ts +1 -0
  15. package/dist/durable.js +1 -0
  16. package/dist/live-view/provider.d.ts +2 -2
  17. package/dist/live-view/provider.js +2 -2
  18. package/dist/live-view/server.d.ts +1 -1
  19. package/dist/providers/chrome-args.d.ts +3 -0
  20. package/dist/providers/chrome-args.js +13 -2
  21. package/dist/vendor/browser-use-pi/ax.d.ts +106 -0
  22. package/dist/vendor/browser-use-pi/ax.js +642 -0
  23. package/dist/vendor/browser-use-pi/cdp.d.ts +19 -0
  24. package/dist/vendor/browser-use-pi/cdp.js +106 -0
  25. package/dist/vendor/browser-use-pi/page.d.ts +38 -0
  26. package/dist/vendor/browser-use-pi/page.js +112 -0
  27. package/package.json +6 -24
  28. package/src/vendor/browser-use-pi/UPSTREAM.json +25 -0
  29. package/src/vendor/stagehand-facade/UPSTREAM.json +0 -4
  30. package/dist/coding-agent-local.d.ts +0 -12
  31. package/dist/coding-agent-local.js +0 -72
  32. package/dist/coding-agent.d.ts +0 -135
  33. package/dist/coding-agent.js +0 -641
  34. package/dist/providers/assigned.d.ts +0 -18
  35. package/dist/providers/assigned.js +0 -75
  36. package/dist/recorder/credential.d.ts +0 -9
  37. package/dist/recorder/credential.js +0 -49
  38. package/dist/recorder/follow.d.ts +0 -36
  39. package/dist/recorder/follow.js +0 -163
  40. package/dist/recorder/frames.d.ts +0 -87
  41. package/dist/recorder/frames.js +0 -377
  42. package/dist/recorder/index.d.ts +0 -4
  43. package/dist/recorder/index.js +0 -7
  44. package/dist/recorder/jpeg.d.ts +0 -8
  45. package/dist/recorder/jpeg.js +0 -70
  46. package/dist/recorder/track.d.ts +0 -107
  47. package/dist/recorder/track.js +0 -280
  48. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +0 -15
  49. package/dist/vendor/stagehand-facade/screenshot-transport.js +0 -51
@@ -1,641 +0,0 @@
1
- import { randomUUID } from "node:crypto";
2
- import { existsSync } from "node:fs";
3
- import { mkdtemp, rm } from "node:fs/promises";
4
- import os from "node:os";
5
- import path from "node:path";
6
- import { setTimeout as sleep } from "node:timers/promises";
7
- import { BROWSER_TOOLS, WEB_TOOLS, browserSection, browserToolsFor, listedFor } from "./core/contract.js";
8
- import { BrowserFailureError, closeDriver, custodyTools, FIXED_SESSION_RELAUNCH, fenced, HANDED_BACK, loadedNoPage, moveRecord, newSessionRecord, notices, NOTHING_TO_HOLD, navigationRefusal, profileRefusal, relaunchRefusal, sessionSpec, waitingForHuman, backoffMs, NO_HANDOFF, } from "./core/custody.js";
9
- import { browserFailure, classifyBrowserError } from "./core/failures.js";
10
- import { workspaceFiles } from "./core/files.js";
11
- import { leaseTag } from "./core/lease.js";
12
- import { createRedactor, hostLiveView, redactContent, redactDeep, scrubPageUrl } from "./core/redact.js";
13
- import { useWebsite, useWebsiteContract } from "./core/sites.js";
14
- import { drivingGuarded } from "./core/driving-guard.js";
15
- import { drivingGates, keptFor, keptReason, personOn, rearmWhenLeft } from "./core/driving.js";
16
- import { captureFor, planRestore, untilQuiet, vaultRuntime } from "./vault-session.js";
17
- import { pageTools } from "./core/tools.js";
18
- import { CREATE_DEADLINE_MS, DEFAULT_BROWSER_POLICY, idleTracker, keyedSerializer, oneAtATime, providerKeyValues } from "./core/session-control.js";
19
- import { createWebTools } from "./core/web.js";
20
- import { fileEvidenceSink, findChrome, httpBackup } from "./coding-agent-local.js";
21
- // The providers' own rule for a key that is set (trimmed, not empty), so a key they would refuse is refused here as `auth`, first.
22
- import { nonEmpty } from "./providers/shared.js";
23
- export { findChrome } from "./coding-agent-local.js";
24
- export const SESSION_ENTRY = "browser.session";
25
- const CONVERSATION = 1;
26
- const BROWSER_FLAGS = ["browser-provider", "browser-endpoint", "browser-chrome", "browser-headed", "browser-no-sandbox"];
27
- const UNHELD_ACTIONS = browserFailure("browser_unavailable", "This run's action policy holds the requests the browser would send (deny or ask), and the pi coding agent cannot hold them, so no browser is started. web_fetch still reads pages. To browse, the person sets the policy's `actions` to \"allow\" (or leaves it out), or runs the browser through the pi-durable adapter, which holds requests.");
28
- /** No browser can be had: a missing key, a bad flag or no Chrome. Unavailable unless the cause is a credential (`auth`) or a refusal. */
29
- const noBrowser = (message, code = "browser_unavailable") => new BrowserFailureError(browserFailure(code, message));
30
- const now = () => new Date().toISOString();
31
- /** The provider released the browser and could not remove a directory it left (`ProfileNotRemovedError`'s code, read without importing the provider). */
32
- const directoryLeft = (error) => error?.code === "profile_not_removed";
33
- export class LocalCustody {
34
- d;
35
- live = null;
36
- /** Browsers that are gone whose directories are not: each is released again as cleanup, never kept as the live session. */
37
- leftovers = [];
38
- /** The last session this custody released, so a release asked after it can say how and when it ended. */
39
- lastReleased = null;
40
- seq = 0;
41
- notice = null;
42
- /** The session an idle release ended, told with its notice and named while its replacement has loaded no page; any
43
- * other release ends it, and a failed launch never touches it. */
44
- replacedBy = null;
45
- queue = keyedSerializer();
46
- idle;
47
- /** The poll of a session the idle timer kept for a person (#1098): stopped when the session is released or closed. */
48
- leaving = null;
49
- constructor(d) {
50
- this.d = d;
51
- this.idle = idleTracker({ idleMs: d.config.policy.idleReleaseS * 1000, onIdle: (key, fired) => void this.serial(async () => {
52
- const live = this.live;
53
- if (!this.idle.isCurrent(key, fired) || !live || live.record.state === "held")
54
- return;
55
- // A person driving or watching the session through the live view keeps it (#1098); it is released one idle window
56
- // after they leave.
57
- const gate = personOn(d.gates ?? drivingGates, live.record.tag);
58
- if (gate) {
59
- this.leaving?.();
60
- this.leaving = rearmWhenLeft(gate, () => this.live === live, () => { this.leaving = null; this.idle.activity(key, 0); }, d.config.policy.idleReleaseS * 1000);
61
- return;
62
- }
63
- await this.finish(live, "idle").catch(() => undefined);
64
- // Whatever the release answered, a session that is over is told to the next call, which opens a fresh browser.
65
- if (this.live !== live) {
66
- this.notice = notices.released("idle", live.record.lastUrl, d.config.policy.idleReleaseS);
67
- this.replacedBy = { reason: "idle", at: live.record.endedAt, lastUrl: live.record.lastUrl };
68
- }
69
- }) });
70
- }
71
- serial(run) {
72
- return this.queue.run(this.d.config.label, run);
73
- }
74
- save(record) {
75
- this.d.keep(SESSION_ENTRY, { tag: record.tag, resourceId: record.resourceId, state: record.state, reason: record.releaseReason, ...(record.endedAt ? { endedAt: record.endedAt } : {}) });
76
- }
77
- failure(error, signal) {
78
- return error instanceof BrowserFailureError ? error : new BrowserFailureError(classifyBrowserError(error, false, { aborted: signal?.aborted === true, redact: this.d.redact }));
79
- }
80
- /** Release every session the branch's entries leave open (a browser a crashed process left running); never adopted. */
81
- async releaseOrphans(entries) {
82
- const last = new Map();
83
- for (const e of entries)
84
- if (e.type === "custom" && e.customType === SESSION_ENTRY && e.data?.tag)
85
- last.set(e.data.tag, e.data);
86
- const open = [...last.values()].filter((entry) => entry.state !== "released");
87
- if (!open.length)
88
- return;
89
- const provider = await this.d.provider();
90
- for (const { tag, resourceId } of open) {
91
- const refs = resourceId ? [{ id: resourceId, tag }] : await provider.findByTag(tag).catch(() => null);
92
- if (!refs)
93
- continue;
94
- let released = true;
95
- for (const ref of refs)
96
- await provider.release(ref).catch(() => { released = false; });
97
- if (released)
98
- this.d.keep(SESSION_ENTRY, { tag, resourceId, state: "released", reason: "lost" });
99
- }
100
- }
101
- async attached(live, bound, afterAttach = null) {
102
- const provider = await this.d.provider();
103
- const signal = AbortSignal.any([this.d.signal, AbortSignal.timeout(CREATE_DEADLINE_MS), ...(bound ? [bound] : [])]);
104
- try {
105
- if (!live.driver) {
106
- const target = await provider.attach(live.ref, signal);
107
- // A kept sign-in is put back before the driver, and so before any page, attaches.
108
- if (afterAttach)
109
- await afterAttach(target);
110
- live.driver = await this.d.driver(target, signal, { batchTimeoutMs: this.d.config.policy.batchTimeoutMs });
111
- }
112
- }
113
- catch (error) {
114
- throw this.failure(error, signal);
115
- }
116
- const notice = this.notice;
117
- this.notice = null;
118
- const fence = live.record.fence ?? 0;
119
- const replaced = this.replacedBy && loadedNoPage(live.record) ? this.replacedBy : null;
120
- return { driver: fenced(live.driver, fence, () => live.mark), tag: live.record.tag, sessionId: live.ref.id, record: live.record, notice, interrupted: null, recorded: !!provider.recordings, effects: null, fence, downloads: provider.downloads ?? null, replaced };
121
- }
122
- async launch(overrides) {
123
- // This host has no request observer, so a policy that holds requests (deny, ask) would be dropped and every request sent:
124
- // it starts no browser instead, as the durable adapter refuses to browse without its observer.
125
- if (this.d.config.policy.actions && this.d.config.policy.actions !== "allow")
126
- throw new BrowserFailureError(UNHELD_ACTIONS);
127
- const provider = await this.d.provider();
128
- const tag = leaseTag("pib", this.d.config.run, randomUUID().slice(0, 8), ++this.seq);
129
- const spec = sessionSpec(this.d.config, tag, overrides);
130
- const unsupported = profileRefusal(spec, provider.caps) ?? navigationRefusal(spec, provider);
131
- if (unsupported)
132
- throw new BrowserFailureError(unsupported);
133
- // The vault may name a context or profile for the provider; the record is made from the spec without it, so no context id is saved to the session file.
134
- const plan = await planRestore(this.d.vault ?? null, this.d.vaultTarget, provider, spec);
135
- const record = newSessionRecord({ plane: "browser", tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
136
- this.save(record);
137
- const signal = AbortSignal.any([this.d.signal, AbortSignal.timeout(CREATE_DEADLINE_MS)]);
138
- let live = null;
139
- try {
140
- const ref = await provider.create(plan.spec, signal);
141
- Object.assign(record, { state: "live", resourceId: ref.id });
142
- this.save(record);
143
- live = { record, ref, driver: null, ...(this.d.vault && this.d.vaultTarget ? { capture: captureFor(this.d.vault, this.d.vaultTarget, provider, ref, { vaulted: plan.vaulted, ...(plan.holdBack ? { holdBack: plan.holdBack } : {}), gate: () => personOn(this.d.gates ?? drivingGates, tag) }) } : {}) };
144
- const attached = await this.attached(live, undefined, plan.afterAttach);
145
- this.live = live;
146
- // A context made for this session is given to the vault now, so a restart that loses the provider's memory of it still finds it.
147
- if (plan.fresh)
148
- await live.capture?.();
149
- return attached;
150
- }
151
- catch (error) {
152
- // A session the host assigned is the task's only one: an attach that failed keeps it live, and the next call attaches it again.
153
- if (live && provider.caps.fixedSession) {
154
- this.live = live;
155
- throw this.failure(error, signal);
156
- }
157
- // A create that threw may still have made a browser: with no ref, look it up by its tag. The record ends released
158
- // only when every release is confirmed; otherwise it stays open for the next start to retry.
159
- const refs = live ? [live.ref] : await provider.findByTag(tag).catch(() => null);
160
- let released = refs !== null;
161
- for (const ref of refs ?? [])
162
- if (!(await provider.release(ref).then(() => true, () => false)))
163
- released = false;
164
- if (released) {
165
- Object.assign(record, { state: "released", releaseReason: "create_failed", endedAt: now() });
166
- this.lastReleased = record;
167
- this.save(record);
168
- }
169
- throw this.failure(error, signal);
170
- }
171
- }
172
- /** A release the provider fails leaves the session held, so a later release, the shutdown or the next start can retry it. The exception is a
173
- * release that says the browser is gone and only a directory is left (`profile_not_removed`): that session is over (it is never the live
174
- * one again), its record stays open for the directory, which is released again by the next release, the shutdown or the next start; the
175
- * caller is still told what is left. */
176
- /** The vault capture of a session while its browser exists; skipped while a person is driving it. Never throws. */
177
- async captured(live, wait = false) {
178
- if (!live.capture)
179
- return;
180
- const gate = personOn(this.d.gates ?? drivingGates, live.record.tag);
181
- // At a handoff's end the person has just let go: their last input is within the driving window, so it is waited out (bounded) before the browser is read.
182
- if (!(wait ? await untilQuiet(gate) : !gate || keptFor(gate) !== "person_driving"))
183
- return;
184
- await live.capture();
185
- }
186
- async finish(live, reason) {
187
- // A released session's poll (#1098) ends with it, whatever released it.
188
- this.leaving?.();
189
- this.leaving = null;
190
- if (reason !== "idle")
191
- this.replacedBy = null;
192
- await this.captured(live);
193
- await this.sweepLeftovers();
194
- // A close that never comes back never holds up the provider's release (closeDriver waits DRIVER_CLOSE_MS at most).
195
- if (live.driver)
196
- await closeDriver(live.driver);
197
- try {
198
- await (await this.d.provider()).release(live.ref);
199
- }
200
- catch (error) {
201
- if (!directoryLeft(error))
202
- throw this.failure(error);
203
- if (this.live === live)
204
- this.live = null;
205
- live.driver = null;
206
- Object.assign(live.record, { state: "releasing", releaseReason: reason });
207
- this.lastReleased = live.record;
208
- this.save(live.record);
209
- this.leftovers.push(live);
210
- throw this.failure(error);
211
- }
212
- if (this.live === live)
213
- this.live = null;
214
- Object.assign(live.record, { state: "released", releaseReason: reason, endedAt: now() });
215
- this.lastReleased = live.record;
216
- this.save(live.record);
217
- }
218
- async refuseHeld() {
219
- if (this.live?.record.state === "held" && !(await this.retireEnded()))
220
- throw new BrowserFailureError(waitingForHuman(this.live.record.handoff));
221
- }
222
- /** Releases again each browser that is gone and whose directory was left; one that still cannot be removed stays for the next time, and the
223
- * last such failure is returned for a caller that was asked to release. */
224
- async sweepLeftovers() {
225
- let stillLeft = null;
226
- const pending = this.leftovers.splice(0);
227
- for (const live of pending) {
228
- try {
229
- await (await this.d.provider()).release(live.ref);
230
- }
231
- catch (error) {
232
- this.leftovers.push(live);
233
- stillLeft = error;
234
- continue;
235
- }
236
- Object.assign(live.record, { state: "released", endedAt: now() });
237
- this.save(live.record);
238
- }
239
- return stillLeft;
240
- }
241
- async retireEnded() {
242
- const live = this.live;
243
- if (!live || !["gone", "stopped"].includes(await (await this.d.provider()).status(live.ref).catch(() => "running")))
244
- return false;
245
- this.notice = notices.ended(live.record.lastUrl);
246
- await this.finish(live, "ended").catch(() => undefined);
247
- return true;
248
- }
249
- session(signal) {
250
- return this.serial(async () => {
251
- await this.refuseHeld();
252
- await this.retireEnded();
253
- return this.live ? this.attached(this.live, signal) : this.launch({});
254
- });
255
- }
256
- async current() { return this.live?.record.tag ?? null; }
257
- relaunch(overrides) {
258
- return this.serial(async () => {
259
- // Checked first, as the durable adapter does: a geolocation with proxies off is refused, never dropped in a new session.
260
- const refusal = relaunchRefusal(this.d.config.policy, overrides);
261
- if (refusal)
262
- throw new BrowserFailureError(refusal);
263
- await this.refuseHeld();
264
- // A session the host assigned is the only one: refused before anything is released.
265
- if ((await this.d.provider()).caps.fixedSession)
266
- throw new BrowserFailureError(FIXED_SESSION_RELAUNCH);
267
- // A browser that is gone with only its directory left is over: the new one opens, and the directory is retried later.
268
- if (this.live)
269
- await this.finish(this.live, "relaunch").catch((error) => { if (this.live)
270
- throw error; });
271
- return this.launch(overrides);
272
- });
273
- }
274
- release() {
275
- return this.serial(async () => {
276
- const live = this.live;
277
- if (live) {
278
- await this.finish(live, "tool");
279
- return { released: true, sessionId: live.ref.id };
280
- }
281
- const stillLeft = await this.sweepLeftovers(); // no browser, but a directory an earlier release left
282
- if (stillLeft)
283
- throw this.failure(stillLeft);
284
- const last = this.lastReleased;
285
- return last ? { released: false, sessionId: last.resourceId, ended: { reason: last.releaseReason ?? "tool", at: last.endedAt } } : { released: false, sessionId: null };
286
- });
287
- }
288
- /** Releases without failing the caller; idempotent. */
289
- close(reason) {
290
- return this.serial(async () => {
291
- this.idle.cancel(this.d.config.label);
292
- this.leaving?.();
293
- this.leaving = null;
294
- if (this.live)
295
- await this.finish(this.live, reason).catch(() => undefined);
296
- await this.sweepLeftovers();
297
- });
298
- }
299
- hold(requestId) {
300
- return this.serial(async () => {
301
- const live = this.live;
302
- if (live?.record.state === "held" && live.record.handoff !== requestId)
303
- throw new BrowserFailureError(waitingForHuman(live.record.handoff));
304
- if (!live)
305
- throw new BrowserFailureError(NOTHING_TO_HOLD);
306
- if (live.record.state === "live") {
307
- moveRecord(live.record, { state: "held", handoff: requestId, at: now() });
308
- live.mark = { fence: live.record.fence, failure: waitingForHuman(requestId) };
309
- this.save(live.record);
310
- const driver = live.driver;
311
- live.driver = null;
312
- if (driver)
313
- await closeDriver(driver);
314
- }
315
- return { tag: live.record.tag, sessionId: live.ref.id };
316
- });
317
- }
318
- resume(notice) {
319
- return this.serial(async () => {
320
- const live = this.live;
321
- if (live?.record.state !== "held")
322
- return;
323
- moveRecord(live.record, { state: "live", at: now() });
324
- live.mark = { fence: live.record.fence, failure: HANDED_BACK };
325
- this.save(live.record);
326
- if (notice)
327
- this.notice = [this.notice, notice].filter(Boolean).join(" ");
328
- });
329
- }
330
- async dispatching() { }
331
- async journal() { }
332
- async mark() { }
333
- async settle() { }
334
- async navigated(url) { if (this.live)
335
- this.live.record.lastUrl = scrubPageUrl(url, this.d.redact); }
336
- ended() {
337
- return this.serial(() => this.retireEnded());
338
- }
339
- unreachable() {
340
- return this.serial(async () => {
341
- const live = this.live;
342
- if (!live)
343
- return { released: false, lastUrl: null };
344
- const lastUrl = live.record.lastUrl;
345
- const kept = keptReason(live.record, this.d.gates ?? drivingGates);
346
- if (kept)
347
- return { released: false, lastUrl, kept };
348
- await this.finish(live, "lost").catch(() => undefined);
349
- if (this.live === live)
350
- return { released: false, lastUrl }; // the release failed, so the session is kept to retry it
351
- this.notice = notices.unreachable(lastUrl);
352
- this.replacedBy = { reason: "lost", at: live.record.endedAt, lastUrl };
353
- return { released: true, lastUrl };
354
- });
355
- }
356
- /** Blocks on the port until the person answers or the call is aborted; the session comes back either way. */
357
- async handoff(ask, signal) {
358
- const port = this.d.handoff;
359
- if (!port)
360
- throw new BrowserFailureError(NO_HANDOFF);
361
- const { tag, sessionId } = await this.hold(ask.requestId);
362
- const stop = signal ? AbortSignal.any([this.d.signal, signal]) : this.d.signal;
363
- try {
364
- const provider = await this.d.provider();
365
- const view = provider.liveView ? await provider.liveView({ id: sessionId, tag }).catch(() => null) : null;
366
- const liveView = view && hostLiveView(view, this.d.redact);
367
- const asked = await port.request({ requestId: ask.requestId, sessionTag: tag, sessionId, liveView, instruction: ask.instruction, completionCondition: ask.completionCondition }, stop);
368
- if ("refused" in asked)
369
- return asked;
370
- for (let attempt = 0;; attempt += 1) {
371
- const answer = await port.outcome(asked.interactionId, stop).catch((error) => { if (stop.aborted)
372
- throw error; return "pending"; });
373
- if (answer !== "pending") {
374
- // A sign-in just happened and the person has handed back: kept now, so a crash after it does not lose it.
375
- await this.resume(null);
376
- if (this.live)
377
- await this.captured(this.live, true);
378
- return typeof answer === "string" ? { outcome: answer } : answer;
379
- }
380
- await sleep(backoffMs(attempt), undefined, { signal: stop });
381
- }
382
- }
383
- catch (error) {
384
- throw this.failure(error, stop);
385
- }
386
- finally {
387
- await this.resume(null);
388
- }
389
- }
390
- dropped() {
391
- return this.serial(async () => {
392
- const driver = this.live?.driver;
393
- if (!driver || !this.live)
394
- return;
395
- this.live.driver = null;
396
- await closeDriver(driver);
397
- });
398
- }
399
- /** A session left idle is released after the policy's idle spell. */
400
- activity(delta) {
401
- this.idle.activity(this.d.config.label, delta);
402
- }
403
- }
404
- const flagOf = (pi, name, fallback) => {
405
- const value = pi.getFlag(name);
406
- return typeof value === "string" && value ? value : fallback;
407
- };
408
- async function chooseProvider(pi, { options, env }, profiles) {
409
- if (options.provider)
410
- return typeof options.provider === "function" ? options.provider() : options.provider;
411
- const kind = flagOf(pi, "browser-provider", env.PI_BROWSER_PROVIDER ?? "cdp");
412
- if (kind === "browserbase") {
413
- if (!(nonEmpty(env.BROWSERBASE_API_KEY) || nonEmpty(env.BB_API_KEY)))
414
- throw noBrowser("The browserbase provider needs BROWSERBASE_API_KEY in the environment; none is set. Use the default local browser, or ask the person to set the key.", "auth");
415
- return (await import("./providers/browserbase.js")).browserbaseProvider({ env });
416
- }
417
- if (kind === "kernel") {
418
- if (!nonEmpty(env.KERNEL_API_KEY))
419
- throw noBrowser("The kernel provider needs KERNEL_API_KEY in the environment; none is set. Use the default local browser, or ask the person to set the key.", "auth");
420
- return (await import("./providers/kernel.js")).kernelProvider({ env, stealth: env.PI_BROWSER_STEALTH === "1" });
421
- }
422
- if (kind !== "cdp")
423
- throw noBrowser(`--browser-provider is "${kind}"; it is cdp, browserbase or kernel.`, "refused");
424
- const { cdpProvider } = await import("./providers/cdp.js");
425
- const endpoint = flagOf(pi, "browser-endpoint", env.PI_BROWSER_ENDPOINT);
426
- if (endpoint)
427
- return cdpProvider({ endpoint });
428
- // A Chrome the person named is used or refused by name, never swapped; only when none is named are the usual
429
- // places searched.
430
- const named = flagOf(pi, "browser-chrome") ?? (env.PI_BROWSER_CHROME || undefined);
431
- if (named && !existsSync(named))
432
- throw noBrowser(`The Chrome named by --browser-chrome or PI_BROWSER_CHROME, ${named}, does not exist. Ask the person for the right path.`);
433
- const executablePath = named ?? findChrome(env);
434
- if (!executablePath)
435
- throw noBrowser("No Chrome or Chromium was found on this machine. Ask the person to install one, or to set PI_BROWSER_CHROME (or pass --browser-chrome) to its path, or --browser-endpoint to a running one.");
436
- const headed = pi.getFlag("browser-headed") === true || env.PI_BROWSER_HEADED === "1";
437
- // Absent the flag, the provider reads PI_BROWSER_NO_SANDBOX itself.
438
- return cdpProvider({ chrome: { executablePath, profileRoot: await profiles.root(), headless: !headed, ...(pi.getFlag("browser-no-sandbox") === true ? { sandbox: false } : {}) } });
439
- }
440
- async function openRuntime(pi, settings, ctx, reason, listSites) {
441
- const { options, env, policy, impls } = settings;
442
- const closing = new AbortController();
443
- // Secrets the package itself comes to hold (a vault's provider context id): registered as they are seen, so no output can carry one.
444
- const tracked = new Set();
445
- const keyValues = () => [...providerKeyValues(env), ...tracked];
446
- const redact = createRedactor(keyValues);
447
- const vault = vaultRuntime(options, (secret) => { tracked.add(secret); }, (message) => process.emitWarning(`pi-browser: ${redact(message)}`, { code: "PI_BROWSER_VAULT" }));
448
- let root = null;
449
- const profiles = { root: () => (root ??= mkdtemp(path.join(os.tmpdir(), "pi-browser-"))) };
450
- let chosen = null;
451
- const provider = () => (chosen ??= chooseProvider(pi, settings, profiles));
452
- const evidence = fileEvidenceSink(path.join(ctx.cwd, ".pi", "browser", "evidence"), ctx.cwd);
453
- const sessionId = ctx.sessionManager.getSessionId?.() ?? randomUUID();
454
- const config = { label: "browser", run: sessionId, policy };
455
- const driver = options.driver ?? (async (target, signal, driverOptions) => (await import("./driver/stagehand.js")).stagehandDriver()(target, signal, driverOptions));
456
- const custody = new LocalCustody({ config, gates: options.gates, provider, driver, redact, signal: closing.signal, keep: (type, data) => pi.appendEntry(type, data), handoff: options.handoff, vault, vaultTarget: options.vault });
457
- // A fork's branch holds its parent's entries: the parent released its own browser when it ended.
458
- if (reason !== "fork")
459
- await custody.releaseOrphans(ctx.sessionManager.getBranch()).catch(() => undefined);
460
- // With no provider (no Chrome) the web tools still run on the host's fetchers.
461
- const chosenProvider = await provider().catch(() => null);
462
- const web = createWebTools({
463
- name: "provider", evidence, redact: { values: keyValues },
464
- scope: () => ({ label: "web", proxies: policy.proxies }), backups: options.backups ?? [httpBackup()],
465
- ...(chosenProvider?.fetch ? { fetch: (request, signal) => chosenProvider.fetch(request, signal) } : {}),
466
- ...(chosenProvider?.search ? { search: (request, signal) => chosenProvider.search(request, signal) } : {}),
467
- });
468
- // A listing that fails is asked again at the next session start.
469
- const sites = options.sites && listSites ? await options.sites.list(closing.signal).catch(() => []) : [];
470
- let closed = null;
471
- return {
472
- redact, web, searches: !!chosenProvider?.search, sharedBrowser: chosenProvider?.caps.sharedBrowser === true, sites,
473
- async call(tool, args, callId, signal) {
474
- const impl = impls[tool];
475
- custody.activity(1);
476
- try {
477
- const call = { callId, conversationId: CONVERSATION, signal, label: config.label, redact, evidence, workspace: ctx.cwd, files: options.files ?? workspaceFiles(ctx.cwd) };
478
- return await impl(args, custody, call);
479
- }
480
- catch (error) {
481
- // A throw would reach the model as its raw message, unredacted (pi shows a tool's error text): every failure comes back as the typed envelope the durable
482
- // adapter gives, redacted, so the model reads its code and `retryable`. A typed one is thrown before the tool's own handling (the driving guard refuses a
483
- // release or relaunch for a person who is driving before the tool runs); any other is classified here.
484
- const typed = error instanceof BrowserFailureError ? error.failure : classifyBrowserError(error, [...BROWSER_TOOLS, ...WEB_TOOLS].find((contract) => contract.name === tool)?.effect === "effect", { aborted: signal?.aborted === true, redact });
485
- return { content: [{ type: "text", text: JSON.stringify(typed) }], isError: true };
486
- }
487
- finally {
488
- custody.activity(-1);
489
- }
490
- },
491
- close: () => (closed ??= (async () => {
492
- closing.abort();
493
- await custody.close("close");
494
- if (root)
495
- await root.then((dir) => rm(dir, { recursive: true, force: true })).catch(() => undefined);
496
- })()),
497
- };
498
- }
499
- function registerTool(pi, contract, runtimeOf) {
500
- pi.registerTool({
501
- name: contract.name,
502
- label: contract.label,
503
- description: contract.description,
504
- promptSnippet: contract.label,
505
- parameters: contract.parameters,
506
- executionMode: contract.executionMode,
507
- annotations: contract.effect === "read" ? { readOnlyHint: true, openWorldHint: true } : { readOnlyHint: false, openWorldHint: true },
508
- async execute(callId, params, signal, _onUpdate, ctx) {
509
- const rt = await runtimeOf(ctx);
510
- const web = contract.name === "web_fetch" ? await rt.web.fetch(CONVERSATION, params, signal) : contract.name === "web_search" ? await rt.web.search(CONVERSATION, params, signal) : null;
511
- const out = web ? { content: [{ type: "text", text: web.text }], details: web.details, isError: web.isError } : await rt.call(contract.name, params, callId, signal);
512
- // Every text the model is shown passes the redactor, as the durable adapter does: a snapshot or a run's return value is
513
- // where a registered key on a page would otherwise appear.
514
- const content = redactContent(out.content, rt.redact);
515
- return { content, details: out.details ? redactDeep(out.details, rt.redact) : undefined, ...(out.isError ? { isError: true } : {}) };
516
- },
517
- });
518
- }
519
- export function createBrowserExtension(options = {}) {
520
- const env = options.env ?? process.env;
521
- const policy = { ...DEFAULT_BROWSER_POLICY, ...(env.PI_BROWSER_PROXIES === "1" ? { proxies: true } : {}), ...options.policy };
522
- // pi checks a call's arguments against the tool's schema before execute, so each implementation receives its own shape.
523
- // Every browser tool is a model call on its session's driving gate (see durable.ts).
524
- const impls = drivingGuarded({ ...custodyTools, ...pageTools() }, options.gates);
525
- return function piBrowser(pi) {
526
- let runtime = null;
527
- let opening = null;
528
- let webSearchRegistered = false;
529
- let sitesRegistered = false;
530
- // Children on a provider whose sessions share one browser (an endpoint, named by the flag or in the host's own provider)
531
- // would drive the same pages, so there they take turns.
532
- const inTurn = oneAtATime();
533
- pi.registerFlag("browser-provider", { type: "string", description: "Browser provider: cdp (a local Chrome, the default), browserbase (needs BROWSERBASE_API_KEY) or kernel (needs KERNEL_API_KEY)" });
534
- pi.registerFlag("browser-endpoint", { type: "string", description: "Attach to a Chrome DevTools endpoint (http://host:port or ws://...) instead of starting Chrome" });
535
- pi.registerFlag("browser-chrome", { type: "string", description: "Path to the Chrome or Chromium to start" });
536
- pi.registerFlag("browser-headed", { type: "boolean", description: "Show the browser window instead of running headless" });
537
- pi.registerFlag("browser-no-sandbox", { type: "boolean", description: "Start Chrome without its sandbox (needed as root or in a container; only for pages you trust)" });
538
- const runtimeOf = (ctx, reason = "startup") => runtime ? Promise.resolve(runtime) : (opening ??= openRuntime(pi, { options, env, policy, impls }, ctx, reason, !sitesRegistered).then((r) => {
539
- if (r.searches && !webSearchRegistered) {
540
- registerTool(pi, WEB_TOOLS.find((tool) => tool.name === "web_search"), runtimeOf);
541
- webSearchRegistered = true;
542
- }
543
- if (options.sites && r.sites.length && !sitesRegistered) {
544
- registerSites(options.sites, r.sites);
545
- sitesRegistered = true;
546
- }
547
- return (runtime = r);
548
- }));
549
- const end = async () => {
550
- const current = runtime ?? (await opening?.catch(() => null)) ?? null;
551
- runtime = null;
552
- opening = null;
553
- await current?.close();
554
- };
555
- pi.on("session_start", async (event, ctx) => { await end(); await runtimeOf(ctx, event.reason); });
556
- pi.on("session_shutdown", end);
557
- const fileTools = options.fileTools !== false;
558
- pi.on("before_agent_start", (event) => { event.systemPromptOptions.sections.browser = browserSection(policy, { downloads: fileTools, upload: fileTools }); });
559
- async function childSession(ctx, prompt, signal) {
560
- const sdk = await import("@earendil-works/pi-coding-agent");
561
- const model = ctx.model;
562
- if (!model)
563
- throw new Error("this session has no model to give a child");
564
- const cancelled = () => { if (signal.aborted)
565
- throw new Error("the use_website call was cancelled before its child started"); };
566
- const agentDir = sdk.getAgentDir();
567
- const modelRuntime = await sdk.ModelRuntime.create();
568
- // A provider registered at run time (by an extension, or a test) is not in the files a fresh runtime reads.
569
- const registered = ctx.modelRegistry.getRegisteredProviderConfig(model.provider);
570
- if (registered)
571
- modelRuntime.registerProvider(model.provider, registered);
572
- const flags = new Map();
573
- for (const flag of BROWSER_FLAGS) {
574
- const value = pi.getFlag(flag);
575
- if (typeof value === "string" || typeof value === "boolean")
576
- flags.set(flag, value);
577
- }
578
- const extension = createBrowserExtension({ ...options, sites: undefined, fileTools: false });
579
- const runtime = await sdk.createAgentSessionRuntime(async ({ cwd, sessionManager, sessionStartEvent }) => {
580
- const services = await sdk.createAgentSessionServices({
581
- cwd, agentDir, modelRuntime, extensionFlagValues: flags,
582
- resourceLoaderOptions: { extensionFactories: [extension], noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true },
583
- });
584
- return { ...(await sdk.createAgentSessionFromServices({ services, sessionManager, sessionStartEvent, model, thinkingLevel: ctx.thinkingLevel, noTools: "builtin" })), services, diagnostics: services.diagnostics };
585
- }, { cwd: ctx.cwd, agentDir, sessionManager: sdk.SessionManager.inMemory(ctx.cwd) });
586
- let report = "";
587
- const stop = runtime.session.subscribe((event) => {
588
- if (event.type !== "message_end" || event.message.role !== "assistant")
589
- return;
590
- const text = event.message.content.filter((part) => part.type === "text").map((part) => part.text ?? "").join("").trim();
591
- if (text)
592
- report = text;
593
- });
594
- const abort = () => { runtime.session.abort().catch(() => undefined); };
595
- signal.addEventListener("abort", abort, { once: true });
596
- try {
597
- // A cancel during the setup above has already fired, so the listener never hears it: check before each step.
598
- cancelled();
599
- await runtime.session.bindExtensions({});
600
- cancelled();
601
- await runtime.session.prompt(prompt);
602
- }
603
- finally {
604
- signal.removeEventListener("abort", abort);
605
- stop();
606
- await runtime.dispose();
607
- }
608
- if (!report)
609
- throw new Error("the child finished without a report");
610
- return report;
611
- }
612
- function registerSites(port, listing) {
613
- const contract = useWebsiteContract(listing);
614
- pi.registerTool({
615
- name: contract.name,
616
- label: contract.label,
617
- description: contract.description,
618
- promptSnippet: contract.label,
619
- parameters: contract.parameters,
620
- executionMode: contract.executionMode,
621
- annotations: { readOnlyHint: false, openWorldHint: true },
622
- async execute(_callId, params, signal, _onUpdate, ctx) {
623
- const rt = await runtimeOf(ctx);
624
- const out = await useWebsite(params, port, listing, { signal: signal ?? new AbortController().signal, runChild: (task, childSignal) => {
625
- const run = () => childSession(ctx, task.prompt, childSignal);
626
- return rt.sharedBrowser ? inTurn(run) : run();
627
- } });
628
- return { content: redactContent(out.content, rt.redact), details: undefined, ...(out.isError ? { isError: true } : {}) };
629
- },
630
- });
631
- }
632
- // A session vault keeps sign-ins, and run says so; without one it claims cookies across pages only.
633
- for (const contract of browserToolsFor(!!options.sessionVault))
634
- if (listedFor(contract, { downloads: fileTools, upload: fileTools, handoff: !!options.handoff }))
635
- registerTool(pi, contract, runtimeOf);
636
- registerTool(pi, WEB_TOOLS.find((tool) => tool.name === "web_fetch"), runtimeOf);
637
- };
638
- }
639
- export default function piBrowser(pi) {
640
- createBrowserExtension()(pi);
641
- }
@@ -1,18 +0,0 @@
1
- import { type BrowserFailure } from "../core/failures.js";
2
- import type { AttachTarget, BrowserProvider } from "../core/host.js";
3
- import type { ResourceStatus } from "../core/lease.js";
4
- export type AssignedSession = {
5
- /** The session's id: the same for every attach. */
6
- readonly id: string;
7
- /** A fresh target for the driver; it names no secret in `sdkCdpUrl` (a relay or a signed URL goes in `dial`). A failure
8
- * the model should read is thrown as an error carrying `failure`. */
9
- attach(signal?: AbortSignal): Promise<AttachTarget>;
10
- status(signal?: AbortSignal): Promise<ResourceStatus>;
11
- /** Why the session can no longer be used (the host fenced it, took it back, it ended), or null while it can. */
12
- failure?(): BrowserFailure | null;
13
- };
14
- export declare function assignedSessionProvider(input: {
15
- name: string;
16
- session: AssignedSession;
17
- maxLifetimeS?: number;
18
- }): BrowserProvider;