@ema.co/mcp-toolkit 2026.2.19 → 2026.2.23

package/dist/mcp/server.js

@@ -24,34 +24,30 @@ export { TOOLKIT_NAME, TOOLKIT_VERSION, TOOLKIT_COMMIT };
 import { PromptRegistry, isPromptError } from "./prompts.js";
 import { ResourceRegistry, isResourceError } from "./resources.js";
 import { generateServerInstructions, getContextualTip, TOOL_GUIDANCE } from "./guidance.js";
-import { resolveSyncBehavior, loadSyncOptions } from "../sync/sync-options.js";
-import { fingerprintPersona } from "../sync.js";
-// Direct Sync (Config-less) - extracted to handlers/sync/direct.ts
-import { directSyncPersona, directSyncPersonaById, directSyncAll } from "./handlers/sync/direct.js";
-import { createVersionStorage } from "../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../sync/version-policy.js";
 // V2 Tools
 import { generateTools } from "./tools.js";
-import { handlePersona } from "./handlers/persona/index.js";
+// Handler imports (simple 1-2 line handlers stay inline)
 import { handleEnv } from "./handlers/env/index.js";
 import { handleAction } from "./handlers/action/index.js";
 import { handleTemplate } from "./handlers/template/index.js";
-import { handleKnowledge } from "./handlers/knowledge/index.js";
 import { handleReference } from "./handlers/reference/index.js";
-// Import extracted handlers
-import { handleWorkflow } from "./handlers/workflow/index.js";
 import { handleCatalog } from "./handlers/catalog/index.js";
 import { handleFeedback } from "./handlers/feedback/index.js";
 import { recordTelemetry } from "./handlers/feedback/store.js";
-import { handleConsolidateDemoData, handleGenerateDemoDocument, handleValidateDemoDocument, handleGetDemoDataTemplate, } from "./handlers/demo/index.js";
+// V2 adapters (extracted from server.ts — each owns its routing/transformation logic)
+import { handlePersonaAdapter } from "./handlers/persona/adapter.js";
+import { handleWorkflowAdapter } from "./handlers/workflow/adapter.js";
+import { handleSyncAdapter } from "./handlers/sync/adapter.js";
+import { handleDemoAdapter } from "./handlers/demo/adapter.js";
+import { handleDebugAdapter } from "./handlers/debug/adapter.js";
 // Start token initialization in background (non-blocking)
 void initializeApiKeyTokens();
 // ─────────────────────────────────────────────────────────────────────────────
 // Tool Definitions
 // ─────────────────────────────────────────────────────────────────────────────
 //
-// V2 TOOLS (5 tools) - LLM-optimized minimal interface
-//   - env, persona, catalog, workflow, sync
+// V2 TOOLS (7 tools) - LLM-optimized minimal interface
+//   - env, persona, catalog, workflow, sync, toolkit_feedback, debug
 //   - Defined in: ./tools.ts
 //
 // NAMING CONVENTION:
@@ -62,7 +58,7 @@ void initializeApiKeyTokens();
 /**
  * Generate all available tools
  *
- * V2: 5 tools (persona, catalog, workflow, sync, env) - LLM-optimized
+ * V2: 7 tools (persona, catalog, workflow, sync, env, toolkit_feedback, debug) - LLM-optimized
  *
  * Why V2:
  * - Minimal tool count optimizes LLM tool selection
@@ -88,224 +84,7 @@ const toolHandlers = {
         })), { name: TOOLKIT_NAME, version: TOOLKIT_VERSION, commit: TOOLKIT_COMMIT });
     },
     persona: async (args) => {
-        const targetEnv = args.env ?? getDefaultEnvName();
-        const client = createClient(targetEnv);
-        // Build version context for version management modes
-        const versionContext = {
-            // Store versions in the caller's workspace, not the toolkit install dir.
-            // This must be writable under typical MCP usage (e.g. Cursor workspace).
-            workspaceRoot: process.cwd(),
-            environment: targetEnv,
-            tenant_id: targetEnv, // Use env name as tenant identifier
-        };
-        // ─────────────────────────────────────────────────────────────────────────
-        // V2 Parameter Transformation
-        // Convert v2 structure to v1 mode-based structure for handler compatibility
-        // ─────────────────────────────────────────────────────────────────────────
-        const transformedArgs = { ...args };
-        // ─────────────────────────────────────────────────────────────────────────
-        // Explicit Method API (takes priority over flag-based args)
-        // persona(method="create|get|list|update|delete|sanitize|analyze|compare|clone")
-        // ─────────────────────────────────────────────────────────────────────────
-        if (args.method) {
-            const method = String(args.method);
-            // Map explicit methods to internal modes
-            const methodToMode = {
-                create: "create",
-                get: "get",
-                list: "list",
-                update: "update",
-                delete: "delete",
-                sanitize: "sanitize",
-                analyze: "analyze",
-                compare: "compare",
-                schema: "schema", // get persona input schema (dashboard columns)
-                clone: "create", // clone is create with from
-                snapshot: "version_create",
-                history: "version_list",
-                restore: "version_restore",
-            };
-            const mode = methodToMode[method];
-            if (!mode) {
-                return { error: `Unknown method: ${method}`, valid_methods: Object.keys(methodToMode) };
-            }
-            transformedArgs.mode = mode;
-            delete transformedArgs.method;
-            // Handle action composition if present
-            if (args.actions && Array.isArray(args.actions)) {
-                // Store actions for post-processing after main operation
-                transformedArgs._actions = args.actions;
-                delete transformedArgs.actions;
-            }
-        }
-        // ─────────────────────────────────────────────────────────────────────────
-        // Flag-based API (legacy compatibility)
-        // ONLY applies when explicit `method` parameter was NOT provided
-        // When method is explicit, flags like sanitize=true are passed through
-        // ─────────────────────────────────────────────────────────────────────────
-        // Guard: Skip flag-based API if explicit method was provided
-        const skipFlagBasedApi = !!args.method;
-        // Create: persona(create={name, type, from, input})
-        if (!skipFlagBasedApi && args.create && typeof args.create === "object") {
-            const create = args.create;
-            transformedArgs.mode = "create";
-            transformedArgs.name = create.name;
-            transformedArgs.type = create.type;
-            transformedArgs.from = create.from;
-            transformedArgs.input = create.input;
-            transformedArgs.preview = create.preview ?? true;
-            delete transformedArgs.create;
-        }
-        // Update: persona(id, update={config, input, workflow_spec})
-        else if (!skipFlagBasedApi && args.update && typeof args.update === "object") {
-            const update = args.update;
-            transformedArgs.mode = "update";
-            transformedArgs.proto_config = update.config;
-            transformedArgs.input = update.input;
-            transformedArgs.workflow_spec = update.workflow_spec;
-            transformedArgs.preview = update.preview ?? false; // Default to deploy, not preview
-            delete transformedArgs.update;
-        }
-        // Delete: persona(id, delete=true)
-        else if (!skipFlagBasedApi && args.delete === true) {
-            transformedArgs.mode = "delete";
-            delete transformedArgs.delete;
-        }
-        // Analyze: persona(id, analyze=true, fix=true)
-        else if (!skipFlagBasedApi && args.analyze === true) {
-            transformedArgs.mode = "analyze";
-            // fix is already in args
-            delete transformedArgs.analyze;
-        }
-        // Sanitize: persona(id, sanitize=true)
-        // ONLY converts to mode="sanitize" when method is NOT explicit
-        // When method="create" + sanitize=true, sanitize is a FLAG for post-creation sanitization
-        else if (!skipFlagBasedApi && args.sanitize === true) {
-            transformedArgs.mode = "sanitize";
-            delete transformedArgs.sanitize;
-        }
-        // Snapshot: persona(id, snapshot="message")
-        else if (!skipFlagBasedApi && typeof args.snapshot === "string") {
-            transformedArgs.mode = "version_create";
-            transformedArgs.message = args.snapshot;
-            delete transformedArgs.snapshot;
-        }
-        // History: persona(id, history=true)
-        else if (!skipFlagBasedApi && args.history === true) {
-            transformedArgs.mode = "version_list";
-            delete transformedArgs.history;
-        }
-        // Restore: persona(id, restore="v3")
-        else if (!skipFlagBasedApi && typeof args.restore === "string") {
-            transformedArgs.mode = "version_restore";
-            transformedArgs.version = args.restore;
-            delete transformedArgs.restore;
-        }
-        // Compare: persona(id, compare="other-id")
-        else if (!skipFlagBasedApi && typeof args.compare === "string") {
-            transformedArgs.mode = "compare";
-            transformedArgs.compare_to = args.compare;
-            delete transformedArgs.compare;
-        }
-        // Data operations: persona(id, data={method:"...", ...})
-        // Supports both explicit method format and legacy flag format
-        else if (args.data && typeof args.data === "object") {
-            const data = args.data;
-            const personaId = args.id;
-            const fs = await import("fs/promises");
-            // EXPLICIT METHOD FORMAT (preferred): data={method:"list/stats/upload/copy/replicate/delete/search/refresh/regenerate/replace"}
-            if (typeof data.method === "string") {
-                // Import the new data handler - pass data object as part of args
-                const { handleData: handleDataNew } = await import("./handlers/data/index.js");
-                return handleDataNew({ persona_id: personaId, env: args.env, data }, client);
-            }
-            // LEGACY FLAG FORMAT (backwards compatibility) - use extracted handler
-            const { handleData: handleDataExtracted } = await import("./handlers/data/index.js");
-            const readFileFn = (path) => fs.readFile(path);
-            if (data.list === true) {
-                return handleDataExtracted({ method: "list", persona_id: personaId, env: args.env }, client, readFileFn);
-            }
-            if (typeof data.upload === "string") {
-                return handleDataExtracted({ method: "upload", persona_id: personaId, data: { path: data.upload }, env: args.env }, client, readFileFn);
-            }
-            if (typeof data.delete === "string") {
-                return handleDataExtracted({ method: "delete", persona_id: personaId, data: { file_id: data.delete }, env: args.env }, client, readFileFn);
-            }
-            if (typeof data.generate === "string" || data.template) {
-                return handleDataExtracted({
-                    method: "generate",
-                    persona_id: personaId,
-                    data: {
-                        input: data.generate,
-                        from: data.template,
-                        count: data.count,
-                    },
-                    env: args.env
-                }, client, readFileFn);
-            }
-            if (typeof data.embed === "boolean") {
-                return handleDataExtracted({ method: "embedding", persona_id: personaId, data: { enabled: data.embed }, env: args.env }, client, readFileFn);
-            }
-            if (typeof data.search === "string") {
-                return handleKnowledge({ mode: "search", persona_id: personaId, query: data.search, env: args.env }, client, (path) => fs.readFile(path));
-            }
-            return {
-                error: "Unknown data operation",
-                hint: "Use data={method:'list'} format (explicit method)",
-                available_methods: ["list", "stats", "upload", "copy", "replicate", "delete", "search", "refresh", "regenerate", "replace"],
-                legacy_flags: ["list", "upload", "delete", "generate", "embed", "search"],
-            };
-        }
-        // Get: persona(id) with no mutation flags
-        else if (args.id && !transformedArgs.mode) {
-            transformedArgs.mode = "get";
-        }
-        // List: persona() or persona(type, status, query) with no id
-        else if (!args.id && !transformedArgs.mode) {
-            transformedArgs.mode = "list";
-        }
-        // Templates are tenant-specific - don't use hardcoded IDs
-        // The handler will use dynamic template lookup from API
-        const result = await handlePersona(transformedArgs, client, () => undefined, // Dynamic lookup in handler
-        (env) => createClient(env), versionContext);
-        // ─────────────────────────────────────────────────────────────────────────
-        // Action Composition Post-Processing
-        // Execute actions array after main operation completes
-        // ─────────────────────────────────────────────────────────────────────────
-        const actions = transformedArgs._actions;
-        if (actions && actions.length > 0) {
-            // Get the target persona ID from result
-            const resultObj = result;
-            const targetId = resultObj.id ??
-                resultObj.persona_id;
-            const sourceId = args.from;
-            if (!targetId) {
-                return {
-                    ...(typeof result === "object" && result !== null ? result : {}),
-                    _actions_error: "No persona ID available for action execution",
-                };
-            }
-            // Import and execute actions
-            const actionExecutor = await import("./handlers/action-executor.js");
-            const context = {
-                source: sourceId,
-                target: targetId,
-                env: targetEnv,
-                originalArgs: args,
-            };
-            const actionsResult = await actionExecutor.executeActions(actions, context, client);
-            return {
-                ...(typeof result === "object" && result !== null ? result : {}),
-                _actions: actionsResult,
-            };
-        }
-        return result;
-    },
-    // Consolidated workflow handler (replaces legacy inline handler)
-    workflow: async (args) => {
-        const client = createClient(args.env);
-        // Templates are tenant-specific - dynamic lookup in handler
-        return handleWorkflow(args, client, () => undefined);
+        return handlePersonaAdapter(args, createClient, getDefaultEnvName);
     },
     action: async (args) => {
         const client = createClient(args.env);
@@ -314,12 +93,6 @@ const toolHandlers = {
     template: async (args) => {
         return handleTemplate(args);
     },
-    knowledge: async (args) => {
-        const client = createClient(args.env);
-        const fs = await import("fs/promises");
-        return handleKnowledge(args, client, (path) => fs.readFile(path));
-    },
-    // v2: data is an alias for knowledge with simplified interface
     data: async (args) => {
         const client = createClient(args.env);
         const fs = await import("fs/promises");
@@ -352,572 +125,19 @@ const toolHandlers = {
     toolkit_feedback: async (args) => {
         return handleFeedback(args);
     },
-};
-// ─────────────────────────────────────────────────────────────────────────────
-// Standalone sync implementation functions
-// (Used by the V2 sync adapter below)
-// ─────────────────────────────────────────────────────────────────────────────
-async function syncRunImpl(args) {
-    const targetEnv = String(args.target_env);
-    const sourceEnv = args.source_env ? String(args.source_env) : getDefaultEnvName();
-    const dryRun = args.dry_run === true;
-    const includeStatus = args.include_status === true;
-    const scope = args.scope === "all" ? "all" : "one";
-    const identifier = args.identifier ? String(args.identifier) : undefined;
-    // Sync all tagged personas
-    if (scope === "all" || !identifier) {
-        const sdk = getSyncSDK();
-        if (sdk) {
-            try {
-                const result = await sdk.runSync();
-                return { success: true, mode: "config", ...result };
-            }
-            finally {
-                sdk.close();
-            }
-        }
-        // Config-less mode
-        try {
-            const result = await directSyncAll({ targetEnv, dryRun });
-            return { success: true, mode: "tags", ...result };
-        }
-        catch (e) {
-            return { success: false, error: e instanceof Error ? e.message : String(e) };
-        }
-    }
-    // Sync single persona
-    const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(identifier);
-    const behavior = resolveSyncBehavior({
-        personaName: isUUID ? undefined : identifier,
-        targetEnv,
-        overrides: {
-            dry_run: dryRun ? true : undefined,
-            sync_status: includeStatus ? true : undefined,
-        },
-    });
-    try {
-        const result = isUUID
-            ? await directSyncPersonaById({
-                personaId: identifier,
-                sourceEnv,
-                targetEnv,
-                dryRun: behavior.dry_run,
-                syncStatus: behavior.sync_status,
-            })
-            : await directSyncPersona({
-                name: identifier,
-                sourceEnv,
-                targetEnv,
-                dryRun: behavior.dry_run,
-                syncStatus: behavior.sync_status,
-            });
-        return { ...result, resolved_behavior: behavior };
-    }
-    catch (e) {
-        return { success: false, error: e instanceof Error ? e.message : String(e) };
-    }
-}
-async function syncInfoImpl(args) {
-    const client = args.env ? createClient(args.env) : undefined;
-    // Check if persona is synced
-    if (args.persona_id) {
-        if (!client)
-            throw new Error("env required when checking persona sync status");
-        const personaId = String(args.persona_id);
-        const personas = await client.getPersonasForTenant();
-        const persona = personas.find((p) => p.id === personaId);
-        if (!persona)
-            throw new Error(`AI Employee not found: ${personaId}`);
-        const meta = client.getSyncMetadata(persona);
-        return {
-            environment: client["env"].name,
-            persona_id: personaId,
-            persona_name: persona.name,
-            is_synced: !!meta,
-            sync_metadata: meta,
-        };
-    }
-    // Check by persona name
-    if (args.persona_name) {
-        const sdk = getSyncSDK();
-        if (!sdk)
-            return { error: "No sync config found. Set EMA_AGENT_SYNC_CONFIG." };
-        try {
-            const persona = await sdk.getMasterPersonaByName(String(args.persona_name));
-            if (!persona)
-                return { error: `Persona not found: ${args.persona_name}` };
-            return await sdk.getPersonaSyncStatus(persona.id);
-        }
-        finally {
-            sdk.close();
-        }
-    }
-    // List all synced personas
-    if (args.list_synced === true) {
-        if (!client)
-            throw new Error("env required when listing synced personas");
-        const personas = await client.getPersonasForTenant();
-        const masterEnvFilter = args.master_env ? String(args.master_env).toLowerCase() : undefined;
-        const synced = [];
-        for (const p of personas) {
-            const meta = client.getSyncMetadata(p);
-            if (meta) {
-                if (masterEnvFilter && meta.master_env.toLowerCase() !== masterEnvFilter)
-                    continue;
-                synced.push({ persona_id: p.id, persona_name: p.name, sync_metadata: meta });
-            }
-        }
-        return { environment: client["env"].name, count: synced.length, synced_personas: synced };
-    }
-    // Default: return overall sync config/status
-    const sdk = getSyncSDK();
-    const options = args.include_options === true ? loadSyncOptions() : undefined;
-    if (!sdk) {
-        return {
-            configured: false,
-            error: "No sync config found. Set EMA_AGENT_SYNC_CONFIG.",
-            options,
-        };
-    }
-    try {
-        const master = sdk.getMasterEnvironment();
-        const envs = sdk.getEnvironments();
-        const personas = await sdk.listMasterPersonas();
-        return {
-            configured: true,
-            master_environment: { name: master.name, url: master.baseUrl },
-            target_environments: envs.filter((e) => !e.isMaster).map((e) => ({ name: e.name, url: e.baseUrl })),
-            total_personas: personas.length,
-            options,
-        };
-    }
-    finally {
-        sdk.close();
-    }
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// V2 Tool Adapters (contract ↔ implementation)
-// ─────────────────────────────────────────────────────────────────────────────
-//
-// The tool schemas in tools.ts are the public MCP contract.
-// These adapters ensure the V2 tool surface behaves as documented,
-// while routing to the extracted handler implementations.
-// Workflow tool: MCP provides data (get) and executes (deploy). LLM does all thinking.
-toolHandlers.workflow = async (args) => {
-    const normalizedArgs = { ...(args ?? {}) };
-    const personaId = normalizedArgs.persona_id ? String(normalizedArgs.persona_id) : undefined;
-    let workflowDef = normalizedArgs.workflow_def;
-    const workflowDefPath = normalizedArgs.workflow_def_path;
-    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : undefined;
-    const baseFingerprint = normalizedArgs.base_fingerprint;
-    const force = normalizedArgs.force;
-    // For deploy: resolve workflow_def from file when workflow_def_path is provided (large payloads)
-    // Also handle the common agent mistake: passing {"workflow_def_path": "/path"} as workflow_def
-    // (happens when the agent's tool schema doesn't expose workflow_def_path as a separate param)
-    let effectivePath = workflowDefPath;
-    if (mode === "deploy" && workflowDef && !effectivePath) {
-        const keys = Object.keys(workflowDef);
-        if (keys.length === 1 && keys[0] === "workflow_def_path" && typeof workflowDef.workflow_def_path === "string") {
-            effectivePath = workflowDef.workflow_def_path;
-            workflowDef = undefined;
-        }
-    }
-    if (mode === "deploy" && !workflowDef && effectivePath) {
-        try {
-            // Guardrails: reduce risk of accidental secret exfiltration
-            const path = await import("path");
-            if (!path.isAbsolute(effectivePath)) {
-                return { error: "workflow_def_path must be an absolute path on the MCP server host", path: effectivePath };
-            }
-            if (!effectivePath.toLowerCase().endsWith(".json")) {
-                return { error: "workflow_def_path must point to a .json file", path: effectivePath };
-            }
-            const fs = await import("fs/promises");
-            const stat = await fs.stat(effectivePath);
-            const MAX_WORKFLOW_DEF_BYTES = 1024 * 1024; // 1MB
-            if (stat.size > MAX_WORKFLOW_DEF_BYTES) {
-                return { error: `workflow_def_path file too large (${stat.size} bytes)`, max_bytes: MAX_WORKFLOW_DEF_BYTES, path: effectivePath };
-            }
-            const raw = await fs.readFile(effectivePath, "utf-8");
-            const parsed = JSON.parse(raw);
-            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-                workflowDef = parsed;
-            }
-            else {
-                return { error: "workflow_def_path must point to a JSON object", path: effectivePath };
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return { error: `Failed to read workflow_def from path: ${msg}`, path: effectivePath };
-        }
-    }
-    // Route to handleWorkflow for get/deploy (the only public modes)
-    const client = createClient(normalizedArgs.env);
-    switch (mode) {
-        case "get": {
-            // Return workflow data for LLM to analyze/modify
-            return handleWorkflow({
-                mode: "get",
-                persona_id: personaId,
-                env: normalizedArgs.env,
-            }, client, () => undefined);
-        }
-        case "validate": {
-            // Static validation with path enumeration
-            return handleWorkflow({
-                mode: "validate",
-                persona_id: personaId,
-                workflow_def: normalizedArgs.workflow_def,
-                workflow_spec: normalizedArgs.workflow_spec,
-                validation_type: normalizedArgs.validation_type,
-                max_paths: normalizedArgs.max_paths,
-                timeout_ms: normalizedArgs.timeout_ms,
-                env: normalizedArgs.env,
-            }, client, () => undefined);
-        }
-        case "deploy": {
-            if (!personaId) {
-                return { error: 'persona_id is required for workflow(mode="deploy")' };
-            }
-            // Pre-deploy snapshot + stale-state protection (out-of-band changes)
-            const targetEnv = normalizedArgs.env ?? getDefaultEnvName();
-            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, {
-                    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 {
-                    versionCreated = { id: snap.version.id, version_name: snap.version.version_name };
-                }
-            }
-            catch {
-                // Snapshotting is required unless force=true
-                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.",
-                    };
-                }
-            }
-            // Route to handleWorkflow deploy
-            const deployResult = await handleWorkflow({
-                mode: "deploy",
-                persona_id: personaId,
-                workflow_def: workflowDef,
-                proto_config: normalizedArgs.proto_config,
-                env: normalizedArgs.env,
-                force: force,
-                strict_validation: normalizedArgs.strict_validation,
-            }, client, () => undefined);
-            // Add version info to result if created
-            if (versionCreated && deployResult && typeof deployResult === "object") {
-                deployResult.version_snapshot = versionCreated;
-            }
-            return deployResult;
-        }
-        // REMOVED modes - LLM does these
-        case "analyze":
-        case "compare":
-        case "compile":
-        case "optimize":
-        case "generate": {
-            return {
-                error: `Mode "${mode}" removed - LLM does this thinking`,
-                hint: "Use workflow(mode='get') to fetch data, then analyze/generate in your reasoning. Deploy with workflow(mode='deploy').",
-                valid_modes: ["get", "validate", "deploy"],
-            };
-        }
-        default: {
-            // No mode or unknown mode - require explicit mode
-            return {
-                error: `Mode required. Valid modes: get, validate, deploy`,
-                hint: "workflow(mode='get') returns data for LLM. workflow(mode='validate') validates specs. workflow(mode='deploy') executes LLM's workflow_def.",
-                example: `workflow(mode="get", persona_id="...")`,
-            };
-        }
-    }
-};
-// Unify sync modes: run | status | config
-toolHandlers.sync = async (args) => {
-    const normalizedArgs = { ...(args ?? {}) };
-    // Tool definition uses "method" (preview/execute/status), but legacy callers use "mode" (run/status/config)
-    const rawMethod = normalizedArgs.method ? String(normalizedArgs.method) : normalizedArgs.mode ? String(normalizedArgs.mode) : "run";
-    // Map tool method values to internal mode values
-    const mode = rawMethod === "preview" ? "run" : rawMethod === "execute" ? "run" : rawMethod;
-    // "preview" implies dry_run
-    if (rawMethod === "preview") {
-        normalizedArgs.dry_run = true;
-    }
-    // Support both old and new arg names
-    const target = (normalizedArgs.target ?? normalizedArgs.target_env);
-    const source = (normalizedArgs.source ?? normalizedArgs.source_env);
-    const id = normalizedArgs.id;
-    const identifier = normalizedArgs.identifier; // deprecated alias
-    const idOrIdentifier = id ?? identifier;
-    if (mode === "config") {
-        return syncInfoImpl({ include_options: true });
-    }
-    if (mode === "status") {
-        const env = normalizedArgs.env;
-        if (normalizedArgs.list_synced === true) {
-            if (!env)
-                throw new Error('env is required for sync(mode="status", list_synced=true)');
-            return syncInfoImpl({ list_synced: true, master_env: normalizedArgs.master_env, env });
-        }
-        if (idOrIdentifier) {
-            if (!env)
-                throw new Error('env is required for sync(mode="status", id="...")');
-            const identifierToResolve = String(idOrIdentifier);
-            const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(identifierToResolve);
-            if (isUUID) {
-                return syncInfoImpl({ persona_id: identifierToResolve, env });
-            }
-            // Name lookup: resolve to ID in env, then reuse persona_id path
-            const client = createClient(env);
-            const personas = await client.getPersonasForTenant();
-            const match = personas.find((p) => p.name === identifierToResolve);
-            if (!match)
-                throw new Error(`AI Employee not found by name in ${env}: ${identifierToResolve}`);
-            return syncInfoImpl({ persona_id: match.id, env });
-        }
-        // Default: overall sync status/config summary
-        return syncInfoImpl({ include_options: normalizedArgs.include_options === true });
-    }
-    // mode === "run" (default)
-    if (!target) {
-        throw new Error('target (or target_env) is required for sync(mode="run")');
-    }
-    return syncRunImpl({
-        identifier: idOrIdentifier,
-        target_env: target,
-        source_env: source,
-        scope: normalizedArgs.scope,
-        dry_run: normalizedArgs.dry_run,
-        include_status: normalizedArgs.include_status,
-    });
-};
-// Consolidated demo tool: kit | validate_kit | scenarios | consolidate | generate | validate | template
-toolHandlers.demo = async (args) => {
-    const normalizedArgs = { ...(args ?? {}) };
-    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : "template";
-    // Deprecation warning - added to all responses
-    const deprecationWarning = {
-        _deprecation: {
-            message: "The 'demo' tool is deprecated. Please use 'data' and 'persona' tools instead.",
-            migration: {
-                "demo(mode='kit')": "persona(from='demo-sales-sdr', include_data=true)",
-                "demo(mode='generate')": "data(mode='generate', from='customer', count=5)",
-                "demo(mode='scenarios')": "data(mode='templates')",
-                "demo(mode='template')": "data(mode='templates', template='customer')",
-            },
-        },
-    };
-    switch (mode) {
-        case "kit": {
-            // Generate complete demo kit for a persona
-            const personaId = String(normalizedArgs.persona_id ?? "");
-            const scenarioId = String(normalizedArgs.scenario ?? "sales-sdr");
-            if (!personaId) {
-                throw new Error('demo(mode="kit") requires: persona_id');
-            }
-            // Import demo generator
-            const { generateDemoKit, DEMO_SCENARIOS, generateDemoScriptMarkdown, validateDemoKit } = await import("./demo-generator.js");
-            // Get scenario
-            const scenario = DEMO_SCENARIOS[scenarioId];
-            if (!scenario) {
-                throw new Error(`Unknown scenario: ${scenarioId}. Available: ${Object.keys(DEMO_SCENARIOS).join(", ")}`);
-            }
-            // Get persona and workflow
-            const client = await createClient(normalizedArgs.env);
-            const persona = await client.getPersonaById(personaId);
-            if (!persona) {
-                throw new Error(`Persona not found: ${personaId}`);
-            }
-            const workflowDef = persona.workflow_def || {};
-            const customQA = normalizedArgs.custom_qa;
-            // Generate kit
-            const kit = generateDemoKit(personaId, persona.name || personaId, workflowDef, scenario, customQA);
-            // Generate markdown script
-            const demoScript = generateDemoScriptMarkdown(kit);
-            // Validate
-            const validation = validateDemoKit(kit);
-            return {
-                success: true,
-                persona_id: personaId,
-                persona_name: persona.name,
-                scenario: scenarioId,
-                kit_summary: {
-                    kb_documents: kit.kb_documents.length,
-                    demo_questions: kit.demo_script.length,
-                    fixed_responses: kit.fixed_responses.length,
-                    validation_queries: kit.validation_queries.length,
-                },
-                validation,
-                demo_script_preview: demoScript.slice(0, 2000) + (demoScript.length > 2000 ? "\n\n... (truncated)" : ""),
-                kit,
-                instructions: [
-                    "1. Upload KB documents to the persona's knowledge base",
-                    "2. Review the demo script and practice the questions",
-                    "3. Optionally apply fixed_responses for guaranteed fallbacks",
-                    "4. Run validation queries to verify demo readiness",
-                    "5. Conduct the demo with confidence!",
-                ],
-            };
-        }
-        case "validate_kit": {
-            // Validate a persona's demo readiness
-            const personaId = String(normalizedArgs.persona_id ?? "");
-            if (!personaId) {
-                throw new Error('demo(mode="validate_kit") requires: persona_id');
-            }
-            const { analyzeWorkflowForDemo, DEMO_SCENARIOS } = await import("./demo-generator.js");
-            const client = await createClient(normalizedArgs.env);
-            const persona = await client.getPersonaById(personaId);
-            if (!persona) {
-                throw new Error(`Persona not found: ${personaId}`);
-            }
-            const analysis = analyzeWorkflowForDemo(persona.workflow_def || {});
-            // Check data sources
-            const dataSourcesResult = await client.listDataSourceFiles(personaId);
-            const dataSources = dataSourcesResult.files || [];
-            const hasKnowledgeBase = dataSources.length > 0;
-            const issues = [];
-            if (!hasKnowledgeBase) {
-                issues.push("No knowledge base documents uploaded - RAG search will fail");
-            }
-            if (analysis.intents.length === 0) {
-                issues.push("No categorizer intents detected - workflow may not route correctly");
-            }
-            if (!analysis.has_search) {
-                issues.push("No search nodes detected - cannot retrieve KB data");
-            }
-            // Suggest best scenario
-            let suggestedScenario = "sales-sdr";
-            for (const [id, scenario] of Object.entries(DEMO_SCENARIOS)) {
-                const intentOverlap = scenario.intents.filter(i => analysis.intents.some(ai => ai.toLowerCase().includes(i.name.toLowerCase()))).length;
-                if (intentOverlap > 0) {
-                    suggestedScenario = id;
-                    break;
-                }
-            }
-            return {
-                persona_id: personaId,
-                persona_name: persona.name,
-                ready: issues.length === 0,
-                issues,
-                workflow_analysis: analysis,
-                knowledge_base: {
-                    has_documents: hasKnowledgeBase,
-                    document_count: dataSources.length,
-                },
-                suggested_scenario: suggestedScenario,
-                next_steps: issues.length > 0
-                    ? issues.map((issue, i) => `${i + 1}. Fix: ${issue}`)
-                    : [`Generate demo kit: demo(mode="kit", persona_id="${personaId}", scenario="${suggestedScenario}")`],
-            };
-        }
-        case "scenarios": {
-            // List available demo scenarios
-            const { DEMO_SCENARIOS } = await import("./demo-generator.js");
-            return {
-                scenarios: Object.entries(DEMO_SCENARIOS).map(([id, scenario]) => ({
-                    id,
-                    name: scenario.name,
-                    description: scenario.description,
-                    persona_types: scenario.persona_types,
-                    tags: scenario.tags,
-                    intent_count: scenario.intents.length,
-                    qa_count: scenario.qa_pairs.length,
-                    entity_types: scenario.entities.map(e => e.type),
-                })),
-                usage: 'demo(mode="kit", persona_id="...", scenario="<scenario_id>")',
-            };
-        }
-        case "consolidate": {
-            const source = String(normalizedArgs.source ?? "");
-            const output = String(normalizedArgs.output ?? "");
-            const entity = String(normalizedArgs.entity ?? "");
-            if (!source || !output || !entity) {
-                throw new Error('demo(mode="consolidate") requires: source, output, entity');
-            }
-            return handleConsolidateDemoData({
-                source_dir: source,
-                output_dir: output,
-                entity_type: entity,
-                primary_file: normalizedArgs.primary ?? `${entity}s.json`,
-                joins: normalizedArgs.joins ?? [],
-                tags: normalizedArgs.tags,
-            });
-        }
-        case "generate": {
-            const entity = String(normalizedArgs.entity ?? "");
-            if (!entity)
-                throw new Error('demo(mode="generate") requires: entity');
-            return handleGenerateDemoDocument({
-                entity_type: entity,
-                data: normalizedArgs.data ?? {},
-                related_data: normalizedArgs.related ?? {},
-                output_path: normalizedArgs.output,
-                tags: normalizedArgs.tags,
-            });
-        }
-        case "validate": {
-            return handleValidateDemoDocument({
-                file_path: normalizedArgs.file,
-                content: normalizedArgs.content,
-            });
-        }
-        case "template": {
-            const entity = String(normalizedArgs.entity ?? "");
-            if (!entity)
-                throw new Error('demo(mode="template") requires: entity');
-            return handleGetDemoDataTemplate({
-                entity_type: entity,
-                include_example: normalizedArgs.include_example,
-            });
-        }
-        default:
-            throw new Error(`Unknown demo mode: ${mode}`);
-    }
+    // V2 adapters — routing + transformation extracted to handler files
+    workflow: async (args) => {
+        return handleWorkflowAdapter(args, createClient, getDefaultEnvName);
+    },
+    sync: async (args) => {
+        return handleSyncAdapter(args, createClient, getDefaultEnvName, getSyncSDK);
+    },
+    demo: async (args) => {
+        return handleDemoAdapter(args, createClient);
+    },
+    debug: async (args) => {
+        return handleDebugAdapter(args, createClient, getDefaultEnvName);
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
@@ -928,24 +148,8 @@ toolHandlers.demo = async (args) => {
  */
 function determineOperation(toolName, args) {
     if (toolName === "persona") {
-        if (args.analyze)
-            return "analyze";
-        if (args.update)
-            return "update";
-        if (args.create)
-            return "create";
-        if (args.delete)
-            return "delete";
-        if (args.snapshot)
-            return "snapshot";
-        if (args.history)
-            return "history";
-        if (args.restore)
-            return "restore";
-        if (args.compare)
-            return "compare";
-        if (args.sanitize)
-            return "sanitize";
+        if (args.method)
+            return String(args.method);
         if (args.data)
             return "data";
         if (args.id)
@@ -953,24 +157,21 @@ function determineOperation(toolName, args) {
         return "list";
     }
     if (toolName === "catalog") {
-        if (args.id)
-            return "get";
-        if (args.for)
-            return "recommend"; // V2 schema uses 'for' parameter
-        if (args.query)
-            return "search";
+        if (args.method)
+            return String(args.method);
         return "list";
     }
     if (toolName === "sync") {
-        if (args.execute)
-            return "execute";
-        if (args.status)
-            return "status";
+        if (args.method)
+            return String(args.method);
         return "preview";
     }
     if (toolName === "toolkit_feedback") {
         return args.method ? String(args.method) : "submit";
     }
+    if (toolName === "debug") {
+        return args.method ? String(args.method) : "conversations";
+    }
     return toolName;
 }
 // ─────────────────────────────────────────────────────────────────────────────