cross-agent-teams-mcp 0.5.8 → 0.5.10

package/README.md

@@ -65,32 +65,7 @@ Common flags:
 - `--db <path>` (default `~/.cross-agent-teams-mcp/data.db`)
 - `--pid-file <path>` (default `~/.cross-agent-teams-mcp/daemon.pid`)
 
-### Cross-host (LAN) collaboration
-
-To let agents on another trusted machine use this daemon, bind the daemon to a LAN address and set a shared bearer token:
-
-```bash
-npx -y cross-agent-teams-mcp@latest daemon \
-  --host 10.0.0.10 \
-  --port 9100 \
-  --token "$XATS_TOKEN" \
-  --device host-a
-```
-
-Then configure the peer host's Claude Code channel proxy to connect back to that daemon:
-
-```bash
-npx -y -p cross-agent-teams-mcp@latest cross-agent-teams-channel \
-  --daemon-url http://10.0.0.10:9100/mcp \
-  --token "$XATS_TOKEN" \
-  --device host-b
-```
-
-Agents are namespaced by `(device, team, name)`.  A bare `send_message({to_agent_name:"creator"})` resolves on the caller's own device; use `creator:host-b` to address a same-team agent on another device.  `list_agents` shows the `device` field so you can compose those addresses.
-
-Security notes: non-loopback `--host` requires `--token`, and the token is shared by everyone who can use that daemon.  Treat LAN exposure as trusted-team only; there is no per-agent authorization, device whitelist, or TLS in this mode.
-
-Upgrade note: the first startup after this version auto-migrates the storage schema from `(team, name)` identity to `(device, team, name)` identity and backfills existing rows with the daemon's local `--device` label.  Rolling back after registering multiple devices with the same `(team, name)` can violate the old uniqueness assumption.
+For multi-host / multi-device setups (LAN, tailscale, etc.), see [section 4](#4-cross-host--cross-device-collaboration) below.
 
 ## 2. Configure your agent's MCP client
 
@@ -160,7 +135,7 @@ url = "http://127.0.0.1:9100/mcp"
 
 `experimental_use_rmcp_client = true` MUST sit at the top level — without it, streamable-http MCP servers fail to load.
 
-(With `--token <t>` on the daemon: add `[mcp_servers.cross-agent-teams-mcp.headers]` and `Authorization = "Bearer <t>"`.)
+When the daemon was started with `--token <t>`: `export XATS_TOKEN=<t>` in the shell that launches codex, then add `bearer_token_env_var = "XATS_TOKEN"` to the `[mcp_servers.cross-agent-teams-mcp]` block.  (Codex 0.130+ silently ignores the older `[mcp_servers.X.headers]` form — its accepted keys are `http_headers` and `bearer_token_env_var`, and `bearer_token_env_var` is preferred so the token never lands in a checked-in config.)
 
 In this minimum mode, `send_message` to this Codex still drops a row in its mailbox, but you have to call `get_inbox` yourself to read it — no push wake.
 
@@ -210,10 +185,12 @@ free-xats-codex() {
     if [[ -n "$codex_home" ]]; then
         CODEX_HOME="$codex_home" exec codex \
             --remote ws://127.0.0.1:8799 \
+            -C "$PWD" \
             -c xats.agent_id="\"$xats_agent_id\"" "$@"
     else
         exec codex \
             --remote ws://127.0.0.1:8799 \
+            -C "$PWD" \
             -c xats.agent_id="\"$xats_agent_id\"" "$@"
     fi
 }
@@ -251,13 +228,35 @@ Or with an explicit team:
 
 If you don't give a team, the agent uses your current working directory's basename — so you typically don't need to think about it.
 
-### Cross-device communication
+### Talk to other agents
+
+Address by name, by team, or by role:
+
+> Send a message to bob: how is the migration going?
+>
+> Tell my team I'm starting the deploy.
+>
+> Send the frontend role a heads-up that the API will change.
+>
+> What's in my inbox?
+
+The agent picks the right tool (`send_message`, `broadcast`, `broadcast_to_role`, `get_inbox`).  Outgoing messages also wake the recipient automatically — you don't need a separate poke.
 
-Cross-device messaging needs three coordinated changes — **daemon bind**, **peer `.mcp.json`**, and **agent registration**. Pure single-host users can ignore this entire section; the new `device` axis is invisible in loopback-only setups.
+### See who else is around
 
-#### 1. Daemon-side: bind beyond loopback
+> Who else is registered on xats?
+>
+> List agents on team backend.
 
-Stop the daemon and restart with a non-loopback `--host` and a `--token`. The token is mandatory whenever `--host` is non-loopback — the daemon refuses to start otherwise (`token_required_for_non_loopback_bind`). Optionally set `--device` for the daemon-host label (defaults to `os.hostname()` lowercased with `[^a-z0-9_-]` replaced by `-`):
+## 4. Cross-host / cross-device collaboration
+
+Most users only need the single-host setup above; the `device` axis is invisible in loopback-only setups and you can skip this entire section.  Read on only if you want agents on multiple physical machines (LAN, tailscale, etc.) to share one daemon.
+
+The setup needs three coordinated changes — **daemon bind**, **peer `.mcp.json`**, and **agent registration**.  Agents are namespaced by `(device, team, name)`: a bare `send_message({to_agent_name:"creator"})` resolves on the caller's own device, while `creator:host-b` addresses a same-team agent on another device.
+
+### 1. Daemon-side: bind beyond loopback
+
+Stop the daemon and restart with a non-loopback `--host` and a `--token`.  The token is mandatory whenever `--host` is non-loopback — the daemon refuses to start otherwise (`token_required_for_non_loopback_bind`).  Optionally set `--device` for the daemon-host label (defaults to `os.hostname()` lowercased with `[^a-z0-9_-]` replaced by `-`):
 
 ```bash
 npx -y cross-agent-teams-mcp@latest daemon \
@@ -267,9 +266,9 @@ npx -y cross-agent-teams-mcp@latest daemon \
   --device host-a
 ```
 
-Use a specific LAN IP (e.g. `10.0.0.10`) or a tailscale CGNAT IP (`100.x.x.x`) instead of `0.0.0.0` if you want to restrict the listener. macOS will prompt to allow node to accept network connections on the first non-loopback bind.
+Use a specific LAN IP (e.g. `10.0.0.10`) or a tailscale CGNAT IP (`100.x.x.x`) instead of `0.0.0.0` if you want to restrict the listener.  macOS will prompt to allow node to accept network connections on the first non-loopback bind.
 
-#### 2. Peer-side: `.mcp.json` updates
+### 2. Peer-side: `.mcp.json` updates
 
 Each remote teammate's Claude Code needs **two** changes from the default loopback config: the HTTP entry must carry an `Authorization: Bearer …` header, and the channel proxy must pass `--token` AND `--device`:
 
@@ -309,47 +308,38 @@ bearer_token_env_var = "XATS_TOKEN"
 
 The **daemon-side** `.mcp.json` (the machine running the daemon) needs the same `headers.Authorization` because the daemon now requires the token on every request, even loopback ones — once `--token` is set, no path through `/mcp` is unauthenticated.
 
-#### 3. Agent registration
+### 3. Agent registration
 
-Restart Claude Code (or codex) on the peer machine so the channel proxy spawns with the new `--device` argument. The proxy's startup hint then embeds the device verbatim, and the user's reply contains it too:
+Restart Claude Code (or codex) on the peer machine so the channel proxy spawns with the new `--device` argument.  The proxy's startup hint then embeds the device verbatim, and the user's reply contains it too:
 
 > Register me to xats as alice, device host-b.
 
-If a remote `register_agent` call omits `device`, the daemon rejects with `device_required_from_remote` — the agent must self-declare. `device` becomes part of the identity tuple `(device, team, name)`, so two physical machines can each host a `creator` in `team=default` without collision.
+If a remote `register_agent` call omits `device`, the daemon rejects with `device_required_from_remote` — the agent must self-declare.  `device` becomes part of the identity tuple `(device, team, name)`, so two physical machines can each host a `creator` in `team=default` without collision.
 
-#### 4. Addressing across devices
+### 4. Addressing across devices
 
 Once everyone is registered, use the `name:device` suffix to address a same-team agent on another device:
 
 > Send creator on host-a a message: build is green.
 
-This resolves to `creator:host-a` and routes to that exact `(device=host-a, team=…, name=creator)` row. A bare `creator` always resolves on the caller's own device.
+This resolves to `creator:host-a` and routes to that exact `(device=host-a, team=…, name=creator)` row.  A bare `creator` always resolves on the caller's own device.
 
 Notes:
 
 - `list_agents` returns a `device` field on every entry — use it to see which devices contribute to your team and to compose the right `name:device` target.
-- `get_inbox` returns `from_name` and `from_device` on every message. When replying via `send_message`, if `from_device !== <your device>` use `from_name:from_device`; otherwise the bare name is correct. `send_message_by_id({to_agent_id: from_agent_id, ...})` is the device-agnostic safe fallback.
-- Security caveat: the bearer token is shared across everyone who can reach the daemon. Treat LAN exposure as a trusted-team boundary; there is no per-agent auth, device whitelist, or TLS in this mode.
-
-### Talk to other agents
+- `get_inbox` returns `from_name` and `from_device` on every message.  When replying via `send_message`, if `from_device !== <your device>` use `from_name:from_device`; otherwise the bare name is correct.  `send_message_by_id({to_agent_id: from_agent_id, ...})` is the device-agnostic safe fallback.
+- Security caveat: the bearer token is shared across everyone who can reach the daemon.  Treat LAN exposure as a trusted-team boundary; there is no per-agent auth, device whitelist, or TLS in this mode.
+- Upgrade note: the first startup after introducing the `device` axis auto-migrates the storage schema from `(team, name)` identity to `(device, team, name)` identity and backfills existing rows with the daemon's local `--device` label.  Rolling back after registering multiple devices with the same `(team, name)` can violate the old uniqueness assumption.
 
-Address by name, by team, or by role:
+### 5. Codex-specific gotchas under cross-device setups
 
-> Send a message to bob: how is the migration going?
->
-> Tell my team I'm starting the deploy.
->
-> Send the frontend role a heads-up that the API will change.
->
-> What's in my inbox?
+The `--token` + Codex `--remote` combination surfaces three caveats that don't show up in loopback-only single-device setups:
 
-The agent picks the right tool (`send_message`, `broadcast`, `broadcast_to_role`, `get_inbox`).  Outgoing messages also wake the recipient automatically — you don't need a separate poke.
+- **App-server env is frozen at launch.**  `codex app-server --listen ...` inherits its environment from the shell that started it.  If you set `bearer_token_env_var = "XATS_TOKEN"` and later `export XATS_TOKEN=…` in another shell, the running app-server still doesn't see it — Codex MCP startup fails with `Deserialize error: data did not match any variant of untagged enum JsonRpcMessage` (codex tries to parse the daemon's 401 body as a JSON-RPC frame).  Restart the app-server from a shell that already has `XATS_TOKEN` exported.
 
-### See who else is around
+- **`--remote` hijacks the working directory.**  Under `codex --remote …` the session cwd is the **app-server's** cwd, not the TUI's — so a launcher invoked from any directory ends up wherever the app-server was started.  Pass `-C "$PWD"` to the `codex` command (already in the launcher above) to override per-session.
 
-> Who else is registered on xats?
->
-> List agents on team backend.
+- **Project-level `.codex/config.toml` overlays the global one.**  A stale per-project block — especially in an iCloud / Dropbox-synced project directory shared between machines — can shadow your global auth setup and produce a failed MCP server name you don't recognize.  Symptom: codex reports a startup failure for a server that doesn't appear in `codex mcp list` (which only reflects the global config).  Audit with `find ~ -path '*/.codex/config.toml' -print` and remove or update stale entries.
 
 ## More
 

package/README.zh-CN.md

@@ -65,32 +65,7 @@ daemon 默认监听 `127.0.0.1:9100`.  MCP endpoint: `http://127.0.0.1:9100/mcp`
 - `--db <path>` (默认 `~/.cross-agent-teams-mcp/data.db`)
 - `--pid-file <path>` (默认 `~/.cross-agent-teams-mcp/daemon.pid`)
 
-### 跨主机 (LAN) 协作
-
-要让可信局域网里另一台机器上的 agent 使用这个 daemon, 把 daemon 绑定到 LAN 地址并设置共享 bearer token:
-
-```bash
-npx -y cross-agent-teams-mcp@latest daemon \
-  --host 10.0.0.10 \
-  --port 9100 \
-  --token "$XATS_TOKEN" \
-  --device host-a
-```
-
-然后在对端机器上让 Claude Code channel proxy 连回这个 daemon:
-
-```bash
-npx -y -p cross-agent-teams-mcp@latest cross-agent-teams-channel \
-  --daemon-url http://10.0.0.10:9100/mcp \
-  --token "$XATS_TOKEN" \
-  --device host-b
-```
-
-agent 身份现在按 `(device, team, name)` 命名空间区分.  裸的 `send_message({to_agent_name:"creator"})` 会解析到调用者自己的 device; 要发给另一个 device 上同 team 的 agent, 用 `creator:host-b`.  `list_agents` 会显示 `device` 字段, 方便拼出这个地址.
-
-安全说明: 非 loopback 的 `--host` 必须带 `--token`, 并且这个 token 会被所有能使用该 daemon 的人共享.  LAN 暴露只适合可信团队环境; 当前模式没有 per-agent 鉴权, device 白名单或 TLS.
-
-升级说明: 升级到这个版本后首次启动会自动迁移存储 schema, 把身份从 `(team, name)` 改为 `(device, team, name)`, 并用 daemon 本机的 `--device` 标签回填旧数据.  如果已经注册了多个 device 上相同 `(team, name)` 的 agent 再回滚, 可能违反旧版本的唯一性假设.
+多主机 / 多设备 (LAN, tailscale 等) 场景请看下面的 [第 4 节](#4-跨主机--跨设备协作).
 
 ## 2. 在 agent 端配置 MCP client
 
@@ -160,7 +135,7 @@ url = "http://127.0.0.1:9100/mcp"
 
 `experimental_use_rmcp_client = true` 必须放在**顶级**, 缺这条 streamable-http MCP 加载不了.
 
-(daemon 带了 `--token <t>` 时, 加 `[mcp_servers.cross-agent-teams-mcp.headers]` 和 `Authorization = "Bearer <t>"`.)
+daemon 带了 `--token <t>` 时: 在启动 codex 的 shell 里 `export XATS_TOKEN=<t>`, 然后在 `[mcp_servers.cross-agent-teams-mcp]` 块里加 `bearer_token_env_var = "XATS_TOKEN"`.  (Codex 0.130+ 会**静默忽略**老写法 `[mcp_servers.X.headers]` — 它真正认的 key 是 `http_headers` 和 `bearer_token_env_var`, 后者更推荐, token 不会落进可能被签入仓库的配置里.)
 
 这种最小配置下 `send_message` 给这个 codex 会写邮箱, 但需要手动调 `get_inbox` 拉读, 没有跨会话 push 唤醒.
 
@@ -210,10 +185,12 @@ free-xats-codex() {
     if [[ -n "$codex_home" ]]; then
         CODEX_HOME="$codex_home" exec codex \
             --remote ws://127.0.0.1:8799 \
+            -C "$PWD" \
             -c xats.agent_id="\"$xats_agent_id\"" "$@"
     else
         exec codex \
             --remote ws://127.0.0.1:8799 \
+            -C "$PWD" \
             -c xats.agent_id="\"$xats_agent_id\"" "$@"
     fi
 }
@@ -251,11 +228,33 @@ agent 第一次连上 xats 时不会自动注册, 要等你开口.  直接说:
 
 不传 team 的话, agent 会用当前工作目录的 basename 作为默认 team — 一般情况下你不用操心.
 
-### 跨设备 (device) 通信
+### 跟其它 agent 对话
+
+按名字, 按 team, 按 role 都行:
+
+> Send a message to bob: how is the migration going?
+>
+> Tell my team I'm starting the deploy.
+>
+> Send the frontend role a heads-up that the API will change.
+>
+> What's in my inbox?
+
+agent 会自动挑对应工具 (`send_message`, `broadcast`, `broadcast_to_role`, `get_inbox`).  发消息的同时会自动唤醒收件人, 不用单独再 poke.
 
-跨设备通信需要三处配套修改 — **daemon bind**, **远端 `.mcp.json`**, **agent 注册**.  纯单机用户可以完全跳过本节, loopback 场景下 device 这个轴是透明的.
+### 看看还有谁在线
 
-#### 1. Daemon 侧: bind 到非 loopback
+> Who else is registered on xats?
+>
+> List agents on team backend.
+
+## 4. 跨主机 / 跨设备协作
+
+大部分用户只用单机就够了, loopback 场景下 `device` 这个轴是透明的, 本节可以完全跳过.  只有当你想让多台物理机器 (LAN, tailscale 等) 共享一个 daemon 时, 才需要往下看.
+
+跨设备需要三处配套修改 — **daemon bind**, **远端 `.mcp.json`**, **agent 注册**.  agent 身份按 `(device, team, name)` 命名空间区分: 裸的 `send_message({to_agent_name:"creator"})` 解析到调用者自己的 device, 用 `creator:host-b` 可以指到另一个 device 上同 team 的 agent.
+
+### 1. Daemon 侧: bind 到非 loopback
 
 停掉旧 daemon, 用非 loopback `--host` 和 `--token` 重启.  `--host` 非 loopback 时 `--token` **必填**, 否则 daemon 拒绝启动 (`token_required_for_non_loopback_bind`).  `--device` 可选, 不传则从 daemon 主机的 hostname 派生 (小写 + 非 `[a-z0-9_-]` 替换为 `-`):
 
@@ -269,7 +268,7 @@ npx -y cross-agent-teams-mcp@latest daemon \
 
 想限定监听接口, 把 `0.0.0.0` 换成具体 LAN IP (例如 `10.0.0.10`) 或者 tailscale CGNAT IP (`100.x.x.x`) 都行.  macOS 第一次绑非 loopback 端口会弹"允许 node 接受网络连接", 选允许.
 
-#### 2. 远端机器侧: 改 `.mcp.json`
+### 2. 远端机器侧: 改 `.mcp.json`
 
 每台远端同事的 Claude Code 相对默认 loopback 配置都要改两处 — HTTP 入口加 `Authorization: Bearer …` 头, channel proxy 加 `--token` 和 `--device`:
 
@@ -309,7 +308,7 @@ bearer_token_env_var = "XATS_TOKEN"
 
 **daemon 所在机器** (host-a 这台) 的 `.mcp.json` 同样需要加 `headers.Authorization` — daemon 一旦设了 `--token`, 所有 `/mcp` 请求 (包括 loopback) 都要带 token, 没例外.
 
-#### 3. Agent 注册
+### 3. Agent 注册
 
 重启远端的 Claude Code (或 codex), channel proxy 用新的 `--device` 启动后, startup hint 会把 device 直接嵌进引导文案, 用户回复时一并带上即可:
 
@@ -317,7 +316,7 @@ bearer_token_env_var = "XATS_TOKEN"
 
 如果远端 `register_agent` 不传 device, daemon 回 `device_required_from_remote` 直接拒.  device 进入身份键 `(device, team, name)`, 所以两台机器都可以有 `team=default` 下的 `creator`, 不会撞名.
 
-#### 4. 跨设备寻址
+### 4. 跨设备寻址
 
 注册完成后, 用 `name:device` 后缀寻址同 team 不同 device 的 agent:
 
@@ -330,26 +329,17 @@ bearer_token_env_var = "XATS_TOKEN"
 - `list_agents` 每条返回都有 `device` 字段, 用它看清 team 里哪些 device 在贡献 agent, 再拼对的 `name:device`.
 - `get_inbox` 每条消息都带 `from_name` 和 `from_device`.  回复时如果 `from_device !== 自己 device`, 用 `from_name:from_device`; 同 device 用裸名即可.  `send_message_by_id({to_agent_id: from_agent_id, ...})` 是 device 无关的安全兜底.
 - 安全提醒: bearer token 在能连到 daemon 的所有人之间共享, 把 LAN 暴露当作可信团队边界处理 — 本模式没有 per-agent 鉴权, 没有 device 白名单, 也没有 TLS.
+- 升级说明: 引入 `device` 轴之后首次启动会自动迁移存储 schema, 把身份从 `(team, name)` 改为 `(device, team, name)`, 并用 daemon 本机的 `--device` 标签回填旧数据.  如果已经注册了多个 device 上相同 `(team, name)` 的 agent 再回滚, 可能违反旧版本的唯一性假设.
 
-### 跟其它 agent 对话
-
-按名字, 按 team, 按 role 都行:
+### 5. 跨设备场景下 Codex 特有的坑
 
-> Send a message to bob: how is the migration going?
->
-> Tell my team I'm starting the deploy.
->
-> Send the frontend role a heads-up that the API will change.
->
-> What's in my inbox?
+`--token` + Codex `--remote` 模式下会暴露三个本地单设备 setup 看不到的问题:
 
-agent 会自动挑对应工具 (`send_message`, `broadcast`, `broadcast_to_role`, `get_inbox`).  发消息的同时会自动唤醒收件人, 不用单独再 poke.
+- **app-server 的 env 在启动时固化**.  `codex app-server --listen ...` 继承启动它那个 shell 的环境.  你在另一个 shell `export XATS_TOKEN=…` 之后, 已经在跑的 app-server 看不到 —— codex MCP 握手时报 `Deserialize error: data did not match any variant of untagged enum JsonRpcMessage` (codex 把 daemon 返回的 401 body 当 JSON-RPC 帧解析失败).  解决: 在已经 `export` 好 `XATS_TOKEN` 的 shell 里重启 app-server.
 
-### 看看还有谁在线
+- **`--remote` 会劫持工作目录**.  `codex --remote …` 下 session 的 cwd 是 **app-server 进程的 cwd**, 不是 TUI 的, 所以 launcher 无论在哪个目录跑都会落回 app-server 启动时的目录.  在 `codex` 命令上加 `-C "$PWD"` 覆盖 (上面 launcher 已经带了).
 
-> Who else is registered on xats?
->
-> List agents on team backend.
+- **项目级 `.codex/config.toml` 会覆盖全局**.  陈旧的 per-project 配置块 —— 尤其在 iCloud / Dropbox 之类跨机同步的目录里 —— 会盖掉你的全局鉴权设置, 报错形如某个 `codex mcp list` (只反映全局) 里看不到的 server 名启动失败.  审计: `find ~ -path '*/.codex/config.toml' -print`, 删掉或更新陈旧条目.
 
 ## 更多