cross-agent-teams-mcp 0.5.9 → 0.5.11

package/README.md

@@ -135,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.
 
@@ -185,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
 }
@@ -329,6 +331,16 @@ Notes:
 - 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.
 
+### 5. Codex-specific gotchas under cross-device setups
+
+The `--token` + Codex `--remote` combination surfaces three caveats that don't show up in loopback-only single-device setups:
+
+- **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.
+
+- **`--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.
+
+- **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
 
 - Full tool reference and schema: launch the daemon and call `tools/list` on the MCP endpoint.

package/README.zh-CN.md

@@ -135,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 唤醒.
 
@@ -185,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
 }
@@ -329,6 +331,16 @@ bearer_token_env_var = "XATS_TOKEN"
 - 安全提醒: bearer token 在能连到 daemon 的所有人之间共享, 把 LAN 暴露当作可信团队边界处理 — 本模式没有 per-agent 鉴权, 没有 device 白名单, 也没有 TLS.
 - 升级说明: 引入 `device` 轴之后首次启动会自动迁移存储 schema, 把身份从 `(team, name)` 改为 `(device, team, name)`, 并用 daemon 本机的 `--device` 标签回填旧数据.  如果已经注册了多个 device 上相同 `(team, name)` 的 agent 再回滚, 可能违反旧版本的唯一性假设.
 
+### 5. 跨设备场景下 Codex 特有的坑
+
+`--token` + Codex `--remote` 模式下会暴露三个本地单设备 setup 看不到的问题:
+
+- **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 已经带了).
+
+- **项目级 `.codex/config.toml` 会覆盖全局**.  陈旧的 per-project 配置块 —— 尤其在 iCloud / Dropbox 之类跨机同步的目录里 —— 会盖掉你的全局鉴权设置, 报错形如某个 `codex mcp list` (只反映全局) 里看不到的 server 名启动失败.  审计: `find ~ -path '*/.codex/config.toml' -print`, 删掉或更新陈旧条目.
+
 ## 更多
 
 - 完整工具列表和参数: 启动 daemon 后调 MCP endpoint 的 `tools/list`.