samagotchi 0.154.1 → 0.156.0

data/lib/samagotchi/engine.rb

@@ -27,9 +27,11 @@ require_relative "thinking_notices"
 require_relative "cancellation_controller"
 require_relative "context_window"
 require_relative "kernel_loop"
+require_relative "reprefill_meter"
 require_relative "tools/builtins"
 require_relative "tools/task_runtime"
 require_relative "tools/tool_index"
+require_relative "tools/tool_surface"
 require_relative "peer_sources"
 require_relative "session_commands"
 require_relative "plugin/loader"
@@ -54,7 +56,13 @@ require_relative "context_judge"
 require_relative "objectives_audit"
 require_relative "owner_prompt"
 require_relative "side_judgments"
+require_relative "system_one/recorder"
 require_relative "toolkit_suggest"
+require_relative "turn_stages/context_judge"
+require_relative "turn_stages/objectives"
+require_relative "turn_stages/toolkit_suggestion"
+require_relative "turn_stages/verify_anchors"
+require_relative "turn_stages/warmup"
 require_relative "tool_loads"
 require_relative "answer_tail"
 require_relative "archive_store"
@@ -79,6 +87,7 @@ require_relative "tools/memory"
 require_relative "muted_memories"
 require_relative "used_memories"
 require_relative "turn_state"
+require_relative "turn_context"
 require_relative "steer_cut"
 require_relative "engine_peers"
 require_relative "engine_snapshots"
@@ -206,8 +215,6 @@ module Samagotchi
       # steers) and the idle layer's activity clock. Built first: a plugin
       # may steer or ask whether a turn runs while it loads.
       @turn_state = TurnState.new(clock: -> { monotonic_now })
-      @objective_proposals = []
-      @objective_proposals_mutex = Mutex.new
       # A message for the running turn cutting its generation.
       @steer_cut = SteerCut.new(clock: -> { monotonic_now }, controller: -> { active_cancel_controller },
                                 cut_after: -> { steer_cut_after })
@@ -223,12 +230,11 @@ module Samagotchi
       @chat_backend_mutex = Mutex.new
       @side_judgments = SideJudgments.new
       @judgments = build_judgments
-      # On mode's cards an answer brought while a turn ran: shown once it
-      # has ended (#show_context_cards_after_turn).
-      @context_cards_after_turn = []
-      @context_cards_mutex = Mutex.new
-      @toolkit_warmup_thread = nil
       @host_registry = host_registry || HostRegistry.new
+      # The turn stages over the objectives (its audit, view and proposals)
+      # and the Verify/Revise anchors (TurnStages).
+      @objectives_stage = build_objectives_stage
+      @verify_anchors = build_verify_anchors
       # A model given here (a worker's session model) is the one it runs,
       # so its host is checked; the config default is only checked once it
       # is used (the one-shot checks the model it starts on, #switch_model!).
@@ -302,6 +308,8 @@ module Samagotchi
       # The kernel (built here, or a spec's) and what it reads of the Engine;
       # then the native backend over it.
       wire_kernel(kernel, muted_memories)
+      # The turn-end warm-up's stage, over that kernel.
+      @turn_warmup = build_turn_warmup
       Log.debug(:model, "backend", provider: backend.provider) if Log.level?(:debug)
       @resume_session = session_id ? Session.load(session_id) : nil
       @prompt_builder = build_system_prompt(memories, appended_prompt_files)
@@ -379,6 +387,11 @@ module Samagotchi
       # The session's toolkit: the kits (the plugins' too, chi.toolkit),
       # what its next turn declares, the turn-start apply.
       @toolkit_binding = build_toolkit_binding
+      # The turn stages over it and the side asks (TurnStages): System 1's
+      # toolkit suggestion and the attached-context candidate judge, which a
+      # plugin may reach as it loads.
+      @toolkit_suggestion = build_toolkit_suggestion
+      @context_judge = build_context_judge
       # The tools plugins publish without declaring (chi.tool_source), and
       # the search and call tools that reach them (Tools::ToolIndex).
       @tool_index = Tools::ToolIndex.new
@@ -396,6 +409,8 @@ module Samagotchi
       # with no plugins too: a toolkit's left-out tools are reachable
       # either way (declared per toolkit, Tools::Registry).
       @tool_index.declare(@tools, failures: @plugin_failures)
+      # What readers off the turn thread see until the first turn's start.
+      publish_tools!
     end
     private :build_tools_and_plugins
 
@@ -424,45 +439,42 @@ module Samagotchi
     end
     private :subscribe_session_observers
 
-    # The kernel and what it holds of the Engine (stores, hooks, tools, the
-    # mutes, the question flow, the gate, peers, warm-up, the hook runtime),
-    # and the native backend over it. After the plugins load.
+    # The kernel and what it holds of the Engine for its life, one
+    # KernelLoop::Services (stores, hooks, tools, the mutes, the question
+    # flow, peers, the gate, warm-up, the generation guard), and the native
+    # backend over it. After the plugins load. Nothing per turn: a turn's
+    # TurnContext goes down the backend's complete (#generate).
     def wire_kernel(kernel, muted_memories)
-      # A given kernel (specs) gets the Engine's store, hooks and tools, as
-      # the one built here does.
-      @kernel = kernel || KernelLoop.new(client: @client, profile: @model_binding.given_profile, model_name: effective_model_name,
-                                         hooks: @hooks, reminder_store: @reminder_store, tools: @tools)
-      @kernel.reminder_store = @reminder_store
-      @kernel.hooks = @hooks
-      @kernel.tools = @tools
-      sync_kernel_client!
-      sync_model_key!
-      # The mutes never change during a session, so no re-sync: the kernel's
-      # memory_read guard reads the same list for every turn.
+      # The mutes never change during a session: the kernel's memory_read
+      # guard reads the same list for every turn.
       @muted_memory_names = MutedMemories.normalize_list(muted_memories)
-      @kernel.muted_memory_names = @muted_memory_names
-      # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
-      @kernel.question_handler = proc { |payload| request_question(payload) }
-      # Every tool call asks this gate first. The kernel is never rebuilt, so
-      # it holds across model switches.
+      # Where the approvals live; also where list_sessions and send_note
+      # look for other sessions (a worker moves it, Worker).
       self.guardrail_state_dir = Session.default_state_dir
-      # list_sessions and send_note speak for whichever session runs now.
-      @kernel.peers = PeerView.new(self)
-      # A plugin tool's row refs resolve against the session's folder, as
-      # answer refs do (AnswerRefs), not the process's.
-      @kernel.session_cwd = -> { @session&.working_directory }
-      # forget_outputs refuses what the user pinned in the working set.
-      @kernel.working_set_pins = -> { @session&.working_set_pins || [] }
-      # A cut tool output is saved whole in the session's folder.
-      @kernel.session_dir = -> { @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir) }
-      @kernel.guardrail_gate = @guardrail_wiring.gate
-      @kernel.participant_turn = -> { Steer.participant_author?(turn_author) }
-      @kernel.participant_mode = -> { @guardrail_wiring.turn_mode }
-      # A pair turn stops once its participant passed their cap.
-      @kernel.generation_guard = -> { guard_participant_spend }
       # The turn-end warm-up; the kernel asks it for a slot pin per request.
       @prompt_warmup = PromptWarmup.new
-      @kernel.warmup = @prompt_warmup
+      # One re-prefill baseline for both loops (the native kernel's and the
+      # chat loop's requests), reset by the warm-up (KernelLoop#warmed_up!).
+      @reprefill = ReprefillMeter.new
+      services = KernelLoop::Services.new(
+        hooks: @hooks, tools: @tools, reminder_store: @reminder_store, muted_memory_names: @muted_memory_names,
+        # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
+        question_handler: proc { |payload| request_question(payload) },
+        # list_sessions and send_note speak for whichever session runs now.
+        peers: PeerView.new(self),
+        # Every tool call asks this gate first. The kernel is never rebuilt,
+        # so it holds across model switches.
+        gate: @guardrail_wiring.gate(hooks: @hooks, tools: @tools),
+        warmup: @prompt_warmup,
+        # A pair turn stops once its participant passed their cap.
+        generation_guard: ->(context) { guard_participant_spend(context) }
+      )
+      # A given kernel (specs) gets the same services as the one built here.
+      @kernel = kernel || KernelLoop.new(client: @client, profile: @model_binding.given_profile,
+                                         model_name: effective_model_name, services: services, reprefill: @reprefill)
+      @kernel.attach(services, reprefill: @reprefill) if kernel
+      sync_kernel_client!
+      sync_model_key!
       # What a hook can do beyond reading its event (event[:notify],
       # event[:ask_user], event[:stop_turn]): the Engine's routes to the UIs.
       @hooks.runtime = hook_runtime
@@ -476,11 +488,9 @@ module Samagotchi
     def build_guardrail_wiring
       GuardrailWiring.new(
         scratch: @scratch,
-        hooks: -> { @hooks },
+        # Built before the tools (the hooks load into its failures).
         tools: -> { @tools },
         session: -> { @session },
-        model_key: -> { @model_binding.model_key },
-        model_name: -> { guardrail_model_name },
         cancelled: -> { !!active_cancel_controller&.cancelled? },
         # An approval of the model's call: :question_asked first (QuestionAsked).
         ask: ->(fields) { open_question(question_asked(QuestionAsked::KIND_APPROVAL, fields)) },
@@ -495,7 +505,7 @@ module Samagotchi
         system_one_runs: -> { system_one_runs },
         cancel_controller: -> { active_cancel_controller },
         # A participant's turn: their name on the owner's card, their
-        # grant's mode for the turn's (GuardrailWiring#turn_mode).
+        # grant's mode for the turn's (GuardrailWiring#begin_turn).
         participant: ->(author) { @participants.entry_for(author, session: @session) }
       )
     end
@@ -511,7 +521,8 @@ module Samagotchi
         thinking_notices: -> { @thinking_notices },
         metrics: -> { @metrics },
         hooks: -> { @hooks },
-        kernel: -> { @kernel },
+        turn_context: -> { turn_context },
+        last_turn_context: -> { last_turn_context },
         model_settings: -> { @model_settings },
         session: -> { @session },
         live_conversation: -> { live_conversation },
@@ -683,7 +694,7 @@ module Samagotchi
       end
       @side_judgments.join(SIDE_JUDGMENTS_JOIN_SECONDS)
       # The warm-up's answer is dropped anyway.
-      stop_toolkit_warmup
+      @toolkit_suggestion.stop_warmup
       left = threads.count(&:alive?)
       Log.warn(:plugins, "anytime_commands_left", count: left) if left.positive?
       @plugin_tasks.kill_leftovers
@@ -715,9 +726,9 @@ module Samagotchi
         kept, event = yield(seconds)
         event[:turn_id] = turn.id
         event[:verify] = true if turn.verify
-        revises = stamp_opening(kept, turn, outcome)
+        revises = @verify_anchors.stamp_opening(kept, turn, outcome)
         replace_session_messages(turn.session, kept) if kept
-        verdict = record_verdict(turn, outcome)
+        verdict = @verify_anchors.record_verdict(turn, outcome)
         event[:verdict] = verdict if verdict
         event[:revises] = revises.to_h if revises
         emit_working_set(turn.on_event, turn.session, turn.session.messages)
@@ -778,14 +789,15 @@ module Samagotchi
     end
     private :build_recap
 
-    # One turn's values, for #run_turn and its endings. Per turn and
-    # single-threaded: the cross-thread turn state (the cancel slot, the
-    # sink, steers) stays on the Engine.
+    # One turn's lifecycle state, for #run_turn and its endings. Per turn
+    # and single-threaded: the cross-thread turn state (the published
+    # TurnContext, the cancel slot, the sink, steers) stays in TurnState.
+    # +context+: the turn's TurnContext, the one source of truth for its
+    # id, session, origin and controller (read through #id, #session,
+    # #origin, #controller); #generate replaces it with the settings in.
     # +ended+: the end event is out (what follows is post-turn work).
-    # +settings+: the kernel's LLM::TurnSettings, made in #prepare_turn and
-    # set on the kernel in #generate.
-    # +id+: names the turn on :turn_started (its metrics record's id) and on
-    # its saved prompt, so a UI pairs the two whatever left the conversation.
+    # +prepared_settings+: the LLM::TurnSettings #prepare_turn makes (before
+    # the hooks); #generate completes them into the context's.
     # +limit+: the iteration limit #generate ran it with.
     # +resumed+: a step-limit Continue (run_turn's resumed:).
     # +resume_from+: where its reasoning starts, the run it resumes
@@ -794,8 +806,15 @@ module Samagotchi
     # +wall+: the wall time it started (MessageTime.now, once): the
     # :turn_started event's at and its user message's (and reminders') stamp.
     # +verify+, +revises+: a Verify turn's claim, a Revise turn's draft.
-    Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id, :limit, :resumed, :resume_from, :wall, :verify, :revises, :outcome) do
+    Turn = Struct.new(:context, :prompt, :continue, :on_event, :started_at, :messages, :ended, :prepared_settings,
+                      :limit, :resumed, :resume_from, :wall, :verify, :revises, :outcome) do
+      # The turn's id (:turn_started's turn_id, its metrics record's id and
+      # its saved prompt's), session, origin and controller: its context's.
+      def id = context.id
+      def session = context.session
+      def origin = context.origin
+      def controller = context.controller
+
       def resumed? = resumed ? true : false
 
       # The turn ended as a completed one (not canceled, not failed): the
@@ -866,7 +885,7 @@ module Samagotchi
     #   wake's note) names it with this id
     # @param verify [VerifyAnchor, nil] a Verify turn's claim (its verdict)
     # @param revises [ReviseAnchor, nil] a Revise turn's draft: stamped on
-    #   the prompt at the turn's end, metadata only (#stamp_opening)
+    #   the prompt at the turn's end, metadata only (TurnStages::VerifyAnchors#stamp_opening)
     #
     # An Interrupt (SIGINT) cancels the turn: what it got to is kept in the
     # session as after a Stop (the prompt, the loop's finished tool
@@ -897,7 +916,7 @@ module Samagotchi
                                 pending_input: pending_input)
         publish_used_memories(session, on_event)
         complete_turn(turn, result)
-        warm_up_next_turn(turn, result)
+        @turn_warmup.after(turn, result, next_turn_waiting: next_turn_waiting)
         result
       rescue Interrupt => e
         # After the end event (in the after_turn/session_end hooks) the
@@ -924,24 +943,23 @@ module Samagotchi
         raise
       ensure
         release_turn(probe_cancel_before)
-        show_context_cards_after_turn
-        # Only a completed turn shows its proposal cards: a canceled, failed
-        # or rolled-back turn keeps none, and its proposals are dropped here
-        # so the next turn does not show them either.
-        turn.completed? ? show_objective_proposals : discard_objective_proposals(turn)
+        @context_judge.show_cards_after_turn
+        # Only a completed turn shows its proposal cards; any other's are
+        # dropped, so the next turn does not show them either.
+        show_objective_proposals(turn)
       end
     end
 
     # The turn's state before anything can fail it: the session running,
-    # the turn flag, its cancel controller and sink. The cross-thread state
-    # is set here and cleared in #release_turn only.
+    # its TurnContext, the turn flag, its cancel controller and sink. The
+    # cross-thread state is set here and cleared in #release_turn only.
     def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil, verify: nil, revises: nil,
                    input_waiting: nil)
       origin = TurnOrigin.of(origin)
       # A participant's Verify fresh child: every turn is theirs (their
       # author, boundary and cap), whoever started it.
       origin = session.verify_fresh.origin_for(origin) if session.respond_to?(:verify_fresh) && session.verify_fresh
-      verify = verified_anchor(session, VerifyAnchor.from(verify))
+      verify = @verify_anchors.verified(session, VerifyAnchor.from(verify), state_dir: session_state_dir)
       # Track the active session for recap and status snapshot.
       @session = session
       # status is turn state: running now, idle again before the turn's end
@@ -950,25 +968,62 @@ module Samagotchi
       @used_memories.absorb(session)
       # Provide a cancellable controller for this turn (cross-process cancel via file flag)
       effective_controller = cancel_controller || CancellationController.new
-      # The turn runs, with its controller and sink, in one step: a Stop
-      # or a plugin's card from another thread never sees a running turn
-      # without them. The idle recap detector does not fire (or render an
-      # invalidated recap) while the model is working. A hook's notice goes
-      # where the turn's events go (a one-shot prints only its sink; a
-      # worker's observers carry it to the bridge).
-      @turn_state.begin!(controller: effective_controller, sink: on_event, input_waiting: input_waiting)
+      # The turn's context, whole before the turn is published: who queued
+      # it, a participant's mode (participants.json), git asked afresh.
+      context = new_turn_context(session, origin, effective_controller, id || SecureRandom.uuid)
+      # The turn runs, with its context, controller and sink, in one step:
+      # a Stop, a plugin's card or its ctx.turn_author from another thread
+      # never sees a running turn without them (or with the last turn's).
+      # The idle recap detector does not fire (or render an invalidated
+      # recap) while the model is working. A hook's notice goes where the
+      # turn's events go (a one-shot prints only its sink; a worker's
+      # observers carry it to the bridge).
+      @turn_state.begin!(context: context, controller: effective_controller, sink: on_event, input_waiting: input_waiting)
       # Drop a recap already in flight: the turn makes it stale.
       @recap&.invalidate!
-      # The gate's context: who queued this turn, and git asked afresh.
-      @guardrail_wiring.begin_turn(origin)
 
-      Turn.new(session: session, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
-               controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
-               id: id || SecureRandom.uuid, wall: MessageTime.now, verify: VerifyAnchor.from(verify),
-               revises: ReviseAnchor.from(revises))
+      Turn.new(context: context, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
+               started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC), wall: MessageTime.now,
+               verify: VerifyAnchor.from(verify), revises: ReviseAnchor.from(revises))
     end
     private :begin_turn
 
+    # A new turn's TurnContext (#begin_turn): the gate's turn facts
+    # (GuardrailWiring#begin_turn), the session's folders. Its settings and
+    # model come in #generate.
+    def new_turn_context(session, origin, controller, id)
+      start = @guardrail_wiring.begin_turn(origin, session: session)
+      TurnContext.new(id: id, session: session, origin: origin, author: origin.participant_author,
+                      participant_mode: start.mode, participant: start.participant, controller: controller,
+                      cwd: (session.working_directory if session.respond_to?(:working_directory)), session_dir: turn_session_dir(session),
+                      state_dir: session_state_dir, git: start.git, settings: nil, model_key: nil,
+                      fallback_model_key: nil, model_name: nil, surface: nil)
+    end
+    private :new_turn_context
+
+    # The session's folder, nil when it can't be named (an id that isn't
+    # one, a lookup that raised): a cut tool output then says it wasn't saved.
+    def turn_session_dir(session)
+      Session.session_dir(session.id, state_dir: session_state_dir)
+    rescue StandardError => e
+      Log.warn(:turn, "tool_output_save_failed", error: e.class.name)
+      nil
+    end
+    private :turn_session_dir
+
+    # The running turn's TurnContext as other threads see it (TurnState),
+    # nil between turns; its settings are nil until #generate.
+    # @return [TurnContext, nil]
+    def turn_context = @turn_state.context
+    private :turn_context
+
+    # The last finished turn's TurnContext (TurnState#last_context), nil
+    # before any: its author (the recap's), its settings (the working set's
+    # between turns).
+    # @return [TurnContext, nil]
+    def last_turn_context = @turn_state.last_context
+    private :last_turn_context
+
     # Everything before the model is asked: :turn_started, the kernel's
     # per-turn settings, the plugins' setup, the session_start/before_turn
     # hooks, then the messages to send (#turn_messages). False when a Stop
@@ -987,14 +1042,14 @@ module Samagotchi
       # A participant's turn names them (author, author_name) for the UIs'
       # badge; the owner's turn_started stays as it was.
       turn_started.merge!(author_fields(turn.origin.author, session: session),
-                          participant_mode_fields(turn.origin.author))
+                          participant_mode_fields(turn.context))
       emit_event(turn.on_event, turn.tag(turn_started))
       raise image_error if image_error
 
       # On mode's ask starts here too; the turn joins it before
       # apply_toolkit! below, so its latency hides behind the probes and
       # the init wait.
-      toolkit_suggestion = start_toolkit_suggestion(turn)
+      @toolkit_suggestion.start(turn, recorder: system_one_recorder)
 
       # The window and the profile probes run after run_turn's probe-cancel
       # swap, so a Stop cuts them; a failure ends the turn as turn_failed.
@@ -1006,12 +1061,12 @@ module Samagotchi
       refresh_profile!
 
       # Before anything of the turn is kept or a reminder is used up.
-      turn.settings = turn_settings(session)
-      refuse_images!(turn.settings.vision) unless image_refs.empty?
+      turn.prepared_settings = turn_settings(session)
+      refuse_images!(turn.prepared_settings.vision) unless image_refs.empty?
       # A Stop during the probes: the turn ends before the load-failure
       # warnings, which show once, so the next turn still shows them.
       if turn.controller.cancelled?
-        toolkit_suggestion&.abandon(:canceled)
+        @toolkit_suggestion.abandon(turn, :canceled)
         return false
       end
 
@@ -1028,11 +1083,11 @@ module Samagotchi
       apply_staged_tools!
       # On mode: the suggested kit, before anything is declared (a Stop
       # during the wait is caught by the check below).
-      settle_toolkit_suggestion(turn, toolkit_suggestion)
+      @toolkit_suggestion.settle(turn)
       # The candidate judge: its asks run beside the turn; on mode's
       # attaches reach the model at the next between-turn delivery.
-      start_context_judge(turn)
-      audit_objectives_incoming(turn)
+      @context_judge.start(turn, recorder: system_one_recorder)
+      @objectives_stage.incoming(turn, recorder: system_one_recorder)
       apply_toolkit!(session, turn.on_event)
       refresh_participants!(session)
       # A Stop during the waits above: the turn ends here,
@@ -1055,7 +1110,8 @@ module Samagotchi
     ensure
       # A turn that ended (a failure, an Interrupt) before it settled the
       # ask: its line says so. Nothing once it was settled.
-      toolkit_suggestion&.abandon(:failed)
+      @toolkit_suggestion.abandon(turn, :failed)
+      @toolkit_suggestion.finish(turn)
     end
     private :prepare_turn
 
@@ -1087,7 +1143,7 @@ module Samagotchi
 
       unless turn.continue
         user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author),
-                         **participant_mode_fields(turn.origin.author), MessageTime::KEY => turn.at }
+                         **participant_mode_fields(turn.context), MessageTime::KEY => turn.at }
         user_message[:verify] = turn.verify.to_h if turn.verify
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
@@ -1106,17 +1162,28 @@ module Samagotchi
       # Route model name as bare (without host prefix) to the server;
       # host selection already done via active client.
       bare_for_backend = bare_model_name(model.name)
-      # The turn's settings, set once here. The chat loop dispatches tools
-      # through the kernel without its #run: tag those dumps with this
-      # turn's model, not the last native one.
+      # The turn's settings, set once here into its context (with the model
+      # key and name the gate and memory_read use: frozen now, after the
+      # hooks that may switch the model), which goes down the backend's
+      # complete to every tool call, and is published (TurnState).
       explained = model.llm_context_explained(@model_settings.llm_context_session_args)
       model_backend = backend(model)
       # A host that loads tools runs a direct call of one the session
       # reaches but doesn't declare (ToolRunner, KernelLoop#dispatch).
       loads_tools = model_backend.respond_to?(:loads_tools?) && model_backend.loads_tools?(bare_for_backend)
-      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: model.window_setting,
-                                                 llm_context: explained&.resolved, price: model.price,
-                                                 loads_tools: loads_tools)
+      settings = turn.prepared_settings.with(model_name: bare_for_backend, window_setting: model.window_setting,
+                                             llm_context: explained&.resolved, price: model.price,
+                                             loads_tools: loads_tools)
+      # The turn's tools (Tools::ToolSurface), built once from the Registry
+      # under those settings' layers and loads_tools: what the loops declare,
+      # defer and dispatch until the turn ends; a change meanwhile (a
+      # /toolkit change, a staged chi.replace_tools) is the next turn's.
+      surface = Tools::ToolSurface.for(@tools, layers: settings.llm_context&.active_layers || [],
+                                               loads_tools: loads_tools)
+      turn.context = turn.context.with(settings: settings, model_key: @model_binding.model_key,
+                                       fallback_model_key: @model_binding.fallback_model_key,
+                                       model_name: guardrail_model_name, surface: surface)
+      @turn_state.replace_context(turn.context)
       log_llm_context(explained)
 
       turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
@@ -1133,7 +1200,8 @@ module Samagotchi
         model_name: bare_for_backend,
         max_tool_output_chars: max_tool_output_chars,
         pending_input: turn_drain(pending_input),
-        reasoning_since: reasoning_since
+        reasoning_since: reasoning_since,
+        context: turn.context
       )
       result.run_start = run_start
       result

data/lib/samagotchi/engine_peers.rb

@@ -4,7 +4,7 @@ require_relative "objectives"
 
 module Samagotchi
   # The views of an Engine its peers get: the kernel's tools
-  # (Engine#initialize sets @kernel.peers) and a delegate's approval relay
+  # (KernelLoop::Services#peers, Engine#wire_kernel) and a delegate's approval relay
   # (Engine#relay_peer).
   class Engine
     # The kernel's Tools::Peers, following the current session. cancelled?

data/lib/samagotchi/event_fanout.rb

@@ -26,7 +26,8 @@ module Samagotchi
     # @param thinking_notices  [#call] → ThinkingNotices
     # @param metrics           [#call] → SessionMetrics
     # @param hooks             [#call] → Hooks::Registry
-    # @param kernel            [#call] → KernelLoop
+    # @param turn_context      [#call] → TurnContext, nil: the running turn's (Engine#turn_context)
+    # @param last_turn_context [#call] → TurnContext, nil: the last finished turn's
     # @param model_settings    [#call] → SessionModelSettings
     # @param session           [#call] → Session, nil
     # @param live_conversation [#call] → Array<Hash>, the running turn's conversation
@@ -35,8 +36,8 @@ module Samagotchi
     # @param working_set_strategy [#call] → the strategy the working set is built under
     # @param turn_running      [#call] → Boolean
     # @param announce_or_hold  [#call] (event) → announces the event, or holds it
-    def initialize(observer:, used_memories:, muted:, steer_cut:, thinking_notices:, metrics:, hooks:, kernel:,
-                   model_settings:, session:, live_conversation:, used_memory_names:, served_expected_by:,
+    def initialize(observer:, used_memories:, muted:, steer_cut:, thinking_notices:, metrics:, hooks:, turn_context:,
+                   last_turn_context:, model_settings:, session:, live_conversation:, used_memory_names:, served_expected_by:,
                    working_set_strategy:, turn_running:, announce_or_hold:)
       @observer = observer
       @used_memories = used_memories
@@ -45,7 +46,8 @@ module Samagotchi
       @thinking_notices = thinking_notices
       @metrics = metrics
       @hooks = hooks
-      @kernel = kernel
+      @turn_context = turn_context
+      @last_turn_context = last_turn_context
       @model_settings = model_settings
       @session = session
       @live_conversation = live_conversation
@@ -149,15 +151,18 @@ module Samagotchi
     end
 
     # The strategy the set is built under: the running turn's
-    # (TurnSettings#llm_context: what its requests send); between turns
-    # the next turn's (as #warm_up_next_turn: the turn's settings keep the
-    # last turn's, stale after a /llm-context or /model change), the last
-    # turn's when it can't be resolved.
+    # (TurnSettings#llm_context: what its requests send), the last turn's
+    # while the running one has no settings yet (before Engine#generate);
+    # between turns the next turn's (as TurnStages::Warmup#after: the last turn's
+    # settings are stale after a /llm-context or /model change), the last
+    # turn's when it can't be resolved. One read of each published context
+    # (TurnState): any thread may ask (/working-set's anytime list).
     def working_set_llm_context
-      turn = kernel.respond_to?(:turn_settings) ? kernel.turn_settings&.llm_context : nil
-      return turn if turn_running?
+      running = turn_context
+      last = last_turn_context&.settings&.llm_context
+      return running.settings ? running.settings.llm_context : last if running
 
-      model_settings.turn_llm_context || turn
+      model_settings.turn_llm_context || last
     end
 
     # A :generation_completed with the generation's decode speed (`speed:`
@@ -222,7 +227,8 @@ module Samagotchi
     def thinking_notices = @thinking_notices.call
     def metrics = @metrics.call
     def hooks = @hooks.call
-    def kernel = @kernel.call
+    def turn_context = @turn_context.call
+    def last_turn_context = @last_turn_context.call
     def model_settings = @model_settings.call
     def session = @session.call
     def live_conversation = @live_conversation.call