@buddhilive/dsh-timeout 0.1.2-alpha.3

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/util/timeout/README.md
+README.md: f446f9b33edad5badc1218802b27547ef116f7db
+README.zh.md: 31b4c4f5d42777b2a2439f85d3d517ec6cd435f9

package/README.md

@@ -0,0 +1,154 @@
+---
+description: "Shared timeout arithmetic, deadline fusion, and timeout-versus-cancel classification for capabilities that clamp a caller's hint, arm a deadline, and must tell the two apart later."
+kind: "package-library"
+---
+
+# @buddhilive/dsh-timeout
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-timeout` lets a capability run one unit of work under a caller-visible timeout and later tell a timeout apart from a cancellation. A caller's optional hint is clamped against a backend default and cap, and upstream cancellation fuses with the deadline into one `AbortSignal`. The deadline signal only notifies — each capability owns the mechanism that stops its work, so no shared layer needs to know how to stop anything. For streamed transports an idle watchdog arms a timeout only while a provider read is outstanding, so consumer think time never counts as idle. A `timeoutMs` of zero is the internal no-timeout sentinel for backend-owned background work, never a public disable switch; the zero-dependency library is shared by the bash, web, subprocess, and tool-timeout-policy consumers.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use `deadline` when a capability runs one unit of work under a caller-visible timeout, and `idleWatchdog` when it reads a streamed transport. Validate caller hints with `clampTimeout` first so the `timeoutMs` that reaches `deadline` is always positive and finite.
+
+### Clamping a timeout hint
+
+```ts
+import { clampTimeout } from '@buddhilive/dsh-timeout'
+
+declare const requested: number | undefined
+declare const DEFAULT_TIMEOUT_MS: number
+declare const MAX_TIMEOUT_MS: number
+
+const timeoutMs = clampTimeout(requested, DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, 'bash-local: request.timeoutMs')
+```
+
+`clampTimeout` fills the backend default when the hint is absent, caps the result at the backend maximum, and rejects a non-positive or non-finite hint with the caller-provided name. Zero is never accepted here: it is not a public disable-timeout value.
+
+### Running work under a deadline
+
+```text
+import { deadline, timeoutOf } from '@buddhilive/dsh-timeout'
+
+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
+const aborted = d.signal.aborted && !timedOut
+```
+
+The signal only notifies: the caller must attach its own termination — hand `d.signal` to `fetch`, or listen for `abort` and kill the child. Racing a promise against a timer would resolve the tool call while the child process or socket leaks on.
+
+### Classifying the outcome
+
+`timeoutOf(signal, code)` recovers the timeout reason only when this deadline's timer fired first. Pass your own `code` so classification composes under nesting: when `upstream` is itself a deadline signal, a foreign timeout reads as an ordinary upstream cancellation instead of claiming that the local timer expired.
+
+### Streaming with an idle watchdog
+
+```ts
+import { idleWatchdog } from '@buddhilive/dsh-timeout'
+
+declare const upstream: AbortSignal | undefined
+declare const idleMs: number
+declare const providerIterator: AsyncIterator<unknown>
+
+using watchdog = idleWatchdog(upstream, idleMs, 'LLM_STREAM_IDLE_TIMEOUT')
+const next = await watchdog.next(providerIterator)    // timer runs only while this read is outstanding
+```
+
+The timer is armed only while an iterator `next()` is outstanding and rearms on `pulse()` for transport activity that yields no value, so consumer think time between reads never counts as idle. The interval must be positive, finite, and no greater than `MAX_TIMER_DELAY_MS`.
+
+### 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.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The library is built on one boundary: share the timing and classification, keep the hard kill local.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `clampTimeout`, `deadline`, `idleWatchdog`, `timeoutOf`, `TimeoutReason`, `MAX_TIMER_DELAY_MS` |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; the timing algebra is exercised by unit tests) |
+
+### How a deadline fuses sources
+
+`deadline` arms one timer and fuses its abort with the upstream signal via `AbortSignal.any`, which adopts the reason of whichever source aborts first — so a race resolves to a single cause. The `TimeoutReason` carries the capability-owned `code` and the elapsed `timeoutMs`; `timeoutOf` reads it only when the timeout won, and upstream-wins leaves an ordinary abort reason. `[Symbol.dispose]` clears the timer.
+
+### The no-timeout sentinel
+
+`timeoutMs <= 0` arms no timer and forwards only the upstream signal — or a never-aborting signal when there is none — so every caller keeps one call shape. The sentinel exists for backend-owned background work; external request hints are validated positive and finite before they reach `deadline`.
+
+### Why an idle watchdog rearms
+
+`idleWatchdog` keeps one stable fused signal and arms the timer only while `next()` is outstanding; resolution disarms, later demand or `pulse()` rearms, disposal clears, and concurrent demand rejects. Only the transport observes the signal, so the provider's real read must listen to it — the DeepSeek and pi-ai adapters close their response body or SDK request on abort.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when you need the consumers or the boundary decision behind the library.
+
+- [Timeout-deadline library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md) — the shared-timing, local-kill boundary.
+- [Tool-call timeout policy](../../guard/timeout-policy/README.md) — the consumer that enforces declared tool timeouts.
+- [Bash provider](../../shell/bash-local/README.md) — a foreground deadline consumer that kills a process group.
+- [Filesystem subsystem](../../../docs/subsystems/filesystem.md) — why local file IO runs untimed.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through the timeout consumers that render timeout outcomes.
+
+#### KV Cache effect
+
+No direct invalidation; the timeout consumers own any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the library deliberately does not do. They are current package constraints, not a task backlog.
+
+- **Notification only** — a deadline cannot stop work that ignores its signal; every capability still needs its own socket, process, or 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- or plugin-facing 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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,154 @@
+---
+description: "共享超时运算、截止时间融合与超时/取消分类，供需要限制调用方提示、启动 deadline 并在之后区分二者的能力使用。"
+kind: "package-library"
+---
+
+# @buddhilive/dsh-timeout
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-timeout` 让能力在调用方可见的超时下运行一个工作单元，之后能把超时与取消区分开。调用方的可选提示会按后端默认值补齐、并按后端上限封顶，上游取消与截止时间融合为一个 `AbortSignal`。deadline 信号只负责通知——停止工作的机制由各能力自己拥有，因此没有任何共享层需要知道如何停止任何东西。对于流式传输，空闲 watchdog 只在提供方读取尚未完成时启动超时，因此消费方的思考时间绝不计入空闲。`timeoutMs` 为 0 是后端自有后台工作使用的内部「无超时」哨兵值，绝不是公开的禁用开关；这个零依赖库由 bash、web、subprocess 与 tool-timeout-policy 消费方共享。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当能力要在调用方可见的超时下运行一个工作单元时使用 `deadline`，读取流式传输时使用 `idleWatchdog`。先用 `clampTimeout` 验证调用方提示，确保到达 `deadline` 的 `timeoutMs` 总是正有限值。
+
+### 限制超时提示
+
+```ts
+import { clampTimeout } from '@buddhilive/dsh-timeout'
+
+declare const requested: number | undefined
+declare const DEFAULT_TIMEOUT_MS: number
+declare const MAX_TIMEOUT_MS: number
+
+const timeoutMs = clampTimeout(requested, DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, 'bash-local: request.timeoutMs')
+```
+
+提示缺失时 `clampTimeout` 填入后端默认值，把结果限制在后端最大值以内，并以调用方提供的名字拒绝非正数或非有限值的提示。此处绝不接受 0：它不是公开的禁用超时值。
+
+### 在 deadline 下运行工作
+
+```text
+import { deadline, timeoutOf } from '@buddhilive/dsh-timeout'
+
+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
+const aborted = d.signal.aborted && !timedOut
+```
+
+该信号只负责通知：调用方必须接入自己的终止机制——把 `d.signal` 传给 `fetch`，或监听 `abort` 并杀死子进程。让 promise 与 timer 竞速，会在子进程或套接字仍在泄漏时就让工具调用完成。
+
+### 分类结果
+
+只有当本 deadline 的 timer 先触发时，`timeoutOf(signal, code)` 才恢复超时原因。传入你自己的 `code`，让分类在嵌套场景中正确组合：当 `upstream` 本身是 deadline 信号时，外部超时会被当作普通的上游取消，而不是声称本地 timer 已到期。
+
+### 用空闲 watchdog 处理流式传输
+
+```ts
+import { idleWatchdog } from '@buddhilive/dsh-timeout'
+
+declare const upstream: AbortSignal | undefined
+declare const idleMs: number
+declare const providerIterator: AsyncIterator<unknown>
+
+using watchdog = idleWatchdog(upstream, idleMs, 'LLM_STREAM_IDLE_TIMEOUT')
+const next = await watchdog.next(providerIterator)    // timer runs only while this read is outstanding
+```
+
+timer 只在某个迭代器 `next()` 尚未完成时启动，并会因不产生值的传输活动通过 `pulse()` 重新启动，因此读取之间的消费方思考时间绝不计入空闲。间隔必须为正有限数，且不得大于 `MAX_TIMER_DELAY_MS`。
+
+### 哪些操作不设置超时
+
+本地文件 `read`/`write`/`edit` 不接受 `timeoutMs`：文件 IO 不设时限地运行，因为截止时间会中止操作系统仍会完成的工作。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本库建立在一个边界之上：共享时序与分类，把强制终止保留在本地。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `clampTimeout`、`deadline`、`idleWatchdog`、`timeoutOf`、`TimeoutReason`、`MAX_TIMER_DELAY_MS` |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；时序运算由单元测试覆盖） |
+
+### deadline 如何融合来源
+
+`deadline` 启动一个 timer，并通过 `AbortSignal.any` 把它与上游信号融合；`AbortSignal.any` 采纳最先中止的来源的原因，因此竞争会归结为单一原因。`TimeoutReason` 携带能力自有的 `code` 与已流逝的 `timeoutMs`；只有当超时胜出时 `timeoutOf` 才读取它，上游胜出则保留普通的中止原因。`[Symbol.dispose]` 清除 timer。
+
+### 无超时哨兵值
+
+`timeoutMs <= 0` 不启动 timer，只转发上游信号——没有上游时返回永不中止的信号——因此每个调用方都保持同一种调用形态。该哨兵值服务于后端自有后台工作；外部请求提示在到达 `deadline` 之前先被验证为正有限值。
+
+### 空闲 watchdog 为何重新启动
+
+`idleWatchdog` 保持一个稳定的融合信号，只在 `next()` 尚未完成时启动 timer；完成后停止，后续需求或 `pulse()` 重新启动，dispose（资源释放）时清除，并发需求被拒绝。只有传输层观察该信号，因此提供方的真实读取必须监听它——DeepSeek 与 pi-ai 适配器会在中止时关闭响应正文或 SDK 请求。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当你需要消费方或库背后的边界决策时，阅读以下页面。
+
+- [超时 deadline 库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.zh.md)——共享时序、本地强制终止的边界。
+- [工具调用超时策略](../../guard/timeout-policy/README.zh.md)——强制执行已声明工具超时的消费方。
+- [bash 提供方](../../shell/bash-local/README.zh.md)——杀死进程组的前台 deadline 消费方。
+- [文件系统子系统](../../../docs/subsystems/filesystem.zh.md)——本地文件 IO 为何不设时限。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过渲染超时结果的超时消费方间接影响模型。
+
+#### KV Cache 影响
+
+不会直接导致失效；请求前缀的任何变更由超时消费方负责。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明本库刻意不做什么。它们是当前包约束，不是任务积压。
+
+- **只发出通知**——deadline 无法停止忽略其信号的工作；每项能力仍需要自己的 socket、进程或任务终止路径。
+- **`timeoutMs <= 0` 是内部词汇**——只有在所属后端已解析策略后，它才会禁用本地 timer；绝不会作为面向模型或插件的公开开关。
+- **第一个中止原因决定分类**——当上游取消早于本地 timer 发生时，即使自己的超时之后也会到期，该层也无法再报告。
+- **空闲 watchdog 不是总 deadline**——它针对每个尚未完成的迭代器需求重新启动，并刻意排除消费方的思考时间。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

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 @buddhilive/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 `@buddhilive/dsh-timeout`.
+* @module @buddhilive/dsh-timeout/invariant
+*/
+const PACKAGE_NAME = "@buddhilive/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 @buddhilive/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 `@buddhilive/dsh-timeout`.
+ * @module @buddhilive/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": "@buddhilive/dsh-timeout",
+  "description": "Zero-dependency timeout/deadline primitive: clampTimeout, deadline, timeoutOf, TimeoutReason (timing + classification only, no termination)",
+  "version": "0.1.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Buddhilive/buddhi-ai-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": "MIT",
+  "peerDependencies": {
+    "@buddhilive/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@buddhilive/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}