samagotchi 0.52.0 → 0.54.0

data/lib/samagotchi/context_providers.rb

@@ -84,10 +84,10 @@ module Samagotchi
     # @raise [Invalid] the provider makes a name that isn't a source name
     def resolve(url)
       url = url.to_s.strip
-      MemoryBundle::Provenance.each_installed do |bundle, data|
-        next if data[:error] || !data[:context_providers].is_a?(Array)
+      MemoryBundle::Provenance.each_installed do |bundle, record|
+        next if record.error? || !record.context_providers?
 
-        providers(bundle, data).each do |provider|
+        providers(bundle, record).each do |provider|
           match = provider.regexp.match(url) or next
           return resolved(bundle, provider, match)
         end
@@ -97,13 +97,11 @@ module Samagotchi
 
     # Whether an installed bundle declares a provider (the web's "+ URL").
     def any?
-      MemoryBundle::Provenance.each_installed.any? do |_bundle, data|
-        !data[:error] && data[:context_providers].is_a?(Array) && !data[:context_providers].empty?
-      end
+      MemoryBundle::Provenance.each_installed.any? { |_bundle, record| !record.error? && record.context_providers? }
     end
 
-    def providers(bundle, data)
-      parse_list(data[:context_providers])
+    def providers(bundle, record)
+      parse_list(record.context_providers)
     rescue Invalid => e
       Log.warn(:context, "providers_unreadable", bundle: bundle, msg: e.message)
       []
@@ -131,13 +129,12 @@ module Samagotchi
       return source.cmd unless source.provider
 
       provenance = MemoryBundle::Provenance.new(name: source.provider)
-      data = provenance.read
-      raise Invalid, "bundle #{source.provider} isn't installed" unless data
+      record = provenance.record
+      raise Invalid, "bundle #{source.provider} isn't installed" unless record
 
-      scripts = data[:scripts].is_a?(Hash) ? data[:scripts] : {}
-      scripts.each do |file, meta|
-        path = File.join(provenance.scripts_dir, file.to_s)
-        recorded = MemoryBundle::Provenance.recorded_sha(meta.is_a?(Hash) ? meta[:sha256] : nil)
+      record.scripts.each do |file, sha|
+        path = File.join(provenance.scripts_dir, file)
+        recorded = MemoryBundle::Provenance.recorded_sha(sha)
         next if File.file?(path) && MemoryBundle::Provenance.file_sha(path) == recorded
 
         raise Invalid, "bundle #{source.provider}'s scripts/#{file} differs from the installed one (reinstall the bundle)"

data/lib/samagotchi/context_status.rb

@@ -12,8 +12,9 @@ module Samagotchi
   #
   # - the status line's value (#display), every request and again from the
   #   server's final counts after each generation;
-  # - a :context_status stream event (#observe's return), on a bucket change
-  #   or every context.status_cadence requests;
+  # - a :context_status stream event (#observe's return), on every request,
+  #   so the web and the attached TUI get a fresh estimate each time (the
+  #   context.status_cadence setting no longer throttles this event);
   # - the model's own short line (#take_guidance), once per rise into a
   #   bucket whose guidance asks for a change (the second threshold up).
   #
@@ -125,7 +126,6 @@ module Samagotchi
       parsed = Config.get("context.status_thresholds").to_s.split(",").map { |value| value.strip.to_i }
                      .select { |value| value.between?(1, 99) }.uniq.sort
       @thresholds = parsed.empty? ? DEFAULT_THRESHOLDS : parsed
-      @cadence = [Config.get("context.status_cadence").to_i, 0].max
       @last_bucket = self.class.last_bucket(conversation)
       @server_usage = nil
       @counted = nil
@@ -153,16 +153,19 @@ module Samagotchi
     # +image_tokens+: the images' estimate (their base64 is not in the chars).
     #
     # @return [Hash, nil] the :context_status event's fields (without
-    #   :type/:iteration) when the emit gate fires, else nil
+    #   :type/:iteration) for every request when enabled, else nil (the
+    #   context.status off). The estimate is returned every request, so the
+    #   web and the attached TUI get a fresh number on each; the model's own
+    #   line is still only left on a rise into a guidance bucket (below).
     def observe(prompt_chars, iteration_index:, window:, image_tokens: 0)
       return nil unless @enabled
 
       usage = estimate(prompt_chars, server_usage: @server_usage, window: window, image_tokens: image_tokens, counted: @counted)
       bucket = bucket_for(usage[:estimated_pct])
-      # The status line's value, every iteration; the gate below decides
-      # only the event and the model's guidance line.
+      # The status line's value, every iteration; the event below too, so the
+      # consumers get a fresh estimate on every request. Only the model's line
+      # is still gated: it is left only on a rise (below).
       @display = { est_pct: usage[:estimated_pct], bucket: bucket }
-      emit = emit?(bucket: bucket, iteration_index: iteration_index)
       previous_bucket = @last_bucket
       @last_bucket = bucket
       line = if @forget
@@ -171,7 +174,6 @@ module Samagotchi
                guidance_message(usage: usage, bucket: bucket)
              end
       @guidance = line if line
-      return nil unless emit
 
       { status: status_message(usage: usage, bucket: bucket), usage: usage, bucket: bucket, source: usage[:source] }
     end
@@ -293,16 +295,6 @@ module Samagotchi
       rank >= GUIDANCE_FROM_RANK && rank > bucket_rank(previous)
     end
 
-    def emit?(bucket:, iteration_index:)
-      bucket_changed = bucket != if @last_bucket.nil?
-                                   "under#{@thresholds.first}"
-                                 else
-                                   @last_bucket
-                                 end
-      cadence_due = @cadence.positive? && ((iteration_index + 1) % @cadence).zero?
-      bucket_changed || cadence_due
-    end
-
     # The forget layer's line for this request, or nil (the tiers and when
     # they come: the class comment).
     def forget_line(usage, bucket, previous, iteration_index)

data/lib/samagotchi/engine.rb

@@ -21,6 +21,7 @@ require_relative "tools/builtins"
 require_relative "tools/task_runtime"
 require_relative "session_commands"
 require_relative "plugin/loader"
+require_relative "extension_load"
 require_relative "log"
 require_relative "log_subscriber"
 require_relative "thinking_tails"
@@ -89,6 +90,9 @@ module Samagotchi
       new(profile: profile, plugins: false).assist_system_prompt
     end
 
+    # What memory_write answers in a scratch session.
+    SCRATCH_MEMORY_WRITE = "Error: scratch session: nothing is saved"
+
     # @param client             [Client, nil] defaults to Client.new
     # @param profile            [ModelProfile, Symbol, String, nil]
     # @param session_id         [String, nil] resume an existing session
@@ -100,8 +104,6 @@ module Samagotchi
     # @param memories           [Array<String>] explicit --memory preload list (merged with the config.yml `memories:` baseline)
     # @param muted_memories     [Array<String>] --mute list: memories hidden from this session (not in the
     #   prompt's index, dropped from the preloads, refused by memory_read); a mute wins over a preload
-    # What memory_write answers in a scratch session.
-    SCRATCH_MEMORY_WRITE = "Error: scratch session: nothing is saved"
     # @param plugins            [Boolean] false: load no bundle plugins (a throwaway Engine for a prompt)
     # @param scratch            [Boolean] a `chi scratch` session: memory writes are refused, and there is no
     #   delegate (a child would outlive it) nor plugin fork
@@ -144,17 +146,7 @@ module Samagotchi
       # Load hooks from config (plugins) and create the registry; what fails
       # to load is announced, and a required guardrail's failure denies
       # every tool call. Rules load now too, so their errors are announced.
-      @guardrail_wiring = GuardrailWiring.new(
-        scratch: @scratch,
-        hooks: -> { @hooks },
-        tools: -> { @tools },
-        session: -> { @session },
-        model_key: -> { @model_key },
-        model_name: -> { guardrail_model_name },
-        cancelled: -> { !!active_cancel_controller&.cancelled? },
-        ask: ->(fields) { open_question(fields) },
-        notify: ->(message) { guardrail_notify(message) }
-      )
+      @guardrail_wiring = build_guardrail_wiring
       @guardrail_failures = @guardrail_wiring.failures
       # Plugins that failed to load: announced apart, as plugins (not
       # guardrails: no tool call is denied for them).
@@ -163,30 +155,17 @@ module Samagotchi
       # approvals). Built before the hooks and plugins load: a plugin can ask
       # during its load (answered nil then: the interface is still
       # :non_interactive).
-      @question_desk = QuestionDesk.new(
-        session: -> { @session },
-        state_dir: -> { session_state_dir },
-        emit: ->(event) { emit_event(nil, event) },
-        cancel_controller: -> { active_cancel_controller },
-        interface: -> { interface },
-        user_input: ->(sid) { ArchiveStore.user_input(sid, state_dir: session_state_dir) }
-      )
+      @question_desk = build_question_desk
       # Built here, not on first use: the turn thread and the Bridge's read it.
       @relay_desk = RelayDesk.new
-      @hooks = load_hooks_from_config
-      load_hooks_from_bundles
+      @extension_load = ExtensionLoad.new(hook_failures: @guardrail_failures)
+      @hooks = @extension_load.hooks
       # The tools this session offers (the prompts' declarations and the
       # kernel's dispatch): the built-ins, per Engine. execute.description
       # off: execute offers no description parameter.
       @tools = Tools::Builtins.registry(command_description: Config.get("execute.description") != false,
                                         policy: Config.get(LLMContextStrategy::POLICY_SETTING))
-      if @scratch
-        # A scratch session's children would outlive it, and so would a
-        # note it left in a peer; its memories would too (write and edit
-        # into the memories: ScratchWrites).
-        [Tools::Delegate::NAME, Tools::DelegateResult::NAME, Tools::SendNote::NAME].each { |name| @tools.unregister(name) }
-        @tools[Tools::MemoryWrite::NAME].handler = ->(_call, _kctx) { SCRATCH_MEMORY_WRITE }
-      end
+      restrict_scratch_tools! if @scratch
       # Likewise the slash commands its SessionCommands run.
       @command_registry = SessionCommands.register_builtins(Commands::Registry.new)
       # Installed bundles' plugins add commands, tools and hooks to these
@@ -199,16 +178,7 @@ module Samagotchi
       # chi.init tasks (#add_init_task), started by #start_init_tasks!, and
       # plugins' tool sets from chi.replace_tools until the turn thread
       # applies them (#apply_staged_tools!). Built before the plugins load.
-      @plugin_tasks = PluginTasks.new(
-        clock: -> { monotonic_now },
-        synchronize_events: ->(&block) { synchronize_events(&block) },
-        announce: ->(event) { announce(event) },
-        emit: ->(sink, event) { emit_event(sink, event) },
-        show_card: ->(**card) { show_card(**card) },
-        tools: -> { @tools },
-        notify: ->(text, level, source, fallback_for: nil) { hook_notify(text, level, source, fallback_for: fallback_for) },
-        tools_changed: -> { tools_changed! }
-      )
+      @plugin_tasks = build_plugin_tasks
       @lifecycle_mutex = Mutex.new
       @shut_down = false
       load_plugins if plugins
@@ -225,36 +195,9 @@ module Samagotchi
       @reminders = build_reminders(auto_turn_callback: callback)
       # Track whether this is the first turn in the session (for session_start event)
       @first_turn = true
-      # 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, hooks: @hooks, reminder_store: @reminder_store,
-                                         tools: @tools)
-      @kernel.reminder_store = @reminder_store
-      @kernel.hooks = @hooks
-      @kernel.tools = @tools
-      sync_kernel_client!
-      sync_model_key!
-      # The mutes never change during a session, so no re-sync: the kernel's
-      # memory_read guard reads the same list for every turn.
-      @muted_memory_names = MutedMemories.normalize_list(muted_memories)
-      @kernel.muted_memory_names = @muted_memory_names
-      # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
-      @kernel.question_handler = proc { |payload| request_question(payload) }
-      # Every tool call asks this gate first. The kernel is never rebuilt, so
-      # it holds across model switches.
-      self.guardrail_state_dir = Session.default_state_dir
-      # list_sessions and send_note speak for whichever session runs now.
-      @kernel.peers = PeerView.new(self)
-      @kernel.guardrail_gate = @guardrail_wiring.gate
-      # The turn-end warm-up; the kernel asks it for a slot pin per request.
-      @prompt_warmup = PromptWarmup.new
-      @kernel.warmup = @prompt_warmup
-      # What a hook can do beyond reading its event (event[:notify],
-      # event[:ask_user], event[:stop_turn]): the Engine's routes to the UIs.
-      @hooks.runtime = hook_runtime
-      # The loop follows the effective model's host (its api:): the raw-prompt
-      # NativeBackend, or the chat backend for openai hosts.
-      @native_backend = LLM::NativeBackend.new(kernel: @kernel)
+      # The kernel (built here, or a spec's) and what it reads of the Engine;
+      # then the native backend over it.
+      wire_kernel(kernel, muted_memories)
       Log.debug(:model, "backend", provider: backend.provider) if Log.level?(:debug)
       @resume_session = session_id ? Session.load(session_id) : nil
       @prompt_builder = SystemPrompt.new(profile: -> { self.profile }, tools: -> { @tools }, session: -> { @session },
@@ -286,6 +229,23 @@ module Samagotchi
         engine: self,
         jobs: [@reminders, @recap].compact
       )
+      subscribe_session_observers
+    end
+
+    # ── initialize's collaborators ──────────────────────────────────────────
+
+    # The tools a scratch session doesn't offer, and its memory_write.
+    def restrict_scratch_tools!
+      # A scratch session's children would outlive it, and so would a
+      # note it left in a peer; its memories would too (write and edit
+      # into the memories: ScratchWrites).
+      [Tools::Delegate::NAME, Tools::DelegateResult::NAME, Tools::SendNote::NAME].each { |name| @tools.unregister(name) }
+      @tools[Tools::MemoryWrite::NAME].handler = ->(_call, _kctx) { SCRATCH_MEMORY_WRITE }
+    end
+    private :restrict_scratch_tools!
+
+    # The persistent observers of every turn's events.
+    def subscribe_session_observers
       # The metrics collector is a persistent observer so every run_turn event
       # (the REPL, -p/--non-interactive/--resume and SessionManager workers)
       # feeds it automatically.
@@ -297,6 +257,88 @@ module Samagotchi
         @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir)
       }))
     end
+    private :subscribe_session_observers
+
+    # The kernel and what it holds of the Engine (stores, hooks, tools, the
+    # mutes, the question flow, the gate, peers, warm-up, the hook runtime),
+    # and the native backend over it. After the plugins load.
+    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, hooks: @hooks, reminder_store: @reminder_store,
+                                         tools: @tools)
+      @kernel.reminder_store = @reminder_store
+      @kernel.hooks = @hooks
+      @kernel.tools = @tools
+      sync_kernel_client!
+      sync_model_key!
+      # The mutes never change during a session, so no re-sync: the kernel's
+      # memory_read guard reads the same list for every turn.
+      @muted_memory_names = MutedMemories.normalize_list(muted_memories)
+      @kernel.muted_memory_names = @muted_memory_names
+      # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
+      @kernel.question_handler = proc { |payload| request_question(payload) }
+      # Every tool call asks this gate first. The kernel is never rebuilt, so
+      # it holds across model switches.
+      self.guardrail_state_dir = Session.default_state_dir
+      # list_sessions and send_note speak for whichever session runs now.
+      @kernel.peers = PeerView.new(self)
+      @kernel.guardrail_gate = @guardrail_wiring.gate
+      # The turn-end warm-up; the kernel asks it for a slot pin per request.
+      @prompt_warmup = PromptWarmup.new
+      @kernel.warmup = @prompt_warmup
+      # What a hook can do beyond reading its event (event[:notify],
+      # event[:ask_user], event[:stop_turn]): the Engine's routes to the UIs.
+      @hooks.runtime = hook_runtime
+      # The loop follows the effective model's host (its api:): the raw-prompt
+      # NativeBackend, or the chat backend for openai hosts.
+      @native_backend = LLM::NativeBackend.new(kernel: @kernel)
+    end
+    private :wire_kernel
+
+    # The tool guardrails (see #initialize for when).
+    def build_guardrail_wiring
+      GuardrailWiring.new(
+        scratch: @scratch,
+        hooks: -> { @hooks },
+        tools: -> { @tools },
+        session: -> { @session },
+        model_key: -> { @model_key },
+        model_name: -> { guardrail_model_name },
+        cancelled: -> { !!active_cancel_controller&.cancelled? },
+        ask: ->(fields) { open_question(fields) },
+        notify: ->(message) { guardrail_notify(message) }
+      )
+    end
+    private :build_guardrail_wiring
+
+    # The question flow (see #initialize for when).
+    def build_question_desk
+      QuestionDesk.new(
+        session: -> { @session },
+        state_dir: -> { session_state_dir },
+        emit: ->(event) { emit_event(nil, event) },
+        cancel_controller: -> { active_cancel_controller },
+        interface: -> { interface },
+        user_input: ->(sid) { ArchiveStore.user_input(sid, state_dir: session_state_dir) }
+      )
+    end
+    private :build_question_desk
+
+    # The plugins' init tasks and staged tool sets (see #initialize for when).
+    def build_plugin_tasks
+      PluginTasks.new(
+        clock: -> { monotonic_now },
+        synchronize_events: ->(&block) { synchronize_events(&block) },
+        announce: ->(event) { announce(event) },
+        emit: ->(sink, event) { emit_event(sink, event) },
+        show_card: ->(**card) { show_card(**card) },
+        tools: -> { @tools },
+        notify: ->(text, level, source, fallback_for: nil) { hook_notify(text, level, source, fallback_for: fallback_for) },
+        tools_changed: -> { tools_changed! }
+      )
+    end
+    private :build_plugin_tasks
 
     # A monotonically-increasing clock (wall clock can jump backwards; the idle
     # detector must never treat a jump as "activity"). Injectable for specs.
@@ -504,6 +546,20 @@ module Samagotchi
     end
     private :record_prompt_notes
 
+    # A failed turn's one line (the error's #summary). A host's failure
+    # under an alias says what the alias became (HostRegistry#alias_note):
+    # "host main" alone doesn't tell --model splash's user it was splash.
+    # @return [String]
+    def failure_summary(error)
+      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 && note.end_with?("on host #{error.host}") ? "#{summary} (#{note})" : summary
+    rescue StandardError
+      summary
+    end
+
     # +name+'s resolved ref (ModelRef#ref).
     def model_ref_for(name)
       @host_registry.model_ref(name).ref
@@ -666,7 +722,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 hold_load_event(card.merge(in_turn: true))[:id] if @loading_plugins
+      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
@@ -767,7 +823,7 @@ module Samagotchi
         announce({ type: :guardrail_warning, message: message }) if message
         plugins = @plugin_failures.message
         announce({ type: :guardrail_warning, message: plugins, label: "plugins" }) if plugins
-        Array(@plugin_load_events).each do |event|
+        @extension_load.held_events.each do |event|
           announce(event[:type] == :card ? event.merge(in_turn: false) : event.merge(between_turns: true))
         end
       end
@@ -1228,7 +1284,7 @@ module Samagotchi
       emit_event(on_event, { type: :guardrail_warning, message: message }) if message
       plugins = @plugin_failures.message
       emit_event(on_event, { type: :guardrail_warning, message: plugins, label: "plugins" }) if plugins
-      Array(@plugin_load_events).each { |event| emit_event(on_event, event) }
+      @extension_load.held_events.each { |event| emit_event(on_event, event) }
     end
     private :announce_guardrail_failures
 
@@ -1388,7 +1444,7 @@ 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
-      return hold_load_event(notice) && nil if @loading_plugins
+      return @extension_load.hold(notice) && nil if @extension_load.loading?
 
       in_turn, sink = @turn_state.in_turn_sink
       if anytime_thread?
@@ -2119,7 +2175,7 @@ module Samagotchi
       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: error.summary)
+        failed.merge!(error_kind: error.kind, retryable: error.retryable?, host: error.host, summary: failure_summary(error))
       end
       failed
     end
@@ -2380,48 +2436,6 @@ module Samagotchi
       end
     end
 
-    # Load hooks from the global config file using the Hooks::Loader.
-    # Returns a Registry with all plugins registered (or an empty Registry if
-    # no hooks config is present).
-    def load_hooks_from_config
-      config_path = Samagotchi::ConfigFile.global_path
-      data = Samagotchi::ConfigFile.read_yaml(path: config_path)
-      return Hooks::Loader.load(data, failures: @guardrail_failures) if data.is_a?(Hash)
-
-      Hooks::Registry.new
-    end
-
-    def load_hooks_from_bundles
-      require_relative "memory_bundle/provenance"
-      settings = bundle_settings
-      MemoryBundle::Provenance.each_installed(holding: :hooks) do |bundle_name, data|
-        if data[:error]
-          Log.warn(:hooks, "bundle_manifest_invalid", echo: "[samagotchi:hooks] bundle '#{bundle_name}': #{data[:error]}; its hooks are not loaded",
-                                                      bundle: bundle_name)
-          @guardrail_failures.add("hooks (bundle #{bundle_name})", data[:error], required: false)
-          next
-        end
-        bundle_dir = File.join(MemoryBundle::Provenance.bundles_dir, bundle_name)
-        hooks_dir = File.join(bundle_dir, "hooks")
-        if (data[:trust_level] || "experimental").to_s == "experimental"
-          Log.info(:hooks, "experimental_bundle", echo: "[hooks] Bundle '#{bundle_name}' is experimental — its hooks may change or misbehave.", bundle: bundle_name)
-        end
-        begin
-          Hooks::BundleLoader.load(bundle_name: bundle_name, hooks_dir: hooks_dir, metadata: data[:hooks], registry: @hooks,
-                                   failures: @guardrail_failures, settings: settings[bundle_name.to_s] || {},
-                                   requires_chi: data[:requires_chi])
-        rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
-          raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
-
-          Log.error(:hooks, "bundle_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' failed to load hooks: #{e.class}: #{e.message}", bundle: bundle_name, error: e.class.name)
-        end
-      end
-    rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
-      raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
-
-      Log.error(:hooks, "bundles_load_failed", echo: "[samagotchi:hooks] failed to load bundle hooks: #{e.class}: #{e.message}", error: e.class.name)
-    end
-
     def load_plugins
       host = plugin_host
       registries = Plugin::Registries.new(
@@ -2440,17 +2454,7 @@ module Samagotchi
       # What plugins show while they load (an MCP server that didn't
       # start) waits for the first turn, beside the load warnings: no UI
       # is there yet, and the Engine isn't built.
-      @plugin_load_events = []
-      @loading_plugins = true
-      Plugin::Loader.load_installed(registries, failures: @plugin_failures, settings: bundle_settings)
-    ensure
-      @loading_plugins = false
-    end
-
-    # Keep a notice or card a plugin showed while loading (#load_plugins).
-    def hold_load_event(event)
-      @plugin_load_events << event
-      event
+      @extension_load.load_plugins(registries, failures: @plugin_failures)
     end
 
     # Keep a plugin's new tool set (chi.replace_tools, from any thread)
@@ -2536,13 +2540,6 @@ module Samagotchi
     end
     private :ask_side_model
 
-    # config.yml `bundles:` (ConfigFile.bundle_settings), read once: the
-    # bundle hooks and the plugins both want it.
-    def bundle_settings
-      @bundle_settings ||= Samagotchi::ConfigFile.bundle_settings
-    end
-    private :bundle_settings
-
     # The session's current model as a recap target: its host's OpenAI API
     # (native llama.cpp hosts serve /v1/chat/completions too), key variable
     # and bare model name, as a turn resolves them.

data/lib/samagotchi/extension_load.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+require_relative "hooks"
+require_relative "plugin/loader"
+
+module Samagotchi
+  # What an Engine loads from outside chi as it starts: config.yml's hooks,
+  # installed bundles' hooks and plugins, and config.yml `bundles:` (their
+  # settings). It holds what plugins showed while they loaded (notices,
+  # cards): no UI is there yet, so the Engine announces them on the first
+  # turn (Engine#announce_load_events!).
+  class ExtensionLoad
+    # @param hook_failures [Guardrails::LoadFailures] where hooks that fail to load go
+    def initialize(hook_failures:)
+      @hook_failures = hook_failures
+      @loading = false
+      @held_events = []
+    end
+
+    # @return [Array<Hash>] the notices and cards plugins showed while loading
+    attr_reader :held_events
+
+    # Whether the plugins are loading now (#load_plugins): what they show
+    # then is held (#hold), not shown.
+    def loading? = @loading
+
+    # Keep a notice or card a plugin showed while loading.
+    # @return [Hash] the event
+    def hold(event)
+      @held_events << event
+      event
+    end
+
+    # The hooks: config.yml's (Hooks::Loader; an empty Registry without a
+    # hooks config), then the installed bundles' added to them.
+    # @return [Hooks::Registry]
+    def hooks
+      registry = hooks_from_config
+      add_bundle_hooks(registry)
+      registry
+    end
+
+    # Load the installed bundles' plugins into +registries+; one that fails
+    # goes to +failures+, and the rest still load.
+    def load_plugins(registries, failures:)
+      @held_events = []
+      @loading = true
+      Plugin::Loader.load_installed(registries, failures: failures, settings: bundle_settings)
+    ensure
+      @loading = false
+    end
+
+    # config.yml `bundles:` (ConfigFile.bundle_settings), read once: the
+    # bundle hooks and the plugins both want it.
+    def bundle_settings
+      @bundle_settings ||= Samagotchi::ConfigFile.bundle_settings
+    end
+
+    private
+
+    def hooks_from_config
+      config_path = Samagotchi::ConfigFile.global_path
+      data = Samagotchi::ConfigFile.read_yaml(path: config_path)
+      return Hooks::Loader.load(data, failures: @hook_failures) if data.is_a?(Hash)
+
+      Hooks::Registry.new
+    end
+
+    def add_bundle_hooks(registry)
+      require_relative "memory_bundle/provenance"
+      settings = bundle_settings
+      MemoryBundle::Provenance.each_installed(holding: :hooks) do |bundle_name, bundle|
+        if bundle.error?
+          Log.warn(:hooks, "bundle_manifest_invalid", echo: "[samagotchi:hooks] bundle '#{bundle_name}': #{bundle.error}; its hooks are not loaded",
+                                                      bundle: bundle_name)
+          @hook_failures.add("hooks (bundle #{bundle_name})", bundle.error, required: false)
+          next
+        end
+        bundle_dir = File.join(MemoryBundle::Provenance.bundles_dir, bundle_name)
+        hooks_dir = File.join(bundle_dir, "hooks")
+        if bundle.experimental?
+          Log.info(:hooks, "experimental_bundle", echo: "[hooks] Bundle '#{bundle_name}' is experimental — its hooks may change or misbehave.", bundle: bundle_name)
+        end
+        begin
+          Hooks::BundleLoader.load(bundle_name: bundle_name, hooks_dir: hooks_dir, metadata: bundle.hooks, registry: registry,
+                                   failures: @hook_failures, settings: settings[bundle_name.to_s] || {},
+                                   requires_chi: bundle.requires_chi)
+        rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
+          raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
+
+          Log.error(:hooks, "bundle_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' failed to load hooks: #{e.class}: #{e.message}", bundle: bundle_name, error: e.class.name)
+        end
+      end
+    rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
+      raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
+
+      Log.error(:hooks, "bundles_load_failed", echo: "[samagotchi:hooks] failed to load bundle hooks: #{e.class}: #{e.message}", error: e.class.name)
+    end
+  end
+end