@ema.co/mcp-toolkit 2026.1.27 → 2026.1.28-2

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

@@ -162,6 +162,9 @@ export async function handleData(args, client, readFile) {
                         path: filePath,
                         widget_name: widgetName ?? "fileUpload",
                         ...result,
+                        _warning: "IMPORTANT: Uploaded documents will NOT be used unless your workflow has a search node (search/v2).",
+                        _next_step: `Verify workflow has search: workflow(mode='get', persona_id='${personaId}') → check for search node. If missing, add one.`,
+                        _validation: "Deploy will BLOCK if you have documents but no search node in your workflow.",
                     };
                 }
                 catch (error) {

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

@@ -221,6 +221,7 @@ export async function handleCreate(args, client, getTemplateId) {
                 sourcePersonaType,
                 dashboardCloneResult,
                 actionsError: validation.errors.join("; "),
+                createdFromTemplate: fromType === "template",
             });
         }
         // Build execution context
@@ -243,6 +244,7 @@ export async function handleCreate(args, client, getTemplateId) {
             sourcePersonaType,
             // Don't include dashboardCloneResult - actions handle data operations
             actionsResult,
+            createdFromTemplate: fromType === "template",
         });
     }
     // ═══════════════════════════════════════════════════════════════════════════
@@ -264,6 +266,7 @@ export async function handleCreate(args, client, getTemplateId) {
             workflowError,
             sourcePersonaType,
             dashboardCloneResult,
+            createdFromTemplate: fromType === "template",
         });
     }
     return buildCreateResult({
@@ -274,6 +277,7 @@ export async function handleCreate(args, client, getTemplateId) {
         workflowError,
         sourcePersonaType,
         dashboardCloneResult,
+        createdFromTemplate: fromType === "template",
     });
 }
 /**
@@ -299,6 +303,18 @@ function buildCreateResult(opts) {
     if (opts.sourcePersonaType) {
         result.source_persona_type = opts.sourcePersonaType;
     }
+    // ── CRITICAL GUIDANCE: Template workflows are minimal starters ──
+    // This is where LLMs often go wrong - they create from template and think they're done
+    if (opts.createdFromTemplate && !opts.workflowApplied) {
+        result._warning = "PERSONA CREATED BUT WORKFLOW IS INCOMPLETE. Template workflows are minimal starters (just trigger→respond).";
+        result._required_next_steps = [
+            "1. BUILD WORKFLOW: Add intent categorization, search nodes, response handling",
+            `2. If uploading docs: Workflow MUST have search/v2 node or documents will NOT be used`,
+            `3. Get current workflow: workflow(mode='get', persona_id='${opts.newPersonaId}')`,
+            `4. Deploy complete workflow: workflow(mode='deploy', persona_id='${opts.newPersonaId}', workflow_def={...})`,
+        ];
+        result._common_mistake = "Creating from template, uploading docs, and declaring 'done' WITHOUT building the workflow. The deploy will now BLOCK this pattern.";
+    }
     if (opts.dashboardCloneResult) {
         result.dashboard_data_clone = opts.dashboardCloneResult;
     }

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

@@ -2,6 +2,7 @@
  * Persona LIST mode handler
  *
  * Lists all personas with optional filtering.
+ * Fetches all pages from the API (no artificial limit).
  */
 import { getTemplates, normalizeTriggerType } from "../utils.js";
 /**
@@ -10,10 +11,12 @@ import { getTemplates, normalizeTriggerType } from "../utils.js";
  * @param args.query - Filter by name (partial match)
  * @param args.status - Filter by status
  * @param args.trigger_type - Filter by trigger type
- * @param args.limit - Max results (default 50)
+ * @param args.limit - Max results (optional, no default limit)
  */
 export async function handleList(args, client) {
+    // Fetch all personas (client handles pagination)
     let personas = await client.getPersonasForTenant();
+    const totalBeforeFilter = personas.length;
     // Apply filters
     if (args.query) {
         const q = args.query.toLowerCase();
@@ -25,14 +28,16 @@ export async function handleList(args, client) {
     if (args.trigger_type) {
         personas = personas.filter(p => p.trigger_type === args.trigger_type);
     }
-    // Apply limit
-    const limit = args.limit || 50;
-    personas = personas.slice(0, limit);
+    // Apply limit only if explicitly provided
+    if (args.limit && typeof args.limit === 'number') {
+        personas = personas.slice(0, args.limit);
+    }
     // Get templates for type lookup (cached)
     const templates = await getTemplates(client);
     const templateMap = new Map(templates.map(t => [t.id, t]));
     return {
         count: personas.length,
+        total: totalBeforeFilter,
         personas: personas.map(p => {
             // Get type from template (dynamic, tenant-specific)
             const template = templateMap.get(p.template_id ?? "");

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

@@ -12,7 +12,9 @@
  * routes to handleWorkflow BEFORE reaching this handler. See handlePersona()
  * in handlers-consolidated.ts.
  */
+import { PROJECT_TYPES } from "../../../sdk/knowledge.js";
 import { resolvePersona, validateWidgetsForApi } from "../utils.js";
+import { validateSearchDataSourceConsistency, validationToHandlerResult } from "../workflow/validation.js";
 /**
  * Apply WorkflowSpec changes to an existing workflow_def.
  * This preserves action-specific inputs that compileWorkflow would lose.
@@ -200,7 +202,7 @@ export async function handleUpdate(args, client) {
         : undefined;
     // Determine persona type from projectSettings.projectType
     const projectSettings = existingProtoConfig.projectSettings;
-    const isVoice = projectSettings?.projectType === 5;
+    const isVoice = projectSettings?.projectType === PROJECT_TYPES.voice;
     // Build merged proto_config with smart widget-level merging
     // Accept both 'config' (tool schema) and 'proto_config' (internal) for compatibility
     let mergedProtoConfig = { ...existingProtoConfig };
@@ -310,6 +312,19 @@ export async function handleUpdate(args, client) {
         // Use raw workflow_def if provided, otherwise keep existing
         workflowToSet = args.workflow ?? existingWorkflow;
     }
+    // ── VALIDATION: Use shared validation rules ──
+    // Run for any workflow update (workflow_spec or raw workflow)
+    if (workflowToSet) {
+        const validation = await validateSearchDataSourceConsistency(workflowToSet, persona.id, client);
+        if (!validation.valid) {
+            return validationToHandlerResult(validation, {
+                preview: preview,
+                persona_id: persona.id,
+                persona_name: persona.name,
+                changes: transformResult.changes || [],
+            });
+        }
+    }
     // ── Preview mode - return without deploying ──
     if (preview && workflowSpec) {
         return {
@@ -317,6 +332,7 @@ export async function handleUpdate(args, client) {
             persona_id: persona.id,
             persona_name: persona.name,
             persona_type: isVoice ? "voice" : "chat/dashboard",
+            validation_passed: true,
             changes: transformResult.changes || [],
             modified_workflow: workflowToSet,
             hint: "Set preview=false to deploy these changes",
@@ -333,7 +349,13 @@ export async function handleUpdate(args, client) {
         });
     }
     catch (apiErr) {
-        throw apiErr;
+        // Return structured error consistent with other handlers
+        const errorMessage = apiErr instanceof Error ? apiErr.message : String(apiErr);
+        return {
+            error: `Update failed: ${errorMessage}`,
+            persona_id: persona.id,
+            persona_name: persona.name,
+        };
     }
     return {
         success: true,

package/dist/mcp/handlers/workflow/deploy.js

@@ -3,9 +3,18 @@
  *
  * Deploys a workflow_def to an existing persona.
  * Includes deprecation warnings (does not block, just warns).
+ *
+ * BLOCKING VALIDATION:
+ * - Uses shared validation from validation.ts
  */
+import { PROJECT_TYPES } from "../../../sdk/knowledge.js";
 import { sanitizeWorkflowForDeploy } from "./utils.js";
 import { DEPRECATED_ACTIONS_FALLBACK, checkWorkflowDeprecations } from "./index.js";
+import { validateSearchDataSourceConsistency, validationToHandlerResult, 
+// Re-export for backwards compatibility
+hasKnowledgeSearchNodes, extractActionTypeName, } from "./validation.js";
+// Re-export for backwards compatibility with existing imports
+export { hasKnowledgeSearchNodes, extractActionTypeName };
 /**
  * Handle workflow deploy mode
  */
@@ -23,8 +32,17 @@ export async function handleWorkflowDeploy(args, client) {
     if (!persona) {
         return { error: `Persona not found: ${personaId}` };
     }
-    // Sanitize workflow before deployment
+    // Sanitize workflow FIRST so we validate what we'll actually deploy
     const sanitizedWorkflow = sanitizeWorkflowForDeploy(workflowDef);
+    // ── BLOCKING VALIDATION: Use shared validation rules ──
+    const validation = await validateSearchDataSourceConsistency(sanitizedWorkflow, personaId, client);
+    if (!validation.valid) {
+        return validationToHandlerResult(validation, {
+            mode: "deploy",
+            persona_id: personaId,
+            persona_name: persona.name,
+        });
+    }
     // Check for deprecated actions (warn, don't block)
     const deprecationWarnings = checkWorkflowDeprecations(workflowDef, DEPRECATED_ACTIONS_FALLBACK);
     // Determine proto_config to use: provided > existing
@@ -33,7 +51,7 @@ export async function handleWorkflowDeploy(args, client) {
     const protoConfigToUse = providedProtoConfig || existingProtoConfig || {};
     // Check if this is a voice persona and warn if critical settings are missing
     const projectSettings = protoConfigToUse.projectSettings;
-    const isVoice = projectSettings?.projectType === 5;
+    const isVoice = projectSettings?.projectType === PROJECT_TYPES.voice;
     const warnings = [];
     // Add deprecation warning message if deprecated actions found
     if (deprecationWarnings.length > 0) {

package/dist/mcp/handlers/workflow/generate.js

@@ -15,6 +15,7 @@ import { runIntentArchitect } from "../../../sdk/intent-architect.js";
 import { ensureActionRegistry } from "../../../sdk/action-registry.js";
 import { ensureSchemaRegistry, validateWorkflowSpec, generateActionCatalogForLLM } from "../../../sdk/workflow-validator.js";
 import { getTemplates, normalizeTriggerType } from "../../handlers/index.js";
+import { validateSearchDataSourceConsistency, validationToHandlerResult } from "./validation.js";
 /**
  * Get persona widget context for workflow bindings
  */
@@ -141,7 +142,20 @@ async function deployToNewPersona(args, client, compiled, actionRegistry, getTem
         ...existingProtoConfig,
         widgets: Array.from(widgetMap.values()),
     };
-    // Step 4: Deploy workflow
+    // Step 4: Validate and Deploy workflow
+    // Validate search/data source consistency before deployment
+    const validation = await validateSearchDataSourceConsistency(compiled.workflow_def, newPersonaId, client);
+    if (!validation.valid) {
+        // Return validation error but keep persona (user can fix and retry)
+        return {
+            success: false,
+            personaId: newPersonaId,
+            personaName,
+            validationError: validation.error,
+            _fix: validation._fix,
+            workflowAttempted: compiled.workflow_def,
+        };
+    }
     // NOTE: The SDK's updateAiEmployee() handles workflowName namespace automatically.
     // It will copy from existing workflow if present, or generate a valid namespace if not.
     // It also fixes the results format. No need to manually manipulate these here.
@@ -293,6 +307,16 @@ export async function handleWorkflowGenerate(args, client, getTemplateId) {
         if (!persona) {
             return { error: `Persona not found: ${personaId}` };
         }
+        // Validate search/data source consistency before deployment
+        const validation = await validateSearchDataSourceConsistency(compiled.workflow_def, personaId, client);
+        if (!validation.valid) {
+            return validationToHandlerResult(validation, {
+                mode: "generate",
+                persona_id: personaId,
+                persona_name: persona.name,
+                workflow_preview: compiled.workflow_def,
+            });
+        }
         await client.updateAiEmployee({
             persona_id: personaId,
             workflow: compiled.workflow_def,
@@ -303,7 +327,20 @@ export async function handleWorkflowGenerate(args, client, getTemplateId) {
     else if (!preview && !personaId) {
         // Greenfield: create new persona
         const deployResult = await deployToNewPersona(args, client, compiled, actionRegistry, getTemplateId);
-        if (deployResult.workflowDeployError) {
+        if (deployResult.validationError) {
+            // Validation failed - persona created but workflow not deployed
+            return {
+                error: deployResult.validationError,
+                _fix: deployResult._fix,
+                persona_id: deployResult.personaId,
+                persona_name: deployResult.personaName,
+                persona_created: true,
+                workflow_deployed: false,
+                workflow_attempted: deployResult.workflowAttempted,
+                hint: "Persona created, but workflow validation failed. Fix the issue and retry deployment.",
+            };
+        }
+        else if (deployResult.workflowDeployError) {
             result.workflow_deploy_error = deployResult.workflowDeployError;
             result.workflow_attempted = deployResult.workflowAttempted;
             result.status = "partial";

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

@@ -26,6 +26,7 @@ import { handleWorkflowOptimize } from "./optimize.js";
 import { handleWorkflowDeploy } from "./deploy.js";
 import { handleWorkflowGenerate } from "./generate.js";
 import { handleWorkflowModify } from "./modify.js";
+import { handleWorkflowValidate } from "./validate.js";
 // Re-export for internal use (persona handler routes to these)
 export { handleWorkflowAnalyze } from "./analyze.js";
 export { handleWorkflowCompare } from "./compare.js";
@@ -240,6 +241,9 @@ export async function handleWorkflow(args, client, getTemplateId) {
     if (mode === "deploy") {
         return handleWorkflowDeploy(args, client);
     }
+    if (mode === "validate") {
+        return handleWorkflowValidate(args, client);
+    }
     // INTERNAL MODES (called from persona tool, not workflow tool)
     if (mode === "modify" || mode === "extend") {
         return handleWorkflowModify(args, client);
@@ -278,15 +282,15 @@ export async function handleWorkflow(args, client, getTemplateId) {
     // Invalid mode
     return {
         error: `Invalid or missing mode: ${mode}`,
-        public_modes: ["get", "deploy"],
-        hint: "MCP provides data (get) and executes (deploy). LLM does all thinking.",
+        public_modes: ["get", "deploy", "validate"],
+        hint: "MCP provides data (get), validates (validate), and executes (deploy). LLM does all thinking.",
     };
 }
 /**
  * Check if a workflow mode has been extracted
  */
 export function hasExtractedWorkflowHandler(mode) {
-    const extractedModes = ["get", "deploy", "modify", "extend", "generate", "analyze", "optimize", "compare"];
+    const extractedModes = ["get", "deploy", "validate", "modify", "extend", "generate", "analyze", "optimize", "compare"];
     return extractedModes.includes(mode);
 }
 /**
@@ -296,6 +300,7 @@ export function getWorkflowModeHandler(mode) {
     switch (mode) {
         case "get":
         case "deploy":
+        case "validate":
         case "modify":
         case "extend":
         case "generate":

package/dist/mcp/handlers/workflow/modify.js

@@ -10,6 +10,7 @@
  */
 import { sanitizeWorkflowForDeploy } from "./utils.js";
 import { ensureSchemaRegistry } from "../../../sdk/workflow-validator.js";
+import { validateSearchDataSourceConsistency, validationToHandlerResult } from "./validation.js";
 // ─────────────────────────────────────────────────────────────────────────
 // Action Building Helpers (use ActionRegistry for metadata)
 // ─────────────────────────────────────────────────────────────────────────
@@ -311,6 +312,8 @@ export async function handleWorkflowModify(args, client) {
     const operations = args.operations;
     const preview = Boolean(args.preview);
     // If no structured operations provided, return guidance
+    // NOTE: This handler does NOT parse natural language - Agent must build operations
+    const userInput = args.input;
     if (!operations || operations.length === 0) {
         // Fetch persona for context
         const persona = await client.getPersonaById(personaId);
@@ -328,9 +331,16 @@ export async function handleWorkflowModify(args, client) {
             ? schemaRegistry.getAllActions().map(a => ({ name: a.name, category: a.category, description: a.description }))
             : [];
         return {
-            message: "No operations provided. Returning workflow context for Agent to build operations.",
+            message: userInput
+                ? `You provided input="${userInput}". This handler requires STRUCTURED operations, not natural language. Build operations from the context below.`
+                : "No operations provided. Returning workflow context for Agent to build operations.",
             persona_id: personaId,
             persona_name: persona.name,
+            // If user provided input, remind them to convert to operations
+            ...(userInput && {
+                _warning: "IMPORTANT: The 'input' parameter is for providing context to the Agent, not for direct execution. The Agent must convert this into structured 'operations'.",
+                user_intent: userInput,
+            }),
             // Current workflow state (DATA for Agent)
             current_nodes: actions.map(a => ({
                 name: a.name,
@@ -341,10 +351,11 @@ export async function handleWorkflowModify(args, client) {
             available_actions: availableActions.slice(0, 20), // Top 20 for context
             // Guidance for Agent
             _next_steps: [
-                "1. Review current_nodes and available_actions above",
-                "2. Fetch ema://rules/anti-patterns to check for issues",
-                "3. Build ModificationOperation[] based on your analysis",
-                "4. Pass operations as 'operations' parameter",
+                userInput
+                    ? `1. Interpret the user intent: "${userInput}"`
+                    : "1. Review current_nodes and available_actions above",
+                "2. Build ModificationOperation[] based on your analysis",
+                "3. Call again with operations=[{type:'insert'|'remove'|'rewire', ...}]",
             ],
             // Example operation structures
             example_operations: {
@@ -387,13 +398,25 @@ export async function handleWorkflowModify(args, client) {
     const schemaRegistry = await ensureSchemaRegistry(client);
     // Apply the structured operations
     const result = applyWorkflowModifications(workflow, operations, schemaRegistry);
-    // Sanitize before deploy
+    // Sanitize before validation (validate what we'll actually deploy)
     const sanitized = sanitizeWorkflowForDeploy(result.workflow);
+    // ── VALIDATION: Use shared validation rules ──
+    // Run BEFORE preview so user knows about issues early
+    const validation = await validateSearchDataSourceConsistency(sanitized, personaId, client);
+    if (!validation.valid) {
+        return validationToHandlerResult(validation, {
+            preview: preview,
+            persona_id: personaId,
+            persona_name: persona.name,
+            changes_attempted: result.changesApplied,
+        });
+    }
     if (preview) {
         return {
             preview: true,
             persona_id: personaId,
             persona_name: persona.name,
+            validation_passed: true, // Explicitly confirm validation passed
             // What would change
             changes_applied: result.changesApplied,
             nodes_added: result.nodesAdded,
@@ -402,14 +425,18 @@ export async function handleWorkflowModify(args, client) {
             connections_changed: result.connectionsChanged,
             // The modified workflow (LLM should analyze with ema://rules/*)
             modified_workflow: sanitized,
-            _tip: "Preview complete. Use ema://rules/anti-patterns to check for issues. Call without preview=true to deploy.",
+            _tip: "Preview complete. Validation passed. Call without preview=true to deploy.",
         };
     }
     // Deploy the workflow
+    // CRITICAL: Must include proto_config alongside workflow for changes to persist
+    // Always use the FULL existing proto_config from the persona
+    const existingProtoConfig = (persona.proto_config ?? {});
     try {
         await client.updateAiEmployee({
             persona_id: personaId,
             workflow: sanitized,
+            proto_config: existingProtoConfig,
         });
         return {
             success: true,

package/dist/mcp/handlers/workflow/validate.js

@@ -0,0 +1,85 @@
+/**
+ * Workflow Validation Handler
+ *
+ * Implements static validation using path enumeration.
+ * Validates: required outputs, multiple writers, response/abstain, category hierarchy.
+ */
+import { validateWorkflowStatic } from "../../../sdk/workflow-static-validator.js";
+/**
+ * Handle workflow(mode="validate") - static validation
+ *
+ * Validates workflow using path enumeration:
+ * - Enumerates all execution paths
+ * - Checks each path for named results compliance
+ * - Returns enhanced error messages (what, why, how)
+ */
+export async function handleWorkflowValidate(args, client) {
+    const personaId = args.persona_id;
+    const workflowDef = args.workflow_def;
+    const workflowSpec = args.workflow_spec;
+    const validationType = args.validation_type || "all";
+    // Get workflow to validate
+    let spec = null;
+    if (workflowSpec) {
+        // Use provided workflow spec
+        spec = workflowSpec;
+    }
+    else if (workflowDef) {
+        // Convert workflow_def to WorkflowSpec
+        // TODO: Implement conversion
+        return {
+            error: "workflow_def validation not yet implemented. Use workflow_spec instead.",
+        };
+    }
+    else if (personaId) {
+        // Get workflow from persona
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            return { error: `Persona not found: ${personaId}` };
+        }
+        const personaWorkflowDef = persona.workflow_def;
+        if (!personaWorkflowDef) {
+            return {
+                error: "Persona has no workflow to validate",
+                _tip: "Deploy a workflow first, then validate it",
+            };
+        }
+        // TODO: Convert workflow_def to WorkflowSpec
+        return {
+            error: "workflow_def validation not yet implemented. Use workflow_spec instead.",
+            _tip: "Convert workflow_def to WorkflowSpec format for validation",
+        };
+    }
+    else {
+        return {
+            error: "Either persona_id, workflow_def, or workflow_spec required",
+        };
+    }
+    if (!spec) {
+        return { error: "Could not extract workflow spec for validation" };
+    }
+    // Perform static validation
+    const validationResult = validateWorkflowStatic(spec, {
+        max_paths: args.max_paths || 1000,
+        timeout_ms: args.timeout_ms || 100,
+    });
+    // Format response
+    return {
+        valid: validationResult.valid,
+        errors: validationResult.errors,
+        warnings: validationResult.warnings,
+        info: validationResult.info,
+        summary: validationResult.summary,
+        _tip: validationResult.valid
+            ? "Workflow passed static validation. Ready to deploy."
+            : "Fix errors before deploying. Use error messages (what/why/how) to guide fixes.",
+        _next_step: validationResult.valid
+            ? "Deploy with: workflow(mode='deploy', persona_id='...', workflow_def={...})"
+            : [
+                "Review errors above",
+                "Fix issues using 'how_to_fix' guidance",
+                "Re-validate: workflow(mode='validate', ...)",
+                "Deploy when valid: workflow(mode='deploy', ...)",
+            ],
+    };
+}

package/dist/mcp/handlers/workflow/validation.js

@@ -0,0 +1,160 @@
+/**
+ * Workflow Validation Rules
+ *
+ * Shared validation logic for all workflow deployment paths.
+ * Called by: deploy.ts, modify.ts, update.ts (persona)
+ */
+/**
+ * Extract action type name from various workflow_def formats.
+ * Handles both string and object formats:
+ * - String: "search/v2"
+ * - Object: { name: { name: "search", namespaces: [...] }, version: "v2" }
+ */
+export function extractActionTypeName(action) {
+    if (typeof action === "string") {
+        return action;
+    }
+    if (typeof action === "object" && action !== null) {
+        const actionObj = action;
+        // Format: { name: { name: "search", namespaces: [...] } }
+        if (actionObj.name && typeof actionObj.name === "object") {
+            const nameObj = actionObj.name;
+            if (typeof nameObj.name === "string") {
+                return nameObj.name;
+            }
+        }
+        // Format: { name: "search" } (direct)
+        if (typeof actionObj.name === "string") {
+            return actionObj.name;
+        }
+    }
+    return "";
+}
+/**
+ * Detect knowledge search nodes in a workflow.
+ * Returns true if workflow contains search/v2 or search_datastore nodes (NOT web_search).
+ */
+export function hasKnowledgeSearchNodes(workflowDef) {
+    const actions = (workflowDef.actions ?? []);
+    return actions.some(a => {
+        // Extract action type from various formats
+        const actionTypeName = extractActionTypeName(a.action) || a.actionType || "";
+        const nodeName = (typeof a.name === "string" ? a.name : "").toLowerCase();
+        // Match: search, search/v2, search_datastore
+        // Exclude: web_search, live_web_search
+        const isSearchNode = actionTypeName.includes("search") ||
+            nodeName.includes("search");
+        const isWebSearch = actionTypeName.includes("web_search") ||
+            nodeName.includes("web_search");
+        return isSearchNode && !isWebSearch;
+    });
+}
+/**
+ * Validate workflow and data source consistency.
+ *
+ * Rules:
+ * 1. If workflow has search nodes → data sources MUST be indexed
+ * 2. If persona has indexed data sources → workflow MUST have search nodes
+ *
+ * @param workflowDef - The workflow to validate
+ * @param personaId - The persona ID for data source lookup
+ * @param client - EmaClient for API calls
+ * @returns Validation result with error details if invalid
+ */
+export async function validateSearchDataSourceConsistency(workflowDef, personaId, client) {
+    const hasSearchNodes = hasKnowledgeSearchNodes(workflowDef);
+    // Try to get data source stats
+    let dataSourceStats = null;
+    try {
+        dataSourceStats = await client.getDataSourceAggregates(personaId);
+    }
+    catch {
+        // If we can't check stats, log warning but don't block
+        console.error(`[validation] Could not verify data sources for ${personaId}`);
+    }
+    // If we couldn't get stats, allow through (don't block on API errors)
+    if (!dataSourceStats) {
+        return { valid: true };
+    }
+    // RULE 1: If workflow has search nodes, data sources MUST be indexed
+    if (hasSearchNodes) {
+        if (dataSourceStats.total === 0) {
+            return {
+                valid: false,
+                error: "DEPLOYMENT BLOCKED: Workflow contains knowledge search nodes but persona has no data sources attached.",
+                validation_failed: "search_nodes_require_data_sources",
+                current_state: {
+                    search_nodes_detected: true,
+                    data_sources_total: 0,
+                    data_sources_indexed: 0,
+                },
+                _fix: [
+                    "1. Upload documents: persona(id='...',data={method:'upload',path:'/path/to/doc.pdf'})",
+                    "2. Check status: persona(id='...',data={method:'stats'}) → wait for 'success' > 0",
+                    "3. Then retry the deployment",
+                ],
+            };
+        }
+        if (dataSourceStats.success === 0) {
+            return {
+                valid: false,
+                error: "DEPLOYMENT BLOCKED: Workflow contains knowledge search nodes but no data sources have been successfully indexed.",
+                validation_failed: "search_nodes_require_indexed_data",
+                current_state: {
+                    search_nodes_detected: true,
+                    data_sources_total: dataSourceStats.total,
+                    data_sources_pending: dataSourceStats.pending,
+                    data_sources_indexed: dataSourceStats.success,
+                    data_sources_failed: dataSourceStats.failed,
+                },
+                _fix: dataSourceStats.pending > 0
+                    ? [
+                        "Data sources are still indexing. Wait for indexing to complete:",
+                        "1. Check status: persona(id='...',data={method:'stats'})",
+                        "2. Retry when 'success' > 0",
+                    ]
+                    : [
+                        "All data sources failed indexing. Check file formats and re-upload:",
+                        "1. List files: persona(id='...',data={method:'list'})",
+                        "2. Delete failed: persona(id='...',data={method:'delete',file_id:'...'})",
+                        "3. Re-upload: persona(id='...',data={method:'upload',path:'...'})",
+                    ],
+            };
+        }
+    }
+    // RULE 2: If persona has indexed data sources, workflow MUST have search nodes
+    if (!hasSearchNodes && dataSourceStats.success > 0) {
+        return {
+            valid: false,
+            error: "DEPLOYMENT BLOCKED: Persona has indexed knowledge files but workflow has no search nodes. The uploaded documents will NEVER be used.",
+            validation_failed: "data_sources_require_search_nodes",
+            current_state: {
+                search_nodes_detected: false,
+                data_sources_total: dataSourceStats.total,
+                data_sources_indexed: dataSourceStats.success,
+            },
+            _fix: [
+                "Your workflow needs a search node to query the uploaded documents.",
+                "1. Get workflow schema: workflow(mode='get', persona_id='...')",
+                "2. Add search node: Update workflow_def to include a search/v2 node",
+                "3. Example pattern: trigger → summarizer → search/v2 → respond → output",
+            ],
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Convert validation result to HandlerResult format for returning errors.
+ */
+export function validationToHandlerResult(validation, additionalContext) {
+    if (validation.valid) {
+        throw new Error("validationToHandlerResult called on valid result");
+    }
+    return {
+        error: validation.error,
+        validation_failed: validation.validation_failed,
+        current_state: validation.current_state,
+        _fix: validation._fix,
+        ...additionalContext,
+    };
+}