samagotchi 0.154.1 → 0.155.0

data/lib/samagotchi/turn_stages/toolkit_suggestion.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../log"
+require_relative "../side_judgments"
+require_relative "../system_one/client"
+require_relative "../toolkit"
+require_relative "../toolkit_suggest"
+require_relative "../tools/tool_index"
+
+module Samagotchi
+  # The steps of a turn that keep state across its preparation, each a
+  # collaborator the Engine builds from constructor arguments and
+  # Engine#prepare_turn calls by name (docs/internals/engine.md, "Turn
+  # stages").
+  module TurnStages
+    # System 1's toolkit suggestion (ToolkitSuggest): the ask a turn starts
+    # before the probes, settles before apply_toolkit! (on mode) or abandons
+    # at a Stop or a failure, and the idle worker's warm-up. Its state is
+    # the running turn's Pending (turn thread only) and the warm-up thread.
+    class ToolkitSuggestion
+      # @param side_judgments [SideJudgments] the Engine's side asks (:toolkit kind)
+      # @param host_registry [HostRegistry] System 1's client resolves its host here
+      # @param toolkit_binding [ToolkitBinding] the kits, #suggest and #fell_back
+      # @param tools [Tools::Registry] the registered tools, for the snapshot
+      # @param state_dir [#call] the sessions dir (the suggestion log's place)
+      # @param recording [#call] (client, judgment, session, mode:) → the client saving its runs
+      # @param runs [#call] the Engine's SystemOne::Runs
+      def initialize(side_judgments:, host_registry:, toolkit_binding:, tools:, state_dir:, recording:, runs:)
+        @side_judgments = side_judgments
+        @host_registry = host_registry
+        @toolkit_binding = toolkit_binding
+        @tools = tools
+        @state_dir = state_dir
+        @recording = recording
+        @runs = runs
+        @pending = nil
+        @pending_turn = nil
+        @warmup_thread = nil
+      end
+
+      # For specs: the running warm-up (#warm!), nil when none started or it
+      # was stopped.
+      attr_reader :warmup_thread
+
+      # For specs: the ask's thread (SideJudgments' :toolkit kind), nil before any.
+      def ask_thread = @side_judgments.thread(:toolkit)
+
+      # Start the toolkit classifier after :turn_started, for audit and on
+      # mode alike (one eligibility, one snapshot, one thread). All session
+      # and tool-registry reads happen here; the thread receives only this
+      # snapshot. Audit never blocks: the thread logs its line. On mode
+      # keeps the ask's Pending for +turn+, which #settle joins before
+      # apply_toolkit!, with the turn's controller as the request's cancel
+      # controller.
+      # @return [ToolkitSuggest::Pending, nil] nil unless the turn joins an ask
+      def start(turn)
+        @pending = nil
+        @pending_turn = turn
+        @pending = ask(turn)
+      end
+
+      # On mode, before apply_toolkit!: wait for +turn+'s ask (#start) up to
+      # System 1's timeout from its start, or until a Stop, and put the
+      # session on a candidate picked with confidence ≥ threshold
+      # (ToolkitBinding#suggest: origin suggested, saved, the notice). Any
+      # other outcome (the default, below threshold, undecided, no judgment,
+      # a timeout, a Stop) leaves the session on its default. Nothing here
+      # sends a request; prepare_turn's cancel check ends a stopped turn. A
+      # Stop wins over an answer already in (Pending#wait checks it first).
+      def settle(turn)
+        pending = pending_for(turn)
+        return if pending.nil?
+
+        outcome, judged = pending.wait(turn.controller)
+        if outcome == :timeout
+          # The session starts on its default without a word otherwise: a
+          # slow System 1 host (a local one) is the usual cause.
+          timeout_ms = SystemOne::Client.configured_timeout_ms
+          Log.warn(:toolkit, "toolkit_suggest_timeout", session_id: turn.session.id, timeout_ms: timeout_ms,
+                                                        reason: "System 1 gave no answer within system_one.timeout_ms")
+          @toolkit_binding.fell_back(turn.session, "System 1 took over #{timeout_ms} ms")
+          return
+        end
+        unless outcome == :answered
+          Log.info(:toolkit, "toolkit_suggest_#{outcome}", session_id: turn.session.id)
+          return
+        end
+        return if judged.nil?
+
+        pending.record(outcome_of(turn.session, judged))
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        pending&.record("failed")
+      end
+
+      # +turn+ ended before it settled its ask (a Stop at the probes, a
+      # failure, an Interrupt): the ask's line says +reason+
+      # (Pending#abandon; nothing once it was settled, so prepare_turn's
+      # ensure calls it too). Nothing when +turn+ started no ask.
+      def abandon(turn, reason)
+        pending_for(turn)&.abandon(reason)
+      end
+
+      # +turn+'s suggestion is done (prepare_turn's ensure, after #abandon):
+      # its Pending and the turn are let go, so nothing of it outlives its
+      # preparation. Nothing for another turn's.
+      def finish(turn)
+        return unless @pending_turn.equal?(turn)
+
+        @pending = nil
+        @pending_turn = nil
+      end
+
+      # On mode, as an idle worker starts (Worker#start_background): one ask
+      # with the real question and a stand-in prompt, on its own thread,
+      # never logged and never waited for, so System 1's server has the
+      # question's prefix cached for the first prompt. Only for a session a
+      # first prompt could be asked for: origin default, no model reply, not
+      # a delegate child or a review session, at least two candidates; and
+      # not when the worker starts on a first prompt (that ask comes at once).
+      def warm!(session)
+        return unless Config.get("toolkit.suggest.mode").to_s == "on"
+
+        return if session.nil? || session.toolkit_origin != "default" || session.delegate? || session.review?
+        return if ToolkitSuggest.model_reply?(session.messages) || !session.last_prompt.to_s.strip.empty?
+
+        default = Toolkit.of(session.toolkit)
+        kits = @toolkit_binding.kits
+        return if ToolkitSuggest.candidates(kits, default_name: default.name).size < 2
+
+        client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
+        return unless client
+
+        project = File.basename(session.project_root.to_s)
+        @warmup_thread = Thread.new do
+          ToolkitSuggest.warm(client: client, default: default, kits: kits, project: project)
+        end
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        nil
+      end
+
+      # A still-running warm-up, stopped: a real ask (or the worker leaving)
+      # doesn't wait behind it.
+      def stop_warmup
+        @warmup_thread&.kill
+        @warmup_thread = nil
+      end
+
+      private
+
+      # The Pending #start kept for this very turn: another turn's (one that
+      # never reached #start) is never touched.
+      def pending_for(turn) = (@pending if @pending_turn.equal?(turn))
+
+      def ask(turn)
+        mode = Config.get("toolkit.suggest.mode").to_s
+        return if mode == "off"
+
+        joined = mode == "on"
+        session = turn.session
+        default = Toolkit.of(session.toolkit)
+        log = suggestion_log
+        # The predicate checks the session first; the kits (memory kits are
+        # read from disk) and the log (read whole) only when it gets there.
+        kits = nil
+        candidates = nil
+        return unless ToolkitSuggest.eligible?(
+          session: session, prompt: turn.prompt, author: turn.origin.author,
+          candidate_count: lambda {
+            kits = @toolkit_binding.kits
+            candidates = ToolkitSuggest.candidates(kits, default_name: default.name)
+            candidates.size
+          },
+          last_suggestion: -> { ToolkitSuggest.last_suggestion(log, session.id) },
+          defer_turns: Config.get("toolkit.suggest.defer_turns"),
+          defer_tokens: Config.get("toolkit.suggest.defer_tokens")
+        )
+
+        # One ask at a time: an eligible turn while the last one still runs
+        # goes unasked, and says so.
+        if @side_judgments.in_flight?(:toolkit)
+          Log.info(:toolkit, "toolkit_suggest_in_flight_skipped", session_id: session.id)
+          return
+        end
+
+        client = @recording.call(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit),
+                                 ToolkitSuggest::JUDGMENT, session, mode: Config.get("toolkit.suggest.mode").to_s)
+        return unless client
+
+        # The warm-up's only value is the cache: the real ask never queues
+        # behind it.
+        stop_warmup
+
+        # Rules, not tool lists: this runs before await_init_tasks and
+        # apply_staged_tools!, so a first turn's plugin/MCP tools aren't
+        # registered yet; the report expands the rules (ToolkitSuggest.rules).
+        snapshots = candidates.map do |kit|
+          ToolkitSuggest::Candidate.new(name: kit.name.dup.freeze, description: kit.description.dup.freeze,
+                                        rules: ToolkitSuggest.rules(Toolkit.resolve_kit(kit.name, kits)))
+        end.freeze
+        default_snapshot = ToolkitSuggest::Candidate.new(name: default.name.dup.freeze, description: nil,
+                                                         rules: ToolkitSuggest.rules(default.resolve(kits)))
+        registered = Tools::ToolSurface.for(@tools, toolkit: nil).declared
+                                       .reject { |entry| entry.source == Tools::ToolIndex::SOURCE }
+        core_tools, plugin_tools = registered.partition(&:core?).map { |entries| entries.map { |entry| entry.name.dup.freeze }.freeze }
+        state = ToolkitSuggest.question(
+          default: default, kits: kits, project: File.basename(session.project_root.to_s),
+          prompt: turn.prompt
+        ).last
+        snapshot = ToolkitSuggest::Snapshot.new(
+          session_id: session.id.dup.freeze, turn_number: ToolkitSuggest.turn_number(session.messages),
+          default: default_snapshot, candidates: snapshots, core_tools: core_tools, plugin_tools: plugin_tools,
+          state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
+        )
+        threshold = Config.get("toolkit.suggest.threshold")
+        runs = session.scratch ? nil : @runs.call
+        pending = ToolkitSuggest::Pending.new(log: log, joined: joined,
+                                              acted: runs && ->(judged, did) { runs.acted(judged.fields[:run_id], did) },
+                                              timeout_seconds: SystemOne::Client.configured_timeout_ms / 1000.0)
+        # On mode: cut by a Stop while the turn waits (Pending#wait), not
+        # by one after it went on; audit's ask is never cut.
+        controller = joined ? pending.cancel_controller : nil
+        @side_judgments.start(:toolkit, warn: ToolkitSuggest.method(:warn), finish: pending.method(:finish)) do
+          ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
+                               cancel_controller: controller)
+        end
+        joined ? pending : nil
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        nil
+      end
+
+      # What the turn does with an answered ask, as the log line's did:
+      # suggested (switched), chosen (the toolkit isn't the default any
+      # more), unavailable (the kit is gone), defer or default.
+      def outcome_of(session, judged)
+        case judged.would
+        when "suggested"
+          return "chosen" unless session.toolkit_origin == "default"
+          return "unavailable" unless @toolkit_binding.kits.key?(judged.suggestion.kit)
+
+          switched = @toolkit_binding.suggest(session, judged.suggestion.kit, confidence: judged.suggestion.confidence,
+                                                                              deferred: ToolkitSuggest.model_reply?(session.messages))
+          switched ? "suggested" : "chosen"
+        when "defer" then "defer"
+        when "no_judgment"
+          # System 1 failed (its own warn) or answered nothing usable.
+          @toolkit_binding.fell_back(session, "System 1 gave no answer")
+          "default"
+        else "default"
+        end
+      end
+
+      def suggestion_log
+        SideJudgments.log(ToolkitSuggest.log_path(@state_dir.call), tag: :toolkit, event: "toolkit_suggest_log_failed")
+      end
+    end
+  end
+end

data/lib/samagotchi/turn_stages/verify_anchors.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../answer_tail"
+require_relative "../log"
+require_relative "../output_formatter"
+require_relative "../redact"
+require_relative "../revise_anchor"
+require_relative "../session"
+require_relative "../steer"
+require_relative "../verdict"
+require_relative "../verify_anchor"
+
+module Samagotchi
+  module TurnStages
+    # Verify and Revise anchors over a turn: a Verify turn's quote checked
+    # against its source session as the turn begins; at its end (inside
+    # Engine#end_turn's event step) the opening's stamp, a Revise turn's
+    # draft checked and a Verify turn's verdict recorded. No state of its
+    # own: it reads the turn, and the sessions it loads from the state dir.
+    class VerifyAnchors
+      # @param state_dir [#call] the sessions dir (a fresh Verify child's parent is loaded from it)
+      def initialize(state_dir:)
+        @state_dir = state_dir
+      end
+
+      # A Verify turn's claim (Engine#begin_turn), when its quote is in the
+      # source session's answer for that turn; nil (logged) otherwise.
+      # @param anchor [VerifyAnchor, nil]
+      # @return [VerifyAnchor, nil]
+      def verified(session, anchor)
+        return unless anchor
+
+        source = source_session(session, anchor)
+        return unless source
+
+        turn = AnswerTail.turn_slice(Array(source.messages), anchor.turn_id)
+        return reject_verify(anchor, :turn_missing) unless turn
+
+        reply = turn.reverse.find { |message| AnswerTail.answer?(message) }
+        return reject_verify(anchor, :reply_missing) unless reply
+
+        quote_text = comparison_text(anchor.quote)
+        quoted = !quote_text.empty? && quote_in?(quote_text, (reply[:content] || reply["content"]).to_s, source)
+        return reject_verify(anchor, :quote_missing) unless quoted
+
+        anchor
+      end
+
+      # The turn's anchors, stamped on its opening message (the prompt, or a
+      # wake turn's note) in the messages it keeps: display metadata, never
+      # in the prompt (LLM::ChatLoop#plain keeps them, no wire sends them).
+      # A Verify turn's claim however it ended; a Revise turn's draft only
+      # once it completed with an answer (#revision_target). Returns the
+      # stamped ReviseAnchor (the end event's revises), or nil.
+      def stamp_opening(messages, turn, outcome)
+        return unless messages.is_a?(Array)
+
+        revises = revision_target(messages, turn, outcome)
+        fields = { verify: turn.verify&.to_h, revises: revises&.to_h }.compact
+        return if fields.empty?
+
+        opening = messages.reverse.find do |message|
+          Steer.turn_prompt?(message) && (message[:turn_id] || message["turn_id"]).to_s == turn.id
+        end
+        return unless opening
+
+        opening.merge!(fields)
+        revises
+      end
+
+      # A completed Verify turn's verdict (Verdict.parse of its answer), added
+      # to the session's verdicts; the record (the end event's verdict), or nil.
+      def record_verdict(turn, outcome)
+        return unless outcome == "completed" && turn.verify
+
+        answer = AnswerTail.find(turn.session.messages, turn_id: turn.id)
+        parsed = Verdict.parse(answer && (answer[:content] || answer["content"]))
+        return unless parsed
+
+        record = { anchor: turn.verify.to_h, verdict: parsed.verdict, reason: parsed.reason,
+                   by: turn.origin.author, check_turn_id: turn.id, at: Time.now.iso8601(3) }
+        turn.session.verdicts = turn.session.verdicts + [record]
+        record
+      end
+
+      private
+
+      # The turn a Revise turn revised (D6: "this turn revised that one"):
+      # only a completed turn with an answer (AnswerTail) has revised
+      # anything. A draft no prompt in the messages carries is no target (a
+      # stale page, a rolled-back turn); one a stamped turn already revised
+      # is re-targeted to its stack's top, the newest version, which the
+      # person meant ("this draft").
+      def revision_target(messages, turn, outcome)
+        return unless turn.revises && outcome == "completed"
+
+        slice = AnswerTail.turn_slice(messages, turn.id)
+        return unless slice&.any? { |message| AnswerTail.answer?(message) }
+
+        target = turn.revises.turn_id
+        seen = [turn.id]
+        until seen.include?(target)
+          return reject_revise(turn.revises, :turn_missing) unless AnswerTail.turn_slice(messages, target)
+
+          seen << target
+          newer = messages.reverse.find do |message|
+            Steer.turn_prompt?(message) && ReviseAnchor.from(message[:revises] || message["revises"])&.turn_id == target
+          end
+          return ReviseAnchor.new(turn_id: target) unless newer
+
+          target = (newer[:turn_id] || newer["turn_id"]).to_s
+        end
+        reject_revise(turn.revises, :cycle)
+      end
+
+      def reject_revise(anchor, reason)
+        Log.warn(:turn, "revise_anchor_rejected", turn_id: anchor.turn_id, reason:)
+        nil
+      end
+
+      # Whether +quote_text+ is in +answer+ as the model wrote it, or as the
+      # pages show it: a page quotes its own text, which reads the session's
+      # folder relative, the home folder as ~ and a secret shape as
+      # [redacted] (a participant's page gets it so, Redact;
+      # the owner's page rewrites its quote the same way, claim_link.js
+      # normalizeClaim, so claim links match both pages). +source+ is the
+      # session whose folder that is.
+      def quote_in?(quote_text, answer, source)
+        return true if comparison_text(answer).include?(quote_text)
+
+        viewer = Redact::Viewer.new(cwd: source.working_directory)
+        comparison_text(Redact.text(answer, viewer)).include?(quote_text)
+      end
+
+      def source_session(session, anchor)
+        return session unless session.verify_fresh
+
+        fresh = session.verify_fresh
+        return reject_verify(anchor, :fresh_anchor_mismatch) unless fresh.anchor == anchor
+        return reject_verify(anchor, :fresh_parent_missing) unless session.parent_id
+
+        Session.load(session.parent_id, state_dir: @state_dir.call)
+      rescue ArgumentError, SystemCallError, IOError => e
+        Log.warn(:turn, "verify_anchor_rejected", turn_id: anchor.turn_id, reason: :source_session_unavailable,
+                                                   error: e.class.name)
+        nil
+      end
+
+      def comparison_text(text)
+        OutputFormatter.strip_markup(text)
+                       .gsub(/!\[([^\]]*)\]\([^)]+\)/, '\1')
+                       .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
+                       .gsub(/^[ \t]*(?:\#{1,6}[ \t]+|>[ \t]?|[-+*][ \t]+|\d+[.)][ \t]+)/, "")
+                       .gsub(/(\*\*|__|~~|`+)(.+?)\1/m, '\2')
+                       .gsub(/(?<!\w)\*(\S(?:.*?\S)?)\*(?!\w)/m, '\1')
+                       .gsub(/(?<!\w)_(\S(?:.*?\S)?)_(?!\w)/m, '\1')
+                       .tr("|", " ") # a table row's cells; the page copies them without the pipes
+                       .gsub(/\s+/, " ")
+                       .strip
+      end
+
+      def reject_verify(anchor, reason)
+        Log.warn(:turn, "verify_anchor_rejected", turn_id: anchor.turn_id, reason:)
+        nil
+      end
+    end
+  end
+end

data/lib/samagotchi/turn_stages/warmup.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../context_note"
+require_relative "../log"
+require_relative "../model_profile"
+require_relative "../prompt_warmup"
+
+module Samagotchi
+  module TurnStages
+    # The turn-end warm-up (PromptWarmup, cache.warmup): after a completed
+    # turn, the next turn's prompt prefilled up to its user message while
+    # the user reads. Called after Engine#complete_turn, so the context
+    # judge's asks started in the turn run first: on a shared local host the
+    # warm-up queues behind them. No state of its own: the PromptWarmup
+    # keeps its pin and thread.
+    class Warmup
+      # @param prompt_warmup [PromptWarmup] the Engine's warm-up (the kernel asks it for a slot pin)
+      # @param kernel [KernelLoop] the warm-up prompt, the last slot, warmed_up!
+      # @param turn_state [TurnState] whether steers are carried to the next turn
+      # @param model_settings [SessionModelSettings] the next turn's LLM context strategy
+      # @param model [#call] the effective model now (Engine#effective_model)
+      # @param system_prompt [#call] (model) the system prompt (Engine#system_prompt)
+      # @param reminders_due [#call] whether a reminder is due (Engine#reminders_due?)
+      # @param next_turn_waiting [#call] whether the next turn starts at once or none follows
+      #   (Engine#next_turn_waiting, called)
+      def initialize(prompt_warmup:, kernel:, turn_state:, model_settings:, model:, system_prompt:, reminders_due:,
+                     next_turn_waiting:)
+        @prompt_warmup = prompt_warmup
+        @kernel = kernel
+        @turn_state = turn_state
+        @model_settings = model_settings
+        @model = model
+        @system_prompt = system_prompt
+        @reminders_due = reminders_due
+        @next_turn_waiting = next_turn_waiting
+      end
+
+      # After a completed turn, prefill the next turn's prompt up to its user
+      # message while the user reads (PromptWarmup, cache.warmup). Only on a
+      # local llama.cpp host on the native loop, and not when the next turn's
+      # start differs anyway or starts at once: a reminder due, a continue
+      # offer (the turn ran out of steps), a carried steer or queued input.
+      # Never fails the turn.
+      def after(turn, result)
+        return if result.canceled? || result.resumable?
+
+        model = @model.call
+        client = model.client
+        return unless target?(model, client)
+        return if @reminders_due.call || @turn_state.carried_steers? || @next_turn_waiting.call
+
+        messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: @system_prompt.call(model) })
+        # Under the next turn's strategy (a /model switch may have changed it);
+        # the last turn's when it can't be resolved; the turn's settings
+        # (TurnContext, set in Engine#generate) for the rest.
+        settings = turn.context.settings
+        prompt, images = @kernel.warmup_prompt(messages, llm_context: @model_settings.turn_llm_context || settings.llm_context,
+                                                         vision: settings.vision)
+        return unless prompt
+
+        # The model name as the native run sent it (KernelLoop#run's
+        # completion name: the default model for a blank one).
+        started = @prompt_warmup.start(client: client, prompt: prompt, model: ModelProfile.required_model_name(settings.model_name),
+                                       slot: @kernel.last_slot, images: images)
+        @kernel.warmed_up! if started
+      rescue StandardError => e
+        Log.warn(:model, "warmup_skipped", error: e.class.name, msg: e.message.to_s[0, 200])
+      end
+
+      private
+
+      # Never a paid or remote host (cache.warmup auto means local only), nor
+      # the chat loop (Splash keeps its own cache; llama.cpp's chat path is
+      # not measured), nor a client that can't warm up (a spec's stub).
+      def target?(model, client)
+        return false if model.chat? || model.entry.remote?
+        return false unless client.respond_to?(:warm_up)
+
+        PromptWarmup.enabled?
+      end
+    end
+  end
+end

data/lib/samagotchi/turn_state.rb

@@ -6,7 +6,8 @@ module Samagotchi
   # A session's turn as other threads see it: whether one runs, its cancel
   # controller and event sink, the plugin steers waiting for its next
   # boundary, whether a person's message waits for it (its caller's
-  # input_waiting: probe), and the activity clock the idle jobs read.
+  # input_waiting: probe), the turn's TurnContext (#context, and the last
+  # turn's, #last_context), and the activity clock the idle jobs read.
   #
   # The turn thread writes it (Engine#begin_turn, #release_turn); the idle
   # scheduler, the bridge's request threads, plugin threads and the UIs
@@ -27,6 +28,8 @@ module Samagotchi
       @ended = false
       @input_waiting = nil
       @input_waiting_warned = false
+      @context = nil
+      @last_context = nil
       @steers = []
       @carried_steers = []
     end
@@ -70,12 +73,16 @@ module Samagotchi
     end
 
     # A turn begins, on the calling thread (the turn's own): running, with
-    # its controller, sink and input_waiting probe, in one step.
+    # its context, controller, sink and input_waiting probe, in one step, so
+    # no reader sees a running turn with the previous turn's context.
+    # @param context [TurnContext, nil] the turn's, built before (nil: none,
+    #   a spec's bare turn)
     # @param input_waiting [#call, nil] true while a person's message waits
     #   for the turn's next boundary (Engine#input_waiting?); nil: never
-    def begin!(controller:, sink:, input_waiting: nil)
+    def begin!(controller:, sink:, context: nil, input_waiting: nil)
       @lock.synchronize do
         @running = true
+        @context = context
         @controller = controller
         @sink = sink
         @thread = Thread.current
@@ -87,10 +94,18 @@ module Samagotchi
       end
     end
 
-    # The turn is over: not running, no controller, sink, probe or steers.
+    # The turn is over: not running, no context, controller, sink, probe or
+    # steers. Its context stays as the last one (#last_context); one that
+    # never got its settings (a turn stopped before Engine#generate) keeps
+    # the last settings there, as the kernel kept the last turn's before.
     # @return [Array<Hash>] the steers it never took ({text:, source:})
     def finish!
       @lock.synchronize do
+        if @context
+          settings = @context.settings || @last_context&.settings
+          @last_context = settings.equal?(@context.settings) ? @context : @context.with(settings: settings)
+        end
+        @context = nil
         @running = false
         @controller = nil
         @sink = nil
@@ -107,6 +122,33 @@ module Samagotchi
       @lock.synchronize { @ended = true }
     end
 
+    # @return [TurnContext, nil] the running turn's context (nil between
+    #   turns); its settings are nil until Engine#generate
+    def context
+      @lock.synchronize { @context }
+    end
+
+    # @return [TurnContext, nil] the last finished turn's context (nil
+    #   before any), kept while the next turn runs
+    def last_context
+      @lock.synchronize { @last_context }
+    end
+
+    # The turn thread's new context for its running turn (Engine#generate's
+    # settings): one assignment of a frozen value. Only the turn's own
+    # thread, and only for the same turn.
+    # @param context [TurnContext]
+    # @raise [ArgumentError] from another thread, outside a turn, or for
+    #   another turn's context
+    def replace_context(context)
+      @lock.synchronize do
+        raise ArgumentError, "no turn runs on this thread" unless @running && @thread.equal?(Thread.current)
+        raise ArgumentError, "not the running turn's context" unless @context.nil? || @context.id == context.id
+
+        @context = context
+      end
+    end
+
     # @return [CancellationController, nil] the running turn's controller
     def controller
       @lock.synchronize { @controller }

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.154.1"
+  VERSION = "0.155.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end