@faapi/agent 4.2.1 → 4.4.0

package/dist/index.js

@@ -419,9 +419,12 @@ function finalizeStreamChunk(accumulators, finishReason, usage) {
 
 // src/provider.ts
 var AgentAbortError = class extends Error {
-  constructor(message = "Agent execution aborted") {
+  /** 中断时刻的部分对话历史（完整轮组快照，可直接用于续跑） */
+  messages;
+  constructor(message = "Agent execution aborted", messages = []) {
     super(message);
     this.name = "AgentAbortError";
+    this.messages = messages;
   }
 };
 function createProvider(config) {
@@ -442,10 +445,13 @@ function isTracingToolResult(value) {
 var ReactLoopError = class extends Error {
   /** 配置的 maxTurns 值 */
   maxTurns;
-  constructor(message, maxTurns) {
+  /** 超限时的完整对话历史（业务方可提高 maxTurns 后经 `config.messages` 续跑，轮数重新计数） */
+  messages;
+  constructor(message, maxTurns, messages = []) {
     super(message);
     this.name = "ReactLoopError";
     this.maxTurns = maxTurns;
+    this.messages = messages;
   }
 };
 var DEFAULT_MAX_TURNS = 10;
@@ -474,6 +480,19 @@ function buildInitialMessages(input, systemPrompt) {
   messages.push({ role: "user", content: input });
   return messages;
 }
+function initLoopMessages(input, config) {
+  if (config.messages?.length) {
+    const messages = [...config.messages];
+    if (config.systemPrompt && !messages.some((m) => m.role === "system")) {
+      messages.unshift({ role: "system", content: config.systemPrompt });
+    }
+    if (input) {
+      messages.push({ role: "user", content: input });
+    }
+    return messages;
+  }
+  return buildInitialMessages(input ?? "", config.systemPrompt);
+}
 function estimateTokens(chars) {
   return Math.ceil(chars / 2);
 }
@@ -532,7 +551,7 @@ function extractSubAgentName(toolName) {
 }
 async function reactLoop(input, config) {
   const enableTracing = config.enableTracing ?? false;
-  const messages = buildInitialMessages(input, config.systemPrompt);
+  const messages = initLoopMessages(input, config);
   const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
   const extras = buildRequestExtras(config);
   let totalUsage;
@@ -541,17 +560,25 @@ async function reactLoop(input, config) {
   const traceEvents = enableTracing ? [] : void 0;
   while (turns < maxTurns) {
     if (config.signal?.aborted) {
-      throw new AgentAbortError();
+      throw new AgentAbortError(void 0, messages);
     }
     turns++;
     const llmStartedAt = enableTracing ? nowMs() : 0;
     const outgoing = config.maxHistoryTokens ? trimHistory(messages, config.maxHistoryTokens) : messages;
     const inputSnapshot = enableTracing ? [...outgoing] : void 0;
-    const response = await config.provider.complete({
-      messages: [...outgoing],
-      ...extras,
-      signal: config.signal
-    });
+    let response;
+    try {
+      response = await config.provider.complete({
+        messages: [...outgoing],
+        ...extras,
+        signal: config.signal
+      });
+    } catch (err) {
+      if (err instanceof AgentAbortError) {
+        throw new AgentAbortError(err.message, messages);
+      }
+      throw err;
+    }
     if (response.usage) {
       totalUsage = accumulateUsage(totalUsage, response.usage);
     }
@@ -667,19 +694,20 @@ async function reactLoop(input, config) {
   }
   throw new ReactLoopError(
     `Max turns (${maxTurns}) exceeded \u2014 agent did not converge to a final answer`,
-    maxTurns
+    maxTurns,
+    messages
   );
 }
 async function* reactLoopStream(input, config) {
   const enableTracing = config.enableTracing ?? false;
-  const messages = buildInitialMessages(input, config.systemPrompt);
+  const messages = initLoopMessages(input, config);
   const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
   const extras = buildRequestExtras(config);
   let totalUsage;
   let turns = 0;
   while (turns < maxTurns) {
     if (config.signal?.aborted) {
-      throw new AgentAbortError();
+      throw new AgentAbortError(void 0, messages);
     }
     turns++;
     const llmStartedAt = enableTracing ? nowMs() : 0;
@@ -689,25 +717,32 @@ async function* reactLoopStream(input, config) {
     let toolCalls;
     let finishReason;
     let turnUsage;
-    for await (const chunk of config.provider.stream({
-      messages: [...outgoing],
-      ...extras,
-      signal: config.signal
-    })) {
-      if (typeof chunk.deltaContent === "string" && chunk.deltaContent.length > 0) {
-        turnContent += chunk.deltaContent;
-        yield { deltaContent: chunk.deltaContent };
-      }
-      if (chunk.toolCalls && chunk.toolCalls.length > 0) {
-        toolCalls = chunk.toolCalls;
-      }
-      if (chunk.finishReason) {
-        finishReason = chunk.finishReason;
+    try {
+      for await (const chunk of config.provider.stream({
+        messages: [...outgoing],
+        ...extras,
+        signal: config.signal
+      })) {
+        if (typeof chunk.deltaContent === "string" && chunk.deltaContent.length > 0) {
+          turnContent += chunk.deltaContent;
+          yield { deltaContent: chunk.deltaContent };
+        }
+        if (chunk.toolCalls && chunk.toolCalls.length > 0) {
+          toolCalls = chunk.toolCalls;
+        }
+        if (chunk.finishReason) {
+          finishReason = chunk.finishReason;
+        }
+        if (chunk.usage) {
+          totalUsage = accumulateUsage(totalUsage, chunk.usage);
+          turnUsage = chunk.usage;
+        }
       }
-      if (chunk.usage) {
-        totalUsage = accumulateUsage(totalUsage, chunk.usage);
-        turnUsage = chunk.usage;
+    } catch (err) {
+      if (err instanceof AgentAbortError) {
+        throw new AgentAbortError(err.message, messages);
       }
+      throw err;
     }
     const assistantMessage = {
       role: "assistant",
@@ -806,12 +841,49 @@ async function* reactLoopStream(input, config) {
   }
   throw new ReactLoopError(
     `Max turns (${maxTurns}) exceeded \u2014 agent did not converge to a final answer`,
-    maxTurns
+    maxTurns,
+    messages
   );
 }
 
 // src/agent.ts
 var DEFAULT_MAX_AGENT_DEPTH = 3;
+var VALID_MESSAGE_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool"]);
+function isProviderInstance(value) {
+  return typeof value === "object" && value !== null && typeof value.complete === "function" && typeof value.stream === "function";
+}
+function isProviderConfig(value) {
+  return typeof value === "object" && value !== null && typeof value.provider === "string";
+}
+function materializeProvider(external) {
+  if (isProviderInstance(external)) return external;
+  if (isProviderConfig(external)) {
+    return createProvider({ ...external, models: external.models ?? {} });
+  }
+  throw new AgentError(
+    'options.provider must be an LlmConfig object (with a string "provider" field) or an LLMProvider instance (with complete/stream methods)'
+  );
+}
+function validateResumeHistory(messages) {
+  messages.forEach((message, index) => {
+    if (!VALID_MESSAGE_ROLES.has(message.role)) {
+      throw new AgentError(
+        `Invalid resume history at messages[${index}]: unknown role "${String(message.role)}"`
+      );
+    }
+    if (message.role === "assistant" && message.toolCalls?.length) {
+      const missing = new Set(message.toolCalls.map((call) => call.id));
+      for (let j = index + 1; j < messages.length && messages[j].role === "tool"; j++) {
+        missing.delete(messages[j].toolCallId ?? "");
+      }
+      if (missing.size > 0) {
+        throw new AgentError(
+          `Invalid resume history at messages[${index}]: assistant tool call(s) [${Array.from(missing).join(", ")}] have no matching tool result (history truncated mid-turn \u2014 persist the full turn group from AgentAbortError.messages / ReactLoopError.messages)`
+        );
+      }
+    }
+  });
+}
 var AgentError = class extends Error {
   constructor(message) {
     super(message);
@@ -860,16 +932,19 @@ var Agent = class _Agent {
    * reactLoop 不知 agent 名（只关心循环逻辑）,返回的 `result.trace.agentName` 为空字符串。
    * 本方法在 reactLoop 返回后填充 `this.deps.agentName`,让顶层 trace 标识"是哪个 agent 跑的"。
    *
-   * @param input 用户输入
-   * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens / enableTracing
+   * @param input 用户输入（可选——续跑场景不传新输入；input 与 `options.messages`
+   *              都为空时抛 `AgentError`）
+   * @param options 临时覆盖本次调用的 provider（外部 provider）/ model（字符串 key）/
+   *                temperature / maxTokens / messages / enableTracing
    *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
    * @returns 最终结果（content + messages + turns + stopReason + usage + trace?）
-   * @throws {AgentError} agent 未注册
-   * @throws {ReactLoopError} 超出 maxTurns
+   * @throws {AgentError} agent 未注册；input 与 messages 都为空；续跑历史结构非法
+   * @throws {ReactLoopError} 超出 maxTurns（`error.messages` 携带完整历史，可续跑）
+   * @throws {AgentAbortError} 中断（`error.messages` 携带断点历史，可续跑）
    * @throws {Error} provider.complete 抛错时立即传播
    */
   async run(input, options) {
-    const config = await this.buildLoopConfig(options);
+    const config = await this.buildLoopConfig(input, options);
     const result = await reactLoop(input, config);
     if (result.trace) {
       result.trace.agentName = options?.agent ?? this.deps.agentName;
@@ -879,16 +954,19 @@ var Agent = class _Agent {
   /**
    * 流式执行——组装 config 调 [reactLoopStream](./reactLoop.md)
    *
-   * @param input 用户输入
-   * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
+   * @param input 用户输入（可选——续跑场景不传新输入；input 与 `options.messages`
+   *              都为空时抛 `AgentError`）
+   * @param options 临时覆盖本次调用的 provider（外部 provider）/ model（字符串 key）/
+   *                temperature / maxTokens / messages
    *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
    * @yields 流式 chunk（deltaContent / toolCall / toolResult / done）
-   * @throws {AgentError} agent 未注册
-   * @throws {ReactLoopError} 超出 maxTurns
+   * @throws {AgentError} agent 未注册；input 与 messages 都为空；续跑历史结构非法
+   * @throws {ReactLoopError} 超出 maxTurns（`error.messages` 携带完整历史，可续跑）
+   * @throws {AgentAbortError} 中断（`error.messages` 携带断点历史，可续跑）
    * @throws {Error} provider.stream 抛错时立即传播
    */
   async *stream(input, options) {
-    const config = await this.buildLoopConfig(options);
+    const config = await this.buildLoopConfig(input, options);
     yield* reactLoopStream(input, config);
   }
   /**
@@ -938,7 +1016,9 @@ var Agent = class _Agent {
    * 3. buildToolDefinitions 组装 tool 列表（用有效 agent 名查 tools / sub-agents）
    * 4. config 字段优先级（高 → 低）：`options` > agent 元数据 > 全局 AgentRuntimeConfig / deps.defaultProvider
    *
-   * `options.model` 是字符串 key,由 {@link resolveModelKey} 解析为 provider + model
+   * `options.provider`（外部 provider）存在时由 {@link resolveExternalProvider} 物化,
+   * 优先级最高——`options.model` 变为原始 model 名原样透传（不解析 llms key）。
+   * 否则 `options.model` 是字符串 key,由 {@link resolveModelKey} 解析为 provider + model
    * （支持 llms key 精确匹配 / `provider/model` 一体化 / 纯 model 名模糊匹配）。
    * 不传 `options.model` 时用 `deps.defaultProvider` + agent 元数据 `config.model`。
    * 详见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」。
@@ -946,15 +1026,28 @@ var Agent = class _Agent {
    * `options.agent` 覆盖本次调用的 agent 名——不传时用 `deps.agentName`（来自
    * `config.agent.defaultAgent`）。`defaultAgent` 未设且 `options.agent` 未传时抛
    * `AgentError`。
+   *
+   * **输入守卫**（续跑入口,见 [reactLoop.md](./reactLoop.md) 中断恢复章节）：
+   * `input` 与 `options.messages` 都为空时抛 `AgentError`（不发送空请求）；
+   * `options.messages` 提供时先经 `validateResumeHistory` 结构校验,非法抛
+   * `AgentError`,不发起 LLM 请求。
    */
-  async buildLoopConfig(options) {
+  async buildLoopConfig(input, options) {
+    if (!input && !options?.messages?.length) {
+      throw new AgentError(
+        "agent.run/stream requires non-empty input, or options.messages to resume from (AgentAbortError.messages / ReactLoopError.messages / previous result.messages)"
+      );
+    }
+    if (options?.messages?.length) {
+      validateResumeHistory(options.messages);
+    }
     const agentName = options?.agent ?? this.deps.agentName;
     const meta = this.deps.getAgent(agentName);
     if (!meta) {
       throw new AgentError(`Agent "${agentName}" is not registered`);
     }
     const tools = await this.buildToolDefinitions(agentName);
-    const { provider, model } = this.resolveModelKey(options?.model, meta);
+    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;
     return {
       provider,
@@ -965,15 +1058,45 @@ var Agent = class _Agent {
       maxTurns: meta.maxTurns ?? this.deps.config?.maxTurns,
       tools,
       signal: options?.signal,
+      messages: options?.messages,
       enableTracing,
       executeTool: async (name, args) => this.executeTool(name, args, enableTracing)
     };
   }
+  /**
+   * 解析外部 provider（`options.provider`）→ provider + model
+   *
+   * 规则见 [agentHandle.md](./agentHandle.md) 的「`options.provider` 外部 provider」章节：
+   * - `LLMProvider` 实例 → 直接使用,`modelKey` 原样透传（可为 `undefined`,自定义 provider 自决）
+   * - `LlmConfig` 配置对象 → `createProvider` 现场创建,`modelKey` 原样透传；
+   *   缺省回落该 config `models` 第一个 key,两者皆无抛 `AgentError`（早失败,不发请求）
+   * - `modelKey` 不做 llms key 解析、不拆 `/`（支持 OpenRouter 等带斜杠的 model id）
+   *
+   * 仅本次调用生效：不进 providers Map、sub-agent 递归不继承（executeSubAgent 构造
+   * subDeps 时不携带 options,sub-agent 走默认解析链路）。
+   *
+   * @throws {AgentError} provider 形式非法；LlmConfig 形式下 model 缺失
+   */
+  resolveExternalProvider(external, modelKey) {
+    const provider = materializeProvider(external);
+    if (isProviderInstance(external)) {
+      return { provider, model: modelKey };
+    }
+    const firstModel = Object.keys(external.models ?? {})[0];
+    const model = modelKey ?? firstModel;
+    if (model === void 0) {
+      throw new AgentError(
+        "External provider requires a model: pass options.model or declare models in the provider config"
+      );
+    }
+    return { provider, model };
+  }
   /**
    * 解析 `options.model` 字符串 key → provider + model
    *
    * 规则见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」：
-   * 1. `undefined` → `deps.defaultProvider` + `meta.model`
+   * 1. `undefined` → `deps.defaultProvider`（未配置时抛 `AgentError`——外部 provider 模式
+   *    要求调用方传 `options.provider`）+ `meta.model`
    * 2. 精确匹配 `deps.providers` 的 key → 该 provider + 其 `models` 第一个 key
    * 3. 含 `/` → `provider/model` 形式,`deps.providers.get(provider)` + 该 model
    *    （要求该 model 在 `deps.llms[provider].models` 里）
@@ -982,10 +1105,16 @@ var Agent = class _Agent {
    *    - 多个 → 抛 `AgentError`（要求用 `provider/model` 消歧）
    *    - 无 → 抛 `AgentError`
    *
-   * @throws {AgentError} key 解析失败（provider/model 不存在或歧义）
+   * @throws {AgentError} key 解析失败（provider/model 不存在或歧义）；deps.defaultProvider
+   *   未配置（外部 provider 模式下调用方未传 options.provider）
    */
   resolveModelKey(key, meta) {
     if (key === void 0) {
+      if (!this.deps.defaultProvider) {
+        throw new AgentError(
+          "No default LLM provider: configure config.agent.llms, or pass options.provider (external provider) on this call"
+        );
+      }
       return { provider: this.deps.defaultProvider, model: meta.model };
     }
     const byProviderKey = this.deps.providers.get(key);
@@ -1000,7 +1129,9 @@ var Agent = class _Agent {
       const modelName = key.slice(slashIdx + 1);
       const provider = this.deps.providers.get(providerName);
       if (!provider) {
-        throw new AgentError(`Unknown provider "${providerName}" in model key "${key}"`);
+        throw new AgentError(
+          `Unknown provider "${providerName}" in model key "${key}". Declare it in config.agent.llms, or pass options.provider to use an external provider.`
+        );
       }
       const llmConfig = this.deps.llms[providerName];
       if (!llmConfig || !llmConfig.models[modelName]) {
@@ -1026,7 +1157,7 @@ var Agent = class _Agent {
       );
     }
     throw new AgentError(
-      `Model "${key}" not found in any provider. Declare it in config.agent.llms.*.models.`
+      `Model "${key}" not found in any provider. Declare it in config.agent.llms.*.models, or pass options.provider to use an external provider.`
     );
   }
   /**
@@ -1210,14 +1341,13 @@ var agentPlugin = {
   setup(ctx) {
     const registries = ctx.registries;
     const agentConfig = readAgentConfig(ctx);
-    if (!agentConfig?.llms) {
-      console.warn(
-        "! @faapi/agent: config.agent.llms not configured, agent parameter injection disabled"
+    const llms = agentConfig?.llms ?? {};
+    if (Object.keys(llms).length === 0) {
+      console.log(
+        "- @faapi/agent: no llms configured \u2014 use agent.run(input, { provider }) to pass an external provider per call"
       );
-      return;
     }
-    const defaultAgent = agentConfig.defaultAgent ?? "";
-    const llms = agentConfig.llms;
+    const defaultAgent = agentConfig?.defaultAgent ?? "";
     const providers = /* @__PURE__ */ new Map();
     for (const [name, llmConfig] of Object.entries(llms)) {
       if (!llmConfig.apiKey || llmConfig.apiKey.trim() === "") {
@@ -1227,22 +1357,21 @@ var agentPlugin = {
       }
       providers.set(name, createProvider(llmConfig));
     }
-    const defaultLlm = agentConfig.defaultLlm ?? Object.keys(llms)[0];
-    const defaultProvider = providers.get(defaultLlm);
-    if (!defaultProvider) {
+    const defaultLlm = agentConfig?.defaultLlm ?? Object.keys(llms)[0];
+    const defaultProvider = defaultLlm !== void 0 ? providers.get(defaultLlm) : void 0;
+    if (defaultLlm !== void 0 && !defaultProvider) {
       console.warn(
-        `! @faapi/agent: config.agent.defaultLlm "${defaultLlm}" not found in llms, agent parameter injection disabled`
+        `! @faapi/agent: config.agent.defaultLlm "${defaultLlm}" not found in llms \u2014 no default provider, use agent.run(input, { provider }) to pass an external provider per call`
       );
-      return;
     }
     const runtimeConfig = {
-      maxTurns: agentConfig.maxTurns,
-      maxAgentDepth: agentConfig.maxAgentDepth,
-      maxHistoryTokens: agentConfig.maxHistoryTokens,
+      maxTurns: agentConfig?.maxTurns,
+      maxAgentDepth: agentConfig?.maxAgentDepth,
+      maxHistoryTokens: agentConfig?.maxHistoryTokens,
       // 鉴权钩子（authHooks,见 ./authHooks.md）——业务方在 config.agent 声明
-      beforeToolCall: agentConfig.beforeToolCall,
-      afterToolCall: agentConfig.afterToolCall,
-      filterTools: agentConfig.filterTools
+      beforeToolCall: agentConfig?.beforeToolCall,
+      afterToolCall: agentConfig?.afterToolCall,
+      filterTools: agentConfig?.filterTools
     };
     const rootDir = ctx.rootDir;
     const schemaCache = /* @__PURE__ */ new Map();
@@ -1289,7 +1418,7 @@ var agentPlugin = {
       });
     });
     console.log(
-      defaultAgent ? `- @faapi/agent: default agent "${defaultAgent}" (provider: ${defaultLlm}) available via agent parameter injection` : `- @faapi/agent: no defaultAgent set \u2014 use agent.run(input, { agent: 'name' }) to specify agent (provider: ${defaultLlm})`
+      defaultProvider ? defaultAgent ? `- @faapi/agent: default agent "${defaultAgent}" (provider: ${defaultLlm}) available via agent parameter injection` : `- @faapi/agent: no defaultAgent set \u2014 use agent.run(input, { agent: 'name' }) to specify agent (provider: ${defaultLlm})` : "- @faapi/agent: no default provider \u2014 use agent.run(input, { provider }) to pass an external provider per call"
     );
   }
 };