cross-agent-teams-mcp 0.5.7 → 0.5.8

package/README.md

@@ -71,22 +71,22 @@ To let agents on another trusted machine use this daemon, bind the daemon to a L
 
 ```bash
 npx -y cross-agent-teams-mcp@latest daemon \
-  --host 192.168.1.10 \
+  --host 10.0.0.10 \
   --port 9100 \
   --token "$XATS_TOKEN" \
-  --device jt-laptop
+  --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://192.168.1.10:9100/mcp \
+  --daemon-url http://10.0.0.10:9100/mcp \
   --token "$XATS_TOKEN" \
-  --device gx-laptop
+  --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:gx-laptop` to address a same-team agent on another device.  `list_agents` shows the `device` field so you can compose those addresses.
+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.
 
@@ -253,22 +253,83 @@ If you don't give a team, the agent uses your current working directory's basena
 
 ### 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:
+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.
 
-> Register me to xats as alice, device gx-laptop.
+#### 1. Daemon-side: bind beyond loopback
 
-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:
+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 `-`):
 
-> Send creator on jt-laptop a message: build is green.
+```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:jt-laptop` and routes to that exact `(device=jt-laptop, team=…, name=creator)` row.  Bare `creator` 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:
 
-- 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.
+- `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
 

package/README.zh-CN.md

@@ -71,22 +71,22 @@ daemon 默认监听 `127.0.0.1:9100`.  MCP endpoint: `http://127.0.0.1:9100/mcp`
 
 ```bash
 npx -y cross-agent-teams-mcp@latest daemon \
-  --host 192.168.1.10 \
+  --host 10.0.0.10 \
   --port 9100 \
   --token "$XATS_TOKEN" \
-  --device jt-laptop
+  --device host-a
 ```
 
 然后在对端机器上让 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 \
+  --daemon-url http://10.0.0.10:9100/mcp \
   --token "$XATS_TOKEN" \
-  --device gx-laptop
+  --device host-b
 ```
 
-agent 身份现在按 `(device, team, name)` 命名空间区分.  裸的 `send_message({to_agent_name:"creator"})` 会解析到调用者自己的 device; 要发给另一个 device 上同 team 的 agent, 用 `creator:gx-laptop`.  `list_agents` 会显示 `device` 字段, 方便拼出这个地址.
+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.
 
@@ -253,22 +253,83 @@ agent 第一次连上 xats 时不会自动注册, 要等你开口.  直接说:
 
 ### 跨设备 (device) 通信
 
-当 agent 连的是**另一台机器**上的 daemon (见上方"跨主机 (LAN) 协作"), 它注册时必须自报一个 `device` 标签:
+跨设备通信需要三处配套修改 — **daemon bind**, **远端 `.mcp.json`**, **agent 注册**.  纯单机用户可以完全跳过本节, loopback 场景下 device 这个轴是透明的.
 
-> Register me to xats as alice, device gx-laptop.
+#### 1. Daemon 侧: bind 到非 loopback
 
-这个 device 会进入 agent 的身份键 — `(device, team, name)` — 所以两台机器都可以有 `team=default` 下的 `creator`, 不会撞名.  注册带上 device 之后, 跨设备寻址用 `name:device` 后缀:
+停掉旧 daemon, 用非 loopback `--host` 和 `--token` 重启.  `--host` 非 loopback 时 `--token` **必填**, 否则 daemon 拒绝启动 (`token_required_for_non_loopback_bind`).  `--device` 可选, 不传则从 daemon 主机的 hostname 派生 (小写 + 非 `[a-z0-9_-]` 替换为 `-`):
 
-> Send creator on jt-laptop a message: build is green.
+```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:jt-laptop`, 准确路由到 `(device=jt-laptop, team=…, name=creator)` 这一行.  裸名字 `creator` 默认解析到 caller 自己 device 上的同名 agent.
+这条解析成 `creator:host-a`, 路由到 `(device=host-a, team=…, name=creator)` 这一行.  裸名字 `creator` 始终解析到 caller 自己 device.
 
 要点:
 
-- 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 名.
+- `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 对话
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-agent-teams-mcp",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "MCP daemon for cross-agent collaboration",
   "type": "module",
   "bin": {