samagotchi 0.131.0 → 0.133.0

data/lib/samagotchi/session_commands.rb

@@ -5,6 +5,7 @@ require_relative "model_profile"
 require_relative "served_model"
 require_relative "prompt_note"
 require_relative "turn_flow"
+require_relative "cache_confirm"
 require_relative "tools/execute"
 require_relative "tools/builtins"
 require_relative "tools/context_read"
@@ -61,7 +62,7 @@ module Samagotchi
 
     # Commands that may ask before a change that restarts the prompt cache
     # (CacheConfirm): #run passes them its confirm flag.
-    CONFIRMING = %i[thinking reasoning_history toolkit].freeze
+    CONFIRMING = %i[model llm_context thinking reasoning_history toolkit].freeze
 
     # @!attribute status [Symbol] :ok, or :error when the line was refused
     # @!attribute output [String, nil] what to tell the user
@@ -302,7 +303,7 @@ module Samagotchi
       text = line.to_s.strip
       entry = @registry.lookup(text)
       return nil unless entry&.handler
-      return run_bundle_command(entry, text) unless entry.source == "core"
+      return run_bundle_command(entry, text, confirm: confirm) unless entry.source == "core"
 
       # Only commands that may ask take the flag.
       return send(entry.id, text, confirm: confirm) if CONFIRMING.include?(entry.id)
@@ -355,16 +356,32 @@ module Samagotchi
     # The resolved ref (what the session stores and --alias/--default write).
     def model_name = @engine.effective_model_ref
 
-    # A bundle plugin's command: its handler gets the text after the name;
-    # what it returns is the output (nil: nothing to show), and a raise is
-    # an error result.
-    def run_bundle_command(entry, text)
-      output = entry.handler.call(text.delete_prefix(entry.name).strip)
-      reply(output.nil? ? nil : output.to_s)
+    # A bundle plugin's command: its handler gets the text after the name
+    # (--yes kept); what it returns is the output (nil: nothing to show),
+    # or [output, CacheConfirm::Confirm or nil] for a change that asks
+    # first (ctx.cache_confirm), and a raise is an error result. The
+    # sender's +confirm+ (false once the line has --yes) reaches
+    # ctx.cache_confirm through the thread (CacheConfirm.asking).
+    def run_bundle_command(entry, text, confirm: false)
+      args = text.delete_prefix(entry.name).strip
+      _, yes = CacheConfirm.split(args)
+      output, ask = bundle_reply(CacheConfirm.asking(confirm && !yes) { entry.handler.call(args) })
+      reply(output, confirm: ask)
     rescue StandardError => e
       reply("#{entry.name}: #{e.class}: #{e.message}", status: :error)
     end
 
+    # A plugin command's return value as [output, confirm]: a String (or
+    # anything, shown as text) or nil, or [text, Confirm/nil].
+    def bundle_reply(value)
+      if value.is_a?(Array) && value.size == 2 && (value[1].nil? || value[1].is_a?(CacheConfirm::Confirm))
+        text, ask = value
+        return [text.nil? ? nil : text.to_s, ask]
+      end
+
+      [value.nil? ? nil : value.to_s, nil]
+    end
+
     def help_group(entry)
       return 2 if entry.local
 
@@ -393,14 +410,16 @@ module Samagotchi
     # here (as in the REPL, the next turn saves it). No parent-session
     # marker: the user runs this, not the model. A worker's `chi --model X`
     # default is unset, though: it was that run's, not the default of a chi
-    # run here (Tools::Builtins.cli_model_unset).
+    # run here (Tools::Builtins.cli_model_unset). It runs in the session's
+    # project env (ProjectEnv), as the model's execute does.
     def shell(text)
       command = text.delete_prefix(SHELL_BANG_PREFIX).strip
       return reply("!: please provide a shell command after '!'", status: :error) if command.empty?
 
       # Killed at the limit, never handed over: the output goes in a user
       # message, which no one reads a task id from (created_ids_in).
-      output = Samagotchi::Tools::Execute.call(command, env: Samagotchi::Tools::Builtins.cli_model_unset, on_timeout: :kill)
+      env = Samagotchi::ProjectEnv.tools_env.merge(Samagotchi::Tools::Builtins.cli_model_unset)
+      output = Samagotchi::Tools::Execute.call(command, env: env, on_timeout: :kill)
       @engine.append_messages([{ role: "user", content: "!(#{command})\n#{output}" }])
       # Rolling back past this would silently drop the command output.
       @turn_flow.note_conversation_changed
@@ -583,13 +602,13 @@ module Samagotchi
 
     # /llm-context (LLMContextCommand); :llm_context in changed when it set
     # the session's values.
-    def llm_context(text)
-      output, changed = LLMContextCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
-                                         .run(text.delete_prefix(LLM_CONTEXT_COMMAND))
+    def llm_context(text, confirm: true)
+      output, changed, ask = LLMContextCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
+                                              .run(text.delete_prefix(LLM_CONTEXT_COMMAND), confirm: confirm)
       # What the model has of each item is the next turn's strategy's: the
       # working set goes out again (sent only when it differs).
       @engine.announce_working_set if changed
-      reply(output, changed: changed ? [:llm_context] : [])
+      reply(output, changed: changed ? [:llm_context] : [], confirm: ask)
     rescue ArgumentError => e
       reply(e.message, status: :error)
     end
@@ -672,16 +691,23 @@ module Samagotchi
       @save.call(session)
     end
 
-    def model(text)
-      output, switched = model_command(text)
-      reply(output, changed: switched ? [:model] : [])
+    # /model; a switch to another model asks first (CacheConfirm, cost
+    # :full: the new model has no cache of the conversation), --yes applies.
+    def model(text, confirm: true)
+      suffix, yes = CacheConfirm.split(text.delete_prefix(MODEL_COMMAND), downcase: false)
+      output, switched, ask = model_command("#{MODEL_COMMAND} #{suffix}", confirm: confirm && !yes)
+      reply(output, changed: switched ? [:model] : [], confirm: ask)
     rescue ModelProfile::MissingModel => e
       # A model qualified with an unknown host: nothing switched.
       reply(e.message, status: :error)
     end
 
-    # @return [Array(String, Boolean)] the message, and whether the model changed
-    def model_command(input)
+    # @param input [String] the /model line, --yes taken out
+    # @param confirm [Boolean] a switch to another model asks first
+    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the message,
+    #   whether the model changed, and the confirm it asks for (nothing
+    #   changed then)
+    def model_command(input, confirm: false)
       suffix = input.delete_prefix(MODEL_COMMAND).strip
       if suffix.empty?
         return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}#{steer_cut_after_note}#{thinking_note}#{reasoning_history_note}#{notes_note}", false] if @default_model.nil? || model_name == @engine.model_ref_for(@default_model)
@@ -735,6 +761,9 @@ module Samagotchi
         invalid = ConfigFile.model_alias_error(alias_name, arg)
         return ["invalid alias: #{invalid}", false] if invalid
 
+        ask = confirm && model_ask(arg, input)
+        return ask if ask
+
         switch_model(arg, persist_default: persist_default)
 
         begin
@@ -756,10 +785,16 @@ module Samagotchi
           return ["--default cannot be combined with clear/default/none/off", false] if persist_default
           raise ModelProfile::MissingModel, "no default model is configured (set default.model in config.yml, or /model <name> --default)" if @default_model.nil?
 
+          ask = confirm && model_ask(@default_model, input)
+          return ask if ask
+
           switch_model(@default_model)
           return ["runtime model reset to #{model_name}#{model_note}#{thinking_note}#{reasoning_history_note}#{notes_note}", true]
         end
 
+        ask = confirm && model_ask(arg, input)
+        return ask if ask
+
         switch_model(arg, persist_default: persist_default)
         if persist_default
           ["runtime model set to #{model_name}#{model_note} and default updated#{thinking_note}#{reasoning_history_note}#{notes_note}", true]
@@ -769,6 +804,20 @@ module Samagotchi
       end
     end
 
+    # The reply that asks before switching to +name+ (CacheConfirm), nil
+    # when it needn't: the name is checked first (a typo errors at once,
+    # MissingModel), and its resolved ref against the current one (the same
+    # model costs nothing; any other restarts the whole cache).
+    # @param line [String] the /model line as typed (its flags too), --yes taken out
+    def model_ask(name, line)
+      ref = @engine.model_switch_ref(name)
+      step = CacheConfirm.ask(line: line, cost: :full, changed: ref != model_name, engine: @engine)
+      return nil unless step
+
+      ["runtime model: #{model_name}\nSwitching to #{ref} restarts the prompt cache: the new model has no cache of " \
+       "this conversation.\n#{step.text}", false, step]
+    end
+
     # Engine owns the switch (alias resolution, profile, kernel, client and
     # the optional default persist); the session keeps the new model.
     def switch_model(name, persist_default: false)

data/lib/samagotchi/session_manager.rb

@@ -5,6 +5,7 @@ require "json"
 require "time"
 require "securerandom"
 require "rbconfig"
+require_relative "chi_home"
 require_relative "child_env"
 require_relative "client_id"
 require_relative "analytics_file"
@@ -33,6 +34,7 @@ require_relative "chi_invocation"
 require_relative "log"
 require_relative "log_path"
 require_relative "paths"
+require_relative "project_env"
 require_relative "model_profile"
 require_relative "installed_gem"
 require_relative "installed_versions"
@@ -256,6 +258,8 @@ module Samagotchi
       else
         Log.warn(:worker, "cwd_gone", sid: session.id, dir: dir, cwd: Dir.pwd)
       end
+      # (A chi a session's tool runs took that session's project env out at
+      # its start: bin/chi, ProjectEnv.take_orig!.)
       child_env = {}
       # A worker gets no CLI args: --model, --thinking, --log-level and the
       # other flags this chi was started with.
@@ -1127,6 +1131,9 @@ module Samagotchi
       fallback = ENV.delete(BOOT_FALLBACK_ENV)
       Log.info(:worker, "start", cwd: Dir.pwd, version: VERSION)
       Log.warn(:worker, "boot_fallback", version: VERSION, error: fallback) if fallback
+      # Tools follow the project (its `mise env`, computed once per worker;
+      # this process's ENV is left as it is); never in a loop run in-process.
+      apply_project_env(session_id, state_dir: sd) if spawned
       # A spawned worker stops its turn on TERM/HUP/INT and saves it; a
       # loop run in-process (specs) traps nothing.
       signals = spawned ? WorkerSignals.new.install! : WorkerSignals::NONE
@@ -1215,6 +1222,18 @@ module Samagotchi
       Log.info(:worker, "kept_session", sid: session_id, error: e.class.name, msg: e.message)
     end
 
+    # The tools' ProjectEnv for the session's folder (its working_directory;
+    # spawn_options chdirs there unless it is gone), installed for this
+    # process's tool spawns. Never fatal: a worker without it still runs.
+    private_class_method def self.apply_project_env(session_id, state_dir:)
+      session = Session.summary_from_file(Session.session_file(session_id, state_dir: state_dir))
+      dir = session&.working_directory.to_s
+      overlay = ProjectEnv.install!(ProjectEnv.compute(dir))
+      Log.info(:worker, "project_env_applied", dir: dir, ruby: overlay.ruby) if overlay.applied
+    rescue StandardError => e
+      Log.warn(:worker, "project_env", reason: "error", error: e.class.name, msg: e.message)
+    end
+
     def self.config_idle_exit_minutes
       Samagotchi::Config.get("session.idle_exit_minutes")
     rescue StandardError
@@ -1252,16 +1271,50 @@ module Samagotchi
     # as it is read, so an rspec run by the worker's execute never forks.
     WORKER_DETACH_ENV = "SAMAGOTCHI_WORKER_DETACH"
 
-    def self.worker_command(session_id, state_dir:, gem_spec: InstalledGem.spec)
+    # The boot string's rescue under a chi home: one line in the spawner's
+    # log file (SAMAGOTCHI_LOG_FILE, set by spawn_options), LogLine's shape,
+    # then exit. Single-quoted: the #{} run in the worker. SID is replaced.
+    # rubocop:disable-next Lint/InterpolationCheck -- the worker interpolates these, not this process
+    HOME_BOOT_FAILED = 'rescue ScriptError, StandardError => e; f = ENV["SAMAGOTCHI_LOG_FILE"].to_s; begin; ' \
+                       'File.open(f, "a") { |io| io.puts(Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ") + ' \
+                       '" ERROR worker pid=#{Process.pid} sid=SID boot_failed ruby=#{RbConfig.ruby.inspect} error=" + ' \
+                       "e.message.lines.first.to_s.strip.inspect) } unless f.empty?; rescue SystemCallError; end; exit 1"
+
+    def self.worker_command(session_id, state_dir:, gem_spec: InstalledGem.spec,
+                            home: ChiHome.current(gem_spec: gem_spec))
       boot = "require 'samagotchi/session_manager'; " \
              "Samagotchi::SessionManager.run_session_loop('#{session_id}', state_dir: #{state_dir.inspect})"
       return [RbConfig.ruby, "-I", File.expand_path("..", __dir__), "-e", boot] unless gem_spec
+      return home_worker_command(session_id, state_dir: state_dir, gem_spec: gem_spec, home: home) if home
 
       activate = "begin; gem 'samagotchi', '>= 0.a'; rescue LoadError => e; " \
                  "ENV['#{BOOT_FALLBACK_ENV}'] = e.message; gem 'samagotchi', '= #{gem_spec.version}'; end"
       [RbConfig.ruby, "-e", "#{activate}; #{boot}"]
     end
 
+    # With a chi home (ChiHome.current, docs/architecture.md "How chi
+    # launches itself"): the home's ruby, `Gem.paths` set to its gems in the
+    # boot string (no GEM_* in the worker's env), the newest chi there, else
+    # the fallback pin (ChiHome.fallback_version). A home that still can't
+    # load chi (a broken install) logs HOME_BOOT_FAILED and exits: never a
+    # silent spawn timeout.
+    private_class_method def self.home_worker_command(session_id, state_dir:, gem_spec:, home:)
+      newest = home.newest_version
+      if newest && newest < Gem::Version.new(gem_spec.version.to_s)
+        ChiHome.warn_once(:older_than_spawner, home: newest.to_s, spawner: gem_spec.version.to_s)
+      end
+      fallback = ChiHome.fallback_version(home, gem_spec)
+      activate = if fallback
+                   "begin; gem 'samagotchi', '>= 0.a'; rescue LoadError => e; " \
+                     "ENV['#{BOOT_FALLBACK_ENV}'] = e.message; gem 'samagotchi', '= #{fallback}'; end"
+                 else
+                   "gem 'samagotchi', '>= 0.a'"
+                 end
+      home.boot_argv(run: "begin; #{activate}; require 'samagotchi/session_manager'; " \
+                           "#{HOME_BOOT_FAILED.sub("SID", session_id)}; end; " \
+                           "Samagotchi::SessionManager.run_session_loop('#{session_id}', state_dir: #{state_dir.inspect})")
+    end
+
     private_class_method def self.spawn_worker_for_session(session, state_dir:)
       session_dir = Session.session_dir(session.id, state_dir: state_dir)
       FileUtils.mkdir_p(session_dir)

data/lib/samagotchi/session_model_settings.rb

@@ -61,9 +61,12 @@ module Samagotchi
 
     # #turn_llm_context with where each value came from
     # (LLMContextStrategy.explain), nil when it can't be resolved.
+    # @param own [LLMContextOverride, nil] the session's own values to
+    #   resolve with (the ones a change would set: /llm-context's confirm)
     # @return [LLMContextStrategy::Explained, nil]
-    def llm_context_explained
-      model_setting(nil) { |model| model.llm_context_explained(llm_context_session_args) }
+    def llm_context_explained(own: :session)
+      args = own == :session ? llm_context_session_args : own&.resolve_args || {}
+      model_setting(nil) { |model| model.llm_context_explained(args) }
     end
 
     # #llm_context_explained's summary (Explained#summary), nil when it

data/lib/samagotchi/system_prompt.rb

@@ -14,6 +14,7 @@ require_relative "memory_bundle/index_size"
 require_relative "thinking"
 require_relative "prompt_files"
 require_relative "participant_mode"
+require_relative "plugin/prompt_sections"
 
 module Samagotchi
   # The system prompt an Engine gives its model: the base prompt (tool
@@ -57,9 +58,12 @@ module Samagotchi
     # @param participants [#call] → ParticipantMode::PAIR / REVIEW while the
     #   session has participants (SessionParticipants#prompt_mode; true reads
     #   as review), nil or false with none (the #participants_section line)
+    # @param sections [#call] → Array<Plugin::PromptSections::Built>, the
+    #   plugins' prompt sections (chi.prompt_section) run for this build
     def initialize(profile:, tools:, session:, thinking:, model: -> {}, model_notes: -> { [] }, memories: [],
-                   muted_memory_names: [], appended_files: [], participants: -> { false })
+                   muted_memory_names: [], appended_files: [], participants: -> { false }, sections: -> { [] })
       @profile_lookup = profile
+      @sections_lookup = sections
       @participants_lookup = participants
       @model_lookup = model
       @model_notes_lookup = model_notes
@@ -97,19 +101,23 @@ module Samagotchi
       @index_sizes ||= {}
       @notes_loaded ||= {}
       @files_loaded ||= {}
+      @sections_loaded ||= {}
       unless @built.key?(key)
         @section_notes = nil
         @section_files = []
+        @section_plugins = []
         @built[key] = system_prompt_with_index(
           assist_system_prompt(chat: chat, layers: layers), chat: chat, thinking: thinking, layers: layers
         )
         @index_sizes[key] = @measured_index
         @notes_loaded[key] = @section_notes || []
         @files_loaded[key] = @section_files.freeze
+        @sections_loaded[key] = @section_plugins.freeze
       end
       @memory_index = @index_sizes[key]
       @prompt_notes = @notes_loaded[key]
       @prompt_files = @files_loaded[key]
+      @prompt_sections = @sections_loaded[key]
       @built[key]
     end
 
@@ -135,6 +143,12 @@ module Samagotchi
     # @return [Array<String>]
     def prompt_files = @prompt_files || []
 
+    # The plugins' prompt sections the prompt #build returned last holds
+    # (Plugin::PromptSections::Built, prompt order), [] before a build and
+    # after #reset!.
+    # @return [Array<Plugin::PromptSections::Built>]
+    def prompt_sections = @prompt_sections || []
+
     # Drops the built prompts: the next #build reads the profile, tools,
     # indexes and memories again (a model or profile switch, changed tools).
     def reset!
@@ -144,6 +158,8 @@ module Samagotchi
       @prompt_notes = nil
       @files_loaded = nil
       @prompt_files = nil
+      @sections_loaded = nil
+      @prompt_sections = nil
       @stable_lengths = nil
     end
 
@@ -298,7 +314,8 @@ module Samagotchi
     # prefix): what every session shares first, what changes least before
     # what changes more, and the per-session lines last. The global parts
     # (identity, preloads) come before the project's AGENTS.md, the
-    # toolkit's prompt text after the appended files, the memory indexes (a
+    # toolkit's prompt text after the appended files, then the plugins'
+    # prompt sections, the memory indexes (a
     # memory write changes them) after all of them; the model, the location
     # and the session close the prompt (Gemma's tool declarations still
     # follow them).
@@ -311,7 +328,7 @@ module Samagotchi
         "System memories:\n#{indexes[:system]}"
       ].join("\n\n")
       stable = [thinking_token + base, not_loaded_line(layers), rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
-                project_specific_description, appended_section, kit_prompt_section, memory_sections]
+                project_specific_description, appended_section, kit_prompt_section, plugin_prompt_section, memory_sections]
       stable_text = stable.compact.join("\n")
       volatile = [participants_section, current_model, project_location, current_session].compact
       return with_tail_declarations(stable_text, chat: chat, layers: layers) if volatile.empty?
@@ -362,6 +379,20 @@ module Samagotchi
       registry.respond_to?(:toolkit) ? registry.toolkit&.prompt : nil
     end
 
+    # The plugins' prompt sections (chi.prompt_section), right after the
+    # kit prompt and before the memory indexes: a plugin's text depends on
+    # its settings and the model, not on a memory write. Each is
+    # "From <bundle> (<name>):\n<text>", sorted by (bundle, name)
+    # (Plugin::PromptSections). nil with none: the prompt is what it was
+    # before prompt sections.
+    def plugin_prompt_section
+      built = Array(@sections_lookup.call)
+      @section_plugins = built
+      Plugin::PromptSections.text(built)
+    rescue StandardError
+      nil
+    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

@@ -87,9 +87,10 @@ module Samagotchi
                            toolkit_flags: toolkit_flags, settings: settings, parent_answers: parent_answers)
                  end
         commands = []
-        commands << "/model #{model}" if model && (attach || resume)
+        # --yes on /model and /thinking: typing the flag is the choice (no
+        # confirm step); its applied reply ends the launch's command.
+        commands << "/model #{model} --yes" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
-        # --yes: typing the flag is the choice (no confirm step).
         commands << "#{ThinkingCommand::NAME} #{thinking} --yes" if (attach || resume) && thinking
         first_command = commands.size > 1 ? commands : commands.first
         surface = open_surface

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -728,6 +728,9 @@ module Samagotchi
         # The files whose text is in the prompt (SystemPrompt#prompt_files).
         files = prompt_files_text(snapshot[:prompt_files])
         lines << "prompt files:     #{files}" if files
+        # The plugins' prompt sections it holds (chi.prompt_section): name (bundle).
+        sections = Array(snapshot[:prompt_sections]).map { |item| "#{item[:name]} (#{item[:bundle]})" }
+        lines << "prompt sections:  #{sections.join(", ")}" unless sections.empty?
         # The toolkit's prompt text (Engine#stats_snapshot's kit_prompt).
         if (kit = snapshot[:kit_prompt])
           lines << "kit prompt:       #{kit[:kit]} (~#{kit[:tokens]} tokens)"

data/lib/samagotchi/testing/boundary.rb

@@ -101,7 +101,9 @@ module Samagotchi
           "Samagotchi::ProcessGroup.stop" => "stops a server's process group: needs a ctx process API",
           'require "samagotchi/token_usage"' => "for CHARS_PER_TOKEN",
           "Samagotchi::TokenUsage::CHARS_PER_TOKEN" => "estimates a tool's tokens: could be a stable constant",
-          'require "samagotchi/tool_declarations"' => "loaded for Api.tool_spec's schemas"
+          'require "samagotchi/tool_declarations"' => "loaded for Api.tool_spec's schemas",
+          "Samagotchi::ProjectEnv" => "checks the worker has a project env (an older chi doesn't)",
+          "Samagotchi::ProjectEnv.current" => "starts a server in the session's project env: needs a ctx tools-env API"
         },
         "slow-commands" => {
           'require "samagotchi/guardrails/shell_lex"' => "for ShellLex",

data/lib/samagotchi/testing/bundle.rb

@@ -101,7 +101,7 @@ module Samagotchi
           Plugin::Registries.new(
             commands: SessionCommands.register_builtins(Commands::Registry.new), tools: Tools::Builtins.registry,
             services: Plugin::Services.new, stage_tools: ->(*) {}, toolkits: [], tool_index: Tools::ToolIndex.new,
-            peer_sources: PeerSources.new, **fields
+            peer_sources: PeerSources.new, prompt_sections: Plugin::PromptSections.new, **fields
           )
         end
       end
@@ -138,6 +138,9 @@ module Samagotchi
       attr_reader :errors
       # @return [Integer] how often chi was told the tools changed
       attr_reader :tools_changes
+      # @return [Integer] how often chi was told the prompt sections changed
+      #   (chi.prompt_changed!)
+      attr_reader :prompt_changes
 
       def initialize(dir, settings: {}, host: {}, session_settings: {}, sandbox: nil)
         @dir = File.expand_path(dir)
@@ -163,6 +166,7 @@ module Samagotchi
         @errors = []
         @lenient = false
         @tools_changes = 0
+        @prompt_changes = 0
         @contexts = {}
         @registries = build_registries
       end
@@ -261,12 +265,16 @@ module Samagotchi
       # Run a command line ("/name args") as chi does: the first matching
       # command, given the text after its name. Returns the handler's value
       # (a raise propagates: chi would show it as an error result).
-      def command(line)
+      # @param confirm [Boolean] sent by a person at a web tab or a TUI, who
+      #   can answer ctx.cache_confirm (false: chi send, a delegate); a line
+      #   with --yes never asks, as in chi
+      def command(line, confirm: false)
         entry = commands.lookup(line)
         raise ArgumentError, "no command matches #{line.inspect}" unless entry
         raise ArgumentError, "#{entry.name} is chi's own command, not the bundle's" if entry.source == "core"
 
-        failing { entry.handler.call(line.to_s.strip.delete_prefix(entry.name).strip) }
+        args = line.to_s.strip.delete_prefix(entry.name).strip
+        failing { CacheConfirm.asking(confirm && !CacheConfirm.split(args).last) { entry.handler.call(args) } }
       end
 
       # Call a registered tool as chi's dispatch does: its handler gets the
@@ -324,6 +332,16 @@ module Samagotchi
       # @return [PeerSources]
       def peer_sources = @registries.peer_sources
 
+      # The prompt sections as chi's next prompt build runs them, for the
+      # session now (its id: a failure keeps that session's last good text).
+      # @return [Array<Plugin::PromptSections::Built>]
+      def prompt_sections = @registries.prompt_sections.render(@recorder[:session_id])
+
+      # The text they add to the system prompt, as chi puts it there; nil
+      # with none.
+      # @return [String, nil]
+      def prompt_text = Plugin::PromptSections.text(prompt_sections)
+
       # The bundle's own command entries.
       def bundle_commands = commands.entries.select { |entry| entry.source == @name }
       # The bundle's own tool entries.
@@ -401,6 +419,7 @@ module Samagotchi
                                                    env: ENV, sessions: @sessions, http_transport: @http)
           },
           tools_changed: -> { @tools_changes += 1 },
+          prompt_changed: -> { @prompt_changes += 1 },
           stage_tools: ->(_bundle, specs, context) { @staged_tools << StagedTools.new(specs: specs, context: context) },
           init: lambda { |_bundle, label, plugin_label, provides_tools:, quiet:, timeout:, failed: nil, &block|
             @inits << Init.new(label: label, plugin_label: plugin_label, provides_tools: provides_tools, quiet: quiet,

data/lib/samagotchi/testing/host.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../cancellation_controller"
+require_relative "../cache_confirm"
 require_relative "../plugin/context"
 require_relative "../session_metrics/cost"
 require_relative "../session_metrics/usage"
@@ -12,6 +13,14 @@ module Samagotchi
     # with every member set, its values read from the Recorder at each call
     # and its actions landing in it.
     module Host
+      # What CacheConfirm.ask reads of an Engine, from the Recorder's
+      # history: and context_tokens:.
+      CacheEngine = Struct.new(:history, :tokens) do
+        def history? = history ? true : false
+        def cache_restart_tokens = tokens
+        def cache_restart_anthropic? = false
+      end
+
       module_function
 
       # @param recorder [Recorder]
@@ -37,6 +46,7 @@ module Samagotchi
           },
           model_name: -> { recorder[:model_name] },
           model_key: -> { recorder[:model_key] },
+          model_names: -> { recorder[:model_names] || model_names(recorder[:model_name]) },
           state_dir: -> { recorder[:state_dir] || Session.default_state_dir },
           scratch: -> { recorder[:scratch] },
           setup: -> { recorder[:setup] },
@@ -52,10 +62,21 @@ module Samagotchi
           cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil },
           cost: -> { cost(recorder[:cost]) },
           usage: -> { usage(recorder[:usage]) },
-          turn_author: -> { recorder[:turn_author] }
+          turn_author: -> { recorder[:turn_author] },
+          cache_confirm: lambda { |line, changed|
+            CacheConfirm.ask(line: line, cost: :full, changed: changed,
+                             engine: CacheEngine.new(recorder[:history], recorder[:context_tokens]))
+          }
         )
       end
 
+      # ctx.model_names for a model ref when the test sets none: the ref,
+      # then its id without the host ("test:model" → test:model, model).
+      def model_names(ref)
+        ref = ref.to_s
+        [ref, ref.split(":", 2).last].reject(&:empty?).uniq
+      end
+
       # The parts a test may give bundle.set(cost: {...}).
       COST_PARTS = %i[reported estimated side known].freeze
 

data/lib/samagotchi/testing/recorder.rb

@@ -43,7 +43,12 @@ module Samagotchi
         # callable giving one.
         usage: nil,
         # ctx.turn_author and the hooks' author: (a participant's "p:<id>"), nil for the owner.
-        turn_author: nil
+        turn_author: nil,
+        # ctx.cache_confirm: whether the session has a model reply (a cache
+        # to restart), and the context size its confirm names (nil: none).
+        history: false, context_tokens: nil,
+        # ctx.model_names: nil gives model_name and its id without the host.
+        model_names: nil
       }.freeze
 
       attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :tool_loads, :answers,

data/lib/samagotchi/testing/recording_api.rb

@@ -11,7 +11,7 @@ module Samagotchi
     # The real Plugin::Api, also recording each declaration in order
     # (#declarations), for a spec of what #register declares as written.
     class RecordingApi < Plugin::Api
-      DECLARATIONS = %i[command annotation tool on service init toolkit tool_source peer_source].freeze
+      DECLARATIONS = %i[command annotation tool on service init toolkit tool_source peer_source prompt_section].freeze
 
       # @return [Array<Declaration>]
       def declarations = (@declarations ||= [])

data/lib/samagotchi/tools/builtins.rb

@@ -3,6 +3,7 @@
 require_relative "registry"
 require_relative "../tool_declarations"
 require_relative "../paths"
+require_relative "../project_env"
 require_relative "execute"
 require_relative "read"
 require_relative "write"
@@ -91,7 +92,7 @@ module Samagotchi
         end,
         Execute::NAME => lambda do |call, kctx|
           Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx), stop_reason: stop_reason_proc(kctx),
-                                       **participant_execute(kctx, parent_env(kctx)))
+                                       **participant_execute(kctx, project_env(kctx).merge(parent_env(kctx))))
         end,
         RegisterReminder::NAME => lambda do |call, kctx|
           RegisterReminder.call(call[:content], reminder_store: kctx.reminder_store, description: call[:description],
@@ -145,6 +146,16 @@ module Samagotchi
           SESSION_REASONING_HISTORY_ENV => history }.merge(cli_model_unset(env)).merge(xdg_absolute(env))
       end
 
+      # The session's project env (ProjectEnv.current: the worker's mise env,
+      # the chi shim first on PATH) for the commands the owner's turns run;
+      # less what every tool runs without (TaskRuntime::SANITIZED_ENV_KEYS).
+      # A participant's turn gets none of it: a project's [env] may load its
+      # .env files.
+      def project_env(kctx)
+        mode = kctx.respond_to?(:participant_mode) ? kctx.participant_mode : nil
+        mode ? {} : ProjectEnv.tools_env
+      end
+
       # execute's env: and on_timeout: for the running turn. A participant's
       # turn runs without the variables whose names hold a secret
       # (Guardrails::PairBoundary.scrubbed_env), and a command still running
@@ -179,7 +190,7 @@ module Samagotchi
       # markers are reserved, the model's env can't set them).
       def task_marker_env(kctx, env)
         given = env.is_a?(Hash) ? env.keys.map(&:to_s) : []
-        parent_env(kctx).reject { |key, _| given.include?(key) }
+        project_env(kctx).merge(parent_env(kctx)).reject { |key, _| given.include?(key) }
       end
 
       # Stop flips the turn's controller, seen through the Engine's PeerView