samagotchi 0.3.0 → 0.4.0

data/lib/samagotchi/guardrails/approval.rb

@@ -20,12 +20,14 @@ module Samagotchi
       # @param label [String, nil] a plugin tool's label ("chrome:
       #   screenshot"): the question names the tool by it, as its row does;
       #   approval[:tool] stays the raw name
+      # @param preview [Hash, nil] EditPreview.for(verdict.call) for edit and
+      #   write: the card shows its diff, the question text one change line
       # @return [Hash] open_question fields
-      def payload(verdict, label: nil)
+      def payload(verdict, label: nil, preview: nil)
         scopes = offered_scopes(verdict)
         targets = verdict.targets
         {
-          question: question_text(verdict, label: label),
+          question: question_text(verdict, label: label, preview: preview),
           options: scopes.map { |scope| label(scope, verdict) } + [DENY],
           header: HEADER,
           multi_select: false,
@@ -44,7 +46,8 @@ module Samagotchi
             rule: verdict.rule,
             source: verdict.source,
             reason: verdict.reason,
-            scopes: scopes
+            scopes: scopes,
+            preview: preview
           }.compact
         }
       end
@@ -112,7 +115,8 @@ module Samagotchi
       # execute: git push origin main
       #   in /path/to/repo (repo samagotchi, branch main)
       #   why: git push publishes commits (rule git-push, bundle guardrails)
-      def question_text(verdict, label: nil)
+      #   change: +3 −1                      (edit/write, from the preview)
+      def question_text(verdict, label: nil, preview: nil)
         targets = verdict.targets
         tool = label || targets&.tool || verdict.call[:name].to_s
         what = targets&.command || (targets && targets.paths.join(", "))
@@ -127,8 +131,26 @@ module Samagotchi
         who = verdict.rule ? ["rule #{verdict.rule}", verdict.source].compact.join(", ") : (verdict.source || "hook")
         reason = verdict.reason.to_s.strip
         lines << "  why: #{reason.empty? ? "(no reason given)" : reason} (#{who})"
+        change = change_text(preview)
+        lines << "  change: #{change}" if change
         lines.join("\n")
       end
+
+      # One line for an EditPreview: "+3 −1", "new file, 12 lines",
+      # "would fail: …" or "not shown (binary file)". The diff itself stays
+      # out of the question text (size); the card and the TUI show it.
+      def change_text(preview)
+        return nil unless preview.is_a?(Hash)
+
+        get = ->(key) { preview[key] || preview[key.to_s] }
+        return "would fail: #{get.(:error)}" if get.(:error)
+        return "not shown (#{get.(:skipped)})" if get.(:skipped)
+
+        added = get.(:added).to_i
+        return "new file, #{added} #{added == 1 ? "line" : "lines"}" if get.(:new_file)
+
+        "+#{added} −#{get.(:removed).to_i}"
+      end
     end
   end
 end

data/lib/samagotchi/guardrails/load_failures.rb

@@ -7,7 +7,7 @@ module Samagotchi
     # guardrail that silently vanished is the failure this guards against);
     # the rest are only announced.
     class LoadFailures
-      Failure = Struct.new(:what, :reason, :required, keyword_init: true)
+      Failure = Struct.new(:what, :reason, :required, :group, keyword_init: true)
 
       def initialize
         @list = []
@@ -15,8 +15,14 @@ module Samagotchi
       end
 
       # @param what [String] e.g. "hook guard.rb (config)"
-      def add(what, reason, required:)
-        @mutex.synchronize { @list << Failure.new(what: what, reason: reason, required: required) }
+      # @param group [Symbol, nil] what loads it again (#drop): :rules
+      def add(what, reason, required:, group: nil)
+        @mutex.synchronize { @list << Failure.new(what: what, reason: reason, required: required, group: group) }
+      end
+
+      # Forget a group's failures before it loads again.
+      def drop(group)
+        @mutex.synchronize { @list.reject! { |failure| failure.group == group } }
       end
 
       def list = @mutex.synchronize { @list.dup }

data/lib/samagotchi/host_registry.rb

@@ -29,9 +29,10 @@ module Samagotchi
     # 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;
-    # sampling: the configured request parameters (SamplingSettings), nil when unset.
+    # sampling: the configured request parameters (SamplingSettings), nil when unset;
+    # thinking: the configured level (Thinking), nil when unset.
     HostEntry = Struct.new(:name, :host, :port, :transport, :client, :api, :scheme, :url, :api_key_env, :profile,
-                           :first_token_timeout, :vision, :sampling, keyword_init: true) do
+                           :first_token_timeout, :vision, :sampling, :thinking, 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
@@ -87,9 +88,10 @@ 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], sampling: cfg[:sampling])
+                              vision: cfg[:vision], sampling: cfg[:sampling], thinking: cfg[:thinking])
         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)
+                                  first_token_timeout: entry.first_token_limit, name: entry.name,
+                                  api_key_env: entry.api_key_env, env: env)
         @entries[entry.name] = entry
       end
       # Fallback single entry (should already be synthesized by hosts_config, but guard)
@@ -117,10 +119,6 @@ module Samagotchi
       nil
     end
 
-    def entry_names
-      @entries.keys
-    end
-
     def default_entry
       @entries["default"] || @entries.values.first
     end
@@ -149,10 +147,8 @@ module Samagotchi
         rescue StandardError
           nil
         end
-        entry = find_entry(host_ref)
-        return [entry, bare] if entry
-        # Unknown prefix — treat as bare model on default host
-        return [default_entry, raw_model.to_s.strip]
+        # parse_qualified_model names a host only when it is one of ours
+        return [find_entry(host_ref), bare]
       end
       # Unqualified: also try alias resolution for discovery (small -> gemma-small or small -> small-box:gemma-small)
       begin

data/lib/samagotchi/idle_client.rb

@@ -2,6 +2,8 @@
 
 require "json"
 require_relative "llm/openai_chat"
+require_relative "thinking"
+require_relative "log"
 
 module Samagotchi
   # Standalone summarizer for the idle session-recap feature.
@@ -33,17 +35,6 @@ module Samagotchi
     # Up to 10 sentences (recap.sentences) need ~350 tokens with thinking off.
     MAX_TOKENS = 512
 
-    # Request fields that turn thinking off. A reasoning model otherwise
-    # spends the budget thinking and the recap stops mid-sentence.
-    # - chat_template_kwargs.enable_thinking: the chat template's switch
-    #   (llama.cpp with Qwen/Gemma templates); templates without it ignore it.
-    # - reasoning_effort "none": the OpenAI-style knob, for servers that
-    #   ignore the template switch (Splash thought until max_tokens).
-    THINKING_OFF = {
-      chat_template_kwargs: { enable_thinking: false },
-      reasoning_effort: "none"
-    }.freeze
-
     # @param base_url [String] the OpenAI API base, e.g. http://host:8081/v1
     # @param api_key_env [String, nil] the variable holding the host's key
     # @param timeout [Numeric] HTTP request timeout. Kept to the recap's own
@@ -119,10 +110,17 @@ module Samagotchi
     # +max_tokens+, the text keeps its finished sentences (+whole_sentences+)
     # or all of it, with "…".
     def generate(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, whole_sentences: true)
-      response = @chat.chat(
-        messages: messages, model: @model, tools: [], cancel_controller: cancel_controller,
-        options: { max_tokens: max_tokens, **THINKING_OFF }
-      )
+      response = begin
+        request(messages, max_tokens, cancel_controller)
+      rescue LLM::BadRequest => e
+        raise unless e.reasoning_refused? && !@thinking_refused
+
+        # The host won't turn thinking off (gpt-oss): ask again without the
+        # fields, and leave them out from now on.
+        @thinking_refused = true
+        Log.info(:recap, "thinking_refused", model: @model, detail: e.detail)
+        request(messages, max_tokens, cancel_controller)
+      end
       content = response.text
       reasoning = response.reasoning
       raise SummarizeError, "server returned no parseable assistant content" if content.empty? && reasoning.empty?
@@ -143,5 +141,16 @@ module Samagotchi
       raise SummarizeError, "server returned no parseable assistant content (#{e.message})"
     end
 
+    def request(messages, max_tokens, cancel_controller)
+      @chat.chat(messages: messages, model: @model, tools: [], cancel_controller: cancel_controller,
+                 options: { max_tokens: max_tokens, **thinking_fields })
+    end
+
+    # A recap or side answer is short and tool-less: thinking off, whatever
+    # the model's level (a reasoning model otherwise spends the budget
+    # thinking and the recap stops mid-sentence). None once the host refused them.
+    def thinking_fields
+      @thinking_refused ? {} : Thinking.chat_fields(:off)
+    end
   end
 end

data/lib/samagotchi/idle_reminders.rb

@@ -9,7 +9,7 @@ module Samagotchi
   # (one background thread for the whole idle layer).
   #
   # Two delivery paths cooperate:
-  #   1. Pull-based: Engine#maybe_inject_reminders / collect_due_reminders
+  #   1. Pull-based: Engine#collect_due_reminders
   #      reads ReminderStore#due_reminders at turn start → injects
   #      [SYSTEM: REMINDERS DUE] → marks all as fired atomically.
   #   2. Synthetic turns: when this job's tick finds due reminders while
@@ -43,7 +43,7 @@ module Samagotchi
       @mutex.synchronize { @due_reminder_name }
     end
 
-    # Get all due reminders (from ReminderStore). Called by Engine#maybe_inject_reminders.
+    # Get all due reminders (from ReminderStore). Called by Engine#collect_due_reminders.
     # Thread-safe. Returns all due reminders, not just one.
     # @return [Array<Hash>] [{name:, description:, interval_minutes:}, ...]
     def due_reminders

data/lib/samagotchi/image_store.rb

@@ -262,12 +262,7 @@ module Samagotchi
         next message unless images.is_a?(Array) && !images.empty?
 
         kept, gone = from ? images.partition { |ref| valid_ref?(from, ref) } : [[], images]
-        kept.each do |ref|
-          file = (ref[:file] || ref["file"]).to_s
-          target = File.join(to.to_s, file)
-          FileUtils.mkdir_p(File.dirname(target))
-          FileUtils.cp(File.join(from.to_s, file), target) unless File.exist?(target)
-        end
+        kept.each { |ref| copy_file(ref, from: from, to: to) }
         dropped += gone.size
         message = message.reject { |key, _| key.to_s == "images" }
         message[:images] = kept unless kept.empty?
@@ -280,6 +275,15 @@ module Samagotchi
       [copied, dropped]
     end
 
+    # One stored image's file from session dir +from+ into +to+ (kept when
+    # it is there already: the name is the content's hash).
+    def self.copy_file(ref, from:, to:)
+      file = (ref[:file] || ref["file"]).to_s
+      target = File.join(to.to_s, file)
+      FileUtils.mkdir_p(File.dirname(target))
+      FileUtils.cp(File.join(from.to_s, file), target) unless File.exist?(target)
+    end
+
     # A ref for an image already stored in this session (a web upload),
     # rebuilt from the file itself: only its name comes from the caller.
     def self.ref_for(session_dir, file:, name: nil, source: "user")

data/lib/samagotchi/kernel_loop.rb

@@ -11,6 +11,7 @@ require_relative "client"
 require_relative "llm/errors"
 require_relative "log"
 require_relative "empty_answer_retry"
+require_relative "thinking"
 require_relative "hooks"
 require_relative "pending_input_queue"
 require_relative "steer"
@@ -179,6 +180,9 @@ module Samagotchi
     # The turn's request parameters (SamplingSettings.for), set by the Engine
     # per turn; empty or nil sends none.
     attr_accessor :sampling
+    # The turn's thinking level (Thinking.resolve), set by the Engine per
+    # turn; its own accessor, since the native path sends @sampling as is.
+    attr_accessor :thinking
     # 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
@@ -217,13 +221,17 @@ module Samagotchi
       @retry_generation = false
       context_status = nil
       stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
+      # Qwen with thinking off: an empty thought after the cue, so the model
+      # answers at once. Kept in the turn's model messages, so each tool-loop
+      # prompt starts with what the server already has cached.
+      prefill = Thinking.native(@thinking || Thinking::DEFAULT, @profile).prefill
       partial_assistant_buffer = +""
 
       effective_max_iterations = @no_interrupt ? 1000 : max_iterations
       effective_max_tool_output_chars = resolve_output_char_cap(max_tool_output_chars)
       effective_max_iterations.times do |iteration_index|
         inject_pending_input!(conversation, pending_input, on_stream_event, iteration_index + 1, cancel_controller)
-        prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @vision)
+        prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @vision, prefill: prefill)
         image_tokens = images.empty? ? 0 : ImagePlan.estimated_tokens(conversation)
         context_window = ContextWindow.resolve(client: @client, model: resolved_model_name)
         context_status = emit_context_status_event(on_stream_event, prompt, iteration_index: iteration_index, state: context_state, window: context_window,
@@ -232,7 +240,7 @@ module Samagotchi
           # The model's own copy, on the tail (the prompt cache keeps its
           # prefix), then the prompt again with it.
           conversation << line
-          prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @vision)
+          prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @vision, prefill: prefill)
         end
         emit_stream_event(
           on_stream_event,
@@ -310,7 +318,7 @@ module Samagotchi
         after_gen_event = { type: :after_generation, iteration: iteration_index + 1, response: response,
                             messages: AnswerDisplay.strip_all(conversation).map(&:dup).freeze }
         fire_hook(:after_generation, after_gen_event) if @hooks
-        conversation << { role: "model", content: response }
+        conversation << { role: "model", content: prefill + response.to_s }
 
         # Profile-specific parse (incl. Qwen unterminated-block recovery); the
         # returned fragment (non-nil only for Qwen) is fed back on the next
@@ -365,6 +373,7 @@ module Samagotchi
         image_counts = []
         shown_params = []
         shown_labels = []
+        diffs = []
         results = calls.map.with_index do |call, call_index|
           run = tool_runner.run(call, iteration: iteration_index + 1, call_index: call_index + 1,
                                       call_count: calls.length, on_stream_event: on_stream_event,
@@ -374,6 +383,7 @@ module Samagotchi
           image_counts << Array(run[:images]).size
           shown_params << run[:shown_params]
           shown_labels << run[:shown_label]
+          diffs << run[:diff]
           run[:output]
         end.join("\n\n---\n\n")
         emit_stream_event(on_stream_event, type: :tool_dispatch_completed, iteration: iteration_index + 1, call_count: calls.length)
@@ -387,6 +397,9 @@ module Samagotchi
         # a built-in), for the web's reload; the prompt never reads it.
         tool_response[:tool_params] = shown_params if shown_params.any?
         tool_response[:tool_labels] = shown_labels if shown_labels.any?
+        # What each edit/write changed (nil for other calls), in call order,
+        # for the web's reload; the prompt never reads it.
+        tool_response[:tool_diffs] = diffs if diffs.any?
         conversation << tool_response
         pending_tool_calls = true
       rescue Client::RequestCancelled => e
@@ -828,14 +841,6 @@ module Samagotchi
       end
     end
 
-    # Parse tool calls from raw model output using the active profile's
-    # ToolCallParser strategy (Gemma 4 or Qwen 3.6).
-    # Thought content is intentionally left intact while a tool-call turn is in
-    # progress to preserve same-turn reasoning context between tool calls.
-    def parse_tool_calls(text)
-      parser.parse(text.to_s)
-    end
-
     public
 
     # Public wrapper so other loops (e.g. the chat loop) can strip
@@ -974,76 +979,18 @@ module Samagotchi
       }
     end
 
+    # ask_user_question: validate the call, then hand the payload to the
+    # Engine's question flow (question_handler, which blocks until the user
+    # answers). Without one (headless), the payload as JSON so the model sees
+    # the options and can ask in plain text.
     def handle_ask_user_question(call)
-      question = (call[:question] || call[:content]).to_s.strip
-      raw_opts = call[:options]
-      # Dumb-model tolerant: raw may be String JSON, Array, or malformed with brackets/quotes
-      options = Samagotchi::Tools::AskUserQuestion.normalize_options_lenient(raw_opts)
-      # Fallback for case where raw was String like '["a","b"]' but lenient returned [] due to edge parse, try raw string of params
-      if options.empty? && raw_opts.is_a?(String)
-        options = Samagotchi::Tools::AskUserQuestion.normalize_options_lenient(raw_opts.to_s)
-      end
-      header = call[:header].to_s.strip
-      header = nil if header.empty?
-      multi = call[:multi_select]
-      free = call[:allow_freeform]
-      # Normalize booleans from string forms (Gemma passes "true"/"false" as strings)
-      multi = normalize_ask_bool(multi)
-      free = normalize_ask_bool(free)
-
-      if question.empty?
-        return "Error: ask_user_question requires 'question'"
-      end
-      # Dumb-model tolerant: salvage single-option parse glitches, but still require at least 1
-      if options.size < 1
-        alt = Samagotchi::Tools::AskUserQuestion.normalize_options_lenient(call[:content].to_s) if call[:content]
-        options = alt unless alt.empty?
-      end
-      if options.empty?
-        return "Error: ask_user_question requires 2-8 options (got 0). Provide e.g. options=[\"Cats\",\"Dogs\"]"
-      end
-      if options.size == 1
-        # Allow single-option salvage for dumb models (will still render, user can answer or provide freeform)
-      elsif options.size < 2 || options.size > 8
-        return "Error: ask_user_question requires 2-8 options (got #{options.size}). Provide e.g. options=[\"Cats\",\"Dogs\"]"
-      end
-
-      # If an Engine-level blocking handler is registered (TUI/Web), delegate
-      # there (Engine sets question_handler). Otherwise fall back to a
-      # non-blocking JSON preview so the model can still see a structured response.
-      handler = @question_handler
-
-      payload = {
-        question: question,
-        options: options,
-        header: header,
-        multi_select: !!multi,
-        allow_freeform: !!free
-      }.compact
-
-      if handler
-        begin
-          result = handler.call(payload)
-          return result.to_s
-        rescue => e
-          return "Error: ask_user_question handler failed: #{e.message}"
-        end
-      end
-
-      # Headless fallback: return JSON so model sees structured options and can
-      # fallback to plain text qualification.
-      JSON.pretty_generate(payload)
-    end
+      payload = Samagotchi::Tools::AskUserQuestion.validate(call)
+      return payload if payload.is_a?(String)
+      return JSON.pretty_generate(payload) unless @question_handler
 
-    def normalize_ask_bool(v)
-      return nil if v.nil?
-      return v if v == true || v == false
-
-      s = v.to_s.strip.downcase
-      return true if %w[1 true yes on].include?(s)
-      return false if %w[0 false no off].include?(s)
-
-      nil
+      @question_handler.call(payload).to_s
+    rescue => e
+      "Error: ask_user_question handler failed: #{e.message}"
     end
   end
 end

data/lib/samagotchi/live_versions.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "socket"
+require_relative "session"
+require_relative "version"
+
+module Samagotchi
+  # Which chi versions the running processes run, for `chi update`: session
+  # workers (their bridge.json sidecar names the version since chi update exists; an
+  # older one names none) and a `chi web` on its port (/api/info). Read-only:
+  # a dead worker's sidecar is left for the next client to clean up.
+  module LiveVersions
+    PROBE_TIMEOUT = 0.2
+    WEB_TIMEOUT = 0.5
+
+    # version is nil for a sidecar written before sidecars carried one.
+    Worker = Struct.new(:session_id, :version, keyword_init: true)
+
+    module_function
+
+    # @return [Array<Worker>] the workers whose Bridge answers, by session id
+    def workers(state_dir: Session.default_state_dir)
+      Dir[File.join(state_dir, "*", "bridge.json")].sort.filter_map do |sidecar|
+        data = JSON.parse(File.read(sidecar))
+        next unless data.is_a?(Hash) && listening?(data["port"].to_i)
+
+        Worker.new(session_id: File.basename(File.dirname(sidecar)), version: data["version"])
+      rescue JSON::ParserError, SystemCallError
+        nil
+      end
+    end
+
+    # The live workers on another version than +version+ (unknown counts).
+    def stale_workers(version = VERSION, state_dir: Session.default_state_dir)
+      workers(state_dir: state_dir).reject { |w| w.version == version }
+    end
+
+    # The version a chi web on host:port runs, or nil when nothing (or not
+    # chi web) answers.
+    def web_version(host, port, timeout: WEB_TIMEOUT)
+      response = Net::HTTP.start(host, port, open_timeout: timeout, read_timeout: timeout) { |http| http.get("/api/info") }
+      info = response.code.to_i == 200 ? JSON.parse(response.body.to_s) : nil
+      info.is_a?(Hash) && info["app"] == "chi-web" ? info["version"].to_s : nil
+    rescue StandardError
+      nil
+    end
+
+    def listening?(port, host: "127.0.0.1")
+      return false unless port.positive?
+
+      Socket.tcp(host, port, connect_timeout: PROBE_TIMEOUT).close
+      true
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/samagotchi/llm/api_key.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Samagotchi
+  module LLM
+    # A host's API key: the environment variable its api_key_env: names,
+    # sent as `Authorization: Bearer <key>` on every request LLM::HTTP makes
+    # for the host (llama.cpp started with --api-key, or a provider). The
+    # key itself never goes into a message.
+    ApiKey = Data.define(:env_name, :host, :env) do
+      # nil for a host without api_key_env: its requests carry no header.
+      def self.for(env_name, host:, env: ENV)
+        name = env_name.to_s.strip
+        name.empty? ? nil : new(env_name: name, host: host.to_s, env: env)
+      end
+
+      # What to try after a 401/403 from a host that has no api_key_env.
+      def self.missing_hint(host)
+        "the server may want an API key: put it in an environment variable and name it with api_key_env: on host #{host}"
+      end
+
+      # Sets the header, or raises AuthError when the variable is not set.
+      def authorize(request)
+        key = env[env_name].to_s
+        raise AuthError.new("#{host}: set #{env_name} (the API key for host #{host})", host: host) if key.strip.empty?
+
+        request["Authorization"] = "Bearer #{key}"
+      end
+
+      # What to try after a 401/403 with the key sent.
+      def hint = "check #{env_name} (the API key for host #{host})"
+
+      # Without the environment: it holds this key and every other secret.
+      def inspect = "#<#{self.class.name} #{env_name} host=#{host}>"
+      alias_method :to_s, :inspect
+
+      def pretty_print(printer) = printer.text(inspect)
+    end
+  end
+end