@bytexbyte/nxtlinq-ai-agent-web-development 0.1.1

package/src/legacy/core/lib/useSpeechToTextFromMic/helper.ts

@@ -0,0 +1,132 @@
+import {
+  AudioConfig,
+  CancellationReason,
+  PropertyId,
+  ResultReason,
+  SpeechConfig,
+  SpeechRecognizer,
+} from 'microsoft-cognitiveservices-speech-sdk';
+import { Dispatch, SetStateAction } from 'react';
+import Cookie from 'universal-cookie';
+import { createNxtlinqApi } from '../../../api/nxtlinq-api';
+
+/**
+ * Start speech recognition
+ * - partialTranscript: temporary partial transcription (recognizing)
+ * - setSpeechToTextArray: finalized sentence array (recognized)
+ */
+export const startSpeechToTextFromMic = async (
+  setSpeechToTextArray: Dispatch<SetStateAction<string[]>>,   // finalized sentences
+  config: { apiKey: string; apiSecret: string },
+  historyRef: React.MutableRefObject<string[]>,
+  indexRef: React.MutableRefObject<number>,
+  setPartialTranscript?: Dispatch<SetStateAction<string>>      // temporary partial transcription state updater
+): Promise<SpeechRecognizer | undefined> => {
+  const tokenRes = await getTokenOrRefresh(config.apiKey, config.apiSecret);
+  if (!tokenRes.authToken || !tokenRes.region) {
+    console.error('Speech token retrieval failed:', tokenRes.error);
+    return;
+  }
+
+  const speechConfig = SpeechConfig.fromAuthorizationToken(tokenRes.authToken, tokenRes.region);
+  speechConfig.speechRecognitionLanguage = 'en-US';
+
+  // silence detection and segmentation configuration
+  speechConfig.setProperty(PropertyId.SpeechServiceConnection_InitialSilenceTimeoutMs, '10000');
+  speechConfig.setProperty(PropertyId.SpeechServiceConnection_EndSilenceTimeoutMs, '86400000');
+  speechConfig.setProperty(PropertyId.Speech_SegmentationSilenceTimeoutMs, '3000');
+
+  const audioConfig = AudioConfig.fromDefaultMicrophoneInput();
+  const recognizer = new SpeechRecognizer(speechConfig, audioConfig);
+
+  // temporary partial transcription
+  recognizer.recognizing = (_s, e) => {
+    if (setPartialTranscript) {
+      setPartialTranscript(e.result.text);
+    }
+  };
+
+  // finalized sentences
+  recognizer.recognized = (_s, e) => {
+    if (e.result.reason === ResultReason.RecognizedSpeech) {
+      const text = e.result.text.trim();
+
+      // Filter out very short text (likely background noise or false positives)
+      // Minimum 3 characters to reduce sensitivity to background sounds
+      if (text.length < 3) {
+        return;
+      }
+
+      // Check confidence if available (some SDK versions provide this)
+      // Lower confidence results are more likely to be background noise
+      // Increased threshold to 0.4 to better filter out low-volume background noise
+      const confidence = (e.result as any).confidence;
+      if (confidence !== undefined && confidence < 0.4) {
+        return;
+      }
+
+      historyRef.current[indexRef.current] = text;
+      indexRef.current += 1;
+
+      // return only the latest finalized sentence to the UI
+      setSpeechToTextArray([text]);
+
+      if (setPartialTranscript) setPartialTranscript('');
+    }
+  };
+
+  recognizer.canceled = (_s, e) => {
+    console.warn('Speech recognition canceled:', e.reason);
+    if (e.reason === CancellationReason.Error) {
+      console.error(`Error code: ${e.errorCode}`);
+      console.error(`Error details: ${e.errorDetails}`);
+    }
+  };
+
+  await new Promise<void>((resolve, reject) => {
+    recognizer.startContinuousRecognitionAsync(
+      () => resolve(),
+      error => {
+        console.error('Failed to start continuous speech recognition:', error);
+        reject(error);
+      }
+    );
+  });
+
+  return recognizer;
+};
+
+/**
+ * Stop speech recognition
+ */
+export const stopRecognition = (recognizer: SpeechRecognizer | undefined) => {
+  if (recognizer) {
+    recognizer.stopContinuousRecognitionAsync();
+  }
+};
+
+export async function getTokenOrRefresh(apiKey: string, apiSecret: string) {
+  const nxtlinqApi = createNxtlinqApi(apiKey, apiSecret);
+  const cookie = new Cookie();
+  const speechToken = cookie.get('speech-token');
+
+  if (speechToken === undefined) {
+    try {
+      const res = await nxtlinqApi.cognitive.getCognitiveToken();
+      if ('error' in res) {
+        throw new Error(res.error);
+      }
+      const token = res.token;
+      const region = res.region;
+      cookie.set('speech-token', region + ':' + token, { maxAge: 540, path: '/' });
+
+      return { authToken: token, region: region };
+    } catch (e) {
+      const err = e as { response: { data: string } };
+      return { authToken: null, error: err.response.data };
+    }
+  } else {
+    const idx = speechToken.indexOf(':');
+    return { authToken: speechToken.slice(idx + 1), region: speechToken.slice(0, idx) };
+  }
+}

package/src/legacy/core/lib/useSpeechToTextFromMic/index.ts

@@ -0,0 +1,126 @@
+import { SpeechRecognizer } from 'microsoft-cognitiveservices-speech-sdk';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { startSpeechToTextFromMic, stopRecognition } from './helper';
+
+interface Props {
+  apiKey: string;
+  apiSecret: string;
+  autoClearTranscript?: boolean;
+}
+
+type UseSpeechToTextFromMicResult = {
+  start: () => Promise<void>;
+  stop: () => void;
+  clear: () => void;
+  isMicEnabled: boolean;
+  transcript: string;
+  partialTranscript: string;
+};
+
+export function useSpeechToTextFromMic({
+  apiKey,
+  apiSecret,
+  autoClearTranscript = true,
+}: Props): UseSpeechToTextFromMicResult {
+  const [isMicEnabled, setIsMicEnabled] = useState(false);
+  const [transcriptArray, setTranscriptArray] = useState<string[]>([]);
+  const [partialTranscript, setPartialTranscript] = useState('');
+  const [recognizer, setRecognizer] = useState<SpeechRecognizer | undefined>();
+
+  const wakelock = useRef<WakeLockSentinel>();
+  const historyRef = useRef<string[]>([]);
+  const indexRef = useRef<number>(0);
+
+  const lockWakeState = useCallback(async () => {
+    if (typeof navigator === 'undefined' || !('wakeLock' in navigator)) return;
+    try {
+      wakelock.current = await navigator.wakeLock.request('screen');
+      wakelock.current.addEventListener('release', () => {
+        // Wake lock was released by the system
+      });
+    } catch (err) {
+      console.error('Wake lock error:', err);
+    }
+  }, []);
+
+  const clear = useCallback(() => {
+    historyRef.current = [];
+    indexRef.current = 0;
+    setTranscriptArray([]);
+    setPartialTranscript('');
+  }, [setPartialTranscript, setTranscriptArray]);
+
+  const start = useCallback(async () => {
+    clear();
+    await lockWakeState();
+    try {
+      const recognizerInstance = await startSpeechToTextFromMic(
+        setTranscriptArray,
+        { apiKey, apiSecret },
+        historyRef,
+        indexRef,
+        setPartialTranscript
+      );
+      setRecognizer(recognizerInstance);
+      setIsMicEnabled(true);
+    } catch (error) {
+      wakelock.current?.release();
+      setIsMicEnabled(false);
+      console.error('Failed to start speech recognition:', error);
+      throw error;
+    }
+  }, [apiKey, apiSecret, clear, lockWakeState, setPartialTranscript, setTranscriptArray]);
+
+  const stop = useCallback(() => {
+    wakelock.current?.release();
+    stopRecognition(recognizer);
+    setIsMicEnabled(false);
+    setRecognizer(undefined);
+  }, [recognizer, setRecognizer]);
+
+  // Keep UI state in sync if recognizer stops or gets canceled by the SDK/browser
+  useEffect(() => {
+    if (!recognizer) return;
+
+    const prevCanceled = recognizer.canceled;
+    const prevSessionStopped = recognizer.sessionStopped;
+
+    recognizer.canceled = (s, e) => {
+      setIsMicEnabled(false);
+      if (prevCanceled) prevCanceled(s, e);
+    };
+
+    recognizer.sessionStopped = (s, e) => {
+      setIsMicEnabled(false);
+      if (prevSessionStopped) prevSessionStopped(s, e);
+    };
+
+    return () => {
+      // No explicit detach API; restoring previous handlers to avoid leaks
+      if (recognizer) {
+        recognizer.canceled = prevCanceled;
+        recognizer.sessionStopped = prevSessionStopped;
+      }
+    };
+  }, [recognizer]);
+
+  useEffect(() => {
+    if (autoClearTranscript && transcriptArray.length > 0) {
+      const timer = setTimeout(() => {
+        setTranscriptArray([]);
+      }, 100);
+      return () => clearTimeout(timer);
+    }
+  }, [transcriptArray, autoClearTranscript]);
+
+  const transcript = transcriptArray.join(' ');
+
+  return {
+    start,
+    stop,
+    clear,
+    isMicEnabled,
+    transcript,
+    partialTranscript,
+  };
+}

package/src/legacy/core/lib/useVoiceMode.ts

@@ -0,0 +1,407 @@
+import * as React from 'react';
+import { flushSync } from 'react-dom';
+import type { AITApi, Message, VoiceTransport } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import {
+  mergeStreamingTranscript,
+  normalizeTranscriptKey,
+  type VoiceDoneEvent,
+  type VoiceSession,
+  type VoiceStatus,
+  type VoiceTranscriptEvent,
+} from '../../api/voice';
+import { appendServerHistoryIntoMessages } from './messageHistory';
+import { useVoiceTranscriptMessages } from '../../../voice/useVoiceTranscriptMessages';
+import { useWsRealtimeAudio } from '../../../voice/useWsRealtimeAudio';
+
+const TURN_SETTLE_MS = 1500;
+const VOICE_HISTORY_SYNC_LAST = 20;
+
+const USER_TRANSCRIPT_BLOCKED: ReadonlySet<VoiceStatus> = new Set([
+  'thinking', 'generating', 'speaking',
+]);
+
+const ASSISTANT_MIC_HOLD_STATUSES: ReadonlySet<VoiceStatus> = new Set([
+  'transcribing', 'thinking', 'generating', 'speaking',
+]);
+
+export type UseVoiceModeOptions = {
+  apiKey: string;
+  apiSecret: string;
+  pseudoId: string;
+  externalId?: string;
+  aitId?: string;
+  walletAddress?: string;
+  aitToken?: string;
+  metadata?: Record<string, unknown>;
+  nxtlinqApi: AITApi;
+  getMessages: () => Message[];
+  setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
+  onError?: (error: Error) => void;
+  stopRecording: () => void;
+  stopTextToSpeech: () => void;
+  voiceTransport?: VoiceTransport;
+};
+
+export function useVoiceMode({
+  apiKey,
+  apiSecret,
+  pseudoId,
+  externalId,
+  aitId,
+  walletAddress,
+  aitToken,
+  metadata,
+  nxtlinqApi,
+  getMessages,
+  setMessages,
+  onError,
+  stopRecording,
+  stopTextToSpeech,
+  voiceTransport = 'ws-realtime',
+}: UseVoiceModeOptions) {
+  const [isVoiceMode, setIsVoiceMode] = React.useState(false);
+  const [voiceStatus, setVoiceStatus] = React.useState<VoiceStatus>('idle');
+  const [isVoiceConnecting, setIsVoiceConnecting] = React.useState(false);
+  const [isMicMuted, setIsMicMuted] = React.useState(true);
+  const [isMicCaptureActive, setIsMicCaptureActive] = React.useState(false);
+  const [voiceSessionId, setVoiceSessionId] = React.useState<string | null>(null);
+
+  const sessionRef = React.useRef<VoiceSession | null>(null);
+  const remoteAudioRef = React.useRef<HTMLAudioElement | null>(null);
+  const voiceStatusRef = React.useRef<VoiceStatus>('idle');
+  const activeTurnRef = React.useRef(false);
+  const historyRefreshInFlightRef = React.useRef<Promise<void> | null>(null);
+  const turnUserTextRef = React.useRef('');
+  const lastCommittedUserRef = React.useRef('');
+  const userMicMutedRef = React.useRef(true);
+  const userMicOptInRef = React.useRef(false);
+  const assistantMicHoldRef = React.useRef(false);
+  const voiceConnectGenerationRef = React.useRef(0);
+  const connectInFlightRef = React.useRef(false);
+  const turnSettleUntilRef = React.useRef(0);
+
+  const syncVoiceTurnHistory = React.useCallback(async (last = VOICE_HISTORY_SYNC_LAST) => {
+    if (historyRefreshInFlightRef.current) return historyRefreshInFlightRef.current;
+    const run = (async () => {
+      const result = await nxtlinqApi.agent.getMessageHistory({
+        apiKey, apiSecret, pseudoId, externalId, last,
+      });
+      if ('error' in result) {
+        onError?.(new Error(result.error));
+        return;
+      }
+      flushSync(() => {
+        setMessages((prev) => appendServerHistoryIntoMessages(prev, result.messages));
+      });
+    })().finally(() => { historyRefreshInFlightRef.current = null; });
+    historyRefreshInFlightRef.current = run;
+    return run;
+  }, [apiKey, apiSecret, pseudoId, externalId, nxtlinqApi, setMessages, onError]);
+
+  const voiceSessionIdRef = React.useRef<string | null>(null);
+
+  const transcriptApi = React.useMemo(() => ({
+    getMessages,
+    setMessages: (messages: Message[]) => setMessages(messages),
+    syncVoiceTurnHistory: (opts?: { last?: number }) => syncVoiceTurnHistory(opts?.last),
+  }), [getMessages, setMessages, syncVoiceTurnHistory]);
+
+  const { handleTranscript: handleTranscriptUi, handleDone: handleDoneUi, clearVoiceStream } =
+    useVoiceTranscriptMessages(transcriptApi, 'voice', voiceSessionId, () => voiceSessionIdRef.current);
+
+  const resetMicAfterTurn = React.useCallback(() => {
+    lastCommittedUserRef.current = turnUserTextRef.current.trim();
+    turnUserTextRef.current = '';
+    activeTurnRef.current = false;
+    turnSettleUntilRef.current = Date.now() + TURN_SETTLE_MS;
+    userMicMutedRef.current = true;
+    userMicOptInRef.current = false;
+    setIsMicCaptureActive(false);
+    applyMicStateRef.current();
+  }, []);
+
+  const applyMicState = React.useCallback(() => {
+    const shouldMute = userMicMutedRef.current || assistantMicHoldRef.current;
+    sessionRef.current?.muteMic(shouldMute);
+    setIsMicMuted(shouldMute);
+    const captureActive = isVoiceMode && !shouldMute && userMicOptInRef.current;
+    setIsMicCaptureActive(captureActive);
+  }, [isVoiceMode]);
+
+  const applyMicStateRef = React.useRef(applyMicState);
+  applyMicStateRef.current = applyMicState;
+
+  const wsAudio = useWsRealtimeAudio(isMicCaptureActive, isVoiceMode, {
+    voiceStatus,
+    muteAfterSilenceCommit: () => {
+      userMicMutedRef.current = true;
+      userMicOptInRef.current = false;
+      setIsMicCaptureActive(false);
+      applyMicStateRef.current();
+    },
+  });
+  const wsAudioRef = React.useRef(wsAudio);
+  wsAudioRef.current = wsAudio;
+
+  const setAssistantMicHold = React.useCallback((held: boolean) => {
+    if (assistantMicHoldRef.current === held) return;
+    assistantMicHoldRef.current = held;
+    applyMicState();
+  }, [applyMicState]);
+
+  const attachRemoteAudio = React.useCallback(() => {
+    if (voiceTransport === 'ws-realtime') return false;
+    const session = sessionRef.current;
+    const audio = remoteAudioRef.current;
+    if (!session || !audio) return false;
+    const stream = session.getRemoteAudioStream();
+    if (stream) {
+      audio.srcObject = stream;
+      void audio.play().catch(() => {});
+      return true;
+    }
+    return false;
+  }, [voiceTransport]);
+
+  const beginTurn = React.useCallback(() => { activeTurnRef.current = true; }, []);
+
+  const handleTranscriptTurn = React.useCallback((event: VoiceTranscriptEvent) => {
+    if (event.role !== 'user') return;
+    if (Date.now() < turnSettleUntilRef.current) return;
+    if (userMicMutedRef.current) return;
+    if (!userMicOptInRef.current && !activeTurnRef.current) return;
+    if (assistantMicHoldRef.current || USER_TRANSCRIPT_BLOCKED.has(voiceStatusRef.current)) return;
+    if (!activeTurnRef.current) beginTurn();
+    const merged = (event.interim === false && event.text.trim())
+      ? event.text.trim()
+      : mergeStreamingTranscript(turnUserTextRef.current, event.text);
+    turnUserTextRef.current = merged;
+    if (lastCommittedUserRef.current &&
+      normalizeTranscriptKey(merged) === normalizeTranscriptKey(lastCommittedUserRef.current)) {
+      turnUserTextRef.current = '';
+      return;
+    }
+    if (!event.interim && event.text.trim()) lastCommittedUserRef.current = '';
+  }, [beginTurn]);
+
+  const handleStatus = React.useCallback((status: VoiceStatus) => {
+    const prev = voiceStatusRef.current;
+    if (status === 'listening' && userMicMutedRef.current && !activeTurnRef.current &&
+      Date.now() < turnSettleUntilRef.current) return;
+    voiceStatusRef.current = status;
+    setVoiceStatus(status);
+    if (ASSISTANT_MIC_HOLD_STATUSES.has(status)) setAssistantMicHold(true);
+    else if (status === 'listening' || status === 'idle') setAssistantMicHold(false);
+    if (status === 'transcribing' && prev === 'listening') beginTurn();
+    if (status === 'generating' && prev !== 'generating') beginTurn();
+    if (status === 'listening' && prev === 'speaking') resetMicAfterTurn();
+  }, [beginTurn, resetMicAfterTurn, setAssistantMicHold]);
+
+  const handleDone = React.useCallback((event: VoiceDoneEvent) => {
+    if (event.guardrailsBlocked || event.billingBlocked) {
+      activeTurnRef.current = false;
+      return;
+    }
+    if (event.error) {
+      onError?.(new Error(event.error));
+      return;
+    }
+    handleDoneUi(event);
+    resetMicAfterTurn();
+  }, [handleDoneUi, onError, resetMicAfterTurn]);
+
+  const voiceHandlersRef = React.useRef({
+    onStatus: (_status: VoiceStatus) => {},
+    onTranscript: (_event: VoiceTranscriptEvent) => {},
+    onDone: (_event: VoiceDoneEvent) => {},
+  });
+
+  const stopVoiceSession = React.useCallback(async (reason = 'unknown') => {
+    const session = sessionRef.current;
+    if (!session && !voiceSessionIdRef.current) return;
+    sessionRef.current = null;
+    voiceSessionIdRef.current = null;
+    setVoiceSessionId(null);
+    clearVoiceStream();
+    if (voiceTransport === 'ws-realtime') wsAudioRef.current.bindSession(null);
+    if (session) {
+      try { await session.stop(); } catch { /* best-effort */ }
+    }
+    const audio = remoteAudioRef.current;
+    if (audio) audio.srcObject = null;
+    voiceStatusRef.current = 'idle';
+    setVoiceStatus('idle');
+    userMicMutedRef.current = true;
+    userMicOptInRef.current = false;
+    assistantMicHoldRef.current = false;
+    turnSettleUntilRef.current = 0;
+    setIsMicMuted(true);
+    setIsMicCaptureActive(false);
+    lastCommittedUserRef.current = '';
+    turnUserTextRef.current = '';
+    activeTurnRef.current = false;
+  }, [clearVoiceStream, voiceTransport]);
+
+  const stopVoiceSessionRef = React.useRef(stopVoiceSession);
+  stopVoiceSessionRef.current = stopVoiceSession;
+
+  const exitVoiceMode = React.useCallback(async () => {
+    voiceConnectGenerationRef.current += 1;
+    setIsVoiceMode(false);
+    setIsVoiceConnecting(false);
+    await stopVoiceSession('exitVoiceMode');
+  }, [stopVoiceSession]);
+
+  const enterVoiceMode = React.useCallback(async () => {
+    if (connectInFlightRef.current || sessionRef.current) return;
+    connectInFlightRef.current = true;
+    const connectGeneration = voiceConnectGenerationRef.current + 1;
+    voiceConnectGenerationRef.current = connectGeneration;
+    const isConnectCancelled = () => connectGeneration !== voiceConnectGenerationRef.current;
+
+    stopRecording();
+    stopTextToSpeech();
+    setIsVoiceMode(true);
+    setIsVoiceConnecting(true);
+    clearVoiceStream();
+    lastCommittedUserRef.current = '';
+    turnUserTextRef.current = '';
+    voiceStatusRef.current = 'idle';
+    setVoiceStatus('idle');
+    userMicMutedRef.current = true;
+    userMicOptInRef.current = false;
+    assistantMicHoldRef.current = false;
+    turnSettleUntilRef.current = 0;
+    setIsMicMuted(true);
+    setIsMicCaptureActive(false);
+    activeTurnRef.current = false;
+
+    const wsCallbacks = voiceTransport === 'ws-realtime'
+      ? wsAudioRef.current.buildCallbacks({
+          onOpen: () => {
+            if (isConnectCancelled()) return;
+            voiceStatusRef.current = 'listening';
+            setVoiceStatus('listening');
+            assistantMicHoldRef.current = false;
+            applyMicState();
+          },
+          onClose: () => {
+            if (isConnectCancelled()) return;
+            voiceStatusRef.current = 'idle';
+            setVoiceStatus('idle');
+            connectInFlightRef.current = false;
+          },
+          onError: (err: Error) => {
+            if (isConnectCancelled()) return;
+            onError?.(err);
+          },
+        })
+      : undefined;
+
+    try {
+      let session: VoiceSession | undefined;
+      session = await nxtlinqApi.voice.startSession({
+        apiKey, apiSecret, pseudoId, externalId, aitId, walletAddress, aitToken,
+        voiceMode: 'realtime',
+        transport: voiceTransport,
+        startWithMicMuted: true,
+        metadata,
+        onAudioDelta: wsCallbacks?.onAudioDelta,
+        onOpen: wsCallbacks?.onOpen ?? (() => {
+          if (isConnectCancelled()) { void session?.stop(); return; }
+          voiceStatusRef.current = 'listening';
+          setVoiceStatus('listening');
+          assistantMicHoldRef.current = false;
+          applyMicState();
+          const tryAttach = () => { if (!attachRemoteAudio()) window.setTimeout(tryAttach, 100); };
+          tryAttach();
+        }),
+        onClose: wsCallbacks?.onClose ?? (() => {
+          if (isConnectCancelled()) return;
+          voiceStatusRef.current = 'idle';
+          setVoiceStatus('idle');
+          connectInFlightRef.current = false;
+        }),
+        onStatus: (status) => voiceHandlersRef.current.onStatus(status),
+        onTranscript: (event) => voiceHandlersRef.current.onTranscript(event),
+        onDone: (event) => voiceHandlersRef.current.onDone(event),
+        onError: (err) => {
+          if (isConnectCancelled()) return;
+          onError?.(err);
+        },
+      });
+
+      if (isConnectCancelled()) {
+        await session.stop();
+        return;
+      }
+      voiceSessionIdRef.current = session.id;
+      sessionRef.current = session;
+      setVoiceSessionId(session.id);
+      if (voiceTransport === 'ws-realtime') {
+        wsAudioRef.current.bindSession(session, false);
+      } else {
+        session.muteMic(true);
+        const tryAttach = () => { if (!attachRemoteAudio()) window.setTimeout(tryAttach, 100); };
+        tryAttach();
+      }
+    } catch (err) {
+      if (isConnectCancelled()) return;
+      onError?.(err instanceof Error ? err : new Error(String(err)));
+      setIsVoiceMode(false);
+      await stopVoiceSession('enterVoiceMode_error');
+    } finally {
+      connectInFlightRef.current = false;
+      if (!isConnectCancelled()) setIsVoiceConnecting(false);
+    }
+  }, [
+    apiKey, apiSecret, pseudoId, externalId, aitId, walletAddress, aitToken, metadata,
+    nxtlinqApi, stopRecording, stopTextToSpeech, attachRemoteAudio,
+    onError, stopVoiceSession, applyMicState, voiceTransport, clearVoiceStream,
+  ]);
+
+  const toggleMicMute = React.useCallback(() => {
+    if (!sessionRef.current) return;
+    if (assistantMicHoldRef.current && userMicMutedRef.current) return;
+    if (assistantMicHoldRef.current) {
+      userMicMutedRef.current = true;
+      applyMicState();
+      return;
+    }
+    const nextMuted = !userMicMutedRef.current;
+    userMicMutedRef.current = nextMuted;
+    userMicOptInRef.current = !nextMuted;
+    if (!nextMuted) turnSettleUntilRef.current = 0;
+    applyMicState();
+  }, [applyMicState]);
+
+  const interruptVoice = React.useCallback(() => {
+    sessionRef.current?.interrupt();
+    setAssistantMicHold(false);
+  }, [setAssistantMicHold]);
+
+  React.useEffect(() => {
+    voiceHandlersRef.current = {
+      onStatus: handleStatus,
+      onTranscript: (event) => {
+        handleTranscriptTurn(event);
+        handleTranscriptUi(event);
+      },
+      onDone: handleDone,
+    };
+  }, [handleStatus, handleTranscriptTurn, handleTranscriptUi, handleDone]);
+
+  React.useEffect(() => () => { void stopVoiceSessionRef.current('unmount'); }, []);
+
+  return {
+    isVoiceMode,
+    voiceStatus,
+    isVoiceConnecting,
+    isMicMuted,
+    remoteAudioRef,
+    enterVoiceMode,
+    exitVoiceMode,
+    toggleMicMute,
+    interruptVoice,
+  };
+}

package/src/legacy/core/metakeepClient.ts

@@ -0,0 +1,12 @@
+import { MetaKeep } from 'metakeep';
+
+const metakeepClient = new MetaKeep({
+  appId: 'e7d521f7-3eea-42d7-af42-4d8b962d9a6d',
+  chainId: 80002,
+  /* RPC node urls map */
+  rpcNodeUrls: {
+    80002: 'https://rpc-amoy.polygon.technology'
+  }
+});
+
+export default metakeepClient;