samagotchi 0.43.0 → 0.45.0

data/lib/samagotchi/bundles/system/self_map.md

@@ -3,7 +3,8 @@
 ## Start here
 - `chi self` (via `execute`) prints my version, **source dir**, config path, hooks dir,
   memory dirs, sessions dir, model/host and bundles. Use its source dir; don't hunt via `which`/`gem list`/`find /`.
-  Its `model` row is this session's model (live after `/model`), `model key` my overlay key.
+  Its `model` row is this session's model (live after `/model`), `model key` my overlay key,
+  `model notes` the model notes my prompt loads (`/stats` names the ones this session's prompt carried).
 - My current session id is in the system prompt; resume with `chi --resume <id>`.
 - My debug log is the `log` line of `chi self` (default `$XDG_STATE_HOME/samagotchi/samagotchi.log`,
   next to the sessions dir; not `~/.local/state` when `XDG_STATE_HOME` is set). One record per line,

data/lib/samagotchi/commands/registry.rb

@@ -10,9 +10,15 @@ module Samagotchi
     # An entry the UI runs itself (/stats, /exit, …) is +local+: it is listed
     # for Tab completion and help, and #lookup never returns it.
     class Registry
+      # What a line does while a turn runs: runs now on its own thread
+      # (:anytime), runs after the turn ends (:queue), or is refused
+      # (:refuse, "busy").
+      MID_TURN = %i[anytime queue refuse].freeze
+
       # @!attribute id [Symbol] the entry's key (:model, :rollback, …)
       # @!attribute name [String] "/model", "!rollback", …
-      # @!attribute anytime [Boolean] may run while a turn runs
+      # @!attribute mid_turn [Symbol, #call] what a line of it does while a
+      #   turn runs (MID_TURN): a symbol, or a lambda line (stripped) → one
       # @!attribute local [Boolean] the UI runs it; completion and help only
       # @!attribute uis [Array<Symbol>, nil] a local entry's UIs (:repl,
       #   :attached) for completion; nil means every UI
@@ -21,9 +27,19 @@ module Samagotchi
       #   a built-in's with the line, and calls a bundle's with the text
       #   after the name
       # @!attribute source [String] "core", or the bundle that added it
-      Entry = Struct.new(:id, :name, :description, :anytime, :local, :uis, :match, :handler, :source,
+      Entry = Struct.new(:id, :name, :description, :mid_turn, :local, :uis, :match, :handler, :source,
                          keyword_init: true) do
         def match?(text) = match.call(text)
+
+        # Whether every line of it runs at once, a turn running or not (D8).
+        def anytime = mid_turn == :anytime
+
+        # @param text [String] a line of it, stripped
+        # @return [Symbol] one of MID_TURN
+        def mid_turn_for(text) = mid_turn.respond_to?(:call) ? mid_turn.call(text) : mid_turn
+
+        # How a listing names #mid_turn: "depends" when it is the line's.
+        def mid_turn_label = mid_turn.respond_to?(:call) ? "depends" : mid_turn.to_s
         def slash? = name.start_with?("/")
         def in_ui?(ui) = uis.nil? || uis.include?(ui)
       end
@@ -49,21 +65,36 @@ module Samagotchi
           next if name.empty? || known.include?(name)
 
           known << name
-          registry.register(name, item[:description].to_s, anytime: item[:anytime] == true, local: item[:local] == true,
+          registry.register(name, item[:description].to_s, mid_turn: listed_mid_turn(item), local: item[:local] == true,
                                                            uis: item[:uis]&.map(&:to_sym), source: item[:source] || "core")
         end
         registry
       end
 
+      # A listed entry's #mid_turn: its mid_turn, else (an older worker's
+      # listing) its anytime. "depends" (a line's own, which only the
+      # worker's entry knows) and anything unknown are :refuse: the UI
+      # sends the line and the worker decides.
+      def self.listed_mid_turn(item)
+        label = item[:mid_turn]&.to_sym
+        return label if MID_TURN.include?(label)
+        return :refuse if label
+
+        item[:anytime] == true ? :anytime : :refuse
+      end
+      private_class_method :listed_mid_turn
+
+      # @param anytime [Boolean] mid_turn: :anytime (a bundle's command)
+      # @param mid_turn [Symbol, #call, nil] see Entry; nil takes +anytime+
       # @param match [#call, nil] the default matches the name alone or the
       #   name, a space and arguments
       # @return [Entry]
-      def register(name, description, id: nil, anytime: false, local: false, uis: nil, match: nil,
+      def register(name, description, id: nil, anytime: false, mid_turn: nil, local: false, uis: nil, match: nil,
                    source: "core", &handler)
         raise ArgumentError, "command #{name} is already registered" if @entries.any? { |entry| entry.name == name }
 
         entry = Entry.new(id: id || name.delete_prefix("/").to_sym, name: name, description: description,
-                          anytime: anytime, local: local, uis: uis, match: match || default_match(name),
+                          mid_turn: mid_turn || (anytime ? :anytime : :refuse), local: local, uis: uis, match: match || default_match(name),
                           handler: handler, source: source)
         @entries << entry
         entry
@@ -77,6 +108,19 @@ module Samagotchi
 
       def command?(line) = !lookup(line).nil?
 
+      # Whether every line of +line+'s command runs at once, a turn running
+      # or not (D8). A line whose #mid_turn is :anytime but whose command's
+      # isn't always (/model) runs at once only while a turn runs.
+      def anytime?(line) = lookup(line)&.anytime == true
+
+      # What +line+ does while a turn runs (MID_TURN); :refuse for a line
+      # no command answers.
+      # @return [Symbol]
+      def mid_turn(line)
+        text = line.to_s.strip
+        lookup(text)&.mid_turn_for(text) || :refuse
+      end
+
       # A line that is one word: a slash and a name, no spaces, no second
       # slash. `/modle` is one; `/foo bar` and `/usr/bin/env` are not (they
       # are prompts).
@@ -115,12 +159,13 @@ module Samagotchi
       def entries = @entries.dup
 
       # What a snapshot tells a UI without an Engine (see .from_listing).
-      # @return [Array<Hash>] {name:, description:, anytime:, local:, uis:,
-      #   source:} per entry, in registration order
+      # @return [Array<Hash>] {name:, description:, anytime:, mid_turn:,
+      #   local:, uis:, source:} per entry, in registration order; anytime
+      #   is true only when every line is (mid_turn "anytime")
       def listing
         @entries.map do |entry|
-          { name: entry.name, description: entry.description, anytime: entry.anytime ? true : false,
-            local: entry.local ? true : false, uis: entry.uis&.map(&:to_s), source: entry.source }
+          { name: entry.name, description: entry.description, anytime: entry.anytime,
+            mid_turn: entry.mid_turn_label, local: entry.local ? true : false, uis: entry.uis&.map(&:to_s), source: entry.source }
         end
       end
 

data/lib/samagotchi/context_status.rb

@@ -63,13 +63,21 @@ module Samagotchi
       "context elevated — be concise, prefer range reads, avoid re-reading large files",
       "context critical — summarize aggressively, avoid large outputs, delegate broad work to subagents"
     ].freeze
+    # The top level's words when the buckets count against a budget
+    # (llm_context.budget_tokens) and no forget layer: nothing in the
+    # model's hands shrinks the context, so no "summarize".
+    BUDGET_CRITICAL = "context budget critical — avoid large outputs and re-reads, delegate broad work to subagents"
 
     # @param bucket [String] "under<N>" or "<N>plus"
     # @param thresholds [Array<Integer>] the configured ones, sorted
-    def self.guidance(bucket, thresholds = DEFAULT_THRESHOLDS)
+    # @param budget [Boolean] the buckets count against a budget
+    def self.guidance(bucket, thresholds = DEFAULT_THRESHOLDS, budget: false)
       rank = bucket_rank(bucket, thresholds)
       level = rank < GUIDANCE_FROM_RANK ? 0 : GUIDANCE.size - 1 - (thresholds.size - rank)
-      GUIDANCE[level.clamp(0, GUIDANCE.size - 1)]
+      level = level.clamp(0, GUIDANCE.size - 1)
+      return BUDGET_CRITICAL if budget && level == GUIDANCE.size - 1
+
+      GUIDANCE[level]
     end
 
     # 0 for the bucket under the first threshold, then one per threshold.
@@ -331,11 +339,16 @@ module Samagotchi
 
     def k(tokens) = tokens >= 1000 ? "#{(tokens / 1000.0).round}k" : tokens.to_s
 
+    # The buckets count against the budget (set, and not over the window).
+    def budget_counted?(usage) = !@budget.nil? && usage[:window_tokens] == @budget
+
     def guidance_message(usage:, bucket:)
       how = usage[:source].to_s == "server" ? "as the server reports" : "estimated"
+      budget = budget_counted?(usage)
+      of = budget ? "the context budget (#{k(@budget)} tokens)" : "the context window"
       { role: "system", kind: LINE_KIND,
-        content: "#{LINE_PREFIX}about #{usage[:estimated_pct].to_f.round}% of the context window is in use " \
-                 "(#{how}; bucket=#{bucket}). #{self.class.guidance(bucket, @thresholds)}]" }
+        content: "#{LINE_PREFIX}about #{usage[:estimated_pct].to_f.round}% of #{of} is in use " \
+                 "(#{how}; bucket=#{bucket}). #{self.class.guidance(bucket, @thresholds, budget: budget)}]" }
     end
 
     def status_message(usage:, bucket:)
@@ -350,7 +363,7 @@ module Samagotchi
         bucket: bucket,
         thresholds: @thresholds.join(","),
         src: usage[:source],
-        guidance: self.class.guidance(bucket, @thresholds)
+        guidance: self.class.guidance(bucket, @thresholds, budget: budget_counted?(usage))
       )
     end
   end

data/lib/samagotchi/engine.rb

@@ -481,11 +481,16 @@ module Samagotchi
 
     # The model notes the session's prompt carried at its last build
     # (Session#prompt_notes): a resumed session's or a woken worker's saved
-    # ones until this process builds its prompt; without a session, the
-    # notes the effective model's prompt would load.
+    # ones until this process builds its prompt; a fresh session (no build
+    # yet, no messages) has none saved, so the effective model's prompt
+    # would load them: the notes #model_notes names, as without a session.
+    # The three readers (/model, /stats, the web) share this.
     # @return [Array<PromptNote>]
     def prompt_notes
-      return @session.prompt_notes.dup if @session
+      return model_notes.map { |note| PromptNote.from_note(note) } unless @session
+
+      saved = @session.prompt_notes
+      return saved.dup if !@prompt_builder.prompt_notes.nil? || !saved.empty? || @session.messages.to_a.any?
 
       model_notes.map { |note| PromptNote.from_note(note) }
     rescue StandardError

data/lib/samagotchi/host_registry.rb

@@ -235,6 +235,26 @@ module Samagotchi
       end
     end
 
+    # List one host's models and save them to ModelListStore: what
+    # ModelProfile.model_warning re-lists on a miss (a fresh saved list that
+    # lacks the id: the server may have been reloaded with another model),
+    # so the saved list catches up at spawn time. Only that host is asked,
+    # and never through the cache (a fresh listing is the point).
+    # @param name [String, Symbol, nil] a host name; anything else lists
+    #   nothing
+    # @return [Array<String>, nil] the ids the host lists now, nil for an
+    #   unknown name or when the host fails to list (nothing is saved then:
+    #   a host that is down keeps the ids we know)
+    def list_models(name)
+      entry = name.nil? ? nil : find_entry(name)
+      return nil unless entry
+
+      save_model_list(entry.name, list_models_for(entry))&.ids
+    rescue StandardError => e
+      Log.warn(:model, "list_failed", host: name.to_s, error: e.class.name, msg: e.message.to_s[0, 500])
+      nil
+    end
+
     def client_for_model(raw_model)
       host_entry, bare = host_for_model(raw_model)
       [client_for(host_entry), bare, host_entry]
@@ -293,9 +313,7 @@ module Samagotchi
             models = list_models_for(entry)
             data = { host: entry.host, port: entry.port, transport: entry.transport, models: models, error: nil }
             @mutex.synchronize { @host_lists[name] = { data: data, at: @clock.call } }
-            # On disk too: a process that spawns a worker without listing
-            # (`chi send --new --model`, delegate) checks an id against it.
-            ModelListStore.save(name, models.map(&:id))
+            save_model_list(name, models)
           rescue StandardError => e
             Log.warn(:model, "list_failed", host: name, error: e.class.name, msg: e.message.to_s[0, 500])
             data = { host: entry.host, port: entry.port, transport: entry.transport, models: [], error: e.message }
@@ -350,6 +368,13 @@ module Samagotchi
 
     private
 
+    # Save a host's just-listed models on disk, for the processes that spawn
+    # a worker without listing (`chi send --new --model`, delegate):
+    # ModelListStore is what they check an id against.
+    def save_model_list(name, models)
+      ModelListStore.save(name, Array(models).map(&:id))
+    end
+
     def fresh_list(name, entry)
       @mutex.synchronize do
         cached = @host_lists[name]

data/lib/samagotchi/kernel_loop.rb

@@ -28,6 +28,7 @@ require_relative "tool_ids"
 require_relative "llm_context_view"
 require_relative "llm_context_apply"
 require_relative "llm_context_forget"
+require_relative "llm_context_notice"
 require_relative "answer_display"
 require_relative "llm/model_result"
 require_relative "llm/turn_settings"
@@ -279,7 +280,8 @@ module Samagotchi
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:)
       conversation = prepare_conversation(messages)
       context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context)
-      @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context)
+      emit = ->(event) { emit_stream_event(on_stream_event, event) }
+      @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context, emit: emit)
       Turn.new(
         conversation: conversation, context: context,
         empty_retry: EmptyAnswerRetry.new, empty_steps: [], tool_activity: [], buffer: +"", streamed_thinking: +"",
@@ -290,7 +292,7 @@ module Samagotchi
         prefill: Thinking.native(@turn_settings.thinking || Thinking::DEFAULT, @profile).prefill,
         pending_tool_calls: false, model_name: @turn_settings.model_name, pending_input: pending_input,
         on_stream_event: on_stream_event, cancel_controller: cancel_controller, cap: cap,
-        emit: ->(event) { emit_stream_event(on_stream_event, event) }
+        emit: emit
       )
     end
 
@@ -321,7 +323,7 @@ module Samagotchi
     # (the prompt cache keeps its prefix), and the prompt is formatted again
     # with it.
     def prepare_request(turn)
-      apply_llm_context!(turn.conversation, context: turn.context)
+      apply_llm_context!(turn.conversation, context: turn.context, emit: turn.emit)
       prompt, images = format_prompt(turn)
       image_tokens = images.empty? ? 0 : ImagePlan.estimated_tokens(turn.conversation)
       window = ContextWindow.resolve(client: @client, model: turn.model_name, setting: @turn_settings.window_setting)
@@ -580,7 +582,7 @@ module Samagotchi
       # The model answered: the staged edits reach the session now (a turn
       # that ran out of steps, on tool results or on a retry's nudge, is
       # mid-task; they wait).
-      apply_llm_context!(turn.conversation, moment: :turn_end) if turn.answered
+      apply_llm_context!(turn.conversation, moment: :turn_end, emit: turn.emit) if turn.answered
       # An empty answer left the conversation: an earlier model message
       # isn't this turn's answer.
       output = turn.ended_empty ? "" : strip_thought_blocks(last_model_content(turn.conversation))
@@ -784,8 +786,8 @@ module Samagotchi
         return "Error: forget_outputs is off (the llm_context strategy has no forget layer)"
       end
 
-      LLMContextForget.call(turn, call, llm_context: llm_context,
-                                        apply: -> { apply_llm_context!(turn.conversation, llm_context, context: turn.context) })
+      apply = -> { apply_llm_context!(turn.conversation, llm_context, context: turn.context, emit: turn.emit) }
+      LLMContextForget.call(turn, call, llm_context: llm_context, apply: apply)
     end
 
     # Before each request of both loops (+moment+ :request; the warm-up
@@ -797,10 +799,12 @@ module Samagotchi
     # first, and the warm-up) is the first with the stubs. +context+: the
     # turn's ContextStatus (payoff applies in its top bucket; an applied
     # batch rebases its estimate, ContextStatus#edited!). none changes
-    # nothing. Logged as llm_context_apply when a batch is applied.
+    # nothing. Logged as llm_context_apply when a batch is applied, and
+    # shown to the user as a ✂ row (+emit+ takes the :llm_context_edited
+    # event, LLMContextNotice; the warm-up's own copy has none).
     # @return [LLMContextApply::Outcome]
     def apply_llm_context!(conversation, llm_context = @turn_settings&.llm_context, moment: :request, context: nil,
-                           warmup: false)
+                           warmup: false, emit: nil)
       view = llm_context_view(llm_context)
       return LLMContextApply::Outcome.none if view.none?
 
@@ -811,7 +815,10 @@ module Samagotchi
       if outcome.applied?
         # The prompt just shrank: the context estimate counts from it.
         context&.edited!
-        log_llm_context(outcome, llm_context, moment) unless warmup
+        unless warmup
+          log_llm_context(outcome, llm_context, moment)
+          emit_llm_context(emit, conversation, outcome, moment) if emit
+        end
       end
       outcome
     end
@@ -825,6 +832,14 @@ module Samagotchi
     end
     private :log_llm_context
 
+    # The batch's ✂ row; a row that can't be built never breaks the turn.
+    def emit_llm_context(emit, conversation, outcome, moment)
+      emit.call(LLMContextNotice.event(conversation, outcome, moment: moment))
+    rescue StandardError => e
+      Log.warn(:model, "llm_context_notice_failed", error: e.class.name, message: e.message)
+    end
+    private :emit_llm_context
+
     # A request's re-prefilled tokens, for both loops: of the prompt the
     # last request on +model+ sent (this kernel's, any turn), what the
     # server didn't reuse from its cache this time (that prompt less

data/lib/samagotchi/llm/chat_loop.rb

@@ -358,7 +358,8 @@ module Samagotchi
           # steps from them (ModelResult#empty_steps).
           @empty_steps = []
           @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context)
-          loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context)
+          loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context,
+                                                             emit: method(:emit))
         end
 
         def call(max_iterations:, cap:)
@@ -455,7 +456,7 @@ module Samagotchi
         def generate(iteration)
           # The strategy's edits the apply rule lets through first (stale):
           # this request sends them.
-          @loop.apply_llm_context!(@conversation, context: @context)
+          @loop.apply_llm_context!(@conversation, context: @context, emit: method(:emit))
           window = @window = @loop.context_window(@model_name)
           observe_context(iteration, window)
           retry_generation = @empty_retry.take_sampling!
@@ -640,7 +641,7 @@ module Samagotchi
         def result(text, exhausted:)
           # The model answered: the staged edits reach the session now (a
           # turn that ran out of steps is mid-task; they wait).
-          @loop.apply_llm_context!(@conversation, moment: :turn_end) unless exhausted
+          @loop.apply_llm_context!(@conversation, moment: :turn_end, emit: method(:emit)) unless exhausted
           ModelResult.new(text: text, conversation: @loop.plain(@conversation), exhausted: exhausted,
                           tool_activity: @tool_activity, empty_steps: @empty_steps, empty_retries: @empty_retry.attempts,
                           context_status: @context.display)

data/lib/samagotchi/llm_context_forget.rb

@@ -44,8 +44,12 @@ module Samagotchi
     SMALL = 80
 
     # The turn a forget_outputs call runs in: its conversation (the
-    # entries the edits are saved on) and its ContextStatus (nil: none).
-    Turn = Data.define(:conversation, :context)
+    # entries the edits are saved on), its ContextStatus (nil: none) and
+    # its stream (+emit+, nil: none), which gets an applied batch's ✂ row
+    # (LLMContextNotice).
+    Turn = Data.define(:conversation, :context, :emit) do
+      def initialize(emit: nil, **fields) = super
+    end
 
     # One output a call may name: its entry, its ToolIds ref, its tool,
     # its text (without the "[name]" lead) and its step; +offset+: what

data/lib/samagotchi/llm_context_notice.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "llm_context_stale"
+require_relative "tool_activity"
+require_relative "token_usage"
+
+module Samagotchi
+  # The ✂ row a turn gets for a batch of LLM context edits the apply rule
+  # let through (LLMContextApply::Outcome#applied?): the :llm_context_edited
+  # event both loops emit (KernelLoop#apply_llm_context!, its +emit+), at a
+  # request (+moment+ :request; a forget_outputs call's batch too) or at the
+  # end of a turn (:turn_end); never for the warm-up, a held or a staged
+  # batch, or a restore (the forget_outputs row says it). The web and the
+  # TUI print +text+ as it is; the web's hover lists +groups+.
+  #
+  # {type: :llm_context_edited, moment:, why:, freed_tokens:, tail_tokens:,
+  #  staged:, text: "✂ forgot 2 outputs, stubbed 1 stale read · frees ~4.1k
+  #  tokens (paid off)", groups: [{kind: "stale", items: [{id, tool, title,
+  #  note}]}, {kind: "forget", note:, by:, items: [{id, tool, title, kept}]}]}
+  #
+  # The stale items share one group, each with its own note; a forget group
+  # is one forget_outputs call's (the view's key: note, by and staged_at),
+  # its note once. Tokens are chars/4, so "~".
+  module LLMContextNotice
+    TYPE = :llm_context_edited
+    # A forget's note on the row, at most (the stub keeps all of it).
+    NOTE_MAX = 300
+    WHY = { payoff: "paid off", top_bucket: "the context is nearly full", turn_end: "at turn end" }.freeze
+
+    module_function
+
+    # @param outcome [LLMContextApply::Outcome] an applied one
+    # @param moment [Symbol] :request or :turn_end
+    # @return [Hash] the event
+    def event(conversation, outcome, moment:, cwd: Dir.pwd)
+      calls = LLMContextStale.paired_runs(conversation).to_h { |run| [run.ref.id, run.call] }
+      groups = groups(outcome.applied, calls, cwd)
+      freed = tokens(outcome.freed_chars)
+      { type: TYPE, moment: moment.to_s, why: outcome.why.to_s, freed_tokens: freed,
+        tail_tokens: tokens(outcome.tail_chars), staged: outcome.staged,
+        text: text(groups, freed, outcome.why, outcome.staged), groups: groups }
+    end
+
+    def groups(edits, calls, cwd)
+      stale = edits.select { |edit| edit.kind == :stale }
+      forgets = edits.select { |edit| edit.kind == :forget }.group_by { |edit| [edit.note, edit.by, edit.staged_at] }
+      groups = []
+      unless stale.empty?
+        groups << { kind: "stale", items: stale.map { |edit| item(edit, calls, cwd).merge(note: edit.note) } }
+      end
+      forgets.each do |(note, by, _), group|
+        items = group.map do |edit|
+          kept = edit.keep.map { |first, last| first == last ? first.to_s : "#{first}-#{last}" }
+          item(edit, calls, cwd).merge(kept: kept.empty? ? nil : kept.join(", ")).compact
+        end
+        groups << { kind: "forget", note: cut(note.to_s), by: by, items: items }
+      end
+      groups
+    end
+
+    # An output's id, its tool and its row's title (ToolActivity.tool_title;
+    # none when its call can't be told).
+    def item(edit, calls, cwd)
+      call = calls[edit.id]
+      return { id: edit.id } unless call
+
+      name = call[:name].to_s
+      { id: edit.id, tool: name, title: ToolActivity.tool_title(name, call, cwd: cwd) }.compact
+    end
+
+    # "✂ forgot 2 outputs, stubbed 1 stale read · frees ~4.1k tokens (paid
+    # off) · 1 more staged".
+    def text(groups, freed, why, staged)
+      forgot = groups.select { |group| group[:kind] == "forget" }.sum { |group| group[:items].size }
+      stale = groups.select { |group| group[:kind] == "stale" }.sum { |group| group[:items].size }
+      done = []
+      done << "forgot #{count(forgot, "output")}" if forgot.positive?
+      done << "stubbed #{count(stale, "stale read")}" if stale.positive?
+      frees = freed.positive? ? "frees ~#{k(freed)}" : "frees nothing"
+      frees += " (#{WHY[why]})" if WHY.key?(why)
+      line = "✂ #{done.join(", ")} · #{frees}"
+      staged.positive? ? "#{line} · #{staged} more staged" : line
+    end
+
+    def count(number, noun) = "#{number} #{noun}#{"s" unless number == 1}"
+
+    def tokens(chars) = [(chars / TokenUsage::CHARS_PER_TOKEN).ceil, 0].max
+
+    # "4.1k tokens", "640 tokens".
+    def k(tokens) = tokens >= 1000 ? format("%.1fk tokens", tokens / 1000.0) : "#{tokens} tokens"
+
+    def cut(note) = note.length > NOTE_MAX ? "#{note[0, NOTE_MAX - 1]}…" : note
+
+    private_class_method :groups, :item, :text, :count, :tokens, :k, :cut
+  end
+end

data/lib/samagotchi/llm_context_strategy.rb

@@ -167,6 +167,43 @@ module Samagotchi
                     budget_tokens: budget_origin)
     end
 
+    # A session's LLM context strategy, apply rule and budget, each with
+    # where it came from (Explained#summary), as its worker would resolve
+    # them; nil when they can't be (an unreadable config, a model that
+    # resolves nowhere). Resolves from config and the registry only: no
+    # network, no model call. What a session page, a session list's ctx %
+    # and a spawn-time check all read.
+    # @param session [Session, nil]
+    # @param registry [HostRegistry, nil] the hosts to resolve against;
+    #   HostRegistry.new by default (what the caller usually has)
+    # @return [Hash, nil] Explained#summary, symbol keys
+    def for_session(session, registry: nil)
+      return nil if session.nil?
+
+      require_relative "config"
+      registry ||= begin
+        require_relative "host_registry"
+        HostRegistry.new
+      end
+      name = session.model_name.to_s.strip.empty? ? ModelProfile.required_model_name(nil) : session.model_name
+      target = registry.resolve(name)
+      names = registry.lookup_names(session.model_typed || name, resolved: name, target: target)
+      own = session.llm_context
+      explain(target, names: names, **(own&.resolve_args || {})).summary(own)
+    rescue StandardError
+      nil
+    end
+
+    # The budget a session's turns run under (for_session's :budget_tokens),
+    # nil when it is off or can't be resolved. What a session list's ctx %
+    # counts against, so a saved session's fill reads as the live meter.
+    # @param session [Session, nil]
+    # @param registry [HostRegistry, nil] see .for_session
+    # @return [Integer, nil]
+    def session_budget(session, registry: nil)
+      for_session(session, registry: registry)&.fetch(:budget_tokens, nil)
+    end
+
     # [the budget, its Origin]: the session's own first (0 there is off,
     # whatever the model says).
     def budget_for(target, names, models, session_budget)

data/lib/samagotchi/model_notes.rb

@@ -63,7 +63,8 @@ module Samagotchi
         files(scope, env).filter_map do |path|
           next unless seen.add?(File.expand_path(path))
 
-          note_at(path, scope, name: name, key: key, fallback_key: fallback_key, muted: muted, small: small_once)
+          note_at(path, scope, name: name, key: key, fallback_key: fallback_key, muted: muted, small: small_once,
+                  env: env)
         end
       end
       warn_sizes(notes) if warn
@@ -110,7 +111,7 @@ module Samagotchi
       []
     end
 
-    def note_at(path, scope, name:, key:, fallback_key:, muted:, small:)
+    def note_at(path, scope, name:, key:, fallback_key:, muted:, small:, env: ENV)
       stem = File.basename(path, ".md")
       return nil if dotted?(path, stem)
       return nil if MutedMemories.muted?(stem, muted)
@@ -122,7 +123,7 @@ module Samagotchi
       body = File.read(path, encoding: "UTF-8").sub(/\A[^\n]*\n?/, "").strip
       return nil if body.empty?
 
-      body = with_overlay(body, stem, scope, [key, fallback_key])
+      body = with_overlay(body, stem, scope, [key, fallback_key], env: env)
 
       Note.new(name: stem, scope: scope, body: body, chars: body.length, digest: Digest::SHA256.hexdigest(body)[0, 12])
     rescue StandardError
@@ -131,10 +132,11 @@ module Samagotchi
 
     # The note's model overlay appended as memory_read appends one: the
     # key's, else the fallback key's. The file is read by its own path, not
-    # by name through memory_read (whose names are comma lists).
-    def with_overlay(body, stem, scope, keys)
+    # by name through memory_read (whose names are comma lists). +env+: the
+    # XDG env the scope's dir (and so the overlay) resolves from.
+    def with_overlay(body, stem, scope, keys, env: ENV)
       keys.compact.each do |overlay_key|
-        overlay = ModelOverlay.overlay_path_for(stem, overlay_key, scope)
+        overlay = ModelOverlay.overlay_path_for(stem, overlay_key, scope, env: env)
         next unless overlay && File.file?(overlay)
 
         return "#{body}#{Tools::MemoryRead::SEPARATOR}Model-specific guidance (#{overlay_key}):\n" \

data/lib/samagotchi/model_overlay.rb

@@ -38,10 +38,11 @@ module Samagotchi
 
     # Return the expected file path for an overlay in the given scope.
     # Respects MemoryBundle overrides (delegates to Tools::MemoryRead.memories_dir).
-    def self.overlay_path_for(name, key, scope)
+    # @param env [Hash] the XDG env the scope's memories dir resolves from
+    def self.overlay_path_for(name, key, scope, env: ENV)
       return nil unless key && !key.to_s.strip.empty?
 
-      File.join(Tools::MemoryRead.memories_dir(scope), "#{name}.#{key.to_s.strip}.md")
+      File.join(Tools::MemoryRead.memories_dir(scope, env: env), "#{name}.#{key.to_s.strip}.md")
     end
 
     # Regex matching overlay file names: /<something>.<lowercase-dashed-key>.md\z