@ema.co/mcp-toolkit 1.5.1 → 1.6.0

package/dist/sdk/workflow-validator.js

@@ -0,0 +1,391 @@
+/**
+ * API-Driven Workflow Validation
+ *
+ * Validates workflow specs against actual API definitions:
+ * - ListActions: Available actions with input/output schemas
+ * - GetPersonaTemplates: Available templates with configurations
+ * - OpenAPI spec: Endpoint contracts (optional, for payload validation)
+ *
+ * This ensures workflows are valid BEFORE deployment, catching errors early.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Schema Registry - Caches API definitions
+// ─────────────────────────────────────────────────────────────────────────────
+export class APISchemaRegistry {
+    actions = new Map();
+    templates = new Map();
+    loaded = false;
+    /**
+     * Load schemas from API
+     */
+    async load(client) {
+        const [actionDTOs, templateDTOs] = await Promise.all([
+            client.listActions().catch(() => []),
+            client.getPersonaTemplates().catch(() => []),
+        ]);
+        // Parse actions
+        for (const dto of actionDTOs) {
+            const schema = this.parseActionDTO(dto);
+            if (schema) {
+                this.actions.set(schema.name, schema);
+            }
+        }
+        // Parse templates
+        for (const dto of templateDTOs) {
+            const schema = this.parseTemplateDTO(dto);
+            if (schema) {
+                this.templates.set(schema.id, schema);
+            }
+        }
+        this.loaded = true;
+    }
+    isLoaded() {
+        return this.loaded;
+    }
+    getAction(name) {
+        return this.actions.get(name);
+    }
+    getTemplate(id) {
+        return this.templates.get(id);
+    }
+    getAllActions() {
+        return Array.from(this.actions.values());
+    }
+    getAllTemplates() {
+        return Array.from(this.templates.values());
+    }
+    /**
+     * Parse ActionDTO from ListActions API into ActionSchema
+     */
+    parseActionDTO(dto) {
+        try {
+            const typeName = dto.typeName;
+            const name = typeName?.name?.name;
+            if (!name)
+                return null;
+            const inputs = new Map();
+            const outputs = new Map();
+            // Parse inputs from dto.inputs.inputs
+            const inputsObj = dto.inputs?.inputs;
+            if (inputsObj && typeof inputsObj === "object") {
+                for (const [inputName, inputDef] of Object.entries(inputsObj)) {
+                    const def = inputDef;
+                    inputs.set(inputName, {
+                        name: inputName,
+                        type: def.type?.wellKnownType ?? "unknown",
+                        required: !def.isOptional,
+                        description: def.description ?? def.displayName,
+                    });
+                }
+            }
+            // Parse outputs from dto.outputs.outputs
+            const outputsObj = dto.outputs?.outputs;
+            if (outputsObj && typeof outputsObj === "object") {
+                for (const [outputName, outputDef] of Object.entries(outputsObj)) {
+                    const def = outputDef;
+                    outputs.set(outputName, {
+                        name: outputName,
+                        type: def.type?.wellKnownType ?? "unknown",
+                        description: def.description,
+                    });
+                }
+            }
+            // Get displayName - might be string or object with nested value
+            const displayName = typeof dto.displayName === "string"
+                ? dto.displayName
+                : dto.name ?? name;
+            // Get description - might be string or object
+            const description = typeof dto.description === "string"
+                ? dto.description
+                : "";
+            return {
+                name,
+                displayName: displayName,
+                description,
+                category: dto.category ?? "unknown",
+                version: typeName?.version ?? "v1",
+                inputs,
+                outputs,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Parse PersonaTemplateDTO from GetPersonaTemplates API
+     */
+    parseTemplateDTO(dto) {
+        try {
+            if (!dto.id)
+                return null;
+            // Determine type from template name or ID
+            let type = "chat";
+            const nameLower = (dto.name ?? "").toLowerCase();
+            if (nameLower.includes("voice"))
+                type = "voice";
+            else if (nameLower.includes("dashboard"))
+                type = "dashboard";
+            // Extract widget names from proto_config
+            const defaultWidgets = [];
+            const protoConfig = dto.proto_config;
+            if (protoConfig?.widgets) {
+                for (const widget of protoConfig.widgets) {
+                    if (widget.name)
+                        defaultWidgets.push(widget.name);
+                }
+            }
+            return {
+                id: dto.id,
+                name: dto.name ?? dto.id,
+                type,
+                description: dto.description,
+                defaultWidgets,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Workflow Validator
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Validate a WorkflowSpec against API schemas
+ */
+export function validateWorkflowSpec(spec, registry) {
+    const errors = [];
+    const warnings = [];
+    const usedActions = [];
+    const unknownActions = [];
+    // Build node map for reference checking
+    const nodeMap = new Map();
+    for (const node of spec.nodes) {
+        nodeMap.set(node.id, node);
+    }
+    // Check if registry actually has data - if not, skip action-specific validation
+    // (API may be unavailable or mocked)
+    const registryHasData = registry.isLoaded() && registry.getAllActions().length > 0;
+    // 1. Check for trigger node
+    const triggerTypes = ["chat_trigger", "document_trigger", "voice_trigger"];
+    const hasTrigger = spec.nodes.some(n => triggerTypes.includes(n.actionType));
+    if (!hasTrigger) {
+        errors.push({
+            type: "missing_trigger",
+            message: "Workflow must have a trigger node (chat_trigger, document_trigger)",
+            suggestion: "Add a trigger node as the first node in your workflow",
+        });
+    }
+    // 2. Validate each node
+    for (const node of spec.nodes) {
+        const actionSchema = registry.getAction(node.actionType);
+        // Schema-dependent validation (only when registry has data)
+        if (!actionSchema && registryHasData) {
+            // Action not found in API (only flag if we have data to check against)
+            unknownActions.push(node.actionType);
+            errors.push({
+                type: "missing_action",
+                node_id: node.id,
+                message: `Action "${node.actionType}" not found in API`,
+                suggestion: `Check ListActions for available actions. Similar: ${findSimilarActions(node.actionType, registry)}`,
+            });
+        }
+        else if (actionSchema) {
+            usedActions.push(node.actionType);
+            // Validate required inputs
+            for (const [inputName, inputSchema] of actionSchema.inputs) {
+                if (inputSchema.required && !node.inputs?.[inputName]) {
+                    errors.push({
+                        type: "missing_input",
+                        node_id: node.id,
+                        field: inputName,
+                        message: `Required input "${inputName}" missing on node "${node.id}" (${node.actionType})`,
+                        suggestion: `Add input "${inputName}" of type ${inputSchema.type}`,
+                    });
+                }
+            }
+            // Schema-aware input validation
+            if (node.inputs) {
+                for (const [inputName, binding] of Object.entries(node.inputs)) {
+                    const inputSchema = actionSchema.inputs.get(inputName);
+                    // Check if input exists on action
+                    if (!inputSchema && actionSchema.inputs.size > 0) {
+                        warnings.push({
+                            type: "suboptimal_wiring",
+                            node_id: node.id,
+                            message: `Input "${inputName}" may not exist on action "${node.actionType}"`,
+                            suggestion: `Valid inputs: ${Array.from(actionSchema.inputs.keys()).join(", ")}`,
+                        });
+                    }
+                }
+            }
+        }
+        // Schema-INDEPENDENT validation (ALWAYS runs - checks node references)
+        if (node.inputs) {
+            for (const [inputName, binding] of Object.entries(node.inputs)) {
+                // Validate action_output references - doesn't need schema
+                if (binding.type === "action_output" && binding.actionName) {
+                    const sourceNode = nodeMap.get(binding.actionName);
+                    if (!sourceNode) {
+                        errors.push({
+                            type: "invalid_wiring",
+                            node_id: node.id,
+                            field: inputName,
+                            message: `Input "${inputName}" references non-existent node "${binding.actionName}"`,
+                            suggestion: `Valid nodes: ${Array.from(nodeMap.keys()).join(", ")}`,
+                        });
+                    }
+                    else if (actionSchema) {
+                        // Output validation only if we have schema
+                        const sourceSchema = registry.getAction(sourceNode.actionType);
+                        if (sourceSchema && binding.output && !sourceSchema.outputs.has(binding.output)) {
+                            warnings.push({
+                                type: "suboptimal_wiring",
+                                node_id: node.id,
+                                message: `Output "${binding.output}" may not exist on action "${sourceNode.actionType}"`,
+                                suggestion: `Valid outputs: ${Array.from(sourceSchema.outputs.keys()).join(", ")}`,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // Validate runIf references - also schema-independent
+        if (node.runIf && "actionName" in node.runIf) {
+            const runIfNode = nodeMap.get(node.runIf.actionName);
+            if (!runIfNode) {
+                errors.push({
+                    type: "invalid_wiring",
+                    node_id: node.id,
+                    message: `runIf references non-existent node "${node.runIf.actionName}"`,
+                    suggestion: `Valid nodes: ${Array.from(nodeMap.keys()).join(", ")}`,
+                });
+            }
+        }
+    }
+    // 3. Validate result mappings
+    for (const mapping of spec.resultMappings) {
+        if (!nodeMap.has(mapping.nodeId)) {
+            errors.push({
+                type: "invalid_structure",
+                message: `Result mapping references non-existent node "${mapping.nodeId}"`,
+                suggestion: `Valid nodes: ${Array.from(nodeMap.keys()).join(", ")}`,
+            });
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        action_coverage: {
+            used: [...new Set(usedActions)],
+            available: registry.getAllActions().map(a => a.name),
+            unknown: unknownActions,
+        },
+    };
+}
+/**
+ * Find similar action names for suggestions
+ */
+function findSimilarActions(name, registry) {
+    const allActions = registry.getAllActions();
+    const similar = allActions
+        .filter(a => {
+        const aLower = a.name.toLowerCase();
+        const nLower = name.toLowerCase();
+        return aLower.includes(nLower) || nLower.includes(aLower) ||
+            levenshteinDistance(aLower, nLower) <= 3;
+    })
+        .slice(0, 3)
+        .map(a => a.name);
+    return similar.length > 0 ? similar.join(", ") : "none found";
+}
+/**
+ * Simple Levenshtein distance for fuzzy matching
+ */
+function levenshteinDistance(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// LLM Context Generation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generate action catalog for LLM context
+ */
+export function generateActionCatalogForLLM(registry) {
+    const sections = [];
+    sections.push("# Available Actions (from API)\n");
+    // Group by category
+    const byCategory = new Map();
+    for (const action of registry.getAllActions()) {
+        const cat = action.category || "other";
+        if (!byCategory.has(cat))
+            byCategory.set(cat, []);
+        byCategory.get(cat).push(action);
+    }
+    for (const [category, actions] of byCategory) {
+        sections.push(`## ${category}\n`);
+        for (const action of actions) {
+            const inputs = Array.from(action.inputs.values())
+                .map(i => `${i.name}${i.required ? "*" : ""}: ${i.type}`)
+                .join(", ");
+            const outputs = Array.from(action.outputs.keys()).join(", ");
+            sections.push(`### ${action.name} (${action.version})`);
+            sections.push(`${action.description}`);
+            sections.push(`- Inputs: ${inputs || "none"}`);
+            sections.push(`- Outputs: ${outputs || "none"}\n`);
+        }
+    }
+    return sections.join("\n");
+}
+/**
+ * Generate template catalog for LLM context
+ */
+export function generateTemplateCatalogForLLM(registry) {
+    const sections = [];
+    sections.push("# Available Templates (from API)\n");
+    for (const template of registry.getAllTemplates()) {
+        sections.push(`## ${template.name} (${template.type})`);
+        sections.push(`ID: ${template.id}`);
+        if (template.description)
+            sections.push(template.description);
+        sections.push(`Default widgets: ${template.defaultWidgets.join(", ") || "none"}\n`);
+    }
+    return sections.join("\n");
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Singleton Registry
+// ─────────────────────────────────────────────────────────────────────────────
+let _schemaRegistry = null;
+export async function ensureSchemaRegistry(client) {
+    if (!_schemaRegistry) {
+        _schemaRegistry = new APISchemaRegistry();
+        await _schemaRegistry.load(client);
+    }
+    return _schemaRegistry;
+}
+export function getSchemaRegistry() {
+    return _schemaRegistry;
+}