@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-3

package/dist/mcp/handlers/workflow/deploy.js

@@ -0,0 +1,73 @@
+/**
+ * Workflow Deploy Handler
+ *
+ * Deploys a workflow_def to an existing persona.
+ */
+import { sanitizeWorkflowForDeploy } from "./utils.js";
+/**
+ * Handle workflow deploy mode
+ */
+export async function handleWorkflowDeploy(args, client) {
+    const personaId = args.persona_id;
+    const workflowDef = args.workflow_def;
+    // 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,
+        };
+    }
+}

package/dist/mcp/handlers/workflow/generate.js

@@ -0,0 +1,350 @@
+/**
+ * Workflow Generate Handler
+ *
+ * Handles greenfield workflow generation from natural language input.
+ * Supports:
+ * - Simple workflows (direct generation)
+ * - Complex workflows (returns LLM prompt for agent to complete)
+ * - Intent Architect integration for qualification questions
+ * - Auto-deploy to new or existing personas
+ */
+import { parseInput, intentToSpec, generateWorkflow } from "../../../sdk/workflow-intent.js";
+import { compileWorkflow } from "../../../sdk/workflow-generator.js";
+import { detectWorkflowIssues } from "../../../sdk/knowledge.js";
+import { runIntentArchitect } from "../../../sdk/intent-architect.js";
+import { ensureActionRegistry } from "../../../sdk/action-registry.js";
+import { ensureSchemaRegistry, validateWorkflowSpec, generateActionCatalogForLLM } from "../../../sdk/workflow-validator.js";
+import { getTemplates, normalizeTriggerType } from "../../handlers/index.js";
+/**
+ * Get persona widget context for workflow bindings
+ */
+async function getPersonaWidgets(personaId, client) {
+    if (!personaId)
+        return [];
+    try {
+        const persona = await client.getPersonaById(personaId);
+        const protoConfig = persona?.proto_config;
+        if (protoConfig?.widgets) {
+            return protoConfig.widgets
+                .filter(w => typeof w.name === "string" && w.name.trim().length > 0)
+                .map(w => ({
+                name: w.name,
+                type: String(w.type ?? "unknown"),
+                title: w.title,
+            }));
+        }
+    }
+    catch {
+        // Persona not found or no widgets - continue without context
+    }
+    return [];
+}
+/**
+ * Enhance an LLM prompt with action catalog and widget context
+ */
+function enhancePromptWithContext(prompt, schemaRegistry, personaWidgets) {
+    let enhancedPrompt = prompt;
+    let availableActions = [];
+    let availableTemplates = [];
+    if (!prompt) {
+        return { prompt: enhancedPrompt, availableActions, availableTemplates };
+    }
+    let systemAdditions = "";
+    // Add action catalog if available
+    if (schemaRegistry) {
+        const actionCatalog = generateActionCatalogForLLM(schemaRegistry);
+        systemAdditions += "\n\n## Available Actions\n" + actionCatalog;
+        availableActions = schemaRegistry.getAllActions().map((a) => a.name);
+        availableTemplates = schemaRegistry.getAllTemplates().map((t) => ({ id: t.id, name: t.name, type: t.type }));
+    }
+    // Add persona widget context if available
+    if (personaWidgets.length > 0) {
+        systemAdditions += "\n\n## Available Persona Widgets\n";
+        systemAdditions += "Use these exact widget names in workflow bindings (widgetName field):\n";
+        for (const w of personaWidgets) {
+            systemAdditions += `- \`${w.name}\` (${w.type})${w.title ? ` - "${w.title}"` : ""}\n`;
+        }
+    }
+    if (systemAdditions) {
+        enhancedPrompt = {
+            system: prompt.system + systemAdditions,
+            user: prompt.user,
+        };
+    }
+    return { prompt: enhancedPrompt, availableActions, availableTemplates };
+}
+/**
+ * Deploy workflow to a new persona (greenfield creation)
+ */
+async function deployToNewPersona(args, client, compiled, actionRegistry, getTemplateId) {
+    const personaName = args.name;
+    if (!personaName) {
+        return { success: false, hint: "Provide name to create new persona, or persona_id to deploy to existing persona" };
+    }
+    const personaType = args.type || "chat";
+    // Dynamic template lookup
+    const templates = await getTemplates(client);
+    const matchingTemplate = templates.find(t => normalizeTriggerType(t.trigger_type) === personaType.toLowerCase());
+    const templateFromRegistry = actionRegistry.getTemplateForType(personaType);
+    const templateId = getTemplateId?.(personaType) || templateFromRegistry?.id || matchingTemplate?.id;
+    if (!templateId) {
+        const availableTypes = [...new Set(templates.map(t => normalizeTriggerType(t.trigger_type)).filter(Boolean))];
+        return {
+            success: false,
+            error: `No template found for type "${personaType}".`,
+            hint: `Available types: ${availableTypes.join(", ")}. Provide template_id directly or use one of the available types.`,
+        };
+    }
+    // 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 { success: false, error: "Failed to create persona: no ID returned" };
+    }
+    // Step 2: Fetch the newly created persona
+    const newPersona = await client.getPersonaById(newPersonaId);
+    if (!newPersona) {
+        return { success: false, error: `Failed to fetch newly created persona: ${newPersonaId}` };
+    }
+    // Step 3: Merge proto_config
+    const existingProtoConfig = (newPersona.proto_config ?? {});
+    const generatedProtoConfig = args.proto_config || compiled.proto_config || {};
+    const existingWidgets = (existingProtoConfig.widgets ?? []);
+    const generatedWidgets = (generatedProtoConfig.widgets ?? []);
+    const widgetMap = new Map();
+    for (const w of existingWidgets) {
+        if (typeof w.name === "string" && w.name.trim().length > 0) {
+            widgetMap.set(w.name, w);
+        }
+    }
+    for (const genWidget of generatedWidgets) {
+        const widgetName = genWidget.name;
+        if (typeof widgetName === "string" && widgetName.trim().length > 0) {
+            const existing = widgetMap.get(widgetName);
+            if (existing) {
+                const merged = { ...existing };
+                if (genWidget[widgetName]) {
+                    merged[widgetName] = { ...(existing[widgetName] || {}), ...genWidget[widgetName] };
+                }
+                widgetMap.set(widgetName, merged);
+            }
+            else {
+                widgetMap.set(widgetName, genWidget);
+            }
+        }
+    }
+    const mergedProtoConfig = {
+        ...existingProtoConfig,
+        widgets: Array.from(widgetMap.values()),
+    };
+    // Step 4: Deploy workflow
+    // NOTE: The SDK's updateAiEmployee() handles workflowName namespace automatically.
+    // It will copy from existing workflow if present, or generate a valid namespace if not.
+    // It also fixes the results format. No need to manually manipulate these here.
+    try {
+        await client.updateAiEmployee({
+            persona_id: newPersonaId,
+            workflow: compiled.workflow_def,
+            proto_config: mergedProtoConfig,
+        }, { verbose: true });
+        return { success: true, personaId: newPersonaId, personaName };
+    }
+    catch (deployError) {
+        const errMsg = deployError instanceof Error ? deployError.message : String(deployError);
+        // Still set proto_config
+        await client.updateAiEmployee({
+            persona_id: newPersonaId,
+            proto_config: mergedProtoConfig,
+        });
+        return {
+            success: false,
+            personaId: newPersonaId,
+            personaName,
+            workflowDeployError: errMsg,
+            workflowAttempted: compiled.workflow_def,
+        };
+    }
+}
+/**
+ * Handle workflow generate mode
+ */
+export async function handleWorkflowGenerate(args, client, getTemplateId) {
+    const personaId = args.persona_id;
+    const input = args.input;
+    const preview = args.preview !== false;
+    if (!input) {
+        return { error: "input required for generate mode" };
+    }
+    // Load action registry
+    const actionRegistry = await ensureActionRegistry(client);
+    // Parse input
+    const parseResult = parseInput(input);
+    if (!parseResult.validation.complete) {
+        return {
+            status: "incomplete",
+            input_type: parseResult.input_type,
+            missing: parseResult.validation.missing,
+            questions: parseResult.validation.questions,
+        };
+    }
+    // Override persona_type from args.type if provided
+    if (args.type) {
+        parseResult.intent.persona_type = args.type;
+    }
+    // Load schema registry
+    let schemaRegistry = null;
+    try {
+        schemaRegistry = await ensureSchemaRegistry(client);
+    }
+    catch {
+        // Schema registry unavailable - skip API validation
+    }
+    // Get persona widgets for context
+    const personaWidgets = await getPersonaWidgets(personaId, client);
+    // Run Intent Architect for complexity assessment
+    const maxComplexity = args.max_complexity || undefined;
+    const architectResult = runIntentArchitect(input, {
+        persona_type: parseResult.intent.persona_type,
+        available_integrations: schemaRegistry?.getAllActions().slice(0, 20).map((a) => a.displayName || a.name),
+    }, { max_complexity: maxComplexity });
+    // For moderate/complex: return Intent Architect result
+    if (!architectResult.strategy.can_proceed) {
+        const enhanced = enhancePromptWithContext(architectResult.prompt_package, schemaRegistry, personaWidgets);
+        return {
+            status: "needs_intent_architect",
+            available_widgets: personaWidgets.length > 0 ? personaWidgets : undefined,
+            assessment: architectResult.assessment,
+            strategy: architectResult.strategy,
+            questions: architectResult.questions,
+            llm_prompt: enhanced.prompt,
+            hint: architectResult.strategy.next_step,
+            reason: architectResult.legacy?.signals.reason,
+            complexity: architectResult.legacy?.complexity,
+            approach: architectResult.strategy.approach,
+            gates_to_ask: architectResult.strategy.gates_to_ask,
+            fallback_spec: intentToSpec(parseResult.intent),
+            available_actions: enhanced.availableActions,
+            available_templates: enhanced.availableTemplates,
+        };
+    }
+    // SIMPLE complexity: generate directly
+    const genResult = generateWorkflow(parseResult.intent);
+    if (genResult.needs_llm) {
+        const enhanced = enhancePromptWithContext(genResult.llm_prompt, schemaRegistry, personaWidgets);
+        return {
+            status: "needs_llm_generation",
+            reason: genResult.reason,
+            complexity: genResult.complexity,
+            llm_prompt: enhanced.prompt,
+            hint: "Send llm_prompt to an LLM, then call persona(workflow_def=<parsed_response>) to deploy.",
+            fallback_spec: intentToSpec(parseResult.intent),
+            available_actions: enhanced.availableActions,
+            available_templates: enhanced.availableTemplates,
+            available_widgets: personaWidgets.length > 0 ? personaWidgets : undefined,
+        };
+    }
+    // Simple workflow - compile
+    const spec = genResult.spec;
+    if (args.name) {
+        spec.name = args.name;
+    }
+    if (args.description) {
+        spec.description = args.description;
+    }
+    // Validate spec before compiling
+    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 generated workflow
+    const issues = detectWorkflowIssues(compiled.workflow_def);
+    const result = {
+        mode: "generate",
+        status: preview ? "preview" : "deployed",
+        workflow_def: compiled.workflow_def,
+        proto_config: compiled.proto_config,
+        validation: parseResult.validation,
+    };
+    if (specValidation) {
+        result.api_validation = {
+            valid: specValidation.valid,
+            warnings: specValidation.warnings,
+            action_coverage: specValidation.action_coverage,
+        };
+    }
+    if (issues.length > 0) {
+        result.issues = issues;
+    }
+    // Deploy if not preview
+    if (!preview && personaId) {
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            return { error: `Persona not found: ${personaId}` };
+        }
+        await client.updateAiEmployee({
+            persona_id: personaId,
+            workflow: compiled.workflow_def,
+            proto_config: args.proto_config || compiled.proto_config || persona.proto_config,
+        });
+        result.deployed_to = { persona_id: personaId, persona_name: persona.name };
+    }
+    else if (!preview && !personaId) {
+        // Greenfield: create new persona
+        const deployResult = await deployToNewPersona(args, client, compiled, actionRegistry, getTemplateId);
+        if (deployResult.workflowDeployError) {
+            result.workflow_deploy_error = deployResult.workflowDeployError;
+            result.workflow_attempted = deployResult.workflowAttempted;
+            result.status = "partial";
+            result.hint = "Persona created, config set, but workflow deploy failed. Check workflow_attempted for details.";
+            result.deployed_to = {
+                persona_id: deployResult.personaId,
+                persona_name: deployResult.personaName,
+                created: true,
+                workflow_deployed: false,
+            };
+            return result;
+        }
+        else if (deployResult.success) {
+            result.deployed_to = {
+                persona_id: deployResult.personaId,
+                persona_name: deployResult.personaName,
+                created: true,
+            };
+            result.status = "deployed";
+            result.next_steps = [
+                `Persona "${deployResult.personaName}" created with template workflow.`,
+                `To customize the workflow, use: workflow(persona_id="${deployResult.personaId}", input="add search node", preview=false)`,
+            ];
+        }
+        else if (deployResult.error) {
+            return { error: deployResult.error, hint: deployResult.hint };
+        }
+        else {
+            result.hint = deployResult.hint;
+        }
+    }
+    if (preview) {
+        result.next_steps = [
+            "Review the generated workflow_def",
+            personaId
+                ? `Deploy with: workflow(mode="generate", input=..., persona_id="${personaId}", preview=false)`
+                : "Create persona first: persona(mode='create', name='...', type='...')",
+        ];
+    }
+    return result;
+}

package/dist/mcp/handlers/workflow/index.js

@@ -0,0 +1,136 @@
+/**
+ * Workflow Handler - Unified greenfield/brownfield operations
+ *
+ * Modes:
+ * - generate: Create new workflow from input
+ * - modify/extend: Transform existing workflow
+ * - analyze: Return current state + issues
+ * - deploy: Deploy workflow to persona
+ * - compare: Compare two workflow versions
+ * - compile: Compile WorkflowSpec to workflow_def
+ * - optimize: Auto-fix issues
+ *
+ * Note: During extraction, individual mode handlers are being moved here.
+ * Until complete, delegates to handlers-consolidated.ts.
+ */
+// Re-export types
+export * from "./types.js";
+// Re-export utilities
+export * from "./utils.js";
+// Import mode handlers
+import { handleWorkflowAnalyze } from "./analyze.js";
+import { handleWorkflowCompare } from "./compare.js";
+import { handleWorkflowCompile } from "./compile.js";
+import { handleWorkflowOptimize } from "./optimize.js";
+import { handleWorkflowDeploy } from "./deploy.js";
+import { handleWorkflowGenerate } from "./generate.js";
+import { handleWorkflowModify } from "./modify.js";
+// Re-export mode handlers
+export { handleWorkflowAnalyze } from "./analyze.js";
+export { handleWorkflowCompare } from "./compare.js";
+export { handleWorkflowCompile } from "./compile.js";
+export { handleWorkflowOptimize } from "./optimize.js";
+export { handleWorkflowDeploy } from "./deploy.js";
+export { handleWorkflowGenerate } from "./generate.js";
+export { handleWorkflowModify } from "./modify.js";
+export { applyWorkflowModifications, buildWorkflowAction, buildInputBinding, } from "./modify.js";
+/**
+ * Main workflow handler with mode-based dispatch
+ *
+ * Routes to the appropriate extracted handler based on effective mode.
+ */
+export async function handleWorkflow(args, client, getTemplateId) {
+    const personaId = args.persona_id;
+    const workflowDef = args.workflow_def;
+    const input = args.input;
+    const optimize = args.optimize;
+    const compareTo = args.compare_to;
+    const operations = args.operations;
+    // Smart mode detection - user doesn't need to specify
+    let effectiveMode;
+    if (args.mode === "compile") {
+        effectiveMode = "compile";
+    }
+    else if (compareTo) {
+        effectiveMode = "compare";
+    }
+    else if (optimize && personaId) {
+        effectiveMode = "optimize";
+    }
+    else if (personaId && workflowDef) {
+        effectiveMode = "deploy";
+    }
+    else if (personaId && (input || operations)) {
+        // Modify mode: either natural language input OR structured operations
+        effectiveMode = "modify";
+    }
+    else if (input && !personaId) {
+        effectiveMode = "generate";
+    }
+    else if (personaId || workflowDef || args.include) {
+        effectiveMode = "analyze";
+    }
+    else {
+        effectiveMode = "analyze";
+    }
+    // Explicit mode support
+    const legacyMode = args.mode;
+    if (legacyMode === "extend")
+        effectiveMode = "modify";
+    if (legacyMode === "modify")
+        effectiveMode = "modify";
+    if (legacyMode === "deploy")
+        effectiveMode = "deploy";
+    // Route to extracted handler
+    switch (effectiveMode) {
+        case "generate":
+            return handleWorkflowGenerate(args, client, getTemplateId);
+        case "modify":
+        case "extend":
+            return handleWorkflowModify(args, client);
+        case "analyze":
+            return handleWorkflowAnalyze(args, client);
+        case "deploy":
+            return handleWorkflowDeploy(args, client);
+        case "compare":
+            return handleWorkflowCompare(args, client);
+        case "compile":
+            return handleWorkflowCompile(args, client);
+        case "optimize":
+            return handleWorkflowOptimize(args, client);
+        default:
+            return { error: `Unknown mode: ${effectiveMode}` };
+    }
+}
+/**
+ * Check if a workflow mode has been extracted
+ */
+export function hasExtractedWorkflowHandler(mode) {
+    const extractedModes = ["analyze", "compare", "compile", "optimize", "deploy", "generate", "modify", "extend"];
+    return extractedModes.includes(mode);
+}
+/**
+ * Get handler for a specific workflow mode
+ * Note: generate handler has a different signature (requires getTemplateId)
+ */
+export function getWorkflowModeHandler(mode) {
+    switch (mode) {
+        case "analyze":
+            return handleWorkflowAnalyze;
+        case "compare":
+            return handleWorkflowCompare;
+        case "compile":
+            return handleWorkflowCompile;
+        case "optimize":
+            return handleWorkflowOptimize;
+        case "deploy":
+            return handleWorkflowDeploy;
+        case "generate":
+            return handleWorkflowGenerate;
+        case "modify":
+        case "extend":
+            return handleWorkflowModify;
+        default:
+            return undefined;
+    }
+}