[BUG] Plugin peer-dep creates duplicate dsh-tools instance -> tool scheduling crashes (prepare undefined)

[SJT503]

Bug 1: Installing a plugin with @deepseek-ai/dsh-tools peer dependency breaks tool scheduling (Cannot read properties of undefined (reading 'prepare'))

Environment

• dsh CLI: 0.1.0-rc.6 (npm global install)
• OS: Windows 10 (11 CoreCountrySpecific)
• Profile: web

Steps to reproduce

1. npm install -g @deepseek-ai/dsh (0.1.0-rc.6)
2. dsh plugin --profile web add dsh-better-sidebar (or any plugin declaring @deepseek-ai/dsh-tools as a peer dependency)
3. Start dsh web, open a session, ask the agent to do anything that invokes a tool (e.g. load a skill)
4. The turn fails with:

Cannot read properties of undefined (reading 'prepare')
code: UNKNOWN

Root cause

dsh-better-sidebar@0.10.3 declares peer dependencies on @deepseek-ai/dsh-tools, @deepseek-ai/dsh-credentials, @deepseek-ai/dsh-settings. pnpm then installs a second, independent copy of @deepseek-ai/dsh-tools under the profile's node_modules:

• Global dsh install: C:\...\npm\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai\dsh-tools
• Profile copy: C:\...\.dsh\profiles\web\node_modules\@deepseek-ai\dsh-tools

These are different physical files (verified different inode). TOOL_RUNTIME_SCHEDULER is a module-level Symbol("@deepseek-ai/dsh-tools.scheduler") (see dsh-tools/lib/index.js:2409). Because the two copies are separate module instances, their Symbols differ. dsh-agent-loop/lib/index.js:193 does:

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

ctx.tools was registered by the profile's dsh-tools copy (different Symbol), so ctx.tools[<global Symbol>] is undefined → .prepare throws.

Workaround (confirmed working)

Replace the profile's independent copies with junctions pointing at the global dsh install so there is a single module instance:

New-Item -ItemType Junction -Path <profile>\node_modules\@deepseek-ai\dsh-tools -Target <global>\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai\dsh-tools

After this, tool scheduling (including skill loading) works normally.

Suggested fix

The plugin loader should resolve peer dependencies like @deepseek-ai/dsh-tools against the same instance used by the host dsh runtime (single-instance hoisting), rather than creating per-profile copies.

[ciceroyang]

这是生态里最经典的坑之一——社区叫它"cordis 双副本"(dsh-plugin-dev 技能文档的头条坑),你复现得很准。

机理:工具注册表和调度器各持一份 @deepseek-ai/dsh-tools(以及背后的 cordis)实例。插件声明的 peer 依赖与 profile 里已 hoist 的那份版本对不上时,pnpm 会给插件装第二份独立拷贝;插件把工具注册进"拷贝 B"的 registry,调度器却按"拷贝 A"找,于是 prepare 未定义。

用户侧临时解法(无需改插件):

1. 查树里到底几份:
   dsh plugin --profile web why @deepseek-ai/dsh-tools
2. 常见修复:
   dsh plugin --profile web dedupe
   不行就卸载出问题的插件,等作者修复。

插件作者侧的根修(我们发插件时踩过,已固化进脚手架):

• dsh-tools / dsh-skill / cordis 一律放 peerDependencies 且版本写 *,绝不放 dependencies
• dsh-skill 这类可选服务同时配 peerDependenciesMeta.optional
• 避免把 @deepseek-ai/* 打进出厂文件

参考模板:https://github.com/ciceroyang/dsh-plugin-starter (peer 写法 + 说明都备好了)。

给官方的建议:这类问题几乎必然反复出现——dsh plugin add 之后校验"关键 @deepseek-ai/* 包在 profile 树内唯一"并告警,能拦下绝大多数案例(dsh-doctor 也值得加这一项检查)。

[leether]

Your peerDependencies/autoInstallPeers observation is key — dedup/relink approaches can't cover all cases. Symbol.for sidesteps every copy scenario; see #2078.

[ciceroyang]

感谢指正,#2078 的 Symbol.for 方案确实比 dedupe 治本:模块级 Symbol 是"每副本一 key",全局符号注册表是"同 realm 一 key",一行改动覆盖最普遍的"同进程多副本"场景。

补一个边界供 #2078 参考:Symbol.for 的注册表是 per-realm 的。DSH 还有 worker-thread 边界(code-runtime worker),跨 realm 的副本仍然不共享注册表——所以 Symbol.for 修掉大头之后,loader 层的单副本保证(或重复告警)仍是值得保留的兜底,二者不是替代关系。

三方各就各位最稳:

• 官方 Fix: `reading 'prepare'` crash from duplicate `@deepseek-ai/dsh-tools` copies (Symbol-key mismatch) — a one-line `Symbol.for` fix #2078 修根因(同 realm 副本不再互盲)
• 插件作者守 peer 写法(我们脚手架里已固化:dsh-tools/dsh-skill/cordis 一律 peer + `*`,可选服务加 peerDependenciesMeta.optional)
• 用户侧用 dsh-doctor 的 dedupe 检查先把事故暴露出来(等 Fix: `reading 'prepare'` crash from duplicate `@deepseek-ai/dsh-tools` copies (Symbol-key mismatch) — a one-line `Symbol.for` fix #2078 合入后,该检查可以提示"此 bug 已在 rc.x 修复,升级即可")

生态协作最舒服的样子就是现在这样:报告者给复现,修复方给根因,检测方给护栏。

[floydbsj-Bai]

Confirm on @deepseek-ai/dsh 0.1.0-rc.6 / Windows / dsh web: this trigger does not require a plugin that is still declared in the current manifest.

• Two fresh Web sessions fail with both Pwsh Get-Date and the MCP vision tool read_image.
• The current profile manifest no longer declares the older custom bundle, but stale profile package-map/lock state still retains a profile-local @deepseek-ai/dsh-tools.
• dsh-agent-loop resolves a second copy through the DSH installation closure. Both copies have the same version and identical lib/index.js hash, but their module-local TOOL_RUNTIME_SCHEDULER Symbols are different.

So profile plugin removal/reconciliation can leave the same dual-copy condition behind even after the manifest looks clean. A startup check that names both resolved paths, plus pruning stale package-map/lock entries when a bundle is removed, would make this recoverable instead of surfacing later as undefined.prepare.

[ciceroyang]

That is a significant sharpening of the repro — the dual-copy state can survive plugin REMOVAL, because stale profile package-map/lock entries keep a profile-local @deepseek-ai/dsh-tools materialized even after the manifest no longer declares the bundle. Same-version, identical lib hash, different module-local Symbols — so dedupe-by-version cannot see it, and the manifest looks clean.

Two implications from our side:

1. Detection: dsh-doctor's dedupe check walks the profile tree by resolved real path, not by manifest — a materialized stale copy IS caught (two distinct real paths for dsh-tools → fail with [BUG] Plugin peer-dep creates duplicate dsh-tools instance -> tool scheduling crashes (prepare undefined) #1849 provenance). What it cannot see is stale lock/package-map state that has not been materialized yet; that case needs exactly the startup check you propose (resolve the runtime copies, name both paths, fail before the scheduler does).

2. Recovery: "prune stale package-map/lock entries when a bundle is removed" is the right fix and probably the smaller one — the loader already knows what it removed. A startup check naming both resolved paths is the safety net for the window between removal and prune.

Endorsing your two asks as the consolidated official action for this thread: (a) startup resolution check naming both paths, (b) prune-on-removal. The Symbol.for fix in #2078 remains the belt-and-braces layer for same-realm copies that none of the above can prevent.