@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23-1

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/persona/index.js

@@ -1,9 +1,9 @@
 /**
- * Persona Handler - Dispatch Table Pattern
+ * Persona Handler - Dispatch Table + Top-Level Router
  *
  * This module exports persona mode handlers using a dispatch table
- * instead of a giant switch statement. Each mode is in its own file
- * for better testability and maintainability.
+ * and provides the top-level `handlePersona` function that was previously
+ * (previously in the now-deleted handlers-consolidated.ts).
  *
  * Persona modes:
  * - get: Fetch single persona (LLM then analyzes the data)
@@ -13,7 +13,7 @@
  * - update: Update persona config
  * - delete: Delete persona (with confirmation)
  * - create/clone: Create new persona from template or clone existing
- * - intent: Direct Intent Architect invocation for qualification
+ * - schema: Get persona input schema (dashboard columns, types)
  *
  * REMOVED (LLM does these):
  * - analyze: LLM analyzes data from 'get'
@@ -23,6 +23,10 @@
  * - snapshot/version_create, history/version_list, version_get
  * - version_compare, restore/version_restore, version_policy
  */
+import { resolvePersona } from "../utils.js";
+import { checkDeprecatedParams, addDeprecationWarnings } from "../deprecation.js";
+import { handleData } from "../data/index.js";
+import { handleWorkflow } from "../workflow/index.js";
 // Import mode handlers
 import { handleGet } from "./get.js";
 import { handleList } from "./list.js";
@@ -31,7 +35,7 @@ import { handleSanitize } from "./sanitize.js";
 import { handleUpdate } from "./update.js";
 import { handleDelete } from "./delete.js";
 import { handleCreate } from "./create.js";
-import { handleIntent } from "./intent.js";
+import { handleSchema } from "./schema.js";
 /**
  * Dispatch table for persona modes
  *
@@ -48,7 +52,7 @@ export const PERSONA_MODE_HANDLERS = {
     delete: handleDelete,
     create: handleCreate,
     clone: handleCreate, // Clone uses same handler as create
-    intent: handleIntent,
+    schema: handleSchema,
 };
 /**
  * Check if a mode has been extracted to this module
@@ -70,7 +74,232 @@ export { handleSanitize } from "./sanitize.js";
 export { handleUpdate } from "./update.js";
 export { handleDelete } from "./delete.js";
 export { handleCreate } from "./create.js";
-export { handleIntent } from "./intent.js";
-// REMOVED: handleCompare, handleAnalyze - LLM does analysis/comparison
+export { handleSchema } from "./schema.js";
 // Version management
 export { handleVersion, isVersionMode } from "./version.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// Top-level Persona Router
+// ═══════════════════════════════════════════════════════════════════════════
+import { handleVersion } from "./version.js";
+/**
+ * Top-level persona handler that routes to mode-specific handlers.
+ *
+ * Handles:
+ * - Data sub-resource routing (data={method:...})
+ * - Legacy workflow routing (optimize flag, workflow_def without update mode)
+ * - Mode resolution and dispatch
+ * - Version management modes
+ */
+export async function handlePersona(args, client, getTemplateId, createClientForEnv, versionContext) {
+    const deprecationWarnings = checkDeprecatedParams(args);
+    for (const warning of deprecationWarnings) {
+        console.warn(`[persona] Deprecation: ${warning}`);
+    }
+    const id = args.id;
+    const identifier = args.identifier;
+    const idOrName = id ?? identifier;
+    // Support both 'method' (new) and 'mode' (legacy) - method takes precedence
+    const method = args.method;
+    const mode = method ?? args.mode;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // DATA SUB-RESOURCE: Handle data={method:...} early
+    // ═══════════════════════════════════════════════════════════════════════════
+    const dataArg = args.data;
+    if (dataArg && typeof dataArg === "object") {
+        if (!idOrName) {
+            return {
+                error: "Data operations require persona id",
+                hint: "Use persona(id=\"abc\", data={method:\"list\"})",
+            };
+        }
+        const dataMethod = dataArg.method;
+        if (!dataMethod) {
+            return {
+                error: "Data operations require explicit method",
+                hint: "Use data={method:\"list|schema|upload|copy|delete|embed|search\", ...}",
+                valid_methods: ["list", "schema", "upload", "copy", "delete", "embed", "search"],
+            };
+        }
+        const methodToMode = {
+            "list": "list",
+            "schema": "schema",
+            "upload": "upload",
+            "copy": "dashboard_clone",
+            "delete": "delete",
+            "embed": "embed",
+            "search": "search",
+        };
+        const mappedMode = methodToMode[dataMethod];
+        if (!mappedMode) {
+            return {
+                error: `Unknown data method: ${dataMethod}`,
+                valid_methods: Object.keys(methodToMode),
+            };
+        }
+        const dataArgs = {
+            persona_id: idOrName,
+            mode: mappedMode,
+        };
+        if (dataArg.from)
+            dataArgs.source_persona_id = dataArg.from;
+        if (dataArg.sanitize !== undefined)
+            dataArgs.sanitize = dataArg.sanitize;
+        if (dataArg.path)
+            dataArgs.file_path = dataArg.path;
+        if (dataArg.content)
+            dataArgs.content = dataArg.content;
+        if (dataArg.file_id)
+            dataArgs.file_id = dataArg.file_id;
+        else if (dataArg.id)
+            dataArgs.file_id = dataArg.id;
+        if (dataArg.enabled !== undefined)
+            dataArgs.embed = dataArg.enabled;
+        if (dataArg.query)
+            dataArgs.query = dataArg.query;
+        const readFile = async (path) => {
+            const fs = await import("fs/promises");
+            return fs.readFile(path);
+        };
+        return handleData(dataArgs, client, readFile);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ROUTING: Persona operations
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LLM-DRIVEN ARCHITECTURE:
+    // - persona tool: config changes only (name, description, widgets)
+    // - workflow tool: ALL workflow changes (get → modify → deploy)
+    // mode="update" → modular handleUpdate (config changes, workflow_spec for rewire/remove only)
+    if (mode === "update" && idOrName) {
+        return getPersonaModeHandler("update")(args, client);
+    }
+    // Legacy: optimize flag routes to workflow handler
+    const optimize = args.optimize;
+    const workflowDef = args.workflow_def ?? args.workflow;
+    if (optimize || (idOrName && workflowDef && mode !== "update")) {
+        const workflowArgs = {
+            ...args,
+            persona_id: idOrName,
+        };
+        delete workflowArgs.id;
+        delete workflowArgs.identifier;
+        return handleWorkflow(workflowArgs, client, getTemplateId);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Standard persona operations (get, list, compare, version management)
+    // ═══════════════════════════════════════════════════════════════════════════
+    const fromParam = args.from;
+    const cloneFromParam = args.clone_from;
+    const templateIdParam = args.template_id;
+    const hasBase = fromParam || cloneFromParam || templateIdParam;
+    let effectiveMode = mode;
+    if (!effectiveMode) {
+        const availableMethods = ["list", "get", "create", "update", "delete", "analyze", "sanitize", "snapshot", "history", "restore", "compare"];
+        if (idOrName && args.proto_config) {
+            return {
+                error: "Explicit method required",
+                message: "You provided id and proto_config. Did you want to update this persona?",
+                suggested_method: "update",
+                hint: "Use method='update' to apply changes",
+                example: `persona(method="update", id="${idOrName}", config={...})`,
+            };
+        }
+        else if (idOrName) {
+            return {
+                error: "Explicit method required",
+                message: "You provided a persona id/name. What operation would you like to perform?",
+                valid_methods: ["get", "update", "delete", "sanitize", "snapshot", "history", "restore"],
+                hint: "LLM does analysis/comparison. Use method='get' to fetch data, then reason about it.",
+                example: `persona(method="get", id="${idOrName}")`,
+            };
+        }
+        else if (hasBase || (args.name && args.type)) {
+            return {
+                error: "Explicit method required",
+                message: "You provided creation parameters. Did you want to create a new persona?",
+                suggested_method: "create",
+                hint: "Use method='create'",
+                example: `persona(method="create", name="...", type="voice")`,
+            };
+        }
+        else {
+            return {
+                error: "Explicit method required",
+                message: "All persona operations require explicit method parameter",
+                valid_methods: availableMethods,
+                examples: [
+                    'persona(method="list") - list all personas',
+                    'persona(method="get", id="...") - get specific persona',
+                    'persona(method="create", name="...", type="voice") - create new',
+                    'persona(method="update", id="...", config={...}) - update config',
+                    'persona(method="delete", id="...", confirm=true) - delete',
+                ],
+            };
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Dispatch to handlers via dispatch table
+    // ─────────────────────────────────────────────────────────────────────────
+    if (hasExtractedHandler(effectiveMode)) {
+        const handler = getPersonaModeHandler(effectiveMode);
+        if (handler) {
+            let extraContext = undefined;
+            if (effectiveMode === "create" || effectiveMode === "clone") {
+                extraContext = getTemplateId;
+            }
+            else if (effectiveMode === "compare") {
+                extraContext = createClientForEnv;
+            }
+            const result = await handler(args, client, extraContext);
+            return addDeprecationWarnings(result, deprecationWarnings);
+        }
+    }
+    switch (effectiveMode) {
+        // Fallback cases for modes already in dispatch table (should not be reached)
+        case "get":
+        case "list":
+        case "templates":
+        case "sanitize":
+        case "update":
+        case "delete": {
+            return { error: `Mode "${effectiveMode}" should be handled by extracted handler` };
+        }
+        // Clone and create - handled by dispatch table
+        case "clone":
+        case "create": {
+            return { error: `Mode "${effectiveMode}" should be handled by extracted handler` };
+        }
+        // Analyze and compare - LLM does this, not MCP
+        case "analyze":
+        case "compare": {
+            return {
+                error: `Method "${effectiveMode}" removed - LLM does analysis/comparison`,
+                hint: "Use method='get' to fetch persona data, then do your own analysis/comparison.",
+                example: `persona(method="get", id="...", include_workflow=true)`,
+            };
+        }
+        // ─────────────── Version Management Modes ───────────────
+        case "snapshot":
+        case "history":
+        case "restore":
+        case "version_create":
+        case "version_list":
+        case "version_get":
+        case "version_compare":
+        case "version_restore":
+        case "version_policy": {
+            if (!idOrName) {
+                return { error: `id required for ${effectiveMode} mode` };
+            }
+            if (!versionContext) {
+                return { error: "Version tracking not configured. Provide workspaceRoot in context." };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            return handleVersion(effectiveMode, args, client, persona, versionContext);
+        }
+        default:
+            return { error: `Unknown mode: ${effectiveMode}` };
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Schema Handler - Get persona input schema (dashboard columns, types)
+ */
+import { resolvePersona } from "../utils.js";
+export async function handleSchema(args, client) {
+    const id = (args.id ?? args.identifier);
+    if (!id) {
+        return { error: "id required for schema mode" };
+    }
+    const persona = await resolvePersona(client, id);
+    if (!persona) {
+        return { error: `Persona not found: ${id}` };
+    }
+    try {
+        const schema = await client.getDashboardSchema(persona.id, persona.id);
+        return {
+            mode: "schema",
+            persona_id: persona.id,
+            persona_name: persona.name,
+            schema: schema,
+            column_count: schema.columns?.length ?? 0,
+        };
+    }
+    catch (error) {
+        return { error: `Failed to get schema: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}

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

@@ -4,7 +4,7 @@
  * Unified reference tool for envs, actions, templates, patterns, concepts, guidance.
  */
 import { errorResult } from "../types.js";
-import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, } from "../../knowledge.js";
+import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, } from "../../knowledge.js";
 /**
  * Handle reference tool requests - unified lookup for all reference data
  */
@@ -284,10 +284,12 @@ export async function handleReference(args, context) {
             note: result?.note,
         };
     }
-    // Validate prompt
+    // Validate prompt (deprecated — LLM responsibility)
     if (args.validate_prompt) {
-        const result = validateWorkflowPrompt(args.validate_prompt);
-        return result;
+        return {
+            error: "Workflow prompt validation is the LLM's responsibility. Use workflow(mode='validate') for structural validation.",
+            _deprecated: true,
+        };
     }
     // ─────────────────────────────────────────────────────────────────────────
     // type="demo_kits" or demo_kits=true - List demo kits

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);
+}