@ema.co/mcp-toolkit 0.2.0

package/dist/mcp/handlers-consolidated.js

@@ -0,0 +1,851 @@
+/**
+ * Consolidated Tool Handlers
+ *
+ * Each handler dispatches based on mode/flags following Unix CLI patterns.
+ */
+import { fingerprintPersona } from "../sync.js";
+import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, detectWorkflowIssues, validateWorkflowConnections, suggestWorkflowFixes, } from "../sdk/knowledge.js";
+import { compileWorkflow } from "../sdk/workflow-generator.js";
+import { parseInput, intentToSpec } from "../sdk/workflow-intent.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// ENV Handler
+// ═══════════════════════════════════════════════════════════════════════════
+export async function handleEnv(_args, getEnvironments) {
+    const envs = getEnvironments();
+    return {
+        environments: envs.map(e => ({
+            name: e.name,
+            default: e.isDefault,
+        })),
+        count: envs.length,
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// PERSONA Handler
+// ═══════════════════════════════════════════════════════════════════════════
+export async function handlePersona(args, client, getTemplateId, createClientForEnv) {
+    const id = args.id;
+    const identifier = args.identifier; // deprecated alias
+    const idOrName = id ?? identifier;
+    const mode = args.mode;
+    // Determine effective mode
+    let effectiveMode = mode;
+    if (!effectiveMode) {
+        if (args.templates)
+            effectiveMode = "templates";
+        else if (args.all || args.query || args.status || args.trigger_type)
+            effectiveMode = "list";
+        else if (idOrName)
+            effectiveMode = "get";
+        else
+            effectiveMode = "list"; // Default to list all
+    }
+    switch (effectiveMode) {
+        case "get": {
+            if (!idOrName) {
+                return { error: "id required for get mode" };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            const result = {
+                id: persona.id,
+                name: persona.name,
+                description: persona.description,
+                status: persona.status,
+                template_id: persona.template_id,
+                trigger_type: persona.trigger_type,
+            };
+            if (args.include_workflow && persona.workflow_def) {
+                result.workflow_def = persona.workflow_def;
+            }
+            if (args.include_fingerprint) {
+                result.fingerprint = fingerprintPersona(persona);
+            }
+            return result;
+        }
+        case "list": {
+            let personas = await client.getPersonasForTenant();
+            // Apply filters
+            if (args.query) {
+                const q = args.query.toLowerCase();
+                personas = personas.filter(p => p.name?.toLowerCase().includes(q));
+            }
+            if (args.status) {
+                personas = personas.filter(p => p.status === args.status);
+            }
+            if (args.trigger_type) {
+                personas = personas.filter(p => p.trigger_type === args.trigger_type);
+            }
+            // Apply limit
+            const limit = args.limit || 50;
+            personas = personas.slice(0, limit);
+            return {
+                count: personas.length,
+                personas: personas.map(p => ({
+                    id: p.id,
+                    name: p.name,
+                    status: p.status,
+                    trigger_type: p.trigger_type,
+                })),
+            };
+        }
+        case "create": {
+            const name = args.name;
+            if (!name) {
+                return { error: "name required for create mode" };
+            }
+            let templateId = args.template_id;
+            if (!templateId && args.type) {
+                templateId = getTemplateId(args.type);
+            }
+            const result = await client.createAiEmployee({
+                name,
+                description: args.description,
+                template_id: templateId,
+                source_persona_id: args.clone_from,
+            });
+            return {
+                success: true,
+                persona_id: result.persona_id,
+                name,
+            };
+        }
+        case "update": {
+            if (!idOrName) {
+                return { error: "id required for update mode" };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            await client.updateAiEmployee({
+                persona_id: persona.id,
+                name: args.name,
+                description: args.description,
+                proto_config: persona.proto_config ?? {},
+                enabled_by_user: typeof args.enabled === "boolean" ? args.enabled : undefined,
+            });
+            return {
+                success: true,
+                persona_id: persona.id,
+                updated_fields: Object.keys(args).filter(k => !["id", "identifier", "mode", "env"].includes(k)),
+            };
+        }
+        case "compare": {
+            if (!idOrName || !args.compare_to) {
+                return { error: "id and compare_to required for compare mode" };
+            }
+            const persona1 = await resolvePersona(client, idOrName);
+            const compareEnv = args.compare_env;
+            const client2 = compareEnv && createClientForEnv ? createClientForEnv(compareEnv) : client;
+            const persona2 = await resolvePersona(client2, args.compare_to);
+            if (!persona1 || !persona2) {
+                return { error: "One or both personas not found" };
+            }
+            return {
+                persona_1: { id: persona1.id, name: persona1.name },
+                persona_2: { id: persona2.id, name: persona2.name, env: compareEnv },
+                differences: comparePersonas(persona1, persona2),
+            };
+        }
+        case "templates": {
+            const personas = await client.getPersonasForTenant();
+            const templates = new Map();
+            for (const p of personas) {
+                const tid = p.template_id ?? p.templateId;
+                if (tid) {
+                    if (!templates.has(tid)) {
+                        templates.set(tid, {
+                            id: tid,
+                            name: p.template_name || tid,
+                            count: 0,
+                        });
+                    }
+                    templates.get(tid).count++;
+                }
+            }
+            return {
+                templates: Array.from(templates.values()),
+                count: templates.size,
+            };
+        }
+        default:
+            return { error: `Unknown mode: ${effectiveMode}` };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// WORKFLOW Handler
+// ═══════════════════════════════════════════════════════════════════════════
+export async function handleWorkflow(args, client) {
+    const mode = args.mode;
+    const personaId = args.persona_id;
+    const workflowDef = args.workflow_def;
+    const input = args.input;
+    // Determine effective mode
+    // Key routing logic:
+    // - persona_id only → analyze (inspect existing)
+    // - input only → generate (greenfield)
+    // - persona_id + input → optimize (brownfield update)
+    // - workflow_def only → analyze
+    let effectiveMode = mode;
+    if (!effectiveMode) {
+        if (args.include)
+            effectiveMode = "analyze";
+        else if (workflowDef && !personaId)
+            effectiveMode = "analyze";
+        else if (personaId && input)
+            effectiveMode = "optimize"; // BROWNFIELD: existing persona + new requirements
+        else if (personaId && !input)
+            effectiveMode = "analyze";
+        else if (input)
+            effectiveMode = "generate"; // GREENFIELD: new requirements only
+        else
+            effectiveMode = "analyze";
+    }
+    switch (effectiveMode) {
+        case "generate": {
+            if (!input) {
+                return { error: "input required for generate mode" };
+            }
+            // BROWNFIELD CHECK: If persona_id is provided, check for existing workflow
+            let existingWorkflow;
+            let personaName;
+            if (personaId) {
+                const persona = await client.getPersonaById(personaId);
+                if (persona) {
+                    existingWorkflow = persona.workflow_def;
+                    personaName = persona.name;
+                }
+            }
+            const parseResult = parseInput(input);
+            if (!parseResult.validation.complete) {
+                return {
+                    status: "incomplete",
+                    input_type: parseResult.input_type,
+                    missing: parseResult.validation.missing,
+                    questions: parseResult.validation.questions,
+                };
+            }
+            // Convert to spec and compile
+            const spec = intentToSpec(parseResult.intent);
+            const compiled = compileWorkflow(spec);
+            // If brownfield, analyze both existing and generated for comparison
+            const result = {
+                status: "generated",
+                input_type: parseResult.input_type,
+                workflow_def: compiled.workflow_def,
+                proto_config: compiled.proto_config,
+                validation: parseResult.validation,
+            };
+            if (existingWorkflow) {
+                result.brownfield_warning = "⚠️ This persona already has a workflow. The generated workflow will REPLACE it, not merge with it.";
+                result.existing_workflow_summary = {
+                    node_count: existingWorkflow.actions ? existingWorkflow.actions.length : 0,
+                };
+                // Run analysis on generated workflow to show issues
+                const generatedIssues = detectWorkflowIssues(compiled.workflow_def);
+                if (generatedIssues.length > 0) {
+                    result.generated_workflow_issues = generatedIssues;
+                }
+            }
+            return result;
+        }
+        case "analyze": {
+            let workflow = workflowDef;
+            let persona = null;
+            if (personaId && !workflow) {
+                persona = await client.getPersonaById(personaId);
+                if (!persona) {
+                    return { error: `Persona not found: ${personaId}` };
+                }
+                workflow = persona.workflow_def;
+            }
+            if (!workflow) {
+                return { error: "No workflow to analyze. Provide workflow_def or persona_id." };
+            }
+            // Determine what to include
+            const include = args.include || ["issues", "connections", "fixes", "metrics"];
+            const result = {};
+            if (include.includes("issues") || include.includes("fixes")) {
+                const issues = detectWorkflowIssues(workflow);
+                if (include.includes("issues")) {
+                    result.issues = issues;
+                }
+                if (include.includes("fixes")) {
+                    result.fixes = suggestWorkflowFixes(issues);
+                }
+                // Always include summary even if only fixes requested
+                result.issue_summary = {
+                    total: issues.length,
+                    critical: issues.filter((i) => i.severity === "critical").length,
+                    warnings: issues.filter((i) => i.severity === "warning").length,
+                    info: issues.filter((i) => i.severity === "info").length,
+                };
+            }
+            if (include.includes("connections")) {
+                result.connections = validateWorkflowConnections(workflow);
+            }
+            if (include.includes("metrics")) {
+                result.metrics = calculateMetrics(workflow);
+            }
+            if (persona) {
+                result.persona = { id: persona.id, name: persona.name };
+            }
+            // Always provide optimization guidance
+            const issues = result.issues;
+            const criticalCount = issues?.filter(i => i.severity === "critical").length ?? 0;
+            const warningCount = issues?.filter(i => i.severity === "warning").length ?? 0;
+            if (criticalCount > 0 || warningCount > 0) {
+                result.optimization_suggestion = `This workflow has ${criticalCount} critical and ${warningCount} warning issues. ` +
+                    `Use workflow(mode="optimize", persona_id="${personaId ?? 'ID'}") to auto-fix, ` +
+                    `or workflow(mode="deploy", persona_id="${personaId ?? 'ID'}", auto_fix=true) to fix and deploy.`;
+            }
+            else {
+                result.status = "✅ Workflow is healthy - no issues detected";
+            }
+            return result;
+        }
+        case "deploy": {
+            if (!personaId) {
+                return { error: "persona_id required for deploy mode" };
+            }
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                return { error: `Persona not found: ${personaId}` };
+            }
+            let deployWorkflow = workflowDef || persona.workflow_def;
+            // Validate if requested (default: true)
+            if (args.validate !== false) {
+                const issues = detectWorkflowIssues(deployWorkflow);
+                const errors = issues.filter((i) => i.severity === "error");
+                if (errors.length > 0 && !args.auto_fix) {
+                    return {
+                        error: "Workflow has errors",
+                        issues: errors,
+                        hint: "Set auto_fix=true to attempt automatic fixes",
+                    };
+                }
+                // Auto-fix if enabled
+                if (args.auto_fix && errors.length > 0) {
+                    // Apply fixes (simplified - actual implementation would be more complex)
+                    deployWorkflow = applySimpleFixes(deployWorkflow, errors);
+                }
+            }
+            await client.updateAiEmployee({
+                persona_id: personaId,
+                workflow: deployWorkflow,
+                proto_config: args.proto_config || persona.proto_config,
+            });
+            return {
+                success: true,
+                persona_id: personaId,
+                deployed: true,
+            };
+        }
+        case "compare": {
+            if (!personaId || !args.compare_to) {
+                return { error: "persona_id and compare_to required for compare mode" };
+            }
+            const persona1 = await client.getPersonaById(personaId);
+            const persona2 = await client.getPersonaById(args.compare_to);
+            if (!persona1 || !persona2) {
+                return { error: "One or both personas not found" };
+            }
+            const workflow1 = persona1.workflow_def;
+            const workflow2 = persona2.workflow_def;
+            return {
+                persona_1: { id: persona1.id, name: persona1.name },
+                persona_2: { id: persona2.id, name: persona2.name },
+                differences: compareWorkflows(workflow1, workflow2),
+            };
+        }
+        case "compile": {
+            const nodes = args.nodes;
+            const resultMappings = args.result_mappings;
+            if (!nodes) {
+                return { error: "nodes required for compile mode" };
+            }
+            const spec = {
+                name: args.name || "Compiled Workflow",
+                description: args.description || "Generated workflow",
+                persona_type: args.type || "chat",
+                nodes: nodes,
+                result_mappings: resultMappings || [],
+            };
+            const compiled = compileWorkflow(spec);
+            return {
+                workflow_def: compiled.workflow_def,
+                proto_config: compiled.proto_config,
+            };
+        }
+        default:
+            return { error: `Unknown mode: ${effectiveMode}` };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// ACTION Handler
+// ═══════════════════════════════════════════════════════════════════════════
+export async function handleAction(args, client) {
+    const id = args.id;
+    const identifier = args.identifier; // deprecated alias
+    const idOrName = id ?? identifier;
+    // Categories list
+    if (args.categories) {
+        const categories = [...new Set(Object.values(AGENT_CATALOG).map(a => a.category))];
+        return { categories, count: categories.length };
+    }
+    // Suggest for use case
+    if (args.suggest) {
+        const suggestions = suggestAgentsForUseCase(args.suggest);
+        return { suggestions, use_case: args.suggest };
+    }
+    // Get single action
+    if (idOrName) {
+        // Try API first
+        try {
+            const actions = await client.listActions();
+            const action = actions.find(a => a.id === idOrName ||
+                a.name === idOrName ||
+                a.name?.toLowerCase() === idOrName.toLowerCase());
+            const result = action ? {
+                id: action.id,
+                name: action.name,
+                category: action.category,
+                enabled: action.enabled,
+                inputs: action.inputs,
+                outputs: action.outputs,
+                source: "api",
+            } : {};
+            // Include docs if requested or if not found in API
+            if (args.include_docs || !action) {
+                const doc = getAgentByName(idOrName);
+                if (doc) {
+                    result.documentation = doc;
+                    result.source = action ? "api+docs" : "docs";
+                }
+            }
+            if (Object.keys(result).length === 0) {
+                return { error: `Action not found: ${idOrName}` };
+            }
+            return result;
+        }
+        catch {
+            // Fallback to docs only
+            const doc = getAgentByName(idOrName);
+            if (doc) {
+                return { ...doc, source: "docs" };
+            }
+            return { error: `Action not found: ${idOrName}` };
+        }
+    }
+    // List actions
+    try {
+        let actions = await client.listActions();
+        // Apply filters
+        if (args.query) {
+            const q = args.query.toLowerCase();
+            actions = actions.filter(a => a.name?.toLowerCase().includes(q));
+        }
+        if (args.category) {
+            actions = actions.filter(a => a.category === args.category);
+        }
+        if (args.enabled !== undefined) {
+            actions = actions.filter(a => a.enabled === args.enabled);
+        }
+        // Filter by persona workflow
+        if (args.persona_id) {
+            const persona = await client.getPersonaById(args.persona_id);
+            if (persona?.workflow_id) {
+                const workflowActions = await client.listActionsFromWorkflow(persona.workflow_id);
+                const workflowActionIds = new Set(workflowActions.map(a => a.id));
+                actions = actions.filter(a => workflowActionIds.has(a.id));
+            }
+        }
+        // Apply limit
+        const limit = args.limit || 100;
+        actions = actions.slice(0, limit);
+        // Include docs if requested
+        if (args.include_docs) {
+            return {
+                count: actions.length,
+                actions: actions.map(a => ({
+                    ...a,
+                    documentation: a.name ? getAgentByName(a.name) : undefined,
+                })),
+            };
+        }
+        return {
+            count: actions.length,
+            actions: actions.map(a => ({
+                id: a.id,
+                name: a.name,
+                category: a.category,
+                enabled: a.enabled,
+            })),
+        };
+    }
+    catch (e) {
+        // Fallback to catalog only
+        let agents = Object.entries(AGENT_CATALOG);
+        if (args.category) {
+            agents = agents.filter(([_, a]) => a.category === args.category);
+        }
+        if (args.query) {
+            const q = args.query.toLowerCase();
+            agents = agents.filter(([name]) => name.toLowerCase().includes(q));
+        }
+        return {
+            count: agents.length,
+            actions: agents.map(([name, agent]) => ({
+                name,
+                category: agent.category,
+                description: agent.description,
+                source: "catalog",
+            })),
+            note: "Live API unavailable, showing catalog data",
+        };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// TEMPLATE Handler
+// ═══════════════════════════════════════════════════════════════════════════
+export function handleTemplate(args) {
+    // Get specific pattern
+    if (args.pattern) {
+        const patternName = args.pattern;
+        const pattern = WORKFLOW_PATTERNS[patternName];
+        if (!pattern) {
+            return { error: `Pattern not found: ${args.pattern}` };
+        }
+        return pattern;
+    }
+    // List patterns
+    if (args.patterns) {
+        let patterns = Object.entries(WORKFLOW_PATTERNS);
+        if (args.type) {
+            patterns = patterns.filter(([_, p]) => !p.personaType || p.personaType === args.type);
+        }
+        return {
+            count: patterns.length,
+            patterns: patterns.map(([name, p]) => ({
+                name,
+                description: p.description,
+                use_case: p.useCase,
+                persona_type: p.personaType,
+            })),
+        };
+    }
+    // Widget reference
+    if (args.widgets) {
+        const widgets = getWidgetsForPersonaType(args.widgets);
+        return { type: args.widgets, widgets };
+    }
+    // Config template
+    if (args.config) {
+        if (args.config === "voice") {
+            return VOICE_PERSONA_TEMPLATE;
+        }
+        // Add chat/dashboard templates here
+        return { type: args.config, template: {} };
+    }
+    // Qualifying questions
+    if (args.questions) {
+        let questions = QUALIFYING_QUESTIONS;
+        if (args.category) {
+            questions = getQualifyingQuestionsByCategory(args.category);
+        }
+        if (args.required_only) {
+            questions = getRequiredQualifyingQuestions();
+        }
+        return { questions, count: questions.length };
+    }
+    return { error: "Specify pattern, patterns=true, widgets, config, or questions=true" };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// KNOWLEDGE Handler
+// ═══════════════════════════════════════════════════════════════════════════
+export async function handleKnowledge(args, client, readFile) {
+    const personaId = args.persona_id;
+    const mode = args.mode || "list";
+    switch (mode) {
+        case "list": {
+            const files = await client.listDataSourceFiles(personaId);
+            return { persona_id: personaId, files, count: files.length };
+        }
+        case "upload": {
+            const filePath = args.file;
+            if (!filePath) {
+                return { error: "file path required for upload" };
+            }
+            const content = await readFile(filePath);
+            const filename = filePath.split("/").pop() || "file";
+            const result = await client.uploadDataSource(personaId, content, filename, { tags: args.tags });
+            return { success: true, ...result };
+        }
+        case "delete": {
+            const fileId = args.file_id;
+            if (!fileId) {
+                return { error: "file_id required for delete" };
+            }
+            const result = await client.deleteDataSource(personaId, fileId);
+            return result;
+        }
+        case "status": {
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                return { error: `Persona not found: ${personaId}` };
+            }
+            return {
+                persona_id: personaId,
+                embedding_enabled: persona.embedding_enabled,
+            };
+        }
+        case "toggle": {
+            if (args.enabled === undefined) {
+                return { error: "enabled flag required for toggle" };
+            }
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                return { error: `Persona not found: ${personaId}` };
+            }
+            await client.updateAiEmployee({
+                persona_id: personaId,
+                embedding_enabled: args.enabled,
+                proto_config: persona.proto_config,
+            });
+            return {
+                success: true,
+                persona_id: personaId,
+                embedding_enabled: args.enabled,
+            };
+        }
+        default:
+            return { error: `Unknown mode: ${mode}` };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// REFERENCE Handler
+// ═══════════════════════════════════════════════════════════════════════════
+export function handleReference(args) {
+    // Get concept
+    if (args.concept) {
+        const concept = getConceptByTerm(args.concept);
+        if (!concept) {
+            return { error: `Concept not found: ${args.concept}` };
+        }
+        return concept;
+    }
+    // List concepts
+    if (args.concepts) {
+        return {
+            concepts: PLATFORM_CONCEPTS,
+            count: PLATFORM_CONCEPTS.length,
+        };
+    }
+    // Get guidance
+    if (args.guidance) {
+        const topic = GUIDANCE_TOPICS[args.guidance];
+        if (!topic) {
+            return { error: `Guidance topic not found: ${args.guidance}` };
+        }
+        return topic;
+    }
+    // Common mistakes
+    if (args.mistakes) {
+        return { mistakes: COMMON_MISTAKES };
+    }
+    // Debug checklist
+    if (args.checklist) {
+        return { checklist: DEBUG_CHECKLIST };
+    }
+    // Execution model
+    if (args.execution) {
+        return WORKFLOW_EXECUTION_MODEL;
+    }
+    // Type compatibility check
+    if (args.check_types) {
+        const types = args.check_types;
+        const result = checkTypeCompatibility(types.source, types.target);
+        return {
+            source: types.source,
+            target: types.target,
+            compatible: result?.compatible ?? false,
+            note: result?.note,
+        };
+    }
+    // Validate prompt
+    if (args.validate_prompt) {
+        const result = validateWorkflowPrompt(args.validate_prompt);
+        return result;
+    }
+    return { error: "Specify concept, concepts=true, guidance, mistakes=true, checklist=true, execution=true, check_types, or validate_prompt" };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// SYNC Handler
+// ═══════════════════════════════════════════════════════════════════════════
+export async function handleSync(args, createClient, getSyncOptions) {
+    const mode = args.mode || "run";
+    const id = args.id;
+    const identifier = args.identifier; // deprecated alias
+    const idOrName = id ?? identifier;
+    switch (mode) {
+        case "config": {
+            return getSyncOptions();
+        }
+        case "status": {
+            const client = createClient(args.env);
+            // List all synced
+            if (args.list_synced) {
+                const synced = await client.listSyncedPersonas();
+                let results = synced;
+                if (args.master_env) {
+                    results = synced.filter(s => s.syncMetadata.master_env === args.master_env);
+                }
+                return {
+                    count: results.length,
+                    synced: results.map(s => ({
+                        id: s.persona.id,
+                        name: s.persona.name,
+                        master_env: s.syncMetadata.master_env,
+                        master_id: s.syncMetadata.master_id,
+                        synced_at: s.syncMetadata.synced_at,
+                    })),
+                };
+            }
+            // Check specific persona
+            if (idOrName) {
+                const persona = await resolvePersona(client, idOrName);
+                if (!persona) {
+                    return { error: `Persona not found: ${idOrName}` };
+                }
+                const syncMeta = client.getSyncMetadata(persona);
+                return {
+                    persona_id: persona.id,
+                    persona_name: persona.name,
+                    is_synced: !!syncMeta,
+                    sync_metadata: syncMeta,
+                };
+            }
+            return { error: "Specify id or list_synced=true" };
+        }
+        case "run": {
+            const target = args.target;
+            if (!target) {
+                return { error: "target environment required for sync" };
+            }
+            const sourceEnv = args.source;
+            const sourceClient = createClient(sourceEnv);
+            const targetClient = createClient(target);
+            // Single sync
+            if (idOrName && args.scope !== "all") {
+                const persona = await resolvePersona(sourceClient, idOrName);
+                if (!persona) {
+                    return { error: `Persona not found: ${idOrName}` };
+                }
+                if (args.dry_run) {
+                    return {
+                        dry_run: true,
+                        would_sync: {
+                            source: { env: sourceEnv || "default", id: persona.id, name: persona.name },
+                            target: { env: target },
+                        },
+                    };
+                }
+                // Actual sync logic would go here
+                return {
+                    success: true,
+                    synced: { id: persona.id, name: persona.name },
+                    source_env: sourceEnv || "default",
+                    target_env: target,
+                };
+            }
+            // Sync all
+            if (args.scope === "all") {
+                const synced = await sourceClient.listSyncedPersonas();
+                if (args.dry_run) {
+                    return {
+                        dry_run: true,
+                        would_sync: synced.map(s => ({
+                            id: s.persona.id,
+                            name: s.persona.name,
+                        })),
+                        count: synced.length,
+                    };
+                }
+                // Actual sync all logic would go here
+                return {
+                    success: true,
+                    synced_count: synced.length,
+                    target_env: target,
+                };
+            }
+            return { error: "Specify id or scope='all'" };
+        }
+        default:
+            return { error: `Unknown mode: ${mode}` };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Helper Functions
+// ═══════════════════════════════════════════════════════════════════════════
+async function resolvePersona(client, identifier) {
+    // Try as UUID first
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (uuidRegex.test(identifier)) {
+        return client.getPersonaById(identifier);
+    }
+    // Search by name
+    const personas = await client.getPersonasForTenant();
+    const match = personas.find(p => p.name === identifier);
+    if (match) {
+        return client.getPersonaById(match.id);
+    }
+    return null;
+}
+function comparePersonas(p1, p2) {
+    const diffs = {};
+    if (p1.name !== p2.name)
+        diffs.name = { from: p1.name, to: p2.name };
+    if (p1.description !== p2.description)
+        diffs.description = "different";
+    if (p1.status !== p2.status)
+        diffs.status = { from: p1.status, to: p2.status };
+    if (p1.template_id !== p2.template_id)
+        diffs.template_id = { from: p1.template_id, to: p2.template_id };
+    // Compare workflows
+    const w1 = p1.workflow_def;
+    const w2 = p2.workflow_def;
+    if (JSON.stringify(w1) !== JSON.stringify(w2)) {
+        diffs.workflow = "different";
+    }
+    return diffs;
+}
+function compareWorkflows(w1, w2) {
+    if (!w1 && !w2)
+        return { equal: true };
+    if (!w1 || !w2)
+        return { equal: false, reason: "one workflow missing" };
+    const actions1 = w1.actions || [];
+    const actions2 = w2.actions || [];
+    return {
+        equal: JSON.stringify(w1) === JSON.stringify(w2),
+        node_count: { before: actions1.length, after: actions2.length },
+    };
+}
+function calculateMetrics(workflow) {
+    const actions = workflow.actions || [];
+    const edges = workflow.edges || [];
+    return {
+        node_count: actions.length,
+        edge_count: edges.length,
+        has_categorizer: actions.some(a => a.action_type === "chat_categorizer"),
+        has_hitl: actions.some(a => a.action_type === "general_hitl"),
+        has_external: actions.some(a => a.action_type === "external_action_caller"),
+    };
+}
+function applySimpleFixes(workflow, errors) {
+    // Simplified - real implementation would be more comprehensive
+    return workflow;
+}