@ema.co/mcp-toolkit 2026.1.26-4 → 2026.1.27

package/dist/sdk/quality-gates.js

@@ -1,386 +1,110 @@
 /**
  * Quality Gates - Pre-Deploy Validation
  *
- * Ensures workflows meet minimum quality standards before deployment.
- * These are the "guardrails" that prevent broken workflows from going live.
+ * 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.
  */
-import { detectWorkflowIssues } from "./knowledge.js";
 // ─────────────────────────────────────────────────────────────────────────────
-// Quality Gate Definitions
+// Minimal Quality Gates (structural only)
 // ─────────────────────────────────────────────────────────────────────────────
-const QUALITY_GATES = [
-    // ═══════════════════════════════════════════════════════════════════════════
-    // CRITICAL GATES (Blocking)
-    // ═══════════════════════════════════════════════════════════════════════════
-    {
-        id: "has_trigger",
-        name: "Has Entry Point",
-        description: "Workflow must have a trigger node as entry point",
-        blocking: true,
-        severity: "critical",
-        check: (workflow) => {
-            const actions = (workflow.actions || []);
-            const hasTrigger = actions.some(a => {
-                const actionName = a.action?.name;
-                const name = (actionName?.name || "").toLowerCase();
-                return name.includes("trigger");
-            });
-            return {
-                passed: hasTrigger,
-                message: hasTrigger
-                    ? "Workflow has a valid trigger"
-                    : "Missing trigger node - workflow has no entry point",
-            };
-        },
-    },
-    {
-        id: "has_output",
-        name: "Has Workflow Output",
-        description: "Workflow must have at least one WORKFLOW_OUTPUT defined",
-        blocking: true,
-        severity: "critical",
-        check: (workflow) => {
-            const results = workflow.results;
-            const hasOutput = results && Object.keys(results).length > 0;
-            return {
-                passed: !!hasOutput,
-                message: hasOutput
-                    ? `Workflow has ${Object.keys(results).length} output(s) defined`
-                    : "No WORKFLOW_OUTPUT defined - responses won't reach users",
-            };
-        },
-    },
-    {
-        id: "no_critical_issues",
-        name: "No Critical Issues",
-        description: "Workflow must not have any critical structural issues",
-        blocking: true,
-        severity: "critical",
-        check: (workflow) => {
-            const issues = detectWorkflowIssues(workflow);
-            const criticalIssues = issues.filter((i) => i.severity === "critical");
-            return {
-                passed: criticalIssues.length === 0,
-                message: criticalIssues.length === 0
-                    ? "No critical issues detected"
-                    : `${criticalIssues.length} critical issue(s) found`,
-                details: criticalIssues.map((i) => `${i.type}: ${i.reason}`),
-            };
-        },
-    },
+export const QUALITY_GATES = [
     {
-        id: "all_paths_reach_output",
-        name: "All Paths Reach Output",
-        description: "Every branch from trigger must eventually reach WORKFLOW_OUTPUT",
+        id: "has_actions",
+        name: "Has Actions",
+        description: "Workflow must have at least one action",
         blocking: true,
         severity: "critical",
         check: (workflow) => {
             const actions = (workflow.actions || []);
-            const results = workflow.results;
-            if (!results || Object.keys(results).length === 0) {
-                return { passed: false, message: "No outputs to check" };
-            }
-            // Get all output nodes
-            const outputNodes = new Set(Object.values(results).map((r) => r.actionName));
-            // Build reverse adjacency (who feeds into whom)
-            const feedsInto = new Map();
-            for (const action of actions) {
-                const name = action.name;
-                feedsInto.set(name, new Set());
-                const inputs = action.inputs;
-                if (inputs) {
-                    for (const binding of Object.values(inputs)) {
-                        const bindingObj = binding;
-                        const actionOutput = bindingObj?.actionOutput;
-                        if (actionOutput?.actionName) {
-                            const source = actionOutput.actionName;
-                            if (!feedsInto.has(source)) {
-                                feedsInto.set(source, new Set());
-                            }
-                            feedsInto.get(source).add(name);
-                        }
-                    }
-                }
-            }
-            // Check if each output node is reachable from trigger
-            const reachableFromTrigger = new Set();
-            const queue = ["trigger"];
-            while (queue.length > 0) {
-                const current = queue.shift();
-                if (reachableFromTrigger.has(current))
-                    continue;
-                reachableFromTrigger.add(current);
-                const children = feedsInto.get(current) || new Set();
-                for (const child of children) {
-                    if (!reachableFromTrigger.has(child)) {
-                        queue.push(child);
-                    }
-                }
-            }
-            const unreachableOutputs = Array.from(outputNodes).filter(n => !reachableFromTrigger.has(n));
-            return {
-                passed: unreachableOutputs.length === 0,
-                message: unreachableOutputs.length === 0
-                    ? "All output nodes are reachable from trigger"
-                    : `${unreachableOutputs.length} output node(s) unreachable from trigger`,
-                details: unreachableOutputs.length > 0
-                    ? [`Unreachable: ${unreachableOutputs.join(", ")}`]
-                    : undefined,
-            };
-        },
-    },
-    // ═══════════════════════════════════════════════════════════════════════════
-    // WARNING GATES (Non-blocking but important)
-    // ═══════════════════════════════════════════════════════════════════════════
-    {
-        id: "hitl_for_side_effects",
-        name: "HITL for Side Effects",
-        description: "Actions with external side effects should have human approval",
-        blocking: false,
-        severity: "warning",
-        check: (workflow) => {
-            const actions = (workflow.actions || []);
-            const sideEffectNodes = actions.filter(a => {
-                const actionName = a.action?.name;
-                const name = (actionName?.name || "").toLowerCase();
-                return name.includes("email") ||
-                    name.includes("external") ||
-                    name.includes("create_") ||
-                    name.includes("update_") ||
-                    name.includes("delete_");
-            });
-            const hitlNodes = new Set(actions
-                .filter(a => {
-                const actionName = a.action?.name;
-                const name = (actionName?.name || "").toLowerCase();
-                return name.includes("hitl");
-            })
-                .map(a => a.name));
-            // Check if side effect nodes have HITL upstream
-            const unprotected = sideEffectNodes.filter(a => {
-                const inputs = a.inputs;
-                if (!inputs)
-                    return true;
-                // Check if any input comes from a HITL node
-                for (const binding of Object.values(inputs)) {
-                    const bindingObj = binding;
-                    const actionOutput = bindingObj?.actionOutput;
-                    if (actionOutput?.actionName && hitlNodes.has(actionOutput.actionName)) {
-                        return false;
-                    }
-                }
-                return true;
-            });
-            return {
-                passed: unprotected.length === 0,
-                message: unprotected.length === 0
-                    ? "All side-effect actions have HITL protection"
-                    : `${unprotected.length} side-effect action(s) without HITL approval`,
-                details: unprotected.map(a => `${a.name}: Consider adding human approval before this action`),
-            };
-        },
-    },
-    {
-        id: "categorizer_has_fallback",
-        name: "Categorizer Has Fallback",
-        description: "Intent categorizers should have a Fallback category",
-        blocking: false,
-        severity: "warning",
-        check: (workflow) => {
-            const enumTypes = (workflow.enumTypes || []);
-            const missingFallback = enumTypes.filter(e => {
-                if (!e.values)
-                    return false;
-                return !e.values.some(v => v.name.toLowerCase() === "fallback");
-            });
             return {
-                passed: missingFallback.length === 0,
-                message: missingFallback.length === 0
-                    ? "All categorizers have Fallback category"
-                    : `${missingFallback.length} categorizer(s) missing Fallback`,
-                details: missingFallback.map(e => `${e.name}: Add Fallback category for unmatched intents`),
+                passed: actions.length > 0,
+                message: actions.length > 0
+                    ? `Workflow has ${actions.length} action(s)`
+                    : "Workflow has no actions",
             };
         },
     },
     {
-        id: "no_orphan_nodes",
-        name: "No Orphan Nodes",
-        description: "All nodes should be connected to the workflow",
+        id: "has_results",
+        name: "Has Results Mapping",
+        description: "Voice AI workflows must have results mapping",
         blocking: false,
         severity: "warning",
         check: (workflow) => {
-            const issues = detectWorkflowIssues(workflow);
-            const orphans = issues.filter((i) => i.type === "orphan");
-            return {
-                passed: orphans.length === 0,
-                message: orphans.length === 0
-                    ? "No orphan nodes detected"
-                    : `${orphans.length} orphan node(s) found`,
-                details: orphans.map((i) => `${i.node}: ${i.reason}`),
-            };
-        },
-    },
-    // ═══════════════════════════════════════════════════════════════════════════
-    // INFO GATES (Best practices)
-    // ═══════════════════════════════════════════════════════════════════════════
-    {
-        id: "reasonable_complexity",
-        name: "Reasonable Complexity",
-        description: "Workflow should not be overly complex",
-        blocking: false,
-        severity: "info",
-        check: (workflow) => {
-            const actions = (workflow.actions || []);
-            const nodeCount = actions.length;
-            // Calculate branching factor
-            let branches = 0;
-            for (const action of actions) {
-                const runIf = action.runIf;
-                if (runIf)
-                    branches++;
-            }
-            const isComplex = nodeCount > 20 || branches > 10;
+            const results = workflow.results;
+            const hasResults = results && Object.keys(results).length > 0;
             return {
-                passed: !isComplex,
-                message: isComplex
-                    ? `High complexity: ${nodeCount} nodes, ${branches} conditional branches`
-                    : `Reasonable complexity: ${nodeCount} nodes, ${branches} branches`,
-                details: isComplex
-                    ? ["Consider breaking into smaller sub-workflows for maintainability"]
-                    : undefined,
+                passed: hasResults || false,
+                message: hasResults
+                    ? `Workflow has ${Object.keys(results).length} result mapping(s)`
+                    : "No results mapping found (may be OK for chat workflows)",
             };
         },
     },
 ];
 // ─────────────────────────────────────────────────────────────────────────────
-// Main Entry Point
+// Quality Gate Runner
 // ─────────────────────────────────────────────────────────────────────────────
-/**
- * Run all quality gates on a workflow
- */
-export function runQualityGates(workflow) {
-    const blockingFailures = [];
-    const warnings = [];
-    const passed = [];
-    for (const gate of QUALITY_GATES) {
+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);
-        const report = {
+        results.push({
             gate_id: gate.id,
             gate_name: gate.name,
             result,
+            blocking: gate.blocking,
             severity: gate.severity,
-        };
+        });
         if (!result.passed) {
             if (gate.blocking) {
-                blockingFailures.push(report);
+                blockingFailures++;
             }
-            else {
-                warnings.push(report);
+            else if (gate.severity === "warning") {
+                warnings++;
             }
         }
-        else {
-            passed.push(report);
-        }
     }
-    const overallStatus = blockingFailures.length > 0
-        ? "fail"
-        : warnings.length > 0
-            ? "warning"
-            : "pass";
-    const summary = generateSummary(blockingFailures, warnings, passed);
+    const deploymentAllowed = blockingFailures === 0;
     return {
-        overall_status: overallStatus,
+        overall_status: blockingFailures > 0 ? "fail" : warnings > 0 ? "warning" : "pass",
+        gates: results,
         blocking_failures: blockingFailures,
         warnings,
-        passed,
-        summary,
-        deploy_allowed: blockingFailures.length === 0,
+        deployment_allowed: deploymentAllowed,
     };
 }
-/**
- * Quick check if a workflow passes all blocking gates
- */
-export function canDeploy(workflow) {
-    for (const gate of QUALITY_GATES) {
-        if (gate.blocking) {
-            const result = gate.check(workflow);
-            if (!result.passed) {
-                return false;
-            }
-        }
-    }
-    return true;
-}
-/**
- * Get list of all quality gates
- */
-export function getQualityGates() {
-    return [...QUALITY_GATES];
-}
 // ─────────────────────────────────────────────────────────────────────────────
-// Helpers
+// Utility Functions
 // ─────────────────────────────────────────────────────────────────────────────
-function generateSummary(failures, warnings, passed) {
-    const parts = [];
-    if (failures.length > 0) {
-        parts.push(`🔴 ${failures.length} BLOCKING failure(s): ${failures.map(f => f.gate_name).join(", ")}`);
-    }
-    if (warnings.length > 0) {
-        parts.push(`🟡 ${warnings.length} warning(s): ${warnings.map(w => w.gate_name).join(", ")}`);
-    }
-    if (passed.length > 0) {
-        parts.push(`🟢 ${passed.length} check(s) passed`);
-    }
-    if (failures.length === 0) {
-        parts.push("✅ Workflow is ready for deployment");
-    }
-    else {
-        parts.push("❌ Deployment blocked - fix critical issues first");
-    }
-    return parts.join("\n");
+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}`);
 }
-/**
- * Get a human-readable quality report
- */
 export function formatQualityReport(report) {
-    const lines = [];
-    lines.push("## Quality Gate Report");
-    lines.push("");
-    lines.push(`**Status**: ${report.overall_status.toUpperCase()}`);
-    lines.push(`**Deploy Allowed**: ${report.deploy_allowed ? "Yes ✅" : "No ❌"}`);
-    lines.push("");
-    if (report.blocking_failures.length > 0) {
-        lines.push("### 🔴 Blocking Failures");
-        for (const failure of report.blocking_failures) {
-            lines.push(`- **${failure.gate_name}**: ${failure.result.message}`);
-            if (failure.result.details) {
-                for (const detail of failure.result.details) {
-                    lines.push(`  - ${detail}`);
-                }
+    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`;
             }
         }
-        lines.push("");
-    }
-    if (report.warnings.length > 0) {
-        lines.push("### 🟡 Warnings");
-        for (const warning of report.warnings) {
-            lines.push(`- **${warning.gate_name}**: ${warning.result.message}`);
-            if (warning.result.details) {
-                for (const detail of warning.result.details) {
-                    lines.push(`  - ${detail}`);
-                }
-            }
-        }
-        lines.push("");
-    }
-    if (report.passed.length > 0) {
-        lines.push("### 🟢 Passed");
-        for (const pass of report.passed) {
-            lines.push(`- ${pass.gate_name}`);
-        }
     }
-    lines.push("");
-    lines.push("---");
-    lines.push(report.summary);
-    return lines.join("\n");
+    return output;
 }

package/dist/sdk/validation-rules.js

@@ -255,6 +255,39 @@ export const ANTI_PATTERNS = [
         },
         severity: "critical",
     },
+    {
+        id: "stateless-response-node",
+        name: "Stateless Response Node",
+        pattern: "Response node receives only user_query without chat_conversation",
+        problem: "The final LLM cannot see the conversation history, only the latest message. " +
+            "This causes repeated questions - when user answers 'My DOB is Jan 1, 1980', the LLM " +
+            "doesn't see it asked the question, so it asks again. Multi-turn context is lost.",
+        solution: "Wire trigger.chat_conversation into the response node's named_inputs or history input. " +
+            "The LLM needs to see the full conversation transcript to maintain context.",
+        detection: {
+            issueType: "stateless_response",
+            condition: "Response node (respond_for_external_actions, respond_with_sources, call_llm as responder) " +
+                "receives trigger.user_query but NOT trigger.chat_conversation",
+        },
+        severity: "warning",
+    },
+    {
+        id: "search-without-data-sources",
+        name: "Search Without Data Sources",
+        pattern: "Workflow has search node but no data sources uploaded",
+        problem: "The workflow includes a search/v2 node to query knowledge base, but no documents have been " +
+            "uploaded to the persona. Search will return empty results, making the RAG workflow useless. " +
+            "The AI will have no context to answer questions.",
+        solution: "Upload data sources BEFORE deploying or testing the workflow:\n" +
+            "1. persona(id='...', data={method:'upload', path:'/path/to/document.pdf'})\n" +
+            "2. Enable embedding if not already: persona(id='...', data={method:'embedding', enabled:true})\n" +
+            "3. Wait for indexing to complete: persona(id='...', data={method:'stats'}) → check 'success' count",
+        detection: {
+            issueType: "search_without_data",
+            condition: "Workflow contains search/v2 node AND persona has 0 data sources uploaded (check via data.stats)",
+        },
+        severity: "critical",
+    },
 ];
 export const OPTIMIZATION_RULES = [
     {