agent-harness 0.15.0 → 0.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34ea90d66e03bff4f53fe144d888ab33909d80e9a198a9a53f7dac00c0ed5d52
-  data.tar.gz: 4daf550bb940f4176b06ce186658803e090a90ed2e5811ae7f22d61dc95391b8
+  metadata.gz: 1c7a73c78312193fa3d7a73f3fa32aa032f9a5c8748dd0a679b2f05abc0853fe
+  data.tar.gz: ca7ed61365d3df1aaa8c3b48ee0100804e7ff49ad08f4da73cc07ce444934b79
 SHA512:
-  metadata.gz: 9273ea29e29a8380e9f64a926019bac4adc160b2205aecceec2d5ba8e0837d16b58ab9106f05e61832153de95c03c9c7a58b1458588a4f4552a0218c210a4c4a
-  data.tar.gz: 0ccefa077c32912d9e6dd205d20420d5ba0170fcfa763df22ca65902ea7fcb9ba600c439e91c38c398fc221dc3b41b9662ce5b693e418078dfd1116027378743
+  metadata.gz: 7bbd40a153f7565617f151d2dea5d7bdded0314b3d144971947ab92699dde8c0851a83ab15eed45f0a4eb34faf30a75274de88434963420b28a68263db1c77fd
+  data.tar.gz: c97a38b9bdb74397b18a9c37f641e3469be3e0fa9532a8728e2f5a8517b2c14bacd5b4b65441fda0c28f2397ab21f83ead4ceaa0aa17585c02c32b5a22d5d8f8

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.15.0"
+  ".": "0.16.1"
 }

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.16.1](https://github.com/viamin/agent-harness/compare/agent-harness/v0.16.0...agent-harness/v0.16.1) (2026-05-03)
+
+
+### Bug Fixes
+
+* **kilocode:** config_file_content generates invalid JSON for kilo CLI v7.1.3 ([#190](https://github.com/viamin/agent-harness/issues/190)) ([0f7e24a](https://github.com/viamin/agent-harness/commit/0f7e24a8c342045d16a9332385e93f0607d0845e))
+
+## [0.16.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.15.0...agent-harness/v0.16.0) (2026-05-03)
+
+
+### Features
+
+* Add plan-only / dry-run API returning command+env without execution ([#192](https://github.com/viamin/agent-harness/issues/192)) ([0e6a105](https://github.com/viamin/agent-harness/commit/0e6a1053515e0495900b67c5845a2f95c571f055))
+
 ## [0.15.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.14.1...agent-harness/v0.15.0) (2026-05-03)
 
 

data/lib/agent_harness/providers/adapter.rb

@@ -775,6 +775,15 @@ module AgentHarness
         raise NotImplementedError, "#{self.class} must implement #send_message"
       end
 
+      # Return the provider CLI execution plan without executing the command.
+      #
+      # @param prompt [String] the prompt to send
+      # @param options [Hash] provider-specific options
+      # @return [Hash] with :command, :env, and :preparation keys
+      def plan_execution(prompt:, **options)
+        raise NotImplementedError, "#{self.class} must implement #plan_execution"
+      end
+
       # Provider configuration schema for app-driven setup UIs
       #
       # Returns metadata describing the configurable fields, supported

data/lib/agent_harness/providers/aider.rb

@@ -263,6 +263,26 @@ module AgentHarness
         cleanup_llm_history_file!(llm_history_path)
       end
 
+      def plan_execution(prompt:, **options)
+        log_debug("plan_execution_start", prompt_length: prompt.length, options: options.keys)
+
+        options = normalize_provider_runtime(options)
+        options = normalize_mcp_servers(options)
+        validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
+
+        llm_history_path = generate_llm_history_path
+
+        {
+          command: build_command(prompt, options.merge(llm_history_path: llm_history_path)),
+          env: build_env(options),
+          preparation: build_execution_preparation(options)
+        }
+      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+        raise
+      rescue => e
+        handle_error(e, prompt: prompt, options: options)
+      end
+
       # Parse raw container output into a Response.
       #
       # Overrides the base implementation to support the

data/lib/agent_harness/providers/anthropic.rb

@@ -386,6 +386,17 @@ module AgentHarness
         cleanup_mcp_tempfiles!
       end
 
+      def plan_execution(prompt:, **options)
+        if options[:mode] == :text
+          raise ProviderError,
+            "Anthropic text mode uses the HTTP transport and does not produce a CLI execution plan"
+        end
+
+        super
+      ensure
+        cleanup_mcp_tempfiles!
+      end
+
       def api_key_env_var_names = ["ANTHROPIC_API_KEY"]
 
       def api_key_unset_vars = ["ANTHROPIC_BASE_URL", "ANTHROPIC_HEADER_X_AGENT_RUN_ID", "ANTHROPIC_HEADER_X_PROXY_TOKEN"]

data/lib/agent_harness/providers/base.rb

@@ -197,6 +197,56 @@ module AgentHarness
         handle_error(e, prompt: prompt, options: options)
       end
 
+      # Return the provider CLI execution plan without executing it.
+      #
+      # @param prompt [String] the prompt to send
+      # @param options [Hash] additional options
+      # @return [Hash] with :command, :env, and :preparation keys
+      def plan_execution(prompt:, **options)
+        log_debug("plan_execution_start", prompt_length: prompt.length, options: options.keys)
+
+        if options[:mode] == :text && !supports_text_mode?
+          log_debug("text_mode_cli_fallback", provider: self.class.provider_name)
+          options = options.except(:mode).merge(tools: :none)
+        end
+
+        if options[:tools] && !supports_tool_control?
+          log_debug("tools_option_unsupported",
+            provider: self.class.provider_name,
+            tools: options[:tools])
+          @logger&.warn(
+            "[AgentHarness::#{self.class.provider_name}] tools option is not supported " \
+            "by this provider and will be ignored"
+          )
+        end
+
+        options = normalize_provider_runtime(options)
+
+        extension_context = apply_extensions_to_prompt(prompt, options)
+        prompt = extension_context.prompt
+        options = extension_context.options
+        options = normalize_sub_agent(options)
+        prompt = apply_sub_agent_to_prompt(prompt, options[:translated_sub_agent])
+
+        options = normalize_mcp_servers(options)
+        validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
+
+        {
+          command: build_command(prompt, options),
+          env: build_env(options),
+          preparation: build_execution_preparation(options)
+        }
+      rescue ExtensionCompatibilityError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+        raise
+      rescue => e
+        handle_error(e, prompt: prompt, options: options)
+      ensure
+        # build_command may call build_mcp_flags which creates tempfiles (and
+        # in Docker even invokes the executor) via write_mcp_config_file.
+        # Clean up so that planning has no lasting side effects.
+        cleanup_mcp_tempfiles! if respond_to?(:cleanup_mcp_tempfiles!, true)
+      end
+
       # Send a multi-turn chat message via the provider's chat transport.
       #
       # Providers that support chat mode can accept either +conversation:+

data/lib/agent_harness/providers/cursor.rb

@@ -312,6 +312,28 @@ module AgentHarness
         handle_error(e, prompt: prompt, options: options)
       end
 
+      def plan_execution(prompt:, **options)
+        log_debug("plan_execution_start", prompt_length: prompt.length, options: options.keys)
+
+        options = normalize_provider_runtime(options)
+        options = normalize_mcp_servers(options)
+        validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
+
+        runtime = options[:provider_runtime]
+        cmd = [self.class.binary_name, "-p"]
+        cmd.concat(runtime.flags) if runtime&.flags&.any?
+
+        {
+          command: cmd,
+          env: build_env(options),
+          preparation: build_execution_preparation(options)
+        }
+      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+        raise
+      rescue => e
+        handle_error(e, prompt: prompt, options: options)
+      end
+
       protected
 
       def build_command(prompt, options)

data/lib/agent_harness/providers/github_copilot.rb

@@ -188,11 +188,11 @@ module AgentHarness
         ["--allow-all"]
       end
 
-      def supports_sessions?(probe_timeout: nil, env: {}, version: nil)
+      def supports_sessions?(probe_timeout: nil, env: {}, version: :not_provided)
         legacy_prompt_cli?(version: version, probe_timeout: probe_timeout, env: env)
       end
 
-      def session_flags(session_id, version: nil, probe_timeout: nil, env: {})
+      def session_flags(session_id, version: :not_provided, probe_timeout: nil, env: {})
         return [] unless session_id && !session_id.empty?
         return [] unless legacy_prompt_cli?(version: version, probe_timeout: probe_timeout, env: env)
 
@@ -345,6 +345,30 @@ module AgentHarness
         handle_error(e, prompt: prompt, options: options)
       end
 
+      def plan_execution(prompt:, **options)
+        log_debug("plan_execution_start", prompt_length: prompt.length, options: options.keys)
+
+        options = normalize_provider_runtime(options)
+        options = normalize_mcp_servers(options)
+        validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
+
+        env = build_env(options)
+        version = planned_copilot_cli_version(env)
+        raise unsupported_subcommand_cli_error if subcommand_cli_version?(version)
+
+        options = options.merge(_command_env: env, _planned_cli_version: version)
+
+        {
+          command: build_command(prompt, options),
+          env: env,
+          preparation: build_execution_preparation(options)
+        }
+      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+        raise
+      rescue => e
+        handle_error(e, prompt: prompt, options: options)
+      end
+
       # Parse raw container output into a Response.
       #
       # Overrides the base implementation to support the
@@ -377,7 +401,14 @@ module AgentHarness
       def build_command(prompt, options)
         env = options.fetch(:_command_env) { build_env(options) }
         runtime = options[:provider_runtime]
-        version = copilot_cli_version(probe_timeout: options[:_version_probe_timeout], env: env)
+        version = if options.key?(:_planned_cli_version)
+          options[:_planned_cli_version]
+        else
+          copilot_cli_version(
+            probe_timeout: options[:_version_probe_timeout],
+            env: env
+          )
+        end
 
         raise unsupported_subcommand_cli_error if subcommand_cli_version?(version)
 
@@ -440,13 +471,13 @@ module AgentHarness
         ["--allow-all-tools"]
       end
 
-      def supports_json_output_format?(probe_timeout: nil, env: {}, version: nil)
-        version ||= copilot_cli_version(probe_timeout: probe_timeout, env: env)
+      def supports_json_output_format?(probe_timeout: nil, env: {}, version: :not_provided)
+        version = copilot_cli_version(probe_timeout: probe_timeout, env: env) if version == :not_provided
         !version.nil? && !subcommand_cli_version?(version) && version >= JSON_OUTPUT_MIN_VERSION
       end
 
-      def legacy_prompt_cli?(probe_timeout: nil, env: {}, version: nil)
-        version ||= copilot_cli_version(probe_timeout: probe_timeout, env: env)
+      def legacy_prompt_cli?(probe_timeout: nil, env: {}, version: :not_provided)
+        version = copilot_cli_version(probe_timeout: probe_timeout, env: env) if version == :not_provided
         !version.nil? && !subcommand_cli_version?(version)
       end
 
@@ -475,6 +506,17 @@ module AgentHarness
         @copilot_cli_versions[cache_key] = nil if defined?(cache_key)
       end
 
+      def planned_copilot_cli_version(env)
+        cache_key = version_probe_cache_key(env)
+        @copilot_cli_versions ||= {}
+        return @copilot_cli_versions[cache_key] if @copilot_cli_versions.key?(cache_key)
+
+        # When no cached version is available (cold start), return nil so
+        # build_command falls back to the conservative -s flag path, matching
+        # the behavior of send_message when the version probe returns nil.
+        nil
+      end
+
       def version_probe_cache_key(env)
         [
           probe_env_cache_component(env, "PATH", inherited_label: :inherited_path, override_label: :path_override),

data/lib/agent_harness/providers/kilocode.rb

@@ -130,10 +130,16 @@ module AgentHarness
       end
 
       def config_file_content(options = {})
-        {
-          provider: options[:api_provider],
-          model: options[:model_id]
-        }.to_json
+        # Only use explicit provider_name or default to "openai".
+        # api_provider is a generic backend label (e.g. "openrouter") that is not
+        # a valid Kilo built-in provider ID, so we must not fall back to it here.
+        provider_name = options[:provider_name] || "openai"
+        model_id = options[:model_id]
+
+        config = {provider: {provider_name => {}}}
+        config[:model] = "#{provider_name}/#{model_id}" if model_id
+
+        config.to_json
       end
 
       def error_patterns

data/lib/agent_harness/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.1
 platform: ruby
 authors:
 - Bart Agapinan