Bug: installing any plugin that depends on @deepseek-ai/dsh-tools breaks every tool call (Cannot read properties of undefined (reading 'prepare'))

[shangdi178]

"### Summary\n\nInstalling any third-party plugin that depends on @deepseek-ai/dsh-tools (e.g. @anweat/dsh-browser, @linxin666/dsh-ssh) breaks every agent tool call with:\n\n\nCannot read properties of undefined (reading 'prepare')\n\n\nThe turn ends immediately after the first tool/call (turn/end reason error). This is a platform-level module-instance shadowing bug, not a plugin bug: the crash site is dsh-agent-loop's scheduler, and the plugin whose install triggered it is never even loaded into the config tree.\n\n### Environment\n\n- dsh 0.1.0-rc.6 (npm global install)\n- Profile: web (generated by dsh; pnpm-workspace.yaml uses nodeLinker: hoisted, autoInstallPeers: false)\n- pnpm 11, Windows 10, Node 24\n\n### Repro\n\n1. dsh plugin --profile web add @anweat/dsh-browser (any plugin whose dependencies include @deepseek-ai/dsh-tools works, e.g. @linxin666/dsh-ssh)\n2. Boot the web profile, start a session, and issue any prompt that triggers a tool call.\n3. The turn fails right after the first tool call with Cannot read properties of undefined (reading 'prepare'). Repeats on every turn.\n\n### Root cause (verified)\n\n1. The profile's pnpm-workspace.yaml (dsh-generated) uses nodeLinker: hoisted, so the plugin's transitive @deepseek-ai/dsh-tools (the same version, 0.1.0-rc.6) is hoisted into the profile's top-level node_modules.\n2. The config tree anchors baseUrl at the profile directory, and bare specifiers resolve profile-first with the host as fallback (HostResolvedRootInclude.import in packages/boot/app-boot \u2192 internal.import(specifier, bareModuleBaseUrl, {})). The tools entry (@deepseek-ai/dsh-tools) therefore loads the hoisted copy instead of the host's copy.\n3. dsh-agent-loop is loaded from the host copy and reads ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec) using the host copy's Symbol('@deepseek-ai/dsh-tools.scheduler') (a module-level unique symbol). The registered ToolRuntime instance was created by the hoisted copy, whose prototype carries a different symbol value (Symbol identity is per-module-instance). The lookup yields undefined \u2192 undefined.prepare(...) \u2192 the exact TypeError above.\n\nVerified empirically: loading both copies of @deepseek-ai/dsh-tools@0.1.0-rc.6 in one process yields TOOL_RUNTIME_SCHEDULER symbols that are not === equal.\n\n### Impact\n\n- Any third-party plugin that imports defineTool from @deepseek-ai/dsh-tools (the platform's own plugin-authoring API) and gets installed with a hoisted profile layout triggers this.\n- Two independent plugins are affected today: @anweat/dsh-browser and @linxin666/dsh-ssh (ships in dsh-web-ui-all).\n- The failure is also completely non-diagnosable: nothing points at duplicate module instances.\n\n### Suggested fix directions\n\n- In HostResolvedRootInclude.import (or the native internal.import fallback), resolve the harness's own scope (@deepseek-ai/* present in the host's node_modules) from the host first, so a profile-installed duplicate can never shadow the host instance; or\n- Detect and warn/error when a profile-installed package shadows a host package of the same name+version, with an actionable message.\n\n### Workaround (verified on the affected setup)\n\nDeclare the SDK as a link: dependency in the profile so the profile resolves the host's copy (same realpath \u2192 same module instance \u2192 symbols match):\n\njsonc\n// ~/.dsh/profiles/web/package.json\n{\n \"dependencies\": {\n \"@deepseek-ai/dsh-tools\": \"link:C:/Users/<user>/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-tools\",\n // ...other plugins\n }\n}\n\n\nthen pnpm install in the profile. After that, tool calls complete normally (verified end-to-end with a Pwsh tool call: 1 \u8f6e \u00b7 2 \u6b65, no errors). Note the absolute path must be adjusted if the npm global prefix changes.\n"

[moonquake2004]

This is the #1486 family surfacing through the plugin install path — same-version dual module instances with module-local Symbol mismatch. Since you called the failure "completely non-diagnosable," one thing that helps: an offline pre-boot check can catch the precondition (a profile-top-level @deepseek-ai/* copy shadowing the host) before anything boots.

We maintain moonquake2004/dsh-doctor (offline diagnostic, profile/session/env) and its P5 check flags exactly this state: any real-directory copy of @deepseek-ai/* at the profile's top-level node_modules is reported as a dual-instance risk (the hoisted-layout shadowing in your root cause). Just updated it to be symlink-aware so your link: workaround is recognized as a single instance (safe) and not false-flagged — the fix is in main (commit 82265ac), tests 41/41.

Worth echoing your suggested fix direction upstream: host-first resolution for the harness's own @deepseek-ai/* scope in HostResolvedRootInclude.import would kill the whole class — P5 exists only because that guarantee isn't there yet.

[zoahdev]

复现并确认了你的根因分析，补一个可直接落地的修复方案（已做机制级验证）。

根因（源码位置确认）

packages/core/tools/src/index.ts:466：

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

Symbol() 的身份是 per-module-instance 的。profile 用 nodeLinker: hoisted 时，插件依赖的 dsh-tools（同版本 rc.6）被提升到 profile 顶层 node_modules，Node 裸说明符解析会先命中这份副本；dsh-agent-loop 用宿主副本的 symbol 去读 ctx.tools[TOOL_RUNTIME_SCHEDULER]，读到的 key 来自另一份副本 → undefined.prepare(...)。和你说的一致，这不是插件 bug。

修复（一行）

-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 走全局 symbol 注册表，同一进程内所有模块实例（无论哪份物理副本）拿到的都是同一个 key；key 仍带 @deepseek-ai/ 命名空间，跨 realm 冲突面可以忽略。ToolRuntime 内部存 key（index.ts:796）和 dsh-agent-loop 读 key（tool-calls.ts:169）都不需要改。

回归测试

新增 packages/core/tools/tests/duplicate-instance.spec.ts：用 vi.resetModules() + query 后缀加载同一模块两次，断言两个实例导出的 symbol 全等，并用"实例 A 写入 scheduler、实例 B 的 symbol 能读到"复现 agent-loop 的查找形状。

机制级验证（真实 npm 包 rc.6）

用两个物理副本（两个独立项目各自 install dsh-tools@0.1.0-rc.6）在同一进程分别 import：

修复前: TOOL_RUNTIME_SCHEDULER identical across two physical dsh-tools copies: false
修复后: TOOL_RUNTIME_SCHEDULER identical across two physical dsh-tools copies: true

修复已放在 fork 分支，方便官方直接取用（当前仓库未开放外部 PR，等开放后可一键 cherry-pick）：

https://github.com/zoahdev/deepseek-harness/tree/fix/tool-runtime-scheduler-symbol-for

顺带：这个问题恰好也是 dsh-plugin-doctor（https://github.com/zoahdev/dsh-plugin-doctor）想提前兜住的场景——发布前在全新 profile 里做真安装/真调用验证，比"能加载"更接近真相。

[moonquake2004]

Good catch on Symbol.for — and nice mechanism-level verification. One trade-off worth surfacing before this lands:

Symbol.for collapses module identity into the global registry, which fixes the same-version shadowing — but it also collapses the version barrier between genuinely different copies. Today a version-skewed duplicate (e.g. rc.5 vs rc.6) yields different keys → undefined.prepare → loud, immediate, diagnosable. With Symbol.for, the agent-loop would read the old copy's ToolRuntime through the shared key — and if the scheduler protocol drifted between releases (dsh-tools is still pre-1.0), that becomes a silent cross-version mismatch, which is much harder to triage than the current crash.

So Symbol.for fixes this instance, but the class remains: any other module-boundary unique symbol pattern (sessions, agents, …) has the same failure mode, and only host-first resolution for the harness's own @deepseek-ai/* scope addresses the whole class. That's also why the offline P5 check (profile-top-level @deepseek-ai/* real-dir copy) stays relevant as a pre-boot class-level tripwire — it flags the precondition regardless of which symbol happens to get hit.

Sensible plan: land Symbol.for as the pragmatic fix now (it's minimal and unblocks affected users), keep host-first resolution on the roadmap as the real elimination, and let the version-skew concern be explicitly re-tested before 1.0.

[zoahdev]

You're right — Symbol.for alone would trade a loud crash for a potentially silent cross-version mismatch. I've updated the fork branch to close exactly that gap.

Upgraded fix: shared key + protocol version guard

1. TOOL_RUNTIME_SCHEDULER_PROTOCOL_VERSION = 1 is now exported from @deepseek-ai/dsh-tools, and the scheduler object itself carries protocolVersion.
2. New assertSchedulerProtocol() in dsh-tools; dsh-agent-loop calls it before every prepare / finalize / finish / dispatch and uses the validated scheduler.

Behavior matrix:

State	Before this change	With the upgraded fix
Same-version duplicate (the #1697 crash)	undefined.prepare	shared key works; if the scheduler is somehow still missing, a descriptive error naming the duplicate-instance cause
Version-skewed duplicate (rc.5 vs rc.6)	different keys → loud undefined.prepare	still loud, now actionable: protocol version mismatch: expected 1, got X + reinstall guidance
Single instance	normal	normal

Regression tests cover all three: symbol identity across duplicate instances, assertSchedulerProtocol accepting the matching version, rejecting a missing scheduler, and rejecting a version-skewed one.

Branch: https://github.com/zoahdev/deepseek-harness/tree/fix/tool-runtime-scheduler-symbol-for

On host-first resolution

Agreed — that eliminates the whole class (any module-boundary symbol, not just this one), and the profile-link: workaround is the same idea applied at install time. Treating it as the roadmap fix is the right call. I'd also love to see your P5-style pre-boot tripwire land as an official dsh doctor-style command (#1719).

In the meantime I'm adding the same tripwire as an optional profile check to dsh-plugin-doctor (detect a real-directory top-level @deepseek-ai/* copy in a profile's node_modules), so the publish path catches the precondition before users hit it. Will ping here when it ships.

[zoahdev]

Shipped as promised: dsh-plugin-doctor v1.2.0 now includes the profile-level tripwire.

dsh-plugin-doctor --profile ~/.dsh/profiles/web

• profile-shadow check: FAILs when the profile's top-level node_modules/@deepseek-ai/* contains a real-directory copy (hoisted duplicate) shadowing the host instance — exactly the precondition your P5 flags, now also available on the publish/diagnostic path.
• Verified both ways: clean profile → PASS (exit 0); fixture with a real dsh-tools directory → FAIL (exit 1) with a message pointing at Bug: installing any plugin that depends on @deepseek-ai/dsh-tools breaks every tool call (Cannot read properties of undefined (reading 'prepare')) #1697.
• Release: https://github.com/zoahdev/dsh-plugin-doctor/releases/tag/v1.2.0

Happy to keep aligning the two doctors: yours is profile/session/env offline diagnostics, ours is the pre-publish plugin + profile tripwire; the checks are complementary.

[moonquake2004]

Verified the v1.2.0 profile-shadow check end-to-end — it works as claimed:

• clean profile → [PASS] profile-shadow: no @deepseek-ai scope at …
• fixture with a real-directory @deepseek-ai/dsh-tools at profile top level → [FAIL] profile-shadow: profile-top-level @deepseek-ai/* real-directory copy(ies) shadow the host: dsh-tools. This can break every tool call (discussion #1697)

Both directions verified, and the FAIL message is actionable. The upgraded Symbol.for + TOOL_RUNTIME_SCHEDULER_PROTOCOL_VERSION guard also closes the cross-version concern cleanly — good call there.

Re: alignment — agreed. Ours stays user-side (profile/session/env offline diagnostics, 19 checks + remote catalog + fixture regression), yours covers the author-side bundle checks plus this profile tripwire; the overlap is exactly the profile-shadow precondition, which both now catch. Ping me when you want to sync the two doctor contracts (JSON schema / exit codes) so they stay interchangeable.