agent-harness 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22137a8f8e81a58503c1e19a2349c6a8e1c8617cc5e12a38470fdc6477b483de
-  data.tar.gz: 185d6003da7d94edfc5fc48cb55f4916b3ca06601bed95de5cfe3db88d0d49bb
+  metadata.gz: 16862141d853f2e8817d000a9e4813162f0544cda2c30343de2efc1ffd7e9e73
+  data.tar.gz: ee57bd3611abb7566560675c65c1feb04faee531cd182f8a8812881a73701aae
 SHA512:
-  metadata.gz: 030b8e627328572ad8d01c5245a6f21b2e3070be6255505eb6e6a3df3a2040083218ee0b28c36dd0584622604fd93319ea6e7675308f2d7212007a4b7369320a
-  data.tar.gz: 23cb19b897faf13438bfdc875c2f151eadcefa13c704cf9f80d443db3e99b7317856d9d744514b082a9f2abd813a26c7dcbf84f243c3e35879f564f979fe180f
+  metadata.gz: f5145b28d2c92bef3c8ba6f8a0e8ffe2217f8eb9462c672f28d25e0f6bd6a1bb17f1fa14ae2dcf2e57d35c4fa82a6233fdf51acf7778d399c89c4412ee9c9695
+  data.tar.gz: f6f9e464d3f5f84a87f98b98dd3d0687157a1b69249a3a0731ba162653aabf6cc517430f31b0f9e9b1d3e5d67d0b767c4c5a12c4e88425bd8b24f578343a87e9

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [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)
 
 

data/README.md

@@ -326,6 +326,36 @@ Any existing expiry metadata in the credentials file is cleared on refresh so th
 
 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/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/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/anthropic.rb

@@ -269,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

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/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/version.rb

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

data/lib/agent_harness.rb

@@ -113,6 +113,25 @@ module AgentHarness
     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
 
@@ -125,6 +144,7 @@ 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.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Bart Agapinan
@@ -76,6 +76,7 @@ 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
@@ -89,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
@@ -126,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !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: []