@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/mcp/knowledge.js

@@ -69,7 +69,7 @@ export const PLATFORM_CONCEPTS = [
         definition: "Human-in-the-Loop. An approval/verification step where a human reviews before the workflow continues.",
         aliases: ["Human Collaboration", "Approval Step", "Review Step"],
         relatedTerms: ["entity_extraction_with_documents", "send_email_agent"],
-        commonConfusions: "HITL is ONLY supported on entity_extraction_with_documents and send_email_agent. general_hitl is NOT deployable. external_action_caller does NOT support HITL.",
+        commonConfusions: "Two HITL mechanisms: 1) general_hitl (Human Collaboration Agent) — standalone node with Conversational, Standard Form, and Custom Form modes. 2) Agent-level flags on entity_extraction_with_documents and send_email_agent (disable_human_interaction: false). external_action_caller does NOT support HITL.",
     },
     {
         term: "Connector",
@@ -155,7 +155,7 @@ const CURATED_OVERRIDES = [
     { sourceType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", targetType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", compatible: false, note: "Cannot convert text to conversation" },
     { sourceType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", targetType: "WELL_KNOWN_TYPE_SEARCH_RESULT", compatible: false, note: "Text is not a search result" },
     // Search result → other types
-    { sourceType: "WELL_KNOWN_TYPE_SEARCH_RESULT", targetType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", compatible: false, note: "Use respond_for_external_actions or call_llm.named_inputs" },
+    { sourceType: "WELL_KNOWN_TYPE_SEARCH_RESULT", targetType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", compatible: false, note: "Use call_llm.named_inputs, respond_with_sources.search_results, or any node accepting ANY" },
     { sourceType: "WELL_KNOWN_TYPE_SEARCH_RESULT", targetType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", compatible: false, note: "Search result is not a conversation" },
     // Document → other types
     { sourceType: "WELL_KNOWN_TYPE_DOCUMENT", targetType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", compatible: false, note: "Use entity_extraction or document-specific agents" },
@@ -166,359 +166,9 @@ export const TYPE_COMPATIBILITY = [
     ...CURATED_OVERRIDES,
 ];
 // ─────────────────────────────────────────────────────────────────────────────
-// Workflow Patterns
+// Workflow Patterns — SINGLE SOURCE OF TRUTH in src/config/workflow-patterns.ts
 // ─────────────────────────────────────────────────────────────────────────────
-export const WORKFLOW_PATTERNS = [
-    {
-        name: "simple-kb-search",
-        personaType: "chat",
-        description: "Basic knowledge base Q&A with search and response",
-        nodes: ["chat_trigger", "conversation_to_search_query", "search", "respond_for_external_actions"],
-        connections: [
-            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
-            "conversation_to_search_query.summarized_conversation → search.query",
-            "search.search_results → respond_for_external_actions.external_action_result",
-            "chat_trigger.user_query → respond_for_external_actions.query",
-            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
-            "respond_for_external_actions.response → WORKFLOW_OUTPUT",
-        ],
-        useCase: "FAQ bot, documentation assistant, policy lookup",
-        antiPatterns: [
-            "Using call_llm instead of respond_for_external_actions (loses citation and conversation awareness)",
-            "Connecting chat_conversation directly to search.query (type mismatch — use conversation_to_search_query)",
-            "Forgetting to upload data sources to the persona (search returns empty results)",
-        ],
-    },
-    {
-        name: "intent-routing",
-        personaType: "chat",
-        description: "Route conversations to different handlers based on intent classification",
-        nodes: ["chat_trigger", "chat_categorizer", "handler_per_category", "fallback_response"],
-        connections: [
-            "chat_trigger.chat_conversation → chat_categorizer.conversation",
-            "handler_1 (runIf: categorizer.category == Category1)",
-            "handler_2 (runIf: categorizer.category == Category2)",
-            "fallback_response (runIf: categorizer.category == Fallback)",
-            "handler_*.response → WORKFLOW_OUTPUT",
-            "fallback_response.response → WORKFLOW_OUTPUT",
-        ],
-        useCase: "Multi-purpose assistant with distinct capabilities (HR + IT + General)",
-        antiPatterns: [
-            "Missing Fallback category",
-            "Categories without outgoing edges",
-            "Not all paths leading to WORKFLOW_OUTPUT",
-            "Only one gated respond node wired to WORKFLOW_OUTPUT while others are silently lost",
-            "Duplicate identical call_llm nodes differing only by trigger_when — consolidate into one with category as named_input",
-        ],
-    },
-    {
-        name: "multi-source-search",
-        personaType: "chat",
-        description: "Combine local and web search for comprehensive answers",
-        nodes: ["chat_trigger", "conversation_to_search_query", "search", "live_web_search", "combine_search_results", "respond_for_external_actions"],
-        connections: [
-            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
-            "conversation_to_search_query.summarized_conversation → search.query",
-            "conversation_to_search_query.summarized_conversation → live_web_search.query",
-            "search.search_results → combine_search_results.search_results_1",
-            "live_web_search.web_search_results → combine_search_results.search_results_2",
-            "combine_search_results.combined_results → respond_for_external_actions.external_action_result",
-            "chat_trigger.user_query → respond_for_external_actions.query",
-            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
-            "respond_for_external_actions.response → WORKFLOW_OUTPUT",
-        ],
-        useCase: "Research assistant needing both internal docs and current web info",
-        antiPatterns: [
-            "Using web search as the primary/only data source (slower, less reliable, uncontrolled content)",
-            "Not wiring combine_search_results.combined_results to response node (combined results go unused)",
-            "Forgetting to upload internal KB documents (search returns empty, only web results used)",
-        ],
-    },
-    {
-        name: "tool-calling",
-        personaType: "voice",
-        description: "Voice AI that calls external tools (ServiceNow, Salesforce, CRM)",
-        nodes: ["chat_trigger", "chat_categorizer", "external_action_caller", "call_llm"],
-        connections: [
-            "chat_trigger.chat_conversation → chat_categorizer.conversation",
-            "external_action_caller (runIf: categorizer.category == <Action>)",
-            "chat_trigger.chat_conversation → external_action_caller.conversation",
-            "external_action_caller.tool_execution_result → call_llm.named_inputs_Tool_Result",
-            "chat_trigger.user_query → call_llm.query",
-            "call_llm.response_with_sources → WORKFLOW_OUTPUT",
-        ],
-        useCase: "IT helpdesk, customer service with ticketing, CRM operations",
-        antiPatterns: [
-            "Creating duplicate records on follow-up questions",
-            "Not checking conversation history before actions",
-            "Forgetting voice-specific widgets (conversationSettings, voiceSettings, callSettings, vadSettings)",
-            "external_action_caller does NOT support HITL — cannot gate tool calls with human approval",
-        ],
-    },
-    {
-        name: "hitl-approval",
-        personaType: "chat",
-        description: "Human-in-the-loop approval — enable HITL flag on send_email_agent or entity_extraction_with_documents (only nodes that support HITL)",
-        nodes: ["chat_trigger", "entity_extraction_with_documents", "send_email_agent", "respond_for_external_actions"],
-        connections: [
-            "chat_trigger.user_query → entity_extraction_with_documents.query",
-            "chat_trigger.chat_conversation → entity_extraction_with_documents.conversation",
-            "entity_extraction_with_documents.extraction_columns → send_email_agent (HITL flag enabled: disable_human_interaction: false)",
-            "send_email_agent.confirmation → respond_for_external_actions.external_action_result",
-            "chat_trigger.user_query → respond_for_external_actions.query",
-            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
-            "respond_for_external_actions.response → WORKFLOW_OUTPUT",
-        ],
-        useCase: "High-value transactions, sensitive operations — enable HITL flag on send_email_agent or entity_extraction_with_documents",
-        antiPatterns: [
-            "Adding general_hitl as a standalone node (it is NOT deployable)",
-            "Not wiring conversation context to response node",
-            "Using external_action_caller for HITL — it does NOT support the HITL flag",
-            "Only send_email_agent and entity_extraction_with_documents support HITL (disable_human_interaction: false)",
-        ],
-    },
-    {
-        name: "document-processing",
-        personaType: "dashboard",
-        description: "Document upload → extraction → validation → analysis (results as dashboard columns)",
-        nodes: ["document_trigger", "entity_extraction_with_documents", "rule_validation_with_documents", "call_llm"],
-        connections: [
-            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
-            "entity_extraction_with_documents.extraction_columns → rule_validation_with_documents.map_of_extracted_columns",
-            "workflowInput.document-mmf2 → rule_validation_with_documents.primary_docs",
-            "rule_validation_with_documents.ruleset_output → call_llm.named_inputs_Validation_Results",
-            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
-            "rule_validation_with_documents.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
-            "call_llm.llm_output → results (dot-notation: '<nodeId>.llm_output')",
-        ],
-        useCase: "Invoice processing, contract analysis, compliance checking",
-        antiPatterns: [
-            "Not mapping extraction/validation outputs to results (dashboard columns won't appear)",
-            "Missing primary_docs on rule_validation_with_documents (validator needs original documents for context)",
-            "Using a single call_llm without passing validation results (analysis lacks validation context)",
-        ],
-    },
-    {
-        name: "dashboard-email-notification",
-        personaType: "dashboard",
-        description: "Document upload → extraction → email notification (with intermediary for type conversion). Production workflows often add a body generator (call_llm/custom_agent) and dual send paths (auto + HITL) with CC config.",
-        nodes: ["document_trigger", "entity_extraction_with_documents", "json_mapper", "fixed_response", "call_llm (body generator)", "send_email_agent"],
-        connections: [
-            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
-            "entity_extraction_with_documents.extraction_columns → json_mapper.input_json",
-            "json_mapper.output_json → fixed_response.named_inputs_Extracted_Data (template: '{{to}}', '{{subject}}', etc.)",
-            "fixed_response.response → send_email_agent.email_to (one fixed_response per email field)",
-            "entity_extraction_with_documents.extraction_columns → call_llm.named_inputs_Extracted_Data (for body generation)",
-            "call_llm.llm_output → send_email_agent.email_body (LLM-generated body)",
-            "send_email_agent.confirmation → results (dot-notation: '<nodeId>.confirmation')",
-            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
-        ],
-        useCase: "Invoice receipt notification, contract alerts, document-triggered emails, payment confirmations",
-        antiPatterns: [
-            "DO NOT wire entity_extraction directly to send_email — type mismatch (ANY vs TEXT_WITH_SOURCES)",
-            "Use json_mapper + fixed_response as intermediary for type conversion",
-            "Enable HITL flag on send_email_agent (disable_human_interaction: false) if approval needed",
-            "For CC/BCC: extract additional recipients via entity_extraction columns, route through separate fixed_response nodes",
-        ],
-    },
-    {
-        name: "guardrails-pattern",
-        personaType: "chat",
-        description: "Response generation with validation guardrails",
-        nodes: ["chat_trigger", "search", "respond_for_external_actions", "response_validator", "abstain_action"],
-        connections: [
-            "chat_trigger.user_query → search.query",
-            "search.search_results → respond_for_external_actions.external_action_result",
-            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
-            "respond_for_external_actions.response → response_validator.response_to_validate",
-            "chat_trigger.user_query → response_validator.reference_query",
-            "response_validator.abstain_reason → [conditional: if valid] → WORKFLOW_OUTPUT",
-            "response_validator.abstain_reason → [conditional: if invalid] → abstain_action → WORKFLOW_OUTPUT",
-        ],
-        useCase: "Regulated industries, compliance-sensitive responses",
-        antiPatterns: [
-            "Not connecting both response and abstain paths to WORKFLOW_OUTPUT",
-            "Using guardrails without search results (validator has nothing to check against)",
-            "Skipping the abstain_action fallback (invalid responses return nothing to user)",
-        ],
-    },
-    {
-        name: "externalized-instructions",
-        personaType: "chat",
-        description: "Dynamic instructions fetched from knowledge base instead of hardcoded in node prompts. Upload instruction documents (policies, tone guides, procedures) to KB and let search retrieve them at runtime.",
-        nodes: ["chat_trigger", "conversation_to_search_query", "search", "respond_for_external_actions"],
-        connections: [
-            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
-            "conversation_to_search_query.summarized_conversation → search.query",
-            "search.search_results → respond_for_external_actions.external_action_result (instructions + knowledge combined)",
-            "chat_trigger.user_query → respond_for_external_actions.query",
-            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
-            "respond_for_external_actions.response → WORKFLOW_OUTPUT",
-        ],
-        useCase: "When instructions change frequently, when multiple teams maintain different policies, when A/B testing response styles",
-        antiPatterns: [
-            "Hardcoding all instructions in node prompt (requires workflow redeploy to change behavior)",
-            "Not connecting search results to extraction nodes that also need instructions",
-            "Mixing instruction documents with knowledge documents without clear separation",
-        ],
-    },
-    {
-        name: "consolidated-intent-routing",
-        personaType: "chat",
-        description: "Single respond node handles all intents by receiving the category as a named_input. Reduces duplication vs. having separate respond nodes per intent.",
-        nodes: ["chat_trigger", "chat_categorizer", "search", "call_llm", "fixed_response"],
-        connections: [
-            "chat_trigger.chat_conversation → chat_categorizer.conversation",
-            "chat_trigger.user_query → search.query (always runs, not gated)",
-            "chat_categorizer.category → call_llm.named_inputs_Intent",
-            "search.search_results → call_llm.named_inputs_Search_Results",
-            "chat_trigger.chat_conversation → call_llm.named_inputs_Conversation",
-            "chat_trigger.user_query → call_llm.query",
-            "call_llm.response_with_sources → WORKFLOW_OUTPUT (runIf: category != Fallback)",
-            "fixed_response.response → WORKFLOW_OUTPUT (runIf: category == Fallback)",
-        ],
-        useCase: "Multi-intent assistant where all intents share similar response style, search sources, and safety constraints",
-        antiPatterns: [
-            "Using this when intents need different tools or actions (use separate nodes instead)",
-            "Forgetting to pass the category as named_input (LLM won't know which intent to address)",
-            "Not gating fallback separately (fixed_response should handle fallback, not the LLM)",
-        ],
-    },
-    // ─── Composite Dashboard Patterns (from FX2 production analysis) ──────────
-    {
-        name: "multi-phase-validation",
-        personaType: "dashboard",
-        description: "Document upload → extraction → N sequential rule_validation_with_documents phases. Each phase checks a different concern (format → compliance → cross-reference) and feeds its output to the next. All phase outputs mapped to dashboard columns for per-phase visibility.",
-        nodes: ["document_trigger", "entity_extraction_with_documents", "rule_validation_phase_1", "rule_validation_phase_2", "rule_validation_phase_3", "call_llm"],
-        connections: [
-            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
-            "entity_extraction_with_documents.extraction_columns → rule_validation_phase_1.map_of_extracted_columns",
-            "workflowInput.document-mmf2 → rule_validation_phase_1.primary_docs",
-            "rule_validation_phase_1.ruleset_output → rule_validation_phase_2.map_of_extracted_columns",
-            "workflowInput.document-mmf2 → rule_validation_phase_2.primary_docs",
-            "rule_validation_phase_2.ruleset_output → rule_validation_phase_3.map_of_extracted_columns",
-            "workflowInput.document-mmf2 → rule_validation_phase_3.primary_docs",
-            "rule_validation_phase_3.ruleset_output → call_llm.named_inputs_Final_Validation",
-            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
-            "rule_validation_phase_1.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
-            "rule_validation_phase_2.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
-            "rule_validation_phase_3.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
-            "call_llm.llm_output → results (dot-notation: '<nodeId>.llm_output')",
-        ],
-        useCase: "Invoice processing with multi-step validation (format → compliance → PO matching), regulatory document review, dunning letter compliance checks",
-        antiPatterns: [
-            "Running all validation rules in a single phase (loses granularity, hard to debug which phase failed)",
-            "Not passing primary_docs to each validation phase (validator needs original documents for context)",
-            "Forgetting to map intermediate phase outputs to results (dashboard won't show per-phase status)",
-        ],
-    },
-    {
-        name: "confidence-dual-path",
-        personaType: "dashboard",
-        description: "Dashboard: after extraction and validation, fork into AUTO path (send_email_agent without HITL) and ESCALATE path (send_email_agent with HITL enabled). A confidence/risk score from validation determines which path fires via runIf conditions.",
-        nodes: ["document_trigger", "entity_extraction_with_documents", "rule_validation_with_documents", "call_llm (confidence scorer)", "send_email_auto (no HITL)", "send_email_escalate (HITL enabled)"],
-        connections: [
-            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
-            "entity_extraction_with_documents.extraction_columns → rule_validation_with_documents.map_of_extracted_columns",
-            "workflowInput.document-mmf2 → rule_validation_with_documents.primary_docs",
-            "rule_validation_with_documents.ruleset_output → call_llm.named_inputs_Validation_Results",
-            "call_llm.llm_output → send_email_auto (runIf: validation_status == PASS)",
-            "call_llm.llm_output → send_email_escalate (runIf: validation_status != PASS)",
-            "send_email_auto.confirmation → results (dot-notation: '<nodeId>.confirmation')",
-            "send_email_escalate.confirmation → results (dot-notation: '<nodeId>.confirmation')",
-            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
-            "rule_validation_with_documents.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
-        ],
-        useCase: "AP invoice processing (clean invoices auto-process, exceptions need human review), dunning workflows (high-confidence auto-send, ambiguous escalate), contract approvals",
-        antiPatterns: [
-            "Using a single send_email_agent for both paths (loses ability to gate high-risk sends separately)",
-            "Not having the ESCALATE path (all documents auto-process with no human oversight for edge cases)",
-            "Hardcoding threshold in node config — use validation rules output to drive the routing decision",
-            "Forgetting to use intermediary (json_mapper + fixed_response) between extraction and send_email inputs",
-        ],
-    },
-    {
-        name: "document-intake-resolution",
-        personaType: "dashboard",
-        description: "Dashboard: full document intake pipeline — extract entities → convert/normalize → search knowledge base for matching records → LLM resolves/reconciles against master data. The resolution chain ensures extracted entities are validated against existing records before downstream processing.",
-        nodes: ["document_trigger", "entity_extraction_with_documents", "json_mapper", "search", "call_llm (resolver)"],
-        connections: [
-            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
-            "entity_extraction_with_documents.extraction_columns → json_mapper.input_json",
-            "json_mapper.output_json → search.query (lookup extracted entity in KB)",
-            "search.search_results → call_llm.named_inputs_Matching_Records",
-            "entity_extraction_with_documents.extraction_columns → call_llm.named_inputs_Extracted_Data",
-            "call_llm.llm_output → results (dot-notation: '<nodeId>.llm_output' — resolution status + matched record)",
-            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
-        ],
-        useCase: "Invoice vendor matching against vendor master, contract party resolution, employee onboarding verification against HR records, PO line-item matching",
-        antiPatterns: [
-            "Skipping the search/resolution step (extracted data goes unvalidated against master data)",
-            "Using entity_extraction output directly as the resolved entity (extraction ≠ resolution)",
-            "Not handling 'no match found' case in the resolver LLM (must surface unresolved items)",
-        ],
-    },
-    {
-        name: "hitl-decision-form",
-        personaType: "dashboard",
-        description: "Dashboard: use entity_extraction_with_documents with HITL flag as a human review/decision form — presenting processed data for human verification or correction before downstream actions. The extraction columns define the form fields the reviewer sees and can modify.",
-        nodes: ["document_trigger", "entity_extraction_with_documents (processing)", "call_llm (prepare review)", "entity_extraction_with_documents (HITL review form)", "send_email_agent"],
-        connections: [
-            "workflowInput.document-mmf2 → entity_extraction_processing.documents",
-            "entity_extraction_processing.extraction_columns → call_llm.named_inputs_Extracted_Data",
-            "call_llm.llm_output → entity_extraction_review.named_inputs_Summary (HITL enabled)",
-            "entity_extraction_review.extraction_columns → send_email_agent (human-verified data)",
-            "entity_extraction_review.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
-        ],
-        useCase: "Invoice approval where reviewer corrects extracted amounts before payment, contract review where legal team verifies extracted terms, compliance review with sign-off",
-        antiPatterns: [
-            "Using general_hitl (NOT deployable) — use HITL flag on entity_extraction_with_documents",
-            "Confusing extraction-for-processing with extraction-as-review-form (different roles, different column configs)",
-            "Not passing processed data to the review form's named_inputs (reviewer sees empty form)",
-        ],
-    },
-    {
-        name: "document-generation-pipeline",
-        personaType: "dashboard",
-        description: "Dashboard: generate formatted documents from processed data — extraction → LLM drafts content → generate_document creates formatted output (PDF) → send_email_agent delivers as attachment.",
-        nodes: ["document_trigger", "entity_extraction_with_documents", "call_llm (content drafter)", "generate_document", "send_email_agent"],
-        connections: [
-            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
-            "entity_extraction_with_documents.extraction_columns → call_llm.named_inputs_Extracted_Data",
-            "call_llm.llm_output → generate_document.markdown_file_contents",
-            "generate_document.document_link → send_email_agent.named_inputs_Attachment",
-            "send_email_agent.confirmation → results (dot-notation: '<nodeId>.confirmation')",
-            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
-        ],
-        useCase: "Dunning letter generation, invoice creation from PO data, compliance report generation, customer correspondence, welcome packets",
-        antiPatterns: [
-            "Putting the full template in call_llm instructions (use data source templates for strict regulatory formats)",
-            "Skipping generate_document and sending raw LLM text as attachment (no formatting, no PDF)",
-            "Not including extracted entity data in the LLM's named_inputs (generated document lacks specifics)",
-        ],
-    },
-    // ─── Voice Patterns ──────────────────────────────────────────────────────
-    {
-        name: "voice-kb-search",
-        personaType: "voice",
-        description: "Voice AI with knowledge base search only — no external actions or side effects. Clean 4-node pattern for informational help desks. Requires voice-specific widgets.",
-        nodes: ["chat_trigger", "conversation_to_search_query", "search", "respond_for_external_actions"],
-        connections: [
-            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
-            "conversation_to_search_query.summarized_conversation → search.query",
-            "search.search_results → respond_for_external_actions.external_action_result",
-            "chat_trigger.user_query → respond_for_external_actions.query",
-            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
-            "respond_for_external_actions.response → WORKFLOW_OUTPUT",
-        ],
-        useCase: "FX rate inquiries, policy Q&A hotline, product information line, internal help desk for common questions",
-        antiPatterns: [
-            "Adding external_action_caller when no side effects are needed (over-engineering)",
-            "Using call_llm instead of respond_for_external_actions (loses citation and conversation awareness)",
-            "Forgetting voice-specific widgets (conversationSettings, voiceSettings, callSettings, vadSettings)",
-        ],
-    },
-];
+export { WORKFLOW_PATTERNS } from "../config/workflow-patterns.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Qualifying Questions
 // ─────────────────────────────────────────────────────────────────────────────
@@ -532,7 +182,7 @@ export const QUALIFYING_QUESTIONS = [
     // Round 2: Workflow Details
     { category: "Data", question: "Are the data sources static files or live APIs?", whyItMatters: "Static = search agent, Live = external_action_caller", required: false },
     { category: "Data", question: "What specific fields/entities need to be extracted from queries?", whyItMatters: "May need entity_extraction or conversation_to_search_query", required: false },
-    { category: "Data", question: "Are there multiple data sources that need to be correlated?", whyItMatters: "Requires cross-document linking strategy and combine_search_results", required: false },
+    { category: "Data", question: "Are there multiple data sources that need to be correlated?", whyItMatters: "Requires cross-document linking strategy — use combine_and_rerank_search_results or call_llm with multiple named_inputs", required: false },
     { category: "Actions", question: "What external tools/APIs should the AI call? (ServiceNow, Salesforce, Workday, etc.)", whyItMatters: "Configures external_action_caller tools and connectors", required: false },
     { category: "Actions", question: "What actions can the AI perform? (create ticket, send email, update record)", whyItMatters: "Lists available tools and determines action scope", required: false },
     { category: "Actions", question: "Which actions require human approval?", whyItMatters: "Enable HITL flag on the relevant agent (only entity_extraction_with_documents and send_email_agent support HITL)", required: false },
@@ -578,9 +228,9 @@ export const COMMON_MISTAKES = [
     { mistake: "Type mismatches in connections", problem: "Validation errors, runtime failures", solution: "Check type compatibility: use conversation_to_search_query when needed" },
     { mistake: "Not mapping to WORKFLOW_OUTPUT", problem: "Responses don't reach user", solution: "Ensure ALL paths terminate at WORKFLOW_OUTPUT" },
     { mistake: "Using workflow_def instead of workflow in updates", problem: "API accepts request but changes silently don't persist", solution: "Use 'workflow' field (not 'workflow_def') in updateAiEmployee(). GET returns workflow_def, UPDATE expects workflow." },
-    { mistake: "Chat workflow without chat-aware response node", problem: "Duplicate/repetitive responses — LLM re-asks questions already answered, loses multi-turn context", solution: "Use respond_for_external_actions (for search results or tool results) instead of generic call_llm. If using call_llm, wire chat_conversation into named_inputs." },
+    { mistake: "Chat workflow without chat-aware response node", problem: "Duplicate/repetitive responses — LLM re-asks questions already answered, loses multi-turn context", solution: "Wire chat_conversation into the response node's named_inputs (e.g., call_llm.named_inputs_Conversation) so the LLM has multi-turn context. respond_for_external_actions is only for external_action_caller results." },
     { mistake: "Wiring entity_extraction directly to send_email inputs", problem: "Type mismatch — entity_extraction outputs ANY type, email inputs need TEXT_WITH_SOURCES. Results in corrupted email addresses or deploy errors.", solution: "Use intermediary: entity_extraction → json_mapper → fixed_response({{field}}) → send_email. Or use custom_agent with output_fields=[To,Subject,Body]." },
-    { mistake: "Adding general_hitl as a standalone workflow node", problem: "general_hitl is NOT deployable — it appears in catalogs but cannot be deployed. Deploying it will fail.", solution: "Enable the HITL flag on the agent that performs the action. Only entity_extraction_with_documents and send_email_agent support HITL (disable_human_interaction: false). external_action_caller does NOT support HITL." },
+    { mistake: "Adding general_hitl without understanding its modes", problem: "general_hitl (Human Collaboration Agent) is a full standalone agent with Conversational, Standard Form, and Custom Form modes — not just an approval gate.", solution: "For rich human-in-the-loop: use general_hitl with appropriate mode. For simple yes/no approval on specific actions: enable the HITL flag on send_email_agent or entity_extraction_with_documents (disable_human_interaction: false)." },
 ];
 export const DEBUG_CHECKLIST = [
     { step: 1, action: "Check Status", description: "Is the AI Employee active/ready?", apiField: "status" },

package/dist/mcp/prompts.js

@@ -1035,7 +1035,7 @@ Fetch \`ema://rules/deprecated-actions-summary\` to know which actions to AVOID.
 
 **Key deprecated actions to avoid:**
 - search/v0 → use search/v2 (requires datastore_configs)
-- respond_with_sources → use respond_for_external_actions
+- respond_with_sources/v0 → use call_llm with named_inputs (for KB Q&A) or respond_with_sources current version
 - call_llm/v0 → use call_llm/v2
 - web_search/v0 → use live_web_search or ai_web_search
 
@@ -1126,7 +1126,7 @@ Fetch \`ema://rules/deprecated-actions-summary\` to know which actions to AVOID.
 
 **Key deprecated actions to avoid:**
 - search/v0 → use search/v2 (requires datastore_configs)
-- respond_with_sources → use respond_for_external_actions
+- respond_with_sources/v0 → use call_llm with named_inputs (for KB Q&A) or respond_with_sources current version
 - call_llm/v0 → use call_llm/v2
 - web_search/v0 → use live_web_search or ai_web_search
 
@@ -1493,7 +1493,7 @@ document_trigger → entity_extraction/call_llm → WORKFLOW_OUTPUT
 **Trigger**: Use \`chat_trigger\`
 **Common Pattern**:
 \`\`\`
-chat_trigger → search/v2 → respond_for_external_actions → WORKFLOW_OUTPUT
+chat_trigger → search/v2 → call_llm (via named_inputs_Search_Results) → WORKFLOW_OUTPUT
 \`\`\`
 
 **Key inputs from trigger**:
@@ -1873,7 +1873,7 @@ Common agents for extensions:
 - **entity_extraction_with_documents**: Extract structured data
 - **json_mapper**: Transform data structures
 - **live_web_search**: Real-time data
-- **combine_search_results**: Merge multiple sources
+- **combine_and_rerank_search_results**: Merge and rerank multiple sources
 - **personalized_content_generator**: Rich content generation
 - **custom_agent**: Complex logic with custom prompts
 - **send_email_agent**: Email notifications
@@ -1968,7 +1968,7 @@ trigger → entity_extraction_with_documents → json_mapper → downstream_node
 trigger → [parallel]
           ├→ search(kb)
           └→ live_web_search
-          combine_search_results → respond
+          combine_and_rerank_search_results → call_llm
 \`\`\`
 
 ### Pattern: Add Email Notification