Skip to content

fix: consume Codex per-call _meta.threadId in the MCP shim (#2024) - #2026

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-04_codex-mcp-threadid
Oct 4, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-04_codex-mcp-threadid

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What & why

Codex ≥0.160 stamps the real thread id on every tools/call via _meta.threadId (codex-rs core/src/mcp_tool_call.rs with_mcp_tool_call_ids_meta; its sessionId is a transient run id and is deliberately NOT consumed). The MCP shim ignored it entirely and kept routing through the stale BILI_CONVERSATION_ID baked into the generated Codex MCP config — so in Code Mode (where the inner compress call never appears as an independent upstream function_call, hence no outbound witness either) every compress/decompress/status/cache/search call failed with unknown plugin conversation. Incident evidence + reproducible PoC: #2024.

Fix at the shared tool entry (all five tools), not a compress special-case:

  • src/mcp.ts — consume strictly-validated per-call _meta.threadId (non-empty string after trim; anything else is treated as ABSENT so malformed metadata can never shadow the legacy channels). Per-call only: never written back to the shim's global conversationId (main/sub-agent threads sharing one MCP process must not clobber each other's binding). The host-stamped origin is flagged to the proxy as nativeCaller in the POST body. The feat: 支持 search_context 显式查询历史 session #841 search-target exception is extended so a native caller keeps args.conversation_id as a read-only cross-session target even when NO default binding exists (previously the target would have been mistaken for the caller).
  • src/plugin.ts — routing ladder gains rung 0: a host-stamped nativeCaller outranks a conflicting unique outbound witness (a collision, not truth — the issue's explicit boundary). Unmarked ids keep the exact 零注入会话身份:移除模型可见 conversation_id,以出站 tool_use 环见证路由 MCP 工具调用(fixes #1611 的非注入路线) #1685 precedence (witness still beats model-transcribed/static ids — flipping that would regress stale-model-id cases). An unresolvable native id fails loudly (404 + 方式一安装的dsh 原生插件:llm-pi-ai 传输(OpenAI SDK + options.fetch 注入)绕过 globalThis.fetch 拦截,模型请求不进代理、压缩完全不生效 #1158 diagnostic) — no witness rescue, no sibling adoption.
  • tests/mcp-native-thread.test.ts — three layers: shim contract (real src/mcp.ts over stdio against a mock proxy capturing the exact POST bodies), proxy routing policy (real startServer: native-vs-conflicting-witness, unmarked-control, loud-failure legs), and the incident-shape e2e leg (real server + real shim over stdio with a stale env id, interleaved main/child threads, meta-less call still failing against the untouched residue).
  • CLIENTS.md / CLIENTS.zh-CN.md — document the new channel for codex (zh/en synced).

Behavior changes (old → new, all intentional)

  1. New wire field nativeCaller on POST /__bili/plugin/tool — set ONLY by the MCP shim and ONLY when the id came from _meta.threadId. Old proxies ignore the unknown field; old shims never send it. Not a config surface (no env/config.json/CLI changes).
  2. Routing precedence: before, a unique outbound witness beat ANY differing body id. Now, for flagged calls only, the host-stamped id wins over a conflicting unique witness; unflagged calls are byte-for-byte unchanged (零注入会话身份:移除模型可见 conversation_id,以出站 tool_use 环见证路由 MCP 工具调用(fixes #1611 的非注入路线) #1685 control leg pinned in tests).
  3. search_context without any default binding + valid _meta.threadId: before, args.conversation_id was the routing fallback (then stripped); now the call routes to the native thread and the target stays read-only in args. Only affects hosts sending Codex-style per-call metadata (new capability); legacy hosts unchanged.
  4. New warn log line on a witness/native conflict; execution log can now read routed by native.

Verification

  • Issue PoC baseline vs master dist 38536f4c: reproduced — "published bridge ignores native threadId" (5/5 baseline checks show the stale-env failure shape); after the fix the PoC trips its own Published bridge changed guard, as designed.
  • npm run typecheck clean.
  • Targeted: tests/mcp-native-thread.test.ts 8/8; neighbors 67/67 (e2e-plugin-tool-routing test: e2e the #1685 plugin tool routing ladder + MCP shim lane #1773, issue760-percall-conversation, search-context-cross-session, tool-ring, tool-witness-pipes, plugin-protocol, zcode-mcp-degraded).
  • Built artifact probe: fresh dist/mcp.js over stdio routes _meta.threadId natively and keeps the legacy env binding when meta is absent (2/2).

Closes #2024

Codex >=0.160 stamps the real thread id on every tools/call via _meta.threadId (codex-rs core/src/mcp_tool_call.rs with_mcp_tool_call_ids_meta; its sessionId is a transient run id and is deliberately not consumed). The shim ignored it and kept routing through the stale BILI_CONVERSATION_ID baked into the generated MCP config, so Code Mode compress calls failed with 'unknown plugin conversation'.

- src/mcp.ts: consume strictly-validated per-call _meta.threadId (non-empty string after trim; malformed/absent metadata leaves the legacy channels untouched), per call only — never written back to the global binding; flag host-stamped origin as nativeCaller in the POST body; extend the #841 search-target exception so a native caller keeps args.conversation_id read-only even without a default binding.

- src/plugin.ts: routing ladder rung 0 — a host-stamped nativeCaller outranks a conflicting unique outbound witness (a collision, not truth); unmarked ids keep the exact #1685 precedence; an unresolvable native id fails loudly (404 + #1158 diagnostic) with no witness rescue and no sibling adoption.

- tests/mcp-native-thread.test.ts: shim contract against a mock proxy capturing POST bodies, proxy routing policy on a real startServer, and the incident-shape e2e leg (real server + real shim over stdio, interleaved main/child threads).

- CLIENTS.md / CLIENTS.zh-CN.md: document the new channel for codex.
@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-04_codex-mcp-threadid (2206434)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2060-pr.2026.346d089

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2026.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷

已完成开发并提 PR:**https://github.com/ranxianglei/billion-context/pull/2027**(Closes #2024)。分支 2026-10-04_codex-mcp-native-threadid,已 rebase 到当前 master(ec95a6d4)后在 rebased head 上验证。

结构化七问

  1. 是什么问题:Codex ≥0.160 在每次 MCP tools/call 上盖真实线程 id(_meta.threadId),但 MCP shim 完全忽略它,仍走生成配置里烘焙的、已过期的 BILI_CONVERSATION_ID 路由。于是 Code Mode(内部压缩调用从不作为独立上游 function_call 出现,也没有出站 witness)下,compress/decompress/status/cache/search 全部报 unknown plugin conversation。

  2. 什么原因导致的:路由身份取自「烘焙进配置的静态 env」而非「宿主每次调用盖章的真实线程 id」。根因层次——不是某个工具没处理,而是共享工具入口整体没有消费宿主盖章的 per-call 身份通道:witness 机制在此场景拿不到(没有独立上游请求),static env 又已被复用/过期,两条既有通道同时失效。

  3. 怎么修复的:在共享工具入口(五个工具统一)加一条权威通道,而非给 compress 打补丁。shim 严格校验 per-call _meta.threadId(非空字符串,否则视为 ABSENT,畸形元数据绝不遮蔽 legacy 通道),仅逐调用生效(绝不写回全局绑定 → 主/子代理线程互不覆盖),并在 POST body 标记 nativeCaller;proxy 路由阶梯加 rung 0——flagged 的 nativeCaller 压过冲突的唯一出站 witness,未标记调用保持 零注入会话身份:移除模型可见 conversation_id,以出站 tool_use 环见证路由 MCP 工具调用(fixes #1611 的非注入路线) #1685 原优先级字节不变;无法解析的 native id 大声失败(404+方式一安装的dsh 原生插件:llm-pi-ai 传输(OpenAI SDK + options.fetch 注入)绕过 globalThis.fetch 拦截,模型请求不进代理、压缩完全不生效 #1158 诊断),不做 witness 救援/兄弟收养。另把 feat: 支持 search_context 显式查询历史 session #841 搜索目标例外扩展:native caller 在无默认绑定时也把 args.conversation_id 当只读跨会话目标保留。测试三层:shim 契约 / proxy 路由策略 / 事故形态 e2e。

  4. 是否有回归问题:无。逐项过既有行为——(a) 未标记调用路径字节级不变(新增 unmarked-control 测试腿钉死 零注入会话身份:移除模型可见 conversation_id,以出站 tool_use 环见证路由 MCP 工具调用(fixes #1611 的非注入路线) #1685 witness>body-id 优先级);(b) legacy host(不发 codex 风格元数据)wire 完全不变(旧 proxy 忽略未知字段、旧 shim 从不发 nativeCaller);(c) 孤儿收养重试天然排除 native caller(其必带 routeOverride)。本地定向验证:新测试 7/7、邻居(routing test: e2e the #1685 plugin tool routing ladder + MCP shim lane #1773 / shim feat: per-call conversation_id for MCP tools — let the model supply its session id #760 / tool-ring / witness-pipes / search-cross-session)49/49、typecheck 干净、build 成功;全量回归交 CI。
    行为变更清单(old→new,均有意):① 新 wire 字段 nativeCaller(仅 shim、且仅来自 _meta.threadId 时置位);② flagged 调用改由宿主盖章 id 胜过冲突 witness(未 flagged 不变);③ 无默认绑定 + 有效 _meta.threadId 时 search_context 路由到 native 线程并保留只读目标(原先该 arg 是路由 fallback、后被剥除);④ witness/native 冲突新增一行 warn 日志,执行日志可读 routed by native。

  5. 是否破坏缓存:不涉及。未触碰压缩缓存/前缀缓存/会话持久化格式或版本;native 路由只是按正确 key 解析已有会话,不改变任何缓存键或失效策略。

  6. 是否改了设计方向:不涉及架构转向。在既有「per-call 身份通道」体系内新增一条宿主盖章来源(与 feat: per-call conversation_id for MCP tools — let the model supply its session id #760 per-call arg、零注入会话身份:移除模型可见 conversation_id,以出站 tool_use 环见证路由 MCP 工具调用(fixes #1611 的非注入路线) #1685 witness、single-active arbitration 并列),边界明确(rung 0 仅限 flagged 调用),不污染其它 host 的路由语义。

  7. 是否引入了新的配置:无。nativeCaller 是 wire 字段(仅 shim 置位),非 env/config.json/CLI,无迁移。config surface:无变更。

判定:可合并。PR #2027 已开(base=master ec95a6d4,head 1460932b),mergeable 待 GitHub 异步计算;CI 全量回归通过后请 owner 合入。

@ranxianglei
ranxianglei merged commit 1d95d31 into master Oct 4, 2026
15 checks passed
@ranxianglei
ranxianglei deleted the 2026-10-04_codex-mcp-threadid branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex Code Mode 压缩失败:MCP shim 忽略每次调用的 _meta.threadId,错误使用过期 env ID

1 participant