@faapi/agent 6.30.0 → 6.32.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { LlmConfig, AgentToolDescriptor, FaapiContext, AgentCore, AgentMetadata, ToolMetadata, ToolModule, FaapiPlugin } from '@faapi/faapi';
+import { LlmConfig, LlmComplete, AgentToolDescriptor, FaapiContext, AgentCore, AgentMetadata, ToolMetadata, ToolModule, FaapiPlugin } from '@faapi/faapi';
+export { LlmComplete, LlmCompleteOptions } from '@faapi/faapi';
 
 /**
  * LLM Provider 错误
@@ -11,12 +12,31 @@ declare class LLMProviderError extends Error {
     readonly status?: number;
     /** 响应体摘要（前 500 字符,便于诊断） */
     readonly body?: string;
+    /**
+     * 实际发起的 HTTP 尝试次数（≥1，含失败尝试）
+     *
+     * 重试耗尽抛出时由重试循环回填（构造时未知，故非 readonly）；
+     * 首次尝试即失败的确定性错误（4xx 直抛）为 1，未回填时视为 1。
+     */
+    attempts?: number;
     constructor(message: string, options?: {
         status?: number;
         body?: string;
         cause?: unknown;
     });
 }
+/**
+ * LLM 请求超时
+ *
+ * {@link LLMProviderError} 的超时子类——`instanceof LLMTimeoutError` 可编程区分
+ * 「超时」与「网络错误」（两者 status 均为 undefined，仅靠 message 字符串无法区分）。
+ * 超时计入重试（与 429/5xx/网络错误同策略）。
+ */
+declare class LLMTimeoutError extends LLMProviderError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * 创建 OpenAI 兼容 LLMProvider
  *
@@ -121,11 +141,23 @@ interface LLMCompleteRequest {
     temperature?: number;
     /** 最大生成 token 数 */
     maxTokens?: number;
+    /**
+     * 本次请求的超时（毫秒，调用级覆盖）
+     *
+     * 缺省回落 `LlmConfig.timeoutMs`，两者皆未设置时无超时。
+     * 超时触发抛 `LLMTimeoutError`（计入重试，与 429/5xx/网络错误同策略）。
+     */
+    timeoutMs?: number;
+    /**
+     * 本次请求的重试上限（调用级覆盖）
+     *
+     * 缺省回落 `LlmConfig.maxRetries`（默认 2）。仅 429/5xx/网络错误/超时计入重试。
+     */
+    maxRetries?: number;
     /**
      * 取消信号（透传到底层 HTTP 请求）
      *
-     * abort 时请求中断并抛 `AgentAbortError`；与 `LlmConfig.timeoutMs` 的
-     * 超时信号组合生效（任一触发即中断）。
+     * abort 时请求中断并抛 `AgentAbortError`；与超时信号组合生效（任一触发即中断）。
      */
     signal?: AbortSignal;
 }
@@ -168,6 +200,12 @@ interface LLMResponse {
     stopReason: LLMStopReason;
     /** token 用量（部分 provider 不返回） */
     usage?: LLMUsage;
+    /**
+     * 实际发起的 HTTP 尝试次数（≥1，含失败尝试）
+     *
+     * 供失败钩子/日志观测重试消耗；provider 未提供时视为 1。
+     */
+    attempts?: number;
 }
 /**
  * Token 用量（OpenAI chat completions 规范形）
@@ -228,6 +266,20 @@ interface LLMProvider {
  */
 declare function createProvider(config: LlmConfig): LLMProvider;
 
+/**
+ * 创建轻量补全通道
+ *
+ * @param deps.llms provider 配置映射（来自 `config.agent.llms`，同源零新增配置）
+ * @param deps.providers 已构建的 provider 实例映射（插件传入——与 agent 循环共享
+ *                       同一单例）；缺省时按 `llms` 逐项 `createProvider` 现场构建
+ *                       （隔离 worker 重建 / 测试形态）
+ * @returns 补全通道（`complete` 方法）
+ */
+declare function createLightComplete(deps: {
+    llms: Record<string, LlmConfig>;
+    providers?: Map<string, LLMProvider>;
+}): LlmComplete;
+
 /**
  * 单次 agent.run() / agent.stream() 的结构化调用明细
  *
@@ -918,6 +970,16 @@ interface AgentDeps {
     loadToolModule: (filePath: string, functionName: string) => Promise<ToolModule>;
     /** tool input 的 schema 解析（Phase 3.5 实现，可选） */
     resolveToolSchema?: (tool: ToolMetadata) => Promise<ToolSchemaResolution | undefined>;
+    /**
+     * sub-agent 派发入参 schema 解析（可选）
+     *
+     * sub 元数据声明 `inputTypeName`（handler.ts 顶层 `Input` 导出，构建期生成 zod.js）
+     * 时解析其 JSON Schema + 校验函数——`buildToolDefinitions` 用作派发工具 parameters、
+     * `executeSubAgent` 执行前校验。通常与 `resolveToolSchema` 是同一实现
+     * （[createToolSchemaResolver](./toolSchemaResolver.md) 返回值同时满足两个签名）。
+     * 未提供时派发一律走单字段 `input` 模式（编程式组装的向后兼容）。
+     */
+    resolveAgentInputSchema?: (agent: AgentMetadata) => Promise<ToolSchemaResolution | undefined>;
 }
 /**
  * Agent 系统级错误
@@ -1086,19 +1148,8 @@ declare class Agent {
      */
     private resolveExternalProvider;
     /**
-     * 解析 `options.model` 字符串 key → provider + model
-     *
-     * 规则见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」。
-     * 无默认 provider——`key` 未传时用 agent 元数据 `config.model` 作为缺省 key；
-     * 两者皆无抛 `AgentError`（要求调用方传 `options.model` 或 `options.provider`）。
-     * 1. 精确匹配 `deps.providers` 的 key → 该 provider + 其 `models` 第一个 key
-     *    （该 provider 未声明 `models` 时回落 `meta.model`）
-     * 2. 含 `/` → `provider/model` 形式,`deps.providers.get(provider)` + 该 model
-     *    （要求该 model 在 `deps.llms[provider].models` 里）
-     * 3. 不含 `/` 且非 provider key → 在所有 provider 的 `models` 里按 model 名查找
-     *    - 唯一 → 该 provider + 该 model
-     *    - 多个 → 抛 `AgentError`（要求用 `provider/model` 消歧）
-     *    - 无 → 抛 `AgentError`
+     * 解析 `options.model` 字符串 key → provider + model（模块级 [resolveModelKey] 的
+     * Agent 方法包装——meta.model 作缺省 key，与 [lightComplete](./lightComplete.md) 共用同一解析实现）
      *
      * @throws {AgentError} key 与 `meta.model` 均缺省；key 解析失败（provider/model
      *   不存在或歧义）
@@ -1115,11 +1166,29 @@ declare class Agent {
      * - `resolveToolSchema` 提供 → 用其 `jsonSchema`
      * - 未提供 / tool 无 `inputTypeName` → 自由 schema `{ type: 'object' }`
      *
-     * sub-agent 的 `function.parameters` 为显式单字段 `input` schema（string,必填）——
-     * 严格遵循 JSON schema 的模型对无属性 `{ type: 'object' }` 只回 `{}`,派发上下文
-     * 传不进子代理;description 用 sub 元数据 `inputDescription`,未声明用默认文案。
+     * sub-agent 的 `function.parameters` 按「派发入参 schema 声明」二选一：
+     * - **富 schema 模式**——sub 元数据声明 `inputTypeName`（handler.ts 顶层 `Input`
+     *   导出）且 `resolveAgentInputSchema` 已接线 → 用解析出的 JSON Schema（结构性
+     *   交接单,字段 JSDoc 即主控可见参数描述）。声明了但解析为 `undefined` 是产物
+     *   异常（dev/prod 全量生成下 zod.js 不可能合法缺失）,抛 `AgentError` 不静默降级
+     * - **单字段 `input` 模式**——未声明 `Input` 或 resolver 未接线 → 显式单字段
+     *   schema（string,必填）——严格遵循 JSON schema 的模型对无属性 `{ type: 'object' }`
+     *   只回 `{}`,派发上下文传不进子代理;description 用 sub 元数据 `inputDescription`,
+     *   未声明用默认文案
      */
     private buildToolDefinitions;
+    /**
+     * 解析 sub-agent 派发工具的 parameters（富 schema / 单字段 input 二选一）
+     *
+     * 富 schema 判定需要完整元数据的 `inputTypeName`（`AgentCore` 不含）——经
+     * `getAgentEntry` 查询；未声明或 `resolveAgentInputSchema` 未接线时返回单字段
+     * `input` schema（历史行为,完全向后兼容）。`inputDescription` 仍从 `AgentCore`
+     * 读取（LLM 可见字段的既定来源,DB skill 同样可声明）。
+     *
+     * @throws {AgentError} 声明了 `inputTypeName` 且 resolver 已接线但解析为
+     *   `undefined`（zod.js 缺失/损坏的产物异常,不静默退回单字段模式）
+     */
+    private getSubAgentParameters;
     /**
      * tool 执行路由（由 reactLoop 调用）
      *
@@ -1142,9 +1211,15 @@ declare class Agent {
      * sub-agent 递归执行
      *
      * 1. `maxAgentDepth` 防护——超限抛 {@link AgentRecursionError}
-     * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`（无 trace、无结构化
+     * 2. **派发入参校验（富 schema 模式）**——sub 元数据声明 `inputTypeName` 且
+     *    `resolveAgentInputSchema` 已接线时执行前 `validate(args)`：失败返回
+     *    `{ error }` 回灌主控 LLM 重试（与常规 tool 校验失败同语义,不进入子循环——
+     *    省掉一次注定失败的子 agent 轮次）;通过后以 coerce 后的 value 继续传导。
+     *    声明了但解析为 `undefined`（zod.js 缺失/损坏）抛 `AgentError` 显式失败;
+     *    resolver 未接线或未声明 `Input` 时跳过校验,行为与历史版本一致
+     * 3. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`（无 trace、无结构化
      *    usage 可卷——直接返回业务结果,其 token 不进入父 run 台账）
-     * 3. 无 `run` 时调 `subAgent.run(stringify(args), { agent, provider, model, enableTracing })`
+     * 4. 无 `run` 时调 `subAgent.run(stringify(args), { agent, provider, model, enableTracing })`
      *    走默认 reactLoop——继承父调用的 provider,sub 元数据声明 `model` 时优先用自身的,
      *    未声明时沿用父 model
      *
@@ -1176,27 +1251,40 @@ declare class Agent {
  */
 
 /**
- * 创建带 mtime 缓存的 tool schema 解析器
+ * schema 定位的最小来源结构——tool 元数据（`ToolMetadata`）与 agent 完整元数据
+ * （`AgentMetadata`，派发入参 schema 声明场景）均满足，同一 resolver 服务两类来源
+ * （`AgentDeps.resolveToolSchema` + `AgentDeps.resolveAgentInputSchema`），缓存按
+ * zod.js 路径天然分流
+ */
+type SchemaSourceRef = {
+    filePath: string;
+    inputTypeName?: string;
+};
+/**
+ * 创建带 mtime 缓存的 schema 解析器（tool input 与 agent 派发入参共用）
  *
- * 返回的函数满足 `AgentDeps.resolveToolSchema` 签名，供两处共用：
- * - `@faapi/agent` 插件 setup（传 `ctx.rootDir`，root + sub-agent 共享同一闭包缓存）
+ * 返回的函数满足 `AgentDeps.resolveToolSchema` / `AgentDeps.resolveAgentInputSchema`
+ * 两个签名（参数为最小结构 `SchemaSourceRef`），供三处共用：
+ * - `@faapi/agent` 插件 setup（传 `ctx.rootDir`，同一实例注入两个 deps，root +
+ *   sub-agent 共享同一闭包缓存）
  * - 任务内组装 [Agent](./agent.md)（`TaskContext` 无 rootDir，缺省 `process.cwd()`——
  *   faapi 服务进程 cwd 即项目根；建议任务文件模块级创建一次）
  *
  * **缓存语义**（闭包级 `Map<key, { mtimeMs, resolution }>`）：
  * - 缓存键 `zodPath#inputTypeName`，每次查找 `statSync` 一次做 mtime 自校验——
- *   mtime 变化即重新解析（dev reloadTools 重生成 zod.js 后自愈，prod 产物固化永远命中）
- * - in-flight Promise 直接入缓存：同一 tool 的并发调用共享同一次解析
+ *   mtime 变化即重新解析（dev reload 重生成 zod.js 后自愈，prod 产物固化永远命中）
+ * - in-flight Promise 直接入缓存：同一来源的并发调用共享同一次解析
  * - 每次 `createToolSchemaResolver` 调用返回独立缓存的 resolver
  *
- * zod.js 缺失 / tool 无 `inputTypeName` 时解析结果为 `undefined`——agent 用
- * 自由 schema `{ type: 'object' }`，LLM 自由传参。
+ * zod.js 缺失 / 无 `inputTypeName` 时解析结果为 `undefined`——tool 侧用自由 schema
+ * `{ type: 'object' }`；agent 派发侧对「声明了 `inputTypeName` 但解析为 `undefined`」
+ * 的产物异常语义（显式抛错）由 [agent.ts](./agent.ts) 定义，本工厂只如实返回。
  *
  * @param options.rootDir 项目根目录（缺省 `process.cwd()`）
  */
 declare function createToolSchemaResolver(options?: {
     rootDir?: string;
-}): (tool: ToolMetadata) => Promise<ToolSchemaResolution | undefined>;
+}): (ref: SchemaSourceRef) => Promise<ToolSchemaResolution | undefined>;
 
 /**
  * @faapi/agent faapi 插件——注册 agent handle 工厂,让 handler 的 `agent` 参数注入可用的 Agent 实例
@@ -1247,4 +1335,4 @@ declare function createToolSchemaResolver(options?: {
  */
 declare const agentPlugin: FaapiPlugin;
 
-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 };
+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, LLMTimeoutError, type LLMToolCall, type LLMToolDefinition, type LLMUsage, type LlmCallEvent, type ReactLoopConfig, ReactLoopError, type ReactLoopResult, type ReactLoopStreamChunk, type SchemaSourceRef, type SubAgentCallEvent, type SubAgentDelta, type SubAgentDeltaEmitter, type SubAgentToolResult, type ToolCallEvent, type ToolExecutor, type ToolSchemaResolution, type TracingToolResult, createLightComplete, createOpenAIProvider, createProvider, createToolSchemaResolver, agentPlugin as default, isSubAgentToolResult, isTracingToolResult, reactLoop, reactLoopStream };