@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23

package/dist/cli/index.js

@@ -11,7 +11,7 @@
  *   config validate       - Validate config file
  */
 import { loadConfig } from "../sdk/config.js";
-import { EmaClient } from "../sdk/client.js";
+import { EmaClientAdapter } from "../sdk/client-adapter.js";
 import { SyncSDK } from "../sync/sdk.js";
 function printUsage() {
     console.log(`
@@ -220,7 +220,7 @@ async function runAgentsCommand(subcommand, args, options) {
         baseUrl: master.baseUrl,
         bearerToken: getEnvOrThrow(master.bearerTokenEnv),
     };
-    const client = new EmaClient(env);
+    const client = new EmaClientAdapter(env);
     switch (subcommand) {
         case "list": {
             const actions = await client.listAgents();

package/dist/mcp/domain/loop-detection.js

@@ -0,0 +1,89 @@
+/**
+ * Loop Detection for Workflow Graphs
+ *
+ * Uses the shared WorkflowGraph representation from workflow-graph.ts
+ * for cycle and re-entry detection in workflow validation.
+ */
+import { buildWorkflowGraph } from "./workflow-graph.js";
+export function detectLoops(workflowDef) {
+    if (!workflowDef || typeof workflowDef !== "object")
+        return [];
+    const graph = buildWorkflowGraph(workflowDef);
+    if (graph.nodes.size === 0)
+        return [];
+    const loops = [];
+    const { forward } = graph;
+    const visited = new Set();
+    const recursionStack = new Set();
+    const path = [];
+    function dfs(nodeId) {
+        visited.add(nodeId);
+        recursionStack.add(nodeId);
+        path.push(nodeId);
+        for (const neighbor of (forward.get(nodeId) ?? [])) {
+            if (!visited.has(neighbor)) {
+                if (dfs(neighbor))
+                    return true;
+            }
+            else if (recursionStack.has(neighbor)) {
+                const cycleStart = path.indexOf(neighbor);
+                const cyclePath = path.slice(cycleStart);
+                cyclePath.push(neighbor);
+                loops.push({
+                    type: 'circular_dependency',
+                    nodes: cyclePath,
+                    description: `Circular dependency: ${cyclePath.join(' → ')}`,
+                    severity: 'critical',
+                    fixSuggestion: `Break the cycle by removing one edge.`,
+                });
+                return true;
+            }
+        }
+        path.pop();
+        recursionStack.delete(nodeId);
+        return false;
+    }
+    if (graph.trigger)
+        dfs(graph.trigger);
+    for (const nodeId of graph.nodes.keys()) {
+        if (!visited.has(nodeId))
+            dfs(nodeId);
+    }
+    // Detect categorizer routing back to upstream (re-entry)
+    detectReentryLoops(graph, loops);
+    return loops;
+}
+/**
+ * Detect categorizer nodes routing back to upstream nodes (re-entry risk).
+ * Uses the graph's reverse adjacency map instead of manual edge traversal.
+ */
+function detectReentryLoops(graph, loops) {
+    for (const [nodeId, graphNode] of graph.nodes) {
+        if (graphNode.actionType !== 'chat_categorizer')
+            continue;
+        const downstream = graph.forward.get(nodeId) ?? new Set();
+        const upstream = new Set();
+        function collectUpstream(nId, depth = 0) {
+            if (depth > 20)
+                return;
+            for (const parent of (graph.reverse.get(nId) ?? [])) {
+                if (!upstream.has(parent)) {
+                    upstream.add(parent);
+                    collectUpstream(parent, depth + 1);
+                }
+            }
+        }
+        collectUpstream(nodeId);
+        for (const downNode of downstream) {
+            if (upstream.has(downNode)) {
+                loops.push({
+                    type: 'reentry_loop',
+                    nodes: [nodeId, downNode],
+                    description: `Categorizer "${graphNode.displayName || nodeId}" routes to "${downNode}" which is upstream - can cause re-processing`,
+                    severity: 'warning',
+                    fixSuggestion: `Add state tracking or one-time-execution gate to prevent re-processing.`,
+                });
+            }
+        }
+    }
+}

package/dist/mcp/domain/sanitizer.js

@@ -896,7 +896,7 @@ export function applySessionMappings(text, session) {
  * Content fields that SHOULD be sanitized (allowlist approach).
  * Only these fields contain user-facing content that may have PII.
  *
- * TODO: Generate this from OpenAPI spec or gRPC definitions
+ * Manually maintained — candidate for auto-generation from OpenAPI/gRPC definitions.
  */
 const CONTENT_FIELDS = new Set([
     // Persona-level

package/dist/mcp/domain/structural-rules.js

@@ -2,9 +2,8 @@
  * Structural Rules for LLM Context
  *
  * These rules encode the validation logic from:
- * - workflow-fixer.ts
- * - workflow-execution-analyzer.ts
  * - knowledge.ts (detectWorkflowIssues)
+ * - loop-detection.ts (cycle detection, extracted from workflow-execution-analyzer.ts)
  *
  * PURPOSE: Feed these to the LLM so it can self-validate during generation/transformation.
  * This is the "teach the LLM the rules" approach vs "fix after the fact".
@@ -105,9 +104,9 @@ export const STRUCTURAL_INVARIANTS = [
     {
         id: "hitl_has_both_paths",
         name: "HITL Must Have Success AND Failure Paths",
-        rule: "A general_hitl node has two outcomes: approval and rejection. Both MUST have downstream handlers.",
+        rule: "Legacy general_hitl nodes (if present) have two outcomes: approval and rejection. Both MUST have downstream handlers. Note: general_hitl is NOT deployable for new workflows — HITL is a flag on entity_extraction_with_documents and send_email_agent only.",
         violation: "HITL 'approval' only has success path - rejections hang",
-        fix: "Add handler for hitl.approval_decision = 'reject' (typically fixed_response with apology)",
+        fix: "For legacy workflows: add handler for hitl.approval_decision = 'reject'. For new workflows: use HITL flag on send_email_agent or entity_extraction_with_documents instead.",
         severity: "critical",
     },
     // ═══════════════════════════════════════════════════════════════════════════
@@ -338,7 +337,7 @@ BEFORE finalizing any workflow modification, verify these rules:
 
 ### HITL Rules
 
-10. **Both Paths Required**: general_hitl needs handlers for both approval AND rejection.
+10. **Both Paths Required**: Legacy general_hitl nodes need handlers for both approval AND rejection. Note: general_hitl is NOT deployable — HITL is a flag on entity_extraction_with_documents and send_email_agent only.
 
 ### Raw workflow_def Format Rules (CRITICAL)
 

package/dist/mcp/domain/validation-rules.js

@@ -135,7 +135,7 @@ export const ANTI_PATTERNS = [
         pattern: "send_email_agent without entity_extraction to validate recipient data",
         problem: "Sending emails without extracting and validating recipient data risks sending to wrong people or with wrong content. Emails are high-impact actions with external side effects.",
         solution: "Always: 1) Extract required fields (email_address, subject) via entity_extraction, 2) Validate completeness via categorizer, 3) Ask user if missing. " +
-            "For approval: enable the HITL flag on send_email_agent (do NOT add a standalone general_hitl node).",
+            "For approval: enable the HITL flag on send_email_agent (disable_human_interaction: false). general_hitl is NOT deployable.",
         detection: {
             issueType: "incomplete_email_validation",
             condition: "send_email_agent without preceding entity_extraction node to extract/validate recipient data",
@@ -195,15 +195,15 @@ export const ANTI_PATTERNS = [
         name: "Incomplete HITL Paths",
         pattern: "HITL with only success path",
         problem: "Rejected requests have no handling, leaving users without response.",
-        solution: "If workflow already has general_hitl node: ALWAYS implement both success AND failure paths. For NEW workflows: use HITL flag on the agent instead of standalone general_hitl nodes (see hitl-patterns guidance).",
+        solution: "If workflow already has general_hitl node: ALWAYS implement both success AND failure paths. For NEW workflows: use HITL flag on the agent (only entity_extraction_with_documents and send_email_agent support HITL). general_hitl is NOT deployable.",
         detection: {
             issueType: "incomplete_hitl",
             condition: "HITL node missing 'hitl_status_HITL Success' or 'hitl_status_HITL Failure' edge (note: space, not underscore)",
         },
         severity: "critical",
-        // TODO: Revisit if general_hitl is re-enabled as a standalone node.
-        // Currently HITL is a flag on agents (send_email_agent, external_action_caller).
-        // This anti-pattern still fires for existing workflows that use general_hitl.
+        // general_hitl is NOT deployable — it appears in catalogs but cannot be deployed.
+        // HITL is a flag on entity_extraction_with_documents and send_email_agent only.
+        // external_action_caller does NOT support HITL. This rule still fires for legacy workflows.
     },
     {
         id: "orphan-nodes",

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

@@ -2,12 +2,10 @@
  * Shared Workflow Graph Representation
  *
  * Single source of truth for parsing workflow_def JSON into a typed graph.
- * Replaces duplicated graph-building across workflow-execution-analyzer,
- * workflow-optimizer (deprecated), and workflow-tracer.
+ * Used by the workflow optimizer for static analysis.
  *
- * NOTE: `workflow-execution-analyzer.ts` still has its own `buildGraphMaps()`
- * which serves validation (runtime checks). This graph serves optimization
- * (static analysis). Future work: consolidate both into this module.
+ * `loop-detection.ts` uses `buildWorkflowGraph()` from this module for
+ * cycle and re-entry detection (consolidated from a prior local `buildGraphMaps`).
  */
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants

package/dist/mcp/domain/workflow-path-enumerator.js

@@ -50,7 +50,7 @@ export function enumeratePaths(workflow, options) {
                 throw new Error("Branch outcome without branch_point");
             }
             for (const value of result.branch_point.possible_values) {
-                const forkedSession = forkSessionForBranching(session, result.branch_point, value);
+                const forkedSession = forkSessionForBranching(session, result.branch_point, value, workflow);
                 sessionsToProcess.push(forkedSession);
             }
         }
@@ -80,7 +80,7 @@ function createInitialSession(workflow) {
         action_states: new Map(),
     };
 }
-function forkSessionForBranching(session, branchInfo, chosenValue) {
+function forkSessionForBranching(session, branchInfo, chosenValue, workflow) {
     // Deep copy session
     const forked = {
         completed_actions: [...session.completed_actions],
@@ -102,8 +102,11 @@ function forkSessionForBranching(session, branchInfo, chosenValue) {
         node_id: branchInfo.action_that_branched,
         output_name: branchInfo.branching_output_name,
     });
-    // TODO: Generate dummy outputs for other outputs of branching action
-    // TODO: Generate dummy outputs for non-branching actions
+    // Add remaining outputs from the branching action (e.g. categorizer also produces confidence)
+    const branchingNode = workflow.nodes?.find(n => n.id === branchInfo.action_that_branched);
+    if (branchingNode) {
+        addActionOutputs(forked, branchingNode);
+    }
     return forked;
 }
 // ─────────────────────────────────────────────────────────────────────────────

package/dist/mcp/guidance.js

@@ -231,7 +231,7 @@ persona({ id: "abc", env: "prod" })  // production`,
 export const TOOL_GUIDANCE = {
     persona: {
         toolName: "persona",
-        quickTip: "Use analyze=true before modifying. Use preview=true before deploying. Build structured operations for modify.",
+        quickTip: "Use workflow(mode='get') to understand the workflow before modifying. Use preview=true before deploying.",
         operations: [
             {
                 name: "List all",
@@ -243,11 +243,6 @@ export const TOOL_GUIDANCE = {
                 description: "Get details for a specific persona",
                 example: 'persona(id="abc")',
             },
-            {
-                name: "Analyze",
-                description: "Get workflow_spec, issues, and fix suggestions",
-                example: 'persona(id="abc", analyze=true)',
-            },
             {
                 name: "Update config",
                 description: "Update persona config (name, description, widgets)",
@@ -371,6 +366,51 @@ export const TOOL_GUIDANCE = {
         ],
         applicableRules: [],
     },
+    debug: {
+        toolName: "debug",
+        quickTip: "Inspect workflow executions and audit conversations. Follow the drill-down: conversations → detail → show_work → action_detail.",
+        operations: [
+            {
+                name: "List conversations",
+                description: "List audit conversations for a persona",
+                example: 'debug(method="conversations", persona_id="abc")',
+            },
+            {
+                name: "Conversation detail",
+                description: "Get messages with workflow_run_ids",
+                example: 'debug(method="conversation_detail", conversation_id="...")',
+            },
+            {
+                name: "Show work",
+                description: "See all actions' execution traces for a workflow run",
+                example: 'debug(method="show_work", persona_id="abc", workflow_run_id="...")',
+            },
+            {
+                name: "Action detail",
+                description: "Deep trace: inputs, outputs, LLM calls, steps",
+                example: 'debug(method="action_detail", persona_id="abc", workflow_run_id="...", action_name="...")',
+            },
+            {
+                name: "Search messages",
+                description: "Full-text search across conversation messages",
+                example: 'debug(method="search", persona_id="abc", query="pricing")',
+            },
+        ],
+        nextSteps: {
+            conversations: "Pick a conversation_id → debug(method='conversation_detail')",
+            conversation_detail: "Pick a workflow_run_id → debug(method='show_work', persona_id='...', workflow_run_id='...')",
+            show_work: "Pick an action_name (especially ERRORED ones) → debug(method='action_detail', persona_id='...', ...)",
+            action_detail: "Examine inputs/outputs/llm_calls to find the root cause",
+            search: "Pick a conversation_id from results → debug(method='conversation_detail')",
+        },
+        commonMistakes: [
+            "Jumping to action_detail without running show_work first (you need the action_name)",
+            "Forgetting persona_id — required for conversations, show_work, action_detail, and search",
+            "Not following _next_step hints in responses",
+            "The search method depends on DebuggerService which may not be deployed in all environments",
+        ],
+        applicableRules: [],
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Contextual Tips (for tool responses)
@@ -383,19 +423,13 @@ export const CONTEXTUAL_TIPS = [
         suggestedAction: "persona(id='<id>')",
         level: "info",
     },
-    // After getting persona without analysis
+    // After getting persona — suggest workflow get for understanding
     {
-        condition: "operation === 'get' && !args.analyze",
-        message: "Run analyze to understand the workflow before making changes",
-        suggestedAction: "persona(id='...', analyze=true)",
+        condition: "operation === 'get'",
+        message: "Use workflow(mode='get') to understand the workflow before making changes",
+        suggestedAction: "workflow(mode='get', persona_id='...')",
         level: "info",
     },
-    // After analysis shows issues
-    {
-        condition: "operation === 'analyze' && result.issues?.length > 0",
-        message: `Found ${"{result.issues.length}"} issues. Review and build workflow_spec to fix.`,
-        level: "warning",
-    },
     // Update without preview
     {
         condition: "operation === 'update' && !args.preview && result.success",
@@ -426,7 +460,7 @@ export function generateServerInstructions(buildInfo) {
 
 ## Workflow Pattern
 1. **Discover**: persona() to list AI Employees
-2. **Understand**: persona(id="...", analyze=true) before any changes
+2. **Understand**: workflow(mode="get", persona_id="...") before any changes
 3. **Preview**: Always use preview=true before deploying
 4. **Deploy**: Only after reviewing preview
 
@@ -445,8 +479,16 @@ All workflow modifications follow a 3-step flow:
 
 The LLM generates the full workflow_def. MCP provides data and executes.
 
+## Debugging Workflow Executions
+Use the \`debug\` tool to inspect workflow runs and troubleshoot issues:
+1. \`debug(method="conversations", persona_id="...")\` → list audit conversations
+2. \`debug(method="show_work", workflow_run_id="...")\` → see action execution traces
+3. \`debug(method="action_detail", ...)\` → deep trace with LLM calls, inputs/outputs
+Also available as persona sub-resource: \`persona(id="abc", debug={method:"conversations"})\`
+
 ## Resources
 - \`ema://docs/usage-guide\` - Complete guide
+- \`ema://docs/debugging-guide\` - Debugging workflow executions
 - \`ema://catalog/agents-summary\` - Action catalog
 - \`ema://rules/anti-patterns\` - Common mistakes
 
@@ -599,22 +641,13 @@ export function getContextualTip(context) {
             level: "info",
         };
     }
-    if (operation === "get" && !args.analyze) {
+    if (operation === "get") {
         return {
-            message: "Run analyze to understand the workflow before making changes",
-            suggestedAction: "persona(id='...', analyze=true)",
+            message: "Use workflow(mode='get') to understand the workflow before making changes",
+            suggestedAction: "workflow(mode='get', persona_id='...')",
             level: "info",
         };
     }
-    if (operation === "analyze" && Array.isArray(result.issues)) {
-        const issues = result.issues;
-        if (issues.length > 0) {
-            return {
-                message: `Found ${issues.length} issues. Review and build workflow_spec to fix.`,
-                level: "warning",
-            };
-        }
-    }
     if (operation === "update" && !args.preview) {
         return {
             message: "Changes deployed. Consider using preview=true next time.",

package/dist/mcp/handlers/debug/adapter.js

@@ -0,0 +1,15 @@
+/**
+ * Debug Adapter
+ *
+ * Thin adapter that resolves client from env and delegates to handleDebug.
+ * Same pattern as workflow/adapter.ts.
+ *
+ * Extracted from server.ts to keep the dispatch table thin.
+ */
+import { handleDebug } from "./index.js";
+export async function handleDebugAdapter(args, createClient, getDefaultEnvName) {
+    const targetEnv = args.env ?? getDefaultEnvName();
+    // createClient() returns EmaClientAdapter at runtime (see env/config.ts)
+    const client = createClient(targetEnv);
+    return handleDebug(args, client);
+}