cross-agent-teams-mcp 0.5.4 → 0.5.5

package/README.md

@@ -4,12 +4,47 @@
 
 A local MCP daemon that lets multiple AI coding agents (Claude Code, Codex, opencode) running on the same machine talk to each other.  Agents register, send 1-to-1 messages, broadcast to a team or role, and wake each other up — all over a single daemon, no external services.
 
-## What's in the npm package
+## Quick start
 
-`cross-agent-teams-mcp` ships two bins from the same package:
+### Claude Code
 
-- **`cross-agent-teams-mcp daemon`** — the long-running HTTP daemon.  Stores agents, mailboxes, and the task list in a local SQLite file, exposes its tools at `http://127.0.0.1:9100/mcp`.
-- **`cross-agent-teams-channel`** — a stdio MCP shim that lets Claude Code receive `notifications/channel_wake` from the daemon (Claude Code's experimental channel capability).  Required for Claude Code wake-ups; not needed for Codex (which uses its own app-server transport) or opencode (which falls back to tmux-pane injection).
+```bash
+# 1. Start the daemon (run once, keep it alive)
+npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
+
+# 2. In your project, install the MCP config
+npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code
+
+# 3. Start Claude Code with the channel loader (manual permission prompt expected)
+claude --dangerously-load-development-channels server:cross-agent-teams-channel
+```
+
+### Other agents (Codex, opencode, ...)
+
+```bash
+# 1. Start the daemon (run once, keep it alive)
+npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
+
+# 2. In your project, install the MCP config (interactive picker)
+npx mcpsmgr add jtianling/cross-agent-teams-mcp
+
+# 3. Start your coding agent as usual
+```
+
+Note: only Claude Code gets push wake out of the box.  Codex needs the `--remote` + launcher setup (see section 2 below) for pokes; without it, it has a mailbox but no wake.  opencode / cursor / other agents only receive pokes when running inside a tmux pane.  If push wake isn't wired up, ask the agent to check its inbox manually ("check my xats inbox").
+
+Then talk to your agent in plain language:
+
+```
+# In agent A:
+Register me to xats as backend on team default.
+
+# In agent B:
+Register me to xats as frontend on team default.
+Send backend a message: the API has changed.
+```
+
+That's it.  Sections below cover the details — daemon flags, manual MCP config, codex `--remote` setup, more usage patterns.
 
 ## 1. Start the daemon
 
@@ -30,26 +65,11 @@ Common flags:
 
 ## 2. Configure your agent's MCP client
 
-### Recommended: install via `mcpsmgr`
-
-The fastest path is the [`mcpsmgr`](https://www.npmjs.com/package/mcpsmgr) CLI.  It reads this repo's manifest (`mcpsmgr.json`) and writes the right MCP entries (and any required stdio proxy entries) into your agent's config in one shot.
-
-```bash
-cd <your-project>
-
-# Pick one or run the bare command for an interactive picker.
-npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code
-npx mcpsmgr add jtianling/cross-agent-teams-mcp -a codex
-npx mcpsmgr add jtianling/cross-agent-teams-mcp                   # interactive
-```
-
-What it does:
+### Recommended: `mcpsmgr` (shown in Quick start)
 
-- For Claude Code, writes both `.mcp.json` entries (the HTTP server AND the `cross-agent-teams-channel` stdio proxy) — you don't have to know there are two.
-- For Codex, writes `~/.codex/config.toml` with `experimental_use_rmcp_client = true` plus the streamable-http MCP entry.
-- Prints the post-install steps you still need to run yourself (e.g. the `--dangerously-load-development-channels server:cross-agent-teams-channel` flag for Claude Code, or the codex `--remote` setup if you want push wake).
+[`mcpsmgr`](https://www.npmjs.com/package/mcpsmgr) reads this repo's `mcpsmgr.json` and writes the right MCP entries into your agent's config in one shot — including the Claude Code stdio channel proxy entry, the Codex `experimental_use_rmcp_client` toggle, and the streamable-http MCP entry.
 
-Override the daemon port:
+To override the daemon port:
 
 ```bash
 npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code --port 9300

package/README.zh-CN.md

@@ -4,12 +4,47 @@
 
 一个本地 MCP daemon, 让同一台机器上的多个 AI 编码 agent (Claude Code, Codex, opencode) 互相通信.  agent 注册到 daemon, 互发 1-to-1 消息, 在 team 或 role 内广播, 互相唤醒 — 全部通过一个本地 daemon 完成, 不依赖任何外部服务.
 
-## npm 包内容
+## 快速开始
 
-`cross-agent-teams-mcp` 在同一个包里发两个 bin:
+### Claude Code
 
-- **`cross-agent-teams-mcp daemon`** — 长驻 HTTP daemon.  把 agent 注册表和邮箱存在本地 SQLite 文件里, MCP endpoint 在 `http://127.0.0.1:9100/mcp`.
-- **`cross-agent-teams-channel`** — stdio MCP shim, 让 Claude Code 通过 `notifications/channel_wake` 接收唤醒通知 (Claude Code 的 experimental channel capability).  Claude Code 需要它接收 wake; Codex 用自己的 app-server 通道, opencode 走 tmux-pane 文本注入, 都不需要 channel proxy.
+```bash
+# 1. 启动 daemon (跑一次, 保持运行)
+npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
+
+# 2. 在你的项目下安装 MCP 配置
+npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code
+
+# 3. 带上 channel loader 启动 Claude Code (需要手动确认权限)
+claude --dangerously-load-development-channels server:cross-agent-teams-channel
+```
+
+### 其它 agent (Codex, opencode, ...)
+
+```bash
+# 1. 启动 daemon (跑一次, 保持运行)
+npx -y cross-agent-teams-mcp@latest daemon --port 9100 &
+
+# 2. 在你的项目下安装 MCP 配置 (交互式选择对应 agent)
+npx mcpsmgr add jtianling/cross-agent-teams-mcp
+
+# 3. 按平时的方式启动对应 coding agent
+```
+
+注意: 只有 Claude Code 默认就能收到 push 唤醒.  Codex 需要 `--remote` + launcher 配置 (见下面 section 2) 才能被 poke; 没配的话只有邮箱, 不会自动醒.  opencode / cursor 等其它 agent 只有跑在 tmux pane 里才能被 poke.  没接通 push 唤醒的情况下, 让 agent 自己手动收信即可 (跟它说"查一下我的 xats inbox").
+
+之后用平时跟 agent 对话的语言就能用了:
+
+```
+# Agent A 里:
+Register me to xats as backend on team default.
+
+# Agent B 里:
+Register me to xats as frontend on team default.
+Send backend a message: the API has changed.
+```
+
+就这些.  下面是细节 — daemon 参数, 手动 MCP 配置, codex `--remote` 设置, 更多使用方式.
 
 ## 1. 启动 daemon
 
@@ -30,24 +65,9 @@ daemon 默认监听 `127.0.0.1:9100`.  MCP endpoint: `http://127.0.0.1:9100/mcp`
 
 ## 2. 在 agent 端配置 MCP client
 
-### 推荐: 用 `mcpsmgr` 安装
-
-最快的方式是用 [`mcpsmgr`](https://www.npmjs.com/package/mcpsmgr) CLI.  它读取本仓库的 manifest (`mcpsmgr.json`), 一次性把对应 agent 需要的 MCP 条目 (含必要的 stdio proxy 条目) 写到 agent 的配置文件里.
-
-```bash
-cd <your-project>
-
-# 选一个, 或者用裸命令进入交互式选择.
-npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code
-npx mcpsmgr add jtianling/cross-agent-teams-mcp -a codex
-npx mcpsmgr add jtianling/cross-agent-teams-mcp                   # 交互式
-```
-
-它做了什么:
+### 推荐: `mcpsmgr` (快速开始里已经演示)
 
-- Claude Code: 同时写两条 `.mcp.json` 条目 (HTTP 工具 + `cross-agent-teams-channel` stdio proxy) — 你不用记两条.
-- Codex: 写 `~/.codex/config.toml`, 带上 `experimental_use_rmcp_client = true` 和 streamable-http MCP 条目.
-- 打印你还需要自己跑的 post-install 步骤 (例如 Claude Code 的 `--dangerously-load-development-channels server:cross-agent-teams-channel` 启动 flag, 或 codex 想要 push 唤醒时的 `--remote` 配置).
+[`mcpsmgr`](https://www.npmjs.com/package/mcpsmgr) 读取本仓库的 `mcpsmgr.json`, 一次性把对应 agent 需要的 MCP 条目写进配置 — 包括 Claude Code 的 stdio channel proxy 条目, Codex 的 `experimental_use_rmcp_client` 开关和 streamable-http MCP 条目.
 
 覆盖 daemon 端口:
 

package/dist/cli.js

@@ -388,6 +388,7 @@ function toAgentRow(row) {
 var AgentsRepo = class {
   constructor(db) {
     this.db = db;
+    this.list = this.list.bind(this);
   }
   db;
   findByIdentity(args) {
@@ -525,8 +526,8 @@ var AgentsRepo = class {
     );
   }
   list(args) {
-    const rows = this.db.prepare(
-      `SELECT
+    const exclude = args.excludeRoles ?? [];
+    const baseSelect = `SELECT
          agent_id,
          agent_type,
          agent_type_name,
@@ -539,9 +540,17 @@ var AgentsRepo = class {
          delivery_payload,
          last_seen_at
        FROM agents
-       WHERE team=?
-       ORDER BY registered_at ASC`
-    ).all(args.team);
+       WHERE team=?`;
+    const orderBy = ` ORDER BY registered_at ASC`;
+    let rows;
+    if (exclude.length > 0) {
+      const placeholders = exclude.map(() => "?").join(",");
+      rows = this.db.prepare(
+        `${baseSelect} AND role NOT IN (${placeholders})${orderBy}`
+      ).all(args.team, ...exclude);
+    } else {
+      rows = this.db.prepare(`${baseSelect}${orderBy}`).all(args.team);
+    }
     const nowMs = Date.now();
     return rows.map((row) => {
       const agent = toAgentRow(row);
@@ -3642,7 +3651,7 @@ function registerBusinessTools(server, db, getCallerAgentId, fanout, onRegisterS
       if (typeof who !== "string") return toText(who);
       const row = agents.findById(who);
       return run(() => ({
-        agents: agents.list({ team: row.team }).map(toPublicAgentRow)
+        agents: agents.list({ team: row.team, excludeRoles: ["__channel_proxy__"] }).map(toPublicAgentRow)
       }));
     }
   );
@@ -4249,11 +4258,24 @@ function runCleanup(db, opts = {}) {
   );
   const deleteMessages = db.prepare(`DELETE FROM messages WHERE sent_at < ?`);
   const deleteEvents = db.prepare(`DELETE FROM events WHERE created_at < ?`);
+  const deleteStaleProxies = db.prepare(
+    `DELETE FROM agents
+      WHERE role = '__channel_proxy__'
+        AND last_seen_at < ?
+        AND NOT EXISTS (
+          SELECT 1 FROM agents host
+          WHERE host.delivery_kind = 'claude-channel'
+            AND host.role <> '__channel_proxy__'
+            AND json_extract(host.delivery_payload, '$.channel_session_id')
+                = json_extract(agents.delivery_payload, '$.channel_session_id')
+        )`
+  );
   const tx = db.transaction(() => {
     const s = deleteStatus.run(ageCutoff);
     const m = deleteMessages.run(ageCutoff);
     const e = deleteEvents.run(ageCutoff);
-    return Number(s.changes) + Number(m.changes) + Number(e.changes);
+    const p = deleteStaleProxies.run(ageCutoff);
+    return Number(s.changes) + Number(m.changes) + Number(e.changes) + Number(p.changes);
   });
   return { deleted: tx() };
 }