@exaudeus/workrail 1.4.0 → 1.5.1

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);
@@ -85,7 +86,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';
@@ -106,7 +107,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 +122,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: {

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-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,170 @@
+"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 invariant violation: ${cause.kind}`,
+                    suggestion: 'Retry; if this persists, treat as invariant violation.',
+                };
+            }
+            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 (invariant violation).',
+                suggestion: 'Retry; if this persists, treat as invariant violation.',
+            };
+        })
+            .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 (invariant violation).',
+                    suggestion: 'Retry; if this persists, treat as invariant violation.',
+                });
+            }
+            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>;

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

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleRehydrateIntent = handleRehydrateIntent;
+const output_schemas_js_1 = require("../../output-schemas.js");
+const snapshot_state_js_1 = require("../../../v2/durable-core/projections/snapshot-state.js");
+const workflow_js_1 = require("../../../types/workflow.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 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_execution_helpers_js_1 = require("../v2-execution-helpers.js");
+const prompt_renderer_js_1 = require("../../../v2/durable-core/domain/prompt-renderer.js");
+const v2_token_ops_js_1 = require("../v2-token-ops.js");
+const v2_state_conversion_js_1 = require("../v2-state-conversion.js");
+const constants_js_1 = require("../../../v2/durable-core/constants.js");
+const index_js_2 = require("./index.js");
+function handleRehydrateIntent(args) {
+    const { input, sessionId, runId, nodeId, workflowHashRef, truth, tokenCodecPorts, pinnedStore, snapshotStore, idFactory } = args;
+    const runStarted = truth.events.find((e) => e.kind === constants_js_1.EVENT_KIND.RUN_STARTED && e.scope.runId === String(runId));
+    const workflowId = runStarted?.data.workflowId;
+    if (!runStarted || typeof workflowId !== 'string' || workflowId.trim() === '') {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'token_unknown_node',
+            message: 'No durable run state was found for this stateToken (missing run_started).',
+            suggestion: 'Use start_workflow to mint a new run, or use a stateToken returned by WorkRail for an existing run.',
+        });
+    }
+    const workflowHash = runStarted.data.workflowHash;
+    const expectedRefRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(workflowHash);
+    if (expectedRefRes.isErr()) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: expectedRefRes.error.message,
+            suggestion: 'Re-pin the workflow via start_workflow.',
+        });
+    }
+    if (String(expectedRefRes.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 stateToken (missing node_created).',
+            suggestion: 'Use a stateToken returned by WorkRail for an existing node.',
+        });
+    }
+    const expectedNodeRefRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(nodeCreated.data.workflowHash);
+    if (expectedNodeRefRes.isErr()) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: expectedNodeRefRes.error.message,
+            suggestion: 'Re-pin the workflow via start_workflow.',
+        });
+    }
+    if (String(expectedNodeRefRes.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.' });
+    }
+    return snapshotStore.getExecutionSnapshotV1(nodeCreated.data.snapshotRef)
+        .mapErr((cause) => ({ kind: 'snapshot_load_failed', cause }))
+        .andThen((snapshot) => {
+        if (!snapshot) {
+            return (0, neverthrow_1.errAsync)({
+                kind: 'token_unknown_node',
+                message: 'No execution snapshot was found for this node.',
+                suggestion: 'Use a stateToken returned by WorkRail for an existing node.',
+            });
+        }
+        const engineState = snapshot.enginePayload.engineState;
+        const pending = (0, snapshot_state_js_1.derivePendingStep)(engineState);
+        const isComplete = (0, snapshot_state_js_1.deriveIsComplete)(engineState);
+        if (!pending) {
+            const preferences = (0, v2_execution_helpers_js_1.derivePreferencesOrDefault)({ truth, runId, nodeId });
+            const nextIntent = (0, v2_state_conversion_js_1.deriveNextIntent)({ rehydrateOnly: true, isComplete, pending: null });
+            return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
+                kind: 'ok',
+                stateToken: input.stateToken,
+                isComplete,
+                pending: null,
+                preferences,
+                nextIntent,
+                nextCall: (0, index_js_2.buildNextCall)({ stateToken: input.stateToken, ackToken: undefined, isComplete, pending: null }),
+            }));
+        }
+        const attemptId = (0, v2_token_ops_js_1.newAttemptId)(idFactory);
+        const ackTokenRes = (0, v2_token_ops_js_1.signTokenOrErr)({
+            payload: { tokenVersion: 1, tokenKind: 'ack', sessionId, runId, nodeId, attemptId },
+            ports: tokenCodecPorts,
+        });
+        if (ackTokenRes.isErr())
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: ackTokenRes.error });
+        const checkpointTokenRes = (0, v2_token_ops_js_1.signTokenOrErr)({
+            payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId, attemptId },
+            ports: tokenCodecPorts,
+        });
+        if (checkpointTokenRes.isErr())
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointTokenRes.error });
+        return pinnedStore.get(workflowHash)
+            .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
+            .andThen((pinned) => {
+            if (!pinned)
+                return (0, neverthrow_1.errAsync)({ kind: 'pinned_workflow_missing', workflowHash });
+            if (pinned.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)(pinned.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 wf = (0, workflow_js_1.createWorkflow)(pinned.definition, (0, workflow_source_js_1.createBundledSource)());
+            const metaRes = (0, prompt_renderer_js_1.renderPendingPrompt)({
+                workflow: wf,
+                stepId: String(pending.stepId),
+                loopPath: pending.loopPath,
+                truth,
+                runId: (0, index_js_1.asRunId)(String(runId)),
+                nodeId: (0, index_js_1.asNodeId)(String(nodeId)),
+                rehydrateOnly: true,
+            });
+            if (metaRes.isErr()) {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'invariant_violation',
+                    message: `Prompt rendering failed: ${metaRes.error.message}`,
+                    suggestion: 'Retry; if this persists, treat as invariant violation.',
+                });
+            }
+            const meta = metaRes.value;
+            const preferences = (0, v2_execution_helpers_js_1.derivePreferencesOrDefault)({ truth, runId, nodeId });
+            const nextIntent = (0, v2_state_conversion_js_1.deriveNextIntent)({ rehydrateOnly: true, isComplete, pending: meta });
+            return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
+                kind: 'ok',
+                stateToken: input.stateToken,
+                ackToken: ackTokenRes.value,
+                checkpointToken: checkpointTokenRes.value,
+                isComplete,
+                pending: { stepId: meta.stepId, title: meta.title, prompt: meta.prompt },
+                preferences,
+                nextIntent,
+                nextCall: (0, index_js_2.buildNextCall)({ stateToken: input.stateToken, ackToken: ackTokenRes.value, isComplete, pending: meta }),
+            }));
+        });
+    });
+}

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

@@ -0,0 +1,23 @@
+import type { ToolContext, ToolResult } from '../../types.js';
+import type { V2ContinueWorkflowInput, V2StartWorkflowInput } from '../../v2/tools.js';
+type NextCallTemplate = {
+    readonly tool: 'continue_workflow';
+    readonly params: {
+        readonly intent: 'advance';
+        readonly stateToken: string;
+        readonly ackToken: string;
+    };
+};
+export declare function buildNextCall(args: {
+    readonly stateToken: string;
+    readonly ackToken: string | undefined;
+    readonly isComplete: boolean;
+    readonly pending: {
+        readonly stepId: string;
+    } | null;
+    readonly retryable?: boolean;
+    readonly retryAckToken?: string;
+}): NextCallTemplate | null;
+export declare function handleV2StartWorkflow(input: V2StartWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
+export declare function handleV2ContinueWorkflow(input: V2ContinueWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
+export {};

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

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildNextCall = buildNextCall;
+exports.handleV2StartWorkflow = handleV2StartWorkflow;
+exports.handleV2ContinueWorkflow = handleV2ContinueWorkflow;
+const types_js_1 = require("../../types.js");
+const index_js_1 = require("../../../v2/durable-core/tokens/index.js");
+const index_js_2 = require("../../../v2/durable-core/ids/index.js");
+const neverthrow_1 = require("neverthrow");
+const v2_execution_helpers_js_1 = require("../v2-execution-helpers.js");
+const v2_token_ops_js_1 = require("../v2-token-ops.js");
+const v2_context_budget_js_1 = require("../v2-context-budget.js");
+const start_js_1 = require("./start.js");
+const continue_rehydrate_js_1 = require("./continue-rehydrate.js");
+const continue_advance_js_1 = require("./continue-advance.js");
+function buildNextCall(args) {
+    if (args.isComplete && !args.pending)
+        return null;
+    if (args.retryable && args.retryAckToken) {
+        return {
+            tool: 'continue_workflow',
+            params: { intent: 'advance', stateToken: args.stateToken, ackToken: args.retryAckToken },
+        };
+    }
+    if (!args.ackToken)
+        return null;
+    return {
+        tool: 'continue_workflow',
+        params: { intent: 'advance', stateToken: args.stateToken, ackToken: args.ackToken },
+    };
+}
+async function handleV2StartWorkflow(input, ctx) {
+    return (0, start_js_1.executeStartWorkflow)(input, ctx).match((payload) => (0, types_js_1.success)(payload), (e) => (0, v2_execution_helpers_js_1.mapStartWorkflowErrorToToolError)(e));
+}
+async function handleV2ContinueWorkflow(input, ctx) {
+    return executeContinueWorkflow(input, ctx).match((payload) => (0, types_js_1.success)(payload), (e) => (0, v2_execution_helpers_js_1.mapContinueWorkflowErrorToToolError)(e));
+}
+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, sha256, tokenCodecPorts, idFactory } = ctx.v2;
+    if (!sha256 || !idFactory) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: 'v2 context missing required dependencies',
+            suggestion: 'Reinitialize v2 tool context (sha256 and idFactory must be provided when v2Tools are enabled).',
+        });
+    }
+    if (!tokenCodecPorts) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: 'v2 context missing tokenCodecPorts dependency',
+            suggestion: 'Reinitialize v2 tool context (tokenCodecPorts must be provided when v2Tools are enabled).',
+        });
+    }
+    const stateRes = (0, v2_token_ops_js_1.parseStateTokenOrFail)(input.stateToken, tokenCodecPorts);
+    if (!stateRes.ok)
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: stateRes.failure });
+    const state = stateRes.token;
+    const ctxCheck = (0, v2_context_budget_js_1.checkContextBudget)({ tool: 'continue_workflow', context: input.context });
+    if (!ctxCheck.ok)
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ctxCheck.error });
+    const sessionId = (0, index_js_2.asSessionId)(state.payload.sessionId);
+    const runId = (0, index_js_2.asRunId)(state.payload.runId);
+    const nodeId = (0, index_js_2.asNodeId)(state.payload.nodeId);
+    const workflowHashRef = state.payload.workflowHashRef;
+    if (input.intent === 'rehydrate') {
+        return sessionStore.load(sessionId)
+            .mapErr((cause) => ({ kind: 'session_load_failed', cause }))
+            .andThen((truth) => (0, continue_rehydrate_js_1.handleRehydrateIntent)({
+            input,
+            sessionId,
+            runId,
+            nodeId,
+            workflowHashRef,
+            truth,
+            tokenCodecPorts,
+            pinnedStore,
+            snapshotStore,
+            idFactory,
+        }));
+    }
+    if (!input.ackToken) {
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: (0, types_js_1.error)('VALIDATION_ERROR', 'ackToken is required for advance intent') });
+    }
+    const ackRes = (0, v2_token_ops_js_1.parseAckTokenOrFail)(input.ackToken, tokenCodecPorts);
+    if (!ackRes.ok)
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ackRes.failure });
+    const ack = ackRes.token;
+    const scopeRes = (0, index_js_1.assertTokenScopeMatchesStateBinary)(state, ack);
+    if (scopeRes.isErr())
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: (0, v2_execution_helpers_js_1.mapTokenDecodeErrorToToolError)(scopeRes.error) });
+    const attemptId = (0, index_js_1.asAttemptId)(ack.payload.attemptId);
+    return sessionStore.load(sessionId)
+        .mapErr((cause) => ({ kind: 'session_load_failed', cause }))
+        .andThen((truth) => (0, continue_advance_js_1.handleAdvanceIntent)({
+        input,
+        sessionId,
+        runId,
+        nodeId,
+        attemptId,
+        workflowHashRef,
+        truth,
+        gate,
+        sessionStore,
+        snapshotStore,
+        pinnedStore,
+        tokenCodecPorts,
+        idFactory,
+        sha256,
+    }));
+}