agent-harness 0.10.0 → 0.11.1

data/lib/agent_harness/providers/base.rb

@@ -126,6 +126,8 @@ module AgentHarness
 
         # Coerce provider_runtime from Hash if needed
         options = normalize_provider_runtime(options)
+        options = normalize_sub_agent(options)
+        prompt = apply_sub_agent_to_prompt(prompt, options[:translated_sub_agent])
 
         # Normalize and validate MCP servers
         options = normalize_mcp_servers(options)
@@ -181,6 +183,67 @@ module AgentHarness
         handle_error(e, prompt: prompt, options: options)
       end
 
+      # Send a multi-turn chat message via the provider's chat transport.
+      #
+      # Providers that support chat mode can accept either +conversation:+
+      # or +messages:+ as the conversation history payload.
+      #
+      # Structured streaming events are delivered through three channels:
+      # - +on_chat_chunk+ proc (keyword argument)
+      # - +observer+ object responding to +on_chat_chunk+
+      # - block (yield)
+      #
+      # When multiple receivers are provided, all receive every event.
+      #
+      # @param conversation [Array<Hash>, nil] message history
+      # @param messages [Array<Hash>, nil] alias for +conversation+
+      # @param tools [Array<Hash>, nil] tool/function definitions
+      # @param stream [Boolean] whether to stream the response
+      # @param on_chat_chunk [Proc, nil] callback for structured streaming events
+      # @param observer [#on_chat_chunk, nil] observer receiving streaming events
+      # @param options [Hash] additional options
+      # @yield [Hash] streaming chunks when stream: true
+      # @return [Response] the response
+      # @raise [ProviderError] if the provider does not support chat mode
+      def send_chat_message(conversation: nil, messages: nil, tools: nil, stream: false,
+        on_chat_chunk: nil, observer: nil, **options, &on_chunk)
+        unless supports_chat?
+          raise ProviderError, "#{name} does not support chat mode"
+        end
+
+        options = normalize_provider_runtime(options)
+        options = normalize_sub_agent(options)
+        runtime = options[:provider_runtime]
+        conversation ||= messages
+        raise ArgumentError, "conversation or messages is required" unless conversation
+        tools = runtime.chat_tools if tools.nil? && runtime&.chat_tools
+
+        transport = resolve_chat_transport(options)
+        messages = format_messages_for_transport(conversation, transport)
+        messages = apply_sub_agent_to_messages(messages, options[:translated_sub_agent])
+        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
+
+        response = transport.chat(
+          messages: messages,
+          tools: tools,
+          stream: stream,
+          **transport_opts,
+          &on_chunk
+        )
+
+        track_tokens(response) if response.tokens
+        log_debug("send_chat_message_complete", duration: response.duration, tokens: response.tokens)
+
+        response
+      rescue ProviderError, AuthenticationError, RateLimitError, TimeoutError
+        raise
+      rescue => e
+        last_msg = conversation&.last || messages&.last
+        handle_error(e, prompt: (last_msg&.dig(:content) || last_msg&.dig("content")).to_s, options: options)
+      end
+
       # Provider name for display
       #
       # @return [String] display name
@@ -387,6 +450,33 @@ module AgentHarness
         options.merge(mcp_servers: normalized)
       end
 
+      def normalize_sub_agent(options)
+        sub_agent = options[:sub_agent]
+        return options unless sub_agent
+
+        resolved = AgentHarness.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
+        )
+
+        options.merge(sub_agent: resolved, translated_sub_agent: translated)
+      end
+
+      def apply_sub_agent_to_prompt(prompt, translated_sub_agent)
+        return prompt unless translated_sub_agent
+
+        [translated_sub_agent[:runtime_instructions], "User task:\n#{prompt}"].join("\n\n")
+      end
+
+      def apply_sub_agent_to_messages(messages, translated_sub_agent)
+        return messages unless translated_sub_agent
+
+        [{role: "system", content: translated_sub_agent[:runtime_instructions]}] + messages
+      end
+
       def command_execution_options(options)
         execution_options = {
           idle_timeout: options[:idle_timeout],
@@ -466,6 +556,89 @@ module AgentHarness
         end
       end
 
+      def resolve_chat_transport(options)
+        runtime = options[:provider_runtime]
+
+        # When the runtime specifies chat-specific overrides (base_url, api_key),
+        # build a fresh transport instead of reusing the memoized default.
+        if runtime && (runtime.chat_base_url || runtime.chat_api_key)
+          transport = build_runtime_chat_transport(runtime)
+          if transport
+            return transport
+          end
+        end
+
+        transport = chat_transport
+        raise ProviderError, "#{name} chat_transport returned nil" unless transport
+
+        transport
+      end
+
+      # Build a one-off chat transport from ProviderRuntime overrides.
+      #
+      # Subclasses that support chat must override this when the runtime
+      # carries chat_base_url or chat_api_key so those overrides are
+      # actually applied. The base implementation raises to surface the
+      # misconfiguration early rather than silently ignoring the overrides.
+      def build_runtime_chat_transport(_runtime)
+        raise ProviderError,
+          "#{name} does not support chat_base_url/chat_api_key overrides on ProviderRuntime"
+      end
+
+      def format_messages_for_transport(conversation, transport)
+        normalized = conversation.map { |msg| normalize_transport_message(msg) }
+        return normalized unless anthropic_transport?(transport)
+        return normalized unless anthropic_conversion_required?(normalized)
+
+        anthropic = anthropic_conversation(normalized)
+        system_messages = anthropic[:system] ? [{role: "system", content: anthropic[:system]}] : []
+
+        system_messages + anthropic[:messages]
+      end
+
+      def normalize_transport_message(message)
+        message.each_with_object({}) do |(key, value), memo|
+          memo[key.is_a?(String) ? key.to_sym : key] = value
+        end.tap do |normalized|
+          normalized[:role] = normalized[:role].to_s if normalized.key?(:role)
+        end
+      end
+
+      def anthropic_transport?(transport)
+        chat_transport_type == :anthropic || transport.is_a?(TextTransport)
+      end
+
+      def anthropic_conversion_required?(messages)
+        messages.any? do |msg|
+          msg[:role] == "tool" || msg.key?(:tool_calls)
+        end
+      end
+
+      def anthropic_conversation(messages)
+        conversation = Conversation.new
+
+        messages.each do |msg|
+          conversation.add_message(
+            msg.fetch(:role).to_sym,
+            msg[:content],
+            tool_calls: msg[:tool_calls],
+            tool_call_id: msg[:tool_call_id]
+          )
+        end
+
+        conversation.to_anthropic_messages
+      end
+
+      def chat_transport_options(runtime, options)
+        opts = {}
+        max_tok = options[:chat_max_tokens] || options[:max_tokens] || runtime&.chat_max_tokens
+        opts[:max_tokens] = max_tok if max_tok
+        model = runtime&.chat_model || runtime&.model
+        opts[:model] = model if model
+        opts[:temperature] = options[:temperature] if options[:temperature]
+        opts
+      end
+
       def log_debug(action, **context)
         @logger&.debug("[AgentHarness::#{self.class.provider_name}] #{action}: #{context.inspect}")
       end

data/lib/agent_harness/providers/github_copilot.rb

@@ -2,6 +2,7 @@
 
 require "digest"
 require "json"
+require "pathname"
 
 module AgentHarness
   module Providers
@@ -97,6 +98,10 @@ module AgentHarness
           ]
         end
 
+        def supports_chat?
+          true
+        end
+
         def smoke_test_contract
           SMOKE_TEST_CONTRACT
         end
@@ -194,6 +199,40 @@ module AgentHarness
         ["--resume", session_id]
       end
 
+      GITHUB_MODELS_BASE_URL = "https://models.inference.ai.azure.com"
+      CHAT_DEFAULT_MODEL = "gpt-4o"
+      CHAT_MODELS = %w[gpt-4o gpt-4o-mini gpt-4-turbo].freeze
+
+      def supports_chat?
+        true
+      end
+
+      def chat_models
+        CHAT_MODELS
+      end
+
+      def chat_transport
+        @chat_transport ||= OpenAICompatibleTransport.new(
+          base_url: GITHUB_MODELS_BASE_URL,
+          api_key: resolve_chat_api_key,
+          model: CHAT_DEFAULT_MODEL,
+          logger: @logger
+        )
+      end
+
+      def build_runtime_chat_transport(runtime)
+        OpenAICompatibleTransport.new(
+          base_url: runtime.chat_base_url || GITHUB_MODELS_BASE_URL,
+          api_key: runtime.chat_api_key || resolve_chat_api_key,
+          model: runtime.chat_model || runtime.model || CHAT_DEFAULT_MODEL,
+          logger: @logger
+        )
+      end
+
+      def chat_transport_type
+        :openai_compatible
+      end
+
       def auth_type
         :oauth
       end
@@ -801,6 +840,28 @@ module AgentHarness
       def hash_key_present?(value, key)
         value.is_a?(Hash) && value.key?(key)
       end
+
+      def resolve_chat_api_key
+        key = ENV["GITHUB_TOKEN"] || ENV["GH_TOKEN"] || read_copilot_cli_access_token
+
+        if key.nil? || key.strip.empty?
+          raise AuthenticationError.new(
+            "Chat mode requires a GitHub token. Set GITHUB_TOKEN or GH_TOKEN, or authenticate the Copilot CLI.",
+            provider: :github_copilot
+          )
+        end
+
+        key.strip
+      end
+
+      def read_copilot_cli_access_token
+        path = Pathname.new(File.join(Dir.home, ".copilot-cli-access-token"))
+        return nil unless path.file?
+
+        path.read
+      rescue Errno::ENOENT, Errno::EACCES, IOError
+        nil
+      end
     end
   end
 end

data/lib/agent_harness/sub_agent_config.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Canonical provider-agnostic sub-agent definition.
+  class SubAgentConfig
+    attr_reader :name, :description, :instructions, :model, :tools, :mcp_servers
+    attr_reader :constraints, :handoff_conditions, :type, :sub_agents, :routing
+
+    def initialize(name:, description:, instructions:, model: "default", tools: [],
+      mcp_servers: [], constraints: {}, handoff_conditions: [], type: nil,
+      sub_agents: [], routing: nil)
+      @name = normalize_name(name)
+      @description = validate_string!(:description, description)
+      @instructions = validate_string!(:instructions, instructions)
+      @model = normalize_model(model)
+      @tools = normalize_array(:tools, tools)
+      @mcp_servers = normalize_array(:mcp_servers, mcp_servers)
+      @constraints = normalize_hash(:constraints, constraints)
+      @handoff_conditions = normalize_array(:handoff_conditions, handoff_conditions)
+      @type = type&.to_sym
+      @sub_agents = normalize_array(:sub_agents, sub_agents)
+      @routing = routing.nil? ? nil : normalize_hash(:routing, routing)
+    end
+
+    def self.from_hash(hash)
+      unless hash.is_a?(Hash)
+        raise ConfigurationError, "Sub-agent definition must be a Hash, got #{hash.class}"
+      end
+
+      attrs = hash.each_with_object({}) do |(key, value), memo|
+        memo[key.to_sym] = value
+      end
+
+      %i[name description instructions].each do |field|
+        value = attrs[field]
+        next if value.is_a?(String) && !value.strip.empty?
+        next if value.is_a?(Symbol)
+
+        raise ConfigurationError, "#{field} is required"
+      end
+
+      new(**attrs)
+    end
+
+    def to_h
+      {
+        name: @name,
+        description: @description,
+        instructions: @instructions,
+        model: @model,
+        tools: deep_dup(@tools),
+        mcp_servers: deep_dup(@mcp_servers),
+        constraints: deep_dup(@constraints),
+        handoff_conditions: deep_dup(@handoff_conditions),
+        type: @type,
+        sub_agents: deep_dup(@sub_agents),
+        routing: deep_dup(@routing)
+      }.compact
+    end
+
+    private
+
+    def normalize_name(name)
+      value = validate_string!(:name, name)
+      value.tr(" ", "_").to_sym
+    end
+
+    def normalize_model(model)
+      return "default" if model.nil?
+
+      validate_string!(:model, model)
+    end
+
+    def validate_string!(field, value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ConfigurationError, "#{field} must be a String or Symbol"
+      end
+
+      string = value.to_s.strip
+      raise ConfigurationError, "#{field} is required" if string.empty?
+
+      string
+    end
+
+    def normalize_array(field, value)
+      return [].freeze if value.nil?
+
+      unless value.is_a?(Array)
+        raise ConfigurationError, "#{field} must be an Array"
+      end
+
+      deep_dup(value).freeze
+    end
+
+    def normalize_hash(field, value)
+      return {}.freeze if value.nil?
+
+      unless value.is_a?(Hash)
+        raise ConfigurationError, "#{field} must be a Hash"
+      end
+
+      deep_dup(value).freeze
+    end
+
+    def deep_dup(value)
+      case value
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when Hash
+        value.each_with_object({}) { |(key, entry), copy| copy[key] = deep_dup(entry) }
+      else
+        value.dup
+      end
+    rescue TypeError
+      value
+    end
+  end
+end

data/lib/agent_harness/sub_agent_file_loader.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module AgentHarness
+  # Loads canonical sub-agent definitions from YAML or Markdown files.
+  class SubAgentFileLoader
+    class << self
+      def load(path)
+        case File.extname(path).downcase
+        when ".yml", ".yaml"
+          load_yaml(path)
+        when ".md", ".markdown"
+          [load_markdown(path)]
+        else
+          raise ConfigurationError, "Unsupported sub-agent definition format: #{path}"
+        end
+      end
+
+      private
+
+      def load_yaml(path)
+        parsed = YAML.safe_load_file(path, permitted_classes: [], aliases: false)
+        unless parsed.is_a?(Hash)
+          raise ConfigurationError, "YAML sub-agent definition must be a Hash"
+        end
+
+        agents = parsed["agents"] || parsed[:agents] || [parsed]
+        unless agents.is_a?(Array)
+          raise ConfigurationError, "YAML sub-agent definitions must provide an agents Array"
+        end
+
+        agents.map { |entry| SubAgentConfig.from_hash(entry) }
+      rescue Psych::SyntaxError => e
+        raise ConfigurationError, "Invalid YAML in #{path}: #{e.message}"
+      end
+
+      def load_markdown(path)
+        content = File.read(path)
+        match = content.match(/\A---\s*\n(?<frontmatter>.*?)\n---\s*\n?(?<body>.*)\z/m)
+        raise ConfigurationError, "Markdown sub-agent definitions require YAML frontmatter" unless match
+
+        attrs = YAML.safe_load(match[:frontmatter], permitted_classes: [], aliases: false) || {}
+        unless attrs.is_a?(Hash)
+          raise ConfigurationError, "Markdown frontmatter must be a Hash"
+        end
+
+        attrs["instructions"] ||= match[:body].strip
+        SubAgentConfig.from_hash(attrs)
+      rescue Psych::SyntaxError => e
+        raise ConfigurationError, "Invalid frontmatter in #{path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/agent_harness/sub_agent_translator.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module AgentHarness
+  # Translates canonical sub-agent definitions into provider-specific formats.
+  module SubAgentTranslator
+    class << self
+      def for_provider(provider, sub_agent_config, tool_registry: AgentHarness.configuration.tool_registry,
+        mcp_servers: AgentHarness.configuration.mcp_servers)
+        config = normalize_sub_agent_config(sub_agent_config)
+        normalized_provider = normalize_provider(provider)
+        tools = resolve_tools(config.tools, provider: normalized_provider, tool_registry: tool_registry)
+        servers = resolve_mcp_servers(config.mcp_servers, mcp_servers: mcp_servers)
+
+        case normalized_provider
+        when :anthropic
+          translate_for_anthropic(config, tools: tools, mcp_servers: servers)
+        when :openai
+          translate_for_openai(config, tools: tools, mcp_servers: servers)
+        when :google
+          translate_for_google(config, tools: tools, mcp_servers: servers)
+        when :claude_code
+          translate_for_claude_code(config, tools: tools, mcp_servers: servers)
+        when :codex
+          translate_for_codex(config, tools: tools, mcp_servers: servers)
+        when :pi
+          translate_for_pi(config, tools: tools, mcp_servers: servers)
+        else
+          translate_generic(normalized_provider, config, tools: tools, mcp_servers: servers)
+        end
+      end
+
+      private
+
+      def normalize_sub_agent_config(sub_agent_config)
+        case sub_agent_config
+        when SubAgentConfig
+          sub_agent_config
+        when Hash
+          SubAgentConfig.from_hash(sub_agent_config)
+        else
+          raise ConfigurationError, "Sub-agent config must be a SubAgentConfig or Hash"
+        end
+      end
+
+      def normalize_provider(provider)
+        case provider.to_sym
+        when :claude then :anthropic
+        when :gemini then :google
+        else provider.to_sym
+        end
+      end
+
+      def resolve_tools(tool_refs, provider:, tool_registry:)
+        tool_refs.map do |tool|
+          case tool
+          when Symbol, String
+            mapping = tool_registry.fetch(tool).mapping_for(provider)
+            mapping.nil? ? tool.to_s : mapping
+          when Hash
+            deep_dup(tool)
+          else
+            raise ConfigurationError, "Unsupported tool reference #{tool.inspect} in sub-agent definition"
+          end
+        end
+      end
+
+      def resolve_mcp_servers(server_refs, mcp_servers:)
+        server_refs.map do |server|
+          resolved = case server
+          when McpServer
+            server
+          when Symbol, String
+            mcp_servers.fetch(server.to_sym) do
+              raise ConfigurationError, "Unknown MCP server: #{server}"
+            end
+          when Hash
+            McpServer.from_hash(server)
+          else
+            raise ConfigurationError, "Unsupported MCP server reference #{server.inspect} in sub-agent definition"
+          end
+
+          resolved.to_h
+        end
+      end
+
+      def translate_for_anthropic(config, tools:, mcp_servers:)
+        {
+          provider: :anthropic,
+          format: :agent_sdk,
+          agent: {
+            name: config.name.to_s,
+            description: config.description,
+            instructions: config.instructions,
+            model: config.model,
+            tools: tools,
+            mcp_servers: mcp_servers,
+            constraints: deep_dup(config.constraints)
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_openai(config, tools:, mcp_servers:)
+        {
+          provider: :openai,
+          format: :responses,
+          assistant: {
+            name: config.name.to_s,
+            description: config.description,
+            instructions: config.instructions,
+            model: config.model,
+            tools: tools,
+            metadata: {
+              mcp_servers: mcp_servers,
+              constraints: deep_dup(config.constraints)
+            }
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_google(config, tools:, mcp_servers:)
+        {
+          provider: :google,
+          format: :adk,
+          agent: {
+            name: config.name.to_s,
+            description: config.description,
+            instruction: config.instructions,
+            model: config.model,
+            tools: tools,
+            mcp_servers: mcp_servers,
+            constraints: deep_dup(config.constraints)
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_claude_code(config, tools:, mcp_servers:)
+        frontmatter = {
+          "name" => config.name.to_s,
+          "description" => config.description,
+          "model" => config.model,
+          "tools" => tools,
+          "mcp_servers" => mcp_servers,
+          "constraints" => deep_dup(config.constraints)
+        }.delete_if { |_key, value| value.respond_to?(:empty?) ? value.empty? : value.nil? }
+
+        {
+          provider: :claude_code,
+          format: :markdown,
+          content: build_markdown_definition(frontmatter, config.instructions),
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_codex(config, tools:, mcp_servers:)
+        {
+          provider: :codex,
+          format: :delegated_prompt,
+          definition: {
+            name: config.name.to_s,
+            description: config.description,
+            instructions: config.instructions,
+            model: config.model,
+            tools: tools,
+            mcp_servers: mcp_servers,
+            constraints: deep_dup(config.constraints)
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_pi(config, tools:, mcp_servers:)
+        frontmatter = {
+          "name" => config.name.to_s,
+          "description" => config.description,
+          "model" => config.model,
+          "tools" => tools,
+          "mcp_servers" => mcp_servers
+        }.delete_if { |_key, value| value.respond_to?(:empty?) ? value.empty? : value.nil? }
+
+        {
+          provider: :pi,
+          format: :skill_markdown,
+          content: build_markdown_definition(frontmatter, config.instructions),
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_generic(provider, config, tools:, mcp_servers:)
+        {
+          provider: provider,
+          format: :generic,
+          definition: {
+            name: config.name.to_s,
+            description: config.description,
+            instructions: config.instructions,
+            model: config.model,
+            tools: tools,
+            mcp_servers: mcp_servers,
+            constraints: deep_dup(config.constraints)
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def runtime_instructions(config)
+        <<~TEXT.strip
+          Sub-agent role: #{config.name}
+          Description: #{config.description}
+
+          Follow these sub-agent instructions exactly:
+          #{config.instructions}
+        TEXT
+      end
+
+      def build_markdown_definition(frontmatter, instructions)
+        <<~MARKDOWN
+          ---
+          #{YAML.dump(frontmatter).sub(/\A---\s*\n/, "").strip}
+          ---
+          #{instructions}
+        MARKDOWN
+      end
+
+      def deep_dup(value)
+        case value
+        when Array
+          value.map { |entry| deep_dup(entry) }
+        when Hash
+          value.each_with_object({}) { |(key, entry), copy| copy[key] = deep_dup(entry) }
+        else
+          value.dup
+        end
+      rescue TypeError
+        value
+      end
+    end
+  end
+end