fix: harden bridge release and MCP handling

Author: DeliciousBuding

.github/workflows/ci.yml

@@ -14,6 +14,9 @@ jobs:
       - uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
       - name: Vet
         shell: bash
         run: go vet ./...
@@ -29,6 +32,21 @@ jobs:
       - name: Build
         shell: bash
         run: go build -trimpath -ldflags "-s -w" -o bin/codex-browser-bridge.exe ./cmd/bridge
+      - name: Check npm package contents
+        shell: bash
+        run: |
+          cd npm
+          npm pack --dry-run --json > pack.json
+          node - <<'NODE'
+          const fs = require("fs");
+          const pack = JSON.parse(fs.readFileSync("pack.json", "utf8"))[0];
+          const files = new Set(pack.files.map((f) => f.path));
+          for (const required of ["package.json", "scripts/install.js", "bin/codex-browser-bridge.js"]) {
+            if (!files.has(required)) {
+              throw new Error(`npm package is missing ${required}`);
+            }
+          }
+          NODE
 
   lint:
     runs-on: windows-latest

.github/workflows/release.yml

@@ -4,6 +4,10 @@ on:
   push:
     tags: ["v*"]
   workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag, for example v1.5.1"
+        required: true
 
 permissions:
   contents: write
@@ -22,7 +26,14 @@ jobs:
 
       - name: Get version
         id: version
-        run: echo "tag=${{ github.ref_name }}" >> $env:GITHUB_OUTPUT
+        shell: bash
+        run: |
+          TAG="${{ github.event.inputs.tag || github.ref_name }}"
+          if [[ ! "$TAG" =~ ^v[0-9]+(\.[0-9]+){1,2}([-+][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Invalid release tag: $TAG" >&2
+            exit 1
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
 
       - name: Build
         shell: bash

.gitignore

@@ -1,6 +1,9 @@
 # Binaries
 *.exe
 bin/
+!npm/bin/
+!npm/bin/codex-browser-bridge.js
+npm/bin/codex-browser-bridge
 /bridge
 /codex-browser-bridge
 

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.5.1] - 2026-06-09
+
+### Fixed
+
+- Serialized per-tab CDP detach, attach, and execute sequences to prevent concurrent actions on the same tab from detaching each other.
+- `codex_click` now returns an error when the selector is missing instead of reporting success after a JavaScript exception.
+- `codex_dom_click` now rejects short `DOM.getBoxModel` content arrays instead of panicking.
+- `codex_wait_for_load` now retries transient navigation-time CDP errors until the timeout.
+- Pipe discovery now ignores the bare `codex-browser-use` namespace entry and only returns concrete pipe names.
+- MCP JSON-RPC handling now ignores notifications, rejects malformed request envelopes, rejects zero-length frames, and validates required tool arguments before opening pipe calls.
+- The npm package now uses a committed JavaScript command wrapper, downloads release assets for the package version instead of `latest`, rejects unsupported CPU architectures, and checks package contents in CI.
+- Manual release workflow runs now require a valid `v*` release tag.
+
 ## [1.5.0] - 2026-06-05
 
 ### Fixed
@@ -61,13 +74,13 @@ All notable changes to this project will be documented in this file.
 ### Changed
 
 - `codex_dom_get_visible` description clarified: returns human-readable DOM tree (not node IDs); use `codex_dom_snapshot` for accessibility node IDs usable with `codex_dom_click`
-- `codex_screenshot` `fullPage` parameter documented as reserved (not yet implemented — always captures viewport)
+- `codex_screenshot` `fullPage` parameter documented as reserved (not yet implemented, always captures viewport)
 
 ## [0.2.0] - 2026-05-16
 
 ### Added
 - `codex_navigate_back` and `codex_navigate_forward` MCP tools (history navigation was already in the client; now exposed)
-- `codex_wait_for_load` MCP tool — polls `document.readyState` until `complete` or timeout
+- `codex_wait_for_load` MCP tool: polls `document.readyState` until `complete` or timeout
 - `codex_screenshot` now returns MCP `image` content so agents can view the screenshot directly (previously only base64 text)
 - `MCPServer.SetVersion` so the build version flows into the MCP `initialize` handshake (`serverInfo.version`)
 - Unit tests across `protocol`, `client`, `discovery`, and `mcp` packages

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thanks for taking the time to contribute. This is a small project — issues and PRs are both welcome.
+Thanks for taking the time to contribute. This is a small project, and issues and PRs are both welcome.
 
 ## Reporting bugs
 
@@ -13,7 +13,7 @@ Please open an issue using the bug report template. Include:
 
 ## Reporting security issues
 
-See [SECURITY.md](SECURITY.md) — please don't file these as public issues.
+See [SECURITY.md](SECURITY.md). Please don't file these as public issues.
 
 ## Development setup
 
@@ -32,11 +32,11 @@ make build
 make test
 ```
 
-The full test suite is hermetic — it uses `net.Pipe` to simulate the Codex pipe, so you don't need Codex Desktop running to run `go test ./...`.
+The full test suite is hermetic. It uses `net.Pipe` to simulate the Codex pipe, so you don't need Codex Desktop running to run `go test ./...`.
 
 ## Code style
 
-- Run `gofmt`/`goimports` before committing — CI enforces this.
+- Run `gofmt`/`goimports` before committing. CI enforces this.
 - `make test` runs `go vet ./...` and `go test -race -cover ./...`.
 - `golangci-lint run` is wired into CI; install it locally with [the official instructions](https://golangci-lint.run/usage/install/) and run it before pushing.
 
@@ -50,18 +50,18 @@ The full test suite is hermetic — it uses `net.Pipe` to simulate the Codex pip
 
 - Branch from `main`.
 - Reference the related issue in the PR description, if any.
-- Add or update tests for behavior changes. The wire-format invariants in `internal/client/browser_rpc_test.go` exist because we discovered them the hard way — please don't break them silently.
+- Add or update tests for behavior changes. The wire-format invariants in `internal/client/browser_rpc_test.go` exist because previous regressions were hard to diagnose. Please don't break them silently.
 - Update `CHANGELOG.md` under `## [Unreleased]`.
 - Update both `README.md` and `README.zh-CN.md` if you add or remove tools.
 
 ## Adding a new MCP tool
 
 There are typically four places to touch:
 
-1. `internal/client/browser.go` — add the client method. If it's a CDP-based tool, use `cdpWithAttach` so the debugger is attached first.
-2. `internal/mcp/server.go` — register the tool in `registerTools()` and add a handler that returns `[]Content`.
-3. `internal/client/browser_rpc_test.go` — lock in the wire format with a `withRecordingServer`-based test.
-4. `internal/mcp/handlers_test.go` — add an integration test that exercises the full client → handler path.
+1. `internal/client/browser.go`: add the client method. If it's a CDP-based tool, use `cdpWithAttach` so the debugger is attached first.
+2. `internal/mcp/server.go`: register the tool in `registerTools()` and add a handler that returns `[]Content`.
+3. `internal/client/browser_rpc_test.go`: lock in the wire format with a `withRecordingServer`-based test.
+4. `internal/mcp/handlers_test.go`: add an integration test that exercises the full client-to-handler path.
 
 Then update the count in `internal/mcp/server_test.go:TestRegisteredToolCount` and document the tool in both READMEs.
 

README.md

@@ -54,9 +54,12 @@ Useful when an agent needs to work with pages that require a real browser sessio
 
 ## Status
 
-Experimental.
+Version 1.5.1 is a local Windows tool for Codex Desktop and the Codex Chrome Extension. It supports both known Codex browser pipe name formats:
 
-The current version is designed for local Windows environments where Codex Desktop and the Codex Chrome Extension are already installed and running.
+- `codex-browser-use-<uuid>`
+- `codex-browser-use\<uuid>`
+
+The bridge is still intended for local development and controlled automation, not remote or multi-user deployment.
 
 ## Features
 
@@ -116,7 +119,7 @@ make build
 The binary will be generated at:
 
 ```text
-bin/codex-browser-bridge
+bin/codex-browser-bridge.exe
 ```
 
 ## Quick Start with Claude Code
@@ -253,7 +256,7 @@ quit
 
 | Tool                    | Description                                  |
 | ----------------------- | -------------------------------------------- |
-| `codex_screenshot`      | Capture a screenshot (returns MCP image). `fullPage` parameter is reserved for future implementation — currently always captures the viewport. |
+| `codex_screenshot`      | Capture a screenshot (returns MCP image). `fullPage` is reserved for a future release. The current implementation captures the viewport. |
 | `codex_dom_snapshot`    | Get an accessibility tree snapshot           |
 | `codex_dom_get_visible` | Get a simplified visible DOM tree (human-readable; use codex_dom_snapshot for node IDs usable with codex_dom_click) |
 | `codex_evaluate`        | Evaluate JavaScript in the page context      |
@@ -375,11 +378,11 @@ make clean         # remove build output
 
 ## Roadmap
 
-Possible next steps:
+Planned or open work:
 
-- richer error messages for common pipe / extension failures
+- clearer error messages for common pipe / extension failures
 - non-Windows fallback or explicit platform guards
-- better screenshot output handling for MCP clients
+- screenshot output handling across MCP clients
 - typed tool result schemas
 - optional allowlist / confirmation layer for sensitive domains
 - examples for Claude Code, Cursor, Codex CLI, and other MCP clients

README.zh-CN.md

@@ -54,9 +54,12 @@ Agent 因此可以：
 
 ## 状态
 
-实验性。
+v1.5.1 是面向本地 Windows 的工具，需要 Codex Desktop 和 Codex Chrome 扩展已安装并运行。当前版本支持两种已知的 Codex 浏览器 pipe 名称格式：
 
-当前版本专为本地 Windows 环境设计，需要已安装并运行 Codex Desktop 和 Codex Chrome 扩展。
+- `codex-browser-use-<uuid>`
+- `codex-browser-use\<uuid>`
+
+桥接器仍然只适合本地开发和受控自动化，不适合作为远程服务或多人共享服务部署。
 
 ## 特性
 
@@ -105,7 +108,7 @@ https://github.com/DeliciousBuding/codex-browser-bridge/releases
 
 将 `codex-browser-bridge.exe` 放到 `PATH` 中的任意位置。
 
-### 方式三：从源码构建
+### 方式四：从源码构建
 
 ```bash
 git clone https://github.com/DeliciousBuding/codex-browser-bridge.git
@@ -233,7 +236,7 @@ info          ping          try <method> [json]   quit
 
 | 工具 | 说明 |
 |------|------|
-| `codex_screenshot` | 截取页面截图（返回 MCP image 内容）。`fullPage` 参数保留供未来实现——当前始终截取视口。 |
+| `codex_screenshot` | 截取页面截图（返回 MCP image 内容）。`fullPage` 参数保留给后续版本，当前实现截取视口。 |
 | `codex_dom_snapshot` | 获取无障碍树快照 |
 | `codex_dom_get_visible` | 获取简化版可见 DOM 树（人类可读；如需可用于 codex_dom_click 的节点 ID，请使用 codex_dom_snapshot） |
 | `codex_evaluate` | 在页面上下文中执行 JavaScript |
@@ -303,7 +306,7 @@ Chrome 标签页
 - 不要为不受信任的 MCP 客户端运行
 - 在允许敏感操作前检查 Agent 的行为
 - 避免在包含密码、支付信息、私有令牌或生产管理后台的页面上使用
-- 请记住被接管的标签页可能已经登录
+- 被接管的标签页可能已经登录，请按已登录会话处理
 
 本项目仅用于本地开发和受控自动化。
 
@@ -344,11 +347,11 @@ make build
 
 ## 路线图
 
-可能的下一步：
+计划或待处理工作：
 
-- 更丰富的错误信息（pipe / 扩展常见故障）
+- 更清晰的错误信息（pipe / 扩展常见故障）
 - 非 Windows 平台的回退或明确平台限制
-- 更好的截图输出处理
+- 面向不同 MCP 客户端的截图输出处理
 - 类型化的工具结果 schema
 - 敏感域名的可选白名单 / 确认层
 - Claude Code、Cursor、Codex CLI 等 MCP 客户端的使用示例