agent-harness 0.5.5 → 0.5.7

data/lib/agent_harness/providers/gemini.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "rubygems/requirement"
 require "time"
 
 module AgentHarness
@@ -11,6 +12,9 @@ module AgentHarness
     class Gemini < Base
       # Model name pattern for Gemini models
       MODEL_PATTERN = /^gemini-[\d.]+-(?:pro|flash|ultra)(?:-\d+)?$/i
+      CLI_PACKAGE = "@google/gemini-cli"
+      SUPPORTED_CLI_VERSION = "0.35.3"
+      SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new("= #{SUPPORTED_CLI_VERSION}").freeze
 
       class << self
         def provider_name
@@ -26,6 +30,32 @@ module AgentHarness
           !!executor.which(binary_name)
         end
 
+        def install_contract(version: SUPPORTED_CLI_VERSION)
+          parsed_version = begin
+            Gem::Version.new(version)
+          rescue ArgumentError
+            raise ArgumentError, "Unsupported Gemini CLI version #{version.inspect}. Supported requirement: #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
+          unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(parsed_version)
+            raise ArgumentError, "Unsupported Gemini CLI version #{version.inspect}. Supported requirement: #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
+          package_spec = "#{CLI_PACKAGE}@#{version}"
+
+          {
+            provider: provider_name,
+            source_type: :npm,
+            package_name: CLI_PACKAGE,
+            supported_version_requirement: SUPPORTED_CLI_REQUIREMENT,
+            default_version: SUPPORTED_CLI_VERSION,
+            resolved_version: version,
+            binary_name: binary_name,
+            install_command: ["npm", "install", "-g", "--ignore-scripts", package_spec],
+            install_command_string: "npm install -g --ignore-scripts #{package_spec}"
+          }
+        end
+
         def firewall_requirements
           {
             domains: [
@@ -73,6 +103,10 @@ module AgentHarness
         def supports_model_family?(family_name)
           MODEL_PATTERN.match?(family_name) || family_name.start_with?("gemini-")
         end
+
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
       end
 
       def name
@@ -83,6 +117,25 @@ module AgentHarness
         "Google Gemini"
       end
 
+      def configuration_schema
+        {
+          fields: [
+            {
+              name: :model,
+              type: :string,
+              label: "Model",
+              required: false,
+              hint: "Gemini model to use (e.g. gemini-2.5-pro, gemini-2.0-flash)",
+              # accepts_arbitrary is true because supports_model_family? accepts
+              # any string starting with "gemini-", not just discovered models.
+              accepts_arbitrary: true
+            }
+          ],
+          auth_modes: [:api_key, :oauth],
+          openai_compatible: false
+        }
+      end
+
       def capabilities
         {
           streaming: true,

data/lib/agent_harness/providers/github_copilot.rb

@@ -9,13 +9,27 @@ module AgentHarness
       # Model name pattern for GitHub Copilot (uses OpenAI models)
       MODEL_PATTERN = /^gpt-[\d.o-]+(?:-turbo)?(?:-mini)?$/i
 
+      # Copilot-specific smoke test contract.  The `what-the-shell` subcommand
+      # translates natural language into shell commands, so the generic
+      # "Reply with exactly OK." prompt would produce something like
+      # `echo "OK"` rather than the literal text "OK".  We use a prompt that
+      # is meaningful for the shell-translation path and only require
+      # non-empty output (no exact match).
+      SMOKE_TEST_CONTRACT = {
+        prompt: "list files in the current directory",
+        expected_output: nil,
+        timeout: 30,
+        require_output: true,
+        success_message: "Smoke test passed"
+      }.freeze
+
       class << self
         def provider_name
           :github_copilot
         end
 
         def binary_name
-          "copilot"
+          "github-copilot-cli"
         end
 
         def available?
@@ -56,6 +70,10 @@ module AgentHarness
           ]
         end
 
+        def smoke_test_contract
+          SMOKE_TEST_CONTRACT
+        end
+
         def model_family(provider_model_name)
           provider_model_name
         end
@@ -77,6 +95,14 @@ module AgentHarness
         "GitHub Copilot CLI"
       end
 
+      def configuration_schema
+        {
+          fields: [],
+          auth_modes: [:oauth],
+          openai_compatible: false
+        }
+      end
+
       def capabilities
         {
           streaming: false,
@@ -108,10 +134,10 @@ module AgentHarness
 
       def execution_semantics
         {
-          prompt_delivery: :flag,
+          prompt_delivery: :arg,
           output_format: :text,
           sandbox_aware: false,
-          uses_subcommand: false,
+          uses_subcommand: true,
           non_interactive_flag: nil,
           legitimate_exit_codes: [0],
           stderr_is_diagnostic: true,
@@ -147,10 +173,12 @@ module AgentHarness
       protected
 
       def build_command(prompt, options)
-        cmd = [self.class.binary_name, "-p", prompt]
+        cmd = [self.class.binary_name, "what-the-shell", prompt]
 
-        # Add dangerous mode flags by default for automation
-        cmd += dangerous_mode_flags if supports_dangerous_mode?
+        # Opt in to unrestricted tool access explicitly to preserve a safe default.
+        if supports_dangerous_mode? && options[:dangerous_mode]
+          cmd += dangerous_mode_flags
+        end
 
         # Add session support if provided
         if options[:session] && !options[:session].empty?

data/lib/agent_harness/providers/kilocode.rb

@@ -6,6 +6,10 @@ module AgentHarness
     #
     # Provides integration with the Kilocode CLI tool.
     class Kilocode < Base
+      PACKAGE_NAME = "@kilocode/cli"
+      DEFAULT_VERSION = "7.1.3"
+      SUPPORTED_VERSION_REQUIREMENT = "= #{DEFAULT_VERSION}"
+
       class << self
         def provider_name
           :kilocode
@@ -35,6 +39,41 @@ module AgentHarness
           return [] unless available?
           []
         end
+
+        def installation_contract(version: DEFAULT_VERSION)
+          validate_install_version!(version)
+          package_spec = "#{PACKAGE_NAME}@#{version}"
+
+          {
+            source: {
+              type: :npm,
+              package: PACKAGE_NAME
+            },
+            install_command: ["npm", "install", "-g", "--ignore-scripts", package_spec],
+            binary_name: binary_name,
+            default_version: DEFAULT_VERSION,
+            supported_version_requirement: SUPPORTED_VERSION_REQUIREMENT
+          }
+        end
+
+        def install_command(version: DEFAULT_VERSION)
+          installation_contract(version: version)[:install_command]
+        end
+
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
+
+        private
+
+        def validate_install_version!(version)
+          requirement = Gem::Requirement.new(SUPPORTED_VERSION_REQUIREMENT)
+          return if requirement.satisfied_by?(Gem::Version.new(version))
+
+          raise ArgumentError,
+            "Unsupported Kilocode CLI version #{version.inspect}; " \
+            "supported versions must satisfy #{SUPPORTED_VERSION_REQUIREMENT}"
+        end
       end
 
       def name

data/lib/agent_harness/providers/mistral_vibe.rb

@@ -37,6 +37,10 @@ module AgentHarness
           return [] unless available?
           []
         end
+
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
       end
 
       def name

data/lib/agent_harness/providers/opencode.rb

@@ -6,6 +6,15 @@ module AgentHarness
     #
     # Provides integration with the OpenCode CLI tool.
     class Opencode < Base
+      CLI_PACKAGE = "opencode-ai"
+      SUPPORTED_CLI_VERSION = "1.3.2"
+      SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 1.4.0").freeze
+      INSTALL_COMMAND_PREFIX = ["npm", "install", "-g", "--ignore-scripts"].freeze
+      SUPPORTED_CLI_VERSIONS = [SUPPORTED_CLI_VERSION].freeze
+      VERSION_REQUIREMENT_STRINGS = SUPPORTED_CLI_REQUIREMENT.requirements
+        .map { |op, ver| "#{op} #{ver}".freeze }
+        .freeze
+
       class << self
         def provider_name
           :opencode
@@ -37,8 +46,66 @@ module AgentHarness
           return [] unless available?
           []
         end
+
+        def installation_contract(version: SUPPORTED_CLI_VERSION)
+          normalized_version = normalize_install_version(version)
+          return DEFAULT_INSTALLATION_CONTRACT if normalized_version == SUPPORTED_CLI_VERSION
+
+          build_installation_contract(normalized_version)
+        end
+
+        def install_command(version: SUPPORTED_CLI_VERSION)
+          installation_contract(version: version)[:install_command]
+        end
+
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
+
+        private
+
+        def build_installation_contract(version)
+          package = "#{CLI_PACKAGE}@#{version}".freeze
+          install_command = (INSTALL_COMMAND_PREFIX + [package]).freeze
+
+          contract = {
+            source: :npm,
+            package: package,
+            package_name: CLI_PACKAGE,
+            version: version,
+            version_requirement: VERSION_REQUIREMENT_STRINGS,
+            binary_name: binary_name,
+            install_command_prefix: INSTALL_COMMAND_PREFIX,
+            install_command: install_command,
+            supported_versions: SUPPORTED_CLI_VERSIONS
+          }
+
+          contract.each_value do |value|
+            value.freeze if value.is_a?(String)
+          end
+          contract.freeze
+        end
+
+        def normalize_install_version(version)
+          raise ArgumentError, unsupported_version_message(version) unless version.is_a?(String) && !version.strip.empty?
+
+          normalized_version = version.strip
+          parsed_version = Gem::Version.new(normalized_version)
+          return normalized_version if SUPPORTED_CLI_REQUIREMENT.satisfied_by?(parsed_version)
+
+          raise ArgumentError, unsupported_version_message(version)
+        rescue ArgumentError
+          raise ArgumentError, unsupported_version_message(version)
+        end
+
+        def unsupported_version_message(version)
+          "Unsupported OpenCode CLI version #{version.inspect}; " \
+            "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
+        end
       end
 
+      DEFAULT_INSTALLATION_CONTRACT = build_installation_contract(SUPPORTED_CLI_VERSION)
+
       def name
         "opencode"
       end
@@ -47,6 +114,14 @@ module AgentHarness
         "OpenCode CLI"
       end
 
+      def configuration_schema
+        {
+          fields: [],
+          auth_modes: [:api_key],
+          openai_compatible: true
+        }
+      end
+
       def capabilities
         {
           streaming: false,
@@ -79,11 +154,26 @@ module AgentHarness
       protected
 
       def build_command(prompt, options)
-        cmd = [self.class.binary_name, "run"]
+        cmd = [self.class.installation_contract[:binary_name], "run"]
+
+        runtime = options[:provider_runtime]
+        if runtime
+          cmd += runtime.flags unless runtime.flags.empty?
+        end
+
         cmd << prompt
         cmd
       end
 
+      def build_env(options)
+        env = super
+        runtime = options[:provider_runtime]
+        return env unless runtime
+
+        env["OPENAI_BASE_URL"] = runtime.base_url if runtime.base_url
+        env
+      end
+
       def default_timeout
         300
       end

data/lib/agent_harness/providers/registry.rb

@@ -79,6 +79,60 @@ module AgentHarness
         @providers.select { |_, klass| klass.available? }.keys
       end
 
+      # Fetch installation metadata for a provider.
+      #
+      # @param name [Symbol, String] the provider name
+      # @param options [Hash] optional target selection (for example, `version:`)
+      # @return [Hash, nil] provider installation contract, or nil when the
+      #   registered provider class does not define `.installation_contract`
+      # @raise [ConfigurationError] if provider not found
+      def installation_contract(name, **options)
+        provider_class = get(name)
+        return nil unless provider_class.respond_to?(:installation_contract)
+
+        provider_class.installation_contract(**options)
+      end
+
+      # Get installation metadata for all providers that expose it.
+      #
+      # @return [Hash<Symbol, Hash>] installation contracts keyed by provider
+      def installation_contracts
+        ensure_builtin_providers_registered
+
+        @providers.each_with_object({}) do |(name, klass), contracts|
+          next unless klass.respond_to?(:installation_contract)
+
+          contract = klass.installation_contract
+          contracts[name] = contract if contract
+        end
+      end
+
+      # Get smoke-test metadata for a provider.
+      #
+      # @param name [Symbol, String] the provider name
+      # @return [Hash, nil] smoke-test contract
+      # @raise [ConfigurationError] if the provider name is not registered
+      def smoke_test_contract(name)
+        klass = get(name)
+        return nil unless klass.respond_to?(:smoke_test_contract)
+
+        klass.smoke_test_contract
+      end
+
+      # Get smoke-test metadata for all providers that expose it.
+      #
+      # @return [Hash<Symbol, Hash>] smoke-test contracts keyed by provider
+      def smoke_test_contracts
+        ensure_builtin_providers_registered
+
+        @providers.each_with_object({}) do |(name, klass), contracts|
+          next unless klass.respond_to?(:smoke_test_contract)
+
+          contract = klass.smoke_test_contract
+          contracts[name] = contract if contract
+        end
+      end
+
       # Reset registry (useful for testing)
       #
       # @return [void]

data/lib/agent_harness/version.rb

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

data/lib/agent_harness.rb

@@ -70,10 +70,11 @@ module AgentHarness
     # Send a message using the orchestration layer
     # @param prompt [String] the prompt to send
     # @param provider [Symbol, nil] optional provider override
+    # @param executor [CommandExecutor, nil] per-request executor 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)
+    def send_message(prompt, provider: nil, executor: nil, **options)
+      conductor.send_message(prompt, provider: provider, executor: executor, **options)
     end
 
     # Get a provider instance
@@ -83,6 +84,64 @@ module AgentHarness
       conductor.provider_manager.get_provider(name)
     end
 
+    # Returns install metadata for a provider CLI when the provider exposes it.
+    #
+    # @param provider_name [Symbol, String] the provider name
+    # @param version [String, nil] optional explicit CLI version override
+    # @return [Hash, nil] installation metadata
+    def provider_install_contract(provider_name, version: nil)
+      provider_installation_contract(provider_name, **(version ? {version: version} : {}))
+    end
+
+    # Get the installation contract for a provider CLI.
+    #
+    # @param name [Symbol, String] the provider name
+    # @param options [Hash] optional target selection (for example, `version:`)
+    # @return [Hash, nil] provider installation contract for the requested target
+    # @raise [ConfigurationError] if provider not found
+    def provider_installation_contract(name, **options)
+      Providers::Registry.instance.installation_contract(name, **options)
+    end
+
+    # Get installation metadata for a provider CLI.
+    # @param provider_name [Symbol, String] the provider name
+    # @param options [Hash] optional target selection (for example, `version:`)
+    # @return [Hash, nil] installation contract
+    # @raise [ConfigurationError] if the provider name is not registered
+    def installation_contract(provider_name, **options)
+      Providers::Registry.instance.installation_contract(provider_name, **options)
+    end
+
+    # Get all provider installation contracts exposed by agent-harness.
+    # @return [Hash<Symbol, Hash>] installation contracts keyed by provider
+    def installation_contracts
+      Providers::Registry.instance.installation_contracts
+    end
+
+    # Get smoke-test metadata for a provider CLI when the provider exposes it.
+    #
+    # @param provider_name [Symbol, String] the provider name
+    # @return [Hash, nil] smoke-test contract
+    def provider_smoke_test_contract(provider_name)
+      smoke_test_contract(provider_name)
+    end
+
+    # Get smoke-test metadata for a provider CLI.
+    # @param provider_name [Symbol, String] the provider name
+    # @return [Hash, nil] smoke-test contract
+    # @raise [ConfigurationError] if the provider name is not registered
+    def smoke_test_contract(provider_name)
+      # Explicitly raise if provider is not registered to match documentation
+      raise ConfigurationError, "Unknown provider: #{provider_name}" unless Providers::Registry.instance.registered?(provider_name)
+      Providers::Registry.instance.smoke_test_contract(provider_name)
+    end
+
+    # Get all provider smoke-test contracts exposed by agent-harness.
+    # @return [Hash<Symbol, Hash>] smoke-test contracts keyed by provider
+    def smoke_test_contracts
+      Providers::Registry.instance.smoke_test_contracts
+    end
+
     # Check if authentication is valid for a provider
     # @param provider_name [Symbol] the provider name
     # @return [Boolean] true if auth is valid
@@ -120,17 +179,29 @@ module AgentHarness
     # authentication, provider health status, and config validation checks.
     #
     # @param timeout [Integer] timeout in seconds for each check (defaults to configured value)
+    # @raise [ArgumentError] if provider_runtime is supplied; runtime overrides are
+    #   only supported by `check_provider` to avoid leaking one provider's execution
+    #   context into every other health check
     # @return [Array<Hash>] health status for each provider
-    def check_providers(timeout: nil)
-      timeout ? ProviderHealthCheck.check_all(timeout: timeout) : ProviderHealthCheck.check_all
+    def check_providers(timeout: nil, executor: nil, provider_runtime: nil)
+      raise ArgumentError, "provider_runtime is only supported for single-provider health checks" unless provider_runtime.nil?
+
+      options = {}
+      options[:timeout] = timeout unless timeout.nil?
+      options[:executor] = executor unless executor.nil?
+      ProviderHealthCheck.check_all(**options)
     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)
+    def check_provider(provider_name, timeout: nil, executor: nil, provider_runtime: nil)
+      options = {}
+      options[:timeout] = timeout unless timeout.nil?
+      options[:executor] = executor unless executor.nil?
+      options[:provider_runtime] = provider_runtime unless provider_runtime.nil?
+      ProviderHealthCheck.check(provider_name, **options)
     end
   end
 end
@@ -138,6 +209,7 @@ end
 # Core components
 require_relative "agent_harness/errors"
 require_relative "agent_harness/mcp_server"
+require_relative "agent_harness/provider_runtime"
 require_relative "agent_harness/configuration"
 require_relative "agent_harness/command_executor"
 require_relative "agent_harness/docker_command_executor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.5.7
 platform: ruby
 authors:
 - Bart Agapinan
@@ -9,6 +9,26 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -92,6 +112,7 @@ files:
 - lib/agent_harness/orchestration/provider_manager.rb
 - lib/agent_harness/orchestration/rate_limiter.rb
 - lib/agent_harness/provider_health_check.rb
+- lib/agent_harness/provider_runtime.rb
 - lib/agent_harness/providers/adapter.rb
 - lib/agent_harness/providers/aider.rb
 - lib/agent_harness/providers/anthropic.rb