@ema.co/mcp-toolkit 2026.2.19 → 2026.2.23

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

@@ -0,0 +1,133 @@
+/**
+ * Debug Handler — Method Dispatch
+ *
+ * Routes debug tool methods to the appropriate SDK calls and formatters.
+ * Follows the drill-down pattern: conversations → conversation_detail → show_work → action_detail
+ */
+import { formatConversations, formatConversationDetail, formatShowWork, formatActionDetail, formatSearch, } from "./formatters.js";
+export async function handleDebug(args, client) {
+    const method = args.method;
+    if (!method) {
+        return {
+            error: "Missing required parameter: method",
+            available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "search"],
+            _tip: "Start with debug(method='conversations', persona_id='...') to list audit conversations.",
+        };
+    }
+    switch (method) {
+        case "conversations":
+            return handleConversations(args, client);
+        case "conversation_detail":
+            return handleConversationDetail(args, client);
+        case "show_work":
+            return handleShowWork(args, client);
+        case "action_detail":
+            return handleActionDetail(args, client);
+        case "search":
+            return handleSearch(args, client);
+        default:
+            return {
+                error: `Unknown method: ${method}`,
+                available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "search"],
+            };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Method handlers
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleConversations(args, client) {
+    const personaId = args.persona_id;
+    if (!personaId) {
+        return { error: "Missing required parameter: persona_id" };
+    }
+    // Build filters matching the gRPC ConversationReviewFilters proto shape
+    const filters = {};
+    if (args.start_time)
+        filters.createdFrom = new Date(String(args.start_time));
+    if (args.end_time)
+        filters.createdTo = new Date(String(args.end_time));
+    if (args.channel)
+        filters.channel = Number(args.channel);
+    if (args.status)
+        filters.status = Number(args.status);
+    if (args.search_query)
+        filters.searchQuery = String(args.search_query);
+    if (args.workflow_failure)
+        filters.workflowFailure = true;
+    if (args.has_user_frustration)
+        filters.hasUserFrustration = true;
+    if (args.no_results_found)
+        filters.noResultsFound = true;
+    const opts = {
+        ...(Object.keys(filters).length > 0 ? { filters } : {}),
+        ...(args.limit ? { limit: Number(args.limit) } : {}),
+        ...(args.pagination_token ? { paginationToken: String(args.pagination_token) } : {}),
+    };
+    const response = await client.getConversationReviews(personaId, opts);
+    return formatConversations(response, personaId);
+}
+async function handleConversationDetail(args, client) {
+    const conversationId = args.conversation_id;
+    if (!conversationId) {
+        return { error: "Missing required parameter: conversation_id" };
+    }
+    const personaId = args.persona_id;
+    const response = await client.getConversationReviewDetail(conversationId);
+    return formatConversationDetail(response, conversationId, personaId);
+}
+async function handleShowWork(args, client) {
+    const workflowRunId = args.workflow_run_id;
+    const personaId = args.persona_id;
+    if (!workflowRunId) {
+        return { error: "Missing required parameter: workflow_run_id" };
+    }
+    if (!personaId) {
+        return {
+            error: "Missing required parameter: persona_id",
+            _tip: "DebugLogService requires persona context. Pass persona_id alongside workflow_run_id.",
+        };
+    }
+    const response = await client.getWorkflowLevelDebugLog(workflowRunId, personaId);
+    return formatShowWork(response, workflowRunId, personaId);
+}
+async function handleActionDetail(args, client) {
+    const workflowRunId = args.workflow_run_id;
+    const actionName = args.action_name;
+    const personaId = args.persona_id;
+    if (!workflowRunId) {
+        return { error: "Missing required parameter: workflow_run_id" };
+    }
+    if (!actionName) {
+        return {
+            error: "Missing required parameter: action_name",
+            _tip: "Use debug(method='show_work') first to see available action names.",
+        };
+    }
+    if (!personaId) {
+        return {
+            error: "Missing required parameter: persona_id",
+            _tip: "DebugLogService requires persona context. Pass persona_id alongside workflow_run_id and action_name.",
+        };
+    }
+    const response = await client.getActionLevelShowWorkLog(actionName, workflowRunId, personaId);
+    return formatActionDetail(response, workflowRunId, actionName);
+}
+async function handleSearch(args, client) {
+    const personaId = args.persona_id;
+    const query = args.query;
+    if (!personaId) {
+        return { error: "Missing required parameter: persona_id" };
+    }
+    if (!query) {
+        return { error: "Missing required parameter: query" };
+    }
+    const opts = { personaId, query };
+    if (args.conversation_id)
+        opts.conversationId = String(args.conversation_id);
+    if (args.start_time)
+        opts.startTime = new Date(String(args.start_time));
+    if (args.end_time)
+        opts.endTime = new Date(String(args.end_time));
+    const response = await client.searchMessages(opts);
+    return formatSearch(response, query, personaId);
+}

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

@@ -0,0 +1,180 @@
+/**
+ * Demo V2 Adapter
+ *
+ * Routes the consolidated demo tool modes (kit, validate_kit, scenarios,
+ * consolidate, generate, validate, template) to the appropriate handlers.
+ *
+ * Extracted from server.ts to keep the dispatch table thin.
+ */
+import { handleConsolidateDemoData, handleGenerateDemoDocument, handleValidateDemoDocument, handleGetDemoDataTemplate, } from "./index.js";
+export async function handleDemoAdapter(args, createClient) {
+    const normalizedArgs = { ...(args ?? {}) };
+    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : "template";
+    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": {
+            const personaId = String(normalizedArgs.persona_id ?? "");
+            const scenarioId = String(normalizedArgs.scenario ?? "sales-sdr");
+            if (!personaId) {
+                throw new Error('demo(mode="kit") requires: persona_id');
+            }
+            const { generateDemoKit, DEMO_SCENARIOS, generateDemoScriptMarkdown, validateDemoKit } = await import("../../demo-generator.js");
+            const scenario = DEMO_SCENARIOS[scenarioId];
+            if (!scenario) {
+                throw new Error(`Unknown scenario: ${scenarioId}. Available: ${Object.keys(DEMO_SCENARIOS).join(", ")}`);
+            }
+            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;
+            const kit = generateDemoKit(personaId, persona.name || personaId, workflowDef, scenario, customQA);
+            const demoScript = generateDemoScriptMarkdown(kit);
+            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": {
+            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 || {});
+            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");
+            }
+            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": {
+            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}`);
+    }
+}

package/dist/mcp/handlers/env/config.js

@@ -9,7 +9,7 @@ import { readFileSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { EmaClient } from "../../../sdk/client.js";
+import { EmaClientAdapter } from "../../../sdk/client-adapter.js";
 import { loadConfigOptional } from "../../../sdk/config.js";
 import { SyncSDK } from "../../../sync/sdk.js";
 // ─────────────────────────────────────────────────────────────────────────────
@@ -282,7 +282,7 @@ export function createClient(envName) {
             },
         }
         : undefined;
-    return new EmaClient({
+    return new EmaClientAdapter({
         name: envInfo.name,
         baseUrl: envInfo.baseUrl,
         bearerToken,

package/dist/mcp/handlers/index.js

@@ -27,6 +27,5 @@ export { handleEnv } from "./env/index.js";
 export { handleTemplate } from "./template/index.js";
 export { handleAction } from "./action/index.js";
 export { handleReference } from "./reference/index.js";
-export { handleKnowledge } from "./knowledge/index.js";
 export { handleSync } from "./sync/index.js";
 // Note: handleDashboardGenerate removed - LLM generates content, MCP uploads via data.method="upload"

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

@@ -0,0 +1,135 @@
+/**
+ * Persona V2 Adapter
+ *
+ * Converts the V2 method-based persona tool args into the internal
+ * mode-based format expected by handlePersona, routes data sub-resource
+ * operations directly to handleData, and executes action composition
+ * post-processing.
+ *
+ * Extracted from server.ts to keep the dispatch table thin.
+ */
+import { handlePersona } from "./index.js";
+export async function handlePersonaAdapter(args, createClient, getDefaultEnvName) {
+    const targetEnv = args.env ?? getDefaultEnvName();
+    const client = createClient(targetEnv);
+    const versionContext = {
+        workspaceRoot: process.cwd(),
+        environment: targetEnv,
+        tenant_id: targetEnv,
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // Debug Sub-Resource (intercepted before data)
+    //
+    // persona(id="abc", debug={method:"conversations"}) routes to handleDebug.
+    // Injects persona_id for methods that need it (conversations, search).
+    // ─────────────────────────────────────────────────────────────────────────
+    if (args.debug && typeof args.debug === "object") {
+        const debug = args.debug;
+        const personaId = args.id;
+        if (typeof debug.method === "string") {
+            const { handleDebugAdapter } = await import("../debug/adapter.js");
+            return handleDebugAdapter({ ...debug, persona_id: debug.persona_id ?? personaId, env: args.env }, createClient, getDefaultEnvName);
+        }
+        return {
+            error: "Missing debug.method",
+            hint: "Use debug={method:'conversations'} format",
+            available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "search"],
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Data Sub-Resource (intercepted after debug — bypasses persona routing entirely)
+    //
+    // persona(id="abc", data={method:"list"}) routes directly to handleData.
+    // This avoids data operations flowing through handlePersona's routing.
+    // Direct callers of handlePersona (e.g. tests) still use its own data routing.
+    // ─────────────────────────────────────────────────────────────────────────
+    if (args.data && typeof args.data === "object") {
+        const data = args.data;
+        const personaId = args.id;
+        if (typeof data.method === "string") {
+            const { handleData: handleDataDirect } = await import("../data/index.js");
+            return handleDataDirect({ persona_id: personaId, env: args.env, data }, client);
+        }
+        return {
+            error: "Missing data.method",
+            hint: "Use data={method:'list'} format",
+            available_methods: ["list", "stats", "upload", "copy", "replicate", "delete", "search", "refresh", "regenerate", "replace"],
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // V2 Parameter Transformation
+    // Convert v2 structure to v1 mode-based structure for handler compatibility
+    // ─────────────────────────────────────────────────────────────────────────
+    const transformedArgs = { ...args };
+    // ─────────────────────────────────────────────────────────────────────────
+    // Method → Mode mapping
+    // persona(method="create|get|list|update|delete|sanitize|snapshot|history|restore")
+    // ─────────────────────────────────────────────────────────────────────────
+    if (args.method) {
+        const method = String(args.method);
+        if (method === "analyze" || method === "compare") {
+            return {
+                error: `method="${method}" is removed. Use persona(method="get", id="...") and analyze/compare the results yourself.`,
+            };
+        }
+        const methodToMode = {
+            create: "create",
+            get: "get",
+            list: "list",
+            update: "update",
+            delete: "delete",
+            sanitize: "sanitize",
+            schema: "schema",
+            clone: "create",
+            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;
+        if (args.actions && Array.isArray(args.actions)) {
+            transformedArgs._actions = args.actions;
+            delete transformedArgs.actions;
+        }
+    }
+    else if (args.id) {
+        transformedArgs.mode = "get";
+    }
+    else {
+        transformedArgs.mode = "list";
+    }
+    const result = await handlePersona(transformedArgs, client, () => undefined, (env) => createClient(env), versionContext);
+    // ─────────────────────────────────────────────────────────────────────────
+    // Action Composition Post-Processing
+    // ─────────────────────────────────────────────────────────────────────────
+    const actions = transformedArgs._actions;
+    if (actions && actions.length > 0) {
+        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",
+            };
+        }
+        const actionExecutor = await import("../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;
+}

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

@@ -0,0 +1,200 @@
+/**
+ * Sync V2 Adapter
+ *
+ * Contains syncRunImpl / syncInfoImpl implementation functions and the
+ * top-level sync tool handler that routes method ↔ mode and normalises arg
+ * names between the V2 tool schema and the internal sync implementation.
+ *
+ * Extracted from server.ts to keep the dispatch table thin.
+ */
+import { resolveSyncBehavior, loadSyncOptions } from "../../../sync/sync-options.js";
+import { directSyncPersona, directSyncPersonaById, directSyncAll } from "./direct.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Implementation helpers
+// ─────────────────────────────────────────────────────────────────────────────
+async function syncRunImpl(args, getDefaultEnvName, getSyncSDK) {
+    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;
+    if (scope === "all" || !identifier) {
+        const sdk = getSyncSDK();
+        if (sdk) {
+            try {
+                const result = await sdk.runSync();
+                return { success: true, mode: "config", ...result };
+            }
+            finally {
+                sdk.close();
+            }
+        }
+        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) };
+        }
+    }
+    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, createClient, getSyncSDK) {
+    const client = args.env ? createClient(args.env) : undefined;
+    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,
+        };
+    }
+    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();
+        }
+    }
+    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 };
+    }
+    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();
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Top-level sync tool handler
+// ─────────────────────────────────────────────────────────────────────────────
+export async function handleSyncAdapter(args, createClient, getDefaultEnvName, getSyncSDK) {
+    const normalizedArgs = { ...(args ?? {}) };
+    const rawMethod = normalizedArgs.method ? String(normalizedArgs.method) : normalizedArgs.mode ? String(normalizedArgs.mode) : "run";
+    const mode = rawMethod === "preview" ? "run" : rawMethod === "execute" ? "run" : rawMethod;
+    if (rawMethod === "preview") {
+        normalizedArgs.dry_run = true;
+    }
+    const target = (normalizedArgs.target ?? normalizedArgs.target_env);
+    const source = (normalizedArgs.source ?? normalizedArgs.source_env);
+    const id = normalizedArgs.id;
+    const identifier = normalizedArgs.identifier;
+    const idOrIdentifier = id ?? identifier;
+    if (mode === "config") {
+        return syncInfoImpl({ include_options: true }, createClient, getSyncSDK);
+    }
+    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 }, createClient, getSyncSDK);
+        }
+        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 }, createClient, getSyncSDK);
+            }
+            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 }, createClient, getSyncSDK);
+        }
+        return syncInfoImpl({ include_options: normalizedArgs.include_options === true }, createClient, getSyncSDK);
+    }
+    // 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,
+    }, getDefaultEnvName, getSyncSDK);
+}