@parcha/pi-browser 0.1.0-beta.17 → 0.1.0-beta.19

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 (87) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/README.md +177 -39
  3. package/dist/coding-agent-local.js +2 -1
  4. package/dist/coding-agent.d.ts +42 -2
  5. package/dist/coding-agent.js +159 -21
  6. package/dist/core/clip.d.ts +31 -0
  7. package/dist/core/clip.js +49 -0
  8. package/dist/core/contract.d.ts +4 -1
  9. package/dist/core/contract.js +40 -7
  10. package/dist/core/custody.d.ts +79 -5
  11. package/dist/core/custody.js +66 -5
  12. package/dist/core/decisions.d.ts +4 -0
  13. package/dist/core/dial.d.ts +7 -0
  14. package/dist/core/dial.js +41 -0
  15. package/dist/core/downloads.d.ts +1 -0
  16. package/dist/core/downloads.js +17 -5
  17. package/dist/core/driving-guard.d.ts +13 -0
  18. package/dist/core/driving-guard.js +61 -0
  19. package/dist/core/driving.d.ts +61 -0
  20. package/dist/core/driving.js +156 -0
  21. package/dist/core/effects.js +33 -13
  22. package/dist/core/evidence.d.ts +3 -1
  23. package/dist/core/failures.d.ts +5 -1
  24. package/dist/core/failures.js +20 -4
  25. package/dist/core/files.d.ts +8 -0
  26. package/dist/core/files.js +74 -0
  27. package/dist/core/find.d.ts +3 -1
  28. package/dist/core/find.js +2 -1
  29. package/dist/core/guard.d.ts +9 -1
  30. package/dist/core/guard.js +7 -2
  31. package/dist/core/host.d.ts +49 -1
  32. package/dist/core/images.d.ts +10 -2
  33. package/dist/core/images.js +4 -4
  34. package/dist/core/lease.d.ts +1 -1
  35. package/dist/core/lease.js +2 -1
  36. package/dist/core/session-control.d.ts +2 -0
  37. package/dist/core/session-control.js +5 -0
  38. package/dist/core/tools.d.ts +70 -4
  39. package/dist/core/tools.js +288 -45
  40. package/dist/core/unanswered.d.ts +3 -0
  41. package/dist/core/unanswered.js +17 -0
  42. package/dist/core/usage.d.ts +2 -0
  43. package/dist/core/usage.js +6 -0
  44. package/dist/core/web.d.ts +1 -1
  45. package/dist/core/web.js +9 -7
  46. package/dist/driver/extension-worker.d.ts +4 -2
  47. package/dist/driver/extension-worker.js +16 -10
  48. package/dist/driver/page-driver.d.ts +8 -0
  49. package/dist/driver/page-driver.js +128 -0
  50. package/dist/driver/stagehand.d.ts +3 -1
  51. package/dist/driver/stagehand.js +40 -66
  52. package/dist/durable.d.ts +16 -4
  53. package/dist/durable.js +415 -82
  54. package/dist/index.d.ts +2 -0
  55. package/dist/index.js +2 -0
  56. package/dist/live-view/index.d.ts +4 -0
  57. package/dist/live-view/index.js +4 -0
  58. package/dist/live-view/protocol.d.ts +152 -0
  59. package/dist/live-view/protocol.js +84 -0
  60. package/dist/live-view/provider.d.ts +6 -0
  61. package/dist/live-view/provider.js +23 -0
  62. package/dist/live-view/server.d.ts +50 -0
  63. package/dist/live-view/server.js +342 -0
  64. package/dist/live-view/stream.d.ts +7 -0
  65. package/dist/live-view/stream.js +388 -0
  66. package/dist/live-view/token.d.ts +6 -0
  67. package/dist/live-view/token.js +13 -0
  68. package/dist/live-view/viewer.d.ts +6 -0
  69. package/dist/live-view/viewer.js +350 -0
  70. package/dist/live-view/ws.d.ts +19 -0
  71. package/dist/live-view/ws.js +176 -0
  72. package/dist/providers/assigned.d.ts +18 -0
  73. package/dist/providers/assigned.js +76 -0
  74. package/dist/providers/cdp-call.js +12 -2
  75. package/dist/providers/cdp.js +37 -11
  76. package/dist/recorder/follow.d.ts +10 -0
  77. package/dist/recorder/follow.js +27 -2
  78. package/dist/recorder/frames.d.ts +7 -0
  79. package/dist/recorder/frames.js +73 -5
  80. package/dist/store.d.ts +22 -3
  81. package/dist/store.js +75 -4
  82. package/dist/testing/backend.d.ts +26 -0
  83. package/dist/testing/backend.js +21 -3
  84. package/dist/testing/driver.d.ts +18 -1
  85. package/dist/testing/driver.js +4 -0
  86. package/dist/web.js +2 -2
  87. package/package.json +10 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,11 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.1.0-beta.19 (2026-10-20)
6
+
7
+ - `@parcha/pi-browser`: a live view for the cdp provider, from the new `@parcha/pi-browser/live-view` export. `createLiveView` serves a viewer page and a loopback WebSocket for one person at a time: the first message must be the hello with the session's token, a wrong or missing token, a bad Origin or a second viewer is refused, the screencast frames are never written anywhere, the viewer says it is connecting and refuses input out loud until it is ready, and the view ends when the session is released. `liveViewProvider` wraps the cdp provider and reports the viewer's URL to `onSession` and nowhere else. While a person drives the viewer, every browser tool call (and `browser_release` and `browser_relaunch`) is refused with a typed, retryable `person_driving` before it does anything, the person's input is discarded while the agent acts (one shared gate per session, `drivingGates`), and an idle window never releases a session a person drives or watches. Custody can hold a session for a person behind a per-session fence: `CustodyPort` gains `current()`, a page action the fence stopped before any driver call got through is settled as not sent, and a held session the provider ended no longer holds up the conversation. `FrameRecorderOptions.hold` keeps a person-driven session out of the recording (one `frame.gap` marks the span), and when a hold lifts one frame is captured on demand so the replay does not end at the hold. `RunAction` types the actions of `run` per op. `browser_upload` runs behind a `WorkspaceFiles` port (it refuses swapped parents, pipes and host-private files, and is journaled like a run), `browser_downloads` works, and a `use_website` child is offered neither. A site child's browser can be the session the host reserved for it: the new `@parcha/pi-browser/providers/assigned` export never creates or ends a browser, takes its assigned session as the run's only browser, and is never relaunched or idled away. A screenshot's result carries the captured image's own facts in `details.media` (`kind`, `path`, `mime`, `bytes`, `width`, `height`, `ask`), and a screenshot can capture one region, by clip, snapshot id or CSS selector. The index exports custody's vocabulary, and a session's record and `relaunch`'s answer say the settings the provider applied. `browser_request_handoff` hands the browser to a person for a step only a human can do, such as a 2FA or a captcha, and waits durably for the host's answer. It is listed only when the host gives a `HandoffPort`, a rerun never asks again once the answer is kept, `done`, `cancelled` or `expired` give the session back under a new fence, and every other call answers `waiting_for_human` meanwhile. A refusal from the port, or a failure before it answers, gives the session straight back.
8
+ - `@parcha/pi-browser`: `use_website` children take turns when the provider in use shares one browser (a provider says so with the new `sharedBrowser` cap, which `cdpProvider` sets on an endpoint), and a durable child keeps its turn until it has read its report and released its browser. The first call after a release says so first and carries `previous_session`, and a read of a fresh `about:blank` browser says it is fresh instead of a wall. An attach waits for an init an earlier attach left running in Stagehand's extension, instead of failing with "Stagehand initialization is already in progress". A page snapshot or screenshot the browser never answers fails at its deadline as a dropped connection, and a read that hangs again after a working reconnect is told as a stuck page, with `browser_relaunch` as the way out. The coding agent returns the typed `person_driving` result for a refused release or relaunch. A saved lease's private TMPDIR is found after a provider restart. `copyProfile` no longer ends the host process when a file vanishes between its listing and its copy. A blank optional property means not given, not an intent to refuse; a screenshot's question travels with the capture; a classified failure names the browser provider, not Browserbase; a conversation's close evicts its repeat guard and idle entry; an upload that throws is named as the upload. A dropped session the provider still runs is reconnected within a bounded budget (90 s, tries at once, then after 1 s and 3 s, each attach cut at what is left of the budget), then released as lost and told to the next call, unless a person holds, drives or watches it; the answer is `browser_unavailable` with `next: browser_relaunch`, and `CustodyPort.session` takes an optional signal. A stuck-page answer carries the same `next`. A browser the store cannot record a release for is released at the provider anyway, and a close over a failed store releases every session the process still holds, so a failed commit on pi-durable 1.2 or later no longer leaks a paid browser. A cut page action's warning survives a crash between telling it and saving the answer that told it, and the journal keeps the cut a later run's entry replaces. An upload the page never answers fails at 60 s as `possibly_effected`, and its identical retry is refused until the agent looks at the page. `browser_read` gives the judge the page's frames (their origins and the text inside them), so a challenge in an iframe is a bot check and not an empty page. The run's registered values are redacted whole before any text is cut: failure details, the repeat guard's note, web failures, download reasons, and the page text, `find` question and chunks the judge reads. A host that passes no session price is metered at Browserbase's list price, and the session record's `spent` carries `source: "list"` so the host can mark the dollars as an estimate; an explicit price, even one equal to the list's, and a deliberate `null` are not changed. `browser_read` and `web_fetch` descriptions name the redaction marker without carrying the literal. An assigned-session provider shares its one-browser hold across every provider instance built over the same session, so a host that builds the provider per call still gets one browser and one release; a browser recovered after a lost create response is tracked before it is recorded, so a store that cannot record it still lets a close release it. After a person has driven the live view, the model's next call is told so, and the session's snapshot ids are dropped, so an old snapshot id fails as stale whatever the page's URL. A cut `browser_upload` is never judged safe to run again: after a crash its identical retry is refused as `effect_unknown` until a look, and the notice never says it is safe to run again.
9
+
5
10
  ## 0.1.0-beta.15 (2026-10-16)
6
11
 
7
12
  - `@parcha/pi-browser`: a session can ask for a named saved profile. `SessionSpec` and `BrowserPolicy` take `profile: { name, save }`, `ProviderCaps` gains `profiles`, and the session record names the profile (the name only; older records read as none). The local Chrome (`cdp`) keeps a named profile in its own directory, and a session can work from a copy that is never saved; Kernel keeps one through its own profiles (created on first use, one saver per profile); Browserbase keeps one as a context made on first use and remembered by name. A provider that cannot keep a profile, a profile beside a context id and a bad name are refused with the typed envelope before any session or record is made. A host can pass an optional `crossing` callback that is called at the two page-action moments a kill sweep needs (after one page action's answer is committed and before the next is dispatched; after a page action's driver call returned and before its answer is committed). `use_website` calls in one turn now run at once, each child in its own browser. `browser_release` on a session that already ended, or is ending, answers `already_released: { reason, at }` and one sentence beside `released`, which keeps its meaning.
package/README.md CHANGED
@@ -1,9 +1,14 @@
1
1
  # @parcha/pi-browser
2
2
 
3
- A browser for [pi](https://github.com/earendil-works/pi) agents that survives crashes. The package records a session
4
- before it calls the provider and releases it with a durable task. After a crash it reruns reads and never reruns actions.
5
- It files every page the agent reads as evidence with its SHA-256, gives each failure a typed code, and keeps credentials out
6
- of anything the model, a document or a log can see.
3
+ Your agent gets its own browser, and you can take over and hand it back.
4
+
5
+ - **Its own browser.** The agent drives a Chrome of its own: a local Chrome, Browserbase or Kernel. It reads pages, clicks, types and takes screenshots. A local Chrome needs no key.
6
+ - **You can take over and hand it back.** A host mounts the live view in a few lines, and then a person sees the agent's page, uses the mouse and keys, and lets the agent go on. While the person is driving, the agent's browser calls are refused. The agent can also ask a person for a step only a person can do, and wait for the answer. See [Take over and hand back](#take-over-and-hand-back). For now, use the live view with test accounts on practice sites only: the model's own page code can read what a person types there.
7
+ - **Credentials you register stay out of what the model sees.** Credentials you register, and keys of the common shapes, are replaced with `[redacted]` in every tool result, failure, filed page and log. See [Credentials](#credentials).
8
+ - **Every page the agent reads is filed as evidence.** The file holds the page's URL, its title and its SHA-256.
9
+ - **Bot walls get a name, and failures get a code.** A CAPTCHA, a login wall, a paywall or a region block is named, with a next step, when you give the package a page judge. Every failure is one envelope with one of 15 codes. See [Failures](#failures).
10
+
11
+ If the process dies, a pi-durable host recovers the session and does not repeat an action. See [For hosts](#for-hosts).
7
12
 
8
13
  Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=22.19.0`, pi 1.1 and 1.2 (the
9
14
  coding-agent entry also runs on pi 1.0.4). ESM only: the
@@ -12,23 +17,11 @@ package has `import` entries and no `require` entry.
12
17
  ## Install
13
18
 
14
19
  ```sh
15
- pi install npm:@parcha/pi-browser # the pi coding agent's extension
16
- npm install @parcha/pi-browser # the library: providers, driver, durable adapter
20
+ pi install npm:@parcha/pi-browser@beta # the pi coding agent's extension
21
+ npm install @parcha/pi-browser@beta # the library: providers, driver, durable adapter
17
22
  ```
18
23
 
19
- Until it is published, build it from a checkout and `pi install ./packages/pi-browser`.
20
-
21
- Stagehand, undici, zod and the two HTML packages are dependencies. Four optional peers cover the rest. Install only the ones you use:
22
-
23
- | Peer | Needed for |
24
- |---|---|
25
- | `@earendil-works/pi-coding-agent` | `/coding-agent`. `pi install` supplies it. |
26
- | `@earendil-works/pi-durable` and `@earendil-works/chord` | `/durable`, the adapter for a pi-durable Harness. |
27
- | `@browserbasehq/sdk` | the Browserbase provider. Kernel needs no SDK. |
28
-
29
- The pi peers are `@earendil-works/pi-durable` and `chord` `>=1.1.0 <1.4.0`, and `@earendil-works/pi-coding-agent` at any version, as pi's package guidance asks of the packages it supplies. The suite passes on pi 1.1, 1.2 and 1.3, and the coding-agent entry's tests also pass on a pi 1.0.4 family.
30
-
31
- pi 1.0.4 or 1.1.x users: pin `@earendil-works/pi-codemode` to the same version as `@earendil-works/pi-coding-agent` (`@1.0.4`, or `@1.1.0`), because pi-codemode 1.2.0 removed an export those versions import, or use pi 1.2.
24
+ `pi install` loads the extension. A Chrome starts on the model's first browser call, and not before.
32
25
 
33
26
  ## Quick start
34
27
 
@@ -93,6 +86,158 @@ Four runnable demos live in `examples/` in the repository. They are not in the n
93
86
  | [`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. |
94
87
  | [`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. |
95
88
 
89
+ ## Providers
90
+
91
+ The same tools run on three kinds of browser. You pick one when you set up the package.
92
+
93
+ | Provider | What it is | What it needs |
94
+ |---|---|---|
95
+ | Local Chrome (`/providers/cdp`) | A Chrome the package starts and stops by exact pid, with its own profile directory and a free debugging port. It can also attach to a Chrome you already run, at a CDP endpoint. | Chrome or Chromium. No key. |
96
+ | Browserbase (`/providers/browserbase`) | A Browserbase session, through its SDK. | `BROWSERBASE_API_KEY` and the `@browserbasehq/sdk` peer. |
97
+ | Kernel (`/providers/kernel`) | A Kernel browser, through its REST API. | `KERNEL_API_KEY`. No SDK. |
98
+
99
+ The pi extension picks one from a flag or an environment variable; see [For pi users](#for-pi-users). A host that wires the package itself passes the provider it wants; see [For hosts](#for-hosts). `examples/one-script-three-providers.mjs` runs one script on all three.
100
+
101
+ ## Take over and hand back
102
+
103
+ A person and the agent never drive the browser together. There are two ways for a person to come in.
104
+
105
+ **The person drives, from a live view.** The live view shows the session's page and sends the person's mouse, keys, paste, address bar, back and reload to it. While a person has driven within the last 3 seconds, every browser call from the agent is refused before it does anything (`refused`, `person_driving`, and it can be retried). While an agent call runs, the person's input is discarded with a notice. A call that waited while the person used the browser is told that the page may have changed, and the agent takes a snapshot before it acts.
106
+
107
+ **The agent asks for a person.** The tool `browser_request_handoff` takes an instruction (what the person should do) and a completion condition (what the page shows when it is done). It waits until the person finishes, cancels or the request expires. While the person has the browser, every other browser call answers `waiting_for_human`. Afterwards the agent takes a snapshot and checks the condition on the page. The tool is listed only when the host gives a `HandoffPort`, which is how the host reaches the person.
108
+
109
+ **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.
110
+
111
+ What runs where:
112
+
113
+ | | The pi extension, as `pi install` loads it | A host that wires it |
114
+ |---|---|---|
115
+ | Live view of a local Chrome | not wired | `createLiveView` and `liveViewProvider` |
116
+ | Live-view URL of a Browserbase or Kernel session | not shown to anyone | handed to the host only, through `onSession` or the handoff port |
117
+ | `browser_request_handoff` | not listed | listed when the host passes a `handoff` port |
118
+
119
+ The pi extension does not offer Kernel's live view, because Kernel's API has no read-only form of it.
120
+
121
+ ### The live view of your own Chrome
122
+
123
+ `@parcha/pi-browser/live-view` serves a canvas of the session's active page, and the person's mouse, keys, paste, address bar, back and reload go to it. It works for the local Chrome (the cdp provider). Browserbase and Kernel give a host a live-view URL of their own.
124
+
125
+ ```ts
126
+ import { createLiveView, liveViewProvider } from "@parcha/pi-browser/live-view";
127
+ import { cdpProvider } from "@parcha/pi-browser/providers/cdp";
128
+
129
+ const liveView = createLiveView({
130
+ hostOrigin: "https://app.example", // the one origin that may frame the viewer (null: none)
131
+ baseUrl: "https://app.example/live/run-123", // where you mount it; omit it and the live view serves itself on 127.0.0.1
132
+ });
133
+ server.on("request", (req, res) => { if (!liveView.handle(req, res)) next(req, res); });
134
+ server.on("upgrade", (req, socket, head) => { if (!liveView.upgrade(req, socket, head)) socket.destroy(); });
135
+
136
+ const provider = liveViewProvider(cdpProvider({ chrome }), liveView); // wrap it as the recorder's `watch` wraps a provider
137
+ createBrowserExtension({ provider: () => provider, onSession: (row) => { /* row.liveView.fullscreen is the viewer's URL */ }, ... });
138
+ ```
139
+
140
+ The URL is a full-control credential and goes to `onSession` only (never a result, a record or the model): `https://.../live/run-123/v/<id>#t=<token>`. The
141
+ token is 256 random bits in the fragment, so it reaches no server log, proxy or Referer; the viewer's script sends it as the WebSocket's first message and
142
+ nothing is accepted before it. The upgrade's `Origin` must be the viewer's own origin (behind a proxy, pass the upgrade through with `Origin` intact).
143
+ There is one authenticated viewer per session (a second is refused `viewer_in_use`); the token, the stream and the viewer's socket end at the session's release.
144
+ The page is served with `Referrer-Policy: no-referrer`, `default-src 'self'` and `frame-ancestors` set to `hostOrigin`. The viewer may send a page only to
145
+ http(s) addresses. Frames are held one at a time and acknowledged after they were sent; none is written anywhere.
146
+
147
+ Every browser tool is a model call on its session's gate (`drivingGates`, shared by default between the live view and the toolset, so you pass nothing). To use your own
148
+ registry, pass the same one to both sides: `const gates = createDrivingGates({ idleMs: 5_000 }); createLiveView({ hostOrigin, gates }); createBrowserExtension({ ..., gates });`.
149
+
150
+ `drivingGates(tag).viewing()` is true for as long as an authenticated viewer is connected to that session, even when the person sits still longer than the 3 s driving window (a person mid-sign-in): the host's own custody reads it before it releases a session on its own. A custom registry's gates implement `viewing()` and `setViewing(on)`; the live view sets it on a viewer's hello and clears it when that viewer leaves or the session is released.
151
+
152
+ Limits: JS dialogs show with accept and dismiss. A file chooser and downloads are not supported.
153
+
154
+ ## Saved sign-ins
155
+
156
+ This section says where a profile's state lives. A host can ask for a browser profile by name, and say whether the session keeps what it learns. The host sets it in the session policy (`profile: { name, save }`). A name is 1 to 64 letters, digits, dots, dashes and underscores, and starts with a letter or a digit. A session that names a profile starts from the cookies and logins that profile holds. A provider that cannot keep a profile refuses the request by name, and no session starts.
157
+
158
+ Where the profile lives:
159
+
160
+ - **Local Chrome:** a directory `.profiles/<name>` under the profile root you give the provider. A session that saves runs on that directory. A session that does not save runs on a copy, and the profile stays as it was.
161
+ - **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.
162
+ - **Kernel:** a Kernel profile of that name, created if it is not there.
163
+
164
+ 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.
165
+
166
+ 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.
167
+
168
+
169
+ ## The tools
170
+
171
+ | Tool | Does | Replay after a crash |
172
+ |---|---|---|
173
+ | `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. |
174
+ | `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`. |
175
+ | `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. |
176
+ | `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`). |
177
+ | `browser_release`, `browser_relaunch` | End the session; end it and open another. | Idempotent. A create carries a tag, so a rerun finds its session. |
178
+ | `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. |
179
+ | `web_fetch`, `web_search` | Fetch a page or search, through the provider's services. | Reruns. |
180
+ | `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. |
181
+ | `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. |
182
+
183
+ `web_fetch` and `web_search` results carry their price as pi usage (the Browserbase provider's list prices). Session
184
+ minutes are charged by the session meter (`core/usage.ts`, wired into custody): every session tool's result carries the
185
+ time since the last charge, and each released session's record carries its total.
186
+
187
+
188
+ ## Failures
189
+
190
+ Every failure is one envelope: `ok: false`, a `code`, `retryable`, `effect` (`none` or `possibly_effected`) and a message that names the way out. A `detail` of at most 2,000 characters may follow, redacted. The code comes from typed facts (a status, a class name, a cause code), never from the text of a message. There are 15 codes.
191
+
192
+ | Code | Means |
193
+ |---|---|
194
+ | `browser_unavailable` | The browser or its provider could not be reached. |
195
+ | `auth` | The provider refused the key (401) or the kind of session (403). |
196
+ | `timeout` | The call ran past its deadline. |
197
+ | `aborted` | The run cancelled the call. |
198
+ | `refused` | The package declined before it did anything: a bad argument, a person driving, a profile that cannot be used, an identical call that has already failed several times, or no person to hand to. |
199
+ | `stale_snapshot` | The snapshot id is stale, the page moved on since the snapshot, or a person used the browser meanwhile. Take a new snapshot. |
200
+ | `session_ended` | The provider closed the session, or the browser died. The next call opens a fresh one. |
201
+ | `session_replaced` | A call that reran after an interruption lost its session, so its page is gone. |
202
+ | `effect_unknown` | An action may have taken effect before an interruption. The identical code is refused once. |
203
+ | `code_error` | The code the model sent to `run` threw. |
204
+ | `command_failed` | A read failed. |
205
+ | `not_content` | The page is not content: a login wall, a paywall, a consent notice, an error page, a loading page, an empty page, or a fresh browser that has loaded no page. |
206
+ | `blocked` | A CAPTCHA or bot check, a region block, or a fetch the site refused (HTTP 401, 403, 451 or 999). |
207
+ | `rate_limited` | The site or the provider answered 429. |
208
+ | `waiting_for_human` | A person has the browser. |
209
+
210
+ **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.
211
+
212
+ ## Credentials
213
+
214
+ What the package does with the credentials you register and the keys it recognises, so they stay out of the model's view, a log and a filed page:
215
+
216
+ - **Registered values.** A host registers the exact strings to scrub (`redact.values`; at least 8 characters). Each is replaced with `[redacted]` in the raw, URL-encoded and fetch-sent spellings.
217
+ - **Known shapes.** A query parameter named `signingKey`, `api_key`, `token`, `access_token`, `key`, `jwt` or `signature`, an OpenAI-style `sk-` key, a Browserbase `bb_live_` or `bb_test_` key, a Google `AIza` key and a `Bearer` value are replaced the same way.
218
+ - **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.
219
+ - **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.
220
+ - **The live view's address** is a full-control credential. It goes to the host's `onSession` and the handoff port, and nowhere else.
221
+ - **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.
222
+ - **Browserbase.** The provider dials Browserbase through a bound credential proxy, not the raw connect URL.
223
+ - **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.
224
+
225
+ What this does not cover: a value nobody registered and no shape matches, and what a person types into a page. See the limit under [Take over and hand back](#take-over-and-hand-back).
226
+
227
+ ## Peers
228
+
229
+ Stagehand, undici, zod and the two HTML packages are dependencies. Four optional peers cover the rest. Install only the ones you use:
230
+
231
+ | Peer | Needed for |
232
+ |---|---|
233
+ | `@earendil-works/pi-coding-agent` | `/coding-agent`. `pi install` supplies it. |
234
+ | `@earendil-works/pi-durable` and `@earendil-works/chord` | `/durable`, the adapter for a pi-durable Harness. |
235
+ | `@browserbasehq/sdk` | the Browserbase provider. Kernel needs no SDK. |
236
+
237
+ The pi peers are `@earendil-works/pi-durable` and `chord` `>=1.1.0 <1.4.0`, and `@earendil-works/pi-coding-agent` at any version, as pi's package guidance asks of the packages it supplies. The suite passes on pi 1.1, 1.2 and 1.3, and the coding-agent entry's tests also pass on a pi 1.0.4 family.
238
+
239
+ pi 1.0.4 or 1.1.x users: pin `@earendil-works/pi-codemode` to the same version as `@earendil-works/pi-coding-agent` (`@1.0.4`, or `@1.1.0`), because pi-codemode 1.2.0 removed an export those versions import, or use pi 1.2.
240
+
96
241
  ## Entries
97
242
 
98
243
  - `@parcha/pi-browser`: the host-neutral core. The model contract (tool names, descriptions, JSON schemas, effect and
@@ -110,28 +255,12 @@ Four runnable demos live in `examples/` in the repository. They are not in the n
110
255
  - `/providers/browserbase`, `/providers/kernel`, `/providers/cdp`: where browsers come from. Browserbase through its SDK,
111
256
  with the credential-proxy dial and the connect-URL rewrite. Kernel through its REST API on the package's own HTTP agent.
112
257
  Any CDP endpoint, or a local Chrome the provider starts and kills by exact pid.
258
+ - `/live-view`: a person sees and drives the local Chrome (the cdp provider) from your page, with nothing leaving the machine but the model. See
259
+ [The live view of your own Chrome](#the-live-view-of-your-own-chrome).
113
260
  - `/testing`: the shared test fake. A provider backend with a ledger of every call, a credential broker, an HTTP face so the
114
261
  ledger outlives a killed child process, a driver over in-memory pages, and sentinel credentials. A host's composition
115
262
  test and this package's crash matrix use the same one.
116
263
 
117
- ## The tools
118
-
119
- | Tool | Does | Replay after a crash |
120
- |---|---|---|
121
- | `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. |
122
- | `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. | Reruns. A read whose session was lost answers `session_replaced`. |
123
- | `browser_downloads` | Copy what the session downloaded into the host's workspace, with a manifest of SHA-256 sums. Listed only when the host gives a `workspace` and the provider can list downloads. | Reruns; files already there are skipped. |
124
- | `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`). |
125
- | `browser_release`, `browser_relaunch` | End the session; end it and open another. | Idempotent. A create carries a tag, so a rerun finds its session. |
126
- | `web_fetch`, `web_search` | Fetch a page or search, through the provider's services. | Reruns. |
127
-
128
- `web_fetch` and `web_search` results carry their price as pi usage (the Browserbase provider's list prices). Session
129
- minutes are charged by the session meter (`core/usage.ts`, wired into custody): every session tool's result carries the
130
- time since the last charge, and each released session's record carries its total.
131
-
132
- Every failure is one envelope: `ok: false`, a `code`, `retryable`, `effect` (`none` or `possibly_effected`) and a message
133
- that names the way out.
134
-
135
264
  ## For pi users
136
265
 
137
266
  The pi coding agent gets `snapshot`, `run`, `screenshot`, `browser_read`, `browser_relaunch`, `browser_release` and
@@ -222,7 +351,10 @@ await browser.reconcile(harness, () => true, context); // settles what a dead
222
351
  - `decisions`: `classifyPage` and `rankChunks`, answered with your judge. Absent, no page is classified and no find is ranked.
223
352
  - `redact.values`: exact strings to scrub besides the built-in shapes.
224
353
  - `section.addendum`: your text after the package's prompt section.
225
- - `workspace`: where `browser_downloads` writes. Absent, that tool is not listed.
354
+ - `workspace`: where `browser_downloads` writes, and where `browser_upload` reads when `files` is absent. Absent, `browser_downloads` is not listed, and `browser_upload` is listed only if `files` is given.
355
+ - `files`: a `WorkspaceFiles` that resolves `browser_upload` paths. Given, `browser_upload` is listed without a `workspace`.
356
+ - `handoff`: a `HandoffPort` that reaches a person (`request`, then `outcome` polled until done, cancelled or expired;
357
+ when a request expires is the port's to decide). Absent, `browser_request_handoff` is not listed.
226
358
  - `prices`: your session price (for example from `BROWSERBASE_USD_PER_MINUTE`). It prices the session meter, so each session
227
359
  tool's result and each released session's record carry dollars. Without it the minutes are recorded unpriced.
228
360
 
@@ -231,7 +363,10 @@ region, a raw context id, the session timeout, the idle release and the batch ti
231
363
  package's defaults to spread and override) in the conversation's creating commit,
232
364
  selects the extensions for it, and calls `handle.release(conversation, "close", ctx)` when the conversation ends. Releases run
233
365
  as background tasks, which `waitForIdle` skips and closing the harness aborts: before it closes, a host calls
234
- `handle.drain(harness, ctx, signal?)`, which resolves once none is live. At run open, after the extensions are installed and
366
+ `handle.drain(harness, ctx, signal?)`, which resolves once none is live. A release the store cannot record (a storage error)
367
+ is still made at the provider, and the record is left for the next run's reconcile; once the store has failed,
368
+ `handle.close()` releases every session the process still holds, and over a healthy store it releases nothing. At run open,
369
+ after the extensions are installed and
235
370
  before anything resumes, it calls `handle.reconcile(harness, isActive, ctx)`, and every session a dead process left is bound,
236
371
  kept or released. The host wraps the tools (`handle.tools`) with its own policy: pause, call records, a result cap, media for
237
372
  the route.
@@ -295,6 +430,9 @@ A session is captured from the moment it is created or reattached (so after a ki
295
430
  is not recorded. The pause lasts until the page navigates and the check is clean; the gap says why in `data.detail` (`field`, `typed`,
296
431
  `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
297
432
  host's to pause with `frames.pause(session)` (lifted with `frames.resume(session)`).
433
+ 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
434
+ (`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`.
435
+ 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.
298
436
  - A live-view URL is never recorded or asked for: the recorder reads only the session's DevTools socket and never writes its address.
299
437
  - 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
300
438
  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.
@@ -43,7 +43,8 @@ export function fileEvidenceSink(root, relativeTo) {
43
43
  }
44
44
  if (!text)
45
45
  await writeFile(receipt, `${header.join("\n")}\n(the capture is ${path.basename(capture)})\n`);
46
- return { path: path.relative(relativeTo, receipt).split(path.sep).join("/"), bodyLine: text ? header.length + 1 : undefined };
46
+ const rel = (file) => path.relative(relativeTo, file).split(path.sep).join("/");
47
+ return { path: rel(receipt), bodyLine: text ? header.length + 1 : undefined, ...(text ? {} : { bodyPath: rel(capture) }) };
47
48
  }
48
49
  }
49
50
  catch {
@@ -1,7 +1,8 @@
1
1
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
2
  import { type AttachedSession, type CustodyPort, type DriverFactory, type Overrides } from "./core/custody.js";
3
- import type { BrowserConfig, BrowserPolicy, BrowserProvider, ReleaseReason, SiteRunPort } from "./core/host.js";
3
+ import type { BrowserConfig, BrowserPolicy, BrowserProvider, HandoffOutcome, HandoffPort, ReleaseReason, SiteRunPort, WorkspaceFiles } from "./core/host.js";
4
4
  import { type Redact } from "./core/redact.js";
5
+ import type { DrivingGates } from "./live-view/protocol.js";
5
6
  import { type PageDriver } from "./core/tools.js";
6
7
  import { type WebBackup } from "./core/web.js";
7
8
  export { findChrome } from "./coding-agent-local.js";
@@ -12,20 +13,32 @@ export type CodingAgentOptions = {
12
13
  /** Default: the Stagehand driver. */
13
14
  driver?: DriverFactory<PageDriver>;
14
15
  policy?: Partial<BrowserPolicy>;
16
+ /** The person/model mutex shared with the live view (`createLiveView`'s `gates`); the default, the package's process-wide `drivingGates`, is the one the live view
17
+ * defaults to as well. Pass it here only together with the same registry there. */
18
+ gates?: DrivingGates;
15
19
  /** Fetchers tried when the provider cannot fetch a page. Default: a plain HTTP read of public hosts. */
16
20
  backups?: ReadonlyArray<WebBackup>;
17
21
  env?: NodeJS.ProcessEnv;
18
22
  /** `use_website`'s sites; absent, the tool is not listed. Each child is a pi session with this extension and no
19
23
  * use_website, started through pi's SDK and disposed, so its browser released, when it reports. */
20
24
  sites?: SiteRunPort;
25
+ /** Reaches a person for `browser_request_handoff`; absent, the tool is not listed. */
26
+ handoff?: HandoffPort;
27
+ /** Resolves `browser_upload` paths. Default: files under the session's working directory. */
28
+ files?: WorkspaceFiles;
29
+ /** Lists `browser_upload` and `browser_downloads`. Default true; a use_website child gets neither. */
30
+ fileTools?: boolean;
21
31
  };
22
32
  type Deps = {
23
33
  config: BrowserConfig;
34
+ /** The live view's driving gates (default: the package's process-wide ones). */
35
+ gates?: DrivingGates;
24
36
  provider: () => Promise<BrowserProvider>;
25
37
  driver: DriverFactory<PageDriver>;
26
38
  keep: (customType: string, data: unknown) => void;
27
39
  redact: Redact;
28
40
  signal: AbortSignal;
41
+ handoff?: HandoffPort;
29
42
  };
30
43
  export declare class LocalCustody implements CustodyPort<PageDriver> {
31
44
  private readonly d;
@@ -36,8 +49,13 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
36
49
  private lastReleased;
37
50
  private seq;
38
51
  private notice;
52
+ /** The session an idle release ended, told with its notice and named while its replacement has loaded no page; any
53
+ * other release ends it, and a failed launch never touches it. */
54
+ private replacedBy;
39
55
  private readonly queue;
40
56
  private readonly idle;
57
+ /** The poll of a session the idle timer kept for a person (#1098): stopped when the session is released or closed. */
58
+ private leaving;
41
59
  constructor(d: Deps);
42
60
  private serial;
43
61
  private save;
@@ -55,11 +73,13 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
55
73
  * one again), its record stays open for the directory, which is released again by the next release, the shutdown or the next start; the
56
74
  * caller is still told what is left. */
57
75
  private finish;
76
+ private refuseHeld;
58
77
  /** Releases again each browser that is gone and whose directory was left; one that still cannot be removed stays for the next time, and the
59
78
  * last such failure is returned for a caller that was asked to release. */
60
79
  private sweepLeftovers;
61
80
  private retireEnded;
62
- session(): Promise<AttachedSession<PageDriver>>;
81
+ session(signal?: AbortSignal): Promise<AttachedSession<PageDriver>>;
82
+ current(): Promise<string | null>;
63
83
  relaunch(overrides: Overrides): Promise<AttachedSession<PageDriver>>;
64
84
  release(): Promise<{
65
85
  released: boolean;
@@ -71,12 +91,32 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
71
91
  }>;
72
92
  /** Releases without failing the caller; idempotent. */
73
93
  close(reason: ReleaseReason): Promise<void>;
94
+ hold(requestId: string): Promise<{
95
+ tag: string;
96
+ sessionId: string;
97
+ }>;
98
+ resume(notice: string | null): Promise<void>;
74
99
  dispatching(): Promise<void>;
75
100
  journal(): Promise<void>;
76
101
  mark(): Promise<void>;
77
102
  settle(): Promise<void>;
78
103
  navigated(url: string): Promise<void>;
79
104
  ended(): Promise<boolean>;
105
+ unreachable(): Promise<{
106
+ released: boolean;
107
+ lastUrl: string | null;
108
+ kept?: "held" | "viewing" | "person_driving";
109
+ }>;
110
+ /** Blocks on the port until the person answers or the call is aborted; the session comes back either way. */
111
+ handoff(ask: {
112
+ requestId: string;
113
+ instruction: string;
114
+ completionCondition: string;
115
+ }, signal?: AbortSignal): Promise<{
116
+ outcome: HandoffOutcome;
117
+ } | {
118
+ refused: string;
119
+ }>;
80
120
  dropped(): Promise<void>;
81
121
  /** A session left idle is released after the policy's idle spell. */
82
122
  activity(delta: 1 | -1): void;