@faapi/agent 6.16.0 → 6.18.0

package/dist/index.js

@@ -296,21 +296,12 @@ function stripReasoningFromMessages(messages) {
     return rest;
   });
 }
-function normalizeToolCalls(toolCalls, bodyText, status) {
+function normalizeToolCalls(toolCalls, _bodyText, _status) {
   if (!toolCalls || toolCalls.length === 0) return void 0;
   const result = [];
   for (let i = 0; i < toolCalls.length; i++) {
     const tc = toolCalls[i];
     const argsStr = tc?.function?.arguments ?? "{}";
-    try {
-      JSON.parse(argsStr);
-    } catch {
-      const excerpt = argsStr.slice(0, 500);
-      throw new LLMProviderError(`Invalid tool arguments JSON: ${excerpt}`, {
-        status,
-        body: bodyText.slice(0, 500)
-      });
-    }
     result.push({
       id: tc?.id ?? `call_${i}`,
       type: "function",
@@ -394,14 +385,6 @@ function finalizeStreamChunk(accumulators, finishReason, usage) {
       const acc = accumulators.get(idx);
       if (!acc.id || !acc.name) continue;
       const argsStr = acc.argsString || "{}";
-      try {
-        JSON.parse(argsStr);
-      } catch {
-        const excerpt = argsStr.slice(0, 500);
-        throw new LLMProviderError(`Invalid tool arguments JSON: ${excerpt}`, {
-          body: excerpt
-        });
-      }
       toolCalls.push({
         id: acc.id,
         type: "function",
@@ -441,6 +424,9 @@ function isTracingToolResult(value) {
 }
 
 // src/reactLoop.ts
+function isSubAgentToolResult(value) {
+  return typeof value === "object" && value !== null && value.__subAgent === true;
+}
 var ReactLoopError = class extends Error {
   /** 配置的 maxTurns 值 */
   maxTurns;
@@ -565,14 +551,15 @@ async function reactLoop(input, config) {
   const extras = buildRequestExtras(config);
   let totalUsage;
   let finalReasoning;
-  let turns = 0;
+  let loopTurns = 0;
+  let subTurns = 0;
   const traceStartedAt = enableTracing ? nowMs() : 0;
   const traceEvents = enableTracing ? [] : void 0;
-  while (turns < maxTurns) {
+  while (loopTurns < maxTurns) {
     if (config.signal?.aborted) {
       throw new AgentAbortError(void 0, messages);
     }
-    turns++;
+    loopTurns++;
     const llmStartedAt = enableTracing ? nowMs() : 0;
     const outgoing = config.maxHistoryTokens ? trimHistory(messages, config.maxHistoryTokens) : messages;
     const inputSnapshot = enableTracing ? [...outgoing] : void 0;
@@ -596,7 +583,7 @@ async function reactLoop(input, config) {
       const llmEndedAt = nowMs();
       traceEvents.push({
         type: "llm_call",
-        turn: turns,
+        turn: loopTurns,
         startedAt: llmStartedAt,
         durationMs: llmEndedAt - llmStartedAt,
         model: config.model ?? "",
@@ -612,6 +599,7 @@ async function reactLoop(input, config) {
     messages.push(stripReasoning(response.message));
     if (response.stopReason !== "tool_calls" || !response.message.tool_calls) {
       const traceEndedAt = enableTracing ? nowMs() : 0;
+      const turns = loopTurns + subTurns;
       const result = {
         content: response.message.content,
         messages,
@@ -646,7 +634,9 @@ async function reactLoop(input, config) {
         try {
           args = parseToolCallArguments(toolCall);
           rawResult = await config.executeTool(toolName, args);
-          if (isTracingToolResult(rawResult)) {
+          if (isSubAgentToolResult(rawResult)) {
+            resultStr = stringifyResult(rawResult.result);
+          } else if (isTracingToolResult(rawResult)) {
             resultStr = stringifyResult(rawResult.result);
           } else {
             resultStr = stringifyResult(rawResult);
@@ -682,11 +672,31 @@ async function reactLoop(input, config) {
       toolErr,
       hasError
     } of settled) {
+      if (isSubAgentToolResult(rawResult)) {
+        if (rawResult.usage) {
+          totalUsage = accumulateUsage(totalUsage, rawResult.usage);
+        }
+        if (typeof rawResult.turns === "number") {
+          subTurns += rawResult.turns;
+        }
+      }
       if (enableTracing) {
-        if (isTracingToolResult(rawResult)) {
+        if (isSubAgentToolResult(rawResult) && rawResult.trace) {
+          traceEvents.push({
+            type: "subagent_call",
+            turn: loopTurns,
+            startedAt: toolStartedAt,
+            durationMs: toolEndedAt - toolStartedAt,
+            toolCallId: toolCall.id,
+            agentName: extractSubAgentName(toolName),
+            input: JSON.stringify(args),
+            trace: rawResult.trace,
+            result: resultStr
+          });
+        } else if (isTracingToolResult(rawResult)) {
           traceEvents.push({
             type: "subagent_call",
-            turn: turns,
+            turn: loopTurns,
             startedAt: toolStartedAt,
             durationMs: toolEndedAt - toolStartedAt,
             toolCallId: toolCall.id,
@@ -698,7 +708,7 @@ async function reactLoop(input, config) {
         } else {
           traceEvents.push({
             type: "tool_call",
-            turn: turns,
+            turn: loopTurns,
             startedAt: toolStartedAt,
             durationMs: toolEndedAt - toolStartedAt,
             toolCallId: toolCall.id,
@@ -728,12 +738,13 @@ async function* reactLoopStream(input, config) {
   const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
   const extras = buildRequestExtras(config);
   let totalUsage;
-  let turns = 0;
-  while (turns < maxTurns) {
+  let loopTurns = 0;
+  let subTurns = 0;
+  while (loopTurns < maxTurns) {
     if (config.signal?.aborted) {
       throw new AgentAbortError(void 0, messages);
     }
-    turns++;
+    loopTurns++;
     const llmStartedAt = enableTracing ? nowMs() : 0;
     const outgoing = config.maxHistoryTokens ? trimHistory(messages, config.maxHistoryTokens) : messages;
     const inputSnapshot = enableTracing ? [...outgoing] : void 0;
@@ -763,7 +774,6 @@ async function* reactLoopStream(input, config) {
           finishReason = chunk.finishReason;
         }
         if (chunk.usage) {
-          totalUsage = accumulateUsage(totalUsage, chunk.usage);
           turnUsage = chunk.usage;
         }
       }
@@ -773,6 +783,9 @@ async function* reactLoopStream(input, config) {
       }
       throw err;
     }
+    if (turnUsage) {
+      totalUsage = accumulateUsage(totalUsage, turnUsage);
+    }
     const assistantMessage = {
       role: "assistant",
       content: turnContent
@@ -787,7 +800,7 @@ async function* reactLoopStream(input, config) {
       yield {
         traceEvent: {
           type: "llm_call",
-          turn: turns,
+          turn: loopTurns,
           startedAt: llmStartedAt,
           durationMs: llmEndedAt - llmStartedAt,
           model: config.model ?? "",
@@ -801,7 +814,7 @@ async function* reactLoopStream(input, config) {
     if (finishReason !== "tool_calls" || !toolCalls) {
       const donePayload = {
         content: turnContent,
-        turns,
+        turns: loopTurns + subTurns,
         stopReason: finishReason ?? "other",
         usage: totalUsage
       };
@@ -819,11 +832,37 @@ async function* reactLoopStream(input, config) {
       let rawResult;
       let toolErr;
       let hasError = false;
+      const pendingDeltas = [];
+      let wakeDrain = null;
+      const deltaEmitter = {
+        onSubAgentDelta: (delta) => {
+          pendingDeltas.push(delta);
+          const wake = wakeDrain;
+          wakeDrain = null;
+          wake?.();
+        }
+      };
       try {
         args = parseToolCallArguments(toolCall);
         yield { toolCall: { name: toolName, arguments: args } };
-        rawResult = await config.executeTool(toolName, args);
-        if (isTracingToolResult(rawResult)) {
+        const toolPromise = config.executeTool(toolName, args, deltaEmitter);
+        const settled = toolPromise.then(
+          () => true,
+          () => true
+          // 错误延后重抛,此处只关心执行结束以收尾 drain
+        );
+        drain: for (; ; ) {
+          while (pendingDeltas.length > 0) {
+            yield { subagentDelta: pendingDeltas.shift() };
+          }
+          if (await Promise.race([settled, new Promise((r) => wakeDrain = r)])) {
+            break drain;
+          }
+        }
+        rawResult = await toolPromise;
+        if (isSubAgentToolResult(rawResult)) {
+          resultStr = stringifyResult(rawResult.result);
+        } else if (isTracingToolResult(rawResult)) {
           resultStr = stringifyResult(rawResult.result);
         } else {
           resultStr = stringifyResult(rawResult);
@@ -834,14 +873,36 @@ async function* reactLoopStream(input, config) {
         resultStr = stringifyError(err);
         rawResult = void 0;
       }
+      if (isSubAgentToolResult(rawResult)) {
+        if (rawResult.usage) {
+          totalUsage = accumulateUsage(totalUsage, rawResult.usage);
+        }
+        if (typeof rawResult.turns === "number") {
+          subTurns += rawResult.turns;
+        }
+      }
       yield { toolResult: { name: toolName, result: resultStr } };
       if (enableTracing) {
         const toolEndedAt = nowMs();
-        if (isTracingToolResult(rawResult)) {
+        if (isSubAgentToolResult(rawResult) && rawResult.trace) {
+          yield {
+            traceEvent: {
+              type: "subagent_call",
+              turn: loopTurns,
+              startedAt: toolStartedAt,
+              durationMs: toolEndedAt - toolStartedAt,
+              toolCallId: toolCall.id,
+              agentName: extractSubAgentName(toolName),
+              input: JSON.stringify(args),
+              trace: rawResult.trace,
+              result: resultStr
+            }
+          };
+        } else if (isTracingToolResult(rawResult)) {
           yield {
             traceEvent: {
               type: "subagent_call",
-              turn: turns,
+              turn: loopTurns,
               startedAt: toolStartedAt,
               durationMs: toolEndedAt - toolStartedAt,
               toolCallId: toolCall.id,
@@ -855,7 +916,7 @@ async function* reactLoopStream(input, config) {
           yield {
             traceEvent: {
               type: "tool_call",
-              turn: turns,
+              turn: loopTurns,
               startedAt: toolStartedAt,
               durationMs: toolEndedAt - toolStartedAt,
               toolCallId: toolCall.id,
@@ -933,6 +994,18 @@ var AgentError = class extends Error {
     this.name = "AgentError";
   }
 };
+var AgentToolTimeoutError = class extends AgentError {
+  /** 超时的 tool 名 */
+  toolName;
+  /** 配置的超时毫秒数 */
+  timeoutMs;
+  constructor(toolName, timeoutMs) {
+    super(`Tool "${toolName}" timed out after ${timeoutMs}ms`);
+    this.name = "AgentToolTimeoutError";
+    this.toolName = toolName;
+    this.timeoutMs = timeoutMs;
+  }
+};
 var AgentRecursionError = class extends AgentError {
   /** 配置的 maxAgentDepth 值 */
   maxDepth;
@@ -1075,6 +1148,22 @@ var Agent = class _Agent {
    * `options.messages` 提供时先经 `validateResumeHistory` 结构校验,非法抛
    * `AgentError`,不发起 LLM 请求。
    */
+  /**
+   * 构建执行白名单：agent 声明的 tools + sub-agents（`agent.` 前缀）
+   *
+   * 每次 run 构建一次存入 callCtx（executeTool 复用）——reload 场景注册表换代后
+   * 新 run 重新构建，声明变化自然生效
+   */
+  buildDeclaredTools(agentName) {
+    const declared = /* @__PURE__ */ new Set();
+    for (const tool of this.deps.resolveAgentTools(agentName)) {
+      declared.add(tool.name);
+    }
+    for (const sub of this.deps.resolveSubAgents(agentName)) {
+      declared.add(`agent.${sub.name}`);
+    }
+    return declared;
+  }
   async buildLoopConfig(input, options) {
     if (!input && !options?.messages?.length) {
       throw new AgentError(
@@ -1097,7 +1186,13 @@ var Agent = class _Agent {
     const tools = await this.buildToolDefinitions(agentName);
     const { provider, model } = options?.provider !== void 0 ? this.resolveExternalProvider(options.provider, options?.model) : this.resolveModelKey(options?.model, meta);
     const enableTracing = options?.enableTracing ?? this.deps.config?.enableTracing ?? false;
-    const callCtx = { agentName, enableTracing, provider, model };
+    const callCtx = {
+      agentName,
+      enableTracing,
+      provider,
+      model,
+      declaredTools: this.buildDeclaredTools(agentName)
+    };
     return {
       provider,
       systemPrompt: meta.systemPrompt,
@@ -1105,11 +1200,12 @@ var Agent = class _Agent {
       temperature: options?.temperature,
       maxTokens: options?.maxTokens,
       maxTurns: meta.maxTurns ?? this.deps.config?.maxTurns,
+      maxHistoryTokens: this.deps.config?.maxHistoryTokens,
       tools,
       signal: options?.signal,
       messages: options?.messages,
       enableTracing,
-      executeTool: async (name, args) => this.executeTool(name, args, callCtx)
+      executeTool: async (name, args, deltaEmitter) => this.executeTool(name, args, callCtx, deltaEmitter)
     };
   }
   /**
@@ -1265,7 +1361,7 @@ var Agent = class _Agent {
   /**
    * tool 执行路由（由 reactLoop 调用）
    *
-   * - `agent.` 前缀 → {@link executeSubAgent} 递归（含 enableTracing + TracingToolResult 包装）
+   * - `agent.` 前缀 → {@link executeSubAgent} 递归（含 usage/turns 上卷 + tracing 包装）
    * - 常规 tool → `loadToolModule` 加载 handler + 可选 input 校验 → 调用
    *
    * `callCtx` 由 [buildLoopConfig](#buildLoopConfig) 闭包捕获传入——本次调用的有效
@@ -1277,7 +1373,7 @@ var Agent = class _Agent {
    *
    * **tool 未找到 / 加载失败**：抛错，被 reactLoop catch 后同样回传 LLM。
    */
-  async executeTool(rawName, rawArgs, callCtx) {
+  async executeTool(rawName, rawArgs, callCtx, deltaEmitter) {
     const name = rawName;
     let args = rawArgs;
     const guard = this.deps.config?.beforeToolCall?.(name, args, this.deps.ctx);
@@ -1285,20 +1381,13 @@ var Agent = class _Agent {
       if ("error" in guard) return { error: guard.error };
       if ("args" in guard) args = guard.args;
     }
-    const declared = /* @__PURE__ */ new Set();
-    for (const tool2 of this.deps.resolveAgentTools(callCtx.agentName)) {
-      declared.add(tool2.name);
-    }
-    for (const sub of this.deps.resolveSubAgents(callCtx.agentName)) {
-      declared.add(`agent.${sub.name}`);
-    }
-    if (!declared.has(name)) {
+    if (!callCtx.declaredTools.has(name)) {
       return {
         error: `Tool "${name}" is not declared by agent "${callCtx.agentName}" (add it to the agent's tools/agents declaration)`
       };
     }
     if (name.startsWith("agent.")) {
-      return await this.executeSubAgent(name.slice(6), args, callCtx);
+      return await this.executeSubAgent(name.slice(6), args, callCtx, deltaEmitter);
     }
     const tool = this.deps.getTool(name);
     if (!tool) {
@@ -1314,27 +1403,49 @@ var Agent = class _Agent {
       callArgs = result2.value ?? args;
     }
     const mod = await this.deps.loadToolModule(tool.filePath, tool.functionName);
-    const result = await mod.handler(callArgs, this.deps.ctx);
-    this.deps.config?.afterToolCall?.(name, args, result, this.deps.ctx);
+    const toolTimeoutMs = this.deps.config?.toolTimeoutMs;
+    let result;
+    if (toolTimeoutMs && toolTimeoutMs > 0) {
+      result = await Promise.race([
+        mod.handler(callArgs, this.deps.ctx),
+        new Promise((_, reject) => {
+          const timer = setTimeout(
+            () => reject(new AgentToolTimeoutError(name, toolTimeoutMs)),
+            toolTimeoutMs
+          );
+          timer.unref?.();
+        })
+      ]);
+    } else {
+      result = await mod.handler(callArgs, this.deps.ctx);
+    }
+    try {
+      this.deps.config?.afterToolCall?.(name, args, result, this.deps.ctx);
+    } catch (hookErr) {
+      console.error(`[faapi] afterToolCall hook error for tool "${name}":`, hookErr);
+    }
     return result;
   }
   /**
    * 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 形状一致）时直传字符串,其余形状
@@ -1344,7 +1455,7 @@ var Agent = class _Agent {
    * 而非 `getAgent`(返回 AgentCore,无代码加载细节)。DB skill 无文件,
    * `getAgentEntry` 返回 `undefined`,走默认 reactLoop。
    */
-  async executeSubAgent(subName, args, callCtx) {
+  async executeSubAgent(subName, args, callCtx, deltaEmitter) {
     const newDepth = this.depth + 1;
     const maxDepth = this.deps.config?.maxAgentDepth ?? DEFAULT_MAX_AGENT_DEPTH;
     if (newDepth > maxDepth) {
@@ -1361,21 +1472,68 @@ var Agent = class _Agent {
       }
     }
     const subMeta = this.deps.getAgent(subName);
-    const result = await subAgent.run(extractSubAgentUserInput(args), {
+    const subOptions = {
       agent: subName,
       provider: callCtx.provider,
       model: subMeta?.model ?? callCtx.model,
       enableTracing: callCtx.enableTracing
-    });
+    };
+    if (deltaEmitter) {
+      const toolName = `agent.${subName}`;
+      const startedAt = performance.now();
+      const traceEvents = callCtx.enableTracing ? [] : void 0;
+      let done;
+      for await (const chunk of subAgent.stream(extractSubAgentUserInput(args), subOptions)) {
+        if (chunk.subagentDelta) {
+          deltaEmitter.onSubAgentDelta(chunk.subagentDelta);
+        } else if (typeof chunk.deltaContent === "string" && chunk.deltaContent.length > 0 || typeof chunk.deltaReasoning === "string" && chunk.deltaReasoning.length > 0) {
+          deltaEmitter.onSubAgentDelta({
+            name: toolName,
+            depth: newDepth,
+            deltaContent: chunk.deltaContent,
+            deltaReasoning: chunk.deltaReasoning
+          });
+        }
+        if (chunk.traceEvent) {
+          traceEvents.push(chunk.traceEvent);
+        }
+        if (chunk.done) {
+          done = chunk.done;
+        }
+      }
+      this.deps.config?.afterToolCall?.(toolName, args, done?.content, this.deps.ctx);
+      const wrapped2 = {
+        __subAgent: true,
+        result: done?.content ?? "",
+        usage: done?.usage,
+        turns: done?.turns ?? 0
+      };
+      if (traceEvents) {
+        wrapped2.trace = {
+          agentName: "",
+          startedAt,
+          durationMs: performance.now() - startedAt,
+          turns: done?.turns ?? 0,
+          usage: done?.usage,
+          stopReason: done?.stopReason,
+          content: done?.content,
+          events: traceEvents
+        };
+      }
+      return wrapped2;
+    }
+    const result = await subAgent.run(extractSubAgentUserInput(args), subOptions);
     this.deps.config?.afterToolCall?.(`agent.${subName}`, args, result.content, this.deps.ctx);
+    const wrapped = {
+      __subAgent: true,
+      result: result.content,
+      usage: result.usage,
+      turns: result.turns
+    };
     if (callCtx.enableTracing && result.trace) {
-      return {
-        __trace: true,
-        result: result.content,
-        trace: result.trace
-      };
+      wrapped.trace = result.trace;
     }
-    return result.content;
+    return wrapped;
   }
 };
 
@@ -1494,12 +1652,14 @@ export {
   AgentAbortError,
   AgentError,
   AgentRecursionError,
+  AgentToolTimeoutError,
   LLMProviderError,
   ReactLoopError,
   createOpenAIProvider,
   createProvider,
   createToolSchemaResolver,
   plugin_default as default,
+  isSubAgentToolResult,
   isTracingToolResult,
   reactLoop,
   reactLoopStream