@exaudeus/workrail 0.11.0 → 0.13.0

package/dist/mcp/error-mapper.d.ts

@@ -1,9 +1,4 @@
 import type { DomainError } from '../domain/execution/error.js';
-import type { ErrorCode } from './types.js';
-export interface ToolErrorMapping {
-    readonly code: ErrorCode;
-    readonly message: string;
-    readonly suggestion?: string;
-}
-export declare function mapDomainErrorToToolError(err: DomainError): ToolErrorMapping;
-export declare function mapUnknownErrorToToolError(err: unknown): ToolErrorMapping;
+import type { ToolError } from './types.js';
+export declare function mapDomainErrorToToolError(err: DomainError): ToolError;
+export declare function mapUnknownErrorToToolError(err: unknown): ToolError;

package/dist/mcp/error-mapper.js

@@ -4,55 +4,77 @@ exports.mapDomainErrorToToolError = mapDomainErrorToToolError;
 exports.mapUnknownErrorToToolError = mapUnknownErrorToToolError;
 const bounded_json_js_1 = require("./validation/bounded-json.js");
 function assertNever(x) {
-    throw new Error(`Unhandled DomainError variant: ${JSON.stringify(x)}`);
+    return {
+        type: 'error',
+        code: 'INTERNAL_ERROR',
+        message: `Unhandled DomainError variant: ${JSON.stringify(x)}`,
+        retry: { kind: 'not_retryable' },
+        details: { invariantViolation: 'exhaustiveness_check_failed' },
+    };
 }
 function mapDomainErrorToToolError(err) {
     switch (err._tag) {
         case 'WorkflowNotFound':
             return {
+                type: 'error',
                 code: 'NOT_FOUND',
                 message: err.message,
-                suggestion: `Check available workflows with workflow_list`,
+                retry: { kind: 'not_retryable' },
+                details: { suggestion: `Check available workflows with workflow_list` },
             };
         case 'InvalidState':
             return {
+                type: 'error',
                 code: 'VALIDATION_ERROR',
                 message: err.message,
-                suggestion: `Use the "state" returned by the last workflow_next call.\n` +
-                    `If you are completing a step, send an event like:\n` +
-                    (0, bounded_json_js_1.toBoundedJsonString)({
-                        kind: 'step_completed',
-                        stepInstanceId: {
-                            stepId: '<previous next.stepInstanceId.stepId>',
-                            loopPath: [],
-                        },
-                    }, 512),
+                retry: { kind: 'not_retryable' },
+                details: {
+                    suggestion: `Use the "state" returned by the last workflow_next call.\n` +
+                        `If you are completing a step, send an event like:\n` +
+                        (0, bounded_json_js_1.toBoundedJsonString)({
+                            kind: 'step_completed',
+                            stepInstanceId: {
+                                stepId: '<previous next.stepInstanceId.stepId>',
+                                loopPath: [],
+                            },
+                        }, 512),
+                },
             };
         case 'InvalidLoop':
             return {
+                type: 'error',
                 code: 'VALIDATION_ERROR',
                 message: err.message,
-                suggestion: 'Validate the workflow definition and ensure loop/body step IDs are consistent',
+                retry: { kind: 'not_retryable' },
+                details: { suggestion: 'Validate the workflow definition and ensure loop/body step IDs are consistent' },
             };
         case 'MissingContext':
             return {
+                type: 'error',
                 code: 'PRECONDITION_FAILED',
                 message: err.message,
-                suggestion: 'Provide the required keys in the `context` object for condition evaluation and loop inputs.\n' +
-                    'Example:\n' +
-                    (0, bounded_json_js_1.toBoundedJsonString)({ context: { '<requiredKey>': '<value>' } }, 256),
+                retry: { kind: 'not_retryable' },
+                details: {
+                    suggestion: 'Provide the required keys in the `context` object for condition evaluation and loop inputs.\n' +
+                        'Example:\n' +
+                        (0, bounded_json_js_1.toBoundedJsonString)({ context: { '<requiredKey>': '<value>' } }, 256),
+                },
             };
         case 'ConditionEvalFailed':
             return {
+                type: 'error',
                 code: 'INTERNAL_ERROR',
                 message: err.message,
-                suggestion: 'Validate workflow JSON and condition expressions with workflow_validate_json',
+                retry: { kind: 'not_retryable' },
+                details: { suggestion: 'Validate workflow JSON and condition expressions with workflow_validate_json' },
             };
         case 'MaxIterationsExceeded':
             return {
+                type: 'error',
                 code: 'PRECONDITION_FAILED',
                 message: err.message,
-                suggestion: `Increase maxIterations for loop '${err.loopId}' or adjust its condition/body`,
+                retry: { kind: 'not_retryable' },
+                details: { suggestion: `Increase maxIterations for loop '${err.loopId}' or adjust its condition/body` },
             };
         default:
             return assertNever(err);
@@ -60,7 +82,7 @@ function mapDomainErrorToToolError(err) {
 }
 function mapUnknownErrorToToolError(err) {
     if (err instanceof Error) {
-        return { code: 'INTERNAL_ERROR', message: err.message };
+        return { type: 'error', code: 'INTERNAL_ERROR', message: err.message, retry: { kind: 'not_retryable' } };
     }
-    return { code: 'INTERNAL_ERROR', message: String(err) };
+    return { type: 'error', code: 'INTERNAL_ERROR', message: String(err), retry: { kind: 'not_retryable' } };
 }

package/dist/mcp/handlers/session.js

@@ -42,7 +42,7 @@ const SESSION_SCHEMA_OVERVIEW = {
 };
 function requireSessionTools(ctx) {
     if (!ctx.sessionManager || !ctx.httpServer) {
-        return (0, types_js_1.error)('PRECONDITION_FAILED', 'Session tools are not enabled', 'Set WORKRAIL_ENABLE_SESSION_TOOLS=true to enable session tools');
+        return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', 'Session tools are not enabled', { suggestion: 'Set WORKRAIL_ENABLE_SESSION_TOOLS=true to enable session tools' });
     }
     return null;
 }
@@ -67,7 +67,7 @@ async function handleCreateSession(input, ctx) {
     }
     catch (err) {
         const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return (0, types_js_1.error)(mapped.code, mapped.message, mapped.suggestion);
+        return mapped;
     }
 }
 async function handleUpdateSession(input, ctx) {
@@ -81,12 +81,19 @@ async function handleUpdateSession(input, ctx) {
         return (0, types_js_1.success)(payload);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (message.toLowerCase().includes('not found')) {
-            return (0, types_js_1.error)('NOT_FOUND', message, 'Make sure the session exists. Use workrail_create_session() first.');
+        if (err instanceof Error && (err.name === 'SessionNotFoundError' ||
+            err.message.toLowerCase().includes('not found') ||
+            err.message.toLowerCase().includes('does not exist'))) {
+            return {
+                type: 'error',
+                code: 'NOT_FOUND',
+                message: err.message,
+                retry: { kind: 'not_retryable' },
+                details: { suggestion: 'Make sure the session exists. Use workrail_create_session() first.' },
+            };
         }
         const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return (0, types_js_1.error)(mapped.code, mapped.message, mapped.suggestion);
+        return mapped;
     }
 }
 async function handleReadSession(input, ctx) {
@@ -110,12 +117,19 @@ async function handleReadSession(input, ctx) {
         return (0, types_js_1.success)(payload);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (message.toLowerCase().includes('not found')) {
-            return (0, types_js_1.error)('NOT_FOUND', message, 'Make sure the session exists. Use workrail_create_session() first.');
+        if (err instanceof Error && (err.name === 'SessionNotFoundError' ||
+            err.message.toLowerCase().includes('not found') ||
+            err.message.toLowerCase().includes('does not exist'))) {
+            return {
+                type: 'error',
+                code: 'NOT_FOUND',
+                message: err.message,
+                retry: { kind: 'not_retryable' },
+                details: { suggestion: 'Make sure the session exists. Use workrail_create_session() first.' },
+            };
         }
         const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return (0, types_js_1.error)(mapped.code, mapped.message, mapped.suggestion);
+        return mapped;
     }
 }
 async function handleOpenDashboard(input, ctx) {
@@ -130,6 +144,6 @@ async function handleOpenDashboard(input, ctx) {
     }
     catch (err) {
         const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return (0, types_js_1.error)(mapped.code, mapped.message, mapped.suggestion);
+        return mapped;
     }
 }

package/dist/mcp/handlers/v2-execution-helpers.d.ts

@@ -0,0 +1,99 @@
+import { errNotRetryable, errRetryAfterMs } from '../types.js';
+import type { WorkflowId, WorkflowHash } from '../../v2/durable-core/ids/index.js';
+import type { ExecutionSessionGateErrorV2 } from '../../v2/usecases/execution-session-gate.js';
+import type { SessionEventLogStoreError } from '../../v2/ports/session-event-log-store.port.js';
+import type { SnapshotStoreError } from '../../v2/ports/snapshot-store.port.js';
+import type { PinnedWorkflowStoreError } from '../../v2/ports/pinned-workflow-store.port.js';
+import type { KeyringError } from '../../v2/ports/keyring.port.js';
+import type { TokenDecodeErrorV2, TokenVerifyErrorV2 } from '../../v2/durable-core/tokens/index.js';
+export type ToolFailure = ReturnType<typeof errNotRetryable> | ReturnType<typeof errRetryAfterMs>;
+export type StartWorkflowError = {
+    readonly kind: 'precondition_failed';
+    readonly message: string;
+    readonly suggestion?: string;
+} | {
+    readonly kind: 'invariant_violation';
+    readonly message: string;
+    readonly suggestion?: string;
+} | {
+    readonly kind: 'validation_failed';
+    readonly failure: ToolFailure;
+} | {
+    readonly kind: 'workflow_not_found';
+    readonly workflowId: WorkflowId;
+} | {
+    readonly kind: 'workflow_has_no_steps';
+    readonly workflowId: WorkflowId;
+} | {
+    readonly kind: 'keyring_load_failed';
+    readonly cause: KeyringError;
+} | {
+    readonly kind: 'hash_computation_failed';
+    readonly message: string;
+} | {
+    readonly kind: 'pinned_workflow_store_failed';
+    readonly cause: PinnedWorkflowStoreError;
+} | {
+    readonly kind: 'snapshot_creation_failed';
+    readonly cause: SnapshotStoreError;
+} | {
+    readonly kind: 'session_append_failed';
+    readonly cause: ExecutionSessionGateErrorV2 | SessionEventLogStoreError;
+} | {
+    readonly kind: 'token_signing_failed';
+    readonly cause: TokenDecodeErrorV2 | TokenVerifyErrorV2;
+};
+export type ContinueWorkflowError = {
+    readonly kind: 'precondition_failed';
+    readonly message: string;
+    readonly suggestion?: string;
+} | {
+    readonly kind: 'token_unknown_node';
+    readonly message: string;
+    readonly suggestion?: string;
+} | {
+    readonly kind: 'invariant_violation';
+    readonly message: string;
+    readonly suggestion?: string;
+} | {
+    readonly kind: 'validation_failed';
+    readonly failure: ToolFailure;
+} | {
+    readonly kind: 'token_decode_failed';
+    readonly cause: TokenDecodeErrorV2;
+} | {
+    readonly kind: 'token_verify_failed';
+    readonly cause: TokenVerifyErrorV2;
+} | {
+    readonly kind: 'keyring_load_failed';
+    readonly cause: KeyringError;
+} | {
+    readonly kind: 'session_load_failed';
+    readonly cause: SessionEventLogStoreError;
+} | {
+    readonly kind: 'snapshot_load_failed';
+    readonly cause: SnapshotStoreError;
+} | {
+    readonly kind: 'pinned_workflow_store_failed';
+    readonly cause: PinnedWorkflowStoreError;
+} | {
+    readonly kind: 'pinned_workflow_missing';
+    readonly workflowHash: WorkflowHash;
+} | {
+    readonly kind: 'token_signing_failed';
+    readonly cause: TokenDecodeErrorV2 | TokenVerifyErrorV2;
+} | {
+    readonly kind: 'advance_execution_failed';
+    readonly cause: ExecutionSessionGateErrorV2 | SessionEventLogStoreError;
+};
+export declare function mapStartWorkflowErrorToToolError(e: StartWorkflowError): ToolFailure;
+export declare function mapContinueWorkflowErrorToToolError(e: ContinueWorkflowError): ToolFailure;
+export declare function mapTokenDecodeErrorToToolError(e: TokenDecodeErrorV2): ToolFailure;
+export declare function mapTokenVerifyErrorToToolError(e: TokenVerifyErrorV2): ToolFailure;
+export declare function mapTokenSigningErrorToToolError(e: TokenDecodeErrorV2 | TokenVerifyErrorV2): ToolFailure;
+export declare function mapKeyringErrorToToolError(e: KeyringError): ToolFailure;
+export declare function mapSessionEventLogStoreErrorToToolError(e: SessionEventLogStoreError): ToolFailure;
+export declare function mapExecutionSessionGateErrorToToolError(e: ExecutionSessionGateErrorV2): ToolFailure;
+export declare function mapSnapshotStoreErrorToToolError(e: SnapshotStoreError, suggestion?: string): ToolFailure;
+export declare function mapPinnedWorkflowStoreErrorToToolError(e: PinnedWorkflowStoreError, suggestion?: string): ToolFailure;
+export declare function mapSessionOrGateErrorToToolError(e: SessionEventLogStoreError | ExecutionSessionGateErrorV2): ToolFailure;

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

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapStartWorkflowErrorToToolError = mapStartWorkflowErrorToToolError;
+exports.mapContinueWorkflowErrorToToolError = mapContinueWorkflowErrorToToolError;
+exports.mapTokenDecodeErrorToToolError = mapTokenDecodeErrorToToolError;
+exports.mapTokenVerifyErrorToToolError = mapTokenVerifyErrorToToolError;
+exports.mapTokenSigningErrorToToolError = mapTokenSigningErrorToToolError;
+exports.mapKeyringErrorToToolError = mapKeyringErrorToToolError;
+exports.mapSessionEventLogStoreErrorToToolError = mapSessionEventLogStoreErrorToToolError;
+exports.mapExecutionSessionGateErrorToToolError = mapExecutionSessionGateErrorToToolError;
+exports.mapSnapshotStoreErrorToToolError = mapSnapshotStoreErrorToToolError;
+exports.mapPinnedWorkflowStoreErrorToToolError = mapPinnedWorkflowStoreErrorToToolError;
+exports.mapSessionOrGateErrorToToolError = mapSessionOrGateErrorToToolError;
+const types_js_1 = require("../types.js");
+const types_js_2 = require("../types.js");
+function mapStartWorkflowErrorToToolError(e) {
+    switch (e.kind) {
+        case 'precondition_failed':
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', e.message, e.suggestion ? { suggestion: e.suggestion } : undefined);
+        case 'invariant_violation':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', e.message, e.suggestion ? { suggestion: e.suggestion } : undefined);
+        case 'validation_failed':
+            return e.failure;
+        case 'workflow_not_found':
+            return (0, types_js_1.errNotRetryable)('NOT_FOUND', `Workflow not found: ${e.workflowId}`, {
+                suggestion: 'Use list_workflows to discover available workflows.',
+            });
+        case 'workflow_has_no_steps':
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', 'Workflow has no steps and cannot be started.', {
+                suggestion: 'Fix the workflow definition (must contain at least one step).',
+            });
+        case 'keyring_load_failed':
+            return mapKeyringErrorToToolError(e.cause);
+        case 'hash_computation_failed':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Failed to compute workflow hash: ${e.message}`, {
+                suggestion: 'Retry start_workflow; if this persists, treat as invariant violation.',
+            });
+        case 'pinned_workflow_store_failed':
+            return mapPinnedWorkflowStoreErrorToToolError(e.cause);
+        case 'snapshot_creation_failed':
+            return mapSnapshotStoreErrorToToolError(e.cause);
+        case 'session_append_failed':
+            return mapSessionOrGateErrorToToolError(e.cause);
+        case 'token_signing_failed':
+            return mapTokenSigningErrorToToolError(e.cause);
+        default:
+            const _exhaustive = e;
+            return _exhaustive;
+    }
+}
+function mapContinueWorkflowErrorToToolError(e) {
+    switch (e.kind) {
+        case 'precondition_failed':
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', e.message, e.suggestion ? { suggestion: e.suggestion } : undefined);
+        case 'token_unknown_node':
+            return (0, types_js_1.errNotRetryable)('TOKEN_UNKNOWN_NODE', e.message, e.suggestion ? { suggestion: e.suggestion } : undefined);
+        case 'invariant_violation':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', e.message, e.suggestion ? { suggestion: e.suggestion } : undefined);
+        case 'validation_failed':
+            return e.failure;
+        case 'token_decode_failed':
+            return mapTokenDecodeErrorToToolError(e.cause);
+        case 'token_verify_failed':
+            return mapTokenVerifyErrorToToolError(e.cause);
+        case 'keyring_load_failed':
+            return mapKeyringErrorToToolError(e.cause);
+        case 'session_load_failed':
+            return mapSessionEventLogStoreErrorToToolError(e.cause);
+        case 'snapshot_load_failed':
+            return mapSnapshotStoreErrorToToolError(e.cause);
+        case 'pinned_workflow_store_failed':
+            return mapPinnedWorkflowStoreErrorToToolError(e.cause);
+        case 'pinned_workflow_missing':
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', `Pinned workflow snapshot is missing for hash: ${e.workflowHash}`, {
+                suggestion: 'Re-run start_workflow or re-pin the workflow via inspect_workflow.',
+            });
+        case 'token_signing_failed':
+            return mapTokenSigningErrorToToolError(e.cause);
+        case 'advance_execution_failed':
+            return mapSessionOrGateErrorToToolError(e.cause);
+        default:
+            const _exhaustive = e;
+            return _exhaustive;
+    }
+}
+function mapTokenDecodeErrorToToolError(e) {
+    switch (e.code) {
+        case 'TOKEN_INVALID_FORMAT':
+            return (0, types_js_1.errNotRetryable)('TOKEN_INVALID_FORMAT', e.message, {
+                suggestion: 'Use the exact tokens returned by WorkRail. Tokens are opaque; do not edit or construct them.',
+            });
+        case 'TOKEN_UNSUPPORTED_VERSION':
+            return (0, types_js_1.errNotRetryable)('TOKEN_UNSUPPORTED_VERSION', e.message, {
+                suggestion: 'Update WorkRail to a version that supports this token format.',
+            });
+        case 'TOKEN_SCOPE_MISMATCH':
+            return (0, types_js_1.errNotRetryable)('TOKEN_SCOPE_MISMATCH', e.message, {
+                suggestion: 'Tokens must come from the same WorkRail response. Do not mix tokens from different runs or nodes.',
+            });
+        case 'TOKEN_PAYLOAD_INVALID':
+            return (0, types_js_1.errNotRetryable)('TOKEN_INVALID_FORMAT', e.message, {
+                suggestion: 'Use the exact tokens returned by WorkRail.',
+            });
+        default:
+            const _exhaustive = e;
+            return _exhaustive;
+    }
+}
+function mapTokenVerifyErrorToToolError(e) {
+    switch (e.code) {
+        case 'TOKEN_BAD_SIGNATURE':
+            return (0, types_js_1.errNotRetryable)('TOKEN_BAD_SIGNATURE', e.message, {
+                suggestion: 'Token signature verification failed. Use the exact tokens returned by WorkRail.',
+            });
+        case 'TOKEN_INVALID_FORMAT':
+            return (0, types_js_1.errNotRetryable)('TOKEN_INVALID_FORMAT', e.message, {
+                suggestion: 'Use the exact tokens returned by WorkRail.',
+            });
+        default:
+            const _exhaustive = e;
+            return _exhaustive;
+    }
+}
+function mapTokenSigningErrorToToolError(e) {
+    switch (e.code) {
+        case 'TOKEN_UNSUPPORTED_VERSION':
+            return (0, types_js_1.errNotRetryable)('TOKEN_UNSUPPORTED_VERSION', e.message, {
+                suggestion: 'Update WorkRail to a version that supports this token format.',
+            });
+        case 'TOKEN_SCOPE_MISMATCH':
+            return (0, types_js_1.errNotRetryable)('TOKEN_SCOPE_MISMATCH', e.message, {
+                suggestion: 'Tokens must come from the same WorkRail response. Do not mix tokens from different runs or nodes.',
+            });
+        case 'TOKEN_PAYLOAD_INVALID':
+            return (0, types_js_1.errNotRetryable)('TOKEN_INVALID_FORMAT', e.message, {
+                suggestion: 'Use the exact tokens returned by WorkRail.',
+            });
+        case 'TOKEN_BAD_SIGNATURE':
+            return (0, types_js_1.errNotRetryable)('TOKEN_BAD_SIGNATURE', e.message, {
+                suggestion: 'Token signature verification failed. Use the exact tokens returned by WorkRail.',
+            });
+        case 'TOKEN_INVALID_FORMAT':
+            return (0, types_js_1.errNotRetryable)('TOKEN_INVALID_FORMAT', e.message, {
+                suggestion: 'Use the exact tokens returned by WorkRail. Tokens are opaque; do not edit or construct them.',
+            });
+        default:
+            const _exhaustive = e;
+            return _exhaustive;
+    }
+}
+function mapKeyringErrorToToolError(e) {
+    switch (e.code) {
+        case 'KEYRING_IO_ERROR':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Keyring I/O error: ${e.message}`, {
+                suggestion: 'Retry; check filesystem permissions. If this persists, treat as invariant violation.',
+            });
+        case 'KEYRING_CORRUPTION_DETECTED':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Keyring corruption detected: ${e.message}`, {
+                suggestion: 'Delete the WorkRail v2 data directory for this repo and retry.',
+            });
+        case 'KEYRING_INVARIANT_VIOLATION':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Keyring invariant violation: ${e.message}`, {
+                suggestion: 'Treat as invariant violation.',
+            });
+        default:
+            const _exhaustive = e;
+            return _exhaustive;
+    }
+}
+function mapSessionEventLogStoreErrorToToolError(e) {
+    switch (e.code) {
+        case 'SESSION_STORE_LOCK_BUSY':
+            return (0, types_js_1.errRetryAfterMs)('INTERNAL_ERROR', e.message, e.retry.afterMs, {
+                suggestion: 'Another WorkRail process may be writing to this session; retry.',
+            });
+        case 'SESSION_STORE_CORRUPTION_DETECTED':
+            return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', `Session corruption detected: ${e.reason.code}`, {
+                suggestion: 'Execution requires a healthy session. Export salvage view, then recreate.',
+                details: (0, types_js_2.detailsSessionHealth)({ kind: e.location === 'head' ? 'corrupt_head' : 'corrupt_tail', reason: e.reason }),
+            });
+        case 'SESSION_STORE_IO_ERROR':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', e.message, {
+                suggestion: 'Retry; check filesystem permissions.',
+            });
+        case 'SESSION_STORE_INVARIANT_VIOLATION':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', e.message, {
+                suggestion: 'Treat as invariant violation.',
+            });
+        default:
+            const _exhaustive = e;
+            return _exhaustive;
+    }
+}
+function mapExecutionSessionGateErrorToToolError(e) {
+    switch (e.code) {
+        case 'SESSION_LOCKED':
+            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', e.message, e.retry.afterMs, {
+                suggestion: 'Retry in 1–3 seconds; if this persists >10s, ensure no other WorkRail process is running.',
+            });
+        case 'LOCK_RELEASE_FAILED':
+            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', e.message, e.retry.afterMs, {
+                suggestion: 'Retry in 1–3 seconds; if this persists >10s, ensure no other WorkRail process is running.',
+            });
+        case 'SESSION_NOT_HEALTHY':
+            return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', e.message, {
+                suggestion: 'Execution requires healthy session.',
+                details: (0, types_js_2.detailsSessionHealth)(e.health),
+            });
+        case 'SESSION_LOAD_FAILED':
+        case 'SESSION_LOCK_REENTRANT':
+        case 'LOCK_ACQUIRE_FAILED':
+        case 'GATE_CALLBACK_FAILED':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', e.message, {
+                suggestion: 'Retry; if this persists, treat as invariant violation.',
+            });
+        default:
+            const _exhaustive = e;
+            return _exhaustive;
+    }
+}
+function mapSnapshotStoreErrorToToolError(e, suggestion) {
+    return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Snapshot store error: ${e.message}`, {
+        suggestion: suggestion ?? 'Retry; if this persists, treat as invariant violation.',
+    });
+}
+function mapPinnedWorkflowStoreErrorToToolError(e, suggestion) {
+    return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Pinned workflow store error: ${e.message}`, {
+        suggestion: suggestion ?? 'Retry; if this persists, treat as invariant violation.',
+    });
+}
+function mapSessionOrGateErrorToToolError(e) {
+    if (e.code === 'SESSION_LOCKED' ||
+        e.code === 'LOCK_RELEASE_FAILED' ||
+        e.code === 'SESSION_NOT_HEALTHY' ||
+        e.code === 'SESSION_LOAD_FAILED' ||
+        e.code === 'SESSION_LOCK_REENTRANT' ||
+        e.code === 'LOCK_ACQUIRE_FAILED' ||
+        e.code === 'GATE_CALLBACK_FAILED') {
+        return mapExecutionSessionGateErrorToToolError(e);
+    }
+    if (e.code === 'SESSION_STORE_LOCK_BUSY' ||
+        e.code === 'SESSION_STORE_IO_ERROR' ||
+        e.code === 'SESSION_STORE_CORRUPTION_DETECTED' ||
+        e.code === 'SESSION_STORE_INVARIANT_VIOLATION') {
+        return mapSessionEventLogStoreErrorToToolError(e);
+    }
+    const _exhaustive = e;
+    return _exhaustive;
+}

package/dist/mcp/handlers/v2-execution.d.ts

@@ -0,0 +1,4 @@
+import type { ToolContext, ToolResult } from '../types.js';
+import type { V2ContinueWorkflowInput, V2StartWorkflowInput } from '../v2/tools.js';
+export declare function handleV2StartWorkflow(input: V2StartWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
+export declare function handleV2ContinueWorkflow(input: V2ContinueWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;