@ema.co/mcp-toolkit 1.5.2 → 1.7.0

package/dist/sdk/action-schema-parser.js

@@ -0,0 +1,379 @@
+/**
+ * Parser for Ema action definitions from .txtpb files
+ *
+ * This parses the Protocol Buffer text format used in ema_backend/grpc/workflow_actions/
+ * to extract action schemas for validation.
+ */
+import * as fs from "fs";
+import * as path from "path";
+// ============================================================================
+// Parser
+// ============================================================================
+/**
+ * Parse a .txtpb file content into a ParsedAction
+ */
+export function parseTextproto(content, filePath) {
+    try {
+        // Extract type_name block using brace matching
+        const typeNameBlock = extractBlock(content, "type_name");
+        // Get the innermost name (action name, not the outer "name" block)
+        const nameMatches = [...typeNameBlock.matchAll(/name:\s*"([^"]+)"/g)];
+        const name = nameMatches.length > 0 ? nameMatches[nameMatches.length - 1][1] : undefined;
+        const version = extractField(typeNameBlock, /version:\s*"([^"]+)"/) || "v0";
+        const displayName = extractField(content, /display_name:\s*"([^"]+)"/);
+        const description = extractField(content, /description:\s*"([^"]+)"/) ||
+            extractMultilineField(content, /description:\s*\n\s*"([^"]+)"/);
+        // Extract directly from source - no hardcoded validation
+        const category = extractField(content, /category:\s*(\w+)/);
+        const lifecycle = extractField(content, /lifecycle:\s*(\w+)/);
+        if (!name) {
+            console.warn(`Could not parse action name from ${filePath}`);
+            return null;
+        }
+        // Parse inputs
+        const inputs = parseInputs(content);
+        // Parse outputs
+        const outputs = parseOutputs(content);
+        // Parse type parameters
+        const typeParameters = parseTypeParameters(content);
+        // Parse required model features
+        const requiredModelFeatures = parseRequiredModelFeatures(content);
+        return {
+            name,
+            version,
+            displayName: displayName || name,
+            description: description || "",
+            category,
+            lifecycle,
+            inputs,
+            outputs,
+            typeParameters,
+            requiredModelFeatures,
+        };
+    }
+    catch (error) {
+        console.error(`Error parsing ${filePath}:`, error);
+        return null;
+    }
+}
+function extractField(content, regex) {
+    const match = content.match(regex);
+    return match?.[1];
+}
+/**
+ * Extract a block by keyword using brace matching
+ */
+function extractBlock(content, keyword) {
+    // Handle both "keyword {" and "keyword: {"
+    const regex = new RegExp(`${keyword}:?\\s*\\{`);
+    const match = content.match(regex);
+    if (!match || match.index === undefined)
+        return "";
+    const start = match.index;
+    let depth = 0;
+    let inBlock = false;
+    let blockEnd = start;
+    for (let i = start; i < content.length; i++) {
+        if (content[i] === "{") {
+            depth++;
+            inBlock = true;
+        }
+        if (content[i] === "}") {
+            depth--;
+        }
+        if (inBlock && depth === 0) {
+            blockEnd = i + 1;
+            break;
+        }
+    }
+    return content.slice(start, blockEnd);
+}
+function extractMultilineField(content, regex) {
+    const match = content.match(regex);
+    return match?.[1];
+}
+/**
+ * Parse required_model_features from content
+ */
+function parseRequiredModelFeatures(content) {
+    const features = [];
+    const regex = /required_model_features:\s*(\w+)/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        features.push(match[1]);
+    }
+    return features;
+}
+function parseInputs(content) {
+    const inputs = [];
+    // Find the inputs block
+    const inputsStart = content.indexOf("\ninputs {");
+    if (inputsStart === -1)
+        return inputs;
+    // Find the end of inputs block (next top-level section)
+    const outputsStart = content.indexOf("\noutputs {", inputsStart);
+    const inputsEnd = outputsStart !== -1 ? outputsStart : content.length;
+    const inputsBlock = content.slice(inputsStart, inputsEnd);
+    // Find each input definition by key
+    const keyMatches = [...inputsBlock.matchAll(/key:\s*"([^"]+)"/g)];
+    for (const keyMatch of keyMatches) {
+        const key = keyMatch[1];
+        const keyIndex = keyMatch.index;
+        // Find the value block after this key
+        const valueStart = inputsBlock.indexOf("value {", keyIndex);
+        if (valueStart === -1)
+            continue;
+        // Find matching closing brace for the value block
+        let valueDepth = 0;
+        let valueEnd = valueStart;
+        for (let i = valueStart; i < inputsBlock.length; i++) {
+            if (inputsBlock[i] === "{")
+                valueDepth++;
+            else if (inputsBlock[i] === "}") {
+                valueDepth--;
+                if (valueDepth === 0) {
+                    valueEnd = i + 1;
+                    break;
+                }
+            }
+        }
+        const valueBlock = inputsBlock.slice(valueStart, valueEnd);
+        const input = {
+            name: key,
+            displayName: extractField(valueBlock, /display_name:\s*"([^"]+)"/) || key,
+            argType: parseArgType(valueBlock),
+            isOptional: /is_optional:\s*true/.test(valueBlock),
+            isAdvanced: /is_advanced:\s*true/.test(valueBlock),
+            isConfigDriven: /is_likely_config_driven:\s*true/.test(valueBlock),
+            isActionOutput: /is_likely_action_output:\s*true/.test(valueBlock),
+            description: extractField(valueBlock, /description:\s*"([^"]+)"/),
+            placeholderDisplayValue: extractField(valueBlock, /placeholder_display_value:\s*"([^"]+)"/),
+        };
+        inputs.push(input);
+    }
+    return inputs;
+}
+function parseOutputs(content) {
+    const outputs = [];
+    // Find the outputs block - more permissive matching
+    const outputsStart = content.indexOf("\noutputs {");
+    if (outputsStart === -1)
+        return outputs;
+    // Find the end of outputs block
+    let depth = 0;
+    let outputsEnd = outputsStart;
+    let started = false;
+    for (let i = outputsStart; i < content.length; i++) {
+        if (content[i] === "{") {
+            depth++;
+            started = true;
+        }
+        else if (content[i] === "}") {
+            depth--;
+            if (started && depth === 0) {
+                outputsEnd = i + 1;
+                break;
+            }
+        }
+    }
+    const outputsBlock = content.slice(outputsStart, outputsEnd);
+    // Find each output definition - handle nested braces
+    const keyMatches = [...outputsBlock.matchAll(/key:\s*"([^"]+)"/g)];
+    for (const keyMatch of keyMatches) {
+        const key = keyMatch[1];
+        const keyIndex = keyMatch.index;
+        // Find the value block after this key
+        const valueStart = outputsBlock.indexOf("value {", keyIndex);
+        if (valueStart === -1)
+            continue;
+        // Find matching closing brace
+        let valueDepth = 0;
+        let valueEnd = valueStart;
+        for (let i = valueStart; i < outputsBlock.length; i++) {
+            if (outputsBlock[i] === "{")
+                valueDepth++;
+            else if (outputsBlock[i] === "}") {
+                valueDepth--;
+                if (valueDepth === 0) {
+                    valueEnd = i + 1;
+                    break;
+                }
+            }
+        }
+        const valueBlock = outputsBlock.slice(valueStart, valueEnd);
+        const output = {
+            name: key,
+            displayName: extractField(valueBlock, /display_name:\s*"([^"]+)"/) || key,
+            argType: parseArgType(valueBlock, true),
+        };
+        outputs.push(output);
+    }
+    return outputs;
+}
+function parseArgType(block, isOutput = false) {
+    const argType = {};
+    // Check for type_parameter (enum types)
+    const typeParam = extractField(block, /type_parameter:\s*"([^"]+)"/);
+    if (typeParam) {
+        argType.typeParameter = typeParam;
+        return argType;
+    }
+    // Check for well_known_type directly
+    const wellKnownDirect = extractField(block, /well_known_type:\s*(\w+)/);
+    // Check for array_type { well_known_type: ... }
+    const arrayMatch = block.match(/array_type\s*\{[\s\S]*?well_known_type:\s*(\w+)/);
+    // Check for array_type { named_type { well_known_type: ... } }
+    const namedArrayMatch = block.match(/array_type\s*\{[\s\S]*?named_type\s*\{[\s\S]*?well_known_type:\s*(\w+)/);
+    if (namedArrayMatch) {
+        argType.wellKnownType = namedArrayMatch[1];
+        argType.isArray = true;
+        argType.isNamed = true;
+    }
+    else if (arrayMatch) {
+        argType.wellKnownType = arrayMatch[1];
+        argType.isArray = true;
+    }
+    else if (wellKnownDirect) {
+        argType.wellKnownType = wellKnownDirect;
+    }
+    return argType;
+}
+function parseTypeParameters(content) {
+    const params = [];
+    const typeParamsMatch = content.match(/type_parameters\s*\{([\s\S]*?)\n\}/);
+    if (!typeParamsMatch)
+        return params;
+    const keyRegex = /key:\s*"([^"]+)"/g;
+    let match;
+    while ((match = keyRegex.exec(typeParamsMatch[1])) !== null) {
+        params.push(match[1]);
+    }
+    return params;
+}
+// ============================================================================
+// File System Helpers
+// ============================================================================
+/**
+ * Parse all .txtpb files from a directory
+ */
+export function parseActionDirectory(dirPath) {
+    const actions = [];
+    if (!fs.existsSync(dirPath)) {
+        console.warn(`Directory not found: ${dirPath}`);
+        return actions;
+    }
+    const files = fs.readdirSync(dirPath).filter((f) => f.endsWith(".txtpb"));
+    for (const file of files) {
+        const filePath = path.join(dirPath, file);
+        const content = fs.readFileSync(filePath, "utf-8");
+        const parsed = parseTextproto(content, filePath);
+        if (parsed) {
+            actions.push(parsed);
+        }
+    }
+    return actions;
+}
+/**
+ * Load documentation for an action from .md files
+ */
+export function loadDocumentation(docDir, actionName) {
+    if (!fs.existsSync(docDir))
+        return undefined;
+    // Try common naming patterns
+    const patterns = [
+        `${actionName}.md`,
+        `${actionName.replace(/_/g, " ")}.md`,
+        `${toTitleCase(actionName.replace(/_/g, " "))}.md`,
+        `${toTitleCase(actionName.replace(/_/g, " "))}_Agent.md`,
+    ];
+    for (const pattern of patterns) {
+        const filePath = path.join(docDir, pattern);
+        if (fs.existsSync(filePath)) {
+            return fs.readFileSync(filePath, "utf-8");
+        }
+    }
+    // Fallback: search for files containing the action name
+    const files = fs.readdirSync(docDir);
+    const searchName = actionName.replace(/_/g, "").toLowerCase();
+    for (const file of files) {
+        if (file.toLowerCase().replace(/_/g, "").includes(searchName)) {
+            return fs.readFileSync(path.join(docDir, file), "utf-8");
+        }
+    }
+    return undefined;
+}
+function toTitleCase(str) {
+    return str.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.slice(1).toLowerCase());
+}
+/**
+ * Generate a complete action schema bundle from the ema repo
+ */
+export function generateSchemaBundle(config) {
+    const prodDir = path.join(config.basePath, config.prodDir || "system_agents/prod");
+    const devDir = path.join(config.basePath, config.devDir || "system_agents/dev");
+    const docsDir = path.join(config.basePath, config.docsDir || "documentation");
+    // Parse all actions
+    const prodActions = parseActionDirectory(prodDir);
+    const devActions = parseActionDirectory(devDir);
+    // Group by action name
+    const actionMap = {};
+    for (const action of [...prodActions, ...devActions]) {
+        if (!actionMap[action.name]) {
+            actionMap[action.name] = [];
+        }
+        // Add raw documentation - LLM will interpret at generation time
+        action.documentation = loadDocumentation(docsDir, action.name);
+        // Note: capabilities field is intentionally left undefined
+        // The LLM should analyze documentation in context, not pre-computed extraction
+        // Avoid duplicates (same name + version)
+        const exists = actionMap[action.name].some((a) => a.version === action.version);
+        if (!exists) {
+            actionMap[action.name].push(action);
+        }
+    }
+    return {
+        version: new Date().toISOString().split("T")[0], // YYYY-MM-DD
+        generatedAt: new Date().toISOString(),
+        source: "code",
+        sourcePath: config.basePath,
+        actions: actionMap,
+    };
+}
+// ============================================================================
+// Type Compatibility Matrix
+// ============================================================================
+/**
+ * Type compatibility rules for workflow validation
+ */
+export const TYPE_COMPATIBILITY = {
+    // What inputs can accept each type
+    WELL_KNOWN_TYPE_CHAT_CONVERSATION: ["conversation", "chat_conversation"],
+    WELL_KNOWN_TYPE_TEXT_WITH_SOURCES: ["query", "text", "user_query", "input"],
+    WELL_KNOWN_TYPE_SEARCH_RESULT: ["search_results", "results"],
+    WELL_KNOWN_TYPE_ANY: ["*"], // Accepts anything
+    WELL_KNOWN_TYPE_STRING: ["text", "query", "instructions", "input"],
+    WELL_KNOWN_TYPE_STRUCT: ["custom_data", "extracted_variables", "json"],
+};
+/**
+ * Check if an output type is compatible with an input type
+ */
+export function isTypeCompatible(sourceType, targetType, targetInputName) {
+    // ANY accepts everything
+    if (targetType === "WELL_KNOWN_TYPE_ANY")
+        return true;
+    // Same type is always compatible
+    if (sourceType === targetType)
+        return true;
+    // named_inputs accepts anything
+    if (targetInputName?.startsWith("named_inputs"))
+        return true;
+    // Check explicit compatibility
+    if (sourceType && TYPE_COMPATIBILITY[sourceType]) {
+        const compatible = TYPE_COMPATIBILITY[sourceType];
+        if (compatible.includes("*"))
+            return true;
+        if (targetInputName && compatible.some((c) => targetInputName.includes(c)))
+            return true;
+    }
+    return false;
+}