@hailer/mcp 1.2.0 → 2.0.0-beta.1

package/dist/mcp/tools/insight.js

@@ -7,10 +7,14 @@
  * - Activities = Rows
  * - Fields = Columns
  *
- * All 4 insight management tools in one file for cohesion.
+ * All 4 insight tools in one file for cohesion (v2 surface):
+ * - run_insight   (saved execution + ad-hoc preview)
+ * - save_insight  (create + update upsert)
+ * - list_insights
+ * - remove_insight
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.insightTools = exports.listInsightsTool = exports.removeInsightTool = exports.updateInsightTool = exports.getInsightDataTool = exports.previewInsightTool = exports.createInsightTool = void 0;
+exports.insightTools = exports.listInsightsTool = exports.removeInsightTool = exports.saveInsightTool = exports.runInsightTool = void 0;
 const zod_1 = require("zod");
 const tool_registry_1 = require("../tool-registry");
 const logger_1 = require("../../lib/logger");
@@ -25,10 +29,10 @@ const logger = (0, logger_1.createLogger)({ component: 'insight-tools' });
  * Accepts both 'id' and 'fieldId' for flexibility (LLMs often use 'id')
  */
 const fieldSchema = zod_1.z.object({
-    name: zod_1.z.string().describe("Column name in SQL query"),
+    name: zod_1.z.string().describe('Column name in SQL query'),
     // Accept both 'id' and 'fieldId' - will be normalized to 'fieldId'
-    id: zod_1.z.string().optional().describe("Field ID (alias for fieldId)"),
-    fieldId: zod_1.z.string().optional().describe("Custom field ID from workflow"),
+    id: zod_1.z.string().optional().describe('Field ID (alias for fieldId)'),
+    fieldId: zod_1.z.string().optional().describe('Custom field ID from workflow'),
     meta: zod_1.z.enum([
         '_id',
         'uid',
@@ -43,7 +47,7 @@ const fieldSchema = zod_1.z.object({
         'workflowId',
         'workflowName',
         'priority'
-    ]).optional().describe("Built-in activity property (alternative to fieldId)"),
+    ]).optional().describe('Built-in activity property (alternative to fieldId)'),
 }).refine((data) => data.meta || data.fieldId || data.id, { message: "Field must have either 'meta', 'fieldId', or 'id'" });
 /**
  * Sanitize field name to be SQL-identifier safe (no spaces, special chars)
@@ -53,8 +57,9 @@ function sanitizeFieldName(name) {
     return name
         .split(/\s+/)
         .map((word, index) => {
-        if (index === 0)
+        if (index === 0) {
             return word.charAt(0).toLowerCase() + word.slice(1);
+        }
         return word.charAt(0).toUpperCase() + word.slice(1);
     })
         .join('')
@@ -67,7 +72,7 @@ function normalizeFields(sources) {
     return sources.map(source => ({
         ...source,
         fields: source.fields.map(field => {
-            let normalized = { ...field };
+            const normalized = { ...field };
             // Sanitize field name (remove spaces, make SQL-safe)
             if (normalized.name) {
                 normalized.name = sanitizeFieldName(normalized.name);
@@ -85,17 +90,14 @@ function normalizeFields(sources) {
  * Source definition schema - workflow as SQL table
  */
 const sourceSchema = zod_1.z.object({
-    name: zod_1.z.string().describe("Table alias for SQL query"),
-    workflowId: zod_1.z.string().describe("Workflow ID to query"),
-    fields: zod_1.z.array(fieldSchema).min(1).describe("Field mappings for SQL columns"),
+    name: zod_1.z.string().describe('Table alias for SQL query'),
+    workflowId: zod_1.z.string().describe('Workflow ID to query'),
+    fields: zod_1.z.array(fieldSchema).min(1).describe('Field mappings for SQL columns'),
 });
-// ============================================================================
-// CREATE INSIGHT TOOL
-// ============================================================================
 const INSIGHT_SQL_GUIDE = `**How sources map to SQL:**
 - sources[].name → TABLE NAME in SQL
 - sources[].fields[].name → COLUMN NAME in SQL
-- sources[].fields[].fieldId → custom field ID (hex string from get_workflow_schema)
+- sources[].fields[].fieldId → custom field ID (hex string from describe_workflows include:["schema"])
 - sources[].fields[].meta → built-in property (use INSTEAD of fieldId): phaseName, name, created, updated, uid, team, priority
 
 **Example — count by phase:**
@@ -103,528 +105,468 @@ sources: [{ name: "T", workflowId: "...", fields: [{ name: "phase", meta: "phase
 query: "SELECT phase, COUNT(*) as count FROM T GROUP BY phase"
 
 **NEVER use fieldId or workflowId in the SQL — only field name values.**`;
-const createInsightDescription = `Create SQL insight over workflow data.
+/**
+ * Format a headers/rows result set as a markdown table (first 10 rows)
+ */
+function formatResultTable(headers, rows) {
+    if (!headers || !rows) {
+        return '⚠️ No data returned\n';
+    }
+    if (rows.length === 0) {
+        return `**Columns:** ${headers.join(', ')}\n\n⚠️ **No rows matched** - Check your query filters\n`;
+    }
+    let text = `**Columns:** ${headers.join(', ')}\n\n`;
+    text += '**Sample Data (first 10 rows):**\n```\n';
+    text += headers.join(' | ') + '\n';
+    text += headers.map(() => '---').join(' | ') + '\n';
+    const rowsToShow = Math.min(rows.length, 10);
+    for (let idx = 0; idx < rowsToShow; idx++) {
+        text += rows[idx].map(val => String(val || '')).join(' | ') + '\n';
+    }
+    if (rows.length > 10) {
+        text += `\n... and ${rows.length - 10} more rows\n`;
+    }
+    text += '```\n';
+    return text;
+}
+// ============================================================================
+// RUN INSIGHT TOOL (saved execution + ad-hoc preview)
+// ============================================================================
+const runInsightDescription = `Execute an insight query and return rows. Two modes (mutually exclusive):
+- Saved: pass insightId to run a stored insight. refresh: true recalculates instead of returning cached results.
+- Ad-hoc: pass sources + query to test SQL without saving. One call replaces multiple list_activities calls. Always run ad-hoc before save_insight.
 
 ${INSIGHT_SQL_GUIDE}`;
-exports.createInsightTool = {
-    name: 'create_insight',
+/** Saved-insight path: v3.insight.data */
+async function runSavedInsight(insightId, refresh, context) {
+    try {
+        logger.debug('Calling v3.insight.data', { insightId, refresh });
+        // Call v3.insight.data endpoint ('update' is the API name for refresh)
+        const result = await context.hailer.request('v3.insight.data', [insightId, { update: refresh }]);
+        logger.debug('Insight data retrieved', {
+            headers: result.headers?.length,
+            rows: result.rows?.length,
+            fullResult: JSON.stringify(result).substring(0, 500)
+        });
+        let responseText = `✅ **Insight Data Retrieved** (${result.rows?.length || 0} rows)\n\n`;
+        responseText += formatResultTable(result.headers, result.rows);
+        if (!result.headers || !result.rows) {
+            responseText += `**Debug:** Response keys: ${Object.keys(result).join(', ')}\n`;
+            responseText += `**Full response (truncated):** \`${JSON.stringify(result).substring(0, 300)}\`\n`;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: responseText,
+                }],
+        };
+    }
+    catch (error) {
+        if (!request_logger_1.RequestLogger.getCurrent()) {
+            logger.error('Error getting insight data', error);
+        }
+        const errorMessage = (0, tool_helpers_1.extractErrorMessage)(error);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ **Error getting insight data**\n\n**Error:** ${errorMessage}\n\n**Common Issues:**\n- Insight ID not found\n- Permission denied\n- Insight query has errors\n- Use \`list_insights\` to verify insight ID`,
+                }],
+        };
+    }
+}
+/** Ad-hoc path: v3.insight.preview */
+async function runAdHocInsight(sources, query, context) {
+    try {
+        // Resolve workspace ID (returns undefined if cache unavailable)
+        const workspaceId = (0, tool_helpers_1.getResolvedWorkspaceId)({}, context);
+        if (!workspaceId) {
+            return (0, tool_helpers_1.missingWorkspaceCacheResponse)();
+        }
+        logger.debug('Calling v3.insight.preview', {
+            workspaceId,
+            sourcesCount: sources.length,
+        });
+        // Normalize sources (convert 'id' to 'fieldId' if needed)
+        const normalizedSources = normalizeFields(sources);
+        const previewData = {
+            sources: normalizedSources,
+            query,
+        };
+        // Call v3.insight.preview endpoint
+        const result = await context.hailer.request('v3.insight.preview', [workspaceId, previewData]);
+        logger.debug('Preview successful', {
+            headers: result.headers?.length,
+            rows: result.rows?.length
+        });
+        let responseText = `✅ **Preview Results** (~${result.rows?.length || 0} rows)\n\n`;
+        responseText += formatResultTable(result.headers, result.rows);
+        responseText += '\n✅ **Query is valid!** Ready to save with `save_insight`.';
+        return {
+            content: [{
+                    type: 'text',
+                    text: responseText,
+                }],
+        };
+    }
+    catch (error) {
+        if (!request_logger_1.RequestLogger.getCurrent()) {
+            logger.error('Error previewing insight', error);
+        }
+        const errorMessage = (0, tool_helpers_1.extractErrorMessage)(error);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ **Preview Failed**\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Check SQL syntax\n- Verify field names match source definitions\n- Ensure workflow IDs are correct\n- Check table aliases match source names`,
+                }],
+        };
+    }
+}
+exports.runInsightTool = {
+    name: 'run_insight',
     group: tool_registry_1.ToolGroup.PLAYGROUND,
-    description: createInsightDescription,
+    description: runInsightDescription,
     schema: zod_1.z.object({
-        workspaceId: zod_1.z
+        insightId: zod_1.z
             .string()
             .optional()
-            .describe("Optional workspace ID or name - defaults to current workspace"),
-        name: zod_1.z
-            .string()
-            .min(1)
-            .describe("Insight name"),
-        public: zod_1.z
+            .describe('Saved insight ID to execute. Mutually exclusive with sources/query.'),
+        refresh: zod_1.z
             .boolean()
             .optional()
-            .default(false)
-            .describe("Whether insight is publicly accessible (default: false)"),
+            .describe('Saved mode only: recalculate data (true) instead of using cached results (false, default)'),
         sources: zod_1.z
             .array(sourceSchema)
             .min(1)
-            .describe("Workflow sources. source.name = SQL table name, field.name = SQL column name. Never use IDs in the query."),
+            .optional()
+            .describe('Ad-hoc mode: workflow sources. source.name = SQL table name, field.name = SQL column name.'),
         query: zod_1.z
             .string()
             .min(1)
-            .describe("SQL query (SELECT, JOIN, WHERE, GROUP BY, ORDER BY, etc.)"),
+            .optional()
+            .describe('Ad-hoc mode: SQL query to test'),
     }),
     async execute(args, context) {
-        logger.debug('Creating insight', {
-            name: args.name,
-            workspaceId: args.workspaceId,
-            sourcesCount: args.sources.length,
+        logger.debug('Running insight', {
+            insightId: args.insightId,
+            refresh: args.refresh,
+            sourcesCount: args.sources?.length,
+            hasQuery: !!args.query,
             apiKey: context.apiKey.substring(0, 8) + '...'
         });
-        try {
-            // Resolve workspace ID (returns undefined if cache unavailable)
-            const workspaceId = (0, tool_helpers_1.getResolvedWorkspaceId)(args, context);
-            if (!workspaceId) {
-                return (0, tool_helpers_1.missingWorkspaceCacheResponse)();
-            }
-            logger.debug('Calling v3.insight.create', {
-                workspaceId,
-                name: args.name,
-                sourcesCount: args.sources.length
-            });
-            // Normalize sources (convert 'id' to 'fieldId' if needed)
-            const normalizedSources = normalizeFields(args.sources);
-            // Build insight payload
-            const insightData = {
-                name: args.name,
-                public: args.public || false,
-                sources: normalizedSources,
-                query: args.query,
+        const hasAdHocArgs = !!args.sources || !!args.query;
+        if (args.insightId && hasAdHocArgs) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: '❌ **Conflicting modes**\n\nPass EITHER `insightId` (run a saved insight) OR `sources` + `query` (ad-hoc test) — not both.',
+                    }],
             };
-            // Call v3.insight.create endpoint
-            const result = await context.hailer.request('v3.insight.create', [workspaceId, insightData]);
-            logger.debug('Insight creation successful', {
-                insightId: result.insightId || result._id,
-                result: JSON.stringify(result)
-            });
-            const insightId = result.insightId || result._id;
-            const discussionId = result.discussionId || result.discussion;
-            // Automatically join the insight's discussion
-            if (discussionId) {
-                try {
-                    logger.debug('Automatically joining insight discussion', { discussionId });
-                    await context.hailer.joinDiscussion(discussionId);
-                    logger.debug('Successfully joined insight discussion', { discussionId });
-                }
-                catch (joinError) {
-                    logger.warn('Failed to join insight discussion (non-fatal)', {
-                        discussionId,
-                        error: joinError instanceof Error ? joinError.message : String(joinError)
-                    });
-                }
-            }
-            else {
-                logger.debug('No discussion ID in response, skipping auto-join');
-            }
-            // Build success response
-            let responseText = `✅ **Insight Created Successfully**\n\n`;
-            responseText += `**Insight Name:** ${args.name}\n`;
-            responseText += `**Insight ID:** \`${insightId}\`\n`;
-            responseText += `**Workspace:** ${workspaceId}\n`;
-            responseText += `**Public:** ${args.public ? 'Yes' : 'No'}\n`;
-            responseText += `**Sources:** ${args.sources.length} workflow(s)\n`;
-            if (discussionId) {
-                responseText += `**Discussion:** Automatically joined ✓\n`;
-            }
-            responseText += `\n`;
-            // Show sources
-            responseText += `**Query Sources:**\n`;
-            args.sources.forEach((source) => {
-                responseText += `- \`${source.name}\` → Workflow: \`${source.workflowId}\` (${source.fields.length} fields)\n`;
-            });
-            responseText += `\n**SQL Query:**\n\`\`\`sql\n${args.query}\n\`\`\`\n\n`;
-            responseText += `💡 **Next Steps:**\n`;
-            responseText += `- Use \`get_insight_data\` to execute the query and see results\n`;
-            responseText += `- Use \`list_insights\` to see all insights in workspace\n`;
-            responseText += `- Use \`update_insight\` to modify the insight\n`;
-            responseText += `- Use \`preview_insight\` to test query changes before saving\n\n`;
-            if (args.public) {
-                responseText += `🌐 **Public Insight:** This insight can be accessed without authentication.\n`;
-            }
+        }
+        if (args.insightId) {
+            return runSavedInsight(args.insightId, args.refresh ?? false, context);
+        }
+        if (!hasAdHocArgs) {
             return {
                 content: [{
-                        type: "text",
-                        text: responseText,
+                        type: 'text',
+                        text: '❌ **Missing parameters**\n\nPass `insightId` to run a saved insight, or `sources` + `query` to test an ad-hoc SQL query.\n\nUse `list_insights` to find saved insight IDs.',
                     }],
             };
         }
-        catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Error creating insight", error);
-            let errorMessage = 'Unknown error occurred';
-            let errorDetails = '';
-            if (error instanceof Error) {
-                errorMessage = error.message;
-                if (error.stack) {
-                    errorDetails = `\n\n**Stack trace:**\n\`\`\`\n${error.stack}\n\`\`\``;
-                }
-            }
-            else if (typeof error === 'object' && error !== null) {
-                try {
-                    errorMessage = JSON.stringify(error, null, 2);
-                }
-                catch {
-                    errorMessage = String(error);
-                }
-            }
-            else {
-                errorMessage = String(error);
-            }
-            // Handle SQL syntax errors
-            if (errorMessage.toLowerCase().includes('sql') || errorMessage.toLowerCase().includes('syntax')) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `❌ **SQL Query Error**\n\nThere's a problem with your SQL query.\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Check column names match field names in sources\n- Check table names match source names\n- Use \`preview_insight\` to test queries before creating\n- Make sure field IDs are correct (use \`get_workflow_schema\`)`,
-                        }],
-                };
-            }
-            // Handle permission errors
-            if (errorMessage.includes('permission') || errorMessage.includes('PermissionDenied')) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `❌ **Permission Denied**\n\nYou may not have permission to create insights or access the specified workflows.\n\n**Error:** ${errorMessage}`,
-                        }],
-                };
-            }
+        if (!args.sources || !args.query) {
             return {
                 content: [{
-                        type: "text",
-                        text: `❌ **Error creating insight**\n\n**Error:** ${errorMessage}${errorDetails}\n\n**Common Issues:**\n- SQL query syntax errors\n- Invalid field IDs or workflow IDs\n- Workflow fields don't exist\n- Permission issues\n- Check field IDs with \`get_workflow_schema\`\n- Test query with \`preview_insight\` first`,
+                        type: 'text',
+                        text: '❌ **Incomplete ad-hoc query**\n\nAd-hoc mode requires BOTH `sources` and `query`.',
                     }],
             };
         }
+        return runAdHocInsight(args.sources, args.query, context);
     }
 };
 // ============================================================================
-// PREVIEW INSIGHT TOOL
+// SAVE INSIGHT TOOL (create + update upsert)
 // ============================================================================
-const previewInsightDescription = `Test SQL query before creating insight. One call replaces multiple list_activities calls. Always preview before create_insight.
+const saveInsightDescription = `Create or update a SQL insight over workflow data (upsert).
+- Create: omit insightId — name, sources, and query are required.
+- Update: pass insightId — only the provided fields (name, public, sources, query) are changed.
 
 ${INSIGHT_SQL_GUIDE}`;
-exports.previewInsightTool = {
-    name: 'preview_insight',
-    group: tool_registry_1.ToolGroup.PLAYGROUND,
-    description: previewInsightDescription,
-    schema: zod_1.z.object({
-        workspaceId: zod_1.z
-            .string()
-            .optional()
-            .describe("Optional workspace ID or name - defaults to current workspace"),
-        sources: zod_1.z
-            .array(sourceSchema)
-            .min(1)
-            .describe("Workflow sources. Use source.name as table, field.name as column in SQL."),
-        query: zod_1.z
-            .string()
-            .min(1)
-            .describe("SQL query to test"),
-        insightId: zod_1.z
-            .string()
-            .optional()
-            .describe("Optional insight ID if previewing changes to existing insight"),
-    }),
-    async execute(args, context) {
-        logger.debug('Previewing insight', {
-            workspaceId: args.workspaceId,
-            sourcesCount: args.sources.length,
-            insightId: args.insightId,
-            apiKey: context.apiKey.substring(0, 8) + '...'
+/** Create path: v3.insight.create (auto-joins the insight's discussion) */
+async function createNewInsight(args, context) {
+    const { name, sources, query } = args;
+    if (!name || !sources || !query) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: '❌ **Missing required fields**\n\nCreating a new insight (no `insightId`) requires `name`, `sources`, and `query`.\n\nTo update an existing insight instead, pass its `insightId`.',
+                }],
+        };
+    }
+    try {
+        // Resolve workspace ID (returns undefined if cache unavailable)
+        const workspaceId = (0, tool_helpers_1.getResolvedWorkspaceId)(args, context);
+        if (!workspaceId) {
+            return (0, tool_helpers_1.missingWorkspaceCacheResponse)();
+        }
+        logger.debug('Calling v3.insight.create', {
+            workspaceId,
+            name,
+            sourcesCount: sources.length
         });
-        try {
-            // Resolve workspace ID (returns undefined if cache unavailable)
-            const workspaceId = (0, tool_helpers_1.getResolvedWorkspaceId)(args, context);
-            if (!workspaceId) {
-                return (0, tool_helpers_1.missingWorkspaceCacheResponse)();
-            }
-            logger.debug('Calling v3.insight.preview', {
-                workspaceId,
-                sourcesCount: args.sources.length,
-                insightId: args.insightId
-            });
-            // Normalize sources (convert 'id' to 'fieldId' if needed)
-            const normalizedSources = normalizeFields(args.sources);
-            // Build preview payload (insightId not accepted by v3.insight.preview)
-            const previewData = {
-                sources: normalizedSources,
-                query: args.query,
-            };
-            // Call v3.insight.preview endpoint
-            const result = await context.hailer.request('v3.insight.preview', [workspaceId, previewData]);
-            logger.debug('Preview successful', {
-                headers: result.headers?.length,
-                rows: result.rows?.length
-            });
-            // Format results
-            let responseText = `✅ **Preview Results** (~${result.rows?.length || 0} rows)\n\n`;
-            if (!result.headers || !result.rows) {
-                responseText += `⚠️ No data returned from preview\n`;
-            }
-            else if (result.rows.length === 0) {
-                responseText += `**Columns:** ${result.headers.join(', ')}\n\n`;
-                responseText += `⚠️ **No rows matched** - Check your query filters\n`;
-            }
-            else {
-                responseText += `**Columns:** ${result.headers.join(', ')}\n\n`;
-                responseText += `**Sample Data:**\n\`\`\`\n`;
-                // Show column headers
-                responseText += result.headers.join(' | ') + '\n';
-                responseText += result.headers.map(() => '---').join(' | ') + '\n';
-                // Show first 10 rows
-                const rowsToShow = Math.min(result.rows.length, 10);
-                for (let i = 0; i < rowsToShow; i++) {
-                    responseText += result.rows[i].map(v => String(v || '')).join(' | ') + '\n';
-                }
-                if (result.rows.length > 10) {
-                    responseText += `\n... and ${result.rows.length - 10} more rows\n`;
-                }
-                responseText += `\`\`\`\n\n`;
+        // Normalize sources (convert 'id' to 'fieldId' if needed)
+        const normalizedSources = normalizeFields(sources);
+        // Build insight payload
+        const insightData = {
+            name,
+            public: args.public || false,
+            sources: normalizedSources,
+            query,
+        };
+        // Call v3.insight.create endpoint
+        const result = await context.hailer.request('v3.insight.create', [workspaceId, insightData]);
+        logger.debug('Insight creation successful', {
+            insightId: result.insightId || result._id,
+            result: JSON.stringify(result)
+        });
+        const insightId = result.insightId || result._id;
+        const discussionId = result.discussionId || result.discussion;
+        // Automatically join the insight's discussion
+        if (discussionId) {
+            try {
+                logger.debug('Automatically joining insight discussion', { discussionId });
+                await context.hailer.joinDiscussion(discussionId);
+                logger.debug('Successfully joined insight discussion', { discussionId });
+            }
+            catch (joinError) {
+                logger.warn('Failed to join insight discussion (non-fatal)', {
+                    discussionId,
+                    error: joinError instanceof Error ? joinError.message : String(joinError)
+                });
             }
-            responseText += `\n✅ **Query is valid!** Ready to use in \`create_insight\` or \`update_insight\`.`;
+        }
+        if (!discussionId) {
+            logger.debug('No discussion ID in response, skipping auto-join');
+        }
+        // Build success response
+        let responseText = '✅ **Insight Created Successfully**\n\n';
+        responseText += `**Insight Name:** ${name}\n`;
+        responseText += `**Insight ID:** \`${insightId}\`\n`;
+        responseText += `**Workspace:** ${workspaceId}\n`;
+        responseText += `**Public:** ${args.public ? 'Yes' : 'No'}\n`;
+        responseText += `**Sources:** ${sources.length} workflow(s)\n`;
+        if (discussionId) {
+            responseText += '**Discussion:** Automatically joined ✓\n';
+        }
+        responseText += '\n';
+        // Show sources
+        responseText += '**Query Sources:**\n';
+        sources.forEach((source) => {
+            responseText += `- \`${source.name}\` → Workflow: \`${source.workflowId}\` (${source.fields.length} fields)\n`;
+        });
+        responseText += `\n**SQL Query:**\n\`\`\`sql\n${query}\n\`\`\`\n\n`;
+        responseText += '💡 **Next Steps:**\n';
+        responseText += '- Use `run_insight` with this insightId to execute the query and see results\n';
+        responseText += '- Use `list_insights` to see all insights in workspace\n';
+        responseText += '- Use `save_insight` with this insightId to modify the insight\n\n';
+        if (args.public) {
+            responseText += '🌐 **Public Insight:** This insight can be accessed without authentication.\n';
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: responseText,
+                }],
+        };
+    }
+    catch (error) {
+        if (!request_logger_1.RequestLogger.getCurrent()) {
+            logger.error('Error creating insight', error);
+        }
+        const errorMessage = (0, tool_helpers_1.extractErrorMessage)(error);
+        const errorDetails = error instanceof Error && error.stack
+            ? `\n\n**Stack trace:**\n\`\`\`\n${error.stack}\n\`\`\``
+            : '';
+        // Handle SQL syntax errors
+        if (errorMessage.toLowerCase().includes('sql') || errorMessage.toLowerCase().includes('syntax')) {
             return {
                 content: [{
-                        type: "text",
-                        text: responseText,
+                        type: 'text',
+                        text: `❌ **SQL Query Error**\n\nThere's a problem with your SQL query.\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Check column names match field names in sources\n- Check table names match source names\n- Use \`run_insight\` (sources + query) to test queries before saving\n- Make sure field IDs are correct (use \`describe_workflows\` with include:["schema"])`,
                     }],
             };
         }
-        catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Error previewing insight", error);
-            let errorMessage = 'Unknown error occurred';
-            if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else if (typeof error === 'object' && error !== null) {
-                try {
-                    errorMessage = JSON.stringify(error, null, 2);
-                }
-                catch {
-                    errorMessage = String(error);
-                }
-            }
-            else {
-                errorMessage = String(error);
-            }
+        // Handle permission errors
+        if (errorMessage.includes('permission') || errorMessage.includes('PermissionDenied')) {
             return {
                 content: [{
-                        type: "text",
-                        text: `❌ **Preview Failed**\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Check SQL syntax\n- Verify field names match source definitions\n- Ensure workflow IDs are correct\n- Check table aliases match source names`,
+                        type: 'text',
+                        text: `❌ **Permission Denied**\n\nYou may not have permission to create insights or access the specified workflows.\n\n**Error:** ${errorMessage}`,
                     }],
             };
         }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ **Error creating insight**\n\n**Error:** ${errorMessage}${errorDetails}\n\n**Common Issues:**\n- SQL query syntax errors\n- Invalid field IDs or workflow IDs\n- Workflow fields don't exist\n- Permission issues\n- Check field IDs with \`describe_workflows\` include:["schema"]\n- Test query with \`run_insight\` (sources + query) first`,
+                }],
+        };
     }
-};
-// ============================================================================
-// GET INSIGHT DATA TOOL
-// ============================================================================
-const getInsightDataDescription = `Execute insight and get results`;
-exports.getInsightDataTool = {
-    name: 'get_insight_data',
-    group: tool_registry_1.ToolGroup.PLAYGROUND,
-    description: getInsightDataDescription,
-    schema: zod_1.z.object({
-        insightId: zod_1.z
-            .string()
-            .describe("Insight ID to execute"),
-        update: zod_1.z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Whether to recalculate data (true) or use cached results (false, default)"),
-    }),
-    async execute(args, context) {
-        logger.debug('Getting insight data', {
-            insightId: args.insightId,
-            update: args.update,
-            apiKey: context.apiKey.substring(0, 8) + '...'
+}
+/** Update path: v3.insight.update (partial-field semantics) */
+async function updateExistingInsight(insightId, args, context) {
+    try {
+        // Build update payload - only include provided fields
+        const updateData = {};
+        if (args.name) {
+            updateData.name = args.name;
+        }
+        if (typeof args.public === 'boolean') {
+            updateData.public = args.public;
+        }
+        if (args.sources) {
+            updateData.sources = normalizeFields(args.sources);
+        }
+        if (args.query) {
+            updateData.query = args.query;
+        }
+        // Validate at least one field is being updated
+        if (Object.keys(updateData).length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `❌ **No updates provided**\n\nYou must provide at least one field to update:\n- name\n- public\n- sources\n- query\n\nExample:\n\`\`\`javascript\nsave_insight({\n  insightId: "${insightId}",\n  name: "New Name"\n})\n\`\`\``,
+                    }],
+            };
+        }
+        logger.debug('Calling v3.insight.update', {
+            insightId,
+            updateFields: Object.keys(updateData)
         });
-        try {
-            logger.debug('Calling v3.insight.data', {
-                insightId: args.insightId,
-                update: args.update
-            });
-            // Call v3.insight.data endpoint
-            const result = await context.hailer.request('v3.insight.data', [args.insightId, { update: args.update || false }]);
-            logger.debug('Insight data retrieved', {
-                headers: result.headers?.length,
-                rows: result.rows?.length,
-                fullResult: JSON.stringify(result).substring(0, 500)
-            });
-            // Format results
-            let responseText = `✅ **Insight Data Retrieved** (${result.rows?.length || 0} rows)\n\n`;
-            if (!result.headers || !result.rows) {
-                responseText += `⚠️ No data returned\n`;
-                responseText += `**Debug:** Response keys: ${Object.keys(result).join(', ')}\n`;
-                responseText += `**Full response (truncated):** \`${JSON.stringify(result).substring(0, 300)}\`\n`;
-            }
-            else if (result.rows.length === 0) {
-                responseText += `**Columns:** ${result.headers.join(', ')}\n\n`;
-                responseText += `⚠️ **No rows matched**\n`;
-            }
-            else {
-                responseText += `**Columns:** ${result.headers.join(', ')}\n\n`;
-                responseText += `**Sample Data (first 10 rows):**\n\`\`\`\n`;
-                // Show column headers
-                responseText += result.headers.join(' | ') + '\n';
-                responseText += result.headers.map(() => '---').join(' | ') + '\n';
-                // Show first 10 rows
-                const rowsToShow = Math.min(result.rows.length, 10);
-                for (let i = 0; i < rowsToShow; i++) {
-                    responseText += result.rows[i].map(v => String(v || '')).join(' | ') + '\n';
-                }
-                if (result.rows.length > 10) {
-                    responseText += `\n... and ${result.rows.length - 10} more rows\n`;
-                }
-                responseText += `\`\`\`\n`;
-            }
+        // Call v3.insight.update endpoint
+        // API expects: [insightId, updateData]
+        const result = await context.hailer.request('v3.insight.update', [
+            insightId,
+            updateData
+        ]);
+        logger.debug('Insight update successful', {
+            insightId,
+            result: JSON.stringify(result)
+        });
+        // Build success response
+        let responseText = '✅ **Insight Updated Successfully**\n\n';
+        responseText += `**Insight ID:** \`${insightId}\`\n`;
+        responseText += '**Updated Fields:**\n';
+        if (args.name) {
+            responseText += `- Name: ${args.name}\n`;
+        }
+        if (typeof args.public === 'boolean') {
+            responseText += `- Public: ${args.public ? 'Yes' : 'No'}\n`;
+        }
+        if (args.sources) {
+            responseText += `- Sources: ${args.sources.length} workflow(s)\n`;
+        }
+        if (args.query) {
+            responseText += '- Query: Updated\n';
+        }
+        if (args.query) {
+            responseText += `\n**New SQL Query:**\n\`\`\`sql\n${args.query}\n\`\`\`\n`;
+        }
+        responseText += '\n💡 **Next Steps:**\n';
+        responseText += '- Use `run_insight` with `refresh: true` to see fresh results\n';
+        responseText += '- Use `run_insight` (sources + query) to test if you made query changes\n';
+        responseText += '- Use `list_insights` to see all insights\n';
+        return {
+            content: [{
+                    type: 'text',
+                    text: responseText,
+                }],
+        };
+    }
+    catch (error) {
+        if (!request_logger_1.RequestLogger.getCurrent()) {
+            logger.error('Error updating insight', error);
+        }
+        const errorMessage = (0, tool_helpers_1.extractErrorMessage)(error);
+        // Handle SQL syntax errors
+        if (errorMessage.toLowerCase().includes('sql') || errorMessage.toLowerCase().includes('syntax')) {
             return {
                 content: [{
-                        type: "text",
-                        text: responseText,
+                        type: 'text',
+                        text: `❌ **SQL Query Error**\n\nThere's a problem with your SQL query.\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Check column names match field names in sources\n- Check table names match source names\n- Use \`run_insight\` (sources + query) to test queries before updating\n- Make sure field IDs are correct (use \`describe_workflows\` with include:["schema"])`,
                     }],
             };
         }
-        catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Error getting insight data", error);
-            let errorMessage = 'Unknown error occurred';
-            if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else if (typeof error === 'object' && error !== null) {
-                try {
-                    errorMessage = JSON.stringify(error, null, 2);
-                }
-                catch {
-                    errorMessage = String(error);
-                }
-            }
-            else {
-                errorMessage = String(error);
-            }
+        // Handle permission errors
+        if (errorMessage.includes('permission') || errorMessage.includes('PermissionDenied')) {
             return {
                 content: [{
-                        type: "text",
-                        text: `❌ **Error getting insight data**\n\n**Error:** ${errorMessage}\n\n**Common Issues:**\n- Insight ID not found\n- Permission denied\n- Insight query has errors\n- Use \`list_insights\` to verify insight ID`,
+                        type: 'text',
+                        text: `❌ **Permission Denied**\n\nYou may not have permission to update this insight.\n\n**Error:** ${errorMessage}`,
                     }],
             };
         }
+        // Handle not found errors
+        if (errorMessage.includes('not found') || errorMessage.includes('NotFound')) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `❌ **Insight Not Found**\n\nInsight ID \`${insightId}\` does not exist.\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Use \`list_insights\` to find valid insight IDs\n- Check for typos in the insight ID`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ **Error updating insight**\n\n**Error:** ${errorMessage}\n\n**Common Issues:**\n- Insight ID not found\n- SQL query syntax errors\n- Invalid field IDs or workflow IDs\n- Permission issues\n- Use \`list_insights\` to verify insight ID\n- Use \`run_insight\` (sources + query) to test query changes first`,
+                }],
+        };
     }
-};
-// ============================================================================
-// UPDATE INSIGHT TOOL
-// ============================================================================
-const updateInsightDescription = `Update existing insight (name, query, sources, or visibility)`;
-exports.updateInsightTool = {
-    name: 'update_insight',
+}
+exports.saveInsightTool = {
+    name: 'save_insight',
     group: tool_registry_1.ToolGroup.PLAYGROUND,
-    description: updateInsightDescription,
+    description: saveInsightDescription,
     schema: zod_1.z.object({
+        workspaceId: zod_1.z
+            .string()
+            .optional()
+            .describe('Optional workspace ID or name - defaults to current workspace (create mode only)'),
         insightId: zod_1.z
             .string()
-            .describe("Insight ID to update (24 characters)"),
+            .optional()
+            .describe('Existing insight ID to update (24 characters). Omit to create a new insight.'),
         name: zod_1.z
             .string()
+            .min(1)
             .optional()
-            .describe("New insight name"),
+            .describe('Insight name (required when creating)'),
         public: zod_1.z
             .coerce.boolean()
             .optional()
-            .describe("Whether insight is publicly accessible"),
+            .describe('Whether insight is publicly accessible (default: false on create)'),
         sources: zod_1.z
-            .preprocess((val) => typeof val === 'string' ? JSON.parse(val) : val, zod_1.z.array(sourceSchema).optional())
-            .describe("Updated workflow sources (like SQL table references)"),
+            .preprocess((val) => typeof val === 'string' ? JSON.parse(val) : val, zod_1.z.array(sourceSchema).min(1).optional())
+            .describe('Workflow sources (required when creating). source.name = SQL table name, field.name = SQL column name. Never use IDs in the query.'),
         query: zod_1.z
             .string()
+            .min(1)
             .optional()
-            .describe("Updated SQL query"),
+            .describe('SQL query (SELECT, JOIN, WHERE, GROUP BY, ORDER BY, etc.) - required when creating'),
     }),
     async execute(args, context) {
-        logger.debug('Updating insight', {
+        logger.debug('Saving insight', {
             insightId: args.insightId,
             hasName: !!args.name,
             hasQuery: !!args.query,
             hasSources: !!args.sources,
-            hasPublic: args.public !== undefined,
+            hasPublic: typeof args.public === 'boolean',
             apiKey: context.apiKey.substring(0, 8) + '...'
         });
-        try {
-            // Build update payload - only include provided fields
-            const updateData = {};
-            if (args.name !== undefined) {
-                updateData.name = args.name;
-            }
-            if (args.public !== undefined) {
-                updateData.public = args.public;
-            }
-            if (args.sources !== undefined) {
-                updateData.sources = normalizeFields(args.sources);
-            }
-            if (args.query !== undefined) {
-                updateData.query = args.query;
-            }
-            // Validate at least one field is being updated
-            if (Object.keys(updateData).length === 0) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `❌ **No updates provided**\n\nYou must provide at least one field to update:\n- name\n- public\n- sources\n- query\n\nExample:\n\`\`\`javascript\nupdate_insight({\n  insightId: "${args.insightId}",\n  name: "New Name"\n})\n\`\`\``,
-                        }],
-                };
-            }
-            logger.debug('Calling v3.insight.update', {
-                insightId: args.insightId,
-                updateFields: Object.keys(updateData)
-            });
-            // Call v3.insight.update endpoint
-            // API expects: [insightId, updateData]
-            const result = await context.hailer.request('v3.insight.update', [
-                args.insightId,
-                updateData
-            ]);
-            logger.debug('Insight update successful', {
-                insightId: args.insightId,
-                result: JSON.stringify(result)
-            });
-            // Build success response
-            let responseText = `✅ **Insight Updated Successfully**\n\n`;
-            responseText += `**Insight ID:** \`${args.insightId}\`\n`;
-            responseText += `**Updated Fields:**\n`;
-            if (args.name !== undefined) {
-                responseText += `- Name: ${args.name}\n`;
-            }
-            if (args.public !== undefined) {
-                responseText += `- Public: ${args.public ? 'Yes' : 'No'}\n`;
-            }
-            if (args.sources !== undefined) {
-                responseText += `- Sources: ${args.sources.length} workflow(s)\n`;
-            }
-            if (args.query !== undefined) {
-                responseText += `- Query: Updated\n`;
-            }
-            if (args.query) {
-                responseText += `\n**New SQL Query:**\n\`\`\`sql\n${args.query}\n\`\`\`\n`;
-            }
-            responseText += `\n💡 **Next Steps:**\n`;
-            responseText += `- Use \`get_insight_data\` with \`update: true\` to see fresh results\n`;
-            responseText += `- Use \`preview_insight\` to test if you made query changes\n`;
-            responseText += `- Use \`list_insights\` to see all insights\n`;
-            return {
-                content: [{
-                        type: "text",
-                        text: responseText,
-                    }],
-            };
-        }
-        catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Error updating insight", error);
-            const errorMessage = (0, tool_helpers_1.extractErrorMessage)(error);
-            // Handle SQL syntax errors
-            if (errorMessage.toLowerCase().includes('sql') || errorMessage.toLowerCase().includes('syntax')) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `❌ **SQL Query Error**\n\nThere's a problem with your SQL query.\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Check column names match field names in sources\n- Check table names match source names\n- Use \`preview_insight\` to test queries before updating\n- Make sure field IDs are correct (use \`get_workflow_schema\`)`,
-                        }],
-                };
-            }
-            // Handle permission errors
-            if (errorMessage.includes('permission') || errorMessage.includes('PermissionDenied')) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `❌ **Permission Denied**\n\nYou may not have permission to update this insight.\n\n**Error:** ${errorMessage}`,
-                        }],
-                };
-            }
-            // Handle not found errors
-            if (errorMessage.includes('not found') || errorMessage.includes('NotFound')) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: `❌ **Insight Not Found**\n\nInsight ID \`${args.insightId}\` does not exist.\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Use \`list_insights\` to find valid insight IDs\n- Check for typos in the insight ID`,
-                        }],
-                };
-            }
-            return {
-                content: [{
-                        type: "text",
-                        text: `❌ **Error updating insight**\n\n**Error:** ${errorMessage}\n\n**Common Issues:**\n- Insight ID not found\n- SQL query syntax errors\n- Invalid field IDs or workflow IDs\n- Permission issues\n- Use \`list_insights\` to verify insight ID\n- Use \`preview_insight\` to test query changes first`,
-                    }],
-            };
+        if (args.insightId) {
+            return updateExistingInsight(args.insightId, args, context);
         }
+        return createNewInsight(args, context);
     }
 };
 // ============================================================================
@@ -638,15 +580,15 @@ exports.removeInsightTool = {
     schema: zod_1.z.object({
         insightId: zod_1.z
             .string()
-            .describe("Insight ID to remove (get from list_insights or create_insight)"),
+            .describe('Insight ID to remove (get from list_insights or save_insight)'),
         confirmed: zod_1.z
             .boolean()
             .optional()
-            .describe("First confirmation - must be true to proceed"),
+            .describe('First confirmation - must be true to proceed'),
         secondConfirmed: zod_1.z
             .boolean()
             .optional()
-            .describe("Second confirmation - must be true to proceed (required for double-check safety)"),
+            .describe('Second confirmation - must be true to proceed (required for double-check safety)'),
     }),
     async execute(args, context) {
         logger.debug('Removing insight', {
@@ -664,7 +606,7 @@ exports.removeInsightTool = {
             // Fetch insight info and workspace info
             const [insightListResult, initData] = await Promise.all([
                 context.hailer.request('v3.insight.list', [workspaceId]),
-                context.hailer.request('v2.core.init', [["network"]])
+                context.hailer.request('v2.core.init', [['network']])
             ]);
             const insights = Array.isArray(insightListResult) ? insightListResult : (insightListResult.details || insightListResult.insights || []);
             const insight = insights.find((i) => i._id === args.insightId);
@@ -695,11 +637,11 @@ exports.removeInsightTool = {
                 warningText += `\`\`\`\n\n`;
                 warningText += `💡 **Before proceeding:**\n`;
                 warningText += `- Load \`remove-insight-skill\` to review safety checklist\n`;
-                warningText += `- Use \`get_insight_data\` to verify before deleting\n`;
+                warningText += `- Use \`run_insight\` to verify before deleting\n`;
                 warningText += `- Verify with user that this is intentional`;
                 return {
                     content: [{
-                            type: "text",
+                            type: 'text',
                             text: warningText,
                         }],
                 };
@@ -724,14 +666,15 @@ exports.removeInsightTool = {
             responseText += `💡 Use \`list_insights\` to see remaining insights.`;
             return {
                 content: [{
-                        type: "text",
+                        type: 'text',
                         text: responseText,
                     }],
             };
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Error removing insight", error);
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Error removing insight', error);
+            }
             let errorMessage = 'Unknown error occurred';
             if (error instanceof Error) {
                 errorMessage = error.message;
@@ -749,7 +692,7 @@ exports.removeInsightTool = {
             }
             return {
                 content: [{
-                        type: "text",
+                        type: 'text',
                         text: `❌ **Error removing insight**\n\n**Error:** ${errorMessage}\n\n**Common Issues:**\n- Insight ID not found\n- Permission denied\n- Insight already deleted\n- Use \`list_insights\` to verify insight ID`,
                     }],
             };
@@ -765,7 +708,7 @@ exports.listInsightsTool = {
         workspaceId: zod_1.z
             .string()
             .optional()
-            .describe("Optional workspace ID or name - defaults to current workspace"),
+            .describe('Optional workspace ID or name - defaults to current workspace'),
     }),
     async execute(args, context) {
         logger.debug('Listing insights', {
@@ -792,7 +735,7 @@ exports.listInsightsTool = {
             let responseText = `📊 **Insights Found** (${insights.length || 0} total)\n\n`;
             if (!insights || insights.length === 0) {
                 responseText += `No insights found in this workspace.\n\n`;
-                responseText += `💡 Use \`create_insight\` to create a new SQL-like report.`;
+                responseText += `💡 Use \`save_insight\` to create a new SQL-like report.`;
             }
             else {
                 insights.forEach((insight, index) => {
@@ -807,20 +750,21 @@ exports.listInsightsTool = {
                     responseText += `   - Query: \`${insight.query?.substring(0, 80)}${(insight.query?.length || 0) > 80 ? '...' : ''}\`\n\n`;
                 });
                 responseText += `💡 **Next Steps:**\n`;
-                responseText += `- Use \`get_insight_data\` to execute an insight\n`;
-                responseText += `- Use \`preview_insight\` to test query changes\n`;
+                responseText += `- Use \`run_insight\` with an insightId to execute an insight\n`;
+                responseText += `- Use \`run_insight\` with sources + query to test changes\n`;
                 responseText += `- Use \`remove_insight\` to delete an insight\n`;
             }
             return {
                 content: [{
-                        type: "text",
+                        type: 'text',
                         text: responseText,
                     }],
             };
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Error listing insights", error);
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Error listing insights', error);
+            }
             let errorMessage = 'Unknown error occurred';
             if (error instanceof Error) {
                 errorMessage = error.message;
@@ -838,7 +782,7 @@ exports.listInsightsTool = {
             }
             return {
                 content: [{
-                        type: "text",
+                        type: 'text',
                         text: `❌ **Error listing insights**\n\n**Error:** ${errorMessage}\n\n**Tips:**\n- Check workspace ID is valid\n- Verify you have permission to list insights`,
                     }],
             };
@@ -847,11 +791,9 @@ exports.listInsightsTool = {
 };
 /** All insight tools */
 exports.insightTools = [
-    exports.createInsightTool,
-    exports.previewInsightTool,
-    exports.getInsightDataTool,
-    exports.updateInsightTool,
-    exports.removeInsightTool,
     exports.listInsightsTool,
+    exports.runInsightTool,
+    exports.saveInsightTool,
+    exports.removeInsightTool,
 ];
 //# sourceMappingURL=insight.js.map