samagotchi 0.20.0 → 0.22.0

data/lib/samagotchi/bundle_command.rb

@@ -200,6 +200,10 @@ module Samagotchi
     end
 
     # Runs +installer+, prints its summary, then yields the manifest.
+    # Ensures the extracted source dir is cleaned up even if an exception
+    # occurs between installer.run and the block (e.g. summary,
+    # print_hooks_and_plugin). The block (upgrade_conflicts) still sees
+    # the files because cleanup happens after the block returns or raises.
     # @return [Integer] the block's exit status, or 1 after "<failed> failed: …"
     def run_installer(installer, failed:)
       _nd, manifest = installer.run
@@ -208,6 +212,8 @@ module Samagotchi
     rescue Samagotchi::MemoryBundle::Installer::InstallError => e
       @stderr.puts "#{failed} failed: #{e.message}"
       1
+    ensure
+      installer.cleanup_source!
     end
 
     def print_hooks_and_plugin(manifest, plugin: true)

data/lib/samagotchi/bundles/loop-guard/manifest.yml

@@ -1,10 +1,10 @@
 ---
 name: loop-guard
-version: 0.2.2
+version: 0.3.1
 scope: system
 description: "Breaks loops: the same tool call with the same result again and again in one turn is denied with advice (after a few denies the turn stops with a card), and thinking that repeats itself while it streams is cut and the model asked again"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:e62c68d1a2280adf55b150488d0d85bbbc35ffce54dfed387a86adceb85e4d34
+  sha256: sha256:32d04fa3f4b3394e80160dd780615a4a1ddeb3be0f2e327a6497c7766dbd9f11
 requires_chi: ">= 0.6.0"

data/lib/samagotchi/bundles/loop-guard/plugin.rb

@@ -24,6 +24,9 @@
 #   thinking:          the thinking watch (ThinkingWatch::DEFAULTS)
 #     watch: true      false: the tool-call guard only
 #     action: retry    retry (cut, ask again; then stop) | stop | notify
+#     forget_after: 10 good steps (generations with no loop) in a row after a
+#                      cut loop, and the next loop is cut again, not stopped;
+#                      0: never forget, the turn's second loop stops it
 require "digest"
 
 # Sees thinking repeat itself, from the deltas of one generation.
@@ -44,12 +47,19 @@ require "digest"
 #   of 2 or more needs a cycle of distinct sentences (not all alike), and a
 #   period of 1 (one sentence over and over) needs `similarity` +
 #   SAME_MARGIN (0.9 by default: near-identical);
-# - the same sentence max_same times in the generation, in any order.
+# - the same sentence max_same times in the generation, in any order;
+# - a short run: short_run short sentences (under min_words) in a row, at
+#   most short_distinct different ones among the last short_run ("I'll
+#   write it. Go. OK. Writing. Go."). Normal thinking has short sentences
+#   too ("Hmm.", "Fine."), but spread out, or in runs of different ones
+#   (code lines); a sentence of min_words or more ends the run, one with no
+#   letters or digits neither counts nor ends it. Lines inside a ``` code
+#   block are not short sentences.
 # Nothing triggers before min_chars of thinking. O(new chars) per feed.
 class ThinkingWatch
   DEFAULTS = { "watch" => true, "action" => "retry", "min_chars" => 2000, "repeats" => 3, "max_period" => 6,
                "similarity" => 0.5, "min_span_sentences" => 6, "min_span_chars" => 600, "max_same" => 8,
-               "min_words" => 5 }.freeze
+               "min_words" => 5, "short_run" => 24, "short_distinct" => 6, "forget_after" => 10 }.freeze
   ACTIONS = %w[retry stop notify].freeze
   MAX_CARRY = 400
   # One sentence again and again needs this much more alike than a cycle.
@@ -68,10 +78,13 @@ class ThinkingWatch
     out = DEFAULTS.dup
     out["watch"] = !%w[false no off 0].include?(raw["watch"].to_s.downcase) if raw.key?("watch")
     out["action"] = raw["action"].to_s if ACTIONS.include?(raw["action"].to_s)
-    %w[min_chars repeats max_period min_span_sentences min_span_chars max_same min_words].each do |key|
+    %w[min_chars repeats max_period min_span_sentences min_span_chars max_same min_words short_run
+       short_distinct].each do |key|
       number = Integer(raw[key].to_s, exception: false)
       out[key] = number if number&.positive?
     end
+    forget = Integer(raw["forget_after"].to_s, exception: false)
+    out["forget_after"] = forget if forget && forget >= 0
     similarity = Float(raw["similarity"].to_s, exception: false)
     out["similarity"] = similarity if similarity && similarity.positive? && similarity <= 1
     out["repeats"] = 2 if out["repeats"] < 2
@@ -87,12 +100,17 @@ class ThinkingWatch
     @min_span_chars = settings["min_span_chars"]
     @max_same = settings["max_same"]
     @min_words = settings["min_words"]
+    @short_run = settings["short_run"]
+    @short_distinct = settings["short_distinct"]
     @same_similarity = [@similarity + SAME_MARGIN, 0.95].min
     @carry = +""
     @window = [] # the last max_period + 1 sentences
     @run = Array.new(@max_period + 1, 0)
     @run_chars = Array.new(@max_period + 1, 0) # chars of the run's sentences plus the first cycle's
     @counts = Hash.new(0)
+    @short_count = 0  # short sentences in a row
+    @short_window = [] # the last short_run of them, [key, text]
+    @in_code = false
     @thinking_chars = 0
   end
 
@@ -115,7 +133,9 @@ class ThinkingWatch
   # The complete sentences in the carry; the unfinished tail stays.
   def sentences
     parts = @carry.split(SPLIT, -1)
-    @carry = parts.pop.to_s
+    # An empty carry splits into no parts: nil.to_s is frozen, and the next
+    # feed's << would raise (the watch went blind for that generation).
+    @carry = +parts.pop.to_s
     if @carry.length > MAX_CARRY
       cut = @carry.rindex(" ", MAX_CARRY) || MAX_CARRY
       parts << @carry[0, cut]
@@ -125,8 +145,13 @@ class ThinkingWatch
   end
 
   def add(text)
+    if text.strip.start_with?("```")
+      @in_code = !@in_code
+      return nil
+    end
     words = text.downcase.gsub(/[^[:alnum:]]+/, " ").split
-    return nil if words.length < @min_words
+    short = short_loop(text.strip, words) unless @in_code
+    return (short if @thinking_chars >= @min_chars) if words.length < @min_words
 
     key = words.join(" ")
     sentence = Sentence.new(text: text.strip, words: words.map(&:hash).uniq,
@@ -140,6 +165,25 @@ class ThinkingWatch
     cycle || (same >= @max_same ? Loop.new(period: 1, times: same, sentences: [sentence.text], chars: nil) : nil)
   end
 
+  def short_loop(text, words)
+    return nil if words.empty?
+
+    if words.length >= @min_words
+      @short_count = 0
+      @short_window.clear
+      return nil
+    end
+    @short_count += 1
+    @short_window << [words.join(" "), text]
+    @short_window.shift if @short_window.length > @short_run
+    return nil if @short_window.length < @short_run
+
+    distinct = @short_window.uniq(&:first)
+    return nil if distinct.length > @short_distinct
+
+    Loop.new(period: distinct.length, times: @short_count / distinct.length, sentences: distinct.first(3).map(&:last), chars: nil)
+  end
+
   def count(key)
     return @counts[key] += 1 if @counts.key?(key) || @counts.size < MAX_DISTINCT
 
@@ -209,6 +253,7 @@ class Plugin
     return unless @thinking["watch"]
 
     chi.on(:before_generation) do |_event|
+      good_step if @watch
       @watch = ThinkingWatch.new(@thinking)
       @watch_done = false
     end
@@ -242,6 +287,16 @@ class Plugin
     end
   end
 
+  # The generation before this one ended with no loop: a good step. After
+  # forget_after of them in a row the turn's loops are forgotten, so a loop
+  # long after the model recovered is cut and retried, not stopped.
+  def good_step
+    return @good_steps = 0 if @watch_done
+
+    @good_steps += 1
+    @thinking_loops = 0 if @good_steps == @thinking["forget_after"]
+  end
+
   def stop_thinking(ctx, found, what)
     return unless ctx.stop_turn("the model's thinking kept repeating itself (#{what})")
 
@@ -261,6 +316,7 @@ class Plugin
     @denials = 0
     @pending = nil
     @thinking_loops = 0
+    @good_steps = 0
     @watch = nil
   end
 

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.20.0
+version: 0.22.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/cli/parent_wait.rb

@@ -64,10 +64,11 @@ module Samagotchi
         result.text = result.text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
         @reported = true
         ParentReport.report(result, session_id: id, stdout: @stdout, stderr: @stderr, command: command_name,
-                                    json: @json, timeout: timeout)
+                                    json: @json, timeout: timeout, extra: report_extra)
       rescue Interrupt
         if @json
-          @stdout.puts(ParentReport.json_line(ReplyWait::Result.new(status: :canceled), session_id: id))
+          @stdout.puts(ParentReport.json_line(ReplyWait::Result.new(status: :canceled), session_id: id,
+                                                                                        extra: report_extra))
           @stdout.flush
           @reported = true
         end
@@ -77,6 +78,12 @@ module Samagotchi
         error_line("#{command_name}: the session is gone (deleted while waiting)")
         Exit::FAILED
       end
+
+      # More keys for the JSON object: answered_here: false when chi
+      # answer's answer didn't go in (the question was no longer open).
+      def report_extra
+        @answered_here == false ? { answered_here: false } : {}
+      end
     end
   end
 end

data/lib/samagotchi/continue_offer.rb

@@ -41,6 +41,9 @@ module Samagotchi
       # A question was posted since the last close (it may have been
       # answered or superseded meanwhile).
       @asked = false
+      # The text a Continue answer came with ({text:, source:}): it steers
+      # the continue turn (#run_continue_turn).
+      @continue_steer = nil
     end
 
     attr_writer :queue_command
@@ -62,6 +65,7 @@ module Samagotchi
     def drop(origin)
       return unless awaiting?
 
+      @continue_steer = nil
       close("dropped")
       @engine.synchronize_events do
         @turn_flow.drop_offer!
@@ -95,6 +99,10 @@ module Samagotchi
       close(resolved ? "answered" : "dropped") unless awaiting?
       return unless resolved
 
+      # Answered without a turn (a typed /continue no that got there before
+      # the answer's /continue yes): the answer's text steers nothing.
+      @continue_steer = nil unless result.resume
+
       # An offer answered without a turn ("no") is activity: the recap
       # written at the offer (it says the turn stopped) gets rewritten.
       @engine.record_activity unless result.resume
@@ -103,18 +111,26 @@ module Samagotchi
     # The continue offer was answered yes: resume the conversation without a
     # user message, with the iteration limit the offer's turn had. A failure
     # keeps the offer, as the REPL does ("continue prompt preserved"), and
-    # asks again.
+    # asks again. The answer's text is carried into the turn as it begins;
+    # a turn that never began (a raise before it) leaves it to no other.
     def run_continue_turn(command)
       offer = @turn_flow.offer
       close("answered")
-      @turn_flow.before_continue_turn
-      @run_turn.call(nil, continue: true, origin: { client_id: command[:client_id] }.compact,
-                          max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
-        if error
-          open(offer)
-        else
-          after_turn(result, continue: true, no_interrupt: offer[:no_interrupt])
+      steer = @continue_steer
+      @continue_steer = nil
+      begin
+        @engine.steer_next_turn(steer[:text], source: steer[:source]) if steer
+        @turn_flow.before_continue_turn
+        @run_turn.call(nil, continue: true, origin: { client_id: command[:client_id] }.compact,
+                            max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
+          if error
+            open(offer)
+          else
+            after_turn(result, continue: true, no_interrupt: offer[:no_interrupt])
+          end
         end
+      ensure
+        @engine.drop_carried_steers if steer
       end
     end
 
@@ -164,9 +180,18 @@ module Samagotchi
     end
 
     # The question's answer as the /continue line a typed answer would be:
-    # Continue → yes; Stop → no; a text (with Stop, or alone) → no, <text>.
+    # Continue → yes, and a text with it steers the continue turn (from the
+    # parent agent when the answer says so); Stop → no; a text (with Stop,
+    # or alone) → no, <text>.
     def answered(answer, client_id:)
+      # The /continue line takes the text on one line; the steer keeps its
+      # line breaks.
       text = answer[:freeform].to_s.gsub(/\s+/, " ").strip
+      @continue_steer = nil
+      if Array(answer[:selected]).include?(CONTINUE) && !text.empty?
+        @continue_steer = { text: answer[:freeform].to_s.strip,
+                            source: answer[:by] == "parent_agent" ? "parent_agent" : "user" }
+      end
       line = if Array(answer[:selected]).include?(CONTINUE) then "/continue yes"
              elsif text.empty? then "/continue no"
              else "/continue no, #{text}"

data/lib/samagotchi/engine.rb

@@ -325,6 +325,21 @@ module Samagotchi
       @turn_state.steer(text, source: source)
     end
 
+    # Like #steer, for the turn that begins next (a continue turn answered
+    # with a text): it joins that turn at its first boundary. Callable from
+    # any thread; a turn that never begins keeps it for the next one, unless
+    # #drop_carried_steers drops it.
+    # @return [Boolean] whether it was queued (false: blank)
+    def steer_next_turn(text, source:)
+      @turn_state.steer_next_turn(text, source: source)
+    end
+
+    # Drop the #steer_next_turn steers no turn began with (the continue turn
+    # failed before it began), logged; a no-op once a turn took them.
+    def drop_carried_steers
+      log_dropped_steers(@turn_state.drop_carried_steers, "not_begun")
+    end
+
     # The drain a turn's loop gets: the caller's lines (a UI's steering; nil
     # in a --non-interactive run) and the plugin steers. At the after-answer
     # boundary the steers are dropped: the model answered, and a nudge would
@@ -1089,7 +1104,8 @@ module Samagotchi
     # @param limit [Integer, nil] the turn ran out of iterations at this
     #   limit: "exhausted" => true, "limit" => N, so a wait with nobody to
     #   answer the continue offer says so (ReplyWait, ParentReport "limit")
-    def record_last_turn(session, outcome, seconds, origin, limit: nil)
+    # @param event [Hash] the turn's end event (#stop_facts)
+    def record_last_turn(session, outcome, seconds, origin, event, limit: nil)
       client_id = origin.is_a?(Hash) ? origin[:client_id].to_s : ""
       source = if client_id.start_with?("#{Tools::Delegate::CLIENT_PREFIX}:") then "delegate"
                elsif client_id == SessionManager::REMINDER_CLIENT_ID then "reminder"
@@ -1098,9 +1114,23 @@ module Samagotchi
       session.last_turn = { "outcome" => outcome, "ended_at" => Time.now.iso8601(3),
                             "seconds" => seconds.round(1), "origin" => source }
       session.last_turn.merge!("exhausted" => true, "limit" => limit) if limit
+      session.last_turn.merge!(stop_facts(event))
     end
     private :record_last_turn
 
+    # Why a turn stopped, from its end event, for a parent agent's wait
+    # (ReplyWait): a provider error's kind and whether a retry may help, a
+    # cancel's reason and the hook that stopped it. Only what is known.
+    def stop_facts(event)
+      case event&.dig(:type)
+      when :turn_failed then { "error_kind" => event[:error_kind]&.to_s, "retryable" => event[:retryable] }.compact
+      when :turn_canceled
+        { "cancel_reason" => event[:cancellation_reason]&.to_s, "stopped_by" => event[:cancelled_by]&.to_s }.compact
+      else {}
+      end
+    end
+    private :stop_facts
+
     # How every turn ends (completed, canceled, failed): the session gets
     # what the turn kept, goes idle and records the ending, and the end
     # event is announced, as one step of the event log (a snapshot taken
@@ -1118,7 +1148,7 @@ module Samagotchi
         kept, event = yield(seconds)
         replace_session_messages(turn.session, kept) if kept
         turn.session.status = Session::STATUS_IDLE
-        record_last_turn(turn.session, outcome, seconds, turn.origin, limit: exhausted ? turn.limit : nil)
+        record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
       end
       turn.ended = true
@@ -1637,12 +1667,25 @@ module Samagotchi
     def stopped_before_model(turn)
       reason = turn.controller.reason
       end_turn(turn, "canceled") do |seconds|
-        [nil, { type: :turn_canceled, cancellation_reason: reason, duration_ms: (seconds * 1000).round }]
+        [nil, { type: :turn_canceled, cancellation_reason: reason, cancelled_by: cancelled_by(turn),
+                duration_ms: (seconds * 1000).round }]
       end
       LLM::ModelResult.new(text: "", canceled: true, cancellation_reason: reason)
     end
     private :stopped_before_model
 
+    # Who stopped a turn a hook stopped or cut (the controller's detail: the
+    # bundle, or the hook's label), for the UIs' "stopped by loop-guard";
+    # nil for any other cancel.
+    def cancelled_by(turn)
+      return nil unless turn.controller.reason == :hook
+
+      detail = turn.controller.detail
+      by = detail[:by].to_s if detail.is_a?(Hash)
+      by unless by.nil? || by.empty?
+    end
+    private :cancelled_by
+
     # The turn's settings for the kernel (LLM::TurnSettings): vision,
     # sampling and thinking, the thinking resolved before the hooks run.
     # The model name is added in #generate, after the hooks that may switch
@@ -1744,7 +1787,7 @@ module Samagotchi
       end_turn(turn, canceled ? "canceled" : "completed", exhausted: !canceled && result.exhausted?) do |seconds|
         kept = kept_messages(turn, result, seconds)
         if canceled
-          [kept, { type: :turn_canceled, cancellation_reason: result.cancellation_reason,
+          [kept, { type: :turn_canceled, cancellation_reason: result.cancellation_reason, cancelled_by: cancelled_by(turn),
                    duration_ms: (seconds * 1000).round }]
         else
           # For a client that attaches later (session_state_snapshot).

data/lib/samagotchi/events.rb

@@ -13,7 +13,7 @@ module Samagotchi
     TURN_KEPT = %i[turn_completed turn_canceled].freeze
     # The kinds of a running turn's parts (Bridge::TurnAccumulator), which a
     # joining UI replays as live events.
-    PART_KINDS = %w[thinking text tool input steer reminder notice].freeze
+    PART_KINDS = %w[generation thinking text tool input steer reminder notice].freeze
     # Types no Engine emits that a UI handles: the Bridge's stream frames
     # and the web's one synthetic replay event (a prompt merged into the
     # turn, turn_events.js snapshotEvents).

data/lib/samagotchi/llm/chat_loop.rb

@@ -438,7 +438,7 @@ module Samagotchi
           record_context_status(response.usage, window)
           emit(type: :generation_completed, iteration: iteration, content_length: response.text.length,
                thinking_chars: response.reasoning.to_s.length, served_model: response.model,
-               requested_model: @model_name, finish_reason: response.finish_reason)
+               served_provider: response.provider, requested_model: @model_name, finish_reason: response.finish_reason)
           dump_response(response, iteration)
           @loop.fire_hook(:after_generation, { type: :after_generation, iteration: iteration, response: response.text,
                                                messages: AnswerDisplay.strip_all(@conversation).map(&:dup).freeze })

data/lib/samagotchi/llm/errors.rb

@@ -22,6 +22,9 @@ module Samagotchi
     #   ConnectionError  no answer (refused, reset, timeout); RetryExhausted,
     #                    ConnectionRefused
     #   RateLimited      429, with retry_after when the server says
+    #   CreditsHeld      402 "… in-flight requests": credit reserved by other
+    #                    requests; a RateLimited, retried after 20 s
+    #   OutOfCredits     any other 402; never retried
     #   ServerError      5xx or a server's error event mid-stream
     #   AuthError        401/403, or an API key variable that is not set
     #   BadRequest       other 4xx (a context overflow is one, whatever status;
@@ -84,6 +87,24 @@ module Samagotchi
       def default_retryable? = true
     end
 
+    # A 402 that says the account's credit is reserved by requests still in
+    # flight (OpenRouter: "This request would exceed your available credits
+    # given your current in-flight requests"): it clears once they settle,
+    # so it is retried like a 429, after CREDITS_SETTLE_DELAY unless the
+    # server says how long.
+    class CreditsHeld < RateLimited
+      def kind = :credits_held
+
+      def summary = "credits on host #{host} are held by in-flight requests (retry after #{retry_after.to_f.ceil}s)"
+    end
+
+    # Any other 402: the account has run out of credits. Never retried.
+    class OutOfCredits < ProviderError
+      def kind = :credits
+
+      def summary = "out of credits on host #{host}: #{detail}; add credits, then send again"
+    end
+
     class ServerError < ProviderError
       def kind = :server
 
@@ -238,6 +259,10 @@ module Samagotchi
       VISION_UNSUPPORTED_RE = /support image input|image input is not supported|mmproj/i
       # A 400 about the thinking fields chi sent (Thinking.chat_fields).
       REASONING_REFUSED_RE = /reasoning|thinking/i
+      # A 402 about credit held by in-flight requests (see CreditsHeld).
+      CREDITS_HELD_RE = /in-flight requests/i
+      # Seconds to wait before retrying a CreditsHeld without a Retry-After.
+      CREDITS_SETTLE_DELAY = 20.0
       RETRYABLE_SERVER_STATUSES = [500, 502, 503, 504, 529].freeze
 
       module_function
@@ -259,6 +284,12 @@ module Samagotchi
         when 401, 403 then AuthError.new(text, **options)
         when 429 then RateLimited.new(text, retry_after: parse_retry_after(retry_after), **options)
         when 408 then ServerError.new(text, retryable: true, **options)
+        when 402
+          if CREDITS_HELD_RE.match?(message) || CREDITS_HELD_RE.match?(body.to_s)
+            CreditsHeld.new(text, retry_after: parse_retry_after(retry_after) || CREDITS_SETTLE_DELAY, **options)
+          else
+            OutOfCredits.new(text, **options)
+          end
         when 400..499
           tools = TOOLS_UNSUPPORTED_RE.match?(message)
           BadRequest.new(text, tools_unsupported: tools,

data/lib/samagotchi/llm/openai_chat.rb

@@ -6,6 +6,7 @@ require_relative "../config"
 require_relative "../sampling_settings"
 require_relative "errors"
 require_relative "http"
+require_relative "prompt_cache"
 require_relative "usage"
 require_relative "utf8_scrub"
 
@@ -35,10 +36,12 @@ module Samagotchi
     # ([] when none), usage (never nil) and the finish reason.
     # +model+ is the model the server says answered (the body's `model`),
     # which can differ from the one asked for; nil when it says nothing.
+    # +provider+ is the provider that served it (the body's `provider`,
+    # OpenRouter's routing name); nil when the server says nothing.
     # +cut+ is set on the empty response the chat loop makes for a
     # generation a plugin cut (stop_generation): {by:, reason:}.
-    ChatResponse = Data.define(:text, :reasoning, :tool_calls, :usage, :finish_reason, :model, :cut) do
-      def initialize(model: nil, cut: nil, **fields) = super
+    ChatResponse = Data.define(:text, :reasoning, :tool_calls, :usage, :finish_reason, :model, :provider, :cut) do
+      def initialize(model: nil, provider: nil, cut: nil, **fields) = super
     end
 
     # The OpenAI Chat Completions API (llama.cpp's /v1, and any compatible
@@ -119,7 +122,8 @@ module Samagotchi
                session_id: nil)
         body = request_body(messages, tools, model, options)
         request = post_request("#{@base_url}/chat/completions", body, session_id: session_id)
-        log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body) }
+        log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body),
+                       cache: ("on" if PromptCache.marked?(body[:messages])) }
         return chat_once(request, cancel_controller, log_fields) unless @stream
 
         assembly = Assembly.new
@@ -202,7 +206,7 @@ module Samagotchi
       def request_body(messages, tools, model, options)
         body = {
           model: model,
-          messages: Array(messages).map { |message| wire_message(message) },
+          messages: cache_breakpoints(Array(messages).map { |message| wire_message(message) }, model),
           temperature: 0.0,
           stream: @stream
         }
@@ -215,6 +219,16 @@ module Samagotchi
         body.merge(options || {}).compact
       end
 
+      # Prompt-cache breakpoints (PromptCache) on the wire copies, for a
+      # Claude model's chat requests to a remote host: a one-shot side ask
+      # would pay for a cache write nothing reads, and a local model named
+      # after Claude must not get Array content.
+      def cache_breakpoints(messages, model)
+        return messages unless @remote && @purpose == "chat"
+
+        PromptCache.mark(messages, model: model)
+      end
+
       # The body's fields beyond the conversation and the stream, for the
       # log line: "temperature=0.6 presence_penalty=1.5".
       def sampling_summary(body)
@@ -248,7 +262,8 @@ module Samagotchi
         ChatResponse.new(text: OpenAIChat.drop_leading_newlines(message["content"].to_s),
                          reasoning: (message["reasoning_content"] || message["reasoning"]).to_s,
                          tool_calls: calls, usage: Usage.from_payload(body) || Usage.none,
-                         finish_reason: body.dig("choices", 0, "finish_reason"), model: served_model(body))
+                         finish_reason: body.dig("choices", 0, "finish_reason"), model: served_model(body),
+                         provider: self.class.served_provider(body))
       end
 
       # Workaround for Splash 1.0.2/1.1.0, which keeps the "\n\n" the model
@@ -265,6 +280,15 @@ module Samagotchi
 
       def served_model(payload) = self.class.served_model(payload)
 
+      # OpenRouter names the provider that served a request (Baseten,
+      # Fireworks, …) in the body's `provider`; other servers send none.
+      def self.served_provider(payload)
+        provider = payload.is_a?(Hash) ? payload["provider"] : nil
+        provider.is_a?(String) && !provider.strip.empty? ? provider : nil
+      end
+
+      def served_provider(payload) = self.class.served_provider(payload)
+
       # The parsed payload of a `data:` line; nil for blank lines, comments
       # and [DONE]. Error events raise their ProviderError.
       # A 200 whose body is a plain JSON error instead of a stream (OpenRouter
@@ -352,7 +376,7 @@ module Samagotchi
       def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       # Streamed deltas put together: text, reasoning, tool calls by index,
-      # the finish reason, the usage chunk and the served model.
+      # the finish reason, the usage chunk, the served model and provider.
       class Assembly
         # The chunk carries part of a tool call.
         def self.tool_call_delta?(payload)
@@ -367,12 +391,14 @@ module Samagotchi
           @finish_reason = nil
           @usage = nil
           @model = nil
+          @provider = nil
         end
 
         # @return [Array(String, String)] this chunk's content and reasoning
         def add(payload)
           @usage = Usage.from_payload(payload) || @usage if payload.key?("usage")
           @model = OpenAIChat.served_model(payload) || @model
+          @provider = OpenAIChat.served_provider(payload) || @provider
           choice = payload["choices"].is_a?(Array) ? payload["choices"].first : nil
           return ["", ""] unless choice.is_a?(Hash)
 
@@ -392,7 +418,7 @@ module Samagotchi
             ToolCall.new(id: call[:id], name: call[:name].to_s, arguments: OpenAIChat.parse_arguments(call[:arguments]))
           end
           ChatResponse.new(text: @text, reasoning: @reasoning, tool_calls: calls, usage: @usage || Usage.none,
-                           finish_reason: @finish_reason, model: @model)
+                           finish_reason: @finish_reason, model: @model, provider: @provider)
         end
 
         private