@ema.co/mcp-toolkit 2026.3.25-4 → 2026.4.9

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

@@ -26,8 +26,11 @@ import { validateWorkflowSchema, validateSearchDataSourceConsistency, validateNo
 hasKnowledgeSearchNodes, extractActionTypeName, } from "./validation.js";
 import { validateWorkflowOutputs } from "./validate-outputs.js";
 import { validateWorkflowDefStructure } from "../../domain/workflow-def-validator.js";
+import { incrementDeployAttempts } from "../knowledge/session-state.js";
+import { emitOutcomeFeedback } from "../knowledge/outcome-feedback.js";
 // Re-export for backwards compatibility with existing imports
 export { hasKnowledgeSearchNodes, extractActionTypeName };
+// Deploy outcome feedback — thin wrapper around the generalized outcome-feedback utility
 /**
  * Handle workflow deploy mode
  */
@@ -52,6 +55,8 @@ export async function handleWorkflowDeploy(args, client) {
     if (!workflowDef) {
         return { error: "workflow_def required for deploy mode" };
     }
+    // Track deploy attempts for retry-aware feedback
+    incrementDeployAttempts();
     const persona = await client.getPersonaById(personaId);
     if (!persona) {
         return { error: `Persona not found: ${personaId}` };
@@ -319,6 +324,11 @@ export async function handleWorkflowDeploy(args, client) {
         // ═══════════════════════════════════════════════════════════════════════════
         const response = updateResponse;
         if (response?.proto_config_updated === false) {
+            // Emit deploy failure feedback before returning
+            try {
+                await emitOutcomeFeedback({ tool: "workflow", operation: "deploy", success: false });
+            }
+            catch { /* best-effort */ }
             return {
                 mode: "deploy",
                 status: "failed",
@@ -403,10 +413,33 @@ export async function handleWorkflowDeploy(args, client) {
         catch {
             // Post-deploy check is best-effort
         }
+        // ═══════════════════════════════════════════════════════════════════════════
+        // DEPLOY-OUTCOME FEEDBACK: Boost confidence on consulted knowledge docs
+        // This closes the feedback loop — successful deploys improve DE ranking.
+        // ═══════════════════════════════════════════════════════════════════════════
+        try {
+            const feedback = await emitOutcomeFeedback({ tool: "workflow", operation: "deploy", success: "accepted" });
+            if (feedback.docs_processed > 0) {
+                result._knowledge_feedback = {
+                    outcome: "accepted",
+                    docs_consulted: feedback.docs_processed,
+                    confidence_updates: feedback.confidence_updates,
+                    _tip: "Deploy accepted by API. Test with conversation() to validate intent alignment — that produces stronger confidence signals.",
+                };
+            }
+        }
+        catch {
+            // Best-effort — never block deploy response
+        }
         return result;
     }
     catch (err) {
         const errorMessage = err instanceof Error ? err.message : String(err);
+        // Emit deploy failure feedback (best-effort, before building response)
+        try {
+            await emitOutcomeFeedback({ tool: "workflow", operation: "deploy", success: false });
+        }
+        catch { /* best-effort */ }
         // Preserve structured error information if available
         const errorResult = {
             mode: "deploy",

package/dist/mcp/knowledge-guidance-topics.js

@@ -197,6 +197,21 @@ export const GUIDANCE_TOPICS = {
             "Producer key (e.g. 'p1') is an arbitrary label — not a reference to anything",
         ],
     },
+    "code-verification": {
+        title: "Verify Code From AI Answers",
+        content: "AI-generated answers (detail='answer') synthesize text from multiple source documents. " +
+            "Code examples — especially workflow_def JSON — may be fabricated or simplified by the " +
+            "generative model, even when the correct format exists in the source documents. " +
+            "NEVER copy JSON directly from a generative answer into a deploy call.",
+        status: "verified",
+        criticalRules: [
+            "ALWAYS verify workflow_def JSON against workflow(mode='get') — it returns the canonical format",
+            "For input binding formats: use knowledge('schema/workflow-def', detail='excerpts') — the source document has validated examples",
+            "For extraction_columns format: use knowledge('extraction-column-format', detail='excerpts')",
+            "If an AI answer shows JSON with unfamiliar fields (e.g., 'producer', 'value', 'actionType'), it is likely fabricated — cross-check against the schema",
+            "The correct action format uses action.name.namespaces, NOT actionType — if you see actionType in an example, it's wrong",
+        ],
+    },
     "workflow-execution": {
         title: "Workflow Execution Model",
         content: "CRITICAL: Each user_query triggers a NEW workflow execution. The workflow runs ONCE per user message, not once per conversation.",
@@ -1305,17 +1320,26 @@ See ema://docs/knowledge-publish for the complete guide with examples.`,
 - Wrong environment — token for dev used against prod
 - Scope escalation (elevate=true) — needs valid @ema.co token for internal scope
 
-Use config() to verify your current authentication status and profile configuration.`,
+Use config() to verify your current authentication status and profile configuration.
+
+**Custom Tenant Environments:**
+For non-standard deployments (e.g. sub-tenant staging at staging.acme.ema.co), use app_url:
+- config(method="login", app_url="https://staging.acme.ema.co") — API URL auto-derived as api.staging.acme.ema.co
+- For non-ema.co custom domains, provide app_url and api_url (env auto-derived from hostname)
+- If auto-derivation is wrong, provide explicit api_url override
+- After login, update endpoints anytime: config(method="set", key="api_url", value="https://...")`,
         status: "verified",
         examples: [
             'config() — check current auth status',
             'config(method="login") — authenticate via browser',
+            'config(method="login", app_url="https://staging.acme.ema.co") — custom tenant environment',
         ],
         criticalRules: [
             "API key auth (EMA_API_KEY) auto-refreshes tokens — preferred for long-running sessions",
             "Bearer tokens expire after ~24 hours — must be manually refreshed",
             "A 401 error means re-authentication is needed, not a bug in your workflow",
             "For knowledge search elevation (internal scope), use EMA_BEARER_TOKEN with an @ema.co account",
+            "For custom URLs, the API URL pattern is api.{subdomain}.ema.co for *.ema.co domains, or api.{hostname} for other domains — override with api_url if different",
         ],
     },
     "data-upload": {

package/dist/mcp/knowledge.js

@@ -481,7 +481,7 @@ export function validateWorkflowConnections(workflowDef) {
 // FALLBACK: Generated from ema repo via: npm run generate:deprecated-actions
 // 
 // The generated file is synced automatically by GH Actions from ema repo.
-// To manually regenerate: npm run generate:deprecated-actions -- --path /path/to/ema
+// To manually regenerate: npm run generate:deprecated-actions -- --path /path/to/parent-of-ema-dir
 // ─────────────────────────────────────────────────────────────────────────────
 // Re-export from generated file (maintains backwards compatibility)
 export { DEPRECATED_ACTIONS_WITH_REPLACEMENT, DEPRECATED_ACTIONS_NO_REPLACEMENT, ALL_DEPRECATED_ACTIONS, DEPRECATED_AGENT_TYPES, DEPRECATED_ACTIONS_MAP, isActionDeprecated, getActionReplacement, } from "../sdk/generated/deprecated-actions.js";

package/dist/mcp/resources-dynamic.js

@@ -223,10 +223,10 @@ const DYNAMIC_RESOURCES = [
                 md += `| \`${d.action}\` | ${d.version} | \`${repl}\`${replVer} | ${env} | ${d.migrationNotes || "-"} |\n`;
             }
             md += "\n## Actions with No Known Replacement\n\n";
-            md += "| Action | Environment | Notes |\n";
-            md += "|--------|-------------|-------|\n";
+            md += "| Action | Version | Environment | Notes |\n";
+            md += "|--------|---------|-------------|-------|\n";
             for (const d of DEPRECATED_ACTIONS_NO_REPLACEMENT) {
-                md += `| \`${d.action}\` | ${d.envs ? d.envs.join(", ") : "all"} | ${d.migrationNotes || "-"} |\n`;
+                md += `| \`${d.action}\` | ${d.version} | ${d.envs ? d.envs.join(", ") : "all"} | ${d.migrationNotes || "-"} |\n`;
             }
             md += `\n**Total Known Deprecated**: ${ALL_DEPRECATED_ACTIONS.length} actions\n`;
             md += `\n> **Best Practice**: Use \`workflow(mode="get")\` to check for deprecation warnings in specific workflows.\n`;

package/dist/mcp/tools.js

@@ -705,12 +705,16 @@ A **profile** = tenant + environment + auth. Example: "acme-corp-prod" = Acme Co
 - \`config(method="login", env="staging")\` — login to specific environment
 - \`config(method="login", env="prod", tenant="acme-corp")\` — login with tenant
 - \`config(method="login", token="eyJ...")\` — direct token login (agent-mediated: user pastes JWT in chat)
+- \`config(method="login", app_url="https://staging.acme.ema.co")\` — login to custom tenant environment
+- \`config(method="login", app_url="https://staging.acme.ema.co", api_url="https://custom-api.example.com")\` — with explicit API URL override
 - \`config(method="logout")\` — remove current profile credential
 - \`config(method="logout", profile="demo-inc-staging")\` — remove specific credential
 - \`config(method="profiles")\` — list all profiles with auth status
 - \`config(method="use", profile="demo-inc-staging")\` — switch active profile
 - \`config(method="set", key="debug", value=true)\` — set preference
 - \`config(method="set", key="default_env", value="prod")\` — set default login environment
+- \`config(method="set", key="api_url", value="https://api.custom.ema.co")\` — update current profile's API URL
+- \`config(method="set", key="app_url", value="https://custom.ema.co")\` — update current profile's app URL
 - \`config(method="get")\` — get all preferences
 - \`config(method="gcp_login")\` — standalone Google auth for knowledge search (no Ema re-login needed)
 - \`config(method="gcp_login", gcp_token="ya29...")\` — direct GCP token (agent-mediated: user pastes token in chat)`,
@@ -724,7 +728,15 @@ A **profile** = tenant + environment + auth. Example: "acme-corp-prod" = Acme Co
                     },
                     env: {
                         type: "string",
-                        description: "Environment for login: prod, staging, dev, demo (for method=login)",
+                        description: "Environment: prod, staging, dev, demo, or auto-derived from app_url (for method=login)",
+                    },
+                    app_url: {
+                        type: "string",
+                        description: "Custom app/frontend URL (e.g. https://staging.acme.ema.co). API URL derived automatically. For method=login, or method=set to update current profile.",
+                    },
+                    api_url: {
+                        type: "string",
+                        description: "Explicit API URL override. Only needed if auto-derivation from app_url is wrong. For method=login, or method=set to update current profile.",
                     },
                     tenant: {
                         type: "string",
@@ -744,8 +756,8 @@ A **profile** = tenant + environment + auth. Example: "acme-corp-prod" = Acme Co
                     },
                     key: {
                         type: "string",
-                        enum: ["debug", "default_env", "resource_source"],
-                        description: "Preference key (for method=set, method=get)",
+                        enum: ["debug", "default_env", "resource_source", "api_url", "app_url"],
+                        description: "Preference key (for method=set, method=get). api_url and app_url update the current profile's endpoints.",
                     },
                     value: {
                         description: "Preference value (for method=set)",

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

@@ -339,6 +339,7 @@ export const AGENT_CATALOG = [
         tier: "core",
         aliases: ["Custom LLM", "Generic Agent"],
     },
+    // Search & Retrieval
     {
         actionName: "document_synthesis",
         displayName: "Document Synthesis",
@@ -360,6 +361,7 @@ export const AGENT_CATALOG = [
         tier: "standard",
         aliases: ["Research Agent", "Agentic Search"],
     },
+    // Generation & Response
     {
         actionName: "json_mapper",
         displayName: "JSON Extractor",
@@ -372,7 +374,7 @@ export const AGENT_CATALOG = [
         outputs: [
             { name: "output_json", type: "WELL_KNOWN_TYPE_STRUCT", description: "Flat JSON object with extracted key-value pairs (string, boolean, number, or null)" },
         ],
-        whenToUse: "Type conversion intermediary — extract specific fields from complex objects, transform entity extraction output for email/categorizer input, normalize structured data between incompatible action types",
+        whenToUse: "Type conversion intermediary — extract specific fields from complex objects, transform entity extraction output for email/categorizer input",
         whenNotToUse: "When full object passthrough is acceptable or when call_llm can handle the transformation",
         criticalRules: [
             "Use json_mapper as type intermediary when wiring actions with incompatible types (e.g., entity_extraction ANY output → send_email TEXT_WITH_SOURCES input)",
@@ -801,7 +803,7 @@ export const AGENT_CATALOG = [
         whenToUse: "When rich text formatting is needed",
         tier: "standard",
     },
-    // ─── Utilities & Internal Pipeline ────────────────────────────────────────
+    // Generation & Response
     {
         actionName: "chart_creator",
         displayName: "Chart Builder",
@@ -816,6 +818,7 @@ export const AGENT_CATALOG = [
         whenToUse: "When dashboard or chat workflows need data visualization from extraction or search results",
         tier: "standard",
     },
+    // utilities
     {
         actionName: "combine_search_results",
         displayName: "Combine Search Results",
@@ -886,7 +889,7 @@ export const AGENT_CATALOG = [
         whenToUse: "When workflows need to classify or label content for routing, filtering, or metadata enrichment",
         tier: "standard",
     },
-    // ─── Agent Assist / Ticketing ─────────────────────────────────────────────
+    // agent_assist
     {
         actionName: "thread_categorizer",
         displayName: "Thread Categorizer",
@@ -945,7 +948,7 @@ export const AGENT_CATALOG = [
         whenToUse: "When workflows need to detect user satisfaction signals from conversation feedback",
         tier: "standard",
     },
-    // ─── Specialized / Vertical ───────────────────────────────────────────────
+    // Domain Agents — Sales
     {
         actionName: "market_research",
         displayName: "Sales Intelligence",
@@ -960,6 +963,7 @@ export const AGENT_CATALOG = [
         whenToUse: "Sales prospecting, account research, financial due diligence workflows",
         tier: "specialized",
     },
+    // Sentiment & Analysis
     {
         actionName: "qa_over_sql",
         displayName: "Natural Language to SQL",

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

@@ -4,8 +4,8 @@
  * PRIMARY SOURCE: API via client.listActions() where deprecated === true
  * This file is FALLBACK only when API is unavailable.
  *
- * Generated at: 2026-02-13T06:42:33.243Z
- * Source: ../ema-repos
+ * Generated at: 2026-04-04T04:29:47.533Z
+ * Source: /Users/sp/Documents/git/ema-repos
  *
  * DO NOT EDIT MANUALLY - regenerate with: npm run generate:deprecated-actions
  */
@@ -36,6 +36,14 @@ export const DEPRECATED_ACTIONS_WITH_REPLACEMENT = [
         "replacement": "fixed_response",
         "replacementVersion": "v1"
     },
+    {
+        "action": "general_hitl",
+        "version": "v0",
+        "source": "system_agents/prod/general_hitl_def.txtpb",
+        "replacement": "general_hitl",
+        "replacementVersion": "v1",
+        "migrationNotes": "Use general_hitl v1 (Human Collaboration); v0 textproto is deprecated"
+    },
     {
         "action": "json_mapper",
         "version": "v0",
@@ -82,7 +90,9 @@ export const DEPRECATED_ACTIONS_WITH_REPLACEMENT = [
     {
         "action": "combine_external_action_and_search_results",
         "version": "v0",
-        "envs": ["dev"],
+        "envs": [
+            "dev"
+        ],
         "source": "system_agents/dev/combine_external_action_and_search_results_def.txtpb",
         "replacement": "respond_for_external_actions"
     }
@@ -132,11 +142,6 @@ export const DEPRECATED_ACTIONS_NO_REPLACEMENT = [
         "version": "v0",
         "source": "system_agents/prod/generate_document_using_outline_def.txtpb"
     },
-    {
-        "action": "general_hitl",
-        "version": "v1",
-        "source": "system_agents/prod/human_collaboration_def.txtpb"
-    },
     {
         "action": "meta_respond",
         "version": "v0",
@@ -162,16 +167,12 @@ export const DEPRECATED_ACTIONS_NO_REPLACEMENT = [
         "version": "v0",
         "source": "system_agents/prod/write_document_def.txtpb"
     },
-    {
-        "action": "external_action_caller",
-        "version": "v1",
-        "envs": ["dev"],
-        "source": "system_agents/dev/external_action_caller_v1_def.txtpb"
-    },
     {
         "action": "ticket_thread_sink",
         "version": "v0",
-        "envs": ["dev"],
+        "envs": [
+            "dev"
+        ],
         "source": "system_agents/dev/ticket_thread_sink_def.txtpb"
     }
 ];
@@ -205,6 +206,7 @@ export const DEPRECATED_ACTIONS_MAP = {
     "ai_web_search/v0": {},
     "call_llm/v0": { replacement: "call_llm/v2", notes: "v2 uses meta_respond_v2" },
     "call_llm/v1": {},
+    "combine_external_action_and_search_results/v0": { replacement: "respond_for_external_actions" },
     "combine_search_results/v0": {},
     "combine_text_with_sources/v0": {},
     "custom_agent/v0": { replacement: "custom_agent/v1" },
@@ -212,8 +214,8 @@ export const DEPRECATED_ACTIONS_MAP = {
     "document_categorizer/v0": {},
     "document_metasearch/v0": {},
     "fixed_response/v0": { replacement: "fixed_response/v1" },
+    "general_hitl/v0": { replacement: "general_hitl/v1", notes: "Use general_hitl v1 (Human Collaboration); v0 textproto is deprecated" },
     "generate_document_using_outline/v0": {},
-    "general_hitl/v1": {},
     "json_mapper/v0": { replacement: "json_mapper/v1" },
     "meta_respond/v0": {},
     "meta_respond/v2": {},
@@ -223,11 +225,9 @@ export const DEPRECATED_ACTIONS_MAP = {
     "text_categorizer/v0": { replacement: "text_categorizer/v1" },
     "text_with_sources_translation/v0": {},
     "ticket_respond_with_sources/v0": {},
+    "ticket_thread_sink/v0": {},
     "web_search/v0": { replacement: "live_web_search or ai_web_search", notes: "Split into two specialized actions" },
     "write_document/v0": {},
-    "combine_external_action_and_search_results/v0": { replacement: "respond_for_external_actions" },
-    "external_action_caller/v1": {},
-    "ticket_thread_sink/v0": {},
 };
 /**
  * Check if an action is deprecated.

package/dist/sdk/generated/proto-fields.js

@@ -1,6 +1,6 @@
 /**
  * Auto-generated protobuf field constants from Ema Platform proto definitions.
- * Generated at: 2026-02-13T06:42:27.676Z
+ * Generated at: 2026-04-04T04:29:51.732Z
  *
  * DO NOT EDIT MANUALLY - regenerate with: npm run generate:proto
  *