@ema.co/mcp-toolkit 1.6.0 → 1.7.1

package/dist/mcp/handlers-consolidated.js

@@ -11,7 +11,9 @@ import { compileWorkflow } from "../sdk/workflow-generator.js";
 import { ensureActionRegistry } from "../sdk/action-registry.js";
 import { parseInput, intentToSpec, generateWorkflow } from "../sdk/workflow-intent.js";
 import { ensureSchemaRegistry, validateWorkflowSpec, generateActionCatalogForLLM } from "../sdk/workflow-validator.js";
+import { runIntentArchitect } from "../sdk/intent-architect.js";
 import { analyzeExecutionFlow, generateASCIIFlow } from "../sdk/workflow-execution-analyzer.js";
+import { SanitizationSession, sanitizePersona, buildConfirmationPrompt, detectWithPatterns, } from "../sdk/sanitizer.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Widget Validation Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -45,7 +47,7 @@ function validateWidgetsForApi(widgets) {
 // ═══════════════════════════════════════════════════════════════════════════
 // ENV Handler
 // ═══════════════════════════════════════════════════════════════════════════
-export async function handleEnv(_args, getEnvironments) {
+export async function handleEnv(_args, getEnvironments, toolkit) {
     const envs = getEnvironments();
     return {
         environments: envs.map(e => ({
@@ -53,6 +55,7 @@ export async function handleEnv(_args, getEnvironments) {
             default: e.isDefault,
         })),
         count: envs.length,
+        toolkit: toolkit ?? { name: "unknown", version: "unknown" },
     };
 }
 // ═══════════════════════════════════════════════════════════════════════════
@@ -87,12 +90,17 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
     // Standard persona operations (get, list, compare, version management)
     // ═══════════════════════════════════════════════════════════════════════════
     // Determine effective mode
+    // BUG FIX: clone_from and name+type now properly route to "create" 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 (args.sanitize && idOrName)
+            effectiveMode = "sanitize"; // Standalone sanitize mode
+        else if (args.clone_from || (args.name && (args.type || args.template_id)))
+            effectiveMode = "create";
         else if (idOrName)
             effectiveMode = "get";
         else
@@ -176,18 +184,267 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
             if (!templateId && args.type) {
                 templateId = getTemplateId(args.type);
             }
+            // Check if cloning from dashboard persona
+            const cloneFrom = args.clone_from;
+            const cloneData = args.clone_data;
+            let sourcePersona = null;
+            let sourcePersonaType;
+            let sourceDashboardId;
+            if (cloneFrom && cloneData) {
+                try {
+                    sourcePersona = await resolvePersona(client, cloneFrom);
+                    if (sourcePersona) {
+                        // Use trigger_type (root level) for reliable persona type detection
+                        // trigger_type: 0=chat, 1=voice, 2=dashboard
+                        const triggerType = sourcePersona.trigger_type;
+                        if (triggerType === 1) {
+                            sourcePersonaType = "voice";
+                        }
+                        else if (triggerType === 2) {
+                            sourcePersonaType = "dashboard";
+                        }
+                        else if (triggerType === 0) {
+                            sourcePersonaType = "chat";
+                        }
+                        sourceDashboardId = sourcePersona.workflow_dashboard_id;
+                    }
+                }
+                catch {
+                    // Ignore errors in source persona detection
+                }
+            }
             const result = await client.createAiEmployee({
                 name,
                 description: args.description,
                 template_id: templateId,
-                source_persona_id: args.clone_from,
-                clone_data: args.clone_data,
+                source_persona_id: cloneFrom,
+                clone_data: cloneData,
             });
-            return {
+            const newPersonaId = result.persona_id ?? result.id;
+            // Automatically clone dashboard rows if source is a dashboard persona
+            let dashboardCloneResult;
+            if (sourcePersonaType === "dashboard" && sourceDashboardId && newPersonaId && cloneData) {
+                try {
+                    // Dashboard operations require the persona to be enabled
+                    // Auto-enable the persona temporarily for cloning
+                    const newPersona = await client.getPersonaById(newPersonaId);
+                    const newPersonaProtoConfig = newPersona?.proto_config;
+                    // Enable the persona so we can add dashboard rows
+                    await client.updateAiEmployee({
+                        persona_id: newPersonaId,
+                        proto_config: newPersonaProtoConfig ?? {},
+                        enabled_by_user: true,
+                    });
+                    // Get source dashboard rows
+                    const sourceRows = await client.getDashboardRows(sourceDashboardId, sourcePersona.id);
+                    if (sourceRows.rows.length > 0) {
+                        // Identify input columns
+                        const inputColumns = sourceRows.schema.columns.filter(c => c.isInput);
+                        // Clone each row
+                        const results = [];
+                        const shouldSanitize = args.sanitize;
+                        const sanitizeExamples = args.sanitize_examples;
+                        // Create sanitization session if needed
+                        let sanitizationSession;
+                        if (shouldSanitize) {
+                            sanitizationSession = new SanitizationSession();
+                        }
+                        // Track document inputs that couldn't be cloned (require manual re-upload)
+                        const allSkippedDocuments = [];
+                        for (const row of sourceRows.rows) {
+                            try {
+                                // Build inputs from row's input column values
+                                const inputs = [];
+                                const rowSkippedDocs = [];
+                                for (const inputCol of inputColumns) {
+                                    const colValue = row.columnValues.find(cv => cv.columnId === inputCol.columnId);
+                                    if (!colValue)
+                                        continue;
+                                    // Handle different column types
+                                    if (inputCol.columnType === "COLUMN_TYPE_DOCUMENT") {
+                                        // Document inputs can't be auto-cloned (no download API for original files)
+                                        // Track them for manual re-upload notification
+                                        const docValues = colValue.value.documentCellValue?.documentValues ?? [];
+                                        for (const doc of docValues) {
+                                            if (!doc.deleted) {
+                                                rowSkippedDocs.push({
+                                                    name: inputCol.name,
+                                                    original_filename: doc.name
+                                                });
+                                                allSkippedDocuments.push({
+                                                    column: inputCol.name,
+                                                    filename: doc.name,
+                                                    contentNodeId: doc.contentNodeId,
+                                                });
+                                            }
+                                        }
+                                        continue;
+                                    }
+                                    else if (inputCol.columnType === "COLUMN_TYPE_STRING") {
+                                        let value = colValue.value.stringValue ?? "";
+                                        // Sanitize if enabled
+                                        if (sanitizationSession && value) {
+                                            const detected = detectWithPatterns(value);
+                                            for (const entity of detected) {
+                                                const replacement = sanitizationSession.getOrCreateReplacement(entity.value, entity.type);
+                                                value = value.split(entity.value).join(replacement);
+                                            }
+                                            if (sanitizeExamples) {
+                                                for (const example of sanitizeExamples) {
+                                                    if (value.includes(example)) {
+                                                        const replacement = sanitizationSession.getOrCreateReplacement(example, "unknown");
+                                                        value = value.split(example).join(replacement);
+                                                    }
+                                                }
+                                            }
+                                        }
+                                        inputs.push({ name: inputCol.name, string_value: value });
+                                    }
+                                    else if (inputCol.columnType === "COLUMN_TYPE_ARRAY") {
+                                        const arrayVals = colValue.value.arrayValue?.arrayValues ?? [];
+                                        if (arrayVals.length > 0) {
+                                            let value = arrayVals[0].stringValue ?? "";
+                                            if (sanitizationSession && value) {
+                                                const detected = detectWithPatterns(value);
+                                                for (const entity of detected) {
+                                                    const replacement = sanitizationSession.getOrCreateReplacement(entity.value, entity.type);
+                                                    value = value.split(entity.value).join(replacement);
+                                                }
+                                            }
+                                            inputs.push({ name: inputCol.name, string_value: value });
+                                        }
+                                    }
+                                    // Note: COLUMN_TYPE_NUMBER and COLUMN_TYPE_BOOLEAN are not currently
+                                    // parsed from the dashboard rows protobuf response, so they're skipped
+                                }
+                                // If we have inputs (even if some docs were skipped), try to clone
+                                if (inputs.length === 0) {
+                                    // Check if we had document-only inputs
+                                    if (rowSkippedDocs.length > 0) {
+                                        results.push({
+                                            source_row_id: row.id,
+                                            status: "skipped",
+                                            error: "Document-only inputs require manual re-upload",
+                                            skipped_documents: rowSkippedDocs,
+                                        });
+                                    }
+                                    else {
+                                        results.push({ source_row_id: row.id, status: "skipped", error: "No clonable input values" });
+                                    }
+                                    continue;
+                                }
+                                // Upload the row to target dashboard
+                                const uploadResult = await client.uploadAndRunDashboardRow(newPersonaId, inputs);
+                                const rowResult = {
+                                    source_row_id: row.id,
+                                    target_row_id: uploadResult.row_id,
+                                    status: rowSkippedDocs.length > 0 ? "partial" : "cloned",
+                                };
+                                if (rowSkippedDocs.length > 0) {
+                                    rowResult.skipped_documents = rowSkippedDocs;
+                                }
+                                results.push(rowResult);
+                            }
+                            catch (err) {
+                                results.push({ source_row_id: row.id, status: "error", error: err instanceof Error ? err.message : String(err) });
+                            }
+                        }
+                        const clonedCount = results.filter(r => r.status === "cloned" || r.status === "partial").length;
+                        dashboardCloneResult = {
+                            source_rows: sourceRows.rows.length,
+                            cloned_rows: clonedCount,
+                            partial_rows: results.filter(r => r.status === "partial").length,
+                            skipped_rows: results.filter(r => r.status === "skipped").length,
+                            error_rows: results.filter(r => r.status === "error").length,
+                            sanitization_applied: !!shouldSanitize,
+                            // Debug info for troubleshooting
+                            _debug: {
+                                total_count_from_api: sourceRows.totalCount,
+                                schema_columns_count: sourceRows.schema.columns.length,
+                                input_columns_count: inputColumns.length,
+                                schema_columns: sourceRows.schema.columns.map(c => ({
+                                    id: c.columnId,
+                                    name: c.name,
+                                    type: c.columnType,
+                                    isInput: c.isInput,
+                                })),
+                                first_row_id: sourceRows.rows[0]?.id?.substring(0, 100),
+                                first_row_state: sourceRows.rows[0]?.state,
+                                first_row_column_values_count: sourceRows.rows[0]?.columnValues?.length,
+                                results_detail: results,
+                            },
+                        };
+                        // Include document upload notice if any documents were skipped
+                        if (allSkippedDocuments.length > 0) {
+                            dashboardCloneResult.documents_require_manual_upload = {
+                                count: allSkippedDocuments.length,
+                                files: allSkippedDocuments.slice(0, 10), // Limit to first 10 for readability
+                                note: "Document inputs cannot be auto-cloned. Re-upload original files to the cloned dashboard.",
+                            };
+                        }
+                    }
+                    else {
+                        dashboardCloneResult = { source_rows: 0, cloned_rows: 0, message: "Source dashboard was empty" };
+                    }
+                }
+                catch (err) {
+                    dashboardCloneResult = { error: `Dashboard clone failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            // Handle workflow sanitization for ALL persona types (including dashboard)
+            // Dashboard rows are sanitized during clone loop above, but workflow still needs sanitization
+            const shouldSanitize = args.sanitize;
+            if (shouldSanitize && newPersonaId) {
+                const sanitizeResult = await sanitizePersonaById(client, newPersonaId, {
+                    examples: args.sanitize_examples,
+                    preview: args.preview ?? false, // Use preview arg, default to false (apply)
+                });
+                const createResult = {
+                    success: true,
+                    persona_id: newPersonaId,
+                    name,
+                    sanitization: sanitizeResult,
+                };
+                if (sourcePersonaType) {
+                    createResult.source_persona_type = sourcePersonaType;
+                }
+                if (dashboardCloneResult) {
+                    createResult.dashboard_data_clone = dashboardCloneResult;
+                }
+                return createResult;
+            }
+            const createResult = {
                 success: true,
-                persona_id: result.persona_id,
+                persona_id: newPersonaId,
                 name,
             };
+            if (sourcePersonaType) {
+                createResult.source_persona_type = sourcePersonaType;
+            }
+            if (dashboardCloneResult) {
+                createResult.dashboard_data_clone = dashboardCloneResult;
+            }
+            return createResult;
+        }
+        case "sanitize": {
+            // Standalone sanitize mode: sanitize an existing persona
+            if (!idOrName) {
+                return { error: "id required for sanitize mode" };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            const sanitizeResult = await sanitizePersonaById(client, persona.id, {
+                examples: args.sanitize_examples,
+                preview: args.preview,
+            });
+            return {
+                mode: "sanitize",
+                persona_id: persona.id,
+                persona_name: persona.name,
+                ...sanitizeResult,
+            };
         }
         case "update": {
             if (!idOrName) {
@@ -792,8 +1049,6 @@ export async function handleWorkflow(args, client, getTemplateId) {
             if (args.type) {
                 parseResult.intent.persona_type = args.type;
             }
-            // Check if intent requires LLM-driven generation
-            const genResult = generateWorkflow(parseResult.intent);
             // Load schema registry for API-driven validation (graceful degradation if unavailable)
             let schemaRegistry;
             try {
@@ -803,9 +1058,66 @@ export async function handleWorkflow(args, client, getTemplateId) {
                 // Schema registry unavailable - skip API validation
                 schemaRegistry = null;
             }
+            // ═══════════════════════════════════════════════════════════════════════════
+            // PROGRESSIVE ENHANCEMENT: Use Intent Architect for moderate/complex requests
+            // ═══════════════════════════════════════════════════════════════════════════
+            // 
+            // Uses the canonical runIntentArchitect() entrypoint which:
+            // - Detects complexity with typed scores (not enums)
+            // - Returns qualification questions or LLM prompt
+            // - Supports iterative refinement with previous_answers
+            //
+            // Configure rollout via max_complexity option (default: allow all levels)
+            const maxComplexity = args.max_complexity || undefined;
+            const inputStr = input; // Already validated above
+            const architectResult = runIntentArchitect(inputStr, {
+                persona_type: parseResult.intent.persona_type,
+                available_integrations: schemaRegistry?.getAllActions().slice(0, 20).map(a => a.displayName || a.name),
+            }, { max_complexity: maxComplexity });
+            // For moderate/complex: return Intent Architect result with questions or prompt
+            if (!architectResult.strategy.can_proceed) {
+                let availableActions = [];
+                let availableTemplates = [];
+                // Enhance prompt with action catalog if available
+                let enhancedPrompt = architectResult.prompt_package;
+                if (schemaRegistry && enhancedPrompt) {
+                    const actionCatalog = generateActionCatalogForLLM(schemaRegistry);
+                    enhancedPrompt = {
+                        system: enhancedPrompt.system + "\n\n## Available Actions\n" + actionCatalog,
+                        user: enhancedPrompt.user,
+                    };
+                    availableActions = schemaRegistry.getAllActions().map(a => a.name);
+                    availableTemplates = schemaRegistry.getAllTemplates().map(t => ({ id: t.id, name: t.name, type: t.type }));
+                }
+                return {
+                    status: "needs_intent_architect",
+                    // Typed assessment (new)
+                    assessment: architectResult.assessment,
+                    // Strategy decision (new)
+                    strategy: architectResult.strategy,
+                    // Qualification questions (new)
+                    questions: architectResult.questions,
+                    // LLM prompt (if full architect)
+                    llm_prompt: enhancedPrompt,
+                    // Hint for what to do next
+                    hint: architectResult.strategy.next_step,
+                    // Legacy fields for backward compatibility
+                    reason: architectResult.legacy?.signals.reason,
+                    complexity: architectResult.legacy?.complexity,
+                    approach: architectResult.strategy.approach,
+                    gates_to_ask: architectResult.strategy.gates_to_ask,
+                    // Also provide basic spec as fallback
+                    fallback_spec: intentToSpec(parseResult.intent),
+                    // Include catalogs for reference (if available)
+                    available_actions: availableActions,
+                    available_templates: availableTemplates,
+                };
+            }
+            // SIMPLE complexity: Check if intent requires LLM-driven generation (legacy path)
+            const genResult = generateWorkflow(parseResult.intent);
             if (genResult.needs_llm) {
-                // Complex workflow - return prompt for LLM to generate
-                // Enhanced with API-driven action catalog if available
+                // Complex workflow detected by legacy system - return prompt for LLM to generate
+                // This is a fallback for cases the new complexity analyzer might miss
                 let enhancedPrompt = genResult.llm_prompt;
                 let availableActions = [];
                 let availableTemplates = [];
@@ -1772,6 +2084,205 @@ export async function handleKnowledge(args, client, readFile) {
                 message: `Data source '${widgetName}' attached to node '${nodeName}'`,
             };
         }
+        case "dashboard_rows": {
+            // Get rows from a dashboard persona
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                return { error: `Persona not found: ${personaId}` };
+            }
+            const dashboardId = persona.workflow_dashboard_id;
+            if (!dashboardId) {
+                return {
+                    error: "This persona has no dashboard. Use dashboard_rows only for Dashboard-type AI Employees.",
+                    hint: "Check that the persona has trigger_type=DASHBOARD",
+                };
+            }
+            const limit = args.limit ?? 100;
+            const result = await client.getDashboardRows(dashboardId, personaId, { limit });
+            // Return schema and rows in a structured format
+            return {
+                persona_id: personaId,
+                dashboard_id: dashboardId,
+                dashboard_name: result.dashboardName,
+                total_rows: result.totalCount,
+                schema: {
+                    input_columns: result.schema.columns.filter(c => c.isInput),
+                    output_columns: result.schema.columns.filter(c => !c.isInput),
+                },
+                rows: result.rows.map(row => ({
+                    id: row.id,
+                    state: row.state,
+                    created_at: row.dashboardRowMetadata.createdAt,
+                    input_values: row.columnValues
+                        .filter(cv => result.schema.columns.find(c => c.columnId === cv.columnId)?.isInput)
+                        .map(cv => ({
+                        column: result.schema.columns.find(c => c.columnId === cv.columnId)?.name ?? cv.columnId,
+                        value: cv.value.stringValue ?? cv.value.documentCellValue?.documentValues?.[0]?.name ?? cv.value.arrayValue?.arrayValues?.[0]?.stringValue ?? "(complex)",
+                    })),
+                })),
+            };
+        }
+        case "dashboard_clone": {
+            const sourcePersonaId = args.source_persona_id;
+            if (!sourcePersonaId) {
+                return { error: "source_persona_id required for dashboard_clone" };
+            }
+            // Get source and target personas
+            const [sourcePersona, targetPersona] = await Promise.all([
+                client.getPersonaById(sourcePersonaId),
+                client.getPersonaById(personaId),
+            ]);
+            if (!sourcePersona) {
+                return { error: `Source persona not found: ${sourcePersonaId}` };
+            }
+            if (!targetPersona) {
+                return { error: `Target persona not found: ${personaId}` };
+            }
+            const sourceDashboardId = sourcePersona.workflow_dashboard_id;
+            if (!sourceDashboardId) {
+                return { error: "Source persona has no dashboard" };
+            }
+            // Dashboard operations require the persona to be enabled
+            // Auto-enable the target persona for cloning
+            const targetProtoConfig = targetPersona.proto_config;
+            await client.updateAiEmployee({
+                persona_id: personaId,
+                proto_config: targetProtoConfig ?? {},
+                enabled_by_user: true,
+            });
+            // Get source dashboard data
+            const sourceRows = await client.getDashboardRows(sourceDashboardId, sourcePersonaId);
+            if (sourceRows.rows.length === 0) {
+                return {
+                    success: true,
+                    message: "No rows to clone - source dashboard is empty",
+                    source_rows: 0,
+                    cloned_rows: 0,
+                };
+            }
+            // Identify input columns
+            const inputColumns = sourceRows.schema.columns.filter(c => c.isInput);
+            // Clone each row
+            const results = [];
+            const sanitize = args.sanitize;
+            const sanitizeExamples = args.sanitize_examples;
+            // Create sanitization session if needed
+            let sanitizationSession;
+            if (sanitize) {
+                sanitizationSession = new SanitizationSession();
+            }
+            for (const row of sourceRows.rows) {
+                try {
+                    // Build inputs from row's input column values
+                    const inputs = [];
+                    for (const inputCol of inputColumns) {
+                        const colValue = row.columnValues.find(cv => cv.columnId === inputCol.columnId);
+                        if (!colValue)
+                            continue;
+                        // Handle different column types
+                        if (inputCol.columnType === "COLUMN_TYPE_DOCUMENT") {
+                            // Document columns - we need to fetch the actual file content
+                            const docs = colValue.value.documentCellValue?.documentValues ?? [];
+                            if (docs.length > 0) {
+                                // For documents, we'd need to download from source and re-upload
+                                // For now, add as placeholder - requires file content fetching
+                                results.push({
+                                    source_row_id: row.id,
+                                    status: "skipped",
+                                    error: "Document cloning requires file content transfer (not yet implemented)",
+                                });
+                                continue;
+                            }
+                        }
+                        else if (inputCol.columnType === "COLUMN_TYPE_STRING") {
+                            let value = colValue.value.stringValue ?? "";
+                            // Sanitize if enabled
+                            if (sanitizationSession && value) {
+                                // Simple pattern-based sanitization for known types
+                                const detected = detectWithPatterns(value);
+                                for (const entity of detected) {
+                                    const replacement = sanitizationSession.getOrCreateReplacement(entity.value, entity.type);
+                                    value = value.split(entity.value).join(replacement);
+                                }
+                                // Also apply any user-provided examples
+                                if (sanitizeExamples) {
+                                    for (const example of sanitizeExamples) {
+                                        if (value.includes(example)) {
+                                            const replacement = sanitizationSession.getOrCreateReplacement(example, "unknown");
+                                            value = value.split(example).join(replacement);
+                                        }
+                                    }
+                                }
+                            }
+                            inputs.push({
+                                name: inputCol.name,
+                                string_value: value,
+                            });
+                        }
+                        else if (inputCol.columnType === "COLUMN_TYPE_ARRAY") {
+                            // Array values - take first value as string for simplicity
+                            const arrayVals = colValue.value.arrayValue?.arrayValues ?? [];
+                            if (arrayVals.length > 0) {
+                                let value = arrayVals[0].stringValue ?? "";
+                                if (sanitizationSession && value) {
+                                    const detected = detectWithPatterns(value);
+                                    for (const entity of detected) {
+                                        const replacement = sanitizationSession.getOrCreateReplacement(entity.value, entity.type);
+                                        value = value.split(entity.value).join(replacement);
+                                    }
+                                }
+                                inputs.push({
+                                    name: inputCol.name,
+                                    string_value: value,
+                                });
+                            }
+                        }
+                    }
+                    if (inputs.length === 0) {
+                        results.push({
+                            source_row_id: row.id,
+                            status: "skipped",
+                            error: "No clonable input values found",
+                        });
+                        continue;
+                    }
+                    // Upload the row to target dashboard
+                    const uploadResult = await client.uploadAndRunDashboardRow(personaId, inputs);
+                    results.push({
+                        source_row_id: row.id,
+                        target_row_id: uploadResult.row_id,
+                        status: "cloned",
+                    });
+                }
+                catch (err) {
+                    results.push({
+                        source_row_id: row.id,
+                        status: "error",
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            const clonedCount = results.filter(r => r.status === "cloned").length;
+            const skippedCount = results.filter(r => r.status === "skipped").length;
+            const errorCount = results.filter(r => r.status === "error").length;
+            return {
+                success: true,
+                source_persona_id: sourcePersonaId,
+                target_persona_id: personaId,
+                source_rows: sourceRows.rows.length,
+                cloned_rows: clonedCount,
+                skipped_rows: skippedCount,
+                error_rows: errorCount,
+                sanitization_applied: !!sanitize,
+                details: results,
+                notes: [
+                    "Dashboard clone creates NEW rows in the target dashboard",
+                    "Workflows will re-run on the new rows to generate output columns",
+                    "Document columns require manual re-upload (file content transfer not implemented)",
+                    sanitize ? "Sanitization applied to string/array values" : null,
+                ].filter(Boolean),
+            };
+        }
         default:
             return { error: `Unknown mode: ${mode}` };
     }
@@ -2733,6 +3244,94 @@ function sanitizeWorkflowForDeploy(workflow) {
 // ═══════════════════════════════════════════════════════════════════════════
 // Helper Functions
 // ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Sanitize a persona's content (PII, company names, etc.)
+ *
+ * Uses two-pass approach:
+ * 1. Detection pass: Find sensitive entities in all text fields
+ * 2. Alignment pass: Apply ALL mappings for cross-field consistency
+ *
+ * Supports typed examples: strings (type inferred) or objects with explicit type.
+ */
+async function sanitizePersonaById(client, personaId, options = {}) {
+    try {
+        // Fetch full persona
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            return { success: false, preview: true, replacements_applied: 0, items_needing_review: 0, error: "Persona not found" };
+        }
+        // Build persona object for sanitization - include ALL text-containing fields
+        const personaData = {
+            name: persona.name,
+            description: persona.description,
+            proto_config: persona.proto_config,
+            workflow_def: persona.workflow_def,
+        };
+        // Create sanitization session with default policy
+        const session = new SanitizationSession();
+        // Normalize examples to TypedExample format
+        const typedExamples = options.examples?.map(ex => {
+            if (typeof ex === "string")
+                return ex;
+            return {
+                value: ex.value,
+                type: ex.type,
+                replacement: ex.replacement,
+            };
+        });
+        // Run sanitization with two-pass approach
+        const sanitizationOptions = {
+            examples: typedExamples,
+            auto_replace_threshold: "high", // Only auto-replace high confidence
+        };
+        const result = sanitizePersona(personaData, session, sanitizationOptions);
+        // If preview mode or there are items needing review, return preview
+        const isPreview = options.preview !== false;
+        if (isPreview || result.summary.items_needing_review > 0) {
+            // Build confirmation prompt with all replacements and items needing review
+            const allReplacements = result.results.flatMap(r => r.result.replacements);
+            const allNeedsReview = result.results.flatMap(r => r.result.needs_review);
+            const confirmation = buildConfirmationPrompt(allReplacements, allNeedsReview);
+            return {
+                success: true,
+                preview: true,
+                replacements_applied: 0,
+                items_needing_review: allNeedsReview.length,
+                by_class: result.summary.by_class,
+                by_type: result.summary.by_type,
+                confirmation,
+            };
+        }
+        // Apply sanitization by updating the persona
+        const sanitizedProtoConfig = result.sanitized.proto_config;
+        const sanitizedWorkflow = result.sanitized.workflow_def;
+        const sanitizedDescription = result.sanitized.description;
+        // Update the persona with sanitized data
+        await client.updateAiEmployee({
+            persona_id: personaId,
+            description: sanitizedDescription ?? persona.description,
+            proto_config: (sanitizedProtoConfig ?? persona.proto_config ?? {}),
+            workflow: sanitizedWorkflow ?? persona.workflow_def,
+        });
+        return {
+            success: true,
+            preview: false,
+            by_class: result.summary.by_class,
+            by_type: result.summary.by_type,
+            replacements_applied: result.summary.total_replacements,
+            items_needing_review: result.summary.items_needing_review,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            preview: true,
+            replacements_applied: 0,
+            items_needing_review: 0,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 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;