@bytexbyte/nxtlinq-ai-agent-ui-react-development 0.1.1

package/src/legacy/index.ts

@@ -0,0 +1,26 @@
+export { ChatBot } from './chatbot/ChatBot';
+export { ChatBotProvider, useChatBot } from './chatbot/context/ChatBotContext';
+
+export { ChatBotUI } from './chatbot/ui/ChatBotUI';
+export { MessageInput } from './chatbot/ui/MessageInput';
+export { MessageList } from './chatbot/ui/MessageList';
+export { ModelSelector } from './chatbot/ui/ModelSelector';
+export { NotificationModal } from './chatbot/ui/NotificationModal';
+export { PermissionForm } from './chatbot/ui/PermissionForm';
+export { PresetMessages } from './chatbot/ui/PresetMessages';
+export { BerifyMeModal } from './chatbot/ui/BerifyMeModal';
+
+export type {
+  AIModel,
+  AITMetadata,
+  ChatBotContextType,
+  ChatBotProps,
+  NovaError,
+  NovaResponse,
+  PresetMessage,
+  ToolCall,
+  ToolUse,
+} from './chatbot/types/ChatBotTypes';
+
+/** Alias for consumers migrating to the new package naming. */
+export { ChatBot as NxtlinqChatBot } from './chatbot/ChatBot';

package/src/theme/defaultTheme.ts

@@ -0,0 +1,22 @@
+import type { AgentAssistantTheme } from '../types';
+
+export const defaultAgentAssistantTheme: AgentAssistantTheme = {
+  colors: {
+    background: '#f8fafc',
+    surface: '#ffffff',
+    border: '#e2e8f0',
+    primary: '#2563eb',
+    primaryText: '#ffffff',
+    userBubble: '#2563eb',
+    userText: '#ffffff',
+    assistantBubble: '#f1f5f9',
+    assistantText: '#0f172a',
+    mutedText: '#64748b',
+    error: '#dc2626',
+    voiceActive: '#22c55e',
+    voiceSpeaking: '#ec4899',
+  },
+  spacing: { xs: 4, sm: 8, md: 16, lg: 24 },
+  radius: { bubble: 12, panel: 8, button: 8 },
+  typography: { titleSize: 17, bodySize: 15, captionSize: 13 },
+};

package/src/types.ts

@@ -0,0 +1,65 @@
+import type { Message, ToolUse as CoreToolUse } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import type { NxtlinqAgentProviderProps } from '@bytexbyte/nxtlinq-ai-agent-web-development';
+import type { CSSProperties } from 'react';
+
+export type PresetMessage = {
+  text: string;
+  autoSend?: boolean;
+};
+
+export type AgentAssistantTheme = {
+  colors: {
+    background: string;
+    surface: string;
+    border: string;
+    primary: string;
+    primaryText: string;
+    userBubble: string;
+    userText: string;
+    assistantBubble: string;
+    assistantText: string;
+    mutedText: string;
+    error: string;
+    voiceActive: string;
+    voiceSpeaking: string;
+  };
+  spacing: {
+    xs: number;
+    sm: number;
+    md: number;
+    lg: number;
+  };
+  radius: {
+    bubble: number;
+    panel: number;
+    button: number;
+  };
+  typography: {
+    titleSize: number;
+    bodySize: number;
+    captionSize: number;
+  };
+};
+
+export type NxtlinqAgentChatProps = Omit<NxtlinqAgentProviderProps, 'children'> & {
+  children?: NxtlinqAgentProviderProps['children'];
+  title?: string;
+  placeholder?: string;
+  presetMessages?: PresetMessage[];
+  loadHistoryOnMount?: boolean;
+  historyLast?: number;
+  enableVoice?: boolean;
+  enableFileUpload?: boolean;
+  startInVoiceMode?: boolean;
+  startWithMicMuted?: boolean;
+  holdMicDuringAssistant?: boolean;
+  theme?: Partial<AgentAssistantTheme>;
+  style?: CSSProperties;
+  headerStyle?: CSSProperties;
+  onMessage?: NxtlinqAgentProviderProps['onMessage'];
+  onError?: NxtlinqAgentProviderProps['onError'];
+  onToolUse?: NxtlinqAgentProviderProps['onToolUse'];
+};
+
+export type ToolUse = CoreToolUse;
+export type { Message };

package/src/voice/useVoiceConnectOrchestration.ts

@@ -0,0 +1,117 @@
+import type { VoiceDoneEvent, VoiceTranscriptEvent } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import type {
+  UseNxtlinqAgentResult,
+  UseNxtlinqVoiceResult,
+} from '@bytexbyte/nxtlinq-ai-agent-web-development';
+import { useCallback, useRef } from 'react';
+import type { InteractionMode } from '../context/AgentAssistantContext';
+
+type VoiceCallbacks = {
+  handleTranscript: (event: VoiceTranscriptEvent) => void;
+  handleDone: (event: VoiceDoneEvent) => void;
+  clearVoiceStream: () => void;
+  prepareForVoiceConnect: () => void;
+  resetMicState: () => void;
+  clearAssistantMicHold: () => void;
+  setInteractionMode: (mode: InteractionMode) => void;
+  setIsVoiceConnecting: (connecting: boolean) => void;
+};
+
+export function useVoiceConnectOrchestration(
+  agent: UseNxtlinqAgentResult,
+  voice: UseNxtlinqVoiceResult,
+  interactionMode: InteractionMode,
+  micStartsMuted: boolean,
+  callbacks: VoiceCallbacks,
+) {
+  const voiceConnectChainRef = useRef<Promise<unknown>>(Promise.resolve());
+
+  const wrappedStartVoice = useCallback(
+    (options?: Parameters<typeof voice.startVoice>[0]) => {
+      const connect = async () => {
+        if (voice.voiceSessionId != null) {
+          await voice.stopVoice('restart_voice');
+        }
+        callbacks.prepareForVoiceConnect();
+        callbacks.setInteractionMode('voice');
+        callbacks.setIsVoiceConnecting(true);
+        try {
+          const session = await voice.startVoice({
+            startWithMicMuted: micStartsMuted,
+            keepMicCaptureActive: true,
+            ...options,
+            onOpen: () => {
+              if (!micStartsMuted) {
+                voice.muteMic(false);
+              }
+              options?.onOpen?.();
+            },
+            onClose: (reason) => {
+              callbacks.clearVoiceStream();
+              callbacks.resetMicState();
+              const userInitiated =
+                reason === 'switch_to_text' ||
+                reason === 'client_stop' ||
+                reason === 'mode_text_cleanup';
+              if (userInitiated) {
+                callbacks.setInteractionMode('text');
+              } else {
+                console.warn('[nxtlinq] voice session closed:', reason);
+              }
+              options?.onClose?.(reason);
+            },
+            onError: (err) => {
+              callbacks.clearVoiceStream();
+              callbacks.resetMicState();
+              console.warn('[nxtlinq] voice session error:', err.message);
+              options?.onError?.(err);
+            },
+            onTranscript: (event) => {
+              callbacks.handleTranscript(event);
+              options?.onTranscript?.(event);
+            },
+            onDone: (event) => {
+              callbacks.handleDone(event);
+              options?.onDone?.(event);
+            },
+          });
+          return session;
+        } catch (err) {
+          callbacks.setInteractionMode('text');
+          callbacks.resetMicState();
+          throw err;
+        } finally {
+          callbacks.setIsVoiceConnecting(false);
+        }
+      };
+      const next = voiceConnectChainRef.current.then(connect, connect);
+      voiceConnectChainRef.current = next.catch(() => undefined);
+      return next;
+    },
+    [voice, micStartsMuted, callbacks],
+  );
+
+  const wrappedStopVoice = useCallback(async () => {
+    await voice.stopVoice('client_stop');
+    callbacks.resetMicState();
+    callbacks.setInteractionMode('text');
+  }, [voice, callbacks]);
+
+  const wrappedInterrupt = useCallback(() => {
+    voice.interrupt();
+    callbacks.clearAssistantMicHold();
+  }, [voice, callbacks]);
+
+  const isVoiceChannelReady =
+    interactionMode === 'voice' &&
+    voice.voiceSessionId != null &&
+    (Boolean(agent.agent.getVoiceSession()?.isAppChannelOpen()) ||
+      voice.voiceStatus === 'listening');
+
+  return {
+    wrappedStartVoice,
+    wrappedStopVoice,
+    wrappedInterrupt,
+    isVoiceChannelReady,
+  };
+}

package/src/voice/useVoiceMicState.ts

@@ -0,0 +1,117 @@
+import type { VoiceStatus } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import type { UseNxtlinqVoiceResult } from '@bytexbyte/nxtlinq-ai-agent-web-development';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ASSISTANT_MIC_HOLD_STATUSES } from './voiceMicConstants';
+
+export type UseVoiceMicStateOptions = {
+  startWithMicMuted?: boolean;
+  holdMicDuringAssistant?: boolean;
+  onBargeIn?: () => void;
+};
+
+export function useVoiceMicState(
+  voice: UseNxtlinqVoiceResult,
+  isVoiceConnecting: boolean,
+  options?: UseVoiceMicStateOptions,
+) {
+  const connectMuted = options?.startWithMicMuted !== false;
+  const holdDuringAssistant = options?.holdMicDuringAssistant !== false;
+  const userMicMutedRef = useRef(connectMuted);
+  const assistantMicHoldRef = useRef(false);
+  const userMicOptInRef = useRef(!connectMuted);
+  const [isMicMuted, setIsMicMuted] = useState(connectMuted);
+
+  const applyMicState = useCallback(() => {
+    const shouldMute = userMicMutedRef.current || assistantMicHoldRef.current;
+    voice.muteMic(shouldMute);
+    setIsMicMuted(shouldMute);
+  }, [voice]);
+
+  const resetMicState = useCallback(() => {
+    userMicMutedRef.current = false;
+    assistantMicHoldRef.current = false;
+    userMicOptInRef.current = false;
+    setIsMicMuted(false);
+  }, []);
+
+  const prepareForVoiceConnect = useCallback(() => {
+    userMicMutedRef.current = connectMuted;
+    userMicOptInRef.current = !connectMuted;
+    assistantMicHoldRef.current = false;
+    setIsMicMuted(connectMuted);
+    voice.muteMic(connectMuted);
+  }, [voice, connectMuted]);
+
+  useEffect(() => {
+    if (!isVoiceConnecting) return;
+    userMicMutedRef.current = connectMuted;
+    voice.muteMic(connectMuted);
+    setIsMicMuted(connectMuted);
+  }, [isVoiceConnecting, voice, connectMuted]);
+
+  const prevVoiceStatusRef = useRef(voice.voiceStatus);
+
+  useEffect(() => {
+    const status = voice.voiceStatus;
+    const prev = prevVoiceStatusRef.current;
+    prevVoiceStatusRef.current = status;
+
+    if (holdDuringAssistant && ASSISTANT_MIC_HOLD_STATUSES.has(status)) {
+      if (!userMicMutedRef.current && userMicOptInRef.current) {
+        assistantMicHoldRef.current = false;
+        applyMicState();
+        return;
+      }
+      assistantMicHoldRef.current = true;
+      applyMicState();
+      return;
+    }
+    if (status === 'listening' || status === 'idle') {
+      assistantMicHoldRef.current = false;
+      if (
+        connectMuted
+        && status === 'listening'
+        && prev === 'speaking'
+        && !userMicOptInRef.current
+      ) {
+        userMicMutedRef.current = true;
+      }
+      applyMicState();
+    }
+  }, [voice.voiceStatus, applyMicState, holdDuringAssistant, connectMuted]);
+
+  const toggleVoiceMicMute = useCallback(() => {
+    if (!voice.isVoiceActive && !isVoiceConnecting) return;
+    if (assistantMicHoldRef.current && userMicMutedRef.current) {
+      assistantMicHoldRef.current = false;
+      userMicMutedRef.current = false;
+      userMicOptInRef.current = true;
+      options?.onBargeIn?.();
+      applyMicState();
+      return;
+    }
+    if (assistantMicHoldRef.current) {
+      userMicMutedRef.current = true;
+      applyMicState();
+      return;
+    }
+    const nextMuted = !userMicMutedRef.current;
+    userMicMutedRef.current = nextMuted;
+    userMicOptInRef.current = !nextMuted;
+    applyMicState();
+  }, [voice.isVoiceActive, isVoiceConnecting, applyMicState, options]);
+
+  const clearAssistantMicHold = useCallback(() => {
+    assistantMicHoldRef.current = false;
+    applyMicState();
+  }, [applyMicState]);
+
+  return {
+    isMicMuted,
+    isMicHeldForAssistant: ASSISTANT_MIC_HOLD_STATUSES.has(voice.voiceStatus),
+    toggleVoiceMicMute,
+    prepareForVoiceConnect,
+    resetMicState,
+    clearAssistantMicHold,
+  };
+}

package/src/voice/useVoiceTranscriptMessages.ts

@@ -0,0 +1,173 @@
+import type {
+  Message,
+  VoiceDoneEvent,
+  VoiceTranscriptEvent,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import { mergeStreamingTranscript } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import { useCallback, useRef } from 'react';
+import type { InteractionMode } from '../context/AgentAssistantContext';
+
+type VoiceTranscriptAgentApi = {
+  getMessages: () => Message[];
+  setMessages: (messages: Message[]) => void;
+  syncVoiceTurnHistory: (options?: { last?: number }) => Promise<void>;
+};
+
+const STREAM_PREFIX = 'voice-stream-';
+
+function voiceMeta(sessionId: string | null) {
+  return {
+    voiceRealtime: true as const,
+    voiceSessionId: sessionId ?? undefined,
+  };
+}
+
+export function useVoiceTranscriptMessages(
+  api: VoiceTranscriptAgentApi,
+  interactionMode: InteractionMode,
+  voiceSessionId: string | null,
+) {
+  const streamIdRef = useRef<string | null>(null);
+  const sessionIdRef = useRef(voiceSessionId);
+  sessionIdRef.current = voiceSessionId;
+
+  const isVoiceUiActive = useCallback(
+    () => interactionMode === 'voice' && sessionIdRef.current != null,
+    [interactionMode],
+  );
+
+  const upsertStreaming = useCallback(
+    (text: string) => {
+      const messages = api.getMessages();
+      let streamId = streamIdRef.current;
+      if (!streamId) {
+        streamId = `${STREAM_PREFIX}${Date.now()}`;
+        streamIdRef.current = streamId;
+      }
+      const idx = messages.findIndex((m) => m.id === streamId);
+      const partialContent =
+        idx >= 0
+          ? mergeStreamingTranscript(messages[idx]?.partialContent ?? '', text)
+          : text;
+      const meta = voiceMeta(sessionIdRef.current);
+      if (idx >= 0) {
+        api.setMessages(
+          messages.map((m, i) =>
+            i === idx
+              ? { ...m, partialContent, isStreaming: true, metadata: { ...m.metadata, ...meta } }
+              : m,
+          ),
+        );
+        return;
+      }
+      api.setMessages([
+        ...messages,
+        {
+          id: streamId,
+          role: 'assistant',
+          content: '',
+          partialContent,
+          isStreaming: true,
+          timestamp: new Date().toISOString(),
+          metadata: meta,
+        },
+      ]);
+    },
+    [api],
+  );
+
+  const finalizeAssistant = useCallback(
+    (text: string, messageId?: string | null) => {
+      const trimmed = text.trim();
+      streamIdRef.current = null;
+      if (!trimmed) return;
+
+      const messages = api.getMessages();
+      const streamIdx = messages.findIndex((m) => m.isStreaming && m.role === 'assistant');
+      if (streamIdx >= 0) {
+        api.setMessages(
+          messages.map((m, i) =>
+            i === streamIdx
+              ? {
+                  ...m,
+                  id: messageId ?? m.id,
+                  content: trimmed,
+                  partialContent: undefined,
+                  isStreaming: false,
+                  metadata: { ...m.metadata, ...voiceMeta(sessionIdRef.current) },
+                }
+              : m,
+          ),
+        );
+        return;
+      }
+      const last = messages[messages.length - 1];
+      if (last?.role === 'assistant' && last.content === trimmed) return;
+      api.setMessages([
+        ...messages,
+        {
+          id: messageId ?? `voice-asst-${Date.now()}`,
+          role: 'assistant',
+          content: trimmed,
+          timestamp: new Date().toISOString(),
+          metadata: voiceMeta(sessionIdRef.current),
+        },
+      ]);
+    },
+    [api],
+  );
+
+  const handleTranscript = useCallback(
+    (event: VoiceTranscriptEvent) => {
+      if (!isVoiceUiActive()) return;
+      const text = event.text?.trim() ?? '';
+      if (event.role === 'assistant') {
+        // Keep one streaming bubble for the whole turn; finalize only in handleDone.
+        if (text) upsertStreaming(text);
+        return;
+      }
+      if (event.role === 'user' && !event.interim && text) {
+        const messages = api.getMessages();
+        const last = messages[messages.length - 1];
+        if (last?.role === 'user' && last.content === text) return;
+        api.setMessages([
+          ...messages,
+          {
+            id: `voice-user-${Date.now()}`,
+            role: 'user',
+            content: text,
+            timestamp: new Date().toISOString(),
+            metadata: voiceMeta(sessionIdRef.current),
+          },
+        ]);
+      }
+    },
+    [api, finalizeAssistant, isVoiceUiActive, upsertStreaming],
+  );
+
+  const handleDone = useCallback(
+    (event: VoiceDoneEvent) => {
+      if (!isVoiceUiActive()) return;
+      if (event.guardrailsBlocked || event.billingBlocked || event.error) {
+        streamIdRef.current = null;
+        return;
+      }
+      const reply = event.replyText?.trim() ?? '';
+      if (reply) {
+        finalizeAssistant(reply, event.assistantMessageId ?? undefined);
+      } else {
+        streamIdRef.current = null;
+      }
+      void api.syncVoiceTurnHistory({ last: 20 }).catch((err) => {
+        console.warn('[nxtlinq] syncVoiceTurnHistory after voice turn failed', err);
+      });
+    },
+    [api, finalizeAssistant, isVoiceUiActive],
+  );
+
+  const clearVoiceStream = useCallback(() => {
+    streamIdRef.current = null;
+  }, []);
+
+  return { handleTranscript, handleDone, clearVoiceStream };
+}

package/src/voice/voiceMicConstants.ts

@@ -0,0 +1,13 @@
+import type { VoiceStatus } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+
+export const ASSISTANT_MIC_HOLD_STATUSES: ReadonlySet<VoiceStatus> = new Set([
+  'transcribing',
+  'thinking',
+  'generating',
+  'speaking',
+]);
+
+export const SPEAKER_ACTIVE_STATUSES: ReadonlySet<VoiceStatus> = new Set([
+  'generating',
+  'speaking',
+]);