@faapi/faapi 2.0.1 → 3.0.0

package/dist/index.js

@@ -790,7 +790,11 @@ var init_resolveInjection = __esm({
       ip: "ip",
       ua: "ua",
       files: "files",
-      fields: "fields"
+      fields: "fields",
+      agent: "agent",
+      // Phase 2.3
+      agents: "agents"
+      // Phase 2.3
     };
   }
 });
@@ -1219,8 +1223,8 @@ __export(generateSchemaFiles_exports, {
   getRuntimeSchemaPath: () => getRuntimeSchemaPath,
   getSchemaOutputPath: () => getSchemaOutputPath
 });
-import path7 from "path";
-import fs6 from "fs/promises";
+import path5 from "path";
+import fs4 from "fs/promises";
 function getSchemaOutputPath(sourceFile, dist, rootDir) {
   let rel = sourceFile.replace(/\\/g, "/");
   if (rel.startsWith("src/")) {
@@ -1228,7 +1232,7 @@ function getSchemaOutputPath(sourceFile, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path7.resolve(rootDir, dist, relDir, "zod.js");
+  return path5.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getRuntimeSchemaPath(filePath, dist, rootDir) {
   let rel = filePath.replace(/\\/g, "/");
@@ -1239,7 +1243,7 @@ function getRuntimeSchemaPath(filePath, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path7.resolve(rootDir, dist, relDir, "zod.js");
+  return path5.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getHelpersImportPath(relDir) {
   if (!relDir) return `./${HELPERS_FILENAME}`;
@@ -1289,7 +1293,7 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path7.relative(rootDir, filePath).replace(/\\/g, "/");
+    const relFile = path5.relative(rootDir, filePath).replace(/\\/g, "/");
     const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
     const allTypes = allTypesByFile.get(filePath) ?? /* @__PURE__ */ new Map();
     let relForDir = relFile;
@@ -1304,7 +1308,7 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
   if (usesCoerceHelpers(allSourceCode)) {
-    const helpersPath = path7.resolve(rootDir, dist, HELPERS_FILENAME);
+    const helpersPath = path5.resolve(rootDir, dist, HELPERS_FILENAME);
     await writeSchemaFile(helpersPath, generateHelpersFileSource());
   }
   await Promise.all(
@@ -1312,8 +1316,8 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   );
 }
 async function writeSchemaFile(outputPath, source) {
-  await fs6.mkdir(path7.dirname(outputPath), { recursive: true });
-  await fs6.writeFile(outputPath, source, "utf-8");
+  await fs4.mkdir(path5.dirname(outputPath), { recursive: true });
+  await fs4.writeFile(outputPath, source, "utf-8");
 }
 var init_generateSchemaFiles = __esm({
   "src/cli/generateSchemaFiles.ts"() {
@@ -1330,175 +1334,86 @@ init_resolveTypeNode();
 init_inputType();
 init_collectRouteSchemaSources();
 
-// src/middleware/cors.ts
-var DEFAULT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
-function cors(options = {}) {
-  const {
-    origin = true,
-    methods = DEFAULT_METHODS,
-    allowedHeaders,
-    exposeHeaders,
-    credentials = false,
-    maxAge
-  } = options;
-  return async (ctx, next) => {
-    const reqOrigin = ctx.headers.get("origin");
-    if (!reqOrigin) {
-      await next();
-      return;
-    }
-    let allowOrigin = null;
-    if (origin === true) {
-      allowOrigin = reqOrigin;
-    } else if (typeof origin === "string") {
-      allowOrigin = reqOrigin === origin ? origin : null;
-    } else if (Array.isArray(origin)) {
-      allowOrigin = origin.includes(reqOrigin) ? reqOrigin : null;
-    }
-    if (!allowOrigin) {
-      await next();
-      return;
-    }
-    ctx.setHeader("Access-Control-Allow-Origin", allowOrigin);
-    if (origin === true || Array.isArray(origin)) {
-      const existingVary = ctx.headers.get("vary");
-      if (existingVary) {
-        if (!existingVary.toLowerCase().includes("origin")) {
-          ctx.setHeader("Vary", `${existingVary}, Origin`);
-        }
-      } else {
-        ctx.setHeader("Vary", "Origin");
-      }
-    }
-    ctx.setHeader("Access-Control-Allow-Methods", methods.join(", "));
-    if (allowedHeaders) {
-      ctx.setHeader("Access-Control-Allow-Headers", allowedHeaders.join(", "));
-    } else {
-      const requestHeaders = ctx.headers.get("access-control-request-headers");
-      if (requestHeaders) {
-        ctx.setHeader("Access-Control-Allow-Headers", requestHeaders);
-      }
-    }
-    if (exposeHeaders && exposeHeaders.length > 0) {
-      ctx.setHeader("Access-Control-Expose-Headers", exposeHeaders.join(", "));
-    }
-    if (credentials) {
-      ctx.setHeader("Access-Control-Allow-Credentials", "true");
-    }
-    if (maxAge !== void 0) {
-      ctx.setHeader("Access-Control-Max-Age", String(maxAge));
-    }
-    if (ctx.method === "OPTIONS") {
-      return new Response(null, { status: 204 });
-    }
-    await next();
-  };
+// src/injection/toolRegistry.ts
+var registry = /* @__PURE__ */ new Map();
+function hydrateToolRegistry(tools) {
+  const next = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    next.set(tool.name, tool);
+  }
+  registry = next;
+}
+function clearToolRegistry() {
+  registry = /* @__PURE__ */ new Map();
+}
+function getTool(name) {
+  return registry.get(name);
 }
 
-// src/middleware/logger.ts
-function logger(options = {}) {
-  return async (ctx, next) => {
-    const log = options.log ?? console.log;
-    const start = Date.now();
-    try {
-      const response = await next();
-      const duration = Date.now() - start;
-      const entry = {
-        method: ctx.method,
-        path: ctx.path,
-        status: response.status,
-        durationMs: duration
-      };
-      log(entry, `${ctx.method} ${ctx.path} ${response.status} ${duration}ms`);
-      return response;
-    } catch (err) {
-      const duration = Date.now() - start;
-      const message = err instanceof Error ? err.message : String(err);
-      const status = err?.statusCode ?? 500;
-      const entry = {
-        method: ctx.method,
-        path: ctx.path,
-        status,
-        durationMs: duration,
-        error: message
-      };
-      log(entry, `${ctx.method} ${ctx.path} ${status} ${duration}ms - ${message}`);
-      throw err;
+// src/injection/agentRegistry.ts
+var registry2 = /* @__PURE__ */ new Map();
+function hydrateAgentRegistry(agents) {
+  const next = /* @__PURE__ */ new Map();
+  for (const agent of agents) {
+    next.set(agent.name, agent);
+  }
+  registry2 = next;
+}
+function clearAgentRegistry() {
+  registry2 = /* @__PURE__ */ new Map();
+}
+function getAgent(name) {
+  return registry2.get(name);
+}
+function listAgents() {
+  return Array.from(registry2.values());
+}
+function resolveAgentTools(name) {
+  const agent = registry2.get(name);
+  if (!agent) return [];
+  const result = /* @__PURE__ */ new Map();
+  if (agent.tools) {
+    for (const toolName of agent.tools) {
+      const tool = getTool(toolName);
+      if (tool) result.set(tool.name, tool);
     }
-  };
+  }
+  return Array.from(result.values());
+}
+function resolveSubAgents(name) {
+  const agent = registry2.get(name);
+  if (!agent || !agent.agents) return [];
+  const result = [];
+  for (const agentName of agent.agents) {
+    const subAgent = registry2.get(agentName);
+    if (subAgent) result.push(subAgent);
+  }
+  return result;
 }
 
-// src/middleware/helmet.ts
-var DEFAULTS = {
-  contentSecurityPolicy: "default-src 'self'",
-  xFrameOptions: "SAMEORIGIN",
-  xContentTypeOptions: true,
-  referrerPolicy: "no-referrer",
-  strictTransportSecurity: "max-age=31536000; includeSubDomains",
-  xDnsPrefetchControl: true,
-  xDownloadOptions: true,
-  xPermittedCrossDomainPolicies: "none",
-  crossOriginOpenerPolicy: "same-origin",
-  crossOriginResourcePolicy: "same-origin",
-  crossOriginEmbedderPolicy: false,
-  originAgentCluster: true,
-  xPoweredBy: true
-};
-function helmet(options = {}) {
-  const opts = { ...DEFAULTS, ...options };
-  return async (ctx, next) => {
-    if (opts.contentSecurityPolicy !== false) {
-      ctx.setHeader("Content-Security-Policy", opts.contentSecurityPolicy);
-    }
-    if (opts.xFrameOptions !== false) {
-      ctx.setHeader("X-Frame-Options", opts.xFrameOptions);
-    }
-    if (opts.xContentTypeOptions) {
-      ctx.setHeader("X-Content-Type-Options", "nosniff");
-    }
-    if (opts.referrerPolicy !== false) {
-      ctx.setHeader("Referrer-Policy", opts.referrerPolicy);
-    }
-    if (opts.strictTransportSecurity !== false) {
-      ctx.setHeader("Strict-Transport-Security", opts.strictTransportSecurity);
-    }
-    if (opts.xDnsPrefetchControl) {
-      ctx.setHeader("X-DNS-Prefetch-Control", "off");
-    }
-    if (opts.xDownloadOptions) {
-      ctx.setHeader("X-Download-Options", "noopen");
-    }
-    if (opts.xPermittedCrossDomainPolicies !== false) {
-      ctx.setHeader("X-Permitted-Cross-Domain-Policies", opts.xPermittedCrossDomainPolicies);
-    }
-    if (opts.crossOriginOpenerPolicy !== false) {
-      ctx.setHeader("Cross-Origin-Opener-Policy", opts.crossOriginOpenerPolicy);
-    }
-    if (opts.crossOriginResourcePolicy !== false) {
-      ctx.setHeader("Cross-Origin-Resource-Policy", opts.crossOriginResourcePolicy);
-    }
-    if (opts.crossOriginEmbedderPolicy !== false) {
-      ctx.setHeader("Cross-Origin-Embedder-Policy", opts.crossOriginEmbedderPolicy);
-    }
-    if (opts.originAgentCluster) {
-      ctx.setHeader("Origin-Agent-Cluster", "?1");
-    }
-    if (opts.xPoweredBy) {
-      ctx.setHeader("X-Powered-By", "faapi");
+// src/loader/loadAgentModule.ts
+import fs6 from "fs";
+
+// src/loader/resolveExports.ts
+function resolveExport(module, exportName) {
+  if (exportName in module && typeof module[exportName] !== "undefined") {
+    return module[exportName];
+  }
+  const defaultExport = module.default;
+  if (defaultExport !== null && typeof defaultExport === "object") {
+    const value = defaultExport[exportName];
+    if (value !== void 0) {
+      return value;
     }
-    return await next();
-  };
+  }
+  return void 0;
 }
 
-// src/config/loadConfig.ts
-import path2 from "path";
-import fs from "fs";
-
 // src/utils/importWithCacheBust.ts
 import { pathToFileURL } from "url";
 var loadTs;
-function setLoadTimestamp(ts7) {
-  loadTs = ts7;
+function setLoadTimestamp(ts9) {
+  loadTs = ts9;
 }
 function getVitestImportActual() {
   const vi = globalThis.vi;
@@ -1522,666 +1437,1227 @@ async function importWithCacheBust(filePath, bustViteCache = false) {
   return await import(url);
 }
 
-// src/config/loadConfig.ts
-var CONFIG_PRODUCT_FILE = "faapi-config.js";
-async function loadConfig(rootDir, dist) {
-  const configProductPath = path2.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
-  if (fs.existsSync(configProductPath)) {
-    const module = await importWithCacheBust(configProductPath);
-    return module.default ?? {};
-  }
-  const hasSourceConfig = fs.existsSync(path2.join(rootDir, "faapi.config.ts")) || fs.existsSync(path2.join(rootDir, "faapi.config.js"));
-  if (hasSourceConfig) {
-    throw new Error(
-      `[faapi] ${dist}/${CONFIG_PRODUCT_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
-    );
-  }
-  return null;
-}
+// src/cli/compileOnDemand.ts
+import path6 from "path";
+import fs5 from "fs";
 
-// src/cli/loadEnv.ts
-import fs2 from "fs";
+// src/cli/compileDevRoutes.ts
+import path4 from "path";
+import fs3 from "fs";
+import fg from "fast-glob";
+
+// src/cli/aliasPlugin.ts
 import path3 from "path";
-function resolveEnv() {
-  return process.env.NODE_ENV || "development";
-}
-function getEnvFiles(env) {
-  return [".env", ".env.local", `.env.${env}`, `.env.${env}.local`];
-}
-function parseEnvFile(content, fileVars) {
-  const result = {};
-  const lines = content.replace(/\r\n/g, "\n").split("\n");
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(trimmed);
-    if (!match) continue;
-    const [, key, rawValue] = match;
-    const value = parseValue(rawValue, { ...fileVars, ...result });
-    result[key] = value;
+import fs2 from "fs";
+
+// src/utils/resolveAlias.ts
+function resolveAlias(specifier, config) {
+  const candidates = [];
+  for (const [pattern, targets] of Object.entries(config.paths)) {
+    const wildcardIndex = pattern.indexOf("*");
+    if (wildcardIndex === -1) {
+      if (specifier === pattern) {
+        candidates.push(...targets);
+      }
+      continue;
+    }
+    const prefix = pattern.slice(0, wildcardIndex);
+    const suffix = pattern.slice(wildcardIndex + 1);
+    if (specifier.startsWith(prefix) && specifier.endsWith(suffix) && specifier.length >= prefix.length + suffix.length) {
+      const captured = specifier.slice(prefix.length, specifier.length - suffix.length);
+      for (const target of targets) {
+        candidates.push(target.replace("*", captured));
+      }
+    }
   }
-  return result;
+  return candidates;
 }
-function parseValue(raw, env) {
-  if (raw === "") return "";
-  if (raw[0] === "'") {
-    const end = raw.indexOf("'", 1);
-    return end === -1 ? raw.slice(1) : raw.slice(1, end);
-  }
-  if (raw[0] === '"') {
-    const match = /^"((?:\\.|[^"\\])*)"/.exec(raw);
-    const inner = match ? match[1] : raw.slice(1);
-    return expandEscapesAndVars(inner, env);
+
+// src/utils/readTsconfig.ts
+import ts6 from "typescript";
+import path2 from "path";
+import fs from "fs";
+function readTsconfig(rootDir) {
+  const tsconfigPath = path2.resolve(rootDir, "tsconfig.json");
+  if (!fs.existsSync(tsconfigPath)) return null;
+  const configFile = ts6.readConfigFile(tsconfigPath, ts6.sys.readFile);
+  if (configFile.error || !configFile.config) return null;
+  const parsed = ts6.parseJsonConfigFileContent(configFile.config, ts6.sys, rootDir);
+  const baseUrl = parsed.options.baseUrl ?? rootDir;
+  const rawPaths = parsed.options.paths;
+  if (!rawPaths) return null;
+  const paths = {};
+  for (const [pattern, targets] of Object.entries(rawPaths)) {
+    paths[pattern] = targets.map((t) => path2.resolve(baseUrl, t));
   }
-  const commentMatch = /^(.*?)(\s+#.*)$/.exec(raw);
-  const value = commentMatch ? commentMatch[1] : raw;
-  return value.trim();
+  return { baseUrl, paths };
 }
-function expandEscapesAndVars(str, env) {
-  const escaped = str.replace(/\\(.)/g, (_, ch) => {
-    switch (ch) {
-      case "n":
-        return "\n";
-      case "r":
-        return "\r";
-      case "t":
-        return "	";
-      case "\\":
-        return "\\";
-      case '"':
-        return '"';
-      default:
-        return ch;
-    }
-  });
-  return escaped.replace(
-    /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g,
-    (_, braced, plain) => {
-      const varName = braced || plain;
-      return env[varName] ?? process.env[varName] ?? "";
-    }
-  );
+
+// src/cli/aliasPlugin.ts
+function toProdExtension(filePath) {
+  if (filePath.endsWith(".ts")) return filePath.slice(0, -3) + ".js";
+  if (filePath.endsWith(".tsx")) return filePath.slice(0, -4) + ".js";
+  if (filePath.endsWith(".jsx")) return filePath.slice(0, -4) + ".js";
+  return filePath;
 }
-function loadEnv(rootDir) {
-  const env = resolveEnv();
-  const files = getEnvFiles(env);
-  const merged = {};
-  for (const file of files) {
-    const filePath = path3.join(rootDir, file);
-    if (!fs2.existsSync(filePath)) continue;
-    const content = fs2.readFileSync(filePath, "utf-8");
-    const parsed = parseEnvFile(content, merged);
-    Object.assign(merged, parsed);
-  }
-  for (const [key, value] of Object.entries(merged)) {
-    if (process.env[key] === void 0) {
-      process.env[key] = value;
-    }
-  }
+function toProdImportPath(sourceFile, importer) {
+  const importerDir = path3.dirname(importer);
+  let rel = path3.relative(importerDir, sourceFile);
+  rel = rel.split(path3.sep).join("/");
+  if (!rel.startsWith(".")) rel = "./" + rel;
+  return toProdExtension(rel);
 }
-
-// src/errors/FaapiError.ts
-var FaapiError = class extends Error {
-  constructor(code, message, statusCode) {
-    super(message);
-    this.code = code;
-    this.statusCode = statusCode;
-    this.name = "FaapiError";
+function toRealPath(p) {
+  try {
+    return fs2.realpathSync(p);
+  } catch {
+    return p;
   }
-  code;
-  statusCode;
-};
-
-// src/errors/httpErrors.ts
-function deriveStatusCode(issues) {
-  const has400 = issues.some((i) => i.code === "INVALID_FORMAT" || i.code === "MISSING_FIELD");
-  return has400 ? 400 : 422;
 }
-var ValidationError = class extends FaapiError {
-  constructor(message, issues) {
-    super("VALIDATION_ERROR", message, deriveStatusCode(issues));
-    this.issues = issues;
-    this.name = "ValidationError";
-  }
-  issues;
-};
-var RouteNotFoundError = class extends FaapiError {
-  constructor(path14) {
-    super("ROUTE_NOT_FOUND", `Route not found: ${path14}`, 404);
-    this.name = "RouteNotFoundError";
+function isInsideDir(filePath, dir) {
+  const rel = path3.relative(dir, filePath);
+  return rel !== "" && !rel.startsWith("..") && !path3.isAbsolute(rel);
+}
+var APP_DIR = "src";
+function toStrippedProdImportPath(sourceFile, rootDir) {
+  const appDirAbs = toRealPath(path3.resolve(rootDir, APP_DIR));
+  const sourceReal = toRealPath(sourceFile);
+  let rel = path3.relative(appDirAbs, sourceReal);
+  rel = rel.split(path3.sep).join("/");
+  if (!rel.startsWith(".")) rel = "./" + rel;
+  return toProdExtension(rel);
+}
+var PROD_EXTS = [".js", ".mjs", ".cjs"];
+var SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+var INDEX_EXTS = [
+  "/index.ts",
+  "/index.tsx",
+  "/index.js",
+  "/index.jsx",
+  "/index.mjs",
+  "/index.cjs"
+];
+function resolveRelativeSpecifier(importer, specifier) {
+  const importerDir = path3.dirname(importer);
+  const base = path3.resolve(importerDir, specifier);
+  if (PROD_EXTS.some((ext) => specifier.endsWith(ext))) {
+    return fs2.existsSync(base) ? base : null;
   }
-};
-var MethodNotAllowedError = class extends FaapiError {
-  constructor(method, path14, allowedMethods) {
-    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path14}`, 405);
-    this.allowedMethods = allowedMethods;
-    this.name = "MethodNotAllowedError";
+  if (/\.(ts|tsx|jsx)$/.test(specifier)) {
+    return fs2.existsSync(base) ? base : null;
   }
-  allowedMethods;
-};
-var InternalError = class extends FaapiError {
-  constructor(message) {
-    super("INTERNAL_ERROR", message, 500);
-    this.name = "InternalError";
+  for (const ext of SOURCE_EXTS) {
+    const file = base + ext;
+    if (fs2.existsSync(file)) return file;
   }
-};
-var ModuleLoadError = class extends FaapiError {
-  constructor(filePath, reason) {
-    super("MODULE_LOAD_ERROR", `Failed to load module ${filePath}: ${reason}`, 500);
-    this.name = "ModuleLoadError";
+  for (const indexExt of INDEX_EXTS) {
+    const file = base + indexExt;
+    if (fs2.existsSync(file)) return file;
   }
-};
-
-// src/cli/createAppCore.ts
-import fs11 from "fs";
-import path12 from "path";
-import { PassThrough, Readable as Readable3 } from "stream";
-
-// src/router/sortRoutes.ts
-function sortRoutes(routes) {
-  return [...routes].sort((a, b) => {
-    if (a.isDynamic !== b.isDynamic) {
-      return a.isDynamic ? 1 : -1;
-    }
-    if (a.isCatchAll !== b.isCatchAll) {
-      return a.isCatchAll ? 1 : -1;
-    }
-    const aSegments = a.urlPath.split("/").filter(Boolean).length;
-    const bSegments = b.urlPath.split("/").filter(Boolean).length;
-    if (aSegments !== bSegments) {
-      return aSegments - bSegments;
-    }
-    return a.urlPath.localeCompare(b.urlPath);
-  });
+  return null;
 }
-
-// src/router/detectRouteConflicts.ts
-function detectRouteConflicts(routes) {
-  const map = /* @__PURE__ */ new Map();
-  for (const route of routes) {
-    const key = `${route.method} ${route.urlPath}`;
-    const existing = map.get(key);
-    if (existing) {
-      existing.files.push(route.filePath);
-    } else {
-      map.set(key, {
-        method: route.method,
-        urlPath: route.urlPath,
-        files: [route.filePath]
+function createAliasPlugin(config, options) {
+  const SPEC_RE = /(\bfrom\s*|import\s*\(\s*)(['"])([^'"]+)\2/g;
+  const appDirAbs = options?.rootDir ? toRealPath(path3.resolve(options.rootDir, APP_DIR)) : null;
+  return {
+    name: "faapi-alias",
+    setup(build) {
+      build.onLoad({ filter: /\.(ts|tsx|js|jsx|mjs|cjs)$/ }, (args) => {
+        let source;
+        try {
+          source = fs2.readFileSync(args.path, "utf8");
+        } catch {
+          return void 0;
+        }
+        const importer = args.path;
+        const importerOutsideAppDir = appDirAbs ? !isInsideDir(importer, appDirAbs) : false;
+        let modified = false;
+        const newSource = source.replace(SPEC_RE, (full, prefix, quote, specifier) => {
+          if (specifier.startsWith("/") || specifier.startsWith("file:") || specifier.startsWith("node:")) {
+            return full;
+          }
+          if (specifier.startsWith("./") || specifier.startsWith("../")) {
+            const resolved = resolveRelativeSpecifier(importer, specifier);
+            if (resolved) {
+              if (PROD_EXTS.some((ext) => specifier.endsWith(ext))) {
+                return full;
+              }
+              if (appDirAbs && importerOutsideAppDir && isInsideDir(resolved, appDirAbs)) {
+                modified = true;
+                return `${prefix}${quote}${toStrippedProdImportPath(
+                  resolved,
+                  options.rootDir
+                )}${quote}`;
+              }
+              modified = true;
+              return `${prefix}${quote}${toProdImportPath(resolved, importer)}${quote}`;
+            }
+            return full;
+          }
+          const candidates = resolveAlias(specifier, config);
+          for (const candidate of candidates) {
+            for (const ext of SOURCE_EXTS) {
+              const file = candidate + ext;
+              if (fs2.existsSync(file)) {
+                modified = true;
+                if (appDirAbs && importerOutsideAppDir && isInsideDir(file, appDirAbs)) {
+                  return `${prefix}${quote}${toStrippedProdImportPath(
+                    file,
+                    options.rootDir
+                  )}${quote}`;
+                }
+                return `${prefix}${quote}${toProdImportPath(file, importer)}${quote}`;
+              }
+            }
+            for (const indexExt of INDEX_EXTS) {
+              const file = candidate + indexExt;
+              if (fs2.existsSync(file)) {
+                modified = true;
+                if (appDirAbs && importerOutsideAppDir && isInsideDir(file, appDirAbs)) {
+                  return `${prefix}${quote}${toStrippedProdImportPath(
+                    file,
+                    options.rootDir
+                  )}${quote}`;
+                }
+                return `${prefix}${quote}${toProdImportPath(file, importer)}${quote}`;
+              }
+            }
+          }
+          return full;
+        });
+        if (!modified) return void 0;
+        return { contents: newSource, loader: "default" };
       });
     }
-  }
-  const conflicts = [];
-  for (const conflict of map.values()) {
-    if (conflict.files.length > 1) {
-      conflicts.push(conflict);
-    }
-  }
-  return conflicts;
+  };
+}
+function buildAliasPlugins(rootDir) {
+  const tsconfig = readTsconfig(rootDir);
+  return [createAliasPlugin(tsconfig ?? { baseUrl: ".", paths: {} }, { rootDir })];
 }
 
-// src/server/createServer.ts
-import {
-  createServer as createHttpServer
-} from "http";
-import { createSecureServer as createHttp2SecureServer } from "http2";
-import { readFileSync } from "fs";
-import { Readable as Readable2 } from "stream";
-import path10 from "path";
-
-// src/router/matchRoute.ts
-function matchRoute(routes, method, path14) {
+// src/cli/compileDevRoutes.ts
+var APP_DIR2 = "src";
+async function compileDevRoutes(options) {
+  const { rootDir, dist, files, logLevel = "silent" } = options;
+  const entryPoints = files ?? await fg([`${APP_DIR2}/**/*.ts`], {
+    cwd: rootDir,
+    onlyFiles: true,
+    absolute: true,
+    ignore: ["**/*.test.ts", "**/*.e2e.test.ts", "**/*.d.ts"]
+  });
+  if (entryPoints.length === 0) {
+    return { compiledFiles: [] };
+  }
+  const absDist = path4.resolve(rootDir, dist);
+  await fs3.promises.mkdir(absDist, { recursive: true });
+  const plugins = buildAliasPlugins(rootDir);
+  const esbuild = await import("esbuild");
+  const outbase = path4.resolve(rootDir, APP_DIR2);
+  const result = await esbuild.build({
+    entryPoints,
+    outdir: absDist,
+    outbase,
+    bundle: false,
+    platform: "node",
+    format: "esm",
+    sourcemap: true,
+    packages: "external",
+    plugins,
+    logLevel,
+    write: false
+  });
+  if (result.outputFiles) {
+    await Promise.all(
+      result.outputFiles.map(async (file) => {
+        await fs3.promises.mkdir(path4.dirname(file.path), { recursive: true });
+        const tmp = `${file.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+        await fs3.promises.writeFile(tmp, file.contents);
+        await fs3.promises.rename(tmp, file.path);
+      })
+    );
+  }
+  return { compiledFiles: entryPoints };
+}
+
+// src/cli/compileOnDemand.ts
+init_generateSchemaFiles();
+init_generateSchemaFiles();
+function isProductFresh(sourceAbsPath, productAbsPath) {
+  try {
+    const srcStat = fs5.statSync(sourceAbsPath);
+    const prodStat = fs5.statSync(productAbsPath);
+    return prodStat.mtimeMs >= srcStat.mtimeMs;
+  } catch {
+    return false;
+  }
+}
+var compiledFiles = /* @__PURE__ */ new Set();
+function clearCompiledFiles() {
+  compiledFiles.clear();
+}
+async function ensureCompiled(sourceAbsPath, rootDir, dist) {
+  if (compiledFiles.has(sourceAbsPath)) {
+    return false;
+  }
+  if (!fs5.existsSync(sourceAbsPath)) {
+    return false;
+  }
+  const productPath = prodSourcePathToProductPath(sourceAbsPath, rootDir, dist);
+  if (productPath && isProductFresh(sourceAbsPath, productPath)) {
+    compiledFiles.add(sourceAbsPath);
+    return false;
+  }
+  await compileDevRoutes({
+    rootDir,
+    dist,
+    files: [sourceAbsPath],
+    logLevel: "silent"
+  });
+  compiledFiles.add(sourceAbsPath);
+  return true;
+}
+function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
+  const rel = path6.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  if (!rel.startsWith("src/")) return null;
+  const relWithoutSrc = rel.slice(4);
+  const jsRel = relWithoutSrc.replace(/\.ts$/, ".js");
+  return path6.resolve(rootDir, dist, jsRel);
+}
+var generatedSchemas = /* @__PURE__ */ new Set();
+function clearGeneratedSchemas() {
+  generatedSchemas.clear();
+}
+async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir, dist) {
+  if (generatedSchemas.has(schemaPath)) {
+    return false;
+  }
+  const prodAbsPath = path6.resolve(rootDir, routeFilePath);
+  const sourceAbsPath = prodPathToSourcePath(prodAbsPath, rootDir, dist);
+  if (!fs5.existsSync(sourceAbsPath)) {
+    return false;
+  }
+  if (isProductFresh(sourceAbsPath, schemaPath)) {
+    generatedSchemas.add(schemaPath);
+    return false;
+  }
+  const fileRoutes = routes.filter((r) => r.filePath === routeFilePath);
+  if (fileRoutes.length === 0) {
+    return false;
+  }
+  const sourceRelPath = path6.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  const sourceRoutes = fileRoutes.map((r) => ({ ...r, filePath: sourceRelPath }));
+  await generateSchemaFiles(sourceRoutes, rootDir, dist);
+  generatedSchemas.add(schemaPath);
+  return true;
+}
+async function deleteSchemaFiles(routes, rootDir, dist) {
+  const deleted = /* @__PURE__ */ new Set();
   for (const route of routes) {
-    if (route.method !== method) {
-      continue;
-    }
-    if (!route.isDynamic) {
-      if (route.urlPath === path14) {
-        return { route, params: {} };
-      }
-      continue;
-    }
-    const params = matchDynamicPath(route.urlPath, path14, route.paramNames, route.isCatchAll);
-    if (params !== null) {
-      return { route, params };
+    const schemaPath = getRuntimeSchemaPath(route.filePath, dist, rootDir);
+    if (deleted.has(schemaPath)) continue;
+    deleted.add(schemaPath);
+    try {
+      await fs5.promises.unlink(schemaPath);
+    } catch {
     }
   }
-  return null;
 }
-function matchWsRoute(wsRoutes, path14) {
-  for (const route of wsRoutes) {
-    if (!route.isDynamic) {
-      if (route.urlPath === path14) {
-        return { route, params: {} };
+function prodPathToSourcePath(prodAbsPath, rootDir, dist) {
+  const rel = path6.relative(rootDir, prodAbsPath).replace(/\\/g, "/");
+  let relWithoutDist = rel;
+  if (relWithoutDist.startsWith(`${dist}/`)) {
+    relWithoutDist = relWithoutDist.slice(dist.length + 1);
+  }
+  const srcRel = `src/${relWithoutDist}`;
+  const tsRel = srcRel.replace(/\.js$/, ".ts");
+  const tsAbs = path6.resolve(rootDir, tsRel);
+  if (fs5.existsSync(tsAbs)) return tsAbs;
+  return path6.resolve(rootDir, srcRel);
+}
+var devOnDemandEnabled = false;
+function isDevOnDemandEnabled() {
+  return devOnDemandEnabled;
+}
+var devDistDir;
+function getDevDist() {
+  return devDistDir;
+}
+
+// src/loader/loadAgentModule.ts
+async function loadAgentModule(filePath, hasConfig, hasRun, rootDir) {
+  if (isDevOnDemandEnabled() && rootDir) {
+    const dist = getDevDist();
+    if (dist) {
+      const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
+      if (sourcePath && fs6.existsSync(sourcePath)) {
+        try {
+          await ensureCompiled(sourcePath, rootDir, dist);
+        } catch (compileErr) {
+          const reason = compileErr instanceof Error ? compileErr.message : String(compileErr);
+          throw new Error(`Failed to compile agent module "${sourcePath}": ${reason}`, {
+            cause: compileErr
+          });
+        }
       }
-      continue;
-    }
-    const params = matchDynamicPath(route.urlPath, path14, route.paramNames, route.isCatchAll);
-    if (params !== null) {
-      return { route, params };
     }
   }
-  return null;
-}
-function matchDynamicPath(pattern, path14, paramNames, isCatchAll) {
-  const patternSegments = pattern.split("/").filter(Boolean);
-  const pathSegments = path14.split("/").filter(Boolean);
-  if (isCatchAll) {
-    const nonCatchAllCount = patternSegments.length - 1;
-    if (pathSegments.length <= nonCatchAllCount) {
-      return null;
+  let module;
+  try {
+    module = await importWithCacheBust(filePath, isDevOnDemandEnabled());
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to load agent module "${filePath}": ${reason}`, { cause: err });
+  }
+  let config;
+  if (hasConfig) {
+    const configExport = resolveExport(module, "config");
+    if (configExport === void 0) {
+      throw new Error(
+        `Agent module "${filePath}" does not export "config" (hasConfig=true but export missing).`
+      );
     }
-    const params2 = {};
-    for (let i = 0; i < nonCatchAllCount; i++) {
-      const patternSeg = patternSegments[i];
-      const pathSeg = pathSegments[i];
-      if (patternSeg.startsWith(":")) {
-        const paramName = patternSeg.slice(1);
-        params2[paramName] = pathSeg;
-      } else if (patternSeg !== pathSeg) {
-        return null;
+    if (typeof configExport === "function") {
+      const returned = configExport();
+      if (returned === null || typeof returned !== "object") {
+        throw new Error(
+          `Agent module "${filePath}" config() did not return an object (got ${returned === null ? "null" : typeof returned}).`
+        );
       }
+      config = returned;
+    } else if (typeof configExport === "object" && configExport !== null) {
+      config = configExport;
+    } else {
+      throw new Error(
+        `Agent module "${filePath}" config export must be an object or function, got ${typeof configExport}.`
+      );
     }
-    const catchAllValue = pathSegments.slice(nonCatchAllCount).join("/");
-    const catchAllParamName = patternSegments[nonCatchAllCount].slice(4);
-    params2[catchAllParamName] = catchAllValue;
-    if (Object.keys(params2).length !== paramNames.length) {
-      return null;
-    }
-    return params2;
-  }
-  if (patternSegments.length !== pathSegments.length) {
-    return null;
   }
-  const params = {};
-  for (let i = 0; i < patternSegments.length; i++) {
-    const patternSeg = patternSegments[i];
-    const pathSeg = pathSegments[i];
-    if (patternSeg.startsWith(":")) {
-      const paramName = patternSeg.slice(1);
-      params[paramName] = pathSeg;
-    } else if (patternSeg !== pathSeg) {
-      return null;
+  let run;
+  if (hasRun) {
+    const runExport = resolveExport(module, "run");
+    if (typeof runExport !== "function") {
+      throw new Error(
+        `Agent module "${filePath}" does not export a valid "run" function (hasRun=true). Expected a function, got ${runExport === void 0 ? "undefined" : typeof runExport}.`
+      );
     }
+    run = runExport;
   }
-  if (Object.keys(params).length !== paramNames.length) {
-    return null;
-  }
-  return params;
+  return { config, run };
 }
 
-// src/loader/loadRouteModule.ts
-import fs8 from "fs";
-
-// src/loader/resolveExports.ts
-function resolveExport(module, exportName) {
-  if (exportName in module && typeof module[exportName] !== "undefined") {
-    return module[exportName];
-  }
-  const defaultExport = module.default;
-  if (defaultExport !== null && typeof defaultExport === "object") {
-    const value = defaultExport[exportName];
-    if (value !== void 0) {
-      return value;
+// src/loader/loadToolModule.ts
+import fs7 from "fs";
+async function loadToolModule(filePath, functionName, rootDir) {
+  if (isDevOnDemandEnabled() && rootDir) {
+    const dist = getDevDist();
+    if (dist) {
+      const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
+      if (sourcePath && fs7.existsSync(sourcePath)) {
+        try {
+          await ensureCompiled(sourcePath, rootDir, dist);
+        } catch (compileErr) {
+          const reason = compileErr instanceof Error ? compileErr.message : String(compileErr);
+          throw new Error(`Failed to compile tool module "${sourcePath}": ${reason}`, {
+            cause: compileErr
+          });
+        }
+      }
     }
   }
-  return void 0;
-}
-
-// src/loader/validateRouteModule.ts
-function validateRouteModule(value, method, filePath) {
-  if (typeof value !== "function") {
+  let module;
+  try {
+    module = await importWithCacheBust(filePath, isDevOnDemandEnabled());
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to load tool module "${filePath}": ${reason}`, { cause: err });
+  }
+  const handler = resolveExport(module, functionName);
+  if (typeof handler !== "function") {
     throw new Error(
-      `Route module "${filePath}" does not export a valid handler for method "${method}". Expected a function, got ${typeof value}.`
+      `Tool module "${filePath}" does not export a valid function for "${functionName}". Expected a function, got ${handler === void 0 ? "undefined" : typeof handler}.`
     );
   }
+  return { handler, functionName };
 }
 
-// src/cli/compileOnDemand.ts
-import path8 from "path";
-import fs7 from "fs";
+// src/loader/loadToolSchema.ts
+import { existsSync as existsSync2 } from "fs";
 
-// src/cli/compileDevRoutes.ts
-import path6 from "path";
-import fs5 from "fs";
-import fg from "fast-glob";
-
-// src/cli/aliasPlugin.ts
-import path5 from "path";
-import fs4 from "fs";
+// src/cli/generateToolArtifacts.ts
+import path7 from "path";
+import fs8 from "fs/promises";
+import { existsSync } from "fs";
 
-// src/utils/resolveAlias.ts
-function resolveAlias(specifier, config) {
-  const candidates = [];
-  for (const [pattern, targets] of Object.entries(config.paths)) {
-    const wildcardIndex = pattern.indexOf("*");
-    if (wildcardIndex === -1) {
-      if (specifier === pattern) {
-        candidates.push(...targets);
-      }
-      continue;
+// src/ast/extractToolMetadata.ts
+import ts7 from "typescript";
+function extractToolMetadata(program, filePath, functionName, pathMeta) {
+  const sourceFile = program.getSourceFile(filePath);
+  if (!sourceFile) return null;
+  const found = findExportedFunction(sourceFile, functionName);
+  if (!found) return null;
+  const { fn, jsDocOwner } = found;
+  const jsDoc = getJSDocFromNode(jsDocOwner);
+  const description = extractDescription(jsDoc);
+  const toolNameOverride = extractToolTagValue(jsDoc);
+  const inputTypeName = getFirstParamTypeName(fn, sourceFile);
+  return {
+    name: toolNameOverride ?? pathMeta.name,
+    description,
+    inputTypeName,
+    filePath: pathMeta.filePath,
+    functionName
+  };
+}
+function findExportedFunction(sourceFile, functionName) {
+  let result = null;
+  ts7.forEachChild(sourceFile, (node) => {
+    if (result) return;
+    if (ts7.isFunctionDeclaration(node) && hasExportModifier(node) && node.name?.text === functionName) {
+      result = { fn: node, jsDocOwner: node };
+      return;
     }
-    const prefix = pattern.slice(0, wildcardIndex);
-    const suffix = pattern.slice(wildcardIndex + 1);
-    if (specifier.startsWith(prefix) && specifier.endsWith(suffix) && specifier.length >= prefix.length + suffix.length) {
-      const captured = specifier.slice(prefix.length, specifier.length - suffix.length);
-      for (const target of targets) {
-        candidates.push(target.replace("*", captured));
+    if (ts7.isVariableStatement(node) && hasExportModifier(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (result) break;
+        const nameText = ts7.isIdentifier(decl.name) ? decl.name.text : decl.name.getText(sourceFile);
+        if (nameText !== functionName || !decl.initializer) continue;
+        if (ts7.isArrowFunction(decl.initializer) || ts7.isFunctionExpression(decl.initializer)) {
+          result = { fn: decl.initializer, jsDocOwner: node };
+        }
       }
     }
-  }
-  return candidates;
+  });
+  return result;
 }
-
-// src/utils/readTsconfig.ts
-import ts6 from "typescript";
-import path4 from "path";
-import fs3 from "fs";
-function readTsconfig(rootDir) {
-  const tsconfigPath = path4.resolve(rootDir, "tsconfig.json");
-  if (!fs3.existsSync(tsconfigPath)) return null;
-  const configFile = ts6.readConfigFile(tsconfigPath, ts6.sys.readFile);
-  if (configFile.error || !configFile.config) return null;
-  const parsed = ts6.parseJsonConfigFileContent(configFile.config, ts6.sys, rootDir);
-  const baseUrl = parsed.options.baseUrl ?? rootDir;
-  const rawPaths = parsed.options.paths;
-  if (!rawPaths) return null;
-  const paths = {};
-  for (const [pattern, targets] of Object.entries(rawPaths)) {
-    paths[pattern] = targets.map((t) => path4.resolve(baseUrl, t));
+function hasExportModifier(node) {
+  if (!ts7.canHaveModifiers(node)) return false;
+  const modifiers = ts7.getModifiers(node);
+  return !!modifiers?.some((m) => m.kind === ts7.SyntaxKind.ExportKeyword);
+}
+function getJSDocFromNode(node) {
+  const apiDocs = ts7.getJSDocCommentsAndTags(node).filter((entry) => ts7.isJSDoc(entry));
+  if (apiDocs.length > 0) return apiDocs[0];
+  const directDocs = node.jsDoc;
+  if (directDocs && directDocs.length > 0) return directDocs[0];
+  return void 0;
+}
+function extractDescription(jsDoc) {
+  if (!jsDoc) return void 0;
+  if (typeof jsDoc.comment !== "string") return void 0;
+  const trimmed = jsDoc.comment.trim();
+  return trimmed || void 0;
+}
+function extractToolTagValue(jsDoc) {
+  if (!jsDoc || !jsDoc.tags) return void 0;
+  for (const tag of jsDoc.tags) {
+    if (tag.tagName.text !== "tool") continue;
+    if (typeof tag.comment !== "string") return void 0;
+    const text = tag.comment.trim();
+    if (!text) return void 0;
+    const cleaned = text.replace(/^\{|\}$/g, "").trim();
+    return cleaned || void 0;
   }
-  return { baseUrl, paths };
+  return void 0;
+}
+function getFirstParamTypeName(fn, sourceFile) {
+  const firstParam = fn.parameters[0];
+  if (!firstParam) return void 0;
+  if (!firstParam.type) return void 0;
+  if (!ts7.isTypeReferenceNode(firstParam.type)) return void 0;
+  return firstParam.type.typeName.getText(sourceFile);
 }
 
-// src/cli/aliasPlugin.ts
-function toProdExtension(filePath) {
-  if (filePath.endsWith(".ts")) return filePath.slice(0, -3) + ".js";
-  if (filePath.endsWith(".tsx")) return filePath.slice(0, -4) + ".js";
-  if (filePath.endsWith(".jsx")) return filePath.slice(0, -4) + ".js";
-  return filePath;
+// src/cli/generateToolArtifacts.ts
+init_createProgram();
+init_extractHandlerTypes();
+init_generateZodSchema();
+init_generateSchemaFiles();
+var TOOLS_FILE = "faapi-tools.js";
+function getToolSchemaOutputPath(sourceFile, dist, rootDir) {
+  let rel = sourceFile.replace(/\\/g, "/");
+  if (rel.startsWith("src/")) {
+    rel = rel.slice(4);
+  }
+  const idx = rel.lastIndexOf("/");
+  const relDir = idx >= 0 ? rel.slice(0, idx) : "";
+  return path7.resolve(rootDir, dist, relDir, "zod.js");
 }
-function toProdImportPath(sourceFile, importer) {
-  const importerDir = path5.dirname(importer);
-  let rel = path5.relative(importerDir, sourceFile);
-  rel = rel.split(path5.sep).join("/");
-  if (!rel.startsWith(".")) rel = "./" + rel;
-  return toProdExtension(rel);
+function getRuntimeToolSchemaPath(filePath, dist, rootDir) {
+  let rel = filePath.replace(/\\/g, "/");
+  if (rel.startsWith("src/")) {
+    rel = rel.slice(4);
+  } else if (rel.startsWith(`${dist}/`)) {
+    rel = rel.slice(dist.length + 1);
+  }
+  const idx = rel.lastIndexOf("/");
+  const relDir = idx >= 0 ? rel.slice(0, idx) : "";
+  return path7.resolve(rootDir, dist, relDir, "zod.js");
 }
-function toRealPath(p) {
-  try {
-    return fs4.realpathSync(p);
-  } catch {
-    return p;
+function toProdFilePath(filePath, dist) {
+  let rel = filePath.replace(/\\/g, "/");
+  if (rel.startsWith("src/")) {
+    rel = rel.slice(4);
   }
+  const jsPath = rel.replace(/\.ts$/, ".js");
+  return jsPath.startsWith(`${dist}/`) ? jsPath : `${dist}/${jsPath}`;
 }
-function isInsideDir(filePath, dir) {
-  const rel = path5.relative(dir, filePath);
-  return rel !== "" && !rel.startsWith("..") && !path5.isAbsolute(rel);
+function serializeTools(tools, dist = "dist") {
+  return tools.map((t) => ({
+    name: t.name,
+    functionName: t.functionName,
+    description: t.description,
+    inputTypeName: t.inputTypeName,
+    filePath: toProdFilePath(t.filePath, dist)
+  }));
+}
+async function writeToolsModule(manifest, outputPath) {
+  const dir = path7.dirname(outputPath);
+  await fs8.mkdir(dir, { recursive: true });
+  const content = `// \u81EA\u52A8\u751F\u6210,\u8BF7\u52FF\u624B\u52A8\u7F16\u8F91(faapi build/dev \u4EA7\u7269)
+export const tools = ${JSON.stringify(manifest, null, 2)};
+`;
+  await fs8.writeFile(outputPath, content, "utf-8");
+}
+function hydrateTools(manifest) {
+  return manifest.map((t) => ({
+    name: t.name,
+    functionName: t.functionName,
+    description: t.description ?? void 0,
+    inputTypeName: t.inputTypeName ?? void 0,
+    filePath: t.filePath
+  }));
+}
+function collectToolSchemaSources(tools, rootDir) {
+  const toolsByFile = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    if (!tool.inputTypeName) continue;
+    const absPath = path7.resolve(rootDir, tool.filePath);
+    let list = toolsByFile.get(absPath);
+    if (!list) {
+      list = [];
+      toolsByFile.set(absPath, list);
+    }
+    list.push(tool);
+  }
+  const allTypesByFile = /* @__PURE__ */ new Map();
+  for (const filePath of toolsByFile.keys()) {
+    const program = createProgram(filePath);
+    const allTypes = extractAllTypes(program, filePath);
+    allTypesByFile.set(filePath, allTypes);
+  }
+  const sources = [];
+  for (const [filePath, fileTools] of toolsByFile) {
+    const program = createProgram(filePath);
+    for (const tool of fileTools) {
+      const inputTypeName = tool.inputTypeName;
+      const typeInfo = extractTypeInfo(program, filePath, inputTypeName);
+      sources.push({
+        name: tool.name,
+        filePath,
+        schemaName: inputTypeName,
+        // schema 名 = inputTypeName
+        typeInfo
+      });
+    }
+  }
+  return { sources, allTypesByFile };
 }
-var APP_DIR = "src";
-function toStrippedProdImportPath(sourceFile, rootDir) {
-  const appDirAbs = toRealPath(path5.resolve(rootDir, APP_DIR));
-  const sourceReal = toRealPath(sourceFile);
-  let rel = path5.relative(appDirAbs, sourceReal);
-  rel = rel.split(path5.sep).join("/");
-  if (!rel.startsWith(".")) rel = "./" + rel;
-  return toProdExtension(rel);
+function generateToolSchemaFileSource(sources, allTypes, helpersImportPath) {
+  const resolveType = (name) => allTypes.get(name)?.runtimeType;
+  const lines = ["import { z } from 'zod';"];
+  const schemaBlocks = [];
+  for (const source of sources) {
+    const { schemaName, typeInfo } = source;
+    if (!typeInfo) {
+      continue;
+    }
+    const coerce = false;
+    const block = [`// ${source.name} \u2192 ${schemaName}`];
+    const schemaCode = generateZodSchemaSource(typeInfo, resolveType, schemaName, coerce).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");
 }
-var PROD_EXTS = [".js", ".mjs", ".cjs"];
-var SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
-var INDEX_EXTS = [
-  "/index.ts",
-  "/index.tsx",
-  "/index.js",
-  "/index.jsx",
-  "/index.mjs",
-  "/index.cjs"
-];
-function resolveRelativeSpecifier(importer, specifier) {
-  const importerDir = path5.dirname(importer);
-  const base = path5.resolve(importerDir, specifier);
-  if (PROD_EXTS.some((ext) => specifier.endsWith(ext))) {
-    return fs4.existsSync(base) ? base : null;
+async function maybeGenerateHelpers(allSourceCode, distDir) {
+  if (!usesCoerceHelpers(allSourceCode)) return;
+  const helpersPath = path7.resolve(distDir, HELPERS_FILENAME);
+  if (existsSync(helpersPath)) return;
+  await fs8.mkdir(path7.dirname(helpersPath), { recursive: true });
+  await fs8.writeFile(helpersPath, generateHelpersFileSource(), "utf-8");
+}
+async function generateToolArtifacts(tools, rootDir, dist, options) {
+  const metadata = [];
+  for (const manifest of tools) {
+    const absPath = path7.resolve(rootDir, manifest.filePath);
+    const program = createProgram(absPath);
+    const result = extractToolMetadata(program, absPath, manifest.functionName, {
+      name: manifest.name,
+      filePath: manifest.filePath
+    });
+    if (result) {
+      metadata.push(result);
+    }
   }
-  if (/\.(ts|tsx|jsx)$/.test(specifier)) {
-    return fs4.existsSync(base) ? base : null;
+  const serialized = serializeTools(metadata, dist);
+  const toolsPath = path7.resolve(rootDir, dist, TOOLS_FILE);
+  await writeToolsModule(serialized, toolsPath);
+  if (options?.skipSchema) {
+    return metadata;
   }
-  for (const ext of SOURCE_EXTS) {
-    const file = base + ext;
-    if (fs4.existsSync(file)) return file;
+  if (metadata.length === 0) {
+    return metadata;
   }
-  for (const indexExt of INDEX_EXTS) {
-    const file = base + indexExt;
-    if (fs4.existsSync(file)) return file;
+  const { sources, allTypesByFile } = collectToolSchemaSources(metadata, rootDir);
+  if (sources.length === 0) {
+    return metadata;
   }
-  return null;
+  const sourcesByFile = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    let list = sourcesByFile.get(source.filePath);
+    if (!list) {
+      list = [];
+      sourcesByFile.set(source.filePath, list);
+    }
+    list.push(source);
+  }
+  const fileEntries = [];
+  for (const [filePath, fileSources] of sourcesByFile) {
+    const relFile = path7.relative(rootDir, filePath).replace(/\\/g, "/");
+    const outputPath = getToolSchemaOutputPath(relFile, dist, rootDir);
+    const allTypes = allTypesByFile.get(filePath) ?? /* @__PURE__ */ new Map();
+    let relForDir = relFile;
+    if (relForDir.startsWith("src/")) {
+      relForDir = relForDir.slice(4);
+    }
+    const dirIdx = relForDir.lastIndexOf("/");
+    const zodRelDir = dirIdx >= 0 ? relForDir.slice(0, dirIdx) : "";
+    const helpersImportPath = getHelpersImportPath(zodRelDir);
+    const source = generateToolSchemaFileSource(fileSources, allTypes, helpersImportPath);
+    fileEntries.push({ outputPath, source });
+  }
+  const allSourceCode = fileEntries.map((e) => e.source).join("\n");
+  const distDir = path7.resolve(rootDir, dist);
+  await maybeGenerateHelpers(allSourceCode, distDir);
+  await Promise.all(
+    fileEntries.map(({ outputPath, source }) => writeToolSchemaFile(outputPath, source))
+  );
+  return metadata;
 }
-function createAliasPlugin(config, options) {
-  const SPEC_RE = /(\bfrom\s*|import\s*\(\s*)(['"])([^'"]+)\2/g;
-  const appDirAbs = options?.rootDir ? toRealPath(path5.resolve(options.rootDir, APP_DIR)) : null;
-  return {
-    name: "faapi-alias",
-    setup(build) {
-      build.onLoad({ filter: /\.(ts|tsx|js|jsx|mjs|cjs)$/ }, (args) => {
-        let source;
-        try {
-          source = fs4.readFileSync(args.path, "utf8");
-        } catch {
-          return void 0;
+async function writeToolSchemaFile(outputPath, source) {
+  await fs8.mkdir(path7.dirname(outputPath), { recursive: true });
+  await fs8.writeFile(outputPath, source, "utf-8");
+}
+
+// src/loader/loadToolSchema.ts
+function getDist() {
+  if (isDevOnDemandEnabled()) {
+    return getDevDist() ?? ".faapi";
+  }
+  return process.env.FAAPI_DIST ?? "dist";
+}
+async function loadToolSchema(tool, rootDir) {
+  if (!tool.inputTypeName) return void 0;
+  const schemaName = `${tool.inputTypeName}Schema`;
+  const dist = getDist();
+  const zodPath = getRuntimeToolSchemaPath(tool.filePath, dist, rootDir ?? process.cwd());
+  if (!existsSync2(zodPath)) return void 0;
+  try {
+    const mod = await importWithCacheBust(zodPath, isDevOnDemandEnabled());
+    const schema = mod[`${tool.inputTypeName}Schema`];
+    if (!schema) return void 0;
+    return { schema, schemaName };
+  } catch {
+    return void 0;
+  }
+}
+
+// src/injection/agentHandle.ts
+var currentFactory = null;
+function registerAgentHandleFactory(factory) {
+  currentFactory = factory;
+}
+function getAgentHandle(ctx) {
+  if (currentFactory === null) return void 0;
+  return currentFactory(ctx);
+}
+function clearAgentHandleFactory() {
+  currentFactory = null;
+}
+
+// src/middleware/cors.ts
+var DEFAULT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+function cors(options = {}) {
+  const {
+    origin = true,
+    methods = DEFAULT_METHODS,
+    allowedHeaders,
+    exposeHeaders,
+    credentials = false,
+    maxAge
+  } = options;
+  return async (ctx, next) => {
+    const reqOrigin = ctx.headers.get("origin");
+    if (!reqOrigin) {
+      await next();
+      return;
+    }
+    let allowOrigin = null;
+    if (origin === true) {
+      allowOrigin = reqOrigin;
+    } else if (typeof origin === "string") {
+      allowOrigin = reqOrigin === origin ? origin : null;
+    } else if (Array.isArray(origin)) {
+      allowOrigin = origin.includes(reqOrigin) ? reqOrigin : null;
+    }
+    if (!allowOrigin) {
+      await next();
+      return;
+    }
+    ctx.setHeader("Access-Control-Allow-Origin", allowOrigin);
+    if (origin === true || Array.isArray(origin)) {
+      const existingVary = ctx.headers.get("vary");
+      if (existingVary) {
+        if (!existingVary.toLowerCase().includes("origin")) {
+          ctx.setHeader("Vary", `${existingVary}, Origin`);
         }
-        const importer = args.path;
-        const importerOutsideAppDir = appDirAbs ? !isInsideDir(importer, appDirAbs) : false;
-        let modified = false;
-        const newSource = source.replace(SPEC_RE, (full, prefix, quote, specifier) => {
-          if (specifier.startsWith("/") || specifier.startsWith("file:") || specifier.startsWith("node:")) {
-            return full;
-          }
-          if (specifier.startsWith("./") || specifier.startsWith("../")) {
-            const resolved = resolveRelativeSpecifier(importer, specifier);
-            if (resolved) {
-              if (PROD_EXTS.some((ext) => specifier.endsWith(ext))) {
-                return full;
-              }
-              if (appDirAbs && importerOutsideAppDir && isInsideDir(resolved, appDirAbs)) {
-                modified = true;
-                return `${prefix}${quote}${toStrippedProdImportPath(
-                  resolved,
-                  options.rootDir
-                )}${quote}`;
-              }
-              modified = true;
-              return `${prefix}${quote}${toProdImportPath(resolved, importer)}${quote}`;
-            }
-            return full;
-          }
-          const candidates = resolveAlias(specifier, config);
-          for (const candidate of candidates) {
-            for (const ext of SOURCE_EXTS) {
-              const file = candidate + ext;
-              if (fs4.existsSync(file)) {
-                modified = true;
-                if (appDirAbs && importerOutsideAppDir && isInsideDir(file, appDirAbs)) {
-                  return `${prefix}${quote}${toStrippedProdImportPath(
-                    file,
-                    options.rootDir
-                  )}${quote}`;
-                }
-                return `${prefix}${quote}${toProdImportPath(file, importer)}${quote}`;
-              }
-            }
-            for (const indexExt of INDEX_EXTS) {
-              const file = candidate + indexExt;
-              if (fs4.existsSync(file)) {
-                modified = true;
-                if (appDirAbs && importerOutsideAppDir && isInsideDir(file, appDirAbs)) {
-                  return `${prefix}${quote}${toStrippedProdImportPath(
-                    file,
-                    options.rootDir
-                  )}${quote}`;
-                }
-                return `${prefix}${quote}${toProdImportPath(file, importer)}${quote}`;
-              }
-            }
-          }
-          return full;
-        });
-        if (!modified) return void 0;
-        return { contents: newSource, loader: "default" };
-      });
+      } else {
+        ctx.setHeader("Vary", "Origin");
+      }
+    }
+    ctx.setHeader("Access-Control-Allow-Methods", methods.join(", "));
+    if (allowedHeaders) {
+      ctx.setHeader("Access-Control-Allow-Headers", allowedHeaders.join(", "));
+    } else {
+      const requestHeaders = ctx.headers.get("access-control-request-headers");
+      if (requestHeaders) {
+        ctx.setHeader("Access-Control-Allow-Headers", requestHeaders);
+      }
+    }
+    if (exposeHeaders && exposeHeaders.length > 0) {
+      ctx.setHeader("Access-Control-Expose-Headers", exposeHeaders.join(", "));
+    }
+    if (credentials) {
+      ctx.setHeader("Access-Control-Allow-Credentials", "true");
+    }
+    if (maxAge !== void 0) {
+      ctx.setHeader("Access-Control-Max-Age", String(maxAge));
+    }
+    if (ctx.method === "OPTIONS") {
+      return new Response(null, { status: 204 });
+    }
+    await next();
+  };
+}
+
+// src/middleware/logger.ts
+function logger(options = {}) {
+  return async (ctx, next) => {
+    const log = options.log ?? console.log;
+    const start = Date.now();
+    try {
+      const response = await next();
+      const duration = Date.now() - start;
+      const entry = {
+        method: ctx.method,
+        path: ctx.path,
+        status: response.status,
+        durationMs: duration
+      };
+      log(entry, `${ctx.method} ${ctx.path} ${response.status} ${duration}ms`);
+      return response;
+    } catch (err) {
+      const duration = Date.now() - start;
+      const message = err instanceof Error ? err.message : String(err);
+      const status = err?.statusCode ?? 500;
+      const entry = {
+        method: ctx.method,
+        path: ctx.path,
+        status,
+        durationMs: duration,
+        error: message
+      };
+      log(entry, `${ctx.method} ${ctx.path} ${status} ${duration}ms - ${message}`);
+      throw err;
+    }
+  };
+}
+
+// src/middleware/helmet.ts
+var DEFAULTS = {
+  contentSecurityPolicy: "default-src 'self'",
+  xFrameOptions: "SAMEORIGIN",
+  xContentTypeOptions: true,
+  referrerPolicy: "no-referrer",
+  strictTransportSecurity: "max-age=31536000; includeSubDomains",
+  xDnsPrefetchControl: true,
+  xDownloadOptions: true,
+  xPermittedCrossDomainPolicies: "none",
+  crossOriginOpenerPolicy: "same-origin",
+  crossOriginResourcePolicy: "same-origin",
+  crossOriginEmbedderPolicy: false,
+  originAgentCluster: true,
+  xPoweredBy: true
+};
+function helmet(options = {}) {
+  const opts = { ...DEFAULTS, ...options };
+  return async (ctx, next) => {
+    if (opts.contentSecurityPolicy !== false) {
+      ctx.setHeader("Content-Security-Policy", opts.contentSecurityPolicy);
+    }
+    if (opts.xFrameOptions !== false) {
+      ctx.setHeader("X-Frame-Options", opts.xFrameOptions);
+    }
+    if (opts.xContentTypeOptions) {
+      ctx.setHeader("X-Content-Type-Options", "nosniff");
+    }
+    if (opts.referrerPolicy !== false) {
+      ctx.setHeader("Referrer-Policy", opts.referrerPolicy);
+    }
+    if (opts.strictTransportSecurity !== false) {
+      ctx.setHeader("Strict-Transport-Security", opts.strictTransportSecurity);
+    }
+    if (opts.xDnsPrefetchControl) {
+      ctx.setHeader("X-DNS-Prefetch-Control", "off");
+    }
+    if (opts.xDownloadOptions) {
+      ctx.setHeader("X-Download-Options", "noopen");
+    }
+    if (opts.xPermittedCrossDomainPolicies !== false) {
+      ctx.setHeader("X-Permitted-Cross-Domain-Policies", opts.xPermittedCrossDomainPolicies);
+    }
+    if (opts.crossOriginOpenerPolicy !== false) {
+      ctx.setHeader("Cross-Origin-Opener-Policy", opts.crossOriginOpenerPolicy);
+    }
+    if (opts.crossOriginResourcePolicy !== false) {
+      ctx.setHeader("Cross-Origin-Resource-Policy", opts.crossOriginResourcePolicy);
+    }
+    if (opts.crossOriginEmbedderPolicy !== false) {
+      ctx.setHeader("Cross-Origin-Embedder-Policy", opts.crossOriginEmbedderPolicy);
+    }
+    if (opts.originAgentCluster) {
+      ctx.setHeader("Origin-Agent-Cluster", "?1");
+    }
+    if (opts.xPoweredBy) {
+      ctx.setHeader("X-Powered-By", "faapi");
     }
+    return await next();
   };
 }
-function buildAliasPlugins(rootDir) {
-  const tsconfig = readTsconfig(rootDir);
-  return [createAliasPlugin(tsconfig ?? { baseUrl: ".", paths: {} }, { rootDir })];
-}
 
-// src/cli/compileDevRoutes.ts
-var APP_DIR2 = "src";
-async function compileDevRoutes(options) {
-  const { rootDir, dist, files, logLevel = "silent" } = options;
-  const entryPoints = files ?? await fg([`${APP_DIR2}/**/*.ts`], {
-    cwd: rootDir,
-    onlyFiles: true,
-    absolute: true,
-    ignore: ["**/*.test.ts", "**/*.e2e.test.ts", "**/*.d.ts"]
-  });
-  if (entryPoints.length === 0) {
-    return { compiledFiles: [] };
+// src/config/loadConfig.ts
+import path8 from "path";
+import fs9 from "fs";
+var CONFIG_PRODUCT_FILE = "faapi-config.js";
+async function loadConfig(rootDir, dist) {
+  const configProductPath = path8.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
+  if (fs9.existsSync(configProductPath)) {
+    const module = await importWithCacheBust(configProductPath);
+    return module.default ?? {};
   }
-  const absDist = path6.resolve(rootDir, dist);
-  await fs5.promises.mkdir(absDist, { recursive: true });
-  const plugins = buildAliasPlugins(rootDir);
-  const esbuild = await import("esbuild");
-  const outbase = path6.resolve(rootDir, APP_DIR2);
-  const result = await esbuild.build({
-    entryPoints,
-    outdir: absDist,
-    outbase,
-    bundle: false,
-    platform: "node",
-    format: "esm",
-    sourcemap: true,
-    packages: "external",
-    plugins,
-    logLevel,
-    write: false
-  });
-  if (result.outputFiles) {
-    await Promise.all(
-      result.outputFiles.map(async (file) => {
-        await fs5.promises.mkdir(path6.dirname(file.path), { recursive: true });
-        const tmp = `${file.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-        await fs5.promises.writeFile(tmp, file.contents);
-        await fs5.promises.rename(tmp, file.path);
-      })
+  const hasSourceConfig = fs9.existsSync(path8.join(rootDir, "faapi.config.ts")) || fs9.existsSync(path8.join(rootDir, "faapi.config.js"));
+  if (hasSourceConfig) {
+    throw new Error(
+      `[faapi] ${dist}/${CONFIG_PRODUCT_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
     );
   }
-  return { compiledFiles: entryPoints };
+  return null;
 }
 
-// src/cli/compileOnDemand.ts
-init_generateSchemaFiles();
-init_generateSchemaFiles();
-function isProductFresh(sourceAbsPath, productAbsPath) {
-  try {
-    const srcStat = fs7.statSync(sourceAbsPath);
-    const prodStat = fs7.statSync(productAbsPath);
-    return prodStat.mtimeMs >= srcStat.mtimeMs;
-  } catch {
-    return false;
-  }
+// src/cli/loadEnv.ts
+import fs10 from "fs";
+import path9 from "path";
+function resolveEnv() {
+  return process.env.NODE_ENV || "development";
 }
-var compiledFiles = /* @__PURE__ */ new Set();
-function clearCompiledFiles() {
-  compiledFiles.clear();
+function getEnvFiles(env) {
+  return [".env", ".env.local", `.env.${env}`, `.env.${env}.local`];
 }
-async function ensureCompiled(sourceAbsPath, rootDir, dist) {
-  if (compiledFiles.has(sourceAbsPath)) {
-    return false;
+function parseEnvFile(content, fileVars) {
+  const result = {};
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(trimmed);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    const value = parseValue(rawValue, { ...fileVars, ...result });
+    result[key] = value;
   }
-  if (!fs7.existsSync(sourceAbsPath)) {
-    return false;
+  return result;
+}
+function parseValue(raw, env) {
+  if (raw === "") return "";
+  if (raw[0] === "'") {
+    const end = raw.indexOf("'", 1);
+    return end === -1 ? raw.slice(1) : raw.slice(1, end);
   }
-  const productPath = prodSourcePathToProductPath(sourceAbsPath, rootDir, dist);
-  if (productPath && isProductFresh(sourceAbsPath, productPath)) {
-    compiledFiles.add(sourceAbsPath);
-    return false;
+  if (raw[0] === '"') {
+    const match = /^"((?:\\.|[^"\\])*)"/.exec(raw);
+    const inner = match ? match[1] : raw.slice(1);
+    return expandEscapesAndVars(inner, env);
   }
-  await compileDevRoutes({
-    rootDir,
-    dist,
-    files: [sourceAbsPath],
-    logLevel: "silent"
+  const commentMatch = /^(.*?)(\s+#.*)$/.exec(raw);
+  const value = commentMatch ? commentMatch[1] : raw;
+  return value.trim();
+}
+function expandEscapesAndVars(str, env) {
+  const escaped = str.replace(/\\(.)/g, (_, ch) => {
+    switch (ch) {
+      case "n":
+        return "\n";
+      case "r":
+        return "\r";
+      case "t":
+        return "	";
+      case "\\":
+        return "\\";
+      case '"':
+        return '"';
+      default:
+        return ch;
+    }
   });
-  compiledFiles.add(sourceAbsPath);
-  return true;
+  return escaped.replace(
+    /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g,
+    (_, braced, plain) => {
+      const varName = braced || plain;
+      return env[varName] ?? process.env[varName] ?? "";
+    }
+  );
 }
-function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
-  const rel = path8.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
-  if (!rel.startsWith("src/")) return null;
-  const relWithoutSrc = rel.slice(4);
-  const jsRel = relWithoutSrc.replace(/\.ts$/, ".js");
-  return path8.resolve(rootDir, dist, jsRel);
+function loadEnv(rootDir) {
+  const env = resolveEnv();
+  const files = getEnvFiles(env);
+  const merged = {};
+  for (const file of files) {
+    const filePath = path9.join(rootDir, file);
+    if (!fs10.existsSync(filePath)) continue;
+    const content = fs10.readFileSync(filePath, "utf-8");
+    const parsed = parseEnvFile(content, merged);
+    Object.assign(merged, parsed);
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    if (process.env[key] === void 0) {
+      process.env[key] = value;
+    }
+  }
 }
-var generatedSchemas = /* @__PURE__ */ new Set();
-function clearGeneratedSchemas() {
-  generatedSchemas.clear();
+
+// src/errors/FaapiError.ts
+var FaapiError = class extends Error {
+  constructor(code, message, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = "FaapiError";
+  }
+  code;
+  statusCode;
+};
+
+// src/errors/httpErrors.ts
+function deriveStatusCode(issues) {
+  const has400 = issues.some((i) => i.code === "INVALID_FORMAT" || i.code === "MISSING_FIELD");
+  return has400 ? 400 : 422;
 }
-async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir, dist) {
-  if (generatedSchemas.has(schemaPath)) {
-    return false;
+var ValidationError = class extends FaapiError {
+  constructor(message, issues) {
+    super("VALIDATION_ERROR", message, deriveStatusCode(issues));
+    this.issues = issues;
+    this.name = "ValidationError";
   }
-  const prodAbsPath = path8.resolve(rootDir, routeFilePath);
-  const sourceAbsPath = prodPathToSourcePath(prodAbsPath, rootDir, dist);
-  if (!fs7.existsSync(sourceAbsPath)) {
-    return false;
+  issues;
+};
+var RouteNotFoundError = class extends FaapiError {
+  constructor(path18) {
+    super("ROUTE_NOT_FOUND", `Route not found: ${path18}`, 404);
+    this.name = "RouteNotFoundError";
   }
-  if (isProductFresh(sourceAbsPath, schemaPath)) {
-    generatedSchemas.add(schemaPath);
-    return false;
+};
+var MethodNotAllowedError = class extends FaapiError {
+  constructor(method, path18, allowedMethods) {
+    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path18}`, 405);
+    this.allowedMethods = allowedMethods;
+    this.name = "MethodNotAllowedError";
   }
-  const fileRoutes = routes.filter((r) => r.filePath === routeFilePath);
-  if (fileRoutes.length === 0) {
-    return false;
+  allowedMethods;
+};
+var InternalError = class extends FaapiError {
+  constructor(message) {
+    super("INTERNAL_ERROR", message, 500);
+    this.name = "InternalError";
+  }
+};
+var ModuleLoadError = class extends FaapiError {
+  constructor(filePath, reason) {
+    super("MODULE_LOAD_ERROR", `Failed to load module ${filePath}: ${reason}`, 500);
+    this.name = "ModuleLoadError";
+  }
+};
+
+// src/cli/createAppCore.ts
+import fs15 from "fs";
+import path14 from "path";
+import { PassThrough, Readable as Readable3 } from "stream";
+
+// src/router/sortRoutes.ts
+function sortRoutes(routes) {
+  return [...routes].sort((a, b) => {
+    if (a.isDynamic !== b.isDynamic) {
+      return a.isDynamic ? 1 : -1;
+    }
+    if (a.isCatchAll !== b.isCatchAll) {
+      return a.isCatchAll ? 1 : -1;
+    }
+    const aSegments = a.urlPath.split("/").filter(Boolean).length;
+    const bSegments = b.urlPath.split("/").filter(Boolean).length;
+    if (aSegments !== bSegments) {
+      return aSegments - bSegments;
+    }
+    return a.urlPath.localeCompare(b.urlPath);
+  });
+}
+
+// src/router/detectRouteConflicts.ts
+function detectRouteConflicts(routes) {
+  const map = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const key = `${route.method} ${route.urlPath}`;
+    const existing = map.get(key);
+    if (existing) {
+      existing.files.push(route.filePath);
+    } else {
+      map.set(key, {
+        method: route.method,
+        urlPath: route.urlPath,
+        files: [route.filePath]
+      });
+    }
+  }
+  const conflicts = [];
+  for (const conflict of map.values()) {
+    if (conflict.files.length > 1) {
+      conflicts.push(conflict);
+    }
   }
-  const sourceRelPath = path8.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
-  const sourceRoutes = fileRoutes.map((r) => ({ ...r, filePath: sourceRelPath }));
-  await generateSchemaFiles(sourceRoutes, rootDir, dist);
-  generatedSchemas.add(schemaPath);
-  return true;
+  return conflicts;
 }
-async function deleteSchemaFiles(routes, rootDir, dist) {
-  const deleted = /* @__PURE__ */ new Set();
+
+// src/server/createServer.ts
+import {
+  createServer as createHttpServer
+} from "http";
+import { createSecureServer as createHttp2SecureServer } from "http2";
+import { readFileSync } from "fs";
+import { Readable as Readable2 } from "stream";
+import path11 from "path";
+
+// src/router/matchRoute.ts
+function matchRoute(routes, method, path18) {
   for (const route of routes) {
-    const schemaPath = getRuntimeSchemaPath(route.filePath, dist, rootDir);
-    if (deleted.has(schemaPath)) continue;
-    deleted.add(schemaPath);
-    try {
-      await fs7.promises.unlink(schemaPath);
-    } catch {
+    if (route.method !== method) {
+      continue;
+    }
+    if (!route.isDynamic) {
+      if (route.urlPath === path18) {
+        return { route, params: {} };
+      }
+      continue;
+    }
+    const params = matchDynamicPath(route.urlPath, path18, route.paramNames, route.isCatchAll);
+    if (params !== null) {
+      return { route, params };
     }
   }
+  return null;
 }
-function prodPathToSourcePath(prodAbsPath, rootDir, dist) {
-  const rel = path8.relative(rootDir, prodAbsPath).replace(/\\/g, "/");
-  let relWithoutDist = rel;
-  if (relWithoutDist.startsWith(`${dist}/`)) {
-    relWithoutDist = relWithoutDist.slice(dist.length + 1);
+function matchWsRoute(wsRoutes, path18) {
+  for (const route of wsRoutes) {
+    if (!route.isDynamic) {
+      if (route.urlPath === path18) {
+        return { route, params: {} };
+      }
+      continue;
+    }
+    const params = matchDynamicPath(route.urlPath, path18, route.paramNames, route.isCatchAll);
+    if (params !== null) {
+      return { route, params };
+    }
   }
-  const srcRel = `src/${relWithoutDist}`;
-  const tsRel = srcRel.replace(/\.js$/, ".ts");
-  const tsAbs = path8.resolve(rootDir, tsRel);
-  if (fs7.existsSync(tsAbs)) return tsAbs;
-  return path8.resolve(rootDir, srcRel);
+  return null;
 }
-var devOnDemandEnabled = false;
-function isDevOnDemandEnabled() {
-  return devOnDemandEnabled;
+function matchDynamicPath(pattern, path18, paramNames, isCatchAll) {
+  const patternSegments = pattern.split("/").filter(Boolean);
+  const pathSegments = path18.split("/").filter(Boolean);
+  if (isCatchAll) {
+    const nonCatchAllCount = patternSegments.length - 1;
+    if (pathSegments.length <= nonCatchAllCount) {
+      return null;
+    }
+    const params2 = {};
+    for (let i = 0; i < nonCatchAllCount; i++) {
+      const patternSeg = patternSegments[i];
+      const pathSeg = pathSegments[i];
+      if (patternSeg.startsWith(":")) {
+        const paramName = patternSeg.slice(1);
+        params2[paramName] = pathSeg;
+      } else if (patternSeg !== pathSeg) {
+        return null;
+      }
+    }
+    const catchAllValue = pathSegments.slice(nonCatchAllCount).join("/");
+    const catchAllParamName = patternSegments[nonCatchAllCount].slice(4);
+    params2[catchAllParamName] = catchAllValue;
+    if (Object.keys(params2).length !== paramNames.length) {
+      return null;
+    }
+    return params2;
+  }
+  if (patternSegments.length !== pathSegments.length) {
+    return null;
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternSeg = patternSegments[i];
+    const pathSeg = pathSegments[i];
+    if (patternSeg.startsWith(":")) {
+      const paramName = patternSeg.slice(1);
+      params[paramName] = pathSeg;
+    } else if (patternSeg !== pathSeg) {
+      return null;
+    }
+  }
+  if (Object.keys(params).length !== paramNames.length) {
+    return null;
+  }
+  return params;
 }
-var devDistDir;
-function getDevDist() {
-  return devDistDir;
+
+// src/loader/loadRouteModule.ts
+import fs11 from "fs";
+
+// src/loader/validateRouteModule.ts
+function validateRouteModule(value, method, filePath) {
+  if (typeof value !== "function") {
+    throw new Error(
+      `Route module "${filePath}" does not export a valid handler for method "${method}". Expected a function, got ${typeof value}.`
+    );
+  }
 }
 
 // src/loader/loadRouteModule.ts
@@ -2190,7 +2666,7 @@ async function loadRouteModule(filePath, method, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs8.existsSync(sourcePath)) {
+      if (sourcePath && fs11.existsSync(sourcePath)) {
         try {
           await ensureCompiled(sourcePath, rootDir, dist);
         } catch (compileErr) {
@@ -2684,6 +3160,12 @@ function getBuiltinInjectionValue(type, ctx, body) {
         return body.fields;
       }
       return {};
+    // Phase 2.3：注入所有已注册 agent 元数据列表
+    case "agents":
+      return listAgents();
+    // Phase 3.5：调 @faapi/agent 插件注册的工厂获取 AgentHandle
+    case "agent":
+      return getAgentHandle(ctx);
     default:
       return void 0;
   }
@@ -2867,9 +3349,9 @@ async function validateInput(schemaPath, method, inputType, input) {
 function mapZodIssues(error) {
   return error.issues.map((issue) => {
     const code = mapZodCode(issue.code, issue.message);
-    const path14 = issue.path.map(String).join(".") || "";
+    const path18 = issue.path.map(String).join(".") || "";
     return {
-      path: path14,
+      path: path18,
       code,
       expected: issue.expected ?? mapExpectedFromMessage(issue.message),
       received: issue.received ?? mapReceivedFromMessage(issue.message),
@@ -2931,9 +3413,9 @@ function getClientIp(req) {
 }
 
 // src/server/handleWsUpgrade.ts
-import fs9 from "fs";
+import fs12 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
-import path9 from "path";
+import path10 from "path";
 
 // src/errors/formatErrorResponse.ts
 function formatErrorResponse(error) {
@@ -3100,7 +3582,7 @@ async function loadWsHandler(filePath, ctx, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs9.existsSync(sourcePath)) {
+      if (sourcePath && fs12.existsSync(sourcePath)) {
         await ensureCompiled(sourcePath, rootDir, dist);
       }
     }
@@ -3180,7 +3662,7 @@ function attachWebSocket(options) {
     const finalHandler = async () => {
       let handlers;
       try {
-        const absoluteFilePath = path9.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path10.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -3279,15 +3761,15 @@ function limitStreamSize(stream, maxSize) {
     }
   });
 }
-function findAllowedMethods(routes, path14) {
+function findAllowedMethods(routes, path18) {
   const methods = /* @__PURE__ */ new Set();
   for (const route of routes) {
-    if (route.urlPath === path14) {
+    if (route.urlPath === path18) {
       methods.add(route.method);
       continue;
     }
     if (route.isDynamic) {
-      const params = matchDynamicPath(route.urlPath, path14, route.paramNames, route.isCatchAll);
+      const params = matchDynamicPath(route.urlPath, path18, route.paramNames, route.isCatchAll);
       if (params !== null) {
         methods.add(route.method);
       }
@@ -3373,7 +3855,7 @@ async function handleRequest(routes, rootDir, dist, req, res, configMiddlewares,
     }
     ctx.params = match.params;
     const { route } = match;
-    const absoluteFilePath = path10.resolve(rootDir, route.filePath);
+    const absoluteFilePath = path11.resolve(rootDir, route.filePath);
     const routeModule = await loadRouteModule(absoluteFilePath, route.method, rootDir);
     const input = await resolveInput(route.method, request);
     const inputType = getInputTypeForMethod(route.method);
@@ -3463,8 +3945,8 @@ function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
 }
 
 // src/cli/generateRoutes.ts
-import fs10 from "fs";
-import path11 from "path";
+import fs13 from "fs";
+import path12 from "path";
 async function hydrateRoutes(manifest) {
   const hydrateRoute = (serialized) => ({
     method: serialized.method,
@@ -3488,6 +3970,266 @@ async function hydrateRoutes(manifest) {
   return { routes, wsRoutes };
 }
 
+// src/cli/generateAgentArtifacts.ts
+import path13 from "path";
+import fs14 from "fs/promises";
+
+// src/ast/extractAgentMetadata.ts
+import ts8 from "typescript";
+function extractAgentMetadata(program, filePath, pathMeta) {
+  const sourceFile = program.getSourceFile(filePath);
+  if (!sourceFile) return null;
+  const configFound = findConfigExport(sourceFile);
+  let jsDocOwner = null;
+  let objectLiteral = null;
+  if (configFound) {
+    jsDocOwner = configFound.jsDocOwner;
+    objectLiteral = configFound.objectLiteral;
+  } else if (pathMeta.hasRun) {
+    const runNode = findRunExport(sourceFile);
+    if (runNode) {
+      jsDocOwner = runNode;
+    }
+  }
+  const jsDoc = jsDocOwner ? getJSDocFromNode2(jsDocOwner) : void 0;
+  const description = extractDescription2(jsDoc);
+  const agentNameOverride = extractAgentTagValue(jsDoc);
+  let systemPrompt;
+  let tools;
+  let agents;
+  let model;
+  let maxTurns;
+  if (objectLiteral) {
+    const fields = extractConfigFields(objectLiteral);
+    systemPrompt = fields.systemPrompt;
+    tools = fields.tools;
+    agents = fields.agents;
+    model = fields.model;
+    maxTurns = fields.maxTurns;
+  }
+  return {
+    name: agentNameOverride ?? pathMeta.name,
+    description,
+    filePath: pathMeta.filePath,
+    hasConfig: pathMeta.hasConfig,
+    hasRun: pathMeta.hasRun,
+    systemPrompt,
+    tools,
+    agents,
+    model,
+    maxTurns
+  };
+}
+function findConfigExport(sourceFile) {
+  let result = null;
+  ts8.forEachChild(sourceFile, (node) => {
+    if (result) return;
+    if (ts8.isVariableStatement(node) && hasExportModifier2(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (result) break;
+        const nameText = ts8.isIdentifier(decl.name) ? decl.name.text : "";
+        if (nameText !== "config" || !decl.initializer) continue;
+        if (ts8.isObjectLiteralExpression(decl.initializer)) {
+          result = { jsDocOwner: node, objectLiteral: decl.initializer };
+        } else if (ts8.isArrowFunction(decl.initializer)) {
+          const returnObj = getReturnObjectLiteral(decl.initializer);
+          result = { jsDocOwner: node, objectLiteral: returnObj };
+        }
+      }
+    }
+    if (ts8.isFunctionDeclaration(node) && hasExportModifier2(node) && node.name?.text === "config") {
+      const returnObj = getReturnObjectLiteral(node);
+      result = { jsDocOwner: node, objectLiteral: returnObj };
+    }
+  });
+  return result;
+}
+function findRunExport(sourceFile) {
+  let result = null;
+  ts8.forEachChild(sourceFile, (node) => {
+    if (result) return;
+    if (ts8.isFunctionDeclaration(node) && hasExportModifier2(node) && node.name?.text === "run") {
+      result = node;
+      return;
+    }
+    if (ts8.isVariableStatement(node) && hasExportModifier2(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (result) break;
+        const nameText = ts8.isIdentifier(decl.name) ? decl.name.text : "";
+        if (nameText !== "run" || !decl.initializer) continue;
+        if (ts8.isArrowFunction(decl.initializer) || ts8.isFunctionExpression(decl.initializer)) {
+          result = node;
+        }
+      }
+    }
+  });
+  return result;
+}
+function getReturnObjectLiteral(fn) {
+  const body = fn.body;
+  if (!body) return null;
+  if (ts8.isObjectLiteralExpression(body)) {
+    return body;
+  }
+  if (ts8.isBlock(body)) {
+    for (const stmt of body.statements) {
+      if (ts8.isReturnStatement(stmt) && stmt.expression && ts8.isObjectLiteralExpression(stmt.expression)) {
+        return stmt.expression;
+      }
+    }
+  }
+  return null;
+}
+function hasExportModifier2(node) {
+  if (!ts8.canHaveModifiers(node)) return false;
+  const modifiers = ts8.getModifiers(node);
+  return !!modifiers?.some((m) => m.kind === ts8.SyntaxKind.ExportKeyword);
+}
+function getJSDocFromNode2(node) {
+  const apiDocs = ts8.getJSDocCommentsAndTags(node).filter((entry) => ts8.isJSDoc(entry));
+  if (apiDocs.length > 0) return apiDocs[0];
+  const directDocs = node.jsDoc;
+  if (directDocs && directDocs.length > 0) return directDocs[0];
+  return void 0;
+}
+function extractDescription2(jsDoc) {
+  if (!jsDoc) return void 0;
+  if (typeof jsDoc.comment !== "string") return void 0;
+  const trimmed = jsDoc.comment.trim();
+  return trimmed || void 0;
+}
+function extractAgentTagValue(jsDoc) {
+  if (!jsDoc || !jsDoc.tags) return void 0;
+  for (const tag of jsDoc.tags) {
+    if (tag.tagName.text !== "agent") continue;
+    if (typeof tag.comment !== "string") return void 0;
+    const text = tag.comment.trim();
+    if (!text) return void 0;
+    const cleaned = text.replace(/^\{|\}$/g, "").trim();
+    return cleaned || void 0;
+  }
+  return void 0;
+}
+function extractConfigFields(objLit) {
+  const result = {};
+  for (const prop of objLit.properties) {
+    if (!ts8.isPropertyAssignment(prop)) continue;
+    const propName = getPropertyName(prop.name);
+    if (!propName) continue;
+    switch (propName) {
+      case "systemPrompt":
+        result.systemPrompt = extractStringValue(prop.initializer);
+        break;
+      case "tools":
+        result.tools = extractStringArrayValue(prop.initializer);
+        break;
+      case "agents":
+        result.agents = extractStringArrayValue(prop.initializer);
+        break;
+      case "model":
+        result.model = extractStringValue(prop.initializer);
+        break;
+      case "maxTurns":
+        result.maxTurns = extractNumberValue(prop.initializer);
+        break;
+    }
+  }
+  return result;
+}
+function getPropertyName(name) {
+  if (ts8.isIdentifier(name)) return name.text;
+  if (ts8.isStringLiteral(name)) return name.text;
+  return null;
+}
+function extractStringValue(expr) {
+  if (ts8.isStringLiteral(expr)) return expr.text;
+  return void 0;
+}
+function extractNumberValue(expr) {
+  if (ts8.isNumericLiteral(expr)) {
+    const num = Number(expr.text);
+    return Number.isNaN(num) ? void 0 : num;
+  }
+  return void 0;
+}
+function extractStringArrayValue(expr) {
+  if (!ts8.isArrayLiteralExpression(expr)) return void 0;
+  const values = [];
+  for (const element of expr.elements) {
+    if (!ts8.isStringLiteral(element)) return void 0;
+    values.push(element.text);
+  }
+  return values;
+}
+
+// src/cli/generateAgentArtifacts.ts
+init_createProgram();
+var AGENTS_FILE = "faapi-agents.js";
+function toProdFilePath2(filePath, dist) {
+  let rel = filePath.replace(/\\/g, "/");
+  if (rel.startsWith("src/")) {
+    rel = rel.slice(4);
+  }
+  const jsPath = rel.replace(/\.ts$/, ".js");
+  return jsPath.startsWith(`${dist}/`) ? jsPath : `${dist}/${jsPath}`;
+}
+function serializeAgents(agents, dist = "dist") {
+  return agents.map((a) => ({
+    name: a.name,
+    description: a.description,
+    hasConfig: a.hasConfig,
+    hasRun: a.hasRun,
+    systemPrompt: a.systemPrompt,
+    tools: a.tools,
+    agents: a.agents,
+    model: a.model,
+    maxTurns: a.maxTurns,
+    filePath: toProdFilePath2(a.filePath, dist)
+  }));
+}
+async function writeAgentsModule(manifest, outputPath) {
+  const dir = path13.dirname(outputPath);
+  await fs14.mkdir(dir, { recursive: true });
+  const content = `// \u81EA\u52A8\u751F\u6210,\u8BF7\u52FF\u624B\u52A8\u7F16\u8F91(faapi build/dev \u4EA7\u7269)
+export const agents = ${JSON.stringify(manifest, null, 2)};
+`;
+  await fs14.writeFile(outputPath, content, "utf-8");
+}
+function hydrateAgents(manifest) {
+  return manifest.map((a) => ({
+    name: a.name,
+    description: a.description ?? void 0,
+    filePath: a.filePath,
+    hasConfig: a.hasConfig,
+    hasRun: a.hasRun,
+    systemPrompt: a.systemPrompt ?? void 0,
+    tools: a.tools ?? void 0,
+    agents: a.agents ?? void 0,
+    model: a.model ?? void 0,
+    maxTurns: a.maxTurns ?? void 0
+  }));
+}
+async function generateAgentArtifacts(agents, rootDir, dist) {
+  const metadata = [];
+  for (const manifest of agents) {
+    const absPath = path13.resolve(rootDir, manifest.filePath);
+    const program = createProgram(absPath);
+    const result = extractAgentMetadata(program, absPath, {
+      name: manifest.name,
+      filePath: manifest.filePath,
+      hasConfig: manifest.hasConfig,
+      hasRun: manifest.hasRun
+    });
+    if (result) {
+      metadata.push(result);
+    }
+  }
+  const serialized = serializeAgents(metadata, dist);
+  const agentsPath = path13.resolve(rootDir, dist, AGENTS_FILE);
+  await writeAgentsModule(serialized, agentsPath);
+  return metadata;
+}
+
 // src/cli/loadPlugins.ts
 async function loadPlugins(declarations, ctx) {
   const handlerWrappers = [];
@@ -3551,7 +4293,29 @@ function resolveDeclaration(decl) {
 var DEFAULT_DIST = "dist";
 var DEFAULT_PORT = 3e3;
 var ROUTES_FILE = "faapi-routes.js";
+var TOOLS_FILE2 = "faapi-tools.js";
+var AGENTS_FILE2 = "faapi-agents.js";
 var PATTERNS = ["src/api/**/*.ts"];
+async function loadAndHydrateTools(rootDir, dist) {
+  const toolsPath = path14.resolve(rootDir, dist, TOOLS_FILE2);
+  if (!fs15.existsSync(toolsPath)) {
+    return [];
+  }
+  const serialized = await importWithCacheBust(toolsPath);
+  const hydrated = hydrateTools(serialized.tools ?? []);
+  hydrateToolRegistry(hydrated);
+  return hydrated;
+}
+async function loadAndHydrateAgents(rootDir, dist) {
+  const agentsPath = path14.resolve(rootDir, dist, AGENTS_FILE2);
+  if (!fs15.existsSync(agentsPath)) {
+    return [];
+  }
+  const serialized = await importWithCacheBust(agentsPath);
+  const hydrated = hydrateAgents(serialized.agents ?? []);
+  hydrateAgentRegistry(hydrated);
+  return hydrated;
+}
 var APP_INSTANCE_KEY = /* @__PURE__ */ Symbol.for("faapi.app.instance");
 function getCurrentApp() {
   return globalThis[APP_INSTANCE_KEY] ?? null;
@@ -3591,8 +4355,8 @@ function isFaapiConfigKey(key) {
 async function createAppBase(options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const dist = options?.dist ?? process.env.FAAPI_DIST ?? DEFAULT_DIST;
-  const routesPath = path12.resolve(rootDir, dist, ROUTES_FILE);
-  if (!fs11.existsSync(routesPath)) {
+  const routesPath = path14.resolve(rootDir, dist, ROUTES_FILE);
+  if (!fs15.existsSync(routesPath)) {
     throw new Error(
       `[faapi] ${dist}/${ROUTES_FILE} \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u6267\u884C \`faapi build\`\uFF08\u6216 \`faapi dev\`\uFF09\u751F\u6210\u4EA7\u7269\u3002`
     );
@@ -3611,6 +4375,8 @@ async function createAppBase(options) {
       }
     }
   }
+  const tools = await loadAndHydrateTools(rootDir, dist);
+  const agents = await loadAndHydrateAgents(rootDir, dist);
   const pluginConfig = config ? Object.fromEntries(Object.entries(config).filter(([k]) => !isFaapiConfigKey(k))) : {};
   const { server, routesRef } = createServer({
     routes: sorted,
@@ -3660,6 +4426,21 @@ async function createAppBase(options) {
               console.log(`  WS     ${route.urlPath}  ${route.filePath}`);
             }
           }
+          if (tools.length > 0) {
+            console.log(`- Loaded ${tools.length} tool(s):`);
+            for (const tool of tools) {
+              console.log(`  ${tool.name}  ${tool.filePath}`);
+            }
+          }
+          if (agents.length > 0) {
+            console.log(`- Loaded ${agents.length} agent(s):`);
+            for (const agent of agents) {
+              const exports = [];
+              if (agent.hasConfig) exports.push("config");
+              if (agent.hasRun) exports.push("run");
+              console.log(`  ${agent.name} [${exports.join("+")}]  ${agent.filePath}`);
+            }
+          }
           if (config?.lifecycle?.onClose) {
             const graceful = async (signal) => {
               console.log(`
@@ -3757,6 +4538,9 @@ async function createAppBase(options) {
       if (config?.lifecycle?.onClose) {
         await config.lifecycle.onClose({ rootDir, routes: sorted, server });
       }
+      clearToolRegistry();
+      clearAgentRegistry();
+      clearAgentHandleFactory();
       if (!server.listening) {
         app.server = null;
         if (getCurrentApp() === app) setCurrentApp(null);
@@ -3794,17 +4578,17 @@ async function createAppBase(options) {
 
 // src/router/scanRoutes.ts
 import fg2 from "fast-glob";
-import path13 from "path";
-import fs12 from "fs";
+import path15 from "path";
+import fs16 from "fs";
 
 // src/router/constants.ts
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 var HTTP_METHOD_SET = new Set(HTTP_METHODS);
 
 // src/utils/normalizePath.ts
-function normalizePath(path14) {
-  if (!path14) return "";
-  let result = path14.replace(/\\/g, "/");
+function normalizePath(path18) {
+  if (!path18) return "";
+  let result = path18.replace(/\\/g, "/");
   result = result.replace(/\/+/g, "/");
   result = result.replace(/\/+$/, "");
   if (result && !result.startsWith("/")) {
@@ -3865,41 +4649,41 @@ function extractExportsFromSource(source) {
   return names;
 }
 function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
-  const routeDir = path13.dirname(routeFilePath);
-  const resolvedRoot = path13.resolve(rootDir);
+  const routeDir = path15.dirname(routeFilePath);
+  const resolvedRoot = path15.resolve(rootDir);
   const paths = [];
-  let currentDir = path13.resolve(rootDir, routeDir);
+  let currentDir = path15.resolve(rootDir, routeDir);
   while (true) {
     if (dist) {
-      const mwTsPath = path13.join(currentDir, "middlewares.ts");
-      const mwJsPath = path13.join(currentDir, "middlewares.js");
-      const absTsPath = path13.resolve(rootDir, mwTsPath);
-      const absJsPath = path13.resolve(rootDir, mwJsPath);
-      const absMwPath = fs12.existsSync(absTsPath) ? absTsPath : fs12.existsSync(absJsPath) ? absJsPath : null;
+      const mwTsPath = path15.join(currentDir, "middlewares.ts");
+      const mwJsPath = path15.join(currentDir, "middlewares.js");
+      const absTsPath = path15.resolve(rootDir, mwTsPath);
+      const absJsPath = path15.resolve(rootDir, mwJsPath);
+      const absMwPath = fs16.existsSync(absTsPath) ? absTsPath : fs16.existsSync(absJsPath) ? absJsPath : null;
       if (absMwPath) {
-        const relMwPath = path13.relative(rootDir, absMwPath);
-        const prodAbsPath = path13.resolve(rootDir, toProdFilePath(relMwPath, dist));
+        const relMwPath = path15.relative(rootDir, absMwPath);
+        const prodAbsPath = path15.resolve(rootDir, toProdFilePath3(relMwPath, dist));
         paths.push(prodAbsPath);
       }
     } else {
       for (const ext of [".ts", ".js"]) {
-        const mwPath = path13.join(currentDir, `middlewares${ext}`);
-        const absMwPath = path13.resolve(rootDir, mwPath);
-        if (fs12.existsSync(absMwPath)) {
+        const mwPath = path15.join(currentDir, `middlewares${ext}`);
+        const absMwPath = path15.resolve(rootDir, mwPath);
+        if (fs16.existsSync(absMwPath)) {
           paths.push(absMwPath);
           break;
         }
       }
     }
     if (currentDir === resolvedRoot) break;
-    const parentDir = path13.dirname(currentDir);
+    const parentDir = path15.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
   paths.reverse();
   return paths;
 }
-function toProdFilePath(filePath, dist) {
+function toProdFilePath3(filePath, dist) {
   let rel = filePath.replace(/\\/g, "/");
   if (rel.startsWith("src/")) {
     rel = rel.slice(4);
@@ -3919,7 +4703,7 @@ async function scanRoutes(rootDir, patterns, dist) {
     const normalizedFile = file.replace(/\\/g, "/");
     const fileName = normalizedFile.split("/").pop();
     if (fileName === "handler.ts" || fileName === "handler.js") {
-      const absPath = path13.resolve(rootDir, normalizedFile);
+      const absPath = path15.resolve(rootDir, normalizedFile);
       const urlPath = filePathToUrlPath(normalizedFile);
       const paramNames = extractParamNames(urlPath);
       const isDynamic = paramNames.length > 0;
@@ -3932,7 +4716,7 @@ async function scanRoutes(rootDir, patterns, dist) {
         const mwPaths = collectMiddlewarePaths(normalizedFile, rootDir);
         middlewareBundle = await loadMergedMiddlewares(mwPaths);
       }
-      const source = await fs12.promises.readFile(absPath, "utf8").catch(() => "");
+      const source = await fs16.promises.readFile(absPath, "utf8").catch(() => "");
       const exportNames = extractExportsFromSource(source);
       const methods = HTTP_METHODS.filter((m) => exportNames.has(m));
       for (const method of methods) {
@@ -3966,6 +4750,140 @@ async function scanRoutes(rootDir, patterns, dist) {
   return { routes, wsRoutes };
 }
 
+// src/tools/scanTools.ts
+import fg3 from "fast-glob";
+import path16 from "path";
+import fs17 from "fs";
+var TOOL_PATTERNS = ["src/tools/**/*.ts"];
+var TOOL_EXPORT_RE = new RegExp(
+  String.raw`export\s+(?:async\s+)?(?:function\s+|const\s+)([A-Za-z_$][\w$]*)\s*(?:\(|=)`,
+  "g"
+);
+var RESERVED_EXPORTS = /* @__PURE__ */ new Set(["default", "config", "run"]);
+function extractToolExportsFromSource(source) {
+  const names = /* @__PURE__ */ new Set();
+  let match;
+  TOOL_EXPORT_RE.lastIndex = 0;
+  while ((match = TOOL_EXPORT_RE.exec(source)) !== null) {
+    const name = match[1];
+    if (!RESERVED_EXPORTS.has(name)) {
+      names.add(name);
+    }
+  }
+  return names;
+}
+function extractNamespaceFromRelPath(relPath) {
+  const lastSlash = relPath.lastIndexOf("/");
+  const dirPath = lastSlash === -1 ? "" : relPath.slice(0, lastSlash);
+  if (!dirPath) return "";
+  return dirPath.split("/").join(".");
+}
+function filePathToToolNamespace(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const toolsMatch = normalized.match(/(?:^|\/)tools\/(.+)$/);
+  if (toolsMatch) {
+    return extractNamespaceFromRelPath(toolsMatch[1]);
+  }
+  return "";
+}
+function buildToolName(namespace, functionName) {
+  return namespace ? `${namespace}.${functionName}` : functionName;
+}
+async function scanTools(rootDir, patterns) {
+  const files = await fg3(patterns, {
+    cwd: rootDir,
+    onlyFiles: true,
+    absolute: false
+  });
+  const tools = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const normalizedFile = file.replace(/\\/g, "/");
+    const fileName = normalizedFile.split("/").pop();
+    if (fileName !== "handler.ts" && fileName !== "handler.js") {
+      continue;
+    }
+    const absPath = path16.resolve(rootDir, normalizedFile);
+    const source = await fs17.promises.readFile(absPath, "utf8").catch(() => "");
+    const exportNames = extractToolExportsFromSource(source);
+    const namespace = filePathToToolNamespace(normalizedFile);
+    for (const fnName of exportNames) {
+      const toolName = buildToolName(namespace, fnName);
+      const prevFile = seen.get(toolName);
+      if (prevFile) {
+        throw new Error(
+          `Tool conflict: "${toolName}" declared in both ${prevFile} and ${normalizedFile}`
+        );
+      }
+      seen.set(toolName, normalizedFile);
+      tools.push({
+        name: toolName,
+        functionName: fnName,
+        filePath: normalizedFile
+      });
+    }
+  }
+  return tools;
+}
+
+// src/agents/scanAgents.ts
+import fg4 from "fast-glob";
+import path17 from "path";
+import fs18 from "fs";
+var DEFAULT_AGENT_PATTERNS = ["src/agents/*/handler.ts"];
+var CONFIG_EXPORT_RE = /export\s+(?:const|function)\s+config\b/;
+var RUN_EXPORT_RE = /export\s+(?:async\s+)?(?:function\s+|const\s+)run\b/;
+function extractAgentNameFromPath(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const match = normalized.match(/(?:^|\/)agents\/([^/]+)\/handler\.ts$/);
+  if (!match) {
+    throw new Error(
+      `Not an agent path: "${filePath}". Expected pattern: src/agents/<name>/handler.ts`
+    );
+  }
+  return match[1];
+}
+function detectAgentExports(source) {
+  return {
+    hasConfig: CONFIG_EXPORT_RE.test(source),
+    hasRun: RUN_EXPORT_RE.test(source)
+  };
+}
+async function scanAgents(rootDir, patterns) {
+  const files = await fg4(patterns, {
+    cwd: rootDir,
+    onlyFiles: true,
+    absolute: false
+  });
+  const agents = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const normalizedFile = file.replace(/\\/g, "/");
+    const fileName = normalizedFile.split("/").pop();
+    if (fileName !== "handler.ts" && fileName !== "handler.js") {
+      continue;
+    }
+    const absPath = path17.resolve(rootDir, normalizedFile);
+    const source = await fs18.promises.readFile(absPath, "utf8").catch(() => "");
+    const { hasConfig, hasRun } = detectAgentExports(source);
+    const name = extractAgentNameFromPath(normalizedFile);
+    const prevFile = seen.get(name);
+    if (prevFile) {
+      throw new Error(
+        `Agent conflict: "${name}" declared in both ${prevFile} and ${normalizedFile}`
+      );
+    }
+    seen.set(name, normalizedFile);
+    agents.push({
+      name,
+      filePath: normalizedFile,
+      hasConfig,
+      hasRun
+    });
+  }
+  return agents;
+}
+
 // src/cli/createDevApp.ts
 init_createProgram();
 async function createDevApp(options) {
@@ -3988,6 +4906,22 @@ async function createDevApp(options) {
     }
     ctx.updateRoutes(sorted, reScanned.wsRoutes);
   };
+  devApp.reloadTools = async () => {
+    setLoadTimestamp(Date.now());
+    invalidateProgramCache();
+    const tools = await scanTools(ctx.rootDir, TOOL_PATTERNS);
+    await generateToolArtifacts(tools, ctx.rootDir, ctx.dist, {
+      skipSchema: isDevOnDemandEnabled()
+    });
+    await loadAndHydrateTools(ctx.rootDir, ctx.dist);
+  };
+  devApp.reloadAgents = async () => {
+    setLoadTimestamp(Date.now());
+    invalidateProgramCache();
+    const agents = await scanAgents(ctx.rootDir, DEFAULT_AGENT_PATTERNS);
+    await generateAgentArtifacts(agents, ctx.rootDir, ctx.dist);
+    await loadAndHydrateAgents(ctx.rootDir, ctx.dist);
+  };
   return devApp;
 }
 
@@ -4004,6 +4938,7 @@ export {
   RouteNotFoundError,
   SchemaExtractionError,
   ValidationError,
+  clearAgentHandleFactory,
   collectRouteSchemaSources,
   cors,
   createProdApp as createApp,
@@ -4011,13 +4946,21 @@ export {
   createProdApp,
   createProgram,
   extractTypeInfo,
+  getAgent,
   getApp,
   getInputTypeForMethod,
+  getTool,
   helmet,
   invalidateProgramCache,
+  loadAgentModule,
   loadConfig,
   loadEnv,
+  loadToolModule,
+  loadToolSchema,
   logger,
+  registerAgentHandleFactory,
+  resolveAgentTools,
+  resolveSubAgents,
   resolveTypeNode
 };
 //# sourceMappingURL=index.js.map