samagotchi 0.154.1 → 0.155.0

data/lib/samagotchi/engine/toolkit.rb

@@ -4,9 +4,9 @@ module Samagotchi
   class Engine
     # The session's toolkit: the kits and what a turn declares
     # (ToolkitBinding, forwarded), ctx.load_tools and the staged loads a turn
-    # appends, and System 1's toolkit suggestion (start, settle, warm-up).
-    # Writes @toolkit_warmup_thread; reads @toolkit_binding, @tools,
-    # @tool_index, @tool_loads, @side_judgments, @session.
+    # appends, and System 1's toolkit suggestion (TurnStages::ToolkitSuggestion,
+    # forwarded). Reads @toolkit_binding, @tools, @tool_index, @tool_loads,
+    # @toolkit_suggestion, @session.
     module ToolkitPart
       private
 
@@ -17,22 +17,29 @@ module Samagotchi
       def toolkit_explained(toolkit = nil) = @toolkit_binding.explained(toolkit)
       def toolkit_summary = @toolkit_binding.summary
 
+      # The Registry published for readers off the turn thread
+      # (ToolkitBinding#publish!): at the end of the Engine's build, after a
+      # turn's staged tool sets and its toolkit apply.
+      def publish_tools! = @toolkit_binding.publish!
+
       # The tools this session registered (Tools::Registry), declared or not.
       attr_reader :tools
 
       public :tools, :toolkit_kits, :resolved_toolkit, :toolkit_explained, :toolkit_summary
 
       # A plugin's ctx.load_tools: stage the reachable tools +names+ names
-      # (Tools::ToolIndex#deferred_name) that the session neither declares
-      # nor loaded with an earlier tool change, for bundle +bundle+. A name
-      # that names no tool at all is logged; a declared or removed one is
-      # skipped quietly.
+      # (Tools::ToolIndex#deferred_name, on the published Registry) that the
+      # session neither declares nor loaded with an earlier tool change, for
+      # bundle +bundle+. A name that names no tool at all is logged; a
+      # declared or removed one is skipped quietly.
       # @return [Array<String>] the wire names staged
       def load_tools(names, bundle)
         added = ToolLoads.added(@session&.messages)
+        published = @toolkit_binding.published
+        surface = Tools::ToolSurface.for(published)
         wanted = names.filter_map do |name|
-          wire = @tool_index.deferred_name(name)
-          Log.info(:plugins, "load_tools_skipped", bundle: bundle, tool: name) unless wire || @tools.key?(name)
+          wire = @tool_index.deferred_name(name, surface)
+          Log.info(:plugins, "load_tools_skipped", bundle: bundle, tool: name) unless wire || published.key?(name)
           wire
         end
         @tool_loads.stage(wanted - added, by: bundle)
@@ -79,191 +86,27 @@ module Samagotchi
       def apply_toolkit!(session, on_event = nil) = @toolkit_binding.apply!(session, on_event)
       private :apply_toolkit!
 
-      # Start the toolkit classifier after :turn_started, for audit and on
-      # mode alike (one eligibility, one snapshot, one thread). All session
-      # and tool-registry reads happen here; the thread receives only this
-      # snapshot. Audit never blocks: the thread logs its line. On mode
-      # returns the ask's Pending, which the turn joins before apply_toolkit!
-      # (#settle_toolkit_suggestion), with the turn's controller as the
-      # request's cancel controller.
-      # @return [ToolkitSuggest::Pending, nil] nil unless the turn joins an ask
-      def start_toolkit_suggestion(turn)
-        mode = Config.get("toolkit.suggest.mode").to_s
-        return if mode == "off"
-
-        joined = mode == "on"
-        session = turn.session
-        default = Toolkit.of(session.toolkit)
-        log = toolkit_suggestion_log
-        # The predicate checks the session first; the kits (memory kits are
-        # read from disk) and the log (read whole) only when it gets there.
-        kits = nil
-        candidates = nil
-        return unless ToolkitSuggest.eligible?(
-          session: session, prompt: turn.prompt, author: turn.origin.author,
-          candidate_count: lambda {
-            kits = @toolkit_binding.kits
-            candidates = ToolkitSuggest.candidates(kits, default_name: default.name)
-            candidates.size
-          },
-          last_suggestion: -> { ToolkitSuggest.last_suggestion(log, session.id) },
-          defer_turns: Config.get("toolkit.suggest.defer_turns"),
-          defer_tokens: Config.get("toolkit.suggest.defer_tokens")
-        )
+      # System 1's toolkit suggestion (TurnStages::ToolkitSuggestion):
+      # prepare_turn starts, settles and abandons it; the Worker warms it.
+      attr_reader :toolkit_suggestion
+      private :toolkit_suggestion
 
-        # One ask at a time: an eligible turn while the last one still runs
-        # goes unasked, and says so.
-        if @side_judgments.in_flight?(:toolkit)
-          Log.info(:toolkit, "toolkit_suggest_in_flight_skipped", session_id: session.id)
-          return
-        end
-
-        client = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit),
-                                      ToolkitSuggest::JUDGMENT, session, mode: Config.get("toolkit.suggest.mode").to_s)
-        return unless client
-
-        # The warm-up's only value is the cache: the real ask never queues
-        # behind it.
-        stop_toolkit_warmup
-
-        # Rules, not tool lists: this runs before await_init_tasks and
-        # apply_staged_tools!, so a first turn's plugin/MCP tools aren't
-        # registered yet; the report expands the rules (ToolkitSuggest.rules).
-        snapshots = candidates.map do |kit|
-          ToolkitSuggest::Candidate.new(name: kit.name.dup.freeze, description: kit.description.dup.freeze,
-                                        rules: ToolkitSuggest.rules(Toolkit.resolve_kit(kit.name, kits)))
-        end.freeze
-        default_snapshot = ToolkitSuggest::Candidate.new(name: default.name.dup.freeze, description: nil,
-                                                         rules: ToolkitSuggest.rules(default.resolve(kits)))
-        registered = @tools.entries(toolkit: nil).reject { |entry| entry.source == Tools::ToolIndex::SOURCE }
-        core_tools, plugin_tools = registered.partition(&:core?).map { |entries| entries.map { |entry| entry.name.dup.freeze }.freeze }
-        state = ToolkitSuggest.question(
-          default: default, kits: kits, project: File.basename(session.project_root.to_s),
-          prompt: turn.prompt
-        ).last
-        snapshot = ToolkitSuggest::Snapshot.new(
-          session_id: session.id.dup.freeze, turn_number: ToolkitSuggest.turn_number(session.messages),
-          default: default_snapshot, candidates: snapshots, core_tools: core_tools, plugin_tools: plugin_tools,
-          state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
-        )
-        threshold = Config.get("toolkit.suggest.threshold")
-        runs = session.scratch ? nil : system_one_runs
-        pending = ToolkitSuggest::Pending.new(log: log, joined: joined,
-                                              acted: runs && ->(judged, did) { runs.acted(judged.fields[:run_id], did) },
-                                              timeout_seconds: SystemOne::Client.configured_timeout_ms / 1000.0)
-        # On mode: cut by a Stop while the turn waits (Pending#wait), not
-        # by one after it went on; audit's ask is never cut.
-        controller = joined ? pending.cancel_controller : nil
-        @side_judgments.start(:toolkit, warn: ToolkitSuggest.method(:warn), finish: pending.method(:finish)) do
-          ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
-                               cancel_controller: controller)
-        end
-        joined ? pending : nil
-      rescue StandardError => e
-        ToolkitSuggest.warn(e)
-        nil
-      end
-      private :start_toolkit_suggestion
-
-      # On mode, before apply_toolkit!: wait for the ask (#start_toolkit_
-      # suggestion) up to System 1's timeout from its start, or until a Stop,
-      # and put the session on a candidate picked with confidence ≥ threshold
-      # (ToolkitBinding#suggest: origin suggested, saved, the notice). Any
-      # other outcome (the default, below threshold, undecided, no judgment,
-      # a timeout, a Stop) leaves the session on its default. Nothing here
-      # sends a request; prepare_turn's cancel check ends a stopped turn. A
-      # Stop wins over an answer already in (Pending#wait checks it first).
-      def settle_toolkit_suggestion(turn, pending)
-        return if pending.nil?
-
-        outcome, judged = pending.wait(turn.controller)
-        if outcome == :timeout
-          # The session starts on its default without a word otherwise: a
-          # slow System 1 host (a local one) is the usual cause.
-          timeout_ms = SystemOne::Client.configured_timeout_ms
-          Log.warn(:toolkit, "toolkit_suggest_timeout", session_id: turn.session.id, timeout_ms: timeout_ms,
-                                                        reason: "System 1 gave no answer within system_one.timeout_ms")
-          @toolkit_binding.fell_back(turn.session, "System 1 took over #{timeout_ms} ms")
-          return
-        end
-        unless outcome == :answered
-          Log.info(:toolkit, "toolkit_suggest_#{outcome}", session_id: turn.session.id)
-          return
-        end
-        return if judged.nil?
-
-        pending.record(toolkit_suggestion_outcome(turn.session, judged))
-      rescue StandardError => e
-        ToolkitSuggest.warn(e)
-        pending&.record("failed")
-      end
-      private :settle_toolkit_suggestion
-
-      # What the turn does with an answered ask, as the log line's did:
-      # suggested (switched), chosen (the toolkit isn't the default any
-      # more), unavailable (the kit is gone), defer or default.
-      def toolkit_suggestion_outcome(session, judged)
-        case judged.would
-        when "suggested"
-          return "chosen" unless session.toolkit_origin == "default"
-          return "unavailable" unless @toolkit_binding.kits.key?(judged.suggestion.kit)
-
-          switched = @toolkit_binding.suggest(session, judged.suggestion.kit, confidence: judged.suggestion.confidence,
-                                                                              deferred: ToolkitSuggest.model_reply?(session.messages))
-          switched ? "suggested" : "chosen"
-        when "defer" then "defer"
-        when "no_judgment"
-          # System 1 failed (its own warn) or answered nothing usable.
-          @toolkit_binding.fell_back(session, "System 1 gave no answer")
-          "default"
-        else "default"
-        end
-      end
-      private :toolkit_suggestion_outcome
-
-      # On mode, as an idle worker starts (Worker#start_background): one ask
-      # with the real question and a stand-in prompt, on its own thread,
-      # never logged and never waited for, so System 1's server has the
-      # question's prefix cached for the first prompt. Only for a session a
-      # first prompt could be asked for: origin default, no model reply, not
-      # a delegate child or a review session, at least two candidates; and
-      # not when the worker starts on a first prompt (that ask comes at once).
-      def warm_toolkit_suggestion!
-        return unless Config.get("toolkit.suggest.mode").to_s == "on"
-
-        session = @session
-        return if session.nil? || session.toolkit_origin != "default" || session.delegate? || session.review?
-        return if ToolkitSuggest.model_reply?(session.messages) || !session.last_prompt.to_s.strip.empty?
-
-        default = Toolkit.of(session.toolkit)
-        kits = @toolkit_binding.kits
-        return if ToolkitSuggest.candidates(kits, default_name: default.name).size < 2
-
-        client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
-        return unless client
-
-        project = File.basename(session.project_root.to_s)
-        @toolkit_warmup_thread = Thread.new do
-          ToolkitSuggest.warm(client: client, default: default, kits: kits, project: project)
-        end
-      rescue StandardError => e
-        ToolkitSuggest.warn(e)
-        nil
-      end
+      # On mode, as an idle worker starts (Worker#start_background): the
+      # warm-up ask (TurnStages::ToolkitSuggestion#warm!).
+      def warm_toolkit_suggestion! = @toolkit_suggestion.warm!(@session)
       public :warm_toolkit_suggestion!
 
-      # A still-running warm-up, stopped: a real ask (or the worker leaving)
-      # doesn't wait behind it.
-      def stop_toolkit_warmup
-        @toolkit_warmup_thread&.kill
-        @toolkit_warmup_thread = nil
-      end
-      private :stop_toolkit_warmup
-
-      def toolkit_suggestion_log
-        SideJudgments.log(ToolkitSuggest.log_path(session_state_dir), tag: :toolkit, event: "toolkit_suggest_log_failed")
+      # The stage over this Engine's side asks, binding and tools (built in
+      # #build_tools_and_plugins, before the plugins load).
+      def build_toolkit_suggestion
+        TurnStages::ToolkitSuggestion.new(
+          side_judgments: @side_judgments, host_registry: @host_registry, toolkit_binding: @toolkit_binding,
+          tools: @tools, state_dir: -> { session_state_dir },
+          recording: ->(client, judgment, session, mode:) { system_one_recording(client, judgment, session, mode: mode) },
+          runs: -> { system_one_runs }
+        )
       end
-      private :toolkit_suggestion_log
+      private :build_toolkit_suggestion
     end
   end
 end

data/lib/samagotchi/engine/turn_end.rb

@@ -117,7 +117,7 @@ module Samagotchi
         # a display version of the answer (AnswerDisplay) and event[:refs]
         # for refs on it (AnswerRefs).
         session = turn.session
-        audit_objectives_outgoing(turn, result) unless canceled || result.exhausted?
+        @objectives_stage.outgoing(turn, result) unless canceled || result.exhausted?
         display = AnswerDisplay.new(session.messages)
         refs = AnswerRefs.new(session.messages, cwd: session.working_directory)
         after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",

data/lib/samagotchi/engine/turn_helpers.rb

@@ -5,8 +5,9 @@ module Samagotchi
     # What a turn's steps use before and around the model: its settings,
     # images and vision, the model ref and resumed run start it generates
     # with, the used memories it publishes, and the turn-end warm-up of the
-    # next one. Writes @next_turn_waiting; reads @model_settings, @kernel,
-    # @prompt_warmup, @thinking_notices, @turn_state.
+    # next one (TurnStages::Warmup, built here). Writes @next_turn_waiting;
+    # reads @model_settings, @kernel, @prompt_warmup, @thinking_notices,
+    # @turn_state, @turn_warmup.
     module TurnHelpersPart
       # The turn's settings for the kernel (LLM::TurnSettings): vision,
       # sampling and thinking, the thinking resolved before the hooks run.
@@ -34,44 +35,20 @@ module Samagotchi
       # warm-up then. nil: neither.
       attr_accessor :next_turn_waiting
 
-      # After a completed turn, prefill the next turn's prompt up to its user
-      # message while the user reads (PromptWarmup, cache.warmup). Only on a
-      # local llama.cpp host on the native loop, and not when the next turn's
-      # start differs anyway or starts at once: a reminder due, a continue
-      # offer (the turn ran out of steps), a carried steer or queued input.
-      # Never fails the turn.
-      def warm_up_next_turn(turn, result)
-        return if result.canceled? || result.resumable?
-
-        model = effective_model
-        client = model.client
-        return unless warmup_target?(model, client)
-        return if reminders_due? || @turn_state.carried_steers? || @next_turn_waiting&.call
-
-        messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: system_prompt(model) })
-        # Under the next turn's strategy (a /model switch may have changed it);
-        # the last turn's when it can't be resolved.
-        prompt, images = @kernel.warmup_prompt(messages, llm_context: @model_settings.turn_llm_context || @kernel.turn_settings&.llm_context)
-        return unless prompt
-
-        started = @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
-                                       slot: @kernel.last_slot, images: images)
-        @kernel.warmed_up! if started
-      rescue StandardError => e
-        Log.warn(:model, "warmup_skipped", error: e.class.name, msg: e.message.to_s[0, 200])
-      end
-      private :warm_up_next_turn
-
-      # Never a paid or remote host (cache.warmup auto means local only), nor
-      # the chat loop (Splash keeps its own cache; llama.cpp's chat path is
-      # not measured), nor a client that can't warm up (a spec's stub).
-      def warmup_target?(model, client)
-        return false if model.chat? || model.entry.remote?
-        return false unless client.respond_to?(:warm_up)
-
-        PromptWarmup.enabled?
+      # The turn-end warm-up's stage (TurnStages::Warmup).
+      attr_reader :turn_warmup
+      private :turn_warmup
+
+      # The stage over the kernel and the Engine's PromptWarmup (built in
+      # #initialize, once the kernel is).
+      def build_turn_warmup
+        TurnStages::Warmup.new(
+          prompt_warmup: @prompt_warmup, kernel: @kernel, turn_state: @turn_state, model_settings: @model_settings,
+          model: -> { effective_model }, system_prompt: ->(model) { system_prompt(model) },
+          reminders_due: -> { reminders_due? }, next_turn_waiting: -> { next_turn_waiting&.call }
+        )
       end
-      private :warmup_target?
+      private :build_turn_warmup
 
       # The ref (host:model, as asked) a turn's generations ran on: the model
       # #generate resolved, after the before_turn hooks (which may switch it).

data/lib/samagotchi/engine/verify.rb

@@ -2,152 +2,16 @@
 
 module Samagotchi
   class Engine
-    # Verify and Revise anchors at a turn's end: the opening's stamp, a Revise
-    # turn's draft checked, a Verify turn's quote checked against its source
-    # session and its verdict recorded. No ivars of its own: it reads the turn,
-    # and the sessions it loads through Engine methods.
+    # Verify and Revise anchors (TurnStages::VerifyAnchors): #begin_turn
+    # checks a Verify turn's claim, #end_turn's event step stamps the opening
+    # and records the verdict. Reads @verify_anchors.
     module VerifyPart
-      # The turn's anchors, stamped on its opening message (the prompt, or a
-      # wake turn's note) in the messages it keeps: display metadata, never
-      # in the prompt (LLM::ChatLoop#plain keeps them, no wire sends them).
-      # A Verify turn's claim however it ended; a Revise turn's draft only
-      # once it completed with an answer (#revision_target). Returns the
-      # stamped ReviseAnchor (the end event's revises), or nil.
-      def stamp_opening(messages, turn, outcome)
-        return unless messages.is_a?(Array)
+      private
 
-        revises = revision_target(messages, turn, outcome)
-        fields = { verify: turn.verify&.to_h, revises: revises&.to_h }.compact
-        return if fields.empty?
+      # The anchors' stage (TurnStages::VerifyAnchors).
+      attr_reader :verify_anchors
 
-        opening = messages.reverse.find do |message|
-          Steer.turn_prompt?(message) && (message[:turn_id] || message["turn_id"]).to_s == turn.id
-        end
-        return unless opening
-
-        opening.merge!(fields)
-        revises
-      end
-      private :stamp_opening
-
-      # The turn a Revise turn revised (D6: "this turn revised that one"):
-      # only a completed turn with an answer (AnswerTail) has revised
-      # anything. A draft no prompt in the messages carries is no target (a
-      # stale page, a rolled-back turn); one a stamped turn already revised
-      # is re-targeted to its stack's top, the newest version, which the
-      # person meant ("this draft").
-      def revision_target(messages, turn, outcome)
-        return unless turn.revises && outcome == "completed"
-
-        slice = AnswerTail.turn_slice(messages, turn.id)
-        return unless slice&.any? { |message| AnswerTail.answer?(message) }
-
-        target = turn.revises.turn_id
-        seen = [turn.id]
-        until seen.include?(target)
-          return reject_revise_anchor(turn.revises, :turn_missing) unless AnswerTail.turn_slice(messages, target)
-
-          seen << target
-          newer = messages.reverse.find do |message|
-            Steer.turn_prompt?(message) && ReviseAnchor.from(message[:revises] || message["revises"])&.turn_id == target
-          end
-          return ReviseAnchor.new(turn_id: target) unless newer
-
-          target = (newer[:turn_id] || newer["turn_id"]).to_s
-        end
-        reject_revise_anchor(turn.revises, :cycle)
-      end
-      private :revision_target
-
-      def reject_revise_anchor(anchor, reason)
-        Log.warn(:turn, "revise_anchor_rejected", turn_id: anchor.turn_id, reason:)
-        nil
-      end
-      private :reject_revise_anchor
-
-      def verified_anchor(session, anchor)
-        return unless anchor
-
-        source = verify_anchor_source_session(session, anchor)
-        return unless source
-
-        turn = AnswerTail.turn_slice(Array(source.messages), anchor.turn_id)
-        return reject_verify_anchor(anchor, :turn_missing) unless turn
-
-        reply = turn.reverse.find { |message| AnswerTail.answer?(message) }
-        return reject_verify_anchor(anchor, :reply_missing) unless reply
-
-        quote_text = verify_comparison_text(anchor.quote)
-        quoted = !quote_text.empty? && verify_quote_in?(quote_text, (reply[:content] || reply["content"]).to_s, source)
-        return reject_verify_anchor(anchor, :quote_missing) unless quoted
-
-        anchor
-      end
-      private :verified_anchor
-
-      # Whether +quote_text+ is in +answer+ as the model wrote it, or as the
-      # pages show it: a page quotes its own text, which reads the session's
-      # folder relative, the home folder as ~ and a secret shape as
-      # [redacted] (a participant's page gets it so, Redact;
-      # the owner's page rewrites its quote the same way, claim_link.js
-      # normalizeClaim, so claim links match both pages). +source+ is the
-      # session whose folder that is.
-      def verify_quote_in?(quote_text, answer, source)
-        return true if verify_comparison_text(answer).include?(quote_text)
-
-        viewer = Redact::Viewer.new(cwd: source.working_directory)
-        verify_comparison_text(Redact.text(answer, viewer)).include?(quote_text)
-      end
-      private :verify_quote_in?
-
-      def verify_anchor_source_session(session, anchor)
-        return session unless session.verify_fresh
-
-        fresh = session.verify_fresh
-        return reject_verify_anchor(anchor, :fresh_anchor_mismatch) unless fresh.anchor == anchor
-        return reject_verify_anchor(anchor, :fresh_parent_missing) unless session.parent_id
-
-        Session.load(session.parent_id, state_dir: session_state_dir)
-      rescue ArgumentError, SystemCallError, IOError => e
-        Log.warn(:turn, "verify_anchor_rejected", turn_id: anchor.turn_id, reason: :source_session_unavailable,
-                                                   error: e.class.name)
-        nil
-      end
-      private :verify_anchor_source_session
-
-      def verify_comparison_text(text)
-        OutputFormatter.strip_markup(text)
-                      .gsub(/!\[([^\]]*)\]\([^)]+\)/, '\1')
-                      .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
-                      .gsub(/^[ \t]*(?:\#{1,6}[ \t]+|>[ \t]?|[-+*][ \t]+|\d+[.)][ \t]+)/, "")
-                      .gsub(/(\*\*|__|~~|`+)(.+?)\1/m, '\2')
-                      .gsub(/(?<!\w)\*(\S(?:.*?\S)?)\*(?!\w)/m, '\1')
-                      .gsub(/(?<!\w)_(\S(?:.*?\S)?)_(?!\w)/m, '\1')
-                      .tr("|", " ") # a table row's cells; the page copies them without the pipes
-                      .gsub(/\s+/, " ")
-                      .strip
-      end
-      private :verify_comparison_text
-
-      def reject_verify_anchor(anchor, reason)
-        Log.warn(:turn, "verify_anchor_rejected", turn_id: anchor.turn_id, reason:)
-        nil
-      end
-      private :reject_verify_anchor
-
-      def record_verdict(turn, outcome)
-        return unless outcome == "completed" && turn.verify
-
-        answer = AnswerTail.find(turn.session.messages, turn_id: turn.id)
-        parsed = Verdict.parse(answer && (answer[:content] || answer["content"]))
-        return unless parsed
-
-        record = { anchor: turn.verify.to_h, verdict: parsed.verdict, reason: parsed.reason,
-                   by: turn.origin.author, check_turn_id: turn.id, at: Time.now.iso8601(3) }
-        turn.session.verdicts = turn.session.verdicts + [record]
-        record
-      end
-      private :record_verdict
+      def build_verify_anchors = TurnStages::VerifyAnchors.new(state_dir: -> { session_state_dir })
     end
   end
 end