@faapi/faapi 6.29.0 → 6.31.0

package/dist/{contextTypes-DhagvRH_.d.ts → contextTypes-BKQsSVMv.d.ts}

@@ -130,6 +130,15 @@ interface AgentCore {
 interface AgentMetadata extends AgentCore {
     /** 源码相对路径(从 `pathMeta` 透传)——声明文件定位与清单可观测性用 */
     filePath: string;
+    /**
+     * 派发入参 schema 声明(handler.ts 顶层 `interface Input` / `type Input` 检测)
+     *
+     * 声明时为 `'Input'`——[generateAgentArtifacts](../cli/generateAgentArtifacts.md)
+     * 据此生成 agent 的 zod.js,`@faapi/agent` 派发该 agent 时用富 JSON Schema 替代
+     * 默认单字段 `input` 交接单并在执行前校验;未声明为 `undefined`,派发行为不变
+     * (完全向后兼容)。DB-driven skill 无源文件,恒为 `undefined`。
+     */
+    inputTypeName?: string;
 }
 /**
  * 路径推导的 agent 元数据(由 [scanAgents](../agents/scanAgents.ts) 计算)
@@ -1159,4 +1168,4 @@ interface FaapiContext {
     deleteCookie(name: string): void;
 }
 
-export { type AppRegistries as A, type TaskDriverProcess as B, type CreateLoggerOptions as C, type TaskDriverRecord as D, type TaskFailedInfo as E, type FaapiContext as F, type TaskJob as G, type TaskJobStatus as H, type TaskMetadata as I, type TaskModule as J, type TaskRegistriesSnapshot as K, type LogConfig as L, type TaskRegistriesView as M, type ToolCore as N, type ToolPathMeta as O, type ToolRegistry as P, createAppRegistries as Q, createTaskRegistriesView as R, type SkillRegistry as S, type TaskClient as T, createTaskRegistry as U, type TaskFailedHandler as a, type TaskQueueDeps as b, type TaskQueue as c, type TaskDriver as d, type TaskRegistry as e, type TaskManifest as f, type ToolMetadata as g, type AgentCore as h, type AgentMetadata as i, type Logger as j, type AgentHandleFactory as k, type AgentHandleStore as l, type AgentPathMeta as m, type AgentRegistry as n, type AgentToolDescriptor as o, type FaapiContextConfig as p, type FaapiTaskMeta as q, type FailOptions as r, type LogEntry as s, type LogLevel as t, type LogSink as u, type SseEvent as v, type SseOptions as w, type SseWriter as x, type TaskContext as y, type TaskDriverJob as z };
+export { type AppRegistries as A, type TaskDriverProcess as B, type CreateLoggerOptions as C, type TaskDriverRecord as D, type TaskFailedInfo as E, type FaapiContext as F, type TaskJob as G, type TaskJobStatus as H, type TaskMetadata as I, type TaskModule as J, type TaskRegistriesSnapshot as K, type LogConfig as L, type TaskRegistriesView as M, type ToolCore as N, type ToolPathMeta as O, type ToolRegistry as P, createAppRegistries as Q, createTaskRegistriesView as R, type SkillRegistry as S, type TaskClient as T, createTaskRegistry as U, type TaskFailedHandler as a, type TaskQueueDeps as b, type TaskQueue as c, type TaskDriver as d, type TaskRegistry as e, type TaskManifest as f, type AgentCore as g, type AgentMetadata as h, type ToolMetadata as i, type Logger as j, type AgentHandleFactory as k, type AgentHandleStore as l, type AgentPathMeta as m, type AgentRegistry as n, type AgentToolDescriptor as o, type FaapiContextConfig as p, type FaapiTaskMeta as q, type FailOptions as r, type LogEntry as s, type LogLevel as t, type LogSink as u, type SseEvent as v, type SseOptions as w, type SseWriter as x, type TaskContext as y, type TaskDriverJob as z };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { A as AppRegistries, F as FaapiContext, T as TaskClient, L as LogConfig, a as TaskFailedHandler, b as TaskQueueDeps, c as TaskQueue, d as TaskDriver, e as TaskRegistry, f as TaskManifest, g as ToolMetadata, h as AgentCore, i as AgentMetadata, C as CreateLoggerOptions, j as Logger } from './contextTypes-DhagvRH_.js';
-export { k as AgentHandleFactory, l as AgentHandleStore, m as AgentPathMeta, n as AgentRegistry, o as AgentToolDescriptor, p as FaapiContextConfig, q as FaapiTaskMeta, r as FailOptions, s as LogEntry, t as LogLevel, u as LogSink, S as SkillRegistry, v as SseEvent, w as SseOptions, x as SseWriter, y as TaskContext, z as TaskDriverJob, B as TaskDriverProcess, D as TaskDriverRecord, E as TaskFailedInfo, G as TaskJob, H as TaskJobStatus, I as TaskMetadata, J as TaskModule, K as TaskRegistriesSnapshot, M as TaskRegistriesView, N as ToolCore, O as ToolPathMeta, P as ToolRegistry, Q as createAppRegistries, R as createTaskRegistriesView, U as createTaskRegistry } from './contextTypes-DhagvRH_.js';
-import { F as FaapiMiddleware, R as RouteManifest, C as CorsOptions, H as HelmetOptions, I as InjectorMap, W as WsRouteManifest } from './routeTypes-0rwuIws-.js';
-export { a as Injector, b as RouteInfo, c as RouteInputSchema, d as RouteOutputSchema, e as RouteParamSchema, f as cors, h as helmet } from './routeTypes-0rwuIws-.js';
+import { A as AppRegistries, F as FaapiContext, T as TaskClient, L as LogConfig, a as TaskFailedHandler, b as TaskQueueDeps, c as TaskQueue, d as TaskDriver, e as TaskRegistry, f as TaskManifest, g as AgentCore, h as AgentMetadata, i as ToolMetadata, C as CreateLoggerOptions, j as Logger } from './contextTypes-BKQsSVMv.js';
+export { k as AgentHandleFactory, l as AgentHandleStore, m as AgentPathMeta, n as AgentRegistry, o as AgentToolDescriptor, p as FaapiContextConfig, q as FaapiTaskMeta, r as FailOptions, s as LogEntry, t as LogLevel, u as LogSink, S as SkillRegistry, v as SseEvent, w as SseOptions, x as SseWriter, y as TaskContext, z as TaskDriverJob, B as TaskDriverProcess, D as TaskDriverRecord, E as TaskFailedInfo, G as TaskJob, H as TaskJobStatus, I as TaskMetadata, J as TaskModule, K as TaskRegistriesSnapshot, M as TaskRegistriesView, N as ToolCore, O as ToolPathMeta, P as ToolRegistry, Q as createAppRegistries, R as createTaskRegistriesView, U as createTaskRegistry } from './contextTypes-BKQsSVMv.js';
+import { F as FaapiMiddleware, R as RouteManifest, C as CorsOptions, H as HelmetOptions, I as InjectorMap, W as WsRouteManifest } from './routeTypes-Cc0P3CcU.js';
+export { a as Injector, b as RouteInfo, c as RouteInputSchema, d as RouteOutputSchema, e as RouteParamSchema, f as cors, h as helmet } from './routeTypes-Cc0P3CcU.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -480,15 +480,6 @@ interface AgentConfig {
      * 详见 `@faapi/agent` 的 [trace](../../agent/src/trace.md) 文档。
      */
     enableTracing?: boolean;
-    /**
-     * 执行守卫（authHooks，见 @faapi/agent 的 authHooks 文档）
-     *
-     * 每次 tool / sub-agent 执行前调用（`agent.x` 名称为 sub-agent 递归）。
-     * 三种返回：`void` 放行；`{ error }` 拒绝（不执行，error 回传 LLM 调整策略）；
-     * `{ args }` 改写后放行（多租户场景强制注入可信值，不信 LLM 传入的标识参数）。
-     *
-     * 典型用法：中间件解析 `ctx.workspace` 后在此校验/强制改写 `args.workspaceId`。
-     */
     /**
      * 发送给 LLM 的历史 token 预算（近似估算，未设置 = 不裁剪）
      *
@@ -498,7 +489,20 @@ interface AgentConfig {
      * reactLoop 文档历史裁剪章节。
      */
     maxHistoryTokens?: number;
-    beforeToolCall?: (name: string, args: Record<string, unknown>, ctx: FaapiContext | undefined) => void | {
+    /**
+     * 执行守卫（authHooks，见 @faapi/agent 的 authHooks 文档）
+     *
+     * 每次 tool / sub-agent 执行前调用（`agent-x` 派发名称为 sub-agent 递归）。
+     * 三种返回：`void` 放行；`{ error }` 拒绝（不执行，error 回传 LLM 调整策略）；
+     * `{ args }` 改写后放行（多租户场景强制注入可信值，不信 LLM 传入的标识参数）。
+     *
+     * ctx 为请求上下文透传（`Partial<FaapiContext>`，框架零读取）：HTTP 请求是完整
+     * ctx，任务内组装 Agent 时业务方显式传窄对象（如鉴权硬闸需要的
+     * `{ currentUserId }`），编程式直调为 undefined。
+     *
+     * 典型用法：中间件解析 `ctx.workspace` 后在此校验/强制改写 `args.workspaceId`。
+     */
+    beforeToolCall?: (name: string, args: Record<string, unknown>, ctx: Partial<FaapiContext> | undefined) => void | {
         error: string;
     } | {
         args: Record<string, unknown>;
@@ -507,7 +511,7 @@ interface AgentConfig {
      * 审计钩子（authHooks）：tool / sub-agent 成功返回后调用，返回值忽略。
      * 用于日志/审计/计量；异常路径不调用。
      */
-    afterToolCall?: (name: string, args: Record<string, unknown>, result: unknown, ctx: FaapiContext | undefined) => void;
+    afterToolCall?: (name: string, args: Record<string, unknown>, result: unknown, ctx: Partial<FaapiContext> | undefined) => void;
     /**
      * 可见性过滤（authHooks）：LLM 可见 tools 清单组装完成后调用，
      * 返回过滤后的数组（含 agent-as-tool 项）。每次 agent.run / stream 生效——
@@ -523,7 +527,7 @@ interface AgentConfig {
             description?: string;
             parameters?: Record<string, unknown>;
         };
-    }>, ctx: FaapiContext | undefined) => Array<{
+    }>, ctx: Partial<FaapiContext> | undefined) => Array<{
         type: 'function';
         function: {
             name: string;
@@ -1295,31 +1299,44 @@ interface ToolSchemaModule {
  * 计算 tool 的 zod.js 绝对路径（纯路径计算，无 fs 访问）
  *
  * 与 [loadToolSchema](./loadToolSchema.ts) 内部使用的路径逻辑同源（共享 `getDist()`），
+/**
+ * zod.js 定位的最小来源结构——`ToolMetadata` 与 `AgentMetadata`（派发入参 schema
+ * 声明场景）均满足，加载器无需感知来源差异
+ */
+interface SchemaSourceRef {
+    /** 源码/产物相对路径（与 zod.js 同级，推导 zod.js 路径用） */
+    filePath: string;
+    /** schema 类型名（`undefined` = 无 schema 声明） */
+    inputTypeName?: string;
+}
+/**
+ * 计算 zod.js 的绝对路径（纯路径计算，无 fs 访问）
+ *
+ * 与 [loadToolSchema](./loadToolSchema.ts) 内部使用的路径逻辑同源（共享 `getDist()`），
  * 供 `@faapi/agent` 的跨请求 schema 缓存用作缓存键 + mtime 校验目标。
  *
- * @param tool tool 元数据（含 `filePath`）
- * @param rootDir 项目根目录（`tool.filePath` 是相对路径时拼接）
+ * @param ref schema 来源元数据（tool / agent 均可，含 `filePath`）
+ * @param rootDir 项目根目录（`ref.filePath` 是相对路径时拼接）
  */
-declare function getToolSchemaPath(tool: ToolMetadata, rootDir?: string): string;
+declare function getToolSchemaPath(ref: SchemaSourceRef, rootDir?: string): string;
 /**
- * 动态加载 tool 的 zod.js schema 模块
+ * 动态加载 zod.js schema 模块（tool input 与 agent 派发入参共用）
  *
  * 与 [loadToolModule](./loadToolModule.md) 对称——一个加载 handler.js（tool 函数），
- * 一个加载 zod.js（tool schema）。
+ * 一个加载 zod.js（schema 模块）。tool 的 zod.js 与 handler.js 同级；agent 声明
+ * `Input` 时同样生成同级 zod.js（见 generateAgentArtifacts），同一加载器服务两类来源。
  *
  * 行为：
- * - `tool.inputTypeName` 为 `undefined` → 返回 `undefined`（无 schema，用自由 schema）
- * - zod.js 文件不存在 → 返回 `undefined`（schema 可选，缺失用自由 schema）
+ * - `ref.inputTypeName` 为 `undefined` → 返回 `undefined`（无 schema 声明）
+ * - zod.js 文件不存在 → 返回 `undefined`（schema 缺失，调用方按各自语义处理——
+ *   tool 用自由 schema `{ type: 'object' }`；agent 派发入参在声明了 `inputTypeName`
+ *   时视为产物异常，由 `@faapi/agent` 侧显式抛错）
  * - import 失败 / 导出名不匹配 → 返回 `undefined`
  *
- * 与 route schema 不同（route schema 缺失抛 `InternalError`），tool schema 是可选的——
- * `@faapi/agent` 的 `resolveToolSchema` 未提供时用自由 schema `{ type: 'object' }`，
- * LLM 自由传参，handler 内部自行处理参数合法性。
- *
- * @param tool tool 元数据（含 `filePath` + `inputTypeName`）
- * @param rootDir 项目根目录（用于计算 zod.js 绝对路径，`tool.filePath` 是相对路径时拼接）
+ * @param ref schema 来源元数据（tool / agent 均可，含 `filePath` + `inputTypeName`）
+ * @param rootDir 项目根目录（用于计算 zod.js 绝对路径，`ref.filePath` 是相对路径时拼接）
  */
-declare function loadToolSchema(tool: ToolMetadata, rootDir?: string): Promise<ToolSchemaModule | undefined>;
+declare function loadToolSchema(ref: SchemaSourceRef, rootDir?: string): Promise<ToolSchemaModule | undefined>;
 
 /**
  * 按名查找单个 agent 的 LLM 可见元数据（默认实例）
@@ -1764,4 +1781,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type AgentConfig, AgentCore, AgentMetadata, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, CreateLoggerOptions, type CronScheduler, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, LLM_TOOL_NAME_PATTERN, type LifecycleContext, type LifecycleHooks, type LlmConfig, type LlmModelConfig, LogConfig, Logger, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SUB_AGENT_TOOL_PREFIX, SchemaExtractionError, TASK_PATTERNS, type TaskBullMqOptions, TaskClient, type TaskConfig, TaskDriver, TaskFailedHandler, TaskManifest, type TaskPgBossOptions, TaskQueue, TaskRegistry, ToolMetadata, type ToolModule, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, flushLogging, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, logger, readResource, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, subAgentToolName, upsertSkill };
+export { type AgentConfig, AgentCore, AgentMetadata, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, CreateLoggerOptions, type CronScheduler, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, LLM_TOOL_NAME_PATTERN, type LifecycleContext, type LifecycleHooks, type LlmConfig, type LlmModelConfig, LogConfig, Logger, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SUB_AGENT_TOOL_PREFIX, SchemaExtractionError, type SchemaSourceRef, TASK_PATTERNS, type TaskBullMqOptions, TaskClient, type TaskConfig, TaskDriver, TaskFailedHandler, TaskManifest, type TaskPgBossOptions, TaskQueue, TaskRegistry, ToolMetadata, type ToolModule, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, flushLogging, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, logger, readResource, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, subAgentToolName, upsertSkill };

package/dist/index.js

@@ -2864,6 +2864,34 @@ var CONCURRENCY_RE = new RegExp(`(?:^|\\n)\\s*concurrency:\\s*${NUM_LITERAL}`);
 var RETRIES_RE = new RegExp(`(?:^|\\n)\\s*retries:\\s*${NUM_LITERAL}`);
 var TIMEOUT_MS_RE = new RegExp(`(?:^|\\n)\\s*timeoutMs:\\s*${NUM_LITERAL}`);
 var GRACE_MS_RE = new RegExp(`(?:^|\\n)\\s*graceMs:\\s*${NUM_LITERAL}`);
+var NUMERIC_META_FIELDS = ["concurrency", "retries", "timeoutMs", "graceMs"];
+var STRING_META_FIELDS = ["cron"];
+var ALL_META_FIELDS = [...NUMERIC_META_FIELDS, ...STRING_META_FIELDS];
+function detectIgnoredMetaFields(source, strictHit) {
+  const declared = /* @__PURE__ */ new Set();
+  for (const line of source.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//")) continue;
+    for (const field of ALL_META_FIELDS) {
+      if (new RegExp(`\\b${field}\\s*:`).test(trimmed)) declared.add(field);
+    }
+  }
+  return ALL_META_FIELDS.filter((field) => declared.has(field) && !strictHit[field]);
+}
+function warnIgnoredMetaFields(name, fields) {
+  for (const field of fields) {
+    if (STRING_META_FIELDS.includes(field)) {
+      console.warn(
+        `[faapi] Task "${name}" declares "${field}" but its value is not a string literal \u2014 the declaration was ignored and the task will not be cron-scheduled. Meta values are extracted from source code without importing it, so only literal values are recognized: use a quoted literal (cron: '0 3 * * *'), not an expression or a dynamic value.`
+      );
+    } else {
+      const consequence = field === "timeoutMs" ? " and the task will run in-process with no timeout" : "";
+      console.warn(
+        `[faapi] Task "${name}" declares "${field}" but its value is not a numeric literal \u2014 the declaration was ignored${consequence}. Meta values are extracted from source code without importing it, so only literal values are recognized (underscores allowed, e.g. 1_800_000); expressions like 30 * 60_000 or dynamic values are not supported.`
+      );
+    }
+  }
+}
 function parseNumericLiteral(raw) {
   return Number(raw.replace(/_/g, ""));
 }
@@ -2925,6 +2953,14 @@ async function scanTasks(rootDir, patterns) {
       manifest.timeoutMs = value;
     }
     if (graceMs !== void 0) manifest.graceMs = parseNumericLiteral(graceMs);
+    const strictHit = {
+      cron: cron !== void 0,
+      concurrency: concurrency !== void 0,
+      retries: retries !== void 0,
+      timeoutMs: timeoutMs !== void 0,
+      graceMs: graceMs !== void 0
+    };
+    warnIgnoredMetaFields(name, detectIgnoredMetaFields(source, strictHit));
     tasks.push(manifest);
   }
   return tasks.sort((a, b) => a.name.localeCompare(b.name));
@@ -3890,18 +3926,18 @@ function getDist() {
   }
   return process.env.FAAPI_DIST ?? "dist";
 }
-function getToolSchemaPath(tool, rootDir) {
+function getToolSchemaPath(ref, rootDir) {
   const dist = getDist();
-  return getRuntimeSchemaPath(tool.filePath, dist, rootDir ?? process.cwd());
+  return getRuntimeSchemaPath(ref.filePath, dist, rootDir ?? process.cwd());
 }
-async function loadToolSchema(tool, rootDir) {
-  if (!tool.inputTypeName) return void 0;
-  const schemaName = `${tool.inputTypeName}Schema`;
-  const zodPath = getToolSchemaPath(tool, rootDir);
+async function loadToolSchema(ref, rootDir) {
+  if (!ref.inputTypeName) return void 0;
+  const schemaName = `${ref.inputTypeName}Schema`;
+  const zodPath = getToolSchemaPath(ref, rootDir);
   if (!existsSync3(zodPath)) return void 0;
   try {
     const mod = await importWithCacheBust(zodPath, isDevOnDemandEnabled());
-    const schema = mod[`${tool.inputTypeName}Schema`];
+    const schema = mod[`${ref.inputTypeName}Schema`];
     if (!schema) return void 0;
     return { schema, schemaName };
   } catch {
@@ -6866,9 +6902,20 @@ function extractAgentMetadata(program, filePath, pathMeta) {
     agents,
     model,
     maxTurns,
-    inputDescription
+    inputDescription,
+    inputTypeName: findInputDeclaration(sourceFile) ? "Input" : void 0
   };
 }
+function findInputDeclaration(sourceFile) {
+  let found = false;
+  ts11.forEachChild(sourceFile, (node) => {
+    if (found) return;
+    if ((ts11.isInterfaceDeclaration(node) || ts11.isTypeAliasDeclaration(node)) && node.name.text === "Input") {
+      found = true;
+    }
+  });
+  return found;
+}
 function findRunExportOwner(sourceFile) {
   let result = null;
   ts11.forEachChild(sourceFile, (node) => {
@@ -7075,6 +7122,9 @@ function extractStringArrayValue(expr) {
 // src/cli/generateAgentArtifacts.ts
 init_createProgram();
 init_atomicWrite();
+init_extractHandlerTypes();
+init_generateZodSchema();
+init_generateZodArtifacts();
 var AGENTS_FILE = "faapi-agents.js";
 function serializeAgents(agents, dist = "dist") {
   return agents.map((a) => ({
@@ -7087,6 +7137,7 @@ function serializeAgents(agents, dist = "dist") {
     model: a.model,
     maxTurns: a.maxTurns,
     inputDescription: a.inputDescription,
+    inputTypeName: a.inputTypeName,
     filePath: toProdFilePath(a.filePath, dist)
   }));
 }
@@ -7107,7 +7158,8 @@ function hydrateAgents(manifest) {
     agents: a.agents ?? void 0,
     model: a.model ?? void 0,
     maxTurns: a.maxTurns ?? void 0,
-    inputDescription: a.inputDescription ?? void 0
+    inputDescription: a.inputDescription ?? void 0,
+    inputTypeName: a.inputTypeName ?? void 0
   }));
 }
 function validateAgentList(metadata) {
@@ -7153,8 +7205,66 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
   const serialized = serializeAgents(metadata, dist);
   const agentsPath = path24.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);
+  await generateAgentZodArtifacts(metadata, programByFile, rootDir, dist);
   return metadata;
 }
+async function generateAgentZodArtifacts(metadata, programByFile, rootDir, dist) {
+  const declared = metadata.filter((a) => a.inputTypeName);
+  if (declared.length === 0) return;
+  const resolversByFile = /* @__PURE__ */ new Map();
+  const sources = [];
+  for (const agent of declared) {
+    const absPath = path24.resolve(rootDir, agent.filePath);
+    const program = programByFile.get(absPath);
+    if (!program) {
+      throw new Error(
+        `agent "${agent.name}" \u6E90\u6587\u4EF6\u4E0D\u5728 Program \u4E2D: ${agent.filePath}\u2014\u2014\u65E0\u6CD5\u751F\u6210\u5165\u53C2 schema`
+      );
+    }
+    if (!resolversByFile.has(absPath)) {
+      resolversByFile.set(absPath, createLazyTypeResolver(program, absPath));
+    }
+    const typeInfo = extractTypeInfo(program, absPath, agent.inputTypeName);
+    sources.push({
+      name: agent.name,
+      filePath: absPath,
+      schemaName: agent.inputTypeName,
+      typeInfo
+    });
+  }
+  await generateZodArtifacts(sources, {
+    generateFileSource: generateAgentSchemaFileSource,
+    resolversByFile,
+    rootDir,
+    dist
+  });
+}
+function generateAgentSchemaFileSource(sources, resolveType, helpersImportPath) {
+  const lines = ["import { z } from 'zod';"];
+  const schemaBlocks = [];
+  for (const source of sources) {
+    if (!source.typeInfo) continue;
+    const block = [`// agent ${source.name} \u2192 ${source.schemaName}`];
+    const schemaCode = generateZodSchemaSource(
+      source.typeInfo,
+      resolveType,
+      source.schemaName,
+      false
+    ).replace(/^import \{ z \} from 'zod';\s*\n\s*\n/, "");
+    block.push(schemaCode);
+    block.push("");
+    schemaBlocks.push(block.join("\n"));
+  }
+  const allSchemaCode = schemaBlocks.join("\n");
+  if (helpersImportPath && usesCoerceHelpers(allSchemaCode)) {
+    lines.push(
+      `import { coerceNumber, coerceBoolean, coerceMap, coerceSet } from '${helpersImportPath}';`
+    );
+  }
+  lines.push("");
+  lines.push(...schemaBlocks);
+  return lines.join("\n").replace(/\n+$/, "\n");
+}
 
 // src/cli/generateTaskArtifacts.ts
 init_generateZodArtifacts();