samagotchi 0.78.0 → 0.80.0

data/lib/samagotchi/llm/anthropic_wire.rb

@@ -32,8 +32,10 @@ module Samagotchi
       TOOL_ID_INVALID = /[^a-zA-Z0-9_-]/
       # What Messages takes as a tool name.
       TOOL_NAME = /\A[a-zA-Z0-9_-]{1,128}\z/
+      # The content block types a model's thinking is replayed in.
+      THINKING_TYPES = %w[thinking redacted_thinking].freeze
       # Blocks that can't carry a cache_control breakpoint.
-      UNMARKABLE = %w[thinking redacted_thinking].freeze
+      UNMARKABLE = THINKING_TYPES
 
       # A request's system blocks and messages.
       Translated = Data.define(:system, :messages)
@@ -105,6 +107,10 @@ module Samagotchi
         end
       end
 
+      # Whether +block+ is a thinking or redacted_thinking block (a Hash,
+      # string or symbol keys).
+      def thinking_block?(block) = block.is_a?(Hash) && THINKING_TYPES.include?(type_of(block))
+
       # +id+ as Messages takes it (^[a-zA-Z0-9_-]+$), the same in tool_use
       # and tool_result: a valid id as it is, another with its invalid
       # characters replaced and a short hash of it appended (so "a.b" and

data/lib/samagotchi/llm/chat_loop.rb

@@ -342,15 +342,6 @@ module Samagotchi
         nil
       end
 
-      # The shape the engine persists: role and content (parts stay an
-      # Array), plus a model turn's tool_calls and thinking (the host's
-      # reasoning, sent back as #wire_messages says), a result's tool_call_id, the image
-      # refs of a user message or a tool result, a prompt's turn_id (Engine,
-      # never sent) and a wake turn's report's turn_start (Steer, never sent), and a plugin tool result's tool_params and tool_labels
-      # (the live row's params line and label, never sent back), an
-      # edit/write result's tool_diffs (never sent), an empty-answer
-      # note's marker (TurnNote.empty, never sent), and an answer's display
-      # and display_refs (AnswerDisplay, AnswerRefs; never sent).
       # Removes the replayed thinking blocks a response's ThinkingDrop
       # names (AnthropicWire.block_identity) from the model entries'
       # anthropic_content: the edit the provider made for that request, so
@@ -375,6 +366,15 @@ module Samagotchi
         removed
       end
 
+      # The shape the engine persists: role and content (parts stay an
+      # Array), plus a model turn's tool_calls and thinking (the host's
+      # reasoning, sent back as #wire_messages says), a result's tool_call_id, the image
+      # refs of a user message or a tool result, a prompt's turn_id (Engine,
+      # never sent) and a wake turn's report's turn_start (Steer, never sent), and a plugin tool result's tool_params and tool_labels
+      # (the live row's params line and label, never sent back), an
+      # edit/write result's tool_diffs (never sent), an empty-answer
+      # note's marker (TurnNote.empty, never sent), and an answer's display
+      # and display_refs (AnswerDisplay, AnswerRefs; never sent).
       def plain(conversation)
         conversation.map do |entry|
           content = entry[:content].is_a?(Array) ? entry[:content] : entry[:content].to_s
@@ -471,8 +471,6 @@ module Samagotchi
 
       def thought?(entry) = entry[:thinking].is_a?(String) && !entry[:thinking].strip.empty?
 
-      THINKING_BLOCKS = %w[thinking redacted_thinking].freeze
-
       # A model entry's saved blocks (anthropic_content) to send back
       # verbatim, for an adapter that replays them: nil when there are none,
       # for an interrupted entry (its partial blocks have no signature), and
@@ -485,7 +483,7 @@ module Samagotchi
         return nil unless replays_content? && blocks.is_a?(Array) && !blocks.empty? && !entry[:interrupted]
         return nil unless Array(entry[:tool_calls]).all? { |call| paired.include?(call[:id]) }
 
-        blocks = blocks.reject { |block| block.is_a?(Hash) && THINKING_BLOCKS.include?((block["type"] || block[:type]).to_s) } unless keep_thinking
+        blocks = blocks.reject { |block| AnthropicWire.thinking_block?(block) } unless keep_thinking
         blocks.empty? ? nil : blocks
       end
 
@@ -519,6 +517,17 @@ module Samagotchi
           # The empty generations, never saved: the UIs draw the turn's
           # steps from them (ModelResult#empty_steps).
           @empty_steps = []
+          # Set as the run goes: the last response's refusal, the context
+          # window the last request was sized for, that request's text and
+          # image estimates, whether a refused reasoning is being asked
+          # again without it, and whether a preserved-thinking recovery
+          # settled nothing once already.
+          @refusal = nil
+          @window = nil
+          @request_chars = nil
+          @request_image_tokens = nil
+          @without_reasoning = false
+          @recovery_repeated = false
           @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context)
           loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context,
                                                              emit: method(:emit))

data/lib/samagotchi/llm/http.rb

@@ -43,8 +43,9 @@ module Samagotchi
 
       # Requests of these purposes are the ones a turn waits on (or, for the
       # turn-end warm-up, prepares the next one): INFO lines (and ERROR when
-      # they fail). Probes and model lists are DEBUG.
-      LOGGED_PURPOSES = %w[chat recap warmup].freeze
+      # they fail); so are a plugin's ctx.http calls ("plugin"). Probes and
+      # model lists are DEBUG.
+      LOGGED_PURPOSES = %w[chat recap warmup plugin].freeze
 
       # Exponential backoff: base_delay * 2^(attempt-1), capped at max_delay,
       # for up to +max+ retries (max + 1 attempts).
@@ -103,10 +104,13 @@ module Samagotchi
       #   show something (see #stream_lines); nil: no limit
       # @param api_key [ApiKey, nil] sent on every request; nil: no
       #   Authorization header (a local server)
+      # @param diagnosis_header [String, nil] a response header the adapter
+      #   wants kept on a ProviderError as its diagnosis; nil: none
       def initialize(label:, open_timeout:, read_timeout:, retry_policy: nil, sleeper: nil, first_token_timeout: nil,
-                     api_key: nil)
+                     api_key: nil, diagnosis_header: nil)
         @label = label
         @api_key = api_key
+        @diagnosis_header = diagnosis_header
         @open_timeout = open_timeout
         @read_timeout = read_timeout
         @first_token_timeout = first_token_timeout&.positive? ? first_token_timeout : nil
@@ -187,11 +191,11 @@ module Samagotchi
       # @raise [RequestCancelled] when +cancel_controller+ cancels (with or
       #   without retries)
       def fetch(uri, request, retries: true, check_status: true, open_timeout: nil, read_timeout: nil,
-                cancel_controller: nil, log_fields: {})
+                write_timeout: nil, cancel_controller: nil, log_fields: {})
         identify(request)
         current = new_attempt_state(uri, request, log_fields, stream: false)
         attempt = lambda do |state|
-          start(uri, open_timeout: open_timeout, read_timeout: read_timeout, max_retries: 0) do |http|
+          start(uri, open_timeout: open_timeout, read_timeout: read_timeout, write_timeout: write_timeout, max_retries: 0) do |http|
             state[:http] = http
             http.request(request).tap do |response|
               state[:status] = response.code.to_i
@@ -221,8 +225,9 @@ module Samagotchi
         @api_key&.authorize(request)
       end
 
-      def start(uri, open_timeout: nil, read_timeout: nil, max_retries: nil, &)
+      def start(uri, open_timeout: nil, read_timeout: nil, write_timeout: nil, max_retries: nil, &)
         options = { open_timeout: open_timeout || @open_timeout, read_timeout: read_timeout || @read_timeout }
+        options[:write_timeout] = write_timeout if write_timeout
         # Net::HTTP retries an idempotent request once on its own (max_retries
         # defaults to 1) when the connection drops before an answer: chi's
         # RetryPolicy owns retries (and the log line says how many were sent),
@@ -418,7 +423,7 @@ module Samagotchi
 
         error = ProviderErrors.from_response(status: status, body: response.body.to_s, host: @label,
                                              retry_after: response["Retry-After"],
-                                             diagnosis: response["anthropic-thinking-prefix-mismatch"])
+                                             diagnosis: @diagnosis_header && response[@diagnosis_header])
         error.hint ||= @api_key ? @api_key.hint : ApiKey.missing_hint(@label) if error.is_a?(AuthError)
         raise error
       end

data/lib/samagotchi/llm/model_listing.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../log"
+
 module Samagotchi
   module LLM
     # A model a host lists. Unknown fields are nil.
@@ -51,7 +53,10 @@ module Samagotchi
 
       def init_model_listing(models_ttl)
         @models_ttl = models_ttl
+        @models_failure_ttl = [models_ttl, 60].min
         @models_mutex = Mutex.new
+        @models_failure_at = nil
+        @models_failure_logged_at = nil
       end
 
       # +model+'s entry in the cached list: its exact id, else any case.
@@ -93,16 +98,39 @@ module Samagotchi
       end
 
       def cached_models
+        now = monotonic
         @models_mutex.synchronize do
-          fresh = @models_at && (monotonic - @models_at) < @models_ttl
+          fresh = @models_at && (now - @models_at) < @models_ttl
           return @models if fresh
+
+          failed_recently = @models_failure_at && (now - @models_failure_at) < @models_failure_ttl
+          return [] if failed_recently
         end
         models = list_models
         @models_mutex.synchronize do
           @models = models
           @models_at = monotonic
+          @models_failure_at = nil
         end
         models
+      rescue StandardError => e
+        @models_mutex.synchronize { @models_failure_at = monotonic }
+        log_model_listing_failure(e)
+        raise
+      end
+
+      def log_model_listing_failure(error)
+        now = monotonic
+        should_log = @models_mutex.synchronize do
+          next false if @models_failure_logged_at && (now - @models_failure_logged_at) < @models_ttl
+
+          @models_failure_logged_at = now
+          true
+        end
+        return unless should_log
+
+        host = @host_name.to_s.empty? ? @base_url : @host_name
+        Log.warn(:model, "list_failed", host: host, error: error.class.name, msg: error.message.to_s[0, 500])
       end
 
       def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)

data/lib/samagotchi/llm/refusal_memo.rb

@@ -6,8 +6,9 @@ module Samagotchi
     # 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.
+    # The turn thread and the model-list reads share HostRegistry's adapter
+    # (an IdleClient's adapter is its own), so every read and write takes the
+    # lock.
     class RefusalMemo
       def initialize
         @mutex = Mutex.new

data/lib/samagotchi/plugin/card.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Samagotchi
+  module Plugin
+    # A card's checked event (docs/plugins.md, Cards): what Engine#show_card
+    # routes and the bundle test kit records.
+    module Card
+      LEVELS = %i[info warn].freeze
+      MAX_ACTIONS = 6
+
+      module_function
+
+      # @return [Hash] {type: :card, id:, source:, title:, body:, level:,
+      #   actions: [{label:, command:}]}; a new id when none is given
+      # @raise [ArgumentError] a card without a title, a bad level or action
+      def build(source:, title:, body:, actions:, level:, id:)
+        title = title.to_s.strip
+        raise ArgumentError, "a card needs a title" if title.empty?
+
+        level = level.to_s.to_sym
+        raise ArgumentError, "card level must be one of #{LEVELS.join(", ")}" unless LEVELS.include?(level)
+
+        actions = Array(actions)
+        raise ArgumentError, "a card has at most #{MAX_ACTIONS} actions" if actions.size > MAX_ACTIONS
+
+        actions = actions.map do |action|
+          raise ArgumentError, "a card action is a Hash {label:, command:}" unless action.is_a?(Hash)
+
+          action = action.transform_keys(&:to_sym)
+          command = action[:command].to_s.strip
+          raise ArgumentError, "a card action needs a command" if command.empty? || command.include?("\n")
+
+          label = action[:label].to_s.strip
+          { label: label.empty? ? command : label, command: command }
+        end
+        id = id.to_s.strip
+        { type: :card, id: id.empty? ? SecureRandom.hex(4) : id, source: source.to_s, title: title, body: body.to_s,
+          level: level, actions: actions }
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/context.rb

@@ -6,18 +6,32 @@ require_relative "../paths"
 require_relative "../guardrails/context"
 require_relative "../idle_client"
 require_relative "side_question"
-require_relative "sessions"
-require_relative "attached_context"
 
 module Samagotchi
+  # Context#saved_session reads it; Sessions and AttachedContext load it too.
+  autoload :Session, File.expand_path("../session", __dir__)
+
   module Plugin
+    # Loaded on first ctx.sessions / ctx.context (or a bundle naming
+    # Sessions::Error): they pull in the session, delivery and bridge
+    # client files (~150), which a plugin that never calls them, and the
+    # bundle test kit, don't need.
+    autoload :Sessions, File.expand_path("sessions", __dir__)
+    autoload :AttachedContext, File.expand_path("attached_context", __dir__)
+    # ctx.http's file needs only json and uri (net/http loads with the first
+    # real request); autoloaded so a bundle can name HttpError at load time.
+    autoload :Http, File.expand_path("http", __dir__)
+    autoload :HttpError, File.expand_path("http", __dir__)
+    autoload :HttpCancelled, File.expand_path("http", __dir__)
+
     # The Engine's side of a Context: callables, so the Engine itself is
     # never handed out. +messages+ returns the conversation, +notify+ takes
     # (text, level, label, fallback_for:), +ask_user+ takes (question:, options:, header:,
     # allow_freeform:, hook:) like the hook runtime's, +card+ takes
     # Engine#show_card's keywords and returns the id, +ask_model+ takes
-    # (chat messages, timeout:, max_tokens:, cancel_controller:) and returns
-    # the answer text.
+    # (chat messages, timeout:, max_tokens:, cancel_controller:, model:: a
+    # configured model ref, nil for the session's) and returns the answer
+    # text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +prompt_files+ returns the files whose text the built system prompt
     # holds (SystemPrompt#prompt_files, [] before a build); +model_name+
@@ -32,10 +46,14 @@ module Samagotchi
     # +toolkit+ returns the session's toolkit name, +declared_tools+ the
     # tool names its next turn declares, +use_toolkit+ takes a name and
     # returns whether it staged it (Engine#use_toolkit).
+    # +cancel_controller+ takes (handler:) and returns the controller a
+    # ctx.http call without cancel: uses, nil for none: an init task's own,
+    # else the running turn's for work done for it (the turn's thread, or a
+    # plugin handler: +handler+) until the turn has ended.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
-                      keyword_init: true)
+                      :cancel_controller, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -85,7 +103,12 @@ module Samagotchi
       # @param label [String] "<file> (bundle <name>)", what notices and
       #   questions are labelled by
       # @param host [Host]
-      def initialize(bundle:, label:, settings:, host:, env: ENV)
+      # @param sessions [Object, nil] what #sessions returns instead of a
+      #   Sessions over +host+ (the test kit's recording one)
+      # @param http_transport [#call, nil] what #http sends through instead
+      #   of the network (the test kit's FakeHttp); the default cancel
+      #   lookup stays the Context's own
+      def initialize(bundle:, label:, settings:, host:, env: ENV, sessions: nil, http_transport: nil)
         @bundle = bundle.to_s
         @label = label
         @settings = deep_freeze(settings.is_a?(Hash) ? settings : {})
@@ -94,6 +117,9 @@ module Samagotchi
         @log = Logger.new(@bundle)
         @git = Guardrails::GitInfo.new
         @data_dir = nil
+        @sessions = sessions
+        @http_transport = http_transport
+        @http = nil
       end
 
       # The bundle, never the environment it holds (every API key in it).
@@ -254,15 +280,21 @@ module Samagotchi
       #   ASK_MAX_TOKENS); an answer cut off ends with "…"
       # @param cancel [CancellationController, nil] cancelling it aborts
       #   the request
+      # @param model [String, nil] a configured model ("host:id", an alias,
+      #   or a model id one of the hosts lists) instead of the session's:
+      #   keys stay chi's config, a plugin never names a URL or a key
       # @return [String] the answer ("" when the model said nothing)
+      # @raise [ArgumentError] no prompt, or a +model+ that names nothing configured
       # @raise [ModelError] the request failed or timed out
       # @raise [ModelCancelled] +cancel+ was cancelled
-      def ask_model(messages:, prompt:, system: nil, timeout: 120, max_tokens: nil, cancel: nil)
+      def ask_model(messages:, prompt:, system: nil, timeout: 120, max_tokens: nil, cancel: nil, model: nil)
         raise ArgumentError, "ask_model needs a prompt" if prompt.to_s.strip.empty?
+        raise ArgumentError, "ask_model's model: is a String like \"host:id\"" unless model.nil? || (model.is_a?(String) && !model.strip.empty?)
 
         request = SideQuestion.request(messages: messages, prompt: prompt, system: system)
         limit = max_tokens.nil? ? ASK_MAX_TOKENS : Integer(max_tokens)
-        @host.ask_model.call(request, timeout: Float(timeout), max_tokens: limit, cancel_controller: cancel).to_s
+        @host.ask_model.call(request, timeout: Float(timeout), max_tokens: limit, cancel_controller: cancel,
+                                      model: model&.strip).to_s
       rescue IdleClient::SummarizeError => e
         raise ModelError, e.message
       rescue LLM::RequestCancelled
@@ -279,6 +311,16 @@ module Samagotchi
         @sessions ||= Sessions.new(@host)
       end
 
+      # An HTTP client for calling services (Http, docs/plugins.md). A call
+      # made for the turn (a tool, a handler) stops when the turn is stopped;
+      # one from a command, a service or your own thread has only its
+      # timeout unless it passes cancel:.
+      # @return [Http]
+      def http
+        @http ||= Http.new(bundle: @bundle, transport: @http_transport,
+                           cancel_lookup: -> { @host.cancel_controller&.call(handler: in_handler?) })
+      end
+
       # This session's attached context: attach a URL or a command, list
       # (AttachedContext).
       # @return [AttachedContext]
@@ -342,6 +384,9 @@ module Samagotchi
 
       private
 
+      # Whether this plugin's handler runs on this thread (#with_event).
+      def in_handler? = !!Thread.current[CURRENT_EVENTS]&.key?(self)
+
       # The event[:x] helper of the event this plugin's handler runs for on
       # this thread, or nil (not in a handler).
       def event_helper(name)

data/lib/samagotchi/plugin/http.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Samagotchi
+  module Plugin
+    # ctx.http failed: the request didn't complete (refused, timed out, DNS,
+    # TLS, reset, a malformed response, a bad gzip body), or Response#json
+    # was called on a body that isn't JSON. The message says what and where,
+    # never headers or a body; the original error is the #cause.
+    class HttpError < StandardError; end
+
+    # A ctx.http request was cancelled (its cancel: controller, or the turn's
+    # Stop).
+    class HttpCancelled < HttpError; end
+
+    # An HTTP client for a plugin (ctx.http, docs/plugins.md): a few methods,
+    # a small Response, one error type (HttpError). It checks its arguments
+    # and builds the request; a transport (Http::NetTransport by default,
+    # the test kit's FakeHttp) puts it on the wire.
+    #
+    # Stateless apart from its bundle's name and its transport: any number of
+    # threads may call it.
+    #
+    # This file needs only json and uri: net/http and chi's HTTP layer load
+    # with the first real request (NetTransport).
+    class Http
+      # What a request is given as the timeout (open, and per read) when none is.
+      DEFAULT_TIMEOUT = 10
+      METHODS = %w[GET POST PUT PATCH DELETE HEAD].freeze
+
+      # One answer. +headers+ is frozen, with lower-case names and a repeated
+      # header's values joined with ", "; +body+ is never nil (HEAD and empty
+      # bodies are ""), tagged UTF-8 when its bytes are valid UTF-8, else
+      # left binary (scrub it before handing unknown text to the model).
+      Response = Data.define(:status, :headers, :body) do
+        # @return [Boolean] a 2xx status
+        def ok? = status.between?(200, 299)
+
+        # The body parsed as JSON, on each call (a Data keeps nothing).
+        # @raise [HttpError] the body isn't JSON
+        def json
+          JSON.parse(body)
+        rescue JSON::ParserError, EncodingError
+          raise HttpError, "not JSON: status #{status}, #{body.bytesize} bytes"
+        end
+      end
+
+      # @param bundle [String] the bundle's name (the log line's bundle=)
+      # @param cancel_lookup [#call] → the CancellationController a call
+      #   without cancel: uses (nil: none), read at call time
+      # @param transport [#call, nil] call(method:, uri:, headers:, body:,
+      #   timeout:, cancel:) → Response, or raises HttpError / HttpCancelled
+      def initialize(bundle:, cancel_lookup: -> {}, transport: nil)
+        @bundle = bundle.to_s
+        @cancel_lookup = cancel_lookup
+        @transport = transport
+      end
+
+      # @param url [String, URI] http or https
+      # @param headers [Hash] header name => value
+      # @param timeout [Numeric] seconds: open, and each read
+      # @param cancel [CancellationController, nil] overrides the default
+      #   (the turn's, for a call made for the turn)
+      # @return [Response] any status: a 4xx/5xx is returned, not raised
+      # @raise [ArgumentError] a bad URL, scheme, header or timeout
+      # @raise [HttpError] the request didn't complete
+      # @raise [HttpCancelled] it was cancelled
+      def get(url, headers: {}, timeout: DEFAULT_TIMEOUT, cancel: nil)
+        request("GET", url, headers: headers, timeout: timeout, cancel: cancel)
+      end
+
+      # POST +body+ encoded as JSON (Content-Type and Accept: application/json
+      # unless +headers+ name them).
+      # @param body [Object] anything JSON can encode
+      # @raise [ArgumentError] +body+ can't be encoded as JSON, and as #get
+      def post_json(url, body, headers: {}, timeout: DEFAULT_TIMEOUT, cancel: nil)
+        encoded = begin
+          JSON.generate(body)
+        rescue JSON::JSONError, EncodingError => e
+          raise ArgumentError, "can't encode the body as JSON: #{e.class}"
+        end
+        headers = { "Content-Type" => "application/json", "Accept" => "application/json" }
+                  .reject { |name, _| named?(headers, name) }.merge(headers)
+        request("POST", url, body: encoded, headers: headers, timeout: timeout, cancel: cancel)
+      end
+
+      # @param method [String, Symbol] GET POST PUT PATCH DELETE HEAD
+      # @param body [String, nil] sent as is (set your own Content-Type)
+      # @raise [ArgumentError] an unknown method, a body that isn't a String, and as #get
+      def request(method, url, body: nil, headers: {}, timeout: DEFAULT_TIMEOUT, cancel: nil)
+        verb = method.to_s.upcase
+        raise ArgumentError, "unknown HTTP method #{method.inspect} (#{METHODS.join(", ")})" unless METHODS.include?(verb)
+        raise ArgumentError, "the body must be a String (or nil), got #{body.class}" unless body.nil? || body.is_a?(String)
+
+        transport.call(method: verb, uri: parse_url(url), headers: header_hash(headers), body: body,
+                       timeout: timeout_seconds(timeout), cancel: cancel || @cancel_lookup.call)
+      end
+
+      private
+
+      def transport
+        @transport ||= begin
+          require_relative "http_transport"
+          NetTransport.new(bundle: @bundle)
+        end
+      end
+
+      def parse_url(url)
+        uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
+        unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+          raise ArgumentError, "the URL must be http:// or https:// with a host: #{quotable(url)}"
+        end
+
+        uri
+      rescue URI::InvalidURIError
+        raise ArgumentError, "not a URL: #{quotable(url)}"
+      end
+
+      # +url+ as an error message may quote it: its first 100 characters
+      # without the query, fragment and user info (a key in them would reach
+      # the logs with the message).
+      def quotable(url)
+        text = url.to_s.sub(/[?#].*\z/m, "").sub(%r{\A([a-z][a-z0-9+.-]*://)[^/@]*@}i, "\\1")
+        text[0, 100].inspect
+      end
+
+      def header_hash(headers)
+        raise ArgumentError, "headers must be a Hash" unless headers.is_a?(Hash)
+
+        headers.to_h do |name, value|
+          name = name.to_s
+          value = value.to_s
+          unless name.match?(/\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/) && !value.match?(/[\r\n\0]/)
+            raise ArgumentError, "bad header #{name[0, 40].inspect}: a name of token characters, a value on one line"
+          end
+
+          [name, value]
+        end
+      end
+
+      def named?(headers, name)
+        headers.keys.any? { |key| key.to_s.casecmp?(name) }
+      end
+
+      def timeout_seconds(timeout)
+        raise ArgumentError, "timeout must be a positive number of seconds" unless timeout.is_a?(Numeric) && timeout.positive?
+
+        timeout.to_f
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/http_transport.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "zlib"
+require_relative "http"
+require_relative "../llm/http"
+require_relative "../llm/errors"
+
+module Samagotchi
+  module Plugin
+    class Http
+      # Plugin::Http's wire: one LLM::HTTP request per call (chi's TLS,
+      # proxies, User-Agent, cancel by closing the socket, and one log line
+      # without query, headers or body), with chi's retries off. Every error
+      # but a cancel becomes an HttpError, so a plugin rescues one type.
+      #
+      # Loaded with the first real request (it pulls in net/http and the
+      # LLM layer). Stateless.
+      class NetTransport
+        # What went wrong, in words (a message never carries a response).
+        REASONS = {
+          Errno::ECONNREFUSED => "connection refused", Errno::ECONNRESET => "connection reset",
+          Errno::EHOSTUNREACH => "host unreachable", Errno::ENETUNREACH => "network unreachable",
+          Errno::ETIMEDOUT => "timed out", Errno::EPIPE => "connection closed",
+          Timeout::Error => "timed out", IO::TimeoutError => "timed out", EOFError => "connection closed",
+          SocketError => "can't resolve the host", OpenSSL::SSL::SSLError => "TLS error",
+          Net::HTTPBadResponse => "malformed response", Net::HTTPHeaderSyntaxError => "malformed response",
+          Net::ProtocolError => "protocol error", Zlib::Error => "bad compressed body"
+        }.freeze
+
+        def initialize(bundle:)
+          @bundle = bundle.to_s
+        end
+
+        # @return [Response]
+        # @raise [HttpError, HttpCancelled]
+        def call(method:, uri:, headers:, body:, timeout:, cancel:)
+          request = Net::HTTP.const_get(method.capitalize).new(uri, headers)
+          request.body = body if body
+          client = LLM::HTTP.new(label: "plugin:#{@bundle}", open_timeout: timeout, read_timeout: timeout,
+                                 retry_policy: LLM::HTTP::RetryPolicy.none)
+          response = client.fetch(uri, request, retries: false, check_status: false, write_timeout: timeout, cancel_controller: cancel,
+                                                log_fields: { purpose: "plugin", bundle: @bundle })
+          build_response(response)
+        rescue LLM::RequestCancelled
+          raise HttpCancelled, "#{method} #{where(uri)}: cancelled"
+        rescue HttpError
+          raise
+        rescue StandardError => e
+          raise HttpError, "#{method} #{where(uri)}: #{reason(e)}"
+        end
+
+        private
+
+        def build_response(response)
+          headers = {}
+          response.each_header { |name, value| headers[name.downcase] = text(value) }
+          Response.new(status: response.code.to_i, headers: headers.freeze, body: text(response.body))
+        end
+
+        # The bytes as UTF-8 when they are, else as they came.
+        def text(body)
+          text = body.to_s.dup
+          utf8 = text.dup.force_encoding(Encoding::UTF_8)
+          utf8.valid_encoding? ? utf8 : text.force_encoding(Encoding::BINARY)
+        end
+
+        def where(uri) = "#{uri.host}:#{uri.port}"
+
+        def reason(error)
+          REASONS.find { |klass, _| error.is_a?(klass) }&.last || "failed (#{error.class.name})"
+        end
+      end
+    end
+  end
+end