[Bug]: tools/pre-execute 等 waterfall 被坏监听器短路后,所有工具返回 Cannot read properties of undefined (reading 'kind')——需要一个消费侧防护与不变式

[yujunqiang123]

问题及现象：

在 web profile 安装 dshmarketplace-plugin@0.1.5 插件后，dsh 调用任何工具都显示 Error: Cannot read properties of undefined (reading 'kind')；此问题只发生在包含 dshmarketplace-plugin 的 web profile;纯 dsh-base + dsh-headless 的 headless profile 不受影响。:

根因

dshmarketplace-plugin@0.1.5(实测 0.1.6 同样存在,逐字节对比确认)注册了一个全局 tools/pre-execute 瀑布监听器(lib/index.js):

t.on('tools/pre-execute', async t => {
  if (t?.tool?.name !== 'dshmarketplace_install') return
  ...
})

1. tools/pre-execute 的 payload 是 ToolExecution,只有 name/arguments/agent/signal 等,没有 .tool 属性，导致 t?.tool?.name !== 'dshmarketplace_install' 对任何调用恒为真，进而，监听器对每个工具都直接 return undefined。
2. 它没有调用 next()。而 waterfall 语义是 "不调 next() 即否决整条链"(vendor/cordis/src/events.ts 内代码注释: "A listener that does not call next() vetoes the rest of the chain, including the built-in behavior")。所以内置的默认 handler({ kind: 'allow' }) 永远轮不到执行，瀑布最终返回 undefined。
3. 工具注册表在 packages/core/tools/src/index.ts 的 prepareExecution 中读取返回值:

const gate = await this.ctx.waterfall(carrier, 'tools/pre-execute', exec, () => Promise.resolve({ kind: 'allow' }))
const askResolution: ToolAskResolution = gate.kind === 'ask'   // gate === undefined → TypeError

3. 抛出的 TypeError 被外层 catch 捕获并变成该工具的错误结果,于是每次调用都返回同样的错误结果。

影响面:一个插件坏,全产品工具失灵

tools/pre-execute 是全产品工具执行的必经点。任何非 scoped、且不调 next() 就返回的监听器，都是对所有 agent 的所有工具的单点故障。这暴露了工具管线对第三方插件监听器的零防御。

建议 DeepSeek Harness 侧做的防护

虽然问题是第三方插件引入的，但也暴露了 tools/pre-execute 的容错性低的问题，因此建议 DeepSeek Harness 做防护性修改：

1. 消费侧校验 — 在 tools 注册表 prepareExecution 中校验瀑布返回值。gate 必须是一个合法 PreToolDecision(allow/deny/ask)；若为 undefined 或形状非法,应当:
   • fail-closed 为 deny，并产出明确的诊断错误(例如 tools/pre-execute chain resolved to no decision: a listener returned without calling next()) 而不是裸 TypeError;
   • 记录注册了该事件的监听器标签(若 Cordis events 能暴露)，把责任归到具体插件;
   • 让模型看到的是 action 化的消息，而不是 reading 'kind'。
     当前行为 把 TypeError 当工具错误结果返回 虽然进程不崩,但对模型不可恢复、且掩盖真实的出错方。
2. 运行时不变式 — 参照现有 invariants 体系(packages/core/tools/src/invariant.ts 与 docs/subsystems/invariants.md)，加一条断言:tools/pre-execute 每次调用都解析为 PreToolDecision。这样同类短路会在不变式诊断中直接显现。
3. 面向插件作者的夹具/示例— 提供一个"用审批门控工具"的正确范本(返回 { kind: 'ask' } / { kind: 'deny' }，或使用 tools.guard()),引导 marketplace 插件不要使用非契约 API 。

[denial123789]

I documented the operator-side failure boundary in the handbook tool execution pipeline guide: when a tools/pre-execute waterfall listener does not call next(), the shared gate can resolve undefined and make every tool fail. The guide includes a minimal-profile A/B and fail-closed diagnosis: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/architecture/tool-execution-pipeline.md\n\nLatest release: https://github.com/sandbaseai/deepseek-harness-handbook/releases/tag/v0.5.263

[denial123789]

Correction: the canonical source link is https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/architecture/tool-execution-pipeline.md . The Pages site does not currently expose a dedicated HTML route for this architecture page.

[denial123789]

Follow-up: v0.5.298 refines the Tool Execution Pipeline guide with the waterfall short-circuit evidence and a fail-closed pre-execute decision contract. It keeps plugin compatibility failures visible instead of flattening them into generic gate.kind errors: https://github.com/sandbaseai/deepseek-harness-handbook/releases/tag/v0.5.298