[observability][codex-sdk] 补齐 send_task 调用与投递链路日志

[s2agi]

背景

Codex / codex-sdk 节点在 Agent Network / CommHub 中会承担派单、转问、轮询任务、汇总回复等协作角色。

在这些场景里，节点通常会调用 CommHub 的 send_task 能力，或者在 MCP tools 未挂载时 fallback 到 REST /api/task。

但当前 Codex 节点的调用链路缺少清晰日志。用户反馈“看不到调用发送 send_task 的 LOGO”，按上下文理解为：看不到 send_task 相关 LOG / 日志 / 标识，导致无法判断任务到底有没有被发出、是否投递成功、是否被目标 agent 消费。

现象

当 Codex 节点调用 send_task 或 REST fallback 发任务时，用户 / 操作者很难在以下位置看到明确链路：

• Codex SDK session 输出；
• agent-node / runtime 日志；
• Dashboard task list；
• CommHub API 状态；
• 上游任务链路。

缺少明确的状态标识，例如：

• 正在发送任务；
• 已投递；
• 已 ack；
• 目标已 started；
• 目标已 replied；
• failed / expired；
• 使用的是 MCP transport 还是 REST fallback；
• 是否带上了 parent_task_id。

影响

• 操作者不知道任务到底有没有发出去。
• 分不清问题发生在哪一层：
  • MCP 工具没挂载；
  • REST fallback 被使用；
  • 目标 agent 没消费；
  • Hub/API 返回异常；
  • network_id / auth / role 问题；
  • parent task chain 缺失。
• 多 agent 协作时，上游看不到任务链路，尤其 parent_task_id 缺失时更难追踪。
• delivered 但长期未 started 的任务没有明显 warning，容易被误认为 agent 已经在处理。
• Debug 依赖人工扫 /api/tasks 或 Dashboard，效率低且不可复制。

期望行为

Codex / codex-sdk 节点在调用 send_task 前后应输出结构化日志，并尽量在 Dashboard / task list 中呈现同一条链路。

日志至少应包含：

• from_alias
• to_alias
• task_id
• parent_task_id
• network_id
• transport: mcp / rest
• status: sending / delivered / acked / started / replied / failed / expired
• duration_ms
• error_code / error_message（如有）
• fallback reason（如 MCP tools missing / CURRENT_TASK_ID missing）

建议人类可读日志示例：

[commhub:task] sending task from=通信牛 to=通信龙 transport=rest parent_task_id=<missing>
[commhub:task] delivered task_id=abc123 to=通信龙 status=delivered duration_ms=42
[commhub:task] warning task_id=abc123 still delivered after 60s; target may be offline or not consuming
[commhub:task] replied task_id=abc123 duration_ms=18234

建议 JSON log 示例：

{
  "event": "task.send.delivered",
  "from_alias": "通信牛",
  "to_alias": "通信龙",
  "task_id": "abc123",
  "parent_task_id": null,
  "transport": "rest",
  "status": "delivered",
  "duration_ms": 42
}

建议方案

A. 在 codex-sdk adapter / CommHub client 包一层 task logger

把所有 task send / poll / reply 状态变化统一经过一个 logger，而不是散落在 runtime 逻辑里。

B. 标准化事件名

建议事件名：

• task.send.start
• task.send.delivered
• task.ack
• task.started
• task.replied
• task.failed
• task.expired
• task.warning.delivered_stale
• task.transport.fallback

C. MCP send_task 与 REST fallback 使用同一日志格式

无论 transport 是 MCP 还是 REST，都输出同样字段，避免 operator 需要理解两套日志。

关键区别用字段表达：

{
  "transport": "mcp"
}

或：

{
  "transport": "rest",
  "fallback_reason": "mcp_tools_missing"
}

D. 支持 JSON logs 和人类可读 logs

建议支持两种输出：

• 默认人类可读：适合终端和 tmux session；
• JSON logs：适合 Dashboard / log collector / E2E 断言。

E. 可配置日志级别

建议支持：

• DEBUG=commhub:task
• ANET_LOG_LEVEL=debug
• 或 runtime config 中的 logLevel。

默认级别可只显示关键状态：send start / delivered / failed / stale warning / replied。

F. 对 delivered-but-not-started 增加 warning

如果任务在 delivered 状态停留超过阈值，输出 warning：

• 30s：提示仍未 started；
• 60s：提示目标可能离线、未消费、队列积压或工具未挂载；
• 继续等待时避免刷屏，可指数退避。

这应与 #166 中的 stuck-task 诊断配套。

验收标准

• 从 Codex 节点发出一个任务后，日志里能看到：
  • from_alias
  • to_alias
  • task_id
  • parent_task_id
  • transport
  • 当前状态。
• MCP transport 和 REST fallback 都使用同一套日志字段。
• 当 MCP tools 缺失并 fallback REST 时，日志明确显示 fallback reason。
• 当 CURRENT_TASK_ID 缺失时，日志明确显示 parent_task_id=<missing> 或等价字段。
• 任务卡在 delivered 超过 30s/60s 时，有明确 warning。
• Dashboard / task list 能看到最近 send_task 调用轨迹或至少能关联到 task_id 状态。
• issue [commhub][dx] MCP 工具缺失时提供一等 REST fallback、parent_task_id 链路和任务诊断 #166 中提到的 MCP 缺失 / REST fallback / parent_task_id 缺失场景可以通过日志快速判断。

关联

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

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

[vansin]

新增 P0 reliability tracker：#169

本条 field report 指向的不是单纯 send_task 日志缺失，而是 codex-sdk 节点完成产出后 completion reply/回执 silent-lost，导致派单方误判任务卡住。#167 继续作为链路日志/observability 配套项；P0 修复主线请以 #169 的 ACK/retry/durability/last_output_path 验收为准。

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

[vansin]

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

#167 继续作为 send_task 日志可观测性配套项；completion reply ACK/retry、artifact metadata、reply missing 状态请集中到 #168。

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