agent-harness 0.11.1 → 0.11.3

data/lib/agent_harness/mcp_config_translator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module McpConfigTranslator
+    module_function
+
+    def for_provider(provider, mcp_servers)
+      servers = normalize_servers(mcp_servers)
+
+      case provider.to_sym
+      when :anthropic, :claude, :claude_code
+        translate_for_claude(servers)
+      when :codex
+        translate_for_codex(servers)
+      when :openai
+        translate_for_openai(servers)
+      else
+        servers.map(&:to_h)
+      end
+    end
+
+    def normalize_servers(mcp_servers)
+      Array(mcp_servers).map do |server|
+        case server
+        when McpServer
+          server
+        when Hash
+          McpServer.from_hash(server)
+        else
+          raise McpConfigurationError, "MCP server must be a Hash or McpServer, got #{server.class}"
+        end
+      end
+    end
+
+    def translate_for_claude(mcp_servers)
+      {
+        mcpServers: mcp_servers.each_with_object({}) do |server, memo|
+          entry = server.stdio? ? {command: server.command} : {url: server.url}
+          entry[:args] = server.args if server.stdio? && !server.args.empty?
+          entry[:env] = server.env unless server.env.empty?
+          entry[:headers] = server.headers if server.http? && !server.headers.empty?
+          memo[server.name] = entry
+        end
+      }
+    end
+
+    def translate_for_codex(mcp_servers)
+      {
+        mcp_servers: mcp_servers.each_with_object({}) do |server, memo|
+          entry = server.stdio? ? {command: server.command, transport: server.transport} : {url: server.url, transport: server.transport}
+          entry[:args] = server.args if server.stdio? && !server.args.empty?
+          entry[:env] = server.env unless server.env.empty?
+          entry[:headers] = server.headers if server.http? && !server.headers.empty?
+          memo[server.name] = entry
+        end
+      }
+    end
+
+    def translate_for_openai(mcp_servers)
+      mcp_servers.map do |server|
+        unless server.http?
+          raise McpTransportUnsupportedError.new(
+            "Provider 'openai' only supports remote MCP servers over HTTP/SSE (server: '#{server.name}')",
+            provider: :openai
+          )
+        end
+
+        unsupported_headers = server.headers.keys - ["Authorization"]
+        unless unsupported_headers.empty?
+          raise McpConfigurationError,
+            "OpenAI MCP translation only supports the Authorization header (server: '#{server.name}')"
+        end
+
+        tool = {
+          type: "mcp",
+          server_label: server.name,
+          server_url: server.url,
+          require_approval: "never"
+        }
+        tool[:authorization] = server.headers["Authorization"] if server.headers.key?("Authorization")
+        tool
+      end
+    end
+  end
+end

data/lib/agent_harness/mcp_server.rb

@@ -10,7 +10,8 @@ module AgentHarness
   #   McpServer.new(
   #     name: "filesystem",
   #     transport: "stdio",
-  #     command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
+  #     command: "npx",
+  #     args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
   #     env: { "DEBUG" => "0" }
   #   )
   #
@@ -23,21 +24,24 @@ module AgentHarness
   class McpServer
     VALID_TRANSPORTS = %w[stdio http sse].freeze
 
-    attr_reader :name, :transport, :command, :args, :env, :url
+    attr_reader :name, :transport, :command, :args, :env, :url, :headers
 
     # @param name [String] unique name for this MCP server
     # @param transport [String] one of "stdio", "http", "sse"
-    # @param command [Array<String>, nil] command to launch (stdio only)
+    # @param command [String, Array<String>, nil] executable to launch (stdio only).
+    #   Arrays are accepted for backwards compatibility and normalized into
+    #   +command+ plus +args+.
     # @param args [Array<String>, nil] additional args for the command
     # @param env [Hash<String,String>, nil] environment variables for the server process
     # @param url [String, nil] URL for HTTP/SSE transport
-    def initialize(name:, transport:, command: nil, args: nil, env: nil, url: nil)
+    # @param headers [Hash<String,String>, nil] HTTP headers for remote MCP servers
+    def initialize(name:, transport:, command: nil, args: nil, env: nil, url: nil, headers: nil)
       @name = name
       @transport = transport.to_s
-      @command = command
-      @args = args || []
+      @command, @args = normalize_command_and_args(command, args)
       @env = env || {}
       @url = url
+      @headers = headers || {}
 
       validate!
     end
@@ -63,7 +67,8 @@ module AgentHarness
         command: hash[:command],
         args: hash[:args],
         env: hash[:env],
-        url: hash[:url]
+        url: hash[:url],
+        headers: hash[:headers]
       )
     end
 
@@ -75,6 +80,12 @@ module AgentHarness
       %w[http sse].include?(@transport)
     end
 
+    def command_argv
+      return [] unless stdio?
+
+      [@command, *@args]
+    end
+
     # Check if the MCP server is reachable based on its transport type.
     #
     # For stdio servers, checks that a command is present.
@@ -101,6 +112,7 @@ module AgentHarness
         h[:args] = @args unless @args.empty?
       else
         h[:url] = @url
+        h[:headers] = @headers unless @headers.empty?
       end
       h[:env] = @env unless @env.empty?
       h
@@ -118,6 +130,7 @@ module AgentHarness
 
       validate_args!
       validate_env!
+      validate_headers!
       validate_stdio! if stdio?
       validate_http! if http?
       validate_no_stdio_only_fields_on_http! if http?
@@ -137,15 +150,17 @@ module AgentHarness
         "MCP server '#{@name}' env must be a Hash with String keys and values"
     end
 
-    def validate_stdio!
-      if @command.nil? || !@command.is_a?(Array) || @command.empty?
-        raise McpConfigurationError,
-          "MCP server '#{@name}' with stdio transport requires a non-empty command array"
-      end
+    def validate_headers!
+      return if @headers.is_a?(Hash) && @headers.keys.all? { |k| k.is_a?(String) } && @headers.values.all? { |v| v.is_a?(String) }
 
-      unless @command.all? { |c| c.is_a?(String) }
+      raise McpConfigurationError,
+        "MCP server '#{@name}' headers must be a Hash with String keys and values"
+    end
+
+    def validate_stdio!
+      if @command.nil? || !@command.is_a?(String) || @command.strip.empty?
         raise McpConfigurationError,
-          "MCP server '#{@name}' command must contain only strings"
+          "MCP server '#{@name}' with stdio transport requires a non-empty command string"
       end
 
       return if @url.nil?
@@ -173,6 +188,17 @@ module AgentHarness
         "MCP server '#{@name}' with #{@transport} transport should not have args (args are only valid for stdio)"
     end
 
+    def normalize_command_and_args(command, args)
+      normalized_args = args || []
+      return [command, normalized_args] unless command.is_a?(Array)
+
+      unless normalized_args.is_a?(Array)
+        return [command.first, normalized_args]
+      end
+
+      [command.first, command[1..] + normalized_args]
+    end
+
     def http_ping_ok?(timeout: 5)
       require "net/http"
       uri = URI.parse(@url)

data/lib/agent_harness/providers/anthropic.rb

@@ -15,6 +15,7 @@ module AgentHarness
     #   response = provider.send_message(prompt: "Hello!")
     class Anthropic < Base
       include RateLimitResetParsing
+      include McpConfigFileSupport
 
       # Model name pattern for Anthropic Claude models
       MODEL_PATTERN = /^claude-[\d.-]+-(?:opus|sonnet|haiku)(?:-\d{8})?$/i
@@ -756,85 +757,8 @@ module AgentHarness
         servers
       end
 
-      def write_mcp_config_file(mcp_servers, working_dir: nil)
-        require "tempfile"
-        require "tmpdir"
-        require "securerandom"
-
-        config = build_claude_mcp_config(mcp_servers)
-        config_json = JSON.generate(config)
-
-        if @executor.is_a?(DockerCommandExecutor)
-          # When running inside a Docker container, write the config file
-          # inside the container so the CLI process can read it.
-          # Track the path so cleanup_mcp_tempfiles! can remove it after execution.
-          container_path = "/tmp/agent_harness_mcp_#{SecureRandom.hex(8)}.json"
-          result = @executor.execute(
-            ["sh", "-c", "cat > #{container_path}"],
-            stdin_data: config_json,
-            timeout: 5
-          )
-          unless result.success?
-            raise McpConfigurationError,
-              "Failed to write MCP config inside container: #{result.stderr}"
-          end
-
-          @mcp_docker_config_paths ||= []
-          @mcp_docker_config_paths << container_path
-
-          container_path
-        else
-          dir = working_dir || Dir.tmpdir
-          file = Tempfile.new(["agent_harness_mcp_", ".json"], dir)
-          file.write(config_json)
-          file.close
-
-          # Hold a reference so the Tempfile is not garbage-collected (and
-          # therefore deleted) before the CLI process reads it.
-          # Cleaned up by cleanup_mcp_tempfiles! after execution.
-          @mcp_config_tempfiles ||= []
-          @mcp_config_tempfiles << file
-
-          file.path
-        end
-      end
-
-      def build_claude_mcp_config(mcp_servers)
-        servers = {}
-        mcp_servers.each do |server|
-          h = if server.stdio?
-            entry = {command: server.command.first}
-            remaining_args = server.command[1..] + server.args
-            entry[:args] = remaining_args unless remaining_args.empty?
-            entry
-          else
-            {url: server.url}
-          end
-          h[:env] = server.env unless server.env.empty?
-          servers[server.name] = h
-        end
-        {mcpServers: servers}
-      end
-
-      def cleanup_mcp_tempfiles!
-        if @mcp_config_tempfiles
-          @mcp_config_tempfiles.each do |file|
-            file.close unless file.closed?
-            file.unlink
-          rescue
-            nil
-          end
-          @mcp_config_tempfiles = nil
-        end
-
-        if @mcp_docker_config_paths
-          @mcp_docker_config_paths.each do |path|
-            @executor.execute(["rm", "-f", path], timeout: 5)
-          rescue
-            nil
-          end
-          @mcp_docker_config_paths = nil
-        end
+      def mcp_provider_key
+        :anthropic
       end
 
       def build_tool_control_flags(tools_option, skip_permission_mode: false)

data/lib/agent_harness/providers/base.rb

@@ -25,6 +25,7 @@ module AgentHarness
     #   end
     class Base
       include Adapter
+      include Extensions::DeepDupable
 
       DEFAULT_SMOKE_TEST_CONTRACT = {
         prompt: "Reply with exactly OK.",
@@ -76,9 +77,11 @@ module AgentHarness
       # @param config [ProviderConfig, nil] provider configuration
       # @param executor [CommandExecutor, nil] command executor
       # @param logger [Logger, nil] logger instance
-      def initialize(config: nil, executor: nil, logger: nil)
+      # @param configuration [Configuration, nil] parent configuration for extension/sub-agent resolution
+      def initialize(config: nil, executor: nil, logger: nil, configuration: nil)
         @config = config || ProviderConfig.new(self.class.provider_name)
-        @executor = executor || AgentHarness.configuration.command_executor
+        @configuration = configuration || AgentHarness.configuration
+        @executor = executor || @configuration.command_executor
         @logger = logger || AgentHarness.logger
       end
 
@@ -126,6 +129,15 @@ module AgentHarness
 
         # Coerce provider_runtime from Hash if needed
         options = normalize_provider_runtime(options)
+
+        # Capture execution options (callbacks, observer) before extensions
+        # processing deep-dups the options hash, which would replace identity-
+        # sensitive references (observers, procs) with clones.
+        exec_opts = command_execution_options(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])
 
@@ -147,7 +159,7 @@ module AgentHarness
           timeout: timeout,
           env: build_env(options),
           preparation: preparation,
-          **command_execution_options(options)
+          **exec_opts
         )
         duration = Time.now - start_time
 
@@ -171,13 +183,15 @@ module AgentHarness
           )
         end
 
+        response = apply_extensions_after_response(extension_context, response)
+
         # Track tokens
         track_tokens(response) if response.tokens
 
         log_debug("send_message_complete", duration: duration, tokens: response.tokens)
 
         response
-      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+      rescue ExtensionCompatibilityError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
         raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
@@ -220,7 +234,12 @@ module AgentHarness
 
         transport = resolve_chat_transport(options)
         messages = format_messages_for_transport(conversation, transport)
+        extension_context = apply_extensions_to_chat(messages, tools, options)
+        messages = extension_context.messages
+        tools = extension_context.tools
+        options = extension_context.options
         messages = apply_sub_agent_to_messages(messages, options[:translated_sub_agent])
+        validate_chat_mcp_servers!(options[:mcp_servers])
         transport_opts = chat_transport_options(runtime, options)
         transport_opts[:on_chat_chunk] = on_chat_chunk if on_chat_chunk
         transport_opts[:observer] = observer if observer
@@ -233,11 +252,13 @@ module AgentHarness
           &on_chunk
         )
 
+        response = apply_extensions_after_response(extension_context, response)
+
         track_tokens(response) if response.tokens
         log_debug("send_chat_message_complete", duration: response.duration, tokens: response.tokens)
 
         response
-      rescue ProviderError, AuthenticationError, RateLimitError, TimeoutError
+      rescue ExtensionCompatibilityError, ProviderError, AuthenticationError, RateLimitError, TimeoutError
         raise
       rescue => e
         last_msg = conversation&.last || messages&.last
@@ -419,7 +440,13 @@ module AgentHarness
       end
 
       def normalize_mcp_servers(options)
-        servers = options[:mcp_servers]
+        if options.key?(:mcp_servers)
+          servers = options[:mcp_servers]
+        else
+          # Configuration stores mcp_servers as a Hash keyed by name; extract values.
+          config_servers = @configuration.mcp_servers
+          servers = config_servers.is_a?(Hash) ? config_servers.values : config_servers
+        end
         return options if servers.nil?
 
         unless servers.is_a?(Array)
@@ -454,12 +481,12 @@ module AgentHarness
         sub_agent = options[:sub_agent]
         return options unless sub_agent
 
-        resolved = AgentHarness.configuration.resolve_sub_agent(sub_agent)
+        resolved = @configuration.resolve_sub_agent(sub_agent)
         translated = SubAgentTranslator.for_provider(
           self.class.provider_name,
           resolved,
-          tool_registry: AgentHarness.configuration.tool_registry,
-          mcp_servers: AgentHarness.configuration.mcp_servers
+          tool_registry: @configuration.tool_registry,
+          mcp_servers: @configuration.mcp_servers
         )
 
         options.merge(sub_agent: resolved, translated_sub_agent: translated)
@@ -477,6 +504,182 @@ module AgentHarness
         [{role: "system", content: translated_sub_agent[:runtime_instructions]}] + messages
       end
 
+      def resolve_extensions(options)
+        Array(options[:extensions]).filter_map do |reference|
+          @configuration.resolve_extension(reference)
+        end
+      end
+
+      def apply_extensions_to_prompt(prompt, options)
+        extensions = resolve_extensions(options)
+        strict = options.fetch(:extensions_strict, true)
+        Extensions::Composition.compose(extensions) if extensions.size > 1
+        context = Extensions::MessageContext.new(
+          provider: self,
+          extensions: extensions,
+          mode: :message,
+          prompt: prompt,
+          options: deep_dup(options),
+          metadata: {}
+        )
+
+        validate_extensions!(extensions, strict: strict)
+        reject_tool_extensions_in_message_mode!(extensions)
+        reject_mcp_extensions_in_message_mode!(extensions)
+        apply_extension_system_prompt!(context)
+        extensions.each { |extension| extension.on_message_before(context) }
+        context
+      end
+
+      def apply_extensions_to_chat(messages, tools, options)
+        extensions = resolve_extensions(options)
+        strict = options.fetch(:extensions_strict, true)
+        Extensions::Composition.compose(extensions) if extensions.size > 1
+        context = Extensions::MessageContext.new(
+          provider: self,
+          extensions: extensions,
+          mode: :chat,
+          messages: deep_dup(messages),
+          tools: merge_extension_tools(tools, extensions),
+          options: deep_dup(options),
+          metadata: {}
+        )
+
+        validate_extensions!(extensions, strict: strict)
+        merge_extension_mcp_servers!(context)
+        apply_extension_system_messages!(context)
+        extensions.each { |extension| extension.on_message_before(context) }
+        extensions.each { |extension| extension.on_tools_available(context) } if context.tools&.any?
+        context
+      end
+
+      def apply_extensions_after_response(context, response)
+        return response unless context
+
+        context.response = response
+        context.extensions.each { |extension| extension.on_message_after(context) }
+        context.response
+      end
+
+      def validate_extensions!(extensions, strict: true)
+        extensions.each do |extension|
+          report = Extensions::Compatibility.check!(provider: self, extension: extension, strict: strict)
+          next if report.fully_supported?
+
+          @logger&.warn(
+            "[AgentHarness::#{self.class.provider_name}] Extension '#{extension.name}' has " \
+            "unsupported features that will be unavailable: #{report.unsupported_features.inspect}"
+          )
+        end
+      end
+
+      def validate_chat_mcp_servers!(mcp_servers)
+        return if mcp_servers.nil? || mcp_servers.empty?
+
+        # Chat transports do not support request-scoped MCP servers.
+        # Raise early so extensions with MCP requirements are not silently ignored.
+        raise McpUnsupportedError.new(
+          "Chat mode does not support request-scoped MCP servers. " \
+          "Extensions or options requiring MCP servers cannot be used with send_chat_message.",
+          provider: self.class.provider_name
+        )
+      end
+
+      def reject_tool_extensions_in_message_mode!(extensions)
+        tool_extensions = extensions.select { |ext| ext.tools.any? }
+        return if tool_extensions.empty?
+
+        names = tool_extensions.map(&:name).join(", ")
+        raise ExtensionCompatibilityError.new(
+          "Extensions with tools are not supported in message mode (CLI execution " \
+          "cannot accept dynamic tool definitions): #{names}",
+          provider: self.class.provider_name
+        )
+      end
+
+      def reject_mcp_extensions_in_message_mode!(extensions)
+        mcp_extensions = extensions.select { |ext| ext.mcp_servers.any? }
+        return if mcp_extensions.empty?
+
+        names = mcp_extensions.map(&:name).join(", ")
+        raise ExtensionCompatibilityError.new(
+          "Extensions with MCP servers are not supported in message mode: #{names}",
+          provider: self.class.provider_name
+        )
+      end
+
+      def merge_extension_mcp_servers!(context)
+        extension_servers = context.extensions.flat_map(&:mcp_servers)
+        return if extension_servers.empty?
+
+        merged = Array(context.options[:mcp_servers]) + extension_servers
+        context.options = context.options.merge(mcp_servers: merged)
+      end
+
+      def merge_extension_tools(tools, extensions)
+        extension_tools = extensions.flat_map(&:tools)
+        return tools unless extension_tools.any?
+
+        normalized_extension_tools = extension_tools.map { |t| normalize_extension_tool_for_provider(t) }
+        merged = Array(tools) + normalized_extension_tools
+        names = merged.map { |t| extract_tool_name(t) }.compact
+        duplicates = names.group_by { |n| n }.select { |_, v| v.size > 1 }.keys
+        unless duplicates.empty?
+          raise ConfigurationError,
+            "Tool name conflict between user-provided and extension tools: #{duplicates.join(", ")}"
+        end
+        merged
+      end
+
+      def extract_tool_name(tool)
+        tool[:name] || tool["name"] ||
+          tool.dig(:function, :name) || tool.dig(:function, "name") ||
+          tool.dig("function", "name") || tool.dig("function", :name)
+      end
+
+      def normalize_extension_tool_for_provider(tool)
+        case chat_transport_type
+        when :openai_compatible
+          # OpenAI-style: {type: "function", function: {name: ..., description: ...}}
+          return tool if tool[:type] == "function" || tool["type"] == "function"
+
+          func = {name: tool[:name] || tool["name"]}
+          description = tool[:description] || tool["description"]
+          func[:description] = description if description
+          parameters = tool[:parameters] || tool["parameters"]
+          func[:parameters] = parameters if parameters
+          {type: "function", function: func}
+        else
+          # Anthropic-style: {name: ..., description: ..., input_schema: ...}
+          # Convert `parameters` key to `input_schema` for Anthropic/TextTransport compatibility.
+          normalized = tool.dup
+          params = normalized.delete(:parameters) || normalized.delete("parameters")
+          if params && !normalized.key?(:input_schema) && !normalized.key?("input_schema")
+            normalized[:input_schema] = params
+          end
+          normalized
+        end
+      end
+
+      def apply_extension_system_prompt!(context)
+        additions = context.extensions.flat_map(&:system_prompt_additions).reject do |addition|
+          addition.nil? || addition.empty?
+        end
+        return if additions.empty?
+
+        context.prompt = [additions.join("\n\n"), context.prompt].join("\n\n")
+      end
+
+      def apply_extension_system_messages!(context)
+        additions = context.extensions.flat_map(&:system_prompt_additions).reject do |addition|
+          addition.nil? || addition.empty?
+        end
+        return if additions.empty?
+
+        system_messages = additions.map { |addition| {role: "system", content: addition} }
+        context.messages = system_messages + context.messages
+      end
+
       def command_execution_options(options)
         execution_options = {
           idle_timeout: options[:idle_timeout],

data/lib/agent_harness/providers/codex.rb

@@ -9,6 +9,7 @@ module AgentHarness
     # Provides integration with the OpenAI Codex CLI tool.
     class Codex < Base
       include RateLimitResetParsing
+      include McpConfigFileSupport
 
       SUPPORTED_CLI_VERSION = "0.116.0"
       SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 0.117.0").freeze
@@ -186,7 +187,7 @@ module AgentHarness
           vision: false,
           tool_use: true,
           json_mode: false,
-          mcp: false,
+          mcp: true,
           dangerous_mode: true
         }
       end
@@ -199,6 +200,27 @@ module AgentHarness
 
       def cli_env_overrides = {"PAID_CODEX_SUBSCRIPTION_AUTH" => "1"}
 
+      def send_message(prompt:, **options)
+        super
+      ensure
+        cleanup_mcp_tempfiles!
+      end
+
+      def supports_mcp?
+        true
+      end
+
+      def supported_mcp_transports
+        %w[stdio http sse]
+      end
+
+      def build_mcp_flags(mcp_servers, working_dir: nil)
+        return [] if mcp_servers.empty?
+
+        config_path = write_mcp_config_file(mcp_servers, working_dir: working_dir)
+        ["--mcp-config", config_path]
+      end
+
       def test_command_overrides
         ["--skip-git-repo-check", "--output-last-message"]
       end
@@ -449,6 +471,11 @@ module AgentHarness
           cmd += sandbox_bypass_flags
         end
 
+        # Add MCP server flags (validated/normalized by Base#send_message)
+        if options[:mcp_servers]&.any?
+          cmd += build_mcp_flags(options[:mcp_servers])
+        end
+
         if options[:session]
           cmd += session_flags(options[:session])
         end
@@ -1259,6 +1286,10 @@ module AgentHarness
         config_dir = ENV["CODEX_CONFIG_DIR"] || File.expand_path("~/.codex")
         File.join(config_dir, "config.json")
       end
+
+      def mcp_provider_key
+        :codex
+      end
     end
   end
 end