agent-harness 0.5.6 → 0.5.8

data/lib/agent_harness/providers/aider.rb

@@ -6,6 +6,17 @@ module AgentHarness
     #
     # Provides integration with the Aider CLI tool.
     class Aider < Base
+      UV_VERSION = "0.8.17"
+      SUPPORTED_CLI_VERSION = "0.86.2"
+      SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 0.87.0").freeze
+      PYTHON_VERSION = "python3.12"
+      BINARY_PATH = "/usr/local/bin/aider"
+      UV_TOOL_ENV = {
+        "UV_TOOL_BIN_DIR" => "/usr/local/bin",
+        "UV_TOOL_DIR" => "/opt/uv/tools",
+        "UV_PYTHON_INSTALL_DIR" => "/opt/uv/python"
+      }.freeze
+
       class << self
         def provider_name
           :aider
@@ -49,6 +60,54 @@ module AgentHarness
             {name: "claude-3-5-sonnet", family: "claude-3-5-sonnet", tier: "standard", provider: "aider"}
           ]
         end
+
+        def installation_contract(version: SUPPORTED_CLI_VERSION)
+          unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(Gem::Version.new(version))
+            raise ArgumentError,
+              "Unsupported Aider CLI version #{version.inspect}; " \
+              "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
+          default_package = "aider-chat==#{version}".freeze
+          bootstrap_command = [
+            "python3", "-m", "pip", "install", "--no-cache-dir", "--break-system-packages", "uv==#{UV_VERSION}"
+          ].freeze
+          install_command_prefix = [
+            "uv", "tool", "install", "--force", "--python", PYTHON_VERSION, "--with", "pip"
+          ].freeze
+          install_command = (install_command_prefix + [default_package]).freeze
+          supported_versions = [version].freeze
+          version_requirement = SUPPORTED_CLI_REQUIREMENT.requirements
+            .map { |op, ver| "#{op} #{ver}".freeze }
+            .freeze
+
+          contract = {
+            source: :uv_tool,
+            bootstrap_source: :pip,
+            bootstrap_package: "uv==#{UV_VERSION}",
+            bootstrap_commands: [bootstrap_command].freeze,
+            install_environment: UV_TOOL_ENV,
+            package: default_package,
+            package_name: "aider-chat",
+            version: version,
+            version_format: "%{package_name}==%{version}",
+            version_requirement: version_requirement,
+            binary_name: binary_name,
+            binary_path: BINARY_PATH,
+            install_command_prefix: install_command_prefix,
+            install_command: install_command,
+            supported_versions: supported_versions
+          }
+
+          contract.each_value do |value|
+            value.freeze if value.is_a?(String)
+          end
+          contract.freeze
+        end
+
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
       end
 
       def name

data/lib/agent_harness/providers/anthropic.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "shellwords"
 
 module AgentHarness
   module Providers
@@ -15,6 +16,12 @@ module AgentHarness
     class Anthropic < Base
       # Model name pattern for Anthropic Claude models
       MODEL_PATTERN = /^claude-[\d.-]+-(?:opus|sonnet|haiku)(?:-\d{8})?$/i
+      SUPPORTED_CLI_VERSION = "2.1.92"
+      SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 2.2.0").freeze
+
+      # Matches semver (e.g. "2.1.92"), optional pre-release (e.g. "2.1.92-beta.1"),
+      # or channel tokens (e.g. "latest", "stable").
+      VALID_VERSION_PATTERN = /\A(?:\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?|latest|stable)\z/
 
       class << self
         def provider_name
@@ -25,11 +32,79 @@ module AgentHarness
           "claude"
         end
 
+        def install_contract(version: nil)
+          target_version = version || SUPPORTED_CLI_VERSION
+          validate_version!(target_version)
+          version_requirement = SUPPORTED_CLI_REQUIREMENT.requirements
+            .map { |op, ver| "#{op} #{ver}" }
+            .join(", ")
+          channel_token = %w[latest stable].include?(target_version.to_s)
+
+          warning = "Review the downloaded installer before execution and verify any published checksum or signature metadata when available."
+          if channel_token
+            warning += " Channel '#{target_version}' is not pinned; the resolved version may fall " \
+              "outside the supported range (#{version_requirement}). Verify the installed version " \
+              "after installation."
+          end
+
+          {
+            provider: provider_name,
+            binary_name: binary_name,
+            binary_paths: [
+              "$HOME/.local/bin/claude",
+              binary_name
+            ],
+            install: {
+              strategy: :shell,
+              source: "official",
+              command: "tmp_script=$(mktemp) && trap 'rm -f \"$tmp_script\"' EXIT && curl -fsSL https://claude.ai/install.sh -o \"$tmp_script\" && bash \"$tmp_script\" #{Shellwords.shellescape(target_version)}",
+              warning: warning,
+              post_install_binary_path: "$HOME/.local/bin/claude",
+              # When a channel token is used, include the requirement so
+              # consumers can validate the installed version post-install.
+              version_not_pinned: channel_token
+            },
+            supported_versions: {
+              default: SUPPORTED_CLI_VERSION,
+              requirement: version_requirement,
+              channel: "stable"
+            },
+            runtime_contract: {
+              available_via: binary_name,
+              build_command: [
+                binary_name,
+                "--print",
+                "--output-format=json"
+              ],
+              required_features: [
+                "print_mode",
+                "json_output",
+                "mcp_config",
+                "mcp_list",
+                "dangerously_skip_permissions",
+                "models_list"
+              ]
+            }
+          }
+        end
+
         def available?
           executor = AgentHarness.configuration.command_executor
           !!executor.which(binary_name)
         end
 
+        def provider_metadata_overrides
+          {
+            auth: {
+              service: :anthropic,
+              api_family: :anthropic
+            },
+            identity: {
+              bot_usernames: %w[claude anthropic]
+            }
+          }
+        end
+
         def firewall_requirements
           {
             domains: [
@@ -81,8 +156,31 @@ module AgentHarness
           MODEL_PATTERN.match?(family_name)
         end
 
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
+
         private
 
+        def validate_version!(version)
+          version_str = version.to_s
+
+          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)
+          return if SUPPORTED_CLI_REQUIREMENT.satisfied_by?(gem_version)
+
+          raise ArgumentError, "Version #{version.inspect} is outside the supported range " \
+            "(#{SUPPORTED_CLI_REQUIREMENT}). Update SUPPORTED_CLI_REQUIREMENT before targeting this version."
+        end
+
         def parse_models_list(output)
           return [] if output.nil? || output.empty?
 

data/lib/agent_harness/providers/base.rb

@@ -22,16 +22,18 @@ module AgentHarness
     #         system("which my-cli > /dev/null 2>&1")
     #       end
     #     end
-    #
-    #     protected
-    #
-    #     def build_command(prompt, options)
-    #       [self.class.binary_name, "--prompt", prompt]
-    #     end
     #   end
     class Base
       include Adapter
 
+      DEFAULT_SMOKE_TEST_CONTRACT = {
+        prompt: "Reply with exactly OK.",
+        expected_output: "OK",
+        timeout: 30,
+        require_output: true,
+        success_message: "Smoke test passed"
+      }.freeze
+
       # Common error patterns shared across providers that use standard
       # HTTP-style error responses. Providers with unique patterns (e.g.
       # Anthropic, GitHub Copilot) override error_patterns entirely.
@@ -63,6 +65,12 @@ module AgentHarness
       attr_reader :config, :logger
       attr_accessor :executor
 
+      class << self
+        def smoke_test_contract
+          nil
+        end
+      end
+
       # Initialize the provider
       #
       # @param config [ProviderConfig, nil] provider configuration
@@ -109,7 +117,12 @@ module AgentHarness
 
         # Execute command
         start_time = Time.now
-        result = execute_with_timeout(command, timeout: timeout, env: build_env(options))
+        result = execute_with_timeout(
+          command,
+          timeout: timeout,
+          env: build_env(options),
+          **command_execution_options(options)
+        )
         duration = Time.now - start_time
 
         # Parse response
@@ -190,7 +203,11 @@ module AgentHarness
         runtime = options[:provider_runtime]
         return {} unless runtime
 
-        runtime.env.dup
+        # Return overrides only. Ruby subprocess spawning treats nil values as
+        # explicit unsets in the child process, while omitted keys are inherited.
+        env = runtime.env.dup
+        runtime.unset_env.each { |key| env[key] = nil }
+        env
       end
 
       # Parse CLI output into Response - override in subclasses
@@ -279,8 +296,21 @@ module AgentHarness
         options.merge(mcp_servers: normalized)
       end
 
-      def execute_with_timeout(command, timeout:, env:)
-        @executor.execute(command, timeout: timeout, env: env)
+      def command_execution_options(options)
+        execution_options = {
+          idle_timeout: options[:idle_timeout],
+          on_stdout_chunk: options[:on_stdout_chunk],
+          on_stderr_chunk: options[:on_stderr_chunk],
+          on_heartbeat: options[:on_heartbeat],
+          observer: options[:execution_observer] || options[:observer]
+        }.reject { |_, value| value.nil? }
+
+        execution_options[:heartbeat_interval] = options[:heartbeat_interval] if options.key?(:heartbeat_interval)
+        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)
       end
 
       def track_tokens(response)
@@ -319,7 +349,13 @@ module AgentHarness
             original_error: original_error
           )
         when :timeout
+          return original_error if original_error.is_a?(TimeoutError)
+
           TimeoutError.new(original_error.message, original_error: original_error)
+        when :idle_timeout
+          return original_error if original_error.is_a?(IdleTimeoutError)
+
+          IdleTimeoutError.new(original_error.message, original_error: original_error)
         else
           ProviderError.new(original_error.message, original_error: original_error)
         end

data/lib/agent_harness/providers/codex.rb

@@ -8,6 +8,9 @@ module AgentHarness
     #
     # Provides integration with the OpenAI Codex CLI tool.
     class Codex < Base
+      SUPPORTED_CLI_VERSION = "0.116.0"
+      SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 0.117.0").freeze
+
       class << self
         def provider_name
           :codex
@@ -22,6 +25,15 @@ module AgentHarness
           !!executor.which(binary_name)
         end
 
+        def provider_metadata_overrides
+          {
+            auth: {
+              service: :openai,
+              api_family: :openai
+            }
+          }
+        end
+
         def firewall_requirements
           {
             domains: [
@@ -49,6 +61,43 @@ module AgentHarness
             {name: "codex", family: "codex", tier: "standard", provider: "codex"}
           ]
         end
+
+        def installation_contract(version: SUPPORTED_CLI_VERSION)
+          unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(Gem::Version.new(version))
+            raise ArgumentError,
+              "Unsupported Codex CLI version #{version.inspect}; " \
+              "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
+          end
+
+          default_package = "@openai/codex@#{version}".freeze
+          install_command_prefix = ["npm", "install", "-g", "--ignore-scripts"].freeze
+          install_command = (install_command_prefix + [default_package]).freeze
+          supported_versions = [version].freeze
+          version_requirement = SUPPORTED_CLI_REQUIREMENT.requirements
+            .map { |op, ver| "#{op} #{ver}".freeze }
+            .freeze
+
+          contract = {
+            source: :npm,
+            package: default_package,
+            package_name: "@openai/codex",
+            version: version,
+            version_requirement: version_requirement,
+            binary_name: binary_name,
+            install_command_prefix: install_command_prefix,
+            install_command: install_command,
+            supported_versions: supported_versions
+          }
+
+          contract.each_value do |value|
+            value.freeze if value.is_a?(String)
+          end
+          contract.freeze
+        end
+
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
       end
 
       def name
@@ -194,12 +243,16 @@ module AgentHarness
 
       def build_command(prompt, options)
         cmd = [self.class.binary_name, "exec"]
-
-        # When running inside an already-sandboxed Docker container, Codex's
-        # own sandboxing conflicts with the outer sandbox. Use --full-auto to
-        # skip nested sandboxing while keeping full tool access.
-        # Also applies when dangerous_mode is explicitly requested.
-        if sandboxed_environment? || options[:dangerous_mode]
+        externally_sandboxed = externally_sandboxed?(options)
+
+        # When externally_sandboxed is set, use --dangerously-bypass-approvals-and-sandbox
+        # instead of --full-auto. In the Codex CLI, full_auto is checked first and
+        # selects workspace-write sandbox mode, which overrides the bypass flag.
+        # Passing both would leave the run in the wrong sandbox mode.
+        #
+        # When NOT externally sandboxed: use --full-auto for Docker containers
+        # (to skip nested sandboxing) or when dangerous_mode is explicitly requested.
+        if !externally_sandboxed && (sandboxed_environment? || options[:dangerous_mode])
           cmd += dangerous_mode_flags
         end
 
@@ -208,10 +261,13 @@ module AgentHarness
           unless flags.is_a?(Array)
             raise ArgumentError, "Codex configuration error: default_flags must be an array of strings"
           end
+          # Strip --full-auto from defaults when externally sandboxed to avoid
+          # conflicting with --dangerously-bypass-approvals-and-sandbox.
+          flags -= dangerous_mode_flags if externally_sandboxed
           cmd += flags if flags.any?
         end
 
-        if externally_sandboxed?(options)
+        if externally_sandboxed
           cmd += sandbox_bypass_flags
         end
 
@@ -222,7 +278,10 @@ module AgentHarness
         runtime = options[:provider_runtime]
         if runtime
           cmd += ["--model", runtime.model] if runtime.model
-          cmd += runtime.flags unless runtime.flags.empty?
+          runtime_flags = runtime.flags
+          # Strip --full-auto from runtime flags when externally sandboxed.
+          runtime_flags -= dangerous_mode_flags if externally_sandboxed
+          cmd += runtime_flags unless runtime_flags.empty?
         end
 
         cmd << prompt
@@ -260,7 +319,7 @@ module AgentHarness
       end
 
       def sandbox_bypass_flags
-        ["--sandbox", "none"]
+        ["--dangerously-bypass-approvals-and-sandbox"]
       end
 
       def read_codex_credentials

data/lib/agent_harness/providers/cursor.rb

@@ -12,6 +12,12 @@ module AgentHarness
     #   provider = AgentHarness::Providers::Cursor.new
     #   response = provider.send_message(prompt: "Hello!")
     class Cursor < Base
+      INSTALL_SCRIPT_URL = "https://cursor.com/install"
+      INSTALL_TARGET_LATEST = "latest"
+      INSTALL_BUILD = "2026.03.30-a5d3e17"
+      INSTALL_SCRIPT_SHA256 = "8371988b483abec13c07c10e95cccc839da81ebf9596e430d3c90835a227cbad"
+      INSTALL_LINUX_X64_PACKAGE_SHA256 = "e0d4b611db111d2dbe76474386271bff3e1dbb2cc6ddf527f9d5d5801b2ce2a0"
+
       class << self
         def provider_name
           :cursor
@@ -26,6 +32,15 @@ module AgentHarness
           !!executor.which(binary_name)
         end
 
+        def provider_metadata_overrides
+          {
+            auth: {
+              service: :cursor,
+              api_family: :cursor
+            }
+          }
+        end
+
         def firewall_requirements
           {
             domains: [
@@ -83,6 +98,67 @@ module AgentHarness
         def supports_model_family?(family_name)
           family_name.match?(/^(claude|gpt|cursor)-/)
         end
+
+        def install_metadata(version: nil)
+          install_target = normalize_install_target(version)
+          linux_x64_package_url = package_url_for(os: "linux", arch: "x64")
+
+          {
+            source: {
+              type: :shell_script,
+              url: INSTALL_SCRIPT_URL,
+              resolved_version: INSTALL_BUILD,
+              default_artifact_url: linux_x64_package_url
+            },
+            checksum: {
+              strategy: :sha256,
+              targets: {
+                script: {
+                  url: INSTALL_SCRIPT_URL,
+                  value: INSTALL_SCRIPT_SHA256
+                },
+                artifacts: {
+                  "linux/x64" => {
+                    url: linux_x64_package_url,
+                    value: INSTALL_LINUX_X64_PACKAGE_SHA256
+                  }
+                }
+              }
+            },
+            binary: {
+              name: binary_name,
+              path: "$HOME/.local/bin/#{binary_name}",
+              suggested_global_path: "/usr/local/bin/#{binary_name}"
+            },
+            version: {
+              default: INSTALL_TARGET_LATEST,
+              supported: install_target,
+              command: [binary_name, "--version"]
+            }
+          }
+        end
+
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
+
+        private
+
+        def package_url_for(os:, arch:)
+          format(
+            "https://downloads.cursor.com/lab/%<build>s/%<os>s/%<arch>s/agent-cli-package.tar.gz",
+            build: INSTALL_BUILD,
+            os: os,
+            arch: arch
+          )
+        end
+
+        def normalize_install_target(version)
+          target = version.nil? ? INSTALL_TARGET_LATEST : version.to_s
+          return target if target == INSTALL_TARGET_LATEST
+
+          raise ArgumentError, "Unsupported Cursor install target: #{version.inspect}"
+        end
       end
 
       def name
@@ -189,7 +265,13 @@ module AgentHarness
         # Execute command with prompt on stdin
         env = build_env(options)
         start_time = Time.now
-        result = @executor.execute(command, timeout: timeout, stdin_data: prompt, env: env)
+        result = execute_with_timeout(
+          command,
+          timeout: timeout,
+          env: env,
+          stdin_data: prompt,
+          **command_execution_options(options)
+        )
         duration = Time.now - start_time
 
         # Parse response
@@ -243,7 +325,7 @@ module AgentHarness
         return nil unless self.class.available?
 
         begin
-          result = @executor.execute(["cursor-agent", "mcp", "list"], timeout: 5)
+          result = @executor.execute([self.class.binary_name, "mcp", "list"], timeout: 5)
           return nil unless result.success?
 
           parse_mcp_servers_output(result.stdout)
@@ -327,7 +409,13 @@ module AgentHarness
         when :auth_expired
           raise AuthenticationError.new(error.message, provider: self.class.provider_name, original_error: error)
         when :timeout
+          raise error if error.is_a?(TimeoutError)
+
           raise TimeoutError.new(error.message, original_error: error)
+        when :idle_timeout
+          raise error if error.is_a?(IdleTimeoutError)
+
+          raise IdleTimeoutError.new(error.message, original_error: error)
         else
           raise ProviderError.new(error.message, original_error: error)
         end

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,41 @@ module AgentHarness
           !!executor.which(binary_name)
         end
 
+        def provider_metadata_overrides
+          {
+            auth: {
+              service: :google,
+              api_family: :gemini
+            }
+          }
+        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 +112,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