agent-harness 0.5.6 → 0.5.7

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
@@ -49,6 +52,37 @@ module AgentHarness
             {name: "codex", family: "codex", tier: "standard", provider: "codex"}
           ]
         end
+
+        def installation_contract
+          default_package = "@openai/codex@#{SUPPORTED_CLI_VERSION}".freeze
+          install_command_prefix = ["npm", "install", "-g", "--ignore-scripts"].freeze
+          install_command = (install_command_prefix + [default_package]).freeze
+          supported_versions = [SUPPORTED_CLI_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: SUPPORTED_CLI_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 +228,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 +246,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 +263,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 +304,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

@@ -83,6 +83,10 @@ module AgentHarness
         def supports_model_family?(family_name)
           family_name.match?(/^(claude|gpt|cursor)-/)
         end
+
+        def smoke_test_contract
+          Base::DEFAULT_SMOKE_TEST_CONTRACT
+        end
       end
 
       def name
@@ -189,7 +193,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
@@ -327,7 +337,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,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

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
@@ -116,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,
@@ -155,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
@@ -87,7 +154,7 @@ 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

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.6"
+  VERSION = "0.5.7"
 end