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

package/dist/mcp/domain/workflow-intent.js

@@ -1,1806 +0,0 @@
-/**
- * WorkflowIntent - Intermediate Representation for Workflow Generation
- *
- * Normalizes any input (natural language, partial spec, full spec) into a
- * structured intent that can be validated, clarified, and then compiled.
- *
- * Key concepts:
- * - **Action Chains**: Understand end-to-end flows (generate doc → attach → send)
- * - **Entity Relationships**: Who (client, advisor), what (brief, report), how (email, download)
- * - **Type Compatibility**: Ensure output types match expected input types
- */
-/**
- * Schema for LLM extraction of output semantics.
- * Pass this to an LLM along with user input to get structured understanding.
- */
-export const OUTPUT_SEMANTICS_EXTRACTION_SCHEMA = {
-    name: "extract_output_semantics",
-    description: "Extract semantic attributes about the desired output from user's request",
-    parameters: {
-        type: "object",
-        properties: {
-            output_type: {
-                type: "object",
-                properties: {
-                    primary: { type: "string", description: "What type of output? (brief, report, email, summary, analysis, proposal, etc.)" },
-                    category: { type: "string", enum: ["document", "communication", "response", "data", "notification"] },
-                    requires_attachment: { type: "boolean" },
-                    requires_delivery: { type: "boolean" },
-                },
-                required: ["primary", "category", "requires_attachment", "requires_delivery"],
-            },
-            format: {
-                type: "object",
-                properties: {
-                    primary: { type: "string", enum: ["document", "email", "chat", "file", "api_response"] },
-                    file_format: { type: "string", enum: ["docx", "pdf", "html", "markdown", "xlsx"] },
-                    structure: { type: "string", enum: ["narrative", "bullet_points", "sections", "table", "mixed"] },
-                },
-                required: ["primary"],
-            },
-            tone: {
-                type: "object",
-                properties: {
-                    formality: { type: "string", enum: ["formal", "professional", "casual", "friendly", "neutral"] },
-                    sentiment: { type: "string", enum: ["positive", "neutral", "cautious", "urgent"] },
-                    voice: { type: "string", enum: ["active", "passive", "mixed"] },
-                },
-                required: ["formality", "sentiment", "voice"],
-            },
-            style: {
-                type: "object",
-                properties: {
-                    approach: { type: "string", enum: ["analytical", "persuasive", "informative", "instructional", "conversational"] },
-                    detail_level: { type: "string", enum: ["high_level", "balanced", "detailed", "exhaustive"] },
-                    use_examples: { type: "boolean" },
-                    use_citations: { type: "boolean" },
-                },
-                required: ["approach", "detail_level", "use_examples", "use_citations"],
-            },
-            audience: {
-                type: "object",
-                properties: {
-                    type: { type: "string", enum: ["internal", "external", "client", "executive", "technical", "general"] },
-                    familiarity: { type: "string", enum: ["expert", "familiar", "novice", "unknown"] },
-                    relationship: { type: "string", description: "Relationship to recipient (client, colleague, manager, etc.)" },
-                },
-                required: ["type", "familiarity"],
-            },
-            purpose: {
-                type: "object",
-                properties: {
-                    primary: { type: "string", enum: ["inform", "persuade", "summarize", "analyze", "recommend", "request", "confirm"] },
-                    secondary: { type: "array", items: { type: "string" } },
-                    action_required: { type: "boolean" },
-                    decision_support: { type: "boolean" },
-                },
-                required: ["primary", "action_required", "decision_support"],
-            },
-            length: { type: "string", enum: ["brief", "standard", "detailed", "comprehensive"] },
-            formatting_requirements: { type: "array", items: { type: "string" } },
-            reasoning: { type: "string", description: "Brief explanation of why these attributes were chosen" },
-        },
-        required: ["output_type", "format", "tone", "style", "audience", "purpose", "length"],
-    },
-};
-/**
- * Default output semantics when LLM extraction is not available.
- * Falls back to reasonable defaults for professional document generation.
- */
-export const DEFAULT_OUTPUT_SEMANTICS = {
-    output_type: {
-        primary: "document",
-        category: "document",
-        requires_attachment: false,
-        requires_delivery: false,
-    },
-    format: {
-        primary: "document",
-        file_format: "docx",
-        structure: "sections",
-    },
-    tone: {
-        formality: "professional",
-        sentiment: "neutral",
-        voice: "active",
-    },
-    style: {
-        approach: "informative",
-        detail_level: "balanced",
-        use_examples: false,
-        use_citations: true,
-    },
-    audience: {
-        type: "general",
-        familiarity: "familiar",
-    },
-    purpose: {
-        primary: "inform",
-        action_required: false,
-        decision_support: false,
-    },
-    length: "standard",
-    extraction_confidence: 50, // Default confidence when using fallback
-};
-export function detectInputType(input) {
-    if (typeof input === "string") {
-        // Check if it's JSON
-        try {
-            const parsed = JSON.parse(input);
-            return detectInputType(parsed);
-        }
-        catch {
-            return "natural_language";
-        }
-    }
-    if (typeof input === "object" && input !== null) {
-        const obj = input;
-        // Full spec: has nodes array with proper structure
-        if (Array.isArray(obj.nodes) && obj.nodes.length > 0) {
-            const firstNode = obj.nodes[0];
-            if (firstNode.id && firstNode.actionType) {
-                return "full_spec";
-            }
-        }
-        // Existing workflow: has actions array (workflow_def structure)
-        if (Array.isArray(obj.actions)) {
-            return "existing_workflow";
-        }
-        // Partial spec: has some structure but not full nodes
-        if (obj.intents || obj.tools || obj.data_sources) {
-            return "partial_spec";
-        }
-    }
-    return "natural_language";
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Natural Language Parsing
-// ─────────────────────────────────────────────────────────────────────────────
-// INTENT_PATTERNS and TOOL_PATTERNS removed - were only used by parseNaturalLanguage()
-// which violated LLM-driven architecture. Agent should understand intent naturally.
-// ─────────────────────────────────────────────────────────────────────────────
-// Action Chain Patterns - End-to-End Semantic Flows
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Known action chains that require specific wiring
- */
-const ACTION_CHAIN_PATTERNS = [
-    {
-        id: "llm_template_to_doc",
-        name: "LLM Templating → Document Generation",
-        description: "Use LLM to generate structured content with template prompt, then convert to document. RECOMMENDED for dynamic, context-dependent content.",
-        steps: [
-            {
-                action_type: "search",
-                purpose: "Gather context from knowledge base",
-                input_from: "trigger.user_query",
-                output_to: "content_generator",
-                config: { output: "search_results", output_type: "WELL_KNOWN_TYPE_SEARCH_RESULT" },
-            },
-            {
-                action_type: "call_llm",
-                purpose: "Generate structured content with LLM templating",
-                input_from: "search_results via named_inputs",
-                output_to: "document_generator",
-                config: {
-                    // LLM TEMPLATING: Use structured prompt with section headers
-                    // The LLM determines appropriate sections based on content type
-                    prompt_guidance: "Include structured sections with ## headers. Let LLM determine appropriate structure based on content type and user intent.",
-                    temperature: "0.3-0.5 for consistent formatting",
-                    use_named_inputs_for_data: true,
-                },
-            },
-            {
-                action_type: "generate_document",
-                purpose: "Convert markdown to document format",
-                input_from: "call_llm.response_with_sources",
-                output_to: "email_or_output",
-                config: { output: "document_link", output_type: "WELL_KNOWN_TYPE_DOCUMENT" },
-            },
-        ],
-    },
-    {
-        id: "doc_to_email",
-        name: "Document Generation → Email Delivery",
-        description: "Generate a document and send it as an email attachment",
-        steps: [
-            {
-                action_type: "generate_document",
-                purpose: "Create the document",
-                input_from: "content_source", // search_results, llm output, etc.
-                output_to: "email_attachment",
-                config: { output: "document_link", output_type: "WELL_KNOWN_TYPE_DOCUMENT" },
-            },
-            {
-                action_type: "send_email_agent",
-                purpose: "Send email with document attached",
-                input_from: "document_link",
-                output_to: "result",
-                config: {
-                    // CRITICAL: document_link is DOCUMENT type, NOT TEXT_WITH_SOURCES
-                    // Must use named_inputs for attachment, not attachment_links
-                    attachment_binding: "named_inputs",
-                    attachment_name: "document_attachment",
-                },
-            },
-        ],
-    },
-    {
-        id: "entity_to_scoped_search",
-        name: "Entity Extraction → Scoped Search",
-        description: "Extract entities (client, advisor) and use them to scope searches",
-        steps: [
-            {
-                action_type: "entity_extraction_with_documents",
-                purpose: "Extract structured entities from conversation",
-                input_from: "trigger.chat_conversation",
-                output_to: "json_mapper",
-            },
-            {
-                action_type: "json_mapper",
-                purpose: "Transform entities into usable variables",
-                input_from: "extracted_entities",
-                output_to: "search_query_modifier",
-            },
-            {
-                action_type: "search",
-                purpose: "Search scoped to extracted entity",
-                input_from: "scoped_query",
-                output_to: "response",
-            },
-        ],
-    },
-    {
-        id: "actor_identification",
-        name: "Actor Identification Flow",
-        description: "Identify caller type and route/validate accordingly",
-        steps: [
-            {
-                action_type: "text_categorizer",
-                purpose: "Classify actor type (client, advisor, unknown)",
-                input_from: "trigger.chat_conversation",
-                output_to: "conditional_routing",
-            },
-            {
-                action_type: "call_llm",
-                purpose: "For unknown actors: ask for identification",
-                input_from: "unknown_actor_branch",
-                output_to: "validation",
-                config: { condition: "actor == unknown" },
-            },
-        ],
-    },
-    {
-        id: "search_combine_respond",
-        name: "Multi-Source Search → Combine → Respond",
-        description: "Search multiple sources, combine results, generate response",
-        steps: [
-            {
-                action_type: "search",
-                purpose: "Search knowledge base",
-                input_from: "trigger.user_query",
-                output_to: "combiner",
-                config: { output: "search_results", output_type: "WELL_KNOWN_TYPE_SEARCH_RESULT" },
-            },
-            {
-                action_type: "live_web_search",
-                purpose: "Search web for real-time data",
-                input_from: "trigger.user_query",
-                output_to: "combiner",
-                config: { output: "search_results", output_type: "WELL_KNOWN_TYPE_SEARCH_RESULT" },
-            },
-            {
-                action_type: "combine_search_results",
-                purpose: "Merge results from multiple sources",
-                input_from: "both_search_results",
-                output_to: "response",
-                config: { output: "combined_results", output_type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES" },
-            },
-            {
-                action_type: "respond_with_sources",
-                purpose: "Generate response with citations",
-                // CRITICAL: respond_with_sources.search_results expects SEARCH_RESULT, not TEXT_WITH_SOURCES
-                // Route original search.search_results, not combined_results
-                input_from: "search.search_results",
-                output_to: "result",
-                config: { use_original_search_for_search_results: true },
-            },
-        ],
-    },
-    {
-        id: "content_generation_to_doc",
-        name: "Content Generation → Document",
-        description: "Generate rich content and create downloadable document",
-        steps: [
-            {
-                action_type: "personalized_content_generator",
-                purpose: "Generate rich HTML content",
-                input_from: "search_results",
-                output_to: "document_generator",
-                config: { output: "generated_content", output_type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES" },
-            },
-            {
-                action_type: "generate_document",
-                purpose: "Create downloadable document",
-                input_from: "generated_content",
-                output_to: "delivery",
-                config: { output: "document_link", output_type: "WELL_KNOWN_TYPE_DOCUMENT" },
-            },
-        ],
-    },
-    {
-        id: "extract_validate_action",
-        name: "Extract Required Inputs → Validate → Action",
-        description: "Extract required data, validate completeness, ask if missing, confirm before action",
-        steps: [
-            {
-                action_type: "entity_extraction",
-                purpose: "Extract required fields from conversation",
-                input_from: "trigger.chat_conversation",
-                output_to: "validator",
-                config: {
-                    // CRITICAL: Define extraction schema with required fields
-                    extraction_schema: {
-                        email_address: { type: "string", required: true },
-                        recipient_name: { type: "string", required: false },
-                        subject: { type: "string", required: false },
-                    },
-                },
-            },
-            {
-                action_type: "text_categorizer",
-                purpose: "Check if all required inputs are present",
-                input_from: "extracted_entities",
-                output_to: "conditional_routing",
-                config: {
-                    categories: ["has_all_required", "missing_required"],
-                    // Route based on presence of required fields
-                },
-            },
-            {
-                action_type: "call_llm",
-                purpose: "Ask for missing required inputs",
-                input_from: "missing_required_branch",
-                output_to: "workflow_output",
-                config: {
-                    condition: "category == missing_required",
-                    prompt: "Ask user for the missing required information",
-                },
-            },
-            {
-                action_type: "hitl",
-                purpose: "Confirm before executing action with side effects",
-                input_from: "has_all_required_branch",
-                output_to: "action_execution",
-                config: { confirmation_message: "Confirm action before proceeding" },
-            },
-            {
-                action_type: "send_email_agent",
-                purpose: "Execute the action only after validation and confirmation",
-                input_from: "hitl_success",
-                output_to: "result",
-                config: {
-                    // CRITICAL: email_to must come from entity_extraction, NOT from summarized text
-                    email_to_source: "entity_extraction.email_address",
-                    runIf: "HITL Success",
-                },
-            },
-        ],
-    },
-    {
-        id: "email_with_validation",
-        name: "Email Sending with Proper Validation",
-        description: "Send email with extracted recipient, validation, and HITL confirmation",
-        steps: [
-            {
-                action_type: "entity_extraction",
-                purpose: "Extract email recipient from conversation",
-                input_from: "trigger.chat_conversation",
-                output_to: "validation",
-                config: {
-                    // Extract structured data, NOT summarized text
-                    output: "extracted_entities",
-                    output_type: "WELL_KNOWN_TYPE_JSON",
-                },
-            },
-            {
-                action_type: "hitl",
-                purpose: "Confirm recipient and content before sending",
-                input_from: "extracted_entities",
-                output_to: "conditional",
-                config: {
-                    // REQUIRED for any action with side effects
-                    display_extracted_data: true,
-                },
-            },
-            {
-                action_type: "send_email_agent",
-                purpose: "Send email after confirmation",
-                input_from: "hitl.success",
-                output_to: "result",
-                config: {
-                    // CRITICAL: email_to must be EMAIL ADDRESS from extraction
-                    // NOT: summarized_conversation (text)
-                    // NOT: search_results (sources)
-                    // NOT: response_with_sources (generated text)
-                    email_to_source: "entity_extraction.email_address",
-                    runIf: "HITL Success",
-                },
-            },
-        ],
-    },
-];
-/**
- * Intent routing type compatibility - determines how outputs wire to inputs during intent processing.
- *
- * NOTE: This is SEPARATE from knowledge.ts TYPE_COMPATIBILITY which is user-facing documentation.
- * This focuses on the "can_connect_to" and "use_named_inputs_for" routing logic.
- *
- * Canonical type documentation: src/sdk/knowledge.ts → TYPE_COMPATIBILITY
- */
-export const INTENT_TYPE_ROUTING = {
-    WELL_KNOWN_TYPE_CHAT_CONVERSATION: {
-        can_connect_to: ["conversation"],
-        use_named_inputs_for: [],
-    },
-    WELL_KNOWN_TYPE_TEXT_WITH_SOURCES: {
-        can_connect_to: ["query", "instructions", "context", "text"],
-        use_named_inputs_for: ["search_results", "attachment_links"],
-    },
-    WELL_KNOWN_TYPE_SEARCH_RESULT: {
-        can_connect_to: ["search_results"],
-        use_named_inputs_for: ["text", "query"],
-    },
-    WELL_KNOWN_TYPE_DOCUMENT: {
-        can_connect_to: [], // Documents can't directly connect to typed inputs
-        use_named_inputs_for: ["attachment_links", "text", "query", "content"], // Always use named_inputs
-    },
-};
-/**
- * Detect action chains in the input text
- */
-export function detectActionChains(text) {
-    const detected = [];
-    const lowerText = text.toLowerCase();
-    // Document + Email chain
-    if ((lowerText.includes("document") || lowerText.includes("brief") || lowerText.includes("report")) &&
-        (lowerText.includes("email") || lowerText.includes("send"))) {
-        detected.push(ACTION_CHAIN_PATTERNS.find((c) => c.id === "doc_to_email"));
-    }
-    // Entity extraction + scoped search
-    if ((lowerText.includes("client") || lowerText.includes("advisor") || lowerText.includes("user")) &&
-        (lowerText.includes("scope") || lowerText.includes("filter") || lowerText.includes("their"))) {
-        detected.push(ACTION_CHAIN_PATTERNS.find((c) => c.id === "entity_to_scoped_search"));
-    }
-    // Actor identification
-    if ((lowerText.includes("identify") || lowerText.includes("who is")) &&
-        (lowerText.includes("caller") || lowerText.includes("client") || lowerText.includes("advisor"))) {
-        detected.push(ACTION_CHAIN_PATTERNS.find((c) => c.id === "actor_identification"));
-    }
-    // Multi-source search
-    if ((lowerText.includes("kb") || lowerText.includes("knowledge")) &&
-        (lowerText.includes("web") || lowerText.includes("live") || lowerText.includes("real-time"))) {
-        detected.push(ACTION_CHAIN_PATTERNS.find((c) => c.id === "search_combine_respond"));
-    }
-    // ═══════════════════════════════════════════════════════════════════════════
-    // FALLBACK: String-based detection for document generation
-    // 
-    // NOTE: This is a FALLBACK approach. For accurate semantic understanding,
-    // use LLM extraction via generateOutputSemanticsPrompt() which extracts:
-    // - output_type (document, email, report, etc.)
-    // - format, tone, style, audience, purpose, length
-    // 
-    // The functions below provide defaults when LLM extraction is unavailable.
-    // ═══════════════════════════════════════════════════════════════════════════
-    const hasGenerationIntent = lowerText.includes("generate") || lowerText.includes("create") ||
-        lowerText.includes("prepare") || lowerText.includes("produce") || lowerText.includes("draft");
-    const hasDocumentOutput = lowerText.includes("document") || lowerText.includes("doc") ||
-        lowerText.includes("file") || lowerText.includes("download") || lowerText.includes("pdf") ||
-        lowerText.includes("attachment") || lowerText.includes(".docx");
-    const hasContentSynthesis = lowerText.includes("content") || lowerText.includes("html") ||
-        lowerText.includes("markdown") || lowerText.includes("formatted");
-    if (hasGenerationIntent && (hasDocumentOutput || hasContentSynthesis)) {
-        // LLM templating is the recommended default for dynamic content
-        detected.push(ACTION_CHAIN_PATTERNS.find((c) => c.id === "llm_template_to_doc"));
-    }
-    // Email sending (without document attachment) - requires proper validation
-    if ((lowerText.includes("send") || lowerText.includes("email") || lowerText.includes("mail")) &&
-        !lowerText.includes("document") && !lowerText.includes("attach") && !lowerText.includes("brief")) {
-        detected.push(ACTION_CHAIN_PATTERNS.find((c) => c.id === "email_with_validation"));
-    }
-    // Extract → Validate → Action pattern (when action has side effects)
-    if ((lowerText.includes("send") || lowerText.includes("create") || lowerText.includes("update") || lowerText.includes("book")) &&
-        (lowerText.includes("confirm") || lowerText.includes("validate") || lowerText.includes("required") || lowerText.includes("check"))) {
-        detected.push(ACTION_CHAIN_PATTERNS.find((c) => c.id === "extract_validate_action"));
-    }
-    return detected.filter(Boolean);
-}
-// PERSONA_TYPE_PATTERNS removed - no longer used after parseNaturalLanguage() removal
-/**
- * REMOVED: parseNaturalLanguage() - regex-based NL parsing violates LLM-driven architecture
- *
- * This function was removed because it violates the core principle:
- * "THE AGENT (LLM) DOES THE THINKING. THE MCP PROVIDES CONTEXT AND EXECUTES."
- *
- * Natural language input should be handled by:
- * 1. Intent Architect (runIntentArchitect) - analyzes complexity and returns LLM prompts
- * 2. generateWorkflow() - takes WorkflowIntent and returns LLM prompts for complex cases
- * 3. Direct structured input (WorkflowSpec) from the Agent
- *
- * For natural language input, create a minimal WorkflowIntent and let Intent Architect
- * or generateWorkflow() handle the complexity analysis.
- *
- * @see src/mcp/AGENTS.md for the LLM-driven architecture guidelines
- */
-function createMinimalIntentFromText(text, personaType = "chat") {
-    // Create minimal intent - no regex parsing
-    // Intent Architect and generateWorkflow() will handle complexity analysis
-    // Extract a name from the text (first sentence or first N words)
-    const sentences = text.split(/[.!?]/);
-    const name = sentences[0].trim().slice(0, 50) || "AI Employee";
-    return {
-        name,
-        description: text,
-        persona_type: personaType,
-    };
-}
-/**
- * Detect entities that should be extracted from the conversation
- */
-function detectEntities(text) {
-    const entities = [];
-    const lowerText = text.toLowerCase();
-    // Client entity
-    if (lowerText.includes("client")) {
-        entities.push({
-            name: "client",
-            type: "person",
-            extract_from: "conversation",
-            use_for: ["scoped_search", "email_recipient", "document_context"],
-        });
-    }
-    // Advisor entity
-    if (lowerText.includes("advisor")) {
-        entities.push({
-            name: "advisor",
-            type: "person",
-            extract_from: "conversation",
-            use_for: ["validation", "cc_recipient"],
-        });
-    }
-    // Ticker/stock symbol
-    if (/ticker|stock|symbol|security/i.test(text)) {
-        entities.push({
-            name: "ticker",
-            type: "identifier",
-            extract_from: "conversation",
-            use_for: ["scoped_search", "document_title"],
-        });
-    }
-    // Topic/focus area
-    if (/focus|topic|about|regarding/i.test(text)) {
-        entities.push({
-            name: "focus_area",
-            type: "topic",
-            extract_from: "conversation",
-            use_for: ["scoped_search", "document_content"],
-        });
-    }
-    return entities;
-}
-/**
- * Detect how results should be delivered
- */
-function detectDeliveryConfig(text) {
-    const lowerText = text.toLowerCase();
-    const methods = [];
-    // Email delivery
-    if (lowerText.includes("email") || lowerText.includes("send")) {
-        const emailConfig = {
-            recipient_source: "extracted",
-            subject_source: "generated",
-            body_source: "llm_generated",
-            include_attachments: false,
-        };
-        // Check if document should be attached
-        if ((lowerText.includes("attach") || lowerText.includes("document") || lowerText.includes("brief")) &&
-            lowerText.includes("email")) {
-            emailConfig.include_attachments = true;
-            emailConfig.attachment_source = "generate_document.document_link";
-        }
-        methods.push({ type: "email", config: emailConfig });
-    }
-    // Document delivery (download/generate)
-    if (lowerText.includes("document") ||
-        lowerText.includes("brief") ||
-        lowerText.includes("report") ||
-        lowerText.includes("download")) {
-        const docConfig = {
-            document_type: lowerText.includes("brief")
-                ? "brief"
-                : lowerText.includes("report")
-                    ? "report"
-                    : "summary",
-            title_source: "extracted",
-            content_source: "combined",
-        };
-        methods.push({ type: "document", config: docConfig });
-    }
-    // Determine if confirmation is needed
-    const requiresConfirmation = lowerText.includes("confirm") || lowerText.includes("approve");
-    if (methods.length === 0) {
-        return undefined;
-    }
-    return {
-        method: methods.length > 1 ? "multiple" : methods[0].type,
-        methods: methods.length > 1 ? methods : undefined,
-        requires_confirmation: requiresConfirmation || methods.some((m) => m.type === "email"),
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Partial Spec Parsing
-// ─────────────────────────────────────────────────────────────────────────────
-export function parsePartialSpec(spec) {
-    return {
-        name: String(spec.name ?? "AI Employee"),
-        description: String(spec.description ?? ""),
-        persona_type: spec.persona_type ?? "chat",
-        intents: spec.intents,
-        tools: spec.tools,
-        data_sources: spec.data_sources,
-        constraints: spec.constraints,
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Validation
-// ─────────────────────────────────────────────────────────────────────────────
-export function validateIntent(intent) {
-    const missing = [];
-    const questions = [];
-    const suggestions = [];
-    // Check name/description
-    if (!intent.name || intent.name.length < 3) {
-        missing.push("name");
-        questions.push("What should this AI Employee be called?");
-    }
-    if (!intent.description || intent.description.length < 10) {
-        missing.push("description");
-        questions.push("What should this AI Employee do?");
-    }
-    // Check if we have any capability defined
-    const hasCapability = (intent.intents?.length ?? 0) > 0 ||
-        (intent.tools?.length ?? 0) > 0 ||
-        (intent.data_sources?.length ?? 0) > 0;
-    if (!hasCapability) {
-        missing.push("capabilities");
-        questions.push("What capabilities should this AI have? (e.g., search KB, create tickets, route by intent)");
-    }
-    // Intent-specific validation
-    if (intent.intents && intent.intents.length > 0) {
-        // Check for Fallback
-        const hasFallback = intent.intents.some((i) => i.name.toLowerCase() === "fallback");
-        if (!hasFallback) {
-            suggestions.push("Consider adding a 'Fallback' intent for unmatched queries");
-        }
-        // Check tool intents have tool config
-        for (const i of intent.intents) {
-            if (i.handler === "tool" && !i.tool_config && (intent.tools?.length ?? 0) === 0) {
-                missing.push(`tool for intent "${i.name}"`);
-                questions.push(`What tool should handle the "${i.name}" intent? (e.g., ServiceNow, Salesforce)`);
-            }
-        }
-    }
-    // Tool validation
-    if (intent.tools && intent.tools.length > 0 && !intent.constraints?.require_hitl) {
-        suggestions.push("External tools detected - consider enabling HITL for safety");
-    }
-    // Voice-specific validation
-    if (intent.persona_type === "voice") {
-        if (!intent.voice_config?.welcome_message) {
-            suggestions.push("Voice AI should have a welcome message");
-        }
-        if (!intent.voice_config?.hangup_instructions) {
-            suggestions.push("Voice AI should have hangup instructions");
-        }
-    }
-    // ═══════════════════════════════════════════════════════════════════════════
-    // ACTION CHAIN VALIDATION - Critical for end-to-end flows
-    // ═══════════════════════════════════════════════════════════════════════════
-    if (intent.action_chains && intent.action_chains.length > 0) {
-        for (const chain of intent.action_chains) {
-            // Validate doc_to_email chain
-            if (chain.id === "doc_to_email") {
-                // Check if we have email config
-                if (!intent.delivery_config?.methods?.some((m) => m.type === "email")) {
-                    questions.push("Who should receive the email? (client, advisor, specific email)");
-                    missing.push("email_recipient");
-                }
-                // Check for document config
-                if (!intent.delivery_config?.methods?.some((m) => m.type === "document")) {
-                    questions.push("What type of document should be generated? (brief, report, summary)");
-                    missing.push("document_type");
-                }
-                // CRITICAL: Remind about proper wiring
-                suggestions.push("Document → Email chain detected. IMPORTANT: document_link output is DOCUMENT type. " +
-                    "Use named_inputs (not attachment_links) to attach documents to emails.");
-            }
-            // Validate entity_to_scoped_search chain
-            if (chain.id === "entity_to_scoped_search") {
-                if (!intent.entities || intent.entities.length === 0) {
-                    questions.push("What entities should be extracted? (client name, advisor, ticker symbol)");
-                    missing.push("entities_to_extract");
-                }
-            }
-            // Validate actor_identification chain
-            if (chain.id === "actor_identification") {
-                questions.push("How should unknown actors be validated? (phone number, PIN, name lookup)");
-                suggestions.push("Actor identification detected. Consider adding validation for unknown callers.");
-            }
-        }
-    }
-    // ═══════════════════════════════════════════════════════════════════════════
-    // ENTITY VALIDATION
-    // ═══════════════════════════════════════════════════════════════════════════
-    if (intent.entities && intent.entities.length > 0) {
-        for (const entity of intent.entities) {
-            // Check if entity usage is clear
-            if (!entity.use_for || entity.use_for.length === 0) {
-                questions.push(`What should the extracted "${entity.name}" be used for?`);
-            }
-            // Email recipient validation
-            if (entity.use_for?.includes("email_recipient")) {
-                suggestions.push(`Ensure ${entity.name} entity extraction includes email address field for email delivery.`);
-            }
-        }
-    }
-    // ═══════════════════════════════════════════════════════════════════════════
-    // DELIVERY VALIDATION
-    // ═══════════════════════════════════════════════════════════════════════════
-    if (intent.delivery_config) {
-        // Email delivery checks
-        const emailMethod = intent.delivery_config.methods?.find((m) => m.type === "email");
-        if (emailMethod) {
-            const emailConfig = emailMethod.config;
-            if (emailConfig?.include_attachments && !emailConfig.attachment_source) {
-                questions.push("What should be attached to the email? (generated document, search results)");
-                missing.push("email_attachment_source");
-            }
-            if (emailConfig?.recipient_source === "static" && !emailConfig.static_recipient) {
-                questions.push("What email address should receive the message?");
-                missing.push("email_recipient_address");
-            }
-            if (emailConfig?.recipient_source === "extracted" && (!intent.entities || intent.entities.length === 0)) {
-                questions.push("How should the recipient email be determined? (extract from conversation, user specifies)");
-                missing.push("recipient_extraction_config");
-            }
-            // Confirm send
-            if (!intent.delivery_config.requires_confirmation) {
-                suggestions.push("Email delivery detected. Consider requiring confirmation before sending.");
-            }
-        }
-        // Document delivery checks
-        const docMethod = intent.delivery_config.methods?.find((m) => m.type === "document");
-        if (docMethod) {
-            const docConfig = docMethod.config;
-            if (!docConfig?.document_type) {
-                questions.push("What type of document should be generated? (brief, report, analysis)");
-                missing.push("document_type");
-            }
-            if (!docConfig?.content_source) {
-                questions.push("Where should document content come from? (search results, generated, template)");
-                missing.push("document_content_source");
-            }
-        }
-    }
-    // Calculate confidence
-    let confidence;
-    if (missing.length === 0 && questions.length === 0) {
-        confidence = "high";
-    }
-    else if (missing.length <= 1) {
-        confidence = "medium";
-    }
-    else {
-        confidence = "low";
-    }
-    return {
-        complete: missing.length === 0,
-        confidence,
-        missing,
-        questions,
-        suggestions,
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Comprehensive Intent Confidence Analysis
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Calculate comprehensive confidence in our understanding of the user's intent.
- * This is the primary driver for deciding whether to proceed or ask questions.
- *
- * @param intent - The parsed workflow intent
- * @param originalText - The original user input (for context analysis)
- * @returns Detailed confidence analysis with recommended action
- */
-export function calculateIntentConfidence(intent, originalText) {
-    const understood = [];
-    const uncertain = [];
-    const blockers = [];
-    const questions = [];
-    // ═══════════════════════════════════════════════════════════════════════════
-    // 1. GOAL UNDERSTANDING - Why does the user want this?
-    // ═══════════════════════════════════════════════════════════════════════════
-    const goalSignals = [];
-    let goalScore = 0;
-    // Check if we have clear intent definitions
-    if (intent.intents && intent.intents.length > 0) {
-        goalScore += 30;
-        goalSignals.push(`${intent.intents.length} intent(s) identified`);
-        // Check intent clarity
-        const hasDescriptions = intent.intents.every(i => i.description && i.description.length > 10);
-        if (hasDescriptions) {
-            goalScore += 20;
-            goalSignals.push("All intents have clear descriptions");
-        }
-        else {
-            goalSignals.push("Some intents lack clear descriptions");
-            uncertain.push("Purpose of some intents unclear");
-        }
-        // Check if handlers are specified
-        const hasHandlers = intent.intents.every(i => i.handler);
-        if (hasHandlers) {
-            goalScore += 15;
-            goalSignals.push("All intents have defined handlers");
-        }
-    }
-    else {
-        goalSignals.push("No explicit intents defined");
-        uncertain.push("Primary goal unclear");
-    }
-    // Check for recognized patterns (shows we understand the "shape" of what they want)
-    if (intent.action_chains && intent.action_chains.length > 0) {
-        goalScore += 25;
-        goalSignals.push(`Recognized pattern: ${intent.action_chains.map(c => c.name).join(", ")}`);
-        understood.push(`Workflow pattern: ${intent.action_chains[0].name}`);
-    }
-    // Check for persona type (basic understanding)
-    if (intent.persona_type) {
-        goalScore += 10;
-        goalSignals.push(`Persona type: ${intent.persona_type}`);
-        understood.push(`Type: ${intent.persona_type} workflow`);
-    }
-    const goalUnderstanding = {
-        score: Math.min(goalScore, 100),
-        level: goalScore >= 70 ? "high" : goalScore >= 40 ? "medium" : goalScore > 0 ? "low" : "unknown",
-        reason: goalScore >= 70
-            ? "Clear understanding of user's objective"
-            : goalScore >= 40
-                ? "Partial understanding of objective - some aspects unclear"
-                : "Limited understanding of why user wants this workflow",
-        signals: goalSignals,
-    };
-    if (goalScore < 40) {
-        questions.push({
-            id: "goal_clarification",
-            question: "What is the main goal you're trying to achieve with this workflow?",
-            category: "goal_understanding",
-            priority: "critical",
-            context: "Understanding the 'why' helps us design the right solution",
-            options: ["Answer questions", "Generate content", "Process documents", "Send communications", "Search & analyze data"],
-        });
-    }
-    // ═══════════════════════════════════════════════════════════════════════════
-    // 2. INPUT REQUIREMENTS - What data is needed?
-    // ═══════════════════════════════════════════════════════════════════════════
-    const inputSignals = [];
-    let inputScore = 0;
-    // Check for entity definitions
-    if (intent.entities && intent.entities.length > 0) {
-        inputScore += 40;
-        inputSignals.push(`${intent.entities.length} entity type(s) identified: ${intent.entities.map(e => e.type).join(", ")}`);
-        understood.push(`Required entities: ${intent.entities.map(e => e.type).join(", ")}`);
-        // Check if entities have clear use_for
-        const entitiesWithUse = intent.entities.filter(e => e.use_for && e.use_for.length > 0);
-        if (entitiesWithUse.length === intent.entities.length) {
-            inputScore += 20;
-            inputSignals.push("All entities have defined usage");
-        }
-        else {
-            uncertain.push("How some entities will be used");
-        }
-    }
-    else {
-        // Try to infer from action chains
-        if (intent.action_chains?.some(c => c.id === "doc_to_email" || c.id === "email_with_validation")) {
-            inputSignals.push("Email workflow detected - will need recipient email");
-            inputScore += 20;
-            uncertain.push("Email recipient source not specified");
-            questions.push({
-                id: "email_recipient_source",
-                question: "Where will the recipient email address come from?",
-                category: "input_requirements",
-                priority: "critical",
-                context: "Email workflows require a valid email address - need to know the source",
-                options: ["Extract from conversation", "User provides it", "From CRM/database", "Fixed recipient"],
-            });
-        }
-    }
-    // Check for data sources
-    if (intent.data_sources && intent.data_sources.length > 0) {
-        inputScore += 30;
-        inputSignals.push(`Data sources specified: ${intent.data_sources.join(", ")}`);
-        understood.push(`Data sources: ${intent.data_sources.join(", ")}`);
-    }
-    else if (intent.intents?.some(i => i.handler === "search")) {
-        inputSignals.push("Search intent but no data sources specified");
-        uncertain.push("What data sources to search");
-    }
-    const inputRequirements = {
-        score: Math.min(inputScore, 100),
-        level: inputScore >= 70 ? "high" : inputScore >= 40 ? "medium" : inputScore > 0 ? "low" : "unknown",
-        reason: inputScore >= 70
-            ? "Clear understanding of required inputs and data"
-            : inputScore >= 40
-                ? "Some inputs identified but gaps remain"
-                : "Unclear what data/inputs are needed",
-        signals: inputSignals,
-    };
-    // ═══════════════════════════════════════════════════════════════════════════
-    // 3. OUTPUT EXPECTATIONS - What should the result look like?
-    // ═══════════════════════════════════════════════════════════════════════════
-    const outputSignals = [];
-    let outputScore = 0;
-    // Check for delivery config
-    if (intent.delivery_config) {
-        outputScore += 40;
-        outputSignals.push(`Delivery method: ${intent.delivery_config.method}`);
-        understood.push(`Delivery: ${intent.delivery_config.method}`);
-        if (intent.delivery_config.requires_confirmation) {
-            outputScore += 10;
-            outputSignals.push("Confirmation required before delivery");
-        }
-    }
-    else {
-        outputSignals.push("Delivery method not specified");
-        uncertain.push("How results should be delivered");
-    }
-    // Check intent handlers for output hints
-    const outputHandlers = intent.intents?.filter(i => i.handler === "document" ||
-        i.handler === "email" ||
-        i.document_config ||
-        i.email_config) ?? [];
-    if (outputHandlers.length > 0) {
-        outputScore += 30;
-        outputSignals.push(`Output-producing handlers: ${outputHandlers.length}`);
-    }
-    // Check for specific output configurations
-    if (intent.intents?.some(i => i.document_config?.document_type)) {
-        outputScore += 20;
-        outputSignals.push("Document type specified");
-        understood.push("Document generation required");
-    }
-    const outputExpectations = {
-        score: Math.min(outputScore, 100),
-        level: outputScore >= 70 ? "high" : outputScore >= 40 ? "medium" : outputScore > 0 ? "low" : "unknown",
-        reason: outputScore >= 70
-            ? "Clear understanding of expected outputs"
-            : outputScore >= 40
-                ? "Partial understanding of expected outputs"
-                : "Unclear what the workflow should produce",
-        signals: outputSignals,
-    };
-    if (outputScore < 40) {
-        questions.push({
-            id: "output_format",
-            question: "What should the output of this workflow look like?",
-            category: "output_expectations",
-            priority: "important",
-            context: "Understanding the expected output helps design the right response format",
-            options: ["Text response in chat", "Generated document", "Email to someone", "Data update", "Multiple outputs"],
-        });
-    }
-    // ═══════════════════════════════════════════════════════════════════════════
-    // 4. PATTERN RECOGNITION - Do we recognize this workflow type?
-    // ═══════════════════════════════════════════════════════════════════════════
-    const patternSignals = [];
-    let patternScore = 0;
-    if (intent.action_chains && intent.action_chains.length > 0) {
-        patternScore += 60;
-        for (const chain of intent.action_chains) {
-            patternSignals.push(`Matched pattern: ${chain.name}`);
-            understood.push(`Pattern: ${chain.description}`);
-        }
-    }
-    // Check for common patterns even without explicit action chains
-    const hasSearch = intent.intents?.some(i => i.handler === "search");
-    const hasLlm = intent.intents?.some(i => i.handler === "llm");
-    const hasDocument = intent.intents?.some(i => i.handler === "document" || i.document_config);
-    const hasEmail = intent.intents?.some(i => i.handler === "email" || i.email_config);
-    if (hasSearch && hasLlm && !intent.action_chains?.length) {
-        patternScore += 30;
-        patternSignals.push("Search + LLM pattern (RAG-style)");
-    }
-    if (hasDocument && hasEmail && !intent.action_chains?.some(c => c.id === "doc_to_email")) {
-        patternSignals.push("Document + Email detected but chain not matched");
-        uncertain.push("Document-to-email flow not fully specified");
-    }
-    const patternRecognition = {
-        score: Math.min(patternScore, 100),
-        level: patternScore >= 60 ? "high" : patternScore >= 30 ? "medium" : patternScore > 0 ? "low" : "unknown",
-        reason: patternScore >= 60
-            ? "Recognized workflow pattern with known best practices"
-            : patternScore >= 30
-                ? "Partial pattern match - may need customization"
-                : "No recognized pattern - custom workflow needed",
-        signals: patternSignals,
-    };
-    // ═══════════════════════════════════════════════════════════════════════════
-    // 5. DATA COMPLETENESS - Are required fields specified?
-    // ═══════════════════════════════════════════════════════════════════════════
-    const dataSignals = [];
-    let dataScore = 50; // Start at 50, deduct for missing critical data
-    // Check action chain requirements
-    if (intent.action_chains) {
-        for (const chain of intent.action_chains) {
-            if (chain.id === "doc_to_email" || chain.id === "email_with_validation") {
-                // Email requires recipient - check entities by name or use_for
-                const hasEmailEntity = intent.entities?.some(e => e.name?.toLowerCase().includes("email") ||
-                    e.name?.toLowerCase().includes("recipient") ||
-                    e.use_for?.some(u => u.includes("email") || u.includes("recipient")));
-                if (!hasEmailEntity) {
-                    dataScore -= 30;
-                    dataSignals.push("Email recipient not specified");
-                    blockers.push({
-                        category: "data_completeness",
-                        what: "Email recipient",
-                        why: "Cannot send email without knowing who to send it to",
-                        impact: "blocking",
-                    });
-                    questions.push({
-                        id: "email_recipient",
-                        question: "Who should receive the email?",
-                        category: "data_completeness",
-                        priority: "critical",
-                        context: "Email recipient is required to send the email",
-                    });
-                }
-                else {
-                    dataSignals.push("Email recipient source identified");
-                }
-            }
-            if (chain.id === "doc_to_email") {
-                // Document type should be specified
-                if (!intent.intents?.some(i => i.document_config?.document_type)) {
-                    dataScore -= 15;
-                    dataSignals.push("Document type not specified");
-                    uncertain.push("What type of document to generate");
-                }
-            }
-        }
-    }
-    // Check for incomplete entity definitions (entities without clear usage)
-    const incompleteEntities = intent.entities?.filter(e => !e.use_for?.length) ?? [];
-    if (incompleteEntities.length > 0) {
-        dataScore -= 10;
-        dataSignals.push(`${incompleteEntities.length} entities with incomplete definitions`);
-    }
-    dataScore = Math.max(0, dataScore);
-    const dataCompleteness = {
-        score: dataScore,
-        level: dataScore >= 70 ? "high" : dataScore >= 40 ? "medium" : dataScore > 0 ? "low" : "unknown",
-        reason: dataScore >= 70
-            ? "Required data and fields are specified"
-            : dataScore >= 40
-                ? "Some required data missing but workflow may still work"
-                : "Critical data missing - cannot proceed",
-        signals: dataSignals,
-    };
-    // ═══════════════════════════════════════════════════════════════════════════
-    // 6. CONSTRAINTS CLARITY - Do we understand rules and constraints?
-    // ═══════════════════════════════════════════════════════════════════════════
-    const constraintSignals = [];
-    let constraintScore = 50; // Start at 50 (neutral if no constraints)
-    // Check for confirmation requirements
-    if (intent.delivery_config?.requires_confirmation) {
-        constraintScore += 20;
-        constraintSignals.push("Confirmation requirement specified");
-        understood.push("Requires confirmation before action");
-    }
-    // Check for HITL patterns in action chains
-    const needsHitl = intent.action_chains?.some(c => c.id === "email_with_validation" ||
-        c.id === "extract_validate_action" ||
-        c.steps?.some(s => s.action_type === "hitl"));
-    if (needsHitl) {
-        constraintScore += 15;
-        constraintSignals.push("HITL requirement recognized");
-        understood.push("Human approval needed before side effects");
-    }
-    else if (intent.action_chains?.some(c => c.id.includes("email"))) {
-        // Email without HITL - potential issue
-        constraintSignals.push("Email action without explicit HITL requirement");
-        uncertain.push("Whether confirmation is needed before sending");
-    }
-    const constraintsClarity = {
-        score: Math.min(constraintScore, 100),
-        level: constraintScore >= 70 ? "high" : constraintScore >= 40 ? "medium" : constraintScore > 0 ? "low" : "unknown",
-        reason: constraintScore >= 70
-            ? "Constraints and rules are clear"
-            : constraintScore >= 40
-                ? "Some constraints understood but may need defaults"
-                : "Unclear what rules or constraints apply",
-        signals: constraintSignals,
-    };
-    // ═══════════════════════════════════════════════════════════════════════════
-    // CALCULATE OVERALL CONFIDENCE
-    // ═══════════════════════════════════════════════════════════════════════════
-    // Weighted average with goal understanding being most important
-    const weights = {
-        goal_understanding: 0.25,
-        input_requirements: 0.20,
-        output_expectations: 0.15,
-        pattern_recognition: 0.15,
-        data_completeness: 0.15,
-        constraints_clarity: 0.10,
-    };
-    const overall = Math.round(goalUnderstanding.score * weights.goal_understanding +
-        inputRequirements.score * weights.input_requirements +
-        outputExpectations.score * weights.output_expectations +
-        patternRecognition.score * weights.pattern_recognition +
-        dataCompleteness.score * weights.data_completeness +
-        constraintsClarity.score * weights.constraints_clarity);
-    // Determine level and recommendation
-    let level;
-    let recommendation;
-    if (blockers.length > 0) {
-        level = "insufficient";
-        recommendation = "clarify_critical";
-    }
-    else if (overall >= 70) {
-        level = "high";
-        recommendation = questions.length > 0 ? "clarify_recommended" : "proceed";
-    }
-    else if (overall >= 45) {
-        level = "medium";
-        recommendation = questions.some(q => q.priority === "critical") ? "clarify_critical" : "clarify_recommended";
-    }
-    else {
-        level = "low";
-        recommendation = "insufficient_info";
-    }
-    // Sort questions by priority
-    questions.sort((a, b) => {
-        const priorityOrder = { critical: 0, important: 1, nice_to_have: 2 };
-        return priorityOrder[a.priority] - priorityOrder[b.priority];
-    });
-    return {
-        overall,
-        level,
-        breakdown: {
-            goal_understanding: goalUnderstanding,
-            input_requirements: inputRequirements,
-            output_expectations: outputExpectations,
-            pattern_recognition: patternRecognition,
-            data_completeness: dataCompleteness,
-            constraints_clarity: constraintsClarity,
-        },
-        understood,
-        uncertain,
-        blockers,
-        recommendation,
-        clarification_questions: questions,
-    };
-}
-/**
- * Get a human-readable summary of intent confidence
- */
-export function summarizeIntentConfidence(confidence) {
-    const lines = [];
-    lines.push(`## Intent Understanding: ${confidence.level.toUpperCase()} (${confidence.overall}%)`);
-    lines.push("");
-    // What we understood
-    if (confidence.understood.length > 0) {
-        lines.push("### ✅ Understood:");
-        for (const item of confidence.understood) {
-            lines.push(`- ${item}`);
-        }
-        lines.push("");
-    }
-    // What's uncertain
-    if (confidence.uncertain.length > 0) {
-        lines.push("### ⚠️ Uncertain:");
-        for (const item of confidence.uncertain) {
-            lines.push(`- ${item}`);
-        }
-        lines.push("");
-    }
-    // Blockers
-    if (confidence.blockers.length > 0) {
-        lines.push("### 🚫 Blocking Issues:");
-        for (const blocker of confidence.blockers) {
-            lines.push(`- **${blocker.what}**: ${blocker.why}`);
-        }
-        lines.push("");
-    }
-    // Recommendation
-    lines.push(`### Recommendation: ${confidence.recommendation.replace(/_/g, " ").toUpperCase()}`);
-    if (confidence.clarification_questions.length > 0) {
-        lines.push("");
-        lines.push("### Questions to Clarify:");
-        for (const q of confidence.clarification_questions) {
-            const priority = q.priority === "critical" ? "🔴" : q.priority === "important" ? "🟡" : "🟢";
-            lines.push(`${priority} ${q.question}`);
-            if (q.options) {
-                lines.push(`   Options: ${q.options.join(", ")}`);
-            }
-        }
-    }
-    return lines.join("\n");
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Intent to Spec Conversion
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Generate takeActionInstructions from tools for Voice AI.
- *
- * This populates the "Define what actions your AI Employee can perform" section
- * in the Voice persona config. Format follows the Ema Voice API spec.
- */
-function generateTakeActionInstructions(tools) {
-    if (!tools || tools.length === 0) {
-        return "";
-    }
-    const cases = tools.map((tool, index) => {
-        const caseNum = index + 1;
-        const toolName = tool.display_name ?? tool.action ?? `Action ${caseNum}`;
-        const triggerCondition = tool.trigger_condition ?? tool.description ?? "Perform this action when requested";
-        // Extract required parameters from tool schema if available
-        const requiredParams = tool.required_inputs ?? [];
-        const paramsObj = requiredParams.length > 0
-            ? `{ ${requiredParams.map(p => `"${p}": ""`).join(", ")} }`
-            : "{ }";
-        return `</Case ${caseNum}>
-${toolName}
-
-Trigger When: ${triggerCondition}
-
-Intent for tool call: "User requests ${toolName.toLowerCase()}"
-
-Required parameters: ${paramsObj}
-</Case ${caseNum}>`;
-    });
-    return cases.join("\n\n");
-}
-export function intentToSpec(intent) {
-    const nodes = [];
-    const resultMappings = [];
-    // 1. Add trigger - Voice and Chat both use chat_trigger, Dashboard uses document_trigger
-    const triggerId = "trigger";
-    // Note: voice_trigger doesn't exist in API - Voice AI uses chat_trigger with voiceSettings in proto_config
-    const triggerType = intent.persona_type === "dashboard" ? "document_trigger" : "chat_trigger";
-    nodes.push({
-        id: triggerId,
-        actionType: triggerType,
-        displayName: "Trigger",
-    });
-    // 2. Add categorizer if multiple intents
-    let categorizerId;
-    if (intent.intents && intent.intents.length > 1) {
-        categorizerId = "categorizer";
-        const categories = intent.intents.map((i) => ({
-            name: i.name,
-            description: i.description,
-            examples: i.examples,
-        }));
-        // Add Fallback if not present
-        if (!categories.some((c) => c.name.toLowerCase() === "fallback")) {
-            categories.push({
-                name: "Fallback",
-                description: "Query doesn't match other categories",
-            });
-        }
-        nodes.push({
-            id: categorizerId,
-            actionType: "chat_categorizer",
-            displayName: "Intent Classifier",
-            inputs: {
-                conversation: {
-                    type: "action_output",
-                    actionName: triggerId,
-                    output: "chat_conversation",
-                },
-            },
-            categories,
-        });
-    }
-    // 3. Add search if data sources include KB
-    let searchId;
-    if (intent.data_sources?.some((ds) => ds.type === "knowledge_base" || ds.type === "combined")) {
-        searchId = "search";
-        nodes.push({
-            id: searchId,
-            actionType: "search",
-            displayName: "Knowledge Search",
-            inputs: {
-                query: {
-                    type: "action_output",
-                    actionName: triggerId,
-                    output: "user_query",
-                },
-                // REQUIRED: Widget binding to fileUpload data sources (uses multiBinding.elements format)
-                datastore_configs: {
-                    type: "widget_config_array",
-                    widgetNames: ["fileUpload"],
-                },
-            },
-        });
-    }
-    // 4. Add web search if enabled
-    let webSearchId;
-    if (intent.data_sources?.some((ds) => ds.type === "web_search" || ds.type === "combined")) {
-        webSearchId = "web_search";
-        nodes.push({
-            id: webSearchId,
-            actionType: "live_web_search",
-            displayName: "Web Search",
-            inputs: {
-                query: {
-                    type: "action_output",
-                    actionName: triggerId,
-                    output: "user_query",
-                },
-            },
-        });
-    }
-    // 5. Add tool caller if tools defined
-    // DISABLED: external_action_caller format causes 500 errors
-    // TODO: Fix tool format and re-enable - tools are stored in intent for future use
-    const toolCallerId = undefined;
-    // if (intent.tools && intent.tools.length > 0) {
-    //   toolCallerId = "tool_caller";
-    //   nodes.push({...});
-    // }
-    // 6. Add HITL if required
-    let hitlId;
-    if (intent.constraints?.require_hitl && toolCallerId) {
-        hitlId = "hitl";
-        nodes.push({
-            id: hitlId,
-            actionType: "general_hitl",
-            displayName: "Human Approval",
-            inputs: {
-                query: {
-                    type: "action_output",
-                    actionName: toolCallerId,
-                    output: "tool_execution_result",
-                },
-            },
-        });
-    }
-    // 7. Add response node
-    const respondId = "respond";
-    const respondInputs = {
-        query: {
-            type: "action_output",
-            actionName: triggerId,
-            output: "user_query",
-        },
-        // REQUIRED: Widget binding to fusionModel for LLM selection
-        model_config: {
-            type: "widget_config",
-            widgetName: "fusionModel",
-        },
-    };
-    if (searchId) {
-        // call_llm uses "named_inputs" not "search_results"
-        // (respond_with_sources doesn't exist in API - mapped to call_llm)
-        respondInputs.named_inputs = {
-            type: "action_output",
-            actionName: searchId,
-            output: "search_results",
-        };
-    }
-    nodes.push({
-        id: respondId,
-        // respond_with_sources doesn't exist in API - always use call_llm
-        actionType: "call_llm",
-        displayName: "Response",
-        inputs: respondInputs,
-    });
-    resultMappings.push({
-        nodeId: respondId,
-        output: searchId ? "response_with_sources" : "response_with_sources",
-    });
-    // NOTE: Action chains (email_with_validation, doc_to_email, etc.) are NOT processed here.
-    // Complex workflows with action chains should be generated via LLM using:
-    // 1. generateWorkflowPrompt(intent, availableActions) - builds LLM prompt
-    // 2. Pass to Auto Builder or external LLM
-    // 3. Parse the LLM response as WorkflowSpec
-    // This keeps intentToSpec simple (basic RAG workflow) and lets LLM handle complexity.
-    // Build voiceConfig from intent.voice_config
-    const voiceConfig = intent.persona_type === "voice" ? {
-        welcomeMessage: intent.voice_config?.welcome_message,
-        identityAndPurpose: intent.voice_config?.identity ?? intent.description,
-        hangupInstructions: intent.voice_config?.hangup_instructions,
-        transferInstructions: intent.voice_config?.transfer_instructions,
-        waitMessage: intent.voice_config?.wait_message,
-        // Generate takeActionInstructions from tools if not explicitly provided
-        takeActionInstructions: intent.voice_config?.take_action_instructions ??
-            generateTakeActionInstructions(intent.tools),
-    } : undefined;
-    return {
-        name: intent.name,
-        description: intent.description,
-        personaType: intent.persona_type,
-        nodes,
-        resultMappings,
-        ...(voiceConfig && { voiceConfig }),
-        ...(intent.persona_type === "chat" && { chatConfig: { name: intent.name } }),
-    };
-}
-/**
- * Parse input and extract workflow intent.
- *
- * Note: The "natural_language" path uses deprecated regex-based parsing.
- * For new code, prefer providing structured input (partial_spec or full_spec)
- * directly from the Agent, which understands user intent naturally.
- */
-export function parseInput(input) {
-    const inputType = detectInputType(input);
-    let intent;
-    switch (inputType) {
-        case "natural_language":
-            // Create minimal intent - no regex parsing
-            // Intent Architect and generateWorkflow() will handle complexity
-            const text = String(input);
-            // Detect persona type from args if available, otherwise default to chat
-            let personaType = "chat";
-            // Simple detection - can be overridden by args.type in handler
-            if (/voice|call|phone/i.test(text)) {
-                personaType = "voice";
-            }
-            else if (/document|batch|upload/i.test(text)) {
-                personaType = "dashboard";
-            }
-            intent = createMinimalIntentFromText(text, personaType);
-            break;
-        case "partial_spec":
-            intent = parsePartialSpec(input);
-            break;
-        case "full_spec":
-            // Full spec: extract intent from the spec
-            const spec = input;
-            intent = {
-                name: spec.name,
-                description: spec.description,
-                persona_type: spec.personaType,
-            };
-            break;
-        case "existing_workflow":
-            // Would need to reverse-engineer from workflow_def
-            // For now, return minimal intent
-            intent = {
-                name: "Existing Workflow",
-                description: "Imported from existing workflow_def",
-                persona_type: "chat",
-            };
-            break;
-    }
-    const validation = validateIntent(intent);
-    return { intent, input_type: inputType, validation };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// LLM-Based Semantic Extraction
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Generate a prompt for LLM-based output semantics extraction.
- * This should be called by tools that have access to an LLM.
- *
- * @param userInput - The user's natural language request
- * @returns Prompt and schema for LLM extraction
- */
-export function generateOutputSemanticsPrompt(userInput) {
-    const systemPrompt = `You are an expert at understanding user requests and extracting semantic attributes about desired outputs.
-
-Given a user's request, extract the following:
-- OUTPUT TYPE: What kind of output are they asking for? (document, email, report, brief, analysis, etc.)
-- FORMAT: How should it be formatted? (document, email, chat response, file type)
-- TONE: What tone is appropriate? (formal, professional, casual, friendly)
-- STYLE: What writing style? (analytical, persuasive, informative, instructional)
-- AUDIENCE: Who is this for? (client, internal, executive, technical)
-- PURPOSE: What is the goal? (inform, persuade, summarize, analyze, recommend)
-- LENGTH: How detailed? (brief, standard, detailed, comprehensive)
-
-Be precise but infer reasonable defaults when not explicitly stated.
-Consider context clues - "send to client" implies external/client audience, "quick summary" implies brief length.`;
-    const userPrompt = `Analyze this user request and extract the output semantic attributes:
-
-"${userInput}"
-
-Extract the attributes using the provided schema. Include your reasoning.`;
-    return {
-        system_prompt: systemPrompt,
-        user_prompt: userPrompt,
-        schema: OUTPUT_SEMANTICS_EXTRACTION_SCHEMA,
-    };
-}
-/**
- * Apply LLM-extracted semantics to an existing intent.
- * Call this after getting LLM extraction results.
- *
- * @param intent - The current workflow intent
- * @param extracted - The LLM-extracted output semantics
- * @returns Updated intent with semantics applied
- */
-export function applyExtractedSemantics(intent, extracted) {
-    return {
-        ...intent,
-        output_semantics: extracted,
-        // Also update delivery config based on extracted info
-        delivery_config: {
-            ...intent.delivery_config,
-            method: extracted.output_type.category === "communication" ? "email" :
-                extracted.output_type.category === "document" ? "document" :
-                    intent.delivery_config?.method ?? "response",
-            requires_confirmation: extracted.output_type.requires_delivery ||
-                extracted.purpose.action_required ||
-                intent.delivery_config?.requires_confirmation,
-        },
-    };
-}
-/**
- * Generate LLM instructions based on extracted semantics.
- * Use these instructions in call_llm prompts for consistent output.
- *
- * @param semantics - The extracted output semantics
- * @returns Instructions to include in LLM prompts
- */
-export function generateContentInstructions(semantics) {
-    const instructions = [];
-    // Tone instructions
-    instructions.push(`TONE: Write in a ${semantics.tone.formality} tone with ${semantics.tone.voice} voice.`);
-    if (semantics.tone.sentiment === "urgent") {
-        instructions.push("Convey urgency appropriately.");
-    }
-    // Style instructions
-    instructions.push(`STYLE: Use ${semantics.style.approach} approach with ${semantics.style.detail_level} detail.`);
-    if (semantics.style.use_citations) {
-        instructions.push("Include citations to source documents.");
-    }
-    if (semantics.style.use_examples) {
-        instructions.push("Include relevant examples where appropriate.");
-    }
-    // Audience instructions
-    instructions.push(`AUDIENCE: Writing for ${semantics.audience.type} audience with ${semantics.audience.familiarity} familiarity.`);
-    if (semantics.audience.relationship) {
-        instructions.push(`The recipient is: ${semantics.audience.relationship}.`);
-    }
-    // Format instructions
-    instructions.push(`FORMAT: Structure content as ${semantics.format.structure ?? "sections"} format.`);
-    // Length instructions
-    const lengthGuidance = {
-        brief: "Keep it concise - 1-2 paragraphs or bullet points.",
-        standard: "Provide balanced coverage - 3-5 paragraphs with key sections.",
-        detailed: "Be thorough - cover all aspects with supporting details.",
-        comprehensive: "Be exhaustive - include all relevant information with deep analysis.",
-    };
-    instructions.push(`LENGTH: ${lengthGuidance[semantics.length]}`);
-    // Purpose instructions
-    instructions.push(`PURPOSE: Primary goal is to ${semantics.purpose.primary}.`);
-    if (semantics.purpose.action_required) {
-        instructions.push("Include clear call-to-action or next steps.");
-    }
-    if (semantics.purpose.decision_support) {
-        instructions.push("Present information to support decision-making.");
-    }
-    // Formatting requirements
-    if (semantics.formatting_requirements && semantics.formatting_requirements.length > 0) {
-        instructions.push(`SPECIFIC REQUIREMENTS: ${semantics.formatting_requirements.join(", ")}`);
-    }
-    return instructions.join("\n");
-}
-/**
- * Determine if intent requires LLM-driven generation or can use simple intentToSpec.
- *
- * Simple (use intentToSpec):
- * - Basic Q&A with search
- * - Single intent without delivery
- *
- * Complex (use LLM):
- * - Action chains (email, document generation)
- * - Multiple intents with routing
- * - HITL requirements
- * - External tool calls
- */
-export function needsLLMGeneration(intent) {
-    // Check for action chains
-    if (intent.action_chains && intent.action_chains.length > 0) {
-        return true;
-    }
-    // Check for email/document delivery
-    if (intent.delivery_config?.methods?.some(m => m.type === "email" || m.type === "document")) {
-        return true;
-    }
-    // Check for HITL requirements
-    if (intent.constraints?.require_hitl) {
-        return true;
-    }
-    // Check for multiple intents (needs categorizer with complex routing)
-    if (intent.intents && intent.intents.length > 2) {
-        return true;
-    }
-    // Check for tools/external actions
-    if (intent.tools && intent.tools.length > 0) {
-        return true;
-    }
-    return false;
-}
-/**
- * Generate a workflow spec or LLM prompt based on intent complexity.
- *
- * For simple intents: returns spec directly
- * For complex intents: returns LLM prompt with full context
- *
- * @param intent - Parsed workflow intent
- * @param availableActions - Actions from ListActions API (optional)
- * @returns Generation result with either spec or LLM prompt
- */
-export function generateWorkflow(intent, availableActions) {
-    const complexity = {
-        has_action_chains: !!(intent.action_chains && intent.action_chains.length > 0),
-        has_email: !!(intent.delivery_config?.methods?.some(m => m.type === "email")),
-        has_hitl: !!intent.constraints?.require_hitl,
-        has_multi_intent: !!(intent.intents && intent.intents.length > 2),
-        chain_ids: intent.action_chains?.map(c => c.id) ?? [],
-    };
-    // Simple workflow - use intentToSpec
-    if (!needsLLMGeneration(intent)) {
-        return {
-            needs_llm: false,
-            spec: intentToSpec(intent),
-            reason: "Simple workflow (basic RAG pattern) - no LLM needed",
-            complexity,
-        };
-    }
-    // Complex workflow - generate LLM prompt
-    const systemPrompt = buildWorkflowGenerationSystemPrompt(availableActions);
-    const userPrompt = buildWorkflowGenerationUserPrompt(intent);
-    return {
-        needs_llm: true,
-        llm_prompt: {
-            system: systemPrompt,
-            user: userPrompt,
-        },
-        reason: `Complex workflow requires LLM: ${complexity.chain_ids.length > 0 ? `chains: ${complexity.chain_ids.join(', ')}` : ''} ${complexity.has_email ? 'email' : ''} ${complexity.has_hitl ? 'HITL' : ''}`.trim(),
-        complexity,
-    };
-}
-/**
- * Build system prompt for LLM workflow generation.
- */
-function buildWorkflowGenerationSystemPrompt(availableActions) {
-    const actionList = availableActions
-        ? availableActions.map(a => `- ${a.name}: ${a.description} (inputs: ${a.inputs.join(', ')})`).join('\n')
-        : 'Use standard Ema actions: chat_trigger, search, call_llm, entity_extraction, general_hitl, send_email, chat_categorizer';
-    return `You are an expert workflow designer for the Ema AI platform.
-
-Your task is to generate a WorkflowSpec JSON that implements the user's requirements.
-
-## Available Actions
-${actionList}
-
-## WorkflowSpec Schema
-\`\`\`typescript
-interface WorkflowSpec {
-  name: string;
-  description: string;
-  personaType: "voice" | "chat" | "dashboard";
-  nodes: Node[];
-  resultMappings: { nodeId: string; output: string }[];
-}
-
-interface Node {
-  id: string;                    // Unique identifier (snake_case)
-  actionType: string;            // Action name from available actions
-  displayName: string;           // Human-readable name
-  inputs?: Record<string, InputBinding>;
-  runIf?: { actionName: string; output: string; enumValue: string };  // Conditional execution
-  categories?: Category[];       // For categorizer nodes
-}
-
-interface InputBinding {
-  type: "action_output" | "inline_string" | "widget_config";
-  actionName?: string;           // For action_output
-  output?: string;               // For action_output
-  value?: string;                // For inline_string
-  widgetName?: string;           // For widget_config
-}
-\`\`\`
-
-## Critical Rules
-1. ALWAYS start with a trigger node (chat_trigger for voice/chat, document_trigger for dashboard)
-2. Wire data correctly: each input must reference a valid upstream output
-3. For EMAIL: extract recipient via entity_extraction FIRST, add HITL before send_email
-4. Use runIf for conditional execution (after HITL approval)
-5. All email recipients must come from entity_extraction, NOT from LLM-generated text
-
-## Example: Email with HITL
-\`\`\`json
-{
-  "nodes": [
-    { "id": "trigger", "actionType": "chat_trigger", "displayName": "Trigger" },
-    { "id": "extract", "actionType": "entity_extraction", "displayName": "Extract Email", 
-      "inputs": { "conversation": { "type": "action_output", "actionName": "trigger", "output": "chat_conversation" } } },
-    { "id": "respond", "actionType": "call_llm", "displayName": "Generate Response",
-      "inputs": { "query": { "type": "action_output", "actionName": "trigger", "output": "user_query" } } },
-    { "id": "hitl", "actionType": "general_hitl", "displayName": "Approve Email",
-      "inputs": { "query": { "type": "action_output", "actionName": "respond", "output": "response" } } },
-    { "id": "send_email", "actionType": "send_email", "displayName": "Send Email",
-      "inputs": { 
-        "email_to": { "type": "action_output", "actionName": "extract", "output": "email_address" },
-        "email_body": { "type": "action_output", "actionName": "respond", "output": "response" }
-      },
-      "runIf": { "actionName": "hitl", "output": "hitl_status", "enumValue": "HITL Success" } }
-  ],
-  "resultMappings": [{ "nodeId": "send_email", "output": "email_sent" }]
-}
-\`\`\`
-
-Respond with ONLY valid JSON - no markdown, no explanation.`;
-}
-/**
- * Build user prompt with intent details.
- */
-function buildWorkflowGenerationUserPrompt(intent) {
-    const sections = [];
-    sections.push(`## User Request\n${intent.description}`);
-    sections.push(`## Persona Type\n${intent.persona_type ?? 'chat'}`);
-    if (intent.action_chains && intent.action_chains.length > 0) {
-        sections.push(`## Detected Patterns\n${intent.action_chains.map(c => `- ${c.name}: ${c.description}`).join('\n')}`);
-    }
-    if (intent.intents && intent.intents.length > 0) {
-        sections.push(`## User Intents\n${intent.intents.map(i => `- ${i.name}: ${i.description}`).join('\n')}`);
-    }
-    if (intent.entities && intent.entities.length > 0) {
-        sections.push(`## Entities to Extract\n${intent.entities.map(e => `- ${e.name}: ${e.type}`).join('\n')}`);
-    }
-    if (intent.data_sources && intent.data_sources.length > 0) {
-        sections.push(`## Data Sources\n${intent.data_sources.map(d => `- ${d.type}${d.instructions ? `: ${d.instructions}` : ''}`).join('\n')}`);
-    }
-    if (intent.constraints) {
-        const constraints = [];
-        if (intent.constraints.require_hitl)
-            constraints.push('- Require human approval before side effects');
-        if (intent.constraints.require_validation)
-            constraints.push('- Require validation before actions');
-        if (intent.constraints.enable_web_search)
-            constraints.push('- Enable web search');
-        if (constraints.length > 0) {
-            sections.push(`## Constraints\n${constraints.join('\n')}`);
-        }
-    }
-    sections.push('\nGenerate a WorkflowSpec JSON that implements this workflow.');
-    return sections.join('\n\n');
-}
-/**
- * Parse LLM response into WorkflowSpec.
- * Handles markdown code blocks and validates structure.
- */
-export function parseWorkflowSpecFromLLM(llmResponse) {
-    try {
-        // Extract JSON from markdown code block if present
-        let json = llmResponse;
-        const codeBlockMatch = llmResponse.match(/```(?:json)?\s*([\s\S]*?)```/);
-        if (codeBlockMatch) {
-            json = codeBlockMatch[1];
-        }
-        const parsed = JSON.parse(json.trim());
-        // Basic validation
-        if (!parsed.nodes || !Array.isArray(parsed.nodes)) {
-            return null;
-        }
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}