Community plugins resolving a second @deepseek-ai/dsh-tools copy crash the tool scheduler with Cannot read properties of undefined (reading 'prepare')

[taonokenshin]

Environment

• dsh 0.1.0-rc.6 (fresh npm install), Windows 11, web profile.
• 12 community plugins installed from GitHub into the profile via pnpm (nodeLinker: hoisted).
• Profile deps: dsh-pdf, dsh-weather, dsh-tool-git, @openbiliclaw/dsh-plugin, dsh-chat-import, dsh-context-doctor (plus pure client/utility plugins).

Symptom (intermittent)

The first tool call of a turn crashes the whole turn with:

Cannot read properties of undefined (reading 'prepare')

(code: UNKNOWN, from dsh-agent-loop). No tool results are appended, so the session history keeps an assistant message with tool_calls and no following tool messages. Every subsequent turn then fails at the API with:

400 INVALID_REQUEST: An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. (insufficient tool messages following tool_calls message)

Disabling all community plugins and restarting eliminates the crash (56+ tool calls since, zero failures). The two affected sessions are permanently un-resumable because of the dangling tool_calls.

Root cause

dsh-agent-loop/lib/index.js:193 reads:

await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec)

TOOL_RUNTIME_SCHEDULER is a per-module Symbol("@deepseek-ai/dsh-tools.scheduler"). The profile's hoisted node_modules resolves its own @deepseek-ai/dsh-tools@0.0.1-rc.1 (satisfying several plugins' ^0.0.1-rc.1 ranges). In that older ABI line the registry class is ToolRegistry and the field is keyed by the old TOOL_REGISTRY_SCHEDULER symbol — same description string, different Symbol instance. One plugin (dsh-context-doctor@0.5.0) additionally bundles a complete second ToolRuntime (class extends Service { super(ctx, "tools") }) with its own local symbol.

When the agent scope's tools resolution lands on an instance minted by a foreign copy, the symbol lookup yields undefined and the scheduler crashes. Profile-loaded plugins bypass the harness.defineTool marker guard that dynamic packages receive, so nothing rejects the alien runtime copy at load time — the failure surfaces hours later, at dispatch, with an opaque message, and silently corrupts session history.

Suggested fix

A load-time guard on the profile plugin loader that:

1. detects a second @deepseek-ai/dsh-tools module instance in the plugin's resolution tree (or asserts the resolved tools service carries the expected scheduler symbol), and
2. fails the offending plugin row with a clear error naming the plugin and the incompatible version,

instead of a delayed runtime crash that also poisons session history.

Evidence bundle

Repro config (profile package.json + cordis.patch.yml), resolved dependency map (.modules.yaml), and the two affected session logs are available; happy to attach.

[argszero]

Thanks for the excellent root-cause write-up — I verified it against the current master source and your diagnosis holds up. Here's the source-level confirmation plus some practical mitigations.

Source confirmation (current master)

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

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

• packages/core/agent-loop/src/tool-calls.ts:169:

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

  There is no defensive check on the lookup — if ctx.tools is a ToolRuntime minted by a different physical copy of the package, the symbol-keyed field is undefined and you get exactly Cannot read properties of undefined (reading 'prepare').
• ToolRuntime is itself the plugin entry (export default ToolRuntime, constructor(ctx, config) { super(ctx, 'tools') }). So a plugin that bundles its own copy of dsh-tools and mounts it registers a second tools service, whose scheduler field is keyed by the foreign Symbol instance.

The key subtlety: Symbol('@deepseek-ai/dsh-tools.scheduler') creates a new Symbol instance per module evaluation. Two physical copies of the package on disk → two evaluations → two distinct Symbols even though the description string is identical. So there are two ways to hit this, both with the same symptom:

1. Version skew between copies (your case): profile's hoisted @deepseek-ai/dsh-tools@0.0.1-rc.1 vs the runtime's newer line. Note master has no TOOL_REGISTRY_SCHEDULER left anywhere — it was renamed to TOOL_RUNTIME_SCHEDULER, so old/new copies can never share the key even if the description matched.
2. Bundled second copy (dsh-context-doctor@0.5.0): even a same-version embedded copy produces a distinct Symbol. This is a plugin packaging bug — @deepseek-ai/dsh-* should be peerDependencies, not vendored.

Practical mitigations

• In the profile directory, run pnpm why @deepseek-ai/dsh-tools to enumerate every physical copy. Then either pnpm dedupe, or force a single copy with an override in the profile's package.json:

  "pnpm": { "overrides": { "@deepseek-ai/dsh-tools": "<version matching the runtime>" } }

• nodeLinker: hoisted makes the second copy at the profile root more likely — worth checking whether the crash disappears with the default isolated linker (though hoisting isn't wrong per se; the real bug is the duplicate).
• Report the vendored ToolRuntime in dsh-context-doctor to its maintainer — re-mounting tools from an embedded copy is what makes the agent scope's ctx.tools land on a foreign instance.

The un-resumable session gap

That's a second, independent robustness issue: agent-loop commits tool_calls to the session before dispatch, and when the scheduler lookup crashes no tool result is ever appended — so the persisted log has a dangling tool_calls the API then rejects. Master still has the same unchecked pattern, so this is worth filing as a feature request to the maintainers: either (a) guard the scheduler lookup and fail the turn cleanly (append a synthetic tool result / abort message so the log stays well-formed), or (b) validate "tool_calls must be followed by tool results" at resume time and offer truncation. Given SESSION_FORMAT_VERSION = 0 (no compat promise yet), a defensive fix in agent-loop would be the cleanest place.

Happy to help draft that feature request if useful. Thanks again for the detailed report — this is exactly the kind of cross-plugin failure mode that's hard to reproduce without a full environment listing like yours.

[taonokenshin]

Update after deeper forensics ? we found the shadowing mechanism that makes this intermittent:

The profile keeps a module map (node_modules/.package-map.json). In the broken state it contained "@deepseek-ai/dsh-tools": { url: "./@deepseek-ai/dsh-tools" } pointing at the hoisted 0.0.1-rc.1 copy pulled in by plugins with stale ^0.0.1-rc.1 ranges. The harness' own 0.1.0-rc.6 copy lives one level up in the shared pool (profiles/node_modules, junctioned from the npm install).

Because the profile-level map shadows the shared pool for host module resolution, @deepseek-ai/dsh-tools could resolve to the rc.1 copy even for the harness' own wiring ? where TOOL_RUNTIME_SCHEDULER (a named export that only exists in 0.1.0-rc.6; rc.1 exports TOOL_REGISTRY_SCHEDULER) is absent, leaving ctx.tools[TOOL_RUNTIME_SCHEDULER] === undefined and producing exactly Cannot read properties of undefined (reading 'prepare') at dsh-agent-loop/lib/index.js:193.

After removing the stale plugins, the map has no dsh-tools entry at all and resolution falls back to the shared pool's 0.1.0-rc.6 copy ? the crash is gone.

Suggestion stands: fail loudly (or never shadow) when a profile hoists a second copy of a runtime package that the harness itself owns, and surface the offending plugin row at load time.