samagotchi 0.23.0 → 0.25.0

data/lib/samagotchi/llm/errors.rb

@@ -25,6 +25,9 @@ module Samagotchi
     #   CreditsHeld      402 "… in-flight requests": credit reserved by other
     #                    requests; a RateLimited, retried after 20 s
     #   OutOfCredits     any other 402; never retried
+    #   OverBudget       402 metadata.reason weight_exceeds_budget: the
+    #                    request alone exceeds the key's budget; an
+    #                    OutOfCredits, 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;
@@ -105,6 +108,15 @@ module Samagotchi
       def summary = "out of credits on host #{host}: #{detail}; add credits, then send again"
     end
 
+    # A 402 whose error.metadata.reason is weight_exceeds_budget (OpenRouter):
+    # this one request's credit reservation is larger than the key's whole
+    # budget, so no amount of waiting lets it through. Never retried, even
+    # when the message reads like the in-flight one.
+    class OverBudget < OutOfCredits
+      def summary = "request too large for the credit budget on host #{host}: #{detail}; " \
+                    "lower max_tokens (default.max_tokens) or raise the key's credit limit"
+    end
+
     class ServerError < ProviderError
       def kind = :server
 
@@ -261,6 +273,9 @@ module Samagotchi
       REASONING_REFUSED_RE = /reasoning|thinking/i
       # A 402 about credit held by in-flight requests (see CreditsHeld).
       CREDITS_HELD_RE = /in-flight requests/i
+      # A 402's error.metadata.reason when the request can never fit the
+      # key's budget (see OverBudget).
+      OVER_BUDGET_REASON = "weight_exceeds_budget"
       # 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
@@ -285,7 +300,9 @@ module Samagotchi
         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)
+          if error_reason(body) == OVER_BUDGET_REASON
+            OverBudget.new(text, **options)
+          elsif 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)
@@ -356,6 +373,14 @@ module Samagotchi
         message.empty? ? "(empty body)" : message[0, 500]
       end
 
+      # error.metadata.reason of a JSON error body (OpenRouter), or nil.
+      def error_reason(body)
+        parsed = parse_json(body.to_s)
+        error = parsed["error"] if parsed.is_a?(Hash)
+        metadata = error["metadata"] if error.is_a?(Hash)
+        metadata["reason"] if metadata.is_a?(Hash)
+      end
+
       # +message+ followed by the upstream provider's name and words from
       # +metadata+ (raw may be text or a JSON error body of its own).
       def with_upstream(message, metadata)

data/lib/samagotchi/llm/openai_chat.rb

@@ -69,6 +69,9 @@ module Samagotchi
             **)
       end
 
+      # true when a streamed +payload+ carries a tool-call delta.
+      def self.tool_call_delta?(payload) = Assembly.tool_call_delta?(payload)
+
       # true when +url+ is OpenRouter's API (openrouter.ai or a subdomain).
       def self.openrouter?(url)
         host = URI(url.to_s).host.to_s.downcase
@@ -237,7 +240,6 @@ module Samagotchi
         body = {
           model: model,
           messages: cache_breakpoints(Array(messages).map { |message| wire_message(message) }, model),
-          temperature: 0.0,
           stream: @stream
         }
         body[:stream_options] = { include_usage: true } if @stream
@@ -246,7 +248,9 @@ module Samagotchi
           body[:tools] = tools
           body[:tool_choice] = "auto"
         end
-        # A configured value replaces chi's own (temperature, max_tokens); nil drops it.
+        # No temperature unless configured: each model runs at its provider's
+        # default (greedy decoding made thinking models loop). A configured
+        # value replaces chi's own (max_tokens); nil drops it.
         body.merge(options || {}).compact
       end
 
@@ -255,13 +259,13 @@ module Samagotchi
       # 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"
+        return PromptCache.without_split(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".
+      # log line: "temperature=0.6 presence_penalty=1.5", nil for none.
       def sampling_summary(body)
         SamplingSettings.log_text(body.except(:model, :messages, :stream, :stream_options, :tools, :tool_choice))
       end

data/lib/samagotchi/llm/prompt_cache.rb

@@ -11,6 +11,12 @@ module Samagotchi
     #   same prefix plus new messages) reads everything up to it.
     # Mid and tail system messages (reminders, turn notes) never take the
     # second mark. Other models' messages pass through untouched.
+    #
+    # A system message whose `cache_split:` says where its stable part ends
+    # (ChatLoop, from SystemPrompt#stable_length) goes as two text parts:
+    # the stable part with the mark, the per-session tail (model, location,
+    # session) without, so a new session reads the stable part from the
+    # cache. `cache_split:` never goes on the wire (#without_split).
     module PromptCache
       CONTROL = { type: "ephemeral" }.freeze
 
@@ -21,16 +27,27 @@ module Samagotchi
 
       # +messages+ (wire messages: symbol keys, content a String or an Array
       # of parts) with the breakpoints set when +model+ is a Claude model;
-      # the given messages as they are otherwise. The marked messages and
-      # parts are copies: the caller's are never changed.
+      # the given messages as they are otherwise (#without_split). The marked
+      # messages and parts are copies: the caller's are never changed.
       # @return [Array<Hash>]
       def mark(messages, model:)
-        return messages unless claude?(model)
+        return without_split(messages) unless claude?(model)
 
         indexes = [system_index(messages), last_index(messages)].compact.uniq
-        return messages if indexes.empty?
+        messages.each_with_index.map do |message, index|
+          next marked(message.except(:cache_split), split: message[:cache_split]) if indexes.include?(index)
 
-        messages.each_with_index.map { |message, index| indexes.include?(index) ? marked(message) : message }
+          message.key?(:cache_split) ? message.except(:cache_split) : message
+        end
+      end
+
+      # +messages+ without the `cache_split:` hints, for a request that sets
+      # no breakpoints.
+      # @return [Array<Hash>]
+      def without_split(messages)
+        return messages unless messages.any? { |message| message.key?(:cache_split) }
+
+        messages.map { |message| message.except(:cache_split) }
       end
 
       # Whether any message in +messages+ carries a breakpoint.
@@ -60,11 +77,19 @@ module Samagotchi
         end
       end
 
-      # A String becomes one text part; an Array gets the mark on its last
-      # text part (the last part when none is text).
-      def marked(message)
+      # A String becomes one text part (two at +split+, the mark on the
+      # first); an Array gets the mark on its last text part (the last part
+      # when none is text).
+      def marked(message, split: nil)
         content = message[:content]
-        return message.merge(content: [{ type: "text", text: content, cache_control: CONTROL }]) if content.is_a?(String)
+        if content.is_a?(String)
+          if split.is_a?(Integer) && split.positive? && split < content.length
+            return message.merge(content: [{ type: "text", text: content[0, split], cache_control: CONTROL },
+                                           { type: "text", text: content[split..] }])
+          end
+
+          return message.merge(content: [{ type: "text", text: content, cache_control: CONTROL }])
+        end
 
         target = content.rindex { |part| part.is_a?(Hash) && (part[:type] || part["type"]).to_s == "text" } ||
                  content.rindex { |part| part.is_a?(Hash) }

data/lib/samagotchi/llm/usage.rb

@@ -5,20 +5,35 @@ require_relative "../token_usage"
 module Samagotchi
   module LLM
     # A response's token counts, never nil: what the server reported
-    # (:server), else zeros (:none).
-    Usage = Data.define(:prompt_tokens, :completion_tokens, :source) do
+    # (:server), else zeros (:none). +cached_tokens+ is the prompt the server
+    # reused from its cache, +cache_write_tokens+ what it wrote to it
+    # (OpenRouter reports those for Anthropic models); 0 when not reported.
+    Usage = Data.define(:prompt_tokens, :completion_tokens, :source, :cached_tokens, :cache_write_tokens) do
       # @return [Usage, nil] nil when the payload carries no counts
       def self.from_payload(payload)
         counts = TokenUsage.from_payload(payload)
         return nil unless counts
 
         new(prompt_tokens: counts.prompt_tokens.to_i, completion_tokens: counts.completion_tokens.to_i,
-            source: :server)
+            source: :server, cached_tokens: counts.cached_tokens.to_i,
+            cache_write_tokens: counts.cache_write_tokens.to_i)
       end
 
       def self.none = new(prompt_tokens: 0, completion_tokens: 0, source: :none)
 
+      def initialize(prompt_tokens:, completion_tokens:, source:, cached_tokens: 0, cache_write_tokens: 0)
+        super
+      end
+
       def total_tokens = prompt_tokens + completion_tokens
+
+      # The request's prompt-cache counts for a :generation_completed event
+      # and the log ({} when the server reported none).
+      def cache_fields
+        return {} unless source == :server
+
+        TokenUsage.cache_fields(prompt: prompt_tokens, cached: cached_tokens, cache_write: cache_write_tokens)
+      end
     end
   end
 end

data/lib/samagotchi/log_subscriber.rb

@@ -106,11 +106,13 @@ module Samagotchi
                                         requested_model: event[:requested_model],
                                         content_length: event[:content_length],
                                         thinking_chars: event[:thinking_chars], finish_reason: event[:finish_reason],
-                                        stopped_by: event[:stopped_by])
+                                        stopped_by: event[:stopped_by], prompt: event[:prompt_tokens],
+                                        cached: event[:cached_tokens], cache_write: event[:cache_write_tokens])
       return unless event[:stopped_by]
 
-      # A plugin cut this generation (stop_generation); the turn goes on.
-      log(:info, :generation_stopped, iteration: event[:iteration], bundle: event[:stopped_by],
+      # A plugin (stop_generation) or a steer (Engine#cut_for_steer, by
+      # "steer") cut this generation; the turn goes on.
+      log(:info, :generation_stopped, iteration: event[:iteration], by: event[:stopped_by],
                                       reason: event[:stop_reason].to_s[0, 200], thinking_chars: event[:thinking_chars], ms: ms)
     end
 

data/lib/samagotchi/plugin/api.rb

@@ -264,8 +264,9 @@ module Samagotchi
 
       # Make +bundle+'s tools in +registry+ the +specs+: its tools not in
       # them go; a new one, or one whose schema or label changed, is
-      # registered (a changed one again, at the end); an unchanged one is
-      # kept as it is. A name another source has is left out. Called on
+      # registered (a changed one again, in its place: Tools::Registry
+      # orders bundle tools by bundle and name); an unchanged one is kept
+      # as it is. A name another source has is left out. Called on
       # the turn thread (Engine#apply_staged_tools!).
       # @return [Hash] {changed: Boolean, skipped: [String] (why)}
       def self.apply_tools(registry, bundle, specs, context)

data/lib/samagotchi/prompt.rb

@@ -4,6 +4,7 @@ require_relative "model_profile"
 require_relative "prompt_literal_guard"
 require_relative "vision_context"
 require_relative "tool_response"
+require_relative "steer"
 
 module Samagotchi
   # Formats a message list into a prompt string ready for the /completion endpoint.
@@ -168,7 +169,9 @@ module Samagotchi
       # peer session), and a turn note carries an error's text: escaped like
       # user content so it can't close its turn.
       role = ESCAPED_KINDS.include?(message[:kind].to_s) ? "user" : message[:role]
-      PromptLiteralGuard.escape(message[:content], profile: profile, role: role)
+      # A steer or merged input is led by a header naming its sender (added
+      # after the escape: the header has no literals to guard).
+      Steer.wire_text(message, PromptLiteralGuard.escape(message[:content], profile: profile, role: role))
     end
 
     private_class_method :image_lines, :format_with_turn_markers, :ends_in_tool_response?, :tool_response_blocks,

data/lib/samagotchi/session_metrics.rb

@@ -16,7 +16,7 @@ module Samagotchi
   # paths and SessionManager background workers.
   #
   # Each finished turn leaves a record (status, timings, model, prompt and
-  # completion tokens, tool calls, iterations, retries); session totals are
+  # completion tokens, tool calls, iterations, retries, cuts); session totals are
   # sums over the records, kept as running counters as records are added, so
   # a worker that stops and wakes again (a new collector) keeps counting:
   # #session_id= loads the records already saved.
@@ -78,10 +78,11 @@ module Samagotchi
       :gen_prompt_max,
       :gen_open,
       # The rest of this generation's server report: the largest cached and
-      # reasoning counts, the last cost, and the server's speeds and decode
+      # reasoning counts (and cache writes), the last cost, and the server's speeds and decode
       # time (llama.cpp's timings); and when its first content, reasoning or
       # tool call chunk came (an estimated speed runs from there).
       :gen_cached_max,
+      :gen_cache_write_max,
       :gen_reasoning_max,
       :gen_cost,
       :gen_decode_tps,
@@ -102,6 +103,7 @@ module Samagotchi
       # tokens of the generations with a speed. The last speeds and where the
       # decode one came from (server / estimate).
       :cached_sum,
+      :cache_write_sum,
       :reasoning_sum,
       :cost_sum,
       :decode_ms_sum,
@@ -110,6 +112,11 @@ module Samagotchi
       :last_prefill_tps,
       :tps_source,
       :retries,
+      # Generations a plugin cut (stop_generation: loop-guard's thinking
+      # watch), not a steer's cut; and ones that ended at the output cap
+      # (finish_reason length). `retries` counts the network's only.
+      :cuts,
+      :capped,
       :model,
       :id,
       :started_at,
@@ -265,6 +272,7 @@ module Samagotchi
         end
       when :generation_completed, :generation_cancelled
         record_served_model(event)
+        count_cut(event)
         record_generation_completed
       when :generation_retrying
         # The retry streams from the start: its counts replace the ones so far.
@@ -364,6 +372,8 @@ module Samagotchi
         iterations_total: totals[:iterations] + (turn&.iteration_count || 0),
         gen_latency_ms: (totals[:gen_ms] + (turn&.gen_latency_accum || 0)).round,
         retries: totals[:retries] + (turn&.retries || 0),
+        cuts: totals[:cuts] + (turn&.cuts || 0),
+        capped: totals[:capped] + (turn&.capped || 0),
         started_at: @started_at,
         last_activity_at: @last_activity_at,
         # From the session's first start (an earlier process's too), to now.
@@ -386,6 +396,7 @@ module Samagotchi
         prompt_sum: add.call(:prompt_sum),
         completion_sum: add.call(:completion_sum),
         cached_sum: add.call(:cached_sum),
+        cache_write_sum: add.call(:cache_write_sum),
         reasoning_sum: add.call(:reasoning_sum),
         cost_sum: add.call(:cost_sum),
         decode_ms_sum: decode_ms.round,
@@ -435,6 +446,7 @@ module Samagotchi
           gen_prompt_max: 0,
           gen_open: false,
           gen_cached_max: 0,
+          gen_cache_write_max: 0,
           gen_reasoning_max: 0,
           generations: 0,
           prompt_last: nil,
@@ -443,11 +455,14 @@ module Samagotchi
           completion_sum: 0,
           token_sources: [],
           cached_sum: 0,
+          cache_write_sum: 0,
           reasoning_sum: 0,
           cost_sum: nil,
           decode_ms_sum: 0,
           decode_tokens_sum: 0,
           retries: 0,
+          cuts: 0,
+          capped: 0,
           model: nil,
           id: event[:turn_id] || SecureRandom.uuid,
           started_at: now.iso8601(3),
@@ -500,6 +515,15 @@ module Samagotchi
       end
     end
 
+    def count_cut(event)
+      @mutex.synchronize do
+        next unless @turn
+
+        @turn.cuts += 1 if event[:stopped_by] && event[:stopped_by].to_s != "steer"
+        @turn.capped += 1 if event[:finish_reason].to_s == "length"
+      end
+    end
+
     def record_generation_completed
       @mutex.synchronize { close_generation if @turn&.gen_open }
     end
@@ -544,6 +568,7 @@ module Samagotchi
     # here: it has no speed. Caller holds the mutex.
     def close_server_report(turn, completion)
       turn.cached_sum += turn.gen_cached_max
+      turn.cache_write_sum += turn.gen_cache_write_max
       turn.reasoning_sum += turn.gen_reasoning_max
       turn.cost_sum = turn.cost_sum.to_f + turn.gen_cost if turn.gen_cost
       turn.last_prefill_tps = turn.gen_prefill_tps.round(1) if turn.gen_prefill_tps
@@ -582,6 +607,7 @@ module Samagotchi
       @turn.gen_had_server = false
       @turn.gen_estimate_sum = 0
       @turn.gen_cached_max = 0
+      @turn.gen_cache_write_max = 0
       @turn.gen_reasoning_max = 0
       @turn.gen_cost = nil
       @turn.gen_decode_tps = @turn.gen_prefill_tps = @turn.gen_decode_ms = nil
@@ -605,7 +631,9 @@ module Samagotchi
         tool_calls: turn.tool_calls,
         tool_errors: turn.tool_errors,
         iterations: turn.iteration_count,
-        retries: turn.retries
+        retries: turn.retries,
+        cuts: turn.cuts,
+        capped: turn.capped
       }.merge(turn_usage_fields(turn))
     end
 
@@ -622,6 +650,7 @@ module Samagotchi
         prefill_tps: turn.last_prefill_tps,
         tps_source: turn.tps_source
       }
+      fields[:cache_write_tokens_sum] = turn.cache_write_sum if turn.cache_write_sum.positive?
       fields.merge!(cost: turn.cost_sum, cost_source: "reported") if turn.cost_sum
       fields
     end
@@ -708,6 +737,7 @@ module Samagotchi
       turn.gen_prompt_max = [turn.gen_prompt_max, usage.prompt_tokens.to_i].max
       turn.gen_completion_max = [turn.gen_completion_max, usage.completion_tokens.to_i].max
       turn.gen_cached_max = [turn.gen_cached_max, usage.cached_tokens.to_i].max
+      turn.gen_cache_write_max = [turn.gen_cache_write_max, usage.cache_write_tokens.to_i].max
       turn.gen_reasoning_max = [turn.gen_reasoning_max, usage.reasoning_tokens.to_i].max
       turn.gen_cost = usage.cost if usage.cost
       if usage.predicted_per_second && usage.predicted_ms
@@ -857,7 +887,8 @@ module Samagotchi
     # (#snapshot adds the running turn). Caller holds the mutex.
     def reset_totals
       @totals = { cancellations: 0, prompt_sum: 0, completion_sum: 0, token_sources: [], iterations: 0,
-                  gen_ms: 0, retries: 0, by_tool: {}, tool_errors: 0, cached_sum: 0, reasoning_sum: 0,
+                  gen_ms: 0, retries: 0, cuts: 0, capped: 0, by_tool: {}, tool_errors: 0, cached_sum: 0, cache_write_sum: 0,
+                  reasoning_sum: 0,
                   cost_sum: 0, decode_ms_sum: 0, decode_tokens_sum: 0, last_decode_tps: nil,
                   last_prefill_tps: nil, tps_source: nil }
     end
@@ -870,7 +901,10 @@ module Samagotchi
       totals[:iterations] += number(record[:iterations])
       totals[:gen_ms] += number(record[:gen_ms])
       totals[:retries] += number(record[:retries])
+      totals[:cuts] += number(record[:cuts])
+      totals[:capped] += number(record[:capped])
       totals[:cached_sum] += number(record[:cached_tokens_sum])
+      totals[:cache_write_sum] += number(record[:cache_write_tokens_sum])
       totals[:reasoning_sum] += number(record[:reasoning_tokens])
       totals[:cost_sum] += number(record[:cost])
       totals[:decode_ms_sum] += number(record[:decode_ms])

data/lib/samagotchi/steer.rb

@@ -10,20 +10,41 @@ module Samagotchi
   #
   # The user's own lines merged into a running turn are marked kind:
   # "input": they are part of that turn, not a turn of their own, so a
-  # reloaded history keeps the turn in one piece.
+  # reloaded history keeps the turn in one piece. A line can be a Line
+  # naming who sent it (a worker's input from chi send, a delegating parent,
+  # a plugin); its input message then carries that source:. The user's own
+  # lines carry none, so their saved bytes are as they always were.
   module Steer
     KIND = "steer"
     INPUT_KIND = "input"
 
+    # A drain item for an input line with its sender (source nil = the user).
+    # A plain String is still a valid item: the user's line.
+    Line = Data.define(:text, :source)
+
+    # The client ids whose input is not the user's own words. Literals, not
+    # SendCommand::CLIENT_ID / Tools::Delegate::CLIENT_PREFIX, so this file
+    # needs no requires (a spec pins them equal).
+    CHI_SEND_CLIENT = "cli:send"
+    DELEGATE_CLIENT_PREFIX = "delegate:"
+    PLUGIN_CLIENT = "plugin"
+
     # What one drain brought: the merged user text (nil when none) and how
-    # many lines made it, and the steers in order.
-    Merge = Struct.new(:content, :count, :steers, keyword_init: true) do
+    # many lines made it, the input messages' text grouped by sender
+    # (consecutive lines from one sender form one group), and the steers in
+    # order.
+    Merge = Struct.new(:content, :count, :inputs, :steers, keyword_init: true) do
       def empty? = content.nil? && steers.empty?
 
-      # The messages it appends: the user's first (marked merged input),
-      # then each steer.
+      # The messages it appends: the merged input first (one message per
+      # sender run, marked kind input, source: when not the user's), then
+      # each steer.
       def messages
-        list = content ? [{ role: "user", kind: INPUT_KIND, content: content }] : []
+        list = inputs.map do |input|
+          message = { role: "user", kind: INPUT_KIND }
+          message[:source] = input[:source] if input[:source]
+          message.merge(content: input[:content])
+        end
         list + steers.map { |steer| Steer.message(**steer) }
       end
 
@@ -36,8 +57,50 @@ module Samagotchi
       end
     end
 
+    # The one line the model reads above a steer or merged input (the wire
+    # only; the saved content stays raw): who sent it, and that it should
+    # follow it or, if it asks for nothing, carry on.
+    HEADER_TAIL = "mid-task. Follow it; if it asks for nothing, carry on with the task.]"
+    SENDERS = {
+      "user" => "from the user",
+      "parent_agent" => "from the parent agent that started this session",
+      "chi_send" => "sent with chi send",
+      "plugin_send" => "sent by a plugin"
+    }.freeze
+    USER_HEADER = "[Steer #{SENDERS["user"]}, #{HEADER_TAIL}".freeze
+
     module_function
 
+    # The saved source of a worker input line from +client_id+: nil for the
+    # user (no client id, the web, an attached TUI, anything unknown).
+    def source_for_client(client_id)
+      id = client_id.to_s
+      if id == CHI_SEND_CLIENT then "chi_send"
+      elsif id.start_with?(DELEGATE_CLIENT_PREFIX) then "parent_agent"
+      elsif id == PLUGIN_CLIENT then "plugin_send"
+      end
+    end
+
+    # The header for a steer or merged input message, else nil. No source
+    # (or "") is the user's; an input with an unknown source too; a steer
+    # with an unknown source is a plugin's (its bundle or hook label).
+    def header(message)
+      kind = (message[:kind] || message["kind"]).to_s
+      return unless [KIND, INPUT_KIND].include?(kind)
+
+      source = (message[:source] || message["source"]).to_s
+      source = "user" if source.empty?
+      sender = SENDERS[source] || (kind == KIND ? "from the #{source} plugin" : SENDERS["user"])
+      "[Steer #{sender}, #{HEADER_TAIL}"
+    end
+
+    # The text a steer or merged input goes out as: its header, a newline,
+    # then +text+ (the message's content by default). Other messages: +text+.
+    def wire_text(message, text = (message[:content] || message["content"]).to_s)
+      header = header(message)
+      header ? "#{header}\n#{text}" : text
+    end
+
     def message(text:, source:)
       { role: "user", kind: KIND, source: source.to_s, content: text.to_s }
     end
@@ -46,6 +109,24 @@ module Samagotchi
       (message[:kind] || message["kind"]).to_s == KIND
     end
 
+    # The sources of a steer a person sent (a continue card's text, from the
+    # user or a parent agent's chi answer), not a plugin's prod.
+    PERSON_SOURCES = %w[user parent_agent].freeze
+
+    # The senders whose message may cut a generation that has only been
+    # thinking (Engine#cut_for_steer): the user (no source), chi send, a
+    # parent agent. A plugin's never does.
+    CUT_SOURCES = ["", "user", "chi_send", "parent_agent"].freeze
+
+    def cuts?(source)
+      CUT_SOURCES.include?(source.to_s)
+    end
+
+    # A steer a person sent: what a recap and a side question keep.
+    def person?(message)
+      steer?(message) && PERSON_SOURCES.include?((message[:source] || message["source"]).to_s)
+    end
+
     # A user message that is a prompt or the user's steering, not a steer:
     # what "the last prompt" and "user turns" count.
     def prompt?(message)
@@ -105,8 +186,22 @@ module Samagotchi
         text = (item[:text] || item["text"]).to_s.strip
         { source: (item[:source] || item["source"]).to_s, text: text } unless text.empty?
       end
-      content = lines.map { |line| line.to_s.strip }.reject(&:empty?).join("\n\n")
-      Merge.new(content: content.empty? ? nil : content, count: content.empty? ? 0 : lines.length, steers: steers)
+      inputs = input_groups(lines)
+      content = inputs.map { |input| input[:content] }.join("\n\n")
+      Merge.new(content: content.empty? ? nil : content, count: content.empty? ? 0 : lines.length,
+                inputs: inputs, steers: steers)
+    end
+
+    # Non-blank input lines as [{content:, source:}], one per run of lines
+    # from the same sender.
+    def input_groups(lines)
+      pairs = lines.filter_map do |line|
+        text = (line.is_a?(Line) ? line.text : line).to_s.strip
+        [text, line.is_a?(Line) ? line.source : nil] unless text.empty?
+      end
+      pairs.chunk_while { |a, b| a[1] == b[1] }.map do |run|
+        { content: run.map(&:first).join("\n\n"), source: run.first[1] }
+      end
     end
   end
 end

data/lib/samagotchi/system_prompt.rb

@@ -14,8 +14,9 @@ module Samagotchi
   # The system prompt an Engine gives its model: the base prompt (tool
   # declarations and call syntax for the raw-prompt loop, none for the chat
   # loop, the shared guidance) and around it the thinking token, rg
-  # guidance, AGENT.md, where the session runs, the memory indexes, the
-  # identity memory and the preloaded memories.
+  # guidance, the identity memory, the preloaded memories, AGENT.md, the
+  # memory indexes and, last, the model, where the session runs and the
+  # session (#system_prompt_with_index has the order and why).
   #
   # What changes during a session (the profile after a model switch, the
   # tools a plugin replaces, the attached session, the thinking level) is
@@ -77,8 +78,16 @@ module Samagotchi
     # indexes and memories again (a model or profile switch, changed tools).
     def reset!
       @built = nil
+      @stable_lengths = nil
     end
 
+    # The length of +prompt+'s stable part when it is a chat prompt #build
+    # made: everything before the model, location and session lines, which
+    # a remote prompt cache can keep for every session (PromptCache). nil
+    # for any other text, or a prompt without those lines.
+    # @return [Integer, nil]
+    def stable_length(prompt) = @stable_lengths&.[](prompt)
+
     # The base prompt (specs, plugins' declarations), with Gemma's tool
     # declarations at its end as #build has them.
     def base(chat: false, thinking: nil)
@@ -186,7 +195,7 @@ module Samagotchi
           6. Use write for full-file rewrites or creating new files.
 
         Memory convention:
-          Project scope: one folder per git repository, shared by its worktrees and subdirectories (path shown above)
+          Project scope: one folder per git repository, shared by its worktrees and subdirectories (its path is on the "Project memories folder:" line below)
           System scope:  ~/.config/samagotchi/memories/ (cross-project)
           memory_read accepts optional scope (project|system).
           memory_write requires explicit scope and entry name.
@@ -229,16 +238,28 @@ module Samagotchi
     # @param chat [Boolean] no Gemma thinking token (the chat API's template
     #   decides about thinking)
     # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
+    #
+    # Ordered for the servers' prompt caches (they reuse only an exact token
+    # prefix): what every session shares first, what changes least before
+    # what changes more, and the per-session lines last. The global parts
+    # (identity, preloads) come before the project's AGENT.md, the memory
+    # indexes (a memory write changes them) after both; the model, the
+    # location and the session close the prompt (Gemma's tool declarations
+    # still follow them).
     def system_prompt_with_index(base, chat: false, thinking: nil)
-      project_index = read_memory_index("project")
-      system_index = read_memory_index("system")
-      project_description = project_specific_description
       thinking_token = chat ? "" : Thinking.native(thinking || turn_thinking, profile).system_token
       memory_sections = [
-        "Project memories:\n#{project_index}",
-        "System memories:\n#{system_index}"
+        "Project memories:\n#{read_memory_index("project")}",
+        "System memories:\n#{read_memory_index("system")}"
       ].join("\n\n")
-      prompt = [thinking_token + base, rg_guidance, project_description, project_location, current_model, current_session, memory_sections, system_identity_section, explicit_memory_section].compact.join("\n")
+      stable = [thinking_token + base, rg_guidance, system_identity_section, explicit_memory_section,
+                project_specific_description, memory_sections]
+      stable_text = stable.compact.join("\n")
+      volatile = [current_model, project_location, current_session].compact
+      return with_tail_declarations(stable_text, chat: chat) if volatile.empty?
+
+      prompt = "#{stable_text}\n#{volatile.join("\n")}"
+      (@stable_lengths ||= {})[prompt] = stable_text.length + 1 if chat
       with_tail_declarations(prompt, chat: chat)
     end