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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/NOTICE +30 -0
  3. package/README.md +28 -178
  4. package/dist/core/contract.js +14 -5
  5. package/dist/core/custody.d.ts +6 -0
  6. package/dist/core/custody.js +6 -0
  7. package/dist/core/driving-guard.js +17 -2
  8. package/dist/core/host.d.ts +2 -2
  9. package/dist/core/tools.d.ts +9 -0
  10. package/dist/driver/cdp.d.ts +6 -0
  11. package/dist/driver/cdp.js +245 -0
  12. package/dist/driver/page-driver.js +29 -3
  13. package/dist/durable/store.js +13 -4
  14. package/dist/durable.d.ts +1 -0
  15. package/dist/durable.js +1 -0
  16. package/dist/live-view/provider.d.ts +2 -2
  17. package/dist/live-view/provider.js +2 -2
  18. package/dist/live-view/server.d.ts +1 -1
  19. package/dist/providers/chrome-args.d.ts +3 -0
  20. package/dist/providers/chrome-args.js +13 -2
  21. package/dist/vendor/browser-use-pi/ax.d.ts +106 -0
  22. package/dist/vendor/browser-use-pi/ax.js +642 -0
  23. package/dist/vendor/browser-use-pi/cdp.d.ts +19 -0
  24. package/dist/vendor/browser-use-pi/cdp.js +106 -0
  25. package/dist/vendor/browser-use-pi/page.d.ts +38 -0
  26. package/dist/vendor/browser-use-pi/page.js +112 -0
  27. package/package.json +6 -24
  28. package/src/vendor/browser-use-pi/UPSTREAM.json +25 -0
  29. package/src/vendor/stagehand-facade/UPSTREAM.json +0 -4
  30. package/dist/coding-agent-local.d.ts +0 -12
  31. package/dist/coding-agent-local.js +0 -72
  32. package/dist/coding-agent.d.ts +0 -135
  33. package/dist/coding-agent.js +0 -641
  34. package/dist/providers/assigned.d.ts +0 -18
  35. package/dist/providers/assigned.js +0 -75
  36. package/dist/recorder/credential.d.ts +0 -9
  37. package/dist/recorder/credential.js +0 -49
  38. package/dist/recorder/follow.d.ts +0 -36
  39. package/dist/recorder/follow.js +0 -163
  40. package/dist/recorder/frames.d.ts +0 -87
  41. package/dist/recorder/frames.js +0 -377
  42. package/dist/recorder/index.d.ts +0 -4
  43. package/dist/recorder/index.js +0 -7
  44. package/dist/recorder/jpeg.d.ts +0 -8
  45. package/dist/recorder/jpeg.js +0 -70
  46. package/dist/recorder/track.d.ts +0 -107
  47. package/dist/recorder/track.js +0 -280
  48. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +0 -15
  49. package/dist/vendor/stagehand-facade/screenshot-transport.js +0 -51
package/CHANGELOG.md CHANGED
@@ -2,6 +2,23 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.1.0-beta.34 (2026-11-11)
6
+
7
+ - The package keeps only what a host runs: the core, `/durable`, `/live-view`, `/driver/stagehand`, `/testing` and the providers (Browserbase, Kernel and the local Chrome). Three entries are removed, with no replacement shim:
8
+ - `/coding-agent`, the pi coding agent's extension: `createBrowserExtension`, the default export, `LocalCustody`, `SESSION_ENTRY`, `CodingAgentOptions` and its re-export of `findChrome`. The package's `pi` manifest goes with it, so `pi install npm:@parcha/pi-browser` no longer loads browser tools, and `@earendil-works/pi-coding-agent` is no longer a peer. Use instead: the durable adapter, `createBrowserExtension` from `@parcha/pi-browser/durable`, installed on a pi-durable Harness; `findChrome` from `@parcha/pi-browser/providers/chrome-args`.
9
+ - `/recorder`: `frameRecorder`, `exportFrameTracks`, `planTrack`, `TrackExportError`, `CREDENTIAL_PROBE`, `jpegSize` and their types (`FrameData`, `FrameGapData`, `FrameLine`, `FrameRecorder`, `FrameRecorderOptions`, `FrameSink`, `FrameTrackData`, `FrameTrackLine`, `Track`, `TrackFrame`, `TrackGap`, `TrackIndex`, `TrackOptions`, `TrackPlan`, `TrackSegment`). Nothing replaces them: a host that records a session's frames does it over the session's DevTools connection itself.
10
+ - `/providers/assigned`: `assignedSessionProvider` and `AssignedSession`. Use instead: a `BrowserProvider` of the host's own whose `caps.fixedSession` is `true`; the durable adapter refuses `browser_relaunch` on it as before.
11
+ - A keyless local browser: the computer package's `local` provider (`LocalBrowserProvider`, kind `browser`) runs this machine's Chrome or Chromium, with no vendor and no key, and pi-browser's new `cdpDriver()` (`@parcha/pi-browser/driver/cdp`) drives it with raw CDP.
12
+ - Each browser is one headless Chrome (`headed: true` shows the window) with a throwaway profile and a random debugging port on 127.0.0.1. `connect()` hands over its `ws://` DevTools URL. `release("delete")` ends it and removes its files.
13
+ - A supervisor process of its own ends each browser at its deadline, on release, or when Chrome exits, so a run that crashes leaves no Chrome behind.
14
+ - Chrome's sandbox is always on: a start as root, or where Chrome cannot start its sandbox, is refused in words. Every request goes through an egress proxy that reaches public addresses only. This machine's loopback, private networks, link-local and the cloud metadata address are refused, and Chrome resolves no name itself, speaks no QUIC and sends no WebRTC UDP.
15
+ - Chrome is the `executablePath` option, or `CHROME_PATH` or `PI_BROWSER_CHROME` in the `env` a host passes, or the first on that env's `PATH`. With none, `check()` and `testConnection()` say what to install.
16
+ - Its known limits: the debugging port has no auth (any local process can drive it), and the browser is a process of this host isolated by Chrome's sandbox alone. It is for local and development use.
17
+ - `ComputerCapabilities.isolation` takes `"host"`, and Settings → Computers lists "Local Chrome" with no key.
18
+ - pi-browser's `run` takes a `goto` action (`{"op":"goto","url":"https://..."}`) on every browser. On a browser computer (`cdpDriver()`: Browserbase, Kernel or Local Chrome), `run` takes actions only and refuses code in words (`CDP_CODE_REFUSED`). Its snapshot keeps the "frame-node" ids and names each cross-origin frame it could not read. The driver is adapted from Browser Use Pi (MIT, see pi-browser's NOTICE).
19
+ - A browser run's money on the runner is counted once and shown. `/v2/usage` shows a runner run's browser time again (its `browser_time` meter read per-run files the runner never writes). A run parked at its cap by a browser call shows the cap's words on its budget card, where its reason was empty. Each browser charge is booked once on the run's ledger, under its real call when it has one, named by its session and time so a reopen never books it twice; a charge owed at the provider (a session's release, a person's carried time) is booked past the cap, as main kept it. The browser's holds (a call's, a session's reserve, a person's time) are money reserved, never spent: a lost claim gives them back, never leaves them counted as spent.
20
+ - A hand-back now resumes the agent within half a second. While a browser hand-over waits on the person, its answer is asked for every 500 ms (`HANDOFF_POLL_MS`), not on the backoff for failed calls, which waited up to 30 s between asks: an agent handed back 40 s into its ask resumed only at 61.5 s. A read of the answer that fails still backs off.
21
+
5
22
  ## 0.1.0-beta.32 (2026-11-10)
6
23
 
7
24
  - `@parcha/pi-browser` runs on Stagehand 4.4.0, whose zod (4.6.6) carries the fix for GHSA-mrhx-c7xc-m3w5. If you upgrade: a local Chrome must be 137 or later, `cdpProvider({ endpoint, extensionId })` and `AttachTarget.extensionId` are gone (Stagehand finds its extension by name), and `STAGEHAND_TELEMETRY` and `STAGEHAND_INIT_IN_PROGRESS` are no longer exported.
package/NOTICE CHANGED
@@ -31,3 +31,33 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
31
31
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
32
32
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
33
33
  SOFTWARE.
34
+
35
+ This package also contains code adapted from Browser Use Pi (https://github.com/browser-use/browser-use-pi), under its MIT
36
+ license, whose text follows:
37
+
38
+ - The files in src/vendor/browser-use-pi (compiled to dist/vendor/browser-use-pi), adapted from Browser Use Pi's
39
+ src/ax.ts, src/cdp.ts and src/page.ts at commit e7007f219b10fa2c2baae1bf3e2f902a5a2706fd. Each file says what changed;
40
+ UPSTREAM.json, shipped beside them as src/vendor/browser-use-pi/UPSTREAM.json, records each upstream file's blob and
41
+ SHA-256.
42
+
43
+ MIT License
44
+
45
+ Copyright (c) 2026 Browser Use contributors
46
+
47
+ Permission is hereby granted, free of charge, to any person obtaining a copy
48
+ of this software and associated documentation files (the "Software"), to deal
49
+ in the Software without restriction, including without limitation the rights
50
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
51
+ copies of the Software, and to permit persons to whom the Software is
52
+ furnished to do so, subject to the following conditions:
53
+
54
+ The above copyright notice and this permission notice shall be included in all
55
+ copies or substantial portions of the Software.
56
+
57
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
58
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
59
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
60
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
61
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
62
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
63
+ SOFTWARE.
package/README.md CHANGED
@@ -17,13 +17,10 @@ package has `import` entries and no `require` entry.
17
17
  ## Install
18
18
 
19
19
  ```sh
20
- pi install npm:@parcha/pi-browser@latest # the pi coding agent's extension
21
20
  npm install @parcha/pi-browser@latest # the library: providers, driver, durable adapter
22
21
  npm install @parcha/pi-browser@latest @earendil-works/pi-durable@1.5.0 @earendil-works/chord@1.5.0 @earendil-works/pi-ai@1.5.0 # a pi-durable host: its peers, pinned to 1.5.0
23
22
  ```
24
23
 
25
- `pi install` loads the extension. A Chrome starts on the model's first browser call, and not before.
26
-
27
24
  ## Quick start
28
25
 
29
26
  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.
@@ -107,7 +104,7 @@ The local Chrome's options, in `cdpProvider({ chrome: { ... } })`:
107
104
  | `args` | Extra Chrome flags, added after the package's own. |
108
105
  | `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
106
 
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.
107
+ A host passes the provider it wants; see [For hosts](#for-hosts). `examples/one-script-three-providers.mjs` runs one script on all three.
111
108
 
112
109
  ## Take over and hand back
113
110
 
@@ -119,15 +116,11 @@ A person and the agent never drive the browser together. There are two ways for
119
116
 
120
117
  **The limit.** The credential guards are not in this release. Until they ship, use the live view with test accounts on practice sites only. The model's own page code can read what a person types there.
121
118
 
122
- What runs where:
123
-
124
- | | The pi extension, as `pi install` loads it | A host that wires it |
125
- |---|---|---|
126
- | Live view of a local Chrome | not wired | `createLiveView` and `liveViewProvider` |
127
- | Live-view URL of a Browserbase or Kernel session | not shown to anyone | handed to the host only, through `onSession` or the handoff port |
128
- | `browser_request_handoff` | not listed | listed when the host passes a `handoff` port |
119
+ What a host wires:
129
120
 
130
- The pi extension does not offer Kernel's live view, because Kernel's API has no read-only form of it.
121
+ - **The live view of a local Chrome:** `createLiveView` and `liveViewProvider`.
122
+ - **The live-view URL of a Browserbase or Kernel session:** handed to the host only, through `onSession` or the handoff port.
123
+ - **`browser_request_handoff`:** listed when the host passes a `handoff` port.
131
124
 
132
125
  ### The live view of your own Chrome
133
126
 
@@ -144,7 +137,7 @@ const liveView = createLiveView({
144
137
  server.on("request", (req, res) => { if (!liveView.handle(req, res)) next(req, res); });
145
138
  server.on("upgrade", (req, socket, head) => { if (!liveView.upgrade(req, socket, head)) socket.destroy(); });
146
139
 
147
- const provider = liveViewProvider(cdpProvider({ chrome }), liveView); // wrap it as the recorder's `watch` wraps a provider
140
+ const provider = liveViewProvider(cdpProvider({ chrome }), liveView);
148
141
  createBrowserExtension({ provider: () => provider, onSession: (row) => { /* row.liveView.fullscreen is the viewer's URL */ }, ... });
149
142
  ```
150
143
 
@@ -198,7 +191,7 @@ Where the profile lives:
198
191
  - **Browserbase:** a Browserbase context. The provider keeps the map from profile name to context id in a file under the user's config directory, or in the store you pass.
199
192
  - **Kernel:** a Kernel profile of that name, created if it is not there.
200
193
 
201
- It is never your own browser's profile. The Chrome the pi extension starts has its own directory under a temporary root, and the pi extension has no flag for a saved profile.
194
+ It is never your own browser's profile.
202
195
 
203
196
  One session at a time may save to a profile in one process. A second saver is refused, and the message says why. Across processes, the last session to end wins. A profile name and a raw Browserbase context id cannot be asked for together.
204
197
 
@@ -209,12 +202,12 @@ One session at a time may save to a profile in one process. A second saver is re
209
202
  |---|---|---|
210
203
  | `snapshot` | The page's accessibility tree with bracketed ids: a working view for the next `run`. Never filed, so it is not citable evidence. | Reruns. |
211
204
  | `screenshot`, `browser_read` | Read the page. Each read is filed as evidence with its URL, SHA-256 and the offset into the session's recording. A screenshot is held to 2,000 px on its long edge. A `screenshot` can take a `clip` (CSS pixels from the viewport's top-left corner), an `id` from the latest snapshot or a CSS `selector` (scrolled into view first) to capture one region (a blank `id` or `selector`, or a clip of zero width and height, counts as not given); an empty or off-screen region, or an element that matches nothing or more than one, is refused with the typed envelope before any capture. Its `details.media` gives the image's path, type, size and the region. | Reruns. A read whose session was lost answers `session_replaced`. |
212
- | `browser_downloads` | Copy what the session downloaded into the host's workspace, with a manifest of SHA-256 sums. The pi extension lists it unless `fileTools` is false; the durable adapter lists it only when the host supplies `workspace`. | Reruns; files already there are skipped. |
213
- | `run` | Act: code, or a batch of ref actions. | Never reruns. The model is told the call may have taken effect and where the page was, and the identical code is refused once (`effect_unknown`). |
205
+ | `browser_downloads` | Copy what the session downloaded into the host's workspace, with a manifest of SHA-256 sums. The durable adapter lists it only when the host supplies `workspace`. | Reruns; files already there are skipped. |
206
+ | `run` | Act: code, or a batch of ref actions (`goto` takes a URL instead of an id). An AgentRun browser computer (raw CDP) takes actions only. | Never reruns. The model is told the call may have taken effect and where the page was, and the identical code is refused once (`effect_unknown`). |
214
207
  | `browser_release`, `browser_relaunch` | End the session; end it and open another. | Idempotent. A create carries a tag, so a rerun finds its session. |
215
208
  | `browser_request_handoff` | Hand the session to a person for a step only a human can do, and wait for the host's handoff port to say how it ended. While the person has it, every other call answers `waiting_for_human`. Listed only when the host gives a `handoff` port. | Reruns and waits on the same request; a request asked again carries the same `request_id`, which the port treats as one. |
216
209
  | `web_fetch`, `web_search` | Fetch a page or search, through the provider's services. | Reruns. |
217
- | `browser_upload` | Choose one workspace file in a file input on the page, as a person picking it would. Nothing is submitted; `run` submits the form afterwards. The pi extension lists it unless `fileTools` is false; the durable adapter lists it only when the host supplies `files` or `workspace`. | Never reruns. An upload the page does not answer fails at 60 s as possibly applied, and the identical retry is refused until the agent has looked at the page. |
210
+ | `browser_upload` | Choose one workspace file in a file input on the page, as a person picking it would. Nothing is submitted; `run` submits the form afterwards. The durable adapter lists it only when the host supplies `files` or `workspace`. | Never reruns. An upload the page does not answer fails at 60 s as possibly applied, and the identical retry is refused until the agent has looked at the page. |
218
211
  | `use_website` | Hand a task to another agent that works one website the host granted, in its own browser, and get its report. Listed only when the host passes `sites`. | A `request_id` that already finished answers its result without running again. A task that failed runs again. |
219
212
 
220
213
  `web_search` hits carry a `snippet` when the search has one: an excerpt of the page with its markdown links reduced to
@@ -255,7 +248,7 @@ Every failure is one envelope: `ok: false`, a `code`, `retryable`, `effect` (`no
255
248
  | `rate_limited` | The site or the provider answered 429. |
256
249
  | `waiting_for_human` | A person has the browser. |
257
250
 
258
- **Walls.** Naming a wall takes a judge. A host passes `decisions.classifyPage`, which gets the page's URL, status, content type and text, and answers one of eight classes: `captcha_or_bot_check`, `login_wall`, `paywall`, `region_or_geo_block`, `consent_interstitial`, `error_or_not_found`, `loading_or_js_required` or `empty_or_template`. A bot check or a region block files as `blocked`, and the others as `not_content`, each with a next step. With no judge, no page is classified. A fetch the site refuses with 401, 403, 451 or 999 still answers `blocked`. The pi extension passes no judge.
251
+ **Walls.** Naming a wall takes a judge. A host passes `decisions.classifyPage`, which gets the page's URL, status, content type and text, and answers one of eight classes: `captcha_or_bot_check`, `login_wall`, `paywall`, `region_or_geo_block`, `consent_interstitial`, `error_or_not_found`, `loading_or_js_required` or `empty_or_template`. A bot check or a region block files as `blocked`, and the others as `not_content`, each with a next step. With no judge, no page is classified. A fetch the site refuses with 401, 403, 451 or 999 still answers `blocked`.
259
252
 
260
253
  A host with a typed-question judge (Jev's `createJevRunner`, or the DSL's `runJudge`) builds the method with `createPageClassifier({ judge, budget?, maxPages?, redact? })`. `judge` is read on each page and must return a `PageJudge`; the page takes one request, which asks for its wall and for the probability that it carries instructions addressed to an AI reader. Its `injection` decision is marked at `INJECTION_THRESHOLD`. A side counts at `PAGE_WALL_THRESHOLD` (0.6). The run's page budget (`pageBudget`, `PAGE_GUARD_MAX_PAGES` pages by default) bounds how many pages are judged. An aborted page, a spent budget, and a judge that throws or answers in the wrong shape (a probability outside 0 to 1 included) each leave the page `unjudged` with no score. An answer where neither side reaches 0.6 leaves it `unjudged` and keeps its injection score: a page at or over `INJECTION_THRESHOLD` is withheld from a search's snippets and marked as an injection on a read, whatever its wall. Each records the reason in its `guard` record. The method never rejects.
261
254
 
@@ -268,7 +261,6 @@ What the package does with the credentials you register and the keys it recognis
268
261
  - **Page URLs.** Every query value is replaced (the names stay), and the fragment and the userinfo are dropped, before a URL is shown or filed.
269
262
  - **Where it runs.** The redactor runs over tool results, failure messages and details, the repeat guard's text, download reasons and the inputs to a page judge. It runs before any text is cut, filed or shown.
270
263
  - **The live view's address** is a full-control credential. It goes to the host's `onSession` and the handoff port, and nowhere else.
271
- - **Recordings.** The frame recorder keeps no frame while a password, a one-time-code field or a field it cannot read is on the page.
272
264
  - **Browserbase.** The provider dials Browserbase through a bound credential proxy, not the raw connect URL.
273
265
  - **Tested.** The wire tests (`test/wire/`) plant sentinel credentials in a fake provider and scan every byte a run produced: the run's entries and database, every request to the model, its reports, its evidence files and its process log. They look for each value raw, URL-encoded, hex- and base64-encoded, and for its head and tail.
274
266
 
@@ -276,23 +268,21 @@ What this does not cover: a value nobody registered and no shape matches, and wh
276
268
 
277
269
  ## Peers
278
270
 
279
- Stagehand, undici, zod and the two HTML packages are dependencies. Four optional peers cover the rest. Install only the ones you use:
271
+ Stagehand, undici, zod and the two HTML packages are dependencies. Three optional peers cover the rest. Install only the ones you use:
280
272
 
281
273
  | Peer | Needed for |
282
274
  |---|---|
283
- | `@earendil-works/pi-coding-agent` | `/coding-agent`. `pi install` supplies it. |
284
275
  | `@earendil-works/pi-durable` and `@earendil-works/chord` | `/durable`, the adapter for a pi-durable Harness. |
285
276
  | `@browserbasehq/sdk` | the Browserbase provider. Kernel needs no SDK. |
286
277
 
287
- The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.0` exactly, and `@earendil-works/pi-coding-agent` at any version, as pi's package guidance asks of the packages it supplies. CI tests pi 1.5.0.
278
+ The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.0` exactly. CI tests pi 1.5.0.
288
279
 
289
280
  ## Entries
290
281
 
291
282
  - `@parcha/pi-browser`: the host-neutral core. The model contract (tool names, descriptions, JSON schemas, effect and
292
283
  replay classes, the `browser` and `web` prompt sections), the typed failure envelope, the redactor, the screenshot
293
284
  budget, the repeat guard, evidence and decision-hook types, usage and prices, `find` (chunking and ranking a long page),
294
- `browser_downloads`, the opt-in request observer, and the provider interface. The public-host guard under the coding
295
- agent's HTTP backup is here too: `publicFetch(url, { lookup?, fetchImpl?, signal?, maxBytes? })` and
285
+ `browser_downloads`, the opt-in request observer, and the provider interface. The public-host guard is here too: `publicFetch(url, { lookup?, fetchImpl?, signal?, maxBytes? })` and
296
286
  `readPage(html, url, { deadlineMs?, signal? })`, with `isPrivateAddress` and `pinnedLookup`. `readPage` never holds
297
287
  the event loop: it drops a page's script, style, svg, noscript and template blocks, cuts what is left at
298
288
  `READ_MAX_CHARS` (`truncated`, with the page's length in `html_chars`), and converts it to markdown in a worker thread
@@ -303,87 +293,33 @@ The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.0` exactly, and `
303
293
  - `/durable`: the pi-durable adapter. `createBrowserExtension` is session custody in the run's own store (a create is
304
294
  committed before the provider is called, release is a durable task, reconcile runs at run open). `createWebExtension` is
305
295
  `web_fetch` and `web_search`.
306
- - `/coding-agent`: the pi coding agent's extension, described under [For pi users](#for-pi-users). `pi install` loads it.
307
296
  - `/driver/stagehand`: `stagehandDriver()`, Stagehand v4 over upstream's facade, vendored unedited in
308
297
  `src/vendor/stagehand-facade/`. `UPSTREAM.json` names the commit and each file's blob id and SHA-256;
309
298
  `node scripts/vendor-facade.mjs --check` verifies them and `--commit SHA --release NAME` re-vendors. Stagehand is created
310
299
  sealed: no inference, no cache, and no trace endpoint, so no trace is exported. Stagehand attaches one client to a browser
311
300
  at a time: closing a driver disconnects it, so the next attach is allowed.
301
+ - `/driver/cdp`: `cdpDriver()`, the driver of every AgentRun browser computer (Browserbase's, Kernel's, or the computer
302
+ package's `local` provider's Chrome on this machine), over its CDP URL. It is raw CDP: no Stagehand, and nothing loaded into the browser. `snapshot` is Chrome's
303
+ accessibility tree with the same "frame-node" ids (`[0-42]`: the frame's place, then Chrome's backend node id). `run`
304
+ takes actions only. Each action is scrolled into view, hit-tested at its centre, and pressed and released there, or
305
+ typed with inserted text and a real last key. Each answers one line: `[ok] click [0-42] button "Add" -> page changed`
306
+ (or `navigated to <url>`, or `no change`). `run` code is refused in words, and navigation is
307
+ `{"op":"goto","url":"https://..."}`. A frame another site runs in its own process (a cross-origin iframe) is not read:
308
+ the snapshot names each one it left out. Adapted from Browser Use Pi's `ax.ts`, `cdp.ts` and `page.ts` under its MIT
309
+ license, in `src/vendor/browser-use-pi/` (see NOTICE and that folder's `UPSTREAM.json`).
312
310
  - `/providers/browserbase`, `/providers/kernel`, `/providers/cdp`: where browsers come from. Browserbase through its SDK,
313
311
  with the credential-proxy dial and the connect-URL rewrite. Kernel through its REST API on the package's own HTTP agent.
314
312
  Any CDP endpoint, or a local Chrome the provider starts and kills by exact pid.
315
313
  - `/providers/chrome-args`: `chromeArgs()`, the arguments the cdp provider starts a local Chrome with, and `extensionOrigin()`,
316
314
  the one Origin its DevTools socket allows (Stagehand's extension). A host that starts its own Chrome for Stagehand takes them
317
- from here rather than copying Stagehand's `--remote-allow-origins=*`.
318
- - `/providers/assigned`: `assignedSessionProvider()`, over the one session a host assigned to the run. It never creates or
319
- ends a browser: it hands that session to one custody at a time, and the host takes it back itself.
315
+ from here rather than copying Stagehand's `--remote-allow-origins=*`. `findChrome()` finds the Chrome to start: the one
316
+ `PI_BROWSER_CHROME` or `CHROME_PATH` names, else `google-chrome` or `chromium` on the PATH, else the usual install locations.
320
317
  - `/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
321
318
  [The live view of your own Chrome](#the-live-view-of-your-own-chrome).
322
- - `/recorder`: `frameRecorder()` screencasts each session over DevTools into a sink you pass, and `exportFrameTracks()`
323
- makes a WebM per session from the recorded frames. See [Recording what the browsers show](#recording-what-the-browsers-show).
324
319
  - `/testing`: the shared test fake. A provider backend with a ledger of every call, a credential broker, an HTTP face so the
325
320
  ledger outlives a killed child process, a driver over in-memory pages, and sentinel credentials. A host's composition
326
321
  test and this package's crash matrix use the same one.
327
322
 
328
- ## For pi users
329
-
330
- The pi coding agent gets `snapshot`, `run`, `screenshot`, `browser_read`, `browser_relaunch`, `browser_release` and
331
- `web_fetch` (plus `web_search` when the provider offers one). It opens a Chrome of its own on first use, reads and drives
332
- pages through Stagehand, files every page and screenshot with the page's URL and a SHA-256, and closes the Chrome when you
333
- release it, after three idle minutes, or when the session ends. Nothing starts until the model's first browser call.
334
-
335
- The local browser needs Chrome or Chromium: the one named by `--browser-chrome` or `PI_BROWSER_CHROME`, else `CHROME_PATH`,
336
- else the first of `google-chrome`, `chromium` and the usual install locations (`/opt/google/chrome/chrome`, Chrome in
337
- `/Applications`, Chrome in `Program Files`). It is tested on Linux; macOS and Windows are not verified.
338
-
339
- | Setting | Meaning |
340
- |---|---|
341
- | `--browser-chrome PATH`, `PI_BROWSER_CHROME` | The Chrome to start. A path that does not exist is refused by name, never replaced. |
342
- | `--browser-headed`, `PI_BROWSER_HEADED=1` | Show the window instead of running headless. |
343
- | `--browser-no-sandbox`, `PI_BROWSER_NO_SANDBOX=1` | Start Chrome without its sandbox. Needed as root, in a container, or where user namespaces are restricted. Use it only for pages you trust. |
344
- | `--browser-endpoint URL`, `PI_BROWSER_ENDPOINT` | Attach to a Chrome you already run (`http://host:port` or `ws://`) instead of starting one. Releasing leaves it running. Stagehand attaches one client to a browser at a time, so a second pi on the same Chrome is refused until the first lets go, and the Chrome must hold at most one Stagehand extension. |
345
- | `--browser-provider browserbase`, `PI_BROWSER_PROVIDER` | Use Browserbase. Needs `BROWSERBASE_API_KEY` (`BB_API_KEY` also works); a missing key is refused by name. `PI_BROWSER_PROXIES=1` turns on its proxies. |
346
- | `--browser-provider kernel`, `PI_BROWSER_PROVIDER` | Use Kernel. Needs `KERNEL_API_KEY`; a missing key is refused by name. `KERNEL_BASE_URL` points at another Kernel API. `PI_BROWSER_STEALTH=1` turns on Kernel's stealth mode. |
347
-
348
- What it does with your machine and your data:
349
-
350
- - The Chrome it starts has its own profile directory under a temporary root and a free debugging port, never your browser's
351
- profile and never port 9222. The profile is deleted when the browser is released.
352
- - Pages and screenshots are filed under `<project>/.pi/browser/evidence/`, each as a receipt (`tool`, `args`, `status`, the
353
- page's final URL and title, `sha256`, then the body). A credential-shaped query parameter in a URL, a Bearer value and a
354
- key of the shapes Stagehand knows are replaced by `[redacted]` before anything is filed, shown to the model or stored.
355
- - Each browser session is appended to the pi session file (`browser.session` entries; the model never sees them). The coding
356
- agent has no mid-turn resume, so a resumed session gets a fresh browser: cookies and page state do not carry over. A Chrome
357
- that a crashed pi left running is closed when that session is next started, never adopted.
358
- - Stagehand is given no trace endpoint, so it exports no traces: nothing you browse goes to a third party.
359
- - `browser_relaunch` with `verified` or `geolocation` changes nothing on a local Chrome or on Kernel; they are Browserbase features.
360
- With proxies off (the default), a `geolocation` is refused and the session is left as it was, as in the pi-durable adapter.
361
- - A host that builds the extension with `policy: { actions: "deny" }` or `"ask"` asks for requests to be held, and the coding
362
- agent has no request observer to hold them. So under either it starts no browser: every browser tool answers
363
- `browser_unavailable`, naming the action policy, and `web_fetch` still works. Set `actions: "allow"` (or leave it out) to
364
- browse, or use the pi-durable adapter (`/durable`), which holds requests under `deny` and `ask`.
365
-
366
- Providers and `web_fetch`:
367
-
368
- - Without a fetch service, `web_fetch` reads public hosts only. It refuses loopback, private, link-local and other
369
- special-purpose addresses and any port but 80 and 443 at every redirect hop, anything over 5 MiB, and non-text, and it
370
- sends no cookies or credentials. The call's signal bounds every hop, its name lookup included.
371
- - A PDF the fetch service will not convert to markdown (Browserbase answers HTTP 400) is fetched once more as the raw file.
372
- The coding agent has no PDF text extractor, so `web_fetch` says the URL is a PDF and that `format: "raw"` returns its
373
- bytes, base64-encoded. A host with an extractor passes `pdf: { text(bytes, url, signal) }` to `createWebExtension`; the text
374
- it returns is answered and filed as the page (`extractor: pdf-text`, judged by `classifyPage` like any page). A PDF over
375
- 32 MiB is not handed to it, and it gets 120 s (`maxBytes`, `timeoutMs`); a PDF with no text says so.
376
- - On Kernel, each session is tagged with its run and lease tag, so a crashed pi's session is found again by tag. It is
377
- created with an idle timeout equal to the idle release (three minutes), so Kernel ends a browser nobody is connected to if
378
- pi dies, and a release deletes it and waits until Kernel shows it gone. Stagehand's extension must be stored in your Kernel
379
- project: a stored extension with the same bytes (Kernel's checksum) is used whatever its name and never changed, and
380
- otherwise the first session uploads it once as `agentrun-stagehand-<sha256 prefix>`. A plan with no room for it fails the
381
- launch naming `insufficient_plan`. Kernel's live view is not offered, because its API has no read-only form of it. Kernel
382
- calls go direct, never through `HTTP(S)_PROXY`, as Browserbase's do; a host behind a proxy passes its own `fetch` to `kernelProvider`.
383
-
384
- Limits: a crash loses the in-flight turn and the browser with it. `pi install` pulls Stagehand, about 40 MB and 52 packages
385
- with its dependencies.
386
-
387
323
  ## For hosts
388
324
 
389
325
  Any pi-durable `Harness` can install the extensions. A local Chrome is the default provider and costs nothing.
@@ -466,100 +402,14 @@ and `search`.
466
402
 
467
403
  Two things to know before you give a model a browser:
468
404
 
469
- - **What a model may reach is your decision.** `web_fetch` takes only absolute `http(s)` URLs with no credentials, and the
470
- coding agent's built-in fetch refuses private addresses, but a provider's fetch service and a driven browser go wherever
405
+ - **What a model may reach is your decision.** `web_fetch` takes only absolute `http(s)` URLs with no credentials, and
406
+ `publicFetch` refuses private addresses, but a provider's fetch service and a driven browser go wherever
471
407
  their network goes. A host that must not let a model reach internal addresses restricts that network or the URLs it passes.
472
408
  - **The Browserbase provider changes the process.** Its first call that needs the Browserbase client adds Browserbase's hosts to `NO_PROXY` and `no_proxy`, and
473
409
  the first attach replaces `globalThis.WebSocket` with a wrapper that dials a bound credential proxy instead of the raw
474
410
  connect URL. Both are process-wide. The wrapper passes every other URL through unchanged. Importing the package does
475
411
  neither.
476
412
 
477
- ### Recording what the browsers show
478
-
479
- `@parcha/pi-browser/recorder` screencasts each session over DevTools (a local Chrome, Browserbase and Kernel all speak it) and hands
480
- `agentrun.recording/1`'s `frame` and `frame.gap` lines, with their JPEGs, to a sink you pass. It is read-only beside the session's own
481
- connections, and it writes nothing itself.
482
-
483
- ```js
484
- import { frameRecorder } from "@parcha/pi-browser/recorder";
485
-
486
- const frames = frameRecorder({
487
- clock: () => Date.now() - started, // ms since the recording started: every line's `t`
488
- gen: () => generation, // optional: this process's generation, on every line
489
- lastFrameAt: (session) => lastFrameT(session), // optional: where an earlier process's frames for a session stopped
490
- sink: (line, blobs = {}) => { // blobs: sha256 hex -> JPEG bytes; the sink keeps blobs/<sha256>.jpg and adds `seq`
491
- for (const [sha, bytes] of Object.entries(blobs)) fs.writeFileSync(`blobs/${sha}.jpg`, bytes);
492
- events.write(JSON.stringify({ ...line, seq: seq++ }) + "\n");
493
- },
494
- });
495
- const browser = createBrowserExtension({ provider: ({ conversationId }) => frames.watch(provider, conversationId), driver, evidence });
496
- ```
497
-
498
- A session is captured from the moment it is created or reattached (so after a kill the same session resumes by itself). The lines:
499
-
500
- ```json
501
- {"channel":"live","source":"browser","kind":"frame","gen":1,"t":20123,"conv":3,"data":{"session":"bb_4e1a","provider":"browserbase","w":800,"h":500,"mime":"image/jpeg"},"blobs":["9c0e..."]}
502
- {"channel":"live","source":"browser","kind":"frame.gap","gen":2,"t":26004,"conv":3,"data":{"session":"bb_4e1a","from":21004,"reason":"process_killed"}}
503
- ```
504
-
505
- - Capture is JPEG at quality 60, at most 800 px wide and 10 frames a second per session (the newest frame wins), of the page the agent is using.
506
- Every line carries the `conv` of the conversation that owns the session (given to `watch`, or read from the lease tag); a session whose
507
- conversation cannot be told is not recorded.
508
- - A gap is written, never filled: `process_killed` when a session this process did not create is taken up and `lastFrameAt` knows its last
509
- frame, `session_released` when the session is released, `credential_on_page` while a credential is on the page.
510
- - **No frame is kept while a credential or a code is on the page**, and anything the recorder cannot read counts as one being there. A frame is
511
- judged against the page the moment it arrives (one check, standing for the page at its capture) and again when its turn to be kept comes (both
512
- checks go through one pace per session: each is sent at least 50 ms after the last, so a session sends at most 20 `Runtime.evaluate` in any
513
- second, however fast frames arrive); a credential seen in either drops it, and a frame held across a navigation or a move to another page is not kept. The check looks at password
514
- fields, `one-time-code` fields and fields named like a code (name, id, `<label>`, `aria-labelledby`, `aria-label` or placeholder says otp, totp,
515
- 2fa, passcode, ...) that hold a value, in the page, open shadow roots and same-origin frames; a value typed and cleared between two checks is
516
- still seen (the page keeps a flag, `window.__piFramesSecret`, set by the fields' own `input` events). A page that nests deeper than the check
517
- reads (eight shadow roots or frames) and a visible frame whose content it cannot reach (another origin: a payment or sign-in widget) count as
518
- a credential present; a frame with no area, or not displayed, is not a picture of anything and does not. A page that cannot be checked at all
519
- is not recorded. The pause lasts until the page navigates and the check is clean; the gap says why in `data.detail` (`field`, `typed`,
520
- `too_deep`, `unreadable_frame` or `host`). What no script in the page can see (a closed shadow root, a value set by script with no event) is the
521
- host's to pause with `frames.pause(session)` (lifted with `frames.resume(session)`).
522
- A host that lets a person drive a session (the live view) passes `hold: (ref) => boolean`: while it answers `true` for a session no frame is stored and one gap
523
- (`credential_on_page`, detail `host`) marks the span, not one per skipped frame; when it answers `false` frames resume. A hold that throws counts as `true`.
524
- The screencast sends a frame only when the page repaints, and a person's login has often already left the page, so when a hold lifts the recorder captures one frame of the page as it is then (a one-off screenshot of the followed session, judged like any other: a field still holding a credential makes it the credential gap, not a frame); a capture that fails costs that frame only. No new option. A withheld frame never counts as the last frame kept, so a `session_released` gap inside a hold starts at the last frame stored before it.
525
- - A live-view URL is never recorded or asked for: the recorder reads only the session's DevTools socket and never writes its address.
526
- - Lines reach the sink one at a time, in order. A sink that throws, rejects or does not answer within `sinkTimeoutMs` (5 s) cannot fail a browser
527
- call: that line is dropped and counted in `frames.stats()`, and a frame that was not saved never becomes the point a later gap starts from.
528
- - `frames.watch(...).release` ends the capture, and writes the `session_released` gap, once the provider has released the session: a release it
529
- refuses leaves the capture running.
530
- - **`frame.track`** (a WebM per session with an index) is made at export, from the recorded frames, by `exportFrameTracks`:
531
-
532
- ```js
533
- import { exportFrameTracks } from "@parcha/pi-browser/recorder";
534
- const tracks = await exportFrameTracks({ lines, readBlob: (sha256) => bytesOfBlob(sha256), endAt: recordingEndMs, fps: 10 });
535
- for (const { line, blobs } of tracks) { /* line is the frame.track line; blobs holds the WebM and its index by sha256 */ }
536
- ```
537
-
538
- One track per session that has a frame. The video is VP9 at a constant `fps` (default 10) on one canvas, the largest frame in even numbers (a smaller
539
- frame is centred on it); each frame is shown until the next one, and while a gap lasts the video shows a slate: from the moment a
540
- `credential_on_page` or `session_released` gap was written, and from the last frame the earlier process saved for a `process_killed` gap (nothing is
541
- known after it). The track runs from the session's first frame to `endAt` (default: the last line, a lone frame lasting one frame's time). The line is
542
- `{ kind: "frame.track", t: <the track's end>, conv, data: { session, fps, from, to }, blobs: [<webm sha256>, <index sha256>] }`; the index (JSON) lists every
543
- frame with its `t` and its `ms` offset into the video, and every gap with `from`, `to`, `reason` and `detail`, so a viewer maps a time in the recording to a
544
- time in the video (`t - from`). A frame whose blob is missing, does not hash to its name or is not a JPEG shows the slate and is reported in `skipped`.
545
- The step starts `ffmpeg` (`ffmpeg` option: a path; default the one on the PATH) in a private temporary directory with `PATH`, `LANG`, `LC_ALL` and `HOME`
546
- only, with fixed arguments and no URL, a timeout (`timeoutMs`, 120 s) and an `AbortSignal`; a failure is a `TrackExportError` (`ffmpeg_missing`,
547
- `ffmpeg_failed`, `ffmpeg_timeout`, `aborted`) and writes nothing.
548
-
549
- ## How it compares
550
-
551
- Our own bench, run by this package's authors with `gpt-6-luna` only, 3 samples per case, against `pi-agent-browser-native`
552
- 0.9.3 on the same prompts and model. Five cases are public-registry lookups (two behind walls, where abstaining is the right
553
- answer); three are loopback fixtures. Treat it as ours, not independent.
554
-
555
- - Local Chrome, 48 runs: no wrong answers from either; median $0.0013 a run against $0.0024, 6 tool calls against 9, 7 tool
556
- errors in 180 calls against 85 in 260, and no process left running after a run, against a browser daemon left after each one.
557
- - Browserbase, 30 runs: a tie on outcomes (5 correct, 10 abstentions, 0 wrong for each). This package's median was $0.0034 a
558
- run against $0.0046, with more tool calls on the walled cases (16 against 12).
559
- - A crash in the middle of a form submit is covered by neither: with a scripted model both submitted twice, and a resumed
560
- model that was not told about the cut call repeated the submit in 0 of 10 runs for each.
561
- - Much of the other arm's tool-error count is how luna calls that tool, not the extension. Another model may give other numbers.
562
-
563
413
  ## Development
564
414
 
565
415
  ```sh
@@ -568,7 +418,7 @@ npm test -w @parcha/pi-browser # everything but the real-Chrome su
568
418
  CHROME_PATH=/path/to/chrome npm run test:chrome -w @parcha/pi-browser
569
419
  ```
570
420
 
571
- The real-Chrome suites (`stagehand_real_chrome`, `cdp_local_chrome`, `effects-chrome`, `coding_agent_real_chrome`,
421
+ The real-Chrome suites (`stagehand_real_chrome`, `cdp_local_chrome`, `effects-chrome`, `screenshot_clip_real_chrome`,
572
422
  `readme_example`) skip with a typed reason where no Chrome can load Stagehand's extension, and fail instead under
573
423
  `AGENTRUN_REQUIRE_LOCAL_CHROME=1`, which CI sets. The crash matrix (`test/custody.test.mjs`) SIGKILLs a child process at each
574
424
  cut point of a session's life against the shared fake and reopens the run's SQLite file. The wire checks (`test/wire/`) plant
@@ -12,7 +12,7 @@ const object = (properties, required = []) => ({ type: "object", additionalPrope
12
12
  const snapshot = {
13
13
  name: "snapshot",
14
14
  label: "Browser: snapshot",
15
- description: "Capture the active page's Stagehand accessibility tree and hydrate its displayed IDs for subsequent run actions. Every call replaces the active page's ID map.",
15
+ description: "Capture the active page's accessibility tree and hydrate its displayed IDs for subsequent run actions. Every call replaces the active page's ID map. On an agent's browser computer a frame another site runs in its own process is not in the tree: the snapshot names each frame it left out.",
16
16
  parameters: object({ includeIframes: { type: "boolean", default: true } }),
17
17
  effect: "read", replay: "safe", executionMode: "sequential", evidence: "none", listedWhen: "always",
18
18
  };
@@ -22,8 +22,8 @@ export const BROWSER_KEEPS = Object.freeze({
22
22
  cookies: "It keeps cookies across pages: use it for a page that depends on an earlier one, or one that sets cookies.",
23
23
  signIns: "It keeps this agent's saved sign-ins and cookies: use it for anything behind a sign-in, or a page that depends on an earlier one.",
24
24
  });
25
- const runDescription = (signIns) => `Browse and automate websites in the persistent Stagehand browser. ${signIns ? BROWSER_KEEPS.signIns : BROWSER_KEEPS.cookies} ` +
26
- 'Navigate with JavaScript such as await page.goto("https://example.com"); there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Code is the body of an async function with page, context and browser in scope: `return` the value you want back. Provide exactly one of code or actions. Each action must use "op" (never "kind") and "id" (never "ref"). Copy the bracketed snapshot ID as a string. Examples: {"actions":[{"op":"click","id":"1-42"}]}, {"actions":[{"op":"fill","id":"2-14","value":"Miami"}]}, {"actions":[{"op":"select","id":"3-9","values":"Lowest price"}]}.';
25
+ const runDescription = (signIns) => `Browse and automate websites in the persistent browser. ${signIns ? BROWSER_KEEPS.signIns : BROWSER_KEEPS.cookies} ` +
26
+ 'Navigate with JavaScript such as await page.goto("https://example.com"), or with a goto action; there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Code is the body of an async function with page, context and browser in scope: `return` the value you want back. Provide exactly one of code or actions. An agent\'s browser computer (Browserbase, Kernel or Local Chrome) takes actions only: code is refused there. Each action must use "op" (never "kind") and "id" (never "ref"), but goto, which takes a "url". Copy the bracketed snapshot ID as a string. Examples: {"actions":[{"op":"goto","url":"https://example.com"}]}, {"actions":[{"op":"click","id":"1-42"}]}, {"actions":[{"op":"fill","id":"2-14","value":"Miami"}]}, {"actions":[{"op":"select","id":"3-9","values":"Lowest price"}]}.';
27
27
  const run = {
28
28
  name: "run",
29
29
  label: "Browser: run",
@@ -33,9 +33,18 @@ const run = {
33
33
  code: { type: "string", minLength: 1 },
34
34
  actions: {
35
35
  type: "array",
36
- description: 'Snapshot actions with the exact fields "op" and "id". Do not use "kind" or "ref".',
36
+ description: 'Snapshot actions with the exact fields "op" and "id" (goto: "op" and "url"). Do not use "kind" or "ref".',
37
37
  items: {
38
38
  oneOf: [
39
+ {
40
+ type: "object",
41
+ properties: {
42
+ op: { const: "goto", description: 'Action operation. Use "op": "goto"; never use a "kind" field.' },
43
+ url: { type: "string", description: "The http or https URL to open in the active page (or about:blank)." },
44
+ },
45
+ required: ["op", "url"],
46
+ additionalProperties: false,
47
+ },
39
48
  actionSchema("click"),
40
49
  actionSchema("hover"),
41
50
  actionSchema("fill", { value: { type: "string" } }),
@@ -182,7 +191,7 @@ export function browserSection(policy, offered = {}) {
182
191
  return [
183
192
  "You control one remote browser:",
184
193
  "- snapshot: the active page's accessibility tree, with bracketed element IDs for run actions.",
185
- "- run: snapshot actions by ID, or JavaScript against the Playwright-shaped page API. Pass exactly one of code or actions; every action uses \"op\" and \"id\", never \"kind\" or \"ref\".",
194
+ "- run: snapshot actions by ID, or JavaScript against the Playwright-shaped page API. Pass exactly one of code or actions; every action uses \"op\" and \"id\" (a goto action \"op\" and \"url\"), never \"kind\" or \"ref\". An agent's browser computer takes actions only.",
186
195
  "- screenshot: the rendered page as an image.",
187
196
  "- browser_read: the current page's content, filed as evidence with its URL.",
188
197
  "- browser_relaunch: a fresh session, Verified or egressing from a given place.",
@@ -151,7 +151,13 @@ export declare class FenceRefusal extends BrowserFailureError {
151
151
  /** How many calls a fenced driver has let through; null for a driver that is not fenced. */
152
152
  export declare const passedThrough: (driver: object) => number | null;
153
153
  export declare function fenced<D extends BrowserDriver>(driver: D, fence: number, mark: () => FenceMark | undefined): D;
154
+ /** The wait between tries of a call that failed (a provider's release, a lookup, an answer that could not be read):
155
+ * doubling from 500 ms up to 30 s. */
154
156
  export declare const backoffMs: (attempt: number) => number;
157
+ /** How often a hand-over's wait asks for the person's answer while it is pending: a short fixed interval, as the host
158
+ * settles an answer (serve's browser-person poll is 500 ms), so a hand-back resumes the agent within one poll however
159
+ * long the person took. An answer is a cheap read on the host's side; only a read that fails backs off (backoffMs). */
160
+ export declare const HANDOFF_POLL_MS = 500;
155
161
  export declare const notices: {
156
162
  kept: (url: string | null) => string;
157
163
  lost: (url: string | null) => string;
@@ -54,7 +54,13 @@ export function fenced(driver, fence, mark) {
54
54
  },
55
55
  });
56
56
  }
57
+ /** The wait between tries of a call that failed (a provider's release, a lookup, an answer that could not be read):
58
+ * doubling from 500 ms up to 30 s. */
57
59
  export const backoffMs = (attempt) => Math.min(30_000, 500 * 2 ** attempt);
60
+ /** How often a hand-over's wait asks for the person's answer while it is pending: a short fixed interval, as the host
61
+ * settles an answer (serve's browser-person poll is 500 ms), so a hand-back resumes the agent within one poll however
62
+ * long the person took. An answer is a cheap read on the host's side; only a read that fails backs off (backoffMs). */
63
+ export const HANDOFF_POLL_MS = 500;
58
64
  export const notices = {
59
65
  kept: (url) => `Your browser session survived an interruption and is still open${url ? ` on ${url}` : ""}. Take a snapshot before acting again.`,
60
66
  lost: (url) => `Your browser session ended during an interruption. The next browser call opens a fresh session with no cookies or page state${url ? `; the last page was ${url}` : ""}.`,
@@ -81,6 +81,9 @@ function epochFenced(driver, gate, epoch) {
81
81
  await check.call(target, list);
82
82
  let completed = 0;
83
83
  let url;
84
+ // A driver that answers each action with its line of what changed (the raw-CDP driver's): the batch answers
85
+ // with every line, in order, as that driver's own batch does.
86
+ const lines = [];
84
87
  for (const [index, action] of list.entries()) {
85
88
  if (moved())
86
89
  throw new FenceRefusal(personTookFailure(acted, { completed, of: list.length }));
@@ -90,17 +93,29 @@ function epochFenced(driver, gate, epoch) {
90
93
  // The batch was checked as one before any was sent, as the browser's own batch checks it once: an action after
91
94
  // the first is not refused because the page's address moved under the batch's own earlier actions (a
92
95
  // same-page link). The person's take-over is still fenced before each one, above.
93
- answer = (await value.call(target, index === 0 ? { actions: [action] } : { actions: [action], checked: true }));
96
+ // `rest`: how many follow, for a driver that stops the batch here (it moved to another tab) to say so.
97
+ const rest = list.length - index - 1;
98
+ answer = (await value.call(target, { actions: [action], ...(index === 0 ? {} : { checked: true }), ...(rest ? { rest } : {}) }));
94
99
  }
95
100
  catch (error) {
96
101
  if (completed > 0)
97
102
  throw partway(error, completed, list.length);
98
103
  throw error;
99
104
  }
105
+ if (typeof answer === "string") {
106
+ lines.push(answer);
107
+ completed += 1;
108
+ // The action moved the driver to another tab (a popup it opened): the batch's later actions name the old
109
+ // tab's ids, so none is sent; the driver's answer says how many were not run.
110
+ const movedTab = target.movedTab;
111
+ if (typeof movedTab === "function" && movedTab.call(target))
112
+ return lines.join("\n");
113
+ continue;
114
+ }
100
115
  completed += typeof answer?.completed === "number" ? answer.completed : 1;
101
116
  url = answer?.url;
102
117
  }
103
- return { completed, url };
118
+ return lines.length === list.length ? lines.join("\n") : { completed, url };
104
119
  })();
105
120
  };
106
121
  },
@@ -219,8 +219,8 @@ export type SiteInfo = {
219
219
  title: string;
220
220
  description: string;
221
221
  };
222
- /** Runs one child agent that has the browser tools and no use_website, and answers its final text. The adapter supplies
223
- * it: a pi session for the coding agent, a task-owned conversation for pi-durable. */
222
+ /** Runs one child agent that has the browser tools and no use_website, and answers its final text. The durable adapter
223
+ * supplies it: a task-owned conversation. */
224
224
  export type ChildRunner = (task: {
225
225
  site: string;
226
226
  requestId: string;
@@ -14,6 +14,9 @@ import type { Geo } from "./host.js";
14
14
  * compiles the whole of it as a single expression (compiled, never run). Any other code reaches the driver unchanged. */
15
15
  export declare function runnableCode(code: string): string;
16
16
  export type RunAction = {
17
+ op: "goto";
18
+ url: string;
19
+ } | {
17
20
  op: "click";
18
21
  id: string;
19
22
  } | {
@@ -48,7 +51,13 @@ export type PageDriver = BrowserDriver & {
48
51
  code?: string;
49
52
  actions?: RunAction[];
50
53
  checked?: true;
54
+ rest?: number;
51
55
  }): Promise<unknown>;
56
+ /** Whether the last `run` moved the driver to another tab (it followed a tab the page opened, or left one that
57
+ * closed): the batch's actions after it name the old tab's ids, so driving-guard sends none of them. `rest`, given to
58
+ * `run`, is how many of the batch's actions follow the ones it was sent, for its answer to say they were not run.
59
+ * Optional: a driver that never changes tabs has neither. */
60
+ movedTab?(): boolean;
52
61
  /** The page's URL, cheaply: no page content is read. */
53
62
  url(): Promise<string>;
54
63
  /** Drops every snapshot's element ids, so an action by an old id fails as a stale snapshot (a person changed the page, whatever its URL). Optional:
@@ -0,0 +1,6 @@
1
+ import type { DriverFactory } from "../core/custody.js";
2
+ import type { PageDriver } from "../core/tools.js";
3
+ /** What `run` with code is told on this browser. */
4
+ export declare const CDP_CODE_REFUSED = "run code is not available on this browser (the agent's browser computer): send actions instead, each an op with a snapshot id and a value, for example {\"actions\":[{\"op\":\"click\",\"id\":\"0-42\"}]}, and navigate with {\"actions\":[{\"op\":\"goto\",\"url\":\"https://example.com\"}]}. Read the page with browser_read.";
5
+ /** The raw-CDP page driver: snapshot ids and actions only. */
6
+ export declare function cdpDriver(): DriverFactory<PageDriver>;