samagotchi 0.154.1 → 0.155.0

data/lib/samagotchi/engine/context_judge.rb

@@ -2,137 +2,31 @@
 
 module Samagotchi
   class Engine
-    # The attached-context candidate judge (ContextJudge): its pass at an
-    # owner turn's start and for a late candidate, the asks it starts, and
-    # the cards it shows after the turn. Reads @context_cards_after_turn
-    # under @context_cards_mutex, @side_judgments, @host_registry, @session.
+    # The attached-context candidate judge (TurnStages::ContextJudge,
+    # forwarded): prepare_turn starts its pass, run_turn's ensure shows the
+    # cards it held, and a plugin's late candidate asks it. Reads
+    # @context_judge, @side_judgments, @host_registry.
     module ContextJudgePart
       private
 
-      # The candidate judge (ContextJudge) 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).
-      def start_context_judge(turn)
-        session = turn.session
-        return unless turn.prompt.is_a?(String) && OwnerPrompt.turn?(session: session, author: turn.origin.author)
-
-        context_judge_pass(session, ContextCandidates.owner_texts(session.messages) + [turn.prompt], phase: "turn")
-      end
-      private :start_context_judge
+      # The judge's stage (TurnStages::ContextJudge).
+      attr_reader :context_judge
 
       # 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.
-      def judge_late_candidates
-        session = @session
-        return if session.nil? || session.review?
-
-        texts = ContextCandidates.owner_texts(plugin_messages)
-        context_judge_pass(session, texts, phase: "late") unless texts.empty?
-      end
-      private :judge_late_candidates
-
-      # One look at +session+'s candidates; the asks go to SideJudgments'
-      # :context kind, one thread asking each due candidate in turn.
-      def context_judge_pass(session, texts, phase:)
-        return if session.id.nil? || session.scratch
-
-        rows = ContextCandidates.with_status(session.id, project_root: session.project_root, state_dir: session_state_dir)
-        return if rows.empty?
-
-        log = ContextCandidatesLog.log_for(session_state_dir)
-        records = ContextCandidatesLog.records_for(log, session.id)
-        ContextCandidatesLog.look(log, session.id, rows, records) if phase == "turn"
-        settings = ContextJudge::Settings.from_config
-        return if settings.mode == "off"
-
-        jobs = ContextJudge.jobs(rows, records, session_id: session.id, texts: texts, settings: settings, phase: phase,
-                                                parent_attached: context_parent_attached(session))
-        return if jobs.empty?
-
-        client = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context),
-                                      ContextJudge::JUDGMENT, session, mode: settings.mode)
-        return unless client
-
-        start_context_asks(client, jobs, log, settings, context_choice(session, log, settings))
-      rescue StandardError => e
-        ContextJudge.warn(e)
-      end
-      private :context_judge_pass
-
-      # @return [Thread, nil] the asks' thread, nil when none started
-      def start_context_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: ContextJudge.method(:warn)) do
-          jobs.each { |job| choice.call(job, ContextJudge.ask(client: client, job: job, log: log, settings: settings)) }
-        end
-      end
-      private :start_context_asks
-
-      # 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 this 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 context_choice(session, log, settings)
-        session_id = session.id
-        project_root = session.project_root
-        state_dir = session_state_dir
-        show = lambda do |**card|
-          current = @session
-          next nil unless current.nil? || current.id == session_id
-
-          @context_cards_mutex.synchronize do
-            next @context_cards_after_turn << card if turn_running?
-
-            show_card(**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
-      private :context_choice
-
-      # The cards #context_choice held while a turn ran (#run_turn's ensure,
-      # after the turn flag is released).
-      def show_context_cards_after_turn
-        cards = @context_cards_mutex.synchronize { @context_cards_after_turn.slice!(0..) }
-        cards.each { |card| show_card(**card) }
-      rescue StandardError => e
-        ContextJudge.warn(e)
-      end
-      private :show_context_cards_after_turn
-
-      # 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 context_parent_attached(session)
-        return nil unless session.delegate? && session.parent_id
-
-        parent_root = if Session.exist?(session.parent_id, state_dir: session_state_dir)
-                        Session.load(session.parent_id, state_dir: session_state_dir).project_root
-                      else
-                        session.project_root
-                      end
-        ContextSources.attached(session.parent_id, project_root: parent_root, state_dir: session_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])
-        []
+      # #candidate_proposed): TurnStages::ContextJudge#late_candidates.
+      def judge_late_candidates = @context_judge.late_candidates
+
+      # The stage over this Engine's side asks and its session (built in
+      # #build_tools_and_plugins, before the plugins load: one may propose a
+      # candidate as it loads).
+      def build_context_judge
+        TurnStages::ContextJudge.new(
+          side_judgments: @side_judgments, host_registry: @host_registry, state_dir: -> { session_state_dir },
+          recording: ->(client, judgment, session, mode:) { system_one_recording(client, judgment, session, mode: mode) },
+          session: -> { session }, messages: -> { plugin_messages }, turn_running: -> { turn_running? },
+          show_card: ->(**card) { show_card(**card) }
+        )
       end
-      private :context_parent_attached
     end
   end
 end

data/lib/samagotchi/engine/guardrails.rb

@@ -76,11 +76,13 @@ module Samagotchi
       end
 
       # Ask the user to approve a call the gate voted `ask` on
-      # (GuardrailWiring#request_approval).
+      # (GuardrailWiring#request_approval), for the running turn (its
+      # author), else the last one. The gate's own asks come with their
+      # call's TurnContext instead.
       # @param verdict [Guardrails::Verdict]
       # @return [Guardrails::Verdict]
       def request_approval(verdict)
-        @guardrail_wiring.request_approval(verdict)
+        @guardrail_wiring.request_approval(verdict, turn_context || last_turn_context)
       end
     end
   end

data/lib/samagotchi/engine/messages.rb

@@ -46,7 +46,7 @@ module Samagotchi
                      from_cwd: note[:from_cwd], text: note[:text], context_source: note[:context_source],
                      created_at: note[:created_at], objectives: entry }.compact)
           announce_objectives(session) if entry
-          objectives_audit.note(session, note)
+          @objectives_stage.note(session, note)
           message
         end
       end
@@ -76,14 +76,17 @@ module Samagotchi
       # register it on the kernel's llm_context_turn): the same array the loop
       # appends to, not a copy, so read it on the turn's thread (the pending
       # input drain, at an iteration boundary: TurnCheckpoint), or from another
-      # only as a dup, read only (/objectives). nil when no
-      # turn runs (llm_context_turn is never cleared, and still holds the
-      # last turn's then).
+      # only as a dup, read only (/objectives). nil when no turn runs, and
+      # while the running turn's loop has yet to register its own
+      # (llm_context_turn is never cleared, and still holds the last turn's
+      # then: its turn_id tells them apart).
       # @return [Array<Hash>, nil]
       def live_conversation
-        return nil unless turn_running? && @kernel.respond_to?(:llm_context_turn)
+        running = turn_context
+        return nil unless running && @kernel.respond_to?(:llm_context_turn)
 
-        @kernel.llm_context_turn&.conversation
+        forget = @kernel.llm_context_turn
+        forget&.turn_id == running.id ? forget.conversation : nil
       end
 
       # Append messages to the current session's conversation.

data/lib/samagotchi/engine/objectives.rb

@@ -2,30 +2,15 @@
 
 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.
+    # The session's objectives (TurnStages::Objectives, forwarded): the view
+    # announced when it changed, the model's proposals kept as cards until
+    # the turn is over, System 1's audit of them (ObjectivesAudit); and
+    # Check this's side request. Reads @objectives_stage, @side_judgments,
+    # @host_registry, @session.
     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
+      # The session's objectives as the page draws them, when that differs
+      # from the last announced (TurnStages::Objectives#announce).
+      def announce_objectives(session = @session) = @objectives_stage.announce(session)
 
       # Check this (ObjectivesCheck)'s one side request. Its usage is in the
       # session's side line. Raises as ctx.ask_model's request does.
@@ -38,79 +23,26 @@ module Samagotchi
       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.
+      # is over (TurnStages::Objectives#propose).
       # @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
+      def propose_objective(proposal) = @objectives_stage.propose(proposal)
 
       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
+      # The objectives' stage (TurnStages::Objectives).
+      attr_reader :objectives_stage
+
+      # The stage over this Engine's side asks and its event lock (built in
+      # #initialize, once the host registry is).
+      def build_objectives_stage
+        TurnStages::Objectives.new(
+          side_judgments: @side_judgments, host_registry: @host_registry, state_dir: -> { session_state_dir },
+          recording: ->(client, judgment, session, mode:) { system_one_recording(client, judgment, session, mode: mode) },
+          runs: -> { system_one_runs }, synchronize: ->(&block) { synchronize_events(&block) },
+          announce: ->(event) { announce(event) }, running: -> { live_conversation },
+          show_card: ->(**card) { show_card(**card) }
         )
       end
-      private :objectives_audit
     end
   end
 end

data/lib/samagotchi/engine/participants.rb

@@ -5,13 +5,16 @@ module Samagotchi
     # 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.
+    # @participants_line; reads @participants, @participants_watch and the
+    # turn's TurnContext.
     module ParticipantsPart
       # The running turn's author when a participant wrote it, else nil
-      # (ctx.turn_author, the hooks' author).
+      # (ctx.turn_author, the hooks' author, the judgments' participant:,
+      # ObjectivesCheck): one read of the published TurnContext, so any
+      # thread sees the running turn's author from its first moment, never
+      # the last turn's.
       # @return [String, nil]
-      def turn_author = turn_running? ? @guardrail_wiring.turn_author : nil
+      def turn_author = turn_context&.author
 
       # Whether a participant's pair turn must stop, read before each of its
       # generations (#guard_participant_spend): author ("p:<id>") → why (their
@@ -20,7 +23,7 @@ module Samagotchi
       # nothing is checked mid-turn.
       attr_writer :participant_stop
 
-      # Before each generation (KernelLoop#generation_guard): a pair turn whose
+      # Before each generation (KernelLoop::Services#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,
@@ -28,10 +31,11 @@ module Samagotchi
       # 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
+      # @param context [TurnContext] the running turn's (the loop's)
+      def guard_participant_spend(context)
+        author = context&.author
         return if author.nil? || @participant_stop.nil?
-        return unless @guardrail_wiring.turn_mode == ParticipantMode::PAIR
+        return unless context.participant_mode == ParticipantMode::PAIR
 
         reason = @participant_stop.call(author) or return
         hook_stop_turn(reason, PARTICIPANTS_HOOK)
@@ -77,8 +81,9 @@ module Samagotchi
       # 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
+      # @param context [TurnContext] the turn's
+      def participant_mode_fields(context)
+        mode = context.participant? && context.participant_mode
         mode ? { participant_mode: mode.to_s } : {}
       end
     end

data/lib/samagotchi/engine/plugins.rb

@@ -101,11 +101,13 @@ module Samagotchi
       # 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).
+      # (a plugin tool the toolkit leaves out). Publishes the Registry it
+      # leaves (#publish_tools!).
       # @return [Boolean] whether the tools changed
       def apply_staged_tools!
         changed = @plugin_tasks.apply_staged_tools!
         @tool_index.refresh! if changed
+        publish_tools!
         changed
       end
       public :apply_staged_tools!

data/lib/samagotchi/engine/questions.rb

@@ -15,7 +15,7 @@ module Samagotchi
       end
 
       # Ask the model's question (ask_user_question): the kernel's
-      # question_handler, called on the turn thread with the payload
+      # Services#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.

data/lib/samagotchi/engine/side_requests.rb

@@ -42,9 +42,12 @@ module Samagotchi
       def side_author(kind)
         # Check this is only ever the owner's, whichever turn runs as it ends.
         return nil if kind.to_s == ObjectivesCheck::SOURCE
-        return nil unless turn_running? || kind.to_s == RECAP_SIDE_KIND
 
-        @guardrail_wiring.turn_author
+        # One read each of the published contexts (TurnState): any thread.
+        running = turn_context
+        return running.author if running
+
+        kind.to_s == RECAP_SIDE_KIND ? last_turn_context&.author : nil
       end
 
       private