samagotchi 0.66.0 → 0.67.0

data/lib/samagotchi/llm/anthropic_messages.rb

@@ -5,11 +5,13 @@ require "uri"
 require_relative "../config"
 require_relative "../sampling_settings"
 require_relative "../thinking"
+require_relative "adapter_common"
 require_relative "errors"
 require_relative "http"
 require_relative "model_listing"
 require_relative "openai_chat"
 require_relative "prompt_cache"
+require_relative "refusal_memo"
 require_relative "anthropic_assembly"
 require_relative "anthropic_wire"
 require_relative "dialect"
@@ -43,10 +45,9 @@ module Samagotchi
     #   names, per model.
     class AnthropicMessages
       include ModelListing
+      include AdapterCommon
 
       API_VERSION = "2023-06-01"
-      DEFAULT_MODELS_TTL = 60
-      MAX_MODEL_PAGES = 20
       # The budget form's budget_tokens per level (a model that takes no
       # adaptive thinking), and Messages' smallest budget.
       BUDGETS = { low: 2048, medium: 8192, high: 24_576 }.freeze
@@ -63,8 +64,6 @@ module Samagotchi
                     \bdisplay\W{0,4}(?:extra\s+inputs\s+are\s+not\s+permitted|is\s+not\s+(?:permitted|allowed|supported))/xi
       # "max_tokens: 200000 > 128000, which is the maximum allowed number of output tokens for …"
       OUTPUT_CAP_RE = /max_tokens`?:?\s*\d+\s*>\s*(\d+)/i
-      # How much of a 200's non-stream body is read as a possible JSON error.
-      PLAIN_ERROR_LIMIT = 64 * 1024
       # max_tokens when default.max_tokens is unset and the model list names
       # none (a listed one is capped by it too).
       DEFAULT_MAX_TOKENS = 64_000
@@ -98,15 +97,12 @@ module Samagotchi
         @api_key_env = api_key_env
         @stream = stream
         init_model_listing(models_ttl)
-        @thinking_form_refused = Set.new
-        @output_caps = {}
-        @cache_control_refused = false
-        @thinking_display_refused = false
-        open_timeout, read_timeout = timeouts(timeout, open_timeout)
-        policy = retry_policy || (retries ? nil : HTTP::RetryPolicy.none)
-        @http = HTTP.new(label: @host_name, open_timeout: open_timeout, read_timeout: read_timeout,
-                         retry_policy: policy, sleeper: sleeper, first_token_timeout: first_token_timeout,
-                         api_key: ApiKey.for(api_key_env, host: @host_name, env: env, scheme: auth || @dialect.auth))
+        # The 400 fixes (#refusal_fix): :thinking_form and :output_cap per
+        # model, :thinking_display and :cache_control for the host.
+        @refusals = RefusalMemo.new
+        @http = build_http(timeout: timeout, open_timeout: open_timeout, retries: retries, retry_policy: retry_policy,
+                           sleeper: sleeper, first_token_timeout: first_token_timeout,
+                           api_key: ApiKey.for(api_key_env, host: @host_name, env: env, scheme: auth || @dialect.auth))
       end
 
       # The same contract as OpenAIChat#chat; +messages+ are ChatLoop's
@@ -170,22 +166,11 @@ module Samagotchi
       # (max_input_tokens, max_tokens, capabilities) and the OpenAI shape a
       # gateway or Splash serves here are both read (ModelListing).
       # Whether +model+ gets the budget form (it refused adaptive thinking).
-      def budget_form?(model) = @thinking_form_refused.include?(model.to_s)
+      def budget_form?(model) = @refusals.refused?(:thinking_form, model.to_s)
 
       # @return [Array<ModelInfo>]
       def list_models
-        models = []
-        after = nil
-        MAX_MODEL_PAGES.times do
-          query = URI.encode_www_form({ limit: 1000, after_id: after }.compact)
-          uri = URI("#{@base_url}/v1/models?#{query}")
-          body = parse_json(@http.fetch(uri, Net::HTTP::Get.new(uri), log_fields: { purpose: "models" }).body, "model list")
-          models.concat(model_entries(body).map { |raw| model_info(raw) })
-          break unless body.is_a?(Hash) && body["has_more"] && body["last_id"]
-
-          after = body["last_id"].to_s
-        end
-        models
+        list_model_pages { |after| URI("#{@base_url}/v1/models?#{URI.encode_www_form({ limit: 1000, after_id: after }.compact)}") }
       end
 
       private
@@ -197,15 +182,6 @@ module Samagotchi
         window.is_a?(Integer) && window.positive? ? window : super
       end
 
-      def timeouts(timeout, open_limit = nil)
-        open_timeout = Samagotchi::Config.positive_seconds("server.open_timeout")
-        read_timeout = Samagotchi::Config.positive_seconds("server.read_timeout")
-        open_timeout = [open_timeout, open_limit].min if open_limit
-        return [open_timeout, read_timeout] unless timeout
-
-        [[open_timeout, timeout].min, timeout]
-      end
-
       # The Messages body: model, max_tokens, the system blocks, the
       # messages, the stream flag, the tools (tool_choice auto with them),
       # then the options as Messages takes them (chi's OpenAI-only fields
@@ -213,11 +189,12 @@ module Samagotchi
       def request_body(messages, tools, model, options)
         options = (options || {}).to_h.transform_keys(&:to_sym).except(*DROPPED_OPTIONS)
         options = budget_form(options) if budget_form?(model)
-        options = without_display(options) if @thinking_display_refused
-        cache = PromptCache.control if @purpose == "chat" && @dialect.cache_breakpoints && !@cache_control_refused
+        options = without_display(options) if @refusals.refused?(:thinking_display)
+        cache = PromptCache.control if @purpose == "chat" && @dialect.cache_breakpoints && !@refusals.refused?(:cache_control)
         translated = AnthropicWire.translate(messages, cache: cache)
         max_tokens = options.delete(:max_tokens) || default_max_tokens(model)
-        max_tokens = [max_tokens, @output_caps[model.to_s]].min if @output_caps[model.to_s]
+        output_cap = @refusals[:output_cap, model.to_s]
+        max_tokens = [max_tokens, output_cap].min if output_cap
         body = { model: model, max_tokens: max_tokens }
         body[:system] = translated.system unless translated.system.empty?
         body[:messages] = translated.messages
@@ -283,21 +260,21 @@ module Samagotchi
         detail = error.detail.to_s
         # Before the adaptive check: the refused field's path
         # ("thinking.adaptive.display") names adaptive too.
-        if !@thinking_display_refused && body[:thinking].is_a?(Hash) && body[:thinking].key?(:display) &&
+        if !@refusals.refused?(:thinking_display) && body[:thinking].is_a?(Hash) && body[:thinking].key?(:display) &&
            DISPLAY_RE.match?(detail)
-          @thinking_display_refused = true
+          @refusals.remember(:thinking_display)
           Log.info(:http, "thinking_display_refused", host: @host_name, detail: detail[0, 200])
           :thinking_display
         elsif body.dig(:thinking, :type) == "adaptive" && ADAPTIVE_REFUSED_RE.match?(detail)
-          @thinking_form_refused << model.to_s
+          @refusals.remember(:thinking_form, model.to_s)
           Log.info(:http, "thinking_form_switched", host: @host_name, model: model.to_s, to: "budget", detail: detail[0, 200])
           :thinking_form
-        elsif !@cache_control_refused && CACHE_CONTROL_RE.match?(detail) && cache_summary(body)
-          @cache_control_refused = true
+        elsif !@refusals.refused?(:cache_control) && CACHE_CONTROL_RE.match?(detail) && cache_summary(body)
+          @refusals.remember(:cache_control)
           Log.info(:http, "cache_control_refused", host: @host_name, detail: detail[0, 200])
           :cache_control
         elsif (cap = detail[OUTPUT_CAP_RE, 1]&.to_i) && cap.positive? && body[:max_tokens].to_i > cap
-          @output_caps[model.to_s] = cap
+          @refusals.remember(:output_cap, model.to_s, cap)
           Log.info(:http, "output_cap", host: @host_name, model: model.to_s, max_tokens: cap)
           :max_tokens
         end
@@ -341,75 +318,21 @@ module Samagotchi
       # `event:` lines are not needed, so a gateway that drops them works);
       # on_delta gets every event but pings, with its text and reasoning.
       def chat_streamed(request, cancel_controller, on_delta, on_retry, log_fields)
-        assembly = AnthropicAssembly.new
-        events = 0
-        other = +""
-        plain = +""
-        # A retry streams the answer from the start again.
-        restart = lambda do |**event|
-          assembly = AnthropicAssembly.new
-          plain = +""
-          on_retry&.call(**event)
-        end
-        @http.stream_lines(URI(request.uri.to_s), request, cancel_controller: cancel_controller, on_retry: restart,
-                                                           log_fields: log_fields) do |line, shown|
-          events += 1 if line.start_with?("data:")
-          other << line[0, 200] if !line.start_with?("data:") && other.length < 200
-          raise_plain_error(plain, line) if events.zero?
-          event = parse_line(line)
-          next unless event
-
+        stream_assembled(request, cancel_controller, on_retry, log_fields, assembly_class: AnthropicAssembly,
+                                                                           what: "stream event") do |assembly, event, shown|
           content, reasoning = assembly.add(event)
           shown.call if AnthropicAssembly.shows?(event)
           on_delta&.call(content: content, reasoning: reasoning, payload: assembly.with_usage(event)) unless event["type"] == "ping"
         end
-        raise ProtocolError.new("#{@host_name}: the response had no stream events: #{other}", host: @host_name) if events.zero?
-
-        assembly.response
-      end
-
-      # A 200 whose body is a plain JSON error instead of a stream: raised
-      # from inside the stream (so it is retried by its kind) once the lines
-      # so far parse as an error object (OpenAIChat's rule).
-      def raise_plain_error(plain, line)
-        return if line.empty? || line.start_with?(":") || (plain.empty? && !line.start_with?("{"))
-        return if plain.bytesize > PLAIN_ERROR_LIMIT
-
-        plain << line << "\n"
-        error = ProviderErrors.from_error_body(plain, host: @host_name)
-        raise error if error
-      end
-
-      # The parsed event of a `data:` line; nil for `event:` lines, blank
-      # lines and comments. An error event raises its ProviderError.
-      def parse_line(line)
-        error = HTTP.sse_error(line, host: @host_name)
-        raise error if error
-        return nil unless line.start_with?("data:")
-
-        data = line.delete_prefix("data:").strip
-        return nil if data.empty? || data == "[DONE]"
-
-        event = parse_json(data, "stream event")
-        event.is_a?(Hash) ? event : nil
-      end
-
-      def parse_json(text, what)
-        JSON.parse(text.to_s)
-      rescue JSON::ParserError => e
-        raise ProtocolError.new("#{@host_name}: malformed #{what}: #{e.message[0, 200]}", host: @host_name)
       end
 
       def post_request(url, body, session_id: nil)
-        Net::HTTP::Post.new(URI(url)).tap do |request|
-          request["Content-Type"] = "application/json"
-          request["anthropic-version"] = API_VERSION
-          unless session_id.to_s.empty?
-            request["Session-Id"] = session_id.to_s
-            request[@dialect.session_header] = session_id.to_s if @dialect.session_header
-          end
-          request.body = JSON.generate(body)
+        headers = { "anthropic-version" => API_VERSION }
+        unless session_id.to_s.empty?
+          headers["Session-Id"] = session_id.to_s
+          headers[@dialect.session_header] = session_id.to_s if @dialect.session_header
         end
+        json_post(url, body, headers)
       end
     end
   end

data/lib/samagotchi/llm/api_key.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "../host_keys"
 
 module Samagotchi
   module LLM
-    # A host's API key: the environment variable its api_key_env: names,
+    # A host's API key: the environment variable its api_key_env: names
+    # (else, on macOS, the login Keychain's item for that name: HostKeys),
     # sent on every request LLM::HTTP makes for the host (llama.cpp started
     # with --api-key, or a provider) in the header its +scheme+ names:
     # :bearer `Authorization: Bearer <key>`, :x_api_key `x-api-key: <key>`
@@ -26,14 +28,15 @@ module Samagotchi
 
       # What to try after a 401/403 from a host that has no api_key_env.
       def self.missing_hint(host)
-        "the server may want an API key: put it in an environment variable and name it with api_key_env: on host #{host}"
+        where = HostKeys.available? ? "an environment variable (or the Keychain)" : "an environment variable"
+        "the server may want an API key: put it in #{where} and name it with api_key_env: on host #{host}"
       end
 
       # Sets the scheme's header (exactly one of the two), or raises
-      # AuthError when the variable is not set.
+      # AuthError when neither the variable nor the Keychain has the key.
       def authorize(request)
-        key = env[env_name].to_s
-        raise AuthError.new("#{host}: set #{env_name} (the API key for host #{host})", host: host) if key.strip.empty?
+        key = HostKeys.fetch(env_name, env: env)
+        raise AuthError.new(unset_message, host: host) unless key
 
         if scheme == :x_api_key
           request.delete("Authorization")
@@ -44,14 +47,27 @@ module Samagotchi
         end
       end
 
-      # What to try after a 401/403 with the key sent.
-      def hint = "check #{env_name} (the API key for host #{host})"
+      # What to try after a 401/403 with the key sent, and where it came
+      # from (a Keychain key is a cache hit by then).
+      def hint
+        from = HostKeys.source(env_name, env: env) == :keychain ? " (from the Keychain)" : ""
+        "check #{env_name}#{from} (the API key for host #{host})"
+      end
 
       # Without the environment: it holds this key and every other secret.
       def inspect = "#<#{self.class.name} #{env_name} host=#{host}#{" scheme=#{scheme}" unless scheme == :bearer}>"
       alias_method :to_s, :inspect
 
       def pretty_print(printer) = printer.text(inspect)
+
+      private
+
+      def unset_message
+        message = "#{host}: set #{env_name} (the API key for host #{host})"
+        return message unless HostKeys.available?
+
+        "#{message} or store it in the Keychain: #{HostKeys.store_command(env_name)}"
+      end
     end
     ApiKey::SCHEMES = %i[bearer x_api_key].freeze
   end

data/lib/samagotchi/llm/chat_loop.rb

@@ -8,6 +8,7 @@ require_relative "errors"
 require_relative "usage"
 require_relative "openai_chat"
 require_relative "native_tool_normalizer"
+require_relative "refusal_memo"
 require_relative "stream_drops"
 require_relative "../kernel_loop"
 require_relative "../answer_display"
@@ -70,6 +71,9 @@ module Samagotchi
         @adapter = adapter
         @stable_length = stable_length
         @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+        # What a host refused per model, for this loop's (the worker's)
+        # life: :reasoning_history, :thinking, :sampling.
+        @refusals = RefusalMemo.new
       end
 
       def provider = :chat
@@ -242,7 +246,7 @@ module Samagotchi
       # blocks always go back (a tool loop with thinking needs the last
       # assistant turn's), whatever the level says.
       def reasoning_history(model = nil)
-        level = model && @reasoning_history_refused&.include?(model) ? :drop : @kernel.turn_settings&.reasoning_history
+        level = model && @refusals.refused?(:reasoning_history, model) ? :drop : @kernel.turn_settings&.reasoning_history
         level ||= :drop
         level == :drop && replays_content? ? :turn : level
       end
@@ -254,7 +258,7 @@ module Samagotchi
       # The host refused +model+'s reasoning sent back: send none from now on
       # (this worker's lifetime, as #thinking_refused!).
       def reasoning_history_refused!(model)
-        (@reasoning_history_refused ||= Set.new) << model
+        @refusals.remember(:reasoning_history, model)
       end
 
       # The turn's VisionContext (the Engine sets the kernel's
@@ -274,14 +278,14 @@ module Samagotchi
       # takes them (OpenAIChat#thinking_fields: Thinking.chat_fields); none
       # for a model whose host refused them (#thinking_refused!).
       def thinking_fields(model = nil)
-        return {} if model && (@thinking_refused ||= Set.new).include?(model)
+        return {} if model && @refusals.refused?(:thinking, model)
 
         adapter.thinking_fields(thinking)
       end
 
       # The host refused +model+'s thinking fields: leave them out from now on.
       def thinking_refused!(model)
-        (@thinking_refused ||= Set.new) << model
+        @refusals.remember(:thinking, model)
       end
 
       # One generation's options: default.max_tokens as max_tokens (the
@@ -296,7 +300,7 @@ module Samagotchi
         options = deep_merge(thinking_fields(model), sampling)
         options = { max_tokens: max_tokens }.merge(options) if max_tokens
         options = EmptyAnswerRetry.sampling(options) if retry_generation
-        options = options.except(*SAMPLING_KEYS) if model && @sampling_refused&.include?(model)
+        options = options.except(*SAMPLING_KEYS) if model && @refusals.refused?(:sampling, model)
         deep_compact(options)
       end
 
@@ -306,7 +310,7 @@ module Samagotchi
       # The host refused a sampling field for +model+: send none of
       # SAMPLING_KEYS from now on (this worker's lifetime, as #thinking_refused!).
       def sampling_refused!(model)
-        (@sampling_refused ||= Set.new) << model
+        @refusals.remember(:sampling, model)
       end
 
       def strip_model_thought(text) = @kernel.strip_model_thought(text)

data/lib/samagotchi/llm/openai_chat.rb

@@ -5,6 +5,7 @@ require "uri"
 require_relative "../config"
 require_relative "../sampling_settings"
 require_relative "../thinking"
+require_relative "adapter_common"
 require_relative "errors"
 require_relative "http"
 require_relative "model_listing"
@@ -70,11 +71,8 @@ module Samagotchi
     # only; the chat loop owns the conversation and the tools.
     class OpenAIChat
       include ModelListing
+      include AdapterCommon
 
-      MAX_MODEL_PAGES = 20
-      # How much of a 200's non-stream body is read as a possible JSON error.
-      PLAIN_ERROR_LIMIT = 64 * 1024
-      DEFAULT_MODELS_TTL = 60
       # OpenRouter holds a paid request's estimated cost against the balance
       # while it runs: the input plus the output max_tokens allows (a fixed
       # per-request cap when it is unset), and refuses a request with a 402
@@ -154,11 +152,9 @@ module Samagotchi
         @api_key_env = api_key_env
         @stream = stream
         init_model_listing(models_ttl)
-        open_timeout, read_timeout = timeouts(timeout, open_timeout)
-        policy = retry_policy || (retries ? nil : HTTP::RetryPolicy.none)
-        @http = HTTP.new(label: @host_name, open_timeout: open_timeout, read_timeout: read_timeout,
-                         retry_policy: policy, sleeper: sleeper, first_token_timeout: first_token_timeout,
-                         api_key: ApiKey.for(api_key_env, host: @host_name, env: env, scheme: auth))
+        @http = build_http(timeout: timeout, open_timeout: open_timeout, retries: retries, retry_policy: retry_policy,
+                           sleeper: sleeper, first_token_timeout: first_token_timeout,
+                           api_key: ApiKey.for(api_key_env, host: @host_name, env: env, scheme: auth))
       end
 
       # @param messages [Array<Hash>] wire messages (role, content, tool_calls,
@@ -180,33 +176,12 @@ module Samagotchi
                        cache: cache_summary(body[:messages]), cache_by: ("session" if body.key?(:prompt_cache_key)) }
         return chat_once(request, cancel_controller, log_fields) unless @stream
 
-        assembly = Assembly.new
-        events = 0
-        other = +""
-        plain = +""
-        # A retry streams the answer from the start again.
-        restart = lambda do |**event|
-          assembly = Assembly.new
-          plain = +""
-          on_retry&.call(**event)
-        end
-        @http.stream_lines(URI(request.uri.to_s), request, cancel_controller: cancel_controller, on_retry: restart,
-                                                           log_fields: log_fields) do |line, shown|
-          events += 1 if line.start_with?("data:")
-          other << line[0, 200] if !line.start_with?("data:") && other.length < 200
-          raise_plain_error(plain, line) if events.zero?
-          payload = parse_line(line)
-          next unless payload
-
+        stream_assembled(request, cancel_controller, on_retry, log_fields, assembly_class: Assembly,
+                                                                           what: "stream chunk") do |assembly, payload, shown|
           content, reasoning = assembly.add(payload)
           shown.call if !content.empty? || !reasoning.empty? || Assembly.tool_call_delta?(payload)
           on_delta&.call(content: content, reasoning: reasoning, payload: payload)
         end
-        # A server that ignores stream: true, or answers with something else
-        # entirely, would otherwise end the turn with no answer and no error.
-        raise ProtocolError.new("#{@host_name}: the response had no stream events: #{other}", host: @host_name) if events.zero?
-
-        assembly.response
       end
 
       # A provider on the network: no llama.cpp /props to ask for the window.
@@ -233,17 +208,7 @@ module Samagotchi
 
       # @return [Array<ModelInfo>] the host's models (every page)
       def list_models
-        models = []
-        after = nil
-        MAX_MODEL_PAGES.times do
-          uri = URI("#{@base_url}/models#{"?after=#{URI.encode_www_form_component(after)}" if after}")
-          body = parse_json(@http.fetch(uri, get_request(uri), log_fields: { purpose: "models" }).body, "model list")
-          models.concat(model_entries(body).map { |raw| model_info(raw) })
-          break unless body.is_a?(Hash) && body["has_more"] && body["last_id"]
-
-          after = body["last_id"].to_s
-        end
-        models
+        list_model_pages { |after| URI("#{@base_url}/models#{"?after=#{URI.encode_www_form_component(after)}" if after}") }
       end
 
       def self.served_model(payload)
@@ -260,15 +225,6 @@ module Samagotchi
 
       private
 
-      def timeouts(timeout, open_limit = nil)
-        open_timeout = Samagotchi::Config.positive_seconds("server.open_timeout")
-        read_timeout = Samagotchi::Config.positive_seconds("server.read_timeout")
-        open_timeout = [open_timeout, open_limit].min if open_limit
-        return [open_timeout, read_timeout] unless timeout
-
-        [[open_timeout, timeout].min, timeout]
-      end
-
       def request_body(messages, tools, model, options, session_id)
         body = {
           model: model,
@@ -364,49 +320,10 @@ module Samagotchi
 
       def served_provider(payload) = self.class.served_provider(payload)
 
-      # The parsed payload of a `data:` line; nil for blank lines, comments
-      # and [DONE]. Error events raise their ProviderError.
-      # A 200 whose body is a plain JSON error instead of a stream (OpenRouter
-      # sends an upstream 503 so): raised, from inside the stream so it is
-      # retried by its kind, once the lines so far parse as an error object.
-      def raise_plain_error(plain, line)
-        return if line.empty? || line.start_with?(":") || (plain.empty? && !line.start_with?("{"))
-        return if plain.bytesize > PLAIN_ERROR_LIMIT
-
-        plain << line << "\n"
-        error = ProviderErrors.from_error_body(plain, host: @host_name)
-        raise error if error
-      end
-
-      def parse_line(line)
-        error = HTTP.sse_error(line, host: @host_name)
-        raise error if error
-        return nil unless line.start_with?("data:")
-
-        data = line.delete_prefix("data:").strip
-        return nil if data.empty? || data == "[DONE]"
-
-        payload = parse_json(data, "stream chunk")
-        payload.is_a?(Hash) ? payload : nil
-      end
-
-      def parse_json(text, what)
-        JSON.parse(text.to_s)
-      rescue JSON::ParserError => e
-        raise ProtocolError.new("#{@host_name}: malformed #{what}: #{e.message[0, 200]}", host: @host_name)
-      end
-
       def post_request(url, body, session_id: nil)
-        uri = URI(url)
-        Net::HTTP::Post.new(uri).tap do |request|
-          request["Content-Type"] = "application/json"
-          request["Session-Id"] = session_id.to_s unless session_id.to_s.empty?
-          request.body = JSON.generate(body)
-        end
+        json_post(url, body, session_id.to_s.empty? ? {} : { "Session-Id" => session_id.to_s })
       end
 
-      def get_request(uri) = Net::HTTP::Get.new(uri)
-
       # Streamed deltas put together: text, reasoning, tool calls by index,
       # the finish reason, the usage chunk, the served model and provider.
       class Assembly

data/lib/samagotchi/llm/refusal_memo.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # What a host refused, remembered for its holder's life (an adapter: the
+    # host's, HostRegistry keeps one per worker; ChatLoop: the worker's): a
+    # +kind+ (a Symbol) for one model, or for the whole host when the model
+    # is nil, with a value (true, or what the refusal named: an output cap).
+    # The turn, side-ask and recap threads share a holder, so every read and
+    # write takes the lock.
+    class RefusalMemo
+      def initialize
+        @mutex = Mutex.new
+        @facts = {}
+      end
+
+      # Remember +kind+ for +model+ (nil: the host) as +value+.
+      def remember(kind, model = nil, value = true)
+        @mutex.synchronize { @facts[[kind, model]] = value }
+      end
+
+      # Whether +kind+ is remembered for +model+ (nil: the host).
+      def refused?(kind, model = nil) = @mutex.synchronize { @facts.key?([kind, model]) }
+
+      # The value remembered for +kind+ and +model+, or nil.
+      def [](kind, model = nil) = @mutex.synchronize { @facts[[kind, model]] }
+    end
+  end
+end

data/lib/samagotchi/llm_context_override.rb

@@ -153,6 +153,7 @@ module Samagotchi
     end
 
     # "64000", "64k" or "off" (0): LLMContextStrategy.budget_tokens.
+    # .update reaches it (and the other parse_<field>s) by its name.
     # @return [Integer] 0 for off
     def self.parse_budget_tokens(text) = LLMContextStrategy.budget_tokens(text)
 

data/lib/samagotchi/peer_sources.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "context_sources"
+
+module Samagotchi
+  # The attached context sources a loaded peer bundle declared as its
+  # peer's answers (chi.peer_source: claude-review, codex-review), with the
+  # peer's name ("Claude"). In-process only: a source is a peer's because
+  # the bundle's code says so, never because of what a source file holds,
+  # which a pushing process can write. Uninstalling the bundle ends it.
+  #
+  # A declared name counts only for a pushed source in the session's own
+  # location (ContextAbsorber#peer_label): a command or project source of
+  # that name is an ordinary one. See docs/context.md (Waking).
+  class PeerSources
+    # The peer's name, shown inside chi's own framing lines.
+    LABEL = /\A[A-Z][A-Za-z ]{0,23}\z/
+
+    def initialize
+      @labels = {}
+      @bundles = {}
+      @lock = Mutex.new
+    end
+
+    # Checks +name+ and +label+ before a plugin's registrations commit.
+    # @raise [ArgumentError]
+    def check!(name, label:, bundle:)
+      name = name.to_s
+      begin
+        ContextSources.check_name!(name)
+      rescue ContextSources::Invalid => e
+        raise ArgumentError, "peer source: #{e.message}"
+      end
+      raise ArgumentError, "peer source #{name}: label must match #{LABEL.inspect}" unless label.to_s.match?(LABEL)
+
+      taken = @lock.synchronize { @bundles[name] }
+      raise ArgumentError, "peer source #{name} is already declared (#{taken})" if taken && taken != bundle
+
+      name
+    end
+
+    # Declares +name+ +label+'s answers (+bundle+: who declared it).
+    # @raise [ArgumentError]
+    def declare(name, label:, bundle:)
+      name = check!(name, label: label, bundle: bundle)
+      @lock.synchronize do
+        @labels[name] = label.to_s
+        @bundles[name] = bundle
+      end
+      nil
+    end
+
+    # @return [String, nil] the peer's name when +name+ is declared
+    def label_for(name) = @lock.synchronize { @labels[name.to_s] }
+
+    def names = @lock.synchronize { @labels.keys }
+  end
+end