agent-harness 0.5.5 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc338c5fc81d4175149d405d494936b68a261a637deda4fc0e4fb7b18944bf67
-  data.tar.gz: aed5c92bc22dadab8826b919e8eabf606bcd7f6bfe0e1d02631c83461056a888
+  metadata.gz: 946d7c425aff8c96536bc30def7e0abdba7ff7d82020f4941674a8c93be63526
+  data.tar.gz: ffc9d707f89ab60bf9cc59b4e5ccbcd2570a3aaa07e97c5a10bfb731f5dc07a0
 SHA512:
-  metadata.gz: 1d662f4ae796d88a1a2c2eabce4604a38c4b53b545640b51c16a4b8e370ddf59f40ff57b19dfb46ba96e50b85399b846c9d2379bdc9806bd40aa78b1f18c1f66
-  data.tar.gz: 913df22acc91cd6db4ff2788867dc8337a2f1e94c0a2b2cce483e0af4ec73d2a946fcbb80270968d82c49c55aa375da86c386f4c8472ad2d42664d2bc1242ee6
+  metadata.gz: c7b0dcef83c7a31be09a87884211a8ba03c0c93fb845e666423cd17eb70a358dd122db7e57ce04271fa5e114013adbc0007394211286c23b03cfa6a2a600c68f
+  data.tar.gz: a8f14eb24039afd0a93ec1eb064b59ebbe6d03aafd61ab1859c64729d2253140afebacc5c8ee761578337c671c074425784c33676808534cdf7b8ad809a2df32

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.5"
+  ".": "0.5.6"
 }

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.5.6](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.5...agent-harness/v0.5.6) (2026-03-30)
+
+
+### Bug Fixes
+
+* 53: Expose provider configuration capabilities for app-driven provider setup UIs ([#57](https://github.com/viamin/agent-harness/issues/57)) ([6aa6a02](https://github.com/viamin/agent-harness/commit/6aa6a02da14feefcad8761302d5fa8b5642a57fe))
+* 54: Add per-request provider runtime overrides for CLI-backed providers ([#55](https://github.com/viamin/agent-harness/issues/55)) ([407467a](https://github.com/viamin/agent-harness/commit/407467a6965a01494e2c4590680b2bb9ddac6dce))
+
 ## [0.5.5](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.4...agent-harness/v0.5.5) (2026-03-29)
 
 

data/lib/agent_harness/provider_runtime.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Normalized runtime configuration for per-request provider overrides.
+  #
+  # ProviderRuntime lets callers pass a single, provider-agnostic payload
+  # into +send_message+ that each provider materializes into CLI args, env
+  # vars, or config files as needed.
+  #
+  # @example Routing OpenCode through OpenRouter with a specific model
+  #   runtime = AgentHarness::ProviderRuntime.new(
+  #     model: "anthropic/claude-opus-4.1",
+  #     base_url: "https://openrouter.ai/api/v1",
+  #     api_provider: "openrouter",
+  #     env: { "OPENROUTER_API_KEY" => "sk-..." }
+  #   )
+  #   provider.send_message(prompt: "Hello", provider_runtime: runtime)
+  #
+  # @example Passing a Hash (auto-coerced by Base#send_message)
+  #   provider.send_message(
+  #     prompt: "Hello",
+  #     provider_runtime: {
+  #       model: "openai/gpt-5.3-codex",
+  #       base_url: "https://openrouter.ai/api/v1"
+  #     }
+  #   )
+  class ProviderRuntime
+    attr_reader :model, :base_url, :api_provider, :env, :flags, :metadata
+
+    # @param model [String, nil] model identifier override
+    # @param base_url [String, nil] upstream API base URL override
+    # @param api_provider [String, nil] API-compatible backend name
+    # @param env [Hash<String,String>] extra environment variables for the subprocess
+    # @param flags [Array<String>] extra CLI flags to append
+    # @param metadata [Hash] arbitrary provider-specific data
+    def initialize(model: nil, base_url: nil, api_provider: nil, env: {}, flags: [], metadata: {})
+      @model = model
+      @base_url = base_url
+      @api_provider = api_provider
+
+      env_hash = env || {}
+      unless env_hash.is_a?(Hash)
+        raise ArgumentError, "env must be a Hash (got #{env_hash.class})"
+      end
+      normalized_env = env_hash.each_with_object({}) do |(key, value), acc|
+        string_key = key.to_s
+        unless value.is_a?(String)
+          raise ArgumentError, "env value for #{string_key.inspect} must be a String (got #{value.class})"
+        end
+        acc[string_key] = value
+      end
+      @env = normalized_env.freeze
+
+      normalized_flags = flags || []
+      unless normalized_flags.is_a?(Array)
+        raise ArgumentError, "flags must be an Array (got #{normalized_flags.class})"
+      end
+      normalized_flags = normalized_flags.dup
+      normalized_flags.each_with_index do |flag, index|
+        unless flag.is_a?(String)
+          raise ArgumentError,
+            "flags must be an Array of Strings; invalid element at index #{index}: #{flag.inspect} (#{flag.class})"
+        end
+      end
+      @flags = normalized_flags.freeze
+
+      metadata_hash = metadata || {}
+      unless metadata_hash.is_a?(Hash)
+        raise ArgumentError, "metadata must be a Hash (got #{metadata_hash.class})"
+      end
+      @metadata = metadata_hash.dup.freeze
+
+      freeze
+    end
+
+    # Build a ProviderRuntime from a Hash.
+    #
+    # @param hash [Hash] runtime attributes
+    # @return [ProviderRuntime]
+    def self.from_hash(hash)
+      raise ArgumentError, "expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      new(
+        model: hash[:model] || hash["model"],
+        base_url: hash[:base_url] || hash["base_url"],
+        api_provider: hash[:api_provider] || hash["api_provider"],
+        env: hash[:env] || hash["env"] || {},
+        flags: hash[:flags] || hash["flags"] || [],
+        metadata: hash[:metadata] || hash["metadata"] || {}
+      )
+    end
+
+    # Coerce a value into a ProviderRuntime.
+    #
+    # @param value [ProviderRuntime, Hash, nil] input
+    # @return [ProviderRuntime, nil]
+    def self.wrap(value)
+      case value
+      when ProviderRuntime then value
+      when Hash then from_hash(value)
+      when nil then nil
+      else
+        raise ArgumentError, "Cannot coerce #{value.class} into ProviderRuntime"
+      end
+    end
+
+    # Whether any meaningful overrides are present.
+    #
+    # @return [Boolean]
+    def empty?
+      model.nil? && base_url.nil? && api_provider.nil? &&
+        env.empty? && flags.empty? && metadata.empty?
+    end
+  end
+end

data/lib/agent_harness/providers/adapter.rb

@@ -75,11 +75,32 @@ module AgentHarness
       # @option options [Integer] :timeout timeout in seconds
       # @option options [String] :session session identifier
       # @option options [Boolean] :dangerous_mode skip permission checks
+      # @option options [ProviderRuntime, Hash, nil] :provider_runtime per-request
+      #   runtime overrides (model, base_url, api_provider, env, flags, metadata).
+      #   For providers that delegate to Providers::Base#send_message, a plain Hash
+      #   is automatically coerced into a ProviderRuntime. Providers that override
+      #   #send_message directly are responsible for handling this option.
       # @return [Response] response object with output and metadata
       def send_message(prompt:, **options)
         raise NotImplementedError, "#{self.class} must implement #send_message"
       end
 
+      # Provider configuration schema for app-driven setup UIs
+      #
+      # Returns metadata describing the configurable fields, supported
+      # authentication modes, and backend compatibility for this provider.
+      # Applications use this to build generic provider-entry forms without
+      # hardcoding provider-specific knowledge.
+      #
+      # @return [Hash] with :fields, :auth_modes, :openai_compatible keys
+      def configuration_schema
+        {
+          fields: [],
+          auth_modes: [auth_type],
+          openai_compatible: false
+        }
+      end
+
       # Provider capabilities
       #
       # @return [Hash] capability flags

data/lib/agent_harness/providers/aider.rb

@@ -59,6 +59,23 @@ module AgentHarness
         "Aider"
       end
 
+      def configuration_schema
+        {
+          fields: [
+            {
+              name: :model,
+              type: :string,
+              label: "Model",
+              required: false,
+              hint: "Model identifier (supports OpenAI, Anthropic, and other model names)",
+              accepts_arbitrary: true
+            }
+          ],
+          auth_modes: [:api_key],
+          openai_compatible: false
+        }
+      end
+
       def capabilities
         {
           streaming: true,

data/lib/agent_harness/providers/anthropic.rb

@@ -160,6 +160,23 @@ module AgentHarness
         "Anthropic Claude CLI"
       end
 
+      def configuration_schema
+        {
+          fields: [
+            {
+              name: :model,
+              type: :string,
+              label: "Model",
+              required: false,
+              hint: "Claude model to use (e.g. claude-3-5-sonnet-20241022)",
+              accepts_arbitrary: false
+            }
+          ],
+          auth_modes: [:oauth],
+          openai_compatible: false
+        }
+      end
+
       def capabilities
         {
           streaming: true,

data/lib/agent_harness/providers/base.rb

@@ -87,10 +87,16 @@ module AgentHarness
       #
       # @param prompt [String] the prompt to send
       # @param options [Hash] additional options
+      # @option options [ProviderRuntime, Hash, nil] :provider_runtime per-request
+      #   runtime overrides (model, base_url, api_provider, env, flags, metadata).
+      #   A plain Hash is automatically coerced into a ProviderRuntime.
       # @return [Response] the response
       def send_message(prompt:, **options)
         log_debug("send_message_start", prompt_length: prompt.length, options: options.keys)
 
+        # Coerce provider_runtime from Hash if needed
+        options = normalize_provider_runtime(options)
+
         # Normalize and validate MCP servers
         options = normalize_mcp_servers(options)
         validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
@@ -108,6 +114,23 @@ module AgentHarness
 
         # Parse response
         response = parse_response(result, duration: duration)
+        runtime = options[:provider_runtime]
+        # Runtime model is a per-request override and always takes precedence
+        # over both the config-level model and whatever parse_response returned.
+        # This is intentional: callers use runtime overrides to route a single
+        # provider instance through different backends on each request.
+        if runtime&.model
+          response = Response.new(
+            output: response.output,
+            exit_code: response.exit_code,
+            duration: response.duration,
+            provider: response.provider,
+            model: runtime.model,
+            tokens: response.tokens,
+            metadata: response.metadata,
+            error: response.error
+          )
+        end
 
         # Track tokens
         track_tokens(response) if response.tokens
@@ -158,10 +181,16 @@ module AgentHarness
 
       # Build environment variables - override in subclasses
       #
+      # Provider subclasses should call +super+ and merge their own env vars
+      # so that ProviderRuntime env overrides are always included.
+      #
       # @param options [Hash] options
       # @return [Hash] environment variables
       def build_env(options)
-        {}
+        runtime = options[:provider_runtime]
+        return {} unless runtime
+
+        runtime.env.dup
       end
 
       # Parse CLI output into Response - override in subclasses
@@ -211,6 +240,13 @@ module AgentHarness
 
       private
 
+      def normalize_provider_runtime(options)
+        raw = options[:provider_runtime]
+        return options if raw.nil? || raw.is_a?(ProviderRuntime)
+
+        options.merge(provider_runtime: ProviderRuntime.wrap(raw))
+      end
+
       def normalize_mcp_servers(options)
         servers = options[:mcp_servers]
         return options if servers.nil?
@@ -252,7 +288,7 @@ module AgentHarness
 
         AgentHarness.token_tracker.record(
           provider: self.class.provider_name,
-          model: @config.model,
+          model: response.model || @config.model,
           input_tokens: response.tokens[:input] || 0,
           output_tokens: response.tokens[:output] || 0,
           total_tokens: response.tokens[:total]

data/lib/agent_harness/providers/codex.rb

@@ -59,6 +59,14 @@ module AgentHarness
         "OpenAI Codex CLI"
       end
 
+      def configuration_schema
+        {
+          fields: [],
+          auth_modes: [:api_key],
+          openai_compatible: true
+        }
+      end
+
       def capabilities
         {
           streaming: false,
@@ -211,11 +219,26 @@ module AgentHarness
           cmd += session_flags(options[:session])
         end
 
+        runtime = options[:provider_runtime]
+        if runtime
+          cmd += ["--model", runtime.model] if runtime.model
+          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/cursor.rb

@@ -93,6 +93,14 @@ module AgentHarness
         "Cursor AI"
       end
 
+      def configuration_schema
+        {
+          fields: [],
+          auth_modes: [:oauth],
+          openai_compatible: false
+        }
+      end
+
       def capabilities
         {
           streaming: false,
@@ -163,23 +171,44 @@ module AgentHarness
       def send_message(prompt:, **options)
         log_debug("send_message_start", prompt_length: prompt.length, options: options.keys)
 
+        # Coerce provider_runtime from Hash if needed (same as Base#send_message)
+        options = normalize_provider_runtime(options)
+        runtime = options[:provider_runtime]
+
         # Normalize and validate MCP servers (same as Base#send_message)
         options = normalize_mcp_servers(options)
         validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
 
         # Build command (without prompt in args - we send via stdin)
         command = [self.class.binary_name, "-p"]
+        command.concat(runtime.flags) if runtime&.flags&.any?
 
         # Calculate timeout
         timeout = options[:timeout] || @config.timeout || default_timeout
 
         # Execute command with prompt on stdin
+        env = build_env(options)
         start_time = Time.now
-        result = @executor.execute(command, timeout: timeout, stdin_data: prompt)
+        result = @executor.execute(command, timeout: timeout, stdin_data: prompt, env: env)
         duration = Time.now - start_time
 
         # Parse response
         response = parse_response(result, duration: duration)
+        # Runtime model is a per-request override and always takes precedence
+        # over both the config-level model and whatever parse_response returned.
+        # See Base#send_message for rationale.
+        if runtime&.model
+          response = Response.new(
+            output: response.output,
+            exit_code: response.exit_code,
+            duration: response.duration,
+            provider: response.provider,
+            model: runtime.model,
+            tokens: response.tokens,
+            metadata: response.metadata,
+            error: response.error
+          )
+        end
 
         # Track tokens
         track_tokens(response) if response.tokens
@@ -201,7 +230,7 @@ module AgentHarness
       end
 
       def build_env(options)
-        {}
+        super
       end
 
       def default_timeout

data/lib/agent_harness/providers/gemini.rb

@@ -83,6 +83,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

@@ -77,6 +77,14 @@ module AgentHarness
         "GitHub Copilot CLI"
       end
 
+      def configuration_schema
+        {
+          fields: [],
+          auth_modes: [:oauth],
+          openai_compatible: false
+        }
+      end
+
       def capabilities
         {
           streaming: false,

data/lib/agent_harness/providers/opencode.rb

@@ -47,6 +47,14 @@ module AgentHarness
         "OpenCode CLI"
       end
 
+      def configuration_schema
+        {
+          fields: [],
+          auth_modes: [:api_key],
+          openai_compatible: true
+        }
+      end
+
       def capabilities
         {
           streaming: false,
@@ -80,10 +88,25 @@ module AgentHarness
 
       def build_command(prompt, options)
         cmd = [self.class.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/version.rb

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

data/lib/agent_harness.rb

@@ -138,6 +138,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.6
 platform: ruby
 authors:
 - Bart Agapinan
@@ -92,6 +92,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