Tool dispatch fails with cryptic "Cannot read properties of undefined (reading 'prepare')" when tool runtime becomes unavailable - turn dies until restart

[LiuJunheng]

Note: This report was prepared and posted on behalf of a community user by an AI assistant, at the user's request. It is based on the user's real local DSH portable installation (v0.1.0-rc.6, Windows) — the diagnosis comes from actual session logs and source inspection.

Summary

When the agent tool runtime becomes unavailable, every tool call in a turn fails with the cryptic TypeError Cannot read properties of undefined (reading 'prepare'), the turn dies with reason: { kind: "error" }, and nothing recovers until the DSH service is restarted. Session-level recovery (fork / rewind / new conversation) does not help.

Environment

• @deepseek-ai/dsh 0.1.0-rc.6 (portable install), Node v22.20.0, Windows
• Third-party plugins (dsh-find-plugin, dsh-web-plugin-manager) were installed at the time and removed later

Symptom (from the session log)

A failing turn looks like (no tool/result is ever recorded):

tool/call  run_code
step/end
turn/end  reason: { kind: "error", error: { message: "Cannot read properties of undefined (reading 'prepare')", code: "UNKNOWN" } }

Every subsequent turn that calls any tool fails the same way until the server process is restarted.

Root-cause analysis

The failure happens at packages/core/agent-loop/src/tool-calls.ts:169:

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

Importantly, ctx.tools.executionMode(...) (line 88) succeeded earlier in the same dispatch — so ctx.tools itself existed, but ctx.tools[TOOL_RUNTIME_SCHEDULER] was undefined. TOOL_RUNTIME_SCHEDULER is a module-local Symbol("@deepseek-ai/dsh-tools.scheduler"). Two plausible causes:

1. Duplicate module instance. If a second copy of @deepseek-ai/dsh-tools is loaded (e.g., pulled in by a profile plugin's dependency tree), the symbol constant differs between the two module instances, so ctx.tools[<runtime copy's symbol>] is undefined while string-keyed methods like executionMode still resolve. (In our environment the profile indeed had its own @deepseek-ai/dsh-tools copy.)
2. Runtime plugin-tree change. cordis supports in-process plugin updates (cordis-plugin-loader's internal/update); installing / uninstalling / toggling plugins at runtime disposes and rebuilds plugin fibers, and already-running agents can resolve a torn-down or mid-rebuild tools service.

Proposed fix (minimal, purely diagnostic)

Add an availability guard at the start of executeToolCalls in packages/core/agent-loop/src/tool-calls.ts (right after const { session } = agent):

// Guard: surface a clear diagnostic instead of the cryptic
// "Cannot read properties of undefined (reading 'prepare')".
const toolsMissing = ctx.tools === undefined
const schedulerMissing = !toolsMissing && ctx.tools[TOOL_RUNTIME_SCHEDULER] === undefined
if (toolsMissing || schedulerMissing) {
  throw new Error(
    '[dsh-agent-loop] tool runtime unavailable: ' +
    (toolsMissing
      ? 'the tools service is not mounted on ctx'
      : 'TOOL_RUNTIME_SCHEDULER is missing on ctx.tools (likely a duplicate @deepseek-ai/dsh-tools module instance or an in-flight plugin-tree change)') +
    '. Restart the service to rebuild the plugin tree.',
  )
}

Benefits:

• Turns fail with a clear, actionable message instead of a TypeError that looks like an unrelated bug.
• The guard fires before appendToolCall, so a failed dispatch no longer leaves a dangling tool/call event in the session log.

Related observation: the turn/end error code is hard-coded to "UNKNOWN" in the agent-loop's turn-error normalization (near the turn/end append in packages/core/agent-loop/src/index.ts). Making this class of failure carry a stable code (e.g. TOOLS_UNAVAILABLE) would let clients detect and explain it programmatically.

Impact / suggestion

• The guard is diagnostic only; the underlying remedies are: avoid mutating the plugin tree while agents are running, and avoid duplicate @deepseek-ai/dsh-tools instances in profile dependency trees.
• Happy to provide a full patch / tests if the team wants it (noting CONTRIBUTING.md says external PRs are not accepted at the moment — this is posted as a bug report + proposal).

---

中文版 (Chinese version)

说明:本报告由 AI 助手应社区用户要求代为撰写与发布,基于用户在本地 DSH 便携安装(0.1.0-rc.6, Windows)中遇到的真实情况,诊断来自实际会话日志与源码检查。

概述

当 agent 的工具运行时失效时,回合中的每一次工具调用都会报晦涩的 Cannot read properties of undefined (reading 'prepare'),回合以 reason: { kind: "error" } 结束,且只能通过重启 DSH 服务恢复。会话级手段(派生/回退/新建对话)均无效。

环境

• @deepseek-ai/dsh 0.1.0-rc.6(便携安装)、Node v22.20.0、Windows
• 当时装有第三方插件 dsh-find-plugin、dsh-web-plugin-manager(后来已移除)

现象(来自会话日志)

失败回合形如(始终没有 tool/result):

tool/call  run_code
step/end
turn/end  reason: { kind: "error", error: { message: "Cannot read properties of undefined (reading 'prepare')", code: "UNKNOWN" } }

此后该服务实例中每个调用工具的回合都以同样方式失败,直到重启进程。

根因分析

报错发生在 packages/core/agent-loop/src/tool-calls.ts:169:

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

关键在于:同一派发流程里前面的 ctx.tools.executionMode(...)(第 88 行)是成功的——说明 ctx.tools 本身存在,但 ctx.tools[TOOL_RUNTIME_SCHEDULER] 是 undefined。TOOL_RUNTIME_SCHEDULER 是模块级 Symbol("@deepseek-ai/dsh-tools.scheduler")。两个合理成因:

1. 模块重复加载:如果进程里加载了第二份 @deepseek-ai/dsh-tools(例如被某个 profile 插件的依赖树带进来),两份模块实例的 Symbol 常量不同,ctx.tools[运行时副本的Symbol] 就是 undefined,而字符串键方法(如 executionMode)仍可解析。(我们的环境里 profile 确实存在第二份 @deepseek-ai/dsh-tools。)
2. 运行中插件树变更:cordis 支持进程内插件更新(cordis-plugin-loader 的 internal/update);运行中安装/卸载/开关插件会 dispose 并重建插件 fiber,正在运行的 agent 可能解析到被拆除或重建中的 tools 服务。

建议修复(最小、纯诊断)

在 packages/core/agent-loop/src/tool-calls.ts 的 executeToolCalls 开头(const { session } = agent 之后)加可用性守卫:

// Guard: surface a clear diagnostic instead of the cryptic
// "Cannot read properties of undefined (reading 'prepare')".
const toolsMissing = ctx.tools === undefined
const schedulerMissing = !toolsMissing && ctx.tools[TOOL_RUNTIME_SCHEDULER] === undefined
if (toolsMissing || schedulerMissing) {
  throw new Error(
    '[dsh-agent-loop] tool runtime unavailable: ' +
    (toolsMissing
      ? 'the tools service is not mounted on ctx'
      : 'TOOL_RUNTIME_SCHEDULER is missing on ctx.tools (likely a duplicate @deepseek-ai/dsh-tools module instance or an in-flight plugin-tree change)') +
    '. Restart the service to rebuild the plugin tree.',
  )
}

收益:

• 失败回合给出清晰、可操作的信息,而不是看似无关的 TypeError。
• 守卫在 appendToolCall 之前触发,失败派发不再在会话日志里留下悬空的 tool/call 事件。

顺带发现:回合错误码被硬编码为 "UNKNOWN"(agent-loop 的 turn/end 错误归一化处,位于 packages/core/agent-loop/src/index.ts)。若此类失败能携带稳定错误码(如 TOOLS_UNAVAILABLE),客户端就能程序化识别并解释它。

影响 / 建议

• 守卫只是诊断性的;根本性对策是:不要在 agent 运行时改动插件树,并避免 profile 依赖树里出现重复的 @deepseek-ai/dsh-tools。
• 如需完整补丁/测试可提供(注:CONTRIBUTING.md 说明目前暂不接受外部 PR,本帖以 bug 报告+方案形式提交)。

---

Reference implementation (open-sourced)

A community reference implementation of the session-recovery workflow is now open-sourced:

https://github.com/LiuJunheng/DeepSeekHarnessGreen → plugins/dsh-session-rewind

It includes:

• A WebUI plugin that lists sessions, analyzes them turn-by-turn (user prompt / step count / tool-call errors / completion status), and recovers poisoned conversations by forking at any completed turn (based on the official session.fork + sessions.open). Since the orphan tool_calls only lives inside the crashed turn, forking from the previous completed-turn boundary cleanly drops the poisoned tail while keeping all earlier history — a more convenient alternative to "start a new session" when you want to keep the conversation.
• tools/rewind-session.mjs — an offline rewind script (truncates a session log back to the last completed turn, with automatic backup) for maintenance windows.
• tools/apply-agentloop-guard.mjs — the diagnostic guard patch described above, as an idempotent re-appliable script.

Built for DSH 0.1.0-rc.6; depends on @deepseek-ai/dsh-session@0.1.0-rc.6 (auto-installed into the profile). MIT licensed.