samagotchi 0.67.0 → 0.69.0

data/lib/samagotchi/engine.rb

@@ -14,6 +14,9 @@ require_relative "context_status"
 require_relative "steer"
 require_relative "turn_note"
 require_relative "model_profile"
+require_relative "effective_model"
+require_relative "session_setting"
+require_relative "thinking_notices"
 require_relative "cancellation_controller"
 require_relative "context_window"
 require_relative "kernel_loop"
@@ -134,15 +137,17 @@ module Samagotchi
       # is used (the REPL checks the model it starts on, #switch_model!).
       @default_model_name = ModelProfile.required_model_name(model_name)
       ModelProfile.check_host!(model_name, hosts: @host_registry.entries) unless model_name.to_s.strip.empty?
-      @effective_model_name = @default_model_name
+      # Guards the model choice and the profile cached for it (#store_profile).
+      @profile_mutex = Mutex.new
+      typed = model_typed.to_s.strip
+      @model_choice = ModelChoice.new(name: @default_model_name, typed: typed.empty? ? @default_model_name : typed)
       # An injected client (specs) stands in for every host's client.
       @host_registry.client_override = client if client
-      @client = @host_registry.resolve(@effective_model_name).client
+      @client = effective_model.client
       # A caller's profile pins it (until a model switch); otherwise
       # #profile_resolution decides on first need (see there), so building an
       # Engine makes no network call.
       @given_profile = profile ? ModelProfile.normalize(profile) : nil
-      @typed_model_name = model_typed.to_s.strip.empty? ? @default_model_name : model_typed.to_s.strip
       @profile_resolution = nil
       # Ensure the built-in system bundle is installed (lazy, warn-only).
       # This is the single seam for both TUI and non-TUI (web/worker) paths.
@@ -195,6 +200,9 @@ module Samagotchi
       # The session's toolkit: the kits (the plugins' too, chi.toolkit),
       # what its next turn declares, the turn-start apply.
       @toolkit_binding = build_toolkit_binding
+      # The notices a turn's thinking level leads to (once per session and host).
+      @thinking_notices = ThinkingNotices.new(session: -> { @session }, profile: -> { self.profile },
+                                              notify: ->(text, level, source) { hook_notify(text, level, source) })
       # The tools plugins publish without declaring (chi.tool_source), and
       # the search and call tools that reach them (Tools::ToolIndex).
       @tool_index = Tools::ToolIndex.new
@@ -204,6 +212,10 @@ module Samagotchi
       @lifecycle_mutex = Mutex.new
       @shut_down = false
       load_plugins if plugins
+      # Registered from what the sources published while they loaded, and
+      # with no plugins too: a toolkit's left-out built-ins are reachable
+      # either way (declared per toolkit, Tools::Registry).
+      @tool_index.declare(@tools, failures: @plugin_failures)
       guardrail_rules
       # The Engine owns the reminder store; its kernel (built here, or a
       # spec's) gets it, so tool calls via KernelLoop and reminder injection
@@ -288,7 +300,7 @@ module Samagotchi
     def wire_kernel(kernel, muted_memories)
       # A given kernel (specs) gets the Engine's store, hooks and tools, as
       # the one built here does.
-      @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, model_name: @effective_model_name,
+      @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, model_name: effective_model_name,
                                          hooks: @hooks, reminder_store: @reminder_store, tools: @tools)
       @kernel.reminder_store = @reminder_store
       @kernel.hooks = @hooks
@@ -373,8 +385,8 @@ module Samagotchi
     end
 
     # The backend for the next turn: the loop the effective model's host speaks.
-    def backend
-      backend_for(@host_registry.resolve(@effective_model_name))
+    def backend(model = effective_model)
+      backend_for(model)
     end
 
     # Record that activity happened (user input or a completed turn): the
@@ -522,14 +534,17 @@ module Samagotchi
 
     # @return [SessionMetrics] the per-session analytics collector
     attr_reader :metrics
-    # effective_model_name: the model as given (maybe an alias; HostRegistry#resolve
-    # applies it); typed_model_name: as typed at start or at the last /model.
-    attr_reader :default_model_name, :effective_model_name, :typed_model_name
+
+    # The model as given (maybe an alias; HostRegistry#resolve applies it).
+    def effective_model_name = @model_choice.name
+
+    # The model as typed at start or at the last /model.
+    def typed_model_name = @model_choice.typed
 
     # The resolved ref a session stores for the effective model (ModelRef#ref:
     # the alias applied, "host:id" when it names a host).
     def effective_model_ref
-      model_ref_for(@effective_model_name)
+      model_ref_for(effective_model_name)
     end
 
     # The effective model as the system prompt names it (SystemPrompt::ModelIdentity):
@@ -537,11 +552,11 @@ module Samagotchi
     # only, the model its /props names when that differs. Never a new
     # request: only the /props answer profile resolution already cached.
     def model_identity
-      target = @host_registry.resolve(@effective_model_name)
-      entry = target.entry
+      model = effective_model
+      entry = model.entry
       host = entry && "host #{entry.name}, #{entry.url || "#{entry.host}:#{entry.port}"}"
-      SystemPrompt::ModelIdentity.new(ref: effective_model_ref, host: host, key: @model_key,
-                                      served: prompt_served_model(target), fallback_key: @fallback_model_key)
+      SystemPrompt::ModelIdentity.new(ref: model.ref, host: host, key: @model_key,
+                                      served: model.prompt_served, fallback_key: @fallback_model_key)
     end
 
     # The model notes for the effective model (ModelNotes): matched on its
@@ -586,10 +601,10 @@ module Samagotchi
       summary = error.respond_to?(:summary) ? error.summary : error.message
       return summary unless error.is_a?(LLM::ProviderError) && error.host
 
-      note = @host_registry.alias_note(@effective_model_name)
+      note = @host_registry.alias_note(effective_model_name)
       note && note.end_with?("on host #{error.host}") ? "#{summary} (#{note})" : summary
-    rescue StandardError
-      summary
+    rescue StandardError => e
+      EffectiveModel::Unresolved.fallback(:alias_note_failed, effective_model_name, e, summary)
     end
 
     # +name+'s resolved ref (ModelRef#ref).
@@ -603,7 +618,8 @@ module Samagotchi
     def store_model!(session)
       ref = effective_model_ref
       session.model_name = ref
-      session.model_typed = @typed_model_name.to_s == ref ? nil : @typed_model_name
+      typed = typed_model_name
+      session.model_typed = typed.to_s == ref ? nil : typed
       session
     end
 
@@ -622,11 +638,17 @@ module Samagotchi
     # and kept, so the system prompt and the server's KV prefix stay stable;
     # #switch_model! starts over, and a failed server probe is retried before
     # the next turn (#refresh_profile!). The kernel follows each resolution.
+    # Kept with the model choice it was resolved for: one that finishes
+    # after a switch is neither kept nor applied (#store_profile).
     # @return [ModelProfile::Resolution]
     def profile_resolution
-      @profile_resolution ||= apply_profile(resolve_profile)
+      choice = @model_choice
+      cached = @profile_resolution
+      return cached.last if cached&.first.equal?(choice)
+
+      store_profile(choice, resolve_profile(choice))
     end
-    attr_reader :host_registry, :client
+    attr_reader :default_model_name, :host_registry, :client
 
     # @return [Commands::Registry] the commands this session runs: the
     #   built-ins, and the ones bundle plugins add
@@ -645,8 +667,9 @@ module Samagotchi
     # (before aliases were applied there): that key is read when the
     # target's overlay is missing (KernelLoop#sync_model_key!).
     def sync_model_key!
-      @model_key = ModelOverlay.key_for(bare_model_name(@effective_model_name))
-      typed_key = ModelOverlay.key_for(@host_registry.parse_qualified_model(@typed_model_name).last)
+      choice = @model_choice
+      @model_key = ModelOverlay.key_for(bare_model_name(choice.name))
+      typed_key = ModelOverlay.key_for(@host_registry.parse_qualified_model(choice.typed).last)
       @fallback_model_key = typed_key == @model_key ? nil : typed_key
       @kernel.sync_model_key!(@model_key, fallback: @fallback_model_key)
     end
@@ -655,17 +678,17 @@ module Samagotchi
     # The effective model's bare name for the guardrails' models: rules;
     # nil without a model name.
     def guardrail_model_name
-      name = @effective_model_name && bare_model_name(@effective_model_name)
+      model = effective_model_name
+      name = model && bare_model_name(model)
       name.to_s.strip.empty? ? nil : name
     end
 
     # Point the kernel (and a chat backend) at the effective model's host
     # (after /model, --model, resume).
-    def sync_kernel_client!
-      target = @host_registry.resolve(@effective_model_name)
-      @client = target.client
-      @kernel.client = target.client if @kernel.client != target.client
-      backend_for(target)
+    def sync_kernel_client!(model = effective_model)
+      @client = model.client
+      @kernel.client = model.client if @kernel.client != model.client
+      backend_for(model)
     end
 
     # Subscribe a persistent observer to engine events.
@@ -966,11 +989,14 @@ module Samagotchi
       # The alias is applied where the model is resolved (HostRegistry#resolve),
       # once; checked here: an unknown host, an alias naming another host.
       resolved = ModelProfile.check_host!(ModelProfile.required_model_name(model_name), hosts: @host_registry.entries)
-      @effective_model_name = resolved
-      @typed_model_name = typed.to_s.strip.empty? ? model_name : typed.to_s.strip
-      # A profile given to .new was for the starting model.
-      @given_profile = nil
-      @profile_resolution = nil
+      choice = ModelChoice.new(name: resolved, typed: typed.to_s.strip.empty? ? model_name : typed.to_s.strip)
+      @profile_mutex.synchronize do
+        # One assignment: a reader on another thread sees the old pair or the new one.
+        @model_choice = choice
+        # A profile given to .new was for the starting model.
+        @given_profile = nil
+        @profile_resolution = nil
+      end
       sync_model_key!
       @prompt_builder.reset!
       # The notes the new model's prompt loads at its next build, so /model,
@@ -1041,22 +1067,24 @@ module Samagotchi
     # @return [Hash] @metrics.snapshot, filled in
     def stats_snapshot
       snapshot = @metrics.snapshot
-      target = @host_registry.resolve(@effective_model_name)
-      served, served_for = served_model_for(snapshot, target: target)
+      # One resolve for the whole snapshot (its readers' rescues stay theirs);
+      # a model that doesn't resolve raises here, as it always has.
+      model = effective_model
+      served, served_for = served_model_for(snapshot, model: model)
       snapshot = snapshot.merge(served_model: served, served_model_for: served_for,
-                                served_expected_by: served_expected_by(served, target: target), llm_context: llm_context_summary,
-                                thinking: thinking_explained&.summary,
-                                reasoning_history: reasoning_history_explained&.summary, prompt_notes: prompt_notes.map(&:to_h),
-                                prompt_files: @prompt_builder.prompt_files, price_host: target.entry.name)
+                                served_expected_by: model.served_expected_by(served),
+                                **setting_chips(SessionSetting::STATS, model),
+                                prompt_notes: prompt_notes.map(&:to_h), prompt_files: @prompt_builder.prompt_files,
+                                price_host: model.host_name)
       unless snapshot.dig(:context, :window_tokens)
-        window = current_context_window(target)
+        window = current_context_window(model)
         if window
           snapshot = snapshot.merge(context: snapshot[:context].merge(window_tokens: window.tokens,
                                                                       window_source: window.source.to_s))
         end
       end
       # The chat loop uses no prompt profile: drop one a native turn reported.
-      return snapshot.except(:profile, :profile_source) if target.entry.chat?
+      return snapshot.except(:profile, :profile_source) if model.chat?
 
       unless snapshot[:profile]
         resolution = profile_resolution
@@ -1069,10 +1097,11 @@ module Samagotchi
     # no turn yet (it woke after an idle exit): nil when either count is
     # unknown or context.status is off. Counted as the turns count it:
     # against the effective model's llm_context budget when it has one.
-    def saved_context_status(context)
+    def saved_context_status(context, model: :current)
       return nil unless context
 
-      ContextStatus.new(llm_context: turn_llm_context)
+      llm_context = model == :current ? turn_llm_context : model&.llm_context_explained(llm_context_session_args)&.resolved
+      ContextStatus.new(llm_context: llm_context)
                    .display_for(used_tokens: context[:used_tokens], window_tokens: context[:window_tokens])
     end
 
@@ -1080,10 +1109,7 @@ module Samagotchi
     # (LLMContextStrategy.explain), nil when it can't be resolved.
     # @return [LLMContextStrategy::Explained, nil]
     def llm_context_explained
-      target = @host_registry.resolve(@effective_model_name)
-      LLMContextStrategy.explain(target, names: model_lookup_names(target), **llm_context_session_args)
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.llm_context_explained(llm_context_session_args) }
     end
 
     # #llm_context_explained's summary (Explained#summary), nil when it
@@ -1095,7 +1121,7 @@ module Samagotchi
 
     # The session's own llm_context values, nil when it has none.
     # @return [LLMContextOverride, nil]
-    def llm_context_override = @session&.llm_context
+    def llm_context_override = SessionSetting::LLM_CONTEXT.own(@session)
 
     # Set the session's own llm_context values (an empty override unsets
     # them); the next turn's start resolves them, never a running one (its
@@ -1104,23 +1130,18 @@ module Samagotchi
     def llm_context_override=(override)
       raise ArgumentError, "no session yet" unless @session
 
-      @session.llm_context = override
+      SessionSetting::LLM_CONTEXT.set(@session, override)
       # The status a later client reads counts against the new budget.
       @last_context_status = saved_context_status(@metrics.snapshot[:context]) || @last_context_status if @last_context_status
     end
 
     # The effective model is on a chat host (api: openai or anthropic), whose loop uses
     # no prompt profile.
-    def chat_model? = @host_registry.resolve(@effective_model_name).entry.chat?
+    def chat_model? = effective_model.chat?
 
     # "temperature=0.6 (hosts.work)" for /model: the effective model's
     # configured sampling, nil when none.
-    def sampling_summary
-      target = @host_registry.resolve(@effective_model_name)
-      SamplingSettings.summary(target, names: model_lookup_names(target))
-    rescue StandardError
-      nil
-    end
+    def sampling_summary = model_setting(nil, &:sampling_summary)
 
     # "off (models: qwen)", "low (session)" for /model: the effective
     # model's thinking level and where it came from, nil when none is set.
@@ -1134,10 +1155,7 @@ module Samagotchi
     # turn_sampling; on any error, the global and its name.
     # @return [Array(Integer, String|nil)]
     def steer_cut_after_explained
-      target = @host_registry.resolve(@effective_model_name)
-      SteerCutAfter.resolve(target, names: model_lookup_names(target))
-    rescue StandardError
-      [SteerCut.cut_after, "steer.cut_after"]
+      model_setting([SteerCut.cut_after, "steer.cut_after"], &:steer_cut_after_explained)
     end
 
     # #steer_cut_after_explained's seconds: what SteerCut#cut_for_steer
@@ -1159,10 +1177,7 @@ module Samagotchi
     # +own+: the session's own level to resolve with (the current one by
     # default; /thinking asks what a change would resolve to).
     def thinking_explained(own: thinking_override)
-      target = @host_registry.resolve(@effective_model_name)
-      Thinking.explain(target, names: model_lookup_names(target), session: own)
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.thinking_explained(own: own) }
     end
 
     # "drop (models: qwen)" for /model: the effective chat model's
@@ -1170,14 +1185,7 @@ module Samagotchi
     # default, the model runs on the native loop (which ignores it) or it
     # can't be resolved.
     def reasoning_history_summary
-      target = @host_registry.resolve(@effective_model_name)
-      return nil unless target.entry&.chat?
-
-      level, source = ReasoningHistory.resolve(target, names: model_lookup_names(target),
-                                                       session: reasoning_history_override)
-      source ? ReasoningHistory.label(level, source) : nil
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.reasoning_history_summary(own: reasoning_history_override) }
     end
 
     # The effective chat model's reasoning_history level with where it came
@@ -1189,12 +1197,7 @@ module Samagotchi
     # +own+: the session's own level to resolve with (the current one by
     # default; a command asks what a change would resolve to).
     def reasoning_history_explained(native: false, own: reasoning_history_override)
-      target = @host_registry.resolve(@effective_model_name)
-      return nil unless native || target.entry&.chat?
-
-      ReasoningHistory.explain(target, names: model_lookup_names(target), session: own)
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.reasoning_history_explained(own: own, native: native) }
     end
 
     # What a reasoning_history change from level +from+ to level +to+ costs
@@ -1203,10 +1206,7 @@ module Samagotchi
     # marked as refusing it may still get :history (one needless ask).
     # @return [Symbol, nil]
     def reasoning_history_cache_cost(from, to)
-      target = @host_registry.resolve(@effective_model_name)
-      ReasoningHistory.cache_cost(from, to, target: target, conversation: @session&.messages)
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.reasoning_history_cache_cost(from, to, conversation: @session&.messages) }
     end
 
     # Whether the session has a model reply (a cache to restart at all).
@@ -1216,7 +1216,7 @@ module Samagotchi
 
     # The session's own reasoning_history level, nil when it has none.
     # @return [Symbol, nil]
-    def reasoning_history_override = @session&.reasoning_history
+    def reasoning_history_override = SessionSetting::REASONING_HISTORY.own(@session)
 
     # Set the session's own reasoning_history level (nil unsets it); the
     # next turn's start resolves it. The caller saves the session.
@@ -1224,19 +1224,18 @@ module Samagotchi
     def reasoning_history_override=(level)
       raise ArgumentError, "no session yet" unless @session
 
-      @session.reasoning_history = level
+      SessionSetting::REASONING_HISTORY.set(@session, level)
     end
 
     # The session's own thinking level, nil when it has none.
     # @return [Symbol, nil]
-    def thinking_override = @session&.thinking
+    def thinking_override = SessionSetting::THINKING.own(@session)
 
     # What a thinking level change costs the effective model's prompt
     # cache (Thinking.cache_cost): :full, :provider or :tail.
     # @return [Symbol]
     def thinking_cache_cost
-      target = @host_registry.resolve(@effective_model_name)
-      Thinking.cache_cost(target, profile: target.entry&.chat? ? nil : profile&.name)
+      effective_model.thinking_cache_cost { profile }
     end
 
     # Set the session's own thinking level (nil unsets it); the next turn's
@@ -1246,7 +1245,7 @@ module Samagotchi
     def thinking_override=(level)
       raise ArgumentError, "no session yet" unless @session
 
-      @session.thinking = level
+      SessionSetting::THINKING.set(@session, level)
     end
 
     # The model the server serves for the current model, and the name asked
@@ -1255,17 +1254,15 @@ module Samagotchi
     # else [nil, nil].
     # @return [Array(String, String), Array(nil, nil)]
     def served_model(probe: true)
-      served_model_for(@metrics.served_report, target: probe ? @host_registry.resolve(@effective_model_name) : nil)
+      served_model_for(@metrics.served_report, model: probe ? effective_model : nil)
     end
 
     # The host whose hosts.<name>.models.<id>.served names +served+ for the
     # current model (a gateway's round-robin targets): not a mismatch to
     # warn about. nil when none does.
     # @return [String, nil]
-    def served_expected_by(served, target: nil)
-      ServedModel.expected_by(target || @host_registry.resolve(@effective_model_name), served)
-    rescue StandardError
-      nil
+    def served_expected_by(served)
+      model_setting(nil) { |model| model.served_expected_by(served) }
     end
 
     def served_expected?(served) = !served_expected_by(served).nil?
@@ -1297,6 +1294,10 @@ module Samagotchi
     def session_state_snapshot
       served_pair = served_model(probe: false)
       metrics = @metrics.snapshot
+      # One resolve for the model's fields; nil when it doesn't resolve (the
+      # Bridge's /state and reset frames rely on this never raising): those
+      # fields are nil then, as their own rescues always gave.
+      model = model_setting(nil) { |resolved| resolved }
       {
         status: @session&.status,
         message_count: (@session&.messages || []).size,
@@ -1312,12 +1313,9 @@ module Samagotchi
         model_name: effective_model_ref,
         served_model: served_pair[0],
         served_model_for: served_pair[1],
-        served_expected_by: served_expected_by(served_pair[0]),
-        context_status: @last_context_status&.dup || saved_context_status(metrics[:context]),
-        llm_context: llm_context_summary,
-        thinking: thinking_explained&.summary,
-        reasoning_history: reasoning_history_explained&.summary,
-        toolkit: toolkit_summary,
+        served_expected_by: model&.served_expected_by(served_pair[0]),
+        context_status: @last_context_status&.dup || saved_context_status(metrics[:context], model: model),
+        **setting_chips(SessionSetting::ALL, model),
         recap_enabled: !@recap.nil?,
         recap_min_user_turns: @recap&.min_user_turns,
         recap_inactivity_seconds: @recap&.inactivity&.to_i
@@ -1673,15 +1671,17 @@ module Samagotchi
     # the chat loop's leaves out the raw-prompt tool text, since its tools go
     # as schemas. Built once per loop (and again after a model switch) so the
     # prompt prefix, and the server's KV cache for it, stay stable.
-    # @param target [HostRegistry::ModelTarget, nil]
+    # @param model [EffectiveModel, nil]
     # @return [String]
     # The native prompt depends on the thinking level too (Gemma's token,
-    # Qwen's turn preamble): a level change builds it again.
-    def system_prompt(target = nil)
-      target ||= @host_registry.resolve(@effective_model_name)
-      chat = target.entry.chat?
-      level = chat ? nil : thinking_level(target)
-      prompt = @prompt_builder.build(chat: chat, thinking: level, layers: llm_context_layers(target))
+    # Qwen's turn preamble): a level change builds it again. A build that
+    # misses the cache names the model and the level through its own
+    # lambdas (#model_identity, #turn_thinking), which resolve again.
+    def system_prompt(model = nil)
+      model ||= effective_model
+      chat = model.chat?
+      level = chat ? nil : thinking_level(model)
+      prompt = @prompt_builder.build(chat: chat, thinking: level, layers: model.llm_context_layers(llm_context_session_args))
       # The memory indexes this prompt holds: /stats, the snapshot, analytics.json.
       @metrics.memory_index = @prompt_builder.memory_index
       # The model notes it carries: the session records them (/stats, /model, the web).
@@ -1689,16 +1689,6 @@ module Samagotchi
       prompt
     end
 
-    # The LLM context layers +target+'s turns run under: the native prompt
-    # declares the tools they add (forget_outputs under forget), so a
-    # model switch may change the tool list. [] under none.
-    def llm_context_layers(target)
-      LLMContextStrategy.resolve(target, names: model_lookup_names(target), **llm_context_session_args).active_layers
-    rescue StandardError
-      []
-    end
-    private :llm_context_layers
-
     # The base prompt (specs, plugins' declarations).
     def assist_system_prompt(chat: false, thinking: nil)
       @prompt_builder.base(chat: chat, thinking: thinking)
@@ -2029,14 +2019,16 @@ module Samagotchi
     # sampling and thinking, the thinking resolved before the hooks run.
     # The model name is added in #generate, after the hooks that may switch
     # the model.
+    # One resolve for all of them: nothing runs between them that could
+    # change what a resolve gives.
     def turn_settings(session)
-      vision = turn_vision(session)
-      sampling = turn_sampling
-      thinking_target = @host_registry.resolve(@effective_model_name)
-      @turn_thinking = [thinking_level(thinking_target), thinking_target]
-      announce_thinking_level(*@turn_thinking)
-      LLM::TurnSettings.new(vision: vision, sampling: sampling, thinking: @turn_thinking.first,
-                            reasoning_history: reasoning_history_level(thinking_target), model_name: nil,
+      model = effective_model
+      vision = turn_vision(session, model)
+      sampling = model.sampling
+      level = thinking_level(model)
+      @thinking_notices.turn_started(level, model.target)
+      LLM::TurnSettings.new(vision: vision, sampling: sampling, thinking: level,
+                            reasoning_history: reasoning_history_level(model), model_name: nil,
                             window_setting: nil, llm_context: nil, price: nil)
     end
     private :turn_settings
@@ -2058,12 +2050,12 @@ module Samagotchi
     def warm_up_next_turn(turn, result)
       return if result.canceled? || result.resumable?
 
-      target = @host_registry.resolve(@effective_model_name)
-      client = target.client
-      return unless warmup_target?(target, client)
+      model = effective_model
+      client = model.client
+      return unless warmup_target?(model, client)
       return if reminders_due? || @turn_state.carried_steers? || @next_turn_waiting&.call
 
-      messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: system_prompt(target) })
+      messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: system_prompt(model) })
       # Under the next turn's strategy (a /model switch may have changed it);
       # the last turn's when it can't be resolved.
       prompt, images = @kernel.warmup_prompt(messages, llm_context: turn_llm_context || @kernel.turn_settings&.llm_context)
@@ -2080,8 +2072,8 @@ module Samagotchi
     # Never a paid or remote host (cache.warmup auto means local only), nor
     # the chat loop (Splash keeps its own cache; llama.cpp's chat path is
     # not measured), nor a non-llama.cpp transport.
-    def warmup_target?(target, client)
-      return false if target.entry.chat? || target.entry.remote?
+    def warmup_target?(model, client)
+      return false if model.chat? || model.entry.remote?
       return false unless client.respond_to?(:warm_up) && client.respond_to?(:transport) && client.transport.native?
 
       PromptWarmup.enabled?
@@ -2122,16 +2114,19 @@ module Samagotchi
 
     # Ask the effective model's backend.
     def generate(turn, max_iterations:, max_tool_output_chars:, pending_input:)
-      sync_kernel_client!
+      # One resolve for the request: nothing runs between these reads that
+      # could change what a resolve gives (the hooks ran before).
+      model = effective_model
+      sync_kernel_client!(model)
       # Route model name as bare (without host prefix) to the transport;
       # host selection already done via active client.
-      bare_for_backend = bare_model_name(@effective_model_name)
+      bare_for_backend = bare_model_name(model.name)
       # The turn's settings, set once here. The chat loop dispatches tools
       # through the kernel without its #run: tag those dumps with this
       # turn's model, not the last native one.
-      explained = llm_context_explained
-      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: turn_window_setting,
-                                                 llm_context: explained&.resolved, price: turn_price)
+      explained = model.llm_context_explained(llm_context_session_args)
+      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: model.window_setting,
+                                                 llm_context: explained&.resolved, price: model.price)
       log_llm_context(explained)
 
       turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
@@ -2139,7 +2134,7 @@ module Samagotchi
       # end keeps it, so a Continue resumes this run.
       run_start = turn.messages.length
       reasoning_since = resumed_run_start(turn, run_start)
-      result = backend.complete(
+      result = backend(model).complete(
         messages: turn.messages,
         max_iterations: turn.limit,
         on_stream_event: build_stream_event_handler(turn.on_event, cancel_controller: turn.controller),
@@ -2353,164 +2348,30 @@ module Samagotchi
 
     # The turn's VisionContext: the session's images folder, and whether the
     # effective model can see images, asked only when a request carries one.
-    def turn_vision(session)
-      target = @host_registry.resolve(@effective_model_name)
+    def turn_vision(session, model = effective_model)
       VisionContext.new(session_dir: Session.session_dir(session.id, state_dir: session_state_dir),
-                        capability: lambda {
-                          VisionSupport.for(target, profile: profile, adapter: vision_adapter(target), names: model_lookup_names(target))
-                        })
+                        capability: -> { model.vision_support(profile) })
     end
 
     # The effective model's request parameters (hosts: and models:
     # sampling), read per turn: /model can change the model between turns.
-    def turn_sampling
-      target = @host_registry.resolve(@effective_model_name)
-      SamplingSettings.for(target, names: model_lookup_names(target))
-    rescue StandardError
-      SamplingSettings::EMPTY
-    end
+    def turn_sampling = model_setting(SamplingSettings::EMPTY, &:sampling)
 
     # The effective model's thinking level (Thinking.resolve), read each turn.
-    def turn_thinking
-      thinking_level(@host_registry.resolve(@effective_model_name))
-    rescue StandardError
-      Thinking::DEFAULT
-    end
-
-    # An effort on a native host, which has no knob for it: said once per
-    # session and host.
-    def announce_thinking_level(level, target)
-      return if target.entry.chat? || Thinking.native(level, profile).honoured
-
-      thinking_notice_once(:unsupported, target, :info,
-                           "#{level} isn't supported by native #{profile.name} on #{target.entry.name}; " \
-                           "thinking stays as the model has it")
-    rescue StandardError
-      nil
-    end
-
-    # An effort on a llama.cpp chat host whose chat template takes none
-    # (its /props says so): said once per session and host, as for a native
-    # host. Read from the /props answer the turn's window probe left in the
-    # cache, so it asks the server nothing.
-    def announce_effort_ignored
-      level, target = @turn_thinking
-      return unless target&.entry&.chat? && Thinking::EFFORTS.include?(level)
-
-      client = target.client
-      props = client.cached_server_props(model: target.bare_model)
-      return unless Thinking.effort_ignored?(level, props)
-
-      thinking_notice_once(:unsupported, target, :info,
-                           "#{level} isn't supported by #{target.bare_model}'s chat template on #{target.entry.name} " \
-                           "(/props: supports_reasoning_effort false); thinking stays as the model has it")
-    rescue StandardError
-      nil
-    end
-
-    # Whether this generation's thinking lane said anything: nil while it
-    # streamed none, false while only whitespace (Gemma 4's empty thought
-    # with thinking off), true once a real thought came.
-    def note_generation_thought(thinking)
-      return if thinking.empty?
-
-      @generation_thought ||= thinking.match?(/\S/)
-    end
-
-    # Thinking off, and the model thought anyway: logged each time, said
-    # once per session and host. A thinking lane of whitespace alone is no
-    # thought.
-    def check_thinking_honoured(event)
-      level, target = @turn_thinking
-      chars = event[:thinking_chars].to_i
-      return unless level == :off && chars.positive? && target
-      return if @generation_thought == false
-
-      Log.warn(:model, "thinking_not_honoured", level: level, host: target.entry.name, model: target.bare_model, chars: chars)
-      thinking_notice_once(:not_honoured, target, :warn,
-                           "off wasn't honoured by #{target.bare_model} on #{target.entry.name} " \
-                           "(#{chars} chars of thinking); a sampling: override on the host or model may turn it off " \
-                           "(see Thinking in docs/configuration.md)")
-    rescue StandardError
-      nil
-    end
+    def turn_thinking = model_setting(Thinking::DEFAULT) { |model| thinking_level(model) }
 
-    # The host refused the level's request fields (gpt-oss can't turn
-    # thinking off) and the chat loop sent the request without them: said
-    # once per session and host, standing in for the not-honoured notice.
-    def thinking_refused(event)
-      _level, target = @turn_thinking
-      return unless target
-
-      Log.warn(:model, "thinking_refused", level: event[:level], host: target.entry.name, model: event[:model],
-                                           detail: event[:detail])
-      (@thinking_notices ||= Set.new) << [@session&.id, target.entry.name, :not_honoured]
-      thinking_notice_once(:refused, target, :warn,
-                           "#{target.entry.name} refused thinking: #{event[:level]} for #{event[:model]} (#{event[:detail]}); " \
-                           "sent without it, so thinking stays as the model has it")
-    rescue StandardError
-      nil
-    end
-
-    # The host refused a sampling field (the empty-answer retry's
-    # temperature on a model that takes none) and the chat loop asked again
-    # without them, as it will for the model from now on: a log line.
-    def sampling_refused(event)
-      Log.info(:model, "sampling_refused", model: event[:model], detail: event[:detail])
-    rescue StandardError
-      nil
-    end
-
-    # The host refused the model's reasoning sent back (reasoning_history)
-    # and the chat loop asked the step again without it, as it will from
-    # now on: logged, and said once per session and host.
-    def reasoning_history_refused(event)
-      _level, target = @turn_thinking
-      return unless target
-
-      Log.warn(:model, "reasoning_history_refused", level: event[:level], host: target.entry.name, model: event[:model],
-                                                    detail: event[:detail])
-      return unless (@thinking_notices ||= Set.new).add?([@session&.id, target.entry.name, :reasoning_history_refused])
-
-      hook_notify("#{target.entry.name} refused reasoning sent back (reasoning_history: #{event[:level]}) for " \
-                  "#{event[:model]} (#{event[:detail]}); sent without it from now on", :warn, "reasoning history")
-    rescue StandardError
-      nil
-    end
-
-    def thinking_notice_once(kind, target, level, text)
-      key = [@session&.id, target.entry.name, kind]
-      return unless (@thinking_notices ||= Set.new).add?(key)
-
-      hook_notify(text, level, "thinking")
-    end
-
-    # +target+'s ReasoningHistory level, the session's own first; the
+    # +model+'s ReasoningHistory level, the session's own first; the
     # default when it can't be resolved.
-    def reasoning_history_level(target)
-      ReasoningHistory.resolve(target, names: model_lookup_names(target), session: reasoning_history_override).first
-    rescue StandardError
-      ReasoningHistory::DEFAULT
-    end
-
-    # +target+'s thinking level (Thinking.resolve), the session's own first.
-    def thinking_level(target)
-      Thinking.resolve(target, names: model_lookup_names(target), session: thinking_override).first
-    rescue StandardError
-      Thinking::DEFAULT
-    end
+    def reasoning_history_level(model) = model.reasoning_history(own: reasoning_history_override)
 
-    def vision_adapter(target)
-      target.entry.chat? ? @host_registry.adapter_for(target.entry) : nil
-    rescue StandardError
-      nil
-    end
+    # +model+'s thinking level (Thinking.resolve), the session's own first.
+    def thinking_level(model) = model.thinking(own: thinking_override)
 
     # A model known not to see images fails a turn with images up front.
     def refuse_images!(vision)
       return if vision.sendable?
 
-      host = @host_registry.resolve(@effective_model_name).entry.name
+      host = effective_model.host_name
       raise LLM::VisionUnsupported.new("#{host}: #{vision.refusal_reason}", host: host)
     end
 
@@ -2605,14 +2466,14 @@ module Samagotchi
       session.messages = messages
     end
 
-    # Pick the loop for a target; the chat loop is pointed at the target
-    # host's adapter (one per host, kept for its cached model list).
-    def backend_for(target)
-      return @native_backend unless target.entry.chat?
+    # Pick the loop for +model+ (EffectiveModel); the chat loop is pointed
+    # at its host's adapter (one per host, kept for its cached model list).
+    def backend_for(model)
+      return @native_backend unless model.chat?
 
       @chat_backend_mutex.synchronize do
         @chat_backend ||= LLM::ChatLoop.new(kernel: @kernel, stable_length: ->(text) { @prompt_builder.stable_length(text) })
-        @chat_backend.adapter = @host_registry.adapter_for(target.entry)
+        @chat_backend.adapter = @host_registry.adapter_for(model.entry)
         @chat_backend.session_id = session&.id
         @chat_backend
       end
@@ -2640,8 +2501,6 @@ module Samagotchi
       # start) waits for the first turn, beside the load warnings: no UI
       # is there yet, and the Engine isn't built.
       @extension_load.load_plugins(registries, failures: @plugin_failures)
-      # Declared once, from what the sources published while they loaded.
-      @tool_index.declare(@tools, failures: @plugin_failures)
     end
 
     # Keep a plugin's new tool set (chi.replace_tools, from any thread)
@@ -2690,6 +2549,7 @@ module Samagotchi
         state_dir: -> { session_state_dir },
         can_stage: -> { !turn_running? && !history? },
         reset_prompt: -> { @prompt_builder&.reset! },
+        refresh_index: -> { @tool_index.refresh! },
         emit: ->(sink, event) { emit_event(sink, event) },
         notify: ->(text, level, source, extra:) { hook_notify(text, level, source, extra: extra) }
       )
@@ -2793,7 +2653,7 @@ module Samagotchi
     # and bare model name, as a turn resolves them.
     # @return [IdleTarget]
     def session_model_recap_target
-      IdleTarget.of_model(@host_registry, @effective_model_name)
+      IdleTarget.of_model(@host_registry, effective_model_name)
     end
 
     # Build the idle reminders job. Always created (reminders are opt-in
@@ -2840,29 +2700,26 @@ module Samagotchi
         @steer_cut.observe(event, progress)
         case event[:type]
         when :generation_started
-          @generation_thought = nil
+          @thinking_notices.generation_started
           watch&.started(event[:iteration])
         when :generation_retrying
           # A dropped stream's step asked again: it streams from the start.
           if event[:restarted]
-            @generation_thought = nil
+            @thinking_notices.generation_started
             watch&.started(event[:iteration], restarted: true)
           end
-        when :generation_chunk then note_generation_thought(progress[:thinking])
+        when :generation_chunk then @thinking_notices.note_thought(progress[:thinking])
         end
         # The chat loop asked again without the thinking fields or the
         # reasoning sent back: a notice, not an event of its own.
-        next thinking_refused(event) if event[:type] == :thinking_refused
-        next reasoning_history_refused(event) if event[:type] == :reasoning_history_refused
-        next sampling_refused(event) if event[:type] == :sampling_refused
+        next @thinking_notices.thinking_refused(event) if event[:type] == :thinking_refused
+        next @thinking_notices.reasoning_history_refused(event) if event[:type] == :reasoning_history_refused
+        next @thinking_notices.sampling_refused(event) if event[:type] == :sampling_refused
 
         event = with_generation_report(event) if event[:type] == :generation_completed
         emit_event(on_event, event)
         watch.feed(**progress) if watch && progress
-        if event[:type] == :generation_completed
-          check_thinking_honoured(event)
-          announce_effort_ignored
-        end
+        @thinking_notices.generation_completed(event) if event[:type] == :generation_completed
       end
     end
 
@@ -2919,38 +2776,13 @@ module Samagotchi
       emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names, read_names: read_names })
     end
 
-    # The window as the target's loop would see it (see ChatLoop#context_window:
-    # a remote chat host has no /props, only its model list).
-    def current_context_window(target)
-      client = target.client
-      adapter = nil
-      if target.entry.chat?
-        adapter = @host_registry.adapter_for(target.entry)
-        client = nil if adapter.remote?
-      end
-      ContextWindow.resolve(client: client, model: target.bare_model, adapter: adapter,
-                            setting: ContextWindow.setting(target, names: model_lookup_names(target)))
-    rescue StandardError
-      nil
-    end
-
     # The effective model's models:/hosts: window_tokens, read per turn
     # (after the hooks that may switch the model).
-    def turn_window_setting
-      target = @host_registry.resolve(@effective_model_name)
-      ContextWindow.setting(target, names: model_lookup_names(target))
-    rescue StandardError
-      nil
-    end
+    def turn_window_setting = model_setting(nil, &:window_setting)
 
     # The effective model's price on its host (hosts.<name>.models.<id>.price),
     # by the requested id, never the served one; read per turn as the window is.
-    def turn_price
-      target = @host_registry.resolve(@effective_model_name)
-      target.entry.models&.dig(target.bare_model.to_s.strip.downcase)&.price
-    rescue StandardError
-      nil
-    end
+    def turn_price = model_setting(nil, &:price)
 
     # The LLM context strategy the next turn runs under: the session's own
     # (Session#llm_context), else the effective model's (models:/hosts:
@@ -2964,57 +2796,82 @@ module Samagotchi
     private :llm_context_session_args
 
     # See #served_model. A report for another name (before a /model switch)
-    # doesn't count. Without a target, no probe. A remote chat host has no
-    # /props: nil until a turn.
-    def served_model_for(snapshot, target: nil)
-      asked = bare_model_name(@effective_model_name)
+    # doesn't count. Without a model (EffectiveModel), no probe. A remote
+    # chat host has no /props: nil until a turn. The name asked is never
+    # resolved (HostRegistry#bare_name), so it holds on a broken resolve.
+    def served_model_for(snapshot, model: nil)
+      asked = bare_model_name(model ? model.name : effective_model_name)
       return [snapshot[:served_model], asked] if snapshot[:served_model] && snapshot[:served_model_for] == asked
-      return [nil, nil] unless target
+      return [nil, nil] unless model
 
-      client = target.client
-      if target.entry.chat?
-        adapter = @host_registry.adapter_for(target.entry)
-        return [nil, nil] if adapter.remote?
-      end
-      served = ServedModel.from_props(client.server_props(model: target.bare_model))
-      served ? [served, asked] : [nil, nil]
+      model.served_from_props(asked)
+    # Only bare_model_name and the snapshot lookup are left to fail here:
+    # the probe's failure is EffectiveModel#served_from_props's.
     rescue StandardError
       [nil, nil]
     end
 
-    # What a local native host's cached /props names, when it isn't the
-    # model asked for; nil for a chat or remote host, or before any probe.
-    def prompt_served_model(target)
-      entry = target.entry
-      return nil if entry.nil? || entry.chat? || entry.remote? || !target.client.respond_to?(:cached_server_props)
+    # The window as +model+'s loop would see it (EffectiveModel#context_window).
+    def current_context_window(model) = model.context_window
 
-      served = ServedModel.from_props(target.client.cached_server_props(model: target.bare_model))
-      served if ServedModel.differs?(target.bare_model, served)
-    rescue StandardError
-      nil
+    # +settings+' chips (SessionSetting), the model's from +model+ (nil
+    # when it doesn't resolve): /stats, the session state, a :command_ran.
+    def setting_chips(settings, model)
+      settings.to_h { |setting| [setting.key, setting.model? ? setting.chip_for(model, @session) : toolkit_summary] }
     end
 
-    # ── Prompt profile ─────────────────────────────────────────────────────────
+    # The effective model now (EffectiveModel.of): resolved on each call,
+    # never kept (config.yml, a model listing and another process's saved
+    # lists all move a resolve). Raises as HostRegistry#resolve does.
+    # @return [EffectiveModel]
+    def effective_model(choice = @model_choice) = EffectiveModel.of(@host_registry, choice)
 
-    def resolve_profile
-      if @given_profile
-        return ModelProfile::Resolution.new(profile: @given_profile, source: :given, detail: nil, retry: false)
+    # The block's answer for the effective model, or +fallback+ when the
+    # model doesn't resolve: the readers whose rescue always covered the
+    # resolve too. Each setting's own failure is the EffectiveModel's.
+    def model_setting(fallback)
+      # One read: the log line names the model that failed, even if a
+      # /model switched it meanwhile.
+      choice = @model_choice
+      model = begin
+        effective_model(choice)
+      rescue StandardError => e
+        return EffectiveModel::Unresolved.fallback(:effective_model_unresolved, choice.name, e, fallback)
       end
+      yield model
+    end
 
-      target = @host_registry.resolve(@effective_model_name)
-      ModelProfile.resolve(names: model_lookup_names(target), entry: target.entry, client: target.client, bare_model: target.bare_model)
+    # ── Prompt profile ─────────────────────────────────────────────────────────
+
+    # +choice+'s profile (ModelProfile.resolve; may probe /props), or the
+    # one given to .new.
+    def resolve_profile(choice)
+      given = @given_profile
+      return ModelProfile::Resolution.new(profile: given, source: :given, detail: nil, retry: false) if given
+
+      EffectiveModel.of(@host_registry, choice).profile_resolution
     end
 
-    # The names a models: entry may be under (HostRegistry#lookup_names):
-    # the model as typed at start or at the last /model, and what it became.
-    def model_lookup_names(target)
-      @host_registry.lookup_names(@typed_model_name, resolved: @effective_model_name, target: target)
+    # Keeps +resolution+ as +choice+'s and applies it, unless the model
+    # switched while it was resolved (a /stats on a Bridge thread probing
+    # as a /model ran): then it is only returned, and the new model's is
+    # resolved on its first need.
+    # @return [ModelProfile::Resolution]
+    def store_profile(choice, resolution)
+      @profile_mutex.synchronize do
+        return resolution unless @model_choice.equal?(choice)
+
+        apply_profile(resolution)
+        @profile_resolution = [choice, resolution]
+      end
+      resolution
     end
 
     # Everything that holds a profile follows the resolution: the kernel's
     # prompt format and parser, and the system prompts built for the old one.
     def apply_profile(resolution)
-      @prompt_builder&.reset! if @profile_resolution && @profile_resolution.profile.name != resolution.profile.name
+      kept = @profile_resolution&.last
+      @prompt_builder&.reset! if kept && kept.profile.name != resolution.profile.name
       @kernel.use_profile!(resolution)
       resolution
     end
@@ -3023,11 +2880,10 @@ module Samagotchi
     # server probe failed (unreachable, or 503 while loading a model). A
     # profile that changes here drops the cached system prompts.
     def refresh_profile!
-      if @profile_resolution&.retry?
-        @profile_resolution = apply_profile(resolve_profile)
-      else
-        profile_resolution
-      end
+      choice, kept = @profile_resolution
+      return profile_resolution unless choice.equal?(@model_choice) && kept.retry?
+
+      store_profile(choice, resolve_profile(choice))
     end
   end
 end