@parcha/pi-browser 0.1.0-beta.23 → 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 +8 -0
- package/README.md +15 -0
- package/dist/coding-agent-local.js +7 -6
- package/dist/coding-agent.js +25 -22
- 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 +9 -0
- package/dist/core/custody.js +22 -5
- 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 +10 -0
- package/dist/core/failures.js +22 -15
- package/dist/core/host.d.ts +6 -0
- package/dist/core/redact.d.ts +5 -0
- package/dist/core/redact.js +4 -0
- package/dist/core/sites.js +2 -1
- package/dist/core/tools.js +7 -8
- 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/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 +39 -131
- package/dist/providers/assigned.js +2 -3
- package/dist/providers/browserbase.js +5 -4
- package/dist/providers/cdp.js +7 -36
- package/dist/providers/chrome-args.d.ts +18 -0
- package/dist/providers/chrome-args.js +66 -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,14 @@
|
|
|
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
|
+
|
|
5
13
|
## 0.1.0-beta.23 (2026-10-22)
|
|
6
14
|
|
|
7
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.
|
package/README.md
CHANGED
|
@@ -267,6 +267,9 @@ pi 1.0.4 or 1.1.x users: pin `@earendil-works/pi-codemode` to the same version a
|
|
|
267
267
|
- `/providers/browserbase`, `/providers/kernel`, `/providers/cdp`: where browsers come from. Browserbase through its SDK,
|
|
268
268
|
with the credential-proxy dial and the connect-URL rewrite. Kernel through its REST API on the package's own HTTP agent.
|
|
269
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=*`.
|
|
270
273
|
- `/providers/assigned`: `assignedSessionProvider()`, over the one session a host assigned to the run. It never creates or
|
|
271
274
|
ends a browser: it hands that session to one custody at a time, and the host takes it back itself.
|
|
272
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
|
|
@@ -309,6 +312,10 @@ What it does with your machine and your data:
|
|
|
309
312
|
that a crashed pi left running is closed when that session is next started, never adopted.
|
|
310
313
|
- Stagehand's trace export is pointed at a closed loopback port, so nothing you browse goes to a third party.
|
|
311
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`.
|
|
312
319
|
|
|
313
320
|
Providers and `web_fetch`:
|
|
314
321
|
|
|
@@ -387,6 +394,14 @@ before anything resumes, it calls `handle.reconcile(harness, isActive, ctx)`, an
|
|
|
387
394
|
kept or released. The host wraps the tools (`handle.tools`) with its own policy: pause, call records, a result cap, media for
|
|
388
395
|
the route.
|
|
389
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
|
+
|
|
390
405
|
A host with its own provider implements `BrowserProvider`: `name`, `caps`, `create` (at most once, the tag stamped on the
|
|
391
406
|
provider's side), `findByTag`, `status`, `attach`, `release`, and optionally `liveView`, `recordings`, `downloads`, `fetch`
|
|
392
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, hostLiveView, 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);
|
|
@@ -375,17 +378,17 @@ async function chooseProvider(pi, { options, env }, profiles) {
|
|
|
375
378
|
return typeof options.provider === "function" ? options.provider() : options.provider;
|
|
376
379
|
const kind = flagOf(pi, "browser-provider", env.PI_BROWSER_PROVIDER ?? "cdp");
|
|
377
380
|
if (kind === "browserbase") {
|
|
378
|
-
if (!(env.BROWSERBASE_API_KEY || env.BB_API_KEY))
|
|
379
|
-
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");
|
|
380
383
|
return (await import("./providers/browserbase.js")).browserbaseProvider({ env });
|
|
381
384
|
}
|
|
382
385
|
if (kind === "kernel") {
|
|
383
|
-
if (!env.KERNEL_API_KEY)
|
|
384
|
-
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");
|
|
385
388
|
return (await import("./providers/kernel.js")).kernelProvider({ env, stealth: env.PI_BROWSER_STEALTH === "1" });
|
|
386
389
|
}
|
|
387
390
|
if (kind !== "cdp")
|
|
388
|
-
throw
|
|
391
|
+
throw noBrowser(`--browser-provider is "${kind}"; it is cdp, browserbase or kernel.`, "refused");
|
|
389
392
|
const { cdpProvider } = await import("./providers/cdp.js");
|
|
390
393
|
const endpoint = flagOf(pi, "browser-endpoint", env.PI_BROWSER_ENDPOINT);
|
|
391
394
|
if (endpoint)
|
|
@@ -394,10 +397,10 @@ async function chooseProvider(pi, { options, env }, profiles) {
|
|
|
394
397
|
// places searched.
|
|
395
398
|
const named = flagOf(pi, "browser-chrome") ?? (env.PI_BROWSER_CHROME || undefined);
|
|
396
399
|
if (named && !existsSync(named))
|
|
397
|
-
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.`);
|
|
398
401
|
const executablePath = named ?? findChrome(env);
|
|
399
402
|
if (!executablePath)
|
|
400
|
-
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.");
|
|
401
404
|
const headed = pi.getFlag("browser-headed") === true || env.PI_BROWSER_HEADED === "1";
|
|
402
405
|
// Absent the flag, the provider reads PI_BROWSER_NO_SANDBOX itself.
|
|
403
406
|
return cdpProvider({ chrome: { executablePath, profileRoot: await profiles.root(), headless: !headed, ...(pi.getFlag("browser-no-sandbox") === true ? { sandbox: false } : {}) } });
|
|
@@ -473,7 +476,7 @@ function registerTool(pi, contract, runtimeOf) {
|
|
|
473
476
|
const out = web ? { content: [{ type: "text", text: web.text }], details: web.details, isError: web.isError } : await rt.call(contract.name, params, callId, signal);
|
|
474
477
|
// Every text the model is shown passes the redactor, as the durable adapter does: a snapshot or a run's return value is
|
|
475
478
|
// where a registered key on a page would otherwise appear.
|
|
476
|
-
const content = out.content
|
|
479
|
+
const content = redactContent(out.content, rt.redact);
|
|
477
480
|
return { content, details: out.details ? redactDeep(out.details, rt.redact) : undefined, ...(out.isError ? { isError: true } : {}) };
|
|
478
481
|
},
|
|
479
482
|
});
|
|
@@ -587,12 +590,12 @@ export function createBrowserExtension(options = {}) {
|
|
|
587
590
|
const run = () => childSession(ctx, task.prompt, childSignal);
|
|
588
591
|
return rt.sharedBrowser ? inTurn(run) : run();
|
|
589
592
|
} });
|
|
590
|
-
return { content: out.content
|
|
593
|
+
return { content: redactContent(out.content, rt.redact), details: undefined, ...(out.isError ? { isError: true } : {}) };
|
|
591
594
|
},
|
|
592
595
|
});
|
|
593
596
|
}
|
|
594
597
|
for (const contract of BROWSER_TOOLS)
|
|
595
|
-
if (contract
|
|
598
|
+
if (listedFor(contract, { downloads: fileTools, upload: fileTools, handoff: !!options.handoff }))
|
|
596
599
|
registerTool(pi, contract, runtimeOf);
|
|
597
600
|
registerTool(pi, WEB_TOOLS.find((tool) => tool.name === "web_fetch"), runtimeOf);
|
|
598
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 = {
|
|
@@ -174,6 +176,13 @@ 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
187
|
/** browser_relaunch on a provider whose session the host assigned: nothing to relaunch onto, and nothing released. */
|
|
179
188
|
export declare const FIXED_SESSION_RELAUNCH: BrowserFailure;
|
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,11 +122,26 @@ 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
|
}
|
|
126
143
|
/** browser_relaunch on a provider whose session the host assigned: nothing to relaunch onto, and nothing released. */
|
|
127
|
-
export const FIXED_SESSION_RELAUNCH = Object.freeze(
|
|
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."));
|
|
128
145
|
/** With proxies off a geolocation is refused up front: the session would browse from the provider's default place,
|
|
129
146
|
* silently. */
|
|
130
147
|
export function relaunchRefusal(policy, overrides) {
|
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,6 +8,14 @@ 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;
|
|
@@ -24,6 +32,8 @@ export type FailureFacts = {
|
|
|
24
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.";
|
package/dist/core/failures.js
CHANGED
|
@@ -6,6 +6,8 @@ export const FAILURE_CODES = Object.freeze([
|
|
|
6
6
|
"session_replaced", "effect_unknown", "code_error", "command_failed", "not_content", "blocked", "rate_limited", "waiting_for_human",
|
|
7
7
|
]);
|
|
8
8
|
export const browserFailure = (code, message, options = {}) => ({ ok: false, code, retryable: options.retryable ?? false, effect: options.effect ?? "none", message, ...(options.detail === undefined ? {} : { detail: options.detail }) });
|
|
9
|
+
/** The vendored facade's refusal texts (vendor/stagehand-facade/contract.ts), copied so the root entry does not load the facade; a test pins
|
|
10
|
+
* them to the facade's own. */
|
|
9
11
|
export const NO_HYDRATED_SNAPSHOT_ERROR = "No hydrated snapshot exists for the active page; call snapshot first.";
|
|
10
12
|
export const NAVIGATED_SNAPSHOT_ERROR = "The active page navigated after its snapshot; call snapshot again.";
|
|
11
13
|
export const STALE_SNAPSHOT_ID_ERROR = 'Snapshot ID "${id}" is stale or not actionable; call snapshot again.';
|
|
@@ -16,9 +18,11 @@ const isStaleSnapshot = (message) => message === NO_HYDRATED_SNAPSHOT_ERROR || m
|
|
|
16
18
|
* host rethrows it with the extension's JSON-RPC internal error (-32603) as the cause. The driver is gone, not the session. */
|
|
17
19
|
export const STAGEHAND_LOOPBACK_DISCONNECTED = "Stagehand loopback CDP is disconnected";
|
|
18
20
|
const JSONRPC_INTERNAL_ERROR = -32603;
|
|
21
|
+
/** A property of a thrown value when it is an object: errors carry facts (a cause, a code, a status) no type declares. */
|
|
22
|
+
const field = (value, key) => (value !== null && typeof value === "object" ? value[key] : undefined);
|
|
19
23
|
const lostLoopback = (error) => {
|
|
20
|
-
const cause = error
|
|
21
|
-
return
|
|
24
|
+
const cause = field(error, "cause");
|
|
25
|
+
return field(cause, "code") === JSONRPC_INTERNAL_ERROR && field(cause, "message") === STAGEHAND_LOOPBACK_DISCONNECTED;
|
|
22
26
|
};
|
|
23
27
|
const UNREACHABLE_CAUSES = new Set(["ECONNREFUSED", "ENOTFOUND", "ECONNRESET", "EAI_AGAIN", "EPIPE", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT"]);
|
|
24
28
|
// A host call the browser left unanswered past its deadline is a dropped connection too.
|
|
@@ -26,20 +30,21 @@ const UNREACHABLE_NAMES = new Set(["CDPConnectionClosedError", UNANSWERED_CALL])
|
|
|
26
30
|
/** A throw site's `transport` record, else class name, `code` and `status` down the cause chain; first found wins. */
|
|
27
31
|
export function transportFactOf(error) {
|
|
28
32
|
const out = {};
|
|
29
|
-
|
|
30
|
-
for (let depth = 0; current && typeof current === "object" && depth < 6; depth += 1, current = current
|
|
31
|
-
const attached = current
|
|
33
|
+
const found = out;
|
|
34
|
+
for (let depth = 0, current = error; current && typeof current === "object" && depth < 6; depth += 1, current = field(current, "cause")) {
|
|
35
|
+
const attached = field(current, "transport");
|
|
32
36
|
if (attached && typeof attached === "object") {
|
|
33
37
|
for (const [key, value] of Object.entries(attached))
|
|
34
|
-
if (value !== undefined &&
|
|
35
|
-
|
|
38
|
+
if (value !== undefined && found[key] === undefined)
|
|
39
|
+
found[key] = value;
|
|
36
40
|
}
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
41
|
+
const name = field(current, "name"), code = field(current, "code"), status = field(current, "status");
|
|
42
|
+
if (out.errorName === undefined && typeof name === "string" && name !== "Error")
|
|
43
|
+
out.errorName = name;
|
|
44
|
+
if (out.causeCode === undefined && typeof code === "string" && code)
|
|
45
|
+
out.causeCode = code;
|
|
46
|
+
if (out.status === undefined && typeof status === "number" && Number.isInteger(status))
|
|
47
|
+
out.status = status;
|
|
43
48
|
}
|
|
44
49
|
return out;
|
|
45
50
|
}
|
|
@@ -59,11 +64,11 @@ function withCause(own, cause) {
|
|
|
59
64
|
}
|
|
60
65
|
export function classifyBrowserError(error, effectful, facts = {}) {
|
|
61
66
|
// Stagehand wraps SDK failures with { cause }: the HTTP status and the real message live on the cause.
|
|
62
|
-
const cause = error
|
|
67
|
+
const cause = field(error, "cause");
|
|
63
68
|
const own = error instanceof Error ? error.message : String(error);
|
|
64
69
|
const message = (facts.redact ?? ((text) => text))(withCause(own, cause));
|
|
65
70
|
const fact = transportFactOf(error);
|
|
66
|
-
const status = fact.status ?? Number(error
|
|
71
|
+
const status = fact.status ?? Number(field(error, "statusCode") ?? field(cause, "statusCode") ?? NaN);
|
|
67
72
|
const effect = effectful ? "possibly_effected" : "none";
|
|
68
73
|
const detail = message.slice(0, 2_000);
|
|
69
74
|
if (facts.aborted || fact.errorName === "AbortError")
|
|
@@ -72,6 +77,8 @@ export function classifyBrowserError(error, effectful, facts = {}) {
|
|
|
72
77
|
return browserFailure("auth", "The browser provider refused the credential (401). The browser plane is unavailable for this run; use fetch (executor tools).", { detail });
|
|
73
78
|
if (status === 403)
|
|
74
79
|
return browserFailure("auth", "The browser provider refused this session type (403). Retry without `verified`, or use web_fetch.", { detail });
|
|
80
|
+
if (status === 429)
|
|
81
|
+
return browserFailure("rate_limited", `The browser provider is rate limiting this run (429). ${effectful ? "Your call may have acted: take a snapshot before you act again." : "Wait a moment, then try again."}`, { retryable: !effectful, effect, detail });
|
|
75
82
|
if (facts.sessionEnded)
|
|
76
83
|
return browserFailure("session_ended", "The browser session ended (the provider closed it at its timeout, or the browser died). Your next browser call opens a fresh session automatically; the old tabs, page state and cookies are gone — navigate to the page again with run, then continue from there.", { retryable: true, effect, detail });
|
|
77
84
|
if (facts.timedOut || fact.errorName === "TimeoutError")
|
package/dist/core/host.d.ts
CHANGED
|
@@ -99,6 +99,9 @@ export type ProviderCaps = {
|
|
|
99
99
|
settings?: Partial<SessionSettingsSupport>;
|
|
100
100
|
/** The host assigned the run this one session: there is no other to relaunch onto. */
|
|
101
101
|
fixedSession?: boolean;
|
|
102
|
+
/** The provider enforces a navigation policy's `allow` list (only the listed sites load). A provider without it cannot apply an
|
|
103
|
+
* allow list, and a session under one is refused. */
|
|
104
|
+
navigationAllow?: boolean;
|
|
102
105
|
};
|
|
103
106
|
export type SessionSettingsSupport = {
|
|
104
107
|
proxies: boolean;
|
|
@@ -250,6 +253,8 @@ export type SessionRecord = {
|
|
|
250
253
|
releaseReason: ReleaseReason | null;
|
|
251
254
|
plane: string;
|
|
252
255
|
provider: string;
|
|
256
|
+
/** `navigationAllow`: the allow list the provider applied when it created the session, which it never changes afterwards.
|
|
257
|
+
* Absent: none was applied. */
|
|
253
258
|
settings: {
|
|
254
259
|
proxies: boolean;
|
|
255
260
|
verified: boolean;
|
|
@@ -257,6 +262,7 @@ export type SessionRecord = {
|
|
|
257
262
|
region: string | null;
|
|
258
263
|
contextId: string | null;
|
|
259
264
|
profile: string | null;
|
|
265
|
+
navigationAllow?: string[];
|
|
260
266
|
};
|
|
261
267
|
/** Every page the session moved to, in order; the last 500 kept. */
|
|
262
268
|
navigation: Array<{
|
package/dist/core/redact.d.ts
CHANGED
|
@@ -8,6 +8,11 @@ export declare function createRedactor(values?: () => readonly string[]): Redact
|
|
|
8
8
|
/** A credential can sit in any query value, the fragment or the userinfo, so every query value is replaced (names stay)
|
|
9
9
|
* and the fragment and userinfo are dropped before `redact` runs. A non-http(s) URL is only redacted. */
|
|
10
10
|
export declare function scrubPageUrl(raw: string, redact: Redact): string;
|
|
11
|
+
/** A tool result's content as the model is shown it: every text passes the redactor; an image is left as it is. */
|
|
12
|
+
export declare function redactContent<T extends {
|
|
13
|
+
type: string;
|
|
14
|
+
text?: string;
|
|
15
|
+
}>(content: readonly T[], redact: Redact): T[];
|
|
11
16
|
/** A live view as the host receives it, on every channel (`onSession`, a handoff's `request`): the viewer's own URLs stay
|
|
12
17
|
* whole, since the host needs their token; a browsed page's URL and title are scrubbed, since its query can carry a credential. */
|
|
13
18
|
export declare function hostLiveView(view: LiveView, redact: Redact): LiveView;
|
package/dist/core/redact.js
CHANGED
|
@@ -38,6 +38,10 @@ export function scrubPageUrl(raw, redact) {
|
|
|
38
38
|
const names = [...new Set(url.searchParams.keys())];
|
|
39
39
|
return redact(`${url.origin}${url.pathname}${names.length ? `?${names.map((n) => `${encodeURIComponent(n)}=${REDACTED}`).join("&")}` : ""}`);
|
|
40
40
|
}
|
|
41
|
+
/** A tool result's content as the model is shown it: every text passes the redactor; an image is left as it is. */
|
|
42
|
+
export function redactContent(content, redact) {
|
|
43
|
+
return content.map((item) => (item.type === "text" && typeof item.text === "string" ? { ...item, text: redact(item.text) } : item));
|
|
44
|
+
}
|
|
41
45
|
/** A live view as the host receives it, on every channel (`onSession`, a handoff's `request`): the viewer's own URLs stay
|
|
42
46
|
* whole, since the host needs their token; a browsed page's URL and title are scrubbed, since its query can carry a credential. */
|
|
43
47
|
export function hostLiveView(view, redact) {
|
package/dist/core/sites.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { browserFailure } from "./failures.js";
|
|
1
2
|
export const MAX_SITE_INSTRUCTIONS = 16_000;
|
|
2
3
|
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
3
4
|
const RUN_ID = /^[A-Za-z0-9_.:-]{1,200}$/;
|
|
@@ -39,7 +40,7 @@ export function siteAnswer(raw) {
|
|
|
39
40
|
return typeof id === "string" && RUN_ID.test(id) && typeof state === "string" && RUN_STATE.test(state) ? { run: { id, state } } : null;
|
|
40
41
|
}
|
|
41
42
|
const siteOutput = (body, isError = false) => ({ content: [{ type: "text", text: JSON.stringify(body) }], ...(isError ? { isError: true } : {}) });
|
|
42
|
-
const siteRefusal = (message) => siteOutput(
|
|
43
|
+
const siteRefusal = (message) => siteOutput(browserFailure("refused", message), true);
|
|
43
44
|
export async function useWebsite(args, port, sites, ctx) {
|
|
44
45
|
const site = sites.find((known) => known.site === args.site);
|
|
45
46
|
if (!site)
|