agent-harness 0.44.21 → 0.44.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79e4e172d70ecba9f4f3249a6d1ee93af4f47ba444991beea77f1a0d152cc0af
-  data.tar.gz: '0489867bae0853510e78ff6251aab2980048be0de24f10fdba9c8ef2b816f90f'
+  metadata.gz: bd3556ae8d2b4d460344b7479ad613d978baec38b54a7261bc4024314b2a5fd6
+  data.tar.gz: e5db97cdc1f923b2791d80bd3ca7b3dcf1060adc30a0c979f96da94e93740f63
 SHA512:
-  metadata.gz: 6657b638390c5f3ae19c5100d33e78b8ed8b26292d90bfad5e649479c5e7e4b0619a6c20118c9a68d9fa1f216379d4c2d25f62cea82a4c82b61d858d09ddc309
-  data.tar.gz: c52577902c4a2852afcceda0f76da39e1f829a4a191051cd5978934955c577830b6ac4281d95d6b563bf3f8c2bf62732b9efe70a1636797b6af014b43b5596d6
+  metadata.gz: 38cba9849f8f085fe92b6c9bb5a7de4df67d4c3591a6d6a48459d391aaf4dc79ccbd8dbc684d667e103df3b2e3661dc82da8e4d88df9327ccf231741c1058525
+  data.tar.gz: 2567485b7f2c3f181d61d9124d43c6e6dd13bdf3ac6158687e6b5ebd0f75a8506a9e0b5dc0157ccc4fa4ff9a06ee52483b0f7571c4442de8fc3bdc59cdaef712

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -12,6 +12,13 @@
 
 * 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)
 
 

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

@@ -490,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"
 
@@ -443,6 +444,11 @@ module AgentHarness
     end
 
     module ErrorClassifier
+      ACTIONABLE_DETAIL_ERRORS = [
+        RubyLLM::BadRequestError,
+        RubyLlmChatAdapter::UnsupportedOptionError
+      ].freeze
+
       TRANSIENT = {
         Faraday::TimeoutError => :timeout,
         Faraday::ConnectionFailed => :connection_failed,
@@ -480,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
@@ -497,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

@@ -303,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

data/lib/agent_harness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentHarness
-  VERSION = "0.44.21"
+  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.21
+  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