@synergenius/flow-weaver 0.10.12 → 0.11.0

package/dist/mcp/tools-debug.js

@@ -0,0 +1,451 @@
+import { z } from 'zod';
+import * as path from 'path';
+import * as fs from 'fs';
+import { parseWorkflow } from '../api/index.js';
+import { getTopologicalOrder } from '../api/query.js';
+import { DebugController } from '../runtime/debug-controller.js';
+import { CheckpointWriter, loadCheckpoint, findLatestCheckpoint } from '../runtime/checkpoint.js';
+import { executeWorkflowFromFile } from './workflow-executor.js';
+import { AgentChannel } from './agent-channel.js';
+import { storeDebugSession, getDebugSession, removeDebugSession, listDebugSessions, } from './debug-session.js';
+import { makeToolResult, makeErrorResult } from './response-utils.js';
+/**
+ * Helper: get execution order for a workflow file by parsing its annotations.
+ */
+async function getExecutionOrder(filePath, workflowName) {
+    const source = fs.readFileSync(path.resolve(filePath), 'utf8');
+    const parsed = await parseWorkflow(source, { workflowName });
+    if (parsed.errors.length > 0) {
+        throw new Error(`Failed to parse workflow: ${parsed.errors.join(', ')}`);
+    }
+    return getTopologicalOrder(parsed.ast);
+}
+/**
+ * Helper: race execution against debug pause. Returns the outcome.
+ */
+async function raceDebugPause(session) {
+    try {
+        const raceResult = await Promise.race([
+            session.executionPromise.then((r) => ({
+                type: 'completed',
+                result: r?.result ?? r,
+            })),
+            session.controller.onPause().then((state) => ({
+                type: 'paused',
+                state,
+            })),
+        ]);
+        if (raceResult.type === 'paused') {
+            session.lastPauseState = raceResult.state;
+        }
+        return raceResult;
+    }
+    catch (err) {
+        return {
+            type: 'error',
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Helper: clean up a debug session after completion or abort.
+ */
+function cleanupDebugSession(debugId) {
+    const session = getDebugSession(debugId);
+    if (!session)
+        return;
+    for (const tmpFile of session.tmpFiles) {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    removeDebugSession(debugId);
+}
+/**
+ * Helper: find the variable key for a nodeId:portName pair from the variables map.
+ * Returns the full key (nodeId:portName:executionIndex) or null.
+ */
+function findVariableKey(variables, nodeId, portName, executionIndex) {
+    const prefix = `${nodeId}:${portName}:`;
+    if (executionIndex !== undefined) {
+        const key = `${prefix}${executionIndex}`;
+        return key in variables ? key : null;
+    }
+    // Find the latest execution index for this nodeId:portName
+    let latestKey = null;
+    let latestIndex = -1;
+    for (const key of Object.keys(variables)) {
+        if (key.startsWith(prefix)) {
+            const idx = parseInt(key.substring(prefix.length), 10);
+            if (idx > latestIndex) {
+                latestIndex = idx;
+                latestKey = key;
+            }
+        }
+    }
+    return latestKey;
+}
+export function registerDebugTools(mcp) {
+    // -------------------------------------------------------------------------
+    // fw_debug_workflow — Start a debug session
+    // -------------------------------------------------------------------------
+    mcp.tool('fw_debug_workflow', 'Start a step-through debug session for a workflow. Compiles and executes the workflow, ' +
+        'pausing before the first node. Returns a debugId and the initial pause state.', {
+        filePath: z.string().describe('Path to the workflow .ts file'),
+        workflowName: z.string().optional().describe('Specific workflow function name (for multi-workflow files)'),
+        params: z.record(z.unknown()).optional().describe('Parameters to pass to the workflow'),
+        breakpoints: z.array(z.string()).optional().describe('Node IDs to set as initial breakpoints'),
+        checkpoint: z.boolean().optional().describe('Enable checkpointing to disk after each node (default: false)'),
+    }, async (args) => {
+        try {
+            const debugId = `debug-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+            // Get execution order from the workflow file
+            const executionOrder = await getExecutionOrder(args.filePath, args.workflowName);
+            // Set up checkpoint writer if requested
+            let checkpointWriter;
+            if (args.checkpoint) {
+                checkpointWriter = new CheckpointWriter(args.filePath, args.workflowName ?? 'default', debugId, args.params);
+            }
+            // Create the debug controller
+            const controller = new DebugController({
+                debug: true,
+                checkpoint: args.checkpoint ?? false,
+                checkpointWriter,
+                breakpoints: args.breakpoints,
+                executionOrder,
+            });
+            // Create agent channel in case the workflow uses waitForAgent
+            const agentChannel = new AgentChannel();
+            // Start execution (non-blocking: the workflow will pause at the first node)
+            const execPromise = executeWorkflowFromFile(args.filePath, args.params, {
+                workflowName: args.workflowName,
+                includeTrace: true,
+                agentChannel,
+                debugController: controller,
+            });
+            // Store the session
+            const session = {
+                debugId,
+                filePath: args.filePath,
+                workflowName: args.workflowName,
+                controller,
+                executionPromise: execPromise,
+                createdAt: Date.now(),
+                tmpFiles: [],
+            };
+            storeDebugSession(session);
+            // Wait for the first pause or immediate completion
+            const outcome = await raceDebugPause(session);
+            if (outcome.type === 'paused') {
+                return makeToolResult({
+                    debugId,
+                    status: 'paused',
+                    state: outcome.state,
+                });
+            }
+            if (outcome.type === 'completed') {
+                cleanupDebugSession(debugId);
+                return makeToolResult({
+                    debugId,
+                    status: 'completed',
+                    result: outcome.result,
+                });
+            }
+            // Error
+            cleanupDebugSession(debugId);
+            return makeErrorResult('EXECUTION_ERROR', outcome.message);
+        }
+        catch (err) {
+            return makeErrorResult('DEBUG_START_ERROR', err instanceof Error ? err.message : String(err));
+        }
+    });
+    // -------------------------------------------------------------------------
+    // fw_debug_step — Execute next node then pause
+    // -------------------------------------------------------------------------
+    mcp.tool('fw_debug_step', 'Step to the next node in a debug session. Executes one node then pauses again.', {
+        debugId: z.string().describe('The debug session ID from fw_debug_workflow'),
+    }, async (args) => {
+        const session = getDebugSession(args.debugId);
+        if (!session) {
+            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}". Use fw_debug_workflow to start one.`);
+        }
+        try {
+            session.controller.resume({ type: 'step' });
+            const outcome = await raceDebugPause(session);
+            if (outcome.type === 'paused') {
+                return makeToolResult({
+                    status: 'paused',
+                    state: outcome.state,
+                });
+            }
+            if (outcome.type === 'completed') {
+                cleanupDebugSession(args.debugId);
+                return makeToolResult({
+                    status: 'completed',
+                    result: outcome.result,
+                });
+            }
+            cleanupDebugSession(args.debugId);
+            return makeErrorResult('EXECUTION_ERROR', outcome.message);
+        }
+        catch (err) {
+            cleanupDebugSession(args.debugId);
+            return makeErrorResult('STEP_ERROR', err instanceof Error ? err.message : String(err));
+        }
+    });
+    // -------------------------------------------------------------------------
+    // fw_debug_continue — Run to completion or breakpoint
+    // -------------------------------------------------------------------------
+    mcp.tool('fw_debug_continue', 'Continue execution from the current pause point. Runs to completion, or stops at the ' +
+        'next breakpoint if toBreakpoint is true.', {
+        debugId: z.string().describe('The debug session ID'),
+        toBreakpoint: z
+            .boolean()
+            .optional()
+            .describe('If true, pause at the next breakpoint instead of running to completion'),
+    }, async (args) => {
+        const session = getDebugSession(args.debugId);
+        if (!session) {
+            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}".`);
+        }
+        try {
+            const action = args.toBreakpoint
+                ? { type: 'continueToBreakpoint' }
+                : { type: 'continue' };
+            session.controller.resume(action);
+            const outcome = await raceDebugPause(session);
+            if (outcome.type === 'paused') {
+                return makeToolResult({
+                    status: 'paused',
+                    state: outcome.state,
+                });
+            }
+            if (outcome.type === 'completed') {
+                cleanupDebugSession(args.debugId);
+                return makeToolResult({
+                    status: 'completed',
+                    result: outcome.result,
+                });
+            }
+            cleanupDebugSession(args.debugId);
+            return makeErrorResult('EXECUTION_ERROR', outcome.message);
+        }
+        catch (err) {
+            cleanupDebugSession(args.debugId);
+            return makeErrorResult('CONTINUE_ERROR', err instanceof Error ? err.message : String(err));
+        }
+    });
+    // -------------------------------------------------------------------------
+    // fw_debug_inspect — Read current state without advancing
+    // -------------------------------------------------------------------------
+    mcp.tool('fw_debug_inspect', 'Inspect the current debug state without advancing execution. Returns all variables, ' +
+        'or filter to a specific node.', {
+        debugId: z.string().describe('The debug session ID'),
+        nodeId: z.string().optional().describe('Filter to show only this node\'s variables'),
+    }, async (args) => {
+        const session = getDebugSession(args.debugId);
+        if (!session) {
+            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}".`);
+        }
+        if (!session.lastPauseState) {
+            return makeErrorResult('NOT_PAUSED', 'Debug session has not paused yet. Wait for the workflow to reach a pause point.');
+        }
+        const state = { ...session.lastPauseState };
+        // Filter variables to a specific node if requested
+        if (args.nodeId) {
+            const prefix = `${args.nodeId}:`;
+            const filtered = {};
+            for (const [key, value] of Object.entries(state.variables)) {
+                if (key.startsWith(prefix)) {
+                    // Show as portName:executionIndex for readability
+                    filtered[key.substring(prefix.length)] = value;
+                }
+            }
+            return makeToolResult({
+                nodeId: args.nodeId,
+                variables: filtered,
+                state: {
+                    currentNodeId: state.currentNodeId,
+                    phase: state.phase,
+                    position: state.position,
+                    completedNodes: state.completedNodes,
+                },
+            });
+        }
+        return makeToolResult({ state });
+    });
+    // -------------------------------------------------------------------------
+    // fw_debug_set_variable — Modify a variable value
+    // -------------------------------------------------------------------------
+    mcp.tool('fw_debug_set_variable', 'Modify a variable value in the debug session. The new value will be used by downstream ' +
+        'nodes when execution continues.', {
+        debugId: z.string().describe('The debug session ID'),
+        nodeId: z.string().describe('The node that produced the variable'),
+        portName: z.string().describe('The output port name'),
+        value: z.unknown().describe('The new value to set'),
+        executionIndex: z.number().optional().describe('Execution index (defaults to the latest)'),
+    }, async (args) => {
+        const session = getDebugSession(args.debugId);
+        if (!session) {
+            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}".`);
+        }
+        if (!session.lastPauseState) {
+            return makeErrorResult('NOT_PAUSED', 'Cannot modify variables when the session is not paused.');
+        }
+        // Find the variable key
+        const key = findVariableKey(session.lastPauseState.variables, args.nodeId, args.portName, args.executionIndex);
+        if (!key) {
+            return makeErrorResult('VARIABLE_NOT_FOUND', `No variable found for ${args.nodeId}.${args.portName}` +
+                (args.executionIndex !== undefined ? `[${args.executionIndex}]` : '') +
+                '. Check fw_debug_inspect to see available variables.');
+        }
+        // Queue the modification (applied before the next node executes)
+        session.controller.setVariable(key, args.value);
+        // Update the lastPauseState to reflect the modification
+        session.lastPauseState.variables[key] = args.value;
+        return makeToolResult({
+            modified: key,
+            value: args.value,
+        });
+    });
+    // -------------------------------------------------------------------------
+    // fw_debug_breakpoint — Manage breakpoints
+    // -------------------------------------------------------------------------
+    mcp.tool('fw_debug_breakpoint', 'Add, remove, or list breakpoints in a debug session. Breakpoints cause execution to ' +
+        'pause when running with fw_debug_continue(toBreakpoint: true).', {
+        debugId: z.string().describe('The debug session ID'),
+        action: z.enum(['add', 'remove', 'list']).describe('Action to perform'),
+        nodeId: z.string().optional().describe('Node ID for add/remove (not needed for list)'),
+    }, async (args) => {
+        const session = getDebugSession(args.debugId);
+        if (!session) {
+            return makeErrorResult('SESSION_NOT_FOUND', `No debug session found with ID "${args.debugId}".`);
+        }
+        if (args.action === 'add') {
+            if (!args.nodeId) {
+                return makeErrorResult('MISSING_PARAM', 'nodeId is required to add a breakpoint');
+            }
+            session.controller.addBreakpoint(args.nodeId);
+        }
+        else if (args.action === 'remove') {
+            if (!args.nodeId) {
+                return makeErrorResult('MISSING_PARAM', 'nodeId is required to remove a breakpoint');
+            }
+            session.controller.removeBreakpoint(args.nodeId);
+        }
+        return makeToolResult({
+            breakpoints: session.controller.getBreakpoints(),
+        });
+    });
+    // -------------------------------------------------------------------------
+    // fw_resume_from_checkpoint — Resume a crashed workflow
+    // -------------------------------------------------------------------------
+    mcp.tool('fw_resume_from_checkpoint', 'Resume a workflow from a checkpoint file written after a crash. Skips already-completed ' +
+        'nodes and re-runs from the last checkpoint position.', {
+        filePath: z.string().describe('Path to the workflow .ts file'),
+        checkpointFile: z
+            .string()
+            .optional()
+            .describe('Path to the checkpoint file. If omitted, auto-detects the latest.'),
+        workflowName: z
+            .string()
+            .optional()
+            .describe('Workflow function name (for multi-workflow files)'),
+        debug: z
+            .boolean()
+            .optional()
+            .describe('Enter step-through debug mode at the resume point (default: false)'),
+    }, async (args) => {
+        try {
+            // Find checkpoint file
+            const checkpointPath = args.checkpointFile ?? findLatestCheckpoint(args.filePath, args.workflowName);
+            if (!checkpointPath) {
+                return makeErrorResult('NO_CHECKPOINT', `No checkpoint file found for ${args.filePath}. ` +
+                    'Checkpoints are created when running with checkpoint: true.');
+            }
+            // Load and validate checkpoint
+            const { data, stale, rerunNodes, skipNodes } = loadCheckpoint(checkpointPath, args.filePath);
+            const skippedCount = data.completedNodes.length - rerunNodes.length;
+            // Create debug controller with skip nodes from checkpoint
+            const controller = new DebugController({
+                debug: args.debug ?? false,
+                checkpoint: true,
+                checkpointWriter: new CheckpointWriter(args.filePath, data.workflowName, `resume-${Date.now()}`, data.params),
+                executionOrder: data.executionOrder,
+                skipNodes,
+            });
+            const agentChannel = new AgentChannel();
+            // Execute with the skip nodes configured
+            const execPromise = executeWorkflowFromFile(args.filePath, data.params, {
+                workflowName: data.workflowName,
+                includeTrace: true,
+                agentChannel,
+                debugController: controller,
+            });
+            // If debug mode, handle like fw_debug_workflow
+            if (args.debug) {
+                const debugId = `debug-resume-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+                const session = {
+                    debugId,
+                    filePath: args.filePath,
+                    workflowName: data.workflowName,
+                    controller,
+                    executionPromise: execPromise,
+                    createdAt: Date.now(),
+                    tmpFiles: [],
+                };
+                storeDebugSession(session);
+                const outcome = await raceDebugPause(session);
+                if (outcome.type === 'paused') {
+                    return makeToolResult({
+                        debugId,
+                        status: 'paused',
+                        resumedFrom: checkpointPath,
+                        skippedNodes: skippedCount,
+                        ...(rerunNodes.length > 0 && { rerunNodes }),
+                        ...(stale && { warning: 'Workflow file has changed since checkpoint was written.' }),
+                        state: outcome.state,
+                    });
+                }
+                if (outcome.type === 'completed') {
+                    cleanupDebugSession(debugId);
+                    return makeToolResult({
+                        status: 'completed',
+                        resumedFrom: checkpointPath,
+                        skippedNodes: skippedCount,
+                        ...(rerunNodes.length > 0 && { rerunNodes }),
+                        result: outcome.result,
+                    });
+                }
+                cleanupDebugSession(debugId);
+                return makeErrorResult('EXECUTION_ERROR', outcome.message);
+            }
+            // Non-debug mode: run to completion
+            const result = await execPromise;
+            // Clean up the checkpoint file on successful completion
+            const writer = new CheckpointWriter(args.filePath, data.workflowName, '', {});
+            writer.cleanup();
+            return makeToolResult({
+                status: 'completed',
+                resumedFrom: checkpointPath,
+                skippedNodes: skippedCount,
+                ...(rerunNodes.length > 0 && { rerunNodes }),
+                ...(stale && { warning: 'Workflow file has changed since checkpoint was written.' }),
+                result: result?.result ?? result,
+            });
+        }
+        catch (err) {
+            return makeErrorResult('RESUME_ERROR', err instanceof Error ? err.message : String(err));
+        }
+    });
+    // -------------------------------------------------------------------------
+    // fw_list_debug_sessions — List active debug sessions
+    // -------------------------------------------------------------------------
+    mcp.tool('fw_list_debug_sessions', 'List all active debug sessions.', {}, async () => {
+        return makeToolResult(listDebugSessions());
+    });
+}
+//# sourceMappingURL=tools-debug.js.map

package/dist/mcp/workflow-executor.d.ts

@@ -4,6 +4,7 @@
  */
 import type { FwMockConfig } from '../built-in-nodes/mock-types.js';
 import type { AgentChannel } from './agent-channel.js';
+import type { DebugController } from '../runtime/debug-controller.js';
 /** A single trace event captured during workflow execution. */
 export interface ExecutionTraceEvent {
     /** The event type (e.g. "NODE_STARTED", "NODE_COMPLETED"). */
@@ -69,6 +70,7 @@ export declare function executeWorkflowFromFile(filePath: string, params?: Recor
     includeTrace?: boolean;
     mocks?: FwMockConfig;
     agentChannel?: AgentChannel;
+    debugController?: DebugController;
     onEvent?: (event: ExecutionTraceEvent) => void;
 }): Promise<ExecuteWorkflowResult>;
 /** Compute a concise summary from raw trace events. */

package/dist/mcp/workflow-executor.js

@@ -44,13 +44,18 @@ export async function executeWorkflowFromFile(filePath, params, options) {
         // Discover all workflows in the file
         const source = fs.readFileSync(resolvedPath, 'utf8');
         const allWorkflows = getAvailableWorkflows(source);
-        // Compile each workflow in-place so all function bodies are generated
+        // Compile each workflow in-place so all function bodies are generated.
+        // Debug controller requires dev mode (production: false) so that
+        // __ctrl__.beforeNode/afterNode hooks are emitted in generated code.
+        const production = options?.debugController
+            ? false
+            : (options?.production ?? !includeTrace);
         for (const wf of allWorkflows) {
             await compileWorkflow(tmpTsFile, {
                 write: true,
                 inPlace: true,
                 parse: { workflowName: wf.functionName },
-                generate: { production: options?.production ?? !includeTrace },
+                generate: { production },
             });
         }
         // Inject debugger binding: replace the TypeScript-only `declare const`
@@ -93,6 +98,10 @@ export async function executeWorkflowFromFile(filePath, params, options) {
         if (options?.agentChannel) {
             globalThis.__fw_agent_channel__ = options.agentChannel;
         }
+        // Set debug controller for step-through debugging and checkpoint/resume
+        if (options?.debugController) {
+            globalThis.__fw_debug_controller__ = options.debugController;
+        }
         // Dynamic import using file:// URL for cross-platform compatibility
         // (Windows paths like C:\... break with bare import() — "Received protocol 'c:'")
         const mod = await import(pathToFileURL(tmpFile).href);
@@ -127,6 +136,7 @@ export async function executeWorkflowFromFile(filePath, params, options) {
         delete globalThis.__fw_mocks__;
         delete globalThis.__fw_workflow_registry__;
         delete globalThis.__fw_agent_channel__;
+        delete globalThis.__fw_debug_controller__;
         // Clean up temp files
         try {
             fs.unlinkSync(tmpFile);

package/dist/runtime/ExecutionContext.d.ts

@@ -143,6 +143,25 @@ export declare class GeneratedExecutionContext {
         status: 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
         result?: unknown;
     }): void;
+    /**
+     * Serialize the execution context state for checkpointing.
+     * Function values are resolved to concrete values before serialization.
+     */
+    serialize(): {
+        variables: Record<string, unknown>;
+        executions: Record<string, ExecutionInfo>;
+        executionCounter: number;
+        nodeExecutionCounts: Record<string, number>;
+    };
+    /**
+     * Restore execution context state from a checkpoint.
+     */
+    restore(data: {
+        variables: Record<string, unknown>;
+        executions: Record<string, ExecutionInfo>;
+        executionCounter: number;
+        nodeExecutionCounts: Record<string, number>;
+    }): void;
 }
 export {};
 //# sourceMappingURL=ExecutionContext.d.ts.map

package/dist/runtime/ExecutionContext.js

@@ -233,5 +233,48 @@ export class GeneratedExecutionContext {
             });
         }
     }
+    /**
+     * Serialize the execution context state for checkpointing.
+     * Function values are resolved to concrete values before serialization.
+     */
+    serialize() {
+        const vars = {};
+        for (const [key, value] of this.variables) {
+            if (typeof value === 'function') {
+                try {
+                    vars[key] = value();
+                }
+                catch {
+                    vars[key] = value; // Let the checkpoint layer handle the marker
+                }
+            }
+            else {
+                vars[key] = value;
+            }
+        }
+        const execs = {};
+        for (const [key, info] of this.executions) {
+            execs[key] = { ...info };
+        }
+        const nodeCounts = {};
+        for (const [key, count] of this.nodeExecutionIndices) {
+            nodeCounts[key] = count;
+        }
+        return {
+            variables: vars,
+            executions: execs,
+            executionCounter: this.executionCounter,
+            nodeExecutionCounts: nodeCounts,
+        };
+    }
+    /**
+     * Restore execution context state from a checkpoint.
+     */
+    restore(data) {
+        this.variables = new Map(Object.entries(data.variables));
+        this.executions = new Map(Object.entries(data.executions));
+        this.executionCounter = data.executionCounter;
+        this.nodeExecutionIndices = new Map(Object.entries(data.nodeExecutionCounts));
+    }
 }
 //# sourceMappingURL=ExecutionContext.js.map

package/dist/runtime/checkpoint.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Checkpoint serialization for crash recovery.
+ *
+ * Writes workflow state to disk after each node completes. If the process
+ * crashes, the checkpoint file persists and can be used to resume execution
+ * from the last completed node.
+ *
+ * Checkpoint files live in .fw-checkpoints/ next to the workflow file and
+ * are auto-deleted after successful workflow completion.
+ */
+import type { GeneratedExecutionContext, ExecutionInfo } from './ExecutionContext.js';
+/** Marker stored in place of values that couldn't be serialized */
+export interface UnserializableMarker {
+    __fw_unserializable__: true;
+    nodeId: string;
+    portName: string;
+    reason: string;
+}
+export interface CheckpointData {
+    /** Format version for forward compatibility */
+    version: 1;
+    /** SHA-256 hash of the workflow source file */
+    workflowHash: string;
+    /** Workflow function name */
+    workflowName: string;
+    /** Original file path */
+    filePath: string;
+    /** Input parameters the workflow was called with */
+    params: Record<string, unknown>;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Node IDs in completion order */
+    completedNodes: string[];
+    /** Full topological execution order */
+    executionOrder: string[];
+    /** Current position in execution order */
+    position: number;
+    /** Serialized variables: key -> value */
+    variables: Record<string, unknown>;
+    /** Execution info for completed nodes */
+    executions: Record<string, ExecutionInfo>;
+    /** Execution counter value */
+    executionCounter: number;
+    /** Per-node execution counts */
+    nodeExecutionCounts: Record<string, number>;
+    /** Nodes whose outputs couldn't be fully serialized */
+    unsafeNodes: string[];
+}
+export declare class CheckpointWriter {
+    private dir;
+    private filePath;
+    private workflowName;
+    private runId;
+    private params;
+    private workflowHash;
+    private checkpointPath;
+    private writeLock;
+    constructor(workflowFilePath: string, workflowName: string, runId: string, params?: Record<string, unknown>);
+    /**
+     * Write a checkpoint after a node completes. Uses a write lock so
+     * concurrent calls from parallel nodes are serialized.
+     */
+    write(completedNodes: string[], executionOrder: string[], position: number, ctx: GeneratedExecutionContext): Promise<void>;
+    /** Clean up checkpoint file after successful completion */
+    cleanup(): void;
+    getCheckpointPath(): string;
+    private _writeCheckpoint;
+}
+/**
+ * Load a checkpoint file and validate it against the current workflow.
+ * Returns the checkpoint data and a list of nodes that need to be re-run
+ * (because their outputs weren't serializable).
+ */
+export declare function loadCheckpoint(checkpointPath: string, workflowFilePath?: string): {
+    data: CheckpointData;
+    stale: boolean;
+    rerunNodes: string[];
+    skipNodes: Map<string, Record<string, unknown>>;
+};
+/**
+ * Find the most recent checkpoint file for a workflow.
+ */
+export declare function findLatestCheckpoint(workflowFilePath: string, workflowName?: string): string | null;
+//# sourceMappingURL=checkpoint.d.ts.map