samagotchi 0.24.0 → 0.26.0

data/lib/samagotchi/llm/openai_chat.rb

@@ -240,7 +240,6 @@ module Samagotchi
         body = {
           model: model,
           messages: cache_breakpoints(Array(messages).map { |message| wire_message(message) }, model),
-          temperature: 0.0,
           stream: @stream
         }
         body[:stream_options] = { include_usage: true } if @stream
@@ -249,7 +248,9 @@ module Samagotchi
           body[:tools] = tools
           body[:tool_choice] = "auto"
         end
-        # A configured value replaces chi's own (temperature, max_tokens); nil drops it.
+        # No temperature unless configured: each model runs at its provider's
+        # default (greedy decoding made thinking models loop). A configured
+        # value replaces chi's own (max_tokens); nil drops it.
         body.merge(options || {}).compact
       end
 
@@ -258,13 +259,13 @@ module Samagotchi
       # would pay for a cache write nothing reads, and a local model named
       # after Claude must not get Array content.
       def cache_breakpoints(messages, model)
-        return messages unless @remote && @purpose == "chat"
+        return PromptCache.without_split(messages) unless @remote && @purpose == "chat"
 
         PromptCache.mark(messages, model: model)
       end
 
       # The body's fields beyond the conversation and the stream, for the
-      # log line: "temperature=0.6 presence_penalty=1.5".
+      # log line: "temperature=0.6 presence_penalty=1.5", nil for none.
       def sampling_summary(body)
         SamplingSettings.log_text(body.except(:model, :messages, :stream, :stream_options, :tools, :tool_choice))
       end

data/lib/samagotchi/llm/prompt_cache.rb

@@ -11,6 +11,12 @@ module Samagotchi
     #   same prefix plus new messages) reads everything up to it.
     # Mid and tail system messages (reminders, turn notes) never take the
     # second mark. Other models' messages pass through untouched.
+    #
+    # A system message whose `cache_split:` says where its stable part ends
+    # (ChatLoop, from SystemPrompt#stable_length) goes as two text parts:
+    # the stable part with the mark, the per-session tail (model, location,
+    # session) without, so a new session reads the stable part from the
+    # cache. `cache_split:` never goes on the wire (#without_split).
     module PromptCache
       CONTROL = { type: "ephemeral" }.freeze
 
@@ -21,16 +27,27 @@ module Samagotchi
 
       # +messages+ (wire messages: symbol keys, content a String or an Array
       # of parts) with the breakpoints set when +model+ is a Claude model;
-      # the given messages as they are otherwise. The marked messages and
-      # parts are copies: the caller's are never changed.
+      # the given messages as they are otherwise (#without_split). The marked
+      # messages and parts are copies: the caller's are never changed.
       # @return [Array<Hash>]
       def mark(messages, model:)
-        return messages unless claude?(model)
+        return without_split(messages) unless claude?(model)
 
         indexes = [system_index(messages), last_index(messages)].compact.uniq
-        return messages if indexes.empty?
+        messages.each_with_index.map do |message, index|
+          next marked(message.except(:cache_split), split: message[:cache_split]) if indexes.include?(index)
 
-        messages.each_with_index.map { |message, index| indexes.include?(index) ? marked(message) : message }
+          message.key?(:cache_split) ? message.except(:cache_split) : message
+        end
+      end
+
+      # +messages+ without the `cache_split:` hints, for a request that sets
+      # no breakpoints.
+      # @return [Array<Hash>]
+      def without_split(messages)
+        return messages unless messages.any? { |message| message.key?(:cache_split) }
+
+        messages.map { |message| message.except(:cache_split) }
       end
 
       # Whether any message in +messages+ carries a breakpoint.
@@ -60,11 +77,19 @@ module Samagotchi
         end
       end
 
-      # A String becomes one text part; an Array gets the mark on its last
-      # text part (the last part when none is text).
-      def marked(message)
+      # A String becomes one text part (two at +split+, the mark on the
+      # first); an Array gets the mark on its last text part (the last part
+      # when none is text).
+      def marked(message, split: nil)
         content = message[:content]
-        return message.merge(content: [{ type: "text", text: content, cache_control: CONTROL }]) if content.is_a?(String)
+        if content.is_a?(String)
+          if split.is_a?(Integer) && split.positive? && split < content.length
+            return message.merge(content: [{ type: "text", text: content[0, split], cache_control: CONTROL },
+                                           { type: "text", text: content[split..] }])
+          end
+
+          return message.merge(content: [{ type: "text", text: content, cache_control: CONTROL }])
+        end
 
         target = content.rindex { |part| part.is_a?(Hash) && (part[:type] || part["type"]).to_s == "text" } ||
                  content.rindex { |part| part.is_a?(Hash) }

data/lib/samagotchi/llm/usage.rb

@@ -5,20 +5,35 @@ require_relative "../token_usage"
 module Samagotchi
   module LLM
     # A response's token counts, never nil: what the server reported
-    # (:server), else zeros (:none).
-    Usage = Data.define(:prompt_tokens, :completion_tokens, :source) do
+    # (:server), else zeros (:none). +cached_tokens+ is the prompt the server
+    # reused from its cache, +cache_write_tokens+ what it wrote to it
+    # (OpenRouter reports those for Anthropic models); 0 when not reported.
+    Usage = Data.define(:prompt_tokens, :completion_tokens, :source, :cached_tokens, :cache_write_tokens) do
       # @return [Usage, nil] nil when the payload carries no counts
       def self.from_payload(payload)
         counts = TokenUsage.from_payload(payload)
         return nil unless counts
 
         new(prompt_tokens: counts.prompt_tokens.to_i, completion_tokens: counts.completion_tokens.to_i,
-            source: :server)
+            source: :server, cached_tokens: counts.cached_tokens.to_i,
+            cache_write_tokens: counts.cache_write_tokens.to_i)
       end
 
       def self.none = new(prompt_tokens: 0, completion_tokens: 0, source: :none)
 
+      def initialize(prompt_tokens:, completion_tokens:, source:, cached_tokens: 0, cache_write_tokens: 0)
+        super
+      end
+
       def total_tokens = prompt_tokens + completion_tokens
+
+      # The request's prompt-cache counts for a :generation_completed event
+      # and the log ({} when the server reported none).
+      def cache_fields
+        return {} unless source == :server
+
+        TokenUsage.cache_fields(prompt: prompt_tokens, cached: cached_tokens, cache_write: cache_write_tokens)
+      end
     end
   end
 end

data/lib/samagotchi/log_subscriber.rb

@@ -106,7 +106,8 @@ module Samagotchi
                                         requested_model: event[:requested_model],
                                         content_length: event[:content_length],
                                         thinking_chars: event[:thinking_chars], finish_reason: event[:finish_reason],
-                                        stopped_by: event[:stopped_by])
+                                        stopped_by: event[:stopped_by], prompt: event[:prompt_tokens],
+                                        cached: event[:cached_tokens], cache_write: event[:cache_write_tokens])
       return unless event[:stopped_by]
 
       # A plugin (stop_generation) or a steer (Engine#cut_for_steer, by

data/lib/samagotchi/plugin/api.rb

@@ -264,8 +264,9 @@ module Samagotchi
 
       # Make +bundle+'s tools in +registry+ the +specs+: its tools not in
       # them go; a new one, or one whose schema or label changed, is
-      # registered (a changed one again, at the end); an unchanged one is
-      # kept as it is. A name another source has is left out. Called on
+      # registered (a changed one again, in its place: Tools::Registry
+      # orders bundle tools by bundle and name); an unchanged one is kept
+      # as it is. A name another source has is left out. Called on
       # the turn thread (Engine#apply_staged_tools!).
       # @return [Hash] {changed: Boolean, skipped: [String] (why)}
       def self.apply_tools(registry, bundle, specs, context)

data/lib/samagotchi/prompt_warmup.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+
+module Samagotchi
+  # The turn-end warm-up (cache.warmup). After a turn, the next turn's prompt
+  # differs from the last request at its tail: the previous answer's
+  # thinking is stripped (Gemma's and Qwen's specs), so a hybrid model on
+  # llama.cpp prefills from a restore point well before the end, longer
+  # with every turn. The warm-up sends that prompt, up to where the new user
+  # turn starts, while the user reads, so the next turn prefills only its
+  # own message (measured on Ornith: 0.73 s -> 0.11 s; 417 -> 26 tokens).
+  #
+  # The slot rule (R4 spike, llama.cpp with its host-memory prompt cache):
+  # - the warm-up runs on the slot the turn's last request used, which still
+  #   holds its state (Client#warm_up, `id_slot`);
+  # - the next request is pinned to that slot only while the warm-up still
+  #   runs, so it queues behind it (0.6 s) instead of starting cold on
+  #   another slot (12 s);
+  # - once the warm-up is done, nothing is pinned: the server finds the
+  #   state itself, and pinning to a slot it has since cleared skips its
+  #   prompt cache (12 s again). #take_pin forgets the slot either way.
+  class PromptWarmup
+    MODES = %w[auto off].freeze
+
+    # Whether cache.warmup allows a warm-up (auto, the default; off, false,
+    # no or 0 turn it off; anything else warns once and is auto).
+    def self.enabled?
+      value = Config.get("cache.warmup").to_s.strip.downcase
+      return false if %w[off false no 0].include?(value)
+
+      unless value.empty? || value == "auto" || @warned
+        @warned = true
+        Log.warn(:config, "invalid_value", echo: "Warning: invalid value for cache.warmup: #{value.inspect} (allowed: auto, off) — using auto",
+                                           key: "cache.warmup")
+      end
+      true
+    rescue StandardError
+      true
+    end
+
+    def initialize
+      @mutex = Mutex.new
+      # The pin (#take_pin forgets it) and the last warm-up's thread.
+      @state = nil
+      @thread = nil
+    end
+
+    # Start a warm-up of +prompt+ on +client+ in its own thread.
+    # @param slot [Integer, nil] the last request's slot (nil: unpinned, and
+    #   nothing to pin the next request to)
+    # @return [Thread]
+    def start(client:, prompt:, model:, slot:, images: [])
+      thread = Thread.new do
+        Thread.current.report_on_exception = false
+        result = client.warm_up(prompt, model: model, slot: slot, images: images)
+        Log.info(:model, "warmup", slot: result&.slot, cached: result&.cache_n, prefilled: result&.prompt_n,
+                                   prefill_ms: result&.prompt_ms, chars: prompt.length)
+        result
+      rescue StandardError => e
+        Log.warn(:model, "warmup_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        nil
+      end
+      @mutex.synchronize do
+        @thread = thread
+        @state = { thread: thread, client: client, slot: slot }
+      end
+      thread
+    end
+
+    # The slot the next request on +client+ must run on: the warm-up's,
+    # while it still runs there; nil otherwise (done, failed, unpinned, or
+    # another host). Called once per request; the first call forgets the
+    # warm-up, so no later request is ever pinned.
+    def take_pin(client)
+      state = @mutex.synchronize { @state.tap { @state = nil } }
+      return nil unless state && state[:slot].is_a?(Integer) && state[:client].equal?(client)
+
+      state[:thread].alive? ? state[:slot] : nil
+    end
+
+    # Whether a warm-up is running (specs, measurements).
+    def running?
+      thread = @mutex.synchronize { @thread }
+      thread&.alive? || false
+    end
+
+    # Wait up to +timeout+ seconds for the running warm-up (specs).
+    def wait(timeout = nil)
+      thread = @mutex.synchronize { @thread }
+      thread&.join(timeout)
+    end
+  end
+end

data/lib/samagotchi/session_metrics.rb

@@ -16,7 +16,7 @@ module Samagotchi
   # paths and SessionManager background workers.
   #
   # Each finished turn leaves a record (status, timings, model, prompt and
-  # completion tokens, tool calls, iterations, retries); session totals are
+  # completion tokens, tool calls, iterations, retries, cuts); session totals are
   # sums over the records, kept as running counters as records are added, so
   # a worker that stops and wakes again (a new collector) keeps counting:
   # #session_id= loads the records already saved.
@@ -78,10 +78,11 @@ module Samagotchi
       :gen_prompt_max,
       :gen_open,
       # The rest of this generation's server report: the largest cached and
-      # reasoning counts, the last cost, and the server's speeds and decode
+      # reasoning counts (and cache writes), the last cost, and the server's speeds and decode
       # time (llama.cpp's timings); and when its first content, reasoning or
       # tool call chunk came (an estimated speed runs from there).
       :gen_cached_max,
+      :gen_cache_write_max,
       :gen_reasoning_max,
       :gen_cost,
       :gen_decode_tps,
@@ -102,6 +103,7 @@ module Samagotchi
       # tokens of the generations with a speed. The last speeds and where the
       # decode one came from (server / estimate).
       :cached_sum,
+      :cache_write_sum,
       :reasoning_sum,
       :cost_sum,
       :decode_ms_sum,
@@ -110,6 +112,11 @@ module Samagotchi
       :last_prefill_tps,
       :tps_source,
       :retries,
+      # Generations a plugin cut (stop_generation: loop-guard's thinking
+      # watch), not a steer's cut; and ones that ended at the output cap
+      # (finish_reason length). `retries` counts the network's only.
+      :cuts,
+      :capped,
       :model,
       :id,
       :started_at,
@@ -265,6 +272,7 @@ module Samagotchi
         end
       when :generation_completed, :generation_cancelled
         record_served_model(event)
+        count_cut(event)
         record_generation_completed
       when :generation_retrying
         # The retry streams from the start: its counts replace the ones so far.
@@ -364,6 +372,8 @@ module Samagotchi
         iterations_total: totals[:iterations] + (turn&.iteration_count || 0),
         gen_latency_ms: (totals[:gen_ms] + (turn&.gen_latency_accum || 0)).round,
         retries: totals[:retries] + (turn&.retries || 0),
+        cuts: totals[:cuts] + (turn&.cuts || 0),
+        capped: totals[:capped] + (turn&.capped || 0),
         started_at: @started_at,
         last_activity_at: @last_activity_at,
         # From the session's first start (an earlier process's too), to now.
@@ -386,6 +396,7 @@ module Samagotchi
         prompt_sum: add.call(:prompt_sum),
         completion_sum: add.call(:completion_sum),
         cached_sum: add.call(:cached_sum),
+        cache_write_sum: add.call(:cache_write_sum),
         reasoning_sum: add.call(:reasoning_sum),
         cost_sum: add.call(:cost_sum),
         decode_ms_sum: decode_ms.round,
@@ -435,6 +446,7 @@ module Samagotchi
           gen_prompt_max: 0,
           gen_open: false,
           gen_cached_max: 0,
+          gen_cache_write_max: 0,
           gen_reasoning_max: 0,
           generations: 0,
           prompt_last: nil,
@@ -443,11 +455,14 @@ module Samagotchi
           completion_sum: 0,
           token_sources: [],
           cached_sum: 0,
+          cache_write_sum: 0,
           reasoning_sum: 0,
           cost_sum: nil,
           decode_ms_sum: 0,
           decode_tokens_sum: 0,
           retries: 0,
+          cuts: 0,
+          capped: 0,
           model: nil,
           id: event[:turn_id] || SecureRandom.uuid,
           started_at: now.iso8601(3),
@@ -500,6 +515,15 @@ module Samagotchi
       end
     end
 
+    def count_cut(event)
+      @mutex.synchronize do
+        next unless @turn
+
+        @turn.cuts += 1 if event[:stopped_by] && event[:stopped_by].to_s != "steer"
+        @turn.capped += 1 if event[:finish_reason].to_s == "length"
+      end
+    end
+
     def record_generation_completed
       @mutex.synchronize { close_generation if @turn&.gen_open }
     end
@@ -544,6 +568,7 @@ module Samagotchi
     # here: it has no speed. Caller holds the mutex.
     def close_server_report(turn, completion)
       turn.cached_sum += turn.gen_cached_max
+      turn.cache_write_sum += turn.gen_cache_write_max
       turn.reasoning_sum += turn.gen_reasoning_max
       turn.cost_sum = turn.cost_sum.to_f + turn.gen_cost if turn.gen_cost
       turn.last_prefill_tps = turn.gen_prefill_tps.round(1) if turn.gen_prefill_tps
@@ -582,6 +607,7 @@ module Samagotchi
       @turn.gen_had_server = false
       @turn.gen_estimate_sum = 0
       @turn.gen_cached_max = 0
+      @turn.gen_cache_write_max = 0
       @turn.gen_reasoning_max = 0
       @turn.gen_cost = nil
       @turn.gen_decode_tps = @turn.gen_prefill_tps = @turn.gen_decode_ms = nil
@@ -605,7 +631,9 @@ module Samagotchi
         tool_calls: turn.tool_calls,
         tool_errors: turn.tool_errors,
         iterations: turn.iteration_count,
-        retries: turn.retries
+        retries: turn.retries,
+        cuts: turn.cuts,
+        capped: turn.capped
       }.merge(turn_usage_fields(turn))
     end
 
@@ -622,6 +650,7 @@ module Samagotchi
         prefill_tps: turn.last_prefill_tps,
         tps_source: turn.tps_source
       }
+      fields[:cache_write_tokens_sum] = turn.cache_write_sum if turn.cache_write_sum.positive?
       fields.merge!(cost: turn.cost_sum, cost_source: "reported") if turn.cost_sum
       fields
     end
@@ -708,6 +737,7 @@ module Samagotchi
       turn.gen_prompt_max = [turn.gen_prompt_max, usage.prompt_tokens.to_i].max
       turn.gen_completion_max = [turn.gen_completion_max, usage.completion_tokens.to_i].max
       turn.gen_cached_max = [turn.gen_cached_max, usage.cached_tokens.to_i].max
+      turn.gen_cache_write_max = [turn.gen_cache_write_max, usage.cache_write_tokens.to_i].max
       turn.gen_reasoning_max = [turn.gen_reasoning_max, usage.reasoning_tokens.to_i].max
       turn.gen_cost = usage.cost if usage.cost
       if usage.predicted_per_second && usage.predicted_ms
@@ -857,7 +887,8 @@ module Samagotchi
     # (#snapshot adds the running turn). Caller holds the mutex.
     def reset_totals
       @totals = { cancellations: 0, prompt_sum: 0, completion_sum: 0, token_sources: [], iterations: 0,
-                  gen_ms: 0, retries: 0, by_tool: {}, tool_errors: 0, cached_sum: 0, reasoning_sum: 0,
+                  gen_ms: 0, retries: 0, cuts: 0, capped: 0, by_tool: {}, tool_errors: 0, cached_sum: 0, cache_write_sum: 0,
+                  reasoning_sum: 0,
                   cost_sum: 0, decode_ms_sum: 0, decode_tokens_sum: 0, last_decode_tps: nil,
                   last_prefill_tps: nil, tps_source: nil }
     end
@@ -870,7 +901,10 @@ module Samagotchi
       totals[:iterations] += number(record[:iterations])
       totals[:gen_ms] += number(record[:gen_ms])
       totals[:retries] += number(record[:retries])
+      totals[:cuts] += number(record[:cuts])
+      totals[:capped] += number(record[:capped])
       totals[:cached_sum] += number(record[:cached_tokens_sum])
+      totals[:cache_write_sum] += number(record[:cache_write_tokens_sum])
       totals[:reasoning_sum] += number(record[:reasoning_tokens])
       totals[:cost_sum] += number(record[:cost])
       totals[:decode_ms_sum] += number(record[:decode_ms])

data/lib/samagotchi/system_prompt.rb

@@ -14,8 +14,9 @@ module Samagotchi
   # The system prompt an Engine gives its model: the base prompt (tool
   # declarations and call syntax for the raw-prompt loop, none for the chat
   # loop, the shared guidance) and around it the thinking token, rg
-  # guidance, AGENT.md, where the session runs, the memory indexes, the
-  # identity memory and the preloaded memories.
+  # guidance, the identity memory, the preloaded memories, AGENT.md, the
+  # memory indexes and, last, the model, where the session runs and the
+  # session (#system_prompt_with_index has the order and why).
   #
   # What changes during a session (the profile after a model switch, the
   # tools a plugin replaces, the attached session, the thinking level) is
@@ -77,8 +78,16 @@ module Samagotchi
     # indexes and memories again (a model or profile switch, changed tools).
     def reset!
       @built = nil
+      @stable_lengths = nil
     end
 
+    # The length of +prompt+'s stable part when it is a chat prompt #build
+    # made: everything before the model, location and session lines, which
+    # a remote prompt cache can keep for every session (PromptCache). nil
+    # for any other text, or a prompt without those lines.
+    # @return [Integer, nil]
+    def stable_length(prompt) = @stable_lengths&.[](prompt)
+
     # The base prompt (specs, plugins' declarations), with Gemma's tool
     # declarations at its end as #build has them.
     def base(chat: false, thinking: nil)
@@ -186,7 +195,7 @@ module Samagotchi
           6. Use write for full-file rewrites or creating new files.
 
         Memory convention:
-          Project scope: one folder per git repository, shared by its worktrees and subdirectories (path shown above)
+          Project scope: one folder per git repository, shared by its worktrees and subdirectories (its path is on the "Project memories folder:" line below)
           System scope:  ~/.config/samagotchi/memories/ (cross-project)
           memory_read accepts optional scope (project|system).
           memory_write requires explicit scope and entry name.
@@ -229,16 +238,28 @@ module Samagotchi
     # @param chat [Boolean] no Gemma thinking token (the chat API's template
     #   decides about thinking)
     # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
+    #
+    # Ordered for the servers' prompt caches (they reuse only an exact token
+    # prefix): what every session shares first, what changes least before
+    # what changes more, and the per-session lines last. The global parts
+    # (identity, preloads) come before the project's AGENT.md, the memory
+    # indexes (a memory write changes them) after both; the model, the
+    # location and the session close the prompt (Gemma's tool declarations
+    # still follow them).
     def system_prompt_with_index(base, chat: false, thinking: nil)
-      project_index = read_memory_index("project")
-      system_index = read_memory_index("system")
-      project_description = project_specific_description
       thinking_token = chat ? "" : Thinking.native(thinking || turn_thinking, profile).system_token
       memory_sections = [
-        "Project memories:\n#{project_index}",
-        "System memories:\n#{system_index}"
+        "Project memories:\n#{read_memory_index("project")}",
+        "System memories:\n#{read_memory_index("system")}"
       ].join("\n\n")
-      prompt = [thinking_token + base, rg_guidance, project_description, project_location, current_model, current_session, memory_sections, system_identity_section, explicit_memory_section].compact.join("\n")
+      stable = [thinking_token + base, rg_guidance, system_identity_section, explicit_memory_section,
+                project_specific_description, memory_sections]
+      stable_text = stable.compact.join("\n")
+      volatile = [current_model, project_location, current_session].compact
+      return with_tail_declarations(stable_text, chat: chat) if volatile.empty?
+
+      prompt = "#{stable_text}\n#{volatile.join("\n")}"
+      (@stable_lengths ||= {})[prompt] = stable_text.length + 1 if chat
       with_tail_declarations(prompt, chat: chat)
     end
 

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -23,6 +23,7 @@ require_relative "../session_manager"
 require_relative "../session_metrics"
 require_relative "../guardrails/parent_approvals"
 require_relative "../tool_activity"
+require_relative "../tool_view"
 require_relative "../web/message_parts"
 
 module Samagotchi
@@ -1109,7 +1110,8 @@ module Samagotchi
         output = part[:output]
         status = output.nil? ? "no result" : ToolActivity.tool_activity_status(output, part[:tool])
         activity = { action: part[:label] || ToolActivity.tool_activity_action(part[:tool]), tool: part[:tool],
-                     params: part[:params], status: status }
+                     params: part[:params], status: status,
+                     description: ToolView.description_title(part[:view] || {}) }
         "#{format_tool_activity_line(activity, duration_ms: duration_ms)}" \
           "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
       end
@@ -1202,8 +1204,9 @@ module Samagotchi
       def replay_tool_completed(event)
         return @renderer.call({ duration_ms: nil }.merge(event)) if event.dig(:activity, :action)
 
-        activity = event[:activity] || {}
+        activity = EventRenderer.described(event) || {}
         @screen.commit(snapshot_tool_line({ tool: event[:tool], params: activity[:params], status: activity[:status],
+                                            description: activity[:description],
                                             images: event[:images], diff: event[:diff] }))
       end
 

data/lib/samagotchi/terminal_ui/attached_view.rb

@@ -4,6 +4,8 @@ require "monitor"
 require_relative "formatting"
 require_relative "../output_formatter"
 require_relative "../turn_tally"
+require_relative "../tool_view"
+require_relative "event_renderer"
 require_relative "thinking_line"
 
 module Samagotchi
@@ -111,7 +113,8 @@ module Samagotchi
           @retry = nil
           @waiting_since = nil
           @tool = "running #{event[:tool]}"
-          @tally.started(key: tally_key(event), tool: event[:tool], params: event[:params])
+          @tally.started(key: tally_key(event), tool: event[:tool], params: event[:params],
+                         description: ToolView.description_title(event[:view] || {}))
           redraw_status
         end
       end
@@ -119,7 +122,8 @@ module Samagotchi
       def tool_call_feedback_completed(event)
         @lock.synchronize do
           @tally.completed(key: tally_key(event), tool: event[:tool],
-                           status: event.dig(:activity, :status), params: event.dig(:activity, :params))
+                           status: event.dig(:activity, :status), params: event.dig(:activity, :params),
+                           description: EventRenderer.described(event)&.dig(:description))
         end
       end
 

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "formatting"
+require_relative "../tool_view"
 
 module Samagotchi
   class TerminalUI
@@ -70,8 +71,8 @@ module Samagotchi
           @view.tool_call_feedback_completed(event)
           # A replayed row (a join) carries its duration (nil: unknown).
           measured = tool_duration_ms(event)
-          render_streamed_tool_activity(event[:activity], duration_ms: event.fetch(:duration_ms, measured), images: event[:images],
-                                                          diff: event[:diff])
+          render_streamed_tool_activity(self.class.described(event), duration_ms: event.fetch(:duration_ms, measured),
+                                                                     images: event[:images], diff: event[:diff])
         when :generation_completed, :generation_cancelled, :tool_dispatch_started
           @view.generation_feedback_finished
         when :pending_input_merged
@@ -190,6 +191,17 @@ module Samagotchi
         Array(event[:steers]).each { |steer| @view.print_line(@view.format_steer_line(source: steer[:source], text: steer[:text])) }
       end
 
+      # A tool_call_completed's activity with the command's description:
+      # its own, else its view's (a snapshot's replay carries the view, not
+      # the description). nil for an event without one.
+      def self.described(event)
+        activity = event[:activity]
+        return activity if activity.nil? || activity[:description] || !event[:view].is_a?(Hash)
+
+        description = ToolView.description_title(event[:view].transform_keys(&:to_sym))
+        description ? activity.merge(description: description) : activity
+      end
+
       private
 
       def render_streamed_tool_activity(activity, duration_ms:, images: nil, diff: nil)