@parcha/pi-browser 0.1.0-beta.21 → 0.1.0-beta.26
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +38 -7
- package/dist/coding-agent-local.js +7 -6
- package/dist/coding-agent.js +32 -28
- package/dist/core/clip.js +2 -2
- package/dist/core/contract.d.ts +7 -0
- package/dist/core/contract.js +3 -0
- package/dist/core/custody.d.ts +13 -4
- package/dist/core/custody.js +23 -6
- package/dist/core/downloads.js +2 -2
- package/dist/core/driving.d.ts +6 -0
- package/dist/core/driving.js +8 -0
- package/dist/core/failures.d.ts +13 -3
- package/dist/core/failures.js +22 -15
- package/dist/core/host.d.ts +6 -0
- package/dist/core/redact.d.ts +9 -0
- package/dist/core/redact.js +9 -0
- package/dist/core/sites.js +2 -1
- package/dist/core/tools.d.ts +2 -2
- package/dist/core/tools.js +7 -10
- package/dist/core/web.d.ts +1 -6
- package/dist/core/web.js +8 -4
- package/dist/driver/extension-worker.js +149 -118
- package/dist/driver/page-driver.d.ts +2 -1
- package/dist/driver/sealed.d.ts +16 -0
- package/dist/driver/sealed.js +47 -0
- package/dist/driver/stagehand.js +7 -43
- package/dist/durable/journal.d.ts +31 -0
- package/dist/durable/journal.js +105 -0
- package/dist/{durable-result.d.ts → durable/result.d.ts} +1 -1
- package/dist/{store.d.ts → durable/store.d.ts} +2 -2
- package/dist/{store.js → durable/store.js} +1 -1
- package/dist/{web.d.ts → durable/web.d.ts} +4 -4
- package/dist/{web.js → durable/web.js} +5 -5
- package/dist/durable.d.ts +2 -2
- package/dist/durable.js +42 -135
- package/dist/live-view/provider.d.ts +1 -1
- package/dist/live-view/provider.js +1 -1
- package/dist/live-view/server.d.ts +2 -2
- package/dist/live-view/server.js +1 -3
- package/dist/providers/assigned.js +2 -3
- package/dist/providers/browserbase-net.d.ts +0 -1
- package/dist/providers/browserbase-net.js +0 -1
- package/dist/providers/browserbase.js +5 -4
- package/dist/providers/cdp.js +38 -43
- package/dist/providers/chrome-args.d.ts +18 -0
- package/dist/providers/chrome-args.js +66 -0
- package/dist/providers/chrome-stderr.d.ts +21 -0
- package/dist/providers/chrome-stderr.js +108 -0
- package/dist/providers/http.d.ts +4 -1
- package/dist/providers/http.js +5 -8
- package/dist/providers/kernel.d.ts +10 -1
- package/dist/providers/kernel.js +1 -1
- package/dist/providers/profiles.js +6 -6
- package/dist/providers/shared.d.ts +9 -0
- package/dist/providers/shared.js +5 -1
- package/package.json +7 -3
- /package/dist/{durable-result.js → durable/result.js} +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.1.0-beta.26 (2026-10-24)
|
|
6
|
+
|
|
7
|
+
- Security: pi-browser requires undici 6.29.1 or later (`^6.29.1`, from `^6.28.0`), the release that fixes GHSA-xjj6-f33q-929c.
|
|
8
|
+
- Security: pi-browser's own zod moves from ~4.4.3 to ~4.6.6, the release that fixes GHSA-mrhx-c7xc-m3w5 (a high-severity memory exhaustion while validating large arrays). The copy of zod that `@browserbasehq/stagehand` pins for itself (4.4.3 in every Stagehand release so far) is outside pi-browser's control until Stagehand ships a fixed release; the package gate accepts that one nested copy until 2026-11-06.
|
|
9
|
+
- `@parcha/pi-browser`: a new entry, `@parcha/pi-browser/providers/chrome-args`, exports `chromeArgs()` (the local Chrome's flags, with `--remote-allow-origins` narrowed to the one extension Origin) and `extensionOrigin()`, for a host that starts its own Chrome for Stagehand and should not copy the list. The README names the action-policy refusal under the pi coding agent.
|
|
10
|
+
- `@parcha/pi-browser`: a `web_fetch` backup's refusal (a private or local host, too many redirects, a redirect out of http(s), a page that is not text, one over 5 MiB) reaches the model as `refused`, not as a retryable `command_failed` that said "Try once more". A provider's 429 on a create or an attach is `rate_limited` on the browser plane, as it already was on the web plane (retryable when the call acted on nothing; an effectful call says to take a snapshot first). The coding agent refuses a whitespace-only Browserbase or Kernel key as `auth`, naming the key, as the providers read keys. The provider reset also lets go of profile writer claims, so a claim left before a reset no longer refuses a later session. `directFetch` is undici's fetch with no silent fallback to the proxied global fetch: a failed undici load is a broken install and now throws. The live-grid and ask-site examples (in the repository, not the npm package) keep a tile on the open page after a popup closes, run through a symlink, import cleanly from a script read through stdin, and work on an IPv6 host. The rest of the batch changes no behaviour: one way to build a refusal in core, `BrowserFailure` declares `next` and `evidence`, the failure classifier reads facts through one typed reader, the two hosts share their keep-for-a-person and redaction rules, and the extension worker, the sealed Stagehand's create-once-more step and the pi-durable adapter's internals are named, tested modules.
|
|
11
|
+
- `@parcha/pi-browser`: three security fixes. The local Chrome's DevTools socket accepts only the Stagehand extension's Origin, not every Origin: the provider launched Chrome with Stagehand's default `--remote-allow-origins=*`, and in a real Chrome for Testing 155 a web page in the run's own Chrome could open the browser-wide DevTools socket when given its URL. The provider now computes the one Origin the extension's service worker connects from (Chrome names an unpacked extension by the SHA-256 of its real path) and allows exactly it; a directory that cannot be resolved refuses the launch as `browser_unavailable` and never opens the socket to every Origin. The pi coding agent refuses to browse under a `deny` or `ask` action policy it cannot hold: it never opened the request observer that enforces that policy, so every request the page sent went out, irreversible ones included; every browser tool now answers `browser_unavailable` naming the action policy (`web_fetch` is unaffected, and `allow` browses as before). A navigation policy the provider cannot enforce refuses the session, naming `navigation.block` or `navigation.allow` and the provider: before, the local, Kernel and assigned providers accepted either and applied neither, and no provider enforces a block list; an allow list is enforced where the new optional `ProviderCaps.navigationAllow` is set (Browserbase). A live durable session reused later meets the same check as a new one at create: the session record keeps the allow list the provider applied at create, and a reused session that was started with no list, or a wider one than the policy now sets, is refused with the same named refusal (a record from before this change fails closed).
|
|
12
|
+
|
|
13
|
+
## 0.1.0-beta.23 (2026-10-22)
|
|
14
|
+
|
|
15
|
+
- `@parcha/pi-browser`: a Chrome that exits before it opens its debugging port now fails the create with the last ten lines it wrote to stderr (a partial first line dropped, each whole line redacted for the common key shapes and then shortened, control characters dropped). When the sandbox is on and Chrome aborted or named the sandbox, the failure is the typed `browser_unavailable` and says to set `sandbox: false` or `PI_BROWSER_NO_SANDBOX=1`; before, only a SIGABRT said so, and Debian's Chromium in a container exited 1 and gave only its exit code. Chrome's stderr is a file in the lease's private directory, emptied once the port is open and whenever it passes 256 KB. A tail window with no newline in it shows nothing, a Chrome a restarted host recovers through `attach` has its file bounded the same way, and a launch whose `spawn` throws closes the file and removes the lease's private directory instead of leaking both. The README's Quick start names the container setting and `--init`, documents the local Chrome's options including `sandbox`, and creates its session inside the `try`, so a failed create leaves no profile root; its pi range now reads 1.1 to 1.3. The pi coding agent's untyped tool errors reach the model redacted: a failure that was not a typed browser failure (a workspace read that fails before `browser_upload`'s own handling, for one) used to be rethrown with its raw message, so a registered key in it reached the model and the session file; every failure now comes back typed and redacted. A handoff gives the host the browsed page's URL with its query and fragment scrubbed and its title redacted, as `onSession` always did; the viewer's own URL stays whole there, since the host needs its token.
|
|
16
|
+
- `@parcha/pi-browser`: the README's Quick start names the container setting (`PI_BROWSER_NO_SANDBOX=1`, or `sandbox: false`, and `--init` so a killed Chrome is reaped), documents the local Chrome's options including `sandbox`, and creates its session inside the `try`, so a failed create leaves no profile root. The entries list names `/providers/assigned` and `/recorder`, and says the core loads the two HTML packages on demand. Doc comments in the source sit on the declaration they describe, and the live view's docs name both host channels that receive the viewer URL.
|
|
17
|
+
- `@parcha/pi-browser`: the README's Install block has a line for a pi-durable host that pins `@earendil-works/pi-durable`, `chord` and `pi-ai` to 1.3.0, and says pi 1.4 is not supported yet. pi 1.4.0 is npm's latest and the peer range stops below it, so the same names unpinned stop `npm install` with ERESOLVE. The first screen's pi range reads 1.1 to 1.3, the range of the peers.
|
|
18
|
+
|
|
5
19
|
## 0.1.0-beta.19 (2026-10-20)
|
|
6
20
|
|
|
7
21
|
- `@parcha/pi-browser`: a live view for the cdp provider, from the new `@parcha/pi-browser/live-view` export. `createLiveView` serves a viewer page and a loopback WebSocket for one person at a time: the first message must be the hello with the session's token, a wrong or missing token, a bad Origin or a second viewer is refused, the screencast frames are never written anywhere, the viewer says it is connecting and refuses input out loud until it is ready, and the view ends when the session is released. `liveViewProvider` wraps the cdp provider and reports the viewer's URL to `onSession` and nowhere else. While a person drives the viewer, every browser tool call (and `browser_release` and `browser_relaunch`) is refused with a typed, retryable `person_driving` before it does anything, the person's input is discarded while the agent acts (one shared gate per session, `drivingGates`), and an idle window never releases a session a person drives or watches. Custody can hold a session for a person behind a per-session fence: `CustodyPort` gains `current()`, a page action the fence stopped before any driver call got through is settled as not sent, and a held session the provider ended no longer holds up the conversation. `FrameRecorderOptions.hold` keeps a person-driven session out of the recording (one `frame.gap` marks the span), and when a hold lifts one frame is captured on demand so the replay does not end at the hold. `RunAction` types the actions of `run` per op. `browser_upload` runs behind a `WorkspaceFiles` port (it refuses swapped parents, pipes and host-private files, and is journaled like a run), `browser_downloads` works, and a `use_website` child is offered neither. A site child's browser can be the session the host reserved for it: the new `@parcha/pi-browser/providers/assigned` export never creates or ends a browser, takes its assigned session as the run's only browser, and is never relaunched or idled away. A screenshot's result carries the captured image's own facts in `details.media` (`kind`, `path`, `mime`, `bytes`, `width`, `height`, `ask`), and a screenshot can capture one region, by clip, snapshot id or CSS selector. The index exports custody's vocabulary, and a session's record and `relaunch`'s answer say the settings the provider applied. `browser_request_handoff` hands the browser to a person for a step only a human can do, such as a 2FA or a captcha, and waits durably for the host's answer. It is listed only when the host gives a `HandoffPort`, a rerun never asks again once the answer is kept, `done`, `cancelled` or `expired` give the session back under a new fence, and every other call answers `waiting_for_human` meanwhile. A refusal from the port, or a failure before it answers, gives the session straight back.
|
package/README.md
CHANGED
|
@@ -10,8 +10,8 @@ Your agent gets its own browser, and you can take over and hand it back.
|
|
|
10
10
|
|
|
11
11
|
If the process dies, a pi-durable host recovers the session and does not repeat an action. See [For hosts](#for-hosts).
|
|
12
12
|
|
|
13
|
-
Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=22.19.0`, pi 1.1
|
|
14
|
-
coding-agent entry also runs on pi 1.0.4). ESM only: the
|
|
13
|
+
Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=22.19.0`, pi 1.1 to 1.3 (the range of its
|
|
14
|
+
pi-durable and chord peers; the coding-agent entry also runs on pi 1.0.4). ESM only: the
|
|
15
15
|
package has `import` entries and no `require` entry.
|
|
16
16
|
|
|
17
17
|
## Install
|
|
@@ -19,13 +19,14 @@ package has `import` entries and no `require` entry.
|
|
|
19
19
|
```sh
|
|
20
20
|
pi install npm:@parcha/pi-browser@beta # the pi coding agent's extension
|
|
21
21
|
npm install @parcha/pi-browser@beta # the library: providers, driver, durable adapter
|
|
22
|
+
npm install @parcha/pi-browser@beta @earendil-works/pi-durable@1.3.0 @earendil-works/chord@1.3.0 @earendil-works/pi-ai@1.3.0 # a pi-durable host: its peers, pinned to 1.3.0 (unpinned, npm takes 1.4.0 and stops with ERESOLVE)
|
|
22
23
|
```
|
|
23
24
|
|
|
24
|
-
`pi install` loads the extension. A Chrome starts on the model's first browser call, and not before.
|
|
25
|
+
`pi install` loads the extension. A Chrome starts on the model's first browser call, and not before. pi 1.4 is not supported yet; a later release widens the range.
|
|
25
26
|
|
|
26
27
|
## Quick start
|
|
27
28
|
|
|
28
|
-
A local Chrome, one page, one snapshot. It needs Chrome or Chromium; `CHROME_PATH` names it.
|
|
29
|
+
A local Chrome, one page, one snapshot. It needs Chrome or Chromium; `CHROME_PATH` names it. As root or in a container, Chrome cannot start its sandbox: set `PI_BROWSER_NO_SANDBOX=1`, or pass `sandbox: false` beside `executablePath`, and run the container with `--init`, or a Chrome killed on cleanup stays a zombie.
|
|
29
30
|
|
|
30
31
|
```js
|
|
31
32
|
import { mkdtemp, rm } from "node:fs/promises";
|
|
@@ -37,14 +38,15 @@ import { stagehandDriver } from "@parcha/pi-browser/driver/stagehand";
|
|
|
37
38
|
const profileRoot = await mkdtemp(join(tmpdir(), "pi-browser-"));
|
|
38
39
|
const provider = cdpProvider({ chrome: { executablePath: process.env.CHROME_PATH ?? "/usr/bin/google-chrome", profileRoot } });
|
|
39
40
|
const signal = AbortSignal.timeout(60_000);
|
|
40
|
-
|
|
41
|
+
let session;
|
|
41
42
|
try {
|
|
43
|
+
session = await provider.create({ tag: "quick-start", maxLifetimeS: 600, idleTimeoutS: 60, proxies: false, verified: false, captcha: false, viewport: { width: 1000, height: 700 }, metadata: {} }, signal);
|
|
42
44
|
const driver = await stagehandDriver()(await provider.attach(session), signal);
|
|
43
45
|
await driver.run({ code: `await page.goto(${JSON.stringify(process.argv[2] ?? "https://example.com")})` });
|
|
44
46
|
console.log(await driver.snapshot());
|
|
45
47
|
await driver.close();
|
|
46
48
|
} finally {
|
|
47
|
-
await provider.release(session);
|
|
49
|
+
if (session) await provider.release(session);
|
|
48
50
|
await rm(profileRoot, { recursive: true, force: true });
|
|
49
51
|
}
|
|
50
52
|
```
|
|
@@ -96,6 +98,15 @@ The same tools run on three kinds of browser. You pick one when you set up the p
|
|
|
96
98
|
| Browserbase (`/providers/browserbase`) | A Browserbase session, through its SDK. | `BROWSERBASE_API_KEY` and the `@browserbasehq/sdk` peer. |
|
|
97
99
|
| Kernel (`/providers/kernel`) | A Kernel browser, through its REST API. | `KERNEL_API_KEY`. No SDK. |
|
|
98
100
|
|
|
101
|
+
The local Chrome's options, in `cdpProvider({ chrome: { ... } })`:
|
|
102
|
+
|
|
103
|
+
| Option | Meaning |
|
|
104
|
+
|---|---|
|
|
105
|
+
| `executablePath`, `profileRoot` | The Chrome to start, and the directory its profiles live under. Both are required. |
|
|
106
|
+
| `headless` | `true` by default; `false` shows the window. |
|
|
107
|
+
| `args` | Extra Chrome flags, added after the package's own. |
|
|
108
|
+
| `sandbox` | Chrome's own sandbox, on unless `false`. When absent, `PI_BROWSER_NO_SANDBOX=1` turns it off. Turn it off only where Chrome cannot start its sandbox (root, a container, restricted user namespaces), and only for pages you trust. A Chrome that exits before it opens its debugging port fails the create with its last lines of stderr, and with this hint when it aborted or named the sandbox. |
|
|
109
|
+
|
|
99
110
|
The pi extension picks one from a flag or an environment variable; see [For pi users](#for-pi-users). A host that wires the package itself passes the provider it wants; see [For hosts](#for-hosts). `examples/one-script-three-providers.mjs` runs one script on all three.
|
|
100
111
|
|
|
101
112
|
## Take over and hand back
|
|
@@ -243,7 +254,8 @@ pi 1.0.4 or 1.1.x users: pin `@earendil-works/pi-codemode` to the same version a
|
|
|
243
254
|
- `@parcha/pi-browser`: the host-neutral core. The model contract (tool names, descriptions, JSON schemas, effect and
|
|
244
255
|
replay classes, the `browser` and `web` prompt sections), the typed failure envelope, the redactor, the screenshot
|
|
245
256
|
budget, the repeat guard, evidence and decision-hook types, usage and prices, `find` (chunking and ranking a long page),
|
|
246
|
-
`browser_downloads`, the opt-in request observer, and the provider interface.
|
|
257
|
+
`browser_downloads`, the opt-in request observer, and the provider interface. Outside Node's builtins it loads only
|
|
258
|
+
node-html-parser and node-html-markdown, on demand, for `browser_read`'s page text and frame scan.
|
|
247
259
|
- `/durable`: the pi-durable adapter. `createBrowserExtension` is session custody in the run's own store (a create is
|
|
248
260
|
committed before the provider is called, release is a durable task, reconcile runs at run open). `createWebExtension` is
|
|
249
261
|
`web_fetch` and `web_search`.
|
|
@@ -255,8 +267,15 @@ pi 1.0.4 or 1.1.x users: pin `@earendil-works/pi-codemode` to the same version a
|
|
|
255
267
|
- `/providers/browserbase`, `/providers/kernel`, `/providers/cdp`: where browsers come from. Browserbase through its SDK,
|
|
256
268
|
with the credential-proxy dial and the connect-URL rewrite. Kernel through its REST API on the package's own HTTP agent.
|
|
257
269
|
Any CDP endpoint, or a local Chrome the provider starts and kills by exact pid.
|
|
270
|
+
- `/providers/chrome-args`: `chromeArgs()`, the arguments the cdp provider starts a local Chrome with, and `extensionOrigin()`,
|
|
271
|
+
the one Origin its DevTools socket allows (Stagehand's extension). A host that starts its own Chrome for Stagehand takes them
|
|
272
|
+
from here rather than copying Stagehand's `--remote-allow-origins=*`.
|
|
273
|
+
- `/providers/assigned`: `assignedSessionProvider()`, over the one session a host assigned to the run. It never creates or
|
|
274
|
+
ends a browser: it hands that session to one custody at a time, and the host takes it back itself.
|
|
258
275
|
- `/live-view`: a person sees and drives the local Chrome (the cdp provider) from your page, with nothing leaving the machine but the model. See
|
|
259
276
|
[The live view of your own Chrome](#the-live-view-of-your-own-chrome).
|
|
277
|
+
- `/recorder`: `frameRecorder()` screencasts each session over DevTools into a sink you pass, and `exportFrameTracks()`
|
|
278
|
+
makes a WebM per session from the recorded frames. See [Recording what the browsers show](#recording-what-the-browsers-show).
|
|
260
279
|
- `/testing`: the shared test fake. A provider backend with a ledger of every call, a credential broker, an HTTP face so the
|
|
261
280
|
ledger outlives a killed child process, a driver over in-memory pages, and sentinel credentials. A host's composition
|
|
262
281
|
test and this package's crash matrix use the same one.
|
|
@@ -293,6 +312,10 @@ What it does with your machine and your data:
|
|
|
293
312
|
that a crashed pi left running is closed when that session is next started, never adopted.
|
|
294
313
|
- Stagehand's trace export is pointed at a closed loopback port, so nothing you browse goes to a third party.
|
|
295
314
|
- `browser_relaunch` with `verified` or `geolocation` changes nothing on a local Chrome or on Kernel; they are Browserbase features.
|
|
315
|
+
- A host that builds the extension with `policy: { actions: "deny" }` or `"ask"` asks for requests to be held, and the coding
|
|
316
|
+
agent has no request observer to hold them. So under either it starts no browser: every browser tool answers
|
|
317
|
+
`browser_unavailable`, naming the action policy, and `web_fetch` still works. Set `actions: "allow"` (or leave it out) to
|
|
318
|
+
browse, or use the pi-durable adapter (`/durable`), which holds requests under `deny` and `ask`.
|
|
296
319
|
|
|
297
320
|
Providers and `web_fetch`:
|
|
298
321
|
|
|
@@ -371,6 +394,14 @@ before anything resumes, it calls `handle.reconcile(harness, isActive, ctx)`, an
|
|
|
371
394
|
kept or released. The host wraps the tools (`handle.tools`) with its own policy: pause, call records, a result cap, media for
|
|
372
395
|
the route.
|
|
373
396
|
|
|
397
|
+
A policy's `navigation` is a restriction the host relies on, so a session that would not hold to it is never started. No
|
|
398
|
+
provider enforces a `block` list today, so a policy with one refuses every session. An `allow` list is enforced only by a
|
|
399
|
+
provider whose `caps.navigationAllow` is true (Browserbase, through `allowedDomains`); on any other provider the session is
|
|
400
|
+
refused. Each refusal names the part of the policy and the provider. Both adapters behave the same.
|
|
401
|
+
A provider applies an allow list only when it creates a session, so the durable adapter records it on the session. A live
|
|
402
|
+
session used again under a policy whose `allow` list it was not started under (none, or a wider one) is refused the same way,
|
|
403
|
+
and `browser_relaunch` starts one under the current policy.
|
|
404
|
+
|
|
374
405
|
A host with its own provider implements `BrowserProvider`: `name`, `caps`, `create` (at most once, the tag stamped on the
|
|
375
406
|
provider's side), `findByTag`, `status`, `attach`, `release`, and optionally `liveView`, `recordings`, `downloads`, `fetch`
|
|
376
407
|
and `search`.
|
|
@@ -4,6 +4,7 @@ import { Agent, fetch as undiciFetch } from "undici";
|
|
|
4
4
|
import dns from "node:dns/promises";
|
|
5
5
|
import net from "node:net";
|
|
6
6
|
import path from "node:path";
|
|
7
|
+
import { refusedError } from "./core/custody.js";
|
|
7
8
|
const LINUX_NAMES = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"];
|
|
8
9
|
export function findChrome(env = process.env, exists = existsSync) {
|
|
9
10
|
for (const named of [env.PI_BROWSER_CHROME, env.CHROME_PATH])
|
|
@@ -88,27 +89,27 @@ export function httpBackup(options = {}) {
|
|
|
88
89
|
for (let hop = 0;; hop += 1) {
|
|
89
90
|
const host = target.hostname.replace(/^\[|\]$/g, "");
|
|
90
91
|
if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal"))
|
|
91
|
-
throw
|
|
92
|
+
throw refusedError(`refused: ${host} is not a public host`);
|
|
92
93
|
const addresses = net.isIP(host) ? [host] : await lookup(host);
|
|
93
94
|
if (!addresses.length || addresses.some(isPrivateAddress))
|
|
94
|
-
throw
|
|
95
|
+
throw refusedError(`refused: ${host} is not a public host`);
|
|
95
96
|
const dispatcher = new Agent({ connect: { lookup: pinnedLookup(addresses[0]) } });
|
|
96
97
|
let res;
|
|
97
98
|
try {
|
|
98
99
|
res = await request(target, { redirect: "manual", signal, dispatcher, headers: { accept: "text/html,text/plain;q=0.9,*/*;q=0.1", "user-agent": "pi-browser" } });
|
|
99
100
|
if (res.status >= 300 && res.status < 400 && res.headers.get("location")) {
|
|
100
101
|
if (hop >= MAX_REDIRECTS)
|
|
101
|
-
throw
|
|
102
|
+
throw refusedError("refused: too many redirects");
|
|
102
103
|
target = new URL(res.headers.get("location"), target);
|
|
103
104
|
if (!/^https?:$/.test(target.protocol))
|
|
104
|
-
throw
|
|
105
|
+
throw refusedError("refused: a redirect left http(s)");
|
|
105
106
|
continue;
|
|
106
107
|
}
|
|
107
108
|
if (!res.ok)
|
|
108
109
|
throw Object.assign(new Error(`the page answered ${res.status}`), { status: res.status });
|
|
109
110
|
const type = res.headers.get("content-type") ?? "";
|
|
110
111
|
if (!/^(text\/|application\/(xhtml\+xml|json|xml))/i.test(type))
|
|
111
|
-
throw
|
|
112
|
+
throw refusedError(`refused: ${type || "an unknown content type"} is not text`);
|
|
112
113
|
const chunks = [];
|
|
113
114
|
let size = 0;
|
|
114
115
|
for (const reader = res.body.getReader();;) {
|
|
@@ -117,7 +118,7 @@ export function httpBackup(options = {}) {
|
|
|
117
118
|
break;
|
|
118
119
|
if ((size += value.length) > MAX_BYTES) {
|
|
119
120
|
await reader.cancel();
|
|
120
|
-
throw
|
|
121
|
+
throw refusedError("refused: the page is over 5 MiB");
|
|
121
122
|
}
|
|
122
123
|
chunks.push(value);
|
|
123
124
|
}
|
package/dist/coding-agent.js
CHANGED
|
@@ -4,24 +4,28 @@ import { mkdtemp, rm } from "node:fs/promises";
|
|
|
4
4
|
import os from "node:os";
|
|
5
5
|
import path from "node:path";
|
|
6
6
|
import { setTimeout as sleep } from "node:timers/promises";
|
|
7
|
-
import { BROWSER_TOOLS, WEB_TOOLS, browserSection } from "./core/contract.js";
|
|
8
|
-
import { BrowserFailureError, closeDriver, custodyTools, FIXED_SESSION_RELAUNCH, fenced, HANDED_BACK, loadedNoPage, moveRecord, newSessionRecord, notices, NOTHING_TO_HOLD, profileRefusal, sessionSpec, waitingForHuman, backoffMs, NO_HANDOFF, } from "./core/custody.js";
|
|
7
|
+
import { BROWSER_TOOLS, WEB_TOOLS, browserSection, 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, sessionSpec, waitingForHuman, backoffMs, NO_HANDOFF, } from "./core/custody.js";
|
|
9
9
|
import { browserFailure, classifyBrowserError } from "./core/failures.js";
|
|
10
10
|
import { workspaceFiles } from "./core/files.js";
|
|
11
11
|
import { leaseTag } from "./core/lease.js";
|
|
12
|
-
import { createRedactor, redactDeep, scrubPageUrl } from "./core/redact.js";
|
|
12
|
+
import { createRedactor, hostLiveView, redactContent, redactDeep, scrubPageUrl } from "./core/redact.js";
|
|
13
13
|
import { useWebsite, useWebsiteContract } from "./core/sites.js";
|
|
14
14
|
import { drivingGuarded } from "./core/driving-guard.js";
|
|
15
|
-
import { drivingGates,
|
|
15
|
+
import { drivingGates, keptReason, personOn, rearmWhenLeft } from "./core/driving.js";
|
|
16
16
|
import { pageTools } from "./core/tools.js";
|
|
17
17
|
import { CREATE_DEADLINE_MS, DEFAULT_BROWSER_POLICY, idleTracker, keyedSerializer, oneAtATime, providerKeyValues } from "./core/session-control.js";
|
|
18
18
|
import { createWebTools } from "./core/web.js";
|
|
19
19
|
import { fileEvidenceSink, findChrome, httpBackup } from "./coding-agent-local.js";
|
|
20
|
+
// 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.
|
|
21
|
+
import { nonEmpty } from "./providers/shared.js";
|
|
20
22
|
export { findChrome } from "./coding-agent-local.js";
|
|
21
23
|
export const SESSION_ENTRY = "browser.session";
|
|
22
24
|
const CONVERSATION = 1;
|
|
23
25
|
const BROWSER_FLAGS = ["browser-provider", "browser-endpoint", "browser-chrome", "browser-headed", "browser-no-sandbox"];
|
|
24
|
-
const
|
|
26
|
+
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.");
|
|
27
|
+
/** 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. */
|
|
28
|
+
const noBrowser = (message, code = "browser_unavailable") => new BrowserFailureError(browserFailure(code, message));
|
|
25
29
|
const now = () => new Date().toISOString();
|
|
26
30
|
/** The provider released the browser and could not remove a directory it left (`ProfileNotRemovedError`'s code, read without importing the provider). */
|
|
27
31
|
const directoryLeft = (error) => error?.code === "profile_not_removed";
|
|
@@ -109,10 +113,14 @@ export class LocalCustody {
|
|
|
109
113
|
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 };
|
|
110
114
|
}
|
|
111
115
|
async launch(overrides) {
|
|
116
|
+
// This host has no request observer, so a policy that holds requests (deny, ask) would be dropped and every request sent:
|
|
117
|
+
// it starts no browser instead, as the durable adapter refuses to browse without its observer.
|
|
118
|
+
if (this.d.config.policy.actions && this.d.config.policy.actions !== "allow")
|
|
119
|
+
throw new BrowserFailureError(UNHELD_ACTIONS);
|
|
112
120
|
const provider = await this.d.provider();
|
|
113
121
|
const tag = leaseTag("pib", this.d.config.run, randomUUID().slice(0, 8), ++this.seq);
|
|
114
122
|
const spec = sessionSpec(this.d.config, tag, overrides);
|
|
115
|
-
const unsupported = profileRefusal(spec, provider.caps);
|
|
123
|
+
const unsupported = profileRefusal(spec, provider.caps) ?? navigationRefusal(spec, provider);
|
|
116
124
|
if (unsupported)
|
|
117
125
|
throw new BrowserFailureError(unsupported);
|
|
118
126
|
const record = newSessionRecord({ plane: "browser", tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
|
|
@@ -307,12 +315,7 @@ export class LocalCustody {
|
|
|
307
315
|
if (!live)
|
|
308
316
|
return { released: false, lastUrl: null };
|
|
309
317
|
const lastUrl = live.record.lastUrl;
|
|
310
|
-
|
|
311
|
-
if (live.record.state === "held")
|
|
312
|
-
return { released: false, lastUrl, kept: "held" };
|
|
313
|
-
// A session a person drives or watches through the live view is theirs: custody never releases it on its own.
|
|
314
|
-
const person = personOn(this.d.gates ?? drivingGates, live.record.tag);
|
|
315
|
-
const kept = person && keptFor(person);
|
|
318
|
+
const kept = keptReason(live.record, this.d.gates ?? drivingGates);
|
|
316
319
|
if (kept)
|
|
317
320
|
return { released: false, lastUrl, kept };
|
|
318
321
|
await this.finish(live, "lost").catch(() => undefined);
|
|
@@ -332,7 +335,8 @@ export class LocalCustody {
|
|
|
332
335
|
const stop = signal ? AbortSignal.any([this.d.signal, signal]) : this.d.signal;
|
|
333
336
|
try {
|
|
334
337
|
const provider = await this.d.provider();
|
|
335
|
-
const
|
|
338
|
+
const view = provider.liveView ? await provider.liveView({ id: sessionId, tag }).catch(() => null) : null;
|
|
339
|
+
const liveView = view && hostLiveView(view, this.d.redact);
|
|
336
340
|
const asked = await port.request({ requestId: ask.requestId, sessionTag: tag, sessionId, liveView, instruction: ask.instruction, completionCondition: ask.completionCondition }, stop);
|
|
337
341
|
if ("refused" in asked)
|
|
338
342
|
return asked;
|
|
@@ -374,17 +378,17 @@ async function chooseProvider(pi, { options, env }, profiles) {
|
|
|
374
378
|
return typeof options.provider === "function" ? options.provider() : options.provider;
|
|
375
379
|
const kind = flagOf(pi, "browser-provider", env.PI_BROWSER_PROVIDER ?? "cdp");
|
|
376
380
|
if (kind === "browserbase") {
|
|
377
|
-
if (!(env.BROWSERBASE_API_KEY || env.BB_API_KEY))
|
|
378
|
-
throw
|
|
381
|
+
if (!(nonEmpty(env.BROWSERBASE_API_KEY) || nonEmpty(env.BB_API_KEY)))
|
|
382
|
+
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");
|
|
379
383
|
return (await import("./providers/browserbase.js")).browserbaseProvider({ env });
|
|
380
384
|
}
|
|
381
385
|
if (kind === "kernel") {
|
|
382
|
-
if (!env.KERNEL_API_KEY)
|
|
383
|
-
throw
|
|
386
|
+
if (!nonEmpty(env.KERNEL_API_KEY))
|
|
387
|
+
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");
|
|
384
388
|
return (await import("./providers/kernel.js")).kernelProvider({ env, stealth: env.PI_BROWSER_STEALTH === "1" });
|
|
385
389
|
}
|
|
386
390
|
if (kind !== "cdp")
|
|
387
|
-
throw
|
|
391
|
+
throw noBrowser(`--browser-provider is "${kind}"; it is cdp, browserbase or kernel.`, "refused");
|
|
388
392
|
const { cdpProvider } = await import("./providers/cdp.js");
|
|
389
393
|
const endpoint = flagOf(pi, "browser-endpoint", env.PI_BROWSER_ENDPOINT);
|
|
390
394
|
if (endpoint)
|
|
@@ -393,10 +397,10 @@ async function chooseProvider(pi, { options, env }, profiles) {
|
|
|
393
397
|
// places searched.
|
|
394
398
|
const named = flagOf(pi, "browser-chrome") ?? (env.PI_BROWSER_CHROME || undefined);
|
|
395
399
|
if (named && !existsSync(named))
|
|
396
|
-
throw
|
|
400
|
+
throw noBrowser(`The Chrome named by --browser-chrome or PI_BROWSER_CHROME, ${named}, does not exist. Ask the person for the right path.`);
|
|
397
401
|
const executablePath = named ?? findChrome(env);
|
|
398
402
|
if (!executablePath)
|
|
399
|
-
throw
|
|
403
|
+
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.");
|
|
400
404
|
const headed = pi.getFlag("browser-headed") === true || env.PI_BROWSER_HEADED === "1";
|
|
401
405
|
// Absent the flag, the provider reads PI_BROWSER_NO_SANDBOX itself.
|
|
402
406
|
return cdpProvider({ chrome: { executablePath, profileRoot: await profiles.root(), headless: !headed, ...(pi.getFlag("browser-no-sandbox") === true ? { sandbox: false } : {}) } });
|
|
@@ -439,11 +443,11 @@ async function openRuntime(pi, settings, ctx, reason, listSites) {
|
|
|
439
443
|
return await impl(args, custody, call);
|
|
440
444
|
}
|
|
441
445
|
catch (error) {
|
|
442
|
-
// A
|
|
443
|
-
//
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
446
|
+
// 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
|
|
447
|
+
// 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
|
|
448
|
+
// release or relaunch for a person who is driving before the tool runs); any other is classified here.
|
|
449
|
+
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 });
|
|
450
|
+
return { content: [{ type: "text", text: JSON.stringify(typed) }], isError: true };
|
|
447
451
|
}
|
|
448
452
|
finally {
|
|
449
453
|
custody.activity(-1);
|
|
@@ -472,7 +476,7 @@ function registerTool(pi, contract, runtimeOf) {
|
|
|
472
476
|
const out = web ? { content: [{ type: "text", text: web.text }], details: web.details, isError: web.isError } : await rt.call(contract.name, params, callId, signal);
|
|
473
477
|
// Every text the model is shown passes the redactor, as the durable adapter does: a snapshot or a run's return value is
|
|
474
478
|
// where a registered key on a page would otherwise appear.
|
|
475
|
-
const content = out.content
|
|
479
|
+
const content = redactContent(out.content, rt.redact);
|
|
476
480
|
return { content, details: out.details ? redactDeep(out.details, rt.redact) : undefined, ...(out.isError ? { isError: true } : {}) };
|
|
477
481
|
},
|
|
478
482
|
});
|
|
@@ -586,12 +590,12 @@ export function createBrowserExtension(options = {}) {
|
|
|
586
590
|
const run = () => childSession(ctx, task.prompt, childSignal);
|
|
587
591
|
return rt.sharedBrowser ? inTurn(run) : run();
|
|
588
592
|
} });
|
|
589
|
-
return { content: out.content
|
|
593
|
+
return { content: redactContent(out.content, rt.redact), details: undefined, ...(out.isError ? { isError: true } : {}) };
|
|
590
594
|
},
|
|
591
595
|
});
|
|
592
596
|
}
|
|
593
597
|
for (const contract of BROWSER_TOOLS)
|
|
594
|
-
if (contract
|
|
598
|
+
if (listedFor(contract, { downloads: fileTools, upload: fileTools, handoff: !!options.handoff }))
|
|
595
599
|
registerTool(pi, contract, runtimeOf);
|
|
596
600
|
registerTool(pi, WEB_TOOLS.find((tool) => tool.name === "web_fetch"), runtimeOf);
|
|
597
601
|
};
|
package/dist/core/clip.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// A screenshot of a region: the page's own rectangle for a clip the model names, or for an element it names by snapshot ID or CSS
|
|
2
2
|
// selector. Every refusal is typed and says why, before a capture is made.
|
|
3
|
-
import {
|
|
4
|
-
const refuse = (message) => { throw
|
|
3
|
+
import { refusedError } from "./custody.js";
|
|
4
|
+
const refuse = (message) => { throw refusedError(`screenshot: ${message} No capture was made.`); };
|
|
5
5
|
const fits = (box, viewport) => box.x >= 0 && box.y >= 0 && box.x + box.width <= viewport.width + 0.5 && box.y + box.height <= viewport.height + 0.5;
|
|
6
6
|
const shown = (box) => `x ${round(box.x)}, y ${round(box.y)}, ${round(box.width)} wide, ${round(box.height)} high`;
|
|
7
7
|
const round = (n) => Math.round(n * 10) / 10;
|
package/dist/core/contract.d.ts
CHANGED
|
@@ -16,6 +16,13 @@ export type ToolContract = {
|
|
|
16
16
|
readonly evidence: "none" | "receipt" | "image" | "files" | "urls";
|
|
17
17
|
readonly listedWhen: "always" | "downloads" | "upload" | "fetch" | "search" | "sites" | "handoff";
|
|
18
18
|
};
|
|
19
|
+
/** Whether a host lists a browser tool: one that is always offered, or one whose capability the host has (a workspace to copy downloads
|
|
20
|
+
* into, files to upload from, a person to hand over to). */
|
|
21
|
+
export declare const listedFor: (contract: ToolContract, offers: {
|
|
22
|
+
readonly downloads: boolean;
|
|
23
|
+
readonly upload: boolean;
|
|
24
|
+
readonly handoff: boolean;
|
|
25
|
+
}) => boolean;
|
|
19
26
|
export declare const BROWSER_TOOLS: readonly ToolContract[];
|
|
20
27
|
export declare const WEB_TOOLS: readonly ToolContract[];
|
|
21
28
|
export declare const BROWSER_TOOL_NAMES: readonly string[];
|
package/dist/core/contract.js
CHANGED
|
@@ -147,6 +147,9 @@ const webSearch = {
|
|
|
147
147
|
parameters: object({ query: { type: "string" }, n: { type: "number", description: "Results to return, 1-25 (default 10)." } }, ["query"]),
|
|
148
148
|
effect: "read", replay: "safe", executionMode: "parallel", evidence: "urls", listedWhen: "search",
|
|
149
149
|
};
|
|
150
|
+
/** Whether a host lists a browser tool: one that is always offered, or one whose capability the host has (a workspace to copy downloads
|
|
151
|
+
* into, files to upload from, a person to hand over to). */
|
|
152
|
+
export const listedFor = (contract, offers) => contract.listedWhen === "always" || (contract.listedWhen === "downloads" && offers.downloads) || (contract.listedWhen === "upload" && offers.upload) || (contract.listedWhen === "handoff" && offers.handoff);
|
|
150
153
|
export const BROWSER_TOOLS = Object.freeze([snapshot, run, screenshot, browserRead, browserRelease, browserRelaunch, browserRequestHandoff, browserDownloads, browserUpload]);
|
|
151
154
|
export const WEB_TOOLS = Object.freeze([webFetch, webSearch]);
|
|
152
155
|
export const BROWSER_TOOL_NAMES = Object.freeze(BROWSER_TOOLS.map((tool) => tool.name));
|
package/dist/core/custody.d.ts
CHANGED
|
@@ -17,6 +17,8 @@ export declare class BrowserFailureError extends Error {
|
|
|
17
17
|
name: string;
|
|
18
18
|
constructor(failure: BrowserFailure);
|
|
19
19
|
}
|
|
20
|
+
/** A refusal, thrown: nothing was tried, and the same call would be refused again. */
|
|
21
|
+
export declare const refusedError: (message: string) => BrowserFailureError;
|
|
20
22
|
/** `verified: true` raises the run's Verified policy for one session; false or absent keeps the policy, which nothing
|
|
21
23
|
* here can lower. */
|
|
22
24
|
export type Overrides = {
|
|
@@ -51,8 +53,8 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
|
|
|
51
53
|
session(signal?: AbortSignal): Promise<AttachedSession<D>>;
|
|
52
54
|
/** A rerun finds the session it launched. */
|
|
53
55
|
relaunch(overrides: Overrides): Promise<AttachedSession<D>>;
|
|
54
|
-
/** No session, or one already released, is not an error.
|
|
55
|
-
|
|
56
|
+
/** No session, or one already released, is not an error.
|
|
57
|
+
* `ended`: the session was released, or is being released, before this call: by what and when (null while in flight). */
|
|
56
58
|
release(): Promise<{
|
|
57
59
|
released: boolean;
|
|
58
60
|
sessionId: string | null;
|
|
@@ -174,11 +176,18 @@ export declare function moveRecord(record: SessionRecord, next: {
|
|
|
174
176
|
}): void;
|
|
175
177
|
export declare const PROFILE_NAME: RegExp;
|
|
176
178
|
export declare function sessionSpec(config: BrowserConfig, tag: string, overrides?: Overrides): SessionSpec;
|
|
179
|
+
/** A navigation policy is a restriction the host relies on, so a session it would not hold to is refused, never started without it.
|
|
180
|
+
* No provider enforces a `block` list; an `allow` list only where the provider says it does (`caps.navigationAllow`). */
|
|
181
|
+
/** `reused`, for a live session about to be used again: the allow list its provider applied at create. A provider fixes the list
|
|
182
|
+
* then, so a session started with none, or with a wider one, does not hold to the list the policy sets now. */
|
|
183
|
+
export declare function navigationRefusal(spec: Pick<SessionSpec, "navigation">, provider: Pick<BrowserProvider, "name" | "caps">, reused?: {
|
|
184
|
+
applied?: readonly string[];
|
|
185
|
+
}): BrowserFailure | null;
|
|
177
186
|
export declare function profileRefusal(spec: SessionSpec, caps: ProviderCaps): BrowserFailure | null;
|
|
178
|
-
/** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
|
|
179
|
-
* silently. */
|
|
180
187
|
/** browser_relaunch on a provider whose session the host assigned: nothing to relaunch onto, and nothing released. */
|
|
181
188
|
export declare const FIXED_SESSION_RELAUNCH: BrowserFailure;
|
|
189
|
+
/** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
|
|
190
|
+
* silently. */
|
|
182
191
|
export declare function relaunchRefusal(policy: BrowserConfig["policy"], overrides: Overrides): BrowserFailure | null;
|
|
183
192
|
/** An ISO alpha-2 country, a US state abbreviation, a city in capitals; null when the country is not two letters. */
|
|
184
193
|
export declare function normalizeGeolocation(raw: unknown): Geo | null;
|
package/dist/core/custody.js
CHANGED
|
@@ -16,6 +16,8 @@ export class BrowserFailureError extends Error {
|
|
|
16
16
|
this.failure = failure;
|
|
17
17
|
}
|
|
18
18
|
}
|
|
19
|
+
/** A refusal, thrown: nothing was tried, and the same call would be refused again. */
|
|
20
|
+
export const refusedError = (message) => new BrowserFailureError(browserFailure("refused", message));
|
|
19
21
|
export const NAVIGATION_CAP = 500;
|
|
20
22
|
export const VIEWPORT = Object.freeze({ width: 1288, height: 711 });
|
|
21
23
|
export const SESSION_REPLACED = browserFailure("session_replaced", "The browser session this call was using ended in an interruption, so its page is gone. Navigate again with run, or take a snapshot, to continue in a fresh session.", { retryable: true });
|
|
@@ -73,6 +75,7 @@ export function newSessionRecord(input) {
|
|
|
73
75
|
proxies, verified: spec.verified && honours.verified !== false,
|
|
74
76
|
geolocation: proxies && honours.geolocation !== false && typeof spec.proxies === "object" ? spec.proxies.geolocation : null,
|
|
75
77
|
region: honours.region === false ? null : spec.region ?? null, contextId: honours.context === false ? null : spec.contextId ?? null, profile: spec.profile?.name ?? null,
|
|
78
|
+
...(spec.navigation?.allow?.length ? { navigationAllow: [...spec.navigation.allow] } : {}),
|
|
76
79
|
},
|
|
77
80
|
navigation: [], lastUrl: null, pendingEffect: null, spent: startSpent(input.at),
|
|
78
81
|
};
|
|
@@ -100,13 +103,12 @@ export function moveRecord(record, next) {
|
|
|
100
103
|
record.endedAt = next.at;
|
|
101
104
|
}
|
|
102
105
|
export const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
|
|
103
|
-
const refused = (message) => ({ ok: false, code: "refused", retryable: false, effect: "none", message });
|
|
104
106
|
export function sessionSpec(config, tag, overrides = {}) {
|
|
105
107
|
const { policy } = config;
|
|
106
108
|
if (policy.profile && !PROFILE_NAME.test(policy.profile.name))
|
|
107
|
-
throw
|
|
109
|
+
throw refusedError("browser profile: a profile name is 1 to 64 characters of letters, digits, dot, underscore and dash, starting with a letter or digit. No session was started.");
|
|
108
110
|
if (policy.profile && policy.contextId)
|
|
109
|
-
throw
|
|
111
|
+
throw refusedError("browser profile: a saved profile and a context id are two ways to ask for the same saved state; set one. No session was started.");
|
|
110
112
|
const geolocation = overrides.geolocation === undefined ? policy.geolocation : overrides.geolocation;
|
|
111
113
|
return {
|
|
112
114
|
tag, maxLifetimeS: policy.sessionTimeoutS, idleTimeoutS: policy.idleReleaseS,
|
|
@@ -120,13 +122,28 @@ export function sessionSpec(config, tag, overrides = {}) {
|
|
|
120
122
|
metadata: { run: config.run, label: config.label },
|
|
121
123
|
};
|
|
122
124
|
}
|
|
125
|
+
/** A navigation policy is a restriction the host relies on, so a session it would not hold to is refused, never started without it.
|
|
126
|
+
* No provider enforces a `block` list; an `allow` list only where the provider says it does (`caps.navigationAllow`). */
|
|
127
|
+
/** `reused`, for a live session about to be used again: the allow list its provider applied at create. A provider fixes the list
|
|
128
|
+
* then, so a session started with none, or with a wider one, does not hold to the list the policy sets now. */
|
|
129
|
+
export function navigationRefusal(spec, provider, reused) {
|
|
130
|
+
const allow = spec.navigation?.allow;
|
|
131
|
+
const unenforced = spec.navigation?.block?.length ? "navigation.block" : allow?.length && !provider.caps.navigationAllow ? "navigation.allow" : null;
|
|
132
|
+
if (unenforced)
|
|
133
|
+
return browserFailure("refused", `browser navigation: this run's policy sets ${unenforced}, and the ${provider.name} browser provider cannot enforce it, so no session was started. Ask the person to remove it from the policy or to use a provider that enforces it.`);
|
|
134
|
+
const applied = reused?.applied;
|
|
135
|
+
if (reused && allow?.length && !(applied?.length && applied.every((site) => allow.includes(site)))) {
|
|
136
|
+
return browserFailure("refused", `browser navigation: this run's policy sets navigation.allow, and this browser session was started ${applied?.length ? "under a wider allow list" : "without one"}, which the ${provider.name} provider cannot change after it starts a session, so the session was not used. browser_relaunch starts one under the current policy.`);
|
|
137
|
+
}
|
|
138
|
+
return null;
|
|
139
|
+
}
|
|
123
140
|
export function profileRefusal(spec, caps) {
|
|
124
|
-
return spec.profile && !caps.profiles ? refused
|
|
141
|
+
return spec.profile && !caps.profiles ? browserFailure("refused", `browser profile: this browser provider cannot keep a saved sign-in, so profile "${spec.profile.name}" cannot be used. No session was started.`) : null;
|
|
125
142
|
}
|
|
143
|
+
/** browser_relaunch on a provider whose session the host assigned: nothing to relaunch onto, and nothing released. */
|
|
144
|
+
export const FIXED_SESSION_RELAUNCH = Object.freeze(browserFailure("refused", "browser_relaunch: this task's browser is the one session its host assigned it, and there is no other to relaunch onto. Nothing was relaunched and your session is unchanged; keep using it."));
|
|
126
145
|
/** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
|
|
127
146
|
* silently. */
|
|
128
|
-
/** browser_relaunch on a provider whose session the host assigned: nothing to relaunch onto, and nothing released. */
|
|
129
|
-
export const FIXED_SESSION_RELAUNCH = Object.freeze({ ok: false, code: "refused", retryable: false, effect: "none", message: "browser_relaunch: this task's browser is the one session its host assigned it, and there is no other to relaunch onto. Nothing was relaunched and your session is unchanged; keep using it." });
|
|
130
147
|
export function relaunchRefusal(policy, overrides) {
|
|
131
148
|
if (!overrides.geolocation || policy.proxies)
|
|
132
149
|
return null;
|
package/dist/core/downloads.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { createHash, randomBytes } from "node:crypto";
|
|
2
2
|
import { lstat, mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
|
|
3
3
|
import path from "node:path";
|
|
4
|
-
import {
|
|
4
|
+
import { refusedError } from "./custody.js";
|
|
5
5
|
export const DOWNLOADS_DIR = "downloads";
|
|
6
6
|
export const DOWNLOADS_MANIFEST = "downloads/manifest.json";
|
|
7
7
|
/** Beside `downloads/`, not in it, so no downloaded file can take its name; temporary names start with a dot, which no
|
|
@@ -60,7 +60,7 @@ async function readManifest(file) {
|
|
|
60
60
|
catch { }
|
|
61
61
|
if (parsed?.schema === "pi-browser.downloads.v1" && Array.isArray(parsed.files))
|
|
62
62
|
return parsed;
|
|
63
|
-
throw
|
|
63
|
+
throw refusedError(`${DOWNLOADS_MANIFEST} exists but is not a pi-browser downloads manifest; fix or move it, then call browser_downloads again.`);
|
|
64
64
|
}
|
|
65
65
|
/** Skips what the workspace already holds; one failing file is skipped with its reason. */
|
|
66
66
|
export async function fetchDownloads(options) {
|
package/dist/core/driving.d.ts
CHANGED
|
@@ -55,6 +55,12 @@ export declare const keptFor: (gate: DrivingGate) => "person_driving" | "viewing
|
|
|
55
55
|
* first lookup, so a gate nobody holds is let go again here (an unsubscribe settles it: a gate in use, a call, a person, a
|
|
56
56
|
* viewer or a listener, stays), and custody's own check never leaves one behind. */
|
|
57
57
|
export declare function personOn(gates: DrivingGates, tag: string): DrivingGate | null;
|
|
58
|
+
/** Why custody must not release a session on its own, or null: a session held for a person is theirs, and so is one a person drives or
|
|
59
|
+
* watches through the live view. */
|
|
60
|
+
export declare function keptReason(record: {
|
|
61
|
+
state: string;
|
|
62
|
+
tag: string;
|
|
63
|
+
}, gates: DrivingGates): "held" | "person_driving" | "viewing" | null;
|
|
58
64
|
/** A session custody kept for a person is released one idle window after they leave: the gate is polled (setViewing and end
|
|
59
65
|
* announce nothing), and the moment nobody is on it `rearm` starts the idle window again. Stops once `alive` says the session
|
|
60
66
|
* is gone; the returned function stops it at once (a release, a close). */
|
package/dist/core/driving.js
CHANGED
|
@@ -136,6 +136,14 @@ export function personOn(gates, tag) {
|
|
|
136
136
|
gate.onChange(() => { })();
|
|
137
137
|
return null;
|
|
138
138
|
}
|
|
139
|
+
/** Why custody must not release a session on its own, or null: a session held for a person is theirs, and so is one a person drives or
|
|
140
|
+
* watches through the live view. */
|
|
141
|
+
export function keptReason(record, gates) {
|
|
142
|
+
if (record.state === "held")
|
|
143
|
+
return "held";
|
|
144
|
+
const person = personOn(gates, record.tag);
|
|
145
|
+
return person && keptFor(person);
|
|
146
|
+
}
|
|
139
147
|
/** A session custody kept for a person is released one idle window after they leave: the gate is polled (setViewing and end
|
|
140
148
|
* announce nothing), and the moment nobody is on it `rearm` starts the idle window again. Stops once `alive` says the session
|
|
141
149
|
* is gone; the returned function stops it at once (a release, a close). */
|
package/dist/core/failures.d.ts
CHANGED
|
@@ -8,22 +8,32 @@ export type BrowserFailure = {
|
|
|
8
8
|
message: string;
|
|
9
9
|
/** Provider or page text, at most 2,000 characters; redacted before it reaches the model. */
|
|
10
10
|
detail?: string;
|
|
11
|
+
/** The one step that gets past this failure, when there is one. */
|
|
12
|
+
next?: Next;
|
|
13
|
+
/** The receipt filed for the page that failed (a wall a browser page showed), or null when none was filed. */
|
|
14
|
+
evidence?: string | null;
|
|
15
|
+
};
|
|
16
|
+
export type Next = {
|
|
17
|
+
action: "drive_page" | "other_source" | "browser_relaunch";
|
|
18
|
+
note: string;
|
|
11
19
|
};
|
|
12
20
|
export declare const browserFailure: (code: FailureCode, message: string, options?: {
|
|
13
21
|
retryable?: boolean;
|
|
14
22
|
effect?: BrowserFailure["effect"];
|
|
15
23
|
detail?: string;
|
|
16
24
|
}) => BrowserFailure;
|
|
17
|
-
/** `timedOut`: the call ran to the driver's batch deadline, which Stagehand reports as a plain Error. */
|
|
18
|
-
/** `action`: what an effectful call ran, named when it threw; "Your browser code" when unset. */
|
|
19
|
-
/** `redact` removes the run's registered values from the error text; it runs over the whole text before any cut below, so no fragment of a value survives a cut point. */
|
|
20
25
|
export type FailureFacts = {
|
|
21
26
|
sessionEnded?: boolean;
|
|
22
27
|
aborted?: boolean;
|
|
28
|
+
/** The call ran to the driver's batch deadline, which Stagehand reports as a plain Error. */
|
|
23
29
|
timedOut?: boolean;
|
|
30
|
+
/** What an effectful call ran, named when it threw; "Your browser code" when unset. */
|
|
24
31
|
action?: string;
|
|
32
|
+
/** Removes the run's registered values from the error text; it runs over the whole text before any cut below, so no fragment of a value survives a cut point. */
|
|
25
33
|
redact?: (text: string) => string;
|
|
26
34
|
};
|
|
35
|
+
/** The vendored facade's refusal texts (vendor/stagehand-facade/contract.ts), copied so the root entry does not load the facade; a test pins
|
|
36
|
+
* them to the facade's own. */
|
|
27
37
|
export declare const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
|
|
28
38
|
export declare const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
|
|
29
39
|
export declare const STALE_SNAPSHOT_ID_ERROR = "Snapshot ID \"${id}\" is stale or not actionable; call snapshot again.";
|