@migor/agentia 0.9.4 → 0.9.5

package/dist/transport/task-events.js

@@ -2,10 +2,21 @@ import { zeroClauseOf } from '../core/limits.js';
 /** 缺省上限 —— 与文档里写的数字必须一致（`usage-guide` §7） */
 export const TASK_STREAM_DEFAULT_MAX_EVENTS = 500;
 export const TASK_STREAM_DEFAULT_RETAIN_TERMINAL = 16;
+export const TASK_STREAM_DEFAULT_NON_TERMINAL_BUFFERS = 32;
 export class TaskEventStreams {
     streams = new Map();
     maxEvents;
     retainTerminal;
+    nonTerminalBuffers;
+    /**
+     * 「非终态**且**缓冲非空」的流数 —— 配额判据的**增量**计数。
+     *
+     * 为什么不每次现数：判定点在 `push` 上（每条事件都可能让一条流从空变非空），
+     * 每次全表扫一遍会把这道内存闸本身变成 O(流数 × 事件数) 的开销。
+     * 增量的代价是必须有**唯二**的增减点（`#recycleNonTerminal` 减、`push`/`open` 增），
+     * 所以三处各有一句注释钉着 —— 谁新开一条改缓冲的路径，得同时改这里。
+     */
+    buffered = 0;
     constructor(opts = {}) {
         // 坏值响亮失败（口径与 resolveTraceLimits / resolveMaxRetries 同款）：
         // 判定是 `length > maxEvents` ⇒ NaN 恒假（上限根本不生效）、Infinity 永不触发、
@@ -26,6 +37,17 @@ export class TaskEventStreams {
                 'NaN 会让「超出保留条数」的判定恒假（终态流被静默清空），负数 / 小数没有「留几条」的读法');
         }
         this.retainTerminal = retainTerminal;
+        // nonTerminalBuffers 同款校验：判定是 `buffered <= quota 提前返回` ⇒ NaN 恒假
+        // ⇒ **每条**非终态流的缓冲都被立刻回收（回放历史静默全没，与 retainTerminal 的
+        // 「保留机制失效」同族、方向相反）。0 有读法：非终态流不留回放缓冲（只做实时转发）。
+        const nonTerminalBuffers = opts.nonTerminalBuffers ?? TASK_STREAM_DEFAULT_NON_TERMINAL_BUFFERS;
+        if (typeof nonTerminalBuffers !== 'number' ||
+            !Number.isSafeInteger(nonTerminalBuffers) ||
+            nonTerminalBuffers < 0) {
+            throw new TypeError(`nonTerminalBuffers 必须是非负安全整数（${zeroClauseOf('TaskEventStreams.nonTerminalBuffers')}），收到 ${String(opts.nonTerminalBuffers)} —— ` +
+                'NaN 会让「超出配额」的判定恒假（没人读的非终态流的回放缓冲被静默回收），负数 / 小数没有「留几条」的读法');
+        }
+        this.nonTerminalBuffers = nonTerminalBuffers;
     }
     /** 这条流在场吗（在场 = 本进程见过它的记账） */
     has(taskId) {
@@ -45,8 +67,14 @@ export class TaskEventStreams {
             });
             return;
         }
-        // 复用：只把「已完成」摘掉 —— 恢复段是同一个任务的续篇，缓冲与序号都接着用
+        // 复用：只把「已完成」摘掉 —— 恢复段是同一个任务的续篇，缓冲与序号都接着用。
+        // 从终态回到非终态且缓冲非空 ⇒ 它重新计入配额（计数 +1，见 `buffered` 的注释）并当场对账。
+        const backInQuota = existing.done && existing.events.length > 0;
         existing.done = false;
+        if (backInQuota) {
+            this.buffered += 1;
+            this.#recycleNonTerminal();
+        }
     }
     /**
      * 记一条事件：入缓冲 + 广播给订阅者。
@@ -60,12 +88,20 @@ export class TaskEventStreams {
         const s = this.streams.get(taskId);
         if (!s || s.done)
             return;
+        // 从「空」变「非空」⇒ 这条流开始占配额（计数 +1，见 `buffered` 的注释）。
+        // 判据取在 push 之前：push 之后一定非空（`maxEvents ≥ 1` 由构造期保证）。
+        const wasEmpty = s.events.length === 0;
         const item = { index: s.nextIndex++, event };
         s.events.push(item);
         if (s.events.length > this.maxEvents) {
             const dropped = s.events.shift();
             s.firstAvailable = dropped.index + 1;
         }
+        if (wasEmpty) {
+            this.buffered += 1;
+            // 超配额就从最旧的别人开始回收 —— **不会**回收刚 push 的这条（它非空且是最后插入的）
+            this.#recycleNonTerminal();
+        }
         // 广播：先拷订阅者集合（回调里可能退订），单个抛错不影响其它订阅者
         for (const l of [...s.subscribers]) {
             try {
@@ -120,6 +156,11 @@ export class TaskEventStreams {
         const s = this.streams.get(taskId);
         if (!s)
             return;
+        // 终态不再计入「非终态缓冲」配额（计数 -1，见 `buffered` 的注释）。
+        // 幂等：重复 markDone 不重复减（计数少减一次会让配额**多**留几条，方向是漏不是错，
+        // 但那也是漂 —— 判据取在赋值之前）。
+        if (!s.done && s.events.length > 0)
+            this.buffered -= 1;
         s.done = true;
         // 先广播终态再考虑淘汰：订阅者要能收口（单个抛错不影响其它订阅者）
         for (const l of [...s.doneListeners]) {
@@ -132,11 +173,51 @@ export class TaskEventStreams {
         }
         this.#evictTerminal();
     }
-    /** 丢弃某条流（终态 LRU 用） */
-    forget(taskId) {
-        this.streams.delete(taskId);
+    /**
+     * **非终态**流的**缓冲**回收（配额 = `nonTerminalBuffers`）。2026-09-28 外部深评 T4 的收口。
+     *
+     * 回收的是**缓冲**，不是**表项**：`has()` 仍为真（任务确实在本进程），`nextIndex` 不动
+     * （序号接着走），只把回放历史丢掉并用 `firstAvailable = nextIndex` 明示缺口 ——
+     * 于是 `replay()` 回空 + `droppedBefore`，HTTP 层据此**先**发一帧 `stream.truncated`
+     * 再转实时。连表项一起删是**错的**，理由写在类注释约束 4（恢复段的序号会从 1 重来，
+     * 拿 `Last-Event-ID` 续订的读者从此静默收不到东西）。
+     *
+     * 三条纪律（每条都有代价，别按直觉改）：
+     *
+     * - **有订阅者的不回收**：那是一条正在被读的流，回收等于从读者手里抽走数据。
+     *   代价如实：**被实时读的流不受配额约束** ⇒ 同时被读的流很多时，缓冲总量仍会超配额 ——
+     *   这是「不抽走正在读的东西」的代价，不是漏洞（与 `#evictTerminal` 同款取舍）。
+     * - **终态的不归这里管**：它走 `#evictTerminal()` 的 LRU（那条丢的是**表项**）。
+     * - **只在缓冲增长时判**（`push` 让某条流从空变非空 / `open()` 把终态流拉回非终态）：
+     *   每次 push 都全表扫会把这道内存闸本身变成开销（见 `buffered` 的注释）。
+     *   代价如实：判定点之间会**短暂**多出几条 —— 但每条增长都会当场触发一次回收，所以超额是
+     *   「本轮一个事件」的量级，不是无界累积。
+     */
+    #recycleNonTerminal() {
+        if (this.buffered <= this.nonTerminalBuffers)
+            return;
+        // Map 的插入序即「最旧优先」：挂得最久的任务（等审批 / 等事件 / 等定时器）先被回收 ——
+        // 它们正是这条闸要治的那一类（永远不会走到终态，缓冲只增不减）。
+        for (const s of this.streams.values()) {
+            if (this.buffered <= this.nonTerminalBuffers)
+                return;
+            if (s.done || s.events.length === 0 || s.subscribers.size > 0)
+                continue;
+            s.events = [];
+            s.firstAvailable = s.nextIndex; // 缺口从「下一条」开始 ⇒ 已缓冲的全不在
+            this.buffered -= 1;
+        }
     }
-    /** 终态流超过保留条数 ⇒ 从最旧的开始丢（Map 的插入序即 LRU 序；恢复段 `open()` 会把它当新流） */
+    /**
+     * 终态流超过保留条数 ⇒ 从最旧的开始丢（Map 的插入序即 LRU 序；恢复段 `open()` 会把它当新流）。
+     *
+     * ⚠️ 这里**曾经**还有一个公开方法 `forget(taskId)`（「丢弃某条流」）。2026-09-28 外部深评
+     * 复核时确认它**全仓零调用点**（`grep` 命中的 `forget()` 全是 `scheduler.ts` 里那个操作
+     * `inFlight` 的同名**局部函数**，与此无关）—— 删掉，不留死承诺。
+     * 淘汰这件事**唯一的真实机制就是本方法**：终态流按 LRU 丢、有订阅者的不丢。
+     * 将来若真要「外部显式丢弃某条流」，请连同**谁在什么场景会调**一起设计再加回来
+     * （报告当初的建议「给 forget 写个测试」是反的：那等于给死代码上锁）。
+     */
     #evictTerminal() {
         const doneIds = [];
         for (const [taskId, s] of this.streams) {

package/dist/transport/task-events.js.map

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

package/dist/transport/wake-policy.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 到期唤醒的**纯判定** + 挂起读数 —— durable timer（2026-09-28 ① 的 timer 侧）。
+ *
+ * 从 AsyncRunner 里抽出来的第五个协作件（slot-pool → approval-policy → drain-gate →
+ * resume-policy → 这里），与 `approval-policy.ts` 是**明确的一对**：挂起的两个原因各有一套闸，
+ * 各自一个纯文件。为什么非要分开写：C 之前「挂起」是一个状态兼职两件事
+ * （`awaiting_approval` 既等人也等时刻），于是 `approvalTimeoutMs` 会去叫醒一条在等时刻的 run
+ * （而且 `#expireAndResume` 紧接着就重派 —— 补不出任何决定也照样开跑）。
+ * 两个原因的判据分开成两个具名函数之后，「谁管谁」在调用点一眼可见，也各有单测。
+ *
+ * 纯的边界：入参不变则结果不变；不碰 store、不改 rec、不派发、不起定时器。
+ */
+import type { SuspendedReason } from '../core/run.js';
+import type { TaskRecord } from '../store/store.js';
+/**
+ * 到点了吗（时间挂起）。
+ *
+ * - 两条判据缺一不可：状态是 `suspended` **且**原因是 `timer`（原因那一半是 C 定的口径 ——
+ *   没有它，等审批的挂起会被到期扫描按「`wakeAt` 缺失」判成不到点，看着像对，其实是
+ *   **恰好**躲过；等时刻的挂起则会被审批那条闸叫醒）；
+ * - `wakeAt` 缺失 ⇒ 永远不到点：**不**拿 `createdAt` / `startedAt` 之类退化（与
+ *   `approvalExpired` 的取舍相反）—— 「不知道它什么时候醒」和「现在就该醒」是两件事，
+ *   猜错的方向是**提前开跑**，代价是真实副作用；
+ * - 边界是**不晚于现在**（`wakeAt <= now`）：到点即可唤醒。与 `approvalExpired` 的严格大于
+ *   相反，两个闸的语义本来就不同 —— 超时是「等够了没」（恰好等于还没够），
+ *   到期是「到点了没」（恰好等于就到了）。
+ */
+export declare function timerDue(rec: TaskRecord, now: number): boolean;
+/** 一条挂起记录的读数 —— AsyncRunner 只留「原因 + 目标时刻」，不持有整条记录 */
+export interface SuspendedEntry {
+    reason: SuspendedReason;
+    wakeAt: number | undefined;
+}
+/** `/healthz` 的 `suspended` 段 */
+export interface SuspendedSummary {
+    /** 等人工决定的条数 */
+    approval: number;
+    /** 等一个时刻的条数 */
+    timer: number;
+    /** 最早的目标时刻（epoch ms）；一条时间挂起都没有 ⇒ **`null`**（不是 `0`） */
+    nextWakeAt: number | null;
+}
+/**
+ * 把挂起的条目收成读数。口径写在调用方（`AsyncRunner.suspendedSummary`）：只数**本进程**
+ * 看得见的记录 —— 与 `inFlight` 同一张表，不假装是全局面（跨进程合并看板是聚合方的事）。
+ *
+ * `nextWakeAt` 给 `null` 而不是 `0`：`0` 在 JSON 里是一个**合法时刻**（1970 年），
+ * 监控端拿它算 `nextWakeAt - now` 会得到一个巨大的负数，看着像「早就该醒却没人醒」。
+ */
+export declare function summarizeSuspended(entries: Iterable<SuspendedEntry>): SuspendedSummary;

package/dist/transport/wake-policy.js

@@ -0,0 +1,43 @@
+/**
+ * 到点了吗（时间挂起）。
+ *
+ * - 两条判据缺一不可：状态是 `suspended` **且**原因是 `timer`（原因那一半是 C 定的口径 ——
+ *   没有它，等审批的挂起会被到期扫描按「`wakeAt` 缺失」判成不到点，看着像对，其实是
+ *   **恰好**躲过；等时刻的挂起则会被审批那条闸叫醒）；
+ * - `wakeAt` 缺失 ⇒ 永远不到点：**不**拿 `createdAt` / `startedAt` 之类退化（与
+ *   `approvalExpired` 的取舍相反）—— 「不知道它什么时候醒」和「现在就该醒」是两件事，
+ *   猜错的方向是**提前开跑**，代价是真实副作用；
+ * - 边界是**不晚于现在**（`wakeAt <= now`）：到点即可唤醒。与 `approvalExpired` 的严格大于
+ *   相反，两个闸的语义本来就不同 —— 超时是「等够了没」（恰好等于还没够），
+ *   到期是「到点了没」（恰好等于就到了）。
+ */
+export function timerDue(rec, now) {
+    return (rec.status === 'suspended' &&
+        rec.suspendedReason === 'timer' &&
+        rec.wakeAt !== undefined &&
+        rec.wakeAt <= now);
+}
+/**
+ * 把挂起的条目收成读数。口径写在调用方（`AsyncRunner.suspendedSummary`）：只数**本进程**
+ * 看得见的记录 —— 与 `inFlight` 同一张表，不假装是全局面（跨进程合并看板是聚合方的事）。
+ *
+ * `nextWakeAt` 给 `null` 而不是 `0`：`0` 在 JSON 里是一个**合法时刻**（1970 年），
+ * 监控端拿它算 `nextWakeAt - now` 会得到一个巨大的负数，看着像「早就该醒却没人醒」。
+ */
+export function summarizeSuspended(entries) {
+    let approval = 0;
+    let timer = 0;
+    let nextWakeAt = null;
+    for (const e of entries) {
+        if (e.reason === 'approval') {
+            approval++;
+            continue;
+        }
+        timer++;
+        if (e.wakeAt !== undefined && (nextWakeAt === null || e.wakeAt < nextWakeAt)) {
+            nextWakeAt = e.wakeAt;
+        }
+    }
+    return { approval, timer, nextWakeAt };
+}
+//# sourceMappingURL=wake-policy.js.map

package/dist/transport/wake-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake-policy.js","sourceRoot":"","sources":["../../src/transport/wake-policy.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAe,EAAE,GAAW;IACnD,OAAO,CACL,GAAG,CAAC,MAAM,KAAK,WAAW;QAC1B,GAAG,CAAC,eAAe,KAAK,OAAO;QAC/B,GAAG,CAAC,MAAM,KAAK,SAAS;QACxB,GAAG,CAAC,MAAM,IAAI,GAAG,CAClB,CAAC;AACJ,CAAC;AAkBD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAiC;IAClE,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,UAAU,GAAkB,IAAI,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC5B,QAAQ,EAAE,CAAC;YACX,SAAS;QACX,CAAC;QACD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,UAAU,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC;YAC7E,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACzC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/agentia",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。",
   "type": "module",
   "main": "dist/index.js",
@@ -53,17 +53,19 @@
     "e2e:grpc": "npm run build && tsx scripts/e2e-grpc.ts",
     "e2e:live": "tsx scripts/e2e-live.ts",
     "e2e:mcp": "npm run build:cli && tsx scripts/e2e-mcp.ts",
+    "e2e:mcp:server": "tsx scripts/e2e-mcp-server.ts",
     "e2e:soak": "tsx scripts/e2e-soak.ts",
     "bench:trace": "tsx scripts/bench-trace-cost.ts",
-    "bench:assembly": "tsx scripts/bench-app-assembly.ts"
+    "bench:assembly": "tsx scripts/bench-app-assembly.ts",
+    "bench:otlp": "tsx scripts/bench-otlp-snapshot.ts"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.126.0",
+    "@anthropic-ai/sdk": "^0.128.0",
     "@biomejs/biome": "^2.5.14",
     "@grpc/grpc-js": "^1.14.5",
     "@grpc/proto-loader": "^0.8.1",
     "@types/node": "^26.5.1",
-    "c8": "^10.1.3",
+    "c8": "^12.0.0",
     "tsx": "^4.19.0",
     "typescript": "^7.0.2",
     "zod": "^4.6.1"