@raysonmeng/agentbridge 0.1.5 → 0.1.7

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
     {
       "name": "agentbridge",
       "description": "Bridge Claude Code and Codex through a shared daemon, push channel delivery, and reply/get_messages tools.",
-      "version": "0.1.5",
+      "version": "0.1.7",
       "author": {
         "name": "AgentBridge Contributors",
         "email": "raysonmeng@qq.com"

package/README.md

@@ -154,14 +154,19 @@ After modifying AgentBridge source code, re-run `agentbridge dev` to sync change
 
 | Command | Description |
 |---------|-------------|
-| `abg init` | Install plugin, check dependencies (bun/claude/codex), generate `.agentbridge/config.json` and `collaboration.md` |
+| `abg init` | Install plugin, check dependencies (bun/claude/codex), generate `.agentbridge/config.json` |
 | `abg claude [args...]` | Start Claude Code with push channel enabled. Clears any killed sentinel from a previous `kill`. Pass-through args are forwarded to `claude` |
-| `abg codex [args...]` | Start Codex TUI connected to AgentBridge daemon. Manages TUI process lifecycle (pid tracking, cleanup). Pass-through args forwarded to `codex` |
-| `abg kill` | Gracefully stop both daemon and managed Codex TUI, clean up state files, write killed sentinel |
+| `abg codex [args...]` | Start Codex TUI connected to AgentBridge daemon. **Bare `abg codex` auto-resumes the pair's last thread; use `abg codex --new` for a fresh thread.** Manages TUI process lifecycle (pid tracking, cleanup). Pass-through args forwarded to `codex` |
+| `abg pairs` | List registered pairs; `abg pairs rm <name\|id>` removes one, `abg pairs prune` deletes orphan state dirs |
+| `abg doctor [--json]` | Read-only diagnosis: env, daemon health/readiness, build drift, artifact alignment, TUI attachment, logs |
+| `abg budget [--json]` | Both agents' subscription quota snapshot (5h/weekly windows, drift, pause state) |
+| `abg kill` | Gracefully stop this pair's daemon and managed Codex TUI, write killed sentinel; `abg kill --all` stops every pair |
 | `abg dev` | (Dev only) Register local marketplace + force-sync plugin to cache |
 | `abg --help` | Show help |
 | `abg --version` | Show version |
 
+The pair-aware commands (`claude`, `codex`, `kill`, `doctor`, `budget`) accept `--pair <name>` to target a specific pair — one pair per project directory by default, with ports allocated per pair in +10 strides from 4500.
+
 ### Owned flags
 
 Some flags are automatically injected and cannot be manually specified:
@@ -171,14 +176,22 @@ Some flags are automatically injected and cannot be manually specified:
 
 Passing these flags manually will result in a hard error with guidance to use the native command directly.
 
+> **Note on flag positioning for `agentbridge codex`:** For the bare TUI form
+> (`agentbridge codex …`), bridge flags are injected at the front. For TUI
+> subcommands that carry per-subcommand args (`resume`, `fork`), they are
+> injected *after* the subcommand name (so clap parses them as options of the
+> actually-invoked command, not the root). Non-TUI subcommands like `exec`,
+> `mcp`, `plugin`, `remote-control`, `update` etc. are passed through
+> unchanged — no bridge flags injected. See `src/cli/codex.ts buildCodexArgs`
+> for the full positioning logic.
+
 ## Project Config
 
 Running `agentbridge init` creates a `.agentbridge/` directory in your project root:
 
 | File | Purpose |
 |------|---------|
-| `config.json` | Machine-readable project config (ports, agent roles, markers, turn coordination) |
-| `collaboration.md` | Human/agent-readable collaboration rules (roles, thinking patterns, communication style) |
+| `config.json` | Machine-readable project config (Codex ports, turn coordination, idle shutdown) |
 
 The config is loaded by the CLI and daemon at startup. Re-running `init` is idempotent and will not overwrite existing files.
 
@@ -218,7 +231,11 @@ agent_bridge/
 │       ├── init.ts                # agentbridge init
 │       ├── claude.ts              # agentbridge claude
 │       ├── codex.ts               # agentbridge codex
+│       ├── pairs.ts               # agentbridge pairs (list / rm / prune)
+│       ├── doctor.ts              # agentbridge doctor (read-only diagnosis)
+│       ├── budget.ts              # agentbridge budget (quota snapshot)
 │       ├── kill.ts                # agentbridge kill
+│       ├── pkg-root.ts            # package-root resolution helper
 │       └── dev.ts                 # agentbridge dev
 ├── CLAUDE.md                      # Project rules for AI agents
 ├── CODE_OF_CONDUCT.md
@@ -240,9 +257,26 @@ agent_bridge/
 | `CODEX_WS_PORT` | `4500` | Codex app-server WebSocket port |
 | `CODEX_PROXY_PORT` | `4501` | Bridge proxy port for the Codex TUI |
 | `AGENTBRIDGE_CONTROL_PORT` | `4502` | Control port between bridge.ts and daemon.ts |
+| `AGENTBRIDGE_LIVENESS_PROBE_TIMEOUT_MS` | `3000` | Maximum wait for incumbent Claude pong before evicting on contention (issue #68) |
+| `AGENTBRIDGE_TURN_WATCHDOG_MS` | `300000` | Per-turn inactivity watchdog: force-completes a turn after this many ms of app-server silence so a lost `turn/completed` can't lock injection forever (issue #69) |
+| `AGENTBRIDGE_CODEX_TRANSPORT` | `auto` | How the daemon reaches the Codex app-server: `auto` (probe `codex app-server --help`, use `ws://` if supported else fall back to a `unix://` socket via a transparent relay), `ws` (force ws), or `unix` (force unix socket + relay). For builds that drop `ws://` listen support (issue #85) |
 | `AGENTBRIDGE_STATE_DIR` | Platform default | State directory for pid, status, logs (macOS: `~/Library/Application Support/agentbridge/`, Linux: `$XDG_STATE_HOME/agentbridge/`) |
-| `AGENTBRIDGE_MODE` | `push` | Message delivery mode (`push` for channels, `pull` for API key mode) |
 | `AGENTBRIDGE_DAEMON_ENTRY` | `./daemon.ts` | Override daemon entry point (used by plugin bundles) |
+| `NO_UPDATE_NOTIFIER` | unset | Set to any value to disable the "update available" notice (ecosystem-standard opt-out) |
+| `AGENTBRIDGE_NO_UPDATE_NOTIFIER` | unset | Namespaced opt-out for the update notice (same effect as `NO_UPDATE_NOTIFIER`) |
+| `AGENTBRIDGE_UPDATE_CHECK_INTERVAL_MS` | `86400000` | How often `abg claude`/`abg codex` may check npm for a newer version (default once/day). The notice is otherwise printed from cache — zero network on most runs |
+
+### Update notifications
+
+`abg claude` and `abg codex` print a one-line notice to stderr when a newer **stable** AgentBridge is published to npm, e.g.:
+
+```
+⚠ AgentBridge update available: 0.1.6 → 0.1.7
+  CLI:    npm install -g @raysonmeng/agentbridge@latest
+  Plugin: /plugin marketplace update agentbridge   (then /reload-plugins)
+```
+
+The check is best-effort and never blocks, delays, or fails your command: the notice is printed from a cached result, the npm check runs at most once per day in the background, and any network/registry failure is silently ignored. It is suppressed automatically for non-interactive (piped) output and in CI, and can be disabled with `NO_UPDATE_NOTIFIER=1`. The notifier never installs anything — it only shows you the command.
 
 ### State Directory
 
@@ -255,12 +289,24 @@ The daemon stores runtime state in a platform-aware directory:
 
 Contents: `daemon.pid`, `status.json`, `agentbridge.log`, `killed` (sentinel), `startup.lock`
 
+### Disabled Bridge States
+
+The bridge can enter several dormant states when it cannot accept new MCP replies. Each state surfaces to the agent as an error message (and, for the transient ones, an in-band push notification):
+
+| State | Cause | Recovery |
+|-------|-------|----------|
+| `killed` | `agentbridge kill` was run, sentinel file present. | Restart Claude Code (`agentbridge claude`), switch to a new conversation, or run `/resume`. |
+| `rejected` | Daemon rejected the connection: another Claude session is already attached. | Close the other session, or run `agentbridge kill` to reset, then `agentbridge claude` again. |
+| `evicted` | A newer session evicted this one after the incumbent failed a liveness probe (issue #68). | Close this session and start a fresh one with `agentbridge claude`. |
+| `probe_in_progress` | A liveness probe is currently checking the incumbent — contention window. Transient (auto-recovers within `DISABLED_RECOVERY_INTERVAL_MS` × cap, ~30 s). | None needed; the recovery poller reconnects automatically when the slot clears. |
+| `auto_recovery_exhausted` | The auto-recovery poller for `probe_in_progress` ran its full retry budget (6 attempts, ~30 s) without succeeding. Terminal. | Retry manually with `agentbridge claude`. |
+
 ## Current Limitations
 
 - Only forwards `agentMessage` items, not intermediate `commandExecution`, `fileChange`, or similar events
-- Single Codex thread, no multi-session support yet
-- Single Claude foreground connection; a new Claude session replaces the previous one
-- Fixed ports mean only one AgentBridge instance per machine (multi-project support planned for post-v1)
+- Single Codex thread per pair, no multi-session support within a pair yet
+- Single Claude foreground connection per pair; a new Claude session replaces the previous one
+- Multiple pairs run side-by-side on one machine (one per project directory, per-pair port allocation); Windows is not an officially supported platform yet
 
 ### Codex git restrictions
 

package/README.zh-CN.md

@@ -154,7 +154,7 @@ agentbridge codex
 
 | 命令 | 说明 |
 |------|------|
-| `abg init` | 安装插件、检查依赖（bun/claude/codex）、生成 `.agentbridge/config.json` 和 `collaboration.md` |
+| `abg init` | 安装插件、检查依赖（bun/claude/codex）、生成 `.agentbridge/config.json` |
 | `abg claude [args...]` | 启动 Claude Code 并启用 push channel。自动清除之前 `kill` 留下的 sentinel。额外参数透传给 `claude` |
 | `abg codex [args...]` | 启动连接到 AgentBridge daemon 的 Codex TUI。管理 TUI 进程生命周期（pid 跟踪、清理）。额外参数透传给 `codex` |
 | `abg kill` | 优雅停止 daemon 和托管的 Codex TUI，清理状态文件，写入 killed sentinel |
@@ -171,14 +171,20 @@ agentbridge codex
 
 手动传入这些参数会报错，并提示使用原生命令。
 
+> **关于 `agentbridge codex` 参数位置的说明：** 对于无子命令的 TUI 形式
+> （`agentbridge codex …`），bridge 注入的参数放在最前面。对于带有自己参数的
+> TUI 子命令（`resume`、`fork`），bridge 参数注入到**子命令名之后**（这样
+> clap 才会把它们解析为该子命令的选项，而不是根命令的）。`exec`、`mcp`、
+> `plugin`、`remote-control`、`update` 等非 TUI 子命令则原样透传，不注入
+> bridge 参数。完整定位逻辑见 `src/cli/codex.ts` 的 `buildCodexArgs`。
+
 ## 项目配置
 
 运行 `agentbridge init` 会在项目根目录创建 `.agentbridge/` 目录：
 
 | 文件 | 用途 |
 |------|------|
-| `config.json` | 机器可读的项目配置（端口、Agent 角色、消息标记、回合协调） |
-| `collaboration.md` | 人类/Agent 可读的协作规则（角色、思考模式、沟通风格） |
+| `config.json` | 机器可读的项目配置（Codex 端口、回合协调、空闲关闭） |
 
 CLI 和 daemon 启动时会加载该配置。重复运行 `init` 是幂等的，不会覆盖已有文件。
 
@@ -240,9 +246,26 @@ agent_bridge/
 | `CODEX_WS_PORT` | `4500` | Codex app-server WebSocket 端口 |
 | `CODEX_PROXY_PORT` | `4501` | Bridge 代理端口，Codex TUI 连接此端口 |
 | `AGENTBRIDGE_CONTROL_PORT` | `4502` | bridge.ts 与 daemon.ts 之间的控制端口 |
+| `AGENTBRIDGE_LIVENESS_PROBE_TIMEOUT_MS` | `3000` | 等待在位 Claude pong 的最长时间，超时后在争用时驱逐（issue #68） |
+| `AGENTBRIDGE_TURN_WATCHDOG_MS` | `300000` | 单 turn 非活动看门狗：app-server 静默超过该毫秒数后强制完成该 turn，避免丢失 `turn/completed` 永久锁死注入（issue #69） |
+| `AGENTBRIDGE_CODEX_TRANSPORT` | `auto` | daemon 连接 Codex app-server 的方式：`auto`（探测 `codex app-server --help`，支持 `ws://` 则用 ws，否则经透明中继回退到 `unix://` socket）、`ws`（强制 ws）、`unix`（强制 unix socket + 中继）。用于去掉 `ws://` listen 支持的 Codex 版本（issue #85） |
 | `AGENTBRIDGE_STATE_DIR` | 平台默认 | 状态目录（pid、status、日志）。macOS: `~/Library/Application Support/agentbridge/`，Linux: `$XDG_STATE_HOME/agentbridge/` |
-| `AGENTBRIDGE_MODE` | `push` | 消息投递模式（`push` 用于 channel，`pull` 用于 API key 模式） |
 | `AGENTBRIDGE_DAEMON_ENTRY` | `./daemon.ts` | 覆盖 daemon 入口（插件包使用） |
+| `NO_UPDATE_NOTIFIER` | 未设置 | 设为任意值即关闭「有新版本」提示（生态通用 opt-out） |
+| `AGENTBRIDGE_NO_UPDATE_NOTIFIER` | 未设置 | 命名空间化的关闭开关（效果同 `NO_UPDATE_NOTIFIER`） |
+| `AGENTBRIDGE_UPDATE_CHECK_INTERVAL_MS` | `86400000` | `abg claude`/`abg codex` 多久查一次 npm 新版本（默认每天一次）。其余时候只读缓存打印，大多数调用零网络 |
+
+### 更新提示
+
+`abg claude` 和 `abg codex` 在 npm 上有更新的**稳定**版本时,会向 stderr 打印一行提示,例如:
+
+```
+⚠ AgentBridge update available: 0.1.6 → 0.1.7
+  CLI:    npm install -g @raysonmeng/agentbridge@latest
+  Plugin: /plugin marketplace update agentbridge   (then /reload-plugins)
+```
+
+该检查是 best-effort,绝不阻塞/拖慢/弄坏你的命令:提示从缓存打印,npm 检查每天最多在后台跑一次,任何网络/registry 失败都静默忽略。非交互(管道)输出和 CI 下自动抑制,可用 `NO_UPDATE_NOTIFIER=1` 关闭。notifier 永远不会自动安装任何东西——只告诉你升级命令。
 
 ### 状态目录
 
@@ -255,6 +278,18 @@ daemon 在平台感知的目录中存储运行时状态：
 
 内容：`daemon.pid`、`status.json`、`agentbridge.log`、`killed`（sentinel）、`startup.lock`
 
+### Bridge 禁用状态
+
+Bridge 在无法接受新 MCP 回复时会进入若干休眠状态。每种状态都会以错误信息返回给 agent；瞬态状态还会推送一条带内通知：
+
+| 状态 | 原因 | 恢复方式 |
+|------|------|---------|
+| `killed` | 运行过 `agentbridge kill`，存在 sentinel 文件。 | 重启 Claude Code（`agentbridge claude`），切换到新会话，或运行 `/resume`。 |
+| `rejected` | daemon 拒绝连接：已有另一个 Claude 会话连接中。 | 先关闭另一个会话，或运行 `agentbridge kill` 重置，然后重新 `agentbridge claude`。 |
+| `evicted` | 在位会话未响应存活探测，被更新的会话驱逐（issue #68）。 | 关闭本会话，用 `agentbridge claude` 重新启动一个。 |
+| `probe_in_progress` | 当前正在对在位会话执行存活探测——争用窗口期。瞬态（在 `DISABLED_RECOVERY_INTERVAL_MS` × 重试上限内自动恢复，约 30 秒）。 | 无需操作；恢复轮询会在槽位释放后自动重连。 |
+| `auto_recovery_exhausted` | `probe_in_progress` 的自动恢复轮询用尽了完整的重试预算（6 次，约 30 秒）仍未成功。终态。 | 手动用 `agentbridge claude` 重试。 |
+
 ## 当前限制
 
 - 目前只转发 `agentMessage`，不转发 `commandExecution`、`fileChange` 等中间过程事件