samagotchi 0.24.0 → 0.26.0

data/lib/samagotchi/engine.rb

@@ -22,6 +22,7 @@ require_relative "session_commands"
 require_relative "plugin/loader"
 require_relative "log"
 require_relative "log_subscriber"
+require_relative "thinking_tails"
 require_relative "client"
 require_relative "host_registry"
 require_relative "llm/backend"
@@ -63,6 +64,7 @@ require_relative "question_desk"
 require_relative "relay_desk"
 require_relative "guardrail_wiring"
 require_relative "plugin_tasks"
+require_relative "prompt_warmup"
 
 module Samagotchi
   # Engine owns the core agent logic: system prompt construction, tool
@@ -172,8 +174,9 @@ module Samagotchi
       @hooks = load_hooks_from_config
       load_hooks_from_bundles
       # The tools this session offers (the prompts' declarations and the
-      # kernel's dispatch): the built-ins, per Engine.
-      @tools = Tools::Builtins.registry
+      # kernel's dispatch): the built-ins, per Engine. execute.description
+      # off: execute offers no description parameter.
+      @tools = Tools::Builtins.registry(command_description: Config.get("execute.description") != false)
       if @scratch
         # A scratch session's children would outlive it, and so would a
         # note it left in a peer; its memories would too (write and edit
@@ -240,6 +243,9 @@ module Samagotchi
       # list_sessions and send_note speak for whichever session runs now.
       @kernel.peers = PeerView.new(self)
       @kernel.guardrail_gate = @guardrail_wiring.gate
+      # The turn-end warm-up; the kernel asks it for a slot pin per request.
+      @prompt_warmup = PromptWarmup.new
+      @kernel.warmup = @prompt_warmup
       # What a hook can do beyond reading its event (event[:notify],
       # event[:ask_user], event[:stop_turn]): the Engine's routes to the UIs.
       @hooks.runtime = hook_runtime
@@ -282,6 +288,10 @@ module Samagotchi
       @session_observer.subscribe(observer: @metrics)
       # And the event trail in the debug log (`turn` records).
       @session_observer.subscribe(observer: LogSubscriber.new(session_id: -> { @session&.id }))
+      # The thinking of cut and capped generations, kept in the session dir.
+      @session_observer.subscribe(observer: ThinkingTails.new(session_dir: lambda {
+        @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir)
+      }))
     end
 
     # A monotonically-increasing clock (wall clock can jump backwards; the idle
@@ -1609,6 +1619,7 @@ module Samagotchi
                                 pending_input: pending_input)
         publish_used_memories(session, on_event)
         complete_turn(turn, result)
+        warm_up_next_turn(turn, result)
         result
       rescue Interrupt
         # After the end event (in the after_turn/session_end hooks) the
@@ -1745,13 +1756,7 @@ module Samagotchi
     # 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)
-      return nil unless turn.controller.reason == :hook
-
-      detail = turn.controller.detail
-      by = detail[:by].to_s if detail.is_a?(Hash)
-      by unless by.nil? || by.empty?
-    end
+    def cancelled_by(turn) = turn.controller.stopped_by
     private :cancelled_by
 
     # The turn's settings for the kernel (LLM::TurnSettings): vision,
@@ -1769,6 +1774,50 @@ module Samagotchi
     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_writer :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?
+
+      target = @host_registry.resolve(@effective_model_name)
+      client = target.client
+      return unless warmup_target?(target, 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(target) })
+      prompt, images = @kernel.warmup_prompt(messages)
+      return unless prompt
+
+      @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
+                           slot: @kernel.last_slot, images: images)
+    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 non-llama.cpp transport.
+    def warmup_target?(target, client)
+      return false if target.entry.chat? || target.entry.remote?
+      return false unless client.respond_to?(:warm_up) && client.respond_to?(:transport) && client.transport.native?
+
+      PromptWarmup.enabled?
+    end
+    private :warmup_target?
+
     # The messages the turn sends: the history under the system head, due
     # reminders, the prompt. turn.messages is set first and grown in place,
     # so a Ctrl-C or a failure meanwhile keeps what is there.
@@ -2039,12 +2088,23 @@ module Samagotchi
       nil
     end
 
+    # Whether this generation's thinking lane said anything: nil while it
+    # streamed none, false while only whitespace (Gemma 4's empty thought
+    # with thinking off), true once a real thought came.
+    def note_generation_thought(thinking)
+      return if thinking.empty?
+
+      @generation_thought ||= thinking.match?(/\S/)
+    end
+
     # Thinking off, and the model thought anyway: logged each time, said
-    # once per session and host.
+    # once per session and host. A thinking lane of whitespace alone is no
+    # thought.
     def check_thinking_honoured(event)
       level, target = @turn_thinking
       chars = event[:thinking_chars].to_i
       return unless level == :off && chars.positive? && target
+      return if @generation_thought == false
 
       Log.warn(:model, "thinking_not_honoured", level: level, host: target.entry.name, model: target.bare_model, chars: chars)
       thinking_notice_once(:not_honoured, target, :warn,
@@ -2184,7 +2244,7 @@ module Samagotchi
       return @native_backend unless target.entry.chat?
 
       @chat_backend_mutex.synchronize do
-        @chat_backend ||= LLM::ChatLoop.new(kernel: @kernel)
+        @chat_backend ||= LLM::ChatLoop.new(kernel: @kernel, stable_length: ->(text) { @prompt_builder.stable_length(text) })
         @chat_backend.adapter = @host_registry.adapter_for(target.entry)
         @chat_backend.session_id = session&.id
         @chat_backend
@@ -2406,6 +2466,7 @@ module Samagotchi
         case event[:type]
         when :generation_started
           @generation_phase.started!
+          @generation_thought = nil
           watch&.started(event[:iteration])
         when :generation_chunk
           # A chunk without the lanes (no loop of ours sends one) counts as text.
@@ -2413,6 +2474,7 @@ module Samagotchi
           progress = { thinking: event[:thinking].to_s, text: text.to_s }
           @generation_phase.chunk!(**progress, tool_call: event[:tool_call])
           recheck_waiting_steer unless progress[:thinking].empty?
+          note_generation_thought(progress[:thinking])
         when :generation_retrying then @generation_phase.retrying!
         when :generation_completed, :generation_cancelled then @generation_phase.finished!
         end

data/lib/samagotchi/guardrails/shell_lex.rb

@@ -33,6 +33,15 @@ module Samagotchi
         Lexer.new(text).tokens
       end
 
+      # lex's tokens, each with the range of +text+ it was read from
+      # appended ([:word, "x", specials, 0...1] / [:op, "&&", 2...4]), for a
+      # display that slices the original text. A heredoc body's range is
+      # the body and its terminator line. lex itself is unchanged by this.
+      def self.lex_with_spans(text)
+        lexer = Lexer.new(text)
+        lexer.tokens.zip(lexer.spans).map { |token, span| [*token, span] }
+      end
+
       # The token stream split at operators into word lists; ( and ) become
       # :open / :close markers.
       def self.simple_commands(tokens)
@@ -57,18 +66,34 @@ module Samagotchi
           @s = text
           @i = 0
           @tokens = []
+          @spans = []
+          @start = 0
           @word = +""
           @specials = +""
           @in_word = false
           @heredocs = []
+          @heredoc_spans = []
+          @unterminated = false
         end
 
         def tokens
           step while @i < @s.size
           flush
+          @unterminated = true unless @heredocs.empty?
           @tokens
         end
 
+        # Each token's range in the text, in step with #tokens (after it).
+        attr_reader :spans
+
+        # The heredocs read ({tag:, span:}, the body and its terminator
+        # line), after #tokens.
+        attr_reader :heredoc_spans
+
+        # Whether a quote, $(…), backtick or heredoc was left open (after
+        # #tokens): the lexer's best effort, not the shell's reading.
+        def unterminated? = @unterminated
+
         private
 
         def step
@@ -87,6 +112,7 @@ module Samagotchi
         end
 
         def add(text, advance)
+          @start = @i unless @in_word
           @word << text
           @in_word = true
           @i += advance
@@ -99,7 +125,10 @@ module Samagotchi
         end
 
         def flush
-          @tokens << [:word, @word.dup, @specials.dup] if @in_word
+          if @in_word
+            @tokens << [:word, @word.dup, @specials.dup]
+            @spans << (@start...[@i, @s.size].min)
+          end
           @word.clear
           @specials.clear
           @in_word = false
@@ -107,11 +136,14 @@ module Samagotchi
         end
 
         def single_quote
-          close = @s.index("'", @i + 1) || @s.size
+          close = @s.index("'", @i + 1)
+          @unterminated ||= close.nil?
+          close ||= @s.size
           add(@s[(@i + 1)...close].to_s, close + 1 - @i)
         end
 
         def double_quote
+          @start = @i unless @in_word
           @i += 1
           @in_word = true
           while @i < @s.size && @s[@i] != '"'
@@ -126,11 +158,14 @@ module Samagotchi
               @i += 1
             end
           end
+          @unterminated = true if @i >= @s.size
           @i += 1
         end
 
         def backtick
-          close = @s.index("`", @i + 1) || @s.size
+          close = @s.index("`", @i + 1)
+          @unterminated ||= close.nil?
+          close ||= @s.size
           add(SUBST, close + 1 - @i)
         end
 
@@ -143,6 +178,7 @@ module Samagotchi
             j += 1
             break if depth.zero? || j >= @s.size
           end
+          @unterminated = true unless depth.zero?
           add(SUBST, j - @i)
         end
 
@@ -170,6 +206,7 @@ module Samagotchi
           else
             flush
             @tokens << [:op, op]
+            @spans << (@i...(@i + op.size))
             @i += op.size
             bodies if op == "\n" && !@heredocs.empty?
           end
@@ -223,16 +260,23 @@ module Samagotchi
           heredocs = @heredocs
           @heredocs = []
           pos = @i
+          start = pos
           read = []
           heredocs.each do |doc|
             body, pos = body(doc, pos)
             break unless body
 
-            read << [doc, body]
+            read << [doc, body, start...(@s[pos - 1] == "\n" ? pos - 1 : pos)]
+            start = pos
           end
+          @unterminated ||= read.size < heredocs.size
           return if read.size < heredocs.size
 
-          read.reverse_each { |doc, body| @tokens.insert(doc[:at], [:word, body_word(doc, body), ""]) }
+          read.reverse_each do |doc, body, span|
+            @tokens.insert(doc[:at], [:word, body_word(doc, body), ""])
+            @spans.insert(doc[:at], span)
+          end
+          read.each { |doc, _body, span| @heredoc_spans << { tag: doc[:tag], span: span } }
           @i = pos
         end
 

data/lib/samagotchi/idle_client.rb

@@ -93,7 +93,8 @@ module Samagotchi
     # @raise [SummarizeError] any failure but a cancel
     # @raise [LLM::RequestCancelled] +cancel_controller+ was cancelled
     def ask(messages, max_tokens: MAX_TOKENS, cancel_controller: nil)
-      content, served = generate(messages, max_tokens: max_tokens, cancel_controller: cancel_controller, whole_sentences: false)
+      content, served = generate(messages, max_tokens: max_tokens, cancel_controller: cancel_controller, whole_sentences: false,
+                                           kind: "ask")
       Summary.new(text: content.to_s.strip, model: served)
     rescue SummarizeError, LLM::RequestCancelled
       raise
@@ -109,7 +110,7 @@ module Samagotchi
     # the reply has neither content nor reasoning_content. Cut off by
     # +max_tokens+, the text keeps its finished sentences (+whole_sentences+)
     # or all of it, with "…".
-    def generate(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, whole_sentences: true)
+    def generate(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, whole_sentences: true, kind: "recap")
       response = begin
         request(messages, max_tokens, cancel_controller)
       rescue LLM::BadRequest => e
@@ -121,6 +122,7 @@ module Samagotchi
         Log.info(:recap, "thinking_refused", model: @model, detail: e.detail)
         request(messages, max_tokens, cancel_controller)
       end
+      log_usage(response, kind)
       content = response.text
       reasoning = response.reasoning
       raise SummarizeError, "server returned no parseable assistant content" if content.empty? && reasoning.empty?
@@ -141,6 +143,16 @@ module Samagotchi
       raise SummarizeError, "server returned no parseable assistant content (#{e.message})"
     end
 
+    # The request's prompt-cache counts (a side request on the session's
+    # host can evict the session's cached prompt there).
+    def log_usage(response, kind)
+      fields = response.usage&.cache_fields || {}
+      return if fields.empty?
+
+      Log.info(:recap, "request_usage", kind: kind, model: @model, prompt: fields[:prompt_tokens],
+                                        cached: fields[:cached_tokens], cache_write: fields[:cache_write_tokens])
+    end
+
     def request(messages, max_tokens, cancel_controller)
       @chat.chat(messages: messages, model: @model, tools: [], cancel_controller: cancel_controller,
                  options: { max_tokens: max_tokens, **thinking_fields })

data/lib/samagotchi/kernel_loop.rb

@@ -8,6 +8,7 @@ require_relative "context_status"
 require_relative "context_window"
 require_relative "prompt"
 require_relative "prompt_literal_guard"
+require_relative "token_usage"
 require_relative "client"
 require_relative "llm/errors"
 require_relative "log"
@@ -155,6 +156,13 @@ module Samagotchi
     # 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
+    # The Engine's PromptWarmup: a request asks it for a slot pin
+    # (#take_pin) while the turn-end warm-up still runs; nil: never pinned.
+    attr_accessor :warmup
+    # @return [Integer, nil] the llama.cpp slot (`id_slot`) the last
+    #   request of the last run streamed from; nil when the server named
+    #   none (other transports) or no request was made
+    attr_reader :last_slot
 
     # Run the conversation loop and return the final model response plus
     # resumable conversation state when execution stops at max_iterations.
@@ -176,6 +184,7 @@ module Samagotchi
     # @return [LLM::ModelResult] final visible response with continuation metadata
     def run(messages, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil, model_name: nil, max_tool_output_chars: nil, pending_input: nil)
       @turn_settings = @turn_settings.with(model_name: completion_model_name(model_name))
+      @last_slot = nil
       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))
 
@@ -185,7 +194,8 @@ module Samagotchi
         return outcome if outcome.is_a?(LLM::ModelResult)
         break if outcome == :answer
       rescue Client::RequestCancelled => e
-        emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: e.reason)
+        emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: e.reason,
+                   stopped_by: turn.cancel_controller&.stopped_by)
         return cancelled_result(turn.conversation, tool_activity: turn.tool_activity, reason: e.reason,
                                                    partial_assistant_text: turn.buffer)
       end
@@ -238,8 +248,10 @@ module Samagotchi
     # 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)
+    # reason, Client::Transport#finish_reason_from; nil when not named),
+    # and its prompt-cache counts (the largest seen: they come cumulative).
+    Generation = Struct.new(:response, :cut, :usage, :served_model, :streamed_thinking, :finish_reason, :cache,
+                            keyword_init: true)
     private_constant :Turn, :Request, :Generation
 
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:)
@@ -328,6 +340,7 @@ module Samagotchi
           on_retry: lambda { |retry_event|
             # The retry streams from the start: its counts replace these.
             generation.usage = nil
+            generation.cache = 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
@@ -346,9 +359,12 @@ module Samagotchi
 
     def stream_chunk(turn, generation, stream_splitter, chunk)
       generation.usage = turn.context.capture(chunk[:payload]) || generation.usage
+      note_cache_counts(generation, chunk[:payload])
       # 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?
+      slot = chunk[:payload]["id_slot"] if chunk[:payload].is_a?(Hash)
+      @last_slot = slot if slot.is_a?(Integer)
       generation.finish_reason = chunk[:finish_reason] if chunk[:finish_reason]
       split = stream_splitter.feed(chunk[:content])
       turn.buffer << split[:text]
@@ -363,6 +379,19 @@ module Samagotchi
       emit(turn, **event)
     end
 
+    # The payload's prompt-cache counts, kept as the largest seen.
+    def note_cache_counts(generation, payload)
+      counts = TokenUsage.from_payload(payload)
+      return unless counts
+
+      cache = generation.cache ||= { prompt: 0, cached: 0, cache_write: 0 }
+      cache[:prompt] = [cache[:prompt], counts.prompt_tokens.to_i].max
+      cache[:cached] = [cache[:cached], counts.cached_tokens.to_i].max
+      cache[:cache_write] = [cache[:cache_write], counts.cache_write_tokens.to_i].max
+    end
+
+    def cache_fields(cache) = cache ? TokenUsage.cache_fields(**cache) : {}
+
     # 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)
@@ -380,7 +409,7 @@ module Samagotchi
       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)
+                 finish_reason: generation.finish_reason, **cache_fields(generation.cache))
       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.
@@ -415,7 +444,7 @@ module Samagotchi
       end
       turn.empty_retry.drop_nudge!(turn.conversation)
       turn.cancel_controller.cancel!(:hook, cut)
-      emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: :hook)
+      emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: :hook, stopped_by: cut[:by])
       cancelled_result(turn.conversation, tool_activity: turn.tool_activity, reason: :hook, partial_assistant_text: "")
     end
 
@@ -548,7 +577,11 @@ module Samagotchi
     # One request, cancelled by +generation_controller+ (the turn's child)
     # when there is one.
     def request_generation(prompt, generation_controller:, cancel_controller:, **)
-      @client.complete(prompt, **complete_kwargs(cancel_controller: generation_controller || cancel_controller, **))
+      kwargs = complete_kwargs(cancel_controller: generation_controller || cancel_controller, **)
+      # Behind a turn-end warm-up still running on its slot (PromptWarmup).
+      slot = @warmup&.take_pin(@client)
+      kwargs[:slot] = slot if slot
+      @client.complete(prompt, **kwargs)
     end
 
     # Yields the turn controller's child for one generation (nil without a
@@ -626,6 +659,22 @@ module Samagotchi
 
     public
 
+    # The next turn's prompt up to where its user message starts, for the
+    # turn-end warm-up (PromptWarmup): +messages+ as the next turn sends
+    # them before its prompt (the history under the system head), formatted
+    # as #run formats them, with a stand-in user message cut off at its
+    # opener. Returns [prompt, images], or nil when the cut isn't found.
+    def warmup_prompt(messages)
+      conversation = prepare_conversation(messages) << { role: "user", content: WARMUP_CUT }
+      prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @turn_settings.vision)
+      head = prompt[0, prompt.index(WARMUP_CUT) || 0]
+      cut = head.rindex(user_opener)
+      cut&.positive? ? [head[0, cut], images] : nil
+    end
+
+    WARMUP_CUT = "chi-warmup-cut"
+    private_constant :WARMUP_CUT
+
     # Public wrapper so other loops (e.g. the chat loop) can strip
     # per-profile thought blocks from finished model text without duplicating the
     # Gemma 4 / Qwen 3.6 logic. Mirrors the native loop's "strip before deciding
@@ -661,6 +710,11 @@ module Samagotchi
       parser.strip_thought(text)
     end
 
+    # What opens a user turn in the profile's format.
+    def user_opener
+      @profile.uses_role_prefixes? ? @profile.user_prefix : "#{@profile.turn_start}user\n"
+    end
+
     def sanitize_history(messages)
       messages.map do |m|
         if m[:role] == "model"

data/lib/samagotchi/llm/chat_loop.rb

@@ -50,9 +50,12 @@ module Samagotchi
       # @param kernel [KernelLoop] tool dispatch, thought stripping, hooks
       # @param adapter [OpenAIChat, nil] the host to talk to; Engine sets it
       #   per turn for the effective model's host
-      def initialize(kernel:, adapter: nil)
+      # @param stable_length [#call, nil] text → the length of the system
+      #   prompt's part every session shares (SystemPrompt#stable_length), or nil
+      def initialize(kernel:, adapter: nil, stable_length: nil)
         @kernel = kernel
         @adapter = adapter
+        @stable_length = stable_length
       end
 
       def provider = :chat
@@ -105,7 +108,7 @@ module Samagotchi
           items = plan.items(entry, index)
           case entry[:role].to_s
           when "system"
-            wire << { role: "system", content: entry[:content].to_s }
+            wire << system_message(entry, index)
           when "user"
             # A steer or merged input (always a String) goes with its header.
             content = Steer.header(entry) ? Steer.wire_text(entry, entry[:content].to_s) : entry[:content]
@@ -132,6 +135,16 @@ module Samagotchi
         wire
       end
 
+      # The head system prompt says where its stable part ends
+      # (`cache_split:`, a character offset): the adapter puts a remote
+      # Claude model's cache breakpoint there (PromptCache) and drops it
+      # for every other request.
+      def system_message(entry, index)
+        text = entry[:content].to_s
+        split = index.zero? && @stable_length&.call(text)
+        split ? { role: "system", content: text, cache_split: split } : { role: "system", content: text }
+      end
+
       TOOL_IMAGES_TEXT = "[images from tool results]"
 
       # The turn's VisionContext (the Engine sets the kernel's
@@ -448,7 +461,8 @@ module Samagotchi
           record_context_status(response.usage, window)
           emit(type: :generation_completed, iteration: iteration, content_length: response.text.length,
                thinking_chars: response.reasoning.to_s.length, served_model: response.model,
-               served_provider: response.provider, requested_model: @model_name, finish_reason: response.finish_reason)
+               served_provider: response.provider, requested_model: @model_name, finish_reason: response.finish_reason,
+               **(response.usage&.cache_fields || {}))
           dump_response(response, iteration)
           @loop.fire_hook(:after_generation, { type: :after_generation, iteration: iteration, response: response.text,
                                                messages: AnswerDisplay.strip_all(@conversation).map(&:dup).freeze })
@@ -581,7 +595,7 @@ module Samagotchi
         # The text streamed before the cancel stays, marked [interrupted],
         # as the native loop's salvage does.
         def canceled(iteration, reason, partial = "")
-          emit(type: :generation_cancelled, iteration: iteration, reason: reason)
+          emit(type: :generation_cancelled, iteration: iteration, reason: reason, stopped_by: @cancel_controller&.stopped_by)
           visible = @loop.strip_model_thought(partial.to_s).strip
           @conversation << { role: "model", content: "#{visible}\n[interrupted]", interrupted: true } unless visible.empty?
           conversation = @loop.plain(@conversation)

data/lib/samagotchi/llm/errors.rb

@@ -25,6 +25,9 @@ module Samagotchi
     #   CreditsHeld      402 "… in-flight requests": credit reserved by other
     #                    requests; a RateLimited, retried after 20 s
     #   OutOfCredits     any other 402; never retried
+    #   OverBudget       402 metadata.reason weight_exceeds_budget: the
+    #                    request alone exceeds the key's budget; an
+    #                    OutOfCredits, never retried
     #   ServerError      5xx or a server's error event mid-stream
     #   AuthError        401/403, or an API key variable that is not set
     #   BadRequest       other 4xx (a context overflow is one, whatever status;
@@ -105,6 +108,15 @@ module Samagotchi
       def summary = "out of credits on host #{host}: #{detail}; add credits, then send again"
     end
 
+    # A 402 whose error.metadata.reason is weight_exceeds_budget (OpenRouter):
+    # this one request's credit reservation is larger than the key's whole
+    # budget, so no amount of waiting lets it through. Never retried, even
+    # when the message reads like the in-flight one.
+    class OverBudget < OutOfCredits
+      def summary = "request too large for the credit budget on host #{host}: #{detail}; " \
+                    "lower max_tokens (default.max_tokens) or raise the key's credit limit"
+    end
+
     class ServerError < ProviderError
       def kind = :server
 
@@ -261,6 +273,9 @@ module Samagotchi
       REASONING_REFUSED_RE = /reasoning|thinking/i
       # A 402 about credit held by in-flight requests (see CreditsHeld).
       CREDITS_HELD_RE = /in-flight requests/i
+      # A 402's error.metadata.reason when the request can never fit the
+      # key's budget (see OverBudget).
+      OVER_BUDGET_REASON = "weight_exceeds_budget"
       # Seconds to wait before retrying a CreditsHeld without a Retry-After.
       CREDITS_SETTLE_DELAY = 20.0
       RETRYABLE_SERVER_STATUSES = [500, 502, 503, 504, 529].freeze
@@ -285,7 +300,9 @@ module Samagotchi
         when 429 then RateLimited.new(text, retry_after: parse_retry_after(retry_after), **options)
         when 408 then ServerError.new(text, retryable: true, **options)
         when 402
-          if CREDITS_HELD_RE.match?(message) || CREDITS_HELD_RE.match?(body.to_s)
+          if error_reason(body) == OVER_BUDGET_REASON
+            OverBudget.new(text, **options)
+          elsif CREDITS_HELD_RE.match?(message) || CREDITS_HELD_RE.match?(body.to_s)
             CreditsHeld.new(text, retry_after: parse_retry_after(retry_after) || CREDITS_SETTLE_DELAY, **options)
           else
             OutOfCredits.new(text, **options)
@@ -356,6 +373,14 @@ module Samagotchi
         message.empty? ? "(empty body)" : message[0, 500]
       end
 
+      # error.metadata.reason of a JSON error body (OpenRouter), or nil.
+      def error_reason(body)
+        parsed = parse_json(body.to_s)
+        error = parsed["error"] if parsed.is_a?(Hash)
+        metadata = error["metadata"] if error.is_a?(Hash)
+        metadata["reason"] if metadata.is_a?(Hash)
+      end
+
       # +message+ followed by the upstream provider's name and words from
       # +metadata+ (raw may be text or a JSON error body of its own).
       def with_upstream(message, metadata)

data/lib/samagotchi/llm/http.rb

@@ -36,9 +36,10 @@ module Samagotchi
         Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ETIMEDOUT
       ].freeze
 
-      # Requests of these purposes are the ones a turn waits on: INFO lines
-      # (and ERROR when they fail). Probes and model lists are DEBUG.
-      LOGGED_PURPOSES = %w[chat recap].freeze
+      # Requests of these purposes are the ones a turn waits on (or, for the
+      # turn-end warm-up, prepares the next one): INFO lines (and ERROR when
+      # they fail). Probes and model lists are DEBUG.
+      LOGGED_PURPOSES = %w[chat recap warmup].freeze
 
       # Exponential backoff: base_delay * 2^(attempt-1), capped at max_delay,
       # for up to +max+ retries (max + 1 attempts).
@@ -127,7 +128,7 @@ module Samagotchi
       # @raise [ProviderError] for an error status
       # @raise [FirstTokenTimeout] when nothing was shown in time
       # @param log_fields [Hash] what the log line says about the request
-      #   (model:, purpose: chat/recap/probe/models); never its body
+      #   (model:, purpose: chat/recap/warmup/probe/models); never its body
       def stream_lines(uri, request, cancel_controller: nil, on_retry: nil, on_network_error: nil, log_fields: {}, &on_line)
         identify(request)
         current = new_attempt_state(uri, request, log_fields, stream: true)