samagotchi 0.75.0 → 0.77.0

data/lib/samagotchi/question_desk.rb

@@ -7,6 +7,7 @@ require "time"
 
 require_relative "client_id"
 require_relative "log"
+require_relative "pending_question"
 require_relative "tools/ask_user_question"
 require_relative "guardrails/parent_approvals"
 require_relative "guardrails/parent_continue"
@@ -87,6 +88,8 @@ module Samagotchi
       # A Monitor: re-entered by the specs from the same thread.
       @lock = Monitor.new
       @cv = @lock.new_cond
+      # The open question (PendingQuestion), nil with none; replaced, never
+      # changed in place (#annotate, #cancel make a new one with #with).
       @pending = nil
       @answer = nil
       # Why the open question was cancelled (#cancel), for the sync path.
@@ -99,9 +102,10 @@ module Samagotchi
       @shelved = nil
     end
 
-    # @return [Hash, nil] current pending question (thread-safe copy)
+    # @return [PendingQuestion, nil] the question pending now (a value: it
+    #   never changes once read)
     def pending
-      @lock.synchronize { @pending&.dup }
+      @lock.synchronize { @pending }
     end
 
     # Ask the model's question (ask_user_question): the kernel's
@@ -127,8 +131,9 @@ module Samagotchi
     # Open a question for the UIs and wait for its answer. Emits
     # :question_requested, persists it to the session, and BLOCKS until
     # answer / cancel wakes it (or the turn is cancelled).
-    # The fields go to pending as given (no cleaning), extra keys
-    # included, so a caller can add its own (kind:, approval:).
+    # The fields become the PendingQuestion as given (no cleaning): any of
+    # its members (kind:, approval:, …); a key it doesn't have raises
+    # ArgumentError.
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
     # @param watch [#call, nil] asked every WATCH_INTERVAL seconds while the
     #   question waits (outside the lock): a String closes the question with
@@ -155,7 +160,7 @@ module Samagotchi
     # @param on_superseded_close [#call, nil] called when a question that
     #   superseded it closes (its poster posts it again if it still
     #   stands); nil: posted again as it was
-    # @return [Hash, nil] the pending question; nil when it waits for another
+    # @return [PendingQuestion, nil] the pending question; nil when it waits for another
     def post(fields, on_answer:, on_superseded_close: nil)
       standing = { fields: fields, on_answer: on_answer, on_superseded_close: on_superseded_close }
       shelved = @lock.synchronize do
@@ -179,7 +184,7 @@ module Samagotchi
       withdrawn = @lock.synchronize do
         @shelved = nil if id.nil?
         standing = @standing
-        next nil unless standing && @pending && @pending[:id] == standing[:id]
+        next nil unless standing && @pending && @pending.id == standing[:id]
         next nil if id && standing[:id].to_s != id.to_s
 
         @standing = nil
@@ -195,7 +200,7 @@ module Samagotchi
 
     private def ask(fields, watch)
       pending = publish(fields)
-      id = pending[:id]
+      id = pending.id
 
       # If a synchronous UI handler is registered (TUI), invoke it inline on the
       # SAME thread that called request_question (TerminalUI's REPL thread is the
@@ -204,7 +209,7 @@ module Samagotchi
       # any future UI that registers a sync handler gets the same guarantee.
       if @sync_handler
         begin
-          sync_res = @sync_handler.call(pending.dup)
+          sync_res = @sync_handler.call(pending.to_h)
           # Handler may have called answer_question or returned a hash/string.
           # Decided under the lock; saved and announced after it (never emit
           # holding the question lock: a snapshot holds the event lock and
@@ -298,12 +303,12 @@ module Samagotchi
       answer = @lock.synchronize do
         pending = @pending
         raise NotPending, "no pending question" unless pending
-        raise NotPending, "id mismatch" unless pending[:id].to_s == id.to_s
+        raise NotPending, "id mismatch" unless pending.id.to_s == id.to_s
         # First responder wins: after the first answer the turn thread clears
         # @pending in a later lock block, so a second UI's answer can
         # land in between and must not overwrite the first.
         raise NotPending, "question already answered" if @answer
-        raise NotPending, "question #{pending[:status]}" unless pending[:status].to_s == "pending"
+        raise NotPending, "question #{pending.status}" unless pending.status.to_s == "pending"
 
         answer = validated_answer(pending, sel, fm, parent_agent: parent_agent, parent_setting: parent_setting)
         if parent_agent && (reason = Guardrails::ParentContinue.refusal(pending, sel, allowed: parent_continue))
@@ -338,15 +343,15 @@ module Samagotchi
     def annotate(id, relayed_to:, reason: nil)
       marked = @lock.synchronize do
         pending = @pending
-        next nil unless pending && pending[:id].to_s == id.to_s
-        next nil if @answer || pending[:status].to_s != "pending"
+        next nil unless pending && pending.id.to_s == id.to_s
+        next nil if @answer || pending.status.to_s != "pending"
 
-        relayed_to ? pending[:relayed_to] = relayed_to : pending.delete(:relayed_to)
+        @pending = pending = pending.with(relayed_to: relayed_to)
         if session
-          session.pending_question = pending.dup
+          session.pending_question = pending
           begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
         end
-        pending[:id]
+        pending.id
       end
       return false unless marked
 
@@ -372,16 +377,16 @@ module Samagotchi
       cancelled_id = @lock.synchronize do
         pending = @pending
         next unless pending
-        next if id && pending[:id].to_s != id.to_s
-        next if @answer || pending[:status].to_s != "pending"
+        next if id && pending.id.to_s != id.to_s
+        next if @answer || pending.status.to_s != "pending"
         # Its poster closes it; nothing waits on a cancel.
-        raise NotDismissable, "answer #{Array(pending[:options]).join(" or ")}" if @standing && id
+        raise NotDismissable, "answer #{Array(pending.options).join(" or ")}" if @standing && id
         next if @standing
 
-        pending[:status] = "cancelled"
+        @pending = pending.with(status: "cancelled")
         @cancel_reason = reason.to_s
         @cv.broadcast
-        pending[:id]
+        pending.id
       end
       return id.nil? && self.pending.nil? unless cancelled_id
 
@@ -420,21 +425,23 @@ module Samagotchi
     # :question_requested to every UI. Observers that stash the event (e.g.
     # TerminalUI handle_question_event) discard it as stale if a sync
     # handler answers and clears it first (drain_pending_question?).
-    # @return [Hash] the pending question
+    # The event carries it as a Hash (PendingQuestion#to_h), as every UI
+    # and the Bridge's stream read it.
+    # @return [PendingQuestion] the pending question
     # @param standing [Hash, nil] a standing question's record (#post)
     def publish(fields, standing: nil)
-      pending = { id: SecureRandom.uuid, **fields, status: "pending", created_at: Time.now.iso8601(3) }.compact
+      pending = PendingQuestion.new(id: SecureRandom.uuid, **fields, status: "pending", created_at: Time.now.iso8601(3))
       @lock.synchronize do
         @pending = pending
         @answer = nil
         @cancel_reason = nil
-        @standing = standing&.merge(id: pending[:id])
+        @standing = standing&.merge(id: pending.id)
       end
       if session
-        session.pending_question = pending.dup
+        session.pending_question = pending
         begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
       end
-      event = { type: :question_requested, pending_question: pending }
+      event = { type: :question_requested, pending_question: pending.to_h }
       event[:standing] = true if standing
       emit(event)
       pending
@@ -489,11 +496,11 @@ module Samagotchi
     # @return [Hash] {id:, selected:, freeform:, selected_indices:, by:}
     # @raise [ArgumentError, Refused]
     def validated_answer(pending, sel, fm, parent_agent:, parent_setting:)
-      opts = Array(pending[:options])
+      opts = Array(pending.options)
       invalid = sel.reject { |v| opts.include?(v) }
       raise ArgumentError, "invalid selection: #{invalid.join(", ")} (valid: #{opts.join(", ")})" unless invalid.empty?
-      raise ArgumentError, "single-select question: got #{sel.size} selections" if !pending[:multi_select] && sel.size > 1
-      raise ArgumentError, "selection required" if pending[:multi_select] == false && sel.empty? && fm.nil?
+      raise ArgumentError, "single-select question: got #{sel.size} selections" if !pending.multi_select && sel.size > 1
+      raise ArgumentError, "selection required" if pending.multi_select == false && sel.empty? && fm.nil?
 
       indices = sel.map { |v| opts.index(v) }
       # The one whose answer settles the approval (Approval.settle, by index).
@@ -501,7 +508,7 @@ module Samagotchi
         reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: parent_setting)
         raise Refused, reason if reason
       end
-      answer = { id: pending[:id].to_s, selected: sel, freeform: fm, selected_indices: indices.compact }
+      answer = { id: pending.id.to_s, selected: sel, freeform: fm, selected_indices: indices.compact }
       answer[:by] = "parent_agent" if parent_agent
       answer
     end
@@ -513,7 +520,7 @@ module Samagotchi
       loop do
         done = @lock.synchronize do
           next true if @answer || cancel_controller&.cancelled?
-          next true if @pending.nil? || @pending[:status] != "pending"
+          next true if @pending.nil? || @pending.status != "pending"
 
           # Wait with timeout to check cancel; 0.2s matches reminder poll
           @cv.wait([0.2, watch ? next_watch - monotonic : 0.2].min.clamp(0.0, 0.2))
@@ -527,9 +534,9 @@ module Samagotchi
         next unless reason
 
         closed = @lock.synchronize do
-          next false if @answer || @pending.nil? || @pending[:status] != "pending"
+          next false if @answer || @pending.nil? || @pending.status != "pending"
 
-          @pending[:status] = "cancelled"
+          @pending = @pending.with(status: "cancelled")
           true
         end
         return reason if closed

data/lib/samagotchi/relay.rb

@@ -18,29 +18,28 @@ module Samagotchi
     module_function
 
     # @param child [Session] the child as loaded (its id, its first prompt)
-    # @param pending [Hash] the child's pending question (string keys inside
-    #   when it came from a saved session)
+    # @param pending [PendingQuestion] the child's pending question (string
+    #   keys inside its approval and relay when it came from a saved session)
     # @param relay_id [String] RelayDesk's id
     # @param more [Integer] other delegates' approvals waiting behind this one
     # @return [Hash] Engine#open_question fields
     def card(child, pending, relay_id:, more: 0)
-      pending = deep_symbolize(pending)
-      facts = pending[:approval].is_a?(Hash) ? pending[:approval] : {}
+      facts = pending.approval.is_a?(Hash) ? deep_symbolize(pending.approval) : {}
       short = child.id.to_s[0, 8]
-      inner = pending[:relay].is_a?(Hash) ? pending[:relay] : nil
+      inner = pending.relay.is_a?(Hash) ? deep_symbolize(pending.relay) : nil
       chain = inner ? [*Array(inner[:chain]), short] : [short]
-      asked = inner ? inner[:asked].to_s : pending[:question].to_s
+      asked = inner ? inner[:asked].to_s : pending.question.to_s
       task = inner ? inner[:task].to_s : task_of(child)
       who = chain.reverse.join(" → ")
       {
         question: question_text(who, task, asked),
-        options: relabel(Array(pending[:options]), facts[:scopes], who),
+        options: relabel(Array(pending.options), facts[:scopes], who),
         header: header(who, more),
         multi_select: false,
-        allow_freeform: pending.key?(:allow_freeform) ? !!pending[:allow_freeform] : true,
+        allow_freeform: pending.allow_freeform.nil? || !!pending.allow_freeform,
         kind: Guardrails::Approval::KIND,
         approval: facts,
-        relay: { id: relay_id, child_id: child.id, child_short: short, child_question_id: pending[:id].to_s,
+        relay: { id: relay_id, child_id: child.id, child_short: short, child_question_id: pending.id.to_s,
                  task: task, chain: chain, asked: asked, more: more.to_i }
       }
     end

data/lib/samagotchi/relay_verifier.rb

@@ -70,9 +70,9 @@ module Samagotchi
     # of range; [] for a freeform-only deny.
     def labels(indices, question_id)
       pending = @engine.pending_question
-      return [] unless pending && pending[:id].to_s == question_id
+      return [] unless pending && pending.id.to_s == question_id
 
-      options = Array(pending[:options])
+      options = Array(pending.options)
       indices = Array(indices)
       return nil unless indices.all? { |index| index.is_a?(Integer) && index >= 0 && index < options.size }
 

data/lib/samagotchi/relay_watcher.rb

@@ -37,8 +37,8 @@ module Samagotchi
     end
 
     def relayed?(pending, question_id, relay_id)
-      relay = pending && pending[:relayed_to]
-      return false unless relay.is_a?(Hash) && pending[:id].to_s == question_id.to_s
+      relay = pending&.relayed_to
+      return false unless relay.is_a?(Hash) && pending.id.to_s == question_id.to_s
 
       (relay[:relay_id] || relay["relay_id"]).to_s == relay_id.to_s
     end

data/lib/samagotchi/reply_wait.rb

@@ -30,7 +30,7 @@ module Samagotchi
     # @!attribute text [String, nil] the reply (:done) or the worker's error
     #   (:error)
     # @!attribute file [String, nil] the reply's filename, the next cursor
-    # @!attribute question [Hash, nil] the pending question
+    # @!attribute question [PendingQuestion, nil] the pending question
     #   (:waiting_for_answer)
     # @!attribute outcome [String, nil] how the turn ended when it left no
     #   reply (:no_reply): "failed", "canceled", "completed" (empty),
@@ -152,7 +152,7 @@ module Samagotchi
         # lists' rule): one a dead worker left waits for no one, and a chi
         # REPL's is answered there.
         pending = session.pending_question
-        if pending && !(baseline && pending[:id] == baseline[:question_id]) &&
+        if pending && !(baseline && pending.id == baseline[:question_id]) &&
            (turn.nil? || own_question?(session, turn, claimed)) &&
            session.waiting_question(live: SessionManager.worker_live?(id, state_dir: state_dir))
           return Result.new(status: :waiting_for_answer, question: pending, session: session)
@@ -217,7 +217,7 @@ module Samagotchi
     # its messages, the question pending then, and when its last turn
     # ended, so a turn that ends before the first look still ends the wait.
     # @return [Hash]
-    def baseline_of(session, question_id: session.pending_question&.dig(:id))
+    def baseline_of(session, question_id: session.pending_question&.id)
       { messages: session.messages.size, question_id: question_id, last_turn: session.last_turn&.ended_at }
     end
 
@@ -252,7 +252,7 @@ module Samagotchi
       end
 
       pending = session.pending_question
-      return nil unless pending && pending[:kind].to_s == "continue"
+      return nil unless pending && pending.kind.to_s == "continue"
       return nil unless turn_ids?(session_dir)
 
       session.last_turn&.enqueued_id

data/lib/samagotchi/row_refs.rb

@@ -10,7 +10,7 @@ module Samagotchi
   # whose +to_h+ the row carries as +refs+ on tool_call_started and
   # tool_call_completed (ToolRowFields::EVENT_KEYS), saved with the result
   # as tool_refs (ToolResponse::SAVED_KEYS) for a reload, which has no
-  # plugins (Web::MessageParts). Display only: the model never sees them.
+  # plugins (MessageParts). Display only: the model never sees them.
   #
   # A file ref is any file under the session's folder (plan D7): a relative
   # path is resolved against it, a path outside it is dropped. The folder

data/lib/samagotchi/session.rb

@@ -8,6 +8,7 @@ require_relative "atomic_file"
 require_relative "context_note"
 require_relative "interrupted_turn"
 require_relative "last_turn"
+require_relative "pending_question"
 require_relative "llm_context_override"
 require_relative "session_setup"
 require_relative "prompt_note"
@@ -49,7 +50,7 @@ module Samagotchi
 
     attr_accessor :id, :metadata_version, :mode, :model_name, :working_directory, :messages,
                   :created_at, :updated_at, :status, :last_prompt, :first_preview, :test_run,
-                  :pending_question, :used_memory_names
+                  :used_memory_names
     # Memories the session was started with (--memory) and memories hidden
     # from it (--mute): the worker rebuilds the same prompt on a respawn.
     # Names as given; the engine normalizes them.
@@ -98,6 +99,15 @@ module Samagotchi
     # A `chi scratch` session: deleted when its REPL ends, and by the next
     # sweep (or `chi sessions clean`) when the process died first.
     attr_accessor :scratch
+    # The question this session waits on (PendingQuestion), saved as
+    # session.json's "pending_question"; nil with none. A Hash (a saved
+    # record, string or symbol keys) is read with PendingQuestion.from_file.
+    attr_reader :pending_question
+
+    def pending_question=(value)
+      @pending_question = PendingQuestion.from_file(value)
+    end
+
     # How the last turn ended (LastTurn), for a parent's wait (ReplyWait)
     # and the web's notifications (the hub sends it in the summary); nil
     # before the first turn.
@@ -246,7 +256,7 @@ module Samagotchi
       @last_prompt = last_prompt
       @first_preview = first_preview
       @test_run = !!test_run
-      @pending_question = pending_question
+      self.pending_question = pending_question
       @used_memory_names = self.class.name_list(used_memory_names)
       @preloaded_memory_names = self.class.name_list(preloaded_memory_names)
       @muted_memory_names = self.class.name_list(muted_memory_names)
@@ -289,12 +299,12 @@ module Samagotchi
     # @return [Hash, nil]
     def waiting_question(live:)
       pending = pending_question
-      return nil unless live && pending.is_a?(Hash) && pending[:id]
+      return nil unless live && pending&.id
 
-      kind = pending[:kind].to_s
-      relayed = pending[:relayed_to]
+      kind = pending.kind.to_s
+      relayed = pending.relayed_to
       relayed_to = relayed.is_a?(Hash) ? (relayed[:parent_short] || relayed["parent_short"]) : nil
-      { id: pending[:id], kind: %w[approval hook continue].include?(kind) ? kind : "question", relayed_to: relayed_to }.compact
+      { id: pending.id, kind: %w[approval hook continue].include?(kind) ? kind : "question", relayed_to: relayed_to }.compact
     end
 
     # A question saved by a process that no longer runs this session (the
@@ -306,7 +316,7 @@ module Samagotchi
       return nil unless pending
 
       @pending_question = nil
-      pending[:id].to_s
+      pending.id.to_s
     end
 
     # The stored project root, else (a file from before the field) the
@@ -390,10 +400,10 @@ module Samagotchi
 
     # The fields of <id>.json, in the order #save writes them: key => the
     # value for a file without it (REQUIRED for the ones it must have).
-    # .from_h and #to_h both go by this table; messages and
-    # pending_question change key type on the way (symbols in memory,
-    # strings on disk); last_turn and prompt_notes are value objects in
-    # memory (LastTurn, PromptNote).
+    # .from_h and #to_h both go by this table; messages change key type on
+    # the way (symbols in memory, strings on disk); last_turn, prompt_notes
+    # and pending_question are value objects in memory (LastTurn,
+    # PromptNote, PendingQuestion).
     FIELDS = {
       "metadata_version" => 1,
       "id" => REQUIRED,
@@ -435,8 +445,6 @@ module Samagotchi
         [key.to_sym, default.equal?(REQUIRED) ? data.fetch(key) : data.fetch(key, default)]
       end
       attrs[:messages] = messages ? Array(attrs[:messages]).map { |msg| symbolize_message_keys(msg) } : []
-      pending = attrs[:pending_question]
-      attrs[:pending_question] = pending.is_a?(Hash) ? symbolize_message_keys(pending) : nil
       new(**attrs)
     end
 
@@ -557,7 +565,7 @@ module Samagotchi
                 when "messages"
                   (checkpoint ? checkpoint[:messages] : @messages).map { |msg| scrub_utf8(stringify_message_keys(msg)) }
                 when "interrupted_turn" then (checkpoint ? checkpoint[:marker] : @interrupted_turn)&.to_file
-                when "pending_question" then @pending_question && scrub_utf8(stringify_message_keys(@pending_question))
+                when "pending_question" then @pending_question && scrub_utf8(@pending_question.to_file)
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
                 when "llm_context" then llm_context_file

data/lib/samagotchi/session_commands.rb

@@ -592,6 +592,11 @@ module Samagotchi
       @engine.switch_model!(name, persist_default: persist_default)
       @default_model = @engine.default_model_name if persist_default
       persist_session_model
+      # The ctx % on the new model's window, before its first turn; saved
+      # too, so the session's card (the hub's summary reads analytics.json)
+      # stops showing the old model's % before a turn ends.
+      @engine.announce_switched_context!
+      @engine.metrics.persist(state_dir: @engine.session_state_dir)
     end
 
     def persist_session_model

data/lib/samagotchi/session_manager.rb

@@ -244,8 +244,7 @@ module Samagotchi
       end
       # And the spawner's XDG dirs, absolute: a relative XDG_STATE_HOME or
       # XDG_CONFIG_HOME would otherwise be read from the session's directory.
-      child_env["XDG_STATE_HOME"] = Paths.state_home unless ENV.fetch("XDG_STATE_HOME", "").to_s.strip.empty?
-      child_env["XDG_CONFIG_HOME"] = Paths.config_home unless ENV.fetch("XDG_CONFIG_HOME", "").to_s.strip.empty?
+      child_env.merge!(Paths.absolute_xdg)
       # The spawner's environment must not reach the worker's guardrails (a
       # parent agent starting or waking a session): Process.spawn unsets a
       # key mapped to nil. config.yml no longer reads them; this keeps an

data/lib/samagotchi/session_metrics/model_segment.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "totals"
+
+module Samagotchi
+  class SessionMetrics
+    # A run of consecutive turns on one model (their records' model_ref, the
+    # asked host:model): /stats and the web's ctx/cost tooltip split the
+    # session's tokens, cost and speed by these, in order, so A -> B -> A is
+    # three. Derived from the turn records as they are counted, never saved
+    # on their own. A record with no ref (a turn stopped before it asked a
+    # model) joins the segment before it; records with none before the first
+    # one that names a model (a session older than model_ref) make one
+    # leading segment with no ref.
+    #
+    # +prefill_tokens+ / +prefill_cost_estimate+: what the segment's first
+    # turn prefilled on its model after the switch (the records'
+    # switch_prefill_*), 0 / nil for none.
+    class ModelSegment < Data.define(:model_ref, :started_at, :ended_at, :turns, :totals, :prefill_tokens,
+                                     :prefill_cost_estimate)
+      # The most rows a snapshot sends: older ones fold into one.
+      CAP = 6
+
+      # A segment opened by +record+ (its first turn).
+      # @param record [Hash] a turn record (symbol keys)
+      # @return [ModelSegment]
+      def self.open(record)
+        ref = record[:model_ref].to_s
+        new(model_ref: ref.empty? ? nil : ref, started_at: record[:started_at], ended_at: nil, turns: 0,
+            totals: Totals.zero, prefill_tokens: 0, prefill_cost_estimate: nil).add(record)
+      end
+
+      # The segment a snapshot shows for the running turn when it is on
+      # another model than the last segment's: no finished turn yet.
+      # @param ref [String]
+      # @param started_at [String, nil]
+      # @return [ModelSegment]
+      def self.empty(ref, started_at)
+        new(model_ref: ref, started_at: started_at, ended_at: nil, turns: 0, totals: Totals.zero, prefill_tokens: 0,
+            prefill_cost_estimate: nil)
+      end
+
+      # Whether +record+ starts a new segment after this one: it names a
+      # model, and another one than this segment's.
+      def self.splits?(segment, record)
+        ref = record[:model_ref].to_s
+        segment.nil? || (!ref.empty? && segment.model_ref != ref)
+      end
+
+      # This segment with one more finished turn record.
+      # @return [ModelSegment]
+      def add(record)
+        tokens = record[:switch_prefill_tokens]
+        estimate = record[:switch_prefill_cost_estimate]
+        with(ended_at: record[:completed_at] || ended_at, turns: turns + 1, totals: totals.add(record),
+             prefill_tokens: prefill_tokens + (tokens.is_a?(Numeric) ? tokens : 0),
+             prefill_cost_estimate: estimate.is_a?(Numeric) ? prefill_cost_estimate.to_f + estimate : prefill_cost_estimate)
+      end
+
+      # This segment with the running turn (SessionMetrics::TurnState) in:
+      # its finished generations and the prefill it recorded so far; it
+      # runs on, so it has no end.
+      # @return [ModelSegment]
+      def with_running(turn)
+        estimate = turn.switch_prefill_cost_estimate
+        with(ended_at: nil, turns: turns + 1, totals: totals.with_running(turn),
+             prefill_tokens: prefill_tokens + turn.switch_prefill_tokens.to_i,
+             prefill_cost_estimate: estimate ? prefill_cost_estimate.to_f + estimate : prefill_cost_estimate)
+      end
+
+      # The row a snapshot carries (JSON-ready). +ended_at+ nil: the segment
+      # runs now.
+      # @return [Hash]
+      def to_h
+        tokens = totals.tokens_block
+        {
+          model_ref: model_ref, started_at: started_at, ended_at: ended_at, turns: turns,
+          **tokens.slice(:prompt_sum, :completion_sum, :cached_sum, :cost_sum, :cost_estimate_sum, :avg_decode_tps,
+                         :last_decode_tps, :tps_source),
+          prefill_tokens: prefill_tokens, prefill_cost_estimate: prefill_cost_estimate
+        }
+      end
+
+      # The rows of +segments+ a snapshot sends: none for fewer than 2 (one
+      # model: the plain totals say it all); over CAP, the oldest fold into
+      # one row with no ref that says how many it holds (folded_segments).
+      # @param segments [Array<ModelSegment>]
+      # @return [Array<Hash>]
+      def self.rows(segments)
+        return [] if segments.size < 2
+        return segments.map(&:to_h) if segments.size <= CAP
+
+        older = segments.first(segments.size - CAP + 1)
+        folded = older.drop(1).reduce(older.first.with(model_ref: nil)) do |sum, segment|
+          sum.merge(segment)
+        end
+        [folded.to_h.merge(folded_segments: older.size), *segments.last(CAP - 1).map(&:to_h)]
+      end
+
+      # This segment and a later one as one row (the folded older ones).
+      # @return [ModelSegment]
+      def merge(later)
+        estimate = [prefill_cost_estimate, later.prefill_cost_estimate].compact
+        with(ended_at: later.ended_at, turns: turns + later.turns, totals: totals.merge(later.totals),
+             prefill_tokens: prefill_tokens + later.prefill_tokens, prefill_cost_estimate: estimate.empty? ? nil : estimate.sum)
+      end
+    end
+  end
+end