Bug: tool calls are dropped against servers that send null in continuation deltas (id/name overwritten, every call becomes UNKNOWN_TOOL)

[zhoukuncheng]

TL;DR

dsh-llm-deepseek loses a streamed tool call's id and name against any server that spells "unchanged" as an explicit null instead of omitting the key. Every tool call then reaches the executor unnamed and is rejected as UNKNOWN_TOOL, so the harness serves conversation but cannot complete a single tool call. One-line-per-field fix, plus tests, on a branch linked below.

I read CONTRIBUTING.md — external PRs are not being accepted right now, so this is a report rather than a pull request. The branch is there purely so the patch and its tests are cherry-pickable; please treat it as attached evidence, not a submission.

Environment

• deepseek-harness at 47f94385 (0.1.0-rc.5), built from source, Node 22.22.1
• Profile: headless, adapter @deepseek-ai/dsh-llm-deepseek (deepseek-official route)
• Endpoint: a self-hosted SGLang server serving deepseek-ai/DeepSeek-V4-Flash-0731, reached by setting baseURL in a --patch overlay. It speaks the DeepSeek dialect natively — thinking: {"type": "enabled"} and reasoning_effort are accepted, and reasoning_content comes back separated — so nothing about the request side is unusual.

Plain chat works. Anything that needs a tool does not.

Symptom

Every tool call fails identically, whatever the tool:

{"type":"tool/result","data":{"message":{"content":[{"type":"tool-result",
 "content":[{"type":"text","text":"Error: unknown tool \"\""}],"isError":true}]},
 "error":{"name":"ToolNotFoundError","code":"UNKNOWN_TOOL"}}}

The corresponding tool/call event shows well-formed arguments with an empty name and an empty callId:

{"type":"tool/call","data":{"turn":1,"step":1,"callId":"","name":"",
 "arguments":"{\"file_path\": \"/…/package.json\", \"limit\": 1}"}}

The failure mode matters more than the error. unknown tool "" names nothing the model can act on, so it retries the same call a few times and then answers from invention. Asked to print the first line of a package.json, the run returned a fabricated file plus a footnote that "repeated tool-invocation errors prevented those calls from executing" — a wrong answer delivered with a plausible excuse. From the outside this reads as a model that ignores its tools, not as a decoding defect, which is why it is worth a report even though the fix is small.

Root cause

packages/llm/llm-deepseek/src/translate.ts (in the delta.tool_calls loop):

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

A tool call carries its identity once: the first delta for a wire index holds id and function.name, and later deltas for that index carry only an arguments fragment. !== undefined accepts null as a value, so on a server that sends explicit nulls each continuation delta overwrites the identity the first delta captured. By the last fragment both are null, and closeBlock emits id: CallId('') / name: ''.

WireToolCallDelta in types.ts declares id?: string and name?: string, so the type says the key is simply absent. That is true of the official API and not of every server implementing the same schema — and it is what makes the undefined comparison look sufficient. (WireDelta.reasoning_content in the same file is already string | null, so the nullable spelling is not new to this wire.)

Wire evidence

Live capture from the endpoint above, one tool call, trimmed to the fields at issue:

# first delta — identity present
"tool_calls":[{"id":"call_4b73c2daf341492892dbd6e3","index":0,"type":"function",
               "function":{"name":"read_file","arguments":""}}]

# continuation deltas — identity explicitly nulled
"tool_calls":[{"id":null,"index":0,"type":"function",
               "function":{"name":null,"arguments":"{"}}]
"tool_calls":[{"id":null,"index":0,"type":"function",
               "function":{"name":null,"arguments":"\"path\": \"/etc/hostname\"}"}}]

I do not think the server is at fault here. Both fields are optional in the chunk schema, and a server that serializes its response model without excluding unset fields emits every unset optional as null. The rest of the same delta shows exactly that: "role":null,"content":null,"reasoning_content":null sit beside the nulled tool-call fields. Absence and null are two spellings of the same statement, and the adapter currently understands only one of them.

Reproduce

Point the deepseek-official route at any OpenAI-compatible server that serializes unset optionals as null (SGLang does by default), then ask for anything requiring a tool:

dsh --profile headless --patch ./selfhosted.cordis.patch.yml \
  "Run 'git rev-parse --short HEAD' and reply with only that hash."

Before the fix: Error: unknown tool "" on every step, then an invented answer. After: the hash.

For a unit-level repro with no server at all, feed translate a first delta carrying id/name followed by continuations whose id and function.name are null; the assembled block-end comes back with id: '' and name: ''.

Fix

Record both spellings in the wire type and assign only on a non-nullish value:

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

Branch: https://github.com/zhoukuncheng/deepseek-harness/tree/fix/tool-call-null-delta-identity (single commit 21564bce5e, cherry-pick freely — no attribution needed).

It contains the two guards, WireToolCallDelta widened to string | null | undefined with the JSDoc stating that omission and null both mean "unchanged", two unit cases, and a bilingual bug-fix Agent Note per AGENTS.md.

The two cases cover a single call whose continuations null out both fields, and two parallel calls whose continuations arrive interleaved and out of index order. Both fail against the previous guard and pass after it, so they hold the behavior rather than describe it. The existing cases for the omitted spelling are untouched and still pass, which is what keeps the official-API path covered — behavior there is unchanged, since an omitted key is nullish under either guard.

Checks run on the branch: pnpm run test packages/llm/llm-deepseek 153/153 (151 before, +2), pnpm run typecheck, pnpm run lint, and pnpm run doc-sync all clean, plus the lefthook pre-commit gates.

Two smaller things found alongside

Neither is a bug, but both cost me time and might be worth a line in the docs:

1. Running the source entry from another working directory fails at import: node --import tsx/esm <repo>/apps/cli/src/bin.ts from outside the repository root gives SyntaxError: The requested module '@deepseek-ai/cordis' does not provide an export named 'FiberState'. Since the invoking directory is the workspace root and there is no --cwd, using dsh against another project from a source checkout means invoking the built apps/cli/lib/bin.js. pnpm dsh works, but only from the repository root.

2. Launcher flags must precede app flags, which the reference does state — but the failure is confusing in one direction: dsh web --port 3099 --patch ./x.yml reports error: unknown option '--patch', because --port already started the app's arguments and the web app then rejects --patch as its own. dsh web --patch ./x.yml --port 3099 is fine.

Thanks for open-sourcing this — the plugin tree and the session log made the root cause a five-minute read rather than a guessing game.

[johnalee123445]

Appreciate the detailed information on Delta Delta Executor. I like posts that explain a technical topic without making everything sound overly complicated, and this one does a good job of keeping things understandable.

[wangziwei734]

Confirmed and reproduced with DeepSeek-V4-Flash via SSE streaming —
the trigger in my case was continuation chunks carrying an empty string ""
for function.name rather than null, but the root cause is identical:
assignment overwrites the already-parsed name instead of accumulating it.

Applied the fix locally in packages/llm/llm-deepseek/src/translate.ts L159–160:

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

[wangziwei734]

Just a heads up: this bug also causes severe secondary damage (bricking session history).

Since the tool call was persisted with an empty callId (""), when you restart and try to load the session log, it triggers a SessionPersistenceCorruptionError ("message must have tool source"). This happens because assertMessageEventShape in packages/core/session/src/index.ts strictly rejects callId === ''.

So this bug not only breaks the current execution but also permanently corrupts the session file. To rescue corrupted sessions, we should relax the empty string check in packages/core/session/src/index.ts:

--- packages/core/session/src/index.ts
+++ packages/core/session/src/index.ts
@@ -336,8 +336,7 @@
   if (type !== 'tool/result') return
   if (sourceRecord['kind'] !== 'tool'
-    || typeof sourceRecord['callId'] !== 'string'
-    || sourceRecord['callId'] === '') {
+    || typeof sourceRecord['callId'] !== 'string') {
     throw new Error(`${subject} message must have tool source`)
   }

补充一个次生灾害及修复方案： 这个 Bug 会导致已经保存的历史会话完全损坏、无法加载（触发 SessionPersistenceCorruptionError）。因为带有空 callId 的异常记录被写入后，重启读取时会被 assertMessageEventShape 的严格校验拦截。要拯救已经坏档的会话，只需按上面的 Diff 移除对空字符串的限制，放宽校验即可正常载入历史脏数据。