squishling 0.5.0 → 0.5.1

data/docs/verifying.md

@@ -27,8 +27,10 @@ Squishling.verify(Triage, Invoice)    # just these classes
 For each squished method (inherited ones too, with the subclass's settings) it checks:
 
 - **The output schema:** that it builds (and is strict), is valid JSON Schema, and produces a typed result, so a
-  property name that can't be a result member (`total=`) is reported. A method with no output schema or no purpose is reported, because its LLM path
-  would raise. The default `call` method is skipped when you don't implement or configure it.
+  property name that can't be a result member (`total=`), an object with `properties` but no `type: "object"`, or a
+  `$ref` that doesn't resolve within the schema (a remote URI is never fetched; a missing `$defs` entry) is reported.
+  A method with no output schema or no purpose is reported, because its LLM path would raise. The default `call`
+  method is skipped when you don't implement or configure it.
 - **What the layers resolve to:** the escalation, generation params and `squawk` that the method, its class and
   `Squishling.config` add up to.
 - **The harness:** that it is still registered (not removed or replaced since the class declared it), and that a

data/lib/squishling/adapter/error_body.rb

@@ -11,7 +11,8 @@ module Squishling
       # repeated.
       WORD = /\A[A-Za-z0-9][\w.]{0,39}\z/
       PATH = /\A[\w.\-\[\]]{1,64}\z/
-      private_constant :WORD, :PATH
+      CONTEXT_LENGTH_EXCEEDED = "context_length_exceeded"
+      private_constant :WORD, :PATH, :CONTEXT_LENGTH_EXCEEDED
 
       module_function
 
@@ -38,9 +39,15 @@ module Squishling
         nil
       end
 
+      # Whether the body's code or type is the structured "context_length_exceeded" (what OpenAI sends for a prompt too
+      # long for the model). Only that field is read, never the message.
+      def context_length?(body)
+        (error(body)&.values_at("code", "type") || []).include?(CONTEXT_LENGTH_EXCEEDED)
+      end
+
       def token(value, pattern)
         value = value.to_s if value.is_a?(Integer)
-        value if value.is_a?(String) && value.match?(pattern)
+        value if value.is_a?(String) && value.valid_encoding? && value.match?(pattern)
       end
     end
   end

data/lib/squishling/adapter.rb

@@ -69,6 +69,11 @@ module Squishling
       end
     end
 
+    # What an adapter puts on a Squishling error's #cause in place of a provider's own exception (see
+    # Base#sanitized_cause): the original's class name and HTTP status in its message, and its backtrace, but none of
+    # its message, response, or other state. Not a Squishling::Error: it is never raised, only carried.
+    class ProviderFailure < StandardError; end
+
     # The adapter contract. Subclass it, implement #complete, and raise Squishling's errors:
     #
     #   class MyAdapter < Squishling::Adapter::Base
@@ -78,15 +83,20 @@ module Squishling
     #     rescue MyClient::Unauthorized
     #       raise configuration_error(request, "MyClient rejected the credentials")
     #     rescue MyClient::Error => e
-    #       raise llm_error(request, "MyClient failed (#{e.class})")
+    #       raise llm_error(request, "MyClient failed (#{e.class})"), cause: sanitized_cause(e, status: e.status)
     #     end
     #   end
     #
     # ConfigurationError is for setup mistakes (bad credentials, an invalid request, an unknown model): it is never
     # retried or escalated. LLMError is for failures worth another attempt (rate limits, 5xx, timeouts, connection
-    # errors): the next attempt, or the last one's caller, sees it. Keep the provider's own message out of both: it can
-    # echo request content or part of a key. Any other exception propagates unwrapped. Adapters are called from worker
-    # threads when a harness takes samples, so they must not share unsynchronized state.
+    # errors, a prompt too long for the model): the next attempt, or the last one's caller, sees it. Keep the provider's
+    # own message out of both: it can echo request content or part of a key. The same goes for the exception it came
+    # from, which error trackers report as the error's #cause: pass `cause: sanitized_cause(e, status:)` rather than
+    # letting a raise inside a rescue set a provider exception that carries a response body. Any other exception
+    # propagates unwrapped.
+    # Which of the two a provider failure is, is the adapter's call (#http_failure maps HTTP statuses, and
+    # #context_length? is where an adapter recognizes an overlong prompt); what happens next is Squishling's.
+    # Adapters are called from worker threads when a harness takes samples, so they must not share unsynchronized state.
     class Base
       # One completion. Returns an Adapter::Response.
       def complete(_request)
@@ -126,10 +136,53 @@ module Squishling
         LLMError.new("#{request.label}: #{message}")
       end
 
-      # A RequestRejectedError for a request the provider rejected (a 400). via names how it failed (the error class,
-      # the HTTP status); body is the provider's error body (a JSON String, or a Hash with String keys), of which only
-      # the status and code tokens are repeated, never its message. http_status, when given, drops a code that only
-      # repeats it. The params are pointed at only when the provider named one of them.
+      # What to pass as `cause:` when raising a Squishling error for a provider's exception: a ProviderFailure naming
+      # the original's class and the HTTP status (when given), with the original's backtrace. A provider exception's
+      # message and response usually hold the provider's response body, which can echo request content, and error
+      # trackers (Sentry, say) report the whole cause chain. Built fresh, never a copy of the original, so none of
+      # its state (a Faraday response, say) comes along. Transport errors that carry no body can be passed as they are.
+      def sanitized_cause(error, status: nil)
+        ProviderFailure.new([error.class, ("HTTP #{status}" if status)].compact.join(", "))
+          .tap { |failure| failure.set_backtrace(error.backtrace) }
+      end
+
+      # Classifies a provider's HTTP failure, so adapters sort the same status the same way: 408, 413, 429, and 5xx are
+      # LLMErrors; 401, 402, 403, 404, and a redirect are ConfigurationErrors (credentials, billing, model or endpoint:
+      # nothing a retry fixes); every other 4xx is a RequestRejectedError, unless #context_length? says the input
+      # outgrew the model, which is an LLMError too (a bigger model may take it). via names how it failed (the error
+      # class, the HTTP status) and is all of the failure that is repeated, with a rejection's status and code tokens.
+      # body is the provider's error body, as for #rejected_request_error. A nil status (no HTTP response) or a
+      # success status (a reply that was unusable) is an LLMError.
+      def http_failure(request, status:, body:, via:)
+        case status
+        when nil, 100..299, 408, 413, 429, 500.. then llm_error(request, via)
+        when 401, 403 then configuration_error(request, "the provider refused the credentials (#{via})")
+        when 402 then configuration_error(request, "#{via}: the provider reports a billing or quota problem")
+        when 404 then configuration_error(request, "#{via}: check the model name and the endpoint")
+        when 300..399 then configuration_error(request, "#{via}: redirects aren't followed; check the endpoint")
+        else rejected_or_overlong(request, status:, body:, via:)
+        end
+      end
+
+      # Whether a rejected request (a 400, or another 4xx not otherwise classified) means the input was too long for the
+      # model, which makes it an LLMError rather than a RequestRejectedError. The adapter decides: only it knows how its
+      # provider says so. The default recognizes a 400 whose structured error code or type is "context_length_exceeded",
+      # never reading the message. Override it to recognize more (and call super); when an adapter can't tell, the
+      # failure stays a rejection. status and body are those given to #http_failure.
+      def context_length?(status:, body:)
+        status == 400 && ErrorBody.context_length?(body)
+      end
+
+      def rejected_or_overlong(request, status:, body:, via:)
+        return llm_error(request, via) if context_length?(status:, body:)
+
+        rejected_request_error(request, via:, body:, http_status: status)
+      end
+
+      # A RequestRejectedError for a request the provider rejected (a 400, or another 4xx). via names how it failed
+      # (the error class, the HTTP status); body is the provider's error body (a JSON String, or a Hash with String
+      # keys), of which only the status and code tokens are repeated, never its message. http_status, when given, drops
+      # a code that only repeats it. The params are pointed at only when the provider named one of them.
       def rejected_request_error(request, via:, body:, http_status: nil)
         found = ErrorBody.read(body, http_status:)
         tokens = found.values_at(:status, :code).compact
@@ -219,7 +272,7 @@ module Squishling
         return value if value.respond_to?(:complete)
 
         raise ConfigurationError, "#{where} adapter must be an adapter (responding to complete), one of " \
-                                  "#{type_list}, or a Hash with type:, got #{value.inspect}"
+                                  "#{type_list}, or a Hash with type:, got #{Appendices.describe(value)}"
       end
     end
 

data/lib/squishling/adapters/openai_compatible.rb

@@ -19,7 +19,8 @@ module Squishling
     #   end
     class OpenAICompatible < Adapter::Base
       Options = OpenAIOptions
-      private_constant :Options
+      Transport = OpenAITransport
+      private_constant :Options, :Transport
 
       DEFAULT_BASE_URL = "https://api.openai.com/v1"
       STRUCTURED_OUTPUT = %i[json_schema json_object none].freeze
@@ -30,10 +31,12 @@ module Squishling
       # 429, and 5xx. A timeout is retried even though the server may have processed the request.
       NETWORK_ERRORS = [Timeout::Error, SocketError, EOFError, IOError, SystemCallError, Net::ProtocolError,
                         Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, OpenSSL::OpenSSLError, Zlib::Error].freeze
+      DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024
       MAX_RETRY_DELAY = 30
-      # How servers without OpenAI's error code (vLLM, Ollama, llama.cpp, ...) say a prompt is too long. The message is
-      # only matched against this, never repeated.
-      CONTEXT_LENGTH_MESSAGE = /context (length|window|size)|too many tokens|prompt is too long|maximum .{0,20}tokens/i
+      # How servers without OpenAI's error code (vLLM, Ollama, llama.cpp, ...) say a prompt is too long. Deliberately
+      # narrow (no bare "maximum ... tokens", which a bad max_tokens value also says): a wording that isn't here is a
+      # rejected request, which is the safe side. The message is only matched against this, never repeated.
+      CONTEXT_LENGTH_MESSAGE = /context (length|window|size)|too many tokens|prompt is too long/i
       private_constant :STRUCTURED_OUTPUT, :TOKEN_PARAMS, :PORTABLE_PARAMS, :NETWORK_ERRORS, :MAX_RETRY_DELAY,
         :CONTEXT_LENGTH_MESSAGE
 
@@ -44,23 +47,30 @@ module Squishling
       # max_retries: how often a timeout, connection failure, HTTP 408, 429, or 5xx is retried here (honoring
       # Retry-After) before it surfaces as an LLMError. max_tokens_param: the body key for max_output_tokens
       # (:max_completion_tokens, or :max_tokens for older servers). structured_output: :json_schema, :json_object,
-      # or :none. Raises ConfigurationError for a bad option.
+      # or :none. allow_insecure_http: lets a credential (api_key, or a header such as Authorization or api-key) go
+      # over plain http to a host that isn't loopback; without it that is a ConfigurationError. max_response_bytes:
+      # the most a response (an error body too) may hold, 8 MiB by default. total_timeout: the most seconds one
+      # attempt may take (read_timeout restarts at every read); it defaults to open_timeout + 2 * read_timeout.
+      # Responses are requested and accepted uncompressed only. Raises ConfigurationError for a bad option.
       def initialize(base_url: DEFAULT_BASE_URL, api_key: nil, headers: {}, default_model: nil, open_timeout: 10,
-        read_timeout: 120, max_retries: 2, max_tokens_param: :max_completion_tokens, structured_output: :json_schema)
+        read_timeout: 120, max_retries: 2, max_tokens_param: :max_completion_tokens, structured_output: :json_schema,
+        allow_insecure_http: false, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES, total_timeout: nil)
         super()
         @endpoint = Options.endpoint(base_url)
-        @api_key = api_key
-        @headers = Options.headers(headers)
+        @api_key = (Secret.new(api_key) unless api_key.nil?)
+        @headers = Secret.new(Options.headers(headers))
+        @allow_insecure_http = Options.flag(:allow_insecure_http, allow_insecure_http)
         @default_model = Options.default_model(default_model)
-        @open_timeout = Options.number(:open_timeout, open_timeout)
-        @read_timeout = Options.number(:read_timeout, read_timeout)
         @max_retries = Options.retries(max_retries)
         @max_tokens_param = Options.choice(:max_tokens_param, max_tokens_param, TOKEN_PARAMS)
         @structured_output = Options.choice(:structured_output, structured_output, STRUCTURED_OUTPUT)
+        @transport = build_transport(open_timeout, read_timeout, total_timeout, max_response_bytes)
+        check_cleartext!(api_key.respond_to?(:call) ? nil : api_key)
       end
 
       # Shows where requests go, never the key or the header values (a console, a log line, or an error tracker may
-      # print the config).
+      # print the config). The key and headers are held in a Secret, so to_yaml, as_json and Marshal can't expose them
+      # either.
       def inspect
         "#<#{self.class.name} #{@endpoint.scheme}://#{@endpoint.authority}#{@endpoint.path} " \
           "default_model=#{@default_model.inspect} structured_output=#{@structured_output.inspect}>"
@@ -143,46 +153,64 @@ module Squishling
         loop do
           attempt += 1
           response, error = exchange(body, headers)
-          return parse_body(request, response) if response.is_a?(Net::HTTPSuccess)
+          return parse_body(request, response) if response&.success?
 
           failure = failure_for(request, response, error)
           raise failure, cause: error unless retryable?(response, error) && attempt <= @max_retries
 
           pause(retry_delay(response, attempt))
         end
+      rescue Transport::Refused => e
+        # A size or time limit, or compression: the same request would hit it again, so it isn't retried.
+        raise llm_error(request, e.message), cause: e
       end
 
       def exchange(body, headers)
-        [http_post(body, headers), nil]
+        [@transport.post(body, headers), nil]
       rescue *NETWORK_ERRORS => e
         [nil, e]
       end
 
-      # Redirects aren't followed: the next hop could be another host, and the Authorization header would go with it.
-      def http_post(body, headers)
-        http = Net::HTTP.new(@endpoint.hostname, @endpoint.port)
-        http.use_ssl = @endpoint.scheme == "https"
-        http.open_timeout = @open_timeout
-        http.read_timeout = @read_timeout
-        http.write_timeout = @read_timeout
-        post = Net::HTTP::Post.new(@endpoint.request_uri, headers)
-        post.body = body
-        http.request(post)
+      def build_transport(open_timeout, read_timeout, total_timeout, max_response_bytes)
+        open_timeout = Options.number(:open_timeout, open_timeout)
+        read_timeout = Options.number(:read_timeout, read_timeout)
+        Transport.new(endpoint: @endpoint, open_timeout:, read_timeout:,
+          total_timeout: Options.total_timeout(total_timeout, open_timeout, read_timeout),
+          max_response_bytes: Options.number(:max_response_bytes, max_response_bytes, type: Integer))
       end
 
       # Built once per call, before any request and outside the network-error rescue, so the developer's own api_key
       # callable runs once and its exceptions propagate as they are.
       def request_headers(request)
-        key = (@api_key.respond_to?(:call) ? @api_key.call : (@api_key || default_api_key)).to_s.strip
+        key = api_key_value.to_s.strip
         if Options.unsafe_header?(key)
           raise configuration_error(request,
             "the api_key can't contain line breaks or NUL")
         end
+        check_cleartext!(key, request)
 
         headers = { "Content-Type" => "application/json", "Accept" => "application/json",
                     "User-Agent" => "squishling/#{VERSION}" }
         headers["Authorization"] = "Bearer #{key}" unless key.empty?
-        headers.merge(@headers)
+        # Accept-Encoding is Squishling's own: a compressed response would be inflated past the size cap.
+        headers.merge(@headers.reveal).reject { |name, _| name.casecmp?("accept-encoding") }
+          .merge("Accept-Encoding" => "identity")
+      end
+
+      def api_key_value
+        key = @api_key&.reveal
+        key.respond_to?(:call) ? key.call : (key || default_api_key)
+      end
+
+      # A credential doesn't go over plain http to another machine unless allow_insecure_http: says so. Checked when the
+      # adapter is built for a key given as a String, and again with each request's own key (a callable's). Reads the
+      # headers through their Secret; the message names neither the key nor a header value.
+      def check_cleartext!(key, request = nil)
+        return if @allow_insecure_http || !Options.cleartext_credential?(@endpoint, key, @headers.reveal)
+
+        raise configuration_error(request, Options::CLEARTEXT_CREDENTIAL) if request
+
+        raise ConfigurationError, Options::CLEARTEXT_CREDENTIAL
       end
 
       def default_api_key
@@ -213,9 +241,7 @@ module Squishling
         return transport_failure(request, error) if error
 
         status = response.code.to_i
-        return llm_error(request, "HTTP #{status}") if retryable?(response, nil) || too_large?(response, status)
-
-        rejection(request, response, status)
+        http_failure(request, status:, body: response.body.to_s, via: "HTTP #{status}")
       end
 
       # A certificate that doesn't verify is a setup mistake (base_url, CA store) that a retry can't fix.
@@ -232,32 +258,13 @@ module Squishling
         error.is_a?(OpenSSL::SSL::SSLError) && error.message.include?("certificate verify failed")
       end
 
-      def rejection(request, response, status)
-        case status
-        when 401, 403 then configuration_error(request, "the provider refused the credentials (HTTP #{status})")
-        when 404 then configuration_error(request, "HTTP 404: check base_url and the model name")
-        when 300..399 then configuration_error(request, "HTTP #{status}: redirects aren't followed; check base_url")
-        else rejected_request_error(request, via: "HTTP #{status}", body: response.body.to_s,
-          http_status: status)
-        end
-      end
-
-      # A request too long for the model's context (or for the server: 413) depends on the input and is worth another
-      # attempt (a bigger model may take it), unlike other 4xx. Only the error's code is read from the body.
-      def too_large?(response, status)
-        status == 413 || context_length?(response)
-      end
-
-      def context_length?(response)
-        return false unless response.code.to_i == 400
-
-        error = Adapter::ErrorBody.error(response.body.to_s)
-        error.is_a?(Hash) && (error.values_at("code", "type").include?("context_length_exceeded") ||
-          error["message"].to_s.match?(CONTEXT_LENGTH_MESSAGE))
+      # The structured code or type, as for any adapter, or the usual wording of a server that sends none (a 400).
+      def context_length?(status:, body:)
+        super || (status == 400 && Adapter::ErrorBody.error(body)&.[]("message").to_s.scrub.match?(CONTEXT_LENGTH_MESSAGE))
       end
 
       def retry_delay(response, attempt)
-        after = response&.[]("retry-after").to_s
+        after = response&.retry_after.to_s
         seconds = after.match?(/\A\d+\z/) ? after.to_i : (0.5 * (2**(attempt - 1))) + (rand * 0.25)
         [seconds, MAX_RETRY_DELAY].min
       end

data/lib/squishling/adapters/openai_options.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "ipaddr"
 require "uri"
 
 module Squishling
@@ -10,6 +11,12 @@ module Squishling
       # The URL itself is never in the message: it may carry credentials.
       INVALID_BASE_URL = "adapter :openai_compatible base_url must be an http(s) URL without credentials (use " \
                          "api_key:), a query, or a fragment"
+      # Headers that carry a secret as a matter of course (OpenAI-style, Azure OpenAI and API Management, Google, and
+      # proxies), by name: an API or subscription key, a token, auth, a secret, a credential, or a cookie.
+      CREDENTIAL_HEADER = /(api|subscription)[-_]?key|token|auth|secret|credential|cookie/i
+      CLEARTEXT_CREDENTIAL = "adapter :openai_compatible won't send credentials (the api_key or a header such as " \
+                             "Authorization or api-key) over plain http to a host that isn't this machine; use " \
+                             "https, or pass allow_insecure_http: true to accept the risk on a network you trust"
       INVALID_HEADER = "adapter :openai_compatible headers (and the api_key) can't contain line breaks or NUL"
 
       module_function
@@ -40,6 +47,40 @@ module Squishling
         text.match?(/[\r\n\0]/)
       end
 
+      # Whether a credential would travel in the clear: over http, to a host that isn't loopback (a name is judged by
+      # its spelling, never resolved, so a lookup can't change the answer).
+      def cleartext?(endpoint)
+        endpoint.scheme == "http" && !loopback?(endpoint.hostname)
+      end
+
+      def loopback?(host)
+        host = host.downcase.delete_suffix(".")
+        host == "localhost" || host.end_with?(".localhost") || IPAddr.new(host).loopback?
+      rescue IPAddr::Error
+        false
+      end
+
+      # Whether a request to endpoint, with this key (a String, possibly blank) and these headers, would send a
+      # credential in the clear.
+      def cleartext_credential?(endpoint, key, headers)
+        return false unless cleartext?(endpoint)
+
+        !key.to_s.strip.empty? || headers.each_key.any? { |name| name.match?(CREDENTIAL_HEADER) }
+      end
+
+      def flag(name, value)
+        return value if [true, false].include?(value)
+
+        raise ConfigurationError, "adapter :openai_compatible #{name} must be true or false, got #{value.inspect}"
+      end
+
+      # Defaults to the time the three timeouts allow together: connecting, writing the request, one read.
+      def total_timeout(value, open_timeout, read_timeout)
+        return open_timeout + (2 * read_timeout) if value.nil?
+
+        number(:total_timeout, value)
+      end
+
       def default_model(model)
         return nil if model.nil?
         return model.to_s if (model.is_a?(String) || model.is_a?(Symbol)) && !model.to_s.strip.empty?
@@ -47,10 +88,11 @@ module Squishling
         raise ConfigurationError, "adapter :openai_compatible default_model must be a model name, got #{model.inspect}"
       end
 
-      def number(name, value)
-        return value if value.is_a?(Numeric) && value.positive?
+      def number(name, value, type: Numeric)
+        return value if value.is_a?(type) && value.positive?
 
-        raise ConfigurationError, "adapter :openai_compatible #{name} must be a positive number, got #{value.inspect}"
+        kind = type == Integer ? "Integer" : "number"
+        raise ConfigurationError, "adapter :openai_compatible #{name} must be a positive #{kind}, got #{value.inspect}"
       end
 
       def retries(value)

data/lib/squishling/adapters/openai_transport.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "timeout"
+
+module Squishling
+  module Adapters
+    # The HTTP exchange of Adapters::OpenAICompatible, kept apart so the limits sit in one place: one POST whose
+    # response is read in chunks, with a cap on its size (the declared length, then the bytes actually received, for an
+    # error body too) and on the total time it may take, which read_timeout alone doesn't bound (it restarts at every
+    # read, so a slow drip of headers or body can hold a worker thread for as long as the server likes). Compression
+    # is refused, not inflated: the request asks for an identity encoding, and a response that comes back encoded
+    # anyway is dropped, so a small body can't expand past the cap. Redirects aren't followed: the next hop could be
+    # another host, and the Authorization header would go with it. A limit that is hit raises a Refused, whose
+    # message names the limit and never carries the URL, a header, or any of the response.
+    class OpenAITransport
+      class Refused < StandardError; end
+      class ResponseTooLarge < Refused; end
+      class DeadlineExceeded < Refused; end
+      class UnexpectedEncoding < Refused; end
+
+      # What is left of a response once it has been read: its status (a String, as Net::HTTPResponse has it), whole
+      # body, and Retry-After header.
+      Reply = Struct.new(:code, :body, :retry_after) do
+        def success?
+          code.start_with?("2")
+        end
+      end
+
+      MONOTONIC = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      private_constant :MONOTONIC
+
+      def initialize(endpoint:, open_timeout:, read_timeout:, total_timeout:, max_response_bytes:, clock: MONOTONIC)
+        @endpoint = endpoint
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @total_timeout = total_timeout
+        @max_response_bytes = max_response_bytes
+        @clock = clock
+      end
+
+      # total_timeout and the byte cap apply per call, so each retry gets its own.
+      def post(body, headers)
+        deadline = @clock.call + @total_timeout
+        perform(body, headers, deadline)
+      rescue DeadlineExceeded
+        # Net::HTTP re-raises what interrupts a connect with the host and port in the message; ours is built afresh.
+        expired!
+      rescue Timeout::Error
+        expired! if @clock.call >= deadline
+
+        raise
+      end
+
+      private
+
+      # Net::HTTP reads the status line and headers before it yields the response, with read_timeout restarting at every
+      # byte, so the deadline can't be checked there: a Timeout cuts the whole exchange off at total_timeout instead.
+      # The connection is dropped whichever way the block ends, so nothing is left half-used. The deadline is checked
+      # again at each chunk, which also stops a body that arrives in time but whose clock says otherwise.
+      def perform(body, headers, deadline)
+        request = Net::HTTP::Post.new(@endpoint.request_uri, headers)
+        request.body = body
+        http = connection
+        Timeout.timeout(@total_timeout, DeadlineExceeded, expired_message) do
+          http.start { http.request(request) { |response| return read(response, deadline) } }
+        end
+      end
+
+      def connection
+        Net::HTTP.new(@endpoint.hostname, @endpoint.port).tap do |http|
+          http.use_ssl = @endpoint.scheme == "https"
+          http.open_timeout = @open_timeout
+          http.read_timeout = http.write_timeout = @read_timeout
+        end
+      end
+
+      def read(response, deadline)
+        Reply.new(response.code, body_of(response, deadline), response["retry-after"])
+      end
+
+      # The whole body, within the limits. On a failure status a body that is compressed or over the cap is dropped
+      # rather than refused: the status alone says what kind of failure it is (a proxy's gzipped 401 is still a
+      # credentials problem, not a transport one), and nothing in the body is read for it anyway.
+      def body_of(response, deadline)
+        check_headers(response)
+        body = String.new(encoding: Encoding::BINARY)
+        response.read_body do |chunk|
+          expired! unless @clock.call < deadline
+          too_large! if body.bytesize + chunk.bytesize > @max_response_bytes
+          body << chunk
+        end
+        body
+      rescue ResponseTooLarge, UnexpectedEncoding
+        raise if response.code.start_with?("2")
+
+        String.new(encoding: Encoding::BINARY)
+      end
+
+      def check_headers(response)
+        encoding = response["content-encoding"].to_s.strip.downcase
+        unless encoding.empty? || encoding == "identity"
+          raise UnexpectedEncoding, "the response was compressed although the request asked for none"
+        end
+
+        length = response["content-length"].to_s.strip
+        too_large! if length.match?(/\A\d+\z/) && length.to_i > @max_response_bytes
+      end
+
+      def too_large!
+        raise ResponseTooLarge, "the response was larger than max_response_bytes (#{@max_response_bytes})"
+      end
+
+      def expired!
+        raise DeadlineExceeded, expired_message, cause: nil
+      end
+
+      def expired_message
+        "the request ran past total_timeout (#{@total_timeout}s)"
+      end
+    end
+  end
+end

data/lib/squishling/adapters/ruby_llm.rb

@@ -12,9 +12,16 @@ module Squishling
       # The ruby_llm gem isn't installed (Adapter.detect tells that apart from a gem that is, but too old).
       class MissingGemError < ConfigurationError; end
 
-      # Raises ConfigurationError when the ruby_llm gem is missing.
-      def initialize
-        super
+      # Raises ConfigurationError when the ruby_llm gem is missing. keep_cause: true keeps RubyLLM's original exception
+      # as the #cause of the errors raised for a failed request (its message and response hold the provider's response
+      # body); by default #cause is a sanitized stand-in (Adapter::ProviderFailure) with only the class and HTTP status.
+      def initialize(keep_cause: false)
+        super()
+        unless [true, false].include?(keep_cause)
+          raise ConfigurationError, "adapter :ruby_llm keep_cause: must be true or false, got #{keep_cause.inspect}"
+        end
+
+        @keep_cause = keep_cause
         require "ruby_llm"
         check_version!
         @lib = gem_lib_dir
@@ -123,31 +130,60 @@ module Squishling
       end
 
       # Transient HTTP failures are already retried by RubyLLM; anything that still fails is surfaced as an
-      # LLMError, which moves on to the next attempt of the escalation (or propagates from the last one). A 400
-      # means the request we built is invalid (an unsupported param, a schema the provider rejects), so it's a
-      # setup mistake: escalating or a fallback would otherwise hide it on every call.
+      # LLMError, which moves on to the next attempt of the escalation (or propagates from the last one), or as a
+      # ConfigurationError for a setup mistake (see #http_failure for which statuses are which): escalating or a
+      # fallback would otherwise hide it on every call.
       # A provider's or transport's own message never goes into ours: a provider can echo request content or part of
-      # an API key in it, and ours reach logs and error trackers. The original stays as #cause for whoever
-      # chooses to read it. RubyLLM's own ConfigurationError is local (it names a missing setting), so it is kept.
+      # an API key in it, and ours reach logs and error trackers.
+      # Error trackers report the whole cause chain, and RubyLLM's error message and response hold the provider's
+      # response body, so #cause is a sanitized stand-in (class, HTTP status, backtrace); the original is there only
+      # with keep_cause: true. RubyLLM's own ConfigurationError, and the errors #build_chat, #apply_params, and #judge
+      # convert, are local (they name a missing setting or a bad param and hold no provider response), so they are
+      # raised as they are and Ruby sets the original as their #cause.
       def guarded(request)
         yield
       rescue ::RubyLLM::ConfigurationError => e
         raise configuration_error(request, "#{e.class}: #{e.message}")
-      rescue ::RubyLLM::UnauthorizedError, ::RubyLLM::ForbiddenError => e
-        raise configuration_error(request, describe_failure(e))
-      rescue ::RubyLLM::BadRequestError => e
-        raise rejected_request_error(request, via: describe_failure(e), body: response_field(e.response, :body),
-          http_status: response_field(e.response, :status))
       rescue ::RubyLLM::Error, Faraday::Error => e
-        raise llm_error(request, describe_failure(e))
+        raise failure_for(request, e), cause: cause_of(e)
+      end
+
+      # Sorted by the HTTP status, not by RubyLLM's error class: RubyLLM's middleware picks a class from the provider's
+      # message text on a 400, so a bad parameter whose message happens to say "per day" arrives as a RateLimitError.
+      # An error with no response is sorted by its class. The one class honored over the status is RubyLLM's
+      # ContextLengthExceededError, since RubyLLM is where its provider's wording for an overlong prompt is known.
+      def failure_for(request, error)
+        via = describe_failure(error)
+        return llm_error(request, via) if error.is_a?(::RubyLLM::ContextLengthExceededError)
+
+        status = response_field(error.response, :status) || class_status(error)
+        http_failure(request, status:, body: response_field(error.response, :body), via:)
+      end
+
+      # The status RubyLLM's classes stand for, for an error raised without a response.
+      def class_status(error)
+        case error
+        when ::RubyLLM::UnauthorizedError then 401
+        when ::RubyLLM::PaymentRequiredError then 402
+        when ::RubyLLM::ForbiddenError then 403
+        when ::RubyLLM::BadRequestError then 400
+        end
       end
 
       # The error's class and HTTP status, when it has one, which is all of it that is ours to repeat.
       def describe_failure(error)
-        status = response_field(error.response, :status)
+        status = status_of(error)
         status ? "#{error.class}, HTTP #{status}" : error.class.to_s
       end
 
+      def status_of(error)
+        response_field(error.response, :status)
+      end
+
+      def cause_of(error)
+        @keep_cause ? error : sanitized_cause(error, status: status_of(error))
+      end
+
       # A field of an error's response, which is a Faraday::Response, or a Hash for a Faraday error.
       def response_field(response, field)
         response.is_a?(Hash) ? response[field] : (response.public_send(field) if response.respond_to?(field))

data/lib/squishling/class_methods.rb

@@ -22,8 +22,8 @@ module Squishling
     # max_total_output_tokens:/max_total_input_tokens: cap the tokens one call may use across all its requests
     # (see Budget); false lifts a cap inherited from the parent class or the configuration:
     #   squishling max_total_output_tokens: 25_000
-    # squawk: is called after each LLM attempt (narrowed by squawk_on:) with the raw output (see
-    # Configuration#squawk); false silences
+    # squawk: is called after each LLM attempt (narrowed by squawk_on:), and once more when a token budget or a
+    # disagreement stops the call, with the raw output (see Configuration#squawk); false silences
     # an inherited one:
     #   squishling squawk: ->(output:, metadata:, error:) { Tracer.record(output, metadata, error) }
     # squawk_on: limits which attempts reach the hook: :all (the default), :rejections, :retries, :final, or a