@ema.co/mcp-toolkit 2026.3.24 → 2026.3.25-2

package/dist/mcp/domain/workflow-def-validator.js

@@ -33,7 +33,10 @@ const VALID_BINDING_CASES = new Set([
 export function validateWorkflowDefStructure(workflowDef) {
     const issues = [];
     validateWorkflowName(workflowDef, issues);
+    validateEnumTypes(workflowDef, issues);
     validateActions(workflowDef, issues);
+    validateTypeArguments(workflowDef, issues);
+    validateRunIfBindings(workflowDef, issues);
     validateResults(workflowDef, issues);
     validateNamedResults(workflowDef, issues);
     return {
@@ -98,6 +101,205 @@ function validateWorkflowName(wf, issues) {
         });
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// enumTypes validation — empty namespaces here cause opaque 500 from the backend
+// ─────────────────────────────────────────────────────────────────────────────
+function validateEnumTypes(wf, issues) {
+    const enumTypes = wf.enumTypes;
+    if (!Array.isArray(enumTypes) || enumTypes.length === 0)
+        return;
+    const enumNames = new Set();
+    for (let i = 0; i < enumTypes.length; i++) {
+        const et = enumTypes[i];
+        const prefix = `enumTypes[${i}]`;
+        const name = et.name;
+        if (!name || typeof name !== "object") {
+            issues.push({
+                path: `${prefix}.name`,
+                severity: "error",
+                message: "enumType missing 'name' (NamespacedName — requires { namespaces, name })",
+                proto_ref: "workflows.v1.EnumTypeDef.name",
+            });
+            continue;
+        }
+        if (!Array.isArray(name.namespaces) || name.namespaces.length === 0) {
+            issues.push({
+                path: `${prefix}.name.namespaces`,
+                severity: "error",
+                message: "enumType namespaces must be a non-empty array. Empty [] causes HTTP 500. " +
+                    "Use the namespaces from the persona's workflowName, or leave namespaces from the template unchanged.",
+                proto_ref: "workflows.v1.NamespacedName.namespaces",
+            });
+        }
+        if (typeof name.name !== "string" || name.name.length === 0) {
+            issues.push({
+                path: `${prefix}.name.name`,
+                severity: "error",
+                message: "enumType name.name must be a non-empty string (e.g. 'intent_categories')",
+                proto_ref: "workflows.v1.NamespacedName.name",
+            });
+        }
+        else {
+            if (enumNames.has(name.name)) {
+                issues.push({
+                    path: `${prefix}.name.name`,
+                    severity: "error",
+                    message: `Duplicate enumType name '${name.name}'`,
+                });
+            }
+            enumNames.add(name.name);
+        }
+        // Validate options array
+        const options = et.options;
+        if (!Array.isArray(options) || options.length === 0) {
+            issues.push({
+                path: `${prefix}.options`,
+                severity: "warning",
+                message: "enumType has no options — categorizer will have nothing to route to",
+                proto_ref: "workflows.v1.EnumTypeDef.options",
+            });
+        }
+        else {
+            const hasFallback = options.some((o) => typeof o.name === "string" && o.name.toLowerCase() === "fallback");
+            if (!hasFallback) {
+                issues.push({
+                    path: `${prefix}.options`,
+                    severity: "warning",
+                    message: "enumType has no 'Fallback' option — categorizer should always include a Fallback category",
+                });
+            }
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// typeArguments validation — categorizers need typeArguments.categories pointing
+// to a valid enumType defined in enumTypes[]
+// ─────────────────────────────────────────────────────────────────────────────
+function validateTypeArguments(wf, issues) {
+    const actions = wf.actions;
+    if (!Array.isArray(actions))
+        return;
+    // Collect defined enum type names
+    const enumTypes = wf.enumTypes;
+    const definedEnums = new Set();
+    if (Array.isArray(enumTypes)) {
+        for (const et of enumTypes) {
+            const name = et.name;
+            if (name && typeof name.name === "string") {
+                definedEnums.add(name.name);
+            }
+        }
+    }
+    for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        const prefix = `actions[${i}]`;
+        const actionDef = action.action;
+        const actionName = actionDef?.name?.name;
+        // Check if this is a categorizer (needs typeArguments)
+        const isCategorizer = actionName === "chat_categorizer" || actionName === "text_categorizer";
+        const typeArgs = action.typeArguments;
+        if (isCategorizer && (!typeArgs || !typeArgs.categories)) {
+            issues.push({
+                path: `${prefix}.typeArguments`,
+                severity: "error",
+                message: `Categorizer '${action.name}' missing typeArguments.categories. ` +
+                    "Must point to an enumType: { categories: { enumType: { name: { name: '<enum_name>', namespaces: [...] } } } }",
+                proto_ref: "workflows.v1.ActionInstance.type_arguments",
+            });
+            continue;
+        }
+        if (!typeArgs?.categories)
+            continue;
+        // Validate the enumType reference
+        const categories = typeArgs.categories;
+        const enumType = categories.enumType;
+        if (!enumType) {
+            issues.push({
+                path: `${prefix}.typeArguments.categories.enumType`,
+                severity: "error",
+                message: "typeArguments.categories missing enumType reference",
+            });
+            continue;
+        }
+        const enumName = enumType.name;
+        if (!enumName || typeof enumName !== "object") {
+            issues.push({
+                path: `${prefix}.typeArguments.categories.enumType.name`,
+                severity: "error",
+                message: "enumType.name must be a NamespacedName object { name, namespaces }",
+            });
+            continue;
+        }
+        // Check namespaces match the enumType definition
+        if (!Array.isArray(enumName.namespaces) || enumName.namespaces.length === 0) {
+            issues.push({
+                path: `${prefix}.typeArguments.categories.enumType.name.namespaces`,
+                severity: "error",
+                message: "typeArguments enumType namespaces must be non-empty. Must match the namespaces in the enumTypes[] definition.",
+                proto_ref: "workflows.v1.NamespacedName.namespaces",
+            });
+        }
+        // Check the referenced enum exists
+        if (typeof enumName.name === "string" && definedEnums.size > 0 && !definedEnums.has(enumName.name)) {
+            issues.push({
+                path: `${prefix}.typeArguments.categories.enumType.name.name`,
+                severity: "error",
+                message: `typeArguments references enumType '${enumName.name}' but it's not defined in enumTypes[]. ` +
+                    `Available: ${[...definedEnums].join(", ")}`,
+            });
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// runIf validation — conditional execution bindings must be well-formed
+// ─────────────────────────────────────────────────────────────────────────────
+function validateRunIfBindings(wf, issues) {
+    const actions = wf.actions;
+    if (!Array.isArray(actions))
+        return;
+    for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        const runIf = action.runIf;
+        if (!runIf)
+            continue;
+        const prefix = `actions[${i}].runIf`;
+        // lhs must be a valid binding
+        const lhs = runIf.lhs;
+        if (!lhs || typeof lhs !== "object") {
+            issues.push({
+                path: `${prefix}.lhs`,
+                severity: "error",
+                message: "runIf.lhs must be a valid InputBinding (e.g., actionOutput referencing categorizer output)",
+                proto_ref: "workflows.v1.ConditionalInputBinding",
+            });
+        }
+        else {
+            validateSingleBinding(lhs, `${prefix}.lhs`, issues);
+        }
+        // operator must be present
+        if (runIf.operator === undefined || runIf.operator === null) {
+            issues.push({
+                path: `${prefix}.operator`,
+                severity: "error",
+                message: "runIf.operator is required (1 = EQUAL, 2 = NOT_EQUAL)",
+                proto_ref: "workflows.v1.ConditionalInputBinding.operator",
+            });
+        }
+        // rhs must be a valid binding
+        const rhs = runIf.rhs;
+        if (!rhs || typeof rhs !== "object") {
+            issues.push({
+                path: `${prefix}.rhs`,
+                severity: "error",
+                message: "runIf.rhs must be a valid InputBinding (e.g., inline enumValue)",
+                proto_ref: "workflows.v1.ConditionalInputBinding",
+            });
+        }
+        else {
+            validateSingleBinding(rhs, `${prefix}.rhs`, issues);
+        }
+    }
+}
 function validateActions(wf, issues) {
     const actions = wf.actions;
     if (!Array.isArray(actions) || actions.length === 0) {
@@ -188,7 +390,43 @@ function validateInputBindings(action, prefix, _knownActions, issues) {
     for (const [inputName, binding] of Object.entries(inputs)) {
         if (!binding || typeof binding !== "object")
             continue;
-        validateSingleBinding(binding, `${prefix}.inputs.${inputName}`, issues);
+        const bindingObj = binding;
+        validateSingleBinding(bindingObj, `${prefix}.inputs.${inputName}`, issues);
+        // named_inputs_* MUST use multiBinding with namedBinding elements
+        if (inputName.startsWith("named_inputs_")) {
+            if (!bindingObj.multiBinding) {
+                issues.push({
+                    path: `${prefix}.inputs.${inputName}`,
+                    severity: "error",
+                    message: `Input '${inputName}' must use multiBinding format: ` +
+                        `{ multiBinding: { elements: [{ namedBinding: { name: "...", binding: {...} } }] } }. ` +
+                        "Search knowledge('named inputs format') for correct structure",
+                    proto_ref: "workflows.v1.InputBinding.MultiBinding",
+                });
+            }
+            else {
+                // Check each element uses namedBinding
+                const mb = bindingObj.multiBinding;
+                const elements = mb.elements;
+                if (Array.isArray(elements)) {
+                    for (let j = 0; j < elements.length; j++) {
+                        const el = elements[j];
+                        if (el && typeof el === "object" && !el.namedBinding) {
+                            issues.push({
+                                path: `${prefix}.inputs.${inputName}.multiBinding.elements[${j}]`,
+                                severity: "error",
+                                message: "named_inputs elements must use namedBinding: { namedBinding: { name: '...', binding: {...} } }. " +
+                                    "Plain actionOutput or inline bindings inside multiBinding are invalid for named_inputs.",
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // extraction_columns MUST use correct array format
+        if (inputName === "extraction_columns") {
+            validateExtractionColumnsFormat(bindingObj, `${prefix}.inputs.${inputName}`, issues);
+        }
     }
 }
 function validateSingleBinding(binding, path, issues) {
@@ -462,3 +700,85 @@ function validateResultDef(value, path, issues) {
         }
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// extraction_columns format validation
+// Must use: inline.array.values[{ wellKnown: { extractionColumn: { id, name, dataType } } }]
+// ─────────────────────────────────────────────────────────────────────────────
+function validateExtractionColumnsFormat(binding, path, issues) {
+    const inline = binding.inline;
+    if (!inline)
+        return; // actionOutput wiring is valid too
+    const array = inline.array;
+    if (!array) {
+        issues.push({
+            path: `${path}.inline`,
+            severity: "error",
+            message: "extraction_columns must use inline.array format: { inline: { array: { values: [{ wellKnown: { extractionColumn: { id, name, dataType } } }] } } }. " +
+                "Search knowledge('extraction columns format') for correct structure",
+        });
+        return;
+    }
+    const values = array.values;
+    if (!Array.isArray(values) || values.length === 0) {
+        issues.push({
+            path: `${path}.inline.array.values`,
+            severity: "warning",
+            message: "extraction_columns array is empty — no columns defined",
+        });
+        return;
+    }
+    const seenIds = new Set();
+    for (let i = 0; i < values.length; i++) {
+        const v = values[i];
+        const vPath = `${path}.inline.array.values[${i}]`;
+        const wellKnown = v?.wellKnown;
+        if (!wellKnown) {
+            issues.push({
+                path: vPath,
+                severity: "error",
+                message: "extraction_columns values must be wrapped in wellKnown: { extractionColumn: { id, name, dataType } }",
+            });
+            continue;
+        }
+        const col = wellKnown.extractionColumn;
+        if (!col) {
+            issues.push({
+                path: `${vPath}.wellKnown`,
+                severity: "error",
+                message: "Missing extractionColumn inside wellKnown wrapper",
+            });
+            continue;
+        }
+        if (typeof col.id !== "string" || col.id.length === 0) {
+            issues.push({
+                path: `${vPath}.wellKnown.extractionColumn.id`,
+                severity: "error",
+                message: "extractionColumn requires 'id' (unique string identifier)",
+            });
+        }
+        else {
+            if (seenIds.has(col.id)) {
+                issues.push({
+                    path: `${vPath}.wellKnown.extractionColumn.id`,
+                    severity: "error",
+                    message: `Duplicate extraction column id '${col.id}'`,
+                });
+            }
+            seenIds.add(col.id);
+        }
+        if (typeof col.name !== "string" || col.name.length === 0) {
+            issues.push({
+                path: `${vPath}.wellKnown.extractionColumn.name`,
+                severity: "error",
+                message: "extractionColumn requires 'name' (display name)",
+            });
+        }
+        if (col.dataType === undefined || col.dataType === null) {
+            issues.push({
+                path: `${vPath}.wellKnown.extractionColumn.dataType`,
+                severity: "error",
+                message: "extractionColumn requires 'dataType' (1=STRING, 2=INT, 3=FLOAT, 4=BOOL, 5=DATE)",
+            });
+        }
+    }
+}

package/dist/mcp/domain/workflow-static-validator.js

@@ -327,7 +327,7 @@ function formatPathName(path) {
 // ─────────────────────────────────────────────────────────────────────────────
 // Global Categorizer Validation (not path-dependent)
 // ─────────────────────────────────────────────────────────────────────────────
-function validateAllCategorizers(workflow) {
+export function validateAllCategorizers(workflow) {
     const errors = [];
     // Find all categorizer nodes in workflow
     const categorizers = workflow.nodes.filter(node => node.actionType === "chat_categorizer" ||

package/dist/mcp/guidance/classify.js

@@ -0,0 +1,74 @@
+/**
+ * Result Shape Classifier
+ *
+ * Inspects an MCP tool response and classifies it into a ResultShape.
+ * The shape drives which guidance atoms are resolved.
+ */
+/**
+ * Classify an MCP tool response into a ResultShape.
+ *
+ * Handlers can override by setting `result._result_shape` directly.
+ */
+export function classifyResult(result, unfilteredCount) {
+    // Handler override
+    if (typeof result._result_shape === "string") {
+        return result._result_shape;
+    }
+    // Error shapes — check error field or status indicators
+    const error = result.error;
+    const status = result.status;
+    const apiStatus = result.api_status;
+    if (error || status === "failed") {
+        // Validation blocked by toolkit (not API)
+        if (typeof result.validation_failed === "string") {
+            return "error_validation";
+        }
+        // Deploy-specific failure — check before generic HTTP codes
+        // because deploy 400/500 needs deploy-specific guidance
+        if (result.mode === "deploy" || result.deployed === false) {
+            return "deploy_failed";
+        }
+        const errorStr = String(error ?? "").toLowerCase();
+        const code = apiStatus ?? extractStatusCode(errorStr);
+        if (code === 401 || code === 403)
+            return "error_401";
+        if (code === 404 || code === 422)
+            return "error_not_found";
+        if (code === 400)
+            return "error_400";
+        if (code === 500 || code === 502 || code === 503)
+            return "error_500";
+        return "error";
+    }
+    // Success shapes
+    if (result.success === true || result.persona_id) {
+        // Created entity
+        if (result.persona_id && !result.workflow_def) {
+            return "created";
+        }
+    }
+    if (result.deployed === true || (result.mode === "deploy" && !error)) {
+        return "deployed";
+    }
+    // List shapes — check count
+    const count = typeof result.count === "number" ? result.count : undefined;
+    if (count !== undefined) {
+        if (count === 0) {
+            const unfiltered = unfilteredCount
+                ?? (typeof result._unfiltered_count === "number" ? result._unfiltered_count : undefined);
+            return unfiltered && unfiltered > 0 ? "empty_filtered" : "empty_source";
+        }
+        return "success";
+    }
+    // Partial — success with warnings
+    if (result._warning && !error) {
+        return "partial";
+    }
+    return "success";
+}
+/** Extract HTTP status code from error message string. */
+function extractStatusCode(errorStr) {
+    // Match patterns like "API error (400)" or "HTTP 500" or just "500"
+    const match = errorStr.match(/\b(4\d{2}|5\d{2})\b/);
+    return match ? parseInt(match[1], 10) : undefined;
+}

package/dist/mcp/guidance/defaults.js

@@ -0,0 +1,114 @@
+/**
+ * Universal Default Guidance — Fallback When DE Has No Match
+ *
+ * These are the last resort. DE-served atoms and agent-published solutions
+ * take priority. Defaults exist so no response ever has zero guidance.
+ */
+/**
+ * Get default guidance hints for a result shape.
+ * Template variables ({tool}, {method}, etc.) are NOT resolved here —
+ * the middleware handles resolution after merging all sources.
+ */
+export function getDefaultGuidance(shape, ctx) {
+    switch (shape) {
+        case "empty_filtered":
+            return {
+                _warning: "Results exist but none match your filters.",
+                _tip: "Try without filters to see all, or use knowledge('{tool}') to search DE.",
+                _next_step: "{tool}(method='{method}')",
+            };
+        case "empty_source":
+            return {
+                _warning: "No results found.",
+                _tip: "Try knowledge('{tool}') to search DE, or check your profile/environment.",
+                _next_step: "knowledge('{tool}')",
+            };
+        case "created":
+            return {
+                _warning: "Entity created but may need additional configuration.",
+                _next_step: "workflow(mode='get', persona_id='{persona_id}') to get starter workflow, then build and deploy a complete workflow_def.",
+            };
+        case "deployed":
+            return {
+                _next_step: "Verify: workflow(mode='get', persona_id='{persona_id}') — confirm workflow is active.",
+            };
+        case "deploy_failed":
+            return {
+                _warning: "Deployment failed. Do NOT retry with the same workflow_def — fix the issue first. If the error is structural (not just a field fix), backtrack to design before rebuilding JSON.",
+                _likely_causes: [
+                    "Type mismatch: input binding has incompatible type",
+                    "Missing or invalid named_inputs format — see knowledge('named inputs format')",
+                    "Empty namespaces on action names or enumTypes",
+                    "namedResults producer missing actionName or outputName",
+                ],
+                _debug_steps: [
+                    "Read the error message — it names the specific field/action that failed",
+                    "Search for the error: knowledge('{tool} {method} <error_keywords>') — other agents may have solved this",
+                    "Compare your workflow_def against a working one: workflow(mode='get', persona_id='<similar_persona>')",
+                    "Run workflow(mode='validate') to catch remaining issues before re-deploying",
+                    "If the error is structural (wrong shape, not just a wrong value), go back to design — don't patch JSON",
+                ],
+                _next_step: "knowledge('{tool} deploy <error_keywords>') to find solutions, then fix and workflow(mode='validate') before retrying.",
+            };
+        case "error_400":
+            return {
+                _warning: "Bad request — the API rejected the input.",
+                _likely_causes: [
+                    "Invalid field format or missing required field",
+                    "Input type mismatch (e.g., string where number expected)",
+                    "Constraint violation (e.g., duplicate name, invalid enum value)",
+                ],
+                _debug_steps: [
+                    "Read the error message — it usually names the problematic field",
+                    "Search for the error: knowledge('{tool} {method} <error_keywords>') — may find known solutions",
+                    "Check field constraints: knowledge('field constraints')",
+                ],
+                _next_step: "knowledge('{tool} {method} <error_keywords>') to find known solutions for this error.",
+            };
+        case "error_500":
+            return {
+                _warning: "Server error — the API gave no details. Do NOT guess — search knowledge and compare against a working workflow.",
+                _likely_causes: [
+                    "Type mismatch in input bindings (API doesn't say which input)",
+                    "Missing typeArguments on categorizer nodes",
+                    "Invalid named_inputs or extraction_columns format",
+                    "Empty namespaces array on action names or enumTypes",
+                    "Deprecated action version",
+                ],
+                _debug_steps: [
+                    "Search for the error: knowledge('{tool} deploy 500 <error_keywords>') — other agents may have solved this",
+                    "Compare against a WORKING workflow: workflow(mode='get', persona_id='<similar_persona>')",
+                    "Check EACH input binding type — TEXT_WITH_SOURCES ≠ STRING ≠ JSON_VALUE",
+                    "Verify enumTypes and action namespaces are non-empty arrays, not []",
+                    "Check namedResults producers have both actionName AND outputName",
+                ],
+                _next_step: "knowledge('{tool} deploy 500') to find known solutions, then compare against a working workflow_def.",
+            };
+        case "error_401":
+            return {
+                _warning: "Authentication failed.",
+                _next_step: "config(method='login') to re-authenticate.",
+            };
+        case "error_not_found":
+            return {
+                _warning: "Entity not found.",
+                _tip: "Check the ID is correct and you're using the right profile/environment.",
+            };
+        case "error_validation":
+            return {
+                _warning: "Validation blocked the operation before it reached the API.",
+                _debug_steps: [
+                    "Read the validation errors — they describe exactly what to fix",
+                    "Fix the issues and retry",
+                ],
+            };
+        case "error":
+            return {
+                _tip: "If this error is unclear, use feedback(method='submit', category='error_unclear', message='...') to report it.",
+            };
+        case "partial":
+        case "success":
+        default:
+            return {};
+    }
+}