feat(timeout): add tools/execute seam + tool-timeout policy plugin

Model-facing tool-call budgets were tangled into each capability's schema
(bash timeoutMs, web_fetch timeout_ms) with no shared home. Add a
tools/execute around-dispatch waterfall to dsh-tools whose base next() is
the dispatch-with-normalization thunk, and a new @deepseek-ai/dsh-timeout-policy
plugin (packages/timeout/) that arms a per-tool deadline on exec.signal and
returns a structured TOOL_TIMEOUT when it wins. Migrate web_fetch (drop the
model-facing timeout_ms) and web_search onto it; the fetch provider keeps its
timeout only as a resource backstop for direct callers. bash and hook command
execution keep BASH_TIMEOUT unchanged.

Named the plugin timeout-policy (not the RFC's tool-timeout) so it does not
trip the gen-tool-catalog packages/*/tool-* completeness guard, and replace
exec.signal by in-place mutation before next() since cordis waterfall next()
ignores passed arguments. RFC moved to implemented/ recording both deviations.
This commit is contained in:
Dudu-0223
2026-07-08 10:06:07 +08:00
parent 6beed9a883
commit 8190016e2b
32 changed files with 1004 additions and 84 deletions

View File

@@ -0,0 +1,46 @@
# dsh-timeout-policy
Tool-call timeout policy: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for each configured tool and returns a structured `TOOL_TIMEOUT` result when that deadline wins. It is the reference `tools/execute` wrapper and the deployment-owned home for model-facing tool-call budgets (the timeout-library RFC's foreseen middleware).
## Plugin (namespace: `timeout-policy`)
A function/namespace plugin (`name` / `Config` / `apply`), not a service. It registers no tool and injects nothing — it consumes `ctx.tools`'s `tools/execute` waterfall, which the `dsh-tools` registry always provides.
### Config
Per-tool policy, keyed by the model-facing tool name. There is deliberately **no global default** (a global budget would silently start failing any tool that runs long once the plugin loads) and **no model-facing override** (timeout is deployment policy, not prompt semantics) in this version.
```yaml
- id: timeout-policy
name: '@deepseek-ai/dsh-timeout-policy'
config:
tools:
web_fetch:
timeoutMs: 30000
web_search:
timeoutMs: 30000
```
| Key | Type | Meaning |
|---|---|---|
| `tools` | `Record<string, { timeoutMs }>` | Per-tool timeout policy; an unlisted tool gets no deadline. `timeoutMs` is required per configured tool and must be positive finite. |
### Behavior
For a **configured** tool the listener:
1. Arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')` — one signal fusing the caller's abort with this plugin's timer (`@deepseek-ai/dsh-timeout`).
2. Swaps that derived signal onto `exec` for the downstream dispatch, then restores the caller's own signal afterward (cordis `next()` ignores passed arguments, so the wrapper mutates the shared `exec` in place; restoring keeps `tools/post-execute` seeing the caller's signal).
3. After dispatch, if `timeoutOf(d.signal, 'TOOL_TIMEOUT')` matches — this plugin's own timer fired — replaces the result with a structured `TOOL_TIMEOUT` tool result: `{ isError: true, error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }, content: 'Error: tool call timed out after <ms>ms' }`.
An **unconfigured** tool delegates untouched (no deadline).
The base `next()` of `tools/execute` is the registry's dispatch-with-normalization thunk, so when the timeout signal reaches a provider that throws its own upstream-abort error, dispatch first turns it into a normal error result, and this wrapper then replaces that with `TOOL_TIMEOUT`. That ordering is why the replacement is keyed off the signal (`timeoutOf`), not off the dispatched result's shape.
### Cooperative, not a hard kill
The derived signal only **notifies**; termination stays with the tool and the capability it forwards `exec.signal` to (the `dsh-timeout` library owns no kill). **"Configured" therefore means "cooperative with `exec.signal`"**: a tool that ignores the signal will not stop on timeout. A deployment must only configure tools that forward the signal to their implementation — the shipped `web_fetch`/`web_search` (which forward through `ctx.web` to providers) are the reference. `TOOL_TIMEOUT` needs no session event for reconstructability: it is the final model-facing `tool/result`, already logged by the loop.
### Composing with other `tools/execute` wrappers
Multiple `tools/execute` listeners compose by cordis registration order. Combined with a future retry/sandbox/metrics wrapper, registration order chooses the semantics — "timeout covers the whole retry operation" (timeout registered outer) versus "timeout covers each attempt" (timeout registered inner).

View File

@@ -0,0 +1,39 @@
{
"name": "@deepseek-ai/dsh-timeout-policy",
"description": "Tool-call timeout policy: a tools/execute wrapper that arms a per-tool deadline on exec.signal and returns TOOL_TIMEOUT when it wins",
"version": "0.0.1",
"private": true,
"type": "module",
"main": "lib/index.js",
"types": "lib/types/index.d.ts",
"exports": {
".": {
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-timeout": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
"cordis": "^4.0.0-rc.6"
},
"dependencies": {
"schemastery": "^3.18.0"
},
"devDependencies": {
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-timeout": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
"cordis": "^4.0.0-rc.6"
}
}

View File

@@ -0,0 +1,137 @@
/**
* `@deepseek-ai/dsh-timeout-policy`: the tool-call timeout policy plugin. It
* registers ONE `tools/execute` around-dispatch listener that, for each
* configured tool, arms a per-call deadline on `exec.signal` and returns a
* structured `TOOL_TIMEOUT` result when that deadline wins.
*
* This is a COOPERATIVE deadline, not a hard kill: the derived signal only
* NOTIFIES. A configured tool (and the capability it forwards `exec.signal` to)
* must honor that signal and reach quiescence — the plugin never races the tool
* promise or terminates work itself (see the timeout-library RFC's rejection of
* `Promise.race`). "Configured" therefore MEANS "cooperative with `exec.signal`":
* a tool that ignores the signal will not stop on timeout, so a deployment must
* only list tools that forward it (the shipped web tools are the reference).
*
* Ownership of the `TOOL_TIMEOUT` code is entirely here: it is both the internal
* {@link deadline} code (so {@link timeoutOf} scopes the classification to THIS
* plugin's own timer, reading a foreign/nested outer deadline as an ordinary
* cancel) and the structured `{ name, code }` on the replacement tool result.
* No new session event is needed for reconstructability: the `TOOL_TIMEOUT`
* result IS the final model-facing `tool/result`, already logged by the loop.
*
* Why a `tools/execute` around seam and not a `pre`/`post` pair: the deadline
* needs ONE lexical scope — arm on `exec.signal`, delegate to dispatch, classify
* the result, dispose the timer — which the around seam gives directly. A
* pre/post split would spread one deadline's lifetime across two independent
* waterfalls (a call-id map, cleanup on every deny/throw/dispose path).
*
* @module @deepseek-ai/dsh-timeout-policy
*/
import type { Context } from 'cordis'
import z from 'schemastery'
import type { CallId } from '@deepseek-ai/dsh-llm'
import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools'
/**
* The code owned by this plugin, used BOTH as the internal {@link deadline}
* classification code AND as the structured error `code` on the replacement
* tool result. Scoping {@link timeoutOf} to it keeps a nested outer deadline
* (another `tools/execute` wrapper's timer that fired first) from being misread
* as this plugin's own timeout — it reads as an ordinary upstream cancel.
*/
export const TOOL_TIMEOUT = 'TOOL_TIMEOUT'
/** Cordis plugin name used by loader diagnostics. */
export const name = 'timeout-policy'
/** Per-tool timeout policy. `timeoutMs` is required and must be positive finite. */
export interface ToolTimeoutPolicy {
/** The per-call cooperative deadline for this tool, in milliseconds. */
timeoutMs: number
}
/**
* Plugin config: per-tool timeout policy, keyed by the model-facing tool name.
* There is deliberately NO global default (a global budget would silently start
* failing any tool that happens to run long once the plugin loads) and NO model
* override (timeout is deployment policy, not prompt semantics) in this version.
*/
export interface Config {
/** Timeout policy per tool name; an unlisted tool gets no deadline from this plugin. */
tools?: Record<string, ToolTimeoutPolicy>
}
export const Config: z<Config> = z.object({
tools: z.dict(z.object({ timeoutMs: z.number() })).default({}),
})
/** The shape after schemastery fills `tools` with its `{}` default. */
type ResolvedConfig = Required<Config>
/** A per-tool timeout must be a positive finite number (0 is not a "disable" value). */
function assertPositiveFinite(toolName: string, value: number): void {
if (!Number.isFinite(value) || value <= 0) {
throw new Error(`timeout-policy: tools.${toolName}.timeoutMs must be a positive finite number`)
}
}
/**
* The structured result substituted when this plugin's deadline wins. `content`
* is the model-facing message; `error.code` is the same {@link TOOL_TIMEOUT}
* this plugin owns, so a retry/sandbox plugin (and replay) can route on it.
*/
export function toolTimeoutResult(callId: CallId, timeoutMs: number): ToolExecutionResult {
return {
callId,
content: [{ type: 'text', text: `Error: tool call timed out after ${timeoutMs}ms` }],
isError: true,
error: { name: 'ToolTimeoutError', code: TOOL_TIMEOUT },
}
}
/**
* Register the tool-call timeout policy. For a configured tool the listener arms
* a {@link deadline} on the caller's `exec.signal`, swaps it onto `exec` for the
* downstream dispatch (cordis `next()` ignores passed arguments, so a wrapper
* mutates the shared `exec` in place), restores the original signal afterward so
* `tools/post-execute` sees the caller's own signal, and replaces the result
* with {@link toolTimeoutResult} when its own timer fired. An unconfigured tool
* delegates untouched.
*/
export function apply(ctx: Context, config: Config): void {
// schemastery (Config) has already filled `tools` with its {} default.
const resolved = config as ResolvedConfig
for (const [toolName, policy] of Object.entries(resolved.tools)) {
assertPositiveFinite(toolName, policy.timeoutMs)
}
ctx.on('tools/execute', async (exec, next): Promise<ToolExecutionResult> => {
const timeoutMs = resolved.tools[exec.name]?.timeoutMs
// Unconfigured tool: no deadline, delegate unchanged.
if (timeoutMs === undefined) return next()
using d = deadline(exec.signal, timeoutMs, TOOL_TIMEOUT)
// Swap the derived deadline onto exec for dispatch, then restore the
// caller's own signal so post-execute listeners never see this plugin's
// (possibly already-aborted) timeout signal. `undefined` is not assignable to
// the optional `signal` under exactOptionalPropertyTypes, so branch on it.
const upstream = exec.signal
exec.signal = d.signal
try {
const result = await next()
// If OUR timer fired (scoped by code — a nested outer deadline reads as
// undefined here), the tool/capability saw the abort and reached
// quiescence; replace whatever it returned (its own abort result) with the
// structured TOOL_TIMEOUT the model sees.
if (timeoutOf(d.signal, TOOL_TIMEOUT) !== undefined) {
return toolTimeoutResult(exec.callId, timeoutMs)
}
return result
} finally {
if (upstream === undefined) delete exec.signal
else exec.signal = upstream
}
})
}

View File

@@ -0,0 +1,241 @@
/**
* Unit + real-load-path coverage for @deepseek-ai/dsh-timeout-policy. The
* timeout-wins cases drive the deadline under fake timers (deterministic — no
* wall-clock race) and use a COOPERATIVE tool that settles only when its
* `exec.signal` aborts, mirroring how a real capability forwards the signal and
* reaches quiescence.
*/
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { Context } from 'cordis'
import Loader from '@cordisjs/plugin-loader'
import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry, { defineTool, type ToolExecution, type ToolExecutionResult, type PostToolDecision } from '@deepseek-ai/dsh-tools'
import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
import { TOOL_TIMEOUT, toolTimeoutResult } from '@deepseek-ai/dsh-timeout-policy'
/** Mount the registry + the timeout-policy plugin with the given per-tool config. */
async function setup(tools: Record<string, { timeoutMs: number }> = {}) {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(timeoutPolicy, { tools })
return ctx
}
/** A fast tool: returns immediately, ignoring the signal. */
const fastTool = defineTool({
name: 'fast',
description: 'returns at once',
parameters: {},
async execute() { return [{ type: 'text' as const, text: 'ok' }] },
})
/** A cooperative tool that settles ONLY when its exec.signal aborts (returns text). */
const cooperativeTool = defineTool({
name: 'slow',
description: 'stops when aborted',
parameters: {},
execute(_args, exec): Promise<{ type: 'text'; text: string }[]> {
const done = [{ type: 'text' as const, text: 'stopped cooperatively' }]
if (exec.signal?.aborted) return Promise.resolve(done)
return new Promise((resolve) => {
exec.signal?.addEventListener('abort', () => { resolve(done) })
})
},
})
/** A cooperative tool that THROWS its own upstream-abort error when aborted (web-provider shape). */
const abortThrowingTool = defineTool({
name: 'aborter',
description: 'throws WEB_ABORTED when aborted',
parameters: {},
execute(_args, exec): Promise<never> {
if (exec.signal?.aborted) return Promise.reject(new HarnessError('web fetch aborted', 'WEB_ABORTED'))
return new Promise((_resolve, reject) => {
exec.signal?.addEventListener('abort', () => { reject(new HarnessError('web fetch aborted', 'WEB_ABORTED')) })
})
},
})
describe('timeout-policy config validation', () => {
it('rejects a non-positive timeout at apply', async () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await expect(ctx.plugin(timeoutPolicy, { tools: { web_fetch: { timeoutMs: 0 } } }))
.rejects.toThrow('tools.web_fetch.timeoutMs must be a positive finite number')
})
it('rejects a non-finite timeout at apply', async () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await expect(ctx.plugin(timeoutPolicy, { tools: { web_fetch: { timeoutMs: Infinity } } }))
.rejects.toThrow('must be a positive finite number')
})
it('mounts with no config (empty tools default) and delegates every call', async () => {
const ctx = await setup()
ctx.tools.register(fastTool)
const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} })
expect(result).toEqual({ callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false })
})
})
describe('timeout-policy delegation (unconfigured / fast)', () => {
it('delegates an UNCONFIGURED tool unchanged and does not touch exec.signal', async () => {
const ctx = await setup({ other: { timeoutMs: 50 } })
let seenSignal: AbortSignal | undefined
ctx.tools.register({ ...fastTool, name: 'probe', async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } })
const upstream = new AbortController().signal
const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream })
expect(result.isError).toBe(false)
expect(seenSignal).toBe(upstream) // no deadline derived for an unconfigured tool
})
it('a configured tool that returns fast keeps its own result (no timeout)', async () => {
const ctx = await setup({ fast: { timeoutMs: 10_000 } })
ctx.tools.register(fastTool)
const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} })
expect(result).toEqual({ callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false })
})
it('a configured tool receives the DERIVED deadline signal (not the caller signal) during dispatch', async () => {
const ctx = await setup({ probe: { timeoutMs: 10_000 } })
let seenSignal: AbortSignal | undefined
ctx.tools.register({ ...fastTool, name: 'probe', async execute(_a, exec) { seenSignal = exec.signal; return [{ type: 'text' as const, text: 'ok' }] } })
const upstream = new AbortController().signal
await ctx.tools.execute({ callId: CallId('c1'), name: 'probe', arguments: {}, signal: upstream })
expect(seenSignal).toBeDefined()
expect(seenSignal).not.toBe(upstream) // the plugin swapped in its fused deadline signal
})
})
describe('timeout-policy signal restoration', () => {
it('restores the caller signal for post-execute after wrapping', async () => {
const ctx = await setup({ fast: { timeoutMs: 10_000 } })
ctx.tools.register(fastTool)
let postSignal: AbortSignal | undefined | 'unset' = 'unset'
ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => {
postSignal = exec.signal
return next()
})
const upstream = new AbortController().signal
await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {}, signal: upstream })
expect(postSignal).toBe(upstream) // restored to the caller's own signal, not the deadline
})
it('deletes exec.signal again when the caller passed none', async () => {
const ctx = await setup({ fast: { timeoutMs: 10_000 } })
ctx.tools.register(fastTool)
let hadSignal: boolean | undefined
ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => {
hadSignal = 'signal' in exec && exec.signal !== undefined
return next()
})
await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} })
expect(hadSignal).toBe(false) // no caller signal → exec.signal absent again after wrapping
})
})
describe('timeout-policy TOOL_TIMEOUT replacement (deadline wins)', () => {
beforeEach(() => { vi.useFakeTimers() })
afterEach(() => { vi.useRealTimers() })
it('replaces a cooperative tool result with TOOL_TIMEOUT when its own deadline fires', async () => {
const ctx = await setup({ slow: { timeoutMs: 100 } })
ctx.tools.register(cooperativeTool)
const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'slow', arguments: {} })
await vi.advanceTimersByTimeAsync(150) // past the 100ms deadline: the timer fires, the tool settles
const result = await pending
expect(result).toEqual({
callId: CallId('c1'),
content: [{ type: 'text', text: 'Error: tool call timed out after 100ms' }],
isError: true,
error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
})
})
it('replaces a provider-owned abort ERROR result with TOOL_TIMEOUT (not WEB_ABORTED) when the signal was ours', async () => {
const ctx = await setup({ aborter: { timeoutMs: 100 } })
ctx.tools.register(abortThrowingTool)
const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'aborter', arguments: {} })
await vi.advanceTimersByTimeAsync(150)
const result = await pending
// Dispatch first normalized the thrown WEB_ABORTED into an isError result;
// the plugin then replaced THAT with TOOL_TIMEOUT because its own timer won.
expect(result.isError).toBe(true)
expect(result.error).toEqual({ name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' })
expect(result.content[0]).toMatchObject({ text: 'Error: tool call timed out after 100ms' })
})
it('does NOT replace when the caller aborts first (upstream cancel, not our timeout)', async () => {
const ctx = await setup({ slow: { timeoutMs: 100 } })
ctx.tools.register(cooperativeTool)
const upstream = new AbortController()
const pending = ctx.tools.execute({ callId: CallId('c1'), name: 'slow', arguments: {}, signal: upstream.signal })
upstream.abort('user cancelled') // fires before the 100ms timer
await vi.advanceTimersByTimeAsync(0)
const result = await pending
// Our timer never fired, so timeoutOf(code) is undefined: the tool's own
// cooperative result stands, not a TOOL_TIMEOUT.
expect(result.isError).toBe(false)
expect(result.content[0]).toMatchObject({ text: 'stopped cooperatively' })
})
})
describe('toolTimeoutResult', () => {
it('builds the structured TOOL_TIMEOUT result', () => {
expect(toolTimeoutResult(CallId('c9'), 250)).toEqual({
callId: CallId('c9'),
content: [{ type: 'text', text: 'Error: tool call timed out after 250ms' }],
isError: true,
error: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' },
} satisfies ToolExecutionResult)
})
it('exposes the owned code constant', () => {
expect(TOOL_TIMEOUT).toBe('TOOL_TIMEOUT')
})
})
describe('dsh-timeout-policy real-load-path guard', () => {
it('has no default export and keeps name/Config through unwrapExports', () => {
expect('default' in timeoutPolicy).toBe(false)
const loader = Object.create(Loader.prototype) as Loader
const unwrapped = loader.unwrapExports(timeoutPolicy) as Record<string, unknown>
expect(unwrapped).toBe(timeoutPolicy)
expect(unwrapped.name).toBe('timeout-policy')
expect(typeof unwrapped.apply).toBe('function')
expect(unwrapped.Config).toBeDefined()
})
it('boots over ctx.tools through the unwrapped module and wraps a configured tool', async () => {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
ctx.tools.register(fastTool)
const loader = Object.create(Loader.prototype) as Loader
const unwrapped = loader.unwrapExports(timeoutPolicy) as Parameters<Context['plugin']>[0]
const fiber = await ctx.plugin(unwrapped, { tools: { fast: { timeoutMs: 5_000 } } })
// A configured fast tool still succeeds (deadline never fires); this proves
// the wrapper is live through the real Loader path.
const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'fast', arguments: {} } satisfies ToolExecution)
expect(result.isError).toBe(false)
await fiber.dispose()
})
})

View File

@@ -0,0 +1,16 @@
{
"extends": "../../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "lib/types"
},
"include": ["src"],
"references": [
{ "path": "../../../vendor/cosmokit" },
{ "path": "../../../vendor/cordis" },
{ "path": "../../../vendor/schemastery" },
{ "path": "../../llm/llm" },
{ "path": "../../util/timeout" },
{ "path": "../../core/tools" }
]
}