会话无法加载："message must have tool source" —— 空 tool callId 能通过 append 写入，却在读取时被拒绝

[xkxkiscoder]

版本

0.1.5-alpha-2

症状

一个此前正常工作的会话无法加载（gateway/internal 报错）：

stored session "session-1ba6018d-9f77-4b92-a3ab-71f0dff63061" is corrupt:
stored session "session-1ba6018d-..." failed validation: Error: session event at seq 3071
message must have tool source

根因

我解码了存储日志（2134 个拼接的 zstd 帧、3740 个事件）。seq 3070/3071 是这样的：

{ "type": "tool/call",   "seq": 3070, "data": { "callId": "", "name": "", "arguments": "{}" } }
{ "type": "tool/result", "seq": 3071, "data": { "message": { "source": { "kind": "tool", "callId": "" } },
    "error": { "name": "ToolNotFoundError", "code": "UNKNOWN_TOOL" } } }

三层问题叠加，造就了一份 harness 自己都读不回来的日志：

1. Provider 翻译层容忍无 id 的 tool_call delta。 packages/llm/llm-deepseek/src/translate.ts 的 closeBlock() 在流式 tool_calls delta 从未携带 id/name 时回退为 block.callId ?? '' / block.name ?? ''（某些 OpenAI 兼容网关确实会这样返回）。甚至有一个测试用例把这个宽松行为固定了下来：translate.spec.ts —— "handles deltas that never carry id or name (empty-string fallbacks)"。

2. agent-loop 原样落盘。 packages/core/agent-loop/src/tool-calls.ts 的 appendToolCall / appendToolResult 把空 id 直接写进 tool/call，随后又写进 tool/result（执行失败的 unknown tool "" 成了结果本身）。

3. 写入端验证弱于读取端验证。 Session.append()（packages/core/session/src/index.ts）只执行 validateSessionEventData + surfaceManager.validateNext。严格的消息不变量（assertMessageEventShape，它要求 tool/result 的 source.callId 非空）是在 b1af35145b（"fix: enforce message snapshot invariants"）中加到读取/seed/快照路径上的，却从未加到 append 路径。于是循环可以持久化一个 validateStoredEvents -> adoptSessionEvent 之后会拒绝的事件——一次畸形的模型 delta 就这样把整个会话变成不可加载：整份日志被拒绝，seq 3071 之后的一切都无法再访问。

这与 append 自己的 JSDoc 相矛盾："a bad event fails at the append site rather than later during a backend flush."

影响

任何一个首个 tool_calls delta 缺少 id 的 provider 响应都会悄然污染会话文件。该回合仍会正常完成（模型会收到 unknown-tool 错误），但这个会话从此再也无法加载。

修复方向建议

• 在 Session.append() 中强制执行 assertMessageEventShape，让坏事件在 append 处就失败。
• 在源头拒绝或修复无 id 的 tool call（合成一个 id，或让流失败），而不是回退为 ''。

遇到此问题的临时绕过方法：重写存储日志，把两个事件中的空 callId 替换掉，并删除 session_projcache 投影缓存让其重建。

[PerryLink]

你的三层分析我逐条对着 master（0d1f50007f，v0.1.6-alpha.1）核对过了，全部成立，而且 master 上至今没有任何修复：空 callId 依旧能通过 append 写入、在读取时被拒绝，你提的两条修复方向（append 处强制校验、源头合成 id）都没有落地。

逐条证据：

1. 写入端确实弱于读取端。 Session.append() 在 packages/core/session/src/index.ts:748-749 只做两件事：validateSessionEventData(event, ...) + this.surfaceManager.validateNext(event as SessionEvent)，没有调 assertMessageEventShape。而 assertMessageEventShape 的调用点只有两处：index.ts:169（adoptSessionEvent，被持久化读取路径 storage-contract.ts:95 和 session-query 使用）和 index.ts:272（seed 路径）。你在 seq 3071 看到的报错正是 index.ts:370-373：sourceRecord['kind'] !== 'tool' || typeof sourceRecord['callId'] !== 'string' || sourceRecord['callId'] === '' → throw message must have tool source，再由 storage-contract.ts:98-99 包成 stored session "..." failed validation。这与 append 自己的 JSDoc 矛盾——那句话在 index.ts:713-715 原样还在。
2. 翻译层回退还在，但路径已迁移。 0.1.5-alpha-2 的 packages/llm/llm-deepseek/src/translate.ts 现在在 packages/llm/llm-deepseek/src/protocols/chat-completions/translate.ts，closeBlock() 于 :96-97 仍是 id: brandString<ToolCallId>(block.callId ?? '') / name: block.name ?? ''；你引用的测试用例也还在 tests/translate.spec.ts:331（"handles deltas that never carry id or name (empty-string fallbacks)"）。
3. agent-loop 原样落盘。 packages/core/agent-loop/src/tool-calls.ts:264 就是 callId: block.id，appendToolResult（:277-281）用同一个 block.id 构造 tool/result 的 message source——与你贴的 seq 3070/3071 完全吻合。
4. b1af351 属实。 提交信息 "fix: enforce message snapshot invariants"，改动落在 packages/core/session/src/index.ts（+89 行）以及 session-persistence / session-query 的读取、种子、快照路径，append 路径从未纳入。

你的绕过方案与源码一致：恢复时的校验只针对事件结构（我在 session-persistence 里没有找到对整份日志的哈希/校验和门禁），所以改写事件后能通过；session_projcache 是派生的按会话缓存（<root>/session_projcache/sessions/<id>.json，见 session-projection-cache/tests/cache.spec.ts:5-8），删除重建是安全的。风险提示：手改 durable log 必须保持 zstd 帧可解码、seq 从 0 连续（index.ts:579-581），并且 tool/result 内容块的 toolCallId 必须等于改后的 source.callId（index.ts:382-384），改前务必备份。

一个小发现：新的 messages 协议翻译层现在会拒绝空 tool 身份（protocols/messages/translate.ts:57 malformed('empty tool identity')），但 chat-completions 路径的 '' 回退依旧，且已损坏的历史会话不会自愈。如果你愿意贴出损坏前后各几帧事件和版本号，我可以帮你确认改写是否覆盖了所有需要改的字段。

[xkxkiscoder]

版本

我是通过源码构建的，该 checkout 的 git HEAD = b2e3b2a，恰好就是 tag dsh-v0.1.5-alpha.2。

两条补充

1. 大部分llm Api在缺少toolCallId时是会直接报400错误中断。 紧随其后的 seq 3076（frame 1779）原始 JSON：

{"type":"turn/end","seq":3076,"time":1789529979861,"data":{"turn":21,"reason":{"kind":"error","error":{"message":"400: {\"code\":\"400\",\"message\":\"Param Incorrect\",\"param\":\"messages[17].tool_calls[1] is missing a function name\",\"type\":\"\"}","code":"INVALID_REQUEST"}}}}

2. 模型为Mimo模型

损坏点前后的帧与原始事件

损坏原值：

{"type":"tool/call","seq":3070,"time":1789529979718,"data":{"turn":21,"step":4,"callId":"","name":"","arguments":"{}"}}

{"type":"tool/result","seq":3071,"time":1789529979731,"data":{"turn":21,"step":4,"message":{"source":{"kind":"tool","callId":""},"content":[{"type":"tool-result","toolCallId":"","content":[{"type":"text","text":"Error: unknown tool \"\""}],"isError":true}],"role":"user","id":"4bee9ece-31af-49d9-b587-406f180200b4"},"error":{"name":"ToolNotFoundError","code":"UNKNOWN_TOOL"}},"sourceEventSeqs":[3070],"surfaceOp":"append"}}

损坏的源头：模型在正文里输出了 XML 工具调用残片

seq 3067（的 message.content 有 4 个块，完整还原了空 tool call 的产生过程：

index	块	内容
0	reasoning	1521 字符正常推理，无任何 XML，结尾 "Let me grep for x:Key=..."
1	tool-call	read / call_03e6e8634e1c4fb2923a9172，正常（产生 seq 3068/3069）
2	text	XML 工具调用残片，见下
3	tool-call	id:"" / name:"" / arguments:"" —— 空 tool call（产生 seq 3070/3071）

<tool_call><function=gr</parameter></function></tool_call>

模型的第二个工具调用（gr，几乎肯定是 grep 被截断，但不清楚是模型原因或是其他原因导致的截断或是模型本身就输出了不规范的格式）走了 XML 语法：开标签之后紧跟的 function=gr 片段连闭合尖括号都没有、parameter 是空的，只剩一串收尾闭标签：

{"type":"chunk","time":1789529979600,"chunk":{"type":"block-start","index":3,"blockType":"tool-call"}}
{"type":"chunk","time":1789529979600,"chunk":{"type":"tool-call-delta","index":3,"id":"","argumentsDelta":"{}"}}
{"type":"chunk","time":1789529979675,"chunk":{"type":"block-end","index":3,"block":{"type":"tool-call","id":"","name":"","arguments":"{}"}}}

seq 3067

seq 3067 全文：

{"type":"assistant/message","seq":3067,"time":1789529979676,"data":{"turn":21,"step":4,"message":{"role":"assistant","content":[{"type":"reasoning","text":"Let me look at the structure. Plan: create sub-folders in XXX.XXX.Styles: e.g. `Legacy/` moved from host. Since these are host App-level resources merged at App level, moving them to the Styles assembly means host App.xaml references pack URIs into XXX.XXX.Styles. But plugins also consume these keys? Legacy styles are at App level (default ALC), plugins reference them via DynamicResource/StaticResource at runtime? Wait — plugin XAML compiled in their own ALC: StaticResource resolution happens at load against app resources... Actually StaticResource in plugin XAML resolved at parse time walks up the element tree + app resources — works since App resources are in default ALC dictionaries (BAML). If we move the dictionaries into XXX.XXX.Styles assembly and merge them into App.xaml instead, keys remain at App level, so resolution still works identically.\n\nBut careful: plugin LocalResources.xaml in DeviceManager — check its content. Also check what other plugins define their own local styles inline (`<UserControl.Resources>` with Style keys). The task says \"把所有非共享样式资源的样式都整理到共享样式资源项目统一管理。相似样式可以合并\" — all styles not in shared project should be moved into shared project. That includes host Legacy styles and plugin-local ones (DeviceManager LocalResources, and inline styles in views? That's a huge scope). Realistic scope: resource dictionaries. Inline `<UserControl.Resources>` styles in many views — that's a lot. Let me inventory.\n\nLet me grep for x:Key=\" Style definitions across plugins and host."},{"type":"tool-call","id":"call_03e6e8634e1c4fb2923a9172","name":"read","arguments":"{\"file_path\":\"D:\\\\deskdop\\\\XXXNewClient\\\\XXX-client-next\\\\plugins\\\\management\\\\XXX.Plugin.DeviceManager\\\\LocalResources.xaml\"}"},{"type":"text","text":"<tool_call><function=gr</parameter></function></tool_call>"},{"type":"tool-call","id":"","name":"","arguments":"{}"}],"source":{"kind":"model","provider":"xiaomi","model":"mimo-x-flash-preview","replayState":{"response":{"kind":"pi-ai","version":2,"api":"openai-completions","provider":"xiaomi","model":"mimo-x-flash-preview","responseId":"c30507db-3031-4857-b502-f1cd3bfb5e6e_3f626eb933174aefa9d17a540c1acc91","stopReason":"toolUse"},"blocks":[{"type":"reasoning","thinkingSignature":"reasoning_content"},{"type":"tool-call"},{"type":"text"},{"type":"tool-call"}]}},"id":"b278f759-8d52-408b-970e-be632bd6f950"},"usage":{"inputTokens":1357,"outputTokens":392,"totalTokens":33237,"cacheReadTokens":31488},"stream":[{"type":"chunk","time":1789529975236,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1789529975237,"index":0,"dt":[47,23,34,8,0,22,35,19,83,17,26,26,29,22,23,28,854,13,20,20,33,18,29,30,24,19,27,22,28,20,28,28,33,17,33,14,23,20,24,19,24,18,17,24,18,22,28,22,18,21,20,25,23,27,20,29,19,22,24,20,24,27,35,41,28,15,15,383,22,23,20,23,32,19,24,23,19,25,24,18,23,20,25,22,30,17,22,29,16,22,24,22,21,30,23,15,24,28,23,24,21,19,28,22,18,30,19,26,17,19,25,76,4,0,9,28,25,24,12,28,17,20,23,23,28],"texts":["Let me look"," at the structure",". Plan",":"," create"," sub","-fold","ers in XXX.XXX.","Styles: e.g. `","Legacy","/` moved"," from host","."," Since"," these"," are host App","-level resources merged"," at"," App level, moving"," them to"," the"," Styles assembly means host"," App.xaml references"," pack UR","Is into"," XXX.XXX.Styles."," But"," plugins also"," consume"," these keys? Legacy"," styles are at"," App level (","default"," ALC),"," plugins reference"," them via DynamicResource/","StaticResource at runtime","? Wait"," — plugin"," XAML compiled"," in"," their"," own ALC: StaticResource resolution"," happens"," at load"," against"," app"," resources..."," Actually StaticResource in plugin"," XAML resolved"," at parse time walks"," up"," the element tree +"," app"," resources — works"," since App"," resources are"," in default ALC dictionaries"," (","B","AML). If"," we"," move the dictionaries into XX","X.XXX.Styles assembly and"," merge them"," into"," App.xaml instead",", keys"," remain"," at App level, so resolution"," still"," works ident","ically.\n\n","But careful: plugin"," Local","Resources.xaml in"," DeviceManager — check its"," content. Also check"," what"," other plugins define"," their own"," local"," styles inline"," (`","<UserControl.Resources>` with Style"," keys","). The task"," says"," \"把所有","非共享样式资源的样式都整理","到共享样式资源项目统一管理。","相似样式可以合并\""," — all"," styles"," not in shared project"," should be moved"," into shared project."," That includes"," host"," Legacy styles and"," plugin-local ones"," (","DeviceManager LocalResources",", and"," inline"," styles in views","? That","'s a huge"," scope)."," Real","istic"," scope: resource"," dictionaries."," Inline"," `<","UserControl.Resources>` styles in"," many"," views — that","'s"," a lot. Let me inventory",".\n\n","Let me grep"," for x:Key=\""," Style"," definitions across plugins and host","."]},{"type":"chunk","time":1789529979397,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1789529979398,"index":1,"dt":[0,1,0,17,24,27,17,3,1],"id":"call_03e6e8634e1c4fb2923a9172","name":"read","args":["","{\"file_path\": ","\"","D:\\\\deskd","op\\\\XXXNewClient\\\\xx","x-client-next\\\\plugins\\\\management\\\\","XXX.Plugin.DeviceManager\\\\LocalResources",".xaml","\"","}"]},{"type":"chunk","time":1789529979575,"chunk":{"type":"block-start","index":2,"blockType":"text"}},{"type":"text-chunks","time0":1789529979575,"index":2,"dt":[24,1],"texts":["<tool_call><function=gr</parameter></","function>","</tool_call>"]},{"type":"chunk","time":1789529979600,"chunk":{"type":"block-start","index":3,"blockType":"tool-call"}},{"type":"chunk","time":1789529979600,"chunk":{"type":"tool-call-delta","index":3,"id":"","argumentsDelta":"{}"}},{"type":"chunk","time":1789529979675,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Let me look at the structure. Plan: create sub-folders in XXX.XXX.Styles: e.g. `Legacy/` moved from host. Since these are host App-level resources merged at App level, moving them to the Styles assembly means host App.xaml references pack URIs into XXX.XXX.Styles. But plugins also consume these keys? Legacy styles are at App level (default ALC), plugins reference them via DynamicResource/StaticResource at runtime? Wait — plugin XAML compiled in their own ALC: StaticResource resolution happens at load against app resources... Actually StaticResource in plugin XAML resolved at parse time walks up the element tree + app resources — works since App resources are in default ALC dictionaries (BAML). If we move the dictionaries into XXX.XXX.Styles assembly and merge them into App.xaml instead, keys remain at App level, so resolution still works identically.\n\nBut careful: plugin LocalResources.xaml in DeviceManager — check its content. Also check what other plugins define their own local styles inline (`<UserControl.Resources>` with Style keys). The task says \"把所有非共享样式资源的样式都整理到共享样式资源项目统一管理。相似样式可以合并\" — all styles not in shared project should be moved into shared project. That includes host Legacy styles and plugin-local ones (DeviceManager LocalResources, and inline styles in views? That's a huge scope). Realistic scope: resource dictionaries. Inline `<UserControl.Resources>` styles in many views — that's a lot. Let me inventory.\n\nLet me grep for x:Key=\" Style definitions across plugins and host."}}},{"type":"chunk","time":1789529979675,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_03e6e8634e1c4fb2923a9172","name":"read","arguments":"{\"file_path\":\"D:\\\\deskdop\\\\XXXNewClient\\\\XXX-client-next\\\\plugins\\\\management\\\\XXX.Plugin.DeviceManager\\\\LocalResources.xaml\"}"}}},{"type":"chunk","time":1789529979675,"chunk":{"type":"block-end","index":2,"block":{"type":"text","text":"<tool_call><function=gr</parameter></function></tool_call>"}}},{"type":"chunk","time":1789529979675,"chunk":{"type":"block-end","index":3,"block":{"type":"tool-call","id":"","name":"","arguments":"{}"}}},{"type":"chunk","time":1789529979675,"chunk":{"type":"usage","usage":{"inputTokens":1357,"outputTokens":392,"totalTokens":33237,"cacheReadTokens":31488}}},{"type":"chunk","time":1789529979675,"chunk":{"type":"finish","reason":{"kind":"tool-calls"},"replayState":{"response":{"kind":"pi-ai","version":2,"api":"openai-completions","provider":"xiaomi","model":"mimo-x-flash-preview","responseId":"c30507db-3031-4857-b502-f1cd3bfb5e6e_3f626eb933174aefa9d17a540c1acc91","stopReason":"toolUse"},"blocks":[{"type":"reasoning","thinkingSignature":"reasoning_content"},{"type":"tool-call"},{"type":"text"},{"type":"tool-call"}]}}}]},"surfaceOp":"append"}