cross-agent-teams-mcp 0.5.7 → 0.5.9

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 192.168.1.10 \
-  --port 9100 \
-  --token "$XATS_TOKEN" \
-  --device jt-laptop
-```
-
-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://192.168.1.10:9100/mcp \
-  --token "$XATS_TOKEN" \
-  --device gx-laptop
-```
-
-Agents are namespaced by `(device, team, name)`.  A bare `send_message({to_agent_name:"creator"})` resolves on the caller's own device; use `creator:gx-laptop` 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
 
@@ -251,25 +226,6 @@ 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
-
-When an agent connects to a daemon running on **another machine** (the Cross-host (LAN) section above), it must self-declare a `device` label at registration:
-
-> Register me to xats as alice, device gx-laptop.
-
-That label becomes part of the agent's identity — `(device, team, name)` — so two physical machines can both have a `creator` in `team=default` without collision.  Once registered with a device, addressing across devices uses a `name:device` suffix:
-
-> Send creator on jt-laptop a message: build is green.
-
-This resolves to `creator:jt-laptop` and routes to that exact `(device=jt-laptop, team=…, name=creator)` row.  Bare `creator` resolves on the caller's own device.
-
-Notes:
-
-- The daemon's local label is set with its own `--device` flag (defaults to the daemon host's hostname normalized to lowercase + `-`).  Local-loopback agents auto-fill that label and don't need to specify `device` on register.
-- A remote register call that omits `device` is rejected with `device_required_from_remote`; the channel proxy's startup hint surfaces the configured device value so the agent prompt includes it verbatim.
-- `list_agents` returns a `device` field on every entry so you can see which devices contribute to your team and pick the right `name:device` target.
-- The channel proxy's `--device` flag (`cross-agent-teams-channel --device gx-laptop ...`) sets the device label for the proxy row and is propagated into the registration hint surfaced to the agent.  Match it to whatever label you want your machine's agents to appear under.
-
 ### Talk to other agents
 
 Address by name, by team, or by role:
@@ -290,6 +246,89 @@ The agent picks the right tool (`send_message`, `broadcast`, `broadcast_to_role`
 >
 > List agents on team backend.
 
+## 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 \
+  --host 0.0.0.0 \
+  --port 9100 \
+  --token "$XATS_TOKEN" \
+  --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.
+
+### 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`:
+
+```json
+{
+  "mcpServers": {
+    "cross-agent-teams": {
+      "type": "http",
+      "url": "http://10.0.0.10:9100/mcp",
+      "headers": {
+        "Authorization": "Bearer xats"
+      }
+    },
+    "cross-agent-teams-channel": {
+      "command": "npx",
+      "args": [
+        "-y", "-p", "cross-agent-teams-mcp@latest",
+        "cross-agent-teams-channel",
+        "--daemon-url", "http://10.0.0.10:9100/mcp",
+        "--token", "xats",
+        "--device", "host-b"
+      ]
+    }
+  }
+}
+```
+
+For Codex CLI, edit `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.cross-agent-teams-mcp]
+url = "http://10.0.0.10:9100/mcp"
+bearer_token_env_var = "XATS_TOKEN"
+```
+
+…and `export XATS_TOKEN=xats` before launching codex.
+
+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
+
+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.
+
+### 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.
+
+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.
+- 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.
+
 ## More
 
 - Full tool reference and schema: launch the daemon and call `tools/list` on the MCP endpoint.

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 192.168.1.10 \
-  --port 9100 \
-  --token "$XATS_TOKEN" \
-  --device jt-laptop
-```
-
-然后在对端机器上让 Claude Code channel proxy 连回这个 daemon:
-
-```bash
-npx -y -p cross-agent-teams-mcp@latest cross-agent-teams-channel \
-  --daemon-url http://192.168.1.10:9100/mcp \
-  --token "$XATS_TOKEN" \
-  --device gx-laptop
-```
-
-agent 身份现在按 `(device, team, name)` 命名空间区分.  裸的 `send_message({to_agent_name:"creator"})` 会解析到调用者自己的 device; 要发给另一个 device 上同 team 的 agent, 用 `creator:gx-laptop`.  `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
 
@@ -251,25 +226,6 @@ agent 第一次连上 xats 时不会自动注册, 要等你开口.  直接说:
 
 不传 team 的话, agent 会用当前工作目录的 basename 作为默认 team — 一般情况下你不用操心.
 
-### 跨设备 (device) 通信
-
-当 agent 连的是**另一台机器**上的 daemon (见上方"跨主机 (LAN) 协作"), 它注册时必须自报一个 `device` 标签:
-
-> Register me to xats as alice, device gx-laptop.
-
-这个 device 会进入 agent 的身份键 — `(device, team, name)` — 所以两台机器都可以有 `team=default` 下的 `creator`, 不会撞名.  注册带上 device 之后, 跨设备寻址用 `name:device` 后缀:
-
-> Send creator on jt-laptop a message: build is green.
-
-这条会被解析成 `creator:jt-laptop`, 准确路由到 `(device=jt-laptop, team=…, name=creator)` 这一行.  裸名字 `creator` 默认解析到 caller 自己 device 上的同名 agent.
-
-要点:
-
-- daemon 自己的 device 标签用 `--device` 设置 (不传则从 daemon 主机的 hostname 派生, 小写 + 非 `[a-z0-9_-]` 替换为 `-`).  loopback 进来的 agent 注册时不必传 device, daemon 会自动填上这个值.
-- 远端 (非 loopback) 连接的 agent 注册时**必须**带 device, 否则 daemon 拒绝并返回 `device_required_from_remote`; channel proxy 的 startup hint 会把已配置的 device 值直接写进引导文案, agent 照抄即可.
-- `list_agents` 每条返回都有 `device` 字段, 方便你看清 team 里都有哪些设备贡献了哪些 agent, 进而拼对的 `name:device`.
-- channel proxy 自己的 `--device` 标志 (`cross-agent-teams-channel --device gx-laptop ...`) 决定 proxy 行的 device 字段, 同一台机器上的 agent 一般用同一个 device 名.
-
 ### 跟其它 agent 对话
 
 按名字, 按 team, 按 role 都行:
@@ -290,6 +246,89 @@ agent 会自动挑对应工具 (`send_message`, `broadcast`, `broadcast_to_role`
 >
 > 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_-]` 替换为 `-`):
+
+```bash
+npx -y cross-agent-teams-mcp@latest daemon \
+  --host 0.0.0.0 \
+  --port 9100 \
+  --token "$XATS_TOKEN" \
+  --device host-a
+```
+
+想限定监听接口, 把 `0.0.0.0` 换成具体 LAN IP (例如 `10.0.0.10`) 或者 tailscale CGNAT IP (`100.x.x.x`) 都行.  macOS 第一次绑非 loopback 端口会弹"允许 node 接受网络连接", 选允许.
+
+### 2. 远端机器侧: 改 `.mcp.json`
+
+每台远端同事的 Claude Code 相对默认 loopback 配置都要改两处 — HTTP 入口加 `Authorization: Bearer …` 头, channel proxy 加 `--token` 和 `--device`:
+
+```json
+{
+  "mcpServers": {
+    "cross-agent-teams": {
+      "type": "http",
+      "url": "http://10.0.0.10:9100/mcp",
+      "headers": {
+        "Authorization": "Bearer xats"
+      }
+    },
+    "cross-agent-teams-channel": {
+      "command": "npx",
+      "args": [
+        "-y", "-p", "cross-agent-teams-mcp@latest",
+        "cross-agent-teams-channel",
+        "--daemon-url", "http://10.0.0.10:9100/mcp",
+        "--token", "xats",
+        "--device", "host-b"
+      ]
+    }
+  }
+}
+```
+
+如果远端用的是 Codex CLI, 改 `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.cross-agent-teams-mcp]
+url = "http://10.0.0.10:9100/mcp"
+bearer_token_env_var = "XATS_TOKEN"
+```
+
+启动前 `export XATS_TOKEN=xats`.
+
+**daemon 所在机器** (host-a 这台) 的 `.mcp.json` 同样需要加 `headers.Authorization` — daemon 一旦设了 `--token`, 所有 `/mcp` 请求 (包括 loopback) 都要带 token, 没例外.
+
+### 3. Agent 注册
+
+重启远端的 Claude Code (或 codex), channel proxy 用新的 `--device` 启动后, startup hint 会把 device 直接嵌进引导文案, 用户回复时一并带上即可:
+
+> Register me to xats as alice, device host-b.
+
+如果远端 `register_agent` 不传 device, daemon 回 `device_required_from_remote` 直接拒.  device 进入身份键 `(device, team, name)`, 所以两台机器都可以有 `team=default` 下的 `creator`, 不会撞名.
+
+### 4. 跨设备寻址
+
+注册完成后, 用 `name:device` 后缀寻址同 team 不同 device 的 agent:
+
+> Send creator on host-a a message: build is green.
+
+这条解析成 `creator:host-a`, 路由到 `(device=host-a, team=…, name=creator)` 这一行.  裸名字 `creator` 始终解析到 caller 自己 device.
+
+要点:
+
+- `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 再回滚, 可能违反旧版本的唯一性假设.
+
 ## 更多
 
 - 完整工具列表和参数: 启动 daemon 后调 MCP endpoint 的 `tools/list`.

package/dist/cli.js

@@ -3748,6 +3748,7 @@ function registerBusinessTools(server, db, getCallerAgentId, fanout, onRegisterS
         'Requests such as "register to xats" or "register to cross-agent-teams" refer to this MCP service, not to the `team` field; do not set `team` to `xats` or `cross-agent-teams` from those phrases.',
         'Do not treat the bare word "register" as a request for this tool unless the current conversation is already about cross-agent-teams registration.',
         "When the end user has not explicitly specified `team`, callers should pass `project_dir` as the current working directory so the daemon derives a project-scoped default team from its basename; if omitted, it falls back to `default`.",
+        'REPORTING RULE: on success the response carries the actual `team` the daemon assigned. When summarizing the registration to the user, surface that returned `team` value verbatim; NEVER derive or paraphrase the team from `project_dir`, cwd, or your own pre-call assumption. Failing to read the response masks the daemon\'s `default` fallback (e.g. when `project_dir` was forgotten) and produces misleading "team: X (from cwd basename)" reports that break later cross-team send_message diagnostics.',
         '`agent_type` must describe the runtime behind `ui_pid`, not merely the current MCP caller. For example, if `ui_pid` points at an external editor process, pass `agent_type="custom"` with `agent_type_name=<editor>` even when the registration request is issued from a different harness.',
         "STRONGLY RECOMMENDED: pass `ui_pid` unless it is truly unobtainable (codex callers excepted, see DETECTION step 1). Without it, automatic runtime binding usually fails to converge and tmux-based cross-agent poke delivery stays off until a separate `bind_runtime_identity(...)` call. From Claude Code, `$PPID` inside a Bash tool call is the `claude` CLI pid. With `ui_pid` the daemon binds via verified pid \u2192 tty \u2192 pane evidence in one shot.",
         "After registration, the daemon best-effort attempts runtime binding for recognized local clients so tmux-based poke delivery can come up without a second tool call.",