Idea: tool-scheduler prepare() failures are very hard to diagnose (Symbol mismatch invisible)

[a1554154492-dev]

Suggestion: tool-scheduler prepare() failures are very hard to diagnose

Where it's hard to debug: packages/core/agent-loop + packages/core/tools

Observed failure: In a web profile, a tool call (e.g. ask_user_question) fails at runtime with:

Cannot read properties of undefined (reading 'prepare')

code: UNKNOWN

The trace points to dsh-agent-loop/lib/index.js:195:

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

Root cause found locally (not a code bug in the harness itself): the profile had a second copy of @deepseek-ai/dsh-tools installed (host = 0.1.2-alpha.5, profile = 0.1.2-rc.1). TOOL_RUNTIME_SCHEDULER is a module-scoped Symbol (packages/core/tools/lib/index.js). Because two different module instances of dsh-tools were loaded at runtime, the two Symbols are not equal, so ctx.tools[TOOL_RUNTIME_SCHEDULER] resolves to undefined and .prepare() throws.

Why the error message is misleading: Cannot read properties of undefined (reading 'prepare') says nothing about why the key is missing. The real cause — two dsh-tools instances with mismatched Symbols — is invisible. It can look like a plugin bug at first, and debugging it required reading source and comparing package versions.

Proposed improvement (open to alternatives):

1. When ctx.tools[TOOL_RUNTIME_SCHEDULER] is undefined in the agent loop, throw a clearer error that names the missing scheduler and hints at a possible duplicate-instance / version-mismatch cause (e.g. check for multiple TOOL_RUNTIME_SCHEDULER symbol identities, or log the resolved dsh-tools version at boot).
2. Optionally, emit a startup warning when the loader detects more than one distinct @deepseek-ai/dsh-tools module instance in the runtime.

This is purely a diagnosability suggestion. The harness behavior itself is correct; the failure came from a version mismatch in the consuming profile. Happy to provide more details if useful.

[argszero]

Great diagnosis — this is a known, well-understood mechanism that has been reported in the community more than once. I can confirm the exact source chain in the current master:

1. Symbol identity is per-module-instance. packages/core/tools/src/index.ts:459:

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

   It uses a fresh Symbol(...), not Symbol.for(...), so its identity is guaranteed unique per loaded module instance. Two separate copies of @deepseek-ai/dsh-tools in the runtime produce two distinct Symbol values.

2. The agent loop reads the key directly. packages/core/agent-loop/src/tool-calls.ts:170:

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

   Because the loop imported TOOL_RUNTIME_SCHEDULER from its own dsh-tools instance while ctx.tools was built from a different instance, ctx.tools[TOOL_RUNTIME_SCHEDULER] resolves to undefined, and the property-access-on-undefined throws the exact Cannot read properties of undefined (reading 'prepare').

So the two-copies-of-dsh-tools / mismatched-symbol mechanism the author identified is exactly right, and the source confirms why the error message is so unhelpful — it reports the property read failing, not the real cause (duplicate module instance).

Your proposed diagnosability improvements are sound. A couple of refinements worth considering:

• Implement the clearer error at the access site in tool-calls.ts:170 (the actual throw point), rather than only in a startup warning. Wrap the lookup: const scheduler = ctx.tools[TOOL_RUNTIME_SCHEDULER] and if !scheduler, throw an Error naming the missing scheduler and suggesting "multiple versions of @deepseek-ai/dsh-tools in the runtime — check the profile/plugin dependency graph". The startup warning would be a nice complement, but the in-place error at the access site is what actually turns this from "looks like a plugin bug" into "you have a version-duplication bug".

• A subtle but useful point: the duplicate-instance problem is not only caused by an explicit host/profile version mismatch. It can also arise from transitive/hoisted duplicates (two dsh-tools copies pulled in by different dependency trees). A robust fix inspects module identity (require.resolve/import.meta path) rather than just the package semver string, since two copies can have the same version string yet still be distinct instances.

This is high-value because the "silent duplicate copy" failure mode has bitten multiple people — a clearer diagnostic would have saved each of them the same source-reading effort you went through. Happy to help test a patch if you'd like to open one.