samagotchi 0.66.0 → 0.68.0

data/lib/samagotchi/reasoning_history_command.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
-require_relative "cache_confirm"
+require_relative "level_setting_command"
 require_relative "reasoning_history"
 
 module Samagotchi
   # /reasoning-history, the session's own reasoning_history level
-  # (Session#reasoning_history): with no argument, the level the next turn
-  # runs under and where it came from; `/reasoning-history drop|turn|all`
-  # sets the session's own (an explicit turn too), `/reasoning-history
-  # default` unsets it (the session follows SAMAGOTCHI_REASONING_HISTORY,
-  # the model, its host, then turn). A change takes effect at the next
-  # turn's start; a native host ignores the level (its loop keeps the
-  # running turn's reasoning), but the session keeps it for a chat model.
-  # A change that rewrites the earlier replies asks first (CacheConfirm);
-  # --yes (or -y) applies it.
-  class ReasoningHistoryCommand
+  # (Session#reasoning_history): `/reasoning-history drop|turn|all` sets it
+  # (an explicit turn too), `/reasoning-history default` unsets it (the
+  # session follows SAMAGOTCHI_REASONING_HISTORY, the model, its host, then
+  # turn). Resolved on any host: a native one ignores the level (its loop
+  # keeps the running turn's reasoning), but the session keeps it for a
+  # chat model. A change that rewrites the earlier replies asks first. See
+  # LevelSettingCommand.
+  class ReasoningHistoryCommand < LevelSettingCommand
     NAME = "/reasoning-history"
     USAGE = "usage: #{NAME} [#{(ReasoningHistory::LEVELS + [ReasoningHistory::UNSET]).join("|")}]".freeze
     NATIVE_NOTE = "  (ignored on this host: the native loop keeps the running turn's reasoning)"
@@ -24,84 +22,25 @@ module Samagotchi
                "from the first earlier thought."
     }.freeze
 
-    # @param engine [Engine] #reasoning_history_explained,
-    #   #reasoning_history_override(=), #session, #chat_model?,
-    #   #reasoning_history_cache_cost, #history?
-    # @param save [#call] saves the session after a change
-    def initialize(engine:, save:)
-      @engine = engine
-      @save = save
-    end
-
-    # @param args [String] what follows /reasoning-history (--yes anywhere)
-    # @param confirm [Boolean] ask before a costly change (CacheConfirm);
-    #   false applies it at once
-    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
-    #   whether the level changed, and the confirm it asks for (nothing
-    #   changed then)
-    # @raise [ArgumentError] a word that isn't a level (with USAGE)
-    def run(args, confirm: true)
-      word, yes = CacheConfirm.split(args)
-      return [listing(explained), false, nil] if word.empty?
-
-      level = ReasoningHistory.session_level(word)
-      raise ArgumentError, "unknown reasoning history level #{word}\n#{USAGE}" unless level || word == ReasoningHistory::UNSET
-
-      session = @engine.session or raise ArgumentError, "no session yet"
-      before = explained
-      ask = confirm && !yes ? ask(before, level, word) : nil
-      return ask if ask
-
-      @engine.reasoning_history_override = level
-      @save.call(session)
-      after = explained
-      [[listing(after), *notes(before, after)].join("\n"), true, nil]
-    end
-
-    # The level, where it came from, and what the session sets itself.
-    def listing(explained)
-      return "reasoning history: can't be resolved for this model" unless explained
-
-      lines = ["reasoning history: #{explained.label}"]
-      unless explained.own
-        lines << "  this session's own: none (follows #{ReasoningHistory::ENV_NAME}, the model, its host, then turn)"
-      end
-      lines << NATIVE_NOTE unless chat?
-      lines.join("\n")
-    end
-
-    private
-
-    # Resolved on any host: a native one ignores it, but /reasoning-history
-    # still shows what a chat model would get.
-    def explained(own: @engine.reasoning_history_override)
-      @engine.reasoning_history_explained(native: true, own: own)
-    end
-
-    # The reply that asks before a costly change, nil when it needn't.
-    def ask(before, own, word)
-      would = explained(own: own)
-      return nil unless before && would
-
-      cost = @engine.reasoning_history_cache_cost(before.level, would.level)
-      return nil unless CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: would.level != before.level)
-
-      step = CacheConfirm.confirm(NAME, word)
-      [[listing(before), "Switching to #{would.level} restarts the prompt cache: #{COST_NOTES[cost]}", step.text].join("\n"), false, step]
-    end
-
-    def chat?
-      @engine.chat_model?
-    rescue StandardError
-      false
-    end
-
-    def notes(before, after)
-      return [] unless before && after
-      return ["(no change to what the next turn runs under)"] if before.level == after.level
-
-      cost = @engine.reasoning_history_cache_cost(before.level, after.level)
-      ["From the next turn's start (a running turn keeps its own).", COST_NOTES[cost]].compact
-    end
+    SPEC = Spec.new(
+      name: NAME, label: "reasoning history", usage: USAGE, cost_notes: COST_NOTES,
+      parse: lambda { |word|
+        level = ReasoningHistory.session_level(word)
+        [!level.nil? || word == ReasoningHistory::UNSET, level]
+      },
+      own: lambda(&:reasoning_history_override),
+      explained: ->(engine, own) { engine.reasoning_history_explained(native: true, own: own) },
+      set: ->(engine, own) { engine.reasoning_history_override = own },
+      cache_cost: ->(engine, from, to) { engine.reasoning_history_cache_cost(from, to) },
+      follows: "#{ReasoningHistory::ENV_NAME}, the model, its host, then turn",
+      extra_line: lambda { |engine|
+        chat = begin
+          engine.chat_model?
+        rescue StandardError
+          false
+        end
+        chat ? nil : NATIVE_NOTE
+      }
+    )
   end
 end

data/lib/samagotchi/row_refs.rb

@@ -26,7 +26,7 @@ module Samagotchi
 
     module_function
 
-    # Runs +fn+ (the tool's refs: lambda, as Api.per_call wraps it: call →
+    # Runs +fn+ (the tool's refs: lambda, as ToolSpec#per_call wraps it: call →
     # a list of {kind:, target:, label:, actions:}) on +call+. Never
     # raises: a lambda that raises or returns something other than a list
     # gives none, and a bad ref is dropped; both are logged (warn, not

data/lib/samagotchi/self_report.rb

@@ -13,6 +13,7 @@ require_relative "thinking"
 require_relative "reasoning_history"
 require_relative "served_model"
 require_relative "host_registry"
+require_relative "host_keys"
 require_relative "llm/adapters"
 require_relative "tools/memory"
 require_relative "hooks/loader"
@@ -391,13 +392,14 @@ module Samagotchi
       "#{entry.name} #{location}#{suffix}"
     end
 
-    # The variable the host's API key comes from and whether it is set; the
-    # key itself is never shown.
+    # The variable the host's API key comes from and whether it is set, or
+    # comes from the Keychain (HostKeys); the key itself is never shown.
     def api_key_for(model, env)
       name = HostRegistry.new(env: env).resolve(model).entry&.api_key_env
       return "-" unless name
 
-      "#{name} (#{env[name].to_s.empty? ? "unset" : "set"})"
+      state = { env: "set", keychain: "keychain" }.fetch(HostKeys.source(name, env: env), "unset")
+      "#{name} (#{state})"
     end
 
     # The Chi Helper app's version against this chi's (read from its

data/lib/samagotchi/send_command.rb

@@ -40,7 +40,7 @@ module Samagotchi
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...
              chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [--thinking LEVEL] [--toolkit NAME] [-m TEXT] [--image PATH]...
-             chi send --new --continues (ID|PREFIX|last:ID) [-m TEXT] [--image PATH]...
+             chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT] [--image PATH]...
              chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
              chi send --queue --wait [--timeout S] [--format json] [-m TEXT] ID
              chi send --wait [--timeout S] [--format json] ID
@@ -63,9 +63,11 @@ module Samagotchi
                     the current one
         --continues ID
                     (--new) start the next link of that session's chain:
-                    in its folder, on its model, LLM context,
-                    thinking level and toolkit, with a note carrying its recap; it
-                    is archived. last:ID names the chain's latest link.
+                    in its folder, on its model (or --model's; one whose
+                    host is gone falls back to the default, with a
+                    warning), LLM context, thinking level and toolkit,
+                    with a note carrying its recap; it is archived.
+                    last:ID names the chain's latest link.
                     Without -m the new session waits idle. Refused for a
                     session continued already (naming the next link) or
                     with delegates still open
@@ -289,11 +291,11 @@ module Samagotchi
       return usage_error("--new takes no session ids: it starts one session") unless options[:ids].empty?
 
       if options[:continues]
-        taken = [("--dir" if options[:dir]), ("--model" if options[:model])] +
+        taken = [("--dir" if options[:dir])] +
                 LLM_CONTEXT_FLAGS.filter_map { |key, flag| flag if options[key] } + [("--thinking" if options[:thinking])] +
                 [("--toolkit" if options[:toolkit])] + TOOLKIT_FLAGS.filter_map { |key, flag| flag unless Array(options[key]).empty? }
         unless taken.compact.empty?
-          return usage_error("--continues takes the previous session's folder, model, LLM context, thinking level and " \
+          return usage_error("--continues takes the previous session's folder, LLM context, thinking level and " \
                              "toolkit; " \
                              "leave out #{taken.compact.join(", ")}")
         end
@@ -358,7 +360,8 @@ module Samagotchi
       begin
         start = through_worker ? { prompt: nil, title: prompt } : { prompt: prompt }
         session = if options[:continues]
-                    SessionManager.continue_session(options[:continues], **start, state_dir: @state_dir)
+                    SessionManager.continue_session(options[:continues], **start, model: options[:model],
+                                                                             state_dir: @state_dir)
                   else
                     SessionManager.spawn_session(**start, working_directory: options[:dir],
                                                           model_name: options[:model],
@@ -388,15 +391,22 @@ module Samagotchi
                                  timeout: options[:timeout])
     end
 
-    # --continues: the model the new link will run (the previous link's),
-    # for the images check; [nil, nil] without --continues.
+    # The model the new session will run, for the images check: --model
+    # (nil: the default), or with --continues the one the new link will run
+    # (SessionContinue.model_for: --model's, else the previous link's, else
+    # the default it falls back to).
     # @return [Array, false] [model_name, model_typed], or false after the
-    #   error line (no such session)
+    #   error line (no such session, a model it can't start on)
     def continued_model(options)
       return [options[:model], nil] unless options[:continues]
 
       previous = Session.load(SessionChain.resolve(options[:continues], state_dir: @state_dir), state_dir: @state_dir)
-      [previous.model_name, previous.model_typed]
+      choice = SessionContinue.model_for(previous, options[:model])
+      inherited = options[:model].to_s.strip.empty? && choice.warning.nil?
+      inherited ? [previous.model_name, previous.model_typed] : [choice.model, nil]
+    rescue ModelProfile::MissingModel => e
+      error_line("chi send: could not start a session: #{e.message}")
+      false
     rescue ArgumentError => e
       error_line("chi send: #{e.message}")
       false

data/lib/samagotchi/session.rb

@@ -259,6 +259,8 @@ module Samagotchi
       self.interrupted_turn = interrupted_turn
       @turn_checkpoint = nil
       @archived = false
+      # #save's lock: one snapshot-and-write at a time (see #save).
+      @save_lock = Mutex.new
     end
 
     # A `delegate` child: its turns report to its parent (ChildReports). A
@@ -513,18 +515,30 @@ module Samagotchi
     end
 
     # Persist the session atomically. Updates +updated_at+ in place.
+    #
+    # One save at a time per Session: a worker saves its session from the
+    # loop/turn thread (TurnCheckpoint, Engine's turn end, WorkerInbound),
+    # from Bridge threads (QuestionDesk, commands run mid-turn) and from a
+    # signal's thread. AtomicFile keeps each write whole, but two
+    # unserialized saves could rename an older snapshot over a newer one (a
+    # lost update); under the lock the last rename is the latest snapshot.
+    # Never call it from a trap handler (Mutex#lock raises ThreadError
+    # there; WorkerSignals saves on a thread of its own) or from inside a
+    # save (the lock isn't re-entrant).
     def save(state_dir: self.class.default_state_dir)
-      @updated_at = Time.now.iso8601(3)
-      # Persist with current metadata version so new flag is written
-      @metadata_version = METADATA_VERSION
-      FileUtils.mkdir_p(state_dir)
+      @save_lock.synchronize do
+        @updated_at = Time.now.iso8601(3)
+        # Persist with current metadata version so new flag is written
+        @metadata_version = METADATA_VERSION
+        FileUtils.mkdir_p(state_dir)
 
-      path = self.class.session_file(@id, state_dir: state_dir)
+        path = self.class.session_file(@id, state_dir: state_dir)
 
-      # Auto-compute first_preview if not yet cached and messages contain a user entry.
-      compute_first_preview!
+        # Auto-compute first_preview if not yet cached and messages contain a user entry.
+        compute_first_preview!
 
-      AtomicFile.write(path, JSON.pretty_generate(to_h) + "\n")
+        AtomicFile.write(path, JSON.pretty_generate(to_h) + "\n")
+      end
       self
     end
 

data/lib/samagotchi/session_continue.rb

@@ -56,11 +56,21 @@ module Samagotchi
     # moved the chain's end while it waited for the lock.
     TRIES = 3
 
+    # The model a new link runs on (#model_for): the name to spawn it with,
+    # and why it isn't the previous link's (nil when it is, or was given).
+    ModelChoice = Data.define(:model, :warning)
+    # What #check! decided before anything changes: the delegates to move
+    # (ChildMove::Plan) and the new link's model (ModelChoice).
+    Checked = Data.define(:plan, :choice)
+
     # Start the next link of a chain: a new session that continues
     # +id_or_ref+ (Session#continues) in its folder, on its model (the name
     # it was typed as, so an alias holds) and with its own setup (SessionSetup),
     # starting with a context note from chi: the link and the previous
-    # link's recap (SessionChain.note_text). The previous link is archived
+    # link's recap (SessionChain.note_text). +model+, when given, is the
+    # new link's model instead; an inherited one whose host can't run it any
+    # more (gone, disabled, an alias naming another host) falls back to the
+    # default with a warning (#model_for). The previous link is archived
     # first, with its finished delegates (archive_session's rules: a turn
     # running, a prompt queued or the step-limit question refuse; an idle
     # worker is stopped), so a refusal starts nothing. Its open delegates
@@ -81,7 +91,7 @@ module Samagotchi
     # @raise [Refused] continued already, delegates open that can't
     #   move, or its folder is gone
     # @raise [ArchiveRefused, OwnedByTUI] as archive_session
-    def self.run(id_or_ref, prompt: nil, title: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5)
+    def self.run(id_or_ref, prompt: nil, title: nil, model: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5)
       sd = state_dir || Session.default_state_dir
       TRIES.times do |try|
         id = SessionChain.resolve(id_or_ref, state_dir: sd)
@@ -89,7 +99,7 @@ module Samagotchi
           follow = id_or_ref.to_s.strip.start_with?(SessionChain::LAST_PREFIX) && try < TRIES - 1
           next :moved if follow && SessionChain.next_of(id, state_dir: sd)
 
-          run_locked(id, prompt: prompt, title: title, state_dir: sd, recap_wait: recap_wait,
+          run_locked(id, prompt: prompt, title: title, model: model, state_dir: sd, recap_wait: recap_wait,
                          archive_wait: archive_wait)
         end
         return result unless result == :moved
@@ -105,9 +115,10 @@ module Samagotchi
       end
     end
 
-    private_class_method def self.run_locked(id, prompt:, title:, state_dir:, recap_wait:, archive_wait:)
+    private_class_method def self.run_locked(id, prompt:, title:, model:, state_dir:, recap_wait:, archive_wait:)
       previous = Session.load(id, state_dir: state_dir)
-      plan = check!(previous, state_dir)
+      checked = check!(previous, state_dir, model: model)
+      plan = checked.plan
       # archive_session's refusals that can be known now, before the wait.
       SessionManager.archivable!(id, state_dir, except: plan.move)
       recap_before_archive(id, state_dir, wait: recap_wait)
@@ -120,7 +131,8 @@ module Samagotchi
       archive = SessionManager.archive_session(id, state_dir: state_dir, wait: archive_wait, except: plan.move)
       archived = archive[:archived] - already
       begin
-        spawn_continuation(previous, prompt: prompt, title: title, state_dir: state_dir, move: plan.move)
+        spawn_continuation(previous, prompt: prompt, title: title, choice: checked.choice, state_dir: state_dir,
+                                     move: plan.move)
       rescue StandardError
         # Nothing started: the delegates go back, what this archived goes
         # back to the lists, and a new link saved before its worker failed
@@ -181,7 +193,7 @@ module Samagotchi
 
     # The new link, holding off any worker but its own (ChildMove.starting?)
     # while +move+ goes to it.
-    private_class_method def self.spawn_continuation(previous, prompt:, title:, state_dir:, move:)
+    private_class_method def self.spawn_continuation(previous, prompt:, title:, choice:, state_dir:, move:)
       recap = RecapStore.read(Session.session_dir(previous.id, state_dir: state_dir))
       start = prompt.to_s.strip.empty? ? nil : prompt
       title = previous.first_preview if title.to_s.strip.empty? && start.nil?
@@ -191,33 +203,64 @@ module Samagotchi
       end
       link = SessionManager.spawn_session(
         prompt: start, title: title, working_directory: previous.working_directory,
-        model_name: previous.model_typed || previous.model_name, setup: SessionSetup.of(previous),
+        model_name: choice.model, setup: SessionSetup.of(previous),
         continues: previous.id, note: SessionChain.note_text(previous, recap: recap),
         note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn
       )
       link.moved_children = move
+      # The fallback's warning first: spawn_session set its own.
+      warnings = [choice.warning, link.model_warning].compact
+      link.model_warning = warnings.join("; ") unless warnings.empty?
       link
     end
 
+    # The model a new link of +previous+'s chain runs on: +given+ when
+    # there is one (its host checked: ModelProfile::UnknownHost as for a new
+    # session), else the previous link's, as typed (so an alias holds). An
+    # inherited one whose host can't run it any more (gone from config.yml,
+    # disabled, an alias naming another host: UnknownHost) falls back to the
+    # default, with a warning naming why. `chi send --new --continues`
+    # judges images by it before #run decides the same.
+    # @param previous [Session]
+    # @param given [String, nil] blank: inherit
+    # @return [ModelChoice]
+    # @raise [ModelProfile::MissingModel] a +given+ model it can't run, or
+    #   a fallback with no default configured (or the default's host can't run it)
+    def self.model_for(previous, given)
+      unless given.to_s.strip.empty?
+        return ModelChoice.new(model: ModelProfile.check_host!(ModelProfile.required_model_name(given.strip)),
+                               warning: nil)
+      end
+
+      inherited = ModelProfile.required_model_name(previous.model_typed || previous.model_name)
+      begin
+        ModelChoice.new(model: ModelProfile.check_host!(inherited), warning: nil)
+      rescue ModelProfile::UnknownHost => e
+        default = ModelProfile.check_host!(ModelProfile.required_model_name(nil))
+        ModelChoice.new(model: default, warning: "#{inherited} can't run (#{e.message}); started on #{default}")
+      end
+    end
+
     # The refusals that come before anything changes: continued already (no
     # forks in a chain), an open delegate that can't move to the new link
     # (ChildMove.plan), the folder gone (the worker would run elsewhere), a
-    # model whose host config.yml no longer has.
-    # @return [ChildMove::Plan]
+    # given model whose host config.yml doesn't have, or an inherited one
+    # that can't run with no default to fall back to (#model_for).
+    # @return [Checked]
     # @raise [Refused, ModelProfile::MissingModel]
-    private_class_method def self.check!(previous, state_dir)
+    private_class_method def self.check!(previous, state_dir, model: nil)
       if (following = SessionChain.next_of(previous.id, state_dir: state_dir))
         raise Refused.new(previous.id, :continued, ids: [following])
       end
 
       plan = move_plan!(previous.id, state_dir)
-      # Its model's host, as SessionManager.spawn_session checks it: before
-      # the archive stops the previous link's worker.
-      ModelProfile.check_host!(ModelProfile.required_model_name(previous.model_typed || previous.model_name))
+      # The new link's model, its host checked as SessionManager.spawn_session
+      # checks it: before the archive stops the previous link's worker.
+      choice = model_for(previous, model)
       dir = previous.working_directory.to_s
       raise Refused.new(previous.id, :folder_gone, detail: dir) unless File.directory?(dir)
 
-      plan
+      Checked.new(plan: plan, choice: choice)
     end
 
     # A child still open below a session (#open_children); why: running,

data/lib/samagotchi/session_inbox.rb

@@ -236,15 +236,6 @@ module Samagotchi
       UNREADABLE_INPUT
     end
 
-    # Whether an unclaimed input file carries images (a mid-turn drain
-    # leaves it for its own turn).
-    def self.input_has_images?(input_file)
-      data = JSON.parse(File.read(input_file))
-      data.is_a?(Hash) && Array(data["images"]).any?
-    rescue JSON::ParserError, SystemCallError
-      false
-    end
-
     # Whether a mid-turn drain leaves this unclaimed input file for a turn
     # of its own instead of merging it at a step boundary: a queued message
     # (`delivery: queue`) or an image message (steering merges text only).
@@ -258,10 +249,6 @@ module Samagotchi
       false
     end
 
-    # Whether an input file carrying +enqueued_id+ still waits unclaimed in
-    # input/ (no worker has taken it for a turn or a step yet).
-    def self.input_waiting?(session_dir, enqueued_id) = !waiting_input(session_dir, enqueued_id).nil?
-
     # How the unclaimed input file carrying +enqueued_id+ waits: :turn_end
     # (a queue or an image message: it runs as a turn of its own, never
     # merged, #waits_for_turn_end?), :merges (a running turn's drain may

data/lib/samagotchi/session_setting.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "effective_model"
+
+module Samagotchi
+  # One per-session setting (the session's own value, before its model's):
+  # what the UIs show as a chip and the commands set. +key+ is the Session
+  # attribute and the chip's key everywhere (the session state, /stats, a
+  # :command_ran, the web's session JSON); +changed_by+ the commands'
+  # `changed` entries that move the chip; +snapshot_fallback+ how the web
+  # treats a worker snapshot's value: :or (a nil value falls back to the
+  # session file's) or :key (a key present stands, nil included: a worker
+  # says nil on a native host, which ignores reasoning_history; an older
+  # worker has no key). +chip+ the chip from an EffectiveModel and the
+  # session's own value; nil for the toolkit, which resolves against the
+  # worker's kits (Engine#toolkit_summary), not the model. +live+ the
+  # chip as an Engine's public readers give it (a :command_ran's).
+  SessionSetting = Data.define(:key, :changed_by, :snapshot_fallback, :chip, :live) do
+    # The session's own value, nil without a session or one.
+    def own(session) = session&.public_send(key)
+
+    # Sets the session's own value (nil unsets it); the caller saves.
+    def set(session, value) = session.public_send(:"#{key}=", value)
+
+    # Whether a command that changed +changed+ moves this chip.
+    def changed_by?(changed) = changed.intersect?(changed_by)
+
+    # Whether the chip comes from the model (not the toolkit).
+    def model? = !chip.nil?
+
+    # The chip for +session+ on +model+ (EffectiveModel, nil when it
+    # doesn't resolve: nil then).
+    def chip_for(model, session) = model && chip.call(model, own(session))
+
+    # The chip as +engine+ (a worker's) gives it now.
+    def summary(engine) = live.call(engine)
+
+    # The chip for a saved session no worker runs (Web::App, the session
+    # lists): resolved from its file, config and the registry (no network);
+    # nil when it can't be.
+    def saved_summary(session, registry:)
+      return saved_toolkit(session.toolkit) unless model?
+
+      chip_for(EffectiveModel.of_session(session, registry: registry), session)
+    rescue StandardError
+      nil
+    end
+
+    # The web's chip: a worker's snapshot (string keys) per
+    # +snapshot_fallback+, else the block's (the saved one).
+    def snapshot_value(snapshot)
+      name = key.to_s
+      return snapshot[name] if snapshot_fallback == :key && snapshot&.key?(name)
+      return snapshot[name] if snapshot_fallback == :or && snapshot && snapshot[name]
+
+      yield
+    end
+
+    private
+
+    # A toolkit as its file names it ({name:, label:}), nil on full:
+    # without a worker nothing resolves it (a bundle's kits load there).
+    def saved_toolkit(toolkit)
+      toolkit && !toolkit.full? ? { name: toolkit.name, label: toolkit.label } : nil
+    end
+  end
+
+  class SessionSetting
+    LLM_CONTEXT = new(key: :llm_context, changed_by: %i[llm_context model], snapshot_fallback: :or,
+                      chip: ->(model, own) { model.llm_context_explained(own&.resolve_args || {})&.summary(own) },
+                      live: lambda(&:llm_context_summary))
+    THINKING = new(key: :thinking, changed_by: %i[thinking model], snapshot_fallback: :or,
+                   chip: ->(model, own) { model.thinking_explained(own: own)&.summary },
+                   live: ->(engine) { engine.thinking_explained&.summary })
+    # nil on a native host (its loop ignores the level).
+    REASONING_HISTORY = new(key: :reasoning_history, changed_by: %i[reasoning_history model], snapshot_fallback: :key,
+                            chip: ->(model, own) { model.reasoning_history_explained(own: own)&.summary },
+                            live: ->(engine) { engine.reasoning_history_explained&.summary })
+    TOOLKIT = new(key: :toolkit, changed_by: %i[toolkit], snapshot_fallback: :key, chip: nil, live: lambda(&:toolkit_summary))
+
+    # In the order the session state, a :command_ran and the web name them.
+    ALL = [LLM_CONTEXT, THINKING, REASONING_HISTORY, TOOLKIT].freeze
+    # /stats's (no toolkit: its JSON never had one).
+    STATS = [LLM_CONTEXT, THINKING, REASONING_HISTORY].freeze
+  end
+end