samagotchi 0.66.0 → 0.67.0

data/lib/samagotchi/desktop/macos.rb

@@ -11,6 +11,7 @@ require_relative "../version"
 require_relative "../self_report"
 require_relative "../installed_gem"
 require_relative "../config"
+require_relative "../host_keys"
 require_relative "../redacted_inspect"
 
 module Samagotchi
@@ -48,6 +49,9 @@ module Samagotchi
       # top of it (MacOS.broadcast_timeout).
       BROADCAST_TRIAGE_DEADLINE = 20
       BROADCAST_MARGIN = 10
+      # The agent terminals the helper pastes into (AgentTerminal.swift):
+      # one launch-file section each, in this order.
+      TERMINALS = %w[kitty tmux].freeze
 
       # Runs a command without a shell; [output, success].
       class Runner
@@ -69,10 +73,36 @@ module Samagotchi
         { "listen_on" => listen_on, "binary" => get.call("kitty.binary").to_s, "agents" => agents }
       end
 
+      # The tmux: settings, or nil while tmux.enabled is off. The binary is
+      # tmux.binary, else the tmux on +env+'s PATH ("" when there is none:
+      # see #warnings); the socket dir is where tmux puts `-L` sockets
+      # ($TMUX_TMPDIR when it is a directory, else /tmp, then tmux-<uid>).
+      # Both are frozen at bake time, like the rest of the launch file.
+      def self.tmux_settings(get = Config.method(:get), env: ENV)
+        return nil unless get.call("tmux.enabled")
+
+        binary = get.call("tmux.binary").to_s.strip
+        binary = path_tmux(env) if binary.empty?
+        tmpdir = env["TMUX_TMPDIR"].to_s
+        tmpdir = "/tmp" if tmpdir.empty? || !File.directory?(tmpdir)
+        agents = get.call("tmux.agents").to_s.split("|").map(&:strip).reject(&:empty?)
+        { "binary" => binary, "socket_dir" => File.join(tmpdir, "tmux-#{Process.uid}"), "agents" => agents }
+      end
+
+      def self.path_tmux(env)
+        env["PATH"].to_s.split(File::PATH_SEPARATOR).reject(&:empty?).map { File.join(_1, "tmux") }
+                   .find { File.file?(_1) && File.executable?(_1) }.to_s
+      end
+
+      # Each switched-on terminal's settings by name ("kitty" => …).
+      def self.terminal_settings(get = Config.method(:get), env: ENV)
+        { "kitty" => kitty_settings(get), "tmux" => tmux_settings(get, env: env) }.compact
+      end
+
       # The helper as chi desktop and chi update make it: the settings it
       # bakes into the launch file read from the config.
       def self.from_config(register: true)
-        new(register: register, kitty: kitty_settings, broadcast_timeout: broadcast_timeout)
+        new(register: register, terminals: terminal_settings, broadcast_timeout: broadcast_timeout)
       end
 
       # Seconds the helper gives `chi broadcast` before it stops it: the
@@ -86,7 +116,7 @@ module Samagotchi
 
       def initialize(app_dir: nil, support_dir: nil, env: ENV, runner: Runner.new,
                      source_dir: SelfReport::SOURCE_DIR, ruby: RbConfig.ruby, version: VERSION,
-                     arch: nil, sources_dir: SOURCES_DIR, register: true, chi_path: nil, kitty: nil,
+                     arch: nil, sources_dir: SOURCES_DIR, register: true, chi_path: nil, terminals: {},
                      broadcast_timeout: nil)
         home = env["HOME"] || Dir.home
         @app_dir = app_dir || File.join(home, "Applications")
@@ -100,7 +130,7 @@ module Samagotchi
         @arch = arch
         @sources_dir = sources_dir
         @register = register
-        @kitty = kitty
+        @terminals = terminals
         @broadcast_timeout = broadcast_timeout
       end
 
@@ -114,13 +144,13 @@ module Samagotchi
       # What the helper runs: absolute ruby + chi (no shims, which need the
       # shell's PATH), and the allowlisted env. chi is an installed gem's
       # RubyGems wrapper (it activates the gem and outlives upgrades and
-      # `gem cleanup`), else this checkout's bin/chi. The kitty section only
-      # when kitty.listen_on is set; the broadcast timeout when given.
+      # `gem cleanup`), else this checkout's bin/chi. A section per terminal
+      # switched on (TERMINALS order); the broadcast timeout when given.
       def launch_config
         env = { "LANG" => LANG }
         ENV_ALLOWLIST.each { |name| env[name] = @env[name] unless @env[name].to_s.empty? }
         config = { "version" => @version, "argv" => [@ruby, @chi_path], "env" => env, "sources_sha" => sources_sha }
-        config["kitty"] = @kitty if @kitty
+        TERMINALS.each { |name| config[name] = @terminals[name] if @terminals[name] }
         config["broadcast_timeout"] = @broadcast_timeout if @broadcast_timeout
         config
       end
@@ -145,11 +175,12 @@ module Samagotchi
       end
 
       # The launch file names another chi version or path than this one, or
-      # other kitty settings or broadcast timeout: refresh_launch_file fixes
-      # that without a rebuild.
+      # other terminal settings or broadcast timeout: refresh_launch_file
+      # fixes that without a rebuild.
       def launch_outdated?
         launch = read_launch
-        launch["version"] != @version || Array(launch["argv"]) != launch_config["argv"] || launch["kitty"] != @kitty ||
+        launch["version"] != @version || Array(launch["argv"]) != launch_config["argv"] ||
+          TERMINALS.map { launch[_1] } != TERMINALS.map { @terminals[_1] } ||
           launch["broadcast_timeout"] != @broadcast_timeout
       end
 
@@ -163,10 +194,41 @@ module Samagotchi
       end
 
       def warnings
-        return [] unless File.file?(File.join(@source_dir, ".git"))
+        worktree = if File.file?(File.join(@source_dir, ".git"))
+                     ["chi runs from a linked git worktree (#{@source_dir}); the helper stops working once it is removed. " \
+                      "Install from the main checkout or a gem install."]
+                   end
+        Array(worktree) + terminal_warnings + host_key_warnings
+      end
 
-        ["chi runs from a linked git worktree (#{@source_dir}); the helper stops working once it is removed. " \
-         "Install from the main checkout or a gem install."]
+      # What a terminal section can't do as baked (chi update shows these
+      # too: they need no Keychain lookup).
+      def terminal_warnings
+        tmux = @terminals["tmux"]
+        return [] unless tmux && tmux["binary"].to_s.empty?
+
+        ["tmux.enabled but no tmux found on PATH: set tmux.binary"]
+      end
+
+      # Each configured host key (api_key_env:) and whether the helper's chi
+      # gets it: the helper's bare env has no keys, so only the Keychain's
+      # count (HostKeys). :keychain, :shell_only (set in this shell, not in
+      # the Keychain) or :unset. Hosts come from the config the helper's chi
+      # reads: the launch file's XDG_CONFIG_HOME when baked; disabled hosts
+      # are left out. @return [Array<Hash>] name:, hosts:, state:
+      def host_keys
+        baked = read_launch["env"]
+        dir = baked["XDG_CONFIG_HOME"] if baked.is_a?(Hash)
+        # Spelled out: Paths.config_home's ~ is this process's HOME, not @env's.
+        config_env = { "XDG_CONFIG_HOME" => dir.to_s.empty? ? File.join(@env["HOME"] || Dir.home, ".config") : dir }
+        hosts = ConfigFile.hosts_config(env: config_env).values.select(&:api_key_env).group_by(&:api_key_env)
+        hosts.map do |name, entries|
+          state = if HostKeys.from_keychain(name, env: @env) then :keychain
+                  elsif !@env[name].to_s.strip.empty? then :shell_only
+                  else :unset
+                  end
+          { name: name, hosts: entries.map(&:name), state: state }
+        end
       end
 
       def info_plist
@@ -248,7 +310,8 @@ module Samagotchi
           stale: stale?,
           baked_dirs: env.select { |name, _| name.start_with?("XDG_") },
           service: dump.include?(BUNDLE_ID),
-          running: running
+          running: running,
+          host_keys: host_keys
         )
       end
 
@@ -311,6 +374,14 @@ module Samagotchi
         @arch ||= RbConfig::CONFIG["host_cpu"] == "arm64" ? "arm64" : `uname -m`.strip
       end
 
+      def host_key_warnings
+        host_keys.reject { |key| key[:state] == :keychain }.map do |key|
+          where = key[:state] == :shell_only ? "is set in this shell only" : "is unset"
+          "#{key[:name]} #{where}: the helper's new sessions and model list won't reach host " \
+            "#{key[:hosts].join(", ")} until it is in the Keychain (#{HostKeys.store_command(key[:name])})"
+        end
+      end
+
       def read_launch
         launch = JSON.parse(File.read(launch_path))
         launch.is_a?(Hash) ? launch : {}

data/lib/samagotchi/desktop_command.rb

@@ -3,6 +3,7 @@
 require_relative "cli/command"
 require_relative "cli/flags"
 require_relative "desktop"
+require_relative "host_keys"
 
 module Samagotchi
   # `chi desktop install|upgrade|uninstall|status`: the native helper that
@@ -121,12 +122,22 @@ module Samagotchi
       dirs = s[:baked_dirs].empty? ? "(defaults)" : s[:baked_dirs].map { |name, value| "#{name}=#{value}" }.join(" ")
       service = s[:service] ? "registered" : "not registered (try chi desktop upgrade, or log out and back in)"
       running = s[:running] ? "running" : "not running (open -g \"#{s[:app_path]}\")"
-      @stdout.puts(format_rows([["Chi Helper", version], ["app", s[:app_path]], ["runs chi", launch],
-                                ["state dirs", dirs], ["service", service], ["hotkey", hotkey(s[:hotkey])],
-                                ["process", running], ["at login", login(s[:login])]]))
+      rows = [["Chi Helper", version], ["app", s[:app_path]], ["runs chi", launch], ["state dirs", dirs],
+              ["service", service], ["hotkey", hotkey(s[:hotkey])], ["process", running], ["at login", login(s[:login])]]
+      rows << ["host keys", host_keys(s[:host_keys])] unless Array(s[:host_keys]).empty?
+      @stdout.puts(format_rows(rows))
       0
     end
 
+    # `VAR keychain · VAR this shell only (security …)`: what the helper's chi gets.
+    def host_keys(keys)
+      keys.map do |key|
+        next "#{key[:name]} keychain" if key[:state] == :keychain
+
+        "#{key[:name]} #{key[:state] == :shell_only ? "this shell only" : "unset"} (#{HostKeys.store_command(key[:name])})"
+      end.join(" · ")
+    end
+
     def hotkey(state)
       return "unknown (the app writes it when it starts)" unless state
 

data/lib/samagotchi/engine.rb

@@ -19,6 +19,8 @@ require_relative "context_window"
 require_relative "kernel_loop"
 require_relative "tools/builtins"
 require_relative "tools/task_runtime"
+require_relative "tools/tool_index"
+require_relative "peer_sources"
 require_relative "session_commands"
 require_relative "plugin/loader"
 require_relative "extension_load"
@@ -31,7 +33,7 @@ require_relative "llm/backend"
 require_relative "llm/openai_chat"
 require_relative "llm/turn_settings"
 require_relative "session"
-require_relative "toolkit"
+require_relative "toolkit_binding"
 require_relative "answer_tail"
 require_relative "archive_store"
 require_relative "session_observer"
@@ -44,6 +46,7 @@ require_relative "recap_setup"
 require_relative "idle_reminders"
 require_relative "idle_scheduler"
 require_relative "hooks"
+require_relative "hook_routes"
 require_relative "guardrails"
 require_relative "reminder_store"
 require_relative "reminder_queue"
@@ -146,9 +149,13 @@ module Samagotchi
       begin
         require_relative "memory_bundle/system_bundle"
         MemoryBundle::SystemBundle.ensure!
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Log.warn(:memory, "system_bundle_ensure_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       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.
+      @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
       # every tool call. Rules load now too, so their errors are announced.
@@ -185,9 +192,15 @@ module Samagotchi
       # plugins' tool sets from chi.replace_tools until the turn thread
       # applies them (#apply_staged_tools!). Built before the plugins load.
       @plugin_tasks = build_plugin_tasks
-      # The toolkits plugins declare (chi.toolkit), beside the built-in and
-      # config ones (#toolkit_kits).
-      @plugin_kits = []
+      # The session's toolkit: the kits (the plugins' too, chi.toolkit),
+      # what its next turn declares, the turn-start apply.
+      @toolkit_binding = build_toolkit_binding
+      # The tools plugins publish without declaring (chi.tool_source), and
+      # the search and call tools that reach them (Tools::ToolIndex).
+      @tool_index = Tools::ToolIndex.new
+      # The context sources the peer bundles declare as a peer agent's
+      # answers (chi.peer_source); the worker's ContextAbsorber asks it.
+      @peer_sources = PeerSources.new
       @lifecycle_mutex = Mutex.new
       @shut_down = false
       load_plugins if plugins
@@ -451,7 +464,8 @@ module Samagotchi
 
       log_dropped_steers(steers, "answered")
       []
-    rescue StandardError
+    rescue StandardError => e
+      Log.warn(:turn, "take_steers_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       []
     end
     private :take_steers
@@ -552,7 +566,8 @@ module Samagotchi
       return saved.dup if !@prompt_builder.prompt_notes.nil? || !saved.empty? || @session.messages.to_a.any?
 
       model_notes.map { |note| PromptNote.from_note(note) }
-    rescue StandardError
+    rescue StandardError => e
+      Log.warn(:model, "prompt_notes_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       []
     end
 
@@ -617,6 +632,9 @@ module Samagotchi
     #   built-ins, and the ones bundle plugins add
     attr_reader :command_registry
 
+    # @return [PeerSources] the sources the peer bundles declared
+    attr_reader :peer_sources
+
     # The model id sent for +full_ref+ (its alias applied, the host prefix off).
     def bare_model_name(full_ref)
       @host_registry.bare_name(full_ref)
@@ -1494,7 +1512,8 @@ module Samagotchi
 
     def save_quietly(session)
       session.save(state_dir: session_state_dir)
-    rescue StandardError
+    rescue StandardError => e
+      Log.warn(:turn, "turn_end_save_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       nil
     end
     private :save_quietly
@@ -1532,122 +1551,59 @@ module Samagotchi
     end
     private :store_answer_display
 
-    # ── The hook runtime (Hooks::Runtime) ─────────────────────────────────────
-
-    # The three things a hook can do beyond reading its event. Each gets the
-    # hook's label (event[:hook]) from the registry.
-    def hook_runtime
-      Hooks::Runtime.new(
-        notify: ->(text:, level:, hook:, fallback_for: nil) { hook_notify(text, level, hook, fallback_for: fallback_for) },
-        ask_user: ->(question:, options:, header:, allow_freeform:, hook:) { hook_ask_user(question, options, header, allow_freeform, hook) },
-        stop_turn: ->(reason:, hook:) { hook_stop_turn(reason, hook) },
-        steer: ->(text:, hook:) { steer(text, source: hook_source(hook)) },
-        stop_generation: ->(reason:, hook:) { hook_stop_generation(reason, hook) }
-      )
-    end
+    # ── The hook runtime (HookRoutes) ───────────────────────────────────────
+
+    # What a hook (Hooks::Runtime) and a plugin (Plugin::Host) can do beyond
+    # reading its event, routed to the UIs by HookRoutes; these forward.
+    def hook_runtime = @hook_routes.runtime
     private :hook_runtime
 
-    # What a steer is attributed to: the bundle of a bundle hook's label
-    # ("<file> (bundle <name>)"), the label of any other.
-    def hook_source(hook)
-      hook.to_s[/\(bundle (.+)\)\z/, 1] || hook.to_s
-    end
+    def hook_source(hook) = @hook_routes.source(hook)
     private :hook_source
 
     # What a notice may stand in for (hook_notify's fallback_for:).
-    NOTICE_FALLBACKS = %i[display editor].freeze
+    NOTICE_FALLBACKS = HookRoutes::NOTICE_FALLBACKS
 
-    # 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.
-    #
-    # +fallback_for+ names what the line stands in for (NOTICE_FALLBACKS):
-    # :display, the answer's display (AnswerDisplay), for a UI that doesn't
-    # render its links; :editor, a ref the viewer could open in its editor
-    # (Web::Capabilities#editor), for a UI or a viewer that can't. A UI that
-    # does leaves the line out; the others, the log among them, show it. An
-    # unknown value is dropped, so the line shows everywhere.
-    # +extra+: more fields for the UIs (a toolkit change's summary).
+    # One line to the user (:hook_notice), HookRoutes#notify.
     def hook_notify(text, level, hook, fallback_for: nil, extra: {})
-      level = (level || :info).to_sym
-      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)
-      return @extension_load.hold(notice) && nil if @extension_load.loading?
-
-      in_turn, sink = @turn_state.in_turn_sink
-      if anytime_thread?
-        announce_anytime(notice.merge(between_turns: true))
-      elsif current_init_task
-        announce(notice.merge(between_turns: true))
-      elsif in_turn
-        emit_event(sink, notice)
-      else
-        announce_or_hold(notice.merge(between_turns: true))
-      end
-      nil
+      @hook_routes.notify(text, level, hook, fallback_for: fallback_for, extra: extra)
     end
     private :hook_notify
 
-    # A known fallback_for (a String is symbolized), else nil; an unknown
-    # one is logged once at debug.
-    def notice_fallback(value, hook)
-      return if value.nil?
-
-      fallback = value.to_s.to_sym
-      return fallback if NOTICE_FALLBACKS.include?(fallback)
-
-      @unknown_fallbacks ||= Set.new
-      Log.debug(:hooks, "notice_unknown_fallback", hook: hook.to_s, value: value.to_s) if @unknown_fallbacks.add?(fallback)
-      nil
-    end
-    private :notice_fallback
-
-    # A guardrails line to the user after load (:guardrail_warning, as the
-    # load failures show): a running turn's event, else announced.
-    def guardrail_notify(message)
-      event = { type: :guardrail_warning, message: message.to_s }
-      in_turn, sink = @turn_state.in_turn_sink
-      in_turn ? emit_event(sink, event) : announce_or_hold(event)
-      nil
-    end
+    def guardrail_notify(message) = @hook_routes.guardrail_notify(message)
     private :guardrail_notify
 
-    # A question through the question flow (REPL sync handler, attached TUI,
-    # web), single-select, kind "hook". A --non-interactive run has no one
-    # to ask: nil at once. Anything but an answer (a sync handler's text, no
-    # answer, cancelled) is nil too.
     # @return [Hash, nil] {selected:, freeform:, selected_indices:}
     def hook_ask_user(question, options, header, allow_freeform, hook)
-      @question_desk.ask_for_hook(question, options, header, allow_freeform, hook)
+      @hook_routes.ask_user(question, options, header, allow_freeform, hook)
     end
     private :hook_ask_user
 
-    # Cancel the running turn (reason :hook), after a notice that says why.
-    # The gate denies the rest of a tool batch once the controller is
-    # cancelled; the next request ends the turn as :turn_canceled.
     # @return [Boolean] true when a running turn was cancelled now
-    def hook_stop_turn(reason, hook)
-      ctrl = active_cancel_controller
-      return false unless ctrl && !ctrl.cancelled?
-
-      hook_notify("stopped the turn: #{reason}", :warn, hook)
-      ctrl.cancel!(:hook, { by: hook_source(hook), reason: reason.to_s })
-    end
+    def hook_stop_turn(reason, hook) = @hook_routes.stop_turn(reason, hook)
     private :hook_stop_turn
 
-    # Cut the streaming generation (reason :hook); the turn goes on and asks
-    # the model again (the loops' cut path). No notice: the plugin posts its
-    # own. The bundle and +reason+ go to the log and the retry's nudge.
     # @return [Boolean] true when a streaming generation was cut now
-    def hook_stop_generation(reason, hook)
-      ctrl = active_cancel_controller
-      return false unless ctrl
+    def hook_stop_generation(reason, hook) = @hook_routes.stop_generation(reason, hook)
+    private :hook_stop_generation
 
-      ctrl.cancel_generation!(:hook, { by: hook_source(hook), reason: reason.to_s })
+    # The hook routes (see #initialize for when).
+    def build_hook_routes
+      HookRoutes.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_or_hold: ->(event) { announce_or_hold(event) },
+        emit: ->(sink, event) { emit_event(sink, event) },
+        question_desk: -> { @question_desk },
+        cancel_controller: -> { active_cancel_controller },
+        steer: ->(text, source) { steer(text, source: source) }
+      )
     end
-    private :hook_stop_generation
+    private :build_hook_routes
 
     # ── Ask-user-question (structured qualification) ──────────────────────────
 
@@ -2228,8 +2184,8 @@ module Samagotchi
       # Persist deduped used memories onto the session for Web + reload.
       begin
         session.used_memory_names = used_memory_names
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Log.warn(:memory, "used_memories_store_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       end
       # Notify live observers of the updated memory list (so yellow bar refreshes
       # even without a tool_call event if the preload was the only addition).
@@ -2238,8 +2194,8 @@ module Samagotchi
 
       begin
         emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names })
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Log.warn(:memory, "used_memories_emit_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       end
     end
     private :publish_used_memories
@@ -2676,12 +2632,16 @@ module Samagotchi
           add_init_task(bundle: bundle, label: label, plugin_label: plugin_label, provides_tools: provides_tools,
                         quiet: quiet, timeout: timeout, failed: failed, &block)
         },
-        toolkits: @plugin_kits
+        toolkits: @toolkit_binding.plugin_kits,
+        tool_index: @tool_index,
+        peer_sources: @peer_sources
       )
       # 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.
       @extension_load.load_plugins(registries, failures: @plugin_failures)
+      # Declared once, from what the sources published while they loaded.
+      @tool_index.declare(@tools, failures: @plugin_failures)
     end
 
     # Keep a plugin's new tool set (chi.replace_tools, from any thread)
@@ -2699,100 +2659,42 @@ module Samagotchi
     end
     public :apply_staged_tools!
 
-    # The kits a session's toolkit resolves against: the built-ins, config's
-    # toolkit.kits, the plugins' (Toolkit.kits). Config's are read once per
-    # process, like the plugins': an edit to toolkit.kits never changes a
-    # live session's tools mid-session (a new worker reads it).
-    # @param errors [Array<String>] gets a line per config kit left out
-    # @return [Hash{String => Toolkit::Kit}]
-    def toolkit_kits(errors = [])
-      @config_kits = Toolkit.config_kits unless defined?(@config_kits)
-      Toolkit.kits(config: @config_kits, plugins: @plugin_kits, errors: errors)
-    end
-
-    # The session's toolkit resolved (Toolkit::Resolved): what its next
-    # turn declares. A plain full toolkit is nil, the Registry's "every tool".
-    def resolved_toolkit(session, errors = [])
-      resolved = Toolkit.of(session&.toolkit).resolve(toolkit_kits(errors))
-      resolved.everything? ? nil : resolved
-    end
+    # The session's toolkit (ToolkitBinding): the kits, what its next turn
+    # declares, ctx.use_toolkit and the turn-start apply.
+    def toolkit_kits(errors = []) = @toolkit_binding.kits(errors)
+    def resolved_toolkit(session, errors = []) = @toolkit_binding.resolved(session, errors)
+    def toolkit_explained(toolkit = nil) = @toolkit_binding.explained(toolkit)
+    def toolkit_summary = @toolkit_binding.summary
 
     # The tools this session registered (Tools::Registry), declared or not.
     attr_reader :tools
 
-    # +toolkit+ (the session's by default) as its next turn would declare
-    # it (/toolkit, the UIs' chip).
-    # @return [Toolkit::Explained]
-    def toolkit_explained(toolkit = nil)
-      toolkit ||= Toolkit.of(@session&.toolkit)
-      resolved = toolkit.resolve(toolkit_kits)
-      filter = resolved.everything? ? nil : resolved
-      Toolkit::Explained.new(toolkit: toolkit, resolved: resolved, declared: @tools.entries(toolkit: filter),
-                             left_out: @tools.left_out_names(toolkit: filter), pending: filter != @tools.toolkit)
-    end
-
-    # The session's toolkit for the UIs (the snapshot, command_ran): nil on
-    # full, or with no session.
-    def toolkit_summary
-      @session && toolkit_explained.summary
-    end
     public :tools, :toolkit_kits, :resolved_toolkit, :toolkit_explained, :toolkit_summary
 
-    # A plugin's ctx.use_toolkit: put the session on toolkit +name+, saved,
-    # when it has no model reply yet and no turn runs (D3: no confirm from
-    # plugins), and tell the user as /toolkit would; it applies at the next
-    # turn's start.
+    # A plugin's ctx.use_toolkit (ToolkitBinding#use).
     # @return [Boolean] whether it was staged
     # @raise [ArgumentError] an unknown toolkit
-    def use_toolkit(name)
-      raise ArgumentError, "no toolkit named #{name}" unless toolkit_kits.key?(name)
-      return false if @session.nil? || turn_running? || history?
-
-      toolkit = Toolkit.new(name: name)
-      return true if @session.toolkit == toolkit
-
-      @session.toolkit = toolkit
-      @session.save(state_dir: session_state_dir)
-      hook_notify("toolkit: #{name} from the next turn's start", :info, "toolkit", extra: { toolkit: toolkit_summary })
-      true
-    end
+    def use_toolkit(name) = @toolkit_binding.use(name)
     public :use_toolkit
 
-    # Resolve the session's toolkit into the Registry, on the turn thread at
-    # a turn's start (before its prompt is built), and build the prompts
-    # again when what it declares changed. A name that doesn't resolve (a
-    # typo, an uninstalled bundle) declares everything for now and says so
-    # once; the saved toolkit stays as it is.
+    # At a turn's start (ToolkitBinding#apply!).
     # @return [Boolean] whether the declared tools changed
-    def apply_toolkit!(session, on_event = nil)
-      errors = []
-      resolved = Toolkit.of(session&.toolkit).resolve(toolkit_kits(errors))
-      warn_toolkit(session, resolved, errors, on_event)
-      resolved = nil if resolved.everything?
-      return false if resolved == @tools.toolkit
-
-      @tools.toolkit = resolved
-      @prompt_builder&.reset!
-      true
-    end
+    def apply_toolkit!(session, on_event = nil) = @toolkit_binding.apply!(session, on_event)
     private :apply_toolkit!
 
-    # The toolkit's load warnings, each once per process: a name that
-    # didn't resolve, config kits left out.
-    def warn_toolkit(session, resolved, errors, on_event)
-      lines = errors.dup
-      if resolved.fallback
-        lines << "#{Toolkit.of(session&.toolkit).label}: #{resolved.fallback}; this session declares every tool (full) " \
-                 "until it resolves"
-      end
-      @toolkit_warned ||= []
-      (lines - @toolkit_warned).each do |line|
-        @toolkit_warned << line
-        Log.warn(:config, "toolkit_unresolved", message: line)
-        emit_event(on_event, { type: :guardrail_warning, message: line, label: "toolkit" })
-      end
+    # The session's toolkit (see #initialize for when).
+    def build_toolkit_binding
+      ToolkitBinding.new(
+        tools: -> { @tools },
+        session: -> { @session },
+        state_dir: -> { session_state_dir },
+        can_stage: -> { !turn_running? && !history? },
+        reset_prompt: -> { @prompt_builder&.reset! },
+        emit: ->(sink, event) { emit_event(sink, event) },
+        notify: ->(text, level, source, extra:) { hook_notify(text, level, source, extra: extra) }
+      )
     end
-    private :warn_toolkit
+    private :build_toolkit_binding
 
     # The tools changed (a plugin's chi.tools_changed!): the system prompts,
     # which declare them, are built again on the next turn.
@@ -2820,7 +2722,7 @@ module Samagotchi
         steer: ->(text, label) { steer(text, source: hook_source(label)) },
         stop_turn: ->(reason, label) { hook_stop_turn(reason, label) },
         stop_generation: ->(reason, label) { hook_stop_generation(reason, label) },
-        toolkit: -> { @session && Toolkit.of(@session.toolkit).name },
+        toolkit: -> { @toolkit_binding.name },
         declared_tools: -> { toolkit_explained.declared.map(&:name) },
         use_toolkit: ->(name) { use_toolkit(name) },
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
@@ -2973,7 +2875,8 @@ module Samagotchi
     def with_generation_report(event)
       report = @metrics.finish_generation
       event.merge(speed: report.speed&.to_h, tokens: report.tokens, served_expected_by: served_expected_by(event[:served_model]))
-    rescue StandardError
+    rescue StandardError => e
+      Log.warn(:turn, "generation_report_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       event
     end
     private :with_generation_report
@@ -2990,7 +2893,8 @@ module Samagotchi
       # Capture used memories synchronously in the turn thread.
       read_names = begin
         @used_memories.capture(event, muted: @muted_memory_names)
-      rescue StandardError
+      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
@@ -2999,8 +2903,9 @@ module Samagotchi
       if on_event
         begin
           on_event.call(event)
-        rescue StandardError
+        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