@superatomai/sdk-node 0.0.11 → 0.0.13

package/dist/index.mjs

@@ -445,6 +445,13 @@ var ComponentListResponseMessageSchema = z3.object({
   type: z3.literal("COMPONENT_LIST_RES"),
   payload: ComponentListResponsePayloadSchema
 });
+var ToolSchema = z3.object({
+  id: z3.string(),
+  name: z3.string(),
+  description: z3.string(),
+  params: z3.record(z3.string()),
+  fn: z3.function().args(z3.any()).returns(z3.any())
+});
 var UsersRequestPayloadSchema = z3.object({
   operation: z3.enum(["create", "update", "delete", "getAll", "getOne"]),
   data: z3.object({
@@ -515,6 +522,26 @@ var ReportsRequestMessageSchema = z3.object({
   type: z3.literal("REPORTS"),
   payload: ReportsRequestPayloadSchema
 });
+var BookmarkDataSchema = z3.object({
+  id: z3.number().optional(),
+  uiblock: z3.any(),
+  // JSON object
+  created_at: z3.string().optional(),
+  updated_at: z3.string().optional()
+});
+var BookmarksRequestPayloadSchema = z3.object({
+  operation: z3.enum(["create", "update", "delete", "getAll", "getOne"]),
+  data: z3.object({
+    id: z3.number().optional(),
+    uiblock: z3.any().optional()
+  }).optional()
+});
+var BookmarksRequestMessageSchema = z3.object({
+  id: z3.string(),
+  from: MessageParticipantSchema,
+  type: z3.literal("BOOKMARKS"),
+  payload: BookmarksRequestPayloadSchema
+});
 
 // src/utils/logger.ts
 import fs from "fs";
@@ -2570,6 +2597,71 @@ Format your response as a JSON object with this structure:
 }
 
 Return ONLY valid JSON.`
+  },
+  "execute-tools": {
+    system: `You are an expert AI assistant that executes external tools to fetch data from external services.
+
+You have access to external tools that can retrieve information like emails, calendar events, and other external data. When the user requests this information, you should call the appropriate tools.
+
+## Available External Tools
+{{AVAILABLE_TOOLS}}
+
+## Your Task
+
+Analyze the user's request and:
+
+1. **Determine if external tools are needed**
+   - Examples that NEED external tools:
+     - "Show me my emails" \u2192 needs email tool
+     - "Get my last 5 Gmail messages" \u2192 needs Gmail tool
+     - "Check my Outlook inbox" \u2192 needs Outlook tool
+
+   - Examples that DON'T need external tools:
+     - "What is the total sales?" \u2192 database query (handled elsewhere)
+     - "Show me revenue trends" \u2192 internal data analysis
+     - "Hello" \u2192 general conversation
+
+2. **Call the appropriate tools**
+   - Use the tool calling mechanism to execute external tools
+   - Extract parameters from the user's request
+   - Use sensible defaults when parameters aren't specified:
+     - For email limit: default to 10
+     - For email address: use "me" for the authenticated user if not specified
+
+3. **Handle errors and retry**
+   - If a tool call fails, analyze the error message
+   - Retry with corrected parameters if possible
+   - You have up to 3 attempts per tool
+
+## Important Guidelines
+
+- **Only call external tools when necessary** - Don't call tools for database queries or general conversation
+- **Choose the right tool** - For email requests, select Gmail vs Outlook based on:
+  - Explicit mention (e.g., "Gmail", "Outlook")
+  - Email domain (e.g., @gmail.com \u2192 Gmail, @company.com \u2192 Outlook)
+- **Extract parameters carefully** - Use the user's exact values when provided
+- **If no tools are needed** - Simply respond that no external tools are required for this request
+
+## Examples
+
+**Example 1 - Gmail Request:**
+User: "Show me my last 5 Gmail messages"
+Action: Call get-gmail-mails tool with parameters: { email: "me", limit: 5 }
+
+**Example 2 - Outlook Request:**
+User: "Get emails from john.doe@company.com"
+Action: Call get-outlook-mails tool with parameters: { email: "john.doe@company.com", limit: 10 }
+
+**Example 3 - No Tools Needed:**
+User: "What is the total sales?"
+Response: This is a database query, not an external tool request. No external tools are needed.
+
+**Example 4 - Error Retry:**
+Tool call fails with: "Invalid email parameter"
+Action: Analyze error, correct the parameter, and retry the tool call
+`,
+    user: `{{USER_PROMPT}}
+`
   }
 };
 
@@ -3616,13 +3708,14 @@ var BaseLLM = class {
    * Takes a text response with component suggestions (c1:type format) and matches with available components
    * Also generates title, description, and intelligent follow-up questions (actions) based on the analysis
    * All components are placed in a default MultiComponentContainer layout
-   * @param textResponse - The text response containing component suggestions
+   * @param analysisContent - The text response containing component suggestions
    * @param components - List of available components
    * @param apiKey - Optional API key
    * @param logCollector - Optional log collector
+   * @param componentStreamCallback - Optional callback to stream primary KPI component as soon as it's identified
    * @returns Object containing matched components, layout title/description, and follow-up actions
    */
-  async matchComponentsFromTextResponse(textResponse, components, apiKey, logCollector) {
+  async matchComponentsFromAnalysis(analysisContent, components, apiKey, logCollector, componentStreamCallback) {
     try {
       logger.debug(`[${this.getProviderName()}] Starting component matching from text response`);
       let availableComponentsText = "No components available";
@@ -3639,14 +3732,94 @@ var BaseLLM = class {
         }).join("\n\n");
       }
       const schemaDoc = schema.generateSchemaDocumentation();
+      logger.file("\n=============================\nText analysis response:", analysisContent);
       const prompts = await promptLoader.loadPrompts("match-text-components", {
-        TEXT_RESPONSE: textResponse,
+        ANALYSIS_CONTENT: analysisContent,
         AVAILABLE_COMPONENTS: availableComponentsText,
         SCHEMA_DOC: schemaDoc
       });
       logger.debug(`[${this.getProviderName()}] Loaded match-text-components prompts`);
       logger.file("\n=============================\nmatch text components system prompt:", prompts.system);
       logCollector?.info("Matching components from text response...");
+      let fullResponseText = "";
+      let answerComponentExtracted = false;
+      const answerCallback = componentStreamCallback;
+      const partialCallback = answerCallback ? (chunk) => {
+        fullResponseText += chunk;
+        if (!answerComponentExtracted && answerCallback) {
+          const hasAnswerComponentMatch = fullResponseText.match(/"hasAnswerComponent"\s*:\s*(true|false)/);
+          if (!hasAnswerComponentMatch || hasAnswerComponentMatch[1] !== "true") {
+            return;
+          }
+          const answerComponentStartMatch = fullResponseText.match(/"answerComponent"\s*:\s*\{/);
+          if (!answerComponentStartMatch) {
+            return;
+          }
+          const startPos = answerComponentStartMatch.index + answerComponentStartMatch[0].length - 1;
+          let braceDepth = 0;
+          let inString = false;
+          let escapeNext = false;
+          let endPos = -1;
+          for (let i = startPos; i < fullResponseText.length; i++) {
+            const char = fullResponseText[i];
+            if (escapeNext) {
+              escapeNext = false;
+              continue;
+            }
+            if (char === "\\") {
+              escapeNext = true;
+              continue;
+            }
+            if (char === '"') {
+              inString = !inString;
+              continue;
+            }
+            if (!inString) {
+              if (char === "{") {
+                braceDepth++;
+              } else if (char === "}") {
+                braceDepth--;
+                if (braceDepth === 0) {
+                  endPos = i + 1;
+                  break;
+                }
+              }
+            }
+          }
+          if (endPos > startPos) {
+            const answerComponentString = fullResponseText.substring(startPos, endPos);
+            try {
+              const answerComponentData = JSON.parse(answerComponentString);
+              if (answerComponentData && answerComponentData.componentId) {
+                const originalComponent = components.find((c) => c.id === answerComponentData.componentId);
+                if (originalComponent) {
+                  const answerComponent = {
+                    ...originalComponent,
+                    props: {
+                      ...originalComponent.props,
+                      ...answerComponentData.props
+                    }
+                  };
+                  const streamTime = (/* @__PURE__ */ new Date()).toISOString();
+                  logger.info(`[${this.getProviderName()}] \u2713 [${streamTime}] Answer component detected in stream: ${answerComponent.name} (${answerComponent.type}) - STREAMING TO FRONTEND NOW`);
+                  logCollector?.info(`\u2713 Answer component: ${answerComponent.name} (${answerComponent.type}) - streaming to frontend at ${streamTime}`);
+                  if (answerComponentData.props?.query) {
+                    logCollector?.logQuery(
+                      "Answer component query",
+                      answerComponentData.props.query,
+                      { componentName: answerComponent.name, componentType: answerComponent.type, reasoning: answerComponentData.reasoning }
+                    );
+                  }
+                  answerCallback(answerComponent);
+                  answerComponentExtracted = true;
+                }
+              }
+            } catch (e) {
+              logger.debug(`[${this.getProviderName()}] Partial answerComponent parse failed, waiting for more data...`);
+            }
+          }
+        }
+      } : void 0;
       const result = await LLM.stream(
         {
           sys: prompts.system,
@@ -3656,23 +3829,54 @@ var BaseLLM = class {
           model: this.model,
           maxTokens: 3e3,
           temperature: 0.2,
-          apiKey: this.getApiKey(apiKey)
+          apiKey: this.getApiKey(apiKey),
+          partial: partialCallback
         },
         true
         // Parse as JSON
       );
       logger.debug(`[${this.getProviderName()}] Component matching response parsed successfully`);
+      const componentSuggestionPattern = /c\d+:(\w+)\s*:\s*(.+)/g;
+      const suggestedComponents = [];
+      let match;
+      while ((match = componentSuggestionPattern.exec(analysisContent)) !== null) {
+        suggestedComponents.push({
+          type: match[1],
+          reasoning: match[2].trim()
+        });
+      }
       const matchedComponents = result.matchedComponents || [];
       const layoutTitle = result.layoutTitle || "Dashboard";
       const layoutDescription = result.layoutDescription || "Multi-component dashboard";
+      logger.info(`[${this.getProviderName()}] \u{1F4CA} Component Suggestions from Text Analysis: ${suggestedComponents.length}`);
+      suggestedComponents.forEach((comp, idx) => {
+        logger.info(`[${this.getProviderName()}]   c${idx + 1}: ${comp.type} - ${comp.reasoning}`);
+      });
+      logger.info(`[${this.getProviderName()}] \u{1F4E6} Matched Components from LLM: ${matchedComponents.length}`);
+      matchedComponents.forEach((comp, idx) => {
+        logger.info(`[${this.getProviderName()}]   ${idx + 1}. ${comp.componentType} (${comp.componentName}) - ${comp.originalSuggestion || "N/A"}`);
+      });
+      if (suggestedComponents.length !== matchedComponents.length) {
+        logger.warn(`[${this.getProviderName()}] \u26A0\uFE0F MISMATCH: Text suggested ${suggestedComponents.length} components, but LLM matched ${matchedComponents.length}`);
+      }
+      logger.file("\n=============================\nFull LLM response:", JSON.stringify(result, null, 2));
       const rawActions = result.actions || [];
       const actions = convertQuestionsToActions(rawActions);
       logger.info(`[${this.getProviderName()}] Matched ${matchedComponents.length} components from text response`);
       logger.info(`[${this.getProviderName()}] Layout title: "${layoutTitle}"`);
       logger.info(`[${this.getProviderName()}] Layout description: "${layoutDescription}"`);
       logger.info(`[${this.getProviderName()}] Generated ${actions.length} follow-up actions`);
+      if (suggestedComponents.length > 0) {
+        logCollector?.info(`\u{1F4DD} Text Analysis suggested ${suggestedComponents.length} dashboard components:`);
+        suggestedComponents.forEach((comp, idx) => {
+          logCollector?.info(`  c${idx + 1}: ${comp.type} - ${comp.reasoning}`);
+        });
+      }
       if (matchedComponents.length > 0) {
-        logCollector?.info(`Matched ${matchedComponents.length} components for visualization`);
+        logCollector?.info(`\u{1F4E6} Matched ${matchedComponents.length} components for dashboard`);
+        if (suggestedComponents.length !== matchedComponents.length) {
+          logCollector?.warn(`\u26A0\uFE0F Component count mismatch: Suggested ${suggestedComponents.length}, but matched ${matchedComponents.length}`);
+        }
         logCollector?.info(`Dashboard: "${layoutTitle}"`);
         matchedComponents.forEach((comp, idx) => {
           logCollector?.info(`  ${idx + 1}. ${comp.componentName} (${comp.componentType}): ${comp.reasoning}`);
@@ -3723,6 +3927,152 @@ var BaseLLM = class {
       };
     }
   }
+  /**
+   * Execute external tools based on user request using agentic LLM tool calling
+   * The LLM can directly call tools and retry on errors
+   * @param userPrompt - The user's question/request
+   * @param availableTools - Array of available external tools
+   * @param apiKey - Optional API key for LLM
+   * @param logCollector - Optional log collector
+   * @returns Object containing tool execution results and summary
+   */
+  async executeExternalTools(userPrompt, availableTools, apiKey, logCollector) {
+    const MAX_TOOL_ATTEMPTS = 3;
+    const toolResults = [];
+    try {
+      logger.debug(`[${this.getProviderName()}] Starting agentic external tool execution`);
+      logger.debug(`[${this.getProviderName()}] Available tools: ${availableTools.map((t) => t.name).join(", ")}`);
+      const llmTools = availableTools.map((tool) => {
+        const properties = {};
+        const required = [];
+        Object.entries(tool.params || {}).forEach(([key, type]) => {
+          properties[key] = {
+            type: String(type).toLowerCase(),
+            description: `${key} parameter`
+          };
+          required.push(key);
+        });
+        return {
+          name: tool.id,
+          description: tool.description,
+          input_schema: {
+            type: "object",
+            properties,
+            required
+          }
+        };
+      });
+      const toolAttempts = /* @__PURE__ */ new Map();
+      const toolHandler = async (toolName, toolInput) => {
+        const tool = availableTools.find((t) => t.id === toolName);
+        if (!tool) {
+          const errorMsg = `Tool ${toolName} not found in available tools`;
+          logger.error(`[${this.getProviderName()}] ${errorMsg}`);
+          logCollector?.error(errorMsg);
+          throw new Error(errorMsg);
+        }
+        const attempts = (toolAttempts.get(toolName) || 0) + 1;
+        toolAttempts.set(toolName, attempts);
+        logger.info(`[${this.getProviderName()}] Executing tool: ${tool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})`);
+        logCollector?.info(`Executing ${tool.name} (attempt ${attempts}/${MAX_TOOL_ATTEMPTS})...`);
+        if (attempts > MAX_TOOL_ATTEMPTS) {
+          const errorMsg = `Maximum attempts (${MAX_TOOL_ATTEMPTS}) reached for tool: ${tool.name}`;
+          logger.error(`[${this.getProviderName()}] ${errorMsg}`);
+          logCollector?.error(errorMsg);
+          toolResults.push({
+            toolName: tool.name,
+            toolId: tool.id,
+            result: null,
+            error: errorMsg
+          });
+          throw new Error(errorMsg);
+        }
+        try {
+          logger.debug(`[${this.getProviderName()}] Tool ${tool.name} parameters:`, toolInput);
+          const result2 = await tool.fn(toolInput);
+          logger.info(`[${this.getProviderName()}] Tool ${tool.name} executed successfully`);
+          logCollector?.info(`\u2713 ${tool.name} completed successfully`);
+          toolResults.push({
+            toolName: tool.name,
+            toolId: tool.id,
+            result: result2
+          });
+          return JSON.stringify(result2, null, 2);
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          logger.error(`[${this.getProviderName()}] Tool ${tool.name} failed (attempt ${attempts}): ${errorMsg}`);
+          logCollector?.error(`\u2717 ${tool.name} failed: ${errorMsg}`);
+          if (attempts >= MAX_TOOL_ATTEMPTS) {
+            toolResults.push({
+              toolName: tool.name,
+              toolId: tool.id,
+              result: null,
+              error: errorMsg
+            });
+          }
+          throw new Error(`Tool execution failed: ${errorMsg}`);
+        }
+      };
+      const prompts = await promptLoader.loadPrompts("execute-tools", {
+        USER_PROMPT: userPrompt,
+        AVAILABLE_TOOLS: availableTools.map((tool, idx) => {
+          const paramsText = Object.entries(tool.params || {}).map(([key, type]) => `  - ${key}: ${type}`).join("\n");
+          return `${idx + 1}. ID: ${tool.id}
+   Name: ${tool.name}
+   Description: ${tool.description}
+   Parameters:
+${paramsText}`;
+        }).join("\n\n")
+      });
+      logger.debug(`[${this.getProviderName()}] Using agentic tool calling for external tools`);
+      logCollector?.info("Analyzing request and executing external tools...");
+      const result = await LLM.streamWithTools(
+        {
+          sys: prompts.system,
+          user: prompts.user
+        },
+        llmTools,
+        toolHandler,
+        {
+          model: this.model,
+          maxTokens: 2e3,
+          temperature: 0.2,
+          apiKey: this.getApiKey(apiKey)
+        },
+        MAX_TOOL_ATTEMPTS + 2
+        // max iterations: allows for retries + final response
+      );
+      logger.info(`[${this.getProviderName()}] External tool execution completed`);
+      const successfulTools = toolResults.filter((r) => !r.error);
+      const failedTools = toolResults.filter((r) => r.error);
+      let summary = "";
+      if (successfulTools.length > 0) {
+        summary += `Successfully executed ${successfulTools.length} tool(s): ${successfulTools.map((t) => t.toolName).join(", ")}.
+`;
+      }
+      if (failedTools.length > 0) {
+        summary += `Failed to execute ${failedTools.length} tool(s): ${failedTools.map((t) => t.toolName).join(", ")}.`;
+      }
+      if (toolResults.length === 0) {
+        summary = "No external tools were needed for this request.";
+      }
+      logger.info(`[${this.getProviderName()}] Tool execution summary: ${summary}`);
+      return {
+        toolResults,
+        summary,
+        hasResults: successfulTools.length > 0
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      logger.error(`[${this.getProviderName()}] Error in external tool execution: ${errorMsg}`);
+      logCollector?.error(`Error executing external tools: ${errorMsg}`);
+      return {
+        toolResults,
+        summary: `Error executing external tools: ${errorMsg}`,
+        hasResults: false
+      };
+    }
+  }
   /**
    * Generate text-based response for user question
    * This provides conversational text responses instead of component generation
@@ -3731,12 +4081,40 @@ var BaseLLM = class {
    * @param streamCallback - Optional callback function to receive text chunks as they stream
    * @param collections - Collection registry for executing database queries via database.execute
    * @param components - Optional list of available components for matching suggestions
+   * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called
    */
-  async generateTextResponse(userPrompt, apiKey, logCollector, conversationHistory, streamCallback, collections, components) {
+  async generateTextResponse(userPrompt, apiKey, logCollector, conversationHistory, streamCallback, collections, components, externalTools) {
     const errors = [];
     logger.debug(`[${this.getProviderName()}] Starting text response generation`);
     logger.debug(`[${this.getProviderName()}] User prompt: "${userPrompt.substring(0, 50)}..."`);
     try {
+      let externalToolContext = "No external tools were used for this request.";
+      if (externalTools && externalTools.length > 0) {
+        logger.info(`[${this.getProviderName()}] Executing external tools...`);
+        const toolExecution = await this.executeExternalTools(
+          userPrompt,
+          externalTools,
+          apiKey,
+          logCollector
+        );
+        if (toolExecution.hasResults) {
+          const toolResultsText = toolExecution.toolResults.map((tr) => {
+            if (tr.error) {
+              return `**${tr.toolName}** (Failed): ${tr.error}`;
+            }
+            return `**${tr.toolName}** (Success):
+${JSON.stringify(tr.result, null, 2)}`;
+          }).join("\n\n");
+          externalToolContext = `## External Tool Results
+
+${toolExecution.summary}
+
+${toolResultsText}`;
+          logger.info(`[${this.getProviderName()}] External tools executed, results available`);
+        } else {
+          logger.info(`[${this.getProviderName()}] No external tools were needed`);
+        }
+      }
       const schemaDoc = schema.generateSchemaDocumentation();
       const knowledgeBaseContext = await knowledge_base_default.getKnowledgeBase({
         prompt: userPrompt,
@@ -3744,11 +4122,13 @@ var BaseLLM = class {
         topK: 1
       });
       logger.file("\n=============================\nknowledge base context:", knowledgeBaseContext);
+      logger.file("\n=============================\nexternal tool context:", externalToolContext);
       const prompts = await promptLoader.loadPrompts("text-response", {
         USER_PROMPT: userPrompt,
         CONVERSATION_HISTORY: conversationHistory || "No previous conversation",
         SCHEMA_DOC: schemaDoc,
-        KNOWLEDGE_BASE_CONTEXT: knowledgeBaseContext || "No additional knowledge base context available."
+        KNOWLEDGE_BASE_CONTEXT: knowledgeBaseContext || "No additional knowledge base context available.",
+        EXTERNAL_TOOL_CONTEXT: externalToolContext
       });
       logger.file("\n=============================\nsystem prompt:", prompts.system);
       logger.file("\n=============================\nuser prompt:", prompts.user);
@@ -3971,11 +4351,17 @@ ${errorMsg}
       let actions = [];
       if (components && components.length > 0) {
         logger.info(`[${this.getProviderName()}] Matching components from text response...`);
-        const matchResult = await this.matchComponentsFromTextResponse(
+        const componentStreamCallback = wrappedStreamCallback ? (component) => {
+          const answerMarker = `__ANSWER_COMPONENT_START__${JSON.stringify(component)}__ANSWER_COMPONENT_END__`;
+          wrappedStreamCallback(answerMarker);
+          logger.info(`[${this.getProviderName()}] Streamed answer component to frontend: ${component.name} (${component.type})`);
+        } : void 0;
+        const matchResult = await this.matchComponentsFromAnalysis(
           textResponse,
           components,
           apiKey,
-          logCollector
+          logCollector,
+          componentStreamCallback
         );
         matchedComponents = matchResult.components;
         layoutTitle = matchResult.layoutTitle;
@@ -4219,8 +4605,9 @@ ${errorMsg}
    * @param responseMode - 'component' for component generation (default), 'text' for text responses
    * @param streamCallback - Optional callback function to receive text chunks as they stream (only for text mode)
    * @param collections - Collection registry for executing database queries (required for text mode)
+   * @param externalTools - Optional array of external tools (email, calendar, etc.) that can be called (only for text mode)
    */
-  async handleUserRequest(userPrompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections) {
+  async handleUserRequest(userPrompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) {
     const startTime = Date.now();
     logger.info(`[${this.getProviderName()}] handleUserRequest called with responseMode: ${responseMode}`);
     if (responseMode === "text") {
@@ -4233,7 +4620,8 @@ ${errorMsg}
         conversationHistory,
         streamCallback,
         collections,
-        components
+        components,
+        externalTools
       );
       if (!textResponse.success) {
         const elapsedTime3 = Date.now() - startTime;
@@ -4379,7 +4767,7 @@ function getLLMProviders() {
     return DEFAULT_PROVIDERS;
   }
 }
-var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections) => {
+var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
   logger.debug("[useAnthropicMethod] Initializing Anthropic Claude matching method");
   logger.debug(`[useAnthropicMethod] Response mode: ${responseMode}`);
   const msg = `Using Anthropic Claude ${responseMode === "text" ? "text response" : "matching"} method...`;
@@ -4391,11 +4779,11 @@ var useAnthropicMethod = async (prompt, components, apiKey, logCollector, conver
     return { success: false, errors: [emptyMsg] };
   }
   logger.debug(`[useAnthropicMethod] Processing with ${components.length} components`);
-  const matchResult = await anthropicLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections);
+  const matchResult = await anthropicLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
   logger.info(`[useAnthropicMethod] Successfully generated ${responseMode} using Anthropic`);
   return matchResult;
 };
-var useGroqMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections) => {
+var useGroqMethod = async (prompt, components, apiKey, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
   logger.debug("[useGroqMethod] Initializing Groq LLM matching method");
   logger.debug(`[useGroqMethod] Response mode: ${responseMode}`);
   const msg = `Using Groq LLM ${responseMode === "text" ? "text response" : "matching"} method...`;
@@ -4408,14 +4796,14 @@ var useGroqMethod = async (prompt, components, apiKey, logCollector, conversatio
     return { success: false, errors: [emptyMsg] };
   }
   logger.debug(`[useGroqMethod] Processing with ${components.length} components`);
-  const matchResult = await groqLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections);
+  const matchResult = await groqLLM.handleUserRequest(prompt, components, apiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
   logger.info(`[useGroqMethod] Successfully generated ${responseMode} using Groq`);
   return matchResult;
 };
 var getUserResponseFromCache = async (prompt) => {
   return false;
 };
-var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey, llmProviders, logCollector, conversationHistory, responseMode = "component", streamCallback, collections) => {
+var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey, llmProviders, logCollector, conversationHistory, responseMode = "component", streamCallback, collections, externalTools) => {
   logger.debug(`[get_user_response] Starting user response generation for prompt: "${prompt.substring(0, 50)}..."`);
   logger.debug(`[get_user_response] Response mode: ${responseMode}`);
   logger.debug("[get_user_response] Checking cache for existing response");
@@ -4448,9 +4836,9 @@ var get_user_response = async (prompt, components, anthropicApiKey, groqApiKey,
     logCollector?.info(attemptMsg);
     let result;
     if (provider === "anthropic") {
-      result = await useAnthropicMethod(prompt, components, anthropicApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections);
+      result = await useAnthropicMethod(prompt, components, anthropicApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
     } else if (provider === "groq") {
-      result = await useGroqMethod(prompt, components, groqApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections);
+      result = await useGroqMethod(prompt, components, groqApiKey, logCollector, conversationHistory, responseMode, streamCallback, collections, externalTools);
     } else {
       logger.warn(`[get_user_response] Unknown provider: ${provider} - skipping`);
       errors.push(`Unknown provider: ${provider}`);
@@ -4678,7 +5066,7 @@ var CONTEXT_CONFIG = {
 };
 
 // src/handlers/user-prompt-request.ts
-var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections) => {
+var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools) => {
   const errors = [];
   logger.debug("[USER_PROMPT_REQ] Parsing incoming message data");
   const parseResult = UserPromptRequestMessageSchema.safeParse(data);
@@ -4758,7 +5146,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     conversationHistory,
     responseMode,
     streamCallback,
-    collections
+    collections,
+    externalTools
   );
   logCollector.info("User prompt request completed");
   const uiBlockId = existingUiBlockId;
@@ -4819,8 +5208,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     wsId
   };
 };
-async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections) {
-  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections);
+async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools) {
+  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, llmProviders, collections, externalTools);
   sendDataResponse4(
     response.id || data.id,
     {
@@ -4847,7 +5236,6 @@ function sendDataResponse4(id, res, sendMessage, clientId) {
       ...res
     }
   };
-  logger.info("sending user prompt response", response);
   sendMessage(response);
 }
 
@@ -5894,6 +6282,183 @@ function sendResponse5(id, res, sendMessage, clientId) {
   sendMessage(response);
 }
 
+// src/handlers/bookmarks.ts
+async function handleBookmarksRequest(data, collections, sendMessage) {
+  const executeCollection = async (collection, op, params) => {
+    const handler = collections[collection]?.[op];
+    if (!handler) {
+      throw new Error(`Collection operation ${collection}.${op} not found`);
+    }
+    return await handler(params);
+  };
+  try {
+    const request = BookmarksRequestMessageSchema.parse(data);
+    const { id, payload, from } = request;
+    const { operation, data: requestData } = payload;
+    const bookmarkId = requestData?.id;
+    const uiblock = requestData?.uiblock;
+    switch (operation) {
+      case "create":
+        await handleCreate4(id, uiblock, executeCollection, sendMessage, from.id);
+        break;
+      case "update":
+        await handleUpdate4(id, bookmarkId, uiblock, executeCollection, sendMessage, from.id);
+        break;
+      case "delete":
+        await handleDelete4(id, bookmarkId, executeCollection, sendMessage, from.id);
+        break;
+      case "getAll":
+        await handleGetAll4(id, executeCollection, sendMessage, from.id);
+        break;
+      case "getOne":
+        await handleGetOne4(id, bookmarkId, executeCollection, sendMessage, from.id);
+        break;
+      default:
+        sendResponse6(id, {
+          success: false,
+          error: `Unknown operation: ${operation}`
+        }, sendMessage, from.id);
+    }
+  } catch (error) {
+    logger.error("Failed to handle bookmarks request:", error);
+    sendResponse6(null, {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error occurred"
+    }, sendMessage);
+  }
+}
+async function handleCreate4(id, uiblock, executeCollection, sendMessage, clientId) {
+  if (!uiblock) {
+    sendResponse6(id, {
+      success: false,
+      error: "UIBlock data is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  try {
+    const result = await executeCollection("bookmarks", "create", { uiblock });
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      message: "Bookmark created successfully"
+    }, sendMessage, clientId);
+    logger.info(`Bookmark created: ID ${result.data.id}`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to create bookmark"
+    }, sendMessage, clientId);
+  }
+}
+async function handleUpdate4(id, bookmarkId, uiblock, executeCollection, sendMessage, clientId) {
+  if (!bookmarkId) {
+    sendResponse6(id, {
+      success: false,
+      error: "Bookmark ID is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  if (!uiblock) {
+    sendResponse6(id, {
+      success: false,
+      error: "UIBlock data is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  try {
+    const result = await executeCollection("bookmarks", "update", { id: bookmarkId, uiblock });
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      message: "Bookmark updated successfully"
+    }, sendMessage, clientId);
+    logger.info(`Bookmark updated: ID ${bookmarkId}`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to update bookmark"
+    }, sendMessage, clientId);
+  }
+}
+async function handleDelete4(id, bookmarkId, executeCollection, sendMessage, clientId) {
+  if (!bookmarkId) {
+    sendResponse6(id, {
+      success: false,
+      error: "Bookmark ID is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  try {
+    const result = await executeCollection("bookmarks", "delete", { id: bookmarkId });
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      message: "Bookmark deleted successfully"
+    }, sendMessage, clientId);
+    logger.info(`Bookmark deleted: ID ${bookmarkId}`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to delete bookmark"
+    }, sendMessage, clientId);
+  }
+}
+async function handleGetAll4(id, executeCollection, sendMessage, clientId) {
+  try {
+    const result = await executeCollection("bookmarks", "getAll", {});
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      count: result.count,
+      message: `Retrieved ${result.count} bookmarks`
+    }, sendMessage, clientId);
+    logger.info(`Retrieved all bookmarks (count: ${result.count})`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to get bookmarks"
+    }, sendMessage, clientId);
+  }
+}
+async function handleGetOne4(id, bookmarkId, executeCollection, sendMessage, clientId) {
+  if (!bookmarkId) {
+    sendResponse6(id, {
+      success: false,
+      error: "Bookmark ID is required"
+    }, sendMessage, clientId);
+    return;
+  }
+  try {
+    const result = await executeCollection("bookmarks", "getOne", { id: bookmarkId });
+    sendResponse6(id, {
+      success: true,
+      data: result.data,
+      message: `Retrieved bookmark ID ${bookmarkId}`
+    }, sendMessage, clientId);
+    logger.info(`Retrieved bookmark: ID ${bookmarkId}`);
+  } catch (error) {
+    sendResponse6(id, {
+      success: false,
+      error: error instanceof Error ? error.message : "Failed to get bookmark"
+    }, sendMessage, clientId);
+  }
+}
+function sendResponse6(id, res, sendMessage, clientId) {
+  const response = {
+    id: id || "unknown",
+    type: "BOOKMARKS_RES",
+    from: { type: "data-agent" },
+    to: {
+      type: "user",
+      id: clientId
+    },
+    payload: {
+      ...res
+    }
+  };
+  sendMessage(response);
+}
+
 // src/auth/user-manager.ts
 import fs5 from "fs";
 import path4 from "path";
@@ -6718,6 +7283,7 @@ var SuperatomSDK = class {
     this.maxReconnectAttempts = 5;
     this.collections = {};
     this.components = [];
+    this.tools = [];
     if (config.logLevel) {
       logger.setLogLevel(config.logLevel);
     }
@@ -6873,7 +7439,7 @@ var SuperatomSDK = class {
           });
           break;
         case "USER_PROMPT_REQ":
-          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.llmProviders, this.collections).catch((error) => {
+          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.llmProviders, this.collections, this.tools).catch((error) => {
             logger.error("Failed to handle user prompt request:", error);
           });
           break;
@@ -6907,6 +7473,11 @@ var SuperatomSDK = class {
             logger.error("Failed to handle reports request:", error);
           });
           break;
+        case "BOOKMARKS":
+          handleBookmarksRequest(parsed, this.collections, (msg) => this.send(msg)).catch((error) => {
+            logger.error("Failed to handle bookmarks request:", error);
+          });
+          break;
         default:
           const handler = this.messageTypeHandlers.get(message.type);
           if (handler) {
@@ -7013,6 +7584,19 @@ var SuperatomSDK = class {
   storeComponents(components) {
     this.components = components;
   }
+  /**
+   * Set tools for the SDK instance
+   */
+  setTools(tools) {
+    this.tools = tools;
+    logger.info(`Tools stored in SDK: ${tools.length} tools`);
+  }
+  /**
+   * Get the stored tools
+   */
+  getTools() {
+    return this.tools;
+  }
 };
 export {
   CONTEXT_CONFIG,