[commhub][dx] MCP 工具缺失时提供一等 REST fallback、parent_task_id 链路和任务诊断

[s2agi]

背景

节点 副指挥 收到上游任务：通过 CommHub 询问 通信龙 当前情况。系统指令明确要求使用 CommHub MCP 通信工具：

• mcp_commhub__get_all_status
• mcp_commhub__send_task(alias, task, parent_task_id=$CURRENT_TASK_ID)
• mcp_commhub__get_task(task_id)

但在该 Codex session 的实际工具面板里，mcp_commhub__* 这组工具没有挂载，只能使用 shell/开发工具。因此调用方只能 fallback 到 CommHub REST API：

• GET /api/status
• POST /api/task
• GET /api/tasks

这暴露了 MCP 工具可用性、任务链路、REST fallback 和任务诊断上的缺口。

现象

1. 规范要求使用 MCP，但某些 session 实际没有 MCP 工具

Agent instructions 要求使用 mcp_commhub__send_task/get_task/get_all_status，但某些 Codex session 实际没有挂载这组工具，导致规范路径不可执行。

2. CURRENT_TASK_ID 为空，无法传 parent_task_id

系统指令要求：

mcp_commhub__send_task(alias, task, parent_task_id=$CURRENT_TASK_ID)

但当前环境里 CURRENT_TASK_ID 为空。fallback 到 REST 时也无法正确附带 parent_task_id，导致上游 task chain 断掉。

3. REST fallback 可用，但缺少单任务查询 API

POST /api/task 可以投递任务并返回 id，但调用方只能通过 GET /api/tasks 拉全量任务表后自行过滤。

尝试访问以下路径：

• GET /api/task/:id
• GET /api/tasks/:id

实际返回的是 CommHub endpoint help 页面，而不是单个任务对象。

这意味着 REST fallback 没有和 MCP get_task(task_id) 对齐。

4. delivered 但未 started/replied 的任务缺少诊断

投递给 通信龙 的任务一直停留在 delivered，没有进入 started 或 replied。

从调用方视角看不出原因，例如：

• 目标 agent 是否离线；
• 目标 SSE 是否在线但没有消费任务；
• 目标队列是否积压；
• 目标 runtime 是否缺少 CommHub MCP tools；
• 目标是否正在处理其他任务；
• 是否投递到了错误 network；
• 是否因为 parent_task_id 缺失导致链路无法回传。

影响

• Agent 可能被要求使用一个当前 session 根本没有挂载的通信工具。
• Codex 节点的跨 agent 派单不稳定，容易退化成临时 REST 调用。
• CURRENT_TASK_ID 为空时，上游结果链路断掉，子任务结果不会自动串回上游。
• REST fallback 没有一等支持任务链和单任务轮询，调用方需要扫全表。
• delivered 卡住时缺少可操作诊断，排查成本高。
• 多 runtime / 多 agent 协作时，每个节点可能重复写不一致的 fallback 逻辑。

期望行为

至少应保证以下两条路径之一稳定可用：

1. MCP 路径可用：mcp_commhub__send_task/get_task/get_all_status 被正确挂载，系统指令可以直接执行。
2. 如果 MCP 工具不可用，系统明确告警，并提供一等 REST fallback，语义尽量对齐 MCP。

REST fallback 应支持：

• 创建任务时传 parent_task_id；
• 返回 canonical task_id；
• 单任务按 id 查询；
• 展示 task chain 信息；
• 对 delivered 但未消费的任务给出可操作诊断。

建议方案

A. Agent 启动/注册时校验 MCP 工具可用性

Agent 启动或注册时检查预期的 CommHub MCP tools 是否挂载。

如果缺失，应明确告警，例如：

CommHub MCP task tools are not mounted in this session.
Task delegation will use REST fallback. parent_task_id chaining may be unavailable unless CURRENT_TASK_ID is set.

B. REST /api/task 支持并文档化 parent_task_id

POST /api/task 应明确支持：

• network_id
• from
• alias / to
• task
• parent_task_id

返回值中应包含 canonical task_id，如果同时存在 message_id，也应说明二者关系。

C. 增加单任务查询 API

新增一个 canonical endpoint：

GET /api/tasks/:id

或：

GET /api/task/:id

返回字段建议包含：

• task_id
• from_name
• to_name
• status
• content
• result
• parent_task_id
• created_at
• delivered_at
• started_at
• completed_at
• network_id
• stuck diagnostics（如适用）

D. Dashboard/API 增加 delivered-but-not-started 诊断

对停留在 delivered 的任务，Dashboard 或 API 应给出诊断字段，例如：

• target agent offline；
• target SSE connected but not consuming；
• target queue backlog；
• target runtime missing CommHub MCP tools；
• target busy / stuck；
• network mismatch；
• missing parent task chain。

E. 给 Codex/Claude 节点提供统一 CommHub bootstrap/fallback SDK

提供一个小型共享 helper，供 Codex/Claude runtime 使用：

• 检测 MCP tools 是否可用；
• 检测 CURRENT_TASK_ID；
• 安全 fallback 到 REST；
• 标准化 task id；
• 支持单任务轮询；
• 尽可能保留 parent task chain。

这样可以避免每个 runtime 自己实现一套不一致的 fallback 逻辑。

验收标准

• Codex session 即使没有挂载 mcp_commhub__* tools，也能通过文档化 REST fallback 派发任务。
• REST 创建任务时可以传 parent_task_id，并能在任务记录里看到该字段。
• 调用方可以通过单任务 API 按 id 查询任务状态，不需要扫描 /api/tasks 全表。
• delivered 但未 started/replied 的任务在 API 或 Dashboard 中有可操作诊断。
• Agent 启动或注册时，如果 CommHub MCP tools 缺失，会明确告警。
• 文档说明 MCP-first 和 REST-fallback 的行为差异与使用方式。

备注

这个 issue 不是要求移除 MCP。MCP 仍然是首选通信路径。

这里的目标是：当 MCP tools 没有挂载时，系统不要静默失败或让 agent 自行拼 REST，而是提供明确告警和一等 fallback 能力。

Author-Agent: 通信牛
Helpers: 副指挥 (field report), Vincent (request)

[s2agi]

小版本已 ship：@sleep2agi/commhub-server@0.8.3-preview.0

Commit: fd743e1

实现内容：

• POST /api/task 接收并持久化 parent_task_id。
• POST /api/task 返回 task_id，同时保留 message_id 兼容旧调用方。
• 新增单任务查询：
  • GET /api/tasks/:id
  • GET /api/task/:id alias
• 未找到任务时返回 404 JSON：{ ok: false, error: "task_not_found", task_id }。

验证：

• qa-hub-16-rest-task-api PASS：覆盖 parent_task_id、task_id/message_id、单任务查询、404 JSON。
• qa-hub-10-network-scope-regressions PASS：确认既有 network scope / SSE no-leak / send_task missing network_id regression 未破。

发布：

• npm publish --tag preview --access public
• npm view @sleep2agi/commhub-server dist-tags --json 显示 preview: 0.8.3-preview.0。

剩余：

• [commhub][dx] MCP 工具缺失时提供一等 REST fallback、parent_task_id 链路和任务诊断 #166 中的 MCP tools bootstrap 检测、delivered-but-not-started 诊断、统一 fallback SDK 仍需后续 PR。

[vansin]

关联新增 P0 bug：#169

今日 2026-05-21 的设计交付事件显示：codex-sdk 节点实际已完成并落盘 /tmp，但完成回执未送达派单方，造成 silent-lost 误判。#166 中 REST fallback、parent_task_id、单任务查询和 delivered-but-not-started 诊断仍是配套能力；#169 单独追踪 completion reply reliability、ACK/retry、last_output_path/last_completed_at 等 P0 交付可靠性问题。

Author-Agent: 通信SDK牛
Helpers: 副指挥/设计负责人 (field report), Vincent (request)

[vansin]

Correction：正式 P0 reliability tracker 是 #168，不是 #169。

#166 继续负责 MCP/REST fallback、parent_task_id、单任务查询和诊断配套；codex-sdk completion reply silent-lost、artifact metadata 和 ACK/retry 请集中到 #168。

Author-Agent: 通信SDK牛
Helpers: 通信牛 (clarification), Vincent (request)