@navai/voice-frontend 0.1.3 → 0.1.6

package/dist/index.js

@@ -247,27 +247,33 @@ function getNavaiRoutePromptLines(routes = []) {
 // src/agent.ts
 var RESERVED_TOOL_NAMES = /* @__PURE__ */ new Set(["navigate_to", "execute_app_function"]);
 var TOOL_NAME_REGEXP = /^[a-zA-Z0-9_-]{1,64}$/;
+var DEBUG_PREFIX = "[navai debug]";
 function toErrorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
-async function buildNavaiAgent(options) {
-  const functionsRegistry = await loadNavaiFunctions(options.functionModuleLoaders ?? {});
-  const backendWarnings = [];
+function debugLog(message, details) {
+  if (details === void 0) {
+    console.log(`${DEBUG_PREFIX} ${message}`);
+    return;
+  }
+  console.log(`${DEBUG_PREFIX} ${message}`, details);
+}
+function normalizeBackendFunctions(backendFunctions, functionsRegistry, warnings) {
   const backendFunctionsByName = /* @__PURE__ */ new Map();
   const backendFunctionsOrdered = [];
-  for (const backendFunction of options.backendFunctions ?? []) {
+  for (const backendFunction of backendFunctions ?? []) {
     const name = backendFunction.name.trim().toLowerCase();
     if (!name) {
       continue;
     }
     if (functionsRegistry.byName.has(name)) {
-      backendWarnings.push(
+      warnings.push(
         `[navai] Ignored backend function "${backendFunction.name}": name conflicts with a frontend function.`
       );
       continue;
     }
     if (backendFunctionsByName.has(name)) {
-      backendWarnings.push(`[navai] Ignored duplicated backend function "${backendFunction.name}".`);
+      warnings.push(`[navai] Ignored duplicated backend function "${backendFunction.name}".`);
       continue;
     }
     const normalizedDefinition = {
@@ -277,94 +283,119 @@ async function buildNavaiAgent(options) {
     backendFunctionsByName.set(name, normalizedDefinition);
     backendFunctionsOrdered.push(normalizedDefinition);
   }
+  return backendFunctionsOrdered;
+}
+function createExecuteAppFunction(input) {
+  const backendFunctionsByName = new Map(input.backendFunctions.map((item) => [item.name, item]));
   const availableFunctionNames = [
-    ...functionsRegistry.ordered.map((item) => item.name),
-    ...backendFunctionsOrdered.map((item) => item.name)
+    ...input.functionsRegistry.ordered.map((item) => item.name),
+    ...input.backendFunctions.map((item) => item.name)
   ];
-  const aliasWarnings = [];
-  const directFunctionToolNames = [...new Set(availableFunctionNames)].map((name) => name.trim().toLowerCase()).filter((name) => {
-    if (!name) {
-      return false;
-    }
-    if (RESERVED_TOOL_NAMES.has(name)) {
-      aliasWarnings.push(
-        `[navai] Function "${name}" is available only via execute_app_function because its name conflicts with a built-in tool.`
-      );
-      return false;
-    }
-    if (!TOOL_NAME_REGEXP.test(name)) {
-      aliasWarnings.push(
-        `[navai] Function "${name}" is available only via execute_app_function because its name is not a valid tool id.`
-      );
-      return false;
-    }
-    return true;
-  });
   const executeAppFunction = async (requestedName, payload) => {
     const requested = requestedName.trim().toLowerCase();
-    const frontendDefinition = functionsRegistry.byName.get(requested);
+    debugLog("execute_app_function called", { requestedName, requested, payload });
+    const frontendDefinition = input.functionsRegistry.byName.get(requested);
     if (frontendDefinition) {
       try {
-        const result = await frontendDefinition.run(payload ?? {}, options);
-        return { ok: true, function_name: frontendDefinition.name, source: frontendDefinition.source, result };
+        debugLog("executing frontend function", {
+          functionName: frontendDefinition.name,
+          source: frontendDefinition.source
+        });
+        const result = await frontendDefinition.run(payload ?? {}, input.context);
+        const response = {
+          ok: true,
+          function_name: frontendDefinition.name,
+          source: frontendDefinition.source,
+          result
+        };
+        debugLog("frontend function completed", response);
+        return response;
       } catch (error) {
-        return {
+        const failure = {
           ok: false,
           function_name: frontendDefinition.name,
           error: "Function execution failed.",
           details: toErrorMessage2(error)
         };
+        debugLog("frontend function failed", failure);
+        return failure;
       }
     }
     const backendDefinition = backendFunctionsByName.get(requested);
     if (!backendDefinition) {
-      return {
+      const failure = {
         ok: false,
         error: "Unknown or disallowed function.",
         available_functions: availableFunctionNames
       };
+      debugLog("execute_app_function rejected unknown function", failure);
+      return failure;
     }
-    if (!options.executeBackendFunction) {
-      return {
+    if (!input.executeBackendFunction) {
+      const failure = {
         ok: false,
         function_name: backendDefinition.name,
         error: "Backend function execution is not configured."
       };
+      debugLog("backend function execution unavailable", failure);
+      return failure;
     }
     try {
-      const result = await options.executeBackendFunction({
+      debugLog("executing backend function", {
+        functionName: backendDefinition.name,
+        source: backendDefinition.source ?? "backend"
+      });
+      const result = await input.executeBackendFunction({
         functionName: backendDefinition.name,
         payload: payload ?? null
       });
-      return {
+      const response = {
         ok: true,
         function_name: backendDefinition.name,
         source: backendDefinition.source ?? "backend",
         result
       };
+      debugLog("backend function completed", response);
+      return response;
     } catch (error) {
-      return {
+      const failure = {
         ok: false,
         function_name: backendDefinition.name,
         error: "Function execution failed.",
         details: toErrorMessage2(error)
       };
+      debugLog("backend function failed", failure);
+      return failure;
     }
   };
-  const navigateTool = tool({
-    name: "navigate_to",
-    description: "Navigate to an allowed route in the current app.",
-    parameters: z.object({
-      target: z.string().min(1).describe("Route name or route path. Example: perfil, ajustes, /profile, /settings")
-    }),
-    execute: async ({ target }) => {
-      const path = resolveNavaiRoute(target, options.routes);
-      if (!path) {
-        return { ok: false, error: "Unknown or disallowed route." };
-      }
-      options.navigate(path);
-      return { ok: true, path };
+  return {
+    availableFunctionNames,
+    executeAppFunction
+  };
+}
+function createFunctionTools(input) {
+  const aliasWarnings = [];
+  const availableFunctionNames = [
+    ...input.functionsRegistry.ordered.map((item) => item.name),
+    ...input.backendFunctions.map((item) => item.name)
+  ];
+  const directFunctionToolNames = input.includeDirectAliases === false ? [] : [...new Set(availableFunctionNames)].map((name) => name.trim().toLowerCase()).filter((name) => {
+    if (!name) {
+      return false;
+    }
+    if (RESERVED_TOOL_NAMES.has(name)) {
+      aliasWarnings.push(
+        `[navai] Function "${name}" is available only via execute_app_function because its name conflicts with a built-in tool.`
+      );
+      return false;
+    }
+    if (!TOOL_NAME_REGEXP.test(name)) {
+      aliasWarnings.push(
+        `[navai] Function "${name}" is available only via execute_app_function because its name is not a valid tool id.`
+      );
+      return false;
     }
+    return true;
   });
   const executeFunctionTool = tool({
     name: "execute_app_function",
@@ -375,36 +406,146 @@ async function buildNavaiAgent(options) {
         "Payload object. Use null when no arguments are needed. Use payload.args as array for function args, payload.constructorArgs for class constructors, payload.methodArgs for class methods."
       )
     }),
-    execute: async ({ function_name, payload }) => await executeAppFunction(function_name, payload)
+    execute: async ({ function_name, payload }) => await input.executeAppFunction(function_name, payload)
   });
   const directFunctionTools = directFunctionToolNames.map(
     (functionName) => tool({
       name: functionName,
       description: `Direct alias for execute_app_function("${functionName}").`,
       parameters: z.object({
-        payload: z.record(z.string(), z.unknown()).nullable().optional().describe(
+        payload: z.record(z.string(), z.unknown()).nullable().describe(
           "Payload object. Optional. Use payload.args as array for function args, payload.constructorArgs for class constructors, payload.methodArgs for class methods."
         )
       }),
-      execute: async ({ payload }) => await executeAppFunction(functionName, payload ?? null)
+      execute: async ({ payload }) => await input.executeAppFunction(functionName, payload ?? null)
     })
   );
-  const routeLines = getNavaiRoutePromptLines(options.routes);
-  const functionLines = functionsRegistry.ordered.length + backendFunctionsOrdered.length > 0 ? [
+  return {
+    aliasWarnings,
+    availableFunctionNames,
+    executeFunctionTool,
+    directFunctionTools
+  };
+}
+function buildFunctionLines(functionsRegistry, backendFunctions) {
+  return functionsRegistry.ordered.length + backendFunctions.length > 0 ? [
     ...functionsRegistry.ordered.map((item) => `- ${item.name}: ${item.description}`),
-    ...backendFunctionsOrdered.map(
-      (item) => `- ${item.name}: ${item.description ?? "Execute backend function."}`
-    )
+    ...backendFunctions.map((item) => `- ${item.name}: ${item.description ?? "Execute backend function."}`)
   ] : ["- none"];
+}
+async function buildNavaiAgent(options) {
+  const aggregatedWarnings = [];
+  const configuredAgents = (options.agents ?? []).filter(
+    (agent2) => Object.keys(agent2.functionModuleLoaders ?? {}).length > 0
+  );
+  const primaryAgentConfig = configuredAgents.find((agent2) => agent2.key === options.primaryAgentKey) ?? configuredAgents.find((agent2) => agent2.isPrimary) ?? configuredAgents[0];
+  const primaryFunctionLoaders = primaryAgentConfig?.functionModuleLoaders ?? options.functionModuleLoaders ?? {};
+  const functionsRegistry = await loadNavaiFunctions(primaryFunctionLoaders);
+  const backendFunctionsOrdered = normalizeBackendFunctions(options.backendFunctions, functionsRegistry, aggregatedWarnings);
+  const primaryExecutionSurface = createExecuteAppFunction({
+    functionsRegistry,
+    backendFunctions: backendFunctionsOrdered,
+    executeBackendFunction: options.executeBackendFunction,
+    context: options
+  });
+  const primaryFunctionTools = createFunctionTools({
+    functionsRegistry,
+    backendFunctions: backendFunctionsOrdered,
+    executeAppFunction: primaryExecutionSurface.executeAppFunction
+  });
+  aggregatedWarnings.push(...functionsRegistry.warnings, ...primaryFunctionTools.aliasWarnings);
+  const navigateTool = tool({
+    name: "navigate_to",
+    description: "Navigate to an allowed route in the current app.",
+    parameters: z.object({
+      target: z.string().min(1).describe("Route name or route path. Example: perfil, ajustes, /profile, /settings")
+    }),
+    execute: async ({ target }) => {
+      debugLog("navigate_to called", { target });
+      const path = resolveNavaiRoute(target, options.routes);
+      if (!path) {
+        const failure = { ok: false, error: "Unknown or disallowed route." };
+        debugLog("navigate_to rejected", failure);
+        return failure;
+      }
+      options.navigate(path);
+      const response = { ok: true, path };
+      debugLog("navigate_to completed", response);
+      return response;
+    }
+  });
+  const routeLines = getNavaiRoutePromptLines(options.routes);
+  const functionLines = buildFunctionLines(functionsRegistry, backendFunctionsOrdered);
+  const specialistAgents = [];
+  const specialistLines = [];
+  for (const runtimeAgent of configuredAgents) {
+    if (primaryAgentConfig && runtimeAgent.key === primaryAgentConfig.key) {
+      continue;
+    }
+    const specialistRegistry = await loadNavaiFunctions(runtimeAgent.functionModuleLoaders);
+    const specialistWarnings = [...specialistRegistry.warnings];
+    const specialistBackendFunctions = normalizeBackendFunctions(
+      options.backendFunctions,
+      specialistRegistry,
+      specialistWarnings
+    );
+    const specialistExecutionSurface = createExecuteAppFunction({
+      functionsRegistry: specialistRegistry,
+      backendFunctions: specialistBackendFunctions,
+      executeBackendFunction: options.executeBackendFunction,
+      context: options
+    });
+    const specialistFunctionTools = createFunctionTools({
+      functionsRegistry: specialistRegistry,
+      backendFunctions: specialistBackendFunctions,
+      executeAppFunction: specialistExecutionSurface.executeAppFunction,
+      includeDirectAliases: false
+    });
+    specialistWarnings.push(...specialistFunctionTools.aliasWarnings);
+    aggregatedWarnings.push(...specialistWarnings);
+    const specialistInstructions = [
+      runtimeAgent.instructions ?? `You are the ${runtimeAgent.name} specialist agent for this web app.`,
+      "Allowed app functions:",
+      ...buildFunctionLines(specialistRegistry, specialistBackendFunctions),
+      "Rules:",
+      "- Always use execute_app_function for app actions.",
+      "- When no arguments are needed, call execute_app_function with payload set to null.",
+      "- Use only the functions available to this specialist agent.",
+      "- Do not navigate unless one of your allowed functions explicitly does so.",
+      "- Return a concise result to the main NAVAI agent."
+    ].join("\n");
+    debugLog("creating specialist agent", {
+      key: runtimeAgent.key,
+      name: runtimeAgent.name,
+      functions: [
+        ...specialistRegistry.ordered.map((item) => item.name),
+        ...specialistBackendFunctions.map((item) => item.name)
+      ]
+    });
+    const specialistAgent = new RealtimeAgent({
+      name: runtimeAgent.name,
+      handoffDescription: runtimeAgent.handoffDescription ?? runtimeAgent.description ?? `Delegate specialist work to ${runtimeAgent.name}.`,
+      instructions: specialistInstructions,
+      tools: [specialistFunctionTools.executeFunctionTool]
+    });
+    specialistAgents.push(specialistAgent);
+    specialistLines.push(
+      `- ${runtimeAgent.name}: ${runtimeAgent.description ?? runtimeAgent.handoffDescription ?? "Specialist agent available by delegation."}`
+    );
+  }
   const instructions = [
-    options.baseInstructions ?? "You are a voice assistant embedded in a web app.",
+    primaryAgentConfig?.instructions ?? options.baseInstructions ?? "You are the main NAVAI voice agent embedded in a web app.",
     "Allowed routes:",
     ...routeLines,
     "Allowed app functions:",
     ...functionLines,
+    "Available specialist agents:",
+    ...specialistLines.length > 0 ? specialistLines : ["- none"],
     "Rules:",
     "- If user asks to go/open a section, always call navigate_to.",
-    "- If user asks to run an internal action, call execute_app_function or the matching direct function tool.",
+    "- If user asks to run an internal action that belongs to you, call execute_app_function or the matching direct function tool.",
+    "- If the task clearly belongs to a specialist agent, hand off to that specialist agent.",
+    "- Food recommendations, fast food, hamburgers, pizza, tacos, snacks, and meal suggestions belong to the food specialist.",
     "- Always include payload in execute_app_function. Use null when no arguments are needed.",
     "- For execute_app_function, pass arguments using payload.args (array).",
     "- For class methods, pass payload.constructorArgs and payload.methodArgs.",
@@ -412,11 +553,23 @@ async function buildNavaiAgent(options) {
     "- If destination/action is unclear, ask a brief clarifying question."
   ].join("\n");
   const agent = new RealtimeAgent({
-    name: options.agentName ?? "Navai Voice Agent",
+    name: primaryAgentConfig?.name ?? options.agentName ?? "Navai Voice Agent",
     instructions,
-    tools: [navigateTool, executeFunctionTool, ...directFunctionTools]
+    handoffs: specialistAgents,
+    tools: [
+      navigateTool,
+      primaryFunctionTools.executeFunctionTool,
+      ...primaryFunctionTools.directFunctionTools
+    ]
+  });
+  debugLog("created primary agent", {
+    name: primaryAgentConfig?.name ?? options.agentName ?? "Navai Voice Agent",
+    primaryAgentKey: primaryAgentConfig?.key ?? null,
+    directFunctions: functionsRegistry.ordered.map((item) => item.name),
+    backendFunctions: backendFunctionsOrdered.map((item) => item.name),
+    specialistDelegates: configuredAgents.filter((runtimeAgent) => runtimeAgent.key !== primaryAgentConfig?.key).map((runtimeAgent) => runtimeAgent.key)
   });
-  return { agent, warnings: [...functionsRegistry.warnings, ...backendWarnings, ...aliasWarnings] };
+  return { agent, warnings: aggregatedWarnings };
 }
 
 // src/backend.ts
@@ -539,6 +692,7 @@ function createNavaiBackendClient(options = {}) {
 // src/runtime.ts
 var ROUTES_ENV_KEYS = ["NAVAI_ROUTES_FILE"];
 var FUNCTIONS_ENV_KEYS = ["NAVAI_FUNCTIONS_FOLDERS"];
+var AGENTS_ENV_KEYS = ["NAVAI_AGENTS_FOLDERS"];
 var MODEL_ENV_KEYS = ["NAVAI_REALTIME_MODEL"];
 async function resolveNavaiFrontendRuntimeConfig(options) {
   const warnings = [];
@@ -548,6 +702,7 @@ async function resolveNavaiFrontendRuntimeConfig(options) {
   const defaultFunctionsFolder = options.defaultFunctionsFolder ?? "src/ai/functions-modules";
   const routesFile = readOptional2(options.routesFile) ?? readFirstOptionalEnv(options.env, ROUTES_ENV_KEYS) ?? defaultRoutesFile;
   const functionsFolders = readOptional2(options.functionsFolders) ?? readFirstOptionalEnv(options.env, FUNCTIONS_ENV_KEYS) ?? defaultFunctionsFolder;
+  const agentsFolders = readOptional2(options.agentsFolders) ?? readFirstOptionalEnv(options.env, AGENTS_ENV_KEYS);
   const modelOverride = readOptional2(options.modelOverride) ?? readFirstOptionalEnv(options.env, MODEL_ENV_KEYS);
   const routes = await resolveRoutes({
     routesFile,
@@ -559,12 +714,23 @@ async function resolveNavaiFrontendRuntimeConfig(options) {
   const functionModuleLoaders = resolveFunctionModuleLoaders({
     indexedLoaders,
     functionsFolders,
+    agentsFolders,
     defaultFunctionsFolder,
     warnings
   });
+  const agents = await resolveRuntimeAgents({
+    indexedLoaders,
+    functionModuleLoaders,
+    functionsFolders,
+    agentsFolders,
+    defaultFunctionsFolder
+  });
+  const primaryAgentKey = agents.find((agent) => agent.isPrimary)?.key;
   return {
     routes,
     functionModuleLoaders,
+    agents,
+    primaryAgentKey,
     modelOverride,
     warnings
   };
@@ -600,10 +766,11 @@ async function resolveRoutes(input) {
 }
 function resolveFunctionModuleLoaders(input) {
   const configuredTokens = input.functionsFolders.split(",").map((value) => value.trim()).filter(Boolean);
+  const agentFolders = parseCsvList(input.agentsFolders);
   const tokens = configuredTokens.length > 0 ? configuredTokens : [input.defaultFunctionsFolder];
-  const matchers = tokens.map((token) => createPathMatcher(token));
+  const matchers = tokens.map((token) => createPathMatcher(token, agentFolders));
   const matchedEntries = input.indexedLoaders.filter(
-    (entry) => !entry.normalizedPath.endsWith(".d.ts") && !entry.normalizedPath.startsWith("src/node_modules/") && matchers.some((matcher) => matcher(entry.normalizedPath))
+    (entry) => !entry.normalizedPath.endsWith(".d.ts") && !entry.normalizedPath.startsWith("src/node_modules/") && !isAgentConfigPath(entry.normalizedPath) && matchers.some((matcher) => matcher(entry.normalizedPath))
   );
   if (matchedEntries.length > 0) {
     return Object.fromEntries(matchedEntries.map((entry) => [entry.rawPath, entry.load]));
@@ -613,9 +780,9 @@ function resolveFunctionModuleLoaders(input) {
       `[navai] NAVAI_FUNCTIONS_FOLDERS did not match any module: "${input.functionsFolders}". Falling back to "${input.defaultFunctionsFolder}".`
     );
   }
-  const fallbackMatcher = createPathMatcher(input.defaultFunctionsFolder);
+  const fallbackMatcherWithAgents = createPathMatcher(input.defaultFunctionsFolder, agentFolders);
   const fallbackEntries = input.indexedLoaders.filter(
-    (entry) => !entry.normalizedPath.endsWith(".d.ts") && !entry.normalizedPath.startsWith("src/node_modules/") && fallbackMatcher(entry.normalizedPath)
+    (entry) => !entry.normalizedPath.endsWith(".d.ts") && !entry.normalizedPath.startsWith("src/node_modules/") && !isAgentConfigPath(entry.normalizedPath) && fallbackMatcherWithAgents(entry.normalizedPath)
   );
   return Object.fromEntries(fallbackEntries.map((entry) => [entry.rawPath, entry.load]));
 }
@@ -658,7 +825,7 @@ function buildModuleCandidates(inputPath) {
   }
   return [srcPrefixed, `${srcPrefixed}.ts`, `${srcPrefixed}.js`, `${srcPrefixed}/index.ts`, `${srcPrefixed}/index.js`];
 }
-function createPathMatcher(input) {
+function createPathMatcher(input, agentFolders = []) {
   const raw = normalizePath(input);
   if (!raw) {
     return () => false;
@@ -676,8 +843,141 @@ function createPathMatcher(input) {
     return (path) => path === normalized;
   }
   const base = normalized.replace(/\/+$/, "");
+  const normalizedAgents = agentFolders.map(normalizePathSegment).filter(Boolean);
+  if (normalizedAgents.length > 0) {
+    return (path) => {
+      if (!path.startsWith(`${base}/`)) {
+        return false;
+      }
+      const suffix = path.slice(base.length + 1);
+      const firstSegment = suffix.split("/", 1)[0] ?? "";
+      return normalizedAgents.includes(firstSegment);
+    };
+  }
   return (path) => path === base || path.startsWith(`${base}/`);
 }
+async function resolveRuntimeAgents(input) {
+  const configuredAgents = parseCsvList(input.agentsFolders);
+  if (configuredAgents.length === 0) {
+    return [];
+  }
+  const loaderByPath = new Map(input.indexedLoaders.map((entry) => [entry.normalizedPath, entry]));
+  const baseDirectories = resolveAgentBaseDirectories(input.functionsFolders, input.defaultFunctionsFolder);
+  const groupedLoaders = /* @__PURE__ */ new Map();
+  for (const [rawPath, load] of Object.entries(input.functionModuleLoaders)) {
+    const agentKey = extractAgentKeyFromPath(rawPath, baseDirectories, configuredAgents);
+    if (!agentKey) {
+      continue;
+    }
+    const current = groupedLoaders.get(agentKey) ?? {};
+    current[rawPath] = load;
+    groupedLoaders.set(agentKey, current);
+  }
+  const configuredPrimaryKey = configuredAgents[0];
+  const agents = [];
+  for (const agentKey of configuredAgents) {
+    const functionLoaders = groupedLoaders.get(agentKey);
+    if (!functionLoaders || Object.keys(functionLoaders).length === 0) {
+      continue;
+    }
+    const config = await loadAgentModuleConfig(agentKey, baseDirectories, loaderByPath);
+    agents.push({
+      key: config.key?.trim() || agentKey,
+      name: readOptional2(config.name) ?? humanizeAgentKey(agentKey),
+      description: readOptional2(config.description),
+      handoffDescription: readOptional2(config.handoffDescription) ?? readOptional2(config.description),
+      instructions: readOptional2(config.instructions),
+      isPrimary: config.isPrimary === true || agentKey === configuredPrimaryKey,
+      functionModuleLoaders: functionLoaders
+    });
+  }
+  if (agents.filter((agent) => agent.isPrimary).length === 0 && agents[0]) {
+    agents[0].isPrimary = true;
+  }
+  if (agents.filter((agent) => agent.isPrimary).length > 1) {
+    let primaryAssigned = false;
+    for (const agent of agents) {
+      if (agent.isPrimary && !primaryAssigned) {
+        primaryAssigned = true;
+        continue;
+      }
+      agent.isPrimary = false;
+    }
+  }
+  return agents;
+}
+async function loadAgentModuleConfig(agentKey, baseDirectories, loaderByPath) {
+  for (const baseDirectory of baseDirectories) {
+    const configBase = `${baseDirectory}/${agentKey}/agent.config`;
+    const matchedLoader = buildModuleCandidates(configBase).map((candidate) => loaderByPath.get(candidate)).find(Boolean);
+    if (!matchedLoader) {
+      continue;
+    }
+    try {
+      const imported = await matchedLoader.load();
+      return readAgentModuleConfig(imported);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+function readAgentModuleConfig(moduleShape) {
+  const candidate = readRecord(moduleShape.NAVAI_AGENT) ?? readRecord(moduleShape.agent) ?? readRecord(moduleShape.default) ?? {};
+  return {
+    key: readOptionalString(candidate.key),
+    name: readOptionalString(candidate.name),
+    description: readOptionalString(candidate.description),
+    handoffDescription: readOptionalString(candidate.handoffDescription),
+    instructions: readOptionalString(candidate.instructions),
+    isPrimary: candidate.isPrimary === true
+  };
+}
+function readRecord(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function readOptionalString(value) {
+  return typeof value === "string" ? readOptional2(value) : void 0;
+}
+function resolveAgentBaseDirectories(functionsFolders, defaultFunctionsFolder) {
+  const configuredTokens = functionsFolders.split(",").map((value) => value.trim()).filter(Boolean);
+  const tokens = configuredTokens.length > 0 ? configuredTokens : [defaultFunctionsFolder];
+  return [...new Set(tokens.map(toAgentBaseDirectory).filter(Boolean))];
+}
+function toAgentBaseDirectory(input) {
+  const raw = normalizePath(input);
+  if (!raw) {
+    return null;
+  }
+  const normalized = raw.startsWith("src/") ? raw : `src/${raw}`;
+  if (normalized.includes("*") || /\.[cm]?[jt]s$/.test(normalized)) {
+    return null;
+  }
+  if (normalized.endsWith("/...")) {
+    return normalized.slice(0, -4).replace(/\/+$/, "") || null;
+  }
+  return normalized.replace(/\/+$/, "") || null;
+}
+function extractAgentKeyFromPath(pathValue, baseDirectories, configuredAgents) {
+  const normalized = normalizePath(pathValue);
+  for (const baseDirectory of baseDirectories) {
+    if (!normalized.startsWith(`${baseDirectory}/`)) {
+      continue;
+    }
+    const suffix = normalized.slice(baseDirectory.length + 1);
+    const firstSegment = suffix.split("/", 1)[0] ?? "";
+    if (configuredAgents.includes(firstSegment)) {
+      return firstSegment;
+    }
+  }
+  return void 0;
+}
+function humanizeAgentKey(value) {
+  return value.split(/[_-]+/g).filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join(" ");
+}
+function isAgentConfigPath(pathValue) {
+  return /\/agent\.config\.[cm]?[jt]s$/i.test(pathValue);
+}
 function globToRegExp(pattern) {
   const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
   const wildcardSafe = escaped.replace(/\*\*/g, "___DOUBLE_STAR___");
@@ -688,6 +988,12 @@ function globToRegExp(pattern) {
 function normalizePath(input) {
   return input.trim().replace(/\\/g, "/").replace(/^\/+/, "").replace(/^(\.\/)+/, "").replace(/^(\.\.\/)+/, "");
 }
+function normalizePathSegment(input) {
+  return normalizePath(input).replace(/\//g, "");
+}
+function parseCsvList(input) {
+  return (input ?? "").split(",").map((value) => normalizePathSegment(value)).filter(Boolean);
+}
 function readFirstOptionalEnv(env, keys) {
   if (!env) {
     return void 0;
@@ -718,6 +1024,7 @@ function toErrorMessage3(error) {
 // src/useWebVoiceAgent.ts
 import { RealtimeSession } from "@openai/agents/realtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+var DEBUG_PREFIX2 = "[navai debug]";
 function formatError(error) {
   if (error instanceof Error) {
     return error.message;
@@ -731,6 +1038,13 @@ function emitWarnings(warnings) {
     }
   }
 }
+function debugLog2(message, details) {
+  if (details === void 0) {
+    console.log(`${DEBUG_PREFIX2} ${message}`);
+    return;
+  }
+  console.log(`${DEBUG_PREFIX2} ${message}`, details);
+}
 function useWebVoiceAgent(options) {
   const sessionRef = useRef(null);
   const attachedRealtimeSessionRef = useRef(null);
@@ -741,6 +1055,7 @@ function useWebVoiceAgent(options) {
       env: options.env,
       routesFile: options.routesFile,
       functionsFolders: options.functionsFolders,
+      agentsFolders: options.agentsFolders,
       modelOverride: options.modelOverride,
       defaultRoutesFile: options.defaultRoutesFile,
       defaultFunctionsFolder: options.defaultFunctionsFolder
@@ -749,6 +1064,7 @@ function useWebVoiceAgent(options) {
       options.defaultFunctionsFolder,
       options.defaultRoutes,
       options.defaultRoutesFile,
+      options.agentsFolders,
       options.env,
       options.functionsFolders,
       options.modelOverride,
@@ -795,6 +1111,45 @@ function useWebVoiceAgent(options) {
   const attachSessionAudioListeners = useCallback(
     (session) => {
       detachSessionAudioListeners();
+      session.on("agent_start", (_context, agent, turnInput) => {
+        debugLog2("session agent_start", {
+          agent: agent.name,
+          turnInputCount: Array.isArray(turnInput) ? turnInput.length : 0
+        });
+      });
+      session.on("agent_end", (_context, agent, output) => {
+        debugLog2("session agent_end", {
+          agent: agent.name,
+          output
+        });
+      });
+      session.on("agent_handoff", (_context, fromAgent, toAgent) => {
+        debugLog2("session agent_handoff", {
+          from: fromAgent.name,
+          to: toAgent.name
+        });
+      });
+      session.on("agent_tool_start", (_context, agent, tool2, details) => {
+        debugLog2("session agent_tool_start", {
+          agent: agent.name,
+          tool: tool2.name,
+          toolCall: details.toolCall
+        });
+      });
+      session.on("agent_tool_end", (_context, agent, tool2, result, details) => {
+        debugLog2("session agent_tool_end", {
+          agent: agent.name,
+          tool: tool2.name,
+          result,
+          toolCall: details.toolCall
+        });
+      });
+      session.on("history_added", (item) => {
+        debugLog2("session history_added", item);
+      });
+      session.on("error", (sessionError) => {
+        debugLog2("session error", sessionError);
+      });
       session.on("audio_start", handleSessionAudioStart);
       session.on("audio_stopped", handleSessionAudioStopped);
       session.on("audio_interrupted", handleSessionAudioInterrupted);
@@ -833,6 +1188,17 @@ function useWebVoiceAgent(options) {
     setAgentVoiceStateIfChanged("idle");
     try {
       const runtimeConfig = await runtimeConfigPromise;
+      debugLog2("resolved runtime config", {
+        routes: runtimeConfig.routes.map((route) => route.path),
+        functionModules: Object.keys(runtimeConfig.functionModuleLoaders),
+        agents: runtimeConfig.agents.map((agent2) => ({
+          key: agent2.key,
+          name: agent2.name,
+          isPrimary: agent2.isPrimary,
+          functionModules: Object.keys(agent2.functionModuleLoaders)
+        })),
+        warnings: runtimeConfig.warnings
+      });
       const requestPayload = runtimeConfig.modelOverride ? { model: runtimeConfig.modelOverride } : {};
       const secretPayload = await backendClient.createClientSecret(requestPayload);
       const backendFunctionsResult = await backendClient.listFunctions();
@@ -840,6 +1206,8 @@ function useWebVoiceAgent(options) {
         navigate: options.navigate,
         routes: runtimeConfig.routes,
         functionModuleLoaders: runtimeConfig.functionModuleLoaders,
+        agents: runtimeConfig.agents,
+        primaryAgentKey: runtimeConfig.primaryAgentKey,
         backendFunctions: backendFunctionsResult.functions,
         executeBackendFunction: backendClient.executeFunction
       });
@@ -855,6 +1223,7 @@ function useWebVoiceAgent(options) {
       setStatus("connected");
     } catch (startError) {
       const message = formatError(startError);
+      debugLog2("session start failed", { message, error: startError });
       setError(message);
       setStatus("error");
       setAgentVoiceStateIfChanged("idle");