[Bug] tool-call timeout is notify-only: a tool with a declared timeoutMs can hang the whole session past its budget

[XJPeng12]

Summary. A web_search call left a session hung indefinitely (~5.5 hours, recovered only by restarting the process): the tool has a declared 60s budget, but no tool/result was ever recorded and the agent step never ended, so queued user messages were never processed.

Root cause (DSH-side, confirmed in code). @deepseek-ai/dsh-tool-call-timeout-policy arms the deadline on exec.signal and then await next() — it only substitutes the TOOL_TIMEOUT result after the tool promise settles. If the transport swallows the abort, the promise stays pending forever and the step hangs. The repository already documents exactly this failure mode in packages/util/timeout (idleWatchdog.next):

A transport can leave a read it aborted pending forever (undici drops the error when the abort lands on an in-flight body read), so waiting for the iterator to observe the signal would leave the caller waiting past its own deadline.

idleWatchdog defends itself with Promise.race; the tool-call deadline does not. The package README even records the gap as a known limitation ("the wrapper remains inside await next()"). The undici default headersTimeout/bodyTimeout (300s) does not cover it either: once the abort has landed on an in-flight body read and the half-open connection goes silent, neither data nor a readable error arrives (observed: socket already gone from ss, promise still pending).

Proposed fix (patch attached — applies to master @ 22ddee379): in packages/guard/timeout-policy, race next() against the deadline's own expiry, mirroring idleWatchdog:

• the model receives the structured TOOL_TIMEOUT result at the deadline, without waiting for the tool to settle — the step continues (the model can retry or reroute);
• upstream cancellation semantics are untouched (only a deadline reason arms the expiry lane; the registry's TOOL_ABORTED mapping is preserved);
• the abandoned work promise stays observed, so a late rejection cannot become an unhandled rejection;
• downstream work is still never hard-stopped — it keeps releasing through the signal it already received (the README limitation is reworded to this remaining truth).

Verification. Two new specs — a never-settling tool resolves TOOL_TIMEOUT at the deadline, and an abandoned rejection stays observed — fail by timeout on current master and pass with the patch; all 15 package specs pass; tsc -b packages/guard/timeout-policy clean. Model-visible timeout text is unchanged, so no recorded-session snapshot moves. The synthetic transport hang itself did not reproduce offline (Node 22 + undici 8.11.2, CONNECT-tunnel variants all settled on abort), which is exactly why the harness-side enforcement is the actionable defect: whatever the transport does, a declared budget must bound the call.

Environment. DSH 0.2.1-rc.3 and 0.2.1-rc.4 (checked the published tarballs — both carry the same implementation) and current master; Node v22.20.0, global undici dispatcher via proxy (http_proxy → ProxyAgent); server without direct internet egress.

Follow-ups (happy to split out): explicit hard timeout on the DeepSeek search provider's fetch (currently signal-only); optional step-level watchdog so no single tool can freeze a session regardless of budgets.

[XJPeng12]

fix-timeout-policy-enforce-deadline.patch.txt

[argszero]

Your diagnosis matches what the code does, and the shape of it decides what can be changed from outside the core.

Where it is. packages/guard/timeout-policy/src/index.ts says of itself that it turns its own expiry into TOOL_TIMEOUT "without racing or abandoning the tool promise" (:4), and the substitution happens only after await next() settles. So a declared budget bounds how long the wait for an answer is announced — not how long the step runs. If the promise never settles, the step never ends, and the queued input behind it is never read. Your idleWatchdog comparison is the right one: that code races precisely because a transport can leave a read pending forever, and this one does not.

What can change it today, without touching the core. A plugin can wrap the tool-call waterfall and race the deadline itself. That is what I built for this, and the two knobs that matter are these:

- insert:
    - id: tool-deadline-guard
      name: '@argszero/cordis-plugin-tool-deadline-guard'
      config:
        applyTo: all          # src/index.ts:192 — makes a tool that declares its own budget eligible
        onExpiry: replace     # src/index.ts:193 — the racing branch, at :458
        perTool: { web_search: 60000 }

Two details that are easy to get wrong:

• applyTo defaults to undeclared, which deliberately leaves a tool that declares its own timeoutMs alone — so your web_search would not be bounded at all until you set all.
• Under all the budget it enforces is its own (perTool[name] ?? defaultTimeoutMs, not the declared value), which is why the perTool line is there rather than inherited.

Install. 0.2.1, from git (the registry copy is 0.2.0):

dsh plugin --profile <profile> add "github:argszero/cordis-plugin-tool-deadline-guard#v0.2.1"

Measured today on a clean profile against the 0.2.1-rc.3 runtime: the verb exits 0, the installed copy carries lib/index.js (23,102 B) and lib/types/index.d.ts, dsh --profile <same> --dump-config carries the entry dsh inserted itself, and there are no allowBuilds. Worth mentioning because it was broken until now: lib/ sat in that repository's .gitignore, so an earlier git install exited 0 and shipped a package with no entry point at all. 0.2.1 commits the build output and the packaging suite asserts it.

What this costs, stated rather than buried. Both of these matter before you set all:

• It is the double-wrapper configuration, and the package says so. The base bundle mounts timeout-policy unconditionally; two wrappers racing one budget can produce two contradictory codes for one call, which is exactly why undeclared is the default. You would be picking all because the core policy's cooperative behaviour is the part failing on your transport — that is a defensible trade, but it is a trade.
• The call is not stopped. The replacement returns TOOL_TIMEOUT to the model at the deadline, and the source admits what is left behind: "the call itself is still running unobserved" (:468). Its side effects can land after the model has been told the call failed, so a model that retries may duplicate them.

So this is a mitigation, not your fix. Your patch is the durable one — racing inside timeout-policy fixes it for every deployment, including ones that never install anything, and it does it once instead of once per mount. A plugin can only make the step continue; it cannot make the core stop waiting. If you want to demonstrate the difference while the patch is reviewed, the mount above reproduces your two specs from outside the package.

One thing I could not do: issues and pull requests are disabled on this repository, so a Discussion reply is the only channel available to me — your patch has no path through me, only through a maintainer.

[argszero]

Correction to my comment above, on the line numbers.

The four numbers I quoted (src/index.ts:192 / :193 / :458 / :468) are from the plugin's source — @argszero/cordis-plugin-tool-deadline-guard v0.2.1 — not from the tree's packages/guard/timeout-policy/src/index.ts. That file is 81 lines at f3803c9697 and contains neither applyTo nor onExpiry; the knobs are the plugin's own:

• packages/guard/timeout-policy/src/index.ts:4 — the design quote ("notify-only, never races the call") is the tree's, and still current.
• plugin src/index.ts:192 — applyTo: z.union(['undeclared', 'all']).default('undeclared')
• plugin src/index.ts:193 — onExpiry: z.union(['cooperative', 'replace']).default('cooperative')
• plugin src/index.ts:458 — if (resolved.onExpiry === 'replace')
• plugin src/index.ts:468 — "...was replaced (onExpiry: replace); the call itself is still running unobserved"

So read that comment with the split in mind: the tree enforces an upper bound and nothing more, and every widening I described (applyTo: 'all', onExpiry: 'replace') is something the plugin adds on top of it rather than a switch the tree already exposes.

Install line, unchanged:

dsh plugin add "github:argszero/cordis-plugin-tool-deadline-guard#v0.2.1"

v0.2.1 is the git tag that carries its built lib/; the registry still serves 0.2.0, which is the same code with the same behaviour.

[XJPeng12]

@tianyicui — you raced idleWatchdog for this exact transport-swallows-abort case on the model path in 0.2.2-alpha.2, but packages/guard/timeout-policy still await next()s without racing (last touched Sep 5), leaving the same hole open on the tool path — is racing there acceptable, or would you rather solve it with a step-level watchdog?