@alia.onl/sdk 8.0.0 → 10.0.1

package/src/hooks/useSpeechToText.ts

@@ -1,12 +1,14 @@
 import { useState, useCallback, useRef, useEffect } from 'react';
 import { create } from 'zustand';
 import {
+  chooseSpeechRecognizer,
   isSpeechRecognitionAvailable,
   requestSpeechRecognitionPermission,
   startSpeechRecognition,
 } from '../lib/speech-recognition';
 import type { SpeechRecognitionSession } from '../lib/speech-recognition-types';
-import { speechFailureMessage } from '../lib/speech-messages';
+import type { SpeechRecognizerChoice } from '../lib/speech-recognition-types';
+import { speechFailureCode, VOICE_ERROR_MESSAGES, type VoiceErrorCode } from '../lib/speech-messages';
 import { defaultSpeechLanguage } from '../lib/speech-language';
 
 // ============== OPTIONS ==============
@@ -68,7 +70,7 @@ export function useSpeechToText(options: UseSTTOptions = {}) {
   const lang = options.lang ?? defaultSpeechLanguage();
 
   const [state, setState] = useState<STTState>('idle');
-  const [error, setError] = useState<string | null>(null);
+  const [errorCode, setErrorCode] = useState<VoiceErrorCode | null>(null);
   const [isSupported] = useState(isSpeechRecognitionAvailable);
 
   const stateRef = useRef<STTState>('idle');
@@ -78,10 +80,17 @@ export function useSpeechToText(options: UseSTTOptions = {}) {
   /** Text from the live session. */
   const currentTextRef = useRef('');
   const restartsRef = useRef(0);
+  /** The recognizer and tag this dictation uses, chosen once when it starts. */
+  const recognizerRef = useRef<{ lang: string; service?: string; silent: boolean }>({ lang, silent: false });
   const endWaitersRef = useRef<Array<() => void>>([]);
   const lastMeteringRef = useRef(0);
   const mountedRef = useRef(true);
 
+  /** What went wrong, as a code; `null` clears it. */
+  const report = useCallback((code: VoiceErrorCode | null) => {
+    if (mountedRef.current) setErrorCode(code);
+  }, []);
+
   const setPhase = useCallback((next: STTState) => {
     stateRef.current = next;
     if (mountedRef.current) setState(next);
@@ -102,8 +111,9 @@ export function useSpeechToText(options: UseSTTOptions = {}) {
   const openSession = useCallback(() => {
     currentTextRef.current = '';
     let failed = false;
+    const recognizer = recognizerRef.current;
     sessionRef.current = startSpeechRecognition(
-      { lang },
+      { lang: recognizer.lang, service: recognizer.service },
       {
         onResult: ({ transcript }) => {
           currentTextRef.current = transcript;
@@ -116,10 +126,13 @@ export function useSpeechToText(options: UseSTTOptions = {}) {
           useSTTStore.getState().setMetering(level);
         },
         onError: (failure) => {
-          const message = speechFailureMessage(failure);
-          if (message === null) return;
+          const code = speechFailureCode(failure);
+          if (code === null) return;
           failed = true;
-          if (mountedRef.current) setError(message);
+          // Every recognizer on the device named no language, and the
+          // default refused this one: it is the device that cannot recognize
+          // speech, not the language that is wrong.
+          report(code === 'speech-language' && recognizer.silent ? 'speech-unsupported' : code);
         },
         onEnd: () => {
           sessionRef.current = null;
@@ -141,14 +154,14 @@ export function useSpeechToText(options: UseSTTOptions = {}) {
         },
       },
     );
-  }, [lang, setPhase]);
+  }, [report, setPhase]);
 
   const startRecording = useCallback(async () => {
     if (stateRef.current !== 'idle') return;
-    setError(null);
+    report(null);
 
     if (!isSpeechRecognitionAvailable()) {
-      setError(speechFailureMessage({ code: 'unsupported' }));
+      report('speech-unsupported');
       return;
     }
 
@@ -157,16 +170,25 @@ export function useSpeechToText(options: UseSTTOptions = {}) {
     const refusal = await requestSpeechRecognitionPermission();
     if ((stateRef.current as STTState) !== 'recording') return; // cancelled while asking
     if (refusal !== null) {
-      setError(speechFailureMessage(refusal));
+      report(speechFailureCode(refusal));
+      setPhase('idle');
+      return;
+    }
+
+    const choice: SpeechRecognizerChoice = await chooseSpeechRecognizer(lang);
+    if ((stateRef.current as STTState) !== 'recording') return; // cancelled while choosing
+    if ('failure' in choice) {
+      report(speechFailureCode(choice.failure));
       setPhase('idle');
       return;
     }
+    recognizerRef.current = choice;
 
     earlierTextRef.current = '';
     currentTextRef.current = '';
     restartsRef.current = 0;
     openSession();
-  }, [openSession, setPhase]);
+  }, [lang, openSession, report, setPhase]);
 
   const waitForEnd = useCallback((): Promise<void> => {
     if (sessionRef.current === null) return Promise.resolve();
@@ -201,21 +223,33 @@ export function useSpeechToText(options: UseSTTOptions = {}) {
     earlierTextRef.current = '';
     currentTextRef.current = '';
     session?.abort();
-    setError(null);
-  }, [setPhase]);
+    report(null);
+  }, [report, setPhase]);
 
   useEffect(() => {
     mountedRef.current = true;
     return () => {
       mountedRef.current = false;
+      const wasListening = stateRef.current !== 'idle';
       stateRef.current = 'idle';
       sessionRef.current?.abort();
+      // The effect that mirrors the phase into the store will not run again,
+      // and the store outlives this hook: a composer unmounted mid-dictation —
+      // the call controls replacing it — would otherwise leave the ambient
+      // field and the dictation bar reading "recording" for the rest of the call.
+      if (wasListening) {
+        useSTTStore.getState().setRecording(false);
+        useSTTStore.getState().setMetering(0);
+      }
     };
   }, []);
 
   return {
     state,
-    error,
+    /** What went wrong, in English. */
+    error: errorCode === null ? null : VOICE_ERROR_MESSAGES[errorCode],
+    /** The same, as a code an app can translate. */
+    errorCode,
     /** False where the platform cannot recognize speech at all (Firefox). */
     isSupported,
     startRecording,

package/src/hooks/useTTS.ts

@@ -5,7 +5,6 @@ import { useOxy } from '@oxy.so/services';
 import { errorMessage } from '../lib/utils';
 import { create } from 'zustand';
 import { createAudioLevelMeter } from '../lib/audio-level';
-import { PREFERRED_VOICE_MODEL_ID } from '../lib/config';
 import { requestSpeechClip } from '../lib/speech-synthesis';
 
 const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
@@ -18,12 +17,8 @@ export interface UseTTSOptions {
   voice?: 'male' | 'female';
   tone?: 'brief' | 'chill' | 'default';
   /**
-   * Speech model. Defaults to the build's `PREFERRED_VOICE_MODEL_ID`.
-   *
-   * Not checked against `GET /catalogue`: that surface describes what a chat
-   * picker may offer and its resolver filters to `chat_visible` entries, so
-   * passing a voice identifier through it would substitute a chat model that
-   * cannot speak. See `lib/config.ts`.
+   * Speech model. Omitted, the request carries no `model` and the server's
+   * own speech model answers.
    */
   model?: string;
 }
@@ -90,7 +85,7 @@ useTTSStore.subscribe((state, previous) => {
 export function useTTS(options: UseTTSOptions = {}) {
   const apiUrl = options.apiUrl || API_URL;
   const voicePref = options.voice ?? 'female';
-  const voiceModel = options.model ?? PREFERRED_VOICE_MODEL_ID;
+  const voiceModel = options.model;
   const tonePref = options.tone ?? 'default';
 
   const { oxyServices } = useOxy();
@@ -112,7 +107,7 @@ export function useTTS(options: UseTTSOptions = {}) {
 
   const getToken = useCallback((): string | null => {
     if (options.accessToken) return options.accessToken;
-    return oxyServices.httpService.getAccessToken();
+    return oxyServices.session.accessToken;
   }, [options.accessToken, oxyServices]);
 
   const getTTSVoice = useCallback(() => {

package/src/hooks/useVoiceRoom.ts

@@ -31,14 +31,14 @@ import { useState, useCallback, useRef, useEffect, useMemo } from 'react';
 import { useOxy } from '@oxy.so/services';
 import { errorMessage } from '../lib/utils';
 import type { RoomState, AgentState, VoiceMessage } from '../types';
-import { PREFERRED_VOICE_MODEL_ID } from '../lib/config';
 import {
   isSpeechRecognitionAvailable,
+  chooseSpeechRecognizer,
   requestSpeechRecognitionPermission,
   startSpeechRecognition,
 } from '../lib/speech-recognition';
 import type { SpeechRecognitionFailure, SpeechRecognitionSession } from '../lib/speech-recognition-types';
-import { speechFailureMessage } from '../lib/speech-messages';
+import { speechFailureCode, VOICE_ERROR_MESSAGES, type VoiceErrorCode } from '../lib/speech-messages';
 import { defaultSpeechLanguage } from '../lib/speech-language';
 import { playSpeechClip, requestSpeechClip, type ProductVoice } from '../lib/speech-synthesis';
 import { VoiceLevelChannel, type VoiceLevelSource } from '../lib/voice-levels';
@@ -66,15 +66,13 @@ export interface UseVoiceRoomOptions {
   /** Bearer for speech synthesis; defaults to the surrounding Oxy session's. */
   accessToken?: string;
   /**
-   * Speech model for the answers. Defaults to the build's
-   * `PREFERRED_VOICE_MODEL_ID`, the one profile `/v1/audio/speech` accepts.
-   *
-   * Not checked against `GET /catalogue`, for the reason given in
-   * `lib/config.ts`.
+   * Speech model for the answers. Omitted, the request carries no `model` and
+   * the server's own speech model answers.
    */
   model?: string;
   /**
-   * Chat routing profile the default sender asks for. Ignored when `sendTurn`
+   * Chat model (`publisher/model`) the default sender asks for; omitted, the
+   * server's default. Ignored when `sendTurn`
    * is given — that sender carries its own conversation's choice.
    */
   chatModel?: string;
@@ -136,16 +134,21 @@ interface ActiveTurn {
 export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
   const apiUrl = options.apiUrl || API_URL;
   const voicePref: ProductVoice = options.voicePreference ?? 'female';
-  const speechModel = options.model ?? PREFERRED_VOICE_MODEL_ID;
+  const speechModel = options.model;
   const endOfUtteranceMs = options.endOfUtteranceMs ?? DEFAULT_END_OF_UTTERANCE_MS;
   const bargeIn = options.bargeIn ?? true;
 
   const [roomState, setRoomState] = useState<RoomState>('disconnected');
   const [agentState, setAgentStateValue] = useState<AgentState>('idle');
   const [isMuted, setIsMuted] = useState(false);
-  const [error, setError] = useState<string | null>(null);
+  /**
+   * Why the call ended, as a code and as the sentence to show. The sentence is
+   * the code's English copy, except for `turn-failed`, which carries what the
+   * turn sender threw.
+   */
+  const [callFailure, setCallFailure] = useState<{ code: VoiceErrorCode; message: string } | null>(null);
   /** A turn that failed without ending the call: no answer, or no audio for it. */
-  const [turnError, setTurnError] = useState<string | null>(null);
+  const [turnErrorCode, setTurnErrorCode] = useState<VoiceErrorCode | null>(null);
   const [messages, setMessagesState] = useState<VoiceMessage[]>([]);
   const [currentSpeaker, setCurrentSpeaker] = useState<'primary' | 'user' | null>(null);
 
@@ -160,6 +163,8 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
   const mountedRef = useRef(true);
   const messagesRef = useRef<VoiceMessage[]>([]);
   const sessionRef = useRef<SpeechRecognitionSession | null>(null);
+  /** The recognizer and tag the call listens with, chosen when it connects. */
+  const recognizerRef = useRef<{ lang: string; service?: string }>({ lang: '' });
   const heardRef = useRef('');
   const committingRef = useRef(false);
   const silenceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -220,7 +225,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
   const getToken = useCallback((): string | null => {
     const { accessToken } = configRef.current;
     if (accessToken) return accessToken;
-    return oxyServices.httpService.getAccessToken();
+    return oxyServices.session.accessToken;
   }, [oxyServices]);
 
   const clearTimers = (): void => {
@@ -267,11 +272,11 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     levels.reset();
   }, [endTurn, levels]);
 
-  const fail = useCallback((message: string) => {
+  const fail = useCallback((code: VoiceErrorCode, message: string = VOICE_ERROR_MESSAGES[code]) => {
     teardown();
     discardDraft();
     if (!mountedRef.current) return;
-    setError(message);
+    setCallFailure({ code, message });
     setRoomState('error');
     setAgentStateValue('idle');
     setCurrentSpeaker(null);
@@ -381,7 +386,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     sessionStartedAtRef.current = Date.now();
 
     sessionRef.current = startSpeechRecognition(
-      { lang: configRef.current.lang, echoCancellation: true },
+      { ...recognizerRef.current, echoCancellation: true },
       {
         onResult: ({ transcript }) => {
           if (phaseRef.current === 'off' || committingRef.current) return;
@@ -426,7 +431,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
 
           const failure = sessionFailedRef.current;
           if (failure !== null && failure.code !== 'other') {
-            fail(speechFailureMessage(failure) ?? 'Speech recognition failed');
+            fail(speechFailureCode(failure) ?? 'speech-failed');
             return;
           }
 
@@ -440,7 +445,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
           if (Date.now() - sessionStartedAtRef.current < RAPID_END_MS) {
             rapidEndsRef.current += 1;
             if (rapidEndsRef.current >= MAX_RAPID_ENDS) {
-              fail(speechFailureMessage(failure ?? { code: 'other' }) ?? 'Speech recognition failed');
+              fail(speechFailureCode(failure ?? { code: 'other' }) ?? 'speech-failed');
               return;
             }
           } else {
@@ -494,7 +499,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     };
     turnRef.current = turn;
     setAgent('thinking');
-    if (mountedRef.current) setTurnError(null);
+    if (mountedRef.current) setTurnErrorCode(null);
 
     // The microphone stays open through thinking and speaking, for barge-in.
     startListeningRef.current();
@@ -520,7 +525,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
       } catch (caught: unknown) {
         if (signal.aborted) return;
         console.error('[useVoiceRoom] Turn failed:', caught);
-        fail(errorMessage(caught, 'Voice request failed'));
+        fail('turn-failed', errorMessage(caught, VOICE_ERROR_MESSAGES['turn-failed']));
         return;
       }
       if (signal.aborted) return;
@@ -540,9 +545,9 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
       sessionRef.current?.abort();
       if (turn.text.trim() === '') {
         updateMessages((previous) => previous.filter((message) => message.id !== assistantId));
-        if (mountedRef.current) setTurnError('No answer came back — try saying it again');
+        if (mountedRef.current) setTurnErrorCode('no-answer');
       } else if (turn.synthesisFailed) {
-        if (mountedRef.current) setTurnError('The answer could not be played aloud');
+        if (mountedRef.current) setTurnErrorCode('not-played');
       }
       setAgent('listening');
       startListeningRef.current();
@@ -554,17 +559,17 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
 
   const connect = useCallback(async () => {
     if (phaseRef.current !== 'off') return;
-    setError(null);
-    setTurnError(null);
+    setCallFailure(null);
+    setTurnErrorCode(null);
     setRoomState('connecting');
 
     if (!isSpeechRecognitionAvailable()) {
-      setError('Voice is not available on this device');
+      setCallFailure({ code: 'voice-unavailable', message: VOICE_ERROR_MESSAGES['voice-unavailable'] });
       setRoomState('error');
       return;
     }
     if (getToken() === null) {
-      setError('Not authenticated');
+      setCallFailure({ code: 'not-authenticated', message: VOICE_ERROR_MESSAGES['not-authenticated'] });
       setRoomState('error');
       return;
     }
@@ -572,10 +577,22 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     const refusal = await requestSpeechRecognitionPermission();
     if (!mountedRef.current) return;
     if (refusal !== null) {
-      setError(speechFailureMessage(refusal) ?? 'Microphone permission required');
+      const code = speechFailureCode(refusal) ?? 'microphone-denied';
+      setCallFailure({ code, message: VOICE_ERROR_MESSAGES[code] });
+      setRoomState('error');
+      return;
+    }
+
+    // The recognizer that knows the call's language, as dictation picks it.
+    const choice = await chooseSpeechRecognizer(configRef.current.lang);
+    if (!mountedRef.current) return;
+    if ('failure' in choice) {
+      const code = speechFailureCode(choice.failure) ?? 'speech-language';
+      setCallFailure({ code, message: VOICE_ERROR_MESSAGES[code] });
       setRoomState('error');
       return;
     }
+    recognizerRef.current = { lang: choice.lang, service: choice.service };
 
     rapidEndsRef.current = 0;
     setRoomState('connected');
@@ -592,8 +609,8 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     mutedRef.current = false;
     setRoomState('disconnected');
     setAgentStateValue('idle');
-    setError(null);
-    setTurnError(null);
+    setCallFailure(null);
+    setTurnErrorCode(null);
     setIsMuted(false);
     setMessagesState([]);
     setCurrentSpeaker(null);
@@ -637,8 +654,12 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     roomState,
     agentState,
     isMuted,
-    error,
-    turnError,
+    /** Why the call ended, in English. */
+    error: callFailure?.message ?? null,
+    /** The same, as a code an app can translate. */
+    errorCode: callFailure?.code ?? null,
+    turnError: turnErrorCode === null ? null : VOICE_ERROR_MESSAGES[turnErrorCode],
+    turnErrorCode,
     messages,
     currentSpeaker,
     connect,

package/src/index.ts

@@ -13,7 +13,7 @@ export { IdentityMark } from './components/IdentityMark';
 export type { IdentityMarkProps, IdentityMarkState } from './components/IdentityMark';
 export { ThinkingIndicator } from './components/ThinkingIndicator';
 export { AliaMarkdown } from './components/Markdown';
-export type { AliaMarkdownProps } from './components/Markdown';
+export type { AliaMarkdownProps, RenderCodeBlock } from './components/Markdown';
 export { Reasoning, ReasoningTrigger, ReasoningContent } from './components/Reasoning';
 export { AliaWelcomeMessage } from './components/AliaWelcomeMessage';
 export { ResearchProgressCard } from './components/ResearchProgressCard';
@@ -27,11 +27,13 @@ export type { UseAliaChatOptions, UseAliaChatReturn } from './hooks/useAliaChat'
 export { useTTS } from './hooks/useTTS';
 export type { UseTTSOptions } from './hooks/useTTS';
 export { useSpeechToText, useSTTStore } from './hooks/useSpeechToText';
+export { VOICE_ERROR_MESSAGES } from './lib/speech-messages';
+export type { VoiceErrorCode } from './lib/speech-messages';
 export type { UseSTTOptions } from './hooks/useSpeechToText';
 
 // ── Model catalogue (GET /catalogue) ──
-// Exported so a consumer building its own picker reads the surface the SDK
-// reads, rather than hardcoding an identifier the way this package used to.
+// Exported so a consumer building its own picker reads the real models the
+// server offers; the SDK itself ships no model identifier.
 export {
   fetchCatalogue,
   parseCatalogue,
@@ -39,8 +41,7 @@ export {
   resolveModelId,
   clearCatalogueCache,
 } from './lib/catalogue';
-export type { CatalogueEntry, CatalogueEntryKind, ModelSelection } from './lib/catalogue';
-export { PREFERRED_CHAT_MODEL_ID, PREFERRED_VOICE_MODEL_ID } from './lib/config';
+export type { Catalogue, CatalogueEntry, ModelSelection, ReasoningEffort } from './lib/catalogue';
 
 // ── Types ──
 export type {