@faapi/agent 0.0.0-canary.0 → 3.1.0

package/dist/index.js

@@ -0,0 +1,894 @@
+// 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 LLMProviderError = class extends Error {
+  /** HTTP 状态码（网络错误 / JSON 解析错误为 undefined） */
+  status;
+  /** 响应体摘要（前 500 字符,便于诊断） */
+  body;
+  constructor(message, options) {
+    super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "LLMProviderError";
+    this.status = options?.status;
+    this.body = options?.body;
+  }
+};
+function createOpenAIProvider(config) {
+  const baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const apiKey = config.apiKey;
+  function buildRequestBody(request) {
+    const modelName = request.model ?? Object.keys(config.models)[0];
+    const modelConfig = modelName ? config.models[modelName] : void 0;
+    const body = {
+      model: modelName,
+      messages: request.messages.map(toOpenAIMessage)
+    };
+    if (request.tools && request.tools.length > 0) {
+      body.tools = request.tools.map(toOpenAITool);
+    }
+    const mergedConfig = {};
+    for (const key of Object.keys(config)) {
+      if (RESERVED_CONFIG_KEYS.has(key)) continue;
+      const value = config[key];
+      if (value !== void 0) {
+        mergedConfig[key] = value;
+      }
+    }
+    if (modelConfig) {
+      for (const key of Object.keys(modelConfig)) {
+        if (RESERVED_CONFIG_KEYS.has(key)) continue;
+        const value = modelConfig[key];
+        if (value !== void 0) {
+          mergedConfig[key] = value;
+        }
+      }
+    }
+    for (const key of Object.keys(mergedConfig)) {
+      const value = mergedConfig[key];
+      if (value !== void 0 && !(key in body)) {
+        body[key] = value;
+      }
+    }
+    if (request.temperature !== void 0) body.temperature = request.temperature;
+    if (request.maxTokens !== void 0) body.max_tokens = request.maxTokens;
+    return body;
+  }
+  function buildHeaders() {
+    const headers = { "Content-Type": "application/json" };
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+    return headers;
+  }
+  async function safeFetch(url, init) {
+    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 });
+    }
+  }
+  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
+    });
+  }
+  async function complete(request) {
+    const url = `${baseURL}/chat/completions`;
+    const body = buildRequestBody(request);
+    const init = {
+      method: "POST",
+      headers: buildHeaders(),
+      body: JSON.stringify(body)
+    };
+    const response = await safeFetch(url, init);
+    await ensureOk(response);
+    const bodyText = await response.text();
+    let json;
+    try {
+      json = JSON.parse(bodyText);
+    } catch {
+      const excerpt = bodyText.slice(0, 500);
+      throw new LLMProviderError(`Invalid JSON response: ${excerpt}`, {
+        status: response.status,
+        body: excerpt
+      });
+    }
+    const choice = json.choices?.[0];
+    const msg = choice?.message;
+    if (!choice || !msg) {
+      const excerpt = bodyText.slice(0, 500);
+      throw new LLMProviderError("Empty choices in response", {
+        status: response.status,
+        body: excerpt
+      });
+    }
+    const content = msg.content ?? "";
+    const toolCalls = parseToolCalls(msg.tool_calls, bodyText, response.status);
+    return {
+      message: {
+        role: "assistant",
+        content,
+        toolCalls
+      },
+      stopReason: mapStopReason(choice.finish_reason ?? void 0),
+      usage: mapUsage(json.usage)
+    };
+  }
+  async function* stream(request) {
+    const url = `${baseURL}/chat/completions`;
+    const body = buildRequestBody(request);
+    body.stream = true;
+    const init = {
+      method: "POST",
+      headers: buildHeaders(),
+      body: JSON.stringify(body)
+    };
+    const response = await safeFetch(url, init);
+    await ensureOk(response);
+    if (!response.body) {
+      throw new LLMProviderError("Response body is null (streaming unsupported)", {
+        status: response.status
+      });
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const accumulators = /* @__PURE__ */ new Map();
+    let finishReason;
+    let usage;
+    try {
+      while (true) {
+        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);
+          const data = extractSSEData(eventStr);
+          if (data === null) continue;
+          if (data === "[DONE]") {
+            yield finalizeStreamChunk(accumulators, finishReason, usage);
+            return;
+          }
+          let chunk;
+          try {
+            chunk = JSON.parse(data);
+          } catch {
+            const excerpt = data.slice(0, 500);
+            throw new LLMProviderError(`Invalid SSE chunk: ${excerpt}`, {
+              status: response.status,
+              body: excerpt
+            });
+          }
+          const delta = chunk.choices?.[0]?.delta;
+          if (delta) {
+            if (typeof delta.content === "string" && delta.content.length > 0) {
+              yield { deltaContent: delta.content };
+            }
+            if (delta.tool_calls) {
+              for (const tc of delta.tool_calls) {
+                accumulateToolCall(accumulators, tc);
+              }
+            }
+          }
+          const fr = chunk.choices?.[0]?.finish_reason;
+          if (fr) finishReason = mapStopReason(fr);
+          if (chunk.usage) usage = mapUsage(chunk.usage);
+        }
+      }
+      yield finalizeStreamChunk(accumulators, finishReason, usage);
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  return { complete, stream };
+}
+function toOpenAIMessage(msg) {
+  const out = {
+    role: msg.role,
+    content: msg.content
+  };
+  if (msg.toolCallId !== void 0) out.tool_call_id = msg.toolCallId;
+  if (msg.toolCalls !== void 0 && msg.toolCalls.length > 0) {
+    out.tool_calls = msg.toolCalls.map((tc) => ({
+      id: tc.id,
+      type: "function",
+      function: { name: tc.name, arguments: JSON.stringify(tc.arguments) }
+    }));
+  }
+  return out;
+}
+function toOpenAITool(tool) {
+  return {
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.input
+    }
+  };
+}
+function parseToolCalls(toolCalls, bodyText, status) {
+  if (!toolCalls || toolCalls.length === 0) return void 0;
+  const result = [];
+  for (let i = 0; i < toolCalls.length; i++) {
+    const tc = toolCalls[i];
+    const argsStr = tc?.function?.arguments ?? "{}";
+    let args;
+    try {
+      args = JSON.parse(argsStr);
+    } catch {
+      const excerpt = argsStr.slice(0, 500);
+      throw new LLMProviderError(`Invalid tool arguments JSON: ${excerpt}`, {
+        status,
+        body: bodyText.slice(0, 500)
+      });
+    }
+    result.push({
+      id: tc?.id ?? `call_${i}`,
+      name: tc?.function?.name ?? "",
+      arguments: args
+    });
+  }
+  return result;
+}
+function mapStopReason(fr) {
+  switch (fr) {
+    case "stop":
+      return "stop";
+    case "tool_calls":
+      return "tool_calls";
+    case "length":
+      return "length";
+    case "content_filter":
+      return "content_filter";
+    default:
+      return "other";
+  }
+}
+function mapUsage(u) {
+  if (!u) return void 0;
+  return {
+    promptTokens: u.prompt_tokens ?? 0,
+    completionTokens: u.completion_tokens ?? 0,
+    totalTokens: u.total_tokens ?? 0
+  };
+}
+function extractSSEData(event) {
+  const dataLines = [];
+  for (const line of event.split("\n")) {
+    if (line === "" || line.startsWith(":")) continue;
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).replace(/^ /, ""));
+    }
+  }
+  if (dataLines.length === 0) return null;
+  return dataLines.join("\n");
+}
+function accumulateToolCall(accumulators, tc) {
+  const idx = tc.index ?? 0;
+  const acc = accumulators.get(idx) ?? { argsString: "" };
+  if (tc.id) acc.id = tc.id;
+  if (tc.function?.name) acc.name = tc.function.name;
+  if (tc.function?.arguments) acc.argsString += tc.function.arguments;
+  accumulators.set(idx, acc);
+}
+function finalizeStreamChunk(accumulators, finishReason, usage) {
+  const toolCalls = [];
+  if (accumulators.size > 0) {
+    const indices = Array.from(accumulators.keys()).sort((a, b) => a - b);
+    for (const idx of indices) {
+      const acc = accumulators.get(idx);
+      if (!acc.id || !acc.name) continue;
+      let args;
+      try {
+        args = acc.argsString ? JSON.parse(acc.argsString) : {};
+      } catch {
+        const excerpt = acc.argsString.slice(0, 500);
+        throw new LLMProviderError(`Invalid tool arguments JSON: ${excerpt}`, {
+          body: excerpt
+        });
+      }
+      toolCalls.push({
+        id: acc.id,
+        name: acc.name,
+        arguments: args
+      });
+    }
+  }
+  const chunk = {};
+  if (toolCalls.length > 0) chunk.toolCalls = toolCalls;
+  if (finishReason) chunk.finishReason = finishReason;
+  if (usage) chunk.usage = usage;
+  return chunk;
+}
+
+// src/provider.ts
+function createProvider(config) {
+  switch (config.provider) {
+    case "openai":
+      return createOpenAIProvider(config);
+    default:
+      throw new Error(`Unsupported LLM provider: ${String(config.provider)}`);
+  }
+}
+
+// src/reactLoop.ts
+var ReactLoopError = class extends Error {
+  /** 配置的 maxTurns 值 */
+  maxTurns;
+  constructor(message, maxTurns) {
+    super(message);
+    this.name = "ReactLoopError";
+    this.maxTurns = maxTurns;
+  }
+};
+var DEFAULT_MAX_TURNS = 10;
+function stringifyResult(result) {
+  if (typeof result === "string") return result;
+  if (result === void 0) return "";
+  return JSON.stringify(result);
+}
+function stringifyError(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+function accumulateUsage(a, b) {
+  if (!a) return { ...b };
+  return {
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    totalTokens: a.totalTokens + b.totalTokens
+  };
+}
+function buildInitialMessages(input, systemPrompt) {
+  const messages = [];
+  if (systemPrompt) {
+    messages.push({ role: "system", content: systemPrompt });
+  }
+  messages.push({ role: "user", content: input });
+  return messages;
+}
+function buildRequestExtras(config) {
+  return {
+    tools: config.tools,
+    model: config.model,
+    temperature: config.temperature,
+    maxTokens: config.maxTokens
+  };
+}
+async function reactLoop(input, config) {
+  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) {
+    turns++;
+    const response = await config.provider.complete({
+      messages: [...messages],
+      ...extras
+    });
+    if (response.usage) {
+      totalUsage = accumulateUsage(totalUsage, response.usage);
+    }
+    messages.push(response.message);
+    if (response.stopReason !== "tool_calls" || !response.message.toolCalls) {
+      return {
+        content: response.message.content,
+        messages,
+        turns,
+        stopReason: response.stopReason,
+        usage: totalUsage
+      };
+    }
+    for (const toolCall of response.message.toolCalls) {
+      let resultStr;
+      try {
+        const result = await config.executeTool(toolCall.name, toolCall.arguments);
+        resultStr = stringifyResult(result);
+      } catch (err) {
+        resultStr = stringifyError(err);
+      }
+      messages.push({
+        role: "tool",
+        content: resultStr,
+        toolCallId: toolCall.id
+      });
+    }
+  }
+  throw new ReactLoopError(
+    `Max turns (${maxTurns}) exceeded \u2014 agent did not converge to a final answer`,
+    maxTurns
+  );
+}
+async function* reactLoopStream(input, config) {
+  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) {
+    turns++;
+    let turnContent = "";
+    let toolCalls;
+    let finishReason;
+    for await (const chunk of config.provider.stream({
+      messages: [...messages],
+      ...extras
+    })) {
+      if (typeof chunk.deltaContent === "string" && chunk.deltaContent.length > 0) {
+        turnContent += chunk.deltaContent;
+        yield { deltaContent: chunk.deltaContent };
+      }
+      if (chunk.toolCalls && chunk.toolCalls.length > 0) {
+        toolCalls = chunk.toolCalls;
+      }
+      if (chunk.finishReason) {
+        finishReason = chunk.finishReason;
+      }
+      if (chunk.usage) {
+        totalUsage = accumulateUsage(totalUsage, chunk.usage);
+      }
+    }
+    const assistantMessage = {
+      role: "assistant",
+      content: turnContent
+    };
+    if (toolCalls) {
+      assistantMessage.toolCalls = toolCalls;
+    }
+    messages.push(assistantMessage);
+    if (finishReason !== "tool_calls" || !toolCalls) {
+      yield {
+        done: {
+          content: turnContent,
+          turns,
+          stopReason: finishReason ?? "other",
+          usage: totalUsage
+        }
+      };
+      return;
+    }
+    for (const toolCall of toolCalls) {
+      yield { toolCall: { name: toolCall.name, arguments: toolCall.arguments } };
+      let resultStr;
+      try {
+        const result = await config.executeTool(toolCall.name, toolCall.arguments);
+        resultStr = stringifyResult(result);
+      } catch (err) {
+        resultStr = stringifyError(err);
+      }
+      yield { toolResult: { name: toolCall.name, result: resultStr } };
+      messages.push({
+        role: "tool",
+        content: resultStr,
+        toolCallId: toolCall.id
+      });
+    }
+  }
+  throw new ReactLoopError(
+    `Max turns (${maxTurns}) exceeded \u2014 agent did not converge to a final answer`,
+    maxTurns
+  );
+}
+
+// src/agent.ts
+var DEFAULT_MAX_AGENT_DEPTH = 3;
+var AgentError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AgentError";
+  }
+};
+var AgentRecursionError = class extends AgentError {
+  /** 配置的 maxAgentDepth 值 */
+  maxDepth;
+  /** 当前递归深度（超出 maxDepth） */
+  currentDepth;
+  constructor(maxDepth, currentDepth) {
+    super(
+      `Agent recursion depth exceeded: current depth ${currentDepth} > maxAgentDepth ${maxDepth}`
+    );
+    this.name = "AgentRecursionError";
+    this.maxDepth = maxDepth;
+    this.currentDepth = currentDepth;
+  }
+};
+var Agent = class _Agent {
+  deps;
+  /** 当前递归深度（根 agent 为 1，sub-agent 递增） */
+  depth;
+  /**
+   * tool schema 解析缓存（按 tool.name 缓存，含 undefined 结果）
+   *
+   * `buildToolDefinitions` 组装 LLM tool 列表时解析一次 schema（取 jsonSchema），
+   * `executeTool` 执行前校验时复用同一份 schema（取 validate）——
+   * 避免每次 tool 执行都重新 `loadToolSchema` + `z.toJSONSchema`。
+   *
+   * 实例级缓存：sub-agent 各有独立 cache（tool 集合可能不同）。
+   */
+  schemaCache = /* @__PURE__ */ new Map();
+  /**
+   * @param deps 运行时依赖（访问器 + providers Map + defaultProvider + llms + config）
+   * @param depth 递归深度（默认 1 = 根 agent；sub-agent 递归时传入 depth+1）
+   */
+  constructor(deps, depth = 1) {
+    this.deps = deps;
+    this.depth = depth;
+  }
+  /**
+   * 非流式执行——组装 config 调 [reactLoop](./reactLoop.md)
+   *
+   * @param input 用户输入
+   * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
+   *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
+   * @returns 最终结果（content + messages + turns + stopReason + usage）
+   * @throws {AgentError} agent 未注册
+   * @throws {ReactLoopError} 超出 maxTurns
+   * @throws {Error} provider.complete 抛错时立即传播
+   */
+  async run(input, options) {
+    const config = await this.buildLoopConfig(options);
+    return reactLoop(input, config);
+  }
+  /**
+   * 流式执行——组装 config 调 [reactLoopStream](./reactLoop.md)
+   *
+   * @param input 用户输入
+   * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
+   *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
+   * @yields 流式 chunk（deltaContent / toolCall / toolResult / done）
+   * @throws {AgentError} agent 未注册
+   * @throws {ReactLoopError} 超出 maxTurns
+   * @throws {Error} provider.stream 抛错时立即传播
+   */
+  async *stream(input, options) {
+    const config = await this.buildLoopConfig(options);
+    yield* reactLoopStream(input, config);
+  }
+  /**
+   * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
+   *
+   * 与 [agentRegistry.asTool](../../faapi/src/injection/agentRegistry.md) 同构——
+   * Agent 类自带此方法便于在注入器场景直接调用（不必再过注册表）。
+   *
+   * @returns `AgentToolDescriptor` 或 `undefined`（agent 未注册）
+   */
+  asTool() {
+    const meta = this.deps.getAgent(this.deps.agentName);
+    if (!meta) return void 0;
+    return {
+      kind: "agent",
+      name: `agent.${meta.name}`,
+      agentName: meta.name,
+      description: meta.description,
+      metadata: meta
+    };
+  }
+  // ─── 内部方法 ────────────────────────────────────────
+  /**
+   * 查询 tool schema（带缓存）
+   *
+   * `buildToolDefinitions` 与 `executeTool` 共用此方法——
+   * 首次调用触发 `deps.resolveToolSchema`（加载 zod.js + 生成 JSON Schema），
+   * 后续命中缓存直接返回（含 `undefined` 结果，用 `has` 区分未解析 vs 解析为空）。
+   *
+   * `deps.resolveToolSchema` 未提供时直接返回 `undefined`，不写缓存。
+   */
+  async getToolSchema(tool) {
+    if (!this.deps.resolveToolSchema) return void 0;
+    if (this.schemaCache.has(tool.name)) {
+      return this.schemaCache.get(tool.name);
+    }
+    const resolved = await this.deps.resolveToolSchema(tool);
+    this.schemaCache.set(tool.name, resolved);
+    return resolved;
+  }
+  /**
+   * 组装 ReactLoopConfig
+   *
+   * 1. 查 agent 元数据（未注册抛 AgentError）——用 `getAgent` 拿 AgentCore
+   *    (LLM-facing 字段:systemPrompt / model / maxTurns)
+   * 2. buildToolDefinitions 组装 tool 列表
+   * 3. 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 解析规则」。
+   */
+  async buildLoopConfig(options) {
+    const meta = this.deps.getAgent(this.deps.agentName);
+    if (!meta) {
+      throw new AgentError(`Agent "${this.deps.agentName}" is not registered`);
+    }
+    const tools = await this.buildToolDefinitions();
+    const { provider, model } = this.resolveModelKey(options?.model, meta);
+    return {
+      provider,
+      systemPrompt: meta.systemPrompt,
+      model,
+      temperature: options?.temperature,
+      maxTokens: options?.maxTokens,
+      maxTurns: meta.maxTurns ?? this.deps.config?.maxTurns,
+      tools,
+      executeTool: async (name, args) => this.executeTool(name, args)
+    };
+  }
+  /**
+   * 解析 `options.model` 字符串 key → provider + model
+   *
+   * 规则见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」：
+   * 1. `undefined` → `deps.defaultProvider` + `meta.model`
+   * 2. 精确匹配 `deps.providers` 的 key → 该 provider + 其 `models` 第一个 key
+   * 3. 含 `/` → `provider/model` 形式,`deps.providers.get(provider)` + 该 model
+   *    （要求该 model 在 `deps.llms[provider].models` 里）
+   * 4. 不含 `/` 且非 provider key → 在所有 provider 的 `models` 里按 model 名查找
+   *    - 唯一 → 该 provider + 该 model
+   *    - 多个 → 抛 `AgentError`（要求用 `provider/model` 消歧）
+   *    - 无 → 抛 `AgentError`
+   *
+   * @throws {AgentError} key 解析失败（provider/model 不存在或歧义）
+   */
+  resolveModelKey(key, meta) {
+    if (key === void 0) {
+      return { provider: this.deps.defaultProvider, model: meta.model };
+    }
+    const byProviderKey = this.deps.providers.get(key);
+    if (byProviderKey) {
+      const llmConfig = this.deps.llms[key];
+      const firstModel = llmConfig ? Object.keys(llmConfig.models)[0] : void 0;
+      return { provider: byProviderKey, model: firstModel ?? meta.model };
+    }
+    if (key.includes("/")) {
+      const slashIdx = key.indexOf("/");
+      const providerName = key.slice(0, slashIdx);
+      const modelName = key.slice(slashIdx + 1);
+      const provider = this.deps.providers.get(providerName);
+      if (!provider) {
+        throw new AgentError(`Unknown provider "${providerName}" in model key "${key}"`);
+      }
+      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[key]) {
+        matches.push({ provider, providerName });
+      }
+    }
+    if (matches.length === 1) {
+      return { provider: matches[0].provider, model: key };
+    }
+    if (matches.length > 1) {
+      throw new AgentError(
+        `Model "${key}" is ambiguous (found in providers: ${matches.map((m) => m.providerName).join(", ")}). Use "provider/model" to disambiguate.`
+      );
+    }
+    throw new AgentError(
+      `Model "${key}" not found in any provider. Declare it in config.agent.llms.*.models.`
+    );
+  }
+  /**
+   * 组装 LLM 可见 tool 列表
+   *
+   * 合并两个来源（按 `name` 去重，先入者保留）：
+   * 1. **resolveAgentTools** —— agent 显式声明的 `tools` 引用
+   * 2. **sub-agent** —— `resolveSubAgents` 每个包装为 `agent.<name>`
+   *
+   * 每个常规 tool 的 `input`：
+   * - `resolveToolSchema` 提供 → 用其 `jsonSchema`
+   * - 未提供 / tool 无 `inputTypeName` → 自由 schema `{ type: 'object' }`
+   *
+   * sub-agent 的 `input` 始终为 `{ type: 'object' }`（agent 参数开放）。
+   */
+  async buildToolDefinitions() {
+    const definitions = /* @__PURE__ */ new Map();
+    for (const tool of this.deps.resolveAgentTools(this.deps.agentName)) {
+      if (definitions.has(tool.name)) continue;
+      const schemaRes = await this.getToolSchema(tool);
+      definitions.set(tool.name, {
+        name: tool.name,
+        description: tool.description,
+        input: schemaRes?.jsonSchema ?? { type: "object" }
+      });
+    }
+    for (const subAgent of this.deps.resolveSubAgents(this.deps.agentName)) {
+      const name = `agent.${subAgent.name}`;
+      if (definitions.has(name)) continue;
+      definitions.set(name, {
+        name,
+        description: subAgent.description,
+        input: { type: "object" }
+      });
+    }
+    return Array.from(definitions.values());
+  }
+  /**
+   * tool 执行路由（由 reactLoop 调用）
+   *
+   * - `agent.` 前缀 → {@link executeSubAgent} 递归
+   * - 常规 tool → `loadToolModule` 加载 handler + 可选 input 校验 → 调用
+   *
+   * **常规 tool 校验失败**：不抛错，返回 `{ error }` 对象——reactLoop stringify 后
+   * 作为 tool 结果回传 LLM，LLM 可据此修正参数重试。
+   *
+   * **tool 未找到 / 加载失败**：抛错，被 reactLoop catch 后同样回传 LLM。
+   */
+  async executeTool(name, args) {
+    if (name.startsWith("agent.")) {
+      return this.executeSubAgent(name.slice(6), args);
+    }
+    const tool = this.deps.getTool(name);
+    if (!tool) {
+      throw new Error(`Tool "${name}" not found`);
+    }
+    const schemaRes = await this.getToolSchema(tool);
+    let callArgs = args;
+    if (schemaRes) {
+      const result = schemaRes.validate(args);
+      if (!result.ok) {
+        return { error: result.error };
+      }
+      callArgs = result.value ?? args;
+    }
+    const mod = await this.deps.loadToolModule(tool.filePath, tool.functionName);
+    return await mod.handler(callArgs);
+  }
+  /**
+   * sub-agent 递归执行
+   *
+   * 1. `maxAgentDepth` 防护——超限抛 {@link AgentRecursionError}
+   * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`
+   * 3. 无 `run` 时调 `subAgent.run(JSON.stringify(args))` 走默认 reactLoop
+   *
+   * 自定义 run 接收原始 args 对象；默认 reactLoop 接收 stringify 后的 args
+   * 作为 user 消息（agent-as-tool input 为开放式 JSON）。
+   *
+   * 加载 handler.js 用 `getAgentEntry`(返回 AgentMetadata,含 filePath/hasRun),
+   * 而非 `getAgent`(返回 AgentCore,无代码加载细节)。DB skill 无文件,
+   * `getAgentEntry` 返回 `undefined`,走默认 reactLoop。
+   */
+  async executeSubAgent(subName, args) {
+    const newDepth = this.depth + 1;
+    const maxDepth = this.deps.config?.maxAgentDepth ?? DEFAULT_MAX_AGENT_DEPTH;
+    if (newDepth > maxDepth) {
+      throw new AgentRecursionError(maxDepth, newDepth);
+    }
+    const subDeps = { ...this.deps, agentName: subName };
+    const subAgent = new _Agent(subDeps, newDepth);
+    const entry = this.deps.getAgentEntry(subName);
+    if (entry?.hasRun) {
+      const mod = await this.deps.loadAgentModule(entry.filePath, entry.hasRun);
+      if (mod.run) {
+        return await mod.run(args);
+      }
+    }
+    const result = await subAgent.run(typeof args === "string" ? args : JSON.stringify(args));
+    return result.content;
+  }
+};
+
+// src/plugin.ts
+import {
+  registerAgentHandleFactory,
+  getAgent,
+  getAgentEntry,
+  getTool,
+  resolveAgentTools,
+  resolveSubAgents,
+  loadAgentModule,
+  loadToolModule,
+  loadToolSchema
+} from "@faapi/faapi";
+import { z } from "zod";
+async function resolveToolSchemaImpl(tool, rootDir) {
+  const schemaMod = await loadToolSchema(tool, rootDir);
+  if (!schemaMod) return void 0;
+  const schema = schemaMod.schema;
+  return {
+    jsonSchema: z.toJSONSchema(schema),
+    validate: (input) => {
+      const result = schema.safeParse(input);
+      if (result.success) {
+        return { ok: true, value: result.data };
+      }
+      return { ok: false, error: result.error.message };
+    }
+  };
+}
+function readAgentConfig(ctx) {
+  const raw = ctx.config?.agent;
+  if (raw === void 0 || raw === null) return void 0;
+  return raw;
+}
+var agentPlugin = {
+  name: "@faapi/agent",
+  setup(ctx) {
+    const agentConfig = readAgentConfig(ctx);
+    if (!agentConfig?.llms) {
+      console.warn(
+        "! @faapi/agent: config.agent.llms not configured, agent parameter injection disabled"
+      );
+      return;
+    }
+    if (!agentConfig.defaultAgent) {
+      console.warn(
+        "! @faapi/agent: config.agent.defaultAgent not configured, agent parameter injection disabled"
+      );
+      return;
+    }
+    const llms = agentConfig.llms;
+    const providers = /* @__PURE__ */ new Map();
+    for (const [name, llmConfig] of Object.entries(llms)) {
+      providers.set(name, createProvider(llmConfig));
+    }
+    const defaultLlm = agentConfig.defaultLlm ?? Object.keys(llms)[0];
+    const defaultProvider = providers.get(defaultLlm);
+    if (!defaultProvider) {
+      console.warn(
+        `! @faapi/agent: config.agent.defaultLlm "${defaultLlm}" not found in llms, agent parameter injection disabled`
+      );
+      return;
+    }
+    const runtimeConfig = {
+      maxTurns: agentConfig.maxTurns,
+      maxAgentDepth: agentConfig.maxAgentDepth
+    };
+    const rootDir = ctx.rootDir;
+    const defaultAgent = agentConfig.defaultAgent;
+    const resolveToolSchema = (tool) => resolveToolSchemaImpl(tool, rootDir);
+    registerAgentHandleFactory(() => {
+      return new Agent({
+        providers,
+        defaultProvider,
+        llms,
+        defaultLlm,
+        agentName: defaultAgent,
+        rootDir,
+        config: runtimeConfig,
+        // 注册表/加载器访问器——从 @faapi/faapi import 的单例模块
+        // createAppBase 启动时已水合 agentRegistry / toolRegistry
+        // getAgent 返回 AgentCore(LLM-facing);getAgentEntry 返回 AgentMetadata(含 filePath/hasRun,供加载 handler.js)
+        getAgent,
+        getAgentEntry,
+        getTool,
+        resolveAgentTools,
+        resolveSubAgents,
+        // 加载器包装：注入 rootDir 用于 dev 按需编译模式
+        loadToolModule: (filePath, functionName) => loadToolModule(filePath, functionName, rootDir),
+        loadAgentModule: (filePath, hasRun) => loadAgentModule(filePath, hasRun, rootDir),
+        // tool schema 解析（zod.js → JSON Schema + safeParse 校验）
+        resolveToolSchema
+      });
+    });
+    console.log(
+      `- @faapi/agent: default agent "${defaultAgent}" (provider: ${defaultLlm}) available via agent parameter injection`
+    );
+  }
+};
+var plugin_default = agentPlugin;
+export {
+  Agent,
+  AgentError,
+  AgentRecursionError,
+  LLMProviderError,
+  ReactLoopError,
+  createOpenAIProvider,
+  createProvider,
+  plugin_default as default,
+  reactLoop,
+  reactLoopStream
+};
+//# sourceMappingURL=index.js.map