@synergenius/flow-weaver 0.10.11 → 0.11.0

package/dist/api/generate-in-place.js

@@ -114,15 +114,16 @@ export function generateInPlace(sourceCode, ast, options = {}) {
     // If any node is async, force async (even if source isn't marked async)
     const nodesRequireAsync = shouldWorkflowBeAsync(ast, ast.nodeTypes);
     const sourceIsAsync = detectFunctionIsAsync(result, ast.functionName);
-    const isAsync = nodesRequireAsync || sourceIsAsync;
-    // Add async keyword to source if nodes require it but source doesn't have it
-    const asyncSigResult = ensureAsyncKeyword(result, ast.functionName, nodesRequireAsync);
+    const forceAsync = nodesRequireAsync;
+    const isAsync = forceAsync || sourceIsAsync;
+    // Add async keyword to source if nodes or debug hooks require it
+    const asyncSigResult = ensureAsyncKeyword(result, ast.functionName, forceAsync);
     if (asyncSigResult.changed) {
         result = asyncSigResult.code;
         hasChanges = true;
     }
     // Step 5b: Wrap return type in Promise<T> when async was added
-    const returnTypeResult = ensurePromiseReturnType(result, ast.functionName, nodesRequireAsync);
+    const returnTypeResult = ensurePromiseReturnType(result, ast.functionName, forceAsync);
     if (returnTypeResult.changed) {
         result = returnTypeResult.code;
         hasChanges = true;

package/dist/api/inline-runtime.js

@@ -89,6 +89,12 @@ export function generateInlineRuntime(production, exportClasses = false) {
         // (e.g., passed as a function parameter or injected by execution harness)
         lines.push('declare const __flowWeaverDebugger__: TDebugger | undefined;');
         lines.push('');
+        // Debug controller type for step-through debugging and checkpoint/resume
+        lines.push('type TDebugController = {');
+        lines.push('  beforeNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<boolean> | boolean;');
+        lines.push('  afterNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<void> | void;');
+        lines.push('};');
+        lines.push('');
     }
     // Declare __abortSignal__ so TypeScript knows it might exist at runtime
     // (passed as a function parameter for cancellation support)
@@ -420,6 +426,42 @@ export function generateInlineRuntime(production, exportClasses = false) {
         lines.push('    // No-op in production mode');
         lines.push('  }');
     }
+    // Serialize/restore methods (dev mode only, used by debug controller and checkpointing)
+    if (!production) {
+        lines.push('');
+        lines.push('  serialize(): {');
+        lines.push('    variables: Record<string, unknown>;');
+        lines.push('    executions: Record<string, ExecutionInfo>;');
+        lines.push('    executionCounter: number;');
+        lines.push('    nodeExecutionCounts: Record<string, number>;');
+        lines.push('  } {');
+        lines.push('    const vars: Record<string, unknown> = {};');
+        lines.push('    for (const [key, value] of this.variables) {');
+        lines.push('      if (typeof value === "function") {');
+        lines.push('        try { vars[key] = (value as () => unknown)(); } catch { vars[key] = value; }');
+        lines.push('      } else {');
+        lines.push('        vars[key] = value;');
+        lines.push('      }');
+        lines.push('    }');
+        lines.push('    const execs: Record<string, ExecutionInfo> = {};');
+        lines.push('    for (const [key, info] of this.executions) { execs[key] = { ...info }; }');
+        lines.push('    const nodeCounts: Record<string, number> = {};');
+        lines.push('    for (const [key, count] of this.nodeExecutionIndices) { nodeCounts[key] = count; }');
+        lines.push('    return { variables: vars, executions: execs, executionCounter: this.executionCounter, nodeExecutionCounts: nodeCounts };');
+        lines.push('  }');
+        lines.push('');
+        lines.push('  restore(data: {');
+        lines.push('    variables: Record<string, unknown>;');
+        lines.push('    executions: Record<string, ExecutionInfo>;');
+        lines.push('    executionCounter: number;');
+        lines.push('    nodeExecutionCounts: Record<string, number>;');
+        lines.push('  }): void {');
+        lines.push('    this.variables = new Map(Object.entries(data.variables));');
+        lines.push('    this.executions = new Map(Object.entries(data.executions));');
+        lines.push('    this.executionCounter = data.executionCounter;');
+        lines.push('    this.nodeExecutionIndices = new Map(Object.entries(data.nodeExecutionCounts));');
+        lines.push('  }');
+    }
     lines.push('}');
     lines.push('');
     return lines.join('\n');

package/dist/cli/commands/run.d.ts

@@ -23,6 +23,14 @@ export interface RunOptions {
     mocks?: string;
     /** Path to JSON file containing mock config for built-in nodes */
     mocksFile?: string;
+    /** Start in step-through debug mode */
+    debug?: boolean;
+    /** Enable checkpointing to disk after each node */
+    checkpoint?: boolean;
+    /** Resume from a checkpoint file (true for auto-detect, or a file path) */
+    resume?: boolean | string;
+    /** Initial breakpoint node IDs */
+    breakpoint?: string[];
 }
 /**
  * Execute a workflow file and output the result.

package/dist/cli/commands/run.js

@@ -6,6 +6,9 @@ import * as fs from 'fs';
 import * as readline from 'readline';
 import { executeWorkflowFromFile } from '../../mcp/workflow-executor.js';
 import { AgentChannel } from '../../mcp/agent-channel.js';
+import { DebugController } from '../../runtime/debug-controller.js';
+import { CheckpointWriter, loadCheckpoint, findLatestCheckpoint } from '../../runtime/checkpoint.js';
+import { getTopologicalOrder } from '../../api/query.js';
 import { logger } from '../utils/logger.js';
 import { getFriendlyError } from '../../friendly-errors.js';
 import { getErrorMessage } from '../../utils/error-utils.js';
@@ -103,6 +106,46 @@ export async function runCommand(input, options) {
         }, options.timeout);
     }
     try {
+        // Handle --resume: load checkpoint and set up skip nodes
+        let resumeSkipNodes;
+        let resumeCheckpointPath;
+        let resumeParams;
+        let resumeWorkflowName;
+        let resumeExecutionOrder;
+        let resumeRerunNodes;
+        let resumeStale = false;
+        if (options.resume) {
+            const checkpointPath = typeof options.resume === 'string'
+                ? options.resume
+                : findLatestCheckpoint(filePath, options.workflow);
+            if (!checkpointPath) {
+                throw new Error(`No checkpoint file found for ${filePath}. ` +
+                    'Checkpoints are created when running with --checkpoint.');
+            }
+            const { data, stale, rerunNodes, skipNodes } = loadCheckpoint(checkpointPath, filePath);
+            resumeSkipNodes = skipNodes;
+            resumeCheckpointPath = checkpointPath;
+            resumeParams = data.params;
+            resumeWorkflowName = data.workflowName;
+            resumeExecutionOrder = data.executionOrder;
+            resumeRerunNodes = rerunNodes;
+            resumeStale = stale;
+            // Use checkpoint params if none provided
+            if (Object.keys(params).length === 0) {
+                params = data.params;
+            }
+            if (!options.json) {
+                const skipped = data.completedNodes.length - rerunNodes.length;
+                logger.info(`Resuming from checkpoint: ${checkpointPath}`);
+                logger.info(`Skipping ${skipped} completed nodes`);
+                if (rerunNodes.length > 0) {
+                    logger.info(`Re-running ${rerunNodes.length} nodes: ${rerunNodes.join(', ')}`);
+                }
+                if (stale) {
+                    logger.warn('Workflow file has changed since checkpoint was written.');
+                }
+            }
+        }
         // Determine trace inclusion:
         // - If --production is set, no trace (unless --trace explicitly set)
         // - If --trace is set, include trace
@@ -111,6 +154,37 @@ export async function runCommand(input, options) {
         if (!options.json && mocks) {
             logger.info('Running with mock data');
         }
+        // Set up debug controller if --debug, --checkpoint, or --resume
+        const useDebug = options.debug || options.checkpoint || options.resume;
+        let debugController;
+        if (useDebug) {
+            // Get execution order for the controller
+            let executionOrder = resumeExecutionOrder;
+            if (!executionOrder) {
+                const source = fs.readFileSync(filePath, 'utf8');
+                const parsed = await parseWorkflow(source, { workflowName: options.workflow });
+                if (parsed.errors.length === 0) {
+                    executionOrder = getTopologicalOrder(parsed.ast);
+                }
+                else {
+                    executionOrder = [];
+                }
+            }
+            // Set up checkpoint writer
+            let checkpointWriter;
+            if (options.checkpoint || options.resume) {
+                const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+                checkpointWriter = new CheckpointWriter(filePath, resumeWorkflowName ?? options.workflow ?? 'default', runId, params);
+            }
+            debugController = new DebugController({
+                debug: options.debug ?? false,
+                checkpoint: !!(options.checkpoint || options.resume),
+                checkpointWriter,
+                breakpoints: options.breakpoint,
+                executionOrder,
+                skipNodes: resumeSkipNodes,
+            });
+        }
         // Build onEvent callback for real-time streaming
         const nodeStartTimes = new Map();
         const onEvent = options.stream && !options.json
@@ -141,25 +215,58 @@ export async function runCommand(input, options) {
             : undefined;
         const channel = new AgentChannel();
         const execPromise = executeWorkflowFromFile(filePath, params, {
-            workflowName: options.workflow,
+            workflowName: resumeWorkflowName ?? options.workflow,
             production: options.production ?? false,
             includeTrace,
             mocks,
             agentChannel: channel,
+            debugController,
             onEvent,
         });
+        // If debug mode is active and interactive, enter the debug REPL
+        if (options.debug && debugController && process.stdin.isTTY) {
+            const debugResult = await runDebugRepl(debugController, execPromise, channel, options);
+            if (timedOut)
+                return;
+            if (options.json) {
+                process.stdout.write(JSON.stringify({
+                    success: true,
+                    result: debugResult,
+                    ...(resumeCheckpointPath && { resumedFrom: resumeCheckpointPath }),
+                    ...(resumeRerunNodes && resumeRerunNodes.length > 0 && { rerunNodes: resumeRerunNodes }),
+                    ...(resumeStale && { warning: 'Workflow changed since checkpoint.' }),
+                }, null, 2) + '\n');
+            }
+            else {
+                logger.success('Debug session completed');
+                logger.newline();
+                logger.section('Result');
+                logger.log(JSON.stringify(debugResult, null, 2));
+            }
+            return;
+        }
         let result;
         let execDone = false;
         // Race loop: detect pauses, prompt user, resume
         while (!execDone) {
-            const raceResult = await Promise.race([
+            const promises = [
                 execPromise.then((r) => ({ type: 'completed', result: r })),
-                channel.onPause().then((req) => ({ type: 'paused', request: req })),
-            ]);
+                channel.onPause().then((req) => ({ type: 'agent_paused', request: req })),
+            ];
+            // Also race against debug controller pause if present (non-interactive checkpoint mode)
+            if (debugController) {
+                promises.push(debugController.onPause().then((state) => ({ type: 'debug_paused', state })));
+            }
+            const raceResult = await Promise.race(promises);
             if (raceResult.type === 'completed') {
                 result = raceResult.result;
                 execDone = true;
             }
+            else if (raceResult.type === 'debug_paused') {
+                // Non-interactive debug mode (checkpoint only, no --debug flag):
+                // Auto-continue, the checkpoint was written in afterNode
+                debugController.resume({ type: 'continue' });
+            }
             else {
                 // Workflow paused at waitForAgent
                 const request = raceResult.request;
@@ -200,6 +307,8 @@ export async function runCommand(input, options) {
                 executionTime: result.executionTime,
                 result: result.result,
                 ...(includeTrace && result.trace && { traceCount: result.trace.length }),
+                ...(resumeCheckpointPath && { resumedFrom: resumeCheckpointPath }),
+                ...(resumeRerunNodes && resumeRerunNodes.length > 0 && { rerunNodes: resumeRerunNodes }),
             }, null, 2) + '\n');
         }
         else {
@@ -301,6 +410,289 @@ export async function validateMockConfig(mocks, filePath, workflowName) {
         // Parsing failed — skip validation, the execution will report the real error
     }
 }
+// ---------------------------------------------------------------------------
+// Interactive debug REPL
+// ---------------------------------------------------------------------------
+function printDebugState(state) {
+    const pos = `${state.position + 1}/${state.executionOrder.length}`;
+    logger.log(`\n[paused] ${state.phase}: ${state.currentNodeId} (${pos})`);
+    if (state.phase === 'after' && state.currentNodeOutputs) {
+        // Show outputs of the node that just completed
+        for (const [port, value] of Object.entries(state.currentNodeOutputs)) {
+            const valueStr = JSON.stringify(value);
+            const display = valueStr.length > 80 ? valueStr.substring(0, 77) + '...' : valueStr;
+            logger.log(`  ${state.currentNodeId}.${port} = ${display}`);
+        }
+    }
+}
+function printDebugHelp() {
+    logger.log('Commands:');
+    logger.log('  s, step             Step to next node');
+    logger.log('  c, continue         Run to completion');
+    logger.log('  cb                  Continue to next breakpoint');
+    logger.log('  i, inspect          Show all variables');
+    logger.log('  i <node>            Show variables for a specific node');
+    logger.log('  b <node>            Add breakpoint');
+    logger.log('  rb <node>           Remove breakpoint');
+    logger.log('  bl                  List breakpoints');
+    logger.log('  set <node>.<port> <json>  Modify a variable');
+    logger.log('  q, quit             Abort debug session');
+    logger.log('  h, help             Show this help');
+}
+async function runDebugRepl(controller, execPromise, agentChannel, options) {
+    if (!options.json) {
+        logger.newline();
+        logger.section('Flow Weaver Debug');
+        logger.log('Type "h" for help.');
+    }
+    // Wait for the first pause
+    const firstResult = await Promise.race([
+        execPromise.then((r) => ({ type: 'completed', result: r })),
+        controller.onPause().then((state) => ({ type: 'paused', state })),
+    ]);
+    if (firstResult.type === 'completed') {
+        return firstResult.result.result;
+    }
+    let currentState = firstResult.state;
+    printDebugState(currentState);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        prompt: '> ',
+    });
+    return new Promise((resolve, reject) => {
+        let resolved = false;
+        function finish(value) {
+            if (resolved)
+                return;
+            resolved = true;
+            rl.close();
+            resolve(value);
+        }
+        function fail(err) {
+            if (resolved)
+                return;
+            resolved = true;
+            rl.close();
+            reject(err);
+        }
+        async function handleResume() {
+            const raceResult = await Promise.race([
+                execPromise.then((r) => ({ type: 'completed', result: r })),
+                controller.onPause().then((state) => ({ type: 'paused', state })),
+                agentChannel.onPause().then((req) => ({ type: 'agent_paused', request: req })),
+            ]);
+            if (raceResult.type === 'completed') {
+                const execResult = raceResult.result;
+                if (!options.json) {
+                    logger.success(`\nWorkflow completed in ${execResult.executionTime}ms`);
+                }
+                finish(execResult.result);
+            }
+            else if (raceResult.type === 'paused') {
+                currentState = raceResult.state;
+                printDebugState(currentState);
+                rl.prompt();
+            }
+            else {
+                // Agent pause during debug: prompt user for agent input
+                const request = raceResult.request;
+                const label = request.prompt || `Agent "${request.agentId}" is requesting input`;
+                logger.log(`\n[waitForAgent] ${label}`);
+                rl.question('Agent response (JSON): ', (answer) => {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(answer);
+                    }
+                    catch {
+                        parsed = { response: answer };
+                    }
+                    agentChannel.resume(parsed);
+                    // Re-race after agent resume
+                    handleResume().catch(fail);
+                });
+            }
+        }
+        rl.on('line', async (line) => {
+            const input = line.trim();
+            if (!input) {
+                rl.prompt();
+                return;
+            }
+            const parts = input.split(/\s+/);
+            const cmd = parts[0].toLowerCase();
+            try {
+                switch (cmd) {
+                    case 's':
+                    case 'step':
+                        controller.resume({ type: 'step' });
+                        await handleResume();
+                        break;
+                    case 'c':
+                    case 'continue':
+                        controller.resume({ type: 'continue' });
+                        await handleResume();
+                        break;
+                    case 'cb':
+                        controller.resume({ type: 'continueToBreakpoint' });
+                        await handleResume();
+                        break;
+                    case 'i':
+                    case 'inspect': {
+                        const nodeId = parts[1];
+                        if (nodeId) {
+                            const prefix = `${nodeId}:`;
+                            let found = false;
+                            for (const [key, value] of Object.entries(currentState.variables)) {
+                                if (key.startsWith(prefix)) {
+                                    found = true;
+                                    const portKey = key.substring(prefix.length);
+                                    logger.log(`  ${nodeId}.${portKey} = ${JSON.stringify(value)}`);
+                                }
+                            }
+                            if (!found) {
+                                logger.log(`  No variables found for node "${nodeId}"`);
+                            }
+                        }
+                        else {
+                            // Group by node
+                            const byNode = new Map();
+                            for (const [key, value] of Object.entries(currentState.variables)) {
+                                const firstColon = key.indexOf(':');
+                                if (firstColon === -1)
+                                    continue;
+                                const node = key.substring(0, firstColon);
+                                if (!byNode.has(node))
+                                    byNode.set(node, {});
+                                byNode.get(node)[key.substring(firstColon + 1)] = value;
+                            }
+                            for (const [node, vars] of byNode) {
+                                logger.log(`  ${node}:`);
+                                for (const [port, value] of Object.entries(vars)) {
+                                    const valueStr = JSON.stringify(value);
+                                    const display = valueStr.length > 60 ? valueStr.substring(0, 57) + '...' : valueStr;
+                                    logger.log(`    ${port} = ${display}`);
+                                }
+                            }
+                        }
+                        rl.prompt();
+                        break;
+                    }
+                    case 'b': {
+                        const nodeId = parts[1];
+                        if (!nodeId) {
+                            logger.log('Usage: b <nodeId>');
+                        }
+                        else {
+                            controller.addBreakpoint(nodeId);
+                            logger.log(`Breakpoint added: ${nodeId}`);
+                        }
+                        rl.prompt();
+                        break;
+                    }
+                    case 'rb': {
+                        const nodeId = parts[1];
+                        if (!nodeId) {
+                            logger.log('Usage: rb <nodeId>');
+                        }
+                        else {
+                            controller.removeBreakpoint(nodeId);
+                            logger.log(`Breakpoint removed: ${nodeId}`);
+                        }
+                        rl.prompt();
+                        break;
+                    }
+                    case 'bl':
+                        logger.log(`Breakpoints: ${controller.getBreakpoints().join(', ') || '(none)'}`);
+                        rl.prompt();
+                        break;
+                    case 'set': {
+                        // set node.port <json_value>
+                        const target = parts[1];
+                        const jsonValue = parts.slice(2).join(' ');
+                        if (!target || !jsonValue) {
+                            logger.log('Usage: set <node>.<port> <json_value>');
+                            rl.prompt();
+                            break;
+                        }
+                        const dotIdx = target.indexOf('.');
+                        if (dotIdx === -1) {
+                            logger.log('Target must be in format: node.port');
+                            rl.prompt();
+                            break;
+                        }
+                        const nodeId = target.substring(0, dotIdx);
+                        const portName = target.substring(dotIdx + 1);
+                        let value;
+                        try {
+                            value = JSON.parse(jsonValue);
+                        }
+                        catch {
+                            logger.log(`Invalid JSON value: ${jsonValue}`);
+                            rl.prompt();
+                            break;
+                        }
+                        // Find the key in current variables
+                        const prefix = `${nodeId}:${portName}:`;
+                        let foundKey = null;
+                        let latestIdx = -1;
+                        for (const key of Object.keys(currentState.variables)) {
+                            if (key.startsWith(prefix)) {
+                                const idx = parseInt(key.substring(prefix.length), 10);
+                                if (idx > latestIdx) {
+                                    latestIdx = idx;
+                                    foundKey = key;
+                                }
+                            }
+                        }
+                        if (!foundKey) {
+                            logger.log(`Variable not found: ${nodeId}.${portName}`);
+                            rl.prompt();
+                            break;
+                        }
+                        controller.setVariable(foundKey, value);
+                        currentState.variables[foundKey] = value;
+                        logger.log(`Set ${nodeId}.${portName} = ${JSON.stringify(value)}`);
+                        rl.prompt();
+                        break;
+                    }
+                    case 'q':
+                    case 'quit':
+                        controller.resume({ type: 'abort' });
+                        finish(undefined);
+                        break;
+                    case 'h':
+                    case 'help':
+                        printDebugHelp();
+                        rl.prompt();
+                        break;
+                    default:
+                        logger.log(`Unknown command: ${cmd}. Type "h" for help.`);
+                        rl.prompt();
+                }
+            }
+            catch (err) {
+                if (!resolved) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (msg.includes('aborted')) {
+                        logger.log('Debug session aborted.');
+                        finish(undefined);
+                    }
+                    else {
+                        logger.error(`Error: ${msg}`);
+                        rl.prompt();
+                    }
+                }
+            }
+        });
+        rl.on('close', () => {
+            if (!resolved) {
+                finish(undefined);
+            }
+        });
+        rl.prompt();
+    });
+}
 function promptForInput(question) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({

package/dist/cli/commands/tunnel.d.ts

@@ -1,20 +1,19 @@
 /**
- * tunnel command — Relay Studio RPC calls from cloud to a local dev server.
+ * tunnel command — Self-contained tunnel for cloud Studio.
  *
- * 1. Connects to the local server via Socket.IO (same as listen command).
- * 2. Opens a WebSocket to the cloud server's /api/tunnel endpoint.
- * 3. Relays tunnel:request messages from cloud → local Socket.IO → cloud.
+ * Handles all RPC methods locally using Node.js fs and the
+ * @synergenius/flow-weaver AST API.  No local server required.
+ *
+ * 1. Opens a WebSocket to the cloud server's /api/tunnel endpoint.
+ * 2. Dispatches RPC calls directly to local handler functions.
  */
-import { io as socketIO } from 'socket.io-client';
 import WebSocket from 'ws';
 export interface TunnelOptions {
     key: string;
     cloud?: string;
-    server?: string;
+    dir?: string;
     /** Override WebSocket factory (for testing) */
     createWs?: (url: string) => WebSocket;
-    /** Override socket.io-client factory (for testing) */
-    ioFactory?: typeof socketIO;
 }
 export declare function tunnelCommand(options: TunnelOptions): Promise<void>;
 //# sourceMappingURL=tunnel.d.ts.map