browser-pilot-cli 0.4.0 → 0.5.1

package/docs/integration/stdio-bridge.md

@@ -1,694 +0,0 @@
-# Stdio Bridge Integration Contract
-
-Status: browser `tools/call`, scoped Observations, target inventory, Artifacts,
-command recovery, event delivery, browser reconnect, and scoped downloads
-implemented.
-
-This document describes the Agent-neutral process boundary. Tenon, OpenClaw,
-and other Agent hosts use the same executable and protocol. No consumer imports
-Browser Pilot source files, links a Native SDK, installs an extension, or needs
-an MCP transport.
-
-## Process Launch
-
-Resolve an exact Browser Pilot executable version from one of these locations:
-
-1. The product's bundled dependency.
-2. A project-local npm dependency.
-3. A compatible global installation selected explicitly by the host.
-
-For release bundles, verify the versioned release index first. It binds the npm
-package, Agent plugin/skill compatible CLI range and tested version, protocol
-range, supported native assets, and adjacent SHA-256 files. Native releases support `darwin-arm64`,
-`linux-x64`, and `win32-x64`; Intel Mac is not supported.
-
-Launch it directly, without a shell:
-
-```text
-browser-pilot bridge --stdio
-```
-
-The three supported layouts are behaviorally equivalent:
-
-- global npm: the host explicitly resolves the installed `browser-pilot` bin;
-- local npm/npx: the host pins `browser-pilot-cli` and resolves its local bin or
-  absolute `dist/cli.js` path;
-- native bundle: the host pins and launches the release archive's absolute
-  `browser-pilot` executable path.
-
-The npm layout requires Node 18 or newer and starts the adjacent packaged
-`daemon.js` and `managed-target-janitor.js` files as private processes. A native
-release is a Node SEA executable with its runtime and dependencies embedded. It
-respawns that same executable for private Broker and janitor roles; reserved
-`--browser-pilot-internal=*` arguments are not a Host API. It never downloads a
-runtime or falls back to a system Node installation.
-
-Native archives contain `manifest.json`, `SHA256SUMS`, dependency/runtime
-licenses, and an adjacent archive checksum. Verify the archive checksum before
-unpacking and the manifest-listed file hashes before launch. The manifest's
-`signature.kind` is evidence, not an aspirational channel label: `developer_id`
-or `adhoc` on macOS, `authenticode` or `unsigned` on Windows, and `unsigned` on
-Linux. Hosts that require a trusted publisher must reject ad-hoc or unsigned
-artifacts themselves.
-
-The host may add `--browser <id|product|channel>` to make its initial browser
-preference explicit. Without it, Browser Pilot deterministically selects the
-first candidate with a recorded debugging endpoint, then stable platform order.
-The running Broker retains that
-choice in memory; it does not write target or profile selection state to disk.
-
-Create pipes for stdin, stdout, and stderr. Stdout is protocol-only. Treat each
-stderr line as a diagnostic and never parse it as protocol data.
-
-The executable owns Broker discovery and startup. Hosts must not read PID
-files, locator metadata, Unix socket paths, or Windows named-pipe names. Two
-products that launch concurrently serialize through the per-user startup lock,
-then both reuse the winning compatible Broker. A dead locator is recovered on
-the next launch. Broker startup and browser discovery are passive. Only an
-explicit `browser.connect` tool call requests Chrome authorization, and
-concurrent calls for the same browser share one in-flight WebSocket attempt. A
-ready live process with an
-unresponsive endpoint is not killed or replaced; launch returns
-`browser_disconnected` with `restart_unresponsive_broker` remediation.
-
-The default is one shared Broker per OS user. Protocol-compatible clients reuse
-it even when different Agent products or product versions launched their
-bridges. If a product must run an incompatible Browser Pilot version, set an
-absolute, product-owned `BROWSER_PILOT_HOME` before process launch. This creates
-a deliberately isolated locator, endpoint, Artifact store, and version history
-on macOS, Linux, and Windows. Do not silently choose an isolated home after
-`protocol_incompatible`: shared-browser coordination and cleanup semantics must
-remain an explicit host decision.
-
-## Framing
-
-The transport is JSON-RPC 2.0 over newline-delimited UTF-8 JSON:
-
-- one complete JSON object per line;
-- ordinary requests are dispatched in input order;
-- request IDs are non-empty strings or safe integers;
-- notifications have no response;
-- the default input limit is 1 MiB per line and the default result limit is
-  4 MiB; protocol 1.1 clients may negotiate lower per-Connection limits;
-- invalid JSON, invalid UTF-8, invalid envelopes, and oversized input terminate
-  that bridge process after an error response with `id: null` when possible;
-- output observes stream backpressure;
-- at most 256 ordinary calls and 16 out-of-band control calls are pending per
-  bridge process; saturation returns retryable `result_too_large` without
-  dispatching the rejected call;
-- EOF releases every Lease owned by that bridge Connection;
-- `shutdown` exits only the bridge process, not the shared per-user daemon.
-
-Hosts must not send concurrent writes that interleave bytes. They may pipeline
-complete lines and must correlate responses by JSON-RPC ID. `commands/get`,
-`commands/cancel`, and dialog list/respond calls may overtake a pending
-`tools/call`, so those responses can arrive earlier. Dialog control needs this
-exception because a browser dialog can pause the command that caused it.
-
-## Initialization
-
-`initialize` must be the first successful request on a bridge Connection:
-
-```json
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"client":{"id":"com.example.agent","name":"Example Agent","version":"2.0.0","instanceId":"install:01J..."},"protocol":{"min":{"major":1,"minor":1},"max":{"major":1,"minor":3}},"requestedCapabilities":["browser.control","workspace.manage","observation.read","action.input","artifact.read","event.read"],"launchMode":"embedded","limits":{"maxMessageBytes":1048576,"maxResultBytes":4194304}}}
-```
-
-The response returns the selected protocol, supported and granted
-capabilities, executable and service versions, a process-stable Broker
-identity, a Connection ID, browser candidates, and negotiated limits. Each
-candidate has a stable `id`, product/channel and `userDataRoot`, aggregate
-`state`, separate `processState`, `remoteDebuggingState`, and
-`authorizationState`, plus structured `remediation` when action is needed.
-Initialization succeeds when no candidate is ready, so a host can present setup
-state and poll `browser.discover`. Discovery is passive and reports
-authorization as `unknown` until an explicit connection succeeds or fails.
-Workspace and Lease creation also remain passive; call `browser.connect` once
-before target tools. Branch on structured `error.data.code`; never branch on
-English error messages.
-
-Protocol 1.0 uses the service limits returned by `initialize`. Protocol 1.1 may
-send `limits.maxMessageBytes` and `limits.maxResultBytes`; each must be from
-64 KiB through 1 GiB. The selected value is the smaller client/service maximum
-and applies only to that bridge Connection. `maxArtifactBytes` and
-`eventJournalSize` remain service resource limits, not client preferences.
-
-Protocol 1.2 adds connection-scoped Chrome Profile routing. It exposes
-`browser.profiles.list`, `browser.profiles.select`, and `profileContextId` on
-tab inventory and new-target operations. Protocol 1.0/1.1 clients retain their
-existing tools; the Broker hides 1.2-only operations and rejects a manually
-constructed Profile call with `protocol_incompatible`.
-
-Protocol 1.3 adds the explicit `browser.profiles.identify` mutation and
-structured Profile identity fields. Browser discovery returns `userDataRoot`
-instead of the legacy candidate field `profile`, and tab inventory returns
-`selected` instead of `active`. `selected` means the target selected by this
-Lease; it does not describe Chrome foreground focus. Protocol 1.2 clients keep
-the old field vocabulary and do not see the identity tool.
-
-The initialize request and response use the service's fixed bootstrap limits.
-The bridge switches limits only after the successful response has been written,
-and waits for that switch before parsing a pipelined next line. Oversized
-responses become `result_too_large`; oversized best-effort notifications are
-dropped and remain recoverable through `events/poll`.
-
-An already-running incompatible daemon is never replaced. Initialization
-returns `protocol_incompatible` with remediation to use a compatible executable
-or a deliberate `BROWSER_PILOT_HOME` isolation boundary. Executable versions
-and protocol versions are independent; successful protocol negotiation is what
-allows embedded clients from different products or releases to share a Broker.
-
-## Lifecycle Methods
-
-The implemented lifecycle surface is:
-
-```text
-initialize
-tools/list
-tools/call
-commands/get
-commands/cancel
-workspaces/create
-workspaces/get
-workspaces/release
-leases/create
-leases/heartbeat
-leases/release
-events/poll
-artifacts/get
-artifacts/export
-artifacts/import
-artifacts/retain
-artifacts/release
-shutdown
-```
-
-`workspaces/create` accepts an optional `browserId`. Protocol 1.1 clients may
-also provide `clientKey` to make active Workspace creation idempotent within
-their Principal; reusing a key for another browser fails. Without a browser ID,
-the Broker prefers its first ready connection and otherwise uses its selected
-stable-order browser binding. It returns a Workspace, its default logical
-ManagedTabSet, the complete `managedTabSets` array, and an `eventCursor`.
-`workspaces/get` also returns the Workspace's transient
-`selectedProfileContextId` when one is selected and the current cursor as a
-recovery baseline. Creating a Workspace does not itself create a browser
-connection or window. Call the Workspace-scoped `browser.connect` tool to
-request Chrome authorization; the first managed navigation then creates the
-dedicated browser window in its resolved Profile context.
-
-`leases/create` accepts a `workspaceId` and optional `ttlMs`. Protocol 1.1
-clients may also provide a `clientKey`; repeating that key on the same live
-Connection and Workspace returns the same Lease and renews its TTL. The default
-Lease is 30 seconds, with a supported range of 1 second through 5 minutes. Heartbeat
-well before `expiresAt`. A Lease belongs to its live Connection and cannot be
-continued by a replacement bridge process. A replacement Connection from the
-same ClientPrincipal may obtain a new Lease for a still-active Workspace.
-
-Workspace identity belongs to `client.id + client.instanceId` for the lifetime
-of the daemon. It is transient and is never restored from disk after Broker
-restart. A Workspace released twice returns the same successful release result
-while its bounded tombstone remains available.
-
-## Tool Calls
-
-`tools/list` returns only operations implemented by the running Broker and
-allowed by negotiated capabilities. Call those tools with one uniform envelope:
-
-```json
-{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"browser.observe","arguments":{"limit":50},"workspaceId":"workspace:...","leaseId":"lease:...","targetId":"target:...","commandId":"command:...","idempotencyKey":"observe:01J...","deadlineMs":30000}}
-```
-
-Connection tools omit Workspace fields. Workspace tools require
-`workspaceId + leaseId`; target tools additionally require the opaque
-`targetId` returned by `browser.tabs.list` or `browser.open`. Raw CDP target and
-session IDs are never public inputs. The Broker validates the negotiated
-capability, Lease ownership, tool schema, and target control before dispatch.
-
-Each tool's `sensitivity.input` and `sensitivity.output` arrays list the classes
-that may occur anywhere in that direction. Specific content-bearing schema
-nodes carry `x-browser-pilot-sensitivity`, for example:
-
-```json
-{"type":"string","maxLength":1000000,"x-browser-pilot-sensitivity":["browser_data"]}
-```
-
-Use the field annotation when mapping `browser.read.result.text`, Observation
-element values, auth fields, cookie values, network headers/bodies, upload
-Artifact references, prompt text, or eval values into the Agent runtime. Keep
-the annotation attached to derived model content; do not infer sensitivity from
-field names or English tool descriptions. The annotation does not wrap or alter
-the value. Artifact descriptors and BrowserEvents provide their actual runtime
-`sensitivity` and should be propagated directly.
-
-Every `tools/call` response is a Command outcome:
-
-```json
-{"command":{"id":"command:...","status":"completed","method":"browser.observe","browserConnectionGeneration":3,"idempotencyKey":"observe:01J...","acceptedAt":1,"deadlineAt":30001,"dispatchedAt":2,"completedAt":20,"mutating":false},"result":{"workspaceId":"workspace:...","leaseId":"lease:...","targetId":"target:...","url":"https://example.com","observationId":"observation:...","title":"Example","elements":[],"truncated":false,"truncationReasons":[]}}
-```
-
-The manifest's output schema describes the inner `result`. Clients should pass
-a unique `commandId` when they may need cancellation; otherwise the Broker
-generates one. `idempotencyKey` is optional, but retries must reuse it or reuse
-the same caller-supplied `commandId`. Reusing a key for different arguments is
-rejected. A duplicate completed call returns the recorded result; a duplicate
-that is still accepted or dispatched returns its current Command without
-dispatching again.
-
-`commands/get` and `commands/cancel` accept `commandId` plus `workspaceId` for
-Workspace commands. They are authorized by Principal ownership rather than the
-original Lease, so a replacement bridge from the same product instance can
-inspect a known outcome. Cancellation while accepted prevents browser dispatch.
-Cancellation after dispatch is best-effort and sets `cancellationRequested`;
-it never claims rollback. A mutating command whose deadline elapses after
-browser dispatch becomes `unknown_outcome` and is never automatically replayed.
-Known tool failures are stored as a completed Command with a nested JSON-RPC
-`error`; the original call also returns that error normally.
-
-### Chrome Profile routing
-
-One connected Chrome endpoint may expose ordinary tabs from several live
-Profiles. Browser Pilot authorizes the endpoint once; it does not reconnect or
-show another Chrome Allow dialog per Profile. `browser.tabs.list` returns every
-eligible managed and user-opened tab across those contexts, each with an opaque
-`profileContextId`. Existing tabs can be selected and controlled immediately;
-Profile selection is routing for new managed targets, not a permission grant.
-Browser-internal and extension-owned pages are excluded from ordinary tab and
-Profile representative inventory.
-
-Protocol 1.2+ hosts should use this flow when creating independent work:
-
-1. Call `browser.profiles.list`. It is passive and returns neutral labels,
-   bounded representative tabs, counts, and the Workspace selection.
-2. On protocol 1.3, if account-aware identity is needed, call
-   `browser.profiles.identify`. It briefly creates visible `chrome://version`
-   targets, verifies each reported path as an immediate child of the connected
-   `userDataRoot`, reads bounded Chrome Local State metadata, closes every
-   temporary target, and caches the result for one connection generation.
-   `refresh: true` explicitly re-probes.
-3. If there is one Profile, `browser.open` can infer it. If there are several
-   and no current target or Workspace selection, ask the user which Profile to
-   use.
-4. Call `browser.profiles.select` with the returned opaque ID, or pass that ID
-   directly as `browser.open.arguments.profileContextId`.
-5. Treat IDs and verified identity as scoped to the current browser connection
-   generation. After reconnect, relist Profiles, tabs, frames, and Observations.
-
-Profile results use `identityStatus: unidentified | verified | unavailable`.
-Only verified results may include `profileName`, `accountName`, `accountEmail`,
-and `profileDirectory`; unavailable results include a stable
-`identityErrorCode` rather than a guessed account. Current codes are
-`profile_path_unavailable`, `profile_path_unverified`,
-`local_state_unavailable`, and `profile_metadata_missing`. Never expose or persist raw
-CDP context IDs. New-target routing uses an explicit call argument, the Lease's logical selected
-target, the Workspace selection, or the only available context, in that order.
-`browser.profiles.select` clears only the logical selected-target anchor so its
-selection applies to the next new managed target; it does not release control,
-activate a user tab, or change Chrome focus.
-
-With multiple unanchored contexts, `browser.open` fails before browser dispatch
-with `profile_selection_required`. Relist on `profile_context_stale`; on
-`profile_context_unavailable`, follow its setup remediation. An
-`unknown_outcome` during Profile-window creation means Chrome may have created
-a target that Browser Pilot could not prove absent; list tabs and Profiles and
-inspect current state before deciding whether to retry.
-
-`browser.click` returns a new Observation plus bounded evidence. For example,
-a checkbox may return:
-
-```json
-{"action":"click","status":"verified","kind":"checkbox","effects":["checked_changed","focus_changed"],"checked":true,"focused":true}
-```
-
-Effects can also include `selected_changed`, `pressed_changed`,
-`expanded_changed`, `navigation`, `document_changed`, `dialog_opened`, and
-`popup_opened`. A semantic control that does not reach its expected state uses
-`mismatch`; coordinate clicks and ref clicks with no conclusive observable
-effect use `unavailable`. Treat evidence as browser-level execution evidence,
-then inspect the returned Observation to decide whether the task itself
-succeeded.
-
-Every Observation produced by the built-in Browser tools also includes a
-bounded `hints` array. Each item is discriminated by `code` and includes
-`source`, `confidence`, and a stable `recommendedAction`:
-
-```json
-{"hints":[{"code":"modal_overlay","source":"observation","confidence":"strong","recommendedAction":"resolve_overlay_first","blocking":true,"refs":[2,5]}]}
-```
-
-Current codes are `autocomplete`, `modal_overlay`, `filter_controls`,
-`authentication_surface`, `access_blocked`, `download`, and
-`repeated_action`. Observation hints may contain only refs from the returned
-Observation. Authentication state is `present` on the first observed auth
-surface, `entered` when a session moves onto one, and `left` when it moves off
-one. A session or selected-frame change resets that transition baseline.
-
-Hints are advisory browser evidence. Use the recommended action as the next
-inspection strategy, not as permission, proof of task success, or a reason to
-skip normal error handling. Unknown hint codes and unknown response fields must
-be ignored. The field is additive for protocol 1.0 and 1.1 and introduces no
-new capability; its data is covered by the tool or event's existing
-sensitivity and granted capability.
-
-### Observation representations
-
-The browser tools expose complementary bounded representations rather than one
-unbounded page dump:
-
-- `browser.observe` creates semantic elements and scoped refs for actions.
-- `browser.read` returns broad readable text from the page or one CSS region.
-- `browser.search` returns visible text matches, nearby context, and viewport
-  geometry, including open Shadow DOM, with at most 200 results.
-- `browser.elements.find` returns bounded safe metadata for a CSS query,
-  optionally across open Shadow DOM. It never exposes DOM/CDP handles and its
-  results are not action refs.
-- `browser.capture` may draw Observation ref boxes for spatial reasoning without
-  injecting an overlay into the page.
-
-Observations may include an additive `page` object containing viewport and
-document dimensions, scroll coordinates, pixels remaining in each direction,
-and horizontal/vertical scroll percentages. Hosts must tolerate its absence
-when talking to an older compatible Broker.
-
-`browser.scroll` moves the page, an Observation ref, a CSS-selected container,
-or a visible text match, then returns a fresh Observation and typed evidence.
-`browser.dropdown.options` enumerates native or currently exposed ARIA options.
-`browser.dropdown.select` verifies native value changes or uses fresh
-Observation refs for custom controls. These tools reuse `observation.read` and
-`action.input`; they are additive manifest entries, not a protocol-version
-fork. Discover them through `tools/list`.
-
-`browser.type` and `browser.keyboard` also return bounded evidence after the
-page has had time to apply a controlled-field update:
-
-```json
-{"action":"type","status":"verified","kind":"input","sensitive":false,"beforeLength":3,"expectedLength":7,"afterLength":7}
-```
-
-Use `verification: "require_exact"` when a mismatch must fail the command.
-Native text controls and contenteditable receive Chrome editing events;
-date/time/color/range controls use their native value setter and emit
-`beforeinput` plus `input`, but not an early `change`. Framework rollback,
-browser value sanitization, canceled `beforeinput`, and editor interception are
-reported from the effective value after the action. Password evidence never
-contains the value itself.
-
-`browser.type` and `browser.keyboard` are guarded composite actions. Browser
-Pilot pins the target/session/frame/loader/Document identity and, once input
-focus is established, the deep active element. It checks them between
-select-all, deletion, individual keyboard characters, and submit. If a change
-is detected before the first browser mutation, the call fails with retryable
-`action_not_verified`. If one or more steps already ran, it fails with
-`unknown_outcome`, for example:
-
-```json
-{"code":"unknown_outcome","retryable":true,"context":{"action":"keyboard","step":"type_character:4","reason":"focus_changed","dispatchedSteps":4,"remainingStepsStopped":true}}
-```
-
-Reasons are `target_changed`, `session_changed`, `frame_changed`,
-`loader_changed`, `document_changed`, or `focus_changed`. On either failure,
-list or switch to the intended target if necessary, create a fresh Observation,
-and decide from current page state whether to continue. Never replay the whole
-mutation automatically after `unknown_outcome`.
-
-`browser.press` returns `action: "press"` with bounded effects such as
-`value_changed`, `checked_changed`, `selected_changed`, `focus_changed`,
-`navigation`, `document_changed`, `dialog_opened`, or `popup_opened`. It returns
-`unavailable` with `no_observable_effect` when the key dispatch completed but no
-supported effect was visible.
-
-`browser.upload` reads the file input after assignment. It returns `verified`
-only when one file with the expected browser filename remains selected,
-`mismatch` when the page cleared or replaced the selection, and `unavailable`
-when the target could no longer be read. Evidence contains counts and a filename
-match boolean, never the Broker storage path.
-
-Inventory includes every eligible ordinary user tab plus the Workspace's
-managed tabs. A physical tab can be controlled by only one Lease at a time.
-Commands for the same physical tab share one actor even though each Workspace
-has a different opaque target ID. A controlling Lease can call
-`browser.tabs.release` for one target without closing it. After that command
-completes and emits `target_control.released`, another Lease may use its own
-opaque ID to acquire the tab. This two-step handoff never accepts a destination
-Lease ID and never silently steals control. Releasing a Workspace closes managed
-tabs but leaves user tabs open.
-
-## Events
-
-Every event is first committed to a bounded per-Workspace journal and then
-offered as this best-effort notification:
-
-```json
-{"jsonrpc":"2.0","method":"events/event","params":{"event":{"id":"event:...","sequence":7,"timestamp":1,"workspaceId":"workspace:...","browserConnectionGeneration":3,"leaseId":"lease:...","targetId":"target:...","type":"dialog","payloadVersion":1,"sensitivity":"browser_data","payload":{"dialogId":"dialog:...","state":"opened","type":"confirm","message":"Continue?","url":"https://example.com"}}}}
-```
-
-Notifications can interleave with responses and can be dropped under transport
-backpressure or a disconnected bridge. Treat them as a low-latency signal, not
-as the recovery record. Track the last fully processed cursor and poll:
-
-```json
-{"jsonrpc":"2.0","id":20,"method":"events/poll","params":{"workspaceId":"workspace:...","cursor":"cursor:6","limit":100}}
-```
-
-The result contains ordered `events`, `nextCursor`, and `hasMore`. Continue until
-`hasMore` is false. If the cursor predates the retained journal, the Broker
-returns `cursor_expired` with `earliestCursor` and `latestCursor`; rebuild tab
-and observation state, then call `workspaces/get` to establish a new baseline.
-Never infer delivery from notification arrival alone, and never advance the
-stored cursor past an event the host has not processed.
-
-Current producers cover command status, Lease expiry, navigation, document
-change, target attach/detach, target control, managed popups, dialogs, downloads,
-browser connection loss/restoration, network request/response metadata, and
-observation invalidation. They also include `watchdog.navigation_stalled`,
-`watchdog.frame_detached`, `watchdog.dialog_unhandled`, and
-`watchdog.no_progress`. Network and watchdog events never contain credentials,
-typed values, refs, headers, request/response bodies, or raw CDP IDs; retrieve
-sensitive detail explicitly through the scoped tools.
-
-`network.response` adds an `access_blocked` hint only for a main-document 403 or
-429, not for failed images, scripts, XHR, or fetches. The threshold
-`watchdog.no_progress` event and the action result that reaches the threshold
-both contain the same `repeated_action` hint. The reason is either repeated
-observable failure or `stagnant_page`, where the same action signature was
-repeated while the bounded page fingerprint stayed unchanged. Fingerprints and
-action parameters never leave the Broker. Change representation and strategy
-instead of automatically repeating the same action or navigation.
-
-`connection.lost` keeps the last connection generation and causes later browser
-tools to fail with retryable `browser_disconnected`. The daemon passively
-refreshes the selected browser endpoint metadata and does not select a Profile
-context or open a WebSocket. The host calls `browser.connect` when it is
-ready to request reconnection. `connection.restored` then carries a strictly
-newer generation. Existing Workspaces
-and active Leases remain valid, but old target IDs, frame IDs, CDP sessions,
-Observations, and refs do not. Poll through the restoration event, call
-`browser.tabs.list`, and rebuild target state. Never retry a mutating command whose
-recorded status is `unknown_outcome`.
-
-Every event has a top-level `browserConnectionGeneration`. A delayed ordinary
-event from an older connection is discarded before journaling. Historical
-`command.status` events and reconnect cleanup events remain in the journal with
-their original generation, so consumers can finish old Command state machines
-without treating cleanup as current browser state. Commands accepted against an
-old generation are fenced before dispatch; commands already dispatched when the
-connection changes follow the `unknown_outcome` rule above.
-
-JavaScript dialogs remain pending. Use `browser.dialogs.list`, then call
-`browser.dialogs.respond` with the returned `dialogId`, target, and explicit
-`accept` or `dismiss` action. Browser Pilot never auto-accepts a dialog.
-
-Watchdog events are advisory browser-state signals, not autonomous recovery:
-
-- `watchdog.navigation_stalled` means `Page.navigate` was dispatched but the
-  page did not become interactive within 30 seconds. The command is
-  `unknown_outcome`; observe the target before deciding whether to navigate
-  again.
-- `watchdog.frame_detached` carries the opaque selected `frameId`. Browser Pilot
-  clears that selection and invalidates the Observation; list frames and create
-  a fresh Observation before continuing.
-- `watchdog.dialog_unhandled` is emitted once when a dialog remains pending for
-  15 seconds. It does not accept or dismiss the dialog.
-- `watchdog.no_progress` is emitted once after three consecutive completed
-  actions on the same Lease and target either have browser-observable mismatch
-  or repeat the same action while the bounded page state remains stagnant.
-  Observable success resets the mismatch detector; a changed action or page
-  state resets the repetition detector. Navigation, frame/session changes, and
-  cleanup reset both. Coordinate/canvas actions whose effects cannot be observed
-  do not count as mismatch-only failures.
-
-Browser Pilot never automatically retries, repeats, stops, accepts, or dismisses
-an action because of a watchdog event. The host or Agent must inspect current
-state and decide. Timers and streaks are in-memory transient state and are
-removed on dialog close, session loss, Lease release, Workspace release, or
-browser disconnect as applicable.
-
-## Artifacts
-
-`browser.capture` and `browser.pdf` return Artifact descriptors, never base64 or
-an internal path. Use `artifacts/get` with the owning active Workspace and Lease
-to obtain a protected local path, or `artifacts/export` with an absolute path to
-copy the file to client-owned storage. Export does not overwrite by default.
-
-Artifacts expire after 15 minutes by default. `artifacts/retain` extends that
-to the retained TTL; `artifacts/release` removes the bytes immediately.
-Workspace release and Broker shutdown also remove owned temporary bytes.
-Directories use mode `0700` and files use `0600` where POSIX permissions apply.
-
-Large screenshots default to a model-sized preview. Pass
-`includeOriginal: true` to receive both the original descriptor and a preview
-descriptor whose `previewOf` points to the original. The adapter reads the
-selected file and converts it to its Agent runtime's native image/file content.
-
-For spatial reasoning, a viewport-only `browser.capture` call may provide:
-
-```json
-{"annotations":{"observationId":"observation:...","refs":[1,3,8]}}
-```
-
-Omitting `refs` requests up to the first 200 refs in that Observation. The
-Broker revalidates each ref, clips live geometry to the viewport, draws on an
-unattached canvas in a Chrome isolated world, and returns `annotationCount`.
-Screenshot bytes are not evaluated in the page's default world. Annotation
-cannot be combined with `fullPage` or `selector`. A page can still move itself
-between geometry sampling and capture, so hosts should use a recent Observation
-and treat the image as visual context rather than durable element identity.
-
-For upload, first call `artifacts/import` with the owning Workspace, active
-Lease, and an absolute client-authorized path:
-
-```json
-{"jsonrpc":"2.0","id":30,"method":"artifacts/import","params":{"workspaceId":"workspace:...","leaseId":"lease:...","path":"/absolute/path/resume.pdf","mimeType":"application/pdf"}}
-```
-
-The Broker copies the source into protected storage and returns an
-`upload_input` Artifact descriptor. Pass only its `artifactId` to
-`browser.upload`; optionally identify a file input with
-`observationId + ref` or `inputIndex`. Output Artifacts such as screenshots and
-downloads are rejected as upload inputs. Workspace cleanup deletes the imported
-copy but never deletes the client-owned source file.
-
-Downloads have no path-returning tool. Once a controlled target session is
-attached, the Broker enables browser-level completion events while preserving
-Chrome's default download behavior, and emits `download` events with one of
-these states:
-
-- `capture_unavailable`: Chrome rejected browser-level completion events;
-- `started`: includes an opaque `downloadId`, bounded URL, and suggested filename;
-- `completed`: includes the Workspace-owned `download` Artifact descriptor;
-- `failed` or `cancelled`: includes a stable, bounded reason and byte metadata.
-
-These four lifecycle states also carry a `download` hint. `started` recommends
-waiting, `completed` recommends inspecting the Artifact and includes only its
-public `artifactId`, and terminal failures recommend inspecting the bounded
-failure reason. `capture_unavailable` is setup state and does not claim that a
-download started.
-
-The private CDP GUID and Chrome source path never appear in protocol output. On
-`completed`, use the descriptor's `id` with `artifacts/get` or
-`artifacts/export` exactly as for screenshots and PDFs. A session-scoped
-`Page.downloadWillBegin` event establishes Workspace/Lease/target ownership;
-the browser-level completion event is ignored unless that ownership already
-exists. Browser Pilot enables those completion events once per browser
-connection generation and Chrome Profile context with
-`Browser.setDownloadBehavior({ behavior: "default", eventsEnabled: true })`.
-It never supplies `downloadPath`, so Chrome continues to use the user's selected
-download directory.
-
-The Broker validates the completed absolute regular-file path and copies it to
-protected Artifact storage. Releasing or expiring the Artifact, Lease, or
-Workspace deletes only that copy. The original Chrome download is never moved
-or deleted. Size, concurrency, or Artifact quota failures reject only the
-Artifact copy and do not call `Browser.cancelDownload`. Downloads from tabs
-without an attached controlled session remain ordinary Chrome downloads and
-produce no Browser Pilot event.
-
-## Cleanup
-
-Normal EOF and `shutdown` release Connection-owned Leases immediately. A killed
-bridge is recovered by Lease expiry; stale Connection records and inactive
-Workspaces are also reclaimed by bounded daemon sweeps. Releasing a Workspace
-will eventually close only its Broker-managed targets. It must never close a
-user tab merely because a client disconnected or a Workspace expired.
-
-The daemon also starts a private managed-target janitor that solely owns the
-browser-level CDP WebSocket and proxies daemon CDP traffic over private IPC. It
-creates and tracks only Broker-managed targets and their managed popup
-descendants. Daemon EOF, including an ungraceful process exit, makes the janitor
-perform bounded cleanup without consulting disk or grouping tabs by browser
-window. This internal process is not a public SDK, tool, or transport; embedded
-clients still launch only `browser-pilot bridge --stdio`.
-
-The stdio `shutdown` method exits only that bridge and disconnects its Broker
-Connection. The human `bp disconnect` command separately releases the one-shot
-compatibility Workspace and requests daemon shutdown. The daemon accepts that
-request only when the Broker process identity and executable installation
-identity still match, `embeddedConnections` is zero, and no other active Lease
-remains. Otherwise it returns
-`protocol_incompatible` or retryable `broker_in_use`; it never evicts an Agent
-product to complete an upgrade.
-
-Owner-only `broker-locator.json` contains current executable and protocol
-metadata. Owner-only `broker-versions.json` retains at most current and previous
-executable installation metadata. Neither file contains browser selection,
-tabs, target IDs, Workspaces, Leases, refs, Artifacts, credentials, network
-rules, or command results. Rollback selection and preservation of old binaries
-belong to the installer or embedding product, not to the Broker.
-
-The current lifecycle runtime uses finite limits for live Connections,
-per-Principal Workspaces, per-Connection Leases, and retained terminal records.
-It does not persist target mappings, refs, cookies, credentials, network bodies,
-or command state.
-
-## Reference Consumer Adapters
-
-The source repository includes
-[`examples/adapters`](https://github.com/relixiaobo/browser-pilot/tree/main/examples/adapters)
-implementations for a
-Pi-style Tenon tool runtime and an OpenClaw dispatcher tool. They are host-side
-examples, not npm package files, a Native SDK, or an additional supported
-protocol surface. Production consumers should copy or port the small adapter
-pattern into their own integration and continue treating this document plus the
-runtime manifest as authoritative.
-
-The shared example launches an absolute executable path without a shell,
-negotiates protocol 1.1 through 1.3, discovers tools at runtime, and maps a host work scope
-to a Workspace plus its active invocation to a renewable Lease. It never stores
-a selected tab, frame, Observation, ref, credential, rule, Artifact, or event
-cursor on disk. Host tool-call IDs become Command and idempotency identities;
-transport loss after dispatch of a mutating operation is returned as
-non-retryable `unknown_outcome`.
-
-For event recovery, call `pollEvents`, completely process the returned ordered
-events, and only then call `acknowledgeEvents(nextCursor)`. A second poll before
-acknowledgement intentionally starts from the same last processed cursor. On
-`cursor_expired`, first rebuild tab and Observation state, then call
-`resetEventCursor` to use `workspaces/get` as the new live baseline. Best-effort
-notifications never advance the cursor.
-
-Image Artifacts are read from their protected path, converted to the host's
-native image content, and released. PDF and other file results require an
-absolute host-owned output directory; they are exported there before the
-protected Artifact is released. Cleanup invalidates local host contexts even if
-the explicit Broker release fails, so Lease expiry remains a bounded fallback
-and stale tools cannot continue issuing calls.
-
-## Current Release Gate
-
-`tools/list` is generated from the canonical schemas used for argument and
-result validation, and production filtering prevents unwired tools from being
-advertised. The current bridge supports discovery, connect, Profile routing, open, all-tab
-inventory, observe/read/search/find, scroll and dropdown actions, annotated
-screenshots, core actions, scoped frames, explicit dialogs, cookies, auth,
-network observation/rules, eval, PDF, protected upload import, scoped download
-Artifacts, Artifact access, command recovery, browser reconnect, and event
-replay. Broker startup serialization, executable/protocol negotiation,
-live-client shutdown protection, bounded version history, and deliberate
-version isolation are covered by process tests. Packed global npm, local
-npm/npx, and product-bundled absolute-path launches are also exercised as
-black-box installs. Native artifact verification covers manifest hashes,
-version output, stdio startup, the private Broker role, protected disconnect,
-and the private janitor role without attaching to the user's browser.
-
-Before shipping an adapter, run the black-box
-[stdio conformance suite](stdio-conformance.md) against the exact bundled launch
-command. The suite exercises only the public NDJSON protocol and creates no
-user-tab control state.