@exaudeus/workrail 1.5.1 → 1.5.2

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultPreferences = void 0;
+exports.internalSuggestion = internalSuggestion;
 exports.mapStartWorkflowErrorToToolError = mapStartWorkflowErrorToToolError;
 exports.mapContinueWorkflowErrorToToolError = mapContinueWorkflowErrorToToolError;
 exports.mapTokenDecodeErrorToToolError = mapTokenDecodeErrorToToolError;
@@ -16,28 +17,30 @@ exports.renderPendingPromptOrDefault = renderPendingPromptOrDefault;
 exports.derivePreferencesOrDefault = derivePreferencesOrDefault;
 const types_js_1 = require("../types.js");
 const types_js_2 = require("../types.js");
+const ESCALATION_SUFFIX = ' To report this, share the name of the tool you called, the input you provided, and this error message with the user so they can forward it to the WorkRail developer.';
+function internalSuggestion(retryAdvice, userMessage) {
+    return `${retryAdvice} If the error persists, tell the user: "${userMessage}"${ESCALATION_SUFFIX}`;
+}
 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);
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail encountered an unexpected error while starting the workflow. This is not caused by your input.', { suggestion: internalSuggestion('Retry start_workflow.', 'WorkRail has an internal error.') });
         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.',
+                suggestion: 'Call list_workflows to see available workflows and verify the workflowId.',
             });
         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).',
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', `Workflow "${e.workflowId}" has no steps and cannot be started.`, {
+                suggestion: 'Tell the user: "This workflow definition is empty (no steps). The workflow JSON file needs to be fixed."',
             });
         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.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not compute a content hash for the workflow definition. This is not caused by your input.', { suggestion: internalSuggestion('Retry start_workflow.', 'WorkRail has an internal error computing workflow hashes.') });
         case 'pinned_workflow_store_failed':
             return mapPinnedWorkflowStoreErrorToToolError(e.cause);
         case 'snapshot_creation_failed':
@@ -58,7 +61,7 @@ function mapContinueWorkflowErrorToToolError(e) {
         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);
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail encountered an unexpected error while continuing the workflow. This is not caused by your input.', { suggestion: internalSuggestion('Retry continue_workflow.', 'WorkRail has an internal error.') });
         case 'validation_failed':
             return e.failure;
         case 'token_decode_failed':
@@ -74,9 +77,7 @@ function mapContinueWorkflowErrorToToolError(e) {
         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.',
-            });
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', 'The stored workflow definition for this session is missing. The session may have been created with a different WorkRail data directory.', { suggestion: 'Call start_workflow again to create a fresh session for this workflow.' });
         case 'token_signing_failed':
             return mapTokenSigningErrorToToolError(e.cause);
         case 'advance_execution_failed':
@@ -160,13 +161,9 @@ function mapTokenSigningErrorToToolError(e) {
                 suggestion: 'Use the exact tokens returned by WorkRail.',
             });
         case 'TOKEN_ENCODE_FAILED':
-            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Token encoding failed: ${e.message}`, {
-                suggestion: 'Retry; if this persists, treat as invariant violation.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not create a security token for this operation. This is not caused by your input.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail has an internal error creating tokens.') });
         case 'KEYRING_INVALID':
-            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Keyring invalid: ${e.message}`, {
-                suggestion: 'Regenerate v2 keyring by deleting the v2 data directory and retrying.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail\'s security keys are in an invalid state and cannot sign tokens.', { suggestion: internalSuggestion('', 'WorkRail\'s security keys need to be regenerated. Delete the .workrail/v2 data directory and restart.') });
         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.',
@@ -183,17 +180,11 @@ function mapTokenSigningErrorToToolError(e) {
 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.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not read its security keys from disk.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail cannot access its security keys. Check that the ~/.workrail directory is readable.') });
         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.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail\'s security keys are corrupted and cannot be used.', { suggestion: internalSuggestion('', 'WorkRail\'s security keys are corrupted. Delete the .workrail/v2 directory and restart WorkRail to regenerate them.') });
         case 'KEYRING_INVARIANT_VIOLATION':
-            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Keyring invariant violation: ${e.message}`, {
-                suggestion: 'Treat as invariant violation.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail\'s security key system encountered an unexpected error. This is not caused by your input.', { suggestion: internalSuggestion('', 'WorkRail has an internal error with its security keys.') });
         default:
             const _exhaustive = e;
             return _exhaustive;
@@ -202,22 +193,16 @@ function mapKeyringErrorToToolError(e) {
 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.',
-            });
+            return (0, types_js_1.errRetryAfterMs)('INTERNAL_ERROR', 'The session is temporarily busy (another operation is in progress).', e.retry.afterMs, { suggestion: internalSuggestion('Retry this call in a few seconds.', 'Another WorkRail process may be accessing this session.') });
         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.',
+            return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', 'This session\'s data is corrupted and cannot be used.', {
+                suggestion: `This session cannot be recovered. Call start_workflow to create a new session for this workflow.${ESCALATION_SUFFIX}`,
                 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.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not read or write session data to disk.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail cannot access its data files. Check that the ~/.workrail directory exists and is writable.') });
         case 'SESSION_STORE_INVARIANT_VIOLATION':
-            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', e.message, {
-                suggestion: 'Treat as invariant violation.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail encountered an unexpected error with session storage. This is not caused by your input.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail has an internal storage error.') });
         default:
             const _exhaustive = e;
             return _exhaustive;
@@ -226,42 +211,32 @@ function mapSessionEventLogStoreErrorToToolError(e) {
 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.',
-            });
+            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', 'This session is currently being modified by another operation.', e.retry.afterMs, { suggestion: internalSuggestion('Wait a moment and retry this call.', 'Another WorkRail process may be accessing this session.') });
         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.',
-            });
+            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', 'A previous operation on this session did not release cleanly.', e.retry.afterMs, { suggestion: 'Wait a moment and retry this call. The lock will auto-expire shortly.' });
         case 'SESSION_NOT_HEALTHY':
-            return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', e.message, {
-                suggestion: 'Execution requires healthy session.',
+            return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', 'This session is in an unhealthy state and cannot accept new operations.', {
+                suggestion: `This session cannot be used. Call start_workflow to create a new session.${ESCALATION_SUFFIX}`,
                 details: (0, types_js_2.detailsSessionHealth)(e.health),
             });
         case 'SESSION_LOCK_REENTRANT':
-            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', e.message, 1000, {
-                suggestion: 'Session is currently locked by concurrent execution. Retry in 1 second.',
-            });
+            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', 'This session is already being modified by a concurrent call you made. Only one operation at a time is allowed per session.', 1000, { suggestion: 'Wait for your other call to complete, then retry this one.' });
         case 'SESSION_LOAD_FAILED':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not load the session data for this operation.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail cannot load session data.') });
         case 'LOCK_ACQUIRE_FAILED':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not acquire a lock on this session.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail is having trouble with session locking — check if another WorkRail process is running.') });
         case 'GATE_CALLBACK_FAILED':
-            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', e.message, {
-                suggestion: 'Retry; if this persists, treat as invariant violation.',
-            });
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail encountered an error while processing this session operation. This is not caused by your input.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail has an internal error.') });
         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 mapSnapshotStoreErrorToToolError(e, _suggestion) {
+    return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not access its execution state data. This is not caused by your input.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail has an internal storage error.') });
 }
-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 mapPinnedWorkflowStoreErrorToToolError(e, _suggestion) {
+    return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not access the stored workflow definition. This is not caused by your input.', { suggestion: internalSuggestion('Retry the call.', 'WorkRail has an internal storage error.') });
 }
 function mapSessionOrGateErrorToToolError(e) {
     if (e.code === 'SESSION_LOCKED' ||

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

@@ -5,22 +5,17 @@ exports.handleV2InspectWorkflow = handleV2InspectWorkflow;
 const neverthrow_1 = require("neverthrow");
 const types_js_1 = require("../types.js");
 const error_mapper_js_1 = require("../error-mapper.js");
+const v2_execution_helpers_js_1 = require("./v2-execution-helpers.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 hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
 const TIMEOUT_MS = 30000;
 const with_timeout_js_1 = require("./shared/with-timeout.js");
-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;
+    const guard = (0, types_js_1.requireV2Context)(ctx);
+    if (!guard.ok)
+        return guard.error;
+    const { crypto, pinnedStore } = guard.ctx.v2;
     return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(ctx.workflowService.listWorkflowSummaries(), TIMEOUT_MS, 'list_workflows'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
         .andThen((summaries) => neverthrow_1.ResultAsync.combine(summaries.map((s) => neverthrow_1.ResultAsync.fromPromise(ctx.workflowService.getWorkflowById(s.id), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)).andThen((wf) => {
         if (!wf) {
@@ -80,10 +75,10 @@ async function handleV2ListWorkflows(_input, ctx) {
         .match((result) => Promise.resolve(result), (err) => Promise.resolve(err));
 }
 async function handleV2InspectWorkflow(input, ctx) {
-    const v2Err = requireV2(ctx);
-    if (v2Err)
-        return v2Err;
-    const { crypto, pinnedStore } = ctx.v2;
+    const guard = (0, types_js_1.requireV2Context)(ctx);
+    if (!guard.ok)
+        return guard.error;
+    const { crypto, pinnedStore } = guard.ctx.v2;
     return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(ctx.workflowService.getWorkflowById(input.workflowId), TIMEOUT_MS, 'inspect_workflow'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
         .andThen((workflow) => {
         if (!workflow) {
@@ -92,7 +87,7 @@ async function handleV2InspectWorkflow(input, ctx) {
         const snapshot = (0, v1_to_v2_shim_js_1.compileV1WorkflowToV2PreviewSnapshot)(workflow);
         const hashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(snapshot, crypto);
         if (hashRes.isErr()) {
-            return (0, neverthrow_1.errAsync)((0, types_js_1.errNotRetryable)('INTERNAL_ERROR', hashRes.error.message));
+            return (0, neverthrow_1.errAsync)((0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not compute a content hash for the workflow definition. This is not caused by your input.', { suggestion: (0, v2_execution_helpers_js_1.internalSuggestion)('Retry inspect_workflow.', 'WorkRail has an internal error computing workflow hashes.') }));
         }
         const workflowHash = hashRes.value;
         return pinnedStore
@@ -104,9 +99,9 @@ async function handleV2InspectWorkflow(input, ctx) {
             return (0, neverthrow_1.okAsync)(existing);
         })
             .orElse(() => (0, neverthrow_1.okAsync)(snapshot))
-            .map((compiled) => {
+            .andThen((compiled) => {
             if (!compiled) {
-                throw new Error('Compiled workflow unexpectedly null');
+                return (0, neverthrow_1.errAsync)((0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not produce a compiled workflow snapshot. This is not caused by your input.', { suggestion: (0, v2_execution_helpers_js_1.internalSuggestion)('Retry inspect_workflow.', 'WorkRail has an internal error.') }));
             }
             const body = input.mode === 'metadata'
                 ? { schemaVersion: compiled.schemaVersion, sourceKind: compiled.sourceKind, workflowId: compiled.workflowId }
@@ -117,7 +112,7 @@ async function handleV2InspectWorkflow(input, ctx) {
                 mode: input.mode,
                 compiled: body,
             });
-            return (0, types_js_1.success)(payload);
+            return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
         });
     })
         .match((result) => Promise.resolve(result), (err) => Promise.resolve(err));