@faapi/agent 6.30.0 → 6.32.0

package/dist/index.js

@@ -14,6 +14,13 @@ var LLMProviderError = class extends Error {
   status;
   /** 响应体摘要（前 500 字符,便于诊断） */
   body;
+  /**
+   * 实际发起的 HTTP 尝试次数（≥1，含失败尝试）
+   *
+   * 重试耗尽抛出时由重试循环回填（构造时未知，故非 readonly）；
+   * 首次尝试即失败的确定性错误（4xx 直抛）为 1，未回填时视为 1。
+   */
+  attempts;
   constructor(message, options) {
     super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
     this.name = "LLMProviderError";
@@ -21,6 +28,12 @@ var LLMProviderError = class extends Error {
     this.body = options?.body;
   }
 };
+var LLMTimeoutError = class extends LLMProviderError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "LLMTimeoutError";
+  }
+};
 function createOpenAIProvider(config) {
   const baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
   const apiKey = config.apiKey;
@@ -69,13 +82,19 @@ function createOpenAIProvider(config) {
     if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
     return headers;
   }
-  function classifyAbortError(err, externalSignal) {
+  function resolveTimeoutMs(request) {
+    if (typeof request.timeoutMs === "number") return request.timeoutMs;
+    return typeof config.timeoutMs === "number" ? config.timeoutMs : void 0;
+  }
+  function classifyAbortError(err, externalSignal, timeoutMs) {
     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`);
+      return new LLMTimeoutError(
+        timeoutMs !== void 0 ? `LLM request timed out after ${timeoutMs}ms` : "LLM request timed out"
+      );
     }
     const reason = err instanceof Error ? err.message : String(err);
     return new LLMProviderError(`Network error: ${reason}`, { cause: err });
@@ -84,11 +103,11 @@ function createOpenAIProvider(config) {
     const name = err?.name;
     return name === "AbortError" || name === "TimeoutError";
   }
-  async function safeFetch(url, init, externalSignal) {
+  async function safeFetch(url, init, externalSignal, timeoutMs) {
     try {
       return await fetch(url, init);
     } catch (err) {
-      throw classifyAbortError(err, externalSignal);
+      throw classifyAbortError(err, externalSignal, timeoutMs);
     }
   }
   function isRetryable(err) {
@@ -106,17 +125,23 @@ function createOpenAIProvider(config) {
   }
   function effectiveSignal(request) {
     const { signal } = request;
-    const timeoutMs = typeof config.timeoutMs === "number" ? config.timeoutMs : void 0;
+    const timeoutMs = resolveTimeoutMs(request);
     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) {
+  function resolveMaxRetries(request) {
+    if (typeof request.maxRetries === "number") return Math.max(0, request.maxRetries);
+    return maxRetries;
+  }
+  async function fetchOkWithRetry(url, baseInit, request) {
+    const maxAttemptsRetries = resolveMaxRetries(request);
+    const timeoutMs = resolveTimeoutMs(request);
     let lastErr;
     let lastResponse;
-    for (let attempt = 0; attempt <= maxRetries2; attempt++) {
+    for (let attempt = 0; attempt <= maxAttemptsRetries; attempt++) {
       if (request.signal?.aborted) {
         throw new AgentAbortError();
       }
@@ -126,13 +151,13 @@ function createOpenAIProvider(config) {
       const init = { ...baseInit, signal: effectiveSignal(request) };
       let response;
       try {
-        response = await safeFetch(url, init, request.signal);
+        response = await safeFetch(url, init, request.signal, timeoutMs);
       } catch (err2) {
         if (!isRetryable(err2)) throw err2;
         lastErr = err2;
         continue;
       }
-      if (response.ok) return response;
+      if (response.ok) return { response, attempts: attempt + 1 };
       let excerpt = "<body unreadable>";
       try {
         excerpt = (await response.text()).slice(0, 500);
@@ -146,6 +171,9 @@ function createOpenAIProvider(config) {
       lastErr = err;
       lastResponse = response;
     }
+    if (lastErr instanceof LLMProviderError) {
+      lastErr.attempts = maxAttemptsRetries + 1;
+    }
     throw lastErr;
   }
   async function complete(request) {
@@ -156,13 +184,14 @@ function createOpenAIProvider(config) {
       headers: buildHeaders(),
       body: JSON.stringify(body)
     };
-    const response = await fetchOkWithRetry(url, baseInit, request, maxRetries);
+    const timeoutMs = resolveTimeoutMs(request);
+    const { response, attempts } = await fetchOkWithRetry(url, baseInit, request);
     let bodyText;
     try {
       bodyText = await response.text();
     } catch (err) {
       if (!isAbortLike(err)) throw err;
-      throw classifyAbortError(err, request.signal);
+      throw classifyAbortError(err, request.signal, timeoutMs);
     }
     let json;
     try {
@@ -192,7 +221,8 @@ function createOpenAIProvider(config) {
     return {
       message,
       stopReason: mapStopReason(choice.finish_reason ?? void 0),
-      usage: mapUsage(json.usage)
+      usage: mapUsage(json.usage),
+      attempts
     };
   }
   async function* stream(request) {
@@ -204,7 +234,8 @@ function createOpenAIProvider(config) {
       headers: buildHeaders(),
       body: JSON.stringify(body)
     };
-    const response = await fetchOkWithRetry(url, baseInit, request, maxRetries);
+    const timeoutMs = resolveTimeoutMs(request);
+    const { response } = await fetchOkWithRetry(url, baseInit, request);
     if (!response.body) {
       throw new LLMProviderError("Response body is null (streaming unsupported)", {
         status: response.status
@@ -281,7 +312,7 @@ function createOpenAIProvider(config) {
       yield finalizeStreamChunk(accumulators, finishReason, usage);
     } catch (err) {
       if (!isAbortLike(err)) throw err;
-      throw classifyAbortError(err, request.signal);
+      throw classifyAbortError(err, request.signal, timeoutMs);
     } finally {
       try {
         await reader.cancel();
@@ -433,6 +464,9 @@ function createProvider(config) {
   }
 }
 
+// src/agent.ts
+import { readResource, subAgentToolName } from "@faapi/faapi";
+
 // src/trace.ts
 function isTracingToolResult(value) {
   return typeof value === "object" && value !== null && value.__trace === true;
@@ -958,7 +992,6 @@ async function* reactLoopStream(input, config) {
 }
 
 // src/agent.ts
-import { readResource, subAgentToolName } from "@faapi/faapi";
 var DEFAULT_MAX_AGENT_DEPTH = 3;
 var DEFAULT_SUBAGENT_INPUT_DESCRIPTION = "\u6D3E\u53D1\u7ED9\u8BE5 agent \u7684\u4EFB\u52A1\u4EA4\u63A5\u5355\uFF08\u81EA\u7136\u8BED\u8A00\uFF09\uFF1A\u5199\u6E05\u4EFB\u52A1\u76EE\u6807\u3001\u5FC5\u8981\u7684\u4E0A\u4E0B\u6587\u4FE1\u606F\u4E0E\u5BF9\u4EA7\u51FA\u7ED3\u679C\u7684\u8981\u6C42";
 function extractSubAgentUserInput(args) {
@@ -984,6 +1017,64 @@ function materializeProvider(external) {
     'options.provider must be an LlmConfig object (with a string "provider" field) or an LLMProvider instance (with complete/stream methods)'
   );
 }
+function resolveModelKey(key, deps, fallbackKey) {
+  const effectiveKey = key ?? fallbackKey;
+  if (effectiveKey === void 0) {
+    throw new AgentError(
+      'No LLM provider resolved: pass options.model (a provider key / "provider/model" / model name from config.agent.llms), options.provider (external provider), or declare model in the agent config'
+    );
+  }
+  const byProviderKey = deps.providers.get(effectiveKey);
+  if (byProviderKey) {
+    const llmConfig = deps.llms[effectiveKey];
+    const firstModel = llmConfig ? Object.keys(llmConfig.models)[0] : void 0;
+    return {
+      provider: byProviderKey,
+      providerName: effectiveKey,
+      model: firstModel ?? fallbackKey
+    };
+  }
+  if (effectiveKey.includes("/")) {
+    const slashIdx = effectiveKey.indexOf("/");
+    const providerName = effectiveKey.slice(0, slashIdx);
+    const modelName = effectiveKey.slice(slashIdx + 1);
+    const provider = deps.providers.get(providerName);
+    if (!provider) {
+      throw new AgentError(
+        `Unknown provider "${providerName}" in model key "${effectiveKey}". Declare it in config.agent.llms, or pass options.provider to use an external provider.`
+      );
+    }
+    const llmConfig = deps.llms[providerName];
+    if (!llmConfig || !llmConfig.models[modelName]) {
+      throw new AgentError(
+        `Model "${modelName}" not found in provider "${providerName}". Declare it in config.agent.llms.${providerName}.models.`
+      );
+    }
+    return { provider, providerName, model: modelName };
+  }
+  const matches = [];
+  for (const [providerName, provider] of deps.providers) {
+    const llmConfig = deps.llms[providerName];
+    if (llmConfig && llmConfig.models[effectiveKey]) {
+      matches.push({ provider, providerName });
+    }
+  }
+  if (matches.length === 1) {
+    return {
+      provider: matches[0].provider,
+      providerName: matches[0].providerName,
+      model: effectiveKey
+    };
+  }
+  if (matches.length > 1) {
+    throw new AgentError(
+      `Model "${effectiveKey}" is ambiguous (found in providers: ${matches.map((m) => m.providerName).join(", ")}). Use "provider/model" to disambiguate.`
+    );
+  }
+  throw new AgentError(
+    `Model "${effectiveKey}" not found in any provider. Declare it in config.agent.llms.*.models, or pass options.provider to use an external provider.`
+  );
+}
 function validateResumeHistory(messages) {
   messages.forEach((message, index) => {
     if (!VALID_MESSAGE_ROLES.has(message.role)) {
@@ -1286,72 +1377,14 @@ var Agent = class _Agent {
     return { provider, model };
   }
   /**
-   * 解析 `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
    *   不存在或歧义）
    */
   resolveModelKey(key, meta) {
-    const effectiveKey = key ?? meta.model;
-    if (effectiveKey === void 0) {
-      throw new AgentError(
-        'No LLM provider resolved: pass options.model (a provider key / "provider/model" / model name from config.agent.llms), options.provider (external provider), or declare model in the agent config'
-      );
-    }
-    const byProviderKey = this.deps.providers.get(effectiveKey);
-    if (byProviderKey) {
-      const llmConfig = this.deps.llms[effectiveKey];
-      const firstModel = llmConfig ? Object.keys(llmConfig.models)[0] : void 0;
-      return { provider: byProviderKey, model: firstModel ?? meta.model };
-    }
-    if (effectiveKey.includes("/")) {
-      const slashIdx = effectiveKey.indexOf("/");
-      const providerName = effectiveKey.slice(0, slashIdx);
-      const modelName = effectiveKey.slice(slashIdx + 1);
-      const provider = this.deps.providers.get(providerName);
-      if (!provider) {
-        throw new AgentError(
-          `Unknown provider "${providerName}" in model key "${effectiveKey}". 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]) {
-        throw new AgentError(
-          `Model "${modelName}" not found in provider "${providerName}". Declare it in config.agent.llms.${providerName}.models.`
-        );
-      }
-      return { provider, model: modelName };
-    }
-    const matches = [];
-    for (const [providerName, provider] of this.deps.providers) {
-      const llmConfig = this.deps.llms[providerName];
-      if (llmConfig && llmConfig.models[effectiveKey]) {
-        matches.push({ provider, providerName });
-      }
-    }
-    if (matches.length === 1) {
-      return { provider: matches[0].provider, model: effectiveKey };
-    }
-    if (matches.length > 1) {
-      throw new AgentError(
-        `Model "${effectiveKey}" is ambiguous (found in providers: ${matches.map((m) => m.providerName).join(", ")}). Use "provider/model" to disambiguate.`
-      );
-    }
-    throw new AgentError(
-      `Model "${effectiveKey}" not found in any provider. Declare it in config.agent.llms.*.models, or pass options.provider to use an external provider.`
-    );
+    return resolveModelKey(key, this.deps, meta.model);
   }
   /**
    * 组装 LLM 可见 tool 列表（OpenAI chat completions 规范形）
@@ -1364,9 +1397,15 @@ var Agent = 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`,
+   *   未声明用默认文案
    */
   async buildToolDefinitions(agentName) {
     const definitions = /* @__PURE__ */ new Map();
@@ -1390,16 +1429,7 @@ var Agent = class _Agent {
         function: {
           name,
           description: subAgent.description,
-          parameters: {
-            type: "object",
-            properties: {
-              input: {
-                type: "string",
-                description: subAgent.inputDescription ?? DEFAULT_SUBAGENT_INPUT_DESCRIPTION
-              }
-            },
-            required: ["input"]
-          }
+          parameters: await this.getSubAgentParameters(subAgent)
         }
       });
     }
@@ -1407,6 +1437,39 @@ var Agent = class _Agent {
     const filtered = this.deps.config?.filterTools?.(defs, this.deps.ctx);
     return filtered ?? defs;
   }
+  /**
+   * 解析 sub-agent 派发工具的 parameters（富 schema / 单字段 input 二选一）
+   *
+   * 富 schema 判定需要完整元数据的 `inputTypeName`（`AgentCore` 不含）——经
+   * `getAgentEntry` 查询；未声明或 `resolveAgentInputSchema` 未接线时返回单字段
+   * `input` schema（历史行为,完全向后兼容）。`inputDescription` 仍从 `AgentCore`
+   * 读取（LLM 可见字段的既定来源,DB skill 同样可声明）。
+   *
+   * @throws {AgentError} 声明了 `inputTypeName` 且 resolver 已接线但解析为
+   *   `undefined`（zod.js 缺失/损坏的产物异常,不静默退回单字段模式）
+   */
+  async getSubAgentParameters(subAgent) {
+    const entry = this.deps.getAgentEntry(subAgent.name);
+    if (!entry?.inputTypeName || !this.deps.resolveAgentInputSchema) {
+      return {
+        type: "object",
+        properties: {
+          input: {
+            type: "string",
+            description: subAgent.inputDescription ?? DEFAULT_SUBAGENT_INPUT_DESCRIPTION
+          }
+        },
+        required: ["input"]
+      };
+    }
+    const schemaRes = await this.deps.resolveAgentInputSchema(entry);
+    if (!schemaRes) {
+      throw new AgentError(
+        `Sub-agent "${subAgent.name}" declares input schema "${entry.inputTypeName}" but its zod.js artifact is missing or broken (run \`faapi build\` / restart \`faapi dev\` to regenerate)`
+      );
+    }
+    return schemaRes.jsonSchema;
+  }
   /**
    * tool 执行路由（由 reactLoop 调用）
    *
@@ -1482,9 +1545,15 @@ var Agent = 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
    *
@@ -1499,12 +1568,27 @@ var Agent = class _Agent {
    * user 消息：args 恰为单字段 `{ input: <string> }`（与显式入参 schema 形状一致）
    * 时直传字符串,其余形状 stringify 兜底（见 `extractSubAgentUserInput`）。
    */
-  async executeSubAgent(subName, args, callCtx, deltaEmitter) {
+  async executeSubAgent(subName, rawArgs, callCtx, deltaEmitter) {
     const newDepth = this.depth + 1;
     const maxDepth = this.deps.config?.maxAgentDepth ?? DEFAULT_MAX_AGENT_DEPTH;
     if (newDepth > maxDepth) {
       throw new AgentRecursionError(maxDepth, newDepth);
     }
+    let args = rawArgs;
+    const entry = this.deps.getAgentEntry(subName);
+    if (entry?.inputTypeName && this.deps.resolveAgentInputSchema) {
+      const schemaRes = await this.deps.resolveAgentInputSchema(entry);
+      if (!schemaRes) {
+        throw new AgentError(
+          `Sub-agent "${subName}" declares input schema "${entry.inputTypeName}" but its zod.js artifact is missing or broken (run \`faapi build\` / restart \`faapi dev\` to regenerate)`
+        );
+      }
+      const result2 = schemaRes.validate(args);
+      if (!result2.ok) {
+        return { error: result2.error };
+      }
+      args = result2.value ?? args;
+    }
     const toolName = subAgentToolName(subName);
     const subAgent = new _Agent(this.deps, newDepth);
     const subMeta = this.deps.getAgent(subName);
@@ -1572,12 +1656,78 @@ var Agent = class _Agent {
   }
 };
 
+// src/lightComplete.ts
+var DEFAULT_LIGHT_TIMEOUT_MS = 6e4;
+function createLightComplete(deps) {
+  const llms = deps.llms;
+  const providers = deps.providers ?? buildProviders(llms);
+  return {
+    async complete(input, options) {
+      const defaultKey = Object.keys(llms)[0];
+      const { provider, providerName, model } = resolveModelKey(
+        options?.model,
+        { providers, llms },
+        defaultKey
+      );
+      const messages = options?.system ? [
+        { role: "system", content: options.system },
+        { role: "user", content: input }
+      ] : [{ role: "user", content: input }];
+      const llmConfig = llms[providerName];
+      const configTimeout = typeof llmConfig?.timeoutMs === "number" ? llmConfig.timeoutMs : void 0;
+      const timeoutMs = options?.timeoutMs ?? configTimeout ?? DEFAULT_LIGHT_TIMEOUT_MS;
+      try {
+        const response = await provider.complete({
+          messages,
+          model,
+          ...options?.temperature !== void 0 ? { temperature: options.temperature } : {},
+          ...options?.maxTokens !== void 0 ? { maxTokens: options.maxTokens } : {},
+          ...options?.signal !== void 0 ? { signal: options.signal } : {},
+          timeoutMs,
+          ...options?.maxRetries !== void 0 ? { maxRetries: options.maxRetries } : {}
+        });
+        return response.message.content ?? "";
+      } catch (err) {
+        if (err instanceof AgentAbortError) throw err;
+        if (!(err instanceof LLMProviderError)) throw err;
+        return handleFailure(err, options);
+      }
+    }
+  };
+}
+function buildProviders(llms) {
+  const providers = /* @__PURE__ */ new Map();
+  for (const [name, llmConfig] of Object.entries(llms)) {
+    providers.set(name, createProvider(llmConfig));
+  }
+  return providers;
+}
+function handleFailure(err, options) {
+  const { onFailure, fallback } = options ?? {};
+  const attempts = err.attempts ?? 1;
+  if (onFailure) {
+    try {
+      onFailure(err, { attempts });
+    } catch {
+    }
+  }
+  if (fallback !== void 0) {
+    if (!onFailure) {
+      console.warn(
+        `[faapi/agent] llm.complete fallback engaged after ${attempts} attempt(s): ${err.message}`
+      );
+    }
+    return Promise.resolve(fallback);
+  }
+  return Promise.reject(err);
+}
+
 // src/toolSchemaResolver.ts
 import { statSync } from "fs";
 import { z } from "zod";
 import { loadToolSchema, getToolSchemaPath } from "@faapi/faapi";
-async function resolveToolSchemaImpl(tool, rootDir) {
-  const schemaMod = await loadToolSchema(tool, rootDir);
+async function resolveToolSchemaImpl(ref, rootDir) {
+  const schemaMod = await loadToolSchema(ref, rootDir);
   if (!schemaMod) return void 0;
   const schema = schemaMod.schema;
   return {
@@ -1594,9 +1744,9 @@ async function resolveToolSchemaImpl(tool, rootDir) {
 function createToolSchemaResolver(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const schemaCache = /* @__PURE__ */ new Map();
-  return (tool) => {
-    const zodPath = getToolSchemaPath(tool, rootDir);
-    const key = `${zodPath}#${tool.inputTypeName ?? ""}`;
+  return (ref) => {
+    const zodPath = getToolSchemaPath(ref, rootDir);
+    const key = `${zodPath}#${ref.inputTypeName ?? ""}`;
     let mtimeMs = -1;
     try {
       mtimeMs = statSync(zodPath).mtimeMs;
@@ -1606,7 +1756,7 @@ function createToolSchemaResolver(options) {
     if (hit && hit.mtimeMs === mtimeMs) {
       return hit.resolution;
     }
-    const resolution = resolveToolSchemaImpl(tool, rootDir);
+    const resolution = resolveToolSchemaImpl(ref, rootDir);
     schemaCache.set(key, { mtimeMs, resolution });
     return resolution;
   };
@@ -1641,6 +1791,7 @@ var agentPlugin = {
       }
       providers.set(name, createProvider(llmConfig));
     }
+    ctx.registries.llm.register(createLightComplete({ llms, providers }));
     const runtimeConfig = {
       maxTurns: agentConfig?.maxTurns,
       maxAgentDepth: agentConfig?.maxAgentDepth,
@@ -1651,7 +1802,7 @@ var agentPlugin = {
       filterTools: agentConfig?.filterTools
     };
     const rootDir = ctx.rootDir;
-    const resolveToolSchema = createToolSchemaResolver({ rootDir });
+    const resolveSchema = createToolSchemaResolver({ rootDir });
     ctx.registries.agentHandle.register((ctx2) => {
       return new Agent({
         providers,
@@ -1670,8 +1821,9 @@ var agentPlugin = {
         resolveSubAgents: registries.agent.resolveSubAgents,
         // 加载器包装：注入 rootDir 用于 dev 按需编译模式
         loadToolModule: (filePath, functionName) => loadToolModule(filePath, functionName, rootDir),
-        // tool schema 解析（zod.js → JSON Schema + safeParse 校验）
-        resolveToolSchema
+        // schema 解析（zod.js → JSON Schema + safeParse 校验）——tool 与 agent 入参共用
+        resolveToolSchema: resolveSchema,
+        resolveAgentInputSchema: resolveSchema
       });
     });
     console.log(
@@ -1687,7 +1839,9 @@ export {
   AgentRecursionError,
   AgentToolTimeoutError,
   LLMProviderError,
+  LLMTimeoutError,
   ReactLoopError,
+  createLightComplete,
   createOpenAIProvider,
   createProvider,
   createToolSchemaResolver,