phronomy 0.29.0 → 0.30.0

data/lib/phronomy/generation/generator_verifier.rb

@@ -1,118 +1,203 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Implements the Generator-Verifier multi-agent coordination pattern.
-  #
-  # Agent completion is integrated through application-defined Workflow events;
-  # Workflow entry actions do not return or await Agent Tasks.
+  # Application-facing draft/review/retry composition.
+  # Owns its Agent instances; Tool authorization remains an application decision.
   class GeneratorVerifier
     DEFAULT_CONFIDENCE_THRESHOLD = 0.7
     DEFAULT_MAX_ITERATIONS = 3
 
-    Result = Struct.new(
-      :output,
-      :confidence,
-      :citations,
-      :iterations,
-      :review_notes,
-      :trusted
-    ) do
-      alias_method :trusted?, :trusted
-    end
+    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver,
+      :AgentOperation, :Invocation, :Protocol
 
-    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver, :AgentOperation
+    def self.open(**options)
+      raise ArgumentError, "GeneratorVerifier.open requires a block" unless block_given?
+      pipeline = new(**options)
+      value = nil
+      primary = nil
+      begin
+        returned = yield pipeline
+        value = returned.is_a?(Phronomy::TaskResult) ? returned.wait_result : returned
+      rescue Exception => error # rubocop:disable Lint/RescueException -- retain Interrupt during cleanup
+        primary = error
+        raise
+      ensure
+        begin
+          pipeline.release!
+        rescue => cleanup
+          failures = cleanup.is_a?(CleanupError) ? cleanup.failures : [{phase: nil, error: cleanup}]
+          raise CleanupError.new(pipeline: pipeline, failures: failures,
+            result: value, primary_error: primary), cause: primary || failures.first.fetch(:error)
+        end
+      end
+      value
+    end
 
-    def initialize(
-      draft_agent:,
-      review_agent:,
-      draft_prompt_builder:,
-      review_prompt_builder:,
-      draft_result_parser: nil,
-      review_result_parser: nil,
+    def initialize(draft_agent:, review_agent:, draft_prompt_builder:, review_prompt_builder:,
+      citation_schema: Protocol::DEFAULT_CITATION,
       confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
-      max_iterations: DEFAULT_MAX_ITERATIONS,
-      raise_if_untrusted: false
-    )
-      @draft_agent_class = draft_agent
-      @review_agent_class = review_agent
-      @draft_prompt_builder = draft_prompt_builder
-      @review_prompt_builder = review_prompt_builder
-      @draft_result_parser =
-        draft_result_parser || method(:default_parse_draft)
-      @review_result_parser =
-        review_result_parser || method(:default_parse_review)
+      max_iterations: DEFAULT_MAX_ITERATIONS, raise_if_unaccepted: false, on_approval: nil)
+      ensure_blocking_allowed!(:new)
+      unless confidence_threshold.is_a?(Numeric) && confidence_threshold.real? && confidence_threshold.to_f.finite? &&
+          (0.0..1.0).cover?(confidence_threshold)
+        raise ArgumentError, "confidence_threshold must be a finite number in 0..1"
+      end
+      unless max_iterations.is_a?(Integer) && max_iterations.positive?
+        raise ArgumentError, "max_iterations must be a positive Integer"
+      end
+      [draft_prompt_builder, review_prompt_builder, on_approval].compact.each do |callable|
+        raise ArgumentError, "builders and on_approval must be callable" unless callable.respond_to?(:call)
+      end
+      unless raise_if_unaccepted == true || raise_if_unaccepted == false
+        raise ArgumentError, "raise_if_unaccepted must be true or false"
+      end
+      @mutex = Mutex.new
+      @status = :idle
+      @operations = {}
+      @active = nil
       @threshold = confidence_threshold.to_f
-      @max_iterations = max_iterations.to_i
-      @raise_if_untrusted = raise_if_untrusted
-      @compiled_workflow = nil
+      @max_iterations = max_iterations
+      @raise_if_unaccepted = raise_if_unaccepted
+      @on_approval = on_approval
+      @draft_prompt_builder, @review_prompt_builder = draft_prompt_builder, review_prompt_builder
+      draft_schema = Protocol.draft(citation_schema)
+      begin
+        @operations[:draft] = AgentOperation.new(draft_agent, output_schema: draft_schema)
+        @operations[:review] = AgentOperation.new(review_agent, output_schema: Protocol::REVIEW)
+      rescue Exception => primary # rubocop:disable Lint/RescueException -- release partially acquired resources
+        begin
+          release!
+        rescue CleanupError => cleanup
+          raise CleanupError.new(pipeline: self, failures: cleanup.failures,
+            primary_error: primary), cause: primary
+        end
+        raise
+      end
     end
 
     def invoke(input, config: {})
-      state = compiled_workflow.invoke({input: input}, config: config)
-      confidence = combined_confidence(state)
-      trusted = confidence >= @threshold
-      result = Result.new(
-        output: state.output || state.draft.to_s,
-        confidence: confidence,
-        citations: state.citations,
-        iterations: state.iteration,
-        review_notes: state.review_notes,
-        trusted: trusted
-      )
-      if @raise_if_untrusted && !trusted
-        raise LowConfidenceError.new(result)
+      ensure_blocking_allowed!(:invoke)
+      invoke_async(input, config: config).wait_result
+    end
+
+    def invoke_async(input, config: {})
+      invocation = @mutex.synchronize do
+        assert_idle!
+        current = Invocation.new(config: config, on_approval: @on_approval,
+          on_finish: -> { @mutex.synchronize { @active = nil } })
+        @active = current
       end
-      result
+      invocation.follow(compiled_workflow.invoke_async({input: input}, config: invocation.config)) do |state|
+        build_result(state)
+      end
+    rescue => error
+      invocation ? invocation.fail_start(error) : Phronomy::TaskResult.failed(error)
+    end
+
+    # Notifications issued in the current invocation, including already-answered
+    # requests. This is not a replica of the Agent's durable approval state.
+    def approval_requests
+      @mutex.synchronize { @active }&.approvals || [].freeze
+    end
+
+    # Requests cancellation; this Task does not promise physical quiescence.
+    # Await the invocation separately, then use release! to check safe release.
+    def cancel_async
+      current, operations = @mutex.synchronize do
+        if @status == :releasing
+          raise Phronomy::Error.new("Generation is releasing", code: "generation.busy")
+        end
+        [@active, @operations.values.dup]
+      end
+      current&.cancel
+      tasks = operations.filter_map(&:cancel_async)
+      Phronomy::TaskResult.all_settled(tasks).map do |outcomes|
+        failure = outcomes.find(&:error)
+        raise failure.error if failure
+        !!current || !tasks.empty?
+      end
+    rescue => error
+      Phronomy::TaskResult.failed(error)
+    end
+
+    def release!
+      ensure_blocking_allowed!(:release!)
+      operations = @mutex.synchronize do
+        return false if @status == :released
+        if @active || @status == :releasing
+          raise Phronomy::Error.new("Generation is busy", code: "generation.busy")
+        end
+        @status = :releasing
+        @operations.dup
+      end
+      failures = []
+      operations.each do |phase, operation|
+        operation.unload!
+        @mutex.synchronize { @operations.delete(phase) }
+      rescue => error
+        failures << {phase: phase, error: error}
+      end
+      @mutex.synchronize { @status = failures.empty? ? :released : :release_failed }
+      unless failures.empty?
+        raise CleanupError.new(pipeline: self, failures: failures), cause: failures.first.fetch(:error)
+      end
+      @compiled_workflow = nil
+      true
     end
 
     private
 
-    def combined_confidence(state)
-      [
-        (state.self_score || 0.0).to_f,
-        (state.review_score || 0.0).to_f
-      ].min
+    def assert_idle!
+      if @status != :idle
+        raise Phronomy::Error.new("Generation is #{@status}", code: "generation.released")
+      end
+      raise Phronomy::Error.new("Generation is busy", code: "generation.busy") if @active
     end
 
-    def compiled_workflow
-      @compiled_workflow ||= build_workflow
+    def ensure_blocking_allowed!(operation)
+      if Phronomy::WaitPolicy.blocking_forbidden?
+        raise Phronomy::EventLoopReentrancyError, "GeneratorVerifier##{operation} cannot run on EventLoop"
+      end
     end
 
-    def build_workflow
-      WorkflowBuilder.new(
-        draft_agent: AgentOperation.new(@draft_agent_class),
-        review_agent: AgentOperation.new(@review_agent_class),
+    def compiled_workflow
+      @compiled_workflow ||= WorkflowBuilder.new(
+        draft_agent: @operations.fetch(:draft),
+        review_agent: @operations.fetch(:review),
         draft_prompt_builder: @draft_prompt_builder,
         review_prompt_builder: @review_prompt_builder,
-        draft_result_parser: @draft_result_parser,
-        review_result_parser: @review_result_parser,
-        threshold: @threshold,
-        max_iterations: @max_iterations
+        threshold: @threshold, max_iterations: @max_iterations,
+        start_operation: ->(operation, phase, input, listener:) {
+          @mutex.synchronize { @active }.start(operation, phase, input, listener: listener)
+        }
       ).build
     end
 
-    def default_parse_draft(text)
-      default_parser.parse(text)
-    rescue Phronomy::ParseError
-      {
-        answer: text.to_s,
-        confidence: 0.0,
-        citations: []
-      }
-    end
-
-    def default_parse_review(text)
-      default_parser.parse(text)
-    rescue Phronomy::ParseError
-      {
-        approved: false,
-        score: 0.0,
-        feedback: "Review output could not be parsed: #{text}"
-      }
+    def build_result(state)
+      interrupted = state.interrupted_phase
+      confidence = interrupted ? nil : [state.self_score, state.review_score].min
+      approved = interrupted ? nil : state.approved
+      accepted = Result.accepted?(confidence: confidence, confidence_threshold: @threshold, review_approved: approved)
+      result = Result.new(output: state.output, confidence: confidence,
+        confidence_threshold: @threshold, review_approved: approved,
+        citations: state.citations, iterations: state.iteration, review_notes: state.review_notes,
+        termination_reason: if interrupted
+                              state.pipeline_error ? "output_failed" : "tool_rejected"
+                            else
+                              (accepted ? "accepted" : "iteration_limit")
+                            end,
+        interrupted_phase: interrupted,
+        failure: output_failure_diagnostic(state.pipeline_error))
+      if @raise_if_unaccepted && !result.accepted?
+        raise UnacceptedResultError.new(result), cause: state.pipeline_error
+      end
+      result
     end
 
-    def default_parser
-      @default_parser ||= DefaultParser.build
+    def output_failure_diagnostic(error)
+      return nil unless error
+      Phronomy::Error.diagnostic(error).merge("execution_id" => error.execution_id,
+        "schema_digest" => error.schema_digest, "reason" => error.reason, "violations" => error.violations)
     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