samagotchi 0.153.0 → 0.154.1

data/lib/samagotchi/engine/participants.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The session's participants: the running turn's author, a pair turn's
+    # stop check, who came or went, the system prompt's participants line and
+    # a participant's author fields. Writes @participant_stop,
+    # @participants_line; reads @participants, @participants_watch,
+    # @guardrail_wiring.
+    module ParticipantsPart
+      # The running turn's author when a participant wrote it, else nil
+      # (ctx.turn_author, the hooks' author).
+      # @return [String, nil]
+      def turn_author = turn_running? ? @guardrail_wiring.turn_author : nil
+
+      # Whether a participant's pair turn must stop, read before each of its
+      # generations (#guard_participant_spend): author ("p:<id>") → why (their
+      # link ended, or they passed their cap), nil while it may go on. The
+      # Worker sets it (Worker#participant_turn_stop); without one (a one-shot)
+      # nothing is checked mid-turn.
+      attr_writer :participant_stop
+
+      # Before each generation (KernelLoop#generation_guard): a pair turn whose
+      # participant's link ended, or whose spend (Engine#metrics: their
+      # finished turns, this one's finished generations, their side requests)
+      # passed their cap, stops on the plugins' stop path (cost-cap's,
+      # work-cap's), with its notice. A generation's own cost is known only
+      # once it ends, so a turn can pass the cap by its last generation. The
+      # turn-start check is the Worker's (Worker#participant_refusal); a
+      # review turn only reads, and keeps to it.
+      def guard_participant_spend
+        author = turn_author
+        return if author.nil? || @participant_stop.nil?
+        return unless @guardrail_wiring.turn_mode == ParticipantMode::PAIR
+
+        reason = @participant_stop.call(author) or return
+        hook_stop_turn(reason, PARTICIPANTS_HOOK)
+      end
+      private :guard_participant_spend
+
+      # A participant joined (invited) or left (revoked, expired) since the
+      # last look: :participants_changed to the observers (ParticipantsWatch;
+      # the worker looks on its idle tick). The first look announces nobody.
+      # @return [ParticipantsWatch::Change, nil]
+      def announce_participants
+        change = @participants_watch.changes or return nil
+
+        announce(change.to_event)
+        change
+      end
+
+      # Reads the session's participants at a turn's start; the first to join,
+      # the first invited to act (a pair participant: the line's words) and
+      # the last to leave rebuild the system prompt (its participants line),
+      # once each: a turn in between sends the same prefix.
+      def refresh_participants!(session)
+        line = @participants.refresh!(session).prompt_mode(session)
+        return if line == @participants_line
+
+        @participants_line = line
+        @prompt_builder.reset!
+      end
+      private :refresh_participants!
+
+      # The author fields a message +author+ wrote carries (Steer.author_fields:
+      # author:, and author_name: from participants.json), {} for the owner.
+      # The worker's drain names a participant's merged lines with it, and
+      # its running save a participant's prompt.
+      # @param author [String, nil] a turn's or a line's author (TurnOrigin#author)
+      # @param session [Session, nil] the session it is for (the turn's)
+      def author_fields(author, session: @session)
+        return {} unless Steer.participant_author?(author)
+
+        Steer.author_fields(author, @participants.name_for(author, session: session))
+      end
+
+      # A participant's opening message keeps the rules it was delivered under
+      # (ParticipantMode), stamped before any request carries it, so its header
+      # never changes when the session's mode does.
+      def participant_mode_fields(author)
+        mode = Steer.participant_author?(author) && @guardrail_wiring.turn_mode
+        mode ? { participant_mode: mode.to_s } : {}
+      end
+    end
+  end
+end

data/lib/samagotchi/engine/plugins.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The Engine as the plugins' host: loading them (Plugin::Registries), their
+    # init tasks and staged tool sets (PluginTasks), Plugin::Host's view of
+    # the session, ctx.messages and ctx.http's cancel. Writes nothing of its
+    # own; reads @plugin_tasks, @extension_load, @hook_routes, @tools,
+    # @tool_index, @toolkit_binding, @prompt_builder, @session.
+    module PluginsPart
+      # Add a plugin's init task (Plugin::Api#init at commit); it starts with
+      # #start_init_tasks!.
+      def add_init_task(bundle:, label:, plugin_label:, provides_tools:, quiet:, timeout:, failed: nil, &)
+        @plugin_tasks.add(bundle: bundle, label: label, plugin_label: plugin_label, provides_tools: provides_tools,
+                          quiet: quiet, timeout: timeout, failed: failed, &)
+      end
+
+      # Start the init tasks not started yet, each on its own thread
+      # (PluginTasks#start!).
+      def start_init_tasks!
+        @plugin_tasks.start!
+      end
+
+      # The running init tasks a UI shows (not the quiet ones), for a UI that
+      # joins while they run (Bridge#snapshot, with the event log held).
+      # @return [Array<Hash>] {bundle:, id:, label:}
+      def init_tasks
+        @plugin_tasks.running
+      end
+
+      # Wait for the running init tasks that provide tools (PluginTasks#await).
+      # @return [Boolean] whether it waited
+      def await_init_tasks(controller = nil, on_event = nil)
+        @plugin_tasks.await(controller, on_event)
+      end
+
+      # The init task this thread runs, or nil.
+      def current_init_task = @plugin_tasks.current
+      private :current_init_task
+
+      private
+
+      def load_plugins
+        host = plugin_host
+        registries = Plugin::Registries.new(
+          commands: @command_registry, tools: @tools, hooks: @hooks,
+          context_for: lambda { |bundle, settings, label|
+            Plugin::Context.new(bundle: bundle, label: label, settings: settings, host: host)
+          },
+          tools_changed: -> { tools_changed! },
+          services: @services,
+          stage_tools: ->(bundle, specs, context) { stage_tools(bundle, specs, context) },
+          init: lambda { |bundle, label, plugin_label, provides_tools:, quiet:, timeout:, failed: nil, &block|
+            add_init_task(bundle: bundle, label: label, plugin_label: plugin_label, provides_tools: provides_tools,
+                          quiet: quiet, timeout: timeout, failed: failed, &block)
+          },
+          toolkits: @toolkit_binding.plugin_kits,
+          tool_index: @tool_index,
+          peer_sources: @peer_sources,
+          prompt_sections: @prompt_sections,
+          prompt_changed: -> { prompt_changed! },
+          judgments: @judgments,
+          hook_failed: ->(hook, failed) { @hook_routes.plugin_hook_failed(hook, failed) }
+        )
+        # What plugins show while they load (an MCP server that didn't
+        # start) waits for the first turn, beside the load warnings: no UI
+        # is there yet, and the Engine isn't built.
+        @extension_load.load_plugins(registries, failures: @plugin_failures) do
+          warn_undeclared_judgments
+          warn_bundle_settings
+        end
+      end
+
+      # config.yml bundles: names and keys that do nothing (BundleSettingsCheck),
+      # held like the judgments' line, for the same reason. Logged by every
+      # Engine; shown by the first to find them (BundleSettingsCheck.unshown).
+      def warn_bundle_settings
+        lines = BundleSettingsCheck.warnings(@extension_load.bundle_settings)
+        lines.each { |line| Log.warn(:config, "bundle_setting_unknown", msg: line) }
+        BundleSettingsCheck.unshown(lines).each { |line| hook_notify(line, :warn, "config") }
+      end
+      private :warn_bundle_settings
+
+      # Held with the plugins' own notices, so every UI gets it: a worker's
+      # stderr goes nowhere.
+      def warn_undeclared_judgments
+        @judgments.undeclared.each do |name|
+          Log.warn(:config, "judgment_undeclared", judgment: name)
+          hook_notify("system_one.judgments.#{name}: no loaded bundle declares it, so it does nothing", :warn, "config")
+        end
+      end
+      private :warn_undeclared_judgments
+
+      # Keep a plugin's new tool set (chi.replace_tools, from any thread)
+      # for the turn thread (PluginTasks#stage_tools).
+      def stage_tools(bundle, specs, context)
+        @plugin_tasks.stage_tools(bundle, specs, context)
+      end
+      private :stage_tools
+
+      # Apply the staged tool sets, on the turn thread, before the turn's
+      # system prompt is built (PluginTasks#apply_staged_tools!). A changed
+      # set may change the chi group the search tool's description counts
+      # (a plugin tool the toolkit leaves out).
+      # @return [Boolean] whether the tools changed
+      def apply_staged_tools!
+        changed = @plugin_tasks.apply_staged_tools!
+        @tool_index.refresh! if changed
+        changed
+      end
+      public :apply_staged_tools!
+
+      # The tools changed (a plugin's chi.tools_changed!): the system prompts,
+      # which declare them, are built again on the next turn.
+      def tools_changed!
+        prompt_changed!
+      end
+
+      # A plugin's prompt section would give other text now
+      # (chi.prompt_changed!): the system prompts are built again at their
+      # next build (the next turn's start; a running turn keeps the prompt it
+      # started with). One cache restart: the plugin's command asked first
+      # (Plugin::Context#cache_confirm).
+      def prompt_changed!
+        @prompt_builder&.reset!
+      end
+      public :prompt_changed!
+
+      # What a Plugin::Context reads and calls: the session now, and the
+      # hook runtime's notify and ask_user.
+      def plugin_host
+        Plugin::Host.new(
+          session_id: -> { @session&.id },
+          cwd: -> { @session&.working_directory },
+          messages: -> { plugin_messages },
+          messages_partial: -> { turn_running? && @running_turn_messages.nil? },
+          turn_running: -> { turn_running? },
+          notify: ->(text, level, label, fallback_for: nil) { hook_notify(text, level, label, fallback_for: fallback_for) },
+          ask_user: ->(question) { hook_ask_user(question) },
+          # An init task's is its own (a Ctrl-C ends a turn, not the task).
+          cancelled: lambda {
+            (task = current_init_task) ? task.cancelled? : active_cancel_controller&.cancelled?
+          },
+          card: ->(**card) { show_card(**card) },
+          steer: ->(text, label) { steer(text, source: hook_source(label)) },
+          stop_turn: ->(reason, label) { hook_stop_turn(reason, label) },
+          stop_generation: ->(reason, label) { hook_stop_generation(reason, label) },
+          toolkit: -> { @toolkit_binding.name },
+          declared_tools: -> { toolkit_explained.declared.map(&:name) },
+          use_toolkit: ->(name) { use_toolkit(name) },
+          load_tools: ->(names, bundle) { load_tools(names, bundle) },
+          cancel_controller: ->(handler: false) { plugin_cancel_controller(handler: handler) },
+          ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil|
+            ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
+                                    model: model, source: source)
+          },
+          model_name: -> { effective_model_ref },
+          model_key: -> { @model_binding.model_key },
+          # The names a models: map looks the model up under; [] when it doesn't resolve.
+          model_names: lambda do
+            effective_model.names
+          rescue StandardError
+            []
+          end,
+          state_dir: -> { session_state_dir },
+          scratch: -> { @scratch },
+          setup: -> { SessionSetup.of(@session) },
+          # The files whose text the built system prompt holds; [] until a
+          # build and after a rebuild that drops them (SystemPrompt#prompt_files
+          # returns [] itself: the || keeps a nil builder safe).
+          prompt_files: -> { @prompt_builder&.prompt_files || [] },
+          frontend: -> { interface },
+          cost: -> { @metrics.cost },
+          usage: -> { @metrics.usage },
+          turn_author: -> { turn_author },
+          # A plugin's prompt section is in the stable part: a full re-read.
+          cache_confirm: ->(line, changed) { CacheConfirm.ask(line: line, cost: :full, changed: changed, engine: self) },
+          candidate_proposed: ->(_candidate) { judge_late_candidates },
+          judgments: -> { @judgments }
+        )
+      end
+
+      # The controller a plugin's ctx.http call without cancel: stops with
+      # (docs/plugins.md): an init task's own, else the running turn's for the
+      # turn's own work until the turn has ended (TurnState#own_controller); nil
+      # for an anytime command, a service or a thread of the plugin's.
+      def plugin_cancel_controller(handler:)
+        (task = current_init_task) ? task.cancel : @turn_state.own_controller(handler: handler)
+      end
+      private :plugin_cancel_controller
+
+      # A plugin's ctx.messages: the conversation without the system prompt
+      # (a session saved by an older chi's REPL may start with it), and,
+      # while a turn runs, the turn so far from the Bridge (plan O1). Read
+      # with the event log held, so a turn is in exactly one of the two.
+      def plugin_messages
+        synchronize_events do
+          messages = AnswerDisplay.strip_all(messages_checkpoint)
+          first = messages.first
+          messages = messages.drop(1) if first && first[:role].to_s == "system" && first[:kind].to_s.empty?
+          running = turn_running? && @running_turn_messages ? Array(@running_turn_messages.call) : []
+          messages + running
+        end
+      end
+      private :plugin_messages
+    end
+  end
+end

data/lib/samagotchi/engine/questions.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # Ask-user-question: the model's question (its :question_asked hooks),
+    # and opening, posting, answering and cancelling questions
+    # (QuestionDesk, forwarded). Reads @question_desk, @hooks, @kernel,
+    # @session.
+    module QuestionsPart
+      # ── Ask-user-question (structured qualification) ──────────────────────────
+
+      # @return [PendingQuestion, nil] the question pending now
+      def pending_question
+        @question_desk.pending
+      end
+
+      # Ask the model's question (ask_user_question): the kernel's
+      # question_handler, called on the turn thread with the payload
+      # Tools::AskUserQuestion.validate made (QuestionDesk#request), after
+      # the :question_asked hooks (QuestionAsked) gave the step its refs; a
+      # --non-interactive run has no one to ask, so they don't fire there.
+      # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
+      # @return [String] normalized answer JSON
+      def request_question(payload)
+        payload = question_asked(QuestionAsked::KIND_QUESTION, payload) unless interface == :non_interactive
+        @question_desk.request(payload)
+      end
+
+      # The :question_asked hooks for a question of the model's about to
+      # open: the fields with the asking step's refs (QuestionAsked.fire).
+      # @return [Hash]
+      def question_asked(kind, fields)
+        QuestionAsked.fire(hooks: @hooks, conversation: live_conversation, kind: kind, fields: fields,
+                           cwd: @session&.working_directory, synchronize: ->(&block) { synchronize_events(&block) },
+                           visible: ->(content) { question_step_text(content) })
+      end
+      private :question_asked
+
+      # A step's text as the asking slot shows it: the native loop's raw
+      # response without its thoughts and tool-call bodies (a chat step has
+      # neither), then the markup's tokens (OutputFormatter.strip_markup).
+      def question_step_text(content)
+        parser = @kernel.parser
+        OutputFormatter.strip_markup(parser.strip_tool_calls(parser.strip_thought(content)))
+      end
+      private :question_step_text
+
+      # Open a question for the UIs and wait for its answer
+      # (QuestionDesk#open_question: BLOCKS until answered or cancelled).
+      # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
+      #   (as a Hash or as keywords)
+      # @param watch [#call, nil] closes the question with the reason it returns
+      # @return [QuestionAnswer, Hash, String] the answer, or {error:, …}, or a
+      #   sync handler's text
+      def open_question(fields = nil, watch: nil, **more)
+        @question_desk.open_question({ **fields.to_h, **more }, watch: watch)
+      end
+
+      # Publish a standing question that blocks nobody (QuestionDesk#post: a
+      # worker's step-limit question).
+      # @return [PendingQuestion, nil] the pending question, nil while another is open
+      def post_question(fields, on_answer:, on_superseded_close: nil)
+        @question_desk.post(fields, on_answer: on_answer, on_superseded_close: on_superseded_close)
+      end
+
+      # Withdraw the standing question (QuestionDesk#withdraw).
+      # @return [Boolean]
+      def withdraw_question(reason, id: nil)
+        @question_desk.withdraw(reason, id: id)
+      end
+
+      # Answer the pending question (called from UI thread; QuestionDesk#answer).
+      # @return [QuestionAnswer]
+      def answer_question(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
+        @question_desk.answer(id: id, selected: selected, freeform: freeform, client_id: client_id,
+                              parent_agent: parent_agent)
+      end
+
+      # Mark the pending question as relayed, or clear the mark
+      # (QuestionDesk#annotate).
+      # @return [Boolean]
+      def annotate_question(id, relayed_to:, reason: nil)
+        @question_desk.annotate(id, relayed_to: relayed_to, reason: reason)
+      end
+
+      def set_question_sync_handler(&block)
+        @question_desk.sync_handler = block
+      end
+
+      # Cancel the pending question (QuestionDesk#cancel).
+      # @return [Boolean] whether it was cancelled
+      # @raise [QuestionDesk::NotDismissable] +id+ names a standing question
+      def cancel_question(reason = "user", id: nil)
+        @question_desk.cancel(reason, id: id)
+      end
+    end
+  end
+end

data/lib/samagotchi/engine/recap.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The idle recap (IdleRecap) and the shared idle scheduler: the recap job
+    # rebuilt under the bound session's own recap values, /recap's override,
+    # the saved recap. Writes @recap, @recap_awaiting_continue; reads
+    # @recap_built_for, @idle_scheduler, @session.
+    module RecapPart
+      # Snapshot the current session messages as a JSON string for the idle
+      # recap. The array is never mutated in place (a turn or a note replaces
+      # it), so the reference read here is a consistent snapshot; a dup'd
+      # copy is serialized. Never mutates session.messages.
+      # @return [String] JSON array of the messages
+      def messages_json_for_recap
+        snapshot = @session&.messages
+        return "[]" if snapshot.nil?
+
+        JSON.generate(AnswerDisplay.strip_all(snapshot).map(&:dup))
+      end
+
+      # Emit a :recap_ready event (additive slot) carrying the generated recap
+      # and the generation id an observer uses to reject an invalidated recap.
+      # +covered+ counts the session messages it summarizes; +created_at+ is
+      # the saved recap's (UTC ISO; the UIs show its local time).
+      def emit_recap(recap:, generation:, covered: nil, created_at: nil)
+        event = { type: :recap_ready, recap: recap, generation: generation, covered: covered }
+        event[:created_at] = created_at if created_at
+        @session_observer.notify(event)
+      end
+
+      # @return [IdleRecap, nil] the idle recap detector, or nil when disabled
+      attr_reader :recap
+
+      # Whether a continue offer waits (the Worker's or the one-shot's TurnFlow),
+      # for the recap job: this one and any rebuilt one (IdleRecap#awaiting_continue=).
+      def recap_awaiting_continue=(callable)
+        @recap_awaiting_continue = callable
+        @recap&.awaiting_continue = callable
+      end
+
+      # The bound session's own recap.* values ({} for none).
+      def session_recap_values
+        (@session&.settings&.core || {}).select { |key, _| key.start_with?("recap.") }
+      end
+      private :session_recap_values
+
+      # A new recap job when the bound session's own recap values differ from
+      # the ones the current job was built under (none at start): the old one
+      # is dropped (an attempt in flight goes stale) and the scheduler swaps
+      # it, keeping its one thread. Binding the same session again changes
+      # nothing.
+      def rebuild_recap!
+        return if session_recap_values == @recap_built_for
+
+        old = @recap
+        old&.invalidate!
+        @recap = build_recap
+        @idle_scheduler&.replace_job(old, @recap)
+      end
+
+      # /recap on|off|default: the bound session's own recap.enabled (true,
+      # false; nil removes it, so config.yml's applies again), and the recap
+      # job rebuilt under it at once. It doesn't save: the command says
+      # changed: [:recap] and its host saves (Worker#run_command).
+      # @param enabled [Boolean, nil]
+      # @raise [ArgumentError] no session is bound
+      def recap_override=(enabled)
+        raise ArgumentError, "no session" unless @session
+
+        core = @session.settings.core.dup
+        enabled.nil? ? core.delete(RECAP_ENABLED_KEY) : core[RECAP_ENABLED_KEY] = enabled
+        @session.settings = @session.settings.with(core: core)
+        rebuild_recap!
+      end
+
+      # The bound session's own recap.enabled (/recap on|off, --set), or nil.
+      # @return [Boolean, nil]
+      def recap_override = @session&.settings&.core&.fetch(RECAP_ENABLED_KEY, nil)
+
+      # Write the recap now, before the session is left (IdleRecap#write_now).
+      # @return [String, nil] the recap written, nil when none was (recap off,
+      #   nothing new, an error, the timeout)
+      def write_recap_now(on_start: nil)
+        @recap&.write_now(on_start: on_start)
+      end
+
+      # The longest #write_recap_now waits (recap.timeout), nil when no recap
+      # is set up.
+      # @return [Float, nil]
+      def recap_timeout = @recap&.timeout
+
+      # Ask for a recap now (/recap), without waiting for the idle window.
+      # @return [Symbol] IdleRecap#request_now's answer, or :off
+      def request_recap
+        @recap ? @recap.request_now : :off
+      end
+
+      # The recap saved with the current session (recap.json), and how many
+      # user turns came after it (0: it is current).
+      # @return [Hash, nil] {text:, covered:, turns_since:, created_at:}
+      def saved_recap
+        state = @recap&.state
+        return nil unless state
+
+        messages = @session&.messages || []
+        covered = state[:covered].to_i
+        turns_since = Array(messages).drop(covered).count { |m| Steer.turn_opening?(m) }
+        { text: state[:text], covered: covered, turns_since: turns_since, created_at: state[:created_at] }
+      end
+
+      # Start the shared idle scheduler (reminders + optional recap). The recap
+      # job is only registered when recap is configured; the reminders job is
+      # always present. SessionManager workers call it so reminders can
+      # trigger turns; a one-shot never starts it and polls nothing.
+      def start_idle
+        @idle_scheduler&.start
+        self
+      end
+
+      # Stop the shared idle scheduler (a worker as it leaves). +join+: wait for a tick under way (IdleScheduler#stop); a
+      # caller holding #synchronize_events passes false, since a recap's emit
+      # in that tick waits for the same lock.
+      def stop_idle(join: true)
+        @idle_scheduler&.stop(join: join)
+        self
+      end
+    end
+  end
+end

data/lib/samagotchi/engine/session.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The bound session and its prompt: #session= (its recap, metrics and
+    # memories), its state dir, the relay's view, and the system prompt with
+    # the memory names it holds. Writes @session, @session_state_dir,
+    # @running_turn_messages; reads @prompt_builder, @metrics, @used_memories,
+    # @question_desk, @state_dir.
+    module SessionPart
+      # @return [Array<String>] deduped used memory names (thread-safe copy)
+      def used_memory_names
+        @used_memories.names
+      end
+
+      # @return [Array<String>] the memories hidden from this session (normalized names)
+      def muted_memory_names
+        @muted_memory_names.dup
+      end
+
+      # @return [Array<String>] the names the session preloads (config baseline
+      #   + --memory, minus mutes), known before the prompt is built, unlike
+      #   #activated_memory_names
+      def preloaded_memory_names
+        @prompt_builder.preloaded_memory_names
+      end
+
+      # Where sessions live (a session's images/ are under it); a worker sets
+      # its own.
+      attr_writer :session_state_dir
+
+      # The metrics load the session's saved records from its state dir, once.
+      def bind_metrics(session)
+        return unless session&.id
+
+        @metrics.state_dir = session_state_dir
+        @metrics.session_id = session.id
+      end
+
+      def session_state_dir = @session_state_dir || Session.default_state_dir
+
+      # The running turn's metrics so far, saved as a turn a worker died in
+      # would leave them (SessionMetrics#persist's running_turn): a worker's
+      # turn checkpoint (TurnCheckpoint) calls it when it writes.
+      # @return [Boolean] whether they were saved
+      def checkpoint_metrics = @metrics.persist(state_dir: session_state_dir, running_turn: true)
+
+      # What a Bridge adds to a plugin's ctx.messages while a turn runs (the
+      # turn so far, as messages); nil without a Bridge (a one-shot).
+      attr_writer :running_turn_messages
+
+      # The system prompt for a target's loop (default: the effective model's):
+      # the chat loop's leaves out the raw-prompt tool text, since its tools go
+      # as schemas. Built once per loop (and again after a model switch) so the
+      # prompt prefix, and the server's KV cache for it, stay stable.
+      # @param model [EffectiveModel, nil]
+      # @return [String]
+      # The native prompt depends on the thinking level too (Gemma's token):
+      # a level change builds it again. A build that
+      # misses the cache names the model and the level through its own
+      # lambdas (#model_identity, #turn_thinking), which resolve again.
+      def system_prompt(model = nil)
+        model ||= effective_model
+        chat = model.chat?
+        level = chat ? nil : @model_settings.thinking_level(model)
+        prompt = @prompt_builder.build(chat: chat, thinking: level, layers: model.llm_context_layers(@model_settings.llm_context_session_args))
+        # The memory indexes this prompt holds: /stats, the snapshot, analytics.json.
+        @metrics.memory_index = @prompt_builder.memory_index
+        # The model notes it carries: the session records them (/stats, /model, the web).
+        record_prompt_notes(@prompt_builder.prompt_notes)
+        prompt
+      end
+
+      # The base prompt (specs, plugins' declarations).
+      def assist_system_prompt(chat: false)
+        @prompt_builder.base(chat: chat)
+      end
+
+      # The --memory names activated while building the prompt; the TerminalUI
+      # mirrors them into its status line.
+      def activated_memory_names
+        @prompt_builder.activated_memory_names
+      end
+
+      # @return [Session] current session (Engine owns create/resume)
+      attr_reader :session
+
+      # This worker's relays of its delegates' approvals (memory only).
+      # @return [RelayDesk]
+      attr_reader :relay_desk
+
+      # The relay's view of this Engine, or nil when it can't host a relay: a
+      # worker's Engine only (its Bridge is what a child verifies against;
+      # --non-interactive has no one to ask), never with a sync handler (no
+      # wait loop, no watch).
+      # @return [RelayPeer, nil]
+      def relay_peer
+        return nil unless interface == :worker && !@question_desk.sync_handler?
+
+        RelayPeer.new(self)
+      end
+
+      # @return [String] the state dir holding this Engine's sessions
+      def peer_state_dir = @state_dir
+
+      # Set the current session outside a turn (the worker and the one-shot
+      # do, before the first turn, so the messages API and recap see it)
+      def session=(session)
+        @session = session
+        # One session per worker or one-shot process: its records carry this sid.
+        Log.session_id = session.id if session&.id
+        # Its own recap values (chi --set recap.enabled=false) rebuild the job.
+        rebuild_recap!
+        # A woken worker's /stats and status line count the turns before it.
+        bind_metrics(session)
+        @used_memories.absorb(session)
+        # Loaded on another model than its last turn ran on (a --resume
+        # one-shot's --model, a worker woken after a /model with no turn since):
+        # the saved ctx % was that model's window's. Drop it and count it as
+        # /model does, on a configured window only: this runs before a
+        # worker's Bridge serves, so no /props GET or model list here (a slow
+        # or hung host would hold up the worker's start). No configured
+        # window: no % (ctx ?) until the first generation reports one.
+        return unless model_switched_since_last_turn?
+
+        @metrics.forget_model_reports!
+        announce_switched_context!(configured_only: true)
+      end
+    end
+  end
+end