samagotchi 0.152.0 → 0.154.0

data/lib/samagotchi/engine/models.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The model: its names and refs, identity and notes, /model's switch (and
+    # the context it shows after), the profile (ModelBinding's, forwarded) and
+    # the loop it runs on. Writes @client, @default_model_name,
+    # @last_context_status, @chat_backend; reads @model_binding, @host_registry,
+    # @kernel, @metrics, @prompt_builder.
+    module ModelsPart
+      # The backend for the next turn: the loop the effective model's host speaks.
+      def backend(model = effective_model)
+        backend_for(model)
+      end
+
+      # The model as given (maybe an alias; HostRegistry#resolve applies it).
+      def effective_model_name = @model_binding.choice.name
+
+      # The model as typed at start or at the last /model.
+      def typed_model_name = @model_binding.choice.typed
+
+      # The resolved ref a session stores for the effective model (ModelRef#ref:
+      # the alias applied, "host:id" when it names a host).
+      def effective_model_ref
+        model_ref_for(effective_model_name)
+      end
+
+      # The effective model as the system prompt names it (SystemPrompt::ModelIdentity):
+      # the ref, its host, the overlay key and, for a local llama.cpp host
+      # only, the model its /props names when that differs. Never a new
+      # request: only the /props answer profile resolution already cached.
+      def model_identity
+        model = effective_model
+        entry = model.entry
+        host = entry && "host #{entry.name}, #{entry.url || "#{entry.host}:#{entry.port}"}"
+        SystemPrompt::ModelIdentity.new(ref: model.ref, host: host, key: @model_binding.model_key,
+                                        served: model.prompt_served, fallback_key: @model_binding.fallback_model_key)
+      end
+
+      # The model notes for the effective model (ModelNotes): matched on its
+      # bare id and key, the session's mutes left out.
+      # @return [Array<ModelNotes::Note>]
+      def model_notes
+        ModelNotes.for(name: guardrail_model_name, key: @model_binding.model_key, fallback_key: @model_binding.fallback_model_key,
+                       muted: @muted_memory_names)
+      end
+
+      # The model notes the session's prompt carried at its last build
+      # (Session#prompt_notes): a resumed session's or a woken worker's saved
+      # ones until this process builds its prompt; a fresh session (no build
+      # yet, no messages) has none saved, so the effective model's prompt
+      # would load them: the notes #model_notes names, as without a session.
+      # The three readers (/model, /stats, the web) share this.
+      # @return [Array<PromptNote>]
+      def prompt_notes
+        return model_notes.map { |note| PromptNote.from_note(note) } unless @session
+
+        saved = @session.prompt_notes
+        return saved.dup if !@prompt_builder.prompt_notes.nil? || !saved.empty? || @session.messages.to_a.any?
+
+        model_notes.map { |note| PromptNote.from_note(note) }
+      rescue StandardError => e
+        Log.warn(:model, "prompt_notes_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        []
+      end
+
+      # Records +notes+ (ModelNotes::Note) on the session as the ones its
+      # prompt carries; saved with it.
+      def record_prompt_notes(notes)
+        @session.prompt_notes = Array(notes).map { |note| PromptNote.from_note(note) } if @session && notes
+      end
+      private :record_prompt_notes
+
+      # A failed turn's one line (the error's #summary). A host's failure
+      # under an alias says what the alias became (HostRegistry#alias_note):
+      # "host main" alone doesn't tell --model splash's user it was splash.
+      # @return [String]
+      def failure_summary(error)
+        summary = error.respond_to?(:summary) ? error.summary : error.message
+        return summary unless error.is_a?(LLM::ProviderError) && error.host
+
+        note = @host_registry.alias_note(effective_model_name)
+        note && note.end_with?("on host #{error.host}") ? "#{summary} (#{note})" : summary
+      rescue StandardError => e
+        EffectiveModel::Unresolved.fallback(:alias_note_failed, effective_model_name, e, summary)
+      end
+
+      # +name+'s resolved ref (ModelRef#ref).
+      def model_ref_for(name)
+        @host_registry.model_ref(name).ref
+      end
+
+      # The ref #switch_model! would switch +model_name+ to, checked the way it
+      # checks one (UnknownHost, MissingModel), without switching.
+      # @return [String]
+      def model_switch_ref(model_name)
+        model_ref_for(ModelProfile.check_host!(ModelProfile.required_model_name(model_name), hosts: @host_registry.entries))
+      end
+
+      # Writes the effective model to +session+: the resolved ref, and the
+      # name as typed when that differs (model_typed: an alias, for the
+      # models: lookup after a resume).
+      def store_model!(session)
+        ref = effective_model_ref
+        session.model_name = ref
+        typed = typed_model_name
+        session.model_typed = typed.to_s == ref ? nil : typed
+        session
+      end
+
+      # The effective model's key (ModelOverlay.key_for its bare name): memory
+      # overlays, guardrail rules' models:.
+      # @return [String, nil]
+      def model_key = @model_binding.model_key
+
+      # The prompt profile for the effective model (see #profile_resolution).
+      # @return [ModelProfile]
+      def profile = profile_resolution.profile
+
+      # Which profile the effective model gets and where that came from,
+      # kept with the model choice it was resolved for
+      # (ModelBinding#profile_resolution).
+      # @return [ModelProfile::Resolution]
+      def profile_resolution = @model_binding.profile_resolution
+
+      # The model id sent for +full_ref+ (its alias applied, the host prefix off).
+      def bare_model_name(full_ref)
+        @host_registry.bare_name(full_ref)
+      end
+
+      # The memory overlay keys follow the model sent (ModelBinding#sync_model_key!).
+      def sync_model_key! = @model_binding.sync_model_key!
+      private :sync_model_key!
+
+      # The effective model's bare name for the guardrails' models: rules;
+      # nil without a model name.
+      def guardrail_model_name
+        model = effective_model_name
+        name = model && bare_model_name(model)
+        name.to_s.strip.empty? ? nil : name
+      end
+
+      # Point the kernel (and a chat backend) at the effective model's host
+      # (after /model, --model, resume).
+      def sync_kernel_client!(model = effective_model)
+        @client = model.client
+        @kernel.client = model.client if @kernel.client != model.client
+        backend_for(model)
+      end
+
+      # ── Model switching ────────────────────────────────────────────────────────
+
+      # @param typed [String, nil] the name the model was typed as when
+      #   +model_name+ is a stored ref (a resumed session's model_typed)
+      # @return [String] the resolved ref the session stores (ModelRef#ref)
+      def switch_model!(model_name, persist_default: false, typed: nil)
+        # The alias is applied where the model is resolved (HostRegistry#resolve),
+        # once; checked here: an unknown host, an alias naming another host.
+        resolved = ModelProfile.check_host!(ModelProfile.required_model_name(model_name), hosts: @host_registry.entries)
+        choice = ModelChoice.new(name: resolved, typed: typed.to_s.strip.empty? ? model_name : typed.to_s.strip)
+        @model_binding.switch!(choice)
+        sync_model_key!
+        @prompt_builder.reset!
+        # The notes the new model's prompt loads at its next build, so /model,
+        # /stats and the web name them before the next turn does.
+        record_prompt_notes(model_notes) if @session
+        sync_kernel_client!
+        @client.invalidate_context_window!
+        @metrics.forget_model_reports!
+        # The last turn's ctx % was the old model's window's
+        # (#announce_switched_context! sends the new one's).
+        @last_context_status = nil
+        ref = effective_model_ref
+        if persist_default
+          ConfigFile.write_default_model!(ref)
+          @default_model_name = ref
+        end
+        ref
+      end
+
+      # After /model: how full the context is on the new model's window,
+      # before its first turn: the last turn's count (the old model's
+      # tokenizer's, replaced at the next generation) against the new model's
+      # window (EffectiveModel#context_window, ContextWindow.resolve: the
+      # running server first, one /props GET that a remote chat host is
+      # spared; else the host's cached model list; else the configured
+      # window) and the
+      # session's budget. Sent as a :context_status event (the web's ctx
+      # meter, the attached TUI's status row) with context_window_tokens, and
+      # kept for a client that joins later (#session_state_snapshot; the
+      # window in the metrics' context too, which a page counts from). A window
+      # that can't be resolved sends usage nil: the UIs clear the % until the
+      # next generation. Nothing before the session's first counted turn.
+      # +configured_only+: the configured window only, never asking a server
+      # (EffectiveModel#configured_context_window): a loaded session's (#session=).
+      # @return [Hash, nil] the event sent
+      def announce_switched_context!(configured_only: false)
+        used = @metrics.snapshot.dig(:context, :used_tokens)
+        return nil unless used.is_a?(Integer)
+
+        model = effective_model
+        window = configured_only ? model.configured_context_window : current_context_window(model)
+        display = window && saved_context_status({ used_tokens: used, window_tokens: window.tokens })
+        @last_context_status = display&.dup
+        @metrics.note_context_window(window.tokens, window.source) if window
+        usage = display && { estimated_pct: display[:est_pct], estimated_used_tokens: used, window_tokens: window.tokens,
+                             window_source: window.source.to_s, source: "switch" }
+        event = { type: :context_status, usage: usage, bucket: display&.dig(:bucket),
+                  context_window_tokens: window&.tokens, context_window_source: window&.source&.to_s }
+        @session_observer.notify(event)
+        event
+      rescue StandardError => e
+        Log.warn(:model, "switched_context_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        nil
+      end
+
+      # Whether the last turn that named its model ran on another one than
+      # the effective model; false before any (or when the ref can't be told).
+      def model_switched_since_last_turn?
+        last = @metrics.last_model_ref
+        !last.nil? && last != effective_model_ref
+      rescue StandardError => e
+        Log.warn(:model, "switch_check_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        false
+      end
+      private :model_switched_since_last_turn?
+
+      private
+
+      # Pick the loop for +model+ (EffectiveModel); the chat loop is pointed
+      # at its host's adapter (one per host, kept for its cached model list).
+      def backend_for(model)
+        return @native_backend unless model.chat?
+
+        @chat_backend_mutex.synchronize do
+          @chat_backend ||= LLM::ChatLoop.new(kernel: @kernel, stable_length: ->(text) { @prompt_builder.stable_length(text) })
+          @chat_backend.adapter = @host_registry.adapter_for(model.entry)
+          @chat_backend.session_id = session&.id
+          @chat_backend
+        end
+      end
+
+      # The window as +model+'s loop would see it (EffectiveModel#context_window).
+      def current_context_window(model) = model.context_window
+
+      # The effective model now, resolved on each call, never kept
+      # (SessionModelSettings#effective_model). Raises as HostRegistry#resolve does.
+      # @return [EffectiveModel]
+      def effective_model(choice = @model_binding.choice) = @model_settings.effective_model(choice)
+
+      # ── Prompt profile ─────────────────────────────────────────────────────────
+
+      # The profile's resolve, keep, apply and retry are ModelBinding's
+      # (#build_model_binding); these forward to it.
+      def resolve_profile(choice) = @model_binding.resolve_profile(choice)
+      def store_profile(choice, resolution) = @model_binding.store_profile(choice, resolution)
+      def apply_profile(resolution) = @model_binding.apply_profile(resolution)
+      def refresh_profile! = @model_binding.refresh_profile!
+    end
+  end
+end

data/lib/samagotchi/engine/objectives.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The session's objectives: their view announced when it changed, Check
+    # this's side request, the model's proposals kept as cards until the turn
+    # is over, System 1's audit of them (ObjectivesAudit). Writes
+    # @objectives_announced, @objectives_audit; reads @objective_proposals
+    # under @objective_proposals_mutex, @session, @side_judgments.
+    module ObjectivesPart
+      # The session's objectives as the page draws them (Objectives.view), when
+      # that differs from the last announced: after an edit (its file written,
+      # pending), once a list note is in, at a turn's end (its moves) and after
+      # a rollback. A session with no list announces nothing. It only informs:
+      # a failure is logged, never the turn's.
+      def announce_objectives(session = @session)
+        return unless session
+
+        synchronize_events do
+          view = Objectives.view(session.id, session.messages, state_dir: session_state_dir, running: live_conversation&.dup)
+          next if view.nil? || view == @objectives_announced
+
+          @objectives_announced = view
+          announce({ type: :objectives_updated, session_id: session.id, **view })
+        end
+      rescue StandardError => e
+        Log.warn(:turn, "objectives_announce_failed", error: e.class.name, msg: e.message)
+      end
+
+      # Check this (ObjectivesCheck)'s one side request. Its usage is in the
+      # session's side line. Raises as ctx.ask_model's request does.
+      # @param request [Array<Hash>] chat messages
+      # @param model [String, nil] a configured model; nil: the session's
+      # @return [String] the answer
+      def ask_objective_check(request, model:)
+        ask_side_model(request, timeout: ObjectivesCheck::TIMEOUT_SECONDS, max_tokens: ObjectivesCheck::MAX_TOKENS,
+                                cancel_controller: nil, model: model, source: ObjectivesCheck::SOURCE)
+      end
+
+      # A change the model proposes (the objectives tool), kept until the turn
+      # is over, as #context_choice's cards are: a card shown then is a quiet one, between turns, with its Apply kept
+      # over a restart (CardStore), not a running turn's that says it waits on the
+      # user. The same change twice in a turn is one card.
+      # @return [Boolean] false past Objectives::PROPOSALS_PER_TURN
+      def propose_objective(proposal)
+        @objective_proposals_mutex.synchronize do
+          next true if @objective_proposals.any? { |p| p.line == proposal.line }
+          next false if @objective_proposals.size >= Objectives::PROPOSALS_PER_TURN
+
+          @objective_proposals << proposal
+          true
+        end
+      end
+
+      def show_objective_proposals
+        drain_objective_proposals.each do |proposal|
+          id = "objectives-#{SecureRandom.hex(4)}"
+          show_card(source: Objectives::SOURCE, id: id, title: proposal.title, body: proposal.body,
+                    actions: [{ label: "Apply", command: proposal.action_line(id) },
+                              { label: "Dismiss", command: "/objectives --card #{id} dismiss" }])
+        end
+      rescue StandardError => e
+        Log.warn(:turn, "objectives_proposal_failed", error: e.class.name, msg: e.message)
+      end
+      private :show_objective_proposals
+
+      # A turn that did not complete (canceled, failed) takes its proposals
+      # off the buffer without showing them: their Apply card would sit after a
+      # turn whose `objectives propose` call is not in the history (a rollback
+      # after Ctrl-C drops it), and leaving them in the buffer would show them
+      # at the end of the next turn.
+      def discard_objective_proposals(turn)
+        dropped = drain_objective_proposals
+        Log.info(:turn, "objectives_proposals_dropped", count: dropped.size, outcome: turn.outcome.to_s) unless dropped.empty?
+      end
+      private :discard_objective_proposals
+
+      def drain_objective_proposals
+        @objective_proposals_mutex.synchronize { @objective_proposals.slice!(0..) }
+      end
+      private :drain_objective_proposals
+
+      private
+
+      # System 1 on the objectives, in audit (ObjectivesAudit): the owner's turns
+      # only, and for a message a person's: a reminder's or a delegate's prompt isn't one.
+      def audit_objectives_incoming(turn)
+        return unless turn.prompt.is_a?(String) && turn.origin.human? && OwnerPrompt.turn?(session: turn.session, author: turn.origin.author)
+
+        objectives_audit.incoming(turn.session, turn.prompt)
+      end
+      private :audit_objectives_incoming
+
+      def audit_objectives_outgoing(turn, result)
+        return unless OwnerPrompt.turn?(session: turn.session, author: turn.origin.author)
+
+        objectives_audit.outgoing(turn.session, result.text)
+      end
+      private :audit_objectives_outgoing
+
+      # With saving off nothing would come of an ask, so none is made.
+      def objectives_audit
+        @objectives_audit ||= ObjectivesAudit.new(
+          side: @side_judgments, state_dir: -> { session_state_dir },
+          client_for: lambda do |judgment, session|
+            next nil unless system_one_runs.on?
+
+            system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: ObjectivesAudit::MODE, tag: :system_one),
+                                 judgment, session)
+          end
+        )
+      end
+      private :objectives_audit
+    end
+  end
+end

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