@btraut/browser-bridge 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -14,6 +14,26 @@ _TBD_
 
 _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

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,13 +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.
-2. Run `browser-bridge install` (skill + optional MCP).
-3. Run a quick CLI check:
+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
@@ -53,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):
 
@@ -128,34 +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.
 
+## Recovery
+
+If drive or inspect gets into a bad state, recovery is explicit:
+
+- `browser-bridge session recover --session-id <id>`
+- Then retry the failed operation once (tools report whether failures are `retryable`).
+
 ## Session TTL (Core Daemon)
 
 The Core daemon keeps sessions in memory. By default, it automatically cleans up idle sessions after 1 hour.
 
 - `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.
-
-## Changelog
-
-See `CHANGELOG.md`.
-
-## Releasing
-
-See `docs/releasing.md`.
-
-## Security Model (v1)
-
-- Extension <-> Core WebSocket has no authentication; trust local machine only.
-- Do not expose the port or run the Core daemon on shared hosts.
-
-## Development Notes
-
-If you are contributing locally, load the extension unpacked:
-
-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`.
-
-Additional manual test flows live in `docs/manual-test.md`.

package/dist/api.js

@@ -2521,8 +2521,125 @@ var InspectService = class {
   async screenshot(input) {
     this.requireSession(input.sessionId);
     const selection = await this.resolveTab(input.targetHint);
-    await this.debuggerCommand(selection.tabId, "Page.enable", {});
     const format = input.format ?? "png";
+    const writeArtifact = async (data2) => {
+      try {
+        const rootDir = await ensureArtifactRootDir(input.sessionId);
+        const artifactId = (0, import_crypto3.randomUUID)();
+        const extension = format === "jpeg" ? "jpg" : format;
+        const filePath = import_node_path2.default.join(
+          rootDir,
+          `screenshot-${artifactId}.${extension}`
+        );
+        await (0, import_promises2.writeFile)(filePath, Buffer.from(data2, "base64"));
+        const mime = format === "jpeg" ? "image/jpeg" : `image/${format}`;
+        const output = {
+          artifact_id: artifactId,
+          path: filePath,
+          mime
+        };
+        this.markInspectConnected(input.sessionId);
+        return output;
+      } catch {
+        const error = new InspectError(
+          "ARTIFACT_IO_ERROR",
+          "Failed to write screenshot file."
+        );
+        this.recordError(error);
+        throw error;
+      }
+    };
+    if (input.selector) {
+      if (!this.extensionBridge?.request) {
+        const error = new InspectError(
+          "NOT_SUPPORTED",
+          "Element screenshots require an extension that supports drive.screenshot."
+        );
+        this.recordError(error);
+        throw error;
+      }
+      const response = await this.extensionBridge.request(
+        "drive.screenshot",
+        {
+          tab_id: selection.tabId,
+          mode: "element",
+          selector: input.selector,
+          format,
+          ...typeof input.quality === "number" ? { quality: input.quality } : {}
+        },
+        12e4
+      );
+      if (response.status === "error") {
+        const error = new InspectError(
+          response.error?.code ?? "INSPECT_UNAVAILABLE",
+          response.error?.message ?? "Failed to capture element screenshot.",
+          {
+            retryable: response.error?.retryable ?? false,
+            ...response.error?.details ? { details: response.error.details } : {}
+          }
+        );
+        this.recordError(error);
+        throw error;
+      }
+      const result2 = response.result;
+      if (!result2?.data_base64 || typeof result2.data_base64 !== "string") {
+        const error = new InspectError(
+          "INSPECT_UNAVAILABLE",
+          "Failed to capture element screenshot."
+        );
+        this.recordError(error);
+        throw error;
+      }
+      return await writeArtifact(result2.data_base64);
+    }
+    if (input.target === "full" && this.extensionBridge?.request) {
+      try {
+        const response = await this.extensionBridge.request(
+          "drive.screenshot",
+          {
+            tab_id: selection.tabId,
+            mode: "full_page",
+            format,
+            ...typeof input.quality === "number" ? { quality: input.quality } : {}
+          },
+          12e4
+        );
+        if (response.status === "error") {
+          const error = new InspectError(
+            response.error?.code ?? "INSPECT_UNAVAILABLE",
+            response.error?.message ?? "Failed to capture full page screenshot.",
+            {
+              retryable: response.error?.retryable ?? false,
+              ...response.error?.details ? { details: response.error.details } : {}
+            }
+          );
+          this.recordError(error);
+          throw error;
+        }
+        const result2 = response.result;
+        if (!result2?.data_base64 || typeof result2.data_base64 !== "string") {
+          const error = new InspectError(
+            "INSPECT_UNAVAILABLE",
+            "Failed to capture full page screenshot."
+          );
+          this.recordError(error);
+          throw error;
+        }
+        return await writeArtifact(result2.data_base64);
+      } catch (error) {
+        if (error instanceof InspectError) {
+          const code = String(error.code);
+          if (![
+            "NOT_SUPPORTED",
+            "NOT_IMPLEMENTED",
+            "INSPECT_UNAVAILABLE"
+          ].includes(code)) {
+            throw error;
+          }
+        }
+      }
+    }
+    await this.debuggerCommand(selection.tabId, "Page.enable", {});
     let captureParams = {
       format,
       fromSurface: true
@@ -2567,31 +2684,7 @@ var InspectService = class {
       this.recordError(error);
       throw error;
     }
-    try {
-      const rootDir = await ensureArtifactRootDir(input.sessionId);
-      const artifactId = (0, import_crypto3.randomUUID)();
-      const extension = format === "jpeg" ? "jpg" : format;
-      const filePath = import_node_path2.default.join(
-        rootDir,
-        `screenshot-${artifactId}.${extension}`
-      );
-      await (0, import_promises2.writeFile)(filePath, Buffer.from(data, "base64"));
-      const mime = format === "jpeg" ? "image/jpeg" : `image/${format}`;
-      const output = {
-        artifact_id: artifactId,
-        path: filePath,
-        mime
-      };
-      this.markInspectConnected(input.sessionId);
-      return output;
-    } catch {
-      const error = new InspectError(
-        "ARTIFACT_IO_ERROR",
-        "Failed to write screenshot file."
-      );
-      this.recordError(error);
-      throw error;
-    }
+    return await writeArtifact(data);
   }
   ensureDebugger() {
     if (!this.debugger) {
@@ -3266,10 +3359,30 @@ var ArtifactsScreenshotInputSchema = import_zod2.z.object({
   session_id: import_zod2.z.string().min(1),
   target: import_zod2.z.enum(["viewport", "full"]).default("viewport"),
   fullPage: import_zod2.z.boolean().default(false),
+  selector: import_zod2.z.string().min(1).optional(),
   format: import_zod2.z.enum(["png", "jpeg", "webp"]).default("png"),
   quality: import_zod2.z.number().min(0).max(100).optional()
 });
 var ArtifactsScreenshotOutputSchema = ArtifactInfoSchema;
+var HealthCheckInputSchema = import_zod2.z.object({});
+var HealthCheckOutputSchema = import_zod2.z.object({
+  started_at: import_zod2.z.string().min(1),
+  uptime_ms: import_zod2.z.number().finite().nonnegative(),
+  memory: import_zod2.z.object({
+    rss: import_zod2.z.number().finite().nonnegative(),
+    heapTotal: import_zod2.z.number().finite().nonnegative(),
+    heapUsed: import_zod2.z.number().finite().nonnegative(),
+    external: import_zod2.z.number().finite().nonnegative(),
+    arrayBuffers: import_zod2.z.number().finite().nonnegative().optional()
+  }).passthrough(),
+  sessions: import_zod2.z.object({
+    active: import_zod2.z.number().finite().nonnegative()
+  }).passthrough(),
+  extension: import_zod2.z.object({
+    connected: import_zod2.z.boolean(),
+    last_seen_at: import_zod2.z.string().min(1).optional()
+  }).passthrough()
+}).passthrough();
 var DiagnosticsDoctorInputSchema = import_zod2.z.object({
   session_id: import_zod2.z.string().min(1).optional()
 });
@@ -3325,6 +3438,7 @@ var registerArtifactsRoutes = (router, options = {}) => {
       const result = await inspect.screenshot({
         sessionId: input.session_id,
         target,
+        selector: input.selector,
         format: input.format,
         quality: input.quality,
         targetHint: hint
@@ -3461,7 +3575,44 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
 };
 
 // packages/core/src/routes/diagnostics.ts
+var PROCESS_STARTED_AT = new Date(
+  Date.now() - Math.floor(process.uptime() * 1e3)
+).toISOString();
 var registerDiagnosticsRoutes = (router, options = {}) => {
+  router.post("/health_check", (req, res) => {
+    const body = req.body ?? {};
+    if (!isRecord(body)) {
+      sendError(res, 400, {
+        code: "INVALID_ARGUMENT",
+        message: "Request body must be an object.",
+        retryable: false
+      });
+      return;
+    }
+    const parsed = HealthCheckInputSchema.safeParse(body);
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      sendError(res, 400, {
+        code: "INVALID_ARGUMENT",
+        message: issue?.message ?? "Invalid health check request.",
+        retryable: false,
+        details: issue?.path.length ? { field: issue.path.map((part) => String(part)).join(".") } : void 0
+      });
+      return;
+    }
+    const sessionsActive = options.registry ? options.registry.list().length : 0;
+    const extensionStatus = options.extensionBridge?.getStatus();
+    sendResult(res, {
+      started_at: PROCESS_STARTED_AT,
+      uptime_ms: Math.floor(process.uptime() * 1e3),
+      memory: process.memoryUsage(),
+      sessions: { active: sessionsActive },
+      extension: {
+        connected: extensionStatus?.connected ?? false,
+        ...extensionStatus?.lastSeenAt ? { last_seen_at: extensionStatus.lastSeenAt } : {}
+      }
+    });
+  });
   router.post("/diagnostics/doctor", (req, res) => {
     let sessionId;
     if (req.body !== void 0) {
@@ -4826,6 +4977,16 @@ var TOOL_DEFINITIONS = [
       corePath: "/artifacts/screenshot"
     }
   },
+  {
+    name: "health_check",
+    config: {
+      title: "Health Check",
+      description: "Check server health including uptime, memory usage, active session count, and extension connection status.",
+      inputSchema: HealthCheckInputSchema,
+      outputSchema: envelope(HealthCheckOutputSchema),
+      corePath: "/health_check"
+    }
+  },
   {
     name: "diagnostics.doctor",
     config: {
@@ -4870,6 +5031,8 @@ var registerBrowserBridgeTools = (server, client) => {
 // packages/mcp-adapter/src/server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+var import_types = require("@modelcontextprotocol/sdk/types.js");
 var DEFAULT_SERVER_NAME = "browser-bridge";
 var DEFAULT_SERVER_VERSION = "0.0.0";
 var createMcpServer = (options = {}) => {