samagotchi 0.38.0 → 0.40.0

data/lib/samagotchi/llm_context_strategy.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Which LLM context strategy a turn runs under (LLMContextView): none,
+  # the default, or a list of layers (stale, forget). Set by
+  # llm_context.strategy, and per model or host by the flat key
+  # llm_context_strategy (models.<key>, hosts.<name>), each a layer name,
+  # "|"-separated names or a YAML list.
+  #
+  # Resolution, first set wins: the session's own (a later per-session
+  # override; nothing sets it yet), models.<key> (by the model's lookup
+  # names, as window_tokens), hosts.<name>, then llm_context.strategy.
+  # An unknown layer warns and is none (every layer is built: stale, and
+  # forget, experimental, with its tool forget_outputs).
+  #
+  # When a layer's edits reach the prompt (LLMContextApply) is set by
+  # llm_context.apply, and per model or host by the flat key
+  # llm_context_apply: payoff (the default), next_request or turn_end,
+  # resolved as the strategy is (the session's own, the model's, the
+  # host's, then llm_context.apply), each layer on its own: a model may
+  # set the strategy and its host the apply rule. An unknown value warns
+  # and is payoff. llm_context.protect_steps (3) and llm_context.stale_edits
+  # (false: edit-driven stale stubs are opt-in, experimental) are global only.
+  #
+  # A soft context budget, llm_context.budget_tokens, and per model or host
+  # the flat key llm_context_budget_tokens (a positive number of tokens),
+  # resolved as the apply rule is, each on its own: off (nil) by default.
+  # When set, ContextStatus counts its bands against it instead of the
+  # window (the smaller of the two), so the forget layer's offers come
+  # under it.
+  module LLMContextStrategy
+    SETTING = "llm_context.strategy"
+    KEY = "llm_context_strategy"
+    NONE = :none
+    LAYERS = %i[stale forget].freeze
+    # The layers a turn can run under so far.
+    BUILT = %i[stale forget].freeze
+    # The sentence forget_outputs' description carries (global only):
+    # the plan's D7 line, adapted from CLM's steering example.
+    POLICY_SETTING = "llm_context.policy"
+    DEFAULT_POLICY = "Tidy at subtask boundaries: once a subtask is done, forget its tool outputs and note what it " \
+                     "established; keep anything you'll still edit against."
+
+    APPLY_SETTING = "llm_context.apply"
+    APPLY_KEY = "llm_context_apply"
+    APPLIES = %i[payoff next_request turn_end].freeze
+    DEFAULT_APPLY = :payoff
+    PROTECT_SETTING = "llm_context.protect_steps"
+    DEFAULT_PROTECT_STEPS = 3
+    STALE_EDITS_SETTING = "llm_context.stale_edits"
+    BUDGET_SETTING = "llm_context.budget_tokens"
+    BUDGET_KEY = "llm_context_budget_tokens"
+
+    # A turn's strategy: the layers as configured, the strategy the view
+    # gets (NONE, or the layers), and where it was set (:session,
+    # :model_setting, :host_setting, :config); the apply rule
+    # (LLMContextApply), the steps whose edited files' reads are kept
+    # (protect_steps), whether an edit or write makes a read stale
+    # (stale_edits; off: later reads only), and the context budget in
+    # tokens (budget_tokens; nil: off).
+    Resolved = Data.define(:layers, :strategy, :source, :apply, :protect_steps, :stale_edits, :budget_tokens) do
+      def initialize(apply: DEFAULT_APPLY, protect_steps: DEFAULT_PROTECT_STEPS, stale_edits: false, budget_tokens: nil,
+                     **fields) = super
+
+      def forget? = active_layers.include?(:forget)
+
+      # The layers the turn runs under: none of them under none (an
+      # unbuilt or unknown layer's strategy too).
+      def active_layers = strategy == NONE ? [] : Array(strategy)
+    end
+
+    module_function
+
+    # +raw+ as written (a String, "|"-separated, or a YAML list) as layers;
+    # [] for none, nil for unset. An unknown name warns, naming +where+,
+    # and is none.
+    # @return [Array<Symbol>, nil]
+    def parse(raw, where)
+      return nil if raw.nil?
+
+      names = (raw.is_a?(Array) ? raw : raw.to_s.split("|")).map { |name| name.to_s.strip.downcase }.reject(&:empty?)
+      return [] if names.empty? || names == [NONE.to_s]
+
+      unknown = names - LAYERS.map(&:to_s)
+      unless unknown.empty?
+        warn_once "Warning: #{where}: unknown llm_context strategy #{unknown.join(", ")} (none, or a list of " \
+                  "#{LAYERS.join(", ")}); using none"
+        return []
+      end
+      names.uniq.map(&:to_sym)
+    end
+
+    # +raw+ as written, an apply rule; nil for unset. An unknown one warns,
+    # naming +where+, and is payoff.
+    # @return [Symbol, nil]
+    def parse_apply(raw, where)
+      return nil if raw.nil? || raw.to_s.strip.empty?
+
+      rule = raw.to_s.strip.downcase.to_sym
+      return rule if APPLIES.include?(rule)
+
+      warn_once "Warning: #{where}: unknown llm_context apply #{raw} (#{APPLIES.join(", ")}); using #{DEFAULT_APPLY}"
+      DEFAULT_APPLY
+    end
+
+    # +raw+ as written, a context budget in tokens; nil for unset or 0
+    # (off). Anything but a number of tokens warns, naming +where+, and is
+    # unset.
+    # @return [Integer, nil]
+    def parse_budget(raw, where)
+      return nil if raw.nil? || raw.to_s.strip.empty?
+
+      tokens = Integer(raw.to_s.strip, exception: false)
+      return nil if tokens&.zero?
+      return tokens if tokens&.positive?
+
+      warn_once "Warning: #{where}: llm_context budget_tokens must be a positive number of tokens; ignored"
+      nil
+    end
+
+    # The strategy for +target+'s turn.
+    # @param target [HostRegistry::ModelTarget, nil]
+    # @param names [Array<String>] HostRegistry#lookup_names
+    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @param session [Array<Symbol>, nil] the session's own layers (none yet)
+    # @param session_apply [Symbol, nil] the session's own apply rule (none yet)
+    # @param session_budget [Integer, nil] the session's own budget (none yet)
+    # @return [Resolved]
+    def resolve(target, names:, models: nil, session: nil, session_apply: nil, session_budget: nil)
+      models ||= ConfigFile.model_settings
+      layers, source, where = layers_for(target, names, models, session)
+      resolved(layers, source, where).with(apply: apply_for(target, names, models, session_apply),
+                                           protect_steps: protect_steps, stale_edits: Config.get(STALE_EDITS_SETTING) == true,
+                                           budget_tokens: budget_for(target, names, models, session_budget))
+    end
+
+    def budget_for(target, names, models, session_budget)
+      session_budget || ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models)&.last ||
+        target&.entry&.llm_context_budget_tokens || parse_budget(Config.get(BUDGET_SETTING), BUDGET_SETTING)
+    end
+
+    def layers_for(target, names, models, session)
+      return [session, :session, "the session"] if session
+
+      key, layers = ConfigFile.model_setting(names, :llm_context_strategy, models: models)
+      return [layers, :model_setting, "models: #{key}"] if layers
+
+      layers = target&.entry&.llm_context_strategy
+      return [layers, :host_setting, "hosts entry '#{target.entry.name}'"] if layers
+
+      [parse(Config.get(SETTING), SETTING) || [], :config, SETTING]
+    end
+
+    def apply_for(target, names, models, session_apply)
+      session_apply || ConfigFile.model_setting(names, :llm_context_apply, models: models)&.last ||
+        target&.entry&.llm_context_apply || parse_apply(Config.get(APPLY_SETTING), APPLY_SETTING) || DEFAULT_APPLY
+    end
+
+    # llm_context.protect_steps: 0 or more (a negative one is the default).
+    def protect_steps
+      steps = Config.get(PROTECT_SETTING)
+      steps.is_a?(Integer) && !steps.negative? ? steps : DEFAULT_PROTECT_STEPS
+    end
+
+    def resolved(layers, source, where)
+      unbuilt = layers - BUILT
+      unless unbuilt.empty?
+        warn_once "Warning: #{where}: llm_context strategy #{unbuilt.join(", ")} is not built yet; using none"
+      end
+      Resolved.new(layers: layers, strategy: layers.empty? || !unbuilt.empty? ? NONE : layers, source: source)
+    end
+
+    def warn_once(message) = ConfigFile.warn_once(message)
+
+    private_class_method :resolved, :warn_once, :layers_for, :apply_for, :budget_for
+  end
+end

data/lib/samagotchi/llm_context_view.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "tool_response"
+require_relative "tool_ids"
+require_relative "llm_context_edit"
+require_relative "llm_context_stale"
+
+module Samagotchi
+  # What the model is sent of the stored conversation: the one step
+  # between a session's messages and the three places that format them
+  # for a request (KernelLoop#format_prompt and #warmup_prompt, the native
+  # prompt; ChatLoop#wire_messages, the chat messages). A strategy may
+  # change what is sent; the session keeps the originals.
+  #
+  # Under +none+ (the default) nothing changes: #messages returns the
+  # conversation it was given, the same Array of the same entries, so the
+  # prompt is byte for byte what it was before the view existed.
+  #
+  # Under a strategy of layers (:stale, :forget), each applied edit saved
+  # on a tool_response entry (LLMContextEdit) whose kind is one of the
+  # layers sends that run's output as its stub. The entry stays where it
+  # is, with its role and tool_call_id, so a call keeps its response and
+  # the image plan (which indexes by entry) lines up. A stub keeps the
+  # output's "[name]" lead (Gemma's prompt writes response:NAME from it),
+  # and the run's images go with its text (images and image_counts kept
+  # consistent). An entry the view can't split for sure (its runs don't
+  # match its ids, or its images can't be told apart by run) is sent whole.
+  # The view only counts the runs: whatever saves an edit on a run checks
+  # the entry's runs against its batch's call names first
+  # (ToolResponse.runs_named), and the entry's content never changes.
+  #
+  # With the forget layer on, every output with a stored id is sent with
+  # it after its lead, "[read]\n[#t41] …" (plan D2: only then), so the
+  # model can name it to forget_outputs; a legacy entry's derived ids are
+  # never shown (they can't be forgotten), nor is the id of a run that
+  # doesn't pair with its call for sure (LLMContextStale.paired_runs: a
+  # "ran as:" line, an output holding a run separator), which
+  # forget_outputs can't name either. A forget's stub carries its
+  # note once: the outputs one forget_outputs call forgot that follow one
+  # another (no other output between them) point to the first one's
+  # instead, and a forget's kept lines (LLMContextEdit#keep) follow its
+  # stub. A forgotten output that isn't a read says how to restore it
+  # (re-reading the file is a read's restore).
+  class LLMContextView
+    NONE = :none
+    LAYERS = LLMContextEdit::KINDS
+
+    # @return [Array<Symbol>] the layers; empty under none
+    attr_reader :layers
+
+    # What +entries+ send, in chars: their contents (a parts list's text
+    # parts) and their calls' names and arguments. The chat loop's context
+    # estimate and the apply rule's payoff count so.
+    def self.chars(entries)
+      entries.sum do |entry|
+        content = entry[:content]
+        chars = if content.is_a?(Array)
+                  content.sum { |part| part.is_a?(Hash) ? (part[:text] || part["text"]).to_s.length : 0 }
+                else
+                  content.to_s.length
+                end
+        chars + Array(entry[:tool_calls]).sum do |call|
+          call.is_a?(Hash) ? call[:name].to_s.length + call[:arguments].to_json.length : 0
+        end
+      end
+    end
+
+    # @param strategy [Symbol, Array<Symbol>] :none, or the layers
+    def initialize(strategy: NONE)
+      @layers = strategy == NONE ? [] : Array(strategy).map(&:to_sym) & LAYERS
+    end
+
+    def none? = layers.empty?
+
+    def strategy = none? ? NONE : layers
+
+    # @param conversation [Array<Hash>] the stored entries, in order
+    # @return [Array<Hash>] the entries to format
+    def messages(conversation)
+      return conversation if none?
+
+      group = Group.new
+      group.paired = forget? ? LLMContextStale.paired_runs(conversation).to_set { |run| run.ref.id } : Set.new
+      conversation.each_with_index.map { |entry, index| edited(conversation, entry, index, group) }
+    end
+
+    def forget? = layers.include?(:forget)
+
+    # The forget whose stub carries the note the next forgotten output of
+    # the same call points to: its first id and its note, author and stamp.
+    # +paired+: the ids of the runs that pair with their calls.
+    Group = Struct.new(:first, :key, :paired)
+    private_constant :Group
+
+    READ = "read"
+
+    private
+
+    def edited(conversation, entry, index, group)
+      return entry unless entry[:role].to_s == "tool_response"
+
+      edits = LLMContextEdit.on(entry).select { |_id, edit| edit.applied? && layers.include?(edit.kind) }
+      return entry if edits.empty? && !forget?
+
+      refs = ToolIds.refs_at(conversation, index)
+      stubbed = refs.each_index.select { |run| edits.key?(refs[run].id) }
+      shown = forget? ? refs.each_index.select { |run| group.paired.include?(refs[run].id) && !refs[run].derived? } : []
+      return whole(entry, group) if stubbed.empty? && shown.empty?
+
+      texts = ToolResponse.runs(entry[:content], refs.size)
+      return whole(entry, group) unless texts.size == refs.size
+
+      images = stubbed.empty? ? :kept : kept_images(entry, refs.size, stubbed)
+      return whole(entry, group) if images.nil?
+
+      texts = texts.each_with_index.map do |text, run|
+        edit = edits[refs[run].id] if stubbed.include?(run)
+        text = edit ? stub(text, edit, refs[run], group) : whole(text, group)
+        shown.include?(run) ? with_id(text, refs[run].id) : text
+      end
+      sent = entry.merge(content: texts.map(&:text).join(ToolResponse::SEPARATOR))
+      images == :kept ? sent : with_images(sent, images)
+    end
+
+    # +sent+ as it is: an output between two forgotten ones ends their run.
+    def whole(sent, group)
+      group.key = nil
+      sent
+    end
+
+    # The run's text with its id after its lead.
+    def with_id(text, id)
+      text.with(body: "[##{id}] #{text.body}")
+    end
+
+    def stub(text, edit, ref, group)
+      lead = text.name ? "[#{text.name}] " : ""
+      ToolResponse::RunText.new(name: text.name, lead: lead, body: stub_body(text, edit, ref, group))
+    end
+
+    # A stale stub's note; a forget's note (or, after the first of its
+    # call's forgotten outputs in a row, a pointer to that one), its
+    # restore hint (not for a derived id: it names nothing the model can
+    # restore) and its kept lines.
+    def stub_body(text, edit, ref, group)
+      return whole(edit.stub, group) unless edit.kind == :forget
+
+      key = [edit.note, edit.by, edit.staged_at]
+      if group.key == key
+        head = "(forgotten with #{group.first}: see its note)"
+      else
+        group.first = ref.id
+        group.key = key
+        head = edit.stub
+      end
+      head += " [restore: #{ref.id}]" unless text.name == READ || ref.derived?
+      [head, *kept_lines(text.body, edit.keep, edit.keep_offset)].join("\n")
+    end
+
+    # The kept ranges of +body+'s lines, each under a "lines A-B kept:"
+    # line, A and B as the model named them (+offset+ past the body's own:
+    # a ranged read's file lines); a range is cut to the body, one wholly
+    # outside it goes.
+    def kept_lines(body, keep, offset)
+      lines = body.lines
+      keep.filter_map do |first, last|
+        from = [first - offset, 1].max
+        to = [last - offset, lines.size].min
+        next if from > to
+
+        "lines #{from + offset}-#{to + offset} kept:\n#{lines[(from - 1)..(to - 1)].join.chomp}"
+      end
+    end
+
+    # The entry's [images, image_counts] without the stubbed runs' ones;
+    # nil when they can't be told apart by run.
+    def kept_images(entry, run_count, stubbed)
+      images = Array(entry[:images])
+      return [[], nil] if images.empty?
+      return [[], nil] if run_count == 1
+
+      counts = entry[:image_counts]
+      return nil unless counts.is_a?(Array) && counts.size == run_count && counts.sum == images.size
+
+      offset = 0
+      kept = counts.each_with_index.flat_map do |count, run|
+        slice = images[offset, count]
+        offset += count
+        stubbed.include?(run) ? [] : slice
+      end
+      [kept, counts.each_with_index.map { |count, run| stubbed.include?(run) ? 0 : count }]
+    end
+
+    def with_images(entry, (images, counts))
+      return entry.except(:images, :image_counts) if images.empty?
+
+      entry.merge(images: images, image_counts: counts)
+    end
+  end
+end

data/lib/samagotchi/log_subscriber.rb

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

data/lib/samagotchi/prompt.rb

@@ -112,18 +112,11 @@ module Samagotchi
 
     # A native tool_response entry (ToolResponse.joined: "[name]" outputs
     # joined by its SEPARATOR) as Gemma's template writes the results: one
-    # response:NAME{value:<|"|>…<|"|>} block per call. A part that doesn't
-    # open with a "[name]" is the previous output's own text.
+    # response:NAME{value:<|"|>…<|"|>} block per call (ToolResponse.split:
+    # a part that doesn't open with a "[name]" is the previous output's own
+    # text).
     def self.tool_response_blocks(content, profile)
-      runs = content.split(ToolResponse::SEPARATOR).each_with_object([]) do |part, acc|
-        if (match = part.match(/\A\[([^\]\s]+)\](?:\n| |\z)/))
-          acc << [match[1], match.post_match]
-        elsif acc.empty?
-          acc << ["unknown", part]
-        else
-          acc.last[1] = "#{acc.last[1]}#{ToolResponse::SEPARATOR}#{part}"
-        end
-      end
+      runs = ToolResponse.split(content).map { |run| [run.name || "unknown", run.body] }
       runs = [["unknown", ""]] if runs.empty?
       q = profile.string_delim
       runs.map do |name, body|

data/lib/samagotchi/session_manager.rb

@@ -178,7 +178,8 @@ module Samagotchi
     # is when the worker starts); opts[:env] adds to it (merged, not
     # replaced) what it can't read there: this `chi`'s CLI settings
     # (Config.cli_env), the hosts and the absolute log file. It unsets
-    # SAMAGOTCHI_GUARDRAILS_*. XDG_CONFIG_HOME passes: whoever starts or
+    # SAMAGOTCHI_GUARDRAILS_* and the session markers (SESSION_MARKER_ENV).
+    # XDG_CONFIG_HOME passes: whoever starts or
     # wakes the worker picks which config.yml it reads (docs/guardrails.md).
     private_class_method def self.spawn_options(session)
       # Own process group: workers outlive `chi web`, and a Ctrl-C in its
@@ -218,6 +219,11 @@ module Samagotchi
       # key mapped to nil. config.yml no longer reads them; this keeps an
       # older or future env-exposed one out as well.
       ENV.each_key { |key| child_env[key] = nil if key.start_with?(GUARDRAILS_ENV_PREFIX) }
+      # The markers a session's execute exports (Tools::Builtins.parent_env)
+      # are that session's: a worker started from its commands (chi send)
+      # is another session. Its execute and tasks set its own; nothing else
+      # it runs (a user's !cmd, an MCP server, a context command) has one.
+      SESSION_MARKER_ENV.each { |key| child_env[key] = nil }
       # A smoke's fake "newest installed" is for this process's notices only.
       child_env[InstalledVersions::ENV_KEY] = nil
       # A gem-mode worker activates the newest installed chi itself: under
@@ -238,6 +244,8 @@ module Samagotchi
     end
 
     GUARDRAILS_ENV_PREFIX = "SAMAGOTCHI_GUARDRAILS_"
+    # Tools::Builtins.parent_env's (Tools::TaskRuntime::MARKER_ENV_KEYS).
+    SESSION_MARKER_ENV = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL].freeze
 
     # List all sessions, reading status from persisted session.json files.
     # +project_root+: only that project's sessions (nil: every session).

data/lib/samagotchi/session_metrics.rb

@@ -6,6 +6,7 @@ require "time"
 require "fileutils"
 require "securerandom"
 require_relative "atomic_file"
+require_relative "token_usage"
 require_relative "session"
 
 module Samagotchi
@@ -104,6 +105,9 @@ module Samagotchi
       # decode one came from (server / estimate).
       :cached_sum,
       :cache_write_sum,
+      # What the server prefilled again of the previous request's prompt
+      # (KernelLoop#reprefilled_tokens; an LLM context edit's cache break).
+      :reprefill_sum,
       :reasoning_sum,
       :cost_sum,
       :decode_ms_sum,
@@ -273,6 +277,7 @@ module Samagotchi
       when :generation_completed, :generation_cancelled
         record_served_model(event)
         count_cut(event)
+        count_reprefill(event)
         record_generation_completed
       when :generation_retrying
         # The retry streams from the start: its counts replace the ones so far.
@@ -397,6 +402,7 @@ module Samagotchi
         completion_sum: add.call(:completion_sum),
         cached_sum: add.call(:cached_sum),
         cache_write_sum: add.call(:cache_write_sum),
+        reprefill_sum: add.call(:reprefill_sum),
         reasoning_sum: add.call(:reasoning_sum),
         cost_sum: add.call(:cost_sum),
         decode_ms_sum: decode_ms.round,
@@ -456,6 +462,7 @@ module Samagotchi
           token_sources: [],
           cached_sum: 0,
           cache_write_sum: 0,
+          reprefill_sum: 0,
           reasoning_sum: 0,
           cost_sum: nil,
           decode_ms_sum: 0,
@@ -527,6 +534,14 @@ module Samagotchi
       end
     end
 
+    # A generation's re-prefilled tokens (its :generation_completed's), into the turn.
+    def count_reprefill(event)
+      tokens = event[:reprefill_tokens]
+      return unless tokens.is_a?(Integer) && tokens >= TokenUsage::REPREFILL_MIN_TOKENS
+
+      @mutex.synchronize { @turn.reprefill_sum += tokens if @turn }
+    end
+
     def record_generation_completed
       @mutex.synchronize { close_generation if @turn&.gen_open }
     end
@@ -654,6 +669,7 @@ module Samagotchi
         tps_source: turn.tps_source
       }
       fields[:cache_write_tokens_sum] = turn.cache_write_sum if turn.cache_write_sum.positive?
+      fields[:reprefill_tokens_sum] = turn.reprefill_sum if turn.reprefill_sum.positive?
       fields.merge!(cost: turn.cost_sum, cost_source: "reported") if turn.cost_sum
       fields
     end
@@ -891,7 +907,7 @@ module Samagotchi
     def reset_totals
       @totals = { cancellations: 0, prompt_sum: 0, completion_sum: 0, token_sources: [], iterations: 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,
+                  reprefill_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
@@ -908,6 +924,7 @@ module Samagotchi
       totals[:capped] += number(record[:capped])
       totals[:cached_sum] += number(record[:cached_tokens_sum])
       totals[:cache_write_sum] += number(record[:cache_write_tokens_sum])
+      totals[:reprefill_sum] += number(record[:reprefill_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

@@ -68,10 +68,13 @@ module Samagotchi
     # server's KV cache for it, stay stable.
     # @param chat [Boolean] for the chat loop
     # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
-    def build(chat: false, thinking: nil)
+    # @param layers [Array<Symbol>] the turn's LLM context layers: the
+    #   native prompt declares the tools they add (Tools::Registry#entries)
+    def build(chat: false, thinking: nil, layers: [])
       @built ||= {}
-      @built[[chat, thinking]] ||= system_prompt_with_index(assist_system_prompt(chat: chat, thinking: thinking),
-                                                            chat: chat, thinking: thinking)
+      @built[[chat, thinking, layers]] ||= system_prompt_with_index(
+        assist_system_prompt(chat: chat, thinking: thinking, layers: layers), chat: chat, thinking: thinking, layers: layers
+      )
     end
 
     # Drops the built prompts: the next #build reads the profile, tools,
@@ -90,8 +93,9 @@ module Samagotchi
 
     # The base prompt (specs, plugins' declarations), with Gemma's tool
     # declarations at its end as #build has them.
-    def base(chat: false, thinking: nil)
-      with_tail_declarations(assist_system_prompt(chat: chat, thinking: thinking), chat: chat)
+    def base(chat: false, thinking: nil, layers: [])
+      with_tail_declarations(assist_system_prompt(chat: chat, thinking: thinking, layers: layers), chat: chat,
+                                                                                                  layers: layers)
     end
 
     # Names activated via preloaded --memory entries during prompt
@@ -113,13 +117,14 @@ module Samagotchi
 
     # ── Tool declarations ──────────────────────────────────────────────────────
 
-    def tool_declarations
+    def tool_declarations(layers)
+      schemas = ToolDeclarations.native_schemas(@tools_lookup.call, layers: layers)
       case profile.name
       when "qwen36"
-        ToolDeclarations.qwen_declarations(ToolDeclarations.native_schemas(@tools_lookup.call))
+        ToolDeclarations.qwen_declarations(schemas)
       else
         # Gemma 4 format
-        ToolDeclarations.gemma_declarations(ToolDeclarations.native_schemas(@tools_lookup.call))
+        ToolDeclarations.gemma_declarations(schemas)
       end
     end
 
@@ -148,7 +153,7 @@ module Samagotchi
     # @param chat [Boolean] for the chat loop: no tool declarations, call
     #   syntax or turn preamble (its tools go as schemas with each request)
     # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
-    def assist_system_prompt(chat: false, thinking: nil)
+    def assist_system_prompt(chat: false, thinking: nil, layers: [])
       return chat_system_prompt if chat
 
       hint = tool_call_hint
@@ -158,7 +163,7 @@ module Samagotchi
       tools = if gemma_tail_declarations?
                 "Your tools are declared at the end of this system prompt."
               else
-                "You have access to the following tools:\n\n#{tool_declarations}\n"
+                "You have access to the following tools:\n\n#{tool_declarations(layers)}\n"
               end
 
       <<~SYS
@@ -247,7 +252,7 @@ module Samagotchi
     # 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)
+    def system_prompt_with_index(base, chat: false, thinking: nil, layers: [])
       thinking_token = chat ? "" : Thinking.native(thinking || turn_thinking, profile).system_token
       memory_sections = [
         "Project memories:\n#{read_memory_index("project")}",
@@ -257,15 +262,15 @@ module Samagotchi
                 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?
+      return with_tail_declarations(stable_text, chat: chat, layers: layers) 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)
+      with_tail_declarations(prompt, chat: chat, layers: layers)
     end
 
-    def with_tail_declarations(prompt, chat:)
-      chat || !gemma_tail_declarations? ? prompt : prompt.rstrip + tool_declarations
+    def with_tail_declarations(prompt, chat:, layers:)
+      chat || !gemma_tail_declarations? ? prompt : prompt.rstrip + tool_declarations(layers)
     end
 
     def gemma_tail_declarations? = profile.name == "gemma4"

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -471,8 +471,9 @@ module Samagotchi
         lines.join("\n")
       end
 
-      # ", cached 4864 (93%), cache writes 312, reasoning 212" for the tokens
-      # line; the counts a server didn't report are left out.
+      # ", cached 4864 (93%), cache writes 312, re-prefilled 2100, reasoning
+      # 212" for the tokens line; the counts a server didn't report are left
+      # out (re-prefilled: SessionMetrics' reprefill_sum).
       def token_breakdown_text(tokens)
         cached = tokens[:cached_sum].to_i
         reasoning = tokens[:reasoning_sum].to_i
@@ -480,6 +481,7 @@ module Samagotchi
         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 << ", re-prefilled #{tokens[:reprefill_sum].to_i}" if tokens[:reprefill_sum].to_i.positive?
         text << ", reasoning #{reasoning}" if reasoning.positive?
         text
       end

data/lib/samagotchi/token_usage.rb

@@ -23,6 +23,9 @@ module Samagotchi
   class TokenUsage < Data.define(:prompt_tokens, :completion_tokens, :cached_tokens, :cache_write_tokens,
                                  :reasoning_tokens, :cost, :predicted_per_second, :prompt_per_second, :predicted_ms, :source)
     CHARS_PER_TOKEN = 4.0
+    # Re-prefilled tokens under this are none (KernelLoop#reprefilled_tokens,
+    # SessionMetrics): servers count the cache in blocks (OpenAI's 128).
+    REPREFILL_MIN_TOKENS = 128
 
     class << self
       # @param payload [Hash, nil] the raw streamed chunk payload