@ema.co/mcp-toolkit 1.5.2 → 1.7.0

package/dist/sdk/workflow-validator.js

@@ -0,0 +1,609 @@
+/**
+ * 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.
+ */
+import { generateSchemaBundle, } from "./action-schema-parser.js";
+import * as fs from "fs";
+// ─────────────────────────────────────────────────────────────────────────────
+// Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Simple hash function for fingerprinting (not cryptographically secure)
+ * Used for detecting schema changes, not for security.
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    // Convert to hex and pad to 8 chars
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+export class APISchemaRegistry {
+    actions = new Map();
+    templates = new Map();
+    loaded = false;
+    _metadata = {
+        source: "api",
+        version: "unknown",
+        generatedAt: new Date().toISOString(),
+    };
+    /**
+     * Get schema metadata (source, version, etc.)
+     */
+    get metadata() {
+        return this._metadata;
+    }
+    /**
+     * Load schemas from API (primary source - reflects deployed state)
+     */
+    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._metadata = {
+            source: "api",
+            version: new Date().toISOString().split("T")[0],
+            generatedAt: new Date().toISOString(),
+        };
+        this.loaded = true;
+    }
+    /**
+     * Load schemas from ema repo source code (for development/offline use)
+     * @param config - Configuration for ema repo paths
+     */
+    loadFromEmaRepo(config) {
+        const bundle = generateSchemaBundle(config);
+        this.loadFromBundle(bundle);
+        this._metadata.source = "code";
+        this._metadata.sourcePath = config.basePath;
+    }
+    /**
+     * Load schemas from a pre-generated bundle (JSON file)
+     * @param bundleOrPath - Bundle object or path to JSON file
+     */
+    loadFromBundle(bundleOrPath) {
+        const bundle = typeof bundleOrPath === "string"
+            ? JSON.parse(fs.readFileSync(bundleOrPath, "utf-8"))
+            : bundleOrPath;
+        // Convert ParsedAction to ActionSchema
+        for (const [actionName, versions] of Object.entries(bundle.actions)) {
+            // Use the latest version (last in array)
+            const action = versions[versions.length - 1];
+            const schema = this.parsedActionToSchema(action);
+            this.actions.set(actionName, schema);
+        }
+        this._metadata = {
+            source: bundle.source,
+            version: bundle.version,
+            generatedAt: bundle.generatedAt,
+            sourcePath: bundle.sourcePath,
+        };
+        this.loaded = true;
+    }
+    /**
+     * Load with fallback strategy: API -> Code -> Bundle
+     */
+    async loadWithFallback(options) {
+        // 1. Try live API first (most accurate for deployed state)
+        if (options.client) {
+            try {
+                await this.load(options.client);
+                this._metadata.environment = options.environment;
+                console.log(`[SchemaRegistry] Loaded ${this.actions.size} actions from API`);
+                return;
+            }
+            catch (e) {
+                console.warn(`[SchemaRegistry] API load failed, trying fallback:`, e);
+            }
+        }
+        // 2. Try parsing ema repo (for development)
+        if (options.emaRepoPath) {
+            try {
+                this.loadFromEmaRepo({ basePath: options.emaRepoPath });
+                console.log(`[SchemaRegistry] Loaded ${this.actions.size} actions from ema repo`);
+                return;
+            }
+            catch (e) {
+                console.warn(`[SchemaRegistry] Ema repo load failed, trying fallback:`, e);
+            }
+        }
+        // 3. Use bundled schema (offline/CI)
+        if (options.bundlePath) {
+            try {
+                this.loadFromBundle(options.bundlePath);
+                console.log(`[SchemaRegistry] Loaded ${this.actions.size} actions from bundle`);
+                return;
+            }
+            catch (e) {
+                console.warn(`[SchemaRegistry] Bundle load failed:`, e);
+            }
+        }
+        console.warn("[SchemaRegistry] No schema source available - validation will be limited");
+    }
+    /**
+     * Convert ParsedAction to ActionSchema
+     */
+    parsedActionToSchema(action) {
+        const inputs = new Map();
+        const outputs = new Map();
+        for (const input of action.inputs) {
+            inputs.set(input.name, {
+                name: input.name,
+                type: input.argType.wellKnownType ?? input.argType.typeParameter ?? "unknown",
+                required: !input.isOptional,
+                description: input.description ?? input.displayName,
+            });
+        }
+        for (const output of action.outputs) {
+            outputs.set(output.name, {
+                name: output.name,
+                type: output.argType.wellKnownType ?? output.argType.typeParameter ?? "unknown",
+                description: output.displayName,
+            });
+        }
+        return {
+            name: action.name,
+            displayName: action.displayName,
+            description: action.description,
+            category: action.category,
+            version: action.version,
+            inputs,
+            outputs,
+            documentation: action.documentation, // Raw docs for LLM context
+        };
+    }
+    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());
+    }
+    /**
+     * Compute a fingerprint hash of all action definitions.
+     * Used for detecting skew between API and code schemas.
+     */
+    computeFingerprint() {
+        const actions = this.getAllActions().sort((a, b) => a.name.localeCompare(b.name));
+        const data = actions.map(a => `${a.name}:${a.version}:${a.inputs.size}:${a.outputs.size}`).join("|");
+        return simpleHash(data);
+    }
+    /**
+     * Compare this registry against another to detect schema skew.
+     * Useful for detecting when API differs from code definitions.
+     */
+    compareWith(other) {
+        const thisActions = new Map(this.actions);
+        const otherActions = new Map(other.actions);
+        const addedInOther = [];
+        const removedFromOther = [];
+        const versionDiff = [];
+        // Check for actions in "other" but not in "this"
+        for (const [name, action] of otherActions) {
+            if (!thisActions.has(name)) {
+                addedInOther.push(name);
+            }
+            else {
+                const thisAction = thisActions.get(name);
+                if (thisAction.version !== action.version) {
+                    versionDiff.push({
+                        name,
+                        apiVersion: otherActions === this.actions ? thisAction.version : action.version,
+                        codeVersion: otherActions === this.actions ? action.version : thisAction.version,
+                    });
+                }
+            }
+        }
+        // Check for actions in "this" but not in "other"
+        for (const name of thisActions.keys()) {
+            if (!otherActions.has(name)) {
+                removedFromOther.push(name);
+            }
+        }
+        return {
+            hasSkew: addedInOther.length > 0 || removedFromOther.length > 0 || versionDiff.length > 0,
+            addedInApi: addedInOther,
+            removedFromApi: removedFromOther,
+            versionDiff,
+        };
+    }
+    /**
+     * 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;
+/**
+ * Ensure schema registry is loaded with layered fallback:
+ * 1. API (live data from ListActions)
+ * 2. Bundled schema (resources/action-schema.json)
+ */
+export async function ensureSchemaRegistry(client) {
+    if (!_schemaRegistry) {
+        _schemaRegistry = new APISchemaRegistry();
+        // Use layered loading: API first, then bundled schema fallback
+        const bundlePath = resolveBundlePath();
+        await _schemaRegistry.loadWithFallback({
+            client,
+            bundlePath,
+        });
+    }
+    return _schemaRegistry;
+}
+/**
+ * Resolve the path to the bundled action schema.
+ * Works both in development (src/) and production (dist/).
+ */
+function resolveBundlePath() {
+    const paths = [
+        // Development: relative to src/sdk/
+        new URL("../../resources/action-schema.json", import.meta.url).pathname,
+        // Production: relative to dist/sdk/
+        new URL("../../resources/action-schema.json", import.meta.url).pathname,
+    ];
+    for (const p of paths) {
+        if (fs.existsSync(p))
+            return p;
+    }
+    return undefined;
+}
+export function getSchemaRegistry() {
+    return _schemaRegistry;
+}
+/**
+ * Reset the schema registry (for testing)
+ */
+export function resetSchemaRegistry() {
+    _schemaRegistry = null;
+}