@migor/agentia 0.9.4 → 0.10.0

package/dist/core/run.d.ts

@@ -6,11 +6,65 @@ import type { SpanError } from './trace.js';
  * store / transport / runtime 都要读它，下沉 core 后三者都不必再向上引 runtime
  * （此前 `store → runtime` 是未声明的兄弟层依赖，见 AGENTS.md 分层约定）。
  *
- * `awaiting_approval`（HITL）：run 在等人审批 —— **非终态**（awaitTask 继续轮询）、
- * 不占并发槽（执行段落已收尾释放）、`resumePending` 不捡走（它不是孤儿，崩溃续跑语义
- * 不适用于「在等人」）；消息历史（含未决 tool_use）与待决清单随 TaskRecord 落库。
+ * `suspended`：run **挂起了** —— **非终态**（awaitTask 继续轮询）、不占并发槽（执行段落已
+ * 收尾释放）、`resumePending` 不捡走（它不是孤儿，崩溃续跑语义不适用于「在等」）；
+ * 消息历史（含未决 tool_use）与待决清单随 TaskRecord 落库。
+ *
+ * 「挂起」是**一个状态 + 一个原因**（2026-09-28 ①：从前 `awaiting_approval` 一个状态兼职
+ * 两件事）：状态只说「它在等」，等什么由 `SuspendedReason` 说 —— 判据（审批超时 / 能否
+ * 审批）落在**原因**上，于是「时间挂起被审批超时提前叫醒」这类误伤在类型上就写不出来。
+ */
+export type RunStatus = 'queued' | 'running' | 'suspended' | 'succeeded' | 'failed'
+/**
+ * 被**取消**（宿主调 `runner.cancel`）—— 终态，但与 `failed` **分开**：
+ * 取消不是失败（引擎侧 `abortedResult` 的注释早就这么写），运维读数不该把
+ * 「人按的」与「跑挂的」混成一类（`GROUP BY status` 是第一读者）。
+ * 机制上是 `abort signal`（与 `runTimeoutMs` 同一条），差别在**意图** ——
+ * 状态按意图落：超时仍是 `failed`。
+ *
+ * ⚠️ **可达性如实（外部深评 K3）**：这个成员**由宿主落**（`TaskRecord.status`），
+ * 进程内 `Run` **到不了它** —— 引擎侧的取消表现为 `stopReason: 'aborted'`，
+ * `Run.finish()` 按 `isSuccessStopReason` 判 ⇒ 记 `failed`（带结构化
+ * `error.type: 'aborted'`）。同一份联合类型有**两个消费者、可达集不同**，这是有意的：
+ * `TaskRecord` 是运维读数（「人按的」与「跑挂的」必须分得开，`GROUP BY status` 是第一读者），
+ * 而 `Run` 是进程内状态机（只关心跑没跑完）。要加状态时**先想清是给谁的**。
+ */
+ | 'cancelled';
+/**
+ * 挂起原因 —— 「等人工审批」与「等一个时刻」是两种挂起，判据必须分开：
+ *   approval —— 等人工决定（HITL）：`approve()` 能叫醒它，`approvalTimeoutMs` 管它；
+ *   timer    —— 等一个时刻（durable timer）：只有到点能叫醒它。
+ * ⚠️ 拿 timer 挂起去撞 `approvalTimeoutMs` = **提前叫醒一条在睡的 run** ——
+ * 那两条闸（`approvalExpired` / `approve` 的 409）因此都 gate 在原因上，不 gate 在状态上。
  */
-export type RunStatus = 'queued' | 'running' | 'awaiting_approval' | 'succeeded' | 'failed';
+export type SuspendedReason = 'approval' | 'timer';
+/** 该状态是否已到终态（不会再变）。判定只此一处 —— 别在调用点重写。 */
+export declare function isTerminalStatus(status: RunStatus): boolean;
+/**
+ * run 事件（2026-09-28 ⑥，run 事件投入口）：外部系统投给一条**挂起** run 的一条输入
+ * （`AsyncRunner.signalTask` / `POST /tasks/:id/events`；审批是它的特例）。
+ *
+ * 白名单形状（设计稿 B1）：**全是字符串** —— 外部永远不能构造消息块，投毒面只到
+ * 「内容注入」为止（任意 `MessageParam` 透传 = 把伪造 assistant / tool_use 块的能力
+ * 交给外部，那是协议注入，明确不做）。续跑段由引擎把它渲染成**一条 user 文本消息**
+ * 注入消息流（见 `engine/resume-input.ts` 的 `renderTaskEvent` 与 `engine/loop.ts`）。
+ *
+ * 与 `transport/task-events.ts` 的 `TaskStreamEvent` 不是一回事：那个是**记账事件流**
+ * 的一帧（出站，`GET /tasks/:id/stream`），这个是**入站**输入。
+ */
+export interface TaskEvent {
+    /**
+     * 幂等键（可选）：给了就按它去重 —— 同一任务重复投递同一个 eventId ⇒ 409
+     * （与 cancel 的「已终态」同款：说出来，不静默）。去重簿记随 TaskRecord 落库
+     * （`deliveredEventIds`，有界 FIFO），跨进程/重启不丢。
+     * **不给则没有恰好一次**：重复投递 = 重复进消息历史（如实文档化，不假装）。
+     */
+    eventId?: string | undefined;
+    /** 事件类型（非空字符串，如 `payment.settled`）—— 进渲染文本与 trace 留痕 */
+    type: string;
+    /** 事件正文（字符串）。HTTP 侧的字节上限与 `maxBodyBytes` 同口径（整个 body 那一道闸） */
+    payload: string;
+}
 /**
  * run 的运行记录（供持久化 / 读取）。字段**必填但可为 undefined**：它们是框架在 run
  * 生命周期各阶段**总是写进对象**的状态（`toMeta()` 一次构造全量），「缺省」在这里不是
@@ -26,4 +80,14 @@ export interface RunMeta {
     startedAt: number | undefined;
     finishedAt: number | undefined;
     error: SpanError | undefined;
+    /**
+     * 挂起原因（仅 `status === 'suspended'` 时非空）—— 「字段在场」约定同 `error`：
+     * 它是 run 生命周期里**总会写进对象**的状态位，缺省在这里没有语义。
+     */
+    suspendedReason: SuspendedReason | undefined;
+    /**
+     * 时间挂起的目标时刻（epoch ms，仅 `suspendedReason === 'timer'` 时非空；字段在场约定同上）
+     * —— 「这条 run 什么时候该醒」是运行记录的一部分，与「在等什么」并列。
+     */
+    wakeAt: number | undefined;
 }

package/dist/core/run.js

@@ -1,2 +1,28 @@
-export {};
+/**
+ * `RunStatus` → 「是不是终态」的**唯一真源**（2026-09-28 外部深评 S1）。
+ *
+ * 为什么要有它：这个判定此前**散在三处各写一遍**，而且写法不同——
+ * `transport/async.ts` 的 `isTerminalTask` 是 `status !== 'queued' && …`（负向枚举
+ * 非终态），`store/redisStore.ts` 施加 TTL 时压根判都不判（于是**挂起中也照样过期**：
+ * 一条在等审批的任务，TTL 一到记录就没了，「批了它」的决定无家可归 —— 与
+ * `InMemoryTaskStore.evict` 里那句「suspended 不可淘汰」正好相反）。谁都没错，
+ * 合起来是错的：**同一事实的两份读数**。
+ *
+ * 形状取**穷尽的分类表**而不是负向枚举：往 `RunStatus` 加成员而不在这里表态 ⇒
+ * `tsc` 报缺属性（`TS2741`，与 `stop-reason.ts` 的分类表同款）。负向枚举会让新成员
+ * **静默变成「终态」**——那正是「挂起中的任务被当成跑完了」那类 bug 的来源。
+ */
+const TERMINAL_STATUS = {
+    queued: false,
+    running: false,
+    // 挂起**不是**终态：批了（或睡到点）它会接着跑
+    suspended: false,
+    succeeded: true,
+    failed: true,
+    cancelled: true,
+};
+/** 该状态是否已到终态（不会再变）。判定只此一处 —— 别在调用点重写。 */
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUS[status];
+}
 //# sourceMappingURL=run.js.map

package/dist/core/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/core/run.ts"],"names":[],"mappings":""}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/core/run.ts"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;GAaG;AACH,MAAM,eAAe,GAA+B;IAClD,MAAM,EAAE,KAAK;IACb,OAAO,EAAE,KAAK;IACd,2BAA2B;IAC3B,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,IAAI;IACf,MAAM,EAAE,IAAI;IACZ,SAAS,EAAE,IAAI;CAChB,CAAC;AAEF,yCAAyC;AACzC,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAChD,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC"}

package/dist/core/schema.js

@@ -1,4 +1,17 @@
 import { stringifySafe } from './json.js';
+/**
+ * `check()` 的**递归深度背板**（2026-09-28 外部深评 C6 收口）。
+ *
+ * 这道闸只管一件事：**别让递归钻到 V8 的栈溢出**（`RangeError: Maximum call stack size exceeded`
+ * 的症状没有辨识度 —— 调用方看到的是「校验不了」，而不是「这个 schema 有问题」）。
+ * 环本身由 `assertNoSchemaCycle()`（前置、与值深度无关）具名抓出来；这里只兜「合法但深到失控」
+ * 那种形态（要手搓几千层嵌套 schema 才够，属于事故级输入）。
+ *
+ * 256 的判据：真实 tool schema 的深度是**个位数**，256 是它的两个数量级以上 ⇒ 不误伤；
+ * 而 V8 的栈在几千帧量级 ⇒ 256 足够早地拦住。**数量有界不是用户旋钮**，不进 `core/limits.ts`
+ * 的 0 语义表（与 `MAX_DELIVERED_EVENT_IDS` / `MAX_PENDING_EVENTS` 同档）。
+ */
+const MAX_SCHEMA_DEPTH = 256;
 /**
  * Agentia —— 最小 JSON Schema 校验子集（v1 裸 JSON Schema；zod 为可选外挂，
  * 见 toolkit/zod.ts —— schema 上挂 __zodValidate 时先走它，core 本身不依赖 zod）。
@@ -21,18 +34,56 @@ export function validateJsonSchema(schema, input) {
         if (err)
             return `$: ${err}`;
     }
-    return check(schema, input, '$');
+    assertNoSchemaCycle(schema);
+    return check(schema, input, '$', 0);
 }
-function check(schema, value, path) {
+/**
+ * **前置环检测**：`properties` / `items` / `additionalProperties` 这几条边里有环 ⇒ 具名报错。
+ *
+ * 为什么不是「只靠深度闸」：递归深度 = min(schema 深度, 值深度)，所以**环 + 浅值**根本不会爆栈
+ * （照常校验通过）—— 那是作者的一个合法但可疑的写法，不该被当成「输入非法」。真正要防的是
+ * 环**配深值**时钻进栈溢出，而那件事用深度闸只能兜住症状；这里直接点出病根（哪条路径上是环）。
+ *
+ * 用**祖先集**而不是全局 visited：共享子树（DAG，`{a: s, b: s}` 这种）是合法写法，不能报环。
+ */
+function assertNoSchemaCycle(root) {
+    const ancestors = new Set();
+    const walk = (schema, path) => {
+        if (typeof schema !== 'object' || schema === null || Array.isArray(schema))
+            return;
+        if (ancestors.has(schema)) {
+            throw new Error(`schema 里有**环**（循环引用）：${path} 又指回了它自己的祖先。` +
+                '这会按值深度一路递归下去 —— 深值就是 RangeError: Maximum call stack size exceeded。' +
+                '修法：把自引用那段拆成不带环的子 schema，或改成显式的深度上限。');
+        }
+        ancestors.add(schema);
+        const s = schema;
+        for (const [key, sub] of Object.entries(s.properties ?? {})) {
+            walk(sub, `${path}.properties.${key}`);
+        }
+        if (s.items !== undefined)
+            walk(s.items, `${path}.items`);
+        if (typeof s.additionalProperties === 'object') {
+            walk(s.additionalProperties, `${path}.additionalProperties`);
+        }
+        ancestors.delete(schema);
+    };
+    walk(root, '$');
+}
+function check(schema, value, path, depth = 0) {
+    if (depth > MAX_SCHEMA_DEPTH) {
+        throw new Error(`schema 递归超过 ${MAX_SCHEMA_DEPTH} 层（路径 ${path}）—— 校验在这里中止。` +
+            '（环由 assertNoSchemaCycle 前置抓；这里兜的是「合法但深到失控」的形态。）');
+    }
     const en = schema.enum;
     if (Array.isArray(en) && !en.some((v) => deepEqual(v, value))) {
         return `${path}: 值不在 enum 允许范围内（得到 ${preview(value)}）`;
     }
     switch (schema.type) {
         case 'object':
-            return checkObject(schema, value, path);
+            return checkObject(schema, value, path, depth);
         case 'array':
-            return checkArray(schema, value, path);
+            return checkArray(schema, value, path, depth);
         case 'string':
             return typeof value === 'string' ? null : `${path}: 期望 string，得到 ${typeOf(value)}`;
         case 'number':
@@ -51,7 +102,7 @@ function check(schema, value, path) {
             return null; // 未声明/未覆盖的 type 放行
     }
 }
-function checkObject(schema, value, path) {
+function checkObject(schema, value, path, depth) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         return `${path}: 期望 object，得到 ${typeOf(value)}`;
     }
@@ -64,7 +115,7 @@ function checkObject(schema, value, path) {
     const properties = schema.properties ?? {};
     for (const [key, sub] of Object.entries(properties)) {
         if (Object.hasOwn(obj, key)) {
-            const err = check(sub, obj[key], `${path}.${key}`);
+            const err = check(sub, obj[key], `${path}.${key}`, depth + 1);
             if (err)
                 return err;
         }
@@ -78,13 +129,13 @@ function checkObject(schema, value, path) {
     }
     return null;
 }
-function checkArray(schema, value, path) {
+function checkArray(schema, value, path, depth) {
     if (!Array.isArray(value))
         return `${path}: 期望 array，得到 ${typeOf(value)}`;
     const items = schema.items;
     if (items && typeof items === 'object' && !Array.isArray(items)) {
         for (let i = 0; i < value.length; i++) {
-            const err = check(items, value[i], `${path}[${i}]`);
+            const err = check(items, value[i], `${path}[${i}]`, depth + 1);
             if (err)
                 return err;
         }

package/dist/core/schema.js.map

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

package/dist/core/timeout.d.ts

@@ -6,10 +6,52 @@
  * 2026-09-14 的「硬保证」收紧只落进了 `engine/concurrency.ts`，桥那一份继续用竞速判定 ——
  * 同一个承诺两套实现，于是同一个事件在 trace 里能有两种账（见 `docs/spec.md` §10 2026-09-17 ①）。
  * `integrations` 只能依赖 core（`tests/architecture/layering.test.ts` 强制），
- * 所以单源的落点是 core。core 是叶子：本文件零 import。
+ * 所以单源的落点是 core。core 是叶子：本文件只 import `limits.js`（**纯数据表，零 import**）
+ * —— 2026-09-28 起它要 `zeroClauseOf`：两处 `assertTimerDelay` 的文案必须与 limits 表同源
+ * （外部深评 C3/C4 的「单源断了一头」）。叶子性没变：数据表不引入任何运行期依赖，也不成环。
  */
 /** 超时哨兵：区分「超时」与「工具恰好返回了 undefined」 */
 export declare const TIMED_OUT: unique symbol;
+/**
+ * Node 定时器延迟的**物理上限**：`2^31-1` ms（约 **24.86 天**）。
+ *
+ * 为什么它必须是单源（而不是各调用点各写一份）：超过这个值的延迟**不会「等那么久」** ——
+ * Node 只会在 stderr 留一行 `TimeoutOverflowWarning`（`Timeout duration was set to 1`），
+ * 然后把延迟**钳到 1ms**。于是「30 天后触发」变成「立刻触发」、「退避到限流窗口之后」
+ * 变成「热重试打风暴」。实测（Node 22）：`delay = 2^31` 在 200ms 内触发并打警告，
+ * 而 `delay = 2^31-1`（边界内）如期不触发。
+ *
+ * 本仓此前的处置是**每个旋钮各自设防**（`transport/scheduler.ts` 的 every/at 各一条，
+ * 2026-09-19 复审加的），而「派生出来的等待」没有 —— 那些正是漏网的部分：
+ * `withTimeout`（引擎 `toolTimeoutMs`）、`interruptibleSleep`（退避）、
+ * `DrainGate.waitForIdle`（drain 预算）、`#raceTimeout`（`runTimeoutMs`）、
+ * `composeSignal`（client `timeout`）五处都直喂 `setTimeout` 且只查「非负有限」。
+ * 单源收在这里（见 `docs/spec.md` §10 2026-09-28 ⑪）。
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * 校验一个**将要喂给 `setTimeout` 的延迟**：`NaN` 与超过 [MAX_TIMER_DELAY_MS] 一律抛。
+ *
+ * 「拒绝」而不是「钳制」是刻意的 —— 钳制正是 Node 现在做的事（钳到 1ms），
+ * 它把「远期」静默变成「立即」，是本条要消灭的那种失败模式。照 `Scheduler.at`
+ * 的既有先例：超上限直接抛，让使用者在配置处就看见（远期等待请拆成多次自检）。
+ *
+ * ⚠️ **非正数不在此列**：`0` / 负数在调用点各有合法语义（「不设超时」/「一直等」/「不睡」），
+ * 各按 `core/limits.ts` 的表读 —— 本函数只挡「物理上兑现不了」的值。
+ * ⚠️ `NaN` 单独判并**必须排在调用点的「非正」早返回之前**：`!(NaN > 0)` 与 `NaN <= 0`
+ * 都不成立或都成立得不一致，不先挡就会被静默读成另一种语义（见 `withTimeout` 处的注释）。
+ */
+export declare function assertTimerDelay(ms: number, where: string): number;
+/**
+ * 把**外部数据**得出的延迟夹进可兑现区间（`retry-after` 等）。
+ *
+ * 与 [assertTimerDelay] 的分工是刻意的、别合并：
+ * - 那个「**拒绝**」使用者配出来的坏值 —— 配置错误必须响亮，否则修法会被写歪；
+ * - 这个「**夹**」上游回给我们的值 —— `Retry-After: 99999999` 不是使用者的错，
+ *   为它抛错会把一次 429 升级成硬失败；但放它直通 `setTimeout` 会钳到 1ms，
+ *   把「等限流窗口过去」变成「热重试」，那才是真危害。
+ */
+export declare function clampTimerDelay(ms: number): number;
 /**
  * 超时错误（`code === 'timeout'`）。
  *

package/dist/core/timeout.js

@@ -6,10 +6,68 @@
  * 2026-09-14 的「硬保证」收紧只落进了 `engine/concurrency.ts`，桥那一份继续用竞速判定 ——
  * 同一个承诺两套实现，于是同一个事件在 trace 里能有两种账（见 `docs/spec.md` §10 2026-09-17 ①）。
  * `integrations` 只能依赖 core（`tests/architecture/layering.test.ts` 强制），
- * 所以单源的落点是 core。core 是叶子：本文件零 import。
+ * 所以单源的落点是 core。core 是叶子：本文件只 import `limits.js`（**纯数据表，零 import**）
+ * —— 2026-09-28 起它要 `zeroClauseOf`：两处 `assertTimerDelay` 的文案必须与 limits 表同源
+ * （外部深评 C3/C4 的「单源断了一头」）。叶子性没变：数据表不引入任何运行期依赖，也不成环。
  */
+import { zeroClauseOf } from './limits.js';
 /** 超时哨兵：区分「超时」与「工具恰好返回了 undefined」 */
 export const TIMED_OUT = Symbol('agentia.timed-out');
+/**
+ * Node 定时器延迟的**物理上限**：`2^31-1` ms（约 **24.86 天**）。
+ *
+ * 为什么它必须是单源（而不是各调用点各写一份）：超过这个值的延迟**不会「等那么久」** ——
+ * Node 只会在 stderr 留一行 `TimeoutOverflowWarning`（`Timeout duration was set to 1`），
+ * 然后把延迟**钳到 1ms**。于是「30 天后触发」变成「立刻触发」、「退避到限流窗口之后」
+ * 变成「热重试打风暴」。实测（Node 22）：`delay = 2^31` 在 200ms 内触发并打警告，
+ * 而 `delay = 2^31-1`（边界内）如期不触发。
+ *
+ * 本仓此前的处置是**每个旋钮各自设防**（`transport/scheduler.ts` 的 every/at 各一条，
+ * 2026-09-19 复审加的），而「派生出来的等待」没有 —— 那些正是漏网的部分：
+ * `withTimeout`（引擎 `toolTimeoutMs`）、`interruptibleSleep`（退避）、
+ * `DrainGate.waitForIdle`（drain 预算）、`#raceTimeout`（`runTimeoutMs`）、
+ * `composeSignal`（client `timeout`）五处都直喂 `setTimeout` 且只查「非负有限」。
+ * 单源收在这里（见 `docs/spec.md` §10 2026-09-28 ⑪）。
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * 校验一个**将要喂给 `setTimeout` 的延迟**：`NaN` 与超过 [MAX_TIMER_DELAY_MS] 一律抛。
+ *
+ * 「拒绝」而不是「钳制」是刻意的 —— 钳制正是 Node 现在做的事（钳到 1ms），
+ * 它把「远期」静默变成「立即」，是本条要消灭的那种失败模式。照 `Scheduler.at`
+ * 的既有先例：超上限直接抛，让使用者在配置处就看见（远期等待请拆成多次自检）。
+ *
+ * ⚠️ **非正数不在此列**：`0` / 负数在调用点各有合法语义（「不设超时」/「一直等」/「不睡」），
+ * 各按 `core/limits.ts` 的表读 —— 本函数只挡「物理上兑现不了」的值。
+ * ⚠️ `NaN` 单独判并**必须排在调用点的「非正」早返回之前**：`!(NaN > 0)` 与 `NaN <= 0`
+ * 都不成立或都成立得不一致，不先挡就会被静默读成另一种语义（见 `withTimeout` 处的注释）。
+ */
+export function assertTimerDelay(ms, where) {
+    if (Number.isNaN(ms)) {
+        throw new RangeError(`${where} 不能是 NaN —— 它既不是「不限」也不是任何时长，` +
+            `静默接受会把它读成另一件事（各旋钮 0 的含义见 core/limits.ts 的表）`);
+    }
+    if (ms > MAX_TIMER_DELAY_MS) {
+        throw new RangeError(`${where} 超过 Node 定时器延迟上限 ${MAX_TIMER_DELAY_MS}ms（约 24.86 天），收到 ${ms} —— ` +
+            `超上限的延迟不会被遵守：Node 只在 stderr 留一行 TimeoutOverflowWarning，` +
+            `随后把延迟钳到 1ms（远期变立即）。远期等待请拆成多次自检`);
+    }
+    return ms;
+}
+/**
+ * 把**外部数据**得出的延迟夹进可兑现区间（`retry-after` 等）。
+ *
+ * 与 [assertTimerDelay] 的分工是刻意的、别合并：
+ * - 那个「**拒绝**」使用者配出来的坏值 —— 配置错误必须响亮，否则修法会被写歪；
+ * - 这个「**夹**」上游回给我们的值 —— `Retry-After: 99999999` 不是使用者的错，
+ *   为它抛错会把一次 429 升级成硬失败；但放它直通 `setTimeout` 会钳到 1ms，
+ *   把「等限流窗口过去」变成「热重试」，那才是真危害。
+ */
+export function clampTimerDelay(ms) {
+    if (!(ms > 0))
+        return 0; // 含 NaN / 负数：调用点读 0 即「不睡」（见 limits 表）
+    return ms > MAX_TIMER_DELAY_MS ? MAX_TIMER_DELAY_MS : ms;
+}
 /**
  * 超时错误（`code === 'timeout'`）。
  *
@@ -91,6 +149,12 @@ export function isTimeoutError(e) {
  * SSE 心跳、metrics 刷盘）成立，对**「等待的终点」**不成立：那正是调用方在等的东西。
  */
 export async function withTimeout(p, timeoutMs) {
+    // 坏值先挡（NaN / 超 2^31-1，见 assertTimerDelay）。⚠️ 必须排在下面那句
+    // 「非正 = 不设超时」**之前**：那句的判据是 `!(timeoutMs > 0)`，而 NaN 满足它
+    // ⇒ 会被**静默**读成「不设超时」，与使用者「我设了个预算」的预期正好相反
+    // （桥还会因此起自己的 60s 兜底 ⇒ 双计时器、双账本，见 limits 表 withTimeout.ms 的 note）。
+    // `0` / 负数不在此列 —— 它们是合法的「不设超时」，走下面那句原样透传。
+    assertTimerDelay(timeoutMs, `withTimeout 的 timeoutMs（引擎 toolTimeoutMs / 桥兜底超时；${zeroClauseOf('withTimeout.ms')}）`);
     if (!(timeoutMs > 0))
         return p;
     // 单调钟（performance.now）：硬超时判定看的是**耗时**，墙钟（Date.now）会被
@@ -158,6 +222,11 @@ export async function withTimeout(p, timeoutMs) {
  * 曾把它当「一致性缺口」改反过一次，被这条用例拦住 —— 保留该用例，别删。
  */
 export function interruptibleSleep(ms, signal, abortMessage = '已被取消') {
+    // 坏值先挡（NaN / 超 2^31-1）：这句**先于**下面的 `ms <= 0`，因为 `NaN <= 0` 是 false
+    // —— 它会穿透那句直落 `setTimeout(fn, NaN)`，被 Node 钳成 1ms ⇒「退避」静默变成
+    // 「立刻重试」；超上限同理（钳到 1ms）。`0` / 负数仍是合法的「不睡」，
+    // 且「先于 aborted 检查」那条次序（被用例钉着）不受影响 —— 见函数头注释。
+    assertTimerDelay(ms, `interruptibleSleep 的 ms（重试退避；${zeroClauseOf('interruptibleSleep.ms')}）`);
     if (ms <= 0)
         return Promise.resolve();
     return new Promise((resolve, reject) => {
@@ -195,11 +264,15 @@ export function interruptibleSleep(ms, signal, abortMessage = '已被取消') {
 export function backoffMs(attempt, retryAfter) {
     if (retryAfter) {
         const secs = Number(retryAfter);
+        // ⚠️ `retry-after` 是**上游数据**，可以大到兑现不了（`Retry-After: 99999999` ⇒ 1e11 ms）。
+        // 这里走 clampTimerDelay（夹）而不是 assertTimerDelay（拒）：为上游的荒谬值把一次 429
+        // 升级成硬失败是错的；而放它直通 setTimeout 会被钳到 1ms，把「等限流窗口过去」
+        // 变成「热重试打风暴」—— 那才是真危害。两条分支都要夹（HTTP-date 可以指到几个月后）。
         if (Number.isFinite(secs))
-            return Math.max(0, Math.round(secs * 1000));
+            return clampTimerDelay(Math.max(0, Math.round(secs * 1000)));
         const at = Date.parse(retryAfter);
         if (Number.isFinite(at))
-            return Math.max(0, at - Date.now());
+            return clampTimerDelay(Math.max(0, at - Date.now()));
         // 解析不了就回落指数退避
     }
     const base = Math.min(500 * 2 ** Math.max(0, attempt - 1), 8000);

package/dist/core/timeout.js.map

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

package/dist/core/tool.d.ts

@@ -169,6 +169,14 @@ export interface ToolRunContext {
      * 不设（undefined）= 子循环用各自缺省（不是"不截断"）。
      */
     maxEventChars?: number | false;
+    /**
+     * 本 run 是否记录 assistant 文本进 llm.turn span（`RunAgentOptions.traceContent`，R8-P3a）。
+     * 嵌套能力（@SubAgent / @Skill）拉起自己的 llm 循环时必须原样传下去 —— 否则同一棵
+     * 调用树上主 agent 的回合有 `output.text`、子 agent 的没有（与 maxEventChars 同理由）。
+     *
+     * 不设（undefined）= 子循环不记录（缺省行为）。
+     */
+    traceContent?: 'full';
     /**
      * 成本硬管控（C1）透传：整条 run 累计 token 上限（见 `RunAgentOptions.maxTotalTokens`）。
      * 嵌套能力（@SubAgent / @Skill）拉起自己的 llm 循环时必须原样传下去 —— 预算是
@@ -184,6 +192,22 @@ export interface ToolRunContext {
      * 批准/拒绝（审计日志、按 decidedBy 分级授权等）。
      */
     approval?: ApprovalDecision;
+    /**
+     * 「现在还不是时候，T 之后再问我」（durable timer，2026-09-28 ① 的 timer 侧）。
+     * 工具在执行期调用它 = 请求**本回合到此为止**：引擎丢弃本回合这批工具的结果、
+     * 把整批 tool_use 挂起（`stopReason: 'suspended'` + `suspendedReason: 'timer'` +
+     * 目标时刻 `wakeAt`），到点后由宿主续跑并**重跑这一批**（与审批续跑的形态一致）。
+     * 真实用途：等批处理作业、等限流窗口、等收盘、等外部系统回填。
+     *
+     * ⚠️ 两条契约（都是「说错就静默出事」的位置，细则见 `engine/defer.ts`）：
+     * ① **必须传将来的时刻**：T ≤ 现在（或非有限数）**当场抛 TypeError** —— 那次工具调用以
+     *    is_error 的 tool_result 回给模型、run 照常往前走（不挂起）。否则到期扫描会立刻
+     *    唤醒、重跑、工具再请求同一个过去时刻＝一条自己打转的 run。
+     * ② **整批语义**：挂起是回合级的（协议要求每个 tool_use 都有配对 tool_result），
+     *    所以同回合**已经执行完**的其他工具会在醒来后重跑（副作用重复）—— 要精确控制就让
+     *    模型单独调它，或把它做成幂等读。本回合多个请求取**最早**的那个时刻。
+     */
+    deferUntil?: (at: number | Date) => void;
     /**
      * 工具执行被引擎**放弃等待**的信号（`toolTimeoutMs` 超时触发）。
      *
@@ -225,7 +249,7 @@ export interface AgentTool<I = unknown, O = unknown> {
     strict?: boolean;
     /**
      * 人工审批闸（HITL）：`'required'` 时模型发起的该工具调用**不直接执行** ——
-     * 该回合挂起（`stopReason: 'awaiting_approval'`，回合级全有或全无：同一回合的
+     * 该回合挂起（`stopReason: 'suspended'`，回合级全有或全无：同一回合的
      * 其他工具也一并等待，因为协议要求每个 tool_use 都有配对 tool_result），
      * 等宿主把决定（`ApprovalDecision`，按 tool_use_id）喂回来后恢复：
      * 批准 → 正常执行（工具体内经 `ToolRunContext.approval` 读到自己的决定）；

package/dist/core/trace.d.ts

@@ -25,6 +25,34 @@ export interface SpanError {
     /** 是否可安全重试（429/5xx/网络 vs 400/400类） */
     retryable: boolean;
 }
+/**
+ * 工具**入参**事件的 `SpanEvent.name`（`TOOL_OUTPUT_EVENT` 是它的另一半）。
+ *
+ * 为什么单源在 `core/`（2026-09-28 外部深评 E8）：这两个名字跨 **engine → eval →
+ * integrations** 三层被手写（12 处取值）—— 改名要改三遍，而漏一处不是「少记一条」，
+ * 是**静默归零**：事件在引擎里叫 A、报表按 B 过滤 ⇒ 报表说「没有工具调用」，而 trace 里
+ * 明明有（`integrations/report.ts` 与 `metrics-state.ts` 那两处都按名字过滤）。
+ *
+ * ⚠️ 报告建议的落点（`engine/tool-events.ts`，与载荷构造器同处）**不可行**：
+ * `integrations` 只许依赖 `core`（`tests/architecture/layering.test.ts`），拿不到 engine 的
+ * 导出 —— 那样 integrations 侧只能再手写一份，等于把「单源」补成「两处」。
+ * 所以词汇表落在最底层：**载荷构造器（engine）与名字（core）分开**，谁都能引。
+ */
+export declare const TOOL_INPUT_EVENT = "tool.input";
+export declare const TOOL_OUTPUT_EVENT = "tool.output";
+/**
+ * 「上游**没回报 usage**」事件名（2026-09-28 外部深评 S2）。
+ *
+ * 为什么也单源在这里：与上面那两条同一理由 —— 名字是跨层契约。写它的是
+ * `engine/turn.ts`，按名字数的是 `integrations/report.ts` 与 `metrics-state.ts`。
+ * 手写三遍 ⇒ 一处改名就是**静默归零**（报表说「没有缺失」，而 trace 里明明有）。
+ *
+ * 语义：该回合的上游响应**没有**带 token 计量，于是 `MessageUsage` 里那几个 `0` 是
+ * **替身值**（不是读数）—— 成本估算会把它读成「真的花了 0」，`maxCostUsd` 因此静默失效。
+ */
+export declare const USAGE_MISSING_EVENT = "usage.missing";
+/** 工具 I/O 事件名的联合 —— `eval/export.ts` 的工具事件过滤器按它取参数 */
+export type ToolIoEventName = typeof TOOL_INPUT_EVENT | typeof TOOL_OUTPUT_EVENT;
 /**
  * 结构化事件（日志）。工具入参/出参**正文默认截断**（入参/成功出参 2000 字符、失败出参 1000），
  * 完整正文需显式开启：`RunInvocationOptions.maxEventChars: false`（缺省关）。
@@ -32,6 +60,11 @@ export interface SpanError {
  */
 export interface SpanEvent {
     time: number;
+    /**
+     * 事件名。工具 I/O 的两条走 `TOOL_INPUT_EVENT` / `TOOL_OUTPUT_EVENT` 常量
+     * （见上：这个名字是跨层契约，不许在别处再写一遍字面量）；
+     * 其余（`'compaction'` 等）目前仍是字面量，尚未单源 —— 如实记在这里，别当已成网。
+     */
     name: string;
     body: unknown;
 }
@@ -168,7 +201,7 @@ export declare function attachScore(trace: Trace, score: Score): void;
 export declare function capabilityKindOf(span: Span): string;
 /**
  * trace 出口：run 收尾（成功或失败）后，框架把【完整 Trace】交给每个 sink。
- * sink 抛错由框架吞掉，绝不影响 run 结果（与 memory 回写同款防护）。
+ * sink 抛错由框架吞掉（吞之前落一条 console.warn 告警），绝不影响 run 结果（与 memory 回写同款防护）。
  * 形状与 OtlpExporter 一致 —— createOtlpExporter() 的返回值天然满足本接口。
  */
 export interface TraceSink {
@@ -189,6 +222,12 @@ export interface TraceSink {
  * ⇒ 这条不变量一次钉住四件事：不丢、不重、顺序正确、增量与终态同源。要改记账点而不派发事件，
  * 那个用例会红。
  *
+ * ⚠️ **没有例外**（2026-09-28 PR #164 复核 §4 定的口径）：截断簿记（`traceLimits.maxEvents`
+ * 超限时 run 根上的 `trace.truncated`）也走**普通 `span.event` 帧**，因此同样折得出来。
+ * 「只在一条缝上出现的事件」正是让这条规则变成假话的方式 —— 判据是「两处同一份载荷」，
+ * 不是「哪条缝更需要它」。折叠侧的类型分派是**编译期穷尽**的（新帧类型会编译失败，
+ * 而不是被当成 `span.link` 静默吞掉）。
+ *
  * `seq`：recorder 内**每次记账动作都自增**（与当时有没有订阅者无关）—— 于是「订阅早」与
  * 「订阅晚」看到的同一个事件序号一致。SSE 的 `Last-Event-ID` 重放、去重、跨段对齐都靠它。
  *

package/dist/core/trace.js

@@ -2,6 +2,32 @@
  * Agentia —— Trace / 调用树 类型草稿。
  * 设计见 docs/spec.md §9。一次 run == 一条 trace（v1 中 traceId == runId）。
  */
+/**
+ * 工具**入参**事件的 `SpanEvent.name`（`TOOL_OUTPUT_EVENT` 是它的另一半）。
+ *
+ * 为什么单源在 `core/`（2026-09-28 外部深评 E8）：这两个名字跨 **engine → eval →
+ * integrations** 三层被手写（12 处取值）—— 改名要改三遍，而漏一处不是「少记一条」，
+ * 是**静默归零**：事件在引擎里叫 A、报表按 B 过滤 ⇒ 报表说「没有工具调用」，而 trace 里
+ * 明明有（`integrations/report.ts` 与 `metrics-state.ts` 那两处都按名字过滤）。
+ *
+ * ⚠️ 报告建议的落点（`engine/tool-events.ts`，与载荷构造器同处）**不可行**：
+ * `integrations` 只许依赖 `core`（`tests/architecture/layering.test.ts`），拿不到 engine 的
+ * 导出 —— 那样 integrations 侧只能再手写一份，等于把「单源」补成「两处」。
+ * 所以词汇表落在最底层：**载荷构造器（engine）与名字（core）分开**，谁都能引。
+ */
+export const TOOL_INPUT_EVENT = 'tool.input';
+export const TOOL_OUTPUT_EVENT = 'tool.output';
+/**
+ * 「上游**没回报 usage**」事件名（2026-09-28 外部深评 S2）。
+ *
+ * 为什么也单源在这里：与上面那两条同一理由 —— 名字是跨层契约。写它的是
+ * `engine/turn.ts`，按名字数的是 `integrations/report.ts` 与 `metrics-state.ts`。
+ * 手写三遍 ⇒ 一处改名就是**静默归零**（报表说「没有缺失」，而 trace 里明明有）。
+ *
+ * 语义：该回合的上游响应**没有**带 token 计量，于是 `MessageUsage` 里那几个 `0` 是
+ * **替身值**（不是读数）—— 成本估算会把它读成「真的花了 0」，`maxCostUsd` 因此静默失效。
+ */
+export const USAGE_MISSING_EVENT = 'usage.missing';
 /** 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})$/;
 /**

package/dist/core/trace.js.map

@@ -1 +1 @@
-{"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;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,MAAc;IAC/D,OAAO,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC;AAC/D,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;AAgDD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAkD,EAClD,MAAmD;IAEnD,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,IAAI,CAAC;YACH,KAAK,CAAC,CAAC,CAAC,CAAC;QACX,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;QACD,IAAI,CAAC;YACH,MAAM,CAAC,CAAC,CAAC,CAAC;QACZ,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ;QACV,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"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"}