lex-llm 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f3fc1bac35781a8134a6d24d7467a790cdd506244cfd4f0e66955a4fa82ceb9
-  data.tar.gz: 0c1cdfe9dee8e21c5b9bba0a01b12f5ef41e30b46c73ff8d22ccc35d621818a9
+  metadata.gz: b266813f29f9a144b2a57408f39fe98bc27b7a53e59b13871ca22c0dc8cf6127
+  data.tar.gz: 80cb7a8866d4cd2b9c150dd4567f99aa09d12208f8acfa38df3dd578c7c93831
 SHA512:
-  metadata.gz: 4592bdc8998415754bfce42444be4168fc05eacd3d20be7872c3f5ed2ef3384cd44a9027cb23bb7f3f0e8dda8b12451f51332b16d2a4611975e950da0a5da2af
-  data.tar.gz: a90e2831742bc0af3c0d540f8459434d8fb287cb5504dbaf2be6c22425aceff4d929ff5c230485951d6669b46be79dd439d0f80a688272b52b8f494adab83b4f
+  metadata.gz: d43d28ab982b938f012a66000f73ee7cb4b9cae34ae31cbb6c11794d87845280ae919e2b91b81b594f76f6e11b95e9c57ff796c46d1ce595a74962b6d4a91800
+  data.tar.gz: 1976f2adfd60d698e547e92b00f7d779ab28b5c75c975a7245bc58ecc94dbb0d81b767c76552b3d1cee24a53fdd8d2bb98d1e3cb204816e27963491326daee50

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.

data/README.md

@@ -48,7 +48,7 @@ gem 'lex-llm'
 Provider extensions should declare `lex-llm` as a gemspec dependency:
 
 ```ruby
-spec.add_dependency 'lex-llm', '>= 0.4.0'
+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.

data/lex-llm.gemspec

@@ -29,11 +29,13 @@ 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'

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

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Fleet
+        # Reads fleet settings from Legion::Settings when available, falling back to lex-llm defaults.
+        module Settings
+          module_function
+
+          def value(*path, default:)
+            configured_llm_settings.each do |configured|
+              found = dig(configured, *path)
+              return found unless found.nil?
+            end
+
+            fallback = dig(default_settings, *path)
+            fallback.nil? ? default : fallback
+          end
+
+          def configured_llm_settings
+            return [] unless defined?(::Legion::Settings) && ::Legion::Settings.respond_to?(:[])
+
+            configured = []
+            extensions = safe_fetch(::Legion::Settings, :extensions)
+            extension_llm = dig(extensions, :llm)
+            configured << extension_llm if extension_llm.respond_to?(:key?)
+
+            llm = safe_fetch(::Legion::Settings, :llm)
+            configured << llm if llm.respond_to?(:key?)
+            configured
+          rescue StandardError
+            []
+          end
+
+          def dig(hash, *keys)
+            keys.reduce(hash) do |current, key|
+              break nil unless current.respond_to?(:key?)
+
+              symbol_key = key.respond_to?(:to_sym) ? key.to_sym : key
+              string_key = key.to_s
+              if current.key?(symbol_key)
+                current[symbol_key]
+              elsif current.key?(string_key)
+                current[string_key]
+              end
+            end
+          end
+
+          def safe_fetch(source, key)
+            source[key] || source[key.to_s]
+          rescue StandardError
+            nil
+          end
+
+          def default_settings
+            return ::Legion::Extensions::Llm.default_settings if
+              ::Legion::Extensions::Llm.respond_to?(:default_settings)
+
+            {}
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Fleet
+        class TokenError < StandardError; end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'time'
+
+require_relative 'settings'
+require_relative 'token_error'
+
+module Legion
+  module Extensions
+    module Llm
+      module Fleet
+        # Verifies responder-side fleet JWTs and prevents replay on provider nodes.
+        module TokenValidator
+          @seen_jtis = Concurrent::Map.new
+          @replay_mutex = Mutex.new
+
+          module_function
+
+          def validate!(token:, envelope:, record_replay: true)
+            raise TokenError, 'fleet token is required' if token.to_s.empty?
+
+            claims = symbolize_keys(jwt_module.verify(
+                                      token,
+                                      verification_key: signing_key,
+                                      issuer: issuer,
+                                      algorithm: algorithm,
+                                      verify_issuer: false
+                                    ))
+            validate_registered_claims!(claims)
+            validate_request_expiry!(claims)
+            validate_envelope_claims!(claims, symbolize_keys(envelope || {}))
+            record_replay ? reserve_replay!(claims[:jti]) : ensure_not_replayed!(claims[:jti])
+            claims
+          rescue TokenError
+            raise
+          rescue StandardError => e
+            raise TokenError, "fleet token verification failed: #{e.message}"
+          end
+
+          def reset_replay_cache!
+            @seen_jtis = Concurrent::Map.new
+            @replay_mutex = Mutex.new
+          end
+
+          def validate_registered_claims!(claims)
+            now = Time.now.to_i
+            raise TokenError, 'fleet token issuer mismatch' unless accepted_issuer?(claims[:iss])
+            raise TokenError, 'fleet token audience mismatch' unless claims[:aud].to_s == audience
+            if claims[:exp].nil? || claims[:exp].to_i + clock_skew_seconds <= now
+              raise TokenError,
+                    'fleet token expired'
+            end
+            if claims[:nbf].nil? || claims[:nbf].to_i - clock_skew_seconds > now
+              raise TokenError,
+                    'fleet token not yet valid'
+            end
+            raise TokenError, 'fleet token missing jti' if claims[:jti].to_s.empty?
+          end
+
+          def validate_request_expiry!(claims)
+            expires_at = claims[:expires_at]
+            raise TokenError, 'fleet request expires_at is required' if expires_at.to_s.empty?
+
+            expires = Time.iso8601(expires_at.to_s)
+            raise TokenError, 'fleet request expired' if expires + clock_skew_seconds <= Time.now.utc
+          rescue ArgumentError
+            raise TokenError, 'fleet request expires_at is invalid'
+          end
+
+          def validate_envelope_claims!(claims, envelope)
+            %i[
+              request_id correlation_id idempotency_key operation provider provider_instance
+              model reply_to message_context params caller trace_context timeout_seconds expires_at
+            ].each do |key|
+              expected = canonical_value(envelope[key])
+              actual = canonical_value(claims[key])
+              raise TokenError, "fleet token #{key} claim mismatch" unless actual == expected
+            end
+          end
+
+          def reserve_replay!(jti)
+            @replay_mutex.synchronize do
+              now = Time.now.to_i
+              purge_replay_cache_locked!(now)
+              existing = @seen_jtis[jti.to_s]
+              raise TokenError, 'fleet token replay detected' if active_replay?(existing, now)
+
+              @seen_jtis[jti.to_s] = replay_entry(:inflight, now)
+            end
+          end
+
+          def mark_replay!(jti)
+            @replay_mutex.synchronize do
+              @seen_jtis[jti.to_s] = replay_entry(:complete)
+            end
+          end
+
+          def release_replay!(jti)
+            @replay_mutex.synchronize do
+              entry = @seen_jtis[jti.to_s]
+              @seen_jtis.delete(jti.to_s) if entry.nil? || entry[:state] == :inflight
+            end
+          end
+
+          def ensure_not_replayed!(jti)
+            @replay_mutex.synchronize do
+              now = Time.now.to_i
+              purge_replay_cache_locked!(now)
+              raise TokenError, 'fleet token replay detected' if active_replay?(@seen_jtis[jti.to_s], now)
+            end
+          end
+
+          def purge_replay_cache!
+            @replay_mutex.synchronize { purge_replay_cache_locked!(Time.now.to_i) }
+          end
+
+          def purge_replay_cache_locked!(now)
+            @seen_jtis.each_pair { |jti, entry| @seen_jtis.delete(jti) unless active_replay?(entry, now) }
+          end
+
+          def active_replay?(entry, now)
+            entry && entry[:expires_at] > now
+          end
+
+          def replay_entry(state, now = Time.now.to_i)
+            { state: state, expires_at: now + replay_ttl_seconds }
+          end
+
+          def replay_ttl_seconds
+            ttl = Settings.value(:fleet, :auth, :replay_ttl_seconds, default: 600).to_i
+            ttl.positive? ? ttl : 600
+          end
+
+          def accepted_issuer?(value)
+            accepted_issuers.map(&:to_s).include?(value.to_s)
+          end
+
+          def accepted_issuers
+            issuers = Settings.value(:fleet, :auth, :accepted_issuers, default: [issuer])
+            issuers = [issuer] if Array(issuers).empty?
+            Array(issuers)
+          end
+
+          def clock_skew_seconds
+            Settings.value(:fleet, :auth, :max_clock_skew_seconds, default: 30).to_i
+          end
+
+          def issuer
+            Settings.value(:fleet, :auth, :issuer, default: 'legion-llm')
+          end
+
+          def audience
+            Settings.value(:fleet, :auth, :audience, default: 'lex-llm-fleet-worker')
+          end
+
+          def algorithm
+            Settings.value(:fleet, :auth, :algorithm, default: 'HS256')
+          end
+
+          def signing_key
+            if defined?(::Legion::Crypt) && ::Legion::Crypt.respond_to?(:cluster_secret)
+              return ::Legion::Crypt.cluster_secret
+            end
+
+            raise TokenError, 'no signing key available - Legion::Crypt not initialized'
+          rescue TokenError
+            raise
+          rescue StandardError => e
+            raise TokenError, "no signing key available: #{e.message}"
+          end
+
+          def jwt_module
+            return ::Legion::Crypt::JWT if defined?(::Legion::Crypt::JWT) && ::Legion::Crypt::JWT.respond_to?(:verify)
+
+            raise TokenError, 'Legion::Crypt::JWT.verify unavailable'
+          end
+
+          def symbolize_keys(hash)
+            return {} unless hash.respond_to?(:each)
+
+            hash.each_with_object({}) do |(key, value), result|
+              result[key.respond_to?(:to_sym) ? key.to_sym : key] = value
+            end
+          end
+
+          def canonical_value(value)
+            case value
+            when Hash
+              value.each_with_object({}) do |(key, child), result|
+                result[key.to_s] = canonical_value(child)
+              end.sort.to_h
+            when Array
+              value.map { |child| canonical_value(child) }
+            when Symbol
+              value.to_s
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+require_relative 'settings'
+require_relative 'token_validator'
+
+module Legion
+  module Extensions
+    module Llm
+      module Fleet
+        # Applies responder-side policy and dispatches a fleet request to a local lex-llm provider.
+        module WorkerExecution
+          class PolicyError < StandardError; end
+
+          @idempotency_keys = Concurrent::Map.new
+          @idempotency_mutex = Mutex.new
+
+          module_function
+
+          def call(envelope:, provider:)
+            claims = nil
+            idempotency_key = nil
+            claims = validate_identity!(envelope)
+            validate_policy!(envelope)
+            idempotency_key = validate_idempotency!(envelope)
+            response = dispatch_local_provider!(envelope: envelope, provider: provider)
+            mark_idempotency_success!(idempotency_key) if idempotency_key
+            TokenValidator.mark_replay!(claims[:jti]) if claims.is_a?(Hash)
+            response
+          rescue TokenError => e
+            release_idempotency!(idempotency_key) if idempotency_key
+            release_replay!(claims)
+            raise PolicyError, e.message
+          rescue StandardError
+            release_idempotency!(idempotency_key) if idempotency_key
+            release_replay!(claims)
+            raise
+          end
+
+          def validate_identity!(envelope)
+            return true unless responder_setting(:require_auth, default: true)
+
+            TokenValidator.validate!(token: envelope_value(envelope, :signed_token), envelope: envelope)
+          end
+
+          def validate_policy!(_envelope)
+            return true unless responder_setting(:require_policy, default: false)
+
+            raise PolicyError, 'fleet responder policy enforcement unavailable'
+          end
+
+          def validate_idempotency!(envelope)
+            return nil unless responder_setting(:require_idempotency, default: true)
+
+            key = envelope_value(envelope, :idempotency_key)
+            raise PolicyError, 'fleet idempotency_key is required' if key.to_s.empty?
+
+            reserve_idempotency_key!(key.to_s)
+            key.to_s
+          end
+
+          def dispatch_local_provider!(envelope:, provider:)
+            provider = provider.call(envelope) if provider.respond_to?(:call) && !provider.respond_to?(:chat)
+            operation = envelope_value(envelope, :operation).to_sym
+            params = normalize_hash(envelope_value(envelope, :params) || {})
+            model = envelope_value(envelope, :model)
+
+            case operation
+            when :chat
+              provider.chat(messages: params.fetch(:messages, []), model: model, **except(params, :messages))
+            when :stream
+              provider.stream_chat(messages: params.fetch(:messages, []), model: model, **except(params, :messages))
+            when :embed
+              provider.embed(text: params[:text], model: model, **except(params, :text))
+            when :count_tokens
+              provider.count_tokens(messages: params.fetch(:messages, []), model: model, **except(params, :messages))
+            else
+              raise PolicyError, "unsupported fleet operation: #{operation}"
+            end
+          end
+
+          def reset_idempotency_cache!
+            @idempotency_keys = Concurrent::Map.new
+            @idempotency_mutex = Mutex.new
+          end
+
+          def mark_idempotency_success!(key)
+            @idempotency_mutex.synchronize do
+              @idempotency_keys[key.to_s] = { state: :complete, expires_at: Time.now.to_i + idempotency_ttl_seconds }
+            end
+          end
+
+          def release_idempotency!(key)
+            @idempotency_mutex.synchronize { @idempotency_keys.delete(key.to_s) }
+          end
+
+          def release_replay!(claims)
+            return unless claims.is_a?(Hash) && claims[:jti]
+
+            TokenValidator.release_replay!(claims[:jti])
+          end
+
+          def purge_idempotency_cache!
+            @idempotency_mutex.synchronize do
+              now = Time.now.to_i
+              @idempotency_keys.each_pair do |key, entry|
+                @idempotency_keys.delete(key) if entry[:expires_at] <= now
+              end
+            end
+          end
+
+          def reserve_idempotency_key!(key)
+            @idempotency_mutex.synchronize do
+              now = Time.now.to_i
+              existing = @idempotency_keys[key]
+              raise PolicyError, 'duplicate fleet idempotency key' if existing && existing[:expires_at] > now
+
+              @idempotency_keys[key] = { state: :inflight, expires_at: now + idempotency_ttl_seconds }
+            end
+          end
+
+          def idempotency_ttl_seconds
+            ttl = responder_setting(:idempotency_ttl_seconds, default: 600).to_i
+            ttl.positive? ? ttl : 600
+          end
+
+          def responder_setting(key, default:)
+            value = Settings.value(:fleet, :responder, key, default: nil)
+            return auth_required? if key == :require_auth && value.nil?
+            return default if value.nil?
+
+            value
+          end
+
+          def auth_required?
+            Settings.value(:fleet, :auth, :require_signed_token, default: true) != false
+          end
+
+          def envelope_value(envelope, key)
+            return nil unless envelope.respond_to?(:key?)
+
+            envelope[key] || envelope[key.to_s]
+          end
+
+          def normalize_hash(hash)
+            return {} unless hash.respond_to?(:each)
+
+            hash.each_with_object({}) do |(key, value), result|
+              result[key.respond_to?(:to_sym) ? key.to_sym : key] = value
+            end
+          end
+
+          def except(hash, *keys)
+            exclusions = keys.map(&:to_sym)
+            hash.each_with_object({}) do |(key, value), result|
+              normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+              result[normalized_key] = value unless exclusions.include?(normalized_key)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.4.2'
+      VERSION = '0.4.3'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -129,7 +129,14 @@ module Legion
               audience: 'lex-llm-fleet-worker',
               algorithm: 'HS256',
               accepted_issuers: ['legion-llm'],
-              max_clock_skew_seconds: 30
+              max_clock_skew_seconds: 30,
+              replay_ttl_seconds: 600
+            },
+            responder: {
+              require_auth: nil,
+              require_policy: false,
+              require_idempotency: true,
+              idempotency_ttl_seconds: 600
             }
           }
         }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors:
 - LegionIO
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1'
+- !ruby/object:Gem::Dependency
+  name: legion-crypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.1
 - !ruby/object:Gem::Dependency
   name: legion-json
   requirement: !ruby/object:Gem::Requirement
@@ -229,7 +257,12 @@ files:
 - lib/legion/extensions/llm/fleet/default_exchange_reply.rb
 - lib/legion/extensions/llm/fleet/envelope_validation.rb
 - lib/legion/extensions/llm/fleet/protocol.rb
+- lib/legion/extensions/llm/fleet/provider_responder.rb
 - lib/legion/extensions/llm/fleet/publish_safety.rb
+- lib/legion/extensions/llm/fleet/settings.rb
+- lib/legion/extensions/llm/fleet/token_error.rb
+- lib/legion/extensions/llm/fleet/token_validator.rb
+- lib/legion/extensions/llm/fleet/worker_execution.rb
 - lib/legion/extensions/llm/image.rb
 - lib/legion/extensions/llm/message.rb
 - lib/legion/extensions/llm/mime_type.rb