@navai/voice-frontend 0.1.0 → 0.1.2

package/dist/index.cjs

@@ -25,7 +25,8 @@ __export(index_exports, {
   getNavaiRoutePromptLines: () => getNavaiRoutePromptLines,
   loadNavaiFunctions: () => loadNavaiFunctions,
   resolveNavaiFrontendRuntimeConfig: () => resolveNavaiFrontendRuntimeConfig,
-  resolveNavaiRoute: () => resolveNavaiRoute
+  resolveNavaiRoute: () => resolveNavaiRoute,
+  useWebVoiceAgent: () => useWebVoiceAgent
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -271,6 +272,8 @@ 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}$/;
 function toErrorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -305,6 +308,76 @@ async function buildNavaiAgent(options) {
     ...functionsRegistry.ordered.map((item) => item.name),
     ...backendFunctionsOrdered.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);
+    if (frontendDefinition) {
+      try {
+        const result = await frontendDefinition.run(payload ?? {}, options);
+        return { ok: true, function_name: frontendDefinition.name, source: frontendDefinition.source, result };
+      } catch (error) {
+        return {
+          ok: false,
+          function_name: frontendDefinition.name,
+          error: "Function execution failed.",
+          details: toErrorMessage2(error)
+        };
+      }
+    }
+    const backendDefinition = backendFunctionsByName.get(requested);
+    if (!backendDefinition) {
+      return {
+        ok: false,
+        error: "Unknown or disallowed function.",
+        available_functions: availableFunctionNames
+      };
+    }
+    if (!options.executeBackendFunction) {
+      return {
+        ok: false,
+        function_name: backendDefinition.name,
+        error: "Backend function execution is not configured."
+      };
+    }
+    try {
+      const result = await options.executeBackendFunction({
+        functionName: backendDefinition.name,
+        payload: payload ?? null
+      });
+      return {
+        ok: true,
+        function_name: backendDefinition.name,
+        source: backendDefinition.source ?? "backend",
+        result
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        function_name: backendDefinition.name,
+        error: "Function execution failed.",
+        details: toErrorMessage2(error)
+      };
+    }
+  };
   const navigateTool = (0, import_realtime.tool)({
     name: "navigate_to",
     description: "Navigate to an allowed route in the current app.",
@@ -329,58 +402,20 @@ 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 }) => {
-      const requested = function_name.trim().toLowerCase();
-      const frontendDefinition = 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 };
-        } catch (error) {
-          return {
-            ok: false,
-            function_name: frontendDefinition.name,
-            error: "Function execution failed.",
-            details: toErrorMessage2(error)
-          };
-        }
-      }
-      const backendDefinition = backendFunctionsByName.get(requested);
-      if (!backendDefinition) {
-        return {
-          ok: false,
-          error: "Unknown or disallowed function.",
-          available_functions: availableFunctionNames
-        };
-      }
-      if (!options.executeBackendFunction) {
-        return {
-          ok: false,
-          function_name: backendDefinition.name,
-          error: "Backend function execution is not configured."
-        };
-      }
-      try {
-        const result = await options.executeBackendFunction({
-          functionName: backendDefinition.name,
-          payload: payload ?? null
-        });
-        return {
-          ok: true,
-          function_name: backendDefinition.name,
-          source: backendDefinition.source ?? "backend",
-          result
-        };
-      } catch (error) {
-        return {
-          ok: false,
-          function_name: backendDefinition.name,
-          error: "Function execution failed.",
-          details: toErrorMessage2(error)
-        };
-      }
-    }
+    execute: async ({ function_name, payload }) => await executeAppFunction(function_name, payload)
   });
+  const directFunctionTools = directFunctionToolNames.map(
+    (functionName) => (0, import_realtime.tool)({
+      name: functionName,
+      description: `Direct alias for execute_app_function("${functionName}").`,
+      parameters: import_zod.z.object({
+        payload: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).nullable().optional().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)
+    })
+  );
   const routeLines = getNavaiRoutePromptLines(options.routes);
   const functionLines = functionsRegistry.ordered.length + backendFunctionsOrdered.length > 0 ? [
     ...functionsRegistry.ordered.map((item) => `- ${item.name}: ${item.description}`),
@@ -396,7 +431,7 @@ async function buildNavaiAgent(options) {
     ...functionLines,
     "Rules:",
     "- If user asks to go/open a section, always call navigate_to.",
-    "- If user asks to run an internal action, always call execute_app_function.",
+    "- If user asks to run an internal action, call execute_app_function or the matching direct function tool.",
     "- 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.",
@@ -406,9 +441,9 @@ async function buildNavaiAgent(options) {
   const agent = new import_realtime.RealtimeAgent({
     name: options.agentName ?? "Navai Voice Agent",
     instructions,
-    tools: [navigateTool, executeFunctionTool]
+    tools: [navigateTool, executeFunctionTool, ...directFunctionTools]
   });
-  return { agent, warnings: [...functionsRegistry.warnings, ...backendWarnings] };
+  return { agent, warnings: [...functionsRegistry.warnings, ...backendWarnings, ...aliasWarnings] };
 }
 
 // src/backend.ts
@@ -706,6 +741,177 @@ function readOptional2(value) {
 function toErrorMessage3(error) {
   return error instanceof Error ? error.message : String(error);
 }
+
+// src/useWebVoiceAgent.ts
+var import_realtime2 = require("@openai/agents/realtime");
+var import_react = require("react");
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function emitWarnings(warnings) {
+  for (const warning of warnings) {
+    if (warning.trim().length > 0) {
+      console.warn(warning);
+    }
+  }
+}
+function useWebVoiceAgent(options) {
+  const sessionRef = (0, import_react.useRef)(null);
+  const attachedRealtimeSessionRef = (0, import_react.useRef)(null);
+  const runtimeConfigPromise = (0, import_react.useMemo)(
+    () => resolveNavaiFrontendRuntimeConfig({
+      moduleLoaders: options.moduleLoaders,
+      defaultRoutes: options.defaultRoutes,
+      env: options.env,
+      routesFile: options.routesFile,
+      functionsFolders: options.functionsFolders,
+      modelOverride: options.modelOverride,
+      defaultRoutesFile: options.defaultRoutesFile,
+      defaultFunctionsFolder: options.defaultFunctionsFolder
+    }),
+    [
+      options.defaultFunctionsFolder,
+      options.defaultRoutes,
+      options.defaultRoutesFile,
+      options.env,
+      options.functionsFolders,
+      options.modelOverride,
+      options.moduleLoaders,
+      options.routesFile
+    ]
+  );
+  const backendClient = (0, import_react.useMemo)(
+    () => createNavaiBackendClient({
+      ...options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {},
+      env: options.env
+    }),
+    [options.apiBaseUrl, options.env]
+  );
+  const [status, setStatus] = (0, import_react.useState)("idle");
+  const [agentVoiceState, setAgentVoiceState] = (0, import_react.useState)("idle");
+  const [error, setError] = (0, import_react.useState)(null);
+  const setAgentVoiceStateIfChanged = (0, import_react.useCallback)((next) => {
+    setAgentVoiceState((current) => current === next ? current : next);
+  }, []);
+  const handleSessionAudioStart = (0, import_react.useCallback)(() => {
+    setAgentVoiceStateIfChanged("speaking");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionAudioStopped = (0, import_react.useCallback)(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionAudioInterrupted = (0, import_react.useCallback)(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionError = (0, import_react.useCallback)(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const detachSessionAudioListeners = (0, import_react.useCallback)(() => {
+    const attachedSession = attachedRealtimeSessionRef.current;
+    if (!attachedSession) {
+      return;
+    }
+    attachedSession.off("audio_start", handleSessionAudioStart);
+    attachedSession.off("audio_stopped", handleSessionAudioStopped);
+    attachedSession.off("audio_interrupted", handleSessionAudioInterrupted);
+    attachedSession.off("error", handleSessionError);
+    attachedRealtimeSessionRef.current = null;
+  }, [handleSessionAudioInterrupted, handleSessionAudioStart, handleSessionAudioStopped, handleSessionError]);
+  const attachSessionAudioListeners = (0, import_react.useCallback)(
+    (session) => {
+      detachSessionAudioListeners();
+      session.on("audio_start", handleSessionAudioStart);
+      session.on("audio_stopped", handleSessionAudioStopped);
+      session.on("audio_interrupted", handleSessionAudioInterrupted);
+      session.on("error", handleSessionError);
+      attachedRealtimeSessionRef.current = session;
+    },
+    [
+      detachSessionAudioListeners,
+      handleSessionAudioInterrupted,
+      handleSessionAudioStart,
+      handleSessionAudioStopped,
+      handleSessionError
+    ]
+  );
+  const stop = (0, import_react.useCallback)(() => {
+    detachSessionAudioListeners();
+    try {
+      sessionRef.current?.close();
+    } finally {
+      sessionRef.current = null;
+      setStatus("idle");
+      setAgentVoiceStateIfChanged("idle");
+    }
+  }, [detachSessionAudioListeners, setAgentVoiceStateIfChanged]);
+  (0, import_react.useEffect)(() => {
+    return () => {
+      stop();
+    };
+  }, [stop]);
+  const start = (0, import_react.useCallback)(async () => {
+    if (status === "connecting" || status === "connected") {
+      return;
+    }
+    setError(null);
+    setStatus("connecting");
+    setAgentVoiceStateIfChanged("idle");
+    try {
+      const runtimeConfig = await runtimeConfigPromise;
+      const requestPayload = runtimeConfig.modelOverride ? { model: runtimeConfig.modelOverride } : {};
+      const secretPayload = await backendClient.createClientSecret(requestPayload);
+      const backendFunctionsResult = await backendClient.listFunctions();
+      const { agent, warnings } = await buildNavaiAgent({
+        navigate: options.navigate,
+        routes: runtimeConfig.routes,
+        functionModuleLoaders: runtimeConfig.functionModuleLoaders,
+        backendFunctions: backendFunctionsResult.functions,
+        executeBackendFunction: backendClient.executeFunction
+      });
+      emitWarnings([...runtimeConfig.warnings, ...backendFunctionsResult.warnings, ...warnings]);
+      const session = new import_realtime2.RealtimeSession(agent);
+      attachSessionAudioListeners(session);
+      if (runtimeConfig.modelOverride) {
+        await session.connect({ apiKey: secretPayload.value, model: runtimeConfig.modelOverride });
+      } else {
+        await session.connect({ apiKey: secretPayload.value });
+      }
+      sessionRef.current = session;
+      setStatus("connected");
+    } catch (startError) {
+      const message = formatError(startError);
+      setError(message);
+      setStatus("error");
+      setAgentVoiceStateIfChanged("idle");
+      detachSessionAudioListeners();
+      try {
+        sessionRef.current?.close();
+      } catch {
+      }
+      sessionRef.current = null;
+    }
+  }, [
+    attachSessionAudioListeners,
+    backendClient,
+    detachSessionAudioListeners,
+    options.navigate,
+    runtimeConfigPromise,
+    setAgentVoiceStateIfChanged,
+    status
+  ]);
+  return {
+    status,
+    agentVoiceState,
+    error,
+    isConnecting: status === "connecting",
+    isConnected: status === "connected",
+    isAgentSpeaking: agentVoiceState === "speaking",
+    start,
+    stop
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   buildNavaiAgent,
@@ -713,5 +919,6 @@ function toErrorMessage3(error) {
   getNavaiRoutePromptLines,
   loadNavaiFunctions,
   resolveNavaiFrontendRuntimeConfig,
-  resolveNavaiRoute
+  resolveNavaiRoute,
+  useWebVoiceAgent
 });

package/dist/index.d.cts

@@ -51,7 +51,7 @@ type BuildNavaiAgentResult = {
 };
 declare function buildNavaiAgent(options: BuildNavaiAgentOptions): Promise<BuildNavaiAgentResult>;
 
-type NavaiFrontendEnv$1 = Record<string, string | undefined>;
+type NavaiFrontendEnv$2 = Record<string, string | undefined>;
 type CreateClientSecretInput = {
     model?: string;
     voice?: string;
@@ -71,7 +71,7 @@ type BackendFunctionsResult = {
 };
 type CreateNavaiBackendClientOptions = {
     apiBaseUrl?: string;
-    env?: NavaiFrontendEnv$1;
+    env?: NavaiFrontendEnv$2;
     fetchImpl?: typeof fetch;
     clientSecretPath?: string;
     functionsListPath?: string;
@@ -84,11 +84,11 @@ type NavaiBackendClient = {
 };
 declare function createNavaiBackendClient(options?: CreateNavaiBackendClientOptions): NavaiBackendClient;
 
-type NavaiFrontendEnv = Record<string, unknown>;
+type NavaiFrontendEnv$1 = Record<string, unknown>;
 type ResolveNavaiFrontendRuntimeConfigOptions = {
     moduleLoaders: NavaiFunctionModuleLoaders;
     defaultRoutes: NavaiRoute[];
-    env?: NavaiFrontendEnv;
+    env?: NavaiFrontendEnv$1;
     routesFile?: string;
     functionsFolders?: string;
     modelOverride?: string;
@@ -103,4 +103,31 @@ type ResolveNavaiFrontendRuntimeConfigResult = {
 };
 declare function resolveNavaiFrontendRuntimeConfig(options: ResolveNavaiFrontendRuntimeConfigOptions): Promise<ResolveNavaiFrontendRuntimeConfigResult>;
 
-export { type BuildNavaiAgentOptions, type BuildNavaiAgentResult, type CreateNavaiBackendClientOptions, type ExecuteNavaiBackendFunction, type ExecuteNavaiBackendFunctionInput, type NavaiBackendClient, type NavaiBackendFunctionDefinition, type NavaiFunctionContext, type NavaiFunctionDefinition, type NavaiFunctionModuleLoaders, type NavaiFunctionPayload, type NavaiFunctionsRegistry, type NavaiRoute, type ResolveNavaiFrontendRuntimeConfigOptions, type ResolveNavaiFrontendRuntimeConfigResult, buildNavaiAgent, createNavaiBackendClient, getNavaiRoutePromptLines, loadNavaiFunctions, resolveNavaiFrontendRuntimeConfig, resolveNavaiRoute };
+type VoiceStatus = "idle" | "connecting" | "connected" | "error";
+type AgentVoiceState = "idle" | "speaking";
+type NavaiFrontendEnv = Record<string, string | undefined>;
+type UseWebVoiceAgentOptions = {
+    navigate: (path: string) => void;
+    moduleLoaders: NavaiFunctionModuleLoaders;
+    defaultRoutes: NavaiRoute[];
+    env?: NavaiFrontendEnv;
+    apiBaseUrl?: string;
+    routesFile?: string;
+    functionsFolders?: string;
+    modelOverride?: string;
+    defaultRoutesFile?: string;
+    defaultFunctionsFolder?: string;
+};
+type UseWebVoiceAgentResult = {
+    status: VoiceStatus;
+    agentVoiceState: AgentVoiceState;
+    error: string | null;
+    isConnecting: boolean;
+    isConnected: boolean;
+    isAgentSpeaking: boolean;
+    start: () => Promise<void>;
+    stop: () => void;
+};
+declare function useWebVoiceAgent(options: UseWebVoiceAgentOptions): UseWebVoiceAgentResult;
+
+export { type BuildNavaiAgentOptions, type BuildNavaiAgentResult, type CreateNavaiBackendClientOptions, type ExecuteNavaiBackendFunction, type ExecuteNavaiBackendFunctionInput, type NavaiBackendClient, type NavaiBackendFunctionDefinition, type NavaiFunctionContext, type NavaiFunctionDefinition, type NavaiFunctionModuleLoaders, type NavaiFunctionPayload, type NavaiFunctionsRegistry, type NavaiRoute, type ResolveNavaiFrontendRuntimeConfigOptions, type ResolveNavaiFrontendRuntimeConfigResult, type UseWebVoiceAgentOptions, type UseWebVoiceAgentResult, buildNavaiAgent, createNavaiBackendClient, getNavaiRoutePromptLines, loadNavaiFunctions, resolveNavaiFrontendRuntimeConfig, resolveNavaiRoute, useWebVoiceAgent };

package/dist/index.d.ts

@@ -51,7 +51,7 @@ type BuildNavaiAgentResult = {
 };
 declare function buildNavaiAgent(options: BuildNavaiAgentOptions): Promise<BuildNavaiAgentResult>;
 
-type NavaiFrontendEnv$1 = Record<string, string | undefined>;
+type NavaiFrontendEnv$2 = Record<string, string | undefined>;
 type CreateClientSecretInput = {
     model?: string;
     voice?: string;
@@ -71,7 +71,7 @@ type BackendFunctionsResult = {
 };
 type CreateNavaiBackendClientOptions = {
     apiBaseUrl?: string;
-    env?: NavaiFrontendEnv$1;
+    env?: NavaiFrontendEnv$2;
     fetchImpl?: typeof fetch;
     clientSecretPath?: string;
     functionsListPath?: string;
@@ -84,11 +84,11 @@ type NavaiBackendClient = {
 };
 declare function createNavaiBackendClient(options?: CreateNavaiBackendClientOptions): NavaiBackendClient;
 
-type NavaiFrontendEnv = Record<string, unknown>;
+type NavaiFrontendEnv$1 = Record<string, unknown>;
 type ResolveNavaiFrontendRuntimeConfigOptions = {
     moduleLoaders: NavaiFunctionModuleLoaders;
     defaultRoutes: NavaiRoute[];
-    env?: NavaiFrontendEnv;
+    env?: NavaiFrontendEnv$1;
     routesFile?: string;
     functionsFolders?: string;
     modelOverride?: string;
@@ -103,4 +103,31 @@ type ResolveNavaiFrontendRuntimeConfigResult = {
 };
 declare function resolveNavaiFrontendRuntimeConfig(options: ResolveNavaiFrontendRuntimeConfigOptions): Promise<ResolveNavaiFrontendRuntimeConfigResult>;
 
-export { type BuildNavaiAgentOptions, type BuildNavaiAgentResult, type CreateNavaiBackendClientOptions, type ExecuteNavaiBackendFunction, type ExecuteNavaiBackendFunctionInput, type NavaiBackendClient, type NavaiBackendFunctionDefinition, type NavaiFunctionContext, type NavaiFunctionDefinition, type NavaiFunctionModuleLoaders, type NavaiFunctionPayload, type NavaiFunctionsRegistry, type NavaiRoute, type ResolveNavaiFrontendRuntimeConfigOptions, type ResolveNavaiFrontendRuntimeConfigResult, buildNavaiAgent, createNavaiBackendClient, getNavaiRoutePromptLines, loadNavaiFunctions, resolveNavaiFrontendRuntimeConfig, resolveNavaiRoute };
+type VoiceStatus = "idle" | "connecting" | "connected" | "error";
+type AgentVoiceState = "idle" | "speaking";
+type NavaiFrontendEnv = Record<string, string | undefined>;
+type UseWebVoiceAgentOptions = {
+    navigate: (path: string) => void;
+    moduleLoaders: NavaiFunctionModuleLoaders;
+    defaultRoutes: NavaiRoute[];
+    env?: NavaiFrontendEnv;
+    apiBaseUrl?: string;
+    routesFile?: string;
+    functionsFolders?: string;
+    modelOverride?: string;
+    defaultRoutesFile?: string;
+    defaultFunctionsFolder?: string;
+};
+type UseWebVoiceAgentResult = {
+    status: VoiceStatus;
+    agentVoiceState: AgentVoiceState;
+    error: string | null;
+    isConnecting: boolean;
+    isConnected: boolean;
+    isAgentSpeaking: boolean;
+    start: () => Promise<void>;
+    stop: () => void;
+};
+declare function useWebVoiceAgent(options: UseWebVoiceAgentOptions): UseWebVoiceAgentResult;
+
+export { type BuildNavaiAgentOptions, type BuildNavaiAgentResult, type CreateNavaiBackendClientOptions, type ExecuteNavaiBackendFunction, type ExecuteNavaiBackendFunctionInput, type NavaiBackendClient, type NavaiBackendFunctionDefinition, type NavaiFunctionContext, type NavaiFunctionDefinition, type NavaiFunctionModuleLoaders, type NavaiFunctionPayload, type NavaiFunctionsRegistry, type NavaiRoute, type ResolveNavaiFrontendRuntimeConfigOptions, type ResolveNavaiFrontendRuntimeConfigResult, type UseWebVoiceAgentOptions, type UseWebVoiceAgentResult, buildNavaiAgent, createNavaiBackendClient, getNavaiRoutePromptLines, loadNavaiFunctions, resolveNavaiFrontendRuntimeConfig, resolveNavaiRoute, useWebVoiceAgent };