@faapi/faapi 3.3.0 → 4.1.0

package/dist/index.js

@@ -90,9 +90,10 @@ function createPrograms(filePaths) {
     }
   }
   for (const { tsconfigPath, files } of groups.values()) {
-    const cacheKey = `shared::${tsconfigPath}::${[...files].sort().join("|")}`;
+    const cacheKey = `shared::${tsconfigPath}`;
     let program = programCache.get(cacheKey);
-    if (!program) {
+    const coversAll = program !== void 0 && files.every((f) => program.getSourceFile(f) !== void 0);
+    if (!program || !coversAll) {
       program = buildProgram(files, tsconfigPath);
       programCache.set(cacheKey, program);
     }
@@ -147,7 +148,7 @@ import ts2 from "typescript";
 function setProgramContext(program) {
   currentProgram = program;
 }
-function resolveTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set()) {
+function resolveTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set(), bindings = /* @__PURE__ */ new Map()) {
   const kind = typeNode.kind;
   switch (kind) {
     case ts2.SyntaxKind.StringKeyword:
@@ -203,13 +204,13 @@ function resolveTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set())
   if (ts2.isArrayTypeNode(typeNode)) {
     return {
       kind: "array",
-      element: resolveTypeNode(typeNode.elementType, checker, visited)
+      element: resolveTypeNode(typeNode.elementType, checker, visited, bindings)
     };
   }
   if (ts2.isTupleTypeNode(typeNode)) {
     const elements = typeNode.elements.map((e) => {
       if (ts2.isRestTypeNode(e)) {
-        const inner = resolveTypeNode(e.type, checker, visited);
+        const inner = resolveTypeNode(e.type, checker, visited, bindings);
         if (inner.kind === "array") {
           return { type: inner.element, optional: false, rest: true };
         }
@@ -217,20 +218,20 @@ function resolveTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set())
       }
       if (ts2.isNamedTupleMember(e)) {
         return {
-          type: resolveTypeNode(e.type, checker, visited),
+          type: resolveTypeNode(e.type, checker, visited, bindings),
           optional: !!e.questionToken,
           rest: false
         };
       }
       if (ts2.isOptionalTypeNode(e)) {
         return {
-          type: resolveTypeNode(e.type, checker, visited),
+          type: resolveTypeNode(e.type, checker, visited, bindings),
           optional: true,
           rest: false
         };
       }
       return {
-        type: resolveTypeNode(e, checker, visited),
+        type: resolveTypeNode(e, checker, visited, bindings),
         optional: false,
         rest: false
       };
@@ -238,40 +239,80 @@ function resolveTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set())
     return { kind: "tuple", elements };
   }
   if (ts2.isUnionTypeNode(typeNode)) {
-    const members = typeNode.types.map((t) => resolveTypeNode(t, checker, visited));
+    const members = typeNode.types.map((t) => resolveTypeNode(t, checker, visited, bindings));
     return { kind: "union", members };
   }
   if (ts2.isIntersectionTypeNode(typeNode)) {
-    const properties = [];
+    const propMap = /* @__PURE__ */ new Map();
     for (const t of typeNode.types) {
-      const resolved = resolveTypeNode(t, checker, visited);
-      if (resolved.kind === "object") {
-        properties.push(...resolved.properties);
+      const resolved = resolveTypeNode(t, checker, visited, bindings);
+      if (resolved.kind !== "object") {
+        throw new SchemaExtractionError(
+          typeNode.getText(),
+          `\u4EA4\u53C9\u7C7B\u578B\u5305\u542B\u975E object \u6210\u5458\uFF08${resolved.kind}\uFF09,\u8FD0\u884C\u65F6\u65E0\u6CD5\u6821\u9A8C\u2014\u2014branded \u7C7B\u578B\u5EFA\u8BAE\u6539\u7528\u5177\u4F53\u7C7B\u578B\u6216 unknown`
+        );
+      }
+      for (const prop of resolved.properties) {
+        const existing = propMap.get(prop.name);
+        if (!existing) {
+          propMap.set(prop.name, prop);
+          continue;
+        }
+        if (JSON.stringify(existing.type) !== JSON.stringify(prop.type) || existing.optional !== prop.optional) {
+          throw SchemaExtractionError.at(
+            typeNode,
+            typeNode.getText(),
+            `\u4EA4\u53C9\u7C7B\u578B\u6210\u5458\u7684\u540C\u540D\u5B57\u6BB5 "${prop.name}" \u7C7B\u578B\u51B2\u7A81\uFF08TS \u4E2D\u4E3A never\uFF09,\u8FD0\u884C\u65F6\u65E0\u6CD5\u6821\u9A8C`
+          );
+        }
+        if (!existing.constraints?.length && prop.constraints?.length) {
+          propMap.set(prop.name, prop);
+        }
       }
     }
-    return { kind: "object", properties };
+    return { kind: "object", properties: [...propMap.values()] };
   }
   if (ts2.isTypeLiteralNode(typeNode)) {
-    return resolveTypeLiteral(typeNode, checker, visited);
+    return resolveTypeLiteral(typeNode, checker, visited, bindings);
   }
   if (ts2.isTypeOperatorNode(typeNode) && typeNode.operator === ts2.SyntaxKind.KeyOfKeyword) {
     return resolveKeyOf(typeNode, checker);
   }
   if (ts2.isTypeOperatorNode(typeNode) && typeNode.operator === ts2.SyntaxKind.ReadonlyKeyword) {
-    return resolveTypeNode(typeNode.type, checker, visited);
+    return resolveTypeNode(typeNode.type, checker, visited, bindings);
   }
   if (ts2.isTypeReferenceNode(typeNode)) {
-    return resolveTypeReference(typeNode, checker, visited);
+    return resolveTypeReference(typeNode, checker, visited, bindings);
+  }
+  if (ts2.isExpressionWithTypeArguments(typeNode)) {
+    return resolveTypeReference(
+      {
+        getText: () => typeNode.getText(),
+        typeName: typeNode.expression,
+        typeArguments: typeNode.typeArguments
+      },
+      checker,
+      visited,
+      bindings
+    );
   }
-  throw new SchemaExtractionError(typeNode.getText(), "\u4E0D\u652F\u6301\u7684\u7C7B\u578B\u8BED\u6CD5");
+  throw SchemaExtractionError.at(typeNode, typeNode.getText(), "\u4E0D\u652F\u6301\u7684\u7C7B\u578B\u8BED\u6CD5");
 }
-function resolveTypeLiteral(typeNode, checker, visited = /* @__PURE__ */ new Set()) {
+function resolveTypeLiteral(typeNode, checker, visited = /* @__PURE__ */ new Set(), bindings = /* @__PURE__ */ new Map()) {
   const properties = [];
+  let catchall;
   for (const member of typeNode.members) {
+    if (ts2.isMethodSignature(member) || ts2.isGetAccessorDeclaration(member) || ts2.isSetAccessorDeclaration(member)) {
+      throw SchemaExtractionError.at(
+        member,
+        member.getText(),
+        "\u5BF9\u8C61\u7C7B\u578B\u542B\u65B9\u6CD5\u7B7E\u540D\u6216\u5B58\u53D6\u5668,\u8FD0\u884C\u65F6 JSON \u6570\u636E\u65E0\u6CD5\u6821\u9A8C\u65B9\u6CD5\u2014\u2014\u8BF7\u6539\u7528\u5177\u4F53\u5C5E\u6027\u7C7B\u578B"
+      );
+    }
     if (ts2.isPropertySignature(member) && member.name) {
       const name = member.name.getText();
       const optional = !!member.questionToken;
-      const type = member.type ? resolveTypeNode(member.type, checker, visited) : { kind: "any" };
+      const type = member.type ? resolveTypeNode(member.type, checker, visited, bindings) : { kind: "any" };
       const constraints = extractConstraintsFromJsDoc(member, name);
       validateConstraints(constraints, type, name);
       properties.push(
@@ -279,12 +320,10 @@ function resolveTypeLiteral(typeNode, checker, visited = /* @__PURE__ */ new Set
       );
     }
     if (ts2.isIndexSignatureDeclaration(member)) {
-      const keyType = member.parameters[0]?.type ? resolveTypeNode(member.parameters[0].type, checker, visited) : { kind: "any" };
-      const valueType = member.type ? resolveTypeNode(member.type, checker, visited) : { kind: "any" };
-      return { kind: "record", key: keyType, value: valueType };
+      catchall = member.type ? resolveTypeNode(member.type, checker, visited, bindings) : { kind: "any" };
     }
   }
-  return { kind: "object", properties };
+  return catchall !== void 0 ? { kind: "object", properties, catchall } : { kind: "object", properties };
 }
 function extractLiteralKeys(type) {
   if (type.kind === "literal" && typeof type.value === "string") {
@@ -353,36 +392,48 @@ function resolveKeyOf(typeNode, checker) {
   }
   throw new SchemaExtractionError(typeNode.getText(), "keyof T \u7684\u7ED3\u679C\u65E0\u6CD5\u89E3\u6790\u4E3A\u5B57\u9762\u91CF\u8054\u5408");
 }
-function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new Set()) {
+function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new Set(), bindings = /* @__PURE__ */ new Map()) {
   const typeName = typeNode.typeName.getText();
+  const bound = bindings.get(typeName);
+  if (bound) {
+    return bound;
+  }
   if (typeName === "Date") {
     return { kind: "date" };
   }
   if ((typeName === "Array" || typeName === "ReadonlyArray") && typeNode.typeArguments?.length === 1) {
+    const [arg] = typeNode.typeArguments;
     return {
       kind: "array",
-      element: resolveTypeNode(typeNode.typeArguments[0], checker, visited)
+      element: resolveTypeNode(arg, checker, visited, bindings)
     };
   }
   if (typeName === "Record" && typeNode.typeArguments?.length === 2) {
+    const [keyArg, valueArg] = typeNode.typeArguments;
     return {
       kind: "record",
-      key: resolveTypeNode(typeNode.typeArguments[0], checker, visited),
-      value: resolveTypeNode(typeNode.typeArguments[1], checker, visited)
+      key: resolveTypeNode(keyArg, checker, visited, bindings),
+      value: resolveTypeNode(valueArg, checker, visited, bindings)
     };
   }
   if ((typeName === "Partial" || typeName === "Required" || typeName === "Readonly") && typeNode.typeArguments?.length === 1) {
-    const inner = resolveTypeNode(typeNode.typeArguments[0], checker, visited);
+    const inner = resolveTypeNode(typeNode.typeArguments[0], checker, visited, bindings);
     if (inner.kind === "object" && typeName === "Partial") {
       return {
         kind: "object",
         properties: inner.properties.map((p) => ({ ...p, optional: true }))
       };
     }
+    if (inner.kind === "object" && typeName === "Required") {
+      return {
+        kind: "object",
+        properties: inner.properties.map((p) => ({ ...p, optional: false }))
+      };
+    }
     return inner;
   }
   if ((typeName === "Pick" || typeName === "Omit") && typeNode.typeArguments?.length === 2) {
-    const innerType = resolveTypeNode(typeNode.typeArguments[0], checker, visited);
+    const innerType = resolveTypeNode(typeNode.typeArguments[0], checker, visited, bindings);
     if (innerType.kind !== "object") {
       throw new SchemaExtractionError(
         typeNode.getText(),
@@ -390,7 +441,7 @@ function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new S
       );
     }
     const keyTypeNode = typeNode.typeArguments[1];
-    let keys = extractLiteralKeys(resolveTypeNode(keyTypeNode, checker, visited));
+    let keys = extractLiteralKeys(resolveTypeNode(keyTypeNode, checker, visited, bindings));
     if (keys === null) {
       keys = extractKeysFromChecker(keyTypeNode, checker);
     }
@@ -408,10 +459,11 @@ function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new S
         "Map \u5FC5\u987B\u5E26 2 \u4E2A\u7C7B\u578B\u53C2\u6570\uFF0C\u5982 Map<K, V>\uFF0C\u88F8 Map \u4E0D\u652F\u6301"
       );
     }
+    const [mapKey, mapValue] = typeNode.typeArguments;
     return {
       kind: "map",
-      key: resolveTypeNode(typeNode.typeArguments[0], checker, visited),
-      value: resolveTypeNode(typeNode.typeArguments[1], checker, visited)
+      key: resolveTypeNode(mapKey, checker, visited, bindings),
+      value: resolveTypeNode(mapValue, checker, visited, bindings)
     };
   }
   if (typeName === "Set") {
@@ -421,9 +473,10 @@ function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new S
         "Set \u5FC5\u987B\u5E26 1 \u4E2A\u7C7B\u578B\u53C2\u6570\uFF0C\u5982 Set<T>\uFF0C\u88F8 Set \u4E0D\u652F\u6301"
       );
     }
+    const [setArg] = typeNode.typeArguments;
     return {
       kind: "set",
-      element: resolveTypeNode(typeNode.typeArguments[0], checker, visited)
+      element: resolveTypeNode(setArg, checker, visited, bindings)
     };
   }
   if (typeName === "WeakMap" || typeName === "WeakSet") {
@@ -446,21 +499,42 @@ function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new S
   }
   visited.add(typeName);
   if (checker) {
-    const symbol = typeNode.typeName.kind === ts2.SyntaxKind.Identifier ? checker.getSymbolAtLocation(typeNode.typeName) : void 0;
+    const symbol = ts2.isIdentifier(typeNode.typeName) || ts2.isQualifiedName(typeNode.typeName) ? checker.getSymbolAtLocation(typeNode.typeName) : void 0;
     if (symbol) {
       const declaration = symbol.declarations?.[0];
       if (declaration) {
         if (ts2.isInterfaceDeclaration(declaration)) {
-          return resolveInterfaceDeclaration(declaration, checker, visited);
+          return resolveInterfaceDeclaration(
+            declaration,
+            checker,
+            visited,
+            bindings,
+            typeNode.typeArguments
+          );
         }
         if (ts2.isTypeAliasDeclaration(declaration)) {
-          return resolveTypeNode(declaration.type, checker, visited);
+          const declBindings = bindTypeParameters(
+            declaration.typeParameters,
+            typeNode.typeArguments,
+            bindings,
+            checker,
+            visited,
+            typeNode
+          );
+          return resolveTypeNode(declaration.type, checker, visited, declBindings);
         }
         if (ts2.isEnumDeclaration(declaration)) {
           return resolveEnumDeclaration(declaration);
         }
         if (ts2.isImportSpecifier(declaration) || ts2.isImportClause(declaration)) {
-          const resolved = resolveImportAlias(typeNode, symbol, checker, visited);
+          const resolved = resolveImportAlias(
+            typeNode,
+            symbol,
+            checker,
+            visited,
+            bindings,
+            typeNode.typeArguments
+          );
           if (resolved) return resolved;
         }
       }
@@ -468,17 +542,45 @@ function resolveTypeReference(typeNode, checker, visited = /* @__PURE__ */ new S
   }
   throw new SchemaExtractionError(typeNode.getText(), `\u65E0\u6CD5\u89E3\u6790\u7684\u5F15\u7528\u7C7B\u578B "${typeName}"`);
 }
-function resolveImportAlias(typeNode, symbol, checker, visited) {
+function bindTypeParameters(typeParameters, typeArguments, outerBindings, checker, visited, errorNode) {
+  if (!typeParameters || typeParameters.length === 0) return outerBindings;
+  const bindings = new Map(outerBindings);
+  for (let i = 0; i < typeParameters.length; i++) {
+    const param = typeParameters[i];
+    if (!param) continue;
+    const arg = typeArguments?.[i];
+    if (arg) {
+      bindings.set(param.name.text, resolveTypeNode(arg, checker, visited, outerBindings));
+    } else if (param.default) {
+      bindings.set(param.name.text, resolveTypeNode(param.default, checker, visited, bindings));
+    } else {
+      throw new SchemaExtractionError(
+        errorNode.getText(),
+        `\u6CDB\u578B\u53C2\u6570 "${param.name.text}" \u7F3A\u5C11\u7C7B\u578B\u5B9E\u53C2\uFF08\u4E14\u65E0\u9ED8\u8BA4\u7C7B\u578B\uFF09`
+      );
+    }
+  }
+  return bindings;
+}
+function resolveImportAlias(typeNode, symbol, checker, visited, bindings = /* @__PURE__ */ new Map(), typeArguments) {
   const typeName = typeNode.typeName.getText();
   try {
     const aliased = checker.getAliasedSymbol(symbol);
     if (aliased && aliased.declarations && aliased.declarations.length > 0) {
       const decl = aliased.declarations[0];
       if (ts2.isInterfaceDeclaration(decl)) {
-        return resolveInterfaceDeclaration(decl, checker, visited);
+        return resolveInterfaceDeclaration(decl, checker, visited, bindings, typeArguments);
       }
       if (ts2.isTypeAliasDeclaration(decl)) {
-        return resolveTypeNode(decl.type, checker, visited);
+        const declBindings = bindTypeParameters(
+          decl.typeParameters,
+          typeArguments,
+          bindings,
+          checker,
+          visited,
+          typeNode
+        );
+        return resolveTypeNode(decl.type, checker, visited, declBindings);
       }
       if (ts2.isEnumDeclaration(decl)) {
         return resolveEnumDeclaration(decl);
@@ -496,10 +598,18 @@ function resolveImportAlias(typeNode, symbol, checker, visited) {
     const found = findTopLevelDecl(sourceFile, typeName);
     if (found) {
       if (found.kind === "interface") {
-        return resolveInterfaceDeclaration(found.node, checker, visited);
+        return resolveInterfaceDeclaration(found.node, checker, visited, bindings, typeArguments);
       }
       if (found.kind === "typeAlias") {
-        return resolveTypeNode(found.node.type, checker, visited);
+        const declBindings = bindTypeParameters(
+          found.node.typeParameters,
+          typeArguments,
+          bindings,
+          checker,
+          visited,
+          typeNode
+        );
+        return resolveTypeNode(found.node.type, checker, visited, declBindings);
       }
       if (found.kind === "enum") {
         return resolveEnumDeclaration(found.node);
@@ -546,13 +656,22 @@ function resolveEnumDeclaration(node) {
   }
   return { kind: "union", members };
 }
-function resolveInterfaceDeclaration(node, checker, visited = /* @__PURE__ */ new Set()) {
+function resolveInterfaceDeclaration(node, checker, visited = /* @__PURE__ */ new Set(), outerBindings = /* @__PURE__ */ new Map(), typeArguments) {
   const properties = [];
   const propMap = /* @__PURE__ */ new Map();
+  let catchall;
+  const bindings = bindTypeParameters(
+    node.typeParameters,
+    typeArguments,
+    outerBindings,
+    checker,
+    visited,
+    node
+  );
   for (const heritageClause of node.heritageClauses ?? []) {
     if (heritageClause.token === ts2.SyntaxKind.ExtendsKeyword) {
       for (const expr of heritageClause.types) {
-        const parentType = resolveTypeNode(expr, checker, visited);
+        const parentType = resolveTypeNode(expr, checker, visited, bindings);
         if (parentType.kind === "object") {
           for (const prop of parentType.properties) {
             propMap.set(prop.name, prop);
@@ -562,10 +681,17 @@ function resolveInterfaceDeclaration(node, checker, visited = /* @__PURE__ */ ne
     }
   }
   for (const member of node.members) {
+    if (ts2.isMethodSignature(member) || ts2.isGetAccessorDeclaration(member) || ts2.isSetAccessorDeclaration(member)) {
+      throw SchemaExtractionError.at(
+        member,
+        member.getText(),
+        "\u63A5\u53E3\u542B\u65B9\u6CD5\u7B7E\u540D\u6216\u5B58\u53D6\u5668,\u8FD0\u884C\u65F6 JSON \u6570\u636E\u65E0\u6CD5\u6821\u9A8C\u65B9\u6CD5\u2014\u2014\u8BF7\u6539\u7528\u5177\u4F53\u5C5E\u6027\u7C7B\u578B"
+      );
+    }
     if (ts2.isPropertySignature(member) && member.name) {
       const name = member.name.getText();
       const optional = !!member.questionToken;
-      const type = member.type ? resolveTypeNode(member.type, checker, visited) : { kind: "any" };
+      const type = member.type ? resolveTypeNode(member.type, checker, visited, bindings) : { kind: "any" };
       const constraints = extractConstraintsFromJsDoc(member, name);
       validateConstraints(constraints, type, name);
       propMap.set(
@@ -574,15 +700,13 @@ function resolveInterfaceDeclaration(node, checker, visited = /* @__PURE__ */ ne
       );
     }
     if (ts2.isIndexSignatureDeclaration(member)) {
-      const keyType = member.parameters[0]?.type ? resolveTypeNode(member.parameters[0].type, checker, visited) : { kind: "any" };
-      const valueType = member.type ? resolveTypeNode(member.type, checker, visited) : { kind: "any" };
-      return { kind: "record", key: keyType, value: valueType };
+      catchall = member.type ? resolveTypeNode(member.type, checker, visited, bindings) : { kind: "any" };
     }
   }
   for (const prop of propMap.values()) {
     properties.push(prop);
   }
-  return { kind: "object", properties };
+  return catchall !== void 0 ? { kind: "object", properties, catchall } : { kind: "object", properties };
 }
 function extractConstraintsFromJsDoc(node, fieldName) {
   const jsDocs = ts2.getJSDocCommentsAndTags(node).filter((entry) => ts2.isJSDoc(entry));
@@ -705,15 +829,38 @@ var init_resolveTypeNode = __esm({
   "src/ast/resolveTypeNode.ts"() {
     "use strict";
     currentProgram = null;
-    SchemaExtractionError = class extends Error {
-      constructor(typeText, reason, options) {
-        super(`\u65E0\u6CD5\u89E3\u6790\u7C7B\u578B "${typeText}": ${reason}`, options);
+    SchemaExtractionError = class _SchemaExtractionError extends Error {
+      constructor(typeText, reason, options, location) {
+        super(
+          `\u65E0\u6CD5\u89E3\u6790\u7C7B\u578B "${typeText}": ${reason}` + (location ? ` (${location.file}:${location.line}:${location.column})` : ""),
+          options
+        );
         this.typeText = typeText;
         this.reason = reason;
+        this.location = location;
         this.name = "SchemaExtractionError";
       }
       typeText;
       reason;
+      location;
+      /**
+       * 从 AST 节点构造错误（自动携带 file:line:column）
+       *
+       * 所有抛错点应优先使用此工厂——错误无行号时，几百行的类型文件只能靠
+       * 类型名肉眼定位；解析 lib.d.ts 类型别名时还会出现错误文本与文件上下文错位
+       */
+      static at(node, typeText, reason) {
+        const sourceFile = node.getSourceFile();
+        if (!sourceFile) {
+          return new _SchemaExtractionError(typeText, reason);
+        }
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        return new _SchemaExtractionError(typeText, reason, void 0, {
+          file: sourceFile.fileName,
+          line: line + 1,
+          column: character + 1
+        });
+      }
     };
     NUMBER_CONSTRAINT_KINDS = /* @__PURE__ */ new Set([
       "max",
@@ -780,55 +927,47 @@ function extractTypeInfo(program, filePath, typeName) {
         return;
       }
     });
-    return result;
-  } finally {
-    setProgramContext(null);
-  }
-}
-function extractAllTypes(program, filePath) {
-  const sourceFile = program.getSourceFile(filePath);
-  if (!sourceFile) return /* @__PURE__ */ new Map();
-  const checker = program.getTypeChecker();
-  setProgramContext(program);
-  try {
-    const result = /* @__PURE__ */ new Map();
-    ts3.forEachChild(sourceFile, (node) => {
-      if (ts3.isInterfaceDeclaration(node)) {
-        const visited = /* @__PURE__ */ new Set();
-        visited.add(node.name.text);
-        const runtimeType = withFileContext(
-          filePath,
-          node.name.text,
-          () => resolveInterfaceDeclaration(node, checker, visited)
-        );
-        result.set(node.name.text, {
-          name: node.name.text,
-          properties: runtimeType.kind === "object" ? runtimeType.properties : [],
-          runtimeType
-        });
-        return;
-      }
-      if (ts3.isTypeAliasDeclaration(node)) {
-        const visited = /* @__PURE__ */ new Set();
-        visited.add(node.name.text);
-        const runtimeType = withFileContext(
-          filePath,
-          node.name.text,
-          () => resolveTypeNode(node.type, checker, visited)
-        );
-        result.set(node.name.text, {
-          name: node.name.text,
-          properties: runtimeType.kind === "object" ? runtimeType.properties : [],
-          runtimeType
-        });
-        return;
+    if (result) return result;
+    for (const sf of program.getSourceFiles()) {
+      if (sf === sourceFile) continue;
+      if (sf.fileName.includes("/node_modules/") || sf.fileName.includes("typescript/lib/")) {
+        continue;
       }
-    });
-    return result;
+      const found = findTopLevelDecl(sf, typeName);
+      if (!found) continue;
+      const visited = /* @__PURE__ */ new Set();
+      visited.add(typeName);
+      const runtimeType = withFileContext(filePath, typeName, () => {
+        if (found.kind === "interface") {
+          return resolveInterfaceDeclaration(found.node, checker, visited);
+        }
+        if (found.kind === "typeAlias") {
+          return resolveTypeNode(found.node.type, checker, visited);
+        }
+        return resolveEnumDeclaration(found.node);
+      });
+      return {
+        name: typeName,
+        properties: runtimeType.kind === "object" ? runtimeType.properties : [],
+        runtimeType
+      };
+    }
+    return null;
   } finally {
     setProgramContext(null);
   }
 }
+function createLazyTypeResolver(program, filePath) {
+  const cache = /* @__PURE__ */ new Map();
+  return {
+    resolve(name) {
+      if (cache.has(name)) return cache.get(name);
+      const info = extractTypeInfo(program, filePath, name);
+      cache.set(name, info);
+      return info;
+    }
+  };
+}
 function withFileContext(filePath, typeName, fn) {
   try {
     return fn();
@@ -838,7 +977,8 @@ function withFileContext(filePath, typeName, fn) {
       const enriched = new SchemaExtractionError(
         err.typeText,
         `${err.reason}\uFF08\u6587\u4EF6: ${fileName}, \u7C7B\u578B: ${typeName}\uFF09`,
-        { cause: err }
+        { cause: err },
+        err.location
       );
       throw enriched;
     }
@@ -883,9 +1023,13 @@ var init_schemaName = __esm({
 // src/injection/resolveInjection.ts
 import ts4 from "typescript";
 function resolveInjection(fn) {
+  const cached = injectionCache.get(fn);
+  if (cached) {
+    return cached;
+  }
   const fnStr = fn.toString();
   const params = extractParamsWithAst(fnStr);
-  return params.map((param) => {
+  const items = params.map((param) => {
     const type = PARAM_TYPE_MAP[param.name] || "unknown";
     return {
       name: param.name,
@@ -894,6 +1038,8 @@ function resolveInjection(fn) {
       // 运行时类型已擦除
     };
   });
+  injectionCache.set(fn, items);
+  return items;
 }
 function extractParamsWithAst(fnStr) {
   const sourceFile = ts4.createSourceFile(
@@ -950,7 +1096,7 @@ function extractParamName(param, names) {
     return;
   }
 }
-var PARAM_TYPE_MAP;
+var PARAM_TYPE_MAP, injectionCache;
 var init_resolveInjection = __esm({
   "src/injection/resolveInjection.ts"() {
     "use strict";
@@ -973,13 +1119,13 @@ var init_resolveInjection = __esm({
       agents: "agents"
       // Phase 2.3
     };
+    injectionCache = /* @__PURE__ */ new WeakMap();
   }
 });
 
 // src/injection/analyzeInjection.ts
 import ts5 from "typescript";
-function analyzeInjection(code, functionName) {
-  const sourceFile = ts5.createSourceFile("temp.ts", code, ts5.ScriptTarget.Latest, true);
+function analyzeInjectionInSourceFile(sourceFile, functionName) {
   const params = [];
   ts5.forEachChild(sourceFile, (node) => {
     if (ts5.isFunctionDeclaration(node) && node.name?.text === functionName) {
@@ -1041,28 +1187,23 @@ function collectRouteSchemaSources(routes, rootDir) {
     entry.methods.add(route.method);
   }
   const programByFile = createPrograms([...methodsByFile.keys()]);
-  const allTypesByFile = /* @__PURE__ */ new Map();
-  const mergedAllTypes = /* @__PURE__ */ new Map();
+  const resolversByFile = /* @__PURE__ */ new Map();
   for (const filePath of methodsByFile.keys()) {
-    const program = programByFile.get(filePath);
-    const allTypes = extractAllTypes(program, filePath);
-    allTypesByFile.set(filePath, allTypes);
-    for (const [name, info] of allTypes) {
-      mergedAllTypes.set(name, info);
-    }
+    resolversByFile.set(filePath, createLazyTypeResolver(programByFile.get(filePath), filePath));
   }
   const sources = [];
   for (const [filePath, entry] of methodsByFile) {
     const program = programByFile.get(filePath);
     const sourceFile = program.getSourceFile(filePath);
-    const code = sourceFile?.text ?? "";
+    if (!sourceFile) continue;
+    const resolver = resolversByFile.get(filePath);
     for (const method of entry.methods) {
       const inputType = getInputTypeForMethod(method);
       const schemaName = getSchemaName(method, inputType);
-      const meta = analyzeInjection(code, method);
+      const meta = analyzeInjectionInSourceFile(sourceFile, method);
       const param = meta.params.find((p) => p.type === inputType) ?? (inputType === "body" ? meta.params.find((p) => p.type === "form") : void 0);
       const isForm = param?.type === "form";
-      const typeInfo = param?.typeName ? extractTypeInfo(program, filePath, param.typeName) : null;
+      const typeInfo = param?.typeName ? resolver.resolve(param.typeName) : null;
       sources.push({
         urlPath: entry.urlPath,
         filePath,
@@ -1072,7 +1213,7 @@ function collectRouteSchemaSources(routes, rootDir) {
       });
     }
   }
-  return { sources, allTypesByFile, mergedAllTypes };
+  return { sources, resolversByFile };
 }
 var init_collectRouteSchemaSources = __esm({
   "src/cli/collectRouteSchemaSources.ts"() {
@@ -1085,6 +1226,21 @@ var init_collectRouteSchemaSources = __esm({
   }
 });
 
+// src/utils/atomicWrite.ts
+import path7 from "path";
+import fs6 from "fs";
+async function atomicWriteFile(outputPath, content) {
+  await fs6.promises.mkdir(path7.dirname(outputPath), { recursive: true });
+  const tmp = `${outputPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  await fs6.promises.writeFile(tmp, content, "utf-8");
+  await fs6.promises.rename(tmp, outputPath);
+}
+var init_atomicWrite = __esm({
+  "src/utils/atomicWrite.ts"() {
+    "use strict";
+  }
+});
+
 // src/ast/generateZodSchema.ts
 function collectNamedTypes(type, ctx) {
   switch (type.kind) {
@@ -1135,8 +1291,12 @@ function collectNamedTypes(type, ctx) {
       if (resolved) {
         ctx.namedTypes.set(type.name, resolved);
         collectNamedTypes(resolved, ctx);
+        return;
       }
-      return;
+      throw new SchemaExtractionError(
+        type.name,
+        `\u65E0\u6CD5\u89E3\u6790\u547D\u540D\u7C7B\u578B\u5F15\u7528 "${type.name}"\uFF08handler \u6587\u4EF6\u4E0E program \u6E90\u6587\u4EF6\u4E2D\u5747\u672A\u627E\u5230\u540C\u540D\u9876\u5C42\u58F0\u660E\uFF09`
+      );
     }
   }
 }
@@ -1146,6 +1306,12 @@ function runtimeTypeToZodExpression(type, ctx, constraints) {
   if (ctx.coerce && (type.kind === "number" || type.kind === "boolean")) {
     return wrapCoercePreprocess(type.kind, withConstraints);
   }
+  if (ctx.coerce && type.kind === "literal" && (typeof type.value === "number" || typeof type.value === "boolean")) {
+    return wrapCoercePreprocess(
+      typeof type.value === "number" ? "number" : "boolean",
+      withConstraints
+    );
+  }
   return withConstraints;
 }
 function applyConstraints(baseExpr, constraints, typeKind) {
@@ -1210,7 +1376,7 @@ function baseExpression(type, ctx) {
     case "tuple":
       return generateTupleExpression(type.elements, ctx);
     case "object":
-      return generateObjectExpression(type.properties, ctx);
+      return generateObjectExpression(type, ctx);
     case "union":
       return generateUnionExpression(type.members, ctx);
     case "date":
@@ -1262,7 +1428,10 @@ function generateTupleExpression(elements, ctx) {
     }
   }
   if (restExpression) {
-    return `z.tuple([${fixedExprs.join(", ")}]).rest(${restExpression})`;
+    const fixedWithOptional = fixedExprs.map(
+      (expr, i) => fixedOptional[i] ? `${expr}.optional()` : expr
+    );
+    return `z.tuple([${fixedWithOptional.join(", ")}]).rest(${restExpression})`;
   }
   const hasOptional = fixedOptional.some((o) => o);
   if (!hasOptional) {
@@ -1283,13 +1452,14 @@ function generateTupleExpression(elements, ctx) {
   }
   return `z.union([${variants.join(", ")}])`;
 }
-function generateObjectExpression(properties, ctx) {
-  const fields = properties.map((prop) => {
+function generateObjectExpression(type, ctx) {
+  const fields = type.properties.map((prop) => {
     const expr = runtimeTypeToZodExpression(prop.type, ctx, prop.constraints);
     const finalExpr = prop.optional ? `${expr}.optional()` : expr;
     return `${JSON.stringify(prop.name)}: ${finalExpr}`;
   });
-  return `z.object({ ${fields.join(", ")} })`;
+  const objectExpr = `z.object({ ${fields.join(", ")} })`;
+  return type.catchall !== void 0 ? `${objectExpr}.catchall(${runtimeTypeToZodExpression(type.catchall, ctx)})` : objectExpr;
 }
 function generateUnionExpression(members, ctx) {
   const hasNull = members.some((m) => m.kind === "null");
@@ -1335,6 +1505,23 @@ function containsRef(type, visited) {
   }
 }
 function generateZodSchemaSource(typeInfo, resolveType, exportName, coerce = false) {
+  const { namedTypeDeclarations, entryDeclaration } = generateZodSchemaSourceParts(
+    typeInfo,
+    resolveType,
+    exportName,
+    coerce
+  );
+  const lines = [];
+  lines.push("import { z } from 'zod';");
+  lines.push("");
+  for (const { declaration } of namedTypeDeclarations) {
+    lines.push(declaration);
+  }
+  if (namedTypeDeclarations.length > 0) lines.push("");
+  lines.push(entryDeclaration);
+  return lines.join("\n");
+}
+function generateZodSchemaSourceParts(typeInfo, resolveType, exportName, coerce = false) {
   const ctx = new CodeGenContext(resolveType);
   const name = exportName ?? typeInfo.name;
   ctx.entryTypeName = typeInfo.name;
@@ -1342,26 +1529,20 @@ function generateZodSchemaSource(typeInfo, resolveType, exportName, coerce = fal
   ctx.coerce = coerce;
   collectNamedTypes(typeInfo.runtimeType, ctx);
   ctx.namedTypes.delete(typeInfo.name);
-  const lines = [];
-  lines.push("import { z } from 'zod';");
-  lines.push("");
-  for (const [n, type] of ctx.namedTypes) {
-    lines.push(generateNamedTypeDeclaration(n, type, ctx));
-  }
-  if (ctx.namedTypes.size > 0) lines.push("");
+  const namedTypeDeclarations = [...ctx.namedTypes].map(([n, type]) => ({
+    name: n,
+    declaration: generateNamedTypeDeclaration(n, type, ctx)
+  }));
   const entryExpr = runtimeTypeToZodExpression(typeInfo.runtimeType, ctx);
   const hasSelfRef = containsRef(typeInfo.runtimeType, /* @__PURE__ */ new Set([typeInfo.name]));
-  if (hasSelfRef) {
-    lines.push(`export const ${name}Schema = z.lazy(() => ${entryExpr});`);
-  } else {
-    lines.push(`export const ${name}Schema = ${entryExpr};`);
-  }
-  return lines.join("\n");
+  const entryDeclaration = hasSelfRef ? `export const ${name}Schema = z.lazy(() => ${entryExpr});` : `export const ${name}Schema = ${entryExpr};`;
+  return { namedTypeDeclarations, entryDeclaration };
 }
 var CodeGenContext, COERCE_NUMBER_HELPER, COERCE_BOOLEAN_HELPER, COERCE_MAP_HELPER, COERCE_SET_HELPER, HELPERS_FILENAME;
 var init_generateZodSchema = __esm({
   "src/ast/generateZodSchema.ts"() {
     "use strict";
+    init_resolveTypeNode();
     CodeGenContext = class {
       /** 命名类型集合：name → RuntimeType */
       namedTypes = /* @__PURE__ */ new Map();
@@ -1383,7 +1564,7 @@ var init_generateZodSchema = __esm({
       }
     };
     COERCE_NUMBER_HELPER = 'export const coerceNumber = (v) => typeof v === "string" && v.trim() !== "" && !isNaN(Number(v)) ? Number(v) : v;';
-    COERCE_BOOLEAN_HELPER = 'export const coerceBoolean = (v) => v === "true" || v === "1" ? true : v === "false" || v === "0" ? false : v;';
+    COERCE_BOOLEAN_HELPER = 'export const coerceBoolean = (v) => {\n  const lower = typeof v === "string" ? v.toLowerCase() : v;\n  return lower === "true" || lower === "1" ? true : lower === "false" || lower === "0" ? false : v;\n};';
     COERCE_MAP_HELPER = 'export const coerceMap = (v) => Array.isArray(v) ? new Map(v) : v instanceof Map ? v : (v && typeof v === "object" ? new Map(Object.entries(v)) : v);';
     COERCE_SET_HELPER = "export const coerceSet = (v) => v instanceof Set ? v : (Array.isArray(v) ? new Set(v) : v);";
     HELPERS_FILENAME = "faapi-helpers.js";
@@ -1399,8 +1580,7 @@ __export(generateSchemaFiles_exports, {
   getRuntimeSchemaPath: () => getRuntimeSchemaPath,
   getSchemaOutputPath: () => getSchemaOutputPath
 });
-import path6 from "path";
-import fs5 from "fs/promises";
+import path8 from "path";
 function getSchemaOutputPath(sourceFile, dist, rootDir) {
   let rel = sourceFile.replace(/\\/g, "/");
   if (rel.startsWith("src/")) {
@@ -1408,7 +1588,7 @@ function getSchemaOutputPath(sourceFile, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path6.resolve(rootDir, dist, relDir, "zod.js");
+  return path8.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getRuntimeSchemaPath(filePath, dist, rootDir) {
   let rel = filePath.replace(/\\/g, "/");
@@ -1419,16 +1599,17 @@ function getRuntimeSchemaPath(filePath, dist, rootDir) {
   }
   const idx = rel.lastIndexOf("/");
   const relDir = idx >= 0 ? rel.slice(0, idx) : "";
-  return path6.resolve(rootDir, dist, relDir, "zod.js");
+  return path8.resolve(rootDir, dist, relDir, "zod.js");
 }
 function getHelpersImportPath(relDir) {
   if (!relDir) return `./${HELPERS_FILENAME}`;
   const depth = relDir.split("/").filter(Boolean).length;
   return `${"../".repeat(depth)}${HELPERS_FILENAME}`;
 }
-function generateSchemaFileSource(sources, allTypes, helpersImportPath) {
-  const resolveType = (name) => allTypes.get(name)?.runtimeType;
+function generateSchemaFileSource(sources, resolveType, helpersImportPath) {
   const lines = ["import { z } from 'zod';"];
+  const namedTypeDeclarations = [];
+  const seenNamedTypes = /* @__PURE__ */ new Set();
   const schemaBlocks = [];
   for (const source of sources) {
     const { schemaName, typeInfo } = source;
@@ -1436,16 +1617,24 @@ function generateSchemaFileSource(sources, allTypes, helpersImportPath) {
       continue;
     }
     const coerce = source.coerce ?? /(?:Query|Params)$/.test(schemaName);
-    const block = [`// ${schemaName}`];
-    const schemaCode = generateZodSchemaSource(typeInfo, resolveType, schemaName, coerce).replace(
-      /^import \{ z \} from 'zod';\s*\n\s*\n/,
-      ""
+    const { namedTypeDeclarations: decls, entryDeclaration } = generateZodSchemaSourceParts(
+      typeInfo,
+      resolveType,
+      schemaName,
+      coerce
     );
-    block.push(schemaCode);
-    block.push("");
-    schemaBlocks.push(block.join("\n"));
+    for (const { name, declaration } of decls) {
+      if (seenNamedTypes.has(name)) continue;
+      seenNamedTypes.add(name);
+      namedTypeDeclarations.push(declaration);
+    }
+    schemaBlocks.push([`// ${schemaName}`, entryDeclaration, ""].join("\n"));
   }
-  const allSchemaCode = schemaBlocks.join("\n");
+  if (namedTypeDeclarations.length > 0) {
+    lines.push(...namedTypeDeclarations);
+    lines.push("");
+  }
+  const allSchemaCode = [...namedTypeDeclarations, ...schemaBlocks].join("\n");
   if (helpersImportPath && usesCoerceHelpers(allSchemaCode)) {
     lines.push(
       `import { coerceNumber, coerceBoolean, coerceMap, coerceSet } from '${helpersImportPath}';`
@@ -1457,7 +1646,7 @@ function generateSchemaFileSource(sources, allTypes, helpersImportPath) {
 }
 async function generateSchemaFiles(routes, rootDir, dist) {
   if (routes.length === 0) return;
-  const { sources, allTypesByFile } = collectRouteSchemaSources(routes, rootDir);
+  const { sources, resolversByFile } = collectRouteSchemaSources(routes, rootDir);
   const sourcesByFile = /* @__PURE__ */ new Map();
   for (const source of sources) {
     let list = sourcesByFile.get(source.filePath);
@@ -1469,9 +1658,8 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path6.relative(rootDir, filePath).replace(/\\/g, "/");
+    const relFile = path8.relative(rootDir, filePath).replace(/\\/g, "/");
     const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
-    const allTypes = allTypesByFile.get(filePath) ?? /* @__PURE__ */ new Map();
     let relForDir = relFile;
     if (relForDir.startsWith("src/")) {
       relForDir = relForDir.slice(4);
@@ -1479,12 +1667,17 @@ async function generateSchemaFiles(routes, rootDir, dist) {
     const dirIdx = relForDir.lastIndexOf("/");
     const zodRelDir = dirIdx >= 0 ? relForDir.slice(0, dirIdx) : "";
     const helpersImportPath = getHelpersImportPath(zodRelDir);
-    const source = generateSchemaFileSource(fileSources, allTypes, helpersImportPath);
+    const resolver = resolversByFile.get(filePath);
+    const source = generateSchemaFileSource(
+      fileSources,
+      (name) => resolver?.resolve(name)?.runtimeType,
+      helpersImportPath
+    );
     fileEntries.push({ outputPath, source });
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
   if (usesCoerceHelpers(allSourceCode)) {
-    const helpersPath = path6.resolve(rootDir, dist, HELPERS_FILENAME);
+    const helpersPath = path8.resolve(rootDir, dist, HELPERS_FILENAME);
     await writeSchemaFile(helpersPath, generateHelpersFileSource());
   }
   await Promise.all(
@@ -1492,12 +1685,12 @@ async function generateSchemaFiles(routes, rootDir, dist) {
   );
 }
 async function writeSchemaFile(outputPath, source) {
-  await fs5.mkdir(path6.dirname(outputPath), { recursive: true });
-  await fs5.writeFile(outputPath, source, "utf-8");
+  await atomicWriteFile(outputPath, source);
 }
 var init_generateSchemaFiles = __esm({
   "src/cli/generateSchemaFiles.ts"() {
     "use strict";
+    init_atomicWrite();
     init_collectRouteSchemaSources();
     init_generateZodSchema();
   }
@@ -1510,95 +1703,178 @@ init_resolveTypeNode();
 init_inputType();
 init_collectRouteSchemaSources();
 
-// 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;
+// src/injection/registries.ts
+function createToolRegistry() {
+  let registry = /* @__PURE__ */ new Map();
+  return {
+    hydrate(tools) {
+      const next = /* @__PURE__ */ new Map();
+      for (const tool of tools) {
+        next.set(tool.name, tool);
+      }
+      registry = next;
+    },
+    get(name) {
+      return registry.get(name);
+    },
+    list() {
+      return Array.from(registry.values());
+    },
+    clear() {
+      registry = /* @__PURE__ */ new Map();
+    }
+  };
 }
-function clearToolRegistry() {
-  registry = /* @__PURE__ */ new Map();
+function createAgentRegistry(tool) {
+  let registry = /* @__PURE__ */ new Map();
+  const getAgent2 = (name) => registry.get(name);
+  return {
+    hydrate(agents) {
+      const next = /* @__PURE__ */ new Map();
+      for (const agent of agents) {
+        next.set(agent.name, agent);
+      }
+      registry = next;
+    },
+    getAgent: getAgent2,
+    getAgentEntry(name) {
+      return registry.get(name);
+    },
+    listAgents() {
+      const merged = /* @__PURE__ */ new Map();
+      for (const agent of registry.values()) merged.set(agent.name, agent);
+      return Array.from(merged.values());
+    },
+    asTool(name) {
+      const agent = getAgent2(name);
+      if (!agent) return void 0;
+      return {
+        kind: "agent",
+        name: `agent.${agent.name}`,
+        agentName: agent.name,
+        description: agent.description,
+        metadata: agent
+      };
+    },
+    resolveAgentTools(name) {
+      const agent = getAgent2(name);
+      if (!agent) return [];
+      const result = /* @__PURE__ */ new Map();
+      if (agent.tools) {
+        for (const toolName of agent.tools) {
+          const resolved = tool.get(toolName);
+          if (resolved) result.set(resolved.name, resolved);
+        }
+      }
+      return Array.from(result.values());
+    },
+    resolveSubAgents(name) {
+      const agent = getAgent2(name);
+      if (!agent || !agent.agents) return [];
+      const result = [];
+      for (const subName of agent.agents) {
+        const sub = getAgent2(subName);
+        if (sub) result.push(sub);
+      }
+      return result;
+    },
+    clear() {
+      registry = /* @__PURE__ */ new Map();
+    }
+  };
 }
-function getTool(name) {
-  return registry.get(name);
+function createSkillRegistry() {
+  let registry = /* @__PURE__ */ new Map();
+  return {
+    hydrate(skills) {
+      const next = /* @__PURE__ */ new Map();
+      for (const skill of skills) {
+        next.set(skill.name, skill);
+      }
+      registry = next;
+    },
+    upsert(skill) {
+      registry.set(skill.name, skill);
+    },
+    remove(name) {
+      registry.delete(name);
+    },
+    get(name) {
+      return registry.get(name);
+    },
+    list() {
+      return Array.from(registry.values());
+    },
+    clear() {
+      registry = /* @__PURE__ */ new Map();
+    }
+  };
 }
-
-// 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 createAgentHandleStore() {
+  let currentFactory = null;
+  return {
+    register(factory) {
+      currentFactory = factory;
+    },
+    get(ctx) {
+      if (currentFactory === null) return void 0;
+      return currentFactory(ctx);
+    },
+    clear() {
+      currentFactory = null;
+    }
+  };
 }
-function clearAgentRegistry() {
-  registry2 = /* @__PURE__ */ new Map();
+function createAppRegistries() {
+  const tool = createToolRegistry();
+  const agent = createAgentRegistry(tool);
+  const skill = createSkillRegistry();
+  const agentHandle = createAgentHandleStore();
+  return { tool, agent, skill, agentHandle };
 }
+var defaultRegistries = createAppRegistries();
+
+// src/injection/agentRegistry.ts
 function getAgent(name) {
-  return registry2.get(name);
+  return defaultRegistries.agent.getAgent(name);
 }
 function getAgentEntry(name) {
-  return registry2.get(name);
+  return defaultRegistries.agent.getAgentEntry(name);
 }
 function listAgents() {
-  const merged = /* @__PURE__ */ new Map();
-  for (const agent of registry2.values()) merged.set(agent.name, agent);
-  return Array.from(merged.values());
+  return defaultRegistries.agent.listAgents();
 }
 function resolveAgentTools(name) {
-  const agent = getAgent(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());
+  return defaultRegistries.agent.resolveAgentTools(name);
 }
 function resolveSubAgents(name) {
-  const agent = getAgent(name);
-  if (!agent || !agent.agents) return [];
-  const result = [];
-  for (const agentName of agent.agents) {
-    const subAgent = getAgent(agentName);
-    if (subAgent) result.push(subAgent);
-  }
-  return result;
+  return defaultRegistries.agent.resolveSubAgents(name);
+}
+
+// src/injection/toolRegistry.ts
+function getTool(name) {
+  return defaultRegistries.tool.get(name);
 }
 
 // src/injection/skillRegistry.ts
-var registry3 = /* @__PURE__ */ new Map();
 function hydrateSkillRegistry(skills) {
-  const next = /* @__PURE__ */ new Map();
-  for (const skill of skills) {
-    next.set(skill.name, skill);
-  }
-  registry3 = next;
-}
-function clearSkillRegistry() {
-  registry3 = /* @__PURE__ */ new Map();
+  defaultRegistries.skill.hydrate(skills);
 }
 function upsertSkill(core) {
-  registry3.set(core.name, core);
+  defaultRegistries.skill.upsert(core);
 }
 function removeSkill(name) {
-  registry3.delete(name);
+  defaultRegistries.skill.remove(name);
 }
 function getSkill(name) {
-  return registry3.get(name);
+  return defaultRegistries.skill.get(name);
 }
 function listSkills() {
-  return Array.from(registry3.values());
+  return defaultRegistries.skill.list();
 }
 
 // src/loader/loadAgentModule.ts
-import fs7 from "fs";
+import fs9 from "fs";
 
 // src/loader/resolveExports.ts
 function resolveExport(module, exportName) {
@@ -1618,8 +1894,8 @@ function resolveExport(module, exportName) {
 // src/utils/importWithCacheBust.ts
 import { pathToFileURL } from "url";
 var loadTs;
-function setLoadTimestamp(ts9) {
-  loadTs = ts9;
+function setLoadTimestamp(ts10) {
+  loadTs = ts10;
 }
 function getVitestImportActual() {
   const vi = globalThis.vi;
@@ -1644,17 +1920,17 @@ async function importWithCacheBust(filePath, bustViteCache = false) {
 }
 
 // src/cli/compileOnDemand.ts
-import path7 from "path";
-import fs6 from "fs";
+import path10 from "path";
+import fs8 from "fs";
 
-// src/cli/compileDevRoutes.ts
-import path5 from "path";
-import fs4 from "fs";
+// src/cli/compileSourceFiles.ts
+import path6 from "path";
+import fs5 from "fs";
 import fg from "fast-glob";
 
 // src/cli/aliasPlugin.ts
-import path4 from "path";
-import fs3 from "fs";
+import path5 from "path";
+import fs4 from "fs";
 
 // src/utils/resolveAlias.ts
 function resolveAlias(specifier, config) {
@@ -1679,57 +1955,84 @@ function resolveAlias(specifier, config) {
   return candidates;
 }
 
-// src/utils/readTsconfig.ts
-import ts6 from "typescript";
+// src/utils/prodPaths.ts
 import path3 from "path";
 import fs2 from "fs";
-function readTsconfig(rootDir) {
-  const tsconfigPath = path3.resolve(rootDir, "tsconfig.json");
-  if (!fs2.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) => path3.resolve(baseUrl, t));
+var APP_DIR = "src";
+var ROUTE_PATTERNS = ["src/api/**/*.ts"];
+function toProdFilePath(filePath, dist) {
+  let rel = filePath.replace(/\\/g, "/");
+  if (rel.startsWith("src/")) {
+    rel = rel.slice(4);
   }
-  return { baseUrl, paths };
+  const jsPath = rel.replace(/\.ts$/, ".js");
+  return jsPath.startsWith(`${dist}/`) ? jsPath : `${dist}/${jsPath}`;
 }
-
-// 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 toProdImportPath(sourceFile, importer) {
-  const importerDir = path4.dirname(importer);
-  let rel = path4.relative(importerDir, sourceFile);
-  rel = rel.split(path4.sep).join("/");
-  if (!rel.startsWith(".")) rel = "./" + rel;
-  return toProdExtension(rel);
-}
 function toRealPath(p) {
   try {
-    return fs3.realpathSync(p);
+    return fs2.realpathSync(p);
   } catch {
     return p;
   }
 }
 function isInsideDir(filePath, dir) {
-  const rel = path4.relative(dir, filePath);
-  return rel !== "" && !rel.startsWith("..") && !path4.isAbsolute(rel);
+  const rel = path3.relative(dir, filePath);
+  return rel !== "" && !rel.startsWith("..") && !path3.isAbsolute(rel);
+}
+
+// src/utils/readTsconfig.ts
+import ts6 from "typescript";
+import path4 from "path";
+import fs3 from "fs";
+var tsconfigCache = /* @__PURE__ */ new Map();
+function readTsconfig(rootDir) {
+  const tsconfigPath = path4.resolve(rootDir, "tsconfig.json");
+  if (!fs3.existsSync(tsconfigPath)) return null;
+  let mtimeMs;
+  try {
+    mtimeMs = fs3.statSync(tsconfigPath).mtimeMs;
+  } catch {
+    return null;
+  }
+  const cached = tsconfigCache.get(tsconfigPath);
+  if (cached && cached.mtimeMs === mtimeMs) {
+    return cached.config;
+  }
+  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;
+  const config = rawPaths ? (() => {
+    const paths = {};
+    for (const [pattern, targets] of Object.entries(rawPaths)) {
+      paths[pattern] = targets.map((t) => path4.resolve(baseUrl, t));
+    }
+    return { baseUrl, paths };
+  })() : null;
+  tsconfigCache.set(tsconfigPath, { mtimeMs, config });
+  return config;
+}
+
+// src/cli/aliasPlugin.ts
+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);
 }
-var APP_DIR = "src";
 function toStrippedProdImportPath(sourceFile, rootDir) {
-  const appDirAbs = toRealPath(path4.resolve(rootDir, APP_DIR));
+  const appDirAbs = toRealPath(path5.resolve(rootDir, APP_DIR));
   const sourceReal = toRealPath(sourceFile);
-  let rel = path4.relative(appDirAbs, sourceReal);
-  rel = rel.split(path4.sep).join("/");
+  let rel = path5.relative(appDirAbs, sourceReal);
+  rel = rel.split(path5.sep).join("/");
   if (!rel.startsWith(".")) rel = "./" + rel;
   return toProdExtension(rel);
 }
@@ -1744,41 +2047,41 @@ var INDEX_EXTS = [
   "/index.cjs"
 ];
 function resolveRelativeSpecifier(importer, specifier) {
-  const importerDir = path4.dirname(importer);
-  const base = path4.resolve(importerDir, specifier);
+  const importerDir = path5.dirname(importer);
+  const base = path5.resolve(importerDir, specifier);
   if (PROD_EXTS.some((ext) => specifier.endsWith(ext))) {
-    return fs3.existsSync(base) ? base : null;
+    return fs4.existsSync(base) ? base : null;
   }
   if (/\.(ts|tsx|jsx)$/.test(specifier)) {
-    return fs3.existsSync(base) ? base : null;
+    return fs4.existsSync(base) ? base : null;
   }
   for (const ext of SOURCE_EXTS) {
     const file = base + ext;
-    if (fs3.existsSync(file)) return file;
+    if (fs4.existsSync(file)) return file;
   }
   for (const indexExt of INDEX_EXTS) {
     const file = base + indexExt;
-    if (fs3.existsSync(file)) return file;
+    if (fs4.existsSync(file)) return file;
   }
   return null;
 }
 function createAliasPlugin(config, options) {
-  const SPEC_RE = /(\bfrom\s*|import\s*\(\s*)(['"])([^'"]+)\2/g;
-  const appDirAbs = options?.rootDir ? toRealPath(path4.resolve(options.rootDir, APP_DIR)) : null;
+  const SPEC_RE2 = /(\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 = fs3.readFileSync(args.path, "utf8");
+          source = fs4.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) => {
+        const newSource = source.replace(SPEC_RE2, (full, prefix, quote, specifier) => {
           if (specifier.startsWith("/") || specifier.startsWith("file:") || specifier.startsWith("node:")) {
             return full;
           }
@@ -1804,7 +2107,7 @@ function createAliasPlugin(config, options) {
           for (const candidate of candidates) {
             for (const ext of SOURCE_EXTS) {
               const file = candidate + ext;
-              if (fs3.existsSync(file)) {
+              if (fs4.existsSync(file)) {
                 modified = true;
                 if (appDirAbs && importerOutsideAppDir && isInsideDir(file, appDirAbs)) {
                   return `${prefix}${quote}${toStrippedProdImportPath(
@@ -1817,7 +2120,7 @@ function createAliasPlugin(config, options) {
             }
             for (const indexExt of INDEX_EXTS) {
               const file = candidate + indexExt;
-              if (fs3.existsSync(file)) {
+              if (fs4.existsSync(file)) {
                 modified = true;
                 if (appDirAbs && importerOutsideAppDir && isInsideDir(file, appDirAbs)) {
                   return `${prefix}${quote}${toStrippedProdImportPath(
@@ -1842,11 +2145,10 @@ function buildAliasPlugins(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`], {
+// src/cli/compileSourceFiles.ts
+async function compileSourceFiles(options) {
+  const { rootDir, dist, files, logLevel = "silent", production, atomicWrite } = options;
+  const entryPoints = files ?? await fg([`${APP_DIR}/**/*.ts`], {
     cwd: rootDir,
     onlyFiles: true,
     absolute: true,
@@ -1855,11 +2157,11 @@ async function compileDevRoutes(options) {
   if (entryPoints.length === 0) {
     return { compiledFiles: [] };
   }
-  const absDist = path5.resolve(rootDir, dist);
-  await fs4.promises.mkdir(absDist, { recursive: true });
+  const absDist = path6.resolve(rootDir, dist);
+  await fs5.promises.mkdir(absDist, { recursive: true });
   const plugins = buildAliasPlugins(rootDir);
   const esbuild = await import("esbuild");
-  const outbase = path5.resolve(rootDir, APP_DIR2);
+  const outbase = path6.resolve(rootDir, APP_DIR);
   const result = await esbuild.build({
     entryPoints,
     outdir: absDist,
@@ -1870,29 +2172,106 @@ async function compileDevRoutes(options) {
     sourcemap: true,
     packages: "external",
     plugins,
+    // build 语义：编译期 NODE_ENV 替换 + 死分支删除（见 AGENTS.md §5.3）
+    ...production ? { define: { "process.env.NODE_ENV": '"production"' }, minifySyntax: true } : {},
     logLevel,
-    write: false
+    // dev 语义：esbuild 返回内存内容，由下方原子写落盘
+    ...atomicWrite ? { write: false } : {}
   });
-  if (result.outputFiles) {
+  if (atomicWrite && result.outputFiles) {
     await Promise.all(
       result.outputFiles.map(async (file) => {
-        await fs4.promises.mkdir(path5.dirname(file.path), { recursive: true });
+        await fs5.promises.mkdir(path6.dirname(file.path), { recursive: true });
         const tmp = `${file.path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-        await fs4.promises.writeFile(tmp, file.contents);
-        await fs4.promises.rename(tmp, file.path);
+        await fs5.promises.writeFile(tmp, file.contents);
+        await fs5.promises.rename(tmp, file.path);
       })
     );
   }
   return { compiledFiles: entryPoints };
 }
 
+// src/cli/compileDevRoutes.ts
+async function compileDevRoutes(options) {
+  return compileSourceFiles({ ...options, atomicWrite: true });
+}
+
 // src/cli/compileOnDemand.ts
 init_generateSchemaFiles();
 init_generateSchemaFiles();
+
+// src/cli/collectImports.ts
+import path9 from "path";
+import fs7 from "fs";
+var SPEC_RE = /(\bfrom\s*|import\s*\(\s*)(['"])([^'"]+)\2/g;
+function extractImportSpecifiers(source) {
+  const specifiers = [];
+  let match;
+  SPEC_RE.lastIndex = 0;
+  while ((match = SPEC_RE.exec(source)) !== null) {
+    specifiers.push(match[3]);
+  }
+  return specifiers;
+}
+function resolveSpecifierFromDir(dir, specifier) {
+  return resolveRelativeSpecifier(path9.join(dir, "__faapi_probe__.ts"), specifier);
+}
+async function collectRelativeImports(entryFiles, rootDir) {
+  const appDirAbs = toRealPath(path9.resolve(rootDir, "src"));
+  const tsconfig = readTsconfig(rootDir);
+  const visited = /* @__PURE__ */ new Set();
+  const insideFiles = /* @__PURE__ */ new Set();
+  const outsideFiles = /* @__PURE__ */ new Set();
+  async function collect(filePath) {
+    if (visited.has(filePath)) return;
+    visited.add(filePath);
+    let source;
+    try {
+      source = await fs7.promises.readFile(filePath, "utf8");
+    } catch {
+      return;
+    }
+    for (const specifier of extractImportSpecifiers(source)) {
+      if (/\.(js|mjs|cjs)$/.test(specifier)) continue;
+      let resolved;
+      if (specifier.startsWith("./") || specifier.startsWith("../")) {
+        resolved = resolveRelativeSpecifier(filePath, specifier);
+      } else if (tsconfig) {
+        resolved = null;
+        for (const candidate of resolveAlias(specifier, tsconfig)) {
+          const probed = resolveSpecifierFromDir(rootDir, candidate);
+          if (probed) {
+            resolved = probed;
+            break;
+          }
+        }
+      } else {
+        resolved = null;
+      }
+      if (!resolved) continue;
+      if (!isInsideDir(toRealPath(resolved), toRealPath(path9.resolve(rootDir)))) continue;
+      if (isInsideDir(toRealPath(resolved), appDirAbs)) {
+        insideFiles.add(resolved);
+      } else {
+        outsideFiles.add(resolved);
+      }
+      await collect(resolved);
+    }
+  }
+  for (const entry of entryFiles) {
+    await collect(entry);
+  }
+  return {
+    insideFiles: Array.from(insideFiles),
+    outsideFiles: Array.from(outsideFiles)
+  };
+}
+
+// src/cli/compileOnDemand.ts
 function isProductFresh(sourceAbsPath, productAbsPath) {
   try {
-    const srcStat = fs6.statSync(sourceAbsPath);
-    const prodStat = fs6.statSync(productAbsPath);
+    const srcStat = fs8.statSync(sourceAbsPath);
+    const prodStat = fs8.statSync(productAbsPath);
     return prodStat.mtimeMs >= srcStat.mtimeMs;
   } catch {
     return false;
@@ -1915,16 +2294,16 @@ function clearCompiledFiles() {
   sourcePathCache.clear();
 }
 async function ensureCompiled(sourceAbsPath, rootDir, dist) {
-  const inFlight = state.inFlightCompilations.get(sourceAbsPath);
-  if (inFlight) {
-    await inFlight.catch(() => {
+  const inFlight2 = state.inFlightCompilations.get(sourceAbsPath);
+  if (inFlight2) {
+    await inFlight2.catch(() => {
     });
     return false;
   }
   if (state.compiledFiles.has(sourceAbsPath)) {
     return false;
   }
-  if (!fs6.existsSync(sourceAbsPath)) {
+  if (!fs8.existsSync(sourceAbsPath)) {
     return false;
   }
   const productPath = prodSourcePathToProductPath(sourceAbsPath, rootDir, dist);
@@ -1933,12 +2312,23 @@ async function ensureCompiled(sourceAbsPath, rootDir, dist) {
     return false;
   }
   const compilePromise = (async () => {
+    const { insideFiles } = await collectRelativeImports([sourceAbsPath], rootDir);
+    const files = [sourceAbsPath];
+    for (const dep of insideFiles) {
+      if (state.compiledFiles.has(dep)) continue;
+      const depProduct = prodSourcePathToProductPath(dep, rootDir, dist);
+      if (depProduct && isProductFresh(dep, depProduct)) continue;
+      files.push(dep);
+    }
     await compileDevRoutes({
       rootDir,
       dist,
-      files: [sourceAbsPath],
+      files,
       logLevel: "silent"
     });
+    for (const file of files) {
+      state.compiledFiles.add(file);
+    }
     state.compiledFiles.add(sourceAbsPath);
   })();
   state.inFlightCompilations.set(sourceAbsPath, compilePromise);
@@ -1949,30 +2339,43 @@ async function ensureCompiled(sourceAbsPath, rootDir, dist) {
     state.inFlightCompilations.delete(sourceAbsPath);
   }
 }
+async function ensureMiddlewaresCompiled(middlewarePaths, rootDir) {
+  if (!isDevOnDemandEnabled() || middlewarePaths.length === 0) return;
+  const dist = getDevDist();
+  if (!dist) return;
+  for (const mwPath of middlewarePaths) {
+    const sourcePath = prodPathToSourcePath(mwPath, rootDir, dist);
+    try {
+      await ensureCompiled(sourcePath, rootDir, dist);
+    } catch (err) {
+      console.error(`[faapi] Failed to compile middleware source ${sourcePath}:`, err);
+    }
+  }
+}
 function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
-  const rel = path7.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  const rel = path10.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
   if (!rel.startsWith("src/")) return null;
   const relWithoutSrc = rel.slice(4);
   const jsRel = relWithoutSrc.replace(/\.ts$/, ".js");
-  return path7.resolve(rootDir, dist, jsRel);
+  return path10.resolve(rootDir, dist, jsRel);
 }
 function clearGeneratedSchemas() {
   state.generatedSchemas.clear();
   state.inFlightSchemaGenerations.clear();
 }
 async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir, dist) {
-  const inFlight = state.inFlightSchemaGenerations.get(schemaPath);
-  if (inFlight) {
-    await inFlight.catch(() => {
+  const inFlight2 = state.inFlightSchemaGenerations.get(schemaPath);
+  if (inFlight2) {
+    await inFlight2.catch(() => {
     });
     return false;
   }
   if (state.generatedSchemas.has(schemaPath)) {
     return false;
   }
-  const prodAbsPath = path7.resolve(rootDir, routeFilePath);
+  const prodAbsPath = path10.resolve(rootDir, routeFilePath);
   const sourceAbsPath = prodPathToSourcePath(prodAbsPath, rootDir, dist);
-  if (!fs6.existsSync(sourceAbsPath)) {
+  if (!fs8.existsSync(sourceAbsPath)) {
     return false;
   }
   if (isProductFresh(sourceAbsPath, schemaPath)) {
@@ -1983,7 +2386,7 @@ async function ensureSchemaGenerated(schemaPath, routeFilePath, routes, rootDir,
   if (fileRoutes.length === 0) {
     return false;
   }
-  const sourceRelPath = path7.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
+  const sourceRelPath = path10.relative(rootDir, sourceAbsPath).replace(/\\/g, "/");
   const sourceRoutes = fileRoutes.map((r) => ({ ...r, filePath: sourceRelPath }));
   const generatePromise = (async () => {
     await generateSchemaFiles(sourceRoutes, rootDir, dist);
@@ -2004,7 +2407,7 @@ async function deleteSchemaFiles(routes, rootDir, dist) {
     if (deleted.has(schemaPath)) continue;
     deleted.add(schemaPath);
     try {
-      await fs6.promises.unlink(schemaPath);
+      await fs8.promises.unlink(schemaPath);
     } catch {
     }
   }
@@ -2013,19 +2416,19 @@ var sourcePathCache = /* @__PURE__ */ new Map();
 function prodPathToSourcePath(prodAbsPath, rootDir, dist) {
   const cached = sourcePathCache.get(prodAbsPath);
   if (cached) return cached;
-  const rel = path7.relative(rootDir, prodAbsPath).replace(/\\/g, "/");
+  const rel = path10.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 = path7.resolve(rootDir, tsRel);
+  const tsAbs = path10.resolve(rootDir, tsRel);
   let result;
-  if (fs6.existsSync(tsAbs)) {
+  if (fs8.existsSync(tsAbs)) {
     result = tsAbs;
   } else {
-    result = path7.resolve(rootDir, srcRel);
+    result = path10.resolve(rootDir, srcRel);
   }
   sourcePathCache.set(prodAbsPath, result);
   return result;
@@ -2043,7 +2446,7 @@ async function loadAgentModule(filePath, hasRun, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs7.existsSync(sourcePath)) {
+      if (sourcePath && fs9.existsSync(sourcePath)) {
         try {
           await ensureCompiled(sourcePath, rootDir, dist);
         } catch (compileErr) {
@@ -2076,13 +2479,13 @@ async function loadAgentModule(filePath, hasRun, rootDir) {
 }
 
 // src/loader/loadToolModule.ts
-import fs8 from "fs";
+import fs10 from "fs";
 async function loadToolModule(filePath, functionName, rootDir) {
   if (isDevOnDemandEnabled() && rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs8.existsSync(sourcePath)) {
+      if (sourcePath && fs10.existsSync(sourcePath)) {
         try {
           await ensureCompiled(sourcePath, rootDir, dist);
         } catch (compileErr) {
@@ -2114,12 +2517,46 @@ async function loadToolModule(filePath, functionName, rootDir) {
 import { existsSync as existsSync2 } from "fs";
 
 // src/cli/generateToolArtifacts.ts
-import path8 from "path";
-import fs9 from "fs/promises";
+import path11 from "path";
 import { existsSync } from "fs";
 
 // src/ast/extractToolMetadata.ts
+import ts8 from "typescript";
+
+// src/ast/jsDocMetadata.ts
 import ts7 from "typescript";
+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 extractJSDocTagValue(jsDoc, tagName) {
+  if (!jsDoc || !jsDoc.tags) return void 0;
+  for (const tag of jsDoc.tags) {
+    if (tag.tagName.text !== tagName) 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;
+}
+
+// src/ast/extractToolMetadata.ts
 function extractToolMetadata(program, filePath, functionName, pathMeta) {
   const sourceFile = program.getSourceFile(filePath);
   if (!sourceFile) return null;
@@ -2128,7 +2565,7 @@ function extractToolMetadata(program, filePath, functionName, pathMeta) {
   const { fn, jsDocOwner } = found;
   const jsDoc = getJSDocFromNode(jsDocOwner);
   const description = extractDescription(jsDoc);
-  const toolNameOverride = extractToolTagValue(jsDoc);
+  const toolNameOverride = extractJSDocTagValue(jsDoc, "tool");
   const inputTypeName = getFirstParamTypeName(fn, sourceFile);
   return {
     name: toolNameOverride ?? pathMeta.name,
@@ -2140,18 +2577,18 @@ function extractToolMetadata(program, filePath, functionName, pathMeta) {
 }
 function findExportedFunction(sourceFile, functionName) {
   let result = null;
-  ts7.forEachChild(sourceFile, (node) => {
+  ts8.forEachChild(sourceFile, (node) => {
     if (result) return;
-    if (ts7.isFunctionDeclaration(node) && hasExportModifier(node) && node.name?.text === functionName) {
+    if (ts8.isFunctionDeclaration(node) && hasExportModifier(node) && node.name?.text === functionName) {
       result = { fn: node, jsDocOwner: node };
       return;
     }
-    if (ts7.isVariableStatement(node) && hasExportModifier(node)) {
+    if (ts8.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);
+        const nameText = ts8.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)) {
+        if (ts8.isArrowFunction(decl.initializer) || ts8.isFunctionExpression(decl.initializer)) {
           result = { fn: decl.initializer, jsDocOwner: node };
         }
       }
@@ -2159,78 +2596,23 @@ function findExportedFunction(sourceFile, functionName) {
   });
   return result;
 }
-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 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;
+  if (!ts8.isTypeReferenceNode(firstParam.type)) return void 0;
   return firstParam.type.typeName.getText(sourceFile);
 }
-
-// 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 path8.resolve(rootDir, dist, relDir, "zod.js");
-}
-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 path8.resolve(rootDir, dist, relDir, "zod.js");
-}
-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}`;
-}
+
+// src/cli/generateToolArtifacts.ts
+init_createProgram();
+init_atomicWrite();
+init_generateSchemaFiles();
+init_extractHandlerTypes();
+init_generateZodSchema();
+init_generateSchemaFiles();
+init_generateSchemaFiles();
+var TOOLS_FILE = "faapi-tools.js";
 function serializeTools(tools, dist = "dist") {
   return tools.map((t) => ({
     name: t.name,
@@ -2241,12 +2623,10 @@ function serializeTools(tools, dist = "dist") {
   }));
 }
 async function writeToolsModule(manifest, outputPath) {
-  const dir = path8.dirname(outputPath);
-  await fs9.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 fs9.writeFile(outputPath, content, "utf-8");
+  await atomicWriteFile(outputPath, content);
 }
 function hydrateTools(manifest) {
   return manifest.map((t) => ({
@@ -2261,7 +2641,7 @@ function collectToolSchemaSources(tools, rootDir) {
   const toolsByFile = /* @__PURE__ */ new Map();
   for (const tool of tools) {
     if (!tool.inputTypeName) continue;
-    const absPath = path8.resolve(rootDir, tool.filePath);
+    const absPath = path11.resolve(rootDir, tool.filePath);
     let list = toolsByFile.get(absPath);
     if (!list) {
       list = [];
@@ -2270,11 +2650,9 @@ function collectToolSchemaSources(tools, rootDir) {
     list.push(tool);
   }
   const programByFile = createPrograms([...toolsByFile.keys()]);
-  const allTypesByFile = /* @__PURE__ */ new Map();
+  const resolversByFile = /* @__PURE__ */ new Map();
   for (const filePath of toolsByFile.keys()) {
-    const program = programByFile.get(filePath);
-    const allTypes = extractAllTypes(program, filePath);
-    allTypesByFile.set(filePath, allTypes);
+    resolversByFile.set(filePath, createLazyTypeResolver(programByFile.get(filePath), filePath));
   }
   const sources = [];
   for (const [filePath, fileTools] of toolsByFile) {
@@ -2291,10 +2669,9 @@ function collectToolSchemaSources(tools, rootDir) {
       });
     }
   }
-  return { sources, allTypesByFile };
+  return { sources, resolversByFile };
 }
-function generateToolSchemaFileSource(sources, allTypes, helpersImportPath) {
-  const resolveType = (name) => allTypes.get(name)?.runtimeType;
+function generateToolSchemaFileSource(sources, resolveType, helpersImportPath) {
   const lines = ["import { z } from 'zod';"];
   const schemaBlocks = [];
   for (const source of sources) {
@@ -2324,16 +2701,15 @@ function generateToolSchemaFileSource(sources, allTypes, helpersImportPath) {
 }
 async function maybeGenerateHelpers(allSourceCode, distDir) {
   if (!usesCoerceHelpers(allSourceCode)) return;
-  const helpersPath = path8.resolve(distDir, HELPERS_FILENAME);
+  const helpersPath = path11.resolve(distDir, HELPERS_FILENAME);
   if (existsSync(helpersPath)) return;
-  await fs9.mkdir(path8.dirname(helpersPath), { recursive: true });
-  await fs9.writeFile(helpersPath, generateHelpersFileSource(), "utf-8");
+  await atomicWriteFile(helpersPath, generateHelpersFileSource());
 }
 async function generateToolArtifacts(tools, rootDir, dist, options) {
   const metadata = [];
-  const programByFile = createPrograms(tools.map((m) => path8.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(tools.map((m) => path11.resolve(rootDir, m.filePath)));
   for (const manifest of tools) {
-    const absPath = path8.resolve(rootDir, manifest.filePath);
+    const absPath = path11.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractToolMetadata(program, absPath, manifest.functionName, {
       name: manifest.name,
@@ -2344,7 +2720,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
     }
   }
   const serialized = serializeTools(metadata, dist);
-  const toolsPath = path8.resolve(rootDir, dist, TOOLS_FILE);
+  const toolsPath = path11.resolve(rootDir, dist, TOOLS_FILE);
   await writeToolsModule(serialized, toolsPath);
   if (options?.skipSchema) {
     return metadata;
@@ -2352,7 +2728,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
   if (metadata.length === 0) {
     return metadata;
   }
-  const { sources, allTypesByFile } = collectToolSchemaSources(metadata, rootDir);
+  const { sources, resolversByFile } = collectToolSchemaSources(metadata, rootDir);
   if (sources.length === 0) {
     return metadata;
   }
@@ -2367,9 +2743,9 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
   }
   const fileEntries = [];
   for (const [filePath, fileSources] of sourcesByFile) {
-    const relFile = path8.relative(rootDir, filePath).replace(/\\/g, "/");
-    const outputPath = getToolSchemaOutputPath(relFile, dist, rootDir);
-    const allTypes = allTypesByFile.get(filePath) ?? /* @__PURE__ */ new Map();
+    const relFile = path11.relative(rootDir, filePath).replace(/\\/g, "/");
+    const outputPath = getSchemaOutputPath(relFile, dist, rootDir);
+    const resolver = resolversByFile.get(filePath);
     let relForDir = relFile;
     if (relForDir.startsWith("src/")) {
       relForDir = relForDir.slice(4);
@@ -2377,11 +2753,15 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
     const dirIdx = relForDir.lastIndexOf("/");
     const zodRelDir = dirIdx >= 0 ? relForDir.slice(0, dirIdx) : "";
     const helpersImportPath = getHelpersImportPath(zodRelDir);
-    const source = generateToolSchemaFileSource(fileSources, allTypes, helpersImportPath);
+    const source = generateToolSchemaFileSource(
+      fileSources,
+      (name) => resolver?.resolve(name)?.runtimeType,
+      helpersImportPath
+    );
     fileEntries.push({ outputPath, source });
   }
   const allSourceCode = fileEntries.map((e) => e.source).join("\n");
-  const distDir = path8.resolve(rootDir, dist);
+  const distDir = path11.resolve(rootDir, dist);
   await maybeGenerateHelpers(allSourceCode, distDir);
   await Promise.all(
     fileEntries.map(({ outputPath, source }) => writeToolSchemaFile(outputPath, source))
@@ -2389,8 +2769,7 @@ async function generateToolArtifacts(tools, rootDir, dist, options) {
   return metadata;
 }
 async function writeToolSchemaFile(outputPath, source) {
-  await fs9.mkdir(path8.dirname(outputPath), { recursive: true });
-  await fs9.writeFile(outputPath, source, "utf-8");
+  await atomicWriteFile(outputPath, source);
 }
 
 // src/loader/loadToolSchema.ts
@@ -2402,7 +2781,7 @@ function getDist() {
 }
 function getToolSchemaPath(tool, rootDir) {
   const dist = getDist();
-  return getRuntimeToolSchemaPath(tool.filePath, dist, rootDir ?? process.cwd());
+  return getRuntimeSchemaPath(tool.filePath, dist, rootDir ?? process.cwd());
 }
 async function loadToolSchema(tool, rootDir) {
   if (!tool.inputTypeName) return void 0;
@@ -2420,16 +2799,14 @@ async function loadToolSchema(tool, rootDir) {
 }
 
 // src/injection/agentHandle.ts
-var currentFactory = null;
 function registerAgentHandleFactory(factory) {
-  currentFactory = factory;
+  defaultRegistries.agentHandle.register(factory);
 }
 function getAgentHandle(ctx) {
-  if (currentFactory === null) return void 0;
-  return currentFactory(ctx);
+  return defaultRegistries.agentHandle.get(ctx);
 }
 function clearAgentHandleFactory() {
-  currentFactory = null;
+  defaultRegistries.agentHandle.clear();
 }
 
 // src/middleware/cors.ts
@@ -2457,11 +2834,6 @@ function cors(options = {}) {
     } 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) {
@@ -2472,6 +2844,11 @@ function cors(options = {}) {
         ctx.setHeader("Vary", "Origin");
       }
     }
+    if (!allowOrigin) {
+      await next();
+      return;
+    }
+    ctx.setHeader("Access-Control-Allow-Origin", allowOrigin);
     ctx.setHeader("Access-Control-Allow-Methods", methods.join(", "));
     if (allowedHeaders) {
       ctx.setHeader("Access-Control-Allow-Headers", allowedHeaders.join(", "));
@@ -2593,16 +2970,16 @@ function helmet(options = {}) {
 }
 
 // src/config/loadConfig.ts
-import path9 from "path";
-import fs10 from "fs";
+import path12 from "path";
+import fs11 from "fs";
 var CONFIG_PRODUCT_FILE = "faapi-config.js";
 async function loadConfig(rootDir, dist) {
-  const configProductPath = path9.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
-  if (fs10.existsSync(configProductPath)) {
+  const configProductPath = path12.resolve(rootDir, dist, CONFIG_PRODUCT_FILE);
+  if (fs11.existsSync(configProductPath)) {
     const module = await importWithCacheBust(configProductPath);
     return module.default ?? {};
   }
-  const hasSourceConfig = fs10.existsSync(path9.join(rootDir, "faapi.config.ts")) || fs10.existsSync(path9.join(rootDir, "faapi.config.js"));
+  const hasSourceConfig = fs11.existsSync(path12.join(rootDir, "faapi.config.ts")) || fs11.existsSync(path12.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`
@@ -2612,8 +2989,8 @@ async function loadConfig(rootDir, dist) {
 }
 
 // src/cli/loadEnv.ts
-import fs11 from "fs";
-import path10 from "path";
+import fs12 from "fs";
+import path13 from "path";
 function resolveEnv() {
   return process.env.NODE_ENV || "development";
 }
@@ -2628,7 +3005,8 @@ function parseEnvFile(content, fileVars) {
     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 key = match[1];
+    const rawValue = match[2];
     const value = parseValue(rawValue, { ...fileVars, ...result });
     result[key] = value;
   }
@@ -2679,9 +3057,9 @@ function loadEnv(rootDir) {
   const files = getEnvFiles(env);
   const merged = {};
   for (const file of files) {
-    const filePath = path10.join(rootDir, file);
-    if (!fs11.existsSync(filePath)) continue;
-    const content = fs11.readFileSync(filePath, "utf-8");
+    const filePath = path13.join(rootDir, file);
+    if (!fs12.existsSync(filePath)) continue;
+    const content = fs12.readFileSync(filePath, "utf-8");
     const parsed = parseEnvFile(content, merged);
     Object.assign(merged, parsed);
   }
@@ -2718,14 +3096,14 @@ var ValidationError = class extends FaapiError {
   issues;
 };
 var RouteNotFoundError = class extends FaapiError {
-  constructor(path19) {
-    super("ROUTE_NOT_FOUND", `Route not found: ${path19}`, 404);
+  constructor(path23) {
+    super("ROUTE_NOT_FOUND", `Route not found: ${path23}`, 404);
     this.name = "RouteNotFoundError";
   }
 };
 var MethodNotAllowedError = class extends FaapiError {
-  constructor(method, path19, allowedMethods) {
-    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path19}`, 405);
+  constructor(method, path23, allowedMethods) {
+    super("METHOD_NOT_ALLOWED", `Method ${method} not allowed for ${path23}`, 405);
     this.allowedMethods = allowedMethods;
     this.name = "MethodNotAllowedError";
   }
@@ -2752,7 +3130,7 @@ var PayloadTooLargeError = class extends FaapiError {
 
 // src/cli/createAppCore.ts
 import fs15 from "fs";
-import path15 from "path";
+import path19 from "path";
 import { PassThrough, Readable as Readable3 } from "stream";
 
 // src/router/sortRoutes.ts
@@ -2805,7 +3183,7 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable2 } from "stream";
-import path12 from "path";
+import path15 from "path";
 
 // src/router/matchRoute.ts
 var httpIndexCache = /* @__PURE__ */ new WeakMap();
@@ -2816,7 +3194,10 @@ function getHttpIndex(routes) {
   index = { static: /* @__PURE__ */ new Map(), methodsByStaticPath: /* @__PURE__ */ new Map(), dynamics: [] };
   for (const route of routes) {
     if (route.isDynamic) {
-      index.dynamics.push(route);
+      index.dynamics.push({
+        route,
+        segments: route.urlPath.split("/").filter(Boolean)
+      });
     } else {
       index.static.set(`${route.method}|${route.urlPath}`, route);
       let methods = index.methodsByStaticPath.get(route.urlPath);
@@ -2844,57 +3225,77 @@ function getWsIndex(routes) {
   wsIndexCache.set(routes, index);
   return index;
 }
-function matchRoute(routes, method, path19) {
+function matchRoute(routes, method, path23) {
   const index = getHttpIndex(routes);
-  const staticHit = index.static.get(`${method}|${path19}`);
+  const upper = method.toUpperCase();
+  const hit = matchByMethod(index, upper, path23);
+  if (hit) return hit;
+  if (upper === "HEAD") {
+    return matchByMethod(index, "GET", path23);
+  }
+  return null;
+}
+function matchByMethod(index, method, path23) {
+  const staticHit = index.static.get(`${method}|${path23}`);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
-  for (const route of index.dynamics) {
+  for (const entry of index.dynamics) {
+    const route = entry.route;
     if (route.method !== method) {
       continue;
     }
-    const params = matchDynamicPath(route.urlPath, path19, route.paramNames, route.isCatchAll);
+    const params = matchSegments(entry.segments, path23, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function matchWsRoute(wsRoutes, path19) {
+function matchWsRoute(wsRoutes, path23) {
   const index = getWsIndex(wsRoutes);
-  const staticHit = index.static.get(path19);
+  const staticHit = index.static.get(path23);
   if (staticHit) {
     return { route: staticHit, params: {} };
   }
   for (const route of index.dynamics) {
-    const params = matchDynamicPath(route.urlPath, path19, route.paramNames, route.isCatchAll);
+    const params = matchDynamicPath(route.urlPath, path23, route.paramNames, route.isCatchAll);
     if (params !== null) {
       return { route, params };
     }
   }
   return null;
 }
-function findAllowedMethods(routes, path19) {
+function findAllowedMethods(routes, path23) {
   const index = getHttpIndex(routes);
   const methods = /* @__PURE__ */ new Set();
-  const staticMethods = index.methodsByStaticPath.get(path19);
+  const staticMethods = index.methodsByStaticPath.get(path23);
   if (staticMethods) {
     for (const method of staticMethods) {
       methods.add(method);
     }
   }
-  for (const route of index.dynamics) {
-    const params = matchDynamicPath(route.urlPath, path19, route.paramNames, route.isCatchAll);
+  for (const entry of index.dynamics) {
+    const params = matchSegments(
+      entry.segments,
+      path23,
+      entry.route.paramNames,
+      entry.route.isCatchAll
+    );
     if (params !== null) {
-      methods.add(route.method);
+      methods.add(entry.route.method);
     }
   }
+  if (methods.has("GET")) {
+    methods.add("HEAD");
+  }
   return Array.from(methods);
 }
-function matchDynamicPath(pattern, path19, paramNames, isCatchAll) {
-  const patternSegments = pattern.split("/").filter(Boolean);
-  const pathSegments = path19.split("/").filter(Boolean);
+function matchDynamicPath(pattern, path23, paramNames, isCatchAll) {
+  return matchSegments(pattern.split("/").filter(Boolean), path23, paramNames, isCatchAll);
+}
+function matchSegments(patternSegments, path23, paramNames, isCatchAll) {
+  const pathSegments = path23.split("/").filter(Boolean);
   if (isCatchAll) {
     const nonCatchAllCount = patternSegments.length - 1;
     if (pathSegments.length <= nonCatchAllCount) {
@@ -3133,10 +3534,14 @@ function formatErrorResponse(error, config) {
       code: error.code,
       message: error.message
     });
-    const bodyObj = typeof body2 === "object" && body2 !== null ? body2 : { error: body2 };
-    const errorObj = bodyObj.error ?? bodyObj;
-    if (errorObj) {
-      errorObj.issues = error.issues;
+    const bodyObj = typeof body2 === "object" && body2 !== null ? { ...body2 } : { error: body2 };
+    const existingError = bodyObj.error;
+    if (existingError && typeof existingError === "object") {
+      bodyObj.error = { ...existingError, issues: error.issues };
+    } else if (typeof body2 === "object" && body2 !== null) {
+      bodyObj.issues = error.issues;
+    } else {
+      bodyObj.error = { issues: error.issues };
     }
     return jsonOk(bodyObj, error.statusCode);
   }
@@ -3193,10 +3598,10 @@ function formatSetCookie(name, value, options) {
   if (options?.sameSite) cookie += `; SameSite=${options.sameSite}`;
   return cookie;
 }
-function createContext(request, params, config = {}, ip = "") {
-  return createContextFromUrl(request, new URL(request.url), params, config, ip);
+function createContext(request, params, config = {}, ip = "", registries) {
+  return createContextFromUrl(request, new URL(request.url), params, config, ip, registries);
 }
-function createContextFromUrl(request, url, params, config = {}, ip = "") {
+function createContextFromUrl(request, url, params, config = {}, ip = "", registries) {
   const meta = { headers: {}, setCookies: [] };
   const parsedCookies = parseCookies(request.headers.get("cookie") ?? "");
   const cookiesObj = {};
@@ -3293,6 +3698,9 @@ function createContextFromUrl(request, url, params, config = {}, ip = "") {
       return formatFailResponse(options, config);
     }
   };
+  if (registries) {
+    ctx.registries = registries;
+  }
   const extend = config?.extendContext;
   if (typeof extend === "function") {
     extend(ctx);
@@ -3304,7 +3712,14 @@ function createContextFromUrl(request, url, params, config = {}, ip = "") {
 function queryToObject(params) {
   const result = {};
   for (const [key, value] of params) {
-    result[key] = value;
+    const existing = result[key];
+    if (existing === void 0) {
+      result[key] = value;
+    } else if (Array.isArray(existing)) {
+      existing.push(value);
+    } else {
+      result[key] = [existing, value];
+    }
   }
   return result;
 }
@@ -3360,7 +3775,7 @@ async function resolveInputFromUrl(method, request, url) {
     }
     if (contentType.includes("application/x-www-form-urlencoded")) {
       const text2 = await request.text();
-      if (text2.trim() === "") return null;
+      if (isBlankText(text2)) return null;
       const params = new URLSearchParams(text2);
       const obj = {};
       for (const [key, value] of params) {
@@ -3369,7 +3784,7 @@ async function resolveInputFromUrl(method, request, url) {
       return obj;
     }
     const text = await request.text();
-    if (text.trim() === "") {
+    if (isBlankText(text)) {
       return null;
     }
     const result = parseJsonBody(text);
@@ -3388,6 +3803,26 @@ async function resolveInputFromUrl(method, request, url) {
   }
   return queryToObject(url.searchParams);
 }
+function isBlankText(text) {
+  return text.length === 0 || !/\S/.test(text);
+}
+async function resolveBodyForQueryMethod(request) {
+  const text = await request.text();
+  if (isBlankText(text)) return void 0;
+  const result = parseJsonBody(text);
+  if (!result.success) {
+    throw new ValidationError("\u8BF7\u6C42\u4F53\u4E0D\u662F\u5408\u6CD5\u7684 JSON", [
+      {
+        path: "body",
+        code: "INVALID_FORMAT",
+        expected: "JSON",
+        received: "text",
+        message: "\u8BF7\u6C42\u4F53\u4E0D\u662F\u5408\u6CD5\u7684 JSON"
+      }
+    ]);
+  }
+  return result.data;
+}
 
 // src/utils/isPlainObject.ts
 function isPlainObject(value) {
@@ -3401,6 +3836,25 @@ function isPlainObject(value) {
   return proto === null || proto === Object.prototype;
 }
 
+// src/response/pendingMeta.ts
+var pending = /* @__PURE__ */ new WeakMap();
+function deferMetaHeaders(response, headers) {
+  const existing = pending.get(response);
+  if (existing) {
+    Object.assign(existing, headers);
+    return;
+  }
+  pending.set(response, { ...headers });
+}
+function consumePendingMetaHeaders(response) {
+  const headers = pending.get(response);
+  if (headers) pending.delete(response);
+  return headers;
+}
+function isHeadersOnlyMeta(meta) {
+  return meta.status === void 0 && meta.setCookies.length === 0;
+}
+
 // src/response/toResponse.ts
 async function toResponse(value, meta) {
   if (value instanceof Promise) {
@@ -3417,6 +3871,10 @@ async function toResponse(value, meta) {
   };
   if (value instanceof Response) {
     if (meta && (meta.status !== void 0 || Object.keys(meta.headers).length > 0 || meta.setCookies.length > 0)) {
+      if (isHeadersOnlyMeta(meta)) {
+        deferMetaHeaders(value, meta.headers);
+        return value;
+      }
       const headers2 = new Headers(value.headers);
       applyMeta(headers2);
       return new Response(value.body, {
@@ -3525,11 +3983,12 @@ function getBuiltinInjectionValue(type, ctx, body) {
       }
       return {};
     // Phase 2.3：注入所有已注册 agent 元数据列表
+    // 方案 A：优先读 app 实例注册表，无实例（编程式直调 ctx）回退默认全局实例
     case "agents":
-      return listAgents();
+      return ctx.registries ? ctx.registries.agent.listAgents() : listAgents();
     // Phase 3.5：调 @faapi/agent 插件注册的工厂获取 AgentHandle
     case "agent":
-      return getAgentHandle(ctx);
+      return ctx.registries ? ctx.registries.agentHandle.get(ctx) : getAgentHandle(ctx);
     default:
       return void 0;
   }
@@ -3560,6 +4019,10 @@ function wrapResult(result, ctx) {
 function mergeMeta(response, meta) {
   const hasMeta = meta.status !== void 0 || Object.keys(meta.headers).length > 0 || meta.setCookies.length > 0;
   if (!hasMeta) return response;
+  if (isHeadersOnlyMeta(meta)) {
+    deferMetaHeaders(response, meta.headers);
+    return response;
+  }
   const headers = new Headers(response.headers);
   for (const [key, value] of Object.entries(meta.headers)) {
     headers.set(key, value);
@@ -3652,11 +4115,24 @@ async function sendNodeResponse(response, res) {
       res.setHeader(key, value);
     }
   }
+  const deferred = consumePendingMetaHeaders(response);
+  if (deferred) {
+    for (const [key, value] of Object.entries(deferred)) {
+      res.setHeader(key, value);
+    }
+  }
   if (response.body) {
     const nodeStream = Readable.fromWeb(response.body);
     await new Promise((resolve, reject) => {
       nodeStream.on("error", reject);
-      res.on("error", reject);
+      const abort = () => {
+        nodeStream.destroy();
+        resolve();
+      };
+      res.on("error", abort);
+      res.on("close", () => {
+        if (!res.writableEnded) abort();
+      });
       res.on("finish", resolve);
       nodeStream.pipe(res);
     });
@@ -3691,28 +4167,25 @@ async function validateInput(schemaPath, method, inputType, input) {
   }
   const schema = mod[schemaKey];
   if (schema === void 0 || schema === null) {
-    const data = typeof input === "object" && input !== null && !Array.isArray(input) ? input : {};
-    return { valid: true, issues: [], data };
+    return { valid: true, issues: [], data: input };
   }
   if (typeof schema !== "object" || typeof schema.safeParse !== "function") {
     throw new InternalError(`Schema \u4E0D\u662F\u6709\u6548\u7684 zod schema: ${schemaPath}#${schemaName}`);
   }
-  const inputObj = typeof input === "object" && input !== null && !Array.isArray(input) ? input : {};
   const zodSchema = schema;
-  const result = zodSchema.safeParse(inputObj);
+  const result = zodSchema.safeParse(input);
   if (result.success) {
-    const data = typeof result.data === "object" && result.data !== null && !Array.isArray(result.data) ? result.data : {};
-    return { valid: true, issues: [], data };
+    return { valid: true, issues: [], data: result.data };
   }
   const issues = mapZodIssues(result.error);
-  return { valid: false, issues, data: inputObj };
+  return { valid: false, issues, data: input };
 }
 function mapZodIssues(error) {
   return error.issues.map((issue) => {
-    const code = mapZodCode(issue.code, issue.message);
-    const path19 = issue.path.map(String).join(".") || "";
+    const code = mapZodCode(issue);
+    const path23 = issue.path.map(String).join(".") || "";
     return {
-      path: path19,
+      path: path23,
       code,
       expected: issue.expected ?? mapExpectedFromMessage(issue.message),
       received: issue.received ?? mapReceivedFromMessage(issue.message),
@@ -3720,27 +4193,29 @@ function mapZodIssues(error) {
     };
   });
 }
-function mapZodCode(zodCode, message) {
-  switch (zodCode) {
+function mapZodCode(issue) {
+  switch (issue.code) {
     case "invalid_type":
+      if (issue.received === "undefined" || /received undefined/i.test(issue.message)) {
+        return "MISSING_FIELD";
+      }
+      return "TYPE_MISMATCH";
     case "invalid_union":
     case "invalid_union_discriminator":
       return "TYPE_MISMATCH";
     case "unrecognized_keys":
       return "INVALID_FORMAT";
     case "invalid_value":
-    case "invalid_string":
+    case "invalid_format":
+    case "invalid_key":
+    case "invalid_element":
     case "too_small":
     case "too_big":
     case "invalid_intersection_types":
     case "not_multiple_of":
-      return "INVALID_VALUE";
     case "custom":
       return "INVALID_VALUE";
     default:
-      if (message.includes("Required") || message.includes("required")) {
-        return "MISSING_FIELD";
-      }
       return "INVALID_VALUE";
   }
 }
@@ -3775,10 +4250,176 @@ function getClientIp(req, trustedProxy = false) {
   return "";
 }
 
+// src/middleware/compression.ts
+import zlib from "zlib";
+import { promisify } from "util";
+var gzipAsync = promisify(zlib.gzip);
+var deflateAsync = promisify(zlib.deflate);
+var brotliAsync = promisify(zlib.brotliCompress);
+var DEFAULT_THRESHOLD = 1024;
+var COMPRESSIBLE_CHECKS = [
+  (ct) => ct === "application/json",
+  (ct) => ct === "application/javascript",
+  (ct) => ct === "image/svg+xml",
+  (ct) => ct.startsWith("text/") && ct !== "text/event-stream"
+];
+function isCompressible(contentType) {
+  const ct = contentType.split(";")[0].trim().toLowerCase();
+  if (ct === "") return false;
+  return COMPRESSIBLE_CHECKS.some((check) => check(ct));
+}
+function parseAcceptEncoding(header) {
+  return header.split(",").map((part) => part.trim()).filter((part) => part !== "").map((part) => {
+    const [encoding, ...params] = part.split(";");
+    let quality = 1;
+    for (const param of params) {
+      const trimmed = param.trim();
+      if (trimmed.startsWith("q=")) {
+        const q = Number(trimmed.slice(2));
+        if (Number.isFinite(q)) quality = q;
+      }
+    }
+    return { encoding: (encoding ?? "").trim().toLowerCase(), quality };
+  }).filter((e) => e.encoding !== "" && e.quality > 0);
+}
+function selectEncoding(accepted) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const { encoding, quality } of accepted) {
+    byName.set(encoding, Math.max(byName.get(encoding) ?? 0, quality));
+  }
+  for (const [encoding, quality] of byName) {
+    if (quality === 0) byName.delete(encoding);
+  }
+  for (const candidate of ["br", "gzip", "deflate"]) {
+    if ((byName.get(candidate) ?? 0) > 0) return candidate;
+  }
+  if ((byName.get("*") ?? 0) > 0) return "gzip";
+  return null;
+}
+async function compressBody(encoding, body) {
+  const buf = Buffer.from(body, "utf-8");
+  switch (encoding) {
+    case "br":
+      return brotliAsync(buf);
+    case "gzip":
+      return gzipAsync(buf);
+    case "deflate":
+      return deflateAsync(buf);
+  }
+}
+function mergeVary(meta, value) {
+  const existing = meta.headers["Vary"] ?? meta.headers["vary"];
+  if (!existing) {
+    meta.headers["Vary"] = value;
+    return;
+  }
+  if (!existing.toLowerCase().includes(value.toLowerCase())) {
+    const key = meta.headers["Vary"] !== void 0 ? "Vary" : "vary";
+    meta.headers[key] = `${existing}, ${value}`;
+  }
+}
+function compression(options = {}) {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  return async (ctx, next) => {
+    const meta = ctx.meta;
+    const response = await next();
+    if (!response) return response;
+    mergeVary(meta, "Accept-Encoding");
+    const acceptEncoding = ctx.request.headers.get("accept-encoding") ?? "";
+    const encoding = selectEncoding(parseAcceptEncoding(acceptEncoding));
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!encoding || !isCompressible(contentType) || response.headers.has("content-encoding") || (response.headers.get("cache-control") ?? "").includes("no-transform") || response.status === 204 || response.status === 304 || response.body === null) {
+      return response;
+    }
+    const deferredHeaders = consumePendingMetaHeaders(response);
+    const bodyText = await response.text();
+    if (bodyText.length < threshold) {
+      const headers2 = new Headers(response.headers);
+      for (const [key, value] of Object.entries(deferredHeaders ?? {})) {
+        headers2.set(key, value);
+      }
+      return new Response(bodyText, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: headers2
+      });
+    }
+    const compressed = await compressBody(encoding, bodyText);
+    const headers = new Headers(response.headers);
+    for (const [key, value] of Object.entries(deferredHeaders ?? {})) {
+      headers.set(key, value);
+    }
+    headers.set("Content-Encoding", encoding);
+    headers.delete("Content-Length");
+    return new Response(compressed, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  };
+}
+
+// src/middleware/etag.ts
+import { createHash } from "crypto";
+var DEFAULTS2 = { weak: true };
+function computeEtag(body, weak) {
+  const hash = createHash("sha1").update(body).digest("base64");
+  return weak ? `W/"${hash}"` : `"${hash}"`;
+}
+function ifNoneMatchMatches(ifNoneMatch, etag2, weak) {
+  const normalize = (tag) => tag.trim().replace(/^W\//i, "");
+  if (weak) {
+    const target = normalize(etag2);
+    return ifNoneMatch.split(",").some((tag) => {
+      const trimmed = tag.trim();
+      return trimmed === "*" || normalize(trimmed) === target;
+    });
+  }
+  return ifNoneMatch.split(",").some((tag) => tag.trim() === etag2 || tag.trim() === "*");
+}
+function etag(options = {}) {
+  const opts = { ...DEFAULTS2, ...options };
+  return async (ctx, next) => {
+    const meta = ctx.meta;
+    const response = await next();
+    if (!response) return response;
+    const method = ctx.request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD") return response;
+    if (response.status < 200 || response.status >= 300) return response;
+    if (meta.headers["etag"] !== void 0 || response.headers.has("etag")) {
+      return response;
+    }
+    if (response.body === null || (response.headers.get("content-type") ?? "").includes("text/event-stream")) {
+      return response;
+    }
+    const bodyText = await response.text();
+    const etagValue = computeEtag(bodyText, opts.weak);
+    const ifNoneMatch = ctx.request.headers.get("if-none-match");
+    if (ifNoneMatch && ifNoneMatchMatches(ifNoneMatch, etagValue, opts.weak)) {
+      return new Response(null, {
+        status: 304,
+        statusText: response.statusText,
+        headers: { ETag: etagValue }
+      });
+    }
+    meta.headers["etag"] = etagValue;
+    const headers = new Headers(response.headers);
+    const deferredHeaders = consumePendingMetaHeaders(response);
+    for (const [key, value] of Object.entries(deferredHeaders ?? {})) {
+      headers.set(key, value);
+    }
+    return new Response(bodyText, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  };
+}
+
 // src/server/handleWsUpgrade.ts
-import fs12 from "fs";
+import fs13 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
-import path11 from "path";
+import path14 from "path";
 
 // src/server/serverUtils.ts
 function nodeHttpToWebHeaders(req) {
@@ -3809,8 +4450,10 @@ function buildErrorResponse(err, config) {
 
 // src/middleware/loadMiddlewares.ts
 var middlewareCache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
 function invalidateMiddlewareCache() {
   middlewareCache.clear();
+  inFlight.clear();
 }
 function getCachedMiddlewares(absPath) {
   return middlewareCache.get(absPath);
@@ -3863,8 +4506,15 @@ async function loadMergedMiddlewares(middlewarePaths) {
   for (const absMwPath of middlewarePaths) {
     let bundle = getCachedMiddlewares(absMwPath);
     if (bundle === void 0) {
-      bundle = await loadMiddlewaresFile(absMwPath);
-      setCachedMiddlewares(absMwPath, bundle);
+      let loading = inFlight.get(absMwPath);
+      if (!loading) {
+        loading = loadMiddlewaresFile(absMwPath).then((result) => {
+          setCachedMiddlewares(absMwPath, result);
+          return result;
+        });
+        inFlight.set(absMwPath, loading);
+      }
+      bundle = await loading;
     }
     mergedMiddlewares.push(...bundle.middlewares);
     for (const [name, injector] of Object.entries(bundle.injectors)) {
@@ -3904,7 +4554,7 @@ async function loadWsHandler(filePath, ctx, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs12.existsSync(sourcePath)) {
+      if (sourcePath && fs13.existsSync(sourcePath)) {
         await ensureCompiled(sourcePath, rootDir, dist);
       }
     }
@@ -3927,9 +4577,9 @@ function bindEvents(rawSocket, handlers) {
     }
   }
   if (handlers.onMessage) {
-    rawSocket.on("message", (data) => {
-      const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
-      handlers.onMessage(ws, buf.toString("utf8"));
+    rawSocket.on("message", (data, isBinary) => {
+      const buf = toWsBuffer(data);
+      handlers.onMessage(ws, isBinary ? buf : buf.toString("utf8"));
     });
   }
   if (handlers.onClose) {
@@ -3943,12 +4593,22 @@ function bindEvents(rawSocket, handlers) {
     });
   }
 }
+function toWsBuffer(data) {
+  if (Buffer.isBuffer(data)) return data;
+  if (Array.isArray(data)) return Buffer.concat(data);
+  return Buffer.from(data);
+}
 async function sendResponseToSocket(socket, response) {
   const body = await response.text().catch(() => "");
   const statusLine = `HTTP/1.1 ${response.status} ${response.statusText || ""}\r
 `;
   const headerLines = [];
   let hasContentLength = false;
+  const deferredHeaders = consumePendingMetaHeaders(response);
+  for (const [key, value] of Object.entries(deferredHeaders ?? {})) {
+    if (key.toLowerCase() === "content-length") hasContentLength = true;
+    headerLines.push(`${key}: ${value}`);
+  }
   for (const [key, value] of response.headers) {
     if (key.toLowerCase() === "content-length") {
       hasContentLength = true;
@@ -3962,9 +4622,33 @@ async function sendResponseToSocket(socket, response) {
   socket.destroy();
 }
 function attachWebSocket(options) {
-  const { server, routesRef, rootDir, config, globalMiddlewares, trustedProxy = false } = options;
+  const {
+    server,
+    routesRef,
+    rootDir,
+    config,
+    globalMiddlewares,
+    trustedProxy = false,
+    registries
+  } = options;
   const wss = new WebSocketServer({ noServer: true });
   server.on("upgrade", async (req, socket, head) => {
+    try {
+      await handleUpgradeRequest(req, socket, head);
+    } catch (err) {
+      console.error("[faapi] WS upgrade \u5904\u7406\u5931\u8D25:", err);
+      if (!socket.destroyed) {
+        try {
+          if (!socket.writableEnded) {
+            socket.write("HTTP/1.1 500 Internal Server Error\r\n\r\n");
+          }
+        } catch {
+        }
+        socket.destroy();
+      }
+    }
+  });
+  async function handleUpgradeRequest(req, socket, head) {
     const currentWsRoutes = routesRef.wsCurrent;
     const pathname = getPathname(req);
     const match = matchWsRoute(currentWsRoutes, pathname);
@@ -3978,13 +4662,13 @@ function attachWebSocket(options) {
     const host = req.headers.host ?? "localhost";
     const url = `http://${host}${req.url ?? "/"}`;
     const request = new Request(url, { method: "GET", headers });
-    const ctx = createContext(request, params, config, getClientIp(req, trustedProxy));
+    const ctx = createContext(request, params, config, getClientIp(req, trustedProxy), registries);
     const meta = ctx.meta;
     let upgraded = false;
     const finalHandler = async () => {
       let handlers;
       try {
-        const absoluteFilePath = path11.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path14.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -4008,6 +4692,7 @@ function attachWebSocket(options) {
     let response;
     try {
       if (route.middlewares === void 0 && route.middlewarePaths) {
+        await ensureMiddlewaresCompiled(route.middlewarePaths, rootDir);
         const bundle = await loadMergedMiddlewares(route.middlewarePaths);
         if (bundle) {
           route.middlewares = bundle.middlewares;
@@ -4033,14 +4718,14 @@ function attachWebSocket(options) {
       return;
     }
     await sendResponseToSocket(socket, mergeMeta(response, meta));
-  });
+  }
   return wss;
 }
 
 // src/server/createServer.ts
 init_generateSchemaFiles();
 var DEFAULT_BODY_LIMIT = 10 * 1024 * 1024;
-function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT) {
+function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT, requestSignal) {
   const forwardedProto = req.headers["x-forwarded-proto"];
   const protocol = Array.isArray(forwardedProto) ? forwardedProto[0]?.split(",")[0]?.trim() ?? "http" : forwardedProto?.split(",")[0]?.trim() ?? "http";
   const host = req.headers.host ?? "localhost";
@@ -4048,7 +4733,10 @@ function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT) {
   const headers = nodeHttpToWebHeaders(req);
   const method = req.method ?? "GET";
   if (method === "GET" || method === "HEAD") {
-    return { request: new Request(url.toString(), { method, headers }), url };
+    return {
+      request: new Request(url.toString(), { method, headers, signal: requestSignal }),
+      url
+    };
   }
   const contentLength = req.headers["content-length"];
   if (contentLength !== void 0) {
@@ -4064,7 +4752,8 @@ function toWebRequest(req, bodyLimit = DEFAULT_BODY_LIMIT) {
       method,
       headers,
       body: limitedStream,
-      duplex: "half"
+      duplex: "half",
+      signal: requestSignal
     }),
     url
   };
@@ -4131,6 +4820,9 @@ function createServer(options) {
     middlewares: globalMiddlewares,
     injectors: globalInjectors,
     helmet: helmetOption,
+    compression: compressionOption,
+    etag: etagOption,
+    registries,
     logger: loggerOption,
     bodyLimit = DEFAULT_BODY_LIMIT,
     http2: http2Option,
@@ -4138,6 +4830,10 @@ function createServer(options) {
   } = options;
   const routesRef = { current: routes, wsCurrent: wsRoutes ?? [] };
   const configMiddlewares = [];
+  if (compressionOption) {
+    const compOpts = typeof compressionOption === "object" ? compressionOption : {};
+    configMiddlewares.push(compression(compOpts));
+  }
   const corsMiddleware = corsOption === false ? null : corsOption === true || corsOption === void 0 ? cors() : cors(corsOption);
   if (corsMiddleware) configMiddlewares.push(corsMiddleware);
   if (helmetOption) {
@@ -4146,6 +4842,10 @@ function createServer(options) {
   }
   const loggerMiddlewareInst = loggerOption === false ? null : loggerOption === true || loggerOption === void 0 ? logger() : logger(loggerOption);
   if (loggerMiddlewareInst) configMiddlewares.push(loggerMiddlewareInst);
+  if (etagOption) {
+    const etagOpts = typeof etagOption === "object" ? etagOption : {};
+    configMiddlewares.push(etag(etagOpts));
+  }
   const outerMiddlewares = [...configMiddlewares];
   if (globalMiddlewares && globalMiddlewares.length > 0) {
     outerMiddlewares.push(...globalMiddlewares);
@@ -4174,22 +4874,36 @@ function createServer(options) {
       config,
       globalInjectors,
       bodyLimit,
-      trustedProxy
+      trustedProxy,
+      registries
     ).catch(() => {
       res.statusCode = 500;
       res.end();
     });
   });
-  if (routesRef.wsCurrent.length > 0) {
-    attachWebSocket({ server, routesRef, rootDir, config, globalMiddlewares, trustedProxy });
-  }
+  attachWebSocket({
+    server,
+    routesRef,
+    rootDir,
+    config,
+    globalMiddlewares,
+    trustedProxy,
+    registries
+  });
   return { server, routesRef };
 }
-function prepareRequest(req, config, bodyLimit, trustedProxy) {
-  const { request, url } = toWebRequest(req, bodyLimit);
+function prepareRequest(req, config, bodyLimit, trustedProxy, registries, requestSignal) {
+  const { request, url } = toWebRequest(req, bodyLimit, requestSignal);
   const method = request.method.toUpperCase();
   const urlPath = url.pathname;
-  const ctx = createContextFromUrl(request, url, {}, config, getClientIp(req, trustedProxy));
+  const ctx = createContextFromUrl(
+    request,
+    url,
+    {},
+    config,
+    getClientIp(req, trustedProxy),
+    registries
+  );
   const meta = ctx.meta;
   return { request, url, ctx, meta, method, urlPath };
 }
@@ -4202,17 +4916,28 @@ function resolveRouteOrThrow(routes, method, urlPath) {
   }
   throw new RouteNotFoundError(urlPath);
 }
+var routePathCache = /* @__PURE__ */ new WeakMap();
+function getRoutePaths(route, rootDir, dist) {
+  let cached = routePathCache.get(route);
+  if (!cached) {
+    cached = {
+      absFilePath: path15.resolve(rootDir, route.filePath),
+      schemaPath: getRuntimeSchemaPath(route.filePath, dist, rootDir)
+    };
+    routePathCache.set(route, cached);
+  }
+  return cached;
+}
 function createRoutePipeline(opts) {
   const { routes, method, urlPath, url, ctx, request, rootDir, dist, globalInjectors } = opts;
   return async () => {
     const match = resolveRouteOrThrow(routes, method, urlPath);
     ctx.params = match.params;
     const { route } = match;
-    const absoluteFilePath = path12.resolve(rootDir, route.filePath);
-    const routeModule = await loadRouteModule(absoluteFilePath, route.method, rootDir);
+    const { absFilePath, schemaPath } = getRoutePaths(route, rootDir, dist);
+    const routeModule = await loadRouteModule(absFilePath, route.method, rootDir);
     const input = await resolveInputFromUrl(route.method, request, url);
     const inputType = getInputTypeForMethod(route.method);
-    const schemaPath = getRuntimeSchemaPath(route.filePath, dist, rootDir);
     if (isDevOnDemandEnabled()) {
       const devDist = getDevDist();
       if (devDist) {
@@ -4223,8 +4948,9 @@ function createRoutePipeline(opts) {
     if (!result.valid) {
       throw new ValidationError("\u53C2\u6570\u6821\u9A8C\u5931\u8D25", result.issues);
     }
-    const body = hasBody(route.method) ? result.data : void 0;
+    const body = inputType === "query" && hasBody(route.method) ? await resolveBodyForQueryMethod(request) : hasBody(route.method) ? result.data : void 0;
     if (route.middlewares === void 0 && route.injectors === void 0 && route.middlewarePaths) {
+      await ensureMiddlewaresCompiled(route.middlewarePaths, rootDir);
       const bundle = await loadMergedMiddlewares(route.middlewarePaths);
       if (bundle) {
         route.middlewares = bundle.middlewares;
@@ -4250,11 +4976,22 @@ async function sendErrorResponse(err, meta, res, onError, ctx) {
     }
   }
 }
-async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares, onError, config, globalInjectors, bodyLimit, trustedProxy) {
+async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares, onError, config, globalInjectors, bodyLimit, trustedProxy, registries) {
   let meta = { headers: {}, setCookies: [] };
   let ctx;
+  const abortController = new AbortController();
+  res.on("close", () => {
+    if (!res.writableEnded) abortController.abort();
+  });
   try {
-    const prepared = prepareRequest(req, config, bodyLimit, trustedProxy);
+    const prepared = prepareRequest(
+      req,
+      config,
+      bodyLimit,
+      trustedProxy,
+      registries,
+      abortController.signal
+    );
     ctx = prepared.ctx;
     meta = prepared.meta;
     const { request, url, method, urlPath } = prepared;
@@ -4272,6 +5009,7 @@ async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares,
     const response = outerMiddlewares.length > 0 ? await compose(outerMiddlewares, ctx, routePipeline) : await routePipeline();
     await sendSuccessResponse(response, res);
   } catch (err) {
+    if (res.destroyed || res.writableEnded) return;
     await sendErrorResponse(err, meta, res, onError, ctx);
   }
 }
@@ -4305,8 +5043,8 @@ function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
 }
 
 // src/cli/generateRoutes.ts
-import fs13 from "fs";
-import path13 from "path";
+import fs14 from "fs";
+import path16 from "path";
 async function hydrateRoutes(manifest) {
   const hydrateRoute = (serialized) => ({
     method: serialized.method,
@@ -4331,11 +5069,10 @@ async function hydrateRoutes(manifest) {
 }
 
 // src/cli/generateAgentArtifacts.ts
-import path14 from "path";
-import fs14 from "fs/promises";
+import path17 from "path";
 
 // src/ast/extractAgentMetadata.ts
-import ts8 from "typescript";
+import ts9 from "typescript";
 function extractAgentMetadata(program, filePath, pathMeta) {
   const sourceFile = program.getSourceFile(filePath);
   if (!sourceFile) return null;
@@ -4351,9 +5088,9 @@ function extractAgentMetadata(program, filePath, pathMeta) {
       jsDocOwner = runNode;
     }
   }
-  const jsDoc = jsDocOwner ? getJSDocFromNode2(jsDocOwner) : void 0;
-  const description = extractDescription2(jsDoc);
-  const agentNameOverride = extractAgentTagValue(jsDoc);
+  const jsDoc = jsDocOwner ? getJSDocFromNode(jsDocOwner) : void 0;
+  const description = extractDescription(jsDoc);
+  const agentNameOverride = extractJSDocTagValue(jsDoc, "agent");
   let systemPrompt;
   let tools;
   let agents;
@@ -4381,22 +5118,22 @@ function extractAgentMetadata(program, filePath, pathMeta) {
 }
 function findConfigExport(sourceFile) {
   let result = null;
-  ts8.forEachChild(sourceFile, (node) => {
+  ts9.forEachChild(sourceFile, (node) => {
     if (result) return;
-    if (ts8.isVariableStatement(node) && hasExportModifier2(node)) {
+    if (ts9.isVariableStatement(node) && hasExportModifier(node)) {
       for (const decl of node.declarationList.declarations) {
         if (result) break;
-        const nameText = ts8.isIdentifier(decl.name) ? decl.name.text : "";
+        const nameText = ts9.isIdentifier(decl.name) ? decl.name.text : "";
         if (nameText !== "config" || !decl.initializer) continue;
-        if (ts8.isObjectLiteralExpression(decl.initializer)) {
+        if (ts9.isObjectLiteralExpression(decl.initializer)) {
           result = { jsDocOwner: node, objectLiteral: decl.initializer };
-        } else if (ts8.isArrowFunction(decl.initializer)) {
+        } else if (ts9.isArrowFunction(decl.initializer)) {
           const returnObj = getReturnObjectLiteral(decl.initializer);
           result = { jsDocOwner: node, objectLiteral: returnObj };
         }
       }
     }
-    if (ts8.isFunctionDeclaration(node) && hasExportModifier2(node) && node.name?.text === "config") {
+    if (ts9.isFunctionDeclaration(node) && hasExportModifier(node) && node.name?.text === "config") {
       const returnObj = getReturnObjectLiteral(node);
       result = { jsDocOwner: node, objectLiteral: returnObj };
     }
@@ -4405,18 +5142,18 @@ function findConfigExport(sourceFile) {
 }
 function findRunExport(sourceFile) {
   let result = null;
-  ts8.forEachChild(sourceFile, (node) => {
+  ts9.forEachChild(sourceFile, (node) => {
     if (result) return;
-    if (ts8.isFunctionDeclaration(node) && hasExportModifier2(node) && node.name?.text === "run") {
+    if (ts9.isFunctionDeclaration(node) && hasExportModifier(node) && node.name?.text === "run") {
       result = node;
       return;
     }
-    if (ts8.isVariableStatement(node) && hasExportModifier2(node)) {
+    if (ts9.isVariableStatement(node) && hasExportModifier(node)) {
       for (const decl of node.declarationList.declarations) {
         if (result) break;
-        const nameText = ts8.isIdentifier(decl.name) ? decl.name.text : "";
+        const nameText = ts9.isIdentifier(decl.name) ? decl.name.text : "";
         if (nameText !== "run" || !decl.initializer) continue;
-        if (ts8.isArrowFunction(decl.initializer) || ts8.isFunctionExpression(decl.initializer)) {
+        if (ts9.isArrowFunction(decl.initializer) || ts9.isFunctionExpression(decl.initializer)) {
           result = node;
         }
       }
@@ -4427,52 +5164,22 @@ function findRunExport(sourceFile) {
 function getReturnObjectLiteral(fn) {
   const body = fn.body;
   if (!body) return null;
-  if (ts8.isObjectLiteralExpression(body)) {
+  if (ts9.isObjectLiteralExpression(body)) {
     return body;
   }
-  if (ts8.isBlock(body)) {
+  if (ts9.isBlock(body)) {
     for (const stmt of body.statements) {
-      if (ts8.isReturnStatement(stmt) && stmt.expression && ts8.isObjectLiteralExpression(stmt.expression)) {
+      if (ts9.isReturnStatement(stmt) && stmt.expression && ts9.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;
+    if (!ts9.isPropertyAssignment(prop)) continue;
     const propName = getPropertyName(prop.name);
     if (!propName) continue;
     switch (propName) {
@@ -4496,26 +5203,26 @@ function extractConfigFields(objLit) {
   return result;
 }
 function getPropertyName(name) {
-  if (ts8.isIdentifier(name)) return name.text;
-  if (ts8.isStringLiteral(name)) return name.text;
+  if (ts9.isIdentifier(name)) return name.text;
+  if (ts9.isStringLiteral(name)) return name.text;
   return null;
 }
 function extractStringValue(expr) {
-  if (ts8.isStringLiteral(expr)) return expr.text;
+  if (ts9.isStringLiteral(expr)) return expr.text;
   return void 0;
 }
 function extractNumberValue(expr) {
-  if (ts8.isNumericLiteral(expr)) {
+  if (ts9.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;
+  if (!ts9.isArrayLiteralExpression(expr)) return void 0;
   const values = [];
   for (const element of expr.elements) {
-    if (!ts8.isStringLiteral(element)) return void 0;
+    if (!ts9.isStringLiteral(element)) return void 0;
     values.push(element.text);
   }
   return values;
@@ -4523,15 +5230,8 @@ function extractStringArrayValue(expr) {
 
 // src/cli/generateAgentArtifacts.ts
 init_createProgram();
+init_atomicWrite();
 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,
@@ -4542,16 +5242,14 @@ function serializeAgents(agents, dist = "dist") {
     agents: a.agents,
     model: a.model,
     maxTurns: a.maxTurns,
-    filePath: toProdFilePath2(a.filePath, dist)
+    filePath: toProdFilePath(a.filePath, dist)
   }));
 }
 async function writeAgentsModule(manifest, outputPath) {
-  const dir = path14.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");
+  await atomicWriteFile(outputPath, content);
 }
 function hydrateAgents(manifest) {
   return manifest.map((a) => ({
@@ -4568,9 +5266,9 @@ function hydrateAgents(manifest) {
 }
 async function generateAgentArtifacts(agents, rootDir, dist) {
   const metadata = [];
-  const programByFile = createPrograms(agents.map((m) => path14.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(agents.map((m) => path17.resolve(rootDir, m.filePath)));
   for (const manifest of agents) {
-    const absPath = path14.resolve(rootDir, manifest.filePath);
+    const absPath = path17.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractAgentMetadata(program, absPath, {
       name: manifest.name,
@@ -4582,17 +5280,20 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
     }
   }
   const serialized = serializeAgents(metadata, dist);
-  const agentsPath = path14.resolve(rootDir, dist, AGENTS_FILE);
+  const agentsPath = path17.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);
   return metadata;
 }
 
 // src/cli/loadPlugins.ts
-async function loadPlugins(declarations, ctx) {
+import path18 from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
+async function loadPlugins(declarations, ctx, rootDir) {
   const handlerWrappers = [];
   const upgradeWrappers = [];
+  const failures = [];
   if (!declarations || declarations.length === 0) {
-    return { handlerWrappers, upgradeWrappers };
+    return { handlerWrappers, upgradeWrappers, failures };
   }
   const fullCtx = {
     ...ctx,
@@ -4605,7 +5306,18 @@ async function loadPlugins(declarations, ctx) {
   };
   const loaded = /* @__PURE__ */ new Set();
   for (const decl of declarations) {
-    const { specifier, options, enable } = resolveDeclaration(decl);
+    let specifier;
+    let options;
+    let enable;
+    try {
+      ({ specifier, options, enable } = resolveDeclaration(decl));
+    } catch (err) {
+      failures.push({
+        specifier: JSON.stringify(decl),
+        reason: err instanceof Error ? err.message : String(err)
+      });
+      continue;
+    }
     if (enable === false) continue;
     if (loaded.has(specifier)) {
       console.warn(`! Plugin already loaded: ${specifier}, skipping`);
@@ -4613,21 +5325,38 @@ async function loadPlugins(declarations, ctx) {
     }
     loaded.add(specifier);
     try {
-      const mod = await import(specifier);
+      const mod = await import(resolveSpecifier(specifier, rootDir));
       const plugin = mod.default ?? mod;
       if (typeof plugin.setup !== "function") {
-        console.warn(`! Plugin ${specifier} has no setup function, skipping`);
+        failures.push({ specifier, reason: "plugin has no setup function" });
         continue;
       }
       await plugin.setup({ ...fullCtx, options });
       console.log(`- Plugin loaded: ${plugin.name ?? specifier}`);
     } catch (err) {
-      console.warn(
-        `! Failed to load plugin ${specifier}: ${err instanceof Error ? err.message : String(err)}`
-      );
+      failures.push({
+        specifier,
+        reason: err instanceof Error ? err.message : String(err)
+      });
     }
   }
-  return { handlerWrappers, upgradeWrappers };
+  if (failures.length > 0) {
+    console.error(
+      `[faapi] ${failures.length} plugin(s) failed to load:
+` + failures.map((f) => `  - ${f.specifier}: ${f.reason}`).join("\n")
+    );
+  }
+  return { handlerWrappers, upgradeWrappers, failures };
+}
+function resolveSpecifier(specifier, rootDir) {
+  if (specifier.startsWith("./") || specifier.startsWith("../")) {
+    const base = rootDir ?? process.cwd();
+    return pathToFileURL2(path18.resolve(base, specifier)).href;
+  }
+  if (path18.isAbsolute(specifier)) {
+    return pathToFileURL2(specifier).href;
+  }
+  return specifier;
 }
 function resolveDeclaration(decl) {
   if (typeof decl === "string") {
@@ -4652,25 +5381,24 @@ 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 = path15.resolve(rootDir, dist, TOOLS_FILE2);
+async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
+  const toolsPath = path19.resolve(rootDir, dist, TOOLS_FILE2);
   if (!fs15.existsSync(toolsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(toolsPath);
   const hydrated = hydrateTools(serialized.tools ?? []);
-  hydrateToolRegistry(hydrated);
+  registries.tool.hydrate(hydrated);
   return hydrated;
 }
-async function loadAndHydrateAgents(rootDir, dist) {
-  const agentsPath = path15.resolve(rootDir, dist, AGENTS_FILE2);
+async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
+  const agentsPath = path19.resolve(rootDir, dist, AGENTS_FILE2);
   if (!fs15.existsSync(agentsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(agentsPath);
   const hydrated = hydrateAgents(serialized.agents ?? []);
-  hydrateAgentRegistry(hydrated);
+  registries.agent.hydrate(hydrated);
   return hydrated;
 }
 var APP_INSTANCE_KEY = /* @__PURE__ */ Symbol.for("faapi.app.instance");
@@ -4684,6 +5412,23 @@ function setCurrentApp(app) {
     globalThis[APP_INSTANCE_KEY] = app;
   }
 }
+var SHUTDOWN_INSTALLED_KEY = /* @__PURE__ */ Symbol.for("faapi.defaultShutdownInstalled");
+function registerDefaultShutdownHandlers() {
+  const g = globalThis;
+  if (g[SHUTDOWN_INSTALLED_KEY]) return;
+  g[SHUTDOWN_INSTALLED_KEY] = true;
+  const shutdown = (signal) => {
+    console.log(`
+- Received ${signal}, shutting down...`);
+    void (async () => {
+      const app = getCurrentApp();
+      if (app) await app.close();
+      process.exit(0);
+    })();
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+}
 function getApp() {
   const app = getCurrentApp();
   if (!app) {
@@ -4701,6 +5446,8 @@ var FAAPI_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "extendContext",
   "plugins",
   "helmet",
+  "compression",
+  "etag",
   "bodyLimit",
   "logger",
   "http2",
@@ -4713,7 +5460,7 @@ 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 = path15.resolve(rootDir, dist, ROUTES_FILE);
+  const routesPath = path19.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`
@@ -4733,8 +5480,9 @@ async function createAppBase(options) {
       }
     }
   }
-  const tools = await loadAndHydrateTools(rootDir, dist);
-  const agents = await loadAndHydrateAgents(rootDir, dist);
+  const registries = createAppRegistries();
+  const tools = await loadAndHydrateTools(rootDir, dist, registries);
+  const agents = await loadAndHydrateAgents(rootDir, dist, registries);
   const pluginConfig = config ? Object.fromEntries(Object.entries(config).filter(([k]) => !isFaapiConfigKey(k))) : {};
   const { server, routesRef } = createServer({
     routes: sorted,
@@ -4747,30 +5495,52 @@ async function createAppBase(options) {
     middlewares: config?.middlewares,
     injectors: config?.injectors,
     helmet: config?.helmet,
+    compression: config?.compression,
+    etag: config?.etag,
     logger: config?.logger,
     bodyLimit: config?.bodyLimit,
     http2: config?.http2,
-    trustedProxy: config?.trustedProxy
-  });
-  const { handlerWrappers, upgradeWrappers } = await loadPlugins(config?.plugins, {
-    rootDir,
-    routes: sorted,
-    getRoutes: () => sorted,
-    server,
-    config: pluginConfig
+    trustedProxy: config?.trustedProxy,
+    registries
   });
+  const { handlerWrappers, upgradeWrappers } = await loadPlugins(
+    config?.plugins,
+    {
+      rootDir,
+      registries,
+      routes: sorted,
+      getRoutes: () => sorted,
+      server,
+      config: pluginConfig
+    },
+    rootDir
+  );
   applyPluginWrappers(server, handlerWrappers, upgradeWrappers);
   let closed = false;
   const app = {
     server: null,
+    registries,
     routes: sorted,
     wsRoutes,
     rootDir,
     async listen(listenPort) {
       const envPort = process.env.PORT ? Number(process.env.PORT) : void 0;
       const actualPort = listenPort ?? options?.port ?? envPort ?? DEFAULT_PORT;
-      return new Promise((resolve) => {
+      return new Promise((resolve, reject) => {
+        const onListenError = (err) => {
+          if (err.code === "EADDRINUSE") {
+            reject(
+              new Error(
+                `Port ${actualPort} is already in use. Is another faapi instance running? Change the port via the PORT env var.`
+              )
+            );
+            return;
+          }
+          reject(err);
+        };
+        server.once("error", onListenError);
         server.listen(actualPort, async () => {
+          server.off("error", onListenError);
           const address = server.address();
           const p = typeof address === "object" && address !== null ? address.port : actualPort;
           console.log("faapi server started");
@@ -4798,18 +5568,9 @@ async function createAppBase(options) {
               console.log(`  ${agent.name} [${exports}]  ${agent.filePath}`);
             }
           }
-          if (config?.lifecycle?.onClose) {
-            const graceful = async (signal) => {
-              console.log(`
-- Received ${signal}, shutting down...`);
-              await app.close();
-              process.exit(0);
-            };
-            process.on("SIGTERM", () => void graceful("SIGTERM"));
-            process.on("SIGINT", () => void graceful("SIGINT"));
-          }
+          registerDefaultShutdownHandlers();
           if (config?.lifecycle?.onReady) {
-            await config.lifecycle.onReady({ rootDir, routes: sorted, server });
+            await config.lifecycle.onReady({ rootDir, routes: sorted, server, registries });
             console.log("- onReady hook executed");
           }
           app.server = server;
@@ -4886,39 +5647,50 @@ async function createAppBase(options) {
       if (closed) return;
       closed = true;
       const s = server;
-      if (typeof s.closeIdleConnections === "function") {
-        s.closeIdleConnections();
-      }
-      if (typeof s.closeAllConnections === "function") {
-        s.closeAllConnections();
-      }
+      s.closeIdleConnections?.();
       if (config?.lifecycle?.onClose) {
-        await config.lifecycle.onClose({ rootDir, routes: sorted, server });
+        await config.lifecycle.onClose({ rootDir, routes: sorted, server, registries });
       }
-      clearToolRegistry();
-      clearAgentRegistry();
-      clearSkillRegistry();
-      clearAgentHandleFactory();
+      registries.tool.clear();
+      registries.agent.clear();
+      registries.skill.clear();
+      registries.agentHandle.clear();
       if (!server.listening) {
         app.server = null;
         if (getCurrentApp() === app) setCurrentApp(null);
         return;
       }
-      return new Promise((resolve) => {
+      const drained = new Promise((resolve) => {
         server.close((err) => {
           if (err) console.error("Error closing server:", err);
-          app.server = null;
-          if (getCurrentApp() === app) setCurrentApp(null);
           resolve();
         });
       });
+      const drainTimeoutMs = Number(process.env.FAAPI_SHUTDOWN_TIMEOUT_MS ?? 1e4);
+      if (typeof s.closeAllConnections === "function" && Number.isFinite(drainTimeoutMs) && drainTimeoutMs >= 0) {
+        const forceClose = new Promise((resolve) => {
+          const timer = setTimeout(() => {
+            s.closeAllConnections?.();
+            resolve();
+          }, drainTimeoutMs);
+          timer.unref?.();
+        });
+        await Promise.race([drained, forceClose]);
+        const tail = new Promise((resolve) => setTimeout(resolve, 250).unref?.());
+        await Promise.race([drained, tail]);
+      } else {
+        await drained;
+      }
+      app.server = null;
+      if (getCurrentApp() === app) setCurrentApp(null);
     }
   };
   setCurrentApp(app);
   const ctx = {
     rootDir,
+    registries,
     dist,
-    patterns: PATTERNS,
+    patterns: ROUTE_PATTERNS,
     server,
     routesRef,
     config,
@@ -4936,7 +5708,7 @@ async function createAppBase(options) {
 
 // src/router/scanRoutes.ts
 import fg2 from "fast-glob";
-import path16 from "path";
+import path20 from "path";
 import fs16 from "fs";
 
 // src/router/constants.ts
@@ -4944,9 +5716,9 @@ var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 var HTTP_METHOD_SET = new Set(HTTP_METHODS);
 
 // src/utils/normalizePath.ts
-function normalizePath(path19) {
-  if (!path19) return "";
-  let result = path19.replace(/\\/g, "/");
+function normalizePath(path23) {
+  if (!path23) return "";
+  let result = path23.replace(/\\/g, "/");
   result = result.replace(/\/+/g, "/");
   result = result.replace(/\/+$/, "");
   if (result && !result.startsWith("/")) {
@@ -5007,26 +5779,26 @@ function extractExportsFromSource(source) {
   return names;
 }
 function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
-  const routeDir = path16.dirname(routeFilePath);
-  const resolvedRoot = path16.resolve(rootDir);
+  const routeDir = path20.dirname(routeFilePath);
+  const resolvedRoot = path20.resolve(rootDir);
   const paths = [];
-  let currentDir = path16.resolve(rootDir, routeDir);
+  let currentDir = path20.resolve(rootDir, routeDir);
   while (true) {
     if (dist) {
-      const mwTsPath = path16.join(currentDir, "middlewares.ts");
-      const mwJsPath = path16.join(currentDir, "middlewares.js");
-      const absTsPath = path16.resolve(rootDir, mwTsPath);
-      const absJsPath = path16.resolve(rootDir, mwJsPath);
+      const mwTsPath = path20.join(currentDir, "middlewares.ts");
+      const mwJsPath = path20.join(currentDir, "middlewares.js");
+      const absTsPath = path20.resolve(rootDir, mwTsPath);
+      const absJsPath = path20.resolve(rootDir, mwJsPath);
       const absMwPath = fs16.existsSync(absTsPath) ? absTsPath : fs16.existsSync(absJsPath) ? absJsPath : null;
       if (absMwPath) {
-        const relMwPath = path16.relative(rootDir, absMwPath);
-        const prodAbsPath = path16.resolve(rootDir, toProdFilePath3(relMwPath, dist));
+        const relMwPath = path20.relative(rootDir, absMwPath);
+        const prodAbsPath = path20.resolve(rootDir, toProdFilePath(relMwPath, dist));
         paths.push(prodAbsPath);
       }
     } else {
       for (const ext of [".ts", ".js"]) {
-        const mwPath = path16.join(currentDir, `middlewares${ext}`);
-        const absMwPath = path16.resolve(rootDir, mwPath);
+        const mwPath = path20.join(currentDir, `middlewares${ext}`);
+        const absMwPath = path20.resolve(rootDir, mwPath);
         if (fs16.existsSync(absMwPath)) {
           paths.push(absMwPath);
           break;
@@ -5034,21 +5806,13 @@ function collectMiddlewarePaths(routeFilePath, rootDir, dist) {
       }
     }
     if (currentDir === resolvedRoot) break;
-    const parentDir = path16.dirname(currentDir);
+    const parentDir = path20.dirname(currentDir);
     if (parentDir === currentDir) break;
     currentDir = parentDir;
   }
   paths.reverse();
   return paths;
 }
-function toProdFilePath3(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}`;
-}
 async function scanRoutes(rootDir, patterns, dist) {
   const files = await fg2(patterns, {
     cwd: rootDir,
@@ -5061,7 +5825,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 = path16.resolve(rootDir, normalizedFile);
+      const absPath = path20.resolve(rootDir, normalizedFile);
       const urlPath = filePathToUrlPath(normalizedFile);
       const paramNames = extractParamNames(urlPath);
       const isDynamic = paramNames.length > 0;
@@ -5110,7 +5874,7 @@ async function scanRoutes(rootDir, patterns, dist) {
 
 // src/tools/scanTools.ts
 import fg3 from "fast-glob";
-import path17 from "path";
+import path21 from "path";
 import fs17 from "fs";
 var TOOL_PATTERNS = ["src/tools/**/*.ts"];
 var TOOL_EXPORT_RE = new RegExp(
@@ -5161,7 +5925,7 @@ async function scanTools(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path17.resolve(rootDir, normalizedFile);
+    const absPath = path21.resolve(rootDir, normalizedFile);
     const source = await fs17.promises.readFile(absPath, "utf8").catch(() => "");
     const exportNames = extractToolExportsFromSource(source);
     const namespace = filePathToToolNamespace(normalizedFile);
@@ -5186,7 +5950,7 @@ async function scanTools(rootDir, patterns) {
 
 // src/agents/scanAgents.ts
 import fg4 from "fast-glob";
-import path18 from "path";
+import path22 from "path";
 import fs18 from "fs";
 var DEFAULT_AGENT_PATTERNS = ["src/agents/*/handler.ts"];
 var RUN_EXPORT_RE = /export\s+(?:async\s+)?(?:function\s+|const\s+)run\b/;
@@ -5219,7 +5983,7 @@ async function scanAgents(rootDir, patterns) {
     if (fileName !== "handler.ts" && fileName !== "handler.js") {
       continue;
     }
-    const absPath = path18.resolve(rootDir, normalizedFile);
+    const absPath = path22.resolve(rootDir, normalizedFile);
     const source = await fs18.promises.readFile(absPath, "utf8").catch(() => "");
     const { hasRun } = detectAgentExports(source);
     const name = extractAgentNameFromPath(normalizedFile);
@@ -5255,6 +6019,14 @@ async function createDevApp(options) {
     if (isDevOnDemandEnabled()) {
       await deleteSchemaFiles(sorted, ctx.rootDir, ctx.dist);
       clearGeneratedSchemas();
+      void (async () => {
+        try {
+          const { generateSchemaFiles: generateSchemaFiles2 } = await Promise.resolve().then(() => (init_generateSchemaFiles(), generateSchemaFiles_exports));
+          await generateSchemaFiles2(sorted, ctx.rootDir, ctx.dist);
+        } catch (err) {
+          console.error("[faapi] Background schema regeneration failed:", err);
+        }
+      })();
     } else {
       const { generateSchemaFiles: generateSchemaFiles2 } = await Promise.resolve().then(() => (init_generateSchemaFiles(), generateSchemaFiles_exports));
       await generateSchemaFiles2(sorted, ctx.rootDir, ctx.dist);
@@ -5268,14 +6040,14 @@ async function createDevApp(options) {
     await generateToolArtifacts(tools, ctx.rootDir, ctx.dist, {
       skipSchema: isDevOnDemandEnabled()
     });
-    await loadAndHydrateTools(ctx.rootDir, ctx.dist);
+    await loadAndHydrateTools(ctx.rootDir, ctx.dist, ctx.registries);
   };
   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);
+    await loadAndHydrateAgents(ctx.rootDir, ctx.dist, ctx.registries);
   };
   return devApp;
 }
@@ -5297,6 +6069,7 @@ export {
   collectRouteSchemaSources,
   cors,
   createProdApp as createApp,
+  createAppRegistries,
   createDevApp,
   createProdApp,
   createProgram,