samagotchi 0.115.0 → 0.116.0

data/lib/samagotchi/memory_bundle/index_updater.rb

@@ -88,6 +88,19 @@ module Samagotchi
         end
       end
 
+      # +entry_name+'s description in +scope+'s index.md — the text after the
+      # " — " on its managed line — or nil when the index has no line for it
+      # or that line carries no description. One small file read.
+      def self.description_for(scope, entry_name)
+        index_path = index_path_for(scope)
+        return nil unless index_path && File.exist?(index_path)
+
+        match = File.read(index_path, encoding: "UTF-8").match(managed_pattern(entry_name))
+        match ? extract_description(match[0].chomp) : nil
+      rescue StandardError
+        nil
+      end
+
       # The bundle a managed line names ("· from <bundle>", before any
       # " — description"), or nil.
       def self.extract_source(line)

data/lib/samagotchi/session_access/contract.rb

@@ -26,7 +26,7 @@ module Samagotchi
       # bin/chi subcommands that act on this machine: never sessions. chi
       # remote (this machine's list of remotes) runs here under a remote too
       # (Dispatch); the others are refused there.
-      MACHINE = %w[bootstrap update models desktop memory bundle remote].freeze
+      MACHINE = %w[bootstrap update models desktop memory bundle guardrails remote].freeze
 
       # "command", "command sub" or either with a flag (its long name) →
       # SUPPORTED or LOCAL_ONLY. A LOCAL_ONLY command or subcommand lists

data/lib/samagotchi/session_commands.rb

@@ -19,6 +19,8 @@ require_relative "reasoning_history_command"
 require_relative "working_set_command"
 require_relative "recap_command"
 require_relative "guardrails/parent_policy"
+require_relative "system_one/log"
+require_relative "system_one/record"
 
 module Samagotchi
   # The session commands a REPL and a session worker both run: /model,
@@ -91,7 +93,7 @@ module Samagotchi
       registry.register(MODELS_COMMAND, "list the hosts' models (/models <text> filters)", anytime: true) do |text|
         reply(models_listing(text.delete_prefix(MODELS_COMMAND).strip))
       end
-      registry.register(GUARDRAILS_COMMAND, "list the guardrail rules and approvals (/guardrails revoke N)",
+      registry.register(GUARDRAILS_COMMAND, "list guardrails, revoke an approval or flag a System 1 auto-allow",
                         mid_turn: show_mid_turn(GUARDRAILS_COMMAND)) do |text|
         guardrails(text.delete_prefix(GUARDRAILS_COMMAND).strip)
       end
@@ -418,11 +420,85 @@ module Samagotchi
 
     def guardrails(args)
       return guardrails_revoke(args.delete_prefix("revoke").strip) if args.start_with?("revoke")
-      return reply("usage: /guardrails [revoke N]", status: :error) unless args.empty?
+      return guardrails_wrong(args.sub(/\Awrong\b/, "").strip) if args.match?(/\Awrong(?:\s|\z)/)
+      return reply("usage: /guardrails [revoke N | wrong [N]]", status: :error) unless args.empty?
 
       reply(guardrails_listing)
     end
 
+    def guardrails_wrong(arg)
+      unless arg.empty? || arg.match?(/\A[1-9]\d*\z/)
+        return reply("usage: /guardrails wrong [N] (N from /guardrails)", status: :error)
+      end
+
+      index = arg.empty? ? 1 : arg.to_i
+      entry = system_one_auto_allows[index - 1]
+      return reply("no unlabelled System 1 auto-allows in this session (see /guardrails)") unless entry
+      unless system_one_log.label(entry["id"], "should_have_asked")
+        return reply("could not label System 1 auto-allow #{index} (see the guardrails log)", status: :error)
+      end
+
+      call = shorten_call(entry["call"].to_s.gsub(/\s+/, " "))
+      probability = entry["p"].nil? ? "unknown" : format("%.2f", entry["p"].to_f)
+      reply("labelled auto-allow #{index}: #{entry["rule"]}: #{call} (p=#{probability}); " \
+            "the rule will ask again until its record is rebuilt")
+    end
+
+    def system_one_log
+      SystemOne::Log.new(dir: File.dirname(@engine.guardrail_approvals.path))
+    end
+
+    def system_one_auto_allows(entries = system_one_entries)
+      session_id = @engine.session&.id
+      return [] unless session_id
+
+      entries.select do |entry|
+        entry["session_id"] == session_id && entry["decision"] == "auto" && entry["answer"].nil?
+      end.last(20).reverse
+    end
+
+    def system_one_entries
+      log = system_one_log
+      File.file?(log.path) ? log.entries : []
+    end
+
+    def system_one_listing(lines)
+      entries = system_one_entries
+      mode = Config.get("guardrails.system_one.mode").to_s
+      return if mode == "off" && entries.empty?
+
+      lines << "System 1 (#{mode}):"
+      auto_allows = system_one_auto_allows(entries)
+      lines << "  auto-allows (this session, newest first; /guardrails wrong N):"
+      if auto_allows.empty?
+        lines << "    (none)"
+      else
+        auto_allows.each_with_index do |entry, index|
+          call = shorten_call(entry["call"].to_s.gsub(/\s+/, " "))
+          probability = entry["p"].nil? ? "unknown" : format("%.2f", entry["p"].to_f)
+          lines << "    #{index + 1}. #{entry["rule"]}: #{call} (p=#{probability})"
+        end
+      end
+
+      rules = entries.filter_map { |entry| entry["rule"] }.uniq.sort
+      lines << "  records:"
+      if rules.empty?
+        lines << "    (none)"
+      else
+        rules.each do |rule|
+          summary = SystemOne::Record.new(entries, rule: rule).summary
+          counts = summary.reject { |key, _| key == :rule }.map { |key, value| "#{key}=#{value}" }.join(", ")
+          lines << "    #{rule}: #{counts}"
+        end
+      end
+    end
+
+    CALL_SHOWN = 100
+
+    def shorten_call(call)
+      call.length > CALL_SHOWN ? "#{call[0, CALL_SHOWN - 1]}…" : call
+    end
+
     def guardrails_listing
       rules = @engine.guardrail_rules
       approvals = @engine.guardrail_approvals.entries
@@ -467,6 +543,7 @@ module Samagotchi
       lines << "  (none)" if approvals.empty?
       approvals.each_with_index { |entry, idx| lines << "  #{idx + 1}. #{approval_line(entry)}" }
       lines << "revoke one with /guardrails revoke N" unless approvals.empty?
+      system_one_listing(lines)
       lines.join("\n")
     end
 

data/lib/samagotchi/session_metrics.rb

@@ -1106,6 +1106,12 @@ module Samagotchi
         active[:via] = via.to_s if via
         # A grep that found nothing (ok): the reloaded web row says "no match".
         active[:no_match] = true if event.dig(:activity, :no_match)
+        # Allowed once by System 1 instead of the user: the reloaded web row
+        # says so and can flag the judgment it came from.
+        guardrail = event.dig(:activity, :guardrail)
+        if guardrail.is_a?(Hash) && guardrail[:decided_by] == "system one"
+          active[:guardrail] = { rule: guardrail[:rule], p: guardrail[:p], judgment_id: guardrail[:judgment_id] }.compact
+        end
         finish_tool_record(active, status.empty? ? "ok" : status, waited_ms: event[:waited_ms].to_i)
       end
     end
@@ -1113,7 +1119,7 @@ module Samagotchi
     # Caller holds the mutex.
     def finish_tool_record(active, status, waited_ms: 0)
       record = active.slice(
-        :id, :turn_id, :iteration, :call_index, :tool, :called_as, :via, :no_match, :started_at
+        :id, :turn_id, :iteration, :call_index, :tool, :called_as, :via, :no_match, :guardrail, :started_at
       ).merge(
         status: status,
         completed_at: now.iso8601(3),

data/lib/samagotchi/system_one/answer.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "question"
+
+module Samagotchi
+  module SystemOne
+    # One judgment the System One API answered: for an :noul question,
+    # `noul` is the probability of "yes"; a :choice answer carries `choice`
+    # (the criterion chosen) and `confidence`; a :score answer carries
+    # `score` (the level's index) and `confidence`. `probabilities` is what
+    # the model put on each option, when it says.
+    Answer = Data.define(:id, :type, :noul, :choice, :score, :confidence, :probabilities) do
+      def initialize(id:, type:, noul: nil, choice: nil, score: nil, confidence: nil, probabilities: nil) = super
+
+      # The response's answers entry as the wire sends it, or nil when it is
+      # not usable: no type, a type the contract doesn't have, a noul
+      # outside 0..1, a score that isn't a whole number, … A nil means "no
+      # judgment for this question", never a guess.
+      def self.from_wire(id, raw)
+        return nil unless raw.is_a?(Hash)
+
+        type = raw["type"].to_s.strip.downcase.to_sym
+        return nil unless QUESTION_TYPES.include?(type)
+
+        confidence = probability(raw["confidence"])
+        odds = probabilities(raw["probabilities"])
+        # A field the server sent but can't read is as unusable as a missing answer.
+        return nil if bad_field(raw, "confidence", confidence) || bad_field(raw, "probabilities", odds)
+
+        answer = { id: id, type: type, confidence: confidence, probabilities: odds }
+
+        case type
+        when :noul
+          noul = probability(raw["noul"])
+          noul.nil? ? nil : new(**answer, noul: noul)
+        when :choice
+          choice = raw["choice"].to_s.strip
+          choice.empty? ? nil : new(**answer, choice: choice)
+        else
+          score = raw["score"]
+          score = score.to_i if score.is_a?(Float) && score.to_i == score
+          score.is_a?(Integer) && score >= 0 ? new(**answer, score: score) : nil
+        end
+      end
+
+      # A value the wire sent that we could not parse.
+      private_class_method def self.bad_field(raw, name, parsed)
+        raw.key?(name) && !raw[name].nil? && parsed.nil?
+      end
+
+      # A probability as written: a number in 0..1, else nil.
+      private_class_method def self.probability(value)
+        return nil unless value.is_a?(Numeric)
+
+        value = value.to_f
+        return nil if value.nan? || value.infinite? || value.negative? || value > 1.0
+
+        value
+      end
+
+      # The probabilities as sent: a map of option => number, or a list of
+      # numbers (the options in order). Anything else is malformed.
+      private_class_method def self.probabilities(value)
+        if value.is_a?(Hash)
+          pairs = value.map { |name, weight| [name.to_s, probability(weight)] }
+          return nil if pairs.any? { |_name, weight| weight.nil? }
+
+          pairs.to_h
+        elsif value.is_a?(Array)
+          weights = value.map { |weight| probability(weight) }
+          return nil if weights.any?(&:nil?)
+
+          weights
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/system_one/approval_question.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "question"
+require_relative "similar"
+
+module Samagotchi
+  module SystemOne
+    # The one question an approval asks System 1: "would this user allow it
+    # without hesitation?" (docs/guardrails.md, "System 1"). The instruction
+    # is a constant in code, reviewed like a prompt; the state is the ask's
+    # own facts — the rule that asked, why, the call, and where it runs — plus
+    # the memory an ask names and the earlier asks it resembles.
+    module ApprovalQuestion
+      ID = "allow"
+      # What the judgment is asked, in the model's terms. Frozen: a change
+      # here is a change in behaviour, not a wording tweak.
+      INSTRUCTIONS = "A coding agent wants to run this tool call, and a guardrail rule asked its user to approve it. " \
+                     "The state names the rule, why it asked, the call and where it runs. Would the user approve it " \
+                     "without hesitation? Users usually approve routine reads, edits of the agent's own notes and " \
+                     "memory, and pushes of verified work; they usually refuse discarding uncommitted work, " \
+                     "interactive rebases, deleting outside the project, and anything irreversible they did not ask " \
+                     "for. The state may also list a few of the user's earlier decisions on calls like this one, " \
+                     "most alike first, each with what they answered."
+      # How much of a command, a diff or a path list the state carries.
+      TEXT_CHARS = 2000
+      # How much of the call the judgment log keeps; its digest is of the whole.
+      CALL_CHARS = 300
+
+      # @return [Question] the noul question for id "allow"
+      def self.question
+        # The type as a string: a symbol here reads as an event type to
+        # spec/web/participant_view_spec.
+        Question.new(id: ID, type: "noul", instructions: INSTRUCTIONS)
+      end
+
+      # @param approval [Hash] payload[:approval]: the ask the user is shown
+      # @param session_title [String, nil] the session's title, when it has one
+      # @param entries [Array<Hash>] SystemOne::Log#entries: the judgments the
+      #   user has answered so far, read once per ask and shared with the
+      #   record gate (GuardrailWiring#system_one_judge)
+      # @return [Hash] the state, with the fields the ask didn't give left out
+      def self.state(approval, session_title: nil, entries: nil)
+        {
+          "rule" => approval[:rule],
+          "source" => approval[:source],
+          "reason" => approval[:reason],
+          "tool" => approval[:tool],
+          "command" => cut(approval[:command]),
+          "paths" => Array(approval[:paths]).map { |path| cut(path) },
+          "change" => change_text(approval[:preview]),
+          "cwd" => approval[:cwd],
+          "repo_name" => approval[:repo_name],
+          "branch" => approval[:branch],
+          "session" => session_title,
+          # Which memory entry the ask is about, when it is a memory ask.
+          "memory" => memory_facts(approval[:memory]),
+          # The asks this one looks like, and what the user did about them.
+          "examples" => Similar.select(entries: entries, rule: approval[:rule], repo_name: approval[:repo_name],
+                                       call_text: call_text(approval))
+        }.reject do |_key, value|
+          value.nil? || (value.is_a?(String) && value.strip.empty?) ||
+            ((value.is_a?(Array) || value.is_a?(Hash)) && value.empty?)
+        end
+      end
+
+      # What the call is, whole: the command, the paths, or a plugin tool's
+      # arguments.
+      def self.call_text(approval)
+        command = approval[:command]
+        return command.to_s if command && !command.to_s.empty?
+
+        paths = Array(approval[:paths])
+        return paths.join("\n") unless paths.empty?
+
+        approval[:args].to_s
+      end
+
+      # The judgment log's two fields for the call: what it was, cut to
+      # CALL_CHARS, and the SHA256 of the whole of it.
+      def self.call_fields(approval)
+        call = call_text(approval)
+        { "call" => cut(call, CALL_CHARS), "call_digest" => Digest::SHA256.hexdigest(call) }
+      end
+
+      # The memory an ask is about, as the approval card built it: entry name,
+      # scope, and (for a removal) the description its index line carries.
+      private_class_method def self.memory_facts(memory)
+        return nil unless memory.is_a?(Hash) && !memory.empty?
+
+        memory.transform_keys(&:to_s).reject { |_key, value| value.to_s.strip.empty? }
+      end
+
+      private_class_method def self.change_text(preview)
+        return nil unless preview.is_a?(Hash)
+
+        text = preview[:text] || preview["text"]
+        return cut(text) if text && !text.to_s.strip.empty?
+
+        note = preview[:error] || preview["error"] || preview[:skipped] || preview["skipped"]
+        return note.to_s unless note.to_s.strip.empty?
+
+        "+#{(preview[:added] || preview["added"]).to_i} −#{(preview[:removed] || preview["removed"]).to_i}"
+      end
+
+      private_class_method def self.cut(text, chars = TEXT_CHARS)
+        text = text.to_s
+        text.length > chars ? "#{text[0, chars - 1]}…" : text
+      end
+    end
+  end
+end

data/lib/samagotchi/system_one/client.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../log"
+require_relative "answer"
+require_relative "errors"
+require_relative "http_backend"
+require_relative "question"
+
+module Samagotchi
+  module SystemOne
+    # The one way anything asks System 1 a question: #ask answers a set of
+    # questions about a state, or says nothing. A backend that is unreachable,
+    # slow, refusing or nonsensical is a nil — no judgment, one log line — and
+    # the caller asks the user as it would have anyway.
+    #
+    #   client = SystemOne::Client.from_config(host_registry: registry)
+    #   client&.ask(state: "git push origin main", questions: {"allow" => question})
+    class Client
+      MODES = %w[off audit on].freeze
+      DEFAULT_TIMEOUT_MS = 2000
+
+      attr_reader :mode, :host, :model, :backend
+
+      def initialize(backend:, mode: "off", host: nil, model: nil)
+        @backend = backend
+        @mode = mode.to_s.strip.downcase
+        @host = host
+        @model = model
+      end
+
+      # nil when judgment is off (the default) or no host is named, so the
+      # caller needs no other check. The settings are read every call: a
+      # config.yml change takes effect on the next ask.
+      # @param model [String, nil] a model for this call only (chi guardrails
+      #   replay --model), else the configured one
+      def self.from_config(host_registry:, env: ENV, model: nil)
+        mode = Config.get("guardrails.system_one.mode").to_s.strip.downcase
+        return nil unless MODES.include?(mode) && mode != "off"
+
+        host = Config.get("guardrails.system_one.host").to_s.strip
+        return nil if host.empty?
+
+        model = (model.nil? ? Config.get("guardrails.system_one.model") : model).to_s.strip
+        timeout_ms = Config.get("guardrails.system_one.timeout_ms").to_i
+        timeout_ms = DEFAULT_TIMEOUT_MS unless timeout_ms.positive?
+
+        new(backend: HttpBackend.new(host_registry: host_registry, host: host, model: model.empty? ? nil : model,
+                                     timeout_ms: timeout_ms, env: env),
+            mode: mode, host: host, model: model.empty? ? nil : model)
+      end
+
+      # @param state [String, Hash, Array] what the question is about, as the
+      #   contract takes it
+      # @param questions [Hash{String => Question|Hash}] the questions, by id
+      # @return [Hash{String => Answer}, nil] one Answer per question, or nil
+      #   when there is no judgment at all
+      def ask(state:, questions:, cancel_controller: nil)
+        questions = SystemOne.normalize_questions(questions)
+        return nil if questions.empty?
+
+        answers = begin
+          @backend.ask(state: state, questions: questions, cancel_controller: cancel_controller)
+        rescue StandardError => e
+          return no_judgment("#{e.class}: #{e.message}", error: e.class.name)
+        end
+
+        unless answers.is_a?(Hash)
+          return no_judgment("the backend returned #{answers.inspect}")
+        end
+
+        answers = questions.to_h { |question| [question.id, answers[question.id]] }
+        missing = questions.reject { |question| answers[question.id].is_a?(Answer) }
+        return no_judgment("no answer for #{missing.map(&:id).join(", ")}") unless missing.empty?
+
+        answers
+      end
+
+      private
+
+      # One warn, one nil: the ask goes to the user.
+      def no_judgment(reason, **fields)
+        # Qualified: inside SystemOne, the bare Log is now SystemOne::Log.
+        Samagotchi::Log.warn(:guardrails, "system_one_failed", echo: "[samagotchi:guardrails] system one: #{reason}", host: @host, **fields)
+        nil
+      end
+    end
+  end
+end

data/lib/samagotchi/system_one/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module SystemOne
+    # A judgment that did not happen: the backend could not reach the host,
+    # the host refused the request, or its answer was not usable. Client#ask
+    # turns any of these into nil (no judgment), so the caller asks the user.
+    class BackendError < StandardError; end
+
+    # The named host is not a System One host: it isn't in hosts:, its api
+    # is not openai, or it names no model.
+    class UnsupportedHost < BackendError; end
+  end
+end

data/lib/samagotchi/system_one/fake_backend.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Samagotchi
+  module SystemOne
+    # The backend the specs use: answers from a block, from a fixed hash, or
+    # an error every time. It never reaches the network.
+    #
+    #   FakeBackend.new { |state, questions| {questions.first.id => answer} }
+    #   FakeBackend.new("git-push" => Answer.from_wire("git-push", {"type" => "noul", "noul" => 0.97}))
+    #   FakeBackend.new(failing: true)
+    class FakeBackend
+      attr_reader :calls
+
+      # @param answers [Hash{String => Answer}, nil] the same answers for
+      #   every call
+      # @param failing [Boolean] true: every #ask raises
+      # @param error [String] what a failing backend says
+      # @param judgments [#call] (state, questions) => {id => Answer}
+      def initialize(answers = nil, failing: false, error: "fake System One backend is unavailable", &judgments)
+        @answers = answers
+        @judgments = judgments
+        @failing = failing
+        @error = error
+        @calls = 0
+      end
+
+      def ask(state:, questions:, cancel_controller: nil)
+        @calls += 1
+        raise BackendError, @error if @failing
+
+        judged = @judgments&.call(state, questions)
+        return judged unless judged.nil?
+
+        ids = Array(questions).map { |question| question.respond_to?(:id) ? question.id : question.to_s }
+        (@answers || {}).select { |id, _answer| ids.include?(id) }
+      end
+
+      def failing? = @failing
+
+      def inspect = "#<#{self.class.name} calls=#{@calls}#{" failing" if @failing}>"
+    end
+  end
+end

data/lib/samagotchi/system_one/http_backend.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "../config"
+require_relative "../llm/api_key"
+require_relative "../llm/http"
+require_relative "answer"
+require_relative "question"
+require_relative "errors"
+
+module Samagotchi
+  module SystemOne
+    # The TypeSafe System One judgment API on a host from config.yml's
+    # `hosts:`: POST <openai_base_url>/systemone (that base already ends in
+    # /v1), one request per #ask, no retries — a judgment that doesn't
+    # arrive in time is no judgment, and the ask goes to the user.
+    #
+    # Works for Splash (a local `api: openai` host serving /v1/systemone)
+    # and for the hosted Jev API the same way; a host whose api isn't
+    # openai is refused.
+    class HttpBackend
+      DEFAULT_TIMEOUT_MS = 2000
+
+      # @param host_registry [HostRegistry] where the host is looked up
+      # @param host [String] the hosts: entry name
+      # @param model [String, nil] the judgment model; nil: the host's first
+      #   model (hosts.<name>.models), and no judgment when it has none
+      # @param timeout_ms [Integer] the whole request's limit, in ms
+      # @param env [Hash] where the host's api_key_env: key is read
+      def initialize(host_registry:, host:, model: nil, timeout_ms: DEFAULT_TIMEOUT_MS, env: ENV)
+        @host_registry = host_registry
+        @host = host.to_s.strip.downcase
+        @model = model.nil? ? nil : model.to_s.strip
+        @timeout_ms = timeout_ms.to_i
+        @env = env
+      end
+
+      # @return [Hash{String => Answer}] one Answer per question, nil for a
+      #   question the response answered badly
+      # @raise [UnsupportedHost] the host is unknown, not an openai host, or
+      #   names no model
+      # @raise [BackendError] the request failed, the status isn't 200, or
+      #   the body isn't a usable response
+      def ask(state:, questions:, cancel_controller: nil)
+        entry = @host_registry.find_entry(@host)
+        raise UnsupportedHost, "host #{@host.inspect} is not in hosts:" unless entry
+        unless entry.api&.to_sym == :openai
+          raise UnsupportedHost, "host #{@host} has api: #{entry.api || "llama_cpp"}; System One speaks the OpenAI-compatible API"
+        end
+
+        model = @model || host_model(entry)
+        raise UnsupportedHost, "host #{@host} names no model for System One" if model.nil? || model.empty?
+
+        url = "#{entry.openai_base_url.to_s.chomp("/")}/systemone"
+        questions = SystemOne.normalize_questions(questions)
+        body = { model: model, state: state, questions: questions.to_h { |question| [question.id, question.to_wire] } }
+        request = json_post(url, body)
+        response = http(entry).fetch(URI(url), request, retries: false, check_status: false, cancel_controller: cancel_controller,
+                                     log_fields: { purpose: "system_one", model: model })
+
+        status = response.code.to_i
+        unless status == 200
+          raise BackendError, "#{@host}: #{status} #{error_detail(response.body)}"
+        end
+
+        answers = answers_of(response.body)
+        questions.to_h { |question| [question.id, Answer.from_wire(question.id, answers[question.id])] }
+      end
+
+      private
+
+      # The host's first model: whatever hosts.<name>.models holds, in the
+      # shape the registry has it in (HostModel by id, or as written).
+      def host_model(entry)
+        models = entry.models
+        return nil if models.nil? || models.empty?
+
+        first = models.is_a?(Hash) ? models.values.first : models.first
+        first.respond_to?(:id) ? first.id : first.to_s
+      end
+
+      # One attempt, closed on the timeout: a judgment is worth at most
+      # timeout_ms, not a retry chain.
+      def http(entry)
+        seconds = @timeout_ms.positive? ? @timeout_ms / 1000.0 : DEFAULT_TIMEOUT_MS / 1000.0
+        open_timeout = [seconds, Config.positive_seconds("server.open_timeout")].min
+        LLM::HTTP.new(label: entry.name, open_timeout: open_timeout, read_timeout: seconds,
+                      retry_policy: LLM::HTTP::RetryPolicy.none,
+                      api_key: LLM::ApiKey.for(entry.api_key_env, host: entry.name, env: @env, scheme: entry.auth_scheme))
+      end
+
+      # The POST the adapters build: JSON body, Content-Type, and the host's
+      # key on the header its auth: names (LLM::HTTP adds it).
+      def json_post(url, body)
+        Net::HTTP::Post.new(URI(url)).tap do |request|
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(body)
+        end
+      end
+
+      def answers_of(body)
+        data = JSON.parse(body.to_s)
+        raise BackendError, "the response is not JSON: #{body.to_s[0, 200]}" unless data.is_a?(Hash)
+
+        answers = data["answers"]
+        raise BackendError, "the response has no answers map" unless answers.is_a?(Hash)
+
+        answers
+      rescue JSON::ParserError => e
+        raise BackendError, "the response is not JSON: #{e.message[0, 200]}"
+      end
+
+      # A 422's detail array, or the body's start, for the log line.
+      def error_detail(body)
+        data = JSON.parse(body.to_s)
+        detail = data["detail"]
+        text = if detail.is_a?(Array)
+                 detail.map { |item| item.is_a?(Hash) ? item["msg"] || item.to_s : item.to_s }.join("; ")
+               else
+                 detail.to_s
+               end
+        text.empty? ? body.to_s[0, 200] : text[0, 200]
+      rescue StandardError
+        body.to_s[0, 200]
+      end
+    end
+  end
+end