@ema.co/mcp-toolkit 1.4.3 → 1.5.1

package/dist/sdk/workflow-execution-analyzer.js

@@ -0,0 +1,412 @@
+/**
+ * Workflow Execution Analyzer
+ *
+ * Deep analysis of workflow execution logic learned from Auto Builder insights:
+ * - Loop detection (circular, infinite, re-entry)
+ * - Multiple responder detection (causes duplicate/triple responses)
+ * - Ungated catch-all detection
+ * - Redundant classifier detection
+ * - Data flow analysis
+ * - runIf condition validation
+ * - Parallel execution opportunities
+ * - Dead code path detection
+ */
+import { parseWorkflowDef } from "./knowledge.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// GRAPH BUILDING
+// ═══════════════════════════════════════════════════════════════════════════
+function buildGraphMaps(nodes) {
+    const forward = new Map();
+    const reverse = new Map();
+    const nodeMap = new Map();
+    for (const node of nodes) {
+        nodeMap.set(node.id, node);
+        forward.set(node.id, new Set());
+        reverse.set(node.id, new Set());
+    }
+    for (const node of nodes) {
+        if (node.incoming_edges) {
+            for (const edge of node.incoming_edges) {
+                const sourceId = edge.source_node_id;
+                forward.get(sourceId)?.add(node.id);
+                reverse.get(node.id)?.add(sourceId);
+            }
+        }
+    }
+    return { forward, reverse, nodeMap };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// LOOP DETECTION
+// ═══════════════════════════════════════════════════════════════════════════
+export function detectLoops(workflowDef) {
+    const nodes = parseWorkflowDef(workflowDef);
+    const loops = [];
+    const { forward, nodeMap } = buildGraphMaps(nodes);
+    // DFS for cycle detection
+    const visited = new Set();
+    const recursionStack = new Set();
+    const path = [];
+    function dfs(nodeId) {
+        visited.add(nodeId);
+        recursionStack.add(nodeId);
+        path.push(nodeId);
+        for (const neighbor of (forward.get(nodeId) || [])) {
+            if (!visited.has(neighbor)) {
+                if (dfs(neighbor))
+                    return true;
+            }
+            else if (recursionStack.has(neighbor)) {
+                const cycleStart = path.indexOf(neighbor);
+                const cyclePath = path.slice(cycleStart);
+                cyclePath.push(neighbor);
+                loops.push({
+                    type: 'circular_dependency',
+                    nodes: cyclePath,
+                    description: `Circular dependency: ${cyclePath.join(' → ')}`,
+                    severity: 'critical',
+                    fixSuggestion: `Break the cycle by removing one edge.`,
+                });
+                return true;
+            }
+        }
+        path.pop();
+        recursionStack.delete(nodeId);
+        return false;
+    }
+    const trigger = nodes.find(n => n.action_name === 'trigger' || n.id === 'trigger');
+    if (trigger)
+        dfs(trigger.id);
+    for (const node of nodes) {
+        if (!visited.has(node.id))
+            dfs(node.id);
+    }
+    // Detect categorizer routing back to upstream (re-entry)
+    for (const node of nodes) {
+        if (node.action_name === 'chat_categorizer') {
+            const downstream = forward.get(node.id) || new Set();
+            const upstream = new Set();
+            function findUpstream(nId, depth = 0) {
+                if (depth > 20)
+                    return;
+                const nodeInfo = nodeMap.get(nId);
+                if (!nodeInfo?.incoming_edges)
+                    return;
+                for (const edge of nodeInfo.incoming_edges) {
+                    upstream.add(edge.source_node_id);
+                    findUpstream(edge.source_node_id, depth + 1);
+                }
+            }
+            findUpstream(node.id);
+            for (const downNode of downstream) {
+                if (upstream.has(downNode)) {
+                    loops.push({
+                        type: 'reentry_loop',
+                        nodes: [node.id, downNode],
+                        description: `Categorizer "${node.display_name || node.id}" routes to "${downNode}" which is upstream - can cause re-processing`,
+                        severity: 'warning',
+                        fixSuggestion: `Add state tracking or one-time-execution gate to prevent re-processing.`,
+                    });
+                }
+            }
+        }
+    }
+    return loops;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// MULTIPLE RESPONDER DETECTION (Key cause of "says same thing 3 times")
+// ═══════════════════════════════════════════════════════════════════════════
+export function detectMultipleResponders(workflowDef) {
+    const nodes = parseWorkflowDef(workflowDef);
+    const issues = [];
+    const { reverse, nodeMap } = buildGraphMaps(nodes);
+    // Find all nodes that feed into WORKFLOW_OUTPUT
+    const def = workflowDef;
+    const resultMappings = def?.resultMappings;
+    const outputFeeders = [];
+    if (resultMappings) {
+        for (const mapping of resultMappings) {
+            const nodeName = mapping.namedOutput?.nodeName;
+            if (nodeName)
+                outputFeeders.push(nodeName);
+        }
+    }
+    // Find responder-type nodes
+    const responderNodes = nodes.filter(n => n.action_name === 'call_llm' ||
+        n.action_name === 'custom_agent' ||
+        n.action_name === 'respond_with_sources' ||
+        n.action_name === 'fixed_response');
+    const respondersFeedingOutput = responderNodes.filter(n => outputFeeders.includes(n.id));
+    if (respondersFeedingOutput.length > 1) {
+        const ungatedResponders = respondersFeedingOutput.filter(n => !n.runIf);
+        const gatedResponders = respondersFeedingOutput.filter(n => n.runIf);
+        if (ungatedResponders.length > 0 && gatedResponders.length > 0) {
+            issues.push({
+                type: 'competing_outputs',
+                nodes: respondersFeedingOutput.map(n => n.id),
+                description: `${ungatedResponders.length} ungated + ${gatedResponders.length} gated responders compete for output`,
+                severity: 'critical',
+                fixSuggestion: `Gate ALL responders with mutually exclusive conditions. Ungated: ${ungatedResponders.map(n => n.display_name || n.id).join(', ')}`,
+                willCauseTripleResponse: ungatedResponders.length + gatedResponders.length >= 3,
+            });
+        }
+        if (ungatedResponders.length > 1) {
+            issues.push({
+                type: 'parallel_responders',
+                nodes: ungatedResponders.map(n => n.id),
+                description: `${ungatedResponders.length} ungated responders fire simultaneously: ${ungatedResponders.map(n => n.display_name || n.id).join(', ')}`,
+                severity: 'critical',
+                fixSuggestion: `Add trigger_when conditions to make mutually exclusive, or consolidate into single responder`,
+                willCauseTripleResponse: ungatedResponders.length >= 3,
+            });
+        }
+    }
+    // Find ALL ungated catch-all nodes (not just output feeders)
+    for (const node of nodes) {
+        if (node.action_name === 'trigger')
+            continue;
+        const isResponder = ['call_llm', 'custom_agent', 'respond_with_sources', 'fixed_response'].includes(node.action_name || '');
+        if (!isResponder)
+            continue;
+        if (node.runIf)
+            continue; // Has gating
+        const upstream = reverse.get(node.id) || new Set();
+        if (upstream.size > 0) {
+            // Check if ALL upstream paths are ungated
+            let allUpstreamUngated = true;
+            for (const upId of upstream) {
+                const upNode = nodeMap.get(upId);
+                if (upNode?.runIf || upNode?.action_name === 'chat_categorizer') {
+                    allUpstreamUngated = false;
+                    break;
+                }
+            }
+            if (allUpstreamUngated && !outputFeeders.includes(node.id)) {
+                issues.push({
+                    type: 'ungated_responder',
+                    nodes: [node.id],
+                    description: `"${node.display_name || node.id}" always runs (no trigger_when gate)`,
+                    severity: 'warning',
+                    fixSuggestion: `Add runIf: { enum: { enumType: "category", enumValue: "specific_intent" } }`,
+                    willCauseTripleResponse: false,
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// REDUNDANT CLASSIFIER DETECTION
+// ═══════════════════════════════════════════════════════════════════════════
+export function detectRedundantClassifiers(workflowDef) {
+    const nodes = parseWorkflowDef(workflowDef);
+    const issues = [];
+    const classifiers = nodes.filter(n => n.action_name === 'chat_categorizer' ||
+        n.action_name === 'intent_classifier');
+    if (classifiers.length > 1) {
+        // Group by input source
+        const classifiersByInput = new Map();
+        for (const classifier of classifiers) {
+            const inputSources = [];
+            if (classifier.incoming_edges) {
+                for (const edge of classifier.incoming_edges) {
+                    if (edge.target_input === 'conversation' || edge.target_input === 'text_input') {
+                        inputSources.push(edge.source_node_id);
+                    }
+                }
+            }
+            const key = inputSources.sort().join(',');
+            const existing = classifiersByInput.get(key) || [];
+            existing.push(classifier);
+            classifiersByInput.set(key, existing);
+        }
+        for (const [, group] of classifiersByInput) {
+            if (group.length > 1) {
+                issues.push({
+                    classifiers: group.map(c => c.id),
+                    description: `${group.map(c => c.display_name || c.id).join(' & ')} analyze same input - causes overlapping/conflicting routing`,
+                    fixSuggestion: `Consolidate into single classifier, or chain sequentially with clear precedence`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// DATA FLOW ISSUES
+// ═══════════════════════════════════════════════════════════════════════════
+export function analyzeDataFlow(workflowDef) {
+    const nodes = parseWorkflowDef(workflowDef);
+    const issues = [];
+    const { forward, nodeMap } = buildGraphMaps(nodes);
+    for (const node of nodes) {
+        if (!node.incoming_edges)
+            continue;
+        for (const edge of node.incoming_edges) {
+            const sourceNode = nodeMap.get(edge.source_node_id);
+            if (!sourceNode) {
+                issues.push({
+                    type: 'missing_data',
+                    node: node.id,
+                    description: `"${node.display_name || node.id}" expects data from non-existent "${edge.source_node_id}"`,
+                    severity: 'critical',
+                    fixSuggestion: `Add node "${edge.source_node_id}" or update input binding`,
+                });
+            }
+            // Check if source is gated but target isn't
+            if (sourceNode?.runIf && !node.runIf) {
+                issues.push({
+                    type: 'gated_dependency',
+                    node: node.id,
+                    description: `"${node.display_name || node.id}" depends on gated "${sourceNode.display_name || sourceNode.id}" but has no gate itself - may not get data`,
+                    severity: 'warning',
+                    fixSuggestion: `Add matching runIf condition to "${node.display_name || node.id}"`,
+                });
+            }
+        }
+    }
+    // Orphaned outputs
+    for (const [nodeId, node] of nodeMap) {
+        const downstream = forward.get(nodeId) || new Set();
+        if (downstream.size === 0 &&
+            nodeId !== 'WORKFLOW_OUTPUT' &&
+            !['send_email_agent', 'send_communications_handler'].includes(node.action_name || '')) {
+            const def = workflowDef;
+            const resultMappings = def?.resultMappings;
+            const isMapped = resultMappings?.some((m) => {
+                const mapping = m;
+                return mapping.namedOutput?.nodeName === nodeId;
+            });
+            if (!isMapped) {
+                issues.push({
+                    type: 'orphaned_output',
+                    node: nodeId,
+                    description: `"${node.display_name || nodeId}" output is never consumed`,
+                    severity: 'warning',
+                    fixSuggestion: `Connect to downstream node or WORKFLOW_OUTPUT, or remove if unused`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// DEAD CODE DETECTION
+// ═══════════════════════════════════════════════════════════════════════════
+export function findDeadCodePaths(workflowDef) {
+    const nodes = parseWorkflowDef(workflowDef);
+    const { forward } = buildGraphMaps(nodes);
+    const trigger = nodes.find(n => n.action_name === 'trigger' || n.id === 'trigger');
+    if (!trigger)
+        return nodes.map(n => n.id);
+    const reachable = new Set();
+    const queue = [trigger.id];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (reachable.has(current))
+            continue;
+        reachable.add(current);
+        for (const next of (forward.get(current) || [])) {
+            queue.push(next);
+        }
+    }
+    return nodes.filter(n => !reachable.has(n.id) && n.id !== 'WORKFLOW_OUTPUT').map(n => n.id);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN ANALYSIS FUNCTION
+// ═══════════════════════════════════════════════════════════════════════════
+export function analyzeExecutionFlow(workflowDef) {
+    const nodes = parseWorkflowDef(workflowDef);
+    const loops = detectLoops(workflowDef);
+    const multipleResponderIssues = detectMultipleResponders(workflowDef);
+    const redundantClassifiers = detectRedundantClassifiers(workflowDef);
+    const dataFlowIssues = analyzeDataFlow(workflowDef);
+    const deadCodePaths = findDeadCodePaths(workflowDef);
+    const criticalIssues = loops.filter(l => l.severity === 'critical').length +
+        multipleResponderIssues.filter(m => m.severity === 'critical').length +
+        dataFlowIssues.filter(d => d.severity === 'critical').length;
+    const summary = {
+        totalNodes: nodes.length,
+        reachableNodes: nodes.length - deadCodePaths.length,
+        unreachableNodes: deadCodePaths.length,
+        loopCount: loops.length,
+        criticalIssues,
+        warnings: loops.filter(l => l.severity === 'warning').length +
+            multipleResponderIssues.filter(m => m.severity === 'warning').length +
+            dataFlowIssues.filter(d => d.severity === 'warning').length,
+        mayRepeatResponses: multipleResponderIssues.some(m => m.willCauseTripleResponse),
+        ungatedResponderCount: multipleResponderIssues.filter(m => m.type === 'ungated_responder').length,
+        redundantClassifierCount: redundantClassifiers.length,
+    };
+    return {
+        loops,
+        multipleResponderIssues,
+        redundantClassifiers,
+        dataFlowIssues,
+        deadCodePaths,
+        summary,
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// ASCII VISUALIZATION
+// ═══════════════════════════════════════════════════════════════════════════
+export function generateASCIIFlow(analysis) {
+    let output = '';
+    output += '╔══════════════════════════════════════════════════════════════════╗\n';
+    output += '║           EXECUTION FLOW ANALYSIS (Auto Builder Insights)       ║\n';
+    output += '╚══════════════════════════════════════════════════════════════════╝\n\n';
+    output += `📊 SUMMARY\n`;
+    output += `   Total Nodes: ${analysis.summary.totalNodes}\n`;
+    output += `   Reachable: ${analysis.summary.reachableNodes}\n`;
+    output += `   Dead Code: ${analysis.summary.unreachableNodes}\n`;
+    output += `   Critical Issues: ${analysis.summary.criticalIssues}\n`;
+    output += `   Warnings: ${analysis.summary.warnings}\n`;
+    output += `   May Repeat Responses: ${analysis.summary.mayRepeatResponses ? '⚠️ YES - TRIPLE RESPONSE RISK!' : '✓ No'}\n`;
+    output += `   Ungated Responders: ${analysis.summary.ungatedResponderCount}\n`;
+    output += `   Redundant Classifiers: ${analysis.summary.redundantClassifierCount}\n\n`;
+    if (analysis.multipleResponderIssues.length > 0) {
+        output += `🔊 DUPLICATE RESPONSE RISKS (${analysis.multipleResponderIssues.length})\n`;
+        for (const issue of analysis.multipleResponderIssues) {
+            const icon = issue.severity === 'critical' ? '❌' : '⚠️';
+            output += `   ${icon} ${issue.type}\n`;
+            output += `      ${issue.description}\n`;
+            if (issue.willCauseTripleResponse)
+                output += `      ⚡ WILL CAUSE TRIPLE RESPONSE!\n`;
+            output += `      Fix: ${issue.fixSuggestion}\n\n`;
+        }
+    }
+    if (analysis.redundantClassifiers.length > 0) {
+        output += `🔀 REDUNDANT CLASSIFIERS (${analysis.redundantClassifiers.length})\n`;
+        for (const issue of analysis.redundantClassifiers) {
+            output += `   ⚠️ ${issue.classifiers.join(', ')}\n`;
+            output += `      ${issue.description}\n`;
+            output += `      Fix: ${issue.fixSuggestion}\n\n`;
+        }
+    }
+    if (analysis.loops.length > 0) {
+        output += `🔄 LOOPS (${analysis.loops.length})\n`;
+        for (const loop of analysis.loops) {
+            const icon = loop.severity === 'critical' ? '❌' : '⚠️';
+            output += `   ${icon} ${loop.type}: ${loop.description}\n`;
+            output += `      Fix: ${loop.fixSuggestion}\n\n`;
+        }
+    }
+    if (analysis.deadCodePaths.length > 0) {
+        output += `💀 DEAD CODE (${analysis.deadCodePaths.length})\n`;
+        output += `   Unreachable: ${analysis.deadCodePaths.slice(0, 5).join(', ')}`;
+        if (analysis.deadCodePaths.length > 5)
+            output += ` +${analysis.deadCodePaths.length - 5} more`;
+        output += '\n\n';
+    }
+    if (analysis.dataFlowIssues.length > 0) {
+        output += `📦 DATA FLOW (${analysis.dataFlowIssues.length})\n`;
+        for (const issue of analysis.dataFlowIssues.slice(0, 5)) {
+            const icon = issue.severity === 'critical' ? '❌' : '⚠️';
+            output += `   ${icon} ${issue.type} at "${issue.node}"\n`;
+            output += `      ${issue.description}\n\n`;
+        }
+        if (analysis.dataFlowIssues.length > 5) {
+            output += `   ... +${analysis.dataFlowIssues.length - 5} more\n`;
+        }
+    }
+    return output;
+}

package/dist/sdk/workflow-fixer.js

@@ -0,0 +1,272 @@
+/**
+ * Workflow Fixer
+ *
+ * Automatically fixes detected workflow issues including:
+ * - Orphan node removal
+ * - Email recipient rewiring to entity_extraction
+ * - Missing fallback addition
+ * - Multiple responder consolidation (NEW)
+ * - Ungated responder gating (NEW)
+ */
+import { detectWorkflowIssues } from "./knowledge.js";
+import { detectMultipleResponders } from "./workflow-execution-analyzer.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// FIX FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Remove orphan nodes (respecting protected nodes used by other fixes)
+ */
+function fixOrphanNodes(workflowDef, issues, protectedNodes) {
+    const fixes = [];
+    const orphanIssues = issues.filter(i => i.type === 'orphan');
+    if (orphanIssues.length === 0)
+        return { def: workflowDef, fixes };
+    // Get actions array (Ema format)
+    const actions = (workflowDef.actions || workflowDef.nodes || []);
+    const nodesToRemove = new Set();
+    for (const issue of orphanIssues) {
+        const nodeName = issue.node;
+        if (!nodeName)
+            continue;
+        if (protectedNodes.has(nodeName)) {
+            fixes.push({
+                applied: false,
+                issueType: 'orphan',
+                nodeName,
+                description: `Skipped - node used by another fix`,
+            });
+            continue;
+        }
+        nodesToRemove.add(nodeName);
+        fixes.push({
+            applied: true,
+            issueType: 'orphan',
+            nodeName,
+            description: `Removed orphan node "${nodeName}"`,
+            change: 'removed',
+        });
+    }
+    const filteredActions = actions.filter((a) => {
+        const action = a;
+        return !nodesToRemove.has(action.name || '');
+    });
+    const key = workflowDef.actions ? 'actions' : 'nodes';
+    return {
+        def: { ...workflowDef, [key]: filteredActions },
+        fixes,
+    };
+}
+/**
+ * Fix wrong email recipient sources - rewire to entity_extraction
+ */
+function fixWrongInputSource(workflowDef, issues) {
+    const fixes = [];
+    const usedNodes = new Set();
+    const wrongInputIssues = issues.filter(i => i.type === 'wrong_input_source');
+    if (wrongInputIssues.length === 0)
+        return { def: workflowDef, fixes, usedNodes };
+    const actions = (workflowDef.actions || workflowDef.nodes || []);
+    // Find entity extraction nodes
+    const entityExtractionNodes = actions.filter((a) => {
+        const action = a;
+        return action.action?.name?.name === 'entity_extraction' ||
+            action.action?.name?.name === 'entity_extraction_with_documents';
+    }).map((a) => a.name).filter(Boolean);
+    if (entityExtractionNodes.length === 0) {
+        fixes.push({
+            applied: false,
+            issueType: 'wrong_input_source',
+            nodeName: 'N/A',
+            description: `No entity_extraction node found to rewire email to`,
+        });
+        return { def: workflowDef, fixes, usedNodes };
+    }
+    const updatedActions = actions.map((a) => {
+        const action = a;
+        const nodeIssue = wrongInputIssues.find(i => i.node === action.name);
+        if (!nodeIssue)
+            return a;
+        const isEmailNode = ['send_email_agent', 'send_communications_handler'].includes(action.action?.name?.name || '');
+        if (!isEmailNode)
+            return a;
+        const inputs = { ...action.inputs };
+        let fixed = false;
+        for (const [inputName, binding] of Object.entries(inputs)) {
+            if (!['to_email', 'email_to', 'recipient'].includes(inputName.toLowerCase()))
+                continue;
+            const b = binding;
+            if (!b.actionOutput?.actionName)
+                continue;
+            const targetExtraction = entityExtractionNodes[0];
+            inputs[inputName] = {
+                actionOutput: {
+                    actionName: targetExtraction,
+                    output: 'extraction_columns',
+                },
+            };
+            usedNodes.add(targetExtraction);
+            fixed = true;
+            fixes.push({
+                applied: true,
+                issueType: 'wrong_input_source',
+                nodeName: action.name || '',
+                description: `Rewired ${inputName} to ${targetExtraction}.extraction_columns`,
+                change: `${inputName}: ${b.actionOutput.actionName} → ${targetExtraction}`,
+            });
+        }
+        if (!fixed) {
+            fixes.push({
+                applied: false,
+                issueType: 'wrong_input_source',
+                nodeName: action.name || '',
+                description: `Could not find email_to field to rewire`,
+            });
+        }
+        return { ...action, inputs };
+    });
+    const key = workflowDef.actions ? 'actions' : 'nodes';
+    return {
+        def: { ...workflowDef, [key]: updatedActions },
+        fixes,
+        usedNodes,
+    };
+}
+/**
+ * Add fallback category to categorizers missing one
+ */
+function fixMissingFallback(workflowDef, issues) {
+    const fixes = [];
+    const fallbackIssues = issues.filter(i => i.type === 'missing_fallback');
+    if (fallbackIssues.length === 0)
+        return { def: workflowDef, fixes };
+    const actions = (workflowDef.actions || workflowDef.nodes || []);
+    for (const issue of fallbackIssues) {
+        const categorizer = actions.find((a) => a.name === issue.node);
+        if (!categorizer?.action?.typeArguments?.categories)
+            continue;
+        const categories = categorizer.action.typeArguments.categories;
+        if (categories.some(c => c.toLowerCase() === 'fallback' || c.toLowerCase() === 'other')) {
+            continue;
+        }
+        categorizer.action.typeArguments.categories = [...categories, 'Fallback'];
+        fixes.push({
+            applied: true,
+            issueType: 'missing_fallback',
+            nodeName: issue.node || '',
+            description: `Added "Fallback" category`,
+            change: `categories += "Fallback"`,
+        });
+    }
+    return { def: workflowDef, fixes };
+}
+/**
+ * NEW: Fix ungated responders by adding runIf conditions
+ */
+function fixUngatedResponders(workflowDef, multiResponderIssues) {
+    const fixes = [];
+    const ungatedIssues = multiResponderIssues.filter(i => i.type === 'ungated_responder');
+    if (ungatedIssues.length === 0)
+        return { def: workflowDef, fixes };
+    const actions = (workflowDef.actions || workflowDef.nodes || []);
+    // Find categorizer to use for gating
+    const categorizer = actions.find((a) => {
+        const action = a;
+        return action.action?.name?.name === 'chat_categorizer';
+    });
+    if (!categorizer) {
+        fixes.push({
+            applied: false,
+            issueType: 'ungated_responder',
+            nodeName: 'N/A',
+            description: `No categorizer found to add gating condition from`,
+        });
+        return { def: workflowDef, fixes };
+    }
+    // For now, just report what SHOULD be done
+    for (const issue of ungatedIssues) {
+        for (const nodeId of issue.nodes) {
+            fixes.push({
+                applied: false, // Manual fix recommended
+                issueType: 'ungated_responder',
+                nodeName: nodeId,
+                description: `Should add runIf condition from "${categorizer.name}"`,
+                change: `Add: runIf: { enum: { enumType: "category", enumValue: "<specific_category>" } }`,
+            });
+        }
+    }
+    return { def: workflowDef, fixes };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN AUTO-FIX FUNCTION
+// ═══════════════════════════════════════════════════════════════════════════
+export function autoFixWorkflow(workflowDef) {
+    const def = workflowDef;
+    const originalIssues = detectWorkflowIssues(workflowDef);
+    const multiResponderIssues = detectMultipleResponders(workflowDef);
+    const originalIssueCount = originalIssues.length + multiResponderIssues.length;
+    const allFixes = [];
+    const warnings = [];
+    let currentDef = { ...def };
+    // 1. Fix wrong input sources first (protects nodes)
+    const inputSourceResult = fixWrongInputSource(currentDef, originalIssues);
+    currentDef = inputSourceResult.def;
+    allFixes.push(...inputSourceResult.fixes);
+    const protectedNodes = inputSourceResult.usedNodes;
+    // 2. Fix missing fallback
+    const fallbackResult = fixMissingFallback(currentDef, originalIssues);
+    currentDef = fallbackResult.def;
+    allFixes.push(...fallbackResult.fixes);
+    // 3. Fix orphan nodes (respecting protected)
+    const orphanResult = fixOrphanNodes(currentDef, originalIssues, protectedNodes);
+    currentDef = orphanResult.def;
+    allFixes.push(...orphanResult.fixes);
+    // 4. NEW: Report ungated responder fixes needed
+    const ungatedResult = fixUngatedResponders(currentDef, multiResponderIssues);
+    const multipleResponderFixes = ungatedResult.fixes;
+    // Re-detect remaining issues
+    const remainingIssues = detectWorkflowIssues(currentDef);
+    const remainingMultiResponder = detectMultipleResponders(currentDef);
+    const remainingIssueCount = remainingIssues.length + remainingMultiResponder.length;
+    const appliedCount = allFixes.filter(f => f.applied).length;
+    if (multipleResponderFixes.length > 0) {
+        warnings.push(`${multipleResponderFixes.length} ungated responder(s) need manual gating to prevent duplicate responses`);
+    }
+    return {
+        originalIssueCount,
+        fixesApplied: allFixes,
+        remainingIssueCount,
+        workflowDef: currentDef,
+        success: appliedCount > 0,
+        warnings,
+        multipleResponderFixes,
+    };
+}
+/**
+ * Suggest fixes without applying (dry run)
+ */
+export function suggestFixes(workflowDef) {
+    const issues = detectWorkflowIssues(workflowDef);
+    const multiResponderIssues = detectMultipleResponders(workflowDef);
+    const standardFixes = [];
+    const multiResponderFixes = [];
+    for (const issue of issues) {
+        if (!issue.auto_fixable)
+            continue;
+        standardFixes.push({
+            applied: false,
+            issueType: issue.type,
+            nodeName: issue.node || 'N/A',
+            description: issue.reason || `Fix ${issue.type}`,
+        });
+    }
+    for (const issue of multiResponderIssues) {
+        multiResponderFixes.push({
+            applied: false,
+            issueType: issue.type,
+            nodeName: issue.nodes.join(', '),
+            description: issue.description,
+            change: issue.fixSuggestion,
+        });
+    }
+    return { standardFixes, multiResponderFixes };
+}