@faapi/agent 6.16.0 → 6.18.0

package/dist/index.d.ts

@@ -242,9 +242,10 @@ interface AgentTrace {
     startedAt: number;
     /** 总耗时 ms（done 时填充,抛错时也填充） */
     durationMs?: number;
-    /** 总轮数（与 ReactLoopResult.turns 一致） */
+    /** 总轮数（与 ReactLoopResult.turns 一致,整树口径——含全部 sub-agent 循环轮数;
+     *  事件 turn 序号是主循环口径,与此独立） */
     turns: number;
-    /** 累计 token 用量（与 ReactLoopResult.usage 一致） */
+    /** 累计 token 用量（与 ReactLoopResult.usage 一致,整树口径——含全部 sub-agent 循环） */
     usage?: LLMUsage;
     /** 最终停止原因（与 ReactLoopResult.stopReason 一致） */
     stopReason?: LLMStopReason;
@@ -269,7 +270,7 @@ type AgentTraceEvent = LlmCallEvent | ToolCallEvent | SubAgentCallEvent;
  */
 interface LlmCallEvent {
     type: 'llm_call';
-    /** 第几轮（从 1 开始） */
+    /** 第几轮（从 1 开始;主循环口径,sub-agent 内部轮在各层 sub-trace 里） */
     turn: number;
     startedAt: number;
     durationMs?: number;
@@ -304,12 +305,16 @@ interface ToolCallEvent {
     error?: string;
 }
 /**
- * sub-agent 调用事件——executeTool 返回 TracingToolResult 时触发
+ * sub-agent 调用事件——executeTool 返回 SubAgentToolResult（trace 存在时）
+ * 或旧 TracingToolResult 时触发
  *
- * sub-agent 的 trace 嵌入 `trace` 字段（递归结构）,业务方可还原完整调用树。
+ * sub-agent 的 trace 嵌入 `trace` 字段（递归结构）,业务方可还原完整调用树;
+ * sub 循环的 usage/turns 已由 reactLoop 上卷进父 run 台账（整树口径）,
+ * 逐层明细经各层 sub-trace 还原。
  */
 interface SubAgentCallEvent {
     type: 'subagent_call';
+    /** 第几轮（从 1 开始;主循环口径） */
     turn: number;
     startedAt: number;
     durationMs?: number;
@@ -328,12 +333,17 @@ interface SubAgentCallEvent {
 /**
  * sub-agent 调用的特殊返回值——reactLoop 据此识别 sub-agent 调用并发出 subagent_call 事件
  *
- * [Agent.executeSubAgent](./agent.md) 在 `enableTracing=true` 时返回此类型;
- * `enableTracing=false` 时返回 `unknown`（与常规 tool 一致）。
+ * **旧版结构（兼容保留）**：无用量字段、不上卷 usage/turns。框架内部的
+ * [Agent.executeSubAgent](./agent.md) 已改用 [SubAgentToolResult](./reactLoop.md)
+ * （`__subAgent` 标记,携带子循环整树 `usage` / `turns`,tracing 开启时附 `trace`）——
+ * 新代码应使用 SubAgentToolResult。reactLoop 对两者都识别（存量业务方直接调
+ * `reactLoop` 自定义 `executeTool` 构造本类型的代码不受影响）。
  *
  * `__trace` 是标记字段,避免与普通对象返回值冲突。reactLoop 通过
  * `typeof result === 'object' && result !== null && result.__trace === true`
  * 判断是否为 TracingToolResult。
+ *
+ * @deprecated 改用 SubAgentToolResult（reactLoop.ts）——本类型仅为存量兼容保留
  */
 interface TracingToolResult {
     /** 标记字段（避免与普通对象返回值冲突） */
@@ -348,6 +358,9 @@ interface TracingToolResult {
  *
  * reactLoop 用此函数区分 sub-agent 调用（发出 subagent_call 事件）
  * 与常规 tool 调用（发出 tool_call 事件）。
+ *
+ * @deprecated 框架内部已改用 isSubAgentToolResult（reactLoop.ts）；本守卫仅为
+ * 存量自定义 executeTool 的兼容识别保留
  */
 declare function isTracingToolResult(value: unknown): value is TracingToolResult;
 
@@ -364,14 +377,66 @@ declare function isTracingToolResult(value: unknown): value is TracingToolResult
  * 由 [Agent 类](./agent.md)提供——reactLoop 不关心 tool 如何被找到和执行。
  * Agent 类的 `executeTool` 实现：
  * - 常规 tool → `loadToolModule` 加载 handler 并调用
- * - agent-as-tool（`agent.` 前缀）→ 递归调子 agent 的 reactLoop（含 `maxAgentDepth` 防护）
+ * - agent-as-tool（`agent.` 前缀）→ 递归调子 agent 的 reactLoop（`maxAgentDepth` 防护由 Agent 类在 `executeTool` 内实现），
+ *   返回 [SubAgentToolResult](#subagenttoolresult)（携带子循环整树 `usage` / `turns` 供父循环上卷）
  *
  * 返回值可以是任意类型——非 string 会被 JSON.stringify 后回传 LLM。
  *
- * sub-agent 调用时,若 `enableTracing=true`,返回 [TracingToolResult](./trace.md)
- * 携带 sub-agent 的 trace,reactLoop 据此发出 `subagent_call` 事件（嵌套递归 trace）。
+ * sub-agent 调用时,`SubAgentToolResult.trace` 存在（`enableTracing=true`）时
+ * reactLoop 发出 `subagent_call` 事件（嵌套递归 trace）；旧 `TracingToolResult`
+ * （`__trace` 标记,无用量字段）仍兼容识别,但不上卷用量。
+ */
+/**
+ * 嵌套子代理循环的增量（流式父循环冒泡透出）
+ *
+ * 仅流式路径产生；`depth` 与 `maxAgentDepth` 口径一致（根循环 = 1,首次嵌套的
+ * 子代理 = 2）。`deltaContent` / `deltaReasoning` 至少存在其一。
+ */
+interface SubAgentDelta {
+    /** 发起调用的 tool 名（agent.<name>） */
+    name: string;
+    /** 该子代理循环的递归深度（根 = 1） */
+    depth: number;
+    deltaContent?: string;
+    deltaReasoning?: string;
+}
+/**
+ * delta 冒泡出口：executeTool 执行 sub-agent 时回调透出嵌套循环增量
+ *
+ * 仅流式父循环传入（`reactLoopStream` 的 tool 执行段构造 emitter 经第三参下发）；
+ * 非流式 `reactLoop` 不传（结果一次性返回,无冒泡需求）。
+ */
+interface SubAgentDeltaEmitter {
+    onSubAgentDelta(delta: SubAgentDelta): void;
+}
+type ToolExecutor = (name: string, args: Record<string, unknown>, deltaEmitter?: SubAgentDeltaEmitter) => Promise<unknown | SubAgentToolResult>;
+/**
+ * sub-agent tool 的结构化返回值——reactLoop 据此上卷子循环用量、剥壳回传、发 subagent_call 事件
+ *
+ * [Agent.executeSubAgent](./agent.md) 在 sub-agent 走默认 reactLoop 时统一构造
+ * （无论 tracing 开关——用量上卷不依赖 tracing）。reactLoop 通过
+ * `isSubAgentToolResult` 识别后：`usage` / `turns` 累加进父循环（整树口径,
+ * 详见 reactLoop.md「usage 与 turns 的整树口径」）,随后剥壳取 `result` 作为
+ * tool 消息回传 LLM;`trace` 存在时再发 `subagent_call` 事件。
+ *
+ * `__subAgent` 是标记字段,避免与普通对象返回值冲突。
+ */
+interface SubAgentToolResult {
+    /** 标记字段（避免与普通对象返回值冲突） */
+    __subAgent: true;
+    /** 子代理返回的业务结果（stringifyResult 后作为 tool 消息内容回传 LLM） */
+    result: unknown;
+    /** 子循环整树 token 用量（自定义 run 的 sub-agent 无结构化用量,缺省 = 计 0） */
+    usage?: LLMUsage;
+    /** 子循环整树轮数（缺省 = 计 0） */
+    turns?: number;
+    /** 子循环 trace（`enableTracing=true` 时携带,reactLoop 发 subagent_call 事件并嵌入） */
+    trace?: AgentTrace;
+}
+/**
+ * 类型守卫：判断 ToolExecutor 返回值是否为 SubAgentToolResult
  */
-type ToolExecutor = (name: string, args: Record<string, unknown>) => Promise<unknown | TracingToolResult>;
+declare function isSubAgentToolResult(value: unknown): value is SubAgentToolResult;
 /**
  * reactLoop 配置
  *
@@ -420,10 +485,11 @@ interface ReactLoopConfig {
      */
     messages?: LLMMessage[];
     /**
-     * 启用 tracing（默认 true）。开启时填充 `ReactLoopResult.trace` /
-     * `ReactLoopStreamChunk.traceEvent`,详见 [trace.md](./trace.md)。
+     * 启用 tracing（默认 false——opt-in,不开启零开销）。开启时填充
+     * `ReactLoopResult.trace` / `ReactLoopStreamChunk.traceEvent`,详见 [trace.md](./trace.md)。
      *
-     * 业务方在生产主路径显式传 `false` 关闭以零开销运行。
+     * 与 `AgentRuntimeConfig.enableTracing` / `AgentRunOptions.enableTracing` 同语义：
+     * 优先级 options > 全局 config > 默认 false。
      */
     enableTracing?: boolean;
 }
@@ -441,11 +507,18 @@ interface ReactLoopResult {
     reasoning?: string;
     /** 完整对话历史（system + user + assistant + tool 消息） */
     messages: LLMMessage[];
-    /** 使用的轮数（含最终轮） */
+    /**
+     * 使用的轮数（整树口径：主循环轮数 + 全部 sub-agent 循环轮数）。
+     * `maxTurns` 循环控制与 trace 事件的 `turn` 序号只按主循环计（子代理轮数不挤占父循环预算）。
+     */
     turns: number;
     /** 最终轮的停止原因 */
     stopReason: LLMStopReason;
-    /** 累计 token 用量（多轮累加，provider 不返回时为 `undefined`） */
+    /**
+     * 累计 token 用量（整树口径：本次 run 全部 `llm_call` usage 之和,含全部层级的
+     * sub-agent 循环,自定义 run 的 sub-agent 计 0;provider 不返回时为 `undefined`）。
+     * 详见 reactLoop.md「usage 与 turns 的整树口径」。
+     */
     usage?: LLMUsage;
     /**
      * 结构化调用明细（`enableTracing=true` 时填充,否则 `undefined` 零开销）。
@@ -479,9 +552,14 @@ interface ReactLoopStreamChunk {
         name: string;
         result: string;
     };
+    /**
+     * 嵌套子代理循环的增量（冒泡透传;仅流式路径）。
+     * 详见 reactLoop.md「子代理 delta 冒泡」章节。
+     */
+    subagentDelta?: SubAgentDelta;
     /**
      * trace 事件（`enableTracing=true` 时增量推送）。
-     * 与 deltaContent / deltaReasoning / toolCall / toolResult / done 互斥,一个 chunk 至多一个字段。
+     * 与 deltaContent / deltaReasoning / toolCall / toolResult / subagentDelta / done 互斥,一个 chunk 至多一个字段。
      */
     traceEvent?: AgentTraceEvent;
     /** 循环结束 */
@@ -489,8 +567,10 @@ interface ReactLoopStreamChunk {
         content: string;
         /** 最终轮的完整推理内容（thinking 模型；无推理内容时不存在） */
         reasoning?: string;
+        /** 整树口径（主循环 + 全部 sub-agent 循环），与 ReactLoopResult.turns 一致 */
         turns: number;
         stopReason: LLMStopReason;
+        /** 整树口径（全部 llm_call 之和），与 ReactLoopResult.usage 一致 */
         usage?: LLMUsage;
     };
 }
@@ -719,6 +799,13 @@ interface AgentRuntimeConfig {
     maxAgentDepth?: number;
     /** 发送给 LLM 的历史 token 预算（近似估算,未设置 = 不裁剪）——透传 reactLoop,见 reactLoop.md 历史裁剪章节 */
     maxHistoryTokens?: number;
+    /**
+     * 单次 tool 执行的超时毫秒数（未设置 = 不限时）。超时抛 `AgentToolTimeoutError`,
+     * 被 reactLoop 按既有 tool 错误路径回传 LLM（LLM 可决定重试或换路）——挂死的
+     * tool handler（如无超时的内部 fetch）此前会让整个 run 永久挂起,且 run 的
+     * abort signal 对 tool 执行无效
+     */
+    toolTimeoutMs?: number;
     /**
      * 启用 tracing 的全局默认值（默认 false——opt-in,不开启零开销）。
      *
@@ -843,6 +930,14 @@ declare class AgentError extends Error {
  *
  * 被 [reactLoop](./reactLoop.md) catch 后错误消息回传 LLM，LLM 可据此调整策略。
  */
+/** tool 执行超时（toolTimeoutMs）——被 reactLoop catch 后回传 LLM,不终止整个 run */
+declare class AgentToolTimeoutError extends AgentError {
+    /** 超时的 tool 名 */
+    readonly toolName: string;
+    /** 配置的超时毫秒数 */
+    readonly timeoutMs: number;
+    constructor(toolName: string, timeoutMs: number);
+}
 declare class AgentRecursionError extends AgentError {
     /** 配置的 maxAgentDepth 值 */
     readonly maxDepth: number;
@@ -951,6 +1046,13 @@ declare class Agent {
      * `options.messages` 提供时先经 `validateResumeHistory` 结构校验,非法抛
      * `AgentError`,不发起 LLM 请求。
      */
+    /**
+     * 构建执行白名单：agent 声明的 tools + sub-agents（`agent.` 前缀）
+     *
+     * 每次 run 构建一次存入 callCtx（executeTool 复用）——reload 场景注册表换代后
+     * 新 run 重新构建，声明变化自然生效
+     */
+    private buildDeclaredTools;
     private buildLoopConfig;
     /**
      * 解析外部 provider（`options.provider`）→ provider + model
@@ -1005,7 +1107,7 @@ declare class Agent {
     /**
      * tool 执行路由（由 reactLoop 调用）
      *
-     * - `agent.` 前缀 → {@link executeSubAgent} 递归（含 enableTracing + TracingToolResult 包装）
+     * - `agent.` 前缀 → {@link executeSubAgent} 递归（含 usage/turns 上卷 + tracing 包装）
      * - 常规 tool → `loadToolModule` 加载 handler + 可选 input 校验 → 调用
      *
      * `callCtx` 由 [buildLoopConfig](#buildLoopConfig) 闭包捕获传入——本次调用的有效
@@ -1022,19 +1124,22 @@ declare class Agent {
      * sub-agent 递归执行
      *
      * 1. `maxAgentDepth` 防护——超限抛 {@link AgentRecursionError}
-     * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`（无 trace,与常规 tool 一致）
+     * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`（无 trace、无结构化
+     *    usage 可卷——直接返回业务结果,其 token 不进入父 run 台账）
      * 3. 无 `run` 时调 `subAgent.run(stringify(args), { agent, provider, model, enableTracing })`
      *    走默认 reactLoop——继承父调用的 provider,sub 元数据声明 `model` 时优先用自身的,
      *    未声明时沿用父 model
      *
-     * **tracing 路径**：`enableTracing=true` 时,subAgent.run 返回的 `result.trace`（agentName
-     * 已被 `Agent.run` 填为 subName）被包装为 [TracingToolResult](./trace.md) 返回给 reactLoop。
-     * reactLoop 通过 `isTracingToolResult` 识别后发出 `subagent_call` 事件,嵌入 sub-trace
-     * （递归结构,业务方可还原完整调用树）。`enableTracing=false` 时返回 `result.content`
-     * （unknown,与常规 tool 一致,零开销）。
+     * **返回值统一包装为 [SubAgentToolResult](./reactLoop.md)**（无论 tracing 开关——
+     * 用量上卷不依赖 tracing）：`usage` / `turns` 是子循环整树口径（sub-sub 已在子循环
+     * 上卷）,reactLoop 识别后累加进父循环,父 run 的 usage 台账 = 全部 `llm_call` 之和。
+     * `enableTracing=true` 时再附 `trace`（agentName 已被 `Agent.run` 填为 subName）,
+     * reactLoop 据此发出 `subagent_call` 事件,嵌入 sub-trace（递归结构,业务方可还原
+     * 完整调用树）。详见 reactLoop.md「usage 与 turns 的整树口径」。
      *
-     * **自定义 run 无 trace**：业务方导出 `run` 函数时直接返回业务结果,无法采集 sub-agent
-     * 内部明细——需 trace 时应让 sub-agent 走默认 reactLoop（不导出 `run`）。
+     * **自定义 run 无 trace、无用量上卷**：业务方导出 `run` 函数时直接返回业务结果,
+     * 无法采集 sub-agent 内部明细——需 trace / 用量统计时让 sub-agent 走默认 reactLoop
+     * （不导出 `run`）。
      *
      * 自定义 run 接收原始 args 对象；默认 reactLoop 的 user 消息：args 恰为单字段
      * `{ input: <string> }`（与显式入参 schema 形状一致）时直传字符串,其余形状
@@ -1132,4 +1237,4 @@ declare function createToolSchemaResolver(options?: {
  */
 declare const agentPlugin: FaapiPlugin;
 
-export { Agent, AgentAbortError, type AgentDeps, AgentError, type AgentHandle, AgentRecursionError, type AgentRunOptions, type AgentRuntimeConfig, type AgentTrace, type AgentTraceEvent, type LLMCompleteRequest, type LLMMessage, type LLMProvider, LLMProviderError, type LLMResponse, type LLMStopReason, type LLMStreamChunk, type LLMToolCall, type LLMToolDefinition, type LLMUsage, type LlmCallEvent, type ReactLoopConfig, ReactLoopError, type ReactLoopResult, type ReactLoopStreamChunk, type SubAgentCallEvent, type ToolCallEvent, type ToolExecutor, type ToolSchemaResolution, type TracingToolResult, createOpenAIProvider, createProvider, createToolSchemaResolver, agentPlugin as default, isTracingToolResult, reactLoop, reactLoopStream };
+export { Agent, AgentAbortError, type AgentDeps, AgentError, type AgentHandle, AgentRecursionError, type AgentRunOptions, type AgentRuntimeConfig, AgentToolTimeoutError, type AgentTrace, type AgentTraceEvent, type LLMCompleteRequest, type LLMMessage, type LLMProvider, LLMProviderError, type LLMResponse, type LLMStopReason, type LLMStreamChunk, type LLMToolCall, type LLMToolDefinition, type LLMUsage, type LlmCallEvent, type ReactLoopConfig, ReactLoopError, type ReactLoopResult, type ReactLoopStreamChunk, type SubAgentCallEvent, type SubAgentDelta, type SubAgentDeltaEmitter, type SubAgentToolResult, type ToolCallEvent, type ToolExecutor, type ToolSchemaResolution, type TracingToolResult, createOpenAIProvider, createProvider, createToolSchemaResolver, agentPlugin as default, isSubAgentToolResult, isTracingToolResult, reactLoop, reactLoopStream };