samagotchi 0.153.0 → 0.154.1

data/lib/samagotchi/engine/turn_end.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # How a turn ends after #end_turn's step: the normal ending and its
+    # after-turn hooks, a stop before the model, the release, what an ending
+    # keeps (TurnEndings, forwarded), last_turn, the answer's display.
+    # Writes @last_context_status; reads @turn_endings, @turn_state,
+    # @steer_cut, @hooks, @session_observer, @client.
+    module TurnEndPart
+      # How the turn ended, on the session (Session#last_turn): the caller's
+      # save puts it in the file the session hub watches. Public for the
+      # Worker's turn that failed before it began (no #end_turn ran).
+      # @param limit [Integer, nil] the turn ran out of iterations at this
+      #   limit: "exhausted" => true, "limit" => N, so a wait with nobody to
+      #   answer the continue offer says so (ReplyWait, ParentReport "limit")
+      # @param origin [TurnOrigin] the turn's (TurnOrigin::NONE for no sender)
+      # @param event [Hash] the turn's end event (#stop_facts)
+      def record_last_turn(session, outcome, seconds, origin, event, limit: nil)
+        enqueued_id = origin.enqueued_id
+        session.last_turn = LastTurn.new(outcome: outcome, ended_at: Time.now.iso8601(3), seconds: seconds.round(1),
+                                         origin: origin.source, exhausted: limit ? true : nil, limit: limit,
+                                         enqueued_id: enqueued_id.to_s.empty? ? nil : enqueued_id.to_s,
+                                         author: origin.participant_author,
+                                         **stop_facts(event))
+      end
+
+      # Why a turn stopped (TurnEndings#stop_facts).
+      def stop_facts(event) = @turn_endings.stop_facts(event)
+      private :stop_facts
+
+      def save_quietly(session)
+        session.save(state_dir: session_state_dir)
+      rescue StandardError => e
+        Log.warn(:turn, "turn_end_save_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        nil
+      end
+      private :save_quietly
+
+      # Keep what the after_turn hooks presented as the answer's `display`
+      # and the refs they attached as its `display_refs` (AnswerRefs, one
+      # replace for both), and tell the observers (:answer_display, the
+      # display or nil, and how many refs), after the turn_completed they
+      # already had: the web re-reads the answer then. A turn_completed
+      # with display_pending (after_turn hooks were about to run) always gets
+      # one, `display: nil` when nothing was presented, so the web holds the
+      # answer's pop until then and never swaps it after. Terminals are not
+      # sinks of it; they printed the answer already. The session is saved by
+      # the caller, as after every turn.
+      def store_answer_display(session, display, refs, pending: false)
+        synchronize_events do
+          # A plugin that kept event[:refs] and calls it later gets nil: the
+          # list is stored now (and the turn is over on every path).
+          refs.close!
+          messages = Array(session.messages)
+          changed = display.changed? && messages.last.equal?(display.target)
+          added = refs.added? && messages.last.equal?(refs.target)
+          if changed || added
+            merged = messages.last.dup
+            merged[AnswerDisplay::KEY] = display.text if changed
+            merged[AnswerRefs::KEY] = refs.to_a if added
+            replace_session_messages(session, messages[0...-1] + [merged])
+            event = { type: :answer_display, display: changed ? display.text : nil }
+            event[:refs] = refs.count if added
+            @session_observer.notify(event)
+          elsif pending
+            @session_observer.notify({ type: :answer_display, display: nil })
+          end
+        end
+      end
+      private :store_answer_display
+
+      # A turn stopped before the model was asked (#prepare_turn returned
+      # false): canceled with nothing kept, like a Ctrl-C there; the result
+      # has no conversation, so a UI's checkpoint stands.
+      def stopped_before_model(turn)
+        reason = turn.controller.reason
+        end_turn(turn, "canceled") do |seconds|
+          [nil, { type: :turn_canceled, cancellation_reason: reason, cancelled_by: cancelled_by(turn),
+                  duration_ms: (seconds * 1000).round }]
+        end
+        LLM::ModelResult.new(text: "", canceled: true, cancellation_reason: reason)
+      end
+      private :stopped_before_model
+
+      # Who stopped a turn a hook stopped or cut (the controller's detail: the
+      # bundle, or the hook's label), for the UIs' "stopped by loop-guard";
+      # nil for any other cancel.
+      def cancelled_by(turn) = turn.controller.stopped_by
+      private :cancelled_by
+
+      # The normal ending (an answer, an empty answer, a Stop, the iteration
+      # limit), then the after-turn hooks.
+      def complete_turn(turn, result)
+        canceled = result.canceled?
+        # after_turn hooks run below and may present the answer (the web
+        # holds its pop until it knows).
+        display_pending = !canceled && @hooks.any?(:after_turn)
+        end_turn(turn, canceled ? "canceled" : "completed", exhausted: !canceled && result.exhausted?) do |seconds|
+          kept = kept_messages(turn, result, seconds)
+          if canceled
+            [kept, { type: :turn_canceled, cancellation_reason: result.cancellation_reason, cancelled_by: cancelled_by(turn),
+                     duration_ms: (seconds * 1000).round }]
+          else
+            # For a client that attaches later (session_state_snapshot).
+            @last_context_status = result.context_status.dup if result.context_status
+            [kept, { type: :turn_completed, result: result, turn_summary: turn_summary(result),
+                     display_pending: display_pending }]
+          end
+        end
+
+        # Fire :after_turn hook (an answer or a Stop; an Interrupt or a failure
+        # ends the turn in #run_turn without it), with a read-only
+        # copy of the conversation the turn stored, event[:answer] (the answer's
+        # text: the native loop's stored message still holds its thought),
+        # event[:present] for
+        # 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?
+        display = AnswerDisplay.new(session.messages)
+        refs = AnswerRefs.new(session.messages, cwd: session.working_directory)
+        after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",
+                       messages: hook_messages(session.messages),
+                       answer: (result.text unless canceled || result.exhausted?) }
+        after_turn[:present] = display.presenter(after_turn)
+        after_turn[:refs] = refs.adder(after_turn)
+        @hooks.fire(:after_turn, after_turn)
+        store_answer_display(session, display, refs, pending: display_pending)
+
+        # Fire :session_end after the turn (turn-level lifecycle), as :after_turn
+        @hooks.fire(:session_end, { type: :session_end, session_id: session.id })
+      end
+      private :complete_turn
+
+      # What each turn ending keeps and announces is TurnEndings'
+      # (#build_turn_endings); these forward to it.
+      def kept_messages(turn, result, seconds) = @turn_endings.kept_messages(turn, result, seconds)
+      private :kept_messages
+      def ctrl_c_messages(turn, interrupt, seconds) = @turn_endings.ctrl_c_messages(turn, interrupt, seconds)
+      private :ctrl_c_messages
+      def loop_conversation(error) = @turn_endings.loop_conversation(error)
+      private :loop_conversation
+      def failed_messages(turn, error) = @turn_endings.failed_messages(turn, error)
+      private :failed_messages
+      def failed_event(error, seconds) = @turn_endings.failed_event(error, seconds)
+      private :failed_event
+
+      # However the turn ended (#run_turn's ensure): the turn flag off, the
+      # probe cancel restored, the cancel controller, sink and steers cleared
+      # (a steer left is logged as dropped), activity recorded, the
+      # turn-scoped hooks cleared.
+      def release_turn(probe_cancel_before)
+        # A completed turn is activity: release the turn flag and advance the
+        # shared inactivity clock so the idle recap detector
+        # treats the just-finished turn as activity and re-arms its window.
+        left = @turn_state.finish!
+        @steer_cut.finished!
+        Client.swap_probe_cancel(probe_cancel_before)
+        # The next turn's window and served model are asked again: the cache
+        # (this host's, process-wide) is dropped here, at the turn's end,
+        # rather than at its start, so what this turn read (the profile's own
+        # probe included) is not asked for a second time within the turn. A
+        # restart with another -c between turns is still noticed: the next
+        # turn's first probe goes to the server.
+        @client.invalidate_context_window!
+        log_dropped_steers(left, "turn_ended")
+        record_activity
+        # Clear hooks so they remain turn-scoped and never leak into the next turn.
+        clear_hooks
+      end
+      private :release_turn
+
+      # JSON-safe digest of a finished turn for renderers (TurnEndings#turn_summary).
+      # @param result [LLM::ModelResult]
+      # @return [Hash]
+      def turn_summary(result) = @turn_endings.turn_summary(result)
+    end
+  end
+end

data/lib/samagotchi/engine/turn_helpers.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # 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.
+    module TurnHelpersPart
+      # The turn's settings for the kernel (LLM::TurnSettings): vision,
+      # sampling and thinking, the thinking resolved before the hooks run.
+      # The model name is added in #generate, after the hooks that may switch
+      # the model.
+      # One resolve for all of them: nothing runs between them that could
+      # change what a resolve gives.
+      def turn_settings(session)
+        model = effective_model
+        vision = turn_vision(session, model)
+        sampling = model.sampling
+        level = @model_settings.thinking_level(model)
+        @thinking_notices.turn_started(level, model.target)
+        LLM::TurnSettings.new(vision: vision, sampling: sampling, thinking: level,
+                              reasoning_history: @model_settings.reasoning_history_level(model), model_name: nil,
+                              window_setting: nil, llm_context: nil, price: nil)
+      end
+      private :turn_settings
+
+      # @return [PromptWarmup] the turn-end warm-up (specs, measurements)
+      attr_reader :prompt_warmup
+
+      # A caller's check that the next turn starts at once (input queued for
+      # it: a worker's inbox) or that none follows (a one-shot run): no
+      # 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?
+      end
+      private :warmup_target?
+
+      # 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).
+      # SessionMetrics keys its per-model segments on it. nil when it can't be
+      # named (the turn's record then has none).
+      def generation_model_ref(model)
+        model.ref
+      rescue StandardError => e
+        Log.warn(:turn, "model_ref_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        nil
+      end
+      private :generation_model_ref
+
+      # A step-limit Continue's resume_from, when it is inside the messages the
+      # run gets (a wrong one only drops reasoning: it is ignored, logged).
+      # Entries before it never move between the turns (#turn_messages adds
+      # at the tail, and the system head is replaced in place).
+      def resumed_run_start(turn, run_start)
+        start = turn.resume_from
+        return nil if start.nil?
+        return start if start.is_a?(Integer) && start.between?(0, run_start)
+
+        Log.warn(:turn, "resume_start_invalid", resume_from: start, length: run_start)
+        nil
+      end
+      private :resumed_run_start
+
+      # The turn's LLM context strategy and where it came from, in the turn
+      # log: when it runs a layer, or the session set it (none too).
+      def log_llm_context(explained)
+        return unless explained
+        return if explained.resolved.active_layers.empty? && explained.strategy.source != :session
+
+        summary = explained.summary
+        Log.info(:turn, "llm_context", **summary.slice(:strategy, :strategy_source, :apply, :apply_source, :budget_tokens,
+                                                       :budget_source).compact)
+      end
+      private :log_llm_context
+
+      def publish_used_memories(session, on_event)
+        # Persist deduped used memories onto the session for Web + reload.
+        begin
+          session.used_memory_names = used_memory_names
+        rescue StandardError => e
+          Log.warn(:memory, "used_memories_store_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        end
+        # Notify live observers of the updated memory list (so yellow bar refreshes
+        # even without a tool_call event if the preload was the only addition).
+        # Only emit when there is something to report to avoid noisy event_count drift.
+        return unless used_memory_names.any?
+
+        begin
+          emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names })
+        rescue StandardError => e
+          Log.warn(:memory, "used_memories_emit_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        end
+      end
+      private :publish_used_memories
+
+      # [refs, nil] for a turn's images, or [[], error] when one can't be used
+      # (the turn then fails right after :turn_started).
+      def turn_image_refs(session, images)
+        return [[], nil] if Array(images).empty?
+
+        [ImageStore.resolve_all(Session.session_dir(session.id, state_dir: session_state_dir), images), nil]
+      rescue ImageStore::Error => e
+        [[], e]
+      end
+
+      # The turn's VisionContext: the session's images folder, and whether the
+      # effective model can see images, asked only when a request carries one.
+      def turn_vision(session, model = effective_model)
+        VisionContext.new(session_dir: Session.session_dir(session.id, state_dir: session_state_dir),
+                          capability: -> { model.vision_support(profile) })
+      end
+
+      # A model known not to see images fails a turn with images up front.
+      def refuse_images!(vision)
+        return if vision.sendable?
+
+        host = effective_model.host_name
+        raise LLM::VisionUnsupported.new("#{host}: #{vision.refusal_reason}", host: host)
+      end
+    end
+  end
+end

data/lib/samagotchi/engine/verify.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+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.
+    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)
+
+        revises = revision_target(messages, turn, outcome)
+        fields = { verify: turn.verify&.to_h, revises: revises&.to_h }.compact
+        return if fields.empty?
+
+        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
+    end
+  end
+end