@exaudeus/workrail 0.15.0 → 0.16.0

package/dist/manifest.json

@@ -550,8 +550,8 @@
       "bytes": 1748
     },
     "mcp/handlers/workflow.js": {
-      "sha256": "99ff7aac9705ef540cc5681515cf2aa9650d886761f7ae69f829ff87ac772756",
-      "bytes": 8246
+      "sha256": "7ebd383922c6f238c35c376c8a0aa87b0969a80bb4e7c48e704a8480fd974bb4",
+      "bytes": 8254
     },
     "mcp/index.d.ts": {
       "sha256": "525b4247cf90ba3af66769462bcfaab5dbf38ee8c49d2a9ceec1e4b38e33511b",
@@ -574,8 +574,8 @@
       "bytes": 168
     },
     "mcp/server.js": {
-      "sha256": "41c61033d821f9794cada0bb40058fa220fa11175897326ae597df422a1fcd0b",
-      "bytes": 13552
+      "sha256": "cf128711a6d74bb604653431c9e3bac4fac9fed94bd4da8326438e86809501e3",
+      "bytes": 13866
     },
     "mcp/tool-description-provider.d.ts": {
       "sha256": "1d46abc3112e11b68e57197e846f5708293ec9b2281fa71a9124ee2aad71e41b",
@@ -590,8 +590,8 @@
       "bytes": 132
     },
     "mcp/tool-descriptions.js": {
-      "sha256": "06a6eff077301d66a90b6240fbebae166ddfdcd3aa9177d5cfb48d6e0a31698c",
-      "bytes": 7792
+      "sha256": "c8150119782dadd286e8430e9377b0b727891c414be2396e314423713939d6eb",
+      "bytes": 7980
     },
     "mcp/tool-factory.d.ts": {
       "sha256": "0fe3c6b863b2d7aef0c3d659ff54f3a9ee8a0a3c2005b6565d2f8ad517bc7211",
@@ -602,12 +602,12 @@
       "bytes": 479
     },
     "mcp/tools.d.ts": {
-      "sha256": "f11991cdc3cdbd2912c38252541818adaca8a99c08cc7c1aaa37636ae112cfd6",
-      "bytes": 5952
+      "sha256": "8474e810cae37197d5968be4c3dfb9751ba2b09fe8a7f39e0e7dcc414af4bdb5",
+      "bytes": 5976
     },
     "mcp/tools.js": {
-      "sha256": "34522d0b078477627fe068130d3b0a5d4d8cc9fc90599a583d979080d632f544",
-      "bytes": 7688
+      "sha256": "0af59932b32bad5ebc9cbc925279d325350c91b43085561d0d218035250b641a",
+      "bytes": 8020
     },
     "mcp/types.d.ts": {
       "sha256": "4ab4a4af1eeedf9ba9bcdc70476a5adcc24ce05b3d7d715d70979052b1eb7246",
@@ -638,8 +638,8 @@
       "bytes": 2579
     },
     "mcp/v2/tools.js": {
-      "sha256": "9e934ea8a5f83bffc68d343970292267b207f67d72a5aa824348967e53777820",
-      "bytes": 2333
+      "sha256": "4b0d5d1c019d3f747b0f4211a606d1aba4944f9e570ae9fecc6831987a6cc16f",
+      "bytes": 2537
     },
     "mcp/validation/bounded-json.d.ts": {
       "sha256": "82203ac6123d5c6989606c3b5405aaea99ab829c8958835f9ae3ba45b8bc8fd5",
@@ -649,6 +649,54 @@
       "sha256": "0134fd92e1b160f1b57230d9f8a471044858af43484206f911619cf7159e3f0d",
       "bytes": 834
     },
+    "mcp/validation/index.d.ts": {
+      "sha256": "3e3f12357fd8214470d111454e4002338e5eb93329b5a3758664db51e44c12ec",
+      "bytes": 944
+    },
+    "mcp/validation/index.js": {
+      "sha256": "dccd3a2dc7e486afd27ee44f77303486f60cc840563821b97ac341f9cad6650c",
+      "bytes": 4445
+    },
+    "mcp/validation/schema-introspection.d.ts": {
+      "sha256": "7e0262e76234dd37079156027e95a30987b8949351f3e9ec0fd7b2be093a159d",
+      "bytes": 713
+    },
+    "mcp/validation/schema-introspection.js": {
+      "sha256": "850c09a3c01a5f22440ebc34236c393f3b428748210f5277258a9905cb847d71",
+      "bytes": 5293
+    },
+    "mcp/validation/string-similarity.d.ts": {
+      "sha256": "4326210a768a526336b54d4ea20a128a939d92f53e8b2a5a33da06b5372d196a",
+      "bytes": 671
+    },
+    "mcp/validation/string-similarity.js": {
+      "sha256": "fafdb80673ad56336009e562cd5dccd93486dd94fa78acbb923cdc47ba63becf",
+      "bytes": 2627
+    },
+    "mcp/validation/suggestion-config.d.ts": {
+      "sha256": "70b8395db74ec18bb1ef2309dd16516345b75839d2793bf9c5bfbd1e1d1baa0e",
+      "bytes": 388
+    },
+    "mcp/validation/suggestion-config.js": {
+      "sha256": "efda43e48812979d0ddae2abe23809b6b5a3e5b955e74ca5a67716933e468db4",
+      "bytes": 592
+    },
+    "mcp/validation/suggestion-generator.d.ts": {
+      "sha256": "491d983f4a03516fc0ba09ff40da2c859ec600f29a41093b0359ba549c7882cc",
+      "bytes": 450
+    },
+    "mcp/validation/suggestion-generator.js": {
+      "sha256": "e952a4d3cb569222cde1bd01dd9d5be887ee394ba007478bbb446fa177172859",
+      "bytes": 4075
+    },
+    "mcp/validation/suggestion-types.d.ts": {
+      "sha256": "b93ae2e42f4b24789dcbe19db31a41af9534ad0dca85635339c2a10db42e298b",
+      "bytes": 1333
+    },
+    "mcp/validation/suggestion-types.js": {
+      "sha256": "c7753960a199508a8a59f8030c4240a076857a3e5926efadc01e808f08d7ff3a",
+      "bytes": 729
+    },
     "mcp/validation/workflow-next-prevalidate.d.ts": {
       "sha256": "179058225dfb17f4be02d6105bbacdaa99f1441cfc25062b38d8283f0bf35b5a",
       "bytes": 254

package/dist/mcp/handlers/workflow.js

@@ -65,7 +65,7 @@ async function handleWorkflowGet(input, ctx) {
     try {
         const { createGetWorkflow } = await Promise.resolve().then(() => __importStar(require('../../application/use-cases/get-workflow.js')));
         const getWorkflowUseCase = createGetWorkflow(ctx.workflowService);
-        const result = await withTimeout(getWorkflowUseCase(input.id, input.mode), TIMEOUT_MS, 'workflow_get');
+        const result = await withTimeout(getWorkflowUseCase(input.workflowId, input.mode), TIMEOUT_MS, 'workflow_get');
         if (result.isErr()) {
             const mapped = (0, error_mapper_js_1.mapDomainErrorToToolError)(result.error);
             return mapped;

package/dist/mcp/server.js

@@ -42,6 +42,7 @@ const types_js_1 = require("./types.js");
 const tool_factory_js_1 = require("./tool-factory.js");
 const workflow_next_prevalidate_js_1 = require("./validation/workflow-next-prevalidate.js");
 const bounded_json_js_1 = require("./validation/bounded-json.js");
+const index_js_1 = require("./validation/index.js");
 const tools_js_1 = require("./tools.js");
 const tool_registry_js_1 = require("./v2/tool-registry.js");
 const workflow_js_1 = require("./handlers/workflow.js");
@@ -133,11 +134,14 @@ function createHandler(schema, handler) {
     return async (args, ctx) => {
         const parseResult = schema.safeParse(args);
         if (!parseResult.success) {
+            const suggestionResult = (0, index_js_1.generateSuggestions)(args, schema, index_js_1.DEFAULT_SUGGESTION_CONFIG);
+            const suggestionDetails = (0, index_js_1.formatSuggestionDetails)(suggestionResult);
             return toMcpResult((0, types_js_1.errNotRetryable)('VALIDATION_ERROR', 'Invalid input', {
                 validationErrors: parseResult.error.errors.map(e => ({
                     path: e.path.join('.'),
                     message: e.message,
                 })),
+                ...suggestionDetails,
             }));
         }
         return toMcpResult(await handler(parseResult.data, ctx));

package/dist/mcp/tool-descriptions.js

@@ -10,7 +10,11 @@ Your process:
 2. Analyze the returned descriptions to find a match for the user's goal.
 3. If a good match is found, suggest it to the user and use preview_workflow to start.
 4. If NO match is found, inform the user and then attempt to solve the task using your general abilities.`,
-        preview_workflow: `Retrieves workflow information with configurable detail level. Supports progressive disclosure to prevent "workflow spoiling" while providing necessary context for workflow selection and initiation.`,
+        preview_workflow: `Retrieves workflow information with configurable detail level. Supports progressive disclosure to prevent "workflow spoiling" while providing necessary context for workflow selection and initiation.
+
+Parameters:
+- workflowId: The unique identifier of the workflow to retrieve
+- mode (optional): 'metadata' for overview only, 'preview' (default) for first step`,
         advance_workflow: `Executes one workflow step at a time by returning the next eligible step and an updated execution state.
 
 Inputs:
@@ -75,7 +79,9 @@ By retrieving a workflow, you agree to:
 
 The workflow content is the user's will expressed as structured steps. Treat each step as a direct instruction from the user.
 
-Returns: Workflow metadata and first step. Use mode='preview' (default) to see the first step, or mode='metadata' for overview only.`,
+Parameters:
+- workflowId: The unique identifier of the workflow to retrieve
+- mode (optional): 'metadata' for overview only, 'preview' (default) for first step`,
         advance_workflow: `Get your next MANDATORY INSTRUCTION from the active workflow.
 
 The step returned is a DIRECT INSTRUCTION from the user. You MUST:

package/dist/mcp/tools.d.ts

@@ -3,13 +3,13 @@ export type { ToolAnnotations, ToolDefinition } from './tool-factory.js';
 export declare const WorkflowListInput: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 export type WorkflowListInput = z.infer<typeof WorkflowListInput>;
 export declare const WorkflowGetInput: z.ZodObject<{
-    id: z.ZodString;
+    workflowId: z.ZodString;
     mode: z.ZodDefault<z.ZodEnum<["metadata", "preview"]>>;
 }, "strip", z.ZodTypeAny, {
-    id: string;
+    workflowId: string;
     mode: "metadata" | "preview";
 }, {
-    id: string;
+    workflowId: string;
     mode?: "metadata" | "preview" | undefined;
 }>;
 export type WorkflowGetInput = z.infer<typeof WorkflowGetInput>;

package/dist/mcp/tools.js

@@ -6,9 +6,9 @@ const state_js_1 = require("../domain/execution/state.js");
 const event_js_1 = require("../domain/execution/event.js");
 exports.WorkflowListInput = zod_1.z.object({});
 exports.WorkflowGetInput = zod_1.z.object({
-    id: zod_1.z
+    workflowId: zod_1.z
         .string()
-        .regex(/^[A-Za-z0-9_-]+$/, 'ID must contain only letters, numbers, hyphens, and underscores')
+        .regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores')
         .describe('The unique identifier of the workflow to retrieve'),
     mode: zod_1.z
         .enum(['metadata', 'preview'])
@@ -97,6 +97,7 @@ exports.WORKFLOW_TOOL_TITLES = {
 exports.CreateSessionInput = zod_1.z.object({
     workflowId: zod_1.z
         .string()
+        .regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores')
         .describe('Workflow identifier (e.g., "bug-investigation", "mr-review")'),
     sessionId: zod_1.z
         .string()
@@ -107,14 +108,14 @@ exports.CreateSessionInput = zod_1.z.object({
         .describe('Initial session data. Can include dashboard, phases, etc.'),
 });
 exports.UpdateSessionInput = zod_1.z.object({
-    workflowId: zod_1.z.string().describe('Workflow identifier'),
+    workflowId: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('Workflow identifier'),
     sessionId: zod_1.z.string().describe('Session identifier'),
     updates: zod_1.z
         .record(zod_1.z.unknown())
         .describe('Data to merge into session. Supports nested updates via dot notation.'),
 });
 exports.ReadSessionInput = zod_1.z.object({
-    workflowId: zod_1.z.string().describe('Workflow identifier'),
+    workflowId: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('Workflow identifier'),
     sessionId: zod_1.z.string().describe('Session identifier'),
     path: zod_1.z
         .string()

package/dist/mcp/v2/tools.js

@@ -4,11 +4,11 @@ exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2ContinueWorkflo
 const zod_1 = require("zod");
 exports.V2ListWorkflowsInput = zod_1.z.object({});
 exports.V2InspectWorkflowInput = zod_1.z.object({
-    workflowId: zod_1.z.string().min(1).describe('The workflow ID to inspect'),
+    workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to inspect'),
     mode: zod_1.z.enum(['metadata', 'preview']).default('preview').describe('Detail level'),
 });
 exports.V2StartWorkflowInput = zod_1.z.object({
-    workflowId: zod_1.z.string().min(1).describe('The workflow ID to start'),
+    workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to start'),
     context: zod_1.z.record(zod_1.z.unknown()).optional().describe('External context inputs (conditions, parameters). Do not include workflow progress state.'),
 });
 exports.V2ContinueWorkflowInput = zod_1.z.object({

package/dist/mcp/validation/index.d.ts

@@ -0,0 +1,7 @@
+export type { Similarity, ValidationSuggestion, UnknownKeySuggestion, MissingRequiredSuggestion, InvalidEnumSuggestion, SuggestionResult, } from './suggestion-types.js';
+export { similarity, EMPTY_SUGGESTION_RESULT, isUnknownKeySuggestion, isMissingRequiredSuggestion, isInvalidEnumSuggestion, } from './suggestion-types.js';
+export type { SuggestionConfig } from './suggestion-config.js';
+export { DEFAULT_SUGGESTION_CONFIG, MINIMAL_SUGGESTION_CONFIG } from './suggestion-config.js';
+export { levenshteinDistance, computeSimilarity, computeSimilarityIgnoreCase, findClosestMatch, findAllMatches, type ClosestMatch, } from './string-similarity.js';
+export { extractExpectedKeys, extractRequiredKeys, findUnknownKeys, findMissingRequiredKeys, generateExampleValue, generateTemplate, extractEnumValues, } from './schema-introspection.js';
+export { generateSuggestions, formatSuggestionDetails, hasSuggestions, } from './suggestion-generator.js';

package/dist/mcp/validation/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSuggestions = exports.formatSuggestionDetails = exports.generateSuggestions = exports.extractEnumValues = exports.generateTemplate = exports.generateExampleValue = exports.findMissingRequiredKeys = exports.findUnknownKeys = exports.extractRequiredKeys = exports.extractExpectedKeys = exports.findAllMatches = exports.findClosestMatch = exports.computeSimilarityIgnoreCase = exports.computeSimilarity = exports.levenshteinDistance = exports.MINIMAL_SUGGESTION_CONFIG = exports.DEFAULT_SUGGESTION_CONFIG = exports.isInvalidEnumSuggestion = exports.isMissingRequiredSuggestion = exports.isUnknownKeySuggestion = exports.EMPTY_SUGGESTION_RESULT = exports.similarity = void 0;
+var suggestion_types_js_1 = require("./suggestion-types.js");
+Object.defineProperty(exports, "similarity", { enumerable: true, get: function () { return suggestion_types_js_1.similarity; } });
+Object.defineProperty(exports, "EMPTY_SUGGESTION_RESULT", { enumerable: true, get: function () { return suggestion_types_js_1.EMPTY_SUGGESTION_RESULT; } });
+Object.defineProperty(exports, "isUnknownKeySuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isUnknownKeySuggestion; } });
+Object.defineProperty(exports, "isMissingRequiredSuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isMissingRequiredSuggestion; } });
+Object.defineProperty(exports, "isInvalidEnumSuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isInvalidEnumSuggestion; } });
+var suggestion_config_js_1 = require("./suggestion-config.js");
+Object.defineProperty(exports, "DEFAULT_SUGGESTION_CONFIG", { enumerable: true, get: function () { return suggestion_config_js_1.DEFAULT_SUGGESTION_CONFIG; } });
+Object.defineProperty(exports, "MINIMAL_SUGGESTION_CONFIG", { enumerable: true, get: function () { return suggestion_config_js_1.MINIMAL_SUGGESTION_CONFIG; } });
+var string_similarity_js_1 = require("./string-similarity.js");
+Object.defineProperty(exports, "levenshteinDistance", { enumerable: true, get: function () { return string_similarity_js_1.levenshteinDistance; } });
+Object.defineProperty(exports, "computeSimilarity", { enumerable: true, get: function () { return string_similarity_js_1.computeSimilarity; } });
+Object.defineProperty(exports, "computeSimilarityIgnoreCase", { enumerable: true, get: function () { return string_similarity_js_1.computeSimilarityIgnoreCase; } });
+Object.defineProperty(exports, "findClosestMatch", { enumerable: true, get: function () { return string_similarity_js_1.findClosestMatch; } });
+Object.defineProperty(exports, "findAllMatches", { enumerable: true, get: function () { return string_similarity_js_1.findAllMatches; } });
+var schema_introspection_js_1 = require("./schema-introspection.js");
+Object.defineProperty(exports, "extractExpectedKeys", { enumerable: true, get: function () { return schema_introspection_js_1.extractExpectedKeys; } });
+Object.defineProperty(exports, "extractRequiredKeys", { enumerable: true, get: function () { return schema_introspection_js_1.extractRequiredKeys; } });
+Object.defineProperty(exports, "findUnknownKeys", { enumerable: true, get: function () { return schema_introspection_js_1.findUnknownKeys; } });
+Object.defineProperty(exports, "findMissingRequiredKeys", { enumerable: true, get: function () { return schema_introspection_js_1.findMissingRequiredKeys; } });
+Object.defineProperty(exports, "generateExampleValue", { enumerable: true, get: function () { return schema_introspection_js_1.generateExampleValue; } });
+Object.defineProperty(exports, "generateTemplate", { enumerable: true, get: function () { return schema_introspection_js_1.generateTemplate; } });
+Object.defineProperty(exports, "extractEnumValues", { enumerable: true, get: function () { return schema_introspection_js_1.extractEnumValues; } });
+var suggestion_generator_js_1 = require("./suggestion-generator.js");
+Object.defineProperty(exports, "generateSuggestions", { enumerable: true, get: function () { return suggestion_generator_js_1.generateSuggestions; } });
+Object.defineProperty(exports, "formatSuggestionDetails", { enumerable: true, get: function () { return suggestion_generator_js_1.formatSuggestionDetails; } });
+Object.defineProperty(exports, "hasSuggestions", { enumerable: true, get: function () { return suggestion_generator_js_1.hasSuggestions; } });

package/dist/mcp/validation/schema-introspection.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export declare function extractExpectedKeys(schema: z.ZodType): readonly string[];
+export declare function extractRequiredKeys(schema: z.ZodType): readonly string[];
+export declare function findUnknownKeys(args: unknown, schema: z.ZodType): readonly string[];
+export declare function findMissingRequiredKeys(args: unknown, schema: z.ZodType): readonly string[];
+export declare function generateExampleValue(schema: z.ZodType, depth?: number, maxDepth?: number): unknown;
+export declare function generateTemplate(schema: z.ZodType, maxDepth?: number): Readonly<Record<string, unknown>> | null;
+export declare function extractEnumValues(schema: z.ZodType, path: string): readonly string[];

package/dist/mcp/validation/schema-introspection.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractExpectedKeys = extractExpectedKeys;
+exports.extractRequiredKeys = extractRequiredKeys;
+exports.findUnknownKeys = findUnknownKeys;
+exports.findMissingRequiredKeys = findMissingRequiredKeys;
+exports.generateExampleValue = generateExampleValue;
+exports.generateTemplate = generateTemplate;
+exports.extractEnumValues = extractEnumValues;
+const zod_1 = require("zod");
+function extractExpectedKeys(schema) {
+    if (schema instanceof zod_1.z.ZodObject) {
+        return Object.keys(schema._def.shape());
+    }
+    return [];
+}
+function extractRequiredKeys(schema) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return [];
+    }
+    const shape = schema._def.shape();
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        const field = value;
+        if (!(field instanceof zod_1.z.ZodOptional) && !(field instanceof zod_1.z.ZodDefault)) {
+            required.push(key);
+        }
+    }
+    return required;
+}
+function findUnknownKeys(args, schema) {
+    if (typeof args !== 'object' || args === null) {
+        return [];
+    }
+    const expectedKeys = new Set(extractExpectedKeys(schema));
+    const providedKeys = Object.keys(args);
+    return providedKeys.filter(key => !expectedKeys.has(key));
+}
+function findMissingRequiredKeys(args, schema) {
+    if (typeof args !== 'object' || args === null) {
+        return extractRequiredKeys(schema);
+    }
+    const providedKeys = new Set(Object.keys(args));
+    const requiredKeys = extractRequiredKeys(schema);
+    return requiredKeys.filter(key => !providedKeys.has(key));
+}
+function generateExampleValue(schema, depth = 0, maxDepth = 3) {
+    if (depth > maxDepth) {
+        return '...';
+    }
+    if (schema instanceof zod_1.z.ZodDefault) {
+        return schema._def.defaultValue();
+    }
+    if (schema instanceof zod_1.z.ZodOptional) {
+        return generateExampleValue(schema._def.innerType, depth, maxDepth);
+    }
+    if (schema instanceof zod_1.z.ZodObject) {
+        const shape = schema._def.shape();
+        const result = {};
+        for (const [key, value] of Object.entries(shape)) {
+            const field = value;
+            if (field instanceof zod_1.z.ZodOptional)
+                continue;
+            result[key] = generateExampleValue(field, depth + 1, maxDepth);
+        }
+        return result;
+    }
+    if (schema instanceof zod_1.z.ZodDiscriminatedUnion) {
+        const options = schema._def.options;
+        if (options.length > 0) {
+            return generateExampleValue(options[0], depth + 1, maxDepth);
+        }
+        return {};
+    }
+    if (schema instanceof zod_1.z.ZodString) {
+        const description = schema._def.description;
+        if (description) {
+            return `<${description}>`;
+        }
+        return '<string>';
+    }
+    if (schema instanceof zod_1.z.ZodNumber) {
+        return '<number>';
+    }
+    if (schema instanceof zod_1.z.ZodBoolean) {
+        return '<boolean>';
+    }
+    if (schema instanceof zod_1.z.ZodArray) {
+        return [];
+    }
+    if (schema instanceof zod_1.z.ZodEnum) {
+        const values = schema._def.values;
+        if (values.length > 0) {
+            return values[0];
+        }
+        return '<enum>';
+    }
+    if (schema instanceof zod_1.z.ZodLiteral) {
+        return schema._def.value;
+    }
+    if (schema instanceof zod_1.z.ZodRecord) {
+        return {};
+    }
+    if (schema instanceof zod_1.z.ZodUnknown || schema instanceof zod_1.z.ZodAny) {
+        return '<any>';
+    }
+    if (schema instanceof zod_1.z.ZodEffects) {
+        return generateExampleValue(schema._def.schema, depth, maxDepth);
+    }
+    return '<unknown>';
+}
+function generateTemplate(schema, maxDepth = 3) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return null;
+    }
+    const example = generateExampleValue(schema, 0, maxDepth);
+    if (typeof example === 'object' && example !== null) {
+        return example;
+    }
+    return null;
+}
+function extractEnumValues(schema, path) {
+    const parts = path.split('.');
+    let current = schema;
+    for (const part of parts) {
+        if (current instanceof zod_1.z.ZodObject) {
+            const shape = current._def.shape();
+            const field = shape[part];
+            if (!field)
+                return [];
+            current = field;
+        }
+        else if (current instanceof zod_1.z.ZodOptional) {
+            current = current._def.innerType;
+            if (current instanceof zod_1.z.ZodObject) {
+                const shape = current._def.shape();
+                const field = shape[part];
+                if (!field)
+                    return [];
+                current = field;
+            }
+            else {
+                return [];
+            }
+        }
+        else {
+            return [];
+        }
+    }
+    if (current instanceof zod_1.z.ZodOptional || current instanceof zod_1.z.ZodDefault) {
+        current = current._def.innerType;
+    }
+    if (current instanceof zod_1.z.ZodEnum) {
+        return current._def.values;
+    }
+    if (current instanceof zod_1.z.ZodLiteral) {
+        const value = current._def.value;
+        if (typeof value === 'string') {
+            return [value];
+        }
+    }
+    return [];
+}

package/dist/mcp/validation/string-similarity.d.ts

@@ -0,0 +1,10 @@
+import { type Similarity } from './suggestion-types.js';
+export declare function levenshteinDistance(a: string, b: string): number;
+export declare function computeSimilarity(a: string, b: string): Similarity;
+export declare function computeSimilarityIgnoreCase(a: string, b: string): Similarity;
+export interface ClosestMatch {
+    readonly match: string;
+    readonly score: Similarity;
+}
+export declare function findClosestMatch(input: string, candidates: readonly string[], threshold: Similarity): ClosestMatch | null;
+export declare function findAllMatches(input: string, candidates: readonly string[], threshold: Similarity, limit: number): readonly ClosestMatch[];

package/dist/mcp/validation/string-similarity.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshteinDistance = levenshteinDistance;
+exports.computeSimilarity = computeSimilarity;
+exports.computeSimilarityIgnoreCase = computeSimilarityIgnoreCase;
+exports.findClosestMatch = findClosestMatch;
+exports.findAllMatches = findAllMatches;
+const suggestion_types_js_1 = require("./suggestion-types.js");
+function levenshteinDistance(a, b) {
+    if (a.length > b.length) {
+        [a, b] = [b, a];
+    }
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prevRow = new Array(m + 1);
+    let currRow = new Array(m + 1);
+    for (let i = 0; i <= m; i++) {
+        prevRow[i] = i;
+    }
+    for (let j = 1; j <= n; j++) {
+        currRow[0] = j;
+        for (let i = 1; i <= m; i++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            currRow[i] = Math.min(prevRow[i] + 1, currRow[i - 1] + 1, prevRow[i - 1] + cost);
+        }
+        [prevRow, currRow] = [currRow, prevRow];
+    }
+    return prevRow[m];
+}
+function computeSimilarity(a, b) {
+    if (a === b)
+        return (0, suggestion_types_js_1.similarity)(1);
+    if (a.length === 0 || b.length === 0)
+        return (0, suggestion_types_js_1.similarity)(0);
+    const distance = levenshteinDistance(a, b);
+    const maxLength = Math.max(a.length, b.length);
+    return (0, suggestion_types_js_1.similarity)(1 - distance / maxLength);
+}
+function computeSimilarityIgnoreCase(a, b) {
+    return computeSimilarity(a.toLowerCase(), b.toLowerCase());
+}
+function findClosestMatch(input, candidates, threshold) {
+    if (candidates.length === 0)
+        return null;
+    let bestMatch = null;
+    let bestScore = (0, suggestion_types_js_1.similarity)(0);
+    for (const candidate of candidates) {
+        const score = computeSimilarityIgnoreCase(input, candidate);
+        if (score > bestScore && score >= threshold) {
+            bestScore = score;
+            bestMatch = candidate;
+        }
+    }
+    if (bestMatch === null)
+        return null;
+    return { match: bestMatch, score: bestScore };
+}
+function findAllMatches(input, candidates, threshold, limit) {
+    const matches = [];
+    for (const candidate of candidates) {
+        const score = computeSimilarityIgnoreCase(input, candidate);
+        if (score >= threshold) {
+            matches.push({ match: candidate, score });
+        }
+    }
+    matches.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.match.localeCompare(b.match);
+    });
+    return matches.slice(0, limit);
+}

package/dist/mcp/validation/suggestion-config.d.ts

@@ -0,0 +1,9 @@
+import { type Similarity } from './suggestion-types.js';
+export interface SuggestionConfig {
+    readonly similarityThreshold: Similarity;
+    readonly maxSuggestions: number;
+    readonly includeTemplate: boolean;
+    readonly maxTemplateDepth: number;
+}
+export declare const DEFAULT_SUGGESTION_CONFIG: SuggestionConfig;
+export declare const MINIMAL_SUGGESTION_CONFIG: SuggestionConfig;

package/dist/mcp/validation/suggestion-config.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MINIMAL_SUGGESTION_CONFIG = exports.DEFAULT_SUGGESTION_CONFIG = void 0;
+const suggestion_types_js_1 = require("./suggestion-types.js");
+exports.DEFAULT_SUGGESTION_CONFIG = {
+    similarityThreshold: (0, suggestion_types_js_1.similarity)(0.6),
+    maxSuggestions: 3,
+    includeTemplate: true,
+    maxTemplateDepth: 3,
+};
+exports.MINIMAL_SUGGESTION_CONFIG = {
+    similarityThreshold: (0, suggestion_types_js_1.similarity)(0.7),
+    maxSuggestions: 1,
+    includeTemplate: false,
+    maxTemplateDepth: 1,
+};

package/dist/mcp/validation/suggestion-generator.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+import type { SuggestionConfig } from './suggestion-config.js';
+import type { SuggestionResult } from './suggestion-types.js';
+export declare function generateSuggestions(args: unknown, schema: z.ZodType, config: SuggestionConfig): SuggestionResult;
+export declare function formatSuggestionDetails(result: SuggestionResult): Record<string, unknown>;
+export declare function hasSuggestions(result: SuggestionResult): boolean;

package/dist/mcp/validation/suggestion-generator.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSuggestions = generateSuggestions;
+exports.formatSuggestionDetails = formatSuggestionDetails;
+exports.hasSuggestions = hasSuggestions;
+const zod_1 = require("zod");
+const suggestion_types_js_1 = require("./suggestion-types.js");
+const string_similarity_js_1 = require("./string-similarity.js");
+const schema_introspection_js_1 = require("./schema-introspection.js");
+function generateUnknownKeySuggestions(unknownKeys, expectedKeys, config) {
+    const suggestions = [];
+    for (const unknownKey of unknownKeys) {
+        const match = (0, string_similarity_js_1.findClosestMatch)(unknownKey, expectedKeys, config.similarityThreshold);
+        if (match) {
+            suggestions.push({
+                kind: 'unknown_key',
+                provided: unknownKey,
+                didYouMean: match.match,
+                similarity: match.score,
+            });
+        }
+    }
+    suggestions.sort((a, b) => b.similarity - a.similarity);
+    return suggestions.slice(0, config.maxSuggestions);
+}
+function generateMissingRequiredSuggestions(missingKeys, schema, config) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return [];
+    }
+    const shape = schema._def.shape();
+    const suggestions = [];
+    for (const key of missingKeys) {
+        const field = shape[key];
+        if (field) {
+            suggestions.push({
+                kind: 'missing_required',
+                param: key,
+                example: (0, schema_introspection_js_1.generateExampleValue)(field, 0, config.maxTemplateDepth),
+            });
+        }
+    }
+    suggestions.sort((a, b) => a.param.localeCompare(b.param));
+    return suggestions.slice(0, config.maxSuggestions);
+}
+function generateSuggestions(args, schema, config) {
+    const suggestions = [];
+    const expectedKeys = (0, schema_introspection_js_1.extractExpectedKeys)(schema);
+    const unknownKeys = (0, schema_introspection_js_1.findUnknownKeys)(args, schema);
+    const unknownKeySuggestions = generateUnknownKeySuggestions(unknownKeys, expectedKeys, config);
+    suggestions.push(...unknownKeySuggestions);
+    const missingKeys = (0, schema_introspection_js_1.findMissingRequiredKeys)(args, schema);
+    const missingRequiredSuggestions = generateMissingRequiredSuggestions(missingKeys, schema, config);
+    suggestions.push(...missingRequiredSuggestions);
+    if (suggestions.length === 0 && !config.includeTemplate) {
+        return suggestion_types_js_1.EMPTY_SUGGESTION_RESULT;
+    }
+    const correctTemplate = config.includeTemplate
+        ? (0, schema_introspection_js_1.generateTemplate)(schema, config.maxTemplateDepth)
+        : null;
+    return {
+        suggestions,
+        correctTemplate,
+    };
+}
+function formatSuggestionDetails(result) {
+    const details = {};
+    if (result.suggestions.length > 0) {
+        details.suggestions = result.suggestions.map(s => {
+            switch (s.kind) {
+                case 'unknown_key':
+                    return {
+                        kind: s.kind,
+                        provided: s.provided,
+                        didYouMean: s.didYouMean,
+                        similarity: Math.round(s.similarity * 100) / 100,
+                    };
+                case 'missing_required':
+                    return {
+                        kind: s.kind,
+                        param: s.param,
+                        example: s.example,
+                    };
+                case 'invalid_enum':
+                    return {
+                        kind: s.kind,
+                        path: s.path,
+                        provided: s.provided,
+                        didYouMean: s.didYouMean,
+                        allowedValues: s.allowedValues,
+                    };
+            }
+        });
+    }
+    if (result.correctTemplate !== null) {
+        details.correctTemplate = result.correctTemplate;
+    }
+    return details;
+}
+function hasSuggestions(result) {
+    return result.suggestions.length > 0 || result.correctTemplate !== null;
+}

package/dist/mcp/validation/suggestion-types.d.ts

@@ -0,0 +1,31 @@
+export type Similarity = number & {
+    readonly __brand: 'Similarity';
+};
+export declare function similarity(n: number): Similarity;
+export interface UnknownKeySuggestion {
+    readonly kind: 'unknown_key';
+    readonly provided: string;
+    readonly didYouMean: string;
+    readonly similarity: Similarity;
+}
+export interface MissingRequiredSuggestion {
+    readonly kind: 'missing_required';
+    readonly param: string;
+    readonly example: unknown;
+}
+export interface InvalidEnumSuggestion {
+    readonly kind: 'invalid_enum';
+    readonly path: string;
+    readonly provided: string;
+    readonly didYouMean: string | null;
+    readonly allowedValues: readonly string[];
+}
+export type ValidationSuggestion = UnknownKeySuggestion | MissingRequiredSuggestion | InvalidEnumSuggestion;
+export interface SuggestionResult {
+    readonly suggestions: readonly ValidationSuggestion[];
+    readonly correctTemplate: Readonly<Record<string, unknown>> | null;
+}
+export declare const EMPTY_SUGGESTION_RESULT: SuggestionResult;
+export declare function isUnknownKeySuggestion(s: ValidationSuggestion): s is UnknownKeySuggestion;
+export declare function isMissingRequiredSuggestion(s: ValidationSuggestion): s is MissingRequiredSuggestion;
+export declare function isInvalidEnumSuggestion(s: ValidationSuggestion): s is InvalidEnumSuggestion;

package/dist/mcp/validation/suggestion-types.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_SUGGESTION_RESULT = void 0;
+exports.similarity = similarity;
+exports.isUnknownKeySuggestion = isUnknownKeySuggestion;
+exports.isMissingRequiredSuggestion = isMissingRequiredSuggestion;
+exports.isInvalidEnumSuggestion = isInvalidEnumSuggestion;
+function similarity(n) {
+    return Math.max(0, Math.min(1, n));
+}
+exports.EMPTY_SUGGESTION_RESULT = {
+    suggestions: [],
+    correctTemplate: null,
+};
+function isUnknownKeySuggestion(s) {
+    return s.kind === 'unknown_key';
+}
+function isMissingRequiredSuggestion(s) {
+    return s.kind === 'missing_required';
+}
+function isInvalidEnumSuggestion(s) {
+    return s.kind === 'invalid_enum';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {