phronomy 0.28.0 → 0.30.0

data/lib/phronomy/integrations/ordered_event_delivery.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module Integrations
+    # Optional transport helper. Payload meaning and destinations belong to the app.
+    # @api public
+    class OrderedEventDelivery
+      class ClosedError < Phronomy::Error; end
+      class OverflowError < Phronomy::Error; end
+
+      # Close and drain after the block, preserving its result or original failure.
+      # A flush timeout limits waiting, not an in-flight network request.
+      # @api public
+      def self.open(deliver:, capacity: 256, batch_size: 32, flush_timeout: 30, prepare_batch: nil)
+        raise ArgumentError, "block required" unless block_given?
+        reject_event_loop!
+        validate_timeout!(flush_timeout)
+        raise ArgumentError, "deliver must be callable" unless deliver.respond_to?(:call)
+        delivery = new(capacity: capacity, batch_size: batch_size, prepare_batch: prepare_batch, &deliver)
+        begin
+          yield delivery
+        ensure
+          primary = $!
+          begin
+            delivery.close_and_wait(timeout: flush_timeout)
+          rescue => secondary
+            if primary
+              report_secondary(secondary)
+            else
+              raise
+            end
+          end
+        end
+      end
+
+      def self.reject_event_loop!
+        if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError, "delivery flush cannot block EventLoop"
+        end
+      end
+
+      def self.validate_timeout!(timeout)
+        valid = timeout.nil? || (timeout.is_a?(Numeric) && timeout.finite? && timeout >= 0)
+        raise ArgumentError, "flush timeout must be a finite nonnegative number or nil" unless valid
+      end
+
+      def self.report_secondary(error)
+        Phronomy.configuration.logger&.error("[OrderedEventDelivery] secondary delivery failure: #{error.class}: #{error.message}")
+      rescue
+        # Diagnostic reporting must not replace the primary application error.
+        nil
+      end
+      private_class_method :reject_event_loop!, :validate_timeout!, :report_secondary
+
+      # Construction does not start a worker or create a pool.
+      # @api public
+      def initialize(capacity: 256, batch_size: 32, prepare_batch: nil, &deliver)
+        raise ArgumentError, "deliver block required" unless deliver
+        unless capacity.is_a?(Integer) && capacity.positive? && batch_size.is_a?(Integer) && batch_size.positive?
+          raise ArgumentError, "capacity and batch_size must be positive Integers"
+        end
+        raise ArgumentError, "prepare_batch must be callable" if prepare_batch && !prepare_batch.respond_to?(:call)
+        @capacity, @batch_size = capacity, batch_size
+        @prepare_batch, @deliver = prepare_batch, deliver
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @queue = []
+        @accepting = true
+        @worker = nil
+        @failure = nil
+      end
+
+      # Snapshot plain data; admission order is the queue insertion order.
+      # Capacity counts queued payloads, excluding the active batch.
+      # @api public
+      def publish(payload)
+        value = immutable_copy(payload)
+        ticket = @mutex.synchronize do
+          raise @failure if @failure
+          raise ClosedError.new("event delivery closed", code: "delivery.closed") unless @accepting
+          raise OverflowError.new("event delivery queue full", code: "delivery.capacity_exceeded") if @queue.length >= @capacity
+          @queue << value
+          next nil if @worker
+          @worker = {started: false}
+        end
+        start_drain(ticket) if ticket
+        error = @mutex.synchronize { @failure }
+        raise error if error
+        self
+      rescue => error
+        # Listener dispatch can log an exception and continue. Retain the failure
+        # for close while continuing to drain already accepted work if possible.
+        @mutex.synchronize do
+          @failure ||= error
+          @accepting = false
+        end
+        raise
+      end
+
+      # External callers only. Concurrent close calls observe the same drain.
+      # Timeout does not abort a network operation or settle the worker's result.
+      # @api public
+      def close_and_wait(timeout: nil)
+        self.class.send(:reject_event_loop!)
+        self.class.send(:validate_timeout!, timeout)
+        deadline = timeout && monotonic_now + timeout
+        @mutex.synchronize do
+          @accepting = false
+          while @worker
+            remaining = deadline && deadline - monotonic_now
+            raise Phronomy::TimeoutError, "event delivery flush timed out" if remaining && remaining <= 0
+            @condition.wait(@mutex, remaining)
+          end
+          raise @failure if @failure
+        end
+        self
+      end
+
+      private
+
+      def start_drain(ticket)
+        Phronomy::Blocking.call_async do
+          started = @mutex.synchronize do
+            ticket[:started] = true if @worker.equal?(ticket)
+          end
+          if started
+            begin
+              drain(ticket)
+            rescue => error
+              fail_worker(ticket, error)
+            ensure
+              finish_worker(ticket)
+            end
+          end
+        end.on_complete do |_value, error|
+          fail_worker(ticket, error) if error
+        end
+      rescue => error
+        fail_worker(ticket, error)
+      end
+
+      def drain(ticket)
+        loop do
+          batch = @mutex.synchronize do
+            if @queue.empty?
+              # Publish must observe queue emptiness and ownership release together.
+              release_worker(ticket)
+              nil
+            else
+              @queue.shift(@batch_size)
+            end
+          end
+          return unless batch
+          prepared = @prepare_batch ? @prepare_batch.call(batch.freeze) : batch
+          raise ArgumentError, "prepare_batch must return an Array" unless prepared.is_a?(Array)
+          immutable_copy(prepared).each { |payload| @deliver.call(payload) }
+        end
+      end
+
+      def fail_worker(ticket, error)
+        @mutex.synchronize do
+          @failure ||= error
+          @accepting = false
+          @queue.clear
+          # Logical cancellation can precede physical worker exit. Keep waiting
+          # for a started delivery; never mistake settled TaskResult for exit.
+          release_worker(ticket) unless ticket[:started]
+        end
+      end
+
+      def finish_worker(ticket)
+        @mutex.synchronize { release_worker(ticket) }
+      end
+
+      def release_worker(ticket)
+        return unless @worker.equal?(ticket)
+        @worker = nil
+        @condition.broadcast
+      end
+
+      def immutable_copy(value, ancestors = {})
+        case value
+        when Hash, Array
+          raise ArgumentError, "event payload must contain acyclic plain data" if ancestors[value.object_id]
+          path = ancestors.merge(value.object_id => true)
+          if value.is_a?(Hash)
+            value.to_h { |key, child| [immutable_copy(key, path), immutable_copy(child, path)] }.freeze
+          else
+            value.map { |child| immutable_copy(child, path) }.freeze
+          end
+        when String then value.dup.freeze
+        when Integer, Symbol, TrueClass, FalseClass, NilClass then value
+        when Float
+          raise ArgumentError, "event payload numbers must be finite" unless value.finite?
+          value
+        else
+          raise ArgumentError, "event payload must contain plain data: #{value.class}"
+        end
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/backends/lm_studio.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "ruby_llm"
+
+module Phronomy
+  module LLMAdapter
+    # Explicit LM Studio / RubyLLM connection. Does not alter the default backend.
+    # Identifies a narrowly specified provider response, not exception messages.
+    # @api public
+    class LMStudio < RubyLLM
+      PARSE_FAILURE_CODE = "llm.provider_output_parse_failed"
+      ENGINE_PREFIX = "Engine protocol predict stream returned an error: "
+      ENGINE_MESSAGE = "The model produced output that does not match the expected peg-native format"
+      private_constant :ENGINE_PREFIX, :ENGINE_MESSAGE
+
+      # SDK retries are disabled in a private configuration snapshot. This also
+      # disables ordinary 429/500 retries for this selected backend; the generic
+      # RubyLLM backend is unchanged. Retries below are opt-in and bounded to one.
+      # on_attempt receives safe diagnostic fields, never a prompt or raw body.
+      # @api public
+      def initialize(context:, max_parse_retries: 0, on_attempt: nil)
+        raise ArgumentError, "context must be a RubyLLM::Context" unless context.is_a?(::RubyLLM::Context)
+        unless max_parse_retries.is_a?(Integer) && (0..1).cover?(max_parse_retries)
+          raise ArgumentError, "max_parse_retries must be 0 or 1"
+        end
+        raise ArgumentError, "on_attempt must be callable" if on_attempt && !on_attempt.respond_to?(:call)
+
+        config = context.config.dup
+        unless config.openai_protocol == :chat_completions
+          raise ArgumentError, "LMStudio requires the Chat Completions protocol"
+        end
+        config.max_retries = 0
+        super(context: ::RubyLLM::Context.new(config.freeze))
+        @max_parse_retries = max_parse_retries
+        @on_attempt = on_attempt
+      end
+
+      protected
+
+      def perform_complete(request, cancellation_token:)
+        require_openai!(request)
+        attempt = 0
+        begin
+          cancellation_token&.raise_if_cancelled!
+          attempt += 1
+          response = super
+        rescue TransportError => error
+          retrying = error.code == PARSE_FAILURE_CODE && retryable_request?(request) &&
+            attempt <= @max_parse_retries
+          record_attempt(attempt, error: error, retrying: retrying)
+          raise unless retrying
+
+          retry
+        end
+        record_attempt(attempt)
+        response
+      end
+
+      def perform_stream(request, cancellation_token:, &block)
+        require_openai!(request)
+        response = super
+        record_attempt(1)
+        response
+      rescue TransportError => error
+        record_attempt(1, error: error)
+        raise
+      end
+
+      private
+
+      def require_openai!(request)
+        unless request.model_config["provider"] == "openai"
+          raise ArgumentError, "LMStudio requires provider: openai"
+        end
+      end
+
+      def retryable_request?(request)
+        request.model_config["model"] == "openai/gpt-oss-20b" &&
+          request.tools.empty? && request.response_schema.nil? &&
+          request.messages.none? { |message| message.role == :tool || !message.tool_calls.empty? }
+      end
+
+      def raise_provider_error(error)
+        if provider_parse_failure?(error)
+          raise TransportError.new(error.message, code: PARSE_FAILURE_CODE), cause: error
+        end
+        super
+      end
+
+      def provider_parse_failure?(error)
+        return false unless error.is_a?(::RubyLLM::BadRequestError) || error.is_a?(::RubyLLM::ServerError)
+
+        response = error.response
+        return false unless response && [400, 500].include?(response.status)
+
+        body = response.body
+        body = JSON.parse(body) if body.is_a?(String)
+        return false unless body.is_a?(Hash)
+
+        detail = body["error"]
+        # Known engine fields can appear directly or inside LM Studio's exact
+        # wrapper. These HTTP envelopes are synthetic test fixtures until a live
+        # failure is captured; unknown envelopes deliberately remain unclassified.
+        if detail.is_a?(Hash) && detail["message"].is_a?(String) && detail["message"].start_with?(ENGINE_PREFIX)
+          detail = detail["message"]
+        end
+        if detail.is_a?(String) && detail.start_with?(ENGINE_PREFIX)
+          detail = JSON.parse(detail.delete_prefix(ENGINE_PREFIX))
+        end
+        detail.is_a?(Hash) && detail["code"] == 500 &&
+          detail["type"] == "server_error" && detail["message"] == ENGINE_MESSAGE
+      rescue JSON::ParserError
+        false
+      end
+
+      def record_attempt(attempt, error: nil, retrying: false)
+        provider = error&.cause
+        status = provider.response&.status if provider.is_a?(::RubyLLM::Error)
+        event = {attempt: attempt, outcome: error ? :failed : :succeeded,
+                 code: error&.code, http_status: status, retrying: retrying}.freeze
+        warn_attempt(event) if error
+        @on_attempt&.call(event)
+      rescue
+        # Diagnostics never replace the operation result or its original cause.
+        nil
+      end
+
+      def warn_attempt(event)
+        warning = "[Phronomy::LLMAdapter::LMStudio] attempt=#{event[:attempt]} " \
+          "code=#{event[:code] || "transport_error"} http_status=#{event[:http_status] || "unknown"} retrying=#{event[:retrying]}"
+        logger = @sdk_context.config.logger
+        logger ? logger.warn(warning) : Kernel.warn(warning)
+      rescue
+        # A broken logger does not prevent the optional observer from running.
+        nil
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/backends/ruby_llm.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "ruby_llm"
+require "faraday"
+require "digest"
 
 module Phronomy
   module LLMAdapter
@@ -8,6 +10,13 @@ module Phronomy
     # the backend boundary; a Tool definition never contains executable work.
     # @api public
     class RubyLLM < Base
+      # An optional RubyLLM context keeps endpoint/transport settings local to
+      # this concrete backend. The default still reads the SDK global settings.
+      # @api public
+      def initialize(context: nil)
+        @sdk_context = context || ::RubyLLM
+      end
+
       ToolsRequested = Class.new(StandardError) do
         attr_reader :message_value
         def initialize(message_value)
@@ -53,6 +62,8 @@ module Phronomy
       def execute_request(request, token)
         callback_error = nil
         chat = build_chat(request)
+        capture = StructuredResponseCapture.new
+        capture.bind(chat) if request.response_schema && block_given?
         token&.raise_if_cancelled!
         chat.after_message do |message|
           raise ToolsRequested.new(message) if message.tool_call?
@@ -72,11 +83,14 @@ module Phronomy
         else
           request.message ? chat.ask(request.message) : chat.complete
         end
-        response_value(response)
+        response_value(response, capture: capture, chat: chat)
       rescue ToolsRequested => requested
-        response_value(requested.message_value)
+        response_value(requested.message_value, capture: capture, chat: chat)
       rescue => error
         raise error if error.equal?(callback_error)
+        if request.response_schema && unsupported_schema_error?(error)
+          raise StructuredOutputUnsupportedError, "Provider rejected native structured output"
+        end
         raise_provider_error(error)
       end
 
@@ -90,17 +104,56 @@ module Phronomy
         elsif config.key?("assume_model_exists")
           options[:assume_model_exists] = config["assume_model_exists"]
         end
-        chat = ::RubyLLM.chat(**options)
+        chat = @sdk_context.chat(**options)
+        if request.response_schema
+          validate_structured_support!(request, chat)
+          chat.with_schema(request.response_schema)
+        end
         chat.with_temperature(config["temperature"]) if config["temperature"]
         chat.with_max_output_tokens(config["max_output_tokens"]) if config["max_output_tokens"]
         if request.system
           chat.with_instructions(request.system, cache_until_here: config["cache_instructions"])
         end
         request.tools.each { |definition| chat.with_tools(tool_declaration(definition)) }
-        request.messages.each { |value| chat.messages << sdk_message(value) }
+        request.messages.each { |value| chat.messages << sdk_message(value, chat: chat) }
         chat
       end
 
+      def validate_structured_support!(request, chat)
+        provider = chat.model.provider.to_s
+        unless %w[openai azure anthropic gemini ollama].include?(provider)
+          raise StructuredOutputUnsupportedError, "Native schema transport has not been verified for #{provider}"
+        end
+        begin
+          known = ::RubyLLM.models.find(chat.model.id, provider: provider)
+        rescue ::RubyLLM::ModelNotFoundError
+          known = nil
+        end
+        if known && !known.supports?(:structured_output)
+          raise StructuredOutputUnsupportedError, "Selected model does not support structured output"
+        end
+        if known && !request.tools.empty? && !known.supports?(:function_calling)
+          raise StructuredOutputUnsupportedError, "Selected model cannot combine the requested schema and Tools"
+        end
+      end
+
+      def unsupported_schema_error?(error)
+        return false unless error.is_a?(::RubyLLM::BadRequestError)
+        response = error.response if error.respond_to?(:response)
+        body = response.respond_to?(:body) ? response.body : response
+        body = JSON.parse(body) if body.is_a?(String)
+        detail = body.is_a?(Hash) ? body["error"] : nil
+        return true if detail == "Cannot combine structured output constraints with lazy grammar"
+        return false unless detail.is_a?(Hash)
+        schema_field = /response_format|output_config\.format|responseJsonSchema|response_schema|text\.format/
+        message = detail["message"].to_s
+        detail["param"].to_s.match?(/response_format|schema|text\.format|output_config/) ||
+          %w[unsupported_response_format unsupported_schema invalid_json_schema].include?(detail["code"]) ||
+          (message.match?(schema_field) && message.match?(/unsupported|not supported|invalid|unknown/i))
+      rescue JSON::ParserError
+        false
+      end
+
       def tool_declaration(definition)
         name = definition.fetch("name")
         klass = Class.new(::RubyLLM::Tool) do
@@ -115,7 +168,7 @@ module Phronomy
         klass
       end
 
-      def sdk_message(value)
+      def sdk_message(value, chat:)
         calls = value.tool_calls.to_h do |call|
           [call.id, ::RubyLLM::ToolCall.new(id: call.id, name: call.name,
             arguments: call.arguments, thought_signature: call.metadata["thought_signature"])]
@@ -125,10 +178,10 @@ module Phronomy
         content = "" if value.role == :assistant && content.nil? && !calls.empty?
         ::RubyLLM::Message.new(role: value.role, content: content,
           tool_calls: calls.empty? ? nil : calls, tool_call_id: value.tool_call_id,
-          model: value.metadata["model_id"])
+          model: value.metadata["model_id"], **sdk_continuation(value, chat))
       end
 
-      def response_value(message)
+      def response_value(message, chat:, capture: nil)
         unless message.respond_to?(:content) && message.respond_to?(:role) && message.role.to_sym == :assistant
           raise InvalidResultError, "provider returned an invalid assistant message"
         end
@@ -150,11 +203,79 @@ module Phronomy
         )
         metadata = {}
         metadata["model_id"] = message.model if message.respond_to?(:model) && message.model
-        Response.new(content: message.content, tool_calls: calls, usage: usage, metadata: metadata)
+        continuation = continuation_metadata(message, chat)
+        metadata["ruby_llm_continuation"] = continuation if continuation
+        reason = message.finish_reason if message.respond_to?(:finish_reason)
+        raw = message.raw if message.respond_to?(:raw)
+        raw = raw.body if raw.respond_to?(:body)
+        raw = {} unless raw.is_a?(Hash)
+        raw_reason = capture&.raw_finish_reason || raw.dig("choices", 0, "finish_reason") || raw["stop_reason"] ||
+          raw.dig("candidates", 0, "finishReason") || reason&.to_s
+        refusal = capture&.refusal || raw.dig("choices", 0, "message", "refusal")
+        if raw["output"].is_a?(Array)
+          refusals = raw["output"].flat_map { |item| Array(item["content"]) }
+            .select { |item| item["type"] == "refusal" }.map { |item| item["refusal"] }
+          refusal ||= refusals.join("\n") unless refusals.empty?
+        end
+        refusal ||= message.content.to_s if raw_reason == "refusal"
+        normalized = refusal ? :refusal : {stop: :stop, tool_calls: :tool_calls,
+                                           max_tokens: :length, length: :length, content_filter: :content_filter, refusal: :refusal}.fetch(reason&.to_sym, :unknown)
+        metadata["raw_finish_reason"] = raw_reason if raw_reason
+        Response.new(content: message.content, tool_calls: calls, usage: usage, metadata: metadata,
+          finish_reason: normalized, refusal: refusal)
       rescue ArgumentError, TypeError, NoMethodError => error
         raise InvalidResultError, "malformed provider response: #{error.message}"
       end
 
+      # Only this concrete backend interprets the envelope. Agent persists and
+      # materializes Message metadata as immutable JSON, without SDK knowledge.
+      def continuation_metadata(message, chat)
+        thinking = message.thinking if message.respond_to?(:thinking)
+        raw = message.raw_reasoning if message.respond_to?(:raw_reasoning)
+        return unless thinking || raw
+
+        {
+          "version" => 1,
+          "scope" => continuation_scope(chat),
+          "thinking" => thinking && {"text" => thinking.text, "signature" => thinking.signature}.compact,
+          "raw_reasoning" => raw
+        }.compact
+      end
+
+      def sdk_continuation(value, chat)
+        return {} unless value.metadata.key?("ruby_llm_continuation")
+
+        state = value.metadata["ruby_llm_continuation"]
+        unless state.is_a?(Hash) && state["version"] == 1 && state["scope"] == continuation_scope(chat)
+          raise Phronomy::ConfigurationError,
+            "RubyLLM continuation metadata is incompatible with the selected model, provider, endpoint, protocol or format version"
+        end
+        thinking = state["thinking"]
+        valid_thinking = thinking.nil? || (thinking.is_a?(Hash) && (thinking.keys - %w[text signature]).empty? &&
+          (thinking["text"].nil? || thinking["text"].is_a?(String)))
+        unless value.role == :assistant && valid_thinking &&
+            (state.keys - %w[version scope thinking raw_reasoning]).empty?
+          raise InvalidResultError, "malformed RubyLLM continuation metadata"
+        end
+        # Reconstitute SDK-owned values only at the backend boundary. Do not
+        # promote arbitrary Message metadata to SDK options or provider params.
+        {thinking: thinking, raw_reasoning: state["raw_reasoning"]}
+      end
+
+      def continuation_scope(chat)
+        provider = chat.provider
+        protocol = provider.protocols.key(provider.protocol_for(chat.model))
+        unless protocol
+          raise Phronomy::ConfigurationError, "RubyLLM continuation requires an identifiable protocol"
+        end
+        {
+          "provider" => chat.model.provider.to_s,
+          "model" => chat.model.id,
+          "protocol" => protocol.to_s,
+          "endpoint_sha256" => Digest::SHA256.hexdigest(provider.api_base.to_s)
+        }
+      end
+
       def stream_value(chunk)
         raise InvalidResultError, "provider returned an invalid stream chunk" unless chunk.respond_to?(:content)
         StreamChunk.new(content: chunk.content)
@@ -162,8 +283,9 @@ module Phronomy
         raise InvalidResultError, "malformed provider chunk: #{error.message}"
       end
 
-      # Translate SDK errors only. Cancellation and callback failures retain
-      # identity; raising here preserves the original provider exception cause.
+      # Translate identified SDK/HTTP failures only. Callback failures bypass
+      # this method even when their class is a transport error. Classification
+      # preserves cause; it does not promise that replay would be safe.
       def raise_provider_error(error)
         case error
         when ::RubyLLM::RateLimitError
@@ -172,8 +294,8 @@ module Phronomy
           raise Phronomy::LLMAdapter::AuthenticationError, error.message
         when ::RubyLLM::ContextLengthExceededError
           raise Phronomy::LLMAdapter::ContextLengthError, error.message
-        when ::RubyLLM::Error
-          raise Phronomy::LLMAdapter::TransportError, error.message
+        when ::RubyLLM::Error, ::Faraday::TimeoutError, ::Faraday::ConnectionFailed
+          raise Phronomy::LLMAdapter::TransportError.new(error.message), cause: error
         else
           raise error
         end

data/lib/phronomy/llm_adapter/backends/structured_response_capture.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # RubyLLM 2.0 drops refusal fields when creating streaming Chunk values.
+    # Use its Protocol subclass seam on this operation's Provider only; never
+    # patch global SDK classes or retain an application callback across calls.
+    # @api private
+    class StructuredResponseCapture
+      attr_reader :refusal, :raw_finish_reason
+
+      def bind(chat)
+        capture = self
+        protocols = chat.provider.protocols.transform_values do |base|
+          Class.new(base) do
+            define_method(:build_chunk) do |data|
+              capture.record(data)
+              super(data)
+            end
+          end
+        end.freeze
+        chat.provider.define_singleton_method(:protocols) { protocols }
+      end
+
+      def record(data)
+        choice = data.dig("choices", 0) || {}
+        @raw_finish_reason = choice["finish_reason"] || data.dig("delta", "stop_reason") ||
+          data.dig("candidates", 0, "finishReason") || @raw_finish_reason
+        delta = choice.dig("delta", "refusal")
+        delta ||= data["delta"] if data["type"] == "response.refusal.delta"
+        @refusal = (@refusal || "") + delta if delta.is_a?(String)
+        final = data["response"]
+        return unless final.is_a?(Hash)
+        refusals = Array(final["output"]).flat_map { |item| Array(item["content"]) }
+          .select { |item| item["type"] == "refusal" }.map { |item| item["refusal"] }
+        @refusal = refusals.join("\n") unless refusals.empty?
+        @raw_finish_reason = final.dig("incomplete_details", "reason") || final["status"] || @raw_finish_reason
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/message.rb

@@ -7,6 +7,10 @@ require_relative "../tool/call_request"
 module Phronomy
   module LLMAdapter
     # Provider-independent conversation value, with no executable capabilities.
+    # Metadata is immutable JSON. Backend-owned continuation values travel with
+    # the message through Agent persistence/import; only their owning backend
+    # interprets their format and replay compatibility. They grant no authority
+    # and are not answer content or arbitrary provider request options.
     # @api public
     class Message
       attr_reader :role, :content, :tool_calls, :tool_call_id, :metadata

data/lib/phronomy/llm_adapter/request.rb

@@ -7,10 +7,10 @@ module Phronomy
     # Immutable input for one model turn, including inert Tool definitions.
     # @api public
     class Request
-      attr_reader :model_config, :system, :messages, :tools, :message
+      attr_reader :model_config, :system, :messages, :tools, :message, :response_schema
 
       # @api public
-      def initialize(model_config: {}, system: nil, messages: [], tools: [], message: nil)
+      def initialize(model_config: {}, system: nil, messages: [], tools: [], message: nil, response_schema: nil)
         if !(model_config.is_a?(Hash) && (system.nil? || system.is_a?(String)) && (message.nil? || message.is_a?(String)))
           raise ArgumentError, "invalid LLM request configuration or text"
         end
@@ -36,6 +36,11 @@ module Phronomy
         names = normalized_tools.map { |tool| tool.fetch("name") }
         raise ArgumentError, "duplicate Tool definition name" unless names.uniq == names
         config = normalize_keys(model_config)
+        @response_schema = response_schema.nil? ? nil : Phronomy::Values::Immutable.json(response_schema)
+        if @response_schema && !@response_schema.is_a?(Hash)
+          raise ArgumentError, "response_schema must be a JSON object or nil"
+        end
+        reject_schema_options!(config) if @response_schema
         Phronomy::Values::Immutable.validate_canonical_json!(config, label: "LLM model configuration")
         max = config["max_output_tokens"]
         if !max.nil? && (!max.is_a?(Integer) || max <= 0)
@@ -64,6 +69,16 @@ module Phronomy
 
       private
 
+      def reject_schema_options!(value)
+        return unless value.is_a?(Hash)
+        value.each do |key, child|
+          if %w[schema output_schema response_schema response_format responseJsonSchema responseSchema].include?(key.to_s)
+            raise ArgumentError, "model configuration cannot override response_schema"
+          end
+          reject_schema_options!(child)
+        end
+      end
+
       def normalize_keys(value)
         value.each_with_object({}) do |(key, child), result|
           unless key.is_a?(String) || key.is_a?(Symbol)