@exaudeus/workrail 1.2.0 → 1.4.0

package/dist/manifest.json

@@ -553,6 +553,14 @@
       "sha256": "d22e4b954022e82bf3017b5fca7101c0499f76fdad1efb86131f189bc9c4602b",
       "bytes": 22251
     },
+    "mcp/handlers/v2-checkpoint.d.ts": {
+      "sha256": "97e1d3ddcb5f92137312c6516b6c4ff2f18dec7a7a83657db30198aedd67e7e1",
+      "bytes": 259
+    },
+    "mcp/handlers/v2-checkpoint.js": {
+      "sha256": "20a8d8524bb64a641d4c82ecabadf70ba84c599636808ba4fe19d594d1f04b8c",
+      "bytes": 9123
+    },
     "mcp/handlers/v2-context-budget.d.ts": {
       "sha256": "cbad1741a183d52c9cbe558be2e09f776843d1f3ec8cd28d6d0d230668e4298c",
       "bytes": 674
@@ -582,8 +590,8 @@
       "bytes": 944
     },
     "mcp/handlers/v2-execution.js": {
-      "sha256": "dccf1b219b0962743cd53ef5c1fca00d356161df388b42524ddf7380ec1c371b",
-      "bytes": 48280
+      "sha256": "561e34c59e1640dd419644b1abc750b2750e8a99bce000abef593e5047badc23",
+      "bytes": 50334
     },
     "mcp/handlers/v2-state-conversion.d.ts": {
       "sha256": "e8d70753ed1b83d9396864ef50929ba32cb008bda24bcb2ce624df24adb72570",
@@ -594,12 +602,12 @@
       "bytes": 5216
     },
     "mcp/handlers/v2-token-ops.d.ts": {
-      "sha256": "64b143576c2741497f393513bb2d04010f3754c8d066c47cbff5819d072f8eea",
-      "bytes": 1504
+      "sha256": "2101c6f44398909b045adf0904dcec10448bb0fd69d85eab352488ee752959e0",
+      "bytes": 1853
     },
     "mcp/handlers/v2-token-ops.js": {
-      "sha256": "27d5b08e3ce3ba984a8258cfbbede7e525039cbcde55a411c74f3c0fd60f91bf",
-      "bytes": 2851
+      "sha256": "c786c2a8de7240989b2368762552373a2c3d397edd47122144c51e31a22d6203",
+      "bytes": 3817
     },
     "mcp/handlers/v2-workflow.d.ts": {
       "sha256": "9fbd4d44854e2060c54982b21e72c608970bb2bd107bb15a8388b26c6b492e55",
@@ -626,12 +634,12 @@
       "bytes": 7535
     },
     "mcp/output-schemas.d.ts": {
-      "sha256": "2e26bc2e2f457dcd2325bbab67a19ce4ed81896eb87b0981094f68c76937f08c",
-      "bytes": 42678
+      "sha256": "ae6188036f2e379c9f5498f7256f658e5bdd5301024e7bd863d02ca3dfad9f41",
+      "bytes": 43607
     },
     "mcp/output-schemas.js": {
-      "sha256": "11fbd471a6b56aa8df3c3d002e4d660da3d034b4fbab82871d810c1d25152283",
-      "bytes": 10346
+      "sha256": "3ad98beeb67c03622651e100e8a4c02374318e1967fa062335d6dda80664ad8e",
+      "bytes": 10889
     },
     "mcp/server.d.ts": {
       "sha256": "bec49b8d07e189a53db7100d2f0e1e84ffe03150f04e1b06908ee3282982b4a2",
@@ -654,8 +662,8 @@
       "bytes": 132
     },
     "mcp/tool-descriptions.js": {
-      "sha256": "4a713e4cad3b59077c42d95c78b5a1b68b93830def6f0d39db4ed79562c8a6e3",
-      "bytes": 14568
+      "sha256": "e5f98cd0791507b87b3d0883155e74aaf4a9f03fd17b795195f21835962bd4cf",
+      "bytes": 15369
     },
     "mcp/tool-factory.d.ts": {
       "sha256": "0fe3c6b863b2d7aef0c3d659ff54f3a9ee8a0a3c2005b6565d2f8ad517bc7211",
@@ -670,8 +678,8 @@
       "bytes": 5976
     },
     "mcp/tools.js": {
-      "sha256": "0af59932b32bad5ebc9cbc925279d325350c91b43085561d0d218035250b641a",
-      "bytes": 8020
+      "sha256": "813dad3f02046e200d99c2228cbf53ad9de58a79e609356730c93b75903d4c01",
+      "bytes": 8198
     },
     "mcp/types.d.ts": {
       "sha256": "9e29d5ae4ec1f80640f073f0d58b603158fe5b22897f44c1c77ed4abaef374f9",
@@ -682,16 +690,16 @@
       "bytes": 1253
     },
     "mcp/types/tool-description-types.d.ts": {
-      "sha256": "7d0fb489a829f7d21ed0d3fe9cef221ff71b63619054070287bc790bf5142a28",
-      "bytes": 782
+      "sha256": "41e31c87b6d5b2e0fb4b66b1e8fac3f74c9769c3ded8a26577804aeccb79ae7b",
+      "bytes": 805
     },
     "mcp/types/tool-description-types.js": {
-      "sha256": "a1c1fdd901bf6a074d9a48cef09e0020c59d9838bfb8754ed2aaf9c23191a533",
-      "bytes": 750
+      "sha256": "689e74ea09e25e51de6020e42de42c37965e55980635d8739fc9ad19ba341955",
+      "bytes": 777
     },
     "mcp/types/workflow-tool-edition.d.ts": {
-      "sha256": "7407d318a9f0cc7d6dc81d7cb003e474b3a31a52bf3e600e07ee94f556e2555a",
-      "bytes": 1470
+      "sha256": "e7228be685155777e3035963056edd503e6660985fe7b5f17032402ca6582c8c",
+      "bytes": 1494
     },
     "mcp/types/workflow-tool-edition.js": {
       "sha256": "2dfd26acd3da2c249b728e7fc48c7eab3dc675f786e7689dbdeec53c25589369",
@@ -710,16 +718,16 @@
       "bytes": 408
     },
     "mcp/v2/tool-registry.js": {
-      "sha256": "8c94984fed94f049daeb01559a2490b7db6fedac2544b3e7e50a60b8c7dfa561",
-      "bytes": 2121
+      "sha256": "719429102bc33c9e5bcd7cf38b0242ecc038484de4159811fbe9b0efa2ebc460",
+      "bytes": 2623
     },
     "mcp/v2/tools.d.ts": {
-      "sha256": "a262c0c17ff9474f017ac1e83d4458c773791604ec4f344f777dcdbefff9318b",
-      "bytes": 3263
+      "sha256": "8fba15da4a60a46ed803046f9b61ea0b8947967880563562473d8a87de68d27c",
+      "bytes": 3600
     },
     "mcp/v2/tools.js": {
-      "sha256": "00c6710f31a9cb42215a1427f48b3e22a1065996dfdaaaf4ae2389f3c23e9aa5",
-      "bytes": 5221
+      "sha256": "93f33152aebe0cbeb92daa727a3dc43ccb3f4cc1001e7564fdd7b31ee78b2475",
+      "bytes": 5743
     },
     "mcp/validation/bounded-json.d.ts": {
       "sha256": "82203ac6123d5c6989606c3b5405aaea99ab829c8958835f9ae3ba45b8bc8fd5",
@@ -1081,6 +1089,22 @@
       "sha256": "f3c86be68aaa045c57c942459031a72df2b2d514e32a57905c1a57f8374e947f",
       "bytes": 1718
     },
+    "v2/durable-core/domain/bundle-builder.d.ts": {
+      "sha256": "4038983872901590c2aaaa6a27ad2af2f381e2816627f01f8d4276435c8c8a87",
+      "bytes": 1221
+    },
+    "v2/durable-core/domain/bundle-builder.js": {
+      "sha256": "f5422dda0c2a6591d7adc6460be49eb3967298658b51ebf0afd4f041a5395305",
+      "bytes": 3468
+    },
+    "v2/durable-core/domain/bundle-validator.d.ts": {
+      "sha256": "549df7b80ab5c2adcdb7c14e2ae7c668ca3531dfd53aab32bdd364180ef4cecd",
+      "bytes": 334
+    },
+    "v2/durable-core/domain/bundle-validator.js": {
+      "sha256": "b68d6fbbbe5bbb207d566118f9d7080ce39f51ba3eb8568a588861ef5639341c",
+      "bytes": 5925
+    },
     "v2/durable-core/domain/context-merge.d.ts": {
       "sha256": "e3068d49237d2ae351cf88c6829bf612dc7ced6f726b618e7f8aeb7462d34256",
       "bytes": 381
@@ -1840,6 +1864,22 @@
     "v2/usecases/execution-session-gate.js": {
       "sha256": "41a25f3046ed474c6c6223655ca1c21d0666aea171c024f51b85071619abfa52",
       "bytes": 7635
+    },
+    "v2/usecases/export-session.d.ts": {
+      "sha256": "037c6efb463c121feb41eff43d3b035e8443a12d25fcffb5387453ac5a49ae44",
+      "bytes": 2049
+    },
+    "v2/usecases/export-session.js": {
+      "sha256": "a91125866d50fe0a00bc8ef7d1a29bd43958b8e4eaff2e73a8247384e2d113db",
+      "bytes": 4092
+    },
+    "v2/usecases/import-session.d.ts": {
+      "sha256": "30c470707f5370f2b90d786f1d959a0a01bc4fecf3296a523a49518c626f99a8",
+      "bytes": 1514
+    },
+    "v2/usecases/import-session.js": {
+      "sha256": "9b9c8922cc2e6d6904f564c35ff0e402a2e755187f36ee7e54e76826f51bed5c",
+      "bytes": 2788
     }
   }
 }

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

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

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

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleV2CheckpointWorkflow = handleV2CheckpointWorkflow;
+const neverthrow_1 = require("neverthrow");
+const types_js_1 = require("../types.js");
+const output_schemas_js_1 = require("../output-schemas.js");
+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");
+function findNodeCreated(events, nodeId) {
+    return events.find((e) => e.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);
+    if (wfRefRes.isErr()) {
+        return { ok: false, error: { kind: 'precondition_failed', message: 'Cannot derive workflowHashRef for stateToken.' } };
+    }
+    const stateTokenRes = (0, v2_token_ops_js_1.signTokenOrErr)({
+        payload: { tokenVersion: 1, tokenKind: 'state', sessionId, runId, nodeId, workflowHashRef: wfRefRes.value },
+        ports: tokenCodecPorts,
+    });
+    if (stateTokenRes.isErr()) {
+        return { ok: false, error: { kind: 'token_signing_failed', cause: stateTokenRes.error } };
+    }
+    return { ok: true, value: stateTokenRes.value };
+}
+function validateEvents(rawEvents) {
+    const validated = [];
+    for (const raw of rawEvents) {
+        const parsed = index_js_2.DomainEventV1Schema.safeParse(raw);
+        if (!parsed.success) {
+            return { issues: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ') };
+        }
+        validated.push(parsed.data);
+    }
+    return validated;
+}
+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));
+}
+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 });
+    }
+    const token = tokenRes.token;
+    const sessionId = (0, index_js_1.asSessionId)(String(token.payload.sessionId));
+    const runId = (0, index_js_1.asRunId)(String(token.payload.runId));
+    const nodeId = (0, index_js_1.asNodeId)(String(token.payload.nodeId));
+    const attemptId = (0, index_js_1.asAttemptId)(String(token.payload.attemptId));
+    const dedupeKey = `checkpoint:${String(sessionId)}:${String(runId)}:${String(nodeId)}:${String(attemptId)}`;
+    return gate.withHealthySessionLock(sessionId, (lock) => {
+        return sessionStore.load(sessionId)
+            .mapErr((cause) => ({ kind: 'store_failed', cause }))
+            .andThen((truth) => {
+            const originalNode = findNodeCreated(truth.events, nodeId);
+            if (!originalNode) {
+                return (0, neverthrow_1.errAsync)({ kind: 'missing_node_or_run' });
+            }
+            const alreadyRecorded = truth.events.some((e) => e.dedupeKey === dedupeKey);
+            if (alreadyRecorded) {
+                return replayCheckpoint(truth.events, dedupeKey, originalNode, sessionId, runId, nodeId, tokenCodecPorts);
+            }
+            return writeCheckpoint(truth, dedupeKey, originalNode, sessionId, runId, nodeId, idFactory.mintNodeId(), () => idFactory.mintEventId(), lock, sessionStore, tokenCodecPorts);
+        });
+    }).mapErr((gateErr) => {
+        if (isGateError(gateErr)) {
+            return { kind: 'gate_failed', cause: gateErr };
+        }
+        return gateErr;
+    });
+}
+function replayCheckpoint(events, dedupeKey, originalNode, sessionId, runId, nodeId, tokenCodecPorts) {
+    const existingCheckpointNode = events.find((e) => e.kind === 'node_created' && e.dedupeKey === `checkpoint_node:${dedupeKey}`);
+    const checkpointNodeId = existingCheckpointNode
+        ? String(existingCheckpointNode.scope?.nodeId ?? 'unknown')
+        : 'unknown';
+    const tokenResult = mintStateTokenForNode(originalNode, sessionId, runId, nodeId, tokenCodecPorts);
+    if (!tokenResult.ok)
+        return (0, neverthrow_1.errAsync)(tokenResult.error);
+    return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2CheckpointWorkflowOutputSchema.parse({
+        checkpointNodeId,
+        stateToken: tokenResult.value,
+    }));
+}
+function writeCheckpoint(truth, dedupeKey, originalNode, sessionId, runId, nodeId, checkpointNodeId, mintEventId, lock, sessionStore, tokenCodecPorts) {
+    const nodeCreatedEventId = mintEventId();
+    const edgeCreatedEventId = mintEventId();
+    const rawEvents = [
+        {
+            v: 1,
+            eventId: nodeCreatedEventId,
+            eventIndex: truth.events.length,
+            sessionId: String(sessionId),
+            kind: 'node_created',
+            dedupeKey: `checkpoint_node:${dedupeKey}`,
+            scope: { runId: String(runId), nodeId: String(checkpointNodeId) },
+            data: {
+                nodeKind: 'checkpoint',
+                parentNodeId: String(nodeId),
+                workflowHash: originalNode.data.workflowHash,
+                snapshotRef: originalNode.data.snapshotRef,
+            },
+        },
+        {
+            v: 1,
+            eventId: edgeCreatedEventId,
+            eventIndex: truth.events.length + 1,
+            sessionId: String(sessionId),
+            kind: 'edge_created',
+            dedupeKey,
+            scope: { runId: String(runId) },
+            data: {
+                edgeKind: 'checkpoint',
+                fromNodeId: String(nodeId),
+                toNodeId: String(checkpointNodeId),
+                cause: {
+                    kind: 'checkpoint_created',
+                    eventId: String(nodeCreatedEventId),
+                },
+            },
+        },
+    ];
+    const validated = validateEvents(rawEvents);
+    if ('issues' in validated) {
+        return (0, neverthrow_1.errAsync)({ kind: 'event_schema_invalid', issues: validated.issues });
+    }
+    const snapshotPins = [{
+            snapshotRef: originalNode.data.snapshotRef,
+            eventIndex: truth.events.length,
+            createdByEventId: nodeCreatedEventId,
+        }];
+    return sessionStore.append(lock, { events: validated, snapshotPins })
+        .mapErr((cause) => ({ kind: 'store_failed', cause }))
+        .andThen(() => {
+        const tokenResult = mintStateTokenForNode(originalNode, sessionId, runId, nodeId, tokenCodecPorts);
+        if (!tokenResult.ok)
+            return (0, neverthrow_1.errAsync)(tokenResult.error);
+        return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2CheckpointWorkflowOutputSchema.parse({
+            checkpointNodeId: String(checkpointNodeId),
+            stateToken: tokenResult.value,
+        }));
+    });
+}
+function mapCheckpointErrorToToolError(e) {
+    switch (e.kind) {
+        case 'precondition_failed':
+            return (0, types_js_1.errNotRetryable)('PRECONDITION_FAILED', e.message);
+        case 'token_signing_failed':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'Failed to sign token.');
+        case 'validation_failed':
+            return e.failure;
+        case 'missing_node_or_run':
+            return (0, types_js_1.errNotRetryable)('TOKEN_UNKNOWN_NODE', 'No durable node state found for this checkpointToken. Use a checkpointToken returned by WorkRail.');
+        case 'event_schema_invalid':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Checkpoint events failed schema validation: ${e.issues}`);
+        case 'gate_failed': {
+            const code = e.cause.code;
+            if (code === 'SESSION_LOCKED' || code === 'SESSION_LOCK_REENTRANT') {
+                return (0, types_js_1.errNotRetryable)('TOKEN_SESSION_LOCKED', `Session is locked: ${code}`);
+            }
+            if (code === 'SESSION_NOT_HEALTHY') {
+                return (0, types_js_1.errNotRetryable)('SESSION_NOT_HEALTHY', 'Session is not healthy.');
+            }
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Session gate error: ${code}`);
+        }
+        case 'store_failed':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Session store error: ${e.cause.code}`);
+    }
+}

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

@@ -70,10 +70,17 @@ function replayFromRecordedAdvance(args) {
                 : null;
             const preferences = (0, v2_state_conversion_js_1.derivePreferencesForNode)({ truth, runId, nodeId });
             const nextIntent = (0, v2_state_conversion_js_1.deriveNextIntent)({ rehydrateOnly: false, isComplete: isCompleteNow, pending: meta });
+            const replayCheckpointTokenRes = pendingNow
+                ? (0, v2_token_ops_js_1.signTokenOrErr)({
+                    payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId, attemptId },
+                    ports: tokenCodecPorts,
+                })
+                : (0, neverthrow_1.ok)(undefined);
             return output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
                 kind: 'blocked',
                 stateToken: inputStateToken,
                 ackToken: inputAckToken,
+                checkpointToken: replayCheckpointTokenRes.isOk() ? replayCheckpointTokenRes.value : undefined,
                 isComplete: isCompleteNow,
                 pending: meta ? { stepId: meta.stepId, title: meta.title, prompt: meta.prompt } : null,
                 preferences,
@@ -119,6 +126,15 @@ function replayFromRecordedAdvance(args) {
         if (nextAckTokenRes.isErr()) {
             return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: nextAckTokenRes.error });
         }
+        const nextCheckpointTokenRes = pending
+            ? (0, v2_token_ops_js_1.signTokenOrErr)({
+                payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId: toNodeIdBranded, attemptId: nextAttemptId },
+                ports: tokenCodecPorts,
+            })
+            : (0, neverthrow_1.ok)(undefined);
+        if (nextCheckpointTokenRes.isErr()) {
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: nextCheckpointTokenRes.error });
+        }
         const wfRefRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(workflowHash);
         if (wfRefRes.isErr()) {
             return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: wfRefRes.error.message, suggestion: 'Ensure workflowHash is a valid sha256 digest.' });
@@ -173,6 +189,7 @@ function replayFromRecordedAdvance(args) {
                 kind: 'blocked',
                 stateToken: nextStateTokenRes.value,
                 ackToken: pending ? nextAckTokenRes.value : undefined,
+                checkpointToken: pending ? nextCheckpointTokenRes.value : undefined,
                 isComplete,
                 pending: meta ? { stepId: meta.stepId, title: meta.title, prompt: meta.prompt } : null,
                 preferences,
@@ -206,6 +223,7 @@ function replayFromRecordedAdvance(args) {
             kind: 'ok',
             stateToken: nextStateTokenRes.value,
             ackToken: pending ? nextAckTokenRes.value : undefined,
+            checkpointToken: pending ? nextCheckpointTokenRes.value : undefined,
             isComplete,
             pending: pending ? { stepId: meta.stepId, title: meta.title, prompt: meta.prompt } : null,
             preferences,
@@ -508,6 +526,12 @@ function executeStartWorkflow(input, ctx) {
         const ackToken = (0, v2_token_ops_js_1.signTokenOrErr)({ payload: ackPayload, ports: tokenCodecPorts });
         if (ackToken.isErr())
             return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: ackToken.error });
+        const checkpointToken = (0, v2_token_ops_js_1.signTokenOrErr)({
+            payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId, attemptId },
+            ports: tokenCodecPorts,
+        });
+        if (checkpointToken.isErr())
+            return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointToken.error });
         const metaRes = (0, prompt_renderer_js_1.renderPendingPrompt)({
             workflow: pinnedWorkflow,
             stepId: firstStep.id,
@@ -529,6 +553,7 @@ function executeStartWorkflow(input, ctx) {
         return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2StartWorkflowOutputSchema.parse({
             stateToken: stateToken.value,
             ackToken: ackToken.value,
+            checkpointToken: checkpointToken.value,
             isComplete: false,
             pending,
             preferences,
@@ -647,6 +672,12 @@ function executeContinueWorkflow(input, ctx) {
                 });
                 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) => {
@@ -685,6 +716,7 @@ function executeContinueWorkflow(input, ctx) {
                         kind: 'ok',
                         stateToken: input.stateToken,
                         ackToken: ackTokenRes.value,
+                        checkpointToken: checkpointTokenRes.value,
                         isComplete,
                         pending: { stepId: meta.stepId, title: meta.title, prompt: meta.prompt },
                         preferences,

package/dist/mcp/handlers/v2-token-ops.d.ts

@@ -9,6 +9,9 @@ export type StateTokenInput = ParsedTokenV1Binary & {
 export type AckTokenInput = ParsedTokenV1Binary & {
     readonly payload: import('../../v2/durable-core/tokens/payloads.js').AckTokenPayloadV1;
 };
+export type CheckpointTokenInput = ParsedTokenV1Binary & {
+    readonly payload: import('../../v2/durable-core/tokens/payloads.js').CheckpointTokenPayloadV1;
+};
 export declare function parseStateTokenOrFail(raw: string, ports: TokenCodecPorts): {
     ok: true;
     token: StateTokenInput;
@@ -23,6 +26,13 @@ export declare function parseAckTokenOrFail(raw: string, ports: TokenCodecPorts)
     ok: false;
     failure: ToolFailure;
 };
+export declare function parseCheckpointTokenOrFail(raw: string, ports: TokenCodecPorts): {
+    ok: true;
+    token: CheckpointTokenInput;
+} | {
+    ok: false;
+    failure: ToolFailure;
+};
 export declare function newAttemptId(idFactory: {
     readonly mintAttemptId: () => AttemptId;
 }): AttemptId;

package/dist/mcp/handlers/v2-token-ops.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseStateTokenOrFail = parseStateTokenOrFail;
 exports.parseAckTokenOrFail = parseAckTokenOrFail;
+exports.parseCheckpointTokenOrFail = parseCheckpointTokenOrFail;
 exports.newAttemptId = newAttemptId;
 exports.attemptIdForNextNode = attemptIdForNextNode;
 exports.signTokenOrErr = signTokenOrErr;
@@ -48,6 +49,25 @@ function parseAckTokenOrFail(raw, ports) {
     }
     return { ok: true, token: parsedRes.value };
 }
+function parseCheckpointTokenOrFail(raw, ports) {
+    const parsedRes = (0, index_js_1.parseTokenV1Binary)(raw, ports);
+    if (parsedRes.isErr()) {
+        return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenDecodeErrorToToolError)(parsedRes.error) };
+    }
+    const verified = (0, index_js_1.verifyTokenSignatureV1Binary)(parsedRes.value, ports);
+    if (verified.isErr()) {
+        return { ok: false, failure: (0, v2_execution_helpers_js_1.mapTokenVerifyErrorToToolError)(verified.error) };
+    }
+    if (parsedRes.value.payload.tokenKind !== 'checkpoint') {
+        return {
+            ok: false,
+            failure: (0, types_js_1.errNotRetryable)('TOKEN_INVALID_FORMAT', 'Expected a checkpoint token (chk1...).', {
+                suggestion: 'Use the checkpointToken returned by WorkRail.',
+            }),
+        };
+    }
+    return { ok: true, token: parsedRes.value };
+}
 function newAttemptId(idFactory) {
     return idFactory.mintAttemptId();
 }

package/dist/mcp/output-schemas.d.ts

@@ -462,6 +462,7 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
     kind: z.ZodLiteral<"ok">;
     stateToken: z.ZodString;
     ackToken: z.ZodOptional<z.ZodString>;
+    checkpointToken: z.ZodOptional<z.ZodString>;
     isComplete: z.ZodBoolean;
     pending: z.ZodNullable<z.ZodObject<{
         stepId: z.ZodString;
@@ -540,6 +541,7 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
         tool: "continue_workflow";
     } | null;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
 }, {
     kind: "ok";
     pending: {
@@ -563,10 +565,12 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
         tool: "continue_workflow";
     } | null;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"blocked">;
     stateToken: z.ZodString;
     ackToken: z.ZodOptional<z.ZodString>;
+    checkpointToken: z.ZodOptional<z.ZodString>;
     isComplete: z.ZodBoolean;
     pending: z.ZodNullable<z.ZodObject<{
         stepId: z.ZodString;
@@ -855,6 +859,7 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
         suggestions: string[];
     } | undefined;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
     retryable?: boolean | undefined;
     retryAckToken?: string | undefined;
 }, {
@@ -906,6 +911,7 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
         suggestions: string[];
     } | undefined;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
     retryable?: boolean | undefined;
     retryAckToken?: string | undefined;
 }>]>, {
@@ -931,6 +937,7 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
         tool: "continue_workflow";
     } | null;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
 } | {
     kind: "blocked";
     blockers: {
@@ -980,6 +987,7 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
         suggestions: string[];
     } | undefined;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
     retryable?: boolean | undefined;
     retryAckToken?: string | undefined;
 }, {
@@ -1005,6 +1013,7 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
         tool: "continue_workflow";
     } | null;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
 } | {
     kind: "blocked";
     blockers: {
@@ -1054,12 +1063,24 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
         suggestions: string[];
     } | undefined;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
     retryable?: boolean | undefined;
     retryAckToken?: string | undefined;
 }>;
+export declare const V2CheckpointWorkflowOutputSchema: z.ZodObject<{
+    checkpointNodeId: z.ZodString;
+    stateToken: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    stateToken: string;
+    checkpointNodeId: string;
+}, {
+    stateToken: string;
+    checkpointNodeId: string;
+}>;
 export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
     stateToken: z.ZodString;
     ackToken: z.ZodOptional<z.ZodString>;
+    checkpointToken: z.ZodOptional<z.ZodString>;
     isComplete: z.ZodBoolean;
     pending: z.ZodNullable<z.ZodObject<{
         stepId: z.ZodString;
@@ -1137,6 +1158,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         tool: "continue_workflow";
     } | null;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
 }, {
     pending: {
         title: string;
@@ -1159,6 +1181,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         tool: "continue_workflow";
     } | null;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
 }>, {
     pending: {
         title: string;
@@ -1181,6 +1204,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         tool: "continue_workflow";
     } | null;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
 }, {
     pending: {
         title: string;
@@ -1203,6 +1227,7 @@ export declare const V2StartWorkflowOutputSchema: z.ZodEffects<z.ZodObject<{
         tool: "continue_workflow";
     } | null;
     ackToken?: string | undefined;
+    checkpointToken?: string | undefined;
 }>;
 export declare const CreateSessionOutputSchema: z.ZodObject<{
     sessionId: z.ZodString;