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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/NOTICE +30 -0
  3. package/README.md +33 -199
  4. package/dist/core/contract.d.ts +9 -6
  5. package/dist/core/contract.js +22 -34
  6. package/dist/core/custody.d.ts +6 -0
  7. package/dist/core/custody.js +6 -0
  8. package/dist/core/driving-guard.js +17 -2
  9. package/dist/core/evidence.d.ts +1 -1
  10. package/dist/core/files.d.ts +3 -0
  11. package/dist/core/files.js +4 -1
  12. package/dist/core/host.d.ts +0 -63
  13. package/dist/core/redact.d.ts +0 -2
  14. package/dist/core/redact.js +0 -32
  15. package/dist/core/session-control.d.ts +0 -2
  16. package/dist/core/session-control.js +0 -5
  17. package/dist/core/tools.d.ts +9 -0
  18. package/dist/core/usage.d.ts +0 -2
  19. package/dist/core/usage.js +0 -2
  20. package/dist/core/web.d.ts +2 -111
  21. package/dist/core/web.js +0 -443
  22. package/dist/driver/cdp.d.ts +6 -0
  23. package/dist/driver/cdp.js +245 -0
  24. package/dist/driver/page-driver.js +29 -3
  25. package/dist/durable/store.js +13 -4
  26. package/dist/durable.d.ts +2 -12
  27. package/dist/durable.js +9 -80
  28. package/dist/index.d.ts +0 -1
  29. package/dist/index.js +0 -1
  30. package/dist/live-view/provider.d.ts +2 -2
  31. package/dist/live-view/provider.js +2 -2
  32. package/dist/live-view/server.d.ts +1 -1
  33. package/dist/providers/browserbase.d.ts +0 -31
  34. package/dist/providers/browserbase.js +2 -27
  35. package/dist/providers/chrome-args.d.ts +3 -0
  36. package/dist/providers/chrome-args.js +13 -2
  37. package/dist/testing/backend.d.ts +2 -21
  38. package/dist/testing/backend.js +1 -25
  39. package/dist/vendor/browser-use-pi/ax.d.ts +106 -0
  40. package/dist/vendor/browser-use-pi/ax.js +642 -0
  41. package/dist/vendor/browser-use-pi/cdp.d.ts +19 -0
  42. package/dist/vendor/browser-use-pi/cdp.js +106 -0
  43. package/dist/vendor/browser-use-pi/page.d.ts +38 -0
  44. package/dist/vendor/browser-use-pi/page.js +112 -0
  45. package/package.json +7 -25
  46. package/src/vendor/browser-use-pi/UPSTREAM.json +25 -0
  47. package/src/vendor/stagehand-facade/UPSTREAM.json +0 -4
  48. package/dist/coding-agent-local.d.ts +0 -12
  49. package/dist/coding-agent-local.js +0 -72
  50. package/dist/coding-agent.d.ts +0 -135
  51. package/dist/coding-agent.js +0 -641
  52. package/dist/core/sites.d.ts +0 -33
  53. package/dist/core/sites.js +0 -104
  54. package/dist/durable/web.d.ts +0 -47
  55. package/dist/durable/web.js +0 -41
  56. package/dist/providers/assigned.d.ts +0 -18
  57. package/dist/providers/assigned.js +0 -75
  58. package/dist/recorder/credential.d.ts +0 -9
  59. package/dist/recorder/credential.js +0 -49
  60. package/dist/recorder/follow.d.ts +0 -36
  61. package/dist/recorder/follow.js +0 -163
  62. package/dist/recorder/frames.d.ts +0 -87
  63. package/dist/recorder/frames.js +0 -377
  64. package/dist/recorder/index.d.ts +0 -4
  65. package/dist/recorder/index.js +0 -7
  66. package/dist/recorder/jpeg.d.ts +0 -8
  67. package/dist/recorder/jpeg.js +0 -70
  68. package/dist/recorder/track.d.ts +0 -107
  69. package/dist/recorder/track.js +0 -280
  70. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +0 -15
  71. package/dist/vendor/stagehand-facade/screenshot-transport.js +0 -51
package/CHANGELOG.md CHANGED
@@ -2,6 +2,31 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.1.0-beta.35 (2026-11-11)
6
+
7
+ - The `use_website` tool is removed from the durable adapter: no host passed `sites`. Gone with it: `createBrowserExtension`'s `sites` option, the handle's `docs.Children`, the root exports `useWebsite`, `useWebsiteContract` and `localSites`, and the types `SiteInfo`, `SiteRunPort` and `ChildRunner`. A host that wants an agent to hand a task to another agent runs that agent itself.
8
+ - The durable adapter's own `web_fetch` and `web_search` are removed: no host used them (AgentRun's server runs its own web tools). Gone: `createWebExtension` and `WebExtensionOptions` (`/durable`); `createWebTools`, `WebBackup`, `FetchSource`, `SearchSource` and the rest of the web tools' exports (root); a provider's `fetch` and `search` (Browserbase's Fetch and Search APIs, the fake backend's `fetches` and `search` options) with `FetchRequest`, `FetchResult`, `SearchRequest`, `SearchResult` and `SearchHit`; the `web_fetch` and `web_search` tool contracts (`WEB_TOOLS`, `WEB_TOOL_NAMES`, `WEB_SEARCH_SNIPPET_MAX`, and the `fetch` and `search` values of a contract's `listedWhen`) and `web_fetch` as an `EvidenceTool`; `fetchUsage`, `searchUsage`, `scrubFetchedUrl`, and Browserbase's `SEARCH_QUERY_MAX` and `SEARCH_RESULTS_MAX`. The page-wall words a browser read uses (`WALLS`, `wallOf`, `wallFailure`, `pageNotice`, `INJECTION_THRESHOLD`) stay. A host that wants fetch or search gives its agent its own tool.
9
+ - A browser that opens with its agent's saved browser profile now says so before its tools. The prompt section's second line tells the model that a site the agent was signed in to there opens signed in, to use the browser rather than `web_fetch` for a page that needs a sign-in (`web_fetch` reads every page signed out), and that a sign-in page means this session has no sign-in for that site (a saved one may still exist, as when a restore failed). `run`'s description says the same. Before, the model was told only that the browser "keeps this agent's saved sign-ins", which didn't connect a signed-in page to the browser, so it fetched one with `web_fetch` and read the sign-in page. The line promises no sign-in, because an agent's first profile is new and holds none, and it names no site, profile id or account: a saved profile doesn't record which sites it covers. Nothing changes for a browser with no saved profile.
10
+ - A run whose files live on the run's Archil disk (Mode 2) can read what its browser saved. browser_read and screenshot file their evidence in the run's own folder on the disk, where the run's `read` opens it; before, they wrote to a local folder that a Mode 2 run never has, so the call failed. browser_upload chooses from the same folder, and refuses a path that would leave it. browser_downloads, which copies into a folder of the runner's machine, is offered only where the run's files are on that machine (Mode 1), so a Mode 2 run is never told a file was saved where it cannot open it.
11
+ pi-browser exports `uploadMime(name)`, the media type browser_upload gives a file by its name.
12
+
13
+ ## 0.1.0-beta.34 (2026-11-11)
14
+
15
+ - 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:
16
+ - `/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`.
17
+ - `/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.
18
+ - `/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.
19
+ - 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.
20
+ - 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.
21
+ - 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.
22
+ - 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.
23
+ - 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.
24
+ - 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.
25
+ - `ComputerCapabilities.isolation` takes `"host"`, and Settings → Computers lists "Local Chrome" with no key.
26
+ - 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).
27
+ - 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.
28
+ - 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.
29
+
5
30
  ## 0.1.0-beta.32 (2026-11-10)
6
31
 
7
32
  - `@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
@@ -10,20 +10,17 @@ Your agent gets its own browser, and you can take over and hand it back.
10
10
 
11
11
  If the process dies, a pi-durable host recovers the session and does not repeat an action. See [For hosts](#for-hosts).
12
12
 
13
- Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=22.19.0`, pi 1.5.0 exactly (its
13
+ Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=24.22.3`, pi 1.5.0 exactly (its
14
14
  pi-durable and chord peers). ESM only: the
15
15
  package has `import` entries and no `require` entry.
16
16
 
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.
@@ -79,14 +76,13 @@ It prints the page's accessibility tree, the same text `snapshot` gives a model:
79
76
 
80
77
  ## Demos
81
78
 
82
- Four runnable demos live in `examples/` in the repository. They are not in the npm package. Build once with `npm ci && npm run build`, then run one from the repository root. Each needs Chrome or Chromium (`CHROME_PATH` names it) except where it says otherwise.
79
+ Three runnable demos live in `examples/` in the repository. They are not in the npm package. Build once with `npm ci && npm run build`, then run one from the repository root. Each needs Chrome or Chromium (`CHROME_PATH` names it) except where it says otherwise.
83
80
 
84
81
  | Demo | Run | What it shows |
85
82
  |---|---|---|
86
83
  | [`examples/one-script-three-providers.mjs`](examples/one-script-three-providers.mjs) | `node packages/pi-browser/examples/one-script-three-providers.mjs https://example.com` | The same script on a local Chrome, Browserbase or Kernel. `PI_BROWSER_PROVIDER=browserbase` needs `BROWSERBASE_API_KEY` and the Browserbase SDK; `kernel` needs `KERNEL_API_KEY`. The tests run the local Chrome path only. |
87
84
  | [`examples/hold-an-irreversible-action.mjs`](examples/hold-an-irreversible-action.mjs) | `node packages/pi-browser/examples/hold-an-irreversible-action.mjs` | Under the `ask` policy a form post is held until a person approves it. The demo refuses, and the local server it posts to counts zero requests. |
88
85
  | [`examples/crash-and-resume.mjs`](examples/crash-and-resume.mjs) | `node packages/pi-browser/examples/crash-and-resume.mjs`, twice | The first run sets a page title and kills itself with SIGKILL between two tool calls. The second recovers the same Chrome from the run's own store and reads the title back. A scripted model stands in for a real one. It uses the pi-durable packages the repository already installs. Delete `$TMPDIR/pi-browser-crash-demo` to start over. |
89
- | [`examples/read-a-pdf.mjs`](examples/read-a-pdf.mjs) | `node packages/pi-browser/examples/read-a-pdf.mjs` | `web_fetch` on a PDF the fetch service cannot convert. It fetches the file raw and hands the bytes to your extractor, here poppler's `pdftotext` (needs poppler installed). The fetch service is a stand-in that answers HTTP 400 for a PDF, as Browserbase does. It does not need Chrome. |
90
86
 
91
87
  ## Providers
92
88
 
@@ -107,7 +103,7 @@ The local Chrome's options, in `cdpProvider({ chrome: { ... } })`:
107
103
  | `args` | Extra Chrome flags, added after the package's own. |
108
104
  | `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
105
 
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.
106
+ 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
107
 
112
108
  ## Take over and hand back
113
109
 
@@ -119,15 +115,11 @@ A person and the agent never drive the browser together. There are two ways for
119
115
 
120
116
  **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
117
 
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 |
118
+ What a host wires:
129
119
 
130
- The pi extension does not offer Kernel's live view, because Kernel's API has no read-only form of it.
120
+ - **The live view of a local Chrome:** `createLiveView` and `liveViewProvider`.
121
+ - **The live-view URL of a Browserbase or Kernel session:** handed to the host only, through `onSession` or the handoff port.
122
+ - **`browser_request_handoff`:** listed when the host passes a `handoff` port.
131
123
 
132
124
  ### The live view of your own Chrome
133
125
 
@@ -144,7 +136,7 @@ const liveView = createLiveView({
144
136
  server.on("request", (req, res) => { if (!liveView.handle(req, res)) next(req, res); });
145
137
  server.on("upgrade", (req, socket, head) => { if (!liveView.upgrade(req, socket, head)) socket.destroy(); });
146
138
 
147
- const provider = liveViewProvider(cdpProvider({ chrome }), liveView); // wrap it as the recorder's `watch` wraps a provider
139
+ const provider = liveViewProvider(cdpProvider({ chrome }), liveView);
148
140
  createBrowserExtension({ provider: () => provider, onSession: (row) => { /* row.liveView.fullscreen is the viewer's URL */ }, ... });
149
141
  ```
150
142
 
@@ -198,7 +190,7 @@ Where the profile lives:
198
190
  - **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
191
  - **Kernel:** a Kernel profile of that name, created if it is not there.
200
192
 
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.
193
+ It is never your own browser's profile.
202
194
 
203
195
  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
196
 
@@ -209,26 +201,13 @@ One session at a time may save to a profile in one process. A second saver is re
209
201
  |---|---|---|
210
202
  | `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
203
  | `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`). |
204
+ | `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. |
205
+ | `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
206
  | `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
207
  | `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
- | `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. |
218
- | `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
-
220
- `web_search` hits carry a `snippet` when the search has one: an excerpt of the page with its markdown links reduced to
221
- their text, whitespace collapsed and clipped to `WEB_SEARCH_SNIPPET_MAX` (500) characters, redacted with the rest of the
222
- answer. A host's `searchSources` (`createWebExtension`) are tried in order before the provider's own search; one that
223
- throws hands the call to the next, a cancelled call is never handed on, and the answer names the source in `via`. A
224
- source's optional `available()` is asked at each call; one that answers false is skipped without counting as a failure.
225
- `fetchSources` (`FetchSource`) are readers tried the same way before the provider's own fetch, for a markdown read: a
226
- page one answers is filed exactly as the provider's is, under `via: <name>_fetch`, and a reader's failure never becomes
227
- the call's own while the provider can still be tried.
228
-
229
- `web_fetch` and `web_search` results carry their price as pi usage (the Browserbase provider's list prices; a search
230
- source's answer at the usage it reports, else the list search price). Session
231
- minutes are charged by the session meter (`core/usage.ts`, wired into custody): every session tool's result carries the
208
+ | `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. |
209
+
210
+ Session minutes are charged by the session meter (`core/usage.ts`, wired into custody): every session tool's result carries the
232
211
  time since the last charge, and each released session's record carries its total. A host that books session time as spend
233
212
  passes `onCharge` (below), which hears each charge in the commit that bills it.
234
213
 
@@ -255,7 +234,7 @@ Every failure is one envelope: `ok: false`, a `code`, `retryable`, `effect` (`no
255
234
  | `rate_limited` | The site or the provider answered 429. |
256
235
  | `waiting_for_human` | A person has the browser. |
257
236
 
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.
237
+ **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
238
 
260
239
  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
240
 
@@ -268,7 +247,6 @@ What the package does with the credentials you register and the keys it recognis
268
247
  - **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
248
  - **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
249
  - **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
250
  - **Browserbase.** The provider dials Browserbase through a bound credential proxy, not the raw connect URL.
273
251
  - **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
252
 
@@ -276,23 +254,21 @@ What this does not cover: a value nobody registered and no shape matches, and wh
276
254
 
277
255
  ## Peers
278
256
 
279
- Stagehand, undici, zod and the two HTML packages are dependencies. Four optional peers cover the rest. Install only the ones you use:
257
+ Stagehand, undici, zod and the two HTML packages are dependencies. Three optional peers cover the rest. Install only the ones you use:
280
258
 
281
259
  | Peer | Needed for |
282
260
  |---|---|
283
- | `@earendil-works/pi-coding-agent` | `/coding-agent`. `pi install` supplies it. |
284
261
  | `@earendil-works/pi-durable` and `@earendil-works/chord` | `/durable`, the adapter for a pi-durable Harness. |
285
262
  | `@browserbasehq/sdk` | the Browserbase provider. Kernel needs no SDK. |
286
263
 
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.
264
+ The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.0` exactly. CI tests pi 1.5.0.
288
265
 
289
266
  ## Entries
290
267
 
291
268
  - `@parcha/pi-browser`: the host-neutral core. The model contract (tool names, descriptions, JSON schemas, effect and
292
269
  replay classes, the `browser` and `web` prompt sections), the typed failure envelope, the redactor, the screenshot
293
270
  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
271
+ `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
272
  `readPage(html, url, { deadlineMs?, signal? })`, with `isPrivateAddress` and `pinnedLookup`. `readPage` never holds
297
273
  the event loop: it drops a page's script, style, svg, noscript and template blocks, cuts what is left at
298
274
  `READ_MAX_CHARS` (`truncated`, with the page's length in `html_chars`), and converts it to markdown in a worker thread
@@ -301,89 +277,34 @@ The pi peers are `@earendil-works/pi-durable` and `chord` `1.5.0` exactly, and `
301
277
  its frame scan reads the page's first 2,000,000 characters in steps that yield the loop. Outside Node's builtins and
302
278
  undici it loads only node-html-parser and node-html-markdown, on demand and in that worker thread.
303
279
  - `/durable`: the pi-durable adapter. `createBrowserExtension` is session custody in the run's own store (a create is
304
- committed before the provider is called, release is a durable task, reconcile runs at run open). `createWebExtension` is
305
- `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.
280
+ committed before the provider is called, release is a durable task, reconcile runs at run open).
307
281
  - `/driver/stagehand`: `stagehandDriver()`, Stagehand v4 over upstream's facade, vendored unedited in
308
282
  `src/vendor/stagehand-facade/`. `UPSTREAM.json` names the commit and each file's blob id and SHA-256;
309
283
  `node scripts/vendor-facade.mjs --check` verifies them and `--commit SHA --release NAME` re-vendors. Stagehand is created
310
284
  sealed: no inference, no cache, and no trace endpoint, so no trace is exported. Stagehand attaches one client to a browser
311
285
  at a time: closing a driver disconnects it, so the next attach is allowed.
286
+ - `/driver/cdp`: `cdpDriver()`, the driver of every AgentRun browser computer (Browserbase's, Kernel's, or the computer
287
+ package's `local-chrome` 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
288
+ accessibility tree with the same "frame-node" ids (`[0-42]`: the frame's place, then Chrome's backend node id). `run`
289
+ takes actions only. Each action is scrolled into view, hit-tested at its centre, and pressed and released there, or
290
+ typed with inserted text and a real last key. Each answers one line: `[ok] click [0-42] button "Add" -> page changed`
291
+ (or `navigated to <url>`, or `no change`). `run` code is refused in words, and navigation is
292
+ `{"op":"goto","url":"https://..."}`. A frame another site runs in its own process (a cross-origin iframe) is not read:
293
+ the snapshot names each one it left out. Adapted from Browser Use Pi's `ax.ts`, `cdp.ts` and `page.ts` under its MIT
294
+ license, in `src/vendor/browser-use-pi/` (see NOTICE and that folder's `UPSTREAM.json`).
312
295
  - `/providers/browserbase`, `/providers/kernel`, `/providers/cdp`: where browsers come from. Browserbase through its SDK,
313
296
  with the credential-proxy dial and the connect-URL rewrite. Kernel through its REST API on the package's own HTTP agent.
314
297
  Any CDP endpoint, or a local Chrome the provider starts and kills by exact pid.
315
298
  - `/providers/chrome-args`: `chromeArgs()`, the arguments the cdp provider starts a local Chrome with, and `extensionOrigin()`,
316
299
  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.
300
+ from here rather than copying Stagehand's `--remote-allow-origins=*`. `findChrome()` finds the Chrome to start: the one
301
+ `PI_BROWSER_CHROME` or `CHROME_PATH` names, else `google-chrome` or `chromium` on the PATH, else the usual install locations.
320
302
  - `/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
303
  [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
304
  - `/testing`: the shared test fake. A provider backend with a ledger of every call, a credential broker, an HTTP face so the
325
305
  ledger outlives a killed child process, a driver over in-memory pages, and sentinel credentials. A host's composition
326
306
  test and this package's crash matrix use the same one.
327
307
 
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
308
  ## For hosts
388
309
 
389
310
  Any pi-durable `Harness` can install the extensions. A local Chrome is the default provider and costs nothing.
@@ -466,100 +387,13 @@ and `search`.
466
387
 
467
388
  Two things to know before you give a model a browser:
468
389
 
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
471
- their network goes. A host that must not let a model reach internal addresses restricts that network or the URLs it passes.
390
+ - **What a model may reach is your decision.** `publicFetch` refuses private addresses, but a driven browser goes
391
+ wherever its network goes. A host that must not let a model reach internal addresses restricts that network or the URLs it passes.
472
392
  - **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
393
  the first attach replaces `globalThis.WebSocket` with a wrapper that dials a bound credential proxy instead of the raw
474
394
  connect URL. Both are process-wide. The wrapper passes every other URL through unchanged. Importing the package does
475
395
  neither.
476
396
 
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
397
  ## Development
564
398
 
565
399
  ```sh
@@ -568,7 +402,7 @@ npm test -w @parcha/pi-browser # everything but the real-Chrome su
568
402
  CHROME_PATH=/path/to/chrome npm run test:chrome -w @parcha/pi-browser
569
403
  ```
570
404
 
571
- The real-Chrome suites (`stagehand_real_chrome`, `cdp_local_chrome`, `effects-chrome`, `coding_agent_real_chrome`,
405
+ The real-Chrome suites (`stagehand_real_chrome`, `cdp_local_chrome`, `effects-chrome`, `screenshot_clip_real_chrome`,
572
406
  `readme_example`) skip with a typed reason where no Chrome can load Stagehand's extension, and fail instead under
573
407
  `AGENTRUN_REQUIRE_LOCAL_CHROME=1`, which CI sets. The crash matrix (`test/custody.test.mjs`) SIGKILLs a child process at each
574
408
  cut point of a session's life against the shared fake and reopens the run's SQLite file. The wire checks (`test/wire/`) plant
@@ -14,16 +14,20 @@ export type ToolContract = {
14
14
  /** One sequential call makes its whole round sequential. */
15
15
  readonly executionMode: "sequential" | "parallel";
16
16
  readonly evidence: "none" | "receipt" | "image" | "files" | "urls";
17
- readonly listedWhen: "always" | "downloads" | "upload" | "fetch" | "search" | "sites" | "handoff";
17
+ readonly listedWhen: "always" | "downloads" | "upload" | "handoff";
18
18
  };
19
19
  /** What the browser keeps, as `run`'s description tells the model when it picks between the browser and web_fetch:
20
20
  * cookies across pages always, its agent's saved sign-ins only on a plane that has them (a local Chrome keeps none). */
21
21
  export declare const BROWSER_KEEPS: Readonly<{
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
- 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.";
23
+ signIns: "This browser opens with this agent's saved browser profile: a site the agent was signed in to there opens signed in here, and only here (web_fetch reads every page signed out). Use it for anything behind a sign-in, or a page that depends on an earlier one.";
24
24
  }>;
25
- /** A hit's snippet is clipped to this many characters, whitespace collapsed, so ten hits stay a few kilobytes. */
26
- export declare const WEB_SEARCH_SNIPPET_MAX = 500;
25
+ /** The prompt section's line for a browser that opens with its agent's saved profile: said once, before the tools, so the
26
+ * model knows of it when it picks between the browser and web_fetch (a description alone was not enough). It promises no
27
+ * sign-in: on an agent's first run the profile is new and holds none (sign-ins-store.ts makes it), so the claim is
28
+ * conditional, and the steer away from web_fetch holds either way. A sign-in page means this session has none, never
29
+ * that none is saved: a vault restore that fails starts the session signed out and leaves the saved sign-in as it was. */
30
+ export declare const SIGNED_IN_LINE = "This browser opens with this agent's saved browser profile, so a site the agent was signed in to there opens signed in here. For a page that needs you signed in, use the browser (run, snapshot, browser_read), not web_fetch: web_fetch reads every page signed out. If the browser shows a sign-in page, this session has no sign-in for that site.";
27
31
  /** Whether a host lists a browser tool: one that is always offered, or one whose capability the host has (a workspace to copy downloads
28
32
  * into, files to upload from, a person to hand over to). */
29
33
  export declare const listedFor: (contract: ToolContract, offers: {
@@ -32,16 +36,15 @@ export declare const listedFor: (contract: ToolContract, offers: {
32
36
  readonly handoff: boolean;
33
37
  }) => boolean;
34
38
  export declare const BROWSER_TOOLS: readonly ToolContract[];
35
- export declare const WEB_TOOLS: readonly ToolContract[];
36
39
  /** The browser's contracts as a plane's model reads them: `run` says the plane keeps its agent's saved sign-ins where it
37
40
  * has them (a host's kept profile, or a session vault), and only cookies where it has none. */
38
41
  export declare const browserToolsFor: (signIns: boolean) => readonly ToolContract[];
39
42
  export declare const BROWSER_TOOL_NAMES: readonly string[];
40
- export declare const WEB_TOOL_NAMES: readonly string[];
41
43
  /** Depends only on configuration, never live state, so every request renders the same text and keeps the prompt cache. */
42
44
  export declare function browserSection(policy: {
43
45
  readonly idleReleaseS: number;
44
46
  }, offered?: {
45
47
  readonly downloads?: boolean;
46
48
  readonly upload?: boolean;
49
+ readonly signedIn?: boolean;
47
50
  }): string;