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

package/dist/sdk/workflow-fixer.js

@@ -1,379 +1,48 @@
 /**
  * Workflow Fixer (SDK)
  *
- * Self-contained auto-detection and fixing of workflow issues.
- * Call autoFixWorkflow() with just a workflow_def for one-call fixing.
+ * DEPRECATED: This module used detectWorkflowIssues which has been removed.
  *
- * Automatically fixes:
- * - Orphan node removal
- * - Email recipient rewiring to entity_extraction
- * - Missing fallback addition
- * - Multiple responder detection
- * - Ungated responder detection
+ * The LLM should analyze workflows using rules from:
+ * - ema://rules/anti-patterns
+ * - ema://rules/input-sources
+ * - ema://rules/optimizations
  *
- * NOTE: This is DIFFERENT from server.ts applyWorkflowFixes():
+ * And then make structured modifications via:
+ * - workflow(mode="deploy", workflow_def={...})
+ * - persona(mode="update", operations=[...])
  *
- * - autoFixWorkflow() (HERE): Self-contained, auto-detects issues, no persona
- *   context needed. Best for SDK consumers who want autonomous fixing.
- *
- * - applyWorkflowFixes() (MCP): Takes pre-detected issues AND persona for
- *   Voice AI specific fixes (results mapping, HITL paths). Used by MCP handlers.
- *
- * These are COMPLEMENTARY, not duplicates. Use autoFixWorkflow() for SDK usage,
- * use applyWorkflowFixes() when you have persona context and pre-analyzed issues.
+ * This file is kept for backwards compatibility with minimal functionality.
  */
-import { detectWorkflowIssues } from "./knowledge.js";
-import { detectMultipleResponders } from "./workflow-execution-analyzer.js";
 // ═══════════════════════════════════════════════════════════════════════════
-// FIX FUNCTIONS
+// DEPRECATED FUNCTIONS (no-ops)
 // ═══════════════════════════════════════════════════════════════════════════
 /**
- * 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,
-    };
-}
-/**
- * Generate a unique node ID with random suffix
- */
-function generateNodeId(prefix) {
-    const suffix = Math.random().toString(36).substring(2, 8);
-    return `${prefix}_${suffix}`;
-}
-/**
- * Create a convert_to_text action node
- * This bridges EXTRACTION_COLUMN → TEXT_WITH_SOURCES
- */
-function createConvertToTextNode(nodeId, sourceActionName, sourceOutput, displayName) {
-    return {
-        name: nodeId,
-        action: {
-            name: { namespaces: ['actions', 'emainternal'], name: 'convert_to_text' },
-            version: 'v0',
-        },
-        inputs: {
-            named_inputs: {
-                inline: {
-                    array: {
-                        values: [{
-                                named: {
-                                    name: 'email_address',
-                                    value: {
-                                        actionOutput: {
-                                            actionName: sourceActionName,
-                                            output: sourceOutput,
-                                        },
-                                    },
-                                    description: 'Email address from entity extraction',
-                                },
-                            }],
-                    },
-                },
-            },
-        },
-        displaySettings: {
-            displayName,
-            description: 'Convert extraction output to text for email',
-            coordinates: { x: 600, y: 300 },
-            showConfig: 0,
-        },
-        typeArguments: {},
-        tools: [],
-        disableHumanInteraction: true,
-    };
-}
-/**
- * Find email column name from entity_extraction node configuration
- */
-function findEmailColumnName(extractionNode) {
-    const inputs = extractionNode.inputs;
-    if (!inputs)
-        return undefined;
-    const extractionColumnsInput = inputs.extraction_columns;
-    const columns = extractionColumnsInput?.inline?.array?.values || [];
-    for (const col of columns) {
-        const name = col.wellKnown?.extractionColumn?.name?.toLowerCase() || '';
-        if (name.includes('email') || name.includes('mail')) {
-            return col.wellKnown?.extractionColumn?.name;
-        }
-    }
-    return undefined;
-}
-/**
- * Fix wrong email recipient sources by inserting convert_to_text nodes
+ * DEPRECATED: Auto-fix workflow issues.
+ *
+ * This function now returns the workflow unchanged with a deprecation warning.
+ * Use LLM analysis with ema://rules/* instead.
  */
-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 actionsSource = workflowDef.actions || workflowDef.nodes || [];
-    const actions = (Array.isArray(actionsSource) ? [...actionsSource] : []);
-    const newNodes = [];
-    // 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';
-    });
-    const entityExtractionNodeNames = entityExtractionNodes
-        .map((a) => a.name)
-        .filter(Boolean);
-    if (entityExtractionNodeNames.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 };
-    }
-    // Track which convert_to_text nodes we've created (to reuse for same source)
-    const converterNodes = new Map(); // "source.output" -> converterId
-    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 anyFixed = 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 targetExtractionName = entityExtractionNodeNames[0];
-            const targetExtractionNode = entityExtractionNodes.find((n) => n.name === targetExtractionName);
-            // Find the email column name from the extraction node config
-            const emailColumnName = findEmailColumnName(targetExtractionNode) || 'Email';
-            // Create or reuse a convert_to_text node
-            const converterKey = `${targetExtractionName}.${emailColumnName}`;
-            let converterId = converterNodes.get(converterKey);
-            if (!converterId) {
-                converterId = generateNodeId('convert_email');
-                converterNodes.set(converterKey, converterId);
-                // Create the new convert_to_text node
-                const converterNode = createConvertToTextNode(converterId, targetExtractionName, emailColumnName, `Convert ${emailColumnName} to Text`);
-                newNodes.push(converterNode);
-            }
-            // Rewire the email input to use the converter's output
-            inputs[inputName] = {
-                actionOutput: {
-                    actionName: converterId,
-                    output: 'text_with_sources',
-                },
-            };
-            usedNodes.add(targetExtractionName);
-            anyFixed = true;
-            fixes.push({
-                applied: true,
-                issueType: 'wrong_input_source',
-                nodeName: action.name || '',
-                description: `Inserted convert_to_text node and rewired ${inputName}`,
-                change: `${targetExtractionName}.${emailColumnName} → ${converterId} → ${action.name}.${inputName}`,
-            });
-        }
-        if (!anyFixed && Object.keys(inputs).length > 0) {
-            // Only report if we couldn't find any email inputs to fix
-            const emailInputs = Object.keys(inputs).filter(k => ['to_email', 'email_to', 'recipient'].includes(k.toLowerCase()));
-            if (emailInputs.length === 0) {
-                fixes.push({
-                    applied: false,
-                    issueType: 'wrong_input_source',
-                    nodeName: action.name || '',
-                    description: `No standard email input field found to rewire`,
-                });
-            }
-        }
-        return { ...action, inputs };
-    });
-    // Add the new converter nodes to the workflow
-    const allActions = [...updatedActions, ...newNodes];
-    const key = workflowDef.actions ? 'actions' : 'nodes';
+export function autoFixWorkflow(workflowDef) {
     return {
-        def: { ...workflowDef, [key]: allActions },
-        fixes,
-        usedNodes,
+        workflowDef: workflowDef,
+        fixesApplied: [],
+        success: true,
+        warnings: [
+            "DEPRECATED: autoFixWorkflow() no longer auto-fixes issues.",
+            "Use LLM analysis with ema://rules/anti-patterns instead.",
+        ],
     };
 }
 /**
- * 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
+ * DEPRECATED: Suggest fixes for workflow issues.
+ *
+ * This function now returns empty results with a deprecation warning.
+ * Use LLM analysis with ema://rules/* instead.
  */
-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`);
-    }
+export function suggestFixes(_workflowDef) {
     return {
-        originalIssueCount,
-        fixesApplied: allFixes,
-        remainingIssueCount,
-        workflowDef: currentDef,
-        success: appliedCount > 0,
-        warnings,
-        multipleResponderFixes,
+        standardFixes: [],
+        multiResponderFixes: [],
     };
 }
-/**
- * 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 };
-}

package/dist/sdk/workflow-generator.js

@@ -9,6 +9,7 @@
  * 2. Construct nodes based on user requirements
  * 3. Pass to compileWorkflow() to generate deployment-ready JSON
  */
+import { PROJECT_TYPES } from "./knowledge.js";
 /**
  * FALLBACK VALUES - Used only when ActionRegistry is not available.
  * These are based on API data as of 2026-01-16.
@@ -329,7 +330,7 @@ function buildInputBinding(binding) {
     }
 }
 function buildProtoConfig(spec) {
-    const projectType = spec.personaType === "voice" ? 5 : spec.personaType === "chat" ? 4 : 2;
+    const projectType = PROJECT_TYPES[spec.personaType] ?? PROJECT_TYPES.dashboard;
     // Widget format expected by Ema API:
     // { name: "widgetName", type: <type_id>, widgetName: { ...config... } }
     // The config is stored under a key matching the widget's name

package/dist/sdk/workflow-intent.js

@@ -445,9 +445,14 @@ const ACTION_CHAIN_PATTERNS = [
     },
 ];
 /**
- * Type compatibility rules - what outputs can connect to what inputs
+ * Intent routing type compatibility - determines how outputs wire to inputs during intent processing.
+ *
+ * NOTE: This is SEPARATE from knowledge.ts TYPE_COMPATIBILITY which is user-facing documentation.
+ * This focuses on the "can_connect_to" and "use_named_inputs_for" routing logic.
+ *
+ * Canonical type documentation: src/sdk/knowledge.ts → TYPE_COMPATIBILITY
  */
-export const TYPE_COMPATIBILITY = {
+export const INTENT_TYPE_ROUTING = {
     WELL_KNOWN_TYPE_CHAT_CONVERSATION: {
         can_connect_to: ["conversation"],
         use_named_inputs_for: [],
@@ -1312,6 +1317,37 @@ export function summarizeIntentConfidence(confidence) {
 // ─────────────────────────────────────────────────────────────────────────────
 // Intent to Spec Conversion
 // ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generate takeActionInstructions from tools for Voice AI.
+ *
+ * This populates the "Define what actions your AI Employee can perform" section
+ * in the Voice persona config. Format follows the Ema Voice API spec.
+ */
+function generateTakeActionInstructions(tools) {
+    if (!tools || tools.length === 0) {
+        return "";
+    }
+    const cases = tools.map((tool, index) => {
+        const caseNum = index + 1;
+        const toolName = tool.display_name ?? tool.action ?? `Action ${caseNum}`;
+        const triggerCondition = tool.trigger_condition ?? tool.description ?? "Perform this action when requested";
+        // Extract required parameters from tool schema if available
+        const requiredParams = tool.required_inputs ?? [];
+        const paramsObj = requiredParams.length > 0
+            ? `{ ${requiredParams.map(p => `"${p}": ""`).join(", ")} }`
+            : "{ }";
+        return `</Case ${caseNum}>
+${toolName}
+
+Trigger When: ${triggerCondition}
+
+Intent for tool call: "User requests ${toolName.toLowerCase()}"
+
+Required parameters: ${paramsObj}
+</Case ${caseNum}>`;
+    });
+    return cases.join("\n\n");
+}
 export function intentToSpec(intent) {
     const nodes = [];
     const resultMappings = [];
@@ -1463,7 +1499,11 @@ export function intentToSpec(intent) {
         welcomeMessage: intent.voice_config?.welcome_message,
         identityAndPurpose: intent.voice_config?.identity ?? intent.description,
         hangupInstructions: intent.voice_config?.hangup_instructions,
-        // Additional fields can be extracted from intent description in the future
+        transferInstructions: intent.voice_config?.transfer_instructions,
+        waitMessage: intent.voice_config?.wait_message,
+        // Generate takeActionInstructions from tools if not explicitly provided
+        takeActionInstructions: intent.voice_config?.take_action_instructions ??
+            generateTakeActionInstructions(intent.tools),
     } : undefined;
     return {
         name: intent.name,