tabbridge-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TabBridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# TabBridge
+
+English · [简体中文](README.zh-CN.md)
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+TabBridge is a CLI tool and Skill designed for AI Agents: after user authorization, it allows AI agents to operate on **tabs you already have open** in your real browser through a browser extension—instead of launching a fresh browser instance like Playwright, Puppeteer, or Agent Browser.
+
+## Core Positioning
+
+> Don't open a new browser instance. Connect the agent to your already-open tabs and let AI seamlessly take over.
+
+Traditional browser automation tools spin up a new browser process, which means:
+
+- Already-logged-in accounts must log in again
+- Cookies, localStorage, and session state are lost
+- Additional authentication steps are required (SMS, 2FA, QR code scans)
+
+TabBridge is different: it takes over **tabs that are already running in your real browser**, letting AI continue working within your existing session.
+
+## Why TabBridge
+
+| Capability | Playwright / Puppeteer / Agent Browser | TabBridge |
+|------------|----------------------------------------|-----------|
+| Target | Fresh browser instance | Your already-open tabs |
+| Login state | Must re-authenticate | Inherits current session |
+| Deployment | Needs browser driver or remote infra | Local CLI + browser extension |
+| AI-friendliness | Raw HTML, high token cost | Structured Snapshot, token-efficient |
+| Dangerous actions | Usually none | Coordinate actions require user confirmation |
+
+## Key Features
+
+- **Session takeover**: connect to the currently active tab or any already-open tab.
+- **AI-friendly Snapshot**: converts a page into a structured semantic view with interactive element refs (`@e1`, `@e2`…), helping large models understand pages faster while consuming fewer tokens.
+- **Ref-based actions**: perform `click`, `fill`, `type`, `select`, `check`, and more using semantic refs from the latest snapshot.
+- **Fine-grained permissions**: explicit user authorization is required before reading or acting; grants expire after 30 minutes and re-authorization is needed when a tab navigates to a different origin. Approval requests shown in the extension popup expire after 5 minutes if not acted on.
+- **High-risk action confirmation**: coordinate actions (`click-coordinates`, `drag-coordinates`) must be manually confirmed in the browser extension popup.
+- **Local-first**: the CLI communicates with the browser extension through a local WebSocket broker, with no reliance on cloud browser farms.
+
+## Architecture Overview
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                     AI Agent (via Skill)                     │
+│                  invokes `tabbridge` commands                │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ process spawn
+┌───────────────────────────▼─────────────────────────────────┐
+│                    TabBridge CLI (Node.js)                   │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ WebSocket
+┌───────────────────────────▼─────────────────────────────────┐
+│                      TabBridge Broker                        │
+│                 (local WebSocket server)                     │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ WebSocket
+┌───────────────────────────▼─────────────────────────────────┐
+│                   Chrome Extension                           │
+│       (offscreen document + content script + popup)          │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+┌───────────────────────────▼─────────────────────────────────┐
+│                   User's Webpage                             │
+│                 (already-open tab)                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+The first `tabbridge` command automatically starts the local broker; you do not need to run it manually.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js (LTS recommended)
+- Chrome / Chromium 116+
+- macOS, Windows, or Linux
+
+### 1. Install the CLI
+
+```bash
+npm install -g tabbridge-cli
+```
+
+After installation, the `tabbridge` command is available globally.
+
+### 2. Install the browser extension
+
+> The extension is not yet on the Chrome Web Store. Until it is published, you need to build and load it manually from source.
+
+Clone the repository, install workspace dependencies from the monorepo root, build the extension with WXT, and load it into Chrome:
+
+```bash
+pnpm install
+pnpm --filter @tabbridge/chrome-extension build
+```
+
+Then open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select `packages/chrome-extension/dist/chrome-mv3/` (the directory that contains `manifest.json`).
+
+When you run `tabbridge tabs request-access`, approve the site in the extension popup. You can also revoke or manage access later in the extension details page.
+
+Note: the extension popup UI is currently in Chinese. Approval buttons are 允许 (Allow), 允许一次 (Allow once), and 拒绝 (Deny).
+
+For development, run `pnpm --filter @tabbridge/chrome-extension dev`; WXT outputs to `packages/chrome-extension/dist/chrome-mv3-dev/`.
+
+### 3. Connect and operate a page
+
+Make sure the active tab is a normal `http://` or `https://` page. Internal Chrome pages, extension pages, file URLs, and `about:` pages are not supported in the current version.
+
+```bash
+# Check connection status
+tabbridge status --json
+
+# List controllable tabs
+tabbridge tabs list --json
+
+# Connect to the currently active tab
+tabbridge connect --json
+
+# Request access to the page
+tabbridge tabs request-access --tab <tabId> --reason "Read page content" --json
+
+# Get an AI-friendly snapshot (`-i` is accepted for compatibility but ignored)
+tabbridge snapshot -i --json
+
+# Perform an action
+tabbridge click @e1 --json
+```
+
+## Snapshot: A Page View Optimized for LLMs
+
+`tabbridge snapshot` does not dump the entire DOM to the model. Instead, it generates a compact semantic representation:
+
+```text
+Page: Example
+URL: https://example.com
+
+@e1 [button] "Save"
+@e2 [textbox] placeholder="Comment"
+```
+
+Each `@eN` ref is a temporary label for the current snapshot. The AI can use it to precisely refer to elements without parsing verbose HTML or CSS selectors. Refs are volatile and reassigned on every snapshot, ensuring actions are always based on the latest page state.
+
+## Security & Approval Boundaries
+
+TabBridge puts the security of your browser context first:
+
+- **Site authorization**: each origin requires separate user approval.
+- **Session isolation**: no extraction of cookies, localStorage, credentials, or tokens.
+- **No arbitrary code execution**: injecting arbitrary JavaScript or intercepting network traffic is not allowed.
+- **High-risk confirmation**: coordinate actions require confirmation through the browser extension popup.
+- **No silent fallback**: ref actions are never silently replaced by coordinate actions.
+- **No secrets in argv**: never pass passwords, 2FA codes, payment details, credentials, or tokens as CLI arguments. Use `type --text-stdin` / `fill --text-stdin` for sensitive input.
+
+## Project Structure
+
+```text
+tabbridge/
+├── packages/
+│   ├── cli/              # TabBridge CLI (the `tabbridge` command)
+│   ├── chrome-extension/ # Chrome / Chromium browser extension
+│   ├── broker/           # Local WebSocket bridge service
+│   └── shared/           # Shared types and error codes
+├── skills/
+│   └── tabbridge/        # Claude Skill and reference docs
+└── docs/                 # Design documents
+```
+
+## Development
+
+```bash
+pnpm test        # run the full test suite
+pnpm typecheck   # run TypeScript checks
+pnpm lint        # run lint / type checks across packages
+pnpm clean       # remove build artifacts
+```
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,177 @@
+# TabBridge
+
+简体中文 · [English](README.md)
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+
+TabBridge 是一款为 AI Agent 设计的 CLI 工具与 Skill：在获得用户授权后，它能让 AI 直接操作你**当前已经打开的浏览器页面**，通过浏览器插件而不是像 Playwright、Puppeteer 或 Agent Browser 那样启动一个全新的浏览器实例。
+
+## 核心定位
+
+> 不是新开一个浏览器实例，而是连接 Agent 与你已打开的网页，让 AI 无缝接手。
+
+传统的浏览器自动化工具会新开一个浏览器进程或实例，导致：
+
+- 已经登录的账号需要重新登录
+- Cookie、localStorage、会话状态全部丢失
+- 需要额外的认证流程（短信、2FA、扫码）
+
+TabBridge 不同：它接管你**真实浏览器中正在运行的标签页**，让 AI 在你的现有会话上继续工作。
+
+## 为什么是 TabBridge
+
+| 能力 | Playwright / Puppeteer / Agent Browser | TabBridge |
+|------|----------------------------------------|-----------|
+| 操作对象 | 新开的浏览器实例 | 用户已打开的页面 |
+| 登录态 | 需要重新登录 | 继承当前会话 |
+| 部署方式 | 需要浏览器驱动或远程环境 | 本地 CLI + 浏览器插件 |
+| 对 AI 友好度 | 原始 HTML，Token 消耗大 | 结构化 Snapshot，更省 Token |
+| 危险操作审核 | 通常无 | 坐标类等高危操作需用户确认 |
+
+## 主要特性
+
+- **会话接管**：连接当前激活的标签页，或指定任意已打开的标签页。
+- **AI 友好的 Snapshot**：将网页转换为结构化的语义视图，包含可交互元素引用（`@e1`、`@e2`…），让大模型更快理解页面，显著减少 Token 消耗。
+- **Ref-based 操作**：基于 Snapshot 中的语义引用执行 `click`、`fill`、`type`、`select`、`check` 等操作。
+- **细粒度权限控制**：读取页面、执行动作前需要用户显式授权；授权在 30 分钟后过期，且网页切换 origin 后需重新授权。浏览器插件弹窗中的授权请求若 5 分钟内未处理将会过期。
+- **高危操作确认**：坐标类操作（`click-coordinates`、`drag-coordinates`）必须通过浏览器插件弹窗手动确认。
+- **本地优先**：CLI 经本地 Broker 与浏览器插件建立 WebSocket 通信，不依赖云端浏览器集群。
+
+## 架构概览
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                      AI Agent（via Skill）                    │
+│                   调用 `tabbridge` 命令行                     │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ 进程调用
+┌───────────────────────────▼─────────────────────────────────┐
+│                   TabBridge CLI（Node.js）                   │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ WebSocket
+┌───────────────────────────▼─────────────────────────────────┐
+│                       TabBridge Broker                       │
+│                  （本地 WebSocket 服务）                      │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ WebSocket
+┌───────────────────────────▼─────────────────────────────────┐
+│                      Chrome Extension                        │
+│           （离屏文档 + 内容脚本 + 浏览器弹窗）                 │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+┌───────────────────────────▼─────────────────────────────────┐
+│                        用户已打开的网页                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+首次运行任意 `tabbridge` 命令会自动启动本地 Broker，无需手动启动。
+
+## 快速开始
+
+### 前置条件
+
+- Node.js（建议使用 LTS）
+- Chrome / Chromium 116+
+- macOS、Windows 或 Linux
+
+### 1. 安装 CLI
+
+```bash
+npm install -g tabbridge-cli
+```
+
+安装完成后，`tabbridge` 命令即可全局使用。
+
+### 2. 安装浏览器插件
+
+> 扩展目前尚未上架 Chrome Web Store。在上架之前，你需要从源码构建并手动加载。
+
+克隆仓库，在 monorepo 根目录安装 workspace 依赖，使用 WXT 构建并加载到 Chrome：
+
+```bash
+pnpm install
+pnpm --filter @tabbridge/chrome-extension build
+```
+
+然后打开 `chrome://extensions`，开启**开发者模式**，点击**加载已解压的扩展**，选择 `packages/chrome-extension/dist/chrome-mv3/`（包含 `manifest.json` 的目录）。
+
+运行 `tabbridge tabs request-access` 后，在扩展弹窗中批准站点访问。也可以稍后在扩展详情页的站点访问中管理。
+
+开发时请运行 `pnpm --filter @tabbridge/chrome-extension dev`；WXT 会输出到 `packages/chrome-extension/dist/chrome-mv3-dev/`。
+
+### 3. 连接并操作页面
+
+请确保当前标签页是正常的 `http://` 或 `https://` 页面。当前版本不支持 Chrome 内部页面、扩展页面、文件 URL 和 `about:` 页面。
+
+```bash
+# 检查连接状态
+tabbridge status --json
+
+# 列出可操作的标签页
+tabbridge tabs list --json
+
+# 连接到当前激活的标签页
+tabbridge connect --json
+
+# 请求页面访问授权
+tabbridge tabs request-access --tab <tabId> --reason "读取页面内容" --json
+
+# 获取 AI 友好的 Snapshot（`-i` 为兼容参数，可忽略）
+tabbridge snapshot -i --json
+
+# 执行操作
+tabbridge click @e1 --json
+```
+
+## Snapshot：为 AI 大模型优化的页面视图
+
+`tabbridge snapshot` 不会把整个 DOM dump 给模型，而是生成一个紧凑的语义表示：
+
+```text
+Page: Example
+URL: https://example.com
+
+@e1 [button] "Save"
+@e2 [textbox] placeholder="Comment"
+```
+
+每个 `@eN` 引用都是当前快照下的临时标签，AI 可以用它精确地指代元素，而无需处理冗长的 HTML 或 CSS 选择器。引用具有易变性，每次快照都会重新分配，确保操作始终基于最新页面状态。
+
+## 安全与审批边界
+
+TabBridge 将用户浏览器上下文的安全放在首位：
+
+- **站点授权**：每个 origin 都需要用户单独授权。
+- **会话隔离**：不提取 Cookie、localStorage、凭证或 Token。
+- **无任意代码执行**：禁止注入任意 JavaScript 或拦截网络请求。
+- **高危操作确认**：坐标类操作必须经浏览器插件弹窗确认后才能执行。
+- **无静默降级**：不会把 ref 操作静默替换为坐标操作。
+- **不在命令行传 secrets**：永远不要把密码、2FA 码、支付信息、凭证或 Token 放在 CLI 参数里。敏感输入请使用 `type --text-stdin` / `fill --text-stdin`。
+
+## 项目结构
+
+```text
+tabbridge/
+├── packages/
+│   ├── cli/              # TabBridge CLI（tabbridge 命令）
+│   ├── chrome-extension/ # Chrome / Chromium 浏览器插件
+│   ├── broker/           # 本地 WebSocket 桥接服务
+│   └── shared/           # 共享类型与错误码
+├── skills/
+│   └── tabbridge/        # Claude Skill 与使用参考
+└── docs/                 # 设计文档
+```
+
+## 开发
+
+```bash
+pnpm test        # 运行完整测试套件
+pnpm typecheck   # 运行 TypeScript 检查
+pnpm lint        # 运行各包的 lint / 类型检查
+pnpm clean       # 清理构建产物
+```
+
+## 许可证
+
+[MIT](LICENSE)

package/broker.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+// src/runtime.ts
+import crypto from "crypto";
+import fs from "fs/promises";
+import path from "path";
+import envPaths from "env-paths";
+
+// ../shared/dist/index.js
+var ERROR_CODES = [
+  "EXTENSION_NOT_CONNECTED",
+  "BRIDGE_SOCKET_UNAVAILABLE",
+  "BRIDGE_REQUEST_TIMEOUT",
+  "TAB_NOT_FOUND",
+  "TAB_NOT_AUTHORIZED",
+  "TAB_NOT_ACTIVE_FOR_SCREENSHOT",
+  "HOST_PERMISSION_DENIED",
+  "USER_APPROVAL_REQUIRED",
+  "APPROVAL_EXPIRED",
+  "APPROVAL_TIMEOUT",
+  "UNSUPPORTED_PAGE",
+  "FRAME_NOT_ACCESSIBLE",
+  "FRAME_ORIGIN_NOT_AUTHORIZED",
+  "SNAPSHOT_REQUIRED",
+  "REF_STALE",
+  "ELEMENT_NOT_VISIBLE",
+  "ELEMENT_DISABLED",
+  "ELEMENT_SCOPE_TOO_LARGE",
+  "ACTION_REQUIRES_CONFIRMATION",
+  "ACTION_NOT_SUPPORTED_IN_EXTENSION_MODE",
+  "USER_DENIED",
+  "MESSAGE_TOO_LARGE",
+  "PROTOCOL_VERSION_MISMATCH",
+  "BROWSER_COMMAND_TIMEOUT",
+  "EXTENSION_ID_MISMATCH"
+];
+var JSON_RPC_TABBRIDGE_ERROR_BASE = -32e3;
+var TAB_BRIDGE_ERROR_CODE_INDEX = Object.fromEntries(
+  ERROR_CODES.map((code, index) => [code, index])
+);
+function tabBridgeErrorToJsonRpc(error) {
+  return {
+    code: JSON_RPC_TABBRIDGE_ERROR_BASE - TAB_BRIDGE_ERROR_CODE_INDEX[error.code],
+    message: error.code,
+    data: error
+  };
+}
+var JSON_RPC_VERSION = "2.0";
+function createJsonRpcSuccess(id, result) {
+  return { jsonrpc: JSON_RPC_VERSION, id, result };
+}
+function createJsonRpcError(id, error) {
+  return { jsonrpc: JSON_RPC_VERSION, id, error };
+}
+var NATIVE_HOST_TO_CHROME_MAX_BYTES = 1024 * 1024;
+var CHROME_TO_NATIVE_HOST_MAX_BYTES = 64 * 1024 * 1024;
+var SNAPSHOT_DEFAULT_MAX_BYTES = 256 * 1024;
+var TEXT_DEFAULT_MAX_BYTES = 128 * 1024;
+var HTML_DEFAULT_MAX_BYTES = 64 * 1024;
+var GRANT_TTL_MS = 30 * 6e4;
+var BROKER_PORT = 9876;
+
+// src/runtime.ts
+function defaultSupportDir() {
+  return envPaths("tabbridge", { suffix: "" }).data;
+}
+function createRuntimePaths(supportDir) {
+  const dir = supportDir ?? defaultSupportDir();
+  return {
+    supportDir: dir,
+    tokenPath: path.join(dir, "broker-token"),
+    lockPath: path.join(dir, "broker.lock")
+  };
+}
+async function ensureSupportDir(paths) {
+  await fs.mkdir(paths.supportDir, { recursive: true, mode: 448 });
+  await fs.chmod(paths.supportDir, 448);
+}
+function generateToken() {
+  return crypto.randomBytes(32).toString("hex");
+}
+async function writeToken(paths, token) {
+  await fs.writeFile(paths.tokenPath, `${token}
+`, { mode: 384 });
+  await fs.chmod(paths.tokenPath, 384);
+}
+
+// src/lock.ts
+import lockfile from "proper-lockfile";
+async function acquireBrokerLock(lockPath) {
+  return await lockfile.lock(lockPath, {
+    stale: 5e3,
+    update: 2e3,
+    retries: 0
+  });
+}
+
+// src/server.ts
+import { WebSocket, WebSocketServer } from "ws";
+var STANDARD_ERRORS = {
+  parseError: { code: -32700, message: "Parse error" },
+  invalidRequest: { code: -32600, message: "Invalid Request" },
+  methodNotFound: { code: -32601, message: "Method not found" },
+  internalError: { code: -32603, message: "Internal error" },
+  duplicatePendingRequest: { code: -32600, message: "Duplicate pending request id" }
+};
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isAuthMessage(value) {
+  return isRecord(value) && ("token" in value || "role" in value);
+}
+function looksLikeResponse(value) {
+  return typeof value.id === "string" && ("result" in value || "error" in value);
+}
+var BrokerServer = class {
+  constructor(options) {
+    this.options = options;
+    this.wss = new WebSocketServer({ port: options.port });
+    this.port = this.wss.address().port;
+    this.wss.on("connection", (socket, req) => this.handleConnection(socket, req));
+  }
+  options;
+  wss;
+  clients = /* @__PURE__ */ new Set();
+  extensionClient;
+  pending = /* @__PURE__ */ new Map();
+  hello;
+  port;
+  status() {
+    return {
+      cliConnected: [...this.clients].some((c) => c.role === "cli"),
+      extensionConnected: this.extensionClient !== void 0 && this.extensionClient.socket.readyState === WebSocket.OPEN,
+      extensionHello: this.hello
+    };
+  }
+  handleConnection(socket, req) {
+    const client = { socket, authenticated: false };
+    this.clients.add(client);
+    const authTimeout = setTimeout(() => {
+      if (!client.authenticated) socket.close();
+    }, 5e3);
+    socket.on("message", async (data) => {
+      try {
+        await this.handleMessage(client, data, req.headers.origin);
+      } catch {
+        socket.send(JSON.stringify(createJsonRpcError("unknown", STANDARD_ERRORS.internalError)));
+      }
+    });
+    socket.on("close", () => {
+      clearTimeout(authTimeout);
+      this.clients.delete(client);
+      if (this.extensionClient === client) {
+        this.extensionClient = void 0;
+        this.hello = void 0;
+        this.failAllPending(extensionNotConnectedError());
+      } else {
+        this.clearPendingForClient(client);
+      }
+    });
+  }
+  async handleMessage(client, data, origin) {
+    let parsed;
+    try {
+      parsed = JSON.parse(data.toString("utf8"));
+    } catch {
+      client.socket.send(JSON.stringify(createJsonRpcError("unknown", STANDARD_ERRORS.parseError)));
+      return;
+    }
+    if (!client.authenticated) {
+      if (!isAuthMessage(parsed)) {
+        client.socket.close();
+        return;
+      }
+      if (parsed.token === this.options.token) {
+        client.authenticated = true;
+        client.role = "cli";
+      } else if (parsed.role === "extension" && typeof origin === "string" && origin.startsWith("chrome-extension://")) {
+        client.authenticated = true;
+        client.role = "extension";
+        this.extensionClient = client;
+      } else {
+        client.socket.close();
+      }
+      return;
+    }
+    if (!isRecord(parsed)) return;
+    if (client.role === "extension") {
+      if (client !== this.extensionClient) return;
+      if (looksLikeResponse(parsed)) {
+        const pendingRequest = this.pending.get(parsed.id);
+        if (pendingRequest) {
+          this.clearPendingRequest(parsed.id, pendingRequest);
+          pendingRequest.client.socket.send(JSON.stringify(parsed));
+        }
+        return;
+      }
+      if (parsed.method === "broker.hello") {
+        this.hello = parsed.params;
+        client.socket.send(JSON.stringify(createJsonRpcSuccess(String(parsed.id), { ok: true })));
+      }
+      return;
+    }
+    const request = parsed;
+    if (request.jsonrpc !== "2.0" || typeof request.method !== "string" || typeof request.id !== "string") {
+      client.socket.send(JSON.stringify(createJsonRpcError(String(request.id ?? "unknown"), STANDARD_ERRORS.invalidRequest)));
+      return;
+    }
+    if (!this.extensionClient || this.extensionClient.socket.readyState !== WebSocket.OPEN) {
+      this.sendJsonRpcError(client, request.id, tabBridgeErrorToJsonRpc(extensionNotConnectedError()));
+      return;
+    }
+    if (this.pending.has(request.id)) {
+      this.sendJsonRpcError(client, request.id, STANDARD_ERRORS.duplicatePendingRequest);
+      return;
+    }
+    const requestId = request.id;
+    const timer = setTimeout(() => {
+      const pendingRequest = this.pending.get(requestId);
+      if (!pendingRequest) return;
+      this.clearPendingRequest(requestId, pendingRequest);
+      this.sendJsonRpcError(pendingRequest.client, requestId, tabBridgeErrorToJsonRpc(requestTimeoutError()));
+    }, this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+    this.pending.set(requestId, { client, timer });
+    this.extensionClient.socket.send(JSON.stringify(request));
+  }
+  clearPendingRequest(id, pendingRequest) {
+    clearTimeout(pendingRequest.timer);
+    this.pending.delete(id);
+  }
+  clearPendingForClient(client) {
+    for (const [id, pendingRequest] of this.pending) {
+      if (pendingRequest.client === client) this.clearPendingRequest(id, pendingRequest);
+    }
+  }
+  failAllPending(error) {
+    for (const [id, pendingRequest] of this.pending) {
+      this.clearPendingRequest(id, pendingRequest);
+      this.sendJsonRpcError(pendingRequest.client, id, tabBridgeErrorToJsonRpc(error));
+    }
+  }
+  sendJsonRpcError(client, id, error) {
+    client.socket.send(JSON.stringify(createJsonRpcError(id, error)));
+  }
+  close() {
+    return new Promise((resolve) => {
+      for (const [id, pendingRequest] of this.pending) {
+        this.clearPendingRequest(id, pendingRequest);
+      }
+      this.wss.close(() => resolve());
+      for (const client of this.clients) {
+        client.socket.terminate();
+      }
+    });
+  }
+};
+function extensionNotConnectedError() {
+  return {
+    code: "EXTENSION_NOT_CONNECTED",
+    message: "The TabBridge extension is not connected.",
+    recoverable: true,
+    suggestedCommand: "Open Chrome and click the TabBridge extension icon, then run tabbridge status --json."
+  };
+}
+function requestTimeoutError() {
+  return {
+    code: "BRIDGE_REQUEST_TIMEOUT",
+    message: "The TabBridge extension did not respond before the broker request timed out.",
+    recoverable: true,
+    suggestedCommand: "Retry the command. If it keeps timing out, open Chrome and restart the TabBridge extension."
+  };
+}
+
+// src/run-broker.ts
+import fs2 from "fs/promises";
+async function runBroker(pathsArg, port = BROKER_PORT) {
+  const paths = pathsArg ?? createRuntimePaths();
+  await ensureSupportDir(paths);
+  await fs2.writeFile(paths.lockPath, "", { mode: 384 });
+  const release = await acquireBrokerLock(paths.lockPath);
+  const token = generateToken();
+  await writeToken(paths, token);
+  const server = new BrokerServer({ port, token });
+  return {
+    port: server.port,
+    close: async () => {
+      await server.close();
+      await release();
+    }
+  };
+}
+
+// src/main.ts
+import path2 from "path";
+import { fileURLToPath } from "url";
+function isExecutedEntrypoint() {
+  if (!process.argv[1]) return false;
+  return fileURLToPath(import.meta.url) === path2.resolve(process.argv[1]);
+}
+if (isExecutedEntrypoint()) {
+  runBroker().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}

package/main.js

@@ -0,0 +1,599 @@
+#!/usr/bin/env node
+// ../shared/dist/index.js
+var ERROR_CODES = [
+  "EXTENSION_NOT_CONNECTED",
+  "BRIDGE_SOCKET_UNAVAILABLE",
+  "BRIDGE_REQUEST_TIMEOUT",
+  "TAB_NOT_FOUND",
+  "TAB_NOT_AUTHORIZED",
+  "TAB_NOT_ACTIVE_FOR_SCREENSHOT",
+  "HOST_PERMISSION_DENIED",
+  "USER_APPROVAL_REQUIRED",
+  "APPROVAL_EXPIRED",
+  "APPROVAL_TIMEOUT",
+  "UNSUPPORTED_PAGE",
+  "FRAME_NOT_ACCESSIBLE",
+  "FRAME_ORIGIN_NOT_AUTHORIZED",
+  "SNAPSHOT_REQUIRED",
+  "REF_STALE",
+  "ELEMENT_NOT_VISIBLE",
+  "ELEMENT_DISABLED",
+  "ELEMENT_SCOPE_TOO_LARGE",
+  "ACTION_REQUIRES_CONFIRMATION",
+  "ACTION_NOT_SUPPORTED_IN_EXTENSION_MODE",
+  "USER_DENIED",
+  "MESSAGE_TOO_LARGE",
+  "PROTOCOL_VERSION_MISMATCH",
+  "BROWSER_COMMAND_TIMEOUT",
+  "EXTENSION_ID_MISMATCH"
+];
+function bridgeNotConnectedError(state) {
+  if (state === "chrome_closed") {
+    return {
+      code: "EXTENSION_NOT_CONNECTED",
+      message: "Chrome is not connected to the TabBridge broker.",
+      recoverable: true,
+      suggestedCommand: "Open Chrome, confirm the TabBridge extension is enabled, then run tabbridge status --json."
+    };
+  }
+  return {
+    code: "EXTENSION_NOT_CONNECTED",
+    message: "The TabBridge extension service worker is not connected to the broker.",
+    recoverable: true,
+    suggestedCommand: "Open Chrome and click the TabBridge extension icon to start the broker, then run tabbridge status --json."
+  };
+}
+var TAB_BRIDGE_ERROR_CODE_INDEX = Object.fromEntries(
+  ERROR_CODES.map((code, index) => [code, index])
+);
+function jsonRpcErrorToTabBridgeError(error) {
+  const data = error.data;
+  if (typeof data !== "object" || data === null) return void 0;
+  const candidate = data;
+  if (typeof candidate.code === "string" && ERROR_CODES.includes(candidate.code) && typeof candidate.message === "string" && typeof candidate.recoverable === "boolean") {
+    return candidate;
+  }
+  return void 0;
+}
+var JSON_RPC_VERSION = "2.0";
+function createJsonRpcRequest(id, method, params) {
+  const req = { jsonrpc: JSON_RPC_VERSION, id, method };
+  if (params !== void 0) {
+    req.params = params;
+  }
+  return req;
+}
+var NATIVE_HOST_TO_CHROME_MAX_BYTES = 1024 * 1024;
+var CHROME_TO_NATIVE_HOST_MAX_BYTES = 64 * 1024 * 1024;
+var SNAPSHOT_DEFAULT_MAX_BYTES = 256 * 1024;
+var TEXT_DEFAULT_MAX_BYTES = 128 * 1024;
+var HTML_DEFAULT_MAX_BYTES = 64 * 1024;
+var GRANT_TTL_MS = 30 * 6e4;
+var APPROVAL_WAIT_DEFAULT_TIMEOUT_MS = 3e4;
+var BROKER_PORT = 9876;
+function okEnvelope(data) {
+  return { ok: true, data };
+}
+function errorEnvelope(error) {
+  return { ok: false, error };
+}
+
+// src/broker-client.ts
+import { WebSocket } from "ws";
+function closedBeforeResponseError() {
+  return errorEnvelope({
+    code: "BRIDGE_SOCKET_UNAVAILABLE",
+    message: "Broker closed the connection before sending a complete response.",
+    recoverable: true,
+    suggestedCommand: "tabbridge status --json"
+  });
+}
+function timeoutError() {
+  return errorEnvelope({
+    code: "BRIDGE_REQUEST_TIMEOUT",
+    message: "Timed out waiting for the broker response.",
+    recoverable: true,
+    suggestedCommand: "tabbridge status --json"
+  });
+}
+function protocolError(message) {
+  return errorEnvelope({
+    code: "PROTOCOL_VERSION_MISMATCH",
+    message,
+    recoverable: true,
+    suggestedCommand: "tabbridge status --json"
+  });
+}
+function parseResponse(request, raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return protocolError("Broker returned malformed JSON.");
+  }
+  if (parsed.id !== request.id) {
+    return protocolError(`Broker response id ${String(parsed.id)} did not match request id ${request.id}.`);
+  }
+  if ("result" in parsed && parsed.result !== void 0) {
+    return okEnvelope(parsed.result);
+  }
+  if ("error" in parsed && parsed.error !== void 0) {
+    const businessError = jsonRpcErrorToTabBridgeError(parsed.error);
+    if (businessError) return errorEnvelope(businessError);
+    const synthetic = {
+      code: "PROTOCOL_VERSION_MISMATCH",
+      message: parsed.error.message,
+      recoverable: true
+    };
+    return errorEnvelope(synthetic);
+  }
+  return protocolError("Broker returned an invalid JSON-RPC response.");
+}
+async function sendBrokerRequest(request, options) {
+  return await new Promise((resolve) => {
+    const ws = new WebSocket(options.url);
+    let settled = false;
+    const finish = (envelope) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      ws.terminate();
+      resolve(envelope);
+    };
+    const timer = setTimeout(() => finish(timeoutError()), options.timeoutMs);
+    ws.once("open", () => {
+      ws.send(JSON.stringify({ type: "auth", token: options.token }));
+      ws.send(JSON.stringify(request));
+    });
+    ws.once("error", () => finish(errorEnvelope(bridgeNotConnectedError("extension_asleep"))));
+    ws.once("close", () => {
+      if (!settled) finish(closedBeforeResponseError());
+    });
+    ws.on("message", (data) => {
+      const text = data.toString("utf8");
+      try {
+        const probe = JSON.parse(text);
+        if (probe.type === "auth") return;
+      } catch {
+      }
+      finish(parseResponse(request, text));
+    });
+  });
+}
+
+// src/cli.ts
+function isValueFlag(token) {
+  return token.startsWith("--") && token !== "--json" && token !== "--current" && token !== "--text-stdin";
+}
+function readFlag(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index < 0) return void 0;
+  const value = argv[index + 1];
+  if (value === void 0 || value.startsWith("--") || value === "-i") throw new Error(`${flag} requires a value`);
+  return value;
+}
+function hasFlag(argv, flag) {
+  return argv.includes(flag);
+}
+function readNumberFlag(argv, flag) {
+  const value = readFlag(argv, flag);
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) throw new Error(`${flag} must be an integer`);
+  return parsed;
+}
+function requireNumberFlag(argv, flag, command) {
+  const value = readNumberFlag(argv, flag);
+  if (value === void 0) throw new Error(`${command} requires ${flag}`);
+  return value;
+}
+function requireStringFlag(argv, flag, command) {
+  const value = readFlag(argv, flag);
+  if (!value) throw new Error(`${command} requires ${flag}`);
+  return value;
+}
+function positionalArgs(argv) {
+  const values = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token) continue;
+    if (token.startsWith("--")) {
+      if (isValueFlag(token)) index += 1;
+      continue;
+    }
+    if (token === "-i") continue;
+    values.push(token);
+  }
+  return values;
+}
+function parseRefAction(first, argv, json) {
+  const [, ref, value] = positionalArgs(argv);
+  if (!ref) throw new Error(`${first} requires a ref like @e1`);
+  const payload = { ref };
+  if (first === "select") {
+    if (!value) throw new Error("select requires a value");
+    payload.value = value;
+  }
+  return { command: `action.${first}`, json, payload };
+}
+function parseTextAction(first, argv, json) {
+  const [, ref, positionalText] = positionalArgs(argv);
+  if (!ref) throw new Error(`${first} requires a ref like @e1`);
+  const textFromStdin = hasFlag(argv, "--text-stdin");
+  const flagText = readFlag(argv, "--text");
+  const text = flagText ?? positionalText;
+  if (!text && !textFromStdin) throw new Error(`${first} requires text or --text-stdin`);
+  return {
+    command: `action.${first}`,
+    json,
+    payload: textFromStdin ? { ref, textFromStdin: true } : { ref, text }
+  };
+}
+function parseCli(argv) {
+  const json = hasFlag(argv, "--json");
+  const [first, second] = argv;
+  if (first === "navigate") {
+    throw new Error("navigate is not part of the TabBridge MVP command set");
+  }
+  if (first === "status") return { command: "status", json, payload: {} };
+  if (first === "doctor") return { command: "doctor", json, payload: {} };
+  if (first === "tabs" && second === "list") return { command: "tabs.list", json, payload: {} };
+  if (first === "tabs" && second === "current") return { command: "tabs.current", json, payload: {} };
+  if (first === "tabs" && second === "release") {
+    return { command: "tabs.release", json, payload: { tabId: requireNumberFlag(argv, "--tab", "tabs release") } };
+  }
+  if (first === "tabs" && second === "request-access") {
+    return {
+      command: "tabs.requestAccess",
+      json,
+      payload: {
+        tabId: requireNumberFlag(argv, "--tab", "tabs request-access"),
+        reason: requireStringFlag(argv, "--reason", "tabs request-access")
+      }
+    };
+  }
+  if (first === "approvals" && second === "status") {
+    return { command: "approvals.status", json, payload: { approvalId: requireStringFlag(argv, "--id", "approvals status") } };
+  }
+  if (first === "approvals" && second === "cancel") {
+    return { command: "approvals.cancel", json, payload: { approvalId: requireStringFlag(argv, "--id", "approvals cancel") } };
+  }
+  if (first === "approvals" && second === "wait") {
+    const timeout = readNumberFlag(argv, "--timeout");
+    return { command: "approvals.wait", json, payload: { approvalId: requireStringFlag(argv, "--id", "approvals wait"), timeoutMs: timeout } };
+  }
+  if (first === "connect") {
+    const tabId = readNumberFlag(argv, "--tab");
+    return { command: "session.connect", json, payload: tabId === void 0 ? { current: true } : { tabId } };
+  }
+  if (first === "session") return { command: "session.status", json, payload: {} };
+  if (first === "disconnect") return { command: "session.disconnect", json, payload: {} };
+  if (first === "snapshot") return { command: "snapshot", json, payload: { interactive: true } };
+  if (first === "text") return { command: "text", json, payload: { maxBytes: readNumberFlag(argv, "--max-bytes") } };
+  if (first === "html") {
+    return {
+      command: "html",
+      json,
+      payload: {
+        ref: requireStringFlag(argv, "--ref", "html"),
+        maxBytes: readNumberFlag(argv, "--max-bytes")
+      }
+    };
+  }
+  if (first === "screenshot") {
+    const [, path2] = positionalArgs(argv);
+    return { command: "screenshot", json, payload: path2 ? { path: path2 } : {} };
+  }
+  const refActions = /* @__PURE__ */ new Set(["click", "clear", "select", "check", "uncheck", "focus"]);
+  if (first && refActions.has(first)) return parseRefAction(first, argv, json);
+  if (first === "fill" || first === "type") return parseTextAction(first, argv, json);
+  if (first === "press") return { command: "action.press", json, payload: { key: requireStringFlag(argv, "--key", "press") } };
+  if (first === "scroll") return { command: "action.scroll", json, payload: { dx: readNumberFlag(argv, "--dx") ?? 0, dy: readNumberFlag(argv, "--dy") ?? 0 } };
+  if (first === "click-coordinates") return { command: "action.clickCoordinates", json, payload: { x: requireNumberFlag(argv, "--x", "click-coordinates"), y: requireNumberFlag(argv, "--y", "click-coordinates") } };
+  if (first === "drag-coordinates") return { command: "action.dragCoordinates", json, payload: { fromX: requireNumberFlag(argv, "--from-x", "drag-coordinates"), fromY: requireNumberFlag(argv, "--from-y", "drag-coordinates"), toX: requireNumberFlag(argv, "--to-x", "drag-coordinates"), toY: requireNumberFlag(argv, "--to-y", "drag-coordinates") } };
+  if (first === "wait") return { command: "wait", json, payload: { ms: requireNumberFlag(argv, "--ms", "wait") } };
+  if (first === "wait-for-text") return { command: "waitForText", json, payload: { text: requireStringFlag(argv, "--text", "wait-for-text"), timeoutMs: readNumberFlag(argv, "--timeout") } };
+  if (first === "reload") return { command: "navigation.reload", json, payload: {} };
+  if (first === "back") return { command: "navigation.back", json, payload: {} };
+  if (first === "forward") return { command: "navigation.forward", json, payload: {} };
+  throw new Error(`Unknown tabbridge command: ${argv.join(" ")}`);
+}
+
+// src/commands.ts
+function mapCliToJsonRpcRequest(parsed, id) {
+  const payload = { ...parsed.payload };
+  if (parsed.command === "approvals.wait" && typeof payload.timeoutMs !== "number") {
+    payload.timeoutMs = APPROVAL_WAIT_DEFAULT_TIMEOUT_MS;
+  }
+  return createJsonRpcRequest(id, parsed.command, payload);
+}
+
+// src/doctor.ts
+import fs2 from "fs/promises";
+
+// ../broker/dist/index.js
+import { WebSocket as WebSocket2, WebSocketServer } from "ws";
+import fs from "fs/promises";
+import path from "path";
+import envPaths from "env-paths";
+import lockfile from "proper-lockfile";
+var ERROR_CODES2 = [
+  "EXTENSION_NOT_CONNECTED",
+  "BRIDGE_SOCKET_UNAVAILABLE",
+  "BRIDGE_REQUEST_TIMEOUT",
+  "TAB_NOT_FOUND",
+  "TAB_NOT_AUTHORIZED",
+  "TAB_NOT_ACTIVE_FOR_SCREENSHOT",
+  "HOST_PERMISSION_DENIED",
+  "USER_APPROVAL_REQUIRED",
+  "APPROVAL_EXPIRED",
+  "APPROVAL_TIMEOUT",
+  "UNSUPPORTED_PAGE",
+  "FRAME_NOT_ACCESSIBLE",
+  "FRAME_ORIGIN_NOT_AUTHORIZED",
+  "SNAPSHOT_REQUIRED",
+  "REF_STALE",
+  "ELEMENT_NOT_VISIBLE",
+  "ELEMENT_DISABLED",
+  "ELEMENT_SCOPE_TOO_LARGE",
+  "ACTION_REQUIRES_CONFIRMATION",
+  "ACTION_NOT_SUPPORTED_IN_EXTENSION_MODE",
+  "USER_DENIED",
+  "MESSAGE_TOO_LARGE",
+  "PROTOCOL_VERSION_MISMATCH",
+  "BROWSER_COMMAND_TIMEOUT",
+  "EXTENSION_ID_MISMATCH"
+];
+var TAB_BRIDGE_ERROR_CODE_INDEX2 = Object.fromEntries(
+  ERROR_CODES2.map((code, index) => [code, index])
+);
+var NATIVE_HOST_TO_CHROME_MAX_BYTES2 = 1024 * 1024;
+var CHROME_TO_NATIVE_HOST_MAX_BYTES2 = 64 * 1024 * 1024;
+var SNAPSHOT_DEFAULT_MAX_BYTES2 = 256 * 1024;
+var TEXT_DEFAULT_MAX_BYTES2 = 128 * 1024;
+var HTML_DEFAULT_MAX_BYTES2 = 64 * 1024;
+var GRANT_TTL_MS2 = 30 * 6e4;
+function defaultSupportDir() {
+  return envPaths("tabbridge", { suffix: "" }).data;
+}
+function createRuntimePaths(supportDir) {
+  const dir = supportDir ?? defaultSupportDir();
+  return {
+    supportDir: dir,
+    tokenPath: path.join(dir, "broker-token"),
+    lockPath: path.join(dir, "broker.lock")
+  };
+}
+async function readToken(paths) {
+  try {
+    return (await fs.readFile(paths.tokenPath, "utf8")).trim();
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+
+// src/ensure-broker.ts
+import { spawn } from "child_process";
+import { access } from "fs/promises";
+import { fileURLToPath } from "url";
+import { WebSocket as WebSocket3 } from "ws";
+var DEFAULT_BROKER_URL = `ws://127.0.0.1:${BROKER_PORT}`;
+async function isBrokerListening(url) {
+  return await new Promise((resolve) => {
+    const ws = new WebSocket3(url);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      resolve(false);
+    }, 500);
+    ws.once("open", () => {
+      clearTimeout(timer);
+      ws.terminate();
+      resolve(true);
+    });
+    ws.once("error", () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+  });
+}
+async function defaultBrokerEntryExists(path2) {
+  try {
+    await access(path2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function brokerEntryPath() {
+  return fileURLToPath(new URL("./broker.js", import.meta.url));
+}
+async function brokerStartArgs(brokerEntryExists) {
+  const entryPath = brokerEntryPath();
+  if (!await brokerEntryExists(entryPath)) {
+    throw new Error(`BROKER_ENTRY_MISSING: expected built broker entry at ${entryPath}; please reinstall the tabbridge package`);
+  }
+  return [entryPath];
+}
+function waitForBroker(child, url, isListening, options) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const timer = setInterval(async () => {
+      try {
+        if (await isListening(url)) {
+          clearInterval(timer);
+          resolve();
+        } else if (Date.now() - start >= options.timeoutMs) {
+          clearInterval(timer);
+          reject(new Error("BROKER_START_FAILED: broker did not start in time"));
+        }
+      } catch {
+        if (Date.now() - start >= options.timeoutMs) {
+          clearInterval(timer);
+          reject(new Error("BROKER_START_FAILED: broker did not start in time"));
+        }
+      }
+    }, options.intervalMs);
+    child.on("error", (error) => {
+      clearInterval(timer);
+      reject(new Error(`BROKER_START_FAILED: ${error.message}`));
+    });
+  });
+}
+async function ensureBroker(options = {}) {
+  const paths = options.paths ?? createRuntimePaths();
+  const url = DEFAULT_BROKER_URL;
+  const listening = options.isListening ?? isBrokerListening;
+  const readBrokerToken = options.readToken ?? readToken;
+  if (await listening(url)) {
+    const token2 = await readBrokerToken(paths);
+    if (!token2) {
+      throw new Error("BROKER_TOKEN_MISSING: broker is listening but the token file is missing; restart the broker");
+    }
+    return { url, token: token2 };
+  }
+  const child = (options.spawn ?? spawn)(process.execPath, await brokerStartArgs(options.brokerEntryExists ?? defaultBrokerEntryExists), {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true
+  });
+  child.unref();
+  await waitForBroker(
+    child,
+    url,
+    listening,
+    { timeoutMs: options.waitTimeoutMs ?? 5e3, intervalMs: options.waitIntervalMs ?? 100 }
+  );
+  const token = await readBrokerToken(paths);
+  if (!token) {
+    throw new Error("BROKER_TOKEN_MISSING: broker started but the token file is missing; restart the broker");
+  }
+  return { url, token };
+}
+
+// src/doctor.ts
+async function exists(filePath) {
+  try {
+    await fs2.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function fileMode(filePath) {
+  try {
+    return (await fs2.stat(filePath)).mode;
+  } catch {
+    return void 0;
+  }
+}
+async function runDoctor(input = {}) {
+  const paths = createRuntimePaths(input.home);
+  const listening = await isBrokerListening(`ws://127.0.0.1:${BROKER_PORT}`);
+  const tokenExists = await exists(paths.tokenPath);
+  const tokenMode = await fileMode(paths.tokenPath);
+  const lockExists = await exists(paths.lockPath);
+  const checks = [
+    { name: "broker is listening on port 9876", ok: listening },
+    { name: "broker token file exists", ok: tokenExists },
+    {
+      name: "broker token file mode is 0600",
+      ok: process.platform === "win32" || tokenMode !== void 0 && (tokenMode & 511) === 384
+    },
+    { name: "broker lock file exists", ok: lockExists }
+  ];
+  if (!listening) {
+    return { ok: false, bridgeState: "extension_asleep", errorCode: "EXTENSION_NOT_CONNECTED", checks };
+  }
+  const ok = checks.every((check) => check.ok);
+  return { ok, bridgeState: "connected", checks };
+}
+
+// src/json-output.ts
+function printJsonEnvelope(envelope, stdout) {
+  stdout.write(`${JSON.stringify(envelope)}
+`);
+}
+function printCliError(error, json, stdout, stderr) {
+  const message = error instanceof Error ? error.message : "Unknown CLI error";
+  if (json) {
+    printJsonEnvelope(errorEnvelope({ code: "BRIDGE_SOCKET_UNAVAILABLE", message, recoverable: true }), stdout);
+    return;
+  }
+  stderr.write(`${message}
+`);
+}
+
+// src/main.ts
+async function readStdin(stdin) {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function hydrateStdinPayload(parsed, stdin) {
+  if (!["action.type", "action.fill"].includes(parsed.command) || parsed.payload.textFromStdin !== true) return parsed;
+  const { textFromStdin: _textFromStdin, ...payloadWithoutMarker } = parsed.payload;
+  return {
+    ...parsed,
+    payload: {
+      ...payloadWithoutMarker,
+      text: await readStdin(stdin)
+    }
+  };
+}
+async function run(options = {}) {
+  const argv = options.argv ?? process.argv.slice(2);
+  const json = argv.includes("--json");
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const stdin = options.stdin ?? process.stdin;
+  const requestId = options.requestId ?? (() => `req_${process.pid}_${Date.now()}`);
+  const ensureBroker2 = options.ensureBroker ?? ensureBroker;
+  const sendBrokerRequest2 = options.sendBrokerRequest ?? sendBrokerRequest;
+  const runDoctor2 = options.runDoctor ?? runDoctor;
+  try {
+    const parsed = await hydrateStdinPayload(parseCli(argv), stdin);
+    if (parsed.command === "doctor") {
+      const report = await runDoctor2();
+      printJsonEnvelope(okEnvelope(report), stdout);
+      return report.ok ? 0 : 1;
+    }
+    const broker = await ensureBroker2();
+    const request = mapCliToJsonRpcRequest(parsed, requestId());
+    const envelope = await sendBrokerRequest2(request, { url: broker.url, token: broker.token, timeoutMs: 3e4 });
+    if (parsed.json) {
+      printJsonEnvelope(envelope, stdout);
+    } else if (envelope.ok) {
+      if (parsed.command === "snapshot" && typeof envelope.data.text === "string") {
+        stdout.write(`${envelope.data.text}
+`);
+      } else {
+        stdout.write(`${JSON.stringify(envelope.data, null, 2)}
+`);
+      }
+    } else {
+      stderr.write(`${envelope.error.message}
+`);
+    }
+    return envelope.ok ? 0 : 1;
+  } catch (error) {
+    printCliError(error, json, stdout, stderr);
+    return 1;
+  }
+}
+if (process.env.VITEST !== "true") {
+  run().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error) => {
+      console.error(error);
+      process.exitCode = 1;
+    }
+  );
+}
+export {
+  run
+};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "tabbridge-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "tabbridge": "main.js"
+  },
+  "files": [
+    "main.js",
+    "broker.js",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "env-paths": "^4.0.0",
+    "proper-lockfile": "^4.1.2",
+    "ws": "^8.18.0"
+  }
+}