@robota-sdk/agent-plugin 3.0.0-beta.64

package/src/error-handling/__tests__/error-handling-plugin.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ErrorHandlingPlugin } from '../error-handling-plugin';
+import { ConfigurationError } from '@robota-sdk/agent-core';
+
+describe('ErrorHandlingPlugin', () => {
+  describe('constructor', () => {
+    it('initializes with simple strategy', () => {
+      const plugin = new ErrorHandlingPlugin({ strategy: 'simple' });
+      expect(plugin.name).toBe('ErrorHandlingPlugin');
+      expect(plugin.version).toBe('1.0.0');
+    });
+
+    it('throws on missing strategy', () => {
+      expect(() => new ErrorHandlingPlugin({ strategy: '' as any })).toThrow(ConfigurationError);
+    });
+
+    it('throws on invalid strategy', () => {
+      expect(() => new ErrorHandlingPlugin({ strategy: 'invalid' as any })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws on negative maxRetries', () => {
+      expect(() => new ErrorHandlingPlugin({ strategy: 'simple', maxRetries: -1 })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws on non-positive retryDelay', () => {
+      expect(() => new ErrorHandlingPlugin({ strategy: 'simple', retryDelay: 0 })).toThrow(
+        ConfigurationError,
+      );
+    });
+  });
+
+  describe('handleError', () => {
+    it('handles error with simple strategy', async () => {
+      const plugin = new ErrorHandlingPlugin({ strategy: 'simple' });
+      await expect(plugin.handleError(new Error('test'))).resolves.not.toThrow();
+    });
+
+    it('handles error with silent strategy', async () => {
+      const plugin = new ErrorHandlingPlugin({ strategy: 'silent' });
+      await expect(plugin.handleError(new Error('test'))).resolves.not.toThrow();
+    });
+
+    it('invokes custom error handler when provided', async () => {
+      const customHandler = vi.fn().mockResolvedValue(undefined);
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'simple',
+        customErrorHandler: customHandler,
+      });
+
+      const error = new Error('custom test');
+      await plugin.handleError(error, { executionId: 'e1' });
+
+      expect(customHandler).toHaveBeenCalledWith(error, { executionId: 'e1' });
+    });
+
+    it('falls back to strategy when custom handler throws', async () => {
+      const customHandler = vi.fn().mockRejectedValue(new Error('handler fail'));
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'simple',
+        customErrorHandler: customHandler,
+      });
+
+      await expect(plugin.handleError(new Error('test'))).resolves.not.toThrow();
+    });
+  });
+
+  describe('circuit breaker', () => {
+    it('opens circuit after reaching failure threshold', async () => {
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'circuit-breaker',
+        failureThreshold: 3,
+      });
+
+      for (let i = 0; i < 3; i++) {
+        await plugin.handleError(new Error(`error ${i}`));
+      }
+
+      const stats = plugin.getStats();
+      expect(stats.circuitBreakerOpen).toBe(true);
+      expect(stats.failureCount).toBe(3);
+    });
+
+    it('does not open circuit below threshold', async () => {
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'circuit-breaker',
+        failureThreshold: 5,
+      });
+
+      await plugin.handleError(new Error('error'));
+      await plugin.handleError(new Error('error'));
+
+      const stats = plugin.getStats();
+      expect(stats.circuitBreakerOpen).toBe(false);
+      expect(stats.failureCount).toBe(2);
+    });
+
+    it('resets circuit breaker manually', async () => {
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'circuit-breaker',
+        failureThreshold: 2,
+      });
+
+      await plugin.handleError(new Error('e1'));
+      await plugin.handleError(new Error('e2'));
+      expect(plugin.getStats().circuitBreakerOpen).toBe(true);
+
+      plugin.resetCircuitBreaker();
+      const stats = plugin.getStats();
+      expect(stats.circuitBreakerOpen).toBe(false);
+      expect(stats.failureCount).toBe(0);
+      expect(stats.lastFailureTime).toBe(0);
+    });
+  });
+
+  describe('executeWithRetry', () => {
+    it('succeeds on first attempt', async () => {
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'simple',
+        maxRetries: 2,
+        retryDelay: 1,
+      });
+
+      const fn = vi.fn().mockResolvedValue('success');
+      const result = await plugin.executeWithRetry(fn);
+
+      expect(result).toBe('success');
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('retries and succeeds on later attempt', async () => {
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'simple',
+        maxRetries: 3,
+        retryDelay: 1,
+      });
+
+      const fn = vi
+        .fn()
+        .mockRejectedValueOnce(new Error('fail 1'))
+        .mockRejectedValueOnce(new Error('fail 2'))
+        .mockResolvedValue('success');
+
+      const result = await plugin.executeWithRetry(fn);
+      expect(result).toBe('success');
+      expect(fn).toHaveBeenCalledTimes(3);
+    });
+
+    it('throws after exhausting retries', async () => {
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'simple',
+        maxRetries: 1,
+        retryDelay: 1,
+      });
+
+      const fn = vi.fn().mockRejectedValue(new Error('always fail'));
+
+      await expect(plugin.executeWithRetry(fn)).rejects.toThrow('Operation failed after 1 retries');
+      expect(fn).toHaveBeenCalledTimes(2); // initial + 1 retry
+    });
+
+    it('blocks when circuit breaker is open', async () => {
+      const plugin = new ErrorHandlingPlugin({
+        strategy: 'circuit-breaker',
+        failureThreshold: 1,
+        maxRetries: 0,
+        retryDelay: 1,
+        circuitBreakerTimeout: 60000,
+      });
+
+      // Open the circuit breaker
+      await plugin.handleError(new Error('trip'));
+      expect(plugin.getStats().circuitBreakerOpen).toBe(true);
+
+      const fn = vi.fn().mockResolvedValue('ok');
+      await expect(plugin.executeWithRetry(fn)).rejects.toThrow('Operation failed after 0 retries');
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('getStats', () => {
+    it('returns initial stats', () => {
+      const plugin = new ErrorHandlingPlugin({ strategy: 'simple' });
+      const stats = plugin.getStats();
+
+      expect(stats.failureCount).toBe(0);
+      expect(stats.circuitBreakerOpen).toBe(false);
+      expect(stats.lastFailureTime).toBe(0);
+    });
+  });
+
+  describe('destroy', () => {
+    it('completes without error', async () => {
+      const plugin = new ErrorHandlingPlugin({ strategy: 'simple' });
+      await expect(plugin.destroy()).resolves.not.toThrow();
+    });
+  });
+});

package/src/error-handling/context-adapter.ts

@@ -0,0 +1,48 @@
+/**
+ * ErrorHandling Plugin - Context adapter utilities for Facade pattern
+ *
+ * REASON: TypeScript exactOptionalPropertyTypes strict mode requires special handling for optional properties
+ * ALTERNATIVES_CONSIDERED: Bracket notation (rejected by TS), type assertions (rejected), interface modification (breaks compatibility), union types (causes dependencies), removing context (loses debugging)
+ * TODO: Consider unified error context type system across all plugins
+ */
+
+import type { IErrorHandlingContextData, IErrorContextAdapter } from './types';
+import type { TErrorContextData } from '@robota-sdk/agent-core';
+
+/**
+ * Convert IErrorHandlingContextData to ErrorContextData-compatible format for PluginError
+ * REASON: Simple object spread with known properties to avoid index signature conflicts
+ * ALTERNATIVES_CONSIDERED: Complex type adapters (unnecessary), Object.assign (verbose), bracket notation (rejected by TS), type assertions (reduces safety)
+ * TODO: Consider unified error context type system across all plugins
+ */
+export function toErrorContext(context: IErrorHandlingContextData): IErrorContextAdapter {
+  return {
+    ...(context.executionId && { executionId: context.executionId }),
+    ...(context.sessionId && { sessionId: context.sessionId }),
+    ...(context.userId && { userId: context.userId }),
+    ...(context.attempt !== undefined && { attempt: context.attempt }),
+    ...(context.originalError && { originalError: context.originalError }),
+  };
+}
+
+/**
+ * Safe context extraction for PluginError with nested context structure
+ *
+ * REASON: PluginError context needs flexible data structure for debugging information
+ * ALTERNATIVES_CONSIDERED:
+ * 1. Strict primitive types (loses debugging information)
+ * 2. Interface definitions (too rigid for error contexts)
+ * 3. Union types (becomes unwieldy for error data)
+ * 4. Generic constraints (too complex for error handling)
+ * 5. Type assertions (decreases type safety)
+ * TODO: Consider standardized error context interface if patterns emerge
+ */
+export function createPluginErrorContext(
+  context: IErrorHandlingContextData,
+  additionalData?: TErrorContextData,
+): TErrorContextData {
+  return {
+    ...toErrorContext(context),
+    ...(additionalData && { ...additionalData }),
+  };
+}

package/src/error-handling/error-handling-helpers.ts

@@ -0,0 +1,53 @@
+/**
+ * Error Handling Plugin - Validation and strategy handler helpers.
+ *
+ * Extracted from error-handling-plugin.ts to keep each file under 300 lines.
+ * @internal
+ */
+
+import { ConfigurationError } from '@robota-sdk/agent-core';
+import type { IErrorHandlingPluginOptions } from './types';
+
+/** Validate ErrorHandlingPlugin constructor options. @internal */
+export function validateErrorHandlingOptions(options: IErrorHandlingPluginOptions): void {
+  if (!options.strategy) {
+    throw new ConfigurationError('Error handling strategy is required');
+  }
+
+  if (!['simple', 'circuit-breaker', 'exponential-backoff', 'silent'].includes(options.strategy)) {
+    throw new ConfigurationError('Invalid error handling strategy', {
+      validStrategies: ['simple', 'circuit-breaker', 'exponential-backoff', 'silent'],
+      provided: options.strategy,
+    });
+  }
+
+  if (options.maxRetries !== undefined && options.maxRetries < 0) {
+    throw new ConfigurationError('Max retries must be non-negative');
+  }
+
+  if (options.retryDelay !== undefined && options.retryDelay <= 0) {
+    throw new ConfigurationError('Retry delay must be positive');
+  }
+}
+
+/** Resolve retry delay based on strategy and attempt number. @internal */
+export function resolveRetryDelay(strategy: string, baseDelay: number, attempt: number): number {
+  return strategy === 'exponential-backoff' ? baseDelay * Math.pow(2, attempt - 1) : baseDelay;
+}
+
+/** Resolve true if the circuit breaker timeout has not yet elapsed. @internal */
+export function isCircuitBreakerStillOpen(
+  circuitBreakerOpen: boolean,
+  lastFailureTime: number,
+  circuitBreakerTimeout: number,
+): { open: boolean; shouldReset: boolean } {
+  if (!circuitBreakerOpen) return { open: false, shouldReset: false };
+  const timeoutPassed = Date.now() - lastFailureTime > circuitBreakerTimeout;
+  if (timeoutPassed) return { open: false, shouldReset: true };
+  return { open: true, shouldReset: false };
+}
+
+/** Sleep for a given number of milliseconds. @internal */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/error-handling/error-handling-plugin.ts

@@ -0,0 +1,293 @@
+import {
+  AbstractPlugin,
+  PluginCategory,
+  PluginPriority,
+  createLogger,
+  type ILogger,
+  PluginError,
+} from '@robota-sdk/agent-core';
+
+// Import from Facade pattern modules for type safety
+import type {
+  IErrorHandlingContextData,
+  IErrorHandlingPluginOptions,
+  IErrorHandlingPluginStats,
+} from './types';
+import { toErrorContext, createPluginErrorContext } from './context-adapter';
+import {
+  validateErrorHandlingOptions,
+  resolveRetryDelay,
+  isCircuitBreakerStillOpen,
+  sleep,
+} from './error-handling-helpers';
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_DELAY_MS = 1000;
+const DEFAULT_FAILURE_THRESHOLD = 5;
+const DEFAULT_CIRCUIT_BREAKER_TIMEOUT_MS = 60000;
+
+/**
+ * Provides configurable error recovery using one of four strategies:
+ * simple logging, circuit breaker, exponential backoff, or silent.
+ *
+ * The circuit breaker opens after
+ * {@link IErrorHandlingPluginOptions.failureThreshold | failureThreshold}
+ * consecutive failures and automatically resets after
+ * {@link IErrorHandlingPluginOptions.circuitBreakerTimeout | circuitBreakerTimeout} ms.
+ * An optional custom error handler can be injected for application-specific
+ * recovery logic.
+ *
+ * @extends AbstractPlugin
+ * @see IErrorHandlingPluginOptions - configuration options
+ * @see IErrorHandlingContextData - error context contract
+ *
+ * @example
+ * ```ts
+ * const plugin = new ErrorHandlingPlugin({
+ *   strategy: 'circuit-breaker',
+ *   failureThreshold: 5,
+ *   circuitBreakerTimeout: 60000,
+ * });
+ * const result = await plugin.executeWithRetry(() => fetchData());
+ * ```
+ */
+export class ErrorHandlingPlugin extends AbstractPlugin<
+  IErrorHandlingPluginOptions,
+  IErrorHandlingPluginStats
+> {
+  name = 'ErrorHandlingPlugin';
+  version = '1.0.0';
+
+  private pluginOptions: Required<Omit<IErrorHandlingPluginOptions, 'customErrorHandler'>> & {
+    customErrorHandler?: (error: Error, context: IErrorHandlingContextData) => Promise<void>;
+  };
+  private logger: ILogger;
+  private failureCount = 0;
+  private circuitBreakerOpen = false;
+  private lastFailureTime = 0;
+
+  constructor(options: IErrorHandlingPluginOptions) {
+    super();
+    this.logger = createLogger('ErrorHandlingPlugin');
+
+    // Validate options
+    validateErrorHandlingOptions(options);
+
+    // Set defaults
+    this.pluginOptions = {
+      enabled: options.enabled ?? true,
+      strategy: options.strategy,
+      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      retryDelay: options.retryDelay ?? DEFAULT_RETRY_DELAY_MS,
+      logErrors: options.logErrors ?? true,
+      failureThreshold: options.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD,
+      circuitBreakerTimeout: options.circuitBreakerTimeout ?? DEFAULT_CIRCUIT_BREAKER_TIMEOUT_MS,
+      // Add plugin options defaults
+      category: options.category ?? PluginCategory.ERROR_HANDLING,
+      priority: options.priority ?? PluginPriority.HIGH,
+      moduleEvents: options.moduleEvents ?? [],
+      subscribeToAllModuleEvents: options.subscribeToAllModuleEvents ?? false,
+      ...(options.customErrorHandler && { customErrorHandler: options.customErrorHandler }),
+    };
+
+    this.logger.info('ErrorHandlingPlugin initialized', {
+      strategy: this.pluginOptions.strategy,
+      maxRetries: this.pluginOptions.maxRetries,
+      failureThreshold: this.pluginOptions.failureThreshold,
+    });
+  }
+
+  /**
+   * Dispatches the error to the active strategy handler. If a custom error
+   * handler is configured, it takes precedence over strategy-specific handling.
+   */
+  async handleError(error: Error, context: IErrorHandlingContextData = {}): Promise<void> {
+    if (this.pluginOptions.logErrors) {
+      this.logger.error('Error occurred', {
+        error: error.message,
+        stack: error.stack,
+        context: context,
+      });
+    }
+
+    // Custom error handler takes precedence
+    if (this.pluginOptions.customErrorHandler) {
+      try {
+        await this.pluginOptions.customErrorHandler(error, context);
+        return;
+      } catch (handlerError) {
+        this.logger.error('Custom error handler failed', {
+          handlerError: handlerError instanceof Error ? handlerError.message : String(handlerError),
+        });
+      }
+    }
+
+    // Apply strategy-specific handling
+    switch (this.pluginOptions.strategy) {
+      case 'circuit-breaker':
+        await this.handleCircuitBreaker(error, context);
+        break;
+      case 'exponential-backoff':
+        await this.handleExponentialBackoff(error, context);
+        break;
+      case 'simple':
+        await this.handleSimple(error, context);
+        break;
+      case 'silent':
+        // Silent mode - do nothing
+        break;
+    }
+  }
+
+  /**
+   * Executes a function with automatic retries up to
+   * {@link IErrorHandlingPluginOptions.maxRetries | maxRetries}. The delay
+   * between retries follows the configured strategy (fixed for simple /
+   * circuit-breaker, doubling for exponential-backoff).
+   *
+   * @throws PluginError after all retry attempts are exhausted
+   */
+  async executeWithRetry<T>(
+    fn: () => Promise<T>,
+    context: IErrorHandlingContextData = {},
+  ): Promise<T> {
+    let lastError: Error | undefined;
+    let attempt = 0;
+
+    while (attempt <= this.pluginOptions.maxRetries) {
+      try {
+        // Check circuit breaker
+        if (this.pluginOptions.strategy === 'circuit-breaker') {
+          const cbState = isCircuitBreakerStillOpen(
+            this.circuitBreakerOpen,
+            this.lastFailureTime,
+            this.pluginOptions.circuitBreakerTimeout,
+          );
+          if (cbState.shouldReset) {
+            this.circuitBreakerOpen = false;
+            this.failureCount = 0;
+            this.logger.info('Circuit breaker timeout passed, attempting to close');
+          }
+          if (cbState.open) {
+            throw new PluginError('Circuit breaker is open', this.name, toErrorContext(context));
+          }
+        }
+
+        const result = await fn();
+
+        // Reset failure count on success
+        if (attempt > 0) {
+          this.failureCount = 0;
+          this.circuitBreakerOpen = false;
+          this.logger.info('Operation succeeded after retry', {
+            attempt: attempt,
+            context: context,
+          });
+        }
+
+        return result;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        attempt++;
+
+        if (attempt <= this.pluginOptions.maxRetries) {
+          await this.handleError(lastError, { ...context, attempt });
+
+          // Calculate delay
+          const delay = resolveRetryDelay(
+            this.pluginOptions.strategy,
+            this.pluginOptions.retryDelay,
+            attempt,
+          );
+
+          this.logger.debug('Retrying operation', {
+            attempt: attempt,
+            delay: delay,
+            context: context,
+          });
+          await sleep(delay);
+        } else {
+          await this.handleError(lastError, { ...context, finalAttempt: true });
+        }
+      }
+    }
+
+    throw new PluginError(
+      `Operation failed after ${this.pluginOptions.maxRetries} retries`,
+      this.name,
+      createPluginErrorContext(context, {
+        originalError: lastError?.message || 'Unknown error',
+      }),
+    );
+  }
+
+  /**
+   * Resets the circuit breaker to closed state, clearing failure count and
+   * last failure timestamp.
+   */
+  resetCircuitBreaker(): void {
+    this.failureCount = 0;
+    this.circuitBreakerOpen = false;
+    this.lastFailureTime = 0;
+    this.logger.info('Circuit breaker reset');
+  }
+
+  /**
+   * Get error handling statistics
+   */
+  override getStats(): IErrorHandlingPluginStats {
+    const base = super.getStats();
+    return {
+      ...base,
+      failureCount: this.failureCount,
+      circuitBreakerOpen: this.circuitBreakerOpen,
+      lastFailureTime: this.lastFailureTime,
+      totalRetries: 0, // TODO: Track total retries
+      successfulRecoveries: 0, // TODO: Track successful recoveries
+    };
+  }
+
+  /**
+   * Cleanup resources
+   */
+  async destroy(): Promise<void> {
+    this.logger.info('ErrorHandlingPlugin destroyed');
+  }
+
+  private async handleSimple(error: Error, context: IErrorHandlingContextData): Promise<void> {
+    // Simple logging - no additional logic
+    this.logger.debug('Simple error handling applied', {
+      error: error.message,
+      context: context,
+    });
+  }
+
+  private async handleCircuitBreaker(
+    _error: Error,
+    context: IErrorHandlingContextData,
+  ): Promise<void> {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+
+    if (this.failureCount >= this.pluginOptions.failureThreshold) {
+      this.circuitBreakerOpen = true;
+      this.logger.warn('Circuit breaker opened', {
+        failureCount: this.failureCount,
+        threshold: this.pluginOptions.failureThreshold,
+        context: context,
+      });
+    }
+  }
+
+  private async handleExponentialBackoff(
+    _error: Error,
+    context: IErrorHandlingContextData,
+  ): Promise<void> {
+    this.failureCount++;
+    this.logger.debug('Exponential backoff error handling applied', {
+      error: _error.message,
+      failureCount: this.failureCount,
+      context: context,
+    });
+  }
+}

package/src/error-handling/index.ts

@@ -0,0 +1,9 @@
+export { ErrorHandlingPlugin } from './error-handling-plugin';
+export { toErrorContext, createPluginErrorContext } from './context-adapter';
+export type {
+  TErrorHandlingStrategy,
+  IErrorHandlingContextData,
+  IErrorHandlingPluginOptions,
+  IErrorHandlingPluginStats,
+  IErrorContextAdapter,
+} from './types';

package/src/error-handling/types.ts

@@ -0,0 +1,82 @@
+/**
+ * ErrorHandling Plugin - Type definitions for Facade pattern implementation
+ *
+ * REASON: Complex ErrorContextData compatibility issues require type adapters and unified error handling
+ * ALTERNATIVES_CONSIDERED:
+ * 1. Modify ErrorContextData type globally (breaks other components)
+ * 2. Use type assertions everywhere (reduces type safety)
+ * 3. Create complex union types (causes circular dependencies)
+ * 4. Redesign PluginError constructor (breaks existing contracts)
+ * 5. Remove context from error handling (loses debugging capability)
+ * TODO: Consider unified error context system across all plugins
+ */
+
+/**
+ * Error handling strategy types
+ */
+export type TErrorHandlingStrategy =
+  | 'simple'
+  | 'circuit-breaker'
+  | 'exponential-backoff'
+  | 'silent';
+
+/**
+ * Base error context for internal operations
+ * REASON: Optional properties and index signature for compatibility with both exactOptionalPropertyTypes and logger constraints
+ * ALTERNATIVES_CONSIDERED: Union types (breaks interface compatibility), explicit undefined (still triggers index signature rules), removing optional properties (breaks existing usage), type assertions (loses safety), intersection types (complex propagation)
+ * TODO: Consider unified error context type system across all plugins
+ */
+export interface IErrorHandlingContextData {
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  attempt?: number;
+  finalAttempt?: boolean;
+  originalError?: string;
+  [key: string]: string | number | boolean | undefined;
+}
+
+import type { IPluginOptions, IPluginStats } from '@robota-sdk/agent-core';
+
+/**
+ * Configuration options for error handling plugin
+ */
+export interface IErrorHandlingPluginOptions extends IPluginOptions {
+  /** Error handling strategy to use */
+  strategy: TErrorHandlingStrategy;
+  /** Maximum number of retry attempts */
+  maxRetries?: number;
+  /** Initial delay between retries in milliseconds */
+  retryDelay?: number;
+  /** Whether to log errors */
+  logErrors?: boolean;
+  /** Circuit breaker failure threshold */
+  failureThreshold?: number;
+  /** Circuit breaker timeout in milliseconds */
+  circuitBreakerTimeout?: number;
+  /** Custom error handler function */
+  customErrorHandler?: (error: Error, context: IErrorHandlingContextData) => Promise<void>;
+}
+
+/**
+ * Error handling plugin statistics
+ */
+export interface IErrorHandlingPluginStats extends IPluginStats {
+  failureCount: number;
+  circuitBreakerOpen: boolean;
+  lastFailureTime: number;
+  totalRetries: number;
+  successfulRecoveries: number;
+}
+
+/**
+ * Error context adapter for PluginError compatibility
+ */
+export interface IErrorContextAdapter {
+  originalError?: string;
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  attempt?: number;
+  [key: string]: string | number | boolean | Date | Error | string[] | undefined;
+}