@superatomai/sdk-node 0.0.11-mds → 0.0.12-mds

package/dist/index.d.mts

@@ -741,6 +741,10 @@ declare const ToolSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     description: z.ZodString;
+    /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
+    toolType: z.ZodOptional<z.ZodEnum<["source", "direct"]>>;
+    /** Full untruncated schema for source agent (all columns visible) */
+    fullSchema: z.ZodOptional<z.ZodString>;
     params: z.ZodRecord<z.ZodString, z.ZodString>;
     fn: z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodAny>;
     outputSchema: z.ZodOptional<z.ZodObject<{
@@ -779,6 +783,8 @@ declare const ToolSchema: z.ZodObject<{
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
     outputSchema?: {
         description: string;
         fields: {
@@ -793,6 +799,8 @@ declare const ToolSchema: z.ZodObject<{
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
     outputSchema?: {
         description: string;
         fields: {

package/dist/index.d.ts

@@ -741,6 +741,10 @@ declare const ToolSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     description: z.ZodString;
+    /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
+    toolType: z.ZodOptional<z.ZodEnum<["source", "direct"]>>;
+    /** Full untruncated schema for source agent (all columns visible) */
+    fullSchema: z.ZodOptional<z.ZodString>;
     params: z.ZodRecord<z.ZodString, z.ZodString>;
     fn: z.ZodFunction<z.ZodTuple<[z.ZodAny], z.ZodUnknown>, z.ZodAny>;
     outputSchema: z.ZodOptional<z.ZodObject<{
@@ -779,6 +783,8 @@ declare const ToolSchema: z.ZodObject<{
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
     outputSchema?: {
         description: string;
         fields: {
@@ -793,6 +799,8 @@ declare const ToolSchema: z.ZodObject<{
     name: string;
     description: string;
     fn: (args_0: any, ...args: unknown[]) => any;
+    toolType?: "source" | "direct" | undefined;
+    fullSchema?: string | undefined;
     outputSchema?: {
         description: string;
         fields: {

package/dist/index.js

@@ -393,6 +393,10 @@ var ToolSchema = import_zod3.z.object({
   id: import_zod3.z.string(),
   name: import_zod3.z.string(),
   description: import_zod3.z.string(),
+  /** Tool type: "source" = routed through SourceAgent, "direct" = called directly by MainAgent */
+  toolType: import_zod3.z.enum(["source", "direct"]).optional(),
+  /** Full untruncated schema for source agent (all columns visible) */
+  fullSchema: import_zod3.z.string().optional(),
   params: import_zod3.z.record(import_zod3.z.string()),
   fn: import_zod3.z.function().args(import_zod3.z.any()).returns(import_zod3.z.any()),
   outputSchema: OutputSchema.optional()
@@ -7178,28 +7182,35 @@ var MainAgent = class {
    * Handle a user question using the multi-agent system.
    *
    * This is ONE LLM.streamWithTools() call. The LLM:
-   * 1. Sees source summaries in system prompt (~100 tokens each)
-   * 2. Decides which source(s) to query (routing)
-   * 3. Calls source tools → SourceAgent runs independently → returns data
-   * 4. Sees data, decides if it needs more → calls tools again if needed
+   * 1. Sees source summaries + direct tool descriptions in system prompt
+   * 2. Decides which tool(s) to call (routing)
+   * 3. Source tools → SourceAgent runs independently → returns data
+   * 4. Direct tools → fn() called directly with LLM params → returns data
    * 5. Generates final analysis text
    */
   async handleQuestion(userPrompt, apiKey, conversationHistory, streamCallback) {
     const startTime = Date.now();
     logger.info(`[MainAgent] Starting | prompt: "${userPrompt.substring(0, 50)}..."`);
-    const summaries = buildSourceSummaries(this.externalTools);
-    logger.info(`[MainAgent] ${summaries.length} source(s) available`);
-    const systemPrompt = await this.buildSystemPrompt(summaries, conversationHistory);
+    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)`);
+    const summaries = buildSourceSummaries(sourceTools);
+    const systemPrompt = await this.buildSystemPrompt(summaries, directTools, conversationHistory);
     logger.logLLMPrompt("mainAgent", "system", extractPromptText(systemPrompt));
     logger.logLLMPrompt("mainAgent", "user", userPrompt);
-    const tools = this.buildSourceToolDefinitions(summaries);
+    const sourceToolDefs = this.buildSourceToolDefinitions(summaries);
+    const directToolDefs = this.buildDirectToolDefinitions(directTools);
+    const tools = [...sourceToolDefs, ...directToolDefs];
     const sourceResults = [];
     const executedTools = [];
     const toolHandler = async (toolName, toolInput) => {
       const externalTool = this.externalTools.find((t) => t.id === toolName);
       if (!externalTool) {
         logger.error(`[MainAgent] Unknown tool called: ${toolName}`);
-        return `Error: Unknown data source "${toolName}"`;
+        return `Error: Unknown tool "${toolName}"`;
+      }
+      if (externalTool.toolType === "direct") {
+        return this.handleDirectTool(externalTool, toolInput, executedTools);
       }
       const sourceInput = {
         intent: toolInput.intent || toolInput.query || JSON.stringify(toolInput),
@@ -7239,17 +7250,93 @@ var MainAgent = class {
     };
   }
   // ============================================
+  // Direct Tool Execution
+  // ============================================
+  /**
+   * Execute a direct tool — call fn() with LLM-provided params, no SourceAgent.
+   */
+  async handleDirectTool(tool, toolInput, executedTools) {
+    const startTime = Date.now();
+    logger.info(`[MainAgent] Executing direct tool "${tool.name}" | params: ${JSON.stringify(toolInput).substring(0, 200)}`);
+    if (this.streamBuffer.hasCallback()) {
+      this.streamBuffer.write(`
+
+\u{1F527} **Running ${tool.name}...**
+
+`);
+      await streamDelay();
+    }
+    try {
+      const result = await tool.fn(toolInput);
+      const executionTimeMs = Date.now() - startTime;
+      if (result && result.error) {
+        const errorMsg = typeof result.error === "string" ? result.error : JSON.stringify(result.error);
+        logger.warn(`[MainAgent] Direct tool "${tool.name}" returned error: ${errorMsg}`);
+        return `\u274C Tool "${tool.name}" error: ${errorMsg}`;
+      }
+      const resultData = result.data || result;
+      const rowCount = Array.isArray(resultData) ? resultData.length : 1;
+      if (this.streamBuffer.hasCallback()) {
+        this.streamBuffer.write(`\u2705 **${tool.name}** completed (${rowCount} results, ${executionTimeMs}ms)
+
+`);
+      }
+      const formattedResult = formatToolResultForLLM(result, {
+        toolName: tool.name,
+        maxRows: 5,
+        maxCharsPerField: 200
+      });
+      executedTools.push({
+        id: tool.id,
+        name: tool.name,
+        params: toolInput,
+        result: {
+          _totalRecords: result.totalItems || result.count || rowCount,
+          _recordsShown: rowCount,
+          _metadata: result.metadata,
+          _sampleData: Array.isArray(resultData) ? resultData.slice(0, 3) : [resultData]
+        },
+        outputSchema: tool.outputSchema
+      });
+      const formatted = typeof formattedResult === "string" ? formattedResult : JSON.stringify(formattedResult);
+      return `\u2705 Tool "${tool.name}" executed successfully. ${rowCount} results returned.
+
+${formatted}`;
+    } catch (error) {
+      const executionTimeMs = Date.now() - startTime;
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      logger.error(`[MainAgent] Direct tool "${tool.name}" failed in ${executionTimeMs}ms: ${errorMsg}`);
+      if (this.streamBuffer.hasCallback()) {
+        this.streamBuffer.write(`
+
+\u274C **${tool.name} failed:** ${errorMsg}
+
+`);
+      }
+      return `\u274C Tool "${tool.name}" failed: ${errorMsg}`;
+    }
+  }
+  // ============================================
   // System Prompt
   // ============================================
   /**
-   * Build the main agent's system prompt with source summaries.
-   * Loads from prompt loader (file system → hardcoded fallback in prompts.ts).
+   * Build the main agent's system prompt with source summaries and direct tool descriptions.
    */
-  async buildSystemPrompt(summaries, conversationHistory) {
+  async buildSystemPrompt(summaries, directTools, conversationHistory) {
     const summariesText = formatSummariesForPrompt(summaries);
     const maxSourceCalls = Math.max(2, this.config.maxIterations - 2);
+    let directToolsText = "";
+    if (directTools.length > 0) {
+      directToolsText = directTools.map((t, idx) => {
+        const params = t.params || {};
+        const paramList = Object.entries(params).map(([k, v]) => `    - ${k}: ${v}`).join("\n");
+        return `${idx + 1}. **${t.name}** (tool: ${t.id})
+  ${t.description || "No description"}${paramList ? "\n  Parameters:\n" + paramList : ""}`;
+      }).join("\n\n");
+    }
     const prompts = await promptLoader.loadPrompts("agent-main", {
       SOURCE_SUMMARIES: summariesText,
+      DIRECT_TOOLS: directToolsText,
       MAX_ROWS: String(this.config.maxRowsPerSource),
       MAX_SOURCE_CALLS: String(maxSourceCalls),
       GLOBAL_KNOWLEDGE_BASE: this.config.globalKnowledgeBase || "No global knowledge base available.",
@@ -7260,11 +7347,10 @@ var MainAgent = class {
     return prompts.system;
   }
   // ============================================
-  // Tool Definitions (summary-only, no full schema)
+  // Tool Definitions
   // ============================================
   /**
-   * Build tool definitions for the main agent — one per source.
-   * Descriptions include entity names with column names for routing.
+   * Build tool definitions for source tools — summary-only descriptions.
    * The full schema is inside the SourceAgent which runs independently.
    */
   buildSourceToolDefinitions(summaries) {
@@ -7296,14 +7382,51 @@ var MainAgent = class {
       };
     });
   }
+  /**
+   * Build tool definitions for direct tools — expose their actual params.
+   * These are called directly by the main agent LLM, no SourceAgent.
+   */
+  buildDirectToolDefinitions(directTools) {
+    return directTools.map((tool) => {
+      const properties = {};
+      const required = [];
+      const toolParams = tool.params || {};
+      Object.entries(toolParams).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 : `Parameter: ${key}`;
+        if (schemaType === "array") {
+          properties[key] = { type: "array", items: { type: "string" }, description };
+        } else if (schemaType === "object") {
+          properties[key] = { type: "object", description };
+        } else {
+          properties[key] = { type: schemaType, description };
+        }
+        if (!isOptional) {
+          required.push(key);
+        }
+      });
+      return {
+        name: tool.id,
+        description: tool.description || `Call ${tool.name}`,
+        input_schema: {
+          type: "object",
+          properties,
+          required: required.length > 0 ? required : void 0
+        }
+      };
+    });
+  }
   // ============================================
   // Format Result for Main Agent
   // ============================================
   /**
    * Format a source agent's result as a clean string for the main agent LLM.
-   * Passes through the data as-is — no server-side aggregation.
-   * If the main agent needs aggregates, it should request aggregation: "pre-aggregate"
-   * from the source agent, which handles it at the query level (SQL GROUP BY, etc.).
    */
   formatResultForMainAgent(result) {
     if (!result.success) {
@@ -9969,6 +10092,7 @@ var get_agent_user_response = async (prompt, components, anthropicApiKey, groqAp
       id: t.id,
       name: t.name,
       description: t.description,
+      toolType: t.toolType,
       fullSchema: t.fullSchema,
       fn: t.fn,
       limit: t.limit,