bug: 源码启动（pnpm dsh / pnpm dsh web）首次工具调用必崩 — Cannot read properties of undefined (reading 'prepare')

[usniumowang-ctrl]

源码启动的 dsh 每次工具调用都失败：Cannot read properties of undefined (reading 'prepare')

TL;DR (English)

A source launch (pnpm dsh, pnpm dsh web) fails on the first tool call of every turn:

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

One process loads two module copies of @deepseek-ai/dsh-tools — packages/core/tools/src/index.ts and packages/core/tools/lib/index.js. Each copy evaluates its own Symbol('@deepseek-ai/dsh-tools.scheduler'), so the tools service instance and dsh-agent-loop disagree about the scheduler property key. ctx.tools[TOOL_RUNTIME_SCHEDULER] is undefined and .prepare(...) throws. Registering the key (Symbol.for) fixes it locally; the underlying "source plane vs artifact plane" mix that produces the duplicate is untouched.

---

Summary

从源码 checkout 启动 dsh 后，任何调用工具的轮次都会立刻失败，模型看不到工具结果，会话直接结束：

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

失败发生在「本轮第一个 tool call 之后、tool result 之前」，与工具种类无关（bash、grep、skill、ask_user_question 都复现），且完全确定为 100% 复现（源码启动必崩）。用户侧表现为 Web UI 里一条 This turn failed + 上面那行错误。

在本地会话日志（$DSH_HOME/sessions/**/session.v3.jsonl.zstd）中可以观察到同一天有 14 个 session 死于同一条错误，事件序列固定为：

tool/call   seq=27  name=bash
step/end    seq=28
turn/end    seq=29  reason.kind=error, message="Cannot read properties of undefined (reading 'prepare')"

Reproduction

环境：macOS 27.0 (arm64)、Node v26.7.0、pnpm 11.7.0、dsh 0.1.6-alpha.2（master ddefc45fbc）。

git clone https://github.com/deepseek-ai/deepseek-harness.git && cd deepseek-harness
pnpm install
pnpm run build          # 关键：树里存在 lib/ 产物
pnpm dsh headless "Run the bash command 'echo REPRO-OK' and reply with its exact output. Use only the bash tool."

实际结果：

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

对照实验（同一棵树、同一条启动链路的产物平面，正常）：

node apps/cli/lib/bin.js headless "Run the bash command 'echo ARTIFACT-OK' ..."
# → ARTIFACT-OK

pnpm dsh web（Web profile，用户日常用法）产生完全相同的错误。

Root cause

崩溃点是工具调度器的取属性，不是任何 SQLite/db.prepare：

• packages/core/agent-loop/src/tool-calls.ts:170（运行的是产物副本 packages/core/agent-loop/lib/index.js:586）

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

ctx.tools（ToolRuntime 实例）上确实存在一个名为 @deepseek-ai/dsh-tools.scheduler 的 symbol 属性，但不是 agent-loop 导入的那个 symbol —— 两者描述相同、身份不同。插桩输出：

toolsCtor=ToolRuntime toolsIsLib=false toolsIsSrc=false symIsLib=false symIsSrc=true
ownSymbols=Symbol(cordis.tracker)|Symbol(@deepseek-ai/dsh-tools.scheduler)
loopUrl=file:///.../packages/core/agent-loop/lib/index.js

同一个进程里，两份副本都被加载（模块加载标记各打印一次）：

[probe] dsh-tools SRC loaded   ← packages/core/tools/src/index.ts
[probe] dsh-tools LIB loaded   ← packages/core/tools/lib/index.js

原因是一个进程里同一个包同时以源码副本和产物副本存在：

1. profile resolution（runtime 模式）按安装锚点走 node_modules → package.json 的 exports，把插件行解析到 lib/index.js（packages/boot/app-boot/src/profile-resolution/、packages/boot/app-boot/src/profile.ts）。解析钩子实测：@deepseek-ai/dsh-tools 被解析到 file:///.../packages/core/tools/lib/index.js。
2. tsx 的 tsconfig paths 投影（tsconfig.base.json 中 "@deepseek-ai/dsh-tools": ["./packages/core/tools/src"]）把仓库内任何文件的 workspace import 映射到 src/index.ts。因此 packages/core/agent-loop/lib/index.js 拿到的是源码副本的 TOOL_RUNTIME_SCHEDULER，而注册 tools 服务的实例来自产物副本。

这违反了仓库自己的规则 “Source plane vs artifact plane, never mixed”（AGENTS.md）。

补充观察（同一根因的另一面）：把 packages/*/*/lib 全部临时移走后启动源码链路，所有插件行都无法激活（Full diagnostics: $DSH_HOME/logs/startup-...log）。也就是说当前源码启动实际上依赖已构建的 lib/；实测修改 packages/core/agent-loop/src/** 对 pnpm dsh 不生效，改 lib/** 才生效 —— “run one task from source” 目前并不成立。

Expected behavior

pnpm dsh（源码启动）应当在单一平面里加载同一个包的一份实例：要么插件行与 workspace import 都落在 src/，要么都落在 lib/；任何跨包共享的模块级身份（Symbol、WeakMap 标记、instanceof）都不应因平面混用而分裂。

风险面不止这一个 symbol，同类键还有 packages/core/scope/src/index.ts:18 的 kScope（createScope 写、scopeOf/scopeTarget 读，跨包使用）、packages/api/gateway/src/client/remote-events.ts 的 REMOTE_EVENT_NEXT 等；只要两个副本各持一份，就可能出现“写了读不到”的不一致。cordis 自身正是用注册表 symbol 做这类 brand（vendor/cordis/src/context.ts:66 → Symbol.for('cordis.is')），可作为先例。

本地修复与验证（供参考，未提交 PR）

packages/core/tools/src/index.ts：

/**
 * Scheduler entry point omitted from the generated named service API. The key is
 * registered (`Symbol.for`) rather than local: one process can hold both the
 * source and the built copy of this package, and the registry instance must
 * present the same key to the agent loop's scheduler caller in either copy.
 * @internal
 */
export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol.for('@deepseek-ai/dsh-tools.scheduler')

回归测试（packages/core/tools/tests/tools.spec.ts）：

expect(Symbol.keyFor(TOOL_RUNTIME_SCHEDULER)).toBe('@deepseek-ai/dsh-tools.scheduler')

验证：

• 修复 + pnpm run build 后，复现命令正常返回 FIXED-OK（修复前同一命令必崩）。
• npx vitest run packages/core/tools packages/core/agent-loop → 36 files / 844 tests 全绿。
• pnpm run build 退出码 0。

注意这是把症状挡住的最小改动：源码/产物两份副本仍然共存，跨包模块级身份的分裂风险仍在。

Ask

1. 官方期望源码启动落在哪个平面？如果目标是“源码启动跑源码”，那么 profile resolution 在源码启动时需要把 workspace 包解析到 src/；如果目标是“插件一律跑产物”，那么 tsx 的 paths 投影不应再作用于 lib/ 下的文件。
2. 是否应当把这类跨包模块级键统一改为注册表 symbol（Symbol.for）？在 pnpm dsh 这种同进程双副本可出现的运行时里，本地 symbol 天然不安全。
3. 建议补一条真实启动链路的门禁：现有 dsh-source-launch-smoke（apps/cli/tests/source-launch.compat.spec.ts）只断言 TTY 拒绝，没有跑过任何一次带工具调用的 turn，因此这类崩溃不会被 CI 捕获（pnpm test 走 tsconfig paths，全图单一平面，也不会覆盖）。

Environment

• macOS 27.0 (arm64)、Node v26.7.0、pnpm 11.7.0
• dsh 0.1.6-alpha.2，master ddefc45fbc
• 启动方式：pnpm dsh（headless）、pnpm dsh web
• profile：$DSH_HOME/profiles/{web,headless}（默认 runtime resolution mode）
• 树状态：已执行 pnpm run build，packages/*/*/lib 存在

[usniumowang-ctrl]

后续：本地按启动平面修好并验证（macOS 27.0 arm64 / Node v26.7.0 / dsh 0.1.6-alpha.2, master ddefc45fbc）

按 #6967 的方向，把非打包启动的默认 resolution mode 按启动平面区分：

// apps/cli/src/profile-boot.ts
const SOURCE_LAUNCH = import.meta.url.endsWith('.ts')
const defaultResolutionMode: ProfileResolutionMode = SOURCE_LAUNCH ? 'link' : 'runtime'
const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? defaultResolutionMode

隔离验证（保留这处修法、把本贴原先建议的 Symbol.for 硬化临时回退）：

• pnpm dsh headless "…bash…" → 工具执行成功（PLANE-ONLY-OK）。单靠平面修法就够了：源码启动回到单一 src 平面。
• 该 profile 目录出现 .dsh-module-fallback + node_modules 链接，确认走的是 link 路径。
• 产物启动 node apps/cli/lib/bin.js headless "…" 不受影响（import.meta.url 以 .js 结尾 → runtime）。
• pnpm exec tsc -b apps/cli/tsconfig.json 干净；vitest run apps/cli packages/core/tools packages/core/agent-loop → 951 passed / 1 skipped；resolved-profile-boot.spec.ts 的 default 行改为断言 link（该套件从源码加载 launcher）；pnpm run build 通过。

Symbol.for('@deepseek-ai/dsh-tools.scheduler') 仍保留为防御性硬化：它不解决平面分裂，但能让「profile 自带第二份 dsh-tools」这类副本（#6529 / #6416）降级为可用，而不是让整个进程的工具调用全挂。

另：崩溃过的会话确实会被卡死（assistant 消息里的 tool calls 无结果 → 之后每轮 DeepSeek Messages tool calls need immediate results）。这次 macOS/Node 26 环境下的日志与 #6967 描述的形态一致。

[zhang-guo-wen]

已把这批 0.1.6-alpha.2 源码启动故障的共同根因和完整修复方案汇总到 #7011 的这条回复。

本帖属于其中的 tsx src + runtime lib 混载路径。建议上游同时落地四项，而不是只选其中一个 workaround：

1. TypeScript 源码启动默认 link，构建产物/pkg 保持 runtime；
2. TOOL_RUNTIME_SCHEDULER 改用 Symbol.for(...)；
3. profile/plugin 安装后检测同名核心包的多个 realpath/版本；
4. 在写入 tool/call 前取得并验证 scheduler，避免失败后留下无法配对的持久事件。

本地 CLI 聚焦测试 16/16、tools scheduler key 测试和 CLI/tools/agent-loop TypeScript build 已通过。详细补丁、用户恢复步骤、会话处理和回归门禁见上面的集中回复。