samagotchi 0.55.0 → 0.57.0

data/lib/samagotchi/llm/chat_loop.rb

@@ -8,6 +8,7 @@ require_relative "errors"
 require_relative "usage"
 require_relative "openai_chat"
 require_relative "native_tool_normalizer"
+require_relative "stream_drops"
 require_relative "../kernel_loop"
 require_relative "../answer_display"
 require_relative "../cut_policy"
@@ -44,6 +45,8 @@ module Samagotchi
     # Cancel closes the request's socket (LLM::HTTP), so it works on any
     # thread; the text streamed so far is kept, marked [interrupted].
     class ChatLoop < ModelBackend
+      include LLM::StreamDrops
+
       attr_accessor :adapter
       # The session every request is for; Engine sets it with the adapter.
       # Goes out as a Session-Id header (OpenAIChat#chat).
@@ -63,42 +66,6 @@ module Samagotchi
         @sleeper = sleeper || ->(seconds) { sleep(seconds) }
       end
 
-      # How many times a dropped stream's step may be asked again: +cap+, or
-      # retry.max when that is smaller (retry.max: 0 turns it off, as it
-      # does the transport's retries).
-      def stream_drop_limit(cap)
-        [cap, HTTP::RetryPolicy.from_config.max].min
-      rescue StandardError
-        cap
-      end
-
-      # The seconds before the +attempt+-th ask-again of a dropped stream's
-      # step: the transport's own backoff (retry.base_delay doubling, capped
-      # at retry.max_delay; LLM::HTTP::RetryPolicy), 0 when retry.max is
-      # spent.
-      def generation_retry_delay(attempt)
-        HTTP::RetryPolicy.from_config.delay_for(attempt) || 0.0
-      rescue StandardError
-        0.0
-      end
-
-      # Waits +seconds+ in short slices, raising RequestCancelled as soon as
-      # one of +controllers+ (the turn's, the generation's) is cancelled, as
-      # LLM::HTTP's own wait between retries does.
-      def wait_retry(seconds, *controllers)
-        remaining = seconds.to_f
-        while remaining.positive?
-          cancelled = controllers.compact.find(&:cancelled?)
-          raise RequestCancelled, cancelled.reason if cancelled
-
-          slice = [remaining, 0.05].min
-          @sleeper.call(slice)
-          remaining -= slice
-        end
-        cancelled = controllers.compact.find(&:cancelled?)
-        raise RequestCancelled, cancelled.reason if cancelled
-      end
-
       def provider = :chat
 
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
@@ -164,11 +131,17 @@ module Samagotchi
       # as one user message "[images from tool results]". Images the request
       # leaves out (ImagePlan) become placeholder lines in the text.
       #
+      # A model turn carries its saved reasoning as reasoning_content when
+      # +reasoning+ (a ReasoningHistory level; the turn's by default) says
+      # so: under turn the running turn's only (#reasoning_boundary, with
+      # +since+ the Run's start), under all every one.
+      #
       # The conversation goes through the kernel's LLMContextView first,
-      # as the native prompt does.
-      def wire_messages(conversation)
+      # as the native prompt does (it keeps every entry in place).
+      def wire_messages(conversation, since: nil, reasoning: reasoning_history)
         conversation = llm_context_view.messages(conversation)
         paired = paired_call_ids(conversation)
+        boundary = reasoning_boundary(conversation, since: since, level: reasoning)
         plan = ImagePlan.new(conversation, vision)
         tool_images = []
         wire = []
@@ -182,7 +155,9 @@ module Samagotchi
             content = Steer.header(entry) ? Steer.wire_text(entry, entry[:content].to_s) : entry[:content]
             wire << { role: "user", content: parts(content, items) }
           when "model"
-            wire << assistant_message(entry, paired)
+            message = assistant_message(entry, paired)
+            message[:reasoning_content] = entry[:thinking] if boundary && index >= boundary && thought?(entry)
+            wire << message
           when "tool_response"
             id = entry[:tool_call_id]
             if id && paired.include?(id)
@@ -215,6 +190,44 @@ module Samagotchi
 
       TOOL_IMAGES_TEXT = "[images from tool results]"
 
+      # The first index whose model entries carry their reasoning (nil:
+      # none do) under +level+. Under turn: past both the last query (a
+      # user message: a prompt, a steer, merged input, the chat template's
+      # last query; or an entry that starts a turn, turn_start) and +since+
+      # (the Run's start, so a continue turn -- a reminder, a context wake,
+      # a continue after a stop -- sends none of the run before it).
+      # @return [Integer, nil]
+      def reasoning_boundary(conversation, since: nil, level: reasoning_history)
+        case level
+        when :all then 0
+        when :turn
+          query = conversation.rindex { |entry| entry[:role].to_s == "user" || entry[:turn_start] == true }
+          [query ? query + 1 : 0, since.to_i].max
+        end
+      end
+
+      # The reasoning +conversation+'s wire messages carry from +since+ on
+      # (#reasoning_boundary), in characters.
+      def reasoning_chars(conversation, since: nil, reasoning: reasoning_history)
+        boundary = reasoning_boundary(conversation, since: since, level: reasoning) or return 0
+        conversation.drop(boundary).sum { |entry| entry[:role].to_s == "model" && thought?(entry) ? entry[:thinking].length : 0 }
+      end
+
+      # The turn's ReasoningHistory level (the kernel's turn_settings); drop
+      # without settings, and for a +model+ whose host refused it
+      # (#reasoning_history_refused!).
+      def reasoning_history(model = nil)
+        return :drop if model && @reasoning_history_refused&.include?(model)
+
+        @kernel.turn_settings&.reasoning_history || :drop
+      end
+
+      # The host refused +model+'s reasoning sent back: send none from now on
+      # (this worker's lifetime, as #thinking_refused!).
+      def reasoning_history_refused!(model)
+        (@reasoning_history_refused ||= Set.new) << model
+      end
+
       # The turn's VisionContext (the Engine sets the kernel's
       # turn_settings), or nil.
       def vision = @kernel.turn_settings.vision
@@ -282,7 +295,7 @@ module Samagotchi
 
       # The shape the engine persists: role and content (parts stay an
       # Array), plus a model turn's tool_calls and thinking (the host's
-      # reasoning, never sent back), a result's tool_call_id, the image
+      # reasoning, sent back as #wire_messages says), a result's tool_call_id, the image
       # refs of a user message or a tool result, a prompt's turn_id (Engine,
       # never sent) and a wake turn's report's turn_start (Steer, never sent), and a plugin tool result's tool_params and tool_labels
       # (the live row's params line and label, never sent back), an
@@ -380,6 +393,8 @@ module Samagotchi
         notes.empty? ? text : [text, *notes].reject(&:empty?).join("\n")
       end
 
+      def thought?(entry) = entry[:thinking].is_a?(String) && !entry[:thinking].strip.empty?
+
       def scrub(text)
         text.encoding == Encoding::UTF_8 && !text.valid_encoding? ? text.scrub("?") : text
       end
@@ -394,6 +409,9 @@ module Samagotchi
           @cancel_controller = cancel_controller
           @model_name = model_name
           @pending_input = pending_input
+          # Where this run's entries start: the reasoning it sends back
+          # (ChatLoop#reasoning_boundary) is its own.
+          @start = conversation.length
           @tool_activity = []
           @empty_retry = EmptyAnswerRetry.new
           # The empty generations, never saved: the UIs draw the turn's
@@ -486,8 +504,8 @@ module Samagotchi
 
         # The host's reasoning, kept on the model message as +thinking+ for
         # the web turn view's reload (the whole of it, as the live view
-        # shows). Only saved: #assistant_message builds the wire message from
-        # content and tool_calls, so it never goes back to the model.
+        # shows), and sent back to the model as ChatLoop#wire_messages says
+        # (reasoning_history).
         def with_thinking(message, response)
           reasoning = response.reasoning.to_s
           reasoning.strip.empty? ? message : message.merge(thinking: reasoning)
@@ -510,18 +528,17 @@ module Samagotchi
           generation_controller = nil
           response = with_generation do |controller|
             generation_controller = controller
-            # One count for the step: the ask-again without thinking fields
-            # doesn't get drops of its own.
-            drops = DropCount.new(0, 0)
+            # One count for the step: an ask-again without reasoning or
+            # thinking fields doesn't get drops of its own.
+            drops = LLM::StreamDrops::DropCount.new(0, 0)
+            ask = -> { request_with_drops(iteration, retry_generation, streamed, thought, drops, controller) }
             begin
-              request_with_drops(iteration, retry_generation, streamed, thought, drops, controller)
+              ask.call
             rescue BadRequest => e
-              raise unless thinking_refused?(e)
-
-              # Once per model: asked again without the thinking fields.
-              @loop.thinking_refused!(@model_name)
-              emit(type: :thinking_refused, iteration: iteration, model: @model_name, level: @loop.thinking, detail: e.detail)
-              request_with_drops(iteration, retry_generation, streamed, thought, drops, controller)
+              if refused?(e) && reasoning_sent? then without_reasoning(iteration, e, ask)
+              elsif thinking_refused?(e) then without_thinking(iteration, e, ask)
+              else raise
+              end
             end
           rescue RequestCancelled
             raise unless generation_controller&.cancelled? && !@cancel_controller.cancelled?
@@ -571,7 +588,7 @@ module Samagotchi
 
         def request(iteration, retry_generation, streamed, thought, generation_controller, streamed_any = nil)
           @loop.adapter.chat(
-            messages: @loop.wire_messages(@conversation), tools: @loop.tool_definitions, model: @model_name,
+            messages: @loop.wire_messages(@conversation, since: @start, reasoning: reasoning_level), tools: @loop.tool_definitions, model: @model_name,
             cancel_controller: generation_controller || @cancel_controller, session_id: @loop.session_id,
             options: @loop.request_options(retry_generation: retry_generation, model: @model_name),
             on_delta: lambda { |content:, reasoning:, payload:|
@@ -596,16 +613,8 @@ module Samagotchi
         # none with 0), after the transport's backoff: the partial reply is
         # dropped and the step restarts. A refusal or a first-token timeout
         # fails as before, and a cancel (before or during the wait) never
-        # retries.
-        MAX_STREAM_DROPS = 2
-
-        # A step's drops asked again (+drops+) and the HTTP requests made so
-        # far (+requests+: each failed request's transport attempts), so the
-        # error that ends the step counts every request, not the last one's.
-        DropCount = Struct.new(:drops, :requests)
-
-        # Runs one request, asking again on a mid-stream drop; +count+ (a
-        # DropCount) carries on across calls for one step.
+        # retries. +count+ (a DropCount) carries on across calls for one
+        # step.
         def request_with_drops(iteration, retry_generation, streamed, thought, count, generation_controller)
           streamed_any = false
           request(iteration, retry_generation, streamed, thought, generation_controller, -> { streamed_any = true })
@@ -616,7 +625,7 @@ module Samagotchi
           raise RequestCancelled, cancelled.reason if cancelled
 
           count.requests += e.attempts.to_i
-          limit = @loop.stream_drop_limit(MAX_STREAM_DROPS)
+          limit = @loop.stream_drop_limit(LLM::StreamDrops::MAX_STREAM_DROPS)
           if count.drops >= limit || !streamed_any
             raise if count.requests == e.attempts.to_i
 
@@ -642,11 +651,52 @@ module Samagotchi
           raise
         end
 
-        # A 400 about reasoning, for a request that carried thinking fields
-        # (not a missing-tools, image or context error).
-        def thinking_refused?(error)
+        # A 400 about reasoning (not a missing-tools, image or context error).
+        def refused?(error)
           error.reasoning_refused? && !error.is_a?(VisionUnsupported) && !error.tools_unsupported? &&
-            !error.context_overflow? && !@loop.thinking_fields(@model_name).empty?
+            !error.context_overflow?
+        end
+
+        # #refused?, for a request that carried thinking fields.
+        def thinking_refused?(error) = refused?(error) && !@loop.thinking_fields(@model_name).empty?
+
+        # Whether this step's request sends reasoning back.
+        def reasoning_sent?
+          !@without_reasoning && @loop.reasoning_chars(@conversation, since: @start, reasoning: reasoning_level).positive?
+        end
+
+        # The level this step's request sends reasoning back under: none
+        # while it is asked again without (#without_reasoning).
+        def reasoning_level = @without_reasoning ? :drop : @loop.reasoning_history(@model_name)
+
+        # The host refused a request that sent reasoning back: ask the step
+        # again without it. When that goes through, the model sends none from
+        # now on. When it is refused too, the thinking fields may be what the
+        # host refuses: #without_thinking asks a third time (still without
+        # reasoning; a later step sends it again, so a host that refuses
+        # only the thinking fields keeps it).
+        def without_reasoning(iteration, error, ask)
+          @without_reasoning = true
+          response = begin
+            ask.call
+          rescue BadRequest => e
+            raise unless thinking_refused?(e)
+
+            return without_thinking(iteration, e, ask)
+          end
+          @loop.reasoning_history_refused!(@model_name)
+          emit(type: :reasoning_history_refused, iteration: iteration, model: @model_name,
+               level: @loop.reasoning_history, detail: error.detail)
+          response
+        ensure
+          @without_reasoning = false
+        end
+
+        # Once per model: asked again without the thinking fields.
+        def without_thinking(iteration, error, ask)
+          @loop.thinking_refused!(@model_name)
+          emit(type: :thinking_refused, iteration: iteration, model: @model_name, level: @loop.thinking, detail: error.detail)
+          ask.call
         end
 
         # Before a request, as the native loop: estimate how full the window
@@ -671,10 +721,11 @@ module Samagotchi
 
         # The conversation's text as the request carries it, through the
         # kernel's LLMContextView (a stub counts, not the output it stands
-        # for): contents (a parts list's text parts) and the tool calls'
-        # names and arguments.
+        # for): contents (a parts list's text parts), the tool calls'
+        # names and arguments, and the reasoning sent back.
         def prompt_chars
-          LLMContextView.chars(@loop.llm_context_view.messages(@conversation))
+          LLMContextView.chars(@loop.llm_context_view.messages(@conversation)) +
+            @loop.reasoning_chars(@conversation, since: @start, reasoning: reasoning_level)
         end
 
         # The server's counts for this request (prompt + answer): the status

data/lib/samagotchi/llm/openai_chat.rb

@@ -333,10 +333,11 @@ module Samagotchi
       end
 
       # A String stays a String, an Array of parts an Array; both scrubbed
-      # of invalid UTF-8 (Utf8Scrub).
+      # of invalid UTF-8 (Utf8Scrub), as is reasoning sent back.
       def wire_message(message)
         wire = message.to_h.transform_keys(&:to_sym)
         wire[:content] = format_content(wire[:content]) if wire.key?(:content)
+        wire[:reasoning_content] = format_content(wire[:reasoning_content]) if wire.key?(:reasoning_content)
         wire
       end
 

data/lib/samagotchi/llm/stream_drops.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "http"
+
+module Samagotchi
+  module LLM
+    # A stream that dropped mid-answer is asked again from the same
+    # conversation: the same limit, backoff and cancel behaviour for both
+    # the chat loop and the native loop, so a native /completion and a chat
+    # request react identically to a dropped stream.
+    #
+    # The helpers the ask-again loop needs: how many times a dropped
+    # stream's step may be asked (stream_drop_limit), the transport's own
+    # backoff before the ask-again (generation_retry_delay), and the
+    # cancel-checking wait between the asks (wait_retry).
+    module StreamDrops
+      # The most times one step's dropped stream is asked again (both loops;
+      # stream_drop_limit lowers it under a smaller retry.max).
+      MAX_STREAM_DROPS = 2
+
+      # A step's drops asked again (+drops+) and the HTTP requests made so
+      # far (+requests+: each failed request's transport attempts), so the
+      # error that ends the step counts every request, not the last one's.
+      DropCount = Struct.new(:drops, :requests)
+
+      # How many times a dropped stream's step may be asked again: +cap+,
+      # or retry.max when that is smaller (retry.max: 0 turns it off, as it
+      # does the transport's retries).
+      def stream_drop_limit(cap)
+        [cap, HTTP::RetryPolicy.from_config.max].min
+      rescue StandardError
+        cap
+      end
+
+      # The seconds before the +attempt+-th ask-again of a dropped stream's
+      # step: the transport's own backoff (LLM::HTTP::RetryPolicy), 0 when
+      # retry.max is spent.
+      def generation_retry_delay(attempt)
+        HTTP::RetryPolicy.from_config.delay_for(attempt) || 0.0
+      rescue StandardError
+        0.0
+      end
+
+      # Waits +seconds+ in short slices, raising RequestCancelled as soon as
+      # one of +controllers+ (the turn's, the generation's) is cancelled,
+      # as LLM::HTTP's own wait between retries does.
+      def wait_retry(seconds, *controllers)
+        remaining = seconds.to_f
+        while remaining.positive?
+          cancelled = controllers.compact.find(&:cancelled?)
+          raise RequestCancelled, cancelled.reason if cancelled
+
+          slice = [remaining, 0.05].min
+          @sleeper.call(slice)
+          remaining -= slice
+        end
+        cancelled = controllers.compact.find(&:cancelled?)
+        raise RequestCancelled, cancelled.reason if cancelled
+      end
+    end
+  end
+end

data/lib/samagotchi/llm/turn_settings.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../thinking"
+require_relative "../reasoning_history"
 
 module Samagotchi
   module LLM
@@ -8,17 +9,20 @@ module Samagotchi
     # ChatLoop) and ToolRunner: the turn's VisionContext (nil sends no
     # images, placeholders instead), its request parameters
     # (SamplingSettings.for; empty sends none), its thinking level
-    # (Thinking.resolve), the bare model id the turn runs on (every debug
+    # (Thinking.resolve), which of its reasoning ChatLoop sends back
+    # (ReasoningHistory.resolve; ignored on the native loop), the bare model id the turn runs on (every debug
     # dump is tagged with it) and the model's or host's configured context
     # window (ContextWindow.setting, nil for none) and LLM context strategy
     # (LLMContextStrategy.resolve, nil for none), and its price on its host
     # (hosts.<name>.models.<id>.price, a ModelPrice; nil for none), what
     # SessionMetrics estimates an unreported cost from. The Engine sets them once
     # per turn, in Engine#generate, after the model's host is synced.
-    TurnSettings = Data.define(:vision, :sampling, :thinking, :model_name, :window_setting, :llm_context, :price) do
-      # No vision, no sampling, the default thinking, no model name.
-      def self.none = new(vision: nil, sampling: {}.freeze, thinking: Thinking::DEFAULT, model_name: nil,
-                          window_setting: nil, llm_context: nil, price: nil)
+    TurnSettings = Data.define(:vision, :sampling, :thinking, :reasoning_history, :model_name, :window_setting,
+                               :llm_context, :price) do
+      # No vision, no sampling, the default thinking, no reasoning sent
+      # back, no model name.
+      def self.none = new(vision: nil, sampling: {}.freeze, thinking: Thinking::DEFAULT, reasoning_history: :drop,
+                          model_name: nil, window_setting: nil, llm_context: nil, price: nil)
     end
   end
 end

data/lib/samagotchi/model_settings.rb

@@ -2,16 +2,18 @@
 
 require_relative "config"
 require_relative "llm_context_strategy"
+require_relative "reasoning_history"
 
 module Samagotchi
   # One config.yml models: entry (per-model settings keyed by model id or
   # alias), parsed and checked; ConfigFile.model_settings holds them by
   # downcased key. Each field is nil when unset: profile kept as written
   # (downcased; ModelProfile.resolve validates it), vision true/false,
-  # sampling a request-field map, thinking a level, window_tokens, and the
+  # sampling a request-field map, thinking a level, reasoning_history a
+  # ReasoningHistory level, window_tokens, and the
   # LLM context strategy, apply rule and budget (LLMContextStrategy). The
   # same per-model fields a hosts: entry carries (HostConfig).
-  ModelSettings = Data.define(:profile, :vision, :sampling, :thinking, :window_tokens,
+  ModelSettings = Data.define(:profile, :vision, :sampling, :thinking, :reasoning_history, :window_tokens,
                               :llm_context_strategy, :llm_context_apply, :llm_context_budget_tokens) do
     # Every field may be left out (nil).
     def initialize(**fields)
@@ -33,6 +35,7 @@ module Samagotchi
           vision: ConfigFile.vision_flag(value.call(:vision), where),
           sampling: ConfigFile.sampling_map(value.call(:sampling), where),
           thinking: Thinking.level(value.call(:thinking), where),
+          reasoning_history: ReasoningHistory.level(value.call(:reasoning_history), where),
           window_tokens: ConfigFile.window_tokens(value.call(:window_tokens), where),
           llm_context_strategy: LLMContextStrategy.parse(value.call(LLMContextStrategy::KEY), where),
           llm_context_apply: LLMContextStrategy.parse_apply(value.call(LLMContextStrategy::APPLY_KEY), where),

data/lib/samagotchi/plugin/context.rb

@@ -90,6 +90,11 @@ module Samagotchi
         @data_dir = nil
       end
 
+      # The bundle, never the environment it holds (every API key in it).
+      def inspect = "#<#{self.class.name} bundle=#{@bundle}>"
+
+      def pretty_print(printer) = printer.text(inspect)
+
       # @return [String, nil] the session's id (nil before the first one)
       def session_id = @host.session_id.call
 

data/lib/samagotchi/reasoning_history.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "setting_explained"
+
+module Samagotchi
+  # Which of its own reasoning a chat host's model gets back
+  # (LLM::ChatLoop sends it as reasoning_content on its earlier replies):
+  #
+  #   turn  the running turn's replies only (the tool-call rounds since the
+  #         last user message); what Qwen's, Gemma 4's and DeepSeek's
+  #         templates and the hosted APIs expect
+  #   drop  none
+  #   all   every reply that has reasoning, earlier turns too (a direct
+  #         DeepSeek API with tools wants this)
+  #
+  # Order (#resolve): the session's own level (/reasoning-history), then
+  # SAMAGOTCHI_REASONING_HISTORY, models.<key>.reasoning_history,
+  # hosts.<name>.reasoning_history, then turn. Native hosts ignore it:
+  # KernelLoop keeps the running turn's reasoning on its own.
+  module ReasoningHistory
+    LEVELS = %i[drop turn all].freeze
+    DEFAULT = :turn
+    KEY = "reasoning_history"
+    ENV_NAME = "SAMAGOTCHI_REASONING_HISTORY"
+    # The source a session's own level reads as.
+    SESSION_SOURCE = "session"
+    # The word that unsets a session's own level.
+    UNSET = "default"
+
+    module_function
+
+    # A session's own level from its file or a command word: :drop, :turn
+    # or :all (an explicit turn is the session's own too); nil for anything
+    # else, default included. Never warns: a session file keeps a value it
+    # can't read as written.
+    # @return [Symbol, nil]
+    def session_level(value)
+      return value if LEVELS.include?(value)
+      return nil unless value.is_a?(String)
+
+      level = value.strip.downcase.to_sym
+      LEVELS.include?(level) ? level : nil
+    end
+
+    # A configured value as a level; nil when unset or not a level (that
+    # warns once, naming +where+).
+    # @return [Symbol, nil]
+    def level(value, where)
+      return nil if value.nil?
+
+      text = value.to_s.strip.downcase
+      return text.to_sym if LEVELS.include?(text.to_sym)
+
+      ConfigFile.warn_once "Warning: #{where}: #{KEY} must be one of #{LEVELS.join(", ")}; ignored"
+      nil
+    end
+
+    # The level for +target+ and where it came from ("session",
+    # "SAMAGOTCHI_REASONING_HISTORY", "models: qwen", "hosts.work"; nil for
+    # the default).
+    # @param target [HostRegistry::ModelTarget]
+    # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
+    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param session [Symbol, nil] the session's own level (Session#reasoning_history)
+    # @return [Array(Symbol, String|nil)]
+    def resolve(target, names:, models: nil, session: nil)
+      return [session, SESSION_SOURCE] if session
+
+      env = env_level
+      return [env, ENV_NAME] if env
+
+      models ||= begin
+        ConfigFile.model_settings
+      rescue StandardError
+        {}
+      end
+      setting = ConfigFile.model_setting(names, :reasoning_history, models: models)
+      return [setting.value, "models: #{setting.key}"] if setting
+
+      host = target.entry&.reasoning_history
+      return [host, "hosts.#{target.entry.name}"] if host
+
+      [DEFAULT, nil]
+    end
+
+    # #resolve, as a SettingExplained with the session's own level beside it.
+    # @return [SettingExplained]
+    def explain(target, names:, models: nil, session: nil)
+      level, source = resolve(target, names: names, models: models, session: session)
+      SettingExplained.new(level: level, source: source, own: session)
+    end
+
+    # What changing the level from +from+ to +to+ costs +target+'s prompt
+    # cache, at a turn boundary (a change waits for the turn's end):
+    #   :history  to or from all on a chat host, with an earlier model entry
+    #             that has thinking: every earlier reply from there gains or
+    #             loses its reasoning_content, so a server that renders it
+    #             (hosted APIs; llama.cpp's default) reads the conversation
+    #             again from the first earlier thought;
+    #   nil       drop <-> turn (a turn's first request carries no reasoning
+    #             under either), no change, nothing thought yet, or a
+    #             native host (it ignores the level).
+    # @param conversation [Array<Hash>] the session's messages
+    # @return [Symbol, nil]
+    def cache_cost(from, to, target:, conversation:)
+      return nil unless target.entry&.chat?
+      return nil if from == to || ![from, to].include?(:all)
+
+      earlier_thought?(conversation) ? :history : nil
+    end
+
+    # Whether +conversation+ has a model entry with thinking (what all
+    # sends back as reasoning_content; LLM::ChatLoop#thought?).
+    def earlier_thought?(conversation)
+      Array(conversation).any? do |entry|
+        entry[:role].to_s == "model" && entry[:thinking].is_a?(String) && !entry[:thinking].strip.empty?
+      end
+    end
+
+    # "drop (models: qwen)", "turn (default)".
+    def label(level, source) = "#{level} (#{source || "default"})"
+
+    # SAMAGOTCHI_REASONING_HISTORY as a level, nil when unset or unknown.
+    def env_level
+      raw, origin = Config.get_with_origin(KEY)
+      origin == :env ? level(raw, ENV_NAME) : nil
+    rescue StandardError
+      nil
+    end
+  end
+end