samagotchi 0.23.0 → 0.25.0

data/lib/samagotchi/generation_phase.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # What the running generation is doing, as the Engine's stream handler
+  # sees it: whether a steer may cut it (Engine#cut_for_steer). A
+  # generation is cuttable while it has only been thinking: it streamed
+  # thinking, still streams it (a thinking delta in the last FRESH_SECONDS),
+  # and has streamed no visible text and no tool call. Its age counts from
+  # its first thinking delta, so the wait for a first token (a busy or
+  # remote server) never counts as thinking. Fed from the stream
+  # thread, read from a steer's thread: its own Mutex, never held while
+  # calling out.
+  class GenerationPhase
+    # A thinking delta this recent means the model is still thinking.
+    FRESH_SECONDS = 2.0
+
+    # @param clock [#call] monotonic seconds
+    def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @clock = clock
+      @mutex = Mutex.new
+      @running = false
+      clear_seen
+    end
+
+    # A generation began.
+    def started!
+      @mutex.synchronize do
+        @running = true
+        clear_seen
+      end
+    end
+
+    # One streamed chunk's lanes. Blank text (a stray newline before Gemma's
+    # thought channel) is no text.
+    def chunk!(thinking:, text:, tool_call: false)
+      @mutex.synchronize do
+        unless thinking.to_s.empty?
+          @thinking_at = @clock.call
+          @thinking_since ||= @thinking_at
+        end
+        @text = true unless text.to_s.strip.empty?
+        @tool_call = true if tool_call
+      end
+    end
+
+    # The request is sent again (a network retry): it streams from the
+    # start, so what it had seen (its thinking clock too) is forgotten.
+    def retrying!
+      @mutex.synchronize { clear_seen }
+    end
+
+    # The generation ended (completed, cut, cancelled, or the turn ended).
+    def finished!
+      @mutex.synchronize { @running = false }
+    end
+
+    # Whether a steer may cut the running generation: thinking only, still
+    # thinking, and thinking for at least +min_age+ seconds.
+    def cuttable?(min_age)
+      @mutex.synchronize do
+        next false unless @running && @thinking_since && !@text && !@tool_call
+
+        now = @clock.call
+        now - @thinking_at <= FRESH_SECONDS && now - @thinking_since >= min_age
+      end
+    end
+
+    # Seconds since the running generation's first thinking delta; nil
+    # with none.
+    def age
+      @mutex.synchronize { @running && @thinking_since ? @clock.call - @thinking_since : nil }
+    end
+
+    private
+
+    def clear_seen
+      @thinking_since = nil
+      @thinking_at = nil
+      @text = false
+      @tool_call = false
+    end
+  end
+end

data/lib/samagotchi/guardrails/shell_lex.rb

@@ -5,13 +5,23 @@ module Samagotchi
     # A small shell lexer for the guardrails' text checks (ShellGitDirs
     # and the rules' shell matchers): words with quotes and
     # backslashes undone, operators apart, comments dropped, and $(…) or
-    # backticks (quoted or not) as one opaque SUBST marker inside a word. It never runs
-    # anything, and it does its best on odd input (an unbalanced quote).
+    # backticks (quoted or not) as one opaque SUBST marker inside a word. A
+    # heredoc's body (<<EOF, <<'EOF', <<-EOF) is one word after its <<TAG
+    # word and lexing goes on after the terminator line: HEREDOC when cat or
+    # tee read it as data, SUBST when an unquoted tag's body holds $(…) or
+    # backticks, else the body text itself (a script, as sh -c '…' gives).
+    # An unterminated heredoc is no heredoc: the rest is lexed as commands.
+    # It never runs anything, and it does its best on odd input (an
+    # unbalanced quote).
     module ShellLex
       # Longest first: "&&" before "&", ";;" before ";".
       OPERATORS = ["&&", "||", ";;", "|&", ";", "|", "&", "\n", "(", ")"].freeze
       # What a $(…) or `…` becomes inside a word.
       SUBST = "\0SUBST"
+      # What a heredoc body that cat or tee read as data becomes.
+      HEREDOC = "\0HEREDOC"
+      # Commands that read a heredoc as data (when not piped on).
+      DATA_SINKS = %w[cat tee].freeze
       # A word that is a redirection (>, >>, 2>&1, <).
       REDIRECT = /\A\d*[<>]/
 
@@ -23,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)
@@ -47,17 +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
@@ -76,6 +112,7 @@ module Samagotchi
         end
 
         def add(text, advance)
+          @start = @i unless @in_word
           @word << text
           @in_word = true
           @i += advance
@@ -88,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
@@ -96,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] != '"'
@@ -115,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
 
@@ -132,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
 
@@ -139,8 +186,12 @@ module Samagotchi
           @i = @s.index("\n", @i) || @s.size
         end
 
-        # >, >>, 2>&1, &>, <, <<: kept in the word (the walk drops them).
+        # >, >>, 2>&1, &>, <, <<<: kept in the word (the walk drops them).
+        # << starts a heredoc.
         def redirection
+          return add("<<<", 3) if @s[@i, 3] == "<<<"
+          return if @s[@i, 2] == "<<" && heredoc
+
           special(@s[@i])
           add(@s[@i], 1) while @i < @s.size && @s[@i].match?(/[&\d>-]/) && @word.end_with?(">")
         end
@@ -155,8 +206,109 @@ module Samagotchi
           else
             flush
             @tokens << [:op, op]
+            @spans << (@i...(@i + op.size))
             @i += op.size
+            bodies if op == "\n" && !@heredocs.empty?
+          end
+        end
+
+        # <<TAG, <<-TAG, <<'TAG', << "TAG": its own word, the body noted to
+        # be read after the line ends. False (nothing read) without a tag.
+        def heredoc
+          dash = @s[@i + 2] == "-"
+          j = @i + (dash ? 3 : 2)
+          j += 1 while [" ", "\t"].include?(@s[j])
+          tag, quoted, stop = heredoc_tag(j)
+          return false if tag.empty?
+
+          flush unless @word.match?(/\A\d*\z/)
+          special("<")
+          @word << "<" << (dash ? "-" : "") << tag
+          @i = stop
+          flush
+          @heredocs << { tag: tag, dash: dash, quoted: quoted, at: @tokens.size }
+          true
+        end
+
+        # The tag starting at +j+ with quotes and backslashes undone, whether
+        # any were there, and where it ends.
+        def heredoc_tag(j)
+          tag = +""
+          quoted = false
+          while j < @s.size && !@s[j].match?(/[\s;&|<>()]/)
+            if ["'", '"'].include?(@s[j])
+              close = @s.index(@s[j], j + 1) or return ["", false, j]
+              tag << @s[(j + 1)...close]
+              j = close + 1
+              quoted = true
+            elsif @s[j] == "\\"
+              tag << @s[j + 1].to_s
+              j += 2
+              quoted = true
+            else
+              tag << @s[j]
+              j += 1
+            end
+          end
+          [tag, quoted, j]
+        end
+
+        # After a line with heredocs: each body in order, up to its
+        # terminator line, as one word in its command. Unterminated: none
+        # are, and the rest is lexed as commands.
+        def bodies
+          heredocs = @heredocs
+          @heredocs = []
+          pos = @i
+          start = pos
+          read = []
+          heredocs.each do |doc|
+            body, pos = body(doc, pos)
+            break unless 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 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
+
+        # The body from +pos+ and where lexing goes on, or nil.
+        def body(doc, pos)
+          start = pos
+          while pos < @s.size
+            eol = @s.index("\n", pos) || @s.size
+            line = @s[pos...eol]
+            line = line.sub(/\A\t+/, "") if doc[:dash]
+            return [@s[start...pos], [eol + 1, @s.size].min] if line == doc[:tag]
+
+            pos = eol + 1
           end
+          nil
+        end
+
+        def body_word(doc, body)
+          return SUBST if !doc[:quoted] && body.match?(/\$\(|`/)
+          return HEREDOC if data_sink?(doc[:at])
+
+          body
+        end
+
+        # Whether the command the heredoc at token +at+ is in is cat or tee
+        # and not piped into another command.
+        def data_sink?(at)
+          start = at
+          start -= 1 while start.positive? && @tokens[start - 1][0] == :word
+          verb = @tokens[start...at].map { |t| t[1] }.find { |w| !w.match?(/\A[A-Za-z_]\w*=/) && !w.match?(REDIRECT) }
+          next_op = @tokens[at..].find { |t| t[0] == :op }
+          DATA_SINKS.include?(File.basename(verb.to_s)) && !["|", "|&"].include?(next_op&.dig(1))
         end
       end
     end

data/lib/samagotchi/guardrails/shell_paths.rb

@@ -114,7 +114,7 @@ module Samagotchi
 
         # An absolute path for +word+ against +dir+, or nil.
         def resolve(word, dir)
-          return nil if word.include?(ShellLex::SUBST) || word.match?(SCRIPT)
+          return nil if word.include?(ShellLex::SUBST) || word == ShellLex::HEREDOC || word.match?(SCRIPT)
 
           word = expand(word) or return nil
           return nil if word.match?(GLOB)

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/idle_recap.rb

@@ -63,8 +63,10 @@ module Samagotchi
 
           case message["role"]
           when "user"
-            # A plugin's steer is a prod to the model, not what the user said.
-            next nil if Steer.steer?(message)
+            # A plugin's steer is a prod to the model, not what the user said;
+            # a continue steer from the user or the parent agent is an
+            # instruction, kept.
+            next nil if Steer.steer?(message) && !Steer.person?(message)
 
             # An image is a line naming it (refs only, never its bytes), unless
             # the text is only the web's placeholder naming it already.

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"
@@ -238,8 +239,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 +331,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,6 +350,7 @@ 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?
@@ -355,10 +360,27 @@ module Samagotchi
       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])
+      event = { type: :generation_chunk, iteration: turn.iteration, content: chunk[:content], text: split[:text],
+                thinking: split[:thinking], payload: chunk[:payload] }
+      # A chunk of a tool call (its bytes are dropped from both lanes): a
+      # steer doesn't cut this generation (Engine#cut_for_steer).
+      event[:tool_call] = true if split[:tool]
+      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)
@@ -376,7 +398,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.
@@ -386,18 +408,24 @@ module Samagotchi
                                      messages: AnswerDisplay.strip_all(turn.conversation).map(&:dup).freeze })
     end
 
-    # 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.
+    # A generation a plugin cut is an empty answer made early. Queued input
+    # (a user's line, a plugin's steer) goes in first, with or without a
+    # retry left, and spends no attempt: the model answers it. A steer's cut
+    # (Engine#cut_for_steer) with nothing queued (its message was taken at
+    # a boundary already) is asked again as is. Else it is asked again with
+    # its own nudge while the retry budget lasts, 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, turn.cancel_controller.reason if turn.cancel_controller.cancelled?
 
-      if turn.empty_retry.left?
-        return :next if inject_pending_input!(turn)
+      # The row under the cut step, above the message it was cut for.
+      emit(turn, type: :steer_cut, iteration: turn.iteration, source: cut[:source].to_s) if cut[:steer]
+      return :next if inject_pending_input!(turn) || cut[:steer]
 
+      if turn.empty_retry.left?
         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])

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,9 +108,11 @@ 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"
-            wire << { role: "user", content: parts(entry[:content], items) }
+            # 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]
+            wire << { role: "user", content: parts(content, items) }
           when "model"
             wire << assistant_message(entry, paired)
           when "tool_response"
@@ -130,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
@@ -381,17 +396,22 @@ module Samagotchi
         end
 
         # A generation a plugin cut (stop_generation) 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 a spent nudge.
-        # A Stop that came right after the cut is a plain cancel. Returns
-        # :retry, or the turn's result.
+        # early. Queued input (a user's line, a plugin's steer) goes in
+        # first, with or without a retry left, and spends no attempt. A
+        # steer's cut (Engine#cut_for_steer) with nothing queued is asked
+        # again as is. Else it is asked again with its own nudge while the
+        # retry budget lasts, else the turn ends as cancelled (hook), with
+        # nothing salvaged and without a spent nudge. A Stop that came right
+        # after the cut is a plain cancel. Returns :retry, or the turn's
+        # result.
         def after_cut(iteration, response)
           return canceled(iteration, @cancel_controller.reason) if @cancel_controller.cancelled?
 
-          if @empty_retry.left?
-            return :retry if inject_pending_input(iteration)
+          # The row under the cut step, above the message it was cut for.
+          emit(type: :steer_cut, iteration: iteration, source: response.cut[:source].to_s) if response.cut[:steer]
+          return :retry if inject_pending_input(iteration) || response.cut[:steer]
 
+          if @empty_retry.left?
             @empty_retry.nudge!(@conversation, TurnNote.cut_retry(response.cut[:by], response.cut[:reason]),
                                 emit: method(:emit), iteration: iteration, finish_reason: response.finish_reason,
                                 thinking_chars: response.reasoning.to_s.length, stopped_by: response.cut[:by])
@@ -441,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 })
@@ -478,8 +499,11 @@ module Samagotchi
             on_delta: lambda { |content:, reasoning:, payload:|
               streamed << content
               thought << reasoning
-              emit(type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
-                   thinking: reasoning, payload: payload)
+              event = { type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
+                        thinking: reasoning, payload: payload }
+              # A tool call streaming: a steer doesn't cut it (Engine#cut_for_steer).
+              event[:tool_call] = true if OpenAIChat.tool_call_delta?(payload)
+              emit(event)
             },
             on_retry: ->(**retry_event) { emit({ type: :generation_retrying, iteration: iteration }.merge(retry_event)) }
           )