[Bug] Saving a tool's image result can hang the session forever: no timeout on the storage step

[yamingmou]

EN / English

Found earlier in our daily usage; re-verified against the current npm line (through 0.1.3-alpha.2) before posting — still present. We publish one topic per report so each can be tracked independently; more findings will follow in the same form.

Authorship note: reproduced and documented by me in real-world usage; root-cause tracing and drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out; I will re-verify against the toolchain and correct.

Summary

When an MCP tool returns images, the harness must decode and durably store them before the result is committed to the session. The tool call itself is bounded (callToolUncached, default 60000 ms), but the storage phase — model-info resolution plus durable image save — has no timeout of its own and only runs under exec.signal. A slow or unreachable model-info route or backing store can therefore hang the turn indefinitely after a successful tool call, with no error, no timeout, and no way for the user to unstick it except killing the session.

Trigger condition

Any image-returning MCP tool whose post-success decode/storage path is slow or unreachable (a stalled proxy, a hung backing store, a slow model-info route). The call returns success; the hang happens in persistence.

Impact scope (production focus)

The MCP bridge is process-wide. One image-returning tool pointed at a slow model-info route or backing store can hold a turn open indefinitely after a successful call — no error, no timeout, no way for the user to unstick it except killing the session. The storage phase is exactly where a hung call is least visible: from the model's perspective the tool already succeeded.

Repro

1. Configure an MCP server whose image-returning tool reaches a slow/unreachable model-info route or backing store (or simulate with a proxy that stalls after the tool result).
2. Call the tool from the harness.
3. Observe: the call returns, but the turn never completes — the storage phase hangs with no timeout.

Environment

• Engine: @deepseek-ai/dsh 0.1.0-rc.6 / 0.1.0-rc.7; re-verified on 0.1.1-rc.2
• Modules: @deepseek-ai/dsh-tool-call-timeout-policy, @deepseek-ai/dsh-mcp-client
• Scenario: any MCP tool returning images with a slow/unreachable model-info route or backing store

---

Detailed evidence chain (source lines) and the root-cause analysis + proposed fix follow in the comments below.

Reported by the OfferKuai Team — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/ | Contact: contact@offerkuai.com

---

中文版 / ZH

此为我们在日常使用中较早发现的问题，发布前已对照 npm 最新线（至 0.1.3-alpha.2）复核，确认仍存在。我们按"一帖一主题"发布以便独立跟踪，后续发现也将以同样形式陆续发出。

协作说明：本文由我在真实使用中复现并记录；根因与成文由 AI 协助完成，我负责校验与发布。我非工程背景，技术表述如有错误，欢迎指出——我会回去用工具链重新验证后更正。

摘要

当 MCP 工具返回图片时，harness 必须先解码并持久化存储，结果才会提交进会话。工具调用本身有界（callToolUncached，默认 60000），但存储阶段——模型信息解析 + 图片持久化——没有自己的超时，只受 exec.signal 约束。因此慢或不可达的模型信息路由/后端存储可以在工具调用成功之后让 turn 无限挂起——无错误、无超时、用户除杀掉会话外无从解脱。

触发条件

任何返回图片的 MCP 工具，其成功后解码/存储路径慢或不可达（停滞的代理、挂起的后端存储、慢的模型信息路由）。调用返回成功；挂起发生在持久化阶段。

影响范围（生产视角）

MCP 桥接是进程级的。一个返回图片的工具指向慢的模型信息路由或后端存储，就能在成功调用后无限挂起一个 turn——无错误、无超时、用户除杀掉会话外无从解脱。存储阶段正是挂起最不可见的位置：从模型视角看工具已经成功了。

复现步骤

1. 配置一个返回图片的 MCP 工具，其模型信息路由/后端存储慢或不可达（或用代理在工具结果后停滞模拟）。
2. 从 harness 调用该工具。
3. 观察：调用返回，但 turn 永不完成——存储阶段无超时地挂起。

环境

• 引擎：@deepseek-ai/dsh 0.1.0-rc.6 / 0.1.0-rc.7；已在 0.1.1-rc.2 复核
• 模块：@deepseek-ai/dsh-tool-call-timeout-policy、@deepseek-ai/dsh-mcp-client
• 场景：任何返回图片、且模型信息路由或后端存储慢/不可达的 MCP 工具

---

完整证据链（源码行号）、根因分析与建议修复见下方跟帖。

本报告由 OfferKuai（Offer快）团队提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/ | 联系：contact@offerkuai.com

---

[yamingmou]

EN / English

Evidence (source)

• dsh-mcp-client/lib/index.js:326 — llm.resolveModelInfo(provider, model, exec.signal) (no timeout).
• dsh-mcp-client/lib/index.js:371 — attachments.saveImages(decoded) carries only exec.signal, never a timeout.
• dsh-mcp-client/lib/index.js:102 — the raw call is bounded by DEFAULT_TOOL_CALL_TIMEOUT_MS = 60000 (transport-level default), so the storage phase is the un-deadlined gap, not the call itself.
• dsh-tool-call-timeout-policy/lib/index.js:123-124 — if (timeoutMs === void 0) return next(); (no harness ceiling when unset; re-verified at :124 on 0.1.1-rc.2).

Version note (2026-09-08): re-verified against @0.1.2-rc.1 and 0.1.3-alpha.2 (npm alpha line, 9/7) — dsh-tool-call-timeout-policy still covers only the tool-call execution phase; the image storage phase (resolveModelInfo + saveImages) still carries no deadline. The alpha.2 tarball differs from rc.1 only in a comment path (implemented → archived), so this stays open on the npm line through 0.1.3-alpha.2.

Authorship note: reproduced and documented by me in real-world usage; root-cause tracing and drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out; I will re-verify against the toolchain and correct.

Reported by the OfferKuai Team — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/ | Contact: contact@offerkuai.com

---

中文版 / ZH

证据（源码）

• dsh-mcp-client/lib/index.js:326 —— llm.resolveModelInfo(provider, model, exec.signal)（无超时）。
• dsh-mcp-client/lib/index.js:371 —— attachments.saveImages(decoded) 只带 exec.signal，从不带 timeout。
• dsh-mcp-client/lib/index.js:102 —— 原始调用受 DEFAULT_TOOL_CALL_TIMEOUT_MS = 60000（传输层默认）约束，因此无截止的是存储阶段，而非调用本身。
• dsh-tool-call-timeout-policy/lib/index.js:123-124 —— if (timeoutMs === void 0) return next();（未设时无任何 harness 上限；0.1.1-rc.2 上复核位于 :124）。

版本注（2026-09-08）： 已对照 @0.1.2-rc.1 与 0.1.3-alpha.2（npm alpha 线，9/7 更新）复核——dsh-tool-call-timeout-policy 仍只覆盖 tool-call 执行阶段；图片存储阶段（resolveModelInfo + saveImages）仍无截止。alpha.2 与 rc.1 仅注释路径差异（implemented→archived），npm 线截至 0.1.3-alpha.2 仍开。

协作说明：本文由我在真实使用中复现并记录；根因与成文由 AI 协助完成，我负责校验与发布。我非工程背景，技术表述如有错误，欢迎指出——我会回去用工具链重新验证后更正。

本报告由 OfferKuai（Offer快）团队提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/ | 联系：contact@offerkuai.com

---

[yamingmou]

EN / English

Analysis (root cause)

Two gaps, at different severities:

Gap 1 (severe, unambiguous) — post-success image storage is a separate, un-deadlined phase.

The tool call itself is bounded by the bridge-level opts.toolCallTimeoutMs (callToolUncached, dsh-mcp-client/lib/index.js:102, default 60000). But decoding + durably storing returned images (dsh-mcp-client/lib/index.js:311-372) is a separate phase that runs only under exec.signal: llm.resolveModelInfo(provider, model, exec.signal) at :326 and attachments.saveImages(decoded) at :371 — neither carries a timeout. So a successful image result can still hang indefinitely in storage. This phase must also be deadline-bounded.

Gap 2 (real but weaker) — "no timeoutMs" means "no additional harness ceiling".

dsh-tool-call-timeout-policy/lib/index.js:123-124:

const timeoutMs = ctx.tools.get(exec.name, exec.agent)?.timeoutMs;
if (timeoutMs === void 0) return next();

The cooperative enforcer treats an absent timeoutMs as no extra ceiling: it returns next() with no deadline(...). createDefinition (dsh-mcp-client/lib/index.js:197) never sets timeoutMs, so all MCP tools fall into this gap — but the raw call still has the 60 s transport default, so Gap 2 is "no additional harness ceiling," not "fully unbounded call."

Proposed fix (minimal, architecture-consistent)

1. Deadline the image storage phase (Gap 1 — the priority). Wrap the decode + llm.resolveModelInfo + attachments.saveImages sequence in the same deadline(exec.signal, N, …) primitive the timeout policy already uses (dsh-tool-call-timeout-policy/lib/index.js:125). Storage then fails like any other tool step when the store/model route is slow. deadline is already imported from @deepseek-ai/dsh-timeout at dsh-tool-call-timeout-policy/lib/index.js:1.
2. Global default tool deadline (Gap 2). In dsh-tool-call-timeout-policy, when timeoutMs === void 0, apply a configured default (e.g. process.env.DSH_TOOL_TIMEOUT_MS or a plugin option) instead of unconditionally return next(). Per-tool timeoutMs still overrides.
3. Expose the storage timeout as a configurable bridge option, a sibling to the existing toolCallTimeoutMs so operators can tune it per server.

All three reuse primitives already present in the codebase, so the new surface is small and consistent.

Questions for the maintainers

1. For Gap 1, is wrapping the storage phase in the existing deadline() primitive the acceptable shape? Should the storage deadline reuse toolCallTimeoutMs or be a separate configurable?
2. For Gap 2, is a global default ceiling (env-var / plugin option) preferred, or should timeoutMs stay strictly opt-in?
3. Would you accept a PR implementing the storage-phase deadline (Gap 1) and the default ceiling (Gap 2), both behind existing option style?

Authorship note: reproduced and documented by me in real-world usage; root-cause tracing and drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out; I will re-verify against the toolchain and correct.

Reported by the OfferKuai Team — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/ | Contact: contact@offerkuai.com

---

中文版 / ZH

根因分析（含源码引用）

两个缺口，严重度不同：

缺口 1（严重、无歧义）—— 成功之后的图片存储是独立、无截止时间的阶段。

工具调用本身受桥接层 opts.toolCallTimeoutMs 约束（callToolUncached，dsh-mcp-client/lib/index.js:102，默认 60000）。但解码 + 持久化返回图片（dsh-mcp-client/lib/index.js:311-372）是独立阶段，只在 exec.signal 下运行：llm.resolveModelInfo(provider, model, exec.signal) 在 :326、attachments.saveImages(decoded) 在 :371 —— 两者都不带 timeout。所以即便图片结果已"成功"，存储阶段仍可能无限挂起。这一阶段也必须受截止时间约束。

缺口 2（真实但较弱）—— "没有 timeoutMs" 等于 "没有额外的 harness 上限"。

dsh-tool-call-timeout-policy/lib/index.js:123-124：

const timeoutMs = ctx.tools.get(exec.name, exec.agent)?.timeoutMs;
if (timeoutMs === void 0) return next();

协作式执行器把缺失的 timeoutMs 当作没有额外上限：直接 return next()，不套任何 deadline(...)。createDefinition（dsh-mcp-client/lib/index.js:197）从不设置 timeoutMs，因此所有 MCP 工具都落入这个缺口——但原始调用仍有 60s 传输默认，所以缺口 2 是"无额外 harness 上限"，而非"调用完全无界"。

建议修复（最小、符合既有架构）

1. 给图片存储阶段加截止时间（缺口 1 —— 优先）。 把"解码 + llm.resolveModelInfo + attachments.saveImages"这段用超时策略已使用的同一 deadline(exec.signal, N, …) 原语（dsh-tool-call-timeout-policy/lib/index.js:125）包裹。存储变慢时就会像其他工具步骤一样失败。deadline 已在 dsh-tool-call-timeout-policy/lib/index.js:1 从 @deepseek-ai/dsh-timeout 导入。
2. 全局默认工具截止时间（缺口 2）。 在 dsh-tool-call-timeout-policy 中，当 timeoutMs === void 0 时，应用一个可配置的默认值（如 process.env.DSH_TOOL_TIMEOUT_MS 或插件选项），而非无条件 return next()。每工具的 timeoutMs 仍可覆盖。
3. 把存储超时作为可配置桥接选项暴露出来，作为既有 toolCallTimeoutMs 的兄弟项，让运维可按 server 调优。

三者都在复用代码库既有原语，因此新增面很小且一致。

想问维护者的问题

1. 对缺口 1，用既有 deadline() 原语包裹存储阶段是否可接受？存储截止时间应复用 toolCallTimeoutMs，还是作为独立可配置项？
2. 对缺口 2，全局默认上限（环境变量 / 插件选项）是否更合适，还是 timeoutMs 应严格保持"显式 opt-in"？
3. 是否愿意接受一个实现"存储阶段截止时间（缺口 1）+ 默认上限（缺口 2）"（均沿用现有选项风格）的 PR？

协作说明：本文由我在真实使用中复现并记录；根因与成文由 AI 协助完成，我负责校验与发布。我非工程背景，技术表述如有错误，欢迎指出——我会回去用工具链重新验证后更正。

本报告由 OfferKuai（Offer快）团队提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/ | 联系：contact@offerkuai.com

---