@btraut/browser-bridge 0.3.0 → 0.4.2

package/CHANGELOG.md

@@ -6,6 +6,48 @@ The format is based on "Keep a Changelog", and this project adheres to Semantic
 
 ## [Unreleased]
 
+### Added
+
+_TBD_
+
+### Fixed
+
+_TBD_
+
+## [0.4.2] - 2026-02-07
+
+### Fixed
+
+- Fix the GitHub release workflow tag/version verification step so tag pushes reliably create a GitHub Release and upload the extension zip.
+
+## [0.4.1] - 2026-02-07
+
+### Added
+
+- `health_check` MCP tool and core endpoint (`/health_check`) for uptime/memory/session/extension status.
+- Full-page scrolling screenshots for `artifacts.screenshot` via `fullPage: true` (scroll + stitch, up to ~50K px tall).
+- MCP Streamable HTTP server transport (in addition to stdio).
+- Pre-built Chrome extension zip attached to GitHub releases.
+- Element-targeted screenshots for `artifacts.screenshot` via `selector`.
+
+### Fixed
+
+_TBD_
+
+## [0.4.0] - 2026-02-06
+
+### Added
+
+- Core idle session TTL cleanup (configurable via `BROWSER_BRIDGE_SESSION_TTL_MS`).
+- Diagnostics now include a session summary (count and max age/idle time).
+
+### Fixed
+
+- Sanitize Chrome extension error messages before forwarding them to clients (remove file paths and redact URLs to origin).
+- Share the core <-> extension protocol types via `@btraut/browser-bridge-shared` (remove manual sync).
+- Refactor InspectService internals into `packages/core/src/inspect/*` modules and expand unit test coverage (no API changes).
+- Stabilize `scripts/cli-full-tool-smoke.sh` dialog steps by refreshing debugger attachment before opening JS dialogs.
+
 ## [0.3.0] - 2026-02-06
 
 ### Added

package/README.md

@@ -1,10 +1,47 @@
 <img src="docs/assets/readme-header.png" alt="Browser Bridge header graphic" width="720" />
 
-[![npm version](https://img.shields.io/npm/v/@btraut/browser-bridge.svg)](https://www.npmjs.com/package/@btraut/browser-bridge) [![CI](https://github.com/btraut/browser-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/btraut/browser-bridge/actions/workflows/ci.yml) [![License](https://img.shields.io/github/license/btraut/browser-bridge.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@btraut/browser-bridge.svg)](https://www.npmjs.com/package/@btraut/browser-bridge) [![npm downloads](https://img.shields.io/npm/dm/@btraut/browser-bridge.svg)](https://www.npmjs.com/package/@btraut/browser-bridge) [![CI](https://github.com/btraut/browser-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/btraut/browser-bridge/actions/workflows/ci.yml) [![License](https://img.shields.io/github/license/btraut/browser-bridge.svg)](LICENSE)
 
 # Browser Bridge
 
-Local Chrome control for coding agents. Browser Bridge provides a CLI and an optional MCP server that drive your real, local Chrome (not headless) and read page state through a Chrome extension. This keeps you in the loop, with your existing tabs and login state.
+**Reliable local Chrome control for coding agents.**
+
+Browser Bridge drives your real, local Chrome (not headless) and inspects page state through a Chrome extension plus a local daemon. You stay in the loop with your existing tabs and login state.
+
+What makes it different:
+
+- **Real browser state**: operate on your actual Chrome profile (tabs, cookies, logins, extensions).
+- **Two-plane architecture**: a **drive** plane that does what a user does (click, type, navigate), plus an **inspect** plane that reads state (DOM, console, screenshots). This separation makes runs less flaky and lets inspection happen in parallel.
+- **Token-efficient inspection**: stable element refs like `@e1` (find once, reuse everywhere) plus knobs to bound output (`--max-nodes`, `--compact`, `--interactive`, `--selector`).
+- **Structured errors for agents**: stable error codes with a `retryable` flag (no more guessing whether to retry).
+- **Recovery-first**: sessions have an explicit state machine with `session.recover()` and `diagnostics doctor`.
+- **Inspect beyond screenshots**: DOM snapshots (AX + HTML) and `inspect dom-diff` to detect page changes.
+
+## Why Browser Bridge
+
+Browser Bridge is built for agent reliability and "stay logged in" workflows in your real Chrome, not for headless test automation.
+
+If you're coming from Playwright/Puppeteer-style tooling:
+
+- Browser Bridge targets the user's existing, interactive Chrome session by default (typical Playwright/Puppeteer flows spin up a separate browser/context).
+- Browser Bridge surfaces retry guidance in the API (`retryable`) instead of forcing the agent to infer it from exceptions and timing.
+- Browser Bridge ships a first-class inspect plane (DOM snapshots, diffs, diagnostics) designed for LLM consumption, with output-bounding options to keep agent context small.
+
+If you're coming from an extension-only MCP tool:
+
+- Browser Bridge puts a stateful local Core daemon behind the tools (sessions, recovery, diagnostics, artifacts).
+- Drive actions are serialized for determinism; inspect is a separate plane that can keep producing structured state.
+- CLI works everywhere; MCP is optional.
+
+## How It Works
+
+Core keeps a session state machine and exposes a small set of stable tools:
+
+- `session.*` - lifecycle + recovery
+- `drive.*` - navigation + input (single-flight)
+- `inspect.*` - DOM snapshots/diffs + evaluation
+- `diagnostics.*` - health checks
+- `artifacts.*` - screenshots
 
 ## Requirements
 
@@ -13,7 +50,7 @@ Local Chrome control for coding agents. Browser Bridge provides a CLI and an opt
 - Browser Bridge extension (Chrome Web Store listing pending; see manual install below)
 - Local-only usage (all services bind to 127.0.0.1)
 
-## Install
+## Install (CLI)
 
 ```bash
 npm i -g @btraut/browser-bridge
@@ -24,6 +61,10 @@ browser-bridge --help
 
 Chrome Web Store listing is pending. For now, install the extension manually:
 
+1. Download the latest pre-built extension zip from [GitHub Releases](https://github.com/btraut/browser-bridge/releases) (Assets), unzip it, and use the unzipped folder for step 3.
+
+Alternative (build from source):
+
 1. Clone this repo.
 2. Install deps and build:
 
@@ -33,14 +74,13 @@ npm run build
 ```
 
 3. Open Chrome and navigate to `chrome://extensions`.
-4. Enable **Developer mode**, click **Load unpacked**, and select `packages/extension` (the folder with `manifest.json`).
+4. Enable **Developer mode**, click **Load unpacked**, and select the extension folder (the folder with `manifest.json`).
 
 ## Quickstart
 
-1. Install the extension (see "Chrome Extension (Manual Install)" above).
-2. Install the Browser Bridge skill (see below).
-3. (Optional) Add Browser Bridge to your MCP client (Codex or Claude Code below).
-4. Run a quick CLI check:
+1. Install the extension.
+2. (Optional) Run `browser-bridge install` (skill + optional MCP).
+3. Run a quick CLI check (Core auto-starts by default):
 
 ```bash
 browser-bridge session create
@@ -54,7 +94,9 @@ Notes:
 
 - `inspect dom-snapshot` defaults to `--format ax`; `--max-nodes` is only supported for AX snapshots.
 
-## Skills (Codex + Claude Code)
+## Skills (Agent Clients)
+
+Browser Bridge skills work across many agent clients, including Codex and Claude Code.
 
 Easiest option (recommended):
 
@@ -62,7 +104,14 @@ Easiest option (recommended):
 browser-bridge install
 ```
 
-Or copy the Browser Bridge skill into your agent skills directory:
+Skill only:
+
+```bash
+browser-bridge skill install
+browser-bridge skill status
+```
+
+Or copy the Browser Bridge skill into your agent skills directory (advanced):
 
 ```bash
 # From this repo:
@@ -80,11 +129,14 @@ Restart your agent app if it does not pick up the new skill automatically.
 
 The MCP server runs over stdio and forwards tool calls to Core. It is optional, since you can use the CLI directly. MCP clients launch it automatically when needed, so you typically do not run it yourself.
 
+- Easiest option: `browser-bridge mcp install`
 - Manual start (debugging): `browser-bridge mcp`
 - Use your MCP client to call `tools/list`, then `session.create`
 - Override Core host/port with `--host`, `--port`, or `BROWSER_BRIDGE_CORE_HOST` / `BROWSER_BRIDGE_CORE_PORT`.
 
-## Add MCP (Codex CLI)
+## Manual MCP Setup (Advanced)
+
+Codex:
 
 ```bash
 codex mcp add browser-bridge -- browser-bridge mcp
@@ -99,7 +151,7 @@ codex mcp add browser-bridge \
   -- browser-bridge mcp
 ```
 
-## Add MCP (Claude Code)
+Claude Code:
 
 ```bash
 claude mcp add --transport stdio browser-bridge -- browser-bridge mcp
@@ -119,27 +171,16 @@ claude mcp add --transport stdio browser-bridge \
 - CLI: `browser-bridge diagnostics doctor --session-id <id>`
 - Reports extension and debugger status alongside session state.
 
-## Changelog
-
-See `CHANGELOG.md`.
-
-## Releasing
-
-See `docs/releasing.md`.
-
-## Security Model (v1)
+## Recovery
 
-- Extension <-> Core WebSocket has no authentication; trust local machine only.
-- Do not expose the port or run the Core daemon on shared hosts.
+If drive or inspect gets into a bad state, recovery is explicit:
 
-## Development Notes
+- `browser-bridge session recover --session-id <id>`
+- Then retry the failed operation once (tools report whether failures are `retryable`).
 
-If you are contributing locally, load the extension unpacked:
+## Session TTL (Core Daemon)
 
-1. Open Chrome and navigate to `chrome://extensions`.
-2. Enable **Developer mode**.
-3. Click **Load unpacked** and select `packages/extension` (repo).
-4. Confirm the extension's background service worker is running.
-5. Start the Core daemon (or run `browser-bridge session create`) so the extension can connect to `127.0.0.1`.
+The Core daemon keeps sessions in memory. By default, it automatically cleans up idle sessions after 1 hour.
 
-Additional manual test flows live in `docs/manual-test.md`.
+- `BROWSER_BRIDGE_SESSION_TTL_MS`: Idle session TTL in milliseconds. Set to `0` to disable cleanup.
+- `BROWSER_BRIDGE_SESSION_CLEANUP_INTERVAL_MS`: Cleanup interval in milliseconds. Defaults to a small value relative to the TTL.