samagotchi 0.80.0 → 0.82.0

data/lib/samagotchi/send_command.rb

@@ -43,7 +43,7 @@ module Samagotchi
              chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT] [--image PATH]...
              chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
              chi send --queue --wait [--timeout S] [--format json] [-m TEXT] ID
-             chi send --wait [--timeout S] [--format json] ID
+             chi send --wait [--timeout S] [--format json] [--turn T] ID
         Sends a message to each session, as if typed in it: a turn starts,
         or a running one takes it at its next step. A stopped session's
         worker starts.
@@ -91,7 +91,10 @@ module Samagotchi
                     the web). With no message (no -m, nothing piped)
                     nothing is sent: it waits for the session's next
                     reply, a running turn's too (after exit 3, 4 or 130,
-                    wait again this way)
+                    wait again this way). To an idle session whose last
+                    turn already ended, that ended turn is the answer:
+                    its reply, or its end when it left none. --turn T
+                    waits for that running, queued or last-ended turn
         --cut       ask the running turn to cut the generation it is
                     streaming and take the message now (a generation that
                     has streamed only thinking for steer.cut_after; else
@@ -108,10 +111,12 @@ module Samagotchi
                     than queueing (it would steer; restart it)
         --timeout S (--wait) give up after S seconds, exit 4 (the turn
                     goes on); default no limit
+        --turn T    (--wait, no message) wait for this turn id, from the
+                    JSON's turn_id; not with -m
         --format json
                     (--wait) one JSON object on stdout, whatever the end:
                     status answered (text), question (question,
-                    answer_with), running, or failed, canceled,
+                    answer_with), turn_id when known, running, or failed, canceled,
                     limit, no_answer, error, worker_gone, stopped,
                     command (detail); with --cut or --queue also
                     delivery (what the worker applied: next_step, cut,
@@ -142,6 +147,7 @@ module Samagotchi
       f.switch "--queue"
       f.value "--timeout"
       f.value "--format"
+      f.value "--turn"
       # Starting a turn in every live session at once is too easy to do
       # by accident.
       f.refuse "--all", "there is no --all: name the sessions"
@@ -204,6 +210,7 @@ module Samagotchi
       prompt = compose(utf8(read_stdin), utf8(options[:message]))
       # Before the wait-only case, which would drop the images.
       return usage_error("--image needs a message: pass -m TEXT or pipe it in") if prompt.nil? && !options[:images].empty?
+      return usage_error("--turn cannot be used with a message") if options[:turn] && prompt
       return run_wait_only(options) if prompt.nil? && options[:wait] && !options[:new]
 
       # The next link of a chain may start idle, waiting for its first message.
@@ -268,6 +275,8 @@ module Samagotchi
         options[:timeout] = Float(options[:timeout], exception: false)
         return usage_error("--timeout takes seconds") unless options[:timeout]&.positive?
       end
+      return usage_error("--turn needs --wait") if options[:turn] && !options[:wait]
+      return usage_error("--turn is only for waiting without a message") if options[:turn] && (options[:new] || options[:queue] || options[:cut])
       return usage_error("--wait takes one session") if options[:wait] && options[:ids].uniq.size > 1
       return usage_error("at most #{MAX_IMAGES} images") if options[:images].size > MAX_IMAGES
       return new_options(options) if options[:new]
@@ -388,7 +397,7 @@ module Samagotchi
       return report_command(session.id) if @sent_command
 
       wait_for_reply(session.id, cursor: nil, baseline: baseline_of(session, question_id: nil),
-                                 timeout: options[:timeout])
+                                 timeout: options[:timeout], report_turn_id: @sent_enqueued_id)
     end
 
     # The model the new session will run, for the images check: --model
@@ -450,6 +459,9 @@ module Samagotchi
 
       cursor = ReplyWait.newest_reply(id, state_dir: @state_dir)
       baseline = baseline_of(session)
+      running_turn = if session.status == Session::STATUS_RUNNING
+                       ReplyWait.own_turn(session, session_dir: Session.session_dir(id, state_dir: @state_dir))
+                     end
       return 1 unless deliver(id, prompt)
       return report_command(id) if @sent_command
 
@@ -457,7 +469,15 @@ module Samagotchi
       # 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).
       turn = @queue ? @sent_enqueued_id : nil
-      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout], turn: turn, queued: !turn.nil?)
+      report_turn_id = if @queue
+                         turn
+                       elsif session.status == Session::STATUS_RUNNING
+                         running_turn
+                       else
+                         @sent_enqueued_id
+                       end
+      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout], turn: turn, queued: !turn.nil?,
+                          report_turn_id: report_turn_id)
     end
 
     # --wait with no message: the session's next reply, sending nothing,
@@ -468,16 +488,33 @@ module Samagotchi
     # waits for whatever wakes one (the web, chi send) rather than calling
     # it gone. The turn running now, or the one whose continue offer
     # stands, is the one waited for (ReplyWait.own_turn): its reply, not a
-    # turn's queued behind it; with none known, the next reply.
+    # turn's queued behind it; with none known, the next reply. An idle
+    # session whose last turn already ended (no question standing) went
+    # idle in the gap between waits: that turn's end is the answer — its
+    # reply, or its no-reply outcome — so the wait returns it at once
+    # (ReplyWait's ended_before:) instead of timing out "running" again.
     # @return [Integer] the exit status
     def run_wait_only(options)
       id = resolve(options[:ids].first) or return 1
       session = Session.load(id, state_dir: @state_dir)
+      session_dir = Session.session_dir(id, state_dir: @state_dir)
+      requested_turn = options[:turn]&.to_s
+      if requested_turn && !ReplyWait.known_turn?(session, session_dir: session_dir, turn: requested_turn)
+        error_line("chi send: turn #{requested_turn} is not a running, queued, or last ended turn")
+        return 1
+      end
       live = session.status == Session::STATUS_RUNNING || SessionManager.session_owner(id, state_dir: @state_dir)
-      turn = ReplyWait.own_turn(session, session_dir: Session.session_dir(id, state_dir: @state_dir))
+      turn = requested_turn || ReplyWait.own_turn(session, session_dir: session_dir)
+      # The gate for the settled case: idle, a turn ended (last_turn), no
+      # question standing (a continue offer waits for its answer).
+      settled = session.status == Session::STATUS_IDLE && session.last_turn && session.pending_question.nil?
+      ended_before = requested_turn ? session.last_turn&.enqueued_id == requested_turn : settled
+      report_turn_id = turn
+      report_turn_id ||= session.last_turn&.enqueued_id if settled
       wait_for_reply(id, cursor: ReplyWait.newest_reply(id, state_dir: @state_dir),
                          baseline: baseline_of(session).merge(messages: nil),
-                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil, turn: turn)
+                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil,
+                         turn: turn, ended_before: ended_before, report_turn_id: report_turn_id)
     end
 
     # The session as it was before the message went in (ReplyWait's
@@ -514,6 +551,8 @@ module Samagotchi
         return false
       end
 
+      ack = result[:ack].is_a?(Hash) ? result[:ack] : {}
+      @sent_enqueued_id = (ack["enqueued_id"] || ack[:enqueued_id])&.to_s
       @sent_command = command_ack?(result[:ack])
       @info.puts("#{session.id}  started#{continued_words(session)}#{with_images}#{"; #{SENT_COMMAND}" if @sent_command}")
       true

data/lib/samagotchi/session_metrics/side_totals.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "../model_price"
+
+module Samagotchi
+  class SessionMetrics
+    # The sums over a session's side requests (SideUsage: an idle recap, a
+    # plugin's ctx.ask_model such as /btw), kept apart from its turns'
+    # Totals: the snapshot's and analytics.json's +side+ block, never in
+    # +tokens+ or +model_segments+. They have no records: the block itself
+    # is saved and loaded (#to_h, .from_saved).
+    # +cost_sum+ is nil until a request reports a cost (a reported 0
+    # included), +cost_estimate_sum+ 0 until one is estimated from a price
+    # (ModelPrice.estimate, the turns' rule). +by_kind+ is a frozen Hash
+    # kind => {requests:, cost_sum:, cost_estimate_sum:} in first-seen order.
+    class SideTotals < Data.define(:requests, :prompt_sum, :completion_sum, :cached_sum, :cache_write_sum,
+                                   :reasoning_sum, :cost_sum, :cost_estimate_sum, :by_kind)
+      # The counts summed as they are (the costs and by_kind apart).
+      COUNTS = %i[requests prompt_sum completion_sum cached_sum cache_write_sum reasoning_sum].freeze
+
+      def self.zero
+        new(**COUNTS.to_h { |key| [key, 0] }, cost_sum: nil, cost_estimate_sum: 0, by_kind: {}.freeze)
+      end
+
+      # The block as analytics.json saved it (string keys): a non-Hash is
+      # zero totals, a missing or non-numeric count 0, a missing or null
+      # cost_sum nil.
+      # @param hash [Hash, nil]
+      # @return [SideTotals]
+      def self.from_saved(hash)
+        return zero unless hash.is_a?(Hash)
+
+        hash = hash.transform_keys(&:to_s)
+        new(
+          **COUNTS.to_h { |key| [key, count(hash[key.to_s])] },
+          cost_sum: cost(hash["cost_sum"]),
+          cost_estimate_sum: number(hash["cost_estimate_sum"]),
+          by_kind: saved_kinds(hash["by_kind"])
+        )
+      end
+
+      def self.saved_kinds(hash)
+        kinds = hash.is_a?(Hash) ? hash : {}
+        kinds.each_with_object({}) do |(kind, row), rows|
+          row = row.is_a?(Hash) ? row.transform_keys(&:to_s) : {}
+          rows[kind.to_s] = { requests: count(row["requests"]), cost_sum: cost(row["cost_sum"]),
+                              cost_estimate_sum: number(row["cost_estimate_sum"]) }.freeze
+        end.freeze
+      end
+
+      # These totals with one side request counted in.
+      # @param usage [SideUsage]
+      # @return [SideTotals]
+      def add(usage)
+        estimate = ModelPrice.estimate(usage.price, reported_cost: usage.cost, prompt_tokens: usage.prompt_tokens,
+                                                    cached_tokens: usage.cached_tokens,
+                                                    cache_write_tokens: usage.cache_write_tokens,
+                                                    completion_tokens: usage.completion_tokens)
+        one = { requests: 1, cost_sum: usage.cost&.to_f, cost_estimate_sum: estimate || 0 }
+        kind = usage.kind.to_s
+        rows = by_kind.merge(kind => sum_row(by_kind[kind], one))
+        with(requests: requests + 1, prompt_sum: prompt_sum + usage.prompt_tokens.to_i,
+             completion_sum: completion_sum + usage.completion_tokens.to_i,
+             cached_sum: cached_sum + usage.cached_tokens.to_i,
+             cache_write_sum: cache_write_sum + usage.cache_write_tokens.to_i,
+             reasoning_sum: reasoning_sum + usage.reasoning_tokens.to_i,
+             cost_sum: add_cost(cost_sum, one[:cost_sum]),
+             cost_estimate_sum: cost_estimate_sum + one[:cost_estimate_sum], by_kind: rows.freeze)
+      end
+
+      # These totals with +other+'s added (a loaded block and the requests
+      # counted before the load); the kinds in first-seen order, these first.
+      # @param other [SideTotals]
+      # @return [SideTotals]
+      def merge(other)
+        rows = other.by_kind.each_with_object(by_kind.dup) { |(kind, row), all| all[kind] = sum_row(all[kind], row) }
+        with(**COUNTS.to_h { |key| [key, public_send(key) + other.public_send(key)] },
+             cost_sum: add_cost(cost_sum, other.cost_sum),
+             cost_estimate_sum: cost_estimate_sum + other.cost_estimate_sum, by_kind: rows.freeze)
+      end
+
+      def empty? = requests.zero?
+
+      # The snapshot's side block (symbol keys; by_kind keyed by kind).
+      # @return [Hash]
+      def to_h
+        counts = COUNTS.to_h { |key| [key, public_send(key)] }
+        counts.merge(cost_sum: cost_sum, cost_estimate_sum: cost_estimate_sum, by_kind: by_kind.transform_values(&:dup))
+      end
+
+      def self.count(value) = value.is_a?(Numeric) ? value.to_i : 0
+
+      def self.number(value) = value.is_a?(Numeric) ? value : 0
+
+      def self.cost(value) = value.is_a?(Numeric) ? value : nil
+
+      private_class_method :count, :number, :cost, :saved_kinds
+
+      private
+
+      def sum_row(row, one)
+        return one.dup.freeze unless row
+
+        { requests: row[:requests] + one[:requests], cost_sum: add_cost(row[:cost_sum], one[:cost_sum]),
+          cost_estimate_sum: row[:cost_estimate_sum] + one[:cost_estimate_sum] }.freeze
+      end
+
+      # nil + nil stays nil (no cost reported yet); a reported one sums.
+      def add_cost(left, right)
+        return left if right.nil?
+        return right if left.nil?
+
+        left + right
+      end
+    end
+  end
+end

data/lib/samagotchi/session_metrics.rb

@@ -12,6 +12,8 @@ require_relative "model_price"
 require_relative "session"
 require_relative "session_metrics/totals"
 require_relative "session_metrics/model_segment"
+require_relative "session_metrics/side_totals"
+require_relative "side_usage"
 
 module Samagotchi
   # SessionMetrics is a persistent, error-isolated collector of per-session
@@ -65,11 +67,14 @@ module Samagotchi
     # nil when an older file has none.
     # cost_estimate_sum: the estimated cost (hosts.<name>.models prices), 0
     # in an older file.
+    # side: the side requests' block (SideTotals#to_h as saved, string
+    # keys), nil when the session made none (or an older file).
     SavedSummary = Data.define(:ctx_pct, :prompt_sum, :completion_sum, :cached_sum, :reasoning_sum, :cost_sum,
-                               :cost_estimate_sum, :memory_index) do
-      def initialize(memory_index: nil, cost_estimate_sum: 0, **) = super
+                               :cost_estimate_sum, :memory_index, :side) do
+      def initialize(memory_index: nil, cost_estimate_sum: 0, side: nil, **) = super
 
-      def tokens = to_h.except(:ctx_pct, :memory_index)
+      # The turns' token totals (the side requests' are #side, apart).
+      def tokens = to_h.except(:ctx_pct, :memory_index, :side)
     end
 
     # Per-turn transient state, reset on each turn_started.
@@ -199,7 +204,8 @@ module Samagotchi
                        completion_sum: count.call("completion_sum"), cached_sum: count.call("cached_sum"),
                        reasoning_sum: count.call("reasoning_sum"), cost_sum: count.call("cost_sum"),
                        cost_estimate_sum: count.call("cost_estimate_sum"),
-                       memory_index: data["memory_index"].is_a?(Hash) ? data["memory_index"] : nil)
+                       memory_index: data["memory_index"].is_a?(Hash) ? data["memory_index"] : nil,
+                       side: data["side"].is_a?(Hash) ? data["side"] : nil)
     rescue TypeError
       nil
     end
@@ -267,6 +273,10 @@ module Samagotchi
 
     def initialize(clock: nil, wall_clock: nil)
       @mutex = Monitor.new
+      # Serializes #persist (snapshot and write), so two threads' saves land
+      # in snapshot order. Taken before @mutex, never under it: the write's
+      # IO doesn't hold up the events.
+      @persist_mutex = Mutex.new
       @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
       @wall_clock = wall_clock || -> { Time.now }
       @session_id = nil
@@ -281,6 +291,9 @@ module Samagotchi
       # and how many were loaded (a woken collector's live records start empty).
       @persisted_turns = 0
       @loaded_turns = 0
+      # The side requests' sums: not in reset_totals, which a load's recount
+      # of the turn records calls (side requests have no records).
+      @side = SideTotals.zero
       reset_totals
     end
 
@@ -338,6 +351,20 @@ module Samagotchi
       end
     end
 
+    # @return [String, nil] the session id #persist writes under
+    def session_id = @mutex.synchronize { @session_id }
+
+    # Count one side request (a recap, a plugin's ctx.ask_model) in the
+    # side block, apart from the turns' totals. Safe from any thread.
+    # @param usage [SideUsage]
+    # @return [Hash] the side block now (SideTotals#to_h)
+    def add_side(usage)
+      @mutex.synchronize do
+        @side = @side.add(usage)
+        @side.to_h
+      end
+    end
+
     # Event sink. Safe to call from any thread; errors are isolated by the
     # caller (SessionObserver / TerminalUI) but we still guard internally.
     # @param event [Hash]
@@ -454,6 +481,15 @@ module Samagotchi
     #   turn's own end writes over it. Only the file has it.
     # @return [Boolean] true on success
     def persist(state_dir: nil, running_turn: false)
+      @persist_mutex.synchronize { persist_now(state_dir, running_turn) }
+    rescue StandardError
+      false
+    end
+
+    private
+
+    # #persist's work, under the persist mutex.
+    def persist_now(state_dir, running_turn)
       sid, data, turn_count = @mutex.synchronize do
         data = build_snapshot(:all).merge(active_turn: nil, active_tools: [])
         if running_turn && @turn
@@ -471,12 +507,8 @@ module Samagotchi
       AtomicFile.write(AnalyticsFile.path(dir), JSON.pretty_generate(data) + "\n")
       @mutex.synchronize { @persisted_turns = [@persisted_turns, turn_count].max }
       true
-    rescue StandardError
-      false
     end
 
-    private
-
     # Caller holds the mutex. +records+: :recent (the live snapshot) or :all
     # (analytics.json).
     def build_snapshot(records_mode)
@@ -502,6 +534,9 @@ module Samagotchi
         # The calls the model made under an alias's name (bash run as
         # execute), by its own spelling; only when there are any.
         **(@tool_tallies[:aliased].empty? ? {} : { tool_calls_aliased: @tool_tallies[:aliased].dup }),
+        # The side requests (recap, ctx.ask_model), apart from +tokens+;
+        # only when there were any.
+        **(@side.empty? ? {} : { side: @side.to_h }),
         tool_errors: @tool_tallies[:errors],
         iterations_total: totals.iterations,
         gen_latency_ms: totals.gen_ms.round,
@@ -791,10 +826,10 @@ module Samagotchi
       turn.cost_sum = turn.cost_sum.to_f + turn.gen_cost if turn.gen_cost
       # A reported cost wins; a reported 0 with a price is taken as no report
       # (a gateway that doesn't bill per call); the 0 stays in cost.
-      if turn.gen_price && (turn.gen_cost.nil? || turn.gen_cost.zero?)
-        turn.cost_estimate_sum += turn.gen_price.cost(prompt_tokens: turn.gen_prompt_max, cached_tokens: turn.gen_cached_max,
-                                                      cache_write_tokens: turn.gen_cache_write_max, completion_tokens: completion)
-      end
+      estimate = ModelPrice.estimate(turn.gen_price, reported_cost: turn.gen_cost, prompt_tokens: turn.gen_prompt_max,
+                                                     cached_tokens: turn.gen_cached_max,
+                                                     cache_write_tokens: turn.gen_cache_write_max, completion_tokens: completion)
+      turn.cost_estimate_sum += estimate if estimate
       turn.last_prefill_tps = turn.gen_prefill_tps.round(1) if turn.gen_prefill_tps
       speed = generation_speed(turn, completion)
       return unless speed
@@ -1098,6 +1133,8 @@ module Samagotchi
       end
       # The indexes the prompt last held, until this process builds its own.
       @memory_index ||= symbolized(prior["memory_index"]) if prior["memory_index"].is_a?(Hash)
+      # The saved side block, with any counted before the load after it.
+      @side = SideTotals.from_saved(prior["side"]).merge(@side)
       # The window last seen, until this process's first generation reports.
       window = prior["context"].is_a?(Hash) ? prior["context"] : {}
       return unless window["window_tokens"] && @context_window_tokens.nil?

data/lib/samagotchi/session_observer.rb

@@ -22,6 +22,9 @@ module Samagotchi
   #   * recap_ready — an idle session-recap finished generating
   #     (`recap:` prose, `generation:` id). Purely additive: it never mutates
   #     session.messages; each UI renders it (or not) however it likes.
+  #   * side_usage — a side request (the recap, a plugin's ctx.ask_model) was
+  #     counted (Engine#note_side_usage): `kind:` and `side:`, the session's
+  #     whole side block (SessionMetrics#add_side), in fold order.
   class SessionObserver
     # Handle returned by #subscribe. Holds the observer reference and carries
     # #unsubscribe so a caller can deregister without keeping the registry.

data/lib/samagotchi/side_usage.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # One side request's usage (an idle recap, a plugin's ctx.ask_model such
+  # as /btw): what IdleClient reports to its on_usage callback and
+  # SessionMetrics#add_side folds into the session's side line, apart from
+  # its turns' totals.
+  # @!attribute kind [String] "recap", or the asking bundle's name ("btw")
+  # @!attribute model [String] the target's model, for the log
+  # @!attribute prompt_tokens [Integer] 0 when not reported (and the rest)
+  # @!attribute completion_tokens [Integer]
+  # @!attribute cached_tokens [Integer]
+  # @!attribute cache_write_tokens [Integer]
+  # @!attribute reasoning_tokens [Integer]
+  # @!attribute cost [Float, nil] the provider's reported cost (OpenRouter's
+  #   usage.cost), nil when not reported
+  # @!attribute price [ModelPrice, nil] the target host's price for the
+  #   model (IdleTarget#price), what the cost is estimated from
+  SideUsage = Data.define(:kind, :model, :prompt_tokens, :completion_tokens, :cached_tokens, :cache_write_tokens,
+                          :reasoning_tokens, :cost, :price) do
+    def initialize(kind:, model: nil, prompt_tokens: 0, completion_tokens: 0, cached_tokens: 0, cache_write_tokens: 0,
+                   reasoning_tokens: 0, cost: nil, price: nil)
+      super
+    end
+
+    # A response's usage (LLM::Usage; Usage.none's zeros when the server
+    # reported no counts: still one request) as a side request's.
+    # @param usage [LLM::Usage, nil]
+    # @return [SideUsage]
+    def self.from_usage(usage, kind:, model:, price:)
+      count = ->(name) { usage.respond_to?(name) ? usage.public_send(name).to_i : 0 }
+      new(kind: kind.to_s, model: model, prompt_tokens: count.call(:prompt_tokens),
+          completion_tokens: count.call(:completion_tokens), cached_tokens: count.call(:cached_tokens),
+          cache_write_tokens: count.call(:cache_write_tokens), reasoning_tokens: count.call(:reasoning_tokens),
+          cost: usage.respond_to?(:cost) ? usage.cost : nil, price: price)
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -594,6 +594,9 @@ module Samagotchi
         lines << "speed:            #{speed}" if speed
         cost = stats_cost_text(tokens, price_host: snapshot[:price_host], per_model: segments.size >= 2)
         lines << "cost:             #{cost}" if cost
+        # The side requests, never in the totals above.
+        side = side_requests_text(snapshot[:side])
+        lines << "side requests:    #{side} (not in the totals above)" unless side.empty?
         lines << "gen latency (ms): #{snapshot[:gen_latency_ms]}"
         lines << "cancellations:    #{snapshot[:cancellations]}"
         lines << "retries:          #{snapshot[:retries]}"

data/lib/samagotchi/terminal_ui/model_segments_text.rb

@@ -5,9 +5,11 @@ require_relative "../memory_bundle/index_size"
 
 module Samagotchi
   class TerminalUI
-    # A session's rows per model in /stats (the snapshot's model_segments).
-    # The four public model_segment_* labels are the words the web's ctx
-    # tooltip shares (ctx.js; spec/shared/labels_matrix.json model_segments).
+    # A session's rows per model in /stats (the snapshot's model_segments),
+    # and its side requests' line (the snapshot's side block).
+    # The four public model_segment_* labels and side_requests_text are the
+    # words the web's ctx tooltip shares (ctx.js;
+    # spec/shared/labels_matrix.json model_segments, side_requests).
     # Rows come symbol- or string-keyed (the attached TUI's as JSON).
     # Included by Formatting, whose cost_text and speed_text it uses.
     module ModelSegmentsText
@@ -34,6 +36,28 @@ module Samagotchi
           .reject(&:empty?).join(" + ")
       end
 
+      # "3 (recap 2, btw 1) · 14.2k in / 380 out · $0.0012 + ~$0.0009": the
+      # side requests (the snapshot's side block: the recap, /btw and other
+      # ctx.ask_model calls), the kinds in first-seen order (one kind: its
+      # name alone), then the model rows' tokens and cost words on the
+      # block; "" without any (the line is hidden).
+      def side_requests_text(side)
+        return "" unless side.is_a?(Hash)
+
+        count = segment_value(side, :requests).to_i
+        return "" unless count.positive?
+
+        kinds = segment_value(side, :by_kind)
+        kinds = {} unless kinds.is_a?(Hash)
+        names = if kinds.size == 1
+                  kinds.keys.first.to_s
+                else
+                  kinds.map { |kind, row| "#{kind} #{(row.is_a?(Hash) ? segment_value(row, :requests) : 0).to_i}" }.join(", ")
+                end
+        head = names.empty? ? count.to_s : "#{count} (#{names})"
+        [head, model_segment_tokens_text(side), model_segment_cost_text(side)].reject(&:empty?).join(" · ")
+      end
+
       # "switch prefill 3.0k uncached prompt ≈$0.0060": what the switch to the
       # row's model prefilled (its cost an estimate from the configured
       # price, left out without one); "" for none.

data/lib/samagotchi/testing/boundary.rb

@@ -9,6 +9,8 @@ module Samagotchi
     # why: the APIs to design before that bundle could leave chi's repo
     # (spec/samagotchi/testing/boundary_spec.rb keeps both exact).
     module Boundary
+      LIB_DIR = File.expand_path("../..", __dir__)
+
       # A name a bundle may use, and the file that defines it (a require of
       # it is fine too). A name allows itself, its methods (".x") and what
       # it holds ("::X"); one ending in a method or constant allows only that.
@@ -124,6 +126,8 @@ module Samagotchi
       REFERENCE = /\bSamagotchi(?:::[A-Z]\w*)+(?:\.[a-z_]\w*[?!]?)?/
       # A require of one of chi's files.
       REQUIRE = %r{\brequire\s*\(?\s*["'](samagotchi(?:/[\w/]+)?)["']}
+      # A relative require that may leave the bundle.
+      REQUIRE_RELATIVE = /\brequire_relative\s*\(?\s*["']([^"']+)["']/
 
       # One reference outside ALLOWED, in a file of the bundle.
       Finding = Data.define(:reference, :file)
@@ -140,11 +144,22 @@ module Samagotchi
           text = File.read(path)
           refs = text.scan(REFERENCE).reject { |name| allowed?(name) }
           refs += text.scan(REQUIRE).flatten.reject { |file| ALLOWED_REQUIRES.include?(file) }.map { |file| %(require "#{file}") }
+          refs += text.scan(REQUIRE_RELATIVE).flatten.filter_map do |relative|
+            target = File.expand_path(relative, File.dirname(path))
+            next unless within?(target, LIB_DIR) && !within?(target, File.expand_path(dir))
+
+            %(require_relative "#{relative}")
+          end
           file = path.delete_prefix("#{File.expand_path(dir)}/")
           refs.uniq.map { |reference| Finding.new(reference: reference, file: file) }
         end
       end
 
+      def within?(path, dir)
+        path == dir || path.start_with?("#{dir}#{File::SEPARATOR}")
+      end
+      private_class_method :within?
+
       # Whether a bundle may use +name+ ("Samagotchi::X::Y", maybe ".method").
       def allowed?(name)
         ALLOWED.any? do |entry|

data/lib/samagotchi/testing/bundle.rb

@@ -26,12 +26,17 @@ module Samagotchi
     class HookFailed < StandardError
       # @return [Hooks::Failure]
       attr_reader :failure
-
-      def initialize(failure)
-        @failure = failure
-        error = failure.error
-        super("#{failure.hook} raised on #{failure.event}: #{error.class}: #{error.message}")
-        set_backtrace(error.backtrace) if error.backtrace
+      # @return [Array<Hooks::Failure>]
+      attr_reader :failures
+
+      def initialize(failures)
+        @failures = failures.dup.freeze
+        @failure = @failures.first
+        super(@failures.map do |failure|
+          error = failure.error
+          "#{failure.hook} raised on #{failure.event}: #{error.class}: #{error.message}"
+        end.join("; "))
+        set_backtrace(@failure.error.backtrace) if @failure.error.backtrace
       end
 
       def cause = @failure.error
@@ -142,7 +147,7 @@ module Samagotchi
             @plugin = built
           end
         end
-        @hooks_namespace = Hooks::BundleLoader.namespace_for(@name).const_set(:"KitHooks#{object_id}", Module.new)
+        @hooks_namespace = Module.new
         @manifest.hooks.each do |basename, hook|
           next if hook.event.empty?
 
@@ -168,6 +173,27 @@ module Samagotchi
         payload
       end
 
+      # Build the before_tool_call payload from the real Gate, without firing
+      # this bundle's hooks.
+      # @param call [Hash] the parsed tool call
+      # @param iteration [Integer]
+      # @param params [String] the call's one-line preview
+      # @param context [Guardrails::Context, nil]
+      # @param verdict [Verdict, nil]
+      # @return [Hash]
+      def before_tool_call_event(call, params:, iteration: 1, context: nil, verdict: nil)
+        context ||= Guardrails::Context.new(cwd: @recorder[:cwd], session_id: @recorder[:session_id],
+                                            interface: @recorder[:frontend])
+        dispatched = nil
+        capture = Hooks::Registry.new
+        capture.register(:before_tool_call) { |event| dispatched = event.dup }
+        gate = Guardrails::Gate.new(-> { capture }, context_lookup: -> { context }, tools_lookup: -> { tools })
+        gate.evaluate(call, iteration: iteration, params: params, verdict: verdict || Verdict.new(call: call))
+        raise ArgumentError, "guardrails did not dispatch a before_tool_call event for #{call[:name].inspect}" unless dispatched
+
+        dispatched.slice(:type, :iteration, :call, :params, :blocked, :block_reason, :guardrail, :context, :targets)
+      end
+
       # One tool call through a real Guardrails::Gate: the before_tool_call
       # hooks vote on a Testing::Verdict (pass +verdict+ to start from one,
       # another voter's deny in it), with the context and targets the Gate
@@ -331,8 +357,8 @@ module Samagotchi
         result = Hooks.capture_failures(failures, &)
         if @lenient
           @errors.concat(failures)
-        elsif (first = failures.first)
-          raise HookFailed, first
+        elsif failures.any?
+          raise HookFailed, failures
         end
         result
       end

data/lib/samagotchi/testing/host.rb

@@ -31,9 +31,9 @@ module Samagotchi
           },
           cancelled: -> { recorder[:cancelled] },
           card: ->(**card) { recorder.card(**card) },
-          ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil|
+          ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil|
             recorder.ask_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
-                                        model: model)
+                                        model: model, source: source)
           },
           model_name: -> { recorder[:model_name] },
           model_key: -> { recorder[:model_key] },

data/lib/samagotchi/testing/recorder.rb

@@ -16,8 +16,11 @@ module Samagotchi
     Question = Data.define(:question, :options, :header, :allow_freeform, :hook)
     # An ask_model request: the request Context built (SideQuestion), its
     # limits, cancel controller and the model: it named (nil: the session's;
-    # the kit doesn't check it against any hosts).
-    ModelRequest = Data.define(:request, :timeout, :max_tokens, :cancel, :model)
+    # the kit doesn't check it against any hosts), and +source+, the asking
+    # bundle's name (what chi counts its side request under).
+    ModelRequest = Data.define(:request, :timeout, :max_tokens, :cancel, :model, :source) do
+      def initialize(source: nil, **) = super
+    end
 
     # What a bundle did at chi's edges, for a test to read: the Engine side
     # of its Context (Testing::Host) and the hook runtime (Testing::Runtime)
@@ -104,9 +107,9 @@ module Samagotchi
       # The next queued model answer (#model_answers): a String, an
       # exception to raise, or a callable given the ModelRequest. None left:
       # Plugin::ModelError, as an unreachable model.
-      def ask_model(request, timeout:, max_tokens:, cancel_controller:, model: nil)
+      def ask_model(request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil)
         entry = ModelRequest.new(request: request, timeout: timeout, max_tokens: max_tokens, cancel: cancel_controller,
-                                 model: model)
+                                 model: model, source: source)
         record(@model_requests, entry)
         answer = @mutex.synchronize { @model_answers.empty? ? :none : @model_answers.shift }
         raise Plugin::ModelError, "no model answer queued (bundle.model_answers << \"text\")" if answer == :none