samagotchi 0.79.0 → 0.80.0

data/lib/samagotchi/testing/fake_http.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../plugin/http"
+
+module Samagotchi
+  module Testing
+    # A request no stub answered (FakeHttp). Not an HttpError: a plugin's
+    # `rescue Plugin::HttpError` doesn't swallow it, and the test fails at
+    # teardown even when the plugin rescued it (FakeHttp#unmatched).
+    class UnstubbedRequest < StandardError; end
+
+    # ctx.http's wire in a bundle's test (docs/plugins.md, "Testing a
+    # bundle"): requests are answered by stubs, never by the network.
+    #
+    #   bundle.http.stub(:post, "http://127.0.0.1:9000/classify", json: { label: "safe" })
+    #   bundle.http.stub(:get, %r{/health\z}, status: 503, body: "down")
+    #   bundle.http.stub(:post, "http://127.0.0.1:9000/classify") { |req| { json: { label: req.json["text"] } } }
+    #   bundle.http.stub(:get, "http://127.0.0.1:9000/x", error: :refused)   # also :timeout
+    #   bundle.http.requests    # what the plugin sent, in order
+    #   bundle.http.unmatched   # what no stub answered
+    #
+    # A String matches the full URL exactly (query included), a Regexp is
+    # matched against it; the method too. Later stubs win. A stub answers
+    # every matching call: a sequence is a block that counts.
+    class FakeHttp
+      # One request the plugin made (headers as the plugin gave them).
+      # `method` shadows Object#method on purpose: it is the plugin's word (request.method == "POST").
+      Request = Data.define(:method, :url, :headers, :body) do # rubocop:disable Lint/DataDefineOverride
+        # The body parsed as JSON.
+        def json = JSON.parse(body.to_s)
+      end
+
+      Stub = Data.define(:verb, :matcher, :answer) do
+        def match?(request)
+          request.method == verb &&
+            (matcher.is_a?(Regexp) ? matcher.match?(request.url) : matcher == request.url)
+        end
+      end
+      private_constant :Stub
+
+      # What error: names, and the words the real transport's message says.
+      ERRORS = { refused: "connection refused", timeout: "timed out" }.freeze
+
+      # The failure message for requests no stub answered (the adapters'
+      # teardown check).
+      # @param requests [Array<Request>] FakeHttp#unmatched, of every bundle
+      def self.unmatched_message(requests)
+        lines = requests.map { |request| "  #{request.method} #{request.url}" }
+        "ctx.http made #{requests.size} request#{"s" unless requests.size == 1} no stub answered " \
+          "(bundle.http.stub):\n#{lines.join("\n")}"
+      end
+
+      def initialize
+        @mutex = Mutex.new
+        @stubs = []
+        @requests = []
+        @unmatched = []
+      end
+
+      # Answer +method+ requests to +url+.
+      # @param method [Symbol, String] :get, :post, :put, :patch, :delete, :head
+      # @param url [String, Regexp]
+      # @param status [Integer]
+      # @param headers [Hash]
+      # @param body [String, nil]
+      # @param json [Object, nil] a JSON body (with its Content-Type)
+      # @param error [Symbol, nil] :refused or :timeout: the request fails
+      #   with the HttpError the real transport raises
+      # @yield [Request] to decide per request: returns a Hash with the same
+      #   keywords (status:, headers:, body:, json:, error:) or a
+      #   Plugin::Http::Response
+      # @return [self]
+      def stub(method, url, status: 200, headers: {}, body: nil, json: nil, error: nil, &block)
+        verb = method.to_s.upcase
+        raise ArgumentError, "unknown HTTP method #{method.inspect}" unless Plugin::Http::METHODS.include?(verb)
+        raise ArgumentError, "the URL is a String or a Regexp" unless url.is_a?(String) || url.is_a?(Regexp)
+        raise ArgumentError, "unknown error #{error.inspect} (#{ERRORS.keys.join(", ")})" if error && !ERRORS.key?(error)
+
+        answer = block || { status: status, headers: headers, body: body, json: json, error: error }
+        @mutex.synchronize { @stubs << Stub.new(verb: verb, matcher: url, answer: answer) }
+        self
+      end
+
+      # @return [Array<Request>] every request the plugin sent, in order
+      def requests = @mutex.synchronize { @requests.dup }
+
+      # @return [Array<Request>] the requests no stub answered (the test
+      #   fails at teardown when there are any)
+      def unmatched = @mutex.synchronize { @unmatched.dup }
+
+      # The transport contract (Plugin::Http): the +cancel+ it is given is
+      # the only cancel it checks.
+      # @raise [UnstubbedRequest, Plugin::HttpError, Plugin::HttpCancelled]
+      def call(method:, uri:, headers:, body:, timeout:, cancel:)
+        raise Plugin::HttpCancelled, "#{method} #{where(uri)}: cancelled" if cancel&.cancelled?
+
+        request = Request.new(method: method, url: uri.to_s, headers: headers.dup.freeze, body: body)
+        stub = @mutex.synchronize do
+          @requests << request
+          @stubs.reverse_each.find { |candidate| candidate.match?(request) }.tap { |found| @unmatched << request unless found }
+        end
+        raise UnstubbedRequest, unstubbed_message(request) unless stub
+
+        respond(request, uri, stub.answer.respond_to?(:call) ? stub.answer.call(request) : stub.answer)
+      end
+
+      private
+
+      def respond(request, uri, answer)
+        return answer if answer.is_a?(Plugin::Http::Response)
+        raise ArgumentError, "a stub's block returns a Hash or a Plugin::Http::Response" unless answer.is_a?(Hash)
+
+        if (error = answer[:error])
+          raise Plugin::HttpError, "#{request.method} #{where(uri)}: #{ERRORS.fetch(error) { raise ArgumentError, "unknown error #{error.inspect}" }}"
+        end
+
+        headers = (answer[:headers] || {}).to_h { |name, value| [name.to_s.downcase, value.to_s] }
+        body = answer[:body].to_s
+        unless answer[:json].nil?
+          body = JSON.generate(answer[:json])
+          headers = { "content-type" => "application/json" }.merge(headers)
+        end
+        body = "" if request.method == "HEAD"
+        Plugin::Http::Response.new(status: Integer(answer[:status] || 200), headers: headers.freeze, body: body.dup)
+      end
+
+      def where(uri) = "#{uri.host}:#{uri.port}"
+
+      def unstubbed_message(request)
+        stubs = @mutex.synchronize { @stubs.map { |stub| "#{stub.verb} #{stub.matcher.inspect}" } }
+        "no stub for #{request.method} #{request.url}; stubbed: #{stubs.empty? ? "none" : stubs.join(", ")} " \
+          "(bundle.http.stub(:#{request.method.downcase}, ...))"
+      end
+    end
+  end
+end

data/lib/samagotchi/testing/helpers.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "bundle"
+require_relative "fake_http"
+require_relative "sandbox"
+require_relative "waiting"
+
+module Samagotchi
+  module Testing
+    # For any test framework: load bundles that #shutdown_bundles stops,
+    # in the test's sandbox. The RSpec and Minitest adapters call
+    # #enter_sandbox before each test and #leave_sandbox after it.
+    module Helpers
+      include Waiting
+
+      # The bundle in +dir+ (Bundle.load), shut down after the test.
+      def load_bundle(dir, **) = remember_bundle(Bundle.load(dir, sandbox: sandbox, **))
+
+      # A shipped bundle by name (Bundle.shipped), shut down after the test.
+      def shipped_bundle(name, **) = remember_bundle(Bundle.shipped(name, sandbox: sandbox, **))
+
+      # This test's sandbox (entered on first use when no adapter did).
+      # @return [Sandbox]
+      def sandbox = (@samagotchi_sandbox ||= Sandbox.enter)
+
+      def enter_sandbox = sandbox
+
+      # Shut the loaded bundles down and leave the sandbox, then say what
+      # no stub answered: the adapters fail the test with it (only a test
+      # that passed: a failure of its own is not hidden). The requests are
+      # collected before the shutdown, and nothing is raised before the
+      # cleanup is done.
+      # @return [Array<FakeHttp::Request>] the ctx.http requests no stub
+      #   answered, of every bundle the test loaded
+      def leave_sandbox
+        unmatched = (@samagotchi_bundles || []).flat_map { |bundle| bundle.http.unmatched }
+        shutdown_bundles
+        @samagotchi_sandbox&.leave
+        @samagotchi_sandbox = nil
+        unmatched
+      end
+
+      def shutdown_bundles
+        (@samagotchi_bundles || []).reverse_each(&:shutdown)
+        @samagotchi_bundles = []
+      end
+
+      private
+
+      def remember_bundle(bundle)
+        (@samagotchi_bundles ||= []) << bundle
+        bundle
+      end
+    end
+  end
+end

data/lib/samagotchi/testing/host.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "../cancellation_controller"
+require_relative "../plugin/context"
+require_relative "recorder"
+
+module Samagotchi
+  module Testing
+    # The Engine side of a bundle's Context, recorded: a real Plugin::Host
+    # with every member set, its values read from the Recorder at each call
+    # and its actions landing in it.
+    module Host
+      module_function
+
+      # @param recorder [Recorder]
+      # @param toolkits [#call] → the toolkit names ctx.use_toolkit accepts
+      # @param tool_names [#call] → the declared tools when none is set
+      # @return [Plugin::Host]
+      def build(recorder, toolkits: -> { [] }, tool_names: -> { [] })
+        # ctx.http's default cancel: a cancelled controller while the test
+        # says the turn is (cancelled: true), none otherwise.
+        stopped = CancellationController.new.tap { |controller| controller.cancel!(:test) }
+        Plugin::Host.new(
+          session_id: -> { recorder[:session_id] },
+          cwd: -> { recorder[:cwd] },
+          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)
+          },
+          cancelled: -> { recorder[:cancelled] },
+          card: ->(**card) { recorder.card(**card) },
+          ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil|
+            recorder.ask_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
+                                        model: model)
+          },
+          model_name: -> { recorder[:model_name] },
+          model_key: -> { recorder[:model_key] },
+          state_dir: -> { recorder[:state_dir] || Session.default_state_dir },
+          scratch: -> { recorder[:scratch] },
+          setup: -> { recorder[:setup] },
+          prompt_files: -> { recorder[:prompt_files] },
+          steer: ->(text, label) { recorder.steer(text, label) },
+          stop_turn: ->(reason, label) { recorder.stop(:turn, reason, label) },
+          stop_generation: ->(reason, label) { recorder.stop(:generation, reason, label) },
+          frontend: -> { recorder[:frontend] },
+          toolkit: -> { recorder[:toolkit] },
+          declared_tools: -> { recorder[:declared_tools] || tool_names.call },
+          use_toolkit: ->(name) { recorder.use_toolkit(name, toolkits.call) },
+          cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil }
+        )
+      end
+    end
+
+    # The hook runtime (Hooks::Runtime: event[:notify] and the other
+    # helpers), recorded in the same Recorder as the Host.
+    module Runtime
+      module_function
+
+      # @param recorder [Recorder]
+      # @return [Hooks::Runtime]
+      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)
+          },
+          stop_turn: ->(reason:, hook:) { recorder.stop(:turn, reason, hook) },
+          steer: ->(text:, hook:) { recorder.steer(text, hook) },
+          stop_generation: ->(reason:, hook:) { recorder.stop(:generation, reason, hook) }
+        )
+      end
+    end
+  end
+end

data/lib/samagotchi/testing/minitest.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "minitest"
+require_relative "../testing"
+
+module Samagotchi
+  module Testing
+    # The bundle test kit in Minitest (EXPERIMENTAL, docs/plugins.md): a
+    # test case with Helpers (load_bundle, shipped_bundle, sandbox), each
+    # test in its own sandbox, its bundles shut down after it.
+    #
+    #   class MyBundleTest < Samagotchi::Testing::Case
+    #     def test_denies = assert load_bundle(__dir__ + "/..").tool_call({ name: "execute", content: "rm -rf /" }).deny?
+    #   end
+    class Case < Minitest::Test
+      include Helpers
+
+      def before_setup
+        super
+        enter_sandbox
+      end
+
+      def after_teardown
+        unmatched = leave_sandbox
+        super
+        # After the cleanup, and only over a test that passed.
+        flunk(FakeHttp.unmatched_message(unmatched)) if !unmatched.empty? && passed?
+      end
+    end
+  end
+end

data/lib/samagotchi/testing/recorder.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "../plugin/card"
+require_relative "../plugin/context"
+
+module Samagotchi
+  module Testing
+    # A line to the user (ctx.notify, event[:notify]); +hook+ is the
+    # plugin's or hook file's label ("plugin.rb (bundle x)").
+    Notice = Data.define(:text, :level, :hook, :fallback_for)
+    # Text put into the running turn (ctx.steer, event[:steer]).
+    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_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).
+    ModelRequest = Data.define(:request, :timeout, :max_tokens, :cancel, :model)
+
+    # What a bundle did at chi's edges, for a test to read: the Engine side
+    # of its Context (Testing::Host) and the hook runtime (Testing::Runtime)
+    # land here, file hooks and plugin hooks in the same lists. It also
+    # holds what those edges answer: queued ask_user / ask_model answers and
+    # the session's values (#values), read at each call.
+    class Recorder
+      # The session values a Host reads when the test sets none.
+      DEFAULTS = {
+        session_id: "test-session", cwd: nil, messages: [], messages_partial: false, model_name: "test:model",
+        model_key: "model", toolkit: "full", declared_tools: nil, frontend: :worker, scratch: false, setup: nil,
+        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true
+      }.freeze
+
+      attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :answers,
+                  :model_answers, :values
+
+      def initialize(**values)
+        unknown = values.keys - DEFAULTS.keys
+        raise ArgumentError, "unknown host values: #{unknown.join(", ")}" unless unknown.empty?
+
+        @values = DEFAULTS.merge(values)
+        @notices = []
+        @cards = []
+        @steers = []
+        @stops = []
+        @questions = []
+        @model_requests = []
+        @toolkit_uses = []
+        @answers = []
+        @model_answers = []
+        @mutex = Mutex.new
+      end
+
+      # Change session values (cwd:, messages:, running:, cancelled: …).
+      def set(**values)
+        unknown = values.keys - DEFAULTS.keys
+        raise ArgumentError, "unknown host values: #{unknown.join(", ")}" unless unknown.empty?
+
+        @mutex.synchronize { @values.merge!(values) }
+        self
+      end
+
+      def [](key) = @mutex.synchronize { @values.fetch(key) }
+
+      # Only stop_turn's, or only stop_generation's.
+      def turn_stops = stops.select { |stop| stop.kind == :turn }
+      def generation_stops = stops.select { |stop| stop.kind == :generation }
+
+      def notify(text, level, hook, fallback_for)
+        record(@notices, Notice.new(text: text.to_s, level: level, hook: hook, fallback_for: fallback_for))
+        nil
+      end
+
+      # Checked as chi's cards are (Plugin::Card.build); the id it shows.
+      def card(**fields)
+        card = Plugin::Card.build(**fields).freeze
+        record(@cards, card)
+        card[:id]
+      end
+
+      def steer(text, hook)
+        return false unless self[:running]
+
+        record(@steers, Steer.new(text: text.to_s, hook: hook))
+        true
+      end
+
+      def stop(kind, reason, hook)
+        return false unless self[:running]
+
+        record(@stops, Stop.new(kind: kind, reason: reason.to_s, hook: hook))
+        true
+      end
+
+      # The next queued answer (#answers), nil with none (no one to ask).
+      def ask_user(question:, options:, header:, allow_freeform:, hook:)
+        record(@questions, Question.new(question: question, options: options, header: header,
+                                        allow_freeform: allow_freeform, hook: hook))
+        answer = @mutex.synchronize { @answers.shift }
+        answer.respond_to?(:call) ? answer.call(@questions.last) : answer
+      end
+
+      # The next queued model answer (#model_answers): a String, an
+      # exception to raise, or a callable given the ModelRequest. None left:
+      # Plugin::ModelError, as an unreachable model.
+      def ask_model(request, timeout:, max_tokens:, cancel_controller:, model: nil)
+        entry = ModelRequest.new(request: request, timeout: timeout, max_tokens: max_tokens, cancel: cancel_controller,
+                                 model: model)
+        record(@model_requests, entry)
+        answer = @mutex.synchronize { @model_answers.empty? ? :none : @model_answers.shift }
+        raise Plugin::ModelError, "no model answer queued (bundle.model_answers << \"text\")" if answer == :none
+        raise answer if answer.is_a?(Exception) || (answer.is_a?(Class) && answer <= Exception)
+
+        answer.respond_to?(:call) ? answer.call(entry) : answer
+      end
+
+      # ctx.use_toolkit: +known+ the toolkits chi and the plugins declare.
+      # Staged (toolkit_staged:, true by default), the session is on it at
+      # once, as chi saves it on the session (ToolkitBinding#use).
+      def use_toolkit(name, known)
+        raise ArgumentError, "no toolkit named #{name}" unless known.include?(name)
+
+        record(@toolkit_uses, name)
+        return false unless self[:toolkit_staged]
+
+        set(toolkit: name)
+        true
+      end
+
+      private
+
+      def record(list, item)
+        @mutex.synchronize { list << item }
+      end
+    end
+  end
+end

data/lib/samagotchi/testing/recording_api.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../plugin/api"
+
+module Samagotchi
+  module Testing
+    # One chi.* call a plugin's #register made, as made: its arguments
+    # before Plugin::Api checks and normalizes them (params: as given).
+    Declaration = Data.define(:name, :args, :options)
+
+    # 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
+
+      # @return [Array<Declaration>]
+      def declarations = (@declarations ||= [])
+
+      DECLARATIONS.each do |name|
+        define_method(name) do |*args, **options, &block|
+          declarations << Declaration.new(name: name, args: args.freeze, options: options.freeze)
+          super(*args, **options, &block)
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/testing/rspec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require_relative "../testing"
+
+# The bundle test kit in RSpec (EXPERIMENTAL, docs/plugins.md): example groups
+# tagged :bundle get Samagotchi::Testing::Helpers (load_bundle,
+# shipped_bundle, sandbox), and each of their examples runs in its own
+# sandbox, its bundles shut down after it. A spec under a bundle's own spec/
+# folder (bundles/<name>/spec/) is tagged :bundle by itself; elsewhere tag the
+# group:
+#
+#   RSpec.describe "my bundle", :bundle do
+#     it("says hi") { expect(load_bundle(BUNDLE_DIR).command("/hi")).to eq("hi") }
+#   end
+RSpec.configure do |config|
+  config.define_derived_metadata(file_path: %r{(?:\A|/)bundles/[^/]+/spec/}) { |metadata| metadata[:bundle] = true }
+  config.include Samagotchi::Testing::Helpers, :bundle
+  config.around(:each, :bundle) do |example|
+    enter_sandbox
+    example.run
+  ensure
+    unmatched = leave_sandbox
+    # A request no stub answered fails an example that passed, after its
+    # cleanup (a plugin that rescued the UnstubbedRequest can't hide it); an
+    # example that failed keeps its own failure.
+    unless unmatched.empty? || example.exception
+      raise Samagotchi::Testing::UnstubbedRequest, Samagotchi::Testing::FakeHttp.unmatched_message(unmatched)
+    end
+  end
+end

data/lib/samagotchi/testing/sandbox.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "yaml"
+require_relative "../log"
+require_relative "../paths"
+require_relative "fake_executable"
+
+module Samagotchi
+  module Testing
+    # The environment a bundle test runs in: temp config and state homes
+    # (config.yml, memories, ctx.data_dir, the debug log), HOME and the peer
+    # CLIs' folders, git without the user's config, no Keychain, none of
+    # the user's SAMAGOTCHI_* settings, a bin/ first on PATH for fake
+    # commands. ENV is put back on #leave.
+    #
+    #   Samagotchi::Testing::Sandbox.with { |sandbox| sandbox.config("bundles" => {…}) … }
+    #   sandbox = Samagotchi::Testing::Sandbox.enter   # … sandbox.leave
+    class Sandbox
+      # The environment switches a run of the test keeps (as the suite does).
+      KEPT = %w[SAMAGOTCHI_LOG_STRICT].freeze
+
+      class << self
+        # The sandbox entered last and not left yet (Bundle.load uses it).
+        # @return [Sandbox, nil]
+        attr_accessor :current
+
+        # @return [Sandbox] entered
+        def enter = new.tap(&:enter)
+
+        # Run the block in a new sandbox, left after it.
+        # @yieldparam sandbox [Sandbox]
+        def with
+          sandbox = enter
+          yield sandbox
+        ensure
+          sandbox&.leave
+        end
+
+        # @api private
+      end
+
+      # @return [String] the temp folder holding everything
+      attr_reader :root
+
+      def initialize
+        @root = nil
+        @saved = nil
+        @outer = nil
+      end
+
+      # Point ENV at fresh temp folders (and remember the previous ENV).
+      # @return [self]
+      def enter
+        raise ArgumentError, "the sandbox was entered already" if @root
+
+        @root = File.realpath(Dir.mktmpdir("chi-bundle-test-"))
+        @saved = ENV.to_h
+        @outer = Sandbox.current
+        ENV.each_key.select { |key| key.start_with?("SAMAGOTCHI_") && !KEPT.include?(key) }.each { |key| ENV.delete(key) }
+        %w[config state home work bin].each { |dir| FileUtils.mkdir_p(File.join(@root, dir)) }
+        File.write(File.join(@root, "gitconfig"), "")
+        ENV.update(
+          "HOME" => File.join(@root, "home"),
+          "XDG_CONFIG_HOME" => File.join(@root, "config"),
+          "XDG_STATE_HOME" => File.join(@root, "state"),
+          "CLAUDE_CONFIG_DIR" => File.join(@root, "home", ".claude"),
+          "CODEX_HOME" => File.join(@root, "home", ".codex"),
+          "GIT_CONFIG_GLOBAL" => File.join(@root, "gitconfig"),
+          "GIT_CONFIG_NOSYSTEM" => "1",
+          "SAMAGOTCHI_KEYCHAIN" => "off",
+          "SAMAGOTCHI_ENV" => "test",
+          "SAMAGOTCHI_RECAP_ENABLED" => "false",
+          "SAMAGOTCHI_CACHE_WARMUP" => "off",
+          "PATH" => [bin_dir, ENV.fetch("PATH", nil)].compact.join(File::PATH_SEPARATOR)
+        )
+        # The log resolves its file from the (now temp) state home.
+        Log.reset!
+        Sandbox.current = self
+        self
+      end
+
+      # Put ENV back as it was and remove the temp folders.
+      def leave
+        return unless @root
+
+        ENV.replace(@saved)
+        Log.reset!
+        FileUtils.rm_rf(@root)
+        Sandbox.current = @outer
+        @root = @saved = @outer = nil
+      end
+
+      # Write config.yml (what Config.get reads): a Hash or YAML text.
+      # @return [String] its path
+      def config(data)
+        path = File.join(Paths.config_home, Paths::APP_DIR, "config.yml")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, data.is_a?(String) ? data : YAML.dump(stringify(data)))
+        path
+      end
+
+      # @return [String] $XDG_STATE_HOME/samagotchi (ctx.data_dir's parent)
+      def state_dir = Paths.state_dir
+
+      # A memory scope's folder ("system", or "project" for the checkout
+      # at +cwd+), as chi's memory tools and bundles find it; created.
+      # @return [String]
+      def memory_dir(scope = "system", cwd: Dir.pwd)
+        require_relative "../memory_paths"
+        MemoryPaths.scope_dir!(scope, cwd: cwd).tap { |dir| FileUtils.mkdir_p(dir) }
+      end
+
+      # Write a memory as memory_write does (the file and its index line,
+      # with +description+), for the checkout at +cwd+ (the project scope's;
+      # default the process's own); +source+ marks the line as a bundle's
+      # ("· from <source>"), as an install writes it.
+      # @return [String] the memory's path
+      # @raise [ArgumentError] what memory_write refused
+      def write_memory(name, content, scope: "system", description: nil, source: nil, cwd: nil)
+        require_relative "../tools/memory"
+        require_relative "../memory_bundle/index_updater"
+        in_dir(cwd) do
+          result = Tools::MemoryWrite.call(content, path: name, scope: scope, description: description)
+          raise ArgumentError, result if result.start_with?("Error")
+
+          MemoryBundle::IndexUpdater.update_index(scope, name, content.bytesize, description, source: source) if source
+        end
+        File.join(memory_dir(scope, cwd: cwd || Dir.pwd), "#{name}.md")
+      end
+
+      # @return [String] a temp folder for the session's cwd
+      def work_dir = File.join(@root, "work")
+
+      # @return [String] the folder first on PATH (#fake_executable's)
+      def bin_dir = File.join(@root, "bin")
+
+      # A command +name+ first on PATH that runs +body+ (sh) with its
+      # arguments; again for the same name replaces the body.
+      # @return [String] its path
+      def fake_executable(name, body) = FakeExecutable.write(bin_dir, name, body)
+
+      private
+
+      # Run the block with +dir+ as the process's cwd (the memory tools
+      # read the project from it); nil: as it is.
+      def in_dir(dir, &)
+        return yield if dir.nil? || File.expand_path(dir) == Dir.pwd
+
+        Dir.chdir(dir, &)
+      end
+
+      def stringify(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.to_s, stringify(item)] }
+        when Array then value.map { |item| stringify(item) }
+        else value
+        end
+      end
+    end
+  end
+end