Web 工具调用时 .prepare 未定义的问题

[sunny-zhai]

问题描述：
更新代码后，Web 会话在模型调用工具时失败，页面显示：

本轮运行失败
Cannot read properties of undefined (reading 'prepare')
UNKNOWN

普通文本回复可能正常，但调用 BashProbe、BashTest、job_list 等工具时失败。
问题原因：
dsh-tools 内部的工具调度器使用普通 Symbol() 标识：
Symbol('@deepseek-ai/dsh-tools.scheduler')
当 Web bundle 中加载了多个 dsh-tools 副本时，不同副本生成的 symbol 不相等，导致 agent-loop 无法找到 ToolRuntime 的 scheduler，最终在调用 .prepare() 时触发运行时错误。
修复内容：
将内部 scheduler 标识改为：
Symbol.for('@deepseek-ai/dsh-tools.scheduler')
相同 key 在同一进程内始终返回相同的 symbol，确保不同 bundle 中的 agent-loop 和 ToolRuntime 可以访问同一个工具调度器。
QA 测试版本：
仓库：sunny-zhai/deepseek-harness
分支：master
Commit：00649801cfb24ed3e42469d2356fc4d014547eb7
修改文件：packages/core/tools/src/index.ts
项目版本：dsh 0.1.6-alpha.2
平台：macOS
Node.js：v24.19.0

[argszero]

Your diagnosis is right and the crash site matches your reasoning line for line. Three things I can add from reading the tree: your patch is not a workaround — it is the convention this repository already uses for exactly this problem, and it has a name; the "Web" in the title is where the error is rendered, not where it happens; and the same criterion that makes your patch right also tells you which neighbouring keys are at risk and which are not.

The crash site, exactly

• Minted once per module evaluation — packages/core/tools/src/index.ts:463:

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

• Installed on the service by the copy that owns the class — :798: readonly [TOOL_RUNTIME_SCHEDULER]: ToolRuntimeScheduler = { … }

• Read from a different package — packages/core/agent-loop/src/tool-calls.ts:153, :154, :170, :174, all of the form ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(…)

So the failing lookup is ctx.tools[<agent-loop's symbol>] against an object keyed by <tools' symbol>. With two evaluations that is undefined, and .prepare is simply the first property touched — the message names the property and never the cause. (packages/core/tools/src/ptc.ts:550 reads the same key, but it lives in the same package, so it can never disagree with itself.)

Your patch is the repository's own convention — and it is documented

The tree does not merely tolerate Symbol.for; it uses it for cross-evaluation identity and calls the property "process-stable":

• packages/subagent/subagent/src/internal.ts:15 — Symbol.for('dsh.subagent.adjacentAgentSendMessageTool'), docstring: "Process-stable identity carried only by the standard adjacent-Agent messaging tool."
• :42 — Symbol.for('dsh.subagent.deliverPrompt'), docstring: "Process-stable symbol-keyed host delivery shared by the bundled runtime entry and this unbundled internal subpath." ← that sentence is your bug, named by the maintainers, in a package they hardened the same way.
• packages/typert/protocol/src/owned-value.ts:4 — Symbol.for('dsh.typert.owned-value'), with a test that pins registry identity instead of declaring a local symbol: packages/typert/protocol/tests/owned-value.spec.ts:20 — expect(TYPERT_OWNED_VALUE).toBe(Symbol.for('dsh.typert.owned-value')).
• packages/experimental/inspector/src/shared/cordis/collector.ts:14 and object-registry.ts:170 (globalThis[Symbol.for(…)]) — a registry explicitly designed to be shared across evaluations.

The term also appears in the architecture record .agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.md:49 ("a process-stable internal identity"). TOOL_RUNTIME_SCHEDULER is the outlier: a cross-module identity key still minted with a local Symbol().

The criterion — and why the neighbours are fine as they are

A module-level symbol needs registry identity exactly when it is used as a key on an object that another module evaluation may have produced: a lookup object[SYMBOL] where the two sides can come from different evaluations. Two neighbours show the other side of that line:

• packages/core/scope/src/index.ts:18 const kScope = Symbol('dsh.scope') — written at :140, read at :155, both inside the same module ⇒ it cannot disagree with itself ⇒ safe as a local symbol.
• packages/core/tools/src/index.ts:1876 createExecutionToken() returns Symbol('dsh.tool.execution') — the token travels as data and is used as a Map key (e.g. packages/context/agent-instructions/src/index.ts:93); object identity survives duplication ⇒ safe.

So the audit list is not "every Symbol()" but "every symbol used as a key on a value produced elsewhere". On that reading TOOL_RUNTIME_SCHEDULER is the one that matters, and your patch closes it.

The frame: nothing here is Web-specific

dsh web is an ordinary profile invocation — apps/cli/src/bin.ts:38 calls runProfile and never passes resolutionMode, so apps/cli/src/profile-boot.ts:263 decides:

const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'runtime'

Tools then execute in the dsh web server process (Node), never in the browser; the browser only renders 本轮运行失败 / Cannot read properties of undefined (reading 'prepare'). That is why the same message shows up across the source-launch, Windows-packaged and Web reports — one cause, four entry points.

Worth knowing if you bisect further: the desktop host passes this explicitly and defaults the other way — apps/desktop-host/src/index.ts:21, resolutionMode: process.argv[5] === 'runtime' ? 'runtime' : 'link' — while the CLI/web path defaults to runtime at :263. Two launchers, two defaults, and one of them is the one that produces two evaluations.

Honest boundary

Symbol.for repairs the handshake, not the duplication: after the patch the process still holds two ToolRuntime classes and two sets of module-level state. Any stateful module singleton reached across the same seam stays split — it simply stops throwing and starts being a silently wrong answer instead. That is the argument for also settling which launcher default is correct; the registry fix makes this failure legible and local, it does not make it impossible. (It is also why Symbol.for is worth keeping even if the default is changed later: two evaluations is a legitimate deployment shape, not something to be excluded by configuration.)

Not reachable from a plugin

For anyone considering a plugin-side fix: a plugin can diagnose this from its own vantage — TOOL_RUNTIME_SCHEDULER is a public export, so it can test ctx.tools[TOOL_RUNTIME_SCHEDULER], or compare ctx.tools against the class it resolved itself, and either mismatch proves that more than one evaluation is live in that process (a match proves nothing — the plugin itself sits on one of the two planes) — but it cannot bridge it. The scheduler's prepare / dispatch / finalize / finish are private state of the owning instance, so a plugin holding the other copy's symbol has a key to a lock it cannot open. This one has to be fixed where the key is minted.