@deepseek-ai/dsh-timeout 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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/util/timeout/README.md
+README.md: 40a655200780e25c434beed4953d96f46e3604fd
+README.zh.md: 638dc1af60761f9c964e356edc070d20af0f4819

package/README.md

@@ -0,0 +1,70 @@
+# dsh-timeout
+
+English | [中文](README.zh.md)
+
+The **timing-and-classification** half of a timeout — a zero-dependency library of pure functions (no runtime harness deps) shared by every capability that clamps a caller's timeout hint, arms a deadline, and later has to tell "timed out" apart from "cancelled".
+
+It owns **no termination**. The signal it hands out only *notifies*; actually stopping the work stays in each capability, because that mechanism differs — bash SIGKILLs an OS process group, web tears down a `fetch` socket — and no shared layer can own all of them. This is the boundary the [Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md) draws: share the timing/classification, keep the hard kill local.
+
+It is a **library, not a service or plugin**: no `ctx`, registers nothing, holds no state, emits no events. A "timeout service" would have to understand how to stop every capability's work — exactly the knowledge a microkernel keeps out of shared layers.
+
+## Surface
+
+```ts
+import { clampTimeout, deadline, idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf, TimeoutReason } from '@deepseek-ai/dsh-timeout'
+```
+
+| Export | Role |
+|---|---|
+| `clampTimeout(requested, def, max, name?)` | Validate the caller's optional positive-finite hint, fill from `def`, cap at `max`. Throws (with `name`) on a non-positive/non-finite hint. |
+| `deadline(upstream, timeoutMs, code)` | Fuse `upstream` cancellation with a timeout into one `AbortSignal` (`AbortSignal.any`); the timeout carries a `TimeoutReason`. `[Symbol.dispose]` clears the timer. |
+| `idleWatchdog(upstream, timeoutMs, code)` | Keep one stable fused signal and arm only while its guarded async-iterator `next()` is outstanding. Resolution disarms; later demand or `pulse()` activity rearms; disposal clears; concurrent demand rejects. |
+| `MAX_TIMER_DELAY_MS` | Largest delay Node schedules without clamping it to one millisecond (`2_147_483_647`). Timer-owning config must not exceed it. |
+| `timeoutOf(signal \| { reason }, code?)` | Recover the `TimeoutReason` from an aborted signal/error, else `undefined` — the timeout-vs-cancel classifier. Pass `code` to match only THIS deadline's timer (see nesting below). |
+| `TimeoutReason` | The internal reason (`code` + `timeoutMs`) stamped on a timeout abort. Not a public error — providers translate it into their own error/field. |
+
+## The `timeoutMs <= 0` sentinel
+
+`0` is the **internal** "no timeout" value for backend-owned background work (bash `start()`): `deadline()` arms no timer and forwards only `upstream`; with no upstream either, it returns a never-aborting signal plus a no-op disposer, so every caller keeps one call shape. External request hints validate as **positive finite** via `clampTimeout` before they reach `deadline`, so `0` is never a model-/plugin-facing "disable timeout" value.
+
+## Usage shape
+
+```ts
+import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
+
+declare function runWork(options: { signal: AbortSignal }): Promise<unknown>
+
+// Scope-lifetime consumer (foreground bash, one fetch): `using` disposes the timer.
+export async function runWithDeadline(upstream: AbortSignal | undefined, timeoutMs: number): Promise<unknown> {
+  using d = deadline(upstream, timeoutMs, 'BASH_TIMEOUT')
+  const outcome = await runWork({ signal: d.signal })               // work listens on d.signal and terminates itself
+  const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined // classify the first abort, scoped to OUR code
+  const aborted = d.signal.aborted && !timedOut                     // mutually exclusive: timeout won, or cancel did
+  return { outcome, timedOut, aborted }
+}
+```
+
+The signal only *notifies* — the caller MUST attach its own termination (`d.signal.addEventListener('abort', kill)`, or hand `d.signal` to `fetch`). Racing a promise against a timer would resolve the tool-call while the child process or socket leaks on; handing out a signal forces a real termination path to exist.
+
+Pass your own `code` to `timeoutOf` so classification composes under nesting. When `upstream` is itself a deadline signal, `AbortSignal.any` preserves its `TimeoutReason` if that timer fires first. Scoping to your code makes a foreign timeout read as an ordinary upstream cancel instead of claiming that the local timer expired.
+
+For a streamed transport, create one `idleWatchdog`, pass its stable `signal` into the transport, and call `watchdog.next(iterator)` for each provider read. Call `watchdog.pulse()` when transport activity does not yield an iterator value. The interval must be positive, finite, and no greater than `MAX_TIMER_DELAY_MS`; Node otherwise clamps it to one millisecond. It measures only outstanding demand, so no timer runs while downstream code renders or otherwise waits before asking for the next chunk. The primitive still only notifies, so the transport must observe the stable signal; the DeepSeek and pi-ai adapters prove that timeout closes their real response body or SDK request.
+
+## What does NOT get a timeout
+
+Local file `read`/`write`/`edit` take no `timeoutMs`: file IO runs untimed because a deadline would kill work the OS will still finish. See [the filesystem subsystem page](../../../docs/subsystems/filesystem.md).
+
+## Model Experience
+
+Indirectly, through consumers such as `dsh-timeout-policy`, which may replace a provider result with a retained timeout error or suppress a late result.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Notification only** — a deadline cannot stop work that ignores its signal; every capability still needs its own socket/process/task termination path.
+- **`timeoutMs <= 0` is internal vocabulary** — it disables the local timer only after an owning backend has resolved policy, never as a public model/plugin knob.
+- **The first abort reason wins classification** — when an upstream cancellation beats the local timer, this layer cannot later report that its own timeout would also have elapsed.
+- **An idle watchdog is not a total deadline** — it rearms per outstanding iterator demand and deliberately excludes consumer think time.

package/README.zh.md

@@ -0,0 +1,70 @@
+# dsh-timeout
+
+[English](README.md) | 中文
+
+超时的**时序与分类**部分：一个零依赖纯函数库（无运行时 harness 依赖），由每个需要限制调用方超时提示、启动 deadline，并在之后区分「已超时」与「已取消」的功能共享。
+
+它**不负责终止**。它发出的信号只会*通知*；真正停止工作仍由各功能负责，因为机制各不相同：bash 对操作系统进程组发送 SIGKILL，web 关闭 `fetch` 套接字，没有任何共享层能够承担全部终止机制。[Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md) 将边界划定为：共享时序/分类，将强制终止保留在本地。
+
+它是**库，而非服务或插件**：没有 `ctx`，不注册任何内容，不持有状态，也不发出事件。「超时服务」必须了解如何停止每项功能的工作，这正是微内核要排除在共享层之外的知识。
+
+## 对外接口
+
+```ts
+import { clampTimeout, deadline, idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf, TimeoutReason } from '@deepseek-ai/dsh-timeout'
+```
+
+| 导出项 | 职责 |
+|---|---|
+| `clampTimeout(requested, def, max, name?)` | 验证调用方可选的、值为正且有限的提示，从 `def` 填充，并限制在 `max` 以内。如果提示为非正数或非有限数，则抛出错误（包含 `name`）。 |
+| `deadline(upstream, timeoutMs, code)` | 将 `upstream` 取消与超时融合为一个 `AbortSignal`（`AbortSignal.any`）；超时携带 `TimeoutReason`。`[Symbol.dispose]` 清除 timer。 |
+| `idleWatchdog(upstream, timeoutMs, code)` | 保持一个稳定的融合信号，并且只在受保护的异步迭代器 `next()` 尚未完成时启动 timer。完成后停止 timer；后续需求或 `pulse()` 活动会重新启动 timer；dispose（资源释放）时清除；并发需求被拒绝。 |
+| `MAX_TIMER_DELAY_MS` | Node 在不将延迟限制为 1 毫秒时可调度的最大延迟（`2_147_483_647`）。负责 timer 的配置不得超过该值。 |
+| `timeoutOf(signal \| { reason }, code?)` | 从已中止的信号/错误中恢复 `TimeoutReason`，否则返回 `undefined`，即超时与取消的分类器。传入 `code` 可仅匹配这个 deadline 的 timer（见下文的嵌套）。 |
+| `TimeoutReason` | 标记在超时中止上的内部原因（`code` + `timeoutMs`）。它不是公开错误；提供方将其转换为自己的错误/字段。 |
+
+## `timeoutMs <= 0` 哨兵值
+
+`0` 是后端自有后台工作（bash `start()`）使用的**内部**「无超时」值。`deadline()` 不启动 timer，只转发 `upstream`；如果也没有 upstream，它将返回永不中止的信号和无操作 disposer，因此每个调用方都能保持同一种调用形态。外部请求提示会通过 `clampTimeout` 验证为**正有限数**，之后才进入 `deadline`，因此 `0` 绝不是面向模型/插件的「禁用超时」值。
+
+## 使用形态
+
+```ts
+import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
+
+declare function runWork(options: { signal: AbortSignal }): Promise<unknown>
+
+// Scope-lifetime consumer (foreground bash, one fetch): `using` disposes the timer.
+export async function runWithDeadline(upstream: AbortSignal | undefined, timeoutMs: number): Promise<unknown> {
+  using d = deadline(upstream, timeoutMs, 'BASH_TIMEOUT')
+  const outcome = await runWork({ signal: d.signal })               // work listens on d.signal and terminates itself
+  const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined // classify the first abort, scoped to OUR code
+  const aborted = d.signal.aborted && !timedOut                     // mutually exclusive: timeout won, or cancel did
+  return { outcome, timedOut, aborted }
+}
+```
+
+该信号只会*通知*；调用方必须接入自己的终止机制（`d.signal.addEventListener('abort', kill)`，或将 `d.signal` 传给 `fetch`）。让 promise 与 timer 竞速，会在子进程或套接字仍在泄漏时就让工具调用完成；发出信号则会强制要求存在真正的终止路径。
+
+将你自己的 `code` 传给 `timeoutOf`，使分类可在嵌套场景中正确组合。当 `upstream` 本身是 deadline 信号时，如果该 timer 先触发，`AbortSignal.any` 会保留它的 `TimeoutReason`。将匹配范围限定为你的 code，会把外部超时视为普通的 upstream 取消，而不会声称本地 timer 已到期。
+
+对于流式传输，创建一个 `idleWatchdog`，将其稳定的 `signal` 传给传输层，并为提供方的每次读取调用 `watchdog.next(iterator)`。当传输活动不产生迭代器值时，调用 `watchdog.pulse()`。间隔必须为正有限数，且不得超过 `MAX_TIMER_DELAY_MS`；否则 Node 会将其限制为 1 毫秒。它只对尚未完成的读取请求计时，因此当下游代码进行渲染或在请求下一个分片前以其他方式等待时，timer 不会运行。该原语仍然只会通知，因此传输层必须观察稳定信号；DeepSeek 和 pi-ai 适配器证明，超时会关闭它们的真实响应正文或 SDK 请求。
+
+## 哪些操作不设置超时
+
+本地文件 `read`/`write`/`edit` 不接受 `timeoutMs`：文件 IO 不设时限地运行，因为截止时间会中止操作系统仍会完成的工作。详见[文件系统子系统页面](../../../docs/subsystems/filesystem.md)。
+
+## 模型体验
+
+通过 `dsh-timeout-policy` 等消费方间接影响模型；消费方可能会将提供方结果替换为已保留的超时错误，或抑制延迟结果。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **只发出通知**：deadline 无法停止忽略其信号的工作；每项功能仍需要自己的 socket/进程/任务终止路径。
+- **`timeoutMs <= 0` 是内部词汇**：只有在所属后端已解析策略后，它才会禁用本地 timer；绝不会作为面向模型/插件的公开开关。
+- **第一个中止原因决定分类**：当 upstream 取消早于本地 timer 发生时，即使自己的超时之后也会到期，该层也无法再报告。
+- **空闲 watchdog 不是总 deadline**：它针对每个尚未完成的迭代器需求重新启动，并刻意排除消费方的处理时间。

package/lib/index.js

@@ -0,0 +1,140 @@
+//#region lib/types/index.js
+/**
+* Shared timeout arithmetic, signal fusion, and classification. The library
+* only notifies through abort signals; each capability still owns the mechanism
+* that stops its work and translates timeout reasons into public outcomes.
+* @module @deepseek-ai/dsh-timeout
+*/
+/**
+* Internal abort reason carrying a capability-owned code and elapsed deadline.
+* Providers translate it through {@link timeoutOf} before returning to callers.
+*/
+var TimeoutReason = class extends Error {
+	code;
+	timeoutMs;
+	name = "TimeoutReason";
+	/**
+	* @param code Capability-owned timeout code (e.g. `BASH_TIMEOUT`).
+	* @param timeoutMs The deadline that elapsed, in milliseconds.
+	*/
+	constructor(code, timeoutMs) {
+		super(`${code} after ${timeoutMs}ms`);
+		this.code = code;
+		this.timeoutMs = timeoutMs;
+	}
+};
+/** Largest delay Node schedules without clamping it to one millisecond. */
+const MAX_TIMER_DELAY_MS = 2147483647;
+function assertTimerDelay(timeoutMs, name) {
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) throw new Error(`${name} must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+}
+/**
+* Validate a caller's optional timeout hint, use the backend default, then cap
+* it. Supplied values must be positive and finite; zero is not a public
+* disable-timeout sentinel.
+*
+* @param requested The caller's optional hint; validated when present.
+* @param def The backend default applied when `requested` is absent.
+* @param max The backend upper bound the result is capped to.
+* @param name Field name used in the thrown message (so the caller sees which input was
+*   bad).
+* @returns The effective timeout in milliseconds: `min(requested ?? def, max)`.
+*/
+function clampTimeout(requested, def, max, name = "timeoutMs") {
+	if (requested !== void 0 && (!Number.isFinite(requested) || requested <= 0)) throw new Error(`${name} must be a positive finite number`);
+	return Math.min(requested ?? def, max);
+}
+/**
+* Fuse upstream cancellation with an identifiable timeout. `timeoutMs <= 0` is
+* the internal no-timer sentinel; the returned disposer clears an armed timer.
+* The signal only notifies, so callers must stop their own work.
+*
+* @param upstream The caller's cancellation signal, if any, fused into the result.
+* @param timeoutMs Deadline in milliseconds; `<= 0` means "no timeout" (arm no timer).
+* @param code Capability-owned code stamped onto the timeout's {@link TimeoutReason}.
+* @returns The fused {@link Deadline} (signal + timer cleanup).
+*/
+function deadline(upstream, timeoutMs, code) {
+	if (timeoutMs <= 0) return {
+		signal: upstream ?? new AbortController().signal,
+		[Symbol.dispose]() {}
+	};
+	assertTimerDelay(timeoutMs, "deadline timeoutMs");
+	const timer = new AbortController();
+	const id = setTimeout(() => {
+		timer.abort(new TimeoutReason(code, timeoutMs));
+	}, timeoutMs);
+	return {
+		signal: upstream !== void 0 ? AbortSignal.any([upstream, timer.signal]) : timer.signal,
+		[Symbol.dispose]() {
+			clearTimeout(id);
+		}
+	};
+}
+/**
+* Create a rearmable idle watchdog for an async iterator. The timer exists only
+* while {@link IdleWatchdog.next} is outstanding, so consumer think time does
+* not count as provider idle time. The returned signal is stable for the whole
+* call and only notifies; the iterator must observe it to terminate its work.
+*
+* @param upstream - caller cancellation fused into the stable signal.
+* @param timeoutMs - positive finite idle interval in milliseconds.
+* @param code - capability-owned code carried by the timeout reason.
+* @returns a stable signal, guarded next operation, and timer disposer.
+*/
+function idleWatchdog(upstream, timeoutMs, code) {
+	assertTimerDelay(timeoutMs, "idleWatchdog timeoutMs");
+	const timeout = new AbortController();
+	const signal = upstream === void 0 ? timeout.signal : AbortSignal.any([upstream, timeout.signal]);
+	let timer;
+	let outstanding = false;
+	let disposed = false;
+	const arm = () => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => {
+			timeout.abort(new TimeoutReason(code, timeoutMs));
+		}, timeoutMs);
+	};
+	return {
+		signal,
+		async next(iterator) {
+			if (disposed) throw new Error("idleWatchdog is disposed");
+			if (outstanding) throw new Error("idleWatchdog next is already outstanding");
+			outstanding = true;
+			arm();
+			try {
+				return await iterator.next();
+			} finally {
+				clearTimeout(timer);
+				timer = void 0;
+				outstanding = false;
+			}
+		},
+		pulse() {
+			if (disposed || !outstanding) return;
+			arm();
+		},
+		[Symbol.dispose]() {
+			if (disposed) return;
+			disposed = true;
+			if (timer !== void 0) clearTimeout(timer);
+			timer = void 0;
+		}
+	};
+}
+/**
+* Recover a timeout reason from a reason-bearing object. Supplying `code`
+* distinguishes this deadline from a nested upstream deadline; a foreign code
+* follows the ordinary cancellation path.
+*
+* @param x An {@link AbortSignal} or any `{ reason }` carrier (e.g. a caught abort error).
+* @param code When provided, only a {@link TimeoutReason} with this exact `code` matches.
+* @returns The matching {@link TimeoutReason}, else `undefined`.
+*/
+function timeoutOf(x, code) {
+	const reason = x.reason;
+	if (!(reason instanceof TimeoutReason)) return void 0;
+	return code === void 0 || reason.code === code ? reason : void 0;
+}
+//#endregion
+export { MAX_TIMER_DELAY_MS, TimeoutReason, clampTimeout, deadline, idleWatchdog, timeoutOf };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-timeout`.
+* @module @deepseek-ai/dsh-timeout/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-timeout";
+/** Cordis companion plugin name. */
+const name = "timeout-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this pure utility owns no event stream or mutable runtime data; its value
+* algebra is enforced by unit tests.
+*/
+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,93 @@
+/**
+ * Shared timeout arithmetic, signal fusion, and classification. The library
+ * only notifies through abort signals; each capability still owns the mechanism
+ * that stops its work and translates timeout reasons into public outcomes.
+ * @module @deepseek-ai/dsh-timeout
+ */
+/**
+ * Internal abort reason carrying a capability-owned code and elapsed deadline.
+ * Providers translate it through {@link timeoutOf} before returning to callers.
+ */
+export declare class TimeoutReason extends Error {
+    readonly code: string;
+    readonly timeoutMs: number;
+    name: string;
+    /**
+     * @param code Capability-owned timeout code (e.g. `BASH_TIMEOUT`).
+     * @param timeoutMs The deadline that elapsed, in milliseconds.
+     */
+    constructor(code: string, timeoutMs: number);
+}
+/** Largest delay Node schedules without clamping it to one millisecond. */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * Validate a caller's optional timeout hint, use the backend default, then cap
+ * it. Supplied values must be positive and finite; zero is not a public
+ * disable-timeout sentinel.
+ *
+ * @param requested The caller's optional hint; validated when present.
+ * @param def The backend default applied when `requested` is absent.
+ * @param max The backend upper bound the result is capped to.
+ * @param name Field name used in the thrown message (so the caller sees which input was
+ *   bad).
+ * @returns The effective timeout in milliseconds: `min(requested ?? def, max)`.
+ */
+export declare function clampTimeout(requested: number | undefined, def: number, max: number, name?: string): number;
+/** A deadline signal plus the cleanup that clears its timer (dispose-once). */
+export interface Deadline {
+    /** Aborts on upstream cancellation OR on timeout (the timeout carries a {@link TimeoutReason}). */
+    readonly signal: AbortSignal;
+    /** Clear the timer. Safe to call once; `using` calls it at scope exit. */
+    [Symbol.dispose](): void;
+}
+/** Rearmable timeout around one outstanding async-iterator demand. */
+export interface IdleWatchdog {
+    /** Stable signal aborted by upstream cancellation or this watchdog's timeout. */
+    readonly signal: AbortSignal;
+    /**
+     * Await one iterator demand while the idle timer is armed.
+     * @param iterator - iterator whose next value represents provider progress.
+     * @returns the iterator's next result.
+     */
+    next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>;
+    /** Rearm an outstanding demand after transport activity that yields no iterator value; otherwise a no-op. */
+    pulse(): void;
+    /** Clear an armed timer; safe to call once at the owning stream's exit. */
+    [Symbol.dispose](): void;
+}
+/**
+ * Fuse upstream cancellation with an identifiable timeout. `timeoutMs <= 0` is
+ * the internal no-timer sentinel; the returned disposer clears an armed timer.
+ * The signal only notifies, so callers must stop their own work.
+ *
+ * @param upstream The caller's cancellation signal, if any, fused into the result.
+ * @param timeoutMs Deadline in milliseconds; `<= 0` means "no timeout" (arm no timer).
+ * @param code Capability-owned code stamped onto the timeout's {@link TimeoutReason}.
+ * @returns The fused {@link Deadline} (signal + timer cleanup).
+ */
+export declare function deadline(upstream: AbortSignal | undefined, timeoutMs: number, code: string): Deadline;
+/**
+ * Create a rearmable idle watchdog for an async iterator. The timer exists only
+ * while {@link IdleWatchdog.next} is outstanding, so consumer think time does
+ * not count as provider idle time. The returned signal is stable for the whole
+ * call and only notifies; the iterator must observe it to terminate its work.
+ *
+ * @param upstream - caller cancellation fused into the stable signal.
+ * @param timeoutMs - positive finite idle interval in milliseconds.
+ * @param code - capability-owned code carried by the timeout reason.
+ * @returns a stable signal, guarded next operation, and timer disposer.
+ */
+export declare function idleWatchdog(upstream: AbortSignal | undefined, timeoutMs: number, code: string): IdleWatchdog;
+/**
+ * Recover a timeout reason from a reason-bearing object. Supplying `code`
+ * distinguishes this deadline from a nested upstream deadline; a foreign code
+ * follows the ordinary cancellation path.
+ *
+ * @param x An {@link AbortSignal} or any `{ reason }` carrier (e.g. a caught abort error).
+ * @param code When provided, only a {@link TimeoutReason} with this exact `code` matches.
+ * @returns The matching {@link TimeoutReason}, else `undefined`.
+ */
+export declare function timeoutOf(x: AbortSignal | {
+    reason?: unknown;
+}, code?: string): TimeoutReason | undefined;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-timeout`.
+ * @module @deepseek-ai/dsh-timeout/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "timeout-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,42 @@
+{
+  "name": "@deepseek-ai/dsh-timeout",
+  "description": "Zero-dependency timeout/deadline primitive: clampTimeout, deadline, timeoutOf, TimeoutReason (timing + classification only, no termination)",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/timeout"
+  },
+  "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": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+  }
+}