Fix: reading 'prepare' crash from duplicate @deepseek-ai/dsh-tools copies (Symbol-key mismatch) — a one-line Symbol.for fix

[leether]

ctx.tools[TOOL_RUNTIME_SCHEDULER] resolves to undefined at tool dispatch because TOOL_RUNTIME_SCHEDULER is a module-local Symbol; when multiple physical copies of @deepseek-ai/dsh-tools exist in one process, the agent-loop's key and the ToolRuntime field's key are unequal Symbols. A one-line Symbol.for fix restores the lookup while preserving the author's intent.

Repro / root cause / fix / verification

• Repro: install any plugin that declares @deepseek-ai/dsh-tools as a dependency (or a peerDependency while autoInstallPeers is on), then dsh web and ask the agent to call any tool.
• Observed: Cannot read properties of undefined (reading 'prepare') at dsh-agent-loop startCall; the turn ends with code: UNKNOWN, leaving a dangling tool_call so later turns fail with INVALID_REQUEST.
• Root cause: packages/core/tools/src/index.ts:466 exports Symbol('@deepseek-ai/dsh-tools.scheduler'); dsh-agent-loop imports the same key from a different physical copy, so the two Symbols are not ===.
  This is the dual package hazard — the Node.js-documented case where the same package loaded twice yields two module instances whose identity checks (Symbol, instanceof, WeakMap) no longer match. Here the second instance comes from a duplicate physical copy rather than the usual ESM/CJS dual entry, and Symbol.for is the standard remedy.
• Fix:

  - export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler')
  + export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol.for('@deepseek-ai/dsh-tools.scheduler')

  Symbol.for uses the global registry, so the key is identical across all module instances. It stays a Symbol, preserving the @internal "omitted from the generated named service API" intent.
• Verified: with duplicate copies present, a second dsh web instance now completes tool calls (turn/end completed, tool/result present) on 0.1.0-rc.6.
• Fix available at: leether/deepseek-harness → fix/tool-runtime-scheduler-symbol — a clean single-commit fork branch (the fork's master tracks upstream).
• Related: lands the "registry-based key" suggestion in ToolRuntime scheduler lookup silently returns `undefined` when multiple physical copies of `@deepseek-ai/dsh-tools` exist in one process (Symbol-key mismatch) #572 (point 2); same root cause as Bug: 每次工具调用崩溃 reading 'prepare' — profile 内独立 dsh-tools 副本分裂 Symbol #1418, Community plugins resolving a second @deepseek-ai/dsh-tools copy crash the tool scheduler with Cannot read properties of undefined (reading 'prepare') #1337, [BUG] Plugin peer-dep creates duplicate dsh-tools instance -> tool scheduling crashes (prepare undefined) #1849.

[zoahdev]

Root cause and the Symbol.for mechanism are both right — this is the same bug family I triaged as #1697, and we landed the same key change. One edge case Symbol.for alone doesn't cover, which is why my branch goes one step further.

The remaining gap: version skew

Symbol.for makes the key identical across copies, but not the value's protocol. If two physical copies are from different trains (e.g. dsh-tools@0.1.0-rc.6 in the host and an older copy hoisted from a plugin), the global key means one copy now reads the other copy's scheduler. If their scheduler protocol shapes differ, that's a silent cross-wire mismatch — worse in a different way than the original undefined (it "works" until it doesn't, and it's hard to attribute).

What fix/tool-runtime-scheduler-symbol-for adds

• Symbol.for('@deepseek-ai/dsh-tools.scheduler') (same as yours).
• A TOOL_RUNTIME_SCHEDULER_PROTOCOL_VERSION guard: the shared registry stores { version, scheduler }, and the reader asserts the expected version, so version skew fails loud and actionable instead of silently crossing wires.

Evidence was mechanism-level, not just "it boots": two physical dsh-tools@0.1.0-rc.6 copies with a real Cordis context, plus a three-state matrix (same-version duplicate / version-skew / single instance) — the skew case fails with the guard's message, the duplicate case dispatches normally.

Suggested path

Your branch is a clean, correct subset. When the PR channel opens, I'd propose the combined version (the guard is the part that keeps Symbol.for from becoming a cross-train footgun), or I can open the base and the guard as a follow-up. Happy to reconcile on the exact wording of the guard error — the mechanism is what matters.

Reference: zoahdev/deepseek-harness@fix/tool-runtime-scheduler-symbol-for (cherry-pick-ready against 47f943859b), discussion #1697.

[leether]

Thanks — the version-skew point is exactly right, and it's what pushed us to re-examine the whole thing. We've since revised our position: Symbol.for is a defensive stopgap with side effects (your cross-wire case is one of them), not the fix. The fuller root-cause map, with a self-correction on our earlier "one-line fix" framing, is here: #2130. Your protocol-version guard is the right companion for anyone who keeps Symbol.for in a multi-copy world.

[MrColder666]

thanks！but where is the path for dsh that's directly installed via npm? I don't see a packages/core/tools/src/index.ts at .dsh（windows user directory）

[leether]

Right — the GitHub repo holds the source (the "recipe", .ts under packages/core/tools/src/), but npm ships only the compiled output (the "cooked dish", .js under lib/). So an npm-installed dsh has no packages/core/ tree — that path only exists in the repo or a source checkout.

The line lives in the built file @deepseek-ai/dsh-tools/lib/index.js — find Symbol("@deepseek-ai/dsh-tools.scheduler") (near line 2409 in the current build) and change it to Symbol.for("@deepseek-ai/dsh-tools.scheduler"). On disk that's ~/.dsh/profiles/node_modules/@deepseek-ai/dsh-tools/lib/index.js (Windows: under your .dsh directory, same profiles\node_modules\... path).

Why two copies: the host ships one at profiles/node_modules, and dsh plugin (pnpm) lands a second in profiles/<name>/node_modules when a plugin declares the host package as a plain dependencies. Each copy mints its own Symbol(), so the keys don't match.

So the caveats: (1) patch both copies (host + profile), or the keys still won't match — Symbol.for only unifies if both sides use it; (2) it's wiped on the next install/update, so it's a stopgap. We've since revised the recommendation (see #2130): declare the host package as peerDependencies in your plugin, or run dsh plugin dedupe, rather than patching the built file.