samagotchi 0.155.0 → 0.157.0

data/lib/samagotchi/bridge/turn_drawings.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require_relative "../log"
+require_relative "../message_time"
+require_relative "../steer"
+
+module Samagotchi
+  class Bridge
+    # A finished turn as live drew it (its drawing), one JSON line per turn in
+    # the session's folder (FILE), so a reload or a reconnect draws the turn
+    # the way the live page did: the TurnAccumulator's final fold of the turn
+    # (its parts in order: steps, rows, notices, steers, merged lines,
+    # reminders, in-turn cards) and the end event's display keys (END_KEYS).
+    # Display-side only: no request, message, strategy, recap, --resume or
+    # continue reads it.
+    #
+    # A line names the turn's own messages by the range the Engine put on
+    # the end event (`kept_from`/`kept_to`: the turn's messages are
+    # `kept[from...to]`) and digests both ends (#digest). It holds while the
+    # messages still reach `to` and both ends digest the same: a rollback, a
+    # rolled-back failure or a prompt handed back drops it. Of two valid
+    # lines that overlap (a rollback, then a re-run that said the same at the
+    # same boundaries), and of several for one turn id, the newest wins
+    # (.valid). A turn with no range (an older worker, a turn that kept
+    # nothing) or an empty one writes no line, and draws as before.
+    #
+    # Written by the accumulator's on_turn_end hook (#append), inside the
+    # SessionObserver's delivery: the line is on disk before any stream gets
+    # the end frame. That departs from SessionObserver's "enqueue-only" note,
+    # as CardStore's save does: one append per turn end.
+    class TurnDrawings
+      FILE = "turn_drawings.jsonl"
+      # In the sidecar's features (Bridge::FEATURES): this worker's CardStore
+      # lists an in-turn entry's of_turn, which a page drawing the turn needs
+      # to leave that entry to the drawing. chi web draws no drawings for a
+      # live worker without it (an older one: its rows would show twice).
+      FEATURE = "turn_drawings"
+      # A show draws at most this many turns from their drawings, the newest
+      # (the payload and the page's offscreen render stay bounded in a long
+      # session); older turns draw as before, from their messages.
+      SHOWN_MAX = 100
+      VERSION = 1
+      # The end event's keys the page draws a finished turn's end from (not
+      # the answer: its text, html and refs stay the message's; not the range:
+      # the line's from/to).
+      END_KEYS = %i[type turn_id duration_ms revises verify cancellation_reason cancelled_by summary message error_class
+                    kept_steps].freeze
+      # What a line keeps of the accumulator's turn.
+      DRAWING_KEYS = (%i[prompt turn_id origin continue at images parts] + Steer::AUTHOR_KEYS).uniq.freeze
+      KINDS = { "turn_completed" => "completed", "turn_canceled" => "canceled", "turn_failed" => "failed" }.freeze
+
+      # One line of the file (string-keyed drawing and end, as JSON has them).
+      Line = Data.define(:v, :turn_id, :kind, :from, :to, :from_digest, :to_digest, :drawing, :end) do
+        # @return [Line, nil] nil for a line this chi can't draw (another
+        #   version, a missing field)
+        def self.from_h(raw)
+          return nil unless raw.is_a?(Hash) && raw["v"] == VERSION
+          return nil unless raw["turn_id"].is_a?(String) && !raw["turn_id"].empty?
+          return nil unless raw["from"].is_a?(Integer) && raw["to"].is_a?(Integer) && raw["from"] < raw["to"] && raw["from"] >= 0
+          return nil unless raw["from_digest"].is_a?(String) && raw["to_digest"].is_a?(String)
+          return nil unless raw["drawing"].is_a?(Hash) && raw["end"].is_a?(Hash)
+
+          new(v: raw["v"], turn_id: raw["turn_id"], kind: raw["kind"].to_s, from: raw["from"], to: raw["to"],
+              from_digest: raw["from_digest"], to_digest: raw["to_digest"], drawing: raw["drawing"], end: raw["end"])
+        end
+
+        def to_h = super.transform_keys(&:to_s)
+
+        def range = (from...to)
+      end
+
+      # @param path [String, nil] the file (nil: nothing is written)
+      # @param messages [#call] the session's messages now (the Engine's,
+      #   as CardStore's): the end step replaced them before the end event, so
+      #   they hold the turn's range when #append runs
+      def initialize(path:, messages:)
+        @path = path
+        @messages = messages
+        @last = path ? self.class.tail_line(path) : nil
+      end
+
+      # The newest line this store wrote or started from (P3's snapshot).
+      # @return [Line, nil]
+      attr_reader :last
+
+      # The accumulator's hook: the turn's line, when its end event names a
+      # range. Never raises (a turn that can't be drawn still ended).
+      # @param turn [Hash] the accumulator's final fold (symbol keys)
+      # @param end_event [Hash] the end event
+      def append(turn, end_event)
+        line = line_for(turn, end_event)
+        return unless line
+
+        write(line)
+        @last = line
+      rescue StandardError => e
+        Log.warn(:bridge, "turn_drawing_failed", error: "#{e.class}: #{e.message}")
+      end
+
+      def line_for(turn, end_event)
+        from = end_event[:kept_from]
+        to = end_event[:kept_to]
+        return nil unless @path && turn && from.is_a?(Integer) && to.is_a?(Integer) && from < to && from >= 0
+
+        messages = @messages.call || []
+        return nil if messages.size < to
+
+        id = end_event[:turn_id] || turn[:turn_id]
+        return nil unless id
+
+        Line.new(v: VERSION, turn_id: id.to_s, kind: KINDS[end_event[:type].to_s] || end_event[:type].to_s, from: from, to: to,
+                 from_digest: self.class.digest(messages[from]), to_digest: self.class.digest(messages[to - 1]),
+                 drawing: JSON.parse(JSON.generate(scrubbed(turn.slice(*DRAWING_KEYS)))),
+                 end: JSON.parse(JSON.generate(scrubbed(self.class.end_of(end_event)))))
+      end
+      private :line_for
+
+      # Newline-first: a torn last line (a crash mid-write) ends before this
+      # one starts, so both parse apart; then one write.
+      def write(line)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, File::RDWR | File::CREAT | File::APPEND, 0o600) do |file|
+          size = file.size
+          torn = size.positive? && (file.pread(1, size - 1) != "\n")
+          file.write("#{"\n" if torn}#{JSON.generate(line.to_h)}\n")
+        end
+      end
+      private :write
+
+      def scrubbed(value) = self.class.scrub(value)
+      private :scrubbed
+
+      class << self
+        # The end event's display keys (END_KEYS), with an empty answer's
+        # notice from its summary.
+        # @return [Hash]
+        def end_of(event)
+          out = event.slice(*END_KEYS).compact
+          out[:type] = out[:type].to_s if out[:type]
+          empty = event.dig(:turn_summary, :empty_answer)
+          out[:turn_summary] = { empty_answer: empty } if empty
+          out
+        end
+
+        # A message's digest in one form for the live (symbol keys, raw
+        # strings) and the saved (string keys, scrubbed as Session#to_h does)
+        # messages: role, content and time, each read from either key.
+        # @return [String]
+        def digest(message)
+          return "" unless message.is_a?(Hash)
+
+          role = fetch(message, :role)
+          time = fetch(message, MessageTime::KEY)
+          Digest::SHA1.hexdigest(JSON.generate(scrub([role&.to_s, fetch(message, :content), time&.to_s])))
+        end
+
+        # Every String in +value+ as Session#to_h saves it (UTF-8, invalid
+        # bytes as "?"); symbol keys stay symbols (JSON writes them alike).
+        def scrub(value)
+          case value
+          when String
+            text = value.encoding == Encoding::UTF_8 ? value : value.dup.force_encoding(Encoding::UTF_8)
+            text.valid_encoding? ? text : text.scrub("?")
+          when Array then value.map { |item| scrub(item) }
+          when Hash then value.to_h { |key, item| [key, scrub(item)] }
+          when Symbol then value.to_s
+          else value
+          end
+        end
+
+        # The session folder's lines, oldest first (unreadable, torn and
+        # unknown lines skipped), cached by the file's path, size and mtime
+        # (chi web reads it on each full show).
+        # @return [Array<Line>]
+        def read(session_dir)
+          path = File.join(session_dir, FILE)
+          stat = File.stat(path)
+          key = [stat.size, stat.mtime.to_r]
+          cached = cache_mutex.synchronize { cache[path] }
+          return cached[1] if cached && cached[0] == key
+
+          lines = parse(File.binread(path))
+          cache_mutex.synchronize do
+            cache.shift while cache.size >= CACHE_SIZE
+            cache[path] = [key, lines]
+          end
+          lines
+        rescue SystemCallError, IOError
+          []
+        end
+
+        # @return [Array<Line>]
+        def parse(text)
+          text.dup.force_encoding(Encoding::UTF_8).scrub("?").each_line.filter_map do |raw|
+            Line.from_h(JSON.parse(raw))
+          rescue JSON::ParserError
+            nil
+          end
+        end
+
+        # The lines that hold against +messages+ (Session messages, symbol
+        # or string keys): each one's range still in them with both ends the
+        # same; of overlapping ranges and of one turn's lines the newest
+        # (last in the file) wins. Ordered by their range.
+        # @return [Array<Line>]
+        def valid(lines, messages)
+          messages = Array(messages)
+          kept = []
+          lines.reverse_each do |line|
+            next unless holds?(line, messages)
+            next if kept.any? { |other| other.turn_id == line.turn_id || overlap?(other, line) }
+
+            kept << line
+          end
+          kept.sort_by(&:from)
+        end
+
+        # The last parseable line of +path+, or nil.
+        # @return [Line, nil]
+        def tail_line(path)
+          return nil unless File.file?(path)
+
+          File.open(path, "rb") do |file|
+            size = file.size
+            chunk = file.pread([size, TAIL_BYTES].min, [size - TAIL_BYTES, 0].max)
+            parse(chunk.to_s).last
+          end
+        rescue SystemCallError, IOError
+          nil
+        end
+
+        # Whether +line+ is small enough to send in a snapshot: within what
+        # #tail_line reads back after a restart (TAIL_BYTES), so a join draws
+        # a turn the same before and after one (a bigger line: rebuilt).
+        def sendable?(line) = JSON.generate(line.to_h).bytesize <= TAIL_BYTES
+
+        def holds?(line, messages)
+          messages.size >= line.to && digest(messages[line.from]) == line.from_digest &&
+            digest(messages[line.to - 1]) == line.to_digest
+        end
+
+        def overlap?(one, other) = one.from < other.to && other.from < one.to
+
+        private
+
+        def fetch(message, key)
+          message.key?(key) ? message[key] : message[key.to_s]
+        end
+
+        def cache = (@cache ||= {})
+        def cache_mutex = (@cache_mutex ||= Mutex.new)
+      end
+
+      # Sessions whose parsed file chi web keeps (a long one's is tens of MB
+      # of objects; the mtime moves at every turn end anyway).
+      CACHE_SIZE = 8
+      # Read from the end at start (#last): a drawing is a few KB, its outputs cut.
+      TAIL_BYTES = 1024 * 1024
+      private_constant :CACHE_SIZE, :TAIL_BYTES
+    end
+  end
+end

data/lib/samagotchi/bridge.rb

@@ -21,6 +21,7 @@ require_relative "bridge/pending_card"
 require_relative "bridge/ring_buffer"
 require_relative "bridge/sse_writer"
 require_relative "bridge/turn_accumulator"
+require_relative "bridge/turn_drawings"
 require_relative "session"
 require_relative "engine"
 require_relative "system_one/log"
@@ -134,7 +135,10 @@ module Samagotchi
       @bind = bind
       @port = port
       @ring = RingBuffer.new(capacity: ring_capacity)
-      @accumulator = TurnAccumulator.new
+      # A finished turn's drawing (TurnDrawings), written by the accumulator
+      # at the end event, before any stream gets it.
+      @drawings = TurnDrawings.new(path: File.join(session_dir, TurnDrawings::FILE), messages: -> { @engine.session&.messages })
+      @accumulator = TurnAccumulator.new(on_turn_end: @drawings.method(:append))
       # Saved in the session's folder: a later worker, and the web without
       # one, show the cards where they were.
       @cards = CardStore.new(path: File.join(session_dir, CardStore::FILE), messages: -> { @engine.session&.messages })
@@ -300,7 +304,7 @@ module Samagotchi
     # the event log: the Engine's messages (not the lagging copy on disk),
     # the turn in progress, turns queued behind it, the idle recap since the
     # last turn, the recap saved with the session (also from before the last
-    # turns: {text:, covered:, turns_since:, created_at:}), a pending continue offer, the guardrail and plugin load warnings,
+    # turns: {text:, covered:, turns_since:, opening_id:, created_at:}), a pending continue offer, the guardrail and plugin load warnings,
     # the plugins' init tasks still running (Engine#init_tasks), the
     # last cards and between-turns notices (CardStore#list), the session's commands (Commands::Registry#listing:
     # what an attached TUI routes and completes, the web's autocomplete), and the event_seq it all covers.
@@ -315,13 +319,20 @@ module Samagotchi
     # working_set: the running turn's last :working_set_updated ({items:,
     # at:}, TurnAccumulator#working_set), which the messages lag; nil
     # between turns and before the turn emitted one.
+    # last_turn_drawing: the last exchange's turn as live drew it
+    # ({drawing:, end:}, TurnDrawings#last, not unfolded: an attaching TUI
+    # unfolds it, TurnAccumulator.replay_events), only while it holds against
+    # these messages and ends at their end; absent otherwise (a rollback, a
+    # later Continue or note, an older worker's file).
     # @return [Hash] {messages:, current_turn:, working_set:, queued:, queued_commands:, recap:, saved_recap:, continue_offer:, pending_question:,
-    #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, chi_version:, event_seq:, event_id:}
+    #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, chi_version:, event_seq:, event_id:, last_turn_drawing:}
     def snapshot
       @engine.synchronize_events do
         seq = @engine.event_count
+        messages = @engine.messages_checkpoint
+        drawing = last_turn_drawing(messages)
         {
-          messages: @engine.messages_checkpoint,
+          messages: messages,
           current_turn: current_turn_with_generation,
           working_set: @accumulator.working_set,
           queued: @accumulator.queued,
@@ -338,10 +349,24 @@ module Samagotchi
           chi_version: Samagotchi::VERSION,
           event_seq: seq,
           event_id: event_id(seq)
-        }
+        }.merge(drawing ? { last_turn_drawing: drawing } : {})
       end
     end
 
+    # The newest drawing (TurnDrawings#last) as the snapshot sends it, when
+    # it is the last exchange's: its range still holds against +messages+
+    # and ends at their end, and is no bigger than a restart reads back
+    # (TurnDrawings.sendable?). nil otherwise.
+    # @return [Hash, nil] {drawing:, end:} (string keys inside, as the file)
+    def last_turn_drawing(messages)
+      line = @drawings.last
+      return nil unless line && line.to == messages.size && TurnDrawings.holds?(line, messages)
+      return nil unless TurnDrawings.sendable?(line)
+
+      { drawing: line.drawing, end: line.end }
+    end
+    private :last_turn_drawing
+
     # The snapshot and the session state (status, pending question, ...) as
     # one step of the event log, both as of the same event_seq: what a
     # snapshot or reset frame (SSEWriter) and GET snapshot carry.
@@ -664,7 +689,7 @@ module Samagotchi
     # review turn, and chi web says so (Delivery::PAIR_FEATURE).
     FEATURES = ["restart", "task_stop", "reparent", Delivery::QUEUE_FEATURE, ReplyWait::TURN_IDS_FEATURE,
                 VerifyAnchor::FEATURE, ReviseAnchor::FEATURE,
-                SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE].freeze
+                SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE, TurnDrawings::FEATURE].freeze
 
     # The routes, by method and what follows /session/:id/: a handler takes
     # the session id and the request body and returns [headers, status, body].

data/lib/samagotchi/broadcast/recipients.rb

@@ -29,12 +29,12 @@ module Samagotchi
       # @return [Array<Recipient>] newest first
       def list(state_dir:, active_hours:, include_tests: Session.test_session_env?, now: Time.now)
         cutoff = now - (active_hours.to_f * 3600)
-        SessionManager.session_summaries(include_tests: include_tests, state_dir: state_dir).filter_map do |row|
-          next if row[:delegate] || row[:scratch]
-          next unless row[:live] || row[:owner] == "tui" || active_since?(row, cutoff, state_dir)
+        SessionManager.session_rows(include_tests: include_tests, state_dir: state_dir).filter_map do |row|
+          next if row.delegate || row.scratch
+          next unless row.live || row.owner == "tui" || active_since?(row, cutoff, state_dir)
 
-          Recipient.new(id: row[:id], short_id: row[:short_id], project: row[:project], cwd: row[:cwd],
-                        desc: row[:desc], live: row[:live], owner: row[:owner])
+          Recipient.new(id: row.id, short_id: row.short_id, project: row.project, cwd: row.cwd,
+                        desc: row.desc, live: row.live, owner: row.owner)
         end
       end
 
@@ -43,11 +43,11 @@ module Samagotchi
       # session with no turn recorded; it is never older than the last
       # turn's end, so an older one rules the session out unread.
       def active_since?(row, cutoff, state_dir)
-        return false unless (time(row[:updated_at]) || Time.at(0)) >= cutoff
+        return false unless (time(row.updated_at) || Time.at(0)) >= cutoff
 
-        session = Session.summary_from_file(Session.session_file(row[:id], state_dir: state_dir))
+        session = Session.summary_from_file(Session.session_file(row.id, state_dir: state_dir))
         ended = time(session&.last_turn&.ended_at)
-        (ended || time(row[:updated_at])) >= cutoff
+        (ended || time(row.updated_at)) >= cutoff
       end
       private_class_method :active_since?
 

data/lib/samagotchi/broadcast/triage_model.rb

@@ -29,7 +29,7 @@ module Samagotchi
       # @param get [#call] a Config key → its value
       # @return [Choice]
       def resolve(host_registry: nil, get: ->(key) { Config.get(key) })
-        registry = host_registry || HostRegistry.new
+        registry = host_registry || HostRegistry.current
         SETTINGS.each do |model, host_ref, base_url|
           target = IdleTarget.resolve(model: get.call(model), host_ref: get.call(host_ref), base_url: get.call(base_url),
                                       host_registry: registry)

data/lib/samagotchi/broadcast_command.rb

@@ -348,11 +348,11 @@ module Samagotchi
     # The full id +given+ names (an id or the start of one), or nil after
     # saying why there is none.
     def resolve_session(given)
-      id = Session.resolve_id(given, state_dir: @state_dir)
-      Session.load(id, state_dir: @state_dir) # raises ArgumentError when there is no such session
+      id = Session.resolve!(given, state_dir: @state_dir)
+      Session.load(id, state_dir: @state_dir) # a file that won't load is refused here too
       id
     rescue ArgumentError => e
-      error_line("chi broadcast: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      error_line("chi broadcast: #{e.message}")
       nil
     rescue SystemCallError => e
       error_line("chi broadcast: session #{given} can't be read: #{e.message}")

data/lib/samagotchi/bundle_command/check.rb

@@ -91,6 +91,7 @@ module Samagotchi
           check_settings(manifest) unless @installed
           check_install(manifest) unless missing || placeholders? || manifest.session_settings_clash
           check_api(manifest)
+          check_fail_closed(manifest) unless @installed
           check_boundary(manifest)
           check_tests unless @installed
         end
@@ -439,6 +440,23 @@ module Samagotchi
         end
       end
 
+      # A chi.on(..., on_error: :fail_closed) guard denies the call it raises
+      # on; only the manifest's plugin: required: true makes its failing to
+      # load deny every call (chi knows it before the plugin registers).
+      FAIL_CLOSED = /on_error:\s*(?::fail_closed\b|["']fail_closed["'])/
+
+      def check_fail_closed(manifest)
+        file = manifest.plugin && manifest.plugin[:file]
+        return if !file || manifest.plugin[:required] || !File.file?(path(file))
+
+        source = File.read(path(file))
+        return unless (index = source =~ FAIL_CLOSED)
+
+        add(:warn, :"fail-closed", file, "a fail-closed chi.on hook, but the manifest's plugin: has no required: true: " \
+                                         "if the plugin fails to load, tool calls still run",
+            line: source[0, index].count("\n") + 1, fix: "add required: true under plugin: in manifest.yml")
+      end
+
       def check_boundary(manifest)
         require_relative "../testing/boundary"
         known = shipped? ? Testing::Boundary::EXCEPTIONS.fetch(manifest.name, {}) : {}

data/lib/samagotchi/bundle_command/try/sandbox.rb

@@ -130,7 +130,7 @@ module Samagotchi
 
         # Stops what the run started that outlives its child chi: the
         # workers of its delegates (they leave the child's process tree,
-        # SessionManager.detach_from_spawner) and its tasks (a group of
+        # WorkerBoot.detach_from_spawner) and its tasks (a group of
         # their own each, reparented once the child exits). Found by their
         # records in the sandbox, so nothing outside it: a session's lock
         # held by a group leader, a running task's record whose pid still
@@ -186,7 +186,7 @@ module Samagotchi
         end
 
         def leftover_workers
-          sessions = File.join(state_home, Session::STATE_SUBDIR)
+          sessions = File.join(state_home, SessionPaths::STATE_SUBDIR)
           Dir.glob(File.join(sessions, "*", OwnerLock::FILE)).filter_map do |lock|
             pid = OwnerLock.owner(File.dirname(lock))&.pid
             pid if ProcessGroup.leader?(pid)

data/lib/samagotchi/bundle_command/try/trace.rb

@@ -28,7 +28,7 @@ module Samagotchi
         def read(exit_code:, answer:, stderr:, sandbox:, timed_out: false)
           return empty_trace(exit_code, answer, stderr, sandbox, timed_out) unless @session_id
 
-          sessions_dir = File.join(@state_home, Session::STATE_SUBDIR)
+          sessions_dir = File.join(@state_home, SessionPaths::STATE_SUBDIR)
           session_dir = Session.session_dir(@session_id, state_dir: sessions_dir)
           session = json_file(Session.session_file(@session_id, state_dir: sessions_dir)) || {}
           messages = Array(session["messages"]).select { |message| message.is_a?(Hash) }

data/lib/samagotchi/bundle_command.rb

@@ -639,9 +639,12 @@ module Samagotchi
       0
     end
 
+    # The base and the file; a marked one also the bundle's text it stays
+    # behind (its source-less FileState says which).
     def diff_memory(prov, target_dir, key)
-      print_base_and_current(key, prov.base_path(key), File.join(target_dir, key))
-      print_incoming(prov, key)
+      state = Samagotchi::MemoryBundle::FileState.of(key, record: prov.record, provenance: prov, target_dir: target_dir, source_dir: nil)
+      print_base_and_current(key, state.paths[:base], state.paths[:current])
+      print_incoming(prov, key) if state.marked?
     end
 
     # The bundle's text a file stays behind (Provenance#incoming_path), so the

data/lib/samagotchi/bundles/known-names/manifest.yml

@@ -1,17 +1,14 @@
 ---
 name: known-names
-version: 0.1.9
+version: 0.2.0
 requires_chi: ">= 0.150.0"
 scope: system
 description: Catches a near-miss of a protected name (home folder, login, git name, repo name, names from config) in a tool call and rejects it with the right spelling; mode ask / correct optional
 trust_level: reviewed
 files:
   known_names.md: sha256:d5348b95b6c655017b541910b36e384220da280818160201f6ec9a50e1e4287c
-hooks:
-  known_names.rb:
-    sha256: sha256:d7eed0dd0f418d8099a147ed124c6e6062b8c752035dd6b5aa5e926e29941c8b
-    event: before_tool_call
-    on_error: log
-    priority: 50
+plugin:
+  file: plugin.rb
+  sha256: sha256:d140612e6c34a9d2d205bf818a2a0797ad1e133829481f354aaa9e56698017e3
 # config.yml bundles: known-names: (another key warns; an older chi ignores this)
 settings: [names, ignore, mode, derive, min_length, max_distance]

data/lib/samagotchi/bundles/known-names/{hooks/known_names.rb → plugin.rb}

@@ -243,3 +243,20 @@ class KnownNames
     Array(value).map { |name| name.to_s.strip }.reject(&:empty?)
   end
 end
+
+# What chi loads: one KnownNames, built once from config.yml
+# `bundles: known-names:` when the plugin loads, on before_tool_call at
+# priority 50. A raise in the handler is logged and the call goes on
+# (chi.on's log policy); KnownNames#call turns its own errors into a
+# notice first.
+class Plugin
+  PRIORITY = 50
+
+  def initialize(settings = {})
+    @names = KnownNames.new(settings)
+  end
+
+  def register(chi)
+    chi.on(:before_tool_call, priority: PRIORITY) { |event, _ctx| @names.call(event) }
+  end
+end

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,17 +1,14 @@
 ---
 name: source-links
-version: 0.6.3
+version: 0.7.0
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, refs in a waiting question's reply, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
 requires_chi: ">= 0.150.0"
 files:
   source_links.md: sha256:ace01a0f7c308a0ae54ece714c31c0e6d7a49c372d98111030e6d268320bed3a
-hooks:
-  source_links.rb:
-    sha256: sha256:21d7a9f7c381c653b126b625feed0e0b6422eaa84c8dfe716b6c5b41644a33b3
-    events: [after_turn, question_asked]
-    on_error: log
-    priority: 90
+plugin:
+  file: plugin.rb
+  sha256: sha256:b4a777d8b6135f80e248dd21b5370c91dfcf2aea17057734e77241eb9cc4afe4
 # config.yml bundles: source-links: (another key warns; an older chi ignores this)
 settings: [sources, max, note]

data/lib/samagotchi/bundles/source-links/{hooks/source_links.rb → plugin.rb}

@@ -59,10 +59,10 @@ require "samagotchi/ref"
 # action, "Open in <name>", the ref's URL. A URL that isn't http(s) stays a
 # markdown link only. The web's ref menu shows the action.
 #
-# The hook is on :question_asked too (the manifest's events:, chi newer than
-# 0.97.0): while a question of the model's (or an approval of its call)
-# waits, the refs in the reply that asks it, and in the question's text and
-# options, are refs on that reply, the same as an answer's. The web pairs
+# The hook is on :question_asked too (Plugin below hooks both events): while
+# a question of the model's (or an approval of its call) waits, the refs in
+# the reply that asks it, and in the question's text and options, are refs
+# on that reply, the same as an answer's. The web pairs
 # them in the stage's asking slot, on the question's card and on that step
 # in the history (a ref only in the question's text pairs there alone). No
 # links in the text and no note line for it: the turn's end has those.
@@ -657,3 +657,22 @@ class SourceLinks
     value.to_s.gsub(/[^A-Za-z0-9\-._~]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join }
   end
 end
+
+# What chi loads: one SourceLinks, built once from config.yml
+# `bundles: source-links:` when the plugin loads, on after_turn and
+# question_asked at priority 90 (its state, the remotes it asked git for,
+# is shared). A raise in the handler is logged and the turn goes on
+# (chi.on's log policy).
+class Plugin
+  PRIORITY = 90
+
+  def initialize(settings = {})
+    @links = SourceLinks.new(settings)
+  end
+
+  def register(chi)
+    %i[after_turn question_asked].each do |event|
+      chi.on(event, priority: PRIORITY) { |payload, _ctx| @links.call(payload) }
+    end
+  end
+end

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -55,8 +55,8 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 **Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
 
 - `model_aliases:` map of alias → model id (`ModelRef.parse`, through `HostRegistry#resolve`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid; only `:` names a host, `org/model` is an id). Aliases apply once: never point an alias at another alias.
-- `hosts:` map of `name → {host, port | url, api, api_key_env, auth, dialect, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `auth:` (`bearer|x-api-key`) is the header the key goes in (default `x-api-key` on `api: anthropic`, Bearer elsewhere); `dialect:` (`fireworks`, or `standard` for the default; `api: anthropic` only) adjusts the Messages wire for that provider (Bearer by default, no thinking `display`, no `cache_control`, `x-session-affinity`; `LLM::Dialect`, docs/configuration.md "Anthropic Messages hosts"); `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; a worker reads `hosts:` from the file as it starts (no environment variable sets hosts).
-- `models:` map of model id or alias → `{profile, vision, sampling, thinking, reasoning_history}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: the session's own level (`/thinking LEVEL`, saved in the session; `chi --thinking` on a session run, `chi send --new --thinking`) > `chi web --thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `reasoning_history:` (here or on a host) is `drop|turn|all`, which of its reasoning a chat host's model gets back. Precedence: the session's own level (`/reasoning-history LEVEL`, saved in the session) > `SAMAGOTCHI_REASONING_HISTORY` > `models:` > `hosts.<name>.reasoning_history` > `turn`; `docs/configuration.md` "Reasoning history". `/thinking` and `/reasoning-history` ask before a change that restarts the prompt cache; `--yes` applies it (`chi send` commands apply directly). `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name whose server publishes no template).
+- `hosts:` map of `name → {host, port | url, api, api_key_env, auth, dialect, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`HostConfig.all`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `auth:` (`bearer|x-api-key`) is the header the key goes in (default `x-api-key` on `api: anthropic`, Bearer elsewhere); `dialect:` (`fireworks`, or `standard` for the default; `api: anthropic` only) adjusts the Messages wire for that provider (Bearer by default, no thinking `display`, no `cache_control`, `x-session-affinity`; `LLM::Dialect`, docs/configuration.md "Anthropic Messages hosts"); `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; a worker reads `hosts:` from the file as it starts (no environment variable sets hosts).
+- `models:` map of model id or alias → `{profile, vision, sampling, thinking, reasoning_history}` (`ModelSettings.all`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: the session's own level (`/thinking LEVEL`, saved in the session; `chi --thinking` on a session run, `chi send --new --thinking`) > `chi web --thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `reasoning_history:` (here or on a host) is `drop|turn|all`, which of its reasoning a chat host's model gets back. Precedence: the session's own level (`/reasoning-history LEVEL`, saved in the session) > `SAMAGOTCHI_REASONING_HISTORY` > `models:` > `hosts.<name>.reasoning_history` > `turn`; `docs/configuration.md` "Reasoning history". `/thinking` and `/reasoning-history` ask before a change that restarts the prompt cache; `--yes` applies it (`chi send` commands apply directly). `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name whose server publishes no template).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
 - `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; config.yml only, like every `guardrails` setting: no env variable), `parent_answers` (`soft`, the default: a parent agent's `chi answer` may deny, answer, Continue and give "Allow once"; `standard`: no allow; `hard`: deny, Stop and plain answers only; never a wider scope; replaces `parent_approvals` and `turn.parent_continue`; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `git`, `models`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`: outside the session's repo, tmp folders and memory files excepted), `git` (only `outside_repo`: a shell call runs commit/add/reset/… in another checkout); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
 

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.155.0
+version: 0.157.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:709bd52710bf6c50334a89a10742ea1554c5985cc2d7c4e7571e526cc4479526
-  config_modification_protocol.md: sha256:f3f6545c93d59b624a2bf1766e26059520ffc7b236470dd9f1b51ab77312376d
-  memory_guide.md: sha256:8b7727b939b9c04486ca59859561023dcc319a73e0f5b47b3fcf5741edaa69e2
+  config_modification_protocol.md: sha256:25ed2d4901f00eeea226db5eb2b75a05d6cdee4015ac8daa4bed624f745c3922
+  memory_guide.md: sha256:fe4dbb25ce4c9f9b51507a6130fa7bf992a2cc41af2453830eacd27c09a65d1e
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd