agent-harness 0.5.8 → 0.5.9

data/lib/agent_harness/provider_runtime.rb

@@ -35,11 +35,15 @@ module AgentHarness
     # @param unset_env [Array<String>] environment variable names to remove from inherited env
     # @param metadata [Hash] arbitrary provider-specific data
     def initialize(model: nil, base_url: nil, api_provider: nil, env: {}, flags: [], unset_env: [], metadata: {})
+      validate_optional_string!(:model, model)
+      validate_optional_string!(:base_url, base_url)
+      validate_optional_string!(:api_provider, api_provider)
+
       @model = model
       @base_url = base_url
       @api_provider = api_provider
 
-      env_hash = env || {}
+      env_hash = env.nil? ? {} : env
       unless env_hash.is_a?(Hash)
         raise ArgumentError, "env must be a Hash (got #{env_hash.class})"
       end
@@ -52,7 +56,7 @@ module AgentHarness
       end
       @env = normalized_env.freeze
 
-      normalized_flags = flags || []
+      normalized_flags = flags.nil? ? [] : flags
       unless normalized_flags.is_a?(Array)
         raise ArgumentError, "flags must be an Array (got #{normalized_flags.class})"
       end
@@ -65,7 +69,7 @@ module AgentHarness
       end
       @flags = normalized_flags.freeze
 
-      metadata_hash = metadata || {}
+      metadata_hash = metadata.nil? ? {} : metadata
       unless metadata_hash.is_a?(Hash)
         raise ArgumentError, "metadata must be a Hash (got #{metadata_hash.class})"
       end
@@ -74,7 +78,7 @@ module AgentHarness
       # Unset environment variables for the request. These are variable names that
       # should be removed from the inherited environment before the provider
       # command runs.
-      unset_array = unset_env || []
+      unset_array = unset_env.nil? ? [] : unset_env
       unless unset_array.is_a?(Array)
         raise ArgumentError, "unset_env must be an Array (got #{unset_array.class})"
       end
@@ -96,14 +100,19 @@ module AgentHarness
     def self.from_hash(hash)
       raise ArgumentError, "expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
 
+      env_val = hash_value(hash, :env)
+      flags_val = hash_value(hash, :flags)
+      unset_env_val = hash_value(hash, :unset_env)
+      metadata_val = hash_value(hash, :metadata)
+
       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"] || [],
-        unset_env: hash[:unset_env] || hash["unset_env"] || [],
-        metadata: hash[:metadata] || hash["metadata"] || {}
+        model: hash_value(hash, :model),
+        base_url: hash_value(hash, :base_url),
+        api_provider: hash_value(hash, :api_provider),
+        env: env_val.nil? ? {} : env_val,
+        flags: flags_val.nil? ? [] : flags_val,
+        unset_env: unset_env_val.nil? ? [] : unset_env_val,
+        metadata: metadata_val.nil? ? {} : metadata_val
       )
     end
 
@@ -128,5 +137,23 @@ module AgentHarness
       model.nil? && base_url.nil? && api_provider.nil? &&
         env.empty? && flags.empty? && metadata.empty? && unset_env.empty?
     end
+
+    private_class_method def self.hash_value(hash, key)
+      sym_value = hash[key]
+      str_value = hash[key.to_s]
+      # Prefer the symbol key; fall back to the string key only when the
+      # symbol key is nil (not just falsy) so that an explicit `false` is
+      # not silently discarded.
+      sym_value.nil? ? str_value : sym_value
+    end
+
+    private
+
+    def validate_optional_string!(name, value)
+      return if value.nil?
+      return if value.is_a?(String)
+
+      raise ArgumentError, "#{name} must be a String or nil (got #{value.class})"
+    end
   end
 end

data/lib/agent_harness/providers/adapter.rb

@@ -638,7 +638,14 @@ module AgentHarness
               entry.is_a?(Array) ? "#{entry[0]} #{entry[1]}" : entry
             end
             parsed_requirement = Gem::Requirement.new(*requirement_args)
-            unless parsed_requirement.satisfied_by?(Gem::Version.new(version))
+            parsed_version = begin
+              Gem::Version.new(version)
+            rescue ArgumentError
+              raise ArgumentError,
+                "Unsupported #{provider_name} CLI version #{version.inspect}; " \
+                "supported versions must satisfy #{parsed_requirement}"
+            end
+            unless parsed_requirement.satisfied_by?(parsed_version)
               raise ArgumentError,
                 "Unsupported #{provider_name} CLI version #{version.inspect}; " \
                 "supported versions must satisfy #{parsed_requirement}"

data/lib/agent_harness/providers/aider.rb

@@ -62,7 +62,23 @@ module AgentHarness
         end
 
         def installation_contract(version: SUPPORTED_CLI_VERSION)
-          unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(Gem::Version.new(version))
+          version = version.strip if version.respond_to?(:strip)
+
+          unless version.is_a?(String) && !version.empty?
+            raise ArgumentError,
+              "Unsupported Aider CLI version #{version.inspect}; " \
+              "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
+          parsed_version = begin
+            Gem::Version.new(version)
+          rescue ArgumentError
+            raise ArgumentError,
+              "Unsupported Aider CLI version #{version.inspect}; " \
+              "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
+          unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(parsed_version)
             raise ArgumentError,
               "Unsupported Aider CLI version #{version.inspect}; " \
               "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"

data/lib/agent_harness/providers/anthropic.rb

@@ -33,7 +33,8 @@ module AgentHarness
         end
 
         def install_contract(version: nil)
-          target_version = version || SUPPORTED_CLI_VERSION
+          target_version = version.nil? ? SUPPORTED_CLI_VERSION : version
+          target_version = target_version.strip if target_version.respond_to?(:strip)
           validate_version!(target_version)
           version_requirement = SUPPORTED_CLI_REQUIREMENT.requirements
             .map { |op, ver| "#{op} #{ver}" }
@@ -163,18 +164,26 @@ module AgentHarness
         private
 
         def validate_version!(version)
-          version_str = version.to_s
+          unless version.is_a?(String) && !version.strip.empty?
+            raise ArgumentError, "Invalid version: #{version.inspect}. " \
+              "Must be a semver string (e.g. '2.1.92'), optional pre-release suffix, or a channel token ('latest', 'stable')."
+          end
+
+          version_str = version.strip
 
           unless VALID_VERSION_PATTERN.match?(version_str)
             raise ArgumentError, "Invalid version: #{version.inspect}. " \
               "Must be a semver string (e.g. '2.1.92'), optional pre-release suffix, or a channel token ('latest', 'stable')."
           end
 
-          # Channel tokens are not concrete versions; skip requirement check.
           return if %w[latest stable].include?(version_str)
 
-          # Validate concrete versions against the supported range.
-          gem_version = Gem::Version.new(version_str)
+          gem_version = begin
+            Gem::Version.new(version_str)
+          rescue ArgumentError
+            raise ArgumentError, "Invalid version: #{version.inspect}. " \
+              "Must be a semver string (e.g. '2.1.92'), optional pre-release suffix, or a channel token ('latest', 'stable')."
+          end
           return if SUPPORTED_CLI_REQUIREMENT.satisfied_by?(gem_version)
 
           raise ArgumentError, "Version #{version.inspect} is outside the supported range " \
@@ -334,7 +343,7 @@ module AgentHarness
           rate_limited: [
             /rate.?limit/i,
             /too.?many.?requests/i,
-            /429/,
+            /\b429\b/,
             /overloaded/i,
             /session.?limit/i
           ],
@@ -343,7 +352,7 @@ module AgentHarness
             /authentication.*error/i,
             /invalid.*api.*key/i,
             /unauthorized/i,
-            /401/,
+            /\b401\b/,
             /session.*expired/i,
             /not.*logged.*in/i,
             /login.*required/i,
@@ -359,17 +368,17 @@ module AgentHarness
             /connection.*reset/i,
             /temporary.*error/i,
             /service.*unavailable/i,
-            /503/,
-            /502/,
-            /504/
+            /\b503\b/,
+            /\b502\b/,
+            /\b504\b/
           ],
           permanent: [
             /invalid.*model/i,
             /unsupported.*operation/i,
             /not.*found/i,
-            /404/,
+            /\b404\b/,
             /bad.*request/i,
-            /400/,
+            /\b400\b/,
             /model.*deprecated/i,
             /end-of-life/i
           ]

data/lib/agent_harness/providers/base.rb

@@ -41,7 +41,7 @@ module AgentHarness
         rate_limited: [
           /rate.?limit/i,
           /too.?many.?requests/i,
-          /429/
+          /\b429\b/
         ],
         auth_expired: [
           /invalid.*api.*key/i,
@@ -57,8 +57,8 @@ module AgentHarness
           /timeout/i,
           /connection.*error/i,
           /service.*unavailable/i,
-          /503/,
-          /502/
+          /\b503\b/,
+          /\b502\b/
         ]
       }.tap { |patterns| patterns.each_value(&:freeze) }.freeze
 
@@ -98,6 +98,8 @@ module AgentHarness
       # @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.
+      #   Providers can derive request-scoped execution preparation from this
+      #   runtime to materialize config files or other bootstrap state.
       # @return [Response] the response
       def send_message(prompt:, **options)
         log_debug("send_message_start", prompt_length: prompt.length, options: options.keys)
@@ -111,6 +113,7 @@ module AgentHarness
 
         # Build command
         command = build_command(prompt, options)
+        preparation = build_execution_preparation(options)
 
         # Calculate timeout
         timeout = options[:timeout] || @config.timeout || default_timeout
@@ -121,6 +124,7 @@ module AgentHarness
           command,
           timeout: timeout,
           env: build_env(options),
+          preparation: preparation,
           **command_execution_options(options)
         )
         duration = Time.now - start_time
@@ -210,6 +214,17 @@ module AgentHarness
         env
       end
 
+      # Build structured runtime preparation for the executor.
+      #
+      # Provider subclasses can override to request request-scoped file writes
+      # or other bootstrap work without shell-wrapping the main command.
+      #
+      # @param options [Hash] options
+      # @return [ExecutionPreparation, nil] preparation contract or nil
+      def build_execution_preparation(options)
+        nil
+      end
+
       # Parse CLI output into Response - override in subclasses
       #
       # Combines stdout and stderr for error classification so that
@@ -309,8 +324,22 @@ module AgentHarness
         execution_options
       end
 
-      def execute_with_timeout(command, timeout:, env:, stdin_data: nil, **execution_options)
-        @executor.execute(command, timeout: timeout, env: env, stdin_data: stdin_data, **execution_options)
+      def execute_with_timeout(command, timeout:, env:, preparation: nil, stdin_data: nil, **execution_options)
+        kwargs = {timeout: timeout, env: env}
+        kwargs[:stdin_data] = stdin_data unless stdin_data.nil?
+        kwargs[:preparation] = preparation unless preparation.nil?
+        kwargs.merge!(execution_options)
+
+        @executor.execute(command, **kwargs)
+      rescue ArgumentError => e
+        unknown_keyword_message = e.message
+        raise unless unknown_keyword_message.start_with?("unknown keyword", "unknown keywords")
+        raise unless unknown_keyword_message.include?(":preparation")
+
+        raise ProviderError.new(
+          "Injected executor #{@executor.class}#execute must accept the preparation: keyword argument",
+          original_error: e
+        )
       end
 
       def track_tokens(response)

data/lib/agent_harness/providers/codex.rb

@@ -63,7 +63,23 @@ module AgentHarness
         end
 
         def installation_contract(version: SUPPORTED_CLI_VERSION)
-          unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(Gem::Version.new(version))
+          version = version.strip if version.respond_to?(:strip)
+
+          unless version.is_a?(String) && !version.empty?
+            raise ArgumentError,
+              "Unsupported Codex CLI version #{version.inspect}; " \
+              "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
+          parsed_version = begin
+            Gem::Version.new(version)
+          rescue ArgumentError
+            raise ArgumentError,
+              "Unsupported Codex CLI version #{version.inspect}; " \
+              "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
+          unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(parsed_version)
             raise ArgumentError,
               "Unsupported Codex CLI version #{version.inspect}; " \
               "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
@@ -156,7 +172,7 @@ module AgentHarness
 
       def error_patterns
         COMMON_ERROR_PATTERNS.merge(
-          auth_expired: COMMON_ERROR_PATTERNS[:auth_expired] + [/401/, /incorrect.*api.*key/i],
+          auth_expired: COMMON_ERROR_PATTERNS[:auth_expired] + [/\b401\b/, /incorrect.*api.*key/i],
           transient: COMMON_ERROR_PATTERNS[:transient] + [/connection.*reset/i],
           sandbox_failure: [
             /bwrap.*no permissions/i,
@@ -172,7 +188,7 @@ module AgentHarness
           if api_key.strip.start_with?("sk-")
             return {valid: true, expires_at: nil, error: nil, auth_method: :api_key}
           else
-            return {valid: false, expires_at: nil, error: "OPENAI_API_KEY is set but does not appear to be a valid OpenAI API key"}
+            return {valid: false, expires_at: nil, error: "OPENAI_API_KEY is set but does not appear to be a valid OpenAI API key", auth_method: nil}
           end
         end
 
@@ -183,14 +199,14 @@ module AgentHarness
             if key.strip.start_with?("sk-")
               return {valid: true, expires_at: nil, error: nil, auth_method: :config_file}
             else
-              return {valid: false, expires_at: nil, error: "Config file API key is set but does not appear to be a valid OpenAI API key"}
+              return {valid: false, expires_at: nil, error: "Config file API key is set but does not appear to be a valid OpenAI API key", auth_method: nil}
             end
           end
         end
 
-        {valid: false, expires_at: nil, error: "No OpenAI API key found. Set OPENAI_API_KEY or configure in #{codex_config_path}"}
+        {valid: false, expires_at: nil, error: "No OpenAI API key found. Set OPENAI_API_KEY or configure in #{codex_config_path}", auth_method: nil}
       rescue IOError, JSON::ParserError => e
-        {valid: false, expires_at: nil, error: e.message}
+        {valid: false, expires_at: nil, error: e.message, auth_method: nil}
       end
 
       def health_status

data/lib/agent_harness/providers/cursor.rb

@@ -228,7 +228,7 @@ module AgentHarness
           rate_limited: [
             /rate.?limit/i,
             /too.?many.?requests/i,
-            /429/
+            /\b429\b/
           ],
           auth_expired: [
             /authentication.*error/i,
@@ -264,12 +264,14 @@ module AgentHarness
 
         # Execute command with prompt on stdin
         env = build_env(options)
+        preparation = build_execution_preparation(options)
         start_time = Time.now
         result = execute_with_timeout(
           command,
           timeout: timeout,
           env: env,
           stdin_data: prompt,
+          preparation: preparation,
           **command_execution_options(options)
         )
         duration = Time.now - start_time

data/lib/agent_harness/providers/gemini.rb

@@ -40,6 +40,12 @@ module AgentHarness
         end
 
         def install_contract(version: SUPPORTED_CLI_VERSION)
+          version = version.strip if version.respond_to?(:strip)
+
+          unless version.is_a?(String) && !version.empty?
+            raise ArgumentError, "Unsupported Gemini CLI version #{version.inspect}. Supported requirement: #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
           parsed_version = begin
             Gem::Version.new(version)
           rescue ArgumentError
@@ -179,7 +185,7 @@ module AgentHarness
           rate_limited: [
             /rate.?limit/i,
             /quota.?exceeded/i,
-            /429/
+            /\b429\b/
           ],
           auth_expired: [
             /authentication/i,
@@ -193,7 +199,7 @@ module AgentHarness
           transient: [
             /timeout/i,
             /temporary/i,
-            /503/
+            /\b503\b/
           ]
         }
       end
@@ -205,21 +211,21 @@ module AgentHarness
         end
 
         credentials = read_gemini_credentials
-        return {valid: false, expires_at: nil, error: "No Gemini credentials found. Run 'gemini auth login' or set GEMINI_API_KEY or GOOGLE_API_KEY"} unless credentials
+        return {valid: false, expires_at: nil, error: "No Gemini credentials found. Run 'gemini auth login' or set GEMINI_API_KEY or GOOGLE_API_KEY", auth_method: nil} unless credentials
 
         token = credentials["access_token"] || credentials["oauth_token"]
         unless token.is_a?(String) && !token.strip.empty?
-          return {valid: false, expires_at: nil, error: "No authentication token in Gemini credentials"}
+          return {valid: false, expires_at: nil, error: "No authentication token in Gemini credentials", auth_method: nil}
         end
 
         expires_at = parse_gemini_expiry(credentials)
         if expires_at && expires_at < Time.now
-          {valid: false, expires_at: expires_at, error: "Gemini session expired. Run 'gemini auth login' to re-authenticate"}
+          {valid: false, expires_at: expires_at, error: "Gemini session expired. Run 'gemini auth login' to re-authenticate", auth_method: :oauth}
         else
           {valid: true, expires_at: expires_at, error: nil, auth_method: :oauth}
         end
       rescue IOError, JSON::ParserError => e
-        {valid: false, expires_at: nil, error: e.message}
+        {valid: false, expires_at: nil, error: e.message, auth_method: nil}
       end
 
       def health_status

data/lib/agent_harness/providers/kilocode.rb

@@ -41,6 +41,7 @@ module AgentHarness
         end
 
         def installation_contract(version: DEFAULT_VERSION)
+          version = version.strip if version.respond_to?(:strip)
           validate_install_version!(version)
           package_spec = "#{PACKAGE_NAME}@#{version}"
 
@@ -67,8 +68,22 @@ module AgentHarness
         private
 
         def validate_install_version!(version)
+          unless version.is_a?(String) && !version.strip.empty?
+            raise ArgumentError,
+              "Unsupported Kilocode CLI version #{version.inspect}; " \
+              "supported versions must satisfy #{SUPPORTED_VERSION_REQUIREMENT}"
+          end
+
+          parsed_version = begin
+            Gem::Version.new(version)
+          rescue ArgumentError
+            raise ArgumentError,
+              "Unsupported Kilocode CLI version #{version.inspect}; " \
+              "supported versions must satisfy #{SUPPORTED_VERSION_REQUIREMENT}"
+          end
+
           requirement = Gem::Requirement.new(SUPPORTED_VERSION_REQUIREMENT)
-          return if requirement.satisfied_by?(Gem::Version.new(version))
+          return if requirement.satisfied_by?(parsed_version)
 
           raise ArgumentError,
             "Unsupported Kilocode CLI version #{version.inspect}; " \

data/lib/agent_harness/providers/opencode.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module AgentHarness
   module Providers
     # OpenCode CLI provider
@@ -99,11 +101,13 @@ module AgentHarness
           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)
+          parsed_version = begin
+            Gem::Version.new(normalized_version)
+          rescue ArgumentError
+            raise ArgumentError, unsupported_version_message(version)
+          end
           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
 
@@ -183,9 +187,57 @@ module AgentHarness
         env
       end
 
+      def build_execution_preparation(options)
+        runtime = options[:provider_runtime]
+        return nil unless runtime
+
+        config_payload = opencode_config_payload(runtime)
+        return nil unless config_payload
+
+        ExecutionPreparation.new(
+          file_writes: [
+            {
+              path: opencode_config_path(runtime),
+              content: serialize_opencode_config(config_payload),
+              mode: 0o600
+            }
+          ]
+        )
+      end
+
       def default_timeout
         300
       end
+
+      private
+
+      def opencode_config_payload(runtime)
+        metadata = runtime.metadata
+        config_extras = metadata[:config] || metadata["config"] || {}
+        unless config_extras.is_a?(Hash)
+          raise ArgumentError, "OpenCode runtime metadata config must be a Hash of provider-specific extras (got #{config_extras.class})"
+        end
+
+        payload = stringify_keys(config_extras)
+        payload["model"] = runtime.model if runtime.model
+        payload["provider"] = runtime.api_provider if runtime.api_provider
+        payload["baseURL"] = runtime.base_url if runtime.base_url
+        payload.empty? ? nil : payload
+      end
+
+      def opencode_config_path(_runtime)
+        "~/.config/opencode/opencode.json"
+      end
+
+      def serialize_opencode_config(payload)
+        JSON.pretty_generate(payload)
+      end
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value
+        end
+      end
     end
   end
 end

data/lib/agent_harness/version.rb

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

data/lib/agent_harness.rb

@@ -238,6 +238,7 @@ end
 require_relative "agent_harness/errors"
 require_relative "agent_harness/mcp_server"
 require_relative "agent_harness/provider_runtime"
+require_relative "agent_harness/execution_preparation"
 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.8
+  version: 0.5.9
 platform: ruby
 authors:
 - Bart Agapinan
@@ -89,6 +89,7 @@ files:
 - ".rubocop.yml"
 - ".simplecov"
 - ".tool-versions"
+- AUDIT_DISPOSITION.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -104,6 +105,7 @@ files:
 - lib/agent_harness/docker_command_executor.rb
 - lib/agent_harness/error_taxonomy.rb
 - lib/agent_harness/errors.rb
+- lib/agent_harness/execution_preparation.rb
 - lib/agent_harness/mcp_server.rb
 - lib/agent_harness/orchestration/circuit_breaker.rb
 - lib/agent_harness/orchestration/conductor.rb