@parcha/pi-browser 0.1.0-beta.30 → 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.
Files changed (48) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/NOTICE +4 -4
  3. package/README.md +41 -12
  4. package/dist/coding-agent.d.ts +1 -0
  5. package/dist/coding-agent.js +5 -4
  6. package/dist/core/contract.d.ts +9 -0
  7. package/dist/core/contract.js +15 -3
  8. package/dist/core/custody.d.ts +7 -2
  9. package/dist/core/custody.js +7 -3
  10. package/dist/core/downloads.d.ts +7 -0
  11. package/dist/core/downloads.js +13 -1
  12. package/dist/core/driving-guard.d.ts +20 -0
  13. package/dist/core/driving-guard.js +175 -23
  14. package/dist/core/driving.d.ts +56 -2
  15. package/dist/core/driving.js +189 -10
  16. package/dist/core/effects.d.ts +80 -6
  17. package/dist/core/effects.js +374 -41
  18. package/dist/core/failures.d.ts +15 -1
  19. package/dist/core/failures.js +7 -0
  20. package/dist/core/host.d.ts +11 -2
  21. package/dist/core/tools.d.ts +14 -0
  22. package/dist/core/tools.js +42 -8
  23. package/dist/driver/page-driver.js +77 -4
  24. package/dist/driver/sealed.d.ts +4 -12
  25. package/dist/driver/sealed.js +23 -37
  26. package/dist/driver/stagehand.d.ts +10 -15
  27. package/dist/driver/stagehand.js +19 -17
  28. package/dist/durable/result.d.ts +1 -2
  29. package/dist/durable/result.js +2 -2
  30. package/dist/durable/store.d.ts +4 -1
  31. package/dist/durable/store.js +16 -11
  32. package/dist/durable.d.ts +17 -1
  33. package/dist/durable.js +41 -14
  34. package/dist/live-view/index.d.ts +2 -1
  35. package/dist/live-view/index.js +1 -0
  36. package/dist/live-view/protocol.d.ts +38 -6
  37. package/dist/live-view/protocol.js +2 -0
  38. package/dist/live-view/server.d.ts +24 -1
  39. package/dist/live-view/server.js +131 -11
  40. package/dist/live-view/stream.js +16 -3
  41. package/dist/live-view/viewer.js +106 -13
  42. package/dist/providers/cdp.d.ts +0 -1
  43. package/dist/providers/cdp.js +33 -11
  44. package/dist/providers/worker-extension.d.ts +6 -0
  45. package/dist/providers/worker-extension.js +17 -4
  46. package/package.json +10 -10
  47. package/dist/driver/extension-worker.d.ts +0 -9
  48. package/dist/driver/extension-worker.js +0 -185
package/CHANGELOG.md CHANGED
@@ -2,6 +2,58 @@
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
+
50
+ ## 0.1.0-beta.31 (2026-11-06)
51
+
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:
53
+ - **web_fetch** has no cookies, sign-ins or session: it reads one page cold, so a page behind a sign-in, or one that depends on an earlier page, needs the browser tool, where this run has it. That holds for serve's web_fetch on every harness and for pi-browser's.
54
+ - **The browser's `run`** keeps this agent's saved sign-ins and cookies, for anything behind a sign-in or a page that depends on an earlier one. It says this only on a run that has a saved sign-in: in serve, a run handed its agent's sign-in; in pi-browser, a host that passes `signIns: true` or a session vault. Without one it says only that the browser keeps cookies across pages, which stays true for a local Chrome, which keeps no saved sign-in.
55
+ - **pi-browser** adds `browserToolsFor(signIns)` (the browser's contracts with `run`'s words for that plane), `BROWSER_KEEPS` (the two sentences), and the durable extension's `signIns` option.
56
+
5
57
  ## 0.1.0-beta.30 (2026-11-05)
6
58
 
7
59
  - Browser minutes count in a run's spend. Each charge of a `browser` session's time is booked as a tool cost, so it is a `Tool cost` line on the run's timeline, part of its `cost.usd`, and `/usage`'s new `browser_time` meter (dollars, and seconds for runs that have ended); capabilities list `browser_time` in `usage.meters`. Under `max_cost_usd`, the browser's time is held before it runs: a browser call that the cap cannot hold is not made, the model gets the cap's words, and the run's session is released, so no browser minute passes the cap.
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.1.0 (https://github.com/browserbase/stagehand), both under its MIT license,
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/cdp.ts, copied from packages/sdk-ts/src/browser/localBrowser.ts
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.1 to 1.3 (the range of its
14
- pi-durable and chord peers; the coding-agent entry also runs on pi 1.0.4). ESM only: the
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.3.0 @earendil-works/chord@1.3.0 @earendil-works/pi-ai@1.3.0 # a pi-durable host: its peers, pinned to 1.3.0 (unpinned, npm takes 1.4.0 and stops with ERESOLVE)
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. pi 1.4 is not supported yet; a later release widens the range.
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` `>=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.
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, its trace exporter pointed at a closed loopback port.
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's trace export is pointed at a closed loopback port, so nothing you browse goes to a third party.
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
@@ -396,6 +421,9 @@ await browser.reconcile(harness, () => true, context); // settles what a dead
396
421
  - `decisions`: `classifyPage` and `rankChunks`, answered with your judge. Absent, no page is classified and no find is ranked.
397
422
  - `redact.values`: exact strings to scrub besides the built-in shapes.
398
423
  - `section.addendum`: your text after the package's prompt section.
424
+ - `signIns`: `true` when the plane's sessions open on the agent's saved sign-ins (your kept profile or context). `run`'s
425
+ description then tells the model the browser keeps them, for a page behind a sign-in; without it, it says only that the
426
+ browser keeps cookies across pages. Absent, it is whether a `sessionVault` is given.
399
427
  - `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.
400
428
  - `files`: a `WorkspaceFiles` that resolves `browser_upload` paths. Given, `browser_upload` is listed without a `workspace`.
401
429
  - `handoff`: a `HandoffPort` that reaches a person (`request`, then `outcome` polled until done, cancelled or expired;
@@ -414,7 +442,8 @@ region, a raw context id, the session timeout, the idle release and the batch ti
414
442
  package's defaults to spread and override) in the conversation's creating commit,
415
443
  selects the extensions for it, and calls `handle.release(conversation, "close", ctx)` when the conversation ends. Releases run
416
444
  as background tasks, which `waitForIdle` skips and closing the harness aborts: before it closes, a host calls
417
- `handle.drain(harness, ctx, signal?)`, which resolves once none is live. A release the store cannot record (a storage error)
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)
418
447
  is still made at the provider, and the record is left for the next run's reconcile; once the store has failed,
419
448
  `handle.close()` releases every session the process still holds, and over a healthy store it releases nothing. At run open,
420
449
  after the extensions are installed and
@@ -123,6 +123,7 @@ export declare class LocalCustody implements CustodyPort<PageDriver> {
123
123
  completionCondition: string;
124
124
  }, signal?: AbortSignal): Promise<{
125
125
  outcome: HandoffOutcome;
126
+ reason?: string;
126
127
  } | {
127
128
  refused: string;
128
129
  }>;
@@ -4,7 +4,7 @@ import { mkdtemp, rm } from "node:fs/promises";
4
4
  import os from "node:os";
5
5
  import path from "node:path";
6
6
  import { setTimeout as sleep } from "node:timers/promises";
7
- import { BROWSER_TOOLS, WEB_TOOLS, browserSection, listedFor } from "./core/contract.js";
7
+ import { BROWSER_TOOLS, WEB_TOOLS, browserSection, browserToolsFor, listedFor } from "./core/contract.js";
8
8
  import { BrowserFailureError, closeDriver, custodyTools, FIXED_SESSION_RELAUNCH, fenced, HANDED_BACK, loadedNoPage, moveRecord, newSessionRecord, notices, NOTHING_TO_HOLD, navigationRefusal, profileRefusal, relaunchRefusal, sessionSpec, waitingForHuman, backoffMs, NO_HANDOFF, } from "./core/custody.js";
9
9
  import { browserFailure, classifyBrowserError } from "./core/failures.js";
10
10
  import { workspaceFiles } from "./core/files.js";
@@ -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 (Stagehand after a reconnect) never holds up the provider's release.
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
  }
@@ -629,7 +629,8 @@ export function createBrowserExtension(options = {}) {
629
629
  },
630
630
  });
631
631
  }
632
- for (const contract of BROWSER_TOOLS)
632
+ // A session vault keeps sign-ins, and run says so; without one it claims cookies across pages only.
633
+ for (const contract of browserToolsFor(!!options.sessionVault))
633
634
  if (listedFor(contract, { downloads: fileTools, upload: fileTools, handoff: !!options.handoff }))
634
635
  registerTool(pi, contract, runtimeOf);
635
636
  registerTool(pi, WEB_TOOLS.find((tool) => tool.name === "web_fetch"), runtimeOf);
@@ -16,6 +16,12 @@ export type ToolContract = {
16
16
  readonly evidence: "none" | "receipt" | "image" | "files" | "urls";
17
17
  readonly listedWhen: "always" | "downloads" | "upload" | "fetch" | "search" | "sites" | "handoff";
18
18
  };
19
+ /** What the browser keeps, as `run`'s description tells the model when it picks between the browser and web_fetch:
20
+ * cookies across pages always, its agent's saved sign-ins only on a plane that has them (a local Chrome keeps none). */
21
+ export declare const BROWSER_KEEPS: Readonly<{
22
+ cookies: "It keeps cookies across pages: use it for a page that depends on an earlier one, or one that sets cookies.";
23
+ signIns: "It keeps this agent's saved sign-ins and cookies: use it for anything behind a sign-in, or a page that depends on an earlier one.";
24
+ }>;
19
25
  /** A hit's snippet is clipped to this many characters, whitespace collapsed, so ten hits stay a few kilobytes. */
20
26
  export declare const WEB_SEARCH_SNIPPET_MAX = 500;
21
27
  /** Whether a host lists a browser tool: one that is always offered, or one whose capability the host has (a workspace to copy downloads
@@ -27,6 +33,9 @@ export declare const listedFor: (contract: ToolContract, offers: {
27
33
  }) => boolean;
28
34
  export declare const BROWSER_TOOLS: readonly ToolContract[];
29
35
  export declare const WEB_TOOLS: readonly ToolContract[];
36
+ /** The browser's contracts as a plane's model reads them: `run` says the plane keeps its agent's saved sign-ins where it
37
+ * has them (a host's kept profile, or a session vault), and only cookies where it has none. */
38
+ export declare const browserToolsFor: (signIns: boolean) => readonly ToolContract[];
30
39
  export declare const BROWSER_TOOL_NAMES: readonly string[];
31
40
  export declare const WEB_TOOL_NAMES: readonly string[];
32
41
  /** Depends only on configuration, never live state, so every request renders the same text and keeps the prompt cache. */
@@ -16,10 +16,18 @@ const snapshot = {
16
16
  parameters: object({ includeIframes: { type: "boolean", default: true } }),
17
17
  effect: "read", replay: "safe", executionMode: "sequential", evidence: "none", listedWhen: "always",
18
18
  };
19
+ /** What the browser keeps, as `run`'s description tells the model when it picks between the browser and web_fetch:
20
+ * cookies across pages always, its agent's saved sign-ins only on a plane that has them (a local Chrome keeps none). */
21
+ export const BROWSER_KEEPS = Object.freeze({
22
+ cookies: "It keeps cookies across pages: use it for a page that depends on an earlier one, or one that sets cookies.",
23
+ signIns: "It keeps this agent's saved sign-ins and cookies: use it for anything behind a sign-in, or a page that depends on an earlier one.",
24
+ });
25
+ const runDescription = (signIns) => `Browse and automate websites in the persistent Stagehand browser. ${signIns ? BROWSER_KEEPS.signIns : BROWSER_KEEPS.cookies} ` +
26
+ 'Navigate with JavaScript such as await page.goto("https://example.com"); there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Code is the body of an async function with page, context and browser in scope: `return` the value you want back. Provide exactly one of code or actions. Each action must use "op" (never "kind") and "id" (never "ref"). Copy the bracketed snapshot ID as a string. Examples: {"actions":[{"op":"click","id":"1-42"}]}, {"actions":[{"op":"fill","id":"2-14","value":"Miami"}]}, {"actions":[{"op":"select","id":"3-9","values":"Lowest price"}]}.';
19
27
  const run = {
20
28
  name: "run",
21
29
  label: "Browser: run",
22
- description: 'Browse and automate websites in the persistent Stagehand browser. Navigate with JavaScript such as await page.goto("https://example.com"); there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Code is the body of an async function with page, context and browser in scope: `return` the value you want back. Provide exactly one of code or actions. Each action must use "op" (never "kind") and "id" (never "ref"). Copy the bracketed snapshot ID as a string. Examples: {"actions":[{"op":"click","id":"1-42"}]}, {"actions":[{"op":"fill","id":"2-14","value":"Miami"}]}, {"actions":[{"op":"select","id":"3-9","values":"Lowest price"}]}.',
30
+ description: runDescription(false),
23
31
  // No top-level oneOf for "exactly one of code or actions": AI-SDK-based clients reject it, so the tool enforces it.
24
32
  parameters: object({
25
33
  code: { type: "string", minLength: 1 },
@@ -114,7 +122,7 @@ const browserDownloads = {
114
122
  name: "browser_downloads",
115
123
  label: "Browser: downloads",
116
124
  description: "Copy the files this browser session downloaded into the workspace under downloads/, with downloads/manifest.json listing each file's SHA-256. " +
117
- "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.",
118
126
  parameters: object({}),
119
127
  effect: "read", replay: "safe", executionMode: "sequential", evidence: "files", listedWhen: "downloads",
120
128
  };
@@ -133,7 +141,8 @@ const webFetch = {
133
141
  name: "web_fetch",
134
142
  label: "Web fetch",
135
143
  description: "Fetch one URL as clean markdown without a browser session: fast and cheap, and it handles most static and many dynamic pages. " +
136
- "Use it for reading articles, filings, registries, PDFs-as-pages. If it returns blocked or empty content, drive the page with run/snapshot instead. " +
144
+ "It has no cookies, sign-ins or session: it reads one page cold. " +
145
+ "Use it for reading articles, filings, registries, PDFs-as-pages. If it returns blocked or empty content, or the page is behind a sign-in or depends on an earlier page, drive it with run/snapshot instead. " +
137
146
  "A page it returns is filed as evidence: that read, not a search result, is what a claim cites. " +
138
147
  "The result is persisted as evidence with its URL: a query value that is in the URL you asked for stays in it, any other value of the final URL is replaced by a redaction marker (the word redacted in square brackets).",
139
148
  parameters: object({
@@ -159,6 +168,9 @@ const webSearch = {
159
168
  export const listedFor = (contract, offers) => contract.listedWhen === "always" || (contract.listedWhen === "downloads" && offers.downloads) || (contract.listedWhen === "upload" && offers.upload) || (contract.listedWhen === "handoff" && offers.handoff);
160
169
  export const BROWSER_TOOLS = Object.freeze([snapshot, run, screenshot, browserRead, browserRelease, browserRelaunch, browserRequestHandoff, browserDownloads, browserUpload]);
161
170
  export const WEB_TOOLS = Object.freeze([webFetch, webSearch]);
171
+ /** The browser's contracts as a plane's model reads them: `run` says the plane keeps its agent's saved sign-ins where it
172
+ * has them (a host's kept profile, or a session vault), and only cookies where it has none. */
173
+ export const browserToolsFor = (signIns) => signIns ? Object.freeze(BROWSER_TOOLS.map((contract) => (contract === run ? { ...contract, description: runDescription(true) } : contract))) : BROWSER_TOOLS;
162
174
  export const BROWSER_TOOL_NAMES = Object.freeze(BROWSER_TOOLS.map((tool) => tool.name));
163
175
  export const WEB_TOOL_NAMES = Object.freeze(WEB_TOOLS.map((tool) => tool.name));
164
176
  /** Depends only on configuration, never live state, so every request renders the same text and keeps the prompt cache. */
@@ -5,8 +5,12 @@ import { type LeaseState } from "./lease.js";
5
5
  export type BrowserDriver = {
6
6
  close(): Promise<void>;
7
7
  };
8
- /** A Stagehand close after a dropped and reconnected connection can hang forever; the provider ends the session anyway. */
9
- export declare const DRIVER_CLOSE_MS = 5000;
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
  }>;
@@ -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 Stagehand close after a dropped and reconnected connection can hang forever; the provider ends the session anyway. */
5
- export const DRIVER_CLOSE_MS = 5_000;
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);
@@ -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 = {
@@ -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
- result.skipped.push({ name: file.name, reason: error instanceof Error ? (options.redact ?? ((text) => text))(error.message).slice(0, 200) : "the read failed" });
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>>>;