Tool calls crash with "Cannot read properties of undefined (reading 'prepare')" when a profile loads a second copy of @deepseek-ai/dsh-tools — TOOL_RUNTIME_SCHEDULER is a module-local Symbol()

[JiewiW]

In @deepseek-ai/dsh-agent-loop (lib/index.js, runGroup → startCall) the tool-call scheduler is read as:

const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec);

TOOL_RUNTIME_SCHEDULER is Symbol("@deepseek-ai/dsh-tools.scheduler") (dsh-tools/lib/index.js:2430) — a module-local Symbol(), not a global-registry Symbol.for(...) — and its value is stored as a class instance field on ToolRuntime:

[TOOL_RUNTIME_SCHEDULER] = { prepare, dispatch, finalize, finish };

while executionMode / prepareScheduledExecution / dispatchScheduledExecution / finalizeScheduledExecution / finishScheduledExecution are prototype methods.

Because the key is module-local, the lookup is only correct while exactly one instance of @deepseek-ai/dsh-tools exists in the process. When the tools service is constructed from a second copy of the package, the two Symbol() keys are different objects, ctx.tools[TOOL_RUNTIME_SCHEDULER] is undefined, and every tool call throws:

TypeError: Cannot read properties of undefined (reading 'prepare')

This is reachable in a documented configuration

Profile module resolution is two-anchor — see the @deepseek-ai/dsh-app-boot module doc: "Pnpm-managed entries in the profile's node_modules resolve first." So a pnpm-managed copy of @deepseek-ai/dsh-tools inside a profile's node_modules shadows the installation copy for the loader's tools entry, while @deepseek-ai/dsh-agent-loop (loaded from the installation) imports the symbol from the installation copy.

Measured on the reporter's machine:

profile anchor (~/.dsh/profiles/web/package.json)
  -> node_modules/.pnpm/@deepseek-ai+dsh-tools@0.1._0f0054f9.../node_modules/@deepseek-ai/dsh-tools/lib/index.js   (0.1.0-rc.8)
installation anchor (dsh-agent-loop's own location)
  -> node_modules/@deepseek-ai/dsh-tools/lib/index.js                                                            (0.1.5-rc.2)
same physical file?                          false
same TOOL_RUNTIME_SCHEDULER symbol?          false

Observed characteristics

• Deterministic on the first tool call of a session — not a mid-session state change and not a parallel-dispatch race (a single read call is enough to fail).
• Turns that make no tool call are unaffected, so a session can look healthy for many turns before the first tool call.
• Independent of the agent preset (minimal / standard / cordis all affected) — the host plane is involved.
• A local workaround exists: call the four prototype methods directly instead of the symbol field. It works because both copies carry those methods, which also confirms the cause is key identity rather than a missing implementation.

Suggested fix (in order of preference)

1. Put the scheduler key in the global symbol registry (Symbol.for("@deepseek-ai/dsh-tools.scheduler")), or expose the staged view as a prototype getter on ToolRuntime, so the contract survives duplicate module instances. Note that cordis itself uses Symbol.for for its cross-package protocol (e.g. Symbol.for("cordis.shadow")) — this symbol is the exception.
2. Otherwise, fail loudly: if ctx.tools exposes the four prototype methods but not the symbol, throw a diagnostic that names the duplicate-copy cause instead of a bare TypeError on .prepare.
3. Optionally, have the loader refuse or warn when a profile's pnpm-managed node_modules shadows an @deepseek-ai/dsh-* package that the installation already provides.

Environment

dsh launcher 0.1.5-rc.1; installation dsh-agent-loop / dsh-tools 0.1.5-rc.2; shadowing profile copy dsh-tools 0.1.0-rc.8; cordis 4.0.2; Node v24.19.0; Windows 10.

[PerryLink]

This is the same root cause as #6416 (verified there in depth, including the
end-to-end repro): a profile that ends up with two copies of
@deepseek-ai/dsh-tools breaks module-local Symbol identity, and the crash you
quote is exactly that failure surface.

Confirmed on master c291e79:

• TOOL_RUNTIME_SCHEDULER is a module-local unique symbol:
  packages/core/tools/src/index.ts:459
  (Symbol('@deepseek-ai/dsh-tools.scheduler')); the registry exposes it at
  tools/src/index.ts:789, and PTC reads it at packages/core/tools/src/ptc.ts:480.
• Dispatch calls ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec) at
  packages/core/agent-loop/src/tool-calls.ts:170. When the registry was
  populated by copy A but the loop imports copy B, the Symbol-keyed lookup
  yields undefined and throws "Cannot read properties of undefined
  (reading 'prepare')" at exactly that line.

User-side triage:

• Run pnpm why @deepseek-ai/dsh-tools (or pnpm dedupe) inside the profile;
  look for two resolved versions/paths.
• Check plugin dependency declarations so every plugin resolves the SAME
  instance (peerDependencies, no bundled copy under a plugin's own
  node_modules).

For maintainers: the durable fix is a cross-instance registry key or a shared
runtime singleton — a core change; #6416 carries the full mechanism and a
browser-free repro recipe.

[JiewiW]

(Edited after checking) Thanks for the detailed analysis and especially the dsh plugin add trigger insight — that was the piece I was missing.

I hit this independently (#6529, now linked as duplicate) on dsh 0.1.5-rc.1 / Windows 10 / Node v24.19.0. Confirmed the same root cause through a different path: the session log showed the TypeError at turn 11, and I traced it by comparing require.resolve('@deepseek-ai/dsh-tools') from the profile anchor vs the installation anchor — two different realpaths, two distinct Symbol()s, === false.

In my case the trigger was @wwskills/dsh-long-memory declaring @deepseek-ai/dsh-tools as peerDependencies: "^0.1.0-rc.6" (not marked optional), plus the profile's pnpm lockfile hoisting a stale 0.1.0-rc.8 to the profile's top-level node_modules. After learning from your analysis that dsh plugin add itself runs pnpm install in the profile (and therefore re-creates the stale copies on every plugin install), I added a startup-time auto-remediation to the launcher:

# DSH.ps1 — runs before dsh web every launch
& powershell.exe -NoProfile -ExecutionPolicy Bypass -File "D:\dsh\DSH-fix-profile-shadowed-deps.ps1" -Silent

Updated recipe (2026-09-14): relink, don't remove. The original -Silent hook moved the shadowing packages out of the profile's node_modules/@deepseek-ai/. That does work — with the profile copies gone, resolution falls through to <DSH_HOME>/profiles/node_modules/@deepseek-ai/* (dsh keeps those as junctions into the installation closure; verified A/B: same_symbol: true, fresh instance serves UI 200 + 15.5 MB combo, empty stderr) — but it is the wrong shape for a machine-level workaround: it removes a package the profile declares (@deepseek-ai/schemastery is in profiles/web/package.json), and the next pnpm install puts it back.

What I run now keeps the profile path and only changes what it points at:

New-Item -ItemType Junction -Path $profilePath -Target $installPath
# profile\node_modules\@deepseek-ai\<pkg>  ->  <install>\node_modules\@deepseek-ai\<pkg>

Same realpath on both anchors → one ESM instance → one Symbol(). Nothing is deleted (the shadowing copy is moved to a backup dir); if pnpm writes a real copy back, the next launch relinks it.

One observation from this incident that may be useful. A separate failure mode, same trigger (pnpm install inside the profile): a hand-made junction mounting a local plugin (node_modules/dsh-long-memory-ui → local source dir, referenced from the profile's cordis.patch.yml) is pruned by pnpm as an unlisted entry. The observable sequence is:

t+0s       process starts, port IS bound, plugin banners printed
t+0..60s   stdout stops, stderr empty, no token URL  →  looks like "running but not serving"
t+~40-60s  exits with:
  Error: dsh: plugin tree failed to load: ... failed to import loader entry long-memory-ui
  (dsh-long-memory-ui): Cannot find package 'dsh-long-memory-ui'
  Error [ERR_MODULE_NOT_FOUND]

So the failure is loud, just ~40–60 s late, and in that window dsh web is indistinguishable from a hang. If boot could reject an unresolvable loader row before binding the port — or print progress while it waits — that window would stop costing people time. Happy to file separately if not tracked.

Thanks again for the thorough upstream analysis and the code-path walk-through. The healProfilesModuleFallback "pnpm entries stay authoritative" rule explains exactly why the copies persist after reboot — I wouldn't have found that on my own.

[zhang-guo-wen]

后续更新：0.1.6-alpha.2 的源码启动回归让本帖描述的“重复 dsh-tools + 本地 Symbol()”弱点变成了默认源码路径可稳定触发的问题。近期重复报告和完整修复方案已集中整理在 #7011 的这条回复。

完整修复需要同时处理两层：

• 解析层：tsx 源码启动默认 link，构建产物/pkg 使用 runtime，并在 profile/plugin 安装后拒绝重复核心包 realpath；
• 运行时层：scheduler 键改为 Symbol.for(...)，且在持久化 tool/call 前验证 scheduler，缺失时给出包含包路径和版本的 typed error。

这样既解决本帖的 profile/plugin 副本问题，也覆盖新的 src/lib 混载与 HMR 触发路径。