[Bug] 流式工具调用增量携带空 id/name，导致会话历史永久无法加载：SessionPersistenceCorruptionError: message must have tool source

[wujason759]

版本 / Version

@deepseek-ai/dsh 0.1.0-rc.5（本地 checkout 构建运行）
复现环境：Linux，Web GUI 打开会话历史（localhost:3080）

现象 / Symptom

某个会话的历史无法加载，接口返回：

history unavailable for session "session-46a0916c-…": SessionPersistenceCorruptionError: stored session "session-46a0916c-…" failed validation: Error: session event at seq 165513 message must have tool source

GUI 侧显示「历史加载失败」。该会话历史之后每次都触发同一错误（无需任何其他操作）。

复现 / Reproduction

1. 在一个会话中让模型（本机为 deepseek-official / deepseek-v4-pro）发起一次工具调用（如 read）。
2. DeepSeek 流式返回：第一个 tool_call 增量带真实 id/name，后续参数增量携带显式空字符串 id: "" / function.name: ""（字段存在，而非省略）。
3. 会话日志里该轮最终 tool-call block 的 id 被清空 → agent 以空工具名执行 → ToolNotFoundError: unknown tool "" → 持久化出 tool/result 且 message.source.callId === ""。
4. 之后每次从 Web GUI 加载该会话历史都触发上面的校验错误。

会话 JSONL 中的关键证据（seq 165496 → 165508 → 165512 → 165513）：

• assistant/chunk 首个 tool-call-delta：id: "call_edb776167f1347a3bad1011e", name: "read", argumentsDelta: ""；
• 随后的打包行 tool-call-chunks：id: ""、name: ""（证实后续增量确实带空串，而非省略）；
• 最终 block：{"type":"tool-call","id":"","name":"","arguments":"{…}"}；
• tool/result：source.callId: ""、content[0].toolCallId: "" → 重放校验拒绝，历史整体无法加载。

根因 / Root cause

1. packages/llm/llm-deepseek/src/translate.ts（约 159–160 行）在每一个 tool_call 增量上无条件覆盖块身份：

   if (call.id !== undefined) block.callId = call.id
   if (call.function?.name !== undefined) block.name = call.function.name

   当后续增量携带 id: "" / name: ""（字段存在但为空）时，真实 id 被空串覆盖。已用真实源码独立复现：同样的流，带空串增量 → 最终 block id: ""；不带 → 正常保留 id: "call_edb…", name: "read"。

2. 次生隐患：packages/llm/llm/src/assembler.ts（约 70 行）同样无条件 partial.toolCallId = chunk.id，会覆盖首个非空 id。客户端 PartialAccumulator 已是「首个 id 固定」的语义，BlockAssembler 应保持一致。

3. 校验侧（packages/core/session/src/index.ts 的 assertMessageEventShape）对任何 source.callId === "" 的 tool/result 抛错，属防损坏的有意检查；但坏数据已持久化，导致该会话历史永久无法加载。

修复建议 / Suggested fix

两处（本地已验证）：

// packages/llm/llm-deepseek/src/translate.ts
- if (call.id !== undefined) block.callId = call.id
- if (call.function?.name !== undefined) block.name = call.function.name
+ if (call.id) block.callId = call.id
+ if (call.function?.name) block.name = call.function.name

// packages/llm/llm/src/assembler.ts
- partial.toolCallId = chunk.id
+ if (chunk.id) partial.toolCallId = chunk.id

修复后同样的流，最终 block 保留 id: "call_edb…"、name: "read"。

另外建议从源头缓解：adapter 侧对空 id/name 做规整（不覆盖），或在持久化/校验侧容忍空 callId 并合成兜底 id，避免再次产生「历史无法打开」的会话。已损坏的会话需要手工修复日志（把空 source.callId / toolCallId 填回真实 id）；注意 .jsonl.zstd 是多帧格式（首帧为 header 一行、带校验和），修复重压时需保持一致，否则会报 corrupt Zstandard session log: first frame is not exactly one header line。

影响 / Impact

任何一次「流式工具调用后续增量携带空 id/name」的会话，其 tool/result 会以空 callId 持久化，该会话历史在 GUI 中永久无法打开（agent 侧仍可运行，仅历史展示与续读失败）。遇到同样问题的朋友请给本帖点赞/upvote，方便官方按优先级处理。

[argszero]

你发现的链路完全正确，而且这是已知家族的一次关键升级——它把"每回合功能破坏"（#1713/#2090 的显式 null 变体）升级为"会话永久毒化"。我逐一验证，并有一个对现有修复的关键修正。

1. 链路验证（master 47f9438）

• translate.ts:159-160：if (call.id !== undefined) block.callId = call.id / if (call.function?.name !== undefined) block.name = call.function.name —— 空字符串 "" 满足 !== undefined → 覆盖首帧捕获的真实 id/name。你观察到的"后续增量带显式空串"正是这个覆盖路径。
• 下游：tool/result 持久化时 source.callId === "" → 会话加载校验 core/session/src/index.ts:339-342 抛出 message must have tool source（typeof callId !== 'string' || callId === '' 都拒绝）→ 每次加载都失败 → 历史永久不可用。

2. 关键修正：!= null 修法（#1713/#2090 当前方案）覆盖不了这个变体

我在 #1713/#2090 上验证过的修复是 if (call.id != null) —— 它只挡住显式 null。但 "" != null 为 true，空字符串仍然会覆盖。所以 zoahdev 已实现的 fix 分支（fix/llm-deepseek-...，带 null 回归测试）无法修复本帖的空字符串变体。正确守卫要同时拒绝空串：

if (call.id) block.callId = call.id            // truthy: 拒绝 null/undefined/"" 三者
if (call.function?.name) block.name = call.function.name

（真实的 call id / 工具名必然非空；首帧已捕获真实值，续帧只有携带非空值才应该覆盖。）需要补一个空字符串回归用例：{ id: '', function: { name: '', arguments: '{"x":1}' } } 不应覆盖已捕获的 id/name。

3. 家族升级：wire 家族获得"永久毒化"放大器

• Streamed tool calls lose name/id against OpenAI-compatible servers that send explicit nulls (SGLang) — every call fails as UNKNOWN_TOOL #1713/Bug + one-line fix: streaming tool calls lose function.name when continuation chunks send name: null (dsh-llm-deepseek, rc.6) #2090（显式 null）→ 每回合 unknown tool ""，但配对错误结果、不毒化会话（我在 Streamed tool calls lose name/id against OpenAI-compatible servers that send explicit nulls (SGLang) — every call fails as UNKNOWN_TOOL #1713 回复里明确写过这一点）。
• 本帖（显式空串）→ 空 callId 持久化进日志 → 会话级校验拒绝 → 永久不可加载。这是 bug 任何会话只要遇到截断在 emoji 中间的工具结果，就会永久 400 无法继续 #1449/Bug + tested fix: truncated tool-call arguments permanently poison a session (llm-deepseek serializer) #1519/Community plugins resolving a second @deepseek-ai/dsh-tools copy crash the tool scheduler with Cannot read properties of undefined (reading 'prepare') #1337/[BUG] 会话日志中一条 tool/result 引用了不存在的 call id，导致该会话所有请求被供应商 400 拒绝，永久不可用 #1593 毒化家族的第 5 条路径，触发源在 wire 层。
• 也就是说：同一个 wire 层缺陷（续帧覆盖块身份），显式 null 是"可恢复的每回合故障"，显式空串是"永久毒化"——区别只在 provider 发什么。

4. 恢复建议

会话日志本身只是被空 callId 的 tool/result 毒化：备份后编辑 JSONL，把该条 tool/result 的 source.callId / content[0].toolCallId 从 "" 改成真实 call id（或移除该 result + 对应 tool-call block），加载即可恢复。多次出现则建议 dsh-doctor S11 式离线隔离。

5. 修复顺序建议：wire 层守卫（truthy 检查）是根修复——毒化永不产生；session 层校验（index.ts:340）是正确的防线，不应放宽（空 callId 的 result 确实是损坏数据）。请把这个空串用例同步到 #1713/#2090 的修复分支上，让一个 fix 覆盖两个 provider 变体。

[leonasd]

同样问题，在 0.1.1-rc.2（2026-08-21 release，Windows 10，Node v24.14.0，源码 zip 构建）上仍然复现。

症状与楼主一致：history unavailable for session ... message must have tool source（internal）。解压 session.jsonl.zstd 检查后发现，单个会话（约 2000 条事件）中产生了 49 对空 callId 的 tool/call + tool/result（callId: ""、name: ""，配对 result 报 ToolNotFoundError: unknown tool ""），全部集中在今天一次运行中。

按楼主和 argszero 的思路手工修复日志后历史恢复加载：

1. 停掉 dsh web，备份原文件；
2. 按 zstd magic（28 B5 2F FD）切帧解压为 JSONL；
3. 为每对空 callId 合成占位 id 并回填三处：tool/call 的 data.callId、配对 tool/result 的 message.source.callId 和 message.content[0].toolCallId（通过 sourceEventSeqs 匹配配对关系）；
4. 重新编码时必须分两个帧：帧 1 只含 header 行，帧 2 为全部事件行，均带 checksum（ZSTD_c_checksumFlag: 1）。压成单帧会触发 first frame is not exactly one header line，导致整个 dsh 启动失败（workspace 插件 listArtifacts 时抛出）。

[Zn-Dk]

同根因。我在 #4365 也报了官方端点的空字符串变体（把失败钉死在最后一个 delta 帧），argszero 已经把这几个串成一个 identity-loss family，并给出了引擎侧修复蓝图。

在引擎 patch 落地之前，已经被毒化、load 不起来的会话不必再手工切帧了——我做了一个恢复插件：

dsh-session-repair(https://github.com/Zn-Dk/dsh-session-repair)

• 在 broken 会话顶部的「会话体检」一键诊断；检测到空 callId 链就给出「备份并修复」，自动完成你列的手工步骤：备份 → 合成占位 id 回填三处（assistant/tool-call/tool-result）→ 按帧重压（header 单帧 + 事件帧，带 checksum）→ 复验。
• 不依赖 agent、不用手动 copy sessionId、不用手动解压 zstd；修复前强制 pre-repair backup，可一键回滚，并留审计记录。
• 覆盖 missing / null / "" 三种身份丢失形态。

它只做「恢复已损坏的历史」，不碰引擎写入路径——根治还是等 argszero 的引擎 patch（L1-L4 + 三态回归）。

[udsy19]

根因与 truthy 守卫的结论都对。但修复建议里的第 2 处（assembler.ts）在 llm-deepseek 这条链路上不会
生效——它是死代码，补了也不会改变本帖的现象。

原因：block-end 短路了整个累加器。 llm-deepseek 在 [DONE] 时为每个块发出自己的权威
block-end,packages/llm/llm-deepseek/src/translate.ts:101-105：

  if (payload === DONE) {
    for (const block of order) {
      yield { type: 'block-end', index: block.index, block: closeBlock(block) }
    }

而 closeBlock（translate.ts:69-74）直接用已被空串覆盖的累加值构造最终块：

    case 'tool-call': return {
      type: 'tool-call',
      id: CallId(block.callId ?? ''),
      name: block.name ?? '',
      arguments: block.text,
    }

BlockAssembler 对 block-end 是「首个关闭优先」（packages/llm/llm/src/assembler.ts:76-82），
且 assemble() 原样返回这个块，assembler.ts:107-108：

  private assemble(partial: PartialBlock, index: number): ContentBlock {
    if (partial.block) return partial.block

所以：assembler.ts:71 的 partial.toolCallId = chunk.id、:72 已有的 if (chunk.name) 守卫、
:114 的 call-${index} 兜底——在这条链路上一个都不会执行。因为 translate() 只要正常收到
[DONE] 就必定发 block-end（收不到则在 translate.ts:184 抛 STREAM_CLOSED，也走不到装配）。

结论：本帖唯一有效的修复点是 translate.ts:159-160（或等价地在 closeBlock 里兜底）。
assembler.ts 的 id 守卫仍值得补——它对其它不发 block-end 的 adapter 有效，也与你说的
PartialAccumulator「首个 id 固定」语义一致——但请不要把它算作本帖的修复，否则容易误判为「已修好」。

顺带确认下游链路（tip b150a551b，与 leonasd 的 0.1.1-rc.2 一致）：
packages/core/agent-loop/src/tool-calls.ts:263 是 packages/ 里唯一的 tool/call 落盘点，
:277 → createToolResultMessage（packages/llm/llm/src/message.ts:231-241）把同一个空
callId 同时写进 source.callId 与 content[0].toolCallId——这正是 leonasd 手工修复时必须回填三处的
原因。校验侧 packages/core/session/src/index.ts:337-341 拒绝空串，是有意的防损坏检查，不应放宽。

无法通过用户配置规避：没有任何配置项能改变这两个守卫，只能改 adapter 源码，或在 llm/stream
waterfall 上拦截并修复 chunk（该 waterfall 位于装配与落盘之前,packages/core/agent-loop/src/agent.ts:343-352
先 append('assistant/chunk', …) 再 assembler.push(chunk)）。已经写坏的会话只能按 leonasd 的方法手工修。

[Jstn-1g]

I implemented and published a tested reference patch for this failure chain on exact upstream base b150a551b. It also incorporates the independently reported durable-corruption cases in #4385 and #4387.

Reference implementation:

• branch
• exact commit 1ed9aed97
• design, limitations, evidence, and attribution

The patch deliberately treats the DeepSeek root fix and the shared hardening as two different layers:

• llm-deepseek/translate.ts retains only non-empty runtime-string ids/names. A call that never receives an id gets a stream-unique, collision-probed fallback before the adapter emits its authoritative block-end. This directly addresses udsy19's analysis: the shared assembler cannot repair a bad DeepSeek block-end after the fact.
• BlockAssembler separately retains non-empty delta identity for adapters without authoritative final blocks, avoids sibling provider-id collisions, and rejects duplicate retained non-empty ids as MALFORMED_RESPONSE before tool dispatch. Agent and token-meter reconstruction use the same durable turn/step namespace, so replaying the same raw missing-id chunks reproduces the live id. This shared layer is relevant to the OpenAI-compatible/pi-ai route reported in [Bug] A degenerate streamed tool call (empty callId) is persisted, then the loader rejects it — entire session history becomes permanently unloadable #4387, although I did not reproduce that external gateway itself.
• Assembly failures use the existing agent/request-error recovery/retry boundary. max-tokens still drops potentially truncated calls without discarding safe text, and a terminal provider error keeps its original failure.
• A missing function name is not invented; it follows the existing paired UNKNOWN_TOOL result path with a valid id.

Deliberate boundary: the strict session loader is unchanged, and this does not silently repair already-corrupted logs. Existing damaged histories still need an explicit offline repair/backup workflow.

Verification on the exact published commit:

• 226 focused identity/session/agent/client/token-meter tests passed
• 100% statements, branches, functions, and lines for both changed identity engines (translate.ts and assembler.ts)
• keyless local SSE/ACP composition through the real DeepSeek adapter code passed preservation, synthesis, provider passback, tool/result pairing, and reload
• full typecheck and lint passed; all 28 documentation gates passed
• full GUI suite: 3,995 passed, 4 expected skips

The Agent Note credits the reporters and the prior analyses/reference patches that informed this implementation, without claiming original discovery or code co-authorship. This is a public reference implementation for review, not a claim of official upstream adoption.