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

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

@@ -2,8 +2,61 @@
  * Workflow Deploy Handler
  *
  * Deploys a workflow_def to an existing persona.
+ * Includes deprecation warnings (does not block, just warns).
+ *
+ * BLOCKING VALIDATION:
+ * - If workflow has knowledge search nodes, data sources MUST be attached and indexed.
  */
+import { PROJECT_TYPES } from "../../../sdk/knowledge.js";
 import { sanitizeWorkflowForDeploy } from "./utils.js";
+import { DEPRECATED_ACTIONS_FALLBACK, checkWorkflowDeprecations } from "./index.js";
+/**
+ * Extract action type name from various workflow_def formats.
+ * Handles both string and object formats:
+ * - String: "search/v2"
+ * - Object: { name: { name: "search", namespaces: [...] }, version: "v2" }
+ */
+function extractActionTypeName(action) {
+    if (typeof action === "string") {
+        return action;
+    }
+    if (typeof action === "object" && action !== null) {
+        const actionObj = action;
+        // Format: { name: { name: "search", namespaces: [...] } }
+        if (actionObj.name && typeof actionObj.name === "object") {
+            const nameObj = actionObj.name;
+            if (typeof nameObj.name === "string") {
+                return nameObj.name;
+            }
+        }
+        // Format: { name: "search" } (direct)
+        if (typeof actionObj.name === "string") {
+            return actionObj.name;
+        }
+    }
+    return "";
+}
+/**
+ * Detect knowledge search nodes in a workflow.
+ * Returns true if workflow contains search/v2 or search_datastore nodes (NOT web_search).
+ */
+function hasKnowledgeSearchNodes(workflowDef) {
+    const actions = (workflowDef.actions ?? []);
+    return actions.some(a => {
+        // Extract action type from various formats
+        const actionTypeName = extractActionTypeName(a.action) || a.actionType || "";
+        const nodeName = (typeof a.name === "string" ? a.name : "").toLowerCase();
+        // Match: search, search/v2, search_datastore
+        // Exclude: web_search, live_web_search
+        const isSearchNode = actionTypeName.includes("search") ||
+            nodeName.includes("search");
+        const isWebSearch = actionTypeName.includes("web_search") ||
+            nodeName.includes("web_search");
+        return isSearchNode && !isWebSearch;
+    });
+}
+// Export for use in modify.ts
+export { hasKnowledgeSearchNodes, extractActionTypeName };
 /**
  * Handle workflow deploy mode
  */
@@ -21,16 +74,116 @@ export async function handleWorkflowDeploy(args, client) {
     if (!persona) {
         return { error: `Persona not found: ${personaId}` };
     }
+    // ── BLOCKING VALIDATION: Bidirectional search/data source validation ──
+    const hasSearchNodes = hasKnowledgeSearchNodes(workflowDef);
+    let dataSourceStats = null;
+    // Try to get data source stats (used for both validation directions)
+    try {
+        dataSourceStats = await client.getDataSourceAggregates(personaId);
+    }
+    catch (statsError) {
+        // If we can't check stats, log warning but don't block
+        console.error(`[deploy] Could not verify data sources: ${statsError}`);
+    }
+    // VALIDATION 1: If workflow has search nodes, data sources MUST exist and be indexed
+    if (hasSearchNodes && dataSourceStats) {
+        if (dataSourceStats.total === 0) {
+            return {
+                error: "DEPLOYMENT BLOCKED: Workflow contains knowledge search nodes but persona has no data sources attached.",
+                mode: "deploy",
+                persona_id: personaId,
+                persona_name: persona.name,
+                validation_failed: "search_nodes_require_data_sources",
+                current_state: {
+                    search_nodes_detected: true,
+                    data_sources_total: 0,
+                    data_sources_indexed: 0,
+                },
+                _fix: [
+                    "1. Upload documents: persona(id='...',data={method:'upload',path:'/path/to/doc.pdf'})",
+                    "2. Check status: persona(id='...',data={method:'stats'}) → wait for 'success' > 0",
+                    "3. Then retry: workflow(mode='deploy', persona_id='...', workflow_def={...})",
+                ],
+            };
+        }
+        if (dataSourceStats.success === 0) {
+            return {
+                error: "DEPLOYMENT BLOCKED: Workflow contains knowledge search nodes but no data sources have been successfully indexed.",
+                mode: "deploy",
+                persona_id: personaId,
+                persona_name: persona.name,
+                validation_failed: "search_nodes_require_indexed_data",
+                current_state: {
+                    search_nodes_detected: true,
+                    data_sources_total: dataSourceStats.total,
+                    data_sources_pending: dataSourceStats.pending,
+                    data_sources_success: dataSourceStats.success,
+                    data_sources_failed: dataSourceStats.failed,
+                },
+                _fix: dataSourceStats.pending > 0
+                    ? [
+                        "Data sources are still indexing. Wait for indexing to complete:",
+                        "1. Check status: persona(id='...',data={method:'stats'})",
+                        "2. Retry when 'success' > 0",
+                    ]
+                    : [
+                        "All data sources failed indexing. Check file formats and re-upload:",
+                        "1. List files: persona(id='...',data={method:'list'})",
+                        "2. Delete failed: persona(id='...',data={method:'delete',file_id:'...'})",
+                        "3. Re-upload: persona(id='...',data={method:'upload',path:'...'})",
+                    ],
+            };
+        }
+    }
+    // VALIDATION 2: If persona has indexed data sources but workflow has NO search nodes → BLOCK
+    // This catches the case where user uploads documents but deploys a workflow that won't use them
+    if (!hasSearchNodes && dataSourceStats && dataSourceStats.success > 0) {
+        return {
+            error: "DEPLOYMENT BLOCKED: Persona has indexed knowledge files but workflow has no search nodes. The uploaded documents will NEVER be used.",
+            mode: "deploy",
+            persona_id: personaId,
+            persona_name: persona.name,
+            validation_failed: "data_sources_require_search_nodes",
+            current_state: {
+                search_nodes_detected: false,
+                data_sources_total: dataSourceStats.total,
+                data_sources_indexed: dataSourceStats.success,
+            },
+            _fix: [
+                "Your workflow needs a search node to query the uploaded documents.",
+                "1. Get workflow schema: workflow(mode='get', persona_id='...')",
+                "2. Add search node: Update workflow_def to include a search/v2 node that queries the knowledge base",
+                "3. Wire it up: Connect chat_trigger → summarizer → search → respond_for_external_actions",
+                "Example pattern: trigger → conversation_summarizer → search/v2 → respond_for_external_actions → WORKFLOW_OUTPUT",
+            ],
+            _example_workflow_pattern: {
+                nodes: [
+                    "chat_trigger (trigger)",
+                    "conversation_summarizer (extract query from conversation)",
+                    "search/v2 (query knowledge base with datastore_configs)",
+                    "respond_for_external_actions (generate response with sources)",
+                ],
+                flow: "trigger → summarizer → search → respond → output",
+            },
+        };
+    }
     // Sanitize workflow before deployment
     const sanitizedWorkflow = sanitizeWorkflowForDeploy(workflowDef);
+    // Check for deprecated actions (warn, don't block)
+    const deprecationWarnings = checkWorkflowDeprecations(workflowDef, DEPRECATED_ACTIONS_FALLBACK);
     // 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 isVoice = projectSettings?.projectType === PROJECT_TYPES.voice;
     const warnings = [];
+    // Add deprecation warning message if deprecated actions found
+    if (deprecationWarnings.length > 0) {
+        warnings.push(`Workflow uses ${deprecationWarnings.length} deprecated action(s). ` +
+            "Consider updating to prevent future breakage when deprecated actions are removed.");
+    }
     if (isVoice && !providedProtoConfig) {
         // Check if existing proto_config has conversationSettings populated
         const widgets = (protoConfigToUse.widgets ?? []);
@@ -58,6 +211,12 @@ export async function handleWorkflowDeploy(args, client) {
         if (warnings.length > 0) {
             result.warnings = warnings;
         }
+        // Include detailed deprecation info if any deprecated actions found
+        if (deprecationWarnings.length > 0) {
+            result.deprecation_warnings = deprecationWarnings;
+            result._warning = "Workflow deployed but contains deprecated actions. Update before platform removes them.";
+            result._next_step = "Use workflow(mode='get') to see current schema, then deploy updated workflow_def with non-deprecated actions.";
+        }
         return result;
     }
     catch (err) {

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

@@ -10,7 +10,7 @@
  */
 import { parseInput, intentToSpec, generateWorkflow } from "../../../sdk/workflow-intent.js";
 import { compileWorkflow } from "../../../sdk/workflow-generator.js";
-import { detectWorkflowIssues } from "../../../sdk/knowledge.js";
+// Detection removed - LLM analyzes with rules from ema://rules/*
 import { runIntentArchitect } from "../../../sdk/intent-architect.js";
 import { ensureActionRegistry } from "../../../sdk/action-registry.js";
 import { ensureSchemaRegistry, validateWorkflowSpec, generateActionCatalogForLLM } from "../../../sdk/workflow-validator.js";
@@ -142,30 +142,13 @@ async function deployToNewPersona(args, client, compiled, actionRegistry, getTem
         widgets: Array.from(widgetMap.values()),
     };
     // Step 4: Deploy workflow
-    const existingWorkflow = newPersona.workflow_def;
-    const existingWfName = existingWorkflow?.workflowName;
-    const workflowForDeploy = JSON.parse(JSON.stringify(compiled.workflow_def));
-    const wfName = workflowForDeploy.workflowName;
-    if (wfName?.name && existingWfName?.name) {
-        wfName.name.namespaces = existingWfName.name.namespaces;
-        wfName.name.name = existingWfName.name.name;
-    }
-    // Fix results format
-    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;
-    }
+    // 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: workflowForDeploy,
+            workflow: compiled.workflow_def,
             proto_config: mergedProtoConfig,
         }, { verbose: true });
         return { success: true, personaId: newPersonaId, personaName };
@@ -182,7 +165,7 @@ async function deployToNewPersona(args, client, compiled, actionRegistry, getTem
             personaId: newPersonaId,
             personaName,
             workflowDeployError: errMsg,
-            workflowAttempted: workflowForDeploy,
+            workflowAttempted: compiled.workflow_def,
         };
     }
 }
@@ -288,14 +271,14 @@ export async function handleWorkflowGenerate(args, client, getTemplateId) {
         }
     }
     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,
+        // LLM should analyze with ema://rules/anti-patterns
+        _analysis_hint: "Use ema://rules/anti-patterns to check for issues",
     };
     if (specValidation) {
         result.api_validation = {
@@ -304,9 +287,6 @@ export async function handleWorkflowGenerate(args, client, getTemplateId) {
             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);

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

@@ -1,43 +1,228 @@
 /**
- * Workflow Handler - Unified greenfield/brownfield operations
+ * Workflow Handler
  *
- * 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
+ * PUBLIC TOOL MODES (workflow tool):
+ * - get: Return workflow data + schema for LLM to generate/modify
+ * - deploy: Deploy LLM-generated workflow_def
  *
- * Note: During extraction, individual mode handlers are being moved here.
- * Until complete, delegates to handlers-consolidated.ts.
+ * INTERNAL MODES (called from persona tool, not exposed):
+ * - modify: Used internally by persona(method="update", input="...")
+ * - generate: Used internally for workflow generation
+ * - analyze: Used internally for workflow analysis
+ * - optimize: Used internally for auto-fix
+ * - compare: Used internally for comparison
+ *
+ * THE LLM DOES ALL THE THINKING. MCP provides data and executes.
  */
+import { generateSchema } from "../../../sdk/generation-schema.js";
 // Re-export types
 export * from "./types.js";
-// Re-export utilities
+// Re-export utilities  
 export * from "./utils.js";
-// Import mode handlers
+// Import internal handlers (not exposed as tool modes, but used internally)
 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
+// Re-export for internal use (persona handler routes to these)
 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";
+// Fallback deprecated actions - ONLY used when API unavailable
+// Source: ema/ema_backend/grpc/workflow_actions/registered_actions.py (synced 2026-01-26)
+// Exported for use by deploy handler
+export const DEPRECATED_ACTIONS_FALLBACK = {
+    "search/v0": { replacement: "search/v2", notes: "v2 requires datastore_configs input" },
+    "web_search/v0": { replacement: "live_web_search or ai_web_search", notes: "Split into two specialized actions" },
+    "call_llm/v0": { replacement: "call_llm/v2" },
+    "human_collaboration/v0": { replacement: "general_hitl" },
+    "fixed_response/v0": { replacement: "fixed_response/v1" },
+    "custom_agent/v0": { replacement: "custom_agent/v1" },
+    "json_mapper/v0": { replacement: "json_mapper/v1" },
+    "text_categorizer/v0": { replacement: "text_categorizer/v1" },
+    "respond_with_sources/v0": { replacement: "respond_for_external_actions", notes: "Handles tool results better" },
+};
+/**
+ * Get deprecated actions from API (with fallback)
+ * Returns map of action/version -> replacement info
+ */
+async function getDeprecatedActions(client) {
+    try {
+        const actions = await client.listActions();
+        const deprecated = {};
+        for (const action of actions) {
+            if (action.deprecated) {
+                // Use action name as key (API doesn't include version in deprecated flag)
+                deprecated[action.id] = {
+                    notes: "Deprecated - check catalog for current version",
+                };
+            }
+        }
+        // Merge with fallback to get replacement info
+        for (const [key, info] of Object.entries(DEPRECATED_ACTIONS_FALLBACK)) {
+            const actionName = key.split("/")[0];
+            if (deprecated[actionName] || !deprecated[key]) {
+                deprecated[key] = { ...info, ...deprecated[key] };
+            }
+        }
+        return { deprecated, source: "api" };
+    }
+    catch {
+        // API unavailable, use fallback
+        return { deprecated: DEPRECATED_ACTIONS_FALLBACK, source: "fallback" };
+    }
+}
+/**
+ * Check if workflow uses deprecated actions
+ * Exported for use by deploy handler
+ */
+export function checkWorkflowDeprecations(workflowDef, deprecatedActions) {
+    if (!workflowDef)
+        return [];
+    const warnings = [];
+    const actions = (workflowDef.actions ?? []);
+    for (const action of actions) {
+        const actionName = action.action?.name?.name;
+        const version = action.action?.name?.version || "v0";
+        if (!actionName)
+            continue;
+        const key = `${actionName}/${version}`;
+        const deprecation = deprecatedActions[key] || deprecatedActions[actionName];
+        if (deprecation) {
+            warnings.push({
+                action: action.name,
+                version,
+                replacement: deprecation.replacement,
+                notes: deprecation.notes,
+                severity: "warning",
+            });
+        }
+    }
+    return warnings;
+}
+/**
+ * Handle workflow(mode="get") - return data + schema + guidance for LLM
+ *
+ * Returns:
+ * - Current workflow_def (if exists)
+ * - Deprecation warnings for current workflow
+ * - Generation schema (agents, types, constraints)
+ * - Requirements and guidance (NOT hardcoded templates)
+ * - Available widgets
+ *
+ * LLM uses this to generate or modify workflow_def
+ */
+async function handleWorkflowGet(args, client) {
+    const personaId = args.persona_id;
+    if (!personaId) {
+        return { error: "persona_id required" };
+    }
+    const persona = await client.getPersonaById(personaId);
+    if (!persona) {
+        return { error: `Persona not found: ${personaId}` };
+    }
+    const protoConfig = persona.proto_config;
+    const widgets = (protoConfig?.widgets ?? []);
+    const workflowDef = persona.workflow_def;
+    // Extract available widget names for LLM
+    const availableWidgets = widgets
+        .filter(w => typeof w.name === "string")
+        .map(w => ({
+        name: w.name,
+        type: w.type,
+    }));
+    // Get generation schema for LLM
+    const schema = generateSchema();
+    // Get deprecated actions (API-first, with fallback)
+    const { deprecated: deprecatedActions, source: deprecationSource } = await getDeprecatedActions(client);
+    // Check if current workflow uses deprecated actions
+    const deprecationWarnings = checkWorkflowDeprecations(workflowDef, deprecatedActions);
+    // Build response
+    const result = {
+        persona_id: persona.id,
+        persona_name: persona.name,
+        persona_type: persona.type,
+        workflow_def: workflowDef ?? null,
+        available_widgets: availableWidgets,
+        // Deprecation warnings (severity: warning)
+        deprecation_warnings: deprecationWarnings.length > 0 ? deprecationWarnings : undefined,
+        deprecated_actions_source: deprecationWarnings.length > 0 ? deprecationSource : undefined,
+        // Schema for LLM to generate valid workflow_def
+        generation_schema: {
+            agents: schema.agents,
+            constraints: schema.constraints,
+            input_rules: schema.inputRules,
+        },
+        // HARD REQUIREMENTS (must be satisfied)
+        hard_requirements: {
+            workflow_output: {
+                rule: "Every workflow MUST have results.WORKFLOW_OUTPUT mapped to a final action output",
+                format: '{ "results": { "WORKFLOW_OUTPUT": { "actionName": "...", "outputName": "..." } } }',
+                failure: "Persona cannot be activated without this",
+            },
+            workflow_name: {
+                rule: "workflowName must be ['ema', 'personas', '<persona_id>']",
+                format: '{ "workflowName": ["ema", "personas", "actual-persona-id"] }',
+            },
+            action_structure: {
+                rule: "Each action needs: name (unique ID), action.name (namespaces, name, version), action.inputs",
+                namespaces: "Most actions use ['actions', 'emainternal'], triggers use ['triggers', 'emainternal']",
+            },
+            no_deprecated_actions: deprecationWarnings.length > 0 ? {
+                rule: "Update deprecated actions before deploying",
+                warnings: deprecationWarnings,
+            } : undefined,
+        },
+        // GUIDANCE (best practices, not hard requirements)
+        guidance: {
+            flow_pattern: "trigger → categorizer (optional) → processing → response → WORKFLOW_OUTPUT",
+            categorizer: "For multi-intent workflows, use chat_categorizer early with a Fallback category",
+            fallback: "Every categorizer MUST have a Fallback category for unmatched intents",
+            hitl: "For actions with side effects (email, external calls), consider general_hitl for approval",
+            search: "Use search/v2 with datastore_configs. Wire query from trigger output.",
+        },
+        // LLM-driven analysis pattern: MCP provides data, LLM does the thinking
+        _next_steps: deprecationWarnings.length > 0
+            ? [
+                "WARNING: Workflow uses deprecated actions. Update them first:",
+                ...deprecationWarnings.map(w => `  - ${w.action}: ${w.replacement || "check catalog for replacement"}`),
+                "",
+                "To analyze workflow health:",
+                "1. Fetch ema://rules/anti-patterns",
+                "2. Fetch ema://rules/structural-invariants",
+                "3. Check workflow_def nodes against the rules",
+                "4. Report issues YOU find (MCP does not pre-compute)",
+                "",
+                "Then deploy with: workflow(mode='deploy', persona_id='...', workflow_def={...})",
+            ]
+            : [
+                "To analyze workflow health:",
+                "1. Fetch ema://rules/anti-patterns",
+                "2. Fetch ema://rules/structural-invariants",
+                "3. Check workflow_def nodes against the rules",
+                "4. Report issues YOU find (MCP does not pre-compute)",
+                "",
+                "Generate or modify workflow_def based on requirements above",
+                "Deploy with: workflow(mode='deploy', persona_id='...', workflow_def={...})",
+            ],
+    };
+    // Include deprecated actions reference if there are warnings or on request
+    if (deprecationWarnings.length > 0 || args.include_deprecated) {
+        result.deprecated_actions_reference = deprecatedActions;
+    }
+    return result;
+}
 /**
  * Main workflow handler with mode-based dispatch
  *
- * Routes to the appropriate extracted handler based on effective mode.
+ * PUBLIC modes: get, deploy
+ * INTERNAL modes: modify, generate, analyze, optimize, compare (called from persona tool)
  */
 export async function handleWorkflow(args, client, getTemplateId) {
     const personaId = args.persona_id;
@@ -46,90 +231,78 @@ export async function handleWorkflow(args, client, getTemplateId) {
     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}` };
+    // Explicit mode takes priority
+    const mode = args.mode;
+    // PUBLIC MODES (from workflow tool)
+    if (mode === "get") {
+        return handleWorkflowGet(args, client);
+    }
+    if (mode === "deploy") {
+        return handleWorkflowDeploy(args, client);
+    }
+    // INTERNAL MODES (called from persona tool, not workflow tool)
+    if (mode === "modify" || mode === "extend") {
+        return handleWorkflowModify(args, client);
+    }
+    if (mode === "generate") {
+        return handleWorkflowGenerate(args, client, getTemplateId);
+    }
+    if (mode === "analyze") {
+        return handleWorkflowAnalyze(args, client);
+    }
+    if (mode === "optimize") {
+        return handleWorkflowOptimize(args, client);
+    }
+    if (mode === "compare") {
+        return handleWorkflowCompare(args, client);
+    }
+    // Auto-detect mode (for backwards compatibility with internal routing)
+    if (compareTo) {
+        return handleWorkflowCompare(args, client);
+    }
+    if (optimize && personaId) {
+        return handleWorkflowOptimize(args, client);
+    }
+    if (personaId && workflowDef) {
+        return handleWorkflowDeploy(args, client);
     }
+    if (personaId && (input || operations)) {
+        return handleWorkflowModify(args, client);
+    }
+    if (input && !personaId) {
+        return handleWorkflowGenerate(args, client, getTemplateId);
+    }
+    if (personaId) {
+        return handleWorkflowAnalyze(args, client);
+    }
+    // Invalid mode
+    return {
+        error: `Invalid or missing mode: ${mode}`,
+        public_modes: ["get", "deploy"],
+        hint: "MCP provides data (get) and executes (deploy). LLM does all thinking.",
+    };
 }
 /**
  * Check if a workflow mode has been extracted
  */
 export function hasExtractedWorkflowHandler(mode) {
-    const extractedModes = ["analyze", "compare", "compile", "optimize", "deploy", "generate", "modify", "extend"];
+    const extractedModes = ["get", "deploy", "modify", "extend", "generate", "analyze", "optimize", "compare"];
     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 "get":
         case "deploy":
-            return handleWorkflowDeploy;
-        case "generate":
-            return handleWorkflowGenerate;
         case "modify":
         case "extend":
-            return handleWorkflowModify;
+        case "generate":
+        case "analyze":
+        case "optimize":
+        case "compare":
+            return handleWorkflow;
         default:
             return undefined;
     }