samagotchi 0.79.0 → 0.81.0

data/lib/samagotchi/session_metrics/side_totals.rb

@@ -0,0 +1,110 @@
+# 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)
+        kinds = hash["by_kind"].is_a?(Hash) ? hash["by_kind"] : {}
+        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: 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
+
+      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,17 @@ module Samagotchi
       end
     end
 
+    # 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 +478,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 +504,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 +531,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 +823,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 +1130,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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Testing
+    # What a bundle's Ruby may reach of chi (docs/plugins.md, "Stable for
+    # bundles"): ALLOWED is the checked copy of that list. #scan finds a
+    # bundle's other references to Samagotchi:: and requires of chi's files;
+    # EXCEPTIONS is what the shipped bundles reach today anyway, each with
+    # why: the APIs to design before that bundle could leave chi's repo
+    # (spec/samagotchi/testing/boundary_spec.rb keeps both exact).
+    module Boundary
+      # 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.
+      Allowed = Data.define(:name, :file)
+
+      ALLOWED = [
+        Allowed.new(name: "Samagotchi::Plugin::Api", file: "samagotchi/plugin/api"),
+        Allowed.new(name: "Samagotchi::Plugin::ToolResult", file: "samagotchi/plugin/tool_result"),
+        Allowed.new(name: "Samagotchi::Plugin::ModelError", file: "samagotchi/plugin/context"),
+        Allowed.new(name: "Samagotchi::Plugin::ModelCancelled", file: "samagotchi/plugin/context"),
+        Allowed.new(name: "Samagotchi::Plugin::HttpError", file: "samagotchi/plugin/http"),
+        Allowed.new(name: "Samagotchi::Plugin::HttpCancelled", file: "samagotchi/plugin/http"),
+        Allowed.new(name: "Samagotchi::Plugin::Http::Response", file: "samagotchi/plugin/http"),
+        Allowed.new(name: "Samagotchi::Plugin::Service::Stopped", file: "samagotchi/plugin/service"),
+        Allowed.new(name: "Samagotchi::Plugin::Sessions::Error", file: "samagotchi/plugin/sessions"),
+        Allowed.new(name: "Samagotchi::Plugin::AttachedContext::Error", file: "samagotchi/plugin/attached_context"),
+        Allowed.new(name: "Samagotchi::Plugin::Peer", file: "samagotchi/plugin/peer"),
+        Allowed.new(name: "Samagotchi::Tools::ToolIndex::Tool", file: "samagotchi/tools/tool_index"),
+        Allowed.new(name: "Samagotchi::Tools::ToolIndex::Group", file: "samagotchi/tools/tool_index"),
+        Allowed.new(name: "Samagotchi::Tools::ToolIndex.schema_note", file: "samagotchi/tools/tool_index"),
+        Allowed.new(name: "Samagotchi::Tools::ToolIndex.spec_tokens", file: "samagotchi/tools/tool_index"),
+        Allowed.new(name: "Samagotchi::Tools::Execute::NAME", file: "samagotchi/tools/execute"),
+        Allowed.new(name: "Samagotchi::Tools::Execute::TIMEOUT_PREFIX", file: "samagotchi/tools/execute"),
+        Allowed.new(name: "Samagotchi::Tools::Execute::HANDED_OVER", file: "samagotchi/tools/execute"),
+        Allowed.new(name: "Samagotchi::Tools::Execute.timeout_seconds", file: "samagotchi/tools/execute"),
+        Allowed.new(name: "Samagotchi::Tools::TaskRuntime::TASKS_DIR", file: "samagotchi/tools/task_runtime"),
+        Allowed.new(name: "Samagotchi::Tools::TaskRuntime::EXIT_CODE_FILENAME", file: "samagotchi/tools/task_runtime"),
+        Allowed.new(name: "Samagotchi::AtomicFile.write", file: "samagotchi/atomic_file"),
+        Allowed.new(name: "Samagotchi::Log.warn", file: "samagotchi/log"),
+        Allowed.new(name: "Samagotchi::Log.debug", file: "samagotchi/log"),
+        Allowed.new(name: "Samagotchi::Config.get", file: "samagotchi/config"),
+        Allowed.new(name: "Samagotchi::VERSION", file: "samagotchi/version"),
+        # The kit itself, for a bundle's own specs.
+        Allowed.new(name: "Samagotchi::Testing", file: "samagotchi/testing")
+      ].freeze
+
+      # The kit's adapters, required by a bundle's specs.
+      ALLOWED_REQUIRES = (ALLOWED.map(&:file) + %w[samagotchi/testing/rspec samagotchi/testing/minitest]).uniq.freeze
+
+      SESSION = "a saved session (context sources are keyed by its id): needs a kit helper that saves one"
+      SOURCES = "the session's context sources (the peer's inbox / outbox): needs a kit helper that attaches one"
+      REF_LIMITS = "a ref's kinds and limits (event[:refs] checks them too): could be stable constants"
+      # The peers' specs pair a session through its context sources.
+      PEER_SPEC = {
+        'require "samagotchi/context_sources"' => "spec: #{SOURCES}",
+        "Samagotchi::Session.new_session" => "spec: #{SESSION}",
+        "Samagotchi::ContextSources.session_location" => "spec: #{SOURCES}",
+        "Samagotchi::ContextSources::Source.new" => "spec: #{SOURCES}",
+        "Samagotchi::ContextSources::Fetched.new" => "spec: an outbox answer as the context poller records it"
+      }.freeze
+
+      # bundle => {reference => why}: what each shipped bundle reaches
+      # beyond ALLOWED today, its specs' (why "spec: …") included.
+      EXCEPTIONS = {
+        "agents-md" => {
+          'require "samagotchi/guardrails/context"' => "for GitInfo: a ctx helper for the checkout's files could replace it",
+          "Samagotchi::Guardrails::GitInfo.new" => "the work tree's top for the AGENTS.md chain (ctx.repo_root covers the top only)"
+        },
+        "claude-peer" => PEER_SPEC,
+        "codex-peer" => PEER_SPEC,
+        "coordinator" => {
+          "Samagotchi::MemoryPaths.scope_dir" => "where the coordinator's memories live: needs a ctx memory-path API",
+          "Samagotchi::MemoryPaths" => "spec: checks /coordinate end reads no memories (MemoryPaths.scope_dir isn't called)"
+        },
+        "github-pr" => {
+          "Samagotchi::Session.new_session" => "spec: #{SESSION} (ctx.delegate?, ctx.fork?, ctx.context read it)",
+          "Samagotchi::ContextSources.session_location" => "spec: reads and removes the session's sources (added_by), " \
+                                                            "which ctx.context.list doesn't show",
+          'require "samagotchi/memory_bundle/installer"' => "spec: for Installer",
+          "Samagotchi::MemoryBundle::Installer.new" => "spec: installs the bundle so its context provider resolves: " \
+                                                       "needs a kit install helper",
+          'require "samagotchi/context_providers"' => "spec: for ContextProviders",
+          "Samagotchi::ContextProviders.resolve" => "spec: the manifest's URL provider through chi's own resolver",
+          'require "samagotchi/answer_display"' => "spec: for AnswerDisplay",
+          "Samagotchi::AnswerDisplay.new" => "spec: after_turn's present: helper, as chi's fire site builds it: " \
+                                             "the kit could supply after_turn's fire-site keys",
+          'require "samagotchi/answer_refs"' => "spec: for AnswerRefs",
+          "Samagotchi::AnswerRefs.new" => "spec: after_turn's refs: helper, as chi's fire site builds it",
+          "Samagotchi::Log" => "spec: stubs Log to check what ctx.log recorded: a kit log recorder could replace it"
+        },
+        "loop-guard" => {
+          'require "samagotchi/llm/native_tool_normalizer"' => "spec: for NativeToolNormalizer",
+          "Samagotchi::LLM::NativeToolNormalizer.normalize" => "spec: replays recorded calls in the shape chi's parser gives",
+          "Samagotchi::Hooks::StreamWatch::EVERY_CHARS" => "spec: the stream watch's batch size (a ctx or kit value later)"
+        },
+        "skills" => {
+          "Samagotchi::Tools::MemoryRead.memories_dir" => "lists the skill memories: needs a ctx memory-path API"
+        },
+        "mcp" => {
+          'require "samagotchi/process_group"' => "for ProcessGroup.stop",
+          "Samagotchi::ProcessGroup.stop" => "stops a server's process group: needs a ctx process API",
+          'require "samagotchi/token_usage"' => "for CHARS_PER_TOKEN",
+          "Samagotchi::TokenUsage::CHARS_PER_TOKEN" => "estimates a tool's tokens: could be a stable constant",
+          'require "samagotchi/tool_declarations"' => "loaded for Api.tool_spec's schemas"
+        },
+        "slow-commands" => {
+          'require "samagotchi/guardrails/shell_lex"' => "for ShellLex",
+          "Samagotchi::Guardrails::ShellLex" => "splits a command into its parts: needs a stable shell-parsing helper",
+          "Samagotchi::Tools::Execute.const_defined?" => "reads execute's limits that older chis lack, by reflection",
+          "Samagotchi::Tools::Execute.const_get" => "reads execute's limits that older chis lack, by reflection"
+        },
+        "source-links" => {
+          'require "samagotchi/ref"' => "for the Ref / RefAction limits",
+          "Samagotchi::Ref::FILE" => REF_LIMITS,
+          "Samagotchi::Ref::KIND.match?" => REF_LIMITS,
+          "Samagotchi::Ref::MAX_LABEL" => REF_LIMITS,
+          "Samagotchi::RefAction::MAX_LABEL" => REF_LIMITS,
+          "Samagotchi::RefAction.http_url?" => "which URLs an action may open: could be a stable helper"
+        }
+      }.freeze
+
+      # A Samagotchi:: name with what follows it (::X, .method).
+      REFERENCE = /\bSamagotchi(?:::[A-Z]\w*)+(?:\.[a-z_]\w*[?!]?)?/
+      # A require of one of chi's files.
+      REQUIRE = %r{\brequire\s*\(?\s*["'](samagotchi(?:/[\w/]+)?)["']}
+
+      # One reference outside ALLOWED, in a file of the bundle.
+      Finding = Data.define(:reference, :file)
+
+      module_function
+
+      # The bundle's references to chi outside ALLOWED (its plugin, hooks,
+      # scripts and specs: every .rb under +dir+), one per reference and
+      # file, sorted.
+      # @param dir [String] the bundle's folder
+      # @return [Array<Finding>]
+      def scan(dir)
+        Dir.glob(File.join(dir, "**", "*.rb")).sort.flat_map do |path|
+          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}") }
+          file = path.delete_prefix("#{File.expand_path(dir)}/")
+          refs.uniq.map { |reference| Finding.new(reference: reference, file: file) }
+        end
+      end
+
+      # Whether a bundle may use +name+ ("Samagotchi::X::Y", maybe ".method").
+      def allowed?(name)
+        ALLOWED.any? do |entry|
+          name == entry.name || name.start_with?("#{entry.name}.", "#{entry.name}::")
+        end
+      end
+    end
+  end
+end