samagotchi 0.65.0 → 0.66.0

data/lib/samagotchi/session_setup.rb

@@ -3,6 +3,7 @@
 require_relative "llm_context_override"
 require_relative "reasoning_history"
 require_relative "thinking"
+require_relative "toolkit"
 
 module Samagotchi
   # A session's own settings that come before its model's, carried as one
@@ -12,27 +13,33 @@ module Samagotchi
   # +thinking+ a level Symbol (Thinking.session_level) or nil,
   # +reasoning_history+ a level Symbol (ReasoningHistory.session_level) or nil,
   # +appended_prompt_files+ the absolute paths chi --append-system-prompt
-  # named (their text goes into the system prompt; [] with none).
+  # named (their text goes into the system prompt; [] with none),
+  # +toolkit+ a Toolkit or nil (SessionManager.spawn_session gives the
+  # session config's toolkit.default then).
   #
   # It doesn't save itself: the session keeps each setting in its own field
   # and file key, and resolves it on its own. A delegate child starts
   # without one; a continue and a fork copy their session's (.of).
-  SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files) do
-    def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [])
+  SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files, :toolkit) do
+    def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [], toolkit: nil)
       super(llm_context: llm_context, thinking: thinking, reasoning_history: reasoning_history,
-            appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze)
+            appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze, toolkit: toolkit)
     end
 
-    def empty? = llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty?
+    def empty?
+      llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty? && toolkit.nil?
+    end
 
-    # A session's own setup, for a session that starts from it.
+    # A session's own setup, for a session that starts from it. Its
+    # toolkit always: one from before toolkits is full (Toolkit.of), not
+    # whatever config's default is now.
     # @param session [Session, nil]
     # @return [SessionSetup]
     def self.of(session)
       return new if session.nil?
 
       new(llm_context: session.llm_context, thinking: session.thinking, reasoning_history: session.reasoning_history,
-          appended_prompt_files: session.appended_prompt_files)
+          appended_prompt_files: session.appended_prompt_files, toolkit: Toolkit.of(session.toolkit))
     end
   end
 end

data/lib/samagotchi/system_prompt.rb

@@ -317,7 +317,7 @@ module Samagotchi
         "Project memories:\n#{indexes[:project]}",
         "System memories:\n#{indexes[:system]}"
       ].join("\n\n")
-      stable = [thinking_token + base, rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
+      stable = [thinking_token + base, not_loaded_line(layers), rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
                 project_specific_description, appended_section, memory_sections]
       stable_text = stable.compact.join("\n")
       volatile = [current_model, project_location, current_session].compact
@@ -328,6 +328,21 @@ module Samagotchi
       with_tail_declarations(prompt, chat: chat, layers: layers)
     end
 
+    # The tools the session's toolkit leaves out, named once right after the
+    # base prompt: sessions on another toolkit already differ at the tools,
+    # and nothing later (a memory write) moves it. nil when none are (full):
+    # the prompt is what it was before toolkits.
+    def not_loaded_line(layers)
+      registry = @tools_lookup.call
+      return nil unless registry.respond_to?(:left_out_names)
+
+      names = registry.left_out_names(layers: layers)
+      return nil if names.empty?
+
+      "Not loaded in this session (toolkit #{registry.toolkit&.name}): #{names.join(", ")}. " \
+        "Only the user can load one (/toolkit add <name>)."
+    end
+
     def with_tail_declarations(prompt, chat:, layers:)
       chat || !gemma_tail_declarations? ? prompt : prompt.rstrip + tool_declarations(layers)
     end

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -46,17 +46,23 @@ module Samagotchi
       # @param thinking [String, nil] --thinking as typed: a new session
       #   starts with it as its own level; a resumed or attached one's
       #   worker gets a /thinking, after those
+      # @param toolkit [Toolkit, nil] --toolkit/--tool/--no-tool: a new
+      #   session's toolkit (config's toolkit.default without); an existing
+      #   session keeps its own
+      # @param toolkit_flags [Array<String>] which of those were given, for
+      #   the line an existing session's run prints
       # @param state_dir [String, nil] where the sessions are (the default
       #   state dir by default): the worker's, for the attached loop too
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
-              memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], state_dir: nil)
+              memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
+              toolkit_flags: [], state_dir: nil)
         state_dir ||= Session.default_state_dir
         client = connect(attach: attach, shared: shared, resume: resume, model: model, state_dir: state_dir,
                          memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking,
-                         appended_prompt_files: appended_prompt_files)
+                         appended_prompt_files: appended_prompt_files, toolkit: toolkit, toolkit_flags: toolkit_flags)
         commands = []
         commands << "/model #{model}" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
@@ -123,10 +129,12 @@ module Samagotchi
       # @return [BridgeClient] a client for the live Bridge of the session
       # @raise [Error]
       def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
-                  memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], err: $stderr)
+                  memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
+                  toolkit_flags: [], err: $stderr)
         sd = state_dir || Session.default_state_dir
         if attach || resume
-          warn_memory_flags_ignored(attach || resume, memories, muted_memories, err, appended_prompt_files: appended_prompt_files)
+          warn_memory_flags_ignored(attach || resume, memories, muted_memories, err, appended_prompt_files: appended_prompt_files,
+                                                                                     toolkit_flags: toolkit_flags)
         end
         if attach
           live = connect_existing(attach, sd)
@@ -143,7 +151,8 @@ module Samagotchi
                                                  memories: memories, muted_memories: muted_memories,
                                                  setup: SessionSetup.new(llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context),
                                                                          thinking: Thinking.session_level(thinking),
-                                                                         appended_prompt_files: appended_prompt_files))
+                                                                         appended_prompt_files: appended_prompt_files,
+                                                                         toolkit: toolkit))
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
         client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")
@@ -159,14 +168,15 @@ module Samagotchi
       end
 
       # An existing session's prompt is built from its own session fields:
-      # --memory/--mute/--append-system-prompt given with --attach or
-      # --resume are ignored, with a line saying so (printed before the live
-      # region opens).
-      def warn_memory_flags_ignored(session_id, memories, muted_memories, err, appended_prompt_files: [])
+      # --memory/--mute/--append-system-prompt and the toolkit flags given
+      # with --attach or --resume are ignored, with a line saying so (printed
+      # before the live region opens).
+      def warn_memory_flags_ignored(session_id, memories, muted_memories, err, appended_prompt_files: [], toolkit_flags: [])
         flags = []
         flags << "--memory" unless Array(memories).empty?
         flags << "--mute" unless Array(muted_memories).empty?
         flags << "--append-system-prompt" unless Array(appended_prompt_files).empty?
+        flags.concat(toolkit_flags)
         return if flags.empty?
 
         verb = flags.size == 1 ? "applies" : "apply"

data/lib/samagotchi/terminal_ui.rb

@@ -97,10 +97,15 @@ module Samagotchi
     # @param appended_prompt_files [Array<String>] --append-system-prompt's
     #   files (absolute): a new session saves them; a resumed one's own come
     #   first, and the merge goes only to the Engine (as --memory's does)
+    # @param toolkit [Toolkit, nil] --toolkit/--tool/--no-tool: a new
+    #   session's toolkit (config's toolkit.default without); a resumed one
+    #   keeps its own, with a line naming +toolkit_flags+ (the flags given)
     def initialize(prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
                    spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {}, thinking: nil,
-                   appended_prompt_files: [])
+                   appended_prompt_files: [], toolkit: nil, toolkit_flags: [])
       @scratch        = scratch
+      @toolkit        = toolkit
+      @toolkit_flags  = toolkit_flags
       @thinking_word  = thinking
       @prompt         = prompt
       @llm_context_words = llm_context
@@ -269,7 +274,7 @@ module Samagotchi
         preloaded_memory_names: @requested_memories,
         muted_memory_names: @muted_memory_names,
         scratch: @scratch,
-        setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files)
+        setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files, toolkit: @toolkit || Toolkit.configured)
       ))
       # --llm-context*: the session's own values, over a resumed one's.
       # Saved at once on a resumed one: leaving before a turn keeps them.
@@ -279,6 +284,7 @@ module Samagotchi
         session.thinking = Thinking.session_level(@thinking_word) if @thinking_word
         session.save if @resume_session
       end
+      warn_toolkit_flags_ignored(session) if @resume_session
       claim_session!(session.id) unless @owner_lock
       # A turn a worker died in (TurnCheckpoint): ended as canceled, with its
       # note, before this REPL's first turn appends after it.
@@ -714,6 +720,16 @@ module Samagotchi
       end
     end
 
+    # The toolkit flags are a new session's: a resumed one keeps its own
+    # toolkit (as attached mode says it, AttachLauncher).
+    def warn_toolkit_flags_ignored(session)
+      return if @toolkit_flags.empty?
+
+      names = @toolkit_flags.size > 1 ? "#{@toolkit_flags[0..-2].join(", ")} and #{@toolkit_flags.last}" : @toolkit_flags.first
+      warn "(#{names} #{@toolkit_flags.size == 1 ? "applies" : "apply"} to a new session; #{session.id}'s prompt is already built)"
+    end
+    private :warn_toolkit_flags_ignored
+
     private
 
     # Interactive REPL loop. Session seed + messages are built by #run and

data/lib/samagotchi/tool_runner.rb

@@ -49,8 +49,11 @@ module Samagotchi
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       # The gate runs first, so tool_call_started shows the call that runs.
+      # A tool the session's toolkit leaves out skips it: no before_tool_call
+      # hook, no approval card for a call that can't run (KernelLoop#dispatch
+      # answers it with the not-loaded error).
       original = call.dup
-      verdict = evaluate(call, iteration, params)
+      verdict = left_out?(call) ? Guardrails::Verdict.new(call: call) : evaluate(call, iteration, params)
       call = verdict.call
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       label = plugin_label(call[:name])
@@ -265,6 +268,15 @@ module Samagotchi
     # The kernel's tools, for the activity line of a tool that isn't built in.
     def tools = @kernel.tools
 
+    # A real tool the session's toolkit leaves out of this turn.
+    def left_out?(call)
+      registry = tools
+      return false unless registry.respond_to?(:left_out) && !call[:name].nil?
+
+      layers = @kernel.respond_to?(:llm_context_layers) ? @kernel.llm_context_layers : []
+      !registry.left_out(call[:name], layers: layers).nil?
+    end
+
     # A tool the registry has from a plugin (not core, not unknown).
     def plugin_tool?(name)
       entry = tools && !name.nil? ? tools[name] : nil

data/lib/samagotchi/toolkit.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Samagotchi
+  # A session's toolkit: which of the registered tools its prompts declare
+  # (docs/sessions.md, "Toolkits"). Saved in the session file as given
+  # ({"name" => "lean", "add" => [], "remove" => []}) when the session is
+  # created, kept by continues and forks, and never resolved again from
+  # config: a respawned worker declares what the session was created with.
+  # A session without one (a file from before toolkits) is on FULL.
+  #
+  # +name+ names a Kit (the built-ins, config's toolkit.kits, a plugin's
+  # chi.toolkit); +add+ and +remove+ are the session's own changes on top
+  # (--tool / --no-tool, /toolkit add|remove). #resolve against the kits
+  # known gives the Resolved the Registry filters by.
+  Toolkit = Data.define(:name, :add, :remove) do
+    def initialize(name:, add: [], remove: [])
+      super(name: name.to_s.strip, add: Toolkit.tool_names(add), remove: Toolkit.tool_names(remove))
+    end
+
+    # @return [Hash] the session file's "toolkit"
+    def to_file = { "name" => name, "add" => add, "remove" => remove }
+
+    # The plain form the snapshot and the web carry.
+    def to_h = { name: name, add: add, remove: remove }
+
+    # This toolkit with +tool+ declared (/toolkit add): a tool it removed
+    # comes out of +remove+ (back to its kit's), any other goes into +add+.
+    def adding(tool)
+      tool = tool.to_s
+      remove.include?(tool) ? with(remove: remove - [tool]) : with(add: (add + [tool]).uniq)
+    end
+
+    # This toolkit with +tool+ left out (/toolkit remove), the other way.
+    def removing(tool)
+      tool = tool.to_s
+      add.include?(tool) ? with(add: add - [tool]) : with(remove: (remove + [tool]).uniq)
+    end
+
+    # How the UIs name it: "lean", "lean +web_fetch -memory_write".
+    def label = [name, *add.map { |tool| "+#{tool}" }, *remove.map { |tool| "-#{tool}" }].join(" ")
+
+    def full? = name == Toolkit::FULL && add.empty? && remove.empty?
+
+    # The kit +name+ names, from +kits+ (Toolkit.kits), with the session's
+    # own +add+ and +remove+ on top. An unknown name, a base that is, or a
+    # cycle falls back to FULL with the reason in Resolved#fallback; the
+    # saved toolkit is untouched, so a reinstalled bundle gets it back.
+    # @param kits [Hash{String => Kit}]
+    # @return [Resolved]
+    def resolve(kits)
+      Toolkit.resolve_kit(name, kits).changed(add: add, remove: remove)
+    rescue Toolkit::Unresolved => e
+      Toolkit.resolve_kit(Toolkit::FULL, kits).changed(add: add, remove: remove).with(fallback: e.message)
+    end
+  end
+
+  class Toolkit
+    FULL = "full"
+    LEAN = "lean"
+    CHILD = "child"
+
+    # A name that can't be resolved (unknown, a cycle).
+    class Unresolved < StandardError; end
+
+    # A toolkit as a session's next turn would declare it (Engine
+    # #toolkit_explained): +toolkit+ as saved, +resolved+, the Registry
+    # +declared+ entries and the names it leaves out (+left_out+), and
+    # whether that isn't what the Registry declares now (+pending+: it
+    # applies at the next turn's start).
+    Explained = Data.define(:toolkit, :resolved, :declared, :left_out, :pending) do
+      # What the prompt carries of it: the declared names and, when it
+      # leaves tools out, the kit name the not-loaded line gives. Two equal
+      # keys build the same prompt (/toolkit's "no change", its cost).
+      def prompt_key = [declared.map(&:name), left_out.empty? ? nil : resolved.name]
+
+      # What the UIs show (the snapshot, command_ran): nil when it declares
+      # every tool on full (full, full +delegate), which has no chip.
+      def summary
+        return nil if toolkit.name == Toolkit::FULL && left_out.empty? && resolved.fallback.nil?
+
+        { name: toolkit.name, label: toolkit.label, left_out: left_out, fallback: resolved.fallback }
+      end
+    end
+
+    # Tool names as a list of unique, stripped strings.
+    def self.tool_names(names) = Array(names).map { |tool| tool.to_s.strip }.reject(&:empty?).uniq
+
+    # A named list of declared tools: +tools+ (:all, every built-in; or the
+    # built-in names) when it has no +base+, else its +base+'s with +add+
+    # and +remove+. +source+: "core", "config", or the bundle that declared
+    # it (chi.toolkit).
+    Kit = Data.define(:name, :base, :tools, :add, :remove, :source) do
+      def initialize(name:, base: nil, tools: nil, add: [], remove: [], source: "core")
+        super(name: name.to_s, base: base&.to_s, tools: tools == :all ? :all : Toolkit.tool_names(tools),
+              add: Toolkit.tool_names(add), remove: Toolkit.tool_names(remove), source: source.to_s)
+      end
+    end
+
+    # The built-ins `lean` declares: the file and shell tools, memories,
+    # the task tools (execute's hand-over, turn notes and task_wait's tail
+    # name the trio), questions, web_fetch, and context_read (core notes
+    # tell the model to call it).
+    LEAN_TOOLS = %w[
+      execute read write edit memory_read memory_write task_create task_wait task_get task_list task_stop
+      ask_user_question web_fetch context_read
+    ].freeze
+
+    BUILTIN_KITS = [
+      Kit.new(name: FULL, tools: :all),
+      Kit.new(name: LEAN, tools: LEAN_TOOLS),
+      # A delegate child: it reports to its parent (send_note; the
+      # delegated-by line names it) and leaves memory writes to it.
+      Kit.new(name: CHILD, base: LEAN, add: %w[send_note], remove: %w[memory_write])
+    ].to_h { |kit| [kit.name, kit] }.freeze
+
+    # What a toolkit declares, the Registry's filter: every built-in
+    # (+all_core+) or the ones in +core+, every plugin tool and every tool
+    # an LLM context layer gates (forget_outputs), but for +removed+;
+    # +added+ declares any registered tool. +fallback+: why the session's
+    # own toolkit couldn't be resolved (this is FULL then), nil when it was.
+    Resolved = Data.define(:name, :all_core, :core, :added, :removed, :fallback) do
+      def initialize(name:, all_core: false, core: [], added: [], removed: [], fallback: nil)
+        super(name: name.to_s, all_core: all_core, core: core.dup.freeze, added: added.dup.freeze,
+              removed: removed.dup.freeze, fallback: fallback)
+      end
+
+      # Every built-in and nothing removed: what no toolkit declares.
+      def everything? = all_core && removed.empty?
+
+      # @param entry [Tools::Registry::Entry]
+      def declares?(entry)
+        return false if removed.include?(entry.name)
+        return true if added.include?(entry.name) || !entry.core? || !entry.layer.nil?
+
+        all_core || core.include?(entry.name)
+      end
+
+      # This with +add+ declared and +remove+ left out, in that order of
+      # the kit's own words: a later change wins.
+      def changed(add: [], remove: [])
+        added = self.added - remove
+        removed = self.removed - add
+        with(added: (added + add).uniq, removed: (removed + remove).uniq)
+      end
+    end
+
+    # The session file's "toolkit": a Toolkit, nil for none (a file from
+    # before toolkits, or one that isn't a toolkit), which reads as FULL.
+    def self.from_file(value)
+      case value
+      when Hash
+        name = value["name"] || value[:name]
+        return nil if name.to_s.strip.empty?
+
+        new(name: name, add: value["add"] || value[:add], remove: value["remove"] || value[:remove])
+      when String, Symbol
+        value.to_s.strip.empty? ? nil : new(name: value)
+      end
+    end
+
+    # The toolkit a new session is stored on: config's toolkit.default, or
+    # toolkit.child for a delegate child; FULL when unset. As named: the
+    # worker resolves it (plugins' kits load there).
+    def self.configured(delegate: false)
+      name = Config.get(delegate ? "toolkit.child" : "toolkit.default").to_s.strip
+      new(name: name.empty? ? FULL : name)
+    end
+
+    # config.yml's toolkit.kits (a map of name => {base:, add:, remove:}),
+    # nil when it has none.
+    def self.config_kits
+      section = ConfigFile.section("toolkit")
+      section.is_a?(Hash) ? section["kits"] : nil
+    rescue StandardError
+      nil
+    end
+
+    # A new session's toolkit from chi --toolkit NAME / --tool / --no-tool
+    # (each repeatable, a comma list too): NAME (config's toolkit.default
+    # without one) with those tools added and left out; nil when none was
+    # given. A tool in both is left out.
+    def self.from_flags(name: nil, add: [], remove: [])
+      add = split_names(add)
+      remove = split_names(remove)
+      return nil if name.to_s.strip.empty? && add.empty? && remove.empty?
+
+      base = name.to_s.strip.empty? ? configured.name : name
+      new(name: base, add: add - remove, remove: remove)
+    end
+
+    def self.split_names(values) = tool_names(Array(values).flat_map { |value| value.to_s.split(",") })
+    private_class_method :split_names
+
+    # The toolkit a session is on: its own, or FULL without one.
+    def self.of(toolkit) = toolkit || new(name: FULL)
+
+    # What a toolkit change costs the prompt cache (CacheConfirm): the
+    # declared tools are the front of every request, so any change to them
+    # (or to the not-loaded line) is :full; nil when they stay the same.
+    # @param before [Object] what the prompt carries now (Explained#prompt_key)
+    # @param after [Object] what it would carry after the change
+    def self.cache_cost(before, after) = before == after ? nil : :full
+
+    # @return [Resolved] +name+'s kit through its bases
+    # @raise [Unresolved] unknown, or a cycle
+    def self.resolve_kit(name, kits, seen = [])
+      raise Unresolved, "no toolkit named #{name}" unless (kit = kits[name])
+      raise Unresolved, "toolkit #{name}'s bases make a cycle (#{(seen + [name]).join(" → ")})" if seen.include?(name)
+
+      base = if kit.base
+               resolve_kit(kit.base, kits, seen + [name])
+             else
+               Resolved.new(name: name, all_core: kit.tools == :all, core: kit.tools == :all ? [] : kit.tools)
+             end
+      base.changed(add: kit.add, remove: kit.remove).with(name: name)
+    end
+
+    # The kits known: the built-ins, then config's toolkit.kits, then the
+    # plugins' (chi.toolkit). A config kit with a built-in's name is left
+    # out (one it can't redefine) with a line in +errors+, and so is one
+    # that isn't a {base:, add:, remove:} map.
+    # @param config [Hash, nil] toolkit.kits
+    # @param plugins [Array<Kit>]
+    # @param errors [Array<String>] gets a line per kit left out
+    # @return [Hash{String => Kit}]
+    def self.kits(config: nil, plugins: [], errors: [])
+      kits = BUILTIN_KITS.dup
+      (config.is_a?(Hash) ? config : {}).each do |name, spec|
+        name = name.to_s
+        if kits.key?(name)
+          errors << "toolkit.kits.#{name}: #{name} is a built-in toolkit"
+        elsif !spec.is_a?(Hash)
+          errors << "toolkit.kits.#{name}: expected {base:, add:, remove:}"
+        else
+          spec = spec.transform_keys(&:to_s)
+          kits[name] = Kit.new(name: name, base: spec["base"] || FULL, add: spec["add"], remove: spec["remove"],
+                               source: "config")
+        end
+      end
+      plugins.each { |kit| kits[kit.name] ||= kit }
+      kits
+    end
+  end
+end

data/lib/samagotchi/toolkit_command.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cache_confirm"
+require_relative "toolkit"
+
+module Samagotchi
+  # /toolkit, the session's toolkit (Session#toolkit): with no argument,
+  # the tools its next turn declares with their estimated tokens, the
+  # toolkit and the tools it leaves out; `/toolkit NAME` puts the session
+  # on another toolkit (its own adds and removes go), `/toolkit add TOOL`
+  # and `/toolkit remove TOOL` change one tool. A change is saved at once
+  # and applies at the next turn's start (Engine#apply_toolkit!). The
+  # declared tools are the front of every request, so once the session has
+  # a model reply a change asks first (CacheConfirm); --yes applies it.
+  class ToolkitCommand
+    NAME = "/toolkit"
+    USAGE = "usage: #{NAME} [NAME | add TOOL | remove TOOL]".freeze
+    # Characters per token for the estimates (context.chars_per_token's
+    # default; a listing, not a meter).
+    CHARS_PER_TOKEN = 4.0
+
+    # @param engine [Engine] #session, #toolkit_explained, #toolkit_kits,
+    #   #tools, #history?
+    # @param save [#call] saves the session after a change
+    def initialize(engine:, save:)
+      @engine = engine
+      @save = save
+    end
+
+    # @param args [String] what follows /toolkit (--yes anywhere)
+    # @param confirm [Boolean] ask before a change once the session has a
+    #   model reply (CacheConfirm); false applies it at once
+    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
+    #   whether the toolkit changed, and the confirm it asks for (nothing
+    #   changed then)
+    # @raise [ArgumentError] an unknown toolkit or tool, or bad words
+    def run(args, confirm: true)
+      words, yes = CacheConfirm.split(args, downcase: false)
+      return [listing(@engine.toolkit_explained), false, nil] if words.empty?
+
+      session = @engine.session or raise ArgumentError, "no session yet"
+      before = @engine.toolkit_explained
+      after = @engine.toolkit_explained(changed(before.toolkit, words.split))
+      # Nothing the prompt carries changes (full +delegate on full): not saved.
+      return [listing(before) + "\n(no change to what the next turn declares)", false, nil] if after.prompt_key == before.prompt_key
+
+      cost = Toolkit.cache_cost(before.prompt_key, after.prompt_key)
+      if confirm && !yes && CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: !cost.nil?)
+        step = CacheConfirm.confirm(NAME, words)
+        return [[change_line(before, after), "The tools are the front of every request: the whole prompt is read " \
+                                             "again from them on.", step.text].join("\n"), false, step]
+      end
+
+      session.toolkit = after.toolkit
+      @save.call(session)
+      [[listing(after), "From the next turn's start (a running turn keeps its tools)."].join("\n"), true, nil]
+    end
+
+    # The toolkit, its declared tools with tokens, and the ones left out.
+    def listing(explained)
+      toolkit = explained.toolkit
+      lines = ["toolkit: #{toolkit.label}#{" (applies at the next turn's start)" if explained.pending}"]
+      if (fallback = explained.resolved.fallback)
+        lines << "  #{fallback}: every tool is declared (full) until it resolves"
+      end
+      declared = explained.declared
+      lines << "  declared (#{declared.size}, ~#{format_tokens(declared.sum { |entry| tokens(entry) })} tokens): " \
+               "#{declared.map { |entry| "#{entry.name} ~#{format_tokens(tokens(entry))}" }.join(", ")}"
+      left_out = explained.left_out
+      lines << "  not loaded: #{left_out.empty? ? "none" : left_out.join(", ")}"
+      lines << "  toolkits: #{@engine.toolkit_kits.keys.join(", ")}; #{USAGE.delete_prefix("usage: ")} changes it"
+      lines.join("\n")
+    end
+
+    private
+
+    # +toolkit+ after the words: NAME, add TOOL…, remove TOOL….
+    def changed(toolkit, words)
+      verb, *tools = words
+      case verb.downcase
+      when "add", "remove"
+        raise ArgumentError, "#{NAME} #{verb} needs a tool name\n#{USAGE}" if tools.empty?
+
+        tools.reduce(toolkit) do |kit, tool|
+          raise ArgumentError, "no tool named #{tool} in this session" unless @engine.tools.key?(tool)
+
+          verb.casecmp?("add") ? kit.adding(tool) : kit.removing(tool)
+        end
+      else
+        raise ArgumentError, "#{NAME} takes one toolkit name\n#{USAGE}" unless tools.empty?
+
+        kits = @engine.toolkit_kits
+        raise ArgumentError, "no toolkit named #{verb} (toolkits: #{kits.keys.join(", ")})" unless kits.key?(verb)
+
+        Toolkit.new(name: verb)
+      end
+    end
+
+    def change_line(before, after)
+      added = names(after) - names(before)
+      removed = names(before) - names(after)
+      parts = []
+      parts << "declares #{added.join(", ")}" unless added.empty?
+      parts << "leaves out #{removed.join(", ")}" unless removed.empty?
+      parts << "declares the same tools under its own name" if parts.empty?
+      "Switching to #{after.toolkit.label} #{parts.join("; ")}."
+    end
+
+    def names(explained) = explained.declared.map(&:name)
+
+    # A tool's schema in tokens, estimated from its JSON.
+    def tokens(entry) = (JSON.generate(entry.schema).length / CHARS_PER_TOKEN).round
+
+    def format_tokens(count) = count >= 1000 ? format("%.1fk", count / 1000.0) : count.to_s
+  end
+end