@ema.co/mcp-toolkit 1.5.1 → 1.6.0

package/dist/sdk/generated/api-types.js

@@ -0,0 +1,11 @@
+/**
+ * Auto-generated TypeScript types from Ema Platform OpenAPI spec.
+ * Generated from: Ema Platform API v1.0.0
+ * Generated at: 2026-01-16T13:46:50.729Z
+ *
+ * DO NOT EDIT MANUALLY - regenerate with: npm run generate:types
+ */
+export {};
+// ─────────────────────────────────────────────────────────────────────────────
+// API Operation Types
+// ─────────────────────────────────────────────────────────────────────────────

package/dist/sdk/index.js

@@ -33,8 +33,14 @@ export {
 compileWorkflow, 
 // Settings builders
 buildVoiceConfig, buildChatConfig, } from "./workflow-generator.js";
+// Action Registry (API-driven action/template definitions)
+export { ActionRegistry, ensureActionRegistry, parseActionDefinition, parseTemplateDefinition, } from "./action-registry.js";
 // Workflow Intent (Normalization layer)
-export { parseInput, validateIntent, intentToSpec, detectInputType, parseNaturalLanguage, parsePartialSpec, } from "./workflow-intent.js";
+export { parseInput, validateIntent, intentToSpec, detectInputType, parseNaturalLanguage, parsePartialSpec, 
+// LLM-driven generation
+needsLLMGeneration, generateWorkflow, parseWorkflowSpecFromLLM, } from "./workflow-intent.js";
+// Workflow Validator (API-driven validation)
+export { APISchemaRegistry, ensureSchemaRegistry, getSchemaRegistry, validateWorkflowSpec, generateActionCatalogForLLM, generateTemplateCatalogForLLM, } from "./workflow-validator.js";
 // Generation Schema (Compact format for LLM-based generation)
 export { generateSchema, generateSchemaMarkdown, buildCompactAgents, buildTypeRules, buildConstraints, getAgentSchema, isTypeCompatible, getRecommendedInput, } from "./generation-schema.js";
 // Version Tracking (Persona version history management)
@@ -49,3 +55,11 @@ export { VersionPolicyEngine, createVersionPolicyEngine, } from "./version-polic
 export { analyzeExecutionFlow, detectLoops, detectMultipleResponders, detectRedundantClassifiers, analyzeDataFlow, findDeadCodePaths, generateASCIIFlow, } from "./workflow-execution-analyzer.js";
 // Workflow Fixer (Auto-fix including multiple responder issues)
 export { autoFixWorkflow, suggestFixes, } from "./workflow-fixer.js";
+// Workflow Optimizer (Health scoring & optimization recommendations)
+export { analyzeOptimizations, summarizeOptimizationReport, } from "./workflow-optimizer.js";
+// Workflow Tracer (Flow visualization & path analysis)
+export { traceWorkflow, generateDetailedTrace, formatFlowTrace, formatDetailedTrace, } from "./workflow-tracer.js";
+// Quality Gates (Pre-deploy validation)
+export { runQualityGates, canDeploy, getQualityGates, formatQualityReport, } from "./quality-gates.js";
+// Structural Rules (LLM validation context)
+export { STRUCTURAL_RULES_FOR_LLM, STRUCTURAL_INVARIANTS, EXECUTION_RULES, COMMON_STRUCTURAL_MISTAKES, getAllStructuralRules, getInvariantById, getCriticalInvariants, } from "./structural-rules.js";

package/dist/sdk/knowledge.js

@@ -1019,6 +1019,7 @@ export const COMMON_MISTAKES = [
     { mistake: "Missing Fallback category", problem: "Workflow validation fails, unhandled intents", solution: "ALWAYS include Fallback category in every categorizer" },
     { mistake: "Type mismatches in connections", problem: "Validation errors, runtime failures", solution: "Check type compatibility: use conversation_to_search_query when needed" },
     { mistake: "Not mapping to WORKFLOW_OUTPUT", problem: "Responses don't reach user", solution: "Ensure ALL paths terminate at WORKFLOW_OUTPUT" },
+    { mistake: "Using workflow_def instead of workflow in updates", problem: "API accepts request but changes silently don't persist", solution: "Use 'workflow' field (not 'workflow_def') in updateAiEmployee(). GET returns workflow_def, UPDATE expects workflow." },
 ];
 export const DEBUG_CHECKLIST = [
     { step: 1, action: "Check Status", description: "Is the AI Employee active/ready?", apiField: "status" },
@@ -2072,17 +2073,34 @@ function detectCategorizerIssues(nodes) {
                 reason: `Categorizer "${categorizer.id}" has no outgoing category edges - routing won't work`,
             });
         }
-        // Check for Fallback - look for edges or enumType options
+        // Check for Fallback - multiple ways to configure:
+        // 1. default_category input set to a fallback-like value
+        // 2. Outgoing edges with "fallback" in the source_output
+        // 3. Category handlers wired to fallback output
         let hasFallback = false;
-        for (const node of nodes) {
-            if (node.incoming_edges) {
-                for (const edge of node.incoming_edges) {
-                    if (edge.source_node_id === categorizer.id &&
-                        (edge.source_output?.toLowerCase().includes("fallback"))) {
-                        hasFallback = true;
-                        break;
+        // Check default_category input (most common way to set fallback)
+        const params = categorizer.parameters;
+        if (params?.default_category) {
+            const defaultCat = params.default_category;
+            const defaultValue = defaultCat?.inline?.enumValue?.toLowerCase() || "";
+            if (defaultValue && ["fallback", "other", "general", "unknown", "default"].includes(defaultValue)) {
+                hasFallback = true;
+            }
+        }
+        // Also check for edges with fallback in the name
+        if (!hasFallback) {
+            for (const node of nodes) {
+                if (node.incoming_edges) {
+                    for (const edge of node.incoming_edges) {
+                        if (edge.source_node_id === categorizer.id &&
+                            (edge.source_output?.toLowerCase().includes("fallback"))) {
+                            hasFallback = true;
+                            break;
+                        }
                     }
                 }
+                if (hasFallback)
+                    break;
             }
         }
         if (!hasFallback && outgoing.size > 0) {
@@ -2191,10 +2209,22 @@ function detectWrongInputSource(nodes) {
         const rule = findInputSourceRule(actionName);
         if (!rule)
             continue;
+        // For send_email nodes, the rule only applies to email_to/recipient inputs
+        // Other inputs (subject, body) can legitimately use LLM/text outputs
+        const isEmailNode = actionName.includes("email") || actionName.includes("send_email");
         if (node.incoming_edges) {
             for (const edge of node.incoming_edges) {
                 const sourceOutput = edge.source_output?.toLowerCase() ?? "";
                 const targetInput = edge.target_input?.toLowerCase() ?? "";
+                // For email nodes, only check the email_to/recipient input, not all inputs
+                if (isEmailNode) {
+                    const isRecipientInput = targetInput.includes("email_to") ||
+                        targetInput.includes("to_email") ||
+                        targetInput.includes("recipient") ||
+                        targetInput.includes("to_address");
+                    if (!isRecipientInput)
+                        continue; // Skip non-recipient inputs for email nodes
+                }
                 // Check if using an avoided input
                 for (const avoid of rule.avoid) {
                     if (sourceOutput.includes(avoid.toLowerCase()) ||

package/dist/sdk/quality-gates.js

@@ -0,0 +1,386 @@
+/**
+ * Quality Gates - Pre-Deploy Validation
+ *
+ * Ensures workflows meet minimum quality standards before deployment.
+ * These are the "guardrails" that prevent broken workflows from going live.
+ */
+import { detectWorkflowIssues } from "./knowledge.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Quality Gate Definitions
+// ─────────────────────────────────────────────────────────────────────────────
+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}`),
+            };
+        },
+    },
+    {
+        id: "all_paths_reach_output",
+        name: "All Paths Reach Output",
+        description: "Every branch from trigger must eventually reach WORKFLOW_OUTPUT",
+        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`),
+            };
+        },
+    },
+    {
+        id: "no_orphan_nodes",
+        name: "No Orphan Nodes",
+        description: "All nodes should be connected to the workflow",
+        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;
+            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,
+            };
+        },
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Entry Point
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Run all quality gates on a workflow
+ */
+export function runQualityGates(workflow) {
+    const blockingFailures = [];
+    const warnings = [];
+    const passed = [];
+    for (const gate of QUALITY_GATES) {
+        const result = gate.check(workflow);
+        const report = {
+            gate_id: gate.id,
+            gate_name: gate.name,
+            result,
+            severity: gate.severity,
+        };
+        if (!result.passed) {
+            if (gate.blocking) {
+                blockingFailures.push(report);
+            }
+            else {
+                warnings.push(report);
+            }
+        }
+        else {
+            passed.push(report);
+        }
+    }
+    const overallStatus = blockingFailures.length > 0
+        ? "fail"
+        : warnings.length > 0
+            ? "warning"
+            : "pass";
+    const summary = generateSummary(blockingFailures, warnings, passed);
+    return {
+        overall_status: overallStatus,
+        blocking_failures: blockingFailures,
+        warnings,
+        passed,
+        summary,
+        deploy_allowed: blockingFailures.length === 0,
+    };
+}
+/**
+ * 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
+// ─────────────────────────────────────────────────────────────────────────────
+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");
+}
+/**
+ * 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}`);
+                }
+            }
+        }
+        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");
+}