@faapi/agent 3.2.1 → 4.0.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LlmConfig, AgentToolDescriptor, AgentCore, AgentMetadata, ToolMetadata, ToolModule, AgentModule, FaapiPlugin } from '@faapi/faapi';
+import { LlmConfig, AgentToolDescriptor, FaapiContext, AgentCore, AgentMetadata, ToolMetadata, ToolModule, AgentModule, FaapiPlugin } from '@faapi/faapi';
 
 /**
  * LLM Provider 错误
@@ -100,6 +100,23 @@ interface LLMCompleteRequest {
     temperature?: number;
     /** 最大生成 token 数 */
     maxTokens?: number;
+    /**
+     * 取消信号（透传到底层 HTTP 请求）
+     *
+     * abort 时请求中断并抛 `AgentAbortError`；与 `LlmConfig.timeoutMs` 的
+     * 超时信号组合生效（任一触发即中断）。
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Agent 执行被取消
+ *
+ * 外部 `AbortSignal` 触发时抛出（请求前预检查或请求中断）。
+ * 业务方通过 `instanceof AgentAbortError` 区分「用户取消」与真实错误——
+ * 取消不是故障，不应触发告警/重试逻辑。
+ */
+declare class AgentAbortError extends Error {
+    constructor(message?: string);
 }
 /**
  * LLM 响应的停止原因
@@ -180,8 +197,9 @@ declare function createProvider(config: LlmConfig): LLMProvider;
 /**
  * 单次 agent.run() / agent.stream() 的结构化调用明细
  *
- * 默认开启（`enableTracing` 默认 `true`）,业务方在生产主路径显式
- * `enableTracing: false` 关闭以零开销运行。详见 [trace.md](./trace.md)。
+ * 默认关闭（`enableTracing` 默认 `false`——opt-in,不开启零开销）,
+ * 通过 `config.agent.enableTracing: true` 全局开启或单次调用
+ * `agent.run(input, { enableTracing: true })` 开启。详见 [trace.md](./trace.md)。
  */
 interface AgentTrace {
     /** agent 名 */
@@ -342,6 +360,21 @@ interface ReactLoopConfig {
     temperature?: number;
     /** 最大生成 token 数 */
     maxTokens?: number;
+    /**
+     * 取消信号（透传到每轮 LLM 请求）
+     *
+     * 循环每轮开始前预检查：已取消时抛 `AgentAbortError`（不再发起 LLM 调用）；
+     * 执行中取消由 provider 的请求中断传播。tool 执行不被取消（业务自决）。
+     */
+    signal?: AbortSignal;
+    /**
+     * 发送给 LLM 的历史 token 预算（近似估算：字符数 / 2；未设置 = 不裁剪，向后兼容）
+     *
+     * 超预算时从最旧的「轮组」（assistant + 其后全部 tool 结果）开始裁剪，
+     * system 与初始 user 永不裁剪，至少保留最近一轮。裁剪只作用于发给 LLM 的
+     * 消息副本，本地 `messages` 与 trace 不受影响。详见 reactLoop.md 的历史裁剪章节。
+     */
+    maxHistoryTokens?: number;
     /**
      * 启用 tracing（默认 true）。开启时填充 `ReactLoopResult.trace` /
      * `ReactLoopStreamChunk.traceEvent`,详见 [trace.md](./trace.md)。
@@ -482,6 +515,9 @@ declare function reactLoopStream(input: string, config: ReactLoopConfig): AsyncI
  * `AgentRuntimeConfig` / `defaultLlm` provider。详见 [agentHandle.md](./agentHandle.md) 的
  * Run-level 覆盖优先级表。
  *
+ * `agent` 字段覆盖本次调用的 agent 名（不传时用 `config.agent.defaultAgent`，
+ * 未设 defaultAgent 时必须显式传入）。
+ *
  * @example
  * ```ts
  * // 按请求切模型（纯 model 名,在 llms 里唯一时切到对应 provider）
@@ -489,9 +525,26 @@ declare function reactLoopStream(input: string, config: ReactLoopConfig): AsyncI
  *
  * // provider/model 一体化形式（精确切换）
  * await agent.run(input, { model: 'anthropic/claude-3-5-sonnet' });
+ *
+ * // 指定 agent（不依赖 defaultAgent 配置）
+ * await agent.run(input, { agent: 'researcher' });
  * ```
  */
 interface AgentRunOptions {
+    /**
+     * 取消信号（透传到每轮 LLM 请求）
+     *
+     * abort 后当前轮请求中断并抛 `AgentAbortError`，循环不再进入下一轮。
+     * 业务方（如 SSE/WS 客户端断开）可通过 `req.signal` 等接入取消链路。
+     */
+    signal?: AbortSignal;
+    /**
+     * 覆盖本次调用的 agent 名（从 agentRegistry 查找对应元数据 / tools / sub-agents）
+     *
+     * 不传时用 `config.agent.defaultAgent`。`defaultAgent` 未设时必须显式传入，
+     * 否则抛 `AgentError`。
+     */
+    agent?: string;
     /**
      * 切换 provider + model 的字符串 key（支持 llms key / `provider/model` / 纯 model 名）
      *
@@ -503,12 +556,11 @@ interface AgentRunOptions {
     /** 最大生成 token 数（透传给 LLM API） */
     maxTokens?: number;
     /**
-     * 启用 tracing（默认沿用全局 `config.agent.enableTracing`,全局默认 `true`）。
+     * 启用 tracing（默认沿用全局 `config.agent.enableTracing`,全局默认 `false`——
+     * opt-in,不开启零开销）。
      *
      * 开启时 `ReactLoopResult.trace` / `ReactLoopStreamChunk.traceEvent` 填充
      * 结构化调用明细,详见 [trace.md](./trace.md)。
-     *
-     * 业务方在生产主路径显式传 `false` 关闭以零开销运行。
      */
     enableTracing?: boolean;
 }
@@ -565,17 +617,54 @@ interface AgentRuntimeConfig {
     maxTurns?: number;
     /** agent 调用 agent 的最大递归深度（默认 3） */
     maxAgentDepth?: number;
+    /** 发送给 LLM 的历史 token 预算（近似估算,未设置 = 不裁剪）——透传 reactLoop,见 reactLoop.md 历史裁剪章节 */
+    maxHistoryTokens?: number;
     /**
-     * 启用 tracing 的全局默认值（默认 true）。
+     * 启用 tracing 的全局默认值（默认 false——opt-in,不开启零开销）。
      *
      * 开启时 `ReactLoopResult.trace` / `ReactLoopStreamChunk.traceEvent` 填充
      * 结构化调用明细,详见 [trace.md](./trace.md)。
      *
      * 单次调用可通过 `AgentRunOptions.enableTracing` 覆盖。
-     * 业务方在生产主路径显式设 `false` 关闭以零开销运行。
      */
     enableTracing?: boolean;
+    /**
+     * 执行守卫（authHooks,见 [authHooks.md](./authHooks.md)）
+     *
+     * `executeTool` 最开头调用（`agent.` 分流之前）——同时覆盖常规 tool 与
+     * sub-agent 递归。三种返回：`void` 放行；`{ error }` 拒绝（不执行 handler,
+     * error 回传 LLM）；`{ args }` 改写后放行（多租户场景强制注入可信值,
+     * 不信 LLM 传入的标识参数）。
+     */
+    beforeToolCall?: ToolCallGuardHook;
+    /**
+     * 审计钩子（authHooks）：tool / sub-agent 成功返回后调用,返回值忽略。
+     * 异常路径不调用。
+     */
+    afterToolCall?: AfterToolCallHook;
+    /**
+     * 可见性过滤（authHooks）：`buildToolDefinitions` 组装完 LLM 可见 tools 后
+     * 调用,返回过滤后的数组。每次 `run` / `stream` 生效,含 agent-as-tool 项。
+     */
+    filterTools?: FilterToolsHook;
 }
+/**
+ * beforeToolCall 的返回守卫
+ *
+ * - `{ error }`：拒绝执行,error 字符串回传 LLM
+ * - `{ args }`：以改写后的参数继续执行
+ */
+type ToolCallGuard = {
+    error: string;
+} | {
+    args: Record<string, unknown>;
+};
+/** 执行守卫钩子签名（ctx 为请求上下文,编程式直调可能为 undefined） */
+type ToolCallGuardHook = (name: string, args: Record<string, unknown>, ctx: FaapiContext | undefined) => void | ToolCallGuard;
+/** 审计钩子签名（仅成功路径调用） */
+type AfterToolCallHook = (name: string, args: Record<string, unknown>, result: unknown, ctx: FaapiContext | undefined) => void;
+/** 可见性过滤钩子签名 */
+type FilterToolsHook = (tools: LLMToolDefinition[], ctx: FaapiContext | undefined) => LLMToolDefinition[];
 /**
  * tool schema 解析结果
  *
@@ -621,6 +710,14 @@ interface AgentDeps {
     rootDir: string;
     /** 全局 agent 配置覆盖 */
     config?: AgentRuntimeConfig;
+    /**
+     * 请求上下文（authHooks ctx 传递链,见 [authHooks.md](./authHooks.md)）
+     *
+     * 由 @faapi/agent 工厂捕获（AgentHandleFactory 签名本就接收 ctx）。
+     * 编程式直调（测试/自定义启动器）不传,钩子收到 undefined。
+     * sub-agent 递归经 subDeps 展开自动传导（同一 HTTP 请求内 ctx 不变）。
+     */
+    ctx?: FaapiContext;
     /** 查 agent LLM 可见元数据（对应 agentRegistry.getAgent,返回 AgentCore） */
     getAgent: (name: string) => AgentCore | undefined;
     /** 查 agent 完整元数据（对应 agentRegistry.getAgentEntry,返回 AgentMetadata 含 filePath/hasRun） */
@@ -732,15 +829,20 @@ declare class Agent {
     /**
      * 组装 ReactLoopConfig
      *
-     * 1. 查 agent 元数据（未注册抛 AgentError）——用 `getAgent` 拿 AgentCore
+     * 1. 解析有效 agent 名：`options.agent` > `deps.agentName`（`config.agent.defaultAgent`）
+     * 2. 查 agent 元数据（未注册抛 AgentError）——用 `getAgent` 拿 AgentCore
      *    (LLM-facing 字段:systemPrompt / model / maxTurns)
-     * 2. buildToolDefinitions 组装 tool 列表
-     * 3. config 字段优先级（高 → 低）：`options` > agent 元数据 > 全局 AgentRuntimeConfig / deps.defaultProvider
+     * 3. buildToolDefinitions 组装 tool 列表（用有效 agent 名查 tools / sub-agents）
+     * 4. config 字段优先级（高 → 低）：`options` > agent 元数据 > 全局 AgentRuntimeConfig / deps.defaultProvider
      *
      * `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 解析规则」。
+     *
+     * `options.agent` 覆盖本次调用的 agent 名——不传时用 `deps.agentName`（来自
+     * `config.agent.defaultAgent`）。`defaultAgent` 未设且 `options.agent` 未传时抛
+     * `AgentError`。
      */
     private buildLoopConfig;
     /**
@@ -842,15 +944,18 @@ declare class Agent {
  * 插件 setup 时：
  * 1. 遍历 `config.agent.llms` → 每项调 `createProvider` → `Map<providerKey, LLMProvider>`
  * 2. 读 `config.agent.defaultLlm` → `defaultProvider`（未设时用 `llms` 第一个 key）
- * 3. 读 `config.agent.defaultAgent` / `maxTurns` / `maxAgentDepth`
+ * 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` 或 `agent.defaultAgent` 未设置）跳过工厂注册并打印警告,
+ * 配置缺失时（`agent.llms` 未设置）跳过工厂注册并打印警告,
  * handler 的 `agent` 参数注入 `undefined`。
  *
+ * `defaultAgent` 可选——未设时 handler 需通过 `agent.run(input, { agent: 'name' })`
+ * 显式指定 agent 名。
+ *
  * 详见 [plugin.md](./plugin.md)。
  */
 
@@ -862,4 +967,4 @@ declare class Agent {
  */
 declare const agentPlugin: FaapiPlugin;
 
-export { Agent, 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, agentPlugin as default, isTracingToolResult, reactLoop, reactLoopStream };
+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, agentPlugin as default, isTracingToolResult, reactLoop, reactLoopStream };