@ema.co/mcp-toolkit 1.5.1 → 1.6.0

package/dist/mcp/handlers-consolidated.js

@@ -8,7 +8,9 @@ import { createVersionStorage } from "../sdk/version-storage.js";
 import { createVersionPolicyEngine } from "../sdk/version-policy.js";
 import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, detectWorkflowIssues, validateWorkflowConnections, suggestWorkflowFixes, } from "../sdk/knowledge.js";
 import { compileWorkflow } from "../sdk/workflow-generator.js";
-import { parseInput, intentToSpec } from "../sdk/workflow-intent.js";
+import { ensureActionRegistry } from "../sdk/action-registry.js";
+import { parseInput, intentToSpec, generateWorkflow } from "../sdk/workflow-intent.js";
+import { ensureSchemaRegistry, validateWorkflowSpec, generateActionCatalogForLLM } from "../sdk/workflow-validator.js";
 import { analyzeExecutionFlow, generateASCIIFlow } from "../sdk/workflow-execution-analyzer.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Widget Validation Helpers
@@ -61,6 +63,29 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
     const identifier = args.identifier; // deprecated alias
     const idOrName = id ?? identifier;
     const mode = args.mode;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // UNIFIED HANDLING: Route workflow operations to handleWorkflow
+    // ═══════════════════════════════════════════════════════════════════════════
+    const input = args.input;
+    const optimize = args.optimize;
+    const workflowDef = args.workflow_def ?? args.workflow;
+    // If input is provided → this is a create/modify workflow operation
+    // If optimize is provided → this is an optimize operation
+    // If id + workflowDef provided → this is a deploy operation
+    // Route these to handleWorkflow
+    if (input || optimize || (idOrName && workflowDef)) {
+        // Map persona args to workflow args
+        const workflowArgs = {
+            ...args,
+            persona_id: idOrName, // workflow uses persona_id not id
+        };
+        delete workflowArgs.id;
+        delete workflowArgs.identifier;
+        return handleWorkflow(workflowArgs, client, getTemplateId);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Standard persona operations (get, list, compare, version management)
+    // ═══════════════════════════════════════════════════════════════════════════
     // Determine effective mode
     let effectiveMode = mode;
     if (!effectiveMode) {
@@ -238,12 +263,13 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
             }
             // IMPORTANT: The Ema API requires workflow to be sent along with proto_config
             // for proto_config changes to persist. This matches what the UI does.
+            const workflowToSet = args.workflow ?? existingWorkflow;
             await client.updateAiEmployee({
                 persona_id: persona.id,
                 name: args.name,
                 description: args.description,
                 proto_config: mergedProtoConfig,
-                workflow: existingWorkflow, // Include workflow for proto_config to persist
+                workflow: workflowToSet, // Use provided workflow or existing workflow for proto_config to persist
                 enabled_by_user: typeof args.enabled === "boolean" ? args.enabled : undefined,
             });
             return {
@@ -544,7 +570,7 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
 // ═══════════════════════════════════════════════════════════════════════════
 // WORKFLOW Handler - Unified greenfield/brownfield operations
 // ═══════════════════════════════════════════════════════════════════════════
-export async function handleWorkflow(args, client) {
+export async function handleWorkflow(args, client, getTemplateId) {
     const personaId = args.persona_id;
     const workflowDef = args.workflow_def;
     const input = args.input;
@@ -570,8 +596,12 @@ export async function handleWorkflow(args, client) {
         // Auto-fix issues
         effectiveMode = "optimize";
     }
+    else if (personaId && workflowDef) {
+        // DEPLOY: Persona exists + workflow_def provided → deploy directly (no input needed)
+        effectiveMode = "deploy";
+    }
     else if (personaId && input) {
-        // BROWNFIELD: Modify existing workflow
+        // MODIFY: Persona exists + input provided → generate new workflow from input
         effectiveMode = "modify"; // New unified mode for all brownfield changes
     }
     else if (input && !personaId) {
@@ -589,8 +619,10 @@ export async function handleWorkflow(args, client) {
     const legacyMode = args.mode;
     if (legacyMode === "extend")
         effectiveMode = "modify";
-    if (legacyMode === "deploy" && personaId && input)
-        effectiveMode = "modify";
+    if (legacyMode === "deploy") {
+        // If explicit deploy mode, use it (works with or without input)
+        effectiveMode = "deploy";
+    }
     switch (effectiveMode) {
         case "extraction_schema": {
             // Generate extraction schema from JSON metadata (fully dynamic, no hardcoding)
@@ -745,6 +777,8 @@ export async function handleWorkflow(args, client) {
             if (!input) {
                 return { error: "input required for generate mode" };
             }
+            // Load action registry for API-driven action versions/namespaces
+            const actionRegistry = await ensureActionRegistry(client);
             const parseResult = parseInput(input);
             if (!parseResult.validation.complete) {
                 return {
@@ -754,10 +788,75 @@ export async function handleWorkflow(args, client) {
                     questions: parseResult.validation.questions,
                 };
             }
-            // Convert to spec and compile
-            const spec = intentToSpec(parseResult.intent);
-            const compiled = compileWorkflow(spec);
-            // Validate the generated workflow
+            // Override persona_type from args.type if provided (args.type takes precedence)
+            if (args.type) {
+                parseResult.intent.persona_type = args.type;
+            }
+            // Check if intent requires LLM-driven generation
+            const genResult = generateWorkflow(parseResult.intent);
+            // Load schema registry for API-driven validation (graceful degradation if unavailable)
+            let schemaRegistry;
+            try {
+                schemaRegistry = await ensureSchemaRegistry(client);
+            }
+            catch {
+                // Schema registry unavailable - skip API validation
+                schemaRegistry = null;
+            }
+            if (genResult.needs_llm) {
+                // Complex workflow - return prompt for LLM to generate
+                // Enhanced with API-driven action catalog if available
+                let enhancedPrompt = genResult.llm_prompt;
+                let availableActions = [];
+                let availableTemplates = [];
+                if (schemaRegistry) {
+                    const actionCatalog = generateActionCatalogForLLM(schemaRegistry);
+                    enhancedPrompt = genResult.llm_prompt ? {
+                        system: genResult.llm_prompt.system + "\n\n" + actionCatalog,
+                        user: genResult.llm_prompt.user,
+                    } : undefined;
+                    availableActions = schemaRegistry.getAllActions().map(a => a.name);
+                    availableTemplates = schemaRegistry.getAllTemplates().map(t => ({ id: t.id, name: t.name, type: t.type }));
+                }
+                return {
+                    status: "needs_llm_generation",
+                    reason: genResult.reason,
+                    complexity: genResult.complexity,
+                    llm_prompt: enhancedPrompt,
+                    hint: "Send llm_prompt to an LLM, then call persona(workflow_def=<parsed_response>) to deploy.",
+                    // Also provide basic spec as fallback (without complex chains)
+                    fallback_spec: intentToSpec(parseResult.intent),
+                    // Include catalogs for reference (if available)
+                    available_actions: availableActions,
+                    available_templates: availableTemplates,
+                };
+            }
+            // Simple workflow - use generated spec directly
+            const spec = genResult.spec;
+            // Override spec name with provided name if given (args.name takes precedence over parsed name)
+            if (args.name) {
+                spec.name = args.name;
+            }
+            if (args.description) {
+                spec.description = args.description;
+            }
+            // Validate spec against API schemas BEFORE compiling (if schema registry available)
+            let specValidation = null;
+            if (schemaRegistry) {
+                specValidation = validateWorkflowSpec(spec, schemaRegistry);
+                if (!specValidation.valid) {
+                    return {
+                        status: "validation_failed",
+                        errors: specValidation.errors,
+                        warnings: specValidation.warnings,
+                        action_coverage: specValidation.action_coverage,
+                        hint: "Fix the validation errors and try again. Unknown actions may need to be checked against ListActions.",
+                        spec_attempted: spec,
+                    };
+                }
+            }
+            const compiled = compileWorkflow(spec, { registry: actionRegistry });
+            // Validate the generated workflow (structural checks)
             const issues = detectWorkflowIssues(compiled.workflow_def);
             const result = {
                 mode: "generate",
@@ -766,6 +865,14 @@ export async function handleWorkflow(args, client) {
                 proto_config: compiled.proto_config,
                 validation: parseResult.validation,
             };
+            // Include API validation results if available
+            if (specValidation) {
+                result.api_validation = {
+                    valid: specValidation.valid,
+                    warnings: specValidation.warnings,
+                    action_coverage: specValidation.action_coverage,
+                };
+            }
             if (issues.length > 0) {
                 result.issues = issues;
             }
@@ -783,7 +890,141 @@ export async function handleWorkflow(args, client) {
                 result.deployed_to = { persona_id: personaId, persona_name: persona.name };
             }
             else if (!preview && !personaId) {
-                result.hint = "Provide persona_id to deploy, or use persona(mode='create') first";
+                // GREENFIELD: Create new persona from template, then deploy workflow + proto_config
+                const personaName = args.name;
+                if (personaName) {
+                    const personaType = args.type || "chat";
+                    // Try API-driven template lookup first, fallback to hardcoded IDs
+                    const FALLBACK_TEMPLATES = {
+                        voice: "00000000-0000-0000-0000-00000000001e", // Voice AI template (fallback)
+                        chat: "00000000-0000-0000-0000-000000000004", // Chat AI template (fallback)
+                        dashboard: "00000000-0000-0000-0000-000000000002", // Dashboard AI template (fallback)
+                    };
+                    // Use registry to find template by type
+                    const templateFromRegistry = actionRegistry.getTemplateForType(personaType);
+                    const templateId = getTemplateId?.(personaType) || templateFromRegistry?.id || FALLBACK_TEMPLATES[personaType];
+                    if (!templateId) {
+                        return {
+                            error: `No template found for type "${personaType}". Provide template_id or use type: voice, chat, or dashboard.`
+                        };
+                    }
+                    // Step 1: Create the persona from template
+                    const createResult = await client.createAiEmployee({
+                        name: personaName,
+                        description: args.description,
+                        template_id: templateId,
+                    });
+                    const newPersonaId = createResult.persona_id ?? createResult.id;
+                    if (!newPersonaId) {
+                        return { error: "Failed to create persona: no ID returned" };
+                    }
+                    // Step 2: Fetch the newly created persona to get template's valid structure
+                    const newPersona = await client.getPersonaById(newPersonaId);
+                    if (!newPersona) {
+                        return { error: `Failed to fetch newly created persona: ${newPersonaId}` };
+                    }
+                    // Step 3: Merge proto_config - keep template structure, update widget values
+                    const existingProtoConfig = (newPersona.proto_config ?? {});
+                    const generatedProtoConfig = args.proto_config || compiled.proto_config || {};
+                    // Merge widgets by name - template widgets provide structure, generated values override
+                    const existingWidgets = (existingProtoConfig.widgets ?? []);
+                    const generatedWidgets = (generatedProtoConfig.widgets ?? []);
+                    const widgetMap = new Map();
+                    // Start with template widgets (valid structure)
+                    for (const w of existingWidgets) {
+                        if (typeof w.name === "string" && w.name.trim().length > 0) {
+                            widgetMap.set(w.name, w);
+                        }
+                    }
+                    // Merge generated widget VALUES into template structure
+                    for (const genWidget of generatedWidgets) {
+                        const widgetName = genWidget.name;
+                        if (typeof widgetName === "string" && widgetName.trim().length > 0) {
+                            const existing = widgetMap.get(widgetName);
+                            if (existing) {
+                                // Merge: keep template structure, update config values
+                                const merged = { ...existing };
+                                // The widget config is stored under the widget name (e.g., conversationSettings)
+                                if (genWidget[widgetName]) {
+                                    merged[widgetName] = { ...(existing[widgetName] || {}), ...genWidget[widgetName] };
+                                }
+                                widgetMap.set(widgetName, merged);
+                            }
+                            else {
+                                // New widget not in template - add as-is
+                                widgetMap.set(widgetName, genWidget);
+                            }
+                        }
+                    }
+                    const mergedProtoConfig = {
+                        ...existingProtoConfig,
+                        widgets: Array.from(widgetMap.values()),
+                    };
+                    // Step 4: Deploy BOTH workflow AND proto_config for ALL persona types
+                    // Voice AI IS driven by workflow (not just identityAndPurpose)
+                    const existingWorkflow = newPersona.workflow_def;
+                    const existingWfName = existingWorkflow?.workflowName;
+                    // Clone our compiled workflow and set the namespace from the existing workflow
+                    const workflowForDeploy = JSON.parse(JSON.stringify(compiled.workflow_def));
+                    const wfName = workflowForDeploy.workflowName;
+                    if (wfName?.name && existingWfName?.name) {
+                        // Copy the exact namespace from the template workflow
+                        wfName.name.namespaces = existingWfName.name.namespaces;
+                        wfName.name.name = existingWfName.name.name; // template_id
+                    }
+                    // Fix results format - use "<actionName>.<outputName>" keys
+                    const compiledResults = workflowForDeploy.results;
+                    if (compiledResults) {
+                        const newResults = {};
+                        for (const [, value] of Object.entries(compiledResults)) {
+                            if (value.actionName && value.outputName) {
+                                const key = `${value.actionName}.${value.outputName}`;
+                                newResults[key] = value;
+                            }
+                        }
+                        workflowForDeploy.results = newResults;
+                    }
+                    try {
+                        await client.updateAiEmployee({
+                            persona_id: newPersonaId,
+                            workflow: workflowForDeploy,
+                            proto_config: mergedProtoConfig,
+                        }, { verbose: true });
+                    }
+                    catch (deployError) {
+                        // Workflow deploy failed - still set proto_config
+                        const errMsg = deployError instanceof Error ? deployError.message : String(deployError);
+                        await client.updateAiEmployee({
+                            persona_id: newPersonaId,
+                            proto_config: mergedProtoConfig,
+                        });
+                        result.workflow_deploy_error = errMsg;
+                        result.workflow_attempted = workflowForDeploy;
+                        result.status = "partial";
+                        result.hint = "Persona created, config set, but workflow deploy failed. Check workflow_attempted for details.";
+                        result.deployed_to = {
+                            persona_id: newPersonaId,
+                            persona_name: personaName,
+                            created: true,
+                            workflow_deployed: false,
+                        };
+                        return result;
+                    }
+                    // Success - workflow deployed for all persona types
+                    result.deployed_to = {
+                        persona_id: newPersonaId,
+                        persona_name: personaName,
+                        created: true
+                    };
+                    result.status = "deployed";
+                    result.next_steps = [
+                        `Persona "${personaName}" created with template workflow.`,
+                        `To customize the workflow, use: workflow(persona_id="${newPersonaId}", input="add search node", preview=false)`,
+                    ];
+                }
+                else {
+                    result.hint = "Provide name to create new persona, or persona_id to deploy to existing persona";
+                }
             }
             if (preview) {
                 result.next_steps = [
@@ -809,6 +1050,88 @@ export async function handleWorkflow(args, client) {
             if (!persona) {
                 return { error: `Persona not found: ${personaId}` };
             }
+            // ─────────────────────────────────────────────────────────────────────────
+            // CONFIG-ONLY DETECTION: Route to proto_config update instead of workflow
+            // ─────────────────────────────────────────────────────────────────────────
+            const lowerInput = input.toLowerCase();
+            const isConfigOnlyUpdate = ((lowerInput.includes("voice settings") || lowerInput.includes("voice config")) ||
+                (lowerInput.includes("welcome message") && !lowerInput.includes("add") && !lowerInput.includes("node")) ||
+                (lowerInput.includes("identity") && lowerInput.includes("purpose")) ||
+                (lowerInput.includes("speech characteristics")) ||
+                (lowerInput.includes("hangup instructions") || lowerInput.includes("hangup")) ||
+                (lowerInput.includes("update") && (lowerInput.includes("persona settings") ||
+                    lowerInput.includes("conversation settings") ||
+                    lowerInput.includes("proto_config") ||
+                    lowerInput.includes("chat settings"))));
+            if (isConfigOnlyUpdate) {
+                // This is a config update, not a workflow modification
+                // Parse the config values from the input and update proto_config only
+                const existingProtoConfig = (persona.proto_config ?? {});
+                const existingWidgets = (existingProtoConfig.widgets ?? []);
+                // Find and update the conversationSettings widget
+                const widgetMap = new Map();
+                for (const w of existingWidgets) {
+                    if (typeof w.name === "string" && w.name.trim().length > 0) {
+                        widgetMap.set(w.name, { ...w });
+                    }
+                }
+                // Parse voice config updates from input
+                const configUpdates = {};
+                // Extract welcome message
+                const welcomeMatch = input.match(/welcome\s*message[:\s]*["']?([^"'\n]+(?:\n(?![0-9]+\.).*)*?)(?:["']|(?=\n\n|\n[0-9]+\.))/i);
+                if (welcomeMatch) {
+                    configUpdates.welcomeMessage = welcomeMatch[1].trim().replace(/^["']|["']$/g, '');
+                }
+                // Extract identity and purpose
+                const identityMatch = input.match(/identity\s*(?:and\s*)?purpose[:\s]*["']?(.+?)(?:["']|(?=\n\n[0-9]+\.|$))/is);
+                if (identityMatch) {
+                    configUpdates.identityAndPurpose = identityMatch[1].trim().replace(/^["']|["']$/g, '');
+                }
+                // Extract speech characteristics
+                const speechMatch = input.match(/speech\s*characteristics?[:\s]*["']?([^"'\n]+)["']?/i);
+                if (speechMatch) {
+                    configUpdates.speechCharacteristics = speechMatch[1].trim().replace(/^["']|["']$/g, '');
+                }
+                // Extract hangup instructions
+                const hangupMatch = input.match(/hangup\s*instructions?[:\s]*["']?(.+?)(?:["']|$)/is);
+                if (hangupMatch) {
+                    configUpdates.hangupInstructions = hangupMatch[1].trim().replace(/^["']|["']$/g, '');
+                }
+                // Update conversationSettings widget
+                const convWidget = widgetMap.get("conversationSettings") || {
+                    name: "conversationSettings",
+                    type: 39,
+                    conversationSettings: {},
+                };
+                const convSettings = (convWidget.conversationSettings ?? {});
+                // Merge config updates
+                for (const [key, value] of Object.entries(configUpdates)) {
+                    convSettings[key] = value;
+                }
+                convWidget.conversationSettings = convSettings;
+                widgetMap.set("conversationSettings", convWidget);
+                const mergedProtoConfig = {
+                    ...existingProtoConfig,
+                    widgets: Array.from(widgetMap.values()),
+                };
+                if (!preview) {
+                    // Deploy config update only - preserve existing workflow
+                    await client.updateAiEmployee({
+                        persona_id: personaId,
+                        proto_config: mergedProtoConfig,
+                        workflow: persona.workflow_def,
+                    });
+                }
+                return {
+                    mode: "config_update",
+                    status: preview ? "preview" : "deployed",
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                    config_updates: configUpdates,
+                    note: "Updated persona configuration only. Workflow unchanged.",
+                    hint: "To modify the workflow itself, describe workflow changes like 'add search node' or 'add HITL before email'.",
+                };
+            }
             const existingWorkflow = persona.workflow_def;
             if (!existingWorkflow) {
                 return {
@@ -959,8 +1282,68 @@ export async function handleWorkflow(args, client) {
             }
             return result;
         }
-        // Note: mode="deploy" is now handled by preview=false on extend/optimize/generate
-        // Legacy calls are converted at the top of the handler
+        case "deploy": {
+            // DEPLOY: Direct workflow deployment to existing persona (no input required)
+            if (!personaId) {
+                return { error: "persona_id required for deploy mode" };
+            }
+            if (!workflowDef) {
+                return { error: "workflow_def required for deploy mode" };
+            }
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                return { error: `Persona not found: ${personaId}` };
+            }
+            // Sanitize workflow before deployment
+            const sanitizedWorkflow = sanitizeWorkflowForDeploy(workflowDef);
+            // Determine proto_config to use: provided > existing
+            const existingProtoConfig = persona.proto_config;
+            const providedProtoConfig = args.proto_config;
+            const protoConfigToUse = providedProtoConfig || existingProtoConfig || {};
+            // Check if this is a voice persona and warn if critical settings are missing
+            const projectSettings = protoConfigToUse.projectSettings;
+            const isVoice = projectSettings?.projectType === 5;
+            const warnings = [];
+            if (isVoice && !providedProtoConfig) {
+                // Check if existing proto_config has conversationSettings populated
+                const widgets = (protoConfigToUse.widgets ?? []);
+                const convSettings = widgets.find(w => w.name === "conversationSettings");
+                const convConfig = convSettings?.conversationSettings;
+                if (!convConfig?.welcomeMessage || !convConfig?.identityAndPurpose) {
+                    warnings.push("Voice persona detected but proto_config not provided. Voice settings (welcomeMessage, identityAndPurpose, etc.) may be empty or generic. " +
+                        "If you generated the workflow with workflow(input=...), pass the generated proto_config along with workflow_def to preserve voice settings.");
+                }
+            }
+            // Deploy workflow (always deploy, preview is not applicable for explicit deploy mode)
+            try {
+                await client.updateAiEmployee({
+                    persona_id: personaId,
+                    workflow: sanitizedWorkflow,
+                    proto_config: protoConfigToUse,
+                });
+                const result = {
+                    mode: "deploy",
+                    status: "deployed",
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                    workflow_deployed: true,
+                };
+                if (warnings.length > 0) {
+                    result.warnings = warnings;
+                }
+                return result;
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                return {
+                    mode: "deploy",
+                    status: "failed",
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                    error: errorMessage,
+                };
+            }
+        }
         case "compare": {
             if (!personaId || !args.compare_to) {
                 return { error: "persona_id and compare_to required for compare mode" };
@@ -984,6 +1367,8 @@ export async function handleWorkflow(args, client) {
             if (!nodes) {
                 return { error: "nodes required for compile mode" };
             }
+            // Load action registry for API-driven action versions/namespaces
+            const compileRegistry = await ensureActionRegistry(client);
             const spec = {
                 name: args.name || "Compiled Workflow",
                 description: args.description || "Generated workflow",
@@ -991,10 +1376,11 @@ export async function handleWorkflow(args, client) {
                 nodes: nodes,
                 result_mappings: resultMappings || [],
             };
-            const compiled = compileWorkflow(spec);
+            const compiled = compileWorkflow(spec, { registry: compileRegistry });
             return {
                 workflow_def: compiled.workflow_def,
                 proto_config: compiled.proto_config,
+                registry_loaded: compileRegistry.isLoaded(),
             };
         }
         case "optimize": {