browser-pilot-cli 0.3.0 → 0.5.0

package/docs/plans/v0.3.0-stabilization.md

@@ -1,7 +1,7 @@
 # Browser Pilot v0.3.0 Stabilization Plan
 
-Status: **In progress**
-Candidate baseline: `v0.3.0-rc.6`; release target: `v0.3.0`, protocol `1.2`
+Status: **Complete**
+Released baseline: `v0.3.0`, protocol `1.2`
 
 ## Goal
 
@@ -48,7 +48,11 @@ products depend on. No Agent-specific behavior enters Browser Pilot.
   Chrome Profiles: public GitHub reading, search, precise scrolling, screenshot
   annotation, PDF export, a disposable form with verified input and submission,
   and managed-only cleanup. User tabs and exported files were preserved.
-- [ ] Tag `v0.3.0`, publish npm `latest`, and verify upgrade/rollback metadata.
+- [x] Tag `v0.3.0`, publish a non-prerelease GitHub Release and npm
+  `latest=0.3.0`, and retain `next=0.3.0-rc.6` plus the local RC.6 standalone
+  as rollback paths. The installed stable executable connected through one
+  authorization request and repeated managed open/cleanup with
+  `closed: 1, remaining: 6`; all six user tabs remained available.
 
 ## Stable decision
 
@@ -64,4 +68,6 @@ RC.4 through RC.6 then closed the remaining real-browser gaps in passive
 connection status, text-targeted scroll verification, restrictive-CSP screenshot
 annotation, and asynchronous managed-target closure. The published RC.6
 standalone now satisfies every pre-stable source, distribution, Host, and live
-Chrome gate above. Stable publication remains a separate explicit release step.
+Chrome gate above. The identical stable runtime passed the complete source and
+distribution gates, published successfully on all three platforms, and passed
+the installed user-Chrome smoke check.

package/docs/releases/v0.2.0.md

@@ -0,0 +1,53 @@
+# Browser Pilot 0.2.0
+
+Browser Pilot 0.2.0 turns the original one-shot CLI into an Agent-neutral
+browser control platform while preserving direct `bp` commands and the user's
+real Chrome profile. It requires no browser extension.
+
+## Highlights
+
+- Adds a versioned `bridge --stdio` protocol for products embedding the
+  official executable, with runtime tool discovery and no required SDK or MCP
+  dependency.
+- Adds a shared per-user Broker with isolated Workspaces, Leases, targets,
+  refs, network rules, auth state, events, and Artifacts for concurrent Agents.
+- Lists and controls eligible user-opened tabs alongside Browser Pilot managed
+  tabs. Bulk cleanup and session release close only managed tabs.
+- Makes Chrome discovery passive. Only an explicit `bp connect` or
+  `browser.connect` may request browser authorization, and concurrent requests
+  share one in-flight connection attempt without timer-driven retries.
+- Replaces file-backed refs with ephemeral Observation-scoped identity across
+  browser generations, targets, frames, CDP sessions, loaders, and documents.
+- Fuses accessibility, DOM, and layout information; supports Shadow DOM,
+  same-process frames, and OOPIFs with bounded output and typed stale-ref
+  failures.
+- Adds verified click, input, keyboard, upload, scroll, and dropdown behavior,
+  including obstruction checks, controlled-input readback, and composite-action
+  cancellation when page state changes.
+- Adds bounded read, search, DOM metadata, page geometry, annotated screenshot,
+  PDF, download Artifact, dialog, network interception, cookie, and HTTP auth
+  support.
+- Adds typed browser events, disconnect/reconnect state, command idempotency,
+  deadlines, cancellation, unknown outcomes, event cursors, and protected
+  Artifact delivery.
+- Adds npm, local project, and self-contained macOS, Linux, and Windows launch
+  modes plus a language-neutral stdio conformance suite and reference Tenon and
+  OpenClaw adapters.
+
+## Upgrade Notes
+
+- Chrome remote debugging must be enabled at
+  `chrome://inspect/#remote-debugging`.
+- Browser authorization is explicit. Run `bp connect` once when Browser Pilot
+  reports that it is disconnected; ordinary discovery and bridge startup do
+  not prompt.
+- Direct CLI behavior remains supported. Embedded products should launch the
+  pinned executable with `bridge --stdio` and depend only on the documented
+  protocol.
+- Refs are intentionally transient. Obtain a fresh snapshot after navigation,
+  frame changes, reconnects, or `stale_ref` responses.
+
+See the [platform specification](https://github.com/relixiaobo/browser-pilot/blob/v0.2.0/docs/architecture/browser-pilot-platform-spec.md),
+[stdio integration contract](https://github.com/relixiaobo/browser-pilot/blob/v0.2.0/docs/integration/stdio-bridge.md),
+and [conformance suite](https://github.com/relixiaobo/browser-pilot/blob/v0.2.0/docs/integration/stdio-conformance.md)
+for the stable public contracts.

package/docs/releases/v0.2.1.md

@@ -0,0 +1,13 @@
+# Browser Pilot 0.2.1
+
+This packaging-only patch adds the canonical GitHub repository metadata
+required for npm Trusted Publishing provenance verification. Browser runtime,
+protocol, CLI, and Agent integration behavior are unchanged from 0.2.0.
+
+This is the first 0.2 stable version published through the package's GitHub
+Actions OIDC Trusted Publisher. The npm package requires no long-lived publish
+token, and its provenance identifies
+`https://github.com/relixiaobo/browser-pilot` as the source repository.
+
+See the [Browser Pilot 0.2.0 release](https://github.com/relixiaobo/browser-pilot/releases/tag/v0.2.0)
+for the complete feature and upgrade notes.

package/docs/releases/v0.2.2.md

@@ -0,0 +1,18 @@
+# Browser Pilot 0.2.2
+
+This patch fixes executable ownership validation when a CLI command encounters
+a compatible Broker started by another Browser Pilot installation.
+
+The CLI now checks the Broker's executable version and identity before it
+initializes its one-shot connection. A mismatched installation returns the
+structured `protocol_incompatible` error without creating or changing Broker
+session state. The executable that owns the Broker can therefore still shut it
+down cleanly, which makes in-place upgrades deterministic and avoids a failed
+command leaving the old Broker unusable.
+
+Health responses from older compatible Brokers that do not expose executable
+metadata remain supported. Current Brokers continue to enforce exact ownership
+for protected shutdown.
+
+Browser authorization, tab ownership, public protocol, and Agent integration
+behavior are otherwise unchanged from 0.2.1.

package/docs/releases/v0.4.0.md

@@ -0,0 +1,62 @@
+# Browser Pilot 0.4.0
+
+Browser Pilot 0.4.0 introduces protocol 1.3 while preserving protocol 1.0-1.2
+compatibility and the extension-free browser control model.
+
+## Profile identity
+
+- `browser.profiles.list` remains passive and returns neutral, connection-scoped
+  Profile contexts without opening or attaching to identity pages.
+- New `browser.profiles.identify` explicitly creates temporary visible
+  `chrome://version` targets, verifies the reported Profile path against the
+  connected browser `userDataRoot`, reads bounded Chrome Local State metadata,
+  and proves cleanup before returning.
+- Results distinguish `unidentified`, `verified`, and `unavailable`, with
+  structured Profile/account fields and stable failure codes. Identity is
+  cached only for one browser connection generation.
+- `bp profiles --identify [--refresh]` exposes the same behavior. Profile and
+  tab selectors are one-based and may use a uniquely verified Profile name,
+  account name, or email address.
+
+## Agent isolation and vocabulary
+
+- Direct one-shot CLI Agents can set a stable `BROWSER_PILOT_CLIENT_KEY` or
+  `--client-key`; different keys receive distinct Principal, Connection,
+  Workspace, and Lease state while repeated calls with one key reuse it.
+- `bp disconnect` releases only its CLI namespace and cannot stop a Broker that
+  still has another active Lease or embedded Connection.
+- Protocol 1.3 browser discovery uses `userDataRoot` instead of the ambiguous
+  legacy candidate field `profile`.
+- Protocol 1.3 tab inventory uses `selected` for the Lease-local target instead
+  of `active`, which could be mistaken for Chrome foreground focus.
+
+## Page and target isolation
+
+- Browser Pilot no longer injects a controller overlay or other status UI into
+  page DOM. Embedding Hosts may present returned controller identity in
+  Host-owned UI.
+- Chrome and Edge extension pages are excluded from ordinary tab inventory and
+  Profile context evidence.
+- Existing eligible user tabs remain fully controllable; managed-only cleanup
+  still leaves user tabs open.
+
+## Embedding
+
+- The Tenon/OpenClaw-neutral reference adapter negotiates protocol 1.3 and
+  discovers the identity operation through the canonical runtime manifest.
+- One-shot CLI, embedded stdio, local Artifact export, native image results,
+  and protocol 1.0-1.2 compatibility remain supported without a Native SDK,
+  MCP server, or browser extension.
+
+## CLI and distribution contract
+
+- Every non-TTY one-shot failure now includes stable `code` and `retryable`
+  fields. Commander/parser and local input errors use `invalid_argument`, while
+  Broker errors preserve their protocol code and structured remediation.
+- The versioned Agent plugin/skill records CLI `0.4.0` as its tested/minimum
+  version and accepts backward-compatible updates within the declared range. It
+  includes Codex UI metadata plus a machine-readable compatibility manifest.
+- GitHub releases publish the plugin archive and checksum alongside a release
+  index that verifies the npm version, protocol range, and every native asset.
+- Native targets are Apple Silicon macOS, x64 Linux, and x64 Windows. Intel Mac
+  is not supported and no `darwin-x64` asset is published.

package/docs/releases/v0.5.0.md

@@ -0,0 +1,93 @@
+# Browser Pilot 0.5.0
+
+Browser Pilot 0.5.0 establishes one public integration model for every Agent:
+the Browser Pilot skill invokes the short-lived `bp` CLI through the Agent's
+existing shell tool. Agent-installed and product-bundled copies now use the
+same commands, state model, and recovery behavior.
+
+## One Agent interface
+
+- The public `bridge --stdio` command, JSON-RPC adapter, reference host
+  adapters, conformance suites, and adapter documentation have been removed.
+- Browser Pilot does not require an MCP server, Native SDK, Browser Pilot
+  native tools, Agent-specific runtime, or browser extension.
+- Tenon, OpenClaw, Codex, Claude Code, and other shell-capable Agents integrate
+  by bundling a compatible CLI on the Agent `PATH`, installing the same skill,
+  and assigning a stable `BROWSER_PILOT_CLIENT_KEY` per independent Agent.
+- The internal Broker remains shared and long-lived. Individual CLI processes
+  remain short-lived and do not expose the Broker protocol as a public API.
+
+## Stateful CLI recovery
+
+- `bp status` returns bounded browser, profile, tab, active-command,
+  uncertain-command, and structured recovery state for the current Agent.
+- `bp commands`, `bp command <id>`, and `bp cancel <id>` expose command
+  inspection and best-effort cancellation without a persistent client.
+- Global `--request-id` provides deterministic deduplication for recovery of
+  one intended operation. Global `--timeout` sets its command deadline.
+- `SIGINT` and `SIGTERM` request cancellation of an active command. Mutations
+  that may already have reached Chrome still return `unknown_outcome` and must
+  be inspected before retry.
+- `bp wait` waits for one browser-visible URL, text, selector, dialog,
+  download, or popup condition and returns stable `wait_timeout` on expiry.
+  Terminating the wait CLI returns `command_cancelled` without releasing its
+  Agent browser state.
+- `bp status` queries active and uncertain command states independently, so a
+  long condition wait cannot hide an older `unknown_outcome` behind its polling
+  reads.
+
+## Files and downloads
+
+- `BROWSER_PILOT_OUTPUT_DIR` provides a task-owned default destination for
+  screenshots, PDFs, exported downloads, and saved network bodies.
+- Capture and download results return an absolute file path, MIME type, byte
+  size, and image dimensions when available.
+- `bp downloads` lists completed downloads retained for the current Agent;
+  `bp download <index> [filename]` copies one result without moving or deleting
+  Chrome's original file.
+- Artifact exports and saved network bodies are written with private file
+  permissions.
+
+## Shared Broker and Agent isolation
+
+- The private Broker RPC envelope is versioned independently from the public
+  CLI. A 0.5 CLI detects a pre-0.5 Broker before sending RPC and returns
+  `protocol_incompatible` with explicit stop-or-isolate remediation.
+- Compatible global, Agent-installed, and product-bundled CLI versions reuse
+  one per-user Broker through protocol negotiation rather than executable-path
+  equality.
+- A stable Agent key preserves selected profile, tab, frame, refs, auth,
+  network rules, downloads, and command history across CLI calls. Different
+  keys remain isolated.
+- Commands are serialized per physical target. A second Agent receives
+  `target_busy` instead of taking control of a tab already leased by another
+  Agent.
+- `bp disconnect` releases only the invoking Agent's state and managed tabs.
+  A compatible CLI that does not own the Broker executable cannot stop the
+  shared Broker.
+- All eligible Browser Pilot-created and user-opened tabs remain available;
+  user tabs stay open during Agent release and crash cleanup.
+
+## Skill and distribution
+
+- The skill uses progressive disclosure: the main operating loop links to
+  separate command, asynchronous recovery, failure recovery, and product
+  embedding references.
+- `bp --help` is the canonical runtime command inventory. The plugin no longer
+  publishes a permanent native-tool manifest.
+- CLI, skill, plugin, marketplace metadata, compatibility range, checksums,
+  and release index are versioned together at 0.5.0.
+- Native release targets remain Apple Silicon macOS, x64 Linux, and x64
+  Windows. Intel Mac is not supported.
+
+## Migration from 0.4.x
+
+Remove any `browser-pilot bridge --stdio` process and Browser Pilot-specific
+tool mapping. Keep the Agent's normal shell tool, install the complete
+`browser-pilot` skill, make a compatible `bp` executable available on `PATH`,
+and inject `BROWSER_PILOT_CLIENT_KEY` plus an absolute
+`BROWSER_PILOT_OUTPUT_DIR`. Use `bp status`, command recovery, and `bp wait`
+when the host previously depended on a persistent adapter for state or events.
+If a pre-0.5 Broker is still running, stop it once with the older executable's
+`bp disconnect` before starting 0.5; Browser Pilot never replaces a live
+incompatible process automatically.

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "browser-pilot-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "CLI tool to control your browser via Chrome DevTools Protocol",
   "repository": "https://github.com/relixiaobo/browser-pilot",
   "type": "module",
   "bin": {
     "bp": "dist/cli.js",
-    "browser-pilot": "dist/cli.js",
-    "browser-pilot-conformance": "scripts/run-stdio-conformance.mjs"
+    "browser-pilot": "dist/cli.js"
   },
   "scripts": {
     "build": "tsup",
     "build:standalone:js": "tsup --config tsup.standalone.config.ts",
     "build:standalone": "npm run build:standalone:js && node scripts/build-standalone.mjs",
     "package:standalone": "node scripts/package-standalone.mjs",
+    "package:agent-plugin": "node scripts/package-agent-plugin.mjs",
+    "package:release-index": "node scripts/build-release-index.mjs",
+    "release:sync-version": "node scripts/sync-release-version.mjs",
+    "release:check-version": "node scripts/sync-release-version.mjs --check",
+    "version": "node scripts/sync-release-version.mjs",
     "verify:standalone": "node scripts/verify-standalone.mjs",
     "dev": "tsup --watch",
     "start": "node dist/cli.js",
@@ -21,8 +25,6 @@
     "test:unit": "tsup && node --test tests/*.test.mjs",
     "test:capabilities": "tsup && node --test tests/browser-capability-fixtures.test.mjs",
     "test:protocol": "tsup && node --test tests/protocol.test.mjs",
-    "test:stdio-conformance": "tsup && node scripts/run-isolated-stdio-conformance.mjs",
-    "test:host-acceptance": "tsup && node scripts/run-isolated-host-integration-acceptance.mjs",
     "test:distribution": "tsup && node scripts/verify-npm-distribution.mjs",
     "test:canary": "tsup && node scripts/run-real-site-canaries.mjs",
     "test:canary:strict": "tsup && node scripts/run-real-site-canaries.mjs --strict",
@@ -36,21 +38,12 @@
     "dist/cli.js",
     "dist/daemon.js",
     "dist/managed-target-janitor.js",
-    "scripts/run-stdio-conformance.mjs",
     "docs/architecture/browser-pilot-platform-spec.md",
-    "docs/integration/stdio-bridge.md",
-    "docs/integration/stdio-conformance.md",
     "docs/plans/browser-capability-evolution.md",
     "docs/plans/profile-context-routing.md",
     "docs/plans/v0.3.0-stabilization.md",
     "docs/plans/universal-agent-integration.md",
-    "docs/releases/v0.3.0-rc.1.md",
-    "docs/releases/v0.3.0-rc.2.md",
-    "docs/releases/v0.3.0-rc.3.md",
-    "docs/releases/v0.3.0-rc.4.md",
-    "docs/releases/v0.3.0-rc.5.md",
-    "docs/releases/v0.3.0-rc.6.md",
-    "docs/releases/v0.3.0.md",
+    "docs/releases/",
     "README.md",
     "LICENSE"
   ],