Duplicate in-box @deepseek-ai/* package in a profile silently breaks every tool call

[CancerTiN]

Summary

Installing a third-party plugin that declares an in-box package (here @deepseek-ai/dsh-tools) as a dependency makes pnpm materialize a second copy inside the profile. Module identity then splits for a module-local Symbol that keys a runtime surface of the tool registry, so ctx.tools[TOOL_RUNTIME_SCHEDULER] reads back undefined and every tool call in that profile fails — bash, read, and the plugin's own tool alike. The surfaced error names prepare, not the duplicated package, so a plugin author gets no signal that their package.json caused a harness-wide breakage.

This is the highest-value finding of the three: it punishes exactly the behaviour the extension docs encourage (defineTool from @deepseek-ai/dsh-tools), and the crash is unattributable.

Reproduction

# any plugin package whose manifest declares an in-box dependency
cat package.json      # { "dependencies": { "@deepseek-ai/dsh-tools": "0.2.0-rc.2" } }

dsh plugin --profile headless add file:/path/to/that-plugin

# then run any task that uses a tool
dsh --profile headless "用 bash 工具执行 pwd，然后报告输出。"
# dsh: UNKNOWN: Cannot read properties of undefined (reading 'prepare')
# exit 1

Isolation on the same profile, same task, only the dependency varying:

profile state	result
plugin installed with the dsh-tools dependency	❌ Cannot read properties of undefined (reading 'prepare')
plugin removed (pnpm prunes the profile copy)	✅ pwd runs, exit 0
plugin reinstalled with no dependency at all	✅ both the first-party bash tool and the plugin's own tool run, exit 0

Current behavior

The model's tool call is reached and logged, then the turn dies before dispatch:

{"type":"tool/call","seq":20,"data":{"name":"set_session_title","arguments":"{\"title\":\"端到端改名验证\"}"}}
{"type":"turn/end","seq":23,"data":{"reason":{"kind":"error","error":{"message":"Cannot read properties of undefined (reading 'prepare')","code":"UNKNOWN"}}}}

A first-party-only task in the same state fails identically:

$ dsh --profile headless "用 bash 工具执行 pwd，然后报告输出。"
dsh: UNKNOWN: Cannot read properties of undefined (reading 'prepare')

Expected behavior

Either the duplicate cannot arise (in-box packages resolve from the installation only), or it is detected and reported as what it is: a profile-local copy of a harness package shadowing the installation's. A bare TypeError from .prepare is the one outcome that should not be reachable.

Environment

Harness	DeepSeek Harness desktop app, @deepseek-ai/dsh-desktop-runtime 0.2.0-rc.2
Profile	headless (shipped template), also reproducible in any profile that installs such a plugin
OS	macOS 26 (darwin/arm64)
DSH_HOME	~/.dsh
Node / pnpm (app runtime)	24.21.0 / 11.7.0
Session format	v4

Root cause

@deepseek-ai/dsh-agent-loop reads a symbol-keyed surface off the registry:

// dsh-agent-loop, lib/index.js ~line 582 (also ~570 for finalize/finish)
import { TOOL_ABORTED_BEFORE_DISPATCH, TOOL_RUNTIME_SCHEDULER } from "@deepseek-ai/dsh-tools";
const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec);

and that symbol is module-local, not global:

// dsh-tools, lib/index.js ~line 2526
const TOOL_RUNTIME_SCHEDULER = Symbol("@deepseek-ai/dsh-tools.scheduler");

class ToolRegistry {
  [TOOL_RUNTIME_SCHEDULER] = { prepare: …, dispatch: …, finalize: … };   // ~line 2674
}

Identity of a plain Symbol(...) is per module instance, so the reader and the registry can bind different copies of dsh-tools. Because dsh plugin --profile <name> add <pkg> runs pnpm in the profile, any plugin that declares @deepseek-ai/dsh-tools (the documented home of defineTool) installs a profile-local copy that shadows the installation's.

The failure mode is not specific to dsh-tools: every in-box module pair that defines and consumes a module-local Symbol, class brand, or instanceof target has it once a profile carries a duplicate.

Suggested fix

1. Use Symbol.for("…") for cross-module runtime seams so identity survives two copies — smallest change, closes the whole class of bug.
2. Resolve in-box @deepseek-ai/* specifiers from the installation only, and warn (or fail loud) when a profile's node_modules shadows one. Silent shadowing is what makes this expensive to diagnose.
3. Failing either, make the crash self-describing: when the scheduler surface is absent, throw a message naming the duplicated package and the profile instead of letting undefined.prepare escape.

Workaround for plugin authors

Declare no dependencies and hand-write the tool definition — ctx.tools.register() only requires output: { schema, render } plus a schema inside the supported subset (type/properties/required/additionalProperties/items/enum/const + the description annotation), which is what defineTool compiles a declaration into anyway:

ctx.tools.register({
  name: "set_session_title",
  description: "…",
  parameters: { type: "object", properties: { title: { type: "string", description: "…" } }, required: ["title"] },
  output: { schema: { … }, render: (_args, value) => [{ type: "text", text: `…${value.title}` }] },
  execute(args, exec) { … }
});

The trade-off is losing defineTool's argument-validation wrapper, so execute validates by hand. Worth documenting as a hazard until (1) or (2) lands.

[argszero]

Thanks — the three-arm table is what makes this actionable, and it pins down something the earlier reports of this signature did not: the unit here is a copy on disk, not one realpath evaluated twice. Here are the source anchors for the mechanism you traced from the bundled output, plus one thing about your fix (2) that I think is worth knowing before anyone writes it.

The identity, in source. TOOL_RUNTIME_SCHEDULER is a unique symbol at packages/core/tools/src/index.ts:480, and the registry carries it as a class property at :816. The read that dies is packages/core/agent-loop/src/tool-calls.ts:170 — await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec) — which is exactly why the surfaced message names prepare and nothing else.

Why the copy appears, precisely. Every profile dsh initializes is written with its own pnpm-workspace.yaml (packages/boot/app-boot/src/profile.ts:233):

nodeLinker: hoisted
autoInstallPeers: false

with the intent stated in the comment above it (:226): "The hoisted linker gives out-of-tree plugins a flat node_modules whose missing peers (cordis and friends) use the runtime resolution, so every plugin shares the installation's single cordis instance instead of a duplicate." autoInstallPeers: false is what makes that work for peers — a peer is never materialized, and the profile-resolution service answers instead (packageOf, packages/boot/app-boot/src/profile-resolution/service.ts:96, which locates a package directory without importing it). A dependencies entry is not a peer: the linker installs it, flat, into <profile>/node_modules. So the one field that can produce this is the one the authoring guide still permits for dsh packages.

The line that invites it. docs/user/develop/basic/publish.md:103 ends with: "Keep independently versioned third-party dependencies and stateless dsh utilities under dependencies." From the outside @deepseek-ai/dsh-tools looks like a stateless utility — you import defineTool, a couple of types, and a schema helper — but it is not stateless: it publishes module-instance identity, and that identity cannot span two copies. The shape the cookbook teaches is the one that is safe (docs/cookbook/extension-cookbook.md:17): import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools' — type-only, erased at runtime, so nothing under the profile ever resolves the package. I don't think the fix is only Symbol.for; that sentence is the widening that leads here, and it is the cheapest thing to narrow.

On your fix (2): the data already exists. RuntimeResolution (packages/boot/app-boot/src/profile.ts:150) already carries the whole answer — entries with scope: 'installation' | 'profile' and declarer, documented as "Manifest whose dependency edge selected this package" (:124–:135) — plus localPackageNames, "Profile-declared packages installed in the profile's own node_modules" (:156). "An installation-owned name that is also present locally" is therefore a set intersection the launcher can compute at profile resolution, before any plugin is imported and long before the first tool call. That is a far smaller change than a new scan pass, and it is where a loud warning belongs. Your (1) remains the only fix that makes the class of bug disappear rather than reporting it.

What I published, because the second branch of your "Expected behavior" is directly satisfiable. "Either the duplicate cannot arise … or it is detected and reported as what it is: a profile-local copy of a harness package shadowing the installation's." The second branch is a plugin:

• npm: https://www.npmjs.com/package/@argszero/cordis-plugin-profile-duplicate-doctor (0.1.0, MIT)
• source: https://github.com/argszero/cordis-plugin-profile-duplicate-doctor

What it does, in the terms your report uses:

1. Boot scan. It enumerates the top level of <profile>/node_modules, keeps the entries whose name the installation also owns, and compares each one to the installation's copy by realpath. A link into the installation resolves to the same directory and is not reported — nor is a generated proxy manifest, the harness's own redirection — while a distinct directory is a second copy, reported together with the manifest that declared it, its section, its range, and its path:

   harness package: @deepseek-ai/dsh-tools
     profile copy:       /Users/…/.dsh/profiles/headless/node_modules/@deepseek-ai/dsh-tools (v0.2.0-rc.2)
     installation copy:  /…/dsh-runtime/node_modules/@deepseek-ai/dsh-tools (v0.2.0-rc.2)
     declared by:        my-plugin (dependencies: 0.2.0-rc.2) at /Users/…/.dsh/profiles/headless/node_modules/my-plugin/package.json
   

   Harness packages are the identity class — the shape you found; any other installation-owned name is reported as a duplicate with "usually harmless" said rather than asserted away. A clean profile says so too, because a quiet start and a scan that never ran must not look alike.

2. One durable advisory per agent. It rides agent/pre-step — the same waterfall, and therefore the same message batch the loop commits into history — so the diagnosis is in the conversation before the first tool call, instead of a bare TypeError naming prepare. One message per agent, not per step.

3. The remedy it names, with the edit attributed to the declaring manifest: move the package to peerDependencies (and devDependencies for the type check), run pnpm install in the profile, restart. Retrying, restarting the session, or reinstalling the plugin with the dependencies entry still present all reproduce it — which is what your table shows.

Mount:

# cordis.yml
plugins:
  '@argszero/cordis-plugin-profile-duplicate-doctor': {}

The honest boundary. This is detection and attribution, not repair — expect (2), not (1). A plugin cannot remove the copy, and should not: by the time anything is loaded the symbol has already been evaluated twice, and rewriting another package's node_modules is not a third-party plugin's business. What was actually missing from this report's perspective is the attribution — that a specific manifest's dependencies field caused it — and that is what a scan over the profile can supply without any core change. The plugin states this limit in its own output, along with the two it shares with any file-level check: only the top level of <profile>/node_modules is inspected (the hoisted-linker shape), and a copy nested inside another package's own node_modules is not seen.

Evidence, if it is useful: 43 behaviour arms driven through a real cordis context, the real agent/pre-step waterfall, and real profile trees on disk (including the unmounted control, the symlink-into-the-installation shape, the module proxy, and a copy nothing declares); a packaging guard over the published tarball; and 14 injected defects — weaker comparison, dropped gate, missing boundary sentence, hoisted state — each required to turn the suite red, none silent.

If the wording or the severity split should say something different for a shipped template like headless, tell me and I'll cut a new version — the mount is a plugin, so it can also be installed just for the profile under investigation (dsh plugin --profile headless add @argszero/cordis-plugin-profile-duplicate-doctor) while a real fix is pending.