cross-agent-teams-mcp 0.5.8 → 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 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
 
@@ -251,13 +226,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:
 
-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.
+> 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?
 
-#### 1. Daemon-side: bind beyond loopback
+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.
 
-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 `-`):
+### See who else is around
+
+> Who else is registered on xats?
+>
+> 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 \
@@ -267,9 +264,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 +306,28 @@ 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
-
-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.
-
-### See who else is around
-
-> Who else is registered on xats?
->
-> List agents on team backend.
+- `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
 

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
 
@@ -251,11 +226,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?
 
-跨设备通信需要三处配套修改 — **daemon bind**, **远端 `.mcp.json`**, **agent 注册**.  纯单机用户可以完全跳过本节, loopback 场景下 device 这个轴是透明的.
+agent 会自动挑对应工具 (`send_message`, `broadcast`, `broadcast_to_role`, `get_inbox`).  发消息的同时会自动唤醒收件人, 不用单独再 poke.
 
-#### 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 +266,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 +306,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 +314,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 +327,7 @@ 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.
-
-### 跟其它 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.
-
-### 看看还有谁在线
-
-> Who else is registered on xats?
->
-> List agents on team backend.
+- 升级说明: 引入 `device` 轴之后首次启动会自动迁移存储 schema, 把身份从 `(team, name)` 改为 `(device, team, name)`, 并用 daemon 本机的 `--device` 标签回填旧数据.  如果已经注册了多个 device 上相同 `(team, name)` 的 agent 再回滚, 可能违反旧版本的唯一性假设.
 
 ## 更多
 

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.",