samagotchi 0.67.0 → 0.68.0

data/lib/samagotchi/level_setting_command.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "cache_confirm"
+
+module Samagotchi
+  # A command for a session's own level of a setting (/thinking,
+  # /reasoning-history): with no argument, the level the next turn runs at
+  # and where it came from; with a level, sets the session's own (the
+  # setting's unset word unsets it). A change takes effect at the next
+  # turn's start (the REPL and the worker run it between turns), and the
+  # reply says what it costs the prompt cache. A costly change asks first
+  # (CacheConfirm); --yes (or -y) applies it.
+  #
+  # A subclass gives its Spec (#spec): what differs between the settings.
+  class LevelSettingCommand
+    # name: the command; label: the reply's ("thinking: low (session)");
+    # usage: the usage line an unknown word gets;
+    # parse: word → [known?, the session's own level (nil unsets)];
+    # own: engine → the session's own level now;
+    # explained: (engine, own) → SettingExplained, nil when it can't be resolved;
+    # set: (engine, own) → sets the session's own;
+    # cache_cost: (engine, from_level, to_level) → a cost_notes key, nil for none;
+    # cost_notes: {cost => the reply's line};
+    # follows: what the session follows with no own level;
+    # extra_line: engine → one more listing line, nil for none.
+    Spec = Data.define(:name, :label, :usage, :parse, :own, :explained, :set, :cache_cost, :cost_notes, :follows,
+                       :extra_line)
+
+    # @param engine [Engine] the session's (#session, #history? and the spec's readers)
+    # @param save [#call] saves the session after a change
+    def initialize(engine:, save:)
+      @engine = engine
+      @save = save
+    end
+
+    # @param args [String] what follows the command (--yes anywhere)
+    # @param confirm [Boolean] ask before a costly change (CacheConfirm);
+    #   false applies it at once (chi send, a delegate, a start flag)
+    # @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 the usage)
+    def run(args, confirm: true)
+      word, yes = CacheConfirm.split(args)
+      return [listing(explained), false, nil] if word.empty?
+
+      known, own = spec.parse.call(word)
+      raise ArgumentError, "unknown #{spec.label} level #{word}\n#{spec.usage}" unless known
+
+      session = @engine.session or raise ArgumentError, "no session yet"
+      before = explained
+      ask = confirm && !yes ? ask(before, own, word) : nil
+      return ask if ask
+
+      spec.set.call(@engine, own)
+      @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 "#{spec.label}: can't be resolved for this model" unless explained
+
+      lines = ["#{spec.label}: #{explained.label}"]
+      lines << "  this session's own: none (follows #{spec.follows})" unless explained.own
+      extra = spec.extra_line&.call(@engine)
+      lines << extra if extra
+      lines.join("\n")
+    end
+
+    private
+
+    def spec = self.class::SPEC
+
+    def explained(own: spec.own.call(@engine)) = spec.explained.call(@engine, own)
+
+    # 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 = spec.cache_cost.call(@engine, before.level, would.level)
+      return nil unless CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: would.level != before.level)
+
+      step = CacheConfirm.confirm(spec.name, word)
+      [[listing(before), "Switching to #{would.level} restarts the prompt cache: #{spec.cost_notes[cost]}", step.text].join("\n"),
+       false, step]
+    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 = spec.cache_cost.call(@engine, before.level, after.level)
+      ["From the next turn's start (a running turn keeps its own).", spec.cost_notes[cost]].compact
+    end
+  end
+end

data/lib/samagotchi/llm_context_strategy.rb

@@ -211,17 +211,12 @@ module Samagotchi
     def for_session(session, registry: nil)
       return nil if session.nil?
 
-      require_relative "config"
-      require_relative "model_profile"
-      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)
+      # Here, not at the top: config.rb requires this file before ConfigFile
+      # exists, and effective_model.rb requires config.rb (via host_registry.rb).
+      require_relative "effective_model"
+      registry ||= HostRegistry.new
       own = session.llm_context
-      explain(target, names: names, **(own&.resolve_args || {})).summary(own)
+      EffectiveModel.of_session(session, registry: registry).llm_context_explained(own&.resolve_args || {})&.summary(own)
     rescue StandardError
       nil
     end

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/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_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

data/lib/samagotchi/thinking_command.rb

@@ -1,18 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "cache_confirm"
+require_relative "level_setting_command"
 require_relative "thinking"
 
 module Samagotchi
-  # /thinking, the session's own thinking level (Session#thinking): with no
-  # argument, the level the next turn runs at and where it came from;
-  # `/thinking off|low|medium|high` sets the session's own, `/thinking
-  # default` unsets it (the session follows the process default, the
-  # model, its host, then thinking.level). A change takes effect at the
-  # next turn's start (the REPL and the worker run it between turns), and
-  # the reply says what it costs the prompt cache (Thinking.cache_cost).
-  # A costly change asks first (CacheConfirm); --yes (or -y) applies it.
-  class ThinkingCommand
+  # /thinking, the session's own thinking level (Session#thinking):
+  # `/thinking off|low|medium|high` sets it, `/thinking default` unsets it
+  # (the session follows the process default, the model, its host, then
+  # thinking.level). What a change costs the prompt cache:
+  # Thinking.cache_cost. See LevelSettingCommand.
+  class ThinkingCommand < LevelSettingCommand
     NAME = "/thinking"
     SETTABLE = (Thinking::LEVELS - [Thinking::DEFAULT]).freeze
     USAGE = "usage: #{NAME} [#{Thinking::LEVELS.join("|")}]".freeze
@@ -24,71 +21,22 @@ module Samagotchi
       tail: "Only the prompt's tail changes: the cache keeps the rest."
     }.freeze
 
-    # @param engine [Engine] #thinking_explained(own:), #thinking_override(=),
-    #   #session, #thinking_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 /thinking (--yes anywhere)
-    # @param confirm [Boolean] ask before a costly change (CacheConfirm);
-    #   false applies it at once (chi send, a delegate, a start flag)
-    # @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(@engine.thinking_explained), false, nil] if word.empty?
-
-      level = word.to_sym
-      raise ArgumentError, "unknown thinking level #{word}\n#{USAGE}" unless Thinking::LEVELS.include?(level)
-
-      session = @engine.session or raise ArgumentError, "no session yet"
-      own = SETTABLE.include?(level) ? level : nil
-      before = @engine.thinking_explained
-      ask = confirm && !yes ? ask(before, own, word) : nil
-      return ask if ask
-
-      @engine.thinking_override = own
-      @save.call(session)
-      after = @engine.thinking_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 "thinking: can't be resolved for this model" unless explained
-
-      lines = ["thinking: #{explained.label}"]
-      unless explained.own
-        lines << "  this session's own: none (follows chi web --thinking / SAMAGOTCHI_THINKING_LEVEL, the model, " \
-                 "its host, then thinking.level)"
-      end
-      lines.join("\n")
-    end
-
-    private
-
-    # The reply that asks before a costly change, nil when it needn't.
-    def ask(before, own, word)
-      would = @engine.thinking_explained(own: own)
-      return nil unless before && would
-
-      cost = @engine.thinking_cache_cost
-      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 notes(before, after)
-      return [] unless before && after
-      return ["(no change to what the next turn runs under)"] if before.level == after.level
-
-      ["From the next turn's start (a running turn keeps its own).", COST_NOTES[@engine.thinking_cache_cost]].compact
-    end
+    SPEC = Spec.new(
+      name: NAME, label: "thinking", usage: USAGE, cost_notes: COST_NOTES,
+      parse: lambda { |word|
+        level = word.to_sym
+        if Thinking::LEVELS.include?(level)
+          [true, SETTABLE.include?(level) ? level : nil]
+        else
+          [false, nil]
+        end
+      },
+      own: lambda(&:thinking_override),
+      explained: ->(engine, own) { engine.thinking_explained(own: own) },
+      set: ->(engine, own) { engine.thinking_override = own },
+      cache_cost: ->(engine, _from, _to) { engine.thinking_cache_cost },
+      follows: "chi web --thinking / SAMAGOTCHI_THINKING_LEVEL, the model, its host, then thinking.level",
+      extra_line: nil
+    )
   end
 end