argszero/cordis-plugin-tool-deadline-guard

@argszero/cordis-plugin-tool-deadline-guard

一个用于 DeepSeek Harness（dsh）的 cordis 插件，
它为那些未声明截止时间的工具调用设置截止时间——也就是当前 harness 中没有任何机制为其
设置任何东西的那些调用。

input:  user        "keep working on the migration until it is done"
assistant   tool_calls: [subagent(prompt="...") id=call-1]
⋯           nothing in the log, nothing on screen, turn still "running"

一个工具调用恰好在其自身定义如此声明时才有边界。
ToolDefinition.timeoutMs 是可选的（“协作式工具调用超时预算，单位为
毫秒。省略则无截止时间”），而核心执行器
（@deepseek-ai/dsh-tool-call-timeout-policy，由基础 bundle 挂载）以
if (timeoutMs === undefined) return next() 开头。省略该字段，没有任何机制会设置任何东西——没有定时器，没有信号，没有诊断信息。

这种省略是常态而非例外。在 dsh-v0.1.6-alpha.2 中调用 defineTool( 的 40 个非测试源文件中，有 26 个完全不包含 timeoutMs
——25 个随附的工具模块加上测试夹具辅助程序——其中包括
tool-subagent（委派）、mcp-resources（由他人服务器拥有的工具）、tool-terminal、tool-ask-user、fs 读/写/编辑工具，以及
tool-workflow / tool-ralph / tool-todo / plan-mode。其中两个正是长时程运行耗费时间的地方：一个其子任务永不结束的委派，以及一个位于网络边界另一侧的工具。

症状不是错误。而是一个持续渲染为运行中、却没有任何地方能解释它的回合。对比一下模型调用：提供方适配器会宣告停滞（DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000，由 idleWatchdog 按每个数据块重新设置），因此沉默是工具调用卡住的标志，而不是模型调用卡住的标志。已报告为讨论
#7339
（“长时程任务停滞，输出中没有任何内容”），并与
#6226（一个前台 subagent 调用，其子进程已经退出）相邻。

挂载后，同样的调用会以模型可以据此行动的内容结束：

tool_result [error] "tool call to "subagent" timed out: it exceeded the
600000ms deadline supplied by the tool-deadline-guard mount,
and the tool declares no timeoutMs of its own"

安装

npm install @argszero/cordis-plugin-tool-deadline-guard

在 cordis.yml / profile bundle 中，添加该行（或合并本包的
cordis.patch.yml，其中包含相同的这一行）：

- insert:
- id: tool-deadline-guard
name: '@argszero/cordis-plugin-tool-deadline-guard'

在无配置的情况下，它会把每个未声明 timeoutMs 的工具限制在十分钟，并让其他所有调用原样派发。

| field | default | meaning |
|-------|---------|---------|
| mode | auto | auto 会设置截止时间；observe 报告它将会约束什么，并原样派发；off 不注册任何内容 |
| defaultTimeoutMs | 600000 | 未声明预算的工具的预算（10 分钟） |
| perTool | {} | 按解析后的工具名设置每个工具的预算；优先于 defaultTimeoutMs |
| exempt | [] | 此挂载点永不约束的工具名，无论其他配置如何 |
| applyTo | undeclared | undeclared 将声明了 timeoutMs 的工具留给核心策略处理；all 约束所有已知工具 |
| onExpiry | cooperative | 到期时执行的操作；参见诚实的限制 |
| warnLimit | 5 | 每个挂载点发出的诊断信息数量；0 表示静默 |

预算必须是正有限数且 ≤ 2147483647（setTimeout 的饱和点）：更大的值会立即触发，因此“无截止时间”应通过将工具排除在作用域之外来表达——exempt 或 mode: off——而不是通过请求无穷大。

它具体做什么

该插件挂载在文档化的 tools/execute 瀑布流上——与核心策略使用的是同一个公共接缝——并对每次派发执行以下操作：

1. 解析工具自身的定义（ctx.tools.get(exec.name, exec.agent)）并决定是否设置。未知工具是注册表的事（UNKNOWN_TOOL），而且没有定义可供权衡预算。
2. 设置一个定时器和一个控制器，并通过 exec.signal 向工具传递一个融合信号（AbortSignal.any([caller, own])），与核心策略传递其派生截止时间的方式完全一致。
3. 在 finally 中恢复调用方的信号，这样执行后的监听器和后续的每个包装器都不会看到此挂载点的（可能已经中止的）信号——核心策略出于同样原因记录了这一规则。
4. 仅当其自身的定时器触发时才替换结果。 在预算内完成的调用返回工具自身的结果对象，保持不变：不重新派发、不包装、不产生诊断信息。

预算到期会产生循环已经理解的形状——isError: true 且 error.info.code === 'TOOL_DEADLINE_EXCEEDED'——其代码归此插件所有，刻意不使用核心策略的 TOOL_TIMEOUT：这样部署就能区分“工具声明了预算但超支”和“此挂载点提供了工具从未声明的预算”，这正是工具缺陷与部署策略之间的区别。针对 TOOL_TIMEOUT 的 ToolTimeoutError 风格路由对已声明的工具继续有效，并且不会静默捕获这些情况。

诚实的限制

它默认不进行竞速，因此无法释放忽略其信号的工具。 timeoutMs 是一种协作式契约：声明它即断言该工具会将 exec.signal 转发给一个在信号中止时达到静止状态的实现。从不查看其信号的工具无法从这个接缝处被解除阻塞——包装器等待工具的 promise，而一个永远不会
settles 会让包装器（以及这一轮）保持等待。因此在 cooperative 模式下，过期会在调用已经 settle 之后才被转换为结构化错误，这正是维持不变量的方式：已提交的 tool/result 对应的是已经停止的工作，而且绝不会在此之前。在一个忽略其信号、预算为 60 ms 的 fixture 上测量（probe-seam.mjs）：调用在 402 ms 时返回，直到那时包装器才报告。

它无法看到调用为什么 settle。 一个遵守信号的工具会返回 abort artifact；一个忽略信号并仍然完成的工具会返回它自己的迟到结果；两者在这里都表现为“promise 在计时器触发后 resolve 了”。核心策略通过契约来解决这种歧义——工具作者声明了预算，因此工具承诺会停止——而这个插件对一个没有声明任何内容的工具也以同样的方式解决它，这是部署代表该工具做出的承诺。后果直白地说就是：一个顽固工具的迟到成功结果会被 deadline failure 替换。迟到结果很重要的工具必须列在 exempt 中。诊断只声称时序（"x" settled after 402ms, past its 40ms budget; its result was replaced），而从不断言该工具观察到了 abort，因为这个 seam 无法知道这一点。

onExpiry: 'replace' 用更弱的保证换来一个可用的轮次。 包装器会在其计时器触发时立即返回 deadline failure，并让调用继续运行、无人观察。它不会在日志中留下孤立的 tool/call——循环会为它派发的调用记录一个 tool/result，也就是我们的那个（packages/core/agent-loop/src/tool-calls.ts:282），因此 transcript 保持平衡，下一个请求会被接受；被放弃的分支会以一个 no-op settle，这样之后的 rejection 就不会表现为 unhandled rejection。它确实做的是让工具的副作用发生在模型被告知调用失败之后，因此重试的模型可能会重复这些副作用。对于一个永远不会 settle 的工具，这是唯一能够返回的模式。

applyTo: 'all' 适用于没有核心策略的部署。 基础 bundle 会无条件挂载 timeout-policy，因此在 stock profile 上，undeclared 是正确的默认值：两个包装器争抢同一个预算会为同一个调用产生两个相互矛盾的 code。all 是为一种丢弃了该策略的组合而存在的——也适用于工具的声明预算大于部署愿意等待的情况。

验证它

npm test                # tsc, then the wiring suite and the packaging guard
python3 mutations.py    # each claim above, broken one at a time, must go red
node probe-seam.mjs     # the numbers above, against a real registry
node probe-tools.mjs    # what a real ToolRuntime accepts and what a wrapper sees

test/cordis.spec.mjs 挂载了一个真实的 Cordis context、一个真实的 ToolRuntime 和一个真实的 tools/execute waterfall，并带有一个未挂载的 control arm，它
展示该缺陷（在没有插件的情况下，一个声明无预算且永不结算的工具会一直处于待处理状态，且没有任何东西报告它）。mutations.py 编辑的是构建产物——绝不是源代码——并要求测试套件对八种变异中的每一种都失败，因此一个没有任何测试实际支撑的断言无法蒙混过关。test/packaging.spec.mjs 针对实际发布的导入断言清单的两个方向（仅在 devDependencies 中声明的运行时导入会导致使用方出现 ERR_MODULE_NOT_FOUND；声明了却从未被导入的包会无谓地扩大安装闭包）。

兼容性

需要 tools/execute waterfall、ToolDispatchExecution、ToolDefinition.timeoutMs 和 ctx.tools.get(name, agent)，这些均存在于 @deepseek-ai/dsh-tools 中，从 0.1.2-rc.1 到 0.1.6-alpha.2（通过解包每个已发布的 tarball 并读取其 d.ts 和 lib/index.js 进行核对）。@deepseek-ai/cordis ^4.0.2 是 peer；@deepseek-ai/schemastery 是唯一的运行时依赖。

许可证

MIT