@exaudeus/workrail 0.12.0 → 0.13.0

package/dist/mcp/handlers/v2-execution.js

@@ -49,6 +49,10 @@ const neverthrow_1 = require("neverthrow");
 const v1_to_v2_shim_js_1 = require("../../v2/read-only/v1-to-v2-shim.js");
 const hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
 const jcs_js_1 = require("../../v2/durable-core/canonical/jcs.js");
+const constants_js_1 = require("../../v2/durable-core/constants.js");
+const notes_markdown_js_1 = require("../../v2/durable-core/domain/notes-markdown.js");
+const outputs_js_1 = require("../../v2/durable-core/domain/outputs.js");
+const ack_advance_append_plan_js_1 = require("../../v2/durable-core/domain/ack-advance-append-plan.js");
 const workflow_source_js_1 = require("../../types/workflow-source.js");
 const workflow_definition_js_1 = require("../../types/workflow-definition.js");
 const workflow_compiler_js_1 = require("../../application/services/workflow-compiler.js");
@@ -57,10 +61,10 @@ const v2_execution_helpers_js_1 = require("./v2-execution-helpers.js");
 function normalizeTokenErrorMessage(message) {
     return message.split(os.homedir()).join('~');
 }
-const MAX_CONTEXT_BYTES_V2 = (256 * 1024);
+const MAX_CONTEXT_BYTES_V2 = constants_js_1.MAX_CONTEXT_BYTES;
 function validateJsonValueOrIssue(value, path, depth, seen) {
-    if (depth > 64)
-        return { kind: 'too_deep', path, maxDepth: 64 };
+    if (depth > constants_js_1.MAX_CONTEXT_DEPTH)
+        return { kind: 'too_deep', path, maxDepth: constants_js_1.MAX_CONTEXT_DEPTH };
     if (value === null)
         return null;
     const t = typeof value;
@@ -210,6 +214,7 @@ function isInternalError(e) {
         kind === 'workflow_hash_mismatch' ||
         kind === 'missing_snapshot' ||
         kind === 'no_pending_step' ||
+        kind === 'invariant_violation' ||
         kind === 'advance_apply_failed' ||
         kind === 'advance_next_failed');
 }
@@ -222,6 +227,8 @@ function mapInternalErrorToToolError(e) {
         case 'missing_snapshot':
         case 'no_pending_step':
             return internalError('Incomplete execution state.', 'Retry; if this persists, treat as invariant violation.');
+        case 'invariant_violation':
+            return internalError(normalizeTokenErrorMessage(e.message), 'Treat as invariant violation.');
         case 'advance_apply_failed':
         case 'advance_next_failed':
             return internalError(normalizeTokenErrorMessage(e.message), 'Retry; if this persists, treat as invariant violation.');
@@ -231,12 +238,13 @@ function mapInternalErrorToToolError(e) {
     }
 }
 function replayFromRecordedAdvance(args) {
-    const { recordedEvent, truth, sessionId, runId, nodeId, workflowHash, attemptId, inputStateToken, inputAckToken, pinnedWorkflow, snapshotStore, keyring, hmac, } = args;
+    const { recordedEvent, truth, sessionId, runId, nodeId, workflowHash, attemptId, inputStateToken, inputAckToken, pinnedWorkflow, snapshotStore, keyring, hmac, base64url, } = args;
     const checkpointTokenRes = signTokenOrErr({
         unsignedPrefix: 'chk.v1.',
         payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId, attemptId },
         keyring,
         hmac,
+        base64url,
     });
     if (checkpointTokenRes.isErr()) {
         return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointTokenRes.error });
@@ -293,6 +301,7 @@ function replayFromRecordedAdvance(args) {
             payload: { tokenVersion: 1, tokenKind: 'ack', sessionId, runId, nodeId: toNodeIdBranded, attemptId: nextAttemptId },
             keyring,
             hmac,
+            base64url,
         });
         if (nextAckTokenRes.isErr()) {
             return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: nextAckTokenRes.error });
@@ -302,6 +311,7 @@ function replayFromRecordedAdvance(args) {
             payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId: toNodeIdBranded, attemptId: nextAttemptId },
             keyring,
             hmac,
+            base64url,
         });
         if (nextCheckpointTokenRes.isErr()) {
             return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: nextCheckpointTokenRes.error });
@@ -311,6 +321,7 @@ function replayFromRecordedAdvance(args) {
             payload: { tokenVersion: 1, tokenKind: 'state', sessionId, runId, nodeId: toNodeIdBranded, workflowHash },
             keyring,
             hmac,
+            base64url,
         });
         if (nextStateTokenRes.isErr()) {
             return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: nextStateTokenRes.error });
@@ -381,74 +392,42 @@ function advanceAndRecord(args) {
             const evtEdgeCreated = `evt_${(0, crypto_1.randomUUID)()}`;
             const hasChildren = truth.events.some((e) => e.kind === 'edge_created' && e.data.fromNodeId === String(nodeId));
             const causeKind = hasChildren ? 'non_tip_advance' : 'intentional_fork';
-            const baseEvents = [
-                {
-                    v: 1,
-                    eventId: evtAdvanceRecorded,
-                    eventIndex: nextEventIndex,
-                    sessionId,
-                    kind: 'advance_recorded',
-                    dedupeKey,
-                    scope: { runId, nodeId },
-                    data: {
-                        attemptId,
-                        intent: 'ack_pending',
-                        outcome: { kind: 'advanced', toNodeId },
-                    },
-                },
-                {
-                    v: 1,
-                    eventId: evtNodeCreated,
-                    eventIndex: nextEventIndex + 1,
-                    sessionId,
-                    kind: 'node_created',
-                    dedupeKey: `node_created:${sessionId}:${runId}:${toNodeId}`,
-                    scope: { runId, nodeId: toNodeId },
-                    data: { nodeKind: 'step', parentNodeId: String(nodeId), workflowHash, snapshotRef: newSnapshotRef },
-                },
-                {
-                    v: 1,
-                    eventId: evtEdgeCreated,
-                    eventIndex: nextEventIndex + 2,
-                    sessionId,
-                    kind: 'edge_created',
-                    dedupeKey: `edge_created:${sessionId}:${runId}:${String(nodeId)}->${toNodeId}:acked_step`,
-                    scope: { runId },
-                    data: {
-                        edgeKind: 'acked_step',
-                        fromNodeId: String(nodeId),
-                        toNodeId,
-                        cause: { kind: causeKind, eventId: evtAdvanceRecorded },
-                    },
-                },
-            ];
             const outputId = (0, index_js_1.asOutputId)(`out_recap_${String(attemptId)}`);
-            const events = inputOutput?.notesMarkdown
+            const outputsToAppend = inputOutput?.notesMarkdown
                 ? [
-                    ...baseEvents,
                     {
-                        v: 1,
-                        eventId: `evt_${(0, crypto_1.randomUUID)()}`,
-                        eventIndex: nextEventIndex + 3,
-                        sessionId,
-                        kind: 'node_output_appended',
-                        dedupeKey: `node_output_appended:${sessionId}:${outputId}`,
-                        scope: { runId, nodeId },
-                        data: {
-                            outputId: `out_recap_${attemptId}`,
-                            outputChannel: 'recap',
-                            payload: {
-                                payloadKind: 'notes',
-                                notesMarkdown: inputOutput.notesMarkdown.slice(0, 4096),
-                            },
+                        outputId: String(outputId),
+                        outputChannel: 'recap',
+                        payload: {
+                            payloadKind: 'notes',
+                            notesMarkdown: (0, notes_markdown_js_1.toNotesMarkdownV1)(inputOutput.notesMarkdown),
                         },
                     },
                 ]
-                : baseEvents;
-            return sessionStore.append(lock, {
-                events,
-                snapshotPins: [{ snapshotRef: newSnapshotRef, eventIndex: nextEventIndex + 1, createdByEventId: evtNodeCreated }],
+                : [];
+            const normalizedOutputs = (0, outputs_js_1.normalizeOutputsForAppend)(outputsToAppend);
+            const outputEventIds = normalizedOutputs.map(() => `evt_${(0, crypto_1.randomUUID)()}`);
+            const planRes = (0, ack_advance_append_plan_js_1.buildAckAdvanceAppendPlanV1)({
+                sessionId: String(sessionId),
+                runId: String(runId),
+                fromNodeId: String(nodeId),
+                workflowHash,
+                attemptId: String(attemptId),
+                nextEventIndex,
+                toNodeId,
+                snapshotRef: newSnapshotRef,
+                causeKind,
+                minted: {
+                    advanceRecordedEventId: evtAdvanceRecorded,
+                    nodeCreatedEventId: evtNodeCreated,
+                    edgeCreatedEventId: evtEdgeCreated,
+                    outputEventIds,
+                },
+                outputsToAppend,
             });
+            if (planRes.isErr())
+                return errAsync({ kind: 'invariant_violation', message: planRes.error.message });
+            return sessionStore.append(lock, planRes.value);
         });
     });
 }
@@ -517,12 +496,12 @@ function snapshotStoreErrorToToolError(e, suggestion) {
 function pinnedWorkflowStoreErrorToToolError(e, suggestion) {
     return internalError(`Pinned workflow store error: ${e.message}`, suggestion);
 }
-function parseStateTokenOrFail(raw, keyring, hmac) {
-    const parsedRes = (0, index_js_1.parseTokenV1)(raw);
+function parseStateTokenOrFail(raw, keyring, hmac, base64url) {
+    const parsedRes = (0, index_js_1.parseTokenV1)(raw, base64url);
     if (parsedRes.isErr()) {
         return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenDecodeErrorToToolError)(parsedRes.error) };
     }
-    const verified = (0, index_js_1.verifyTokenSignatureV1)(parsedRes.value, keyring, hmac);
+    const verified = (0, index_js_1.verifyTokenSignatureV1)(parsedRes.value, keyring, hmac, base64url);
     if (verified.isErr()) {
         return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenVerifyErrorToToolError)(verified.error) };
     }
@@ -536,12 +515,12 @@ function parseStateTokenOrFail(raw, keyring, hmac) {
     }
     return { ok: true, token: parsedRes.value };
 }
-function parseAckTokenOrFail(raw, keyring, hmac) {
-    const parsedRes = (0, index_js_1.parseTokenV1)(raw);
+function parseAckTokenOrFail(raw, keyring, hmac, base64url) {
+    const parsedRes = (0, index_js_1.parseTokenV1)(raw, base64url);
     if (parsedRes.isErr()) {
         return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenDecodeErrorToToolError)(parsedRes.error) };
     }
-    const verified = (0, index_js_1.verifyTokenSignatureV1)(parsedRes.value, keyring, hmac);
+    const verified = (0, index_js_1.verifyTokenSignatureV1)(parsedRes.value, keyring, hmac, base64url);
     if (verified.isErr()) {
         return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenVerifyErrorToToolError)(verified.error) };
     }
@@ -565,7 +544,7 @@ function signTokenOrErr(args) {
     const bytes = (0, index_js_2.encodeTokenPayloadV1)(args.payload);
     if (bytes.isErr())
         return (0, neverthrow_1.err)(bytes.error);
-    const token = (0, index_js_2.signTokenV1)(args.unsignedPrefix, bytes.value, args.keyring, args.hmac);
+    const token = (0, index_js_2.signTokenV1)(args.unsignedPrefix, bytes.value, args.keyring, args.hmac, args.base64url);
     if (token.isErr())
         return (0, neverthrow_1.err)(token.error);
     return (0, neverthrow_1.ok)(String(token.value));
@@ -651,7 +630,7 @@ function executeStartWorkflow(input, ctx) {
     if (!ctx.v2) {
         return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 tools disabled', suggestion: 'Enable v2Tools flag' });
     }
-    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac } = ctx.v2;
+    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac, base64url } = ctx.v2;
     const ctxCheck = checkContextBudget({ tool: 'start_workflow', context: input.context });
     if (!ctxCheck.ok)
         return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ctxCheck.error });
@@ -806,13 +785,13 @@ function executeStartWorkflow(input, ctx) {
             nodeId,
             attemptId,
         };
-        const stateToken = signTokenOrErr({ unsignedPrefix: 'st.v1.', payload: statePayload, keyring, hmac });
+        const stateToken = signTokenOrErr({ unsignedPrefix: 'st.v1.', payload: statePayload, keyring, hmac, base64url });
         if (stateToken.isErr())
             return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: stateToken.error });
-        const ackToken = signTokenOrErr({ unsignedPrefix: 'ack.v1.', payload: ackPayload, keyring, hmac });
+        const ackToken = signTokenOrErr({ unsignedPrefix: 'ack.v1.', payload: ackPayload, keyring, hmac, base64url });
         if (ackToken.isErr())
             return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: ackToken.error });
-        const checkpointToken = signTokenOrErr({ unsignedPrefix: 'chk.v1.', payload: checkpointPayload, keyring, hmac });
+        const checkpointToken = signTokenOrErr({ unsignedPrefix: 'chk.v1.', payload: checkpointPayload, keyring, hmac, base64url });
         if (checkpointToken.isErr())
             return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointToken.error });
         const { stepId, title, prompt } = extractStepMetadata(pinnedWorkflow, firstStep.id);
@@ -833,8 +812,8 @@ function executeContinueWorkflow(input, ctx) {
     if (!ctx.v2) {
         return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 tools disabled', suggestion: 'Enable v2Tools flag' });
     }
-    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac } = ctx.v2;
-    const stateRes = parseStateTokenOrFail(input.stateToken, keyring, hmac);
+    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac, base64url } = ctx.v2;
+    const stateRes = parseStateTokenOrFail(input.stateToken, keyring, hmac, base64url);
     if (!stateRes.ok)
         return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: stateRes.failure });
     const state = stateRes.token;
@@ -891,6 +870,7 @@ function executeContinueWorkflow(input, ctx) {
                     payload: { tokenVersion: 1, tokenKind: 'ack', sessionId, runId, nodeId, attemptId },
                     keyring,
                     hmac,
+                    base64url,
                 });
                 if (ackTokenRes.isErr())
                     return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: ackTokenRes.error });
@@ -899,6 +879,7 @@ function executeContinueWorkflow(input, ctx) {
                     payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId, attemptId },
                     keyring,
                     hmac,
+                    base64url,
                 });
                 if (checkpointTokenRes.isErr())
                     return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointTokenRes.error });
@@ -940,7 +921,7 @@ function executeContinueWorkflow(input, ctx) {
             });
         });
     }
-    const ackRes = parseAckTokenOrFail(input.ackToken, keyring, hmac);
+    const ackRes = parseAckTokenOrFail(input.ackToken, keyring, hmac, base64url);
     if (!ackRes.ok)
         return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ackRes.failure });
     const ack = ackRes.token;
@@ -983,6 +964,7 @@ function executeContinueWorkflow(input, ctx) {
                     snapshotStore,
                     keyring,
                     hmac,
+                    base64url,
                 });
             }
             return gate
@@ -1054,6 +1036,7 @@ function executeContinueWorkflow(input, ctx) {
                     snapshotStore,
                     keyring,
                     hmac,
+                    base64url,
                 });
             });
         });

package/dist/mcp/handlers/v2-workflow.js

@@ -6,9 +6,6 @@ const types_js_1 = require("../types.js");
 const error_mapper_js_1 = require("../error-mapper.js");
 const output_schemas_js_1 = require("../output-schemas.js");
 const v1_to_v2_shim_js_1 = require("../../v2/read-only/v1-to-v2-shim.js");
-const index_js_1 = require("../../v2/infra/local/crypto/index.js");
-const index_js_2 = require("../../v2/infra/local/data-dir/index.js");
-const index_js_3 = require("../../v2/infra/local/pinned-workflow-store/index.js");
 const hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
 const TIMEOUT_MS = 30000;
 async function withTimeout(operation, timeoutMs, name) {
@@ -17,12 +14,19 @@ async function withTimeout(operation, timeoutMs, name) {
     });
     return Promise.race([operation, timeoutPromise]);
 }
+function requireV2(ctx) {
+    if (!ctx.v2) {
+        return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', 'v2 tools are not enabled');
+    }
+    return null;
+}
 async function handleV2ListWorkflows(_input, ctx) {
+    const v2Err = requireV2(ctx);
+    if (v2Err)
+        return v2Err;
+    const { crypto, pinnedStore } = ctx.v2;
     try {
         const summaries = await withTimeout(ctx.workflowService.listWorkflowSummaries(), TIMEOUT_MS, 'list_workflows');
-        const crypto = new index_js_1.NodeCryptoV2();
-        const dataDir = new index_js_2.LocalDataDirV2(process.env);
-        const pinnedStore = new index_js_3.LocalPinnedWorkflowStoreV2(dataDir);
         const compiled = await Promise.all(summaries.map(async (s) => {
             const wf = await ctx.workflowService.getWorkflowById(s.id);
             if (!wf) {
@@ -72,14 +76,15 @@ async function handleV2ListWorkflows(_input, ctx) {
     }
 }
 async function handleV2InspectWorkflow(input, ctx) {
+    const v2Err = requireV2(ctx);
+    if (v2Err)
+        return v2Err;
+    const { crypto, pinnedStore } = ctx.v2;
     try {
         const workflow = await withTimeout(ctx.workflowService.getWorkflowById(input.workflowId), TIMEOUT_MS, 'inspect_workflow');
         if (!workflow) {
             return (0, types_js_1.errNotRetryable)('NOT_FOUND', `Workflow not found: ${input.workflowId}`);
         }
-        const crypto = new index_js_1.NodeCryptoV2();
-        const dataDir = new index_js_2.LocalDataDirV2(process.env);
-        const pinnedStore = new index_js_3.LocalPinnedWorkflowStoreV2(dataDir);
         const snapshot = (0, v1_to_v2_shim_js_1.compileV1WorkflowToV2PreviewSnapshot)(workflow);
         const hashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(snapshot, crypto);
         if (hashRes.isErr()) {

package/dist/mcp/server.js

@@ -89,21 +89,26 @@ async function createToolContext() {
         const keyringPort = container_js_1.container.resolve(tokens_js_1.DI.V2.Keyring);
         const keyringResult = await keyringPort.loadOrCreate();
         if (keyringResult.isErr()) {
-            console.error(`[FeatureFlags] v2 tools enabled but keyring load failed: ${keyringResult.error.code}`);
-            throw new Error(`Failed to initialize v2 keyring: ${keyringResult.error.message}`);
+            const err = keyringResult.error;
+            console.error(`[V2Init] Keyring load failed: code=${err.code}, message=${err.message}`);
+            console.error('[FeatureFlags] v2 tools disabled due to keyring initialization failure');
+        }
+        else {
+            const crypto = container_js_1.container.resolve(tokens_js_1.DI.V2.Crypto);
+            const hmac = container_js_1.container.resolve(tokens_js_1.DI.V2.HmacSha256);
+            const base64url = container_js_1.container.resolve(tokens_js_1.DI.V2.Base64Url);
+            v2 = {
+                gate,
+                sessionStore,
+                snapshotStore,
+                pinnedStore,
+                keyring: keyringResult.value,
+                crypto,
+                hmac,
+                base64url,
+            };
+            console.error('[FeatureFlags] v2 tools enabled');
         }
-        const crypto = container_js_1.container.resolve(tokens_js_1.DI.V2.Crypto);
-        const hmac = container_js_1.container.resolve(tokens_js_1.DI.V2.HmacSha256);
-        v2 = {
-            gate,
-            sessionStore,
-            snapshotStore,
-            pinnedStore,
-            keyring: keyringResult.value,
-            crypto,
-            hmac,
-        };
-        console.error('[FeatureFlags] v2 tools enabled');
     }
     else {
         console.error('[FeatureFlags] v2 tools disabled (enable with WORKRAIL_ENABLE_V2_TOOLS=true)');
@@ -166,35 +171,35 @@ async function startServer() {
     const ctx = await createToolContext();
     const descriptionProvider = container_js_1.container.resolve(tokens_js_1.DI.Mcp.DescriptionProvider);
     const buildTool = (0, tool_factory_js_1.createToolFactory)(descriptionProvider);
-    const workflowListTool = buildTool({
-        name: 'workflow_list',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.workflow_list,
+    const discoverWorkflowsTool = buildTool({
+        name: 'discover_workflows',
+        title: tools_js_1.WORKFLOW_TOOL_TITLES.discover_workflows,
         inputSchema: tools_js_1.WorkflowListInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.workflow_list,
+        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.discover_workflows,
     });
-    const workflowGetTool = buildTool({
-        name: 'workflow_get',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.workflow_get,
+    const previewWorkflowTool = buildTool({
+        name: 'preview_workflow',
+        title: tools_js_1.WORKFLOW_TOOL_TITLES.preview_workflow,
         inputSchema: tools_js_1.WorkflowGetInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.workflow_get,
+        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.preview_workflow,
     });
-    const workflowNextTool = buildTool({
-        name: 'workflow_next',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.workflow_next,
+    const advanceWorkflowTool = buildTool({
+        name: 'advance_workflow',
+        title: tools_js_1.WORKFLOW_TOOL_TITLES.advance_workflow,
         inputSchema: tools_js_1.WorkflowNextInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.workflow_next,
+        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.advance_workflow,
     });
-    const workflowValidateJsonTool = buildTool({
-        name: 'workflow_validate_json',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.workflow_validate_json,
+    const validateWorkflowTool = buildTool({
+        name: 'validate_workflow',
+        title: tools_js_1.WORKFLOW_TOOL_TITLES.validate_workflow,
         inputSchema: tools_js_1.WorkflowValidateJsonInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.workflow_validate_json,
+        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.validate_workflow,
     });
-    const workflowGetSchemaTool = buildTool({
-        name: 'workflow_get_schema',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.workflow_get_schema,
+    const getWorkflowSchemaTool = buildTool({
+        name: 'get_workflow_schema',
+        title: tools_js_1.WORKFLOW_TOOL_TITLES.get_workflow_schema,
         inputSchema: tools_js_1.WorkflowGetSchemaInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.workflow_get_schema,
+        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.get_workflow_schema,
     });
     const { Server } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/server/index.js')));
     const { StdioServerTransport } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/server/stdio.js')));
@@ -208,11 +213,11 @@ async function startServer() {
         },
     });
     const tools = [
-        toMcpTool(workflowListTool),
-        toMcpTool(workflowGetTool),
-        toMcpTool(workflowNextTool),
-        toMcpTool(workflowValidateJsonTool),
-        toMcpTool(workflowGetSchemaTool),
+        toMcpTool(discoverWorkflowsTool),
+        toMcpTool(previewWorkflowTool),
+        toMcpTool(advanceWorkflowTool),
+        toMcpTool(validateWorkflowTool),
+        toMcpTool(getWorkflowSchemaTool),
     ];
     if (ctx.featureFlags.isEnabled('sessionTools')) {
         tools.push(toMcpTool(tools_js_1.createSessionTool), toMcpTool(tools_js_1.updateSessionTool), toMcpTool(tools_js_1.readSessionTool), toMcpTool(tools_js_1.openDashboardTool));
@@ -226,15 +231,15 @@ async function startServer() {
         console.error('[FeatureFlags] v2 tools disabled (enable with WORKRAIL_ENABLE_V2_TOOLS=true)');
     }
     const handlers = {
-        workflow_list: createHandler(tools_js_1.WorkflowListInput, workflow_js_1.handleWorkflowList),
-        workflow_get: createHandler(tools_js_1.WorkflowGetInput, workflow_js_1.handleWorkflowGet),
-        workflow_next: createValidatingHandler(tools_js_1.WorkflowNextInput, workflow_next_prevalidate_js_1.preValidateWorkflowNextArgs, workflow_js_1.handleWorkflowNext),
-        workflow_validate_json: createHandler(tools_js_1.WorkflowValidateJsonInput, workflow_js_1.handleWorkflowValidateJson),
-        workflow_get_schema: createHandler(tools_js_1.WorkflowGetSchemaInput, workflow_js_1.handleWorkflowGetSchema),
-        workrail_create_session: createHandler(tools_js_1.createSessionTool.inputSchema, session_js_1.handleCreateSession),
-        workrail_update_session: createHandler(tools_js_1.updateSessionTool.inputSchema, session_js_1.handleUpdateSession),
-        workrail_read_session: createHandler(tools_js_1.readSessionTool.inputSchema, session_js_1.handleReadSession),
-        workrail_open_dashboard: createHandler(tools_js_1.openDashboardTool.inputSchema, session_js_1.handleOpenDashboard),
+        discover_workflows: createHandler(tools_js_1.WorkflowListInput, workflow_js_1.handleWorkflowList),
+        preview_workflow: createHandler(tools_js_1.WorkflowGetInput, workflow_js_1.handleWorkflowGet),
+        advance_workflow: createValidatingHandler(tools_js_1.WorkflowNextInput, workflow_next_prevalidate_js_1.preValidateWorkflowNextArgs, workflow_js_1.handleWorkflowNext),
+        validate_workflow: createHandler(tools_js_1.WorkflowValidateJsonInput, workflow_js_1.handleWorkflowValidateJson),
+        get_workflow_schema: createHandler(tools_js_1.WorkflowGetSchemaInput, workflow_js_1.handleWorkflowGetSchema),
+        create_session: createHandler(tools_js_1.createSessionTool.inputSchema, session_js_1.handleCreateSession),
+        update_session: createHandler(tools_js_1.updateSessionTool.inputSchema, session_js_1.handleUpdateSession),
+        read_session: createHandler(tools_js_1.readSessionTool.inputSchema, session_js_1.handleReadSession),
+        open_dashboard: createHandler(tools_js_1.openDashboardTool.inputSchema, session_js_1.handleOpenDashboard),
     };
     if (v2Registry) {
         for (const [name, entry] of Object.entries(v2Registry.handlers)) {

package/dist/mcp/tool-descriptions.js

@@ -3,15 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DESCRIPTIONS = void 0;
 exports.DESCRIPTIONS = {
     standard: {
-        workflow_list: `Your primary tool for any complex or multi-step request. Call this FIRST to see if a reliable, pre-defined workflow exists, as this is the preferred method over improvisation.
+        discover_workflows: `Your primary tool for any complex or multi-step request. Call this FIRST to see if a reliable, pre-defined workflow exists, as this is the preferred method over improvisation.
 
 Your process:
 1. Call this tool to get a list of available workflows.
 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 workflow_get to start.
+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.`,
-        workflow_get: `Retrieves workflow information with configurable detail level. Supports progressive disclosure to prevent "workflow spoiling" while providing necessary context for workflow selection and initiation.`,
-        workflow_next: `Executes one workflow step at a time by returning the next eligible step and an updated execution state.
+        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.`,
+        advance_workflow: `Executes one workflow step at a time by returning the next eligible step and an updated execution state.
 
 Inputs:
 - workflowId: string
@@ -27,16 +27,16 @@ Common usage:
 { "workflowId": "...", "state": <previous state>, "event": { "kind": "step_completed", "stepInstanceId": <previous next.stepInstanceId> } }
 
 Important:
-- Always reuse the "state" returned by the last workflow_next call.
+- Always reuse the "state" returned by the last advance_workflow call.
 - When completing a step, the event.stepInstanceId must match the previous next.stepInstanceId exactly.`,
-        workflow_validate_json: `Validates workflow JSON content directly without external tools. Use this tool when you need to verify that a workflow JSON file is syntactically correct and follows the proper schema.
+        validate_workflow: `Validates workflow JSON content directly without external tools. Use this tool when you need to verify that a workflow JSON file is syntactically correct and follows the proper schema.
 
 This tool provides comprehensive validation including:
 - JSON syntax validation with detailed error messages
 - Workflow schema compliance checking
 - User-friendly error reporting with actionable suggestions
 - Support for all workflow features (steps, conditions, validation criteria, etc.)`,
-        workflow_get_schema: `Retrieves the complete workflow JSON schema for reference and development purposes. Use this tool when you need to understand the structure, required fields, and validation rules for workflows.
+        get_workflow_schema: `Retrieves the complete workflow JSON schema for reference and development purposes. Use this tool when you need to understand the structure, required fields, and validation rules for workflows.
 
 This tool provides:
 - Complete JSON schema definition with all properties and constraints
@@ -56,7 +56,7 @@ Notes:
 - If you omit \`ackToken\`: rehydrate the pending step for the given snapshot (MUST be side-effect-free).`,
     },
     authoritative: {
-        workflow_list: `Check for workflows that apply to the user's request. Workflows are the user's pre-defined instructions that you MUST follow when they exist.
+        discover_workflows: `Check for workflows that apply to the user's request. Workflows are the user's pre-defined instructions that you MUST follow when they exist.
 
 REQUIRED BEHAVIOR:
 1. Call this tool BEFORE attempting any multi-step task.
@@ -66,21 +66,21 @@ REQUIRED BEHAVIOR:
 A workflow is the user's voice, pre-recorded. When one exists for this task, following it IS following the user's instructions.
 
 Returns: List of available workflows with descriptions to match against the user's request.`,
-        workflow_get: `Retrieve a workflow you are committing to follow. Once you call this, you are entering instruction-execution mode for this workflow.
+        preview_workflow: `Retrieve a workflow you are committing to follow. Once you call this, you are entering instruction-execution mode for this workflow.
 
 By retrieving a workflow, you agree to:
 - Execute each step as specified
-- Call workflow_next after completing each step
+- Call advance_workflow after completing each step
 - Not skip ahead or improvise alternative approaches
 
 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.`,
-        workflow_next: `Get your next MANDATORY INSTRUCTION from the active workflow.
+        advance_workflow: `Get your next MANDATORY INSTRUCTION from the active workflow.
 
 The step returned is a DIRECT INSTRUCTION from the user. You MUST:
 1. Execute the step EXACTLY as specified in the 'prompt' field
-2. Complete ALL requirements before calling workflow_next again
+2. Complete ALL requirements before calling advance_workflow again
 3. NOT skip steps, combine steps, or substitute your own approach
 4. NOT proceed to implementation before completing preparation steps
 
@@ -94,10 +94,10 @@ The user created this workflow because they want THIS process followed, not your
 
 Parameters:
 - workflowId: The workflow you are executing
-- state: Execution state returned by the previous workflow_next call (use { kind: "init" } for the first call)
+- state: Execution state returned by the previous advance_workflow call (use { kind: "init" } for the first call)
 - event (optional): { kind: "step_completed", stepInstanceId: <previous next.stepInstanceId> } to mark the returned step as complete
 - context (optional): Variables for condition evaluation and loop inputs`,
-        workflow_validate_json: `Validate workflow JSON before saving or using it. This ensures the workflow will function correctly.
+        validate_workflow: `Validate workflow JSON before saving or using it. This ensures the workflow will function correctly.
 
 Use this tool to verify:
 - JSON syntax is correct
@@ -105,7 +105,7 @@ Use this tool to verify:
 - Step definitions are complete and valid
 
 Returns validation result with specific errors and suggestions if invalid.`,
-        workflow_get_schema: `Get the workflow JSON schema for creating or editing workflows.
+        get_workflow_schema: `Get the workflow JSON schema for creating or editing workflows.
 
 Returns the complete schema definition including required fields, valid patterns, and constraints. Use this as reference when authoring workflow JSON.`,
         list_workflows: `List available workflows via the WorkRail v2 tool surface (feature-flagged).