@navai/voice-frontend 0.1.3 → 0.1.5

package/README.en.md

@@ -32,22 +32,24 @@ HTTP client for backend routes:
 - `GET /navai/functions`
 - `POST /navai/functions/execute`
 
-2. `src/runtime.ts`
-Runtime resolver for:
-- route module selection
-- function module filtering by `NAVAI_FUNCTIONS_FOLDERS`
-- optional model override
+2. `src/runtime.ts`
+Runtime resolver for:
+- route module selection
+- function module filtering by `NAVAI_FUNCTIONS_FOLDERS`
+- agent discovery by `NAVAI_AGENTS_FOLDERS`
+- optional model override
 
 3. `src/functions.ts`
 Local function loader:
 - imports modules from generated loaders
 - converts exports into normalized callable tool definitions
 
-4. `src/agent.ts`
-Agent builder:
-- creates `RealtimeAgent`
-- injects built-in tools (`navigate_to`, `execute_app_function`)
-- optionally adds direct alias tools for each allowed function
+4. `src/agent.ts`
+Agent builder:
+- creates the primary `RealtimeAgent`
+- injects built-in tools (`navigate_to`, `execute_app_function`)
+- optionally adds direct alias tools for each allowed function
+- creates specialist agents and wires them with `handoffs`
 
 5. `src/useWebVoiceAgent.ts`
 React lifecycle wrapper:
@@ -161,16 +163,51 @@ For class methods:
 2. Env object keys.
 3. Package defaults.
 
-Keys used:
-
-- `NAVAI_ROUTES_FILE`
-- `NAVAI_FUNCTIONS_FOLDERS`
-- `NAVAI_REALTIME_MODEL`
-
-Defaults:
-
-- routes file: `src/ai/routes.ts`
-- functions folder: `src/ai/functions-modules`
+Keys used:
+
+- `NAVAI_ROUTES_FILE`
+- `NAVAI_FUNCTIONS_FOLDERS`
+- `NAVAI_AGENTS_FOLDERS`
+- `NAVAI_REALTIME_MODEL`
+
+Defaults:
+
+- routes file: `src/ai/routes.ts`
+- functions folder: `src/ai/functions-modules`
+
+Multi-agent layout:
+
+- agent root: `src/ai`
+- agents env: `NAVAI_AGENTS_FOLDERS=main,support,sales,food`
+- per-agent files live in `src/ai/<agent>/...`
+- optional per-agent config file: `src/ai/<agent>/agent.config.ts`
+- only the first level under `src/ai/` defines the agent key
+- deeper folders are optional organization for that same agent
+
+Example:
+
+```text
+src/ai/
+  main/
+    agent.config.ts
+    session/logout.fn.ts
+    support/open-help.fn.ts
+  support/
+    agent.config.ts
+    system/ai-service.ts
+  sales/
+    agent.config.ts
+    utils/math.ts
+  food/
+    agent.config.ts
+    comida_rapida/hamburguesa.ts
+```
+
+Notes:
+
+- `src/ai/main/session/logout.fn.ts` belongs to the `main` agent.
+- `src/ai/main/support/open-help.fn.ts` also belongs to the `main` agent.
+- folders like `session`, `support`, `help`, or `utils` inside an agent are optional.
 
 Path matcher formats:
 
@@ -180,10 +217,14 @@ Path matcher formats:
 - explicit file: `src/ai/functions-modules/secret.ts`
 - CSV list: `a,b,c`
 
-Fallback behavior:
-
-- if configured folders match no modules, warning is emitted.
-- resolver falls back to default functions folder.
+Fallback behavior:
+
+- if configured folders match no modules, warning is emitted.
+- resolver falls back to default functions folder.
+
+When `NAVAI_AGENTS_FOLDERS` is present and `NAVAI_FUNCTIONS_FOLDERS` points to a root such as `src/ai`, the resolver only includes modules inside `src/ai/<agent>/...` for the configured agents.
+
+For browser realtime multi-agent orchestration, `buildNavaiAgent` currently wires specialist agents with `handoffs` inside the shared `RealtimeSession`.
 
 ## Backend Client Behavior
 

package/README.es.md

@@ -32,22 +32,24 @@ Cliente HTTP para rutas backend:
 - `GET /navai/functions`
 - `POST /navai/functions/execute`
 
-2. `src/runtime.ts`
-Resolver de runtime para:
-- seleccion de modulo de rutas
-- filtrado de modulos de funciones por `NAVAI_FUNCTIONS_FOLDERS`
-- override opcional de modelo
+2. `src/runtime.ts`
+Resolver de runtime para:
+- seleccion de modulo de rutas
+- filtrado de modulos de funciones por `NAVAI_FUNCTIONS_FOLDERS`
+- descubrimiento de agentes por `NAVAI_AGENTS_FOLDERS`
+- override opcional de modelo
 
 3. `src/functions.ts`
 Loader de funciones locales:
 - importa modulos desde loaders generados
 - transforma exports en definiciones de tools normalizadas y ejecutables
 
-4. `src/agent.ts`
-Builder del agente:
-- crea `RealtimeAgent`
-- inyecta tools base (`navigate_to`, `execute_app_function`)
-- agrega aliases directos por funcion permitida cuando aplica
+4. `src/agent.ts`
+Builder del agente:
+- crea el `RealtimeAgent` principal
+- inyecta tools base (`navigate_to`, `execute_app_function`)
+- agrega aliases directos por funcion permitida cuando aplica
+- crea agentes especialistas y los conecta con `handoffs`
 
 5. `src/useWebVoiceAgent.ts`
 Wrapper de ciclo de vida React:
@@ -161,16 +163,51 @@ Prioridad de entrada en `resolveNavaiFrontendRuntimeConfig`:
 2. Claves del objeto env.
 3. Defaults del paquete.
 
-Claves usadas:
-
-- `NAVAI_ROUTES_FILE`
-- `NAVAI_FUNCTIONS_FOLDERS`
-- `NAVAI_REALTIME_MODEL`
-
-Defaults:
-
-- archivo de rutas: `src/ai/routes.ts`
-- carpeta de funciones: `src/ai/functions-modules`
+Claves usadas:
+
+- `NAVAI_ROUTES_FILE`
+- `NAVAI_FUNCTIONS_FOLDERS`
+- `NAVAI_AGENTS_FOLDERS`
+- `NAVAI_REALTIME_MODEL`
+
+Defaults:
+
+- archivo de rutas: `src/ai/routes.ts`
+- carpeta de funciones: `src/ai/functions-modules`
+
+Estructura multiagente:
+
+- raiz de agentes: `src/ai`
+- env de agentes: `NAVAI_AGENTS_FOLDERS=main,support,sales,food`
+- los archivos por agente viven en `src/ai/<agent>/...`
+- archivo opcional por agente: `src/ai/<agent>/agent.config.ts`
+- solo el primer nivel debajo de `src/ai/` define la clave del agente
+- el resto de carpetas son solo organizacion interna de ese agente
+
+Ejemplo:
+
+```text
+src/ai/
+  main/
+    agent.config.ts
+    session/logout.fn.ts
+    support/open-help.fn.ts
+  support/
+    agent.config.ts
+    system/ai-service.ts
+  sales/
+    agent.config.ts
+    utils/math.ts
+  food/
+    agent.config.ts
+    comida_rapida/hamburguesa.ts
+```
+
+Notas:
+
+- `src/ai/main/session/logout.fn.ts` pertenece al agente `main`.
+- `src/ai/main/support/open-help.fn.ts` tambien pertenece al agente `main`.
+- carpetas como `session`, `support`, `help` o `utils` dentro de un agente no son obligatorias.
 
 Formatos aceptados en matcher de rutas:
 
@@ -180,10 +217,14 @@ Formatos aceptados en matcher de rutas:
 - archivo explicito: `src/ai/functions-modules/secret.ts`
 - CSV: `a,b,c`
 
-Comportamiento fallback:
-
-- si `NAVAI_FUNCTIONS_FOLDERS` no matchea modulos, emite warning.
-- hace fallback a carpeta de funciones por defecto.
+Comportamiento fallback:
+
+- si `NAVAI_FUNCTIONS_FOLDERS` no matchea modulos, emite warning.
+- hace fallback a carpeta de funciones por defecto.
+
+Cuando `NAVAI_AGENTS_FOLDERS` esta presente y `NAVAI_FUNCTIONS_FOLDERS` apunta a una raiz como `src/ai`, el resolver solo incluye modulos dentro de `src/ai/<agent>/...` para los agentes configurados.
+
+En realtime web, `buildNavaiAgent` conecta actualmente los agentes especialistas usando `handoffs` dentro de la misma `RealtimeSession`.
 
 ## Comportamiento del Backend Client
 

package/README.md

@@ -32,22 +32,24 @@ HTTP client for backend routes:
 - `GET /navai/functions`
 - `POST /navai/functions/execute`
 
-2. `src/runtime.ts`
-Runtime resolver for:
-- route module selection
-- function module filtering by `NAVAI_FUNCTIONS_FOLDERS`
-- optional model override
+2. `src/runtime.ts`
+Runtime resolver for:
+- route module selection
+- function module filtering by `NAVAI_FUNCTIONS_FOLDERS`
+- agent discovery by `NAVAI_AGENTS_FOLDERS`
+- optional model override
 
 3. `src/functions.ts`
 Local function loader:
 - imports modules from generated loaders
 - converts exports into normalized callable tool definitions
 
-4. `src/agent.ts`
-Agent builder:
-- creates `RealtimeAgent`
-- injects built-in tools (`navigate_to`, `execute_app_function`)
-- optionally adds direct alias tools for each allowed function
+4. `src/agent.ts`
+Agent builder:
+- creates primary `RealtimeAgent`
+- injects built-in tools (`navigate_to`, `execute_app_function`)
+- optionally adds direct alias tools for each allowed function
+- creates specialist realtime agents and wires them as `handoffs`
 
 5. `src/useWebVoiceAgent.ts`
 React lifecycle wrapper:
@@ -110,10 +112,16 @@ Useful types:
 
 ## Tool Model and Behavior
 
-`buildNavaiAgent` always registers:
-
-- `navigate_to`
-- `execute_app_function`
+`buildNavaiAgent` always registers:
+
+- `navigate_to`
+- `execute_app_function`
+
+When runtime agents are available:
+
+- the first configured or explicit primary agent becomes the main realtime agent.
+- other configured agents become specialist `RealtimeAgent` instances.
+- the main agent delegates with `handoffs`, following the OpenAI Agents SDK multi-agent model.
 
 Optional direct alias tools:
 
@@ -161,16 +169,58 @@ For class methods:
 2. Env object keys.
 3. Package defaults.
 
-Keys used:
-
-- `NAVAI_ROUTES_FILE`
-- `NAVAI_FUNCTIONS_FOLDERS`
-- `NAVAI_REALTIME_MODEL`
-
-Defaults:
-
-- routes file: `src/ai/routes.ts`
-- functions folder: `src/ai/functions-modules`
+Keys used:
+
+- `NAVAI_ROUTES_FILE`
+- `NAVAI_FUNCTIONS_FOLDERS`
+- `NAVAI_AGENTS_FOLDERS`
+- `NAVAI_REALTIME_MODEL`
+
+Defaults:
+
+- routes file: `src/ai/routes.ts`
+- functions folder: `src/ai/functions-modules`
+
+Multi-agent layout:
+
+- agent root: `src/ai`
+- agents env: `NAVAI_AGENTS_FOLDERS=main,support,sales,food`
+- per-agent files live in `src/ai/<agent>/...`
+- optional per-agent config file: `src/ai/<agent>/agent.config.ts`
+- only the first level under `src/ai/` defines the agent key
+- deeper folders are optional organization for that same agent
+
+Multi-agent layout:
+
+- agent root: `src/ai`
+- agents env: `NAVAI_AGENTS_FOLDERS=main,support,sales`
+- per-agent files live in `src/ai/<agent>/...`
+- optional per-agent config file: `src/ai/<agent>/agent.config.ts`
+
+Example:
+
+```text
+src/ai/
+  main/
+    agent.config.ts
+    session/logout.fn.ts
+    support/open-help.fn.ts
+  support/
+    agent.config.ts
+    system/ai-service.ts
+  sales/
+    agent.config.ts
+    utils/math.ts
+  food/
+    agent.config.ts
+    comida_rapida/hamburguesa.ts
+```
+
+Notes:
+
+- `src/ai/main/session/logout.fn.ts` belongs to the `main` agent.
+- `src/ai/main/support/open-help.fn.ts` also belongs to the `main` agent.
+- folders like `session`, `support`, `help`, or `utils` inside an agent are optional.
 
 Path matcher formats:
 
@@ -180,10 +230,14 @@ Path matcher formats:
 - explicit file: `src/ai/functions-modules/secret.ts`
 - CSV list: `a,b,c`
 
-Fallback behavior:
-
-- if configured folders match no modules, warning is emitted.
-- resolver falls back to default functions folder.
+Fallback behavior:
+
+- if configured folders match no modules, warning is emitted.
+- resolver falls back to default functions folder.
+
+When `NAVAI_AGENTS_FOLDERS` is present and `NAVAI_FUNCTIONS_FOLDERS` points to a folder root such as `src/ai`, the resolver only includes modules inside `src/ai/<agent>/...` for the configured agents.
+
+For browser realtime multi-agent orchestration, `buildNavaiAgent` currently wires specialist agents with `handoffs` inside the shared `RealtimeSession`.
 
 ## Backend Client Behavior
 

package/bin/generate-web-module-loaders.mjs

@@ -39,9 +39,13 @@ async function main() {
   const configuredFunctionsFolders =
     readOptional(process.env.NAVAI_FUNCTIONS_FOLDERS) ??
     readOptional(envFileValues.NAVAI_FUNCTIONS_FOLDERS);
+  const configuredAgentsFolders =
+    readOptional(process.env.NAVAI_AGENTS_FOLDERS) ??
+    readOptional(envFileValues.NAVAI_AGENTS_FOLDERS);
   const configuredRoutesFile =
     readOptional(process.env.NAVAI_ROUTES_FILE) ?? readOptional(envFileValues.NAVAI_ROUTES_FILE);
   const functionsFolders = configuredFunctionsFolders ?? defaultFunctionsFolder;
+  const agentTokens = parseCsvList(configuredAgentsFolders);
   const routesFile = configuredRoutesFile ?? defaultRoutesFile;
 
   const defaultRoutesModuleFile = await resolveModulePathFromFs(defaultRoutesFile, projectRoot);
@@ -52,7 +56,7 @@ async function main() {
     .filter(Boolean);
   const functionTokens =
     configuredFunctionTokens.length > 0 ? configuredFunctionTokens : [defaultFunctionsFolder];
-  const functionMatchers = functionTokens.map((token) => createPathMatcher(token));
+  const functionMatchers = functionTokens.map((token) => createPathMatcher(token, agentTokens));
 
   let selectedFunctionFiles = await collectFilesForTokens({
     tokens: functionTokens,
@@ -66,7 +70,7 @@ async function main() {
   });
 
   if (selectedFunctionFiles.length === 0 && configuredFunctionTokens.length > 0) {
-    const fallbackMatcher = createPathMatcher(defaultFunctionsFolder);
+    const fallbackMatcher = createPathMatcher(defaultFunctionsFolder, agentTokens);
     selectedFunctionFiles = await collectFilesForTokens({
       tokens: [defaultFunctionsFolder],
       projectRoot,
@@ -423,7 +427,7 @@ function globToRegExp(pattern) {
   return new RegExp(`^${output}$`);
 }
 
-function createPathMatcher(input) {
+function createPathMatcher(input, agentFolders = []) {
   const normalized = ensureSrcPrefix(input);
   if (!normalized) {
     return () => false;
@@ -444,9 +448,33 @@ function createPathMatcher(input) {
   }
 
   const base = normalized.replace(/\/+$/, "");
+  const normalizedAgents = agentFolders.map(normalizePathSegment).filter(Boolean);
+  if (normalizedAgents.length > 0) {
+    return (candidatePath) => {
+      if (!candidatePath.startsWith(`${base}/`)) {
+        return false;
+      }
+
+      const suffix = candidatePath.slice(base.length + 1);
+      const firstSegment = suffix.split("/", 1)[0] ?? "";
+      return normalizedAgents.includes(firstSegment);
+    };
+  }
+
   return (candidatePath) => candidatePath === base || candidatePath.startsWith(`${base}/`);
 }
 
+function normalizePathSegment(input) {
+  return normalizeSourcePath(input).replace(/\//g, "");
+}
+
+function parseCsvList(input) {
+  return (input ?? "")
+    .split(",")
+    .map((value) => normalizePathSegment(value))
+    .filter(Boolean);
+}
+
 function buildModuleCandidates(inputPath) {
   const normalized = ensureSrcPrefix(inputPath);
   if (!normalized) {