squishling 0.2.0 → 0.4.0

data/lib/squishling/model_path.rb

@@ -8,13 +8,22 @@ 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.
+  # 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.
   module ModelPath
-    # One attempt: the model, its provider, and the fully resolved generation params.
-    Step = Data.define(:model, :provider, :params)
+    # 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).
+      def display_name
+        model || "RubyLLM default model"
+      end
+    end
 
-    STEP_KEYS = %i[model provider params attempts order].freeze
+    STEP_KEYS = %i[model provider params attempts priority order rotate forward_rejected].freeze
 
     module_function
 
@@ -50,42 +59,62 @@ 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]))
+          params: Params.resolve(params, step[:params]), forward_rejected: step[:forward_rejected])
         [attempt] * step[:attempts]
       end
     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
 
-      steps.sort_by { |step| step[:order] }.map { |step| step.except(:order) }
+    def rotates?(tier)
+      tier.size > 1 && tier.none? { |step| step[:rotate] == false }
     end
 
-    def normalize_step(step, label)
+    def rotated(path, turn)
+      tiers(path).flat_map { |tier| rotates?(tier) ? tier.rotate(turn % tier.size) : tier }
+    end
+
+    # 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 then { model: model_name(step, label), provider: nil, params: nil, attempts: 1 }
-      when Hash then normalize_hash(step, label)
+      when String, Symbol
+        { model: model_name(step, label), provider: nil, params: nil, attempts: 1, forward_rejected: true }
+      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}"
@@ -96,13 +125,41 @@ 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
+
+      forward_rejected = step.fetch(:forward_rejected, true)
+      unless [true, false].include?(forward_rejected)
+        raise ConfigurationError,
+          "#{label} (#{model}): forward_rejected: must be true or false, got #{forward_rejected.inspect}"
       end
 
       params = step[:params] && Params.normalize(step[:params], "#{label} (#{model}) params")
-      normalized = { model:, provider: step[:provider], params:, attempts: }
-      step.key?(:order) ? normalized.merge(order: step[:order]) : normalized
+      normalized = { model:, provider: step[:provider], params:, attempts:, forward_rejected: }
+      normalized.merge(step.slice(:priority, :rotate, *extras))
+    end
+
+    # A step used on its own (a judge, a harness's step) can't take part in a tier, so it takes no priority: or
+    # rotate:. who names it for the message.
+    def single_step!(step, who)
+      return unless step.key?(:priority) || step.key?(:rotate)
+
+      raise ConfigurationError, "#{who} takes no priority: or rotate:"
+    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/observer.rb

@@ -0,0 +1,100 @@
+# 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
+
+    def usage(response)
+      tokens = response.respond_to?(:tokens) ? response.tokens : nil
+      model = response.respond_to?(:model) ? response.model : nil
+      Usage.new(input_tokens: tokens&.input, output_tokens: tokens&.output,
+        model: model.respond_to?(:id) ? model.id : model)
+    end
+    private_class_method :usage
+  end
+end

data/lib/squishling/observers/coolhand.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Squishling
+  module Observers
+    # Declares each request's workload and template to Coolhand (Coolhand.with_context), so Coolhand files the
+    # logged call under them instead of matching it to a template. The workload is the squished method
+    # ("Class#method", described as that, plus "(rescue)" when squish! handed the call over); the template is the
+    # call's place in it: "Class#method/squish:L2" (an escalation attempt), "/sample:a", or "/judge". The model
+    # isn't in the key: it's on the log, and the place is the stable identity.
+    # Used automatically when the coolhand gem is loaded and configured (see Observer.resolve). See docs/coolhand.md.
+    class Coolhand
+      REPORTER = "squishling"
+
+      # Coolhand rejects keys longer than this.
+      MAX_KEY_LENGTH = 255
+
+      # Whether Coolhand is loaded, new enough to declare workloads, and set up to send logs.
+      def self.available?
+        return false unless defined?(::Coolhand) && ::Coolhand.respond_to?(:with_context)
+
+        configuration = ::Coolhand.respond_to?(:configuration) && ::Coolhand.configuration
+        return false unless configuration
+
+        configuration.enabled != false && !configuration.api_key.to_s.strip.empty?
+      rescue StandardError
+        false # nobody asked for this observer, so a Coolhand that can't say whether it's set up isn't ours to break
+      end
+
+      def self.load_library
+        require "coolhand"
+      end
+      private_class_method :load_library
+
+      # Raises ConfigurationError when the coolhand gem is missing or too old to declare workloads.
+      def initialize
+        self.class.send(:load_library) unless defined?(::Coolhand)
+        return if ::Coolhand.respond_to?(:with_context)
+
+        raise ConfigurationError, "observer :coolhand needs a coolhand gem version with Coolhand.with_context " \
+                                  "(declared workloads); upgrade the coolhand gem"
+      rescue LoadError
+        raise ConfigurationError, "observer :coolhand needs the coolhand gem; add `gem \"coolhand\"` to your Gemfile"
+      end
+
+      def around(call, &)
+        workload = call.label
+        template = "#{workload}/#{role_key(call)}"
+        return yield unless declarable?(workload) && declarable?(template)
+
+        ::Coolhand.with_context(
+          reporter: REPORTER,
+          workload: { key: workload, name: workload, description: description(call) },
+          template: { key: template, name: "#{workload} · #{role_name(call)}" },
+          &
+        )
+      end
+
+      private
+
+      # The squished method, marked "(rescue)" when squish! handed it to the LLM. Not the purpose text, which can be
+      # a proc that differs per call.
+      def description(call)
+        call.handed_off ? "#{call.label} (rescue)" : call.label
+      end
+
+      # Coolhand rejects, and drops the whole log for, a key over the limit, with surrounding whitespace, or with
+      # a leading, trailing or doubled "/".
+      def declarable?(key)
+        key.length <= MAX_KEY_LENGTH && key == key.strip && !key.start_with?("/") && !key.end_with?("/") &&
+          !key.include?("//")
+      end
+
+      def role_key(call)
+        case call.role
+        when :sample then "sample:#{call.sample}"
+        when :judge then "judge"
+        else "squish:L#{call.attempt}"
+        end
+      end
+
+      def role_name(call)
+        role_key(call).tr(":", " ")
+      end
+    end
+  end
+end

data/lib/squishling/output_check.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Squishling
+  # Turns a model response into a typed result: parses it, validates it against the schema, and runs the
+  # method's squish_validate check.
+  class OutputCheck
+    MAX_ERRORS = 20
+    UNREPRESENTABLE = "response contained a value JSON can't represent (such as Infinity or invalid UTF-8)"
+
+    def initialize(definition, receiver, inputs)
+      @definition = definition
+      @receiver = receiver
+      @inputs = inputs
+    end
+
+    # Parses and validates a response: [typed result, []] when it passes, [nil or result, errors] otherwise.
+    # The judge's role skips squish_validate, which checks the operation's output, not a verdict.
+    def call(content, prompt)
+      data, errors = parse(content)
+      errors = prompt.schema.validate(data) if errors.empty?
+      return [nil, cap(errors)] if errors.any?
+
+      result = prompt.schema.build(data, squished: true)
+      [result, prompt.role == :judge ? [] : validator_errors(result)]
+    end
+
+    private
+
+    # RubyLLM parses structured output itself and leaves the raw string when that fails, so
+    # content is a Hash on success, or a String/nil when the model refused, was cut off, or
+    # ignored the schema.
+    def parse(content)
+      return [nil, [UNREPRESENTABLE]] if content.is_a?(String) && !content.valid_encoding?
+      return [nil, ["response was empty"]] if content.nil? || (content.is_a?(String) && content.strip.empty?)
+
+      data = content.is_a?(String) ? JSON.parse(strip_code_fence(content)) : content
+      representable?(data) ? [data, []] : [nil, [UNREPRESENTABLE]]
+    rescue JSON::ParserError => e
+      [nil, ["response was not valid JSON#{parse_position(e)}"]]
+    end
+
+    # JSON.parse turns an out-of-range number such as 1e400 into Infinity, and accepts invalid UTF-8 in a string.
+    # Both can satisfy the schema but can't be serialized again (and the deterministic path rejects them), so
+    # they are invalid output.
+    def representable?(data)
+      JSON.generate(data)
+      true
+    rescue JSON::GeneratorError
+      false
+    end
+
+    # A long output can fail the schema thousands of times over; every error goes into the retry message and
+    # the log, so only the first few are kept.
+    def cap(errors)
+      return errors if errors.size <= MAX_ERRORS
+
+      errors.first(MAX_ERRORS) + ["... and #{errors.size - MAX_ERRORS} more errors"]
+    end
+
+    # The parser's message quotes a snippet of the response, which must not reach error messages or logs
+    # (the raw output lives only in InvalidOutputError#raw), so only the position is kept.
+    def parse_position(error)
+      position = error.message.strip.match(/ at line (\d+) column (\d+)\z/)
+      position ? " (at line #{position[1]} column #{position[2]})" : ""
+    end
+
+    # Models without native structured output sometimes wrap JSON in a markdown code fence.
+    def strip_code_fence(text)
+      text[/\A\s*```(?:json)?\s*\n(.*?)\n\s*```\s*\z/m, 1] || text
+    end
+
+    # Runs the squish_validate check, if any. Exceptions it raises are the user's own and propagate as-is.
+    def validator_errors(result)
+      validator = @definition.validator
+      return [] unless validator
+
+      value = @receiver.instance_exec(result, **@inputs, &validator)
+      case value
+      when nil, true then []
+      when false then ["the output was rejected by squish_validate"]
+      when String, Array then Array(value).flatten.compact.map(&:to_s).reject { |message| message.strip.empty? }
+      else
+        return contract_errors(value) if value.respond_to?(:success?) && value.respond_to?(:errors)
+
+        raise ConfigurationError, "#{@definition.label}: squish_validate must return nil, true, false, a String, " \
+                                  "an Array of Strings, or a validation result, got #{value.class}"
+      end
+    end
+
+    # A dry-validation style result: errors.to_h is { key => ["message", ...] }, nested for nested keys.
+    def contract_errors(value)
+      return [] if value.success?
+
+      errors = value.errors
+      errors = errors.to_h if !errors.is_a?(Array) && errors.respond_to?(:to_h)
+      messages = errors.is_a?(Hash) ? flatten_messages(errors) : Array(errors).map(&:to_s)
+      messages.empty? ? ["the output was rejected by squish_validate"] : messages
+    end
+
+    def flatten_messages(errors, prefix = nil)
+      errors.flat_map do |key, value|
+        path = [prefix, key].compact.join(".")
+        next flatten_messages(value, path) if value.is_a?(Hash)
+
+        Array(value).map { |message| path.empty? ? message.to_s : "#{path} #{message}" }
+      end
+    end
+  end
+end

data/lib/squishling/params.rb

@@ -11,9 +11,25 @@ module Squishling
     RESERVED_KEYS = %i[
       model messages input inputs instructions contents system system_instruction systemInstruction cachedContent
       stream stream_options store include response_format text output_config outputConfig tools tool_choice
-      toolConfig schema
+      toolConfig tool_config schema
     ].freeze
 
+    # Some protocols carry the structured-output format (or tool selection) inside a container that is
+    # itself allowed, because it also holds ordinary settings (Gemini's topK, Mistral's top_p, ...). RubyLLM
+    # deep-merges provider options, so these nested keys would override the strict format just like the
+    # top-level ones. Re-check each protocol's render_payload (ruby_llm protocols/*/chat.rb) on every
+    # ruby_llm upgrade.
+    GENERATION_CONFIG_RESERVED_KEYS = %i[
+      responseMimeType response_mime_type responseSchema response_schema responseJsonSchema response_json_schema
+      response_format tools tool_choice toolConfig tool_config
+    ].freeze
+    COMPLETION_ARGS_RESERVED_KEYS = %i[response_format tools tool_choice].freeze
+    NESTED_RESERVED_KEYS = {
+      generationConfig: GENERATION_CONFIG_RESERVED_KEYS, # Gemini
+      generation_config: GENERATION_CONFIG_RESERVED_KEYS, # Gemini Interactions
+      completion_args: COMPLETION_ARGS_RESERVED_KEYS # Mistral Conversations
+    }.freeze
+
     module_function
 
     # Validates and symbolizes one layer. nil values are kept so a layer can unset an inherited key.
@@ -21,15 +37,40 @@ module Squishling
       raise ConfigurationError, "#{label} must be a Hash, got #{params.class}" unless params.is_a?(Hash)
 
       params = params.transform_keys(&:to_sym)
-      reserved = params.keys & RESERVED_KEYS
-      if reserved.any?
-        raise ConfigurationError, "#{label}: #{reserved.join(', ')} can't be set through params " \
-                                  "(controlled by Squishling/RubyLLM; use model:/provider:/output_schema)"
-      end
+      reject_reserved!(params, RESERVED_KEYS, label, "; use model:/provider:/output_schema")
+      reject_nested_reserved!(params, label)
       params[:thinking] = normalize_thinking(params[:thinking], label) unless params[:thinking].nil?
       params.freeze
     end
 
+    # Raises when params sets any of the keys Squishling owns. hint is appended inside the parenthetical.
+    def reject_reserved!(params, keys, label, hint = "")
+      reserved = params.keys & keys
+      return if reserved.empty?
+
+      raise ConfigurationError, "#{label}: #{reserved.join(', ')} can't be set through params " \
+                                "(controlled by Squishling/RubyLLM#{hint})"
+    end
+
+    # Nested keys are compared as symbols so a string-keyed "responseMimeType" can't slip past the check.
+    # A non-Hash container would replace (not merge into) the one RubyLLM builds, wiping the strict format.
+    # Validated containers are copied and frozen so they can't be mutated after the check.
+    def reject_nested_reserved!(params, label)
+      nested = NESTED_RESERVED_KEYS.flat_map do |container, reserved|
+        value = params[container]
+        next [] if value.nil?
+        raise ConfigurationError, "#{label}: #{container} must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+        params[container] = value.dup.freeze
+        (value.keys.filter_map { |key| key.to_sym if key.respond_to?(:to_sym) } & reserved)
+          .map { |key| "#{container}.#{key}" }
+      end
+      return if nested.empty?
+
+      raise ConfigurationError, "#{label}: #{nested.join(', ')} can't be set through params " \
+                                "(controls the strict output format or tools; use output_schema)"
+    end
+
     # Later layers override earlier ones key by key; nil removes the key (back to the provider default).
     def resolve(*layers)
       layers.compact.reduce({}) { |merged, layer| merged.merge(layer) }.compact

data/lib/squishling/rotation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Squishling
+  # How many times each squished method has been called with models to rotate between (see ModelPath: steps tied on
+  # priority). The count is the call's turn: each tier of tied models starts that many steps further along, so
+  # successive calls give every model an even share of the first attempts. Counted per class and method, across
+  # threads.
+  module Rotation
+    # class => { method name => calls so far }. Weak keys, so classes replaced by code reloading can be collected.
+    COUNTS = ObjectSpace::WeakKeyMap.new
+    COUNTS_LOCK = Mutex.new
+    private_constant :COUNTS, :COUNTS_LOCK
+
+    class << self
+      # This call's turn, counting from 0, and counts it.
+      def advance(klass, name)
+        COUNTS_LOCK.synchronize do
+          counts = (COUNTS[klass] ||= {})
+          turn = counts.fetch(name, 0)
+          counts[name] = turn + 1
+          turn
+        end
+      end
+    end
+  end
+end

data/lib/squishling/router.rb

@@ -13,7 +13,7 @@ module Squishling
     class << self
       def dispatch(receiver, name, args, kwargs, impl, wrapper:)
         if (frame = enclosing_frame(receiver, name, wrapper))
-          return frame.definition.coerce(impl.call)
+          return coerce_inner(frame, impl.call)
         end
 
         definition = receiver.class.squishling_definition(name)
@@ -57,6 +57,12 @@ module Squishling
 
       private
 
+      # An inner call (`super`, or the method called from squish_when or a fallback) hands its value to user code
+      # that may reshape it, so only a Hash is typed (for accessor access); the outermost return is validated in full.
+      def coerce_inner(frame, value)
+        value.is_a?(Hash) ? frame.definition.coerce(value) : value
+      end
+
       def route_to_llm(frame, definition, reason)
         log(definition, reason)
         previous = frame.phase
@@ -73,7 +79,7 @@ module Squishling
 
       # The call in progress that this one is part of, which runs its Ruby implementation without routing again:
       # a subclass override's `super` (entered through an ancestor's wrapper), or a call made while deciding or on
-      # the LLM path (squish_when, squish_fallback, an instructions proc). Only recursion from the Ruby
+      # the LLM path (squish_when, squish_fallback, a purpose proc). Only recursion from the Ruby
       # implementation itself is a new call, routed on its own.
       def enclosing_frame(receiver, name, wrapper)
         frame = frames.reverse_each.find do |candidate|

data/lib/squishling/run/messages.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Squishling
+  class Run
+    # The follow-up messages a Run sends a model after an output was rejected.
+    module Messages
+      private
+
+      def retry_message(errors)
+        "Your previous response was rejected:\n- #{errors.join("\n- ")}\nRespond again with corrected JSON only."
+      end
+
+      # The first message to a fresh chat after an earlier model's output was rejected. The rejected output is
+      # model-generated and may cross providers, so it is capped at Invoker::MAX_FORWARDED_CHARS.
+      def escalation_message(input, raw, errors)
+        previous = rejected_text(raw)
+        previous = "(an empty response)" if previous.strip.empty? || raw.nil?
+        if previous.length > Invoker::MAX_FORWARDED_CHARS
+          omitted = previous.length - Invoker::MAX_FORWARDED_CHARS
+          previous = "#{previous[0, Invoker::MAX_FORWARDED_CHARS]}... [truncated, #{omitted} more characters]"
+        end
+        "#{input}\n\nA previous attempt at this request returned:\n#{previous}\n" \
+          "It was rejected:\n- #{errors.join("\n- ")}\nRespond with corrected JSON only."
+      end
+
+      # The rejected output as text. Output that was rejected for being unrepresentable in JSON (Infinity, invalid
+      # UTF-8) can't be serialized or measured as is, so it is scrubbed or replaced rather than raising.
+      def rejected_text(raw)
+        return utf8(raw).scrub("?") if raw.is_a?(String)
+
+        JSON.generate(raw)
+      rescue JSON::JSONError
+        "(a response JSON can't represent)"
+      end
+
+      # A binary-tagged string counts every byte as valid, so it is read as UTF-8 before scrubbing.
+      def utf8(text)
+        text.encoding == Encoding::BINARY ? text.dup.force_encoding(Encoding::UTF_8) : text
+      end
+    end
+  end
+end