samagotchi 0.19.0 → 0.20.0

data/lib/samagotchi/session_metrics.rb

@@ -20,8 +20,10 @@ module Samagotchi
   # 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.
-  # Only prompt and completion counts, which every backend reports the same
-  # way, are kept.
+  # Prompt and completion counts come from every backend. Cached and reasoning
+  # tokens, cost (OpenRouter's usage.cost) and the server's speeds (llama.cpp's
+  # timings) are kept when the server reports them; a generation without a
+  # server speed gets an estimated decode speed (see #close_generation).
   #
   # A snapshot is surfaced via Engine#session_state_snapshot (the Bridge's
   # /state, /snapshot, /stats and SSE frames) and persisted to a sibling
@@ -35,6 +37,25 @@ module Samagotchi
     # unsaved ones of a collector whose saves keep failing stay bounded.
     LIVE_RECORDS_CAP = 20
 
+    # A generation shorter than this gets no decode speed of its own: one
+    # tiny generation would skew the session's average.
+    SPEED_MIN_TOKENS = 8
+    SPEED_MIN_MS = 100
+
+    # The session's token totals as a saved analytics.json has them (zeros
+    # where an older file lacks a count), with how full the context was.
+    # A generation's decode speed (tokens per second) and where it came
+    # from: "server" (llama.cpp's timings) or "estimate".
+    GenerationSpeed = Data.define(:decode_tps, :source)
+
+    # What #finish_generation reports: the generation's speed (nil when it
+    # had none) and the session's tokens block as the snapshot has it.
+    GenerationReport = Data.define(:speed, :tokens)
+
+    SavedSummary = Data.define(:ctx_pct, :prompt_sum, :completion_sum, :cached_sum, :reasoning_sum, :cost_sum) do
+      def tokens = to_h.except(:ctx_pct)
+    end
+
     # Per-turn transient state, reset on each turn_started.
     TurnState = Struct.new(
       :session_id,
@@ -56,6 +77,17 @@ module Samagotchi
       # comes cumulative per request) and whether it is still streaming.
       :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
+      # 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_reasoning_max,
+      :gen_cost,
+      :gen_decode_tps,
+      :gen_prefill_tps,
+      :gen_decode_ms,
+      :gen_first_chunk_at,
       # The turn's generations, folded as each one ends: the count, the last
       # one's prompt and completion, the sums, and which kinds of counts
       # (server / estimate) they came from.
@@ -65,6 +97,18 @@ module Samagotchi
       :completion_last,
       :completion_sum,
       :token_sources,
+      # Summed over the turn's generations: cached and reasoning tokens, the
+      # cost (nil until one reports it), and the decode time and completion
+      # tokens of the generations with a speed. The last speeds and where the
+      # decode one came from (server / estimate).
+      :cached_sum,
+      :reasoning_sum,
+      :cost_sum,
+      :decode_ms_sum,
+      :decode_tokens_sum,
+      :last_decode_tps,
+      :last_prefill_tps,
+      :tps_source,
       :retries,
       :model,
       :id,
@@ -80,7 +124,27 @@ module Samagotchi
     # @param session_dir [String]
     # @return [Float, nil]
     def self.saved_context_pct(session_dir)
-      context = JSON.parse(File.read(File.join(session_dir, "analytics.json")))["context"]
+      saved_summary(session_dir)&.ctx_pct
+    end
+
+    # The context's fill and the token totals from the session's saved
+    # analytics.json, read once; nil without a readable file.
+    # @param session_dir [String]
+    # @return [SavedSummary, nil]
+    def self.saved_summary(session_dir)
+      data = JSON.parse(File.read(File.join(session_dir, "analytics.json")))
+      return nil unless data.is_a?(Hash)
+
+      tokens = data["tokens"].is_a?(Hash) ? data["tokens"] : {}
+      count = ->(key) { tokens[key].is_a?(Numeric) ? tokens[key] : 0 }
+      SavedSummary.new(ctx_pct: saved_pct(data["context"]), prompt_sum: count.("prompt_sum"),
+                       completion_sum: count.("completion_sum"), cached_sum: count.("cached_sum"),
+                       reasoning_sum: count.("reasoning_sum"), cost_sum: count.("cost_sum"))
+    rescue JSON::ParserError, SystemCallError, TypeError
+      nil
+    end
+
+    def self.saved_pct(context)
       return nil unless context.is_a?(Hash)
 
       used = context["used_tokens"]
@@ -88,9 +152,8 @@ module Samagotchi
       return nil unless used.is_a?(Numeric) && window.is_a?(Numeric) && window.positive?
 
       used * 100.0 / window
-    rescue JSON::ParserError, SystemCallError, TypeError
-      nil
     end
+    private_class_method :saved_pct
 
     # One turn's tool records from the session's saved analytics.json, in
     # call order (iteration, then call_index), string-keyed as saved: what a
@@ -236,6 +299,17 @@ module Samagotchi
       @mutex.synchronize { build_snapshot(:recent) }
     end
 
+    # Close the open generation now, ahead of its :generation_completed
+    # (which then finds it closed), and report its speed with the session's
+    # running token totals: what the event carries to the UIs.
+    # @return [GenerationReport]
+    def finish_generation
+      @mutex.synchronize do
+        speed = close_generation if @turn&.gen_open
+        GenerationReport.new(speed: speed, tokens: tokens_block(@totals, @turn))
+      end
+    end
+
     # The served model a generation last reported and the name asked for
     # then, without building a snapshot (Engine#served_model).
     # @return [Hash] :served_model, :served_model_for
@@ -278,11 +352,7 @@ module Samagotchi
         session_id: @session_id,
         turns: @turn_records.size + (turn ? 1 : 0),
         cancellations: totals[:cancellations],
-        tokens: {
-          prompt_sum: totals[:prompt_sum] + (turn&.prompt_sum || 0),
-          completion_sum: totals[:completion_sum] + (turn&.completion_sum || 0),
-          source: combined_source(totals[:token_sources] + (turn&.token_sources || []))
-        },
+        tokens: tokens_block(totals, turn),
         context: context_block(@turn_records),
         profile: @profile,
         profile_source: @profile_source,
@@ -304,6 +374,30 @@ module Samagotchi
       }
     end
 
+    # The session's token totals, with the running turn's finished
+    # generations; the last speeds are the newest a generation reported.
+    # Caller holds the mutex.
+    def tokens_block(totals, turn)
+      add = ->(key) { totals[key] + (turn&.public_send(key) || 0) }
+      decode_ms = add.(:decode_ms_sum)
+      decode_tokens = add.(:decode_tokens_sum)
+      speed_turn = turn&.last_decode_tps ? turn : nil
+      {
+        prompt_sum: add.(:prompt_sum),
+        completion_sum: add.(:completion_sum),
+        cached_sum: add.(:cached_sum),
+        reasoning_sum: add.(:reasoning_sum),
+        cost_sum: add.(:cost_sum),
+        decode_ms_sum: decode_ms.round,
+        decode_tokens_sum: decode_tokens,
+        avg_decode_tps: decode_ms.positive? ? (decode_tokens * 1000.0 / decode_ms).round(1) : nil,
+        last_decode_tps: speed_turn ? speed_turn.last_decode_tps : totals[:last_decode_tps],
+        last_prefill_tps: turn&.last_prefill_tps || totals[:last_prefill_tps],
+        tps_source: speed_turn ? speed_turn.tps_source : totals[:tps_source],
+        source: combined_source(totals[:token_sources] + (turn&.token_sources || []))
+      }
+    end
+
     # The records a snapshot carries, copied. :all is every record; :recent
     # the newest turn this collector finished (live before its save lands)
     # and the unsaved ones (capped), and the tool records of those turns and
@@ -340,12 +434,19 @@ module Samagotchi
           gen_estimate_sum: 0,
           gen_prompt_max: 0,
           gen_open: false,
+          gen_cached_max: 0,
+          gen_reasoning_max: 0,
           generations: 0,
           prompt_last: nil,
           prompt_sum: 0,
           completion_last: 0,
           completion_sum: 0,
           token_sources: [],
+          cached_sum: 0,
+          reasoning_sum: 0,
+          cost_sum: nil,
+          decode_ms_sum: 0,
+          decode_tokens_sum: 0,
           retries: 0,
           model: nil,
           id: event[:turn_id] || SecureRandom.uuid,
@@ -407,14 +508,17 @@ module Samagotchi
     # instead (there is no prompt count then). The two paths are mutually
     # exclusive per generation, so a final chunk carrying timings while
     # earlier chunks did not will not double count. Caller holds the mutex.
+    # @return [GenerationSpeed, nil] the generation's speed, if it had one
     def close_generation
       turn = @turn
       turn.gen_open = false
+      speed = nil
       if turn.gen_had_server
         completion = turn.gen_completion_max
         turn.prompt_last = turn.gen_prompt_max
         turn.prompt_sum += turn.gen_prompt_max
         turn.token_sources |= ["server"]
+        speed = close_server_report(turn, completion)
       else
         completion = turn.gen_estimate_sum
         turn.token_sources |= ["estimate"] if completion.positive?
@@ -422,11 +526,51 @@ module Samagotchi
       turn.completion_last = completion
       turn.completion_sum += completion
       started = turn.gen_started_at
-      return unless started
+      return speed unless started
 
       elapsed_ms = (monotonic_time - started) * 1000.0
       turn.gen_latency_accum += elapsed_ms if elapsed_ms > 0
       turn.gen_started_at = nil
+      speed
+    end
+
+    # The generation's cached/reasoning counts, cost and decode speed, into
+    # the turn. The speed is the server's (llama.cpp's predicted_per_second
+    # over its predicted_ms) or, without one, an estimate: the completion
+    # over the time from the first streamed chunk to now (that leaves out
+    # queueing and the prefill). An estimated chars/4 generation never gets
+    # here: it has no speed. Caller holds the mutex.
+    def close_server_report(turn, completion)
+      turn.cached_sum += turn.gen_cached_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
+      speed = generation_speed(turn, completion)
+      return unless speed
+
+      tps, decode_ms, source = speed
+      turn.decode_ms_sum += decode_ms
+      turn.decode_tokens_sum += completion
+      turn.last_decode_tps = tps.round(1)
+      turn.tps_source = source
+      GenerationSpeed.new(decode_tps: turn.last_decode_tps, source: source)
+    end
+
+    # [tokens per second, decode ms, "server" | "estimate"], or nil for a
+    # generation too short (or without a first chunk) to time.
+    def generation_speed(turn, completion)
+      if turn.gen_decode_tps && turn.gen_decode_ms
+        decode_ms = turn.gen_decode_ms
+        tps = turn.gen_decode_tps
+        source = "server"
+      elsif turn.gen_first_chunk_at
+        decode_ms = (monotonic_time - turn.gen_first_chunk_at) * 1000.0
+        tps = decode_ms.positive? ? completion * 1000.0 / decode_ms : 0
+        source = "estimate"
+      end
+      return nil unless decode_ms && completion >= SPEED_MIN_TOKENS && decode_ms >= SPEED_MIN_MS
+
+      [tps, decode_ms, source]
     end
 
     # Caller holds the mutex.
@@ -435,6 +579,11 @@ module Samagotchi
       @turn.gen_prompt_max = 0
       @turn.gen_had_server = false
       @turn.gen_estimate_sum = 0
+      @turn.gen_cached_max = 0
+      @turn.gen_reasoning_max = 0
+      @turn.gen_cost = nil
+      @turn.gen_decode_tps = @turn.gen_prefill_tps = @turn.gen_decode_ms = nil
+      @turn.gen_first_chunk_at = nil
     end
 
     # The turn record's model and token fields. The context used at the end
@@ -455,7 +604,24 @@ module Samagotchi
         tool_errors: turn.tool_errors,
         iterations: turn.iteration_count,
         retries: turn.retries
+      }.merge(turn_usage_fields(turn))
+    end
+
+    # The rest of the server's report: cached and reasoning tokens, the cost,
+    # and the speeds (decode_tps is the turn's last generation's, decode_ms
+    # and decode_tokens what the session's average is weighted by).
+    def turn_usage_fields(turn)
+      fields = {
+        cached_tokens_sum: turn.cached_sum,
+        reasoning_tokens: turn.reasoning_sum,
+        decode_ms: turn.decode_ms_sum.round,
+        decode_tokens: turn.decode_tokens_sum,
+        decode_tps: turn.last_decode_tps,
+        prefill_tps: turn.last_prefill_tps,
+        tps_source: turn.tps_source
       }
+      fields.merge!(cost: turn.cost_sum, cost_source: "reported") if turn.cost_sum
+      fields
     end
 
     def record_tool_call_start(event)
@@ -519,15 +685,10 @@ module Samagotchi
       payload = event[:payload]
       payload = {} unless payload.is_a?(Hash)
 
+      @mutex.synchronize { note_first_chunk(payload, event) }
       usage = TokenUsage.from_payload(payload)
       if usage
-        @mutex.synchronize do
-          if @turn
-            @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_had_server = true
-          end
-        end
+        @mutex.synchronize { note_server_usage(usage) if @turn }
       else
         @mutex.synchronize do
           chars = event_content_chars(payload, event)
@@ -539,6 +700,37 @@ module Samagotchi
       end
     end
 
+    # Caller holds the mutex.
+    def note_server_usage(usage)
+      turn = @turn
+      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_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
+        turn.gen_decode_tps = usage.predicted_per_second
+        turn.gen_decode_ms = usage.predicted_ms
+      end
+      turn.gen_prefill_tps = usage.prompt_per_second if usage.prompt_per_second
+      turn.gen_had_server = true
+    end
+
+    # The first chunk with content, reasoning or a tool call starts the
+    # generation's decode clock (an estimated speed runs from it). Caller
+    # holds the mutex.
+    def note_first_chunk(payload, event)
+      return unless @turn && @turn.gen_open && @turn.gen_first_chunk_at.nil?
+      return unless !event[:content].to_s.empty? || tool_call_delta?(payload)
+
+      @turn.gen_first_chunk_at = monotonic_time
+    end
+
+    def tool_call_delta?(payload)
+      choice = payload["choices"].is_a?(Array) ? payload["choices"].first : nil
+      choice.is_a?(Hash) && choice["delta"].is_a?(Hash) && !Array(choice["delta"]["tool_calls"]).empty?
+    end
+
     def event_content_chars(payload, event)
       len = payload_content(payload, event).length
       len.positive? ? len : nil
@@ -663,7 +855,9 @@ 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 }
+                  gen_ms: 0, retries: 0, by_tool: {}, tool_errors: 0, cached_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
 
     def count_turn(record)
@@ -674,6 +868,17 @@ module Samagotchi
       totals[:iterations] += number(record[:iterations])
       totals[:gen_ms] += number(record[:gen_ms])
       totals[:retries] += number(record[:retries])
+      totals[:cached_sum] += number(record[:cached_tokens_sum])
+      totals[:reasoning_sum] += number(record[:reasoning_tokens])
+      totals[:cost_sum] += number(record[:cost])
+      totals[:decode_ms_sum] += number(record[:decode_ms])
+      totals[:decode_tokens_sum] += number(record[:decode_tokens])
+      # The newest speeds a record has (an older record has none).
+      if record[:decode_tps].is_a?(Numeric)
+        totals[:last_decode_tps] = record[:decode_tps]
+        totals[:tps_source] = record[:tps_source]
+      end
+      totals[:last_prefill_tps] = record[:prefill_tps] if record[:prefill_tps].is_a?(Numeric)
       source = record[:token_source]
       totals[:token_sources] |= [source.to_s] unless source.nil?
     end

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -221,6 +221,26 @@ module Samagotchi
         duration_ms.nil? ? "" : " · #{format_elapsed_duration(duration_ms)}"
       end
 
+      # "87 tok/s", "1.9k tok/s"; "~64 tok/s" for an estimate; "" without a
+      # speed. The web says the same (ctx.js speedText;
+      # spec/shared/labels_matrix.json).
+      def speed_text(tps, source)
+        value = tps.to_f
+        return "" unless value.positive?
+
+        number = value >= 1000 ? "#{format('%.1f', (value / 100).round / 10.0)}k" : value.round.to_s
+        "#{'~' if source.to_s == 'estimate'}#{number} tok/s"
+      end
+
+      # "$0.42"; a cost under a cent keeps four decimals ("$0.0012"); "" for
+      # none. As ctx.js costText.
+      def cost_text(cost)
+        value = cost.to_f
+        return "" unless value.positive?
+
+        value >= 0.01 ? format("$%.2f", value) : format("$%.4f", value)
+      end
+
       private
 
       # The recap shown on return: dim, one "recap>" block, noting how many
@@ -343,7 +363,11 @@ module Samagotchi
         end
         lines << "iterations:       #{snapshot[:iterations_total]}"
         # Summed over every request: each prompt is sent in full again.
-        lines << "tokens in/out:    #{tokens[:prompt_sum].to_i}/#{tokens[:completion_sum].to_i} (all requests, #{token_src_label})"
+        lines << "tokens in/out:    #{tokens[:prompt_sum].to_i}/#{tokens[:completion_sum].to_i} (all requests, #{token_src_label})" \
+                 "#{token_breakdown_text(tokens)}"
+        speed = stats_speed_text(tokens)
+        lines << "speed:            #{speed}" if speed
+        lines << "cost:             #{cost_text(tokens[:cost_sum])} (this session only)" if tokens[:cost_sum].to_f.positive?
         lines << "gen latency (ms): #{snapshot[:gen_latency_ms]}"
         lines << "cancellations:    #{snapshot[:cancellations]}"
         lines << "retries:          #{snapshot[:retries]}"
@@ -362,6 +386,33 @@ 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.
+      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 << ", reasoning #{reasoning}" if reasoning.positive?
+        text
+      end
+
+      # "87 tok/s out, 1.9k tok/s prompt (last, server), avg 81 tok/s", or nil
+      # before a generation had a speed. The prompt (prefill) speed only when
+      # the server reported it.
+      def stats_speed_text(tokens)
+        last = tokens[:last_decode_tps]
+        return nil unless last
+
+        source = tokens[:tps_source].to_s
+        text = +"#{speed_text(last, source)} out"
+        text << ", #{speed_text(tokens[:last_prefill_tps], 'server')} prompt" if tokens[:last_prefill_tps]
+        text << " (last, #{source})"
+        text << ", avg #{speed_text(tokens[:avg_decode_tps], source)}" if tokens[:avg_decode_tps]
+        text
+      end
+
       def format_elapsed_duration(duration_ms)
         duration_ms = duration_ms.to_f
         return "" if duration_ms.negative?

data/lib/samagotchi/token_usage.rb

@@ -1,61 +1,58 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  # TokenUsage extracts real server-reported token counts from a model API
-  # stream payload, transport-agnostically.
+  # TokenUsage is the server-reported token accounting of one model API stream
+  # payload, read transport-agnostically.
   #
   # llama.cpp's /completion stream emits per-chunk `timings.prompt_n` /
   # `timings.predicted_n` (cumulative) and a final top-level
-  # `tokens_evaluated` / `tokens_predicted`. mlx_lm.server (OpenAI-compatible)
-  # emits a `usage` object with `prompt_tokens` / `completion_tokens`.
+  # `tokens_evaluated` / `tokens_predicted`. OpenAI-compatible servers emit a
+  # `usage` object with `prompt_tokens` / `completion_tokens`.
   #
-  # Returns nil when no server token data is present, so a caller can fall back
-  # to a chars/4 heuristic. The reported values are cumulative per request, so
-  # callers should take the running MAX across chunks (see SessionMetrics).
-  class TokenUsage
+  # The last chunk can say more: llama.cpp adds a `timings` block with exact
+  # speeds and `cache_n` (its native `tokens_cached` counts the new tokens too,
+  # so it is not read); OpenRouter adds `usage.cost` (USD) and the
+  # `prompt_tokens_details.cached_tokens` / `completion_tokens_details.reasoning_tokens`
+  # breakdowns. Those fields are nil when a payload doesn't carry them.
+  #
+  # from_payload returns nil when no server token counts are present, so a
+  # caller can fall back to a chars/4 heuristic. The reported values are
+  # cumulative per request, so callers should take the running MAX across
+  # chunks (see SessionMetrics).
+  class TokenUsage < Data.define(:prompt_tokens, :completion_tokens, :cached_tokens, :reasoning_tokens, :cost,
+                                 :predicted_per_second, :prompt_per_second, :predicted_ms, :source)
     CHARS_PER_TOKEN = 4.0
 
     class << self
       # @param payload [Hash, nil] the raw streamed chunk payload
-      # @return [Hash, nil] { prompt_tokens:, completion_tokens:, source: :server }
+      # @return [TokenUsage, nil]
       def from_payload(payload)
         payload_hash = payload.is_a?(Hash) ? payload : {}
-        usage = payload_hash["usage"] || payload_hash[:usage]
-        usage = {} unless usage.is_a?(Hash)
+        usage = hash_at(payload_hash, :usage)
+        timings = hash_at(payload_hash, :timings)
 
         prompt_tokens = first_positive(
-          usage["prompt_tokens"],
-          usage[:prompt_tokens],
-          payload_hash["prompt_tokens"],
-          payload_hash[:prompt_tokens],
-          payload_hash["prompt_n"],
-          payload_hash[:prompt_n],
-          payload_hash["tokens_evaluated"],
-          payload_hash[:tokens_evaluated],
-          payload_hash.dig("timings", "prompt_n"),
-          payload_hash.dig(:timings, :prompt_n)
+          *both(usage, :prompt_tokens), *both(payload_hash, :prompt_tokens), *both(payload_hash, :prompt_n),
+          *both(payload_hash, :tokens_evaluated), *both(timings, :prompt_n)
         )
-
         completion_tokens = first_positive(
-          usage["completion_tokens"],
-          usage[:completion_tokens],
-          payload_hash["completion_tokens"],
-          payload_hash[:completion_tokens],
-          payload_hash["predicted_n"],
-          payload_hash[:predicted_n],
-          payload_hash["tokens_predicted"],
-          payload_hash[:tokens_predicted],
-          payload_hash.dig("timings", "predicted_n"),
-          payload_hash.dig(:timings, :predicted_n)
+          *both(usage, :completion_tokens), *both(payload_hash, :completion_tokens),
+          *both(payload_hash, :predicted_n), *both(payload_hash, :tokens_predicted), *both(timings, :predicted_n)
         )
-
         return nil unless prompt_tokens || completion_tokens
 
-        {
+        new(
           prompt_tokens: prompt_tokens,
           completion_tokens: completion_tokens,
+          cached_tokens: first_positive(*both(hash_at(usage, :prompt_tokens_details), :cached_tokens),
+                                        *both(timings, :cache_n)),
+          reasoning_tokens: first_positive(*both(hash_at(usage, :completion_tokens_details), :reasoning_tokens)),
+          cost: number(*both(usage, :cost)),
+          predicted_per_second: positive_number(*both(timings, :predicted_per_second)),
+          prompt_per_second: positive_number(*both(timings, :prompt_per_second)),
+          predicted_ms: positive_number(*both(timings, :predicted_ms)),
           source: :server
-        }
+        )
       end
 
       # Estimate token count from raw text length using the chars/4 heuristic.
@@ -73,16 +70,35 @@ module Samagotchi
       # float never raises RangeError; non-numeric values are skipped.
       def first_positive(*values)
         values.each do |value|
-          next if value.nil?
-
-          n = Float(value).to_i
-          return n if n.positive?
-        rescue ArgumentError, TypeError
-          next
+          n = float(value)&.to_i
+          return n if n&.positive?
         end
 
         nil
       end
+
+      private
+
+      def hash_at(hash, key)
+        value = hash[key.to_s] || hash[key]
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def both(hash, key) = [hash[key.to_s], hash[key]]
+
+      def positive_number(*values) = values.filter_map { |value| float(value) }.find(&:positive?)
+
+      # A cost of 0 is a real answer (a free model), so zero counts here.
+      def number(*values) = values.filter_map { |value| float(value) }.find { |n| n >= 0 }
+
+      def float(value)
+        return nil if value.nil?
+
+        n = Float(value)
+        n.finite? ? n : nil
+      rescue ArgumentError, TypeError
+        nil
+      end
     end
   end
 end

data/lib/samagotchi/tool_runner.rb

@@ -44,6 +44,7 @@ module Samagotchi
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       # The gate runs first, so tool_call_started shows the call that runs.
+      original = call.dup
       verdict = evaluate(call, iteration, params)
       call = verdict.call
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
@@ -73,6 +74,11 @@ module Samagotchi
       result, images = attach_images(call, result) if result[:images]
 
       output = scrub(result[:output].to_s)
+      # The gate may have replaced the call (known-names corrects a near
+      # miss): one leading line tells the model what actually ran.
+      if (changed = changed_call_line(original, call))
+        output = "#{changed}\n#{output}"
+      end
       capped = output
       truncated = false
       if max_tool_output_chars && output.length > max_tool_output_chars
@@ -84,14 +90,16 @@ module Samagotchi
       # full output: ok, error, blocked, stopped); a dispatcher that raised
       # left none, an error.
       status = result[:activity].is_a?(Hash) ? result[:activity][:status] : nil
-      fire(:after_tool_call, { type: :after_tool_call, iteration: iteration, tool: call[:name], output: capped,
-                               status: status || "error" })
       completed = { type: :tool_call_completed, iteration: iteration, call_count: call_count, call_index: call_index,
                     tool: call[:name], output: capped, output_truncated: truncated, activity: result[:activity] }
       completed[:images] = images if images&.any?
       completed[:diff] = diff if diff
       completed[:waited_ms] = waited_ms if waited_ms
       emit(on_stream_event, completed)
+      # After the completed event: a hook's card (check-in, skills) prints
+      # under the call's tool row, not before it.
+      fire(:after_tool_call, { type: :after_tool_call, iteration: iteration, tool: call[:name], output: capped,
+                               status: status || "error" })
 
       run = { output: output, capped_output: capped, truncated: truncated, activity: result[:activity] }
       run[:images] = images if images&.any?
@@ -203,6 +211,17 @@ module Samagotchi
     # A plugin tool's label, what the UIs show for its raw name.
     def plugin_label(name) = ToolActivity.plugin_label(name, registry: tools)
 
+    # The one leading line the model gets when the gate changed the call it
+    # asked for: "ran as: <tool> <changed args>", or nil when nothing
+    # changed. The args are the changed call's activity params, so the line
+    # stays short.
+    def changed_call_line(original, call)
+      return nil if original == call
+
+      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
+      ["ran as: #{call[:name]}", params].compact.join(" ")
+    end
+
     # The Engine sets the kernel's gate (its context, later the approval
     # flow); a bare kernel (specs) gets one that only runs the hooks.
     def gate

data/lib/samagotchi/tools/execute.rb

@@ -199,22 +199,23 @@ module Samagotchi
         # thread; the text is safe to read afterwards.
         def finish
           @thread.join(STOP_POLL_INTERVAL_SEC) unless done?
-          Execute.send(:close_quietly, @io)
+          close_quietly
           @thread.kill unless @thread.join(STOP_GRACE_SEC)
         end
 
         def text
           @buffer.dup.force_encoding(@io.external_encoding || Encoding.default_external)
         end
-      end
-      private_constant :OutputReader
 
-      def self.close_quietly(io)
-        io.close unless io.closed?
-      rescue IOError
-        nil
+        private
+
+        def close_quietly
+          @io.close unless @io.closed?
+        rescue IOError
+          nil
+        end
       end
-      private_class_method :close_quietly
+      private_constant :OutputReader
 
       def self.terminate_process_tree(pid)
         signal_process(pid, "TERM")