@migor/agentia 0.9.4 → 0.10.0

package/dist/engine/policy.js

@@ -35,8 +35,14 @@ export function createBudgetPolicy(opts = {}) {
                 return current;
             if (info.iteration - lastCompactAt < compactEvery)
                 return current;
+            // ⚠️ 滞回记的是「上次**成功**压缩的回合」（2026-09-28 修）：原实现在 `compactMessages(...)`
+            // **之前**就写 `lastCompactAt` —— 摘要器走模型（429 / 超时都常见），压缩失败时额度却已被
+            // 烧掉，于是「这一回合没压成」还连带让后面 `compactEvery - 1` 个回合都不再尝试。
+            // 失败不记账 ⇒ 下一回合自然重试。代价要说清：**摘要器持续失败时每回合都会再调一次**
+            // （每次多一次失败的模型往返）；要抑制请在 `summarize` 里自己退避，别靠滞回额度兜。
+            const compacted = await compactMessages(current, { keepRecent, summarize });
             lastCompactAt = info.iteration;
-            return compactMessages(current, { keepRecent, summarize });
+            return compacted;
         },
     };
 }

package/dist/engine/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/engine/policy.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,GACd,MAAM,eAAe,CAAC;AAuCvB,MAAM,UAAU,kBAAkB,CAAC,IAAI,GAAwB,EAAE;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,MAAM,CAAC;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,IAAI,qBAAqB,CAAC;IAC9D,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACjC,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC;IACzD,IAAI,aAAa,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC7C,4CAA4C;IAC5C,MAAM,WAAW,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAEjD,OAAO;QACL,YAAY;QACZ,yEAAyE;QACzE,0DAA0D;QAC1D,4DAA4D;QAC5D,iBAAiB;QACjB,MAAM,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC;QACtC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI;YAC7B,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,YAAY;gBAAE,OAAO,QAAQ,CAAC;YAE3D,oDAAoD;YACpD,IAAI,OAAO,GAAG,QAAQ,CAAC;YACvB,IAAI,iBAAiB,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC1D,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;oBACpC,OAAO,GAAG,OAAO,CAAC;oBAClB,IAAI,WAAW,CAAC,OAAO,CAAC,IAAI,YAAY;wBAAE,OAAO,OAAO,CAAC;gBAC3D,CAAC;YACH,CAAC;YAED,0BAA0B;YAC1B,IAAI,CAAC,SAAS;gBAAE,OAAO,OAAO,CAAC;YAC/B,IAAI,IAAI,CAAC,SAAS,GAAG,aAAa,GAAG,YAAY;gBAAE,OAAO,OAAO,CAAC;YAClE,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC;YAC/B,OAAO,eAAe,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/engine/policy.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,GACd,MAAM,eAAe,CAAC;AAwCvB,MAAM,UAAU,kBAAkB,CAAC,IAAI,GAAwB,EAAE;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,MAAM,CAAC;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,IAAI,qBAAqB,CAAC;IAC9D,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACjC,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC;IACzD,IAAI,aAAa,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC7C,4CAA4C;IAC5C,MAAM,WAAW,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAEjD,OAAO;QACL,YAAY;QACZ,yEAAyE;QACzE,0DAA0D;QAC1D,4DAA4D;QAC5D,iBAAiB;QACjB,MAAM,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC;QACtC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI;YAC7B,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,YAAY;gBAAE,OAAO,QAAQ,CAAC;YAE3D,oDAAoD;YACpD,IAAI,OAAO,GAAG,QAAQ,CAAC;YACvB,IAAI,iBAAiB,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC1D,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;oBACpC,OAAO,GAAG,OAAO,CAAC;oBAClB,IAAI,WAAW,CAAC,OAAO,CAAC,IAAI,YAAY;wBAAE,OAAO,OAAO,CAAC;gBAC3D,CAAC;YACH,CAAC;YAED,0BAA0B;YAC1B,IAAI,CAAC,SAAS;gBAAE,OAAO,OAAO,CAAC;YAC/B,IAAI,IAAI,CAAC,SAAS,GAAG,aAAa,GAAG,YAAY;gBAAE,OAAO,OAAO,CAAC;YAClE,oEAAoE;YACpE,6DAA6D;YAC7D,oDAAoD;YACpD,+CAA+C;YAC/C,kDAAkD;YAClD,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;YAC5E,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC;YAC/B,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/replay.d.ts

@@ -25,7 +25,8 @@ import type { Trace } from '../core/trace.js';
  *   可直接作为 Messages API 的 messages 喂回模型（末条为 user 是硬要求：
  *   以 assistant 收尾即 prefill，缺省模型上 400）。
  *
- * 注意：trace 不记录 assistant 文本（llm.turn 只记 usage/事件），还原的
+ * 注意：trace **缺省**不记录 assistant 文本（llm.turn 只记 usage/事件；opt-in 例外见
+ * `RunAgentOptions.traceContent: 'full'`，R8-P3a），还原的
  * assistant 消息以标注文本占位，非逐字原文。trace 同样不记 run 的原始输入，
  * 故重放的首尾说明性 user 均为合成（这一有损边界对 forkMessages 同样成立）。
  *

package/dist/engine/replay.js

@@ -1,3 +1,4 @@
+import { TOOL_INPUT_EVENT, TOOL_OUTPUT_EVENT } from '../core/trace.js';
 import { stringifySafe, truncateWithMark } from '../core/json.js';
 const DEFAULT_MAX_EVENT_CHARS = 2000;
 export function traceToMessages(trace, opts = {}) {
@@ -54,8 +55,8 @@ function expandTurns(turns, byId, includeToolIO, maxChars) {
         const content = [{ type: 'text', text: note }];
         const pairs = [];
         if (includeToolIO) {
-            const inputs = eventsOf(turn, 'tool.input');
-            const outputs = eventsOf(turn, 'tool.output');
+            const inputs = eventsOf(turn, TOOL_INPUT_EVENT);
+            const outputs = eventsOf(turn, TOOL_OUTPUT_EVENT);
             const used = new Set();
             for (const input of inputs) {
                 // 配对优先级：同 id 精确匹配 > 同名最早未配对 > 最早未配对。

package/dist/engine/replay.js.map

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

package/dist/engine/resume-input.d.ts

@@ -1,4 +1,5 @@
 import type { MessageParam, ToolUseBlock } from '../core/message.js';
+import type { TaskEvent } from '../core/run.js';
 /**
  * Agentia —— 续跑入口的**读取件**（engine/loop.ts 的拆分第三步）。
  *
@@ -24,3 +25,12 @@ import type { MessageParam, ToolUseBlock } from '../core/message.js';
 export declare function tailToolUses(messages: MessageParam[]): ToolUseBlock[];
 /** 取 MessageParam（请求侧）里的文本块拼成的文本（恢复模式收尾时用） */
 export declare function textOfParam(message: MessageParam): string;
+/**
+ * run 事件 → **一条 user 文本消息**（2026-09-28 ⑥ 的 B1：外部永远不能构造 block ——
+ * 进来的只有文本，投毒面只到「内容注入」为止）。
+ *
+ * `eventId` **不进正文**：它是投递簿记（幂等去重依据），不是内容 —— 模型不需要知道
+ * 去重键，把它放进去只会给「同一件事换 id 再投一次」留语义噪音。留痕走 trace
+ * （`task.event` 事件，见 loop.ts 的注入点），不进消息。
+ */
+export declare function renderTaskEvent(ev: TaskEvent): MessageParam;

package/dist/engine/resume-input.js

@@ -36,4 +36,15 @@ export function textOfParam(message) {
         .map((b) => b.text ?? '')
         .join('\n');
 }
+/**
+ * run 事件 → **一条 user 文本消息**（2026-09-28 ⑥ 的 B1：外部永远不能构造 block ——
+ * 进来的只有文本，投毒面只到「内容注入」为止）。
+ *
+ * `eventId` **不进正文**：它是投递簿记（幂等去重依据），不是内容 —— 模型不需要知道
+ * 去重键，把它放进去只会给「同一件事换 id 再投一次」留语义噪音。留痕走 trace
+ * （`task.event` 事件，见 loop.ts 的注入点），不进消息。
+ */
+export function renderTaskEvent(ev) {
+    return { role: 'user', content: `[事件 type=${ev.type}]\n${ev.payload}` };
+}
 //# sourceMappingURL=resume-input.js.map

package/dist/engine/resume-input.js.map

@@ -1 +1 @@
-{"version":3,"file":"resume-input.js","sourceRoot":"","sources":["../../src/engine/resume-input.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAAwB;IACnD,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,IAAI,EAAE,IAAI,KAAK,WAAW,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1E,4DAA4D;IAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAqB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AAC9E,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;QACjC,OAAO,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,OAAO,OAAO,CAAC,OAAO;SACnB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAuB,CAAC,IAAI,IAAI,EAAE,CAAC;SAC/C,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}
+{"version":3,"file":"resume-input.js","sourceRoot":"","sources":["../../src/engine/resume-input.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAAwB;IACnD,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,IAAI,EAAE,IAAI,KAAK,WAAW,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1E,4DAA4D;IAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAqB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AAC9E,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;QACjC,OAAO,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,OAAO,OAAO,CAAC,OAAO;SACnB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAuB,CAAC,IAAI,IAAI,EAAE,CAAC;SAC/C,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,EAAa;IAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC;AAC1E,CAAC"}

package/dist/engine/run-config.d.ts

@@ -1,5 +1,5 @@
-import type { JsonSchema } from '../core/tool.js';
-import type { RunAgentOptions } from './types.js';
+import type { JsonSchema, ModelClient } from '../core/tool.js';
+import type { ModelFallbackLink, RunAgentOptions } from './types.js';
 import type { TraceLimits } from './tracer.js';
 /**
  * Agentia —— run 生效旋钮：**缺省解析 + 快照编码**（spec §5 / §9 G3）。
@@ -21,6 +21,30 @@ export declare function resolveDefaultModel(over?: string): string;
 /** 缺省单次 maxTokens / 循环上限：runAgent 与 runAgentScoped 共用，避免两处各写一遍漂移。 */
 export declare const DEFAULT_MAX_TOKENS = 64000;
 export declare const DEFAULT_MAX_ITERATIONS = 40;
+/** fallback 链的已解析形态（每环的 client 已就位） */
+export interface ResolvedModelLink {
+    model: string;
+    client: ModelClient;
+}
+/**
+ * 解析本 run 的模型链（R8-P2）：主环 + `fallbacks` 逐环（环的 client 缺省复用主环的）。
+ *
+ * 校验在**这里**（run 入口，每次 run 都过 —— 含崩溃续跑读回的那份 options）：
+ * - 环必须是对象、`model` 必须是非空字符串 —— 否则 TypeError（响亮失败，不静默跳过坏环）；
+ * - 环的 `client`（若给）必须鸭子类型满足 `messages.stream` 是函数 —— 持久化 store
+ *   反序列化回来的空壳（`{}`）在这里变成可读报错，而不是发请求时才爆。
+ */
+export declare function resolveModelChain(args: {
+    model: string;
+    client: ModelClient;
+    fallbacks?: ModelFallbackLink[] | undefined;
+}): ResolvedModelLink[];
+/**
+ * 校验归因标签（R8-P4）：键必须非空、值必须是字符串（**允许空串** —— 「租户未知」
+ * 是有意义的值）。坏值在 run 入口抛 TypeError（与 resolveModelChain 同一个
+ * 「配置错响亮失败」的落点），不静默丢键。
+ */
+export declare function validateLabels(labels: Record<string, string> | undefined): void;
 /**
  * 生效配置快照（G3）：把本 run 实际生效的旋钮整理成 run 根的 `config.*` attributes。
  * 只放标量（OTLP/日志/看板都能直接吃）；缺省值也记，这样"没配"与"配了缺省值"可区分于

package/dist/engine/run-config.js

@@ -23,6 +23,54 @@ export function resolveDefaultModel(over) {
 /** 缺省单次 maxTokens / 循环上限：runAgent 与 runAgentScoped 共用，避免两处各写一遍漂移。 */
 export const DEFAULT_MAX_TOKENS = 64_000;
 export const DEFAULT_MAX_ITERATIONS = 40;
+/**
+ * 解析本 run 的模型链（R8-P2）：主环 + `fallbacks` 逐环（环的 client 缺省复用主环的）。
+ *
+ * 校验在**这里**（run 入口，每次 run 都过 —— 含崩溃续跑读回的那份 options）：
+ * - 环必须是对象、`model` 必须是非空字符串 —— 否则 TypeError（响亮失败，不静默跳过坏环）；
+ * - 环的 `client`（若给）必须鸭子类型满足 `messages.stream` 是函数 —— 持久化 store
+ *   反序列化回来的空壳（`{}`）在这里变成可读报错，而不是发请求时才爆。
+ */
+export function resolveModelChain(args) {
+    const chain = [{ model: args.model, client: args.client }];
+    for (const [i, link] of (args.fallbacks ?? []).entries()) {
+        const where = `fallbacks[${i}]`;
+        if (typeof link !== 'object' || link === null) {
+            throw new TypeError(`${where} 必须是 { model, client? } 对象，收到 ${String(link)}`);
+        }
+        if (typeof link.model !== 'string' || link.model.trim() === '') {
+            throw new TypeError(`${where}.model 必须是非空字符串，收到 ${JSON.stringify(link.model)}`);
+        }
+        const client = link.client ?? args.client;
+        const stream = client?.messages?.stream;
+        if (typeof stream !== 'function') {
+            throw new TypeError(`${where}.client 不满足 ModelClient 契约（messages.stream 不是函数）—— ` +
+                '常见原因：异步任务的 options 经持久化 store  JSON 往返后 client 变成空壳；' +
+                '跨重启仍成立的链请只写 model（client 由 runner/应用级配置兜住）');
+        }
+        chain.push({ model: link.model, client });
+    }
+    return chain;
+}
+/**
+ * 校验归因标签（R8-P4）：键必须非空、值必须是字符串（**允许空串** —— 「租户未知」
+ * 是有意义的值）。坏值在 run 入口抛 TypeError（与 resolveModelChain 同一个
+ * 「配置错响亮失败」的落点），不静默丢键。
+ */
+export function validateLabels(labels) {
+    if (labels === undefined)
+        return;
+    if (typeof labels !== 'object' || labels === null || Array.isArray(labels)) {
+        throw new TypeError(`labels 必须是 Record<string, string>，收到 ${JSON.stringify(labels)}`);
+    }
+    for (const [k, v] of Object.entries(labels)) {
+        if (k.trim() === '')
+            throw new TypeError('labels 的键不能为空字符串');
+        if (typeof v !== 'string') {
+            throw new TypeError(`labels.${k} 必须是字符串，收到 ${JSON.stringify(v)}`);
+        }
+    }
+}
 /**
  * 生效配置快照（G3）：把本 run 实际生效的旋钮整理成 run 根的 `config.*` attributes。
  * 只放标量（OTLP/日志/看板都能直接吃）；缺省值也记，这样"没配"与"配了缺省值"可区分于
@@ -81,6 +129,18 @@ options) {
     const overridden = options.priceOverrides ? Object.keys(options.priceOverrides) : [];
     if (overridden.length > 0)
         out['config.priceOverrides'] = overridden.sort().join(',');
+    // fallback 链（R8-P2）：只记备用模型名（client 是对象，不可序列化；主模型在 config.model）
+    if (options.fallbacks && options.fallbacks.length > 0) {
+        out['config.fallbacks'] = options.fallbacks.map((l) => l.model).join(',');
+    }
+    // assistant 文本记录（R8-P3a）：只在显式开启时记（缺省不记 = 没有这个键）
+    if (options.traceContent === 'full')
+        out['config.traceContent'] = 'full';
+    // 归因标签（R8-P4）：只记**键名**（值可能含租户标识，配置快照不该复制它 ——
+    // 值本体在 labels.* 属性里，想看的人去看那里）
+    if (options.labels && Object.keys(options.labels).length > 0) {
+        out['config.labels'] = Object.keys(options.labels).sort().join(',');
+    }
     if (options.resultSchema)
         out['config.resultSchema'] = true;
     return out;

package/dist/engine/run-config.js.map

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

package/dist/engine/spec.d.ts

@@ -1,8 +1,9 @@
 import type { MessageParam } from '../core/message.js';
 import type { AgentTool, ApprovalDecision, ModelClient, ModelPricing } from '../core/tool.js';
 import type { BlackboardSeed } from '../core/blackboard.js';
+import type { TaskEvent } from '../core/run.js';
 import type { TraceContext, TraceRecordEvent } from '../core/trace.js';
-import type { ContextPolicy } from './types.js';
+import type { ContextPolicy, ModelFallbackLink } from './types.js';
 import type { RetryOptions } from './retry.js';
 import type { TraceLimits } from './tracer.js';
 /**
@@ -33,8 +34,10 @@ export interface RunInvocationOptions {
     idempotencyKey?: string;
     /**
      * **记账的数量上限**（spec §9.4 的答案里「让少记了数据可数」那一半）：整条 trace 的
-     * 事件总数上限，超限即停止记账并在交付时于 run 根写一笔 `trace.truncated`
-     * （`{ droppedEvents, limit }`）—— 缺口位置可预测（尾巴）、且有计数 ⇒ 可解释。
+     * 事件总数上限，超限即停止记账并在 run 根留**两笔** `trace.truncated` ——
+     * 起点标记 `{ limit }`（断点在这里）+ 收尾摘要 `{ droppedEvents, limit }`（丢了多少）
+     * —— 缺口位置可预测（尾巴）、且有计数 ⇒ 可解释。两笔**同时**进交付的 trace 与增量流
+     * （见 `TraceLimits`：折叠契约在截断下无例外成立）。
      *
      * 与 `maxEventChars`（单个事件**正文长度**）正交：一个管「多长」、一个管「多少」，
      * 各有各的家，两个都「不设 = 不限」。缺省**不设** —— 全量记账是本框架的承诺，
@@ -72,6 +75,24 @@ export interface RunInvocationOptions {
     maxTotalTokens?: number;
     /** 成本硬管控：累计成本（美元）上限；依赖模型在价格表内，见 createBudgetGuard */
     maxCostUsd?: number;
+    /**
+     * 模型 fallback 链（R8-P2；语义见 `RunAgentOptions.fallbacks`）。
+     * ⚠️ 序列化边界：链环里的 `client` 是进程内对象，随 `TaskRecord` 落库会丢 ——
+     * 崩溃续跑读回的是空壳，run 入口会响亮抛 TypeError（鸭子类型校验）。要跨重启仍成立
+     * 的链只写 `model`（client 由 runner/应用级配置兜住），或干脆只在应用/run 级配置。
+     */
+    fallbacks?: ModelFallbackLink[];
+    /**
+     * opt-in 记录 assistant 文本进 llm.turn span 的 `output.text`（R8-P3a；
+     * 语义与代价见 `RunAgentOptions.traceContent`）。可序列化（字符串枚举），异步任务
+     * 随 TaskRecord 落库、续跑不丢 —— 与 fallbacks 环里的 client 不同。
+     */
+    traceContent?: 'full';
+    /**
+     * 租户/业务维度归因标签（R8-P4；语义与边界见 `RunAgentOptions.labels`）。
+     * 可序列化（字符串字典），异步任务随 TaskRecord 落库、续跑不丢。
+     */
+    labels?: Record<string, string>;
     /** 价格表覆盖/追加（$/1M tokens）；见 RunAgentOptions.priceOverrides */
     priceOverrides?: Record<string, ModelPricing>;
     /** 单个工具执行超时（毫秒）；超时该条 tool_result 记 is_error，不杀 run */
@@ -88,7 +109,15 @@ export interface RunInvocationOptions {
      */
     maxEventChars?: number | false;
     /**
-     * 人工审批决定（HITL）：以 tool_use_id 为键。恢复 `awaiting_approval` 任务时由
+     * 挂起期间投递的事件（2026-09-28 ⑥，run 事件投入口）：随 `TaskRecord.pendingEvents`
+     * 落库（纯数据、可序列化，重启不丢），续跑段由引擎在**未决 tool_use 解决之后**
+     * 渲染成 user 文本消息注入消息流（为什么不是宿主直接追加到消息末尾：续跑判定
+     * 只认历史**末尾一条**，追加 user 消息会把续跑判成新对话 —— 见 engine/loop.ts）。
+     * 手工续跑「assistant 结尾带 tool_use」的消息历史时也可直接给 `app.run`。
+     */
+    events?: TaskEvent[];
+    /**
+     * 人工审批决定（HITL）：以 tool_use_id 为键。恢复 `suspended` 任务时由
      * 异步宿主随记录传入（纯数据、可序列化，随 `TaskRecord` 落库）；手工续跑
      * 「assistant 结尾带 tool_use」的消息历史时也可直接给 `app.run`。
      */

package/dist/engine/spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/engine/spec.ts"],"names":[],"mappings":"AA4HA;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,wCAAwC;AACxC,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,mDAAmD;QACnD,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,cAAc,CAAC,kBAAkB,CAAC,CAAC;QACzD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,cAAc,CAAC,kBAAkB,CAAC,CAAC;QACrE,OAAO,KAAuB,CAAC;IACjC,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,KAAiE,CAAC;QAC5E,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,cAAc,CAAC,kBAAkB,CAAC,CAAC;YAC1E,OAAO,CAAC,CAAC,QAA0B,CAAC;QACtC,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3F,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,IAAI,cAAc,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AACjF,CAAC"}
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/engine/spec.ts"],"names":[],"mappings":"AAyJA;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,wCAAwC;AACxC,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,mDAAmD;QACnD,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,cAAc,CAAC,kBAAkB,CAAC,CAAC;QACzD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,cAAc,CAAC,kBAAkB,CAAC,CAAC;QACrE,OAAO,KAAuB,CAAC;IACjC,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,KAAiE,CAAC;QAC5E,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,cAAc,CAAC,kBAAkB,CAAC,CAAC;YAC1E,OAAO,CAAC,CAAC,QAA0B,CAAC;QACtC,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3F,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI;YAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,IAAI,cAAc,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AACjF,CAAC"}

package/dist/engine/tool-context.d.ts

@@ -2,15 +2,18 @@
  * 单工具执行的**上下文装配**（纯）：把引擎侧的取值摊成交给工具的 `ToolRunContext`。
  *
  * 从 turn.ts 的 executeOneTool 里外移（2026-09-20，turn 拆分第三步）。这段全部是搬运，但它
- * **不是无害的样板**：八处条件展开里每一处都对应一个「漏了就静默降级」的守卫 ——
+ * **不是无害的样板**：十处条件展开里每一处都对应一个「漏了就静默降级」的守卫 ——
  * 价格覆盖漏了 ⇒ 子 agent 用同一模型退化成「未定价」、`maxCostUsd` 静默失效；预算/超时上限
- * 漏了 ⇒ 护栏在子循环里离线；`abandoned` 漏了 ⇒ 超时后没人通知工具「别等了」。
+ * 漏了 ⇒ 护栏在子循环里离线；`abandoned` 漏了 ⇒ 超时后没人通知工具「别等了」；
+ * `deferUntil` 漏了 ⇒ 工具调用它当场 TypeError（工具契约里它有值，不是可选装饰）。
  *
  * 判定用哪一种是**语义**，不是风格，单测逐项钉住：
  * - `signal` / `priceOverrides` / `onUnpricedModel` 用**真值**判定；
- * - `maxEventChars` / `maxTotalTokens` / `maxCostUsd` / `toolTimeoutMs` 用**非空**判定 ——
- *   因为 `false`（不截断）与 `0`（不限/不超时）都是**有意义的值**，真值判定会把它们吃掉；
- * - `approval` 用 `!== undefined`：批/拒的决定要原样带给工具体（审计与分级授权用）。
+ * - `maxEventChars` / `traceContent` / `maxTotalTokens` / `maxCostUsd` / `toolTimeoutMs`
+ *   用**非空**判定 —— 因为 `false`（不截断）与 `0`（不限/不超时）都是**有意义的值**，
+ *   真值判定会把它们吃掉；
+ * - `approval` 用 `!== undefined`：批/拒的决定要原样带给工具体（审计与分级授权用）；
+ * - `deferUntil` 用真值判定：它是函数，没有「`false` = 有意义」这一档。
  *
  * 纯的边界：只做取值搬运，不读 ctx、不碰 recorder、不执行工具。
  */
@@ -25,8 +28,10 @@ export declare function buildToolRunContext(opts: {
     priceOverrides?: ToolRunContext['priceOverrides'];
     onUnpricedModel?: ToolRunContext['onUnpricedModel'];
     maxEventChars?: ToolRunContext['maxEventChars'];
+    traceContent?: ToolRunContext['traceContent'];
     maxTotalTokens?: ToolRunContext['maxTotalTokens'];
     maxCostUsd?: ToolRunContext['maxCostUsd'];
     toolTimeoutMs?: ToolRunContext['toolTimeoutMs'];
     approval?: ToolRunContext['approval'];
+    deferUntil?: ToolRunContext['deferUntil'];
 }): ToolRunContext;

package/dist/engine/tool-context.js

@@ -1,5 +1,5 @@
 export function buildToolRunContext(opts) {
-    const { client, recorder, parentSpanId, abandoned, signal, priceOverrides, onUnpricedModel, maxEventChars, maxTotalTokens, maxCostUsd, toolTimeoutMs, approval, } = opts;
+    const { client, recorder, parentSpanId, abandoned, signal, priceOverrides, onUnpricedModel, maxEventChars, traceContent, maxTotalTokens, maxCostUsd, toolTimeoutMs, approval, deferUntil, } = opts;
     return {
         client,
         recorder,
@@ -9,10 +9,14 @@ export function buildToolRunContext(opts) {
         ...(priceOverrides ? { priceOverrides } : {}),
         ...(onUnpricedModel ? { onUnpricedModel } : {}),
         ...(maxEventChars != null ? { maxEventChars } : {}),
+        ...(traceContent != null ? { traceContent } : {}),
         ...(maxTotalTokens != null ? { maxTotalTokens } : {}),
         ...(maxCostUsd != null ? { maxCostUsd } : {}),
         ...(toolTimeoutMs != null ? { toolTimeoutMs } : {}),
         ...(approval !== undefined ? { approval } : {}),
+        // 真值判定：它是个函数，没有 `false` / `0` 这类有意义的值（与上面那批「非空判定」的
+        // 旋钮不同类）；装配点永远给一份，缺它只可能是「这条路径不走回合」（如 MCP 反向桥）
+        ...(deferUntil ? { deferUntil } : {}),
     };
 }
 //# sourceMappingURL=tool-context.js.map

package/dist/engine/tool-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../src/engine/tool-context.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,mBAAmB,CAAC,IAanC;IACC,MAAM,EACJ,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,MAAM,EACN,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,UAAU,EACV,aAAa,EACb,QAAQ,GACT,GAAG,IAAI,CAAC;IACT,OAAO;QACL,MAAM;QACN,QAAQ;QACR,YAAY;QACZ,SAAS;QACT,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../src/engine/tool-context.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,mBAAmB,CAAC,IAenC;IACC,MAAM,EACJ,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,MAAM,EACN,cAAc,EACd,eAAe,EACf,aAAa,EACb,YAAY,EACZ,cAAc,EACd,UAAU,EACV,aAAa,EACb,QAAQ,EACR,UAAU,GACX,GAAG,IAAI,CAAC;IACT,OAAO;QACL,MAAM;QACN,QAAQ;QACR,YAAY;QACZ,SAAS;QACT,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,mDAAmD;QACnD,8CAA8C;QAC9C,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC"}

package/dist/engine/tracer.d.ts

@@ -2,18 +2,32 @@ import type { SpanError, SpanId, SpanKind, SpanLink, SpanStatus, Trace, TraceId,
 /**
  * 记账的**数量上限**（spec §9.4 的答案里「让少记了数据可数」那一半）。
  *
- * 只有 `maxEvents` 一个旋钮，而且它管的是**整条 trace 的事件总数**
- * （`tool.input` / `tool.output` / `score` / … 都算）—— 因为成本就是整条 trace 的量。
+ * 只有 `maxEvents` 一个旋钮，而且它管的是**整条 trace 的记录事件数**
+ * （`tool.input` / `tool.output` / `score` / … 都算，截断簿记那两笔不算）
+ * —— 因为成本就是整条 trace 的量。
  * 与 `maxEventChars`（**单个事件正文长度**）是两个正交的旋钮，各有各的家：
  * 一个管「多长」，一个管「多少」；两个都「不设 = 不限」。
  *
- * 超限后的行为是**停止记账 + 记一笔 `trace.truncated`**（交付时写在 run 根上：
- * `{ droppedEvents, limit }`）—— 缺口位置可预测（尾巴），且有计数 ⇒ 可解释。
+ * 超限后：**停止记账**（记录事件不再进 trace），并在 run 根上留**两笔**同名 `trace.truncated`
+ * 簿记 —— 按 body 区分（两笔都同时出现在交付的 trace 与增量流里，见下）：
+ * - **起点标记** `{ limit }`：第一笔丢弃那一刻写下，标「从这里起有缺」（位置信号）；
+ * - **收尾摘要** `{ droppedEvents, limit }`：`snapshot()` 交付时才写得出的最终计数。
+ * 缺口位置可预测（尾巴），且有计数 ⇒ 可解释。
+ *
+ * ⚠️ 两笔都**必须**进 `span.events`（而不是只派给增量订阅者）：`core/trace.ts` 那条
+ * **折叠规则**（按 `seq` 折回逐字等于 `snapshot()`）是钉住的契约，只在一条缝上出现的事件
+ * 会让它在「设了上限且真截断」的 run 上变成假话。纯 `onTraceEvent` 的消费者因此也不再
+ * 面对一个静默的洞（2026-09-28 外部深评 P3-1；落点由 PR #164 复核 §4 定为「两缝同源」）。
+ *
  * 刻意**不做**环形缓冲（丢最旧、留最近）：那会让 trace 中间出现空洞，
  * 而空洞比「尾巴截断」难解释得多（「这一回合怎么没有工具事件」）。
  */
 export interface TraceLimits {
-    /** 整条 trace 的事件总数上限；`0` = 一条都不记（有意义的值，仍有计数）；不设 = 不限 */
+    /**
+     * **记录事件**的条数上限；`0` = 一条都不记（有意义的值，仍有计数）；不设 = 不限。
+     * ⚠️ 这个计数**不含**上面那两笔 `trace.truncated` 簿记（它们是「关于记账」的簿记，不是被
+     * 记录的事实）⇒ 真截断时这条 trace 的事件数最多 `maxEvents + 2`。
+     */
     maxEvents?: number;
 }
 /**
@@ -35,6 +49,7 @@ export interface TraceRecorderOptions {
  * 一次 run 一个 recorder；run 与 trace 1:1。
  */
 export declare class TraceRecorder {
+    #private;
     readonly traceId: TraceId;
     private readonly spans;
     private readonly index;
@@ -47,6 +62,12 @@ export declare class TraceRecorder {
     private recordedEvents;
     /** 因超限被丢弃的事件数（交付时写进 run 根的 `trace.truncated`） */
     private droppedEvents;
+    /**
+     * 收尾摘要是否已派给增量出口。`snapshot()` 交付时派**一次**（见该方法的注释）：
+     * 一次 run 只交付一次，但这个方法可以被调用多次（错误出口 / MCP / 引擎各一处），
+     * 重复派发会让增量流里出现两条摘要 ⇒ 折回的树与交付的树又对不上。
+     */
+    private truncationSummarySent;
     /** 记账事件订阅者（增量出口，见 `core/trace.ts` 的 `TraceRecordEvent`） */
     private readonly listeners;
     /**
@@ -98,6 +119,23 @@ export declare class TraceRecorder {
     /** 子孙里所有 `llm.turn` 的 usage 之和（不含自身）；无任何计量时返回 undefined */
     private aggregateDescendantUsage;
     event(id: SpanId, name: string, body: unknown): void;
+    /**
+     * 给 span 记一条属性（`key` 自由、`value` 三态）。
+     *
+     * ⚠️ **口径如实（2026-09-28 外部深评 E7）**：本方法**不过** `maxEvents` 那道数量闸
+     * （上面 `event()` 才过），属性值也**不做** `maxEventChars` 截断。所以「超限即停记」这句话
+     * 的射程是**事件**（`span.events`），不是属性（`span.attributes`）。
+     *
+     * 实际有界的部分（别把它读成「无界」）：`turn.ts` 的 `traceContent:'full'` 正文**确实**按
+     * `maxEventChars` 截断；属性**条数**受调用点上限约束（turns ≤ `maxIterations`、
+     * 一次工具调用 ≤ 2 条、run 根的 `tools.names` / `labels.*` 由调用方在 run 入口给）。
+     * 真正「由调用方决定大小」的是 run 入口那几条（`labels.*` 的值、`tools.names` 的拼接结果）。
+     *
+     * ⚠️ **别顺手给它加截断**：属性是**交付的 trace** 与增量流共用的同一份载荷，
+     * 而 `core/trace.ts` 那条折叠契约（按 `seq` 折回**逐字等于** `snapshot()`）的两端就是它们 ——
+     * 只截一侧就当场毁掉那条契约（`tests/engine/trace-events.test.ts` 钉着它）。
+     * 要收就收「run 入口那几条的入参大小」，见 §10 ⑳ 的取舍。
+     */
     setAttribute(id: SpanId, key: string, value: string | number | boolean): void;
     /**
      * 给 span 记一条跨 trace 的链路引用（入站触发来源，见 `core/trace.ts` 的 `TraceContext`）。

package/dist/engine/tracer.js

@@ -40,6 +40,12 @@ export class TraceRecorder {
     recordedEvents = 0;
     /** 因超限被丢弃的事件数（交付时写进 run 根的 `trace.truncated`） */
     droppedEvents = 0;
+    /**
+     * 收尾摘要是否已派给增量出口。`snapshot()` 交付时派**一次**（见该方法的注释）：
+     * 一次 run 只交付一次，但这个方法可以被调用多次（错误出口 / MCP / 引擎各一处），
+     * 重复派发会让增量流里出现两条摘要 ⇒ 折回的树与交付的树又对不上。
+     */
+    truncationSummarySent = false;
     /** 记账事件订阅者（增量出口，见 `core/trace.ts` 的 `TraceRecordEvent`） */
     listeners = [];
     /**
@@ -206,9 +212,11 @@ export class TraceRecorder {
         const span = this.index.get(id);
         if (!span)
             return; // 未知 span 静默忽略（见类注释的容错策略）—— 增量出口同样不派发
-        // 数量闸（traceLimits.maxEvents）：超限即**停止记账**，并只记一个计数 ——
-        // 计数在 snapshot() 交付时写成 run 根的 `trace.truncated`（见 TraceLimits 的注释）。
+        // 数量闸（traceLimits.maxEvents）：超限即**停止记账**（记录事件不再进 trace）——
+        // 但「缺口」本身要**在两条缝上都看得见**（2026-09-28 外部深评 P3-1；PR #164 复核 §4 改了落点）。
         if (this.maxEvents !== undefined && this.recordedEvents >= this.maxEvents) {
+            if (this.droppedEvents === 0)
+                this.#markTruncationStart();
             this.droppedEvents += 1;
             return;
         }
@@ -217,6 +225,52 @@ export class TraceRecorder {
         span.events.push(event);
         this.emit({ type: 'span.event', spanId: id, event: { ...event } });
     }
+    /**
+     * 截断**开始**那一刻的簿记（只在第一笔丢弃时调一次）：在 run 根上记一条
+     * `trace.truncated { limit }` —— 它**同时进 `span.events` 与增量流**（两处同一份载荷）。
+     *
+     * 为什么要进 `span.events`（而不是「只派给增量订阅者」）：`core/trace.ts` 那条**折叠规则**
+     * 是钉住的契约 —— 「按 `seq` 折回必须逐字等于 `snapshot()`」。只要有一笔只出现在增量流里、
+     * 不出现在交付的 trace 里（或反过来），那条契约在**设了 `maxEvents` 且真截断**的 run 上就是假的。
+     * 这个 bug 的形态很隐蔽：默认不设上限 ⇒ 折叠用例永远碰不到 ⇒ 全绿。
+     *
+     * 两条纪律：
+     * - **不占** `recordedEvents` 配额（那是「被记录的事实」的上限；本事件是**关于**记账的簿记）
+     *   ⇒ 截断时 trace 的事件数最多 `maxEvents + 2`（本条 + 收尾摘要）；
+     * - 落在 **run 根**，不是「当时正在记的那条 span」：配额是**整条 trace 的**，「从哪里断」
+     *   因此是 trace 级的陈述，不是某条 span 的属性。
+     *
+     * 与收尾摘要的分工（两者同名 `trace.truncated`，按 body 区分，见 `TraceLimits` 的注释）：
+     * 这条是**位置**信号（`{ limit }`，断点在这里），收尾摘要是**计数**（`{ droppedEvents, limit }`）。
+     */
+    #markTruncationStart() {
+        const rootId = this.rootSpanId;
+        if (!rootId)
+            return; // 没有 run 根（不该发生）：与收尾摘要的 `root?` 同款，不记也不派
+        const root = this.index.get(rootId);
+        if (!root)
+            return;
+        const marker = { time: Date.now(), name: 'trace.truncated', body: { limit: this.maxEvents } };
+        root.events.push(marker);
+        this.emit({ type: 'span.event', spanId: rootId, event: { ...marker } });
+    }
+    /**
+     * 给 span 记一条属性（`key` 自由、`value` 三态）。
+     *
+     * ⚠️ **口径如实（2026-09-28 外部深评 E7）**：本方法**不过** `maxEvents` 那道数量闸
+     * （上面 `event()` 才过），属性值也**不做** `maxEventChars` 截断。所以「超限即停记」这句话
+     * 的射程是**事件**（`span.events`），不是属性（`span.attributes`）。
+     *
+     * 实际有界的部分（别把它读成「无界」）：`turn.ts` 的 `traceContent:'full'` 正文**确实**按
+     * `maxEventChars` 截断；属性**条数**受调用点上限约束（turns ≤ `maxIterations`、
+     * 一次工具调用 ≤ 2 条、run 根的 `tools.names` / `labels.*` 由调用方在 run 入口给）。
+     * 真正「由调用方决定大小」的是 run 入口那几条（`labels.*` 的值、`tools.names` 的拼接结果）。
+     *
+     * ⚠️ **别顺手给它加截断**：属性是**交付的 trace** 与增量流共用的同一份载荷，
+     * 而 `core/trace.ts` 那条折叠契约（按 `seq` 折回**逐字等于** `snapshot()`）的两端就是它们 ——
+     * 只截一侧就当场毁掉那条契约（`tests/engine/trace-events.test.ts` 钉着它）。
+     * 要收就收「run 入口那几条的入参大小」，见 §10 ⑳ 的取舍。
+     */
     setAttribute(id, key, value) {
         const span = this.index.get(id);
         if (!span)
@@ -284,16 +338,25 @@ export class TraceRecorder {
             events: [...s.events],
             ...(s.links ? { links: [...s.links] } : {}),
         }));
-        // 截断摘要：**交付时**写在 run 根上（与 totalUsage 同族 —— 都是「跑完才算得出的结论」，
-        // 不是记账动作）。所以它**不在**增量事件流里：折叠不变量管的是「记账动作不丢不重」，
-        // 而这是一个派生结论，增量消费者靠 `droppedEvents > 0` 自己判（见 TraceLimits）。
+        // 截断摘要：**交付时**才写得出的结论（与 totalUsage 同族），写在 run 根上。
+        // 它也**走增量出口**（2026-09-28 PR #164 复核 §4）：否则「按 seq 折回的那棵树」会少这一笔
+        // —— 只要设了 `maxEvents` 且真截断，`core/trace.ts` 那条折叠规则就是**假的**（此前没有
+        // 用例覆盖到：默认不设上限，折叠用例永远碰不到截断）。同一对象两处用 ⇒ 时间戳逐字一致；
+        // 只派一次 ⇒ 重复交付不会让增量流里多出一条。
         if (this.droppedEvents > 0) {
             const root = spans.find((s) => s.spanId === this.rootSpanId);
-            root?.events.push({
-                time: Date.now(),
-                name: 'trace.truncated',
-                body: { droppedEvents: this.droppedEvents, limit: this.maxEvents },
-            });
+            if (root) {
+                const summary = {
+                    time: Date.now(),
+                    name: 'trace.truncated',
+                    body: { droppedEvents: this.droppedEvents, limit: this.maxEvents },
+                };
+                root.events.push(summary);
+                if (!this.truncationSummarySent) {
+                    this.truncationSummarySent = true;
+                    this.emit({ type: 'span.event', spanId: this.rootSpanId, event: { ...summary } });
+                }
+            }
         }
         return {
             traceId: this.traceId,