samagotchi 0.109.0 → 0.111.0

data/lib/samagotchi/engine.rb

@@ -13,6 +13,7 @@ require_relative "context_note"
 require_relative "context_status"
 require_relative "steer"
 require_relative "turn_note"
+require_relative "turn_endings"
 require_relative "turn_origin"
 require_relative "model_profile"
 require_relative "effective_model"
@@ -53,6 +54,7 @@ require_relative "recap_setup"
 require_relative "idle_reminders"
 require_relative "idle_scheduler"
 require_relative "hooks"
+require_relative "event_fanout"
 require_relative "event_routes"
 require_relative "hook_routes"
 require_relative "guardrails"
@@ -65,7 +67,9 @@ require_relative "used_memories"
 require_relative "turn_state"
 require_relative "steer_cut"
 require_relative "engine_peers"
+require_relative "engine_snapshots"
 require_relative "bundle_needs"
+require_relative "model_binding"
 require_relative "model_overlay"
 require_relative "model_notes"
 require_relative "prompt_note"
@@ -78,6 +82,7 @@ require_relative "thinking"
 require_relative "reasoning_history"
 require_relative "answer_display"
 require_relative "answer_refs"
+require_relative "message_time"
 require_relative "edit_preview"
 require_relative "question_desk"
 require_relative "question_asked"
@@ -141,6 +146,12 @@ module Samagotchi
       # A message for the running turn cutting its generation.
       @steer_cut = SteerCut.new(clock: -> { monotonic_now }, controller: -> { active_cancel_controller },
                                 cut_after: -> { steer_cut_after })
+      # How an event reaches the turn's sink and the observers, and the
+      # stream handler. Built early: the question desk's and the init tasks'
+      # emit go through it.
+      @event_fanout = build_event_fanout
+      # What each turn ending keeps and announces (one lookup).
+      @turn_endings = build_turn_endings
       @scratch = scratch
       @no_interrupt = no_interrupt
       @chat_backend = nil
@@ -151,22 +162,22 @@ 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?
-      # Guards the model choice and the profile cached for it (#store_profile).
-      @profile_mutex = Mutex.new
+      # The model choice and the profile resolved for it, under one mutex.
+      # 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.
       typed = model_typed.to_s.strip
-      @model_choice = ModelChoice.new(name: @default_model_name, typed: typed.empty? ? @default_model_name : typed)
+      @model_binding = build_model_binding(
+        ModelChoice.new(name: @default_model_name, typed: typed.empty? ? @default_model_name : typed),
+        profile ? ModelProfile.normalize(profile) : nil
+      )
       # The session's settings on its effective model (SessionModelSettings),
       # read at use: /model moves the choice, #session= the session.
-      @model_settings = SessionModelSettings.new(registry: @host_registry, choice: -> { @model_choice },
+      @model_settings = SessionModelSettings.new(registry: @host_registry, choice: -> { @model_binding.choice },
                                                  session: -> { @session })
       # An injected client (specs) stands in for every host's client.
       @host_registry.client_override = client if 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
-      @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.
       begin
@@ -253,6 +264,9 @@ module Samagotchi
       # the single background thread and isolates per-job failures.
       @idle_scheduler = build_idle_scheduler
       subscribe_session_observers
+      # The UIs' read model (/state, /stats). Built last: nothing calls a
+      # snapshot while the Engine is built.
+      @engine_snapshots = build_engine_snapshots
     end
 
     # ── initialize's collaborators ──────────────────────────────────────────
@@ -337,7 +351,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: @model_binding.given_profile, model_name: effective_model_name,
                                          hooks: @hooks, reminder_store: @reminder_store, tools: @tools)
       @kernel.reminder_store = @reminder_store
       @kernel.hooks = @hooks
@@ -382,7 +396,7 @@ module Samagotchi
         hooks: -> { @hooks },
         tools: -> { @tools },
         session: -> { @session },
-        model_key: -> { @model_key },
+        model_key: -> { @model_binding.model_key },
         model_name: -> { guardrail_model_name },
         cancelled: -> { !!active_cancel_controller&.cancelled? },
         # An approval of the model's call: :question_asked first (QuestionAsked).
@@ -392,6 +406,74 @@ module Samagotchi
     end
     private :build_guardrail_wiring
 
+    # The event fan-out and the stream handler (see #initialize for when).
+    def build_event_fanout
+      EventFanout.new(
+        observer: -> { @session_observer },
+        used_memories: -> { @used_memories },
+        muted: -> { @muted_memory_names },
+        steer_cut: -> { @steer_cut },
+        thinking_notices: -> { @thinking_notices },
+        metrics: -> { @metrics },
+        hooks: -> { @hooks },
+        kernel: -> { @kernel },
+        model_settings: -> { @model_settings },
+        session: -> { @session },
+        live_conversation: -> { live_conversation },
+        used_memory_names: -> { used_memory_names },
+        served_expected_by: ->(served) { served_expected_by(served) },
+        working_set_strategy: -> { working_set_strategy },
+        turn_running: -> { turn_running? },
+        announce_or_hold: ->(event) { announce_or_hold(event) }
+      )
+    end
+    private :build_event_fanout
+
+    # The snapshots the UIs read (see #initialize for when).
+    def build_engine_snapshots
+      EngineSnapshots.new(
+        session: -> { @session },
+        metrics: -> { @metrics },
+        observer: -> { @session_observer },
+        question_desk: -> { @question_desk },
+        used_memories: -> { @used_memories },
+        muted: -> { @muted_memory_names },
+        prompt_builder: -> { @prompt_builder },
+        participants: -> { @participants },
+        participants_watch: -> { @participants_watch },
+        recap: -> { @recap },
+        last_context_status: -> { @last_context_status },
+        model_settings: -> { @model_settings },
+        effective_model: -> { effective_model },
+        effective_model_name: -> { effective_model_name },
+        effective_model_ref: -> { effective_model_ref },
+        bare_model_name: ->(ref) { bare_model_name(ref) },
+        served_model: ->(probe:) { served_model(probe: probe) },
+        prompt_notes: -> { prompt_notes },
+        preloaded: -> { preloaded_memory_names },
+        saved_context_status: ->(context, **opts) { saved_context_status(context, **opts) },
+        context_window: ->(model) { current_context_window(model) },
+        profile_resolution: -> { profile_resolution },
+        toolkit_summary: -> { toolkit_summary },
+        toolkit_explained: -> { toolkit_explained }
+      )
+    end
+    private :build_engine_snapshots
+
+    # The model choice and its prompt profile (see #initialize for when).
+    def build_model_binding(choice, given_profile)
+      ModelBinding.new(choice: choice, given_profile: given_profile, registry: @host_registry,
+                       kernel: -> { @kernel }, prompt_builder: -> { @prompt_builder },
+                       bare_name: ->(name) { bare_model_name(name) })
+    end
+    private :build_model_binding
+
+    # The turn endings' builders (see #initialize for when).
+    def build_turn_endings
+      TurnEndings.new(failure_summary: ->(error) { failure_summary(error) })
+    end
+    private :build_turn_endings
+
     # The question flow (see #initialize for when).
     def build_question_desk
       QuestionDesk.new(
@@ -585,9 +667,12 @@ module Samagotchi
 
     # Emit a :recap_ready event (additive slot) carrying the generated recap
     # and the generation id an observer uses to reject an invalidated recap.
-    # +covered+ counts the session messages it summarizes.
-    def emit_recap(recap:, generation:, covered: nil)
-      @session_observer.notify(type: :recap_ready, recap: recap, generation: generation, covered: covered)
+    # +covered+ counts the session messages it summarizes; +created_at+ is
+    # the saved recap's (UTC ISO; the UIs show its local time).
+    def emit_recap(recap:, generation:, covered: nil, created_at: nil)
+      event = { type: :recap_ready, recap: recap, generation: generation, covered: covered }
+      event[:created_at] = created_at if created_at
+      @session_observer.notify(event)
     end
 
     # Count one side request (a recap, a plugin's ctx.ask_model: IdleClient's
@@ -639,10 +724,10 @@ module Samagotchi
     attr_reader :metrics
 
     # The model as given (maybe an alias; HostRegistry#resolve applies it).
-    def effective_model_name = @model_choice.name
+    def effective_model_name = @model_binding.choice.name
 
     # The model as typed at start or at the last /model.
-    def typed_model_name = @model_choice.typed
+    def typed_model_name = @model_binding.choice.typed
 
     # The resolved ref a session stores for the effective model (ModelRef#ref:
     # the alias applied, "host:id" when it names a host).
@@ -658,15 +743,15 @@ module Samagotchi
       model = effective_model
       entry = model.entry
       host = entry && "host #{entry.name}, #{entry.url || "#{entry.host}:#{entry.port}"}"
-      SystemPrompt::ModelIdentity.new(ref: model.ref, host: host, key: @model_key,
-                                      served: model.prompt_served, fallback_key: @fallback_model_key)
+      SystemPrompt::ModelIdentity.new(ref: model.ref, host: host, key: @model_binding.model_key,
+                                      served: model.prompt_served, fallback_key: @model_binding.fallback_model_key)
     end
 
     # The model notes for the effective model (ModelNotes): matched on its
     # bare id and key, the session's mutes left out.
     # @return [Array<ModelNotes::Note>]
     def model_notes
-      ModelNotes.for(name: guardrail_model_name, key: @model_key, fallback_key: @fallback_model_key,
+      ModelNotes.for(name: guardrail_model_name, key: @model_binding.model_key, fallback_key: @model_binding.fallback_model_key,
                      muted: @muted_memory_names)
     end
 
@@ -729,28 +814,17 @@ module Samagotchi
     # The effective model's key (ModelOverlay.key_for its bare name): memory
     # overlays, guardrail rules' models:.
     # @return [String, nil]
-    attr_reader :model_key
+    def model_key = @model_binding.model_key
 
     # The prompt profile for the effective model (see #profile_resolution).
     # @return [ModelProfile]
     def profile = profile_resolution.profile
 
-    # Which profile the effective model gets and where that came from
-    # (ModelProfile.resolve: --profile/env, models:, hosts.<name>.profile,
-    # the server's chat template, the name, qwen36). Resolved on first need
-    # 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).
+    # Which profile the effective model gets and where that came from,
+    # kept with the model choice it was resolved for
+    # (ModelBinding#profile_resolution).
     # @return [ModelProfile::Resolution]
-    def profile_resolution
-      choice = @model_choice
-      cached = @profile_resolution
-      return cached.last if cached&.first.equal?(choice)
-
-      store_profile(choice, resolve_profile(choice))
-    end
+    def profile_resolution = @model_binding.profile_resolution
     attr_reader :default_model_name, :host_registry, :client
 
     # @return [Commands::Registry] the commands this session runs: the
@@ -765,17 +839,8 @@ module Samagotchi
       @host_registry.bare_name(full_ref)
     end
 
-    # The memory overlay key follows the model sent (ModelOverlay.key_for
-    # its id). A model typed as an alias used to key overlays by the alias
-    # (before aliases were applied there): that key is read when the
-    # target's overlay is missing (KernelLoop#sync_model_key!).
-    def sync_model_key!
-      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
+    # The memory overlay keys follow the model sent (ModelBinding#sync_model_key!).
+    def sync_model_key! = @model_binding.sync_model_key!
     private :sync_model_key!
 
     # The effective model's bare name for the guardrails' models: rules;
@@ -1085,13 +1150,7 @@ module Samagotchi
       # 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)
       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
+      @model_binding.switch!(choice)
       sync_model_key!
       @prompt_builder.reset!
       # The notes the new model's prompt loads at its next build, so /model,
@@ -1192,53 +1251,10 @@ module Samagotchi
     # @return [ReminderStore] the reminder store for inspection
     attr_reader :reminder_store
 
-    # The metrics for /stats. Before the first generation reports them, the
-    # context window, the served model and (on a native host) the prompt
-    # profile come from the effective model's server, so this may make one
-    # short /props GET; the cheap #session_state_snapshot never does.
-    # price_host: the effective model's host, whose hosts.<name>.models
-    # prices the cost estimate names. kit_prompt: the next turn's kit
-    # prompt text ({kit:, tokens:}), only when its toolkit has one.
-    # settings: the session's own settings ({"recap.enabled" => false}),
-    # only when it has some.
+    # The metrics for /stats, which may make one short /props GET
+    # (EngineSnapshots#stats_snapshot).
     # @return [Hash] @metrics.snapshot, filled in
-    def stats_snapshot
-      snapshot = @metrics.snapshot
-      # 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: 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)
-      kit_prompt = kit_prompt_stats
-      snapshot = snapshot.merge(kit_prompt: kit_prompt) if kit_prompt
-      # Each participant's spend under their name (participants.json's).
-      if (spend = snapshot[:spend_by_author])
-        named = spend.to_h { |author, row| [author, row.merge(name: @participants.name_for(author, session: @session))] }
-        snapshot = snapshot.merge(spend_by_author: named)
-      end
-      # The session's own settings (chi --set), as --set names them.
-      settings = @session&.settings&.flat || {}
-      snapshot = snapshot.merge(settings: settings) unless settings.empty?
-      unless snapshot.dig(:context, :window_tokens)
-        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 model.chat?
-
-      unless snapshot[:profile]
-        resolution = profile_resolution
-        snapshot = snapshot.merge(profile: resolution.profile.name, profile_source: resolution.label)
-      end
-      snapshot
-    end
+    def stats_snapshot = @engine_snapshots.stats_snapshot
 
     # ── The session's model settings (SessionModelSettings) ──────────────────
 
@@ -1309,67 +1325,14 @@ module Samagotchi
     # else [nil, nil].
     # @return [Array(String, String), Array(nil, nil)]
     def served_model(probe: true)
-      served_model_for(@metrics.served_report, model: probe ? effective_model : nil)
+      @engine_snapshots.served_model_for(@metrics.served_report, model: probe ? effective_model : nil)
     end
 
     # Read-only snapshot of the engine's view of the current session plus the
-    # live event sequence. Cheap primitive used by the bridge's reconnect-too-
-    # old reset marker and the GET /session/:id/state read surface. Orthogonal
-    # to the transport — safe to call before the first turn (nil session).
-    #
-    # @return [Hash] with keys:
-    #   :status        [String, nil] current session status
-    #   :message_count [Integer]   number of messages in the session
-    #   :last_prompt   [String, nil] the last user prompt (empty string if none)
-    #   :event_seq     [Integer]   @session_observer.event_count
-    #   :metrics       [Hash]      @metrics.snapshot (per-session analytics)
-    #   :pending_question [Hash, nil] the pending question (PendingQuestion#to_h)
-    #   :used_memory_names [Array<String>] deduped memory names active this session
-    #   :prompt_notes  [Array<Hash>] the model notes the prompt carried
-    #     ({name:, scope:, chars:, digest:}; #prompt_notes)
-    #   :parent_id     [String, nil] the session that delegated this one
-    #   :model_name    [String]    the model turns run on now (after /model)
-    #   :served_model, :served_model_for [String, nil] what a generation of
-    #     that model reported serving, and the name asked (#served_model
-    #     without the probe)
-    #   :served_expected_by [String, nil] the host whose models: entry names
-    #     that served model under served: (#served_expected_by)
-    #   :recap_enabled [Boolean]   whether an idle recap is configured, with
-    #     :recap_min_user_turns and :recap_inactivity_seconds (nil when not)
-    #   :participants  [Array<Hash>] who is in the review now ({id:, name:,
-    #     kind:}; ParticipantsWatch#active), [] for nobody
-    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_settings.model_setting(nil) { |resolved| resolved }
-      {
-        status: @session&.status,
-        message_count: (@session&.messages || []).size,
-        last_prompt: @session&.last_prompt,
-        event_seq: @session_observer&.event_count,
-        metrics: metrics,
-        pending_question: @question_desk.pending&.to_h,
-        used_memory_names: @used_memories.names,
-        preloaded_memory_names: preloaded_memory_names,
-        muted_memory_names: @muted_memory_names.dup,
-        prompt_notes: prompt_notes.map(&:to_h),
-        parent_id: @session&.parent_id,
-        title: @session&.title,
-        model_name: effective_model_ref,
-        served_model: served_pair[0],
-        served_model_for: served_pair[1],
-        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,
-        participants: @participants_watch.active
-      }
-    end
+    # live event sequence; cheap, never probes, never raises
+    # (EngineSnapshots#session_state_snapshot has its keys).
+    # @return [Hash]
+    def session_state_snapshot = @engine_snapshots.session_state_snapshot
 
     # @return [Array<String>] deduped used memory names (thread-safe copy)
     def used_memory_names
@@ -1547,20 +1510,8 @@ module Samagotchi
       Steer.author_fields(author, @participants.name_for(author, session: session))
     end
 
-    # Why a turn stopped, from its end event (LastTurn::STOP_FACTS), for a
-    # parent agent's wait (ReplyWait): a provider error's kind and whether
-    # a retry may help, a cancel's reason and the hook that stopped it.
-    # Only what is known.
-    def stop_facts(event)
-      case event&.dig(:type)
-      # kept_steps: the turn's work stayed (a parent must not send the task again).
-      when :turn_failed
-        { error_kind: event[:error_kind]&.to_s, retryable: event[:retryable], kept_steps: event[:kept_steps] }
-      when :turn_canceled
-        { cancel_reason: event[:cancellation_reason]&.to_s, stopped_by: event[:cancelled_by]&.to_s }
-      else {}
-      end
-    end
+    # Why a turn stopped (TurnEndings#stop_facts).
+    def stop_facts(event) = @turn_endings.stop_facts(event)
     private :stop_facts
 
     # How every turn ends (completed, canceled, failed): the session gets
@@ -1997,8 +1948,10 @@ module Samagotchi
     # +resume_from+: where its reasoning starts, the run it resumes
     # (run_turn's resume_from:); nil for every other turn, and for a
     # Continue that starts cold (after a model change).
+    # +wall+: the wall time it started (MessageTime.now, once): the
+    # :turn_started event's at and its user message's (and reminders') stamp.
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id, :limit, :resumed, :resume_from) do
+                      :settings, :id, :limit, :resumed, :resume_from, :wall) do
       def resumed? = resumed ? true : false
 
       # The turn's boundary events carry the origin only when it names a
@@ -2009,6 +1962,9 @@ module Samagotchi
 
       # Seconds since the turn started (the cancel note says how long it ran).
       def elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+
+      # The wall time's stamp text (MessageTime::KEY).
+      def at = MessageTime.iso(wall)
     end
     private_constant :Turn
 
@@ -2141,7 +2097,7 @@ module Samagotchi
 
       Turn.new(session: session, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
                controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
-               id: id || SecureRandom.uuid)
+               id: id || SecureRandom.uuid, wall: MessageTime.now)
     end
     private :begin_turn
 
@@ -2155,7 +2111,7 @@ module Samagotchi
       image_refs, image_error = turn_image_refs(session, images)
       # Emit turn_started event
       bind_metrics(session)
-      turn_started = { type: :turn_started, session_id: session.id, prompt: turn.prompt, turn_id: turn.id }
+      turn_started = { type: :turn_started, session_id: session.id, prompt: turn.prompt, turn_id: turn.id, at: turn.at }
       turn_started[:continue] = true if turn.continue
       turn_started[:resumed] = true if turn.resumed?
       turn_started[:images] = image_refs unless image_refs.empty?
@@ -2316,16 +2272,18 @@ module Samagotchi
       # system prompt invalidates cache for the entire prefix.
       # Not into a participant's turn: the owner's reminders are the owner's,
       # and would be used up there under the review boundary.
-      due_reminders = turn.origin.participant? ? [] : @reminder_queue.inject!(turn.messages)
+      due_reminders = turn.origin.participant? ? [] : @reminder_queue.inject!(turn.messages, now: turn.wall)
       if due_reminders.any?
         emit_event(turn.on_event, {
           type: :reminder_injected,
-          reminders: due_reminders
+          reminders: due_reminders,
+          at: turn.at
         })
       end
 
       unless turn.continue
-        user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author) }
+        user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author),
+                         MessageTime::KEY => turn.at }
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
         session.last_prompt = turn.prompt
@@ -2475,89 +2433,17 @@ module Samagotchi
     end
     private :complete_turn
 
-    # What the session keeps of a turn that ended normally (nil: nothing to
-    # replace). Runs under the event lock: it also adds the turn's note to
-    # result.conversation, which the REPL keeps as-is.
-    # A turn that ran out of iterations ends at its tool results, so a
-    # continue resumes from them rather than after a made-up reply (and a
-    # step-limit Continue from its run's start: ModelResult#run_start).
-    def kept_messages(turn, result, seconds)
-      conversation = result.conversation if result.conversation.is_a?(Array)
-      # Nothing visible (no text) is a turn the model should know ended
-      # that way: the note, and nothing made up as its answer. The note's
-      # marker is for the UIs (the notice, and the empty steps after a
-      # reload); it goes on the result's conversation too (the REPL keeps it).
-      # A retry's nudge at the tail goes: this note says it all. An earlier
-      # turn's note stays: it says why that turn ended.
-      if result.empty_answer?
-        note = TurnNote.empty(retries: result.empty_retries, steps: result.empty_steps, refusal: result.refusal)
-        conversation&.replace(TurnNote.without_trailing_nudge(conversation))
-        saved = TurnNote.without_trailing_nudge(conversation || turn.session.messages)
-        conversation << note if conversation
-        saved + [note]
-      elsif result.canceled? && conversation
-        conversation << TurnNote.cancelled(result.cancellation_reason, seconds: seconds,
-                                                                      stopped_by: turn.controller.detail,
-                                                                      shown: TurnNote.interrupted_tail?(conversation),
-                                                                      running_tasks: Tools::TaskRuntime.running_created_in(conversation))
-      else
-        conversation
-      end
-    end
+    # What each turn ending keeps and announces is TurnEndings'
+    # (#build_turn_endings); these forward to it.
+    def kept_messages(turn, result, seconds) = @turn_endings.kept_messages(turn, result, seconds)
     private :kept_messages
-
-    # A Ctrl-C keeps the loop's conversation so far, as a Stop does (its
-    # finished tool iterations, every call answered: ToolResponse.run_batch),
-    # else the turn's messages so far (it came before the loop), with a
-    # cancel note naming the tasks still running; nil before there are any.
-    def ctrl_c_messages(turn, interrupt, seconds)
-      kept = loop_conversation(interrupt) || turn.messages
-      return nil unless kept
-
-      note = TurnNote.cancelled(:ctrl_c, seconds: seconds, running_tasks: Tools::TaskRuntime.running_created_in(kept))
-      TurnNote.replace_trailing(kept, note)
-    end
+    def ctrl_c_messages(turn, interrupt, seconds) = @turn_endings.ctrl_c_messages(turn, interrupt, seconds)
     private :ctrl_c_messages
-
-    # The conversation the loop had built when +error+ ended the turn
-    # (LLM::FailedTurn), or nil.
-    def loop_conversation(error)
-      error.partial_conversation if error.respond_to?(:partial_conversation) && error.partial_conversation.is_a?(Array)
-    end
+    def loop_conversation(error) = @turn_endings.loop_conversation(error)
     private :loop_conversation
-
-    # A failure keeps the loop's partial conversation (else the turn's
-    # messages so far) with a failed note; nil when the turn never reached
-    # the model. The model reads why on its next turn. A turn that got to
-    # tool results (LLM::FailedTurn.progress) says so in the note; on the
-    # error (kept_steps) too unless it failed in a way that rolls back
-    # (FailedTurn.keeps_work?: a context overflow). The UIs keep a marked
-    # turn (TurnFlow#prompt_turn_failed), and roll back the others, with a
-    # note of their own; -p --non-interactive keeps what this keeps.
-    def failed_messages(turn, error)
-      kept = loop_conversation(error) || turn.messages
-      return nil unless kept
-
-      steps = LLM::FailedTurn.progress(turn.session.messages, kept)
-      error.kept_steps = steps if steps && error.is_a?(LLM::FailedTurn) && LLM::FailedTurn.keeps_work?(error)
-      summary = error.respond_to?(:summary) ? error.summary : error.message
-      TurnNote.replace_trailing(kept, TurnNote.failed(summary, continued: turn.continue, steps: steps))
-    end
+    def failed_messages(turn, error) = @turn_endings.failed_messages(turn, error)
     private :failed_messages
-
-    # Called after #failed_messages, which marks the error's kept steps.
-    def failed_event(error, seconds)
-      failed = { type: :turn_failed, error_class: error.class.name, message: error.message,
-                 duration_ms: (seconds * 1000).round }
-      # Its work stays: the UIs say so, as after a cancel.
-      steps = LLM::FailedTurn.kept_steps(error)
-      failed[:kept_steps] = steps if steps
-      # A provider error says what kind it is, for one line per kind in the UIs.
-      if error.is_a?(LLM::ProviderError)
-        failed.merge!(error_kind: error.kind, retryable: error.retryable?, host: error.host, summary: failure_summary(error))
-      end
-      failed
-    end
+    def failed_event(error, seconds) = @turn_endings.failed_event(error, seconds)
     private :failed_event
 
     # However the turn ended (#run_turn's ensure): the turn flag off, the
@@ -2615,23 +2501,10 @@ module Samagotchi
       raise LLM::VisionUnsupported.new("#{host}: #{vision.refusal_reason}", host: host)
     end
 
-    # JSON-safe digest of a finished turn for renderers (in-process or over the
-    # Bridge): the bits of the native loop's result a UI needs beyond `result:`.
+    # JSON-safe digest of a finished turn for renderers (TurnEndings#turn_summary).
     # @param result [LLM::ModelResult]
     # @return [Hash]
-    def turn_summary(result)
-      summary = {
-        output: result.output.to_s,
-        exhausted: result.exhausted?,
-        resumable: result.resumable?,
-        pending_tool_calls: result.pending_tool_calls?,
-        tool_activity: Array(result.tool_activity).map(&:dup),
-        context_status: result.context_status&.dup
-      }
-      # No answer: every UI shows its notice (TurnNote.empty_answer_line).
-      summary[:empty_answer] = { retries: result.empty_retries.to_i, refusal: result.refusal }.compact if result.empty_answer?
-      summary
-    end
+    def turn_summary(result) = @turn_endings.turn_summary(result)
 
     # ── Session messages API ───────────────────────────────────────────────
     #
@@ -2882,7 +2755,7 @@ module Samagotchi
                                   model: model, source: source)
         },
         model_name: -> { effective_model_ref },
-        model_key: -> { @model_key },
+        model_key: -> { @model_binding.model_key },
         state_dir: -> { session_state_dir },
         scratch: -> { @scratch },
         setup: -> { SessionSetup.of(@session) },
@@ -2999,253 +2872,47 @@ module Samagotchi
 
     # ── Event helpers ──────────────────────────────────────────────────────────
 
-    # Always return a handler so raw kernel loop events reach the persistent
-    # SessionObserver (and thus the analytics collector) even when there is no
-    # turn-scoped +on_event+ sink (e.g. the -p/--resume paths and
-    # SessionManager background workers). emit_event tolerates a nil on_event by
-    # only notifying the observer.
-    # Wrap a raw kernel stream event and fan it out to the turn sink + observers.
-    #
-    # Each :generation_chunk comes split already, by the loop that streamed it:
-    # besides the raw `content` (left untouched — the TUI thinking spinner,
-    # analytics, and Bridge replay rely on it) it carries
-    #   * :text     — visible prose (thinking AND tool_call blocks removed)
-    #   * :thinking — thinking-only content
-    # KernelLoop splits a native stream with a ThoughtStreamSplitter per
-    # generation (every profile, Gemma's thought channel included); the chat
-    # loop gets reasoning apart from the answer. The web routes on those
-    # fields (chunk_router.js).
-    #
-    # With a :generation_progress hook registered, a Hooks::StreamWatch gets
-    # each chunk's thinking and text after the UIs had it.
-    #
-    # +model_ref+: the turn's model (#generation_model_ref), added to each
-    # :generation_started as `model_ref:` (both loops send through here).
-    def build_stream_event_handler(on_event, cancel_controller: nil, model_ref: nil)
-      watch = stream_watch(cancel_controller)
-      proc do |event|
-        progress = SteerCut.lanes(event) if event[:type] == :generation_chunk
-        @steer_cut.observe(event, progress)
-        case event[:type]
-        when :generation_started
-          event = event.merge(model_ref: model_ref) if model_ref
-          @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]
-            @thinking_notices.generation_started
-            watch&.started(event[:iteration], restarted: true)
-          end
-        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_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)
-        # What this request sends: both loops start a generation after
-        # their apply_llm_context!.
-        emit_working_set(on_event, @session, live_conversation) if event[:type] == :generation_started
-        watch.feed(**progress) if watch && progress
-        @thinking_notices.generation_completed(event) if event[:type] == :generation_completed
-      end
-    end
-
-    # The working set (WorkingSet) as the model has it, as a
-    # :working_set_updated event ({items:, at:}, adds: while the user's
-    # adds are pending): at each request (the
-    # stream handler's :generation_started, from the running turn's
-    # conversation) and at turn end (#end_turn, from the session's kept
-    # messages). Only when it differs from the last one emitted for this
-    # session, and never while it is empty — except one empty event,
-    # remembered, when the last one for this session had items (a
-    # rollback removed the tool calls), so a tool-free turn emits none
-    # and the next empty request sends nothing more. The web overlays it
-    # on the rows' set; other UIs ignore it.
-    #
-    # Between turns (#announce_working_set: no +on_event+) it is
-    # announced, under the next turn's strategy.
-    def emit_working_set(on_event, session, conversation)
-      return unless session && conversation
-
-      snapshot = WorkingSet.build(conversation, cwd: session.working_directory, strategy: working_set_strategy,
-                                  pins: session.working_set_pins)
-
-      shown = snapshot.to_h.except(:at)
-      last = @working_set_emitted
-      if snapshot.empty?
-        return unless last && last[0] == session.id && last[1] != { items: [] }
-      elsif last == [session.id, shown]
-        return
-      end
-
-      @working_set_emitted = [session.id, shown]
-      event = { type: :working_set_updated, **shown, at: snapshot.at }
-      on_event ? emit_event(on_event, event) : announce_or_hold(event)
-    rescue StandardError => e
-      Log.warn(:turn, "working_set_failed", error: e.class.name, msg: e.message.to_s[0, 200])
-    end
+    # The stream handler, the working set and the event fan-out are
+    # EventFanout's (#build_event_fanout); these forward to it.
+    def build_stream_event_handler(...) = @event_fanout.build_stream_event_handler(...)
+    def emit_working_set(...) = @event_fanout.emit_working_set(...)
     private :emit_working_set
-
-    # The strategy the set is built under: the running turn's
-    # (TurnSettings#llm_context: what its requests send); between turns
-    # the next turn's (as #warm_up_next_turn: the turn's settings keep the
-    # last turn's, stale after a /llm-context or /model change), the last
-    # turn's when it can't be resolved.
-    def working_set_llm_context
-      turn = @kernel.respond_to?(:turn_settings) ? @kernel.turn_settings&.llm_context : nil
-      return turn if turn_running?
-
-      @model_settings.turn_llm_context || turn
-    end
+    def working_set_llm_context = @event_fanout.working_set_llm_context
     private :working_set_llm_context
-
-    # A :generation_completed with the generation's decode speed (`speed:`
-    # {decode_tps:, source:}, nil without one), the session's running
-    # token totals (`tokens:`, the snapshot's block) and its per-model rows
-    # (`model_segments:`, the snapshot's) and whether its served
-    # model is an expected one (`served_expected_by:`, its host): the web's info bar
-    # reads them from the stream. SessionMetrics closes the generation here,
-    # so the event it gets next finds it closed.
-    def with_generation_report(event)
-      report = @metrics.finish_generation
-      event.merge(speed: report.speed&.to_h, tokens: report.tokens, model_segments: report.model_segments,
-                  served_expected_by: served_expected_by(event[:served_model]))
-    rescue StandardError => e
-      Log.warn(:turn, "generation_report_failed", error: e.class.name, msg: e.message.to_s[0, 200])
-      event
-    end
+    def with_generation_report(event) = @event_fanout.with_generation_report(event)
     private :with_generation_report
-
-    # The turn's StreamWatch, or nil when no hook listens.
-    def stream_watch(cancel_controller)
-      return nil unless cancel_controller && @hooks.any?(Hooks::StreamWatch::EVENT)
-
-      Hooks::StreamWatch.new(hooks: @hooks, cancel_controller: cancel_controller)
-    end
+    def stream_watch(cancel_controller) = @event_fanout.stream_watch(cancel_controller)
     private :stream_watch
-
-    def emit_event(on_event, event)
-      # Capture used memories synchronously in the turn thread.
-      read_names = begin
-        @used_memories.capture(event, muted: @muted_memory_names)
-      rescue StandardError => e
-        Log.warn(:memory, "used_memories_capture_failed", error: e.class.name, msg: e.message.to_s[0, 200])
-        nil
-      end
-      # Turn-scoped sink: receives the event hash as the stream handler
-      # passed it (no event_seq; a :generation_completed has its report). Sink errors are isolated and never break the
-      # kernel loop (same as KernelLoop's own handling).
-      if on_event
-        begin
-          on_event.call(event)
-        rescue StandardError => e
-          # Sink errors must not break the kernel loop (same as KernelLoop's own handling)
-          Log.warn(:turn, "sink_failed", event_type: event[:type].to_s, error: e.class.name, msg: e.message.to_s[0, 200])
-        end
-      end
-
-      # Persistent subscribers: receive a copy with a locally-monotonic
-      # `event_seq`, fan out with per-subscriber error isolation.
-      @session_observer.notify(event)
-      # Every memory read, after its tool_call_started: the whole list for
-      # the UIs' memory line, and the names this call read (read_names).
-      return unless read_names
-
-      emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names, read_names: read_names })
-    end
+    def emit_event(on_event, event) = @event_fanout.emit_event(on_event, event)
 
     # The effective model's window_tokens and price, read per turn
     # (SessionModelSettings).
     def turn_window_setting = @model_settings.turn_window_setting
     def turn_price = @model_settings.turn_price
 
-    # See #served_model. A report for another name (before a /model switch)
-    # 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 model
-
-      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
-
-    # The next turn's kit prompt text for /stats: its kit and its estimated
-    # tokens (chars / 4), nil when its toolkit has none.
-    def kit_prompt_stats
-      resolved = toolkit_explained.resolved
-      return nil unless resolved.prompt
-
-      { kit: resolved.name, tokens: (resolved.prompt.length / TokenUsage::CHARS_PER_TOKEN).ceil }
-    end
+    # The snapshots' helpers are EngineSnapshots' (#build_engine_snapshots);
+    # these forward to it.
+    def served_model_for(...) = @engine_snapshots.served_model_for(...)
+    def kit_prompt_stats = @engine_snapshots.kit_prompt_stats
 
     # The window as +model+'s loop would see it (EffectiveModel#context_window).
     def current_context_window(model) = model.context_window
 
-    # +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
+    # +settings+' chips (EngineSnapshots#setting_chips).
+    def setting_chips(settings, model) = @engine_snapshots.setting_chips(settings, model)
 
     # The effective model now, resolved on each call, never kept
     # (SessionModelSettings#effective_model). Raises as HostRegistry#resolve does.
     # @return [EffectiveModel]
-    def effective_model(choice = @model_choice) = @model_settings.effective_model(choice)
+    def effective_model(choice = @model_binding.choice) = @model_settings.effective_model(choice)
 
     # ── 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
-
-    # 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)
-      kept = @profile_resolution&.last
-      @prompt_builder&.reset! if kept && kept.profile.name != resolution.profile.name
-      @kernel.use_profile!(resolution)
-      resolution
-    end
-
-    # Before a turn: resolve now if nothing has yet, or again if the last
-    # server probe failed (unreachable, or 503 while loading a model). A
-    # profile that changes here drops the cached system prompts.
-    def refresh_profile!
-      choice, kept = @profile_resolution
-      return profile_resolution unless choice.equal?(@model_choice) && kept.retry?
-
-      store_profile(choice, resolve_profile(choice))
-    end
+    # The profile's resolve, keep, apply and retry are ModelBinding's
+    # (#build_model_binding); these forward to it.
+    def resolve_profile(choice) = @model_binding.resolve_profile(choice)
+    def store_profile(choice, resolution) = @model_binding.store_profile(choice, resolution)
+    def apply_profile(resolution) = @model_binding.apply_profile(resolution)
+    def refresh_profile! = @model_binding.refresh_profile!
   end
 end