samagotchi 0.131.0 → 0.133.0

data/lib/samagotchi/home_command.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "chi_home"
+require_relative "home_doctor"
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "installed_gem"
+require_relative "paths"
+require_relative "version"
+
+module Samagotchi
+  # `chi home`: the chi home (ChiHome), the Ruby every chi launch boots.
+  # Shows it, sets it (`chi home set [--ruby PATH]`), and checks it
+  # (`chi home doctor`, HomeDoctor's rows).
+  class HomeCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi home [set [--ruby PATH] | doctor]
+        (none)            show the chi home: its Ruby, the chi it runs, its gem home and path, mise
+        set               record this chi's Ruby and gem path as the home (a chruby shell's
+                          GEM_HOME/GEM_PATH are part of it)
+        set --ruby PATH   record that Ruby (its own gem dirs) as the home; it must have samagotchi
+                          (gem install samagotchi with it first)
+        doctor            check the home (its Ruby is there and has samagotchi) and what should
+                          follow it: this chi, the desktop helper, sessions, the tools' chi script,
+                          this project's Gemfile.lock, mise and the last worker's project env
+        Every chi launch (workers, chi web's restart and Update, the macOS helper's next
+        chi desktop install or upgrade) boots the home's Ruby with the home's gems. Saved in
+        #{Paths.tilde(ChiHome.path)}.
+    TEXT
+
+    SUBCOMMANDS = %w[set doctor].freeze
+    FLAGS = {
+      nil => CLI::Flags.new(help: HELP_WORDS, args: false),
+      "set" => CLI::Flags.new(help: HELP_WORDS, args: false) { |f| f.value "--ruby" },
+      "doctor" => CLI::Flags.new(help: HELP_WORDS, args: false)
+    }.freeze
+
+    # @param path [String] home.json
+    # @param probe [#call] (ruby) → ChiHome::Record or nil (ChiHome.probe)
+    # @param doctor [#call] (home) → HomeDoctor
+    def initialize(argv, stdout: $stdout, stderr: $stderr, path: ChiHome.path, gem_spec: InstalledGem.spec,
+                   env: ENV, probe: nil, doctor: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @path = path
+      @gem_spec = gem_spec
+      @env = env
+      @probe = probe || ->(ruby) { ChiHome.probe(ruby, env: env) }
+      @doctor = doctor || lambda { |home|
+        HomeDoctor.new(home: home, env: env, gem_spec: gem_spec, helper: HomeDoctor.default_helper(env: env))
+      }
+    end
+
+    # @return [Integer] 0, 1 (no usable home, a refusal), 2 usage
+    def run
+      @sub = SUBCOMMANDS.include?(@argv.first) ? @argv.first : nil
+      parsed = parse_flags(FLAGS.fetch(@sub), @sub ? @argv[1..] : @argv)
+      return parsed if parsed.is_a?(Integer)
+
+      case @sub
+      when "set" then run_set(parsed.options)
+      when "doctor" then run_doctor
+      else run_show
+      end
+    rescue ChiHome::Invalid => e
+      error_line("#{command_name}: #{e.message} (chi home set rewrites it)")
+      CLI::Exit::FAILED
+    end
+
+    private
+
+    def command_name = @sub ? "chi home #{@sub}" : "chi home"
+    def usage_on_error = nil
+
+    def run_show
+      home = ChiHome.read(path: @path)
+      unless home
+        @stdout.puts("no chi home: chi launches on the Ruby that starts it (chi home set records this one, #{running_ruby})")
+        return CLI::Exit::OK
+      end
+
+      rows(home).each { |label, value| @stdout.puts("#{label.ljust(9)} #{value}") }
+      problem = ChiHome.problem(home)
+      @stdout.puts("problem   #{problem} (chi home doctor)") if problem
+      problem ? CLI::Exit::FAILED : CLI::Exit::OK
+    end
+
+    def rows(home)
+      list = [["ruby", home.ruby], ["chi", home.newest_version&.to_s || "none"], ["gem home", home.gem_home],
+              ["gem path", home.gem_path], ["mise", home.mise || "none"],
+              ["set", "#{home.set_at} by chi #{home.set_by_version}"]]
+      list << ["running", "chi #{VERSION} on #{running_ruby}"] unless running_home?(home)
+      list
+    end
+
+    def running_home?(home) = @gem_spec && home.running_here? && home.newest_version.to_s == VERSION
+
+    def running_ruby = "#{RbConfig.ruby}#{" (a checkout)" unless @gem_spec}"
+
+    def run_set(options)
+      home = options[:ruby] ? probed(options[:ruby]) : ChiHome.from_running(env: @env)
+      return CLI::Exit::FAILED unless home
+
+      if (problem = ChiHome.problem(home))
+        error_line("#{command_name}: #{problem}: gem install samagotchi with #{home.ruby} first")
+        return CLI::Exit::FAILED
+      end
+
+      ChiHome.write!(home, path: @path)
+      @stdout.puts("chi home set to #{home.ruby} (chi #{home.newest_version}); new workers and launches boot it")
+      CLI::Exit::OK
+    rescue SystemCallError => e
+      error_line("#{command_name}: couldn't write #{Paths.tilde(@path)}: #{e.message}")
+      CLI::Exit::FAILED
+    end
+
+    # The home a --ruby names: this one's (with this shell's gem path) when
+    # it is the running Ruby, else asked of it.
+    def probed(ruby)
+      path = File.expand_path(ruby)
+      unless File.file?(path) && File.executable?(path)
+        error_line("#{command_name}: no Ruby at #{ruby}")
+        return nil
+      end
+      return ChiHome.from_running(env: @env) if ChiHome.real(path) == ChiHome.real(RbConfig.ruby)
+
+      home = @probe.call(path)
+      error_line("#{command_name}: #{ruby} didn't answer as a Ruby") unless home
+      home
+    end
+
+    # The home's rows and what should follow it (HomeDoctor); exit 1 when
+    # one fails.
+    def run_doctor
+      rows = @doctor.call(ChiHome.read(path: @path)).rows
+      rows.each { |row| @stdout.puts(row.to_s) }
+      rows.any? { |row| row.status == :fail } ? CLI::Exit::FAILED : CLI::Exit::OK
+    end
+  end
+end

data/lib/samagotchi/home_doctor.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "chi_home"
+require_relative "chi_shim"
+require_relative "config"
+require_relative "desktop"
+require_relative "home_notice"
+require_relative "installed_gem"
+require_relative "log_path"
+require_relative "paths"
+require_relative "project_env"
+require_relative "session"
+require_relative "version"
+
+module Samagotchi
+  # `chi home doctor`'s rows: the chi home (ChiHome) and what should follow
+  # it, each one line with a status and what to run. One check each; the
+  # text is the condition owner's (ChiHome, HomeNotice, Desktop::MacOS,
+  # ChiShim, ProjectEnv) where another surface says the same.
+  class HomeDoctor
+    # +status+ :ok, :warn (works, not as intended) or :fail (a launch can't
+    # boot what it should).
+    Row = Data.define(:status, :text) do
+      def to_s = "#{status.to_s.ljust(5)} #{text}"
+    end
+
+    # What a Gemfile.lock that bundles chi has (a GEM or PATH spec line).
+    LOCKED_CHI = /^ {4}samagotchi \(/
+
+    # @param home [ChiHome::Record, nil] home.json's record
+    # @param helper [Desktop::MacOS, nil] the desktop helper (nil off macOS)
+    # @param sessions [#call] () → [Session] this machine's sessions
+    def initialize(home:, env: ENV, cwd: Dir.pwd, gem_spec: InstalledGem.spec, helper: nil,
+                   sessions: -> { Session.list(state_dir: Session.default_state_dir(env: env)) },
+                   shim_dir: ChiShim.dir(env: env), log_path: LogPath.resolve(env: env),
+                   ruby: RbConfig.ruby, gem_dir: Gem.dir)
+      @home = home
+      @env = env
+      @cwd = cwd
+      @gem_spec = gem_spec
+      @helper = helper
+      @sessions = sessions
+      @shim_dir = shim_dir
+      @log_path = log_path
+      @ruby = ruby
+      @gem_dir = gem_dir
+    end
+
+    # @return [Array<Row>]
+    def rows
+      list = [home_row]
+      if @home && !ChiHome.problem(@home)
+        list.concat([running_row, helper_row, sessions_row, shim_row].compact)
+      end
+      list.concat([gemfile_row, mise_row, project_env_row].compact)
+    end
+
+    # The desktop helper chi home doctor checks: this machine's, when it
+    # is installed.
+    def self.default_helper(env: ENV)
+      return nil unless Desktop.supported?
+
+      helper = Desktop::MacOS.new(env: env, register: false)
+      File.file?(helper.launch_path) ? helper : nil
+    end
+
+    private
+
+    def ok_row(text) = Row.new(status: :ok, text: text)
+    def warn_row(text) = Row.new(status: :warn, text: text)
+    def fail_row(text) = Row.new(status: :fail, text: text)
+
+    def home_row
+      return ok_row("no chi home: each launch uses the Ruby that starts it (chi home set to record one)") unless @home
+
+      if (problem = ChiHome.problem(@home))
+        return fail_row("#{problem}: after a Ruby upgrade, gem install samagotchi with the new Ruby, then " \
+                    "chi home set from it (chi home set --ruby PATH); until then launches use the Ruby that starts them")
+      end
+
+      ok_row("chi home #{@home.ruby} runs chi #{@home.newest_version}")
+    end
+
+    def running_row
+      return ok_row("this chi runs from a source checkout: it starts its own code, not the home") unless @gem_spec
+
+      text = HomeNotice.mismatch(@home, ruby: @ruby, gem_dir: @gem_dir)
+      text && warn_row("#{text}: launches boot the home; chi home set makes this chi the home")
+    end
+
+    def helper_row
+      return nil unless @helper
+
+      if (problem = @helper.launch_problem)
+        fail_row(problem)
+      elsif (problem = @helper.home_problem(@home))
+        warn_row(problem)
+      end
+    end
+
+    # Sessions last saved by a newer chi than the home's: their workers
+    # (the home's chi) run them without what that chi added.
+    def sessions_row
+      newest = @home.newest_version
+      newer = @sessions.call.filter_map do |session|
+        version = session.written_by
+        Gem::Version.new(version) if version.is_a?(String) && Gem::Version.correct?(version)
+      end.select { |version| version > newest }
+      return nil if newer.empty?
+
+      count = newer.size == 1 ? "1 session was" : "#{newer.size} sessions were"
+      warn_row("#{count} last saved by a newer chi (#{newer.max}) than the home's #{newest}: " \
+           "their workers run without what it added; chi update brings the home up to date")
+    end
+
+    def shim_row
+      problem = ChiShim.problem(@home, dir: @shim_dir)
+      problem && warn_row(problem)
+    end
+
+    # The cwd's project bundling chi (a Gemfile.lock with samagotchi):
+    # `bundle exec chi` there runs the bundle's chi, off the home.
+    def gemfile_row
+      lock = project_lockfile
+      return nil unless lock && File.read(lock).match?(LOCKED_CHI)
+
+      warn_row("#{Paths.tilde(lock)} bundles samagotchi: chi under the project's bundle (bundle exec chi) isn't " \
+           "supported; run chi itself, and bundle remove samagotchi there")
+    rescue SystemCallError
+      nil
+    end
+
+    # The nearest Gemfile.lock from the cwd up to its git root; nil for
+    # chi's own source tree (its gemspec is next to it).
+    def project_lockfile
+      dir = project_dirs.find { |candidate| File.file?(File.join(candidate, "Gemfile.lock")) }
+      return nil if dir.nil? || File.file?(File.join(dir, "samagotchi.gemspec"))
+
+      File.join(dir, "Gemfile.lock")
+    end
+
+    # The cwd and the folders above it up to its git root (the cwd alone
+    # outside git).
+    def project_dirs
+      @project_dirs ||= begin
+        dirs = []
+        dir = File.expand_path(@cwd)
+        loop do
+          dirs << dir
+          break if File.exist?(File.join(dir, ".git"))
+
+          parent = File.dirname(dir)
+          break dirs = [dirs.first] if parent == dir
+
+          dir = parent
+        end
+        dirs
+      end
+    end
+
+    def mise_row
+      mode, origin = Config.get_with_origin("session.project_env")
+      return ok_row("project env off (session.project_env: off): tools keep the env of whoever starts the worker") if mode.to_s == "off"
+
+      mise = ProjectEnv.find_mise(env: @env)
+      return ok_row("project env: mise (#{mise})") if mise
+
+      origin == :default ? ok_row(ProjectEnv::NO_MISE) : warn_row(ProjectEnv::NO_MISE)
+    end
+
+    def project_env_row
+      warning = ProjectEnv.last_warning(project_dirs, log_path: @log_path)
+      warning && warn_row(warning.message)
+    end
+  end
+end

data/lib/samagotchi/home_notice.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+require_relative "chi_home"
+require_relative "installed_gem"
+require_relative "paths"
+require_relative "version"
+
+module Samagotchi
+  # One dim stderr line, at most once a day, when a person runs an installed
+  # chi at a terminal from a Ruby that isn't the chi home's: "chi 0.131.0 on
+  # /x/ruby; the chi home is /y/ruby (chi 0.132.0) (chi home doctor)". The
+  # sessions it starts boot the home anyway; the line says which chi answered.
+  # Never inside a worker's tools (SAMAGOTCHI_PROJECT_ENV), never for a
+  # script (no TTY, --json, --non-interactive), never from a checkout.
+  # The day is stamped in $XDG_STATE_HOME/samagotchi/home_noticed.
+  module HomeNotice
+    STAMP_FILE = "home_noticed"
+    # Runs whose output a program reads, or that say this themselves.
+    QUIET_COMMANDS = %w[home update self].freeze
+    QUIET_FLAGS = %w[--json --non-interactive --version -h --help].freeze
+    # Set in a worker's tools (ProjectEnv::MARKER_ENV) and in specs' test runs.
+    QUIET_ENV = %w[SAMAGOTCHI_PROJECT_ENV SAMAGOTCHI_ENV RACK_ENV CI].freeze
+
+    module_function
+
+    # Prints the line when it is due. Cheap when it isn't: the TTY, argv
+    # and env checks come first, then the stamp, then home.json.
+    # @return [String, nil] the line printed
+    def show(argv: ARGV, env: ENV, tty: $stdin.tty? && $stderr.tty?, io: $stderr,
+             gem_spec: nil, today: Time.now.strftime("%Y-%m-%d"))
+      return nil unless tty && !quiet_argv?(argv) && QUIET_ENV.none? { |key| env.key?(key) }
+
+      stamp = File.join(Paths.state_dir(env: env), STAMP_FILE)
+      return nil if stamped?(stamp, today)
+
+      gem_spec ||= InstalledGem.spec
+      text = gem_spec && mismatch(ChiHome.current(path: ChiHome.path(env: env), gem_spec: gem_spec))
+      return nil unless text
+
+      line = "#{text} (chi home doctor)"
+      io.puts("\e[2m#{line}\e[0m")
+      FileUtils.mkdir_p(File.dirname(stamp))
+      File.write(stamp, "#{today}\n")
+      line
+    rescue StandardError
+      nil
+    end
+
+    # This chi isn't the home's: the text, also chi home doctor's row; nil
+    # when this process runs on +home+ (or there is none).
+    # @return [String, nil]
+    def mismatch(home, ruby: RbConfig.ruby, gem_dir: Gem.dir, version: VERSION)
+      return nil if home.nil? || (home.running_here?(ruby: ruby, gem_dir: gem_dir) && home.newest_version.to_s == version)
+
+      where = ruby
+      # The same Ruby on other gems (a chruby GEM_HOME): name them both.
+      if ChiHome.real(ruby) == ChiHome.real(home.ruby) && ChiHome.real(gem_dir) != ChiHome.real(home.gem_home)
+        where = "#{ruby} (gems #{gem_dir})"
+        home_where = "#{home.ruby} (gems #{home.gem_home})"
+      end
+      "chi #{version} on #{where}; the chi home is #{home_where || home.ruby} (chi #{home.newest_version})"
+    end
+
+    def quiet_argv?(argv)
+      return true if QUIET_COMMANDS.include?(argv.first)
+
+      argv.each_with_index.any? do |arg, i|
+        QUIET_FLAGS.include?(arg) || arg == "--format=json" || (arg == "--format" && argv[i + 1] == "json")
+      end
+    end
+
+    def stamped?(stamp, today)
+      File.read(stamp, 32).to_s.strip == today
+    rescue SystemCallError
+      false
+    end
+  end
+end

data/lib/samagotchi/installed_versions.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "chi_home"
 require_relative "installed_gem"
 require_relative "version"
 require_relative "redacted_inspect"
@@ -8,8 +9,9 @@ module Samagotchi
   # The newest chi on this machine, which a long-lived process (chi web, an
   # attaching TUI) compares with its own VERSION to say "chi X is installed;
   # restart". Run from an installed gem: the highest samagotchi-<v>.gemspec
-  # in RubyGems' specification dirs, matching the `>= 0.a` a new worker
-  # activates (prereleases count). Run from a source checkout: the VERSION
+  # in RubyGems' specification dirs (the chi home's when there is one,
+  # ChiHome), matching the `>= 0.a` a new worker activates (prereleases
+  # count). Run from a source checkout: the VERSION
   # in lib/samagotchi/version.rb on disk now (a `git pull` moves it).
   #
   # Cheap enough to poll: each dir is listed again only when its mtime
@@ -30,7 +32,7 @@ module Samagotchi
     #   runs from (nil: a source checkout)
     # @param dirs [#call] → the specification dirs to list
     # @param version_file [String] a checkout's version.rb
-    def initialize(env: ENV, gem_spec: InstalledGem.spec, dirs: -> { Gem::Specification.dirs },
+    def initialize(env: ENV, gem_spec: InstalledGem.spec, dirs: -> { ChiHome.spec_dirs(gem_spec: gem_spec) },
                    version_file: File.join(InstalledGem::ROOT, "lib", "samagotchi", "version.rb"))
       @env = env
       @gem_spec = gem_spec

data/lib/samagotchi/llm_context_command.rb

@@ -4,6 +4,7 @@ require_relative "llm_context_override"
 require_relative "llm_context_strategy"
 require_relative "llm_context_edit"
 require_relative "llm_context_stale"
+require_relative "cache_confirm"
 
 module Samagotchi
   # /llm-context, the session's own LLM context values
@@ -18,7 +19,9 @@ module Samagotchi
   # system prompt (a full cache break); stale turned on stages the reads
   # already superseded as one batch under the apply rule; a layer turned
   # off sends its stubs whole again (the originals stay in the session, so
-  # turning it back on brings them back).
+  # turning it back on brings them back). The two that restart the prompt
+  # cache (forget on or off, stubs sent whole again) ask first
+  # (CacheConfirm, #cache_cost); --yes (or -y) applies them.
   class LLMContextCommand
     NAME = LLMContextOverride::COMMAND
     USAGE = "usage: #{NAME} [strategy <none|stale,forget|default>] [apply <payoff|next_request|turn_end|default>] " \
@@ -33,20 +36,49 @@ module Samagotchi
       @save = save
     end
 
-    # @param args [String] what follows /llm-context
-    # @return [Array(String, Boolean)] the reply and whether the values changed
+    # @param args [String] what follows /llm-context (--yes anywhere)
+    # @param confirm [Boolean] ask before a change that restarts the prompt
+    #   cache (CacheConfirm, #cache_cost); false applies it at once (chi
+    #   send, a delegate, a start flag)
+    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
+    #   whether the values changed, and the confirm it asks for (nothing
+    #   changed then)
     # @raise [ArgumentError] a line that isn't one (its message and USAGE)
-    def run(args)
-      args = args.to_s.strip
-      return [listing(@engine.llm_context_explained), false] if args.empty?
+    def run(args, confirm: true)
+      # Before #words: it refuses --yes, and "reset --yes" isn't RESET.
+      args, yes = CacheConfirm.split(args, downcase: false)
+      return [listing(@engine.llm_context_explained), false, nil] if args.empty?
 
       session = @engine.session or raise ArgumentError, "no session yet"
       before = @engine.llm_context_explained
       updated = args.casecmp?(RESET) ? LLMContextOverride.new : LLMContextOverride.update(@engine.llm_context_override, words(args))
+      ask = confirm && !yes ? ask(session, before, updated, args) : nil
+      return ask if ask
+
       @engine.llm_context_override = updated
       @save.call(session)
       after = @engine.llm_context_explained
-      [[listing(after), *notes(session, before&.resolved, after&.resolved)].join("\n"), true]
+      [[listing(after), *notes(session, before&.resolved, after&.resolved)].join("\n"), true, nil]
+    end
+
+    # What a change from +before+ to +after+ (Resolved) costs the prompt
+    # cache, nil for nothing worth asking about: forget on or off changes
+    # the tool list and the system prompt (:full); a layer turned off while
+    # it has applied stubs sends them whole again (:history). Stale turned
+    # on only stages a batch under the apply rule (its break comes later,
+    # as designed), and the apply rule and budget only decide when a break
+    # comes: a switch to next_request with staged edits pending applies
+    # them at the next request, a break the old rule makes by the end of
+    # the next turn anyway.
+    # @return [Symbol, nil]
+    def cache_cost(session, before, after)
+      return nil unless before && after
+
+      was = before.active_layers
+      now = after.active_layers
+      return :full if was.include?(:forget) != now.include?(:forget)
+
+      :history if (was - now).any? { |layer| applied_count(session.messages, layer).positive? }
     end
 
     # The values, where each came from, and what the session sets itself.
@@ -66,6 +98,20 @@ module Samagotchi
 
     private
 
+    # The reply that asks before a costly change (CacheConfirm), nil when
+    # it needn't.
+    def ask(session, before, updated, args)
+      would = @engine.llm_context_explained(own: updated)
+      was = before&.resolved
+      now = would&.resolved
+      cost = cache_cost(session, was, now)
+      step = CacheConfirm.ask(line: "#{NAME} #{args}", cost: cost, changed: !cost.nil?, engine: @engine)
+      return nil unless step
+
+      costs = notes(session, was, now).drop(1).reject { |note| note.start_with?("stale:") }
+      [[listing(before), "This change restarts the prompt cache:", *costs, step.text].join("\n"), false, step]
+    end
+
     # "strategy stale stale forget apply turn_end budget 64k" as fields
     # and their words; a strategy takes the words up to the next field.
     def words(args)

data/lib/samagotchi/llm_context_override.rb

@@ -55,7 +55,8 @@ module Samagotchi
     COMMAND_WORDS = { strategy: "strategy", apply: "apply", budget_tokens: "budget" }.freeze
 
     # The /llm-context line that sets +words+ (field => value as typed,
-    # checked by .update first): what a flag on an existing session runs.
+    # checked by .update first): what a flag on an existing session runs,
+    # with --yes (typing the flag is the choice: no confirm step).
     # @return [String]
     def self.command_line(words)
       parts = words.map do |field, word|
@@ -63,7 +64,7 @@ module Samagotchi
         word = parse_strategy(word).then { |layers| layers.empty? ? "none" : layers.join(",") } if field == :strategy && !word.casecmp?(DEFAULT_WORD)
         "#{COMMAND_WORDS.fetch(field)} #{word}"
       end
-      [COMMAND, *parts].join(" ")
+      [COMMAND, *parts, "--yes"].join(" ")
     end
 
     # A session file's "llm_context" (or an override already): nil when

data/lib/samagotchi/plugin/api.rb

@@ -7,6 +7,7 @@ require_relative "../commands/registry"
 require_relative "service"
 require_relative "tool_result"
 require_relative "tool_spec"
+require_relative "prompt_sections"
 
 module Samagotchi
   module Plugin
@@ -45,7 +46,9 @@ module Samagotchi
         "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0",
         "ctx.usage" => "0.100.0", "ctx.sessions.stop" => "0.34.0", "ctx.turn_author" => "0.106.0",
         "ctx.sessions.review" => "0.107.0", "ctx.sessions.send(delivery:)" => "0.64.0",
-        "chi.toolkit(prompt:)" => "0.72.0", "ctx.ask_model(model:)" => "0.80.0", "chi.toolkit(groups:)" => "0.121.0"
+        "chi.toolkit(prompt:)" => "0.72.0", "ctx.ask_model(model:)" => "0.80.0", "chi.toolkit(groups:)" => "0.121.0",
+        "chi.prompt_section" => "0.132.0", "chi.prompt_changed" => "0.132.0", "ctx.cache_confirm" => "0.132.0",
+        "ctx.model_names" => "0.132.0"
       }.freeze
 
       # @param bundle [String]
@@ -65,6 +68,7 @@ module Samagotchi
         @services = []
         @inits = []
         @toolkits = []
+        @prompt_sections = []
         @peer_sources = []
         @tool_source = nil
         @committed = false
@@ -279,6 +283,42 @@ module Samagotchi
         nil
       end
 
+      # Text this session's system prompt carries (docs/plugins.md, Prompt
+      # sections): the block gets the Context and returns a String (at most
+      # PromptSections::MAX characters) or nil for none. It runs when the
+      # prompt is built (a session's first turn, after /model or a
+      # #prompt_changed!), never per request, on whatever thread builds:
+      # keep it quick (no I/O beyond reading a small file) and give the same
+      # text for the same inputs. A raise, a non-String or text over the
+      # limit keeps the section's last good text (one warn).
+      # @param name [String] a-z, 0-9, _ and -; unique in the bundle
+      def prompt_section(name, &block)
+        raise ArgumentError, "prompt_section #{name.inspect} needs a block" unless block
+
+        name = name.to_s
+        unless name.match?(PromptSections::NAME)
+          raise ArgumentError, "prompt section name #{name.inspect} must be a-z, 0-9, _ and - (at most 32)"
+        end
+        raise ArgumentError, "this chi has no prompt sections (plugins: false)" unless @registries.prompt_sections
+        if @prompt_sections.any? { |item| item[:name] == name } || @registries.prompt_sections.registered?(@bundle, name)
+          raise ArgumentError, "prompt section #{name} is registered twice"
+        end
+
+        @prompt_sections << { name: name, block: block }
+        nil
+      end
+
+      # Say this session's prompt sections would now give other text (a
+      # setting the plugin keeps changed): the system prompt is built again
+      # at its next build (the next turn's start; a running turn keeps the
+      # prompt it started with). That restarts the model server's prompt
+      # cache, so a command that changes a section asks first
+      # (Context#cache_confirm) and calls this only once it applies.
+      def prompt_changed!
+        @registries.prompt_changed&.call
+        nil
+      end
+
       # Publish tools into the session's tool index instead of declaring
       # them one by one (docs/plugins.md, "Publishing tools to the index"):
       # the model searches them with find_tools and calls one with
@@ -393,6 +433,9 @@ module Samagotchi
           end
         end
         @registries.toolkits&.concat(@toolkits)
+        @prompt_sections.each do |item|
+          @registries.prompt_sections.add(bundle: @bundle, name: item[:name], context: context, &item[:block])
+        end
         @registries.tool_index.add(@tool_source) if @tool_source
         @peer_sources.each { |item| @registries.peer_sources.declare(item[:name], label: item[:label], bundle: @bundle) }
         @committed = true
@@ -401,6 +444,7 @@ module Samagotchi
       # @return [Hash] how many of each it registered (for the log)
       def counts = { commands: @commands.size, annotations: @annotations.size, tools: @tools.size, hooks: @hooks.size,
                      services: @services.size, inits: @inits.size, toolkits: @toolkits.size,
+                     prompt_sections: @prompt_sections.size,
                      tool_sources: @tool_source ? 1 : 0, peer_sources: @peer_sources.size }
 
       # Each annotation's command is one #command staged.