agent-harness 0.39.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b6b9b84a3074d82a44dd35a6b377628c64cfa01958ca5c41ec910b694375fcf
-  data.tar.gz: 8069427d9a79624deba026984490a5f25cf97df7364c6d78b44c2a43aef773c6
+  metadata.gz: c4406422d8b90ec6406bb4cdcc6e1d7496b708f43aad306d258c2570ed4f710e
+  data.tar.gz: cd23fe2f7d4b05e2ac18ac9aa2a631a0b292bc2703ae092f4f55a1ca6f3febbb
 SHA512:
-  metadata.gz: cad34514f544dcf13a470afbb7cbdde82269246ee16d97319e3e6f33afd2e663b0625fd2f088bc4c68ef491676ac3c5cfc80e6bc3ba5a030fbda1abbe9a04cf7
-  data.tar.gz: 48fd85599fca1ae94fe13e433d4a69d1ab5bd8ce4c9c8feab6388c79c2d48c5314467cba8c4fcb277662c1aea20f53206b35fef6cad0a82ef82618249a80a883
+  metadata.gz: efb5e61347d70b28e03bb0cd2843429928843147bf8f196d1292af97be97c8ec67ca4ef81e6f169562d1fac5e88e277b06d07a7cd44bf3d85a772effb2c46051
+  data.tar.gz: 7c5fb37c7e14edbc3da68f74dc3f1a6d10e04630e70509a79bd04b9ebbfde2397d6a4753e288dd33d962efae79003728d30cdb0ae113d1bd4864de5995daa112

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.39.0"
+  ".": "0.41.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,20 @@
 * 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)).
 * **auth:** add provider-owned PKCE code-exchange API for Claude OAuth (`AgentHarness::Authentication.exchange_code`). Takes an authorization code plus PKCE verifier (and `redirect_uri`/`client_id`), posts an `authorization_code` grant to the Claude token endpoint, and persists the resulting access/refresh tokens in the native `claudeAiOauth` shape. Adds `exchange_code_supported?` and a `code_exchange` key to `auth_capabilities` ([#266](https://github.com/viamin/agent-harness/issues/266)).
 
+## [0.41.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.40.0...agent-harness/v0.41.0) (2026-09-25)
+
+
+### Features
+
+* Normalize API Chat Transport, Tools and Streaming (RDR-072) ([#441](https://github.com/viamin/agent-harness/issues/441)) ([761c118](https://github.com/viamin/agent-harness/commit/761c11842ccacd18d91e9412f71cb98d76afa3b2))
+
+## [0.40.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.39.0...agent-harness/v0.40.0) (2026-09-25)
+
+
+### Features
+
+* Provide Native Embedding Support (RDR-072) ([#439](https://github.com/viamin/agent-harness/issues/439)) ([551378d](https://github.com/viamin/agent-harness/commit/551378d11627a5227059032f0b7418dc166f54e9))
+
 ## [0.39.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.38.0...agent-harness/v0.39.0) (2026-09-25)
 
 

data/README.md

@@ -39,6 +39,71 @@ puts response.output
 response = AgentHarness.send_message("Explain this code", provider: :cursor)
 ```
 
+## Native Embeddings
+
+`AgentHarness.embed` sends a whole input batch through RubyLLM and returns one
+vector per input, in the same order. Credentials, endpoint, headers, timeout,
+and retry limits are request-local; they do not change `RubyLLM.config` or the
+CLI/subscription provider configuration.
+
+```ruby
+result = AgentHarness.embed(
+  inputs: ["first document", "second document"],
+  model: "text-embedding-3-small",
+  dimensions: 512,
+  endpoint: "https://api.openai.com/v1", # optional OpenAI-compatible base URL
+  credentials: {api_key: ENV.fetch("EMBEDDING_API_KEY")},
+  headers: {"X-Tenant-ID" => tenant.external_id},
+  timeout: 30,
+  max_attempts: 3,
+  cancellation: -> { request_cancelled? }
+)
+
+result.vectors # one vector for each input
+result.usage   # { input_tokens: 42 }
+```
+
+`credentials` may also be the API key string. Extra headers cannot replace the
+`Authorization` header; change credentials explicitly instead. `max_attempts`
+includes the initial request. Agent Harness performs the only retry loop: 429,
+timeout/connection, and transient 5xx failures are retried up to that bound,
+while 401 and 403 responses fail immediately. The harness honors `Retry-After`
+within its bounded retry policy. A cancellation callable is checked immediately
+before every physical HTTP attempt.
+
+Usage is the provider-reported total for the complete batch. When the provider
+omits usage, `result.usage[:input_tokens]` remains `nil`. The harness does not
+estimate usage or allocate a batch total across vectors, so
+`result.per_vector_usage` is always `nil`.
+
+Authentication failures raise `AgentHarness::AuthenticationError`, exhausted
+rate limits raise `AgentHarness::RateLimitError`, timeouts raise
+`AgentHarness::TimeoutError`, transient provider failures raise
+`AgentHarness::ProviderError`, cancellations raise
+`AgentHarness::CancelledError`, and incomplete or invalid vector batches raise
+`AgentHarness::MalformedEmbeddingError`. Empty input returns an empty result
+without contacting the provider.
+
+### Migrating from Paid transport patches
+
+This operation replaces downstream host/container embedding transport
+extensions for OpenAI-compatible direct and proxy endpoints. After adopting an
+agent-harness release containing this capability:
+
+1. Run the downstream embedding contract suite against both the direct provider
+   and proxy endpoint, including tenant-specific credentials and headers.
+2. Verify the released gem artifact includes `AgentHarness.embed` and record the
+   passing artifact version or digest. Issue closure or a Git tag alone is not
+   release evidence.
+3. Switch only the embedding call site to `AgentHarness.embed`; leave unrelated
+   chat, schema, CLI, and subscription paths unchanged.
+4. Remove the downstream embedding request/parser/retry patch so Agent Harness
+   owns the single bounded retry loop. Keep durable workflow recovery and
+   accounting in the downstream application.
+
+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.
+
 ## Configuration
 
 ### Ruby DSL

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

@@ -7,19 +7,83 @@ usage, and optional conversation-persistence work.
 
 ## Status and rollout boundary
 
-This is a design contract, not a claim that the described API is implemented.
-RDR-072's rollout guard is **docs-only now**, so this change adds no runtime
-behavior or dependency. Each capability below needs its own failing-first
-contract tests, implementation, release evidence, and downstream adoption
-evidence before a caller enables it.
+RDR-072's rollout guard was **docs-only** for the design phase. The normalized
+chat capability described in "Shipped normalized chat surface" below is now
+implemented. Other capabilities remain design contracts and each still needs
+its own failing-first contract tests, implementation, release evidence, and
+downstream adoption evidence before a caller enables it.
 
 Existing CLI and subscription behavior remains the default. Existing
 `TextTransport`, `OpenAICompatibleTransport`, `Conversation`, and `Response`
-interfaces remain available, but they do not yet satisfy this contract. A
-caller must not infer support from a gem version or issue closure.
+interfaces remain available and unchanged; they are not aliases for the
+normalized API. A caller must not infer support for another capability from a
+gem version or issue closure.
 
 Normative words such as MUST and MUST NOT describe the future public boundary.
 
+## Shipped normalized chat surface
+
+`AgentHarness::Api::ChatTransport#call` implements one normalized assistant
+response while leaving the conversation loop and all application tool
+execution with the caller:
+
+```ruby
+transport = AgentHarness::Api::ChatTransport.new
+result = transport.call(request.merge(
+  operation: :chat,
+  messages: [
+    {id: "system-1", role: :system,
+     content: [{type: :text, text: "Be concise"}]},
+    {id: "user-1", role: :user,
+     content: [{type: :text, text: "Summarize this"}]}
+  ],
+  tools: [{
+    name: "lookup",
+    description: "Looks up a record",
+    input_schema: {type: "object", properties: {id: {type: "string"}}}
+  }],
+  max_output_tokens: 1_000,
+  stream: true
+), observer: ->(event) { events << event })
+```
+
+The returned value is the normalized result hash in this document. The
+observer is either callable or responds to `on_chat_event`. It receives ordered
+events with request/attempt identity and sequence numbers. This transport never
+invokes a supplied tool; callers append completed tool results to a later
+request. A failed partial stream is terminal, so its content cannot be appended
+to a fallback response and its tool calls cannot be replayed automatically.
+
+Streamed tool-call arguments are emitted as raw, appendable JSON fragments
+correlated to one `tool_call_started` event per provider call, and cumulative
+provider token counts are emitted as deduplicated `usage_updated` events. An
+observer that raises aborts the in-flight request and surfaces as
+`AgentHarness::Api::ChatTransport::ObserverError` with the original failure as
+its `cause`; it is never classified as a provider error, never retried, and the
+failed observer is not invoked again.
+
+The verified scopes are Anthropic with `protocol: :messages`, OpenAI with
+`protocol: :responses` or `:chat_completions`, and OpenAI-compatible endpoints
+with `provider: :openai`, an explicit `endpoint`, and
+`protocol: :chat_completions`. Compatible endpoints that do not implement the
+Responses API must select `:chat_completions`; the transport never probes and
+silently switches protocols. Only `authentication_mode: :api_key` is currently
+supported.
+
+Credentials, endpoint, custom headers, timeout, and RubyLLM configuration are
+isolated with a request-local `RubyLLM::Context`. RubyLLM middleware retries
+are disabled; `retry.max_attempts` is the total physical-attempt limit owned by
+the harness. Authentication headers cannot be overridden by custom headers.
+`max_output_tokens` is forwarded without changing it.
+
+Unknown model IDs are allowed only because a complete provider and protocol
+are explicit in every candidate (`assume_model_exists: true` in the RubyLLM
+adapter). This skips registry validation; it does not assert that the endpoint
+supports the model. Provider rejection returns a classified failure. Custom
+endpoints retain the selected provider's wire protocol and authentication
+shape. Custom provider types, authentication modes, media content, and
+automatic protocol discovery are not supported by this capability.
+
 ## Ownership boundary
 
 AgentHarness owns protocol translation and one bounded provider request:

data/lib/agent_harness/api/chat_transport.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "ruby_llm"
+require_relative "ruby_llm_chat_adapter"
+
+module AgentHarness
+  module Api
+    # Executes one normalized chat response without running application tools.
+    class ChatTransport
+      RESERVED_HEADERS = {
+        anthropic: %w[x-api-key anthropic-version],
+        openai: %w[authorization]
+      }.freeze
+      PROTOCOLS = {
+        anthropic: %i[messages],
+        openai: %i[responses chat_completions]
+      }.freeze
+      DEFAULT_RETRY = {max_attempts: 1, base_delay_seconds: 0, max_delay_seconds: 0}.freeze
+
+      # Raised when the caller's observer fails. Observer bugs stay outside
+      # provider error classification, abort the in-flight request, and are
+      # never re-invoked with a synthetic terminal event.
+      class ObserverError < StandardError
+      end
+
+      def initialize(adapter: RubyLlmChatAdapter.new, id_generator: -> { SecureRandom.uuid }, sleeper: Kernel.method(:sleep))
+        @adapter = adapter
+        @id_generator = id_generator
+        @sleeper = sleeper
+      end
+
+      def call(request, observer: nil, &on_event)
+        execution = Execution.new(request, adapter: @adapter, id_generator: @id_generator,
+          sleeper: @sleeper, observer: observer || on_event)
+        execution.call
+      end
+
+      # Holds mutable state for exactly one request, keeping the transport reusable.
+      class Execution
+        def initialize(request, adapter:, id_generator:, sleeper:, observer:)
+          @request = symbolize(request)
+          @adapter = adapter
+          @id_generator = id_generator
+          @sleeper = sleeper
+          @observer = observer
+          @attempts = []
+          @sequence = 0
+          @partial_content = +""
+          @stream_tool_calls = {}
+          @tool_ids = {}
+          validate!
+        end
+
+        def call
+          return cancelled_result unless active?
+
+          candidates.each_with_index do |candidate, candidate_index|
+            result = attempt_candidate(candidate, candidate_index)
+            return result if terminal?(result)
+          end
+          failed_result(@last_error, @last_candidate)
+        end
+
+        private
+
+        attr_reader :request, :attempts
+
+        def attempt_candidate(candidate, candidate_index)
+          loop do
+            return cancelled_result(candidate) unless active?
+            return failed_result(@last_error, candidate) if attempts.length >= retry_config[:max_attempts]
+
+            result = perform_attempt(candidate)
+            return result if result[:status] == :succeeded || result[:status] == :partial
+            return cancelled_result(candidate) unless active?
+
+            @last_error = result[:error]
+            @last_candidate = candidate
+            return result if select_fallback(result, candidate_index)
+            return result unless retryable?(result)
+
+            backoff
+          end
+        end
+
+        def perform_attempt(candidate)
+          attempt_id = @id_generator.call
+          started_at = Time.now.utc
+          emitted = false
+          streamed_usage = nil
+          emit(:response_started, attempt_id:, candidate: candidate_identity(candidate))
+
+          adapter_result = @adapter.call(
+            candidate: candidate,
+            messages: request[:messages],
+            tools: request[:tools] || [],
+            max_output_tokens: request[:max_output_tokens],
+            temperature: request[:temperature],
+            stream: request[:stream] == true,
+            timeout: request[:timeout],
+            cancellation: request[:cancellation]
+          ) do |event|
+            event = normalize_stream_event(event)
+            emitted = true if output_event?(event)
+            streamed_usage = event.except(:type) if event[:type] == :usage_updated
+            accumulate(event)
+            emit(event.fetch(:type), attempt_id:, **event.except(:type))
+          end
+          raise RubyLLM::CancelledError unless active?
+
+          success(candidate, attempt_id, started_at, adapter_result)
+        rescue ObserverError
+          raise
+        rescue => error
+          failure(candidate, attempt_id, started_at, classify(error), partial: emitted, usage: streamed_usage)
+        end
+
+        def success(candidate, attempt_id, started_at, adapter_result)
+          attempts << attempt_report(candidate, attempt_id, started_at, :succeeded, usage: adapter_result[:usage])
+          result = base_result(candidate).merge(
+            status: :succeeded,
+            content: adapter_result[:content] || "",
+            tool_calls: normalize_tool_calls(adapter_result[:tool_calls]),
+            finish_reason: adapter_result[:finish_reason],
+            usage: aggregate_usage,
+            error: nil
+          )
+          emit(:response_completed, attempt_id:, result: result)
+          result
+        end
+
+        def failure(candidate, attempt_id, started_at, error, partial:, usage:)
+          status = failure_status(error, partial)
+          error = error.merge(retryable: false) if partial
+          attempts << attempt_report(candidate, attempt_id, started_at, status, error: error, usage: usage)
+          result = base_result(candidate).merge(
+            status: status,
+            content: partial ? @partial_content.dup : "",
+            tool_calls: partial_tool_calls,
+            finish_reason: nil,
+            usage: aggregate_usage,
+            error: error
+          )
+          emit((status == :cancelled) ? :response_cancelled : :response_failed, attempt_id:, result: result)
+          result
+        end
+
+        def fallback_allowed?(result, candidate_index)
+          return false if result[:status] == :partial
+          return false unless fallback_categories.include?(result.dig(:error, :category))
+          return false unless candidates[candidate_index + 1]
+
+          true
+        end
+
+        def select_fallback(result, candidate_index)
+          return false unless fallback_allowed?(result, candidate_index)
+
+          next_candidate = candidates[candidate_index + 1]
+          emit(:fallback_selected, attempt_id: attempts.last[:attempt_id],
+            from: candidate_identity(candidates[candidate_index]),
+            to: candidate_identity(next_candidate), error: result[:error])
+          true
+        end
+
+        def retryable?(result)
+          result.dig(:error, :retryable) && attempts.length < retry_config[:max_attempts]
+        end
+
+        def terminal?(result)
+          return true if %i[succeeded partial cancelled].include?(result[:status])
+          return true unless fallback_categories.include?(result.dig(:error, :category))
+
+          attempts.length >= retry_config[:max_attempts]
+        end
+
+        def backoff
+          exponent = [attempts.length - 1, 0].max
+          delay = retry_config[:base_delay_seconds] * (2**exponent)
+          cap = retry_config[:max_delay_seconds]
+          remaining = cap&.positive? ? [delay, cap].min : delay
+          while remaining.positive? && active?
+            interval = [remaining, 0.05].min
+            @sleeper.call(interval)
+            remaining -= interval
+          end
+        end
+
+        def emit(type, attempt_id:, **payload)
+          @sequence += 1
+          event = payload.merge(type: type, request_id: request[:request_id], attempt_id: attempt_id, sequence: @sequence)
+          deliver(event) if @observer
+        end
+
+        # Observer exceptions are caller bugs, not provider failures: they
+        # abort the in-flight request and surface directly instead of being
+        # classified or retried as provider errors.
+        def deliver(event)
+          @observer.respond_to?(:on_chat_event) ? @observer.on_chat_event(event) : @observer.call(event)
+        rescue => error
+          raise ObserverError, "chat observer failed: #{error.class} #{error.message}", error.backtrace
+        end
+
+        def accumulate(event)
+          @partial_content << event[:content].to_s if event[:type] == :text_delta
+          return unless event[:id]
+
+          call = (@stream_tool_calls[event[:id]] ||= {
+            id: event[:id], provider_id: event[:provider_id], name: event[:name],
+            arguments_json: +"", status: :incomplete
+          })
+          call[:arguments_json] << event[:arguments_json].to_s if event[:type] == :tool_call_delta
+          if event[:type] == :tool_call_completed
+            call[:arguments_json] = event[:arguments_json]
+            call[:status] = :completed
+          end
+        end
+
+        def output_event?(event)
+          %i[text_delta tool_call_started tool_call_delta tool_call_completed].include?(event[:type])
+        end
+
+        def partial_tool_calls
+          @stream_tool_calls.values.map(&:dup)
+        end
+
+        def normalize_tool_calls(tool_calls)
+          Array(tool_calls).map do |call|
+            call.merge(id: tool_id(call[:provider_id]), status: :completed)
+          end
+        end
+
+        def normalize_stream_event(event)
+          return event unless event[:provider_id]
+
+          event.merge(id: tool_id(event[:provider_id]))
+        end
+
+        def tool_id(provider_id)
+          @tool_ids[provider_id] ||= @id_generator.call
+        end
+
+        def base_result(candidate)
+          {
+            request_id: request[:request_id],
+            provider: candidate&.dig(:provider),
+            model: candidate&.dig(:model),
+            protocol: candidate&.dig(:protocol),
+            authentication_mode: candidate&.dig(:authentication_mode),
+            parsed: nil,
+            attempts: attempts.dup,
+            provider_request_id: nil
+          }
+        end
+
+        def failed_result(error, candidate)
+          base_result(candidate).merge(status: :failed, content: "", tool_calls: [], finish_reason: nil,
+            usage: aggregate_usage, error: error)
+        end
+
+        def cancelled_result(candidate = candidates.first)
+          error = {category: :cancelled, code: :cancelled, retryable: false, message: "Request cancelled"}
+          base_result(candidate).merge(status: :cancelled, content: "", tool_calls: [], finish_reason: nil,
+            usage: aggregate_usage, error: error)
+        end
+
+        def attempt_report(candidate, attempt_id, started_at, status, error: nil, usage: nil)
+          {
+            attempt_id: attempt_id,
+            request_id: request[:request_id],
+            number: attempts.length + 1,
+            provider: candidate[:provider],
+            model: candidate[:model],
+            status: status,
+            started_at: started_at.iso8601(6),
+            finished_at: Time.now.utc.iso8601(6),
+            usage: usage,
+            cost: nil,
+            provider_reported: false,
+            error: error
+          }
+        end
+
+        def aggregate_usage
+          reports = attempts.filter_map { |attempt| attempt[:usage] }
+          return if reports.empty?
+
+          %i[input_tokens output_tokens total_tokens].to_h do |key|
+            values = reports.filter_map { |usage| usage[key] }
+            [key, values.empty? ? nil : values.sum]
+          end
+        end
+
+        def classify(error)
+          ErrorClassifier.call(error)
+        end
+
+        def failure_status(error, partial)
+          return :cancelled if error[:category] == :cancelled
+          return :partial if partial
+
+          :failed
+        end
+
+        def candidates = request[:candidates]
+        def retry_config = @retry_config ||= DEFAULT_RETRY.merge(request[:retry] || {})
+        def fallback_categories = Array(request.dig(:fallback, :on_error_categories)).map(&:to_sym)
+
+        def active?
+          token = request[:cancellation]
+          return true unless token
+
+          cancelled = token.respond_to?(:cancelled?) ? token.cancelled? : token.call
+          !cancelled
+        end
+
+        def validate!
+          raise ArgumentError, "operation must be :chat" unless request[:operation]&.to_sym == :chat
+          raise ArgumentError, "request_id is required" if request[:request_id].to_s.empty?
+          raise ArgumentError, "candidates must not be empty" if !request[:candidates].is_a?(Array) || request[:candidates].empty?
+          raise ArgumentError, "messages must be an array" unless request[:messages].is_a?(Array)
+          validate_attempt_limit!
+          candidates.each { |candidate| validate_candidate!(candidate) }
+        end
+
+        def validate_attempt_limit!
+          limit = retry_config[:max_attempts]
+          raise ArgumentError, "retry.max_attempts must be a positive integer" unless limit.is_a?(Integer) && limit.positive?
+        end
+
+        def validate_candidate!(candidate)
+          candidate.replace(symbolize(candidate))
+          %i[provider model protocol authentication_mode credentials].each do |key|
+            raise ArgumentError, "candidate.#{key} is required" if candidate[key].nil?
+          end
+          raise ArgumentError, "only api_key authentication is supported" unless candidate[:authentication_mode].to_sym == :api_key
+          supported_protocols = PROTOCOLS[candidate[:provider].to_sym]
+          unless supported_protocols&.include?(candidate[:protocol].to_sym)
+            raise ArgumentError, "unsupported provider/protocol combination"
+          end
+
+          headers = candidate[:headers] || {}
+          reserved_names = RESERVED_HEADERS.fetch(candidate[:provider].to_sym, RESERVED_HEADERS.values.flatten)
+          reserved = headers.keys.map { |key| key.to_s.downcase } & reserved_names
+          raise ArgumentError, "reserved header override: #{reserved.first}" if reserved.any?
+        end
+
+        def candidate_identity(candidate)
+          candidate.slice(:provider, :model, :protocol, :authentication_mode)
+        end
+
+        def symbolize(value)
+          if value.is_a?(Hash)
+            return value.each_with_object({}) do |(key, child), normalized|
+              symbol = key.to_sym
+              normalized[symbol] = (symbol == :headers) ? child.dup : symbolize(child)
+            end
+          end
+          return value.map { |child| symbolize(child) } if value.is_a?(Array)
+
+          value
+        end
+      end
+    end
+
+    module ErrorClassifier
+      TRANSIENT = {
+        Faraday::TimeoutError => :timeout,
+        Faraday::ConnectionFailed => :connection_failed,
+        Faraday::SSLError => :connection_failed,
+        RubyLLM::RateLimitError => :rate_limited,
+        RubyLLM::ServerError => :server_error,
+        RubyLLM::ServiceUnavailableError => :service_unavailable,
+        RubyLLM::OverloadedError => :overloaded
+      }.freeze
+
+      NON_RETRYABLE = {
+        RubyLlmChatAdapter::MissingCredentialError => [:authentication, :invalid_credential],
+        RubyLLM::UnauthorizedError => [:authentication, :invalid_credential],
+        RubyLLM::ForbiddenError => [:authorization, :permission_denied],
+        RubyLLM::PaymentRequiredError => [:billing, :billing_unavailable],
+        RubyLLM::ContextLengthExceededError => [:context_length, :context_length_exceeded],
+        RubyLLM::BadRequestError => [:invalid_request, :invalid_request],
+        RubyLlmChatAdapter::UnsupportedOptionError => [:unsupported, :unsupported_capability],
+        RubyLLM::UnsupportedServerToolError => [:unsupported, :unsupported_capability],
+        RubyLLM::ToolCallParseError => [:invalid_response, :invalid_tool_arguments],
+        JSON::ParserError => [:invalid_response, :invalid_tool_arguments],
+        RubyLLM::ModelNotFoundError => [:configuration, :invalid_configuration],
+        RubyLLM::ConfigurationError => [:configuration, :invalid_configuration],
+        RubyLLM::CancelledError => [:cancelled, :cancelled]
+      }.freeze
+
+      def self.call(error)
+        transient = TRANSIENT.find { |klass, _| error.is_a?(klass) }
+        return payload(error, :transient, transient.last, true) if transient
+
+        permanent = NON_RETRYABLE.find { |klass, _| error.is_a?(klass) }
+        return payload(error, *permanent.last, false) if permanent
+
+        payload(error, :unknown, :unclassified_provider_error, false)
+      end
+
+      def self.payload(error, category, code, retryable)
+        {category: category, code: code, retryable: retryable, message: safe_message(category, code)}
+      end
+      private_class_method :payload
+
+      def self.safe_message(category, code)
+        "Chat request failed (#{category}/#{code})"
+      end
+      private_class_method :safe_message
+    end
+  end
+end