samagotchi 0.154.1 → 0.156.0

data/lib/samagotchi/kernel_loop.rb

@@ -24,8 +24,11 @@ require_relative "reasoning_history"
 require_relative "thought_stream_splitter"
 require_relative "tools/builtins"
 require_relative "tools/builtin_calls"
+require_relative "tools/tool_surface"
 require_relative "muted_memories"
 require_relative "tool_activity"
+require_relative "reprefill_meter"
+require_relative "tool_output_cut"
 require_relative "tool_runner"
 require_relative "tool_response"
 require_relative "tool_ids"
@@ -38,6 +41,7 @@ require_relative "answer_display"
 require_relative "message_time"
 require_relative "llm/model_result"
 require_relative "llm/turn_settings"
+require_relative "turn_context"
 require_relative "llm/stream_drops"
 
 module Samagotchi
@@ -59,30 +63,34 @@ module Samagotchi
     # The built-in tool classes (Tools::Builtins registers them).
     TOOLS = Tools::Builtins::CLASSES
 
-    # What a tool handler (call, kctx) gets from the kernel: the reminder
-    # store, the peers, the model key, and the memory read and ask-user
-    # flows that need its state (read through the kernel's public readers).
+    # What a tool handler (call, kctx) gets: the kernel's reminder store
+    # and peers, the call's turn (+context+, a TurnContext: the participant's
+    # mode, the model key), and the memory read and ask-user flows that need
+    # them. One per dispatched call.
     class ToolContext
-      def initialize(kernel)
+      def initialize(kernel, context)
         @kernel = kernel
+        @context = context
       end
 
       def reminder_store = @kernel.reminder_store
-      def peers = @kernel.peers
+      def peers = @kernel.services.peers
 
-      # The running participant turn's mode (KernelLoop#participant_mode:
-      # :pair, :review), nil for the owner's turns.
-      def participant_mode = @kernel.participant_mode&.call
-      def model_key = @kernel.model_key
+      # The participant turn's mode (TurnContext#participant_mode: :pair,
+      # :review), nil for the owner's turns.
+      def participant_mode = @context.participant_mode
+      # The memory overlay key (TurnContext#model_key, frozen at the turn's
+      # generate).
+      def model_key = @context.model_key
 
       # memory_read with the session's mutes applied: a blank name (the index)
       # loses the muted memories' lines; a muted name in a comma list is
       # refused with its own error line and the rest is read as usual.
       def muted_memory_read(call)
-        muted = Array(@kernel.muted_memory_names)
+        muted = Array(@kernel.services.muted_memory_names)
         content = call[:content].to_s
         read = lambda do |names|
-          Tools::MemoryRead.call(names, scope: call[:scope], model_key: model_key, fallback_model_key: @kernel.model_key_fallback)
+          Tools::MemoryRead.call(names, scope: call[:scope], model_key: model_key, fallback_model_key: @context.fallback_model_key)
         end
         return read.call(content) if muted.empty?
         return MutedMemories.filter_index(read.call(content), muted) if content.strip.empty?
@@ -98,14 +106,14 @@ module Samagotchi
       end
 
       # ask_user_question: validate the call, then hand the payload to the
-      # Engine's question flow (the kernel's question_handler, which blocks
+      # Engine's question flow (the kernel's Services#question_handler, which blocks
       # until the user answers). Without one (headless), the payload as JSON
       # so the model sees the options and can ask in plain text.
       def ask_user_question(call)
         payload = Tools::AskUserQuestion.validate(call)
         return payload if payload.is_a?(String)
 
-        handler = @kernel.question_handler
+        handler = @kernel.services.question_handler
         return JSON.pretty_generate(payload) unless handler
 
         handler.call(payload).to_s
@@ -115,44 +123,102 @@ module Samagotchi
 
       # forget_outputs: the forget layer's call on the running turn's
       # conversation (KernelLoop#forget_outputs).
-      def forget_outputs(call) = @kernel.forget_outputs(call)
+      def forget_outputs(call) = @kernel.forget_outputs(call, @context)
+
+      # The turn's Tools::ToolSurface (TurnContext#surface; a bare kernel's
+      # own context has one too, KernelLoop#own_context): what the tool
+      # index's handlers (find_tools, call_tool) read.
+      def surface = Tools::ToolSurface.of(@context)
     end
 
-    DEFAULT_MAX_TOOL_OUTPUT_CHARS = 10_000
     QWEN_INCOMPLETE_TOOL_CALL_RECOVERY_LIMIT = 2
     # How much of a malformed generation's end the warning keeps.
     MALFORMED_TAIL_CHARS = 400
     QWEN_INCOMPLETE_TOOL_CALL_RECOVERY_PROMPT = "Continue the previous assistant message by finishing the open <tool_call> XML block. Output only the remaining XML needed to complete the tool call."
 
-    # @param tools [Tools::Registry, nil] the tools calls dispatch to (the
-    #   Engine's; nil: the built-ins alone)
+    # What a kernel holds of its Engine for the Engine's life, one value
+    # (Engine#wire_kernel builds it; a spec's kernel takes one through
+    # #attach): nothing per turn (a turn's TurnContext goes down #run).
+    #
+    # - hooks: the Hooks::Registry the loop fires (nil: none); the Engine's
+    # - tools: the Tools::Registry #dispatch runs (the built-ins by default)
+    # - reminder_store: the ReminderStore the reminder tools write (nil: none)
+    # - muted_memory_names: the session's muted memories (normalized names,
+    #   MutedMemories), refused by memory_read; nil: none
+    # - question_handler: answers ask_user_question (payload → answer
+    #   string; the Engine's blocking request_question); nil: headless
+    # - peers: Tools::Peers (or the Engine's PeerView): the session
+    #   list_sessions and send_note speak for; nil outside a session
+    # - gate: the Guardrails::Gate ToolRunner asks before each call; nil:
+    #   ToolRunner's own, hooks only
+    # - warmup: the Engine's PromptWarmup, asked for a slot pin per request
+    #   (#take_pin) while the turn-end warm-up runs; nil: never pinned
+    # - generation_guard: called before each generation with the turn's
+    #   TurnContext, before the before_generation hook; the Engine's check
+    #   that may stop the turn (a pair turn past its participant's cap,
+    #   Engine#guard_participant_spend); nil: none
+    #
+    # The client is not one of them: a model switch swaps it
+    # (#client=, Engine#sync_kernel_client!).
+    Services = Data.define(:hooks, :tools, :reminder_store, :muted_memory_names, :question_handler, :peers, :gate,
+                           :warmup, :generation_guard) do
+      # A bare kernel's (specs, a kernel built without its Engine): the
+      # built-in tools and nothing else, or the +fields+ given.
+      # @return [Services]
+      def self.none(**fields)
+        new(hooks: nil, tools: Tools::Builtins.default, reminder_store: nil, muted_memory_names: nil,
+            question_handler: nil, peers: nil, gate: nil, warmup: nil, generation_guard: nil).with(**fields)
+      end
+    end
+
+    # @param services [Services, nil] what the kernel holds of its Engine
+    #   (Services.none by default: the built-in tools alone)
+    # @param reprefill [ReprefillMeter, nil] the re-prefill baseline its
+    #   requests count against (the Engine's, shared with its ChatLoop; its
+    #   own by default)
     # @param sleeper [#call, nil] waits the given seconds before a dropped
     #   stream's step is asked again (specs pass one that doesn't sleep)
-    def initialize(client: nil, profile: nil, model_name: nil, hooks: nil, reminder_store: nil, model_key: nil, tools: nil,
-                   sleeper: nil)
+    def initialize(client: nil, profile: nil, model_name: nil, model_key: nil, services: nil, reprefill: nil, sleeper: nil)
       @client = client || Client.new
       @sleeper = sleeper || ->(seconds) { sleep(seconds) }
-      @tools = tools || Tools::Builtins.default
+      @services = services || Services.none
+      @reprefill = reprefill || ReprefillMeter.new
       resolved_model_name = ModelProfile.required_model_name(model_name)
-      # The turn's settings (LLM::TurnSettings). Its model name is the
-      # resolved model id actually used for this run (per-run override wins
-      # over the config alias); on every debug dump so we can see exactly
-      # which model each request went to. The Engine sets them per turn:
-      # the chat loop dispatches tools here without going through #run.
-      @turn_settings = LLM::TurnSettings.none.with(model_name: resolved_model_name)
+      # The context of the run in progress, else of the last run (#context):
+      # a kernel that ran none has its own (no turn, no settings but its
+      # model name, its model key). #run takes the one it is given.
+      @context = TurnContext.none(settings: LLM::TurnSettings.none.with(model_name: resolved_model_name),
+                                  model_key: model_key)
       @profile = profile ? ModelProfile.normalize(profile) : ModelProfile.from_model_name(resolved_model_name)
       # Where @profile came from, as /stats shows it (a Resolution's label
       # once the Engine resolves one, see #use_profile!).
       @profile_source = profile ? "given" : "name"
-      @hooks = hooks
-      @reminder_store = reminder_store
-      @model_key = model_key
-      @model_key_fallback = nil
     end
 
-    # @return [ReminderStore, nil] the reminder store the reminder tools
-    #   write; the Engine's own (it hands it to a kernel it was given).
-    attr_accessor :reminder_store
+    # @return [Services] what the kernel holds of its Engine (#attach)
+    attr_reader :services
+
+    # Hand the kernel its Engine's services, all at once, and its
+    # re-prefill meter (nil keeps the one it has): the Engine does for a
+    # kernel it is given (specs) what KernelLoop.new does for its own.
+    # @param services [Services]
+    # @param reprefill [ReprefillMeter, nil]
+    # @return [Services]
+    def attach(services, reprefill: nil)
+      @reprefill = reprefill if reprefill
+      @services = services
+    end
+
+    # @return [Hooks::Registry, nil] the hooks the loop fires (Services#hooks)
+    def hooks = @services.hooks
+    # @return [Tools::Registry] the tools #dispatch runs (Services#tools)
+    def tools = @services.tools
+    # @return [ReminderStore, nil] the store the reminder tools write
+    #   (Services#reminder_store)
+    def reminder_store = @services.reminder_store
+    # @return [Guardrails::Gate, nil] the gate ToolRunner asks before each
+    #   call (Services#gate)
+    def guardrail_gate = @services.gate
 
     # @return [Float, nil] the last counted request's chars per token
     #   (ContextStatus#counted_chars_per_token), for the next turn's first
@@ -162,79 +228,43 @@ module Samagotchi
     # @return [ModelProfile] the active prompt profile
     attr_reader :profile
 
-    # @return [Samagotchi::Hooks::Registry, nil] hooks registry shared with Engine.
-    #   Engine owns the registry; KernelLoop only fires events. Accessor allows
-    #   Engine to hand its registry to a kernel it is given (specs).
-    attr_accessor :hooks
-    # @return [Tools::Registry] the tools #dispatch runs. The Engine sets
-    #   its own on a kernel it is given, as with hooks.
-    attr_accessor :tools
-    attr_accessor :client, :model_key
-    # @return [String, nil] the key whose overlay memory_read takes when
-    #   #model_key has none (#sync_model_key!)
-    attr_reader :model_key_fallback
-    # @return [Array<String>, nil] the session's muted memories (normalized
-    #   names, see MutedMemories); memory_read refuses them. The Engine sets it.
-    attr_accessor :muted_memory_names
-    # @return [Proc, nil] answers ask_user_question (payload → answer string);
-    #   Engine sets it to its blocking request_question.
-    attr_accessor :question_handler
-    # The Guardrails::Gate ToolRunner asks before each call; the Engine sets
-    # it (nil: ToolRunner's own, hooks only).
-    attr_accessor :guardrail_gate
-    # Whether the current turn belongs to a participant, so pre-gate
-    # refusals can defer to ReviewBoundary.
-    attr_accessor :participant_turn
-    # The running participant turn's mode (a callable → :pair, :review or
-    # nil: GuardrailWiring#turn_mode): ToolRunner reads it. The Engine sets it.
-    attr_accessor :participant_mode
-    # Called before each generation, before the before_generation hook (a
-    # callable, nil: none): the Engine's check that may stop the turn (a
-    # pair turn past its participant's cap, Engine#guard_participant_spend).
-    attr_accessor :generation_guard
-
-    # The generation guard, if any; one that raises never breaks the turn.
+    # The model client; a model switch swaps it (Engine#sync_kernel_client!).
+    attr_accessor :client
+
+    # @return [String, nil] the model key a kernel was built with (its own
+    #   #context's, for a run given none)
+    def model_key = @context.model_key
+
     # The model's context window as this loop knows it (ContextWindow.resolve
-    # on the client and the turn's setting): ToolRunner halves it for
-    # memory_read's overflow guard. nil when it can't be read.
+    # on the client and +settings+, a turn's LLM::TurnSettings): ToolRunner
+    # halves it for memory_read's overflow guard. nil when it can't be read.
     # @return [ContextWindow::Resolved, nil]
-    def tool_output_window
+    def tool_output_window(settings = turn_settings)
       Degrade.call(:model, "context_window_unresolved") do
-        ContextWindow.resolve(client: @client, model: @turn_settings&.model_name, setting: @turn_settings&.window_setting)
+        ContextWindow.resolve(client: @client, model: settings&.model_name, setting: settings&.window_setting)
       end
     end
 
-    def guard_generation
-      @generation_guard&.call
+    # The generation guard for +context+'s turn, if any; one that raises
+    # never breaks the turn.
+    def guard_generation(context = @context)
+      @services.generation_guard&.call(context)
     rescue StandardError => e
       Log.warn(:turn, "generation_guard_failed", error: "#{e.class}: #{e.message}")
       nil
     end
 
-    def participant_turn? = @participant_turn&.call == true
-    # @return [LLM::TurnSettings] the turn's vision, sampling, thinking and
-    #   model name, set by the Engine per turn (#run sets the model name
-    #   too); the thinking level is its own field, since the native path
-    #   sends the sampling as is.
-    attr_accessor :turn_settings
-    # The session's working directory (a callable → String or nil), which
-    # a plugin tool's row refs resolve their files against (ToolRunner,
-    # RowRefs); the Engine sets it. nil: the process's own (Dir.pwd).
-    attr_accessor :session_cwd
-    # The session's working-set pins (a callable → Array<WorkingSetPin>),
-    # which forget_outputs refuses (LLMContextForget); the Engine sets it.
-    # nil: none.
-    attr_accessor :working_set_pins
-    # The session's folder (a callable → String or nil), where ToolRunner
-    # saves a cut output whole (ToolOutputFiles); the Engine sets it. nil:
-    # none (a bare kernel), the cut says the output wasn't saved.
-    attr_accessor :session_dir
-    # Tools::Peers (or the Engine's live view of it): the session
-    # list_sessions and send_note speak for; nil outside a session.
-    attr_accessor :peers
-    # The Engine's PromptWarmup: a request asks it for a slot pin
-    # (#take_pin) while the turn-end warm-up still runs; nil: never pinned.
-    attr_accessor :warmup
+    # @return [TurnContext] the context of the run in progress, else of the
+    #   last run (the kernel's own before any): its turn's settings,
+    #   session folders and participant mode. Read on the turn's thread
+    #   only; another thread reads the Engine's (Engine#turn_context).
+    attr_reader :context
+
+    # @return [LLM::TurnSettings] the vision, sampling, thinking and model
+    #   name of the run in progress, else of the last one (#context's; #run
+    #   sets the model name); the thinking level is its own field, since the
+    #   native path sends the sampling as is.
+    def turn_settings = @context.settings
     # The turn a forget_outputs call works on (LLMContextForget::Turn: its
     # conversation and ContextStatus); both loops set it as a turn starts.
     attr_accessor :llm_context_turn
@@ -265,13 +295,17 @@ module Samagotchi
     #   run it resumes started in +messages+; that run's model messages keep
     #   their thought blocks (#prepare_conversation), as within one run. nil:
     #   every earlier thought is stripped.
+    # @param context [TurnContext] the run's turn (Engine#generate's); a
+    #   bare kernel's own (#own_context) by default. Its settings take the
+    #   run's model name: this run's own copy, never published.
     # @return [LLM::ModelResult] final visible response with continuation metadata
     def run(messages, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil, model_name: nil, max_tool_output_chars: nil, pending_input: nil,
-            reasoning_since: nil)
-      @turn_settings = @turn_settings.with(model_name: completion_model_name(model_name))
+            reasoning_since: nil, context: own_context)
+      settings = context.settings || LLM::TurnSettings.none
+      @context = context.with(settings: settings.with(model_name: completion_model_name(model_name)))
       @last_slot = nil
       turn = start_turn(messages, on_stream_event: on_stream_event, cancel_controller: cancel_controller,
-                                  pending_input: pending_input, cap: resolve_output_char_cap(max_tool_output_chars),
+                                  pending_input: pending_input, cap: ToolOutputCut.max_chars(max_tool_output_chars),
                                   reasoning_since: reasoning_since)
 
       max_iterations.times do |iteration_index|
@@ -304,28 +338,6 @@ module Samagotchi
       @profile_source = resolution.label
     end
 
-    # @param fallback [String, nil] a key whose overlay memory_read takes
-    #   when +key+ has none (the alias a model was typed as)
-    def sync_model_key!(key, fallback: nil)
-      @model_key = key
-      @model_key_fallback = fallback
-    end
-
-    # Resolve the per-output character cap for the tool outputs the model
-    # gets back and the emitted tool call events.
-    #
-    # Precedence: an explicit override wins, then max_tool_output_chars
-    # (Config). A non-positive value falls back to
-    # DEFAULT_MAX_TOOL_OUTPUT_CHARS (there is intentionally no "unlimited" — live UIs get a
-    # bounded `output:` plus a truthful `output_truncated:` flag). The one
-    # exception is memory_read, which ToolRunner leaves out of this cap
-    # (memory.read_max_chars, 0: no fixed cap; a memory is read whole).
-    # Class-level so the chat loop resolves it the same way.
-    def self.resolve_output_char_cap(override)
-      parsed = (override || Samagotchi::Config.get("max_tool_output_chars")).to_i
-      parsed.positive? ? parsed : DEFAULT_MAX_TOOL_OUTPUT_CHARS
-    end
-
     private
 
     # ── One turn (#run) ────────────────────────────────────────────────────────
@@ -354,10 +366,11 @@ module Samagotchi
 
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:, reasoning_since: nil)
       conversation = prepare_conversation(messages, keep_thought_from: ReasoningHistory.run_start(messages, reasoning_since))
-      context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context,
+      context = ContextStatus.new(conversation: conversation, llm_context: turn_settings.llm_context,
                                   counted_chars_per_token: @counted_chars_per_token)
       emit = ->(event) { emit_stream_event(on_stream_event, event) }
-      @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context, emit: emit)
+      @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context, emit: emit,
+                                                     turn_id: @context.id)
       Turn.new(
         conversation: conversation, context: context,
         empty_retry: EmptyAnswerRetry.new, empty_steps: [], tool_activity: [], buffer: +"", streamed_thinking: +"",
@@ -366,8 +379,8 @@ module Samagotchi
         # answers at once; on, an open one where the server's template has
         # it. Kept in the turn's model messages, so each tool-loop prompt
         # starts with what the server already has cached.
-        prefill: native_prefill(@turn_settings.thinking || Thinking::DEFAULT),
-        pending_tool_calls: false, model_name: @turn_settings.model_name, pending_input: pending_input,
+        prefill: native_prefill(turn_settings.thinking || Thinking::DEFAULT),
+        pending_tool_calls: false, model_name: turn_settings.model_name, pending_input: pending_input,
         on_stream_event: on_stream_event, cancel_controller: cancel_controller, cap: cap,
         emit: emit
       )
@@ -385,7 +398,7 @@ module Samagotchi
 
     def model_props
       Degrade.call(:model, "server_props_unreadable") do
-        @client.respond_to?(:server_props) ? @client.server_props(model: @turn_settings.model_name) : nil
+        @client.respond_to?(:server_props) ? @client.server_props(model: turn_settings.model_name) : nil
       end
     end
 
@@ -435,7 +448,7 @@ module Samagotchi
       apply_llm_context!(turn.conversation, context: turn.context, emit: turn.emit)
       prompt, images = format_prompt(turn)
       image_tokens = images.empty? ? 0 : ImagePlan.estimated_tokens(turn.conversation)
-      window = ContextWindow.resolve(client: @client, model: turn.model_name, setting: @turn_settings.window_setting)
+      window = ContextWindow.resolve(client: @client, model: turn.model_name, setting: turn_settings.window_setting)
       emit_context_status_event(turn.on_stream_event, turn.context, prompt, iteration_index: turn.iteration - 1,
                                                                              window: window, image_tokens: image_tokens)
       if (line = turn.context.take_guidance)
@@ -450,7 +463,7 @@ module Samagotchi
 
     def format_prompt(turn)
       Prompt.format_with_images(llm_context_view.messages(turn.conversation), profile: @profile,
-                                                                             vision: @turn_settings.vision, prefill: turn.prefill)
+                                                                             vision: turn_settings.vision, prefill: turn.prefill)
     end
 
     # One streamed request, under the generation's own controller: a
@@ -460,8 +473,8 @@ module Samagotchi
     def generate(turn, request)
       # Before the generation starts: a hook that waits (a question) isn't
       # the generation's time, and a Stop there leaves none started.
-      guard_generation
-      fire_hook(:before_generation, { type: :before_generation, iteration: turn.iteration }) if @hooks
+      guard_generation(@context)
+      fire_hook(:before_generation, { type: :before_generation, iteration: turn.iteration }) if hooks
       raise Client::RequestCancelled, turn.cancel_controller.reason if turn.cancel_controller&.cancelled?
 
       # Each ask splits its own stream (run_generation rebuilds the
@@ -469,7 +482,7 @@ module Samagotchi
       # leave the next one "inside" it.
       emit(turn, type: :generation_started, iteration: turn.iteration, context_window_tokens: request.window.tokens,
                  context_window_source: request.window.source, profile: @profile.name, profile_source: @profile_source,
-                 price: @turn_settings.price&.to_h)
+                 price: turn_settings.price&.to_h)
       # This generation's own server counts (the run-long ones in the
       # context tracker can be an earlier one's), and the thinking it
       # streamed, for the log (a stuck thinking generation shows as
@@ -505,7 +518,7 @@ module Samagotchi
       # The empty-retry sampling is taken once, before the ask-again loop:
       # a drop's restart must still carry the nudge's 0.6 (as ChatLoop does
       # per step), not lose it when request_sampling is asked again.
-      sampling = turn.empty_retry.request_sampling(@turn_settings.sampling)
+      sampling = turn.empty_retry.request_sampling(turn_settings.sampling)
       count = LLM::StreamDrops::DropCount.new(0, 0)
       begin
         # Each ask splits its own stream: a drop mid tool call (or mid
@@ -639,7 +652,7 @@ module Samagotchi
     def cache_fields(cache) = cache ? TokenUsage.cache_fields(**cache) : {}
 
     def reprefill_field(model, cache)
-      tokens = cache && reprefilled_tokens(model, prompt: cache[:prompt], cached: cache[:cached])
+      tokens = cache && @reprefill.tokens(model, client: @client, prompt: cache[:prompt], cached: cache[:cached])
       tokens ? { reprefill_tokens: tokens } : {}
     end
 
@@ -666,7 +679,7 @@ module Samagotchi
       dump_log("response", generation.response, iteration: turn.iteration)
       # The after_generation hook (after the model returns, before the tool
       # parse), with a read-only copy of the conversation as sent.
-      return unless @hooks
+      return unless hooks
 
       fire_hook(:after_generation, { type: :after_generation, iteration: turn.iteration, response: generation.response,
                                      messages: AnswerDisplay.strip_all(turn.conversation).map(&:dup).freeze })
@@ -780,7 +793,7 @@ module Samagotchi
       turn.qwen_partial = nil
       runs = []
       begin
-        ToolResponse.run_batch(tool_runner, calls, iteration: turn.iteration, emit: turn.emit,
+        ToolResponse.run_batch(tool_runner, calls, context: @context, iteration: turn.iteration, emit: turn.emit,
                                                    on_stream_event: turn.on_stream_event, cap: turn.cap) { |run, _| runs << run }
       rescue Interrupt
         # A Ctrl-C mid-batch: the entry still answers every call (the
@@ -848,29 +861,21 @@ module Samagotchi
     end
 
     def fire_hook(name, event)
-      return unless @hooks
+      return unless hooks
 
       # A failing hook must not break the turn.
-      Degrade.call(:hooks, "hook_fire_failed", hook: name) { @hooks.fire(name, event) }
+      Degrade.call(:hooks, "hook_fire_failed", hook: name) { hooks.fire(name, event) }
     end
 
     # Coerce a value to boolean — handles true/false, nil, and string "true"/"false".
     def truthy?(val) = Tools::Builtins.truthy?(val)
 
-    def tool_context = @tool_context ||= ToolContext.new(self)
-
-    # ── Output char cap resolution ─────────────────────────────────────────────
-
-    def resolve_output_char_cap(override)
-      self.class.resolve_output_char_cap(override)
-    end
-
     # One request, cancelled by +generation_controller+ (the turn's child)
     # when there is one.
     def request_generation(prompt, generation_controller:, cancel_controller:, **)
       kwargs = complete_kwargs(cancel_controller: generation_controller || cancel_controller, **)
       # Behind a turn-end warm-up still running on its slot (PromptWarmup).
-      slot = @warmup&.take_pin(@client)
+      slot = @services.warmup&.take_pin(@client)
       kwargs[:slot] = slot if slot
       @client.complete(prompt, **kwargs)
     end
@@ -940,10 +945,10 @@ module Samagotchi
 
     # A payload dump (model response, tool call/result, context status): the
     # debug level only, tagged with the model it came from.
-    def dump_log(event, payload, **fields)
+    def dump_log(event, payload, model: turn_settings.model_name, **fields)
       return unless Log.level?(:debug)
 
-      Log.debug(:model, event, payload: payload, model: @turn_settings.model_name, **fields)
+      Log.debug(:model, event, payload: payload, model: model, **fields)
     end
 
     # Estimate context usage for this iteration's prompt (ContextStatus#observe)
@@ -971,12 +976,14 @@ module Samagotchi
     # for the model the next turn runs on, after a /model switch too),
     # else the last turn's. Returns [prompt, images], or nil when the cut
     # isn't found.
-    def warmup_prompt(messages, llm_context: @turn_settings&.llm_context)
+    # +vision+: the next turn's VisionContext (the last turn's settings'),
+    # else the last run's.
+    def warmup_prompt(messages, llm_context: turn_settings&.llm_context, vision: turn_settings.vision)
       conversation = prepare_conversation(messages)
       apply_llm_context!(conversation, llm_context, warmup: true)
       conversation << { role: "user", content: WARMUP_CUT }
       prompt, images = Prompt.format_with_images(llm_context_view(llm_context).messages(conversation),
-                                                 profile: @profile, vision: @turn_settings.vision)
+                                                 profile: @profile, vision: vision)
       head = prompt[0, prompt.index(WARMUP_CUT) || 0]
       cut = head.rindex(user_opener)
       cut&.positive? ? [head[0, cut], images] : nil
@@ -985,119 +992,52 @@ module Samagotchi
     WARMUP_CUT = "chi-warmup-cut"
     private_constant :WARMUP_CUT
 
-    # What both loops send of the conversation (LLMContextView), under the
-    # turn's strategy (TurnSettings#llm_context, none without one), or the
-    # one given (the warm-up's, the next turn's): the prompt, the warm-up
-    # and the chat messages all format through it, so the warm-up warms
-    # the prompt the next turn sends.
-    def llm_context_view(llm_context = @turn_settings&.llm_context)
-      LLMContextView.new(strategy: llm_context&.strategy || LLMContextView::NONE)
-    end
-
-    # The turn's LLM context layers ([] under none): the tools they add
-    # (Tools::Registry#entries) are the turn's to offer and dispatch.
-    def llm_context_layers = @turn_settings&.llm_context&.active_layers || []
+    # What the native prompt and the warm-up send of the conversation
+    # (LLMContextView.for), under the turn's strategy or the one given (the
+    # warm-up's, the next turn's).
+    def llm_context_view(llm_context = turn_settings&.llm_context) = LLMContextView.for(llm_context)
 
     # The model's forget_outputs call (LLMContextForget) on the running
-    # turn, under its strategy; the apply rule runs on the turn's
-    # conversation at once, as at a request, so the result says whether the
-    # stubs go with the next request or wait for the turn's end.
+    # turn (the loop's llm_context_turn), under +context+'s strategy (the
+    # call's TurnContext); the apply rule runs on the turn's conversation at
+    # once, as at a request, so the result says whether the stubs go with
+    # the next request or wait for the turn's end.
     # @return [String] the tool result
-    def forget_outputs(call)
-      llm_context = @turn_settings&.llm_context
+    def forget_outputs(call, context)
+      llm_context = context.settings&.llm_context
       turn = @llm_context_turn
       unless turn && llm_context&.active_layers&.include?(:forget)
         return "Error: forget_outputs is off (the llm_context strategy has no forget layer)"
       end
 
-      apply = -> { apply_llm_context!(turn.conversation, llm_context, context: turn.context, emit: turn.emit) }
-      LLMContextForget.call(turn, call, llm_context: llm_context, apply: apply, pinned: method(:pinned_ids))
+      apply = lambda {
+        apply_llm_context!(turn.conversation, llm_context, context: turn.context, emit: turn.emit,
+                                                           model: context.settings.model_name)
+      }
+      LLMContextForget.call(turn, call, llm_context: llm_context, apply: apply,
+                                        pinned: ->(conversation) { pinned_ids(conversation, context) })
     end
 
-    # The ids of +conversation+'s outputs the session's pins hold.
-    def pinned_ids(conversation)
-      pins = Array(@working_set_pins&.call)
-      WorkingSet.pinned_ids(conversation, pins: pins, cwd: @session_cwd&.call)
+    # The ids of +conversation+'s outputs the session's pins hold (the
+    # working-set pins of +context+'s session, read now).
+    def pinned_ids(conversation, context)
+      WorkingSet.pinned_ids(conversation, pins: context.working_set_pins, cwd: context.cwd)
     end
     private :pinned_ids
 
-    # Before each request of both loops (+moment+ :request; the warm-up
-    # too, on its own copy, as the next turn's first request) and at the
-    # end of a turn the model answered (:turn_end): the strategy's layers
-    # stage their edits on +conversation+ and the apply rule
-    # (LLMContextApply, llm_context.apply) saves the batch it lets through
-    # as applied, so the request about to be sent (or the next turn's
-    # first, and the warm-up) is the first with the stubs. +context+: the
-    # turn's ContextStatus (payoff applies in its top bucket; an applied
-    # batch rebases its estimate, ContextStatus#edited!). none changes
-    # nothing. Logged as llm_context_apply when a batch is applied, and
-    # shown to the user as a ✂ row (+emit+ takes the :llm_context_edited
-    # event, LLMContextNotice; the warm-up's own copy has none).
+    # The strategy's edits on +conversation+ (LLMContextApply.apply!), under
+    # the turn's strategy and model name by default: the native run's
+    # requests and turn end, the warm-up's copy, a forget_outputs call.
     # @return [LLMContextApply::Outcome]
-    def apply_llm_context!(conversation, llm_context = @turn_settings&.llm_context, moment: :request, context: nil,
-                           warmup: false, emit: nil)
-      view = llm_context_view(llm_context)
-      return LLMContextApply::Outcome.none if view.none?
-
-      outcome = LLMContextApply.run!(conversation, layers: view.layers, rule: llm_context.apply, moment: moment,
-                                                   protect_steps: llm_context.protect_steps,
-                                                   top_bucket: context&.top_bucket? || false,
-                                                   changes: llm_context.stale_edits)
-      if outcome.applied?
-        # The prompt just shrank: the context estimate counts from it.
-        context&.edited!
-        unless warmup
-          log_llm_context(outcome, llm_context, moment)
-          emit_llm_context(emit, conversation, outcome, moment) if emit
-        end
-      end
-      outcome
-    end
-
-    def log_llm_context(outcome, llm_context, moment)
-      Log.info(:model, "llm_context_apply", rule: llm_context.apply, at: moment, why: outcome.why,
-                                            applied: outcome.applied.size, ids: outcome.applied.map(&:id).join(","),
-                                            staged: outcome.staged, freed: (outcome.freed_chars / TokenUsage::CHARS_PER_TOKEN).ceil,
-                                            tail: (outcome.tail_chars / TokenUsage::CHARS_PER_TOKEN).ceil,
-                                            model: @turn_settings&.model_name)
-    end
-    private :log_llm_context
-
-    # The batch's ✂ row; a row that can't be built never breaks the turn.
-    def emit_llm_context(emit, conversation, outcome, moment)
-      emit.call(LLMContextNotice.event(conversation, outcome, moment: moment))
-    rescue StandardError => e
-      Log.warn(:model, "llm_context_notice_failed", error: e.class.name, message: e.message)
-    end
-    private :emit_llm_context
-
-    # A request's re-prefilled tokens, for both loops: of the prompt the
-    # last request on +model+ through this client (the host) sent (this
-    # kernel's, any turn), what the server didn't reuse from its cache this
-    # time (that prompt less +cached+), so an LLM context edit's cache break
-    # shows, and so does anything else that rewrote the prompt's middle or
-    # lost the cache. nil under TokenUsage::REPREFILL_MIN_TOKENS (a cache
-    # block's rounding), for a server that reports no cached count (or 0: a
-    # cold cache isn't told from no cache), the first request, a model
-    # switch (another bare model, or the same one on another host: the
-    # Engine points #client at the new host's; SessionMetrics counts that
-    # prefill as the switch's), and the first request after a warm-up
-    # (#warmed_up!).
-    # @return [Integer, nil]
-    def reprefilled_tokens(model, prompt:, cached:)
-      previous = @reprefill_baseline
-      @reprefill_baseline = { model: model, client: @client, prompt: prompt.to_i } if prompt.to_i.positive?
-      return nil unless previous && previous[:model] == model && previous[:client].equal?(@client) && cached.to_i.positive?
-
-      tokens = previous[:prompt] - cached.to_i
-      tokens >= TokenUsage::REPREFILL_MIN_TOKENS ? tokens : nil
+    def apply_llm_context!(conversation, llm_context = turn_settings&.llm_context, model: turn_settings&.model_name, **)
+      LLMContextApply.apply!(conversation, llm_context, model: model, **)
     end
 
     # The Engine started a turn-end warm-up: it prefills the next prompt
     # off the clock, so the next request's cache counts are against it, not
-    # the last request (#reprefilled_tokens starts over).
+    # the last request (the re-prefill meter starts over, ReprefillMeter#reset!).
     def warmed_up!
-      @reprefill_baseline = nil
+      @reprefill.reset!
     end
 
     # Public wrapper so other loops (e.g. the chat loop) can strip
@@ -1188,78 +1128,40 @@ module Samagotchi
     # unknown-tool handling, and activity events are shared, not duplicated. Callers
     # are responsible for normalizing the provider's native call into this shape
     # first (see Samagotchi::LLM::NativeToolNormalizer); dispatch itself never
-    # parses provider text.
-    def dispatch_tool_call(call)
-      dispatch(call)
+    # parses provider text. +context+: the call's turn (TurnContext: its
+    # ToolSurface, the handler's ToolContext); a bare kernel's own
+    # (#own_context) by default.
+    def dispatch_tool_call(call, context = own_context)
+      dispatch(call, context)
     end
 
-    private
-
-    # Shell-like names (the harness's is `execute`). The unknown-tool error
-    # never echoes the name the model used — a model that sees its own wrong
-    # name again calls it again (a steer that named `bash` raised one model's
-    # bash rate from 9% to 30%); the activity event and the logs keep it.
-    SHELL_LIKE_TOOL_NAMES = %w[
-      bash sh zsh shell terminal cmd command run run_command run_shell exec execute_command
-    ].freeze
-
-    # The error an unknown tool name gets back. A shell-like name with
-    # `execute` offered this turn points at `execute`; every other unknown
-    # name lists what is offered. Neither echoes the wrong name.
-    #
-    # A tool the session's toolkit leaves out is a real one, so its error
-    # does name it (deliberately, against the rule above): the model learns
-    # it exists, and how to reach it (call_tool, when the toolkit reaches
-    # it that way) or that only the user can load it. A call reached
-    # through call_tool (+via+) of a tool the toolkit declares is told to
-    # call it directly: the model's call_tool(tool: "chi/read") with read
-    # declared, or a hook's rewrite (a direct call can't carry via:).
-    # The built-in +name+ names when the turn's host loads tools and the
-    # toolkit reaches it (Registry#indexed): a direct call runs it.
-    def loaded_entry(name)
-      return nil unless @turn_settings&.loads_tools && @tools.respond_to?(:indexed)
-
-      @tools.indexed(name, layers: llm_context_layers)
-    end
+    # The context a bare kernel (no Engine: a spec, a bench) runs in when
+    # given none: #context, with a Tools::ToolSurface built now from the
+    # kernel's tools when it has none (Tools::ToolSurface.bare). An
+    # Engine's turn always hands its own down (Engine#generate's surface).
+    # @return [TurnContext]
+    def own_context = Tools::ToolSurface.bare(@context, tools)
 
-    def unknown_tool_error(name, layers, via: nil)
-      names = @tools.names(layers: layers)
-      toolkit = @tools.toolkit&.name
-      in_toolkit = " in this session#{" (toolkit #{toolkit})" if toolkit}"
-      if via && @tools.offered(name, layers: layers)
-        "Error: #{name} is declared#{in_toolkit}; call it directly. Available: #{names.join(", ")}"
-      elsif !via && @tools.respond_to?(:indexed) && @tools.indexed(name, layers: layers)
-        "Error: #{name} isn't declared#{in_toolkit}; call it with #{Tools::BuiltinCalls::VIA}(tool: \"chi/#{name}\", args: {…}) " \
-          "(find_tools gives its inputSchema). Available: #{names.join(", ")}"
-      elsif @tools.respond_to?(:left_out) && @tools.left_out(name, layers: layers)
-        "Error: #{name} isn't loaded#{in_toolkit} and can't be loaded from " \
-          "here; only the user can (/toolkit add #{name}). Available: #{names.join(", ")}"
-      elsif SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
-        "Error: no such tool. Shell commands run with `execute` (same arguments)."
-      else
-        "Error: no such tool. Available: #{names.join(", ")}"
-      end
-    end
+    private
 
-    def dispatch(call)
-      # A built-in reached through call_tool runs only while the toolkit
-      # reaches it that way (Registry#indexed); any other call by its name,
-      # on a host that loads tools (TurnSettings#loads_tools) a reachable
-      # one too.
-      entry = if call[:via]
-                @tools.respond_to?(:indexed) ? @tools.indexed(call[:name], layers: llm_context_layers) : nil
-              else
-                @tools.offered(call[:name], layers: llm_context_layers) || loaded_entry(call[:name])
-              end
+    # The call runs on the entry the turn's surface gives it
+    # (Tools::ToolSurface#entry_for: a call_tool-reached one only while the
+    # toolkit reaches it that way, a reachable one by its name on a host
+    # that loads tools); without one it gets ToolSurface#unknown_tool_error.
+    # A context without a surface raises Tools::MissingSurface.
+    def dispatch(call, context)
+      model = context.settings&.model_name
+      surface = Tools::ToolSurface.of(context)
+      entry = surface.entry_for(call)
       unless entry
-        result = unknown_tool_error(call[:name], llm_context_layers, via: call[:via])
+        result = surface.unknown_tool_error(call[:name], via: call[:via])
         return {
           output: result,
-          activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: @tools)
+          activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: tools, surface: surface)
         }
       end
 
-      dump_log("tool_call", call[:content], tool: call[:name], path: call[:path], scope: call[:scope])
+      dump_log("tool_call", call[:content], model: model, tool: call[:name], path: call[:path], scope: call[:scope])
 
       if call[:called_as]
         # The model's spelling for a tool an alias ran (bash → execute); its
@@ -1268,12 +1170,12 @@ module Samagotchi
         Log.info(:turn, "tool_alias", name: call[:called_as], as: call[:name])
       end
 
-      result = entry.handler.call(call, tool_context)
+      result = entry.handler.call(call, ToolContext.new(self, context))
 
-      dump_log("tool_result", result, tool: call[:name])
+      dump_log("tool_result", result, model: model, tool: call[:name])
       dispatched = {
         output: "[#{call[:name]}]\n#{result}",
-        activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: @tools)
+        activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: tools, surface: surface)
       }
       # Images the tool returned (read's ImageResult, a plugin's ToolResult):
       # ToolRunner attaches them (or says why not).
@@ -1292,12 +1194,12 @@ module Samagotchi
       end
       dispatched
     rescue StandardError => e
-      dump_log("tool_error", e.message, tool: call[:name], error: e.class.name)
+      dump_log("tool_error", e.message, model: context.settings&.model_name, tool: call[:name], error: e.class.name)
       result = "Error: #{e.message}"
-      {
-        output: "[#{call[:name]}] #{result}",
-        activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: @tools)
-      }
+      # No surface (Tools::MissingSurface from ToolSurface.of): no row either,
+      # it would read the surface again.
+      activity = surface && ToolActivity.tool_activity_event(call[:name], call, result, registry: tools, surface: surface)
+      { output: "[#{call[:name]}] #{result}", activity: activity }
     end
   end
 end