@ema.co/mcp-toolkit 0.2.0

package/dist/sdk/workflow-intent.js

@@ -0,0 +1,1585 @@
+/**
+ * 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
+// ─────────────────────────────────────────────────────────────────────────────
+const INTENT_PATTERNS = [
+    { pattern: /password\s*reset/i, name: "Password Reset", handler: "llm" },
+    { pattern: /billing|payment|invoice/i, name: "Billing", handler: "search" },
+    { pattern: /technical|support|help/i, name: "Technical Support", handler: "search" },
+    { pattern: /schedule|appointment|book/i, name: "Scheduling", handler: "tool" },
+    { pattern: /ticket|incident|request/i, name: "Ticket Creation", handler: "tool" },
+    { pattern: /status|check|lookup/i, name: "Status Check", handler: "search" },
+];
+const TOOL_PATTERNS = [
+    { pattern: /servicenow/i, namespace: "service_now", action: "Create_Incident" },
+    { pattern: /salesforce/i, namespace: "salesforce", action: "Create_Case" },
+    { pattern: /jira/i, namespace: "jira", action: "Create_Issue" },
+    { pattern: /slack/i, namespace: "slack", action: "Send_Message" },
+    { pattern: /email/i, namespace: "email", action: "Send_Email" },
+    { pattern: /calendar|schedule/i, namespace: "calendar", action: "Check_Availability" },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// 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",
+                },
+            },
+        ],
+    },
+];
+/**
+ * Type compatibility rules - what outputs can connect to what inputs
+ */
+export const TYPE_COMPATIBILITY = {
+    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);
+}
+const PERSONA_TYPE_PATTERNS = [
+    { pattern: /voice|call|phone/i, type: "voice" },
+    { pattern: /document|batch|upload/i, type: "dashboard" },
+];
+export function parseNaturalLanguage(text) {
+    // Detect persona type (default: chat)
+    let personaType = "chat";
+    for (const { pattern, type } of PERSONA_TYPE_PATTERNS) {
+        if (pattern.test(text)) {
+            personaType = type;
+            break;
+        }
+    }
+    // Detect intents
+    const intents = [];
+    const seenIntents = new Set();
+    for (const { pattern, name, handler } of INTENT_PATTERNS) {
+        if (pattern.test(text) && !seenIntents.has(name)) {
+            seenIntents.add(name);
+            intents.push({
+                name,
+                description: `User requests ${name.toLowerCase()}`,
+                handler,
+            });
+        }
+    }
+    // Detect tools
+    const tools = [];
+    for (const { pattern, namespace, action } of TOOL_PATTERNS) {
+        if (pattern.test(text)) {
+            tools.push({ namespace, action });
+        }
+    }
+    // Detect data sources
+    const dataSources = [];
+    if (/search|knowledge|faq|document|lookup|kb/i.test(text)) {
+        dataSources.push({ type: "knowledge_base" });
+    }
+    if (/web|internet|online|live/i.test(text)) {
+        dataSources.push({ type: "web_search" });
+    }
+    if (dataSources.length === 0) {
+        // Default to KB search for most use cases
+        dataSources.push({ type: "knowledge_base" });
+    }
+    // Detect constraints
+    const constraints = {};
+    if (/approv|human|review|escalat|hitl/i.test(text)) {
+        constraints.require_hitl = true;
+    }
+    if (/validat|check|verify/i.test(text)) {
+        constraints.require_validation = true;
+    }
+    // Detect action chains - end-to-end semantic flows
+    const actionChains = detectActionChains(text);
+    // Detect entities to extract
+    const entities = detectEntities(text);
+    // Detect delivery configuration
+    const deliveryConfig = detectDeliveryConfig(text);
+    // 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,
+        intents: intents.length > 0 ? intents : undefined,
+        tools: tools.length > 0 ? tools : undefined,
+        data_sources: dataSources,
+        constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
+        action_chains: actionChains.length > 0 ? actionChains : undefined,
+        entities: entities.length > 0 ? entities : undefined,
+        delivery_config: deliveryConfig,
+    };
+}
+/**
+ * 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
+// ─────────────────────────────────────────────────────────────────────────────
+export function intentToSpec(intent) {
+    const nodes = [];
+    const resultMappings = [];
+    // 1. Add trigger
+    const triggerId = "trigger";
+    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",
+                },
+            },
+        });
+    }
+    // 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
+    let toolCallerId;
+    if (intent.tools && intent.tools.length > 0) {
+        toolCallerId = "tool_caller";
+        nodes.push({
+            id: toolCallerId,
+            actionType: "external_action_caller",
+            displayName: "External Actions",
+            inputs: {
+                conversation: {
+                    type: "action_output",
+                    actionName: triggerId,
+                    output: "chat_conversation",
+                },
+            },
+            tools: intent.tools.map((t) => ({
+                name: t.action,
+                namespace: t.namespace,
+            })),
+        });
+    }
+    // 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",
+        },
+    };
+    if (searchId) {
+        respondInputs.search_results = {
+            type: "action_output",
+            actionName: searchId,
+            output: "search_results",
+        };
+    }
+    nodes.push({
+        id: respondId,
+        actionType: searchId ? "respond_with_sources" : "call_llm",
+        displayName: "Response",
+        inputs: respondInputs,
+    });
+    resultMappings.push({
+        nodeId: respondId,
+        output: searchId ? "response_with_sources" : "response_with_sources",
+    });
+    return {
+        name: intent.name,
+        description: intent.description,
+        personaType: intent.persona_type,
+        nodes,
+        resultMappings,
+    };
+}
+export function parseInput(input) {
+    const inputType = detectInputType(input);
+    let intent;
+    switch (inputType) {
+        case "natural_language":
+            intent = parseNaturalLanguage(String(input));
+            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");
+}