samagotchi 0.10.1 → 0.12.0

data/lib/samagotchi/kernel_loop.rb

@@ -20,7 +20,10 @@ require_relative "tools/builtins"
 require_relative "muted_memories"
 require_relative "tool_activity"
 require_relative "tool_runner"
+require_relative "tool_response"
 require_relative "answer_display"
+require_relative "llm/model_result"
+require_relative "llm/turn_settings"
 
 module Samagotchi
   # The KernelLoop drives the model ↔ tool interaction cycle.
@@ -36,30 +39,12 @@ module Samagotchi
   #   - Gemma 4: <|tool_call>call:NAME{params}<tool_call|>
   #   - Qwen 3.6: <tool_call><function=NAME><parameter=KEY>VALUE</parameter></function></tool_call>
   class KernelLoop
-    Result = Struct.new(:output, :conversation, :exhausted, :pending_tool_calls, :tool_activity, :canceled, :cancellation_reason, :context_status, keyword_init: true) do
-      def exhausted?
-        exhausted
-      end
-
-      def pending_tool_calls?
-        pending_tool_calls
-      end
-
-      def resumable?
-        exhausted? && pending_tool_calls?
-      end
-
-      def canceled?
-        canceled
-      end
-    end
-
     # The built-in tool classes (Tools::Builtins registers them).
     TOOLS = Tools::Builtins::CLASSES
 
     # What a tool handler (call, kctx) gets from the kernel: the reminder
     # store, the peers, the model key, and the memory read and ask-user
-    # flows that need its state.
+    # flows that need its state (read through the kernel's public readers).
     class ToolContext
       def initialize(kernel)
         @kernel = kernel
@@ -68,8 +53,44 @@ module Samagotchi
       def reminder_store = @kernel.reminder_store
       def peers = @kernel.peers
       def model_key = @kernel.model_key
-      def muted_memory_read(call) = @kernel.__send__(:muted_memory_read, Tools::MemoryRead, call)
-      def ask_user_question(call) = @kernel.__send__(:handle_ask_user_question, call)
+
+      # memory_read with the session's mutes applied: a blank name (the index)
+      # loses the muted memories' lines; a muted name in a comma list is
+      # refused with its own error line and the rest is read as usual.
+      def muted_memory_read(call)
+        muted = Array(@kernel.muted_memory_names)
+        content = call[:content].to_s
+        read = lambda do |names|
+          Tools::MemoryRead.call(names, scope: call[:scope], model_key: model_key, fallback_model_key: @kernel.model_key_fallback)
+        end
+        return read.call(content) if muted.empty?
+        return MutedMemories.filter_index(read.call(content), muted) if content.strip.empty?
+
+        names = Tools::MemoryRead.parse_names(content)
+        refused, allowed = names.partition { |name| MutedMemories.muted?(name, muted) }
+        return read.call(content) if refused.empty?
+
+        errors = refused.map { |name| "Error: memory '#{name}' is muted for this session" }
+        return errors.join("\n") if allowed.empty?
+
+        [read.call(allowed.join(",")), *errors].join(Tools::MemoryRead::SEPARATOR)
+      end
+
+      # ask_user_question: validate the call, then hand the payload to the
+      # Engine's question flow (the kernel's question_handler, which blocks
+      # until the user answers). Without one (headless), the payload as JSON
+      # so the model sees the options and can ask in plain text.
+      def ask_user_question(call)
+        payload = Tools::AskUserQuestion.validate(call)
+        return payload if payload.is_a?(String)
+
+        handler = @kernel.question_handler
+        return JSON.pretty_generate(payload) unless handler
+
+        handler.call(payload).to_s
+      rescue StandardError => e
+        "Error: ask_user_question handler failed: #{e.message}"
+      end
     end
 
     DEFAULT_MAX_TOOL_OUTPUT_CHARS = 10_000
@@ -78,17 +99,16 @@ module Samagotchi
 
     # @param tools [Tools::Registry, nil] the tools calls dispatch to (the
     #   Engine's; nil: the built-ins alone)
-    def initialize(client: nil, profile: nil, model_name: nil, no_interrupt: false, hooks: nil, reminder_store: nil, model_key: nil,
-                   tools: nil)
+    def initialize(client: nil, profile: nil, model_name: nil, hooks: nil, reminder_store: nil, model_key: nil, tools: nil)
       @client = client || Client.new
       @tools = tools || Tools::Builtins.default
-      @no_interrupt = no_interrupt
       resolved_model_name = ModelProfile.required_model_name(model_name)
-      # The resolved model id actually used for this run (per-run override wins
+      # The turn's settings (LLM::TurnSettings). Its model name is the
+      # resolved model id actually used for this run (per-run override wins
       # over the config alias); on every debug dump so we can see exactly
-      # which model each request went to. The Engine sets it per turn too:
+      # which model each request went to. The Engine sets them per turn:
       # the chat loop dispatches tools here without going through #run.
-      @current_model_name = resolved_model_name
+      @turn_settings = LLM::TurnSettings.none.with(model_name: resolved_model_name)
       @profile = profile ? ModelProfile.normalize(profile) : ModelProfile.from_model_name(resolved_model_name)
       # Where @profile came from, as /stats shows it (a Resolution's label
       # once the Engine resolves one, see #use_profile!).
@@ -96,26 +116,28 @@ module Samagotchi
       @hooks = hooks
       @reminder_store = reminder_store
       @model_key = model_key
+      @model_key_fallback = nil
     end
 
-    # @return [ReminderStore, nil] the reminder store for inspection (used by
-    #   Engine to share the same store with the KernelLoop when TerminalUI
-    #   creates both).
-    attr_reader :reminder_store
+    # @return [ReminderStore, nil] the reminder store the reminder tools
+    #   write; the Engine's own (it hands it to a kernel it was given).
+    attr_accessor :reminder_store
 
     # @return [ModelProfile] the active prompt profile
     attr_reader :profile
 
     # @return [Samagotchi::Hooks::Registry, nil] hooks registry shared with Engine.
     #   Engine owns the registry; KernelLoop only fires events. Accessor allows
-    #   Engine to propagate its registry to an externally-created kernel (TUI path).
+    #   Engine to hand its registry to a kernel it is given (specs).
     attr_accessor :hooks
     # @return [Tools::Registry] the tools #dispatch runs. The Engine sets
-    #   its own on a kernel built before it (the REPL's), as with hooks.
+    #   its own on a kernel it is given, as with hooks.
     attr_accessor :tools
     attr_accessor :client
     attr_accessor :model_key
-    attr_accessor :current_model_name
+    # @return [String, nil] the key whose overlay memory_read takes when
+    #   #model_key has none (#sync_model_key!)
+    attr_reader :model_key_fallback
     # @return [Array<String>, nil] the session's muted memories (normalized
     #   names, see MutedMemories); memory_read refuses them. The Engine sets it.
     attr_accessor :muted_memory_names
@@ -125,15 +147,11 @@ module Samagotchi
     # The Guardrails::Gate ToolRunner asks before each call; the Engine sets
     # it (nil: ToolRunner's own, hooks only).
     attr_accessor :guardrail_gate
-    # The turn's VisionContext (images: capability, files, limits), set by
-    # the Engine per turn; nil sends no images (placeholders instead).
-    attr_accessor :vision
-    # The turn's request parameters (SamplingSettings.for), set by the Engine
-    # per turn; empty or nil sends none.
-    attr_accessor :sampling
-    # The turn's thinking level (Thinking.resolve), set by the Engine per
-    # turn; its own accessor, since the native path sends @sampling as is.
-    attr_accessor :thinking
+    # @return [LLM::TurnSettings] the turn's vision, sampling, thinking and
+    #   model name, set by the Engine per turn (#run sets the model name
+    #   too); the thinking level is its own field, since the native path
+    #   sends the sampling as is.
+    attr_accessor :turn_settings
     # Tools::Peers (or the Engine's live view of it): the session
     # list_sessions and send_note speak for; nil outside a session.
     attr_accessor :peers
@@ -142,7 +160,7 @@ module Samagotchi
     # resumable conversation state when execution stops at max_iterations.
     #
     # @param messages       [Array<Hash>]        conversation so far ({role:, content:});
-    #   a stopped run resumes from its Result#conversation
+    #   a stopped run resumes from its result's #conversation
     # @param max_iterations [Integer]            safety cap on tool-call rounds
     # @param on_stream_event [Proc, nil]         optional callback for generation events
     # @param cancel_controller [CancellationController, nil] optional cancellation source
@@ -155,275 +173,25 @@ module Samagotchi
     #   steering mid-stream); drained lines merge into ONE user message appended
     #   at the conversation tail (prefix KV cache preserved) and a
     #   :pending_input_merged stream event is emitted.
-    # @return [Result] final visible response with continuation metadata
+    # @return [LLM::ModelResult] final visible response with continuation metadata
     def run(messages, max_iterations: 100, on_stream_event: nil, cancel_controller: nil, model_name: nil, max_tool_output_chars: nil, pending_input: nil)
-      resolved_model_name = completion_model_name(model_name)
-      @current_model_name = resolved_model_name
-
-      conversation = prepare_conversation(messages)
-      context = ContextStatus.new(conversation: conversation)
-      exhausted = false
-      pending_tool_calls = false
-      tool_activity = []
-      qwen_recovery_attempts = 0
-      qwen_partial_tool_call = nil
-      empty_retries = 0
-      empty_retry_limit = EmptyAnswerRetry.limit
-      @retry_generation = false
-      # Qwen with thinking off: an empty thought after the cue, so the model
-      # answers at once. Kept in the turn's model messages, so each tool-loop
-      # prompt starts with what the server already has cached.
-      prefill = Thinking.native(@thinking || Thinking::DEFAULT, @profile).prefill
-      partial_assistant_buffer = +""
-
-      effective_max_iterations = @no_interrupt ? 1000 : max_iterations
-      effective_max_tool_output_chars = resolve_output_char_cap(max_tool_output_chars)
-      effective_max_iterations.times do |iteration_index|
-        inject_pending_input!(conversation, pending_input, on_stream_event, iteration_index + 1, cancel_controller)
-        prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @vision, prefill: prefill)
-        image_tokens = images.empty? ? 0 : ImagePlan.estimated_tokens(conversation)
-        context_window = ContextWindow.resolve(client: @client, model: resolved_model_name)
-        emit_context_status_event(on_stream_event, context, prompt, iteration_index: iteration_index, window: context_window,
-                                                                    image_tokens: image_tokens)
-        if (line = context.take_guidance)
-          # The model's own copy, on the tail (the prompt cache keeps its
-          # prefix), then the prompt again with it.
-          conversation << line
-          prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @vision, prefill: prefill)
-        end
-        # Each generation splits its own stream: one that ended inside a
-        # thought or a tool call doesn't leave the next one "inside" it.
-        stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
-        emit_stream_event(
-          on_stream_event,
-          type: :generation_started,
-          iteration: iteration_index + 1,
-          context_window_tokens: context_window.tokens,
-          context_window_source: context_window.source,
-          profile: @profile.name,
-          profile_source: @profile_source
-        )
-        served_model = nil
-        # This generation's own server counts (the run-long ones in
-        # `context` can be an earlier one's).
-        generation_usage = nil
-        # The thinking this generation streamed, for the log (a stuck
-        # thinking generation shows as thinking_chars=N content_length=…).
-        streamed_thinking = 0
-        # Fire :before_generation hook
-        gen_event = { type: :before_generation, iteration: iteration_index + 1 }
-        fire_hook(:before_generation, gen_event) if @hooks
-        # The request runs under the generation's own controller: a plugin's
-        # stop_generation cuts it alone, and the turn goes on (a cut).
-        buffer_mark = partial_assistant_buffer.length
-        cut = nil
-        response = with_generation(cancel_controller) do |generation_controller|
-          request_generation(
-            prompt,
-            generation_controller: generation_controller,
-            cancel_controller: cancel_controller,
-            model_name: resolved_model_name,
-            on_chunk: lambda { |chunk|
-              generation_usage = context.capture(chunk[:payload]) || generation_usage
-              # llama.cpp names the loaded model in the stream's last payload.
-              named = chunk[:payload]["model"] if chunk[:payload].is_a?(Hash)
-              served_model = named if named.is_a?(String) && !named.strip.empty?
-              split = stream_splitter.feed(chunk[:content])
-              partial_assistant_buffer << split[:text]
-              streamed_thinking += split[:thinking].to_s.length
-              if on_stream_event
-                emit_stream_event(
-                  on_stream_event,
-                  type: :generation_chunk,
-                  iteration: iteration_index + 1,
-                  content: chunk[:content],
-                  text: split[:text],
-                  thinking: split[:thinking],
-                  payload: chunk[:payload]
-                )
-              end
-            },
-            on_retry: lambda { |retry_event|
-              # The retry streams from the start: its counts replace these.
-              generation_usage = nil
-              streamed_thinking = 0
-              next unless on_stream_event
-
-              emit_stream_event(
-                on_stream_event,
-                {
-                  type: :generation_retrying,
-                  iteration: iteration_index + 1
-                }.merge(retry_event)
-              )
-            },
-            images: images
-          )
-        rescue Client::RequestCancelled
-          raise unless cut?(generation_controller, cancel_controller)
-
-          cut = generation_controller.detail || {}
-          ""
-        end
-        if cut
-          # The cut stream's visible text goes with it: the buffer as it was
-          # before (the next generation gets a fresh splitter).
-          partial_assistant_buffer.slice!(buffer_mark..)
-          emit_stream_event(on_stream_event, type: :generation_completed, iteration: iteration_index + 1,
-                                             content_length: 0, thinking_chars: streamed_thinking,
-                                             served_model: served_model, requested_model: resolved_model_name,
-                                             finish_reason: "stopped", stopped_by: cut[:by], stop_reason: cut[:reason])
-          # A Stop that came right after the cut is a plain cancel.
-          raise Client::RequestCancelled.new(cancel_controller.reason) if cancel_controller.cancelled?
-
-          if empty_retries < empty_retry_limit
-            # Queued input (the user's line, a plugin's steer) goes in place of the nudge.
-            next if inject_pending_input!(conversation, pending_input, on_stream_event, iteration_index + 1, cancel_controller)
-
-            empty_retries += 1
-            @retry_generation = true
-            emit_stream_event(on_stream_event, type: :empty_answer_retry, iteration: iteration_index + 1,
-                                               attempt: empty_retries, of: empty_retry_limit,
-                                               thinking_chars: streamed_thinking, stopped_by: cut[:by])
-            conversation << TurnNote.cut_retry(cut[:by], cut[:reason])
-            next
-          end
-          # No retry left: the turn ends as cancelled (hook), with nothing
-          # salvaged and without the spent nudge.
-          drop_last_empty_retry!(conversation)
-          cancel_controller.cancel!(:hook, cut)
-          emit_stream_event(on_stream_event, type: :generation_cancelled, iteration: iteration_index + 1, reason: :hook)
-          return cancelled_result(conversation, tool_activity: tool_activity, reason: :hook, partial_assistant_text: "")
-        end
-        context.generation_done(generation_usage, prompt_chars: prompt.length, image_tokens: image_tokens, window: context_window)
-        emit_stream_event(
-          on_stream_event,
-          type: :generation_completed,
-          iteration: iteration_index + 1,
-          content_length: response.to_s.length,
-          thinking_chars: thinking_chars(response.to_s, streamed_thinking),
-          served_model: served_model,
-          requested_model: resolved_model_name
-        )
-        dump_log("response", response, iteration: iteration_index + 1)
-        # Fire :after_generation hook (after LLM returns, before tool parse),
-        # with a read-only copy of the conversation as sent.
-        after_gen_event = { type: :after_generation, iteration: iteration_index + 1, response: response,
-                            messages: AnswerDisplay.strip_all(conversation).map(&:dup).freeze }
-        fire_hook(:after_generation, after_gen_event) if @hooks
-        conversation << { role: "model", content: prefill + response.to_s }
-
-        # Profile-specific parse (incl. Qwen unterminated-block recovery); the
-        # returned fragment (non-nil only for Qwen) is fed back on the next
-        # iteration if the model opened a tool-call block it did not close.
-        calls, qwen_partial_tool_call = parser.parse_with_recovery(response, qwen_partial_tool_call)
-        calls = calls.map do |call|
-          PromptLiteralGuard.restore_call(call, profile: @profile)
-        end
-        qwen_incomplete_tool_call = !qwen_partial_tool_call.nil?
-
-        if calls.empty?
-          if qwen_incomplete_tool_call && qwen_recovery_attempts < QWEN_INCOMPLETE_TOOL_CALL_RECOVERY_LIMIT
-            qwen_recovery_attempts += 1
-            conversation << { role: "user", content: QWEN_INCOMPLETE_TOOL_CALL_RECOVERY_PROMPT, preserve_literals: true }
-            pending_tool_calls = false
-            next
-          end
-
-          pending_tool_calls = false
-          answer = -> { PromptLiteralGuard.restore(strip_thought_blocks(response), profile: @profile) }
-          empty = strip_thought_blocks(response.to_s).strip.empty?
-          retry_empty = empty && empty_retries < empty_retry_limit && !cancel_controller&.cancelled?
-          # The empty generation goes (its thinking would be sent again and
-          # prime the same loop); an empty answer that will be retried is no
-          # answer site, so a plugin's steer joins the retry.
-          conversation.pop if retry_empty
-          unless inject_pending_input!(conversation, pending_input, on_stream_event, iteration_index + 1, cancel_controller,
-                                       answer: retry_empty ? nil : answer)
-            if retry_empty
-              empty_retries += 1
-              @retry_generation = true
-              emit_stream_event(on_stream_event, type: :empty_answer_retry, iteration: iteration_index + 1,
-                                                 attempt: empty_retries, of: empty_retry_limit,
-                                                 thinking_chars: thinking_chars(response.to_s, streamed_thinking))
-              conversation << TurnNote.empty_retry
-              next
-            end
-            # The Engine's TurnNote.empty says it all: the spent nudge goes.
-            drop_last_empty_retry!(conversation) if empty && empty_retries.positive?
-            break
-          end
-          # Queued steering keeps the turn going: loop again so the model
-          # answers the injected message instead of stopping here.
-          next
-        end
-
-        qwen_recovery_attempts = 0
-        qwen_partial_tool_call = nil
-
-        emit_stream_event(on_stream_event, type: :tool_dispatch_started, iteration: iteration_index + 1, call_count: calls.length)
-        tool_images = []
-        image_counts = []
-        shown_params = []
-        shown_labels = []
-        diffs = []
-        results = calls.map.with_index do |call, call_index|
-          run = tool_runner.run(call, iteration: iteration_index + 1, call_index: call_index + 1,
-                                      call_count: calls.length, on_stream_event: on_stream_event,
-                                      max_tool_output_chars: effective_max_tool_output_chars)
-          tool_activity << run[:activity]
-          tool_images.concat(Array(run[:images]))
-          image_counts << Array(run[:images]).size
-          shown_params << run[:shown_params]
-          shown_labels << run[:shown_label]
-          diffs << run[:diff]
-          run[:output]
-        end.join("\n\n---\n\n")
-        emit_stream_event(on_stream_event, type: :tool_dispatch_completed, iteration: iteration_index + 1, call_count: calls.length)
-        # The joined results carry every call's images, in call order.
-        tool_response = { role: "tool_response", content: results }
-        tool_response[:images] = tool_images unless tool_images.empty?
-        # How many of them each call returned, in call order, so the web's
-        # reload puts each on its own tool row; the prompt never reads it.
-        tool_response[:image_counts] = image_counts unless tool_images.empty?
-        # A plugin tool's params line, one per call in call order (nil for
-        # a built-in), for the web's reload; the prompt never reads it.
-        tool_response[:tool_params] = shown_params if shown_params.any?
-        tool_response[:tool_labels] = shown_labels if shown_labels.any?
-        # What each edit/write changed (nil for other calls), in call order,
-        # for the web's reload; the prompt never reads it.
-        tool_response[:tool_diffs] = diffs if diffs.any?
-        conversation << tool_response
-        pending_tool_calls = true
+      @turn_settings = @turn_settings.with(model_name: completion_model_name(model_name))
+      turn = start_turn(messages, on_stream_event: on_stream_event, cancel_controller: cancel_controller,
+                                  pending_input: pending_input, cap: resolve_output_char_cap(max_tool_output_chars))
+
+      max_iterations.times do |iteration_index|
+        turn.iteration = iteration_index + 1
+        outcome = iterate(turn)
+        return outcome if outcome.is_a?(LLM::ModelResult)
+        break if outcome == :answer
       rescue Client::RequestCancelled => e
-        emit_stream_event(
-          on_stream_event,
-          type: :generation_cancelled,
-          iteration: iteration_index + 1,
-          reason: e.reason
-        )
-        return cancelled_result(conversation, tool_activity: tool_activity, reason: e.reason, partial_assistant_text: partial_assistant_buffer)
-      end
-
-      if pending_tool_calls && tool_response_turn?(conversation.last)
-        exhausted = true
+        emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: e.reason)
+        return cancelled_result(turn.conversation, tool_activity: turn.tool_activity, reason: e.reason,
+                                                   partial_assistant_text: turn.buffer)
       end
-
-      output = strip_thought_blocks(last_model_content(conversation))
-      # A turn stopped at the limit ends on a call it never ran: show only its text.
-      output = parser.strip_tool_calls(output) if exhausted
-      Result.new(
-        output: PromptLiteralGuard.restore(output, profile: @profile),
-        conversation: duplicate_conversation(conversation),
-        exhausted: exhausted,
-        pending_tool_calls: pending_tool_calls,
-        tool_activity: tool_activity,
-        canceled: false,
-        cancellation_reason: nil,
-        context_status: context.display
-      )
+      finish(turn)
     rescue StandardError => e
-      LLM::FailedTurn.attach(e, conversation && duplicate_conversation(conversation))
+      LLM::FailedTurn.attach(e, turn && duplicate_conversation(turn.conversation))
       raise
     end
 
@@ -434,30 +202,277 @@ module Samagotchi
       @profile_source = resolution.label
     end
 
-    def sync_model_key!(key)
+    # @param fallback [String, nil] a key whose overlay memory_read takes
+    #   when +key+ has none (the alias a model was typed as)
+    def sync_model_key!(key, fallback: nil)
       @model_key = key
+      @model_key_fallback = fallback
     end
 
     private
 
-    # memory_read with the session's mutes applied: a blank name (the index)
-    # loses the muted memories' lines; a muted name in a comma list is
-    # refused with its own error line and the rest is read as usual.
-    def muted_memory_read(tool, call)
-      muted = Array(@muted_memory_names)
-      content = call[:content].to_s
-      read = ->(names) { tool.call(names, scope: call[:scope], model_key: @model_key) }
-      return read.call(content) if muted.empty?
-      return MutedMemories.filter_index(read.call(content), muted) if content.strip.empty?
+    # ── One turn (#run) ────────────────────────────────────────────────────────
+
+    # One run's state, threaded through its steps: the conversation, the
+    # context tracker and the retry budget, the tool activity, the visible
+    # text streamed so far (salvaged on a cancel), the Qwen recovery state,
+    # the prefill, and what the caller gave.
+    Turn = Struct.new(:conversation, :context, :empty_retry, :tool_activity, :buffer, :qwen_attempts, :qwen_partial,
+                      :prefill, :pending_tool_calls, :model_name, :pending_input, :on_stream_event,
+                      :cancel_controller, :cap, :emit, :iteration, keyword_init: true)
+    # One request: the prompt and its images as sent, the images' token
+    # estimate, and the window it was measured against.
+    Request = Struct.new(:prompt, :images, :image_tokens, :window, keyword_init: true)
+    # One generation: the response (nil when cut), the cut's detail, this
+    # generation's own server counts, the model the server named, the
+    # thinking it streamed, and why it stopped (the transport's finish
+    # reason, Client::Transport#finish_reason_from; nil when not named).
+    Generation = Struct.new(:response, :cut, :usage, :served_model, :streamed_thinking, :finish_reason, keyword_init: true)
+    private_constant :Turn, :Request, :Generation
+
+    def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:)
+      conversation = prepare_conversation(messages)
+      Turn.new(
+        conversation: conversation, context: ContextStatus.new(conversation: conversation),
+        empty_retry: EmptyAnswerRetry.new, tool_activity: [], buffer: +"", qwen_attempts: 0, qwen_partial: nil,
+        # Qwen with thinking off: an empty thought after the cue, so the model
+        # answers at once. Kept in the turn's model messages, so each tool-loop
+        # prompt starts with what the server already has cached.
+        prefill: Thinking.native(@turn_settings.thinking || Thinking::DEFAULT, @profile).prefill,
+        pending_tool_calls: false, model_name: @turn_settings.model_name, pending_input: pending_input,
+        on_stream_event: on_stream_event, cancel_controller: cancel_controller, cap: cap,
+        emit: ->(event) { emit_stream_event(on_stream_event, event) }
+      )
+    end
+
+    # One iteration. Returns :next, :answer (the turn ends), or the turn's
+    # result (it ended cancelled).
+    def iterate(turn)
+      inject_pending_input!(turn)
+      request = prepare_request(turn)
+      generation = generate(turn, request)
+      return after_cut(turn, generation) if generation.cut
+
+      turn.conversation << { role: "model", content: turn.prefill + generation.response.to_s }
+      # Profile-specific parse (incl. Qwen unterminated-block recovery); the
+      # returned fragment (non-nil only for Qwen) is fed back on the next
+      # iteration if the model opened a tool-call block it did not close.
+      calls, turn.qwen_partial = parser.parse_with_recovery(generation.response, turn.qwen_partial)
+      calls = calls.map { |call| PromptLiteralGuard.restore_call(call, profile: @profile) }
+      return after_text(turn, request, generation) if calls.empty?
+
+      dispatch_calls(turn, calls)
+    end
+
+    # The prompt for this iteration, after the context check: a rise into a
+    # bucket that asks the model for a change puts its line on the tail
+    # (the prompt cache keeps its prefix), and the prompt is formatted again
+    # with it.
+    def prepare_request(turn)
+      prompt, images = format_prompt(turn)
+      image_tokens = images.empty? ? 0 : ImagePlan.estimated_tokens(turn.conversation)
+      window = ContextWindow.resolve(client: @client, model: turn.model_name)
+      emit_context_status_event(turn.on_stream_event, turn.context, prompt, iteration_index: turn.iteration - 1,
+                                                                             window: window, image_tokens: image_tokens)
+      if (line = turn.context.take_guidance)
+        turn.conversation << line
+        prompt, images = format_prompt(turn)
+      end
+      Request.new(prompt: prompt, images: images, image_tokens: image_tokens, window: window)
+    end
+
+    def format_prompt(turn)
+      Prompt.format_with_images(turn.conversation, profile: @profile, vision: @turn_settings.vision, prefill: turn.prefill)
+    end
+
+    # One streamed request, under the generation's own controller: a
+    # plugin's stop_generation cuts it alone, and the turn goes on (a cut).
+    # Ends with its :generation_completed (and, unless cut, the
+    # after_generation hook).
+    def generate(turn, request)
+      # Each generation splits its own stream: one that ended inside a
+      # thought or a tool call doesn't leave the next one "inside" it.
+      stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
+      emit(turn, type: :generation_started, iteration: turn.iteration, context_window_tokens: request.window.tokens,
+                 context_window_source: request.window.source, profile: @profile.name, profile_source: @profile_source)
+      # This generation's own server counts (the run-long ones in the
+      # context tracker can be an earlier one's), and the thinking it
+      # streamed, for the log (a stuck thinking generation shows as
+      # thinking_chars=N content_length=…).
+      generation = Generation.new(usage: nil, served_model: nil, streamed_thinking: 0)
+      fire_hook(:before_generation, { type: :before_generation, iteration: turn.iteration }) if @hooks
+      buffer_mark = turn.buffer.length
+      generation.response = with_generation(turn.cancel_controller) do |generation_controller|
+        request_generation(
+          request.prompt,
+          generation_controller: generation_controller,
+          cancel_controller: turn.cancel_controller,
+          model_name: turn.model_name,
+          sampling: turn.empty_retry.request_sampling(@turn_settings.sampling),
+          on_chunk: ->(chunk) { stream_chunk(turn, generation, stream_splitter, chunk) },
+          on_retry: lambda { |retry_event|
+            # The retry streams from the start: its counts replace these.
+            generation.usage = nil
+            generation.streamed_thinking = 0
+            generation.finish_reason = nil
+            turn.emit.call({ type: :generation_retrying, iteration: turn.iteration }.merge(retry_event)) if turn.on_stream_event
+          },
+          images: request.images
+        )
+      rescue Client::RequestCancelled
+        raise unless cut?(generation_controller, turn.cancel_controller)
 
-      names = Tools::MemoryRead.parse_names(content)
-      refused, allowed = names.partition { |name| MutedMemories.muted?(name, muted) }
-      return read.call(content) if refused.empty?
+        generation.cut = generation_controller.detail || {}
+        nil
+      end
+      generation.cut ? cut_generation(turn, generation, buffer_mark) : completed_generation(turn, request, generation)
+      generation
+    end
+
+    def stream_chunk(turn, generation, stream_splitter, chunk)
+      generation.usage = turn.context.capture(chunk[:payload]) || generation.usage
+      # llama.cpp names the loaded model in the stream's last payload.
+      named = chunk[:payload]["model"] if chunk[:payload].is_a?(Hash)
+      generation.served_model = named if named.is_a?(String) && !named.strip.empty?
+      generation.finish_reason = chunk[:finish_reason] if chunk[:finish_reason]
+      split = stream_splitter.feed(chunk[:content])
+      turn.buffer << split[:text]
+      generation.streamed_thinking += split[:thinking].to_s.length
+      return unless turn.on_stream_event
+
+      emit(turn, type: :generation_chunk, iteration: turn.iteration, content: chunk[:content], text: split[:text],
+                 thinking: split[:thinking], payload: chunk[:payload])
+    end
+
+    # The cut stream's visible text goes with it: the buffer as it was
+    # before (the next generation gets a fresh splitter).
+    def cut_generation(turn, generation, buffer_mark)
+      turn.buffer.slice!(buffer_mark..)
+      emit(turn, type: :generation_completed, iteration: turn.iteration, content_length: 0,
+                 thinking_chars: generation.streamed_thinking, served_model: generation.served_model,
+                 requested_model: turn.model_name, finish_reason: "stopped", stopped_by: generation.cut[:by],
+                 stop_reason: generation.cut[:reason])
+    end
+
+    def completed_generation(turn, request, generation)
+      response = generation.response.to_s
+      turn.context.generation_done(generation.usage, prompt_chars: request.prompt.length, image_tokens: request.image_tokens,
+                                                     window: request.window)
+      emit(turn, type: :generation_completed, iteration: turn.iteration, content_length: response.length,
+                 thinking_chars: thinking_chars(response, generation.streamed_thinking),
+                 served_model: generation.served_model, requested_model: turn.model_name,
+                 finish_reason: generation.finish_reason)
+      dump_log("response", generation.response, iteration: turn.iteration)
+      # The after_generation hook (after the model returns, before the tool
+      # parse), with a read-only copy of the conversation as sent.
+      return unless @hooks
 
-      errors = refused.map { |name| "Error: memory '#{name}' is muted for this session" }
-      return errors.join("\n") if allowed.empty?
+      fire_hook(:after_generation, { type: :after_generation, iteration: turn.iteration, response: generation.response,
+                                     messages: AnswerDisplay.strip_all(turn.conversation).map(&:dup).freeze })
+    end
 
-      [read.call(allowed.join(",")), *errors].join(Tools::MemoryRead::SEPARATOR)
+    # A generation a plugin cut is an empty answer made early: asked again
+    # with its own nudge while the retry budget lasts (queued input goes in
+    # place of the nudge), else the turn ends as cancelled (hook), with
+    # nothing salvaged and without the spent nudge. A Stop that came right
+    # after the cut is a plain cancel. Returns :next or the turn's result.
+    def after_cut(turn, generation)
+      cut = generation.cut
+      raise Client::RequestCancelled.new(turn.cancel_controller.reason) if turn.cancel_controller.cancelled?
+
+      if turn.empty_retry.left?
+        return :next if inject_pending_input!(turn)
+
+        turn.empty_retry.nudge!(turn.conversation, TurnNote.cut_retry(cut[:by], cut[:reason]),
+                                emit: turn.emit, iteration: turn.iteration, finish_reason: "stopped",
+                                thinking_chars: generation.streamed_thinking, stopped_by: cut[:by])
+        return :next
+      end
+      turn.empty_retry.drop_nudge!(turn.conversation)
+      turn.cancel_controller.cancel!(:hook, cut)
+      emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: :hook)
+      cancelled_result(turn.conversation, tool_activity: turn.tool_activity, reason: :hook, partial_assistant_text: "")
+    end
+
+    # A generation with no tool calls: a Qwen call left open is asked to be
+    # finished; an empty answer is asked again (EmptyAnswerRetry: not when
+    # a length stop came with the context full); queued input keeps the
+    # turn going (the model answers it); else it is the answer. Returns
+    # :next or :answer.
+    def after_text(turn, request, generation)
+      turn.pending_tool_calls = false
+      if turn.qwen_partial && turn.qwen_attempts < QWEN_INCOMPLETE_TOOL_CALL_RECOVERY_LIMIT
+        turn.qwen_attempts += 1
+        turn.conversation << { role: "user", content: QWEN_INCOMPLETE_TOOL_CALL_RECOVERY_PROMPT, preserve_literals: true }
+        return :next
+      end
+
+      response = generation.response
+      answer = -> { PromptLiteralGuard.restore(strip_thought_blocks(response), profile: @profile) }
+      empty = strip_thought_blocks(response.to_s).strip.empty?
+      retry_empty = empty && turn.empty_retry.retry_empty?(iteration: turn.iteration,
+                                                           cancelled: turn.cancel_controller&.cancelled?,
+                                                           finish_reason: generation.finish_reason,
+                                                           used_tokens: generation.usage&.dig(:total_tokens),
+                                                           window_tokens: request.window.tokens)
+      # The empty generation goes (its thinking would be sent again and
+      # prime the same loop); an empty answer that will be retried is no
+      # answer site, so a plugin's steer joins the retry.
+      turn.conversation.pop if retry_empty
+      # Queued steering keeps the turn going: the model answers the
+      # injected message instead of stopping here.
+      return :next if inject_pending_input!(turn, answer: retry_empty ? nil : answer)
+
+      if retry_empty
+        turn.empty_retry.nudge!(turn.conversation, TurnNote.empty_retry,
+                                emit: turn.emit, iteration: turn.iteration, finish_reason: generation.finish_reason,
+                                thinking_chars: thinking_chars(response.to_s, generation.streamed_thinking))
+        return :next
+      end
+      # The Engine's TurnNote.empty says it all: the spent nudge goes.
+      turn.empty_retry.drop_nudge!(turn.conversation) if empty && turn.empty_retry.used?
+      :answer
+    end
+
+    # The batch runs (ToolResponse) and its results go back as one entry.
+    def dispatch_calls(turn, calls)
+      turn.qwen_attempts = 0
+      turn.qwen_partial = nil
+      runs = ToolResponse.run_batch(tool_runner, calls, iteration: turn.iteration, emit: turn.emit,
+                                                        on_stream_event: turn.on_stream_event, cap: turn.cap)
+      turn.tool_activity.concat(ToolResponse.activities(runs))
+      # One entry for the batch: the full outputs joined (ToolResponse.joined).
+      turn.conversation << ToolResponse.joined(runs)
+      turn.pending_tool_calls = true
+      :next
+    end
+
+    # The turn's result. It is exhausted only when it stopped on tool
+    # results it never answered (so exhausted? alone means resumable?);
+    # then the answer shows only its text.
+    def finish(turn)
+      exhausted = turn.pending_tool_calls && tool_response_turn?(turn.conversation.last)
+      output = strip_thought_blocks(last_model_content(turn.conversation))
+      output = parser.strip_tool_calls(output) if exhausted
+      LLM::ModelResult.new(
+        text: PromptLiteralGuard.restore(output, profile: @profile).to_s,
+        conversation: duplicate_conversation(turn.conversation),
+        exhausted: exhausted,
+        pending_tool_calls: turn.pending_tool_calls,
+        tool_activity: turn.tool_activity,
+        context_status: turn.context.display
+      )
+    end
+
+    def emit(turn, **event)
+      emit_stream_event(turn.on_stream_event, event)
+    end
+
+    # Queued input at an iteration boundary (Steer.inject!); +answer+ is a
+    # proc, built only on a merge. Returns true when anything was injected.
+    def inject_pending_input!(turn, answer: nil)
+      Steer.inject!(turn.conversation, turn.pending_input, iteration: turn.iteration, emit: turn.emit,
+                                                           cancel_controller: turn.cancel_controller, answer: answer)
     end
 
     def emit_stream_event(callback, event)
@@ -466,34 +481,6 @@ module Samagotchi
       nil
     end
 
-    # Drain the pending input queue (if any) and, when messages are waiting,
-    # append them as ONE merged user message at the conversation tail and emit
-    # :pending_input_merged. Tail-append only: head mutation would invalidate
-    # the server-side prefix KV cache. Returns true when a message was injected.
-    # A plugin's steers (Steer) follow the user's message, each its own
-    # message; after an answer the Engine's drain has already dropped them.
-    # After a cancel the input stays queued: it runs as the next turn instead
-    # of dying with this one. +answer+ (a proc, called only on a merge) is the
-    # answer the merge follows: the UIs show it, the turn summary has only the
-    # last one.
-    def inject_pending_input!(conversation, pending_input, on_stream_event, iteration, cancel_controller = nil, answer: nil)
-      return false unless pending_input
-      return false if cancel_controller&.cancelled?
-
-      merge = Steer.merge(Steer.drain(pending_input, at_answer: !answer.nil?))
-      return false if merge.empty?
-
-      answer = answer.call.to_s if answer
-      conversation.concat(merge.messages)
-      emit_stream_event(
-        on_stream_event,
-        type: :pending_input_merged,
-        iteration: iteration,
-        **merge.event_fields,
-        answer: answer.to_s.strip.empty? ? nil : answer
-      )
-      true
-    end
 
     # ── Hook dispatch helper ───────────────────────────────────────────────────
 
@@ -553,21 +540,20 @@ module Samagotchi
       generation_controller&.cancelled? && !cancel_controller.cancelled?
     end
 
-    def complete_kwargs(cancel_controller:, model_name: nil, on_chunk: nil, on_retry: nil, images: [])
+    # +sampling+: this request's (EmptyAnswerRetry#request_sampling).
+    def complete_kwargs(cancel_controller:, model_name: nil, on_chunk: nil, on_retry: nil, images: [], sampling: nil)
       kwargs = {}
       # Only a request with images names them: a text-only call is unchanged.
       kwargs[:images] = images unless images.empty?
       kwargs[:on_chunk] = on_chunk if on_chunk
-      kwargs[:on_retry] = on_retry if on_retry && client_supports_keyword?(:on_retry)
-      kwargs[:cancel_controller] = cancel_controller if cancel_controller && client_supports_keyword?(:cancel_controller)
-      kwargs[:stop] = @profile.stop_sequences if client_supports_keyword?(:stop)
+      kwargs[:on_retry] = on_retry if on_retry
+      kwargs[:cancel_controller] = cancel_controller if cancel_controller
+      kwargs[:stop] = @profile.stop_sequences
       n_predict = completion_n_predict
-      kwargs[:n_predict] = n_predict if n_predict && client_supports_keyword?(:n_predict)
+      kwargs[:n_predict] = n_predict if n_predict
       resolved_model_name = completion_model_name(model_name)
-      kwargs[:model] = resolved_model_name if resolved_model_name && client_supports_keyword?(:model)
-      sampling = @retry_generation ? EmptyAnswerRetry.sampling(@sampling) : @sampling
-      @retry_generation = false
-      kwargs[:sampling] = sampling if sampling && !sampling.empty? && client_supports_keyword?(:sampling)
+      kwargs[:model] = resolved_model_name if resolved_model_name
+      kwargs[:sampling] = sampling if sampling && !sampling.empty?
       kwargs
     end
 
@@ -580,19 +566,6 @@ module Samagotchi
       ModelProfile.required_model_name(override)
     end
 
-    def client_supports_keyword?(keyword)
-      @client_complete_keyword_support ||= {}
-      return @client_complete_keyword_support[keyword] if @client_complete_keyword_support.key?(keyword)
-
-      @client_complete_keyword_support[keyword] = begin
-        parameters = @client.method(:complete).parameters
-        parameters.any? { |kind, name| (kind == :key || kind == :keyreq) && name == keyword } ||
-          parameters.any? { |kind, _name| kind == :keyrest }
-      rescue StandardError
-        false
-      end
-    end
-
     def cancelled_result(conversation, tool_activity:, reason:, partial_assistant_text: "")
       partial = partial_assistant_text.to_s.strip
       conversation = duplicate_conversation(conversation)
@@ -603,11 +576,9 @@ module Samagotchi
       unless partial.empty?
         conversation << { role: "model", content: "#{partial}\n[interrupted]", interrupted: true }
       end
-      Result.new(
-        output: "",
+      LLM::ModelResult.new(
+        text: "",
         conversation: conversation,
-        exhausted: false,
-        pending_tool_calls: false,
         tool_activity: tool_activity,
         canceled: true,
         cancellation_reason: reason
@@ -619,7 +590,7 @@ module Samagotchi
     def dump_log(event, payload, **fields)
       return unless Log.level?(:debug)
 
-      Log.debug(:model, event, payload: payload, model: @current_model_name, **fields)
+      Log.debug(:model, event, payload: payload, model: @turn_settings.model_name, **fields)
     end
 
     # Estimate context usage for this iteration's prompt (ContextStatus#observe)
@@ -627,7 +598,7 @@ module Samagotchi
     # :context_status event. The telemetry is not for the model (it used to
     # be injected as a synthetic system message).
     def emit_context_status_event(on_stream_event, context, prompt, iteration_index:, window:, image_tokens: 0)
-      event = context.observe(prompt, iteration_index: iteration_index, window: window, image_tokens: image_tokens)
+      event = context.observe(prompt.length, iteration_index: iteration_index, window: window, image_tokens: image_tokens)
       return unless event
 
       emit_stream_event(on_stream_event, type: :context_status, iteration: iteration_index + 1, **event)
@@ -644,13 +615,6 @@ module Samagotchi
       strip_thought_blocks(text)
     end
 
-    # The status line's context value ({est_pct:, bucket:}) for +used_tokens+
-    # of +window_tokens+; nil without both, or with context.status off. The
-    # chat loop builds its value with it too.
-    def context_display(used_tokens:, window_tokens:)
-      ContextStatus.new.display_for(used_tokens: used_tokens, window_tokens: window_tokens)
-    end
-
     # Per-profile parse strategy. Rebuilt when the active profile changes
     # (the profile may be re-inferred per run when not explicitly pinned).
     # Public so other loops (and specs) can reach the active profile's parser.
@@ -696,11 +660,6 @@ module Samagotchi
       messages.map(&:dup)
     end
 
-    def drop_last_empty_retry!(conversation)
-      index = conversation.rindex { |entry| TurnNote.retry_nudge?(entry) }
-      conversation.delete_at(index) if index
-    end
-
     def last_model_content(conversation)
       message = conversation.reverse.find { |entry| entry[:role] == "model" }
       message ? message[:content].to_s : ""
@@ -760,19 +719,5 @@ module Samagotchi
         activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: @tools)
       }
     end
-
-    # ask_user_question: validate the call, then hand the payload to the
-    # Engine's question flow (question_handler, which blocks until the user
-    # answers). Without one (headless), the payload as JSON so the model sees
-    # the options and can ask in plain text.
-    def handle_ask_user_question(call)
-      payload = Samagotchi::Tools::AskUserQuestion.validate(call)
-      return payload if payload.is_a?(String)
-      return JSON.pretty_generate(payload) unless @question_handler
-
-      @question_handler.call(payload).to_s
-    rescue => e
-      "Error: ask_user_question handler failed: #{e.message}"
-    end
   end
 end