groundswell 0.0.3 → 1.0.0

package/dist/types/providers.js

@@ -0,0 +1,14 @@
+// src/types/providers.ts — Backward-compatible deprecated alias shim (v1.2)
+//
+// Every Provider* symbol is either:
+//   Bucket A — @deprecated alias → structurally-identical Harness* counterpart (types/harnesses.ts)
+//   Bucket B — @deprecated superset union (ProviderId = HarnessId | legacy literals)
+//   Bucket C — KEPT CONCRETE (shape diverges or consumers depend on specifics)
+//
+// The ProviderResult family is already @deprecated → AgentResponse and is left byte-for-byte
+// unchanged.  ToolExecutionRequest / ToolExecutionResult are shared types re-exported from
+// harnesses.ts (NOT renamed, NOT deprecated).  ToolExecutor is a concrete util (not deprecated).
+//
+// NO runtime code.  NO edits to any consumer file.
+export {};
+//# sourceMappingURL=providers.js.map

package/dist/types/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/types/providers.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,oCAAoC;AACpC,oGAAoG;AACpG,qFAAqF;AACrF,+EAA+E;AAC/E,EAAE;AACF,6FAA6F;AAC7F,2FAA2F;AAC3F,iGAAiG;AACjG,EAAE;AACF,mDAAmD"}

package/dist/types/restart.d.ts

@@ -0,0 +1,132 @@
+import type { WorkflowError } from './error.js';
+/**
+ * Restart analysis result
+ *
+ * Provides error classification and restart recommendations for step retry logic.
+ * This interface encapsulates the decision-making process for determining whether
+ * a failed step should be retried, aborted, or require plan rebuilding.
+ *
+ * **Probability Interpretation**:
+ * - `0.0 - 0.3`: Low success probability - consider abort or rebuild
+ * - `0.4 - 0.6`: Moderate probability - retry with caution
+ * - `0.7 - 1.0`: High probability - safe to retry
+ *
+ * @example Transient error - safe to retry
+ * ```ts
+ * const analysis: RestartAnalysis = {
+ *   shouldRestart: true,
+ *   reason: 'Network timeout - likely transient',
+ *   suggestedAction: 'retry',
+ *   estimatedSuccessProbability: 0.8
+ * };
+ * ```
+ *
+ * @example Permanent error - should abort
+ * ```ts
+ * const analysis: RestartAnalysis = {
+ *   shouldRestart: false,
+ *   reason: 'Invalid API key - authentication will never succeed',
+ *   suggestedAction: 'abort',
+ *   estimatedSuccessProbability: 0.0
+ * };
+ * ```
+ *
+ * @example Recoverable but requires intervention
+ * ```ts
+ * const analysis: RestartAnalysis = {
+ *   shouldRestart: true,
+ *   reason: 'Rate limit exceeded - retry after backoff',
+ *   suggestedAction: 'retry',
+ *   estimatedSuccessProbability: 0.6
+ * };
+ * ```
+ *
+ * @see {@link ErrorCriterion} - For defining error matching criteria
+ * @remarks Used in stepRetry events and error analysis utilities
+ */
+export interface RestartAnalysis {
+    /** Whether the step should be restarted */
+    shouldRestart: boolean;
+    /** Human-readable reason for the restart decision */
+    reason: string;
+    /** Suggested action to take */
+    suggestedAction: 'retry' | 'abort' | 'rebuild';
+    /** Estimated probability of success (0-1) */
+    estimatedSuccessProbability: number;
+}
+/**
+ * Error matching criterion for step restart decisions
+ *
+ * Supports three patterns for error matching:
+ * 1. **By error code** - Exact string match or regex pattern matching
+ * 2. **By recoverable flag** - Match recoverable vs non-recoverable errors
+ * 3. **Custom predicate** - Function for complex matching logic
+ *
+ * @example Match by exact error code
+ * ```ts
+ * const criterion: ErrorCriterion = { code: 'RATE_LIMIT_EXCEEDED' };
+ * ```
+ *
+ * @example Match by regex pattern
+ * ```ts
+ * const criterion: ErrorCriterion = { code: /TIMEOUT|NETWORK_ERROR/ };
+ * ```
+ *
+ * @example Match by recoverable flag
+ * ```ts
+ * const criterion: ErrorCriterion = { recoverable: true };
+ * ```
+ *
+ * @example Custom predicate with complex logic
+ * ```ts
+ * const criterion: ErrorCriterion = (error) => {
+ *   const isTemporary = error.message.includes('temporary');
+ *   const isTimeout = error.code === 'TIMEOUT';
+ *   const hasRetryableStatus = error.original?.status >= 500;
+ *   return isTemporary || isTimeout || hasRetryableStatus;
+ * };
+ * ```
+ *
+ * @remarks
+ * **IMPORTANT**: Function types must come last in the discriminated union for proper
+ * TypeScript type narrowing. When checking criteria at runtime, always check
+ * `typeof criterion === 'function'` first before discriminant property checks.
+ *
+ * **Why functions must be last**:
+ * In JavaScript, functions can have properties. If a function has a `code` property,
+ * the discriminant check `'code' in criterion` would return `true`, causing TypeScript
+ * to incorrectly narrow the type. By placing functions last and checking them first
+ * at runtime, we ensure type safety.
+ *
+ * **Runtime checking pattern**:
+ * ```ts
+ * function matchesCriterion(
+ *   criterion: ErrorCriterion,
+ *   error: WorkflowError
+ * ): boolean {
+ *   // Check function FIRST
+ *   if (typeof criterion === 'function') {
+ *     return criterion(error);
+ *   }
+ *   // Now safe to use discriminant checks
+ *   if ('code' in criterion) {
+ *     const codeMatch = criterion.code instanceof RegExp
+ *       ? criterion.code.test(error.code || '')
+ *       : error.code === criterion.code;
+ *     return codeMatch;
+ *   }
+ *   if ('recoverable' in criterion) {
+ *     return error.original?.recoverable === criterion.recoverable;
+ *   }
+ *   return false;
+ * }
+ * ```
+ *
+ * @see {@link RestartAnalysis} - For restart decision result type
+ */
+export type ErrorCriterion = {
+    code: string | RegExp;
+} | {
+    recoverable: boolean;
+} | ((error: WorkflowError) => boolean);
+//# sourceMappingURL=restart.d.ts.map

package/dist/types/restart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.d.ts","sourceRoot":"","sources":["../../src/types/restart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,aAAa,EAAE,OAAO,CAAC;IAEvB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IAEf,+BAA+B;IAC/B,eAAe,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IAE/C,6CAA6C;IAC7C,2BAA2B,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GACzB;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,GACxB,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC"}

package/dist/types/restart.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=restart.js.map

package/dist/types/restart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.js","sourceRoot":"","sources":["../../src/types/restart.ts"],"names":[],"mappings":""}

package/dist/types/streaming.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Streaming types for LLM streaming responses
+ *
+ * Provides types and utilities for streaming responses from LLM providers.
+ * Uses TypeScript's built-in AsyncGenerator for efficient streaming.
+ */
+import type { AgentResponse } from './agent.js';
+/**
+ * Stream event types for LLM streaming responses
+ *
+ * Discriminated union for type-safe event handling during streaming.
+ * Each event type has a unique `type` field for TypeScript narrowing.
+ *
+ * @example
+ * ```ts
+ * for await (const event of streamResult.stream) {
+ *   switch (event.type) {
+ *     case 'text_delta':
+ *       console.log(event.delta); // Type-safe access to delta
+ *       break;
+ *     case 'tool_call_start':
+ *       console.log(event.name); // Type-safe access to name
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type StreamEvent = {
+    type: 'text_delta';
+    delta: string;
+    index: number;
+} | {
+    type: 'text_done';
+    text: string;
+    index: number;
+} | {
+    type: 'tool_call_start';
+    id: string;
+    name: string;
+    index: number;
+} | {
+    type: 'tool_call_delta';
+    id: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_call_done';
+    id: string;
+    result: unknown;
+} | {
+    type: 'metadata';
+    metadata: {
+        requestId?: string;
+        model?: string;
+        provider: string;
+    };
+} | {
+    type: 'usage';
+    inputTokens: number;
+    outputTokens: number;
+    cacheTokens?: number;
+} | {
+    type: 'done';
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'error';
+} | {
+    type: 'error';
+    error: Error;
+    code?: string;
+    retryable?: boolean;
+};
+/**
+ * AsyncStream interface for streaming responses
+ *
+ * Wraps AsyncGenerator with additional metadata and cancellation support.
+ * Designed for for-await...of consumption.
+ *
+ * @template T - The type of the final response data (from AsyncGenerator return)
+ *
+ * @example
+ * ```ts
+ * const streamResult = agent.stream(prompt);
+ *
+ * for await (const event of streamResult.stream) {
+ *   if (event.type === 'text_delta') {
+ *     process.stdout.write(event.delta);
+ *   }
+ * }
+ *
+ * // Cancel stream if needed
+ * streamResult.controller?.abort();
+ * ```
+ */
+export interface AsyncStream<T> {
+    /**
+     * Async generator yielding stream events
+     *
+     * Consume with for await...of loop. The generator yields StreamEvent
+     * objects and returns the final AgentResponse<T> when complete.
+     *
+     * @example
+     * ```ts
+     * for await (const event of streamResult.stream) {
+     *   switch (event.type) {
+     *     case 'text_delta':
+     *       console.log(event.delta);
+     *       break;
+     *     case 'done':
+     *       console.log('Complete!');
+     *       break;
+     *   }
+     * }
+     * ```
+     */
+    stream: AsyncGenerator<StreamEvent, AgentResponse<T>, unknown>;
+    /**
+     * Optional abort controller for cancellation
+     *
+     * Use to cancel an in-progress stream. The stream generator should
+     * check controller.signal.aborted and yield an error event or break.
+     *
+     * @example
+     * ```ts
+     * let eventCount = 0;
+     * for await (const event of streamResult.stream) {
+     *   eventCount++;
+     *   if (eventCount >= 10) {
+     *     streamResult.controller?.abort();
+     *     break;
+     *   }
+     * }
+     * ```
+     */
+    controller?: AbortController;
+}
+/**
+ * Type guard for text delta events
+ *
+ * Narrows StreamEvent to text_delta type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is a text_delta event
+ *
+ * @example
+ * ```ts
+ * if (isTextDeltaEvent(event)) {
+ *   console.log(event.delta); // TypeScript knows delta exists
+ *   console.log(event.index); // TypeScript knows index exists
+ * }
+ * ```
+ */
+export declare function isTextDeltaEvent(event: StreamEvent): event is Extract<StreamEvent, {
+    type: 'text_delta';
+}>;
+/**
+ * Type guard for tool call events
+ *
+ * Narrows StreamEvent to any tool call event type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is a tool_call_start, tool_call_delta, or tool_call_done event
+ *
+ * @example
+ * ```ts
+ * if (isToolCallEvent(event)) {
+ *   if (event.type === 'tool_call_start') {
+ *     console.log(event.name); // TypeScript knows name exists
+ *   }
+ * }
+ * ```
+ */
+export declare function isToolCallEvent(event: StreamEvent): event is Extract<StreamEvent, {
+    type: 'tool_call_start' | 'tool_call_delta' | 'tool_call_done';
+}>;
+/**
+ * Type guard for error events
+ *
+ * Narrows StreamEvent to error type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is an error event
+ *
+ * @example
+ * ```ts
+ * if (isErrorEvent(event)) {
+ *   console.error(event.error.message); // TypeScript knows error exists
+ *   if (event.retryable) {
+ *     // Retry logic
+ *   }
+ * }
+ * ```
+ */
+export declare function isErrorEvent(event: StreamEvent): event is Extract<StreamEvent, {
+    type: 'error';
+}>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/types/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/types/streaming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,GAEnB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAGlD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAGvD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAGxF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAGlF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAA;CAAE,GAG1E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,EAAE,cAAc,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAE/D;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAE1G;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,gBAAgB,CAAA;CAAE,CAAC,CAErJ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAEjG"}

package/dist/types/streaming.js

@@ -0,0 +1,67 @@
+/**
+ * Streaming types for LLM streaming responses
+ *
+ * Provides types and utilities for streaming responses from LLM providers.
+ * Uses TypeScript's built-in AsyncGenerator for efficient streaming.
+ */
+/**
+ * Type guard for text delta events
+ *
+ * Narrows StreamEvent to text_delta type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is a text_delta event
+ *
+ * @example
+ * ```ts
+ * if (isTextDeltaEvent(event)) {
+ *   console.log(event.delta); // TypeScript knows delta exists
+ *   console.log(event.index); // TypeScript knows index exists
+ * }
+ * ```
+ */
+export function isTextDeltaEvent(event) {
+    return event.type === 'text_delta';
+}
+/**
+ * Type guard for tool call events
+ *
+ * Narrows StreamEvent to any tool call event type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is a tool_call_start, tool_call_delta, or tool_call_done event
+ *
+ * @example
+ * ```ts
+ * if (isToolCallEvent(event)) {
+ *   if (event.type === 'tool_call_start') {
+ *     console.log(event.name); // TypeScript knows name exists
+ *   }
+ * }
+ * ```
+ */
+export function isToolCallEvent(event) {
+    return event.type === 'tool_call_start' || event.type === 'tool_call_delta' || event.type === 'tool_call_done';
+}
+/**
+ * Type guard for error events
+ *
+ * Narrows StreamEvent to error type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is an error event
+ *
+ * @example
+ * ```ts
+ * if (isErrorEvent(event)) {
+ *   console.error(event.error.message); // TypeScript knows error exists
+ *   if (event.retryable) {
+ *     // Retry logic
+ *   }
+ * }
+ * ```
+ */
+export function isErrorEvent(event) {
+    return event.type === 'error';
+}
+//# sourceMappingURL=streaming.js.map

package/dist/types/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/types/streaming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgHH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB;IAChD,OAAO,KAAK,CAAC,IAAI,KAAK,iBAAiB,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC;AACjH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAkB;IAC7C,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC;AAChC,CAAC"}

package/dist/types/workflow-context.d.ts

@@ -6,6 +6,8 @@
  */
 import type { WorkflowNode } from './workflow.js';
 import type { ReflectionAPI } from './reflection.js';
+import type { AgentResponse } from './agent.js';
+import type { ErrorMergeStrategy } from './error-strategy.js';
 export type { ReflectionAPI } from './reflection.js';
 /**
  * Handle for querying the event tree
@@ -61,7 +63,7 @@ export interface EventMetrics {
  * Agent interface for context revision (minimal to avoid circular deps)
  */
 export interface AgentLike {
-    prompt<T>(prompt: PromptLike<T>): Promise<T>;
+    prompt<T>(prompt: PromptLike<T>): Promise<AgentResponse<T>>;
 }
 /**
  * Prompt interface for context revision (minimal to avoid circular deps)
@@ -116,6 +118,74 @@ export interface WorkflowContext {
      */
     readonly reflection: ReflectionAPI;
 }
+/**
+ * Event history configuration for workflow execution
+ *
+ * @remarks
+ * When enabled, events are stored in memory and can be accessed via
+ * the workflow's replay functionality. Events include step execution,
+ * errors, agent prompts, tool invocations, and state changes.
+ *
+ * **Memory Management:**
+ * - Events are trimmed based on both count (`maxEvents`) and age (`maxAgeMs`)
+ * - Lazy trimming is used for performance (only trims when significantly over limit)
+ * - When disabled, no events are stored in history (still emitted to observers)
+ *
+ * **Performance Impact:**
+ * - Enabled: Minimal overhead (~1-2ms per event)
+ * - Disabled: Zero overhead
+ *
+ * @example Enable event history with defaults
+ * ```ts
+ * const config: WorkflowConfig = {
+ *   name: 'MyWorkflow',
+ *   eventHistory: { enabled: true }
+ * };
+ * ```
+ *
+ * @example Custom limits
+ * ```ts
+ * const config: WorkflowConfig = {
+ *   name: 'MyWorkflow',
+ *   eventHistory: {
+ *     enabled: true,
+ *     maxEvents: 500,
+ *     maxAgeMs: 1800000  // 30 minutes
+ *   }
+ * };
+ * ```
+ */
+export interface EventHistoryConfig {
+    /**
+     * Enable event history collection
+     *
+     * When false (default), no events are stored in history.
+     * Events are still emitted to observers in real-time.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of events to store in history
+     *
+     * When the limit is exceeded, oldest events are removed first.
+     * Uses lazy trimming for performance (trims at 1.5x the limit).
+     *
+     * @default 1000
+     * @minimum 1
+     */
+    maxEvents?: number;
+    /**
+     * Maximum age of events in milliseconds
+     *
+     * Events older than this are removed from history.
+     * Age is based on insertion time, not event timestamp.
+     *
+     * @default 3600000 (1 hour)
+     * @minimum 1000 (1 second)
+     */
+    maxAgeMs?: number;
+}
 /**
  * Configuration for creating a functional workflow
  */
@@ -124,6 +194,72 @@ export interface WorkflowConfig {
     name?: string;
     /** Enable reflection for this workflow */
     enableReflection?: boolean;
+    /** Automatically validate AgentResponse results after agent.prompt() calls */
+    autoValidateResponses?: boolean;
+    /**
+     * Event history configuration
+     *
+     * @remarks
+     * Controls whether events are stored in memory for replay functionality.
+     * When disabled (default), events are still emitted to observers but not
+     * stored in the internal event history array.
+     *
+     * @example Enable with defaults
+     * ```ts
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow',
+     *   eventHistory: { enabled: true }
+     * };
+     * ```
+     *
+     * @example Custom limits
+     * ```ts
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow',
+     *   eventHistory: {
+     *     enabled: true,
+     *     maxEvents: 500,
+     *     maxAgeMs: 1800000
+     *   }
+     * };
+     * ```
+     */
+    eventHistory?: EventHistoryConfig;
+    /**
+     * Strategy for merging multiple errors
+     *
+     * @remarks
+     * When provided, enables workflow-level error merge for multiple failures.
+     * Default: undefined (first error wins behavior).
+     *
+     * @example
+     * ```ts
+     * // Enable error merging with default strategy
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow',
+     *   errorMergeStrategy: { enabled: true }
+     * };
+     *
+     * // Enable with custom combine function
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow',
+     *   errorMergeStrategy: {
+     *     enabled: true,
+     *     combine: (errors) => ({
+     *       message: `Custom: ${errors.length} failures`,
+     *       // ... custom error object
+     *     })
+     *   }
+     * };
+     *
+     * // Default behavior (first error wins)
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow'
+     *   // errorMergeStrategy not provided = first error wins
+     * };
+     * ```
+     */
+    errorMergeStrategy?: ErrorMergeStrategy;
 }
 /**
  * Result from workflow execution

package/dist/types/workflow-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-context.d.ts","sourceRoot":"","sources":["../../src/types/workflow-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow-context.d.ts","sourceRoot":"","sources":["../../src/types/workflow-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9D,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAE3C;;;OAGG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;IAErC;;;OAGG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;IAEtC;;OAEG;IACH,MAAM,IAAI,SAAS,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,IAAI,MAAM,CAAC;IAC3B,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,mCAAmC;IACnC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;;;;;OAOG;IACH,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE;QAAE,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9D;;;;;;;OAOG;IACH,uBAAuB,CAAC,CAAC,EACvB,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,EACxB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,CAAC,CAAC,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,8EAA8E;IAC9E,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,uBAAuB;IACvB,IAAI,EAAE,CAAC,CAAC;IAER,wBAAwB;IACxB,IAAI,EAAE,YAAY,CAAC;IAEnB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB"}