@migor/agentia 0.2.1 → 0.2.2

package/dist/engine/policy.js

@@ -1,24 +1,27 @@
-import { compactMessages, defaultEstimateTokens, estimateMessages, trimToolPairs, } from './context.js';
+import { compactMessages, createTokenCounter, defaultEstimateTokens, trimToolPairs, } from './trimming.js';
 export function createBudgetPolicy(opts = {}) {
     const budgetTokens = opts.budgetTokens ?? 60_000;
     const keepRecent = Math.max(1, opts.keepRecent ?? 20);
+    const keepToolPairs = Math.max(0, opts.keepToolPairs ?? 1);
     const estimate = opts.estimateTokens ?? defaultEstimateTokens;
     const editBeforeCompact = opts.editBeforeCompact ?? true;
     const summarize = opts.summarize;
     const compactEvery = Math.max(1, opts.compactEvery ?? 1);
     let lastCompactAt = Number.NEGATIVE_INFINITY;
+    // 增量计数：历史只追加时只估新增部分，把 O(回合 × 上下文) 压成 O(上下文)
+    const countTokens = createTokenCounter(estimate);
     return {
         budgetTokens,
         async beforeTurn(messages, info) {
-            if (estimateMessages(messages, estimate) <= budgetTokens)
+            if (countTokens(messages) <= budgetTokens)
                 return messages;
-            // 1) context editing：先丢旧工具对
+            // 1) context editing：先丢旧工具对（按「对数」计，见 keepToolPairs）
             let current = messages;
             if (editBeforeCompact) {
-                const trimmed = trimToolPairs(current, { keepRecent });
+                const trimmed = trimToolPairs(current, { keepToolPairs });
                 if (trimmed.length < current.length) {
                     current = trimmed;
-                    if (estimateMessages(current, estimate) <= budgetTokens)
+                    if (countTokens(current) <= budgetTokens)
                         return current;
                 }
             }

package/dist/engine/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/engine/policy.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,GACd,MAAM,cAAc,CAAC;AA+BtB,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,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;IAE7C,OAAO;QACL,YAAY;QACZ,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI;YAC7B,IAAI,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,YAAY;gBAAE,OAAO,QAAQ,CAAC;YAE1E,4BAA4B;YAC5B,IAAI,OAAO,GAAG,QAAQ,CAAC;YACvB,IAAI,iBAAiB,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;gBACvD,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;oBACpC,OAAO,GAAG,OAAO,CAAC;oBAClB,IAAI,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,YAAY;wBAAE,OAAO,OAAO,CAAC;gBAC1E,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":"AAEA,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,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"}

package/dist/engine/replay.d.ts

@@ -10,17 +10,20 @@ import type { Trace } from '../core/trace.js';
  * 还原规则：
  * - 全部 llm.turn 按 startedAt 时序线性展开（稳定排序，同刻保插入序）——
  *   子 agent 的嵌套回合与主 agent 回合交错进同一序列，每回合以 text 块标注
- *   来源（model / 所属 unit span 名 / spanId）；
+ *   来源（model / 所属 capability span 名 / spanId）；
  * - 每回合 → 一条 assistant 消息：标注文本 + 各 tool.input 事件还原的 tool_use 块
  *   （id 由重放合成 `replay_tu_<n>`，trace 不记原始 id）；
  * - tool.output 事件 → 紧随其后一条 user 消息里的 tool_result 块，与 tool_use
- *   按「同名优先、兜底取最早未配对」配对（并行工具完成序 ≠ 发起序）；
- *   缺失输出的 tool_use 补一条 is_error 占位 —— 保证 role 交替与配对合法；
+ *   配对：优先按 tool_use_id 精确匹配（同名工具并行是本框架的常态 —— 完成序 ≠
+ *   发起序，只有 id 能把入参出参对上），老 trace 无 id 时回落到「同名最早未配对」，
+ *   再兜底「最早未配对」；缺失输出的 tool_use 补一条 is_error 占位 ——
+ *   保证 role 交替与配对合法；
  * - 事件负载（工具入参/出参）已是 engine 截断后的字符串；入参尝试 JSON.parse
  *   还原为对象，失败（或非 object）包 `{ _raw }` —— tool_use.input 必须是 object；
  *   所有串按 maxEventChars 再截断（缺省 2000）；
- * - 产出经 normalizeForApi 规整：连续同 role 合并、首条确保为 user ——
- *   可直接作为 Messages API 的 messages 喂回模型。
+ * - 产出经 normalizeForApi 规整：连续同 role 合并、首尾都确保为 user ——
+ *   可直接作为 Messages API 的 messages 喂回模型（末条为 user 是硬要求：
+ *   以 assistant 收尾即 prefill，缺省模型上 400）。
  *
  * 注意：trace 不记录 assistant 文本（llm.turn 只记 usage/事件），还原的
  * assistant 消息以标注文本占位，非逐字原文。

package/dist/engine/replay.js

@@ -1,3 +1,4 @@
+import { stringifySafe, truncateWithMark } from '../core/json.js';
 const DEFAULT_MAX_EVENT_CHARS = 2000;
 export function traceToMessages(trace, opts = {}) {
     const includeToolIO = opts.includeToolIO ?? true;
@@ -9,9 +10,9 @@ export function traceToMessages(trace, opts = {}) {
     const messages = [];
     let seq = 0;
     turns.forEach((turn, i) => {
-        const unit = nearestUnitName(turn, byId);
+        const capability = nearestCapabilityName(turn, byId);
         const note = `[replay turn ${i + 1}/${turns.length}] model=${turn.name} ` +
-            `unit=${unit ?? '(主 agent run)'} span=${turn.spanId}`;
+            `capability=${capability ?? '(主 agent run)'} span=${turn.spanId}`;
         const content = [{ type: 'text', text: note }];
         const pairs = [];
         if (includeToolIO) {
@@ -19,8 +20,13 @@ export function traceToMessages(trace, opts = {}) {
             const outputs = eventsOf(turn, 'tool.output');
             const used = new Set();
             for (const input of inputs) {
-                // 同名优先（并行工具完成序 ≠ 发起序），兜底取最早未配对的输出
-                let idx = outputs.findIndex((o, j) => !used.has(j) && o.tool === input.tool);
+                // 配对优先级：同 id 精确匹配 > 同名最早未配对 > 最早未配对。
+                // 同名工具并行时同名的那个回落会把入参出参张冠李戴，id 才是唯一可靠的锚。
+                let idx = input.toolUseId === undefined
+                    ? -1
+                    : outputs.findIndex((o, j) => !used.has(j) && o.toolUseId === input.toolUseId);
+                if (idx < 0)
+                    idx = outputs.findIndex((o, j) => !used.has(j) && o.tool === input.tool);
                 if (idx < 0)
                     idx = outputs.findIndex((_, j) => !used.has(j));
                 const output = idx >= 0 ? outputs[idx] : undefined;
@@ -45,7 +51,7 @@ export function traceToMessages(trace, opts = {}) {
                     type: 'tool_result',
                     tool_use_id: id,
                     content: output
-                        ? truncate(output.content ?? '', maxChars)
+                        ? truncateWithMark(output.content ?? '', maxChars)
                         : '[replay] trace 中缺失对应 tool.output 事件',
                     is_error: output ? output.ok === false : true,
                 })),
@@ -54,11 +60,18 @@ export function traceToMessages(trace, opts = {}) {
     });
     return normalizeForApi(messages);
 }
+/** 前置 user 说明（API 要求首条为 user；trace 不含 run 的原始输入） */
+const REPLAY_HEAD = '[replay] 以下是一次已完成 run 的 trace 重放（assistant 文本为标注占位，非逐字原文）。';
+/** 收尾 user 请求：末条为 assistant 会被 API 当作 prefill */
+const REPLAY_TAIL = '[replay] 以上是全部回合，请分析这次 run 的过程与结果。';
 /**
  * 规整为可直接喂回 Messages API 的形态：
  * - 连续同 role 消息合并（无 tool 对的连续 assistant 会合流，交替保持合法；
  *   带 tool_use 的 assistant 之后必有其 tool_result user，配对不受影响）；
- * - 首条确保为 user（API 硬要求）——trace 不含 run 的原始输入，前置一条说明性 user。
+ * - 首条确保为 user（API 硬要求）——trace 不含 run 的原始输入，前置一条说明性 user；
+ * - **末条也确保为 user**：多数 run 以 `end_turn` 的 assistant 回合收尾，直接喂回就是
+ *   assistant prefill —— 缺省模型（claude-opus-5 / claude-sonnet-5）上会 400。
+ *   空 trace（无 llm.turn）返回的也是这条前置 user，而非 `[]`（空 messages 同样非法）。
  */
 function normalizeForApi(messages) {
     const merged = [];
@@ -71,22 +84,21 @@ function normalizeForApi(messages) {
             merged.push({ role: m.role, content: toBlocks(m.content) });
         }
     }
-    if (merged.length > 0 && merged[0].role !== 'user') {
-        merged.unshift({
-            role: 'user',
-            content: '[replay] 以下是一次已完成 run 的 trace 重放，请分析这次 run 的过程与结果。',
-        });
+    if (merged[0]?.role !== 'user')
+        merged.unshift({ role: 'user', content: REPLAY_HEAD });
+    if (merged[merged.length - 1].role !== 'user') {
+        merged.push({ role: 'user', content: REPLAY_TAIL });
     }
     return merged;
 }
 function toBlocks(content) {
     return typeof content === 'string' ? [{ type: 'text', text: content }] : [...content];
 }
-/** 向上找最近的 unit span 名（子 agent 嵌套回合的来源标注）；直属 run 根则 null */
-function nearestUnitName(span, byId) {
+/** 向上找最近的 capability span 名（子 agent 嵌套回合的来源标注）；直属 run 根则 null */
+function nearestCapabilityName(span, byId) {
     let cur = span.parentSpanId ? byId.get(span.parentSpanId) : undefined;
     while (cur) {
-        if (cur.kind === 'unit')
+        if (cur.kind === 'capability')
             return cur.name;
         cur = cur.parentSpanId ? byId.get(cur.parentSpanId) : undefined;
     }
@@ -100,6 +112,7 @@ function eventsOf(turn, name) {
         const b = (e.body ?? {});
         return {
             tool: typeof b.tool === 'string' ? b.tool : 'unknown',
+            toolUseId: typeof b.tool_use_id === 'string' ? b.tool_use_id : undefined,
             input: asString(b.input),
             ok: typeof b.ok === 'boolean' ? b.ok : undefined,
             content: asString(b.content),
@@ -107,20 +120,12 @@ function eventsOf(turn, name) {
     });
 }
 function asString(x) {
-    if (x === undefined)
-        return undefined;
-    if (typeof x === 'string')
-        return x;
-    try {
-        return JSON.stringify(x) ?? String(x);
-    }
-    catch {
-        return String(x);
-    }
+    // 与 core/json.ts 的 stringifySafe 同源；仅额外把 undefined 视作「无值」
+    return x === undefined ? undefined : stringifySafe(x);
 }
 /** 入参还原：截断后尝试 JSON.parse 回对象，失败包 {_raw}（tool_use.input 必须是 object，否则 API 400） */
 function parseInput(raw, maxChars) {
-    const s = truncate(raw ?? '', maxChars);
+    const s = truncateWithMark(raw ?? '', maxChars);
     try {
         const parsed = JSON.parse(s);
         return typeof parsed === 'object' && parsed !== null ? parsed : { _raw: s };
@@ -129,8 +134,4 @@ function parseInput(raw, maxChars) {
         return { _raw: s };
     }
 }
-/** 截断到上限字符，超长加省略标记（与 engine/loop.ts 的 limit 同款格式） */
-function truncate(s, n) {
-    return s.length > n ? `${s.slice(0, n)}…(+${s.length - n})` : s;
-}
 //# sourceMappingURL=replay.js.map

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/retry.d.ts

@@ -0,0 +1,47 @@
+import type { SpanError } from '../core/trace.js';
+/**
+ * Agentia —— 模型请求的重试与退避（spec §6.5 确定性工程）。
+ *
+ * 消费 `classifyError().retryable`（此前该标记只产出、无人消费）：429 / 5xx /
+ * 连接失败自动重试，400 一类的确定性错误立即失败。
+ *
+ * **只重试尚未产出任何文本的尝试** —— 已流出一半的文本无法撤回，重试会造成
+ * 重复输出。这条约束由 engine/loop.ts 保证（它才知道有没有吐过文本）。
+ *
+ * ⚠️ 与 SDK 内置重试叠加：Anthropic SDK 自己会对 429/5xx 重试（默认 2 次）。
+ * 框架层是更外层的兜底（覆盖 SDK 放弃后、以及 OpenAI 兼容客户端）。两层同时开
+ * 最多会打 `(1+sdkAttempts) × maxAttempts` 次请求 —— 建议二选一调（把这里设
+ * `maxAttempts: 1`，或把 SDK 的 `maxRetries` 设小）。
+ */
+export interface RetryOptions {
+    /** 最大尝试次数（含首次）；1 = 关闭。缺省 3 */
+    maxAttempts?: number;
+    /** 首次退避毫秒，指数增长；缺省 500 */
+    baseDelayMs?: number;
+    /** 退避上限毫秒；缺省 8000 */
+    maxDelayMs?: number;
+    /** 抖动比例 0~1（避免并发 run 同时重试打爆上游）；缺省 0.2 */
+    jitter?: number;
+    /** 判定是否可重试；缺省 `(e) => classifyError(e).retryable` */
+    isRetryable?: (err: unknown) => boolean;
+    /** 重试前回调（观测用；trace 里另有 `llm.retry` 事件） */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: SpanError;
+    }) => void;
+}
+/** 缺省重试参数（不含两个函数字段 —— 它们在 resolveRetry 里注入） */
+export declare const DEFAULT_RETRY: {
+    readonly maxAttempts: 3;
+    readonly baseDelayMs: 500;
+    readonly maxDelayMs: 8000;
+    readonly jitter: 0.2;
+};
+export type ResolvedRetry = Required<RetryOptions>;
+/** 归一重试配置：`undefined` → 缺省策略（**缺省开启**）；`false` → null（关闭）。 */
+export declare function resolveRetry(o: RetryOptions | false | undefined): ResolvedRetry | null;
+/** 指数退避 + 上限 + 抖动：attempt 从 1 起，`base * 2^(attempt-1)` 封顶 maxDelayMs。 */
+export declare function backoffDelay(attempt: number, r: ResolvedRetry): number;
+/** 可被 signal 中断的 sleep（退避期间收到取消就不必再等） */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/engine/retry.js

@@ -0,0 +1,51 @@
+import { classifyError } from './errors.js';
+/** 缺省重试参数（不含两个函数字段 —— 它们在 resolveRetry 里注入） */
+export const DEFAULT_RETRY = {
+    maxAttempts: 3,
+    baseDelayMs: 500,
+    maxDelayMs: 8000,
+    jitter: 0.2,
+};
+/** 归一重试配置：`undefined` → 缺省策略（**缺省开启**）；`false` → null（关闭）。 */
+export function resolveRetry(o) {
+    if (o === false)
+        return null;
+    const merged = { ...DEFAULT_RETRY, ...(o ?? {}) };
+    if (!(merged.maxAttempts >= 1))
+        return null; // maxAttempts < 1 等同关闭
+    return {
+        ...merged,
+        isRetryable: o?.isRetryable ?? ((e) => classifyError(e).retryable),
+        onRetry: o?.onRetry ?? (() => { }),
+    };
+}
+/** 指数退避 + 上限 + 抖动：attempt 从 1 起，`base * 2^(attempt-1)` 封顶 maxDelayMs。 */
+export function backoffDelay(attempt, r) {
+    const exp = r.baseDelayMs * 2 ** Math.max(0, attempt - 1);
+    const capped = Math.min(exp, r.maxDelayMs);
+    const jitter = r.jitter > 0 ? capped * r.jitter * (Math.random() * 2 - 1) : 0;
+    return Math.max(0, Math.round(capped + jitter));
+}
+/** 可被 signal 中断的 sleep（退避期间收到取消就不必再等） */
+export function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const abortError = () => Object.assign(new Error('run 已被取消'), { name: 'AbortError' });
+        // 已中止：立即 reject（此处 timer 尚未创建，绝不能去 clear）
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        function onAbort() {
+            clearTimeout(timer);
+            reject(abortError());
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/engine/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/engine/retry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA+B5C,+CAA+C;AAC/C,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,IAAI;IAChB,MAAM,EAAE,GAAG;CACH,CAAC;AAIX,8DAA8D;AAC9D,MAAM,UAAU,YAAY,CAAC,CAAmC;IAC9D,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,MAAM,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;IAClD,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,uBAAuB;IACpE,OAAO;QACL,GAAG,MAAM;QACT,WAAW,EAAE,CAAC,EAAE,WAAW,IAAI,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3E,OAAO,EAAE,CAAC,EAAE,OAAO,IAAI,CAAC,GAAS,EAAE,GAAE,CAAC,CAAC;KACxC,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,CAAgB;IAC5D,MAAM,GAAG,GAAG,CAAC,CAAC,WAAW,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IACtC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,UAAU,GAAG,GAAU,EAAE,CAC7B,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAC/D,0CAA0C;QAC1C,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,SAAS,OAAO;YACd,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QACvB,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/engine/spec.d.ts

@@ -0,0 +1,61 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { ModelClient, ModelPricing } from '../core/tool.js';
+import type { AgentTool } from '../core/tool.js';
+import type { BlackboardSeed } from '../core/blackboard.js';
+import type { ContextPolicy } from './types.js';
+import type { RetryOptions } from './retry.js';
+/**
+ * Agentia —— run 调用契约（spec §6.3 三类触发共用同一份入参形态）。
+ * transport 层（同步 RPC / 异步任务 / 定时）只谈 RunInput / RunSpec，
+ * 与具体 agent 装配解耦 —— 换宿主（HTTP/队列/DB）不换语义（spec §6.6）。
+ *
+ * 放在 engine 的理由：这是 transport 与 runtime **共用**的入参契约，而 engine
+ * 在两者之下。此前它在 runtime，导致 store 为了 `TaskRecord.spec` 反向依赖
+ * runtime（兄弟层）—— 移到 engine 后 store/toolkit/transport 都能合法引用。
+ */
+/** 单次 run 透传给引擎/应用的可选调用参数（与 toolkit/module 的 RunAppOptions 子集对齐） */
+export interface RunInvocationOptions {
+    model?: string;
+    maxTokens?: number;
+    maxIterations?: number;
+    client?: ModelClient;
+    onText?: (delta: string) => void;
+    /** 中断信号：中止则在飞请求被取消，run 以 stopReason='aborted' 收尾 */
+    signal?: AbortSignal;
+    /** 预置进本次 RunContext.blackboard（扩展过 Blackboard 时键有补全） */
+    blackboard?: BlackboardSeed;
+    /** 上下文预算策略（compaction / context editing） */
+    contextPolicy?: ContextPolicy;
+    /** 模型请求重试策略（覆盖应用级缺省）；见 RunAgentOptions.retry */
+    retry?: RetryOptions | false;
+    /** 幂等键：异步宿主的 at-least-once 去重依据 */
+    idempotencyKey?: string;
+    /** 硬失败是否抛出；缺省 true（异步宿主置 false 落 failed 记录） */
+    rethrow?: boolean;
+    tools?: AgentTool[];
+    /** 成本硬管控：整条 run 累计 token 上限；超限以 stopReason='budget_exceeded' 收尾（算失败） */
+    maxTotalTokens?: number;
+    /** 成本硬管控：累计成本（美元）上限；依赖模型在价格表内，见 createBudgetGuard */
+    maxCostUsd?: number;
+    /** 价格表覆盖/追加（$/1M tokens）；见 RunAgentOptions.priceOverrides */
+    priceOverrides?: Record<string, ModelPricing>;
+    /** 单个工具执行超时（毫秒）；超时该条 tool_result 记 is_error，不杀 run */
+    toolTimeoutMs?: number;
+    /** 同回合并行工具上限；缺省不限 */
+    maxToolConcurrency?: number;
+}
+/** 一次任务的规范化入参：messages（已由 normalizeMessages 规整） */
+export interface RunSpec {
+    messages: Anthropic.MessageParam[];
+    options?: RunInvocationOptions;
+    /** 触发来源标记（sync / async / schedule:<id>），供 run 记录审计 */
+    source?: string;
+}
+/** transport 层接受的原始入参形态 */
+export type RunInput = string | Anthropic.MessageParam[] | {
+    prompt?: string;
+    text?: string;
+    messages?: Anthropic.MessageParam[];
+};
+/** 把任意任务入参规范成 messages（首条缺省包成 user）。 */
+export declare function normalizeMessages(input: RunInput | unknown): Anthropic.MessageParam[];

package/dist/{run → engine}/spec.js

@@ -1,7 +1,10 @@
 /** 把任意任务入参规范成 messages（首条缺省包成 user）。 */
 export function normalizeMessages(input) {
     if (typeof input === 'string') {
-        return input ? [{ role: 'user', content: input }] : [];
+        // 空串与 []、{prompt:''} 一致报错：返回 [] 会带着空 messages 去调模型
+        if (!input)
+            throw new Error('任务 messages 不能为空');
+        return [{ role: 'user', content: input }];
     }
     if (Array.isArray(input)) {
         if (input.length === 0)

package/dist/engine/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/engine/spec.ts"],"names":[],"mappings":"AA+DA,wCAAwC;AACxC,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,mDAAmD;QACnD,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAChD,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,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAC5D,OAAO,KAAiC,CAAC;IAC3C,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,KAAK,CAAC,kBAAkB,CAAC,CAAC;YACjE,OAAO,CAAC,CAAC,QAAoC,CAAC;QAChD,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,KAAK,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/dist/engine/tracer.d.ts

@@ -8,6 +8,8 @@ export declare class TraceRecorder {
     readonly traceId: TraceId;
     private readonly spans;
     private readonly index;
+    /** parentSpanId → 直接子 span（增量维护，供 capability 结束时就地聚合子孙 usage，O(子孙) 而非每次重建） */
+    private readonly children;
     private rootSpanId;
     begin(kind: SpanKind, name: string, parentSpanId: SpanId | null): SpanId;
     get rootStarted(): boolean;
@@ -15,12 +17,19 @@ export declare class TraceRecorder {
      * 结束 span。容错策略：未知 span id 抛错（程序员错误要响亮）；
      * 对已结束的 span 幂等忽略（重复 end 视为无害）。event/setAttribute 对未知
      * span 静默忽略 —— 观测不应中断业务，与 end 的严格性刻意区分。
+     *
+     * `capability` span 收尾时若调用方**未**显式给 usage，就地聚合其**子孙 llm.turn** 的
+     * usage 写回该 span —— 兑现 `core/trace.ts` 里「capability.usage = 其子孙聚合，仅供展示」
+     * 的已声明语义（此前该字段从不写入，指标/报告拿不到「某个子 agent 花了多少」）。
+     * 只累加 llm.turn，故层层嵌套也不会重复计数。
      */
     end(id: SpanId, patch?: {
         status?: SpanStatus;
         error?: SpanError;
         usage?: Usage;
     }): void;
+    /** 子孙里所有 `llm.turn` 的 usage 之和（不含自身）；无任何计量时返回 undefined */
+    private aggregateDescendantUsage;
     event(id: SpanId, name: string, body: unknown): void;
     setAttribute(id: SpanId, key: string, value: string | number | boolean): void;
     snapshot(status: SpanStatus): Trace;

package/dist/engine/tracer.js

@@ -8,6 +8,8 @@ export class TraceRecorder {
     traceId = randomUUID();
     spans = [];
     index = new Map();
+    /** parentSpanId → 直接子 span（增量维护，供 capability 结束时就地聚合子孙 usage，O(子孙) 而非每次重建） */
+    children = new Map();
     rootSpanId = null;
     begin(kind, name, parentSpanId) {
         if (kind === 'run') {
@@ -29,6 +31,11 @@ export class TraceRecorder {
         };
         this.spans.push(span);
         this.index.set(id, span);
+        const siblings = this.children.get(parentSpanId);
+        if (siblings)
+            siblings.push(span);
+        else
+            this.children.set(parentSpanId, [span]);
         return id;
     }
     get rootStarted() {
@@ -38,6 +45,11 @@ export class TraceRecorder {
      * 结束 span。容错策略：未知 span id 抛错（程序员错误要响亮）；
      * 对已结束的 span 幂等忽略（重复 end 视为无害）。event/setAttribute 对未知
      * span 静默忽略 —— 观测不应中断业务，与 end 的严格性刻意区分。
+     *
+     * `capability` span 收尾时若调用方**未**显式给 usage，就地聚合其**子孙 llm.turn** 的
+     * usage 写回该 span —— 兑现 `core/trace.ts` 里「capability.usage = 其子孙聚合，仅供展示」
+     * 的已声明语义（此前该字段从不写入，指标/报告拿不到「某个子 agent 花了多少」）。
+     * 只累加 llm.turn，故层层嵌套也不会重复计数。
      */
     end(id, patch = {}) {
         const span = this.index.get(id);
@@ -52,6 +64,47 @@ export class TraceRecorder {
             span.error = patch.error;
         if (patch.usage)
             span.usage = patch.usage;
+        else if (span.kind === 'capability') {
+            const aggregated = this.aggregateDescendantUsage(id);
+            if (aggregated)
+                span.usage = aggregated;
+        }
+    }
+    /** 子孙里所有 `llm.turn` 的 usage 之和（不含自身）；无任何计量时返回 undefined */
+    aggregateDescendantUsage(id) {
+        const total = {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+        };
+        let cost = 0;
+        let priced = false;
+        let any = false;
+        const stack = [...(this.children.get(id) ?? [])];
+        while (stack.length > 0) {
+            const s = stack.pop();
+            if (s.kind === 'llm.turn' && s.usage) {
+                any = true;
+                total.inputTokens += s.usage.inputTokens;
+                total.outputTokens += s.usage.outputTokens;
+                total.cacheReadTokens += s.usage.cacheReadTokens;
+                total.cacheCreationTokens += s.usage.cacheCreationTokens;
+                if (s.usage.costEstimate != null) {
+                    priced = true;
+                    cost += s.usage.costEstimate;
+                }
+            }
+            const kids = this.children.get(s.spanId);
+            if (kids)
+                stack.push(...kids);
+        }
+        if (!any)
+            return undefined;
+        // 与 usage.ts 的取整口径一致（1e-6 美元），避免浮点尾差进 trace/OTLP
+        if (priced)
+            total.costEstimate = Math.round(cost * 1e6) / 1e6;
+        return total;
     }
     event(id, name, body) {
         this.index.get(id)?.events.push({ time: Date.now(), name, body });
@@ -70,8 +123,11 @@ export class TraceRecorder {
             cacheReadTokens: 0,
             cacheCreationTokens: 0,
         };
+        // 只累加「自身计量」的 span（llm.turn 是唯一 token 来源）。
+        // capability span 的 usage 语义是**其子孙的聚合**（见 core/trace.ts Span.usage），
+        // 若一并求和，skill/subagent 一旦写入聚合值就会把同一批 token 计两遍。
         for (const s of this.spans) {
-            if (!s.usage)
+            if (!s.usage || s.kind !== 'llm.turn')
                 continue;
             totalUsage.inputTokens += s.usage.inputTokens;
             totalUsage.outputTokens += s.usage.outputTokens;

package/dist/engine/tracer.js.map

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

package/dist/engine/{context.d.ts → trimming.d.ts}

@@ -1,35 +1,34 @@
 import type Anthropic from '@anthropic-ai/sdk';
-/**
- * Agentia —— 长上下文策略的纯函数层（spec §5/§6：compaction / context editing 分清）。
- *
- * 三策略不混：
- * - **context editing**（`trimToolPairs`）：清旧 tool_use→tool_result 对，不掉内容、不额外调模型；
- * - **compaction**（`compactMessages`）：把旧消息前缀做**服务端摘要**（摘要器由上层注入，可走模型），
- *   只保留最近 N 条 + 一段摘要 —— 新的消息数组仍保证角色交替合法；
- * - **客户端剪裁** = 子 agent 的独立上下文（见 toolkit/subagent.ts）。
- *
- * 不在此自研 token 计数黑名单：`estimateMessages` 只是预算策略的默认启发式
- * （CJK 感知估算，明确标注为估算），上层可注入真实 count_tokens 结果。
- */
-/**
- * 默认估算（仅预算决策用，非精确记账）：CJK 字符按 ~1.5 字/token，
- * 其余（ASCII/拉丁）按 ~4 字符/token。纯字符/4 对中文系统性高估，
- * 会让预算护栏过早触发压缩。
- */
 export declare function defaultEstimateTokens(text: string): number;
 export declare function isToolResultMessage(msg: Anthropic.MessageParam): boolean;
 /** 整组消息的估算 token（含每条 role 开销）。 */
 export declare function estimateMessages(messages: Anthropic.MessageParam[], estimate?: (text: string) => number): number;
+/**
+ * 增量 token 计数器（预算策略专用；**不属公共导出面**，故不进 index.ts）。
+ *
+ * 为什么需要：`estimateMessages` 是 O(消息数 × 块大小)（每个块还要 stringify），
+ * 而预算策略的 `beforeTurn` **每回合都要估一次**。历史只追加，若每回合从零重算，
+ * 就是 O(回合 × 上下文)。实测：160 回合时估算吃掉 run 全部框架 CPU 的约 88%、
+ * 累计 467ms（10→160 回合之间增长 ×103，明显超线性）。
+ *
+ * 这里缓存「已计过的前缀」，只对**新增消息**计数 —— 追加场景降为 O(上下文)。
+ * 数组引用变了、或长度变短（策略裁剪过 / 换了新数组）→ 自动从零重算，所以
+ * 在 `messages.splice(...)` 原地替换后也不会读到脏缓存。
+ */
+export declare function createTokenCounter(estimate?: (text: string) => number): (messages: Anthropic.MessageParam[]) => number;
 /** 把消息渲染成可喂给摘要器的纯文本（role: content）。 */
 export declare function renderMessages(messages: Anthropic.MessageParam[]): string;
 export interface TrimOptions {
-    /** 保留最近几对 tool exchange；缺省 1 */
-    keepRecent?: number;
+    /** 保留最近几对 tool exchange（tool_use→tool_result **对数**）；缺省 1 */
+    keepToolPairs?: number;
 }
 /**
- * context editing：丢弃旧的 tool_use→tool_result 对（超出 keepRecent 的），
+ * context editing：丢弃旧的 tool_use→tool_result 对（超出 keepToolPairs 的），
  * 保留最近 N 对以及所有非工具消息。逐对整体移除，保角色交替合法。
  * 返回原数组引用（若无需裁剪）或新数组。
+ *
+ * 前置：历史必须是工具块严格成对的（toolBlocksPaired）。畸形历史直接返回原数组
+ * —— 宁可少裁剪，也不能切出孤立 tool_use/tool_result 让后续请求 400。
  */
 export declare function trimToolPairs(messages: Anthropic.MessageParam[], opts?: TrimOptions): Anthropic.MessageParam[];
 export interface CompactOptions {