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

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

@@ -0,0 +1,294 @@
+/**
+ * Workflow Handler
+ *
+ * PUBLIC TOOL MODES (workflow tool):
+ * - get: Return workflow data + schema for LLM to generate/modify
+ * - deploy: Deploy LLM-generated workflow_def
+ *
+ * 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  
+export * from "./utils.js";
+// Import internal handlers (not exposed as tool modes, but used internally)
+import { handleWorkflowAnalyze } from "./analyze.js";
+import { handleWorkflowCompare } from "./compare.js";
+import { handleWorkflowOptimize } from "./optimize.js";
+import { handleWorkflowDeploy } from "./deploy.js";
+import { handleWorkflowGenerate } from "./generate.js";
+import { handleWorkflowModify } from "./modify.js";
+// Re-export for internal use (persona handler routes to these)
+export { handleWorkflowAnalyze } from "./analyze.js";
+export { handleWorkflowCompare } from "./compare.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)
+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
+ */
+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.",
+        },
+        // Tell LLM to check for deprecated actions if any exist
+        _next_steps: deprecationWarnings.length > 0
+            ? [
+                "WARNING: Workflow uses deprecated actions. Update them first:",
+                ...deprecationWarnings.map(w => `  - ${w.action}: ${w.replacement || "check catalog for replacement"}`),
+                "Then deploy with: workflow(mode='deploy', persona_id='...', workflow_def={...})",
+            ]
+            : [
+                "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
+ *
+ * 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;
+    const workflowDef = args.workflow_def;
+    const input = args.input;
+    const optimize = args.optimize;
+    const compareTo = args.compare_to;
+    const operations = args.operations;
+    // 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 = ["get", "deploy", "modify", "extend", "generate", "analyze", "optimize", "compare"];
+    return extractedModes.includes(mode);
+}
+/**
+ * Get handler for a specific workflow mode
+ */
+export function getWorkflowModeHandler(mode) {
+    switch (mode) {
+        case "get":
+        case "deploy":
+        case "modify":
+        case "extend":
+        case "generate":
+        case "analyze":
+        case "optimize":
+        case "compare":
+            return handleWorkflow;
+        default:
+            return undefined;
+    }
+}