@ema.co/mcp-toolkit 2026.2.13 → 2026.2.19

package/dist/mcp/domain/quality-gates.js

@@ -1,110 +0,0 @@
-/**
- * Quality Gates - Pre-Deploy Validation
- *
- * DEPRECATED: This module used detectWorkflowIssues which has been removed.
- *
- * The LLM should analyze workflows using rules from:
- * - ema://rules/anti-patterns
- * - ema://rules/input-sources
- * - ema://rules/optimizations
- *
- * Backend validation happens when workflow is deployed.
- * These quality gates are kept for backwards compatibility but are minimal.
- */
-// ─────────────────────────────────────────────────────────────────────────────
-// Minimal Quality Gates (structural only)
-// ─────────────────────────────────────────────────────────────────────────────
-export const QUALITY_GATES = [
-    {
-        id: "has_actions",
-        name: "Has Actions",
-        description: "Workflow must have at least one action",
-        blocking: true,
-        severity: "critical",
-        check: (workflow) => {
-            const actions = (workflow.actions || []);
-            return {
-                passed: actions.length > 0,
-                message: actions.length > 0
-                    ? `Workflow has ${actions.length} action(s)`
-                    : "Workflow has no actions",
-            };
-        },
-    },
-    {
-        id: "has_results",
-        name: "Has Results Mapping",
-        description: "Voice AI workflows must have results mapping",
-        blocking: false,
-        severity: "warning",
-        check: (workflow) => {
-            const results = workflow.results;
-            const hasResults = results && Object.keys(results).length > 0;
-            return {
-                passed: hasResults || false,
-                message: hasResults
-                    ? `Workflow has ${Object.keys(results).length} result mapping(s)`
-                    : "No results mapping found (may be OK for chat workflows)",
-            };
-        },
-    },
-];
-// ─────────────────────────────────────────────────────────────────────────────
-// Quality Gate Runner
-// ─────────────────────────────────────────────────────────────────────────────
-export function runQualityGates(workflow, gates = QUALITY_GATES) {
-    const results = [];
-    let blockingFailures = 0;
-    let warnings = 0;
-    for (const gate of gates) {
-        const result = gate.check(workflow);
-        results.push({
-            gate_id: gate.id,
-            gate_name: gate.name,
-            result,
-            blocking: gate.blocking,
-            severity: gate.severity,
-        });
-        if (!result.passed) {
-            if (gate.blocking) {
-                blockingFailures++;
-            }
-            else if (gate.severity === "warning") {
-                warnings++;
-            }
-        }
-    }
-    const deploymentAllowed = blockingFailures === 0;
-    return {
-        overall_status: blockingFailures > 0 ? "fail" : warnings > 0 ? "warning" : "pass",
-        gates: results,
-        blocking_failures: blockingFailures,
-        warnings,
-        deployment_allowed: deploymentAllowed,
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Utility Functions
-// ─────────────────────────────────────────────────────────────────────────────
-export function isDeploymentAllowed(report) {
-    return report.deployment_allowed;
-}
-export function getBlockingIssues(report) {
-    return report.gates
-        .filter(g => g.blocking && !g.result.passed)
-        .map(g => `${g.gate_name}: ${g.result.message}`);
-}
-export function formatQualityReport(report) {
-    let output = `Quality Report: ${report.overall_status.toUpperCase()}\n`;
-    output += `Deployment Allowed: ${report.deployment_allowed ? "YES" : "NO"}\n\n`;
-    for (const gate of report.gates) {
-        const status = gate.result.passed ? "✓" : gate.blocking ? "✗" : "⚠";
-        output += `${status} ${gate.gate_name}: ${gate.result.message}\n`;
-        if (gate.result.details) {
-            for (const detail of gate.result.details) {
-                output += `    - ${detail}\n`;
-            }
-        }
-    }
-    return output;
-}

package/dist/mcp/domain/workflow-execution-analyzer.js

@@ -1,412 +0,0 @@
-/**
- * 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;
-}