@cmnd-ai/chatbot-react 1.10.0 → 1.13.0

package/Readme.md

@@ -117,6 +117,110 @@ const App = () => {
 };
 ```
 
+## Headless Usage with `useCMNDChat` Hook
+
+If you want complete control over your UI while maintaining the powerful chatbot logic, you can use the `useCMNDChat` hook. It handles all state management, real-time streaming, conversation history, and tool orchestration.
+
+```tsx
+import { useCMNDChat, MessageRole } from "@cmnd-ai/chatbot-react";
+
+const MyCustomChat = () => {
+  const {
+    messages,
+    input,
+    setInput,
+    isChatLoading,
+    canSendMessage,
+    sendMessage,
+    submitToolResult,
+    conversations,
+    handleNewChat,
+    handleConversationSelect,
+    error,
+  } = useCMNDChat({
+    chatbotId: 123,
+    organizationId: 456,
+    baseUrl: "https://api.cmnd.ai",
+    apiKey: "your-api-key",
+    cleanResponse: true, // Optional: Returns assistant messages as plaintext
+    onData: (data) => console.log("Stream update:", data),
+    onToolCall: async (tool) => {
+      console.log("AI called tool:", tool.name);
+
+      // For UI tools, you must execute and call submitToolResult
+      if (tool.name === "my_custom_tool") {
+        const result = await runMyTool(tool.args);
+        submitToolResult(JSON.stringify(result));
+      }
+    },
+  });
+
+  return (
+    <div className="custom-chat">
+      <div className="message-list">
+        {messages.map((m) => (
+          <div key={m.id} className={`message ${m.role}`}>
+            {m.role === MessageRole.ASSISTANT ? "🤖" : "👤"}: {m.message}
+            {/* Handle tool calls */}
+            {m.role === MessageRole.FUNCTION && (
+              <div className="tool-ui">
+                Rendering Tool: {m.tool.name}
+                {/* Once done, call submitToolResult("result") */}
+              </div>
+            )}
+          </div>
+        ))}
+      </div>
+
+      <div className="controls">
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Type here..."
+        />
+        <button onClick={() => sendMessage()}>Send</button>
+        <button onClick={handleNewChat}>Clear Chat</button>
+      </div>
+    </div>
+  );
+};
+```
+
+### Hook API Reference
+
+#### `UseCMNDChatOptions`
+
+| Option           | Type                  | Description                                                                |
+| ---------------- | --------------------- | -------------------------------------------------------------------------- |
+| `chatbotId`      | `number`              | **Required**. Your unique chatbot ID.                                      |
+| `organizationId` | `number`              | **Required**. Your unique organization ID.                                 |
+| `baseUrl`        | `string`              | **Required**. The CMND API base URL.                                       |
+| `apiKey`         | `string`              | Optional API key for authentication.                                       |
+| `initialMemory`  | `object`              | Context to send when starting a new conversation.                          |
+| `UITools`        | `CMNDChatbotUITool[]` | Array of custom UI tools.                                                  |
+| `onData`         | `function`            | Triggered for every response chunk or message update.                      |
+| `onToolCall`     | `function`            | Triggered when the AI requests a tool execution.                           |
+| `cleanResponse`  | `boolean`             | If `true`, assistant messages are returned as plaintext. Default: `false`. |
+
+#### `UseCMNDChatResult`
+
+| Property                   | Type                    | Description                                               |
+| -------------------------- | ----------------------- | --------------------------------------------------------- |
+| `messages`                 | `Message[]`             | Array of all messages in the current conversation thread. |
+| `input`                    | `string`                | The current text in the chat input.                       |
+| `setInput`                 | `function`              | Update the chat input text.                               |
+| `isChatLoading`            | `boolean`               | True if a message is being generated or tool is running.  |
+| `canSendMessage`           | `boolean`               | True if the system is ready to receive the next message.  |
+| `sendMessage`              | `(text?) => Promise`    | Send a message. Uses `input` if `text` is omitted.        |
+| `submitToolResult`         | `(output) => Promise`   | Submit results from a UI tool back to the AI.             |
+| `conversations`            | `ChatbotConversation[]` | List of historical conversations.                         |
+| `selectedConversation`     | `ChatbotConversation`   | The currently active conversation metadata.               |
+| `handleNewChat`            | `function`              | Starts a fresh conversation thread.                       |
+| `handleConversationSelect` | `function`              | Loads a specific conversation from history.               |
+| `handleDeleteConversation` | `function`              | Deletes a conversation from history.                      |
+| `tools`                    | `any[]`                 | All available tools (API + UI).                           |
+| `error`                    | `string`                | Contains description of any API or processing errors.     |
+
 ## Props
 
 ### Required Props
@@ -130,15 +234,15 @@ const App = () => {
 
 ### Optional Props
 
-| Prop                    | Type                  | Default     | Description                                           |
-| ----------------------- | --------------------- | ----------- | ----------------------------------------------------- |
-| `theme`                 | `"light" \| "dark"`   | `"light"`   | Theme for the chatbot                                 |
-| `UITools`               | `CMNDChatbotUITool[]` | `[]`        | Array of UI tools                                     |
-| `enabledTools`          | `any[]`               | `[]`        | Array of enabled tools                                |
-| `initialMemory`         | `CMNDChatMemory`      | `undefined` | Initial conversation memory                           |
-| `customStyles`          | `CustomStyles`        | `undefined` | Custom CSS styles                                     |
-| `Components`            | `Components`          | `undefined` | Custom component overrides                            |
-| `chatHistoryStorageKey` | `string`              | `undefined` | The chat history key defined by the client            |
+| Prop                    | Type                  | Default     | Description                                |
+| ----------------------- | --------------------- | ----------- | ------------------------------------------ |
+| `theme`                 | `"light" \| "dark"`   | `"light"`   | Theme for the chatbot                      |
+| `UITools`               | `CMNDChatbotUITool[]` | `[]`        | Array of UI tools                          |
+| `enabledTools`          | `any[]`               | `[]`        | Array of enabled tools                     |
+| `initialMemory`         | `CMNDChatMemory`      | `undefined` | Initial conversation memory                |
+| `customStyles`          | `CustomStyles`        | `undefined` | Custom CSS styles                          |
+| `Components`            | `Components`          | `undefined` | Custom component overrides                 |
+| `chatHistoryStorageKey` | `string`              | `undefined` | The chat history key defined by the client |
 
 ## Custom Components
 

package/dist/ChatProvider/index.d.ts

@@ -5,7 +5,7 @@ export declare const ChatProviderContext: React.Context<CmndChatContext | undefi
 export interface ChatProviderProps extends Omit<CmndChatBotProps, "postSessionMessage"> {
     children?: React.ReactNode | ((props: CmndChatBotProps) => React.ReactNode);
 }
-export declare const setCurrentConversationMemory: (memory: CMNDChatMemory) => Promise<import("axios").AxiosResponse<any, any> | undefined>;
-export declare const deleteCurrentConversationMemory: (memoryKeyToDelete: string) => Promise<import("axios").AxiosResponse<any, any> | undefined>;
+export declare const setCurrentConversationMemory: (memory: CMNDChatMemory) => Promise<import("axios").AxiosResponse<any, any, {}> | undefined>;
+export declare const deleteCurrentConversationMemory: (memoryKeyToDelete: string) => Promise<import("axios").AxiosResponse<any, any, {}> | undefined>;
 declare function ChatProvider(props: ChatProviderProps): JSX.Element | null;
 export default ChatProvider;

package/dist/ChatProvider/processStream/index.js

@@ -3,6 +3,7 @@ const processStream = async (reader, onData) => {
     if (!onData)
         return;
     let fullAssistantMessage = "";
+    let functionName = "";
     let buffer = ""; // buffer to store incomplete JSON string fragments
     try {
         while (true) {
@@ -44,17 +45,31 @@ const processStream = async (reader, onData) => {
                         });
                     }
                     else if (dataObject.function_call) {
-                        // console.log("no processing necessary");
+                        const { name } = dataObject.function_call;
+                        if (name)
+                            functionName = name;
+                        onData({
+                            completionFinished: false,
+                            finalResponseWithUsageData: false,
+                            streamingFunctionCall: true,
+                            functionName,
+                        });
+                    }
+                    else if (dataObject.function_result) {
+                        onData({
+                            completionFinished: false,
+                            finalResponseWithUsageData: false,
+                            streamingFunctionCall: false,
+                            functionResult: dataObject.function_result,
+                        });
                     }
                     else {
-                        //at this point, the dataObject does not have a content propery
-                        //and it is completed
-                        //get the last message from the dataObject to check if it is a function call
-                        const { messages, completionFinished, finalResponseWithUsageData, chatbotConversationRef, totalTokens, totalCost, } = dataObject;
+                        const { messages, completionFinished, finalResponseWithUsageData, conversationRef, chatbotConversationRef, totalTokens, totalCost, } = dataObject;
                         onData({
                             messages,
                             completionFinished,
                             finalResponseWithUsageData,
+                            conversationRef,
                             chatbotConversationRef,
                             totalTokens,
                             totalCost,
@@ -68,13 +83,23 @@ const processStream = async (reader, onData) => {
                         continue;
                     }
                     console.error("StreamError caught", error);
-                    onData({
-                        completionFinished: true,
-                        message: error instanceof StreamError
-                            ? error.message
-                            : "Oops! I ran into a problem.",
-                        finalResponseWithUsageData: true,
-                    });
+                    if (error instanceof StreamError) {
+                        onData({
+                            completionFinished: true,
+                            message: error.message,
+                            finalResponseWithUsageData: true,
+                            hasError: true,
+                            errorPath: error.path,
+                        });
+                    }
+                    else {
+                        onData({
+                            completionFinished: true,
+                            message: "Oops! I ran into a problem.",
+                            finalResponseWithUsageData: true,
+                            hasError: true,
+                        });
+                    }
                 }
             }
         }
@@ -84,11 +109,12 @@ const processStream = async (reader, onData) => {
         }
     }
     catch (error) {
-        console.error("Error processing stream", error);
+        console.error("Fatal error in processStream", error);
         onData({
             completionFinished: true,
             message: "Oops! I ran into a problem.",
             finalResponseWithUsageData: true,
+            hasError: true,
         });
     }
 };

package/dist/CmndChatBot/index.d.ts

@@ -20,6 +20,7 @@ export interface CmndChatBotProps {
         LoadingIndicator?: () => JSX.Element;
         error?: any;
     };
+    cleanResponse?: boolean;
 }
-declare function CmndChatBot({ chatbotId, organizationId, apiKey, baseUrl, theme, UITools, customStyles, chatHistoryStorageKey, enabledTools, Components, initialMemory, }: CmndChatBotProps): JSX.Element;
+declare function CmndChatBot({ chatbotId, organizationId, apiKey, baseUrl, theme, UITools, customStyles, chatHistoryStorageKey, enabledTools, Components, initialMemory, cleanResponse, }: CmndChatBotProps): JSX.Element;
 export default CmndChatBot;

package/dist/CmndChatBot/index.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import ChatProvider from "../ChatProvider/index.js";
-function CmndChatBot({ chatbotId, organizationId, apiKey, baseUrl, theme, UITools, customStyles, chatHistoryStorageKey, enabledTools = [], Components, initialMemory, }) {
-    return (_jsx(ChatProvider, { chatbotId: chatbotId, organizationId: organizationId, chatHistoryStorageKey: chatHistoryStorageKey, apiKey: apiKey, baseUrl: baseUrl, theme: theme, UITools: UITools, customStyles: customStyles, enabledTools: enabledTools, Components: Components, initialMemory: initialMemory }));
+function CmndChatBot({ chatbotId, organizationId, apiKey, baseUrl, theme, UITools, customStyles, chatHistoryStorageKey, enabledTools = [], Components, initialMemory, cleanResponse, }) {
+    return (_jsx(ChatProvider, { chatbotId: chatbotId, organizationId: organizationId, chatHistoryStorageKey: chatHistoryStorageKey, apiKey: apiKey, baseUrl: baseUrl, theme: theme, UITools: UITools, customStyles: customStyles, enabledTools: enabledTools, Components: Components, initialMemory: initialMemory, cleanResponse: cleanResponse }));
 }
 export default CmndChatBot;

package/dist/hooks/use-cmnd-chat.d.ts

@@ -0,0 +1,130 @@
+/// <reference types="react" />
+import { ChatbotConversation, Message, CMNDChatMemory, CMNDChatbotUITool, ConversationDataObject, ToolDetails } from "../type.js";
+/**
+ * Options for configuring the useCMNDChat hook.
+ */
+export interface UseCMNDChatOptions {
+    /** The unique identifier for the chatbot. */
+    chatbotId: number;
+    /** The unique identifier for the organization. */
+    organizationId: number;
+    /** The base URL for the CMND API. */
+    baseUrl: string;
+    /** Optional API key for authentication. If provided, it will be sent in the 'x-api-key' header. */
+    apiKey?: string;
+    /** Optional key used for local message persistence. Defaults to a combined string of orgId and chatbotId. */
+    chatHistoryStorageKey?: string;
+    /** Initial memory/context to send when starting a new conversation. */
+    initialMemory?: CMNDChatMemory;
+    /** Array of custom UI tools that the AI can call. */
+    UITools?: CMNDChatbotUITool[];
+    /** Callback triggered whenever new data (chunks or finalized messages) is received from the stream. */
+    onData?: (data: ConversationDataObject) => void;
+    /**
+     * Callback triggered whenever the AI initiates a tool call.
+     *
+     * For **backend tools**: The hook automatically confirms them, which triggers your backend server
+     * to execute the tool and return the output. Use this callback for logging or UI updates.
+     *
+     * For **UI tools**: You must execute the tool in your frontend, then call submitToolResult with the output.
+     *
+     * @example
+     * ```tsx
+     * onToolCall: async (toolDetails) => {
+     *   if (toolDetails.name === 'show_ui_component') {
+     *     // UI tool - execute in frontend
+     *     displayComponent(toolDetails.args);
+     *     submitToolResult('Component displayed');
+     *   }
+     *   // Backend tools are handled automatically by the server
+     * }
+     * ```
+     */
+    onToolCall?: (toolCall: ToolDetails) => void;
+    /**
+     * Whether to clean the AI response by removing markdown characters.
+     * If true, assistant messages will be returned as plaintext.
+     * @default false
+     */
+    cleanResponse?: boolean;
+}
+/**
+ * The object returned by the useCMNDChat hook.
+ */
+export interface UseCMNDChatResult {
+    /** The list of messages in the current active conversation thread. */
+    messages: Message[];
+    /** A setter function for the messages list. */
+    setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
+    /** The current text value of the chat input field. */
+    input: string;
+    /** A setter function for the chat input field. */
+    setInput: React.Dispatch<React.SetStateAction<string>>;
+    /** Indicates if a message is currently being processed or streamed. */
+    isChatLoading: boolean;
+    /** Indicates if the user is allowed to send a message (e.g., not loading, not empty). */
+    canSendMessage: boolean;
+    /**
+     * Sends a message to the chatbot.
+     * @param text Optional text to send. If not provided, it uses the current 'input' state.
+     * @param onData Optional callback for this specific message stream.
+     */
+    sendMessage: (text?: string, onData?: (data: ConversationDataObject) => void) => Promise<void>;
+    /**
+     * Submits the result of a tool call back to the AI.
+     * @param toolOutput The string result of the tool execution.
+     * @param onData Optional callback for the resulting message stream.
+     */
+    submitToolResult: (toolOutput: string, onData?: (data: ConversationDataObject) => void) => Promise<void>;
+    /** The reference ID for the current active conversation. */
+    chatbotConversationRef: string | undefined;
+    /** A list of all historical conversations for the current chatbot/org. */
+    conversations: ChatbotConversation[];
+    /** The currently selected conversation object from history. */
+    selectedConversation: ChatbotConversation | null;
+    /** Resets the chat state and prepares for a new conversation thread. */
+    handleNewChat: () => void;
+    /**
+     * Switches to an existing conversation from history.
+     * @param conversation The conversation object to load.
+     */
+    handleConversationSelect: (conversation: ChatbotConversation) => void;
+    /**
+     * Deletes a conversation from history and local storage.
+     * @param conversationId The ID of the conversation to delete.
+     */
+    handleDeleteConversation: (conversationId: string) => Promise<void>;
+    /** Re-fetches the list of historical conversations. */
+    refreshConversations: () => Promise<void>;
+    /** Combined list of backend tools (from API) and UI tools (provided in options). */
+    tools: any[];
+    /** Holds any error message encountered during API calls. */
+    error: string | null;
+}
+/**
+ * A comprehensive hook to manage CMND.AI chatbot logic without being forced to use the default UI.
+ * This hook handles conversation state, message sending (including streaming), history management, and tool call orchestration.
+ *
+ * @example
+ * ```tsx
+ * const { messages, sendMessage, input, setInput, submitToolResult } = useCMNDChat({
+ *   chatbotId: 1,
+ *   organizationId: 1,
+ *   baseUrl: 'https://api.cmnd.ai',
+ *   cleanResponse: true, // Optional: Returns assistant messages as plaintext
+ *   onToolCall: async (toolDetails) => {
+ *     // Backend tools are auto-confirmed by the hook
+ *     if (toolDetails.name === 'get_playlists') {
+ *       console.log('Fetching playlists from backend...');
+ *     }
+ *
+ *     // UI tools need manual execution and confirmation
+ *     if (toolDetails.name === 'show_notification') {
+ *       showNotification(toolDetails.args.message);
+ *       submitToolResult('Notification displayed');
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare const useCMNDChat: (options: UseCMNDChatOptions) => UseCMNDChatResult;

package/dist/hooks/use-cmnd-chat.js

@@ -0,0 +1,396 @@
+import { useState, useEffect, useCallback, useMemo, useRef } from "react";
+import { v4 as uuidv4 } from "uuid";
+import postUserConversation from "../services/postUserConversation.js";
+import getChatBotConversationsList from "../services/getChatBotConversationsList/index.js";
+import getEmbedChatBotById from "../services/getEmbedChatBotById.js";
+import { MessageRole, FunctionType, } from "../type.js";
+import getConversationLocalStorageKey from "../utils/getConversationLocalStorageKey/index.js";
+import saveConversationIdToLocalStorage from "../utils/saveConversationIdToLocalStorage/index.js";
+import getUTCDateTime from "../utils/getUTCDateTime/index.js";
+import parseUITools from "../utils/parseUITools.js";
+import getTools from "../utils/getTools/index.js";
+import { cleanMarkdown } from "../utils/cleanMarkdown.js";
+/**
+ * A comprehensive hook to manage CMND.AI chatbot logic without being forced to use the default UI.
+ * This hook handles conversation state, message sending (including streaming), history management, and tool call orchestration.
+ *
+ * @example
+ * ```tsx
+ * const { messages, sendMessage, input, setInput, submitToolResult } = useCMNDChat({
+ *   chatbotId: 1,
+ *   organizationId: 1,
+ *   baseUrl: 'https://api.cmnd.ai',
+ *   cleanResponse: true, // Optional: Returns assistant messages as plaintext
+ *   onToolCall: async (toolDetails) => {
+ *     // Backend tools are auto-confirmed by the hook
+ *     if (toolDetails.name === 'get_playlists') {
+ *       console.log('Fetching playlists from backend...');
+ *     }
+ *
+ *     // UI tools need manual execution and confirmation
+ *     if (toolDetails.name === 'show_notification') {
+ *       showNotification(toolDetails.args.message);
+ *       submitToolResult('Notification displayed');
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export const useCMNDChat = (options) => {
+    const { chatbotId, organizationId, baseUrl, apiKey, chatHistoryStorageKey, initialMemory, UITools, onData: globalOnData, onToolCall, cleanResponse = false, } = options;
+    const [messages, setMessages] = useState([]);
+    const [input, setInput] = useState("");
+    const [isChatLoading, setIsChatLoading] = useState(false);
+    const [canSendMessage, setCanSendMessage] = useState(true);
+    const [chatbotConversationRef, setChatbotConversationRef] = useState(undefined);
+    const [conversations, setConversations] = useState([]);
+    const [selectedConversation, setSelectedConversation] = useState(null);
+    const [enabledTools, setEnabledTools] = useState([]);
+    const [error, setError] = useState(null);
+    const lastProcessedToolCallId = useRef(null);
+    const localStorageKey = useMemo(() => chatHistoryStorageKey ||
+        getConversationLocalStorageKey({ organizationId, chatbotId }), [chatHistoryStorageKey, organizationId, chatbotId]);
+    const tools = useMemo(() => getTools({
+        apiTools: enabledTools,
+        uiTools: parseUITools(UITools),
+    }), [enabledTools, UITools]);
+    // Fetch Chatbot Info for enabled tools
+    useEffect(() => {
+        if (!baseUrl || !organizationId || !chatbotId)
+            return;
+        getEmbedChatBotById(baseUrl, organizationId, chatbotId)
+            .then((response) => {
+            const { chatbot } = response.data;
+            setEnabledTools(chatbot.enabledTools || []);
+        })
+            .catch((err) => {
+            console.error("Error fetching chatbot tools:", err);
+        });
+    }, [baseUrl, organizationId, chatbotId]);
+    const refreshConversations = useCallback(async () => {
+        try {
+            const storedIds = JSON.parse(localStorage.getItem(localStorageKey) || "[]");
+            if (storedIds.length > 0) {
+                const response = await getChatBotConversationsList({
+                    organizationId,
+                    chatbotId,
+                    conversationIds: storedIds,
+                    baseUrl,
+                });
+                setConversations(response.chatbotConversations || []);
+            }
+            else {
+                setConversations([]);
+            }
+        }
+        catch (err) {
+            console.error("Error fetching conversations:", err);
+        }
+    }, [baseUrl, chatbotId, localStorageKey, organizationId]);
+    useEffect(() => {
+        refreshConversations();
+    }, [refreshConversations]);
+    const handleStreamData = useCallback(async (data, currentMessages, onDataCallback) => {
+        if (onDataCallback)
+            onDataCallback(data);
+        if (globalOnData)
+            globalOnData(data);
+        // Handle streaming assistant message
+        if (data.message && !data.finalResponseWithUsageData) {
+            // Clear loading state when assistant starts responding
+            setIsChatLoading(false);
+            setCanSendMessage(true);
+            const assistantMessage = {
+                role: MessageRole.ASSISTANT,
+                message: data.message,
+                id: "streaming-assistant-message",
+                unuseful: false,
+                hiddenFromUser: false,
+            };
+            setMessages([...currentMessages, assistantMessage]);
+        }
+        if (data.finalResponseWithUsageData) {
+            const { messages: updatedMessages, message, hasError } = data;
+            const newConversationId = data.chatbotConversationRef || data.conversationRef;
+            if (hasError) {
+                setError(message || "Oops! I ran into a problem.");
+            }
+            if (newConversationId) {
+                setChatbotConversationRef(newConversationId);
+                await saveConversationIdToLocalStorage({
+                    chatbotConversationRef: newConversationId,
+                    chatbotId,
+                    organizationId,
+                    chatHistoryStorageKey,
+                });
+                refreshConversations();
+            }
+            if (updatedMessages) {
+                setMessages(updatedMessages);
+            }
+            else if (message) {
+                // If we have a standalone message in the final response (e.g. an error)
+                const assistantMessage = {
+                    role: MessageRole.ASSISTANT,
+                    message: message,
+                    id: uuidv4(),
+                    unuseful: false,
+                    hiddenFromUser: false,
+                };
+                setMessages([...currentMessages, assistantMessage]);
+            }
+            // Ensure loading state is cleared (in case no streaming message came)
+            setIsChatLoading(false);
+            setCanSendMessage(true);
+        }
+    }, [
+        globalOnData,
+        refreshConversations,
+        chatbotId,
+        organizationId,
+        chatHistoryStorageKey,
+    ]);
+    const sendMessage = useCallback(async (text, onData) => {
+        const messageToSend = text !== undefined ? text : input;
+        if (!messageToSend.trim() || !canSendMessage)
+            return;
+        const userMessage = {
+            role: MessageRole.USER,
+            message: messageToSend,
+            id: uuidv4(),
+            unuseful: false,
+            hiddenFromUser: false,
+        };
+        const newMessages = [...messages, userMessage];
+        setMessages(newMessages);
+        if (text === undefined)
+            setInput("");
+        setIsChatLoading(true);
+        setCanSendMessage(false);
+        setError(null);
+        const payload = {
+            messages: newMessages,
+            uiTools: parseUITools(UITools),
+        };
+        if (chatbotConversationRef) {
+            payload["chatbotConversationRef"] = chatbotConversationRef;
+        }
+        else if (initialMemory) {
+            payload["initialMemory"] = initialMemory;
+        }
+        try {
+            await postUserConversation({
+                payload,
+                apikey: apiKey,
+                chatbotId,
+                baseUrl,
+                onData: (data) => handleStreamData(data, newMessages, onData),
+            });
+        }
+        catch (err) {
+            console.error("Error sending message:", err);
+            setError(err.message || "Failed to send message");
+            setIsChatLoading(false);
+            setCanSendMessage(true);
+        }
+    }, [
+        input,
+        canSendMessage,
+        messages,
+        UITools,
+        chatbotConversationRef,
+        initialMemory,
+        chatbotId,
+        baseUrl,
+        apiKey,
+        handleStreamData,
+    ]);
+    // Confirm a backend tool (sets confirmed: true, server will add output)
+    const confirmBackendTool = useCallback(async () => {
+        const lastMessage = messages[messages.length - 1];
+        if (!lastMessage || lastMessage.role !== MessageRole.FUNCTION) {
+            return;
+        }
+        const updatedLastMessage = {
+            ...lastMessage,
+            tool: {
+                ...lastMessage.tool,
+                confirmed: true,
+            },
+        };
+        const newMessages = [...messages.slice(0, -1), updatedLastMessage];
+        setMessages(newMessages);
+        // Keep loading state true while backend tool executes
+        setIsChatLoading(true);
+        setCanSendMessage(false);
+        const payload = {
+            messages: newMessages,
+            uiTools: parseUITools(UITools),
+            chatbotConversationRef,
+        };
+        try {
+            await postUserConversation({
+                payload,
+                apikey: apiKey,
+                chatbotId,
+                baseUrl,
+                onData: (data) => handleStreamData(data, newMessages),
+            });
+        }
+        catch (err) {
+            console.error("Error confirming backend tool:", err);
+            setError(err.message || "Failed to confirm backend tool");
+            setIsChatLoading(false);
+            setCanSendMessage(true);
+        }
+    }, [
+        messages,
+        UITools,
+        chatbotConversationRef,
+        apiKey,
+        chatbotId,
+        baseUrl,
+        handleStreamData,
+    ]);
+    const submitToolResult = useCallback(async (toolOutput, onData) => {
+        const lastMessage = messages[messages.length - 1];
+        if (!lastMessage || lastMessage.role !== MessageRole.FUNCTION) {
+            console.error("Last message is not a function call");
+            return;
+        }
+        const updatedLastMessage = {
+            ...lastMessage,
+            tool: {
+                ...lastMessage.tool,
+                output: toolOutput,
+                confirmed: true,
+                runAt: new Date().toISOString(),
+            },
+        };
+        const newMessages = [...messages.slice(0, -1), updatedLastMessage];
+        setMessages(newMessages);
+        setIsChatLoading(true);
+        setCanSendMessage(false);
+        const payload = {
+            messages: newMessages,
+            uiTools: parseUITools(UITools),
+            chatbotConversationRef,
+        };
+        try {
+            await postUserConversation({
+                payload,
+                apikey: apiKey,
+                chatbotId,
+                baseUrl,
+                onData: (data) => handleStreamData(data, newMessages, onData),
+            });
+        }
+        catch (err) {
+            console.error("Error submitting tool result:", err);
+            setError(err.message || "Failed to submit tool result");
+            setIsChatLoading(false);
+            setCanSendMessage(true);
+        }
+    }, [
+        messages,
+        UITools,
+        chatbotConversationRef,
+        apiKey,
+        chatbotId,
+        baseUrl,
+        handleStreamData,
+    ]);
+    // Handle tool call detection and auto-confirmation
+    useEffect(() => {
+        const lastMessage = messages[messages.length - 1];
+        if (lastMessage &&
+            lastMessage.role === MessageRole.FUNCTION &&
+            lastMessage.id !== lastProcessedToolCallId.current) {
+            const toolDetails = lastMessage.tool;
+            const toolDef = tools.find((t) => t.name === toolDetails.name);
+            // Notify consumer about the tool call
+            if (onToolCall)
+                onToolCall(toolDetails);
+            // Auto-confirm backend tools so the server can execute them
+            if (toolDef?.functionType === FunctionType.BACKEND &&
+                !toolDetails.confirmed) {
+                lastProcessedToolCallId.current = lastMessage.id;
+                confirmBackendTool();
+            }
+        }
+    }, [messages, tools, onToolCall, confirmBackendTool]);
+    const handleNewChat = useCallback(() => {
+        setSelectedConversation(null);
+        setChatbotConversationRef(undefined);
+        setMessages([]);
+        setInput("");
+        const dateString = getUTCDateTime();
+        const newConversation = {
+            chatbotConversationRef: uuidv4(),
+            messages: [],
+            chatbotId: chatbotId,
+            chatbotConversationTitle: "New Conversation",
+            createdAt: dateString,
+            updatedAt: dateString,
+            totalCostSoFar: 0,
+            totalTokensSoFar: 0,
+        };
+        setSelectedConversation(newConversation);
+    }, [chatbotId]);
+    const handleConversationSelect = useCallback((conversation) => {
+        setSelectedConversation(conversation);
+        setChatbotConversationRef(conversation.chatbotConversationRef);
+        setMessages(conversation.messages.map((m) => ({
+            ...m,
+            id: m.id || uuidv4(),
+        })));
+    }, []);
+    const handleDeleteConversation = useCallback(async (conversationId) => {
+        try {
+            const storedIds = JSON.parse(localStorage.getItem(localStorageKey) || "[]");
+            const updatedIds = storedIds.filter((id) => id !== conversationId);
+            localStorage.setItem(localStorageKey, JSON.stringify(updatedIds));
+            if (selectedConversation?.chatbotConversationRef === conversationId) {
+                handleNewChat();
+            }
+            refreshConversations();
+        }
+        catch (err) {
+            console.error("Error deleting conversation:", err);
+        }
+    }, [localStorageKey, selectedConversation, handleNewChat, refreshConversations]);
+    const visibleMessages = useMemo(() => {
+        return messages
+            .filter((msg) => !msg.hiddenFromUser && msg.role !== MessageRole.FUNCTION)
+            .map((msg) => {
+            if (cleanResponse &&
+                msg.role === MessageRole.ASSISTANT &&
+                msg.message) {
+                return {
+                    ...msg,
+                    message: cleanMarkdown(msg.message),
+                };
+            }
+            return msg;
+        });
+    }, [messages, cleanResponse]);
+    return {
+        messages: visibleMessages,
+        setMessages,
+        input,
+        setInput,
+        isChatLoading,
+        canSendMessage,
+        sendMessage,
+        submitToolResult,
+        chatbotConversationRef,
+        conversations,
+        selectedConversation,
+        handleNewChat,
+        handleConversationSelect,
+        handleDeleteConversation,
+        refreshConversations,
+        tools,
+        error,
+    };
+};

package/dist/index.d.ts

@@ -1,5 +1,8 @@
+export { default as CmndChatBot } from "./CmndChatBot/index.js";
 export { default as ChatProvider } from "./ChatProvider/index.js";
 export { ConversationsPanel } from "./components/ConversationsPanel/index.js";
-export { CmndChatContext, InputFieldProps, SendButtonProps, CustomStyles, CMNDChatMemory, ChatbotConversation, ChatbotConversationsResponse, } from "./type.js";
+export { default as Conversation } from "./components/Conversation.js";
+export { CmndChatContext, InputFieldProps, SendButtonProps, CustomStyles, CMNDChatMemory, ChatbotConversation, ChatbotConversationsResponse, Message, MessageRole, ConversationDataObject, ToolDetails, FunctionType, CMNDChatbotUITool, ChatbotConversationMessage, } from "./type.js";
 export { setCurrentConversationMemory, deleteCurrentConversationMemory, } from "./ChatProvider/index.js";
 export { useCMNDChatContext } from "./ChatProvider/useChatContext.js";
+export { useCMNDChat, UseCMNDChatOptions, UseCMNDChatResult, } from "./hooks/use-cmnd-chat.js";

package/dist/index.js

@@ -1,4 +1,8 @@
+export { default as CmndChatBot } from "./CmndChatBot/index.js";
 export { default as ChatProvider } from "./ChatProvider/index.js";
 export { ConversationsPanel } from "./components/ConversationsPanel/index.js";
+export { default as Conversation } from "./components/Conversation.js";
+export { MessageRole, FunctionType, } from "./type.js";
 export { setCurrentConversationMemory, deleteCurrentConversationMemory, } from "./ChatProvider/index.js";
 export { useCMNDChatContext } from "./ChatProvider/useChatContext.js";
+export { useCMNDChat, } from "./hooks/use-cmnd-chat.js";

package/dist/services/deleteChatbotConversationMemory/index.d.ts

@@ -5,5 +5,5 @@ interface IDeleteChatbotConversationMemory {
     memoryKeyToDelete: string;
     baseUrl: string;
 }
-declare const deleteChatbotConversationMemory: ({ organizationId, chatbotId, chatbotConversationRef, memoryKeyToDelete, baseUrl, }: IDeleteChatbotConversationMemory) => Promise<import("axios").AxiosResponse<any, any>>;
+declare const deleteChatbotConversationMemory: ({ organizationId, chatbotId, chatbotConversationRef, memoryKeyToDelete, baseUrl, }: IDeleteChatbotConversationMemory) => Promise<import("axios").AxiosResponse<any, any, {}>>;
 export default deleteChatbotConversationMemory;

package/dist/services/getEmbedChatBotById.d.ts

@@ -1,2 +1,2 @@
-declare const getEmbedChatBotById: (baseUrl: string, organizationId: number, chatbotId: number) => Promise<import("axios").AxiosResponse<any, any>>;
+declare const getEmbedChatBotById: (baseUrl: string, organizationId: number, chatbotId: number) => Promise<import("axios").AxiosResponse<any, any, {}>>;
 export default getEmbedChatBotById;

package/dist/services/patchChatbotConversationMemory/index.d.ts

@@ -7,5 +7,5 @@ interface IPatchChatbotConversationMemory {
     };
     baseUrl: string;
 }
-declare const patchChatbotConversationMemory: ({ organizationId, chatbotId, chatbotConversationRef, memory, baseUrl, }: IPatchChatbotConversationMemory) => Promise<import("axios").AxiosResponse<any, any>>;
+declare const patchChatbotConversationMemory: ({ organizationId, chatbotId, chatbotConversationRef, memory, baseUrl, }: IPatchChatbotConversationMemory) => Promise<import("axios").AxiosResponse<any, any, {}>>;
 export default patchChatbotConversationMemory;

package/dist/type.d.ts

@@ -1,46 +1,58 @@
 import { CSSProperties } from "react";
 import { ConversationProps } from "./components/Conversation.js";
+/**
+ * Context interface for the CMND Chat system.
+ * This is used primarily by the internal provider but can be accessed via useCMNDChatContext.
+ */
 export interface CmndChatContext {
+    /** Internal props passed to the conversation view. */
     props: Partial<ConversationProps>;
-    /**
-     * Create a new conversation (resets state, starts a new chat thread)
-     */
+    /** Create a new conversation (resets state, starts a new chat thread). */
     createNewConversation: () => void;
-    /**
-     * Toggle the sidebar open/collapsed state
-     */
+    /** Toggle the sidebar open/collapsed state. */
     toggleSidebar: () => void;
-    /**
-     * Open the sidebar (set collapsed to false)
-     */
+    /** Open the sidebar (set collapsed to false). */
     openSidePanel: () => void;
-    /**
-     * Close the sidebar (set collapsed to true)
-     */
+    /** Close the sidebar (set collapsed to true). */
     closeSidePanel: () => void;
-    /**
-     * Set the message text in the input box
-     */
+    /** Set the message text in the input box. */
     setMessageText: (text: string) => void;
-    /**
-     * Send the current message, or set and send if text is provided
-     */
+    /** Send the current message, or set and send if text is provided. */
     sendMessage: (text?: string) => void;
 }
+/**
+ * Props for a custom input field component.
+ */
 export interface InputFieldProps {
+    /** The current input text. */
     input: string;
+    /** Setter for the input text. */
     setInput: (input: string) => void;
+    /** Whether the send button should be enabled. */
     canSendMessage: boolean;
+    /** Callback to trigger the send action. */
     handleSendClick: () => void;
-    inputRef?: React.RefObject<HTMLInputElement> | React.RefObject<HTMLTextAreaElement> | React.RefObject<HTMLTextAreaElement>;
+    /** Ref for the input element. */
+    inputRef?: React.RefObject<HTMLInputElement> | React.RefObject<HTMLTextAreaElement>;
 }
+/**
+ * Props for a custom send button component.
+ */
 export interface SendButtonProps {
+    /** Callback to trigger the send action. */
     handleSendClick: () => void;
+    /** Whether the button should be enabled. */
     canSendMessage: boolean;
 }
+/**
+ * Utility type for wrapping API responses that might contain an error.
+ */
 export type ErrorOrData<T> = {
     error: unknown;
 } | T;
+/**
+ * Represents a conversation object from the server.
+ */
 export interface Conversation {
     conversationId: number;
     conversationTitle: string;
@@ -50,35 +62,54 @@ export interface Conversation {
     costLimit: number;
     systemPrompt: string;
     enabledTools: any[];
-    /** Date string format */
+    /** Date string format (UTC). */
     createdAt: string;
-    /** Date string format */
+    /** Date string format (UTC). */
     updatedAt: string;
 }
+/**
+ * Data object received via streaming or finalized responses.
+ */
 export interface ConversationDataObject {
+    /** Indicates if the AI has finished generating the response text. */
     completionFinished: boolean;
+    /** Indicates if this is the final message containing usage metadata. */
     finalResponseWithUsageData: boolean;
+    /** The message text (full or chunk). */
     message?: string;
+    /** The conversation reference ID. */
     chatbotConversationRef?: string;
+    /** Alias for chatbotConversationRef used in some stream responses. */
+    conversationRef?: string;
+    /** Total tokens used in the conversation so far. */
     totalTokens?: number;
+    /** Total cost of the conversation so far. */
     totalCost?: number;
+    /** Updated list of all messages in the conversation. */
     messages?: Message[];
+    /** Indicates if an error occurred during streaming. */
+    hasError?: boolean;
+    /** Path associated with the error if available. */
+    errorPath?: string[] | string;
+    /** Indicates if a function call is currently being streamed. */
+    streamingFunctionCall?: boolean;
+    /** Name of the function being called. */
+    functionName?: string;
+    /** Result of a function execution. */
+    functionResult?: any;
 }
-interface ToolArgument {
-    type: string;
-    description: string;
-    default?: any;
-}
-interface ToolArguments {
-    type: string;
-    default?: any;
-    properties: Record<string, ToolArgument>;
-    required?: string[];
-}
+/**
+ * Defines the type of tool function.
+ */
 export declare enum FunctionType {
+    /** Tool that renders a React component in the chat. */
     UI = "ui",
+    /** Tool that runs on the backend. */
     BACKEND = "backend"
 }
+/**
+ * Metadata for a tool.
+ */
 export type ToolData = {
     name: string;
     description: string;
@@ -87,62 +118,105 @@ export type ToolData = {
     subsubcategory?: string;
     functionType: FunctionType;
     dangerous: boolean;
-    arguments: ToolArguments;
-};
-export type UIFunctionArguments<AIProvidedParams> = {
-    functionArgs: AIProvidedParams;
-    previousRunResults?: string;
-    captureResults: (result: string) => void;
+    arguments: any;
 };
+/**
+ * Represents a tool that can be used within the chatbot.
+ */
 export interface CMNDChatbotUITool {
+    /** Unique name of the tool. */
     name: string;
+    /** Description of what the tool does. */
     description: string;
+    /** Category for organizational purposes. */
     category: string;
+    /** Subcategory for finer organization. */
     subcategory?: string;
+    /** Indicates if the tool should be treated as dangerous (e.g., requires confirmation). */
     dangerous?: boolean;
+    /** Command aliases that might trigger this tool. */
     associatedCommands?: string[];
+    /** Prerequisites required before this tool can run. */
     prerequisites?: string[];
+    /** JSON Schema for the tool's arguments. */
     argumentSchema: any;
+    /** Whether the tool can be re-run after finishing. */
     rerun?: boolean;
+    /** Whether the tool can be re-run with different parameters. */
     rerunWithDifferentParameters?: boolean;
+    /** Whether the tool requires further user input. */
     capturesUserInput?: boolean;
+    /** Explicitly set to 'ui' for UI-based tools. */
     functionType?: "ui";
+    /** The function implementation to run when the tool is called. */
     runCmd: (args: {
         functionArgs?: Record<string, any>;
         captureResults?: (result: any) => Promise<any>;
         previousRunResults?: any;
     }, ref?: React.RefObject<HTMLElement>) => void;
 }
+/**
+ * Roles for different message types.
+ */
 export declare enum MessageRole {
+    /** A tool call or result. */
     FUNCTION = "function",
+    /** A message from the user. */
     USER = "user",
+    /** A message from the AI assistant. */
     ASSISTANT = "assistant",
+    /** A system instruction. */
     SYSTEM = "system"
 }
 type MessageRoleExceptFunctions = Exclude<MessageRole, MessageRole.FUNCTION>;
+/**
+ * Base message structure.
+ */
 interface GenericMessage {
     id: string;
+    /** Whether the message should be hidden or ignored in some contexts. */
     unuseful: boolean;
+    /** Whether the message is visible to the end user. */
     hiddenFromUser: boolean;
+    /** The text content of the message. */
     message?: string;
+    /** The role of the sender. */
     role: MessageRoleExceptFunctions;
 }
+/**
+ * Details of a tool call or its execution result.
+ */
 export interface ToolDetails {
+    /** Arguments passed by the AI. */
     args: any;
+    /** Name of the tool called. */
     name: string;
+    /** Whether the tool run has been confirmed. */
     confirmed?: boolean;
+    /** Timestamp of when the tool was run. */
     runAt?: string;
+    /** The result/output of the tool execution. */
     output?: string;
 }
+/**
+ * A message representing a tool call.
+ */
 interface ToolMessage {
     id: string;
     unuseful: boolean;
     hiddenFromUser: boolean;
     message?: string;
     role: MessageRole.FUNCTION;
+    /** Details about the tool call. */
     tool: ToolDetails;
 }
+/**
+ * Union type for all possible message types in a conversation.
+ */
 export type Message = GenericMessage | ToolMessage;
+/**
+ * CSS properties for customizing various parts of the chatbot UI.
+ */
 export interface CustomStyles {
     chatAvatarStyle?: CSSProperties;
     inputStyle?: CSSProperties;
@@ -163,9 +237,15 @@ export interface CustomStyles {
     dateStyle?: CSSProperties;
     deleteButtonStyle?: CSSProperties;
 }
+/**
+ * KV store for conversation memory/context.
+ */
 export interface CMNDChatMemory {
     [key: string]: any;
 }
+/**
+ * Simple message structure used in the ChatbotConversation summary.
+ */
 export interface ChatbotConversationMessage {
     id?: string;
     role: "user" | "assistant";
@@ -173,16 +253,30 @@ export interface ChatbotConversationMessage {
     unuseful: boolean;
     hiddenFromUser: boolean;
 }
+/**
+ * Full conversation metadata and history.
+ */
 export interface ChatbotConversation {
+    /** Unique reference for the conversation. */
     chatbotConversationRef: string;
+    /** Snapshot of message history. */
     messages: ChatbotConversationMessage[];
+    /** ID of the parent chatbot. */
     chatbotId: number;
+    /** Human-readable title for the conversation. */
     chatbotConversationTitle: string;
+    /** Creation timestamp. */
     createdAt: string;
+    /** Last update timestamp. */
     updatedAt: string;
+    /** Cumulative cost of this thread. */
     totalCostSoFar: number;
+    /** Cumulative token count for this thread. */
     totalTokensSoFar: number;
 }
+/**
+ * Response structure when listing conversations.
+ */
 export interface ChatbotConversationsResponse {
     chatbotConversations: ChatbotConversation[];
 }

package/dist/type.js

@@ -1,12 +1,24 @@
+/**
+ * Defines the type of tool function.
+ */
 export var FunctionType;
 (function (FunctionType) {
+    /** Tool that renders a React component in the chat. */
     FunctionType["UI"] = "ui";
+    /** Tool that runs on the backend. */
     FunctionType["BACKEND"] = "backend";
 })(FunctionType = FunctionType || (FunctionType = {}));
+/**
+ * Roles for different message types.
+ */
 export var MessageRole;
 (function (MessageRole) {
+    /** A tool call or result. */
     MessageRole["FUNCTION"] = "function";
+    /** A message from the user. */
     MessageRole["USER"] = "user";
+    /** A message from the AI assistant. */
     MessageRole["ASSISTANT"] = "assistant";
+    /** A system instruction. */
     MessageRole["SYSTEM"] = "system";
 })(MessageRole = MessageRole || (MessageRole = {}));

package/dist/utils/cleanMarkdown.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cleans markdown characters from a string to return plaintext.
+ * This is a simple regex-based cleaner that handles common markdown patterns.
+ *
+ * @param markdown The markdown string to clean.
+ * @returns The cleaned plaintext string.
+ */
+export declare const cleanMarkdown: (markdown: string) => string;

package/dist/utils/cleanMarkdown.js

@@ -0,0 +1,31 @@
+/**
+ * Cleans markdown characters from a string to return plaintext.
+ * This is a simple regex-based cleaner that handles common markdown patterns.
+ *
+ * @param markdown The markdown string to clean.
+ * @returns The cleaned plaintext string.
+ */
+export const cleanMarkdown = (markdown) => {
+    if (!markdown)
+        return "";
+    return (markdown
+        // Handle bold/italic
+        .replace(/(\*\*|__)(.*?)\1/g, "$2")
+        .replace(/(\*|_)(.*?)\1/g, "$2")
+        // Handle links: [text](url) -> text
+        .replace(/\[(.*?)\]\(.*?\)/g, "$1")
+        // Handle code blocks
+        .replace(/```[\s\S]*?```/g, (match) => {
+        return match.replace(/```(\w+)?\n?|```/g, "").trim();
+    })
+        // Handle inline code
+        .replace(/`(.*?)`/g, "$1")
+        // Handle headers: # Header -> Header
+        .replace(/^#+\s+/gm, "")
+        // Handle blockquotes: > quote -> quote
+        .replace(/^>\s+/gm, "")
+        // Handle horizontal rules
+        .replace(/^-{3,}|^\*{3,}|^\_{3,}/gm, "")
+        // Handle images: ![alt](url) -> alt
+        .replace(/!\[(.*?)\]\(.*?\)/g, "$1"));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmnd-ai/chatbot-react",
-  "version": "1.10.0",
+  "version": "1.13.0",
   "main": "dist/index.js",
   "description": "",
   "type": "module",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "axios": "^1.7.5",
+    "axios": "^1.13.1",
     "react-error-boundary": "^4.0.13",
     "react-icons": "^5.3.0",
     "react-markdown": "^8.0.6",

package/readme.dev.md

@@ -28,3 +28,52 @@
    ```
 
 This will allow you to test your local changes in another project without publishing to npm.
+
+## Core Hook Implementation (`useCMNDChat`)
+
+The `useCMNDChat` hook is designed to be the logic engine of the chatbot. Key implementation details:
+
+- **State Management**: Uses native React `useState` for messages, input, and loading states.
+- **Real-time Streaming**: Utilizes `postUserConversation` with a stream reader to process response chunks.
+- **Tool Orchestration**:
+  - **Backend Tools**: Automatically confirms tool call by setting `confirmed: true`. This triggers the server to execute the tool and return the actual data.
+  - **UI Tools**: Fires the `onToolCall` callback. The developer must execute the tool logic and call `submitToolResult(output)`.
+- **Message Cleaning**: When `cleanResponse: true` is enabled, assistant messages are passed through a `cleanMarkdown` utility to return plaintext.
+- **Persistence**: Automatically saves and loads conversation IDs from `localStorage` based on the `organizationId` and `chatbotId`.
+
+### Tool Call Flow
+
+1. AI generates a `function_call`.
+2. Hook receives the call and adds a message with `role: "function"` to the state (internally).
+3. **Internal Behavior:**
+   - **Backend Tools**: The hook automatically calls `confirmBackendTool()`. This sends a confirmed message back to the server.
+   - **UI Tools**: The hook notifies the developer via `onToolCall`.
+4. **Execution:**
+   - **Backend Tools**: The server receives the confirmation, executes the tool, and returns the real data in the next stream update.
+   - **UI Tools**: The developer manually calls `submitToolResult(data)` with the result of the frontend execution.
+5. The conversation resumes with the tool results included in the history.
+
+### Backend Tool Data Flow
+
+```
+User: "Show my playlists"
+  ↓
+AI calls: get_playlists() (role: function)
+  ↓
+Hook auto-confirms: internal confirmBackendTool() (sets confirmed: true)
+  ↓
+Server executes and returns: { playlists: [...] } (Actual data)
+  ↓
+AI receives data and responds: "Here are your playlists: ..."
+```
+
+**Note**: `FUNCTION` role messages are filtered out from the `messages` array returned by the hook to keep the UI clean. Only `USER` and `ASSISTANT` messages are exposed.
+
+## Building and Releasing
+
+1. **Build the package:**
+   ```sh
+   npm run build
+   ```
+2. **Release:**
+   This project uses `semantic-release` for automated versioning and npm publishing. Ensure your commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.