lex-llm 0.3.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21bb44444f871870151b379672c39b043c36233ee0b7d634660a7fe021f355b6
-  data.tar.gz: 2bc64a7a18d4304179e7465c99e21fdf584a9e4dd54860b207bf8d8c87e738cf
+  metadata.gz: b266813f29f9a144b2a57408f39fe98bc27b7a53e59b13871ca22c0dc8cf6127
+  data.tar.gz: 80cb7a8866d4cd2b9c150dd4567f99aa09d12208f8acfa38df3dd578c7c93831
 SHA512:
-  metadata.gz: 930d418014199a5f3b34bf505555e54462e2e590c11475859221d9a83c2def586f547c8341f813cfab03d6677ddbc8a66e06edc9f36e6bb6ffea05d36e40ce0b
-  data.tar.gz: 66201e1d6405692d6da1fbb38d294b7632a0ef2ca42f1578c548746a5caeb3d3a25d1d37347e33f88d628408d962707d4ab254038cc97d0ad27b89bafa42b0e8
+  metadata.gz: d43d28ab982b938f012a66000f73ee7cb4b9cae34ae31cbb6c11794d87845280ae919e2b91b81b594f76f6e11b95e9c57ff796c46d1ce595a74962b6d4a91800
+  data.tar.gz: 1976f2adfd60d698e547e92b00f7d779ab28b5c75c975a7245bc58ecc94dbb0d81b767c76552b3d1cee24a53fdd8d2bb98d1e3cb204816e27963491326daee50

data/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.4.3 - 2026-05-06
+
+- Move provider-owned fleet responder execution into `lex-llm` so provider gems no longer depend on `legion-llm`.
+- Add shared responder-side fleet token validation, idempotency protection, provider dispatch, and response/error publishing helpers.
+- Reserve fleet replay tokens before provider dispatch, split replay TTL into auth settings, and raise explicit responder transport configuration errors.
+
+## 0.4.2 - 2026-05-06
+
+- Remove the temporary settings logger wrapper and lazy-load fleet transport envelopes so `lex-llm` boot does not force `legion-transport` loading.
+
+## 0.4.1 - 2026-05-06
+
+- Make `AutoRegistration` a pure provider discovery mixin and remove upward `Legion::LLM::Call::Registry` mutation hooks.
+- Add provider alias metadata so `legion-llm` can register compatibility provider families without provider require-time side effects.
+- Pass live discovery flags and filters through from `Provider#discover_offerings` to `#list_models`.
+- Merge provider-specific embedding params into canonical `Provider#embed` request payloads.
+
+## 0.4.0 - 2026-05-06
+
+- Set the coordinated sweep dependency floor for provider-owned fleet responders.
+- Make `Provider#discover_offerings(live: false)` serve only cached live discovery results so inventory reads do not probe provider endpoints.
+
+## 0.3.6 - 2026-05-06
+
+- Replace shared fleet request, response, and error envelopes with strict fleet protocol v2 fields.
+- Reject legacy fleet envelope fields and publish provider replies through the AMQP default exchange reply queue with optional mandatory routing and publisher confirms.
+
+## 0.3.5 - 2026-05-06
+
+- Add shared response normalization value objects for chat, stream, embedding, and thinking extraction.
+- Strip provider thinking from caller-visible OpenAI-compatible completion content, including malformed trailing close-tag output.
+- Preserve provider reasoning metadata while tolerating streaming tool-call deltas without optional function names.
+
+## 0.3.4 - 2026-05-06
+
+- Add shared provider contract and unsupported capability error namespace for lex-llm provider gems.
+- Require keyword provider embed/count token calls and validate provider settings instance nesting.
+- Move shared fleet defaults under nested consumer/auth settings.
+
+## 0.3.3 - 2026-05-03
+
+- Fix OpenAI-compatible streaming to keep split `<think>` tag content out of streamed assistant content.
+- Strip leaked assistant thinking from outbound OpenAI-compatible history, including dangling close-tag content from prior responses.
+- Tolerate incomplete streaming tool-call deltas that omit `function.name`.
+
+## 0.3.2 - 2026-05-03
+
+- Fix AutoRegistration to pass the discovered instance id into provider adapter config for instance-aware model offerings
+
 ## 0.3.1 - 2026-05-02
 
 - Fix AutoRegistration to pass tier and capabilities metadata to Call::Registry on registration

data/README.md

@@ -37,7 +37,7 @@ Expected provider gems include:
 - `lex-llm-mlx`
 - `lex-llm-bedrock`
 - `lex-llm-vertex`
-- `lex-llm-azure`
+- `lex-llm-azure-foundry`
 
 ## Install
 
@@ -48,7 +48,7 @@ gem 'lex-llm'
 Provider extensions should declare `lex-llm` as a gemspec dependency:
 
 ```ruby
-spec.add_dependency 'lex-llm', '>= 0.1.6'
+spec.add_dependency 'lex-llm', '>= 0.4.3'
 ```
 
 For local development across LegionIO repos, prefer a local path override in the app or test `Gemfile`, not a permanent git dependency in the gemspec.
@@ -297,6 +297,22 @@ At minimum, a provider extension should define:
 
 Provider extensions should avoid duplicating shared classes, schema logic, fleet lane construction, JSON handling, or common request/response objects.
 
+Canonical provider calls are keyword-based:
+
+```ruby
+provider.chat(messages:, model:, tools: [], temperature: nil, params: {}, headers: {}, schema: nil, thinking: nil)
+provider.stream_chat(messages:, model:, tools: [], temperature: nil, params: {}, headers: {}, schema: nil, thinking: nil) { |chunk| ... }
+provider.embed(text:, model:, dimensions: nil, params: {}, headers: {})
+provider.image(prompt:, model:, size:, with: nil, mask: nil, params: {})
+provider.count_tokens(messages:, model:, params: {})
+provider.health(live: false)
+provider.discover_offerings(live: false, **filters)
+```
+
+Provider responses should normalize through the shared response objects before they reach callers. Visible assistant text and provider reasoning are separate values: provider-specific thinking fields, OpenAI-compatible `reasoning_content`, and literal `<think>...</think>` text are removed from caller-visible content and preserved as thinking metadata when present.
+
+Fleet envelopes also live here. `FleetRequest`, `FleetResponse`, and `FleetError` are protocol-v2 transport messages with `operation`, `request_id`, `correlation_id`, `idempotency_key`, `message_context`, and signed-token fields. Provider gems should consume and publish these shared envelopes instead of defining local fleet message shapes.
+
 All providers inherit `#readiness(live: false)`, which returns configured state, provider locality, API base, endpoint helpers, and non-live health metadata without probing remote services. Providers with a cheap health endpoint can pass `live: true` to include that endpoint response. OpenAI-compatible providers also inherit shared model-list parsing that maps discovered models into normalized capabilities and modalities for Legion routing.
 
 ## Schema Status

data/lex-llm.gemspec

@@ -29,14 +29,17 @@ Gem::Specification.new do |spec|
 
   # Runtime dependencies
   spec.add_dependency 'base64'
+  spec.add_dependency 'concurrent-ruby', '>= 1.2'
   spec.add_dependency 'event_stream_parser', '~> 1'
   spec.add_dependency 'faraday', ENV['FARADAY_VERSION'] || '>= 1.10.0'
   spec.add_dependency 'faraday-multipart', '>= 1'
   spec.add_dependency 'faraday-net_http', '>= 1'
   spec.add_dependency 'faraday-retry', '>= 1'
+  spec.add_dependency 'legion-crypt', '>= 1.5.1'
   spec.add_dependency 'legion-json', '>= 1.2.1'
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.3.14'
+  spec.add_dependency 'legion-transport', '>= 1.4.14'
   spec.add_dependency 'marcel', '~> 1'
   spec.add_dependency 'ruby_llm-schema', '~> 0'
   spec.add_dependency 'zeitwerk', '~> 2'

data/lib/legion/extensions/llm/auto_registration.rb

@@ -3,9 +3,9 @@
 module Legion
   module Extensions
     module Llm
-      # Mixin that lex-llm-* provider modules `extend` to get shared
-      # registration boilerplate.  The provider only needs to override
-      # `discover_instances` — everything else is handled here.
+      # Mixin that lex-llm-* provider modules `extend` to expose shared
+      # discovery metadata. Registration into Legion::LLM is owned by
+      # legion-llm so loaded providers can be rediscovered after reloads.
       #
       # Prerequisites on the extending module:
       #   - `PROVIDER_FAMILY` constant (Symbol, e.g. :ollama)
@@ -16,39 +16,10 @@ module Legion
           {}
         end
 
-        # Calls discover_instances, creates a LexLLMAdapter for each,
-        # and registers into Call::Registry.
-        #
-        # Strips :tier and :capabilities from config before passing to
-        # the adapter (these are metadata, not connection config).
-        #
-        # Guarded: no-op when Legion::LLM::Call::Registry is not loaded.
-        def register_discovered_instances
-          return unless defined?(Legion::LLM::Call::Registry)
-
-          instances = discover_instances
-          instances.each do |instance_id, config|
-            registry_config = config.except(:tier, :capabilities)
-            adapter = Legion::LLM::Call::LexLLMAdapter.new(
-              self::PROVIDER_FAMILY, provider_class, instance_config: registry_config
-            )
-            meta = { tier: config[:tier], capabilities: config[:capabilities] || [] }
-            Legion::LLM::Call::Registry.register(
-              self::PROVIDER_FAMILY, adapter, instance: instance_id, metadata: meta
-            )
-          end
-        rescue StandardError => e
-          log.warn "[#{self::PROVIDER_FAMILY}] self-registration failed: #{e.message}" if respond_to?(:log)
-        end
-
-        # Deregisters all instances for this provider and re-runs discovery.
-        #
-        # Guarded: no-op when Legion::LLM::Call::Registry is not loaded.
-        def rediscover!
-          return unless defined?(Legion::LLM::Call::Registry)
-
-          Legion::LLM::Call::Registry.deregister_provider(self::PROVIDER_FAMILY)
-          register_discovered_instances
+        # Optional provider-family aliases that legion-llm should register
+        # against the same discovered provider instances.
+        def provider_aliases
+          []
         end
       end
     end

data/lib/legion/extensions/llm/embedding.rb

@@ -25,7 +25,7 @@ module Legion
                                                            config: config)
           model_id = model.id
 
-          provider_instance.embed(text, model: model_id, dimensions:)
+          provider_instance.embed(text:, model: model_id, dimensions:)
         end
       end
     end

data/lib/legion/extensions/llm/error.rb

@@ -27,6 +27,20 @@ module Legion
       class ModelNotFoundError < StandardError; end
       class UnsupportedAttachmentError < StandardError; end
 
+      # Backward-compatible unsupported-capability error alias.
+      class UnsupportedCapabilityError < Errors::UnsupportedCapability
+        def initialize(message = nil, provider: nil, capability: nil, model: nil)
+          if provider && capability
+            super(provider:, capability:, model:)
+          else
+            @provider = provider
+            @capability = capability
+            @model = model
+            StandardError.instance_method(:initialize).bind_call(self, message)
+          end
+        end
+      end
+
       # Error classes for different HTTP status codes
       class BadRequestError < Error; end
       class ForbiddenError < Error; end

data/lib/legion/extensions/llm/errors/unsupported_capability.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Errors
+        # Raised when a provider receives a canonical call for an unsupported capability.
+        class UnsupportedCapability < StandardError
+          attr_reader :provider, :capability, :model
+
+          def initialize(provider:, capability:, model: nil)
+            @provider = provider
+            @capability = capability
+            @model = model
+            super("Provider #{provider} does not support #{capability}#{" for #{model}" if model}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/fleet/default_exchange_reply.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative 'publish_safety'
+
+module Legion
+  module Extensions
+    module Llm
+      module Fleet
+        # Publishes correlated fleet replies directly to the caller's reply queue.
+        module DefaultExchangeReply
+          include PublishSafety
+
+          DEFAULT_REPLY_PUBLISH_OPTIONS = {
+            mandatory: false,
+            publisher_confirm: false,
+            spool: false,
+            return_result: true
+          }.freeze
+
+          def publish(options = nil)
+            raise unless @valid
+
+            requested_options = DEFAULT_REPLY_PUBLISH_OPTIONS.merge(@options).merge(options || {})
+            return_result = return_publish_result?(requested_options)
+            publish_options = reply_publish_options(requested_options)
+            validate_payload_size
+            default_exchange = channel.default_exchange
+            return_state = {}
+            install_return_listener(default_exchange, requested_options, return_state)
+            prepare_publisher_confirms(default_exchange, requested_options)
+            default_exchange.publish(encode_message, **publish_options)
+            return nil unless return_result
+
+            publish_result(default_exchange, requested_options.merge(publish_options), return_state)
+          rescue Bunny::ConnectionClosedError, Bunny::ChannelAlreadyClosed, Bunny::ChannelError,
+                 Bunny::NetworkErrorWrapper, IOError, Timeout::Error => e
+            handle_exception(e, level: :warn, handled: true, operation: 'llm.fleet.reply.publish')
+            reply_publish_failure_result(e, publish_options || @options)
+          end
+
+          private
+
+          def reply_publish_failure_result(error, options)
+            {
+              status: :failed,
+              accepted: false,
+              error_class: error.class.name,
+              error: error.message,
+              routing_key: options[:routing_key] || routing_key,
+              message_id: message_id,
+              correlation_id: correlation_id
+            }.compact
+          end
+
+          def reply_publish_options(options)
+            {
+              routing_key: routing_key,
+              content_type: options[:content_type] || content_type,
+              content_encoding: options[:content_encoding] || content_encoding,
+              type: options[:type] || type,
+              priority: options[:priority] || priority,
+              expiration: options[:expiration] || expiration,
+              headers: reply_headers(options),
+              persistent: options.key?(:persistent) ? options[:persistent] : persistent,
+              message_id: message_id,
+              correlation_id: correlation_id,
+              reply_to: reply_to,
+              app_id: options[:app_id] || app_id,
+              timestamp: timestamp,
+              mandatory: options[:mandatory] == true
+            }.compact
+          end
+
+          def reply_headers(options)
+            options[:headers] ? headers.merge(options[:headers]) : headers
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/fleet/envelope_validation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'protocol'
+
+module Legion
+  module Extensions
+    module Llm
+      module Fleet
+        # Shared validation helpers for strict fleet protocol v2 envelopes.
+        module EnvelopeValidation
+          LEGACY_OPTIONS = %i[schema_version request_type fleet_correlation_id].freeze
+
+          private
+
+          def reject_legacy_options!
+            LEGACY_OPTIONS.each do |key|
+              if @options.key?(key) || @options.key?(key.to_s)
+                raise ArgumentError, "#{key} is not supported by fleet protocol v2"
+              end
+            end
+          end
+
+          def require_option!(key)
+            return if @options.key?(key) && !@options[key].nil?
+
+            raise ArgumentError, "#{key} is required"
+          end
+
+          def require_protocol_version!
+            version = @options.fetch(:protocol_version, Fleet::Protocol::VERSION)
+            return if version == Fleet::Protocol::VERSION
+
+            raise ArgumentError, "protocol_version must be #{Fleet::Protocol::VERSION}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/fleet/protocol.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Fleet
+        module Protocol
+          VERSION = 2
+          REQUEST_TYPE = 'llm.fleet.request'
+          RESPONSE_TYPE = 'llm.fleet.response'
+          ERROR_TYPE = 'llm.fleet.error'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/fleet/provider_responder.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'protocol'
+require_relative 'settings'
+require_relative 'worker_execution'
+
+module Legion
+  module Extensions
+    module Llm
+      module Transport
+        # Autoloads responder publish envelopes without booting legion-transport during lex-llm load.
+        module Messages
+          autoload :FleetError, File.expand_path('../transport/messages/fleet_error', __dir__) unless
+            autoload?(:FleetError) || const_defined?(:FleetError, false)
+          autoload :FleetResponse, File.expand_path('../transport/messages/fleet_response', __dir__) unless
+            autoload?(:FleetResponse) || const_defined?(:FleetResponse, false)
+        end
+      end
+
+      module Fleet
+        # Shared implementation for provider-owned fleet responder runners.
+        module ProviderResponder
+          class ConfigurationError < StandardError; end
+
+          REQUIRED_FIELDS = %i[
+            request_id correlation_id idempotency_key operation provider provider_instance model params reply_to
+            message_context caller trace_context signed_token timeout_seconds expires_at protocol_version
+          ].freeze
+          LEGACY_FIELDS = %i[schema_version request_type fleet_correlation_id].freeze
+
+          FleetEnvelope = Struct.new(:data, keyword_init: true) do
+            def [](key)
+              data[key.to_sym] || data[key.to_s]
+            end
+
+            def key?(key)
+              data.key?(key.to_sym) || data.key?(key.to_s)
+            end
+
+            def fetch(key, default = nil)
+              key?(key) ? self[key] : default
+            end
+
+            def to_h = data
+            def protocol_version = self[:protocol_version]
+            def request_id = self[:request_id]
+            def correlation_id = self[:correlation_id]
+            def idempotency_key = self[:idempotency_key]
+            def operation = self[:operation]
+            def provider = self[:provider]
+            def provider_instance = self[:provider_instance]
+            def model = self[:model]
+            def params = self[:params] || {}
+            def reply_to = self[:reply_to]
+            def message_context = self[:message_context] || {}
+            def trace_context = self[:trace_context] || {}
+          end
+
+          module_function
+
+          # Public runner entry point mirrors AMQP delivery callbacks, which carry both delivery and property metadata.
+          # rubocop:disable Metrics/ParameterLists
+          def call(payload:, provider_family:, provider_class:, provider_instances:, delivery: nil, properties: nil)
+            envelope = parse_payload(payload)
+            check_envelope!(envelope, provider_family:)
+            provider = build_provider(envelope:, provider_class:, provider_instances:)
+            response = WorkerExecution.call(envelope: envelope, provider: provider)
+            publish_response(envelope, response)
+            ack(delivery || properties)
+            response
+          rescue StandardError => e
+            safe_publish_error(envelope, e) if defined?(envelope) && envelope
+            reject(delivery || properties, requeue: requeue_error?(e))
+            raise
+          end
+          # rubocop:enable Metrics/ParameterLists
+
+          def enabled_for?(provider_instances)
+            instances = resolve_provider_instances(provider_instances)
+            instances.any? do |_instance_id, settings|
+              truthy?(dig(settings, :fleet, :respond_to_requests))
+            end
+          end
+
+          def parse_payload(payload)
+            hash = case payload
+                   when FleetEnvelope
+                     payload.to_h
+                   when String
+                     parse_json(payload)
+                   else
+                     payload.respond_to?(:to_h) ? payload.to_h : {}
+                   end
+            FleetEnvelope.new(data: deep_symbolize(hash))
+          end
+
+          def check_envelope!(envelope, provider_family:)
+            reject_legacy_fields!(envelope)
+            REQUIRED_FIELDS.each do |field|
+              raise ArgumentError, "#{field} is required" unless envelope.key?(field) && !envelope[field].nil?
+            end
+
+            validate_protocol_version!(envelope)
+            validate_provider_family!(envelope, provider_family)
+          end
+
+          def build_provider(envelope:, provider_class:, provider_instances:)
+            instances = resolve_provider_instances(provider_instances)
+            instance_id = envelope.provider_instance.to_s
+            instance_settings = instances[instance_id.to_sym] || instances[instance_id]
+            unless instance_settings
+              raise ConfigurationError,
+                    "fleet provider instance is not configured: #{instance_id}"
+            end
+            unless truthy?(dig(instance_settings, :fleet, :respond_to_requests))
+              raise ConfigurationError, "fleet responses are disabled for provider instance: #{instance_id}"
+            end
+
+            provider_class.new(deep_symbolize(instance_settings))
+          end
+
+          def publish_response(envelope, response)
+            transport_message_class(:FleetResponse).new(
+              protocol_version: envelope.protocol_version,
+              request_id: envelope.request_id,
+              correlation_id: envelope.correlation_id,
+              idempotency_key: envelope.idempotency_key,
+              operation: envelope.operation,
+              provider: envelope.provider,
+              provider_instance: envelope.provider_instance,
+              model: envelope.model,
+              reply_to: envelope.reply_to,
+              message_context: envelope.message_context,
+              trace_context: envelope.trace_context,
+              content: response_content(response),
+              tool_calls: response_field(response, :tool_calls) || [],
+              usage: response_usage(response),
+              finish_reason: response_field(response, :finish_reason),
+              metadata: response_metadata(response)
+            ).publish
+          end
+
+          def publish_error(envelope, error)
+            transport_message_class(:FleetError).new(
+              protocol_version: envelope.protocol_version,
+              request_id: envelope.request_id,
+              correlation_id: envelope.correlation_id,
+              idempotency_key: envelope.idempotency_key,
+              operation: envelope.operation,
+              provider: envelope.provider,
+              provider_instance: envelope.provider_instance,
+              model: envelope.model,
+              reply_to: envelope.reply_to,
+              message_context: envelope.message_context,
+              trace_context: envelope.trace_context,
+              code: error_code(error),
+              message: error.message,
+              error_class: error.class.name,
+              retryable: retryable_error?(error),
+              metadata: {}
+            ).publish
+          end
+
+          def safe_publish_error(envelope, error)
+            publish_error(envelope, error)
+          rescue StandardError
+            nil
+          end
+
+          def transport_message_class(name)
+            ::Legion::Extensions::Llm::Transport::Messages.const_get(name)
+          rescue LoadError, NameError => e
+            raise ConfigurationError, "fleet responder transport unavailable for #{name}: #{e.message}"
+          end
+
+          def ack(delivery)
+            return unless delivery
+
+            if delivery.respond_to?(:ack)
+              delivery.ack
+            elsif delivery.respond_to?(:channel) && delivery.respond_to?(:delivery_tag)
+              delivery.channel.ack(delivery.delivery_tag)
+            end
+          end
+
+          def reject(delivery, requeue:)
+            return unless delivery
+
+            if delivery.respond_to?(:reject)
+              delivery.reject(requeue)
+            elsif delivery.respond_to?(:channel) && delivery.respond_to?(:delivery_tag)
+              delivery.channel.reject(delivery.delivery_tag, requeue)
+            end
+          end
+
+          def parse_json(payload)
+            if defined?(::Legion::JSON)
+              ::Legion::JSON.parse(payload)
+            else
+              ::JSON.parse(payload)
+            end
+          end
+
+          def reject_legacy_fields!(envelope)
+            LEGACY_FIELDS.each do |field|
+              raise ArgumentError, "#{field} is not supported by fleet protocol v2" if envelope.key?(field)
+            end
+          end
+
+          def validate_protocol_version!(envelope)
+            return if envelope.protocol_version == Protocol::VERSION
+
+            raise ArgumentError, "protocol_version must be #{Protocol::VERSION}"
+          end
+
+          def validate_provider_family!(envelope, provider_family)
+            return if envelope.provider.to_s == provider_family.to_s
+
+            raise ArgumentError, "fleet request provider #{envelope.provider} does not match #{provider_family}"
+          end
+
+          def resolve_provider_instances(provider_instances)
+            instances = provider_instances.respond_to?(:call) ? provider_instances.call : provider_instances
+            deep_symbolize(instances || {})
+          end
+
+          def requeue_error?(error)
+            retryable_error?(error) &&
+              Settings.value(:fleet, :consumer, :requeue_transient, default: true) != false
+          end
+
+          def retryable_error?(error)
+            return false if error.is_a?(ConfigurationError)
+            return false if error.is_a?(WorkerExecution::PolicyError)
+
+            true
+          end
+
+          def error_code(error)
+            return 'configuration_error' if error.is_a?(ConfigurationError)
+            return 'policy_error' if error.is_a?(WorkerExecution::PolicyError)
+
+            'provider_error'
+          end
+
+          def response_content(response)
+            response_field(response, :content) || response_field(response, :result) || response.to_s
+          end
+
+          def response_usage(response)
+            usage = response_field(response, :usage) || response_field(response, :tokens)
+            return deep_symbolize(usage) if usage.respond_to?(:to_h)
+
+            {
+              input_tokens: response_field(response, :input_tokens),
+              output_tokens: response_field(response, :output_tokens),
+              thinking_tokens: response_field(response, :thinking_tokens)
+            }.compact
+          end
+
+          def response_metadata(response)
+            metadata = response_field(response, :metadata)
+            metadata.respond_to?(:to_h) ? deep_symbolize(metadata) : {}
+          end
+
+          def response_field(response, field)
+            return response[field] if response.respond_to?(:key?) && response.key?(field)
+            return response[field.to_s] if response.respond_to?(:key?) && response.key?(field.to_s)
+            return response.public_send(field) if response.respond_to?(field)
+
+            nil
+          end
+
+          def dig(hash, *keys)
+            keys.reduce(hash) do |current, key|
+              break nil unless current.respond_to?(:key?)
+
+              current[key.to_sym] || current[key.to_s]
+            end
+          end
+
+          def truthy?(value)
+            value == true || value.to_s == 'true'
+          end
+
+          def deep_symbolize(value)
+            case value
+            when Hash
+              value.each_with_object({}) do |(key, child), result|
+                result[key.respond_to?(:to_sym) ? key.to_sym : key] = deep_symbolize(child)
+              end
+            when Array
+              value.map { |child| deep_symbolize(child) }
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end