@ema.co/mcp-toolkit 2026.2.5 → 2026.2.19

package/dist/mcp/domain/validation-rules.js

@@ -135,7 +135,7 @@ export const ANTI_PATTERNS = [
         pattern: "send_email_agent without entity_extraction to validate recipient data",
         problem: "Sending emails without extracting and validating recipient data risks sending to wrong people or with wrong content. Emails are high-impact actions with external side effects.",
         solution: "Always: 1) Extract required fields (email_address, subject) via entity_extraction, 2) Validate completeness via categorizer, 3) Ask user if missing. " +
-            "For approval: enable the HITL flag on send_email_agent (do NOT add a standalone general_hitl node).",
+            "For approval: enable the HITL flag on send_email_agent (disable_human_interaction: false). general_hitl is NOT deployable.",
         detection: {
             issueType: "incomplete_email_validation",
             condition: "send_email_agent without preceding entity_extraction node to extract/validate recipient data",
@@ -195,15 +195,15 @@ export const ANTI_PATTERNS = [
         name: "Incomplete HITL Paths",
         pattern: "HITL with only success path",
         problem: "Rejected requests have no handling, leaving users without response.",
-        solution: "If workflow already has general_hitl node: ALWAYS implement both success AND failure paths. For NEW workflows: use HITL flag on the agent instead of standalone general_hitl nodes (see hitl-patterns guidance).",
+        solution: "If workflow already has general_hitl node: ALWAYS implement both success AND failure paths. For NEW workflows: use HITL flag on the agent (only entity_extraction_with_documents and send_email_agent support HITL). general_hitl is NOT deployable.",
         detection: {
             issueType: "incomplete_hitl",
             condition: "HITL node missing 'hitl_status_HITL Success' or 'hitl_status_HITL Failure' edge (note: space, not underscore)",
         },
         severity: "critical",
-        // TODO: Revisit if general_hitl is re-enabled as a standalone node.
-        // Currently HITL is a flag on agents (send_email_agent, external_action_caller).
-        // This anti-pattern still fires for existing workflows that use general_hitl.
+        // general_hitl is NOT deployable — it appears in catalogs but cannot be deployed.
+        // HITL is a flag on entity_extraction_with_documents and send_email_agent only.
+        // external_action_caller does NOT support HITL. This rule still fires for legacy workflows.
     },
     {
         id: "orphan-nodes",
@@ -255,13 +255,15 @@ export const ANTI_PATTERNS = [
     },
     {
         id: "missing-workflow-output",
-        name: "Missing WORKFLOW_OUTPUT",
-        pattern: "Response nodes not connected to WORKFLOW_OUTPUT",
-        problem: "Responses never reach the user.",
-        solution: "Connect all terminal response nodes to WORKFLOW_OUTPUT.",
+        name: "Missing results Mapping",
+        pattern: "Action outputs not mapped in workflow results",
+        problem: "Outputs never reach the user or dashboard.",
+        solution: "Chat/Voice: map terminal response nodes to WORKFLOW_OUTPUT. " +
+            "Dashboard: map extraction/validation outputs using dot-notation keys " +
+            "(e.g., 'extraction_node.extraction_columns': { actionName: '...', outputName: 'extraction_columns' }).",
         detection: {
             issueType: "missing_workflow_output",
-            condition: "No WORKFLOW_OUTPUT node, or response nodes not connected to it",
+            condition: "No results mapping, or terminal output nodes not connected to results",
         },
         severity: "critical",
     },
@@ -439,30 +441,30 @@ export const ANTI_PATTERNS = [
     {
         id: "chat-conversation-without-chat-response",
         name: "Chat Conversation Not Wired to Chat Response Node",
-        pattern: "Chat workflow where chat_conversation is consumed by processing nodes but never wired to a chat-aware response node (respond_with_sources or respond_for_external_actions)",
+        pattern: "Chat workflow where chat_conversation is consumed by processing nodes but never wired to a chat-aware response node (respond_for_external_actions)",
         problem: "When chat_conversation is processed by nodes like entity_extraction, call_llm, or search, " +
             "but the final response is generated by a generic call_llm (not a chat-aware response node), " +
             "the response node lacks conversation history context. This causes:\n" +
             "1. Duplicate/repetitive responses — the LLM re-asks questions already answered in conversation\n" +
             "2. Lost context — follow-up messages lose prior context\n" +
             "3. Hallucinated greetings — the LLM generates its own greeting instead of continuing the conversation\n\n" +
-            "The chat-aware response nodes (respond_with_sources, respond_for_external_actions) are specifically " +
-            "designed to handle conversation history and produce contextually appropriate responses.",
+            "The respond_for_external_actions node is specifically designed to handle conversation history " +
+            "and produce contextually appropriate responses (replacing the deprecated respond_with_sources).",
         solution: "Wire chat_conversation through to a chat-aware response node:\n" +
-            "• For search-based responses: use respond_with_sources (takes query + search_results)\n" +
-            "• For tool/action results: use respond_for_external_actions (takes query + external_action_result)\n" +
+            "• For search results or tool/action results: use respond_for_external_actions (takes query + conversation + external_action_result)\n" +
             "• If using call_llm as responder: wire chat_conversation into named_inputs so the LLM sees full history\n\n" +
             "Correct patterns:\n" +
-            "  chat_trigger → search → respond_with_sources → WORKFLOW_OUTPUT\n" +
+            "  chat_trigger → search → respond_for_external_actions → WORKFLOW_OUTPUT\n" +
             "  chat_trigger → external_action_caller → respond_for_external_actions → WORKFLOW_OUTPUT\n" +
             "  chat_trigger → call_llm(named_inputs includes chat_conversation) → WORKFLOW_OUTPUT\n\n" +
             "Anti-patterns:\n" +
             "  ❌ chat_trigger → search → call_llm (no conversation context) → WORKFLOW_OUTPUT\n" +
-            "  ❌ chat_trigger → entity_extraction → call_llm (stateless) → WORKFLOW_OUTPUT",
+            "  ❌ chat_trigger → entity_extraction → call_llm (stateless) → WORKFLOW_OUTPUT\n" +
+            "  ❌ chat_trigger → search → respond_with_sources (DEPRECATED) → WORKFLOW_OUTPUT",
         detection: {
             issueType: "chat_conversation_not_wired_to_response",
             condition: "Chat workflow (chat_trigger) where terminal response node is call_llm without chat_conversation in named_inputs, " +
-                "and respond_with_sources / respond_for_external_actions are not used",
+                "and respond_for_external_actions is not used",
         },
         severity: "critical",
     },
@@ -494,6 +496,75 @@ export const ANTI_PATTERNS = [
         },
         severity: "critical",
     },
+    {
+        id: "partial-output-wiring",
+        name: "Gated Respond Nodes Missing WORKFLOW_OUTPUT Wiring",
+        pattern: "Multiple call_llm/respond nodes gated by categorizer (trigger_when/runIf), but only some connected to WORKFLOW_OUTPUT",
+        problem: "When intent routing gates multiple respond nodes via trigger_when, ALL branches must wire to WORKFLOW_OUTPUT. " +
+            "If only one branch is wired (e.g., get_respond → WORKFLOW_OUTPUT but schedule_respond is not), " +
+            "the other branches execute and produce responses that are silently lost — the user gets no reply for those intents.",
+        solution: "Ensure every gated respond node maps to WORKFLOW_OUTPUT:\n\n" +
+            "Option A — Wire all respond nodes to WORKFLOW_OUTPUT:\n" +
+            "  get_respond.response_with_sources → WORKFLOW_OUTPUT\n" +
+            "  schedule_respond.response_with_sources → WORKFLOW_OUTPUT\n" +
+            "  reschedule_respond.response_with_sources → WORKFLOW_OUTPUT\n" +
+            "  fallback.response → WORKFLOW_OUTPUT\n\n" +
+            "Option B — Consolidate into a single respond node that receives the category as named_input:\n" +
+            "  categorizer.category → call_llm.named_inputs_Intent\n" +
+            "  call_llm.response_with_sources → WORKFLOW_OUTPUT\n\n" +
+            "Option B is preferred when all branches share similar prompts and differ only by intent.",
+        detection: {
+            issueType: "partial_output_wiring",
+            condition: "Workflow has categorizer/router with multiple gated call_llm/respond nodes, " +
+                "but not all of them are mapped to WORKFLOW_OUTPUT resultMappings",
+        },
+        severity: "critical",
+    },
+    {
+        id: "duplicate-identical-llm-nodes",
+        name: "Duplicate LLM Nodes Differing Only by Gate",
+        pattern: "Multiple call_llm nodes with identical inputs (query, named_inputs, instructions) that differ only in trigger_when",
+        problem: "When several call_llm nodes share the same prompt, search results, and conversation inputs — " +
+            "differing only in their trigger_when condition — the workflow has unnecessary complexity. " +
+            "Each duplicate requires separate output wiring, separate prompt maintenance, and increases " +
+            "the risk of partial-output-wiring bugs (one branch silently loses responses).",
+        solution: "Consolidate into a single call_llm node and pass the intent as context:\n\n" +
+            "1. Remove the duplicate respond nodes\n" +
+            "2. Create one call_llm node that always runs (or runs when not Fallback)\n" +
+            "3. Wire categorizer.category → call_llm.named_inputs_Intent\n" +
+            "4. Update the prompt to: 'Based on the detected intent ({{Intent}}), respond accordingly'\n" +
+            "5. Wire the single call_llm.response_with_sources → WORKFLOW_OUTPUT\n\n" +
+            "Keep separate nodes ONLY when intents require different tools, search sources, or safety constraints.",
+        detection: {
+            issueType: "duplicate_identical_llm_nodes",
+            condition: "Two or more call_llm nodes with same query source, same named_inputs (search results, conversation), " +
+                "and only trigger_when differs",
+        },
+        severity: "warning",
+    },
+    {
+        id: "overscoped-extraction-inputs",
+        name: "Extraction Nodes Receiving Excessive Context",
+        pattern: "Entity extraction call_llm nodes wired to full search_results and conversation when only current_message is needed",
+        problem: "When extracting specific entities (emails, dates, IDs) from the user's current message, " +
+            "passing full search_results and complete conversation history increases token usage and " +
+            "can cause hallucinated extractions — the model may 'find' entities in search results " +
+            "that weren't in the user's actual message.",
+        solution: "Scope extraction inputs to the minimum needed:\n\n" +
+            "For extracting from user's current message:\n" +
+            "  ✅ trigger.user_query → extract.named_inputs_Current_Message\n" +
+            "  ❌ search.search_results → extract.named_inputs_Search_Results (unnecessary)\n\n" +
+            "For extracting from documents/search results:\n" +
+            "  ✅ search.search_results → extract.named_inputs_Documents (intentional)\n" +
+            "  Use entity_extraction_with_documents instead of call_llm for grounded extraction\n\n" +
+            "Include conversation only when entity might span multiple turns (e.g., user gave email 3 messages ago).",
+        detection: {
+            issueType: "overscoped_extraction_inputs",
+            condition: "call_llm node configured for extraction (prompt mentions 'extract') " +
+                "receives search_results when extraction target is in user_query",
+        },
+        severity: "info",
+    },
 ];
 export const OPTIMIZATION_RULES = [
     {
@@ -516,8 +587,8 @@ export const OPTIMIZATION_RULES = [
         id: "use-purpose-built",
         name: "Use Purpose-Built Response Nodes",
         currentState: "Using call_llm for search-based responses",
-        recommendation: "Use respond_with_sources instead - it has built-in citation handling",
-        benefit: "Better citations, grounded responses, less configuration",
+        recommendation: "Use respond_for_external_actions instead - it has built-in citation handling and conversation awareness (respond_with_sources is deprecated)",
+        benefit: "Better citations, grounded responses, conversation context, less configuration",
         priority: "medium",
     },
     {
@@ -528,6 +599,22 @@ export const OPTIMIZATION_RULES = [
         benefit: "Reduced token usage, faster processing",
         priority: "low",
     },
+    {
+        id: "consolidate-respond-nodes",
+        name: "Consolidate Identical Respond Nodes",
+        currentState: "Multiple call_llm respond nodes with same inputs (query, search_results, conversation) differing only by trigger_when gate",
+        recommendation: "Replace with single call_llm that receives categorizer.category as named_inputs_Intent, with prompt adapting by intent",
+        benefit: "Single output wiring to WORKFLOW_OUTPUT, single prompt to maintain, eliminates partial-output-wiring bugs",
+        priority: "high",
+    },
+    {
+        id: "scope-extraction-inputs",
+        name: "Scope Extraction Inputs to Minimum Needed",
+        currentState: "Extraction nodes (call_llm for entity extraction) receiving full search_results and conversation when only user_query is needed",
+        recommendation: "Wire only trigger.user_query to extraction nodes. Add conversation only when entity may span multiple turns.",
+        benefit: "Reduced token usage, fewer hallucinated extractions from irrelevant context",
+        priority: "medium",
+    },
 ];
 // ─────────────────────────────────────────────────────────────────────────────
 // Helper Functions

package/dist/mcp/domain/workflow-graph-optimizer.js

@@ -0,0 +1,235 @@
+/**
+ * Workflow Graph Optimizer Orchestrator
+ *
+ * Ties the graph and transforms together into a single `optimizeWorkflow()` function.
+ * Pure function — never mutates input, never throws, no side effects.
+ */
+import { buildWorkflowGraph, getReachableNodes, getTopologicalOrder, } from "./workflow-graph.js";
+import { AUTO_TRANSFORMS, ADVISORY_TRANSFORMS, } from "./workflow-graph-transforms.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+function calculateMetrics(workflowDef, graph) {
+    const nodeCount = graph.nodes.size;
+    const edgeCount = graph.edges.length;
+    // Dead nodes: total - reachable from trigger
+    const reachable = getReachableNodes(graph);
+    const deadNodes = nodeCount - reachable.size;
+    // Cycles: if topological order cannot include all nodes, there are cycles
+    const topoOrder = getTopologicalOrder(graph);
+    const cycles = nodeCount > 0 && topoOrder.length < nodeCount
+        ? nodeCount - topoOrder.length
+        : 0;
+    return { nodeCount, edgeCount, deadNodes, cycles };
+}
+function generateImprovementSummary(before, after) {
+    const parts = [];
+    const removedDead = before.deadNodes - after.deadNodes;
+    if (removedDead > 0) {
+        parts.push(`Removed ${removedDead} dead node${removedDead > 1 ? "s" : ""}`);
+    }
+    const brokenCycles = before.cycles - after.cycles;
+    if (brokenCycles > 0) {
+        parts.push(`broke ${brokenCycles} cycle${brokenCycles > 1 ? "s" : ""}`);
+    }
+    const removedNodes = before.nodeCount - after.nodeCount;
+    if (removedNodes > 0 && removedDead === 0) {
+        parts.push(`Removed ${removedNodes} node${removedNodes > 1 ? "s" : ""}`);
+    }
+    const removedEdges = before.edgeCount - after.edgeCount;
+    if (removedEdges > 0) {
+        parts.push(`removed ${removedEdges} edge${removedEdges > 1 ? "s" : ""}`);
+    }
+    if (parts.length === 0) {
+        return "No changes needed.";
+    }
+    let summary = parts.join(", ");
+    summary += `. ${before.nodeCount} \u2192 ${after.nodeCount} nodes.`;
+    return summary;
+}
+function validateWorkflow(workflowDef) {
+    const errors = [];
+    const warnings = [];
+    // Check actions array exists and is non-empty
+    const actions = workflowDef?.actions;
+    if (!actions || !Array.isArray(actions)) {
+        errors.push("Workflow has no actions array");
+        return { valid: false, errors, warnings };
+    }
+    if (actions.length === 0) {
+        errors.push("Workflow actions array is empty");
+        return { valid: false, errors, warnings };
+    }
+    // Check all nodes have name and action fields
+    for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        if (!action || typeof action !== "object") {
+            errors.push(`Action at index ${i} is not an object`);
+            continue;
+        }
+        if (!action.name) {
+            errors.push(`Action at index ${i} has no name`);
+        }
+        if (!action.action) {
+            errors.push(`Action "${action.name ?? `index ${i}`}" has no action definition`);
+        }
+    }
+    // Check results object exists
+    if (!workflowDef.results || typeof workflowDef.results !== "object") {
+        warnings.push("Workflow has no results object");
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Entry Point
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Optimize a workflow_def by applying auto-transforms and collecting advisories.
+ *
+ * Pure function: never mutates input, never throws.
+ */
+export function optimizeWorkflow(workflowDef, options) {
+    const autoApply = options?.autoApply ?? true;
+    const maxPasses = options?.maxPasses ?? 5;
+    // Graceful handling of invalid input
+    if (!workflowDef || typeof workflowDef !== "object") {
+        return {
+            workflowDef: workflowDef ?? {},
+            modified: false,
+            appliedTransforms: [],
+            advisories: [],
+            metrics: {
+                before: { nodeCount: 0, edgeCount: 0, deadNodes: 0, cycles: 0 },
+                after: { nodeCount: 0, edgeCount: 0, deadNodes: 0, cycles: 0 },
+                improvement: "No changes needed.",
+            },
+            validation: { valid: false, errors: ["Invalid workflow_def input"], warnings: [] },
+        };
+    }
+    try {
+        // Step 1: Deep-clone input (never mutate)
+        let currentWorkflowDef = deepClone(workflowDef);
+        // Step 2: Calculate "before" metrics
+        let graph = buildWorkflowGraph(currentWorkflowDef);
+        const beforeMetrics = calculateMetrics(currentWorkflowDef, graph);
+        // Step 3: Auto-apply transforms (convergence loop)
+        const appliedTransforms = [];
+        if (autoApply && maxPasses > 0) {
+            for (let pass = 0; pass < maxPasses; pass++) {
+                let anyApplied = false;
+                for (const transform of AUTO_TRANSFORMS) {
+                    try {
+                        const result = transform.apply(currentWorkflowDef, graph);
+                        if (result && result.applied) {
+                            currentWorkflowDef = result.workflowDef;
+                            graph = buildWorkflowGraph(currentWorkflowDef);
+                            appliedTransforms.push({
+                                transformId: transform.id,
+                                description: result.description,
+                                nodesRemoved: result.nodesRemoved,
+                                nodesModified: result.nodesModified,
+                            });
+                            anyApplied = true;
+                        }
+                    }
+                    catch {
+                        // Individual transform failure: skip, continue with others
+                    }
+                }
+                if (!anyApplied)
+                    break; // Converged
+            }
+        }
+        // Step 4: Calculate "after" metrics
+        graph = buildWorkflowGraph(currentWorkflowDef);
+        const afterMetrics = calculateMetrics(currentWorkflowDef, graph);
+        // Step 5: Run advisory transforms
+        const advisories = [];
+        for (const transform of ADVISORY_TRANSFORMS) {
+            try {
+                const result = transform.apply(currentWorkflowDef, graph);
+                if (result && !result.applied) {
+                    // Advisory: applied=false means it's a finding, not a fix
+                    // Extract affected nodes from the description or result fields
+                    const affectedNodes = extractAffectedNodes(result);
+                    advisories.push({
+                        id: transform.id,
+                        description: result.description,
+                        affectedNodes,
+                    });
+                }
+            }
+            catch {
+                // Advisory failure: skip
+            }
+        }
+        // Step 6: Generate improvement summary
+        const improvement = generateImprovementSummary(beforeMetrics, afterMetrics);
+        // Step 7: Post-optimization validation
+        const validation = validateWorkflow(currentWorkflowDef);
+        return {
+            workflowDef: currentWorkflowDef,
+            modified: appliedTransforms.length > 0,
+            appliedTransforms,
+            advisories,
+            metrics: {
+                before: beforeMetrics,
+                after: afterMetrics,
+                improvement,
+            },
+            validation,
+        };
+    }
+    catch {
+        // Top-level safety net: never throw
+        return {
+            workflowDef: deepClone(workflowDef),
+            modified: false,
+            appliedTransforms: [],
+            advisories: [],
+            metrics: {
+                before: { nodeCount: 0, edgeCount: 0, deadNodes: 0, cycles: 0 },
+                after: { nodeCount: 0, edgeCount: 0, deadNodes: 0, cycles: 0 },
+                improvement: "No changes needed.",
+            },
+            validation: { valid: false, errors: ["Optimization failed unexpectedly"], warnings: [] },
+        };
+    }
+}
+/**
+ * Extract affected node IDs from a transform result.
+ * Combines nodesRemoved and nodesModified, falling back to parsing description.
+ */
+function extractAffectedNodes(result) {
+    const nodes = new Set();
+    for (const n of result.nodesRemoved)
+        nodes.add(n);
+    for (const n of result.nodesModified)
+        nodes.add(n);
+    for (const n of result.nodesAdded)
+        nodes.add(n);
+    // If no nodes found from fields, try to extract from description
+    if (nodes.size === 0 && result.description) {
+        // Match quoted node names in descriptions like: search_1 <-> search_2
+        const matches = result.description.match(/\b[a-zA-Z_][a-zA-Z0-9_]*\b/g);
+        if (matches) {
+            // Filter out common English words to keep only node-like identifiers
+            const commonWords = new Set([
+                "Found", "pair", "pairs", "of", "similar", "nodes", "with", "the",
+                "same", "action", "type", "but", "different", "inputs", "Categorizer",
+                "has", "only", "non", "Fallback", "category", "branching", "adds",
+                "no", "value", "Nested", "categorizer", "chain", "consider",
+                "flattening", "a", "and", "or", "is", "in", "for",
+            ]);
+            for (const m of matches) {
+                if (!commonWords.has(m) && m.length > 2) {
+                    nodes.add(m);
+                }
+            }
+        }
+    }
+    return [...nodes];
+}