@ema.co/mcp-toolkit 1.5.2 → 1.7.0

package/dist/sdk/workflow-tracer.js

@@ -0,0 +1,648 @@
+/**
+ * Workflow Flow Tracer
+ *
+ * Simulates and visualizes how data flows through a workflow,
+ * helping debug and understand execution paths.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Latency Estimates (based on typical Ema platform metrics)
+// ─────────────────────────────────────────────────────────────────────────────
+const LATENCY_ESTIMATES = {
+    // Trigger - instant
+    "chat_trigger": 10,
+    "voice_trigger": 10,
+    // Categorizers - LLM call
+    "chat_categorizer": 800,
+    "text_categorizer": 600,
+    // Search - depends on index size
+    "search": 500,
+    "live_web_search": 2000,
+    "knowledge_search": 500,
+    // LLM calls
+    "call_llm": 1500,
+    "respond_with_sources": 1200,
+    "conversation_to_search_query": 600,
+    // Entity extraction
+    "entity_extraction": 800,
+    "entity_extraction_with_documents": 1000,
+    // HITL - user dependent, estimate 30s average
+    "general_hitl": 30000,
+    "human_collaboration": 30000,
+    // External actions
+    "send_email_agent": 1000,
+    "external_action_caller": 2000,
+    // Quick operations
+    "json_mapper": 50,
+    "fixed_response": 50,
+    "custom_agent": 500,
+    // Default
+    "default": 500,
+};
+function estimateLatency(actionType) {
+    const normalized = actionType.toLowerCase();
+    for (const [pattern, latency] of Object.entries(LATENCY_ESTIMATES)) {
+        if (normalized.includes(pattern)) {
+            return latency;
+        }
+    }
+    return LATENCY_ESTIMATES.default;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Type Detection
+// ─────────────────────────────────────────────────────────────────────────────
+const TYPE_NAMES = {
+    "CHAT_CONVERSATION": "Chat History",
+    "TEXT_WITH_SOURCES": "Text + Sources",
+    "WELL_KNOWN_TYPE_ANY": "Any",
+    "DOCUMENT": "Document",
+    "FILE_PATH": "File Path",
+    "EMAIL": "Email",
+    "JSON": "JSON Object",
+};
+function friendlyTypeName(type) {
+    return TYPE_NAMES[type] || type.replace(/WELL_KNOWN_TYPE_/g, "").replace(/_/g, " ");
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Sample Values (for simulation)
+// ─────────────────────────────────────────────────────────────────────────────
+const SAMPLE_VALUES = {
+    "chat_conversation": '{"messages": [{"role": "user", "content": "What is my account balance?"}]}',
+    "user_query": "What is my account balance?",
+    "summarized_conversation": "User is asking about their account balance",
+    "search_results": '[{"title": "Account FAQ", "content": "...", "score": 0.95}]',
+    "response_with_sources": "Your account balance is $1,234.56 [Source: Account System]",
+    "email_address": "customer@example.com",
+    "email_body": "Dear Customer, Your account balance is $1,234.56...",
+    "hitl_status": "HITL Success",
+    "category": "Account Inquiry",
+};
+function getSampleValue(outputName) {
+    const normalized = outputName.toLowerCase().replace(/_/g, "");
+    for (const [pattern, value] of Object.entries(SAMPLE_VALUES)) {
+        if (normalized.includes(pattern.toLowerCase().replace(/_/g, ""))) {
+            return value.length > 50 ? value.slice(0, 47) + "..." : value;
+        }
+    }
+    return `<${outputName}>`;
+}
+/**
+ * Trace execution flow through a workflow
+ */
+export function traceWorkflow(workflowDef) {
+    const workflow = workflowDef;
+    const actions = workflow.actions || [];
+    // Build dependency graph
+    const graph = buildDependencyGraph(actions);
+    // Find all paths from trigger to outputs
+    const paths = findAllPaths(actions, graph, workflow.results || {});
+    // Calculate stats
+    const stats = calculateStats(paths, actions);
+    // Generate visualizations
+    const ascii = generateAsciiFlow(paths);
+    const mermaid = generateMermaidDiagram(actions, graph);
+    // Detect trigger type
+    const trigger = actions.find(a => a.action?.name?.name?.includes("trigger") || a.name?.includes("trigger"));
+    const triggerType = trigger?.action?.name?.name?.includes("voice") ? "voice" : "chat";
+    return {
+        workflowName: "Workflow",
+        triggerType,
+        paths,
+        stats,
+        ascii,
+        mermaid,
+    };
+}
+function buildDependencyGraph(actions) {
+    const dependencies = new Map();
+    const dependents = new Map();
+    const outputs = new Map();
+    const conditions = new Map();
+    for (const action of actions) {
+        const nodeName = action.name;
+        dependencies.set(nodeName, new Set());
+        if (!dependents.has(nodeName)) {
+            dependents.set(nodeName, new Set());
+        }
+        // Parse inputs to find dependencies
+        if (action.inputs) {
+            for (const [inputName, binding] of Object.entries(action.inputs)) {
+                const bindingObj = binding;
+                const actionOutput = bindingObj?.actionOutput;
+                if (actionOutput?.actionName) {
+                    dependencies.get(nodeName).add(actionOutput.actionName);
+                    if (!dependents.has(actionOutput.actionName)) {
+                        dependents.set(actionOutput.actionName, new Set());
+                    }
+                    dependents.get(actionOutput.actionName).add(nodeName);
+                }
+            }
+        }
+        // Parse runIf conditions
+        if (action.runIf) {
+            if (action.runIf.enum) {
+                conditions.set(nodeName, `${action.runIf.enum.enumType}: ${action.runIf.enum.enumValue}`);
+            }
+            else if (action.runIf.actionOutput) {
+                conditions.set(nodeName, `${action.runIf.actionOutput.actionName}.${action.runIf.actionOutput.output}`);
+                dependencies.get(nodeName).add(action.runIf.actionOutput.actionName);
+            }
+        }
+        // Determine outputs
+        const actionType = action.action?.name?.name || action.name;
+        const nodeOutputs = inferOutputs(actionType, action);
+        outputs.set(nodeName, nodeOutputs);
+    }
+    return { dependencies, dependents, outputs, conditions };
+}
+function inferOutputs(actionType, action) {
+    const type = actionType.toLowerCase();
+    if (type.includes("categorizer")) {
+        // Categorizers output a category enum
+        const categories = action.typeArguments?.categories;
+        if (Array.isArray(categories)) {
+            return categories.map(c => c.name);
+        }
+        // Categories might be in a different format
+        return ["category"];
+    }
+    if (type.includes("search")) {
+        return ["search_results", "combined_results"];
+    }
+    if (type.includes("respond_with_sources") || type.includes("call_llm")) {
+        return ["response_with_sources", "generated_content"];
+    }
+    if (type.includes("entity_extraction")) {
+        return ["email_address", "phone_number", "extracted_fields"];
+    }
+    if (type.includes("hitl") || type.includes("human_collaboration")) {
+        return ["hitl_status", "human_input"];
+    }
+    if (type.includes("conversation_to_search") || type.includes("summarizer")) {
+        return ["summarized_conversation", "search_query"];
+    }
+    if (type.includes("trigger")) {
+        return ["chat_conversation", "user_query"];
+    }
+    return ["output"];
+}
+function findAllPaths(actions, graph, results) {
+    const paths = [];
+    // Find trigger node
+    const trigger = actions.find(a => a.action?.name?.name?.includes("trigger") || a.name?.includes("trigger"));
+    if (!trigger) {
+        return [{
+                name: "No Trigger",
+                steps: [],
+                totalLatencyMs: 0,
+                llmCalls: 0,
+                externalCalls: 0,
+                hasHitl: false,
+                sendsEmail: false,
+            }];
+    }
+    // Find categorizers (branching points)
+    const categorizers = actions.filter(a => a.action?.name?.name?.includes("categorizer") || a.name?.includes("categorizer"));
+    if (categorizers.length === 0) {
+        // Linear workflow - single path
+        const steps = buildLinearPath(actions, graph, trigger.name);
+        paths.push(createFlowPath("Main Flow", steps, actions));
+    }
+    else {
+        // Branching workflow - trace each branch
+        for (const categorizer of categorizers) {
+            const categories = categorizer.typeArguments?.categories;
+            if (Array.isArray(categories)) {
+                for (const category of categories) {
+                    const branchSteps = buildBranchPath(actions, graph, trigger.name, categorizer.name, category.name);
+                    paths.push(createFlowPath(`Branch: ${category.name}`, branchSteps, actions));
+                }
+            }
+            else {
+                // Single categorizer path if categories not properly defined
+                const steps = buildLinearPath(actions, graph, trigger.name);
+                paths.push(createFlowPath(`Via ${categorizer.displaySettings?.displayName || categorizer.name}`, steps, actions));
+            }
+        }
+    }
+    // If no paths were found, create a default main flow
+    if (paths.length === 0) {
+        const steps = buildLinearPath(actions, graph, trigger.name);
+        paths.push(createFlowPath("Main Flow", steps, actions));
+    }
+    return paths;
+}
+function buildLinearPath(actions, graph, startNode) {
+    const steps = [];
+    const visited = new Set();
+    const queue = [startNode];
+    let stepNum = 1;
+    while (queue.length > 0) {
+        const nodeName = queue.shift();
+        if (visited.has(nodeName))
+            continue;
+        visited.add(nodeName);
+        const action = actions.find(a => a.name === nodeName);
+        if (!action)
+            continue;
+        steps.push(createFlowStep(stepNum++, action, graph));
+        // Add dependents to queue
+        const dependents = graph.dependents.get(nodeName) || new Set();
+        for (const dep of dependents) {
+            if (!visited.has(dep)) {
+                queue.push(dep);
+            }
+        }
+    }
+    return steps;
+}
+function buildBranchPath(actions, graph, startNode, categorizerName, categoryName) {
+    const steps = [];
+    const visited = new Set();
+    const queue = [startNode];
+    let stepNum = 1;
+    while (queue.length > 0) {
+        const nodeName = queue.shift();
+        if (visited.has(nodeName))
+            continue;
+        visited.add(nodeName);
+        const action = actions.find(a => a.name === nodeName);
+        if (!action)
+            continue;
+        // Check if this node has a runIf condition that matches our branch
+        const condition = graph.conditions.get(nodeName);
+        if (condition) {
+            // Skip nodes that are conditioned on different categories
+            const isCategoryCondition = condition.includes(categorizerName);
+            if (isCategoryCondition && !condition.includes(categoryName)) {
+                continue; // Skip this branch
+            }
+        }
+        const step = createFlowStep(stepNum++, action, graph);
+        step.branch = categoryName;
+        steps.push(step);
+        // Add dependents to queue
+        const dependents = graph.dependents.get(nodeName) || new Set();
+        for (const dep of dependents) {
+            if (!visited.has(dep)) {
+                queue.push(dep);
+            }
+        }
+    }
+    return steps;
+}
+function createFlowStep(step, action, graph) {
+    const actionType = action.action?.name?.name || action.name || "unknown";
+    const displayName = action.displaySettings?.displayName || action.name;
+    // Build inputs
+    const inputs = [];
+    if (action.inputs) {
+        for (const [name, binding] of Object.entries(action.inputs)) {
+            const bindingObj = binding;
+            const actionOutput = bindingObj?.actionOutput;
+            inputs.push({
+                name,
+                source: actionOutput ? `${actionOutput.actionName}.${actionOutput.output}` : "static",
+                type: friendlyTypeName("TEXT_WITH_SOURCES"),
+                sampleValue: actionOutput ? getSampleValue(actionOutput.output || "") : undefined,
+            });
+        }
+    }
+    // Build outputs
+    const outputNames = graph.outputs.get(action.name) || ["output"];
+    const consumers = Array.from(graph.dependents.get(action.name) || []);
+    const outputs = outputNames.map(name => ({
+        name,
+        type: friendlyTypeName("TEXT_WITH_SOURCES"),
+        consumers,
+        sampleValue: getSampleValue(name),
+    }));
+    // Get condition
+    const condition = graph.conditions.get(action.name);
+    // Get notes
+    const notes = [];
+    if (actionType.includes("hitl") || actionType.includes("human")) {
+        notes.push("⏸️ Waits for human approval");
+    }
+    if (actionType.includes("email")) {
+        notes.push("📧 Sends external email");
+    }
+    if (actionType.includes("external_action")) {
+        notes.push("🔌 Calls external API");
+    }
+    return {
+        step,
+        node: action.name,
+        displayName,
+        actionType,
+        inputs,
+        outputs,
+        condition,
+        estimatedLatencyMs: estimateLatency(actionType),
+        notes: notes.length > 0 ? notes : undefined,
+    };
+}
+function createFlowPath(name, steps, actions) {
+    const totalLatencyMs = steps.reduce((sum, s) => sum + (s.estimatedLatencyMs || 0), 0);
+    const llmCalls = steps.filter(s => s.actionType.includes("categorizer") ||
+        s.actionType.includes("call_llm") ||
+        s.actionType.includes("respond")).length;
+    const externalCalls = steps.filter(s => s.actionType.includes("email") ||
+        s.actionType.includes("external_action")).length;
+    const hasHitl = steps.some(s => s.actionType.includes("hitl") || s.actionType.includes("human"));
+    const sendsEmail = steps.some(s => s.actionType.includes("email"));
+    return {
+        name,
+        steps,
+        totalLatencyMs,
+        llmCalls,
+        externalCalls,
+        hasHitl,
+        sendsEmail,
+    };
+}
+function calculateStats(paths, actions) {
+    const allNodeNames = new Set(actions.map(a => a.name));
+    const pathNodeSets = paths.map(p => new Set(p.steps.map(s => s.node)));
+    // Nodes in ALL paths
+    const commonNodes = Array.from(allNodeNames).filter(node => pathNodeSets.every(set => set.has(node)));
+    // Nodes in SOME but not all paths
+    const optionalNodes = Array.from(allNodeNames).filter(node => pathNodeSets.some(set => set.has(node)) && !commonNodes.includes(node));
+    const pathLengths = paths.map(p => p.steps.length);
+    const latencies = paths.map(p => p.totalLatencyMs);
+    return {
+        totalNodes: allNodeNames.size,
+        uniquePaths: paths.length,
+        maxDepth: Math.max(...pathLengths),
+        avgPathLength: pathLengths.reduce((a, b) => a + b, 0) / pathLengths.length,
+        commonNodes,
+        optionalNodes,
+        minLatencyMs: Math.min(...latencies),
+        maxLatencyMs: Math.max(...latencies),
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Visualization: ASCII
+// ─────────────────────────────────────────────────────────────────────────────
+function generateAsciiFlow(paths) {
+    const lines = [];
+    lines.push("╔══════════════════════════════════════════════════════════════════╗");
+    lines.push("║                     WORKFLOW EXECUTION FLOW                       ║");
+    lines.push("╚══════════════════════════════════════════════════════════════════╝");
+    lines.push("");
+    for (const path of paths) {
+        lines.push(`━━━ ${path.name} ━━━`);
+        lines.push(`    Latency: ~${formatLatency(path.totalLatencyMs)} | LLM calls: ${path.llmCalls} | External: ${path.externalCalls}`);
+        if (path.hasHitl)
+            lines.push("    ⏸️  Human approval required");
+        if (path.sendsEmail)
+            lines.push("    📧 Sends email");
+        lines.push("");
+        for (let i = 0; i < path.steps.length; i++) {
+            const step = path.steps[i];
+            const isLast = i === path.steps.length - 1;
+            // Node box
+            const icon = getNodeIcon(step.actionType);
+            const latency = step.estimatedLatencyMs ? ` (~${step.estimatedLatencyMs}ms)` : "";
+            lines.push(`    ┌─────────────────────────────────────────┐`);
+            lines.push(`    │ ${icon} ${step.displayName.slice(0, 35).padEnd(35)} │`);
+            lines.push(`    │   ${step.actionType.slice(0, 37).padEnd(37)} │`);
+            // Show inputs
+            if (step.inputs.length > 0) {
+                lines.push(`    │   ← ${step.inputs.map(i => i.source).join(", ").slice(0, 33).padEnd(33)} │`);
+            }
+            // Show condition
+            if (step.condition) {
+                lines.push(`    │   🔀 if: ${step.condition.slice(0, 28).padEnd(28)} │`);
+            }
+            // Show outputs  
+            if (step.outputs.length > 0 && step.outputs[0].consumers.length > 0) {
+                lines.push(`    │   → ${step.outputs[0].consumers.join(", ").slice(0, 33).padEnd(33)} │`);
+            }
+            lines.push(`    └─────────────────────────────────────────┘`);
+            if (!isLast) {
+                lines.push("              │");
+                lines.push("              ▼");
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function getNodeIcon(actionType) {
+    const type = actionType.toLowerCase();
+    if (type.includes("trigger"))
+        return "🎯";
+    if (type.includes("categorizer"))
+        return "🔀";
+    if (type.includes("search"))
+        return "🔍";
+    if (type.includes("llm") || type.includes("respond"))
+        return "🤖";
+    if (type.includes("hitl") || type.includes("human"))
+        return "👤";
+    if (type.includes("email"))
+        return "📧";
+    if (type.includes("entity_extraction"))
+        return "📋";
+    if (type.includes("external"))
+        return "🔌";
+    return "⚙️";
+}
+function formatLatency(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${(ms / 60000).toFixed(1)}m`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Visualization: Mermaid
+// ─────────────────────────────────────────────────────────────────────────────
+function generateMermaidDiagram(actions, graph) {
+    const lines = [];
+    lines.push("```mermaid");
+    lines.push("flowchart TD");
+    // Define nodes
+    for (const action of actions) {
+        const type = action.action?.name?.name || action.name;
+        const displayName = action.displaySettings?.displayName || action.name;
+        const icon = getNodeIcon(type);
+        // Node shape based on type
+        if (type.includes("trigger")) {
+            lines.push(`    ${action.name}(("${icon} ${displayName}"))`);
+        }
+        else if (type.includes("categorizer")) {
+            lines.push(`    ${action.name}{{"${icon} ${displayName}"}}`);
+        }
+        else if (type.includes("hitl") || type.includes("human")) {
+            lines.push(`    ${action.name}[/"${icon} ${displayName}"/]`);
+        }
+        else if (type.includes("email") || type.includes("external")) {
+            lines.push(`    ${action.name}[["${icon} ${displayName}"]]`);
+        }
+        else {
+            lines.push(`    ${action.name}["${icon} ${displayName}"]`);
+        }
+    }
+    lines.push("");
+    // Define edges
+    for (const action of actions) {
+        const deps = graph.dependencies.get(action.name) || new Set();
+        const condition = graph.conditions.get(action.name);
+        for (const dep of deps) {
+            if (condition) {
+                // Extract just the category name from condition
+                const label = condition.split(":").pop()?.trim() || condition;
+                lines.push(`    ${dep} -->|${label}| ${action.name}`);
+            }
+            else {
+                lines.push(`    ${dep} --> ${action.name}`);
+            }
+        }
+    }
+    lines.push("```");
+    return lines.join("\n");
+}
+/**
+ * Generate a detailed trace with sample data showing what happens at each step
+ */
+export function generateDetailedTrace(path) {
+    const steps = [];
+    // Accumulate outputs as we go (simulate data flow)
+    const availableData = {
+        "trigger.chat_conversation": '{"messages": [{"role": "user", "content": "What is my account balance?"}]}',
+        "trigger.user_query": "What is my account balance?",
+    };
+    for (const flowStep of path.steps) {
+        // Gather inputs for this step
+        const inputData = {};
+        for (const input of flowStep.inputs) {
+            inputData[input.name] = availableData[input.source] || input.sampleValue || `<from ${input.source}>`;
+        }
+        // Generate outputs for this step
+        const outputData = {};
+        for (const output of flowStep.outputs) {
+            const value = output.sampleValue || getSampleValue(output.name);
+            outputData[output.name] = value;
+            // Make available for downstream nodes
+            availableData[`${flowStep.node}.${output.name}`] = value;
+        }
+        steps.push({
+            step: flowStep.step,
+            node: flowStep.node,
+            description: generateStepDescription(flowStep, inputData),
+            inputData,
+            outputData,
+            timing: `~${flowStep.estimatedLatencyMs || 500}ms`,
+        });
+    }
+    return {
+        pathName: path.name,
+        steps,
+    };
+}
+function generateStepDescription(step, inputData) {
+    const type = step.actionType.toLowerCase();
+    if (type.includes("trigger")) {
+        return "📥 Receive user message and start workflow";
+    }
+    if (type.includes("categorizer")) {
+        return `🔀 Analyze message to determine intent category`;
+    }
+    if (type.includes("search")) {
+        const query = Object.values(inputData)[0] || "user query";
+        return `🔍 Search knowledge base for: "${query.slice(0, 30)}..."`;
+    }
+    if (type.includes("respond") || type.includes("call_llm")) {
+        return "🤖 Generate response using LLM with search results";
+    }
+    if (type.includes("entity_extraction")) {
+        return "📋 Extract structured data (email, phone, etc.) from conversation";
+    }
+    if (type.includes("hitl") || type.includes("human")) {
+        return "👤 WAIT for human approval before proceeding";
+    }
+    if (type.includes("email")) {
+        return "📧 Send email to extracted recipient";
+    }
+    if (type.includes("summarizer") || type.includes("conversation_to")) {
+        return "📝 Summarize conversation into search query";
+    }
+    return `⚙️ Execute ${step.displayName}`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Format Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Format a flow trace as readable text
+ */
+export function formatFlowTrace(trace) {
+    const lines = [];
+    lines.push("# Workflow Flow Analysis");
+    lines.push("");
+    lines.push(`**Trigger**: ${trace.triggerType}`);
+    lines.push(`**Total Nodes**: ${trace.stats.totalNodes}`);
+    lines.push(`**Unique Paths**: ${trace.stats.uniquePaths}`);
+    lines.push(`**Latency Range**: ${formatLatency(trace.stats.minLatencyMs)} - ${formatLatency(trace.stats.maxLatencyMs)}`);
+    lines.push("");
+    lines.push("## Common Nodes (all paths)");
+    lines.push(trace.stats.commonNodes.map(n => `- ${n}`).join("\n") || "- None");
+    lines.push("");
+    lines.push("## Branch-Specific Nodes");
+    lines.push(trace.stats.optionalNodes.map(n => `- ${n}`).join("\n") || "- None");
+    lines.push("");
+    lines.push("## Execution Paths");
+    for (const path of trace.paths) {
+        lines.push(`\n### ${path.name}`);
+        lines.push(`- **Steps**: ${path.steps.length}`);
+        lines.push(`- **Est. Latency**: ${formatLatency(path.totalLatencyMs)}`);
+        lines.push(`- **LLM Calls**: ${path.llmCalls}`);
+        lines.push(`- **External Calls**: ${path.externalCalls}`);
+        if (path.hasHitl)
+            lines.push("- ⚠️ **Requires human approval**");
+        if (path.sendsEmail)
+            lines.push("- 📧 **Sends email**");
+        lines.push("\n**Step-by-Step:**");
+        for (const step of path.steps) {
+            const condition = step.condition ? ` (if ${step.condition})` : "";
+            lines.push(`${step.step}. ${getNodeIcon(step.actionType)} **${step.displayName}**${condition}`);
+            if (step.inputs.length > 0) {
+                lines.push(`   - Inputs: ${step.inputs.map(i => `\`${i.name}\` ← ${i.source}`).join(", ")}`);
+            }
+        }
+    }
+    lines.push("\n---\n");
+    lines.push("## ASCII Flow");
+    lines.push("```");
+    lines.push(trace.ascii);
+    lines.push("```");
+    lines.push("\n## Mermaid Diagram");
+    lines.push(trace.mermaid);
+    return lines.join("\n");
+}
+/**
+ * Format a detailed trace as readable text
+ */
+export function formatDetailedTrace(trace) {
+    const lines = [];
+    lines.push(`# Detailed Execution: ${trace.pathName}`);
+    lines.push("");
+    for (const step of trace.steps) {
+        lines.push(`## Step ${step.step}: ${step.node}`);
+        lines.push(`**${step.description}** (${step.timing})`);
+        lines.push("");
+        lines.push("**Inputs:**");
+        for (const [name, value] of Object.entries(step.inputData)) {
+            lines.push(`- \`${name}\`: \`${value.slice(0, 60)}${value.length > 60 ? "..." : ""}\``);
+        }
+        lines.push("");
+        lines.push("**Outputs:**");
+        for (const [name, value] of Object.entries(step.outputData)) {
+            lines.push(`- \`${name}\`: \`${value.slice(0, 60)}${value.length > 60 ? "..." : ""}\``);
+        }
+        lines.push("");
+        lines.push("---");
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/sdk/workflow-transformer.js

@@ -14,6 +14,7 @@
  * - No brittle keyword matching
  */
 import { compileWorkflow } from "./workflow-generator.js";
+import { STRUCTURAL_RULES_FOR_LLM } from "./structural-rules.js";
 // ═══════════════════════════════════════════════════════════════════════════
 // SCHEMA DOCUMENTATION FOR LLM CONTEXT
 // ═══════════════════════════════════════════════════════════════════════════
@@ -263,7 +264,16 @@ inputs: { to_email: { type: "action_output", actionName: "entity_extraction", ou
 1. Find the categorizer node
 2. Add to the categories array
 3. Add a handler node with runIf condition for the new category
+
+${STRUCTURAL_RULES_FOR_LLM}
 `;
+/**
+ * Get the complete schema including structural validation rules.
+ * Use this for LLM context when generating or modifying workflows.
+ */
+export function getCompleteSchemaForLLM() {
+    return WORKFLOW_SCHEMA_FOR_LLM;
+}
 // ═══════════════════════════════════════════════════════════════════════════
 // DECOMPILER: workflow_def JSON → WorkflowSpec
 // ═══════════════════════════════════════════════════════════════════════════