@exaudeus/workrail 1.5.0 → 1.5.2

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

@@ -8,8 +8,9 @@ const v2_token_ops_js_1 = require("./v2-token-ops.js");
 const index_js_1 = require("../../v2/durable-core/ids/index.js");
 const workflow_hash_ref_js_1 = require("../../v2/durable-core/ids/workflow-hash-ref.js");
 const index_js_2 = require("../../v2/durable-core/schemas/session/index.js");
+const constants_js_1 = require("../../v2/durable-core/constants.js");
 function findNodeCreated(events, nodeId) {
-    return events.find((e) => e.kind === 'node_created' && e.scope?.nodeId === String(nodeId));
+    return events.find((e) => e.kind === constants_js_1.EVENT_KIND.NODE_CREATED && e.scope?.nodeId === String(nodeId));
 }
 function mintStateTokenForNode(originalNode, sessionId, runId, nodeId, tokenCodecPorts) {
     const wfRefRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(originalNode.data.workflowHash);
@@ -40,19 +41,13 @@ function isGateError(e) {
     return typeof e === 'object' && e !== null && 'code' in e && typeof e.code === 'string' && !('kind' in e);
 }
 async function handleV2CheckpointWorkflow(input, ctx) {
-    return executeCheckpoint(input, ctx).match((payload) => (0, types_js_1.success)(payload), (e) => mapCheckpointErrorToToolError(e));
+    const guard = (0, types_js_1.requireV2Context)(ctx);
+    if (!guard.ok)
+        return guard.error;
+    return executeCheckpoint(input, guard.ctx).match((payload) => (0, types_js_1.success)(payload), (e) => mapCheckpointErrorToToolError(e));
 }
 function executeCheckpoint(input, ctx) {
-    if (!ctx.v2) {
-        return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 tools disabled' });
-    }
     const { gate, sessionStore, tokenCodecPorts, idFactory } = ctx.v2;
-    if (!tokenCodecPorts) {
-        return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 context missing tokenCodecPorts' });
-    }
-    if (!idFactory) {
-        return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 context missing idFactory' });
-    }
     const tokenRes = (0, v2_token_ops_js_1.parseCheckpointTokenOrFail)(input.checkpointToken, tokenCodecPorts);
     if (!tokenRes.ok) {
         return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: tokenRes.failure });
@@ -85,7 +80,7 @@ function executeCheckpoint(input, ctx) {
     });
 }
 function replayCheckpoint(events, dedupeKey, originalNode, sessionId, runId, nodeId, tokenCodecPorts) {
-    const existingCheckpointNode = events.find((e) => e.kind === 'node_created' && e.dedupeKey === `checkpoint_node:${dedupeKey}`);
+    const existingCheckpointNode = events.find((e) => e.kind === constants_js_1.EVENT_KIND.NODE_CREATED && e.dedupeKey === `checkpoint_node:${dedupeKey}`);
     const checkpointNodeId = existingCheckpointNode
         ? String(existingCheckpointNode.scope?.nodeId ?? 'unknown')
         : 'unknown';
@@ -95,6 +90,7 @@ function replayCheckpoint(events, dedupeKey, originalNode, sessionId, runId, nod
     return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2CheckpointWorkflowOutputSchema.parse({
         checkpointNodeId,
         stateToken: tokenResult.value,
+        nextCall: { tool: 'continue_workflow', params: { intent: 'rehydrate', stateToken: tokenResult.value } },
     }));
 }
 function writeCheckpoint(truth, dedupeKey, originalNode, sessionId, runId, nodeId, checkpointNodeId, mintEventId, lock, sessionStore, tokenCodecPorts) {
@@ -106,7 +102,7 @@ function writeCheckpoint(truth, dedupeKey, originalNode, sessionId, runId, nodeI
             eventId: nodeCreatedEventId,
             eventIndex: truth.events.length,
             sessionId: String(sessionId),
-            kind: 'node_created',
+            kind: constants_js_1.EVENT_KIND.NODE_CREATED,
             dedupeKey: `checkpoint_node:${dedupeKey}`,
             scope: { runId: String(runId), nodeId: String(checkpointNodeId) },
             data: {
@@ -121,7 +117,7 @@ function writeCheckpoint(truth, dedupeKey, originalNode, sessionId, runId, nodeI
             eventId: edgeCreatedEventId,
             eventIndex: truth.events.length + 1,
             sessionId: String(sessionId),
-            kind: 'edge_created',
+            kind: constants_js_1.EVENT_KIND.EDGE_CREATED,
             dedupeKey,
             scope: { runId: String(runId) },
             data: {
@@ -153,6 +149,7 @@ function writeCheckpoint(truth, dedupeKey, originalNode, sessionId, runId, nodeI
         return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2CheckpointWorkflowOutputSchema.parse({
             checkpointNodeId: String(checkpointNodeId),
             stateToken: tokenResult.value,
+            nextCall: { tool: 'continue_workflow', params: { intent: 'rehydrate', stateToken: tokenResult.value } },
         }));
     });
 }

package/dist/mcp/handlers/v2-context-budget.js

@@ -154,9 +154,9 @@ function checkContextBudget(args) {
 function collectArtifactsForEvaluation(args) {
     const collected = [];
     for (const e of args.truthEvents) {
-        if (e.kind !== 'node_output_appended')
+        if (e.kind !== constants_js_1.EVENT_KIND.NODE_OUTPUT_APPENDED)
             continue;
-        if (e.data.outputChannel !== 'artifact')
+        if (e.data.outputChannel !== constants_js_1.OUTPUT_CHANNEL.ARTIFACT)
             continue;
         if (e.data.payload.payloadKind !== 'artifact_ref')
             continue;

package/dist/mcp/handlers/v2-error-mapping.d.ts

@@ -2,7 +2,7 @@ import type { SessionEventLogStoreError } from '../../v2/ports/session-event-log
 import type { ExecutionSessionGateErrorV2 } from '../../v2/usecases/execution-session-gate.js';
 import type { SnapshotStoreError } from '../../v2/ports/snapshot-store.port.js';
 import type { PinnedWorkflowStoreError } from '../../v2/ports/pinned-workflow-store.port.js';
-import type { ToolFailure } from './v2-execution-helpers.js';
+import { type ToolFailure } from './v2-execution-helpers.js';
 export type InternalError = {
     readonly kind: 'invariant_violation';
     readonly message: string;
@@ -29,6 +29,6 @@ export declare function normalizeTokenErrorMessage(message: string): string;
 export declare function internalError(message: string, suggestion?: string): ToolFailure;
 export declare function sessionStoreErrorToToolError(e: SessionEventLogStoreError): ToolFailure;
 export declare function gateErrorToToolError(e: ExecutionSessionGateErrorV2): ToolFailure;
-export declare function snapshotStoreErrorToToolError(e: SnapshotStoreError, suggestion?: string): ToolFailure;
-export declare function pinnedWorkflowStoreErrorToToolError(e: PinnedWorkflowStoreError, suggestion?: string): ToolFailure;
+export declare function snapshotStoreErrorToToolError(_e: SnapshotStoreError, _suggestion?: string): ToolFailure;
+export declare function pinnedWorkflowStoreErrorToToolError(_e: PinnedWorkflowStoreError, _suggestion?: string): ToolFailure;
 export declare function mapInternalErrorToToolError(e: InternalError): ToolFailure;

package/dist/mcp/handlers/v2-error-mapping.js

@@ -42,6 +42,7 @@ exports.snapshotStoreErrorToToolError = snapshotStoreErrorToToolError;
 exports.pinnedWorkflowStoreErrorToToolError = pinnedWorkflowStoreErrorToToolError;
 exports.mapInternalErrorToToolError = mapInternalErrorToToolError;
 const types_js_1 = require("../types.js");
+const v2_execution_helpers_js_1 = require("./v2-execution-helpers.js");
 function isInternalError(e) {
     return (typeof e === 'object' &&
         e !== null &&
@@ -58,68 +59,71 @@ function internalError(message, suggestion) {
 function sessionStoreErrorToToolError(e) {
     switch (e.code) {
         case 'SESSION_STORE_LOCK_BUSY':
-            return (0, types_js_1.errRetryAfterMs)('INTERNAL_ERROR', normalizeTokenErrorMessage(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: (0, v2_execution_helpers_js_1.internalSuggestion)('Wait a moment and retry this call.', '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: (0, v2_execution_helpers_js_1.internalSuggestion)('This session cannot be recovered. Call start_workflow to create a new session.', 'The session data was corrupted.'),
                 details: (0, types_js_1.detailsSessionHealth)({ kind: e.location === 'head' ? 'corrupt_head' : 'corrupt_tail', reason: e.reason }),
             });
         case 'SESSION_STORE_IO_ERROR':
-            return internalError(e.message, 'Retry; check filesystem permissions.');
+            return internalError('WorkRail could not read or write session data to disk.', (0, v2_execution_helpers_js_1.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 internalError(e.message, 'Treat as invariant violation.');
+            return internalError('WorkRail encountered an unexpected error with session storage. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal storage error.'));
         default:
             const _exhaustive = e;
-            return internalError('Unknown session store error', 'Treat as invariant violation.');
+            return internalError('WorkRail encountered an unexpected session storage error. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error.'));
     }
 }
 function gateErrorToToolError(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: (0, v2_execution_helpers_js_1.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.', details: (0, types_js_1.detailsSessionHealth)(e.health) });
-        case 'SESSION_LOCK_REENTRANT':
-            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', e.message, 1000, {
-                suggestion: 'Session is locked by concurrent execution. Retry in 1 second.',
+            return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', 'This session is in an unhealthy state and cannot accept new operations.', {
+                suggestion: (0, v2_execution_helpers_js_1.internalSuggestion)('This session cannot be used. Call start_workflow to create a new session.', 'The session is in an unhealthy state.'),
+                details: (0, types_js_1.detailsSessionHealth)(e.health),
             });
+        case 'SESSION_LOCK_REENTRANT':
+            return (0, types_js_1.errRetryAfterMs)('TOKEN_SESSION_LOCKED', 'This session is already being modified by a concurrent call. 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 internalError('WorkRail could not load the session data for this operation.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail cannot load session data.'));
         case 'LOCK_ACQUIRE_FAILED':
+            return internalError('WorkRail could not acquire a lock on this session.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail is having trouble with session locking — check if another process is running.'));
         case 'GATE_CALLBACK_FAILED':
-            return internalError(e.message, 'Retry; if persists, treat as invariant violation.');
+            return internalError('WorkRail encountered an error while processing this session operation. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error.'));
         default:
             const _exhaustive = e;
-            return internalError('Unknown gate error', 'Treat as invariant violation.');
+            return internalError('WorkRail encountered an unexpected session error. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error.'));
     }
 }
-function snapshotStoreErrorToToolError(e, suggestion) {
-    return internalError(`Snapshot store error: ${e.message}`, suggestion);
+function snapshotStoreErrorToToolError(_e, _suggestion) {
+    return internalError('WorkRail could not access its execution state data. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal storage error.'));
 }
-function pinnedWorkflowStoreErrorToToolError(e, suggestion) {
-    return internalError(`Pinned workflow store error: ${e.message}`, suggestion);
+function pinnedWorkflowStoreErrorToToolError(_e, _suggestion) {
+    return internalError('WorkRail could not access the stored workflow definition. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal storage error.'));
 }
 function mapInternalErrorToToolError(e) {
     switch (e.kind) {
         case 'missing_node_or_run':
-            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', 'No durable run/node state was found for this stateToken. Advancement cannot be recorded.', { suggestion: 'Use a stateToken returned by WorkRail for an existing run/node.' });
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', 'The stateToken you provided does not match any active workflow session. It may be expired or from a different session.', { suggestion: 'Use the stateToken returned by the most recent start_workflow or continue_workflow call.' });
         case 'workflow_hash_mismatch':
-            return (0, types_js_1.errNotRetryable)('TOKEN_WORKFLOW_HASH_MISMATCH', 'workflowHash mismatch for this node.', { suggestion: 'Use the stateToken returned by WorkRail for this node.' });
+            return (0, types_js_1.errNotRetryable)('TOKEN_WORKFLOW_HASH_MISMATCH', 'The stateToken refers to a different version of this workflow than what is currently stored.', { suggestion: 'Call start_workflow to create a new session with the current workflow version.' });
         case 'token_scope_mismatch':
-            return (0, types_js_1.errNotRetryable)('TOKEN_SCOPE_MISMATCH', normalizeTokenErrorMessage(e.message), { suggestion: 'Use the correct token type for this operation.' });
+            return (0, types_js_1.errNotRetryable)('TOKEN_SCOPE_MISMATCH', 'The stateToken and ackToken do not belong to the same session or node. Tokens must come from the same WorkRail response.', { suggestion: 'Use the stateToken and ackToken from the same continue_workflow or start_workflow response. Do not mix tokens from different calls.' });
         case 'missing_snapshot':
+            return internalError('WorkRail\'s execution state is incomplete — a required snapshot is missing. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call, or call start_workflow to create a new session.', 'WorkRail has incomplete execution state.'));
         case 'no_pending_step':
-            return internalError('Incomplete execution state.', 'Retry; if this persists, treat as invariant violation.');
+            return internalError('There is no pending step to advance. The workflow may already be complete.', 'Call continue_workflow with only a stateToken (no ackToken) to check the current workflow state.');
         case 'invariant_violation':
-            return internalError(normalizeTokenErrorMessage(e.message), 'Treat as invariant violation.');
+            return internalError('WorkRail encountered an unexpected error during workflow advancement. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error during workflow advancement.'));
         case 'advance_apply_failed':
+            return internalError('WorkRail could not record the workflow advancement. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail could not record the advancement.'));
         case 'advance_next_failed':
-            return internalError(normalizeTokenErrorMessage(e.message), 'Retry; if this persists, treat as invariant violation.');
+            return internalError('WorkRail could not compute the next workflow step. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail could not compute the next step.'));
         default:
             const _exhaustive = e;
-            return internalError('Unknown internal error kind', 'Treat as invariant violation.');
+            return internalError('WorkRail encountered an unexpected error. This is not caused by your input.', (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error.'));
     }
 }

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

@@ -0,0 +1,32 @@
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import { createWorkflow } from '../../../types/workflow.js';
+import { type AttemptId } from '../../../v2/durable-core/tokens/index.js';
+import { type SessionId, type RunId, type NodeId, type WorkflowHash } from '../../../v2/durable-core/ids/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { WithHealthySessionLock } from '../../../v2/durable-core/ids/with-healthy-session-lock.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 { Sha256PortV2 } from '../../../v2/ports/sha256.port.js';
+import { ResultAsync as RA } from 'neverthrow';
+import type { JsonValue } from '../../../v2/durable-core/canonical/json-types.js';
+import { type InternalError } from '../v2-error-mapping.js';
+export declare function advanceAndRecord(args: {
+    readonly truth: LoadedSessionTruthV2;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+    readonly attemptId: AttemptId;
+    readonly workflowHash: WorkflowHash;
+    readonly dedupeKey: string;
+    readonly inputContext: JsonValue | undefined;
+    readonly inputOutput: V2ContinueWorkflowInput['output'];
+    readonly lock: WithHealthySessionLock;
+    readonly pinnedWorkflow: ReturnType<typeof createWorkflow>;
+    readonly snapshotStore: import('../../../v2/ports/snapshot-store.port.js').SnapshotStorePortV2;
+    readonly sessionStore: import('../../../v2/ports/session-event-log-store.port.js').SessionEventLogAppendStorePortV2 & import('../../../v2/ports/session-event-log-store.port.js').SessionEventLogReadonlyStorePortV2;
+    readonly sha256: Sha256PortV2;
+    readonly idFactory: {
+        readonly mintNodeId: () => NodeId;
+        readonly mintEventId: () => string;
+    };
+}): RA<void, InternalError | SessionEventLogStoreError | SnapshotStoreError>;

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.advanceAndRecord = advanceAndRecord;
+const neverthrow_1 = require("neverthrow");
+const v2_advance_core_js_1 = require("../v2-advance-core.js");
+const constants_js_1 = require("../../../v2/durable-core/constants.js");
+function advanceAndRecord(args) {
+    const { truth, sessionId, runId, nodeId, attemptId, workflowHash, dedupeKey, inputContext, inputOutput, lock, pinnedWorkflow, snapshotStore, sessionStore, sha256, idFactory } = args;
+    const hasRun = truth.events.some((e) => e.kind === constants_js_1.EVENT_KIND.RUN_STARTED && e.scope?.runId === String(runId));
+    const hasNode = truth.events.some((e) => e.kind === constants_js_1.EVENT_KIND.NODE_CREATED && e.scope?.runId === String(runId) && e.scope?.nodeId === String(nodeId));
+    if (!hasRun || !hasNode) {
+        return (0, neverthrow_1.errAsync)({ kind: 'missing_node_or_run' });
+    }
+    const nodeCreated = truth.events.find((e) => e.kind === constants_js_1.EVENT_KIND.NODE_CREATED && e.scope?.nodeId === String(nodeId));
+    if (!nodeCreated) {
+        return (0, neverthrow_1.errAsync)({ kind: 'missing_node_or_run' });
+    }
+    if (String(nodeCreated.data.workflowHash) !== String(workflowHash)) {
+        return (0, neverthrow_1.errAsync)({ kind: 'workflow_hash_mismatch' });
+    }
+    return snapshotStore.getExecutionSnapshotV1(nodeCreated.data.snapshotRef).andThen((snap) => {
+        if (!snap)
+            return (0, neverthrow_1.errAsync)({ kind: 'missing_snapshot' });
+        const engineState = snap.enginePayload.engineState;
+        if (nodeCreated.data.nodeKind === 'blocked_attempt') {
+            if (engineState.kind !== 'blocked') {
+                return (0, neverthrow_1.errAsync)({ kind: 'invariant_violation', message: 'blocked_attempt node requires engineState.kind=blocked' });
+            }
+            const blocked = engineState.blocked;
+            if (blocked.kind !== 'retryable_block') {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'token_scope_mismatch',
+                    message: 'Cannot retry a terminal blocked_attempt node (blocked.kind=terminal_block).',
+                });
+            }
+            return (0, v2_advance_core_js_1.executeAdvanceCore)({
+                mode: { kind: 'retry', blockedNodeId: nodeId, blockedSnapshot: snap },
+                truth, sessionId, runId, attemptId, workflowHash, dedupeKey,
+                inputContext, inputOutput, lock, pinnedWorkflow,
+                ports: { snapshotStore, sessionStore, sha256, idFactory },
+            });
+        }
+        return (0, v2_advance_core_js_1.executeAdvanceCore)({
+            mode: { kind: 'fresh', sourceNodeId: nodeId, snapshot: snap },
+            truth, sessionId, runId, attemptId, workflowHash, dedupeKey,
+            inputContext, inputOutput, lock, pinnedWorkflow,
+            ports: { snapshotStore, sessionStore, sha256, idFactory },
+        });
+    });
+}

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

@@ -0,0 +1,29 @@
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import { V2ContinueWorkflowOutputSchema } from '../../output-schemas.js';
+import { type AttemptId } from '../../../v2/durable-core/tokens/index.js';
+import { type SessionId, type RunId, type NodeId } from '../../../v2/durable-core/ids/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { Sha256PortV2 } from '../../../v2/ports/sha256.port.js';
+import type { TokenCodecPorts } from '../../../v2/durable-core/tokens/token-codec-ports.js';
+import { ResultAsync as RA } from 'neverthrow';
+import { type ContinueWorkflowError } from '../v2-execution-helpers.js';
+import * as z from 'zod';
+export declare function handleAdvanceIntent(args: {
+    readonly input: V2ContinueWorkflowInput;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+    readonly attemptId: AttemptId;
+    readonly workflowHashRef: string;
+    readonly truth: LoadedSessionTruthV2;
+    readonly gate: import('../../../v2/usecases/execution-session-gate.js').ExecutionSessionGateV2;
+    readonly sessionStore: import('../../../v2/ports/session-event-log-store.port.js').SessionEventLogAppendStorePortV2 & import('../../../v2/ports/session-event-log-store.port.js').SessionEventLogReadonlyStorePortV2;
+    readonly snapshotStore: import('../../../v2/ports/snapshot-store.port.js').SnapshotStorePortV2;
+    readonly pinnedStore: import('../../../v2/ports/pinned-workflow-store.port.js').PinnedWorkflowStorePortV2;
+    readonly tokenCodecPorts: TokenCodecPorts;
+    readonly idFactory: {
+        readonly mintNodeId: () => NodeId;
+        readonly mintEventId: () => string;
+    };
+    readonly sha256: Sha256PortV2;
+}): RA<z.infer<typeof V2ContinueWorkflowOutputSchema>, ContinueWorkflowError>;

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

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAdvanceIntent = handleAdvanceIntent;
+const workflow_js_1 = require("../../../types/workflow.js");
+const workflow_hash_ref_js_1 = require("../../../v2/durable-core/ids/workflow-hash-ref.js");
+const neverthrow_1 = require("neverthrow");
+const workflow_source_js_1 = require("../../../types/workflow-source.js");
+const workflow_definition_js_1 = require("../../../types/workflow-definition.js");
+const v2_error_mapping_js_1 = require("../v2-error-mapping.js");
+const constants_js_1 = require("../../../v2/durable-core/constants.js");
+const replay_js_1 = require("./replay.js");
+const advance_js_1 = require("./advance.js");
+function handleAdvanceIntent(args) {
+    const { input, sessionId, runId, nodeId, attemptId, workflowHashRef, truth, gate, sessionStore, snapshotStore, pinnedStore, tokenCodecPorts, idFactory, sha256 } = args;
+    const dedupeKey = `advance_recorded:${sessionId}:${nodeId}:${attemptId}`;
+    const runStarted = truth.events.find((e) => e.kind === constants_js_1.EVENT_KIND.RUN_STARTED && e.scope.runId === String(runId));
+    if (!runStarted) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'token_unknown_node',
+            message: 'No durable run state was found for this token (missing run_started).',
+            suggestion: 'Use start_workflow to mint a new run, or use tokens returned by WorkRail for an existing run.',
+        });
+    }
+    const workflowHash = runStarted.data.workflowHash;
+    const refRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(workflowHash);
+    if (refRes.isErr()) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: refRes.error.message,
+            suggestion: 'Re-pin the workflow via start_workflow.',
+        });
+    }
+    if (String(refRes.value) !== String(workflowHashRef)) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: 'workflowHash mismatch for this run.',
+            suggestion: 'Use the stateToken returned by WorkRail for this run.',
+        });
+    }
+    const nodeCreated = truth.events.find((e) => e.kind === constants_js_1.EVENT_KIND.NODE_CREATED && e.scope.nodeId === String(nodeId) && e.scope.runId === String(runId));
+    if (!nodeCreated) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'token_unknown_node',
+            message: 'No durable node state was found for this token (missing node_created).',
+            suggestion: 'Use tokens returned by WorkRail for an existing node.',
+        });
+    }
+    const nodeRefRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(nodeCreated.data.workflowHash);
+    if (nodeRefRes.isErr()) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: nodeRefRes.error.message,
+            suggestion: 'Re-pin the workflow via start_workflow.',
+        });
+    }
+    if (String(nodeRefRes.value) !== String(workflowHashRef)) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: 'workflowHash mismatch for this node.',
+            suggestion: 'Use the stateToken returned by WorkRail for this node.',
+        });
+    }
+    const existing = truth.events.find((e) => e.kind === constants_js_1.EVENT_KIND.ADVANCE_RECORDED && e.dedupeKey === dedupeKey);
+    return pinnedStore.get(workflowHash)
+        .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
+        .andThen((compiled) => {
+        if (!compiled)
+            return (0, neverthrow_1.errAsync)({ kind: 'pinned_workflow_missing', workflowHash });
+        if (compiled.sourceKind !== 'v1_pinned')
+            return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'Pinned workflow snapshot is read-only (v1_preview) and cannot be executed.' });
+        if (!(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(compiled.definition)) {
+            return (0, neverthrow_1.errAsync)({
+                kind: 'precondition_failed',
+                message: 'Pinned workflow snapshot has an invalid workflow definition shape.',
+                suggestion: 'Re-pin the workflow via start_workflow.',
+            });
+        }
+        const pinnedWorkflow = (0, workflow_js_1.createWorkflow)(compiled.definition, (0, workflow_source_js_1.createBundledSource)());
+        if (existing) {
+            return (0, replay_js_1.replayFromRecordedAdvance)({
+                recordedEvent: existing,
+                truth,
+                sessionId,
+                runId,
+                nodeId,
+                workflowHash,
+                attemptId,
+                inputStateToken: input.stateToken,
+                inputAckToken: input.ackToken,
+                pinnedWorkflow,
+                snapshotStore,
+                sha256,
+                tokenCodecPorts,
+            });
+        }
+        return gate
+            .withHealthySessionLock(sessionId, (lock) => sessionStore.load(sessionId).andThen((truthLocked) => {
+            const existingLocked = truthLocked.events.find((e) => e.kind === constants_js_1.EVENT_KIND.ADVANCE_RECORDED && e.dedupeKey === dedupeKey);
+            if (existingLocked)
+                return (0, neverthrow_1.okAsync)({ kind: 'replay', truth: truthLocked, recordedEvent: existingLocked });
+            return (0, advance_js_1.advanceAndRecord)({
+                truth: truthLocked,
+                sessionId,
+                runId,
+                nodeId,
+                attemptId,
+                workflowHash,
+                dedupeKey,
+                inputContext: input.context,
+                inputOutput: input.output,
+                lock,
+                pinnedWorkflow,
+                snapshotStore,
+                sessionStore,
+                sha256,
+                idFactory,
+            }).andThen(() => sessionStore
+                .load(sessionId)
+                .map((truthAfter) => ({ kind: 'replay', truth: truthAfter, recordedEvent: null })));
+        }))
+            .mapErr((cause) => {
+            if ((0, v2_error_mapping_js_1.isInternalError)(cause)) {
+                return {
+                    kind: 'invariant_violation',
+                    message: `Advance failed due to internal error: ${cause.kind}`,
+                };
+            }
+            if (typeof cause === 'object' && cause !== null && 'code' in cause) {
+                const code = cause.code;
+                if (code.startsWith('SNAPSHOT_STORE_')) {
+                    return { kind: 'snapshot_load_failed', cause: cause };
+                }
+                return { kind: 'advance_execution_failed', cause: cause };
+            }
+            return {
+                kind: 'invariant_violation',
+                message: 'Advance failed with an unknown error shape.',
+            };
+        })
+            .andThen((res) => {
+            const truth2 = res.truth;
+            const recordedEvent = res.recordedEvent ??
+                truth2.events.find((e) => e.kind === constants_js_1.EVENT_KIND.ADVANCE_RECORDED && e.dedupeKey === dedupeKey);
+            if (!recordedEvent) {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'invariant_violation',
+                    message: 'Missing recorded advance outcome after successful append.',
+                });
+            }
+            return (0, replay_js_1.replayFromRecordedAdvance)({
+                recordedEvent,
+                truth: truth2,
+                sessionId,
+                runId,
+                nodeId,
+                workflowHash,
+                attemptId,
+                inputStateToken: input.stateToken,
+                inputAckToken: input.ackToken,
+                pinnedWorkflow,
+                snapshotStore,
+                sha256,
+                tokenCodecPorts,
+            });
+        });
+    });
+}

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

@@ -0,0 +1,22 @@
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import { V2ContinueWorkflowOutputSchema } from '../../output-schemas.js';
+import { type SessionId, type RunId, type NodeId } from '../../../v2/durable-core/ids/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { TokenCodecPorts } from '../../../v2/durable-core/tokens/token-codec-ports.js';
+import { ResultAsync as RA } from 'neverthrow';
+import { type ContinueWorkflowError } from '../v2-execution-helpers.js';
+import * as z from 'zod';
+export declare function handleRehydrateIntent(args: {
+    readonly input: V2ContinueWorkflowInput;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+    readonly workflowHashRef: string;
+    readonly truth: LoadedSessionTruthV2;
+    readonly tokenCodecPorts: TokenCodecPorts;
+    readonly pinnedStore: import('../../../v2/ports/pinned-workflow-store.port.js').PinnedWorkflowStorePortV2;
+    readonly snapshotStore: import('../../../v2/ports/snapshot-store.port.js').SnapshotStorePortV2;
+    readonly idFactory: {
+        readonly mintAttemptId: () => import('../../../v2/durable-core/tokens/index.js').AttemptId;
+    };
+}): RA<z.infer<typeof V2ContinueWorkflowOutputSchema>, ContinueWorkflowError>;