@synergenius/flow-weaver 0.10.12 → 0.12.0

package/dist/generator/unified.js

@@ -109,6 +109,18 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
         lines.push(`  const ctx = new GeneratedExecutionContext(${asyncArg}, __effectiveDebugger__, __abortSignal__);`);
     }
     lines.push('');
+    // Debug controller: step-through debugging and checkpoint/resume
+    // In production mode, no controller is emitted. In dev mode, the controller
+    // resolves from globalThis (injected by executor) or falls back to a no-op.
+    if (!production) {
+        lines.push(`  // Debug controller for step-through debugging and checkpoint/resume`);
+        lines.push(`  const __ctrl__: TDebugController = (`);
+        lines.push(`    typeof globalThis !== 'undefined' && (globalThis as any).__fw_debug_controller__`);
+        lines.push(`      ? (globalThis as any).__fw_debug_controller__`);
+        lines.push(`      : { beforeNode: () => true, afterNode: () => {} }`);
+        lines.push(`  );`);
+        lines.push('');
+    }
     lines.push(`  const startIdx = ctx.addExecution('${RESERVED_NODE_NAMES.START}');`);
     Object.keys(extractStartPorts(workflow)).forEach((portName) => {
         const setCall = isAsync ? `await ctx.setVariable` : `ctx.setVariable`;
@@ -335,7 +347,7 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
             const group = parallelGroupOf.get(instanceId);
             const ungeneratedGroup = group.filter((id) => !generatedNodes.has(id));
             if (ungeneratedGroup.length >= 2) {
-                generateParallelGroupWithContext(ungeneratedGroup, workflow, nodeTypes, availableVars, lines, generatedNodes, '  ', isAsync, 'ctx', bundleMode, branchingNodes);
+                generateParallelGroupWithContext(ungeneratedGroup, workflow, nodeTypes, availableVars, lines, generatedNodes, '  ', isAsync, 'ctx', bundleMode, branchingNodes, production);
                 // Generate scoped children for each parallel node
                 for (const parallelNodeId of ungeneratedGroup) {
                     const inst = workflow.instances.find((i) => i.id === parallelNodeId);
@@ -344,7 +356,7 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
                     const nt = nodeTypes.find((n) => n.name === inst.nodeType || n.functionName === inst.nodeType);
                     if (!nt)
                         continue;
-                    generateScopedChildrenExecution(inst, nt, workflow, nodeTypes, generatedNodes, availableVars, lines, '  ', branchingNodes, branchRegions, isAsync, bundleMode);
+                    generateScopedChildrenExecution(inst, nt, workflow, nodeTypes, generatedNodes, availableVars, lines, '  ', branchingNodes, branchRegions, isAsync, bundleMode, production);
                 }
                 return;
             }
@@ -377,7 +389,7 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
                         chainNeedsClose = true;
                     }
                 }
-                generateBranchingChainCode(branchingChains.get(instanceId), workflow, nodeTypes, branchingNodes, branchRegions, availableVars, generatedNodes, lines, chainIndent, isAsync, 'ctx', bundleMode, branchingNodesNeedingSuccessFlag);
+                generateBranchingChainCode(branchingChains.get(instanceId), workflow, nodeTypes, branchingNodes, branchRegions, availableVars, generatedNodes, lines, chainIndent, isAsync, 'ctx', bundleMode, branchingNodesNeedingSuccessFlag, production);
                 if (chainNeedsClose) {
                     lines.push(`  }`);
                 }
@@ -404,7 +416,7 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
                     branchNeedsClose = true;
                 }
             }
-            generateBranchingNodeCode(instance, nodeType, workflow, nodeTypes, branchRegions.get(instanceId), availableVars, generatedNodes, lines, branchIndent, false, branchingNodes, branchRegions, isAsync, 'ctx', bundleMode, new Set(), branchingNodesNeedingSuccessFlag.has(instanceId));
+            generateBranchingNodeCode(instance, nodeType, workflow, nodeTypes, branchRegions.get(instanceId), availableVars, generatedNodes, lines, branchIndent, false, branchingNodes, branchRegions, isAsync, 'ctx', bundleMode, new Set(), branchingNodesNeedingSuccessFlag.has(instanceId), production);
             if (branchNeedsClose) {
                 lines.push(`  }`);
             }
@@ -412,7 +424,7 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
             region.successNodes.forEach((n) => generatedNodes.add(n));
             region.failureNodes.forEach((n) => generatedNodes.add(n));
             // Check if this node creates a scope and generate scoped children
-            generateScopedChildrenExecution(instance, nodeType, workflow, nodeTypes, generatedNodes, availableVars, lines, '  ', branchingNodes, branchRegions, isAsync, bundleMode);
+            generateScopedChildrenExecution(instance, nodeType, workflow, nodeTypes, generatedNodes, availableVars, lines, '  ', branchingNodes, branchRegions, isAsync, bundleMode, production);
         }
         else {
             const belongsToBranch = Array.from(branchRegions.values()).some((region) => region.successNodes.has(instanceId) || region.failureNodes.has(instanceId));
@@ -425,11 +437,11 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
                 generateNodeCallWithContext(instance, nodeType, workflow, availableVars, lines, nodeTypes, '  ', isAsync, nodeUseConst, undefined, // instanceParent
                 'ctx', // ctxVar
                 bundleMode, false, // skipExecuteGuard
-                branchingNodes // for port-aware STEP guards
-                );
+                branchingNodes, // for port-aware STEP guards
+                production);
                 generatedNodes.add(instanceId);
                 // Check if this node creates a scope and generate scoped children
-                generateScopedChildrenExecution(instance, nodeType, workflow, nodeTypes, generatedNodes, availableVars, lines, '  ', branchingNodes, branchRegions, isAsync, bundleMode);
+                generateScopedChildrenExecution(instance, nodeType, workflow, nodeTypes, generatedNodes, availableVars, lines, '  ', branchingNodes, branchRegions, isAsync, bundleMode, production);
             }
         }
     });
@@ -578,7 +590,7 @@ export function generateControlFlowWithExecutionContext(workflow, nodeTypes, isA
 /**
  * Helper function to generate scoped children execution for nodes that create scopes
  */
-function generateScopedChildrenExecution(parentInstance, parentNodeType, workflow, allNodeTypes, generatedNodes, availableVars, lines, indent, branchingNodes, branchRegions, isAsync, bundleMode = false) {
+function generateScopedChildrenExecution(parentInstance, parentNodeType, workflow, allNodeTypes, generatedNodes, availableVars, lines, indent, branchingNodes, branchRegions, isAsync, bundleMode = false, production = false) {
     // Check if this node creates a scope
     if (!parentNodeType.scope)
         return;
@@ -631,7 +643,7 @@ function generateScopedChildrenExecution(parentInstance, parentNodeType, workflo
         // Check if this child is a branching node
         if (branchingNodes.has(childInstanceId)) {
             generateBranchingNodeCode(childInstance, childNodeType, workflow, allNodeTypes, branchRegions.get(childInstanceId), availableVars, generatedNodes, lines, indent, false, branchingNodes, branchRegions, isAsync, scopedCtxVar, // Pass scoped context name
-            bundleMode);
+            bundleMode, new Set(), false, production);
             const region = branchRegions.get(childInstanceId);
             region.successNodes.forEach((n) => generatedNodes.add(n));
             region.failureNodes.forEach((n) => generatedNodes.add(n));
@@ -640,7 +652,9 @@ function generateScopedChildrenExecution(parentInstance, parentNodeType, workflo
             generateNodeCallWithContext(childInstance, childNodeType, workflow, availableVars, lines, allNodeTypes, indent, isAsync, false, // useConst = false - scoped children need let (referenced outside scope block)
             parentInstance.id, // instanceParent - parent node is const, no ! needed when referencing it
             scopedCtxVar, // Pass scoped context name
-            bundleMode);
+            bundleMode, false, // skipExecuteGuard
+            new Set(), // branchingNodes
+            production);
         }
         generatedNodes.add(childInstanceId);
     });
@@ -655,7 +669,7 @@ function generateScopedChildrenExecution(parentInstance, parentNodeType, workflo
  * Each node's execution code is wrapped in an async IIFE inside Promise.all.
  * The outer `let` variables for execution indices are assigned inside the IIFEs.
  */
-function generateParallelGroupWithContext(nodeIds, workflow, nodeTypes, availableVars, lines, generatedNodes, indent, isAsync, ctxVar, bundleMode, branchingNodes) {
+function generateParallelGroupWithContext(nodeIds, workflow, nodeTypes, availableVars, lines, generatedNodes, indent, isAsync, ctxVar, bundleMode, branchingNodes, production = false) {
     // Collect code buffers for each node
     const nodeBuffers = [];
     for (const nodeId of nodeIds) {
@@ -668,7 +682,7 @@ function generateParallelGroupWithContext(nodeIds, workflow, nodeTypes, availabl
         const nodeLines = [];
         generateNodeCallWithContext(instance, nodeType, workflow, availableVars, nodeLines, nodeTypes, `${indent}    `, // indent for inside the async IIFE
         isAsync, false, // useConst = false — outer let declarations
-        undefined, ctxVar, bundleMode, false, branchingNodes);
+        undefined, ctxVar, bundleMode, false, branchingNodes, production);
         nodeBuffers.push({ id: nodeId, lines: nodeLines });
     }
     // Fallback: if only 0-1 nodes remain, emit directly without Promise.all
@@ -816,7 +830,7 @@ function buildStepSourceCondition(sourceNode, sourcePort, branchingNodes) {
  *   if (A_success) { B code } else { CANCELLED for B,C and regions }
  *   if (A_success && B_success) { C code } else { CANCELLED for C and regions }
  */
-function generateBranchingChainCode(chain, workflow, nodeTypes, branchingNodes, branchRegions, availableVars, generatedNodes, lines, indent, isAsync, ctxVar, bundleMode, forceTrackSuccessNodes = new Set()) {
+function generateBranchingChainCode(chain, workflow, nodeTypes, branchingNodes, branchRegions, availableVars, generatedNodes, lines, indent, isAsync, ctxVar, bundleMode, forceTrackSuccessNodes = new Set(), production = false) {
     // Pre-declare success flags for all non-last chain nodes so they're
     // accessible across guard blocks (avoiding let-in-block scoping issues).
     // Also pre-declare for the last node if promoted nodes depend on its _success flag.
@@ -860,10 +874,10 @@ function generateBranchingChainCode(chain, workflow, nodeTypes, branchingNodes,
             lines.push(`${indent}if (${guardCondition}) {`);
         }
         const nodeIndent = hasGuard ? indent + '  ' : indent;
-        generateBranchingNodeCode(instance, nodeType, workflow, nodeTypes, effectiveRegion, availableVars, generatedNodes, lines, nodeIndent, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, preDeclaredFlags, !isLast || forceTrackSuccessNodes.has(chain[i]) // forceTrackSuccess for non-last chain nodes or nodes with promoted dependents
-        );
+        generateBranchingNodeCode(instance, nodeType, workflow, nodeTypes, effectiveRegion, availableVars, generatedNodes, lines, nodeIndent, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, preDeclaredFlags, !isLast || forceTrackSuccessNodes.has(chain[i]), // forceTrackSuccess for non-last chain nodes or nodes with promoted dependents
+        production);
         // Generate scoped children for this chain node
-        generateScopedChildrenExecution(instance, nodeType, workflow, nodeTypes, generatedNodes, availableVars, lines, nodeIndent, branchingNodes, branchRegions, isAsync, bundleMode);
+        generateScopedChildrenExecution(instance, nodeType, workflow, nodeTypes, generatedNodes, availableVars, lines, nodeIndent, branchingNodes, branchRegions, isAsync, bundleMode, production);
         if (hasGuard) {
             lines.push(`${indent}} else {`);
             // Emit CANCELLED for this node and all remaining chain nodes + their regions
@@ -890,10 +904,29 @@ function generateBranchingChainCode(chain, workflow, nodeTypes, branchingNodes,
 }
 function generateBranchingNodeCode(instance, branchNode, workflow, allNodeTypes, region, availableVars, generatedNodes, lines, indent, _generateReturns = true, // DEPRECATED: always false, kept for signature compat
 branchingNodes, branchRegions, isAsync, ctxVar = 'ctx', // Context variable name (for scoped contexts)
-bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = false) {
+bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = false, production = false) {
     const instanceId = instance.id;
     const safeId = toValidIdentifier(instanceId);
     const functionName = branchNode.functionName;
+    // Debug controller: beforeNode hook for branching nodes
+    const emitDebugHooks = !production;
+    const outerIndent = indent;
+    // Only declare success flag if there are downstream nodes
+    const hasSuccessDownstream = region.successNodes.size > 0;
+    const hasFailureDownstream = region.failureNodes.size > 0;
+    const hasDownstream = hasSuccessDownstream || hasFailureDownstream;
+    // Track success flag when there are downstream nodes OR when chain code needs it
+    const trackSuccess = hasDownstream || forceTrackSuccess;
+    if (emitDebugHooks) {
+        // Hoist success flag declaration before the if block so it remains in scope
+        // for downstream branching code that runs after the if/else.
+        if (trackSuccess && !preDeclaredSuccessFlags.has(safeId)) {
+            lines.push(`${indent}let ${safeId}_success = false;`);
+        }
+        const awaitHook = isAsync ? 'await ' : '';
+        lines.push(`${indent}if (${awaitHook}__ctrl__.beforeNode('${instanceId}', ${ctxVar})) {`);
+        indent = `${indent}  `;
+    }
     lines.push(`${indent}${ctxVar}.checkAborted('${instanceId}');`);
     lines.push(`${indent}${safeId}Idx = ${ctxVar}.addExecution('${instanceId}');`);
     lines.push(`${indent}if (typeof globalThis !== 'undefined') (globalThis as any).__fw_current_node_id__ = '${instanceId}';`);
@@ -904,15 +937,9 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
     lines.push(`${indent}  status: 'RUNNING',`);
     lines.push(`${indent}});`);
     lines.push('');
-    // Only declare success flag if there are downstream nodes
-    const hasSuccessDownstream = region.successNodes.size > 0;
-    const hasFailureDownstream = region.failureNodes.size > 0;
-    const hasDownstream = hasSuccessDownstream || hasFailureDownstream;
-    // Track success flag when there are downstream nodes OR when chain code needs it
-    const trackSuccess = hasDownstream || forceTrackSuccess;
     if (trackSuccess) {
-        if (preDeclaredSuccessFlags.has(safeId)) {
-            // Flag was pre-declared by chain code — use assignment, not declaration
+        if (preDeclaredSuccessFlags.has(safeId) || emitDebugHooks) {
+            // Flag was pre-declared (by chain code or hoisted for debug hooks) — assignment only
             lines.push(`${indent}${safeId}_success = false;`);
         }
         else {
@@ -1051,6 +1078,11 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
     lines.push(`${indent}    executionIndex: ${safeId}Idx,`);
     lines.push(`${indent}    status: 'SUCCEEDED',`);
     lines.push(`${indent}  });`);
+    // Debug controller: afterNode hook for branching nodes
+    if (emitDebugHooks) {
+        const awaitHook = isAsync ? 'await ' : '';
+        lines.push(`${indent}  ${awaitHook}__ctrl__.afterNode('${instanceId}', ${ctxVar});`);
+    }
     // Use onSuccess from result to determine control flow
     // For expression nodes, onSuccess is always true here (catch handles failure)
     if (trackSuccess) {
@@ -1087,6 +1119,20 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
     // Re-throw the error to propagate it up (important for recursive workflows)
     lines.push(`${indent}  throw error;`);
     lines.push(`${indent}}`);
+    // Close the debug controller beforeNode if block for the node's own execution.
+    // The downstream branching must be outside the if block so it runs even when
+    // the node is skipped (checkpoint resume).
+    if (emitDebugHooks) {
+        lines.push(`${outerIndent}} else {`);
+        // Node was skipped (checkpoint resume). Controller already restored outputs
+        // into ctx, but we need local vars for downstream branching.
+        lines.push(`${outerIndent}  ${safeId}Idx = ${ctxVar}.addExecution('${instanceId}');`);
+        if (trackSuccess) {
+            lines.push(`${outerIndent}  ${safeId}_success = true;`);
+        }
+        lines.push(`${outerIndent}}`);
+        indent = outerIndent; // Restore indent level for downstream code
+    }
     lines.push('');
     // Only generate if/else if there are downstream nodes
     if (hasDownstream) {
@@ -1112,7 +1158,7 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
                 return;
             if (branchingNodes.has(instanceId)) {
                 const nestedRegion = branchRegions.get(instanceId);
-                generateBranchingNodeCode(inst, nodeType, workflow, allNodeTypes, nestedRegion, successVars, generatedNodes, lines, `${indent}  `, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode);
+                generateBranchingNodeCode(inst, nodeType, workflow, allNodeTypes, nestedRegion, successVars, generatedNodes, lines, `${indent}  `, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, new Set(), false, production);
                 successExecutedNodes.push(instanceId);
                 nestedRegion.successNodes.forEach((n) => successExecutedNodes.push(n));
                 nestedRegion.failureNodes.forEach((n) => successExecutedNodes.push(n));
@@ -1120,8 +1166,8 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
             else {
                 generateNodeCallWithContext(inst, nodeType, workflow, successVars, lines, allNodeTypes, `${indent}  `, isAsync, false, // useConst
                 undefined, // instanceParent
-                ctxVar, bundleMode, true // skipExecuteGuard — inside branch, execute is guaranteed by if/else
-                );
+                ctxVar, bundleMode, true, // skipExecuteGuard — inside branch, execute is guaranteed by if/else
+                branchingNodes, production);
                 Object.keys(nodeType.outputs).forEach((portName) => {
                     successVars.set(`${instanceId}.${portName}`, `${toValidIdentifier(instanceId)}Result.${portName}`);
                 });
@@ -1153,7 +1199,7 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
                     return;
                 if (branchingNodes.has(instanceId)) {
                     const nestedRegion = branchRegions.get(instanceId);
-                    generateBranchingNodeCode(inst, nodeType, workflow, allNodeTypes, nestedRegion, failureVars, generatedNodes, lines, `${indent}  `, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode);
+                    generateBranchingNodeCode(inst, nodeType, workflow, allNodeTypes, nestedRegion, failureVars, generatedNodes, lines, `${indent}  `, false, branchingNodes, branchRegions, isAsync, ctxVar, bundleMode, new Set(), false, production);
                     failureExecutedNodes.push(instanceId);
                     nestedRegion.successNodes.forEach((n) => failureExecutedNodes.push(n));
                     nestedRegion.failureNodes.forEach((n) => failureExecutedNodes.push(n));
@@ -1161,8 +1207,8 @@ bundleMode = false, preDeclaredSuccessFlags = new Set(), forceTrackSuccess = fal
                 else {
                     generateNodeCallWithContext(inst, nodeType, workflow, failureVars, lines, allNodeTypes, `${indent}  `, isAsync, false, // useConst
                     undefined, // instanceParent
-                    ctxVar, bundleMode, true // skipExecuteGuard — inside branch, execute is guaranteed by if/else
-                    );
+                    ctxVar, bundleMode, true, // skipExecuteGuard — inside branch, execute is guaranteed by if/else
+                    branchingNodes, production);
                     Object.keys(nodeType.outputs).forEach((portName) => {
                         failureVars.set(`${instanceId}.${portName}`, `${toValidIdentifier(instanceId)}Result.${portName}`);
                     });
@@ -1318,7 +1364,8 @@ instanceParent, // Parent node ID for scope children (parent is const, no ! need
 ctxVar = 'ctx', // Context variable name (for scoped contexts)
 bundleMode = false, // Bundle mode uses params object pattern for wrapper functions
 skipExecuteGuard = false, // Skip execute port STEP guard (for nodes inside branch blocks)
-branchingNodes = new Set() // Branching nodes set for port-aware STEP guards
+branchingNodes = new Set(), // Branching nodes set for port-aware STEP guards
+production = false // When false, emit debug controller hooks (beforeNode/afterNode)
 ) {
     const instanceId = instance.id;
     const safeId = toValidIdentifier(instanceId);
@@ -1458,7 +1505,24 @@ branchingNodes = new Set() // Branching nodes set for port-aware STEP guards
             }
         }
     }
-    const varDecl = useConst ? 'const ' : '';
+    // Debug controller: beforeNode hook (step-through / checkpoint resume)
+    // When enabled, wraps the entire node execution in if(await __ctrl__.beforeNode(...))
+    // so checkpoint resume can skip already-completed nodes.
+    const emitDebugHooks = !production;
+    const outerIndent = indent; // preserve for closing brace
+    if (emitDebugHooks) {
+        // When useConst=true, the Idx variable would normally be declared with const
+        // inside the node execution block. Since debug hooks wrap that in if/else,
+        // we must hoist the declaration before the if block to keep it in scope.
+        if (useConst) {
+            lines.push(`${indent}let ${safeId}Idx: number;`);
+        }
+        const awaitHook = isAsync ? 'await ' : '';
+        lines.push(`${indent}if (${awaitHook}__ctrl__.beforeNode('${instanceId}', ${ctxVar})) {`);
+        indent = `${indent}  `;
+    }
+    // When debug hooks hoist the declaration, we use assignment only inside the block.
+    const varDecl = (useConst && !emitDebugHooks) ? 'const ' : '';
     lines.push(`${indent}${ctxVar}.checkAborted('${instanceId}');`);
     lines.push(`${indent}${varDecl}${safeId}Idx = ${ctxVar}.addExecution('${instanceId}');`);
     lines.push(`${indent}if (typeof globalThis !== 'undefined') (globalThis as any).__fw_current_node_id__ = '${instanceId}';`);
@@ -1628,6 +1692,11 @@ branchingNodes = new Set() // Branching nodes set for port-aware STEP guards
     lines.push(`${indent}    executionIndex: ${safeId}Idx,`);
     lines.push(`${indent}    status: 'SUCCEEDED',`);
     lines.push(`${indent}  });`);
+    // Debug controller: afterNode hook (checkpoint write, step pause)
+    if (emitDebugHooks) {
+        const awaitHook = isAsync ? 'await ' : '';
+        lines.push(`${indent}  ${awaitHook}__ctrl__.afterNode('${instanceId}', ${ctxVar});`);
+    }
     lines.push(`${indent}} catch (error: unknown) {`);
     lines.push(`${indent}  const isCancellation = CancellationError.isCancellationError(error);`);
     lines.push(`${indent}  ${ctxVar}.sendStatusChangedEvent({`);
@@ -1651,8 +1720,16 @@ branchingNodes = new Set() // Branching nodes set for port-aware STEP guards
     lines.push(`${indent}  }`);
     lines.push(`${indent}  throw error;`);
     lines.push(`${indent}}`);
+    // Close the debug controller beforeNode if block
+    if (emitDebugHooks) {
+        // Else block: node was skipped (checkpoint resume).
+        // Register execution so downstream nodes can reference {safeId}Idx.
+        lines.push(`${outerIndent}} else {`);
+        lines.push(`${outerIndent}  ${varDecl}${safeId}Idx = ${ctxVar}.addExecution('${instanceId}');`);
+        lines.push(`${outerIndent}}`);
+    }
     if (shouldIndent) {
-        const originalIndent = indent.slice(0, -2);
+        const originalIndent = outerIndent.slice(0, -2);
         lines.push(`${originalIndent}}`);
     }
 }

package/dist/mcp/debug-session.d.ts

@@ -0,0 +1,30 @@
+/**
+ * In-memory registry for active debug sessions.
+ * Mirrors the pattern of run-registry.ts but tracks DebugController state
+ * instead of AgentChannel state.
+ */
+import type { DebugController, DebugPauseState } from '../runtime/debug-controller.js';
+export interface DebugSession {
+    debugId: string;
+    filePath: string;
+    workflowName?: string;
+    controller: DebugController;
+    /** The still-pending execution promise. Resolves when workflow completes. */
+    executionPromise: Promise<unknown>;
+    createdAt: number;
+    /** Temp files to clean up when the session ends. */
+    tmpFiles: string[];
+    /** Most recent pause state (updated on each pause) */
+    lastPauseState?: DebugPauseState;
+}
+export declare function storeDebugSession(session: DebugSession): void;
+export declare function getDebugSession(debugId: string): DebugSession | undefined;
+export declare function removeDebugSession(debugId: string): void;
+export declare function listDebugSessions(): Array<{
+    debugId: string;
+    filePath: string;
+    workflowName?: string;
+    createdAt: number;
+    lastPauseState?: DebugPauseState;
+}>;
+//# sourceMappingURL=debug-session.d.ts.map

package/dist/mcp/debug-session.js

@@ -0,0 +1,25 @@
+/**
+ * In-memory registry for active debug sessions.
+ * Mirrors the pattern of run-registry.ts but tracks DebugController state
+ * instead of AgentChannel state.
+ */
+const debugSessions = new Map();
+export function storeDebugSession(session) {
+    debugSessions.set(session.debugId, session);
+}
+export function getDebugSession(debugId) {
+    return debugSessions.get(debugId);
+}
+export function removeDebugSession(debugId) {
+    debugSessions.delete(debugId);
+}
+export function listDebugSessions() {
+    return Array.from(debugSessions.values()).map((session) => ({
+        debugId: session.debugId,
+        filePath: session.filePath,
+        workflowName: session.workflowName,
+        createdAt: session.createdAt,
+        lastPauseState: session.lastPauseState,
+    }));
+}
+//# sourceMappingURL=debug-session.js.map

package/dist/mcp/index.d.ts

@@ -7,6 +7,7 @@ export { registerEditorTools } from './tools-editor.js';
 export { registerQueryTools } from './tools-query.js';
 export { registerTemplateTools } from './tools-template.js';
 export { registerPatternTools } from './tools-pattern.js';
+export { registerDebugTools } from './tools-debug.js';
 export { registerResources } from './resources.js';
 export { registerPrompts } from './prompts.js';
 export { startMcpServer, mcpServerCommand } from './server.js';

package/dist/mcp/index.js

@@ -6,6 +6,7 @@ export { registerEditorTools } from './tools-editor.js';
 export { registerQueryTools } from './tools-query.js';
 export { registerTemplateTools } from './tools-template.js';
 export { registerPatternTools } from './tools-pattern.js';
+export { registerDebugTools } from './tools-debug.js';
 export { registerResources } from './resources.js';
 export { registerPrompts } from './prompts.js';
 export { startMcpServer, mcpServerCommand } from './server.js';

package/dist/mcp/server.js

@@ -12,6 +12,8 @@ import { registerMarketplaceTools } from './tools-marketplace.js';
 import { registerDiagramTools } from './tools-diagram.js';
 import { registerDocsTools } from './tools-docs.js';
 import { registerModelTools } from './tools-model.js';
+import { registerDebugTools } from './tools-debug.js';
+import { registerContextTools } from './tools-context.js';
 import { registerResources } from './resources.js';
 import { registerPrompts } from './prompts.js';
 function parseEventFilterFromEnv() {
@@ -74,6 +76,8 @@ export async function startMcpServer(options) {
     registerDiagramTools(mcp);
     registerDocsTools(mcp);
     registerModelTools(mcp);
+    registerDebugTools(mcp);
+    registerContextTools(mcp);
     registerResources(mcp, connection, buffer);
     registerPrompts(mcp);
     // Connect transport (only in stdio MCP mode)

package/dist/mcp/tools-context.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerContextTools(mcp: McpServer): void;
+//# sourceMappingURL=tools-context.d.ts.map

package/dist/mcp/tools-context.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { buildContext } from '../context/index.js';
+import { makeToolResult, makeErrorResult } from './response-utils.js';
+export function registerContextTools(mcp) {
+    mcp.tool('fw_context', 'Generate a self-contained LLM context bundle with Flow Weaver documentation, grammar, and conventions. Use preset="core" for basics, "authoring" for writing workflows, "full" for everything, "ops" for CLI/deployment reference.', {
+        preset: z
+            .enum(['core', 'authoring', 'full', 'ops'])
+            .optional()
+            .default('core')
+            .describe('Topic preset'),
+        profile: z
+            .enum(['standalone', 'assistant'])
+            .optional()
+            .default('assistant')
+            .describe('standalone = full self-contained dump, assistant = assumes MCP tools available'),
+        topics: z
+            .string()
+            .optional()
+            .describe('Comma-separated topic slugs (overrides preset)'),
+        addTopics: z
+            .string()
+            .optional()
+            .describe('Comma-separated slugs to add to preset'),
+        includeGrammar: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Include EBNF annotation grammar section'),
+    }, async (args) => {
+        try {
+            const result = buildContext({
+                preset: args.preset,
+                profile: args.profile,
+                topics: args.topics ? args.topics.split(',').map((s) => s.trim()) : undefined,
+                addTopics: args.addTopics ? args.addTopics.split(',').map((s) => s.trim()) : undefined,
+                includeGrammar: args.includeGrammar,
+            });
+            return makeToolResult({
+                profile: result.profile,
+                topicCount: result.topicCount,
+                lineCount: result.lineCount,
+                topicSlugs: result.topicSlugs,
+                content: result.content,
+            });
+        }
+        catch (err) {
+            return makeErrorResult('CONTEXT_ERROR', `fw_context failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+//# sourceMappingURL=tools-context.js.map

package/dist/mcp/tools-debug.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDebugTools(mcp: McpServer): void;
+//# sourceMappingURL=tools-debug.d.ts.map