agent-harness 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8162991fcf80a1cfe21b522abe909f615e87e56942b8261f5ee3cbb9a86f18c2
-  data.tar.gz: 22f7b57522dc3f38dd73a5200cbf878ca72d0b22d889c29bfa58ca878725a705
+  metadata.gz: 635aae919a5bbbf99af4a24199b45507370c01ccbf637bfd8d9d0fa18bdb3c22
+  data.tar.gz: 30548d834ae0195030e98565007ced6ebf140f12f9a489ae10a6d423c40e087f
 SHA512:
-  metadata.gz: 1a9f60dc02f229765786bfe38c5cc84f489f52efb8d146f1a0595f9bc03d930b6e71f2194cfb4c86d24e191e1c5d184e7030addda5f1ab09a4a9098ff3a90a7f
-  data.tar.gz: 7b4a8d87ceb151d28d867522afe69872f5a983df961b7c2a1dcccf07324c1ca8c6cc2e7ed1eb7b4dd129d7315917084a0e0da7d29c2ad4e032b6be29eda71fa2
+  metadata.gz: ac200425094b482ad90fd6492ba0bf4d612ed08560bacde517c988375d1d452b12aca7c34f8ed9519cf907daa87a07a96a4c044952126ce3cd9e37f2d6b9a788
+  data.tar.gz: a871de9fcc11224506f4220025016b3b7201ef97bc1e1aca918562c1f983b9dd175a93dbd6315a71a3a270234d3b9cd019f7deaa82030b984e11434ca86328f8

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.9.0"
+  ".": "0.11.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [0.11.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.10.0...agent-harness/v0.11.0) (2026-04-25)
+
+
+### Features
+
+* add conversation manager for multi-turn chat ([#159](https://github.com/viamin/agent-harness/issues/159)) ([14f1d55](https://github.com/viamin/agent-harness/commit/14f1d551008c2d52a0aee7c2a7e2e0273f254578))
+* add MCP HTTP transport support for servers ([#153](https://github.com/viamin/agent-harness/issues/153)) ([#155](https://github.com/viamin/agent-harness/issues/155)) ([8ea631a](https://github.com/viamin/agent-harness/commit/8ea631a3274ca4331ce42e8d63fc972cd48fbb12))
+* add OpenAI-compatible chat transport ([#154](https://github.com/viamin/agent-harness/issues/154)) ([6005702](https://github.com/viamin/agent-harness/commit/60057029ba6eaaf81f65d42e487e6f0ca8cd159f))
+* add provider chat capability with GitHub Models and Anthropic support ([#158](https://github.com/viamin/agent-harness/issues/158)) ([4188fa5](https://github.com/viamin/agent-harness/commit/4188fa542e6c4d330e5b230e54b1c1a5a55f4e8a))
+* add structured streaming response observer for chat ([#157](https://github.com/viamin/agent-harness/issues/157)) ([225f4d9](https://github.com/viamin/agent-harness/commit/225f4d99b2b89d8eb030018236050672d3e47ba2))
+
+## [0.10.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.9.0...agent-harness/v0.10.0) (2026-04-21)
+
+
+### Features
+
+* **codex:** expose JSONL transcript parser ([#148](https://github.com/viamin/agent-harness/issues/148)) ([05312ea](https://github.com/viamin/agent-harness/commit/05312eaf9c11fff50931e511ee6e534838eb8746))
+
+
+### Bug Fixes
+
+* **copilot:** github-copilot-cli does not support the -p flag used by build_command ([#141](https://github.com/viamin/agent-harness/issues/141)) ([d06fbc4](https://github.com/viamin/agent-harness/commit/d06fbc414489d6c3bc93a122d0eb2a5771ddbb26))
+
 ## [0.9.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.8.0...agent-harness/v0.9.0) (2026-04-19)
 
 

data/README.md

@@ -501,6 +501,29 @@ AgentHarness.auth_status(:claude)
 
 For providers without a built-in auth check (including `:api_key` providers), `auth_valid?` returns `false` and `auth_status` returns an error indicating the check is not implemented. Custom providers can implement an `auth_status` instance method to provide their own check.
 
+### Auth Flow Capabilities
+
+Before rendering provider-specific auth controls, check whether the flow is supported:
+
+```ruby
+AgentHarness.auth_url_supported?(:claude)
+# => true
+
+AgentHarness.auth_url_supported?(:codex)
+# => false
+
+AgentHarness.refresh_auth_supported?(:claude)
+# => true
+
+AgentHarness.refresh_auth_supported?(:codex)
+# => false
+
+AgentHarness.auth_capabilities(:codex)
+# => { auth_type: :api_key, auth_url: false, refresh: false }
+```
+
+Provider aliases are resolved the same way as other auth APIs, so `:anthropic` reports the same capabilities as `:claude`. Unknown providers raise `AgentHarness::ProviderNotFoundError`, matching `auth_url` and `refresh_auth` provider lookup behavior.
+
 ### Auth Error Detection
 
 When a CLI agent fails due to expired or invalid authentication, `send_message` raises `AuthenticationError` with the provider name. Authentication errors are always surfaced directly to the caller (never auto-switched to another provider) so your application can trigger the appropriate re-auth flow:
@@ -509,9 +532,15 @@ When a CLI agent fails due to expired or invalid authentication, `send_message`
 begin
   AgentHarness.send_message("Hello", provider: :claude)
 rescue AgentHarness::AuthenticationError => e
-  puts e.provider  # => :claude
-  puts e.message   # => "oauth token expired"
-  # Trigger re-authentication flow for the specific provider
+  provider = e.provider
+
+  if AgentHarness.auth_url_supported?(provider)
+    redirect_to AgentHarness.auth_url(provider)
+  elsif AgentHarness.refresh_auth_supported?(provider)
+    render :reauth_token_form, locals: { provider: provider }
+  else
+    render :auth_expired_without_refresh, locals: { provider: provider, message: e.message }
+  end
 end
 ```
 
@@ -524,7 +553,7 @@ AgentHarness.auth_url(:claude)
 # => "https://claude.ai/oauth/authorize"
 ```
 
-This raises `NotImplementedError` for `:api_key` providers.
+This raises `AgentHarness::UnsupportedAuthFlowError` for `:api_key` providers or providers whose OAuth URL flow is not implemented. The exception inherits from `AgentHarness::Error` and `StandardError`, so host applications can rescue it with their normal app-level error handling.
 
 ### Credential Refresh
 
@@ -537,7 +566,9 @@ AgentHarness.refresh_auth(:claude, token: "new-oauth-token")
 
 Any existing expiry metadata in the credentials file is cleared on refresh so that `auth_valid?` returns `true` immediately after a successful refresh.
 
-This raises `NotImplementedError` for `:api_key` providers. Credential file paths respect the `CLAUDE_CONFIG_DIR` environment variable.
+This raises `AgentHarness::UnsupportedAuthFlowError` for `:api_key` providers or providers whose credential refresh flow is not implemented. Credential file paths respect the `CLAUDE_CONFIG_DIR` environment variable.
+
+If you currently rescue `NotImplementedError` for unsupported auth URL generation or credential refresh, update that code to rescue `AgentHarness::UnsupportedAuthFlowError` or the broader `AgentHarness::Error` instead.
 
 ## Provider Health Checks
 

data/lib/agent_harness/authentication.rb

@@ -35,19 +35,46 @@ module AgentHarness
         end
       end
 
+      # Get authentication flow capabilities for a provider.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [Hash] capabilities with :auth_type, :auth_url, :refresh keys
+      # @raise [ProviderNotFoundError] if provider is unknown
+      def auth_capabilities(provider_name)
+        provider_name = provider_name.to_sym
+        provider = resolve_provider(provider_name)
+        canonical_name = Providers::Registry.instance.canonical_name(provider_name)
+        flow_supported = claude_oauth_flow_provider?(provider_name, canonical_name)
+
+        {
+          auth_type: provider.auth_type,
+          auth_url: flow_supported,
+          refresh: flow_supported
+        }
+      end
+
+      # Check whether OAuth URL generation is supported for a provider.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [Boolean] true if auth_url can be called for the provider
+      # @raise [ProviderNotFoundError] if provider is unknown
+      def auth_url_supported?(provider_name)
+        auth_capabilities(provider_name)[:auth_url]
+      end
+
       # Generate an OAuth URL for a provider
       #
       # Only supported for :oauth auth type providers.
       #
       # @param provider_name [Symbol] the provider name
       # @return [String] the OAuth authorization URL
-      # @raise [NotImplementedError] if provider doesn't support OAuth
+      # @raise [UnsupportedAuthFlowError] if provider doesn't support OAuth
       def auth_url(provider_name)
         provider_name = provider_name.to_sym
         provider = resolve_provider(provider_name)
 
         unless provider.auth_type == :oauth
-          raise NotImplementedError,
+          raise UnsupportedAuthFlowError,
             "Provider #{provider_name} uses #{provider.auth_type} auth and does not support OAuth URL generation"
         end
 
@@ -55,29 +82,38 @@ module AgentHarness
         when :claude, :anthropic
           claude_auth_url
         else
-          raise NotImplementedError,
+          raise UnsupportedAuthFlowError,
             "OAuth URL generation is not yet implemented for provider #{provider_name}"
         end
       end
 
+      # Check whether credential refresh is supported for a provider.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [Boolean] true if refresh_auth can be called for the provider
+      # @raise [ProviderNotFoundError] if provider is unknown
+      def refresh_auth_supported?(provider_name)
+        auth_capabilities(provider_name)[:refresh]
+      end
+
       # Refresh authentication credentials for a provider
       #
       # For OAuth providers, stores a pre-exchanged token directly.
       # This method accepts a token (not an authorization code) because
       # the OAuth code-exchange flow is provider-specific and should be
       # handled by the caller or a CLI login command before calling this.
-      # For API key providers, raises NotImplementedError.
+      # For API key providers, raises UnsupportedAuthFlowError.
       #
       # @param provider_name [Symbol] the provider name
       # @param token [String] OAuth token to store (must be non-blank)
       # @return [Hash] result with :success key
-      # @raise [NotImplementedError] if provider doesn't support credential refresh
+      # @raise [UnsupportedAuthFlowError] if provider doesn't support credential refresh
       def refresh_auth(provider_name, token: nil)
         provider_name = provider_name.to_sym
         provider = resolve_provider(provider_name)
 
         unless provider.auth_type == :oauth
-          raise NotImplementedError,
+          raise UnsupportedAuthFlowError,
             "Provider #{provider_name} uses #{provider.auth_type} auth and does not support credential refresh"
         end
 
@@ -85,13 +121,17 @@ module AgentHarness
         when :claude, :anthropic
           refresh_claude_auth(token: token)
         else
-          raise NotImplementedError,
+          raise UnsupportedAuthFlowError,
             "Credential refresh is not yet implemented for provider #{provider_name}"
         end
       end
 
       private
 
+      def claude_oauth_flow_provider?(requested_name, canonical_name)
+        [:claude, :anthropic].include?(requested_name) || canonical_name == :claude
+      end
+
       def resolve_provider(provider_name)
         klass = Providers::Registry.instance.get(provider_name)
         canonical_name = Providers::Registry.instance.canonical_name(provider_name)

data/lib/agent_harness/conversation.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AgentHarness
+  # Manages multi-turn conversation history with token tracking and
+  # transport-specific message formatting.
+  #
+  # Encapsulates message storage, token budget awareness, context window
+  # truncation, and serialisation to OpenAI and Anthropic API formats.
+  #
+  # @example Basic usage
+  #   convo = AgentHarness::Conversation.new(system_prompt: "You are helpful.")
+  #   convo.add_message(:user, "Hello")
+  #   convo.add_message(:assistant, "Hi there!", tokens: { input: 10, output: 5 })
+  #   convo.to_openai_messages
+  #
+  # @example Token-aware truncation
+  #   convo = AgentHarness::Conversation.new(system_prompt: "...", token_limit: 8000)
+  #   # ... add many messages ...
+  #   convo.truncate(keep_recent: 4) if convo.approaching_limit?
+  class Conversation
+    VALID_ROLES = %i[system user assistant tool].freeze
+
+    # @return [Integer, nil] the token budget for this conversation
+    attr_reader :token_limit
+
+    # @param system_prompt [String, nil] optional system prompt prepended to messages
+    # @param token_limit [Integer, nil] optional context-window token budget
+    def initialize(system_prompt: nil, token_limit: nil)
+      @messages = []
+      @token_limit = token_limit
+
+      if system_prompt
+        add_message(:system, system_prompt)
+      end
+    end
+
+    # Append a message to the conversation.
+    #
+    # @param role [Symbol] one of :system, :user, :assistant, :tool
+    # @param content [String, nil] message text
+    # @param metadata [Hash] optional fields — :tool_calls, :tool_call_id,
+    #   :tool_name, :tool_arguments, :tool_result, :model, :tokens
+    # @return [Hash] the message that was added
+    # @raise [ArgumentError] if role is invalid
+    def add_message(role, content = nil, **metadata)
+      role = role.to_sym
+      unless VALID_ROLES.include?(role)
+        raise ArgumentError, "Invalid role: #{role}. Must be one of #{VALID_ROLES.join(", ")}"
+      end
+      if role == :system && !@messages.empty?
+        raise ArgumentError, "System messages are only allowed as the first message"
+      end
+
+      message = {
+        role: role,
+        content: content,
+        created_at: Time.now
+      }
+
+      message[:tool_calls] = metadata[:tool_calls] if metadata[:tool_calls]
+      message[:tool_call_id] = metadata[:tool_call_id] if metadata[:tool_call_id]
+      message[:tool_name] = metadata[:tool_name] if metadata[:tool_name]
+      message[:tool_arguments] = metadata[:tool_arguments] if metadata[:tool_arguments]
+      message[:tool_result] = metadata[:tool_result] if metadata[:tool_result]
+      message[:model] = metadata[:model] if metadata[:model]
+      message[:tokens] = metadata[:tokens] if metadata[:tokens]
+
+      @messages << message
+      deep_copy(message)
+    end
+
+    # Returns the full message history.
+    #
+    # @return [Array<Hash>] all messages in chronological order
+    def messages
+      deep_copy(@messages)
+    end
+
+    # @return [Integer] the number of messages in the conversation
+    def message_count
+      @messages.size
+    end
+
+    # Sum of all tracked tokens (input + output) across messages.
+    #
+    # @return [Integer] total tokens consumed
+    def token_count
+      @messages.sum do |msg|
+        tokens = msg[:tokens]
+        next 0 unless tokens
+
+        (tokens[:input] || 0) + (tokens[:output] || 0)
+      end
+    end
+
+    # Tokens remaining before hitting the limit.
+    #
+    # @return [Integer, nil] remaining tokens, or nil when no limit is set
+    def token_remaining
+      return nil unless @token_limit
+
+      @token_limit - token_count
+    end
+
+    # Whether token usage has reached or exceeded the given threshold of the limit.
+    #
+    # @param threshold [Float] fraction of token_limit (0.0–1.0) at which to warn
+    # @return [Boolean] true when usage >= threshold * limit; false when no limit set
+    def approaching_limit?(threshold: 0.8)
+      return false unless @token_limit
+
+      token_count >= (threshold * @token_limit)
+    end
+
+    # Remove oldest non-system messages to free context window.
+    #
+    # keep_recent counts conversational turns, not individual messages. A turn is
+    # anchored by a user message and includes any following assistant/tool
+    # messages up to the next user message.
+    #
+    # @param keep_recent [Integer, nil] minimum number of recent turns to preserve
+    # @param keep_system_prompt [Boolean] whether to preserve the system prompt
+    # @return [Integer] number of messages removed
+    def truncate(keep_recent: nil, keep_system_prompt: true)
+      original_size = @messages.size
+      system_message = initial_system_message
+      system_messages = (keep_system_prompt && system_message) ? [system_message] : []
+      non_system = system_message ? @messages.drop(1) : @messages
+
+      kept = if keep_recent
+        recent_turns(non_system, keep_recent).flatten
+      else
+        non_system
+      end
+
+      @messages = system_messages + kept
+      original_size - @messages.size
+    end
+
+    # Format messages for OpenAI-compatible chat completions APIs.
+    #
+    # @return [Array<Hash>] messages with string roles and content
+    def to_openai_messages
+      @messages.map { |msg| openai_format(msg) }
+    end
+
+    # Format messages for the Anthropic Messages API.
+    #
+    # The system prompt is returned separately; tool results are wrapped as
+    # content blocks inside user messages per Anthropic's schema.
+    #
+    # @return [Hash] :system [String, nil] and :messages [Array<Hash>]
+    def to_anthropic_messages
+      system_prompt = initial_system_message&.dig(:content)
+      result_messages = []
+
+      start_index = system_prompt ? 1 : 0
+      @messages.drop(start_index).each do |msg|
+        case msg[:role]
+        when :user
+          result_messages << {
+            role: "user",
+            content: [{type: "text", text: msg[:content]}]
+          }
+        when :assistant
+          content_blocks = []
+          content_blocks << {type: "text", text: msg[:content]} if msg[:content]
+
+          msg[:tool_calls]&.each do |tc|
+            arguments = tool_call_arguments(tc)
+            parsed_arguments = if arguments.is_a?(String)
+              begin
+                JSON.parse(arguments)
+              rescue JSON::ParserError
+                arguments
+              end
+            else
+              arguments
+            end
+
+            content_blocks << {
+              type: "tool_use",
+              id: tool_call_value(tc, :id),
+              name: tool_call_name(tc),
+              input: parsed_arguments
+            }
+          end
+
+          result_messages << {role: "assistant", content: content_blocks}
+        when :tool
+          tool_result_block = {
+            type: "tool_result",
+            tool_use_id: msg[:tool_call_id],
+            content: msg[:content]
+          }
+          prev = result_messages.last
+          if prev && prev[:role] == "user" && prev[:content]&.first&.dig(:type) == "tool_result"
+            prev[:content] << tool_result_block
+          else
+            result_messages << {
+              role: "user",
+              content: [tool_result_block]
+            }
+          end
+        end
+      end
+
+      {system: system_prompt, messages: result_messages}
+    end
+
+    # Returns the most recent assistant message, or nil.
+    #
+    # @return [Hash, nil]
+    def last_assistant_message
+      @messages.reverse_each do |msg|
+        return deep_copy(msg) if msg[:role] == :assistant
+      end
+      nil
+    end
+
+    # Remove all messages except the system prompt.
+    #
+    # @return [void]
+    def clear!
+      system_message = initial_system_message
+      @messages = system_message ? [system_message] : []
+    end
+
+    private
+
+    def initial_system_message
+      @messages.first if @messages.first&.dig(:role) == :system
+    end
+
+    def recent_turns(non_system_messages, keep_recent)
+      turns = non_system_messages.each_with_object([]) do |msg, grouped_turns|
+        if msg[:role] == :user || grouped_turns.empty?
+          grouped_turns << [msg]
+        else
+          grouped_turns.last << msg
+        end
+      end
+
+      (keep_recent < turns.size) ? turns.last(keep_recent) : turns
+    end
+
+    def openai_format(msg)
+      case msg[:role]
+      when :tool
+        {
+          role: "tool",
+          content: msg[:content],
+          tool_call_id: msg[:tool_call_id]
+        }
+      when :assistant
+        formatted = {role: "assistant", content: msg[:content]}
+        if msg[:tool_calls]
+          formatted[:tool_calls] = msg[:tool_calls].map do |tc|
+            {
+              id: tool_call_value(tc, :id),
+              type: "function",
+              function: {
+                name: tool_call_name(tc),
+                arguments: serialize_tool_call_arguments(tc)
+              }
+            }
+          end
+        end
+        formatted
+      else
+        {role: msg[:role].to_s, content: msg[:content]}
+      end
+    end
+
+    def deep_copy(value)
+      case value
+      when Array
+        value.map { |item| deep_copy(item) }
+      when Hash
+        value.each_with_object({}) do |(key, nested_value), copy|
+          copy[key] = deep_copy(nested_value)
+        end
+      else
+        begin
+          value.dup
+        rescue TypeError
+          value
+        end
+      end
+    end
+
+    def serialize_tool_call_arguments(tool_call)
+      arguments = tool_call_arguments(tool_call)
+      arguments.is_a?(Hash) ? JSON.generate(arguments) : arguments
+    end
+
+    def tool_call_name(tool_call)
+      tool_call_value(tool_call, :name) || nested_tool_call_value(tool_call, :function, :name)
+    end
+
+    def tool_call_arguments(tool_call)
+      tool_call_value(tool_call, :arguments) || nested_tool_call_value(tool_call, :function, :arguments)
+    end
+
+    def nested_tool_call_value(tool_call, *keys)
+      value = tool_call
+      keys.each do |key|
+        value = hash_value(value, key)
+        return nil if value.nil?
+      end
+      value
+    end
+
+    def tool_call_value(tool_call, key)
+      hash_value(tool_call, key)
+    end
+
+    def hash_value(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash[key] || hash[key.to_s]
+    end
+  end
+end

data/lib/agent_harness/errors.rb

@@ -66,6 +66,9 @@ module AgentHarness
   # subscription to API-metered usage.
   class AuthMismatchError < AuthenticationError; end
 
+  # Raised when a provider does not support the requested authentication flow.
+  class UnsupportedAuthFlowError < Error; end
+
   # Configuration errors
   class ConfigurationError < Error; end
 

data/lib/agent_harness/mcp_server.rb

@@ -75,6 +75,25 @@ module AgentHarness
       %w[http sse].include?(@transport)
     end
 
+    # Check if the MCP server is reachable based on its transport type.
+    #
+    # For stdio servers, checks that a command is present.
+    # For HTTP/SSE servers, checks that a URL is present and the server
+    # responds to an HTTP HEAD request.
+    #
+    # @param timeout [Integer] HTTP request timeout in seconds (default: 5)
+    # @return [Boolean]
+    def reachable?(timeout: 5)
+      case transport
+      when "stdio"
+        !command.nil? && !command.empty?
+      when "http", "sse"
+        !url.nil? && !url.to_s.strip.empty? && http_ping_ok?(timeout: timeout)
+      else
+        false
+      end
+    end
+
     def to_h
       h = {name: @name, transport: @transport}
       if stdio?
@@ -153,5 +172,18 @@ module AgentHarness
       raise McpConfigurationError,
         "MCP server '#{@name}' with #{@transport} transport should not have args (args are only valid for stdio)"
     end
+
+    def http_ping_ok?(timeout: 5)
+      require "net/http"
+      uri = URI.parse(@url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      response = http.head(uri.request_uri)
+      response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPRedirection)
+    rescue
+      false
+    end
   end
 end