browser-pilot-cli 0.1.6 → 0.2.1

package/docs/integration/stdio-bridge.md

@@ -0,0 +1,614 @@
+# 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.
+
+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":1}},"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/profile identity, 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.
+
+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, and an `eventCursor`. `workspaces/get` returns 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.
+
+`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.
+
+`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 originally selected profile's endpoint metadata and does not
+switch profiles 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 configures target-session download capture and emits
+`download` events with one of these states:
+
+- `capture_unavailable`: that Chrome version rejected target-session isolation;
+- `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 staging 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. Staging directories are separate per CDP
+session, use mode `0700`, enforce concurrency and byte quotas, and are removed on
+session, Lease, or Workspace release. The session setting is restored to
+`default` before an attached session is retired. Browser Pilot never calls browser-wide
+`Browser.setDownloadBehavior`; unsupported target-session capture remains
+unavailable instead of redirecting unrelated user downloads.
+
+## 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 and `embeddedConnections` is zero. 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, discovers tools at runtime, and maps a host work scope
+to a Workspace plus its active invocation to a renewable Lease. It never stores
+an active 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, 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.

package/docs/integration/stdio-conformance.md

@@ -0,0 +1,51 @@
+# Stdio Conformance Suite
+
+The stdio conformance suite verifies an embedded Browser Pilot executable as a
+black box. It launches the exact command supplied by the integrator, exchanges
+only newline-delimited JSON-RPC 2.0 over stdin/stdout, and imports no Browser
+Pilot source or protocol modules.
+
+Build and test the repository executable:
+
+```bash
+npm run build
+node scripts/run-stdio-conformance.mjs
+```
+
+An installed package also exposes the same runner as
+`browser-pilot-conformance`.
+
+Test an executable or product-bundled adapter with its exact arguments. The
+command after `--` is passed directly to the operating system without a shell:
+
+```bash
+node scripts/run-stdio-conformance.mjs -- \
+  /absolute/path/to/browser-pilot bridge --stdio
+```
+
+Use `--report <path>` to write the same JSON report printed to stdout, and
+`--timeout-ms <value>` to change the per-operation timeout. A passed suite exits
+with status 0, a conformance failure exits with status 1, and invalid runner
+arguments exit with status 2.
+
+The suite creates one transient Workspace, one renewable Lease, and one managed
+`about:blank` target. It does not enumerate or control user tabs. It validates:
+
+- initialization and capability negotiation;
+- tool manifest discovery;
+- Workspace, Lease, and heartbeat lifecycle;
+- managed target creation and inventory;
+- a bounded Observation;
+- screenshot creation, protected Artifact access, and release;
+- event cursor polling;
+- explicit target, Lease, Workspace, and bridge cleanup.
+
+Failures trigger best-effort cleanup of only the resources created by the
+suite. The versioned report contains check outcomes, counts, timings, version
+metadata, and a bounded error summary. It intentionally omits opaque resource
+IDs, Artifact paths, browser content, and bridge stderr text.
+
+The repository tests exercise the runner against an independent fake stdio
+executable, so normal unit tests do not connect to Chrome. Running the suite
+against the real executable requires a ready supported browser and may start or
+reuse the per-user Browser Pilot daemon.