@ema.co/mcp-toolkit 2026.2.5 → 2026.2.19

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

@@ -0,0 +1,374 @@
+/**
+ * Shared Workflow Graph Representation
+ *
+ * Single source of truth for parsing workflow_def JSON into a typed graph.
+ * Used by the workflow optimizer for static analysis.
+ *
+ * NOTE: `loop-detection.ts` has its own `buildGraphMaps()` for validation
+ * (cycle/re-entry detection). Future work: consolidate both into this module.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+const TRIGGER_TYPES = new Set([
+    "chat_trigger",
+    "voice_trigger",
+    "document_trigger",
+]);
+// WARNING: These lists are hardcoded and may become stale as new action types
+// are added to the platform. Future work: load side-effect classification from
+// ActionRegistry metadata instead of maintaining a static list here.
+// Unknown action types default to hasSideEffects=true (safe default).
+const SIDE_EFFECT_FREE = new Set([
+    "search",
+    "call_llm",
+    "entity_extraction",
+    "respond_with_sources",
+    "respond_for_external_actions",
+    "conversation_to_search_query",
+    "combine_search_results",
+    "text_categorizer",
+    "chat_categorizer",
+    "response_validator",
+    "fixed_response",
+    "live_web_search",
+    "ai_web_search",
+    "json_mapper",
+    "custom_agent",
+]);
+const SIDE_EFFECT_ACTIONS = new Set([
+    "send_email_agent",
+    "external_action_caller",
+    "general_hitl",
+]);
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Entry Point
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Parse a workflow_def JSON into a typed WorkflowGraph.
+ *
+ * Handles the Ema platform action format:
+ * ```
+ * { actions: [{ name, action: { name: { namespaces, name }, version }, inputs, runIf, categories, displaySettings }] }
+ * ```
+ */
+export function buildWorkflowGraph(workflowDef) {
+    const emptyGraph = {
+        nodes: new Map(),
+        edges: [],
+        forward: new Map(),
+        reverse: new Map(),
+        trigger: null,
+        outputMappings: [],
+        enumTypes: [],
+    };
+    if (!workflowDef || typeof workflowDef !== "object") {
+        return emptyGraph;
+    }
+    const actions = workflowDef.actions ?? [];
+    if (!Array.isArray(actions) || actions.length === 0) {
+        return emptyGraph;
+    }
+    const nodes = new Map();
+    const edges = [];
+    const forward = new Map();
+    const reverse = new Map();
+    let trigger = null;
+    // ── Pass 1: Build nodes ──────────────────────────────────────────────────
+    for (const action of actions) {
+        if (!action || typeof action !== "object")
+            continue;
+        const nodeId = action.name;
+        if (!nodeId)
+            continue;
+        const actionType = extractActionType(action);
+        const actionVersion = extractActionVersion(action);
+        const displayName = extractDisplayName(action);
+        const isTrigger = TRIGGER_TYPES.has(actionType);
+        const hasSideEffects = classifySideEffects(actionType);
+        // Categories can be string[] or { name: string, description?: string }[]
+        let categories;
+        const rawCategories = action.categories;
+        if (Array.isArray(rawCategories)) {
+            categories = rawCategories
+                .map((c) => typeof c === "string" ? c : c?.name)
+                .filter(Boolean);
+            if (categories.length === 0)
+                categories = undefined;
+        }
+        if (isTrigger && trigger === null) {
+            trigger = nodeId;
+        }
+        // Parse inputs
+        const inputsObj = action.inputs ?? {};
+        const inputRefs = new Map();
+        for (const [inputName, inputValue] of Object.entries(inputsObj)) {
+            if (!inputValue || typeof inputValue !== "object")
+                continue;
+            const binding = inputValue;
+            if (binding.actionOutput) {
+                const ao = binding.actionOutput;
+                inputRefs.set(inputName, {
+                    type: "action_output",
+                    sourceNode: ao.actionName,
+                    sourceOutput: ao.output,
+                });
+                addEdge(edges, forward, reverse, ao.actionName, nodeId, ao.output, inputName);
+            }
+            else if (binding.multiBinding) {
+                inputRefs.set(inputName, { type: "multi_binding" });
+                // Parse elements for nested actionOutput refs
+                const mb = binding.multiBinding;
+                const elements = mb.elements ?? [];
+                for (const elem of elements) {
+                    if (elem.namedBinding) {
+                        const nb = elem.namedBinding;
+                        const value = nb.value;
+                        if (value?.actionOutput) {
+                            const ao = value.actionOutput;
+                            addEdge(edges, forward, reverse, ao.actionName, nodeId, ao.output, inputName);
+                        }
+                    }
+                    else if (elem.actionOutput) {
+                        const ao = elem.actionOutput;
+                        addEdge(edges, forward, reverse, ao.actionName, nodeId, ao.output, inputName);
+                    }
+                }
+            }
+            else if (binding.widgetConfig) {
+                inputRefs.set(inputName, { type: "widget" });
+            }
+            else if (binding.inline) {
+                inputRefs.set(inputName, { type: "inline" });
+            }
+        }
+        // Parse runIf
+        const runIf = parseRunIf(action.runIf);
+        if (runIf) {
+            // runIf creates a dependency edge from the source node
+            addEdge(edges, forward, reverse, runIf.sourceNode, nodeId, runIf.sourceOutput, "__runIf__");
+        }
+        forward.set(nodeId, forward.get(nodeId) ?? new Set());
+        reverse.set(nodeId, reverse.get(nodeId) ?? new Set());
+        nodes.set(nodeId, {
+            id: nodeId,
+            actionType,
+            actionVersion,
+            displayName,
+            depth: 0,
+            inputs: inputRefs,
+            rawAction: action,
+            runIf,
+            categories: Array.isArray(categories) ? categories : undefined,
+            isTrigger,
+            hasSideEffects,
+        });
+    }
+    // ── Pass 2: BFS depth from trigger ───────────────────────────────────────
+    if (trigger) {
+        const visited = new Set();
+        const queue = [{ node: trigger, depth: 0 }];
+        while (queue.length > 0) {
+            const { node, depth } = queue.shift();
+            if (visited.has(node))
+                continue;
+            visited.add(node);
+            const graphNode = nodes.get(node);
+            if (graphNode) {
+                graphNode.depth = depth;
+            }
+            for (const child of forward.get(node) ?? []) {
+                if (!visited.has(child)) {
+                    queue.push({ node: child, depth: depth + 1 });
+                }
+            }
+        }
+    }
+    // ── Pass 3: Parse output mappings ────────────────────────────────────────
+    const outputMappings = [];
+    const results = workflowDef.results ?? {};
+    for (const resultDef of Object.values(results)) {
+        if (resultDef && typeof resultDef === "object") {
+            outputMappings.push({
+                nodeId: resultDef.actionName,
+                output: resultDef.outputName,
+            });
+        }
+    }
+    // ── Pass 4: Parse enumTypes ──────────────────────────────────────────────
+    const enumTypes = [];
+    const rawEnumTypes = workflowDef.enumTypes ?? [];
+    for (const et of rawEnumTypes) {
+        const name = extractEnumTypeName(et);
+        const options = (et.options ?? et.values ?? []);
+        if (name) {
+            enumTypes.push({
+                name,
+                values: options.filter(o => typeof o.name === "string").map(o => o.name),
+            });
+        }
+    }
+    return {
+        nodes,
+        edges,
+        forward,
+        reverse,
+        trigger,
+        outputMappings,
+        enumTypes,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * BFS from trigger, returning the set of reachable node IDs.
+ */
+export function getReachableNodes(graph) {
+    if (!graph.trigger)
+        return new Set();
+    const visited = new Set();
+    const queue = [graph.trigger];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        if (visited.has(node))
+            continue;
+        visited.add(node);
+        for (const child of graph.forward.get(node) ?? []) {
+            if (!visited.has(child)) {
+                queue.push(child);
+            }
+        }
+    }
+    return visited;
+}
+/**
+ * Topological ordering via Kahn's algorithm.
+ * Returns node IDs in dependency order (parents before children).
+ */
+export function getTopologicalOrder(graph) {
+    if (graph.nodes.size === 0)
+        return [];
+    // Calculate in-degrees
+    const inDegree = new Map();
+    for (const nodeId of graph.nodes.keys()) {
+        inDegree.set(nodeId, 0);
+    }
+    for (const edge of graph.edges) {
+        inDegree.set(edge.target, (inDegree.get(edge.target) ?? 0) + 1);
+    }
+    // Seed queue with zero-in-degree nodes
+    const queue = [];
+    for (const [nodeId, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(nodeId);
+        }
+    }
+    const result = [];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        result.push(node);
+        for (const child of graph.forward.get(node) ?? []) {
+            const newDegree = (inDegree.get(child) ?? 1) - 1;
+            inDegree.set(child, newDegree);
+            if (newDegree === 0) {
+                queue.push(child);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Filter graph nodes by one or more action types.
+ */
+export function getNodesByType(graph, ...types) {
+    const typeSet = new Set(types);
+    const result = [];
+    for (const node of graph.nodes.values()) {
+        if (typeSet.has(node.actionType)) {
+            result.push(node);
+        }
+    }
+    return result;
+}
+/**
+ * Get IDs of nodes that consume outputs from the given node.
+ */
+export function getOutputConsumers(graph, nodeId) {
+    const children = graph.forward.get(nodeId);
+    if (!children)
+        return [];
+    return [...children];
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function extractActionType(action) {
+    const actionDef = action.action;
+    const actionName = actionDef?.name;
+    if (typeof actionName === "string")
+        return actionName;
+    if (actionName && typeof actionName === "object") {
+        return actionName.name ?? "unknown";
+    }
+    return "unknown";
+}
+function extractActionVersion(action) {
+    const actionDef = action.action;
+    return actionDef?.version ?? "";
+}
+function extractDisplayName(action) {
+    const ds = action.displaySettings;
+    return ds?.displayName ?? action.name ?? "";
+}
+function classifySideEffects(actionType) {
+    if (TRIGGER_TYPES.has(actionType))
+        return false;
+    if (SIDE_EFFECT_FREE.has(actionType))
+        return false;
+    if (SIDE_EFFECT_ACTIONS.has(actionType))
+        return true;
+    // Unknown → assume has side effects (safe default)
+    return true;
+}
+function parseRunIf(runIf) {
+    if (!runIf)
+        return undefined;
+    const lhs = runIf.lhs;
+    if (!lhs?.actionOutput)
+        return undefined;
+    const actionOutput = lhs.actionOutput;
+    const rhs = runIf.rhs;
+    const inlineRhs = rhs?.inline;
+    return {
+        sourceNode: actionOutput.actionName,
+        sourceOutput: actionOutput.output ?? "",
+        operator: runIf.operator ?? 0,
+        value: inlineRhs?.enumValue ?? "",
+    };
+}
+function extractEnumTypeName(et) {
+    const rawName = et.name;
+    if (typeof rawName === "string")
+        return rawName;
+    if (rawName && typeof rawName === "object") {
+        const nameObj = rawName;
+        if (typeof nameObj.name === "string")
+            return nameObj.name;
+        if (nameObj.name && typeof nameObj.name === "object") {
+            const nestedName = nameObj.name;
+            if (typeof nestedName.name === "string")
+                return nestedName.name;
+        }
+    }
+    return undefined;
+}
+function addEdge(edges, forward, reverse, source, target, sourceOutput, targetInput) {
+    edges.push({ source, target, sourceOutput, targetInput });
+    if (!forward.has(source))
+        forward.set(source, new Set());
+    forward.get(source).add(target);
+    if (!reverse.has(target))
+        reverse.set(target, new Set());
+    reverse.get(target).add(source);
+}

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

@@ -1,9 +1,15 @@
 /**
- * Workflow Optimizer - Proactive Intelligence Engine
+ * @deprecated Use `workflow-graph-optimizer.ts` instead.
  *
- * Goes beyond issue detection to find optimization opportunities,
- * suggest improvements, and calculate workflow health scores.
- * This is the "brains" that makes workflows better.
+ * This file contains the legacy heuristic-based optimizer (health scores,
+ * recommendations, scoring). It is superseded by the deterministic graph
+ * optimizer which provides:
+ *   - Shared typed graph (`workflow-graph.ts`)
+ *   - Provably safe auto-fix transforms (`workflow-graph-transforms.ts`)
+ *   - Convergence-based orchestrator (`workflow-graph-optimizer.ts`)
+ *
+ * Remaining consumer: `test/intelligence-layer.test.ts` (legacy tests).
+ * Remove this file once that test is migrated or deleted.
  */
 // ─────────────────────────────────────────────────────────────────────────────
 // Main Entry Point

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)",
@@ -340,6 +335,37 @@ export const TOOL_GUIDANCE = {
         ],
         applicableRules: ["preview-before-deploy"],
     },
+    toolkit_feedback: {
+        toolName: "toolkit_feedback",
+        quickTip: "Submit feedback to help improve the MCP toolkit. Report gaps, confusion, successes, or suggestions.",
+        operations: [
+            {
+                name: "Submit feedback",
+                description: "Report an issue or positive experience",
+                example: 'toolkit_feedback(method="submit", category="gap", message="Missing docs on X")',
+            },
+            {
+                name: "List feedback",
+                description: "View recent feedback entries",
+                example: 'toolkit_feedback(method="list")',
+            },
+            {
+                name: "Analyze feedback",
+                description: "Aggregate feedback into actionable insights",
+                example: 'toolkit_feedback(method="analyze")',
+            },
+        ],
+        nextSteps: {
+            submit: "Continue with your task. Your feedback will be reviewed to improve the toolkit.",
+            list: "Review entries and use analyze for aggregated insights.",
+            analyze: "Address actionable_items by updating guidance, resources, or patterns documentation.",
+        },
+        commonMistakes: [
+            "Forgetting to include which tool/operation the feedback is about",
+            "Not describing what you were trying to accomplish (use context parameter)",
+        ],
+        applicableRules: [],
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Contextual Tips (for tool responses)
@@ -352,19 +378,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",
@@ -385,14 +405,17 @@ export const CONTEXTUAL_TIPS = [
  * Generate server instructions from rules.
  * These are injected into the MCP init response and should be concise.
  */
-export function generateServerInstructions() {
+export function generateServerInstructions(buildInfo) {
     const critical = GUIDANCE_RULES.filter((r) => r.level === "critical");
     const important = GUIDANCE_RULES.filter((r) => r.level === "important");
-    return `# Ema MCP Toolkit
+    const versionLine = buildInfo
+        ? `\n> Build: ${buildInfo.version}${buildInfo.commit ? ` (${buildInfo.commit})` : ""}\n`
+        : "";
+    return `# Ema MCP Toolkit${versionLine}
 
 ## 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
 
@@ -416,6 +439,15 @@ The LLM generates the full workflow_def. MCP provides data and executes.
 - \`ema://catalog/agents-summary\` - Action catalog
 - \`ema://rules/anti-patterns\` - Common mistakes
 
+## Feedback Welcome
+Help us improve! Use \`toolkit_feedback\` to report issues or successes:
+- **Missing docs**: \`toolkit_feedback(method="submit", category="gap", message="...")\`
+- **Confusing guidance**: \`toolkit_feedback(method="submit", category="confusion", message="...")\`
+- **Something worked well**: \`toolkit_feedback(method="submit", category="success", message="...")\`
+- **Unclear error**: \`toolkit_feedback(method="submit", category="error_unclear", tool="...", message="...")\`
+
+Your feedback is automatically collected and analyzed to improve the toolkit for all agents.
+
 ## Need Help?
 Use the \`toolkit_onboard\` prompt for comprehensive guidance.
 `;
@@ -556,22 +588,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/feedback/index.js

@@ -0,0 +1,139 @@
+/**
+ * Feedback Handler - Agent feedback collection and analysis
+ *
+ * Enables a self-improving loop where agents that USE the MCP toolkit
+ * can report gaps, confusion, successes, and suggestions.
+ *
+ * Methods:
+ * - submit  - Agent reports feedback
+ * - list    - View recent feedback entries
+ * - analyze - Aggregate feedback + telemetry into actionable insights
+ * - rotate  - Manually trigger log rotation
+ */
+import { errorResult } from "../types.js";
+import { submitFeedback, listFeedback, listTelemetry, analyzeFeedback, rotateLogs, } from "./store.js";
+const VALID_CATEGORIES = [
+    "gap",
+    "confusion",
+    "success",
+    "error_unclear",
+    "suggestion",
+];
+const VALID_SEVERITIES = ["low", "medium", "high"];
+/** Max lengths to prevent oversized entries from consuming disk/memory */
+const MAX_MESSAGE_LENGTH = 2000;
+const MAX_CONTEXT_LENGTH = 1000;
+const MAX_FIELD_LENGTH = 100;
+/** Truncate a string to maxLen, appending "..." if truncated */
+function truncate(value, maxLen) {
+    return value.length > maxLen ? value.slice(0, maxLen) + "..." : value;
+}
+/**
+ * Handle toolkit_feedback tool requests.
+ */
+export async function handleFeedback(args) {
+    const method = args.method ? String(args.method) : "submit";
+    switch (method) {
+        case "submit":
+            return handleSubmit(args);
+        case "list":
+            return handleList(args);
+        case "analyze":
+            return handleAnalyze();
+        case "rotate":
+            return handleRotate();
+        default:
+            return errorResult(`Unknown feedback method: ${method}`, {
+                hint: "Available methods: submit, list, analyze, rotate",
+            });
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Method handlers
+// ─────────────────────────────────────────────────────────────────────────────
+async function handleSubmit(args) {
+    const category = args.category ? String(args.category) : undefined;
+    const message = args.message ? String(args.message) : undefined;
+    if (!category) {
+        return errorResult("Missing required parameter: category", {
+            hint: `Valid categories: ${VALID_CATEGORIES.join(", ")}`,
+        });
+    }
+    if (!VALID_CATEGORIES.includes(category)) {
+        return errorResult(`Invalid category: ${category}`, {
+            hint: `Valid categories: ${VALID_CATEGORIES.join(", ")}`,
+        });
+    }
+    if (!message) {
+        return errorResult("Missing required parameter: message", {
+            hint: "Describe what you encountered, what was confusing, or what's missing.",
+        });
+    }
+    const severity = args.severity ? String(args.severity) : undefined;
+    if (severity && !VALID_SEVERITIES.includes(severity)) {
+        return errorResult(`Invalid severity: ${severity}`, {
+            hint: `Valid severities: ${VALID_SEVERITIES.join(", ")}`,
+        });
+    }
+    const entry = await submitFeedback({
+        category: category,
+        message: truncate(message, MAX_MESSAGE_LENGTH),
+        tool: args.tool ? truncate(String(args.tool), MAX_FIELD_LENGTH) : undefined,
+        operation: args.operation ? truncate(String(args.operation), MAX_FIELD_LENGTH) : undefined,
+        context: args.context ? truncate(String(args.context), MAX_CONTEXT_LENGTH) : undefined,
+        severity: severity,
+    });
+    return {
+        success: true,
+        feedback_id: entry.id,
+        message: "Feedback recorded. Thank you for helping improve the toolkit!",
+        _tip: "Your feedback helps us identify documentation gaps and improve guidance for all agents.",
+    };
+}
+async function handleList(args) {
+    const categoryStr = args.category ? String(args.category) : undefined;
+    if (categoryStr && !VALID_CATEGORIES.includes(categoryStr)) {
+        return errorResult(`Invalid category filter: ${categoryStr}`, {
+            hint: `Valid categories: ${VALID_CATEGORIES.join(", ")}`,
+        });
+    }
+    const category = categoryStr;
+    const limit = args.limit ? Number(args.limit) : 50;
+    const includeTelemetry = args.include_telemetry === true;
+    const feedback = await listFeedback({ limit, category });
+    const result = {
+        count: feedback.length,
+        feedback,
+    };
+    if (includeTelemetry) {
+        const telemetry = await listTelemetry({ limit });
+        result.telemetry = {
+            count: telemetry.length,
+            entries: telemetry,
+        };
+    }
+    if (feedback.length === 0) {
+        result._tip = "No feedback recorded yet. Agents can submit feedback using toolkit_feedback(method='submit', category='...', message='...').";
+    }
+    return result;
+}
+async function handleAnalyze() {
+    const analysis = await analyzeFeedback();
+    return {
+        ...analysis,
+        _tip: analysis.actionable_items.length > 0
+            ? `Found ${analysis.actionable_items.length} actionable item(s). Review and address these to improve agent experience.`
+            : "No actionable items found. Feedback data may be limited - encourage agents to submit feedback.",
+        _next_step: analysis.actionable_items.length > 0
+            ? "Review actionable_items and update guidance.ts or resources.ts accordingly."
+            : "Continue collecting feedback. Use toolkit_feedback(method='list') to review individual entries.",
+    };
+}
+async function handleRotate() {
+    const result = await rotateLogs();
+    return {
+        success: true,
+        ...result,
+        message: "Log files rotated successfully.",
+    };
+}