squishling 0.3.0 → 0.5.0

data/lib/squishling/llm_client.rb

@@ -1,25 +1,41 @@
 # frozen_string_literal: true
 
 module Squishling
-  # RubyLLM requests for one squished method, with RubyLLM's errors mapped onto Squishling's taxonomy.
+  # The requests for one squished method, made through the configured adapter (see Adapter). Squishling owns the
+  # conversation: each Conversation holds the system prompt, the output schema, and the messages so far, and every
+  # request sends all of it to the adapter.
   class LLMClient
-    # Where RubyLLM's own code lives, to tell its ArgumentErrors from the developer's (see #judge).
-    RUBY_LLM_LIB = File.dirname(RubyLLM.method(:judge).source_location.first)
-    private_constant :RUBY_LLM_LIB
+    # One chat on one escalation step. messages are { role:, content: } Hashes, grown by #ask.
+    Conversation = Struct.new(:step, :instructions, :schema, :messages)
+
+    # purpose, harness (the harness type), and handed_off (squish! sent the call here) are only told to the observer.
+    # budget (see Budget) caps the tokens the requests of this client may use between them.
+    def initialize(label, purpose:, harness:, handed_off:, budget: {})
+      @label = label
+      @purpose = purpose
+      @harness = harness
+      @handed_off = handed_off
+      @adapter = Squishling.config.resolved_adapter
+      @tally = Budget::Tally.new(budget)
+    end
+
+    # The budget limit this client's requests have reached ({ limit:, max:, used: }), or nil. Checked before each
+    # request, so one already in flight is never cut short.
+    def exhausted_budget
+      @tally.exhausted
+    end
 
     # Runs each job on its own thread and returns, in order, each job's [value, exception]. Only provider
     # requests run here: parsing, validation, and the developer's callbacks stay on the caller's thread. Fiber
-    # storage (RubyLLM's usage owner) is inherited by the threads, and RubyLLM's instrumentation context is
-    # carried over the way RubyLLM's own concurrent tool calls do it. Unlike those, the threads don't enter the
-    # Rails executor: the caller already holds it, and a second share can deadlock against a pending code reload.
-    # If the caller is interrupted while waiting (a timeout, Thread#raise), the requests still running are
-    # stopped rather than left running unobserved.
-    def self.concurrently(jobs)
+    # storage is inherited by the threads, and the adapter carries over whatever request context it keeps (see
+    # Adapter::Base#capture_context). If the caller is interrupted while waiting (a timeout, Thread#raise), the
+    # requests still running are stopped rather than left running unobserved.
+    def concurrently(jobs)
       return jobs.map { |job| capture(job) } if jobs.size < 2
 
-      context = instrumentation_context
+      context = @adapter.capture_context if @adapter.respond_to?(:capture_context)
       threads = jobs.map do |job|
-        thread = Thread.new { with_instrumentation_context(context) { capture(job) } }
+        thread = Thread.new { with_context(context) { capture(job) } }
         thread.report_on_exception = false
         thread
       end
@@ -28,123 +44,71 @@ module Squishling
       threads&.each { |thread| thread.kill.join if thread.alive? }
     end
 
-    def self.capture(job)
-      [job.call, nil]
-    rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised on the caller's thread
-      [nil, e]
-    end
-
-    def self.instrumentation_context
-      instrumentation = defined?(RubyLLM::Support::Instrumentation) && RubyLLM::Support::Instrumentation
-      return unless instrumentation.respond_to?(:current_workflow) && instrumentation.respond_to?(:capture_context)
-
-      [instrumentation.current_workflow, instrumentation.capture_context]
-    end
-
-    def self.with_instrumentation_context(context, &)
-      return yield unless context
-
-      instrumentation = RubyLLM::Support::Instrumentation
-      instrumentation.with_workflow(context.first) { instrumentation.with_context(context.last, &) }
+    # A fresh conversation on one escalation step, with the system prompt and the strict output schema.
+    def chat(step, instructions:, schema:)
+      Conversation.new(step, instructions, schema, [])
     end
 
-    private_class_method :capture, :instrumentation_context, :with_instrumentation_context
-
-    def initialize(label)
-      @label = label
+    # One request in the conversation: the message goes in, and the adapter's answer is kept in it so the next
+    # message continues from there. A request that fails leaves the conversation as it was.
+    # The adapter raises ConfigurationError for setup mistakes (never retried) and LLMError for failures worth another
+    # attempt, which moves on to the next attempt of the escalation (or propagates from the last one).
+    # The request runs inside the configured observer (see Observer), on this thread: for samples, the worker's.
+    # role is nil for an escalation attempt, :sample (with its name) or :judge; attempt counts in attempts.
+    # reask is whether this message is a retry in the same chat (see ModelPath::Step#request_params).
+    def ask(chat, message, step, attempt:, attempts:, role: nil, sample: nil, reask: false)
+      call = call_info(step, :chat, role:, sample:, attempt:, attempts:)
+      Observer.around(call) { complete(chat, message, step, reask) }
     end
 
-    # A fresh chat on one escalation step, with the system prompt, the strict output schema, and its params.
-    def chat(step, instructions:, schema:)
-      chat = build_chat(step)
-      chat.with_instructions(instructions)
-      chat.with_schema(schema)
-      apply_params(chat, step.params)
-      chat
+    # Whether the adapter can make System One judgments (judges with type: :judgment).
+    def judgments?
+      @adapter.respond_to?(:judgments?) && @adapter.respond_to?(:judge) && @adapter.judgments?
     end
 
-    # Transient HTTP failures are already retried by RubyLLM (RubyLLM.config.max_retries); 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.
-    def ask(chat, message, step)
-      request(step) { chat.ask(message) }
+    # A System One judgment on one step, through the adapter.
+    # Judge#check_judgments! has already refused an adapter that can't.
+    def judge(input, questions:, step:)
+      @tally.add(@adapter.judge(input, questions:, step:, label: @label))
     end
 
-    # A System One judgment (RubyLLM.judge) on one step. The step's params are sent as provider options.
-    # RubyLLM raises ArgumentError for a judgment it can't build (e.g. a model on a provider that takes none, or
-    # a provider option its protocol reserves), and a bare RubyLLM::Error without an HTTP response for a provider
-    # that doesn't support judgments at all. An ArgumentError from anywhere else (an instrumentation subscriber
-    # runs inside the call) is the developer's own and propagates as-is.
-    def judge(input, questions:, step:)
-      request(step) do
-        RubyLLM.judge(input, questions:, provider_options: step.params, **model_options(step))
-      rescue RubyLLM::ModelNotFoundError => e
-        raise ConfigurationError, "#{@label}: #{e.message}"
-      rescue ArgumentError => e
-        raise unless raised_by_ruby_llm?(e)
-
-        raise ConfigurationError, "#{@label}: #{e.message}"
-      rescue RubyLLM::Error => e
-        raise unless e.instance_of?(RubyLLM::Error) && e.response.nil?
-
-        raise ConfigurationError, "#{@label}: #{e.message}"
-      end
+    # #judge inside the configured observer (see Observer), attempt counting in attempts.
+    def observed_judgment(input, questions:, step:, attempt:, attempts:)
+      call = call_info(step, :judgment, role: :judge, attempt:, attempts:)
+      Observer.around(call) { judge(input, questions:, step:) }
     end
 
     private
 
-    def raised_by_ruby_llm?(error)
-      error.backtrace&.first&.start_with?("#{RUBY_LLM_LIB}/") || false
-    end
-
-    def build_chat(step)
-      RubyLLM.chat(**model_options(step))
-    rescue RubyLLM::ModelNotFoundError, RubyLLM::ConfigurationError => e
-      raise ConfigurationError, "#{@label}: #{e.message}"
+    def capture(job)
+      [job.call, nil]
+    rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised on the caller's thread
+      [nil, e]
     end
 
-    # RubyLLM validates some settings locally (e.g. an impossible thinking budget for the model)
-    # and raises ArgumentError before any request is sent.
-    def apply_params(chat, params)
-      Params.apply(chat, params)
-    rescue ArgumentError => e
-      raise ConfigurationError, "#{@label}: invalid params #{params.inspect} (#{e.message})"
-    end
+    def complete(chat, message, step, reask)
+      messages = chat.messages + [{ role: :user, content: message }]
+      request = Adapter::Request.new(label: @label, model: step.model, provider: step.provider,
+        instructions: chat.instructions, messages:, schema: chat.schema, params: step.request_params(reask))
+      response = @adapter.complete(request)
+      unless response.is_a?(Adapter::Response)
+        raise ConfigurationError, "#{@label}: the #{@adapter.class} adapter must return a " \
+                                  "Squishling::Adapter::Response from #complete, got #{response.class}"
+      end
 
-    def request(step)
-      yield
-    rescue RubyLLM::ConfigurationError, RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError => e
-      raise ConfigurationError, "#{@label}: #{e.class}: #{e.message}"
-    rescue RubyLLM::BadRequestError => e
-      raise ConfigurationError,
-        "#{@label}: the provider rejected the request (#{e.message})#{params_hint(step.params)}"
-    rescue RubyLLM::Error, Faraday::Error => e
-      raise LLMError, "#{@label}: #{e.class}: #{e.message}"
+      chat.messages = messages + [{ role: :assistant, content: response.text }]
+      @tally.add(response)
     end
 
-    # Models missing from RubyLLM's registry (e.g. newly released ones) are only usable when a
-    # provider is named, so RubyLLM is told to assume they exist.
-    def model_options(step)
-      model = step.model
-      provider = step.provider
-      options = { model:, provider: }.compact
-      options[:assume_model_exists] = true if model && provider && !known_model?(model, provider)
-      options
-    end
+    def with_context(context, &)
+      return yield unless @adapter.respond_to?(:with_context)
 
-    def known_model?(model, provider)
-      RubyLLM.models.find(model, provider:)
-      true
-    rescue RubyLLM::ModelNotFoundError
-      false
+      @adapter.with_context(context, &)
     end
 
-    def params_hint(params)
-      return "" if params.empty?
-
-      ". Check params #{params.inspect}; reasoning models often reject sampling params such as temperature and top_p"
+    def call_info(step, request, attempt:, attempts:, role: nil, sample: nil)
+      Observer::Call.new(label: @label, purpose: @purpose, harness: @harness, handed_off: @handed_off, role:, sample:,
+        attempt:, attempts:, model: step.model, provider: step.provider, request:)
     end
   end
 end

data/lib/squishling/model_path.rb

@@ -8,20 +8,35 @@ module Squishling
   #     "claude-sonnet-5-5",
   #     { model: "claude-opus-5-5", params: { thinking: { effort: :high } } }
   #   ]
-  # attempts: (default 1) retries a step; order: (all steps or none, unique, lowest first) makes the order
-  # explicit instead of positional. forward_rejected: false starts a step from the original input alone, without
-  # the previous step's rejected output.
+  # attempts: (default 1) retries a step; priority: (all steps or none, lowest first) makes the order explicit
+  # instead of positional. Steps sharing a priority are one tier: each call rotates which of them goes first
+  # (see Rotation), and the others follow before the next tier, unless a step in the tier sets rotate: false.
+  # order: is the deprecated name of priority:. forward_rejected: false starts a step from the original input
+  # alone, without the previous step's rejected output. include_when: (a Proc, called like squish_when with the
+  # method's inputs as keywords, on the instance) drops the step from any call where it is falsy.
+  # retry_temperature: (a Numeric) is the temperature for the step's same-chat retries after the first attempt.
   module ModelPath
-    # One attempt: the model, its provider, the fully resolved generation params, and whether the previous
-    # step's rejected output is shown to it.
-    Step = Data.define(:model, :provider, :params, :forward_rejected) do
-      # The model for logs and messages (nil means RubyLLM's default model).
+    # One attempt: the model, its provider, the fully resolved generation params, whether the previous
+    # step's rejected output is shown to it, and the temperature its retries in the same chat use, if any.
+    Step = Data.define(:model, :provider, :params, :forward_rejected, :retry_temperature) do
+      def initialize(model:, provider:, params:, forward_rejected:, retry_temperature: nil)
+        super
+      end
+
+      # The params for a request: on a retry in the same chat (reask), the step's retry_temperature replaces the
+      # temperature, if it sets one.
+      def request_params(reask)
+        reask && retry_temperature ? Params.resolve(params, temperature: retry_temperature) : params
+      end
+
+      # The model for logs and messages (nil means the adapter's default model).
       def display_name
-        model || "RubyLLM default model"
+        model || "the adapter's default model"
       end
     end
 
-    STEP_KEYS = %i[model provider params attempts order forward_rejected].freeze
+    STEP_KEYS = %i[model provider params attempts priority order rotate forward_rejected include_when
+                   retry_temperature].freeze
 
     module_function
 
@@ -57,43 +72,75 @@ module Squishling
     end
 
     # One Step per attempt. The level's provider applies to steps that don't name their own, and each
-    # step's params are merged over the level-resolved params.
-    def steps(path, provider:, params:)
-      path.flat_map do |step|
+    # step's params are merged over the level-resolved params. turn is this call's place in the method's rotation
+    # (see Rotation): each tier of tied priorities starts turn steps further along.
+    def steps(path, provider:, params:, turn: 0)
+      rotated(path, turn).flat_map do |step|
         attempt = Step.new(model: step[:model], provider: step[:provider] || provider,
-          params: Params.resolve(params, step[:params]), forward_rejected: step[:forward_rejected])
+          params: Params.resolve(params, step[:params]), forward_rejected: step[:forward_rejected],
+          retry_temperature: step[:retry_temperature])
         [attempt] * step[:attempts]
       end
     end
 
+    # The steps this call may use: those without an include_when:, and those whose include_when: is truthy for the
+    # call's inputs (evaluated against the receiver, like squish_when). Priority order is kept.
+    def eligible(path, receiver, inputs, label)
+      kept = path.select do |step|
+        gate = step[:include_when]
+        gate.nil? || receiver.instance_exec(**inputs, &gate)
+      end
+      raise ConfigurationError, "#{label}: include_when: excluded every escalation step" if kept.empty?
+
+      kept
+    end
+
+    # Whether any tier of the path has several models to rotate between.
+    def rotating?(path)
+      tiers(path).any? { |tier| rotates?(tier) }
+    end
+
+    # Steps sorted by priority, lowest first, ties kept in the order declared.
     def ordered(steps, label)
-      numbered = steps.count { |step| step.key?(:order) }
-      return steps.map { |step| step.except(:order) } if numbered.zero?
+      numbered = steps.count { |step| step.key?(:priority) }
+      return steps if numbered.zero?
 
       if numbered < steps.size
-        raise ConfigurationError, "#{label}: give every step an order: or none (#{numbered} of #{steps.size} have one)"
+        raise ConfigurationError,
+          "#{label}: give every step a priority: or none (#{numbered} of #{steps.size} have one)"
       end
 
-      orders = steps.map { |step| step[:order] }
-      duplicates = orders.tally.select { |_, count| count > 1 }.keys
-      raise ConfigurationError, "#{label}: duplicate order: #{duplicates.join(', ')}" if duplicates.any?
+      steps.each_with_index.sort_by { |step, index| [step[:priority], index] }.map(&:first)
+    end
+
+    # Runs of steps with the same priority. A step without one is a tier of its own.
+    def tiers(path)
+      path.slice_when { |before, after| before[:priority].nil? || before[:priority] != after[:priority] }
+    end
+
+    def rotates?(tier)
+      tier.size > 1 && tier.none? { |step| step[:rotate] == false }
+    end
 
-      steps.sort_by { |step| step[:order] }.map { |step| step.except(:order) }
+    def rotated(path, turn)
+      tiers(path).flat_map { |tier| rotates?(tier) ? tier.rotate(turn % tier.size) : tier }
     end
 
-    def normalize_step(step, label)
+    # extras: names more keys a step Hash may carry for its caller (a judge's type:, say). They are kept as given,
+    # for the caller to check.
+    def normalize_step(step, label, extras: [])
       case step
       when String, Symbol
         { model: model_name(step, label), provider: nil, params: nil, attempts: 1, forward_rejected: true }
-      when Hash then normalize_hash(step, label)
+      when Hash then normalize_hash(step, label, extras)
       else
         raise ConfigurationError, "#{label}: each step must be a model name or a Hash with model:, got #{step.inspect}"
       end
     end
 
-    def normalize_hash(step, label)
+    def normalize_hash(step, label, extras)
       step = step.transform_keys(&:to_sym)
-      unknown = step.keys - STEP_KEYS
+      unknown = step.keys - STEP_KEYS - extras
       raise ConfigurationError, "#{label}: unknown step option(s) #{unknown.join(', ')}" if unknown.any?
       unless step[:model].is_a?(String) || step[:model].is_a?(Symbol)
         raise ConfigurationError, "#{label}: a step needs a model: name, got #{step.inspect}"
@@ -104,10 +151,17 @@ module Squishling
       unless attempts.is_a?(Integer) && attempts.positive?
         raise ConfigurationError, "#{label} (#{model}): attempts: must be a positive Integer, got #{attempts.inspect}"
       end
-      if step.key?(:order) && !step[:order].is_a?(Integer)
-        raise ConfigurationError, "#{label} (#{model}): order: must be an Integer, got #{step[:order].inspect}"
+
+      step = priority_alias(step, label, model)
+      if step.key?(:priority) && !step[:priority].is_a?(Integer)
+        raise ConfigurationError, "#{label} (#{model}): priority: must be an Integer, got #{step[:priority].inspect}"
+      end
+      if step.key?(:rotate) && ![true, false].include?(step[:rotate])
+        raise ConfigurationError, "#{label} (#{model}): rotate: must be true or false, got #{step[:rotate].inspect}"
       end
 
+      check_include_when!(step, label, model)
+      check_retry_temperature!(step, label, model)
       forward_rejected = step.fetch(:forward_rejected, true)
       unless [true, false].include?(forward_rejected)
         raise ConfigurationError,
@@ -116,7 +170,43 @@ module Squishling
 
       params = step[:params] && Params.normalize(step[:params], "#{label} (#{model}) params")
       normalized = { model:, provider: step[:provider], params:, attempts:, forward_rejected: }
-      step.key?(:order) ? normalized.merge(order: step[:order]) : normalized
+      normalized.merge(step.slice(:priority, :rotate, :include_when, :retry_temperature, *extras))
+    end
+
+    def check_include_when!(step, label, model)
+      return if !step.key?(:include_when) || step[:include_when].is_a?(Proc)
+
+      raise ConfigurationError,
+        "#{label} (#{model}): include_when: must be a Proc, got #{step[:include_when].inspect}"
+    end
+
+    def valid_temperature?(temperature)
+      temperature.is_a?(Numeric) && temperature.real? && temperature.finite? && !temperature.negative?
+    end
+
+    def check_retry_temperature!(step, label, model)
+      temperature = step[:retry_temperature]
+      return if !step.key?(:retry_temperature) || valid_temperature?(temperature)
+
+      raise ConfigurationError,
+        "#{label} (#{model}): retry_temperature: must be a finite Numeric of 0 or more, got #{temperature.inspect}"
+    end
+
+    # A step used on its own (a judge, a harness's step) can't take part in a tier or be left out of a call, so it
+    # takes no priority:, rotate:, or include_when:. who names it for the message.
+    def single_step!(step, who)
+      return unless step.key?(:priority) || step.key?(:rotate) || step.key?(:include_when)
+
+      raise ConfigurationError, "#{who} takes no priority:, rotate:, or include_when:"
+    end
+
+    # order: is the deprecated name of priority:.
+    def priority_alias(step, label, model)
+      return step unless step.key?(:order)
+      raise ConfigurationError, "#{label} (#{model}): give priority: or order:, not both" if step.key?(:priority)
+
+      warn "[Squishling] #{label} (#{model}): order: is deprecated, use priority:"
+      step.except(:order).merge(priority: step[:order])
     end
 
     def model_name(model, label)

data/lib/squishling/named_registry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Classes by name, for the things that can be registered (harnesses, adapters): the built-ins, registered as they
+  # load, and the developer's own. Shared across threads, so every read and write is under the lock.
+  class NamedRegistry
+    NAME = /\A[a-z][a-z0-9_]*\z/
+
+    # kind names what is registered ("harness"), for messages.
+    def initialize(kind)
+      @kind = kind
+      @lock = Mutex.new
+      @built_in = {}
+      @custom = {}
+    end
+
+    def register_built_in(name, klass)
+      @lock.synchronize { @built_in[name] = klass }
+    end
+
+    # The name as a Symbol. Raises ConfigurationError when it isn't a Symbol or String of lowercase letters, digits
+    # and underscores, starting with a letter.
+    def checked_name(name)
+      unless name.is_a?(Symbol) || name.is_a?(String)
+        raise ConfigurationError, "#{@kind} name must be a Symbol or String, got #{name.inspect}"
+      end
+
+      name = name.to_sym
+      return name if NAME.match?(name)
+
+      raise ConfigurationError,
+        "#{@kind} name #{name.inspect} must be lowercase letters, digits, and underscores, starting with a letter"
+    end
+
+    # Registers klass under name (already checked), unless the name is taken.
+    def add(name, klass)
+      @lock.synchronize do
+        raise ConfigurationError, "#{@kind} #{name.inspect} is already registered" if taken?(name)
+
+        @custom[name] = klass
+      end
+      klass
+    end
+
+    def fetch(name)
+      @lock.synchronize { @built_in[name] || @custom[name] }
+    end
+
+    def names
+      @lock.synchronize { @built_in.keys + @custom.keys }
+    end
+
+    # Forgets the registered classes; the built-ins stay.
+    def reset!
+      @lock.synchronize { @custom.clear }
+    end
+
+    private
+
+    def taken?(name)
+      @built_in.key?(name) || @custom.key?(name)
+    end
+  end
+end

data/lib/squishling/observer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Squishling
+  # The around-style hook for tools that must see an LLM request while it is made (a tracing span, a Coolhand
+  # declared workload), which squawk's after-the-fact report can't do. An observer is any object responding to
+  # around(call), which yields once to make the request. See docs/observers.md.
+  #
+  # Observers get call metadata (Call) and, back from the yield, the request's token Usage: never the model's
+  # output or the method's inputs.
+  module Observer
+    # What an observer is told about one provider request. handed_off is true when squish! sent the call to the
+    # LLM (typically from a rescue) and false when squish_when or a missing implementation did. role is nil for an
+    # escalation attempt, :sample (with sample "a", "b", ...) or :judge, like squawk's metadata. attempt and
+    # attempts count the (expanded) escalation path the request belongs to. request is :chat, or :judgment for a
+    # System One judge.
+    Call = Data.define(:label, :purpose, :harness, :handed_off, :role, :sample, :attempt, :attempts, :model, :provider,
+      :request)
+
+    # What an observer's block returns: the request's token usage and the model that answered, never the content.
+    # A count the provider didn't report is nil.
+    Usage = Data.define(:input_tokens, :output_tokens, :model)
+
+    BUILT_IN = %i[coolhand].freeze
+
+    module_function
+
+    # The observer itself, nil (auto-detect), or false (none). A built-in's name (:coolhand) or anything that
+    # responds to around is accepted, checked here so a mistake fails at setup, not inside the first request.
+    def validate(observer, where)
+      return observer if observer.nil? || observer == false
+
+      if observer.is_a?(Symbol)
+        return observer if BUILT_IN.include?(observer)
+
+        raise ConfigurationError, "#{where} observer must be one of #{BUILT_IN.map(&:inspect).join(', ')}, " \
+                                  "an object that responds to around, or false, got #{observer.inspect}"
+      end
+      return observer if observer.respond_to?(:around)
+
+      raise ConfigurationError, "#{where} observer must respond to around(call) { ... } (or be false), " \
+                                "got #{observer.inspect}"
+    end
+
+    # The observer that wraps a request: the configured one, the Coolhand observer when nothing is configured and
+    # Coolhand is loaded and set up, or nil.
+    def resolve(configured)
+      case configured
+      when false then nil
+      when nil then Observers::Coolhand.new if Observers::Coolhand.available?
+      when Symbol then Observers::Coolhand.new
+      else configured
+      end
+    end
+
+    # Runs the request inside the resolved observer, if there is one. The block runs on the calling thread, so
+    # for samples it is the worker thread that makes the request. The observer gets the request's Usage back from
+    # its yield, not the response, so the model's output can't leave the process through it, and what it returns
+    # is ignored, and so is any rescue of the request's error: the error is raised again. An observer that never
+    # yields would make the request vanish, and one that yields twice would send it twice: both are setup mistakes.
+    def around(call)
+      observer = resolve(Squishling.config.observer)
+      return yield unless observer
+
+      yielded = false
+      response = nil
+      failure = nil
+      observer.around(call) do
+        if yielded
+          failure = ConfigurationError.new("#{call.label}: #{observer.class}#around must yield only once")
+          raise failure
+        end
+
+        yielded = true
+        begin
+          response = yield
+        rescue StandardError => e
+          failure = e
+          raise
+        end
+        usage(response)
+      end
+      unless yielded
+        raise ConfigurationError,
+          "#{call.label}: the #{observer.class} observer's around must yield to make the request"
+      end
+
+      raise failure if failure # an observer can't swallow the request's error: Squishling's taxonomy holds
+
+      response
+    end
+
+    # An Adapter::Response carries its token counts in a Hash; a judgment (see Adapter::Base#judge) may carry them in
+    # an object with input and output instead. Shared with Budget::Tally; not part of the public API.
+    def usage(response)
+      tokens = response.respond_to?(:tokens) ? response.tokens : nil
+      model = response.respond_to?(:model) ? response.model : nil
+      Usage.new(input_tokens: token_count(tokens, :input_tokens, :input),
+        output_tokens: token_count(tokens, :output_tokens, :output),
+        model: model.respond_to?(:id) ? model.id : model)
+    end
+
+    def token_count(tokens, key, reader)
+      return tokens[key] if tokens.is_a?(Hash)
+
+      tokens.respond_to?(reader) ? tokens.public_send(reader) : nil
+    end
+    private_class_method :token_count
+  end
+end