@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/sdk/generated/agent-catalog.js

@@ -1,10 +1,18 @@
 /**
- * Agent Catalog — Auto-Generated API Fallback
+ * Agent Catalog — API Fallback + Enrichments
  *
- * This is the AGENT_CATALOG array extracted from knowledge.ts.
- * Used as a fallback when the API is unavailable.
+ * SINGLE SOURCE OF TRUTH for action definitions used when API is unavailable.
+ * Enriched with `tier` and `aliases` for guidance quality.
+ *
+ * Tier definitions:
+ * - core: Production-proven, actively recommended
+ * - standard: Available, use when intent calls for it
+ * - specialized: Domain-specific verticals
+ * - experimental: Minimal/zero production usage
+ *
+ * IMPORTANT: respond_for_external_actions is ONLY for external_action_caller results.
+ * For KB Q&A after search, use call_llm with named_inputs (89% of production personas).
  *
- * Generated from source repos via scheduled workflows.
  * See: .context/core/guides/source-repos.md for full architecture
  */
 export const AGENT_CATALOG = [
@@ -24,6 +32,8 @@ export const AGENT_CATALOG = [
             "Each user message triggers a NEW workflow execution",
             "chat_conversation accumulates; user_query is current message only",
         ],
+        tier: "core",
+        aliases: ["Chat Entry Point"],
     },
     {
         actionName: "document_trigger",
@@ -35,6 +45,8 @@ export const AGENT_CATALOG = [
             { name: "user_query", type: "WELL_KNOWN_TYPE_DOCUMENT", description: "Uploaded document(s)" },
         ],
         whenToUse: "When workflow is triggered by document upload for processing/extraction",
+        tier: "core",
+        aliases: ["Document Entry Point", "Upload Trigger"],
     },
     {
         actionName: "voice_trigger",
@@ -47,6 +59,8 @@ export const AGENT_CATALOG = [
             { name: "user_query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Current utterance" },
         ],
         whenToUse: "Voice AI employees handling phone calls",
+        tier: "core",
+        aliases: ["Voice Entry Point", "Phone Call Trigger"],
     },
     // Routing / Classification
     {
@@ -71,6 +85,8 @@ export const AGENT_CATALOG = [
         whenToUse: "When you need to route chat conversations to different processing paths based on intent",
         whenNotToUse: "Simple single-path workflows that don't need routing",
         example: "Categories: [Market_Impact, Client_Lookup, Compliance_Check, Fallback]",
+        tier: "core",
+        aliases: ["Intent Router", "Conversation Classifier"],
     },
     {
         actionName: "text_categorizer",
@@ -87,6 +103,8 @@ export const AGENT_CATALOG = [
             "Same rules as chat_categorizer: must have Fallback, edges for each category",
         ],
         whenToUse: "When routing based on text content rather than full conversation history",
+        tier: "standard",
+        aliases: ["Text Router"],
     },
     {
         actionName: "document_categorizer",
@@ -100,6 +118,8 @@ export const AGENT_CATALOG = [
             { name: "category", type: "WELL_KNOWN_TYPE_ENUM", description: "Document classification" },
         ],
         whenToUse: "When routing based on document type or content",
+        tier: "standard",
+        aliases: ["Document Router"],
     },
     {
         actionName: "conversation_to_search_query",
@@ -118,6 +138,8 @@ export const AGENT_CATALOG = [
             "May still be needed WITH chat_conversation for downstream agents requiring specific format",
             "Use to reduce conversation size due to LLM context window limits",
         ],
+        tier: "standard",
+        aliases: ["Query Refiner", "Conversation to Query"],
     },
     // Search & Retrieval
     {
@@ -135,6 +157,8 @@ export const AGENT_CATALOG = [
         whenToUse: "When searching static uploaded documents or internal knowledge base. Always use search/v2 (not deprecated search/v0).",
         whenNotToUse: "For real-time web content — use live_web_search or ai_web_search instead",
         example: "FAQ lookup, policy search, documentation assistant",
+        tier: "core",
+        aliases: ["Knowledge Search", "KB Lookup", "File Search"],
     },
     {
         actionName: "live_web_search",
@@ -149,27 +173,11 @@ export const AGENT_CATALOG = [
         ],
         whenToUse: "When you need real-time external information not in the knowledge base",
         example: "Current events, live data, external research",
+        tier: "standard",
+        aliases: ["Web Search", "Real-Time Search"],
     },
-    {
-        actionName: "combine_search_results",
-        displayName: "Combine Search Results",
-        category: "search",
-        description: "Merges results from multiple search sources with deduplication.",
-        inputs: [
-            { name: "search_results_1", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", required: true, description: "First result set" },
-            { name: "search_results_2", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", required: true, description: "Second result set" },
-        ],
-        outputs: [
-            { name: "combined_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", description: "Merged, deduplicated results" },
-        ],
-        criticalRules: [
-            "AVOID using unless necessary - prefer combine_and_rerank_search_results or call_llm with named_inputs",
-            "combine_and_rerank_search_results provides intelligent relevance ranking",
-            "call_llm with named_inputs allows prompt-based ranking control",
-        ],
-        whenToUse: "When combining local + web search, or multiple knowledge bases",
-        whenNotToUse: "When you need intelligent ranking - use combine_and_rerank_search_results instead",
-    },
+    // combine_search_results REMOVED — does not exist in the live API.
+    // Use combine_and_rerank_search_results instead.
     {
         actionName: "combine_and_rerank_search_results",
         displayName: "Rerank Search Results",
@@ -183,6 +191,8 @@ export const AGENT_CATALOG = [
             { name: "reranked_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", description: "Reranked results" },
         ],
         whenToUse: "When you need to prioritize results by relevance after combining multiple sources",
+        tier: "standard",
+        aliases: ["Rerank Results", "Result Prioritizer"],
     },
     {
         actionName: "document_metasearch",
@@ -197,6 +207,8 @@ export const AGENT_CATALOG = [
             { name: "document_metasearch_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", description: "Metadata search results" },
         ],
         whenToUse: "When searching by document metadata rather than content",
+        tier: "standard",
+        aliases: ["Metadata Search"],
     },
     // Generation & Response
     {
@@ -222,6 +234,8 @@ export const AGENT_CATALOG = [
         ],
         example: "named_inputs_Market_Context, named_inputs_Client_Data | " +
             "LLM Template prompt: 'Generate structured content with clear ## section headers, organized by themes'",
+        tier: "core",
+        aliases: ["Respond", "LLM Response", "Generate Text"],
     },
     {
         actionName: "generate_document",
@@ -243,6 +257,8 @@ export const AGENT_CATALOG = [
             "Optional: Add CSS/styling in markdown for professional formatting",
         ],
         example: "detailed_content (call_llm) → generate_doc → send_email.named_inputs_Attachment",
+        tier: "standard",
+        aliases: ["Publish Document", "Create PDF"],
     },
     {
         actionName: "respond_with_sources",
@@ -261,6 +277,8 @@ export const AGENT_CATALOG = [
             "Enable use_citation_based_filtering for trust",
             "Implement confidence thresholds for quality control",
         ],
+        tier: "standard",
+        aliases: ["Answer with Citations", "Grounded Response"],
     },
     {
         actionName: "respond_for_external_actions",
@@ -275,6 +293,8 @@ export const AGENT_CATALOG = [
             { name: "response", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Human-friendly explanation" },
         ],
         whenToUse: "After external_action_caller to explain results to user",
+        tier: "standard",
+        aliases: ["Explain Tool Results"],
     },
     {
         actionName: "fixed_response",
@@ -299,6 +319,8 @@ export const AGENT_CATALOG = [
         ],
         example: "Template: 'Dear {{Customer_Name}}, your order {{Order_ID}} has been {{Status}}.' " +
             "→ Connect entity_extraction.customer_name to named_inputs_Customer_Name",
+        tier: "core",
+        aliases: ["Template Response", "Static Response"],
     },
     {
         actionName: "send_email_agent",
@@ -322,6 +344,8 @@ export const AGENT_CATALOG = [
             "Never connect summarized_conversation or search_results directly to email_to",
         ],
         example: "entity_extraction → fixed_response('{{email}}') → send_email.email_to (CORRECT pattern)",
+        tier: "core",
+        aliases: ["Email Sender"],
     },
     // External Actions
     {
@@ -342,6 +366,8 @@ export const AGENT_CATALOG = [
             "external_action_caller does NOT support HITL — only send_email_agent and entity_extraction_with_documents do",
         ],
         example: "ServiceNow ticket creation, Salesforce record update, Email sending",
+        tier: "core",
+        aliases: ["Call API", "Tool Caller", "Intelligent Actions"],
     },
     // Entity & Rule Processing
     {
@@ -362,6 +388,8 @@ export const AGENT_CATALOG = [
         ],
         whenToUse: "When you need structured data extraction for cross-document linking, API calls, or audit trails with citations",
         whenNotToUse: "For simple conversational queries—use LLM resolution instead",
+        tier: "core",
+        aliases: ["Extract Fields", "Data Extraction"],
     },
     {
         actionName: "rule_validation_with_documents",
@@ -376,31 +404,38 @@ export const AGENT_CATALOG = [
             { name: "ruleset_output", type: "WELL_KNOWN_TYPE_ANY", description: "Pass/Fail results per rule with explanations" },
         ],
         whenToUse: "For compliance checks, business rule validation, threshold checking. Rules (e.g., 'Required Fields', 'Data Variance') are defined in the node's UI settings — the LLM only needs to wire inputs/outputs correctly.",
+        tier: "standard",
+        aliases: ["Business Rules", "Compliance Checker"],
     },
     // Human Collaboration
-    // NOTE: general_hitl is NOT a deployable node — it appears in catalogs but cannot be deployed.
-    // HITL is implemented as a FLAG on specific agents: entity_extraction_with_documents and send_email_agent.
-    // Kept here for reference when analyzing existing workflows that may use it.
     {
         actionName: "general_hitl",
-        displayName: "Human Collaboration (NOT RECOMMENDED — use agent flags instead)",
+        displayName: "Human Collaboration Agent",
         category: "collaboration",
-        description: "NOT DEPLOYABLE — general_hitl appears in catalogs but cannot be deployed. HITL approval is a flag on entity_extraction_with_documents and send_email_agent only. Do NOT add general_hitl nodes to workflows.",
+        description: "Pauses workflow to collect human input, then resumes. Supports three modes: Conversational (back-and-forth dialogue with success/failure criteria), Standard Form (structured fields: string, number, boolean, multi-select), and Custom Form (external hosted form via URL). Uses intelligent categorization to detect success, failure, or need for continued conversation.",
         inputs: [
-            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Context for review" },
+            { name: "conversation", type: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", required: true, description: "Chat conversation for ongoing dialogue context" },
+            { name: "named_inputs", type: "WELL_KNOWN_TYPE_ANY", required: false, description: "Flexible inputs from other agents (search results, tool outputs, text, structured data)" },
         ],
         outputs: [
-            { name: "hitl_status_HITL Success", type: "WELL_KNOWN_TYPE_ANY", description: "Human approved path" },
-            { name: "hitl_status_HITL Failure", type: "WELL_KNOWN_TYPE_ANY", description: "Human rejected path" },
+            { name: "human_collaboration_status", type: "WELL_KNOWN_TYPE_ENUM", description: "HITL Success or HITL Failure — use with runIf for branching" },
+            { name: "summarized_conversation", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Summary of the full conversation history" },
         ],
         criticalRules: [
-            "general_hitl is NOT deployable — do NOT add it to any workflow",
-            "If user asks for approval: enable the HITL flag on entity_extraction_with_documents or send_email_agent (only nodes that support HITL)",
-            "external_action_caller does NOT support HITL despite appearing in older guidance",
-            "If you encounter general_hitl in an existing workflow: it may not function correctly",
-        ],
-        whenToUse: "DO NOT USE — general_hitl is not deployable. HITL is a flag on entity_extraction_with_documents and send_email_agent only.",
-        example: "For approval: enable HITL flag on send_email_agent (disable_human_interaction: false)",
+            "Three modes: Conversational (dialogue), Standard Form (structured input), Custom Form (external URL)",
+            "Conversational mode: define success criteria, failure criteria, and instructions for Ema's behavior",
+            "Standard Form mode: define fields (string, number, boolean, multi-select). Output is JSON of submitted values",
+            "Custom Form mode: requires form URL, button label, and display dimensions",
+            "Max exchanges setting prevents infinite loops — defaults to 5. Exceeding max = HITL Failure",
+            "Context window controls how many recent messages the categorizer considers (default: 10)",
+            "Use runIf conditions on downstream nodes to branch on HITL Success vs HITL Failure",
+            "entity_extraction_with_documents and send_email_agent also support HITL via their own flags (disable_human_interaction: false)",
+        ],
+        whenToUse: "Content approval workflows, quality assurance checkpoints, interactive data collection, approval workflows for business decisions",
+        whenNotToUse: "Simple yes/no approval on email sends — use send_email_agent's built-in HITL flag instead",
+        example: "Content approval: success='User approves content', instructions='Present content and ask for feedback', max_exchanges=3",
+        tier: "core",
+        aliases: ["HITL", "Human Review", "Approval Gate", "Human-in-the-Loop"],
     },
     // Validation & Guardrails
     {
@@ -416,6 +451,8 @@ export const AGENT_CATALOG = [
             { name: "abstain_reason", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Reason if validation fails" },
         ],
         whenToUse: "For guardrails, compliance checking on generated responses, quality control",
+        tier: "experimental",
+        aliases: ["Guardrail", "Response Checker"],
     },
     {
         actionName: "abstain_action",
@@ -429,6 +466,7 @@ export const AGENT_CATALOG = [
             { name: "abstain_reason", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Abstention message" },
         ],
         whenToUse: "When the AI should explicitly decline to answer or redirect",
+        tier: "experimental",
     },
     // Sentiment & Analysis
     {
@@ -443,6 +481,7 @@ export const AGENT_CATALOG = [
             { name: "sentiment", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Sentiment analysis" },
         ],
         whenToUse: "When you need to gauge user emotion for routing or response tone adjustment",
+        tier: "standard",
     },
     // Domain Agents - Finance
     {
@@ -453,6 +492,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Risk query" }],
         outputs: [{ name: "risk_assessment", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Risk analysis" }],
         whenToUse: "Financial services: portfolio risk, credit assessment, exposure analysis",
+        tier: "specialized",
     },
     {
         actionName: "financial_statement_analyzer",
@@ -462,6 +502,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Financial documents" }],
         outputs: [{ name: "analysis", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Financial analysis" }],
         whenToUse: "Analyzing P&L, balance sheets, annual reports",
+        tier: "specialized",
     },
     {
         actionName: "tax_advisor",
@@ -471,6 +512,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Tax question" }],
         outputs: [{ name: "tax_advice", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Tax guidance" }],
         whenToUse: "Tax planning, compliance questions, deduction analysis",
+        tier: "specialized",
     },
     {
         actionName: "audit_evidence_verifier",
@@ -480,6 +522,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Audit documents" }],
         outputs: [{ name: "verification", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Verification results" }],
         whenToUse: "Audit support, evidence verification, compliance documentation",
+        tier: "specialized",
     },
     // Domain Agents - Healthcare
     {
@@ -490,6 +533,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Medical records" }],
         outputs: [{ name: "summary", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Record summary" }],
         whenToUse: "Healthcare: summarizing patient records, medical history, clinical notes",
+        tier: "specialized",
     },
     {
         actionName: "medical_research_assistant",
@@ -499,6 +543,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Research query" }],
         outputs: [{ name: "research", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Research findings" }],
         whenToUse: "Medical research, literature review, clinical guidance",
+        tier: "specialized",
     },
     {
         actionName: "insurance_claim_summarizer",
@@ -508,6 +553,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Claim documents" }],
         outputs: [{ name: "summary", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Claim summary" }],
         whenToUse: "Insurance processing, claim analysis",
+        tier: "specialized",
     },
     // Domain Agents - Legal
     {
@@ -518,6 +564,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Documents to analyze" }],
         outputs: [{ name: "compliance_findings", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Compliance analysis" }],
         whenToUse: "Regulatory compliance, contract review, policy compliance",
+        tier: "specialized",
     },
     {
         actionName: "legal_expert",
@@ -527,6 +574,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Legal question" }],
         outputs: [{ name: "legal_analysis", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Legal guidance" }],
         whenToUse: "Legal research, contract analysis, regulatory questions",
+        tier: "specialized",
     },
     {
         actionName: "information_redacter",
@@ -536,6 +584,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Documents to redact" }],
         outputs: [{ name: "redacted", type: "WELL_KNOWN_TYPE_DOCUMENT", description: "Redacted documents" }],
         whenToUse: "Privacy compliance, document sanitization",
+        tier: "specialized",
     },
     // Domain Agents - IT/Security
     {
@@ -546,6 +595,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "email_content", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Email to analyze" }],
         outputs: [{ name: "detection_result", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Phishing analysis" }],
         whenToUse: "Email security, security operations",
+        tier: "specialized",
     },
     {
         actionName: "cybersecurity_expert",
@@ -555,6 +605,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Security query" }],
         outputs: [{ name: "security_analysis", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Security guidance" }],
         whenToUse: "Security incident analysis, vulnerability assessment",
+        tier: "specialized",
     },
     {
         actionName: "technical_support",
@@ -564,6 +615,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Support query" }],
         outputs: [{ name: "support_response", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Technical guidance" }],
         whenToUse: "IT helpdesk, troubleshooting, technical guidance",
+        tier: "specialized",
     },
     // Domain Agents - Sales
     {
@@ -574,6 +626,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Sales query" }],
         outputs: [{ name: "intelligence", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Sales insights" }],
         whenToUse: "Account research, competitive analysis, opportunity assessment",
+        tier: "specialized",
     },
     {
         actionName: "email_writer",
@@ -583,6 +636,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Email context" }],
         outputs: [{ name: "email", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Generated email" }],
         whenToUse: "Sales outreach, customer communication, follow-ups",
+        tier: "specialized",
     },
     // Formatting Agents
     {
@@ -593,6 +647,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "content", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Content to format" }],
         outputs: [{ name: "json", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "JSON formatted output" }],
         whenToUse: "When structured JSON output is required",
+        tier: "standard",
     },
     {
         actionName: "json_extractor",
@@ -602,6 +657,7 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "content", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Content containing JSON" }],
         outputs: [{ name: "extracted_json", type: "WELL_KNOWN_TYPE_ANY", description: "Extracted JSON object" }],
         whenToUse: "When you need to parse JSON from LLM responses",
+        tier: "standard",
     },
     {
         actionName: "markdown_formatter",
@@ -611,5 +667,6 @@ export const AGENT_CATALOG = [
         inputs: [{ name: "content", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Content to format" }],
         outputs: [{ name: "markdown", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Markdown formatted output" }],
         whenToUse: "When rich text formatting is needed",
+        tier: "standard",
     },
 ];

package/dist/sdk/generated/deprecated-actions.js

@@ -240,7 +240,7 @@ export const DEPRECATED_ACTIONS_MAP = {
     "json_mapper/v0": { replacement: "json_mapper/v1" },
     "meta_respond/v0": {},
     "meta_respond/v2": {},
-    "respond_with_sources/v0": { replacement: "respond_for_external_actions", notes: "Better tool result handling" },
+    "respond_with_sources/v0": { replacement: "call_llm with named_inputs", notes: "For KB Q&A use call_llm; respond_for_external_actions is ONLY for external_action_caller results" },
     "rule_validation_with_documents/v0": { replacement: "rule_validation_with_documents/v1" },
     "search/v0": { replacement: "search/v2", notes: "v2 requires datastore_configs input" },
     "text_categorizer/v0": { replacement: "text_categorizer/v1" },

package/dist/sdk/grpc-client.js

@@ -14,9 +14,10 @@ import { createGrpcWebTransport } from '@connectrpc/connect-node';
 import { create, fromJson } from '@bufbuild/protobuf';
 // Generated service definitions (v2: services and schemas in same _pb.ts file)
 import { ActionManager, ListActionsRequestSchema, ListActionsFromWorkflowRequestSchema, GetActionRequestSchema, } from './generated/protos/service/workflows/v1/action_registry_pb.js';
-import { DashboardsService, GetDashboardRowsRequestSchema, GetDashboardSchemaRequestSchema, } from './generated/protos/service/workflows/v1/dashboards_pb.js';
+import { DashboardsService, GetDashboardRowsRequestSchema, GetDashboardSchemaRequestSchema, ContinueWorkflowForRowRequestSchema, } from './generated/protos/service/workflows/v1/dashboards_pb.js';
+import { ContinuationMessageSchema, } from './generated/protos/service/workflows/v1/coordinator_pb.js';
 import { WorkflowManager, CheckWorkflowRequestSchema, GetWorkflowRequestSchema, } from './generated/protos/service/workflows/v1/rpc/workflow_rpc_pb.js';
-import { DataIngestService, GetRootContentNodesRequestSchema, GetContentNodeAggregatesRequestSchema, ReplicateDataRequestSchema, GetReplicationStatusRequestSchema, FilePickerGroupType, WidgetReplicationMappingSchema, } from './generated/protos/service/dataingest/v1/dataingest_pb.js';
+import { DataIngestService, GetRootContentNodesRequestSchema, GetContentNodeAggregatesRequestSchema, ReplicateDataRequestSchema, GetReplicationStatusRequestSchema, GetSignedUrlRequestSchema, DeleteFilesForGroupRequestSchema, DeletionGroupType, FilePickerGroupType, WidgetReplicationMappingSchema, } from './generated/protos/service/dataingest/v1/dataingest_pb.js';
 import { ConversationReviewService, GetConversationReviewsRequestSchema, GetConversationReviewDetailRequestSchema, ConversationReviewFiltersSchema, } from './generated/protos/service/conversation_review/v1/conversation_review_pb.js';
 import { DebugLogService, WorkflowLevelDebugLogRequestSchema, ActionLevelShowWorkLogRequestSchema, } from './generated/protos/service/persona/v1/debug_logs_pb.js';
 import { DebuggerService, SearchMessagesRequestSchema as DebuggerSearchMessagesRequestSchema, } from './generated/protos/service/debugger/service_pb.js';
@@ -163,6 +164,22 @@ export class GrpcClient {
         const request = create(GetDashboardSchemaRequestSchema, {});
         return this.dashboardsService.getDashboardSchema(request);
     }
+    /**
+     * Continue a paused (HITL) workflow for a dashboard row.
+     * Sends a continuation message (text, button selection, or form submission)
+     * to resume the workflow.
+     *
+     * @param rowId - The dashboard row ID
+     * @param continuationMessage - The continuation message as JSON (matches ContinuationMessage proto)
+     * @returns Empty response on success
+     */
+    async continueWorkflowForRow(rowId, continuationMessage) {
+        const request = create(ContinueWorkflowForRowRequestSchema, {
+            rowId,
+            continuationMessage: fromJson(ContinuationMessageSchema, continuationMessage),
+        });
+        return this.dashboardsService.continueWorkflowForRow(request);
+    }
     // ─────────────────────────────────────────────────────────────────────────────
     // WorkflowManager RPCs
     // ─────────────────────────────────────────────────────────────────────────────
@@ -218,7 +235,10 @@ export class GrpcClient {
             page: opts?.page ?? 1,
             limit: opts?.limit ?? 100,
         });
-        return this.dataIngestService.getRootContentNodes(request);
+        // DataIngestService has PERSONA_REQUIRED auth — pass persona via gRPC header
+        return this.dataIngestService.getRootContentNodes(request, {
+            headers: new Headers({ 'x-persona-id': personaId }),
+        });
     }
     /**
      * Get content node aggregates (file counts by status).
@@ -233,7 +253,10 @@ export class GrpcClient {
             filePickerGroupId: personaId,
             filePickerGroupType: FilePickerGroupType.PERSONA,
         });
-        return this.dataIngestService.getContentNodeAggregates(request);
+        // DataIngestService has PERSONA_REQUIRED auth — pass persona via gRPC header
+        return this.dataIngestService.getContentNodeAggregates(request, {
+            headers: new Headers({ 'x-persona-id': personaId }),
+        });
     }
     /**
      * Replicate data from one persona to another.
@@ -259,7 +282,24 @@ export class GrpcClient {
                 ...(m.targetWidget ? { destinationWidgetName: m.targetWidget } : {}),
             })),
         });
-        return this.dataIngestService.replicateData(request);
+        // DataIngestService has PERSONA_REQUIRED auth — use target persona for write auth
+        return this.dataIngestService.replicateData(request, {
+            headers: new Headers({ 'x-persona-id': target.id }),
+        });
+    }
+    /**
+     * Get a signed download URL for a file by its UploadedFile.Id.
+     *
+     * @param fileId - The UploadedFile.Id (from ContentNodeResponse.id, NOT contentNodeId)
+     * @returns Signed URL, MIME type, title, and deletion status
+     */
+    async getSignedUrl(fileId, personaId) {
+        const request = create(GetSignedUrlRequestSchema, { fileId });
+        // DataIngestService may require PERSONA_REQUIRED auth
+        const callOpts = personaId
+            ? { headers: new Headers({ 'x-persona-id': personaId }) }
+            : undefined;
+        return this.dataIngestService.getSignedUrl(request, callOpts);
     }
     /**
      * Get the status of a replication request.
@@ -273,6 +313,28 @@ export class GrpcClient {
         });
         return this.dataIngestService.getReplicationStatus(request);
     }
+    /**
+     * Delete files from a group (persona/project/dashboard_row) via gRPC.
+     *
+     * NOTE: DIS does NOT expose a REST DELETE endpoint for files.
+     * This gRPC method is the ONLY way to delete files.
+     *
+     * @param personaId - The persona ID (group)
+     * @param fileIds - Array of UploadedFile.Id values to delete
+     * @param widgetName - Optional widget name scope
+     */
+    async deleteFilesForGroup(personaId, fileIds, widgetName) {
+        const request = create(DeleteFilesForGroupRequestSchema, {
+            groupId: personaId,
+            groupType: DeletionGroupType.PERSONA,
+            fileIds,
+            ...(widgetName ? { widgetName } : {}),
+        });
+        // DataIngestService has PERSONA_REQUIRED auth
+        return this.dataIngestService.deleteFilesForGroup(request, {
+            headers: new Headers({ 'x-persona-id': personaId }),
+        });
+    }
     // ─────────────────────────────────────────────────────────────────────────────
     // ConversationReviewService RPCs (Audit)
     // ─────────────────────────────────────────────────────────────────────────────

package/dist/sync/central-factory.js

@@ -0,0 +1,86 @@
+/**
+ * Central storage factory — creates DIS-backed version storage + policy engine.
+ *
+ * Used by all 4 call sites (version.ts, update.ts, delete.ts, workflow/adapter.ts)
+ * to avoid duplicating construction logic.
+ *
+ * Also provides lazy migration from local (.ema-versions/) to central (DIS).
+ */
+import { DISAdapter } from "./dis-port.js";
+import { CentralVersionStorage } from "./central-version-storage.js";
+import { VersionPolicyEngine } from "./version-policy.js";
+/**
+ * Extract a DISClientLike from an SDK client.
+ *
+ * At runtime, `createClient()` returns EmaClientAdapter which wraps EmaClientV2.
+ * EmaClientV2 satisfies DISClientLike (has uploadDataSource, downloadFile,
+ * deleteDataSource, listDataSourceFiles with raw gRPC response).
+ *
+ * This function checks for the `.v2Client` accessor (EmaClientAdapter) and
+ * falls back to using the client directly (e.g., in tests with a mock).
+ */
+function extractDISClient(client) {
+    // If the client has a v2Client accessor (EmaClientAdapter), use the inner V2 client
+    const maybeAdapter = client;
+    if (maybeAdapter.v2Client) {
+        return maybeAdapter.v2Client;
+    }
+    // Fallback: assume the client itself satisfies DISClientLike (tests, direct V2 usage)
+    return client;
+}
+/**
+ * Create a central version storage + policy engine pair for a persona.
+ *
+ * @param client - SDK client. Typically the EmaClient/EmaClientAdapter from createClient().
+ *   The factory auto-extracts the underlying EmaClientV2 for raw DIS operations.
+ * @param personaId - The persona ID to scope storage to
+ */
+export function createCentralStorageEngine(client, personaId) {
+    const disClient = extractDISClient(client);
+    const port = new DISAdapter(disClient, personaId);
+    const storage = new CentralVersionStorage(port, personaId);
+    const engine = new VersionPolicyEngine(storage);
+    return { storage, engine };
+}
+/**
+ * Lazily migrate local versions to central storage on first access.
+ *
+ * Called by version.ts before creating a new snapshot. If central already has
+ * versions, this is a no-op. Otherwise, reads the last `limit` local versions
+ * and uploads them to DIS, preserving version numbers and parent chains.
+ *
+ * @param localStorage - Local git-backed storage (VersionStorage)
+ * @param centralStorage - DIS-backed central storage
+ * @param personaId - Persona to migrate
+ * @param limit - Max versions to migrate (default: 5, most recent)
+ * @returns Number of versions migrated (0 if central already populated or no local versions)
+ */
+export async function migrateLocalToCentral(localStorage, centralStorage, personaId, limit = 5) {
+    // Skip if central already has versions (idempotent)
+    const centralManifest = await centralStorage.getManifest(personaId);
+    if (centralManifest && centralManifest.versions.length > 0) {
+        return 0;
+    }
+    // Read local versions
+    const localVersions = await localStorage.listVersions(personaId);
+    if (localVersions.length === 0) {
+        return 0;
+    }
+    // Take the most recent `limit` versions, sorted ascending for upload order
+    const sorted = [...localVersions].sort((a, b) => b.version_number - a.version_number);
+    const toMigrate = sorted.slice(0, limit).reverse();
+    let migrated = 0;
+    for (const entry of toMigrate) {
+        try {
+            const snapshot = await localStorage.getVersion(personaId, entry.version_number);
+            if (!snapshot)
+                continue;
+            await centralStorage.saveVersion(snapshot);
+            migrated++;
+        }
+        catch {
+            // Best-effort: skip failed individual versions
+        }
+    }
+    return migrated;
+}