samagotchi 0.70.0 → 0.72.0

data/lib/samagotchi/engine.rb

@@ -16,6 +16,7 @@ require_relative "turn_note"
 require_relative "model_profile"
 require_relative "effective_model"
 require_relative "session_setting"
+require_relative "session_model_settings"
 require_relative "thinking_notices"
 require_relative "cancellation_controller"
 require_relative "context_window"
@@ -49,6 +50,7 @@ require_relative "recap_setup"
 require_relative "idle_reminders"
 require_relative "idle_scheduler"
 require_relative "hooks"
+require_relative "event_routes"
 require_relative "hook_routes"
 require_relative "guardrails"
 require_relative "reminder_store"
@@ -141,6 +143,10 @@ module Samagotchi
       @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)
+      # 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 },
+                                                 session: -> { @session })
       # An injected client (specs) stands in for every host's client.
       @host_registry.client_override = client if client
       @client = effective_model.client
@@ -159,7 +165,9 @@ module Samagotchi
       end
       # What hooks and plugins do beyond reading their event (a notice, a
       # question, a stop, a steer), routed to the UIs. Built before anything
-      # that may notify.
+      # that may notify. Where a card or a notice goes (EventRoutes) first:
+      # the hook routes use it.
+      @event_routes = build_event_routes
       @hook_routes = build_hook_routes
       # Load hooks from config (plugins) and create the registry; what fails
       # to load is announced, and a required guardrail's failure denies
@@ -772,9 +780,10 @@ module Samagotchi
 
     # Show a card in every UI (docs/plugins.md, Cards): {type: :card, id:,
     # source:, title:, body:, level:, actions: [{label:, command:}], in_turn:}.
-    # During a turn it is a turn event (the turn's sink and the observers),
-    # else it is announced. A card with the id of an earlier one replaces it
-    # (btw's "thinking…" → the answer).
+    # Where it goes (held while the plugins load, an anytime command's, an
+    # init task's, a turn event, else announced) is EventRoutes#route's,
+    # marked in_turn: (CARD_MARKS). A card with the id of an earlier one
+    # replaces it (btw's "thinking…" → the answer).
     # @param source [String] who shows it (a bundle's name)
     # @param actions [Array<Hash>] {label:, command:}; a command is a line
     #   the session runs, as typed (D3)
@@ -782,18 +791,7 @@ module Samagotchi
     # @raise [ArgumentError] a card without a title, or a bad action
     def show_card(source:, title:, body: "", actions: [], level: :info, id: nil)
       card = build_card(source: source, title: title, body: body, actions: actions, level: level, id: id)
-      return @extension_load.hold(card.merge(in_turn: true))[:id] if @extension_load.loading?
-      return announce_anytime(card.merge(in_turn: false))[:id] if anytime_thread?
-      # A plugin's init task (chi.init): never a running turn's event.
-      return announce(card.merge(in_turn: false)) && card[:id] if current_init_task
-
-      in_turn, sink = @turn_state.in_turn_sink
-      card[:in_turn] = in_turn ? true : false
-      if in_turn
-        emit_event(sink, card)
-      else
-        announce_or_hold(card)
-      end
+      @event_routes.route(card, **EventRoutes::CARD_MARKS)
       card[:id]
     end
 
@@ -1065,7 +1063,8 @@ module Samagotchi
     # 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.
+    # prices the cost estimate names. kit_prompt: the next turn's kit
+    # prompt text ({kit:, tokens:}), only when its toolkit has one.
     # @return [Hash] @metrics.snapshot, filled in
     def stats_snapshot
       snapshot = @metrics.snapshot
@@ -1078,6 +1077,8 @@ module Samagotchi
                                 **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
       unless snapshot.dig(:context, :window_tokens)
         window = current_context_window(model)
         if window
@@ -1095,36 +1096,45 @@ module Samagotchi
       snapshot
     end
 
-    # The status line's ctx from the saved context, for a worker that has run
-    # 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, model: :current)
-      return nil unless context
+    # ── The session's model settings (SessionModelSettings) ──────────────────
+
+    # The session's own thinking, reasoning_history and llm_context values
+    # over the effective model's, the summaries /model and /stats show, and
+    # the saved context's status: SessionModelSettings' (resolved on every
+    # read); these forward.
+    def saved_context_status(context, model: :current) = @model_settings.saved_context_status(context, model: model)
+    def llm_context_explained = @model_settings.llm_context_explained
+    def llm_context_summary = @model_settings.llm_context_summary
+    def llm_context_override = @model_settings.llm_context_override
+    def chat_model? = @model_settings.chat_model?
+    def sampling_summary = @model_settings.sampling_summary
+    def thinking_summary = @model_settings.thinking_summary
+    def steer_cut_after_explained = @model_settings.steer_cut_after_explained
+    def steer_cut_after = @model_settings.steer_cut_after
+    def steer_cut_summary = @model_settings.steer_cut_summary
+    def thinking_explained(own: thinking_override) = @model_settings.thinking_explained(own: own)
+    def reasoning_history_summary = @model_settings.reasoning_history_summary
+    def reasoning_history_cache_cost(from, to) = @model_settings.reasoning_history_cache_cost(from, to)
+    def reasoning_history_override = @model_settings.reasoning_history_override
+    def thinking_override = @model_settings.thinking_override
+    def served_expected_by(served) = @model_settings.served_expected_by(served)
+    def served_expected?(served) = @model_settings.served_expected?(served)
 
-      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])
+    def reasoning_history_explained(native: false, own: reasoning_history_override)
+      @model_settings.reasoning_history_explained(native: native, own: own)
     end
 
-    # #turn_llm_context with where each value came from
-    # (LLMContextStrategy.explain), nil when it can't be resolved.
-    # @return [LLMContextStrategy::Explained, nil]
-    def llm_context_explained
-      model_setting(nil) { |model| model.llm_context_explained(llm_context_session_args) }
+    # Set the session's own reasoning_history or thinking level (nil unsets
+    # it): SessionModelSettings'. The caller saves the session.
+    # @raise [ArgumentError] with no session yet
+    def reasoning_history_override=(level)
+      @model_settings.reasoning_history_override = level
     end
 
-    # #llm_context_explained's summary (Explained#summary), nil when it
-    # can't be resolved: /stats, the snapshot, the web's info bar.
-    # @return [Hash, nil]
-    def llm_context_summary
-      llm_context_explained&.summary(llm_context_override)
+    def thinking_override=(level)
+      @model_settings.thinking_override = level
     end
 
-    # The session's own llm_context values, nil when it has none.
-    # @return [LLMContextOverride, nil]
-    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
     # TurnSettings are fixed). The caller saves the session.
@@ -1137,102 +1147,11 @@ module Samagotchi
       @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? = effective_model.chat?
-
-    # "temperature=0.6 (hosts.work)" for /model: the effective model's
-    # configured sampling, nil when none.
-    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.
-    def thinking_summary
-      explained = thinking_explained
-      explained&.source ? explained.label : nil
-    end
-
-    # The seconds a cut waits for the effective model to stream only
-    # thinking (SteerCutAfter.resolve), resolved on every call, as
-    # turn_sampling; on any error, the global and its name.
-    # @return [Array(Integer, String|nil)]
-    def steer_cut_after_explained
-      model_setting([SteerCut.cut_after, "steer.cut_after"], &:steer_cut_after_explained)
-    end
-
-    # #steer_cut_after_explained's seconds: what SteerCut#cut_for_steer
-    # reads, per host and model.
-    def steer_cut_after = steer_cut_after_explained.first
-
-    # "after 60 s (models: qwen)", "never (hosts.splash)" for /model: the
-    # effective model's cut wait and where it came from, nil for the
-    # default.
-    def steer_cut_summary
-      seconds, source = steer_cut_after_explained
-      source ? SteerCutAfter.label(seconds, source) : nil
-    end
-
-    # The effective model's thinking level with where it came from and the
-    # session's own (SettingExplained), as the next turn resolves it;
-    # nil when it can't be resolved.
-    # @return [SettingExplained, nil]
-    # +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)
-      model_setting(nil) { |model| model.thinking_explained(own: own) }
-    end
-
-    # "drop (models: qwen)" for /model: the effective chat model's
-    # reasoning_history level and where it came from; nil when it is the
-    # default, the model runs on the native loop (which ignores it) or it
-    # can't be resolved.
-    def reasoning_history_summary
-      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
-    # from and the session's own (SettingExplained), as the next turn
-    # resolves it; nil on a native host (the native loop ignores it; native:
-    # true resolves it there too, for /reasoning-history) or when it can't
-    # be resolved.
-    # @return [SettingExplained, nil]
-    # +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)
-      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
-    # the effective model's prompt cache, given the session's conversation
-    # (ReasoningHistory.cache_cost): :history or nil. A host ChatLoop
-    # marked as refusing it may still get :history (one needless ask).
-    # @return [Symbol, nil]
-    def reasoning_history_cache_cost(from, to)
-      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).
     def history?
       Array(@session&.messages).any? { |entry| entry[:role].to_s == "model" }
     end
 
-    # The session's own reasoning_history level, nil when it has none.
-    # @return [Symbol, nil]
-    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.
-    # @raise [ArgumentError] with no session yet
-    def reasoning_history_override=(level)
-      raise ArgumentError, "no session yet" unless @session
-
-      SessionSetting::REASONING_HISTORY.set(@session, level)
-    end
-
-    # The session's own thinking level, nil when it has none.
-    # @return [Symbol, nil]
-    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]
@@ -1240,16 +1159,6 @@ module Samagotchi
       effective_model.thinking_cache_cost { profile }
     end
 
-    # Set the session's own thinking level (nil unsets it); the next turn's
-    # start resolves it, never a running one (its TurnSettings are fixed).
-    # The caller saves the session.
-    # @raise [ArgumentError] with no session yet
-    def thinking_override=(level)
-      raise ArgumentError, "no session yet" unless @session
-
-      SessionSetting::THINKING.set(@session, level)
-    end
-
     # The model the server serves for the current model, and the name asked
     # for: what the last generation of that name reported, else llama.cpp's
     # model_alias (/props, one short cached probe; not with probe: false),
@@ -1259,16 +1168,6 @@ module Samagotchi
       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)
-      model_setting(nil) { |model| model.served_expected_by(served) }
-    end
-
-    def served_expected?(served) = !served_expected_by(served).nil?
-
     # 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
@@ -1299,7 +1198,7 @@ module Samagotchi
       # 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 }
+      model = @model_settings.model_setting(nil) { |resolved| resolved }
       {
         status: @session&.status,
         message_count: (@session&.messages || []).size,
@@ -1587,17 +1486,26 @@ module Samagotchi
     def hook_stop_generation(reason, hook) = @hook_routes.stop_generation(reason, hook)
     private :hook_stop_generation
 
-    # The hook routes (see #initialize for when).
-    def build_hook_routes
-      HookRoutes.new(
+    # Where cards and notices go (see #initialize for when). Each lookup
+    # calls the Engine method the routes used before EventRoutes, at use.
+    def build_event_routes
+      EventRoutes.new(
         extension_load: -> { @extension_load },
         in_turn_sink: -> { @turn_state.in_turn_sink },
         anytime_thread: -> { anytime_thread? },
-        announce_anytime: ->(event) { announce_anytime(event) },
         init_task: -> { current_init_task },
         announce: ->(event) { announce(event) },
+        announce_anytime: ->(event) { announce_anytime(event) },
         announce_or_hold: ->(event) { announce_or_hold(event) },
-        emit: ->(sink, event) { emit_event(sink, event) },
+        emit: ->(sink, event) { emit_event(sink, event) }
+      )
+    end
+    private :build_event_routes
+
+    # The hook routes (see #initialize for when).
+    def build_hook_routes
+      HookRoutes.new(
+        event_routes: @event_routes,
         question_desk: -> { @question_desk },
         cancel_controller: -> { active_cancel_controller },
         steer: ->(text, source) { steer(text, source: source) }
@@ -1682,8 +1590,8 @@ module Samagotchi
     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))
+      level = chat ? nil : @model_settings.thinking_level(model)
+      prompt = @prompt_builder.build(chat: chat, thinking: level, layers: model.llm_context_layers(@model_settings.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).
@@ -2027,10 +1935,10 @@ module Samagotchi
       model = effective_model
       vision = turn_vision(session, model)
       sampling = model.sampling
-      level = thinking_level(model)
+      level = @model_settings.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,
+                            reasoning_history: @model_settings.reasoning_history_level(model), model_name: nil,
                             window_setting: nil, llm_context: nil, price: nil)
     end
     private :turn_settings
@@ -2060,7 +1968,7 @@ module Samagotchi
       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)
+      prompt, images = @kernel.warmup_prompt(messages, llm_context: @model_settings.turn_llm_context || @kernel.turn_settings&.llm_context)
       return unless prompt
 
       started = @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
@@ -2126,7 +2034,7 @@ module Samagotchi
       # 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 = model.llm_context_explained(llm_context_session_args)
+      explained = model.llm_context_explained(@model_settings.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)
@@ -2355,19 +2263,10 @@ module Samagotchi
                         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 = model_setting(SamplingSettings::EMPTY, &:sampling)
-
-    # The effective model's thinking level (Thinking.resolve), read each turn.
-    def turn_thinking = model_setting(Thinking::DEFAULT) { |model| thinking_level(model) }
-
-    # +model+'s ReasoningHistory level, the session's own first; the
-    # default when it can't be resolved.
-    def reasoning_history_level(model) = model.reasoning_history(own: reasoning_history_override)
-
-    # +model+'s thinking level (Thinking.resolve), the session's own first.
-    def thinking_level(model) = model.thinking(own: thinking_override)
+    # The effective model's sampling and thinking level as the next turn
+    # reads them (SessionModelSettings).
+    def turn_sampling = @model_settings.turn_sampling
+    def turn_thinking = @model_settings.turn_thinking
 
     # A model known not to see images fails a turn with images up front.
     def refuse_images!(vision)
@@ -2778,24 +2677,10 @@ module Samagotchi
       emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names, read_names: read_names })
     end
 
-    # The effective model's models:/hosts: window_tokens, read per turn
-    # (after the hooks that may switch the model).
-    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 = 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:
-    # llm_context_strategy), else llm_context.strategy; read per turn as
-    # the window is.
-    def turn_llm_context
-      llm_context_explained&.resolved
-    end
-
-    def llm_context_session_args = @session&.llm_context&.resolve_args || {}
-    private :llm_context_session_args
+    # 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
@@ -2813,6 +2698,15 @@ module Samagotchi
       [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 window as +model+'s loop would see it (EffectiveModel#context_window).
     def current_context_window(model) = model.context_window
 
@@ -2822,26 +2716,10 @@ module Samagotchi
       settings.to_h { |setting| [setting.key, setting.model? ? setting.chip_for(model, @session) : toolkit_summary] }
     end
 
-    # 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.
+    # 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) = EffectiveModel.of(@host_registry, choice)
-
-    # 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
+    def effective_model(choice = @model_choice) = @model_settings.effective_model(choice)
 
     # ── Prompt profile ─────────────────────────────────────────────────────────
 

data/lib/samagotchi/engine_peers.rb

@@ -20,6 +20,8 @@ module Samagotchi
       def model_ref = engine.effective_model_ref
       def thinking = engine.thinking_override
       def reasoning_history = engine.reasoning_history_override
+      # The kits a delegate may start its child on (Engine#toolkit_kits).
+      def toolkit_names = engine.toolkit_kits.keys
       # The peer's name when +name+ is a source a peer bundle declared
       # (PeerSources), for context_read's header.
       def peer_label(name) = engine.peer_sources&.label_for(name)

data/lib/samagotchi/event_routes.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Where a card or a notice goes, by what this thread is doing (Engine#show_card,
+  # HookRoutes#notify, HookRoutes#guardrail_notify):
+  #
+  # 1. the plugins load (ExtensionLoad#loading?): held, announced after the load
+  #    (Engine#announce_load_events!);
+  # 2. an anytime command's thread (Engine#running_anytime): announced at once,
+  #    marked anytime: true;
+  # 3. a plugin's init task (chi.init): announced, never a running turn's event;
+  # 4. a running turn: the turn's event (its sink and the observers);
+  # 5. else announced, or held for Engine#holding_announcements' caller.
+  #
+  # #route takes all five; #route_by_turn only 4 and 5 (a guardrails line).
+  # Each caller says what the event is marked with on each route (CARD_MARKS,
+  # NOTICE_MARKS). What it needs from the Engine comes through lookups, called
+  # at use.
+  class EventRoutes
+    # A card says whether it came in a turn (in_turn:); a held one, true.
+    CARD_MARKS = { held: { in_turn: true }.freeze, in_turn: { in_turn: true }.freeze,
+                   between: { in_turn: false }.freeze }.freeze
+    # A notice is marked only outside a turn (between_turns: true).
+    NOTICE_MARKS = { held: {}.freeze, in_turn: {}.freeze, between: { between_turns: true }.freeze }.freeze
+
+    # @param extension_load   [#call] → ExtensionLoad (#loading?, #hold)
+    # @param in_turn_sink     [#call] → [Boolean, sink] (TurnState#in_turn_sink)
+    # @param anytime_thread   [#call] → whether this thread runs an anytime command
+    # @param init_task        [#call] → the init task running on this thread, nil
+    # @param announce         [#call] (event) → announces an event
+    # @param announce_anytime [#call] (event) → announces an anytime command's event
+    # @param announce_or_hold [#call] (event) → announces it, or holds it for the caller
+    # @param emit             [#call] (sink, event) → emits to a turn's sink + observers
+    def initialize(extension_load:, in_turn_sink:, anytime_thread:, init_task:, announce:, announce_anytime:,
+                   announce_or_hold:, emit:)
+      @extension_load = extension_load
+      @in_turn_sink = in_turn_sink
+      @anytime_thread = anytime_thread
+      @init_task = init_task
+      @announce = announce
+      @announce_anytime = announce_anytime
+      @announce_or_hold = announce_or_hold
+      @emit = emit
+    end
+
+    # Route +event+ by the five routes, first match wins.
+    # @param held    [Hash] merged into the event held while the plugins load
+    # @param in_turn [Hash] merged into a running turn's event
+    # @param between [Hash] merged into an event announced outside a turn (routes 2, 3, 5)
+    # @return [Symbol] the route taken: :held, :anytime, :init, :in_turn or :between
+    def route(event, held:, in_turn:, between:)
+      extension_load = @extension_load.call
+      if extension_load.loading?
+        extension_load.hold(event.merge(held))
+        return :held
+      end
+      if @anytime_thread.call
+        @announce_anytime.call(event.merge(between))
+        return :anytime
+      end
+      if @init_task.call
+        @announce.call(event.merge(between))
+        return :init
+      end
+      route_by_turn(event, in_turn: in_turn, between: between)
+    end
+
+    # Route +event+ by routes 4 and 5 only: a running turn's event, else
+    # announced or held for the caller. Never held while the plugins load,
+    # never marked anytime (a guardrails line).
+    # @return [Symbol] :in_turn or :between
+    def route_by_turn(event, in_turn: {}, between: {})
+      running, sink = @in_turn_sink.call
+      if running
+        @emit.call(sink, event.merge(in_turn))
+        :in_turn
+      else
+        @announce_or_hold.call(event.merge(between))
+        :between
+      end
+    end
+  end
+end

data/lib/samagotchi/hook_routes.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "event_routes"
 require_relative "hooks"
 require_relative "log"
 
@@ -8,33 +9,21 @@ module Samagotchi
   # reading its event (Hooks::Runtime, Plugin::Host): a notice (#notify),
   # a question (#ask_user), stopping the turn or cutting its generation,
   # and a steer; also the guardrails' line after load (#guardrail_notify).
+  # Where a notice goes (held, anytime, init task, turn, between turns) is
+  # EventRoutes'.
   #
-  # What it needs from the Engine comes through lookups, called at use.
+  # What it needs from the Engine comes through lookups, called at use, and
+  # the Engine's EventRoutes.
   class HookRoutes
     # What a notice may stand in for (#notify's fallback_for:).
     NOTICE_FALLBACKS = %i[display editor].freeze
 
-    # @param extension_load    [#call] → ExtensionLoad (#loading?, #hold)
-    # @param in_turn_sink      [#call] → [Boolean, sink] (TurnState#in_turn_sink)
-    # @param anytime_thread    [#call] → whether this thread runs an anytime command
-    # @param announce_anytime  [#call] (event) → announces an anytime command's event
-    # @param init_task         [#call] → the init task running on this thread, nil
-    # @param announce          [#call] (event) → announces an event
-    # @param announce_or_hold  [#call] (event) → announces it, or holds it for the caller
-    # @param emit              [#call] (sink, event) → emits to a turn's sink + observers
+    # @param event_routes      [EventRoutes] where a notice goes
     # @param question_desk     [#call] → QuestionDesk
     # @param cancel_controller [#call] → the running turn's CancellationController, nil
     # @param steer             [#call] (text, source) → steers the running turn
-    def initialize(extension_load:, in_turn_sink:, anytime_thread:, announce_anytime:, init_task:, announce:,
-                   announce_or_hold:, emit:, question_desk:, cancel_controller:, steer:)
-      @extension_load = extension_load
-      @in_turn_sink = in_turn_sink
-      @anytime_thread = anytime_thread
-      @announce_anytime = announce_anytime
-      @init_task = init_task
-      @announce = announce
-      @announce_or_hold = announce_or_hold
-      @emit = emit
+    def initialize(event_routes:, question_desk:, cancel_controller:, steer:)
+      @event_routes = event_routes
       @question_desk = question_desk
       @cancel_controller = cancel_controller
       @steer = steer
@@ -63,7 +52,9 @@ module Samagotchi
     # One line to the user (:hook_notice). During a turn it is a turn
     # event: the turn's sink (the REPL) and the observers (bridge, log).
     # Outside one (a plugin's command at the prompt) it is announced with
-    # between_turns: true, which every UI shows as cards are shown.
+    # between_turns: true, which every UI shows as cards are shown. While the
+    # plugins load it is held; on an anytime command's thread or an init task
+    # it is announced (EventRoutes#route).
     #
     # +fallback_for+ names what the line stands in for (NOTICE_FALLBACKS):
     # :display, the answer's display (AnswerDisplay), for a UI that doesn't
@@ -77,28 +68,16 @@ module Samagotchi
       level = :info unless %i[info warn].include?(level)
       notice = { type: :hook_notice, hook: hook.to_s, text: text.to_s, level: level,
                  fallback_for: notice_fallback(fallback_for, hook) }.compact.merge(extra)
-      extension_load = @extension_load.call
-      return extension_load.hold(notice) && nil if extension_load.loading?
-
-      in_turn, sink = @in_turn_sink.call
-      if @anytime_thread.call
-        @announce_anytime.call(notice.merge(between_turns: true))
-      elsif @init_task.call
-        @announce.call(notice.merge(between_turns: true))
-      elsif in_turn
-        @emit.call(sink, notice)
-      else
-        @announce_or_hold.call(notice.merge(between_turns: true))
-      end
+      @event_routes.route(notice, **EventRoutes::NOTICE_MARKS)
       nil
     end
 
     # A guardrails line to the user after load (:guardrail_warning, as the
-    # load failures show): a running turn's event, else announced.
+    # load failures show): a running turn's event, else announced or held for
+    # the caller (EventRoutes#route_by_turn: never held while the plugins
+    # load, never an anytime command's, unmarked).
     def guardrail_notify(message)
-      event = { type: :guardrail_warning, message: message.to_s }
-      in_turn, sink = @in_turn_sink.call
-      in_turn ? @emit.call(sink, event) : @announce_or_hold.call(event)
+      @event_routes.route_by_turn({ type: :guardrail_warning, message: message.to_s })
       nil
     end