Bug: TOOL_RUNTIME_SCHEDULER symbol mismatch crashes every subagent tool call (fix included)

[rohit267]

Component: @deepseek-ai/dsh-tools + @deepseek-ai/dsh-agent-loop (tested at 0.1.0-rc.8, the synced dsh-* ecosystem version as of 2026-08-21, with @deepseek-ai/dsh@0.1.0-rc.7)

I know external PRs aren't accepted right now (per CONTRIBUTING.md), so posting the finding + a working fix here instead, per that same doc's guidance to report bugs in Discussions.

Summary

Every subagent tool call (ctx.subagents.start('spawn' | 'fork', ...), any tool, any model) crashes the turn with:

Cannot read properties of undefined (reading 'prepare')

Root cause

packages/core/tools/src/index.ts declares:

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

as a module-scoped Symbol(). dsh-agent-loop's tool dispatch reads ctx.tools[TOOL_RUNTIME_SCHEDULER] (runGroup/startCall) to get the scheduler off the live ToolRuntime instance. That index read returns undefined whenever the ToolRuntime instance and the dsh-agent-loop consumer resolved TOOL_RUNTIME_SCHEDULER from two different evaluations of that Symbol(...) call — which happens in at least two real ways:

1. pnpm peer-dependency splitting. packages/bundle/base/package.json depends on dsh-tools directly; packages/core/agent-loop/package.json only has it as a peerDependency. Differing transitive peer sets across consumers can make pnpm install more than one physical copy of dsh-tools.
2. Bundler chunk duplication within the same package. dsh-tools has multiple exports entry points (., ./invariant, ./types, ./presentation). Confirmed empirically: after a clean pnpm run typecheck build, both the . entry's lib/index.js and the internal lib/types/index.js chunk each contain their own independently-evaluated Symbol(...) call for this constant — tsdown/rolldown inlined the shared declaration into two separate output chunks instead of sharing one module instance.
3. Also worth knowing if you're chasing this locally: dsh and an active profile are two separate dependency trees. The CLI launcher (wherever @deepseek-ai/dsh itself is installed) and $DSH_HOME/profiles/<name>/ each resolve dsh-tools independently — a fix/patch applied to only one of the two won't fully resolve the symptom, since dsh-agent-loop can load from one tree while the live ToolRuntime (ctx.tools) is constructed via dsh-base in the other.

Confirmed via a targeted diagnostic comparing Object.getOwnPropertySymbols(ctx.tools) against the imported TOOL_RUNTIME_SCHEDULER: same .toString() description, Symbol.keyFor() returning undefined on the live instance's own symbol (proving it's a plain Symbol(), not Symbol.for()), and identityEqual === false.

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() resolves to the same process-wide value for a given key regardless of how many separate module instances (pnpm copies or bundler chunks) evaluate it, so all three duplication paths above stop mattering.

Branch with the fix (commit + comment explaining why): https://github.com/rohit267/deepseek-harness/commits/fix/tool-runtime-scheduler-symbol-identity

Verification

• pnpm exec tsc -b tsconfig.host.json — zero errors
• pnpm run typecheck (full: tsc -b tsconfig.host.json && tsdown --env.DSH_BUILD_FACE host && tsc -b tsconfig.client.json) — exit 0
• pnpm exec vitest run packages/core/tools packages/core/agent-loop — 30 files, 723 tests, all passing
• Confirmed the fix lands in every duplicated compiled chunk via the real build (lib/index.js and lib/types/index.js both read Symbol.for(...) after the build)
• Reproduced the original crash end-to-end against a live subagent run hitting a real LLM endpoint, then confirmed it's gone with this fix applied (and that ctx.tools's own scheduler symbol becomes identity-equal to the imported constant) after patching all resolution points involved (the package itself, both its bundled entry chunks, and both dependency trees a CLI + profile setup involves)

Reproduction

1. Any dsh profile with @deepseek-ai/dsh-base (or any composition with dsh-agent-loop + a subagent provider + real tool plugins).
2. ctx.subagents.start('spawn' | 'fork', {...}) with a persona that causes the model to call any real tool.
3. Turn ends with { kind: 'error', error: { message: "Cannot read properties of undefined (reading 'prepare')", code: 'UNKNOWN' } }.

Doesn't depend on outputSchema, toolFilter, subagent provider (spawn/fork both crash identically), or model — reproduced with two different models via a custom OpenAI-compatible Ollama endpoint.

Happy to answer questions or send the full local repro if useful — thanks for the project, this took a while to fully pin down so hopefully saves someone else the trip!

[PensiveFei]

Verified against the installed @deepseek-ai/dsh-tools (rc.8): lib/index.js:2416 and lib/types/index.js:57 each contain an independently-evaluated Symbol("@deepseek-ai/dsh-tools.scheduler"), exactly as you describe — the same constant exists twice in two compiled chunks, so a consumer importing from one entry and a ToolRuntime built through the other will never see the same symbol identity. Your Symbol.for() fix is the right call: it makes identity process-wide and immune to pnpm peer-splitting, bundler chunk duplication, and the CLI/profile dual-tree situation.

One extra consideration for the fix: any third-party plugin that imports TOOL_RUNTIME_SCHEDULER (not just dsh-agent-loop) can hit the same mismatch today. Switching to Symbol.for() fixes all of them at once since the key is stable. I'd also suggest a follow-up assertion (e.g. in dsh-tools tests) that Object.getOwnPropertySymbols(registry) finds the scheduler under the shared symbol, so a future refactor that reverts to Symbol() gets caught in CI.

Great find and thorough reproduction — this one would have been painful to debug.

[weijiafu14]

这条的根因分析我完全同意，而且能给你一份独立佐证：我们在自己的发版回归里为同一族失败专门写了一条断言，因为被它坑过。

我们踩的那一脚

我们是 DSH 的外部插件（Pi 生态兼容层），核心包对我们是 peer。规矩本来很清楚：DSH core 由 CLI 的依赖树提供，profile 里只该有 surface 和插件。但 profile 有时会解析出自己的一份 core 拷贝——一旦如此，树里就同时存在两代/两份核心包，instanceof、Symbol()、模块级单例这三类跨包身份全部失效。

所以我们的真机 E2E 里现在硬钉着这几句：

// profile 不许有自己的 core 拷贝——它会遮住 CLI 那份
const profileCore = sh(`find ${profileRoot}/node_modules -maxdepth 4 -path '*/@deepseek-ai/dsh-agent' -print`)
if (profileCore !== '') throw new Error(`the profile resolved its own core copy at ${profileCore} — it would shadow the CLI's core`)

// CLI 树里的 dsh-agent 必须和 CLI 同版本线
if (agentVersion !== expectedCoreVersion) throw new Error(`resolved dsh-agent@${agentVersion}, expected ${expectedCoreVersion}`)

也就是说："同一个包被求值两次"在 DSH 的依赖布局下不是理论风险，是一个我们必须每次发版都主动检查的现实。你这条把它从"版本混装"推进到了"同一版本、peer 提升差异也能触发"，这比我们那条更狠——我们的断言只挡得住版本不同的那种。

一个可能更彻底的修法

如果你的补丁还没定型，考虑把

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

换成

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

Symbol.for 走的是全局 symbol registry，按字符串键跨 realm/跨模块实例返回同一个 symbol。这样即使 dsh-tools 被求值 N 次，ctx.tools[TOOL_RUNTIME_SCHEDULER] 也一定命中——它把"身份"从模块图搬到了运行时全局，而模块图恰恰是 pnpm 布局和打包器分块都能改变的东西。

代价要说清：Symbol.for 的键是全局命名空间，所以键名必须带包名前缀（你现在这个 @deepseek-ai/dsh-tools.scheduler 已经合格了）；类型上 unique symbol 的窄化会丢，需要显式声明。这是 Node 生态里跨包共享品牌/槽位的标准做法——比"确保只有一份实例"更稳，因为后者依赖每个使用者的安装布局都正确，而布局不是你能控制的。

兜底建议

不管走哪条，我建议再加一句 fail loud：ctx.tools[TOOL_RUNTIME_SCHEDULER] 取到 undefined 时抛一个说人话的错（"scheduler not found — dsh-tools may be duplicated in the dependency tree"），而不是让它一路走到 .prepare 上炸出 Cannot read properties of undefined。你这份报告里最贵的部分其实是从那个报错反推到 Symbol 身份的这段路——如果错误自己就说清楚了，下一个人不用再走一遍。

边界

我们不修 DSH 自家组件，上面全是佐证和建议，不是我们能替你落地的东西。Symbol.for 那条我没有在 dsh-tools 上实跑验证过——它是我对你这份定位的推论 + 通用做法，最终以维护者的判断为准。

利益相关：我维护 pi2dsh。这条不推销——重复实例是依赖布局层的问题，多装一个插件只会让树更复杂，帮不上你。

[weijiafu14]

更新：这条已经被完整解决了，而且我上面给的建议不完整——需要更正一下。

#1697 报的是同一个符号、同一个失败（TOOL_RUNTIME_SCHEDULER 的模块级 Symbol()，读到 undefined 后炸在 .prepare），只是触发条件是另一种：profile 的 pnpm-workspace.yaml 用 nodeLinker: hoisted，插件的传递依赖 @deepseek-ai/dsh-tools（同版本）被提升到 profile 顶层，裸说明符解析 profile 优先，于是宿主的 dsh-agent-loop 和被注册的 ToolRuntime 用的是两份副本的两个 symbol。已实测确认两份同版本副本的该 symbol 不 === 相等。

那边的结论走得比我远，有两点值得搬回来：

一、我漏了 Symbol.for 的一个代价

我上面写的两个代价（全局键命名空间、unique symbol 类型窄化）是对的，但漏了更重要的第三个，是 @moonquake2004 在那边指出的：

Symbol.for 修好了同版本遮蔽，但它同时把不同版本副本之间的屏障也一起拆了。今天版本错配（rc.5 vs rc.6）会产生不同的 key → undefined.prepare → 响亮、立刻、可诊断。换成 Symbol.for 之后，agent-loop 会通过共享 key 读到旧副本的 ToolRuntime——如果 scheduler 协议在两版之间漂移过，那就变成一个静默的跨版本错配，比现在这个崩溃难查得多。

这一点我当时没想到，应该说在前面。 我给出 Symbol.for 时把它当成纯改进，实际上它是一次权衡：用"可能静默的跨版本错配"换掉"响亮的同版本崩溃"。

二、正确的形状是"共享键 + 协议版本守卫"

@zoahdev 据此把补丁升级了，我认为这才是完整解法：

1. 从 @deepseek-ai/dsh-tools 导出 TOOL_RUNTIME_SCHEDULER_PROTOCOL_VERSION，scheduler 对象自身带 protocolVersion；
2. 新增 assertSchedulerProtocol()，dsh-agent-loop 在每次 prepare / finalize / finish / dispatch 之前校验。

结果：同版本重复 → 共享键正常工作；版本错配 → 仍然响亮，而且从"undefined.prepare"升级成"protocol version mismatch: expected 1, got X"加重装指引。

换句话说：Symbol.for 负责让重复不再致命，协议版本守卫负责让真正的不兼容仍然喊出来。 两者缺一不可——这正好补上了我上面那条建议的缺口。

三、还有一个可以现在就用的东西

那边同时产出了两个离线诊断工具，都检测同一个前提条件（profile 顶层 node_modules/@deepseek-ai/* 出现真实目录副本，遮蔽宿主那份）：

• dsh-plugin-doctor 的 profile-shadow 检查：dsh-plugin-doctor --profile ~/.dsh/profiles/web
• dsh-doctor 的 P5 检查（symlink-aware，link: 装法不会误报）

两边互相验证过双向结果。如果你现在就想确认自己有没有踩这个坑，跑一下比读源码快。

（顺带：@yzke 在那边报了同一机制的第二个实例——装某个插件会让 profile 顶层出现旧版 dsh-system-prompt 遮蔽宿主，导致内置的 minimal 预设直接挂不上，而 Web 界面什么都不显示。所以这个类不止 dsh-tools 一处，Symbol.for 也只能治它自己那一处；那边讨论的更彻底方向是让 DSH 自己的 @deepseek-ai/* 包始终宿主优先解析。）

建议

这帖和 #1697 是同一个 bug 的两份报告，那边已经有完整的根因验证、升级过的补丁、两个诊断工具和一篇写清全过程的长文。建议把讨论并过去，免得修复分成两条线。

（我这条的定位不变：我们不修 DSH 自家组件，上面是把另一帖的结论搬过来，外加更正我自己给漏的那个权衡。）