samagotchi 0.2.0 → 0.3.0

data/lib/samagotchi/hooks/registry.rb

@@ -15,14 +15,15 @@ module Samagotchi
       takes_settings ? klass.new(settings.is_a?(Hash) ? settings : {}) : klass.new
     end
 
-    # What a hook can do beyond reading its event: the Engine's three
+    # What a hook can do beyond reading its event: the Engine's
     # callables, each given the hook's label. +notify+ takes
     # (text:, level:, hook:) and shows one line to the user; +ask_user+
     # takes (question:, options:, header:, allow_freeform:, hook:) and
     # returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
-    # cancels the running turn (true when it did). A registry without one
-    # gives hooks no-op helpers.
-    Runtime = Struct.new(:notify, :ask_user, :stop_turn, keyword_init: true)
+    # cancels the running turn (true when it did); +steer+ takes (text:,
+    # hook:) and puts the text into the running turn (Engine#steer, true
+    # when queued). A registry without one gives hooks no-op helpers.
+    Runtime = Struct.new(:notify, :ask_user, :stop_turn, :steer, keyword_init: true)
 
     # A thread-safe registry for named hook callbacks.
     #
@@ -172,6 +173,12 @@ module Samagotchi
       #   event[:stop_turn].call(reason) -> true when the turn was cancelled;
       #     in a before_tool_call event it also denies the call; from
       #     after_turn / session_end it does nothing (false)
+      #   event[:steer].call(text) -> true when the text was queued for the
+      #     running turn's next boundary (its own user message, source: the
+      #     hook's bundle); from after_turn / session_end false
+      # and after_turn's fire site adds one more (AnswerDisplay):
+      #   event[:present].call { |text| new_text } -> the answer's display
+      #     text after the call (chained in hook order), nil without an answer
       #
       # @param name [Symbol] the hook name to fire
       # @param event [Hash] the event payload (may be mutated by hooks)
@@ -191,6 +198,13 @@ module Samagotchi
         end
       end
 
+      # Whether a #fire of +name+ would call any hook.
+      # @param name [Symbol]
+      # @return [Boolean]
+      def any?(name)
+        !ordered_procs(name).empty?
+      end
+
       # Like #fire, and yields the event after each hook (a raising one
       # too), so the caller can fold what that hook did before the next one
       # runs (the guardrail gate keeps a deny sticky this way).
@@ -235,7 +249,7 @@ module Samagotchi
         end
       end
 
-      # The three helpers, once per fire; a fire site's own keys stay.
+      # The helpers, once per fire; a fire site's own keys stay.
       def with_runtime(event)
         return unless event.is_a?(Hash)
 
@@ -255,6 +269,11 @@ module Samagotchi
           end
           @runtime&.stop_turn&.call(reason: reason.to_s, hook: event[:hook]) ? true : false
         }
+        event[:steer] ||= lambda { |text|
+          next false if TURN_OVER_EVENTS.include?(event[:type])
+
+          @runtime&.steer&.call(text: text.to_s, hook: event[:hook]) ? true : false
+        }
       end
     end
   end

data/lib/samagotchi/host_registry.rb

@@ -28,9 +28,10 @@ module Samagotchi
     # come from it); api_key_env: the variable holding the host's API key;
     # profile: the configured prompt profile name, if any;
     # first_token_timeout: the configured first-token limit (see #first_token_limit);
-    # vision: the configured true/false (VisionSupport), nil when unset.
+    # vision: the configured true/false (VisionSupport), nil when unset;
+    # sampling: the configured request parameters (SamplingSettings), nil when unset.
     HostEntry = Struct.new(:name, :host, :port, :transport, :client, :api, :scheme, :url, :api_key_env, :profile,
-                           :first_token_timeout, :vision, keyword_init: true) do
+                           :first_token_timeout, :vision, :sampling, keyword_init: true) do
       # Talks the OpenAI chat API (the chat loop); nil and raw apis use the
       # raw-prompt loop.
       def chat? = api == :openai
@@ -86,7 +87,7 @@ module Samagotchi
         entry = HostEntry.new(name: key.to_s.downcase, host: cfg[:host], port: cfg[:port].to_i, transport: transport,
                               api: cfg[:api]&.to_sym, scheme: cfg[:scheme], url: cfg[:url], api_key_env: cfg[:api_key_env],
                               profile: cfg[:profile], first_token_timeout: cfg[:first_token_timeout],
-                              vision: cfg[:vision])
+                              vision: cfg[:vision], sampling: cfg[:sampling])
         entry.client = Client.new(host: cfg[:host], port: cfg[:port], transport: transport, scheme: cfg[:scheme],
                                   first_token_timeout: entry.first_token_limit, name: entry.name)
         @entries[entry.name] = entry

data/lib/samagotchi/idle_recap.rb

@@ -7,6 +7,7 @@ require "time"
 
 require_relative "idle_client"
 require_relative "output_formatter"
+require_relative "steer"
 require_relative "recap_store"
 require_relative "log"
 
@@ -60,6 +61,9 @@ module Samagotchi
 
           case message["role"]
           when "user"
+            # A plugin's steer is a prod to the model, not what the user said.
+            next nil if Steer.steer?(message)
+
             # An image is a line naming it (refs only, never its bytes).
             [message["content"].to_s, *image_lines(message["images"])].reject(&:empty?).join("\n")
           when "model", "assistant"
@@ -411,7 +415,7 @@ module Samagotchi
       parsed = safe_parse(@engine.messages_json_for_recap)
       return :too_short if parsed.nil?
 
-      user_turns = parsed.count { |message| message.is_a?(Hash) && message["role"] == "user" }
+      user_turns = parsed.count { |message| Steer.prompt?(message) }
       if parsed.empty? || user_turns < @min_user_turns
         drop_stale(parsed)
         return :too_short

data/lib/samagotchi/kernel_loop.rb

@@ -10,13 +10,16 @@ require_relative "prompt_literal_guard"
 require_relative "client"
 require_relative "llm/errors"
 require_relative "log"
+require_relative "empty_answer_retry"
 require_relative "hooks"
 require_relative "pending_input_queue"
+require_relative "steer"
 require_relative "thought_stream_splitter"
 require_relative "tools/builtins"
 require_relative "muted_memories"
 require_relative "tool_activity"
 require_relative "tool_runner"
+require_relative "answer_display"
 
 module Samagotchi
   # The KernelLoop drives the model ↔ tool interaction cycle.
@@ -173,6 +176,9 @@ module Samagotchi
     # The turn's VisionContext (images: capability, files, limits), set by
     # the Engine per turn; nil sends no images (placeholders instead).
     attr_accessor :vision
+    # The turn's request parameters (SamplingSettings.for), set by the Engine
+    # per turn; empty or nil sends none.
+    attr_accessor :sampling
     # Tools::Peers (or the Engine's live view of it): the session
     # list_sessions and send_note speak for; nil outside a session.
     attr_accessor :peers
@@ -206,6 +212,9 @@ module Samagotchi
       tool_activity = []
       qwen_recovery_attempts = 0
       qwen_partial_tool_call = nil
+      empty_retries = 0
+      empty_retry_limit = EmptyAnswerRetry.limit
+      @retry_generation = false
       context_status = nil
       stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
       partial_assistant_buffer = +""
@@ -299,7 +308,7 @@ module Samagotchi
         # Fire :after_generation hook (after LLM returns, before tool parse),
         # with a read-only copy of the conversation as sent.
         after_gen_event = { type: :after_generation, iteration: iteration_index + 1, response: response,
-                            messages: conversation.map(&:dup).freeze }
+                            messages: AnswerDisplay.strip_all(conversation).map(&:dup).freeze }
         fire_hook(:after_generation, after_gen_event) if @hooks
         conversation << { role: "model", content: response }
 
@@ -322,7 +331,25 @@ module Samagotchi
 
           pending_tool_calls = false
           answer = -> { PromptLiteralGuard.restore(strip_thought_blocks(response), profile: @profile) }
-          unless inject_pending_input!(conversation, pending_input, on_stream_event, iteration_index + 1, cancel_controller, answer: answer)
+          empty = strip_thought_blocks(response.to_s).strip.empty?
+          retry_empty = empty && empty_retries < empty_retry_limit && !cancel_controller&.cancelled?
+          # The empty generation goes (its thinking would be sent again and
+          # prime the same loop); an empty answer that will be retried is no
+          # answer site, so a plugin's steer joins the retry.
+          conversation.pop if retry_empty
+          unless inject_pending_input!(conversation, pending_input, on_stream_event, iteration_index + 1, cancel_controller,
+                                       answer: retry_empty ? nil : answer)
+            if retry_empty
+              empty_retries += 1
+              @retry_generation = true
+              emit_stream_event(on_stream_event, type: :empty_answer_retry, iteration: iteration_index + 1,
+                                                 attempt: empty_retries, of: empty_retry_limit,
+                                                 thinking_chars: thinking_chars(response.to_s, streamed_thinking))
+              conversation << TurnNote.empty_retry
+              next
+            end
+            # The Engine's TurnNote.empty says it all: the spent nudge goes.
+            drop_last_empty_retry!(conversation) if empty && empty_retries.positive?
             break
           end
           # Queued steering keeps the turn going: loop again so the model
@@ -437,6 +464,8 @@ module Samagotchi
     # append them as ONE merged user message at the conversation tail and emit
     # :pending_input_merged. Tail-append only: head mutation would invalidate
     # the server-side prefix KV cache. Returns true when a message was injected.
+    # A plugin's steers (Steer) follow the user's message, each its own
+    # message; after an answer the Engine's drain has already dropped them.
     # After a cancel the input stays queued: it runs as the next turn instead
     # of dying with this one. +answer+ (a proc, called only on a merge) is the
     # answer the merge follows: the UIs show it, the turn summary has only the
@@ -445,24 +474,16 @@ module Samagotchi
       return false unless pending_input
       return false if cancel_controller&.cancelled?
 
-      lines = begin
-        pending_input.call
-      rescue StandardError
-        nil
-      end
-      return false if lines.nil? || lines.empty?
-
-      content = lines.map { |line| line.to_s.strip }.reject(&:empty?).join("\n\n")
-      return false if content.empty?
+      merge = Steer.merge(Steer.drain(pending_input, at_answer: !answer.nil?))
+      return false if merge.empty?
 
       answer = answer.call.to_s if answer
-      conversation << { role: "user", content: content }
+      conversation.concat(merge.messages)
       emit_stream_event(
         on_stream_event,
         type: :pending_input_merged,
         iteration: iteration,
-        count: lines.length,
-        content: content,
+        **merge.event_fields,
         answer: answer.to_s.strip.empty? ? nil : answer
       )
       true
@@ -524,6 +545,9 @@ module Samagotchi
       kwargs[:n_predict] = n_predict if n_predict && client_supports_keyword?(:n_predict)
       resolved_model_name = completion_model_name(model_name)
       kwargs[:model] = resolved_model_name if resolved_model_name && client_supports_keyword?(:model)
+      sampling = @retry_generation ? EmptyAnswerRetry.sampling(@sampling) : @sampling
+      @retry_generation = false
+      kwargs[:sampling] = sampling if sampling && !sampling.empty? && client_supports_keyword?(:sampling)
       kwargs
     end
 
@@ -862,7 +886,9 @@ module Samagotchi
     def sanitize_history(messages)
       messages.map do |m|
         if m[:role] == "model"
-          { role: m[:role], content: strip_thought_blocks(m[:content].to_s) }
+          # `display` rides along so the stored conversation keeps it; the
+          # prompt formatter never reads it (AnswerDisplay).
+          { role: m[:role], content: strip_thought_blocks(m[:content].to_s), display: m[:display] }.compact
         else
           m.dup
         end
@@ -882,6 +908,12 @@ module Samagotchi
       messages.map(&:dup)
     end
 
+    def drop_last_empty_retry!(conversation)
+      nudge = TurnNote.empty_retry
+      index = conversation.rindex { |entry| entry[:kind] == nudge[:kind] && entry[:content] == nudge[:content] }
+      conversation.delete_at(index) if index
+    end
+
     def last_model_content(conversation)
       message = conversation.reverse.find { |entry| entry[:role] == "model" }
       message ? message[:content].to_s : ""

data/lib/samagotchi/llm/chat_loop.rb

@@ -8,12 +8,15 @@ require_relative "usage"
 require_relative "openai_chat"
 require_relative "native_tool_normalizer"
 require_relative "../kernel_loop"
+require_relative "../answer_display"
 require_relative "../context_window"
 require_relative "../context_note"
 require_relative "../tool_runner"
 require_relative "../tool_declarations"
 require_relative "../vision_context"
 require_relative "../log"
+require_relative "../empty_answer_retry"
+require_relative "../turn_note"
 
 module Samagotchi
   module LLM
@@ -131,6 +134,11 @@ module Samagotchi
         @kernel.respond_to?(:vision) ? @kernel.vision : nil
       end
 
+      # The turn's request parameters (the Engine sets them on the kernel).
+      def sampling
+        @kernel.respond_to?(:sampling) ? @kernel.sampling || {} : {}
+      end
+
       def strip_model_thought(text)
         @kernel.respond_to?(:strip_model_thought) ? @kernel.strip_model_thought(text) : text
       end
@@ -183,6 +191,7 @@ module Samagotchi
           message[:thinking] = entry[:thinking] if entry[:thinking].is_a?(String) && !entry[:thinking].empty?
           message[:tool_params] = entry[:tool_params] if entry[:tool_params]
           message[:tool_labels] = entry[:tool_labels] if entry[:tool_labels]
+          message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
           message
         end
@@ -268,6 +277,8 @@ module Samagotchi
           # usage: the text, and each image's estimate (not its base64).
           @prompt_text = conversation.sum("") { |entry| entry[:content].to_s }
           @image_tokens = ImagePlan.estimated_tokens(conversation)
+          @empty_retries = 0
+          @empty_retry_limit = EmptyAnswerRetry.limit
         end
 
         EMPTY_ANSWER = "(the model returned an empty answer)"
@@ -288,7 +299,12 @@ module Samagotchi
               # 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 last_text.empty?
-              next if inject_pending_input(iteration, answer: last_text)
+              retry_empty = last_text.empty? && retry_empty_answer?(iteration, response)
+              # An empty answer that will be retried is no answer site: a
+              # plugin's steer joins the retry instead of being dropped, and
+              # queued input (a user's line, a steer) goes in place of the nudge.
+              next if inject_pending_input(iteration, answer: retry_empty ? nil : last_text)
+              next if retry_empty && nudge_empty_answer(iteration, response)
 
               # Shown, not saved: an empty answer (content "" + stop, seen from
               # a remote host) would otherwise end the turn with nothing.
@@ -310,6 +326,31 @@ module Samagotchi
 
         private
 
+        # A retry is left, and the answer wasn't cut short by a full context
+        # (a length stop while thinking is retried: a thinking loop cut by
+        # the provider's output cap, not a full window).
+        def retry_empty_answer?(iteration, response)
+          return false if @empty_retries >= @empty_retry_limit || @cancel_controller&.cancelled?
+
+          if response.finish_reason.to_s == "length" &&
+             EmptyAnswerRetry.context_full?(response.usage&.total_tokens, @window&.tokens)
+            Log.info(:turn, "empty_answer_not_retried", iteration: iteration, why: "context full")
+            return false
+          end
+          true
+        end
+
+        # The hidden nudge before the next generation (EmptyAnswerRetry),
+        # which runs at the retry temperature. Returns true.
+        def nudge_empty_answer(iteration, response)
+          @empty_retries += 1
+          @retry_generation = true
+          emit(type: :empty_answer_retry, iteration: iteration, attempt: @empty_retries, of: @empty_retry_limit,
+               finish_reason: response.finish_reason, thinking_chars: response.reasoning.to_s.length)
+          @conversation << TurnNote.empty_retry
+          true
+        end
+
         # 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). Only saved: #assistant_message builds the wire message from
@@ -322,14 +363,17 @@ module Samagotchi
         # One streamed request. Returns [response, nil], or [reason, partial
         # text] when it was cancelled.
         def generate(iteration)
-          window = @loop.context_window(@model_name)
+          window = @window = @loop.context_window(@model_name)
+          options = @loop.sampling
+          options = EmptyAnswerRetry.sampling(options) if @retry_generation
+          @retry_generation = false
           emit(type: :generation_started, iteration: iteration, context_window_tokens: window&.tokens,
                context_window_source: window&.source)
           @loop.fire_hook(:before_generation, { type: :before_generation, iteration: iteration })
           streamed = +""
           response = @loop.adapter.chat(
             messages: @loop.wire_messages(@conversation), tools: @loop.tool_definitions, model: @model_name,
-            cancel_controller: @cancel_controller, session_id: @loop.session_id,
+            cancel_controller: @cancel_controller, session_id: @loop.session_id, options: options,
             on_delta: lambda { |content:, reasoning:, payload:|
               streamed << content
               emit(type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
@@ -340,10 +384,10 @@ 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)
+               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: @conversation.map(&:dup).freeze })
+                                               messages: AnswerDisplay.strip_all(@conversation).map(&:dup).freeze })
           [response, nil]
         rescue RequestCancelled => e
           [e.reason, streamed]
@@ -390,26 +434,21 @@ module Samagotchi
           emit(type: :tool_dispatch_completed, iteration: iteration, call_count: tool_calls.length)
         end
 
-        # Queued steering joins the conversation as one user message.
-        # Returns true when there was any. After a cancel it stays queued, so
-        # it runs as the next turn instead of dying with this one. +answer+ is
-        # the answer the merge follows, for the UIs.
+        # Queued steering joins the conversation as one user message, a
+        # plugin's steers each as its own after it (Steer). Returns true when
+        # there was any. After a cancel it stays queued, so it runs as the
+        # next turn instead of dying with this one. +answer+ is the answer the
+        # merge follows, for the UIs; given, the drain is told it is the
+        # after-answer site (plugin steers are dropped there).
         def inject_pending_input(iteration, answer: nil)
           return false unless @pending_input
           return false if @cancel_controller&.cancelled?
 
-          lines = begin
-            @pending_input.call
-          rescue StandardError
-            nil
-          end
-          return false if lines.nil? || lines.empty?
-
-          content = lines.map { |line| line.to_s.strip }.reject(&:empty?).join("\n\n")
-          return false if content.empty?
+          merge = Steer.merge(Steer.drain(@pending_input, at_answer: !answer.nil?))
+          return false if merge.empty?
 
-          @conversation << { role: "user", content: content }
-          emit(type: :pending_input_merged, iteration: iteration, count: lines.length, content: content,
+          @conversation.concat(merge.messages)
+          emit(type: :pending_input_merged, iteration: iteration, **merge.event_fields,
                answer: answer.to_s.empty? ? nil : answer)
           true
         end

data/lib/samagotchi/llm/errors.rb

@@ -19,7 +19,8 @@ module Samagotchi
     # (#kind): the UIs print one line per kind, and #retryable? says whether
     # asking again could help.
     #
-    #   ConnectionError  no answer (refused, reset, timeout); RetryExhausted
+    #   ConnectionError  no answer (refused, reset, timeout); RetryExhausted,
+    #                    ConnectionRefused
     #   RateLimited      429, with retry_after when the server says
     #   ServerError      5xx or a server's error event mid-stream
     #   AuthError        401/403, or an API key variable that is not set
@@ -98,12 +99,16 @@ module Samagotchi
     class BadRequest < ProviderError
       TOOLS_HINT = "this model can't use tools, and chi needs them: pick another model (/model) or host"
 
-      def initialize(message = nil, context_overflow: false, tools_unsupported: false, **options)
+      # @param hint [String, nil] what to try, added to the summary
+      def initialize(message = nil, context_overflow: false, tools_unsupported: false, hint: nil, **options)
         @context_overflow = context_overflow
         @tools_unsupported = tools_unsupported
+        @hint = hint
         super(message, **options)
       end
 
+      attr_reader :hint
+
       # The prompt is larger than the model's context window.
       def context_overflow? = @context_overflow
 
@@ -119,7 +124,7 @@ module Samagotchi
         elsif tools_unsupported?
           "host #{host} rejected the request: #{tools_detail}; #{TOOLS_HINT}"
         else
-          "host #{host} rejected the request: #{detail}"
+          "host #{host} rejected the request: #{detail}#{"; #{hint}" if hint}"
         end
       end
 
@@ -174,6 +179,19 @@ module Samagotchi
       def summary = "network error after #{attempts} attempts (host #{host}: #{last_error.class})"
     end
 
+    # A refused connection: nothing listens at the host's address. Not
+    # retried (a server that isn't running rarely starts within the backoff).
+    class ConnectionRefused < ConnectionError
+      attr_reader :address
+
+      def initialize(host:, address: nil, attempts: 1)
+        @address = address
+        super("#{host}: connection refused#{" at #{address}" if address}", host: host, retryable: false, attempts: attempts)
+      end
+
+      def summary = "can't reach host #{host}#{" at #{address}" if address} (connection refused) — is the server running?"
+    end
+
     # A stream that showed nothing (no text, reasoning or tool call) within
     # the host's first-token limit. A queued request can stay open for many
     # minutes on keep-alive comments alone, which reset the read timeout.

data/lib/samagotchi/llm/http.rb

@@ -176,15 +176,18 @@ module Samagotchi
       private :stream_attempt
 
       # Send +request+ and return the response with its body read.
-      # @param retries [Boolean] false: one attempt, network errors raised as is
+      # @param retries [Boolean] false: one attempt, network errors raised as
+      #   is (Net::HTTP's own silent retry of an idempotent GET included)
       # @param check_status [Boolean] false: return an error response instead
       #   of raising its ProviderError
+      # @raise [RequestCancelled] when +cancel_controller+ cancels (with or
+      #   without retries)
       def fetch(uri, request, retries: true, check_status: true, open_timeout: nil, read_timeout: nil,
                 cancel_controller: nil, log_fields: {})
         identify(request)
         current = new_attempt_state(uri, request, log_fields, stream: false)
         attempt = lambda do |state|
-          start(uri, open_timeout: open_timeout, read_timeout: read_timeout) do |http|
+          start(uri, open_timeout: open_timeout, read_timeout: read_timeout, max_retries: retries ? nil : 0) do |http|
             state[:http] = http
             http.request(request).tap do |response|
               state[:status] = response.code.to_i
@@ -193,9 +196,15 @@ module Samagotchi
           end
         end
         logged(current) do
-          next attempt.call(current.merge!(attempts: 1)) unless retries
+          next with_retries(cancel_controller, nil, nil, current, &attempt) if retries
 
-          with_retries(cancel_controller, nil, nil, current, &attempt)
+          cancellable(cancel_controller, current) do
+            attempt.call(current.merge!(attempts: 1))
+          rescue StandardError => e
+            raise RequestCancelled.new(cancel_controller.reason) if !e.is_a?(RequestCancelled) && cancel_controller&.cancelled?
+
+            raise
+          end
         end
       end
 
@@ -205,8 +214,9 @@ module Samagotchi
         request["User-Agent"] = Samagotchi::USER_AGENT
       end
 
-      def start(uri, open_timeout: nil, read_timeout: nil, &block)
+      def start(uri, open_timeout: nil, read_timeout: nil, max_retries: nil, &block)
         options = { open_timeout: open_timeout || @open_timeout, read_timeout: read_timeout || @read_timeout }
+        options[:max_retries] = max_retries if max_retries
         options[:use_ssl] = true if uri.scheme == "https"
         Net::HTTP.start(uri.host, uri.port, **options, &block)
       end
@@ -215,10 +225,29 @@ module Samagotchi
       # errors. The block gets a hash to put the attempt's Net::HTTP in, so a
       # cancel can reach its socket.
       def with_retries(cancel_controller, on_retry, on_network_error, current = { mutex: Mutex.new })
+        cancellable(cancel_controller, current) do
+          retrying(cancel_controller, on_retry, on_network_error, current) { |state| yield(state) }
+        end
+      end
+
+      # Runs the block with +cancel_controller+ able to abort it: a cancel
+      # closes the socket in current[:http] (or raises RequestCancelled in
+      # this thread while there is none).
+      def cancellable(cancel_controller, current)
         requesting_thread = Thread.current
         listener_id = cancel_controller&.on_cancel { |reason| abort_request(current, requesting_thread, reason) }
         raise RequestCancelled.new(cancel_controller.reason) if cancel_controller&.cancelled?
 
+        yield
+      ensure
+        # A cancel can call the listener after remove_listener returned (the
+        # controller calls listeners outside its lock); :done keeps it from
+        # raising into this thread once the request is over.
+        current[:mutex].synchronize { current[:done] = true }
+        cancel_controller&.remove_listener(listener_id)
+      end
+
+      def retrying(cancel_controller, on_retry, on_network_error, current)
         attempts = 0
         loop do
           attempts += 1
@@ -243,6 +272,12 @@ module Samagotchi
             raise unless self.class.network_error?(e)
 
             on_network_error&.call(e)
+            # Nothing is listening: asking again rarely helps, so it fails
+            # at once and says what to check.
+            if e.is_a?(Errno::ECONNREFUSED)
+              raise ConnectionRefused.new(host: @label, address: current[:address], attempts: attempts)
+            end
+
             delay = current[:streamed] ? nil : @retry_policy.delay_for(attempts)
             raise RetryExhausted.new(attempts: attempts, last_error: e, label: @label) if delay.nil?
 
@@ -251,12 +286,6 @@ module Samagotchi
             current.delete(:http)
           end
         end
-      ensure
-        # A cancel can call the listener after remove_listener returned (the
-        # controller calls listeners outside its lock); :done keeps it from
-        # raising into this thread once the request is over.
-        current[:mutex].synchronize { current[:done] = true }
-        cancel_controller&.remove_listener(listener_id)
       end
 
       # Runs one attempt (the block) under the first-token limit: a watchdog
@@ -302,7 +331,7 @@ module Samagotchi
       # closes, status, timings) and what its log line says.
       def new_attempt_state(uri, request, log_fields, stream:)
         purpose = log_fields[:purpose]&.to_s
-        { mutex: Mutex.new, started_at: monotonic_now, stream: stream,
+        { mutex: Mutex.new, started_at: monotonic_now, stream: stream, address: "#{uri.host}:#{uri.port}",
           level: LOGGED_PURPOSES.include?(purpose) ? :info : :debug,
           log: { host: @label, method: request.method, url: log_url(uri),
                  **log_fields.compact } }
@@ -326,7 +355,7 @@ module Samagotchi
                         ms: elapsed_ms(current), attempts: retried(current))
         result
       rescue RequestCancelled => e
-        Log.info(:http, "cancelled", **log_base(current), ms: elapsed_ms(current), reason: e.reason&.to_s)
+        Log.public_send(current[:level], :http, "cancelled", **log_base(current), ms: elapsed_ms(current), reason: e.reason&.to_s)
         raise
       rescue StandardError => e
         failure_level = current[:level] == :info ? :error : :debug

data/lib/samagotchi/llm/openai_chat.rb

@@ -3,6 +3,7 @@
 require "json"
 require "uri"
 require_relative "../config"
+require_relative "../sampling_settings"
 require_relative "errors"
 require_relative "http"
 require_relative "usage"
@@ -111,9 +112,9 @@ module Samagotchi
       # @return [ChatResponse]
       def chat(messages:, model:, tools: [], cancel_controller: nil, on_delta: nil, on_retry: nil, options: {},
                session_id: nil)
-        request = post_request("#{@base_url}/chat/completions", request_body(messages, tools, model, options),
-                               session_id: session_id)
-        log_fields = { model: model, purpose: @purpose }
+        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) }
         return chat_once(request, cancel_controller, log_fields) unless @stream
 
         assembly = Assembly.new
@@ -209,7 +210,14 @@ module Samagotchi
           body[:tools] = tools
           body[:tool_choice] = "auto"
         end
-        body.merge(options || {})
+        # A configured value replaces chi's own (temperature); nil drops it.
+        body.merge(options || {}).compact
+      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)
+        SamplingSettings.log_text(body.except(:model, :messages, :stream, :stream_options, :tools, :tool_choice))
       end
 
       # A String stays a String; an Array of parts passes as given.