samagotchi 0.85.0 → 0.87.0

data/lib/samagotchi/session_commands.rb

@@ -13,7 +13,9 @@ require_relative "commands/registry"
 require_relative "llm_context_command"
 require_relative "thinking_command"
 require_relative "toolkit_command"
+require_relative "parent_answers_command"
 require_relative "reasoning_history_command"
+require_relative "guardrails/parent_policy"
 
 module Samagotchi
   # The session commands a REPL and a session worker both run: /model,
@@ -34,6 +36,7 @@ module Samagotchi
     LLM_CONTEXT_COMMAND = LLMContextCommand::NAME
     THINKING_COMMAND = ThinkingCommand::NAME
     TOOLKIT_COMMAND = ToolkitCommand::NAME
+    PARENT_ANSWERS_COMMAND = ParentAnswersCommand::NAME
     REASONING_HISTORY_COMMAND = ReasoningHistoryCommand::NAME
     # A remote catalog has hundreds of ids (OpenRouter ~380): plain /models
     # shows this many per host; /models <text> lists every match.
@@ -76,12 +79,8 @@ module Samagotchi
                         id: :rollback) { |_text| rollback }
       registry.register("!", "run a shell command; its output goes into the conversation",
                         id: :shell, mid_turn: :queue, match: ->(text) { text.match?(/\A!\s*\S/) }) { |text| shell(text) }
-      registry.register(CONTINUE_COMMAND, "answer the continue offer (yes, no or no, <reason>)") do |text|
-        next reply("nothing to continue") unless @turn_flow.awaiting_continue?
-
-        answer = text.delete_prefix(CONTINUE_COMMAND).strip
-        continue_answer(answer.empty? ? CONTINUE_COMMAND : answer)
-      end
+      # #run passes who sent it (as_parent:) per call.
+      registry.register(CONTINUE_COMMAND, "answer the continue offer (yes, no or no, <reason>)") { |text| continue_command(text) }
       # It reads the hosts only (the registry is mutex-guarded): mid-turn too.
       registry.register(MODELS_COMMAND, "list the hosts' models (/models <text> filters)", anytime: true) do |text|
         reply(models_listing(text.delete_prefix(MODELS_COMMAND).strip))
@@ -108,6 +107,11 @@ module Samagotchi
       registry.register(TOOLKIT_COMMAND, "show or change the tools this session declares (NAME, add TOOL, remove TOOL)",
                         id: :toolkit, mid_turn: show_mid_turn(TOOLKIT_COMMAND),
                         match: ->(text) { text.match?(%r{\A/toolkit(?:\s+.*)?\z}) }) { |text| toolkit(text) }
+      # Tighten-only from anyone; loosening is a user's at a UI (#run's user_ui:).
+      registry.register(PARENT_ANSWERS_COMMAND, "show or set what a parent agent may answer here (hard|standard|soft|default; " \
+                                                "never looser than config.yml's)",
+                        id: :parent_answers, mid_turn: show_mid_turn(PARENT_ANSWERS_COMMAND),
+                        match: ->(text) { text.match?(%r{\A/parent-answers(?:\s+.*)?\z}) }) { |text| parent_answers(text) }
       registry.register(HELP_COMMAND, "list the commands, the bundles' too", anytime: true) { |_text| reply(help_listing) }
       registry.register("/stats", "show the session's stats", local: true)
       registry.register("/recap", "show the session's recap", local: true)
@@ -254,8 +258,14 @@ module Samagotchi
     #   change asks first (CacheConfirm): true for a person at a web tab or
     #   a TUI; false applies it at once (chi send, a delegate, a plugin,
     #   chi -p)
+    # @param as_parent [Boolean] a parent agent sent it (client cli:answer):
+    #   a /continue yes is held to guardrails.parent_answers, as chi
+    #   answer --option Continue is (Guardrails::ParentPolicy)
+    # @param user_ui [Boolean] a user at a UI sent it (the REPL, an attached
+    #   TUI, the web; not a piped or marked one): only such a line loosens
+    #   /parent-answers
     # @return [Result, nil] nil when +line+ is not one of these commands
-    def run(line, confirm: true)
+    def run(line, confirm: true, as_parent: false, user_ui: false)
       text = line.to_s.strip
       entry = @registry.lookup(text)
       return nil unless entry&.handler
@@ -263,14 +273,33 @@ module Samagotchi
 
       # The two that may ask take the flag; the rest never ask.
       return send(entry.id, text, confirm: confirm) if CONFIRMING.include?(entry.id)
+      # Who sent it goes to its handler per call, never through an ivar:
+      # an anytime command runs on another thread against this instance.
+      return continue_command(text, as_parent: as_parent) if entry.id == :continue
+      return parent_answers(text, user_ui: user_ui) if entry.id == :parent_answers
 
       instance_exec(text, &entry.handler)
     end
 
+    # /continue [yes|no|no, <reason>]: the continue offer's answer.
+    def continue_command(text, as_parent: false)
+      return reply("nothing to continue") unless @turn_flow.awaiting_continue?
+
+      answer = text.delete_prefix(CONTINUE_COMMAND).strip
+      continue_answer(answer.empty? ? CONTINUE_COMMAND : answer, as_parent: as_parent)
+    end
+
     # Answer the pending continue offer (yes / no / no, <reason>).
+    # @param as_parent [Boolean] a parent agent's answer: a yes its strategy
+    #   doesn't allow is refused (the offer stays; decision :invalid)
     # @return [Result] resume: true on yes
-    def continue_answer(text)
+    def continue_answer(text, as_parent: false)
       decision, reason = TurnFlow.continue_decision(text)
+      if decision == :resume && as_parent &&
+         (refusal = Guardrails::ParentPolicy.continue_refusal(strategy: Guardrails::ParentPolicy.for_session(@engine.session)))
+        return reply(refusal, status: :error).tap { |result| result.decision = :invalid }
+      end
+
       result = case decision
                when :resume then Result.new(status: :ok, changed: [], model_name: model_name, resume: true, shell: false)
                when :abort
@@ -485,6 +514,14 @@ module Samagotchi
       reply(e.message, status: :error)
     end
 
+    # /parent-answers (ParentAnswersCommand); :parent_answers in changed
+    # when it set the session's own level.
+    def parent_answers(text, user_ui: false)
+      output, changed, status = ParentAnswersCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
+                                                    .run(text.delete_prefix(PARENT_ANSWERS_COMMAND), user_ui: user_ui)
+      reply(output, status: status, changed: changed ? [:parent_answers] : [])
+    end
+
     # A session setting changed (/llm-context, /thinking, /reasoning-history):
     # saved with its model.
     def save_setup(session)

data/lib/samagotchi/session_setup.rb

@@ -18,24 +18,26 @@ module Samagotchi
   # +toolkit+ a Toolkit or nil (SessionManager.spawn_session gives the
   # session config's toolkit.default then), +bundle_settings+ the bundle
   # settings chi --set gave ({bundle => {key => value}}, frozen; {} with
-  # none), which Plugin::Context#settings lays over config.yml's.
+  # none), which Plugin::Context#settings lays over config.yml's,
+  # +parent_answers+ the session's own guardrails.parent_answers (a level
+  # String, tighten-only: Guardrails::ParentPolicy.effective) or nil.
   #
   # 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 (but the toolkit its delegate call named); a continue and a
-  # fork copy their session's (.of).
+  # without one (but the toolkit its delegate call named, and its parent's
+  # parent_answers); a continue and a fork copy their session's (.of).
   SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files, :toolkit,
-                             :bundle_settings) do
+                             :bundle_settings, :parent_answers) do
     def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [], toolkit: nil,
-                   bundle_settings: {})
+                   bundle_settings: {}, parent_answers: nil)
       super(llm_context: llm_context, thinking: thinking, reasoning_history: reasoning_history,
             appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze, toolkit: toolkit,
-            bundle_settings: BundleSessionSettings.normalize(bundle_settings))
+            bundle_settings: BundleSessionSettings.normalize(bundle_settings), parent_answers: parent_answers&.to_s)
     end
 
     def empty?
       llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty? && toolkit.nil? &&
-        bundle_settings.empty?
+        bundle_settings.empty? && parent_answers.nil?
     end
 
     # A session's own setup, for a session that starts from it. Its
@@ -48,7 +50,7 @@ module Samagotchi
 
       new(llm_context: session.llm_context, thinking: session.thinking, reasoning_history: session.reasoning_history,
           appended_prompt_files: session.appended_prompt_files, toolkit: Toolkit.of(session.toolkit),
-          bundle_settings: session.bundle_settings)
+          bundle_settings: session.bundle_settings, parent_answers: session.parent_answers)
     end
   end
 end

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -53,6 +53,10 @@ module Samagotchi
       #   the line an existing session's run prints (--set too)
       # @param bundle_settings [Hash] --set's values (BundleSessionSettings):
       #   a new session's setup carries them; an existing session keeps its own
+      # @param parent_answers [String, nil] --parent-answers: a new session's
+      #   own guardrails.parent_answers; an existing session keeps its own
+      #   (never sent as a /parent-answers command: that would be a
+      #   loosening route from a command line)
       # @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,
@@ -60,12 +64,12 @@ module Samagotchi
       #   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: [], toolkit: nil,
-              toolkit_flags: [], bundle_settings: {}, state_dir: nil)
+              toolkit_flags: [], bundle_settings: {}, parent_answers: nil, 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, toolkit: toolkit, toolkit_flags: toolkit_flags,
-                         bundle_settings: bundle_settings)
+                         bundle_settings: bundle_settings, parent_answers: parent_answers)
         commands = []
         commands << "/model #{model}" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
@@ -77,13 +81,15 @@ module Samagotchi
                                     first_command: first_command, no_interrupt: no_interrupt,
                                     default_input: default_input && !prompt && !attach && !resume,
                                     wait_at_eof: !$stdin.tty?,
-                                    parent_answers: Guardrails::ParentApprovals.parent_process?, state_dir: state_dir)
+                                    as_parent: Guardrails::ParentApprovals.parent_process?, state_dir: state_dir)
         ended = begin
           attached.run
         ensure
           close_surface(surface)
         end
-        report_unanswered(attached.unanswered, session_id: client.session_id) if ended == :unanswered && attached.unanswered
+        if ended == :unanswered && attached.unanswered
+          report_unanswered(attached.unanswered, session_id: client.session_id, state_dir: state_dir)
+        end
         report_ended(ended)
         ended
       end
@@ -92,9 +98,12 @@ module Samagotchi
       # --wait` prints it (ParentReport), so a script or a parent agent
       # can answer it with chi answer.
       # @param pending [Hash] the pending question as the Bridge sent it
-      def report_unanswered(pending, session_id:, err: $stderr)
+      # @param state_dir [String, nil] where the session file is: what a
+      #   parent may pick follows its own parent_answers too
+      def report_unanswered(pending, session_id:, err: $stderr, state_dir: nil)
         question = PendingQuestion.from_file(pending)
-        err.print("chi: #{ParentReport.question_text(question, session_id: session_id)}")
+        strategy = ParentReport.strategy_for(session_id, state_dir: state_dir || Session.default_state_dir)
+        err.print("chi: #{ParentReport.question_text(question, session_id: session_id, strategy: strategy)}")
         err.flush
       end
 
@@ -134,7 +143,7 @@ module Samagotchi
       # @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: [], toolkit: nil,
-                  toolkit_flags: [], bundle_settings: {}, err: $stderr)
+                  toolkit_flags: [], bundle_settings: {}, parent_answers: nil, 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,
@@ -156,7 +165,8 @@ module Samagotchi
                                                  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,
-                                                                         toolkit: toolkit, bundle_settings: bundle_settings))
+                                                                         toolkit: toolkit, bundle_settings: bundle_settings,
+                                                                         parent_answers: parent_answers))
                   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")

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -105,7 +105,7 @@ module Samagotchi
       # @param state_dir [String] the state dir the worker was found in: its
       #   session folder (@path images, saved records) is under it
       def initialize(client:, screen:, client_id:, first_prompt: nil, first_command: nil, no_interrupt: false,
-                     default_input: false, wait_at_eof: false, parent_answers: false,
+                     default_input: false, wait_at_eof: false, as_parent: false,
                      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
                      delete_session: ->(id) { SessionManager.delete_session(id, stop: true, wait: DELETE_WAIT) },
                      archive_session: ->(id) { SessionManager.archive_session(id, wait: DELETE_WAIT) },
@@ -121,8 +121,8 @@ module Samagotchi
         @client_id = client_id
         # A parent agent drives this attach (AttachLauncher:
         # ParentApprovals.parent_process?): its answers go as chi answer's,
-        # so the worker holds them to guardrails.parent_approvals.
-        @parent_answers = parent_answers
+        # so the worker holds them to Guardrails::ParentPolicy.
+        @as_parent = as_parent
         @view = AttachedView.new(screen)
         @renderer = EventRenderer.new(@view)
         @shown_enqueued = Set.new
@@ -592,7 +592,7 @@ module Samagotchi
       # The worker runs it and every UI renders its :command_ran, this one
       # too, so nothing waits here.
       def send_command(line)
-        reply = @client.post_command(line: line, client_id: @client_id)
+        reply = @client.post_command(line: line, client_id: client_id_for(line))
         if reply.status == 202
           # Input from a pipe ends once its output is in (#command_ran).
           command_id = reply.json&.fetch("command_id", nil)
@@ -805,13 +805,27 @@ module Samagotchi
         steer_cut_note(ack["cut"].to_s.to_sym, ack["cut_after"])
       end
 
+      # The client id +line+ goes with, as a command (#send_command) or as a
+      # message the Bridge may run as one (#send_prompt: /cut and /queue
+      # text). A parent agent's /continue yes and /parent-answers go as chi
+      # answer's: the worker holds the first to guardrails.parent_answers and
+      # never takes the second as a user's loosening. The command is the
+      # registry's own match (the worker's), not a pattern of ours.
+      def client_id_for(line)
+        return @client_id unless @as_parent
+        return ClientId::CLI_ANSWER if TurnFlow.continue_yes?(line)
+        return ClientId::CLI_ANSWER if command_registry.lookup(line)&.id == :parent_answers
+
+        @client_id
+      end
+
       def send_prompt(text, delivery: nil)
         persist_recent_history(text)
         images = attach_images(text)
         return own_prompt_failed if images.nil?
 
         running = @running
-        options = { prompt: text, client_id: @client_id }
+        options = { prompt: text, client_id: client_id_for(text) }
         options[:no_interrupt] = true if @no_interrupt
         options[:images] = images unless images.empty?
         options[:delivery] = delivery if delivery
@@ -990,7 +1004,7 @@ module Samagotchi
           return @screen.commit(answer.error)
         end
 
-        parent = @parent_answers ? { client_id: ClientId::CLI_ANSWER } : {}
+        parent = @as_parent ? { client_id: ClientId::CLI_ANSWER } : {}
         reply = @client.answer(id: @question.id, selected: answer.selected, freeform: answer.freeform, **parent)
         case reply.status
         when 200
@@ -1554,14 +1568,13 @@ module Samagotchi
         elsif !(own?(origin[:client_id]) || @shown_enqueued.include?(origin[:enqueued_id]))
           @screen.commit(prompt_line(origin[:client_id], event[:prompt]))
         end
-        # Another client's prompt line is up (here or at its enqueue); an
-        # own send has none, so its image lines are its echo.
-        @renderer.call(own?(origin[:client_id]) ? event : without_named_images(event, event[:prompt]))
+        # The own-send echo already names an image-only prompt; another
+        # client's prompt line does too, here or at its enqueue.
+        @renderer.call(without_named_images(event, event[:prompt]))
       end
 
-      # The turn's start without its image lines when the prompt line shown
-      # for it is the web's "[image: name]" text of a turn of images alone:
-      # that line names them already.
+      # The turn's start without its image lines when the shown prompt is
+      # the image-only "[image: name]" placeholder: that line names them.
       def without_named_images(event, shown_prompt)
         ImageRef.placeholder_only?(shown_prompt) ? event.except(:images) : event
       end

data/lib/samagotchi/terminal_ui/thinking_line.rb

@@ -11,9 +11,9 @@ module Samagotchi
     # ThinkingTicker (so it changes at most once per dwell). Both TUIs use it
     # in place of the raw tail of the stream.
     #
-    # A chunk carries :text (and :thinking): both loops split their stream,
-    # for every profile. A chunk without them (an older worker) has its raw
-    # :content, markup stripped, stand for thinking. A switch of lane starts the next sentence from the new
+    # A chunk carries :text and :thinking: both loops split their stream,
+    # for every profile (the raw :content stays in the worker,
+    # Bridge::ClientEvent). A switch of lane starts the next sentence from the new
     # lane's text; the line shown keeps the label of the lane it came from.
     class ThinkingLine
       include Formatting
@@ -43,12 +43,8 @@ module Samagotchi
       # @return [Boolean] whether the line changed
       def chunk(event)
         # The Bridge's TurnAccumulator reads the lanes by the same rule.
-        if event.key?(:text)
-          changed = add(:thinking, event[:thinking])
-          add(:writing, event[:text]) || changed
-        else
-          add(:thinking, event[:content], raw: true)
-        end
+        changed = add(:thinking, event[:thinking])
+        add(:writing, event[:text]) || changed
       end
 
       # A turn joined mid-way: the newest thinking or text part so far.

data/lib/samagotchi/terminal_ui.rb

@@ -105,10 +105,14 @@ module Samagotchi
     # @param bundle_settings [Hash] --set's values (BundleSessionSettings):
     #   a new session's own; a resumed one keeps its own (--set is in
     #   +toolkit_flags+ then)
+    # @param parent_answers [String, nil] --parent-answers: a new session's
+    #   own guardrails.parent_answers; a resumed one keeps its own (named in
+    #   +toolkit_flags+ then)
     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: [], toolkit: nil, toolkit_flags: [], bundle_settings: {})
+                   appended_prompt_files: [], toolkit: nil, toolkit_flags: [], bundle_settings: {}, parent_answers: nil)
       @scratch        = scratch
+      @parent_answers = parent_answers
       @toolkit        = toolkit
       @toolkit_flags  = toolkit_flags
       @bundle_settings = bundle_settings
@@ -281,7 +285,7 @@ module Samagotchi
         muted_memory_names: @muted_memory_names,
         scratch: @scratch,
         setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files, toolkit: @toolkit || Toolkit.configured,
-                                bundle_settings: @bundle_settings)
+                                bundle_settings: @bundle_settings, parent_answers: @parent_answers)
       ))
       # --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.
@@ -295,7 +299,7 @@ module Samagotchi
       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.
-      session.save if @resume_session && TurnCheckpoint.settle(session)
+      session.save if @resume_session && TurnCheckpoint.settle(session, session_dir: Session.session_dir(session.id))
       keep_cards(session)
       # Saved at once, so a process killed before its first turn leaves a
       # file the sweep knows to delete.
@@ -830,7 +834,7 @@ module Samagotchi
     end
 
     def answer_continue_offer(session, input)
-      answer = @commands.continue_answer(input)
+      answer = @commands.continue_answer(input, as_parent: as_parent?)
       if answer.decision == :invalid
         # The read left no echo: the line shows above its error.
         @surface.commit("#{paint(QUESTION_PROMPT, 33)}#{input}")
@@ -876,7 +880,11 @@ module Samagotchi
         command = if command_registry.anytime?(input)
                     @engine.running_anytime { @commands.run(input, confirm: confirm) }
                   else
-                    @commands.run(input, confirm: confirm)
+                    # A parent's /continue yes is held to guardrails.parent_answers;
+                    # only a person here (not piped, no agent marker) loosens
+                    # /parent-answers.
+                    parent = as_parent?
+                    @commands.run(input, confirm: confirm, as_parent: parent && TurnFlow.continue_yes?(input), user_ui: !parent)
                   end
         if command
           show_command_result(command)
@@ -1579,15 +1587,16 @@ module Samagotchi
         end
 
         begin
-          parent = parent_answers? ? { client_id: ClientId::CLI_ANSWER } : {}
+          parent = as_parent? ? { client_id: ClientId::CLI_ANSWER } : {}
           @engine.answer_question(id: prompt.id, selected: answer.selected, freeform: answer.freeform, **parent)
           close_question_widget(prompt, prompt.answer_text(answer))
           return true
         rescue QuestionDesk::Refused => e
-          # A parent's allow guardrails.parent_approvals doesn't let through:
-          # the question stays open for a deny (or the end of the input).
+          # A parent's pick its strategy doesn't let through
+          # (Guardrails::ParentPolicy): the question stays open for a deny
+          # (or the end of the input).
           echo_choice(raw)
-          @surface.commit(Guardrails::ParentApprovals.message(e.reason, typed: true))
+          @surface.commit(e.detail(typed: true))
           next
         rescue ArgumentError => e
           @surface.commit("Invalid: #{e.message}. Try again.")
@@ -1600,8 +1609,8 @@ module Samagotchi
     end
 
     # Whether the answers typed here are a parent agent's (piped stdin, an
-    # agent marker): QuestionDesk holds them to guardrails.parent_approvals.
-    def parent_answers?
+    # agent marker): QuestionDesk holds them to Guardrails::ParentPolicy.
+    def as_parent?
       Guardrails::ParentApprovals.parent_process?
     end
 

data/lib/samagotchi/testing/boundary.rb

@@ -79,9 +79,6 @@ module Samagotchi
           "Samagotchi::Session.new_session" => "spec: #{SESSION} (ctx.delegate?, ctx.fork?, ctx.context read it)",
           "Samagotchi::ContextSources.session_location" => "spec: reads and removes the session's sources (added_by), " \
                                                             "which ctx.context.list doesn't show",
-          'require "samagotchi/memory_bundle/installer"' => "spec: for Installer",
-          "Samagotchi::MemoryBundle::Installer.new" => "spec: installs the bundle so its context provider resolves: " \
-                                                       "needs a kit install helper",
           'require "samagotchi/context_providers"' => "spec: for ContextProviders",
           "Samagotchi::ContextProviders.resolve" => "spec: the manifest's URL provider through chi's own resolver",
           'require "samagotchi/answer_display"' => "spec: for AnswerDisplay",

data/lib/samagotchi/testing/bundle.rb

@@ -240,6 +240,13 @@ module Samagotchi
         failing { entry.handler.call({ name: name.to_s, args: stringify(args) }, nil) }
       end
 
+      # Install this bundle's dir into its sandbox as chi does and load the
+      # installed copy with chi's loaders (Install.run, with its settings):
+      # what a test of the installed bundle needs (its scripts, context
+      # providers), and the install warnings and load failures.
+      # @return [Install::Result]
+      def install(force: false) = Install.run(@dir, settings: @settings, sandbox: @sandbox, force: force)
+
       # Run the chi.init blocks in order, as chi's init tasks do.
       # @return [Array] their results
       def run_inits = failing { @inits.map { |init| init.block.call } }

data/lib/samagotchi/testing/host.rb

@@ -27,8 +27,9 @@ module Samagotchi
           messages: -> { recorder[:messages] },
           messages_partial: -> { recorder[:messages_partial] },
           notify: ->(text, level, label, fallback_for: nil) { recorder.notify(text, level, label, fallback_for) },
-          ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:|
-            recorder.ask_user(question: question, options: options, header: header, allow_freeform: allow_freeform, hook: hook)
+          ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:, effects: nil|
+            recorder.ask_user(question: question, options: options, header: header, allow_freeform: allow_freeform, hook: hook,
+                              effects: effects)
           },
           cancelled: -> { recorder[:cancelled] },
           card: ->(**card) { recorder.card(**card) },
@@ -88,8 +89,9 @@ module Samagotchi
       def build(recorder)
         Hooks::Runtime.new(
           notify: ->(text:, level:, hook:, fallback_for: nil) { recorder.notify(text, level, hook, fallback_for) },
-          ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:|
-            recorder.ask_user(question: question, options: options, header: header, allow_freeform: allow_freeform, hook: hook)
+          ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:, effects: nil|
+            recorder.ask_user(question: question, options: options, header: header, allow_freeform: allow_freeform, hook: hook,
+                              effects: effects)
           },
           stop_turn: ->(reason:, hook:) { recorder.stop(:turn, reason, hook) },
           steer: ->(text:, hook:) { recorder.steer(text, hook) },

data/lib/samagotchi/testing/install.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "../extension_load"
+require_relative "../guardrails/load_failures"
+require_relative "../memory_bundle/installer"
+require_relative "../memory_bundle/provenance"
+require_relative "../hooks"
+require_relative "bundle"
+require_relative "sandbox"
+require_relative "recorder"
+require_relative "host"
+
+module Samagotchi
+  module Testing
+    # A bundle as chi installs and loads it, unlike Bundle (its source as it
+    # is): MemoryBundle::Installer copies it into the sandbox's state (sha256
+    # and requires_chi checked), then chi's own loaders load what is
+    # installed (ExtensionLoad: the bundle hooks, then the plugins). What
+    # failed names the bundle's source files, not the installed copies.
+    #
+    #   result = Samagotchi::Testing::Install.run("path/to/bundle", settings: { "every" => 3 })
+    #   result.warnings, result.plugin_failures, result.hook_failures, result.registered[:commands]
+    module Install
+      # warnings: the Installer's; plugin_failures / hook_failures:
+      # [Guardrails::LoadFailures::Failure] of this bundle, each location
+      # in the source dir; registered: what it registered (#registered).
+      Result = Data.define(:name, :warnings, :plugin_failures, :hook_failures, :registered) do
+        def failures = plugin_failures + hook_failures
+        def ok? = failures.empty?
+      end
+
+      module_function
+
+      # Install the bundle at +dir+ into +sandbox+ (default Sandbox.current,
+      # else one of its own, left before returning) and load it.
+      # @param settings [Hash] config.yml `bundles: <name>:` (written to the
+      #   sandbox's config.yml)
+      # @param force [Boolean] the Installer's --force (a name chi ships)
+      # @return [Result]
+      # @raise [MemoryBundle::Installer::InstallError] what the Installer refused
+      def run(dir, settings: {}, sandbox: nil, force: false)
+        return Sandbox.with { |own| run(dir, settings: settings, sandbox: own, force: force) } if sandbox.nil? && Sandbox.current.nil?
+
+        sandbox ||= Sandbox.current
+        dir = File.expand_path(dir)
+        name = MemoryBundle::Manifest.read(dir: dir).name
+        sandbox.config("bundles" => { name => settings })
+        installer = MemoryBundle::Installer.new(source: dir, name: name, scope: "system", force: force)
+        installer.run
+        load_installed(name, dir, installer.warnings, sandbox)
+      end
+
+      def load_installed(name, dir, warnings, sandbox)
+        inits = []
+        # A session's values, as an Engine's host gives them (only what the loaders register matters).
+        host = Host.build(Recorder.new(cwd: sandbox.work_dir))
+        hook_failures = Guardrails::LoadFailures.new
+        plugin_failures = Guardrails::LoadFailures.new
+        extension = ExtensionLoad.new(hook_failures: hook_failures)
+        registries = Plugin::Registries.new(
+          commands: SessionCommands.register_builtins(Commands::Registry.new),
+          tools: Tools::Builtins.registry, hooks: extension.hooks,
+          context_for: lambda { |bundle, bundle_settings, label|
+            Plugin::Context.new(bundle: bundle, label: label, settings: bundle_settings, host: host)
+          },
+          services: Plugin::Services.new, stage_tools: ->(*) {},
+          init: ->(_bundle, label, _plugin_label, **, &_block) { inits << { label: label } },
+          toolkits: [], tool_index: Tools::ToolIndex.new, peer_sources: PeerSources.new
+        )
+        extension.load_plugins(registries, failures: plugin_failures)
+        installed = File.join(MemoryBundle::Provenance.bundles_dir, name)
+        Result.new(name: name, warnings: warnings.dup,
+                   plugin_failures: own(plugin_failures, name, installed, dir),
+                   hook_failures: own(hook_failures, name, installed, dir),
+                   registered: registered(registries, name, inits))
+      ensure
+        registries&.services&.stop_all
+      end
+      private_class_method :load_installed
+
+      # What bundle +name+ registered, from the registries it loaded into:
+      # commands ([name, mid_turn, annotation labels]), tools, hooks per
+      # event ([bundle, hook, priority]; Hooks::EVENTS, then any other event
+      # the bundle registered for), inits, toolkits, tool sources and
+      # peer sources.
+      # @param inits [Array<Hash>] {label:} of each chi.init
+      # @return [Hash]
+      def registered(registries, name, inits)
+        {
+          commands: registries.commands.entries.select { |e| e.source == name }.map { |e| [e.name, e.mid_turn, e.annotations.map(&:label)] },
+          tools: registries.tools.by_source(name).map(&:name),
+          hooks: hooks_of(registries.hooks, name),
+          inits: inits.map { |init| init[:label] },
+          toolkits: Array(registries.toolkits).map(&:name),
+          tool_sources: registries.tool_index.sources.map(&:label),
+          peer_sources: registries.peer_sources.names
+        }
+      end
+
+      def hooks_of(hooks, name)
+        own = ->(event) { hooks.bundle_hook_names(event).select { |bundle, _, _| bundle == name } }
+        others = (hooks.bundle_events - Hooks::EVENTS).to_h { |event| [event, own.call(event)] }.reject { |_, list| list.empty? }
+        Hooks::EVENTS.to_h { |event| [event, own.call(event)] }.merge(others)
+      end
+      private_class_method :hooks_of
+
+      # +failures+' entries for bundle +name+, their location moved from the
+      # installed copy to the source dir.
+      def own(failures, name, installed, dir)
+        failures.list.select { |f| f.what.end_with?("(bundle #{name})") }.map do |failure|
+          # The plugin is installed into plugin/, the hooks into hooks/.
+          location = failure.location&.sub(%r{\A#{Regexp.escape(installed)}/(?:plugin/)?}, "#{dir}/")
+          failure.dup.tap { |copy| copy.location = location }
+        end
+      end
+      private_class_method :own
+    end
+  end
+end

data/lib/samagotchi/testing/recorder.rb

@@ -2,6 +2,7 @@
 
 require_relative "../plugin/card"
 require_relative "../plugin/context"
+require_relative "../guardrails/parent_policy"
 
 module Samagotchi
   module Testing
@@ -12,8 +13,11 @@ module Samagotchi
     Steer = Data.define(:text, :hook)
     # A stop_turn or stop_generation (+kind+ :turn or :generation).
     Stop = Data.define(:kind, :reason, :hook)
-    # An ask_user question.
-    Question = Data.define(:question, :options, :header, :allow_freeform, :hook)
+    # An ask_user question; effects: its options' tags as the bundle gave
+    # them (label => effect), nil for none.
+    Question = Data.define(:question, :options, :header, :allow_freeform, :hook, :effects) do
+      def initialize(effects: nil, **) = super
+    end
     # An ask_model request: the request Context built (SideQuestion), its
     # limits, cancel controller and the model: it named (nil: the session's;
     # the kit doesn't check it against any hosts), and +source+, the asking
@@ -100,9 +104,14 @@ module Samagotchi
       end
 
       # The next queued answer (#answers), nil with none (no one to ask).
-      def ask_user(question:, options:, header:, allow_freeform:, hook:)
+      # Effects chi would refuse (a label the options don't have, an
+      # unknown effect: Guardrails::ParentPolicy.option_tags) ask no one, as
+      # in chi: nil, nothing recorded, no answer taken.
+      def ask_user(question:, options:, header:, allow_freeform:, hook:, effects: nil)
+        return nil if Guardrails::ParentPolicy.option_tags(options, effects) == false
+
         record(@questions, Question.new(question: question, options: options, header: header,
-                                        allow_freeform: allow_freeform, hook: hook))
+                                        allow_freeform: allow_freeform, hook: hook, effects: effects))
         answer = @mutex.synchronize { @answers.shift }
         answer.respond_to?(:call) ? answer.call(@questions.last) : answer
       end