@migor/agentia 0.6.0 → 0.6.2

package/dist/core/abort.js

@@ -10,7 +10,10 @@
 const cleanups = new WeakMap();
 /** 合成多个中断源：任一已中止 / 后中止即中止；忽略 undefined；全空返回**永不中止**的 signal。 */
 export function combineSignals(...signals) {
-    const real = signals.filter((s) => s !== undefined);
+    // 去重：同一个源被传两次时，下面的 listeners Map 按源建（后者覆盖前者），
+    // 却对同一源挂了两个同名监听 ⇒ 摘除只摘掉一个，另一个（连闭包）滞留在宿主级
+    // 长寿 signal 上 —— 正是这段代码要防的累积。Set 保序，行为不变。
+    const real = [...new Set(signals.filter((s) => s !== undefined))];
     // 单源直接复用，避免多包一层 listener
     if (real.length === 1)
         return real[0];

package/dist/core/abort.js.map

@@ -1 +1 @@
-{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/core/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gEAAgE;AAChE,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA2B,CAAC;AAExD,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,GAAG,OAAuC;IACvE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACtE,yBAAyB;IACzB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IAEtC,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACnB,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,+CAA+C;QAC/C,gDAAgD;QAChD,iDAAiD;QACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;QACrD,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,SAAS;gBAAE,CAAC,CAAC,mBAAmB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAClE,SAAS,CAAC,KAAK,EAAE,CAAC;YAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,GAAS,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACzC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACpB,CAAC,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAmB;IACvD,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/core/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gEAAgE;AAChE,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA2B,CAAC;AAExD,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,GAAG,OAAuC;IACvE,8CAA8C;IAC9C,yCAAyC;IACzC,0CAA0C;IAC1C,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC;IACpF,yBAAyB;IACzB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IAEtC,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACnB,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,+CAA+C;QAC/C,gDAAgD;QAChD,iDAAiD;QACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;QACrD,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,SAAS;gBAAE,CAAC,CAAC,mBAAmB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAClE,SAAS,CAAC,KAAK,EAAE,CAAC;YAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,GAAS,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACzC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACpB,CAAC,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAmB;IACvD,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;AAC3B,CAAC"}

package/dist/core/sse.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Agentia —— SSE 逐行分帧（**单源**）。
+ *
+ * Anthropic 与 OpenAI 兼容端点的事件流都是「一行一条 `data:`」（不需要处理跨行
+ * payload），两个适配器此前各写了一份**逐字相同**的 `sseLines`。合并的意义不止整洁：
+ * `finally` 里的 `reader.cancel()` 是「提前 break（abort / `[DONE]`）时底层流仍被回收」
+ * 的唯一保证 —— 这份代码在两处各存一份，漏改一处就是一处泄漏（读锁不释放，连接挂着）。
+ *
+ * 只做分帧，不解释协议：空行照常 yield，是不是 `data:` 前缀、要不要认 `[DONE]`
+ * 全由调用方判。
+ *
+ * core 是叶子层：本文件零 import（只用全局的 `ReadableStream` / `TextDecoder`）。
+ */
+export declare function sseLines(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;

package/dist/core/sse.js

@@ -0,0 +1,45 @@
+/**
+ * Agentia —— SSE 逐行分帧（**单源**）。
+ *
+ * Anthropic 与 OpenAI 兼容端点的事件流都是「一行一条 `data:`」（不需要处理跨行
+ * payload），两个适配器此前各写了一份**逐字相同**的 `sseLines`。合并的意义不止整洁：
+ * `finally` 里的 `reader.cancel()` 是「提前 break（abort / `[DONE]`）时底层流仍被回收」
+ * 的唯一保证 —— 这份代码在两处各存一份，漏改一处就是一处泄漏（读锁不释放，连接挂着）。
+ *
+ * 只做分帧，不解释协议：空行照常 yield，是不是 `data:` 前缀、要不要认 `[DONE]`
+ * 全由调用方判。
+ *
+ * core 是叶子层：本文件零 import（只用全局的 `ReadableStream` / `TextDecoder`）。
+ */
+export async function* sseLines(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            let idx = buf.indexOf('\n');
+            while (idx >= 0) {
+                yield buf.slice(0, idx).replace(/\r$/, '');
+                buf = buf.slice(idx + 1);
+                idx = buf.indexOf('\n');
+            }
+        }
+        // 末尾没有换行收尾的残行也要交出去（不是所有端点都补 \n）
+        if (buf)
+            yield buf.replace(/\r$/, '');
+    }
+    finally {
+        // 提前 break（abort / [DONE]）时释放读锁，否则流不会被回收
+        try {
+            await reader.cancel();
+        }
+        catch {
+            /* 已结束/已取消 */
+        }
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/core/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/core/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAAC,IAAgC;IAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/C,IAAI,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC5B,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;gBAChB,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC3C,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;gBACzB,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QACD,gCAAgC;QAChC,IAAI,GAAG;YAAE,MAAM,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACxC,CAAC;YAAS,CAAC;QACT,yCAAyC;QACzC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,aAAa;QACf,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/core/stats.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Agentia —— 统计小工具（**单源**）。
+ *
+ * `percentile` 此前在 `integrations/metrics.ts`（直方图窗口的分位，导出给看板）与
+ * `integrations/report.ts`（时长报告的 p50/p95）各有一份。两处口径**必须**一致
+ * （都取 Prometheus 语义的「最近 rank」），分开演化就会出现「看板 p95 ≠ 报告 p95」——
+ * 同一条 trace、两个数，用户无从判断该信哪个。
+ *
+ * 入参是**已排序**数组：排序成本留给调用方决定 —— metrics 每次要复制滑动窗口再排，
+ * report 只排一次复用给 p50/p95。本函数不替它们做这个选择。
+ *
+ * core 是叶子层：本文件零 import。
+ */
+/**
+ * 分位数：取 `ceil(q · n)` 处的样本（Prometheus 的 quantile 语义 —— 不是线性插值）。
+ * 空数组返回 0；`rank` 钳到 `[1, n]`，所以 `q=0` 也返回最小样本，不会越界读 `-1`。
+ */
+export declare function percentile(sorted: readonly number[], q: number): number;

package/dist/core/stats.js

@@ -0,0 +1,24 @@
+/**
+ * Agentia —— 统计小工具（**单源**）。
+ *
+ * `percentile` 此前在 `integrations/metrics.ts`（直方图窗口的分位，导出给看板）与
+ * `integrations/report.ts`（时长报告的 p50/p95）各有一份。两处口径**必须**一致
+ * （都取 Prometheus 语义的「最近 rank」），分开演化就会出现「看板 p95 ≠ 报告 p95」——
+ * 同一条 trace、两个数，用户无从判断该信哪个。
+ *
+ * 入参是**已排序**数组：排序成本留给调用方决定 —— metrics 每次要复制滑动窗口再排，
+ * report 只排一次复用给 p50/p95。本函数不替它们做这个选择。
+ *
+ * core 是叶子层：本文件零 import。
+ */
+/**
+ * 分位数：取 `ceil(q · n)` 处的样本（Prometheus 的 quantile 语义 —— 不是线性插值）。
+ * 空数组返回 0；`rank` 钳到 `[1, n]`，所以 `q=0` 也返回最小样本，不会越界读 `-1`。
+ */
+export function percentile(sorted, q) {
+    if (sorted.length === 0)
+        return 0;
+    const rank = Math.ceil(q * sorted.length);
+    return sorted[Math.min(Math.max(rank, 1), sorted.length) - 1];
+}
+//# sourceMappingURL=stats.js.map

package/dist/core/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/core/stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,EAAE,CAAS;IAC7D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAE,CAAC;AACjE,CAAC"}

package/dist/core/text.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Agentia —— 消息文本读取（**单源**）。
+ *
+ * 合并三处同形实现：`integrations/anthropic.ts` 与 `integrations/openai.ts` 的
+ * 「非流式回落路径」各有一份 `join('')`，`engine/turn.ts` 有一份 `join('\n')`。
+ * 三份长得一样、只差一个连接符 —— 这不是巧合，是同一个语义在三处各自推导了一遍，
+ * 任何后续修正（例如「空文本块不该产生分隔符」）都只会落到其中一处。
+ *
+ * 为什么不放进 `core/message.ts`：那个文件**刻意**是「零依赖纯类型文件」
+ * （见其头注：编译后全部擦除、import 它零运行时成本）。为一个 8 行函数破掉这条性质
+ * 不划算 —— 类型在 `message.ts`、取值函数在这儿，两边各守一个职责。
+ *
+ * `separator` 是**调用方语义**，不是格式细节：
+ * - `''`（适配器）：回落的原文本来就是一整段，拼回去要与流式累积的文本逐字一致；
+ * - `'\n'`（引擎）：多文本块是模型分段的输出，拼成 `finalText` 要保住分段。
+ */
+import type { Message } from './message.js';
+/** 取消息里的全部文本块，按 `separator` 连接（无文本块 → 空串） */
+export declare function textOf(message: Pick<Message, 'content'>, separator: string): string;

package/dist/core/text.js

@@ -0,0 +1,8 @@
+/** 取消息里的全部文本块，按 `separator` 连接（无文本块 → 空串） */
+export function textOf(message, separator) {
+    return message.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join(separator);
+}
+//# sourceMappingURL=text.js.map

package/dist/core/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/core/text.ts"],"names":[],"mappings":"AAkBA,6CAA6C;AAC7C,MAAM,UAAU,MAAM,CAAC,OAAiC,EAAE,SAAiB;IACzE,OAAO,OAAO,CAAC,OAAO;SACnB,MAAM,CAAC,CAAC,CAAC,EAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,CAAC,SAAS,CAAC,CAAC;AACrB,CAAC"}

package/dist/core/timeout.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Agentia —— 「等待的终点」超时原语（**单源**）。
+ *
+ * 为什么在 core：engine 的工具级超时（`engine/turn.ts`）与桥的 MCP 调用超时
+ * （`integrations/mcp.ts`）**必须共用同一套判定**。此前两处各写一份，代价是
+ * 2026-09-14 的「硬保证」收紧只落进了 `engine/concurrency.ts`，桥那一份继续用竞速判定 ——
+ * 同一个承诺两套实现，于是同一个事件在 trace 里能有两种账（见 `docs/spec.md` §10 2026-09-17 ①）。
+ * `integrations` 只能依赖 core（`tests/architecture/layering.test.ts` 强制），
+ * 所以单源的落点是 core。core 是叶子：本文件零 import。
+ */
+/** 超时哨兵：区分「超时」与「工具恰好返回了 undefined」 */
+export declare const TIMED_OUT: unique symbol;
+/**
+ * 超时错误（`code === 'timeout'`）。
+ *
+ * 为什么需要它：超时此前只能靠**错误文案**辨认 —— 桥抛的是普通 `Error`，而
+ * `classifyError` 里没有 timeout 这一类，于是 trace 里记成 `error(unknown)` +
+ * `errorKind=threw`，与引擎自己判的超时（`error(timeout)` + `errorKind=timeout`）
+ * 成为同一事件的**两种账**（见 `docs/spec.md` §10 2026-09-17 ①）。
+ *
+ * 判定契约（对使用者可见）：**任何** `code === 'timeout'` 的错误都会被引擎归为
+ * `errorKind='timeout'`，不需要 import 这个类（`isTimeoutError` 也认鸭子类型）。
+ */
+export declare class TimeoutError extends Error {
+    readonly code: 'timeout';
+    constructor(message: string);
+}
+/**
+ * 是否超时错误。三条判据（任一条成立即算，**全部是鸭子类型** —— 使用者不必 import 本模块）：
+ *
+ * 1. 本模块的 `TimeoutError` 实例（框架自己判的超时，如 MCP 桥的兜底）；
+ * 2. `code === 'timeout'`（工具作者自报超时的推荐写法）；
+ * 3. 内建 `DOMException` 的 `name === 'TimeoutError'` —— `AbortSignal.timeout()` 与默认 client 的
+ *    超时合成信号（`integrations/anthropic.ts` 的 `composeSignal`）产出的就是它，`name` 是规范值、
+ *    不受压缩影响。
+ *
+ * 为什么第 3 条也算：`engine/errors.ts` 的分类**此前只有它**认这一条（当时把超时归进 `connection`），
+ * 于是「超时」在 trace 里混在「连不上」里，看板与 `trace-diff` 分不出两者。现在超时有自己的
+ * `type: 'timeout'`，这条判据由分类与工具级记账**共用**，口径一致（spec §10 2026-09-17 ②）。
+ */
+export declare function isTimeoutError(e: unknown): boolean;
+/**
+ * 给一个 promise 套超时；超时返回 `TIMED_OUT`。
+ *
+ * ⚠️ **不取消底层** —— `AgentTool.run` 拿不到 signal（那会破坏现有签名），所以
+ * 「超时」的语义是**放弃等待**：副作用可能已经发生，只是我们不等了。
+ * 想真停下来的工具请自行读 `ToolRunContext.signal`（框架传了，但**不强制**工具中断
+ * —— 见 core/tool.ts 的说明：工具副作用无法回滚）。
+ *
+ * **超时是硬的**（2026-09-14 收紧，见 `docs/spec.md` §10）：判定不看竞速结果，而看**实测耗时**。
+ * 原因：`Promise.race` 不是硬保证 —— 两个计时器在同一毫秒内建、又因事件循环被饿住而同批到期时，
+ * 列表顺序决定谁先 resolve，**超预算的工具能赢过截止计时器**（实测 `60ms 工具 vs 20ms 预算`
+ * 在 8 倍 CPU 超订下 1200 次翻转 1 次，记成 `ok: true`，护栏静默失效）。
+ * 代价是语义收紧：`21ms 完成 / 20ms 预算` 由「成功」变「超时」—— 这正确，
+ * 「预算」本来就是对**实际耗时**的承诺，不是对调度运气的承诺。
+ *
+ * `timeoutMs` 非正数 = 不设超时（直接返回原 promise）。
+ *
+ * ⚠️ **截止计时器绝不可 `unref()`**（2026-09-14 修正，见 `docs/spec.md` §10 ④）：
+ * 这个计时器的**触发本身就是「被 await 的 promise 得以 settle」的条件**。一旦 unref，
+ * 当它是事件循环里唯一的把手时，进程会在它触发前直接退出 —— `await` **永不 settle**。
+ * 实测（空事件循环、挂死的 promise，Node 22 与 26 一个样）：
+ *
+ * | 计时器 | 结果 |
+ * |---|---|
+ * | `unref()` | 进程退出（顶层 await 未 settle），**什么都没返回** |
+ * | 不 unref | `settled: TIMED_OUT`，exit 0 |
+ *
+ * 「兜底计时器不该让宿主为它续命」这条理由对**没人 await 的兜底 tick**（scheduler 的下一拍、
+ * SSE 心跳、metrics 刷盘）成立，对**「等待的终点」**不成立：那正是调用方在等的东西。
+ */
+export declare function withTimeout<T>(p: Promise<T>, timeoutMs: number): Promise<T | typeof TIMED_OUT>;
+/**
+ * 可被 signal 中断的 sleep（**单源**）。
+ *
+ * 合并两处逐字相同的实现：`engine/retry.ts` 的 `sleep`（重试退避期间收到取消就
+ * 不必再等）与 `integrations/anthropic.ts` 的 `interruptibleSleep`（client 层退避）。
+ * 那边此前自带一段「与 engine/retry.ts 的 sleep 同语义但不复用它 —— 分层约束：
+ * integrations 只能依赖 core」的注解：**正是那条约束把两份代码逼成了重复**，
+ * 所以下沉到 core 是让它们合一的唯一合法落点（见 spec §10 2026-09-17 ① 的单源化口径）。
+ *
+ * ⚠️ 只合并这个 sleep，**不合并退避计算器**：engine 是 ±20% 均匀抖动、client 是
+ * ±25% 且额外尊重 `retry-after`。函数体相同、策略不同 —— 合策略会真改行为。
+ *
+ * `abortMessage` 参数化而非统一：文案是**调用方语境**（引擎说「run 已被取消」，
+ * client 说「请求已被取消」），两者都会出现在用户眼前的报错里。为去重把两句话
+ * 改成一句，是拿可读性换整洁度。
+ *
+ * 抛的是 `name === 'AbortError'` 的错误（而非 `TimeoutError`）：取消不是超时，
+ * `engine/errors.ts` 按 `name` 把它归进「已中止」，`loop` 据此以 `aborted` 收尾。
+ */
+export declare function interruptibleSleep(ms: number, signal?: AbortSignal, abortMessage?: string): Promise<void>;

package/dist/core/timeout.js

@@ -0,0 +1,157 @@
+/**
+ * Agentia —— 「等待的终点」超时原语（**单源**）。
+ *
+ * 为什么在 core：engine 的工具级超时（`engine/turn.ts`）与桥的 MCP 调用超时
+ * （`integrations/mcp.ts`）**必须共用同一套判定**。此前两处各写一份，代价是
+ * 2026-09-14 的「硬保证」收紧只落进了 `engine/concurrency.ts`，桥那一份继续用竞速判定 ——
+ * 同一个承诺两套实现，于是同一个事件在 trace 里能有两种账（见 `docs/spec.md` §10 2026-09-17 ①）。
+ * `integrations` 只能依赖 core（`tests/architecture/layering.test.ts` 强制），
+ * 所以单源的落点是 core。core 是叶子：本文件零 import。
+ */
+/** 超时哨兵：区分「超时」与「工具恰好返回了 undefined」 */
+export const TIMED_OUT = Symbol('agentia.timed-out');
+/**
+ * 超时错误（`code === 'timeout'`）。
+ *
+ * 为什么需要它：超时此前只能靠**错误文案**辨认 —— 桥抛的是普通 `Error`，而
+ * `classifyError` 里没有 timeout 这一类，于是 trace 里记成 `error(unknown)` +
+ * `errorKind=threw`，与引擎自己判的超时（`error(timeout)` + `errorKind=timeout`）
+ * 成为同一事件的**两种账**（见 `docs/spec.md` §10 2026-09-17 ①）。
+ *
+ * 判定契约（对使用者可见）：**任何** `code === 'timeout'` 的错误都会被引擎归为
+ * `errorKind='timeout'`，不需要 import 这个类（`isTimeoutError` 也认鸭子类型）。
+ */
+export class TimeoutError extends Error {
+    code = 'timeout';
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+/**
+ * 是否超时错误。三条判据（任一条成立即算，**全部是鸭子类型** —— 使用者不必 import 本模块）：
+ *
+ * 1. 本模块的 `TimeoutError` 实例（框架自己判的超时，如 MCP 桥的兜底）；
+ * 2. `code === 'timeout'`（工具作者自报超时的推荐写法）；
+ * 3. 内建 `DOMException` 的 `name === 'TimeoutError'` —— `AbortSignal.timeout()` 与默认 client 的
+ *    超时合成信号（`integrations/anthropic.ts` 的 `composeSignal`）产出的就是它，`name` 是规范值、
+ *    不受压缩影响。
+ *
+ * 为什么第 3 条也算：`engine/errors.ts` 的分类**此前只有它**认这一条（当时把超时归进 `connection`），
+ * 于是「超时」在 trace 里混在「连不上」里，看板与 `trace-diff` 分不出两者。现在超时有自己的
+ * `type: 'timeout'`，这条判据由分类与工具级记账**共用**，口径一致（spec §10 2026-09-17 ②）。
+ */
+export function isTimeoutError(e) {
+    if (e instanceof TimeoutError)
+        return true;
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const o = e;
+    return o.code === 'timeout' || o.name === 'TimeoutError';
+}
+/**
+ * 给一个 promise 套超时；超时返回 `TIMED_OUT`。
+ *
+ * ⚠️ **不取消底层** —— `AgentTool.run` 拿不到 signal（那会破坏现有签名），所以
+ * 「超时」的语义是**放弃等待**：副作用可能已经发生，只是我们不等了。
+ * 想真停下来的工具请自行读 `ToolRunContext.signal`（框架传了，但**不强制**工具中断
+ * —— 见 core/tool.ts 的说明：工具副作用无法回滚）。
+ *
+ * **超时是硬的**（2026-09-14 收紧，见 `docs/spec.md` §10）：判定不看竞速结果，而看**实测耗时**。
+ * 原因：`Promise.race` 不是硬保证 —— 两个计时器在同一毫秒内建、又因事件循环被饿住而同批到期时，
+ * 列表顺序决定谁先 resolve，**超预算的工具能赢过截止计时器**（实测 `60ms 工具 vs 20ms 预算`
+ * 在 8 倍 CPU 超订下 1200 次翻转 1 次，记成 `ok: true`，护栏静默失效）。
+ * 代价是语义收紧：`21ms 完成 / 20ms 预算` 由「成功」变「超时」—— 这正确，
+ * 「预算」本来就是对**实际耗时**的承诺，不是对调度运气的承诺。
+ *
+ * `timeoutMs` 非正数 = 不设超时（直接返回原 promise）。
+ *
+ * ⚠️ **截止计时器绝不可 `unref()`**（2026-09-14 修正，见 `docs/spec.md` §10 ④）：
+ * 这个计时器的**触发本身就是「被 await 的 promise 得以 settle」的条件**。一旦 unref，
+ * 当它是事件循环里唯一的把手时，进程会在它触发前直接退出 —— `await` **永不 settle**。
+ * 实测（空事件循环、挂死的 promise，Node 22 与 26 一个样）：
+ *
+ * | 计时器 | 结果 |
+ * |---|---|
+ * | `unref()` | 进程退出（顶层 await 未 settle），**什么都没返回** |
+ * | 不 unref | `settled: TIMED_OUT`，exit 0 |
+ *
+ * 「兜底计时器不该让宿主为它续命」这条理由对**没人 await 的兜底 tick**（scheduler 的下一拍、
+ * SSE 心跳、metrics 刷盘）成立，对**「等待的终点」**不成立：那正是调用方在等的东西。
+ */
+export async function withTimeout(p, timeoutMs) {
+    if (!(timeoutMs > 0))
+        return p;
+    const startedAt = Date.now();
+    // 在**工具 settle 的那个微任务里**记时间，而不是 `await` 恢复之后再记：
+    // 微任务紧跟在 resolve 它的那次回调之后跑，所以这个时刻最贴近「工具真正完成」。
+    // 若改成 await 恢复后再测，宿主在「工具完成 → 恢复」之间被饿住会把按时完成的工具误判成超时。
+    let settledAt = 0;
+    const tracked = p.then((v) => {
+        settledAt = Date.now();
+        return v;
+    }, (e) => {
+        settledAt = Date.now();
+        throw e;
+    });
+    let timer;
+    try {
+        const out = await Promise.race([
+            tracked,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+                // ⚠️ 不 unref：它的触发是「这个 await 得以结束」的条件（详见函数头注释的实测表）。
+                // unref 过它 ⇒ 空事件循环下进程先退出，await 永不 settle。
+            }),
+        ]);
+        // 竞速只当快路径；最终以实测耗时兜底判定（见上面注释里的翻转样本）。
+        if (out === TIMED_OUT)
+            return TIMED_OUT;
+        return settledAt - startedAt >= timeoutMs ? TIMED_OUT : out;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * 可被 signal 中断的 sleep（**单源**）。
+ *
+ * 合并两处逐字相同的实现：`engine/retry.ts` 的 `sleep`（重试退避期间收到取消就
+ * 不必再等）与 `integrations/anthropic.ts` 的 `interruptibleSleep`（client 层退避）。
+ * 那边此前自带一段「与 engine/retry.ts 的 sleep 同语义但不复用它 —— 分层约束：
+ * integrations 只能依赖 core」的注解：**正是那条约束把两份代码逼成了重复**，
+ * 所以下沉到 core 是让它们合一的唯一合法落点（见 spec §10 2026-09-17 ① 的单源化口径）。
+ *
+ * ⚠️ 只合并这个 sleep，**不合并退避计算器**：engine 是 ±20% 均匀抖动、client 是
+ * ±25% 且额外尊重 `retry-after`。函数体相同、策略不同 —— 合策略会真改行为。
+ *
+ * `abortMessage` 参数化而非统一：文案是**调用方语境**（引擎说「run 已被取消」，
+ * client 说「请求已被取消」），两者都会出现在用户眼前的报错里。为去重把两句话
+ * 改成一句，是拿可读性换整洁度。
+ *
+ * 抛的是 `name === 'AbortError'` 的错误（而非 `TimeoutError`）：取消不是超时，
+ * `engine/errors.ts` 按 `name` 把它归进「已中止」，`loop` 据此以 `aborted` 收尾。
+ */
+export function interruptibleSleep(ms, signal, abortMessage = '已被取消') {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const abortError = () => Object.assign(new Error(abortMessage), { name: 'AbortError' });
+        // 已中止：立即 reject（此处 timer 尚未创建，绝不能去 clear）
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        function onAbort() {
+            clearTimeout(timer);
+            reject(abortError());
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=timeout.js.map

package/dist/core/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../../src/core/timeout.ts"],"names":[],"mappings":"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"}

package/dist/core/tool.d.ts

@@ -117,6 +117,17 @@ export interface ToolRunContext {
      * 模型在子循环里会退化成"未定价"（成本恒 0，`maxCostUsd` 静默失效）。
      */
     priceOverrides?: Record<string, ModelPricing>;
+    /**
+     * 本次工具调用的**引擎侧预算**（毫秒）= 本次 run 的 `RunAgentOptions.toolTimeoutMs`；
+     * undefined / 非正 = 引擎不设超时。
+     *
+     * 存在的意义是**划定裁判权**：工具（尤其带自己计时器的桥，见 `integrations/mcp.ts`）
+     * 据此知道「这次调用的超时由引擎判」，从而不再启动第二个计时器 —— 两个计时器判同一件事，
+     * 只会得到两种账（桥那份曾被记成 `error(unknown)` + `errorKind=threw`，见 spec §10 2026-09-17 ①）。
+     *
+     * ⚠️ 它是本次调用的**配置值**，不是「剩余时间」。
+     */
+    toolTimeoutMs?: number;
     /**
      * trace 事件正文的截断上限（见 `RunAgentOptions.maxEventChars`）。嵌套能力
      * （@SubAgent / @Skill）拉起自己的 llm 循环时必须原样传下去，否则**同一棵调用树

package/dist/core/trace.d.ts

@@ -35,6 +35,41 @@ export interface SpanEvent {
     name: string;
     body: unknown;
 }
+/**
+ * 触发来源的链路上下文（跨进程 / 跨服务关联，spec §9.2）。
+ *
+ * 语义是**入站**的：调用方（HTTP 网关、队列消费者、上游服务）把它自己的 span 标识
+ * 传进来，本次 run 的根 span 会把它记成一条 `SpanLink` 指回去 —— 于是「这条 run 是被
+ * 谁触发的」在两个系统之间可查。
+ *
+ * ⚠️ **不改变 `traceId == runId` 的 1:1 不变量**：run 仍是自己的一棵新树，上游只是被
+ * **链接**、不是被**继承**成父 span。所以一次 run 的调用树永远自洽（不依赖上游是否
+ * 还在、是否被采样掉），而因果关系仍然成立。
+ */
+export interface TraceContext {
+    /** 上游 trace id：32 位 hex（W3C traceparent）或 UUID（带 '-'）两种形态都接受 */
+    traceId: string;
+    /** 上游 span id（16 位 hex）；缺省表示只知道 trace 粒度、没有具体 span */
+    spanId?: string;
+}
+/**
+ * 一条链路引用：指向**另一个** trace 里的 span（OTLP 的 span links 同语义）。
+ * v1 只在 run 根 span 上写入（来源是 `RunInvocationOptions.traceContext`）。
+ */
+export interface SpanLink {
+    traceId: TraceId;
+    spanId?: SpanId;
+}
+/**
+ * 解析 W3C `traceparent` 头（spec §9.2 的「header 语义」）。这是入站唯一的字符串形态
+ * —— 宿主从 HTTP 头 / 队列消息属性里取到它，直接交给 `RunInvocationOptions.traceContext`。
+ *
+ * **非法或缺失一律返回 `undefined`**（调用方据此当作「没有上游上下文」继续跑）：
+ * 链路关联是观测行为，不该因为一个畸形头把业务请求打成 400。被拒的形态有：
+ * 版本 `ff`（W3C 保留为非法）、trace/span id 全零、位宽不符、大小写之外的畸形。
+ * 版本号非 `00` 时按 W3C「兼容未来」规则接受（只认前四段语义）。
+ */
+export declare function parseTraceparent(value: string | null | undefined): TraceContext | undefined;
 export interface Span {
     spanId: SpanId;
     traceId: TraceId;
@@ -45,6 +80,12 @@ export interface Span {
     endedAt?: number;
     status: SpanStatus;
     error?: SpanError;
+    /**
+     * 跨 trace 的链路引用（v1 只出现在 run 根 span 上，见 `TraceContext`）。
+     * 缺席（而不是空数组）表示「没有上游上下文」—— 与 links 为空的 span 是同一件事，
+     * 不要据此区分「没传」和「传了但为空」。
+     */
+    links?: SpanLink[];
     /**
      * usage —— 语义按 kind 区分：
      * - `llm.turn`：该次模型往返的**自身计量**，是 Trace.totalUsage 的唯一来源；
@@ -83,6 +124,19 @@ export interface Score {
  * 出口映射：OTLP 导出时译为 `gen_ai.evaluation.result` 事件，metricsSink 聚合为 score 指标族。
  */
 export declare function attachScore(trace: Trace, score: Score): void;
+/**
+ * 能力 span 的类型标签：`attributes.skill` 有值 → `'skill'`，`attributes.subagent` 有值
+ * → `'subagent'`，否则 `'capability'`（`SpanKind` 的第三个取值，也是 span 的 kind）。
+ *
+ * 放在本文件（而不是各出口里）：`skill` / `subagent` 这两个 attribute 名是
+ * `toolkit/skill.ts`、`toolkit/subagent.ts` 与本类型之间的共同契约 —— 判定写在契约
+ * 定义处，两个出口（`metrics.ts` 的指标 label、`report.ts` 的能力排行）只消费结论。
+ * 此前两处各有一份同形实现，加起来是**同一件事的三个定义**。
+ *
+ * 返回 `string` 而非 `CapabilityType`：`'capability'` 不在 `CapabilityType`
+ * （那是「菜单四类能力」的口径）里，两者刻意不混。
+ */
+export declare function capabilityKindOf(span: Span): string;
 /**
  * trace 出口：run 收尾（成功或失败）后，框架把【完整 Trace】交给每个 sink。
  * sink 抛错由框架吞掉，绝不影响 run 结果（与 memory 回写同款防护）。

package/dist/core/trace.js

@@ -2,6 +2,30 @@
  * Agentia —— Trace / 调用树 类型草稿。
  * 设计见 docs/spec.md §9。一次 run == 一条 trace（v1 中 traceId == runId）。
  */
+/** W3C traceparent：`<2位版本>-<32位trace>-<16位span>-<2位flags>`，全小写 hex */
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+/**
+ * 解析 W3C `traceparent` 头（spec §9.2 的「header 语义」）。这是入站唯一的字符串形态
+ * —— 宿主从 HTTP 头 / 队列消息属性里取到它，直接交给 `RunInvocationOptions.traceContext`。
+ *
+ * **非法或缺失一律返回 `undefined`**（调用方据此当作「没有上游上下文」继续跑）：
+ * 链路关联是观测行为，不该因为一个畸形头把业务请求打成 400。被拒的形态有：
+ * 版本 `ff`（W3C 保留为非法）、trace/span id 全零、位宽不符、大小写之外的畸形。
+ * 版本号非 `00` 时按 W3C「兼容未来」规则接受（只认前四段语义）。
+ */
+export function parseTraceparent(value) {
+    if (!value)
+        return undefined;
+    const m = TRACEPARENT_RE.exec(value.trim().toLowerCase());
+    if (!m)
+        return undefined;
+    const [, version, traceId, spanId] = m;
+    if (version === 'ff')
+        return undefined;
+    if (/^0+$/.test(traceId) || /^0+$/.test(spanId))
+        return undefined;
+    return { traceId, spanId };
+}
 /**
  * 把评分挂到 trace 根 span（一条 `score` 事件，body 即 Score）。
  * trace 找不到根 span 时静默忽略（观测不击穿业务）；多次调用即多条事件（不同维度各记各的）。
@@ -11,4 +35,23 @@ export function attachScore(trace, score) {
     const root = trace.spans.find((s) => s.spanId === trace.rootSpanId);
     root?.events.push({ time: Date.now(), name: 'score', body: score });
 }
+/**
+ * 能力 span 的类型标签：`attributes.skill` 有值 → `'skill'`，`attributes.subagent` 有值
+ * → `'subagent'`，否则 `'capability'`（`SpanKind` 的第三个取值，也是 span 的 kind）。
+ *
+ * 放在本文件（而不是各出口里）：`skill` / `subagent` 这两个 attribute 名是
+ * `toolkit/skill.ts`、`toolkit/subagent.ts` 与本类型之间的共同契约 —— 判定写在契约
+ * 定义处，两个出口（`metrics.ts` 的指标 label、`report.ts` 的能力排行）只消费结论。
+ * 此前两处各有一份同形实现，加起来是**同一件事的三个定义**。
+ *
+ * 返回 `string` 而非 `CapabilityType`：`'capability'` 不在 `CapabilityType`
+ * （那是「菜单四类能力」的口径）里，两者刻意不混。
+ */
+export function capabilityKindOf(span) {
+    if (span.attributes.skill !== undefined)
+        return 'skill';
+    if (span.attributes.subagent !== undefined)
+        return 'subagent';
+    return 'capability';
+}
 //# sourceMappingURL=trace.js.map

package/dist/core/trace.js.map

@@ -1 +1 @@
-{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuFH;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY,EAAE,KAAY;IACpD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,UAAU,CAAC,CAAC;IACpE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqEH,sEAAsE;AACtE,MAAM,cAAc,GAAG,6DAA6D,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgC;IAC/D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAqDD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY,EAAE,KAAY;IACpD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,UAAU,CAAC,CAAC;IACpE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACzC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACxD,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC9D,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/engine/concurrency.d.ts

@@ -8,36 +8,12 @@
  * `limit` 非正数或非有限值一律视为**不限**（= 旧行为 `Promise.all`）。
  */
 export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
-/** 超时哨兵：区分「超时」与「工具恰好返回了 undefined」 */
-export declare const TIMED_OUT: unique symbol;
 /**
- * 给一个 promise 套超时；超时返回 `TIMED_OUT`。
+ * 超时原语（`TIMED_OUT` 哨兵 + `withTimeout`）已**下沉到 `core/timeout.ts`**：
+ * 它与 `integrations/mcp.ts` 的 MCP 调用超时共用同一实现 —— 此前是两份，而
+ * 「超时是硬的」那次收紧只落进了这里，桥那份留在竞速判定上（见 `docs/spec.md` §10 2026-09-17 ①）。
  *
- * ⚠️ **不取消底层** —— `AgentTool.run` 拿不到 signal（那会破坏现有签名），所以
- * 「超时」的语义是**放弃等待**：副作用可能已经发生，只是我们不等了。
- * 想真停下来的工具请自行读 `ToolRunContext.signal`（框架传了，但**不强制**工具中断
- * —— 见 core/tool.ts 的说明：工具副作用无法回滚）。
- *
- * **超时是硬的**（2026-09-14 收紧，见 `docs/spec.md` §10）：判定不看竞速结果，而看**实测耗时**。
- * 原因：`Promise.race` 不是硬保证 —— 两个计时器在同一毫秒内建、又因事件循环被饿住而同批到期时，
- * 列表顺序决定谁先 resolve，**超预算的工具能赢过截止计时器**（实测 `60ms 工具 vs 20ms 预算`
- * 在 8 倍 CPU 超订下 1200 次翻转 1 次，记成 `ok: true`，护栏静默失效）。
- * 代价是语义收紧：`21ms 完成 / 20ms 预算` 由「成功」变「超时」—— 这正确，
- * 「预算」本来就是对**实际耗时**的承诺，不是对调度运气的承诺。
- *
- * `timeoutMs` 非正数 = 不设超时（直接返回原 promise）。
- *
- * ⚠️ **截止计时器绝不可 `unref()`**（2026-09-14 修正，见 `docs/spec.md` §10 ④）：
- * 这个计时器的**触发本身就是「被 await 的 promise 得以 settle」的条件**。一旦 unref，
- * 当它是事件循环里唯一的把手时，进程会在它触发前直接退出 —— `await` **永不 settle**。
- * 实测（空事件循环、挂死的 promise，Node 22 与 26 一个样）：
- *
- * | 计时器 | 结果 |
- * |---|---|
- * | `unref()` | 进程退出（顶层 await 未 settle），**什么都没返回** |
- * | 不 unref | `settled: TIMED_OUT`，exit 0 |
- *
- * 「兜底计时器不该让宿主为它续命」这条理由对**没人 await 的兜底 tick**（scheduler 的下一拍、
- * SSE 心跳、metrics 刷盘）成立，对**「等待的终点」**不成立：那正是调用方在等的东西。
+ * 这里**原样再导出**：`engine/turn.ts` 与既有测试的 import 路径与名字保持不变，
+ * 单源化对它们零影响。
  */
-export declare function withTimeout<T>(p: Promise<T>, timeoutMs: number): Promise<T | typeof TIMED_OUT>;
+export { TIMED_OUT, withTimeout } from '../core/timeout.js';