@faapi/faapi 6.26.0 → 6.28.0

package/dist/index.js

@@ -1835,6 +1835,19 @@ function createTaskRegistry() {
   };
 }
 
+// src/injection/subAgentToolName.ts
+var LLM_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+var SUB_AGENT_TOOL_PREFIX = "agent-";
+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;
+}
+
 // src/injection/registries.ts
 function createToolRegistry() {
   let registry = /* @__PURE__ */ new Map();
@@ -1882,7 +1895,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
@@ -2224,7 +2237,6 @@ async function runTaskInWorker(options) {
         payload,
         taskCtx: {
           config: safeConfig(taskCtx.config),
-          resourcesDir: taskCtx.resourcesDir,
           job: taskCtx.job
         },
         registries: options.registries,
@@ -2607,7 +2619,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}`, {
@@ -3687,6 +3698,7 @@ function extractJSDocTagValue(jsDoc, tagName) {
 }
 
 // src/ast/extractToolMetadata.ts
+init_resolveTypeNode();
 function extractToolMetadata(program, filePath, functionName, pathMeta) {
   const sourceFile = program.getSourceFile(filePath);
   if (!sourceFile) return null;
@@ -3696,6 +3708,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,
@@ -4296,7 +4316,7 @@ import {
 import { createSecureServer as createHttp2SecureServer } from "http2";
 import { readFileSync } from "fs";
 import { Readable as Readable2 } from "stream";
-import path21 from "path";
+import path20 from "path";
 
 // src/router/matchRoute.ts
 var httpIndexCache = /* @__PURE__ */ new WeakMap();
@@ -4917,18 +4937,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 = {};
@@ -4956,9 +4968,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;
@@ -5776,17 +5785,9 @@ function etag(options = {}) {
 }
 
 // src/server/handleWsUpgrade.ts
-import fs17 from "fs";
+import fs16 from "fs";
 import { WebSocketServer, WebSocket } from "ws";
-import path20 from "path";
-
-// src/cli/copyResources.ts
 import path19 from "path";
-import fs16 from "fs";
-var RESOURCES_OUTPUT_DIR = "resources";
-function resolveResourcesDir(rootDir, dist) {
-  return path19.resolve(rootDir, dist, RESOURCES_OUTPUT_DIR);
-}
 
 // src/server/serverUtils.ts
 function nodeHttpToWebHeaders(req) {
@@ -5926,7 +5927,7 @@ async function loadWsHandler(filePath, ctx, rootDir) {
     const dist = getDevDist();
     if (dist) {
       const sourcePath = prodPathToSourcePath(filePath, rootDir, dist);
-      if (sourcePath && fs17.existsSync(sourcePath)) {
+      if (sourcePath && fs16.existsSync(sourcePath)) {
         await ensureCompiled(sourcePath, rootDir, dist);
       }
     }
@@ -6024,7 +6025,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 {
@@ -6056,19 +6056,12 @@ 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 () => {
       const schemaPath = getRuntimeSchemaPath(route.filePath, dist, rootDir);
-      if (fs17.existsSync(schemaPath)) {
+      if (fs16.existsSync(schemaPath)) {
         if (isDevOnDemandEnabled()) {
           const devDist = getDevDist();
           if (devDist) {
@@ -6107,7 +6100,7 @@ function attachWebSocket(options) {
       }
       let handlers;
       try {
-        const absoluteFilePath = path20.resolve(rootDir, route.filePath);
+        const absoluteFilePath = path19.resolve(rootDir, route.filePath);
         handlers = await loadWsHandler(absoluteFilePath, ctx, rootDir);
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -6267,7 +6260,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 : {};
@@ -6314,8 +6306,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 {
@@ -6341,7 +6332,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(
@@ -6350,8 +6341,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 };
@@ -6370,7 +6360,7 @@ function getRoutePaths(route, rootDir, dist) {
   let cached = routePathCache.get(route);
   if (!cached) {
     cached = {
-      absFilePath: path21.resolve(rootDir, route.filePath),
+      absFilePath: path20.resolve(rootDir, route.filePath),
       schemaPath: getRuntimeSchemaPath(route.filePath, dist, rootDir)
     };
     routePathCache.set(route, cached);
@@ -6493,7 +6483,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;
@@ -6513,8 +6503,7 @@ async function handleRequest(routes, rootDir, dist, req, res, outerMiddlewares,
       config,
       trustedProxy,
       registries,
-      preMatched,
-      resourcesDir
+      preMatched
     );
     ctx = prepared.ctx;
     meta = prepared.meta;
@@ -6590,8 +6579,8 @@ function applyPluginWrappers(server, handlerWrappers, upgradeWrappers) {
 }
 
 // src/cli/generateRoutes.ts
-import fs18 from "fs";
-import path22 from "path";
+import fs17 from "fs";
+import path21 from "path";
 async function hydrateRoutes(manifest) {
   const hydrateRoute = (serialized) => ({
     method: serialized.method,
@@ -6635,18 +6624,18 @@ function createIdleTaskDriver() {
 }
 
 // src/cli/loadPlugins.ts
-import path24 from "path";
-import fs20 from "fs";
+import path23 from "path";
+import fs19 from "fs";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/cli/compileConfig.ts
-import path23 from "path";
-import fs19 from "fs";
+import path22 from "path";
+import fs18 from "fs";
 async function compileProjectModules(entryPoints, rootDir, dist) {
   const { insideFiles, outsideFiles } = await collectRelativeImports(entryPoints, rootDir);
   const esbuild = await import("esbuild");
   const aliasPlugins = buildAliasPlugins(rootDir);
-  const absDist = path23.resolve(rootDir, dist);
+  const absDist = path22.resolve(rootDir, dist);
   await esbuild.build({
     entryPoints: [...entryPoints, ...outsideFiles],
     outdir: absDist,
@@ -6660,7 +6649,7 @@ async function compileProjectModules(entryPoints, rootDir, dist) {
     logLevel: "silent"
   });
   if (insideFiles.length > 0) {
-    const appOutbase = path23.resolve(rootDir, "src");
+    const appOutbase = path22.resolve(rootDir, "src");
     await esbuild.build({
       entryPoints: insideFiles,
       outdir: absDist,
@@ -6741,30 +6730,30 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
 var TS_EXTS = /\.(ts|tsx|mts|cts)$/;
 var JS_EXTS = /\.(js|mjs|cjs|jsx)$/;
 function resolveLocalPluginSource(specifier, baseDir) {
-  const base = path24.isAbsolute(specifier) ? specifier : path24.resolve(baseDir, specifier);
-  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs20.existsSync(base)) return base;
+  const base = path23.isAbsolute(specifier) ? specifier : path23.resolve(baseDir, specifier);
+  if ((TS_EXTS.test(base) || JS_EXTS.test(base)) && fs19.existsSync(base)) return base;
   for (const ext of [".ts", ".js"]) {
-    if (fs20.existsSync(base + ext)) return base + ext;
+    if (fs19.existsSync(base + ext)) return base + ext;
   }
   for (const indexExt of ["/index.ts", "/index.js"]) {
-    if (fs20.existsSync(base + indexExt)) return base + indexExt;
+    if (fs19.existsSync(base + indexExt)) return base + indexExt;
   }
   return null;
 }
 function mirrorProductPath(sourcePath, baseDir, distDir) {
-  let rel = path24.relative(baseDir, sourcePath).replace(/\\/g, "/");
+  let rel = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
   if (rel.startsWith("src/")) rel = rel.slice(4);
-  return path24.resolve(distDir, rel.replace(TS_EXTS, ".js"));
+  return path23.resolve(distDir, rel.replace(TS_EXTS, ".js"));
 }
 async function importPluginModule(specifier, baseDir, dist) {
   const isRelative = specifier.startsWith("./") || specifier.startsWith("../");
-  if (!isRelative && !path24.isAbsolute(specifier)) {
+  if (!isRelative && !path23.isAbsolute(specifier)) {
     return import(specifier);
   }
-  const distDir = dist ? path24.resolve(baseDir, dist) : null;
+  const distDir = dist ? path23.resolve(baseDir, dist) : null;
   const sourcePath = resolveLocalPluginSource(specifier, baseDir);
   const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
-  if (productPath !== null && fs20.existsSync(productPath) && (sourcePath === null || isProductFresh(sourcePath, productPath))) {
+  if (productPath !== null && fs19.existsSync(productPath) && (sourcePath === null || isProductFresh(sourcePath, productPath))) {
     return import(pathToFileURL3(productPath).href);
   }
   if (sourcePath && TS_EXTS.test(sourcePath)) {
@@ -6773,13 +6762,13 @@ async function importPluginModule(specifier, baseDir, dist) {
         `Local plugin "${specifier}" has no up-to-date build artifact (dist is stale or missing). Run "faapi build" first, or use "faapi dev" for on-demand compilation.`
       );
     }
-    const relFromRoot = path24.relative(baseDir, sourcePath).replace(/\\/g, "/");
+    const relFromRoot = path23.relative(baseDir, sourcePath).replace(/\\/g, "/");
     if (relFromRoot.startsWith("src/")) {
       await ensureCompiled(sourcePath, baseDir, dist);
     } else {
       await compileProjectModules([sourcePath], baseDir, dist);
     }
-    if (productPath && fs20.existsSync(productPath)) {
+    if (productPath && fs19.existsSync(productPath)) {
       return import(pathToFileURL3(productPath).href);
     }
   }
@@ -6791,7 +6780,7 @@ async function importPluginModule(specifier, baseDir, dist) {
     `${specifier}/index.ts`,
     `${specifier}.js`,
     `${specifier}/index.js`
-  ].map((c) => path24.isAbsolute(c) ? c : path24.join(baseDir, c));
+  ].map((c) => path23.isAbsolute(c) ? c : path23.join(baseDir, c));
   throw new Error(
     `Cannot find local plugin "${specifier}" (resolved from ${baseDir}). Expected one of:
   ${candidates.join("\n  ")}
@@ -6816,11 +6805,11 @@ function resolveDeclaration(decl) {
 }
 
 // src/cli/manifestLoader.ts
-import fs21 from "fs";
-import path27 from "path";
+import fs20 from "fs";
+import path26 from "path";
 
 // src/cli/generateAgentArtifacts.ts
-import path25 from "path";
+import path24 from "path";
 
 // src/ast/extractAgentMetadata.ts
 import ts11 from "typescript";
@@ -6858,6 +6847,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,
@@ -7137,9 +7134,9 @@ function validateAgentList(metadata) {
 }
 async function generateAgentArtifacts(agents, rootDir, dist) {
   const metadata = [];
-  const programByFile = createPrograms(agents.map((m) => path25.resolve(rootDir, m.filePath)));
+  const programByFile = createPrograms(agents.map((m) => path24.resolve(rootDir, m.filePath)));
   for (const manifest of agents) {
-    const absPath = path25.resolve(rootDir, manifest.filePath);
+    const absPath = path24.resolve(rootDir, manifest.filePath);
     const program = programByFile.get(absPath);
     const result = extractAgentMetadata(program, absPath, {
       name: manifest.name,
@@ -7154,14 +7151,14 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
   }
   validateAgentList(metadata);
   const serialized = serializeAgents(metadata, dist);
-  const agentsPath = path25.resolve(rootDir, dist, AGENTS_FILE);
+  const agentsPath = path24.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);
   return metadata;
 }
 
 // src/cli/generateTaskArtifacts.ts
 init_generateZodArtifacts();
-import path26 from "path";
+import path25 from "path";
 init_createProgram();
 init_atomicWrite();
 init_extractHandlerTypes();
@@ -7199,7 +7196,7 @@ function collectTaskSchemaSources(tasks, rootDir) {
   const tasksByFile = /* @__PURE__ */ new Map();
   for (const task of tasks) {
     if (!task.inputTypeName) continue;
-    const absPath = path26.resolve(rootDir, task.filePath);
+    const absPath = path25.resolve(rootDir, task.filePath);
     let list = tasksByFile.get(absPath);
     if (!list) {
       list = [];
@@ -7256,9 +7253,9 @@ function generateTaskSchemaFileSource(sources, resolveType, helpersImportPath) {
 async function generateTaskArtifacts(manifests, rootDir, dist) {
   const metadata = [];
   if (manifests.length > 0) {
-    const programByFile = createPrograms(manifests.map((m) => path26.resolve(rootDir, m.filePath)));
+    const programByFile = createPrograms(manifests.map((m) => path25.resolve(rootDir, m.filePath)));
     for (const manifest of manifests) {
-      const absPath = path26.resolve(rootDir, manifest.filePath);
+      const absPath = path25.resolve(rootDir, manifest.filePath);
       const result = extractToolMetadata(programByFile.get(absPath), absPath, "run", {
         name: manifest.name,
         filePath: manifest.filePath
@@ -7269,7 +7266,7 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
     }
   }
   const serialized = serializeTasks(manifests, dist);
-  const tasksPath = path26.resolve(rootDir, dist, TASKS_FILE);
+  const tasksPath = path25.resolve(rootDir, dist, TASKS_FILE);
   await writeTasksModule(serialized, tasksPath);
   if (metadata.length === 0) {
     return hydrateTasks(serialized);
@@ -7291,8 +7288,8 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
 var TOOLS_FILE2 = "faapi-tools.js";
 var AGENTS_FILE2 = "faapi-agents.js";
 async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries) {
-  const toolsPath = path27.resolve(rootDir, dist, TOOLS_FILE2);
-  if (!fs21.existsSync(toolsPath)) {
+  const toolsPath = path26.resolve(rootDir, dist, TOOLS_FILE2);
+  if (!fs20.existsSync(toolsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(toolsPath);
@@ -7301,8 +7298,8 @@ async function loadAndHydrateTools(rootDir, dist, registries = defaultRegistries
   return hydrated;
 }
 async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistries) {
-  const agentsPath = path27.resolve(rootDir, dist, AGENTS_FILE2);
-  if (!fs21.existsSync(agentsPath)) {
+  const agentsPath = path26.resolve(rootDir, dist, AGENTS_FILE2);
+  if (!fs20.existsSync(agentsPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(agentsPath);
@@ -7317,8 +7314,8 @@ function getTaskDriverOptions(config) {
   return void 0;
 }
 async function loadAndHydrateTasks(rootDir, dist, registries = defaultRegistries) {
-  const tasksPath = path27.resolve(rootDir, dist, TASKS_FILE);
-  if (!fs21.existsSync(tasksPath)) {
+  const tasksPath = path26.resolve(rootDir, dist, TASKS_FILE);
+  if (!fs20.existsSync(tasksPath)) {
     return [];
   }
   const serialized = await importWithCacheBust(tasksPath);
@@ -7449,6 +7446,14 @@ function performInject(server, injectOpts) {
   });
 }
 
+// src/cli/copyResources.ts
+import path27 from "path";
+import fs21 from "fs";
+var RESOURCES_OUTPUT_DIR = "resources";
+function resolveResourcesDir(rootDir, dist) {
+  return path27.resolve(rootDir, dist, RESOURCES_OUTPUT_DIR);
+}
+
 // src/cli/createAppCore.ts
 var DEFAULT_DIST = "dist";
 var DEFAULT_PORT = 3e3;
@@ -7580,7 +7585,6 @@ async function createAppBase(options) {
     config?.plugins,
     {
       rootDir,
-      resourcesDir,
       registries,
       routes: sorted,
       getRoutes: () => sorted,
@@ -7611,8 +7615,7 @@ async function createAppBase(options) {
             routes: sorted,
             server,
             registries,
-            tasks: taskQueue,
-            resourcesDir
+            tasks: taskQueue
           });
           console.log("- onBoot hook executed");
         } catch (err) {
@@ -7647,8 +7650,7 @@ async function createAppBase(options) {
               routes: sorted,
               server,
               registries,
-              tasks: taskQueue,
-              resourcesDir
+              tasks: taskQueue
             });
             console.log("- onReady hook executed");
           }
@@ -7672,8 +7674,7 @@ async function createAppBase(options) {
           routes: sorted,
           server,
           registries,
-          tasks: taskQueue,
-          resourcesDir
+          tasks: taskQueue
         });
       }
       registries.tool.clear();
@@ -7926,11 +7927,20 @@ function extractToolExportsFromSource(source) {
   }
   return names;
 }
+var TOOL_DIR_SEGMENT_PATTERN = /^[a-zA-Z0-9-]+$/;
 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, "/");
@@ -7941,7 +7951,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 fg4(patterns, {
@@ -7983,6 +7999,7 @@ async function scanTools(rootDir, patterns) {
 // src/agents/scanAgents.ts
 import fg5 from "fast-glob";
 var DEFAULT_AGENT_PATTERNS = ["src/agents/**/handler.ts"];
+var AGENT_DIR_SEGMENT_PATTERN = /^[a-zA-Z0-9-]+$/;
 function extractAgentNameFromPath(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
   const match = normalized.match(/(?:^|\/)agents\/(.+)\/handler\.ts$/);
@@ -7991,7 +8008,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 fg5(patterns, {
@@ -8107,9 +8132,11 @@ async function createProdApp(options) {
 export {
   FaapiError,
   InternalError,
+  LLM_TOOL_NAME_PATTERN,
   MethodNotAllowedError,
   ModuleLoadError,
   RouteNotFoundError,
+  SUB_AGENT_TOOL_PREFIX,
   SchemaExtractionError,
   TASK_PATTERNS,
   ValidationError,
@@ -8154,6 +8181,7 @@ export {
   resolveSubAgents,
   resolveTypeNode,
   scanTasks,
+  subAgentToolName,
   upsertSkill
 };
 //# sourceMappingURL=index.js.map