agent-harness 0.44.20 → 0.44.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 894fbdcf3b2dc1db0a3da49dbe98acc21c03b167f6ba2fe0574760ba74c18854
-  data.tar.gz: cdfca3e9e6edc6f1704ac6336c190c2268a537b141bf2ba9cb7a3ffdb172d9d4
+  metadata.gz: bd3556ae8d2b4d460344b7479ad613d978baec38b54a7261bc4024314b2a5fd6
+  data.tar.gz: e5db97cdc1f923b2791d80bd3ca7b3dcf1060adc30a0c979f96da94e93740f63
 SHA512:
-  metadata.gz: 3b94d9c2e2772489a160e8a645b5bc49b0f75682c05b2710643767379e7986da93cd11178745e3bb045fc06c47895c179f53e90939a55920b80f8dc08ec33d90
-  data.tar.gz: 9bb666e9d727cd3d7cea914053dfa80849d450e8fc786d0234f227842fc95bf99ac97e9181f00d9431a1202b3ac65933888380fca5e99a5f49a4f3b77b916f81
+  metadata.gz: 38cba9849f8f085fe92b6c9bb5a7de4df67d4c3591a6d6a48459d391aaf4dc79ccbd8dbc684d667e103df3b2e3661dc82da8e4d88df9327ccf231741c1058525
+  data.tar.gz: 2567485b7f2c3f181d61d9124d43c6e6dd13bdf3ac6158687e6b5ebd0f75a8506a9e0b5dc0157ccc4fa4ff9a06ee52483b0f7571c4442de8fc3bdc59cdaef712

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.44.20"
+  ".": "0.44.22"
 }

data/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+* support reasoning-capable OpenAI function-tool chat through the Responses API, including opaque reasoning state across tool-result continuation, streaming tool IDs and arguments, usage, cancellation, classified errors, an explicit compatible-provider protocol contract, and a gated live smoke test ([#499](https://github.com/viamin/agent-harness/issues/499)).
 * verify RDR-072's published capability artifacts and migration limits, retain the application chat loop over normalized transport, and remove the private RubyLLM streaming-refusal patch in favor of an explicit non-streaming schema boundary ([#437](https://github.com/viamin/agent-harness/issues/437)).
 * expose normalized API chat transport and schema-constrained responses with preserved JSON text, locally validated parsed values, and explicit refusal, truncation, invalid JSON, schema mismatch, and unsupported-mode outcomes; this combined delivery supersedes the separate chat-transport work item ([#433](https://github.com/viamin/agent-harness/issues/433), [#434](https://github.com/viamin/agent-harness/issues/434)).
 * add runner model compatibility contract (`AgentHarness.model_compatibility`) with structured `ModelCompatibility::Result` outcomes. Codex exposes static facts for CLI-gated models (e.g. `gpt-5.5` requires Codex CLI `>= 0.116.0`), a baseline supported-model list, supported auth modes, and a `DEFAULT_COMPATIBLE_MODEL_ID` fallback so downstream orchestrators can validate tier/model assignments before scheduling agent runs ([#259](https://github.com/viamin/agent-harness/issues/259)).
@@ -11,6 +12,20 @@
 
 * close the RDR-072 upstream epic from #437's retained-scope evidence while keeping unpublished capabilities and downstream adoption behind their explicit release and integration gates ([#430](https://github.com/viamin/agent-harness/issues/430)).
 
+## [0.44.22](https://github.com/viamin/agent-harness/compare/agent-harness/v0.44.21...agent-harness/v0.44.22) (2026-10-21)
+
+
+### Bug Fixes
+
+* Preserve safe actionable provider error details in API chat failures ([#502](https://github.com/viamin/agent-harness/issues/502)) ([509a877](https://github.com/viamin/agent-harness/commit/509a8773e330cdc4bccb53edfe51bafef6b8e20f))
+
+## [0.44.21](https://github.com/viamin/agent-harness/compare/agent-harness/v0.44.20...agent-harness/v0.44.21) (2026-10-21)
+
+
+### Bug Fixes
+
+* Support reasoning-capable OpenAI chat with function tools through Responses API ([#501](https://github.com/viamin/agent-harness/issues/501)) ([5976a89](https://github.com/viamin/agent-harness/commit/5976a89b2dacec48338eac8b2b45bc59976e4bd1))
+
 ## [0.44.20](https://github.com/viamin/agent-harness/compare/agent-harness/v0.44.19...agent-harness/v0.44.20) (2026-10-19)
 
 

data/README.md

@@ -104,6 +104,55 @@ agent-harness release containing this capability:
 The runtime dependency is Ruby 3.2 or newer and RubyLLM 2.x. No Rails database
 or RubyLLM persistence tables are required for this plain-Ruby operation.
 
+## Native API chat
+
+`AgentHarness::Api::ChatTransport` supports OpenAI's Responses API explicitly.
+Select `protocol: :responses` for reasoning-capable OpenAI models used with
+function tools; this preserves the model's reasoning behavior. Do not select
+Chat Completions and do not disable reasoning or remove tools as a workaround.
+OpenAI-compatible providers that only implement Chat Completions continue to
+use `provider: :openai`, their explicit `endpoint`, and
+`protocol: :chat_completions`; Agent Harness never probes or silently changes
+the selected protocol.
+
+```ruby
+candidate = {
+  provider: :openai,
+  model: "gpt-5.6-luna",
+  protocol: :responses,
+  authentication_mode: :api_key,
+  credentials: {api_key: ENV.fetch("OPENAI_API_KEY")}
+}
+
+result = AgentHarness::Api::ChatTransport.new.call(
+  request_id: SecureRandom.uuid,
+  operation: :chat,
+  candidates: [candidate],
+  messages: [{role: :user, content: "Look up order 42"}],
+  tools: [{
+    name: "lookup_order",
+    description: "Find an order",
+    input_schema: {type: "object", properties: {id: {type: "integer"}}, required: ["id"]}
+  }],
+  stream: true,
+  retry: {max_attempts: 1}
+)
+```
+
+The harness returns tool calls without executing them. For the next request,
+append the assistant message (including `tool_calls` and `provider_state`) and
+then a tool message whose `tool_call_id` is the returned stable harness ID.
+`provider_state` is opaque protocol continuation data: persist and return it
+unchanged, and never inspect or log it. The transport maps the stable ID back
+to the provider call ID and replays the encrypted Responses reasoning item.
+
+To run the credential-gated live tool-continuation smoke test:
+
+```bash
+AGENT_HARNESS_LIVE_OPENAI=1 OPENAI_API_KEY=... \
+  bundle exec rspec spec/live/openai_responses_reasoning_spec.rb
+```
+
 ## Configuration
 
 ### Ruby DSL

data/docs/provider-neutral-api-execution-contract.md

@@ -247,7 +247,10 @@ The input is an ordered array. Each message has a stable caller-owned `id`, one
 of `system`, `user`, `assistant`, or `tool` as its `role`, and an ordered
 `content` array. Content parts initially support `text`; unimplemented media
 parts produce an explicit unsupported outcome. Assistant messages MAY contain
-tool calls. Tool messages MUST reference exactly one `tool_call_id`.
+tool calls. A Responses assistant message that requests tools also carries the
+opaque `provider_state` returned by the preceding result. Consumers MUST
+persist and return that value unchanged and MUST NOT inspect or log it. Tool
+messages MUST reference exactly one `tool_call_id`.
 
 Provider-specific wire roles, system-message placement, and content block
 shapes stay behind the harness boundary. The harness MUST preserve ordering,
@@ -275,6 +278,9 @@ reference the stable ID. Redelivery or restoration MUST skip a tool call when a
 completed result for that ID exists.
 
 The transport never decides approval and never executes application tools.
+For stateless OpenAI Responses continuation, the harness uses `provider_state`
+to replay the provider's encrypted reasoning and function-call output items.
+The field is absent when the selected protocol does not require opaque state.
 
 ### Streaming
 
@@ -484,7 +490,13 @@ result/usage where available. Categories are:
 
 Adapters MUST use the following category and code mappings. A provider-specific
 status or error name may be retained as sanitized metadata, but MUST NOT replace
-these values or change fallback eligibility.
+these values or change fallback eligibility. The normalized `message` may append
+bounded, actionable detail for request, capability, configuration, and
+response-shape failures. Such detail MUST redact credentials, headers, request
+bodies, conversation content, and URLs, and MUST never copy an unparsed provider
+response body or a message derived from one. Parser diagnostics are also omitted
+because they can quote request or conversation content. Attempt reports retain
+the same sanitized error object as the public result.
 
 | Failure | Category | Code |
 | --- | --- | --- |

data/lib/agent_harness/api/chat_transport.rb

@@ -3,6 +3,7 @@
 require "securerandom"
 require "ruby_llm"
 require_relative "attempt_report"
+require_relative "provider_error_detail"
 require_relative "ruby_llm_chat_adapter"
 require_relative "schema_response"
 
@@ -150,6 +151,7 @@ module AgentHarness
             content: schema_result[:content],
             parsed: schema_result[:parsed],
             tool_calls: normalize_tool_calls(adapter_result[:tool_calls]),
+            provider_state: adapter_result[:provider_state],
             finish_reason: adapter_result[:finish_reason],
             usage: aggregate_usage,
             error: schema_result[:error]
@@ -442,6 +444,11 @@ module AgentHarness
     end
 
     module ErrorClassifier
+      ACTIONABLE_DETAIL_ERRORS = [
+        RubyLLM::BadRequestError,
+        RubyLlmChatAdapter::UnsupportedOptionError
+      ].freeze
+
       TRANSIENT = {
         Faraday::TimeoutError => :timeout,
         Faraday::ConnectionFailed => :connection_failed,
@@ -479,7 +486,7 @@ module AgentHarness
       end
 
       def self.payload(error, category, code, retryable)
-        payload = {category: category, code: code, retryable: retryable, message: safe_message(category, code)}
+        payload = {category: category, code: code, retryable: retryable, message: safe_message(error, category, code)}
         retry_after = retry_after_seconds(error)
         payload[:retry_after_seconds] = retry_after if retry_after
         payload
@@ -496,8 +503,12 @@ module AgentHarness
       end
       private_class_method :retry_after_seconds
 
-      def self.safe_message(category, code)
-        "Chat request failed (#{category}/#{code})"
+      def self.safe_message(error, category, code)
+        summary = "Chat request failed (#{category}/#{code})"
+        return summary unless ACTIONABLE_DETAIL_ERRORS.any? { |klass| error.is_a?(klass) }
+
+        detail = ProviderErrorDetail.call(error)
+        detail.to_s.empty? ? summary : "#{summary}: #{detail}"
       end
       private_class_method :safe_message
     end

data/lib/agent_harness/api/provider_error_detail.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module Api
+    # Extracts allowlisted, actionable text from provider errors without
+    # retaining response bodies or caller-controlled message content.
+    module ProviderErrorDetail
+      LOCAL_DETAILS = [
+        "RubyLLM does not support request-local connect timeouts",
+        "provider state does not match the selected protocol",
+        "provider state must carry at least one Responses output item",
+        "unsupported content type"
+      ].freeze
+      TOOL_REASONING_DETAIL = "Function tools with reasoning_effort are not supported for gpt-5.6-luna " \
+        "in /v1/chat/completions. To use function tools, use /v1/responses or set reasoning_effort to 'none'."
+
+      module_function
+
+      def call(error)
+        message = normalized(error.message)
+        return if message.empty? || structured_body?(message) || !safe_source?(error, message)
+
+        message
+      end
+
+      def normalized(value)
+        value.to_s.encode("UTF-8", invalid: :replace, undef: :replace, replace: "�")
+          .gsub(/[[:cntrl:]]+/, " ").gsub(/\s+/, " ").strip
+      end
+      private_class_method :normalized
+
+      def safe_source?(error, message)
+        safe_local_detail?(error, message) || safe_provider_detail?(error, message)
+      end
+      private_class_method :safe_source?
+
+      def safe_local_detail?(error, message)
+        error.is_a?(RubyLlmChatAdapter::UnsupportedOptionError) && LOCAL_DETAILS.include?(message)
+      end
+      private_class_method :safe_local_detail?
+
+      # RubyLLM parses this provider diagnostic from a JSON error field before
+      # constructing BadRequestError. Checking both the structured body and its
+      # fixed, non-content-bearing shape avoids exposing raw bodies or arbitrary
+      # provider prose that may echo request or conversation content.
+      def safe_provider_detail?(error, message)
+        error.is_a?(RubyLLM::BadRequestError) && message == TOOL_REASONING_DETAIL &&
+          structured_messages(error.response).include?(message)
+      end
+      private_class_method :safe_provider_detail?
+
+      def structured_messages(response)
+        body = response&.body
+        parsed = body.is_a?(String) ? JSON.parse(body) : body
+        return [] unless parsed.is_a?(Hash)
+
+        error = parsed["error"] || parsed[:error]
+        [error, parsed].filter_map { |part| part["message"] || part[:message] if part.is_a?(Hash) }
+      rescue JSON::ParserError
+        []
+      end
+      private_class_method :structured_messages
+
+      def structured_body?(message)
+        message.start_with?("{", "[", "<")
+      end
+      private_class_method :structured_body?
+    end
+  end
+end

data/lib/agent_harness/api/ruby_llm_chat_adapter.rb

@@ -26,8 +26,8 @@ module AgentHarness
           provider_usage_reported = true if event[:type] == :usage_updated
           on_event&.call(event)
         end
-        emit_completed_tool_calls(response, &on_event) if stream
-        normalize_response(response)
+        emit_completed_tool_calls(response, &on_event) if stream && on_event
+        normalize_response(response, candidate)
       end
 
       def prepare(candidate:, messages:, tools:, max_output_tokens:, temperature:, timeout:, on_accounting: nil,
@@ -74,6 +74,66 @@ module AgentHarness
         end
       end
 
+      # Captures the opaque Responses output items that continue a turn.
+      # RubyLLM exposes the provider output only when it kept it: an
+      # unstreamed call parses the response body, and a streamed one keeps the
+      # output for namespaced calls and server tools. A streamed turn that used
+      # plain function calls leaves neither, so its replay items are rebuilt
+      # from the reasoning signature and tool calls the stream accumulator
+      # retained, in the same shape the Responses protocol itself replays.
+      class ResponsesOutput
+        def self.from(message)
+          new(message).items
+        end
+
+        def initialize(message)
+          @message = message
+        end
+
+        def items
+          retained_output || replay_items
+        end
+
+        private
+
+        def retained_output
+          [parsed_body_output, @message.raw_content].find { |output| output.is_a?(Array) && output.any? }
+        end
+
+        # A streamed response's raw is the Faraday response, whose body the
+        # adapter empties, so only an unstreamed body is a parsed Hash here.
+        def parsed_body_output
+          body = @message.raw&.body
+          body["output"] if body.is_a?(Hash)
+        end
+
+        def replay_items
+          [reasoning_item, message_item, *function_call_items].compact
+        end
+
+        def reasoning_item
+          thinking = @message.thinking
+          return unless thinking&.signature
+
+          summary = thinking.text.to_s.empty? ? [] : [{type: "summary_text", text: thinking.text}]
+          {"type" => "reasoning", "summary" => summary, "encrypted_content" => thinking.signature}
+        end
+
+        def message_item
+          content = @message.content.to_s
+          return if content.strip.empty?
+
+          {"role" => "assistant", "content" => [{"type" => "output_text", "text" => content}]}
+        end
+
+        def function_call_items
+          Array(@message.tool_calls&.values).map do |call|
+            {"type" => "function_call", "call_id" => call.id, "name" => call.name,
+             "arguments" => JSON.generate(call.arguments || {})}
+          end
+        end
+      end
+
       private
 
       def ruby_llm_protocol(candidate)
@@ -151,7 +211,7 @@ module AgentHarness
       end
 
       def configure_chat(chat, candidate, messages, tools, max_output_tokens, temperature, schema)
-        chat.messages = normalize_messages(messages)
+        chat.messages = normalize_messages(messages, candidate)
         chat.with_tools(tools.map { |tool| normalized_tool(tool) }) unless tools.empty?
         chat.with_headers(candidate[:headers] || {})
         chat.with_max_output_tokens(max_output_tokens) if max_output_tokens
@@ -185,17 +245,43 @@ module AgentHarness
         token.respond_to?(:cancelled?) ? token.cancelled? : token.call
       end
 
-      def normalize_messages(messages)
+      def normalize_messages(messages, candidate)
         stable_to_provider = tool_id_map(messages)
         messages.map do |message|
           role = message.fetch(:role).to_sym
           normalized = {role: role, content: text_content(message[:content])}
           normalized[:tool_calls] = normalize_input_tool_calls(message[:tool_calls]) if message[:tool_calls]
           normalized[:tool_call_id] = stable_to_provider.fetch(message[:tool_call_id], message[:tool_call_id]) if role == :tool
+          apply_provider_state(normalized, message[:provider_state], candidate) if role == :assistant
           normalized
         end
       end
 
+      def apply_provider_state(message, state, candidate)
+        return unless state
+
+        validate_provider_state(state, candidate)
+        message[:raw_content] = state[:output]
+      end
+
+      # Provider state crosses a caller-owned boundary, so anything the
+      # selected protocol cannot replay as an assistant turn is rejected here
+      # rather than sent: an empty item list would drop the message content and
+      # its tool calls from the request.
+      def validate_provider_state(state, candidate)
+        unless responses_protocol?(candidate) && state[:protocol]&.to_sym == :responses
+          raise UnsupportedOptionError, "provider state does not match the selected protocol"
+        end
+
+        return if state[:output].is_a?(Array) && state[:output].any?
+
+        raise UnsupportedOptionError, "provider state must carry at least one Responses output item"
+      end
+
+      def responses_protocol?(candidate)
+        candidate[:provider].to_s == "openai" && candidate[:protocol].to_s == "responses"
+      end
+
       def tool_id_map(messages)
         messages.each_with_object({}) do |message, ids|
           Array(message[:tool_calls]).each do |call|
@@ -217,7 +303,7 @@ module AgentHarness
 
         Array(content).map do |part|
           unless part[:type]&.to_sym == :text
-            raise UnsupportedOptionError, "unsupported content type: #{part[:type]}"
+            raise UnsupportedOptionError, "unsupported content type"
           end
 
           part[:text].to_s
@@ -301,17 +387,27 @@ module AgentHarness
         end
       end
 
-      def normalize_response(response)
+      def normalize_response(response, candidate)
         {
           content: response.content || "",
           model: response.model,
           finish_reason: response.finish_reason,
           usage: normalize_usage(response.tokens),
           tool_calls: Array(response.tool_calls&.values).map { |call| normalize_tool_call(call) },
+          provider_state: provider_state(response, candidate),
           refusal: refusal?(response)
         }
       end
 
+      # Only the Responses protocol carries opaque continuation state; other
+      # protocols replay a turn from the normalized messages alone.
+      def provider_state(response, candidate)
+        return unless responses_protocol?(candidate)
+
+        output = ResponsesOutput.from(response)
+        {protocol: :responses, output: output} if output.any?
+      end
+
       def refusal?(response)
         return true if response.finish_reason == :content_filter
         return false unless response.respond_to?(:raw)

data/lib/agent_harness/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.44.20
+  version: 0.44.22
 platform: ruby
 authors:
 - Bart Agapinan
@@ -145,6 +145,7 @@ files:
 - lib/agent_harness.rb
 - lib/agent_harness/api/attempt_report.rb
 - lib/agent_harness/api/chat_transport.rb
+- lib/agent_harness/api/provider_error_detail.rb
 - lib/agent_harness/api/ruby_llm_chat_adapter.rb
 - lib/agent_harness/api/schema_response.rb
 - lib/agent_harness/authentication.rb