agent-harness 0.2.1

data/lib/agent_harness/providers/registry.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module AgentHarness
+  module Providers
+    # Registry for provider classes
+    #
+    # Manages registration and lookup of provider classes. Supports dynamic
+    # registration of custom providers and aliasing of provider names.
+    #
+    # @example Registering a custom provider
+    #   AgentHarness::Providers::Registry.instance.register(:my_provider, MyProviderClass)
+    #
+    # @example Looking up a provider
+    #   klass = AgentHarness::Providers::Registry.instance.get(:claude)
+    class Registry
+      include Singleton
+
+      def initialize
+        @providers = {}
+        @aliases = {}
+        @builtin_registered = false
+      end
+
+      # Register a provider class
+      #
+      # @param name [Symbol, String] the provider name
+      # @param klass [Class] the provider class
+      # @param aliases [Array<Symbol, String>] alternative names
+      # @return [void]
+      def register(name, klass, aliases: [])
+        name = name.to_sym
+        validate_provider_class!(klass)
+
+        @providers[name] = klass
+
+        aliases.each do |alias_name|
+          @aliases[alias_name.to_sym] = name
+        end
+
+        AgentHarness.logger&.debug("[AgentHarness::Registry] Registered provider: #{name}")
+      end
+
+      # Get provider class by name
+      #
+      # @param name [Symbol, String] the provider name
+      # @return [Class] the provider class
+      # @raise [ConfigurationError] if provider not found
+      def get(name)
+        ensure_builtin_providers_registered
+        name = resolve_alias(name.to_sym)
+        @providers[name] || raise(ConfigurationError, "Unknown provider: #{name}")
+      end
+
+      # Check if provider is registered
+      #
+      # @param name [Symbol, String] the provider name
+      # @return [Boolean] true if registered
+      def registered?(name)
+        ensure_builtin_providers_registered
+        name = resolve_alias(name.to_sym)
+        @providers.key?(name)
+      end
+
+      # List all registered provider names
+      #
+      # @return [Array<Symbol>] provider names
+      def all
+        ensure_builtin_providers_registered
+        @providers.keys
+      end
+
+      # List available providers (CLI installed)
+      #
+      # @return [Array<Symbol>] available provider names
+      def available
+        ensure_builtin_providers_registered
+        @providers.select { |_, klass| klass.available? }.keys
+      end
+
+      # Reset registry (useful for testing)
+      #
+      # @return [void]
+      def reset!
+        @providers.clear
+        @aliases.clear
+        @builtin_registered = false
+      end
+
+      private
+
+      def resolve_alias(name)
+        @aliases[name] || name
+      end
+
+      def validate_provider_class!(klass)
+        includes_adapter = klass.included_modules.include?(Adapter)
+        has_required_methods = klass.respond_to?(:provider_name) &&
+          klass.respond_to?(:available?) &&
+          klass.respond_to?(:binary_name)
+
+        return if includes_adapter || has_required_methods
+
+        raise ConfigurationError, "Provider class must include AgentHarness::Providers::Adapter or implement required class methods"
+      end
+
+      def ensure_builtin_providers_registered
+        return if @builtin_registered
+
+        register_builtin_providers
+        @builtin_registered = true
+      end
+
+      def register_builtin_providers
+        # Only register providers that exist
+        # These will be loaded on demand
+        register_if_available(:claude, "agent_harness/providers/anthropic", :Anthropic, aliases: [:anthropic])
+        register_if_available(:cursor, "agent_harness/providers/cursor", :Cursor)
+        register_if_available(:gemini, "agent_harness/providers/gemini", :Gemini)
+        register_if_available(:github_copilot, "agent_harness/providers/github_copilot", :GithubCopilot, aliases: [:copilot])
+        register_if_available(:codex, "agent_harness/providers/codex", :Codex)
+        register_if_available(:opencode, "agent_harness/providers/opencode", :Opencode)
+        register_if_available(:kilocode, "agent_harness/providers/kilocode", :Kilocode)
+        register_if_available(:aider, "agent_harness/providers/aider", :Aider)
+      end
+
+      def register_if_available(name, require_path, class_name, aliases: [])
+        require_relative require_path.sub("agent_harness/providers/", "")
+        klass = AgentHarness::Providers.const_get(class_name)
+        register(name, klass, aliases: aliases)
+      rescue LoadError, NameError => e
+        AgentHarness.logger&.debug("[AgentHarness::Registry] Provider #{name} not available: #{e.message}")
+      end
+    end
+  end
+end

data/lib/agent_harness/response.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Response object returned from provider send_message calls
+  #
+  # Contains the output, status, and metadata from a provider interaction.
+  #
+  # @example
+  #   response = provider.send_message(prompt: "Hello")
+  #   if response.success?
+  #     puts response.output
+  #   else
+  #     puts "Error: #{response.error}"
+  #   end
+  class Response
+    attr_reader :output, :exit_code, :duration, :provider, :model
+    attr_reader :tokens, :metadata, :error
+
+    # Create a new Response
+    #
+    # @param output [String] the output from the provider
+    # @param exit_code [Integer] the exit code (0 for success)
+    # @param duration [Float] execution duration in seconds
+    # @param provider [Symbol, String] the provider name
+    # @param model [String, nil] the model used
+    # @param tokens [Hash, nil] token usage information
+    # @param metadata [Hash] additional metadata
+    # @param error [String, nil] error message if failed
+    def initialize(output:, exit_code:, duration:, provider:, model: nil,
+      tokens: nil, metadata: {}, error: nil)
+      @output = output
+      @exit_code = exit_code
+      @duration = duration
+      @provider = provider.to_sym
+      @model = model
+      @tokens = tokens
+      @metadata = metadata
+      @error = error
+    end
+
+    # Check if the response indicates success
+    #
+    # @return [Boolean] true if exit_code is 0 and no error
+    def success?
+      @exit_code == 0 && @error.nil?
+    end
+
+    # Check if the response indicates failure
+    #
+    # @return [Boolean] true if not successful
+    def failed?
+      !success?
+    end
+
+    # Get total tokens used
+    #
+    # @return [Integer, nil] total tokens or nil if not tracked
+    def total_tokens
+      @tokens&.[](:total)
+    end
+
+    # Get input tokens used
+    #
+    # @return [Integer, nil] input tokens or nil if not tracked
+    def input_tokens
+      @tokens&.[](:input)
+    end
+
+    # Get output tokens used
+    #
+    # @return [Integer, nil] output tokens or nil if not tracked
+    def output_tokens
+      @tokens&.[](:output)
+    end
+
+    # Convert to hash representation
+    #
+    # @return [Hash] hash representation of the response
+    def to_h
+      {
+        output: @output,
+        exit_code: @exit_code,
+        duration: @duration,
+        provider: @provider,
+        model: @model,
+        tokens: @tokens,
+        metadata: @metadata,
+        error: @error,
+        success: success?
+      }
+    end
+
+    # String representation for debugging
+    #
+    # @return [String] debug string
+    def inspect
+      "#<AgentHarness::Response provider=#{@provider} success=#{success?} duration=#{@duration.round(2)}s>"
+    end
+  end
+end

data/lib/agent_harness/token_tracker.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module AgentHarness
+  # Tracks token usage across provider interactions
+  #
+  # Provides in-memory tracking of token usage with support for callbacks
+  # when tokens are used. Consumers can register callbacks to persist
+  # usage data externally.
+  #
+  # @example Basic usage
+  #   tracker = AgentHarness::TokenTracker.new
+  #   tracker.record(provider: :claude, input_tokens: 100, output_tokens: 50)
+  #   puts tracker.summary
+  #
+  # @example With callback
+  #   tracker.on_tokens_used do |event|
+  #     MyDatabase.save_usage(event)
+  #   end
+  class TokenTracker
+    # Token usage event structure
+    TokenEvent = Struct.new(
+      :provider, :model, :input_tokens, :output_tokens, :total_tokens,
+      :timestamp, :request_id,
+      keyword_init: true
+    )
+
+    def initialize
+      @events = []
+      @callbacks = []
+      @mutex = Mutex.new
+    end
+
+    # Record token usage
+    #
+    # @param provider [Symbol, String] the provider name
+    # @param model [String, nil] the model used
+    # @param input_tokens [Integer] input tokens used
+    # @param output_tokens [Integer] output tokens used
+    # @param total_tokens [Integer, nil] total tokens (calculated if nil)
+    # @param request_id [String, nil] unique request ID (generated if nil)
+    # @return [TokenEvent] the recorded event
+    def record(provider:, model: nil, input_tokens: 0, output_tokens: 0, total_tokens: nil, request_id: nil)
+      total = total_tokens || (input_tokens + output_tokens)
+
+      event = TokenEvent.new(
+        provider: provider.to_sym,
+        model: model,
+        input_tokens: input_tokens,
+        output_tokens: output_tokens,
+        total_tokens: total,
+        timestamp: Time.now,
+        request_id: request_id || SecureRandom.uuid
+      )
+
+      @mutex.synchronize do
+        @events << event
+      end
+
+      # Notify callbacks
+      notify_callbacks(event)
+
+      event
+    end
+
+    # Get usage summary
+    #
+    # @param since [Time, nil] only include events after this time
+    # @param provider [Symbol, String, nil] filter by provider
+    # @return [Hash] usage summary
+    def summary(since: nil, provider: nil)
+      events = filtered_events(since: since, provider: provider)
+
+      {
+        total_requests: events.size,
+        total_input_tokens: events.sum(&:input_tokens),
+        total_output_tokens: events.sum(&:output_tokens),
+        total_tokens: events.sum(&:total_tokens),
+        by_provider: group_by_provider(events),
+        by_model: group_by_model(events)
+      }
+    end
+
+    # Get recent events
+    #
+    # @param limit [Integer] maximum number of events to return
+    # @return [Array<TokenEvent>] recent events
+    def recent_events(limit: 100)
+      @mutex.synchronize do
+        @events.last(limit)
+      end
+    end
+
+    # Register callback for token events
+    #
+    # @yield [TokenEvent] called when tokens are recorded
+    # @return [void]
+    def on_tokens_used(&block)
+      @callbacks << block
+    end
+
+    # Clear all recorded events
+    #
+    # @return [void]
+    def clear!
+      @mutex.synchronize do
+        @events.clear
+      end
+    end
+
+    # Get total token count
+    #
+    # @param since [Time, nil] only include events after this time
+    # @return [Integer] total tokens used
+    def total_tokens(since: nil)
+      filtered_events(since: since).sum(&:total_tokens)
+    end
+
+    # Get event count
+    #
+    # @return [Integer] number of recorded events
+    def event_count
+      @mutex.synchronize do
+        @events.size
+      end
+    end
+
+    private
+
+    def filtered_events(since: nil, provider: nil)
+      @mutex.synchronize do
+        events = @events.dup
+        events = events.select { |e| e.timestamp >= since } if since
+        events = events.select { |e| e.provider.to_s == provider.to_s } if provider
+        events
+      end
+    end
+
+    def group_by_provider(events)
+      events.group_by(&:provider).transform_values do |provider_events|
+        {
+          requests: provider_events.size,
+          input_tokens: provider_events.sum(&:input_tokens),
+          output_tokens: provider_events.sum(&:output_tokens),
+          total_tokens: provider_events.sum(&:total_tokens)
+        }
+      end
+    end
+
+    def group_by_model(events)
+      events.group_by { |e| "#{e.provider}:#{e.model}" }.transform_values do |model_events|
+        {
+          requests: model_events.size,
+          input_tokens: model_events.sum(&:input_tokens),
+          output_tokens: model_events.sum(&:output_tokens),
+          total_tokens: model_events.sum(&:total_tokens)
+        }
+      end
+    end
+
+    def notify_callbacks(event)
+      @callbacks.each do |callback|
+        callback.call(event)
+      rescue => e
+        AgentHarness.logger&.error("[AgentHarness::TokenTracker] Callback error: #{e.message}")
+      end
+    end
+  end
+end

data/lib/agent_harness/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  VERSION = "0.2.1"
+end

data/lib/agent_harness.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "agent_harness/version"
+
+# AgentHarness provides a unified interface for CLI-based AI coding agents.
+#
+# It offers:
+# - Unified interface for multiple AI coding agents (Claude Code, Cursor, Gemini CLI, etc.)
+# - Full orchestration layer with provider switching, circuit breakers, and health monitoring
+# - Flexible configuration via YAML, Ruby DSL, or environment variables
+# - Dynamic provider registration for custom provider support
+# - Token usage tracking for cost and limit calculations
+#
+# @example Basic usage
+#   AgentHarness.send_message("Write a hello world function", provider: :claude)
+#
+# @example With configuration
+#   AgentHarness.configure do |config|
+#     config.logger = Logger.new(STDOUT)
+#     config.default_provider = :cursor
+#   end
+#
+# @example Direct provider access
+#   provider = AgentHarness.provider(:claude)
+#   provider.send_message(prompt: "Hello")
+#
+module AgentHarness
+  class Error < StandardError; end
+
+  class << self
+    # Returns the global configuration instance
+    # @return [Configuration] the configuration object
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure AgentHarness with a block
+    # @yield [Configuration] the configuration object
+    # @return [void]
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    # Reset configuration to defaults (useful for testing)
+    # @return [void]
+    def reset!
+      @configuration = nil
+      @conductor = nil
+      @token_tracker = nil
+    end
+
+    # Returns the global logger
+    # @return [Logger, nil] the configured logger
+    def logger
+      configuration.logger
+    end
+
+    # Returns the global token tracker
+    # @return [TokenTracker] the token tracker instance
+    def token_tracker
+      @token_tracker ||= TokenTracker.new
+    end
+
+    # Returns the global conductor for orchestrated requests
+    # @return [Orchestration::Conductor] the conductor instance
+    def conductor
+      @conductor ||= Orchestration::Conductor.new(config: configuration)
+    end
+
+    # Send a message using the orchestration layer
+    # @param prompt [String] the prompt to send
+    # @param provider [Symbol, nil] optional provider override
+    # @param options [Hash] additional options
+    # @return [Response] the response from the provider
+    def send_message(prompt, provider: nil, **options)
+      conductor.send_message(prompt, provider: provider, **options)
+    end
+
+    # Get a provider instance
+    # @param name [Symbol] the provider name
+    # @return [Providers::Base] the provider instance
+    def provider(name)
+      conductor.provider_manager.get_provider(name)
+    end
+  end
+end
+
+# Core components
+require_relative "agent_harness/errors"
+require_relative "agent_harness/configuration"
+require_relative "agent_harness/command_executor"
+require_relative "agent_harness/response"
+require_relative "agent_harness/token_tracker"
+require_relative "agent_harness/error_taxonomy"
+
+# Provider layer
+require_relative "agent_harness/providers/registry"
+require_relative "agent_harness/providers/adapter"
+require_relative "agent_harness/providers/base"
+require_relative "agent_harness/providers/anthropic"
+require_relative "agent_harness/providers/aider"
+require_relative "agent_harness/providers/codex"
+require_relative "agent_harness/providers/cursor"
+require_relative "agent_harness/providers/gemini"
+require_relative "agent_harness/providers/github_copilot"
+require_relative "agent_harness/providers/kilocode"
+require_relative "agent_harness/providers/opencode"
+
+# Orchestration layer
+require_relative "agent_harness/orchestration/circuit_breaker"
+require_relative "agent_harness/orchestration/rate_limiter"
+require_relative "agent_harness/orchestration/health_monitor"
+require_relative "agent_harness/orchestration/metrics"
+require_relative "agent_harness/orchestration/provider_manager"
+require_relative "agent_harness/orchestration/conductor"

data/release-please-config.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "agent-harness",
+      "version-file": "lib/agent_harness/version.rb",
+      "extra-files": ["Gemfile.lock"],
+      "changelog-sections": [
+        {
+          "type": "feat",
+          "section": "Features",
+          "hidden": false
+        },
+        {
+          "type": "fix",
+          "section": "Bug Fixes",
+          "hidden": false
+        },
+        {
+          "type": "refactor",
+          "section": "Improvements",
+          "hidden": false
+        },
+        {
+          "type": "chore",
+          "section": "Maintenance",
+          "hidden": true
+        },
+        {
+          "type": "docs",
+          "section": "Documentation",
+          "hidden": false
+        },
+        {
+          "type": "test",
+          "section": "Testing",
+          "hidden": true
+        },
+        {
+          "type": "spec",
+          "section": "Test Specifications",
+          "hidden": true
+        },
+        {
+          "type": "ci",
+          "section": "CI/CD",
+          "hidden": true
+        },
+        {
+          "type": "deps",
+          "section": "Dependencies",
+          "hidden": false
+        },
+        {
+          "type": "BREAKING CHANGE",
+          "section": "Breaking Changes",
+          "hidden": false
+        }
+      ]
+    }
+  }
+}