@migor/agentia 0.9.4 → 0.9.5

package/dist/engine/defer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 延后请求（durable timer）的**纯判定与收集**：工具说「现在还不是时候，T 之后再问我」。
+ *
+ * 为什么单独成件：这是挂起的第二个**原因**（`core/run.ts` 的 `SuspendedReason` —— timer 侧）。
+ * 它与审批（approval）的关键差别决定了这个文件里的每一条规则：
+ *
+ * | | 审批 | 延后 |
+ * |---|---|---|
+ * | 谁提 | **宿主**在执行前给决定（引擎只查 `args.approvals`） | **工具**在跑的时候提 |
+ * | 判据 | 「决定在不在」（没有就不执行） | 「时刻到了没」（没到就挂起） |
+ * | 非法值 | 不适用（决定是布尔） | **有**：T 在过去 / 非有限数 ⇒ 必须响亮拒绝 |
+ *
+ * 后一行是本文件存在的理由：延后是**工具运行时**提出的，取值就成了一条外部契约。
+ * 让「T ≤ 现在」成立的话，到期扫描读到它会立刻唤醒、续跑、工具再请求同一个过去时刻 ——
+ * **一条自己打转的 run**（每次都不花钱，但 store / trace / 判据全在空转，且永不收尾）。
+ * 所以 `resolveWakeAt` 把「必须在将来」做成**当场抛错**：那次工具调用以 is_error 的
+ * tool_result 回给模型（既有路径），run 照常往前走 —— 不静默、不挂起成僵尸。
+ *
+ * 第二件审批不需要解决的事：**一个回合一挂起**（协议要求每个 tool_use 都有配对的
+ * tool_result），所以同回合的多个延后请求只能合并成一个时刻 —— 取**最早**的那个
+ * （「早醒」是可补救的：醒来看还没到就再请求一次；「晚醒」则白等）。
+ *
+ * 纯的边界：只吃 `(at, now)`，只吐结论；不碰 recorder、不碰 ctx、不改任何 rec。
+ * 时刻口径是**绝对毫秒时间戳**（epoch ms）—— 它要落库、要跨进程比较，相对毫秒不行。
+ */
+/**
+ * 校验并归一化一次延后请求的时刻（epoch ms）。
+ *
+ * - `Date` 取 `getTime()`，数字原样用；
+ * - 非有限数（NaN / Infinity / 非数字）⇒ TypeError；
+ * - **不晚于现在**（`at <= now`）⇒ TypeError。
+ *
+ * 边界是**严格大于**：恰好等于「现在」不算将来（同一毫秒里到期扫描会立刻捞起它）。
+ */
+export declare function resolveWakeAt(input: number | Date, now: number): number;
+/** 一个回合收到的全部延后请求（每个 `executeTurnTools` 一次，随回合消亡） */
+export interface DeferRequest {
+    /** 记一次请求。同一个 tool_use_id 重复请求取**最早**的那个（早醒可补救，晚醒白等） */
+    request(toolUseId: string, at: number | Date): void;
+    /** 本回合的目标时刻：所有请求里**最早**的那个；一个请求都没有 ⇒ undefined */
+    earliest(): number | undefined;
+    /** 请求过延后的 tool_use_id（按请求到达顺序；并行工具下即完成顺序） */
+    ids(): string[];
+}
+/**
+ * 建一个回合级的延后请求收集器。`clock` 只为单测注入（默认 `Date.now`）——
+ * 「什么是过去」由它决定，测试不该依赖墙钟。
+ */
+export declare function createDeferRequest(clock?: () => number): DeferRequest;

package/dist/engine/defer.js

@@ -0,0 +1,72 @@
+/**
+ * 延后请求（durable timer）的**纯判定与收集**：工具说「现在还不是时候，T 之后再问我」。
+ *
+ * 为什么单独成件：这是挂起的第二个**原因**（`core/run.ts` 的 `SuspendedReason` —— timer 侧）。
+ * 它与审批（approval）的关键差别决定了这个文件里的每一条规则：
+ *
+ * | | 审批 | 延后 |
+ * |---|---|---|
+ * | 谁提 | **宿主**在执行前给决定（引擎只查 `args.approvals`） | **工具**在跑的时候提 |
+ * | 判据 | 「决定在不在」（没有就不执行） | 「时刻到了没」（没到就挂起） |
+ * | 非法值 | 不适用（决定是布尔） | **有**：T 在过去 / 非有限数 ⇒ 必须响亮拒绝 |
+ *
+ * 后一行是本文件存在的理由：延后是**工具运行时**提出的，取值就成了一条外部契约。
+ * 让「T ≤ 现在」成立的话，到期扫描读到它会立刻唤醒、续跑、工具再请求同一个过去时刻 ——
+ * **一条自己打转的 run**（每次都不花钱，但 store / trace / 判据全在空转，且永不收尾）。
+ * 所以 `resolveWakeAt` 把「必须在将来」做成**当场抛错**：那次工具调用以 is_error 的
+ * tool_result 回给模型（既有路径），run 照常往前走 —— 不静默、不挂起成僵尸。
+ *
+ * 第二件审批不需要解决的事：**一个回合一挂起**（协议要求每个 tool_use 都有配对的
+ * tool_result），所以同回合的多个延后请求只能合并成一个时刻 —— 取**最早**的那个
+ * （「早醒」是可补救的：醒来看还没到就再请求一次；「晚醒」则白等）。
+ *
+ * 纯的边界：只吃 `(at, now)`，只吐结论；不碰 recorder、不碰 ctx、不改任何 rec。
+ * 时刻口径是**绝对毫秒时间戳**（epoch ms）—— 它要落库、要跨进程比较，相对毫秒不行。
+ */
+/**
+ * 校验并归一化一次延后请求的时刻（epoch ms）。
+ *
+ * - `Date` 取 `getTime()`，数字原样用；
+ * - 非有限数（NaN / Infinity / 非数字）⇒ TypeError；
+ * - **不晚于现在**（`at <= now`）⇒ TypeError。
+ *
+ * 边界是**严格大于**：恰好等于「现在」不算将来（同一毫秒里到期扫描会立刻捞起它）。
+ */
+export function resolveWakeAt(input, now) {
+    const at = input instanceof Date ? input.getTime() : input;
+    if (typeof at !== 'number' || !Number.isFinite(at)) {
+        throw new TypeError(`deferUntil 需要一个将来时刻（epoch 毫秒或 Date），收到 ${String(input)} —— ` +
+            '非有限值会在落库/比较时静默失效');
+    }
+    if (at <= now) {
+        throw new TypeError(`deferUntil 的时刻必须在将来（收到 ${at}，现在是 ${now}）—— ` +
+            '「现在就能续」表达不了「T 之后再问我」，而且到期扫描会立刻唤醒它、原样再请求一次（自己打转的 run）');
+    }
+    return at;
+}
+/**
+ * 建一个回合级的延后请求收集器。`clock` 只为单测注入（默认 `Date.now`）——
+ * 「什么是过去」由它决定，测试不该依赖墙钟。
+ */
+export function createDeferRequest(clock = Date.now) {
+    const asked = new Map();
+    return {
+        request(toolUseId, at) {
+            const wakeAt = resolveWakeAt(at, clock());
+            const prev = asked.get(toolUseId);
+            if (prev === undefined || wakeAt < prev)
+                asked.set(toolUseId, wakeAt);
+        },
+        earliest() {
+            let min;
+            for (const at of asked.values())
+                if (min === undefined || at < min)
+                    min = at;
+            return min;
+        },
+        ids() {
+            return [...asked.keys()];
+        },
+    };
+}
+//# sourceMappingURL=defer.js.map

package/dist/engine/defer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defer.js","sourceRoot":"","sources":["../../src/engine/defer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAoB,EAAE,GAAW;IAC7D,MAAM,EAAE,GAAG,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC3D,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,SAAS,CACjB,0CAA0C,MAAM,CAAC,KAAK,CAAC,MAAM;YAC3D,kBAAkB,CACrB,CAAC;IACJ,CAAC;IACD,IAAI,EAAE,IAAI,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,SAAS,CACjB,0BAA0B,EAAE,QAAQ,GAAG,MAAM;YAC3C,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAYD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAK,GAAiB,IAAI,CAAC,GAAG;IAC/D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,OAAO;QACL,OAAO,CAAC,SAAS,EAAE,EAAE;YACnB,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAClC,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,GAAG,IAAI;gBAAE,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACxE,CAAC;QACD,QAAQ;YACN,IAAI,GAAuB,CAAC;YAC5B,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,MAAM,EAAE;gBAAE,IAAI,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,GAAG;oBAAE,GAAG,GAAG,EAAE,CAAC;YAC7E,OAAO,GAAG,CAAC;QACb,CAAC;QACD,GAAG;YACD,OAAO,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/forwarded.d.ts

@@ -14,7 +14,7 @@
  * 本文件的机制有两半，缺一不可：
  *
  * 1. **取值收一处**：`forwardToolContext(ctx)` 是唯一的取值点，映射类型写成
- *    `{ [K in Key]-?: … }` —— 七个键**全必填**（值可以是 `undefined`）。少写一行 = 编译错误，
+ *    `{ [K in Key]-?: … }` —— 全部键**必填**（值可以是 `undefined`）。少写一行 = 编译错误，
  *    而不是静默漏。调用点播 `...forwardToolContext(ctx)` 即可，**没有**可漏的地方。
  * 2. **归类要穷尽**：`ToolRunContext` 的每个键必须在「转发」或「引擎自装配」里各就各位。
  *    新增一个可选字段而两边都没归类 ⇒ `UnclassifiedToolContextKey` 不再是 `never`
@@ -23,7 +23,7 @@
  * ⚠️ 唯一需要**覆盖**而不是直取的是 `signal`：两个调用点交下去的是
  * `combineSignals(ctx.signal, ctx.abandoned)`（子循环还要能被「放弃等待」打断），
  * 所以那里写成 `{ ...forwardToolContext(ctx), signal: combined }` —— 覆盖是显式的，
- * 其余六个键仍然不可能漏。
+ * 其余键仍然不可能漏。
  *
  * ⚠️ 本模块不是公共 API（不进 `src/index.ts`）：它是内部纪律的落点。
  */
@@ -42,13 +42,15 @@ export declare const FORWARDED_TOOL_CONTEXT_KEYS: readonly [
 'onUnpricedModel', 
 /** 正文截断口径（漏了 ⇒ 同一棵树上主/子 agent 的可见性不一致） */
 'maxEventChars', 
+/** assistant 文本记录口径（漏了 ⇒ 同一棵树上主 agent 有 output.text、子 agent 没有） */
+'traceContent', 
 /** 成本护栏（漏了 ⇒ 护栏在子循环期间离线） */
 'maxTotalTokens', 'maxCostUsd', 
 /** 超时裁判权（漏了 ⇒ 永不超时 + 桥另起计时器，见文件头） */
 'toolTimeoutMs'];
 export type ForwardedToolContextKey = (typeof FORWARDED_TOOL_CONTEXT_KEYS)[number];
 /**
- * 交给子循环的那一组值：**七个键全必填**（值可以是 `undefined` —— 那表示「本 run 没设」，
+ * 交给子循环的那一组值：**全部键必填**（值可以是 `undefined` —— 那表示「本 run 没设」，
  * 与「忘了转发」是两件事，后者在类型上写不出来）。
  */
 export type ForwardedToolContext = {
@@ -68,14 +70,21 @@ export type ToolContextNotForwardedKey =
 /** 「放弃等待」信号：折进 `signal`（见文件头的 combine），子循环的工具会拿到**它自己**的 */
  | 'abandoned'
 /** 审批决定：属于**本次工具调用**（外层那个工具被批没批），不该灌进子循环的每一次调用 */
- | 'approval';
+ | 'approval'
+/**
+ * 延后请求口：与 `approval` 同一类 —— 它是**本次工具调用所在的那个回合**的产物
+ * （请求由外层哪一次调用提出、就记在外层那个回合上）。灌进子循环会让子循环里某次工具
+ * 调用的「再问我」记到**外层回合**的收集器上：外层整批作废重跑，而请求它的那个工具
+ * 可能根本不在这批里 —— 张冠李戴。子循环自己的回合有自己的收集器（同一个入口装配）。
+ */
+ | 'deferUntil';
 /**
  * 未归类的键。全部归类时是 `never`；一旦 `ToolRunContext` 新增字段而上面两组都没收，
  * 它就变成那个字段名 —— 于是 `tests/types/forwarding.types.ts` 里那句赋 `true` 编译失败。
  */
 export type UnclassifiedToolContextKey = Exclude<keyof ToolRunContext, ForwardedToolContextKey | ToolContextNotForwardedKey>;
 /**
- * 取值：把 `ctx` 上该转发的七个键原样取出（**不判空** —— `undefined` 是有信息的值，
+ * 取值：把 `ctx` 上该转发的键原样取出（**不判空** —— `undefined` 是有信息的值，
  * 表示「本 run 没设这个旋钮」，子循环该用它自己的缺省；判空会把它吃成「没转发」）。
  *
  * ⚠️ 不做真值判定：`maxEventChars: false`（不截断）与 `maxTotalTokens: 0` 都是有意义的值，

package/dist/engine/forwarded.js

@@ -12,6 +12,8 @@ export const FORWARDED_TOOL_CONTEXT_KEYS = [
     'onUnpricedModel',
     /** 正文截断口径（漏了 ⇒ 同一棵树上主/子 agent 的可见性不一致） */
     'maxEventChars',
+    /** assistant 文本记录口径（漏了 ⇒ 同一棵树上主 agent 有 output.text、子 agent 没有） */
+    'traceContent',
     /** 成本护栏（漏了 ⇒ 护栏在子循环期间离线） */
     'maxTotalTokens',
     'maxCostUsd',
@@ -19,7 +21,7 @@ export const FORWARDED_TOOL_CONTEXT_KEYS = [
     'toolTimeoutMs',
 ];
 /**
- * 取值：把 `ctx` 上该转发的七个键原样取出（**不判空** —— `undefined` 是有信息的值，
+ * 取值：把 `ctx` 上该转发的键原样取出（**不判空** —— `undefined` 是有信息的值，
  * 表示「本 run 没设这个旋钮」，子循环该用它自己的缺省；判空会把它吃成「没转发」）。
  *
  * ⚠️ 不做真值判定：`maxEventChars: false`（不截断）与 `maxTotalTokens: 0` 都是有意义的值，
@@ -31,6 +33,7 @@ export function forwardToolContext(ctx) {
         priceOverrides: ctx.priceOverrides,
         onUnpricedModel: ctx.onUnpricedModel,
         maxEventChars: ctx.maxEventChars,
+        traceContent: ctx.traceContent,
         maxTotalTokens: ctx.maxTotalTokens,
         maxCostUsd: ctx.maxCostUsd,
         toolTimeoutMs: ctx.toolTimeoutMs,

package/dist/engine/forwarded.js.map

@@ -1 +1 @@
-{"version":3,"file":"forwarded.js","sourceRoot":"","sources":["../../src/engine/forwarded.ts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,oCAAoC;IACpC,QAAQ;IACR,wDAAwD;IACxD,gBAAgB;IAChB,mCAAmC;IACnC,iBAAiB;IACjB,0CAA0C;IAC1C,eAAe;IACf,4BAA4B;IAC5B,gBAAgB;IAChB,YAAY;IACZ,qCAAqC;IACrC,eAAe;CACP,CAAC;AAqCX;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAmB;IACpD,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,eAAe,EAAE,GAAG,CAAC,eAAe;QACpC,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,aAAa,EAAE,GAAG,CAAC,aAAa;KACjC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"forwarded.js","sourceRoot":"","sources":["../../src/engine/forwarded.ts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,oCAAoC;IACpC,QAAQ;IACR,wDAAwD;IACxD,gBAAgB;IAChB,mCAAmC;IACnC,iBAAiB;IACjB,0CAA0C;IAC1C,eAAe;IACf,mEAAmE;IACnE,cAAc;IACd,4BAA4B;IAC5B,gBAAgB;IAChB,YAAY;IACZ,qCAAqC;IACrC,eAAe;CACP,CAAC;AA4CX;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAmB;IACpD,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,eAAe,EAAE,GAAG,CAAC,eAAe;QACpC,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,aAAa,EAAE,GAAG,CAAC,aAAa;KACjC,CAAC;AACJ,CAAC"}

package/dist/engine/loop-result.d.ts

@@ -1,17 +1,18 @@
 import type { MessageParam } from '../core/message.js';
 import type { SpanError } from '../core/trace.js';
+import type { SuspendedReason } from '../core/run.js';
 import type { AgentStopReason } from './types.js';
 /**
  * Agentia —— 循环出口的**结果形状单源**（engine/loop.ts 的拆分第二步）。
  *
- * `AgentLoopResult` 属「结果/状态记录」型（`docs/guards.md` 的类型角色表）：7 个字段
+ * `AgentLoopResult` 属「结果/状态记录」型（`docs/guards.md` 的类型角色表）：10 个字段
  * **必须全在场**，值可以为 undefined —— 消费方按 `result.suspendedMessages === undefined`
  * 判「没挂起」，而「字段缺席」与「字段为 undefined」在 JSON / OTLP 上是两回事。
  *
  * 此前这 7 个字段由 loop.ts 的五处对象字面量各写一遍（= 35 次「记得写」）：加一个字段
  * 要改五处，漏一处就是无声的形状漂移。现在出口只剩四个具名构造器，各自的语义写在名字上：
  *
- *   suspendedResult  挂起（等人审批）—— 不是失败；交出的历史是**拷贝**
+ *   suspendedResult  挂起（等人审批 / 等一个时刻）—— 不是失败；交出的历史是**拷贝**
  *   abortedResult    已取消 —— 带结构化 error（取消不是失败，但原因要可查）
  *   failedResult     抛出被兜住 —— 由 `classifyError` 翻成结构化 error
  *   finishedResult   循环这次**结束**了 —— 成败由 stopReason 表达，error 由调用方给
@@ -28,21 +29,67 @@ export interface AgentLoopResult<T = unknown> {
     /** submit_result 校验通过的结构化结果；未提交则为 undefined（类型由 resultSchema 推导） */
     typed: T | undefined;
     /**
-     * HITL 挂起（stopReason === 'awaiting_approval'）时的完整消息历史
+     * HITL 挂起（stopReason === 'suspended'）时的完整消息历史
      * （末尾是含未决 tool_use 的 assistant 消息）；未挂起为 undefined（字段在场）。
      */
     suspendedMessages: MessageParam[] | undefined;
-    /** HITL 挂起时待决的 tool_use_id 列表；未挂起为 undefined（字段在场） */
+    /**
+     * HITL 挂起时待决的 tool_use_id 列表；未挂起为 undefined（字段在场）
+     */
     pendingApprovals: string[] | undefined;
+    /**
+     * 挂起原因（`stopReason === 'suspended'` 时非空，2026-09-28 ①）：
+     * `approval` = 等人工决定、`timer` = 等一个时刻。**由出口的调用方给** ——
+     * 出口自己不认识「为什么挂起」，它只保证这个位一定在场。
+     */
+    suspendedReason: SuspendedReason | undefined;
+    /**
+     * 时间挂起的目标时刻（epoch ms）：`suspendedReason === 'timer'` 时在场，
+     * 其余（含 `approval` 挂起与一切非挂起收尾）为 undefined（字段在场）。
+     *
+     * 宿主（`AsyncRunner`）据此落 `TaskRecord.wakeAt`，到期扫描靠它判「醒了没」——
+     * 与「原因」同一个道理：**在哪个出口写、什么时候非空**由调用方（循环）说，
+     * 出口只保证这个位一定在场。
+     */
+    wakeAt: number | undefined;
+    /**
+     * 本段是否把传入的 `events`（run 事件投入口，2026-09-28 ⑥）**真注入了消息流**
+     * （字段在场）。宿主据此清 `TaskRecord.pendingEvents`：注入过 ⇒ 事件已在历史里，
+     * 簿记清掉（否则下次续跑会**重复注入**）；没注入（续跑入口的再挂起出口在注入点
+     * 之前返回）⇒ 簿记必须留住，等跑通的那次。
+     */
+    eventsDelivered: boolean;
 }
-/** 挂起收尾（两处出口共用：循环中途挂起 / 恢复模式进来发现决定仍不齐） */
+/**
+ * 挂起请求：**为什么**挂起由调用方说（出口不认识业务原因），`pending` 是本批未决的 id。
+ *
+ * 判别联合让「说 timer 却不给时刻」在类型上写不出来（`wakeAt` 是 timer 分支的必填项）——
+ * 落到结果里就成了 `suspendedReason === 'timer' ⇔ wakeAt 在场` 这条不变量，
+ * 到期扫描读的就是它（`wake-policy.ts` 的 `timerDue`）。
+ */
+export type Suspension = {
+    reason: 'approval';
+    pending: string[];
+} | {
+    reason: 'timer';
+    pending: string[];
+    wakeAt: number;
+};
+/** 挂起收尾（四处出口共用：循环中途挂起 / 恢复模式进来决定仍不齐 / 两处延后请求） */
 export declare function suspendedResult<T>(ctx: {
     messages: MessageParam[];
+    /**
+     * 段级进度簿记。`eventsDelivered` **必须从这里读**（不是 ctx 上的独立字段）：
+     * 它跨段共享、外层收尾也读同一份（见 `loop.ts` 的 catch 与外部深评 E4）。
+     * ⚠️ 别把它挪回 ctx 的顶层字段 —— 那样四个挂起出口会**静默报 false**
+     * （可选字段缺失不报错），2026-09-28 第一版就是这么改的，被既有用例当场抓住。
+     */
     progress: {
         iterations: number;
+        eventsDelivered?: boolean;
     };
     typed: T | undefined;
-}, pending: string[], 
+}, suspension: Suspension, 
 /** 挂起前那一回合的文本（循环中途挂起时给；恢复模式再次挂起时没有新回合，留空） */
 finalText?: string): AgentLoopResult<T>;
 /**
@@ -56,8 +103,18 @@ export declare function abortedResult<T = never>(iterations?: number): AgentLoop
  * 抛出被兜住的收尾：`cause` 是**任何**抛出来的东西（SDK 异常、类型错误、abort 信号……），
  * 出口处一律经 `classifyError` 翻成结构化 SpanError —— 「非正常收尾必带结构化 error」
  * 这条不变量落在这一处，而不是散在各 catch 里。
+ *
+ * ⚠️ `eventsDelivered` 必须由调用方**按事实**传入，不在这里硬写 `false`（外部深评 E4）：
+ * `false` 的含义是「本段没注入过事件」，而这条出口完全可能发生在注入**之后**
+ * （事件注入 → 后续回合请求失败 ⇒ 落到这里）。硬写就把「已注入」报成「未注入」——
+ * 该字段随 `rec.result` **落库、在导出面上**，消费者据此判断「这批事件进没进历史」，
+ * 报错方向恰好会让宿主以为该重投（重投 = 模型看到两条）。
+ *
+ * 当日为什么没被发现：`pendingEvents` 的清理在**终态**分支是无条件的（`async.ts`），
+ * 而这条出口只走终态 ⇒ 框架内部的簿记恰好被掩盖。它坏的是**对外字段的语义**，不是内部行为 ——
+ * 所以这是「如实类」修复：**零行为变更，一个字段不再说谎**。
  */
-export declare function failedResult<T = never>(cause: unknown, iterations: number): AgentLoopResult<T>;
+export declare function failedResult<T = never>(cause: unknown, iterations: number, eventsDelivered?: boolean): AgentLoopResult<T>;
 /**
  * 循环这次结束了。名字刻意不含成败：`stopReason` 才是成败的表达
  * （`end_turn` / `stop_sequence` 成功，`budget_exceeded` / `max_iterations` / `refusal` 一类
@@ -69,4 +126,5 @@ export declare function finishedResult<T>(f: {
     iterations: number;
     typed: T | undefined;
     error?: SpanError | undefined;
+    eventsDelivered?: boolean;
 }): AgentLoopResult<T>;

package/dist/engine/loop-result.js

@@ -13,15 +13,18 @@ function loopResult(f) {
         typed: f.typed,
         suspendedMessages: undefined,
         pendingApprovals: undefined,
+        suspendedReason: undefined,
+        wakeAt: undefined,
+        eventsDelivered: f.eventsDelivered ?? false,
     };
 }
-/** 挂起收尾（两处出口共用：循环中途挂起 / 恢复模式进来发现决定仍不齐） */
-export function suspendedResult(ctx, pending, 
+/** 挂起收尾（四处出口共用：循环中途挂起 / 恢复模式进来决定仍不齐 / 两处延后请求） */
+export function suspendedResult(ctx, suspension, 
 /** 挂起前那一回合的文本（循环中途挂起时给；恢复模式再次挂起时没有新回合，留空） */
 finalText = '') {
     return {
         ...loopResult({
-            stopReason: 'awaiting_approval',
+            stopReason: 'suspended',
             finalText,
             // 挂起不是失败：等人不该被看板算成失败（区分由 stopReason 承担）
             error: undefined,
@@ -31,7 +34,11 @@ finalText = '') {
         // 历史是**拷贝**：宿主落库后仍可能继续用同一条数组，挂起段的消息不能再被改
         suspendedMessages: [...ctx.messages],
         // 待决 id 列表原样交出（同一引用）—— 调用方此后不再改动它，保留原行为，不顺手加拷贝
-        pendingApprovals: pending,
+        pendingApprovals: suspension.pending,
+        suspendedReason: suspension.reason,
+        // 只有时间挂起有目标时刻；判别联合让这一行不可能「说 timer 却没时刻」
+        wakeAt: suspension.reason === 'timer' ? suspension.wakeAt : undefined,
+        eventsDelivered: ctx.progress.eventsDelivered ?? false,
     };
 }
 /**
@@ -53,14 +60,25 @@ export function abortedResult(iterations = 0) {
  * 抛出被兜住的收尾：`cause` 是**任何**抛出来的东西（SDK 异常、类型错误、abort 信号……），
  * 出口处一律经 `classifyError` 翻成结构化 SpanError —— 「非正常收尾必带结构化 error」
  * 这条不变量落在这一处，而不是散在各 catch 里。
+ *
+ * ⚠️ `eventsDelivered` 必须由调用方**按事实**传入，不在这里硬写 `false`（外部深评 E4）：
+ * `false` 的含义是「本段没注入过事件」，而这条出口完全可能发生在注入**之后**
+ * （事件注入 → 后续回合请求失败 ⇒ 落到这里）。硬写就把「已注入」报成「未注入」——
+ * 该字段随 `rec.result` **落库、在导出面上**，消费者据此判断「这批事件进没进历史」，
+ * 报错方向恰好会让宿主以为该重投（重投 = 模型看到两条）。
+ *
+ * 当日为什么没被发现：`pendingEvents` 的清理在**终态**分支是无条件的（`async.ts`），
+ * 而这条出口只走终态 ⇒ 框架内部的簿记恰好被掩盖。它坏的是**对外字段的语义**，不是内部行为 ——
+ * 所以这是「如实类」修复：**零行为变更，一个字段不再说谎**。
  */
-export function failedResult(cause, iterations) {
+export function failedResult(cause, iterations, eventsDelivered) {
     return loopResult({
         stopReason: 'error',
         finalText: '',
         error: classifyError(cause),
         iterations,
         typed: undefined,
+        ...(eventsDelivered !== undefined ? { eventsDelivered } : {}),
     });
 }
 /**
@@ -75,6 +93,7 @@ export function finishedResult(f) {
         error: f.error,
         iterations: f.iterations,
         typed: f.typed,
+        ...(f.eventsDelivered !== undefined ? { eventsDelivered: f.eventsDelivered } : {}),
     });
 }
 //# sourceMappingURL=loop-result.js.map

package/dist/engine/loop-result.js.map

@@ -1 +1 @@
-{"version":3,"file":"loop-result.js","sourceRoot":"","sources":["../../src/engine/loop-result.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAuCzC;;;GAGG;AACH,SAAS,UAAU,CAAI,CAMtB;IACC,OAAO;QACL,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,iBAAiB,EAAE,SAAS;QAC5B,gBAAgB,EAAE,SAAS;KAC5B,CAAC;AACJ,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,eAAe,CAC7B,GAAyF,EACzF,OAAiB;AACjB,6CAA6C;AAC7C,SAAS,GAAG,EAAE;IAEd,OAAO;QACL,GAAG,UAAU,CAAI;YACf,UAAU,EAAE,mBAAmB;YAC/B,SAAS;YACT,wCAAwC;YACxC,KAAK,EAAE,SAAS;YAChB,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU;YACnC,KAAK,EAAE,GAAG,CAAC,KAAK;SACjB,CAAC;QACF,yCAAyC;QACzC,iBAAiB,EAAE,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC;QACpC,+CAA+C;QAC/C,gBAAgB,EAAE,OAAO;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAY,UAAU,GAAG,CAAC;IACrD,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,SAAS;QACrB,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,YAAY,EAAE;QACrB,UAAU;QACV,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAY,KAAc,EAAE,UAAkB;IACxE,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,OAAO;QACnB,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC;QAC3B,UAAU;QACV,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAI,CAMjC;IACC,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"loop-result.js","sourceRoot":"","sources":["../../src/engine/loop-result.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AA+DzC;;;GAGG;AACH,SAAS,UAAU,CAAI,CAQtB;IACC,OAAO;QACL,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,iBAAiB,EAAE,SAAS;QAC5B,gBAAgB,EAAE,SAAS;QAC3B,eAAe,EAAE,SAAS;QAC1B,MAAM,EAAE,SAAS;QACjB,eAAe,EAAE,CAAC,CAAC,eAAe,IAAI,KAAK;KAC5C,CAAC;AACJ,CAAC;AAaD,iDAAiD;AACjD,MAAM,UAAU,eAAe,CAC7B,GAUC,EACD,UAAsB;AACtB,6CAA6C;AAC7C,SAAS,GAAG,EAAE;IAEd,OAAO;QACL,GAAG,UAAU,CAAI;YACf,UAAU,EAAE,WAAW;YACvB,SAAS;YACT,wCAAwC;YACxC,KAAK,EAAE,SAAS;YAChB,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU;YACnC,KAAK,EAAE,GAAG,CAAC,KAAK;SACjB,CAAC;QACF,yCAAyC;QACzC,iBAAiB,EAAE,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC;QACpC,+CAA+C;QAC/C,gBAAgB,EAAE,UAAU,CAAC,OAAO;QACpC,eAAe,EAAE,UAAU,CAAC,MAAM;QAClC,wCAAwC;QACxC,MAAM,EAAE,UAAU,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACrE,eAAe,EAAE,GAAG,CAAC,QAAQ,CAAC,eAAe,IAAI,KAAK;KACvD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAY,UAAU,GAAG,CAAC;IACrD,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,SAAS;QACrB,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,YAAY,EAAE;QACrB,UAAU;QACV,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,UAAkB,EAClB,eAAyB;IAEzB,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,OAAO;QACnB,SAAS,EAAE,EAAE;QACb,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC;QAC3B,UAAU;QACV,KAAK,EAAE,SAAS;QAChB,GAAG,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9D,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAI,CAOjC;IACC,OAAO,UAAU,CAAI;QACnB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,GAAG,CAAC,CAAC,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnF,CAAC,CAAC;AACL,CAAC"}

package/dist/engine/loop.d.ts

@@ -35,6 +35,8 @@ export declare function runAgentScoped<S extends JsonSchema = JsonSchema>(opts:
     maxToolConcurrency?: number | undefined;
     /** 事件正文截断上限；同 RunAgentOptions.maxEventChars */
     maxEventChars?: number | false | undefined;
+    /** opt-in 记录 assistant 文本（R8-P3a）；同 RunAgentOptions.traceContent（由转发机制透传下来） */
+    traceContent?: 'full' | undefined;
     /** 价格表覆盖（F1）：由发起它的能力从 ToolRunContext.priceOverrides 透传 */
     priceOverrides?: Record<string, ModelPricing> | undefined;
     /** 未定价模型回调（F2）：由发起它的能力透传 */