samagotchi 0.79.0 → 0.81.0

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,141 @@
+# 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), and +source+, the asking
+    # bundle's name (what chi counts its side request under).
+    ModelRequest = Data.define(:request, :timeout, :max_tokens, :cancel, :model, :source) do
+      def initialize(source: nil, **) = super
+    end
+
+    # 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, source: nil)
+        entry = ModelRequest.new(request: request, timeout: timeout, max_tokens: max_tokens, cancel: cancel_controller,
+                                 model: model, source: source)
+        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,165 @@
+# 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, state, data and cache
+    # 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 data cache 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"),
+          "XDG_DATA_HOME" => File.join(@root, "data"),
+          "XDG_CACHE_HOME" => File.join(@root, "cache"),
+          "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

data/lib/samagotchi/testing/sessions.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../plugin/context"
+
+module Samagotchi
+  module Testing
+    # One ctx.sessions call: the method's name and its arguments.
+    SessionCall = Data.define(:name, :args, :options)
+
+    # ctx.sessions recorded (Plugin::Sessions' methods, same signatures:
+    # the contract spec checks): each call lands in #calls and returns a
+    # scripted answer (#on), or by default: fork a new id ("fork-1"…), send
+    # and stop the id they got, children [], read raises
+    # Plugin::Sessions::Error (no such session).
+    #
+    #   bundle.sessions.on(:children) { |all:| [{ id: "c1", status: "running" }] }
+    #   bundle.sessions.on(:send) { |id, text, delivery:| raise Samagotchi::Plugin::Sessions::Error, "busy" }
+    class Sessions
+      METHODS = %i[fork send read children stop].freeze
+
+      def initialize
+        @calls = []
+        @scripts = {}
+        @forks = 0
+        @mutex = Mutex.new
+      end
+
+      # @return [Array<SessionCall>]
+      def calls = @mutex.synchronize { @calls.dup }
+
+      # The calls of one method.
+      def calls_to(method) = calls.select { |call| call.name == method }
+
+      # Answer +method+'s calls with the block (it gets the call's
+      # arguments; a raise is the call's).
+      def on(method, &block)
+        raise ArgumentError, "ctx.sessions has no #{method} (#{METHODS.join(", ")})" unless METHODS.include?(method)
+        raise ArgumentError, "on(#{method}) needs a block" unless block
+
+        @mutex.synchronize { @scripts[method] = block }
+        self
+      end
+
+      def fork(messages:, title: nil, prompt: nil)
+        answer(:fork, [], { messages: messages, title: title, prompt: prompt }) do
+          "fork-#{@mutex.synchronize { @forks += 1 }}"
+        end
+      end
+
+      def send(id, text, delivery: nil)
+        answer(:send, [id, text], { delivery: delivery }) { id }
+      end
+
+      def read(id)
+        answer(:read, [id], {}) { raise Plugin::Sessions::Error, "no session #{id}" }
+      end
+
+      def children(all: false)
+        answer(:children, [], { all: all }) { [] }
+      end
+
+      def stop(id)
+        answer(:stop, [id], {}) { id }
+      end
+
+      private
+
+      def answer(method, args, options)
+        script = @mutex.synchronize do
+          @calls << SessionCall.new(name: method, args: args.freeze, options: options.freeze)
+          @scripts[method]
+        end
+        script ? script.call(*args, **options) : yield
+      end
+    end
+  end
+end

data/lib/samagotchi/testing/verdict.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../guardrails/verdict"
+
+module Samagotchi
+  module Testing
+    # One deny! or ask! a voter cast, kept or not.
+    Vote = Data.define(:decision, :reason, :options)
+
+    # A real Guardrails::Verdict that also records every deny! and ask!
+    # (#votes), for tests that count votes or check their keywords
+    # (advice:, rule:), even the ones a stricter earlier vote ignored.
+    class Verdict < Guardrails::Verdict
+      # @return [Array<Vote>]
+      def votes = (@votes ||= [])
+
+      def deny!(reason, **options)
+        votes << Vote.new(decision: :deny, reason: reason, options: options)
+        super
+      end
+
+      def ask!(reason, **options)
+        votes << Vote.new(decision: :ask, reason: reason, options: options)
+        super
+      end
+    end
+  end
+end

data/lib/samagotchi/testing/waiting.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Testing
+    # Waiting with a deadline, for a test that waits on a thread or a
+    # process (Helpers has them).
+    module Waiting
+      # The block's value once truthy, polled every +interval+ s; after
+      # +timeout+ s its last (falsy) value.
+      def wait_until(timeout: 5, interval: 0.01)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        until (value = yield)
+          return yield if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+          sleep(interval)
+        end
+        value
+      end
+
+      # #wait_until, raising "timed out after N s waiting for <what>" when
+      # the time runs out: for a wait no check follows.
+      def wait_until!(what, timeout: 5, interval: 0.01, &)
+        wait_until(timeout: timeout, interval: interval, &) || raise("timed out after #{timeout} s waiting for #{what}")
+      end
+
+      # Whether no process +pid+ is left (a killed grandchild is reaped a
+      # moment later: wait_until { process_gone?(pid) }).
+      def process_gone?(pid)
+        Process.kill(0, pid)
+        false
+      rescue Errno::ESRCH
+        true
+      end
+    end
+  end
+end

data/lib/samagotchi/testing.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# The bundle test kit (docs/plugins.md, "Testing a bundle"): load a bundle's
+# plugin and hook files through chi's own loaders, registries, Context and
+# guardrail Gate, with only the edges recorded (the session's Host, the hook
+# runtime, ctx.sessions, init tasks), in a sandboxed environment.
+#
+# EXPERIMENTAL: it may change in any release before 1.0.0; it is not part of
+# "Stable for bundles".
+#
+#   require "samagotchi/testing"            # plain Ruby
+#   require "samagotchi/testing/rspec"      # RSpec helpers
+#   require "samagotchi/testing/minitest"   # Samagotchi::Testing::Case
+require_relative "version"
+require_relative "testing/sandbox"
+require_relative "testing/recorder"
+require_relative "testing/host"
+require_relative "testing/sessions"
+require_relative "testing/fake_http"
+require_relative "testing/verdict"
+require_relative "testing/recording_api"
+require_relative "testing/waiting"
+require_relative "testing/fake_executable"
+require_relative "testing/bundle"
+require_relative "testing/helpers"
+require_relative "testing/boundary"

data/lib/samagotchi/tools/delegate_relay.rb

@@ -5,6 +5,7 @@ require_relative "../bridge_client"
 require_relative "../relay"
 require_relative "../guardrails/approval"
 require_relative "../log"
+require_relative "../question_answer"
 
 module Samagotchi
   # Loaded on first use (a require cycle otherwise; see delegate.rb).
@@ -84,10 +85,10 @@ module Samagotchi
           return closed(answer[:reason].to_s, what, client: client, relay_id: relay_id, qid: qid)
         end
 
-        dismissed = !(answer.is_a?(Hash) && answer[:selected])
-        by = answer.is_a?(Hash) && answer[:by] == "parent_agent" ? "parent_agent" : "user"
-        desk.record(relay_id, selected_indices: dismissed ? [] : Array(answer[:selected_indices]),
-                              freeform: dismissed ? nil : answer[:freeform], dismissed: dismissed, by: by)
+        dismissed = !answer.is_a?(QuestionAnswer)
+        by = answer.is_a?(QuestionAnswer) && answer.parent_agent? ? "parent_agent" : "user"
+        desk.record(relay_id, selected_indices: dismissed ? [] : answer.selected_indices,
+                              freeform: dismissed ? nil : answer.freeform, dismissed: dismissed, by: by)
         response = post(client, "answered", relay_id, qid)
         Outcome.new(line: line(what, delivered(response, answer, fields, dismissed)), stopped: false)
       end
@@ -118,7 +119,7 @@ module Samagotchi
       # allowed once / allowed for its session / denied ("why")
       def verdict(answer, fields)
         scopes = Array(fields.dig(:approval, :scopes))
-        index = Array(answer[:selected_indices]).first
+        index = answer.selected_indices.first
         if index && index < scopes.size
           return case scopes[index].to_s
                  when "once" then "allowed once"
@@ -129,7 +130,7 @@ module Samagotchi
                  end
         end
 
-        why = answer[:freeform].to_s.strip
+        why = answer.freeform.to_s.strip
         why.empty? ? "denied" : "denied (#{why.inspect})"
       end
 

data/lib/samagotchi/tools/tool_index.rb

@@ -194,6 +194,9 @@ module Samagotchi
         nil
       end
 
+      # @return [Array<Source>] the sources added, in order
+      def sources = @sources.dup
+
       # Every group, now: the index's own (#registry_groups), then the
       # sources'. A source group with a reserved name, or one an earlier
       # group has, is left out of search, lookup and the description (said

data/lib/samagotchi/turn_state.rb

@@ -22,6 +22,8 @@ module Samagotchi
       @running = false
       @controller = nil
       @sink = nil
+      @thread = nil
+      @ended = false
       @steers = []
       @carried_steers = []
     end
@@ -64,12 +66,15 @@ module Samagotchi
       @lock.synchronize { @running }
     end
 
-    # A turn begins: running, with its controller and sink, in one step.
+    # A turn begins, on the calling thread (the turn's own): running, with
+    # its controller and sink, in one step.
     def begin!(controller:, sink:)
       @lock.synchronize do
         @running = true
         @controller = controller
         @sink = sink
+        @thread = Thread.current
+        @ended = false
         @steers.concat(@carried_steers)
         @carried_steers = []
       end
@@ -82,15 +87,37 @@ module Samagotchi
         @running = false
         @controller = nil
         @sink = nil
+        @thread = nil
+        @ended = false
         @steers.tap { @steers = [] }
       end
     end
 
+    # The turn's end is decided (its end event is out): what runs after,
+    # its after_turn / session_end hooks, is post-turn work, up to #finish!.
+    def ended!
+      @lock.synchronize { @ended = true }
+    end
+
     # @return [CancellationController, nil] the running turn's controller
     def controller
       @lock.synchronize { @controller }
     end
 
+    # The controller for work done for the turn itself (a plugin's HTTP
+    # call): the running turn's, on the turn's thread or +handler+ (inside a
+    # plugin's event handler, whatever thread fires it), until the turn has
+    # ended; nil for any other thread (an anytime command, a service) and
+    # outside a turn.
+    # @return [CancellationController, nil]
+    def own_controller(handler: false)
+      @lock.synchronize do
+        return nil unless @running && !@ended
+
+        handler || @thread.equal?(Thread.current) ? @controller : nil
+      end
+    end
+
     # Cancel the running turn, if any (outside the lock).
     # @return [Boolean] whether a cancellation was triggered
     def cancel!(reason)