samagotchi 0.24.0 → 0.25.0

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

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -11,11 +11,21 @@ module Samagotchi
     # $stdout is a colour terminal.
     module Formatting
       def format_tool_activity_line(activity, duration_ms: nil)
-        params = activity[:params].to_s.strip
-        params_suffix = params.empty? ? "" : " #{paint(params, 90)}"
         status = activity[:status].to_s
         elapsed_suffix = duration_ms.nil? ? "" : " (#{format_elapsed_duration(duration_ms)})"
-        "#{paint("tool>", 36)} #{activity[:action]} (#{activity[:tool]}#{params_suffix}): #{paint(status, status_color(status))}#{elapsed_suffix}"
+        "#{paint("tool>", 36)} #{activity[:action]} (#{activity[:tool]}#{tool_params_suffix(activity)}): " \
+          "#{paint(status, status_color(status))}#{elapsed_suffix}"
+      end
+
+      # What a tool line says the call did: the model's description of a
+      # command (": List the specs") in place of its cut params, else the
+      # params, dim.
+      def tool_params_suffix(activity)
+        description = activity[:description].to_s.strip
+        return ": #{description}" unless description.empty?
+
+        params = activity[:params].to_s.strip
+        params.empty? ? "" : " #{paint(params, 90)}"
       end
 
       # Green ok, yellow stopped (a wait the user's Stop ended), red the rest.
@@ -30,12 +40,22 @@ module Samagotchi
 
       STEER_PREVIEW = 80
 
+      # Who a steer names as its sender: a plugin's own label, chi's sender
+      # ids in words (the web's format.js steerSender agrees;
+      # spec/shared/labels_matrix.json). "": no one named.
+      STEER_SENDERS = { "parent_agent" => "parent agent", "chi_send" => "chi send", "plugin_send" => "plugin" }.freeze
+
+      def steer_sender(source)
+        STEER_SENDERS.fetch(source.to_s, source.to_s)
+      end
+
       # "check-in> nudged: <text>", dim, one line cut: a plugin's steer
       # (Steer) in the running turn or the join's last exchange.
       def format_steer_line(source:, text:)
         first = text.to_s.strip.split("\n").first.to_s
         first = "#{first[0, STEER_PREVIEW - 1]}…" if first.length > STEER_PREVIEW || text.to_s.strip.include?("\n")
-        paint("#{source.to_s.empty? ? "plugin" : source}> nudged: #{first}", 90)
+        sender = steer_sender(source)
+        paint("#{sender.empty? ? "plugin" : sender}> nudged: #{first}", 90)
       end
 
       # "↻ empty answer, asking again (1/1)": the loop retries an empty answer;
@@ -119,10 +139,8 @@ module Samagotchi
 
       # A tool call from the snapshot: it has no action text, only the tool.
       def snapshot_tool_line(part)
-        params = part[:params].to_s.strip
-        params_suffix = params.empty? ? "" : " #{paint(params, 90)}"
         status = part[:status].to_s
-        "#{paint("tool>", 36)} #{part[:tool]}#{params_suffix}: #{paint(status, status_color(status))}" \
+        "#{paint("tool>", 36)} #{part[:tool]}#{tool_params_suffix(part)}: #{paint(status, status_color(status))}" \
           "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
       end
 
@@ -385,6 +403,9 @@ module Samagotchi
         lines << "gen latency (ms): #{snapshot[:gen_latency_ms]}"
         lines << "cancellations:    #{snapshot[:cancellations]}"
         lines << "retries:          #{snapshot[:retries]}"
+        # A looped session: loop-guard's cuts, or thinking that ran to the cap.
+        lines << "thinking cuts:    #{snapshot[:cuts].to_i}"
+        lines << "output cap hits:  #{snapshot[:capped].to_i}"
         context = snapshot[:context] || {}
         if context[:used_tokens]
           pct = context[:window_tokens].to_i.positive? ? format(" (%.1f%%)", context[:used_tokens] * 100.0 / context[:window_tokens]) : ""
@@ -400,14 +421,15 @@ module Samagotchi
         lines.join("\n")
       end
 
-      # ", cached 4864 (93%), reasoning 212" for the tokens line; the counts a
-      # server didn't report are left out.
+      # ", cached 4864 (93%), cache writes 312, reasoning 212" for the tokens
+      # line; the counts a server didn't report are left out.
       def token_breakdown_text(tokens)
         cached = tokens[:cached_sum].to_i
         reasoning = tokens[:reasoning_sum].to_i
         prompt = tokens[:prompt_sum].to_i
         text = +""
         text << ", cached #{cached} (#{(cached * 100.0 / prompt).round}%)" if cached.positive? && prompt.positive?
+        text << ", cache writes #{tokens[:cache_write_sum].to_i}" if tokens[:cache_write_sum].to_i.positive?
         text << ", reasoning #{reasoning}" if reasoning.positive?
         text
       end