@faapi/agent 4.2.1 → 4.4.0

package/dist/index.d.ts

@@ -114,9 +114,16 @@ interface LLMCompleteRequest {
  * 外部 `AbortSignal` 触发时抛出（请求前预检查或请求中断）。
  * 业务方通过 `instanceof AgentAbortError` 区分「用户取消」与真实错误——
  * 取消不是故障，不应触发告警/重试逻辑。
+ *
+ * `messages` 为中断时刻的部分对话历史（截至最后一个完整轮组），由
+ * [reactLoop](./reactLoop.md) 在循环边界附加（provider 层不感知历史，恒为空数组）。
+ * 业务方持久化后经 `config.messages` / `AgentRunOptions.messages` 从断点续跑，
+ * 语义详见 [reactLoop.md](./reactLoop.md) 中断恢复章节。
  */
 declare class AgentAbortError extends Error {
-    constructor(message?: string);
+    /** 中断时刻的部分对话历史（完整轮组快照，可直接用于续跑） */
+    readonly messages: LLMMessage[];
+    constructor(message?: string, messages?: LLMMessage[]);
 }
 /**
  * LLM 响应的停止原因
@@ -375,6 +382,16 @@ interface ReactLoopConfig {
      * 消息副本，本地 `messages` 与 trace 不受影响。详见 reactLoop.md 的历史裁剪章节。
      */
     maxHistoryTokens?: number;
+    /**
+     * 初始对话历史（续跑 / 多轮对话）
+     *
+     * 提供时以其为基础（历史应含 system）：历史无 `system` 消息且配置了
+     * `systemPrompt` 时自动在最前插入（agent 人格不因续跑丢失）；`input` 非空时
+     * 追加为新的 `user` 消息（多轮对话），为空时纯续跑。历史经 `Agent` 层结构校验
+     * （assistant.toolCalls 与 tool 结果按 toolCallId 配对完整）。
+     * 续跑源见 [reactLoop.md](./reactLoop.md) 中断恢复章节。
+     */
+    messages?: LLMMessage[];
     /**
      * 启用 tracing（默认 true）。开启时填充 `ReactLoopResult.trace` /
      * `ReactLoopStreamChunk.traceEvent`,详见 [trace.md](./trace.md)。
@@ -447,32 +464,36 @@ interface ReactLoopStreamChunk {
 declare class ReactLoopError extends Error {
     /** 配置的 maxTurns 值 */
     readonly maxTurns: number;
-    constructor(message: string, maxTurns: number);
+    /** 超限时的完整对话历史（业务方可提高 maxTurns 后经 `config.messages` 续跑，轮数重新计数） */
+    readonly messages: LLMMessage[];
+    constructor(message: string, maxTurns: number, messages?: LLMMessage[]);
 }
 /**
  * 执行 ReAct 循环（非流式）
  *
  * 反复调 `provider.complete()` → 执行 tool → 回传结果，直到 LLM 返回 `stop`（或其他非 `tool_calls` 原因）或超出 `maxTurns`。
  *
- * @param input 用户输入
+ * @param input 用户输入（续跑场景可为空，历史经 `config.messages` 提供）
  * @param config 循环配置
  * @returns 最终结果（content + messages + turns + stopReason + usage）
- * @throws {ReactLoopError} 超出 maxTurns
+ * @throws {ReactLoopError} 超出 maxTurns（`error.messages` 携带完整历史，可续跑）
+ * @throws {AgentAbortError} 中断（`error.messages` 携带断点历史，可续跑）
  * @throws {Error} provider.complete 抛错时立即传播
  */
-declare function reactLoop(input: string, config: ReactLoopConfig): Promise<ReactLoopResult>;
+declare function reactLoop(input: string | undefined, config: ReactLoopConfig): Promise<ReactLoopResult>;
 /**
  * 执行 ReAct 循环（流式）
  *
  * 使用 `provider.stream()` 异步迭代 chunks，yield `deltaContent` + `toolCall` + `toolResult` + `done`。
  *
- * @param input 用户输入
+ * @param input 用户输入（续跑场景可为空，历史经 `config.messages` 提供）
  * @param config 循环配置
  * @yields {ReactLoopStreamChunk} 流式 chunk
- * @throws {ReactLoopError} 超出 maxTurns
+ * @throws {ReactLoopError} 超出 maxTurns（`error.messages` 携带完整历史，可续跑）
+ * @throws {AgentAbortError} 中断（`error.messages` 携带断点历史，可续跑）
  * @throws {Error} provider.stream 抛错时立即传播
  */
-declare function reactLoopStream(input: string, config: ReactLoopConfig): AsyncIterable<ReactLoopStreamChunk>;
+declare function reactLoopStream(input: string | undefined, config: ReactLoopConfig): AsyncIterable<ReactLoopStreamChunk>;
 
 /**
  * agent handle——注入到 handler 的 `agent` 参数,提供可调用的 agent 运行入口
@@ -494,8 +515,9 @@ declare function reactLoopStream(input: string, config: ReactLoopConfig): AsyncI
  * }
  * ```
  *
- * 工厂未注册（`@faapi/agent` 插件未加载或 `config.agent.llm` / `defaultAgent` 未配置）
- * 时注入 `undefined`,handler 需自行处理。
+ * 仅在 `@faapi/agent` 插件未加载时注入 `undefined`,handler 需自行处理。
+ * `config.agent.llms` 未配置时工厂照常注册（外部 provider 模式）——
+ * `agent.run/stream` 需调用方传 `options.provider` 才能调用 LLM。
  *
  * 详见 [agentHandle.md](./agentHandle.md)。
  */
@@ -549,8 +571,29 @@ interface AgentRunOptions {
      * 切换 provider + model 的字符串 key（支持 llms key / `provider/model` / 纯 model 名）
      *
      * 不传时用 `defaultLlm` provider + agent 元数据 `config.model`。
+     * `provider` 字段存在时本字段变为「原始 model 名」原样透传给外部 provider
+     * （不做 llms key 解析,支持带 / 的 model id），详见 {@link AgentRunOptions.provider}。
      */
     model?: string;
+    /**
+     * 外部 provider（本次调用临时使用,优先级最高——完全不查 `config.agent.llms`）
+     *
+     * 两种形式（运行时按形状判别,两者皆非抛 `AgentError`）：
+     * - `LlmConfig` 对象（含字符串 `provider` 字段）→ 现场调 `createProvider` 创建适配器
+     *   （浅拷贝 + `models` 兜底 `{}`,不改调用方对象）,适用于 BYOK（用户自带 apiKey）/
+     *   按请求指定 baseURL 网关
+     * - `LLMProvider` 实例（有 `complete` / `stream` 方法）→ 直接使用,适用于框架未内置
+     *   适配器的 LLM 服务（内部自研模型网关等）
+     *
+     * 传入时 `options.model` 语义变为「原始 model 名」——不做 llms key 解析、不拆 `/`,
+     * 原样透传给该 provider（支持 OpenRouter 等带 `/` 的 model id）。
+     * LlmConfig 形式下 `options.model` 缺省时回落该 config 的 `models` 第一个 key,
+     * 两者皆无抛 `AgentError`；LLMProvider 实例形式下可为 `undefined`（自定义 provider 自决）。
+     *
+     * 仅影响本次调用——不进 providers Map、不修改 agent 状态,**sub-agent 递归不继承**
+     * （sub-agent 仍走默认解析链路）,下一次调用仍用默认配置。
+     */
+    provider?: LlmConfig | LLMProvider;
     /** 采样温度（透传给 LLM API,覆盖 provider/model 级 temperature） */
     temperature?: number;
     /** 最大生成 token 数（透传给 LLM API） */
@@ -563,6 +606,20 @@ interface AgentRunOptions {
      * 结构化调用明细,详见 [trace.md](./trace.md)。
      */
     enableTracing?: boolean;
+    /**
+     * 初始对话历史（续跑 / 多轮对话）
+     *
+     * 提供时以其为基础,agent 的 systemPrompt 缺失时自动补齐；`input` 非空时追加为
+     * 新的 user 消息（多轮对话）,为空时纯续跑。续跑源：
+     * - `AgentAbortError.messages` —— 中断断点（客户端断开 / 请求取消）
+     * - `ReactLoopError.messages` —— maxTurns 超限（提高预算后续跑）
+     * - 上次 `result.messages` —— 多轮对话拼接
+     *
+     * 历史经结构校验（assistant.toolCalls 与 tool 结果按 toolCallId 配对完整、
+     * role 合法）,非法抛 `AgentError`,不发起 LLM 请求。
+     * 语义详见 [reactLoop.md](./reactLoop.md) 中断恢复章节。
+     */
+    messages?: LLMMessage[];
 }
 interface AgentHandle {
     /**
@@ -571,30 +628,34 @@ interface AgentHandle {
      * 组装 ReAct 循环 config（systemPrompt + tools + maxTurns + 应用 `options` 覆盖）→ 调
      * [reactLoop](./reactLoop.md) → 返回最终结果。
      *
-     * @param input 用户输入文本
-     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
-     *                （不修改 agent 自身状态,详见 {@link AgentRunOptions}）
+     * @param input 用户输入文本（可选——续跑场景不传新输入；input 与
+     *              `options.messages` 都为空时抛 `AgentError`）
+     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens /
+     *                messages（不修改 agent 自身状态,详见 {@link AgentRunOptions}）
      * @returns 循环结果（content + messages + turns + stopReason + usage）
-     * @throws {AgentError} agent 未注册
-     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {AgentError} agent 未注册；input 与 messages 都为空；续跑历史结构非法
+     * @throws {ReactLoopError} 超出 maxTurns（`error.messages` 可续跑）
+     * @throws {AgentAbortError} 中断（`error.messages` 为断点历史,可续跑）
      * @throws {Error} LLM provider 抛错时立即传播
      */
-    run(input: string, options?: AgentRunOptions): Promise<ReactLoopResult>;
+    run(input?: string, options?: AgentRunOptions): Promise<ReactLoopResult>;
     /**
      * 流式执行 agent
      *
      * 组装 config（应用 `options` 覆盖）→ 调 [reactLoopStream](./reactLoop.md) → yield 流式 chunk。
      * 适用于 LLM token 流式输出、tool 调用过程展示等场景。
      *
-     * @param input 用户输入文本
-     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
-     *                （不修改 agent 自身状态,详见 {@link AgentRunOptions}）
+     * @param input 用户输入文本（可选——续跑场景不传新输入；input 与
+     *              `options.messages` 都为空时抛 `AgentError`）
+     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens /
+     *                messages（不修改 agent 自身状态,详见 {@link AgentRunOptions}）
      * @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} LLM provider 抛错时立即传播
      */
-    stream(input: string, options?: AgentRunOptions): AsyncIterable<ReactLoopStreamChunk>;
+    stream(input?: string, options?: AgentRunOptions): AsyncIterable<ReactLoopStreamChunk>;
     /**
      * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
      *
@@ -696,14 +757,19 @@ interface ToolSchemaResolution {
  * 访问器签名与 faapi 核心对称（见 [agent.md](./agent.md) 依赖注入章节）。
  */
 interface AgentDeps {
-    /** LLM provider 实例映射（key 是 provider 名，来自 config.agent.llms） */
+    /** LLM provider 实例映射（key 是 provider 名，来自 config.agent.llms；未配置时为空 Map） */
     providers: Map<string, LLMProvider>;
-    /** 默认 provider 实例（config.agent.defaultLlm 对应，或 llms 第一个 key） */
-    defaultProvider: LLMProvider;
-    /** LLM provider 配置映射（含 models，用于 options.model key 解析） */
+    /**
+     * 默认 provider 实例（config.agent.defaultLlm 对应，或 llms 第一个 key）
+     *
+     * 可选——config.agent.llms 未配置时为 undefined（外部 provider 模式），
+     * 此时 run/stream 必须传 options.provider，否则 resolveModelKey 抛 AgentError。
+     */
+    defaultProvider?: LLMProvider;
+    /** LLM provider 配置映射（含 models，用于 options.model key 解析；llms 未配置时为空对象） */
     llms: Record<string, LlmConfig>;
-    /** 默认 provider key（config.agent.defaultLlm，或 llms 第一个 key） */
-    defaultLlm: string;
+    /** 默认 provider key（config.agent.defaultLlm，或 llms 第一个 key；llms 未配置时为 undefined） */
+    defaultLlm?: string;
     /** 当前 agent 名 */
     agentName: string;
     /** 项目根目录（Phase 3.5 接线时用于加载器） */
@@ -786,27 +852,33 @@ declare 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 抛错时立即传播
      */
-    run(input: string, options?: AgentRunOptions): Promise<ReactLoopResult>;
+    run(input?: string, options?: AgentRunOptions): Promise<ReactLoopResult>;
     /**
      * 流式执行——组装 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 抛错时立即传播
      */
-    stream(input: string, options?: AgentRunOptions): AsyncIterable<ReactLoopStreamChunk>;
+    stream(input?: string, options?: AgentRunOptions): AsyncIterable<ReactLoopStreamChunk>;
     /**
      * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
      *
@@ -835,7 +907,9 @@ declare 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 解析规则」。
@@ -843,13 +917,34 @@ declare 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 请求。
      */
     private buildLoopConfig;
+    /**
+     * 解析外部 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 缺失
+     */
+    private resolveExternalProvider;
     /**
      * 解析 `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` 里）
@@ -858,7 +953,8 @@ declare class Agent {
      *    - 多个 → 抛 `AgentError`（要求用 `provider/model` 消歧）
      *    - 无 → 抛 `AgentError`
      *
-     * @throws {AgentError} key 解析失败（provider/model 不存在或歧义）
+     * @throws {AgentError} key 解析失败（provider/model 不存在或歧义）；deps.defaultProvider
+     *   未配置（外部 provider 模式下调用方未传 options.provider）
      */
     private resolveModelKey;
     /**
@@ -942,16 +1038,17 @@ declare class Agent {
  * ```
  *
  * 插件 setup 时：
- * 1. 遍历 `config.agent.llms` → 每项调 `createProvider` → `Map<providerKey, LLMProvider>`
- * 2. 读 `config.agent.defaultLlm` → `defaultProvider`（未设时用 `llms` 第一个 key）
+ * 1. 遍历 `config.agent.llms`（可选）→ 每项调 `createProvider` → `Map<providerKey, LLMProvider>`
+ * 2. 读 `config.agent.defaultLlm` → `defaultProvider`（未设时用 `llms` 第一个 key;
+ *    `llms` 未配置/未命中时为 `undefined`——外部 provider 模式,照常注册工厂）
  * 3. 读 `config.agent.defaultAgent`（可选） / `maxTurns` / `maxAgentDepth`
  * 4. 从 `@faapi/faapi` import 注册表/加载器访问器（getAgent / getTool / resolveAgentTools /
  *    resolveSubAgents / loadAgentModule / loadToolModule）
  * 5. `registerAgentHandleFactory` 注册工厂——每次请求时构造 [Agent](./agent.md) 实例注入到
  *    handler 的 `agent` 参数
  *
- * 配置缺失时（`agent.llms` 未设置）跳过工厂注册并打印警告,
- * handler 的 `agent` 参数注入 `undefined`。
+ * `agent.llms` 可选——未配置时工厂照常注册（外部 provider 模式）,`agent.run/stream`
+ * 需调用方传 `options.provider` 才能调用 LLM。只有插件未加载时 `agent` 参数才注入 `undefined`。
  *
  * `defaultAgent` 可选——未设时 handler 需通过 `agent.run(input, { agent: 'name' })`
  * 显式指定 agent 名。