残缺或孤立的 tool_calls 记录导致 DeepSeek 接口返回 400

[bozhang1214]

会话历史中存在无配对 result 或 id/name/arguments 残缺的 tool_calls 时，DeepSeek chat-completions 接口返回 400。

复现、预期与验收

• 复现步骤：
  1. 模型发起工具调用后，流被中断或上下文被裁剪，留下没有对应 result 的孤儿调用，或 id / name / arguments 残缺的调用；
  2. 下一轮请求拼装历史并调用 DeepSeek chat-completions；
  3. 接口返回 400。
• 实际结果：返回 400，错误信息包含 insufficient tool messages following tool_calls message 或 tool_call_id。
• 预期结果：框架在拼历史 / 裁剪边界自动丢弃或补齐残缺调用，保证发上 wire 的 tool_calls 合法。
• 环境：deepseek-harness（master 分支）；@deepseek-ai/dsh-llm-deepseek 适配器。
• 验收条件：残缺 / 孤儿 tool_calls 不再导致 400；相关单元测试通过。

定位与修复建议（附 patch）

根因是三处对「残缺 tool_calls 记录」缺少容错：

1. packages/core/agent-loop/src/agent.ts —— 拼历史时只剥离孤儿调用，未校验空 id、空 name、非法 JSON arguments 的畸形调用；
2. packages/llm/llm-deepseek/src/translate.ts —— provider 未下发 id 时兜底成空字符串 id（空 id 可能与其他空 id result 误配对）；
3. packages/compaction/compaction/src/tool-pairing.ts —— 裁剪边界的配对平衡按「计数」而非 callId，识别不了「数量相等但 callId 错配」。

修复改动拆成 4 个 commit（含单元测试），验证结果：

• agent-loop 340 测试、llm-deepseek 151 测试、compaction 195 测试全过；
• 类型检查与 oxlint 均通过。

完整改动见我的 fork 分支：https://github.com/bozhang1214/deepseek-harness/tree/fix/tool-call-pairing-harden（fork 后可见）；也可直接使用附件中的 patch 文件。

[0001-chore-ignore-the-local-.venv-directory.patch](https://github.com/user-attachments/files/31541105/0001-chore-ignore-the-local-.venv-directory.patch) [0002-fix-agent-loop-strip-malformed-tool-calls-at-the-req.patch](https://github.com/user-attachments/files/31541106/0002-fix-agent-loop-strip-malformed-tool-calls-at-the-req.patch) [0003-fix-llm-deepseek-synthesize-a-fallback-tool-call-id-.patch](https://github.com/user-attachments/files/31541107/0003-fix-llm-deepseek-synthesize-a-fallback-tool-call-id-.patch) [0004-fix-compaction-balance-tool-pairing-by-call-id-inste.patch](https://github.com/user-attachments/files/31541108/0004-fix-compaction-balance-tool-pairing-by-call-id-inste.patch)

[liyangbing]

这个定位方向成立，尤其是 tool-pairing.ts 只按计数判断 balance 的问题。alpha.1 当前算法确实可能把下面的历史误判为 balanced：

assistant tool_calls: [call_A]
tool results:          [call_B]
count: 1 - 1 = 0
identity: call_A 仍未关闭，call_B 是孤儿

建议修复时把验收边界再收紧一些：

1. compaction 使用按原始顺序维护的 callId ledger，而不是 Set 或计数；空 ID、重复 ID、unknown result 都应是不同的 typed failure。
2. translate 的 fallback ID 必须 request-scoped 且无碰撞，并确保之后生成的 result 使用同一 ID。不能在多个边界各自随机补 ID，否则仍无法关联。空 name 与非法 arguments 也应在 block close / execution admission 前失败。
3. Agent request 侧丢弃 malformed block 只能算 containment。应记录被排除的 immutable source message/block、原因以及是否存在执行证据；不要静默改写 Session，否则 compaction、export、replay 和其他 adapter 会看到不同历史。
4. 对已有 tool/call 但无 result 的情况，不要默认成“未执行”。副作用状态是 unknown；修复文本或 typed outcome 需要保留这个不确定性，防止盲目重试。
5. 建议加入“调用/结果数量相等但 ID 错配”、两个空 ID、重复 ID、流结束时缺 name、非法 arguments、compaction cut 后 replay、DeepSeek/OpenAI-compatible 双 adapter 的 fixture。

我把 rc.7 → rc.2 → alpha.1 的生产、Turn closure、compaction、wire containment 四层边界和恢复流程合并到了现有 runbook（revision 3）：
https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/dangling-tool-calls-insufficient-results.md

[Leeminjing]

If you need a fix that works without patching the harness — on a build that still has this bug, or for a session that's already been poisoned — I wrote a plugin-level safety net:

dsh-messages-sanitizer — auto-repairs an invalid messages array (orphaned / unpaired tool_calls, orphaned tool messages) so the next request is valid and the session no longer stalls on 400 INVALID_REQUEST.

dsh plugin --profile web add dsh-messages-sanitizer

Source: https://github.com/Leeminjing/dsh-messages-sanitizer · on npm: dsh-messages-sanitizer

It's complementary to, not a replacement for, the harness-side fix: it works on the messages array at runtime (auto-resume after a tool-dispatch crash, carries the error back to the LLM so it decides the next step), independent of agent-loop / llm-deepseek / compaction. Happy to take feedback.

---

如果你需要的是一个不改 harness 源码就能落地的方案——比如跑的还是带这个 bug 的版本，或会话已经被污染了——我写了一个插件层安全网：

dsh-messages-sanitizer —— 自动修复非法的 messages 数组（孤儿/未配对的 tool_calls、孤立的 tool 消息），让下一次请求合法、会话不再卡死在 400 INVALID_REQUEST。

dsh plugin --profile web add dsh-messages-sanitizer

源码：https://github.com/Leeminjing/dsh-messages-sanitizer · npm：dsh-messages-sanitizer

它与 harness 侧的修复互补、而非替代：它在运行时作用于 messages 数组（工具调度崩溃后自动续跑，把错误报给 LLM 让它决定下一步），不依赖 agent-loop / llm-deepseek / compaction。欢迎反馈。