samagotchi 0.24.0 → 0.25.0

data/lib/samagotchi/command_steps.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require_relative "guardrails/shell_lex"
+
+module Samagotchi
+  # An execute command as the steps a person reads, for the web's tool row
+  # (display only: the guardrails read the command themselves). Built from
+  # ShellLex's tokens and their spans, so each step's text is a slice of the
+  # command as the model wrote it. Rules, in order:
+  #
+  # - a heredoc's body leaves its step's text and becomes its +heredoc+
+  #   ({tag:, lines:}), also one inside a "$(cat <<'EOF' … EOF)" argument;
+  # - steps are split at && || ; | |& & and newlines; a ( … ) subshell stays
+  #   one step; +op+ is the operator before a step (nil for the first);
+  # - a leading "cd X &&" / "cd X;" becomes +cd+ (only the first);
+  # - a pipeline's last "| head …" / "| tail …" becomes the +limit+ of the
+  #   step before it ("head 20", "tail", "head -c 60");
+  # - a lone echo of a marker-wrapped string ("=== x ===", "--- x ---",
+  #   "## x") becomes the +label+ of the next step; a bare marker echo
+  #   ("---", "====", "") only spaces the output and goes;
+  # - anything the parser isn't sure of (a quote or heredoc left open,
+  #   for/while/until/if/case/function bodies, { … } groups, unbalanced
+  #   parentheses) gives nil: the UI then shows the title and the raw
+  #   command.
+  module CommandSteps
+    Step = Data.define(:text, :op, :label, :limit, :heredoc) do
+      def initialize(text:, op: nil, label: nil, limit: nil, heredoc: nil) = super
+
+      def to_h = super.compact
+    end
+
+    Parsed = Data.define(:cd, :steps) do
+      def to_h = { cd: cd, steps: steps.map(&:to_h) }.compact
+    end
+
+    Lex = Guardrails::ShellLex
+
+    SPLIT = ["&&", "||", ";", "|", "|&", "&", "\n"].freeze
+    KEYWORDS = %w[for while until if then elif else fi case esac select do done function { }].freeze
+    LIMITERS = %w[head tail].freeze
+    MARKER = /\A\s*(?:={2,}|-{2,}|#+)\s*(.*?)\s*(?:={2,}|-{2,})?\s*\z/m
+    ECHO_FLAGS = %w[-e -n -en -ne].freeze
+
+    module_function
+
+    # @return [Parsed, nil] nil when the command isn't plain enough to show
+    #   as steps
+    def parse(command)
+      text = command.to_s
+      lexer = Lex::Lexer.new(text)
+      tokens = lexer.tokens.zip(lexer.spans).map { |token, span| [*token, span] }
+      return nil if lexer.unterminated? || tokens.empty?
+
+      bodies = lexer.heredoc_spans.to_h { |doc| [doc[:span], doc[:tag]] }
+      raw = split(tokens)
+      return nil if raw.nil? || raw.empty?
+
+      steps = raw.map { |op, words| step(text, op, words, bodies) }
+      return nil if steps.any?(&:nil?)
+
+      cd, steps = leading_cd(steps, raw)
+      steps = labels(limits(steps))
+      steps.empty? ? nil : Parsed.new(cd: cd, steps: steps)
+    end
+
+    # [[op, word tokens]] split at SPLIT outside parentheses; nil for a
+    # control keyword at a command's start, ;; or unbalanced parentheses.
+    def split(tokens)
+      steps = []
+      op = nil
+      words = []
+      depth = 0
+      tokens.each do |token|
+        kind, value = token
+        if kind == :op && value == "("
+          depth += 1
+          words << token
+        elsif kind == :op && value == ")"
+          depth -= 1
+          return nil if depth.negative?
+
+          words << token
+        elsif kind == :op && depth.zero?
+          return nil unless SPLIT.include?(value)
+
+          if words.empty?
+            op = value unless value == "\n" # "a;\nb" keeps the ;
+          else
+            steps << [steps.empty? ? nil : op, words]
+            op = value
+          end
+          words = []
+        else
+          return nil if keyword?(words, token)
+
+          words << token
+        end
+      end
+      return nil unless depth.zero?
+
+      steps << [steps.empty? ? nil : op, words] unless words.empty?
+      steps
+    end
+
+    # Whether +token+ is a control keyword where a command starts (the
+    # step's first word, or the first after a "(" inside it).
+    def keyword?(words, token)
+      return false unless token[0] == :word
+
+      at_start = words.empty? || words.last[0] == :op
+      at_start && KEYWORDS.include?(token[1])
+    end
+
+    # A Step from its tokens: the text from the first to the last token,
+    # heredoc bodies cut out.
+    def step(text, op, tokens, bodies)
+      body = tokens.find { |t| bodies.key?(t.last) }
+      shown = tokens.reject { |t| bodies.key?(t.last) }
+      from = shown.map { |t| t.last.begin }.min
+      to = shown.map { |t| t.last.end }.max
+      return nil unless from
+
+      slice = text[from...to]
+      heredoc = body && { tag: bodies[body.last], lines: body_lines(text[body.last]) }
+      slice, heredoc = inner_heredoc(slice) unless heredoc
+      Step.new(text: slice.strip, op: op, heredoc: heredoc)
+    end
+
+    # A heredoc inside a $(…) in +slice+ (git commit -m "$(cat <<'EOF' …)"):
+    # the slice with the body cut out, and the heredoc; or the slice as is.
+    def inner_heredoc(slice)
+      return [slice, nil] unless slice.include?("<<")
+
+      at = 0
+      while (open = slice.index("$(", at))
+        lexer = Lex::Lexer.new(slice[(open + 2)..])
+        lexer.tokens
+        doc = lexer.heredoc_spans.first
+        if doc
+          from = open + 2 + doc[:span].begin - 1 # the newline before the body
+          to = open + 2 + doc[:span].end
+          to += 1 if slice[to] == "\n"
+          return [slice[0...from] + slice[to..], { tag: doc[:tag], lines: body_lines(slice[(from + 1)...to]) }]
+        end
+        at = open + 2
+      end
+      [slice, nil]
+    end
+
+    # The body's line count, its terminator line not counted.
+    def body_lines(body_and_tag) = [body_and_tag.to_s.chomp.lines.size - 1, 0].max
+
+    # A first "cd X" step followed by && or ; becomes the cd.
+    def leading_cd(steps, raw)
+      words = raw.first[1]
+      next_op = steps[1]&.op
+      plain = words.size == 2 && words.all? { |t| t[0] == :word } && !words[1][1].include?(Lex::SUBST)
+      return [nil, steps] unless plain && words[0][1] == "cd" && ["&&", ";"].include?(next_op)
+
+      [words[1][1], [steps[1].with(op: nil), *steps.drop(2)]]
+    end
+
+    # A pipeline's last head/tail becomes the limit of the step before it.
+    def limits(steps)
+      steps.each_with_index.with_object([]) do |(step, i), out|
+        limit = step.op == "|" && !out.empty? && out.last.limit.nil? && limit_of(step.text)
+        if limit && !["|", "|&"].include?(steps[i + 1]&.op)
+          out[-1] = out.last.with(limit: limit)
+        else
+          out << step
+        end
+      end
+    end
+
+    # "head 20" for "head -n 20" / "head -20" / "head -n20"; "head -c 60";
+    # "tail +5"; "head" alone. nil for anything else (tail -f, a file).
+    def limit_of(text)
+      words = Lex.lex(text)
+      return nil unless words.all? { |t| t[0] == :word }
+
+      name, *args = words.map { |t| t[1] }
+      return nil unless LIMITERS.include?(name)
+
+      count = case args
+              in [] then nil
+              in [/\A-\d+\z/ => arg] then arg[1..]
+              in [/\A-n\+?\d+\z/ => arg] then arg[2..]
+              in ["-n", /\A\+?\d+\z/ => arg] then arg
+              in ["-c", /\A\d+\z/ => arg] then "-c #{arg}"
+              else return nil
+              end
+      [name, count].compact.join(" ")
+    end
+
+    # A marker echo labels the next step; a bare one goes.
+    # A dropped echo's op goes to the step after it (the link from the
+    # step before).
+    def labels(steps)
+      out = []
+      label = nil
+      op = nil
+      steps.each_with_index do |step, i|
+        marker = marker_label(step.text)
+        if marker.nil? || (!marker.empty? && i == steps.size - 1)
+          step = step.with(label: label, op: op || step.op) if op
+          out << (out.empty? ? step.with(op: nil) : step)
+          label = op = nil
+        else
+          label = marker unless marker.empty?
+          op ||= step.op || "\n"
+        end
+      end
+      out
+    end
+
+    # The label of a lone marker echo ("" for a bare marker or an empty
+    # echo), nil for any other step.
+    def marker_label(text)
+      words = Lex.lex(text)
+      return nil unless words.all? { |t| t[0] == :word && !t[1].include?(Lex::SUBST) }
+
+      name, *args = words.map { |t| t[1] }
+      args.shift while ECHO_FLAGS.include?(args.first)
+      return nil unless name == "echo" && args.size <= 1
+      return "" if args.empty? || args[0].strip.empty?
+
+      match = MARKER.match(args[0])
+      return nil unless match && args[0].strip.match?(/\A(?:={2,}|-{2,}|#)/)
+
+      match[1].strip
+    end
+  end
+end

data/lib/samagotchi/config.rb

@@ -174,6 +174,8 @@ module Samagotchi
       Entry.new(key: "execute.telemetry_threshold_pct", yaml_path: %w[execute telemetry_threshold_pct], type: :integer, default: 80,     expose: %i[env config cli]),
       # Seconds one execute command may run before it is stopped (Tools::Execute::TIMEOUT_SEC).
       Entry.new(key: "execute.timeout_sec",             yaml_path: %w[execute timeout_sec],             type: :integer, default: 120,    expose: %i[env config cli]),
+      # Whether execute declares its optional description parameter (a few model-written words, a tool row's title).
+      Entry.new(key: "execute.description",             yaml_path: %w[execute description],             type: :bool,    default: true,   expose: %i[env config]),
 
       Entry.new(key: "web.port",                 yaml_path: %w[web port],                 type: :integer, default: 4567,            expose: %i[env config cli]),
       Entry.new(key: "web.host",                 yaml_path: %w[web host],                 type: :string, default: "127.0.0.1",     expose: %i[env config cli]),
@@ -666,8 +668,9 @@ module Samagotchi
     # A `sampling:` setting (hosts entry or models: entry): request parameters
     # passed through to the provider as written (keys symbolized, nested maps
     # too, so e.g. chat_template_kwargs works). A null value means "don't
-    # send it" (drops chi's own temperature default). Not a map: warns once,
-    # nil. Reserved keys warn once and are dropped. nil when nothing is left.
+    # send it" (a null temperature also keeps the empty-answer retry from
+    # setting one). Not a map: warns once, nil. Reserved keys warn once and
+    # are dropped. nil when nothing is left.
     def sampling_map(value, where)
       return nil if value.nil?
 

data/lib/samagotchi/empty_answer_retry.rb

@@ -13,8 +13,8 @@ module Samagotchi
   # when the retries run out.
   class EmptyAnswerRetry
     MAX = 3
-    # Greedy decoding on a near-identical prompt would likely loop again:
-    # the retry runs at this temperature unless one is configured.
+    # The same (or greedy) decoding on a near-identical prompt would likely
+    # loop again: the retry runs at this temperature unless one is configured.
     TEMPERATURE = 0.6
     # A generation cut at the provider's output cap (finish_reason length)
     # is retried unless the context is this full.

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"
@@ -172,8 +173,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
@@ -282,6 +284,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
@@ -2039,12 +2045,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 +2201,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 +2423,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 +2431,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"
@@ -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?
@@ -363,6 +368,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 +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.

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 })