@navai/voice-frontend 0.1.2 → 0.1.5

package/dist/index.js

@@ -1,3 +1,8 @@
+import {
+  Orb,
+  useNavaiVoiceOrbStyles
+} from "./chunk-KBBRQQLK.js";
+
 // src/agent.ts
 import { RealtimeAgent, tool } from "@openai/agents/realtime";
 import { z } from "zod";
@@ -242,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 = {
@@ -272,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",
@@ -370,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.",
@@ -407,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
@@ -534,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 = [];
@@ -543,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,
@@ -554,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
   };
@@ -595,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]));
@@ -608,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]));
 }
@@ -653,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;
@@ -671,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___");
@@ -683,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;
@@ -713,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;
@@ -726,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);
@@ -736,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
@@ -744,6 +1064,7 @@ function useWebVoiceAgent(options) {
       options.defaultFunctionsFolder,
       options.defaultRoutes,
       options.defaultRoutesFile,
+      options.agentsFolders,
       options.env,
       options.functionsFolders,
       options.modelOverride,
@@ -790,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);
@@ -828,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();
@@ -835,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
       });
@@ -850,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");
@@ -880,12 +1254,361 @@ function useWebVoiceAgent(options) {
     stop
   };
 }
+
+// src/orb/NavaiHeroOrb.tsx
+import { useEffect as useEffect3, useMemo as useMemo2, useState as useState3 } from "react";
+
+// src/orb/dynamic.tsx
+import { lazy, Suspense, useEffect as useEffect2, useState as useState2 } from "react";
+import { jsx } from "react/jsx-runtime";
+function dynamic(loader, options = {}) {
+  const { ssr = true, loading: LoadingComponent } = options;
+  const LazyComponent = lazy(async () => {
+    const loaded = await loader();
+    if (typeof loaded === "function") {
+      return { default: loaded };
+    }
+    return loaded;
+  });
+  function DynamicComponent(props) {
+    const [isClientReady, setIsClientReady] = useState2(ssr);
+    useEffect2(() => {
+      if (!ssr) {
+        setIsClientReady(true);
+      }
+    }, [ssr]);
+    if (!isClientReady) {
+      return null;
+    }
+    const fallback = LoadingComponent ? /* @__PURE__ */ jsx(LoadingComponent, {}) : null;
+    return /* @__PURE__ */ jsx(Suspense, { fallback, children: /* @__PURE__ */ jsx(LazyComponent, { ...props }) });
+  }
+  DynamicComponent.displayName = "DynamicComponent";
+  return DynamicComponent;
+}
+
+// src/orb/NavaiHeroOrb.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var Orb2 = dynamic(() => import("./Orb-B4OSC3XR.js"), {
+  ssr: false
+});
+var ORB_DELAY_MS_MIN = 0;
+var ORB_DELAY_MS_MAX = 6e4;
+var DEFAULT_AUTOPLAY_DELAY_MS = 9e3;
+var DEFAULT_REVEAL_DELAY_MS = 5200;
+function clampNavaiOrbDelayMs(value, fallback) {
+  const numericValue = Number.isFinite(value) ? value : fallback;
+  return Math.min(ORB_DELAY_MS_MAX, Math.max(ORB_DELAY_MS_MIN, numericValue));
+}
+function NavaiHeroOrb({
+  className = "",
+  backgroundColor = "#000000",
+  isAgentSpeaking = false,
+  hoverIntensitySpeaking = 0.66,
+  hoverIntensityIdle = 0.08,
+  revealDelayMs = DEFAULT_REVEAL_DELAY_MS,
+  autoplayDelayMs = DEFAULT_AUTOPLAY_DELAY_MS
+}) {
+  useNavaiVoiceOrbStyles();
+  const resolvedRevealDelayMs = clampNavaiOrbDelayMs(revealDelayMs, DEFAULT_REVEAL_DELAY_MS);
+  const resolvedAutoplayDelayMs = clampNavaiOrbDelayMs(autoplayDelayMs, DEFAULT_AUTOPLAY_DELAY_MS);
+  const [isOrbReady, setIsOrbReady] = useState3(resolvedRevealDelayMs === 0);
+  const [isOrbAutoAnimating, setIsOrbAutoAnimating] = useState3(resolvedAutoplayDelayMs === 0);
+  useEffect3(() => {
+    if (typeof window === "undefined" || resolvedRevealDelayMs === 0) {
+      return;
+    }
+    const revealOrb = () => setIsOrbReady(true);
+    window.addEventListener("pointerdown", revealOrb, { passive: true, once: true });
+    window.addEventListener("touchstart", revealOrb, { passive: true, once: true });
+    window.addEventListener("keydown", revealOrb, { once: true });
+    const timeoutId = window.setTimeout(revealOrb, resolvedRevealDelayMs);
+    return () => {
+      window.removeEventListener("pointerdown", revealOrb);
+      window.removeEventListener("touchstart", revealOrb);
+      window.removeEventListener("keydown", revealOrb);
+      window.clearTimeout(timeoutId);
+    };
+  }, [resolvedRevealDelayMs]);
+  useEffect3(() => {
+    if (typeof window === "undefined" || resolvedAutoplayDelayMs === 0) {
+      return;
+    }
+    let started = false;
+    const startOrbAnimation = () => {
+      if (started) {
+        return;
+      }
+      started = true;
+      setIsOrbAutoAnimating(true);
+    };
+    if (navigator.userActivation?.hasBeenActive) {
+      startOrbAnimation();
+    }
+    window.addEventListener("pointerdown", startOrbAnimation, { passive: true, once: true });
+    window.addEventListener("touchstart", startOrbAnimation, { passive: true, once: true });
+    window.addEventListener("keydown", startOrbAnimation, { once: true });
+    const timeoutId = window.setTimeout(startOrbAnimation, resolvedAutoplayDelayMs);
+    return () => {
+      window.removeEventListener("pointerdown", startOrbAnimation);
+      window.removeEventListener("touchstart", startOrbAnimation);
+      window.removeEventListener("keydown", startOrbAnimation);
+      window.clearTimeout(timeoutId);
+    };
+  }, [resolvedAutoplayDelayMs]);
+  const orbHoverIntensity = useMemo2(() => {
+    return isAgentSpeaking ? hoverIntensitySpeaking : hoverIntensityIdle;
+  }, [hoverIntensityIdle, hoverIntensitySpeaking, isAgentSpeaking]);
+  if (!isOrbReady) {
+    return null;
+  }
+  return /* @__PURE__ */ jsx2("div", { className: ["navai-voice-orb-hero", className].filter(Boolean).join(" "), children: /* @__PURE__ */ jsx2(
+    Orb2,
+    {
+      hoverIntensity: orbHoverIntensity,
+      rotateOnHover: true,
+      forceHoverState: isAgentSpeaking,
+      enablePointerHover: false,
+      animate: isAgentSpeaking || isOrbAutoAnimating,
+      backgroundColor
+    }
+  ) });
+}
+
+// src/orb/NavaiMiniOrbDock.tsx
+import { jsx as jsx3, jsxs } from "react/jsx-runtime";
+var Orb3 = dynamic(() => import("./Orb-B4OSC3XR.js"), {
+  ssr: false
+});
+function NavaiMiniOrbDock({
+  className = "",
+  style,
+  themeMode = "dark",
+  placement = "bottom-right",
+  isActive = false,
+  isConnected = false,
+  isDisabled = false,
+  isAgentSpeaking = false,
+  animateOrb = true,
+  backgroundColor = "#060914",
+  buttonAriaLabel,
+  buttonIcon,
+  buttonType = "button",
+  onButtonClick,
+  statusMessage = "",
+  isError = false,
+  ariaMessage = ""
+}) {
+  useNavaiVoiceOrbStyles();
+  const dockClassName = ["navai-voice-orb-dock", `is-${placement}`, themeMode === "light" ? "is-light" : "", className].filter(Boolean).join(" ");
+  const shouldHighlightOrb = isAgentSpeaking || isActive;
+  const orbHoverIntensity = isAgentSpeaking ? 0.66 : 0.08;
+  return /* @__PURE__ */ jsxs("aside", { className: dockClassName, style, children: [
+    /* @__PURE__ */ jsxs("div", { className: "navai-voice-orb-wrap", children: [
+      /* @__PURE__ */ jsx3("div", { className: ["navai-voice-orb-surface", shouldHighlightOrb ? "is-highlighted" : ""].filter(Boolean).join(" "), children: /* @__PURE__ */ jsx3(
+        Orb3,
+        {
+          hoverIntensity: orbHoverIntensity,
+          rotateOnHover: true,
+          forceHoverState: isAgentSpeaking,
+          enablePointerHover: false,
+          animate: animateOrb,
+          backgroundColor
+        }
+      ) }),
+      /* @__PURE__ */ jsx3("div", { className: ["navai-voice-orb-button-shell", isConnected ? "is-active" : ""].filter(Boolean).join(" "), children: /* @__PURE__ */ jsx3(
+        "button",
+        {
+          type: buttonType,
+          className: [
+            "navai-voice-orb-button",
+            isConnected ? "is-active" : "",
+            isActive && !isConnected ? "is-connecting" : ""
+          ].filter(Boolean).join(" "),
+          onClick: onButtonClick,
+          disabled: isDisabled,
+          "aria-label": buttonAriaLabel,
+          children: buttonIcon
+        }
+      ) })
+    ] }),
+    statusMessage ? /* @__PURE__ */ jsx3("p", { className: ["navai-voice-orb-status", isError ? "is-error" : ""].filter(Boolean).join(" "), role: "status", children: statusMessage }) : null,
+    /* @__PURE__ */ jsx3("span", { className: "navai-voice-orb-live", "aria-live": "polite", children: ariaMessage })
+  ] });
+}
+
+// src/orb/NavaiVoiceHeroOrb.tsx
+import { useEffect as useEffect4 } from "react";
+
+// src/orb/NavaiVoiceOrbDock.tsx
+import { useCallback as useCallback2, useMemo as useMemo3 } from "react";
+
+// src/orb/NavaiVoiceOrbDockMicIcon.tsx
+import { jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
+function NavaiVoiceOrbDockMicIcon({
+  isActive = false,
+  size = 20
+}) {
+  return /* @__PURE__ */ jsxs2(
+    "svg",
+    {
+      width: size,
+      height: size,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      className: ["navai-voice-orb-icon", isActive ? "is-pulsing" : ""].filter(Boolean).join(" "),
+      children: [
+        /* @__PURE__ */ jsx4("path", { d: "M12 3a3 3 0 0 0-3 3v6a3 3 0 1 0 6 0V6a3 3 0 0 0-3-3Z" }),
+        /* @__PURE__ */ jsx4("path", { d: "M19 10v2a7 7 0 1 1-14 0v-2" }),
+        /* @__PURE__ */ jsx4("path", { d: "M12 19v3" })
+      ]
+    }
+  );
+}
+
+// src/orb/NavaiVoiceOrbDockSpinnerIcon.tsx
+import { jsx as jsx5 } from "react/jsx-runtime";
+function NavaiVoiceOrbDockSpinnerIcon({
+  size = 20
+}) {
+  const style = {
+    width: size,
+    height: size
+  };
+  return /* @__PURE__ */ jsx5("span", { "aria-hidden": "true", className: "navai-voice-orb-spinner", style });
+}
+
+// src/orb/NavaiVoiceOrbDock.tsx
+import { jsx as jsx6 } from "react/jsx-runtime";
+var DEFAULT_MESSAGES = {
+  ariaStart: "Activate NAVAI voice",
+  ariaStop: "Deactivate NAVAI voice",
+  idle: "NAVAI ready to start.",
+  connecting: "Connecting NAVAI voice...",
+  listening: "NAVAI is listening.",
+  speaking: "NAVAI is speaking.",
+  errorPrefix: "NAVAI error"
+};
+function resolveNavaiVoiceOrbRuntimeSnapshot(agent) {
+  return {
+    status: agent.status,
+    agentVoiceState: agent.agentVoiceState,
+    isAgentSpeaking: agent.isAgentSpeaking,
+    error: agent.error
+  };
+}
+function resolveStatusMessage(runtimeSnapshot, messages) {
+  if (runtimeSnapshot.error) {
+    return `${messages.errorPrefix}: ${runtimeSnapshot.error}`;
+  }
+  if (runtimeSnapshot.isAgentSpeaking) {
+    return messages.speaking;
+  }
+  if (runtimeSnapshot.status === "connecting") {
+    return messages.connecting;
+  }
+  if (runtimeSnapshot.status === "connected") {
+    return messages.listening;
+  }
+  return messages.idle;
+}
+function NavaiVoiceOrbDock({
+  agent,
+  className,
+  style,
+  themeMode = "dark",
+  placement = "bottom-right",
+  backgroundColorLight = "#f4f6fb",
+  backgroundColorDark = "#060914",
+  showStatus = true,
+  messages
+}) {
+  const resolvedMessages = useMemo3(() => ({ ...DEFAULT_MESSAGES, ...messages }), [messages]);
+  const runtimeSnapshot = useMemo3(() => resolveNavaiVoiceOrbRuntimeSnapshot(agent), [agent]);
+  const statusMessage = showStatus ? resolveStatusMessage(runtimeSnapshot, resolvedMessages) : "";
+  const isError = runtimeSnapshot.status === "error" || Boolean(runtimeSnapshot.error);
+  const isConnecting = runtimeSnapshot.status === "connecting";
+  const isActive = runtimeSnapshot.status === "connecting" || runtimeSnapshot.status === "connected";
+  const isDisabled = agent.isConnecting;
+  const shouldAnimateOrb = runtimeSnapshot.status !== "error";
+  const handleToggle = useCallback2(() => {
+    if (agent.isConnecting) {
+      return;
+    }
+    if (agent.isConnected) {
+      agent.stop();
+      return;
+    }
+    void agent.start();
+  }, [agent]);
+  return /* @__PURE__ */ jsx6(
+    NavaiMiniOrbDock,
+    {
+      className,
+      style,
+      themeMode,
+      placement,
+      isActive,
+      isConnected: agent.isConnected,
+      isDisabled,
+      isAgentSpeaking: agent.isAgentSpeaking,
+      animateOrb: shouldAnimateOrb,
+      backgroundColor: themeMode === "light" ? backgroundColorLight : backgroundColorDark,
+      buttonAriaLabel: isConnecting ? resolvedMessages.connecting : agent.isConnected ? resolvedMessages.ariaStop : resolvedMessages.ariaStart,
+      buttonIcon: isConnecting ? /* @__PURE__ */ jsx6(NavaiVoiceOrbDockSpinnerIcon, {}) : /* @__PURE__ */ jsx6(NavaiVoiceOrbDockMicIcon, { isActive: agent.isConnected || agent.isAgentSpeaking }),
+      onButtonClick: handleToggle,
+      statusMessage,
+      isError,
+      ariaMessage: statusMessage
+    }
+  );
+}
+
+// src/orb/NavaiVoiceHeroOrb.tsx
+import { jsx as jsx7 } from "react/jsx-runtime";
+function NavaiVoiceHeroOrb({
+  agent,
+  themeMode = "dark",
+  backgroundColorLight = "#ffffff",
+  backgroundColorDark = "#000000",
+  onRuntimeSnapshotChange,
+  ...orbProps
+}) {
+  const runtimeSnapshot = resolveNavaiVoiceOrbRuntimeSnapshot(agent);
+  useEffect4(() => {
+    if (typeof onRuntimeSnapshotChange === "function") {
+      onRuntimeSnapshotChange(runtimeSnapshot);
+    }
+  }, [onRuntimeSnapshotChange, runtimeSnapshot]);
+  return /* @__PURE__ */ jsx7(
+    NavaiHeroOrb,
+    {
+      ...orbProps,
+      isAgentSpeaking: runtimeSnapshot.isAgentSpeaking,
+      backgroundColor: themeMode === "light" ? backgroundColorLight : backgroundColorDark,
+      className: themeMode === "light" ? "is-light" : ""
+    }
+  );
+}
 export {
+  NavaiHeroOrb,
+  NavaiMiniOrbDock,
+  NavaiVoiceHeroOrb,
+  NavaiVoiceOrbDock,
+  NavaiVoiceOrbDockMicIcon,
+  Orb,
   buildNavaiAgent,
+  clampNavaiOrbDelayMs,
   createNavaiBackendClient,
   getNavaiRoutePromptLines,
   loadNavaiFunctions,
   resolveNavaiFrontendRuntimeConfig,
   resolveNavaiRoute,
+  resolveNavaiVoiceOrbRuntimeSnapshot,
   useWebVoiceAgent
 };