Bug: llm-deepseek adapter drops tool name/id when relay sends explicit null in stream chunks

[sonsheone]

Summary

When using a third-party OpenAI-compatible relay (e.g. opencode.ai/zen/go/v1) that sends explicit null for tool_calls[].function.name / tool_calls[].id in later stream chunks of one tool call, the llm-deepseek adapter treats null as a present value and overwrites the real name/id from the first chunk. Result: the harness receives unknown tool "" errors, the model retries repeatedly, and the run fails.

Environment

• dsh: deepseek-harness (master, b150a55)
• Package: @deepseek-ai/llm-deepseek (packages/llm/llm-deepseek)
• Provider: DeepSeek official works; third-party OpenAI-compatible relay reproduces the bug
• Model: deepseek-v4-flash

Repro

1. Configure llm-deepseek with baseURL pointing to a relay that, on a streaming tool call, emits chunk 1 {"tool_calls":[{"index":0,"id":"call_1","function":{"name":"bash","arguments":"echo hello"}}]} and later a chunk {"tool_calls":[{"index":0,"id":null,"function":{"name":null,"arguments":"..."}}]} (explicit null instead of omitted field).
2. Ask the agent to use the bash tool.
3. Session file shows Error: unknown tool "" repeated; the real tool name never surfaces.

Root cause

In packages/llm/llm-deepseek/src/translate.ts (and compiled lib/), the streaming tool_calls parser guards with !== undefined:

• Official API omits unset fields → undefined → guard false → previous value kept (correct).
• Some relays serialize null explicitly → null !== undefined is true → guard passes → overwrites real name with null → downstream maps to "".

Proposed fix (1-line each)

Change !== undefined to != null in the streaming tool_calls parsing path:

- if (call.id !== undefined)
+ if (call.id != null)
      block.callId = call.id;
- if (call.function?.name !== undefined)
+ if (call.function?.name != null)
      block.name = call.function.name;

!= null covers both undefined (omitted) and null (explicit) as "absent", matching OpenAI-compatible relays that explicitly emit null.

Notes

• After patching locally, bash tool worked end-to-end through the relay.
• Same guard pattern may exist in other adapters/packages; worth a repo-wide sweep for !== undefined on streamed nullable fields.

[argszero]

Confirmed against b150a55 (the exact commit you quote) — your diagnosis is precise, and the proposed != null fix is correct. Two additions from a sweep of the rest of the tree:

1. The bug is real exactly as described

packages/llm/llm-deepseek/src/translate.ts lines 159-160 use the guard call.id !== undefined and call.function?.name !== undefined to decide whether to overwrite the accumulated block values. With a relay that emits explicit null in a later chunk, null !== undefined evaluates true, block.callId and block.name are overwritten with null, and the downstream CallId construction (block.callId ?? empty string) plus the name spread turn that into empty id and empty name — the unknown tool retry loop you observed. The official API omits the fields (undefined), so the !== undefined guard was fine against it; the guard conflates "absent" with "present but null", and OpenAI-compatible relays in the wild serialize the latter. != null covers both — the right fix.

2. A second, worse instance of the same conflation lives in llm-pi-ai

packages/llm/llm-pi-ai/src/stream.ts:

• The toolcall_start handler copies partial.id and partial.name straight through a ternary, so an explicit null from a relay lands as null (not the empty-string fallback). The line reads: const name = (partial type is toolCall) ? partial.name : empty string — with type toolCall and name null, the ternary yields null unchanged.
• The delta handler then guards on name !== undefined AND name.length greater than zero. With name strictly null, the first clause passes (null !== undefined is true) and the second clause evaluates null.length, which throws TypeError mid-stream — a crash, not a silent empty name.

So the same root (explicit null treated as a present value) has two manifestations in the llm layer: silent overwrite in llm-deepseek (your report) and a hard crash in llm-pi-ai. Worth fixing both, and the llm-pi-ai side should normalize at the source (coalesce to empty string where the value is copied) rather than patching the consumer.

3. Same class as the family this repo already tracks

The "explicit null is absence, not a value" conflation has now bitten in: #1713 / #2997 (null-delta in the serializer/assembler — null treated as a present delta overwrites real data), and now this pair in the llm stream adapters. Same root shape: a guard written for the happy-path wire format (fields omitted) breaks when a peer serializes absence explicitly. A repo-wide sweep for !== undefined guarding nullable fields is worthwhile — the pattern is now confirmed live at 4+ sites.

4. Regression shape

A fake stream that emits chunk 1 with id and name set and chunk 2 with explicit null for both, asserting the emitted tool-call-delta keeps the chunk-1 values. Cheap, and it pins the exact relay behavior the report describes.

中文摘要：已对照 b150a55 确认——translate.ts 第 159-160 行的 undefined 守卫正是问题所在，!= null 修复正确（官方 API 省略字段为 undefined，relay 显式 null 则穿透守卫覆盖真实值）。sweep 发现第二处更严重的同形：llm-pi-ai/stream.ts 的 toolcall_start 三元分支让 null 穿透，delta 处理里 null.length 直接 TypeError 崩溃（不是静默覆盖）。家族关联：与 #1713/#2997（null-delta 被当 present 值覆盖真实数据）同根——「显式 null 是缺失不是值」的守卫漏洞在 llm 流适配器再次出现。回归测试形态：chunk1 带 id/name + chunk2 显式 null，断言 delta 保留首值。

[argszero]

Follow-up correction to my own previous comment, and a family convergence that makes this report more significant than a one-line fix:

1. The != null fix is not complete — the family already proved the empty-string variant

This is the 4th independent report of the exact same mechanism (explicit-null continuation deltas wiping captured tool id/name through the !== undefined guards at translate.ts:159-160):

• Streamed tool calls lose name/id against OpenAI-compatible servers that send explicit nulls (SGLang) — every call fails as UNKNOWN_TOOL #1713 — SGLang endpoint (BehindTheCartan, 2026-08-15)
• Bug + one-line fix: streaming tool calls lose function.name when continuation chunks send name: null (dsh-llm-deepseek, rc.6) #2090 — Xreative, same bug, same one-line fix
• [Bug] Tool-call name dropped when gateway streams explicit "null" name deltas (dsh-llm-deepseek) #2997 — opencode.ai zen gateway, "name": null + "id": null in continuation deltas, same mechanism
• Bug: llm-deepseek adapter drops tool name/id when relay sends explicit null in stream chunks #4265 — this report (opencode.ai/zen/go/v1)

And the family's hard-won refinement: != null does NOT cover explicit empty strings ("" != null is true). #2169 (wujason759, deepseek-official) proved the empty-string variant is worse than null — continuation deltas with id:""/name:"" persist a tool/result with source.callId === "", and session-load validation (core/session/src/index.ts:339-342) throws on that, making the history permanently unloadable — a poison, not a recoverable per-turn break. #2540 (arnold-gopagoda) and #2343 (lanjie8) independently confirmed the same. The family-complete guard is a truthy check: if (call.id) block.callId = call.id / if (call.function?.name) block.name = call.function.name — covers missing, null, and empty string in one form.

2. The canonical fix is three layers, not one line

• L1 — translate.ts:159-160 truthy guards (covers null and empty string; != null covers only null)
• L2 — packages/llm/llm/src/assembler.ts:70 partial.toolCallId = chunk.id is unconditional while :71 name is already truthy-guarded — the id guard was never added (predates the wire fixes); a translate-only fix leaves the assembler vulnerable for every other provider adapter
• L3 — assembler.ts assemble() should backfill name/id from accumulated partial.* when the raw block-end carries them empty (Bug: Tool calls fail with `unknown tool ""` (empty name) when a large tool call is split into multiple stream chunks #2855's contribution — the raw block short-circuit layer)

Family total now: 6 poison paths / 11 threads (#1449/#1519/#1337/#1593/#2169 + identity-loss #1713/#2090/#2997/#4265, with #2343/#2540/#2855 confirming variants and layers). One regression test with three wire samples (null, empty-string, omitted) pins the whole family.

3. The llm-pi-ai crash site I flagged stands on its own — stream.ts:172 null.length TypeError is genuinely new (pi-ai's event shape), though same root philosophy: absent-null must not be treated as a present value.

中文摘要（更正+收敛）：我上一条评论说的 != null 修复不完整——家族记忆已证明空串变体（#2169/#2540/#2343）：显式空串穿透 != null（空串不等于 null），持久化 callId 空串 → session 加载抛错 → 历史永久不可加载（毒化）。正确守卫是 truthy 形式（if (call.id)），一次覆盖缺失/null/空串三种状态。且规范修复是三层：L1 translate 守卫、L2 assembler.ts:70 id 守卫缺失（:71 name 已有）、L3 assemble() backfill（#2855）。本报告 = #1713 家族第 4 实例，家族累计 6 毒化路径 / 11 线程。