samagotchi 0.152.0 → 0.154.0

data/lib/samagotchi/engine/toolkit.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The session's toolkit: the kits and what a turn declares
+    # (ToolkitBinding, forwarded), ctx.load_tools and the staged loads a turn
+    # appends, and System 1's toolkit suggestion (start, settle, warm-up).
+    # Writes @toolkit_warmup_thread; reads @toolkit_binding, @tools,
+    # @tool_index, @tool_loads, @side_judgments, @session.
+    module ToolkitPart
+      private
+
+      # The session's toolkit (ToolkitBinding): the kits, what its next turn
+      # declares, ctx.use_toolkit and the turn-start apply.
+      def toolkit_kits(errors = []) = @toolkit_binding.kits(errors)
+      def resolved_toolkit(session, errors = []) = @toolkit_binding.resolved(session, errors)
+      def toolkit_explained(toolkit = nil) = @toolkit_binding.explained(toolkit)
+      def toolkit_summary = @toolkit_binding.summary
+
+      # The tools this session registered (Tools::Registry), declared or not.
+      attr_reader :tools
+
+      public :tools, :toolkit_kits, :resolved_toolkit, :toolkit_explained, :toolkit_summary
+
+      # A plugin's ctx.load_tools: stage the reachable tools +names+ names
+      # (Tools::ToolIndex#deferred_name) that the session neither declares
+      # nor loaded with an earlier tool change, for bundle +bundle+. A name
+      # that names no tool at all is logged; a declared or removed one is
+      # skipped quietly.
+      # @return [Array<String>] the wire names staged
+      def load_tools(names, bundle)
+        added = ToolLoads.added(@session&.messages)
+        wanted = names.filter_map do |name|
+          wire = @tool_index.deferred_name(name)
+          Log.info(:plugins, "load_tools_skipped", bundle: bundle, tool: name) unless wire || @tools.key?(name)
+          wire
+        end
+        @tool_loads.stage(wanted - added, by: bundle)
+      end
+      public :load_tools
+
+      # The staged tool loads, appended to +turn+'s messages (after its user
+      # message, or the trailing results and notes of a turn with none) as
+      # one ToolLoads entry per bundle, when the turn's host takes tool
+      # changes (ChatLoop#tool_changes?). Elsewhere they are dropped, logged.
+      # A conversation that ends with a reply keeps them staged (a system
+      # change must follow a user turn).
+      def append_tool_loads(turn)
+        return unless @tool_loads.any?
+        return if turn.messages.last&.dig(:role).to_s == "model"
+
+        model = effective_model
+        host = backend(model)
+        staged = @tool_loads.take
+        added = ToolLoads.added(turn.messages)
+        unless host.respond_to?(:tool_changes?) && host.tool_changes?(bare_model_name(model.name))
+          Log.info(:plugins, "tool_loads_not_sent", tools: staged.values.flatten.join(","), model: model.name.to_s)
+          return
+        end
+
+        staged.each do |bundle, names|
+          names -= added
+          next if names.empty?
+
+          turn.messages << ToolLoads.entry(names, by: bundle)
+          hook_notify("tools loaded: #{names.join(", ")}", :info, bundle)
+        end
+      end
+      private :append_tool_loads
+
+      # A plugin's ctx.use_toolkit (ToolkitBinding#use).
+      # @return [Boolean] whether it was staged
+      # @raise [ArgumentError] an unknown toolkit
+      def use_toolkit(name) = @toolkit_binding.use(name)
+      public :use_toolkit
+
+      # At a turn's start (ToolkitBinding#apply!).
+      # @return [Boolean] whether the declared tools changed
+      def apply_toolkit!(session, on_event = nil) = @toolkit_binding.apply!(session, on_event)
+      private :apply_toolkit!
+
+      # Start the toolkit classifier after :turn_started, for audit and on
+      # mode alike (one eligibility, one snapshot, one thread). All session
+      # and tool-registry reads happen here; the thread receives only this
+      # snapshot. Audit never blocks: the thread logs its line. On mode
+      # returns the ask's Pending, which the turn joins before apply_toolkit!
+      # (#settle_toolkit_suggestion), with the turn's controller as the
+      # request's cancel controller.
+      # @return [ToolkitSuggest::Pending, nil] nil unless the turn joins an ask
+      def start_toolkit_suggestion(turn)
+        mode = Config.get("toolkit.suggest.mode").to_s
+        return if mode == "off"
+
+        joined = mode == "on"
+        session = turn.session
+        default = Toolkit.of(session.toolkit)
+        log = toolkit_suggestion_log
+        # The predicate checks the session first; the kits (memory kits are
+        # read from disk) and the log (read whole) only when it gets there.
+        kits = nil
+        candidates = nil
+        return unless ToolkitSuggest.eligible?(
+          session: session, prompt: turn.prompt, author: turn.origin.author,
+          candidate_count: lambda {
+            kits = @toolkit_binding.kits
+            candidates = ToolkitSuggest.candidates(kits, default_name: default.name)
+            candidates.size
+          },
+          last_suggestion: -> { ToolkitSuggest.last_suggestion(log, session.id) },
+          defer_turns: Config.get("toolkit.suggest.defer_turns"),
+          defer_tokens: Config.get("toolkit.suggest.defer_tokens")
+        )
+
+        # One ask at a time: an eligible turn while the last one still runs
+        # goes unasked, and says so.
+        if @side_judgments.in_flight?(:toolkit)
+          Log.info(:toolkit, "toolkit_suggest_in_flight_skipped", session_id: session.id)
+          return
+        end
+
+        client = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit),
+                                      ToolkitSuggest::JUDGMENT, session, mode: Config.get("toolkit.suggest.mode").to_s)
+        return unless client
+
+        # The warm-up's only value is the cache: the real ask never queues
+        # behind it.
+        stop_toolkit_warmup
+
+        # Rules, not tool lists: this runs before await_init_tasks and
+        # apply_staged_tools!, so a first turn's plugin/MCP tools aren't
+        # registered yet; the report expands the rules (ToolkitSuggest.rules).
+        snapshots = candidates.map do |kit|
+          ToolkitSuggest::Candidate.new(name: kit.name.dup.freeze, description: kit.description.dup.freeze,
+                                        rules: ToolkitSuggest.rules(Toolkit.resolve_kit(kit.name, kits)))
+        end.freeze
+        default_snapshot = ToolkitSuggest::Candidate.new(name: default.name.dup.freeze, description: nil,
+                                                         rules: ToolkitSuggest.rules(default.resolve(kits)))
+        registered = @tools.entries(toolkit: nil).reject { |entry| entry.source == Tools::ToolIndex::SOURCE }
+        core_tools, plugin_tools = registered.partition(&:core?).map { |entries| entries.map { |entry| entry.name.dup.freeze }.freeze }
+        state = ToolkitSuggest.question(
+          default: default, kits: kits, project: File.basename(session.project_root.to_s),
+          prompt: turn.prompt
+        ).last
+        snapshot = ToolkitSuggest::Snapshot.new(
+          session_id: session.id.dup.freeze, turn_number: ToolkitSuggest.turn_number(session.messages),
+          default: default_snapshot, candidates: snapshots, core_tools: core_tools, plugin_tools: plugin_tools,
+          state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
+        )
+        threshold = Config.get("toolkit.suggest.threshold")
+        runs = session.scratch ? nil : system_one_runs
+        pending = ToolkitSuggest::Pending.new(log: log, joined: joined,
+                                              acted: runs && ->(judged, did) { runs.acted(judged.fields[:run_id], did) },
+                                              timeout_seconds: SystemOne::Client.configured_timeout_ms / 1000.0)
+        # On mode: cut by a Stop while the turn waits (Pending#wait), not
+        # by one after it went on; audit's ask is never cut.
+        controller = joined ? pending.cancel_controller : nil
+        @side_judgments.start(:toolkit, warn: ToolkitSuggest.method(:warn), finish: pending.method(:finish)) do
+          ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
+                               cancel_controller: controller)
+        end
+        joined ? pending : nil
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        nil
+      end
+      private :start_toolkit_suggestion
+
+      # On mode, before apply_toolkit!: wait for the ask (#start_toolkit_
+      # suggestion) up to System 1's timeout from its start, or until a Stop,
+      # and put the session on a candidate picked with confidence ≥ threshold
+      # (ToolkitBinding#suggest: origin suggested, saved, the notice). Any
+      # other outcome (the default, below threshold, undecided, no judgment,
+      # a timeout, a Stop) leaves the session on its default. Nothing here
+      # sends a request; prepare_turn's cancel check ends a stopped turn. A
+      # Stop wins over an answer already in (Pending#wait checks it first).
+      def settle_toolkit_suggestion(turn, pending)
+        return if pending.nil?
+
+        outcome, judged = pending.wait(turn.controller)
+        if outcome == :timeout
+          # The session starts on its default without a word otherwise: a
+          # slow System 1 host (a local one) is the usual cause.
+          timeout_ms = SystemOne::Client.configured_timeout_ms
+          Log.warn(:toolkit, "toolkit_suggest_timeout", session_id: turn.session.id, timeout_ms: timeout_ms,
+                                                        reason: "System 1 gave no answer within system_one.timeout_ms")
+          @toolkit_binding.fell_back(turn.session, "System 1 took over #{timeout_ms} ms")
+          return
+        end
+        unless outcome == :answered
+          Log.info(:toolkit, "toolkit_suggest_#{outcome}", session_id: turn.session.id)
+          return
+        end
+        return if judged.nil?
+
+        pending.record(toolkit_suggestion_outcome(turn.session, judged))
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        pending&.record("failed")
+      end
+      private :settle_toolkit_suggestion
+
+      # What the turn does with an answered ask, as the log line's did:
+      # suggested (switched), chosen (the toolkit isn't the default any
+      # more), unavailable (the kit is gone), defer or default.
+      def toolkit_suggestion_outcome(session, judged)
+        case judged.would
+        when "suggested"
+          return "chosen" unless session.toolkit_origin == "default"
+          return "unavailable" unless @toolkit_binding.kits.key?(judged.suggestion.kit)
+
+          switched = @toolkit_binding.suggest(session, judged.suggestion.kit, confidence: judged.suggestion.confidence,
+                                                                              deferred: ToolkitSuggest.model_reply?(session.messages))
+          switched ? "suggested" : "chosen"
+        when "defer" then "defer"
+        when "no_judgment"
+          # System 1 failed (its own warn) or answered nothing usable.
+          @toolkit_binding.fell_back(session, "System 1 gave no answer")
+          "default"
+        else "default"
+        end
+      end
+      private :toolkit_suggestion_outcome
+
+      # On mode, as an idle worker starts (Worker#start_background): one ask
+      # with the real question and a stand-in prompt, on its own thread,
+      # never logged and never waited for, so System 1's server has the
+      # question's prefix cached for the first prompt. Only for a session a
+      # first prompt could be asked for: origin default, no model reply, not
+      # a delegate child or a review session, at least two candidates; and
+      # not when the worker starts on a first prompt (that ask comes at once).
+      def warm_toolkit_suggestion!
+        return unless Config.get("toolkit.suggest.mode").to_s == "on"
+
+        session = @session
+        return if session.nil? || session.toolkit_origin != "default" || session.delegate? || session.review?
+        return if ToolkitSuggest.model_reply?(session.messages) || !session.last_prompt.to_s.strip.empty?
+
+        default = Toolkit.of(session.toolkit)
+        kits = @toolkit_binding.kits
+        return if ToolkitSuggest.candidates(kits, default_name: default.name).size < 2
+
+        client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
+        return unless client
+
+        project = File.basename(session.project_root.to_s)
+        @toolkit_warmup_thread = Thread.new do
+          ToolkitSuggest.warm(client: client, default: default, kits: kits, project: project)
+        end
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        nil
+      end
+      public :warm_toolkit_suggestion!
+
+      # A still-running warm-up, stopped: a real ask (or the worker leaving)
+      # doesn't wait behind it.
+      def stop_toolkit_warmup
+        @toolkit_warmup_thread&.kill
+        @toolkit_warmup_thread = nil
+      end
+      private :stop_toolkit_warmup
+
+      def toolkit_suggestion_log
+        SideJudgments.log(ToolkitSuggest.log_path(session_state_dir), tag: :toolkit, event: "toolkit_suggest_log_failed")
+      end
+      private :toolkit_suggestion_log
+    end
+  end
+end

data/lib/samagotchi/engine/turn_end.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # How a turn ends after #end_turn's step: the normal ending and its
+    # after-turn hooks, a stop before the model, the release, what an ending
+    # keeps (TurnEndings, forwarded), last_turn, the answer's display.
+    # Writes @last_context_status; reads @turn_endings, @turn_state,
+    # @steer_cut, @hooks, @session_observer, @client.
+    module TurnEndPart
+      # How the turn ended, on the session (Session#last_turn): the caller's
+      # save puts it in the file the session hub watches. Public for the
+      # Worker's turn that failed before it began (no #end_turn ran).
+      # @param limit [Integer, nil] the turn ran out of iterations at this
+      #   limit: "exhausted" => true, "limit" => N, so a wait with nobody to
+      #   answer the continue offer says so (ReplyWait, ParentReport "limit")
+      # @param origin [TurnOrigin] the turn's (TurnOrigin::NONE for no sender)
+      # @param event [Hash] the turn's end event (#stop_facts)
+      def record_last_turn(session, outcome, seconds, origin, event, limit: nil)
+        enqueued_id = origin.enqueued_id
+        session.last_turn = LastTurn.new(outcome: outcome, ended_at: Time.now.iso8601(3), seconds: seconds.round(1),
+                                         origin: origin.source, exhausted: limit ? true : nil, limit: limit,
+                                         enqueued_id: enqueued_id.to_s.empty? ? nil : enqueued_id.to_s,
+                                         author: origin.participant_author,
+                                         **stop_facts(event))
+      end
+
+      # Why a turn stopped (TurnEndings#stop_facts).
+      def stop_facts(event) = @turn_endings.stop_facts(event)
+      private :stop_facts
+
+      def save_quietly(session)
+        session.save(state_dir: session_state_dir)
+      rescue StandardError => e
+        Log.warn(:turn, "turn_end_save_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        nil
+      end
+      private :save_quietly
+
+      # Keep what the after_turn hooks presented as the answer's `display`
+      # and the refs they attached as its `display_refs` (AnswerRefs, one
+      # replace for both), and tell the observers (:answer_display, the
+      # display or nil, and how many refs), after the turn_completed they
+      # already had: the web re-reads the answer then. A turn_completed
+      # with display_pending (after_turn hooks were about to run) always gets
+      # one, `display: nil` when nothing was presented, so the web holds the
+      # answer's pop until then and never swaps it after. Terminals are not
+      # sinks of it; they printed the answer already. The session is saved by
+      # the caller, as after every turn.
+      def store_answer_display(session, display, refs, pending: false)
+        synchronize_events do
+          # A plugin that kept event[:refs] and calls it later gets nil: the
+          # list is stored now (and the turn is over on every path).
+          refs.close!
+          messages = Array(session.messages)
+          changed = display.changed? && messages.last.equal?(display.target)
+          added = refs.added? && messages.last.equal?(refs.target)
+          if changed || added
+            merged = messages.last.dup
+            merged[AnswerDisplay::KEY] = display.text if changed
+            merged[AnswerRefs::KEY] = refs.to_a if added
+            replace_session_messages(session, messages[0...-1] + [merged])
+            event = { type: :answer_display, display: changed ? display.text : nil }
+            event[:refs] = refs.count if added
+            @session_observer.notify(event)
+          elsif pending
+            @session_observer.notify({ type: :answer_display, display: nil })
+          end
+        end
+      end
+      private :store_answer_display
+
+      # A turn stopped before the model was asked (#prepare_turn returned
+      # false): canceled with nothing kept, like a Ctrl-C there; the result
+      # has no conversation, so a UI's checkpoint stands.
+      def stopped_before_model(turn)
+        reason = turn.controller.reason
+        end_turn(turn, "canceled") do |seconds|
+          [nil, { type: :turn_canceled, cancellation_reason: reason, cancelled_by: cancelled_by(turn),
+                  duration_ms: (seconds * 1000).round }]
+        end
+        LLM::ModelResult.new(text: "", canceled: true, cancellation_reason: reason)
+      end
+      private :stopped_before_model
+
+      # Who stopped a turn a hook stopped or cut (the controller's detail: the
+      # bundle, or the hook's label), for the UIs' "stopped by loop-guard";
+      # nil for any other cancel.
+      def cancelled_by(turn) = turn.controller.stopped_by
+      private :cancelled_by
+
+      # The normal ending (an answer, an empty answer, a Stop, the iteration
+      # limit), then the after-turn hooks.
+      def complete_turn(turn, result)
+        canceled = result.canceled?
+        # after_turn hooks run below and may present the answer (the web
+        # holds its pop until it knows).
+        display_pending = !canceled && @hooks.any?(:after_turn)
+        end_turn(turn, canceled ? "canceled" : "completed", exhausted: !canceled && result.exhausted?) do |seconds|
+          kept = kept_messages(turn, result, seconds)
+          if canceled
+            [kept, { type: :turn_canceled, cancellation_reason: result.cancellation_reason, cancelled_by: cancelled_by(turn),
+                     duration_ms: (seconds * 1000).round }]
+          else
+            # For a client that attaches later (session_state_snapshot).
+            @last_context_status = result.context_status.dup if result.context_status
+            [kept, { type: :turn_completed, result: result, turn_summary: turn_summary(result),
+                     display_pending: display_pending }]
+          end
+        end
+
+        # Fire :after_turn hook (an answer or a Stop; an Interrupt or a failure
+        # ends the turn in #run_turn without it), with a read-only
+        # copy of the conversation the turn stored, event[:answer] (the answer's
+        # text: the native loop's stored message still holds its thought),
+        # event[:present] for
+        # a display version of the answer (AnswerDisplay) and event[:refs]
+        # for refs on it (AnswerRefs).
+        session = turn.session
+        audit_objectives_outgoing(turn, result) unless canceled || result.exhausted?
+        display = AnswerDisplay.new(session.messages)
+        refs = AnswerRefs.new(session.messages, cwd: session.working_directory)
+        after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",
+                       messages: hook_messages(session.messages),
+                       answer: (result.text unless canceled || result.exhausted?) }
+        after_turn[:present] = display.presenter(after_turn)
+        after_turn[:refs] = refs.adder(after_turn)
+        @hooks.fire(:after_turn, after_turn)
+        store_answer_display(session, display, refs, pending: display_pending)
+
+        # Fire :session_end after the turn (turn-level lifecycle), as :after_turn
+        @hooks.fire(:session_end, { type: :session_end, session_id: session.id })
+      end
+      private :complete_turn
+
+      # What each turn ending keeps and announces is TurnEndings'
+      # (#build_turn_endings); these forward to it.
+      def kept_messages(turn, result, seconds) = @turn_endings.kept_messages(turn, result, seconds)
+      private :kept_messages
+      def ctrl_c_messages(turn, interrupt, seconds) = @turn_endings.ctrl_c_messages(turn, interrupt, seconds)
+      private :ctrl_c_messages
+      def loop_conversation(error) = @turn_endings.loop_conversation(error)
+      private :loop_conversation
+      def failed_messages(turn, error) = @turn_endings.failed_messages(turn, error)
+      private :failed_messages
+      def failed_event(error, seconds) = @turn_endings.failed_event(error, seconds)
+      private :failed_event
+
+      # However the turn ended (#run_turn's ensure): the turn flag off, the
+      # probe cancel restored, the cancel controller, sink and steers cleared
+      # (a steer left is logged as dropped), activity recorded, the
+      # turn-scoped hooks cleared.
+      def release_turn(probe_cancel_before)
+        # A completed turn is activity: release the turn flag and advance the
+        # shared inactivity clock so the idle recap detector
+        # treats the just-finished turn as activity and re-arms its window.
+        left = @turn_state.finish!
+        @steer_cut.finished!
+        Client.swap_probe_cancel(probe_cancel_before)
+        # The next turn's window and served model are asked again: the cache
+        # (this host's, process-wide) is dropped here, at the turn's end,
+        # rather than at its start, so what this turn read (the profile's own
+        # probe included) is not asked for a second time within the turn. A
+        # restart with another -c between turns is still noticed: the next
+        # turn's first probe goes to the server.
+        @client.invalidate_context_window!
+        log_dropped_steers(left, "turn_ended")
+        record_activity
+        # Clear hooks so they remain turn-scoped and never leak into the next turn.
+        clear_hooks
+      end
+      private :release_turn
+
+      # JSON-safe digest of a finished turn for renderers (TurnEndings#turn_summary).
+      # @param result [LLM::ModelResult]
+      # @return [Hash]
+      def turn_summary(result) = @turn_endings.turn_summary(result)
+    end
+  end
+end

data/lib/samagotchi/engine/turn_helpers.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # What a turn's steps use before and around the model: its settings,
+    # images and vision, the model ref and resumed run start it generates
+    # with, the used memories it publishes, and the turn-end warm-up of the
+    # next one. Writes @next_turn_waiting; reads @model_settings, @kernel,
+    # @prompt_warmup, @thinking_notices, @turn_state.
+    module TurnHelpersPart
+      # The turn's settings for the kernel (LLM::TurnSettings): vision,
+      # sampling and thinking, the thinking resolved before the hooks run.
+      # The model name is added in #generate, after the hooks that may switch
+      # the model.
+      # One resolve for all of them: nothing runs between them that could
+      # change what a resolve gives.
+      def turn_settings(session)
+        model = effective_model
+        vision = turn_vision(session, model)
+        sampling = model.sampling
+        level = @model_settings.thinking_level(model)
+        @thinking_notices.turn_started(level, model.target)
+        LLM::TurnSettings.new(vision: vision, sampling: sampling, thinking: level,
+                              reasoning_history: @model_settings.reasoning_history_level(model), model_name: nil,
+                              window_setting: nil, llm_context: nil, price: nil)
+      end
+      private :turn_settings
+
+      # @return [PromptWarmup] the turn-end warm-up (specs, measurements)
+      attr_reader :prompt_warmup
+
+      # A caller's check that the next turn starts at once (input queued for
+      # it: a worker's inbox) or that none follows (a one-shot run): no
+      # warm-up then. nil: neither.
+      attr_accessor :next_turn_waiting
+
+      # After a completed turn, prefill the next turn's prompt up to its user
+      # message while the user reads (PromptWarmup, cache.warmup). Only on a
+      # local llama.cpp host on the native loop, and not when the next turn's
+      # start differs anyway or starts at once: a reminder due, a continue
+      # offer (the turn ran out of steps), a carried steer or queued input.
+      # Never fails the turn.
+      def warm_up_next_turn(turn, result)
+        return if result.canceled? || result.resumable?
+
+        model = effective_model
+        client = model.client
+        return unless warmup_target?(model, client)
+        return if reminders_due? || @turn_state.carried_steers? || @next_turn_waiting&.call
+
+        messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: system_prompt(model) })
+        # Under the next turn's strategy (a /model switch may have changed it);
+        # the last turn's when it can't be resolved.
+        prompt, images = @kernel.warmup_prompt(messages, llm_context: @model_settings.turn_llm_context || @kernel.turn_settings&.llm_context)
+        return unless prompt
+
+        started = @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
+                                       slot: @kernel.last_slot, images: images)
+        @kernel.warmed_up! if started
+      rescue StandardError => e
+        Log.warn(:model, "warmup_skipped", error: e.class.name, msg: e.message.to_s[0, 200])
+      end
+      private :warm_up_next_turn
+
+      # Never a paid or remote host (cache.warmup auto means local only), nor
+      # the chat loop (Splash keeps its own cache; llama.cpp's chat path is
+      # not measured), nor a client that can't warm up (a spec's stub).
+      def warmup_target?(model, client)
+        return false if model.chat? || model.entry.remote?
+        return false unless client.respond_to?(:warm_up)
+
+        PromptWarmup.enabled?
+      end
+      private :warmup_target?
+
+      # The ref (host:model, as asked) a turn's generations ran on: the model
+      # #generate resolved, after the before_turn hooks (which may switch it).
+      # SessionMetrics keys its per-model segments on it. nil when it can't be
+      # named (the turn's record then has none).
+      def generation_model_ref(model)
+        model.ref
+      rescue StandardError => e
+        Log.warn(:turn, "model_ref_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        nil
+      end
+      private :generation_model_ref
+
+      # A step-limit Continue's resume_from, when it is inside the messages the
+      # run gets (a wrong one only drops reasoning: it is ignored, logged).
+      # Entries before it never move between the turns (#turn_messages adds
+      # at the tail, and the system head is replaced in place).
+      def resumed_run_start(turn, run_start)
+        start = turn.resume_from
+        return nil if start.nil?
+        return start if start.is_a?(Integer) && start.between?(0, run_start)
+
+        Log.warn(:turn, "resume_start_invalid", resume_from: start, length: run_start)
+        nil
+      end
+      private :resumed_run_start
+
+      # The turn's LLM context strategy and where it came from, in the turn
+      # log: when it runs a layer, or the session set it (none too).
+      def log_llm_context(explained)
+        return unless explained
+        return if explained.resolved.active_layers.empty? && explained.strategy.source != :session
+
+        summary = explained.summary
+        Log.info(:turn, "llm_context", **summary.slice(:strategy, :strategy_source, :apply, :apply_source, :budget_tokens,
+                                                       :budget_source).compact)
+      end
+      private :log_llm_context
+
+      def publish_used_memories(session, on_event)
+        # Persist deduped used memories onto the session for Web + reload.
+        begin
+          session.used_memory_names = used_memory_names
+        rescue StandardError => e
+          Log.warn(:memory, "used_memories_store_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        end
+        # Notify live observers of the updated memory list (so yellow bar refreshes
+        # even without a tool_call event if the preload was the only addition).
+        # Only emit when there is something to report to avoid noisy event_count drift.
+        return unless used_memory_names.any?
+
+        begin
+          emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names })
+        rescue StandardError => e
+          Log.warn(:memory, "used_memories_emit_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        end
+      end
+      private :publish_used_memories
+
+      # [refs, nil] for a turn's images, or [[], error] when one can't be used
+      # (the turn then fails right after :turn_started).
+      def turn_image_refs(session, images)
+        return [[], nil] if Array(images).empty?
+
+        [ImageStore.resolve_all(Session.session_dir(session.id, state_dir: session_state_dir), images), nil]
+      rescue ImageStore::Error => e
+        [[], e]
+      end
+
+      # The turn's VisionContext: the session's images folder, and whether the
+      # effective model can see images, asked only when a request carries one.
+      def turn_vision(session, model = effective_model)
+        VisionContext.new(session_dir: Session.session_dir(session.id, state_dir: session_state_dir),
+                          capability: -> { model.vision_support(profile) })
+      end
+
+      # A model known not to see images fails a turn with images up front.
+      def refuse_images!(vision)
+        return if vision.sendable?
+
+        host = effective_model.host_name
+        raise LLM::VisionUnsupported.new("#{host}: #{vision.refusal_reason}", host: host)
+      end
+    end
+  end
+end