@superatomai/sdk-node 0.0.38-mds → 0.0.39-mds

package/dist/index.mjs

@@ -319,6 +319,24 @@ var ComponentListResponseMessageSchema = z3.object({
   type: z3.literal("COMPONENT_LIST_RES"),
   payload: ComponentListResponsePayloadSchema
 });
+var WorkflowDescriptorSchema = z3.object({
+  id: z3.string(),
+  name: z3.string(),
+  description: z3.string(),
+  whenToUse: z3.string(),
+  propsSchema: z3.record(z3.string()),
+  defaultProps: z3.record(z3.unknown()).optional()
+});
+var WorkflowsSchema = z3.array(WorkflowDescriptorSchema);
+var WorkflowListResponsePayloadSchema = z3.object({
+  workflows: z3.array(WorkflowDescriptorSchema)
+});
+var WorkflowListResponseMessageSchema = z3.object({
+  id: z3.string(),
+  from: MessageParticipantSchema,
+  type: z3.literal("WORKFLOW_LIST_RES"),
+  payload: WorkflowListResponsePayloadSchema
+});
 var OutputFieldSchema = z3.object({
   name: z3.string(),
   // Field name (column name in the result)
@@ -7484,8 +7502,9 @@ Even if a table appears in the detailed schema above, search_schema returns samp
 
 // src/userResponse/agents/main-agent.ts
 var MainAgent = class {
-  constructor(externalTools, config, streamBuffer) {
+  constructor(externalTools, config, streamBuffer, workflows = []) {
     this.externalTools = externalTools;
+    this.workflows = workflows;
     this.config = config;
     this.streamBuffer = streamBuffer || new StreamBuffer();
   }
@@ -7504,18 +7523,26 @@ var MainAgent = class {
     logger.info(`[MainAgent] Starting | prompt: "${userPrompt.substring(0, 50)}..."`);
     const sourceTools = this.externalTools.filter((t) => t.toolType !== "direct");
     const directTools = this.externalTools.filter((t) => t.toolType === "direct");
-    logger.info(`[MainAgent] ${sourceTools.length} source tool(s), ${directTools.length} direct tool(s)`);
+    logger.info(`[MainAgent] ${sourceTools.length} source tool(s), ${directTools.length} direct tool(s), ${this.workflows.length} workflow(s)`);
     const summaries = buildSourceSummaries(sourceTools);
-    const systemPrompt = await this.buildSystemPrompt(summaries, directTools, conversationHistory);
+    const systemPrompt = await this.buildSystemPrompt(summaries, directTools, this.workflows, conversationHistory);
     logger.logLLMPrompt("mainAgent", "system", extractPromptText(systemPrompt));
     logger.logLLMPrompt("mainAgent", "user", userPrompt);
     const sourceToolDefs = this.buildSourceToolDefinitions(summaries);
     const directToolDefs = this.buildDirectToolDefinitions(directTools);
-    const tools = [...sourceToolDefs, ...directToolDefs];
+    const workflowToolDefs = this.buildWorkflowToolDefinitions(this.workflows);
+    const tools = [...sourceToolDefs, ...directToolDefs, ...workflowToolDefs];
     const sourceResults = [];
     const executedTools = [];
     let sourceCallCounter = 0;
+    let selectedWorkflow;
     const toolHandler = async (toolName, toolInput) => {
+      const workflow = this.workflows.find((w) => w.id === toolName);
+      if (workflow) {
+        return this.handleWorkflow(workflow, toolInput, (w) => {
+          selectedWorkflow = w;
+        });
+      }
       const externalTool = this.externalTools.find((t) => t.id === toolName);
       if (!externalTool) {
         logger.error(`[MainAgent] Unknown tool called: ${toolName}`);
@@ -7566,11 +7593,14 @@ var MainAgent = class {
       this.config.maxIterations
     );
     const totalTime = Date.now() - startTime;
-    logger.info(`[MainAgent] Complete | ${sourceResults.length} source queries, ${executedTools.length} successful | ${totalTime}ms`);
+    logger.info(
+      `[MainAgent] Complete | ${sourceResults.length} source queries, ${executedTools.length} successful${selectedWorkflow ? ` | workflow="${selectedWorkflow.name}"` : ""} | ${totalTime}ms`
+    );
     return {
       text,
       executedTools,
-      sourceResults
+      sourceResults,
+      workflow: selectedWorkflow
     };
   }
   // ============================================
@@ -7644,9 +7674,10 @@ ${formatted}`;
   // System Prompt
   // ============================================
   /**
-   * Build the main agent's system prompt with source summaries and direct tool descriptions.
+   * Build the main agent's system prompt with source summaries, direct tool descriptions,
+   * and workflow component descriptions.
    */
-  async buildSystemPrompt(summaries, directTools, conversationHistory) {
+  async buildSystemPrompt(summaries, directTools, workflows, conversationHistory) {
     const summariesText = formatSummariesForPrompt(summaries);
     const maxSourceCalls = Math.max(2, this.config.maxIterations - 2);
     let directToolsText = "";
@@ -7658,9 +7689,25 @@ ${formatted}`;
   ${t.description || "No description"}${paramList ? "\n  Parameters:\n" + paramList : ""}`;
       }).join("\n\n");
     }
+    let workflowsText = "";
+    if (workflows.length > 0) {
+      workflowsText = workflows.map((w, idx) => {
+        const propLines = Object.entries(w.propsSchema || {}).map(([k, v]) => `    - ${k}: ${v}`).join("\n");
+        return [
+          `${idx + 1}. **${w.name}** (tool: ${w.id})`,
+          `  ${w.description}`,
+          `  When to use: ${w.whenToUse}`,
+          propLines ? `  Props:
+${propLines}` : ""
+        ].filter(Boolean).join("\n");
+      }).join("\n\n");
+    } else {
+      workflowsText = "No workflow components registered for this project.";
+    }
     const prompts = await promptLoader.loadPrompts("agent-main", {
       SOURCE_SUMMARIES: summariesText,
       DIRECT_TOOLS: directToolsText,
+      WORKFLOW_COMPONENTS: workflowsText,
       MAX_ROWS: String(this.config.maxRowsPerSource),
       MAX_SOURCE_CALLS: String(maxSourceCalls),
       GLOBAL_KNOWLEDGE_BASE: this.config.globalKnowledgeBase || "No global knowledge base available.",
@@ -7747,6 +7794,70 @@ ${formatted}`;
     });
   }
   // ============================================
+  // Workflow Handling
+  // ============================================
+  /**
+   * Capture a workflow selection. We do NOT execute anything — the LLM has
+   * already extracted the props it wants the workflow rendered with. We
+   * record the selection (via the capture callback) and return a short
+   * acknowledgement so the LLM ends its turn cleanly without writing
+   * analysis text or calling more tools.
+   */
+  async handleWorkflow(workflow, toolInput, capture) {
+    const props = { ...workflow.defaultProps || {}, ...toolInput || {} };
+    logger.info(
+      `[MainAgent] Workflow selected: "${workflow.name}" | props: ${JSON.stringify(props).substring(0, 200)}`
+    );
+    if (this.streamBuffer.hasCallback()) {
+      this.streamBuffer.write(`
+
+\u{1F9ED} **Launching ${workflow.name} workflow...**
+
+`);
+      await streamDelay();
+    }
+    capture({ name: workflow.name, props });
+    return `\u2705 Workflow "${workflow.name}" selected. The UI will render now \u2014 do NOT write analysis text or call any other tools. End your turn.`;
+  }
+  /**
+   * Build LLM tool definitions for workflow components. The workflow's
+   * propsSchema becomes the tool's input_schema so the LLM extracts props
+   * directly from the prompt — same mechanic as direct tools.
+   */
+  buildWorkflowToolDefinitions(workflows) {
+    return workflows.map((workflow) => {
+      const properties = {};
+      const required = [];
+      Object.entries(workflow.propsSchema || {}).forEach(([key, typeOrValue]) => {
+        const valueStr = String(typeOrValue).toLowerCase();
+        let schemaType = "string";
+        const typeMatch = valueStr.match(/^(string|number|integer|boolean|array|object)\b/);
+        if (typeMatch) {
+          schemaType = typeMatch[1];
+        }
+        const isOptional = valueStr.includes("(optional)") || valueStr.includes("optional");
+        const description = typeof typeOrValue === "string" ? typeOrValue : `Prop: ${key}`;
+        if (schemaType === "array") {
+          properties[key] = { type: "array", items: {}, description };
+        } else if (schemaType === "object") {
+          properties[key] = { type: "object", description };
+        } else {
+          properties[key] = { type: schemaType, description };
+        }
+        if (!isOptional) required.push(key);
+      });
+      return {
+        name: workflow.id,
+        description: `[WORKFLOW] ${workflow.description} \u2014 When to use: ${workflow.whenToUse}`,
+        input_schema: {
+          type: "object",
+          properties,
+          required: required.length > 0 ? required : void 0
+        }
+      };
+    });
+  }
+  // ============================================
   // Format Result for Main Agent
   // ============================================
   /**
@@ -10398,7 +10509,7 @@ function getLLMInstance(provider) {
       return anthropicLLM;
   }
 }
-var get_agent_user_response = async (prompt, components, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, conversationHistory, streamCallback, collections, externalTools, userId, mainAgentModel, sourceAgentModel) => {
+var get_agent_user_response = async (prompt, components, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, conversationHistory, streamCallback, collections, externalTools, userId, mainAgentModel, sourceAgentModel, workflows) => {
   const startTime = Date.now();
   const providers = llmProviders || ["anthropic"];
   const provider = providers[0];
@@ -10500,13 +10611,35 @@ var get_agent_user_response = async (prompt, components, anthropicApiKey, groqAp
       knowledgeBaseContext
     };
     const streamBuffer = new StreamBuffer(streamCallback);
-    const mainAgent = new MainAgent(agentTools, agentConfig, streamBuffer);
+    const mainAgent = new MainAgent(agentTools, agentConfig, streamBuffer, workflows || []);
     const agentResponse = await mainAgent.handleQuestion(
       prompt,
       apiKey,
       conversationHistory,
       streamBuffer.hasCallback() ? (chunk) => streamBuffer.write(chunk) : void 0
     );
+    if (agentResponse.workflow) {
+      streamBuffer.flush();
+      const workflowComponent = {
+        id: `workflow_${Date.now()}`,
+        name: agentResponse.workflow.name,
+        type: `Workflow_${agentResponse.workflow.name}`,
+        description: `Workflow: ${agentResponse.workflow.name}`,
+        props: agentResponse.workflow.props
+      };
+      const elapsedTime2 = Date.now() - startTime;
+      logger.info(`[AgentFlow] Workflow short-circuit | "${agentResponse.workflow.name}" | ${elapsedTime2}ms`);
+      return {
+        success: true,
+        data: {
+          text: "",
+          component: workflowComponent,
+          actions: [],
+          method: `${provider}-agent-workflow`
+        },
+        errors: []
+      };
+    }
     const rawText = streamBuffer.getFullText() || agentResponse.text || "I apologize, but I was unable to generate a response.";
     const textResponse = rawText.replace(/_?_?SB_END_?_?/g, "").replace(/__SB_\w+_(?:START|MSG)_?_?/g, "").replace(/__QUERY_TIMER_START_[^_]*__/g, "").replace(/__QUERY_TIMER_DONE_[\d.]+__/g, "").replace(/__TEXT_COMPLETE__COMPONENT_GENERATION_START__/g, "").replace(/\[COMPLEXITY:\s*(?:simple|medium|complex)\]/gi, "");
     streamBuffer.flush();
@@ -10859,7 +10992,7 @@ var CONTEXT_CONFIG = {
 };
 
 // src/handlers/user-prompt-request.ts
-var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel) => {
+var get_user_request = async (data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows) => {
   const errors = [];
   const parseResult = UserPromptRequestMessageSchema.safeParse(data);
   if (!parseResult.success) {
@@ -10945,7 +11078,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     externalTools,
     userId,
     mainAgentModel,
-    sourceAgentModel
+    sourceAgentModel,
+    workflows
   );
   logger.info("User prompt request completed");
   const uiBlockId = existingUiBlockId;
@@ -11098,8 +11232,8 @@ var get_user_request = async (data, components, sendMessage, anthropicApiKey, gr
     wsId
   };
 };
-async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel) {
-  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel);
+async function handleUserPromptRequest(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows) {
+  const response = await get_user_request(data, components, sendMessage, anthropicApiKey, groqApiKey, geminiApiKey, openaiApiKey, llmProviders, collections, externalTools, mainAgentModel, sourceAgentModel, workflows);
   if (response.data?.component?.props?.config?.components) {
     response.data.component.props.config.components = response.data.component.props.config.components.map((comp) => ({
       ...comp,
@@ -11531,6 +11665,24 @@ async function handleComponentListResponse(data, storeComponents, collections) {
   }
 }
 
+// src/handlers/workflow-list-response.ts
+async function handleWorkflowListResponse(data, storeWorkflows) {
+  try {
+    const parsed = WorkflowListResponseMessageSchema.parse(data);
+    const { payload } = parsed;
+    const workflowsList = payload.workflows;
+    if (!workflowsList) {
+      logger.error("Workflows list not found in WORKFLOW_LIST_RES payload");
+      return;
+    }
+    const workflows = WorkflowsSchema.parse(workflowsList);
+    storeWorkflows(workflows);
+    logger.info(`Stored ${workflows.length} workflow descriptor(s) from frontend`);
+  } catch (error) {
+    logger.error("Failed to handle workflow list response:", error);
+  }
+}
+
 // src/handlers/users.ts
 async function handleUsersRequest(data, collections, sendMessage) {
   const executeCollection = async (collection, op, params) => {
@@ -16864,6 +17016,7 @@ var SuperatomSDK = class {
     this.collections = {};
     this.components = [];
     this.tools = [];
+    this.workflows = [];
     // Heartbeat properties for keeping WebSocket connection alive
     this.pingInterval = null;
     this.lastPong = Date.now();
@@ -17045,7 +17198,7 @@ var SuperatomSDK = class {
           });
           break;
         case "USER_PROMPT_REQ":
-          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.geminiApiKey, this.openaiApiKey, this.llmProviders, this.collections, this.tools, this.mainAgentModel, this.sourceAgentModel).catch((error) => {
+          handleUserPromptRequest(parsed, this.components, (msg) => this.send(msg), this.anthropicApiKey, this.groqApiKey, this.geminiApiKey, this.openaiApiKey, this.llmProviders, this.collections, this.tools, this.mainAgentModel, this.sourceAgentModel, this.workflows).catch((error) => {
             logger.error("Failed to handle user prompt request:", error);
           });
           break;
@@ -17064,6 +17217,11 @@ var SuperatomSDK = class {
             logger.error("Failed to handle component list request:", error);
           });
           break;
+        case "WORKFLOW_LIST_RES":
+          handleWorkflowListResponse(parsed, (wf) => this.setWorkflows(wf)).catch((error) => {
+            logger.error("Failed to handle workflow list request:", error);
+          });
+          break;
         case "USERS":
           handleUsersRequest(parsed, this.collections, (msg) => this.send(msg)).catch((error) => {
             logger.error("Failed to handle users request:", error);
@@ -17303,6 +17461,24 @@ var SuperatomSDK = class {
   getTools() {
     return this.tools;
   }
+  /**
+   * Register workflow components for the SDK instance.
+   *
+   * Workflows are pre-built multi-step UI flows the main agent can pick when
+   * the user's prompt matches a workflow's `whenToUse` trigger. Picking a
+   * workflow short-circuits analysis text + dashboard component generation —
+   * the workflow component is returned directly, with the LLM-extracted props.
+   */
+  setWorkflows(workflows) {
+    this.workflows = workflows;
+    logger.info(`Workflows stored in SDK: ${workflows.length} workflow(s)`);
+  }
+  /**
+   * Get the registered workflow components.
+   */
+  getWorkflows() {
+    return this.workflows;
+  }
   /**
    * Apply model strategy to all LLM provider singletons
    * @param strategy - 'best', 'fast', or 'balanced'