groundswell 0.0.2 → 1.0.0

package/dist/decorators/observed-state.d.ts

@@ -0,0 +1,32 @@
+import type { StateFieldMetadata, SerializedWorkflowState } from '../types/index.js';
+/**
+ * @ObservedState decorator
+ * Marks a class field for inclusion in state snapshots
+ *
+ * @example
+ * class MyWorkflow extends Workflow {
+ *   @ObservedState()
+ *   currentStep!: string;
+ *
+ *   @ObservedState({ redact: true })
+ *   sensitiveData!: string;
+ *
+ *   @ObservedState({ hidden: true })
+ *   internalState!: object;
+ * }
+ */
+export declare function ObservedState(meta?: StateFieldMetadata): (_value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * Get all observed state from an object instance
+ * Applies hidden and redact transformations
+ */
+export declare function getObservedState(obj: object): SerializedWorkflowState;
+/**
+ * Check if a field is observed on an object
+ */
+export declare function isFieldObserved(obj: object, fieldName: string): boolean;
+/**
+ * Get metadata for a specific field
+ */
+export declare function getFieldMetadata(obj: object, fieldName: string): StateFieldMetadata | undefined;
+//# sourceMappingURL=observed-state.d.ts.map

package/dist/decorators/observed-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed-state.d.ts","sourceRoot":"","sources":["../../src/decorators/observed-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAQrF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,kBAAuB,IAEvD,QAAQ,SAAS,EACjB,SAAS,0BAA0B,KAClC,IAAI,CAeR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,CA2BrE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAIvE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAI/F"}

package/dist/decorators/observed-state.js

@@ -0,0 +1,79 @@
+/**
+ * WeakMap storing field metadata keyed by class prototype
+ * Structure: Map<propertyKey, StateFieldMetadata>
+ */
+const OBSERVED_STATE_FIELDS = new WeakMap();
+/**
+ * @ObservedState decorator
+ * Marks a class field for inclusion in state snapshots
+ *
+ * @example
+ * class MyWorkflow extends Workflow {
+ *   @ObservedState()
+ *   currentStep!: string;
+ *
+ *   @ObservedState({ redact: true })
+ *   sensitiveData!: string;
+ *
+ *   @ObservedState({ hidden: true })
+ *   internalState!: object;
+ * }
+ */
+export function ObservedState(meta = {}) {
+    return function (_value, context) {
+        const propertyKey = String(context.name);
+        // Use addInitializer to register field when class is instantiated
+        context.addInitializer(function () {
+            const instance = this;
+            const proto = Object.getPrototypeOf(instance);
+            let map = OBSERVED_STATE_FIELDS.get(proto);
+            if (!map) {
+                map = new Map();
+                OBSERVED_STATE_FIELDS.set(proto, map);
+            }
+            map.set(propertyKey, meta);
+        });
+    };
+}
+/**
+ * Get all observed state from an object instance
+ * Applies hidden and redact transformations
+ */
+export function getObservedState(obj) {
+    const proto = Object.getPrototypeOf(obj);
+    const map = OBSERVED_STATE_FIELDS.get(proto);
+    if (!map) {
+        return {};
+    }
+    const result = {};
+    for (const [key, meta] of map) {
+        // Skip hidden fields
+        if (meta.hidden) {
+            continue;
+        }
+        let value = obj[key];
+        // Redact sensitive fields
+        if (meta.redact) {
+            value = '***';
+        }
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Check if a field is observed on an object
+ */
+export function isFieldObserved(obj, fieldName) {
+    const proto = Object.getPrototypeOf(obj);
+    const map = OBSERVED_STATE_FIELDS.get(proto);
+    return map?.has(fieldName) ?? false;
+}
+/**
+ * Get metadata for a specific field
+ */
+export function getFieldMetadata(obj, fieldName) {
+    const proto = Object.getPrototypeOf(obj);
+    const map = OBSERVED_STATE_FIELDS.get(proto);
+    return map?.get(fieldName);
+}
+//# sourceMappingURL=observed-state.js.map

package/dist/decorators/observed-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed-state.js","sourceRoot":"","sources":["../../src/decorators/observed-state.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,qBAAqB,GAAG,IAAI,OAAO,EAA2C,CAAC;AAErF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,OAA2B,EAAE;IACzD,OAAO,UACL,MAAiB,EACjB,OAAmC;QAEnC,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEzC,kEAAkE;QAClE,OAAO,CAAC,cAAc,CAAC;YACrB,MAAM,QAAQ,GAAG,IAAc,CAAC;YAChC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;YAC9C,IAAI,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;gBAChB,qBAAqB,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAE7C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QAC9B,qBAAqB;QACrB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,SAAS;QACX,CAAC;QAED,IAAI,KAAK,GAAI,GAA+B,CAAC,GAAG,CAAC,CAAC;QAElD,0BAA0B;QAC1B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC;QAED,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,SAAiB;IAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,SAAiB;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;AAC7B,CAAC"}

package/dist/decorators/step.d.ts

@@ -0,0 +1,15 @@
+import type { StepOptions } from '../types/index.js';
+/**
+ * @Step decorator
+ * Wraps a method to emit step events, handle errors, and optionally snapshot state
+ *
+ * @example
+ * class MyWorkflow extends Workflow {
+ *   @Step({ snapshotState: true, trackTiming: true })
+ *   async processData() {
+ *     // ... step logic
+ *   }
+ * }
+ */
+export declare function Step(opts?: StepOptions): <This, Args extends unknown[], Return>(originalMethod: (this: This, ...args: Args) => Promise<Return>, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>) => (this: This, ...args: Args) => Promise<Return>;
+//# sourceMappingURL=step.d.ts.map

package/dist/decorators/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/decorators/step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAyF,MAAM,mBAAmB,CAAC;AAgB5I;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,IACxB,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACnD,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,EAC9D,SAAS,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,YAoCzD,IAAI,WAAW,IAAI,KAAG,OAAO,CAAC,MAAM,CAAC,CA0KzE"}

package/dist/decorators/step.js

@@ -0,0 +1,192 @@
+import { getObservedState } from './observed-state.js';
+import { runInContext } from '../core/context.js';
+import { generateId, delay } from '../utils/index.js';
+/**
+ * @Step decorator
+ * Wraps a method to emit step events, handle errors, and optionally snapshot state
+ *
+ * @example
+ * class MyWorkflow extends Workflow {
+ *   @Step({ snapshotState: true, trackTiming: true })
+ *   async processData() {
+ *     // ... step logic
+ *   }
+ * }
+ */
+export function Step(opts = {}) {
+    return function (originalMethod, context) {
+        const methodName = String(context.name);
+        /**
+         * Check if an error matches a retry criterion
+         * Handles all three ErrorCriterion variants: code, recoverable, and function
+         */
+        function matchesCriterion(error, criterion) {
+            // CRITICAL: Check typeof first for function type narrowing
+            if (typeof criterion === 'function') {
+                return criterion(error);
+            }
+            // Object type checks (type narrowing works after typeof check)
+            if ('code' in criterion) {
+                const errorCode = error.message;
+                return typeof criterion.code === 'string'
+                    ? errorCode === criterion.code
+                    : criterion.code.test(errorCode);
+            }
+            if ('recoverable' in criterion) {
+                // For recoverable criterion, we check the original error if available
+                const original = error.original;
+                if (original && 'recoverable' in original) {
+                    return original.recoverable === criterion.recoverable;
+                }
+                // If no recoverable field on original error, assume true to allow retry
+                return criterion.recoverable;
+            }
+            return false;
+        }
+        // CRITICAL: Use regular function, not arrow function, to preserve 'this'
+        async function stepWrapper(...args) {
+            // Cast to WorkflowLike for type safety when accessing workflow properties
+            const wf = this;
+            const stepName = opts.name ?? methodName;
+            const startTime = Date.now();
+            // NEW: Initialize retry state
+            let retryCount = 0;
+            const maxRetries = opts.maxRetries ?? 3;
+            // Log start if requested
+            if (opts.logStart) {
+                wf.logger.info(`STEP START: ${stepName}`);
+            }
+            // Emit step start event (only once, not on retry)
+            wf.emitEvent({
+                type: 'stepStart',
+                node: wf.node,
+                step: stepName,
+            });
+            // Create step node for hierarchy tracking
+            const stepNode = {
+                id: generateId(),
+                name: stepName,
+                parent: wf.node,
+                children: [],
+                status: 'running',
+                logs: [],
+                events: [],
+                stateSnapshot: null,
+            };
+            // Create execution context for agent/prompt operations within this step
+            const executionContext = {
+                workflowNode: stepNode,
+                emitEvent: (event) => {
+                    stepNode.events.push(event);
+                    wf.emitEvent(event);
+                },
+                workflowId: wf.id,
+            };
+            // ============================================================
+            // CRITICAL: Retry loop wraps existing try-catch
+            // ============================================================
+            while (retryCount <= maxRetries) {
+                try {
+                    // Execute the original method within the execution context
+                    // This allows Agent.prompt() calls to automatically capture events
+                    const result = await runInContext(executionContext, async () => {
+                        return originalMethod.call(this, ...args);
+                    });
+                    // Update step node status
+                    stepNode.status = 'completed';
+                    // Snapshot state if requested
+                    if (opts.snapshotState) {
+                        wf.snapshotState();
+                    }
+                    // Calculate duration and emit end event
+                    const duration = Date.now() - startTime;
+                    if (opts.trackTiming !== false) {
+                        wf.emitEvent({
+                            type: 'stepEnd',
+                            node: wf.node,
+                            step: stepName,
+                            duration,
+                        });
+                    }
+                    // Log finish if requested
+                    if (opts.logFinish) {
+                        wf.logger.info(`STEP END: ${stepName} (${duration}ms)`);
+                    }
+                    // CRITICAL: Exit loop on success
+                    return result;
+                }
+                catch (err) {
+                    // Update step node status
+                    stepNode.status = 'failed';
+                    // Create rich error with context
+                    const error = err;
+                    const snap = getObservedState(this);
+                    const workflowError = {
+                        message: error?.message ?? 'Unknown error',
+                        original: err,
+                        workflowId: wf.id,
+                        stack: error?.stack,
+                        state: snap,
+                        logs: [...wf.node.logs],
+                    };
+                    // ============================================================
+                    // CRITICAL: Check if should retry or throw immediately
+                    // ============================================================
+                    const shouldAttemptRetry = opts.restartable && retryCount < maxRetries;
+                    // Check retry criteria if specified
+                    const matchesRetryCriteria = opts.retryOn
+                        ? opts.retryOn.some(criterion => matchesCriterion(workflowError, criterion))
+                        : true; // If no criteria specified, retry all errors when restartable
+                    if (!shouldAttemptRetry || !matchesRetryCriteria) {
+                        // Emit error event and throw
+                        wf.emitEvent({
+                            type: 'error',
+                            node: wf.node,
+                            error: workflowError,
+                        });
+                        // Re-throw the enriched error
+                        throw workflowError;
+                    }
+                    // ============================================================
+                    // CRITICAL: Emit retry event and delay before retry
+                    // ============================================================
+                    const nextRetryCount = retryCount + 1;
+                    // Create restart analysis for the retry event
+                    const analysis = {
+                        shouldRestart: true,
+                        reason: `Error matches retry criteria (attempt ${nextRetryCount}/${maxRetries})`,
+                        suggestedAction: 'retry',
+                        estimatedSuccessProbability: 0.7,
+                    };
+                    // Emit step retry event
+                    wf.emitEvent({
+                        type: 'stepRetry',
+                        node: wf.node,
+                        stepName: stepName,
+                        retryCount: nextRetryCount,
+                        analysis,
+                        error: workflowError,
+                        timestamp: Date.now(),
+                    });
+                    // Log retry if logging enabled
+                    if (opts.logStart || opts.logFinish) {
+                        wf.logger.info(`STEP RETRY: ${stepName} (attempt ${nextRetryCount}/${maxRetries})`);
+                    }
+                    // Wait before retry
+                    const delayMs = opts.retryDelayMs ?? 1000;
+                    await delay(delayMs);
+                    // Increment retry count and continue loop
+                    retryCount = nextRetryCount;
+                    // Update step node name for retry
+                    stepNode.name = `${stepName} (retry ${retryCount})`;
+                    stepNode.status = 'running';
+                }
+            }
+            // Should not reach here, but TypeScript needs it
+            // This would only happen if loop exits without return or throw
+            throw new Error(`Retry loop exited unexpectedly for step ${stepName}`);
+        }
+        return stepWrapper;
+    };
+}
+//# sourceMappingURL=step.js.map

package/dist/decorators/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/decorators/step.ts"],"names":[],"mappings":"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"}

package/dist/decorators/task.d.ts

@@ -0,0 +1,50 @@
+import type { TaskOptions } from '../types/index.js';
+/**
+ * @Task decorator
+ * Wraps a method that returns child workflow(s), automatically attaching them
+ *
+ * @example
+ * class ParentWorkflow extends Workflow {
+ *   @Task({ concurrent: true })
+ *   async createChildren(): Promise<ChildWorkflow[]> {
+ *     return [
+ *       new ChildWorkflow('child1', this),
+ *       new ChildWorkflow('child2', this),
+ *     ];
+ *   }
+ * }
+ *
+ * @example Non-workflow return (silently skipped)
+ * class MyWorkflow extends Workflow {
+ *   @Task()
+ *   async returnsString(): Promise<string> {
+ *     return 'not a workflow';  // Returned as-is, not attached
+ *   }
+ * }
+ *
+ * @example Mixed return (only workflows attached)
+ * class MyWorkflow extends Workflow {
+ *   @Task()
+ *   async mixedReturn(): Promise<(Workflow | string)[]> {
+ *     return [
+ *       new ChildWorkflow('child1', this),  // Attached
+ *       'some string',                       // Skipped
+ *       new ChildWorkflow('child2', this),  // Attached
+ *     ];
+ *   }
+ * }
+ *
+ * Validation Behavior
+ *
+ * The decorator uses lenient validation for return values:
+ * - Workflow objects (with 'id' property) are automatically attached
+ * - Non-workflow objects are silently skipped (not attached)
+ * - The original return value is always preserved
+ *
+ * This lenient approach enables:
+ * - Duck-typing: Works with workflow-like objects, not just Workflow instances
+ * - Flexible signatures: Methods can return any type without breaking
+ * - Graceful handling: Edge cases (null, undefined, primitives) don't throw errors
+ */
+export declare function Task(opts?: TaskOptions): <This, Args extends unknown[], Return>(originalMethod: (this: This, ...args: Args) => Promise<Return>, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>) => (this: This, ...args: Args) => Promise<Return>;
+//# sourceMappingURL=task.d.ts.map

package/dist/decorators/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/decorators/task.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAuE,MAAM,mBAAmB,CAAC;AAkB1H;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,IACxB,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACnD,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,EAC9D,SAAS,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,YAKzD,IAAI,WAAW,IAAI,KAAG,OAAO,CAAC,MAAM,CAAC,CAqFzE"}

package/dist/decorators/task.js

@@ -0,0 +1,118 @@
+import { mergeWorkflowErrors } from '../utils/workflow-error-utils.js';
+/**
+ * @Task decorator
+ * Wraps a method that returns child workflow(s), automatically attaching them
+ *
+ * @example
+ * class ParentWorkflow extends Workflow {
+ *   @Task({ concurrent: true })
+ *   async createChildren(): Promise<ChildWorkflow[]> {
+ *     return [
+ *       new ChildWorkflow('child1', this),
+ *       new ChildWorkflow('child2', this),
+ *     ];
+ *   }
+ * }
+ *
+ * @example Non-workflow return (silently skipped)
+ * class MyWorkflow extends Workflow {
+ *   @Task()
+ *   async returnsString(): Promise<string> {
+ *     return 'not a workflow';  // Returned as-is, not attached
+ *   }
+ * }
+ *
+ * @example Mixed return (only workflows attached)
+ * class MyWorkflow extends Workflow {
+ *   @Task()
+ *   async mixedReturn(): Promise<(Workflow | string)[]> {
+ *     return [
+ *       new ChildWorkflow('child1', this),  // Attached
+ *       'some string',                       // Skipped
+ *       new ChildWorkflow('child2', this),  // Attached
+ *     ];
+ *   }
+ * }
+ *
+ * Validation Behavior
+ *
+ * The decorator uses lenient validation for return values:
+ * - Workflow objects (with 'id' property) are automatically attached
+ * - Non-workflow objects are silently skipped (not attached)
+ * - The original return value is always preserved
+ *
+ * This lenient approach enables:
+ * - Duck-typing: Works with workflow-like objects, not just Workflow instances
+ * - Flexible signatures: Methods can return any type without breaking
+ * - Graceful handling: Edge cases (null, undefined, primitives) don't throw errors
+ */
+export function Task(opts = {}) {
+    return function (originalMethod, context) {
+        const methodName = String(context.name);
+        // CRITICAL: Use regular function, not arrow function
+        async function taskWrapper(...args) {
+            // Cast to WorkflowLike for type safety when accessing workflow properties
+            const wf = this;
+            const taskName = opts.name ?? methodName;
+            // Emit task start event
+            wf.emitEvent({
+                type: 'taskStart',
+                node: wf.node,
+                task: taskName,
+            });
+            // Execute the original method
+            const result = await originalMethod.call(this, ...args);
+            // Process returned workflows
+            const workflows = Array.isArray(result) ? result : [result];
+            for (const workflow of workflows) {
+                // Type guard to check if it's a workflow
+                if (workflow && typeof workflow === 'object' && 'id' in workflow) {
+                    const childWf = workflow;
+                    // Only attach if not already attached (parent not set by constructor)
+                    if (!childWf.parent) {
+                        childWf.parent = wf;
+                        wf.attachChild(childWf);
+                    }
+                }
+            }
+            // If concurrent option is set and we have multiple workflows, run them in parallel
+            if (opts.concurrent && Array.isArray(result)) {
+                const runnable = workflows.filter((w) => w && typeof w === 'object' && 'run' in w && typeof w.run === 'function');
+                if (runnable.length > 0) {
+                    const results = await Promise.allSettled(runnable.map((w) => w.run()));
+                    const rejected = results.filter((r) => r.status === 'rejected');
+                    if (rejected.length > 0) {
+                        // Check if error merge strategy is enabled
+                        if (opts.errorMergeStrategy?.enabled) {
+                            // Extract WorkflowError objects from rejected promises
+                            const errors = rejected.map((r) => r.reason);
+                            // Merge errors using custom combine() or default merger
+                            const mergedError = opts.errorMergeStrategy?.combine
+                                ? opts.errorMergeStrategy.combine(errors)
+                                : mergeWorkflowErrors(errors, taskName, wf.id, runnable.length);
+                            // Emit error event with merged error
+                            wf.emitEvent({
+                                type: 'error',
+                                node: wf.node,
+                                error: mergedError,
+                            });
+                            // Throw merged error
+                            throw mergedError;
+                        }
+                        // Backward compatibility: throw first error
+                        throw rejected[0].reason;
+                    }
+                }
+            }
+            // Emit task end event
+            wf.emitEvent({
+                type: 'taskEnd',
+                node: wf.node,
+                task: taskName,
+            });
+            return result;
+        }
+        return taskWrapper;
+    };
+}
+//# sourceMappingURL=task.js.map

package/dist/decorators/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/decorators/task.ts"],"names":[],"mappings":"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"}

package/dist/examples/index.d.ts

@@ -0,0 +1,3 @@
+export { TestCycleWorkflow } from './test-cycle-workflow.js';
+export { TDDOrchestrator } from './tdd-orchestrator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/examples/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/examples/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/{src/examples/index.ts → dist/examples/index.js}

@@ -1,2 +1,3 @@
 export { TestCycleWorkflow } from './test-cycle-workflow.js';
 export { TDDOrchestrator } from './tdd-orchestrator.js';
+//# sourceMappingURL=index.js.map

package/dist/examples/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/examples/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/examples/tdd-orchestrator.d.ts

@@ -0,0 +1,15 @@
+import { Workflow } from '../core/workflow.js';
+import { TestCycleWorkflow } from './test-cycle-workflow.js';
+/**
+ * Example parent workflow demonstrating TDD orchestration
+ */
+export declare class TDDOrchestrator extends Workflow {
+    cycleCount: number;
+    maxCycles: number;
+    apiKey: string;
+    setupEnvironment(): Promise<void>;
+    runCycle(): Promise<TestCycleWorkflow>;
+    run(): Promise<void>;
+    private delay;
+}
+//# sourceMappingURL=tdd-orchestrator.d.ts.map

package/dist/examples/tdd-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tdd-orchestrator.d.ts","sourceRoot":"","sources":["../../src/examples/tdd-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAI/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAE3C,UAAU,EAAE,MAAM,CAAK;IAGvB,SAAS,EAAE,MAAM,CAAK;IAGtB,MAAM,EAAE,MAAM,CAAgB;IAGxB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,QAAQ,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAMtC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B1B,OAAO,CAAC,KAAK;CAGd"}