agent-harness 0.2.1

data/lib/agent_harness/configuration.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Configuration for AgentHarness
+  #
+  # Supports configuration via Ruby DSL, YAML files, and environment variables.
+  # Configuration sources are merged with priority: Ruby DSL > YAML > Environment.
+  #
+  # @example Ruby DSL configuration
+  #   AgentHarness.configure do |config|
+  #     config.logger = Logger.new(STDOUT)
+  #     config.default_provider = :cursor
+  #     config.fallback_providers = [:claude, :gemini]
+  #
+  #     config.provider :claude do |p|
+  #       p.enabled = true
+  #       p.timeout = 600
+  #     end
+  #   end
+  class Configuration
+    attr_accessor :logger, :log_level, :default_provider, :fallback_providers
+    attr_accessor :config_file_path, :default_timeout
+    attr_writer :command_executor
+
+    attr_reader :providers, :orchestration_config, :callbacks, :custom_provider_classes
+
+    def initialize
+      @logger = nil # Will use null logger if not set
+      @log_level = :info
+      @default_provider = :cursor
+      @fallback_providers = []
+      @command_executor = nil # Lazy-initialized
+      @config_file_path = nil
+      @default_timeout = 300
+      @providers = {}
+      @orchestration_config = OrchestrationConfig.new
+      @callbacks = CallbackRegistry.new
+      @custom_provider_classes = {}
+    end
+
+    # Get or lazily initialize the command executor
+    #
+    # @return [CommandExecutor] the command executor
+    def command_executor
+      @command_executor ||= CommandExecutor.new(logger: @logger)
+    end
+
+    # Configure orchestration settings
+    #
+    # @yield [OrchestrationConfig] the orchestration configuration
+    # @return [OrchestrationConfig] the orchestration configuration
+    def orchestration(&block)
+      yield(@orchestration_config) if block_given?
+      @orchestration_config
+    end
+
+    # Configure a provider
+    #
+    # @param name [Symbol, String] the provider name
+    # @yield [ProviderConfig] the provider configuration
+    # @return [ProviderConfig] the provider configuration
+    def provider(name, &block)
+      config = ProviderConfig.new(name)
+      yield(config) if block_given?
+      @providers[name.to_sym] = config
+    end
+
+    # Register a custom provider class
+    #
+    # @param name [Symbol, String] the provider name
+    # @param klass [Class] the provider class
+    # @return [void]
+    def register_provider(name, klass)
+      @custom_provider_classes[name.to_sym] = klass
+    end
+
+    # Register callback for token usage events
+    #
+    # @yield [TokenEvent] called when tokens are used
+    # @return [void]
+    def on_tokens_used(&block)
+      @callbacks.register(:tokens_used, block)
+    end
+
+    # Register callback for provider switch events
+    #
+    # @yield [Hash] event data with :from_provider, :to_provider, :reason
+    # @return [void]
+    def on_provider_switch(&block)
+      @callbacks.register(:provider_switch, block)
+    end
+
+    # Register callback for circuit open events
+    #
+    # @yield [Hash] event data with :provider, :failure_count
+    # @return [void]
+    def on_circuit_open(&block)
+      @callbacks.register(:circuit_open, block)
+    end
+
+    # Register callback for circuit close events
+    #
+    # @yield [Hash] event data with :provider
+    # @return [void]
+    def on_circuit_close(&block)
+      @callbacks.register(:circuit_close, block)
+    end
+
+    # Validate the configuration
+    #
+    # @raise [ConfigurationError] if configuration is invalid
+    # @return [void]
+    def validate!
+      errors = []
+
+      errors << "No providers configured" if @providers.empty?
+      errors << "Default provider '#{@default_provider}' not configured" unless @providers[@default_provider]
+
+      raise ConfigurationError, errors.join(", ") unless errors.empty?
+    end
+
+    # Check if configuration is valid
+    #
+    # @return [Boolean] true if valid
+    def valid?
+      validate!
+      true
+    rescue ConfigurationError
+      false
+    end
+  end
+
+  # Orchestration configuration
+  class OrchestrationConfig
+    attr_accessor :enabled, :auto_switch_on_error, :auto_switch_on_rate_limit
+
+    attr_reader :circuit_breaker_config, :retry_config, :rate_limit_config, :health_check_config
+
+    def initialize
+      @enabled = true
+      @auto_switch_on_error = true
+      @auto_switch_on_rate_limit = true
+      @circuit_breaker_config = CircuitBreakerConfig.new
+      @retry_config = RetryConfig.new
+      @rate_limit_config = RateLimitConfig.new
+      @health_check_config = HealthCheckConfig.new
+    end
+
+    # Configure circuit breaker
+    #
+    # @yield [CircuitBreakerConfig] the circuit breaker configuration
+    # @return [CircuitBreakerConfig]
+    def circuit_breaker(&block)
+      yield(@circuit_breaker_config) if block_given?
+      @circuit_breaker_config
+    end
+
+    # Configure retry behavior
+    #
+    # @yield [RetryConfig] the retry configuration
+    # @return [RetryConfig]
+    def retry(&block)
+      yield(@retry_config) if block_given?
+      @retry_config
+    end
+
+    # Configure rate limiting
+    #
+    # @yield [RateLimitConfig] the rate limit configuration
+    # @return [RateLimitConfig]
+    def rate_limit(&block)
+      yield(@rate_limit_config) if block_given?
+      @rate_limit_config
+    end
+
+    # Configure health checking
+    #
+    # @yield [HealthCheckConfig] the health check configuration
+    # @return [HealthCheckConfig]
+    def health_check(&block)
+      yield(@health_check_config) if block_given?
+      @health_check_config
+    end
+  end
+
+  # Circuit breaker configuration
+  class CircuitBreakerConfig
+    attr_accessor :enabled, :failure_threshold, :timeout, :half_open_max_calls
+
+    def initialize
+      @enabled = true
+      @failure_threshold = 5
+      @timeout = 300 # 5 minutes
+      @half_open_max_calls = 3
+    end
+  end
+
+  # Retry configuration
+  class RetryConfig
+    attr_accessor :enabled, :max_attempts, :base_delay, :max_delay, :exponential_base, :jitter
+
+    def initialize
+      @enabled = true
+      @max_attempts = 3
+      @base_delay = 1.0
+      @max_delay = 60.0
+      @exponential_base = 2.0
+      @jitter = true
+    end
+  end
+
+  # Rate limit configuration
+  class RateLimitConfig
+    attr_accessor :enabled, :default_reset_time
+
+    def initialize
+      @enabled = true
+      @default_reset_time = 3600 # 1 hour
+    end
+  end
+
+  # Health check configuration
+  class HealthCheckConfig
+    attr_accessor :enabled, :interval, :failure_threshold
+
+    def initialize
+      @enabled = true
+      @interval = 60 # 1 minute
+      @failure_threshold = 3
+    end
+  end
+
+  # Provider-specific configuration
+  class ProviderConfig
+    attr_accessor :enabled, :type, :priority, :models, :default_flags, :timeout, :model
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name.to_sym
+      @enabled = true
+      @type = :usage_based
+      @priority = 10
+      @models = []
+      @default_flags = []
+      @timeout = nil
+      @model = nil
+    end
+
+    # Merge options into this configuration
+    #
+    # @param options [Hash] options to merge
+    # @return [self]
+    def merge!(options)
+      options.each do |key, value|
+        setter = "#{key}="
+        send(setter, value) if respond_to?(setter)
+      end
+      self
+    end
+  end
+
+  # Registry for event callbacks
+  class CallbackRegistry
+    def initialize
+      @callbacks = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Register a callback for an event
+    #
+    # @param event [Symbol] the event name
+    # @param block [Proc] the callback
+    # @return [void]
+    def register(event, block)
+      @callbacks[event] << block
+    end
+
+    # Emit an event to all registered callbacks
+    #
+    # @param event [Symbol] the event name
+    # @param data [Hash] event data
+    # @return [void]
+    def emit(event, data)
+      @callbacks[event].each do |callback|
+        callback.call(data)
+      rescue => e
+        AgentHarness.logger&.error("[AgentHarness::CallbackRegistry] Callback error for #{event}: #{e.message}")
+      end
+    end
+
+    # Check if any callbacks are registered for an event
+    #
+    # @param event [Symbol] the event name
+    # @return [Boolean] true if callbacks exist
+    def registered?(event)
+      @callbacks[event].any?
+    end
+  end
+end

data/lib/agent_harness/error_taxonomy.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Error classification system for categorizing and handling errors
+  #
+  # Provides a standardized way to classify errors from different providers
+  # into actionable categories for retry logic, provider switching, and
+  # error reporting.
+  module ErrorTaxonomy
+    # Error categories with their metadata
+    CATEGORIES = {
+      rate_limited: {
+        description: "Rate limit exceeded",
+        action: :switch_provider,
+        retryable: false
+      },
+      auth_expired: {
+        description: "Authentication failed or expired",
+        action: :switch_provider,
+        retryable: false
+      },
+      quota_exceeded: {
+        description: "Usage quota exceeded",
+        action: :switch_provider,
+        retryable: false
+      },
+      transient: {
+        description: "Temporary error",
+        action: :retry_with_backoff,
+        retryable: true
+      },
+      permanent: {
+        description: "Unrecoverable error",
+        action: :escalate,
+        retryable: false
+      },
+      timeout: {
+        description: "Operation timed out",
+        action: :retry_with_backoff,
+        retryable: true
+      },
+      unknown: {
+        description: "Unknown error",
+        action: :retry_with_backoff,
+        retryable: true
+      }
+    }.freeze
+
+    class << self
+      # Classify an error based on provider patterns
+      #
+      # @param error [Exception] the error to classify
+      # @param patterns [Hash<Symbol, Array<Regexp>>] provider-specific patterns
+      # @return [Symbol] error category
+      def classify(error, patterns = {})
+        message = error.message.to_s.downcase
+
+        # Check provider-specific patterns first
+        patterns.each do |category, regexes|
+          return category if regexes.any? { |r| message.match?(r) }
+        end
+
+        # Fall back to generic patterns
+        classify_generic(message)
+      end
+
+      # Classify a message string into error category
+      #
+      # @param message [String] the error message
+      # @return [Symbol] error category
+      def classify_message(message)
+        classify_generic(message.to_s.downcase)
+      end
+
+      # Get recommended action for error category
+      #
+      # @param category [Symbol] the error category
+      # @return [Symbol] recommended action
+      def action_for(category)
+        CATEGORIES.dig(category, :action) || :escalate
+      end
+
+      # Check if error category is retryable
+      #
+      # @param category [Symbol] the error category
+      # @return [Boolean] true if the error can be retried
+      def retryable?(category)
+        CATEGORIES.dig(category, :retryable) || false
+      end
+
+      # Get description for error category
+      #
+      # @param category [Symbol] the error category
+      # @return [String] human-readable description
+      def description_for(category)
+        CATEGORIES.dig(category, :description) || "Unknown error"
+      end
+
+      # Get all category names
+      #
+      # @return [Array<Symbol>] list of category names
+      def categories
+        CATEGORIES.keys
+      end
+
+      private
+
+      def classify_generic(message)
+        case message
+        when /rate.?limit|too many requests|429/i
+          :rate_limited
+        when /quota|usage.?limit|billing/i
+          :quota_exceeded
+        when /auth|unauthorized|forbidden|invalid.*(key|token)|401|403/i
+          :auth_expired
+        when /timeout|timed.?out/i
+          :timeout
+        when /temporary|retry|503|502|500/i
+          :transient
+        when /invalid|malformed|bad.?request|400/i
+          :permanent
+        else
+          :unknown
+        end
+      end
+    end
+  end
+end

data/lib/agent_harness/errors.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Base error class for all AgentHarness errors
+  class Error < StandardError
+    attr_reader :original_error, :context
+
+    def initialize(message = nil, original_error: nil, context: {})
+      @original_error = original_error
+      @context = context
+      super(message)
+    end
+  end
+
+  # Provider-related errors
+  class ProviderError < Error; end
+
+  class ProviderNotFoundError < ProviderError; end
+
+  class ProviderUnavailableError < ProviderError; end
+
+  # Execution errors
+  class TimeoutError < Error; end
+
+  class CommandExecutionError < Error; end
+
+  # Rate limiting and circuit breaker errors
+  class RateLimitError < Error
+    attr_reader :reset_time, :provider
+
+    def initialize(message = nil, reset_time: nil, provider: nil, **kwargs)
+      @reset_time = reset_time
+      @provider = provider
+      super(message, **kwargs)
+    end
+  end
+
+  class CircuitOpenError < Error
+    attr_reader :provider
+
+    def initialize(message = nil, provider: nil, **kwargs)
+      @provider = provider
+      super(message, **kwargs)
+    end
+  end
+
+  # Authentication errors
+  class AuthenticationError < Error; end
+
+  # Configuration errors
+  class ConfigurationError < Error; end
+
+  # Orchestration errors
+  class NoProvidersAvailableError < Error
+    attr_reader :attempted_providers, :errors
+
+    def initialize(message = nil, attempted_providers: [], errors: {}, **kwargs)
+      @attempted_providers = attempted_providers
+      @errors = errors
+      super(message, **kwargs)
+    end
+  end
+end

data/lib/agent_harness/orchestration/circuit_breaker.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module Orchestration
+    # Circuit breaker for provider fault tolerance
+    #
+    # Implements the circuit breaker pattern to prevent cascading failures.
+    # The circuit has three states:
+    # - :closed - Normal operation, requests pass through
+    # - :open - Failures exceeded threshold, requests are blocked
+    # - :half_open - After timeout, limited requests allowed to test recovery
+    #
+    # @example
+    #   breaker = CircuitBreaker.new(failure_threshold: 5, timeout: 300)
+    #   breaker.record_failure
+    #   breaker.open? # => false (still below threshold)
+    class CircuitBreaker
+      STATES = [:closed, :open, :half_open].freeze
+
+      attr_reader :state, :failure_count, :success_count
+
+      # Create a new circuit breaker
+      #
+      # @param config [CircuitBreakerConfig, nil] configuration object
+      # @param failure_threshold [Integer] failures before opening
+      # @param timeout [Integer] seconds before half-open transition
+      # @param half_open_max_calls [Integer] successful calls to close
+      def initialize(config = nil, failure_threshold: nil, timeout: nil, half_open_max_calls: nil)
+        if config
+          @enabled = config.enabled
+          @failure_threshold = config.failure_threshold
+          @timeout = config.timeout
+          @half_open_max_calls = config.half_open_max_calls
+        else
+          @enabled = true
+          @failure_threshold = failure_threshold || 5
+          @timeout = timeout || 300
+          @half_open_max_calls = half_open_max_calls || 3
+        end
+
+        reset!
+      end
+
+      # Check if circuit is open (blocking requests)
+      #
+      # @return [Boolean] true if open
+      def open?
+        return false unless @enabled
+
+        if @state == :open && timeout_elapsed?
+          transition_to(:half_open)
+        end
+
+        @state == :open
+      end
+
+      # Check if circuit is closed (allowing requests)
+      #
+      # @return [Boolean] true if closed
+      def closed?
+        @state == :closed
+      end
+
+      # Check if circuit is half-open (testing recovery)
+      #
+      # @return [Boolean] true if half-open
+      def half_open?
+        @state == :half_open
+      end
+
+      # Record a successful call
+      #
+      # @return [void]
+      def record_success
+        @mutex.synchronize do
+          @success_count += 1
+
+          if @state == :half_open && @success_count >= @half_open_max_calls
+            transition_to(:closed)
+          end
+        end
+      end
+
+      # Record a failed call
+      #
+      # @return [void]
+      def record_failure
+        @mutex.synchronize do
+          @failure_count += 1
+
+          if @failure_count >= @failure_threshold
+            transition_to(:open)
+          end
+        end
+      end
+
+      # Reset the circuit breaker to initial state
+      #
+      # @return [void]
+      def reset!
+        @mutex = Mutex.new
+        @state = :closed
+        @failure_count = 0
+        @success_count = 0
+        @opened_at = nil
+      end
+
+      # Get time until circuit attempts recovery
+      #
+      # @return [Integer, nil] seconds until half-open, or nil if not open
+      def time_until_recovery
+        return nil unless @state == :open && @opened_at
+
+        remaining = @timeout - (Time.now - @opened_at)
+        remaining.positive? ? remaining.to_i : 0
+      end
+
+      # Get circuit status
+      #
+      # @return [Hash] status information
+      def status
+        {
+          state: @state,
+          failure_count: @failure_count,
+          success_count: @success_count,
+          failure_threshold: @failure_threshold,
+          timeout: @timeout,
+          time_until_recovery: time_until_recovery,
+          enabled: @enabled
+        }
+      end
+
+      private
+
+      def transition_to(new_state)
+        old_state = @state
+        @state = new_state
+
+        case new_state
+        when :open
+          @opened_at = Time.now
+          @failure_count = 0
+          emit_event(:circuit_open, old_state: old_state)
+        when :half_open
+          @success_count = 0
+          emit_event(:circuit_half_open, old_state: old_state)
+        when :closed
+          @failure_count = 0
+          @success_count = 0
+          @opened_at = nil
+          emit_event(:circuit_close, old_state: old_state)
+        end
+
+        AgentHarness.logger&.info(
+          "[AgentHarness::CircuitBreaker] State transition: #{old_state} -> #{new_state}"
+        )
+      end
+
+      def timeout_elapsed?
+        return true unless @opened_at
+        Time.now - @opened_at >= @timeout
+      end
+
+      def emit_event(event, **data)
+        AgentHarness.configuration.callbacks.emit(event, data.merge(circuit_breaker: self))
+      end
+    end
+  end
+end