@faapi/agent 3.2.1 → 4.0.0

package/dist/index.js

@@ -1,6 +1,14 @@
 // src/providers/openai.ts
 var DEFAULT_BASE_URL = "https://api.openai.com/v1";
-var RESERVED_CONFIG_KEYS = /* @__PURE__ */ new Set(["provider", "apiKey", "model", "baseURL", "models"]);
+var RESERVED_CONFIG_KEYS = /* @__PURE__ */ new Set([
+  "provider",
+  "apiKey",
+  "model",
+  "baseURL",
+  "models",
+  "timeoutMs",
+  "maxRetries"
+]);
 var LLMProviderError = class extends Error {
   /** HTTP 状态码（网络错误 / JSON 解析错误为 undefined） */
   status;
@@ -16,6 +24,7 @@ var LLMProviderError = class extends Error {
 function createOpenAIProvider(config) {
   const baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
   const apiKey = config.apiKey;
+  const maxRetries = Math.max(0, typeof config.maxRetries === "number" ? config.maxRetries : 2);
   function buildRequestBody(request) {
     const modelName = request.model ?? Object.keys(config.models)[0];
     const modelConfig = modelName ? config.models[modelName] : void 0;
@@ -58,34 +67,101 @@ function createOpenAIProvider(config) {
     if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
     return headers;
   }
-  async function safeFetch(url, init) {
+  function classifyAbortError(err, externalSignal) {
+    if (externalSignal?.aborted) {
+      return new AgentAbortError();
+    }
+    const errName = err?.name;
+    if (errName === "AbortError" || errName === "TimeoutError") {
+      return new LLMProviderError(`LLM request timed out after ${config.timeoutMs}ms`);
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    return new LLMProviderError(`Network error: ${reason}`, { cause: err });
+  }
+  function isAbortLike(err) {
+    const name = err?.name;
+    return name === "AbortError" || name === "TimeoutError";
+  }
+  async function safeFetch(url, init, externalSignal) {
     try {
       return await fetch(url, init);
     } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      throw new LLMProviderError(`Network error: ${reason}`, { cause: err });
+      throw classifyAbortError(err, externalSignal);
     }
   }
-  async function ensureOk(response) {
-    if (response.ok) return "";
-    const bodyText = await response.text();
-    const excerpt = bodyText.slice(0, 500);
-    throw new LLMProviderError(`HTTP ${response.status}: ${excerpt}`, {
-      status: response.status,
-      body: excerpt
-    });
+  function isRetryable(err) {
+    if (!(err instanceof LLMProviderError)) return false;
+    if (err.status === void 0) return true;
+    return err.status === 429 || err.status >= 500;
+  }
+  function retryDelayMs(response, attempt) {
+    const retryAfter = response?.headers.get("retry-after");
+    if (retryAfter) {
+      const seconds = Number(retryAfter);
+      if (!isNaN(seconds) && seconds >= 0) return Math.min(seconds * 1e3, 3e4);
+    }
+    return 500 * 2 ** attempt;
+  }
+  function effectiveSignal(request) {
+    const { signal } = request;
+    const timeoutMs = typeof config.timeoutMs === "number" ? config.timeoutMs : void 0;
+    if (!signal && !timeoutMs) return void 0;
+    const signals = [];
+    if (signal) signals.push(signal);
+    if (timeoutMs) signals.push(AbortSignal.timeout(timeoutMs));
+    return signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+  }
+  async function fetchOkWithRetry(url, baseInit, request, maxRetries2) {
+    let lastErr;
+    let lastResponse;
+    for (let attempt = 0; attempt <= maxRetries2; attempt++) {
+      if (request.signal?.aborted) {
+        throw new AgentAbortError();
+      }
+      if (attempt > 0) {
+        await new Promise((r) => setTimeout(r, retryDelayMs(lastResponse, attempt - 1)));
+      }
+      const init = { ...baseInit, signal: effectiveSignal(request) };
+      let response;
+      try {
+        response = await safeFetch(url, init, request.signal);
+      } catch (err2) {
+        if (!isRetryable(err2)) throw err2;
+        lastErr = err2;
+        continue;
+      }
+      if (response.ok) return response;
+      let excerpt = "<body unreadable>";
+      try {
+        excerpt = (await response.text()).slice(0, 500);
+      } catch {
+      }
+      const err = new LLMProviderError(`HTTP ${response.status}: ${excerpt}`, {
+        status: response.status,
+        body: excerpt
+      });
+      if (!isRetryable(err)) throw err;
+      lastErr = err;
+      lastResponse = response;
+    }
+    throw lastErr;
   }
   async function complete(request) {
     const url = `${baseURL}/chat/completions`;
     const body = buildRequestBody(request);
-    const init = {
+    const baseInit = {
       method: "POST",
       headers: buildHeaders(),
       body: JSON.stringify(body)
     };
-    const response = await safeFetch(url, init);
-    await ensureOk(response);
-    const bodyText = await response.text();
+    const response = await fetchOkWithRetry(url, baseInit, request, maxRetries);
+    let bodyText;
+    try {
+      bodyText = await response.text();
+    } catch (err) {
+      if (!isAbortLike(err)) throw err;
+      throw classifyAbortError(err, request.signal);
+    }
     let json;
     try {
       json = JSON.parse(bodyText);
@@ -121,13 +197,12 @@ function createOpenAIProvider(config) {
     const url = `${baseURL}/chat/completions`;
     const body = buildRequestBody(request);
     body.stream = true;
-    const init = {
+    const baseInit = {
       method: "POST",
       headers: buildHeaders(),
       body: JSON.stringify(body)
     };
-    const response = await safeFetch(url, init);
-    await ensureOk(response);
+    const response = await fetchOkWithRetry(url, baseInit, request, maxRetries);
     if (!response.body) {
       throw new LLMProviderError("Response body is null (streaming unsupported)", {
         status: response.status
@@ -144,10 +219,12 @@ function createOpenAIProvider(config) {
         const { done, value } = await reader.read();
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
-        let sep;
-        while ((sep = buffer.indexOf("\n\n")) >= 0) {
-          const eventStr = buffer.slice(0, sep);
-          buffer = buffer.slice(sep + 2);
+        while (true) {
+          const boundary = findSseEventBoundary(buffer);
+          if (!boundary) break;
+          const [start, length] = boundary;
+          const eventStr = buffer.slice(0, start);
+          buffer = buffer.slice(start + length);
           const data = extractSSEData(eventStr);
           if (data === null) continue;
           if (data === "[DONE]") {
@@ -181,8 +258,15 @@ function createOpenAIProvider(config) {
         }
       }
       yield finalizeStreamChunk(accumulators, finishReason, usage);
+    } catch (err) {
+      if (!isAbortLike(err)) throw err;
+      throw classifyAbortError(err, request.signal);
     } finally {
-      reader.releaseLock();
+      try {
+        await reader.cancel();
+      } catch {
+        reader.releaseLock();
+      }
     }
   }
   return { complete, stream };
@@ -260,7 +344,7 @@ function mapUsage(u) {
 }
 function extractSSEData(event) {
   const dataLines = [];
-  for (const line of event.split("\n")) {
+  for (const line of event.split(/\r\n|\n|\r/)) {
     if (line === "" || line.startsWith(":")) continue;
     if (line.startsWith("data:")) {
       dataLines.push(line.slice(5).replace(/^ /, ""));
@@ -269,6 +353,32 @@ function extractSSEData(event) {
   if (dataLines.length === 0) return null;
   return dataLines.join("\n");
 }
+function findSseEventBoundary(buffer) {
+  let eolCount = 0;
+  let boundaryStart = -1;
+  for (let i = 0; i < buffer.length; ) {
+    const ch = buffer[i];
+    let eolLen = 0;
+    if (ch === "\n") {
+      eolLen = 1;
+    } else if (ch === "\r") {
+      eolLen = buffer[i + 1] === "\n" ? 2 : 1;
+    }
+    if (eolLen === 0) {
+      eolCount = 0;
+      i++;
+      continue;
+    }
+    eolCount++;
+    if (eolCount === 1) {
+      boundaryStart = i;
+    } else {
+      return [boundaryStart, i + eolLen - boundaryStart];
+    }
+    i += eolLen;
+  }
+  return null;
+}
 function accumulateToolCall(accumulators, tc) {
   const idx = tc.index ?? 0;
   const acc = accumulators.get(idx) ?? { argsString: "" };
@@ -308,6 +418,12 @@ function finalizeStreamChunk(accumulators, finishReason, usage) {
 }
 
 // src/provider.ts
+var AgentAbortError = class extends Error {
+  constructor(message = "Agent execution aborted") {
+    super(message);
+    this.name = "AgentAbortError";
+  }
+};
 function createProvider(config) {
   switch (config.provider) {
     case "openai":
@@ -358,6 +474,44 @@ function buildInitialMessages(input, systemPrompt) {
   messages.push({ role: "user", content: input });
   return messages;
 }
+function estimateTokens(chars) {
+  return Math.ceil(chars / 2);
+}
+function estimateMessageTokens(message) {
+  let chars = message.content.length;
+  if (message.toolCalls) {
+    chars += JSON.stringify(message.toolCalls).length;
+  }
+  if (message.toolCallId) {
+    chars += message.toolCallId.length;
+  }
+  return estimateTokens(chars);
+}
+function trimHistory(messages, maxTokens) {
+  let headEnd = 0;
+  while (headEnd < messages.length && messages[headEnd].role !== "assistant") {
+    headEnd++;
+  }
+  const head = messages.slice(0, headEnd);
+  const turns = [];
+  for (const message of messages.slice(headEnd)) {
+    if (message.role === "assistant" || turns.length === 0) {
+      turns.push([message]);
+    } else {
+      turns[turns.length - 1].push(message);
+    }
+  }
+  if (turns.length === 0) return messages;
+  const kept = [];
+  let total = head.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
+  for (let i = turns.length - 1; i >= 0; i--) {
+    const turnTokens = turns[i].reduce((sum, m) => sum + estimateMessageTokens(m), 0);
+    if (kept.length > 0 && total + turnTokens > maxTokens) break;
+    kept.unshift(turns[i]);
+    total += turnTokens;
+  }
+  return [...head, ...kept.flat()];
+}
 function buildRequestExtras(config) {
   return {
     tools: config.tools,
@@ -377,7 +531,7 @@ function extractSubAgentName(toolName) {
   return toolName;
 }
 async function reactLoop(input, config) {
-  const enableTracing = config.enableTracing ?? true;
+  const enableTracing = config.enableTracing ?? false;
   const messages = buildInitialMessages(input, config.systemPrompt);
   const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
   const extras = buildRequestExtras(config);
@@ -386,12 +540,17 @@ async function reactLoop(input, config) {
   const traceStartedAt = enableTracing ? nowMs() : 0;
   const traceEvents = enableTracing ? [] : void 0;
   while (turns < maxTurns) {
+    if (config.signal?.aborted) {
+      throw new AgentAbortError();
+    }
     turns++;
     const llmStartedAt = enableTracing ? nowMs() : 0;
-    const inputSnapshot = enableTracing ? [...messages] : void 0;
+    const outgoing = config.maxHistoryTokens ? trimHistory(messages, config.maxHistoryTokens) : messages;
+    const inputSnapshot = enableTracing ? [...outgoing] : void 0;
     const response = await config.provider.complete({
-      messages: [...messages],
-      ...extras
+      messages: [...outgoing],
+      ...extras,
+      signal: config.signal
     });
     if (response.usage) {
       totalUsage = accumulateUsage(totalUsage, response.usage);
@@ -431,27 +590,48 @@ async function reactLoop(input, config) {
         } : void 0
       };
     }
-    for (const toolCall of response.message.toolCalls) {
-      const toolStartedAt = enableTracing ? nowMs() : 0;
-      let resultStr;
-      let rawResult;
-      let toolErr;
-      let hasError = false;
-      try {
-        rawResult = await config.executeTool(toolCall.name, toolCall.arguments);
-        if (isTracingToolResult(rawResult)) {
-          resultStr = stringifyResult(rawResult.result);
-        } else {
-          resultStr = stringifyResult(rawResult);
+    const settled = await Promise.all(
+      response.message.toolCalls.map(async (toolCall) => {
+        const toolStartedAt = enableTracing ? nowMs() : 0;
+        let resultStr;
+        let rawResult;
+        let toolErr;
+        let hasError = false;
+        try {
+          rawResult = await config.executeTool(toolCall.name, toolCall.arguments);
+          if (isTracingToolResult(rawResult)) {
+            resultStr = stringifyResult(rawResult.result);
+          } else {
+            resultStr = stringifyResult(rawResult);
+          }
+        } catch (err) {
+          hasError = true;
+          toolErr = err;
+          resultStr = stringifyError(err);
+          rawResult = void 0;
         }
-      } catch (err) {
-        hasError = true;
-        toolErr = err;
-        resultStr = stringifyError(err);
-        rawResult = void 0;
-      }
+        const toolEndedAt = enableTracing ? nowMs() : 0;
+        return {
+          toolCall,
+          toolStartedAt,
+          toolEndedAt,
+          resultStr,
+          rawResult,
+          toolErr,
+          hasError
+        };
+      })
+    );
+    for (const {
+      toolCall,
+      toolStartedAt,
+      toolEndedAt,
+      resultStr,
+      rawResult,
+      toolErr,
+      hasError
+    } of settled) {
       if (enableTracing) {
-        const toolEndedAt = nowMs();
         if (isTracingToolResult(rawResult)) {
           traceEvents.push({
             type: "subagent_call",
@@ -491,23 +671,28 @@ async function reactLoop(input, config) {
   );
 }
 async function* reactLoopStream(input, config) {
-  const enableTracing = config.enableTracing ?? true;
+  const enableTracing = config.enableTracing ?? false;
   const messages = buildInitialMessages(input, config.systemPrompt);
   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();
+    }
     turns++;
     const llmStartedAt = enableTracing ? nowMs() : 0;
-    const inputSnapshot = enableTracing ? [...messages] : void 0;
+    const outgoing = config.maxHistoryTokens ? trimHistory(messages, config.maxHistoryTokens) : messages;
+    const inputSnapshot = enableTracing ? [...outgoing] : void 0;
     let turnContent = "";
     let toolCalls;
     let finishReason;
     let turnUsage;
     for await (const chunk of config.provider.stream({
-      messages: [...messages],
-      ...extras
+      messages: [...outgoing],
+      ...extras,
+      signal: config.signal
     })) {
       if (typeof chunk.deltaContent === "string" && chunk.deltaContent.length > 0) {
         turnContent += chunk.deltaContent;
@@ -687,7 +872,7 @@ var Agent = class _Agent {
     const config = await this.buildLoopConfig(options);
     const result = await reactLoop(input, config);
     if (result.trace) {
-      result.trace.agentName = this.deps.agentName;
+      result.trace.agentName = options?.agent ?? this.deps.agentName;
     }
     return result;
   }
@@ -747,24 +932,30 @@ var Agent = 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`。
    */
   async buildLoopConfig(options) {
-    const meta = this.deps.getAgent(this.deps.agentName);
+    const agentName = options?.agent ?? this.deps.agentName;
+    const meta = this.deps.getAgent(agentName);
     if (!meta) {
-      throw new AgentError(`Agent "${this.deps.agentName}" is not registered`);
+      throw new AgentError(`Agent "${agentName}" is not registered`);
     }
-    const tools = await this.buildToolDefinitions();
+    const tools = await this.buildToolDefinitions(agentName);
     const { provider, model } = this.resolveModelKey(options?.model, meta);
-    const enableTracing = options?.enableTracing ?? this.deps.config?.enableTracing ?? true;
+    const enableTracing = options?.enableTracing ?? this.deps.config?.enableTracing ?? false;
     return {
       provider,
       systemPrompt: meta.systemPrompt,
@@ -773,6 +964,7 @@ var Agent = class _Agent {
       maxTokens: options?.maxTokens,
       maxTurns: meta.maxTurns ?? this.deps.config?.maxTurns,
       tools,
+      signal: options?.signal,
       enableTracing,
       executeTool: async (name, args) => this.executeTool(name, args, enableTracing)
     };
@@ -850,9 +1042,9 @@ var Agent = class _Agent {
    *
    * sub-agent 的 `input` 始终为 `{ type: 'object' }`（agent 参数开放）。
    */
-  async buildToolDefinitions() {
+  async buildToolDefinitions(agentName) {
     const definitions = /* @__PURE__ */ new Map();
-    for (const tool of this.deps.resolveAgentTools(this.deps.agentName)) {
+    for (const tool of this.deps.resolveAgentTools(agentName)) {
       if (definitions.has(tool.name)) continue;
       const schemaRes = await this.getToolSchema(tool);
       definitions.set(tool.name, {
@@ -861,7 +1053,7 @@ var Agent = class _Agent {
         input: schemaRes?.jsonSchema ?? { type: "object" }
       });
     }
-    for (const subAgent of this.deps.resolveSubAgents(this.deps.agentName)) {
+    for (const subAgent of this.deps.resolveSubAgents(agentName)) {
       const name = `agent.${subAgent.name}`;
       if (definitions.has(name)) continue;
       definitions.set(name, {
@@ -870,7 +1062,9 @@ var Agent = class _Agent {
         input: { type: "object" }
       });
     }
-    return Array.from(definitions.values());
+    const defs = Array.from(definitions.values());
+    const filtered = this.deps.config?.filterTools?.(defs, this.deps.ctx);
+    return filtered ?? defs;
   }
   /**
    * tool 执行路由（由 reactLoop 调用）
@@ -886,9 +1080,28 @@ var Agent = class _Agent {
    *
    * **tool 未找到 / 加载失败**：抛错，被 reactLoop catch 后同样回传 LLM。
    */
-  async executeTool(name, args, enableTracing) {
+  async executeTool(rawName, rawArgs, enableTracing) {
+    const name = rawName;
+    let args = rawArgs;
+    const guard = this.deps.config?.beforeToolCall?.(name, args, this.deps.ctx);
+    if (guard) {
+      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(this.deps.agentName)) {
+      declared.add(tool2.name);
+    }
+    for (const sub of this.deps.resolveSubAgents(this.deps.agentName)) {
+      declared.add(`agent.${sub.name}`);
+    }
+    if (!declared.has(name)) {
+      return {
+        error: `Tool "${name}" is not declared by agent "${this.deps.agentName}" (add it to the agent's tools/agents declaration)`
+      };
+    }
     if (name.startsWith("agent.")) {
-      return this.executeSubAgent(name.slice(6), args, enableTracing);
+      return await this.executeSubAgent(name.slice(6), args, enableTracing);
     }
     const tool = this.deps.getTool(name);
     if (!tool) {
@@ -897,14 +1110,16 @@ var Agent = class _Agent {
     const schemaRes = await this.getToolSchema(tool);
     let callArgs = args;
     if (schemaRes) {
-      const result = schemaRes.validate(args);
-      if (!result.ok) {
-        return { error: result.error };
+      const result2 = schemaRes.validate(args);
+      if (!result2.ok) {
+        return { error: result2.error };
       }
-      callArgs = result.value ?? args;
+      callArgs = result2.value ?? args;
     }
     const mod = await this.deps.loadToolModule(tool.filePath, tool.functionName);
-    return await mod.handler(callArgs);
+    const result = await mod.handler(callArgs, this.deps.ctx);
+    this.deps.config?.afterToolCall?.(name, args, result, this.deps.ctx);
+    return result;
   }
   /**
    * sub-agent 递归执行
@@ -941,12 +1156,15 @@ var Agent = class _Agent {
     if (entry?.hasRun) {
       const mod = await this.deps.loadAgentModule(entry.filePath, entry.hasRun);
       if (mod.run) {
-        return await mod.run(args);
+        const result2 = await mod.run(args, this.deps.ctx);
+        this.deps.config?.afterToolCall?.(`agent.${subName}`, args, result2, this.deps.ctx);
+        return result2;
       }
     }
     const result = await subAgent.run(typeof args === "string" ? args : JSON.stringify(args), {
       enableTracing
     });
+    this.deps.config?.afterToolCall?.(`agent.${subName}`, args, result.content, this.deps.ctx);
     if (enableTracing && result.trace) {
       return {
         __trace: true,
@@ -960,16 +1178,12 @@ var Agent = class _Agent {
 
 // src/plugin.ts
 import {
-  registerAgentHandleFactory,
-  getAgent,
-  getAgentEntry,
-  getTool,
-  resolveAgentTools,
-  resolveSubAgents,
   loadAgentModule,
   loadToolModule,
-  loadToolSchema
+  loadToolSchema,
+  getToolSchemaPath
 } from "@faapi/faapi";
+import { statSync } from "fs";
 import { z } from "zod";
 async function resolveToolSchemaImpl(tool, rootDir) {
   const schemaMod = await loadToolSchema(tool, rootDir);
@@ -994,6 +1208,7 @@ function readAgentConfig(ctx) {
 var agentPlugin = {
   name: "@faapi/agent",
   setup(ctx) {
+    const registries = ctx.registries;
     const agentConfig = readAgentConfig(ctx);
     if (!agentConfig?.llms) {
       console.warn(
@@ -1001,12 +1216,7 @@ var agentPlugin = {
       );
       return;
     }
-    if (!agentConfig.defaultAgent) {
-      console.warn(
-        "! @faapi/agent: config.agent.defaultAgent not configured, agent parameter injection disabled"
-      );
-      return;
-    }
+    const defaultAgent = agentConfig.defaultAgent ?? "";
     const llms = agentConfig.llms;
     const providers = /* @__PURE__ */ new Map();
     for (const [name, llmConfig] of Object.entries(llms)) {
@@ -1022,28 +1232,50 @@ var agentPlugin = {
     }
     const runtimeConfig = {
       maxTurns: agentConfig.maxTurns,
-      maxAgentDepth: agentConfig.maxAgentDepth
+      maxAgentDepth: agentConfig.maxAgentDepth,
+      maxHistoryTokens: agentConfig.maxHistoryTokens,
+      // 鉴权钩子（authHooks,见 ./authHooks.md）——业务方在 config.agent 声明
+      beforeToolCall: agentConfig.beforeToolCall,
+      afterToolCall: agentConfig.afterToolCall,
+      filterTools: agentConfig.filterTools
     };
     const rootDir = ctx.rootDir;
-    const defaultAgent = agentConfig.defaultAgent;
-    const resolveToolSchema = (tool) => resolveToolSchemaImpl(tool, rootDir);
-    registerAgentHandleFactory(() => {
+    const schemaCache = /* @__PURE__ */ new Map();
+    const resolveToolSchema = (tool) => {
+      const zodPath = getToolSchemaPath(tool, rootDir);
+      const key = `${zodPath}#${tool.inputTypeName ?? ""}`;
+      let mtimeMs = -1;
+      try {
+        mtimeMs = statSync(zodPath).mtimeMs;
+      } catch {
+      }
+      const hit = schemaCache.get(key);
+      if (hit && hit.mtimeMs === mtimeMs) {
+        return hit.resolution;
+      }
+      const resolution = resolveToolSchemaImpl(tool, rootDir);
+      schemaCache.set(key, { mtimeMs, resolution });
+      return resolution;
+    };
+    ctx.registries.agentHandle.register((ctx2) => {
       return new Agent({
         providers,
         defaultProvider,
         llms,
         defaultLlm,
-        agentName: defaultAgent,
+        agentName: defaultAgent ?? "",
         rootDir,
         config: runtimeConfig,
-        // 注册表/加载器访问器——从 @faapi/faapi import 的单例模块
-        // createAppBase 启动时已水合 agentRegistry / toolRegistry
+        // ctx 传递链（authHooks）：捕获请求上下文,tool handler / sub-agent /
+        // 鉴权钩子均可读取中间件塞入的身份信息（ctx.user / ctx.workspace 等）
+        ctx: ctx2,
+        // 注册表访问器——app 实例（PluginContext.registries），非全局单例
         // getAgent 返回 AgentCore(LLM-facing);getAgentEntry 返回 AgentMetadata(含 filePath/hasRun,供加载 handler.js)
-        getAgent,
-        getAgentEntry,
-        getTool,
-        resolveAgentTools,
-        resolveSubAgents,
+        getAgent: registries.agent.getAgent,
+        getAgentEntry: registries.agent.getAgentEntry,
+        getTool: registries.tool.get,
+        resolveAgentTools: registries.agent.resolveAgentTools,
+        resolveSubAgents: registries.agent.resolveSubAgents,
         // 加载器包装：注入 rootDir 用于 dev 按需编译模式
         loadToolModule: (filePath, functionName) => loadToolModule(filePath, functionName, rootDir),
         loadAgentModule: (filePath, hasRun) => loadAgentModule(filePath, hasRun, rootDir),
@@ -1052,13 +1284,14 @@ var agentPlugin = {
       });
     });
     console.log(
-      `- @faapi/agent: default agent "${defaultAgent}" (provider: ${defaultLlm}) available via agent parameter injection`
+      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})`
     );
   }
 };
 var plugin_default = agentPlugin;
 export {
   Agent,
+  AgentAbortError,
   AgentError,
   AgentRecursionError,
   LLMProviderError,