agent-harness 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3f57fefa5527c5cdc436d4da8c10e5f638c69363b32e689213feb9bdccadf7d
-  data.tar.gz: ae98c1fc1f1a919adf7919f8d4dc0dc308286f1cb0e02d4a719d9060e29451b4
+  metadata.gz: 16862141d853f2e8817d000a9e4813162f0544cda2c30343de2efc1ffd7e9e73
+  data.tar.gz: ee57bd3611abb7566560675c65c1feb04faee531cd182f8a8812881a73701aae
 SHA512:
-  metadata.gz: eeafca1c0fe7183572056d50caf4e30f28e7a410a5fdb0f2bd3271ae3c0ef5a679f48c559266143a14cd03130de714a6e9af286d7e6e990eb8977fa3972c74df
-  data.tar.gz: c29ad51bcd248190e44d089d28daf6914a319a800536a3dfce25be6ad9b993a1582b6f317bf7df5f0989864c0a6b663cbb76de1921155b2c2f1aad10037bdd9e
+  metadata.gz: f5145b28d2c92bef3c8ba6f8a0e8ffe2217f8eb9462c672f28d25e0f6bd6a1bb17f1fa14ae2dcf2e57d35c4fa82a6233fdf51acf7778d399c89c4412ee9c9695
+  data.tar.gz: f6f9e464d3f5f84a87f98b98dd3d0687157a1b69249a3a0731ba162653aabf6cc517430f31b0f9e9b1d3e5d67d0b767c4c5a12c4e88425bd8b24f578343a87e9

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.0"
+  ".": "0.5.1"
 }

data/.rubocop.yml

@@ -0,0 +1,2 @@
+inherit_gem:
+  standard: config/base.yml

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 ## [Unreleased]
 
+## [0.5.1](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.0...agent-harness/v0.5.1) (2026-03-24)
+
+
+### Bug Fixes
+
+* 30: fix(codex): use 'codex exec' subcommand instead of --prompt ([#35](https://github.com/viamin/agent-harness/issues/35)) ([1093a23](https://github.com/viamin/agent-harness/commit/1093a23dd001a7ea3caf13306d284fe3b5b976c5))
+* **anthropic:** use positional argument instead of --prompt for Claude CLI ([4ba59bd](https://github.com/viamin/agent-harness/commit/4ba59bd55394cf9ff1d1994ce787e0e285725b93)), closes [#29](https://github.com/viamin/agent-harness/issues/29)
+* **kilocode:** use 'kilo run' subcommand instead of --prompt flag ([f850f54](https://github.com/viamin/agent-harness/commit/f850f54cfac595fe910298303beb373c7bc68376))
+* **test:** use correct RSpec matcher `end_with` instead of `ending_with` ([3a9d68b](https://github.com/viamin/agent-harness/commit/3a9d68b90a0e788683a382303108ebe28cc24e63))
+
+## [0.5.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.4.0...agent-harness/v0.5.0) (2026-03-03)
+
+
+### Features
+
+* parse token usage from Claude CLI JSON output ([a0e6d7c](https://github.com/viamin/agent-harness/commit/a0e6d7cafb5f5b74806a44d3d4f487e87fdfa05e)), closes [#19](https://github.com/viamin/agent-harness/issues/19)
+* support authentication error detection and token refresh for CLI agents ([83f2c71](https://github.com/viamin/agent-harness/commit/83f2c71c555483322c8a19d8a6ae195bd7720296)), closes [#20](https://github.com/viamin/agent-harness/issues/20)
+
+
+### Bug Fixes
+
+* add file lock to refresh_claude_auth to prevent lost-update races ([eb00e19](https://github.com/viamin/agent-harness/commit/eb00e1935dcd574f952ea37c263e9794de23f9a7))
+* address code review feedback for authentication module ([6d11067](https://github.com/viamin/agent-harness/commit/6d1106743c79f5ae4c3a98f078e4c4d4c93db465))
+* address code review feedback for resolve_provider and conductor docs ([5975b3b](https://github.com/viamin/agent-harness/commit/5975b3b8e087f681b57cc9935499e0691f865360))
+* address PR review feedback for auth error handling ([70d7ea7](https://github.com/viamin/agent-harness/commit/70d7ea7eb4d13fd80d7c2724af57053a6dea9972))
+* address PR review feedback for authentication module ([b098682](https://github.com/viamin/agent-harness/commit/b098682448104a833a3e50c89531bcb838910b52))
+* address PR review feedback for token handling in authentication ([03398b9](https://github.com/viamin/agent-harness/commit/03398b9be4b43c12c31694d8c7864dfde891da29))
+* address remaining PR review feedback for auth behavior ([893b549](https://github.com/viamin/agent-harness/commit/893b549bb080345bb1c0dfe718bb1840ff2a1f5e))
+* align ErrorTaxonomy auth_expired action with Conductor behavior ([7697637](https://github.com/viamin/agent-harness/commit/76976375708f56c4fbcaf635bebafd8da9f35de1))
+* clear expiry metadata on token refresh and align docs with API ([9bba06e](https://github.com/viamin/agent-harness/commit/9bba06e00c7b65722afef4b4492ec777e65578e0))
+* correct method for checking module inclusion in provider validation ([4cf57fc](https://github.com/viamin/agent-harness/commit/4cf57fcebed92261e065aa6cf526f1f3851f57e7))
+* differentiate credential read errors instead of returning generic nil ([cada3c5](https://github.com/viamin/agent-harness/commit/cada3c5404144b4eaf122d5dbe5f023eb30e5d95))
+* guard against non-Hash JSON in refresh_claude_auth credentials ([74e1301](https://github.com/viamin/agent-harness/commit/74e1301ec7835f929bd43dc15f4a87e62bcf7237))
+* remove accidentally committed bundler binstubs ([8207ef0](https://github.com/viamin/agent-harness/commit/8207ef0df67add5d1db8f3af9ef495c0b832d0b6))
+* validate tokens are non-empty strings in authentication module ([55a12e4](https://github.com/viamin/agent-harness/commit/55a12e45616839079afe509e079c771a1a71a1a5))
+
 ## [0.4.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.3.0...agent-harness/v0.4.0) (2026-02-16)
 
 

data/README.md

@@ -227,6 +227,9 @@ AgentHarness.token_tracker.summary
 ```ruby
 begin
   response = AgentHarness.send_message("Hello")
+rescue AgentHarness::AuthenticationError => e
+  puts "Auth failed for provider: #{e.provider}"
+  # Optionally trigger re-auth flow (see Authentication Management below)
 rescue AgentHarness::TimeoutError => e
   puts "Request timed out"
 rescue AgentHarness::RateLimitError => e
@@ -253,6 +256,106 @@ AgentHarness::ErrorTaxonomy.action_for(category)
 # => :switch_provider
 ```
 
+## Authentication Management
+
+AgentHarness can detect authentication failures and manage credentials for CLI agents.
+
+### Auth Type
+
+Providers declare their authentication type:
+
+```ruby
+provider = AgentHarness.provider(:claude)
+provider.auth_type
+# => :oauth  (token-based auth that can expire)
+
+provider = AgentHarness.provider(:aider)
+provider.auth_type
+# => :api_key  (static API key, no refresh needed)
+```
+
+### Auth Status Check
+
+Pre-flight check auth before starting a run:
+
+```ruby
+AgentHarness.auth_valid?(:claude)
+# => true/false
+
+AgentHarness.auth_status(:claude)
+# => { valid: false, expires_at: <Time>, error: "Session expired" }
+```
+
+For providers without a built-in auth check (including `:api_key` providers), `auth_valid?` returns `false` and `auth_status` returns an error indicating the check is not implemented. Custom providers can implement an `auth_status` instance method to provide their own check.
+
+### Auth Error Detection
+
+When a CLI agent fails due to expired or invalid authentication, `send_message` raises `AuthenticationError` with the provider name. Authentication errors are always surfaced directly to the caller (never auto-switched to another provider) so your application can trigger the appropriate re-auth flow:
+
+```ruby
+begin
+  AgentHarness.send_message("Hello", provider: :claude)
+rescue AgentHarness::AuthenticationError => e
+  puts e.provider  # => :claude
+  puts e.message   # => "oauth token expired"
+  # Trigger re-authentication flow for the specific provider
+end
+```
+
+### OAuth URL Generation
+
+For OAuth providers, get the URL the user should visit to start the login flow:
+
+```ruby
+AgentHarness.auth_url(:claude)
+# => "https://claude.ai/oauth/authorize"
+```
+
+This raises `NotImplementedError` for `:api_key` providers.
+
+### Credential Refresh
+
+Accept a pre-exchanged OAuth token and update the provider's stored credentials. The OAuth authorization code exchange is provider-specific and should be handled by your application or CLI login command before calling this method:
+
+```ruby
+AgentHarness.refresh_auth(:claude, token: "new-oauth-token")
+# => { success: true }
+```
+
+Any existing expiry metadata in the credentials file is cleared on refresh so that `auth_valid?` returns `true` immediately after a successful refresh.
+
+This raises `NotImplementedError` for `:api_key` providers. Credential file paths respect the `CLAUDE_CONFIG_DIR` environment variable.
+
+## Provider Health Checks
+
+Pre-flight check that configured providers are registered and authenticated. Reachability and configuration validation depend on provider-specific `health_status` and `validate_config` overrides; providers that don't implement these use safe defaults (healthy / valid).
+
+> **Note:** These methods provide the library-level API. CLI flag (`--check-providers`) and HTTP endpoint (`GET /providers/status`) integration are not yet implemented and are tracked separately.
+
+```ruby
+# Check all enabled providers
+results = AgentHarness.check_providers
+results.each do |r|
+  puts "#{r[:name]}: #{r[:status]} - #{r[:message]} (#{r[:latency_ms]}ms)"
+end
+
+# Check a single provider
+result = AgentHarness.check_provider(:claude)
+puts result[:status]  # => "ok", "degraded", or "error"
+
+# Formatted CLI output
+puts AgentHarness::ProviderHealthCheck.format_results(results)
+```
+
+Each result is a hash with keys:
+
+- `:name` — provider name (Symbol)
+- `:status` — `"ok"` (all checks passed), `"degraded"` (partial issues such as unimplemented auth status), or `"error"` (provider unavailable or authentication failed)
+- `:message` — human-readable description
+- `:latency_ms` — time taken for the check in milliseconds
+
+Health checks run five steps per provider: registration, CLI availability, authentication, provider health status, and configuration validation. The default timeout per provider is configurable via `orchestration.health_check.timeout` (default: 5 seconds).
+
 ## Development
 
 ```bash

data/lib/agent_harness/authentication.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "tempfile"
+require "time"
+
+module AgentHarness
+  # Authentication management for CLI agent providers
+  #
+  # Provides methods for checking auth status, generating OAuth URLs,
+  # and refreshing credentials for providers that support it.
+  module Authentication
+    class << self
+      # Check if authentication is valid for a provider
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [Boolean] true if auth is valid, false otherwise
+      def auth_valid?(provider_name)
+        status = auth_status(provider_name)
+        !!status[:valid]
+      end
+
+      # Get detailed authentication status for a provider
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [Hash] status with :valid, :expires_at, :error keys
+      def auth_status(provider_name)
+        provider_name = provider_name.to_sym
+        case provider_name
+        when :claude, :anthropic
+          claude_auth_status
+        else
+          generic_auth_status(provider_name)
+        end
+      end
+
+      # Generate an OAuth URL for a provider
+      #
+      # Only supported for :oauth auth type providers.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [String] the OAuth authorization URL
+      # @raise [NotImplementedError] if provider doesn't support OAuth
+      def auth_url(provider_name)
+        provider_name = provider_name.to_sym
+        provider = resolve_provider(provider_name)
+
+        unless provider.auth_type == :oauth
+          raise NotImplementedError,
+            "Provider #{provider_name} uses #{provider.auth_type} auth and does not support OAuth URL generation"
+        end
+
+        case provider_name
+        when :claude, :anthropic
+          claude_auth_url
+        else
+          raise NotImplementedError,
+            "OAuth URL generation is not yet implemented for provider #{provider_name}"
+        end
+      end
+
+      # Refresh authentication credentials for a provider
+      #
+      # For OAuth providers, stores a pre-exchanged token directly.
+      # This method accepts a token (not an authorization code) because
+      # the OAuth code-exchange flow is provider-specific and should be
+      # handled by the caller or a CLI login command before calling this.
+      # For API key providers, raises NotImplementedError.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @param token [String] OAuth token to store (must be non-blank)
+      # @return [Hash] result with :success key
+      # @raise [NotImplementedError] if provider doesn't support credential refresh
+      def refresh_auth(provider_name, token: nil)
+        provider_name = provider_name.to_sym
+        provider = resolve_provider(provider_name)
+
+        unless provider.auth_type == :oauth
+          raise NotImplementedError,
+            "Provider #{provider_name} uses #{provider.auth_type} auth and does not support credential refresh"
+        end
+
+        case provider_name
+        when :claude, :anthropic
+          refresh_claude_auth(token: token)
+        else
+          raise NotImplementedError,
+            "Credential refresh is not yet implemented for provider #{provider_name}"
+        end
+      end
+
+      private
+
+      def resolve_provider(provider_name)
+        klass = Providers::Registry.instance.get(provider_name)
+        # Construct the provider with config/executor/logger to match
+        # ProviderManager#create_provider and support custom providers
+        # that may rely on these initializer arguments.
+        config = AgentHarness.configuration.providers[provider_name]
+        klass.new(
+          config: config,
+          executor: AgentHarness.configuration.command_executor,
+          logger: AgentHarness.logger
+        )
+      rescue ConfigurationError
+        raise ProviderNotFoundError, "Unknown provider: #{provider_name}"
+      end
+
+      # Claude Code auth status check
+      def claude_auth_status
+        credentials = read_claude_credentials
+        return {valid: false, expires_at: nil, error: "No credentials found"} unless credentials
+
+        # Check if the credentials file has a token, preferring a non-blank oauth_token over apiKey
+        oauth_token = credentials["oauth_token"]
+        api_key = credentials["apiKey"]
+        token = [oauth_token, api_key].find { |t| t.is_a?(String) && !t.strip.empty? }
+        if token
+          expires_at = parse_expiry(credentials["expiresAt"] || credentials["expires_at"])
+          if expires_at && expires_at < Time.now
+            {valid: false, expires_at: expires_at, error: "Session expired"}
+          else
+            {valid: true, expires_at: expires_at, error: nil}
+          end
+        else
+          {valid: false, expires_at: nil, error: "No authentication token found"}
+        end
+      rescue IOError, JSON::ParserError => e
+        {valid: false, expires_at: nil, error: e.message}
+      end
+
+      # Generic auth status for non-Claude providers
+      def generic_auth_status(provider_name)
+        provider = resolve_provider(provider_name)
+
+        # Prefer a provider-specific auth_status hook when available
+        if provider.respond_to?(:auth_status)
+          return provider.auth_status
+        end
+
+        if provider.auth_type == :api_key
+          {valid: false, expires_at: nil, error: "Auth status check not implemented for api_key providers"}
+        else
+          {valid: false, expires_at: nil, error: "Auth status check not implemented for #{provider_name}"}
+        end
+      rescue ProviderNotFoundError => e
+        {valid: false, expires_at: nil, error: e.message}
+      end
+
+      def claude_auth_url
+        "https://claude.ai/oauth/authorize"
+      end
+
+      def refresh_claude_auth(token: nil)
+        raise ArgumentError, "token must be a non-empty string" unless token.is_a?(String) && !token.strip.empty?
+
+        credentials_path = claude_credentials_path
+        dir = File.dirname(credentials_path)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+
+        lock_path = "#{credentials_path}.lock"
+        File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+
+          credentials = read_claude_credentials
+          credentials = {} unless credentials.is_a?(Hash)
+          credentials["oauth_token"] = token.strip
+          # Clear any existing expiry metadata so refreshed tokens are not treated as expired
+          credentials.delete("expiresAt")
+          credentials.delete("expires_at")
+
+          # Write under a file lock using tempfile + rename to avoid corruption and lost updates on concurrent refreshes
+          tmpfile = Tempfile.new(".credentials", dir)
+          begin
+            tmpfile.write(JSON.pretty_generate(credentials))
+            tmpfile.close
+            File.chmod(0o600, tmpfile.path)
+            File.rename(tmpfile.path, credentials_path)
+          rescue
+            tmpfile.close!
+            raise
+          end
+        end
+
+        {success: true}
+      end
+
+      def read_claude_credentials
+        path = claude_credentials_path
+        return nil unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      rescue Errno::ENOENT
+        # File was removed between the existence check and the read; treat as missing
+        nil
+      rescue Errno::EACCES => e
+        raise IOError, "Permission denied when reading Claude credentials at #{path}: #{e.message}"
+      rescue JSON::ParserError => e
+        raise JSON::ParserError, "Invalid JSON in Claude credentials at #{path}: #{e.message}"
+      end
+
+      def claude_credentials_path
+        config_dir = ENV["CLAUDE_CONFIG_DIR"] || File.expand_path("~/.claude")
+        File.join(config_dir, ".credentials.json")
+      end
+
+      def parse_expiry(value)
+        return nil unless value
+
+        case value
+        when Time
+          value
+        when Integer, Float
+          Time.at(value)
+        when String
+          Time.parse(value)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/agent_harness/configuration.rb

@@ -221,12 +221,13 @@ module AgentHarness
 
   # Health check configuration
   class HealthCheckConfig
-    attr_accessor :enabled, :interval, :failure_threshold
+    attr_accessor :enabled, :interval, :failure_threshold, :timeout
 
     def initialize
       @enabled = true
       @interval = 60 # 1 minute
       @failure_threshold = 3
+      @timeout = 5 # seconds per provider check
     end
   end
 

data/lib/agent_harness/error_taxonomy.rb

@@ -16,7 +16,7 @@ module AgentHarness
       },
       auth_expired: {
         description: "Authentication failed or expired",
-        action: :switch_provider,
+        action: :reauthenticate,
         retryable: false
       },
       quota_exceeded: {

data/lib/agent_harness/errors.rb

@@ -45,7 +45,14 @@ module AgentHarness
   end
 
   # Authentication errors
-  class AuthenticationError < Error; end
+  class AuthenticationError < Error
+    attr_reader :provider
+
+    def initialize(message = nil, provider: nil, **kwargs)
+      @provider = provider
+      super(message, **kwargs)
+    end
+  end
 
   # Configuration errors
   class ConfigurationError < Error; end

data/lib/agent_harness/orchestration/conductor.rb

@@ -101,6 +101,17 @@ module AgentHarness
           @provider_manager.record_success(provider_name)
 
           response
+        rescue AuthenticationError => e
+          # Authentication errors are intentionally NOT retried or switched.
+          # Unlike transient provider errors, auth failures indicate expired
+          # or invalid credentials that require user re-authentication — switching
+          # to another provider would mask the real problem. The error is surfaced
+          # directly so callers can trigger a re-auth flow (e.g. via Authentication.refresh_auth).
+          # We also skip @provider_manager.record_failure to avoid tripping the
+          # circuit breaker, since auth failures are credential issues, not
+          # provider health issues.
+          @metrics.record_failure(provider_name, e)
+          raise
         rescue RateLimitError => e
           @provider_manager.mark_rate_limited(provider_name, reset_at: e.reset_time)
           handle_provider_failure(e, provider_name, :switch)

data/lib/agent_harness/provider_health_check.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module AgentHarness
+  # Performs health checks on configured providers
+  #
+  # Validates provider setup, authentication status, and reachability.
+  # Returns per-provider status objects with name, status, message, and latency.
+  #
+  # @example Check all providers
+  #   results = AgentHarness::ProviderHealthCheck.check_all
+  #   results.each { |r| puts "#{r[:name]}: #{r[:status]}" }
+  #
+  # @example Check a single provider
+  #   result = AgentHarness::ProviderHealthCheck.check(:claude)
+  #   puts result[:status] # => "ok", "error", or "degraded"
+  class ProviderHealthCheck
+    # Single source of truth: derive the fallback from HealthCheckConfig's default
+    # so that the timeout isn't duplicated here and in configuration.rb.
+    DEFAULT_TIMEOUT = HealthCheckConfig.new.timeout
+
+    class << self
+      # Check health of all configured providers
+      #
+      # @param timeout [Integer] timeout in seconds for each check
+      # @return [Array<Hash>] health status for each provider
+      def check_all(timeout: configured_timeout)
+        provider_names = if AgentHarness.configuration.providers.empty?
+          Providers::Registry.instance.all
+        else
+          enabled_provider_names
+        end
+
+        provider_names.map { |name| check(name, timeout: timeout) }
+      end
+
+      # Check health of a single provider
+      #
+      # @param provider_name [Symbol, String] the provider name
+      # @param timeout [Integer] timeout in seconds
+      # @return [Hash] health status with :name, :status, :message, :latency_ms keys
+      def check(provider_name, timeout: configured_timeout)
+        name = normalize_name(provider_name)
+        start_time = monotonic_now
+        timeout = validate_timeout(timeout)
+
+        Timeout.timeout(timeout) do
+          perform_check(name, start_time)
+        end
+      rescue Timeout::Error
+        build_result(
+          name: name,
+          status: "error",
+          message: "Health check timed out after #{timeout}s",
+          start_time: start_time || monotonic_now
+        )
+      rescue NotImplementedError => e
+        # NotImplementedError inherits from ScriptError, not StandardError,
+        # so it must be rescued explicitly. Its messages are safe internal
+        # setup errors (e.g., missing provider methods) that help users
+        # diagnose configuration problems.
+        AgentHarness.logger&.error("ProviderHealthCheck error for #{name}: #{e.class}")
+        build_result(
+          name: name,
+          status: "error",
+          message: "Health check failed: #{e.class}: #{e.message}",
+          start_time: start_time || monotonic_now
+        )
+      rescue => e
+        # Return a generic message to avoid leaking sensitive details
+        # (e.g., tokens embedded in exception messages). Log only the
+        # exception class (not the message) to avoid leaking secrets.
+        AgentHarness.logger&.error("ProviderHealthCheck error for #{name}: #{e.class}")
+        build_result(
+          name: name,
+          status: "error",
+          message: "Health check failed: #{e.class}",
+          start_time: start_time || monotonic_now
+        )
+      end
+
+      # Format health check results for CLI output
+      #
+      # @param results [Array<Hash>] health check results
+      # @return [String] formatted output
+      def format_results(results)
+        lines = ["Checking providers..."]
+
+        if results.empty?
+          lines << ""
+          lines << "No providers checked."
+          return lines.join("\n")
+        end
+
+        results.each do |result|
+          name = result[:name].to_s.ljust(16)
+          case result[:status]
+          when "ok"
+            latency = result[:latency_ms] ? "(#{result[:latency_ms]}ms)" : ""
+            lines << "  ✓ #{name} OK #{latency}".rstrip
+          when "degraded"
+            lines << "  ~ #{name} #{result[:message]}"
+          else
+            lines << "  ✗ #{name} #{result[:message]}"
+          end
+        end
+
+        failed = results.count { |r| r[:status] == "error" }
+        degraded = results.count { |r| r[:status] == "degraded" }
+        total = results.size
+
+        lines << ""
+        summary_parts = []
+        summary_parts << "#{failed} failed" if failed > 0
+        summary_parts << "#{degraded} degraded" if degraded > 0
+
+        provider_word = (total == 1) ? "provider" : "providers"
+        lines << if summary_parts.any?
+          "#{total} #{provider_word} checked: #{summary_parts.join(", ")}."
+        else
+          "All #{total} #{provider_word} healthy."
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def enabled_provider_names
+        AgentHarness.configuration.providers.select { |_name, config| config.enabled }.keys
+      end
+
+      def validate_timeout(timeout)
+        (timeout.is_a?(Numeric) && timeout.positive?) ? timeout : configured_timeout
+      end
+
+      def configured_timeout
+        timeout = AgentHarness.configuration.orchestration_config.health_check_config.timeout
+        (timeout.is_a?(Numeric) && timeout.positive?) ? timeout : DEFAULT_TIMEOUT
+      rescue NoMethodError
+        DEFAULT_TIMEOUT
+      end
+
+      def normalize_name(provider_name)
+        provider_name.to_sym
+      rescue NoMethodError, ArgumentError, TypeError
+        :unknown
+      end
+
+      def perform_check(provider_name, start_time)
+        # Step 1: Check provider is registered
+        registry = Providers::Registry.instance
+        unless registry.registered?(provider_name)
+          return build_result(
+            name: provider_name,
+            status: "error",
+            message: "Provider not registered",
+            start_time: start_time
+          )
+        end
+
+        # Step 2: Check CLI availability
+        klass = registry.get(provider_name)
+        unless klass.available?
+          return build_result(
+            name: provider_name,
+            status: "error",
+            message: "CLI '#{klass.binary_name}' not found in PATH",
+            start_time: start_time
+          )
+        end
+
+        # Step 3: Check authentication
+        # Treat "not implemented" auth status as degraded rather than error,
+        # since most built-in providers don't implement auth_status hooks.
+        # In either case, continue to steps 4/5 so health and config issues
+        # are still surfaced for providers that lack an auth_status hook.
+        auth = Authentication.auth_status(provider_name)
+        auth_degraded = false
+        unless auth[:valid]
+          unless auth_not_implemented?(auth)
+            return build_result(
+              name: provider_name,
+              status: "error",
+              message: auth[:error] || "Authentication failed",
+              start_time: start_time
+            )
+          end
+          auth_degraded = true
+        end
+
+        # Step 4: Check provider-level health (e.g., endpoint reachability)
+        # The Adapter default always returns {healthy: true}, so providers
+        # that haven't implemented a real health check are reported as ok
+        # with a note that the check is not implemented.
+        provider_instance = build_provider(provider_name, klass)
+        health = provider_instance.health_status
+        unless health[:healthy]
+          return build_result(
+            name: provider_name,
+            status: "degraded",
+            message: health[:message] || "Provider health check failed",
+            start_time: start_time
+          )
+        end
+
+        # Step 5: Validate provider config
+        # The Adapter default always returns {valid: true}, so providers
+        # that haven't implemented real config validation pass by default.
+        validation = provider_instance.validate_config
+        unless validation[:valid]
+          errors_msg = Array(validation[:errors]).join(", ")
+          errors_msg = "check provider configuration" if errors_msg.empty?
+          return build_result(
+            name: provider_name,
+            status: "degraded",
+            message: "Configuration issues: #{errors_msg}",
+            start_time: start_time
+          )
+        end
+
+        # If auth was not implemented but health/config passed, report degraded
+        if auth_degraded
+          return build_result(
+            name: provider_name,
+            status: "degraded",
+            message: "Auth status check not implemented; health and config checks passed",
+            start_time: start_time
+          )
+        end
+
+        message = if provider_overrides_method?(provider_instance, :health_status) ||
+            provider_overrides_method?(provider_instance, :validate_config)
+          "All checks passed"
+        else
+          "Registered and authenticated (health/config checks use defaults)"
+        end
+
+        build_result(
+          name: provider_name,
+          status: "ok",
+          message: message,
+          start_time: start_time
+        )
+      end
+
+      def auth_not_implemented?(auth)
+        # Prefer explicit flags over brittle string matching on error messages.
+        # This keeps backward compatibility with existing callers that only set :error,
+        # while allowing newer callers to pass structured reasons.
+        if auth.respond_to?(:[])
+          return true if auth.key?(:implemented) && auth[:implemented] == false
+          return true if auth.key?(:reason) && auth[:reason] == :not_implemented
+        end
+
+        error = auth[:error].to_s
+        error.include?("not implemented")
+      end
+
+      def provider_overrides_method?(provider_instance, method_name)
+        provider_instance.method(method_name).owner != Providers::Adapter
+      end
+
+      def build_result(name:, status:, message:, start_time:)
+        latency = ((monotonic_now - start_time) * 1000).round
+        {
+          name: name,
+          status: status,
+          message: message,
+          latency_ms: latency
+        }
+      end
+
+      def build_provider(provider_name, klass)
+        config = AgentHarness.configuration.providers[provider_name]
+        klass.new(
+          config: config,
+          executor: AgentHarness.configuration.command_executor,
+          logger: AgentHarness.logger
+        )
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/agent_harness/providers/adapter.rb

@@ -102,6 +102,14 @@ module AgentHarness
         {}
       end
 
+      # Authentication type for this provider
+      #
+      # @return [Symbol] :oauth for token-based auth that can expire,
+      #   :api_key for static API key auth
+      def auth_type
+        :api_key
+      end
+
       # Check if provider supports MCP
       #
       # @return [Boolean] true if MCP is supported

data/lib/agent_harness/providers/anthropic.rb

@@ -184,6 +184,10 @@ module AgentHarness
         ["--dangerously-skip-permissions"]
       end
 
+      def auth_type
+        :oauth
+      end
+
       def error_patterns
         {
           rate_limited: [
@@ -198,7 +202,11 @@ module AgentHarness
             /authentication.*error/i,
             /invalid.*api.*key/i,
             /unauthorized/i,
-            /401/
+            /401/,
+            /session.*expired/i,
+            /not.*logged.*in/i,
+            /login.*required/i,
+            /credentials.*expired/i
           ],
           quota_exceeded: [
             /quota.*exceeded/i,
@@ -246,7 +254,7 @@ module AgentHarness
       def build_command(prompt, options)
         cmd = [self.class.binary_name]
 
-        cmd += ["--print", "--output-format=text"]
+        cmd += ["--print", "--output-format=json"]
 
         # Add model if specified
         if @config.model && !@config.model.empty?
@@ -261,7 +269,7 @@ module AgentHarness
         # Add custom flags from config
         cmd += @config.default_flags if @config.default_flags&.any?
 
-        cmd += ["--prompt", prompt]
+        cmd << prompt
 
         cmd
       end
@@ -269,18 +277,27 @@ module AgentHarness
       def parse_response(result, duration:)
         output = result.stdout
         error = nil
+        tokens = nil
 
         if result.failed?
           combined = [result.stdout, result.stderr].compact.join("\n")
           error = classify_error_message(combined)
         end
 
+        # Parse JSON output to extract result text and token usage
+        parsed = parse_json_output(output)
+        if parsed
+          output = parsed["result"] || output
+          tokens = extract_tokens(parsed)
+        end
+
         Response.new(
           output: output,
           exit_code: result.exit_code,
           duration: duration,
           provider: self.class.provider_name,
           model: @config.model,
+          tokens: tokens,
           error: error
         )
       end
@@ -291,6 +308,28 @@ module AgentHarness
 
       private
 
+      def parse_json_output(output)
+        return nil if output.nil? || output.empty?
+
+        JSON.parse(output)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def extract_tokens(parsed)
+        usage = parsed["usage"]
+        return nil unless usage
+
+        input = usage["input_tokens"]
+        output = usage["output_tokens"]
+        return nil unless input || output
+
+        input ||= 0
+        output ||= 0
+
+        {input: input, output: output, total: input + output}
+      end
+
       def classify_error_message(message)
         msg_lower = message.downcase
 

data/lib/agent_harness/providers/base.rb

@@ -179,7 +179,11 @@ module AgentHarness
         when :rate_limited
           RateLimitError.new(original_error.message, original_error: original_error)
         when :auth_expired
-          AuthenticationError.new(original_error.message, original_error: original_error)
+          AuthenticationError.new(
+            original_error.message,
+            provider: self.class.provider_name,
+            original_error: original_error
+          )
         when :timeout
           TimeoutError.new(original_error.message, original_error: original_error)
         else

data/lib/agent_harness/providers/codex.rb

@@ -81,13 +81,13 @@ module AgentHarness
       protected
 
       def build_command(prompt, options)
-        cmd = [self.class.binary_name]
+        cmd = [self.class.binary_name, "exec"]
 
         if options[:session]
           cmd += session_flags(options[:session])
         end
 
-        cmd += ["--prompt", prompt]
+        cmd << prompt
 
         cmd
       end

data/lib/agent_harness/providers/cursor.rb

@@ -114,6 +114,10 @@ module AgentHarness
         fetch_mcp_servers_cli || fetch_mcp_servers_config
       end
 
+      def auth_type
+        :oauth
+      end
+
       def error_patterns
         {
           rate_limited: [
@@ -265,7 +269,7 @@ module AgentHarness
         when :rate_limited
           raise RateLimitError.new(error.message, original_error: error)
         when :auth_expired
-          raise AuthenticationError.new(error.message, original_error: error)
+          raise AuthenticationError.new(error.message, provider: self.class.provider_name, original_error: error)
         when :timeout
           raise TimeoutError.new(error.message, original_error: error)
         else

data/lib/agent_harness/providers/gemini.rb

@@ -92,6 +92,10 @@ module AgentHarness
         }
       end
 
+      def auth_type
+        :oauth
+      end
+
       def error_patterns
         {
           rate_limited: [

data/lib/agent_harness/providers/github_copilot.rb

@@ -106,6 +106,10 @@ module AgentHarness
         ["--resume", session_id]
       end
 
+      def auth_type
+        :oauth
+      end
+
       def error_patterns
         {
           auth_expired: [

data/lib/agent_harness/providers/kilocode.rb

@@ -12,7 +12,7 @@ module AgentHarness
         end
 
         def binary_name
-          "kilocode"
+          "kilo"
         end
 
         def available?
@@ -60,8 +60,8 @@ module AgentHarness
       protected
 
       def build_command(prompt, options)
-        cmd = [self.class.binary_name]
-        cmd += ["--prompt", prompt]
+        cmd = [self.class.binary_name, "run"]
+        cmd << prompt
         cmd
       end
 

data/lib/agent_harness/providers/registry.rb

@@ -95,7 +95,7 @@ module AgentHarness
       end
 
       def validate_provider_class!(klass)
-        includes_adapter = klass.included_modules.include?(Adapter)
+        includes_adapter = klass.include?(Adapter)
         has_required_methods = klass.respond_to?(:provider_name) &&
           klass.respond_to?(:available?) &&
           klass.respond_to?(:binary_name)

data/lib/agent_harness/version.rb

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

data/lib/agent_harness.rb

@@ -82,6 +82,56 @@ module AgentHarness
     def provider(name)
       conductor.provider_manager.get_provider(name)
     end
+
+    # Check if authentication is valid for a provider
+    # @param provider_name [Symbol] the provider name
+    # @return [Boolean] true if auth is valid
+    def auth_valid?(provider_name)
+      Authentication.auth_valid?(provider_name)
+    end
+
+    # Get detailed authentication status for a provider
+    # @param provider_name [Symbol] the provider name
+    # @return [Hash] status with :valid, :expires_at, :error keys
+    def auth_status(provider_name)
+      Authentication.auth_status(provider_name)
+    end
+
+    # Generate an OAuth URL for a provider
+    # @param provider_name [Symbol] the provider name
+    # @return [String] the OAuth authorization URL
+    # @raise [NotImplementedError] if provider doesn't support OAuth
+    def auth_url(provider_name)
+      Authentication.auth_url(provider_name)
+    end
+
+    # Refresh authentication credentials for a provider
+    # @param provider_name [Symbol] the provider name
+    # @param token [String, nil] OAuth token to store
+    # @return [Hash] result with :success key
+    # @raise [NotImplementedError] if provider doesn't support credential refresh
+    def refresh_auth(provider_name, token: nil)
+      Authentication.refresh_auth(provider_name, token: token)
+    end
+
+    # Check health of all configured providers.
+    #
+    # Validates each enabled provider through registration, CLI availability,
+    # authentication, provider health status, and config validation checks.
+    #
+    # @param timeout [Integer] timeout in seconds for each check (defaults to configured value)
+    # @return [Array<Hash>] health status for each provider
+    def check_providers(timeout: nil)
+      timeout ? ProviderHealthCheck.check_all(timeout: timeout) : ProviderHealthCheck.check_all
+    end
+
+    # Check health of a single provider
+    # @param provider_name [Symbol] the provider name
+    # @param timeout [Integer, nil] timeout in seconds (nil lets ProviderHealthCheck apply its validated default)
+    # @return [Hash] health status with :name, :status, :message, :latency_ms
+    def check_provider(provider_name, timeout: nil)
+      timeout ? ProviderHealthCheck.check(provider_name, timeout: timeout) : ProviderHealthCheck.check(provider_name)
+    end
   end
 end
 
@@ -93,6 +143,8 @@ require_relative "agent_harness/docker_command_executor"
 require_relative "agent_harness/response"
 require_relative "agent_harness/token_tracker"
 require_relative "agent_harness/error_taxonomy"
+require_relative "agent_harness/authentication"
+require_relative "agent_harness/provider_health_check"
 
 # Provider layer
 require_relative "agent_harness/providers/registry"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Bart Agapinan
@@ -66,6 +66,7 @@ files:
 - ".markdownlintignore"
 - ".release-please-manifest.json"
 - ".rspec"
+- ".rubocop.yml"
 - ".simplecov"
 - ".tool-versions"
 - CHANGELOG.md
@@ -75,7 +76,9 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- json-2.18.1.gem
 - lib/agent_harness.rb
+- lib/agent_harness/authentication.rb
 - lib/agent_harness/command_executor.rb
 - lib/agent_harness/configuration.rb
 - lib/agent_harness/docker_command_executor.rb
@@ -87,6 +90,7 @@ files:
 - lib/agent_harness/orchestration/metrics.rb
 - lib/agent_harness/orchestration/provider_manager.rb
 - lib/agent_harness/orchestration/rate_limiter.rb
+- lib/agent_harness/provider_health_check.rb
 - lib/agent_harness/providers/adapter.rb
 - lib/agent_harness/providers/aider.rb
 - lib/agent_harness/providers/anthropic.rb
@@ -117,14 +121,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.3.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Unified interface for CLI-based AI coding agents
 test_files: []