@btraut/browser-bridge 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -6,7 +6,33 @@ The format is based on "Keep a Changelog", and this project adheres to Semantic
 
 ## [Unreleased]
 
-_TBD_
+## [0.13.0] - 2026-02-18
+
+### Changed
+
+- `drive.navigate` now supports omitted `session_id` through both CLI and MCP; Core auto-creates the session and returns canonical `result.session_id` in the success payload.
+- CLI and MCP now share parity guardrails for `drive.navigate` contracts via shared explicit/missing-session fixture variants and contract checks.
+- Diagnostics caller runtime context is now normalized across CLI and MCP, with both clients attaching equivalent endpoint/process metadata for `diagnostics.doctor`.
+- Deprecation lifecycle policy is now explicit and machine-checked: shared tool metadata includes `deprecated_since`/`removal_target`/replacement fields and `packages/shared/src/tooling.test.ts` enforces notice window + migration metadata requirements.
+- Navigation naming is now canonicalized end-to-end on `drive.go_back`/`drive.go_forward`: Core routes and extension actions removed legacy alias actions, while CLI/MCP keep temporary deprecated alias shims that forward to canonical routes and emit explicit warnings.
+- Public contract version signaling is now explicit across HTTP and websocket surfaces: Core enforces/echoes `x-browser-bridge-contract-version`, CLI/MCP send the version header by default, extension `drive.hello` now includes websocket `protocol_version`, and core rejects handshake mismatches deterministically.
+- Public error taxonomy is now canonicalized: legacy/internal codes are normalized to a smaller non-overlapping public set, with typed migration details (`legacy_code`, `reason`, and structured context fields) attached to mapped responses.
+- Retry semantics now use centralized structured hints: shared `retry` metadata (`retryable`, `reason`, `retry_after_ms`, `max_attempts`) and shared retry policy logic replace boolean-only retry decisions in core drive flows, while preserving compatibility via `retryable`.
+- API route style is now explicitly RPC-over-HTTP POST: canonical health diagnostics route is `/health/check` (with legacy `/health_check` alias), and readiness supports canonical `POST /health` while retaining `GET /health` compatibility.
+- Dialog operations are now canonicalized to `drive.handle_dialog`; `dialog.accept`/`dialog.dismiss` are deprecated aliases that map to canonical payloads and emit explicit warnings.
+- Extension-core handshake now negotiates capabilities explicitly: `drive.hello` includes capability map metadata, and core gates non-negotiated or unsupported actions with deterministic errors.
+- Extension defaults are now tighter and explicit: host/content-script scope is limited to `http://*/*` + `https://*/*`, unused `tabGroups` permission is removed, and `debugger.*` inspect actions are gated behind an options toggle (`debuggerCapabilityEnabled`, default off) with deterministic `ATTACH_DENIED` guidance.
+- Refactor guardrails now explicitly separate semantic contracts from internal wiring details: inventory/tool-coverage docs define must-preserve behavior vs allowed internal evolution, and CLI/MCP contract tests now enforce semantic/schema parity without freezing exact internal route strings.
+
+### Fixed
+
+- MCP adapter integration coverage now disambiguates fixtures that share core routes (for example, dialog aliases), preventing false failures from path-only fixture collisions.
+- Filled test/doc gaps for deprecated aliases: added missing `dialog.dismiss` core route coverage, added MCP coverage for `drive.forward` warnings and `dialog.dismiss` input transform, and clarified deprecation/error-code docs.
+- Extension now re-applies the `Browser Bridge` tab-group title for reused dedicated agent tabs, so stale groups no longer stay untitled.
+- Extension now reapplies the toolbar robot icon as the dedicated agent tab favicon after agent-driven navigations.
+- Core drive preflight now fails fast with an explicit `EXTENSION_DISCONNECTED` error when the extension is offline, instead of attempting a drive call first.
+- Core `drive.navigate` now preflights loopback targets (`localhost`/`127.0.0.1`/`::1`) and returns `NAVIGATION_FAILED` quickly when the local app is unreachable.
+- Runtime path resolution now honors `BROWSER_BRIDGE_CWD` and safer cwd fallbacks, preventing broken launch contexts from writing logs/metadata under `/.context`.
 
 ## [0.12.1] - 2026-02-17
 

package/README.md

@@ -57,9 +57,8 @@ If Chrome shows a Browser Bridge permissions prompt, approve it, then tell the a
 <summary>CLI sanity check (debugging)</summary>
 
 ```bash
-browser-bridge session create
-# Use the session_id from the output for the next commands.
-browser-bridge drive navigate --session-id <id> --url https://example.com
+browser-bridge drive navigate --url https://example.com --json
+# Copy result.session_id from the response for subsequent session-scoped calls.
 browser-bridge inspect dom-snapshot --session-id <id> --max-nodes 2000
 browser-bridge session close --session-id <id>
 ```
@@ -107,7 +106,7 @@ See `docs/cdp-input-model.md` for details and smoke verification.
 
 ## 🔒 Site Permissions (Drive Actions)
 
-Browser Bridge is intentionally safe: **drive actions** (`drive.navigate`, click, type, etc.) require **per-site approval**. `inspect.*` is not gated, so agents can inspect first and only ask for permission when it's time to click/type.
+Browser Bridge is intentionally safe: **drive actions** (`drive.navigate`, click, type, etc.) require **per-site approval**. `inspect.*` is additionally guarded behind an explicit debugger-capability toggle in extension options.
 
 <details>
 <summary>How approvals work (click to expand)</summary>
@@ -125,6 +124,7 @@ Manage approvals (and bypass mode):
 - Switch **Permission mode** to **Bypass (dangerous)** to skip the allowlist and prompts entirely.
 - In bypass mode, the agent can take actions on any website without asking.
 - Restricted URLs (for example `chrome://` and `file://`) are still blocked.
+- `inspect.*` requires enabling **Debugger-based inspect** in extension options. If disabled, inspect calls fail with `ATTACH_DENIED` and a clear next step.
 
 </details>
 
@@ -147,8 +147,8 @@ The CLI mirrors the MCP tool surface.
 - `drive.navigate`
 - `drive.go_back`
 - `drive.go_forward`
-- `drive.back`
-- `drive.forward`
+- `drive.back` (deprecated alias for `drive.go_back`)
+- `drive.forward` (deprecated alias for `drive.go_forward`)
 - `drive.click`
 - `drive.hover`
 - `drive.select`
@@ -166,8 +166,8 @@ The CLI mirrors the MCP tool surface.
 
 **dialog**
 
-- `dialog.accept`
-- `dialog.dismiss`
+- `dialog.accept` (deprecated alias for `drive.handle_dialog` with `action=accept`)
+- `dialog.dismiss` (deprecated alias for `drive.handle_dialog` with `action=dismiss`)
 
 **inspect**
 
@@ -315,7 +315,7 @@ tail -n 80 .context/logs/browser-bridge/mcp-adapter.jsonl
 
 ## 🩺 Diagnostics
 
-- CLI: `browser-bridge diagnostics doctor --session-id <id>`
+- CLI: `browser-bridge diagnostics doctor [--session-id <id>]`
 - Reports extension and debugger status alongside session state.
 - Includes runtime context for caller, Core, and extension endpoints so mismatch causes are visible in one run.
 - Popup shows a simple `Connected` indicator (`green` when connected, `red` otherwise).