samagotchi 0.79.0 → 0.81.0

data/lib/samagotchi/testing/bundle.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require_relative "../plugin/loader"
+require_relative "../plugin/tool_spec"
+require_relative "../hooks"
+require_relative "../commands/registry"
+require_relative "../session_commands"
+require_relative "../tools/builtins"
+require_relative "../tools/tool_index"
+require_relative "../peer_sources"
+require_relative "../toolkit"
+require_relative "../guardrails/gate"
+require_relative "../memory_bundle/manifest"
+require_relative "sandbox"
+require_relative "recorder"
+require_relative "host"
+require_relative "sessions"
+require_relative "fake_http"
+require_relative "verdict"
+require_relative "recording_api"
+
+module Samagotchi
+  module Testing
+    # A hook (a plugin's chi.on block or a hook file) raised while the kit
+    # fired it: chi would log it and go on, a test fails with it.
+    class HookFailed < StandardError
+      # @return [Hooks::Failure]
+      attr_reader :failure
+
+      def initialize(failure)
+        @failure = failure
+        error = failure.error
+        super("#{failure.hook} raised on #{failure.event}: #{error.class}: #{error.message}")
+        set_backtrace(error.backtrace) if error.backtrace
+      end
+
+      def cause = @failure.error
+    end
+
+    # A chi.init the plugin registered: its arguments and block.
+    Init = Data.define(:label, :plugin_label, :provides_tools, :quiet, :timeout, :failed, :block)
+    # A chi.replace_tools set, staged as chi stages it for the turn thread.
+    StagedTools = Data.define(:specs, :context)
+
+    # One bundle loaded for a test through chi's own seams: its plugin
+    # through Plugin::Loader.register_file (Plugin::Api, a real
+    # Plugin::Context) and its hook files through
+    # Hooks::BundleLoader.load_hook_file, into real registries (commands
+    # and tools with chi's built-ins in them, so a name clash fails as in
+    # chi). Only the edges are recorded: the Host and hook Runtime
+    # (Recorder), ctx.sessions (Testing::Sessions), chi.init tasks and
+    # staged tool sets. No sha256 or requires_chi check: it loads the
+    # source as it is.
+    #
+    #   bundle = Samagotchi::Testing::Bundle.load("path/to/bundle", settings: { "every" => 3 })
+    #   bundle.fire(:after_turn, status: "completed")
+    #   bundle.command("/checkin stop")
+    #   bundle.tool_call({ name: "execute", content: "ls" })   # → Verdict
+    #   bundle.notices, bundle.cards, bundle.steers …
+    #   bundle.shutdown
+    #
+    # A hook that raises while #fire, #tool_call, #command or #tool runs
+    # raises HookFailed after the call (chi would log it and go on);
+    # #lenient collects them in #errors instead.
+    class Bundle
+      SHIPPED_DIR = File.expand_path("../bundles", __dir__)
+
+      class << self
+        # @param dir [String] the bundle's folder (its manifest.yml)
+        # @param settings [Hash] config.yml `bundles: <name>:`
+        # @param host [Hash] session values (Recorder::DEFAULTS' keys)
+        # @param sandbox [Sandbox, nil] default Sandbox.current, else one of
+        #   its own, left at #shutdown
+        # @return [Bundle]
+        def load(dir, settings: {}, host: {}, sandbox: nil)
+          new(dir, settings: settings, host: host, sandbox: sandbox).tap(&:load!)
+        end
+
+        # A bundle chi ships (lib/samagotchi/bundles/<name>), as #load.
+        def shipped(name, **) = load(File.join(SHIPPED_DIR, name.to_s), **)
+      end
+
+      # @return [String] the bundle's name (manifest.yml)
+      attr_reader :name
+      # @return [MemoryBundle::Manifest]
+      attr_reader :manifest
+      # @return [Plugin::Registries]
+      attr_reader :registries
+      # @return [Recorder]
+      attr_reader :recorder
+      # @return [Sessions] ctx.sessions
+      attr_reader :sessions
+      # @return [FakeHttp] what answers ctx.http (stub, requests, unmatched)
+      attr_reader :http
+      # @return [Sandbox]
+      attr_reader :sandbox
+      # @return [Plugin::Api, nil] the plugin's committed Api (nil without one)
+      attr_reader :api
+      # @return [Object, nil] the plugin's instance (the object #register ran
+      #   on), for specs of its own methods
+      attr_reader :plugin
+      # @return [Module, nil] the module the plugin was evaluated in
+      #   (bundle.namespace::ThinkingWatch)
+      attr_reader :namespace
+      # @return [Module] the module the hook files were evaluated in
+      attr_reader :hooks_namespace
+      # @return [Array<Init>]
+      attr_reader :inits
+      # @return [Array<StagedTools>]
+      attr_reader :staged_tools
+      # @return [Array<Hooks::Failure>] what raised under #lenient
+      attr_reader :errors
+      # @return [Integer] how often chi was told the tools changed
+      attr_reader :tools_changes
+
+      def initialize(dir, settings: {}, host: {}, sandbox: nil)
+        @dir = File.expand_path(dir)
+        @manifest = MemoryBundle::Manifest.read(dir: @dir)
+        @name = @manifest.name
+        @settings = stringify(settings || {})
+        @own_sandbox = sandbox.nil? && Sandbox.current.nil?
+        @sandbox = sandbox || Sandbox.current || Sandbox.enter
+        @recorder = Recorder.new(cwd: @sandbox.work_dir, **host)
+        @sessions = Sessions.new
+        @http = FakeHttp.new
+        @inits = []
+        @staged_tools = []
+        @errors = []
+        @lenient = false
+        @tools_changes = 0
+        @contexts = {}
+        @registries = build_registries
+      end
+
+      # @api private (Bundle.load)
+      def load!
+        if (plugin = @manifest.plugin)
+          @namespace = Plugin::Loader.fresh_namespace(@name)
+          @api = Plugin::Loader.register_file(@name, File.join(@dir, plugin[:file]), @registries, settings: @settings,
+                                                                                                  namespace: @namespace,
+                                                                                                  api_class: RecordingApi) do |built|
+            @plugin = built
+          end
+        end
+        @hooks_namespace = Hooks::BundleLoader.namespace_for(@name).const_set(:"KitHooks#{object_id}", Module.new)
+        @manifest.hooks.each do |basename, hook|
+          next if hook.event.empty?
+
+          Hooks::BundleLoader.load_hook_file(@name, basename, File.join(@dir, "hooks", basename), hook, hooks,
+                                             settings: @settings, namespace: @hooks_namespace)
+        end
+        self
+      rescue Exception # rubocop:disable Lint/RescueException -- leave the sandbox it entered, whatever failed
+        shutdown
+        raise
+      end
+
+      # ── Firing ──────────────────────────────────────────────────────────
+
+      # Fire hook +event+ through the registry, as chi's fire sites do: the
+      # event is {type: event, **fields} (a fire site's own keys, such as
+      # after_turn's present:/refs:, come from +fields+), with the runtime
+      # helpers added. Returns the event after the hooks.
+      # @return [Hash]
+      def fire(event, **fields)
+        payload = { type: event.to_sym, **fields }
+        failing { hooks.fire(event.to_sym, payload) }
+        payload
+      end
+
+      # One tool call through a real Guardrails::Gate: the before_tool_call
+      # hooks vote on a Testing::Verdict (pass +verdict+ to start from one,
+      # another voter's deny in it), with the context and targets the Gate
+      # computes for the call (cwd: the session's by default).
+      # @param call [Hash] the parsed call ({name:, content:/path:/args:})
+      # @param context [Guardrails::Context, nil]
+      # @return [Verdict]
+      def tool_call(call, params: nil, cwd: nil, context: nil, verdict: nil, iteration: 1)
+        context ||= Guardrails::Context.new(cwd: cwd || @recorder[:cwd], session_id: @recorder[:session_id],
+                                            interface: @recorder[:frontend])
+        gate = Guardrails::Gate.new(-> { hooks }, context_lookup: -> { context }, tools_lookup: -> { tools },
+                                                  checks_lookup: -> { [] })
+        verdict ||= Verdict.new(call: call)
+        params ||= "#{call[:name]} #{call[:content] || call[:path]}".strip
+        failing { gate.evaluate(call, iteration: iteration, params: params, verdict: verdict) }
+      end
+
+      # 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)
+        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) }
+      end
+
+      # Call a registered tool as chi's dispatch does: its handler gets the
+      # call ({name:, args:}), types the args by the tool's schema
+      # (ToolSpec.args_of) and returns the text the model reads.
+      # @return [String]
+      def tool(name, args = {})
+        entry = tools[name.to_s]
+        raise ArgumentError, "no tool #{name}" unless entry
+
+        failing { entry.handler.call({ name: name.to_s, args: stringify(args) }, nil) }
+      end
+
+      # 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 } }
+
+      # Apply the staged chi.replace_tools sets, as chi does before a turn
+      # (ToolSpec.apply). @return [Boolean] whether the tools changed
+      def apply_staged_tools!
+        sets = @staged_tools.dup
+        @staged_tools.clear
+        sets.map { |set| Plugin::ToolSpec.apply(tools, @name, set.specs, set.context)[:changed] }.any?
+      end
+
+      # Collect what raises in the block's fires in #errors instead of
+      # raising HookFailed.
+      def lenient
+        was = @lenient
+        @lenient = true
+        yield
+      ensure
+        @lenient = was
+      end
+
+      # ── What it registered ─────────────────────────────────────────────
+
+      # @return [Commands::Registry] chi's built-ins and the bundle's
+      def commands = @registries.commands
+      # @return [Tools::Registry] chi's built-ins and the bundle's
+      def tools = @registries.tools
+      # @return [Hooks::Registry]
+      def hooks = @registries.hooks
+      # @return [Array<Toolkit::Kit>]
+      def toolkits = @registries.toolkits
+      # @return [Tools::ToolIndex]
+      def tool_index = @registries.tool_index
+      # @return [PeerSources]
+      def peer_sources = @registries.peer_sources
+
+      # The bundle's own command entries.
+      def bundle_commands = commands.entries.select { |entry| entry.source == @name }
+      # The bundle's own tool entries.
+      def bundle_tools = tools.by_source(@name)
+      # Its hooks for +event+ as [bundle, hook_name, priority], fire order.
+      def hook_names(event) = hooks.bundle_hook_names(event.to_sym)
+      # The annotations its commands carry.
+      def annotations = bundle_commands.flat_map(&:annotations)
+
+      # The chi.* calls #register made, in order, as made (RecordingApi).
+      # @return [Array<Declaration>]
+      def declarations = @api ? @api.declarations : []
+
+      # The plugin's ctx (a real Plugin::Context; nil without a plugin).
+      def ctx = @contexts.values.first
+
+      # ── Recorders ──────────────────────────────────────────────────────
+
+      def notices = @recorder.notices
+      def cards = @recorder.cards
+      def steers = @recorder.steers
+      # Every stop_turn and stop_generation, in order (Stop#kind).
+      def stops = @recorder.stops
+      def turn_stops = @recorder.turn_stops
+      def generation_stops = @recorder.generation_stops
+      def questions = @recorder.questions
+      def model_requests = @recorder.model_requests
+      def toolkit_uses = @recorder.toolkit_uses
+      # Queue ask_model answers: a String, an exception, or a callable.
+      def model_answers = @recorder.model_answers
+
+      # Queue ask_user answers ({selected:, freeform:, selected_indices:},
+      # or a callable given the Question).
+      def answer(*answers)
+        @recorder.answers.concat(answers)
+        self
+      end
+
+      # Change the session's values (cwd:, messages:, running: …).
+      def set(**values)
+        @recorder.set(**values)
+        self
+      end
+
+      # Stop the plugin's services; leave the sandbox it entered.
+      def shutdown
+        @registries&.services&.stop_all
+        return unless @own_sandbox
+
+        @own_sandbox = false
+        @sandbox.leave
+      end
+
+      private
+
+      def build_registries
+        builtin_tools = Tools::Builtins.registry
+        toolkits = []
+        host = Host.build(@recorder, toolkits: -> { Toolkit::BUILTIN_KITS.keys + toolkits.map(&:name) },
+                                     tool_names: -> { @registries.tools.names })
+        Plugin::Registries.new(
+          commands: SessionCommands.register_builtins(Commands::Registry.new),
+          tools: builtin_tools,
+          hooks: Hooks::Registry.new.tap { |registry| registry.runtime = Runtime.build(@recorder) },
+          context_for: lambda { |bundle, settings, label|
+            @contexts[label] = Plugin::Context.new(bundle: bundle, label: label, settings: settings, host: host,
+                                                   env: ENV, sessions: @sessions, http_transport: @http)
+          },
+          tools_changed: -> { @tools_changes += 1 },
+          services: Plugin::Services.new,
+          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,
+                               timeout: timeout, failed: failed, block: block)
+          },
+          toolkits: toolkits,
+          tool_index: Tools::ToolIndex.new,
+          peer_sources: PeerSources.new
+        )
+      end
+
+      # Run the block catching the hooks that raise in it.
+      def failing(&)
+        failures = []
+        result = Hooks.capture_failures(failures, &)
+        if @lenient
+          @errors.concat(failures)
+        elsif (first = failures.first)
+          raise HookFailed, first
+        end
+        result
+      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

data/lib/samagotchi/testing/fake_executable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Samagotchi
+  module Testing
+    # Fake commands for a test's PATH (Sandbox#fake_executable), cheap to
+    # exec: macOS checks a new executable file on its first exec (about
+    # 0.5–1 s, once per file). A fake is a symlink to one launcher, made
+    # once per process, that runs the fake's body (<name>.sh beside the
+    # link) with /bin/sh: writing a new body costs nothing.
+    module FakeExecutable
+      LAUNCHER = "#!/bin/sh\nexec /bin/sh \"$0.sh\" \"$@\"\n"
+
+      module_function
+
+      # Writes +dir+/+name+, which runs +body+ (sh) with its arguments;
+      # again for the same name replaces the body.
+      # @return [String] the command's path
+      def write(dir, name, body)
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, name)
+        File.write("#{path}.sh", body.end_with?("\n") ? body : "#{body}\n")
+        FileUtils.ln_sf(launcher, path)
+        path
+      end
+
+      def launcher
+        @launcher ||= begin
+          dir = Dir.mktmpdir("chi-fake-exec")
+          owner = Process.pid
+          at_exit { FileUtils.rm_rf(dir) if Process.pid == owner }
+          File.join(dir, "launcher").tap do |path|
+            File.write(path, LAUNCHER)
+            File.chmod(0o755, path)
+          end
+        end
+      end
+    end
+  end
+end

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, source: nil|
+            recorder.ask_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
+                                        model: model, source: source)
+          },
+          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