@migor/agentia 0.10.2 → 0.10.4

package/dist/core/limits.d.ts

@@ -142,6 +142,22 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zeroClause: '0 = 不重试';
     readonly badValue: 'throws';
     readonly note: '坏值必须响亮失败：判定是 `attempt >= maxRetries` ⇒ `NaN` 比较恒假、`Infinity` 永远达不到，两者都是**无限重试**（429 场景下每一次都是真金白银）；`-1` 静默变成「不重试」；`1.5` 实际只允许 1 次。';
+}, {
+    readonly knob: 'RetryOptions.maxAttempts';
+    readonly where: 'engine/retry.ts（resolveRetry）';
+    readonly unit: 'count';
+    readonly zero: 'disabled';
+    readonly zeroClause: '0 = 关闭重试';
+    readonly badValue: 'throws';
+    readonly note: '含首次尝试（1 = 只试一次不重试）。⚠️ 2026-10-13 深评 A1 补登 + 补校验：`maxAttempts: NaN` 曾让 `!(NaN >= 1)` 成立 ⇒ 重试被**静默关闭**，run 根快照记 `config.retry.maxAttempts: 0`，看着像用户主动关的；与 client 层 maxRetries 同纪律改为 `resolveRetry` 抛 TypeError（runAgent 入口另有一次同款校验，配置错不收成「失败的 run」）。';
+}, {
+    readonly knob: 'RetryOptions.jitter';
+    readonly where: 'engine/retry.ts（resolveRetry）';
+    readonly unit: 'n/a';
+    readonly zero: 'disabled';
+    readonly zeroClause: '0 = 不加抖动';
+    readonly badValue: 'throws';
+    readonly note: '抖动比例 0~1。>1 会把退避拉成负数再被 `Math.max(0, …)` 静默钳回 0（抖动与退避一起失效，429 场景变热重试）；NaN 让退避算成 NaN。2026-10-13 深评 A1 补登。';
 }, {
     readonly knob: 'maxEventChars';
     readonly where: 'engine/tool-events.ts';
@@ -198,6 +214,22 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zeroClause: '0 = 立即导出';
     readonly badValue: 'none';
     readonly note: '⚠️ **同名反义**：`Scheduler.every` 的 `intervalMs: 0` 是**配置错误**（抛错），这里却是「关掉定时器、每次累加后立即导出」。两个同名旋钮两种读法 —— 改任何一个之前先看这张表。';
+}, {
+    readonly knob: 'RetryOptions.baseDelayMs';
+    readonly where: 'engine/retry.ts（resolveRetry）';
+    readonly unit: 'ms';
+    readonly zero: 'immediate';
+    readonly zeroClause: '0 = 不退避（立即重试）';
+    readonly badValue: 'throws';
+    readonly note: '⚠️ 2026-10-13 深评 A1 补登 + 补校验：`baseDelayMs: NaN` 让 backoffDelay 算出 NaN ⇒ `interruptibleSleep` 的 `assertTimerDelay` 抛 RangeError —— 它曾被 turn.ts 退避处的裸 `catch` 吞成「用户取消」（配置错被谎报成取消，实测 `retry:{baseDelayMs:NaN}` + 429 → stopReason:aborted）。超 2^31-1ms 同理拒（Node 钳到 1ms ⇒ 热重试；上限单源 core/timeout.ts）。';
+}, {
+    readonly knob: 'RetryOptions.maxDelayMs';
+    readonly where: 'engine/retry.ts（resolveRetry）';
+    readonly unit: 'ms';
+    readonly zero: 'immediate';
+    readonly zeroClause: '0 = 退避封顶为零（立即重试）';
+    readonly badValue: 'throws';
+    readonly note: '同 baseDelayMs：NaN 穿透 `Math.min` 让封顶失效（`Math.min(x, NaN)` = NaN）；超上限被 Node 钳到 1ms。2026-10-13 深评 A1 补登。⚠️ 正向抖动可能把最终退避推过 maxDelayMs（±jitter 是有意的），但 `backoffDelay` 会把它夹在 2^31-1ms 以内，sleep 不会因此抛。';
 }, {
     readonly knob: 'BudgetGuardOptions.maxTotalTokens';
     readonly where: 'engine/budget.ts（createBudgetGuard；由 RunAgentOptions.maxTotalTokens 传进来）';
@@ -325,7 +357,7 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zero: 'invalid';
     readonly zeroClause: '0 = 一个标签组合都认不下，全折进一个桶';
     readonly badValue: 'throws';
-    readonly note: '**组合数**上限（2026-09-27 ⑧ 补的第四条基数上限）。`maxLabelValues` 只封每个键的**值域**，而进内存的是组合，数量是叉乘 `(maxLabelValues+1)^labelKeys.length` —— 缺省 100 × 3 键就是一百万条，且每键的 dropped 计数看不见它。与另外三道同款：超限折进一个全 `__other__` 的桶（量不丢），折叠数见 `droppedLabelCombos` / `dropped_keys{kind="label:combos"}`。';
+    readonly note: '**组合数**上限（2026-09-27 ref-menu-drift-signals 补的第四条基数上限）。`maxLabelValues` 只封每个键的**值域**，而进内存的是组合，数量是叉乘 `(maxLabelValues+1)^labelKeys.length` —— 缺省 100 × 3 键就是一百万条，且每键的 dropped 计数看不见它。与另外三道同款：超限折进一个全 `__other__` 的桶（量不丢），折叠数见 `droppedLabelCombos` / `dropped_keys{kind="label:combos"}`。';
 }];
 /** 表里全部旋钮的标识（用例按它建穷尽表：少一项 `typecheck:tests` 就红） */
 export type LimitKnob = (typeof LIMIT_SEMANTICS)[number]['knob'];

package/dist/core/limits.js

@@ -105,6 +105,24 @@ export const LIMIT_SEMANTICS = [
         badValue: 'throws',
         note: '坏值必须响亮失败：判定是 `attempt >= maxRetries` ⇒ `NaN` 比较恒假、`Infinity` 永远达不到，两者都是**无限重试**（429 场景下每一次都是真金白银）；`-1` 静默变成「不重试」；`1.5` 实际只允许 1 次。',
     },
+    {
+        knob: 'RetryOptions.maxAttempts',
+        where: 'engine/retry.ts（resolveRetry）',
+        unit: 'count',
+        zero: 'disabled',
+        zeroClause: '0 = 关闭重试',
+        badValue: 'throws',
+        note: '含首次尝试（1 = 只试一次不重试）。⚠️ 2026-10-13 深评 A1 补登 + 补校验：`maxAttempts: NaN` 曾让 `!(NaN >= 1)` 成立 ⇒ 重试被**静默关闭**，run 根快照记 `config.retry.maxAttempts: 0`，看着像用户主动关的；与 client 层 maxRetries 同纪律改为 `resolveRetry` 抛 TypeError（runAgent 入口另有一次同款校验，配置错不收成「失败的 run」）。',
+    },
+    {
+        knob: 'RetryOptions.jitter',
+        where: 'engine/retry.ts（resolveRetry）',
+        unit: 'n/a',
+        zero: 'disabled',
+        zeroClause: '0 = 不加抖动',
+        badValue: 'throws',
+        note: '抖动比例 0~1。>1 会把退避拉成负数再被 `Math.max(0, …)` 静默钳回 0（抖动与退避一起失效，429 场景变热重试）；NaN 让退避算成 NaN。2026-10-13 深评 A1 补登。',
+    },
     {
         knob: 'maxEventChars',
         where: 'engine/tool-events.ts',
@@ -169,6 +187,24 @@ export const LIMIT_SEMANTICS = [
         badValue: 'none',
         note: '⚠️ **同名反义**：`Scheduler.every` 的 `intervalMs: 0` 是**配置错误**（抛错），这里却是「关掉定时器、每次累加后立即导出」。两个同名旋钮两种读法 —— 改任何一个之前先看这张表。',
     },
+    {
+        knob: 'RetryOptions.baseDelayMs',
+        where: 'engine/retry.ts（resolveRetry）',
+        unit: 'ms',
+        zero: 'immediate',
+        zeroClause: '0 = 不退避（立即重试）',
+        badValue: 'throws',
+        note: '⚠️ 2026-10-13 深评 A1 补登 + 补校验：`baseDelayMs: NaN` 让 backoffDelay 算出 NaN ⇒ `interruptibleSleep` 的 `assertTimerDelay` 抛 RangeError —— 它曾被 turn.ts 退避处的裸 `catch` 吞成「用户取消」（配置错被谎报成取消，实测 `retry:{baseDelayMs:NaN}` + 429 → stopReason:aborted）。超 2^31-1ms 同理拒（Node 钳到 1ms ⇒ 热重试；上限单源 core/timeout.ts）。',
+    },
+    {
+        knob: 'RetryOptions.maxDelayMs',
+        where: 'engine/retry.ts（resolveRetry）',
+        unit: 'ms',
+        zero: 'immediate',
+        zeroClause: '0 = 退避封顶为零（立即重试）',
+        badValue: 'throws',
+        note: '同 baseDelayMs：NaN 穿透 `Math.min` 让封顶失效（`Math.min(x, NaN)` = NaN）；超上限被 Node 钳到 1ms。2026-10-13 深评 A1 补登。⚠️ 正向抖动可能把最终退避推过 maxDelayMs（±jitter 是有意的），但 `backoffDelay` 会把它夹在 2^31-1ms 以内，sleep 不会因此抛。',
+    },
     {
         knob: 'BudgetGuardOptions.maxTotalTokens',
         where: 'engine/budget.ts（createBudgetGuard；由 RunAgentOptions.maxTotalTokens 传进来）',
@@ -312,7 +348,7 @@ export const LIMIT_SEMANTICS = [
         zero: 'invalid',
         zeroClause: '0 = 一个标签组合都认不下，全折进一个桶',
         badValue: 'throws',
-        note: '**组合数**上限（2026-09-27 ⑧ 补的第四条基数上限）。`maxLabelValues` 只封每个键的**值域**，而进内存的是组合，数量是叉乘 `(maxLabelValues+1)^labelKeys.length` —— 缺省 100 × 3 键就是一百万条，且每键的 dropped 计数看不见它。与另外三道同款：超限折进一个全 `__other__` 的桶（量不丢），折叠数见 `droppedLabelCombos` / `dropped_keys{kind="label:combos"}`。',
+        note: '**组合数**上限（2026-09-27 ref-menu-drift-signals 补的第四条基数上限）。`maxLabelValues` 只封每个键的**值域**，而进内存的是组合，数量是叉乘 `(maxLabelValues+1)^labelKeys.length` —— 缺省 100 × 3 键就是一百万条，且每键的 dropped 计数看不见它。与另外三道同款：超限折进一个全 `__other__` 的桶（量不丢），折叠数见 `droppedLabelCombos` / `dropped_keys{kind="label:combos"}`。',
     },
 ];
 /** 按旋钮取那行（拼错旋钮名 = 编译期报错，不是运行期 undefined） */

package/dist/core/limits.js.map

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

package/dist/core/run.d.ts

@@ -10,7 +10,7 @@ import type { SpanError } from './trace.js';
  * 收尾释放）、`resumePending` 不捡走（它不是孤儿，崩溃续跑语义不适用于「在等」）；
  * 消息历史（含未决 tool_use）与待决清单随 TaskRecord 落库。
  *
- * 「挂起」是**一个状态 + 一个原因**（2026-09-28 ①：从前 `awaiting_approval` 一个状态兼职
+ * 「挂起」是**一个状态 + 一个原因**（2026-09-28 ref-suspend-state-reason：从前 `awaiting_approval` 一个状态兼职
  * 两件事）：状态只说「它在等」，等什么由 `SuspendedReason` 说 —— 判据（审批超时 / 能否
  * 审批）落在**原因**上，于是「时间挂起被审批超时提前叫醒」这类误伤在类型上就写不出来。
  */
@@ -41,7 +41,7 @@ export type SuspendedReason = 'approval' | 'timer';
 /** 该状态是否已到终态（不会再变）。判定只此一处 —— 别在调用点重写。 */
 export declare function isTerminalStatus(status: RunStatus): boolean;
 /**
- * run 事件（2026-09-28 ⑥，run 事件投入口）：外部系统投给一条**挂起** run 的一条输入
+ * run 事件（2026-09-28 ref-run-event-input，run 事件投入口）：外部系统投给一条**挂起** run 的一条输入
  * （`AsyncRunner.signalTask` / `POST /tasks/:id/events`；审批是它的特例）。
  *
  * 白名单形状（设计稿 B1）：**全是字符串** —— 外部永远不能构造消息块，投毒面只到

package/dist/core/timeout.d.ts

@@ -4,7 +4,7 @@
  * 为什么在 core：engine 的工具级超时（`engine/turn.ts`）与桥的 MCP 调用超时
  * （`integrations/mcp.ts`）**必须共用同一套判定**。此前两处各写一份，代价是
  * 2026-09-14 的「硬保证」收紧只落进了 `engine/concurrency.ts`，桥那一份继续用竞速判定 ——
- * 同一个承诺两套实现，于是同一个事件在 trace 里能有两种账（见 `docs/spec.md` §10 2026-09-17 ①）。
+ * 同一个承诺两套实现，于是同一个事件在 trace 里能有两种账（见 `docs/spec.md` §10 2026-09-17 ref-mcp-timeout-single-source）。
  * `integrations` 只能依赖 core（`tests/architecture/layering.test.ts` 强制），
  * 所以单源的落点是 core。core 是叶子：本文件只 import `limits.js`（**纯数据表，零 import**）
  * —— 2026-09-28 起它要 `zeroClauseOf`：两处 `assertTimerDelay` 的文案必须与 limits 表同源
@@ -26,7 +26,7 @@ export declare const TIMED_OUT: unique symbol;
  * `withTimeout`（引擎 `toolTimeoutMs`）、`interruptibleSleep`（退避）、
  * `DrainGate.waitForIdle`（drain 预算）、`#raceTimeout`（`runTimeoutMs`）、
  * `composeSignal`（client `timeout`）五处都直喂 `setTimeout` 且只查「非负有限」。
- * 单源收在这里（见 `docs/spec.md` §10 2026-09-28 ⑪）。
+ * 单源收在这里（见 `docs/spec.md` §10 2026-09-28 ref-timer-cap-single-source）。
  */
 export declare const MAX_TIMER_DELAY_MS = 2147483647;
 /**
@@ -58,7 +58,7 @@ export declare function clampTimerDelay(ms: number): number;
  * 为什么需要它：超时此前只能靠**错误文案**辨认 —— 桥抛的是普通 `Error`，而
  * `classifyError` 里没有 timeout 这一类，于是 trace 里记成 `error(unknown)` +
  * `errorKind=threw`，与引擎自己判的超时（`error(timeout)` + `errorKind=timeout`）
- * 成为同一事件的**两种账**（见 `docs/spec.md` §10 2026-09-17 ①）。
+ * 成为同一事件的**两种账**（见 `docs/spec.md` §10 2026-09-17 ref-mcp-timeout-single-source）。
  *
  * 判定契约（对使用者可见）：**任何** `code === 'timeout'` 的错误都会被引擎归为
  * `errorKind='timeout'`，不需要 import 这个类（`isTimeoutError` 也认鸭子类型）。
@@ -87,7 +87,7 @@ export declare function abortError(message?: string): Error;
  *
  * 为什么第 3 条也算：`engine/errors.ts` 的分类**此前只有它**认这一条（当时把超时归进 `connection`），
  * 于是「超时」在 trace 里混在「连不上」里，看板与 `trace-diff` 分不出两者。现在超时有自己的
- * `type: 'timeout'`，这条判据由分类与工具级记账**共用**，口径一致（spec §10 2026-09-17 ②）。
+ * `type: 'timeout'`，这条判据由分类与工具级记账**共用**，口径一致（spec §10 2026-09-17 ref-timeout-error-type）。
  */
 export declare function isTimeoutError(e: unknown): boolean;
 /**
@@ -128,7 +128,7 @@ export declare function withTimeout<T>(p: Promise<T>, timeoutMs: number): Promis
  * 不必再等）与 `integrations/anthropic.ts` 的 `interruptibleSleep`（client 层退避）。
  * 那边此前自带一段「与 engine/retry.ts 的 sleep 同语义但不复用它 —— 分层约束：
  * integrations 只能依赖 core」的注解：**正是那条约束把两份代码逼成了重复**，
- * 所以下沉到 core 是让它们合一的唯一合法落点（见 spec §10 2026-09-17 ① 的单源化口径）。
+ * 所以下沉到 core 是让它们合一的唯一合法落点（见 spec §10 2026-09-17 ref-mcp-timeout-single-source 的单源化口径）。
  *
  * ⚠️ 「不合并退避计算器」的例外只针对**引擎层**：`engine/retry.ts` 的 `backoffDelay`
  * 是 ±20% 均匀抖动、底数/上限来自 `RetryOptions`，与 client 层策略不同（见下方

package/dist/core/timeout.js

@@ -4,7 +4,7 @@
  * 为什么在 core：engine 的工具级超时（`engine/turn.ts`）与桥的 MCP 调用超时
  * （`integrations/mcp.ts`）**必须共用同一套判定**。此前两处各写一份，代价是
  * 2026-09-14 的「硬保证」收紧只落进了 `engine/concurrency.ts`，桥那一份继续用竞速判定 ——
- * 同一个承诺两套实现，于是同一个事件在 trace 里能有两种账（见 `docs/spec.md` §10 2026-09-17 ①）。
+ * 同一个承诺两套实现，于是同一个事件在 trace 里能有两种账（见 `docs/spec.md` §10 2026-09-17 ref-mcp-timeout-single-source）。
  * `integrations` 只能依赖 core（`tests/architecture/layering.test.ts` 强制），
  * 所以单源的落点是 core。core 是叶子：本文件只 import `limits.js`（**纯数据表，零 import**）
  * —— 2026-09-28 起它要 `zeroClauseOf`：两处 `assertTimerDelay` 的文案必须与 limits 表同源
@@ -27,7 +27,7 @@ export const TIMED_OUT = Symbol('agentia.timed-out');
  * `withTimeout`（引擎 `toolTimeoutMs`）、`interruptibleSleep`（退避）、
  * `DrainGate.waitForIdle`（drain 预算）、`#raceTimeout`（`runTimeoutMs`）、
  * `composeSignal`（client `timeout`）五处都直喂 `setTimeout` 且只查「非负有限」。
- * 单源收在这里（见 `docs/spec.md` §10 2026-09-28 ⑪）。
+ * 单源收在这里（见 `docs/spec.md` §10 2026-09-28 ref-timer-cap-single-source）。
  */
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /**
@@ -74,7 +74,7 @@ export function clampTimerDelay(ms) {
  * 为什么需要它：超时此前只能靠**错误文案**辨认 —— 桥抛的是普通 `Error`，而
  * `classifyError` 里没有 timeout 这一类，于是 trace 里记成 `error(unknown)` +
  * `errorKind=threw`，与引擎自己判的超时（`error(timeout)` + `errorKind=timeout`）
- * 成为同一事件的**两种账**（见 `docs/spec.md` §10 2026-09-17 ①）。
+ * 成为同一事件的**两种账**（见 `docs/spec.md` §10 2026-09-17 ref-mcp-timeout-single-source）。
  *
  * 判定契约（对使用者可见）：**任何** `code === 'timeout'` 的错误都会被引擎归为
  * `errorKind='timeout'`，不需要 import 这个类（`isTimeoutError` 也认鸭子类型）。
@@ -108,7 +108,7 @@ export function abortError(message = '已被取消') {
  *
  * 为什么第 3 条也算：`engine/errors.ts` 的分类**此前只有它**认这一条（当时把超时归进 `connection`），
  * 于是「超时」在 trace 里混在「连不上」里，看板与 `trace-diff` 分不出两者。现在超时有自己的
- * `type: 'timeout'`，这条判据由分类与工具级记账**共用**，口径一致（spec §10 2026-09-17 ②）。
+ * `type: 'timeout'`，这条判据由分类与工具级记账**共用**，口径一致（spec §10 2026-09-17 ref-timeout-error-type）。
  */
 export function isTimeoutError(e) {
     if (e instanceof TimeoutError)
@@ -199,7 +199,7 @@ export async function withTimeout(p, timeoutMs) {
  * 不必再等）与 `integrations/anthropic.ts` 的 `interruptibleSleep`（client 层退避）。
  * 那边此前自带一段「与 engine/retry.ts 的 sleep 同语义但不复用它 —— 分层约束：
  * integrations 只能依赖 core」的注解：**正是那条约束把两份代码逼成了重复**，
- * 所以下沉到 core 是让它们合一的唯一合法落点（见 spec §10 2026-09-17 ① 的单源化口径）。
+ * 所以下沉到 core 是让它们合一的唯一合法落点（见 spec §10 2026-09-17 ref-mcp-timeout-single-source 的单源化口径）。
  *
  * ⚠️ 「不合并退避计算器」的例外只针对**引擎层**：`engine/retry.ts` 的 `backoffDelay`
  * 是 ±20% 均匀抖动、底数/上限来自 `RetryOptions`，与 client 层策略不同（见下方

package/dist/core/tool.d.ts

@@ -155,7 +155,7 @@ export interface ToolRunContext {
      *
      * 存在的意义是**划定裁判权**：工具（尤其带自己计时器的桥，见 `integrations/mcp.ts`）
      * 据此知道「这次调用的超时由引擎判」，从而不再启动第二个计时器 —— 两个计时器判同一件事，
-     * 只会得到两种账（桥那份曾被记成 `error(unknown)` + `errorKind=threw`，见 spec §10 2026-09-17 ①）。
+     * 只会得到两种账（桥那份曾被记成 `error(unknown)` + `errorKind=threw`，见 spec §10 2026-09-17 ref-mcp-timeout-single-source）。
      *
      * ⚠️ 它是本次调用的**配置值**，不是「剩余时间」。
      */
@@ -193,7 +193,7 @@ export interface ToolRunContext {
      */
     approval?: ApprovalDecision;
     /**
-     * 「现在还不是时候，T 之后再问我」（durable timer，2026-09-28 ① 的 timer 侧）。
+     * 「现在还不是时候，T 之后再问我」（durable timer，2026-09-28 ref-suspend-state-reason 的 timer 侧）。
      * 工具在执行期调用它 = 请求**本回合到此为止**：引擎丢弃本回合这批工具的结果、
      * 把整批 tool_use 挂起（`stopReason: 'suspended'` + `suspendedReason: 'timer'` +
      * 目标时刻 `wakeAt`），到点后由宿主续跑并**重跑这一批**（与审批续跑的形态一致）。

package/dist/core/trace-sink.d.ts

@@ -0,0 +1,8 @@
+import type { Trace, TraceSink } from './trace.js';
+/** 单个 sink 的默认等待上限；超时只放弃等待，不取消底层导出。 */
+export declare const TRACE_SINK_TIMEOUT_MS = 10000;
+/**
+ * 顺序投递 trace。抛错与超时都只告警，不击穿业务；后续 sink 仍照常接收。
+ * module 级 export 供 runtime / MCP 反向桥共用，刻意不进公共导出面。
+ */
+export declare function flushTraceSinks(sinks: readonly TraceSink[] | undefined, trace: Trace, timeoutMs?: number): Promise<void>;

package/dist/core/trace-sink.js

@@ -0,0 +1,24 @@
+import { TIMED_OUT, withTimeout } from './timeout.js';
+/** 单个 sink 的默认等待上限；超时只放弃等待，不取消底层导出。 */
+export const TRACE_SINK_TIMEOUT_MS = 10_000;
+/**
+ * 顺序投递 trace。抛错与超时都只告警，不击穿业务；后续 sink 仍照常接收。
+ * module 级 export 供 runtime / MCP 反向桥共用，刻意不进公共导出面。
+ */
+export async function flushTraceSinks(sinks, trace, timeoutMs = TRACE_SINK_TIMEOUT_MS) {
+    if (!sinks || sinks.length === 0)
+        return;
+    for (const sink of sinks) {
+        try {
+            const delivery = Promise.resolve().then(() => sink.export(trace));
+            const outcome = await withTimeout(delivery, timeoutMs);
+            if (outcome === TIMED_OUT) {
+                console.warn(`[agentia] trace sink 投递超时（${timeoutMs}ms），已放弃等待（不取消底层导出）`);
+            }
+        }
+        catch (e) {
+            console.warn('[agentia] trace sink 投递失败:', e instanceof Error ? e.message : e);
+        }
+    }
+}
+//# sourceMappingURL=trace-sink.js.map

package/dist/core/trace-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-sink.js","sourceRoot":"","sources":["../../src/core/trace-sink.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEtD,uCAAuC;AACvC,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAuC,EACvC,KAAY,EACZ,SAAS,GAAG,qBAAqB;IAEjC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAClE,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YACvD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,CAAC,IAAI,CACV,6BAA6B,SAAS,oBAAoB,CAC3D,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/core/trace.d.ts

@@ -51,6 +51,15 @@ export declare const TOOL_OUTPUT_EVENT = "tool.output";
  * **替身值**（不是读数）—— 成本估算会把它读成「真的花了 0」，`maxCostUsd` 因此静默失效。
  */
 export declare const USAGE_MISSING_EVENT = "usage.missing";
+/**
+ * 「上下文策略在本回合开始前**真的压缩了**历史」事件名（body 带 `{ from, to, model }`）。
+ *
+ * 记账点在 `engine/turn.ts` 的回合入口检查（压缩发生时本回合的 llm.turn span 还不存在，
+ * 故事件记在回合的**父** span 上）；消费方是 `integrations/otlp.ts`
+ * （映射 `gen_ai.conversation.compacted`）。与 `TOOL_INPUT_EVENT` 同因单源：
+ * 跨 engine → integrations 的名字各写一份就是静默归零。
+ */
+export declare const CONTEXT_BUDGET_EVENT = "context.budget";
 /** 工具 I/O 事件名的联合 —— `eval/export.ts` 的工具事件过滤器按它取参数 */
 export type ToolIoEventName = typeof TOOL_INPUT_EVENT | typeof TOOL_OUTPUT_EVENT;
 /**
@@ -127,7 +136,7 @@ export declare function wireSpanId(id: string): string;
  * （采样闸门要看完好整棵 trace 才判得出来），而出站调用发生在**运行期** ——
  * 那时「这条 trace 会不会被采样掉」还没有答案。所以恒 `00` 是唯一不撒谎的选择
  * （`00` = 不声明「已采样」）；编一个 `01` 是替下游做决定。⚠️ 别下一轮「顺手」改成跟随采样
- * （见 `docs/spec.md` §10 2026-09-21 ⑦）。入站侧 `parseTraceparent` 也从不读 flags。
+ * （见 `docs/spec.md` §10 2026-09-21 ref-cost-sampling）。入站侧 `parseTraceparent` 也从不读 flags。
  *
  * 调用方保证给的是内部 id 或线缆 id（本函数只做投影，不做合法性判定）。
  */
@@ -201,7 +210,8 @@ export declare function attachScore(trace: Trace, score: Score): void;
 export declare function capabilityKindOf(span: Span): string;
 /**
  * trace 出口：run 收尾（成功或失败）后，框架把【完整 Trace】交给每个 sink。
- * sink 抛错由框架吞掉（吞之前落一条 console.warn 告警），绝不影响 run 结果（与 memory 回写同款防护）。
+ * sink 抛错或永久挂起都不影响 run 结果：抛错告警，超过默认 10 秒则告警并放弃等待；
+ * 放弃不等于取消底层导出，后续 sink 仍照常接收。
  * 形状与 OtlpExporter 一致 —— createOtlpExporter() 的返回值天然满足本接口。
  */
 export interface TraceSink {

package/dist/core/trace.js

@@ -28,6 +28,15 @@ export const TOOL_OUTPUT_EVENT = 'tool.output';
  * **替身值**（不是读数）—— 成本估算会把它读成「真的花了 0」，`maxCostUsd` 因此静默失效。
  */
 export const USAGE_MISSING_EVENT = 'usage.missing';
+/**
+ * 「上下文策略在本回合开始前**真的压缩了**历史」事件名（body 带 `{ from, to, model }`）。
+ *
+ * 记账点在 `engine/turn.ts` 的回合入口检查（压缩发生时本回合的 llm.turn span 还不存在，
+ * 故事件记在回合的**父** span 上）；消费方是 `integrations/otlp.ts`
+ * （映射 `gen_ai.conversation.compacted`）。与 `TOOL_INPUT_EVENT` 同因单源：
+ * 跨 engine → integrations 的名字各写一份就是静默归零。
+ */
+export const CONTEXT_BUDGET_EVENT = 'context.budget';
 /** 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})$/;
 /**
@@ -80,7 +89,7 @@ export function wireSpanId(id) {
  * （采样闸门要看完好整棵 trace 才判得出来），而出站调用发生在**运行期** ——
  * 那时「这条 trace 会不会被采样掉」还没有答案。所以恒 `00` 是唯一不撒谎的选择
  * （`00` = 不声明「已采样」）；编一个 `01` 是替下游做决定。⚠️ 别下一轮「顺手」改成跟随采样
- * （见 `docs/spec.md` §10 2026-09-21 ⑦）。入站侧 `parseTraceparent` 也从不读 flags。
+ * （见 `docs/spec.md` §10 2026-09-21 ref-cost-sampling）。入站侧 `parseTraceparent` 也从不读 flags。
  *
  * 调用方保证给的是内部 id 或线缆 id（本函数只做投影，不做合法性判定）。
  */

package/dist/core/trace.js.map

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

package/dist/engine/concurrency.d.ts

@@ -11,7 +11,7 @@ export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: num
 /**
  * 超时原语（`TIMED_OUT` 哨兵 + `withTimeout`）已**下沉到 `core/timeout.ts`**：
  * 它与 `integrations/mcp.ts` 的 MCP 调用超时共用同一实现 —— 此前是两份，而
- * 「超时是硬的」那次收紧只落进了这里，桥那份留在竞速判定上（见 `docs/spec.md` §10 2026-09-17 ①）。
+ * 「超时是硬的」那次收紧只落进了这里，桥那份留在竞速判定上（见 `docs/spec.md` §10 2026-09-17 ref-mcp-timeout-single-source）。
  *
  * 这里**原样再导出**：`engine/turn.ts` 与既有测试的 import 路径与名字保持不变，
  * 单源化对它们零影响。

package/dist/engine/concurrency.js

@@ -35,7 +35,7 @@ export async function mapWithConcurrency(items, limit, fn) {
 /**
  * 超时原语（`TIMED_OUT` 哨兵 + `withTimeout`）已**下沉到 `core/timeout.ts`**：
  * 它与 `integrations/mcp.ts` 的 MCP 调用超时共用同一实现 —— 此前是两份，而
- * 「超时是硬的」那次收紧只落进了这里，桥那份留在竞速判定上（见 `docs/spec.md` §10 2026-09-17 ①）。
+ * 「超时是硬的」那次收紧只落进了这里，桥那份留在竞速判定上（见 `docs/spec.md` §10 2026-09-17 ref-mcp-timeout-single-source）。
  *
  * 这里**原样再导出**：`engine/turn.ts` 与既有测试的 import 路径与名字保持不变，
  * 单源化对它们零影响。

package/dist/engine/errors.d.ts

@@ -14,14 +14,14 @@ import type { SpanError } from '../core/trace.js';
 /** 是否中断异常（DOMException / 普通 Error 都可能是，靠 name 判定） */
 export declare function isAbortError(e: unknown): boolean;
 /**
- * 分类器**能产出的全部类别** —— 单一真源（2026-09-29 ⑤）。
+ * 分类器**能产出的全部类别** —— 单一真源（2026-09-29 ref-soak-error-taxonomy）。
  *
  * 为什么需要这个常量：在此之前「到底有哪几类」只活在 `classifyError` 的字面量里，
  * 任何想按类别表态的地方（浸泡验证的判据、看板、`trace-diff`）都只能**再手写一份清单**，
  * 而漏一类的表现是**静默**的。实测过一次（就是加这个常量的原因）：
  * `scripts/e2e-soak.ts` 里手写的 `['api','server','rate_limit']` 漏了 `connection`，
  * 默认 60 秒的跑法永远撞不到 —— 而 2 小时那轮（719 万 run / 811 万请求）撞到 **1 次**
- * 就让整轮报红，红的是判据、不是被测的代码（spec §10 2026-09-29 ⑤）。
+ * 就让整轮报红，红的是判据、不是被测的代码（spec §10 2026-09-29 ref-soak-error-taxonomy）。
  *
  * 消费方式：`Record<ErrorType, …>` 的**穷尽表** —— 加一类而不表态 ⇒ `TS2741`
  * （与 `SUCCESS_STOP_REASON` / `KIND_SPEC` 同款护栏，见 `docs/guards.md`）。

package/dist/engine/errors.js

@@ -16,14 +16,14 @@ export function isAbortError(e) {
     return typeof e === 'object' && e !== null && e.name === 'AbortError';
 }
 /**
- * 分类器**能产出的全部类别** —— 单一真源（2026-09-29 ⑤）。
+ * 分类器**能产出的全部类别** —— 单一真源（2026-09-29 ref-soak-error-taxonomy）。
  *
  * 为什么需要这个常量：在此之前「到底有哪几类」只活在 `classifyError` 的字面量里，
  * 任何想按类别表态的地方（浸泡验证的判据、看板、`trace-diff`）都只能**再手写一份清单**，
  * 而漏一类的表现是**静默**的。实测过一次（就是加这个常量的原因）：
  * `scripts/e2e-soak.ts` 里手写的 `['api','server','rate_limit']` 漏了 `connection`，
  * 默认 60 秒的跑法永远撞不到 —— 而 2 小时那轮（719 万 run / 811 万请求）撞到 **1 次**
- * 就让整轮报红，红的是判据、不是被测的代码（spec §10 2026-09-29 ⑤）。
+ * 就让整轮报红，红的是判据、不是被测的代码（spec §10 2026-09-29 ref-soak-error-taxonomy）。
  *
  * 消费方式：`Record<ErrorType, …>` 的**穷尽表** —— 加一类而不表态 ⇒ `TS2741`
  * （与 `SUCCESS_STOP_REASON` / `KIND_SPEC` 同款护栏，见 `docs/guards.md`）。

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

@@ -26,7 +26,7 @@ export interface AgentLoopResult<T = unknown> {
     error: SpanError | undefined;
     /** 本轮循环自己发起的模型往返次数 */
     iterations: number;
-    /** submit_result 校验通过的结构化结果；未提交则为 undefined（类型由 resultSchema 推导） */
+    /** submit_result 校验通过的结构化结果；声明 schema 却未提交会以 result_missing 失败，未声明则为 undefined */
     typed: T | undefined;
     /**
      * HITL 挂起（stopReason === 'suspended'）时的完整消息历史
@@ -38,7 +38,7 @@ export interface AgentLoopResult<T = unknown> {
      */
     pendingApprovals: string[] | undefined;
     /**
-     * 挂起原因（`stopReason === 'suspended'` 时非空，2026-09-28 ①）：
+     * 挂起原因（`stopReason === 'suspended'` 时非空，2026-09-28 ref-suspend-state-reason）：
      * `approval` = 等人工决定、`timer` = 等一个时刻。**由出口的调用方给** ——
      * 出口自己不认识「为什么挂起」，它只保证这个位一定在场。
      */
@@ -53,7 +53,7 @@ export interface AgentLoopResult<T = unknown> {
      */
     wakeAt: number | undefined;
     /**
-     * 本段是否把传入的 `events`（run 事件投入口，2026-09-28 ⑥）**真注入了消息流**
+     * 本段是否把传入的 `events`（run 事件投入口，2026-09-28 ref-run-event-input）**真注入了消息流**
      * （字段在场）。宿主据此清 `TaskRecord.pendingEvents`：注入过 ⇒ 事件已在历史里，
      * 簿记清掉（否则下次续跑会**重复注入**）；没注入（续跑入口的再挂起出口在注入点
      * 之前返回）⇒ 簿记必须留住，等跑通的那次。