Bug: Tool call with empty name/id → Error: unknown tool "" (UNKNOWN_TOOL)

[Ijon-Miao]

FIX-ANALYSIS.md
ISSUE-REPORT.md

Environment

• dsh version: 0.1.2-rc.1 (not fixed in 0.1.5-alpha.1, per release notes)
• Node.js: v24.15.0
• Platform: Windows (win32)
• LLM gateway: self-hosted DeepSeek gateway at http://10.10.10.10:8000/v1
• Model: deepseek-v4-pro
• Provider: deepseek-official (chat-completions)
• Agent preset: standard (also reproduced with cordis)

Summary

When the model is an instruction that triggers a tool call (e.g. "check"/"检查"), the harness
records the tool call with an empty name and empty id, while arguments is fully populated.
The tool dispatcher then rejects it:

Error: unknown tool ""
ToolNotFoundError / UNKNOWN_TOOL

This repeats in a loop (8 times in one observed turn).

Evidence (decoded from session.jsonl.zstd)

{
"type": "assistant/message",
"data": { "message": { "content": [
{ "type": "text", "text": "user asked..." },
{ "type": "tool-call",
"id": "", // <- empty
"name": "", // <- empty
"arguments": "{"command": "echo ..."}" }
] } }
}

Already ruled out (direct gateway tests)

Test	Result
/v1/chat/completions (non-stream)	function.name == "pwsh" ✓
/v1/chat/completions (stream)	first delta carries name = "pwsh" ✓
/v1/chat/completions (stream + reasoning)	name = "pwsh" ✓
/v1/responses (stream)	name = "pwsh" ✓

The empty name is produced inside the adapter, not upstream.

Suspected code path

packages/llm/deepseek (bundled as @deepseek-ai/dsh-llm-deepseek/lib/index.js)

closeBlock():
case "tool-call": return {
type: "tool-call",
id: brandString(block.callId ?? ""),
name: block.name ?? "", // <- empty if name never assigned
arguments: block.text
};

translate() tool-call loop only assigns name/id when a delta carries them:
if (call.id !== void 0) block.callId = call.id;
if (call.function?.name !== void 0) block.name = call.function.name;

[argszero]

@Ijon-Miao solid report — the code archaeology is right, but I have news that changes the conclusion: this exact defect was already fixed upstream on 2026-09-01, and the release you're on (0.1.2-rc.1) predates the fix. The FIX-ANALYSIS quotes the pre-fix bundle.

The fix, and why your version shows the bug

Commit a1271a4903 ("fix(llm): keep streamed tool-call identity across empty deltas", 2026-09-01, first shipped in dsh-v0.1.3-alpha.1; also present in 0.1.5-alpha.1 — the release notes don't mention it, but git tag --contains confirms 0.1.5-alpha.1 carries it) describes your symptom verbatim: "The assembled block reached the loop with an empty name and failed as unknown tool \"\"".

The pre-fix loop (the code your FIX-ANALYSIS quotes from the 0.1.2-rc.1 bundle) was:

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

null !== void 0 is true, and '' !== void 0 is true — so a continuation delta that repeated id/name as "" or null erased the identity the first delta had established. Your evidence is exactly that shape: arguments fully accumulated into one block while both identity fields came out empty = they were set on the first delta and erased on a later one. Your direct gateway tests passed because a bare /v1/chat/completions call doesn't produce the multi-delta continuation stream the harness's real request does.

What master does now (packages/llm/llm-deepseek/src/translate.ts, current 5dda764 = 0.1.5-alpha.1):

block.callId = acceptIdentity(block.callId, call.id)
block.name = acceptIdentity(block.name, call.function?.name)

acceptIdentity accepts only a non-empty string — undefined, null, '' and any non-string mean "no update", never "clear". WireToolCallDelta was widened to admit null so the values gateways actually send are in the type system. So the empty-continuation trigger no longer reproduces: upgrade to ≥ 0.1.3-alpha.1 and the unknown tool "" path is closed.

Your Direction 1/3 (fail-loud MALFORMED_TOOL_CALL) was tried upstream — and deliberately reverted

The original fix shipped exactly that refusal (error finish at [DONE] for a tool call still missing identity, new retryable code MALFORMED_TOOL_CALL), then commit b03261caad ("fix(llm): narrow the fix to identity acceptance", 2026-09-02) removed it. The recorded rationale (.agents/notes/implemented/architecture/2026-09-01-streamed-tool-call-identity.md): a [DONE] gate that refuses never-identified calls needs a new failure code, a change to the default retryable set, and can override a finish reason the provider already sent — turning a safe max-tokens truncation into up to five retries — all to guard a wire shape no report had demonstrated ("the lenient wire it guards against is hypothetical: no report describes a stream that omits identity entirely"). A block that never receives identity still closes empty, by deliberate decision.

What to do next

1. Retest on 0.1.5-alpha.1 (or 0.1.3-alpha.1+) with the same self-hosted gateway + long-history + reasoning setup. If it stops reproducing — expected for the null/empty-resend trigger — this issue is resolved by upgrade.
2. If it still reproduces there, the trigger is a different shape — most plausibly your path 2 (identity deltas and arguments deltas arriving under different call.index keys), which acceptIdentity does not cover: it guards per-block, so a block whose identity delta landed under another index still closes empty. That class is genuinely unreported upstream, and the evidence needed to reopen it is a raw SSE chunk-sequence capture of the failing stream (chunk 1..n with index/id/name/arguments per delta) — without it, the maintainers' "hypothetical wire" judgment stands.

Family note: this is the wire-identity-loss family (#5413 empty-delta overwrite, #5268 dup-id, #5884 cross-step id reuse), with a distinctive locus — the provider stream translator — and a nastier tail: the empty callId also persisted into tool/result, which the session reader refuses on reopen (the fix commit cites adoptSessionEvent), so a session recording one such call could become unloadable. The acceptIdentity fix closed both halves.

[PerryLink]

Good analysis — I re-checked it against the current source (the 0.1.5-alpha line) and the picture has moved a bit since the 0.1.2-rc.1 bundle you inspected. Three corrections/additions.

What is already in place

packages/llm/llm-deepseek/src/translate.ts now has acceptIdentity(), applied to both identity fields:

function acceptIdentity(current: string | undefined, incoming: unknown): string | undefined {
  return typeof incoming === 'string' && incoming.length > 0 ? incoming : current
}
// ...
block.callId = acceptIdentity(block.callId, call.id)
block.name = acceptIdentity(block.name, call.function?.name)

So a continuation delta that re-sends the field empty or null can no longer clear it, and a name arriving on any delta of the same index is kept. Your Direction 2 is therefore partially implemented already; what remains open is the correlation key and the close-time behaviour.

What is still open (the actual gap)

1. Correlation is still call.index alone: toolBlocks.get(call.index) / toolBlocks.set(call.index, block). A gateway that emits the identity on index: 0 and the argument fragments with index missing, null, or a different value produces two blocks — one carrying name, one carrying only arguments — and the one that closes second is the nameless one. Note a missing index is a single Map key (undefined), so all index-less deltas still share one block; the split only happens when index values genuinely disagree.
2. closeBlock still renders name: block.name ?? '' with no assertion, so a nameless block is emitted as a normal ContentBlock and only fails later in the dispatcher as UNKNOWN_TOOL.
3. No finish-time validation on finish_reason === 'tool_calls'.

Also worth ruling out: the "leading reasoning_content delta" hypothesis is unlikely to be the trigger — reasoning is handled before tool calls and an empty first reasoning chunk explicitly does not open a block.

A fix that fits this file

• Keep acceptIdentity; add an index fallback: when call.index is not an integer, correlate by call.id if present, else by the single currently-open tool-call block.
• Fail loud at close, in the same style as this file's existing throws (MALFORMED_RESPONSE, STREAM_CLOSED):

case 'tool-call': {
  if (block.name === undefined || block.name.length === 0) {
    throw new LlmError(
      `tool-call closed with no name (callId=${block.callId ?? ''}, blockIndex=${block.index}, argumentsBytes=${block.text.length})`,
      'MALFORMED_TOOL_CALL',
    )
  }
  return { type: 'tool-call', id: brandString<ToolCallId>(block.callId ?? ''), name: block.name, arguments: block.text }
}

Because the close loop runs while draining [DONE], this surfaces as a stream error carrying the block index, instead of a successful finish that the dispatcher can only report as UNKNOWN_TOOL.

• Add your Direction 3 (finish-time assertion for finish_reason === 'tool_calls') as a second line of defence, and a regression fixture where the name arrives on one index and the arguments on another.

How to confirm which shape hits you

The raw deltas are persisted: on 0.1.2-rc.1 (your version) the session log carries assistant/chunk events whose data.chunk is the exact tool-call-delta (index / id / name / argumentsDelta); the 0.1.5-alpha line migrated that event to assistant/attempt with data.stream[].chunk. Grepping the failing turn's log answers immediately whether name was ever present on any delta and whether the index values disagree — which decides between "the gateway never sent it" (fail-loud is the whole fix) and "the adapter split the call" (the fallback matters).

If this helped, marking it as the answer keeps it findable for others hitting UNKNOWN_TOOL.

[argszero]

@PerryLink 你的三点修正全部源级成立——我刚在 0.1.5-alpha.1 基线复核了一遍，逐条确认：

• acceptIdentity() 在 translate.ts:85，callId/name 分别应用在 :184/:185；
• 关联键确实仍是 call.index 单独：:115 const toolBlocks = new Map<number, OpenBlock>()、:178 toolBlocks.get(call.index)；
• closeBlock 在 :90，tool-call 分支 :97 确实 name: block.name ?? '' 无断言——nameless 块被当正常 ContentBlock 发出，只能在 dispatcher 里晚失败成 UNKNOWN_TOOL。

所以你说「Direction 2 已部分实现、剩下的是关联键 + 关闭时行为」这个判断准确，我的原回复确实忽略了这层。

关于你的修复方向，我的两点补充

1. "哪一个 shape 打到你"的判别器值得优先写。你结尾那句诊断路径很关键——原始 delta 是持久化的。在 0.1.2-rc.1 上 session log 带 assistant/chunk 事件（data.chunk 就是原始 tool-call-delta，含 index/id/name/argumentsDelta）；0.1.5-alpha 线把它迁到 assistant/attempt 的 data.stream[].chunk。grep 失败那个 turn 的日志能立刻回答「name 到底出现在没出现在任何 delta 上、index 值是不是真的分歧」——这决定了是「gateway 从未发 name（fail-loud 就是全部修复）」还是「adapter 把 call 拆成了两个 block（fallback 才有意义）」。

2. 你的 close-time fail-loud 修复我认可，且和你 cite 的文件现有风格一致（该文件 :209 本来就抛 STREAM_CLOSED，:~ 也抛 MALFORMED_RESPONSE）。把 closeBlock 的 tool-call 分支改为「name 为空即抛 MALFORMED_TOOL_CALL（带 callId/blockIndex/argumentsBytes）」，因为 close 循环是在 drain [DONE] 时跑的，所以这会以携带 block index 的流错误浮出，而不是一个 dispatcher 只能报 UNKNOWN_TOOL 的成功 finish。这是我同意的点。

一处边界提醒

acceptIdentity 只保 incoming 是非空 string 时更新——你 Cite 的效果是「同一 index 的任何 delta 到了 name 就保留」，这正是名实对应的好行为。但要小心与之组合的 fallback：当引入「index 非整数时按 call.id 关联、否则按当前唯一 open tool-call block」之后，一个「先发 name（index:0）、后续参数无 index」的真实 case 会被归并到同一个 block——这修复了拆块，但也意味着「无 index 的参数」全都进一个 block。如果 gateway 同时并发多个无 index 的调用，这个 fallback 会在 map 上把它们也合并。所以 fallback 的触发面要窄（只在 call.index 非整数时用），且理想情况配上「无 index 且已有多个 open tool-call block 时fail-loud而不是猜」。

整体方向我赞成，这是对 upstream 那条 2026-09-01 fix 的合理收尾。如果你的修复落地了、或者想让我在你的 patch 上加 finish_reason === 'tool_calls' 的 finish-time 断言作第二道防线，我可以补。