samagotchi 0.24.0 → 0.26.0

data/docs/testing.md

@@ -15,6 +15,18 @@ bug) or a broken spec: fix it, or disable that line with the reason (`# rubocop:
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 
+## Worktrees
+
+Each fix or feature gets its own worktree next to the main checkout:
+
+```sh
+script/worktree NAME [-b BRANCH]   # ../samagotchi-NAME off main, branch NAME unless -b; prints the path
+```
+
+It runs `git worktree add ../samagotchi-NAME -b BRANCH main`, then `npm ci --prefer-offline` in it, so
+`npm test` and `npm run e2e` work there right away (Ruby gems and Playwright's browsers are shared: nothing else
+to install). It refuses when the folder or the branch already exists.
+
 ## Integration specs
 
 Examples tagged `:integration` (`spec/integration/`, the "with LLM access" part of `spec/hooks/integration_spec.rb`)

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

@@ -1,10 +1,10 @@
 ---
 name: loop-guard
-version: 0.3.2
+version: 0.3.4
 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:27b135c462d8462313edaa1faa90f3104a1bff3c421d6965e9e71955f347d55b
+  sha256: sha256:a267a325aa134e3d9c57f41d9446c4385a6a1f6bee6267ef127880f8bc4d121f
 requires_chi: ">= 0.6.0"

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

@@ -56,12 +56,20 @@ require "digest"
 #   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.
+#   block are not short sentences;
+# - a low-diversity window: among the last window_sentences sentences of any
+#   length, at most window_distinct different ones (exact, normalized). It
+#   sees a cycle too long for the short run (7-8 short sentences), or one
+#   where a longer sentence keeps ending the run ("Go. OK. I'll write the
+#   spec file now. Go."). Real thinking holds 40+ different sentences in
+#   any 48 (the lowest seen: 42); a loop holds under 10. Lines inside a ```
+#   code block don't count.
 # 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, "short_run" => 24, "short_distinct" => 6, "forget_after" => 10 }.freeze
+               "min_words" => 5, "short_run" => 24, "short_distinct" => 6, "window_sentences" => 48,
+               "window_distinct" => 12, "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.
@@ -69,7 +77,18 @@ class ThinkingWatch
   MAX_DISTINCT = 5000
   SPLIT = /(?<=[.!?])\s+|\n+/
 
-  Loop = Struct.new(:period, :times, :sentences, :chars, keyword_init: true)
+  # +span+: the sentences a loop that isn't a cycle (the short run, the
+  # window) was seen in, +period+ the different ones among them; nil for a
+  # cycle of +period+ sentences seen +times+ times.
+  Loop = Struct.new(:period, :times, :sentences, :chars, :span, keyword_init: true) do
+    # "one sentence ×8", "3 sentences ×3", "12 different sentences in 48".
+    def describe
+      return "one sentence ×#{times}" if period == 1
+      return "#{period} sentences ×#{times}" unless span
+
+      "#{period} different sentences in #{span}"
+    end
+  end
   Sentence = Struct.new(:text, :words, :bigrams, :key, :length, keyword_init: true)
 
   attr_reader :thinking_chars
@@ -81,7 +100,7 @@ class ThinkingWatch
     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 short_run
-       short_distinct].each do |key|
+       short_distinct window_sentences window_distinct].each do |key|
       number = Integer(raw[key].to_s, exception: false)
       out[key] = number if number&.positive?
     end
@@ -104,6 +123,8 @@ class ThinkingWatch
     @min_words = settings["min_words"]
     @short_run = settings["short_run"]
     @short_distinct = settings["short_distinct"]
+    @window_sentences = settings["window_sentences"]
+    @window_distinct = settings["window_distinct"]
     @same_similarity = [@similarity + SAME_MARGIN, 0.95].min
     @carry = +""
     @window = [] # the last max_period + 1 sentences
@@ -112,6 +133,8 @@ class ThinkingWatch
     @counts = Hash.new(0)
     @short_count = 0  # short sentences in a row
     @short_window = [] # the last short_run of them, [key, text]
+    @recent = [] # the last window_sentences sentences, [key, text]
+    @recent_counts = Hash.new(0) # key => times in @recent
     @in_code = false
     @thinking_chars = 0
   end
@@ -153,7 +176,8 @@ class ThinkingWatch
     end
     words = text.downcase.gsub(/[^[:alnum:]]+/, " ").split
     short = short_loop(text.strip, words) unless @in_code
-    return (short if @thinking_chars >= @min_chars) if words.length < @min_words
+    window = window_loop(text.strip, words) unless @in_code
+    return (@thinking_chars >= @min_chars ? short || window : nil) if words.length < @min_words
 
     key = words.join(" ")
     sentence = Sentence.new(text: text.strip, words: words.map(&:hash).uniq,
@@ -164,7 +188,28 @@ class ThinkingWatch
     @window.shift if @window.length > @max_period + 1
     return nil if @thinking_chars < @min_chars
 
-    cycle || (same >= @max_same ? Loop.new(period: 1, times: same, sentences: [sentence.text], chars: nil) : nil)
+    cycle || (same >= @max_same ? Loop.new(period: 1, times: same, sentences: [sentence.text], chars: nil) : nil) || window
+  end
+
+  # The last window_sentences sentences (any length) hold at most
+  # window_distinct different ones: a loop. Its sentences are the most
+  # frequent first.
+  def window_loop(text, words)
+    return nil if words.empty?
+
+    key = words.join(" ")
+    @recent << [key, text]
+    @recent_counts[key] += 1
+    if @recent.length > @window_sentences
+      old, = @recent.shift
+      @recent_counts.delete(old) if (@recent_counts[old] -= 1).zero?
+    end
+    return nil if @recent.length < @window_sentences || @recent_counts.size > @window_distinct
+
+    texts = @recent.to_h # key => its last text
+    top = @recent_counts.sort_by { |_key, n| -n }.first(3).map { |key, _n| texts[key] }
+    Loop.new(period: @recent_counts.size, times: @window_sentences / @recent_counts.size, sentences: top, chars: nil,
+             span: @window_sentences)
   end
 
   def short_loop(text, words)
@@ -183,7 +228,8 @@ class ThinkingWatch
     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)
+    Loop.new(period: distinct.length, times: @short_count / distinct.length, sentences: distinct.first(3).map(&:last), chars: nil,
+             span: @short_window.length)
   end
 
   def count(key)
@@ -274,16 +320,18 @@ class Plugin
     return unless found
 
     @watch_done = true
-    what = "#{found.period == 1 ? "one sentence" : "#{found.period} sentences"} ×#{found.times}, " \
-           "#{(@watch.thinking_chars / 1000.0).round}k chars, #{(event[:elapsed_ms].to_i / 1000.0).round} s"
+    what = "#{found.describe}, #{(@watch.thinking_chars / 1000.0).round}k chars, #{(event[:elapsed_ms].to_i / 1000.0).round} s"
+    # The notices quote the loop's sentences on one line (a short cycle
+    # whole), as the stop card does.
+    quoted = "\"#{cut(found.sentences.first(3).join(" ").gsub(/\s+/, " "))}\", #{what}"
     case @thinking["action"]
     when "notify"
-      ctx.notify("thinking repeats itself (#{what})", level: :warn)
+      ctx.notify("thinking repeats itself (#{quoted})", level: :warn)
     when "retry"
       @thinking_loops += 1
       return stop_thinking(ctx, found, what) if @thinking_loops > 1
 
-      ctx.notify("thinking repeats itself (#{what}): cut", level: :warn) if ctx.stop_generation("its thinking kept repeating itself")
+      ctx.notify("thinking repeats itself (#{quoted}): cut", level: :warn) if ctx.stop_generation("its thinking kept repeating itself")
     else
       stop_thinking(ctx, found, what)
     end

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

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

data/lib/samagotchi/cancellation_controller.rb

@@ -54,6 +54,14 @@ module Samagotchi
       @mutex.synchronize { @detail }
     end
 
+    # Who stopped it when a hook did: the detail's +by+ (the bundle, or the
+    # hook's label); nil for any other cancel.
+    def stopped_by
+      reason, detail = @mutex.synchronize { [@reason, @detail] }
+      by = detail[:by].to_s if reason == :hook && detail.is_a?(Hash)
+      by unless by.nil? || by.empty?
+    end
+
     # Yields a child controller for one generation: it is cancelled when
     # this one is, and #cancel_generation! cancels it alone. Gone after the
     # block.

data/lib/samagotchi/client.rb

@@ -148,6 +148,9 @@ module Samagotchi
         value.empty? ? nil : value
       end
 
+      # llama.cpp's own API: slots (`id_slot`), `cache_prompt`, /props.
+      def native? = @name == :llama_cpp
+
       private
 
       def openai_compatible?
@@ -243,11 +246,15 @@ module Samagotchi
     #   ImagePlan::NATIVE_PLACEHOLDER in the prompt (llama.cpp only)
     # @param sampling    [Hash]          request fields to add (SamplingSettings):
     #   temperature, penalties, …; they can't replace the fields above
+    # @param slot        [Integer, nil]  llama.cpp only: the slot (`id_slot`)
+    #   this request runs on. PromptWarmup's pin, and only while a warm-up
+    #   still runs there: a request pinned to a slot the server has since
+    #   cleared skips its prompt cache and prefills everything again
     # @return [String] the generated text
     def complete(prompt, stop: [], n_predict: nil, model: nil, on_chunk: nil, cancel_controller: nil, on_retry: nil,
-                 images: [], sampling: {})
+                 images: [], sampling: {}, slot: nil)
       images = Array(images)
-      request = { stop: stop, n_predict: n_predict, model: model, sampling: sampling }
+      request = { stop: stop, n_predict: n_predict, model: model, sampling: sampling, slot: slot }
       return stream_completion(LLM::Utf8Scrub.call(prompt), request, on_chunk, cancel_controller, on_retry) if images.empty?
 
       # The media marker is random per server process: a restart between the
@@ -269,6 +276,41 @@ module Samagotchi
 
     OPENAI_API_HINT = "does this host speak the OpenAI API? set `api: openai` on it"
 
+    # What a warm-up (#warm_up) did: the slot it ran on and the server's
+    # counts (tokens reused from the cache, tokens prefilled, prefill ms).
+    Warmup = Data.define(:slot, :cache_n, :prompt_n, :prompt_ms)
+
+    # Prefill +prompt+ and keep it in the server's cache, so the next
+    # request that starts with it only prefills what follows (PromptWarmup:
+    # the turn-end warm-up). llama.cpp's native /completion only; nil on
+    # any other transport. One non-streamed request generating one token
+    # (n_predict 0 does the same on current builds, 1 on every one): no
+    # retries, no first-token limit, no stream events. Errors are raised.
+    # @param slot [Integer, nil] the slot to run on (`id_slot`): the one the
+    #   last request used, which still holds its state
+    # @param images [Array<String>] as #complete's
+    # @return [Warmup, nil]
+    def warm_up(prompt, model: nil, slot: nil, images: [])
+      return nil unless @transport.native?
+
+      images = Array(images)
+      text = LLM::Utf8Scrub.call(images.empty? ? prompt : prompt.gsub(ImagePlan::NATIVE_PLACEHOLDER, media_marker!(model)))
+      payload = { prompt: images.empty? ? text : { prompt_string: text, multimodal_data: images },
+                  n_predict: 1, cache_prompt: true, stream: false }
+      payload[:id_slot] = slot if slot.is_a?(Integer)
+      model_name = @transport.model_for_payload(model)
+      payload[:model] = model_name if model_name
+      uri = completion_uri
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = payload.to_json
+      response = @http.fetch(uri, request, retries: false, log_fields: { model: model, purpose: "warmup" })
+      body = JSON.parse(response.body.to_s)
+      timings = body["timings"].is_a?(Hash) ? body["timings"] : {}
+      Warmup.new(slot: body["id_slot"], cache_n: timings["cache_n"], prompt_n: timings["prompt_n"],
+                 prompt_ms: timings["prompt_ms"]&.round)
+    end
+
     private def stream_completion(prompt, fields, on_chunk, cancel_controller, on_retry)
       uri = completion_uri
       request = Net::HTTP::Post.new(uri)
@@ -456,11 +498,19 @@ module Samagotchi
       URI("#{@scheme}://#{@host}:#{@port}#{@transport.completion_path}")
     end
 
-    def completion_payload(prompt, stop:, n_predict:, model:, sampling: {})
+    def completion_payload(prompt, stop:, n_predict:, model:, sampling: {}, slot: nil)
       payload = { prompt: prompt, stop: stop, stream: true }
+      # A non-positive cap is dropped, which leaves the length to the server
+      # (unbounded): 0 here never means "only process the prompt". The
+      # turn-end warm-up (#warm_up) sends its own payload for that reason.
       payload[@transport.token_limit_key] = n_predict if n_predict && n_predict.to_i.positive?
       model_name = @transport.model_for_payload(model)
       payload[:model] = model_name if model_name
+      if @transport.native?
+        # llama.cpp's default today, sent anyway: chi's next turn relies on it.
+        payload[:cache_prompt] = true
+        payload[:id_slot] = slot if slot.is_a?(Integer)
+      end
       sendable_sampling(sampling).merge(payload)
     end
 

data/lib/samagotchi/command_steps.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require_relative "guardrails/shell_lex"
+
+module Samagotchi
+  # An execute command as the steps a person reads, for the web's tool row
+  # (display only: the guardrails read the command themselves). Built from
+  # ShellLex's tokens and their spans, so each step's text is a slice of the
+  # command as the model wrote it. Rules, in order:
+  #
+  # - a heredoc's body leaves its step's text and becomes its +heredoc+
+  #   ({tag:, lines:}), also one inside a "$(cat <<'EOF' … EOF)" argument;
+  # - steps are split at && || ; | |& & and newlines; a ( … ) subshell stays
+  #   one step; +op+ is the operator before a step (nil for the first);
+  # - a leading "cd X &&" / "cd X;" becomes +cd+ (only the first);
+  # - a pipeline's last "| head …" / "| tail …" becomes the +limit+ of the
+  #   step before it ("head 20", "tail", "head -c 60");
+  # - a lone echo of a marker-wrapped string ("=== x ===", "--- x ---",
+  #   "## x") becomes the +label+ of the next step; a bare marker echo
+  #   ("---", "====", "") only spaces the output and goes;
+  # - anything the parser isn't sure of (a quote or heredoc left open,
+  #   for/while/until/if/case/function bodies, { … } groups, unbalanced
+  #   parentheses) gives nil: the UI then shows the title and the raw
+  #   command.
+  module CommandSteps
+    Step = Data.define(:text, :op, :label, :limit, :heredoc) do
+      def initialize(text:, op: nil, label: nil, limit: nil, heredoc: nil) = super
+
+      def to_h = super.compact
+    end
+
+    Parsed = Data.define(:cd, :steps) do
+      def to_h = { cd: cd, steps: steps.map(&:to_h) }.compact
+    end
+
+    Lex = Guardrails::ShellLex
+
+    SPLIT = ["&&", "||", ";", "|", "|&", "&", "\n"].freeze
+    KEYWORDS = %w[for while until if then elif else fi case esac select do done function { }].freeze
+    LIMITERS = %w[head tail].freeze
+    MARKER = /\A\s*(?:={2,}|-{2,}|#+)\s*(.*?)\s*(?:={2,}|-{2,})?\s*\z/m
+    ECHO_FLAGS = %w[-e -n -en -ne].freeze
+
+    module_function
+
+    # @return [Parsed, nil] nil when the command isn't plain enough to show
+    #   as steps
+    def parse(command)
+      text = command.to_s
+      lexer = Lex::Lexer.new(text)
+      tokens = lexer.tokens.zip(lexer.spans).map { |token, span| [*token, span] }
+      return nil if lexer.unterminated? || tokens.empty?
+
+      bodies = lexer.heredoc_spans.to_h { |doc| [doc[:span], doc[:tag]] }
+      raw = split(tokens)
+      return nil if raw.nil? || raw.empty?
+
+      steps = raw.map { |op, words| step(text, op, words, bodies) }
+      return nil if steps.any?(&:nil?)
+
+      cd, steps = leading_cd(steps, raw)
+      steps = labels(limits(steps))
+      steps.empty? ? nil : Parsed.new(cd: cd, steps: steps)
+    end
+
+    # [[op, word tokens]] split at SPLIT outside parentheses; nil for a
+    # control keyword at a command's start, ;; or unbalanced parentheses.
+    def split(tokens)
+      steps = []
+      op = nil
+      words = []
+      depth = 0
+      tokens.each do |token|
+        kind, value = token
+        if kind == :op && value == "("
+          depth += 1
+          words << token
+        elsif kind == :op && value == ")"
+          depth -= 1
+          return nil if depth.negative?
+
+          words << token
+        elsif kind == :op && depth.zero?
+          return nil unless SPLIT.include?(value)
+
+          if words.empty?
+            op = value unless value == "\n" # "a;\nb" keeps the ;
+          else
+            steps << [steps.empty? ? nil : op, words]
+            op = value
+          end
+          words = []
+        else
+          return nil if keyword?(words, token)
+
+          words << token
+        end
+      end
+      return nil unless depth.zero?
+
+      steps << [steps.empty? ? nil : op, words] unless words.empty?
+      steps
+    end
+
+    # Whether +token+ is a control keyword where a command starts (the
+    # step's first word, or the first after a "(" inside it).
+    def keyword?(words, token)
+      return false unless token[0] == :word
+
+      at_start = words.empty? || words.last[0] == :op
+      at_start && KEYWORDS.include?(token[1])
+    end
+
+    # A Step from its tokens: the text from the first to the last token,
+    # heredoc bodies cut out.
+    def step(text, op, tokens, bodies)
+      body = tokens.find { |t| bodies.key?(t.last) }
+      shown = tokens.reject { |t| bodies.key?(t.last) }
+      from = shown.map { |t| t.last.begin }.min
+      to = shown.map { |t| t.last.end }.max
+      return nil unless from
+
+      slice = text[from...to]
+      heredoc = body && { tag: bodies[body.last], lines: body_lines(text[body.last]) }
+      slice, heredoc = inner_heredoc(slice) unless heredoc
+      Step.new(text: slice.strip, op: op, heredoc: heredoc)
+    end
+
+    # A heredoc inside a $(…) in +slice+ (git commit -m "$(cat <<'EOF' …)"):
+    # the slice with the body cut out, and the heredoc; or the slice as is.
+    def inner_heredoc(slice)
+      return [slice, nil] unless slice.include?("<<")
+
+      at = 0
+      while (open = slice.index("$(", at))
+        lexer = Lex::Lexer.new(slice[(open + 2)..])
+        lexer.tokens
+        doc = lexer.heredoc_spans.first
+        if doc
+          from = open + 2 + doc[:span].begin - 1 # the newline before the body
+          to = open + 2 + doc[:span].end
+          to += 1 if slice[to] == "\n"
+          return [slice[0...from] + slice[to..], { tag: doc[:tag], lines: body_lines(slice[(from + 1)...to]) }]
+        end
+        at = open + 2
+      end
+      [slice, nil]
+    end
+
+    # The body's line count, its terminator line not counted.
+    def body_lines(body_and_tag) = [body_and_tag.to_s.chomp.lines.size - 1, 0].max
+
+    # A first "cd X" step followed by && or ; becomes the cd.
+    def leading_cd(steps, raw)
+      words = raw.first[1]
+      next_op = steps[1]&.op
+      plain = words.size == 2 && words.all? { |t| t[0] == :word } && !words[1][1].include?(Lex::SUBST)
+      return [nil, steps] unless plain && words[0][1] == "cd" && ["&&", ";"].include?(next_op)
+
+      [words[1][1], [steps[1].with(op: nil), *steps.drop(2)]]
+    end
+
+    # A pipeline's last head/tail becomes the limit of the step before it.
+    def limits(steps)
+      steps.each_with_index.with_object([]) do |(step, i), out|
+        limit = step.op == "|" && !out.empty? && out.last.limit.nil? && limit_of(step.text)
+        if limit && !["|", "|&"].include?(steps[i + 1]&.op)
+          out[-1] = out.last.with(limit: limit)
+        else
+          out << step
+        end
+      end
+    end
+
+    # "head 20" for "head -n 20" / "head -20" / "head -n20"; "head -c 60";
+    # "tail +5"; "head" alone. nil for anything else (tail -f, a file).
+    def limit_of(text)
+      words = Lex.lex(text)
+      return nil unless words.all? { |t| t[0] == :word }
+
+      name, *args = words.map { |t| t[1] }
+      return nil unless LIMITERS.include?(name)
+
+      count = case args
+              in [] then nil
+              in [/\A-\d+\z/ => arg] then arg[1..]
+              in [/\A-n\+?\d+\z/ => arg] then arg[2..]
+              in ["-n", /\A\+?\d+\z/ => arg] then arg
+              in ["-c", /\A\d+\z/ => arg] then "-c #{arg}"
+              else return nil
+              end
+      [name, count].compact.join(" ")
+    end
+
+    # A marker echo labels the next step; a bare one goes.
+    # A dropped echo's op goes to the step after it (the link from the
+    # step before).
+    def labels(steps)
+      out = []
+      label = nil
+      op = nil
+      steps.each_with_index do |step, i|
+        marker = marker_label(step.text)
+        if marker.nil? || (!marker.empty? && i == steps.size - 1)
+          step = step.with(label: label, op: op || step.op) if op
+          out << (out.empty? ? step.with(op: nil) : step)
+          label = op = nil
+        else
+          label = marker unless marker.empty?
+          op ||= step.op || "\n"
+        end
+      end
+      out
+    end
+
+    # The label of a lone marker echo ("" for a bare marker or an empty
+    # echo), nil for any other step.
+    def marker_label(text)
+      words = Lex.lex(text)
+      return nil unless words.all? { |t| t[0] == :word && !t[1].include?(Lex::SUBST) }
+
+      name, *args = words.map { |t| t[1] }
+      args.shift while ECHO_FLAGS.include?(args.first)
+      return nil unless name == "echo" && args.size <= 1
+      return "" if args.empty? || args[0].strip.empty?
+
+      match = MARKER.match(args[0])
+      return nil unless match && args[0].strip.match?(/\A(?:={2,}|-{2,}|#)/)
+
+      match[1].strip
+    end
+  end
+end

data/lib/samagotchi/config.rb

@@ -138,6 +138,11 @@ module Samagotchi
       Entry.new(key: "default.max_tokens",       yaml_path: %w[default max_tokens],       type: :integer, default: nil,              expose: %i[env config cli]),
       Entry.new(key: "max_tool_output_chars",    yaml_path: %w[max_tool_output_chars],    type: :integer, default: 10_000,          expose: %i[env config cli]),
 
+      # The turn-end warm-up (PromptWarmup): auto prefills the next turn's
+      # prompt on a local llama.cpp host while the user reads; off never
+      # does. A :string, since YAML reads an unquoted off as false.
+      Entry.new(key: "cache.warmup",             yaml_path: %w[cache warmup],             type: :string, default: "auto",           expose: %i[env config]),
+
       Entry.new(key: "retry.max",                yaml_path: %w[retry max],                type: :integer, default: 5,               expose: %i[env config cli]),
       Entry.new(key: "retry.base_delay",         yaml_path: %w[retry base_delay],         type: :float,   default: 0.5,             expose: %i[env config cli]),
       Entry.new(key: "retry.max_delay",          yaml_path: %w[retry max_delay],          type: :float,   default: 8.0,             expose: %i[env config cli]),
@@ -174,6 +179,8 @@ module Samagotchi
       Entry.new(key: "execute.telemetry_threshold_pct", yaml_path: %w[execute telemetry_threshold_pct], type: :integer, default: 80,     expose: %i[env config cli]),
       # Seconds one execute command may run before it is stopped (Tools::Execute::TIMEOUT_SEC).
       Entry.new(key: "execute.timeout_sec",             yaml_path: %w[execute timeout_sec],             type: :integer, default: 120,    expose: %i[env config cli]),
+      # Whether execute declares its optional description parameter (a few model-written words, a tool row's title).
+      Entry.new(key: "execute.description",             yaml_path: %w[execute description],             type: :bool,    default: true,   expose: %i[env config]),
 
       Entry.new(key: "web.port",                 yaml_path: %w[web port],                 type: :integer, default: 4567,            expose: %i[env config cli]),
       Entry.new(key: "web.host",                 yaml_path: %w[web host],                 type: :string, default: "127.0.0.1",     expose: %i[env config cli]),
@@ -659,15 +666,18 @@ module Samagotchi
     end
 
     # Request keys chi sets itself; a `sampling:` map can't override them.
-    # (Length caps would need their own semantics.)
+    # (Length caps would need their own semantics.) `id_slot` too: pinning
+    # every request to one llama.cpp slot makes a request after an idle
+    # gap skip the server's prompt cache (measured: 0.5 s → 12 s).
     SAMPLING_RESERVED_KEYS = %w[model messages prompt stream stream_options tools tool_choice stop n_predict
-                                max_tokens n parallel_tool_calls response_format cache_prompt].freeze
+                                max_tokens n parallel_tool_calls response_format cache_prompt id_slot].freeze
 
     # A `sampling:` setting (hosts entry or models: entry): request parameters
     # passed through to the provider as written (keys symbolized, nested maps
     # too, so e.g. chat_template_kwargs works). A null value means "don't
-    # send it" (drops chi's own temperature default). Not a map: warns once,
-    # nil. Reserved keys warn once and are dropped. nil when nothing is left.
+    # send it" (a null temperature also keeps the empty-answer retry from
+    # setting one). Not a map: warns once, nil. Reserved keys warn once and
+    # are dropped. nil when nothing is left.
     def sampling_map(value, where)
       return nil if value.nil?
 

data/lib/samagotchi/empty_answer_retry.rb

@@ -13,8 +13,8 @@ module Samagotchi
   # when the retries run out.
   class EmptyAnswerRetry
     MAX = 3
-    # Greedy decoding on a near-identical prompt would likely loop again:
-    # the retry runs at this temperature unless one is configured.
+    # The same (or greedy) decoding on a near-identical prompt would likely
+    # loop again: the retry runs at this temperature unless one is configured.
     TEMPERATURE = 0.6
     # A generation cut at the provider's output cap (finish_reason length)
     # is retried unless the context is this full.