@meetsmore-oss/use-ai-client 1.6.0 → 1.8.0

package/dist/index.d.ts

@@ -1,10 +1,9 @@
 import { z } from 'zod';
 export { z } from 'zod';
-import * as _meetsmore_oss_use_ai_core from '@meetsmore-oss/use-ai-core';
-import { ToolAnnotations, ToolDefinition, WorkflowStatus, FeedbackValue, AgentInfo, McpHeadersMap, MultimodalContent, AGUIEvent, Message as Message$1, UseAIClientMessage } from '@meetsmore-oss/use-ai-core';
+import { ToolAnnotations, ToolDefinition, WorkflowStatus, FeedbackValue, AgentInfo, MultimodalContent, UseAIForwardedProps, AGUIEvent, Message as Message$1, UseAIClientMessage, 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, { ReactNode } from 'react';
+import React$1, { MutableRefObject, RefObject, ReactNode } from 'react';
 
 /**
  * Options for configuring tool behavior.
@@ -941,7 +940,6 @@ declare class UseAIClient {
     private _tools;
     private _messages;
     private _state;
-    private mcpHeadersProvider?;
     private _availableAgents;
     private _defaultAgent;
     private _selectedAgent;
@@ -982,20 +980,15 @@ declare class UseAIClient {
      * @param state - The current state object to provide to the AI
      */
     updateState(state: unknown): void;
-    /**
-     * Sets the MCP headers provider.
-     * The provider will be called each time a message is sent to get fresh headers.
-     *
-     * @param provider - Function that returns MCP headers configuration
-     */
-    setMcpHeadersProvider(provider: () => McpHeadersMap | Promise<McpHeadersMap>): 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[]): Promise<void>;
+    sendPrompt(prompt: string, multimodalContent?: MultimodalContent[], forwardedProps?: UseAIForwardedProps): Promise<void>;
     /**
      * Sends the result of a tool execution back to the server.
      *
@@ -1150,6 +1143,76 @@ declare class UseAIClient {
     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.
+ */
+interface PendingToolApproval {
+    toolCallId: string;
+    toolCallName: string;
+    toolCallArgs: Record<string, unknown>;
+    annotations?: ToolAnnotations;
+}
+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().
  */
@@ -1162,97 +1225,45 @@ interface SendMessageOptions {
     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 UseChatManagementOptions {
-    /** Chat repository for persistence */
-    repository: ChatRepository;
-    /** Reference to the UseAIClient (can be null during initialization) */
-    clientRef: React.MutableRefObject<UseAIClient | null>;
-    /** Current messages state (owned by provider) */
-    messages: Message[];
-    /** Setter for messages state (owned by provider) */
-    setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
-    /** Callback to send a message (from UseAIProvider) */
-    onSendMessage?: (message: string, attachments?: FileAttachment[]) => Promise<void>;
+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 a response */
-    loading?: boolean;
+    connected: boolean;
+    /** Whether the AI is currently loading/processing */
+    loading: boolean;
     /** Whether there's a pending tool approval blocking the queue */
-    hasPendingApproval?: boolean;
+    hasPendingApproval: boolean;
 }
-interface UseChatManagementReturn {
-    /** Current active chat ID where AI responses are saved */
-    currentChatId: string | null;
-    /** Chat loaded for viewing but not yet active for AI responses */
-    pendingChatId: string | null;
-    /** The displayed chat ID (pending or current) */
-    displayedChatId: string | null;
-    /** Creates a new chat and switches to it */
-    createNewChat: (options?: CreateChatOptions) => Promise<string>;
-    /** Loads an existing chat by ID */
-    loadChat: (chatId: string) => Promise<void>;
-    /** Deletes a chat by ID */
-    deleteChat: (chatId: string) => Promise<void>;
-    /** Lists all available chats */
-    listChats: () => Promise<Array<Omit<Chat, 'messages'>>>;
-    /** Clears the current chat messages */
-    clearCurrentChat: () => Promise<void>;
-    /** Activates the pending chat (called when user sends first message) */
-    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>;
-    /** Reloads messages from storage for the given chat ID */
-    reloadMessages: (chatId: string) => Promise<void>;
+interface UseMessageQueueReturn {
     /**
      * Programmatically send a message to the chat.
-     * Throws on failure (e.g., not connected, no onSendMessage callback).
+     * 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>;
-    /** Get the current chat object. Metadata is frozen to prevent accidental mutation. */
-    getCurrentChat: () => Promise<Chat | null>;
-    /** Update metadata for the current chat */
-    updateMetadata: (metadata: ChatMetadata, overwrite?: boolean) => Promise<void>;
-    /** Snapshot refs for use in event handlers */
-    currentChatIdSnapshot: React.MutableRefObject<string | null>;
-    pendingChatIdSnapshot: React.MutableRefObject<string | null>;
 }
 /**
- * Hook for managing chat lifecycle operations.
- *
- * Features:
- * - Creates, loads, deletes chats
- * - Manages pending/active chat state machine
- * - Saves user messages and AI responses
- * - Auto-generates chat titles
- * - Initializes with most recent chat or creates new one
+ * Hook for queuing and sending programmatic messages.
  *
- * @example
- * ```typescript
- * const {
- *   currentChatId,
- *   pendingChatId,
- *   createNewChat,
- *   loadChat,
- *   deleteChat,
- *   listChats,
- *   clearCurrentChat,
- *   activatePendingChat,
- *   saveUserMessage,
- *   saveAIResponse,
- * } = useChatManagement({
- *   repository: chatRepository,
- *   clientRef,
- *   messages,
- *   setMessages,
- * });
- * ```
+ * 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 useChatManagement({ repository, clientRef, messages, setMessages, onSendMessage, setOpen, connected, loading, hasPendingApproval, }: UseChatManagementOptions): UseChatManagementReturn;
+declare function useMessageQueue({ sendFn, createNewChat, setOpen, connected, loading, hasPendingApproval, }: UseMessageQueueOptions): UseMessageQueueReturn;
 
 /**
  * Chat management context (from useChatManagement hook).
@@ -1313,15 +1324,19 @@ interface CommandContextValue {
     delete: (id: string) => Promise<void>;
 }
 /**
- * Tool registry context (from useToolRegistry hook).
+ * Tool system context (from useToolSystem hook).
  */
 interface ToolRegistryContextValue {
     /** Registers tools for a specific component */
-    register: (id: string, tools: ToolsDefinition, options?: {
-        invisible?: boolean;
-    }) => void;
+    register: (id: string, tools: ToolsDefinition, options?: RegisterToolsOptions) => void;
     /** Unregisters tools for a specific component */
     unregister: (id: string) => void;
+    /** Signals that a component has completed registration in useLayoutEffect */
+    signalReady: (id: string) => void;
+    /** Registers a waiter function for a component */
+    registerWaiter: (id: string, waiter: () => Promise<void>) => void;
+    /** Unregisters a waiter function */
+    unregisterWaiter: (id: string) => void;
 }
 /**
  * Prompt management context.
@@ -1329,10 +1344,6 @@ interface ToolRegistryContextValue {
 interface PromptsContextValue {
     /** Updates the prompt and suggestions for a specific component */
     update: (id: string, prompt?: string, suggestions?: string[]) => void;
-    /** Registers a waiter function for a component */
-    registerWaiter: (id: string, waiter: () => Promise<void>) => void;
-    /** Unregisters a waiter function */
-    unregisterWaiter: (id: string) => void;
 }
 /**
  * Context value provided by UseAIProvider.
@@ -1345,15 +1356,15 @@ interface UseAIContextValue {
     connected: boolean;
     /** The underlying WebSocket client instance */
     client: UseAIClient | null;
-    /** Tool registry (from useToolRegistry hook) */
+    /** Tool system (registry, waiters, execution) */
     tools: ToolRegistryContextValue;
     /** Prompt management */
     prompts: PromptsContextValue;
-    /** Chat management (from useChatManagement hook) */
+    /** Chat management */
     chat: ChatContextValue;
-    /** Agent selection (from useAgentSelection hook) */
+    /** Agent selection */
     agents: AgentContextValue;
-    /** Command management (from useCommandManagement hook) */
+    /** Command management */
     commands: CommandContextValue;
 }
 /**
@@ -1407,33 +1418,41 @@ interface UseAIProviderProps extends UseAIConfig {
      */
     chatRepository?: ChatRepository;
     /**
-     * Callback to provide HTTP headers for MCP endpoints.
-     * Called each time AI is invoked by use-ai.
-     * Returns a mapping of MCP endpoint patterns to header configurations.
-     *
-     * Patterns can be:
-     * - Constant strings: `https://api.example.com` - Exact match
-     * - Glob patterns: `https://*.meetsmore.com` - Wildcard matching using picomatch
+     * Provider function for forwarded props (telemetry metadata, MCP headers, etc.).
+     * Called before each message is sent. Can be sync or async.
+     * Props from this provider are merged with message-level forwardedProps,
+     * with message-level taking precedence.
      *
      * @example
-     * ```typescript
-     * mcpHeadersProvider={() => ({
-     *   // Exact match
-     *   'https://api.example.com': {
-     *     headers: { 'Authorization': `Bearer ${userToken}` }
-     *   },
-     *   // Wildcard subdomain
-     *   'https://*.meetsmore.com': {
-     *     headers: { 'X-API-Key': apiKey }
-     *   },
-     *   // Multiple wildcards
-     *   '*://*.example.com': {
-     *     headers: { 'X-Custom': 'value' }
-     *   }
-     * })}
+     * ```tsx
+     * <UseAIProvider
+     *   serverUrl="wss://your-server.com"
+     *   forwardedPropsProvider={() => ({
+     *     mcpHeaders: {
+     *       // Exact match
+     *       'https://api.example.com': {
+     *         headers: { 'Authorization': `Bearer ${userToken}` }
+     *       },
+     *       // Wildcard subdomain
+     *       'https://*.meetsmore.com': {
+     *         headers: { 'X-API-Key': apiKey }
+     *       },
+     *       // Multiple wildcards
+     *       '*://*.example.com': {
+     *         headers: { 'X-Custom': 'value' }
+     *       },
+     *     },
+     *     telemetryMetadata: {
+     *       userId: currentUser.id,
+     *       tenantId: tenant.id,
+     *     },
+     *   })}
+     * >
+     *   <App />
+     * </UseAIProvider>
      * ```
      */
-    mcpHeadersProvider?: () => _meetsmore_oss_use_ai_core.McpHeadersMap | Promise<_meetsmore_oss_use_ai_core.McpHeadersMap>;
+    forwardedPropsProvider?: () => UseAIForwardedProps | Promise<UseAIForwardedProps>;
     /**
      * Configuration for file uploads.
      * File upload is enabled by default with EmbedFileUploadBackend, 10MB max size,
@@ -1547,22 +1566,10 @@ interface UseAIProviderProps extends UseAIConfig {
  * }
  * ```
  */
-declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton, CustomChat, chatRepository, mcpHeadersProvider, fileUploadConfig: fileUploadConfigProp, commandRepository, renderChat, theme: customTheme, strings: customStrings, visibleAgentIds, onOpenChange, }: UseAIProviderProps): react_jsx_runtime.JSX.Element;
+declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton, CustomChat, chatRepository, forwardedPropsProvider, fileUploadConfig: fileUploadConfigProp, commandRepository, renderChat, theme: customTheme, strings: customStrings, visibleAgentIds, onOpenChange, }: UseAIProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the UseAI context.
  * When used outside a UseAIProvider, returns a no-op context and logs a warning.
- * This allows components with useAI hooks to render even when UseAIProvider
- * is conditionally not rendered (e.g., feature flagged).
- *
- * @returns The UseAI context value (or no-op if provider is missing)
- *
- * @example
- * ```typescript
- * function MyComponent() {
- *   const { connected, client } = useAIContext();
- *   return <div>Connected: {connected}</div>;
- * }
- * ```
  */
 declare function useAIContext(): UseAIContextValue;
 
@@ -2012,6 +2019,63 @@ interface UseSlashCommandsReturn {
  */
 declare function useSlashCommands({ commands, onCommandSelect, onSaveCommand, onRenameCommand, onDeleteCommand, }: UseSlashCommandsOptions): UseSlashCommandsReturn;
 
+interface UseChatManagementOptions {
+    /** Chat repository for persistence */
+    repository: ChatRepository;
+    /** Reference to the UseAIClient (can be null during initialization) */
+    clientRef: React.MutableRefObject<UseAIClient | null>;
+    /** Current messages state (owned by provider) */
+    messages: Message[];
+    /** Setter for messages state (owned by provider) */
+    setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
+    /** Whether the client is connected */
+    connected?: boolean;
+}
+interface UseChatManagementReturn {
+    /** Current active chat ID where AI responses are saved */
+    currentChatId: string | null;
+    /** Chat loaded for viewing but not yet active for AI responses */
+    pendingChatId: string | null;
+    /** The displayed chat ID (pending or current) */
+    displayedChatId: string | null;
+    /** Creates a new chat and switches to it */
+    createNewChat: (options?: CreateChatOptions) => Promise<string>;
+    /** Loads an existing chat by ID */
+    loadChat: (chatId: string) => Promise<void>;
+    /** Deletes a chat by ID */
+    deleteChat: (chatId: string) => Promise<void>;
+    /** Lists all available chats */
+    listChats: () => Promise<Array<Omit<Chat, 'messages'>>>;
+    /** Clears the current chat messages */
+    clearCurrentChat: () => Promise<void>;
+    /** Activates the pending chat (called when user sends first message) */
+    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>;
+    /** 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. */
+    getCurrentChat: () => Promise<Chat | null>;
+    /** Update metadata for the current chat */
+    updateMetadata: (metadata: ChatMetadata, overwrite?: boolean) => Promise<void>;
+    /** Snapshot refs for use in event handlers */
+    currentChatIdSnapshot: React.MutableRefObject<string | null>;
+    pendingChatIdSnapshot: React.MutableRefObject<string | null>;
+}
+/**
+ * Hook for managing chat lifecycle operations.
+ *
+ * Features:
+ * - Creates, loads, deletes chats
+ * - Manages pending/active chat state machine
+ * - Saves user messages and AI responses
+ * - Auto-generates chat titles
+ * - Initializes with most recent chat or creates new one
+ */
+declare function useChatManagement({ repository, clientRef, messages, setMessages, connected, }: UseChatManagementOptions): UseChatManagementReturn;
+
 interface UseAgentSelectionOptions {
     /** Reference to the UseAIClient (can be null during initialization) */
     clientRef: React.MutableRefObject<UseAIClient | null>;
@@ -2119,33 +2183,6 @@ interface UseCommandManagementReturn {
  */
 declare function useCommandManagement({ repository, }?: UseCommandManagementOptions): UseCommandManagementReturn;
 
-interface RegisterToolsOptions {
-    /** Mark component as invisible (no visual state, skip prompt wait) */
-    invisible?: boolean;
-}
-interface UseToolRegistryReturn {
-    /** 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: React.MutableRefObject<ToolsDefinition>;
-    /** Ref mapping tool names to component IDs */
-    toolOwnershipRef: React.MutableRefObject<Map<string, string>>;
-}
-/**
- * Hook for managing tool registration and aggregation.
- *
- * Only handles tools - prompt management is handled separately.
- */
-declare function useToolRegistry(): UseToolRegistryReturn;
-
 interface UsePromptStateOptions {
     /** System prompt to include in state */
     systemPrompt?: string;
@@ -2157,16 +2194,12 @@ interface UsePromptStateOptions {
 interface UsePromptStateReturn {
     /** Updates the prompt and suggestions for a specific component */
     updatePrompt: (id: string, prompt?: string, suggestions?: string[]) => void;
-    /** Registers a waiter function for a component */
-    registerWaiter: (id: string, waiter: () => Promise<void>) => void;
-    /** Unregisters a waiter function */
-    unregisterWaiter: (id: string) => void;
-    /** Gets the waiter function for a component */
-    getWaiter: (id: string) => (() => Promise<void>) | undefined;
     /** All suggestions aggregated from registered components */
     aggregatedSuggestions: string[];
-    /** Ref mapping component IDs to prompts */
-    promptsRef: React.MutableRefObject<Map<string, string>>;
+    /** Builds the aggregated state from all registered prompts */
+    buildStateFromPrompts: () => {
+        context: string;
+    } | null;
 }
 /**
  * Hook for managing prompt state across multiple useAI hooks.
@@ -2174,11 +2207,56 @@ interface UsePromptStateReturn {
  * Handles:
  * - Storing prompts and suggestions per component
  * - Updating client state when prompts change
- * - Managing waiter functions for prompt change notifications
  * - Aggregating suggestions from all components
  */
 declare function usePromptState({ systemPrompt, clientRef, connected, }: UsePromptStateOptions): UsePromptStateReturn;
 
+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>;
+    /** UI strings for error messages and tool execution fallbacks */
+    strings: UseAIStrings;
+}
+interface ExecutingToolDisplay {
+    displayText: string;
+}
+interface UseServerEventsReturn {
+    /** Whether the AI is currently loading/processing a response */
+    loading: boolean;
+    /** Set the loading state (e.g., when sending a message) */
+    setLoading: React.Dispatch<React.SetStateAction<boolean>>;
+    /** Current streaming text from the AI response */
+    streamingText: string;
+    /** Clear streaming text (e.g., when starting a new message) */
+    clearStreamingText: () => void;
+    /** Currently executing tool info for UI display, or null */
+    executingTool: ExecutingToolDisplay | null;
+    /** Ref tracking which chat the current streaming text belongs to */
+    streamingChatIdRef: React.MutableRefObject<string | null>;
+    /**
+     * Handles a server event. Called from the provider's client subscription.
+     * Takes the client instance so it can access client-internal state
+     * (currentToolCalls, currentMessageContent).
+     */
+    handleServerEvent: (client: UseAIClient, event: AGUIEvent) => Promise<void>;
+}
+/**
+ * Hook that owns all server event handling state and logic.
+ *
+ * Manages:
+ * - Loading state (set on message send, cleared on RUN_FINISHED/RUN_ERROR)
+ * - Streaming text accumulation (TEXT_MESSAGE_CONTENT/END events)
+ * - Executing tool display (TOOL_CALL_START/END events)
+ * - Tool execution dispatch (delegates to toolSystem)
+ * - Error handling (RUN_ERROR events)
+ *
+ * The provider creates the client and subscribes `handleServerEvent` to it.
+ * This hook doesn't manage the client lifecycle — only the event handling.
+ */
+declare function useServerEvents({ toolSystem, saveAIResponse, strings, }: UseServerEventsOptions): UseServerEventsReturn;
+
 interface UseFeedbackOptions {
     /** Reference to the UseAIClient */
     clientRef: React.MutableRefObject<UseAIClient | null>;
@@ -2298,4 +2376,4 @@ interface UseDropdownStateOptions {
  */
 declare function useDropdownState(options?: UseDropdownStateOptions): UseDropdownStateReturn;
 
-export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFeedbackOptions, type UseFeedbackReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolRegistryReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformerPattern, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, usePromptState, useSlashCommands, useStableTools, useStrings, useTheme, useToolRegistry, validateCommandName };
+export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type ExecutingToolDisplay, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PendingToolApproval, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFeedbackOptions, type UseFeedbackReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UseMessageQueueOptions, type UseMessageQueueReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseServerEventsOptions, type UseServerEventsReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolSystemOptions, type UseToolSystemReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformerPattern, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, useMessageQueue, usePromptState, useServerEvents, useSlashCommands, useStableTools, useStrings, useTheme, useToolSystem, validateCommandName };