@parcha/pi-browser 0.1.0-beta.31 → 0.1.0-beta.32
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +45 -0
- package/NOTICE +4 -4
- package/README.md +38 -12
- package/dist/coding-agent.d.ts +1 -0
- package/dist/coding-agent.js +2 -2
- package/dist/core/contract.js +1 -1
- package/dist/core/custody.d.ts +7 -2
- package/dist/core/custody.js +7 -3
- package/dist/core/downloads.d.ts +7 -0
- package/dist/core/downloads.js +13 -1
- package/dist/core/driving-guard.d.ts +20 -0
- package/dist/core/driving-guard.js +175 -23
- package/dist/core/driving.d.ts +56 -2
- package/dist/core/driving.js +189 -10
- package/dist/core/effects.d.ts +80 -6
- package/dist/core/effects.js +374 -41
- package/dist/core/failures.d.ts +15 -1
- package/dist/core/failures.js +7 -0
- package/dist/core/host.d.ts +11 -2
- package/dist/core/tools.d.ts +14 -0
- package/dist/core/tools.js +42 -8
- package/dist/driver/page-driver.js +77 -4
- package/dist/driver/sealed.d.ts +4 -12
- package/dist/driver/sealed.js +23 -37
- package/dist/driver/stagehand.d.ts +10 -15
- package/dist/driver/stagehand.js +19 -17
- package/dist/durable/result.d.ts +1 -2
- package/dist/durable/result.js +2 -2
- package/dist/durable/store.d.ts +4 -1
- package/dist/durable/store.js +16 -11
- package/dist/durable.d.ts +14 -1
- package/dist/durable.js +39 -12
- package/dist/live-view/index.d.ts +2 -1
- package/dist/live-view/index.js +1 -0
- package/dist/live-view/protocol.d.ts +38 -6
- package/dist/live-view/protocol.js +2 -0
- package/dist/live-view/server.d.ts +24 -1
- package/dist/live-view/server.js +131 -11
- package/dist/live-view/stream.js +16 -3
- package/dist/live-view/viewer.js +106 -13
- package/dist/providers/cdp.d.ts +0 -1
- package/dist/providers/cdp.js +33 -11
- package/dist/providers/worker-extension.d.ts +6 -0
- package/dist/providers/worker-extension.js +17 -4
- package/package.json +10 -10
- package/dist/driver/extension-worker.d.ts +0 -9
- package/dist/driver/extension-worker.js +0 -185
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,51 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
## 0.1.0-beta.32 (2026-11-10)
|
|
6
|
+
|
|
7
|
+
- `@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.
|
|
8
|
+
- **One client per browser.** Stagehand 4.4 attaches one client to a browser at a time. Closing a driver now disconnects it, so the next attach (a handoff, a reconnect, a durable reattach) is allowed; an attach while another client holds the browser fails with "A Stagehand client is already connected".
|
|
9
|
+
- **One Stagehand extension per browser.** Stagehand refuses a browser with two. The cdp provider uninstalls any other Stagehand extension from a local Chrome at each attach, so the lease's confined copy is the one used. A Chrome you attach to by endpoint must hold at most one.
|
|
10
|
+
- **The extension dials the browser directly.** `AttachTarget.extensionCdpUrl` names the browser's own DevTools URL for the extension's connection; the cdp provider sets it for a local Chrome. A dropped connection between the driver and the browser then no longer stalls the next attach for 60 s.
|
|
11
|
+
- **No trace export.** Stagehand 4.4 exports traces only to an endpoint it is given, and the driver gives none. The closed loopback trace port, and the request observer's exemption for it, are gone.
|
|
12
|
+
- **Shutdown with no drain.** `handle.close()` of the pi-durable adapter now waits (30 s at most) for this process's `close` releases that no `drain` since covered to reach the provider. Before, a host that closed the Harness straight after them left the browser running whenever the driver closed fast enough, which Stagehand 4.4's does.
|
|
13
|
+
- The pi family is 1.5.0 exactly (pi-durable, pi-ai, pi-coding-agent, chord), with one typebox (1.3.27); the older-pi CI legs are gone. A pi 1.5 run store is SQLite schema 2, which pi 1.3.0 or earlier cannot open again, so there is no rollback past this release. Tool results are under `output` only. A browser charge serve fails to count makes the run's spend unknown, and a capped run then refuses its next paid call until the spend is known again. The door's `GET /events` and a recording's live lines read through an adapter on pi 1.5's `observeCommits` (pi-durable-disk `./internals` `watchEvents`, with no compatibility promise) until they move to `conversation.watch`. A failed run store's close releases this process's live browser sessions again; a normal close keeps them for the next run. A claude-agent, codex or opencode run opens on pi 1.5, and an image it reads through pi's read tool is read. particle-1's cap hold keeps Particle's list price over pi-ai's promotional catalog price; a request is still booked at OpenRouter's billed total. The agent store reader reads pi-durable schema 2.
|
|
14
|
+
- The owner watches a run's browser live from the console, read-only. `GET /v2/runs/{id}/browser` answers `{state: "live", viewer}` while the run's browser session is open (`viewer`, a link on this server with its token in the fragment), `{state: "none"}` when it has a browser with no session open, and `{state: "off", reason}` when it has none (no `browser` tool, or its browser resolves unavailable here); it takes the owner's password session in the console, never a token (`403`). Capabilities say so: `features.browser_live: {read_only: true}`.
|
|
15
|
+
- The view is pi-browser's own viewer for every vendor, served by the run's process on a loopback port of its own: the vendors' own live-view links never leave that process. The process hands each session's viewer to the server in a file of that session's own in the run's directory, outside `work/` (`browser-live/<session>.json`, 0600, written whole), which goes when that session ends and never touches another session's; the token dies with the session, and the old link opens nothing.
|
|
16
|
+
- The viewer's page and WebSocket are proxied under `/v2/runs/{id}/browser/live/` to that run's port alone: the page under `frame-ancestors 'self'` (the console keeps `'none'` everywhere else), the WebSocket from this server's own origin with the owner's session only. One viewer at a time (`viewer_in_use`).
|
|
17
|
+
- The token is in no record, timeline row, run view, run file, home, log or the model's context.
|
|
18
|
+
- `@parcha/pi-browser`'s live view takes `readOnly`: every input, navigation and dialog answer is dropped on the server (`held read_only`), `ready` says `readOnly: true`, and a watching viewer keeps no session open. A browser with no page yet (Kernel's headless one starts with none) tells the viewer `no_page`, and the page says "No page yet" until one opens.
|
|
19
|
+
- `createBrowserExtension` takes `beforeCreate` (type `BeforeCreate`): the host's step between a session's `creating` record (its tag, in the inventory) reaching the store and the provider's create, with the session's conversation, its tag and its commit. Nothing is created at the provider before it resolves; one that throws creates nothing, and the record ends released (`create_failed`).
|
|
20
|
+
- The owner takes over a run's browser from the live view and hands it back, and the agent can ask them to. Capabilities say so: `features.browser_live: {read_only: false, take_over: true, ask: true}`.
|
|
21
|
+
- **Take over, hand back.** The viewer watches until the owner presses Take over in it; until then the run drops its input before the browser. The hold lasts until Hand back, the viewer is gone 2 minutes, or 15 minutes pass with no input. Meanwhile the agent's browser calls wait inside the tool, then go on with the page's old element ids dropped and the model told plainly that the person had the browser. Each change of hands moves the session's epoch, so an act a call took before it is refused. The run stays `working`; the timeline says "You took over the browser" and "You handed the browser back". A page's dialog that opens before the owner takes over never covers Take over; it says to take over to answer it, and its buttons stay off until they do.
|
|
22
|
+
- **The agent asks.** `browser_request_handoff` is listed. The run reads `input_required`/`waiting` with `pending: {kind: "browser", instruction, completion_condition, asked_at, expires_at}`, a "Waiting for you: <instruction>" row, and `run.needs_input` with `pending.kind: "browser"`. The owner answers `POST /v2/runs/{id}/browser/hand-back` `{outcome: "done" | "cancelled"}` (their password session only): the first answer wins, a different later one is `409 handoff_answered`; unanswered for 15 minutes it expires. Handing the browser back in the viewer answers the agent's open ask on that session `done` too (first answer wins); a take-over that ends any other way (idle, away, the cap) leaves the ask open. An ask whose waiting row cannot be written fails, its tool's result saying so, with nothing held or left open, so asking again shows it. Each ask is its session's own: two conversations of a run that pick the same request id make two asks, each with its own instruction, answer and take-over.
|
|
23
|
+
- **The owner's time counts.** A take-over and an ask hold 15 minutes of session time at the provider's price under the run's cap before they start (once per session: a take-over and an ask on it share one hold); with no room they are refused in the cap's words (in the viewer, or in the tool's result). A take-over that input keeps alive is held again every 15 minutes, and with no room the browser goes back to the agent at the cap. When the browser comes back, the time the person had stays held until the session's next charge books it. An ask a restarted run's process takes up holds only what is left of it, up to its expiry, and none once it is past.
|
|
24
|
+
- A run's process that dies while the agent's ask waits is started again, and the new process takes the wait up: the owner's answer reaches the agent, or the ask expires. That holds when the owner answers after the process went and before the server found it gone: the hand-off is started again until its call's result is saved, the answer already on disk.
|
|
25
|
+
- A browser session a restarted run's process keeps gets its viewer handed over again: the owner no longer reads `none` while it is live.
|
|
26
|
+
- **The viewer's code is the server's own.** Serve now serves the viewer's page, script and style from the pi-browser it has installed, never from the run's port; only the viewer's WebSocket goes to the run.
|
|
27
|
+
- `@parcha/pi-browser`'s live view takes `takeOver: { take(tag) }`, the driving gate gains `take`, `give`, `held`, `epoch`, `setPresent`, `untilFree`, `command` and `settling` (with `holdIdleMs`, `holdAwayMs` and `settleMs`: a hand-back wakes the agent only once the person's last command has returned, or `settleMs` has let it go, after which it no longer renews the person's turn), and `viewerAssets` is exported from `@parcha/pi-browser/live-view`.
|
|
28
|
+
- The timeline's "Waiting for you" row for a browser hand-over (`agent.handover`) takes the host's redact, as a tool call's arguments do: a held value the model echoes in what it asks never shows; the run's `pending` for a browser ask is redacted the same way.
|
|
29
|
+
- A cancelled browser call no longer waits for an allowed request's response head before it returns. After the effect observer lets a held request go under allow, a call's flush waits, within its bound, for the response's head (so a redirect's next hop is decided under the same call); a cancelled call now stops that wait at once instead of after up to 1 s.
|
|
30
|
+
- `browser_downloads` no longer files a download Chrome is still writing. At the end of a download (sandboxed, on a busy machine), Chrome creates the file's name empty for a moment while the bytes are still in its `.crdownload`; the local Chrome provider listed that empty file as finished, so a call in that moment copied an empty file into the workspace with the empty file's SHA-256. Now such a file, and the `.crdownload` itself, are listed as still downloading and skipped with "still downloading; call browser_downloads again", and the next call files them; a read that finds the file replaced or changed by the time it ends is skipped the same way.
|
|
31
|
+
- A page request the browser loses before it is sent is told to the call, so the model can send it again. Chrome sometimes restarts its network service while the effect observer holds requests, more often on a busy machine. A request still on its way at that moment was never sent, and the page may never hear of it. `run` and `browser_upload` now say so in plain words ("The browser lost a request your page made before the request left the browser: POST https://…/path … so the request was not sent"), and list it in `details.lost` by method and URL, with no query, body or header. A call whose action fails says it too, after the error's own words. A form is told once.
|
|
32
|
+
- `EffectObserver.record(listener, lost?)` takes a second listener, which hears of each lost request (`requestId`, `method`, `origin`, `path`) while the call records.
|
|
33
|
+
- A lost request is never journaled, so it never counts as sent or allowed. If Chrome pauses it after all, it is refused and journaled denied. The observer holds and denies every request after the restart as before.
|
|
34
|
+
- The observer asks Chrome for its network service's pid only while a held request waits for its pause: once per request (at most one question per 50 ms, which requests announced meanwhile share), then every 250 ms while it waits, never when idle, and never for an observer that holds nothing. A browser that refuses the question, or never names a network service of its own for 2 s, is not asked again. When a known service is gone, the call's flush waits for its successor, up to 10 s or until the call is cancelled; if none shows, its waiting requests are told lost and the next service is learned afresh. One question unanswered for 1 s counts as no answer, never as a restart, and is not kept; after three in a row (an answer with no result, or a failed question, counts too) the observer stops asking until a new held request. Over the 12-case effect matrix under deny that was 16 questions of about 3 ms each.
|
|
35
|
+
- A form POST lost before its request existed is told by its frame's intent; if its Document request is paused after all, it is refused.
|
|
36
|
+
- A redirect's next hop of a held request is held and decided under the same call: after an allowed request is continued, the call's flush waits, within its bound, for the response's head, and a 307 hop is journaled as a row of its own (`<id>#2`) instead of replacing the first hop's row. A hop after a redirect is never told "not sent", since its first hop went out. Before, a call could end between the hops, so the second hop's decision belonged to the next call or to none.
|
|
37
|
+
- Live view and take-over follow-ups: the watch-only viewer reads as watching, the page fills the viewer's window, a broken connection never writes an HTTP line into an open viewer, two take-over notices say what happened, and a run of several actions stops before an action on a new document.
|
|
38
|
+
- A view-only viewer shows "View only: you're watching the agent's browser; your clicks and keys are not sent." in a banner of its own, with the page's address beside it as plain text (cut with an ellipsis, the whole address in its tooltip), never the take-over wording that input is held, and no toolbar (its back, reload and address field acted on nothing there).
|
|
39
|
+
- In every mode the page fills the window at its own shape and follows it as the window resizes, with clicks still landing where they are made; the end of a session (released, refused or disconnected) reads in large type over a dimmed page.
|
|
40
|
+
- A run's live view whose browser connection breaks mid-session just closes the viewer's WebSocket: the server no longer writes an HTTP "502" (or "500") line into a WebSocket stream already open.
|
|
41
|
+
- A take-over whose hold ended before it went live (the agent's step ran on) says "Your take-over did not start: …" instead of that the browser went back to the agent, which the person never had.
|
|
42
|
+
- A live view whose gate registry cannot hold refuses a take with "This browser can't be handed over from the live view." instead of telling the person it is held already.
|
|
43
|
+
- A run of several snapshot actions stops before an action that would land on a new document (a link to another page, a reload): the action is not sent, and the run answers `stale_snapshot`, partial, with how many ran, telling the model to snapshot again. A #hash change or history.pushState/replaceState keeps the document, and the run goes on.
|
|
44
|
+
- A take-over now reads as it happened on the Timeline. "You took over the browser" and "You handed the browser back" each show the time it happened, so the gap between them is how long you held the browser. Before, each showed the time of the row above it, so an 11 s hold could read as 3 s. The agent's browser call that waited for your hand-back says so: "Waited for you 11 s, then opened www.example.com/…". Before, it read as the agent opening the page while you had the browser. Upgrading: nothing to do.
|
|
45
|
+
- pi-browser: a browser call that waited for the person adds `waited_for_person_ms` to its result's `details`; one stopped while it waited adds nothing.
|
|
46
|
+
- pi-durable-agent: a `HOST_PHASE` entry's `at` (ms) is its row's time, and a browser call's row whose result has `waited_for_person_ms` starts "Waited for you <time>, then …" when the call succeeded, and "Waited for you <time>: …" when it failed.
|
|
47
|
+
- Packages take TypeBox's `Type`, `Static` and `TSchema` from typebox, never through pi-ai, pi-agent-core, pi-durable or chord, which drop those re-exports from pi 1.5. serve, pi-browser and pi-agent-learn now depend on typebox 1.3.27 directly (the version pi-ai 1.1 resolves); harness and agentrun-pi keep it as a host-provided peer. Tool schemas serialize exactly as before, so tool arguments are checked the same. harness's `shownShots` has a named return type, `ShownShots`.
|
|
48
|
+
- `npm run test:affected` (`node scripts/test-affected.mjs`) runs only the test files a change reaches: a changed test file, the tests that import a changed source file directly or transitively (imports read from the parse tree, `dist/` mapped back to `src/`, workspace names resolved through `exports`), a package's every test when its `package.json`, tsconfig or build script changes, and the tests that name a changed file where an import can't say. A shared root (root manifests, `scripts/`, `.github/`) adds only its importers, and a fast smoke file per package always runs. It prints a command per suite, or the files (`--list`), or why each file was picked (`--json`). CI still runs every suite. pi-browser's test runner (`node scripts/run-tests.mjs`) now runs only the test files it is given.
|
|
49
|
+
|
|
5
50
|
## 0.1.0-beta.31 (2026-11-06)
|
|
6
51
|
|
|
7
52
|
- A model granted both web_fetch and the browser is now told which one has cookies. Asked to "Open https://httpbin.org/cookies", a pi run picked web_fetch, which has no cookies, and answered with an empty page; it picked the browser only when told to. The tool descriptions the model reads now say:
|
package/NOTICE
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
AgentRun
|
|
2
2
|
Copyright 2026 Parcha Labs, Inc.
|
|
3
3
|
|
|
4
|
-
This package contains two pieces of Stagehand
|
|
4
|
+
This package contains two pieces of Stagehand (https://github.com/browserbase/stagehand), both under its MIT license,
|
|
5
5
|
whose text follows:
|
|
6
6
|
|
|
7
|
-
- The Chrome launch flags in src/providers/
|
|
8
|
-
(DEFAULT_CHROME_FLAGS).
|
|
9
|
-
- The files in src/vendor/stagehand-facade (compiled to dist/vendor/stagehand-facade), copied from
|
|
7
|
+
- The Chrome launch flags in src/providers/chrome-args.ts, copied from Stagehand 4.1.0's
|
|
8
|
+
packages/sdk-ts/src/browser/localBrowser.ts (DEFAULT_CHROME_FLAGS).
|
|
9
|
+
- The files in src/vendor/stagehand-facade (compiled to dist/vendor/stagehand-facade), copied from Stagehand 4.1.0's
|
|
10
10
|
packages/integrations/core/src/facade at commit cd7b230778cf92269e4cb90e80d97f5113781c51. UPSTREAM.json, shipped
|
|
11
11
|
beside them as src/vendor/stagehand-facade/UPSTREAM.json, records each file's upstream blob and SHA-256.
|
|
12
12
|
|
package/README.md
CHANGED
|
@@ -10,8 +10,8 @@ Your agent gets its own browser, and you can take over and hand it back.
|
|
|
10
10
|
|
|
11
11
|
If the process dies, a pi-durable host recovers the session and does not repeat an action. See [For hosts](#for-hosts).
|
|
12
12
|
|
|
13
|
-
Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=22.19.0`, pi 1.
|
|
14
|
-
pi-durable and chord peers
|
|
13
|
+
Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=22.19.0`, pi 1.5.0 exactly (its
|
|
14
|
+
pi-durable and chord peers). ESM only: the
|
|
15
15
|
package has `import` entries and no `require` entry.
|
|
16
16
|
|
|
17
17
|
## Install
|
|
@@ -19,10 +19,10 @@ package has `import` entries and no `require` entry.
|
|
|
19
19
|
```sh
|
|
20
20
|
pi install npm:@parcha/pi-browser@latest # the pi coding agent's extension
|
|
21
21
|
npm install @parcha/pi-browser@latest # the library: providers, driver, durable adapter
|
|
22
|
-
npm install @parcha/pi-browser@latest @earendil-works/pi-durable@1.
|
|
22
|
+
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
23
|
```
|
|
24
24
|
|
|
25
|
-
`pi install` loads the extension. A Chrome starts on the model's first browser call, and not before.
|
|
25
|
+
`pi install` loads the extension. A Chrome starts on the model's first browser call, and not before.
|
|
26
26
|
|
|
27
27
|
## Quick start
|
|
28
28
|
|
|
@@ -94,7 +94,7 @@ The same tools run on three kinds of browser. You pick one when you set up the p
|
|
|
94
94
|
|
|
95
95
|
| Provider | What it is | What it needs |
|
|
96
96
|
|---|---|---|
|
|
97
|
-
| 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. |
|
|
97
|
+
| 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 137 or later. No key. |
|
|
98
98
|
| Browserbase (`/providers/browserbase`) | A Browserbase session, through its SDK. | `BROWSERBASE_API_KEY` and the `@browserbasehq/sdk` peer. |
|
|
99
99
|
| Kernel (`/providers/kernel`) | A Kernel browser, through its REST API. | `KERNEL_API_KEY`. No SDK. |
|
|
100
100
|
|
|
@@ -160,6 +160,32 @@ registry, pass the same one to both sides: `const gates = createDrivingGates({ i
|
|
|
160
160
|
|
|
161
161
|
`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.
|
|
162
162
|
|
|
163
|
+
`readOnly: true` makes the view watch-only: every input, navigation and dialog answer a viewer sends is dropped on the server, before the browser (`held read_only`, and
|
|
164
|
+
one that keeps sending is closed), its `ready` carries `readOnly: true` and the page shows "view only" with its controls off; a watching viewer never sets `viewing`, so it
|
|
165
|
+
keeps no session open. A browser with no page to show (a headless one that starts with none, or whose last page closed) sends `no_page`, and the page says "No page yet"
|
|
166
|
+
until one opens.
|
|
167
|
+
|
|
168
|
+
`takeOver: { take(tag) }` makes the view drive only once the person takes the browser. The page shows **Take over** and **Hand back** in its own bar and sends `take`
|
|
169
|
+
and `give`; outside a hold every input, navigation and dialog answer is dropped on the server (`held not_taken`). A `take` asks the host's `take(tag)` first, which may
|
|
170
|
+
refuse in its own words (a spend cap with no room for the person's time; the viewer shows `take_refused` with them), or answers `{ end(why), started?(), cancel?() }` (`started` as the hold goes live, `cancel` instead of `end` when no hold starts after all: the session released, the viewer gone, or the browser held already, which the viewer is told as `take_refused`); the session's gate then
|
|
171
|
+
holds the browser for the person (`drivingGates(tag).take()`) until their `give`, `holdIdleMs` with no input (15 minutes), `holdAwayMs` with no viewer connected
|
|
172
|
+
(2 minutes), or the session's release, and `end` is called once with why (`given`, `answered`, `cap`, `idle`, `away`, `released`). A host gives the
|
|
173
|
+
browser back at its spend cap with `drivingGates(tag).give("cap", words)`: the viewer's `hold` end carries the words as `message`. The viewer is told `hold` as it starts
|
|
174
|
+
and ends; `ready` carries `takeOver: true` and whether it holds now, so a viewer that reconnects within the away window still holds it. While held, every model call
|
|
175
|
+
waits inside its tool (it does not fail; an abort ends the wait with nothing done), and past the hold's end until the person's last command has returned (a Back
|
|
176
|
+
between reading the history and moving; at most `settleMs`, 10 s, after which that command is let go and moves nothing more), then goes on with its old element ids dropped and told plainly that the person had
|
|
177
|
+
the browser and the page may have changed. Its result's `details` then say how long it waited (`waited_for_person_ms`), so a timeline shows the call waited for the
|
|
178
|
+
person rather than acting while they had the browser; a call stopped while it waits did nothing and carries none. Each change of hands moves the gate's epoch (`drivingGates(tag).epoch()`), and a driver a call took before it is refused at
|
|
179
|
+
its next act (a `FenceRefusal`), so an agent action from before the person took over never reaches the page: a `run` of
|
|
180
|
+
several actions has all of them checked against the snapshot first (`checkActions`: a stale id anywhere sends none), then is
|
|
181
|
+
sent one action at a time, each checked against the epoch. One stopped partway (a take, or a later action failing) says
|
|
182
|
+
`effect: "partial"` with `completed`, how many ran. An act already sent (a `run`'s code is one batch inside
|
|
183
|
+
the browser, out of reach once sent) ends first: a take while a model call runs is held at once, no call starts, and the
|
|
184
|
+
hold goes live (`holding()`, the viewer's `hold`, the person's input taken) once that call returns. A host gives the browser back itself with
|
|
185
|
+
`drivingGates(tag).give("answered")` (an agent's handoff that was answered). A watching take-over viewer keeps no session from its idle release; a held one is kept by
|
|
186
|
+
its hold. `viewerAssets` (from `@parcha/pi-browser/live-view`) are the viewer's page, script and style, for a host that serves the page from its own origin and
|
|
187
|
+
passes only the WebSocket to the live view.
|
|
188
|
+
|
|
163
189
|
Limits: JS dialogs show with accept and dismiss. A file chooser and downloads are not supported.
|
|
164
190
|
|
|
165
191
|
## Saved sign-ins
|
|
@@ -258,9 +284,7 @@ Stagehand, undici, zod and the two HTML packages are dependencies. Four optional
|
|
|
258
284
|
| `@earendil-works/pi-durable` and `@earendil-works/chord` | `/durable`, the adapter for a pi-durable Harness. |
|
|
259
285
|
| `@browserbasehq/sdk` | the Browserbase provider. Kernel needs no SDK. |
|
|
260
286
|
|
|
261
|
-
The pi peers are `@earendil-works/pi-durable` and `chord`
|
|
262
|
-
|
|
263
|
-
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.
|
|
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
288
|
|
|
265
289
|
## Entries
|
|
266
290
|
|
|
@@ -283,7 +307,8 @@ pi 1.0.4 or 1.1.x users: pin `@earendil-works/pi-codemode` to the same version a
|
|
|
283
307
|
- `/driver/stagehand`: `stagehandDriver()`, Stagehand v4 over upstream's facade, vendored unedited in
|
|
284
308
|
`src/vendor/stagehand-facade/`. `UPSTREAM.json` names the commit and each file's blob id and SHA-256;
|
|
285
309
|
`node scripts/vendor-facade.mjs --check` verifies them and `--commit SHA --release NAME` re-vendors. Stagehand is created
|
|
286
|
-
sealed: no inference, no cache,
|
|
310
|
+
sealed: no inference, no cache, and no trace endpoint, so no trace is exported. Stagehand attaches one client to a browser
|
|
311
|
+
at a time: closing a driver disconnects it, so the next attach is allowed.
|
|
287
312
|
- `/providers/browserbase`, `/providers/kernel`, `/providers/cdp`: where browsers come from. Browserbase through its SDK,
|
|
288
313
|
with the credential-proxy dial and the connect-URL rewrite. Kernel through its REST API on the package's own HTTP agent.
|
|
289
314
|
Any CDP endpoint, or a local Chrome the provider starts and kills by exact pid.
|
|
@@ -316,7 +341,7 @@ else the first of `google-chrome`, `chromium` and the usual install locations (`
|
|
|
316
341
|
| `--browser-chrome PATH`, `PI_BROWSER_CHROME` | The Chrome to start. A path that does not exist is refused by name, never replaced. |
|
|
317
342
|
| `--browser-headed`, `PI_BROWSER_HEADED=1` | Show the window instead of running headless. |
|
|
318
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. |
|
|
319
|
-
| `--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. |
|
|
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. |
|
|
320
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. |
|
|
321
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. |
|
|
322
347
|
|
|
@@ -330,7 +355,7 @@ What it does with your machine and your data:
|
|
|
330
355
|
- Each browser session is appended to the pi session file (`browser.session` entries; the model never sees them). The coding
|
|
331
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
|
|
332
357
|
that a crashed pi left running is closed when that session is next started, never adopted.
|
|
333
|
-
- Stagehand
|
|
358
|
+
- Stagehand is given no trace endpoint, so it exports no traces: nothing you browse goes to a third party.
|
|
334
359
|
- `browser_relaunch` with `verified` or `geolocation` changes nothing on a local Chrome or on Kernel; they are Browserbase features.
|
|
335
360
|
With proxies off (the default), a `geolocation` is refused and the session is left as it was, as in the pi-durable adapter.
|
|
336
361
|
- A host that builds the extension with `policy: { actions: "deny" }` or `"ask"` asks for requests to be held, and the coding
|
|
@@ -417,7 +442,8 @@ region, a raw context id, the session timeout, the idle release and the batch ti
|
|
|
417
442
|
package's defaults to spread and override) in the conversation's creating commit,
|
|
418
443
|
selects the extensions for it, and calls `handle.release(conversation, "close", ctx)` when the conversation ends. Releases run
|
|
419
444
|
as background tasks, which `waitForIdle` skips and closing the harness aborts: before it closes, a host calls
|
|
420
|
-
`handle.drain(harness, ctx, signal?)`, which resolves once none is live. A
|
|
445
|
+
`handle.drain(harness, ctx, signal?)`, which resolves once none is live. A host that closes with no drain after its `close`
|
|
446
|
+
releases gets them at the provider all the same: `handle.close()` waits, 30 s at most, for every one no drain since covered. A release the store cannot record (a storage error)
|
|
421
447
|
is still made at the provider, and the record is left for the next run's reconcile; once the store has failed,
|
|
422
448
|
`handle.close()` releases every session the process still holds, and over a healthy store it releases nothing. At run open,
|
|
423
449
|
after the extensions are installed and
|
package/dist/coding-agent.d.ts
CHANGED
package/dist/coding-agent.js
CHANGED
|
@@ -191,7 +191,7 @@ export class LocalCustody {
|
|
|
191
191
|
this.replacedBy = null;
|
|
192
192
|
await this.captured(live);
|
|
193
193
|
await this.sweepLeftovers();
|
|
194
|
-
// A close that never comes back
|
|
194
|
+
// A close that never comes back never holds up the provider's release (closeDriver waits DRIVER_CLOSE_MS at most).
|
|
195
195
|
if (live.driver)
|
|
196
196
|
await closeDriver(live.driver);
|
|
197
197
|
try {
|
|
@@ -375,7 +375,7 @@ export class LocalCustody {
|
|
|
375
375
|
await this.resume(null);
|
|
376
376
|
if (this.live)
|
|
377
377
|
await this.captured(this.live, true);
|
|
378
|
-
return { outcome: answer };
|
|
378
|
+
return typeof answer === "string" ? { outcome: answer } : answer;
|
|
379
379
|
}
|
|
380
380
|
await sleep(backoffMs(attempt), undefined, { signal: stop });
|
|
381
381
|
}
|
package/dist/core/contract.js
CHANGED
|
@@ -122,7 +122,7 @@ const browserDownloads = {
|
|
|
122
122
|
name: "browser_downloads",
|
|
123
123
|
label: "Browser: downloads",
|
|
124
124
|
description: "Copy the files this browser session downloaded into the workspace under downloads/, with downloads/manifest.json listing each file's SHA-256. " +
|
|
125
|
-
"Returns the files fetched now, those fetched before and those skipped, never their bytes; open a fetched file with read.",
|
|
125
|
+
"Returns the files fetched now, those fetched before and those skipped with why, never their bytes; open a fetched file with read. A file the browser is still downloading is skipped as still downloading: call again to fetch it.",
|
|
126
126
|
parameters: object({}),
|
|
127
127
|
effect: "read", replay: "safe", executionMode: "sequential", evidence: "files", listedWhen: "downloads",
|
|
128
128
|
};
|
package/dist/core/custody.d.ts
CHANGED
|
@@ -5,8 +5,12 @@ import { type LeaseState } from "./lease.js";
|
|
|
5
5
|
export type BrowserDriver = {
|
|
6
6
|
close(): Promise<void>;
|
|
7
7
|
};
|
|
8
|
-
/** A
|
|
9
|
-
|
|
8
|
+
/** A driver's close is waited for this long at most, so a close that never comes back (any `DriverFactory` may be passed)
|
|
9
|
+
* never holds up a release. It is past the longest a Stagehand disconnect takes (10 s for the instance's close, then 10 s
|
|
10
|
+
* for the detach): a shorter wait could return while the client is still attached, and the next attach to the browser is
|
|
11
|
+
* refused until it has let go. */
|
|
12
|
+
export declare const DRIVER_CLOSE_MS = 25000;
|
|
13
|
+
/** A close that fails is not the caller's: the session goes on or is released either way. */
|
|
10
14
|
export declare function closeDriver(driver: BrowserDriver): Promise<void>;
|
|
11
15
|
export type DriverOptions = {
|
|
12
16
|
batchTimeoutMs: number;
|
|
@@ -107,6 +111,7 @@ export interface CustodyPort<D extends BrowserDriver = BrowserDriver> {
|
|
|
107
111
|
completionCondition: string;
|
|
108
112
|
}, signal?: AbortSignal): Promise<{
|
|
109
113
|
outcome: HandoffOutcome;
|
|
114
|
+
reason?: string;
|
|
110
115
|
} | {
|
|
111
116
|
refused: string;
|
|
112
117
|
}>;
|
package/dist/core/custody.js
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
import { browserFailure } from "./failures.js";
|
|
2
2
|
import { isLeaseTransition } from "./lease.js";
|
|
3
3
|
import { startSpent } from "./usage.js";
|
|
4
|
-
/** A
|
|
5
|
-
|
|
4
|
+
/** A driver's close is waited for this long at most, so a close that never comes back (any `DriverFactory` may be passed)
|
|
5
|
+
* never holds up a release. It is past the longest a Stagehand disconnect takes (10 s for the instance's close, then 10 s
|
|
6
|
+
* for the detach): a shorter wait could return while the client is still attached, and the next attach to the browser is
|
|
7
|
+
* refused until it has let go. */
|
|
8
|
+
export const DRIVER_CLOSE_MS = 25_000;
|
|
9
|
+
/** A close that fails is not the caller's: the session goes on or is released either way. */
|
|
6
10
|
export async function closeDriver(driver) {
|
|
7
11
|
let timer;
|
|
8
12
|
await Promise.race([driver.close().catch(() => undefined), new Promise((resolve) => { timer = setTimeout(resolve, DRIVER_CLOSE_MS); })]);
|
|
@@ -208,7 +212,7 @@ export const custodyTools = {
|
|
|
208
212
|
if ("refused" in answer)
|
|
209
213
|
return text(browserFailure("refused", `No person could take the browser: ${answer.refused}. Your session is unchanged; go on without the handoff.`), true);
|
|
210
214
|
const next = answer.outcome === "done" ? "Take a snapshot and verify the completion condition on the page before acting." : "The person did not finish. Take a snapshot to see the page before deciding what to do next.";
|
|
211
|
-
return text({ ok: true, outcome: answer.outcome, completion_condition: args.completion_condition, next });
|
|
215
|
+
return text({ ok: true, outcome: answer.outcome, ...(answer.reason ? { reason: answer.reason } : {}), completion_condition: args.completion_condition, next });
|
|
212
216
|
}
|
|
213
217
|
catch (error) {
|
|
214
218
|
return failed(error);
|
package/dist/core/downloads.d.ts
CHANGED
|
@@ -4,6 +4,13 @@ export declare const DOWNLOADS_DIR = "downloads";
|
|
|
4
4
|
export declare const DOWNLOADS_MANIFEST = "downloads/manifest.json";
|
|
5
5
|
export declare const MAX_DOWNLOAD_BYTES: number;
|
|
6
6
|
export declare const MAX_DOWNLOAD_FILES = 50;
|
|
7
|
+
/** What a skipped download the browser is still writing says: the next call files it. */
|
|
8
|
+
export declare const STILL_DOWNLOADING = "still downloading; call browser_downloads again";
|
|
9
|
+
/** A provider's read of a file the browser was still writing (its bytes or its name moved while it was read). */
|
|
10
|
+
export declare class DownloadNotSettled extends Error {
|
|
11
|
+
readonly code = "not_settled";
|
|
12
|
+
constructor(name: string);
|
|
13
|
+
}
|
|
7
14
|
/** The handle `browser_release` returns for a session's recording; the host's `read` door resolves it. */
|
|
8
15
|
export declare const recordingHandle: (sessionId: string) => string;
|
|
9
16
|
export type DownloadEntry = {
|
package/dist/core/downloads.js
CHANGED
|
@@ -9,6 +9,13 @@ export const DOWNLOADS_MANIFEST = "downloads/manifest.json";
|
|
|
9
9
|
const LOCK_FILE = ".downloads.lock";
|
|
10
10
|
export const MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
|
|
11
11
|
export const MAX_DOWNLOAD_FILES = 50;
|
|
12
|
+
/** What a skipped download the browser is still writing says: the next call files it. */
|
|
13
|
+
export const STILL_DOWNLOADING = "still downloading; call browser_downloads again";
|
|
14
|
+
/** A provider's read of a file the browser was still writing (its bytes or its name moved while it was read). */
|
|
15
|
+
export class DownloadNotSettled extends Error {
|
|
16
|
+
code = "not_settled";
|
|
17
|
+
constructor(name) { super(`${name} changed while it was read`); }
|
|
18
|
+
}
|
|
12
19
|
/** The handle `browser_release` returns for a session's recording; the host's `read` door resolves it. */
|
|
13
20
|
export const recordingHandle = (sessionId) => `session:${sessionId}`;
|
|
14
21
|
/** A name that stays inside `downloads/`: the last path segment, no control characters, not hidden, not the manifest. */
|
|
@@ -84,6 +91,10 @@ export async function fetchDownloads(options) {
|
|
|
84
91
|
result.already_fetched.push(entry(known));
|
|
85
92
|
continue;
|
|
86
93
|
}
|
|
94
|
+
if (file.downloading) {
|
|
95
|
+
result.skipped.push({ name: file.name, reason: STILL_DOWNLOADING });
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
87
98
|
// Counts attempts, not places in the provider's list, so files fetched before never starve the ones behind them.
|
|
88
99
|
if (attempted >= (options.maxFiles ?? MAX_DOWNLOAD_FILES)) {
|
|
89
100
|
result.skipped.push({ name: file.name, reason: "over the per-call file limit; call again" });
|
|
@@ -136,7 +147,8 @@ export async function fetchDownloads(options) {
|
|
|
136
147
|
}
|
|
137
148
|
catch (error) {
|
|
138
149
|
await rm(part, { force: true });
|
|
139
|
-
|
|
150
|
+
const reason = error instanceof DownloadNotSettled ? STILL_DOWNLOADING : error instanceof Error ? (options.redact ?? ((text) => text))(error.message).slice(0, 200) : "the read failed";
|
|
151
|
+
result.skipped.push({ name: file.name, reason });
|
|
140
152
|
}
|
|
141
153
|
}
|
|
142
154
|
return result;
|
|
@@ -3,11 +3,31 @@ import { type DrivingGates } from "./driving.js";
|
|
|
3
3
|
import type { ToolImpl } from "./tools.js";
|
|
4
4
|
/** Told to the model's next call once a person has driven the session through the live view: the page can change without its URL changing. */
|
|
5
5
|
export declare const PERSON_DROVE = "A person used this browser through the live view since your last call, so the page may have changed even where its address did not: take a snapshot before you act on an element by its id.";
|
|
6
|
+
/** Told, before PERSON_DROVE, to a call that waited while the person held the browser. */
|
|
7
|
+
export declare const PERSON_HAD = "This call waited while the person had the browser: they took it over through the live view and have handed it back.";
|
|
8
|
+
/** Told, instead, to a call that waited through a take the person did not use: no input of theirs reached the page, so the
|
|
9
|
+
* snapshot stands and nothing says the page changed. */
|
|
10
|
+
export declare const PERSON_HAD_UNUSED = "This call waited while the person had the browser: they took it over through the live view and handed it back without using it, so the page is as you left it.";
|
|
11
|
+
/** The mark (in a call's result details) of an act the person's take made stale: the person drove the session through the
|
|
12
|
+
* live view while the call waited, so the snapshot its element ids came from no longer stands. Its timeline row reads
|
|
13
|
+
* neutral, in plain words (pi-durable-agent's timeline), never as a failure. */
|
|
14
|
+
export declare const PAGE_CHANGED_WHILE_HELD = "page_changed_while_held";
|
|
15
|
+
/** Told to the model by such an act: nothing was done, and its next step is a snapshot. */
|
|
16
|
+
export declare const PAGE_CHANGED_FOR_MODEL = "The person changed the page while they had the browser, so this action was not done. Take a snapshot first, then act on the page as it is now.";
|
|
17
|
+
/** What a model call that was under way when the person took the browser is told at its next act on it: nothing more of it reached the page. */
|
|
18
|
+
export declare const personTookFailure: (acted: boolean, batch?: {
|
|
19
|
+
completed: number;
|
|
20
|
+
of: number;
|
|
21
|
+
}) => import("./failures.js").BrowserFailure;
|
|
22
|
+
/** How long a call waited for the person to hand the browser back, in its result's details: a host's timeline says the
|
|
23
|
+
* call waited, and for how long, so a call row that spans a take-over does not read as the agent acting meanwhile. */
|
|
24
|
+
export declare const WAITED_FOR_PERSON = "waited_for_person_ms";
|
|
6
25
|
/** One browser tool as a model call on its session's driving gate: it is refused, typed and before it has done anything, while a person drives that session
|
|
7
26
|
* through the live view, and it holds the gate for as long as it runs, so the viewer's input is held meanwhile. The session is known when the tool first
|
|
8
27
|
* asks its port for it (`session()` or `relaunch()`), which is every tool's first act on the browser. */
|
|
9
28
|
export declare function drivingGuard<D extends BrowserDriver, A = unknown>(impl: ToolImpl<D, A>, gates?: DrivingGates, options?: {
|
|
10
29
|
early?: boolean;
|
|
30
|
+
now?: () => number;
|
|
11
31
|
}): ToolImpl<D, A>;
|
|
12
32
|
/** Every implementation of a toolset guarded as above. */
|
|
13
33
|
export declare function drivingGuarded<D extends BrowserDriver>(impls: Partial<Record<string, ToolImpl<D>>>, gates?: DrivingGates): Partial<Record<string, ToolImpl<D>>>;
|