samagotchi 0.154.1 → 0.156.0

data/lib/samagotchi/tools/tool_surface.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require_relative "builtin_calls"
+require_relative "deferred_tools"
+require_relative "registry"
+
+module Samagotchi
+  module Tools
+    # What one turn's loops see of the session's tools, as one frozen value:
+    # what the request declares, what call_tool reaches, what the toolkit
+    # leaves out (and why), and the dispatch decision for a call. Built once
+    # per turn in Engine#generate from the Registry (its only input), where
+    # the turn's LLM context layers and its host's loads_tools are known,
+    # and carried as TurnContext#surface: KernelLoop#dispatch, ChatLoop's
+    # tool_definitions/deferred_tools and ToolRunner's left-out, unwrap
+    # and refusal checks read it. A change made while the turn runs (a
+    # /toolkit change, chi.replace_tools: staged anyway) shapes the next
+    # turn's surface only. Outside a turn a caller builds one (.for): a bare
+    # kernel or loop at its own context (KernelLoop#own_context), the tool
+    # index at load and at #refresh!, the readers off the turn thread from
+    # ToolkitBinding#published.
+    #
+    # +declared+    the entries the request declares, in prompt order (Registry#entries)
+    # +index_only+  the entries the toolkit leaves out that call_tool reaches (Registry#reachable_names)
+    # +left_out+    {name => why} for every tool the toolkit leaves out (Registry#left_out_names),
+    #               in declaration order: :indexed (call_tool reaches it) or :user_only (only
+    #               /toolkit add brings it back: removed, or nothing reaches it)
+    # +removed+     the names the toolkit removes (Registry#removed_names: remove:, --no-tool,
+    #               /toolkit remove), in declaration order
+    # +stranded+    the names of the plugin tools registered after the index was declared that
+    #               the toolkit leaves out and nothing reaches (Registry#stranded_names)
+    # +registered+  {name => entry} of every registered tool, declared or not
+    # +toolkit+     the session's Toolkit::Resolved (nil: full)
+    # +reaching_kit+ group → the kit that reaches it (Registry#reaching_kit), for a refusal's hint
+    # +index+       the tool index's declaration (Registry::Index), nil without one
+    # +layers+      the turn's LLM context layers
+    # +loads_tools+ whether the turn's host loads tools (TurnSettings#loads_tools)
+    class ToolSurface < Data.define(:declared, :index_only, :left_out, :removed, :stranded, :registered, :toolkit,
+                                    :reaching_kit, :index, :layers, :loads_tools)
+      # @param registry [Registry, nil] nil: no tools at all
+      # @param layers [Array<Symbol>] the turn's LLM context layers
+      # @param loads_tools [Boolean] the turn's host's (TurnSettings#loads_tools)
+      # @param toolkit [Toolkit::Resolved, nil] the toolkit to read the
+      #   Registry under: its own (the session's) by default; another one
+      #   for what a change would declare (ToolkitBinding#explained)
+      # @return [ToolSurface]
+      def self.for(registry, layers: [], loads_tools: false, toolkit: registry&.toolkit)
+        layers = Array(layers)
+        return empty(layers, loads_tools) if registry.nil?
+
+        reachable = registry.reachable_names(layers: layers, toolkit: toolkit)
+        new(declared: registry.entries(layers: layers, toolkit: toolkit),
+            index_only: reachable.map { |name| registry[name] },
+            left_out: registry.left_out_names(layers: layers, toolkit: toolkit)
+                              .to_h { |name| [name, reachable.include?(name) ? :indexed : :user_only] },
+            removed: registry.removed_names(layers: layers, toolkit: toolkit),
+            stranded: registry.stranded_names(layers: layers, toolkit: toolkit),
+            registered: registry.registered.to_h { |entry| [entry.name, entry] },
+            toolkit: toolkit, reaching_kit: registry.reaching_kit, index: registry.index,
+            layers: layers, loads_tools: loads_tools == true)
+      end
+
+      # Its lists frozen (copies of the ones given), whichever way it is
+      # made (.for, .new, #with): no reader can change a turn's surface.
+      # The entries in them stay the Registry's own.
+      def initialize(declared:, index_only:, left_out:, registered:, layers:, removed: [], stranded: [], **)
+        super(declared: frozen_copy(Array(declared)), index_only: frozen_copy(Array(index_only)),
+              left_out: frozen_copy(left_out.to_h), removed: frozen_copy(Array(removed)),
+              stranded: frozen_copy(Array(stranded)), registered: frozen_copy(registered.to_h),
+              layers: frozen_copy(Array(layers)), **)
+      end
+
+      # The turn's surface (+context+'s: an Engine turn's, or a bare kernel's
+      # or loop's own, KernelLoop#own_context); a context without one raises
+      # MissingSurface (no reader falls back to the Registry as it is now).
+      # @param context [TurnContext]
+      # @return [ToolSurface]
+      def self.of(context) = context.surface || raise(MissingSurface)
+
+      # A bare kernel's or loop's own +context+ (no Engine turn: a spec, a
+      # bench) with a surface: its own, else one built now from +registry+
+      # under its layers and loads_tools. Only their own default context
+      # goes through here (KernelLoop#own_context, ChatLoop#turn_context);
+      # a context handed down is read as it is (.of).
+      # @param context [TurnContext]
+      # @return [TurnContext]
+      def self.bare(context, registry)
+        return context if context.surface
+
+        context.with(surface: self.for(registry, layers: context.llm_context_layers,
+                                                 loads_tools: context.settings&.loads_tools == true))
+      end
+
+      def self.empty(layers, loads_tools)
+        new(declared: [], index_only: [], left_out: {}, removed: [], stranded: [], registered: {}, toolkit: nil,
+            reaching_kit: nil, index: nil, layers: layers, loads_tools: loads_tools == true)
+      end
+      private_class_method :empty
+
+      # @return [Array<String>] the declared tools' names, in prompt order
+      def declared_names = declared.map(&:name)
+
+      # @return [Array<Hash>] the declared tools' schemas, in prompt order
+      def schemas = declared.map(&:schema)
+
+      # The declared entry +name+ names (the one a call dispatches to), nil
+      # otherwise.
+      # @return [Registry::Entry, nil]
+      def declared_entry(name) = declared.find { |entry| entry.name == name.to_s }
+
+      # The entry +name+ names when call_tool reaches it (#index_only).
+      # @return [Registry::Entry, nil]
+      def indexed_entry(name) = index_only.find { |entry| entry.name == name.to_s }
+
+      # Whether the toolkit leaves +name+'s real tool out (#left_out).
+      def left_out?(name) = left_out.key?(name.to_s)
+
+      # Whether any tool, declared or not, is registered as +name+.
+      def registered?(name) = registered.key?(name.to_s)
+
+      # The entry a call runs on, nil when it can't run in this turn: one
+      # reached through call_tool (via:) only while the toolkit reaches it
+      # that way; any other by its name when declared, or, on a host that
+      # loads tools, when call_tool reaches it.
+      # @param call [Hash] the normalized call ({name:, via:, …})
+      # @return [Registry::Entry, nil]
+      def entry_for(call)
+        name = call[:name]
+        return indexed_entry(name) if call[:via]
+
+        declared_entry(name) || (loads_tools ? indexed_entry(name) : nil)
+      end
+
+      # 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 a call #entry_for has no entry for gets back. A shell-like
+      # name with `execute` declared points at `execute`; every other unknown
+      # name lists what is declared. 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:).
+      # @return [String]
+      def unknown_tool_error(name, via: nil)
+        names = declared_names
+        in_toolkit = " in this session#{" (toolkit #{toolkit.name})" if toolkit}"
+        if via && declared_entry(name)
+          "Error: #{name} is declared#{in_toolkit}; call it directly. Available: #{names.join(", ")}"
+        elsif !via && indexed_entry(name)
+          "Error: #{name} isn't declared#{in_toolkit}; call it with #{BuiltinCalls::VIA}(tool: \"chi/#{name}\", args: {…}) " \
+            "(find_tools gives its inputSchema). Available: #{names.join(", ")}"
+        elsif left_out?(name)
+          "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
+
+      # The tools a request on a host that loads tools declares deferred,
+      # +conversation+ (the request's, engine format) naming the ones it
+      # loaded (Tools::DeferredTools.list). The index's source tools are
+      # asked now (a late MCP server joins the list mid-turn, as before).
+      # @return [Array<DeferredTools::Deferred>]
+      def deferred_for(conversation) = DeferredTools.list(self, conversation)
+
+      private
+
+      # +list+ itself when frozen, else a frozen copy (the caller's stays
+      # as it is).
+      def frozen_copy(list) = list.frozen? ? list : list.dup.freeze
+    end
+  end
+end

data/lib/samagotchi/turn_context.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "turn_origin"
+require_relative "steer"
+require_relative "guardrails/context"
+require_relative "llm/turn_settings"
+
+module Samagotchi
+  # What one turn's tool path reads of it, as one frozen value: built by
+  # Engine#begin_turn before the turn is published (TurnState#begin!),
+  # handed explicitly down the loops (ModelBackend#complete's context:,
+  # KernelLoop#run, ChatLoop#complete), ToolResponse.run_batch,
+  # ToolRunner#run, Guardrails::Gate#evaluate and KernelLoop#dispatch_tool_call
+  # (its ToolContext). Lifetime: one turn. The source of truth for the
+  # turn's id, session, origin and controller (Engine::Turn keeps only the
+  # lifecycle state and reads these from it).
+  #
+  # +id+         the turn's id (:turn_started's turn_id)
+  # +session+    the Session it runs in (live: its working-set pins are read at call time)
+  # +origin+     its TurnOrigin (TurnOrigin::NONE for the owner's)
+  # +author+     the participant's author ("p:<id>") when one wrote it, else nil
+  # +participant_mode+ a participant's turn's mode (ParticipantMode: :review, :pair), nil for the owner's
+  # +participant+ that participant's Participants::Entry (participants.json), nil for none
+  # +controller+ the turn's CancellationController (live: its cancel state); a thread
+  #   off the turn cancels through TurnState#controller, never through this
+  # +cwd+        the session's working directory (nil: the process's, Dir.pwd)
+  # +session_dir+ the session's folder (a cut tool output is saved there), nil for none
+  # +state_dir+  the sessions' state dir
+  # +git+        the turn's Guardrails::GitInfo (asked once per directory per turn)
+  # +settings+   the turn's LLM::TurnSettings: nil until Engine#generate sets them
+  # +model_key+, +fallback_model_key+ the memory overlay keys (memory_read, memory_write,
+  #   rules' models:), +model_name+ the bare model name the gate's rules match: frozen at
+  #   Engine#generate with the settings (a before_turn hook may switch the model)
+  # +surface+    the turn's Tools::ToolSurface (what its loops declare, defer and dispatch):
+  #   nil until Engine#generate builds it; a reader given none raises Tools::MissingSurface
+  #   (ToolSurface.of), a bare kernel's or loop's own context builds one (ToolSurface.bare)
+  #
+  # Only the turn thread replaces it (TurnState#replace_context), one frozen
+  # value per write; other threads read the published one (Engine#turn_context,
+  # Engine#last_turn_context).
+  TurnContext = Data.define(:id, :session, :origin, :author, :participant_mode, :participant, :controller, :cwd,
+                            :session_dir, :state_dir, :git, :settings, :model_key, :fallback_model_key, :model_name,
+                            :surface) do
+    # A context outside an Engine turn (a bare kernel, a spec, the bundle
+    # test kit's Gate): no session, the owner's, no controller, a fresh
+    # GitInfo, the settings given (LLM::TurnSettings.none by default).
+    # @return [TurnContext]
+    def self.none(**fields)
+      new(id: nil, session: nil, origin: TurnOrigin::NONE, author: nil, participant_mode: nil, participant: nil,
+          controller: nil, cwd: nil, session_dir: nil, state_dir: nil, git: Guardrails::GitInfo.new,
+          settings: LLM::TurnSettings.none, model_key: nil, fallback_model_key: nil, model_name: nil, surface: nil,
+          **fields)
+    end
+
+    # Whether a participant wrote the turn (Steer.participant_author?).
+    def participant? = Steer.participant_author?(author)
+
+    # Whether the turn's controller is cancelled (a Stop, a hook's stop_turn).
+    def cancelled? = !!controller&.cancelled?
+
+    # The turn's LLM context layers ([] without settings or a strategy): the
+    # tools they add are the turn's to offer and dispatch.
+    def llm_context_layers = settings&.llm_context&.active_layers || []
+
+    # The session's working-set pins (Session#working_set_pins), read now.
+    def working_set_pins = session.respond_to?(:working_set_pins) ? Array(session.working_set_pins) : []
+  end
+end

data/lib/samagotchi/turn_stages/context_judge.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../context_candidate_choice"
+require_relative "../context_candidates"
+require_relative "../context_candidates_log"
+require_relative "../context_judge"
+require_relative "../context_sources"
+require_relative "../log"
+require_relative "../owner_prompt"
+require_relative "../session"
+require_relative "../side_judgments"
+require_relative "../system_one/client"
+
+module Samagotchi
+  module TurnStages
+    # The attached-context candidate judge's stage (Samagotchi::ContextJudge
+    # is the judge itself; inside this class the bare name is this stage):
+    # its pass at an owner turn's start and for a late candidate, the asks it
+    # starts, and the cards an answer brought while a turn ran, shown once it
+    # has ended. Its state is those held cards, under their mutex.
+    #
+    # Its two callables are read on the asks' thread, after the call that
+    # started the asks returned (an answer comes when it comes): which
+    # session the Engine is on then, and the card shown where cards go then.
+    class ContextJudge
+      # @param side_judgments [SideJudgments] the Engine's side asks (:context kind)
+      # @param host_registry [HostRegistry] System 1's client resolves its host here
+      # @param turn_state [TurnState] whether a turn runs as an answer comes (#running?)
+      # @param show_card [#call] (**card) shows a card (Engine#show_card: EventRoutes, on the caller's thread)
+      # @param current_session [#call] the session the Engine is on as an answer comes (nil: none)
+      def initialize(side_judgments:, host_registry:, turn_state:, show_card:, current_session:)
+        @side_judgments = side_judgments
+        @host_registry = host_registry
+        @turn_state = turn_state
+        @show_card = show_card
+        @current_session = current_session
+        # On mode's cards an answer brought while a turn ran: shown once it
+        # has ended (#show_cards_after_turn).
+        @cards_after_turn = []
+        @cards_mutex = Mutex.new
+      end
+
+      # For specs: the asks' thread (SideJudgments' :context kind), nil before any.
+      def asks_thread = @side_judgments.thread(:context)
+
+      # The candidate judge at an owner turn's start, after the toolkit's
+      # ask settled: the session's candidates' status changes are logged
+      # (ContextCandidatesLog#look) and, unless context.candidates.mode is
+      # off, the proposed candidates due an ask are asked about the owner's
+      # prompts so far, this one included. Never a participant's turn, a
+      # review session or a Continue (no new prompt). The sessions dir is
+      # the turn's (TurnContext#state_dir).
+      # @param recorder [SystemOne::Recorder] the asks' runs (built for this call)
+      def start(turn, recorder:)
+        session = turn.session
+        return unless turn.prompt.is_a?(String) && OwnerPrompt.turn?(session: session, author: turn.origin.author)
+
+        pass(session, ContextCandidates.owner_texts(session.messages) + [turn.prompt], phase: "turn",
+                                                                                         state_dir: turn.context.state_dir, recorder: recorder)
+      end
+
+      # A late proposal no owner prompt mentions (Plugin::Host
+      # #candidate_proposed: github-pr's init task runs beside the first
+      # turn): judged on the owner's prompts so far, the running turn's too.
+      # The caller (Engine#judge_late_candidates) gives the session the
+      # Engine is on, never nil nor a review session.
+      # @param messages [Array<Hash>] the owner's conversation so far (Engine#plugin_messages)
+      # @param recorder [SystemOne::Recorder] the asks' runs (built for this call)
+      # @param state_dir [String] the sessions dir
+      def late_candidates(session, messages:, recorder:, state_dir:)
+        texts = ContextCandidates.owner_texts(messages)
+        pass(session, texts, phase: "late", state_dir: state_dir, recorder: recorder) unless texts.empty?
+      end
+
+      # The cards #choice held while a turn ran (Engine#run_turn's ensure,
+      # after the turn flag is released).
+      def show_cards_after_turn
+        cards = @cards_mutex.synchronize { @cards_after_turn.slice!(0..) }
+        cards.each { |card| @show_card.call(**card) }
+      rescue StandardError => e
+        Samagotchi::ContextJudge.warn(e)
+      end
+
+      private
+
+      # One look at +session+'s candidates; the asks go to SideJudgments'
+      # :context kind, one thread asking each due candidate in turn.
+      def pass(session, texts, phase:, state_dir:, recorder:)
+        return if session.id.nil? || session.scratch
+
+        rows = ContextCandidates.with_status(session.id, project_root: session.project_root, state_dir: state_dir)
+        return if rows.empty?
+
+        log = ContextCandidatesLog.log_for(state_dir)
+        records = ContextCandidatesLog.records_for(log, session.id)
+        ContextCandidatesLog.look(log, session.id, rows, records) if phase == "turn"
+        settings = Samagotchi::ContextJudge::Settings.from_config
+        return if settings.mode == "off"
+
+        jobs = Samagotchi::ContextJudge.jobs(rows, records, session_id: session.id, texts: texts, settings: settings,
+                                                            phase: phase, parent_attached: parent_attached(session, state_dir))
+        return if jobs.empty?
+
+        client = recorder.wrap(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context),
+                               Samagotchi::ContextJudge::JUDGMENT, session, mode: settings.mode)
+        return unless client
+
+        start_asks(client, jobs, log, settings, choice(session, log, settings, state_dir))
+      rescue StandardError => e
+        Samagotchi::ContextJudge.warn(e)
+      end
+
+      # @return [Thread, nil] the asks' thread, nil when none started
+      def start_asks(client, jobs, log, settings, choice)
+        if @side_judgments.in_flight?(:context)
+          Log.info(:context, "context_judge_in_flight_skipped", session_id: jobs.first.session_id)
+          return nil
+        end
+
+        @side_judgments.start(:context, warn: Samagotchi::ContextJudge.method(:warn)) do
+          jobs.each { |job| choice.call(job, Samagotchi::ContextJudge.ask(client: client, job: job, log: log, settings: settings)) }
+        end
+      end
+
+      # What an answer does on the asks' thread (ContextCandidateChoice
+      # #after_judged: on mode attaches or cards; audit nothing). Taken on
+      # the caller's thread. The attach only writes the session's folder: its
+      # note comes with the next between-turn delivery, never into a running
+      # turn. A card shows only while the Engine is still on that session,
+      # and not in a running turn (it isn't the turn's: no "waiting for you"
+      # on it), but once it has ended.
+      # @return [#call] (job, fields)
+      def choice(session, log, settings, state_dir)
+        session_id = session.id
+        project_root = session.project_root
+        show = lambda do |**card|
+          current = @current_session.call
+          next nil unless current.nil? || current.id == session_id
+
+          @cards_mutex.synchronize do
+            next @cards_after_turn << card if @turn_state.running?
+
+            @show_card.call(**card)
+          end
+        end
+        lambda do |job, fields|
+          ContextCandidateChoice.after_judged(job: job, fields: fields, settings: settings, project_root: project_root,
+                                              state_dir: state_dir, log: log, show_card: show)
+        end
+      end
+
+      # A delegate child's parent's sources, by title (else name): the
+      # judge's started_from. nil for any other session (a chi send --new
+      # session has no parent; a fork isn't a delegate).
+      def parent_attached(session, state_dir)
+        return nil unless session.delegate? && session.parent_id
+
+        parent_root = if Session.exist?(session.parent_id, state_dir: state_dir)
+                        Session.load(session.parent_id, state_dir: state_dir).project_root
+                      else
+                        session.project_root
+                      end
+        ContextSources.attached(session.parent_id, project_root: parent_root, state_dir: state_dir)
+                      .map { |attached| attached.source.title || attached.name }
+      rescue StandardError => e
+        Log.warn(:context, "context_parent_attached_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        []
+      end
+    end
+  end
+end

data/lib/samagotchi/turn_stages/objectives.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "../log"
+require_relative "../objectives"
+require_relative "../objectives_audit"
+require_relative "../owner_prompt"
+require_relative "../system_one/client"
+
+module Samagotchi
+  module TurnStages
+    # The session's objectives over a turn (Samagotchi::Objectives is the
+    # list itself; inside this class the bare name is this stage): System 1's
+    # audit of what comes in at a turn's start and what goes out at its end
+    # (ObjectivesAudit), the view announced when it changed, and the model's
+    # proposals kept as cards until the turn is over. Its state is those
+    # proposals under their mutex and the last view announced (under the
+    # event lock); the audit is built per call.
+    class Objectives
+      # @param side_judgments [SideJudgments] the Engine's side asks (the audit's kinds)
+      # @param host_registry [HostRegistry] System 1's client resolves its host here
+      def initialize(side_judgments:, host_registry:)
+        @side_judgments = side_judgments
+        @host_registry = host_registry
+        # The last view announced (#announce), under the event lock.
+        @announced = nil
+        # The model's proposals until the turn is over (#finally).
+        @proposals = []
+        @proposals_mutex = Mutex.new
+      end
+
+      # System 1 on the objectives, in audit (ObjectivesAudit), at a turn's
+      # start: the owner's turns only, and for a message a person's: a
+      # reminder's or a delegate's prompt isn't one.
+      # @param recorder [SystemOne::Recorder] the audit's runs (built for this call)
+      def incoming(turn, recorder:)
+        return unless turn.prompt.is_a?(String) && turn.origin.human? && OwnerPrompt.turn?(session: turn.session, author: turn.origin.author)
+
+        audit(turn.context.state_dir, recorder).incoming(turn.session, turn.prompt)
+      end
+
+      # The turn's answer, after the end event and before :after_turn (the
+      # caller skips a canceled or exhausted turn): the owner's turns only.
+      # @param recorder [SystemOne::Recorder] the audit's runs (built for this
+      #   call: after a before_turn hook's model switch, the new model)
+      def outgoing(turn, result, recorder:)
+        return unless OwnerPrompt.turn?(session: turn.session, author: turn.origin.author)
+
+        audit(turn.context.state_dir, recorder).outgoing(turn.session, result.text)
+      end
+
+      # A note added between turns (Engine#add_context_note): incoming too.
+      # @param recorder [SystemOne::Recorder] the audit's runs (built for this call)
+      # @param state_dir [String] the sessions dir
+      def note(session, note, recorder:, state_dir:) = audit(state_dir, recorder).note(session, note)
+
+      # 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. The caller
+      # (Engine#announce_objectives) holds the event lock, the one guard of
+      # the last view, announces the event and logs a failure: it only
+      # informs, never fails a turn.
+      # @param state_dir [String] the sessions dir
+      # @param running [Array<Hash>, nil] the running turn's conversation (Engine#live_conversation), nil between turns
+      # @return [Hash, nil] the :objectives_updated event to announce, nil when the view is the same
+      def announce(session, state_dir:, running:)
+        view = Samagotchi::Objectives.view(session.id, session.messages, state_dir: state_dir, running: running&.dup)
+        return if view.nil? || view == @announced
+
+        @announced = view
+        { type: :objectives_updated, session_id: session.id, **view }
+      end
+
+      # A change the model proposes (the objectives tool), kept until the turn
+      # is over, as TurnStages::ContextJudge'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(proposal)
+        @proposals_mutex.synchronize do
+          next true if @proposals.any? { |p| p.line == proposal.line }
+          next false if @proposals.size >= Samagotchi::Objectives::PROPOSALS_PER_TURN
+
+          @proposals << proposal
+          true
+        end
+      end
+
+      # However +turn+ ended (Engine#run_turn's ensure, after the turn flag is
+      # released): only a completed turn shows its proposal cards. A canceled,
+      # failed or rolled-back turn keeps none, and its proposals are dropped
+      # here so the next turn does not show them either: their Apply card
+      # would sit after a turn whose `objectives propose` call is not in the
+      # history (a rollback after Ctrl-C drops it). The caller
+      # (Engine#show_objective_proposals) shows the cards.
+      # @return [Array<Hash>] the completed turn's cards (Engine#show_card's
+      #   arguments); none for any other ending
+      def finally(turn)
+        return proposal_cards if turn.completed?
+
+        discard_proposals(turn)
+        []
+      end
+
+      # For specs: the audit's asks' thread for +kind+ (ObjectivesAudit's
+      # SideJudgments kinds), nil before any.
+      def audit_thread(kind) = @side_judgments.thread(kind)
+
+      # For specs: the proposals kept for the running turn (a copy).
+      def proposals = @proposals_mutex.synchronize { @proposals.dup }
+
+      private
+
+      def proposal_cards
+        drain_proposals.map do |proposal|
+          id = "objectives-#{SecureRandom.hex(4)}"
+          { source: Samagotchi::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
+      end
+
+      def discard_proposals(turn)
+        dropped = drain_proposals
+        Log.info(:turn, "objectives_proposals_dropped", count: dropped.size, outcome: turn.outcome.to_s) unless dropped.empty?
+      end
+
+      def drain_proposals
+        @proposals_mutex.synchronize { @proposals.slice!(0..) }
+      end
+
+      # The audit for one call, over the values it is given: nothing of it
+      # is kept. Its client is asked for only once an active objective is
+      # there (ObjectivesAudit#ask), and with saving off nothing would come
+      # of an ask, so none is made.
+      def audit(state_dir, recorder)
+        ObjectivesAudit.new(
+          side: @side_judgments, state_dir: state_dir,
+          client_for: lambda do |judgment, session|
+            next nil unless recorder.saving?
+
+            recorder.wrap(SystemOne::Client.from_config(host_registry: @host_registry, mode: ObjectivesAudit::MODE, tag: :system_one),
+                          judgment, session, mode: nil)
+          end
+        )
+      end
+    end
+  end
+end