samagotchi 0.64.0 → 0.65.0

data/lib/samagotchi/llm/anthropic_wire.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require_relative "../log"
+require_relative "utf8_scrub"
+
+module Samagotchi
+  module LLM
+    # ChatLoop's wire messages (the OpenAI shape #wire_messages builds) as a
+    # Messages request's top-level system blocks and messages
+    # (AnthropicMessages):
+    # - the head system message → the top-level system, as text blocks: with
+    #   its cache_split, two blocks, the breakpoint on the first; a later
+    #   system message → user text (a mid-conversation system role is
+    #   model-gated);
+    # - an assistant message → its saved blocks verbatim (anthropic_content),
+    #   else a text block and its tool_use blocks (arguments as the input
+    #   object); one with neither is dropped;
+    # - tool messages → tool_result blocks in a user message;
+    # - user parts → text blocks and image blocks (a data URL as base64, an
+    #   http(s) URL as a url source).
+    # Consecutive messages of one role go as one message (so a turn's tool
+    # results and the "[images from tool results]" message after them make
+    # one user message), its tool_result blocks first (Messages wants them
+    # before any other block). Empty or blank text blocks are never
+    # sent; a user message left with none says PLACEHOLDER. reasoning_content
+    # and cache_split never go out.
+    module AnthropicWire
+      PLACEHOLDER = "(empty)"
+      # What Messages takes as a tool_use id.
+      TOOL_ID_INVALID = /[^a-zA-Z0-9_-]/
+      # What Messages takes as a tool name.
+      TOOL_NAME = /\A[a-zA-Z0-9_-]{1,128}\z/
+      # Blocks that can't carry a cache_control breakpoint.
+      UNMARKABLE = %w[thinking redacted_thinking].freeze
+
+      # A request's system blocks and messages.
+      Translated = Data.define(:system, :messages)
+
+      module_function
+
+      # @param wire [Array<Hash>] ChatLoop's wire messages (symbol or string keys)
+      # @param cache [Hash, nil] the cache_control the breakpoints carry
+      #   (PromptCache.control): on the head system's first block and on the
+      #   last block that didn't come from a later system message (a tail
+      #   note moves each request, as PromptCache's rule says); nil sets none
+      # @return [Translated]
+      def translate(wire, cache: nil)
+        system = []
+        messages = []
+        notes = {}.compare_by_identity
+        Array(wire).each_with_index do |raw, index|
+          message = raw.to_h.transform_keys(&:to_sym)
+          role = message[:role].to_s
+          if role == "system" && index.zero?
+            system = system_blocks(message[:content], message[:cache_split], cache)
+            next
+          end
+
+          case role
+          when "assistant" then append(messages, "assistant", assistant_blocks(message))
+          when "tool" then append(messages, "user", [tool_result(message)])
+          when "system"
+            blocks = content_blocks(message[:content])
+            blocks.each { |block| notes[block] = true }
+            append(messages, "user", blocks)
+          else append(messages, "user", content_blocks(message[:content]))
+          end
+        end
+        messages.each { |message| message[:content] << text_block(PLACEHOLDER) if message[:content].empty? }
+        mark_last(messages, cache, notes) if cache
+        Translated.new(system: system, messages: messages)
+      end
+
+      # ChatLoop's function definitions as Messages tools.
+      # @param tools [Array<Hash>] {type: "function", function: {name:, description:, parameters:}}
+      def tools(tools)
+        Array(tools).map do |tool|
+          function = (tool[:function] || tool["function"] || tool).to_h.transform_keys(&:to_sym)
+          { name: function[:name].to_s, description: function[:description],
+            input_schema: function[:parameters] || { type: "object", properties: {} } }.compact
+        end
+      end
+
+      # +id+ as Messages takes it (^[a-zA-Z0-9_-]+$), the same in tool_use
+      # and tool_result: a valid id as it is, another with its invalid
+      # characters replaced and a short hash of it appended (so "a.b" and
+      # "a_b" stay apart).
+      def tool_id(id)
+        text = id.to_s
+        return text if !text.empty? && !text.match?(TOOL_ID_INVALID)
+
+        "#{text.gsub(TOOL_ID_INVALID, "_")}_#{Digest::SHA256.hexdigest(text)[0, 8]}"
+      end
+
+      # A tool name as Messages takes it (TOOL_NAME): a model's malformed one
+      # ("get_weather\n</parameter", a streaming glitch) would 400 every
+      # later request once sent back.
+      def tool_name(name)
+        text = name.to_s
+        return text if text.match?(TOOL_NAME)
+
+        text = text.gsub(TOOL_ID_INVALID, "_")[0, 128]
+        text.empty? ? "tool" : text
+      end
+
+      # A message joins the one before it when the role is the same; an
+      # assistant message with no blocks is dropped.
+      def append(messages, role, blocks)
+        return if role == "assistant" && blocks.empty?
+
+        if messages.last && messages.last[:role] == role
+          content = messages.last[:content].concat(blocks)
+          results, rest = content.partition { |block| type_of(block) == "tool_result" }
+          messages.last[:content] = results + rest
+        else
+          messages << { role: role, content: blocks }
+        end
+      end
+
+      def system_blocks(content, split, cache)
+        text = scrub(content.to_s)
+        return [] if blank?(text)
+
+        head = split.is_a?(Integer) && split.positive? && split < text.length ? text[0, split] : text
+        tail = head.length < text.length ? text[head.length..] : ""
+        first = text_block(head)
+        first[:cache_control] = cache if cache
+        blank?(tail) ? [first] : [first, text_block(tail)]
+      end
+
+      # The saved blocks go back as they came (string keys); otherwise the
+      # text, then the calls.
+      def assistant_blocks(message)
+        saved = message[:anthropic_content]
+        return saved.map { |block| valid_tool_use(block) } if saved.is_a?(Array) && !saved.empty?
+
+        blocks = content_blocks(message[:content])
+        Array(message[:tool_calls]).each do |raw|
+          call = raw.to_h.transform_keys(&:to_sym)
+          function = (call[:function] || {}).to_h.transform_keys(&:to_sym)
+          name = function[:name].to_s
+          blocks << { type: "tool_use", id: tool_id(call[:id]), name: tool_name(name), input: input_of(function[:arguments], name) }
+        end
+        blocks
+      end
+
+      # A saved block as it came, but a tool_use's name made valid and its
+      # id mapped as its tool_result's is (#tool_id: a provider may answer
+      # an id such as "functions.get_weather:0", which Messages refuses
+      # sent back, and the result would name another id).
+      def valid_tool_use(block)
+        return block.dup unless block.is_a?(Hash) && type_of(block) == "tool_use"
+
+        name_key = block.key?("name") ? "name" : :name
+        id_key = block.key?("id") ? "id" : :id
+        block.merge(name_key => tool_name(block[name_key]), id_key => tool_id(block[id_key]))
+      end
+
+      # A tool call's arguments as the input object: ChatLoop sends a JSON
+      # String (raw when it was invalid, for a paired call): one that isn't
+      # an object goes as {}.
+      def input_of(arguments, name)
+        return arguments if arguments.is_a?(Hash)
+
+        text = arguments.to_s
+        return {} if text.strip.empty?
+
+        parsed = JSON.parse(text)
+        return parsed if parsed.is_a?(Hash)
+
+        warn_arguments(name)
+      rescue JSON::ParserError
+        warn_arguments(name)
+      end
+
+      def warn_arguments(name)
+        Log.warn(:model, "tool_arguments_invalid", tool: name, detail: "sent as {} to a Messages host")
+        {}
+      end
+
+      def tool_result(message)
+        block = { type: "tool_result", tool_use_id: tool_id(message[:tool_call_id]) }
+        text = scrub(message[:content].to_s)
+        block[:content] = text unless blank?(text)
+        block
+      end
+
+      # A String or a parts list as blocks.
+      def content_blocks(content)
+        return blank?(content.to_s) ? [] : [text_block(scrub(content.to_s))] unless content.is_a?(Array)
+
+        content.filter_map do |raw|
+          next unless raw.is_a?(Hash)
+
+          part = raw.transform_keys(&:to_sym)
+          case part[:type].to_s
+          when "text" then blank?(part[:text].to_s) ? nil : text_block(scrub(part[:text].to_s))
+          when "image_url" then image_block(part[:image_url])
+          when "image" then raw
+          end
+        end
+      end
+
+      def image_block(image_url)
+        url = image_url.is_a?(Hash) ? (image_url[:url] || image_url["url"]).to_s : image_url.to_s
+        if (match = url.match(/\Adata:([^;,]+);base64,(.*)\z/m))
+          { type: "image", source: { type: "base64", media_type: match[1], data: match[2] } }
+        elsif url.match?(%r{\Ahttps?://}i)
+          { type: "image", source: { type: "url", url: url } }
+        end
+      end
+
+      # Breakpoint #2: the last user block that can carry one and didn't
+      # come from a later system message (+notes+).
+      def mark_last(messages, cache, notes)
+        markable = ->(block) { !UNMARKABLE.include?(type_of(block)) && !notes.key?(block) }
+        message = messages.reverse_each.find { |m| m[:role] == "user" && m[:content].any?(&markable) } or return
+        index = message[:content].rindex(&markable)
+        block = message[:content][index]
+        key = block.key?("type") ? "cache_control" : :cache_control
+        message[:content][index] = block.merge(key => cache)
+      end
+
+      def type_of(block) = (block[:type] || block["type"]).to_s
+
+      def text_block(text) = { type: "text", text: text }
+
+      def blank?(text) = text.strip.empty?
+
+      def scrub(text) = Utf8Scrub.call(text)
+
+      private_class_method :append, :system_blocks, :assistant_blocks, :input_of, :warn_arguments, :tool_result,
+                           :content_blocks, :image_block, :mark_last, :valid_tool_use, :type_of, :text_block, :blank?, :scrub
+    end
+  end
+end

data/lib/samagotchi/llm/api_key.rb

@@ -5,14 +5,23 @@ require_relative "errors"
 module Samagotchi
   module LLM
     # A host's API key: the environment variable its api_key_env: names,
-    # sent as `Authorization: Bearer <key>` on every request LLM::HTTP makes
-    # for the host (llama.cpp started with --api-key, or a provider). The
-    # key itself never goes into a message.
-    ApiKey = Data.define(:env_name, :host, :env) do
+    # sent on every request LLM::HTTP makes for the host (llama.cpp started
+    # with --api-key, or a provider) in the header its +scheme+ names:
+    # :bearer `Authorization: Bearer <key>`, :x_api_key `x-api-key: <key>`
+    # (Anthropic's Messages API, which refuses a request carrying both).
+    # The key itself never goes into a message.
+    ApiKey = Data.define(:env_name, :host, :env, :scheme) do
       # nil for a host without api_key_env: its requests carry no header.
-      def self.for(env_name, host:, env: ENV)
+      # @param scheme [Symbol, nil] one of ApiKey::SCHEMES; nil is :bearer
+      def self.for(env_name, host:, env: ENV, scheme: nil)
         name = env_name.to_s.strip
-        name.empty? ? nil : new(env_name: name, host: host.to_s, env: env)
+        name.empty? ? nil : new(env_name: name, host: host.to_s, env: env, scheme: scheme || :bearer)
+      end
+
+      def initialize(env_name:, host:, env:, scheme: :bearer)
+        raise ArgumentError, "unknown auth scheme #{scheme.inspect}" unless self.class::SCHEMES.include?(scheme)
+
+        super
       end
 
       # What to try after a 401/403 from a host that has no api_key_env.
@@ -20,22 +29,30 @@ module Samagotchi
         "the server may want an API key: put it in an environment variable and name it with api_key_env: on host #{host}"
       end
 
-      # Sets the header, or raises AuthError when the variable is not set.
+      # Sets the scheme's header (exactly one of the two), or raises
+      # AuthError when the variable is not set.
       def authorize(request)
         key = env[env_name].to_s
         raise AuthError.new("#{host}: set #{env_name} (the API key for host #{host})", host: host) if key.strip.empty?
 
-        request["Authorization"] = "Bearer #{key}"
+        if scheme == :x_api_key
+          request.delete("Authorization")
+          request["x-api-key"] = key
+        else
+          request.delete("x-api-key")
+          request["Authorization"] = "Bearer #{key}"
+        end
       end
 
       # What to try after a 401/403 with the key sent.
       def hint = "check #{env_name} (the API key for host #{host})"
 
       # Without the environment: it holds this key and every other secret.
-      def inspect = "#<#{self.class.name} #{env_name} host=#{host}>"
+      def inspect = "#<#{self.class.name} #{env_name} host=#{host}#{" scheme=#{scheme}" unless scheme == :bearer}>"
       alias_method :to_s, :inspect
 
       def pretty_print(printer) = printer.text(inspect)
     end
+    ApiKey::SCHEMES = %i[bearer x_api_key].freeze
   end
 end

data/lib/samagotchi/llm/chat_loop.rb

@@ -49,6 +49,10 @@ module Samagotchi
     class ChatLoop < ModelBackend
       include LLM::StreamDrops
 
+      # The line after an answer an OpenAI-compatible host's content filter
+      # cut (finish_reason content_filter with text): kept, not asked again.
+      FILTERED_MARK = "[cut off by the provider's content filter]"
+
       attr_accessor :adapter
       # The session every request is for; Engine sets it with the adapter.
       # Goes out as a Session-Id header (OpenAIChat#chat).
@@ -147,6 +151,11 @@ module Samagotchi
         conversation = llm_context_view.messages(conversation)
         paired = paired_call_ids(conversation)
         boundary = reasoning_boundary(conversation, since: since, level: reasoning)
+        # The last reply with tool calls keeps its thinking blocks past the
+        # boundary: a run stopped between steps (Stop, the step limit) left
+        # its tool_use last, and Messages wants the thinking before it.
+        last_calls = conversation.rindex { |entry| entry[:role].to_s == "model" }
+        last_calls = nil unless last_calls && !Array(conversation[last_calls][:tool_calls]).empty?
         plan = ImagePlan.new(conversation, vision)
         tool_images = []
         wire = []
@@ -162,6 +171,8 @@ module Samagotchi
           when "model"
             message = assistant_message(entry, paired)
             message[:reasoning_content] = entry[:thinking] if boundary && index >= boundary && thought?(entry)
+            blocks = replay_blocks(entry, paired, keep_thinking: (boundary && index >= boundary) || index == last_calls)
+            message[:anthropic_content] = blocks if blocks
             wire << message
           when "tool_response"
             id = entry[:tool_call_id]
@@ -226,13 +237,20 @@ module Samagotchi
 
       # The turn's ReasoningHistory level (the kernel's turn_settings); drop
       # without settings, and for a +model+ whose host refused it
-      # (#reasoning_history_refused!).
+      # (#reasoning_history_refused!). An adapter that sends its blocks back
+      # (#replays_content?) is floored at turn: the running run's thinking
+      # blocks always go back (a tool loop with thinking needs the last
+      # assistant turn's), whatever the level says.
       def reasoning_history(model = nil)
-        return :drop if model && @reasoning_history_refused&.include?(model)
-
-        @kernel.turn_settings&.reasoning_history || :drop
+        level = model && @reasoning_history_refused&.include?(model) ? :drop : @kernel.turn_settings&.reasoning_history
+        level ||= :drop
+        level == :drop && replays_content? ? :turn : level
       end
 
+      # Whether the adapter sends a model entry's saved blocks back verbatim
+      # (AnthropicMessages); the OpenAI wire doesn't.
+      def replays_content? = @adapter.respond_to?(:replays_content?) && @adapter.replays_content?
+
       # The host refused +model+'s reasoning sent back: send none from now on
       # (this worker's lifetime, as #thinking_refused!).
       def reasoning_history_refused!(model)
@@ -252,12 +270,13 @@ module Samagotchi
       # The turn's thinking level (the kernel's turn_settings).
       def thinking = @kernel.turn_settings.thinking || Thinking::DEFAULT
 
-      # The request fields the thinking level adds (Thinking.chat_fields);
-      # none for a model whose host refused them (#thinking_refused!).
+      # The request fields the thinking level adds, as the adapter's wire
+      # takes them (OpenAIChat#thinking_fields: Thinking.chat_fields); none
+      # for a model whose host refused them (#thinking_refused!).
       def thinking_fields(model = nil)
         return {} if model && (@thinking_refused ||= Set.new).include?(model)
 
-        Thinking.chat_fields(thinking)
+        adapter.thinking_fields(thinking)
       end
 
       # The host refused +model+'s thinking fields: leave them out from now on.
@@ -270,14 +289,26 @@ module Samagotchi
       # under the sampling (a sampling key wins, chat_template_kwargs merges
       # per sub-key), the empty-answer retry's temperature on top, then every
       # null dropped at any depth (a sampling null means "don't send it").
+      # A +model+ whose host refused a sampling field (#sampling_refused!)
+      # gets none of SAMPLING_KEYS.
       def request_options(retry_generation: false, model: nil)
         max_tokens = Samagotchi::Config.max_tokens
         options = deep_merge(thinking_fields(model), sampling)
         options = { max_tokens: max_tokens }.merge(options) if max_tokens
         options = EmptyAnswerRetry.sampling(options) if retry_generation
+        options = options.except(*SAMPLING_KEYS) if model && @sampling_refused&.include?(model)
         deep_compact(options)
       end
 
+      # The fields a sampling refusal (BadRequest#sampling_refused?) drops.
+      SAMPLING_KEYS = %i[temperature top_p top_k].freeze
+
+      # The host refused a sampling field for +model+: send none of
+      # SAMPLING_KEYS from now on (this worker's lifetime, as #thinking_refused!).
+      def sampling_refused!(model)
+        (@sampling_refused ||= Set.new) << model
+      end
+
       def strip_model_thought(text) = @kernel.strip_model_thought(text)
 
       def tool_runner
@@ -323,6 +354,7 @@ module Samagotchi
           message[:turn_id] = entry[:turn_id] if entry[:turn_id]
           message[:turn_start] = true if entry[:turn_start] == true
           message[:thinking] = entry[:thinking] if entry[:thinking].is_a?(String) && !entry[:thinking].empty?
+          message[:anthropic_content] = entry[:anthropic_content] if entry[:anthropic_content].is_a?(Array)
           ToolResponse::SAVED_KEYS.each { |key| message[key] = entry[key] if entry[key] }
           message[TurnNote::RETRY_NUDGE] = true if TurnNote.retry_nudge?(entry)
           marker = TurnNote.empty_answer(entry)
@@ -408,6 +440,24 @@ module Samagotchi
 
       def thought?(entry) = entry[:thinking].is_a?(String) && !entry[:thinking].strip.empty?
 
+      THINKING_BLOCKS = %w[thinking redacted_thinking].freeze
+
+      # A model entry's saved blocks (anthropic_content) to send back
+      # verbatim, for an adapter that replays them: nil when there are none,
+      # for an interrupted entry (its partial blocks have no signature), and
+      # for one with unpaired calls (it goes as flattened text: a tool_use
+      # without its tool_result would fail every later request). Before the
+      # reasoning boundary (+keep_thinking+ false) the thinking blocks are
+      # left out, which removes them only from the front of the history.
+      def replay_blocks(entry, paired, keep_thinking:)
+        blocks = entry[:anthropic_content]
+        return nil unless replays_content? && blocks.is_a?(Array) && !blocks.empty? && !entry[:interrupted]
+        return nil unless Array(entry[:tool_calls]).all? { |call| paired.include?(call[:id]) }
+
+        blocks = blocks.reject { |block| block.is_a?(Hash) && THINKING_BLOCKS.include?((block["type"] || block[:type]).to_s) } unless keep_thinking
+        blocks.empty? ? nil : blocks
+      end
+
       def scrub(text)
         text.encoding == Encoding::UTF_8 && !text.valid_encoding? ? text.scrub("?") : text
       end
@@ -415,6 +465,11 @@ module Samagotchi
       # One turn's state: the conversation, the stream sink and tool
       # activity.
       class Run
+        # Messages' refusal; OpenAI's content filter, a refusal only when
+        # it left no text (else the text stays, marked FILTERED_MARK).
+        REFUSAL = "refusal"
+        FILTERED = "content_filter"
+
         # +start+: where the run a step-limit Continue resumes started (nil:
         # this run starts at the conversation's end).
         def initialize(loop, conversation, on_stream_event, cancel_controller, model_name, pending_input, start: nil)
@@ -457,13 +512,22 @@ module Samagotchi
             end
 
             last_text = @loop.strip_model_thought(response.text)
-            if response.tool_calls.empty?
+            # A provider's refusal (or its content filter) ends the turn here:
+            # tool calls that came with it are not run.
+            @refusal = refusal_of(response, last_text)
+            stopped = @refusal || response.finish_reason.to_s == FILTERED
+            if response.tool_calls.empty? || stopped
+              # A refusal is no answer, never asked again; text it streamed
+              # before is not kept as one. A filtered answer's text stays,
+              # marked as cut by the filter.
+              last_text = "" if @refusal
+              last_text = "#{last_text}\n#{FILTERED_MARK}" if !@refusal && response.finish_reason.to_s == FILTERED
               # Only whitespace is no answer either (as in the native loop).
               empty = last_text.strip.empty?
               # Kept before a merge too: the model answers the merged line
               # knowing what it just said.
               @conversation << with_thinking({ role: "model", content: last_text }, response) unless empty
-              retry_empty = empty &&
+              retry_empty = empty && !stopped &&
                             @empty_retry.retry_empty?(iteration: iteration, cancelled: @cancel_controller&.cancelled?,
                                                       finish_reason: response.finish_reason,
                                                       used_tokens: response.usage&.total_tokens, window_tokens: @window&.tokens)
@@ -495,6 +559,18 @@ module Samagotchi
 
         private
 
+        # A provider's refusal as ModelResult#refusal ({category:} when its
+        # stop_details name one): finish reason refusal, or content_filter
+        # with no visible +text+.
+        def refusal_of(response, text)
+          reason = response.finish_reason.to_s
+          return nil unless reason == REFUSAL || (reason == FILTERED && text.strip.empty?)
+
+          details = response.stop_details
+          category = details["category"] || details[:category] if details.is_a?(Hash)
+          category.to_s.strip.empty? ? {} : { category: category.to_s }
+        end
+
         # The hidden nudge before the next generation (EmptyAnswerRetry),
         # which runs at the retry temperature. Returns true.
         def nudge_empty_answer(iteration, response)
@@ -521,10 +597,14 @@ module Samagotchi
         # The host's reasoning, kept on the model message as +thinking+ for
         # the web turn view's reload (the whole of it, as the live view
         # shows), and sent back to the model as ChatLoop#wire_messages says
-        # (reasoning_history).
+        # (reasoning_history). A wire that sends its blocks back keeps them
+        # as +anthropic_content+ (ChatResponse#provider_content: string
+        # keys, as received, so a resumed session sends the same bytes).
         def with_thinking(message, response)
           reasoning = response.reasoning.to_s
-          reasoning.strip.empty? ? message : message.merge(thinking: reasoning)
+          message = message.merge(thinking: reasoning) unless reasoning.strip.empty?
+          blocks = response.provider_content
+          blocks.is_a?(Array) && !blocks.empty? ? message.merge(anthropic_content: blocks) : message
         end
 
         # One streamed request. Returns [response, nil], or [reason, partial
@@ -551,7 +631,11 @@ module Samagotchi
             begin
               ask.call
             rescue BadRequest => e
-              if refused?(e) && reasoning_sent? then without_reasoning(iteration, e, ask)
+              # A wire that replays its blocks sends them under the turn
+              # floor anyway: asking again without reasoning would resend
+              # the same body.
+              if e.sampling_refused? && sampling_sent?(retry_generation) then without_sampling(iteration, e, ask)
+              elsif refused?(e) && reasoning_sent? && !@loop.replays_content? then without_reasoning(iteration, e, ask)
               elsif thinking_refused?(e) then without_thinking(iteration, e, ask)
               else raise
               end
@@ -613,7 +697,7 @@ module Samagotchi
               event = { type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
                         thinking: reasoning, payload: payload }
               # A tool call streaming: a steer doesn't cut it (Engine#cut_for_steer).
-              tool_call = OpenAIChat.tool_call_delta?(payload)
+              tool_call = @loop.adapter.tool_call_delta?(payload)
               event[:tool_call] = true if tool_call
               streamed_any&.call if !content.to_s.empty? || !reasoning.to_s.empty? || tool_call
               emit(event)
@@ -708,6 +792,21 @@ module Samagotchi
           @without_reasoning = false
         end
 
+        # Whether this step's request sends a sampling field.
+        def sampling_sent?(retry_generation)
+          options = @loop.request_options(retry_generation: retry_generation, model: @model_name)
+          SAMPLING_KEYS.any? { |key| options.key?(key) }
+        end
+
+        # Once per model: asked again without the sampling fields (the
+        # thinking fields stay: an effort level with the empty-answer
+        # retry's temperature keeps thinking on).
+        def without_sampling(iteration, error, ask)
+          @loop.sampling_refused!(@model_name)
+          emit(type: :sampling_refused, iteration: iteration, model: @model_name, detail: error.detail)
+          ask.call
+        end
+
         # Once per model: asked again without the thinking fields.
         def without_thinking(iteration, error, ask)
           @loop.thinking_refused!(@model_name)
@@ -814,7 +913,7 @@ module Samagotchi
           @loop.apply_llm_context!(@conversation, moment: :turn_end, emit: method(:emit)) unless exhausted
           ModelResult.new(text: text, conversation: @loop.plain(@conversation), exhausted: exhausted,
                           tool_activity: @tool_activity, empty_steps: @empty_steps, empty_retries: @empty_retry.attempts,
-                          context_status: @context.display)
+                          context_status: @context.display, refusal: (@refusal unless exhausted))
         end
 
         def emit(event)

data/lib/samagotchi/llm/dialect.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # How a provider's Messages API (`api: anthropic`) departs from
+    # Anthropic's own: a small set of overrides on the standard wire, picked
+    # per host with `dialect:` (HostConfig#dialect, HostEntry#dialect_profile).
+    # A host without one is STANDARD (Anthropic, Splash, a gateway passing
+    # Claude through).
+    #
+    # name: the config value ("standard" for none);
+    # auth: the header the key goes in when the host sets no auth:
+    #   (LLM::ApiKey::SCHEMES);
+    # thinking_display: the `display` sent with adaptive or budget thinking,
+    #   nil for none;
+    # cache_breakpoints: whether chat requests carry cache_control;
+    # session_header: a header that carries the session id (beside
+    #   Session-Id), nil for none.
+    Dialect = Data.define(:name, :auth, :thinking_display, :cache_breakpoints, :session_header) do
+      # The dialect for a `dialect:` name (HostConfig#dialect); STANDARD for
+      # nil or an unknown one.
+      def self.for(name) = self::BY_NAME.fetch(name.to_s, self::STANDARD)
+
+      # A hosts entry's `dialect:` as written: the name, or nil when unset.
+      # An unknown name, or one on a host whose api isn't anthropic, warns
+      # once (naming +where+) and is ignored.
+      # @param api [Symbol, nil] the entry's api
+      # @return [String, nil]
+      def self.parse(value, where, api:)
+        text = value.to_s.strip.downcase
+        return nil if text.empty?
+
+        require_relative "../config"
+
+        unless self::BY_NAME.key?(text)
+          ConfigFile.warn_once "Warning: #{where}: dialect must be one of #{self::BY_NAME.keys.join(", ")}; ignored"
+          return nil
+        end
+        return text if api&.to_sym == :anthropic
+
+        ConfigFile.warn_once "Warning: #{where}: dialect has no effect on api: #{api || "(none)"}; ignored"
+        nil
+      end
+    end
+
+    Dialect::STANDARD = Dialect.new(name: "standard", auth: :x_api_key, thinking_display: "summarized",
+                                    cache_breakpoints: true, session_header: nil)
+    # Fireworks' /v1/messages (docs.fireworks.ai, anthropic-compatibility):
+    # Bearer auth, no `display` in its thinking schema (every object refuses
+    # extra fields; thinking comes back by default), an automatic prefix
+    # cache (no breakpoints), and x-session-affinity to keep a session on
+    # one replica, where its cache is.
+    Dialect::FIREWORKS = Dialect.new(name: "fireworks", auth: :bearer, thinking_display: nil,
+                                     cache_breakpoints: false, session_header: "x-session-affinity")
+    Dialect::BY_NAME = { "standard" => Dialect::STANDARD, "fireworks" => Dialect::FIREWORKS }.freeze
+  end
+end