@faapi/faapi 6.27.0 → 6.29.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();
   }
 });
 
@@ -7550,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
@@ -7688,6 +7751,7 @@ var init_registries = __esm({
   "src/injection/registries.ts"() {
     "use strict";
     init_taskRegistry();
+    init_subAgentToolName();
     defaultRegistries = createAppRegistries();
   }
 });
@@ -10288,7 +10352,6 @@ async function createAppBase(options) {
     wsRoutes,
     rootDir,
     dist,
-    resourcesDir,
     tasks: taskQueue,
     async listen(listenPort) {
       const envPort = process.env.PORT ? Number(process.env.PORT) : void 0;