samagotchi 0.155.0 → 0.157.0

data/lib/samagotchi/reasoning_history.rb

@@ -63,38 +63,31 @@ module Samagotchi
       nil
     end
 
-    # The level for +target+ and where it came from ("session",
+    # The level for +lookup+'s model and where it came from ("session",
     # "SAMAGOTCHI_REASONING_HISTORY", "models: qwen", "hosts.work"; nil for
     # the default).
-    # @param target [HostRegistry::ModelTarget]
-    # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param lookup [ModelLookup] the model's layers (EffectiveModel#lookup)
     # @param session [Symbol, nil] the session's own level (Session#reasoning_history)
     # @return [Array(Symbol, String|nil)]
-    def resolve(target, names:, models: nil, session: nil)
+    def resolve(lookup, session: nil)
       return [session, SESSION_SOURCE] if session
 
-      env = env_level
+      env = env_level(lookup)
       return [env, ENV_NAME] if env
 
-      models ||= begin
-        ConfigFile.model_settings
-      rescue StandardError
-        {}
-      end
-      setting = ConfigFile.model_setting(names, :reasoning_history, models: models)
+      setting = lookup.model(:reasoning_history)
       return [setting.value, "models: #{setting.key}"] if setting
 
-      host = target.entry&.reasoning_history
-      return [host, "hosts.#{target.entry.name}"] if host
+      host = lookup.host(:reasoning_history)
+      return [host, "hosts.#{lookup.host_name}"] if host
 
-      [API_DEFAULTS.fetch(target.entry&.api&.to_sym, DEFAULT), nil]
+      [API_DEFAULTS.fetch(lookup.entry&.api&.to_sym, DEFAULT), nil]
     end
 
     # #resolve, as a SettingExplained with the session's own level beside it.
     # @return [SettingExplained]
-    def explain(target, names:, models: nil, session: nil)
-      level, source = resolve(target, names: names, models: models, session: session)
+    def explain(lookup, session: nil)
+      level, source = resolve(lookup, session: session)
       SettingExplained.new(level: level, source: source, own: session)
     end
 
@@ -150,9 +143,10 @@ module Samagotchi
     # "drop (models: qwen)", "turn (default)".
     def label(level, source) = "#{level} (#{source || "default"})"
 
-    # SAMAGOTCHI_REASONING_HISTORY as a level, nil when unset or unknown.
-    def env_level
-      raw, origin = Config.get_with_origin(KEY)
+    # SAMAGOTCHI_REASONING_HISTORY (read with +lookup+'s env) as a level,
+    # nil when unset or unknown.
+    def env_level(lookup)
+      raw, origin = lookup.global(KEY)
       origin == :env ? level(raw, ENV_NAME) : nil
     rescue StandardError
       nil

data/lib/samagotchi/recap_place.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "steer"
+require_relative "bridge/card_places"
+
+module Samagotchi
+  # Where a saved recap sits among the turns a page draws: after the last
+  # turn opening it covers (Steer.turn_opening?, the rule its turns_since
+  # count goes by). Its stamp is that opening's id, as a card's is
+  # (Bridge::CardPlaces.stamp: a prompt's turn_id, a wake note's, a
+  # /continue no reason line's opening_id), so the page finds the bubble by
+  # id, not by counting back (a rollback or a check-in could make the count
+  # land a turn off). Read at read time from recap.json's `covered`: the file
+  # is unchanged, an old one gets a stamp too. Pure.
+  module RecapPlace
+    module_function
+
+    # @param messages [Array<Hash>] the session's messages (symbol or string keys)
+    # @param covered [Integer] how many of them the recap covers
+    # @return [String, nil] the id of the last opening in the covered
+    #   messages; nil for none, or one with no id (a line an older chi wrote)
+    def opening_id(messages, covered)
+      opening = Array(messages).first([covered.to_i, 0].max).reverse_each.find { |message| Steer.turn_opening?(message) }
+      opening && Bridge::CardPlaces.stamp(opening)
+    end
+  end
+end

data/lib/samagotchi/reminder_carry.rb

@@ -15,7 +15,7 @@ module Samagotchi
   # restart writes one: a stop, an idle exit, a crash and a fallback restart
   # (a TERM) drop the reminders as before, and a stop or an archive removes a
   # file left behind (SessionManager.stop_session, .archive_session); a
-  # restart a stop landed on starts no successor (.run_session_loop). A file is honoured only by the same
+  # restart a stop landed on starts no successor (WorkerBoot.run_session_loop). A file is honoured only by the same
   # session, within WINDOW of its writing (a successor starts in seconds), so
   # one no successor read can't bring reminders back a day later.
   module ReminderCarry

data/lib/samagotchi/reply_wait/liveness.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../worker_link"
+
+module Samagotchi
+  module ReplyWait
+    # Who runs the session, as one look of a wait reads it: one owner lock
+    # read and one WorkerLink resolve on it. Two readers on purpose:
+    # #owner? (any kind, a one-turn chi run's too: its turn is alive) for
+    # whether the worker is gone, #worker_owned? (a worker's lock) for
+    # whether a question waits for an answer (a one-turn run's is answered
+    # there; a dead worker's waits for no one).
+    class Liveness
+      def initialize(id, state_dir:)
+        @id = id
+        @state_dir = state_dir
+      end
+
+      # The lock's holder (SessionManager.session_owner).
+      # @return [OwnerLock::Owner, nil]
+      def owner
+        return @owner if defined?(@owner)
+
+        @owner = SessionManager.session_owner(@id, state_dir: @state_dir)
+      end
+
+      def owner? = !owner.nil?
+
+      def worker_owned?
+        return @worker_owned if defined?(@worker_owned)
+
+        @worker_owned = WorkerLink.resolve(Session.session_dir(@id, state_dir: @state_dir), unlink: false,
+                                                           owner: owner).worker_owned?
+      end
+    end
+  end
+end

data/lib/samagotchi/reply_wait/poll.rb

@@ -5,7 +5,7 @@ require_relative "../session_inbox"
 require_relative "../turn_checkpoint"
 require_relative "../continue_offer"
 require_relative "../steer"
-require_relative "../worker_link"
+require_relative "liveness"
 
 module Samagotchi
   module ReplyWait
@@ -72,13 +72,17 @@ module Samagotchi
       # @return [Result, nil]
       def look
         look_at_input
+        # Before the load: the turn it names began before what the load sees.
+        merge = merge_record
         session = Session.load(@id, state_dir: @state_dir)
+        # Who runs it, read once for this look's checks.
+        @live = Liveness.new(@id, state_dir: @state_dir)
         if (result = removed(session))
           return result
         end
 
         note_own_running(session)
-        follow_merge(session)
+        follow_merge(session, merge)
         reply(session) || settled_turn(session) || status_end(session) || question(session) || held(session) || canceled ||
           ended_before_reply(session) || ended_before_turn(session) || turn_end(session) || owner_gone(session) ||
           message_waiting || timed_out
@@ -106,8 +110,11 @@ module Samagotchi
         Result.new(status: :no_reply, outcome: "removed", session: session)
       end
 
+      # Its turn ran, or a drain merged it (its merge record): a dequeue's
+      # tombstone that lost the claim to the drain is a stray too.
       def turn_ran?(session)
-        session.last_turn&.enqueued_id == @turn || !SessionInbox.reply_for(@session_dir, @turn).nil?
+        session.last_turn&.enqueued_id == @turn || !SessionInbox.reply_for(@session_dir, @turn).nil? ||
+          !SessionInbox.merged_into(@session_dir, @turn).nil?
       end
 
       def note_own_running(session)
@@ -119,14 +126,37 @@ module Samagotchi
 
       # Taken but never run as a turn of its own: a running turn's drain
       # merged it as a steer, so that turn's reply (or question) is its
-      # answer. Waited for as the next reply past the cursor, as without
-      # turn:, never as a turn that will not come.
-      def follow_merge(session)
-        return unless @turn && @claimed && !@seen_own && !@own_turn_input &&
-                      ReplyWait.merged_elsewhere?(session, @turn, @baseline, @session_dir)
-
-        @turn = nil
-        @seen_running = running?(session)
+      # answer. With the drain's merge record (SessionInbox.mark_merged)
+      # the wait is that turn's from here on, as if it had been bound to it
+      # (#follow_into). Without one (a 0.156 worker, a turn with no id, a
+      # merge from before the update) the merge is inferred
+      # (ReplyWait.merged_elsewhere?) and waited for as the next reply past
+      # the cursor, as without turn:, never as a turn that will not come.
+      def follow_merge(session, merge)
+        return unless may_follow?
+
+        if merge
+          follow_into(session, merge)
+        elsif ReplyWait.merged_elsewhere?(session, @turn, @baseline, @session_dir)
+          @turn = nil
+          @seen_running = running?(session)
+        end
+      end
+
+      def may_follow? = @turn && @claimed && !@seen_own && !@own_turn_input
+
+      def merge_record = may_follow? ? SessionInbox.merged_into(@session_dir, @turn) : nil
+
+      # Bound to the turn that took it, once (its own input ran as its own
+      # turn). Not running in this look, which loaded after the record:
+      # that turn is over (its end, its reply, its settle say how), and a
+      # turn that ended after the merge with last_turn not its is past it
+      # (#own_turn_end).
+      def follow_into(session, merge)
+        @turn = merge.into
+        @own_turn_input = true
+        note_own_running(session)
+        @merged_at = merge.at unless @seen_own
       end
 
       def reply(session)
@@ -172,9 +202,7 @@ module Samagotchi
       end
 
       # A worker holds the session's lock (a one-turn chi run's question is its own).
-      def worker_owned?
-        WorkerLink.resolve(Session.session_dir(@id, state_dir: @state_dir), unlink: false).worker_owned?
-      end
+      def worker_owned? = @live.worker_owned?
 
       # A participant's turn its worker holds while the owner's Continue
       # offer stands (Worker#run_input_files): it waits for the owner's
@@ -273,6 +301,7 @@ module Samagotchi
         # died), or it ended with no reply and a next turn ran and ended
         # between two looks. Waiting on would sit through those turns.
         return Result.new(status: :no_reply, session: session) if @seen_own && ReplyWait.past_own?(session, @turn, @own_base)
+        return Result.new(status: :no_reply, session: session) if @merged_at && ReplyWait.ended_after?(session, @merged_at)
 
         nil
       end
@@ -307,7 +336,7 @@ module Samagotchi
       def owner_gone(session)
         return nil unless @owner_grace
 
-        if SessionManager.session_owner(@id, state_dir: @state_dir)
+        if @live.owner?
           @gone_since = nil
         elsif ReplyWait.monotonic - (@gone_since ||= ReplyWait.monotonic) > @owner_grace
           return Result.new(status: :worker_gone, session: session)

data/lib/samagotchi/reply_wait/target.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../delivery"
+require_relative "../session"
+
+module Samagotchi
+  module ReplyWait
+    # Which turn a reply wait waits for, and how: the one binding every
+    # caller builds (chi send --wait, chi answer, a participant's wait, the
+    # delegate tools and a delegate report), each with its constructor.
+    # #to_h is ReplyWait.call's kwargs (+cursor+, +baseline+,
+    # +owner_grace+, +turn+, +queued+, +ended_before+: ReplyWait.call's
+    # parameters say what each means); +report_turn_id+ (the turn_id of
+    # --format json's line, ParentWait's) is read on its own.
+    Target = Data.define(:turn, :report_turn_id, :queued, :ended_before, :cursor, :baseline, :owner_grace) do
+      def initialize(turn: nil, report_turn_id: nil, queued: false, ended_before: false, cursor: nil, baseline: nil,
+                     owner_grace: nil)
+        super
+      end
+
+      # A --new session's first message: its own turn, the ack's id (a
+      # file-delivered one's also names the outcome of a session command
+      # that runs no turn), so a worker that dies in it and the next one's
+      # settle end the wait (TurnCheckpoint.settled_turn). A message merged
+      # into a turn starting then falls back to that turn's reply
+      # (ReplyWait's turn: without queued:); no id (an older worker), the
+      # next reply. A prompt the session was created with has no delivery:
+      # its turn is the id the create gave it (+direct_turn+,
+      # Session#first_turn_id), and nothing can merge into it, so the wait
+      # is for that turn alone (ReplyWait's queued:).
+      # @param start [SessionAccess::WaitStart] prepare_wait's (its cursor
+      #   and baseline)
+      # @param delivered [SessionManager::DeliverResult, nil] nil when the
+      #   message started the session itself (no delivery)
+      # @param direct_turn [String, nil] that first turn's id, for a direct
+      #   start
+      def self.first_message(start, delivered, direct_turn: nil)
+        reads = { cursor: start&.cursor, baseline: start&.baseline, owner_grace: ReplyWait::GONE_AFTER }
+        return new(**reads) unless delivered || !direct_turn.to_s.strip.empty?
+
+        return new(turn: direct_turn, report_turn_id: direct_turn, queued: true, **reads) if delivered.nil?
+
+        new(turn: delivered.enqueued_id, report_turn_id: delivered.enqueued_id, **reads)
+      end
+
+      # A message to an existing session: its own turn, the ack's id. With
+      # --queue it runs as that turn, also when the turn running at the
+      # check ended before it went in (an idle worker's ack says next_step,
+      # and the file still runs as that turn). A plain one may run as its
+      # own turn or merge into a running one (a session left running by a
+      # dead worker, the busy check's owner gone; or a turn starting then):
+      # that turn's end is its answer (ReplyWait's follow_merge). A plain
+      # message the worker queued (its ack says queue: a participant's
+      # review turn was running, which takes no steer) is a --queue's. An
+      # ack with no id (an older worker): the next reply, reported as the
+      # turn that was running when it went in (start's own_turn).
+      # @param start [SessionAccess::WaitStart] read before it went in (its
+      #   running says the session was running then)
+      def self.message(start, delivered, queue:)
+        queue ||= delivered.delivery == Delivery::QUEUE
+        turn = delivered.enqueued_id
+        new(turn: turn, report_turn_id: turn || (start.own_turn if start.running && !queue), queued: queue && !turn.nil?,
+            cursor: start.cursor, baseline: start.baseline, owner_grace: ReplyWait::GONE_AFTER)
+      end
+
+      # --wait with no message: --turn's (+requested+), or the turn running
+      # now or whose continue offer stands (start's own_turn,
+      # ReplyWait.own_turn). Settled (idle, a turn ended, no question
+      # standing: a continue offer waits for its answer), its last turn's
+      # end is the answer (ended_before); with --turn, when that turn is the
+      # last one. A session no worker runs waits for whatever wakes one (no
+      # owner_grace).
+      # @param start [SessionAccess::WaitStart]
+      def self.wait_only(start, requested:)
+        turn = requested || start.own_turn
+        ended_before = requested ? start.last_turn_id == requested : start.settled
+        new(turn: turn, report_turn_id: turn || (start.last_turn_id if start.settled), ended_before: ended_before,
+            cursor: start.cursor, baseline: start.baseline, owner_grace: start.live ? ReplyWait::GONE_AFTER : nil)
+      end
+
+      # chi answer: the turn the question is about (start's own_turn: the
+      # one running, or the one whose continue offer stands), else the next
+      # reply.
+      def self.answer(start)
+        new(turn: start.own_turn, report_turn_id: start.own_turn, cursor: start.cursor, baseline: start.baseline,
+            owner_grace: ReplyWait::GONE_AFTER)
+      end
+
+      # A participant's --wait -m: their review turn just queued (+turn+),
+      # as --wait --turn T (their wait routes take only a turn of theirs).
+      def self.participant(start, turn:) = wait_only(start, requested: turn)
+
+      # A delegate's wait (DelegateWait, a delegate report) from the
+      # parent's DelegateCursor: the newest reply it was given, the child as
+      # it was then, and the turn a follow-up joined. The child's first turn
+      # (Session#first_turn_id: the prompt it was spawned with) runs as its
+      # own and nothing merges into it, so a wait bound to it is queued.
+      # @param cursor [Tools::DelegateCursor]
+      # @param child [Session, nil] the child as read now (its first_turn_id)
+      # @param owner_grace [Numeric, nil] nil: no gone check (a report's
+      #   look)
+      def self.from_cursor(cursor, child:, owner_grace: nil)
+        first = child&.first_turn_id
+        new(turn: cursor.turn, cursor: cursor.reply_file, baseline: cursor.baseline, owner_grace: owner_grace,
+            queued: !cursor.turn.to_s.empty? && cursor.turn == first)
+      end
+
+      # ReplyWait.call's kwargs (report_turn_id is ParentWait's, not one).
+      def to_h = { cursor: cursor, baseline: baseline, owner_grace: owner_grace, turn: turn, queued: queued,
+                   ended_before: ended_before }
+    end
+  end
+end

data/lib/samagotchi/reply_wait.rb

@@ -6,6 +6,7 @@ require_relative "session_inbox"
 require_relative "turn_checkpoint"
 require_relative "worker_link"
 require_relative "reply_wait/poll"
+require_relative "reply_wait/target"
 
 module Samagotchi
   # Loaded on first use: this autoload keeps SessionManager and its ~80
@@ -21,6 +22,12 @@ module Samagotchi
   # The delegate tools and `chi send --wait` wrap it in their own words.
   module ReplyWait
     POLL_INTERVAL = 0.5
+    # The one dead-worker rule: no owner of any kind this long while
+    # waiting (a Target's owner_grace) and the worker is gone (it died
+    # before it could mark the session). A caller that just spawned or woke
+    # a worker awaits it first (Tools::Delegate.await_worker,
+    # SendCommand#deliver_new), so a booting worker isn't read as gone.
+    GONE_AFTER = 5
     # A worker's sidecar feature (Bridge::FEATURES): its running turn's
     # checkpoint mark (InterruptedTurn#enqueued_id), a continue turn and a
     # Stop's last_turn carry the turn's enqueued_id (#own_turn).
@@ -209,7 +216,8 @@ module Samagotchi
     end
 
     # Whether +turn+ is a turn the caller can wait for: running now, queued
-    # as its own turn, or the last one to have ended.
+    # as its own turn, the last one to have ended, or an input a turn's
+    # drain merged (its merge record: the wait follows it to that turn).
     def known_turn?(session, session_dir:, turn:)
       id = turn.to_s
       return false if id.empty?
@@ -217,7 +225,7 @@ module Samagotchi
       running = session.status == Session::STATUS_RUNNING && session.interrupted_turn&.enqueued_id == id
       queued = SessionInbox.waiting_input(session_dir, id) == :turn_end
       ended = session.last_turn&.enqueued_id == id || !TurnCheckpoint.settled_turn(session_dir, id).nil?
-      running || queued || ended
+      running || queued || ended || !SessionInbox.merged_into(session_dir, id).nil?
     end
 
     # Whether the session's live worker names TURN_IDS_FEATURE.
@@ -287,6 +295,18 @@ module Samagotchi
       !ended.nil? && ended != own_base
     end
 
+    # Whether the session's last turn ended after +at+ (a Time): a turn
+    # that isn't own_turn_end's (its last_turn is checked first) ended
+    # after the turn a merge record named began, so that turn is over.
+    # Clock skew can't fire it: +at+ and every ended_at come from the
+    # same machine's clock (its workers'; a remote wait's Poll runs there).
+    def ended_after?(session, at)
+      ended = session.last_turn&.ended_at
+      !ended.to_s.empty? && Time.iso8601(ended.to_s) > at
+    rescue ArgumentError
+      false
+    end
+
     # @return [Result, nil] :done with the reply of the turn that ran the
     #   input +turn+ (its enqueued_id)
     def reply_for_turn(id, state_dir:, turn:)

data/lib/samagotchi/reprefill_meter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "token_usage"
+
+module Samagotchi
+  # A request's re-prefilled tokens, for both loops: of the prompt the last
+  # request on the same model through the same client (the host) sent, what
+  # the server didn't reuse from its cache this time (that prompt less the
+  # cached count), so an LLM context edit's cache break shows, and so does
+  # anything else that rewrote the prompt's middle or lost the cache.
+  #
+  # One per Engine, given to its KernelLoop and its ChatLoop, so the
+  # baseline is the last request's whichever loop sent it: a switch to
+  # another host and back starts over on the way back. A bare loop (a spec,
+  # a bench) builds its own. Read and written on the turn's thread only
+  # (each loop's completed generation; the turn-end warm-up's #reset!).
+  class ReprefillMeter
+    # The last counted request: its model, its client, its prompt tokens.
+    Baseline = Data.define(:model, :client, :prompt)
+
+    # The tokens the server prefilled again for this request (+prompt+ and
+    # +cached+, its counts), and this request becomes the baseline. nil
+    # under TokenUsage::REPREFILL_MIN_TOKENS (a cache block's rounding), for
+    # a server that reports no cached count (or 0: a cold cache isn't told
+    # from no cache), the first request, a model switch (another bare model,
+    # or the same one on another host's +client+: SessionMetrics counts that
+    # prefill as the switch's), and the first request after #reset!.
+    # @return [Integer, nil]
+    def tokens(model, client:, prompt:, cached:)
+      previous = @baseline
+      @baseline = Baseline.new(model: model, client: client, prompt: prompt.to_i) if prompt.to_i.positive?
+      return nil unless previous && previous.model == model && previous.client.equal?(client) && cached.to_i.positive?
+
+      tokens = previous.prompt - cached.to_i
+      tokens >= TokenUsage::REPREFILL_MIN_TOKENS ? tokens : nil
+    end
+
+    # A turn-end warm-up prefilled the next prompt off the clock, so the
+    # next request's cache counts are against it, not the last request:
+    # start over (KernelLoop#warmed_up!).
+    def reset!
+      @baseline = nil
+    end
+  end
+end

data/lib/samagotchi/review_command.rb

@@ -64,7 +64,7 @@ module Samagotchi
     rescue ModelProfile::MissingModel, Toolkit::Refused => e
       refused("could not start: #{e.message}")
     rescue ArgumentError => e
-      refused(e.is_a?(Session::AmbiguousId) ? e.message : e.message.sub(/\ASession not found: /, "no session "))
+      refused(e.message)
     end
 
     private

data/lib/samagotchi/sampling_settings.rb

@@ -11,18 +11,16 @@ module Samagotchi
   module SamplingSettings
     EMPTY = {}.freeze
 
-    # @param target [HostRegistry::ModelTarget]
-    # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param lookup [ModelLookup] the model's layers (EffectiveModel#lookup)
     # @return [Hash] frozen, symbol keys; may be empty
-    def self.for(target, names:, models: nil)
-      resolve(target, names, models).first
+    def self.for(lookup)
+      resolve(lookup).first
     end
 
     # "temperature=0.6 presence_penalty=1.5 (hosts.work, models: qwen)" for
     # /model, or nil when nothing is configured.
-    def self.summary(target, names:, models: nil)
-      params, sources = resolve(target, names, models)
+    def self.summary(lookup)
+      params, sources = resolve(lookup)
       return nil if params.empty?
 
       pairs = params.map { |key, value| "#{key}=#{value.nil? ? "(not sent)" : value.inspect}" }
@@ -37,16 +35,11 @@ module Samagotchi
       fields.map { |key, value| "#{key}=#{value.is_a?(String) ? value : JSON.generate(value)}" }.join(" ")
     end
 
-    def self.resolve(target, names, models)
-      models ||= begin
-        ConfigFile.model_settings
-      rescue StandardError
-        {}
-      end
-      host = target.entry.sampling || EMPTY
-      model = ConfigFile.model_setting(names, :sampling, models: models)
+    def self.resolve(lookup)
+      host = lookup.host(:sampling) || EMPTY
+      model = lookup.model(:sampling)
       sources = []
-      sources << "hosts.#{target.entry.name}" unless host.empty?
+      sources << "hosts.#{lookup.host_name}" unless host.empty?
       sources << "models: #{model.key}" if model
       [host.merge(model&.value || EMPTY).freeze, sources]
     end