@meetsmore-oss/use-ai-client 1.9.0 → 1.9.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 export { z } from 'zod';
-import { ToolAnnotations, ToolDefinition, WorkflowStatus, FeedbackValue, AgentInfo, MultimodalContent, UseAIForwardedProps, AGUIEvent, Message as Message$1, UseAIClientMessage, ToolApprovalRequestEvent } from '@meetsmore-oss/use-ai-core';
+import { ToolAnnotations, ToolDefinition, WorkflowStatus, MultimodalContent, UseAIForwardedProps, AGUIEvent, Message as Message$1, AgentInfo, UseAIClientMessage, FeedbackValue, ToolApprovalRequestEvent } from '@meetsmore-oss/use-ai-core';
 export { AgentInfo, ToolAnnotations, ToolDefinition } from '@meetsmore-oss/use-ai-core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1, { MutableRefObject, RefObject, ReactNode } from 'react';
@@ -325,6 +325,245 @@ interface UseAIConfig {
     serverUrl: string;
 }
 
+/**
+ * Handler for AG-UI events from the server.
+ */
+type AGUIEventHandler = (event: AGUIEvent) => void;
+/**
+ * Simplified message handler for text responses.
+ */
+type MessageHandler = (content: string) => void;
+/**
+ * Tool call handler that receives the tool name, arguments, and a callback to send the result.
+ */
+type ToolCallHandler = (toolCallId: string, toolName: string, args: Record<string, unknown>) => void;
+/**
+ * Socket.IO client for communicating with the UseAI server.
+ * Uses the AG-UI protocol (https://docs.ag-ui.com/), so will be compatible with other AG-UI compliant servers.
+ *
+ * Handles:
+ * - Connection management and automatic reconnection
+ * - Sending RunAgentInput messages to server
+ * - Parsing AG-UI event streams from server
+ * - Tool execution coordination
+ *
+ * You probably don't need to use this directly, instead use {@link UseAIProvider}.
+ */
+declare class UseAIClient {
+    private serverUrl;
+    private socket;
+    private eventHandlers;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private _threadId;
+    private _tools;
+    private _messages;
+    private _state;
+    private _availableAgents;
+    private _defaultAgent;
+    private _selectedAgent;
+    private agentsChangeHandlers;
+    private connectionStateHandlers;
+    private _currentMessageId;
+    private _currentMessageContent;
+    private _currentAssistantMessage;
+    private _currentAssistantToolCalls;
+    private _pendingToolResults;
+    private currentToolCalls;
+    private _langfuseEnabled;
+    private langfuseConfigHandlers;
+    /**
+     * Creates a new UseAI client instance.
+     *
+     * @param serverUrl - The WebSocket URL of the UseAI server
+     */
+    constructor(serverUrl: string);
+    /**
+     * Establishes a Socket.IO connection to the server.
+     * Connection state changes are notified via onConnectionStateChange().
+     * Socket.IO handles reconnection automatically.
+     */
+    connect(): void;
+    private handleEvent;
+    /**
+     * Registers available tools and optional state with the server.
+     * This updates the session state for future agent runs.
+     *
+     * @param tools - Array of tool definitions to register
+     * @param state - Optional state object to provide to the AI.
+     */
+    registerTools(tools: ToolDefinition[], state?: unknown): void;
+    /**
+     * Updates the state without re-registering tools.
+     * Call this before sendPrompt to ensure the AI sees the latest UI state.
+     *
+     * @param state - The current state object to provide to the AI
+     */
+    updateState(state: unknown): void;
+    /**
+     * Sends a user prompt to the AI.
+     *
+     * @param prompt - The user's prompt/question (text part)
+     * @param multimodalContent - Optional multimodal content (text, images, files)
+     * @param forwardedProps - Optional props to forward to the server (e.g., telemetryMetadata, mcpHeaders).
+     *                         Internally merged with other forwardedProps.
+     */
+    sendPrompt(prompt: string, multimodalContent?: MultimodalContent[], forwardedProps?: UseAIForwardedProps): Promise<void>;
+    /**
+     * Sends the result of a tool execution back to the server.
+     *
+     * @param toolCallId - The ID of the tool call being responded to
+     * @param result - The result returned by the tool execution
+     * @param state - Optional updated state to send back to the AI
+     */
+    sendToolResponse(toolCallId: string, result: unknown, state?: unknown): void;
+    /**
+     * Sends a tool approval response back to the server.
+     *
+     * @param toolCallId - The ID of the tool call being approved/rejected
+     * @param approved - Whether the tool execution is approved
+     * @param reason - Optional reason for rejection (shown to AI)
+     */
+    sendToolApprovalResponse(toolCallId: string, approved: boolean, reason?: string): void;
+    /**
+     * Retrieves accumulated tool call data for a specific tool call ID.
+     * Used to get the complete tool name and arguments after they've been streamed
+     * across multiple TOOL_CALL_ARGS events.
+     *
+     * @param toolCallId - The ID of the tool call
+     * @returns Object with tool name and accumulated arguments, or undefined if not found
+     */
+    getToolCallData(toolCallId: string): {
+        name: string;
+        args: string;
+    } | undefined;
+    /**
+     * Registers an AG-UI event handler for receiving server events.
+     *
+     * @param id - Unique identifier for this handler
+     * @param handler - Callback function to handle incoming AG-UI events
+     * @returns Cleanup function to unregister the handler
+     */
+    onEvent(id: string, handler: AGUIEventHandler): () => void;
+    /**
+     * Helper method to listen for text message content.
+     * Aggregates TEXT_MESSAGE_CONTENT events and calls handler with complete messages.
+     *
+     * @param handler - Callback function to handle complete text messages
+     * @returns Cleanup function
+     */
+    onTextMessage(handler: MessageHandler): () => void;
+    /**
+     * Helper method to listen for tool call requests.
+     * Aggregates TOOL_CALL_* events and calls handler with complete tool calls.
+     *
+     * @param handler - Callback function to handle tool calls
+     * @returns Cleanup function
+     */
+    onToolCall(handler: ToolCallHandler): () => void;
+    /**
+     * Gets the current accumulated message content (useful during streaming).
+     */
+    get currentMessageContent(): string;
+    /**
+     * Gets the current thread ID for this session.
+     * Generates a new one if not set.
+     */
+    get threadId(): string;
+    /**
+     * Gets the current conversation messages.
+     */
+    get messages(): Message$1[];
+    /**
+     * Gets the current state.
+     */
+    get state(): unknown;
+    /**
+     * Gets the list of available agents from the server.
+     */
+    get availableAgents(): AgentInfo[];
+    /**
+     * Gets the default agent ID from the server.
+     */
+    get defaultAgent(): string | null;
+    /**
+     * Gets the currently selected agent ID.
+     * Returns null if using server default.
+     */
+    get selectedAgent(): string | null;
+    /**
+     * Gets the effective agent ID (selected or default).
+     */
+    get currentAgent(): string | null;
+    /**
+     * Sets the agent to use for requests.
+     * Pass null to use the server default.
+     *
+     * @param agentId - The agent ID to use, or null for server default
+     */
+    setAgent(agentId: string | null): void;
+    /**
+     * Subscribes to agent changes (when server sends available agents).
+     *
+     * @param handler - Callback function receiving agents list and default agent
+     * @returns Cleanup function to unsubscribe
+     */
+    onAgentsChange(handler: (agents: AgentInfo[], defaultAgent: string | null) => void): () => void;
+    /**
+     * Subscribes to connection state changes.
+     * This is called on both initial connection and reconnection.
+     *
+     * @param handler - Callback function receiving connection state (true = connected, false = disconnected)
+     * @returns Cleanup function to unsubscribe
+     */
+    onConnectionStateChange(handler: (connected: boolean) => void): () => void;
+    /**
+     * Sets the thread ID for this session.
+     * When the thread ID changes, conversation state is cleared to prevent history bleeding.
+     * Use this when switching between different chat conversations.
+     *
+     * @param threadId - The thread/chat ID to use (typically the chatId)
+     */
+    setThreadId(threadId: string): void;
+    /**
+     * Loads messages into the conversation history (for resuming from storage).
+     * @param messages - Array of messages to load
+     */
+    loadMessages(messages: Message$1[]): void;
+    /**
+     * Clears the conversation history and resets the thread.
+     */
+    clearConversation(): void;
+    send(message: UseAIClientMessage): void;
+    /**
+     * Closes the Socket.IO connection to the server.
+     */
+    disconnect(): void;
+    /**
+     * Checks if the client is currently connected to the server.
+     *
+     * @returns true if connected, false otherwise
+     */
+    isConnected(): boolean;
+    /**
+     * Subscribes to Langfuse config changes.
+     *
+     * @param handler - Callback function receiving langfuse enabled status
+     * @returns Cleanup function to unsubscribe
+     */
+    onLangfuseConfigChange(handler: (enabled: boolean) => void): () => void;
+    /**
+     * Submits feedback for an assistant message.
+     * Sends feedback to the server, which forwards it to Langfuse.
+     *
+     * @param messageId - The client-side message ID
+     * @param traceId - The Langfuse trace ID (runId from RUN_FINISHED)
+     * @param feedback - 'upvote' for positive, 'downvote' for negative, null to remove
+     */
+    submitFeedback(messageId: string, traceId: string, feedback: FeedbackValue): void;
+}
+
 /**
  * Default maximum file size (10MB)
  */
@@ -476,7 +715,7 @@ type ChatMetadata = Record<string, unknown>;
  * Display mode for chat messages.
  * Determines the visual styling of the message bubble.
  */
-type MessageDisplayMode$1 = 'default' | 'error';
+type MessageDisplayMode = 'default' | 'error';
 /**
  * Text content part for persisted messages.
  */
@@ -506,17 +745,38 @@ type PersistedMessageContent = string | PersistedContentPart[];
  * Message format for persisted chat history.
  * Compatible with AI SDK's UIMessage format for future integration.
  */
+/**
+ * Tool call entry on an assistant message.
+ * Matches the AG-UI MessageToolCall format.
+ */
+interface PersistedToolCall {
+    /** @example "toolu_01abc123" */
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        /** JSON-serialized arguments */
+        arguments: string;
+    };
+}
 interface PersistedMessage {
     id: string;
     role: 'user' | 'assistant' | 'tool';
     /** Content can be a string or multimodal content array */
     content: PersistedMessageContent;
     createdAt: Date;
-    displayMode?: MessageDisplayMode$1;
+    displayMode?: MessageDisplayMode;
     /** Langfuse trace ID for feedback tracking (only for assistant messages) */
     traceId?: string;
     /** User feedback on this message (only for assistant messages) */
     feedback?: FeedbackValue;
+    /** Tool calls made by the assistant in this message (only for assistant messages) */
+    toolCalls?: PersistedToolCall[];
+    /**
+     * ID of the tool call this message is a result of (only for tool messages)
+     * @example "toolu_01abc123"
+     */
+    toolCallId?: string;
 }
 /**
  * Represents a stored chat conversation.
@@ -659,11 +919,137 @@ declare function generateCommandId(): string;
  */
 declare function validateCommandName(name: string): string | null;
 
+interface RegisterToolsOptions {
+    /** Mark component as invisible (no visual state, skip prompt wait) */
+    invisible?: boolean;
+}
 /**
- * Default text labels for the chat UI.
- * Use for internationalization (i18n) or branding.
+ * Pending tool approval request state.
  */
-declare const defaultStrings: {
+interface PendingToolApproval {
+    toolCallId: string;
+    toolCallName: string;
+    toolCallArgs: Record<string, unknown>;
+    annotations?: ToolAnnotations;
+    /** Optional message explaining why approval is needed (runtime approval) */
+    message?: string;
+    /** Optional metadata for the approval request (runtime approval) */
+    metadata?: Record<string, unknown>;
+}
+interface UseToolSystemOptions {
+    /** Reference to the UseAI client for sending responses */
+    clientRef: RefObject<UseAIClient | null>;
+    /** Builds the aggregated state from all registered prompts */
+    buildState: () => unknown;
+}
+interface UseToolSystemReturn {
+    /** Registers tools for a specific component */
+    registerTools: (id: string, tools: ToolsDefinition, options?: RegisterToolsOptions) => void;
+    /** Unregisters tools for a specific component */
+    unregisterTools: (id: string) => void;
+    /** Checks if a component is marked as invisible */
+    isInvisible: (id: string) => boolean;
+    /** All tools aggregated from registered components */
+    aggregatedTools: ToolsDefinition;
+    /** Whether any tools are registered */
+    hasTools: boolean;
+    /** Ref to current aggregated tools (for use in closures) */
+    aggregatedToolsRef: MutableRefObject<ToolsDefinition>;
+    /** Signals that a component has completed its registration in useLayoutEffect */
+    signalReady: (id: string) => void;
+    /** Current tool registry version (increments when tools change) */
+    toolRegistryVersion: number;
+    /** Registers a waiter function for a component (called when tool exec needs to wait for re-render) */
+    registerWaiter: (id: string, waiter: () => Promise<void>) => void;
+    /** Unregisters a waiter function */
+    unregisterWaiter: (id: string) => void;
+    /** All pending tool approval requests */
+    pendingApprovals: PendingToolApproval[];
+    /** Handle a tool approval request event from the server */
+    handleApprovalRequest: (event: ToolApprovalRequestEvent) => void;
+    /** Execute a tool call and send the response to the server */
+    executeToolCall: (toolCallId: string, name: string, input: unknown) => Promise<void>;
+    /** Store a tool call as pending approval (deferred execution) */
+    storePendingToolCall: (toolCallId: string, name: string, input: unknown, toolCallData: {
+        name: string;
+        args: string;
+    }) => void;
+    /** Approve all pending tool calls and execute them */
+    approveAll: () => Promise<void>;
+    /** Reject all pending tool calls with optional reason */
+    rejectAll: (reason?: string) => void;
+}
+/**
+ * Unified hook for the tool lifecycle: registration, waiter coordination,
+ * and execution (including approval flow).
+ *
+ * Merges what were previously three separate concerns:
+ * - Tool registry (registration, aggregation, ownership tracking)
+ * - Waiters (waiting for component re-renders after tool execution)
+ * - Tool execution (running tools, sending responses, approval flow)
+ *
+ * The only external dependency is `buildState` from prompt management,
+ * which provides the aggregated app state sent alongside tool responses.
+ */
+declare function useToolSystem({ clientRef, buildState, }: UseToolSystemOptions): UseToolSystemReturn;
+
+/**
+ * Options for programmatically sending a message via sendMessage().
+ */
+interface SendMessageOptions {
+    /** Start a new chat before sending. Default: false (continue existing chat) */
+    newChat?: boolean;
+    /** File attachments to include with the message */
+    attachments?: File[];
+    /** Open the chat panel after sending. Default: true */
+    openChat?: boolean;
+    /** Metadata to set on the new chat (only used when newChat: true) */
+    metadata?: ChatMetadata;
+    /**
+     * Forwarded props for observability and configuration (e.g., telemetryMetadata, mcpHeaders).
+     * This is merged with provider-level forwardedProps (message-level takes precedence).
+     */
+    forwardedProps?: UseAIForwardedProps;
+}
+interface UseMessageQueueOptions {
+    /** The function that actually sends a message (the provider's handleSendMessage) */
+    sendFn: (message: string, attachments?: FileAttachment[], forwardedProps?: UseAIForwardedProps) => Promise<void>;
+    /** Creates a new chat */
+    createNewChat: (options?: CreateChatOptions) => Promise<string>;
+    /** Callback to open/close the chat panel */
+    setOpen?: (open: boolean) => void;
+    /** Whether the client is connected */
+    connected: boolean;
+    /** Whether the AI is currently loading/processing */
+    loading: boolean;
+    /** Whether there's a pending tool approval blocking the queue */
+    hasPendingApproval: boolean;
+}
+interface UseMessageQueueReturn {
+    /**
+     * Programmatically send a message to the chat.
+     * Messages are queued and processed one at a time.
+     * Throws on failure (e.g., not connected, no sendFn).
+     */
+    sendMessage: (message: string, options?: SendMessageOptions) => Promise<void>;
+}
+/**
+ * Hook for queuing and sending programmatic messages.
+ *
+ * Handles:
+ * - Message queuing (one at a time)
+ * - Waiting for loading + approval to complete between messages
+ * - Creating new chats before sending
+ * - Opening the chat panel after sending
+ * - Converting File[] to FileAttachment[]
+ */
+declare function useMessageQueue({ sendFn, createNewChat, setOpen, connected, loading, hasPendingApproval, }: UseMessageQueueOptions): UseMessageQueueReturn;
+
+/**
+ * Default text labels for the chat UI.
+ * Use for internationalization (i18n) or branding.
+ */
+declare const defaultStrings: {
     header: {
         /** Header title when no chat history feature */
         aiAssistant: string;
@@ -770,542 +1156,96 @@ declare const defaultStrings: {
     };
 };
 /**
- * Customizable text labels for the chat UI.
- */
-type UseAIStrings = typeof defaultStrings;
-/**
- * Hook to access the current strings.
- * Returns the strings from UseAIProvider, or defaults if not inside a provider.
- *
- * @example
- * ```tsx
- * function MyComponent() {
- *   const strings = useStrings();
- *   return <button>{strings.input.send}</button>;
- * }
- * ```
- */
-declare function useStrings(): UseAIStrings;
-
-/**
- * Default theme configuration for the chat UI.
- * All colors support CSS color values (hex, rgb, hsl, gradients, etc.)
- */
-declare const defaultTheme: {
-    /** Primary color for buttons, links, active states */
-    primaryColor: string;
-    /** Primary gradient for user messages and buttons */
-    primaryGradient: string;
-    /** Translucent primary color for overlays (e.g., drop zone) */
-    primaryColorTranslucent: string;
-    /** Panel background color */
-    backgroundColor: string;
-    /** Assistant message bubble background */
-    assistantMessageBackground: string;
-    /** Hover background for buttons and items */
-    hoverBackground: string;
-    /** Active/selected item background */
-    activeBackground: string;
-    /** Disabled button background */
-    buttonDisabledBackground: string;
-    /** Primary text color */
-    textColor: string;
-    /** Secondary/muted text color */
-    secondaryTextColor: string;
-    /** Placeholder text color */
-    placeholderTextColor: string;
-    /** Online status indicator color */
-    onlineColor: string;
-    /** Offline status indicator color */
-    offlineColor: string;
-    /** Unread notification indicator color */
-    unreadIndicatorColor: string;
-    /** Error message background */
-    errorBackground: string;
-    /** Error message text color */
-    errorTextColor: string;
-    /** Danger/destructive action color (e.g., delete) */
-    dangerColor: string;
-    /** Border color for dividers and inputs */
-    borderColor: string;
-    /** Dashed border color (e.g., file placeholder) */
-    dashedBorderColor: string;
-    /** Panel box shadow */
-    panelShadow: string;
-    /** Dropdown box shadow */
-    dropdownShadow: string;
-    /** Button box shadow */
-    buttonShadow: string;
-    /** Button hover box shadow */
-    buttonHoverShadow: string;
-    /** Font family */
-    fontFamily: string;
-    /** Modal backdrop color */
-    backdropColor: string;
-};
-/**
- * Theme configuration for the chat UI.
- */
-type UseAITheme = typeof defaultTheme;
-/**
- * Hook to access the current theme.
- * Returns the theme from UseAIProvider, or defaults if not inside a provider.
- *
- * @example
- * ```tsx
- * function MyComponent() {
- *   const theme = useTheme();
- *   return <div style={{ color: theme.primaryColor }}>Hello</div>;
- * }
- * ```
- */
-declare function useTheme(): UseAITheme;
-
-type UseAIChatPanelStrings = UseAIStrings;
-type UseAIChatPanelTheme = UseAITheme;
-/**
- * Display mode for chat messages.
- */
-type MessageDisplayMode = 'default' | 'error';
-/**
- * Represents a single message in the AI conversation.
- */
-interface Message {
-    /** Unique identifier for the message */
-    id: string;
-    /** The role of the message sender */
-    role: 'user' | 'assistant';
-    /** The message content - string or multimodal content */
-    content: PersistedMessageContent;
-    /** When the message was created */
-    timestamp: Date;
-    /** Display mode for styling the message bubble */
-    displayMode?: MessageDisplayMode;
-    /** Langfuse trace ID for feedback tracking (only for assistant messages) */
-    traceId?: string;
-    /** User feedback on this message (only for assistant messages) */
-    feedback?: FeedbackValue;
-}
-/**
- * Props for the chat panel component.
- */
-interface UseAIChatPanelProps {
-    onSendMessage: (message: string, attachments?: FileAttachment[]) => void;
-    messages: Message[];
-    loading: boolean;
-    connected: boolean;
-    /** Currently streaming text from assistant (real-time updates) */
-    streamingText?: string;
-    currentChatId?: string | null;
-    onNewChat?: () => Promise<string | void>;
-    onLoadChat?: (chatId: string) => Promise<void>;
-    onDeleteChat?: (chatId: string) => Promise<void>;
-    onListChats?: () => Promise<Array<Omit<Chat, 'messages'>>>;
-    /** Gets the current chat */
-    onGetChat?: () => Promise<Chat | null>;
-    suggestions?: string[];
-    availableAgents?: AgentInfo[];
-    defaultAgent?: string | null;
-    selectedAgent?: string | null;
-    onAgentChange?: (agentId: string | null) => void;
-    fileUploadConfig?: FileUploadConfig;
-    /** File processing state for send-time transformations (e.g., OCR) */
-    fileProcessing?: FileProcessingState | null;
-    commands?: SavedCommand[];
-    onSaveCommand?: (name: string, text: string) => Promise<string>;
-    onRenameCommand?: (id: string, newName: string) => Promise<void>;
-    onDeleteCommand?: (id: string) => Promise<void>;
-    /** Optional close button to render in header (for floating mode) */
-    closeButton?: React$1.ReactNode;
-    /** Currently executing tool info for status display */
-    executingTool?: {
-        displayText: string;
-    } | null;
-    /** Whether feedback buttons are enabled (requires Langfuse on server) */
-    feedbackEnabled?: boolean;
-    /** Callback when user submits feedback on a message */
-    onFeedback?: (messageId: string, traceId: string, feedback: FeedbackValue) => void;
-    /** Pending tool approvals awaiting user confirmation */
-    pendingApprovals?: Array<{
-        toolCallId: string;
-        toolCallName: string;
-        toolCallArgs: Record<string, unknown>;
-        annotations?: ToolAnnotations;
-    }>;
-    /** Callback to approve all pending tool calls */
-    onApproveToolCall?: () => void;
-    /** Callback to reject all pending tool calls */
-    onRejectToolCall?: (reason?: string) => void;
-}
-/**
- * Chat panel content - fills its container.
- * Use directly for embedded mode, or wrap with UseAIFloatingChatWrapper for floating mode.
- */
-declare function UseAIChatPanel({ onSendMessage, messages, loading, connected, streamingText, currentChatId, onNewChat, onLoadChat, onDeleteChat, onListChats, onGetChat, suggestions, availableAgents, defaultAgent, selectedAgent, onAgentChange, fileUploadConfig, fileProcessing, commands, onSaveCommand, onRenameCommand, onDeleteCommand, closeButton, executingTool, feedbackEnabled, onFeedback, pendingApprovals, onApproveToolCall, onRejectToolCall, }: UseAIChatPanelProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Handler for AG-UI events from the server.
- */
-type AGUIEventHandler = (event: AGUIEvent) => void;
-/**
- * Simplified message handler for text responses.
- */
-type MessageHandler = (content: string) => void;
-/**
- * Tool call handler that receives the tool name, arguments, and a callback to send the result.
- */
-type ToolCallHandler = (toolCallId: string, toolName: string, args: Record<string, unknown>) => void;
-/**
- * Socket.IO client for communicating with the UseAI server.
- * Uses the AG-UI protocol (https://docs.ag-ui.com/), so will be compatible with other AG-UI compliant servers.
- *
- * Handles:
- * - Connection management and automatic reconnection
- * - Sending RunAgentInput messages to server
- * - Parsing AG-UI event streams from server
- * - Tool execution coordination
- *
- * You probably don't need to use this directly, instead use {@link UseAIProvider}.
- */
-declare class UseAIClient {
-    private serverUrl;
-    private socket;
-    private eventHandlers;
-    private reconnectAttempts;
-    private maxReconnectAttempts;
-    private reconnectDelay;
-    private _threadId;
-    private _tools;
-    private _messages;
-    private _state;
-    private _availableAgents;
-    private _defaultAgent;
-    private _selectedAgent;
-    private agentsChangeHandlers;
-    private connectionStateHandlers;
-    private _currentMessageId;
-    private _currentMessageContent;
-    private _currentAssistantMessage;
-    private _currentAssistantToolCalls;
-    private currentToolCalls;
-    private _langfuseEnabled;
-    private langfuseConfigHandlers;
-    /**
-     * Creates a new UseAI client instance.
-     *
-     * @param serverUrl - The WebSocket URL of the UseAI server
-     */
-    constructor(serverUrl: string);
-    /**
-     * Establishes a Socket.IO connection to the server.
-     * Connection state changes are notified via onConnectionStateChange().
-     * Socket.IO handles reconnection automatically.
-     */
-    connect(): void;
-    private handleEvent;
-    /**
-     * Registers available tools and optional state with the server.
-     * This updates the session state for future agent runs.
-     *
-     * @param tools - Array of tool definitions to register
-     * @param state - Optional state object to provide to the AI.
-     */
-    registerTools(tools: ToolDefinition[], state?: unknown): void;
-    /**
-     * Updates the state without re-registering tools.
-     * Call this before sendPrompt to ensure the AI sees the latest UI state.
-     *
-     * @param state - The current state object to provide to the AI
-     */
-    updateState(state: unknown): void;
-    /**
-     * Sends a user prompt to the AI.
-     *
-     * @param prompt - The user's prompt/question (text part)
-     * @param multimodalContent - Optional multimodal content (text, images, files)
-     * @param forwardedProps - Optional props to forward to the server (e.g., telemetryMetadata, mcpHeaders).
-     *                         Internally merged with other forwardedProps.
-     */
-    sendPrompt(prompt: string, multimodalContent?: MultimodalContent[], forwardedProps?: UseAIForwardedProps): Promise<void>;
-    /**
-     * Sends the result of a tool execution back to the server.
-     *
-     * @param toolCallId - The ID of the tool call being responded to
-     * @param result - The result returned by the tool execution
-     * @param state - Optional updated state to send back to the AI
-     */
-    sendToolResponse(toolCallId: string, result: unknown, state?: unknown): void;
-    /**
-     * Sends a tool approval response back to the server.
-     *
-     * @param toolCallId - The ID of the tool call being approved/rejected
-     * @param approved - Whether the tool execution is approved
-     * @param reason - Optional reason for rejection (shown to AI)
-     */
-    sendToolApprovalResponse(toolCallId: string, approved: boolean, reason?: string): void;
-    /**
-     * Retrieves accumulated tool call data for a specific tool call ID.
-     * Used to get the complete tool name and arguments after they've been streamed
-     * across multiple TOOL_CALL_ARGS events.
-     *
-     * @param toolCallId - The ID of the tool call
-     * @returns Object with tool name and accumulated arguments, or undefined if not found
-     */
-    getToolCallData(toolCallId: string): {
-        name: string;
-        args: string;
-    } | undefined;
-    /**
-     * Registers an AG-UI event handler for receiving server events.
-     *
-     * @param id - Unique identifier for this handler
-     * @param handler - Callback function to handle incoming AG-UI events
-     * @returns Cleanup function to unregister the handler
-     */
-    onEvent(id: string, handler: AGUIEventHandler): () => void;
-    /**
-     * Helper method to listen for text message content.
-     * Aggregates TEXT_MESSAGE_CONTENT events and calls handler with complete messages.
-     *
-     * @param handler - Callback function to handle complete text messages
-     * @returns Cleanup function
-     */
-    onTextMessage(handler: MessageHandler): () => void;
-    /**
-     * Helper method to listen for tool call requests.
-     * Aggregates TOOL_CALL_* events and calls handler with complete tool calls.
-     *
-     * @param handler - Callback function to handle tool calls
-     * @returns Cleanup function
-     */
-    onToolCall(handler: ToolCallHandler): () => void;
-    /**
-     * Gets the current accumulated message content (useful during streaming).
-     */
-    get currentMessageContent(): string;
-    /**
-     * Gets the current thread ID for this session.
-     * Generates a new one if not set.
-     */
-    get threadId(): string;
-    /**
-     * Gets the current conversation messages.
-     */
-    get messages(): Message$1[];
-    /**
-     * Gets the current state.
-     */
-    get state(): unknown;
-    /**
-     * Gets the list of available agents from the server.
-     */
-    get availableAgents(): AgentInfo[];
-    /**
-     * Gets the default agent ID from the server.
-     */
-    get defaultAgent(): string | null;
-    /**
-     * Gets the currently selected agent ID.
-     * Returns null if using server default.
-     */
-    get selectedAgent(): string | null;
-    /**
-     * Gets the effective agent ID (selected or default).
-     */
-    get currentAgent(): string | null;
-    /**
-     * Sets the agent to use for requests.
-     * Pass null to use the server default.
-     *
-     * @param agentId - The agent ID to use, or null for server default
-     */
-    setAgent(agentId: string | null): void;
-    /**
-     * Subscribes to agent changes (when server sends available agents).
-     *
-     * @param handler - Callback function receiving agents list and default agent
-     * @returns Cleanup function to unsubscribe
-     */
-    onAgentsChange(handler: (agents: AgentInfo[], defaultAgent: string | null) => void): () => void;
-    /**
-     * Subscribes to connection state changes.
-     * This is called on both initial connection and reconnection.
-     *
-     * @param handler - Callback function receiving connection state (true = connected, false = disconnected)
-     * @returns Cleanup function to unsubscribe
-     */
-    onConnectionStateChange(handler: (connected: boolean) => void): () => void;
-    /**
-     * Sets the thread ID for this session.
-     * When the thread ID changes, conversation state is cleared to prevent history bleeding.
-     * Use this when switching between different chat conversations.
-     *
-     * @param threadId - The thread/chat ID to use (typically the chatId)
-     */
-    setThreadId(threadId: string): void;
-    /**
-     * Loads messages into the conversation history (for resuming from storage).
-     * @param messages - Array of messages to load
-     */
-    loadMessages(messages: Message$1[]): void;
-    /**
-     * Clears the conversation history and resets the thread.
-     */
-    clearConversation(): void;
-    send(message: UseAIClientMessage): void;
-    /**
-     * Closes the Socket.IO connection to the server.
-     */
-    disconnect(): void;
-    /**
-     * Checks if the client is currently connected to the server.
-     *
-     * @returns true if connected, false otherwise
-     */
-    isConnected(): boolean;
-    /**
-     * Subscribes to Langfuse config changes.
-     *
-     * @param handler - Callback function receiving langfuse enabled status
-     * @returns Cleanup function to unsubscribe
-     */
-    onLangfuseConfigChange(handler: (enabled: boolean) => void): () => void;
-    /**
-     * Submits feedback for an assistant message.
-     * Sends feedback to the server, which forwards it to Langfuse.
-     *
-     * @param messageId - The client-side message ID
-     * @param traceId - The Langfuse trace ID (runId from RUN_FINISHED)
-     * @param feedback - 'upvote' for positive, 'downvote' for negative, null to remove
-     */
-    submitFeedback(messageId: string, traceId: string, feedback: FeedbackValue): void;
-}
-
-interface RegisterToolsOptions {
-    /** Mark component as invisible (no visual state, skip prompt wait) */
-    invisible?: boolean;
-}
-/**
- * Pending tool approval request state.
+ * Customizable text labels for the chat UI.
  */
-interface PendingToolApproval {
-    toolCallId: string;
-    toolCallName: string;
-    toolCallArgs: Record<string, unknown>;
-    annotations?: ToolAnnotations;
-    /** Optional message explaining why approval is needed (runtime approval) */
-    message?: string;
-    /** Optional metadata for the approval request (runtime approval) */
-    metadata?: Record<string, unknown>;
-}
-interface UseToolSystemOptions {
-    /** Reference to the UseAI client for sending responses */
-    clientRef: RefObject<UseAIClient | null>;
-    /** Builds the aggregated state from all registered prompts */
-    buildState: () => unknown;
-}
-interface UseToolSystemReturn {
-    /** Registers tools for a specific component */
-    registerTools: (id: string, tools: ToolsDefinition, options?: RegisterToolsOptions) => void;
-    /** Unregisters tools for a specific component */
-    unregisterTools: (id: string) => void;
-    /** Checks if a component is marked as invisible */
-    isInvisible: (id: string) => boolean;
-    /** All tools aggregated from registered components */
-    aggregatedTools: ToolsDefinition;
-    /** Whether any tools are registered */
-    hasTools: boolean;
-    /** Ref to current aggregated tools (for use in closures) */
-    aggregatedToolsRef: MutableRefObject<ToolsDefinition>;
-    /** Signals that a component has completed its registration in useLayoutEffect */
-    signalReady: (id: string) => void;
-    /** Current tool registry version (increments when tools change) */
-    toolRegistryVersion: number;
-    /** Registers a waiter function for a component (called when tool exec needs to wait for re-render) */
-    registerWaiter: (id: string, waiter: () => Promise<void>) => void;
-    /** Unregisters a waiter function */
-    unregisterWaiter: (id: string) => void;
-    /** All pending tool approval requests */
-    pendingApprovals: PendingToolApproval[];
-    /** Handle a tool approval request event from the server */
-    handleApprovalRequest: (event: ToolApprovalRequestEvent) => void;
-    /** Execute a tool call and send the response to the server */
-    executeToolCall: (toolCallId: string, name: string, input: unknown) => Promise<void>;
-    /** Store a tool call as pending approval (deferred execution) */
-    storePendingToolCall: (toolCallId: string, name: string, input: unknown, toolCallData: {
-        name: string;
-        args: string;
-    }) => void;
-    /** Approve all pending tool calls and execute them */
-    approveAll: () => Promise<void>;
-    /** Reject all pending tool calls with optional reason */
-    rejectAll: (reason?: string) => void;
-}
+type UseAIStrings = typeof defaultStrings;
 /**
- * Unified hook for the tool lifecycle: registration, waiter coordination,
- * and execution (including approval flow).
- *
- * Merges what were previously three separate concerns:
- * - Tool registry (registration, aggregation, ownership tracking)
- * - Waiters (waiting for component re-renders after tool execution)
- * - Tool execution (running tools, sending responses, approval flow)
+ * Hook to access the current strings.
+ * Returns the strings from UseAIProvider, or defaults if not inside a provider.
  *
- * The only external dependency is `buildState` from prompt management,
- * which provides the aggregated app state sent alongside tool responses.
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const strings = useStrings();
+ *   return <button>{strings.input.send}</button>;
+ * }
+ * ```
  */
-declare function useToolSystem({ clientRef, buildState, }: UseToolSystemOptions): UseToolSystemReturn;
+declare function useStrings(): UseAIStrings;
 
 /**
- * Options for programmatically sending a message via sendMessage().
+ * Default theme configuration for the chat UI.
+ * All colors support CSS color values (hex, rgb, hsl, gradients, etc.)
  */
-interface SendMessageOptions {
-    /** Start a new chat before sending. Default: false (continue existing chat) */
-    newChat?: boolean;
-    /** File attachments to include with the message */
-    attachments?: File[];
-    /** Open the chat panel after sending. Default: true */
-    openChat?: boolean;
-    /** Metadata to set on the new chat (only used when newChat: true) */
-    metadata?: ChatMetadata;
-    /**
-     * Forwarded props for observability and configuration (e.g., telemetryMetadata, mcpHeaders).
-     * This is merged with provider-level forwardedProps (message-level takes precedence).
-     */
-    forwardedProps?: UseAIForwardedProps;
-}
-interface UseMessageQueueOptions {
-    /** The function that actually sends a message (the provider's handleSendMessage) */
-    sendFn: (message: string, attachments?: FileAttachment[], forwardedProps?: UseAIForwardedProps) => Promise<void>;
-    /** Creates a new chat */
-    createNewChat: (options?: CreateChatOptions) => Promise<string>;
-    /** Callback to open/close the chat panel */
-    setOpen?: (open: boolean) => void;
-    /** Whether the client is connected */
-    connected: boolean;
-    /** Whether the AI is currently loading/processing */
-    loading: boolean;
-    /** Whether there's a pending tool approval blocking the queue */
-    hasPendingApproval: boolean;
-}
-interface UseMessageQueueReturn {
-    /**
-     * Programmatically send a message to the chat.
-     * Messages are queued and processed one at a time.
-     * Throws on failure (e.g., not connected, no sendFn).
-     */
-    sendMessage: (message: string, options?: SendMessageOptions) => Promise<void>;
-}
+declare const defaultTheme: {
+    /** Primary color for buttons, links, active states */
+    primaryColor: string;
+    /** Primary gradient for user messages and buttons */
+    primaryGradient: string;
+    /** Translucent primary color for overlays (e.g., drop zone) */
+    primaryColorTranslucent: string;
+    /** Panel background color */
+    backgroundColor: string;
+    /** Assistant message bubble background */
+    assistantMessageBackground: string;
+    /** Hover background for buttons and items */
+    hoverBackground: string;
+    /** Active/selected item background */
+    activeBackground: string;
+    /** Disabled button background */
+    buttonDisabledBackground: string;
+    /** Primary text color */
+    textColor: string;
+    /** Secondary/muted text color */
+    secondaryTextColor: string;
+    /** Placeholder text color */
+    placeholderTextColor: string;
+    /** Online status indicator color */
+    onlineColor: string;
+    /** Offline status indicator color */
+    offlineColor: string;
+    /** Unread notification indicator color */
+    unreadIndicatorColor: string;
+    /** Error message background */
+    errorBackground: string;
+    /** Error message text color */
+    errorTextColor: string;
+    /** Danger/destructive action color (e.g., delete) */
+    dangerColor: string;
+    /** Border color for dividers and inputs */
+    borderColor: string;
+    /** Dashed border color (e.g., file placeholder) */
+    dashedBorderColor: string;
+    /** Panel box shadow */
+    panelShadow: string;
+    /** Dropdown box shadow */
+    dropdownShadow: string;
+    /** Button box shadow */
+    buttonShadow: string;
+    /** Button hover box shadow */
+    buttonHoverShadow: string;
+    /** Font family */
+    fontFamily: string;
+    /** Modal backdrop color */
+    backdropColor: string;
+};
 /**
- * Hook for queuing and sending programmatic messages.
+ * Theme configuration for the chat UI.
+ */
+type UseAITheme = typeof defaultTheme;
+/**
+ * Hook to access the current theme.
+ * Returns the theme from UseAIProvider, or defaults if not inside a provider.
  *
- * Handles:
- * - Message queuing (one at a time)
- * - Waiting for loading + approval to complete between messages
- * - Creating new chats before sending
- * - Opening the chat panel after sending
- * - Converting File[] to FileAttachment[]
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const theme = useTheme();
+ *   return <div style={{ color: theme.primaryColor }}>Hello</div>;
+ * }
+ * ```
  */
-declare function useMessageQueue({ sendFn, createNewChat, setOpen, connected, loading, hasPendingApproval, }: UseMessageQueueOptions): UseMessageQueueReturn;
+declare function useTheme(): UseAITheme;
 
 /**
  * Chat management context (from useChatManagement hook).
@@ -1433,7 +1373,7 @@ interface ChatPanelProps {
     /** Callback when a message is sent */
     onSendMessage: (message: string) => void;
     /** Array of messages in the conversation */
-    messages: Message[];
+    messages: PersistedMessage[];
     /** Whether the AI is currently processing */
     loading: boolean;
     /** Whether the client is connected to the server */
@@ -1615,6 +1555,69 @@ declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton
  */
 declare function useAIContext(): UseAIContextValue;
 
+type UseAIChatPanelStrings = UseAIStrings;
+type UseAIChatPanelTheme = UseAITheme;
+/**
+ * @deprecated Use `PersistedMessage` directly instead.
+ */
+type Message = PersistedMessage;
+/**
+ * Props for the chat panel component.
+ */
+interface UseAIChatPanelProps {
+    onSendMessage: (message: string, attachments?: FileAttachment[]) => void;
+    messages: Message[];
+    loading: boolean;
+    connected: boolean;
+    /** Currently streaming text from assistant (real-time updates) */
+    streamingText?: string;
+    currentChatId?: string | null;
+    onNewChat?: () => Promise<string | void>;
+    onLoadChat?: (chatId: string) => Promise<void>;
+    onDeleteChat?: (chatId: string) => Promise<void>;
+    onListChats?: () => Promise<Array<Omit<Chat, 'messages'>>>;
+    /** Gets the current chat */
+    onGetChat?: () => Promise<Chat | null>;
+    suggestions?: string[];
+    availableAgents?: AgentInfo[];
+    defaultAgent?: string | null;
+    selectedAgent?: string | null;
+    onAgentChange?: (agentId: string | null) => void;
+    fileUploadConfig?: FileUploadConfig;
+    /** File processing state for send-time transformations (e.g., OCR) */
+    fileProcessing?: FileProcessingState | null;
+    commands?: SavedCommand[];
+    onSaveCommand?: (name: string, text: string) => Promise<string>;
+    onRenameCommand?: (id: string, newName: string) => Promise<void>;
+    onDeleteCommand?: (id: string) => Promise<void>;
+    /** Optional close button to render in header (for floating mode) */
+    closeButton?: React$1.ReactNode;
+    /** Currently executing tool info for status display */
+    executingTool?: {
+        displayText: string;
+    } | null;
+    /** Whether feedback buttons are enabled (requires Langfuse on server) */
+    feedbackEnabled?: boolean;
+    /** Callback when user submits feedback on a message */
+    onFeedback?: (messageId: string, traceId: string, feedback: FeedbackValue) => void;
+    /** Pending tool approvals awaiting user confirmation */
+    pendingApprovals?: Array<{
+        toolCallId: string;
+        toolCallName: string;
+        toolCallArgs: Record<string, unknown>;
+        annotations?: ToolAnnotations;
+    }>;
+    /** Callback to approve all pending tool calls */
+    onApproveToolCall?: () => void;
+    /** Callback to reject all pending tool calls */
+    onRejectToolCall?: (reason?: string) => void;
+}
+/**
+ * Chat panel content - fills its container.
+ * Use directly for embedded mode, or wrap with UseAIFloatingChatWrapper for floating mode.
+ */
+declare function UseAIChatPanel({ onSendMessage, messages, loading, connected, streamingText, currentChatId, onNewChat, onLoadChat, onDeleteChat, onListChats, onGetChat, suggestions, availableAgents, defaultAgent, selectedAgent, onAgentChange, fileUploadConfig, fileProcessing, commands, onSaveCommand, onRenameCommand, onDeleteCommand, closeButton, executingTool, feedbackEnabled, onFeedback, pendingApprovals, onApproveToolCall, onRejectToolCall, }: UseAIChatPanelProps): react_jsx_runtime.JSX.Element;
+
 /**
  * Props for the floating chat wrapper.
  */
@@ -2067,9 +2070,9 @@ interface UseChatManagementOptions {
     /** Reference to the UseAIClient (can be null during initialization) */
     clientRef: React.MutableRefObject<UseAIClient | null>;
     /** Current messages state (owned by provider) */
-    messages: Message[];
+    messages: PersistedMessage[];
     /** Setter for messages state (owned by provider) */
-    setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
+    setMessages: React.Dispatch<React.SetStateAction<PersistedMessage[]>>;
     /** Whether the client is connected */
     connected?: boolean;
 }
@@ -2094,8 +2097,13 @@ interface UseChatManagementReturn {
     activatePendingChat: () => string | null;
     /** Saves a user message to storage and reloads messages */
     saveUserMessage: (chatId: string, content: PersistedMessageContent) => Promise<boolean>;
-    /** Saves an AI response to storage and optionally reloads messages */
-    saveAIResponse: (content: string, displayMode?: 'default' | 'error', traceId?: string) => Promise<void>;
+    /**
+     * Saves an AI response to storage and optionally reloads messages.
+     * When turnMessages are provided, intermediate assistant+tool messages from
+     * the turn are persisted before the final assistant message, preserving the
+     * complete tool call context for conversation history.
+     */
+    saveAIResponse: (content: string, displayMode?: 'default' | 'error', traceId?: string, turnMessages?: PersistedMessage[]) => Promise<void>;
     /** Reloads messages from storage for the given chat ID */
     reloadMessages: (chatId: string) => Promise<void>;
     /** Get the current chat object. Metadata is frozen to prevent accidental mutation. */
@@ -2257,7 +2265,7 @@ interface UseServerEventsOptions {
     /** Tool system for executing tools and looking up tool metadata */
     toolSystem: UseToolSystemReturn;
     /** Saves an AI response to chat storage */
-    saveAIResponse: (content: string, displayMode?: 'default' | 'error', traceId?: string) => Promise<void>;
+    saveAIResponse: (content: string, displayMode?: 'default' | 'error', traceId?: string, turnMessages?: PersistedMessage[]) => Promise<void>;
     /** UI strings for error messages and tool execution fallbacks */
     strings: UseAIStrings;
 }
@@ -2307,7 +2315,7 @@ interface UseFeedbackOptions {
     /** Callback to get the currently displayed chat ID */
     getDisplayedChatId: () => string | null;
     /** Setter for messages state (for optimistic UI updates) */
-    setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
+    setMessages: React.Dispatch<React.SetStateAction<PersistedMessage[]>>;
 }
 interface UseFeedbackReturn {
     /** Whether Langfuse feedback is enabled on the server */