agent-harness 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3549cf974343fcdb961dea202dc22b84f820671a29f9139f1e36bb9c8a6363d4
-  data.tar.gz: a35417365aba964248a50cc44d543fd6e11e18a7c27946d7f7750cdfa6347cf0
+  metadata.gz: 635aae919a5bbbf99af4a24199b45507370c01ccbf637bfd8d9d0fa18bdb3c22
+  data.tar.gz: 30548d834ae0195030e98565007ced6ebf140f12f9a489ae10a6d423c40e087f
 SHA512:
-  metadata.gz: beb28e93b4f37ad2328f70fa4ec0e88677e0b2bf0bff2c2826fb3086aab4b9c0714692f8b17268ec3ecb58815f19021880237c6fff59821d73942cb18b008e5f
-  data.tar.gz: d12b1399447b77bf9b570b6791b7426d92e52d691b094f27329a118f1e1ba472daf794a27bc2150a0d8b9a47d825f668dc875f128ac2986e44236792c6d07d10
+  metadata.gz: ac200425094b482ad90fd6492ba0bf4d612ed08560bacde517c988375d1d452b12aca7c34f8ed9519cf907daa87a07a96a4c044952126ce3cd9e37f2d6b9a788
+  data.tar.gz: a871de9fcc11224506f4220025016b3b7201ef97bc1e1aca918562c1f983b9dd175a93dbd6315a71a3a270234d3b9cd019f7deaa82030b984e11434ca86328f8

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [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)
 
 

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/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