Turtle
38c7a9fbf4
* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * test(release): expect source and maps in master's new payload cases * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * build(release): publish source and maps from the message-quotes package * build(release): publish source and maps from packages new on master * build(release): publish source and maps from the tool-office package
description, kind
| description | kind |
|---|---|
| Cooperative time limit for cancellation-aware tool calls, mapping a settled timeout to a clear model error for users and maintainers choosing or debugging the plugin. | package-reference |
@deepseek-ai/dsh-tool-call-timeout-policy
English | 中文
Summary
Use this package to give tool calls their configured cooperative time limits and return a clear timeout error to the model after cancellation settles. Calls that finish in time are unchanged. A tool that ignores or slowly handles cancellation can keep the caller waiting because the package cannot hard-stop downstream work. Each tool supplies its own limit; the package has no configuration and is enabled in the dsh base bundle.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
The common path is one line: add the plugin to the composition — the dsh base bundle already has it. Tools that have a limit configured are protected automatically; every other tool is untouched.
When to choose it
Choose it when the model calls tools that can take a long time, those tools honor exec.signal, and you want a predictable timed-out answer after cancellation settles. Avoid it when a tool must be hard-stopped at its limit — the plugin can only ask a tool to stop, so a tool that ignores cancellation keeps running and keeps the caller waiting — and when you want one default limit for every tool, because each tool's limit comes from that tool's own configuration.
Setting it up
Mount the plugin with no configuration:
- name: '@deepseek-ai/dsh-tool-call-timeout-policy'
The limit is set where the tool is configured. For example, dsh-tool-web's fetchTimeoutMs/searchTimeoutMs settings (default 30,000 ms) put the limit on web_fetch and web_search. Tools without a limit — the shipped bash, read, write, and edit — are never cut off. The generated configuration catalog lists the tool settings that produce limits.
What you get
When the deadline fires, the plugin aborts the derived exec.signal. After downstream code honors cancellation and next() settles, the model receives Error: tool call timed out after <ms>ms as an error result, so it can decide to retry, adjust, or give up. A tool that ignores or slowly handles the signal keeps the caller waiting and produces no timeout result until it settles; calls that finish in time are unchanged.
Understand the implementation
Implementation internals — click to expand
This section explains how the plugin arms a deadline around each dispatch and maps it to the TOOL_TIMEOUT result, and points at the code that realizes it; the observable behavior is fully covered in Use this package.
Design philosophy
The wrapper is built on four commitments:
- Enforcement home, not a library.
dsh-timeoutowns timing and classification (deadline,timeoutOf); this plugin owns the per-call wiring overtools/execute; each capability owns termination. The split is recorded in the timeout-deadline-library Agent Note. - The tool declares its own budget.
timeoutMslives on the tool'sToolDefinition, read from the registry (ctx.tools.get(exec.name, exec.agent)?.timeoutMs), so a mistyped tool name is impossible and undeclared tools delegate untouched. - Scoped classification.
TOOL_TIMEOUTserves as both the internaldeadlineclassification code and the structured errorcode; scopingtimeoutOfto it keeps a nested outer deadline (another wrapper's timer that fired first) from being misread as this plugin's timeout — it reads as an ordinary upstream cancel. - Signal swap, then restore. Cordis
next()ignores passed arguments, so the wrapper mutates the sharedexecin place: it swaps the derived deadline signal ontoexecfor dispatch and restores the caller's signal in afinally, sotools/post-executelisteners never see this plugin's possibly-aborted signal.
How a deadline is armed and mapped
One tools/execute listener reads the dispatched tool's declared limit from the registry (ctx.tools.get(exec.name, exec.agent)?.timeoutMs); a tool without a limit delegates untouched. For a limited tool, deadline(exec.signal, timeoutMs, TOOL_TIMEOUT) builds a fused signal that the wrapper swaps onto exec for dispatch and restores in a finally, so tools/post-execute listeners never see the derived signal. When the wrapper's own timer fired — timeoutOf(d.signal, 'TOOL_TIMEOUT') scoped by the code, so a nested outer deadline reads as an ordinary upstream cancel — the dispatched result, already normalized into an error result by dispatch, is replaced with the structured result: isError: true, content Error: tool call timed out after <ms>ms, and error info { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' }.
Composing with other wrappers
Multiple tools/execute listeners compose by Cordis registration order, which chooses the semantics: the timeout registered outer covers a whole retry operation, the timeout registered inner covers each attempt.
Source map
| File | Role |
|---|---|
src/index.ts |
Plugin entry: TOOL_TIMEOUT, name/inject/apply, the tools/execute wrapper |
Further Exploration
Read these pages when the package-level contract is not enough. They move from the tool-call pipeline to the timeout-library split, the enforced limits, and the guard group map.
- Tools subsystem reference — the
tools/executewaterfall and decision shapes this wrapper hooks. - Timeout deadline library Agent Note — the timing/termination split and why the deadline only notifies.
- Generated configuration catalog —
dsh-tool-web'sfetchTimeoutMs/searchTimeoutMsbudgets the policy enforces. - guard group map — the sibling guard packages and the loop-hygiene family.
Model Experience
Conditional tool result
What the model sees
This plugin adds no prompt or schema. If a declared deadline wins and downstream cancellation settles, it replaces the provider's outcome with Error: tool call timed out after <ms>ms plus the structured TOOL_TIMEOUT error; otherwise the original result passes through unchanged. A downstream call that never settles cannot produce a timeout result.
Token effect
Zero tokens on non-timeout calls. A timeout adds one small retained error result and can prevent a larger late provider result from entering context.
KV Cache effect
Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV Cache entries.
Known Limitations and Deferred Work
These limits define when the policy is a poor fit. They are current package constraints, not a task backlog.
- Cooperative, never a hard kill — the deadline only notifies via
exec.signal; a tool that ignores the signal does not stop on timeout, the wrapper remains insideawait next(), and the model receives no timeout result until downstream settles. - No blanket budget — only tools that declare
timeoutMson theirToolDefinitionget a deadline; undeclared tools (the shippedbash,read,write, andeditdeclare none) have no registry-wide default.
Dev Note
Working context for maintainers — click to expand
This Dev Note is working context for maintainers: open questions and directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
The src/index.ts FIXME asks to settle a @deepseek-ai/dsh-timeout-guard rename; the naming ledger already records @deepseek-ai/dsh-tool-call-timeout-policy as the decided name, so the FIXME is stale pending a code cleanup.