@faapi/faapi 6.26.0 → 6.28.0

package/dist/cli/index.js

@@ -985,6 +985,25 @@ var init_sortRoutes = __esm({
   }
 });
 
+// src/injection/subAgentToolName.ts
+function subAgentToolName(agentName) {
+  const toolName = SUB_AGENT_TOOL_PREFIX + agentName;
+  if (!LLM_TOOL_NAME_PATTERN.test(toolName)) {
+    throw new Error(
+      `Sub-agent tool name "${toolName}" (from agent name "${agentName}") violates the LLM tool name pattern ${LLM_TOOL_NAME_PATTERN} \u2014 rename the agent (allowed: a-z A-Z 0-9 '-' '_'; file-based agent directory segments allow a-z A-Z 0-9 '-' only, '_' is the nesting separator)`
+    );
+  }
+  return toolName;
+}
+var LLM_TOOL_NAME_PATTERN, SUB_AGENT_TOOL_PREFIX;
+var init_subAgentToolName = __esm({
+  "src/injection/subAgentToolName.ts"() {
+    "use strict";
+    LLM_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+    SUB_AGENT_TOOL_PREFIX = "agent-";
+  }
+});
+
 // src/tools/scanTools.ts
 import fg2 from "fast-glob";
 import path9 from "path";
@@ -1005,7 +1024,15 @@ function extractNamespaceFromRelPath(relPath) {
   const lastSlash = relPath.lastIndexOf("/");
   const dirPath = lastSlash === -1 ? "" : relPath.slice(0, lastSlash);
   if (!dirPath) return "";
-  return dirPath.split("/").join(".");
+  const segments = dirPath.split("/");
+  for (const segment of segments) {
+    if (!TOOL_DIR_SEGMENT_PATTERN.test(segment)) {
+      throw new Error(
+        `Invalid tool directory segment "${segment}" in "tools/${relPath}": tool directory names allow a-z A-Z 0-9 '-' only ('_' is reserved as the nesting separator, '.' is not allowed \u2014 tool names are sent to LLMs as function.name) \u2014 rename the directory`
+      );
+    }
+  }
+  return segments.join("_");
 }
 function filePathToToolNamespace(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
@@ -1016,7 +1043,13 @@ function filePathToToolNamespace(filePath) {
   return "";
 }
 function buildToolName(namespace, functionName) {
-  return namespace ? `${namespace}.${functionName}` : functionName;
+  const name = namespace ? `${namespace}_${functionName}` : functionName;
+  if (!LLM_TOOL_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Tool name "${name}" (function "${functionName}"${namespace ? ` in namespace "${namespace}"` : ""}) violates the LLM tool name pattern ${LLM_TOOL_NAME_PATTERN} \u2014 rename the function or use a @tool JSDoc override (allowed: a-z A-Z 0-9 '-' '_')`
+    );
+  }
+  return name;
 }
 async function scanTools(rootDir, patterns) {
   const files = await fg2(patterns, {
@@ -1054,16 +1087,18 @@ async function scanTools(rootDir, patterns) {
   }
   return tools;
 }
-var TOOL_PATTERNS, TOOL_EXPORT_RE, RESERVED_EXPORTS;
+var TOOL_PATTERNS, TOOL_EXPORT_RE, RESERVED_EXPORTS, TOOL_DIR_SEGMENT_PATTERN;
 var init_scanTools = __esm({
   "src/tools/scanTools.ts"() {
     "use strict";
+    init_subAgentToolName();
     TOOL_PATTERNS = ["src/tools/**/*.ts"];
     TOOL_EXPORT_RE = new RegExp(
       String.raw`export\s+(?:async\s+)?(?:function\s+|const\s+)([A-Za-z_$][\w$]*)\s*(?:\(|=)`,
       "g"
     );
     RESERVED_EXPORTS = /* @__PURE__ */ new Set(["default", "config", "run"]);
+    TOOL_DIR_SEGMENT_PATTERN = /^[a-zA-Z0-9-]+$/;
   }
 });
 
@@ -2898,6 +2933,14 @@ function extractToolMetadata(program, filePath, functionName, pathMeta) {
   const jsDoc = getJSDocFromNode(jsDocOwner);
   const description = extractDescription(jsDoc);
   const toolNameOverride = extractJSDocTagValue(jsDoc, "tool");
+  if (toolNameOverride !== void 0 && !LLM_TOOL_NAME_PATTERN.test(toolNameOverride)) {
+    throw SchemaExtractionError.at(
+      jsDocOwner,
+      "@tool",
+      `\u8986\u76D6\u540D "${toolNameOverride}" \u542B\u975E\u6CD5\u5B57\u7B26\u2014\u2014\u987B\u6EE1\u8DB3 ${LLM_TOOL_NAME_PATTERN}\uFF08tool \u540D\u76F4\u63A5\u4F5C\u4E3A LLM function.name\uFF0C\u5F3A\u6821\u9A8C\u4E0A\u6E38\u5BF9\u975E\u6CD5\u5B57\u7B26\u6574\u5355 400\uFF09`,
+      sourceFile
+    );
+  }
   const inputTypeName = getFirstParamTypeName(fn, sourceFile);
   return {
     name: toolNameOverride ?? pathMeta.name,
@@ -2939,6 +2982,8 @@ var init_extractToolMetadata = __esm({
   "src/ast/extractToolMetadata.ts"() {
     "use strict";
     init_jsDocMetadata();
+    init_subAgentToolName();
+    init_resolveTypeNode();
   }
 });
 
@@ -3090,7 +3135,15 @@ function extractAgentNameFromPath(filePath) {
       `Not an agent path: "${filePath}". Expected pattern: src/agents/<name>/handler.ts`
     );
   }
-  return match[1].replace(/\//g, ".");
+  const segments = match[1].split("/");
+  for (const segment of segments) {
+    if (!AGENT_DIR_SEGMENT_PATTERN.test(segment)) {
+      throw new Error(
+        `Invalid agent directory segment "${segment}" in "${filePath}": agent directory names allow a-z A-Z 0-9 '-' only ('_' is reserved as the nesting separator, '.' is not allowed \u2014 agent names become LLM tool names "agent-<name>") \u2014 rename the directory`
+      );
+    }
+  }
+  return segments.join("_");
 }
 async function scanAgents(rootDir, patterns) {
   const files = await fg3(patterns, {
@@ -3121,11 +3174,12 @@ async function scanAgents(rootDir, patterns) {
   }
   return agents;
 }
-var DEFAULT_AGENT_PATTERNS;
+var DEFAULT_AGENT_PATTERNS, AGENT_DIR_SEGMENT_PATTERN;
 var init_scanAgents = __esm({
   "src/agents/scanAgents.ts"() {
     "use strict";
     DEFAULT_AGENT_PATTERNS = ["src/agents/**/handler.ts"];
+    AGENT_DIR_SEGMENT_PATTERN = /^[a-zA-Z0-9-]+$/;
   }
 });
 
@@ -3164,6 +3218,14 @@ function extractAgentMetadata(program, filePath, pathMeta) {
   const jsDoc = getJSDocFromNode(configFound.jsDocOwner);
   const description = extractDescription(jsDoc);
   const agentNameOverride = extractJSDocTagValue(jsDoc, "agent");
+  if (agentNameOverride !== void 0 && !LLM_TOOL_NAME_PATTERN.test(agentNameOverride)) {
+    throw SchemaExtractionError.at(
+      configFound.jsDocOwner,
+      "@agent",
+      `\u8986\u76D6\u540D "${agentNameOverride}" \u542B\u975E\u6CD5\u5B57\u7B26\u2014\u2014\u987B\u6EE1\u8DB3 ${LLM_TOOL_NAME_PATTERN}\uFF08\u8986\u76D6\u540D\u6210\u4E3A LLM \u5DE5\u5177\u540D "agent-<\u8986\u76D6\u540D>"\uFF0C\u5F3A\u6821\u9A8C\u4E0A\u6E38\u5BF9\u975E\u6CD5\u5B57\u7B26\u6574\u5355 400\uFF09`,
+      sourceFile
+    );
+  }
   const { systemPrompt, systemPromptFile, tools, agents, model, maxTurns, inputDescription } = extractConfigFields(objectLiteral, sourceFile);
   return {
     name: agentNameOverride ?? pathMeta.name,
@@ -3385,6 +3447,7 @@ var init_extractAgentMetadata = __esm({
     "use strict";
     init_jsDocMetadata();
     init_resolveTypeNode();
+    init_subAgentToolName();
   }
 });
 
@@ -7080,18 +7143,10 @@ function formatSetCookie(name, value, options) {
   if (options?.sameSite) cookie += `; SameSite=${options.sameSite}`;
   return cookie;
 }
-function createContext(request, params, config = {}, ip = "", registries, resourcesDir) {
-  return createContextFromUrl(
-    request,
-    new URL(request.url),
-    params,
-    config,
-    ip,
-    registries,
-    resourcesDir
-  );
+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 = "", registries, resourcesDir) {
+function createContextFromUrl(request, url, params, config = {}, ip = "", registries) {
   const meta = { headers: {}, setCookies: [] };
   const parsedCookies = parseCookies(request.headers.get("cookie") ?? "");
   const cookiesObj = {};
@@ -7119,9 +7174,6 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
     ua: request.headers.get("user-agent") ?? "",
     cookies: cookiesObj,
     config,
-    // 运行时资源根目录（HTTP/WS 链路由 createServer/handleWsUpgrade 传入；
-    // testing 直调未传时为 undefined，见 contextTypes.resourcesDir 注释）
-    resourcesDir,
     meta,
     setStatus(status) {
       meta.status = status;
@@ -7561,7 +7613,7 @@ function createAgentRegistry(tool) {
       if (!agent) return void 0;
       return {
         kind: "agent",
-        name: `agent.${agent.name}`,
+        name: subAgentToolName(agent.name),
         agentName: agent.name,
         description: agent.description,
         metadata: agent
@@ -7699,6 +7751,7 @@ var init_registries = __esm({
   "src/injection/registries.ts"() {
     "use strict";
     init_taskRegistry();
+    init_subAgentToolName();
     defaultRegistries = createAppRegistries();
   }
 });
@@ -8657,7 +8710,6 @@ function attachWebSocket(options) {
     trustedProxy = false,
     registries
   } = options;
-  const resourcesDir = resolveResourcesDir(rootDir, dist);
   const wss = new WebSocketServer({ noServer: true });
   server.on("upgrade", async (req, socket, head) => {
     try {
@@ -8689,14 +8741,7 @@ function attachWebSocket(options) {
     const host = req.headers.host ?? "localhost";
     const fullUrl = new URL(`http://${host}${req.url ?? "/"}`);
     const request = new Request(fullUrl.toString(), { method: "GET", headers });
-    const ctx = createContext(
-      request,
-      params,
-      config,
-      getClientIp(req, trustedProxy),
-      registries,
-      resourcesDir
-    );
+    const ctx = createContext(request, params, config, getClientIp(req, trustedProxy), registries);
     const meta = ctx.meta;
     let upgraded = false;
     const finalHandler = async () => {
@@ -8798,7 +8843,6 @@ var init_handleWsUpgrade = __esm({
     "use strict";
     init_matchRoute();
     init_createContext();
-    init_copyResources();
     init_invokeHandler();
     init_importWithCacheBust();
     init_getClientIp();
@@ -8925,7 +8969,6 @@ function createServer(options) {
     trustedProxy = false
   } = options;
   const routesRef = { current: routes, wsCurrent: wsRoutes ?? [] };
-  const resourcesDir = resolveResourcesDir(rootDir, dist);
   const configMiddlewares = [];
   if (compressionOption) {
     const compOpts = typeof compressionOption === "object" ? compressionOption : {};
@@ -8972,8 +9015,7 @@ function createServer(options) {
       bodyLimit,
       trustedProxy,
       registries,
-      routesRef.wsCurrent,
-      resourcesDir
+      routesRef.wsCurrent
     ).catch((err) => {
       console.error("[faapi] Request pipeline failed after error response attempt:", err);
       try {
@@ -8999,7 +9041,7 @@ function createServer(options) {
   });
   return { server, routesRef };
 }
-function prepareRequest(req, request, url, config, trustedProxy, registries, preMatched, resourcesDir) {
+function prepareRequest(req, request, url, config, trustedProxy, registries, preMatched) {
   const method = request.method.toUpperCase();
   const urlPath = url.pathname;
   const ctx = createContextFromUrl(
@@ -9008,8 +9050,7 @@ function prepareRequest(req, request, url, config, trustedProxy, registries, pre
     preMatched?.params ?? {},
     config,
     getClientIp(req, trustedProxy),
-    registries,
-    resourcesDir
+    registries
   );
   const meta = ctx.meta;
   return { request, url, ctx, meta, method, urlPath };
@@ -9149,7 +9190,7 @@ async function sendErrorResponse(err, meta, res, onError, ctx) {
     }
   }
 }
-async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares, onError, config, globalInjectors, bodyLimit, trustedProxy, registries, wsRoutes, resourcesDir) {
+async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares, onError, config, globalInjectors, bodyLimit, trustedProxy, registries, wsRoutes) {
   let meta = { headers: {}, setCookies: [] };
   let ctx;
   let sseEarlySent = false;
@@ -9169,8 +9210,7 @@ async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares,
       config,
       trustedProxy,
       registries,
-      preMatched,
-      resourcesDir
+      preMatched
     );
     ctx = prepared.ctx;
     meta = prepared.meta;
@@ -9239,7 +9279,6 @@ var init_createServer = __esm({
     init_handleWsUpgrade();
     init_serverUtils();
     init_generateSchemaFiles();
-    init_copyResources();
     init_compileOnDemand();
     init_loadMiddlewares();
     DEFAULT_BODY_LIMIT = 10 * 1024 * 1024;
@@ -9419,7 +9458,6 @@ async function runTaskInWorker(options) {
         payload,
         taskCtx: {
           config: safeConfig(taskCtx.config),
-          resourcesDir: taskCtx.resourcesDir,
           job: taskCtx.job
         },
         registries: options.registries,
@@ -9578,7 +9616,6 @@ function createTaskQueue(deps) {
         const taskCtx = {
           signal: job.signal,
           config: deps.config,
-          resourcesDir: deps.resourcesDir,
           job: { id: job.id, name: job.name, attempt: job.attempt },
           registries: registriesView,
           log: createLogger(`task:${job.name}`, {
@@ -10297,7 +10334,6 @@ async function createAppBase(options) {
     config?.plugins,
     {
       rootDir,
-      resourcesDir,
       registries,
       routes: sorted,
       getRoutes: () => sorted,
@@ -10328,8 +10364,7 @@ async function createAppBase(options) {
             routes: sorted,
             server,
             registries,
-            tasks: taskQueue,
-            resourcesDir
+            tasks: taskQueue
           });
           console.log("- onBoot hook executed");
         } catch (err) {
@@ -10364,8 +10399,7 @@ async function createAppBase(options) {
               routes: sorted,
               server,
               registries,
-              tasks: taskQueue,
-              resourcesDir
+              tasks: taskQueue
             });
             console.log("- onReady hook executed");
           }
@@ -10389,8 +10423,7 @@ async function createAppBase(options) {
           routes: sorted,
           server,
           registries,
-          tasks: taskQueue,
-          resourcesDir
+          tasks: taskQueue
         });
       }
       registries.tool.clear();