robot_lab 0.2.8 → 0.3.0

data/examples/29_ractor_tools.rb

@@ -46,7 +46,7 @@ end
 class WordStatsTool < TextTool
   description "Count words, sentences, and average word length"
 
-  param :text, type: :string, desc: "Text to analyze"
+  parameter :text, type: :string, description: "Text to analyze"
 
   def execute(text:)
     words     = text.scan(/\b\w+\b/)
@@ -61,7 +61,7 @@ end
 class ReadabilityTool < TextTool
   description "Estimate words-per-sentence and long-word density"
 
-  param :text, type: :string, desc: "Text to analyze"
+  parameter :text, type: :string, description: "Text to analyze"
 
   def execute(text:)
     words      = text.scan(/\b\w+\b/)
@@ -86,7 +86,7 @@ class HeavyDigestTool < TextTool
 
   ROUNDS = 500_000
 
-  param :text, type: :string, desc: "Seed text"
+  parameter :text, type: :string, description: "Seed text"
 
   def execute(text:)
     digest = text
@@ -102,7 +102,7 @@ class RequestCounterTool < RobotLab::Tool
 
   @@hits = 0   # mutable class variable — Ractor workers cannot access this
 
-  param :text, type: :string, desc: "Text to count"
+  parameter :text, type: :string, description: "Text to count"
 
   def execute(text:)
     @@hits += 1

data/examples/30_ractor_network.rb

@@ -190,7 +190,7 @@ puts
 
 unless ENV["RUN_LIVE"]
   section "Part 3: Live LLM Run"
-  puts "   Set RUN_LIVE=1 (with Ollama running) to attempt the real pipeline."
+  puts "   Set RUN_LIVE=1 (with LM Studio running) to attempt the real pipeline."
   puts "   Expected behavior: headline_finder, background_brief, and"
   puts "   fact_checker run in parallel; report_writer follows."
   puts
@@ -204,7 +204,7 @@ unless ENV["RUN_LIVE"]
   exit 0
 end
 
-require_ollama!
+require_lms!
 
 section "Part 3: Live LLM Run (RUN_LIVE set)"
 

data/examples/33_stock_predictor.rb

@@ -14,7 +14,7 @@
 # Prerequisites:
 #   gem install redis
 #   Redis server running on localhost:6379
-#   Ollama running with the model from common.rb pulled
+#   LM Studio running with the models from common.rb downloaded
 #
 # Usage:
 #   ruby examples/33_stock_predictor.rb
@@ -119,12 +119,12 @@ class AdjustParameters < RobotLab::Tool
   description "Adjust one predictor parameter to improve future prediction accuracy. " \
               "Make at most one or two targeted changes per window."
 
-  param :parameter, type: "string",
-    desc: "Parameter to adjust: sma_window, sma_std_multiplier, ema_alpha, ema_vol_multiplier, sma_weight"
-  param :value, type: "number",
-    desc: "New value (sma_window: 3-30 int; std/vol multipliers: 0.5-4.0; ema_alpha: 0.05-0.5; sma_weight: 0.0-1.0)"
-  param :reasoning, type: "string",
-    desc: "Why this change should reduce prediction error"
+  parameter :parameter, type: "string",
+    description: "Parameter to adjust: sma_window, sma_std_multiplier, ema_alpha, ema_vol_multiplier, sma_weight"
+  parameter :value, type: "number",
+    description: "New value (sma_window: 3-30 int; std/vol multipliers: 0.5-4.0; ema_alpha: 0.05-0.5; sma_weight: 0.0-1.0)"
+  parameter :reasoning, type: "string",
+    description: "Why this change should reduce prediction error"
 
   LIMITS = {
     "sma_window"         => { min: 3,    max: 30,  integer: true  },
@@ -204,7 +204,7 @@ puts "Warmup     : #{PredictorConfig.sma_window} ticks"
 puts "Press Ctrl-C to stop."
 puts "-" * 60
 
-require_ollama!
+require_lms!
 
 redis  = Redis.new
 prices = []

data/examples/35_hooks.rb

@@ -129,7 +129,7 @@ end
 
 class HookDemoTool < RobotLab::Tool
   description "Returns a deterministic hook demo value"
-  param :label, type: "string", desc: "The label to echo"
+  parameter :label, type: "string", description: "The label to echo"
 
   def execute(label:)
     { label: label, status: "handled by HookDemoTool" }
@@ -187,7 +187,7 @@ class HookDemo
 
     puts "  provider=#{LLM[:default].provider}  model=#{LLM[:default].model}\n\n"
 
-    # with_model alone would leave the provider unset, and an Ollama model is
+    # with_model alone would leave the provider unset, and an LM Studio model is
     # not in RubyLLM's registry — pass provider and model together.
     robot = RobotLab.build(
       name: "loop_demo_robot",
@@ -224,7 +224,7 @@ class HookDemo
   def run_tool
     section "Tool Call Hooks"
     tool   = HookDemoTool.new
-    result = tool.call({ "label" => "tool hook payload" })
+    result = tool.call(**{ "label" => "tool hook payload" })
     puts "Tool result: #{result.inspect}"
   end
 

data/examples/README.md

@@ -2,6 +2,15 @@
 
 Working demonstrations of RobotLab features, from single-robot basics to multi-robot orchestration and message bus communication.
 
+> **A note on performance:** how fast (and how well) these demos run depends
+> almost entirely on which provider and model you point them at. A large model
+> served locally on consumer hardware can take a minute or more per LLM call,
+> while a small local model or a hosted API answers in seconds — and smaller
+> models may also give noticeably weaker answers on the multi-robot demos.
+> Wall-clock times you see will differ from anyone else's; tune the
+> provider/model in `common.rb` (or via `LLM_PROFILE`) to trade speed against
+> quality.
+
 ## Prerequisites
 
 - Ruby >= 3.2
@@ -83,8 +92,16 @@ bundle exec rake examples:all
 
 # Run directly
 bundle exec ruby examples/01_simple_robot.rb
+
+# Run every demo serially with a banner between each (works from any cwd)
+examples/run_all.rb
 ```
 
+`run_all.rb` executes every executable `NN_*.rb` demo in order, announcing
+each one with a banner so the outputs stay separated. Ctrl-C kills only the
+demo that is currently running — the runner notes the interruption and moves
+on to the next demo.
+
 ## Tools require `tools: :inherit` at run time
 
 This trips up everyone once. `Robot#run` defaults to `tools: :none`, which

data/examples/common.rb

@@ -1,33 +1,64 @@
 # frozen_string_literal: true
 
+# The examples are runnable directly (./01_simple_robot.rb) as well as via
+# bundle exec. Without bundler/setup, bare requires let RubyGems activate the
+# newest installed json (3.x), which conflicts with ruby_llm's json (< 3) pin;
+# the lockfile pins json 2.x, so honor it in both invocation styles.
+#
+# The workspace .envrc exports BUNDLE_GEMFILE as a RELATIVE path ("Gemfile" or
+# "Gemfile.local"), which bundler resolves against the cwd — so a demo run
+# from examples/ or a subdirectory demo run from its own directory would look
+# for a Gemfile there. Anchor the basename to the gem root before bundler
+# sees it, preserving the prod/dev (Gemfile vs Gemfile.local) choice.
+ENV["BUNDLE_GEMFILE"] = File.expand_path(
+  "../#{File.basename(ENV.fetch("BUNDLE_GEMFILE", "Gemfile"))}", __dir__
+)
+require "bundler/setup"
+
 require "logger"
 
 # Fallback for when direnv has not activated examples/.envrc
 ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
 
 require_relative "../lib/robot_lab"
+require "ruby_llm/providers/lms"
+
+# robot_lab's dependencies load parts of ActiveSupport, so amazing_print 3.0
+# sees the constant and loads its ActiveSupport extension, which at require
+# time calls ActiveSupport.try and reads ActiveSupport::LogSubscriber —
+# neither of which those parts provide. Load both up front so any demo can
+# `require "amazing_print"` safely.
+require "active_support/core_ext/object/try"
+require "active_support/log_subscriber"
 
 # ── Local LLM Configuration ───────────────────────────────────────────────────
 #
-# Every example runs against a LOCAL model served by Ollama. No API keys, no
-# network egress, no per-token cost. Pull the model once before running:
+# Every example runs against a LOCAL model served by LM Studio through the
+# ruby_llm-providers-lms gem (provider :lms). No API keys, no network egress,
+# no per-token cost. Start the server and download the models once:
+#
+#   lms server start
+#   lms get qwen/qwen3.8-27b
+#   lms get openai/gpt-oss-20b
 #
-#   ollama pull qwen3.6
+# Model choice: qwen/qwen3.8-27b for complex activities (tools, structured
+# output, multi-robot reasoning — it honors tool_choice and schemas), and
+# openai/gpt-oss-20b for simpler items (plain chat, streaming).
 #
-# Ollama models are not in RubyLLM's model registry, so a `provider:` must be
-# supplied alongside `model:` — that is what makes RubyLLM skip the registry
-# lookup (see Robot#initialize, which sets assume_model_exists when provider is
-# given). Use the `llm_opts` helper below so every robot gets both.
+# LM Studio models are not in RubyLLM's model registry, so a `provider:` must
+# be supplied alongside `model:` — that is what makes RubyLLM skip the
+# registry lookup (see Robot#initialize, which sets assume_model_exists when
+# provider is given). Use the `llm_opts` helper below so every robot gets both.
 
 LlmConfig = Data.define(:provider, :model)
 
 LLM = {
-  default: LlmConfig.new(provider: "ollama", model: "qwen3.6:latest"),
-  small:   LlmConfig.new(provider: "ollama", model: "qwen2.5:7b"),
-  large:   LlmConfig.new(provider: "ollama", model: "llama3.3:latest")
+  default: LlmConfig.new(provider: "lms", model: "qwen/qwen3.8-27b"),
+  small:   LlmConfig.new(provider: "lms", model: "openai/gpt-oss-20b"),
+  large:   LlmConfig.new(provider: "lms", model: "qwen/qwen3.8-27b")
 }.freeze
 
-OLLAMA_API_BASE = ENV.fetch("OLLAMA_API_BASE", "http://localhost:11434/v1")
+LMS_API_BASE = ENV.fetch("LMS_API_BASE", "http://localhost:1234/v1")
 
 # ORDER MATTERS. The first touch of RobotLab.config runs Config#after_load,
 # which calls RubyLLM.configure itself and would clobber anything set before
@@ -37,9 +68,9 @@ RobotLab.configure do |c|
 end
 
 RubyLLM.configure do |c|
-  c.logger          = Logger.new(File::NULL)
-  c.default_model   = LLM[:default].model
-  c.ollama_api_base = OLLAMA_API_BASE
+  c.logger        = Logger.new(File::NULL)
+  c.default_model = LLM[:default].model
+  c.lms_api_base  = LMS_API_BASE
 
   # A large local model on consumer hardware is far slower than a hosted API,
   # and robot_lab's bundled 120s default is comfortably exceeded by a long
@@ -67,7 +98,7 @@ end
 
 # Provider + model keyword pair for RobotLab.build / Robot.new.
 #
-# Both are required for a local Ollama model. Splat it into any robot
+# Both are required for a local LM Studio model. Splat it into any robot
 # constructor:
 #
 #   RobotLab.build(name: "helper", **llm_opts)          # honors LLM_PROFILE
@@ -80,19 +111,20 @@ def llm_opts(key = nil)
   { provider: cfg.provider, model: cfg.model }
 end
 
-# Fail fast with an actionable message when Ollama isn't reachable, instead of
-# letting every example die inside an HTTP adapter.
-def require_ollama!
+# Fail fast with an actionable message when LM Studio isn't reachable,
+# instead of letting every example die inside an HTTP adapter.
+def require_lms!
   require "net/http"
-  uri = URI(OLLAMA_API_BASE.sub(%r{/v1/?$}, "") + "/api/tags")
+  uri = URI("#{LMS_API_BASE.sub(%r{/v1/?\z}, '')}/v1/models")
   Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 2) { |h| h.get(uri.request_uri) }
 rescue StandardError => e
   abort <<~ERROR
-    Cannot reach Ollama at #{OLLAMA_API_BASE} (#{e.class}).
+    Cannot reach LM Studio at #{LMS_API_BASE} (#{e.class}).
 
-    Start it and pull the model used by the examples:
-      ollama serve
-      ollama pull #{LLM[:default].model.sub(/:latest\z/, "")}
+    Start the server and download the models used by the examples:
+      lms server start
+      lms get #{LLM[:default].model}
+      lms get #{LLM[:small].model}
   ERROR
 end
 

data/examples/run_all.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Runs every executable NN_*.rb demo in this directory serially, printing a
+# banner to STDOUT before each one so the outputs are easy to tell apart.
+
+module RunAll
+  module_function
+
+  # Executable NN_*.rb demos in +dir+, in numeric order.
+  def demo_files(dir = __dir__)
+    Dir.glob(File.join(dir, "[0-9][0-9]_*.rb"))
+       .select { File.executable?(it) }
+       .sort
+  end
+
+  def banner(path)
+    bar = "=" * 70
+    <<~BANNER
+
+      #{bar}
+      ==  #{File.basename(path)}
+      #{bar}
+    BANNER
+  end
+
+  # Absolute path to the gem root's Gemfile, honoring the prod/dev choice
+  # (Gemfile vs Gemfile.local) carried by BUNDLE_GEMFILE. The inherited value
+  # is relative, so left alone it would resolve against the demo's cwd.
+  def bundle_gemfile(dir = __dir__)
+    name = File.basename(ENV.fetch("BUNDLE_GEMFILE", "Gemfile"))
+    File.expand_path("../#{name}", dir)
+  end
+
+  # Runs one demo with this Ruby interpreter; returns true on success.
+  def run_demo(path)
+    system({ "BUNDLE_GEMFILE" => bundle_gemfile }, RbConfig.ruby, path)
+  end
+
+  # True when the last demo was killed by Ctrl-C (SIGINT).
+  def interrupted?(status = Process.last_status)
+    !status.nil? && status.signaled? && status.termsig == Signal.list["INT"]
+  end
+
+  # Ctrl-C reaches the whole foreground process group. A proc trap (unlike
+  # "IGNORE") is reset to DEFAULT in the exec'd child, so the demo dies while
+  # this runner survives and moves on to the next one.
+  def run(files = demo_files)
+    previous = trap("INT") { nil }
+    files.each do |file|
+      puts banner(file)
+      run_demo(file)
+      puts "--  #{File.basename(file)} interrupted (Ctrl-C); moving on" if interrupted?
+    end
+  ensure
+    trap("INT", previous || "DEFAULT")
+  end
+end
+
+RunAll.run if $PROGRAM_NAME == __FILE__

data/lib/robot_lab/ask_user.rb

@@ -33,9 +33,9 @@ module RobotLab
   #
   class AskUser < Tool
     description "Ask the user a question and wait for their typed response"
-    param :question, type: "string",  desc: "The question to ask the user"
-    param :choices,  type: "array",   desc: "Optional list of choices to present", required: false
-    param :default,  type: "string",  desc: "Default value if user presses Enter",  required: false
+    parameter :question, type: "string",  description: "The question to ask the user"
+    parameter :choices,  type: "array",   description: "Optional list of choices to present", required: false
+    parameter :default,  type: "string",  description: "Default value if user presses Enter",  required: false
 
     # :reek:FeatureEnvy -- rendering and resolving the caller-supplied choices list is this tool's whole job.
     # :reek:TooManyStatements -- linear prompt/read/resolve terminal interaction.

data/lib/robot_lab/config/defaults.yml

@@ -41,13 +41,13 @@ defaults:
     with_model:
       provider: null # chat-specific provider
       model: null # chat-specific model
-      assume_exists: null # assume the model exists primarily for local providers
+      assume_model_exists: null # assume the model exists primarily for local providers
     with_temperature: 0.7 # Controls randomness (0.0-2.0, null = model default)
+    with_max_output_tokens: null # Maximum tokens in response
     with_tools: null # ?? not sure about this one.
-    with_params:
+    with_provider_options: # merged into the request payload (ruby_llm 2.0)
       top_p: null # Nucleus sampling threshold (0.0-1.0)
       top_k: null # Top-k sampling (integer, provider-specific)
-      max_tokens: null # Maximum tokens in response
       presence_penalty: null # Penalize new tokens based on presence (-2.0 to 2.0)
       frequency_penalty: null # Penalize new tokens based on frequency (-2.0 to 2.0)
       stop: null # Stop sequences (string or array of strings)
@@ -55,7 +55,7 @@ defaults:
   # RubyLLM Configuration Section
   ruby_llm:
     provider: :anthropic
-    model: claude-sonnet-4
+    model: claude-sonnet-4-6
     assume_model_exists: false # (dep of assume_exists in chat section) set true for Ollama and other local LLM providers
     # Provider API Keys (null = use env vars directly)
     anthropic_api_key: null
@@ -117,7 +117,7 @@ test:
   max_iterations: 3
   streaming_enabled: false
   ruby_llm:
-    model: claude-3-haiku-20240307
+    model: claude-haiku-4-5
     request_timeout: 30
     max_retries: 1
     log_level: :warn

data/lib/robot_lab/config.rb

@@ -14,7 +14,7 @@ module RobotLab
   # - Automatic RubyLLM configuration application
   #
   # @example Access configuration values
-  #   RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+  #   RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4-6"
   #   RobotLab.config.ruby_llm.request_timeout  #=> 120
   #   RobotLab.config.development?              #=> true
   #
@@ -28,7 +28,7 @@ module RobotLab
   #   # defaults.yml. This file is NOT run through ERB, so keep secrets in
   #   # environment variables or in ./config/robot_lab.yml (which is).
   #   ruby_llm:
-  #     model: claude-sonnet-4
+  #     model: claude-sonnet-4-6
   #     request_timeout: 120
   #
   class Config < MywayConfig::Base

data/lib/robot_lab/mcp/transports/streamable_http.rb

@@ -116,9 +116,7 @@ module RobotLab
         # Returns the session identifier.
         #
         # @return [String, nil] the session ID
-        def session_id
-          @session_id
-        end
+        attr_reader :session_id
 
         private
 

data/lib/robot_lab/memory.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
-require "ruby_llm/semantic_cache"
+# Optional: ruby_llm-semantic_cache has not shipped a ruby_llm 2.0-compatible
+# release. When the gem is absent, Memory#cache returns nil and semantic
+# caching is silently disabled.
+begin
+  require "ruby_llm/semantic_cache"
+rescue LoadError
+  # Semantic caching unavailable; Memory runs without it.
+end
 
 module RobotLab
   # Raised when a blocking get times out
@@ -106,7 +113,7 @@ module RobotLab
       set_internal(:results, Array(results))
       set_internal(:messages, Array(messages).map { |m| normalize_message(m) })
       set_internal(:session_id, session_id)
-      set_internal(:cache, @enable_cache ? RubyLLM::SemanticCache : nil)
+      set_internal(:cache, @enable_cache ? create_semantic_cache : nil)
 
       # Data proxy for method-style access
       @data = nil
@@ -215,9 +222,11 @@ module RobotLab
 
     # Get the semantic cache module
     #
-    # The cache is always active and provides semantic similarity matching
-    # for LLM responses, reducing costs and latency by returning cached
-    # responses for semantically equivalent queries.
+    # When the optional ruby_llm-semantic_cache gem is installed (and
+    # enable_cache is true), provides semantic similarity matching for LLM
+    # responses, reducing costs and latency by returning cached responses
+    # for semantically equivalent queries. Returns nil when the gem is
+    # absent or caching is disabled.
     #
     # @example Using the cache with fetch
     #   response = memory.cache.fetch("What is Ruby?") do
@@ -228,7 +237,7 @@ module RobotLab
     #   chat = memory.cache.wrap(RubyLLM.chat(model: "gpt-4"))
     #   chat.ask("What is Ruby?")  # Cached on semantic similarity
     #
-    # @return [RubyLLM::SemanticCache] the semantic cache module
+    # @return [RubyLLM::SemanticCache, nil] the semantic cache module, or nil when unavailable
     #
     def cache
       get_internal(:cache)
@@ -702,7 +711,7 @@ module RobotLab
     end
 
     def create_semantic_cache
-      RubyLLM::SemanticCache
+      defined?(RubyLLM::SemanticCache) ? RubyLLM::SemanticCache : nil
     end
 
     # :reek:ControlParameter -- factory method; the preference symbol is exactly what selects the backend.

data/lib/robot_lab/robot/hooking.rb

@@ -54,6 +54,32 @@ module RobotLab
       def hook_registries(network = nil)
         [RobotLab.hooks, network&.hooks, @hooks]
       end
+
+      # Arm the per-run circuit breaker checked by the chat's before_tool_call
+      # dispatcher (see Robot#register_chat_callbacks). Raises ToolLoopError
+      # once tool calls exceed @config.max_tool_rounds. ruby_llm 2.0 callbacks
+      # are additive and cannot be removed, so the breaker toggles a flag the
+      # permanent dispatcher consults instead of swapping callbacks per run.
+      def install_circuit_breaker
+        @circuit_breaker_call_count = 0
+        @circuit_breaker_armed = true
+      end
+
+      # Disarm the circuit breaker after a run.
+      def restore_tool_call_callback
+        @circuit_breaker_armed = false
+      end
+
+      # Count a tool call against max_tool_rounds and raise once exceeded.
+      def enforce_circuit_breaker!
+        max = @config.max_tool_rounds
+        @circuit_breaker_call_count += 1
+        return if @circuit_breaker_call_count <= max
+
+        raise ToolLoopError,
+              "Circuit breaker triggered: #{@circuit_breaker_call_count} tool calls exceeded " \
+              "max_tool_rounds (#{max})"
+      end
     end
   end
 end

data/lib/robot_lab/robot/result_building.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Adapts a ruby_llm response into a RobotResult, including token
+    # accounting, stop-reason normalization, and message coercion helpers.
+    #
+    # Owns:    nothing (pure adapters over the response and @chat)
+    # Reads:   @chat, @name; Writes: @total_input_tokens, @total_output_tokens
+    module ResultBuilding
+      private
+
+      # :reek:TooManyStatements :reek:FeatureEnvy -- adapting a provider response's many optional fields into
+      #   a RobotResult is inherently response-centric.
+      def build_result(response, _memory)
+        text = result_text(response)
+        output = text ? [TextMessage.new(role: 'assistant', content: text)] : []
+
+        tool_calls = response.respond_to?(:tool_calls) ? (response.tool_calls || []) : []
+
+        input_toks, output_toks = extract_token_counts(response)
+        @total_input_tokens += input_toks
+        @total_output_tokens += output_toks
+
+        RobotResult.new(
+          robot_name: @name,
+          output: output,
+          tool_calls: normalize_tool_calls(tool_calls),
+          stop_reason: extract_stop_reason(response),
+          raw: response,
+          input_tokens: input_toks,
+          output_tokens: output_toks
+        )
+      end
+
+      # Token usage from the response. ruby_llm 2.0 nests counts under
+      # response.tokens; duck-typed responses may still answer input_tokens.
+      # :reek:FeatureEnvy -- reading the response's optional token fields is the extraction itself.
+      def extract_token_counts(response)
+        if response.respond_to?(:tokens) && (tokens = response.tokens)
+          [tokens.input.to_i, tokens.output.to_i]
+        elsif response.respond_to?(:input_tokens)
+          [response.input_tokens.to_i,
+           response.respond_to?(:output_tokens) ? response.output_tokens.to_i : 0]
+        else
+          [0, 0]
+        end
+      end
+
+      # ruby_llm 2.0's add_message accepts a Message, an attribute Hash, or a
+      # record responding to to_llm. Compression summaries (and tests) hand us
+      # plain role/content value objects; convert those to attribute hashes so
+      # the chat can coerce them.
+      def coerce_replacement_message(message)
+        if message.is_a?(RubyLLM::Message) || message.is_a?(Hash) || message.respond_to?(:to_llm)
+          message
+        else
+          { role: message.role, content: message.content }
+        end
+      end
+
+      # The response's normalized stop reason. ruby_llm 2.0 exposes it as
+      # finish_reason (a Symbol such as :stop or :tool_calls); older or
+      # duck-typed responses may still answer stop_reason.
+      def extract_stop_reason(response)
+        return response.finish_reason if response.respond_to?(:finish_reason)
+
+        response.respond_to?(:stop_reason) ? response.stop_reason : nil
+      end
+
+      # Text for the result's output. Prefers the final response's content, then
+      # falls back in order to: (1) thinking text for models that route all output
+      # through reasoning_content (e.g. qwen3 on Ollama), (2) the most recent
+      # assistant text within the current turn for models that end on a tool call
+      # with no trailing text.
+      #
+      # The chat-history fallback is scoped to messages AFTER the last user message
+      # (the current turn) to prevent a previous turn's response from being returned
+      # when a thinking-mode model emits nothing in response.content.
+      # :reek:TooManyStatements :reek:FeatureEnvy -- documented fallback chain over the response's optional content/thinking/history fields.
+      def result_text(response)
+        content = response.content if response.respond_to?(:content)
+        return content if content && !content.to_s.empty?
+
+        # Ollama routes qwen3's reasoning to reasoning_content, which ruby_llm
+        # surfaces as response.thinking (a RubyLLM::Thinking object). When content
+        # is nil and thinking is present, the thinking IS the response for that turn.
+        if response.respond_to?(:thinking) && (thinking = response.thinking)
+          thinking_text = thinking.respond_to?(:text) ? thinking.text.to_s : thinking.to_s
+          return thinking_text unless thinking_text.empty?
+        end
+
+        return nil unless @chat.respond_to?(:messages)
+
+        messages = @chat.messages
+        last_user_idx = messages.rindex { |m| m.role == :user } || -1
+        current_turn = messages[(last_user_idx + 1)..]
+
+        last = current_turn.rfind { |m| m.role == :assistant && m.content && !m.content.to_s.empty? }
+        last&.content
+      end
+
+      def normalize_tool_calls(tool_calls)
+        return [] unless tool_calls
+
+        tool_calls.map do |tc|
+          if tc.is_a?(Hash)
+            ToolResultMessage.new(
+              tool: tc,
+              content: tc[:result] || tc['result']
+            )
+          else
+            tc
+          end
+        end
+      end
+    end
+  end
+end