@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/mcp/handlers/persona/version.js

@@ -1,11 +1,11 @@
 /**
  * Version Management Handlers
  *
- * Provides local version tracking for personas (snapshot, history, restore).
- * Versions are stored in the local workspace, not on the Ema platform.
+ * Provides version tracking for personas (snapshot, history, restore).
+ * Uses IVersionStorage — can be local (.ema-versions/) or central (DIS).
  */
-import { createVersionStorage } from "../../../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { createCentralStorageEngine, migrateLocalToCentral } from "../../../sync/central-factory.js";
+import { VersionStorage } from "../../../sync/version-storage.js";
 /**
  * Check if a mode is a version management mode.
  */
@@ -32,20 +32,27 @@ export function isVersionMode(mode) {
  * @param versionContext - Workspace and environment context
  */
 export async function handleVersion(mode, args, client, persona, versionContext) {
-    const storage = createVersionStorage(versionContext.workspaceRoot);
-    const engine = createVersionPolicyEngine(storage);
+    const { storage, engine } = createCentralStorageEngine(client, persona.id);
     switch (mode) {
         // ─────────────────────────────────────────────────────────────────────────
         // snapshot / version_create - Create a new version snapshot
         // ─────────────────────────────────────────────────────────────────────────
         case "snapshot":
         case "version_create": {
+            // Lazy migration: seed central from local on first snapshot
+            try {
+                const localStorage = new VersionStorage(versionContext.workspaceRoot);
+                await migrateLocalToCentral(localStorage, storage, persona.id);
+            }
+            catch {
+                // Best-effort: migration failure should not block snapshot creation
+            }
             // Fetch full persona with workflow
             const fullPersona = await client.getPersonaById(persona.id);
             if (!fullPersona) {
                 return { error: `Could not fetch full persona: ${persona.id}` };
             }
-            const result = engine.forceCreateVersion(fullPersona, {
+            const result = await engine.forceCreateVersion(fullPersona, {
                 environment: versionContext.environment,
                 tenant_id: versionContext.tenant_id,
                 message: args.message,
@@ -73,7 +80,15 @@ export async function handleVersion(mode, args, client, persona, versionContext)
         // ─────────────────────────────────────────────────────────────────────────
         case "history":
         case "version_list": {
-            const versions = engine.listVersions(persona.id, {
+            // Lazy migration: seed central from local so history shows existing versions
+            try {
+                const localStorage = new VersionStorage(versionContext.workspaceRoot);
+                await migrateLocalToCentral(localStorage, storage, persona.id);
+            }
+            catch {
+                // Best-effort
+            }
+            const versions = await engine.listVersions(persona.id, {
                 limit: args.limit,
             });
             return {
@@ -88,7 +103,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
         // ─────────────────────────────────────────────────────────────────────────
         case "version_get": {
             const versionId = args.version ?? "latest";
-            const version = engine.getVersion(persona.id, versionId);
+            const version = await engine.getVersion(persona.id, versionId);
             if (!version) {
                 return { error: `Version not found: ${versionId}` };
             }
@@ -126,7 +141,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
             if (!v1 || !v2) {
                 return { error: "v1 and v2 required for version_compare mode" };
             }
-            const result = engine.compareVersions(persona.id, v1, v2);
+            const result = await engine.compareVersions(persona.id, v1, v2);
             if (!result.success) {
                 return { error: result.error };
             }
@@ -152,14 +167,14 @@ export async function handleVersion(mode, args, client, persona, versionContext)
             if (!versionId) {
                 return { error: "version required for restore mode" };
             }
-            const restoreData = engine.getRestoreData(persona.id, versionId);
+            const restoreData = await engine.getRestoreData(persona.id, versionId);
             if (!restoreData.success || !restoreData.restore_payload) {
                 return { error: restoreData.error ?? "Failed to get restore data" };
             }
             // Create a version snapshot before restoring (audit trail)
             const fullPersona = await client.getPersonaById(persona.id);
             if (fullPersona) {
-                engine.forceCreateVersion(fullPersona, {
+                await engine.forceCreateVersion(fullPersona, {
                     environment: versionContext.environment,
                     tenant_id: versionContext.tenant_id,
                     message: `Before restore to ${restoreData.version?.version_name}`,
@@ -180,7 +195,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
             // Create post-restore version
             const restoredPersona = await client.getPersonaById(persona.id);
             if (restoredPersona) {
-                engine.forceCreateVersion(restoredPersona, {
+                await engine.forceCreateVersion(restoredPersona, {
                     environment: versionContext.environment,
                     tenant_id: versionContext.tenant_id,
                     message: `Restored to ${restoreData.version?.version_name}`,
@@ -207,7 +222,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
                 args.auto_on_sync !== undefined ||
                 args.max_versions !== undefined;
             if (hasUpdates) {
-                const updated = engine.updatePolicy(persona.id, {
+                const updated = await engine.updatePolicy(persona.id, {
                     auto_version_on_deploy: args.auto_on_deploy,
                     auto_version_on_sync: args.auto_on_sync,
                     max_versions: args.max_versions,
@@ -221,7 +236,7 @@ export async function handleVersion(mode, args, client, persona, versionContext)
                 };
             }
             // Just get current policy
-            const policy = engine.getPolicy(persona.id);
+            const policy = await engine.getPolicy(persona.id);
             return {
                 persona_id: persona.id,
                 persona_name: persona.name,

package/dist/mcp/handlers/template/adapter.js

@@ -0,0 +1,23 @@
+/**
+ * Template Adapter
+ *
+ * Routes CRUD methods (list/get/create/update/delete) to the new crud handler.
+ * Non-CRUD calls (patterns, widgets, config, questions) fall through to the
+ * existing handleTemplate handler for backwards compatibility.
+ *
+ * Same pattern as debug/adapter.ts.
+ */
+import { handleTemplateCrud } from "./crud.js";
+import { handleTemplate } from "./index.js";
+const CRUD_METHODS = new Set(["list", "get", "create", "update", "delete"]);
+export async function handleTemplateAdapter(args, createClient, getDefaultEnvName) {
+    const method = args.method;
+    // Route CRUD methods to the new handler
+    if (method && CRUD_METHODS.has(method)) {
+        const targetEnv = args.env ?? getDefaultEnvName();
+        const client = createClient(targetEnv);
+        return handleTemplateCrud(args, client);
+    }
+    // Legacy calls (patterns, widgets, config, questions) go to existing handler
+    return handleTemplate(args);
+}

package/dist/mcp/handlers/template/crud.js

@@ -0,0 +1,174 @@
+/**
+ * Template CRUD Handler — Method Dispatch
+ *
+ * Routes template CRUD methods to the appropriate SDK calls.
+ * Follows the handler pattern from debug/index.ts.
+ */
+const METHODS = ["list", "get", "create", "update", "delete"];
+/**
+ * Map friendly type names to PersonaTriggerTypeEnum values.
+ * The backend DB rejects "UNSPECIFIED" (proto default 0), so a valid
+ * trigger_type must always be provided on create.
+ */
+const TRIGGER_TYPE_MAP = {
+    chat: 1,
+    chatbot: 1,
+    dashboard: 2,
+    extraction: 2,
+    agent_assist: 3,
+    conversational: 4,
+    document: 5,
+    email: 6,
+    agent_qa: 7,
+    voice: 1, // voice personas use CHATBOT trigger type
+};
+function resolveTriggerType(type) {
+    if (!type)
+        return 1; // default to CHATBOT
+    const asNumber = Number(type);
+    if (!isNaN(asNumber) && asNumber >= 1 && asNumber <= 7)
+        return asNumber;
+    return TRIGGER_TYPE_MAP[type.toLowerCase()] ?? 1;
+}
+export async function handleTemplateCrud(args, client) {
+    const method = args.method;
+    if (!method) {
+        return {
+            error: "Missing required parameter: method",
+            available_methods: [...METHODS],
+            _tip: "Start with template(method='list') to browse available templates.",
+        };
+    }
+    switch (method) {
+        case "list":
+            return handleList(args, client);
+        case "get":
+            return handleGet(args, client);
+        case "create":
+            return handleCreate(args, client);
+        case "update":
+            return handleUpdate(args, client);
+        case "delete":
+            return handleDelete(args, client);
+        default:
+            return {
+                error: `Unknown method: ${method}`,
+                available_methods: [...METHODS],
+            };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Method handlers
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleList(args, client) {
+    const templates = await client.getPersonaTemplates();
+    // Apply optional filters
+    let filtered = templates;
+    const query = args.query;
+    if (query) {
+        const q = query.toLowerCase();
+        filtered = filtered.filter((t) => t.name?.toLowerCase().includes(q) ||
+            t.description?.toLowerCase().includes(q));
+    }
+    const type = args.type;
+    if (type) {
+        // Map friendly type names to trigger_type values
+        const typeMap = {
+            voice: "VOICEBOT_AI_EMPLOYEE",
+            chat: "CHATBOT",
+            dashboard: "DOCUMENT_TRIGGER",
+        };
+        const triggerType = typeMap[type.toLowerCase()] ?? type;
+        filtered = filtered.filter((t) => t.trigger_type === triggerType);
+    }
+    const category = args.category;
+    if (category) {
+        const c = category.toLowerCase();
+        filtered = filtered.filter((t) => t.category?.toLowerCase() === c);
+    }
+    return {
+        count: filtered.length,
+        templates: filtered.map((t) => ({
+            id: t.id,
+            name: t.name,
+            description: t.description,
+            category: t.category,
+            trigger_type: t.trigger_type,
+            has_project_template: t.has_project_template,
+        })),
+    };
+}
+async function handleGet(args, client) {
+    const id = args.id;
+    if (!id) {
+        return { error: "Missing required parameter: id" };
+    }
+    const template = await client.getPersonaTemplateById(id);
+    if (!template) {
+        return { error: `Template not found: ${id}` };
+    }
+    return template;
+}
+async function handleCreate(args, client) {
+    const name = args.name;
+    if (!name) {
+        return { error: "Missing required parameter: name" };
+    }
+    // Resolve trigger_type: the backend DB rejects proto default "UNSPECIFIED",
+    // so we must always provide a valid numeric trigger_type.
+    const triggerType = resolveTriggerType(args.type);
+    const result = await client.createPersonaTemplate({
+        name,
+        description: args.description,
+        proto_config: args.proto_config,
+        trigger_type: String(triggerType),
+        category: args.category,
+        about_template: args.about_template,
+        workflow_def: args.workflow_def,
+        source_template_id: args.from,
+    });
+    return {
+        success: true,
+        template_id: result.template_id,
+        name,
+        _tip: `Template created. Use template(method='get', id='${result.template_id}') to view it.`,
+    };
+}
+async function handleUpdate(args, client) {
+    const id = args.id;
+    if (!id) {
+        return { error: "Missing required parameter: id" };
+    }
+    const result = await client.updatePersonaTemplate({
+        template_id: id,
+        name: args.name,
+        description: args.description,
+        proto_config: args.proto_config,
+        category: args.category,
+        about_template: args.about_template,
+        workflow_def: args.workflow_def,
+    });
+    return {
+        success: true,
+        template_id: id,
+        ...result,
+    };
+}
+async function handleDelete(args, client) {
+    const id = args.id;
+    if (!id) {
+        return { error: "Missing required parameter: id" };
+    }
+    const confirm = args.confirm;
+    if (confirm !== true) {
+        return {
+            error: "Deletion requires confirm=true",
+            _tip: `To delete template ${id}, call template(method='delete', id='${id}', confirm=true)`,
+        };
+    }
+    await client.deletePersonaTemplate(id);
+    return {
+        success: true,
+        deleted_template_id: id,
+    };
+}

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

@@ -15,8 +15,7 @@ import { getTemplateFallback, getTemplateFieldDocs } from "../../../sdk/generate
 export function handleTemplate(args) {
     // Get specific pattern
     if (args.pattern) {
-        const patternName = args.pattern;
-        const pattern = WORKFLOW_PATTERNS[patternName];
+        const pattern = WORKFLOW_PATTERNS.find(p => p.name === args.pattern);
         if (!pattern) {
             return { error: `Pattern not found: ${args.pattern}` };
         }
@@ -24,14 +23,14 @@ export function handleTemplate(args) {
     }
     // List patterns
     if (args.patterns) {
-        let patterns = Object.entries(WORKFLOW_PATTERNS);
+        let filtered = WORKFLOW_PATTERNS;
         if (args.type) {
-            patterns = patterns.filter(([_, p]) => !p.personaType || p.personaType === args.type);
+            filtered = filtered.filter(p => !p.personaType || p.personaType === args.type);
         }
         return {
-            count: patterns.length,
-            patterns: patterns.map(([name, p]) => ({
-                name,
+            count: filtered.length,
+            patterns: filtered.map(p => ({
+                name: p.name,
                 description: p.description,
                 use_case: p.useCase,
                 persona_type: p.personaType,

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

@@ -7,8 +7,7 @@
  * Extracted from server.ts to keep the dispatch table thin.
  */
 import { fingerprintPersona } from "../../../sync.js";
-import { createVersionStorage } from "../../../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { createCentralStorageEngine } from "../../../sync/central-factory.js";
 import { handleWorkflow } from "./index.js";
 import { handleWorkflowOptimize } from "./optimize.js";
 export async function handleWorkflowAdapter(args, createClient, getDefaultEnvName) {
@@ -84,60 +83,45 @@ export async function handleWorkflowAdapter(args, createClient, getDefaultEnvNam
                 return { error: 'persona_id is required for workflow(mode="deploy")' };
             }
             const targetEnv = normalizedArgs.env ?? getDefaultEnvName();
+            // Fetch persona and validate fingerprint (blocking — these are safety checks)
+            const personaBefore = await client.getPersonaById(personaId);
+            if (!personaBefore) {
+                return { error: `Persona not found: ${personaId}` };
+            }
+            const currentFp = fingerprintPersona(personaBefore);
+            if (!force && !baseFingerprint) {
+                return {
+                    error: "base_fingerprint is required for workflow deploy (stale-state protection)",
+                    persona_id: personaId,
+                    current_fingerprint: currentFp,
+                    hint: "Run workflow(mode='get', persona_id='...') immediately before deploying and pass fingerprint as base_fingerprint. Use force=true only for emergency overrides.",
+                };
+            }
+            if (!force && baseFingerprint && baseFingerprint !== currentFp) {
+                return {
+                    error: "Persona changed since you last fetched it (fingerprint mismatch)",
+                    persona_id: personaId,
+                    base_fingerprint: baseFingerprint,
+                    current_fingerprint: currentFp,
+                    hint: "Re-run workflow(mode='get') to fetch the latest workflow_def, re-apply your edits, then deploy again. Use force=true only if you intend to overwrite out-of-band changes.",
+                };
+            }
+            // Best-effort: snapshot before any destructive change (via central DIS storage)
             let versionCreated;
             try {
-                const personaBefore = await client.getPersonaById(personaId);
-                if (!personaBefore) {
-                    return { error: `Persona not found: ${personaId}` };
-                }
-                const currentFp = fingerprintPersona(personaBefore);
-                if (!force && !baseFingerprint) {
-                    return {
-                        error: "base_fingerprint is required for workflow deploy (stale-state protection)",
-                        persona_id: personaId,
-                        current_fingerprint: currentFp,
-                        hint: "Run workflow(mode='get', persona_id='...') immediately before deploying and pass fingerprint as base_fingerprint. Use force=true only for emergency overrides.",
-                    };
-                }
-                if (!force && baseFingerprint && baseFingerprint !== currentFp) {
-                    return {
-                        error: "Persona changed since you last fetched it (fingerprint mismatch)",
-                        persona_id: personaId,
-                        base_fingerprint: baseFingerprint,
-                        current_fingerprint: currentFp,
-                        hint: "Re-run workflow(mode='get') to fetch the latest workflow_def, re-apply your edits, then deploy again. Use force=true only if you intend to overwrite out-of-band changes.",
-                    };
-                }
-                const storage = createVersionStorage(process.cwd());
-                const engine = createVersionPolicyEngine(storage);
-                const snap = engine.forceCreateVersion(personaBefore, {
+                const { engine } = createCentralStorageEngine(client, personaId);
+                const snap = await engine.forceCreateVersion(personaBefore, {
                     environment: targetEnv,
                     tenant_id: targetEnv,
                     message: "Pre-deploy snapshot",
                     created_by: "mcp-toolkit",
                 });
-                if (!snap.created || !snap.version) {
-                    if (!force) {
-                        return {
-                            error: "Failed to create pre-deploy snapshot (required before deploy)",
-                            persona_id: personaId,
-                            details: snap.reason,
-                            hint: "Fix snapshotting (workspace storage) or retry with force=true for emergency override.",
-                        };
-                    }
-                }
-                else {
+                if (snap.created && snap.version) {
                     versionCreated = { id: snap.version.id, version_name: snap.version.version_name };
                 }
             }
-            catch (snapshotErr) {
-                if (!force) {
-                    return {
-                        error: "Failed to create pre-deploy snapshot (required before deploy)",
-                        persona_id: personaId,
-                        hint: "Retry after fixing local workspace write access, or use force=true for emergency override.",
-                    };
-                }
+            catch {
+                // Best-effort: snapshot failure does not block the deploy
             }
             const deployResult = await handleWorkflow({
                 mode: "deploy",

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

@@ -43,7 +43,7 @@ export const DEPRECATED_ACTIONS_FALLBACK = {
     "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" },
+    "respond_with_sources/v0": { replacement: "call_llm with named_inputs", notes: "For KB Q&A use call_llm; respond_for_external_actions is ONLY for external_action_caller results" },
 };
 /**
  * Get deprecated actions from API (with fallback)
@@ -183,7 +183,7 @@ async function handleWorkflowGet(args, client) {
             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), enable the HITL flag on the agent — do NOT add standalone general_hitl nodes",
+            hitl: "Two HITL mechanisms: 1) general_hitl (Human Collaboration Agent) for rich dialogue/forms, 2) disable_human_interaction: false flag on send_email_agent or entity_extraction_with_documents for simple approval",
             search: "Use search/v2 with datastore_configs. Wire query from trigger output.",
         },
         // LLM-driven analysis pattern: MCP provides data, LLM does the thinking

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

@@ -167,7 +167,7 @@ const KNOWLEDGE_SEARCH_TYPES = [
     "search_datastore",
     "knowledge_search",
     "semantic_search",
-    "combine_search_results",
+    "combine_and_rerank_search_results",
 ];
 /**
  * Known web search action types (excluded from knowledge search detection).
@@ -222,7 +222,7 @@ export function getSearchNodeWidgetNames(workflowDef) {
         const elements = dc?.multiBinding?.elements ?? [];
         for (const el of elements) {
             const name = el.widgetConfig?.widgetName;
-            if (typeof name === "string" && name.trim().length > 0) {
+            if (typeof name === "string" && name.trim().length > 0 && !name.startsWith("_")) {
                 widgetNames.add(name.trim());
             }
         }