@exaudeus/workrail 1.3.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",

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;

package/dist/mcp/output-schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2ContinueWorkflowOutputSchema = exports.V2BlockerReportSchema = exports.V2NextCallSchema = exports.V2NextIntentSchema = exports.V2PreferencesSchema = exports.V2PendingStepSchema = exports.V2WorkflowInspectOutputSchema = exports.V2WorkflowListOutputSchema = exports.V2WorkflowListItemSchema = exports.WorkflowGetSchemaOutputSchema = exports.WorkflowValidateJsonOutputSchema = exports.WorkflowNextOutputSchema = exports.WorkflowGetOutputSchema = exports.WorkflowListOutputSchema = exports.WorkflowSummarySchema = exports.JsonValueSchema = void 0;
+exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2CheckpointWorkflowOutputSchema = exports.V2ContinueWorkflowOutputSchema = exports.V2BlockerReportSchema = exports.V2NextCallSchema = exports.V2NextIntentSchema = exports.V2PreferencesSchema = exports.V2PendingStepSchema = exports.V2WorkflowInspectOutputSchema = exports.V2WorkflowListOutputSchema = exports.V2WorkflowListItemSchema = exports.WorkflowGetSchemaOutputSchema = exports.WorkflowValidateJsonOutputSchema = exports.WorkflowNextOutputSchema = exports.WorkflowGetOutputSchema = exports.WorkflowListOutputSchema = exports.WorkflowSummarySchema = exports.JsonValueSchema = void 0;
 const zod_1 = require("zod");
 const state_js_1 = require("../domain/execution/state.js");
 const JsonPrimitiveSchema = zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.null()]);
@@ -168,10 +168,12 @@ exports.V2BlockerReportSchema = zod_1.z
         }
     }
 });
+const checkpointTokenSchema = zod_1.z.string().regex(/^chk1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid checkpointToken format').optional();
 const V2ContinueWorkflowOkSchema = zod_1.z.object({
     kind: zod_1.z.literal('ok'),
     stateToken: zod_1.z.string().regex(/^st1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid stateToken format'),
     ackToken: zod_1.z.string().regex(/^ack1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid ackToken format').optional(),
+    checkpointToken: checkpointTokenSchema,
     isComplete: zod_1.z.boolean(),
     pending: exports.V2PendingStepSchema.nullable(),
     preferences: exports.V2PreferencesSchema,
@@ -182,6 +184,7 @@ const V2ContinueWorkflowBlockedSchema = zod_1.z.object({
     kind: zod_1.z.literal('blocked'),
     stateToken: zod_1.z.string().regex(/^st1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid stateToken format'),
     ackToken: zod_1.z.string().regex(/^ack1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid ackToken format').optional(),
+    checkpointToken: checkpointTokenSchema,
     isComplete: zod_1.z.boolean(),
     pending: exports.V2PendingStepSchema.nullable(),
     preferences: exports.V2PreferencesSchema,
@@ -201,9 +204,14 @@ exports.V2ContinueWorkflowOutputSchema = zod_1.z.discriminatedUnion('kind', [
     V2ContinueWorkflowOkSchema,
     V2ContinueWorkflowBlockedSchema,
 ]).refine((data) => (data.pending ? data.ackToken != null : true), { message: 'ackToken is required when a pending step exists' });
+exports.V2CheckpointWorkflowOutputSchema = zod_1.z.object({
+    checkpointNodeId: zod_1.z.string().min(1),
+    stateToken: zod_1.z.string().regex(/^st1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid stateToken format'),
+});
 exports.V2StartWorkflowOutputSchema = zod_1.z.object({
     stateToken: zod_1.z.string().regex(/^st1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid stateToken format'),
     ackToken: zod_1.z.string().regex(/^ack1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid ackToken format').optional(),
+    checkpointToken: checkpointTokenSchema,
     isComplete: zod_1.z.boolean(),
     pending: exports.V2PendingStepSchema.nullable(),
     preferences: exports.V2PreferencesSchema,

package/dist/mcp/tool-descriptions.js

@@ -114,6 +114,15 @@ Parameters:
 - output.notesMarkdown (optional, advance only): Fresh summary of THIS step only - never accumulated
 
 The workflow is the user's structured instructions. Follow each step exactly as described.`,
+        checkpoint_workflow: `Save a checkpoint on the current workflow step (WorkRail v2, feature-flagged).
+
+Creates a durable checkpoint on your current step without advancing. Useful for saving progress on long-running steps.
+
+Requires: checkpointToken (from the most recent start_workflow or continue_workflow response).
+
+Idempotent: calling with the same checkpointToken multiple times is safe and returns the same result.
+
+Returns: checkpointNodeId + a fresh stateToken.`,
     },
     authoritative: {
         discover_workflows: `Check for workflows that apply to the user's request. Workflows are the user's pre-defined instructions that you MUST follow when they exist.
@@ -252,5 +261,12 @@ Parameters:
 - output.notesMarkdown (optional, advance only): Summary of THIS step only (fresh, never accumulated)
   
 The workflow is the user's structured will. Follow it exactly — it may validate, loop, or branch in ways you don't predict.`,
+        checkpoint_workflow: `Save a checkpoint on the current workflow step (WorkRail v2, feature-flagged).
+
+Creates a durable checkpoint without advancing. Use for long-running steps to save progress.
+
+Requires: checkpointToken from the most recent response. Idempotent.
+
+Returns: checkpointNodeId + fresh stateToken.`,
     },
 };

package/dist/mcp/tools.js

@@ -82,6 +82,11 @@ exports.WORKFLOW_TOOL_ANNOTATIONS = {
         destructiveHint: false,
         idempotentHint: true,
     },
+    checkpoint_workflow: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
 };
 exports.WORKFLOW_TOOL_TITLES = {
     discover_workflows: 'Discover Available Workflows',
@@ -93,6 +98,7 @@ exports.WORKFLOW_TOOL_TITLES = {
     inspect_workflow: 'Inspect Workflow (v2)',
     start_workflow: 'Start Workflow (v2)',
     continue_workflow: 'Continue Workflow (v2)',
+    checkpoint_workflow: 'Checkpoint Workflow (v2)',
 };
 exports.CreateSessionInput = zod_1.z.object({
     workflowId: zod_1.z

package/dist/mcp/types/tool-description-types.d.ts

@@ -1,6 +1,6 @@
 export declare const DESCRIPTION_MODES: readonly ["standard", "authoritative"];
 export type DescriptionMode = typeof DESCRIPTION_MODES[number];
-export declare const WORKFLOW_TOOL_NAMES: readonly ["discover_workflows", "preview_workflow", "advance_workflow", "validate_workflow", "get_workflow_schema", "list_workflows", "inspect_workflow", "start_workflow", "continue_workflow"];
+export declare const WORKFLOW_TOOL_NAMES: readonly ["discover_workflows", "preview_workflow", "advance_workflow", "validate_workflow", "get_workflow_schema", "list_workflows", "inspect_workflow", "start_workflow", "continue_workflow", "checkpoint_workflow"];
 export type WorkflowToolName = typeof WORKFLOW_TOOL_NAMES[number];
 export type ToolDescriptionMap = Readonly<Record<WorkflowToolName, string>>;
 export type DescriptionsByMode = Readonly<Record<DescriptionMode, ToolDescriptionMap>>;

package/dist/mcp/types/tool-description-types.js

@@ -17,6 +17,7 @@ exports.WORKFLOW_TOOL_NAMES = [
     'inspect_workflow',
     'start_workflow',
     'continue_workflow',
+    'checkpoint_workflow',
 ];
 function isDescriptionMode(value) {
     return exports.DESCRIPTION_MODES.includes(value);

package/dist/mcp/types/workflow-tool-edition.d.ts

@@ -2,7 +2,7 @@ import type { z } from 'zod';
 import type { ToolDefinition } from '../tool-factory.js';
 import type { ToolContext } from '../types.js';
 export type V1WorkflowToolName = 'discover_workflows' | 'preview_workflow' | 'advance_workflow' | 'validate_workflow' | 'get_workflow_schema';
-export type V2WorkflowToolName = 'list_workflows' | 'inspect_workflow' | 'start_workflow' | 'continue_workflow';
+export type V2WorkflowToolName = 'list_workflows' | 'inspect_workflow' | 'start_workflow' | 'continue_workflow' | 'checkpoint_workflow';
 export type McpCallToolResult = {
     readonly content: ReadonlyArray<{
         readonly type: 'text';

package/dist/mcp/v2/tool-registry.js

@@ -5,6 +5,7 @@ const handler_factory_js_1 = require("../handler-factory.js");
 const tools_js_1 = require("./tools.js");
 const v2_execution_js_1 = require("../handlers/v2-execution.js");
 const v2_workflow_js_1 = require("../handlers/v2-workflow.js");
+const v2_checkpoint_js_1 = require("../handlers/v2-checkpoint.js");
 function buildV2ToolRegistry(buildTool) {
     const tools = [
         buildTool({
@@ -31,12 +32,19 @@ function buildV2ToolRegistry(buildTool) {
             inputSchema: tools_js_1.V2ContinueWorkflowInput,
             annotations: tools_js_1.V2_TOOL_ANNOTATIONS.continue_workflow,
         }),
+        buildTool({
+            name: 'checkpoint_workflow',
+            title: tools_js_1.V2_TOOL_TITLES.checkpoint_workflow,
+            inputSchema: tools_js_1.V2CheckpointWorkflowInput,
+            annotations: tools_js_1.V2_TOOL_ANNOTATIONS.checkpoint_workflow,
+        }),
     ];
     const handlers = {
         list_workflows: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ListWorkflowsInput, v2_workflow_js_1.handleV2ListWorkflows),
         inspect_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2InspectWorkflowInput, v2_workflow_js_1.handleV2InspectWorkflow),
         start_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2StartWorkflowInput, v2_execution_js_1.handleV2StartWorkflow),
         continue_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ContinueWorkflowInput, v2_execution_js_1.handleV2ContinueWorkflow),
+        checkpoint_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2CheckpointWorkflowInput, v2_checkpoint_js_1.handleV2CheckpointWorkflow),
     };
     return { tools, handlers };
 }

package/dist/mcp/v2/tools.d.ts

@@ -77,10 +77,19 @@ export declare const V2ContinueWorkflowInput: z.ZodEffects<z.ZodObject<{
     ackToken?: string | undefined;
 }>;
 export type V2ContinueWorkflowInput = z.infer<typeof V2ContinueWorkflowInput>;
+export declare const V2CheckpointWorkflowInput: z.ZodObject<{
+    checkpointToken: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    checkpointToken: string;
+}, {
+    checkpointToken: string;
+}>;
+export type V2CheckpointWorkflowInput = z.infer<typeof V2CheckpointWorkflowInput>;
 export declare const V2_TOOL_TITLES: {
     readonly list_workflows: "List Workflows (v2)";
     readonly inspect_workflow: "Inspect Workflow (v2)";
     readonly start_workflow: "Start Workflow (v2)";
     readonly continue_workflow: "Continue Workflow (v2)";
+    readonly checkpoint_workflow: "Checkpoint Workflow (v2)";
 };
 export declare const V2_TOOL_ANNOTATIONS: Readonly<Record<keyof typeof V2_TOOL_TITLES, ToolAnnotations>>;

package/dist/mcp/v2/tools.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2ContinueWorkflowInput = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
+exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ContinueWorkflowInput = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
 const zod_1 = require("zod");
 exports.V2ListWorkflowsInput = zod_1.z.object({});
 exports.V2InspectWorkflowInput = zod_1.z.object({
@@ -54,15 +54,21 @@ exports.V2ContinueWorkflowInput = zod_1.z.object({
         });
     }
 });
+exports.V2CheckpointWorkflowInput = zod_1.z.object({
+    checkpointToken: zod_1.z.string().min(1).describe('The checkpoint token from the most recent start_workflow or continue_workflow response. ' +
+        'Creates a checkpoint on the current step without advancing. Idempotent — calling with the same token is safe.'),
+}).strict();
 exports.V2_TOOL_TITLES = {
     list_workflows: 'List Workflows (v2)',
     inspect_workflow: 'Inspect Workflow (v2)',
     start_workflow: 'Start Workflow (v2)',
     continue_workflow: 'Continue Workflow (v2)',
+    checkpoint_workflow: 'Checkpoint Workflow (v2)',
 };
 exports.V2_TOOL_ANNOTATIONS = {
     list_workflows: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     inspect_workflow: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     start_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
     continue_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    checkpoint_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {