@hasna-internal/kai-tool-call-timeout-policy 0.1.1-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/guard/timeout-policy/README.md
+README.md: 4b0ea4e541f0740289623f5e81d79e168240a402
+README.zh.md: 36bf8150e5b095c713cb71b76bd8dcc43857afc8

package/README.md

@@ -0,0 +1,57 @@
+# dsh-tool-call-timeout-policy
+
+English | [中文](README.zh.md)
+
+Tool-call timeout enforcer: a single `tools/execute` around-dispatch listener that arms a per-call cooperative deadline on `exec.signal` for a tool declaring `timeoutMs` on its `ToolDefinition` and returns a structured `TOOL_TIMEOUT` result when that deadline wins. The budget is read from the tool's own declaration (`ToolDefinition.timeoutMs`, set by the owning tool plugin), so this plugin is **zero-config**. It is the reference `tools/execute` wrapper and the enforcement home for model-facing tool-call budgets ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
+
+## Plugin (namespace: `timeout-policy`)
+
+A function/namespace plugin (`name` / `inject` / `apply`), not a service. It registers no tool and takes no config — it consumes `ctx.tools`'s `tools/execute` waterfall (which the `dsh-tools` registry always provides) and reads each dispatched tool's declared `timeoutMs` from the registry (`ctx.tools.get(exec.name)`).
+
+```yaml
+- id: timeout-policy
+  name: '@hasna-internal/kai-tool-call-timeout-policy'
+```
+
+The per-tool budget is declared by the tool plugin (e.g. `dsh-tool-web`'s `fetchTimeoutMs`/`searchTimeoutMs` config, attached as `ToolDefinition.timeoutMs`); this plugin only enforces it, so a mistyped tool name is not possible.
+
+### Behavior
+
+For a tool that **declares a `timeoutMs`** the listener:
+
+1. Reads the budget from the tool's own declaration in the registry (`ctx.tools.get(exec.name)?.timeoutMs`) and arms `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')` — one signal fusing the caller's abort with this plugin's timer (`@hasna-internal/kai-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: { message, info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' } }, content: 'Error: tool call timed out after <ms>ms' }`.
+
+A tool that **declares no budget** 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). **Declaring `timeoutMs` therefore means "cooperative with `exec.signal`"**: a tool that ignores the signal will not stop on timeout. Only signal-forwarding tools should declare it — 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).
+
+## Model Experience
+
+### Conditional tool result
+
+#### What the model sees
+
+This plugin adds no prompt or schema. If a declared deadline wins, it replaces the provider's outcome with `Error: tool call timed out after <ms>ms` plus structured `TOOL_TIMEOUT`; otherwise the original result passes through unchanged.
+
+#### 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
+
+- **Cooperative, never a hard kill** — the deadline only notifies via `exec.signal`; a tool that ignores the signal does not stop on timeout (see § Cooperative, not a hard kill).
+- **No blanket budget** — only tools that declare `timeoutMs` on their `ToolDefinition` get a deadline; there is no registry-wide default for undeclared tools (the shipped `bash`/`read`/`write`/`edit` deliberately declare none).

package/README.zh.md

@@ -0,0 +1,57 @@
+# dsh-tool-call-timeout-policy
+
+[English](README.md) | 中文
+
+工具调用超时强制执行器：单个 `tools/execute` 环绕分发监听器，会在 `exec.signal` 上设置单次调用的协作式截止时间；适用于声明了 `timeoutMs` 且声明位于其 `ToolDefinition` 上的工具。该截止时间先到时，它返回结构化 `TOOL_TIMEOUT` 结果。预算从工具自身的声明中读取（`ToolDefinition.timeoutMs`，由拥有该工具的插件设置），因此此插件是**零配置**的。它是 `tools/execute` 包装层的参考实现，也是面向模型工具调用预算的强制执行归属地（[超时库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md)）。
+
+## 插件（命名空间：`timeout-policy`）
+
+它是函数／命名空间插件（`name`／`inject`／`apply`），而非服务。它不注册工具，也不接受配置；它消费 `ctx.tools` 的 `tools/execute` waterfall（瀑布式事件）（由 `dsh-tools` 注册表始终提供），并读取每个已分发工具声明的 `timeoutMs`；该声明来自注册表（`ctx.tools.get(exec.name)`）。
+
+```yaml
+- id: timeout-policy
+  name: '@hasna-internal/kai-tool-call-timeout-policy'
+```
+
+每工具预算由工具插件声明（例如 `dsh-tool-web` 的 `fetchTimeoutMs`／`searchTimeoutMs` 配置，会附加为 `ToolDefinition.timeoutMs`）；此插件只负责强制执行，因此不可能拼错工具名。
+
+### 行为
+
+对 **声明了 `timeoutMs` 的工具**，监听器会：
+
+1. 从注册表中的工具自身声明（`ctx.tools.get(exec.name)?.timeoutMs`）读取预算，并设置 `deadline(exec.signal, timeoutMs, 'TOOL_TIMEOUT')`：一个将调用方中止与此插件计时器融合的信号（`@hasna-internal/kai-timeout`）。
+2. 将该派生信号替换到 `exec` 上用于下游分发，然后恢复调用方自身的信号（Cordis `next()` 忽略传入的参数，因此包装层会原地修改共享 `exec`；恢复可使 `tools/post-execute` 看到调用方的信号）。
+3. 分发后，如果 `timeoutOf(d.signal, 'TOOL_TIMEOUT')` 检测到此插件自身的计时器已触发，则将结果替换为结构化 `TOOL_TIMEOUT` 工具结果：`{ isError: true, error: { message, info: { name: 'ToolTimeoutError', code: 'TOOL_TIMEOUT' } }, content: 'Error: tool call timed out after <ms>ms' }`。
+
+**未声明预算的工具** 会原样委托（不启动截止时间）。
+
+基础 `next()` 是注册表为 `tools/execute` 提供的、带规范化处理的分发 thunk，因此当超时信号到达抛出自身上游中止错误的提供方时，分发会先将其转换为普通错误结果，再由此包装层替换为 `TOOL_TIMEOUT`。这一顺序就是替换依据信号（`timeoutOf`）而非已分发结果形状的原因。
+
+### 协作式，而非硬终止
+
+派生信号只会**通知**；是否终止仍取决于工具及其将 `exec.signal` 转发到的能力（`dsh-timeout` 库本身不负责硬终止）。**因此，声明 `timeoutMs` 意味着「与 `exec.signal` 协作」**：忽略该信号的工具不会在超时时停止。只有转发信号的工具才应声明该字段；已交付的 `web_fetch`／`web_search`（通过 `ctx.web` 转发给提供方）是参考实现。`TOOL_TIMEOUT` 无需会话事件以满足可重建性：它是最终面向模型的 `tool/result`，已由循环记录。
+
+### 与其他 `tools/execute` 包装层组合
+
+多个 `tools/execute` 监听器按 Cordis 注册顺序组合。与未来的重试／沙箱／指标包装层一起使用时，注册顺序决定语义：「超时覆盖整个重试操作」（超时注册在外层），或「超时覆盖每次尝试」（超时注册在内层）。
+
+## 模型体验
+
+### 条件工具结果
+
+#### 模型看到的内容
+
+此插件不添加提示词或 schema。如果已声明的截止时间先到，它会将提供方结果替换为 `Error: tool call timed out after <ms>ms` 与结构化 `TOOL_TIMEOUT`；否则原结果保持不变。
+
+#### Token 影响
+
+未超时的调用不会增加 token。超时会添加一条会被保留的简短错误结果，并可防止体积更大、较晚返回的提供方结果进入上下文。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **协作式，绝不是硬终止**：截止时间只通过 `exec.signal` 通知；忽略该信号的工具不会在超时时停止（参见「协作式，而非硬终止」一节）。
+- **没有统一预算**：只有声明 `timeoutMs` 并将其放在 `ToolDefinition` 上的工具才会获得截止时间；未声明工具没有注册表级默认值（已交付的 `bash`／`read`／`write`／`edit` 有意不声明）。

package/lib/index.js

@@ -0,0 +1,144 @@
+import { deadline, timeoutOf } from "@hasna-internal/kai-timeout";
+//#region lib/types/index.js
+/**
+* Cooperative tool-call timeout enforcer. A tool declares `timeoutMs` and
+* promises to honor `exec.signal`; this wrapper arms that deadline and maps its
+* own expiry to `TOOL_TIMEOUT` without racing or abandoning the tool promise.
+*
+* FIXME: settle the intended `@hasna-internal/kai-timeout-guard` rename before the
+* first tagged release — suggestion only, aligning the name with its `guard/`
+* home; decide at resolution time
+* ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
+*
+* @module @hasna-internal/kai-tool-call-timeout-policy
+*/
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+* 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.
+*/
+const TOOL_TIMEOUT = "TOOL_TIMEOUT";
+/** Cordis plugin name used by loader diagnostics. */
+const name = "timeout-policy";
+/** The tool registry service this plugin wraps (`tools/execute`) and reads (`get`). */
+const inject = ["tools"];
+/**
+* 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.
+*
+* @param timeoutMs - the elapsed budget, rendered into the model-facing message.
+* @returns the `isError` {@link ToolExecutionResult} with a `TOOL_TIMEOUT` error.
+*/
+function toolTimeoutResult(timeoutMs) {
+	const message = `tool call timed out after ${timeoutMs}ms`;
+	return {
+		content: [{
+			type: "text",
+			text: `Error: ${message}`
+		}],
+		isError: true,
+		error: {
+			message,
+			info: {
+				name: "ToolTimeoutError",
+				code: TOOL_TIMEOUT
+			}
+		}
+	};
+}
+/**
+* Register the timeout wrapper. It resolves the caller-visible tool definition,
+* temporarily replaces `exec.signal`, delegates, restores the upstream signal,
+* and replaces the result only when this wrapper's own timer fired.
+*/
+function apply(ctx) {
+	ctx.on("tools/execute", async (exec, next) => {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			const timeoutMs = ctx.tools.get(exec.name, exec.agent)?.timeoutMs;
+			if (timeoutMs === void 0) return next();
+			const d = __addDisposableResource(env_1, deadline(exec.signal, timeoutMs, TOOL_TIMEOUT), false);
+			const upstream = exec.signal;
+			exec.signal = d.signal;
+			try {
+				const result = await next();
+				if (timeoutOf(d.signal, "TOOL_TIMEOUT") !== void 0) return toolTimeoutResult(timeoutMs);
+				return result;
+			} finally {
+				exec.signal = upstream;
+			}
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	});
+}
+//#endregion
+export { TOOL_TIMEOUT, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-tool-call-timeout-policy`.
+* @module @hasna-internal/kai-tool-call-timeout-policy/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-tool-call-timeout-policy";
+/** Cordis companion plugin name. */
+const name = "timeout-policy-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this stateless policy plugin owns no package-local event history or mutable
+* data relation beyond the seam it intercepts.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cooperative tool-call timeout enforcer. A tool declares `timeoutMs` and
+ * promises to honor `exec.signal`; this wrapper arms that deadline and maps its
+ * own expiry to `TOOL_TIMEOUT` without racing or abandoning the tool promise.
+ *
+ * FIXME: settle the intended `@hasna-internal/kai-timeout-guard` rename before the
+ * first tagged release — suggestion only, aligning the name with its `guard/`
+ * home; decide at resolution time
+ * ([regrouping Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md)).
+ *
+ * @module @hasna-internal/kai-tool-call-timeout-policy
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * 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 declare const TOOL_TIMEOUT = "TOOL_TIMEOUT";
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "timeout-policy";
+/** The tool registry service this plugin wraps (`tools/execute`) and reads (`get`). */
+export declare const inject: string[];
+/**
+ * Register the timeout wrapper. It resolves the caller-visible tool definition,
+ * temporarily replaces `exec.signal`, delegates, restores the upstream signal,
+ * and replaces the result only when this wrapper's own timer fired.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-tool-call-timeout-policy`.
+ * @module @hasna-internal/kai-tool-call-timeout-policy/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "timeout-policy-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hasna-internal/kai-tool-call-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.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/guard/timeout-policy"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-tools": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-timeout": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-tools": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-timeout": "^0.1.1-rc.2"
+  }
+}