rubino-agent 0.3.0

data/lib/rubino/llm/error_classifier.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "faraday"
+require "net/http"
+
+module Rubino
+  module LLM
+    # Why an API call failed — determines recovery strategy. A faithful subset
+    # of the reference FailoverReason: only the CORE reasons
+    # this gem can actually act on are ported. Provider-niche reasons
+    # (thinking_signature, llama_cpp_grammar, encrypted_content,
+    # long_context_tier, image_too_large, …) are intentionally dropped.
+    #
+    # The load-bearing default is `unknown → retryable`:
+    # an unclassifiable provider blip backs off and retries rather than aborting.
+    module FailoverReason
+      AUTH             = :auth              # 401/403 — invalid credential, don't retry as-is
+      BILLING          = :billing           # 402 / credit exhaustion — don't retry
+      RATE_LIMIT       = :rate_limit        # 429 — backoff then retry
+      OVERLOADED       = :overloaded        # 503/529 — provider overloaded, backoff
+      SERVER_ERROR     = :server_error      # 500/502 — internal server error, retry
+      TIMEOUT          = :timeout           # connection/read timeout / transport drop — retry
+      CONTEXT_OVERFLOW = :context_overflow  # context too large — compress, not failover
+      MODEL_NOT_FOUND  = :model_not_found   # 404 / invalid model — fallback to another model
+      FORMAT_ERROR     = :format_error      # 400 bad request — abort + fallback
+      UNKNOWN          = :unknown           # unclassifiable — retry with backoff
+
+      ALL = [
+        AUTH, BILLING, RATE_LIMIT, OVERLOADED, SERVER_ERROR, TIMEOUT,
+        CONTEXT_OVERFLOW, MODEL_NOT_FOUND, FORMAT_ERROR, UNKNOWN
+      ].freeze
+    end
+
+    # Structured classification of an API error with recovery hints, mirroring
+    # the reference ClassifiedError. The retry loop checks
+    # these hints instead of re-classifying the error itself.
+    #
+    # `should_rotate_credential` is recorded for fidelity but is a NO-OP in this
+    # gem: there is no credential pool to rotate. `should_fallback` is likewise
+    # advisory until the FallbackChain lands (Slice 7).
+    ClassifiedError = Data.define(
+      :reason, :status_code, :message,
+      :retryable, :should_compress, :should_rotate_credential, :should_fallback
+    ) do
+      def auth?
+        reason == FailoverReason::AUTH
+      end
+    end
+
+    # Centralized API-error classifier — the single source of truth for "is this
+    # error worth a retry?", replacing the adapter's boolean transient_error?.
+    # Port of the reference classify_api_error, reduced to
+    # the structural signals ruby_llm actually surfaces: a typed error class and
+    # the wrapped HTTP status. We do NOT port the giant message-pattern tables
+    # (billing/rate-limit/context phrase lists) — ruby_llm raises typed classes,
+    # so status + class carry the same information without the brittle matching.
+    # The one message-based branch kept is the MiniMax "unknown error" (code
+    # 999/1000) blip, which arrives statusless and must stay in the retryable
+    # `unknown` bucket.
+    module ErrorClassifier
+      # Transport-level drops that surface mid-request and never reach an HTTP
+      # status — always retryable. faraday-net_http re-raises IOError/EOFError
+      # (and friends) as Faraday::ConnectionFailed, the type we actually see for
+      # an upstream socket close; the rest are defensive.
+      STREAM_DROP_ERRORS = [
+        Faraday::ConnectionFailed, Faraday::TimeoutError,
+        Net::OpenTimeout, Net::ReadTimeout,
+        EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE
+      ].freeze
+
+      # ruby_llm 1.15 raises a typed error per HTTP status. Map the classes we
+      # can name directly; everything else falls through to status-based then
+      # unknown classification.
+      RETRYABLE_HTTP = ->(status) { status && (status >= 500 || status == 429) }.freeze
+
+      # Body/message fragments identifying a transient provider "unknown error"
+      # (MiniMax api_error 999/1000 on the Anthropic-compatible endpoint). Kept
+      # narrow and provider-blip-specific. Moved here from the adapter so the
+      # classifier is the single source of truth (folds Slice 0(b)).
+      UNKNOWN_PROVIDER_ERROR_PATTERNS = [
+        "unknown error",
+        "api_error 999",
+        "api_error 1000",
+        "\"code\":999",
+        "\"code\": 999",
+        "\"code\":1000",
+        "\"code\": 1000",
+        "code 999",
+        "code 1000"
+      ].freeze
+
+      # Last-resort transport-drop phrases for statusless errors that never
+      # surfaced as a typed transport class.
+      TRANSIENT_TRANSPORT_PATTERNS = [
+        "timeout", "timed out", "connection reset",
+        "connection refused", "broken pipe", "end of file reached"
+      ].freeze
+
+      # Local Ruby PROGRAMMING errors — unambiguous bugs in our own code (or a
+      # caller's), not provider/API blips. These must NEVER be retried: a retry
+      # storm would mask the bug behind backoff (the very thing that turned a
+      # mid-turn `NoMethodError` from the UI into three `llm.retry` warnings).
+      # They reach `classify` only because ModelCallRunner rescues StandardError
+      # broadly around the boundary call; the reference classify_api_error never sees
+      # them because it only ever runs at the API layer. So we short-circuit them
+      # to NON-retryable (reason stays :unknown) BEFORE the unknown→retryable
+      # fallback, surfacing the bug immediately. The set is curated by CLASS, not
+      # message: every entry is a clear local bug. RuntimeError is deliberately
+      # EXCLUDED — it is too generic (ruby_llm/providers raise it for transient
+      # conditions), so it stays on the message-based path and keeps its
+      # provider-blip retryability.
+      LOCAL_PROGRAMMING_ERRORS = [
+        NoMethodError, NameError, NoMatchingPatternError, NoMatchingPatternKeyError,
+        ArgumentError, TypeError, NotImplementedError, FrozenError,
+        LocalJumpError, ThreadError, FiberError
+      ].freeze
+
+      module_function
+
+      # Classify an error into a ClassifiedError with reason + recovery hints.
+      # Priority mirrors the reference pipeline: typed/transport class → HTTP status →
+      # statusless provider-unknown / transport → unknown (retryable default).
+      def classify(error)
+        status = http_status(error)
+
+        result = classify_missing_credential(error) ||
+                 classify_invalid_credential(error) ||
+                 classify_transport(error) ||
+                 classify_invalid_media(error) ||
+                 classify_typed(error) ||
+                 (status && classify_by_status(status, error)) ||
+                 classify_statusless(error)
+        return result if result
+
+        # A genuine local Ruby bug (NoMethodError, ArgumentError, …) is NOT a
+        # retryable provider blip — propagate it immediately instead of letting
+        # the unknown→retryable default mask it behind a backoff storm.
+        return result_for(FailoverReason::UNKNOWN, status, error, retryable: false) if local_programming_error?(error)
+
+        result_for(FailoverReason::UNKNOWN, status, error, retryable: true)
+      end
+
+      # Convenience: just the boolean the adapter's retry loop needs.
+      def retryable?(error)
+        classify(error).retryable
+      end
+
+      # ── classification stages ────────────────────────────────────────────
+
+      # A missing / unconfigured credential — raised BEFORE any HTTP call, so it
+      # carries no status and would otherwise fall through to the unknown→
+      # retryable default and trigger an ~80s retry storm that exits empty (#93).
+      # ruby_llm raises RubyLLM::ConfigurationError ("Missing configuration for
+      # OpenRouter: openrouter_api_key") when a provider's key is unset; our own
+      # adapter raises Rubino::Error ("Missing API key for provider ..."). A
+      # missing key is a credential problem the user must fix — classify it as a
+      # NON-retryable AUTH error so the runner surfaces it immediately.
+      MISSING_CREDENTIAL_PATTERNS = [
+        "missing configuration for",
+        "missing api key",
+        "no api key",
+        "api key is not set",
+        "_api_key"
+      ].freeze
+
+      def classify_missing_credential(error)
+        is_config_error =
+          defined?(RubyLLM::ConfigurationError) && error.is_a?(RubyLLM::ConfigurationError)
+        msg = error.message.to_s.downcase
+        return unless is_config_error || MISSING_CREDENTIAL_PATTERNS.any? { |p| msg.include?(p) }
+
+        result_for(FailoverReason::AUTH, http_status(error), error,
+                   retryable: false, should_rotate_credential: true, should_fallback: true)
+      end
+
+      # A PRESENT but INVALID credential rejected by the provider via a
+      # statusless / untyped error body (MiniMax's Anthropic-compatible
+      # endpoint says "login fail" with no 401), which used to fall through to
+      # the unknown→retryable default and burn ~60-90s of silent retries on a
+      # deterministic auth failure (#126). Same deal as a typed 401/403:
+      # NON-retryable AUTH, surfaced immediately. Patterns are the literal
+      # provider phrasings, kept narrow.
+      INVALID_CREDENTIAL_PATTERNS = [
+        "login fail",
+        "invalid api key",
+        "incorrect api key",
+        "invalid x-api-key",
+        "authentication_error",
+        "authentication failed"
+      ].freeze
+
+      def classify_invalid_credential(error)
+        msg = error.message.to_s.downcase
+        return unless INVALID_CREDENTIAL_PATTERNS.any? { |p| msg.include?(p) }
+
+        result_for(FailoverReason::AUTH, http_status(error), error,
+                   retryable: false, should_rotate_credential: true, should_fallback: true)
+      end
+
+      # Transport drops (Faraday::ConnectionFailed for the MiniMax EOF, read/
+      # connect timeouts, …) are retryable regardless of message — they never
+      # reach an HTTP status. STREAM_DROP_ERRORS lives on the adapter.
+      def classify_transport(error)
+        return unless STREAM_DROP_ERRORS.any? { |klass| error.is_a?(klass) }
+
+        result_for(FailoverReason::TIMEOUT, nil, error, retryable: true)
+      end
+
+      # Provider media/image validation rejections — a PERMANENT 4xx-class
+      # complaint about the attachment itself, which some providers (MiniMax
+      # Anthropic-compat) surface statusless so it used to fall through to the
+      # unknown→retryable default and burn the whole retry budget (~80s) on a
+      # bad image (#98). The same attachment fails identically on every retry,
+      # so fail fast. Patterns are the literal provider phrasings, kept narrow.
+      INVALID_MEDIA_PATTERNS = [
+        "media exceeds size limit",
+        "invalid image content",
+        "image: unknown format",
+        "could not process image"
+      ].freeze
+
+      def classify_invalid_media(error)
+        msg = error.message.to_s.downcase
+        return unless INVALID_MEDIA_PATTERNS.any? { |p| msg.include?(p) }
+
+        result_for(FailoverReason::FORMAT_ERROR, http_status(error), error,
+                   retryable: false, should_fallback: true)
+      end
+
+      # Typed ruby_llm errors we can name without a status lookup.
+      def classify_typed(error)
+        case error
+        when RubyLLM::ContextLengthExceededError
+          result_for(FailoverReason::CONTEXT_OVERFLOW, http_status(error), error,
+                     retryable: false, should_compress: true)
+        when RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError
+          result_for(FailoverReason::AUTH, http_status(error), error,
+                     retryable: false, should_rotate_credential: true, should_fallback: true)
+        when RubyLLM::PaymentRequiredError
+          result_for(FailoverReason::BILLING, http_status(error), error,
+                     retryable: false, should_rotate_credential: true, should_fallback: true)
+        when RubyLLM::RateLimitError
+          result_for(FailoverReason::RATE_LIMIT, http_status(error) || 429, error,
+                     retryable: true, should_rotate_credential: true, should_fallback: true)
+        when RubyLLM::OverloadedError, RubyLLM::ServiceUnavailableError
+          result_for(FailoverReason::OVERLOADED, http_status(error), error, retryable: true)
+        when RubyLLM::ServerError
+          result_for(FailoverReason::SERVER_ERROR, http_status(error), error, retryable: true)
+        end
+      end
+
+      # HTTP status classification with message-aware refinement, mirroring
+      # _classify_by_status (error_classifier.py:725) for the CORE reasons.
+      def classify_by_status(status, error)
+        case status
+        when 401, 403
+          result_for(FailoverReason::AUTH, status, error,
+                     retryable: false, should_rotate_credential: true, should_fallback: true)
+        when 402
+          result_for(FailoverReason::BILLING, status, error,
+                     retryable: false, should_rotate_credential: true, should_fallback: true)
+        when 404
+          # Generic 404 with no "model not found" signal is treated as unknown
+          # (retryable) per the reference: a misconfigured
+          # endpoint or proxy glitch shouldn't masquerade as a missing model.
+          if model_not_found?(error)
+            result_for(FailoverReason::MODEL_NOT_FOUND, status, error,
+                       retryable: false, should_fallback: true)
+          else
+            result_for(FailoverReason::UNKNOWN, status, error, retryable: true)
+          end
+        when 429
+          result_for(FailoverReason::RATE_LIMIT, status, error,
+                     retryable: true, should_rotate_credential: true, should_fallback: true)
+        when 503, 529
+          result_for(FailoverReason::OVERLOADED, status, error, retryable: true)
+        when 400
+          if context_overflow?(error)
+            result_for(FailoverReason::CONTEXT_OVERFLOW, status, error,
+                       retryable: false, should_compress: true)
+          elsif model_not_found?(error)
+            result_for(FailoverReason::MODEL_NOT_FOUND, status, error,
+                       retryable: false, should_fallback: true)
+          else
+            result_for(FailoverReason::FORMAT_ERROR, status, error,
+                       retryable: false, should_fallback: true)
+          end
+        else
+          if status >= 500
+            result_for(FailoverReason::SERVER_ERROR, status, error, retryable: true)
+          elsif status >= 400
+            result_for(FailoverReason::FORMAT_ERROR, status, error,
+                       retryable: false, should_fallback: true)
+          end
+        end
+      end
+
+      # No decisive status: the MiniMax "unknown error" blip and bare transport
+      # drops. A permanent 4xx never reaches here (returned above), so the
+      # provider-unknown net stays narrow — mirrors the reference unknown→retryable.
+      def classify_statusless(error)
+        msg = error.message.to_s.downcase
+        if UNKNOWN_PROVIDER_ERROR_PATTERNS.any? { |p| msg.include?(p) }
+          return result_for(FailoverReason::UNKNOWN, nil, error, retryable: true)
+        end
+        if TRANSIENT_TRANSPORT_PATTERNS.any? { |p| msg.include?(p) }
+          return result_for(FailoverReason::TIMEOUT, nil, error, retryable: true)
+        end
+
+        nil
+      end
+
+      # ── helpers ──────────────────────────────────────────────────────────
+
+      def result_for(reason, status, error, retryable:, should_compress: false,
+                     should_rotate_credential: false, should_fallback: false)
+        ClassifiedError.new(
+          reason: reason,
+          status_code: status,
+          message: error.respond_to?(:message) ? error.message.to_s[0, 500] : error.to_s[0, 500],
+          retryable: retryable,
+          should_compress: should_compress,
+          should_rotate_credential: should_rotate_credential,
+          should_fallback: should_fallback
+        )
+      end
+
+      # HTTP status from a typed RubyLLM::Error's wrapped Faraday response, or nil.
+      def http_status(error)
+        return unless error.respond_to?(:response) && error.response.respond_to?(:status)
+
+        status = error.response.status
+        status if status.is_a?(Integer)
+      end
+
+      CONTEXT_OVERFLOW_PATTERNS = [
+        "context length", "context window", "maximum context",
+        "token limit", "too many tokens", "prompt is too long", "max_tokens"
+      ].freeze
+
+      MODEL_NOT_FOUND_PATTERNS = [
+        "is not a valid model", "invalid model", "model not found",
+        "model_not_found", "does not exist", "no such model", "unknown model"
+      ].freeze
+
+      def context_overflow?(error)
+        return true if error.is_a?(RubyLLM::ContextLengthExceededError)
+
+        msg = error.message.to_s.downcase
+        CONTEXT_OVERFLOW_PATTERNS.any? { |p| msg.include?(p) }
+      end
+
+      def model_not_found?(error)
+        msg = error.message.to_s.downcase
+        MODEL_NOT_FOUND_PATTERNS.any? { |p| msg.include?(p) }
+      end
+
+      def local_programming_error?(error)
+        LOCAL_PROGRAMMING_ERRORS.any? { |klass| error.is_a?(klass) }
+      end
+    end
+  end
+end

data/lib/rubino/llm/fake_provider.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require_relative "adapter_response"
+require_relative "scenario_loader"
+require_relative "scenario_selector"
+
+module Rubino
+  module LLM
+    # Dev-only LLM adapter that replays a pre-recorded YAML scenario instead
+    # of hitting a real provider. The public surface mirrors RubyLLMAdapter
+    # so Agent::Loop can swap it in without further plumbing changes.
+    #
+    # Selection:
+    #   - model_id starting with "fake/" pins the scenario (suffix is the name).
+    #   - otherwise ScenarioSelector.resolve(last_user_message_content) chooses
+    #     one based on keyword routing, falling back to "happy-path".
+    #
+    # Streaming:
+    #   - "content"  → yield { type: :content,  text: ... }
+    #   - "thinking" → yield { type: :thinking, text: ... } (gated by
+    #                  display.show_reasoning, mirroring RubyLLMAdapter)
+    #   - "tool_call"     → buffered onto the final AdapterResponse (NOT yielded
+    #                  mid-stream; this matches RubyLLMAdapter and is what Loop
+    #                  expects).
+    #   - "delay_seconds" → cancellable sleep between events.
+    #   - unknown    → logged and skipped.
+    #
+    # Cancellation is checked between each event so Esc / Ctrl+C lands within
+    # one tick instead of waiting for the full scenario to drain.
+    class FakeProvider
+      attr_reader :model_id, :provider
+
+      DEFAULT_DELAY = 0.1
+
+      def initialize(model_id: nil, provider: nil, config: nil, ui: nil, event_bus: nil,
+                     tool_executor: nil, cancel_token: nil)
+        @config        = config || Rubino.configuration
+        @model_id      = model_id || @config.model_default || "fake/happy-path"
+        @provider      = provider || "fake"
+        @ui            = ui
+        @event_bus     = event_bus
+        @tool_executor = tool_executor
+        @cancel_token  = cancel_token
+      end
+
+      # LLM boundary entry: dispatch an LLM::Request to the
+      # streaming vs non-streaming transport. Mirrors RubyLLMAdapter#call so Loop
+      # can drive the fake through the same seam.
+      def call(request, &)
+        if request.stream?
+          stream(messages: request.messages, tools: request.tools,
+                 image_paths: request.image_paths, &)
+        else
+          chat(messages: request.messages, tools: request.tools,
+               image_paths: request.image_paths)
+        end
+      end
+
+      # Non-streaming entry point. Plays the scenario with a no-op block and
+      # returns the accumulated AdapterResponse.
+      def chat(messages:, tools: nil, response_format: nil, image_paths: nil)
+        stream(messages: messages, tools: tools, response_format: response_format,
+               image_paths: image_paths) { |_chunk| }
+      end
+
+      # Streaming entry point. Yields chunk hashes shaped exactly like
+      # RubyLLMAdapter:
+      #   { type: :content,  text: String }
+      #   { type: :thinking, text: String }
+      # Returns AdapterResponse with concatenated content, accumulated
+      # tool_calls, zero usage tokens, and the model id.
+      def stream(messages:, tools: nil, response_format: nil, image_paths: nil, &block)
+        # image_paths is accepted for signature parity with RubyLLMAdapter
+        # (Loop passes it on every call). FakeProvider plays back recorded
+        # scenarios verbatim, so it has nothing to do with attachments.
+        _ = image_paths
+        # If the runner is calling us back after a tool result, replaying the
+        # original scenario would re-emit the same tool_call indefinitely
+        # (FakeProvider has no inter-turn state). Detect the post-tool turn
+        # and emit a short closing message instead so the run terminates.
+        events =
+          if post_tool_turn?(messages)
+            closing_events
+          else
+            scenario_name = pick_scenario(messages)
+            ScenarioLoader.load(scenario_name, scenarios_dir: scenarios_dir_from_config)
+          end
+        # {{input}} is the only placeholder scenarios currently use. The reference
+        # had a richer template system, but in practice every scenario only
+        # interpolated the user input. Keep it simple until a scenario actually
+        # needs more (e.g. {{session_id}}).
+        @scenario_vars = { "input" => extract_last_user_text(messages).to_s }
+
+        buffered    = +""
+        tool_calls  = []
+
+        events.each do |event|
+          @cancel_token&.check!
+          dispatch_event(event, buffered: buffered, tool_calls: tool_calls, &block)
+        end
+
+        AdapterResponse.new(
+          content: buffered,
+          tool_calls: tool_calls,
+          input_tokens: 0,
+          output_tokens: 0,
+          model_id: @model_id
+        )
+      rescue Rubino::Interrupted
+        # Mirror RubyLLMAdapter: surface whatever was buffered as a clean
+        # AdapterResponse instead of swallowing the partial output.
+        AdapterResponse.new(
+          content: buffered || "",
+          tool_calls: tool_calls || [],
+          input_tokens: 0,
+          output_tokens: 0,
+          model_id: @model_id
+        )
+      end
+
+      def model_info
+        nil
+      end
+
+      def context_window
+        @config.model_context_length || 128_000
+      end
+
+      # Convenience: returns the scenario name FakeProvider would pick for
+      # this set of messages. Useful in specs and the doctor command.
+      def resolve_scenario(messages)
+        pick_scenario(messages)
+      end
+
+      private
+
+      def dispatch_event(event, buffered:, tool_calls:, &block)
+        type = event["type"] || event[:type]
+        case type.to_s
+        when "content"
+          text = interpolate(event["text"] || event[:text])
+          return if text.nil? || text.empty?
+
+          buffered << text
+          # Single buffered scenario turn ⇒ one content block ⇒ message_id 0,
+          # matching the uniform chunk contract every adapter emits.
+          safe_yield(block, type: :content, text: text, message_id: 0)
+        when "thinking"
+          text = interpolate(event["text"] || event[:text])
+          return if text.nil? || text.empty?
+          return if reasoning_hidden?
+
+          safe_yield(block, type: :thinking, text: text, message_id: 0)
+        when "tool_call"
+          tool_calls << build_tool_call(event)
+        when "delay_seconds"
+          seconds = event["value"] || event[:value] || DEFAULT_DELAY
+          cancellable_sleep(seconds.to_f)
+        else
+          log_safely(event: "llm.fake.unknown_event", type: type.to_s)
+        end
+      end
+
+      # Substitutes {{var}} placeholders using @scenario_vars. Returns the
+      # text unchanged when nothing matches so scenario authors can mix
+      # static and templated chunks freely.
+      def interpolate(text)
+        return text if text.nil? || text.empty? || @scenario_vars.nil?
+
+        @scenario_vars.reduce(text) { |acc, (k, v)| acc.gsub("{{#{k}}}", v.to_s) }
+      end
+
+      def extract_last_user_text(messages)
+        return "" unless messages.is_a?(Array)
+
+        last = messages.reverse.find { |m| (m[:role] || m["role"]).to_s == "user" }
+        return "" unless last
+
+        content = last[:content] || last["content"]
+        case content
+        when String then content
+        when Array
+          content.filter_map { |part| part.is_a?(Hash) ? (part[:text] || part["text"]) : nil }.join(" ")
+        else
+          content.to_s
+        end
+      end
+
+      def safe_yield(block, payload)
+        return unless block
+
+        block.call(payload)
+      rescue StandardError => e
+        # UI hiccups must not abort the stream. Mirror RubyLLMAdapter#emit.
+        log_safely(event: "llm.fake.emit_error", error: e.message, type: payload[:type])
+      end
+
+      def build_tool_call(event)
+        id        = event["id"]        || event[:id]        || "fake_call_#{SecureRandom.hex(4)}"
+        name      = event["name"]      || event[:name]      || event["tool"] || event[:tool]
+        arguments = event["arguments"] || event[:arguments] || {}
+
+        # Loop / ToolBridge expect string-keyed arguments. Normalise here so
+        # scenario authors can use either symbol or string keys in the YAML.
+        normalised_args =
+          if arguments.is_a?(Hash)
+            arguments.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+          else
+            arguments
+          end
+
+        { id: id, name: name, arguments: normalised_args }
+      end
+
+      def pick_scenario(messages)
+        if @model_id.to_s.start_with?("fake/")
+          suffix = @model_id.to_s.sub(%r{\Afake/}, "")
+          return suffix unless suffix.empty?
+        end
+        ScenarioSelector.resolve(last_user_message_content(messages))
+      end
+
+      # True when the runner is calling us back IN THE SAME TURN, right
+      # after a tool result — i.e. the very last message has role "tool".
+      # In a multi-turn session there are usually older tool results from
+      # previous runs in the history; those must NOT flip us into the
+      # closing-content path, only an immediately-preceding tool result
+      # does. Checking just the tail handles both cases.
+      def post_tool_turn?(messages)
+        return false unless messages.is_a?(Array)
+
+        last = messages.last
+        return false unless last.is_a?(Hash)
+
+        (last[:role] || last["role"]).to_s == "tool"
+      end
+
+      # A minimal closing turn: a short content chunk and nothing else. Returns
+      # the events array the scenario dispatcher expects.
+      def closing_events
+        [{ "type" => "content", "text" => "Done." }]
+      end
+
+      def last_user_message_content(messages)
+        return "" if messages.nil? || messages.empty?
+
+        last_user = messages.reverse.find do |m|
+          role = (m[:role] || m["role"]).to_s
+          role == "user"
+        end
+        last_user ||= messages.last
+        last_user[:content] || last_user["content"] || ""
+      end
+
+      def reasoning_hidden?
+        Config::ReasoningPrefs.mode(@config) == :hidden
+      end
+
+      # Pulls the override scenarios directory off the adapter's own config
+      # so tests (which build a one-off configuration via test_configuration)
+      # don't have to mutate the global Rubino.configuration.
+      def scenarios_dir_from_config
+        @config.dig("fake_provider", "scenarios_dir") ||
+          @config.dig("providers", "fake", "scenarios_dir")
+      rescue StandardError
+        nil
+      end
+
+      def cancellable_sleep(seconds)
+        return if seconds <= 0
+
+        deadline = monotonic_now + seconds
+        while (remaining = deadline - monotonic_now).positive?
+          @cancel_token&.check!
+          sleep([0.05, remaining].min)
+        end
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def log_safely(**fields)
+        Rubino.logger.warn(**fields)
+      rescue StandardError
+        # nothing to do
+      end
+    end
+  end
+end
+
+require "securerandom"