groundswell 0.0.3 → 1.0.0

package/dist/debugger/tree-debugger.d.ts

@@ -12,11 +12,38 @@ export declare class WorkflowTreeDebugger implements WorkflowObserver {
     readonly events: Observable<WorkflowEvent>;
     /** Node lookup map for quick access */
     private nodeMap;
+    /** Event history for persistence (only when persistEvents is true) */
+    private eventHistory;
+    /** Whether to persist events to memory */
+    private persistEvents;
+    /** Maximum event history size (optional, for memory management) */
+    private maxEventHistorySize?;
     /**
      * Create a tree debugger attached to a workflow
      * @param workflow The root workflow to debug
+     * @param options Configuration options
+     * @param options.persistEvents Whether to accumulate event history (default: false)
+     * @param options.maxEventHistorySize Maximum number of events to keep (optional, FIFO eviction)
+     *
+     * @example
+     * ```typescript
+     * // Without persistence (default)
+     * const debugger = new WorkflowTreeDebugger(workflow);
+     *
+     * // With persistence enabled
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     *
+     * // With persistence and size limit
+     * const debugger = new WorkflowTreeDebugger(workflow, {
+     *   persistEvents: true,
+     *   maxEventHistorySize: 10000,
+     * });
+     * ```
      */
-    constructor(workflow: Workflow);
+    constructor(workflow: Workflow, options?: {
+        persistEvents?: boolean;
+        maxEventHistorySize?: number;
+    });
     /**
      * Build node lookup map recursively
      */
@@ -28,6 +55,12 @@ export declare class WorkflowTreeDebugger implements WorkflowObserver {
      */
     private removeSubtreeNodes;
     onLog(_entry: LogEntry): void;
+    /**
+     * Handle workflow events from observer interface
+     * Captures events for history if persistence enabled, handles structural updates, forwards to stream
+     *
+     * @param event - The workflow event to handle
+     */
     onEvent(event: WorkflowEvent): void;
     onStateUpdated(_node: WorkflowNode): void;
     onTreeChanged(root: WorkflowNode): void;
@@ -67,5 +100,141 @@ export declare class WorkflowTreeDebugger implements WorkflowObserver {
         totalEvents: number;
     };
     private collectStats;
+    /**
+     * Get the accumulated event history
+     * Returns a copy to prevent external modification
+     *
+     * @returns Copy of event history array, or empty array if persistence disabled
+     *
+     * @example
+     * ```typescript
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * const events = debugger.getEventHistory();
+     * console.log(`Captured ${events.length} events`);
+     * ```
+     */
+    getEventHistory(): WorkflowEvent[];
+    /**
+     * Serialize a WorkflowEvent to JSON-safe format
+     * Extracts only primitive fields to avoid circular references in WorkflowNode objects
+     *
+     * **Strategy:**
+     * - Extract nodeId and nodeName from WorkflowNode references
+     * - Skip WorkflowNode.parent, WorkflowNode.children (circular refs)
+     * - Skip WorkflowError.original (could be circular)
+     * - Add timestamp for chronological ordering
+     *
+     * **Circular Reference Handling:**
+     * - WorkflowNode has bidirectional links (parent ↔ children)
+     * - WorkflowNode.events[] contains WorkflowEvents that reference WorkflowNodes
+     * - JSON.stringify would throw TypeError without selective extraction
+     *
+     * @param event - The workflow event to serialize
+     * @returns JSON-safe object with primitive fields only
+     *
+     * @example
+     * ```typescript
+     * const event: WorkflowEvent = {
+     *   type: 'stateSnapshot',
+     *   node: { id: 'wf-123', name: 'MyWorkflow', ... }
+     * };
+     * const serialized = serializeEvent(event);
+     * // { type: 'stateSnapshot', timestamp: 1234567890, nodeId: 'wf-123', nodeName: 'MyWorkflow', stateSnapshot: {...} }
+     * ```
+     */
+    private serializeEvent;
+    /**
+     * Save event history to a JSON file
+     * Serializes events to avoid circular references and writes to disk
+     *
+     * **Serialization Strategy:**
+     * - Uses serializeEvent() to extract primitive fields only
+     * - Avoids circular references in WorkflowNode objects
+     * - Adds timestamp for chronological ordering
+     *
+     * **Error Handling:**
+     * - Throws descriptive errors for file system issues
+     * - Does not modify internal event history on failure
+     *
+     * @param path - File path to write event history
+     * @throws {Error} If file cannot be written (permission denied, disk full, etc.)
+     * @throws {Error} If event persistence is not enabled
+     *
+     * @example
+     * ```typescript
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * await debugger.saveEventHistory('./workflow-execution.json');
+     * ```
+     */
+    saveEventHistory(path: string): Promise<void>;
+    /**
+     * Load event history from a JSON file
+     * Static method that can be called without instantiating WorkflowTreeDebugger
+     *
+     * **Error Handling:**
+     * - Throws descriptive errors for file system issues
+     * - Throws descriptive errors for invalid JSON
+     *
+     * @param path - File path to read event history from
+     * @returns Parsed event array (unknown[] - caller should validate structure)
+     * @throws {Error} If file does not exist
+     * @throws {Error} If file cannot be read (permission denied, etc.)
+     * @throws {Error} If file contains invalid JSON
+     *
+     * @example
+     * ```typescript
+     * const events = await WorkflowTreeDebugger.loadEventHistory('./workflow-execution.json');
+     *
+     * // Use with WorkflowEventReplayer
+     * const replayer = new WorkflowEventReplayer();
+     * const tree = replayer.replay(events as WorkflowEvent[]);
+     * ```
+     */
+    static loadEventHistory(path: string): Promise<unknown[]>;
+    /**
+     * Replay workflow execution from saved event history file.
+     *
+     * This is a convenience method that combines loadEventHistory and
+     * WorkflowEventReplayer.replay() for one-call restoration of workflow trees.
+     *
+     * **Use Case**: Time-travel debugging - reconstruct workflow tree from saved events
+     * to inspect execution after completion without requiring the live workflow instance.
+     *
+     * **Workflow**:
+     * 1. Load events from file using loadEventHistory()
+     * 2. Create WorkflowEventReplayer instance
+     * 3. Replay events and return reconstructed tree
+     *
+     * **Error Handling**:
+     * - Throws descriptive errors for file operations (delegated to loadEventHistory)
+     * - Wraps replay errors with file path context
+     *
+     * **Returns**: Read-only WorkflowNode tree (no live workflow attached)
+     *
+     * @param path - File path to saved event history JSON file
+     * @returns Reconstructed workflow tree root node
+     * @throws {Error} If file cannot be read or parsed
+     * @throws {Error} If events cannot be replayed (empty events, no root established)
+     *
+     * @example
+     * ```typescript
+     * // Save event history during execution
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * await debugger.saveEventHistory('./workflow-events.json');
+     *
+     * // Later, replay the events to reconstruct the tree
+     * const tree = await WorkflowTreeDebugger.replay('./workflow-events.json');
+     * console.log(`Restored tree with ${tree.children.length} children`);
+     *
+     * // Use debugger instance to inspect the reconstructed tree
+     * const debugInstance = new WorkflowTreeDebugger({ getNode: () => tree });
+     * console.log(debugInstance.toTreeString(tree));
+     * console.log(debugInstance.getStats());
+     * ```
+     */
+    static replay(path: string): Promise<WorkflowNode>;
 }
 //# sourceMappingURL=tree-debugger.d.ts.map

package/dist/debugger/tree-debugger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree-debugger.d.ts","sourceRoot":"","sources":["../../src/debugger/tree-debugger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACT,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAapD;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,qCAAqC;IACrC,OAAO,CAAC,IAAI,CAAe;IAE3B,2CAA2C;IAC3C,SAAgB,MAAM,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;IAElD,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAAwC;IAEvD;;;OAGG;gBACS,QAAQ,EAAE,QAAQ;IAW9B;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAI7B,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IA2BnC,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAIzC,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAUvC;;OAEG;IACH,OAAO,IAAI,YAAY;IAIvB;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI7C;;;OAGG;IACH,YAAY,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM;IAIzC;;OAEG;IACH,OAAO,CAAC,UAAU;IA8BlB;;;OAGG;IACH,WAAW,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM;IAiBxC;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB;IAYD,OAAO,CAAC,YAAY;CAarB"}
+{"version":3,"file":"tree-debugger.d.ts","sourceRoot":"","sources":["../../src/debugger/tree-debugger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACT,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAepD;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,qCAAqC;IACrC,OAAO,CAAC,IAAI,CAAe;IAE3B,2CAA2C;IAC3C,SAAgB,MAAM,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;IAElD,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAAwC;IAEvD,sEAAsE;IACtE,OAAO,CAAC,YAAY,CAAuB;IAE3C,0CAA0C;IAC1C,OAAO,CAAC,aAAa,CAAkB;IAEvC,mEAAmE;IACnE,OAAO,CAAC,mBAAmB,CAAC,CAAS;IAErC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBAED,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE;IAqBrE;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAI7B;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAuCnC,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAIzC,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAUvC;;OAEG;IACH,OAAO,IAAI,YAAY;IAIvB;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI7C;;;OAGG;IACH,YAAY,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM;IAIzC;;OAEG;IACH,OAAO,CAAC,UAAU;IA8BlB;;;OAGG;IACH,WAAW,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM;IAiBxC;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB;IAYD,OAAO,CAAC,YAAY;IAkBpB;;;;;;;;;;;;;OAaG;IACH,eAAe,IAAI,aAAa,EAAE;IAQlC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,cAAc;IAiLtB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACU,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IA2C/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;WACU,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAkBzD"}

package/dist/debugger/tree-debugger.js

@@ -1,4 +1,6 @@
 import { Observable } from '../utils/observable.js';
+import { writeFile, readFile } from 'fs/promises';
+import { WorkflowEventReplayer } from './event-replayer.js';
 /**
  * Status symbols for tree visualization
  */
@@ -20,13 +22,44 @@ export class WorkflowTreeDebugger {
     events;
     /** Node lookup map for quick access */
     nodeMap = new Map();
+    /** Event history for persistence (only when persistEvents is true) */
+    eventHistory = [];
+    /** Whether to persist events to memory */
+    persistEvents = false;
+    /** Maximum event history size (optional, for memory management) */
+    maxEventHistorySize;
     /**
      * Create a tree debugger attached to a workflow
      * @param workflow The root workflow to debug
+     * @param options Configuration options
+     * @param options.persistEvents Whether to accumulate event history (default: false)
+     * @param options.maxEventHistorySize Maximum number of events to keep (optional, FIFO eviction)
+     *
+     * @example
+     * ```typescript
+     * // Without persistence (default)
+     * const debugger = new WorkflowTreeDebugger(workflow);
+     *
+     * // With persistence enabled
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     *
+     * // With persistence and size limit
+     * const debugger = new WorkflowTreeDebugger(workflow, {
+     *   persistEvents: true,
+     *   maxEventHistorySize: 10000,
+     * });
+     * ```
      */
-    constructor(workflow) {
+    constructor(workflow, options) {
         this.root = workflow.getNode();
         this.events = new Observable();
+        // Extract options with defaults
+        this.persistEvents = options?.persistEvents ?? false;
+        this.maxEventHistorySize = options?.maxEventHistorySize;
+        // Initialize event history if persistence enabled
+        if (this.persistEvents) {
+            this.eventHistory = [];
+        }
         // Build initial node map
         this.buildNodeMap(this.root);
         // Register as observer on the workflow
@@ -68,7 +101,22 @@ export class WorkflowTreeDebugger {
     onLog(_entry) {
         // Events are forwarded through the event stream
     }
+    /**
+     * Handle workflow events from observer interface
+     * Captures events for history if persistence enabled, handles structural updates, forwards to stream
+     *
+     * @param event - The workflow event to handle
+     */
     onEvent(event) {
+        // Capture event for history if persistence enabled
+        if (this.persistEvents) {
+            // Handle max size limit (FIFO eviction)
+            if (this.maxEventHistorySize &&
+                this.eventHistory.length >= this.maxEventHistorySize) {
+                this.eventHistory.shift(); // Remove oldest event
+            }
+            this.eventHistory.push(event);
+        }
         // Handle structural events with incremental updates
         switch (event.type) {
             case 'childAttached':
@@ -194,5 +242,379 @@ export class WorkflowTreeDebugger {
             this.collectStats(child, stats);
         }
     }
+    // ============================================================
+    // Event Persistence API
+    // ============================================================
+    /**
+     * Get the accumulated event history
+     * Returns a copy to prevent external modification
+     *
+     * @returns Copy of event history array, or empty array if persistence disabled
+     *
+     * @example
+     * ```typescript
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * const events = debugger.getEventHistory();
+     * console.log(`Captured ${events.length} events`);
+     * ```
+     */
+    getEventHistory() {
+        if (!this.persistEvents) {
+            return [];
+        }
+        // Return copy to prevent external modification
+        return [...this.eventHistory];
+    }
+    /**
+     * Serialize a WorkflowEvent to JSON-safe format
+     * Extracts only primitive fields to avoid circular references in WorkflowNode objects
+     *
+     * **Strategy:**
+     * - Extract nodeId and nodeName from WorkflowNode references
+     * - Skip WorkflowNode.parent, WorkflowNode.children (circular refs)
+     * - Skip WorkflowError.original (could be circular)
+     * - Add timestamp for chronological ordering
+     *
+     * **Circular Reference Handling:**
+     * - WorkflowNode has bidirectional links (parent ↔ children)
+     * - WorkflowNode.events[] contains WorkflowEvents that reference WorkflowNodes
+     * - JSON.stringify would throw TypeError without selective extraction
+     *
+     * @param event - The workflow event to serialize
+     * @returns JSON-safe object with primitive fields only
+     *
+     * @example
+     * ```typescript
+     * const event: WorkflowEvent = {
+     *   type: 'stateSnapshot',
+     *   node: { id: 'wf-123', name: 'MyWorkflow', ... }
+     * };
+     * const serialized = serializeEvent(event);
+     * // { type: 'stateSnapshot', timestamp: 1234567890, nodeId: 'wf-123', nodeName: 'MyWorkflow', stateSnapshot: {...} }
+     * ```
+     */
+    serializeEvent(event) {
+        const timestamp = Date.now();
+        switch (event.type) {
+            // Core events
+            case 'childAttached':
+                return {
+                    type: event.type,
+                    timestamp,
+                    parentId: event.parentId,
+                    childId: event.child.id,
+                    childName: event.child.name,
+                    childStatus: event.child.status,
+                };
+            case 'childDetached':
+                return {
+                    type: event.type,
+                    timestamp,
+                    parentId: event.parentId,
+                    childId: event.childId,
+                };
+            case 'stateSnapshot':
+                return {
+                    type: event.type,
+                    timestamp,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                    stateSnapshot: event.node.stateSnapshot,
+                };
+            case 'stepStart':
+                return {
+                    type: event.type,
+                    timestamp,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                    step: event.step,
+                };
+            case 'stepEnd':
+                return {
+                    type: event.type,
+                    timestamp,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                    step: event.step,
+                    duration: event.duration,
+                };
+            case 'error':
+                return {
+                    type: event.type,
+                    timestamp,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                    error: {
+                        message: event.error.message,
+                        workflowId: event.error.workflowId,
+                        state: event.error.state,
+                        logs: event.error.logs,
+                        stack: event.error.stack,
+                        // Skip 'original' field - could be circular
+                    },
+                };
+            case 'taskStart':
+            case 'taskEnd':
+                return {
+                    type: event.type,
+                    timestamp,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                    task: event.task,
+                };
+            case 'treeUpdated':
+                return {
+                    type: event.type,
+                    timestamp,
+                    rootId: event.root.id,
+                    rootName: event.root.name,
+                };
+            // Agent/Prompt events
+            case 'agentPromptStart':
+                return {
+                    type: event.type,
+                    timestamp,
+                    agentId: event.agentId,
+                    agentName: event.agentName,
+                    promptId: event.promptId,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                };
+            case 'agentPromptEnd':
+                return {
+                    type: event.type,
+                    timestamp,
+                    agentId: event.agentId,
+                    agentName: event.agentName,
+                    promptId: event.promptId,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                    duration: event.duration,
+                    tokenUsage: event.tokenUsage,
+                };
+            // Tool events
+            case 'toolInvocation':
+                return {
+                    type: event.type,
+                    timestamp,
+                    toolName: event.toolName,
+                    input: event.input,
+                    output: event.output,
+                    duration: event.duration,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                };
+            // MCP events
+            case 'mcpEvent':
+                return {
+                    type: event.type,
+                    timestamp,
+                    serverName: event.serverName,
+                    event: event.event,
+                    payload: event.payload,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                };
+            // Reflection events
+            case 'reflectionStart':
+                return {
+                    type: event.type,
+                    timestamp,
+                    level: event.level,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                };
+            case 'reflectionEnd':
+                return {
+                    type: event.type,
+                    timestamp,
+                    level: event.level,
+                    success: event.success,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                };
+            // Cache events
+            case 'cacheHit':
+            case 'cacheMiss':
+                return {
+                    type: event.type,
+                    timestamp,
+                    key: event.key,
+                    nodeId: event.node.id,
+                    nodeName: event.node.name,
+                };
+            default:
+                // Should not happen with TypeScript discriminated union
+                // But handle gracefully for unknown event types
+                return {
+                    type: event.type,
+                    timestamp,
+                    rawData: JSON.stringify(event),
+                };
+        }
+    }
+    /**
+     * Save event history to a JSON file
+     * Serializes events to avoid circular references and writes to disk
+     *
+     * **Serialization Strategy:**
+     * - Uses serializeEvent() to extract primitive fields only
+     * - Avoids circular references in WorkflowNode objects
+     * - Adds timestamp for chronological ordering
+     *
+     * **Error Handling:**
+     * - Throws descriptive errors for file system issues
+     * - Does not modify internal event history on failure
+     *
+     * @param path - File path to write event history
+     * @throws {Error} If file cannot be written (permission denied, disk full, etc.)
+     * @throws {Error} If event persistence is not enabled
+     *
+     * @example
+     * ```typescript
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * await debugger.saveEventHistory('./workflow-execution.json');
+     * ```
+     */
+    async saveEventHistory(path) {
+        if (!this.persistEvents) {
+            throw new Error('Event persistence is not enabled. Initialize with { persistEvents: true }');
+        }
+        try {
+            // Serialize all events
+            const serialized = this.eventHistory.map((event) => this.serializeEvent(event));
+            // Convert to JSON string
+            const json = JSON.stringify(serialized, null, 2);
+            // Write to file
+            await writeFile(path, json, 'utf-8');
+        }
+        catch (error) {
+            const err = error;
+            // Enhance error messages with context
+            if (err.code === 'ENOENT') {
+                throw new Error(`Cannot save event history: Directory does not exist: ${path}`);
+            }
+            if (err.code === 'EACCES') {
+                throw new Error(`Cannot save event history: Permission denied: ${path}`);
+            }
+            if (err.code === 'ENOSPC') {
+                throw new Error(`Cannot save event history: No space left on device`);
+            }
+            // Re-throw with context
+            throw new Error(`Failed to save event history to ${path}: ${err.message}`);
+        }
+    }
+    /**
+     * Load event history from a JSON file
+     * Static method that can be called without instantiating WorkflowTreeDebugger
+     *
+     * **Error Handling:**
+     * - Throws descriptive errors for file system issues
+     * - Throws descriptive errors for invalid JSON
+     *
+     * @param path - File path to read event history from
+     * @returns Parsed event array (unknown[] - caller should validate structure)
+     * @throws {Error} If file does not exist
+     * @throws {Error} If file cannot be read (permission denied, etc.)
+     * @throws {Error} If file contains invalid JSON
+     *
+     * @example
+     * ```typescript
+     * const events = await WorkflowTreeDebugger.loadEventHistory('./workflow-execution.json');
+     *
+     * // Use with WorkflowEventReplayer
+     * const replayer = new WorkflowEventReplayer();
+     * const tree = replayer.replay(events as WorkflowEvent[]);
+     * ```
+     */
+    static async loadEventHistory(path) {
+        try {
+            // Read file
+            const content = await readFile(path, 'utf-8');
+            // Parse JSON
+            const parsed = JSON.parse(content);
+            // Validate it's an array
+            if (!Array.isArray(parsed)) {
+                throw new Error(`Invalid event history file: Expected array, got ${typeof parsed}`);
+            }
+            return parsed;
+        }
+        catch (error) {
+            const err = error;
+            // Handle file not found
+            if (err.code === 'ENOENT') {
+                throw new Error(`Event history file not found: ${path}`);
+            }
+            // Handle permission denied
+            if (err.code === 'EACCES') {
+                throw new Error(`Permission denied reading file: ${path}`);
+            }
+            // Handle invalid JSON
+            if (err instanceof SyntaxError) {
+                throw new Error(`Invalid JSON in event history file: ${path}\n${err.message}`);
+            }
+            // Re-throw with context
+            throw new Error(`Failed to load event history from ${path}: ${err.message}`);
+        }
+    }
+    /**
+     * Replay workflow execution from saved event history file.
+     *
+     * This is a convenience method that combines loadEventHistory and
+     * WorkflowEventReplayer.replay() for one-call restoration of workflow trees.
+     *
+     * **Use Case**: Time-travel debugging - reconstruct workflow tree from saved events
+     * to inspect execution after completion without requiring the live workflow instance.
+     *
+     * **Workflow**:
+     * 1. Load events from file using loadEventHistory()
+     * 2. Create WorkflowEventReplayer instance
+     * 3. Replay events and return reconstructed tree
+     *
+     * **Error Handling**:
+     * - Throws descriptive errors for file operations (delegated to loadEventHistory)
+     * - Wraps replay errors with file path context
+     *
+     * **Returns**: Read-only WorkflowNode tree (no live workflow attached)
+     *
+     * @param path - File path to saved event history JSON file
+     * @returns Reconstructed workflow tree root node
+     * @throws {Error} If file cannot be read or parsed
+     * @throws {Error} If events cannot be replayed (empty events, no root established)
+     *
+     * @example
+     * ```typescript
+     * // Save event history during execution
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * await debugger.saveEventHistory('./workflow-events.json');
+     *
+     * // Later, replay the events to reconstruct the tree
+     * const tree = await WorkflowTreeDebugger.replay('./workflow-events.json');
+     * console.log(`Restored tree with ${tree.children.length} children`);
+     *
+     * // Use debugger instance to inspect the reconstructed tree
+     * const debugInstance = new WorkflowTreeDebugger({ getNode: () => tree });
+     * console.log(debugInstance.toTreeString(tree));
+     * console.log(debugInstance.getStats());
+     * ```
+     */
+    static async replay(path) {
+        // Load events from file using existing static method
+        const events = await WorkflowTreeDebugger.loadEventHistory(path);
+        // Create replayer instance
+        const replayer = new WorkflowEventReplayer();
+        // Replay events with type assertion (loadEventHistory returns unknown[])
+        // GOTCHA: Wrap in try-catch to enhance error messages with file path context
+        try {
+            return replayer.replay(events);
+        }
+        catch (error) {
+            const err = error;
+            throw new Error(`Failed to replay events from ${path}: ${err.message}`);
+        }
+    }
 }
 //# sourceMappingURL=tree-debugger.js.map