@migor/agentia 0.6.3 → 0.7.1

package/dist/core/tool.d.ts

@@ -54,6 +54,14 @@ export interface RecorderBackend {
     event(id: SpanId, name: string, body: unknown): void;
     setAttribute(id: SpanId, key: string, value: string | number | boolean): void;
     snapshot(status: SpanStatus): Trace;
+    /**
+     * 整条 run 的累计 usage（只算 `llm.turn` 的**自身**计量，子 agent 的往返也在内）。
+     *
+     * 与 `snapshot(status).totalUsage` **同一口径**，但不拷 spans / attributes / events ——
+     * 预算护栏每回合要判两次（回合入口 + 回合末），走 `snapshot()` 会白拷全部 span 的
+     * attributes/events（O(回合 × 累计事件量)）。**只看总量**的消费者该走这里。
+     */
+    usage(): Usage;
 }
 /**
  * engine 对模型端的最小结构面（R4 多模型）：消息形态由 core/message.js 的自有类型族
@@ -117,6 +125,16 @@ export interface ToolRunContext {
      * 模型在子循环里会退化成"未定价"（成本恒 0，`maxCostUsd` 静默失效）。
      */
     priceOverrides?: Record<string, ModelPricing>;
+    /**
+     * 宿主的未定价告警回调（F2，见 `RunAgentOptions.onUnpricedModel`）：模型不在价格表、
+     * 成本算不出时每模型回调一次。嵌套能力（@SubAgent / @Skill）拉起自己的 llm 循环时
+     * 必须原样传下去 —— 否则子循环里的「算不出成本」只有 `usage.unpriced` 事件、
+     * 宿主的告警回调静默缺席（`maxCostUsd` 在子循环里失效了却没人知道）。
+     */
+    onUnpricedModel?: (info: {
+        model: string;
+        spanId: string;
+    }) => void;
     /**
      * 本次工具调用的**引擎侧预算**（毫秒）= 本次 run 的 `RunAgentOptions.toolTimeoutMs`；
      * undefined / 非正 = 引擎不设超时。
@@ -146,6 +164,43 @@ export interface ToolRunContext {
     maxTotalTokens?: number;
     /** 成本硬管控（C1）透传：累计成本（美元）上限；同 maxTotalTokens 的透传语义 */
     maxCostUsd?: number;
+    /**
+     * 本工具的审批决定（HITL）：仅当该工具声明了 `approval: 'required'` 且本次调用的
+     * 决定已到达时在场 —— 工具体内可据此读到自己「被谁、什么时候、以什么理由」
+     * 批准/拒绝（审计日志、按 decidedBy 分级授权等）。
+     */
+    approval?: ApprovalDecision;
+    /**
+     * 工具执行被引擎**放弃等待**的信号（`toolTimeoutMs` 超时触发）。
+     *
+     * 放弃 ≠ 取消：超时的语义是「不等了」，没有它时工具在后台继续跑、副作用与花费
+     * 都不进任何 trace。想「真停」的工具监听它自行收尾 —— 框架自带的
+     * @SubAgent / @Skill 就是这么做的：收到信号即中止子循环（在飞请求被 signal
+     * 中止，不再烧 token），capability span 立刻以 error 收尾（交付的 trace 里不留
+     * 永不闭合的半截 span）。
+     */
+    abandoned?: AbortSignal;
+}
+/**
+ * 人工审批决定（HITL）：一条 tool_use 的批准/拒绝结论。
+ * 以 **tool_use_id 为键**传给引擎（`RunAgentOptions.approvals`）或随任务落库
+ * （`TaskRecord.approvals` —— 进程重启不丢）。
+ */
+export interface ApprovalDecision {
+    /** true = 批准执行；false = 拒绝（该条 tool_result 记 is_error，理由回给模型） */
+    approved: boolean;
+    /** 拒绝理由 / 备注（回给模型，模型可据此换路） */
+    reason?: string;
+    /** 审批人标识（审计用） */
+    decidedBy?: string;
+    /** 决定时刻（epoch ms）；缺省由框架在收到决定时填 `Date.now()` */
+    decidedAt?: number;
+    /**
+     * 审批请求挂起的时刻（epoch ms）—— 框架回填，调用方不必设置。
+     * trace 的 `approval.decided` 事件里 `waitedMs = decidedAt - requestedAt` 靠它算出；
+     * 缺省（如手工给 `runAgent` 传 approvals）时该事件不带 waitedMs。
+     */
+    requestedAt?: number;
 }
 export interface AgentTool<I = unknown, O = unknown> {
     /** 模型可见的唯一名（建议 snake_case） */
@@ -154,6 +209,15 @@ export interface AgentTool<I = unknown, O = unknown> {
     inputSchema: JsonSchema;
     /** 开启严格参数校验（schema 需 additionalProperties:false + required） */
     strict?: boolean;
+    /**
+     * 人工审批闸（HITL）：`'required'` 时模型发起的该工具调用**不直接执行** ——
+     * 该回合挂起（`stopReason: 'awaiting_approval'`，回合级全有或全无：同一回合的
+     * 其他工具也一并等待，因为协议要求每个 tool_use 都有配对 tool_result），
+     * 等宿主把决定（`ApprovalDecision`，按 tool_use_id）喂回来后恢复：
+     * 批准 → 正常执行（工具体内经 `ToolRunContext.approval` 读到自己的决定）；
+     * 拒绝 → 该条 tool_result 记 `is_error: true`（理由回给模型，可自行换路）。
+     */
+    approval?: 'required';
     /**
      * 执行体。入参 = 模型按 schema 解析的结构化 input；
      * ctx 由 engine 注入（含 recorder/父 span），需要开嵌套 span 的能力（子 agent）用，

package/dist/engine/budget.d.ts

@@ -1,4 +1,4 @@
-import type { Trace } from '../core/trace.js';
+import type { Usage } from '../core/trace.js';
 /**
  * Agentia —— 成本硬管控（C1，补 spec §6.4 的欠账）。
  *
@@ -39,11 +39,24 @@ export interface BudgetGuardOptions {
     onExceed?: ((snapshot: BudgetSnapshot) => void) | undefined;
 }
 export interface BudgetGuard {
-    /** 每回合记账完成后调用；超限返回 `'tokens' | 'cost'`，否则 `null` */
-    check(trace: Trace): 'tokens' | 'cost' | null;
+    /**
+     * 每回合记账完成后调用；超限返回 `'tokens' | 'cost'`，否则 `null`。
+     *
+     * ⚠️ 入参**只收它真正要读的那一项**，不是整份 `Trace`：本护栏每回合要判**两次**
+     * （回合入口 + 回合末），而 `TraceRecorder.snapshot()` 会拷全部 span 的
+     * attributes/events（O(回合 × 累计事件量)，长 run 下是白花的钱）。`Trace` 结构上
+     * 满足本类型，所以既有调用方（传整份 trace）不受影响；引擎侧传廉价视图即可：
+     * `check({ totalUsage: recorder.usage() })`。
+     *
+     * 收窄还有个附带好处：护栏**在类型上就没法**再去读 `spans` —— 「只看 totalUsage」
+     * 这条口径从注释变成了结构约束。
+     */
+    check(input: {
+        readonly totalUsage: Usage;
+    }): 'tokens' | 'cost' | null;
 }
 /**
- * 建一个预算护栏。`check` 只看 **trace.totalUsage**（已由 recorder 按 llm.turn 求和，
+ * 建一个预算护栏。`check` 只看 **totalUsage**（已由 recorder 按 llm.turn 求和，
  * 子 agent 的往返也在内 —— 所以这是**整条 run** 的口径，不只是主循环）。
  */
 export declare function createBudgetGuard(opts?: BudgetGuardOptions): BudgetGuard;

package/dist/engine/budget.js

@@ -1,12 +1,12 @@
 /**
- * 建一个预算护栏。`check` 只看 **trace.totalUsage**（已由 recorder 按 llm.turn 求和，
+ * 建一个预算护栏。`check` 只看 **totalUsage**（已由 recorder 按 llm.turn 求和，
  * 子 agent 的往返也在内 —— 所以这是**整条 run** 的口径，不只是主循环）。
  */
 export function createBudgetGuard(opts = {}) {
     const { maxTotalTokens, maxCostUsd, onExceed } = opts;
     return {
-        check(trace) {
-            const u = trace.totalUsage;
+        check(input) {
+            const u = input.totalUsage;
             const totalTokens = u.inputTokens + u.outputTokens + u.cacheReadTokens + u.cacheCreationTokens;
             const costUsd = u.costEstimate ?? 0;
             if (maxTotalTokens != null && totalTokens > maxTotalTokens) {

package/dist/engine/budget.js.map

@@ -1 +1 @@
-{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/engine/budget.ts"],"names":[],"mappings":"AAiDA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAAuB,EAAE;IAC7D,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACtD,OAAO;QACL,KAAK,CAAC,KAAY;YAChB,MAAM,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;YAC3B,MAAM,WAAW,GACf,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,mBAAmB,CAAC;YAC7E,MAAM,OAAO,GAAG,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;YACpC,IAAI,cAAc,IAAI,IAAI,IAAI,WAAW,GAAG,cAAc,EAAE,CAAC;gBAC3D,QAAQ,EAAE,CAAC;oBACT,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE,cAAc;oBACrB,MAAM,EAAE,WAAW;oBACnB,WAAW;oBACX,OAAO;iBACR,CAAC,CAAC;gBACH,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,IAAI,UAAU,IAAI,IAAI,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;gBAC/C,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;gBACvF,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/engine/budget.ts"],"names":[],"mappings":"AA4DA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAAuB,EAAE;IAC7D,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACtD,OAAO;QACL,KAAK,CAAC,KAAqC;YACzC,MAAM,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;YAC3B,MAAM,WAAW,GACf,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,mBAAmB,CAAC;YAC7E,MAAM,OAAO,GAAG,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;YACpC,IAAI,cAAc,IAAI,IAAI,IAAI,WAAW,GAAG,cAAc,EAAE,CAAC;gBAC3D,QAAQ,EAAE,CAAC;oBACT,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE,cAAc;oBACrB,MAAM,EAAE,WAAW;oBACnB,WAAW;oBACX,OAAO;iBACR,CAAC,CAAC;gBACH,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,IAAI,UAAU,IAAI,IAAI,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;gBAC/C,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;gBACvF,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/loop.d.ts

@@ -33,6 +33,13 @@ export interface AgentLoopResult<T = unknown> {
     iterations: number;
     /** submit_result 校验通过的结构化结果；未提交则为 undefined（类型由 resultSchema 推导） */
     typed: T | undefined;
+    /**
+     * HITL 挂起（stopReason === 'awaiting_approval'）时的完整消息历史
+     * （末尾是含未决 tool_use 的 assistant 消息）；未挂起为 undefined（字段在场）。
+     */
+    suspendedMessages: MessageParam[] | undefined;
+    /** HITL 挂起时待决的 tool_use_id 列表；未挂起为 undefined（字段在场） */
+    pendingApprovals: string[] | undefined;
 }
 /** 主入口：开 run 根 span，循环跑在其下。返回完整 trace（traceId 即 runId）。 */
 export declare function runAgent<S extends JsonSchema = JsonSchema>(options: RunAgentOptions<S>): Promise<AgentRunResult<SchemaType<S>>>;

package/dist/engine/loop.js

@@ -28,6 +28,38 @@ const DEFAULT_MAX_ITERATIONS = 40;
 function forkPolicyPerRun(policy) {
     return policy?.forRun ? policy.forRun() : policy;
 }
+/**
+ * 取消息历史**末尾**那条 assistant 消息里待解决的 tool_use 块（恢复模式检测）。
+ * 空数组 = 不是恢复场景（正常从 user 消息起跑）。
+ */
+function tailToolUses(messages) {
+    const tail = messages[messages.length - 1];
+    if (tail?.role !== 'assistant' || !Array.isArray(tail.content))
+        return [];
+    // ToolUseBlockParam 结构上兼容 ToolUseBlock（多一个可选 cache_control）
+    return tail.content.filter((b) => b.type === 'tool_use');
+}
+/** 取 MessageParam（请求侧）里的文本块拼成的文本（恢复模式收尾时用） */
+function textOfParam(message) {
+    if (!Array.isArray(message.content))
+        return typeof message.content === 'string' ? message.content : '';
+    return message.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text ?? '')
+        .join('\n');
+}
+/** 挂起收尾的结果对象（两处出口共用：循环中途挂起 / 恢复模式进来发现决定仍不齐） */
+function suspendResult(ctx, pending) {
+    return {
+        stopReason: 'awaiting_approval',
+        finalText: '',
+        error: undefined,
+        iterations: ctx.progress.iterations,
+        typed: ctx.typed,
+        suspendedMessages: [...ctx.messages],
+        pendingApprovals: pending,
+    };
+}
 /**
  * 循环体核心：带父 span 跑一轮 manual loop。请求失败按 error 收掉 turn 后抛出，由外层收尾。
  *
@@ -43,6 +75,45 @@ async function agentLoop(args) {
     let error;
     let finalText = '';
     let finished = false;
+    // 恢复模式（HITL 挂起续跑，也是通用续跑入口）：messages 末尾是含 tool_use 的
+    // assistant 消息 ⇒ 这些 tool_use 尚未解决。跳过模型请求，先把它们解决掉再进正常
+    // 循环 —— assistant 消息已在历史里，**不重复 push**。决定仍不齐则再次挂起
+    // （不发请求、零花费）。
+    const resumeUses = tailToolUses(ctx.messages);
+    if (resumeUses.length > 0) {
+        // 已取消：不执行任何工具（副作用不该在取消后发生），按 aborted 收尾
+        if (args.signal?.aborted) {
+            return {
+                stopReason: 'aborted',
+                finalText: '',
+                error: abortedError(),
+                iterations: 0,
+                typed: undefined,
+                suspendedMessages: undefined,
+                pendingApprovals: undefined,
+            };
+        }
+        // 工具事件记到父 span：被恢复的回合属于挂起段的旧 trace，本段没有对应 llm.turn
+        const outcome = await executeTurnTools(ctx, args.parentSpanId ?? '', resumeUses, null);
+        if (outcome.kind === 'suspended') {
+            return suspendResult(ctx, outcome.pending);
+        }
+        if (outcome.results.length > 0)
+            ctx.messages.push({ role: 'user', content: outcome.results });
+        if (ctx.submitted) {
+            // 恢复的回合里 submit_result 校验通过：直接落定（finalText 取该 assistant 消息的文本块）
+            const tail = ctx.messages[ctx.messages.length - 2]; // 刚 push 了 tool_results，前一条是那条 assistant
+            return {
+                stopReason: 'end_turn',
+                finalText: tail ? textOfParam(tail) : '',
+                error: undefined,
+                iterations: 0,
+                typed: ctx.typed,
+                suspendedMessages: undefined,
+                pendingApprovals: undefined,
+            };
+        }
+    }
     for (let iteration = 0; iteration < args.maxIterations; iteration++) {
         const halt = await checkTurnEntry(ctx, iteration);
         if (halt) {
@@ -65,7 +136,7 @@ async function agentLoop(args) {
         // - 模型本回合自然收尾 → 不因「最后一回合把额度用超了」把已成功的 run 改判失败
         //   （只留 budget.exceeded 事件，可观测）；
         // - 循环还要继续（模型要求调工具）→ 停在这里，不再发下一个请求 = 不再花钱。
-        const overBudget = ctx.budget ? ctx.budget.check(args.recorder.snapshot('ok')) : null;
+        const overBudget = ctx.budget ? ctx.budget.check({ totalUsage: args.recorder.usage() }) : null;
         ctx.messages.push({ role: 'assistant', content: message.content });
         const resolution = resolveStopReason(message, args.maxTokens);
         if (resolution.kind === 'finish') {
@@ -76,9 +147,17 @@ async function agentLoop(args) {
             finished = true;
             break;
         }
-        const toolResults = await executeTurnTools(ctx, turnId, resolution.toolUses, overBudget);
-        if (toolResults.length > 0)
-            ctx.messages.push({ role: 'user', content: toolResults });
+        const outcome = await executeTurnTools(ctx, turnId, resolution.toolUses, overBudget);
+        if (outcome.kind === 'suspended') {
+            // HITL 挂起：assistant 消息（含未决 tool_use）已在历史里、**不推任何 tool_result**
+            // （全有或全无，见 executeTurnTools 的审批闸）；approval.requested 已记在 turn span 上。
+            // error 保持 undefined —— 挂起不是失败。
+            stopReason = 'awaiting_approval';
+            finalText = textOf(message);
+            return { ...suspendResult(ctx, outcome.pending), finalText };
+        }
+        if (outcome.results.length > 0)
+            ctx.messages.push({ role: 'user', content: outcome.results });
         if (ctx.submitted) {
             // submit_result 校验通过：结构化结果落定，循环正常收尾（finalText 取该回合文本，可空）
             stopReason = 'end_turn';
@@ -105,7 +184,15 @@ async function agentLoop(args) {
             retryable: false,
         };
     }
-    return { stopReason, finalText, error, iterations: ctx.progress.iterations, typed: ctx.typed };
+    return {
+        stopReason,
+        finalText,
+        error,
+        iterations: ctx.progress.iterations,
+        typed: ctx.typed,
+        suspendedMessages: undefined,
+        pendingApprovals: undefined,
+    };
 }
 /** 主入口：开 run 根 span，循环跑在其下。返回完整 trace（traceId 即 runId）。 */
 export async function runAgent(options) {
@@ -168,6 +255,7 @@ export async function runAgent(options) {
             maxEventChars: options.maxEventChars,
             priceOverrides: options.priceOverrides,
             onUnpricedModel: options.onUnpricedModel,
+            approvals: options.approvals,
         });
     }
     catch (e) {
@@ -178,9 +266,15 @@ export async function runAgent(options) {
             error: classifyError(e),
             iterations: progress.iterations,
             typed: undefined,
+            suspendedMessages: undefined,
+            pendingApprovals: undefined,
         };
     }
-    const runStatus = isSuccessStopReason(result.stopReason) ? 'ok' : 'error';
+    // awaiting_approval 不是失败：挂起段本身执行无误（「等人」不该被看板算成「失败」），
+    // trace 记 ok；它与成功的区分由 stop_reason attribute 承担。
+    const runStatus = result.stopReason === 'awaiting_approval' || isSuccessStopReason(result.stopReason)
+        ? 'ok'
+        : 'error';
     recorder.setAttribute(rootId, 'stop_reason', result.stopReason);
     recorder.end(rootId, { status: runStatus, ...(result.error ? { error: result.error } : {}) });
     const trace = recorder.snapshot(runStatus);
@@ -191,6 +285,8 @@ export async function runAgent(options) {
         iterations: result.iterations,
         error: result.error,
         typed: result.typed,
+        suspendedMessages: result.suspendedMessages,
+        pendingApprovals: result.pendingApprovals,
     };
 }
 /**

package/dist/engine/loop.js.map

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

package/dist/engine/spec.d.ts

@@ -1,6 +1,5 @@
 import type { MessageParam } from '../core/message.js';
-import type { ModelClient, ModelPricing } from '../core/tool.js';
-import type { AgentTool } from '../core/tool.js';
+import type { AgentTool, ApprovalDecision, ModelClient, ModelPricing } from '../core/tool.js';
 import type { BlackboardSeed } from '../core/blackboard.js';
 import type { TraceContext } from '../core/trace.js';
 import type { ContextPolicy } from './types.js';
@@ -63,6 +62,23 @@ export interface RunInvocationOptions {
      * 截断只影响记账，回给模型的 tool_result 永远完整。见 `RunAgentOptions.maxEventChars`。
      */
     maxEventChars?: number | false;
+    /**
+     * 人工审批决定（HITL）：以 tool_use_id 为键。恢复 `awaiting_approval` 任务时由
+     * 异步宿主随记录传入（纯数据、可序列化，随 `TaskRecord` 落库）；手工续跑
+     * 「assistant 结尾带 tool_use」的消息历史时也可直接给 `app.run`。
+     */
+    approvals?: Record<string, ApprovalDecision>;
+    /**
+     * 会话引用（C4 的**可序列化**形态）：会话 id 字符串，随 `TaskRecord` 落库、
+     * 重启续跑不丢。只被**异步宿主**消费 —— `AsyncRunner` 配了 `sessionStore` 时，
+     * 执行前把它换成 `RunAppOptions.session`（store 实例 + id）注入 run；
+     * 没配 `sessionStore` 而任务带了 `sessionId` 则**响亮失败**（submit 即报
+     * TaskInputError），不静默降级成「没有会话」。
+     *
+     * 同步宿主（HTTP `POST /run` / `runSync`）不消费它：那边没有 store 可注入，
+     * 会话请走程序内的 `RunAppOptions.session`。
+     */
+    sessionId?: string;
 }
 /** 一次任务的规范化入参：messages（已由 normalizeMessages 规整） */
 export interface RunSpec {

package/dist/engine/spec.js.map

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

@@ -37,5 +37,16 @@ export declare class TraceRecorder {
      * 未知 span 静默忽略 —— 与 `event` / `setAttribute` 同一条容错规则（观测不击穿业务）。
      */
     addLink(id: SpanId, link: SpanLink): void;
+    /**
+     * 整条 run 的累计 usage（**只算 `llm.turn` 的自身计量**，子 agent 的往返也在内）。
+     *
+     * 廉价：只扫 `this.spans` 求和，**不拷** attributes / events / links。
+     * `snapshot().totalUsage` 就是调它 —— 两者口径不可能漂移。
+     *
+     * 为什么单拎出来：预算护栏每回合要判**两次**（回合入口 + 回合末），而 `snapshot()`
+     * 会拷全部 span 的 attributes/events ⇒ 白花 O(回合 × 累计事件量)（长 run 下可观）。
+     * 护栏只看这一项，就只给它这一项（见 `engine/budget.ts` 的 `BudgetGuard.check` 入参）。
+     */
+    usage(): Usage;
     snapshot(status: SpanStatus): Trace;
 }

package/dist/engine/tracer.js

@@ -126,10 +126,18 @@ export class TraceRecorder {
             span.links = [];
         span.links.push(link);
     }
-    snapshot(status) {
-        if (!this.rootSpanId)
-            throw new Error('run root not started');
-        const totalUsage = {
+    /**
+     * 整条 run 的累计 usage（**只算 `llm.turn` 的自身计量**，子 agent 的往返也在内）。
+     *
+     * 廉价：只扫 `this.spans` 求和，**不拷** attributes / events / links。
+     * `snapshot().totalUsage` 就是调它 —— 两者口径不可能漂移。
+     *
+     * 为什么单拎出来：预算护栏每回合要判**两次**（回合入口 + 回合末），而 `snapshot()`
+     * 会拷全部 span 的 attributes/events ⇒ 白花 O(回合 × 累计事件量)（长 run 下可观）。
+     * 护栏只看这一项，就只给它这一项（见 `engine/budget.ts` 的 `BudgetGuard.check` 入参）。
+     */
+    usage() {
+        const total = {
             inputTokens: 0,
             outputTokens: 0,
             cacheReadTokens: 0,
@@ -141,19 +149,24 @@ export class TraceRecorder {
         for (const s of this.spans) {
             if (!s.usage || s.kind !== 'llm.turn')
                 continue;
-            totalUsage.inputTokens += s.usage.inputTokens;
-            totalUsage.outputTokens += s.usage.outputTokens;
-            totalUsage.cacheReadTokens += s.usage.cacheReadTokens;
-            totalUsage.cacheCreationTokens += s.usage.cacheCreationTokens;
+            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) {
-                totalUsage.costEstimate = (totalUsage.costEstimate ?? 0) + s.usage.costEstimate;
+                total.costEstimate = (total.costEstimate ?? 0) + s.usage.costEstimate;
             }
         }
         // 与 capability 聚合（end() 内）同一取整口径（1e-6 美元）：浮点连加的尾差
         // （0.1+0.2=0.30000000000000004）不该进 trace/OTLP
-        if (totalUsage.costEstimate != null) {
-            totalUsage.costEstimate = Math.round(totalUsage.costEstimate * 1e6) / 1e6;
+        if (total.costEstimate != null) {
+            total.costEstimate = Math.round(total.costEstimate * 1e6) / 1e6;
         }
+        return total;
+    }
+    snapshot(status) {
+        if (!this.rootSpanId)
+            throw new Error('run root not started');
         return {
             traceId: this.traceId,
             rootSpanId: this.rootSpanId,
@@ -169,7 +182,7 @@ export class TraceRecorder {
                 ...(s.links ? { links: [...s.links] } : {}),
             })),
             status,
-            totalUsage,
+            totalUsage: this.usage(),
         };
     }
 }

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

@@ -11,7 +11,7 @@
  * 与测试 import —— 按仓库约定不进 src/index.ts（纯内部实现细节）。
  */
 import type { Message, MessageParam, ToolParam, ToolResultBlockParam, ToolUseBlock } from '../core/message.js';
-import type { AgentTool, JsonSchema, ModelClient, ModelPricing, RecorderBackend, SchemaType } from '../core/tool.js';
+import type { AgentTool, ApprovalDecision, JsonSchema, ModelClient, ModelPricing, RecorderBackend, SchemaType } from '../core/tool.js';
 import type { SpanError, SpanId } from '../core/trace.js';
 import type { BudgetGuard } from './budget.js';
 import type { ResolvedRetry, RetryOptions } from './retry.js';
@@ -61,6 +61,8 @@ export interface AgentLoopArgs<S extends JsonSchema = JsonSchema> {
         model: string;
         spanId: string;
     }) => void) | undefined;
+    /** 人工审批决定（HITL）：以 tool_use_id 为键；恢复挂起的 run 时由宿主传入 */
+    approvals?: Record<string, ApprovalDecision> | undefined;
 }
 /**
  * 回合上下文：一次 agentLoop 调用内、跨「一回合执行步骤」共享的全部状态。
@@ -121,7 +123,7 @@ export interface TurnOutcome {
 export declare function streamTurn<S extends JsonSchema>(ctx: LoopContext<S>): Promise<TurnOutcome>;
 /**
  * 回合记账：usage 换算 + 成本估算（未定价记事件 + 回调）+ 关 llm.turn span + token 属性。
- * 预算护栏依赖「记账完成后」的 snapshot，所以本函数必须先于任何 budget.check 调用。
+ * 预算护栏依赖「记账完成后」的 usage 累计，所以本函数必须先于任何 budget.check 调用。
  */
 export declare function recordTurnUsage<S extends JsonSchema>(ctx: LoopContext<S>, turnId: SpanId, message: Message): void;
 /** 回合收尾分流：finish = 终止/边界分支（带 stopReason 与收尾文本）；tools = 还有工具要执行 */
@@ -140,12 +142,32 @@ export type StopResolution = {
  * 畸形 tool_use（块为空）与框架不认识的 stop_reason。
  */
 export declare function resolveStopReason(message: Message, maxTokens: number): StopResolution;
+/**
+ * 回合工具执行的结果：
+ * - `executed`：全部执行完（results 与输入一一对应，顺序保持）；
+ * - `suspended`：有需审批的 tool_use 还没有决定 ⇒ **整回合一个工具都没执行**
+ *   （全有或全无，见下），`pending` 是缺决定的 tool_use_id 列表，由 loop 收尾为挂起。
+ */
+export type TurnToolsOutcome = {
+    kind: 'executed';
+    results: ToolResultBlockParam[];
+} | {
+    kind: 'suspended';
+    pending: string[];
+};
 /**
  * —— 执行工具：默认全并行，可由 maxToolConcurrency 收窄（C2）；
  *    单条 user 消息回全部 tool_result（抑制并行是反模式）——
  * submit_result 校验通过会就地更新 ctx.typed / ctx.submitted（先到先得，见 executeOneTool）。
+ *
+ * 审批闸（HITL，**回合级全有或全无**）：任何一个标了 `approval: 'required'` 的
+ * tool_use 在 `args.approvals` 里没有决定 ⇒ 整回合**一个工具都不执行**、不推任何
+ * tool_result（Anthropic 协议要求每个 tool_use 都有配对 tool_result —— 部分执行 +
+ * 部分挂起会产出协议上残缺的历史），记 `approval.requested` 事件后交 loop 挂起。
+ * 两类例外不参与审批：隐藏的 submit_result（不在 args.tools 里，是纯内部提交、
+ * 永不需审批）与未知工具（走既有 unknown_tool 路径）。
  */
-export declare function executeTurnTools<S extends JsonSchema>(ctx: LoopContext<S>, turnId: SpanId, toolUses: ToolUseBlock[], overBudget: 'tokens' | 'cost' | null): Promise<ToolResultBlockParam[]>;
+export declare function executeTurnTools<S extends JsonSchema>(ctx: LoopContext<S>, turnId: SpanId, toolUses: ToolUseBlock[], overBudget: 'tokens' | 'cost' | null): Promise<TurnToolsOutcome>;
 /**
  * 取消息里的全部文本块（引擎侧口径：**多块按 `\n` 连接** —— 多文本块是模型分段的
  * 输出，拼成 `finalText` 要保住分段）。