Bug: a duplicate @deepseek-ai/dsh-tools inside a profile silently breaks every tool call

[webkubor]

If any package under a profile's node_modules brings its own copy of @deepseek-ai/dsh-tools, every tool call in that profile fails:

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

The scheduler handle is keyed by a module-local Symbol(), so two copies of dsh-tools yield two non-equal keys and the lookup returns undefined. Nothing fails at load time, the message names neither the tool nor the duplicated package, and it also fires from orphaned packages the profile no longer references.

Impact

• Every tool call in the affected profile throws — the agent loop is unusable.
• The session is left corrupted: the turn appends tool_calls but never the matching results, so the next request fails upstream with An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. The conversation has to be abandoned.
• Nothing in the error hints at dependency duplication, so the natural first guess is that the harness or the model provider broke. This took a multi-hour bisect to pin down.

Root cause

TOOL_RUNTIME_SCHEDULER is a module-local symbol:

// @deepseek-ai/dsh-tools/lib/index.js:2416
const TOOL_RUNTIME_SCHEDULER = Symbol("@deepseek-ai/dsh-tools.scheduler");

It is exposed as an instance property of the ToolRuntime service (dsh-tools/lib/index.js:2564; declared in dsh-tool-cordis as readonly [TOOL_RUNTIME_SCHEDULER]: ToolRuntimeScheduler) and read back by the agent loop:

// @deepseek-ai/dsh-agent-loop/lib/index.js:193
const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec);

Since Symbol() (not Symbol.for()) is identity-scoped per module instance, writer and reader must resolve to the same dsh-tools file. A profile-local copy breaks that.

Resolution on my machine — three distinct instances:

agent-loop (reader)  → …/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-tools/lib/index.js
profile web plugin   → ~/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-tools/lib/index.js
profile headless     → ~/.dsh/profiles/headless/node_modules/@deepseek-ai/dsh-tools/lib/index.js

I did not instrument which instance ends up owning ctx.tools; the duplication plus the Symbol() identity rule is enough to explain the undefined.

Reproduction

1. Author a profile plugin that declares a DSH package as a regular dependency instead of a peer:

{ "name": "my-plugin", "dependencies": { "@deepseek-ai/dsh-tools": "^0.1.1-rc.2" } }

2. dsh plugin --profile <name> add my-plugin — a copy lands in <profile>/node_modules/@deepseek-ai/dsh-tools.
3. Boot the profile and ask for anything that calls a tool.
4. Every call throws Cannot read properties of undefined (reading 'prepare').

The part that makes it much worse

The duplicate does not need to be referenced by the profile. My headless profile had:

{ "dependencies": {}, "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless"] } } }

Empty dependencies, and the offending plugin was not in bundles — only a leftover node_modules/@deepseek-ai/ tree from an earlier install. Tool calls still failed on every turn.

Moving that orphaned directory aside fixed it immediately, with no other change:

mv ~/.dsh/profiles/headless/node_modules/@deepseek-ai /tmp/backup/
# the same prompt now answers normally instead of throwing

So uninstalling the plugin isn't enough — a stale node_modules keeps the profile broken, with no configuration anywhere hinting why.

Suggestions

Roughly in order of value:

1. Fail loud at load time. When composing a profile, realpath every resolved @deepseek-ai/* package and throw if one resolves to more than a single path. This matches the stance the codebase already takes elsewhere — dsh-credentials-local rejects rather than skips, reasoning that "a silently ignored entry reads as 'the credential I stored has no effect'". A duplicated runtime package is the same class of failure, with a much wider blast radius.
2. Make the key instance-independent: Symbol.for("@deepseek-ai/dsh-tools.scheduler"). Cheap, and downgrades a hard failure to a merely-redundant install. Best combined with (1) so duplication still gets reported.
3. State the contract for plugin authors. dsh-context gets it right — dependencies: {}, with every @deepseek-ai/* package plus react/zod under peerDependencies — but I couldn't find this written down anywhere, so it reads as a style choice rather than a hard requirement. A line in the plugin docs, plus a warning from dsh plugin add when a plugin declares a @deepseek-ai/* package as a non-peer dependency, would prevent the entire class.

I know external PRs aren't being accepted right now — happy to provide any further detail or to verify a fix against my setup if that's useful.

Environment

@deepseek-ai/dsh	0.1.1-rc.2
Node	v24.15.0
OS	macOS (Darwin 25.5.0, Apple Silicon)
Install	global npm; profiles at ~/.dsh/profiles/{web,headless}