samagotchi 0.3.0 → 0.4.0

data/lib/samagotchi/engine.rb

@@ -46,7 +46,9 @@ require_relative "image_store"
 require_relative "vision_context"
 require_relative "vision_support"
 require_relative "sampling_settings"
+require_relative "thinking"
 require_relative "answer_display"
+require_relative "edit_preview"
 
 module Samagotchi
   # Engine owns the core agent logic: system prompt construction, tool
@@ -92,9 +94,13 @@ module Samagotchi
       @scratch = scratch
       @chat_backend = nil
       @chat_backend_mutex = Mutex.new
+      @host_registry = host_registry || HostRegistry.new
+      # A model given here (a worker's session model) is the one it runs,
+      # so its host is checked; the config default is only checked once it
+      # is used (the REPL checks the model it starts on, #switch_model!).
       @default_model_name = ModelProfile.required_model_name(model_name)
+      ModelProfile.check_host!(model_name, hosts: @host_registry.entries) unless model_name.to_s.strip.empty?
       @effective_model_name = @default_model_name
-      @host_registry = host_registry || HostRegistry.new
       # An injected client (specs) stands in for every host's client.
       @host_registry.client_override = client if client
       @client = @host_registry.resolve(@effective_model_name).client
@@ -116,6 +122,7 @@ module Samagotchi
       # to load is announced, and a required guardrail's failure denies
       # every tool call. Rules load now too, so their errors are announced.
       @guardrail_failures = Guardrails::LoadFailures.new
+      @guardrail_rules_mutex = Mutex.new
       # Plugins that failed to load: announced apart, as plugins (not
       # guardrails: no tool call is denied for them).
       @plugin_failures = Guardrails::LoadFailures.new
@@ -847,7 +854,7 @@ module Samagotchi
     def switch_model!(model_name, persist_default: false)
       # Resolve alias first (alias may point to qualified ref)
       aliased = ConfigFile.resolve_model_alias(model_name)
-      resolved = ModelProfile.required_model_name(aliased)
+      resolved = ModelProfile.check_host!(ModelProfile.required_model_name(aliased), hosts: @host_registry.entries)
       @effective_model_name = resolved
       bare = bare_model_name(resolved)
       @model_lookup_names = [model_name, aliased, resolved]
@@ -867,10 +874,6 @@ module Samagotchi
       resolved
     end
 
-    def reset_model!
-      switch_model!(@default_model_name)
-    end
-
     # ── Hooks API ──────────────────────────────────────────────────────────────
 
     # Register a hook callback for a named lifecycle event.
@@ -941,8 +944,6 @@ module Samagotchi
       clear_due_reminder_names!
       due
     end
-    # Alias for backward compatibility.
-    alias maybe_inject_reminders collect_due_reminders
 
     # @return [Boolean] whether any reminder is due now (the store's view,
     #   which #collect_due_reminders would inject), regardless of the REPL queue
@@ -1003,6 +1004,16 @@ module Samagotchi
       nil
     end
 
+    # "off (models: qwen)" for /model: the effective model's thinking level
+    # and where it came from, nil when none is set.
+    def thinking_summary
+      target = @host_registry.resolve(@effective_model_name)
+      level, source = Thinking.resolve(target, names: model_lookup_names(target))
+      source ? "#{level} (#{source})" : nil
+    rescue StandardError
+      nil
+    end
+
     # The model the server serves for the current model, and the name asked
     # for: what the last generation of that name reported, else llama.cpp's
     # model_alias (/props, one short cached probe; not with probe: false),
@@ -1128,6 +1139,9 @@ module Samagotchi
       base.empty? ? nil : base
     end
 
+    # A memory read (memory_read, or read of a memories/*.md file) as it
+    # starts: its names join used_memory_names.
+    # @return [Array<String>, nil] the names this call read, nil for any other event
     def capture_used_memory_from_event(event)
       return unless event.is_a?(Hash) && event[:type] == :tool_call_started
 
@@ -1138,6 +1152,7 @@ module Samagotchi
       return if names.empty?
 
       add_used_memory_names(names)
+      names
     end
 
     # ── Guardrails ─────────────────────────────────────────────────────────────
@@ -1193,28 +1208,54 @@ module Samagotchi
 
     # The YAML rules: config.yml's `guardrails:` section (rules, disable) and
     # installed bundles'. One that doesn't parse is a required load failure
-    # (every call is denied).
+    # (every call is denied). Read again when one of those files changed
+    # (a stat of each per tool call), so a long-lived worker follows edits.
     # @return [Guardrails::Rules]
     def guardrail_rules
-      @guardrail_rules ||= begin
-        section = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-        section = section["guardrails"] if section.is_a?(Hash)
-        rules = []
-        disable = []
-        begin
-          raise Guardrails::Rules::ParseError, "guardrails must be a mapping" unless section.nil? || section.is_a?(Hash)
-
-          rules = Guardrails::Rules.parse(section && section["rules"], source: "config")
-          disable = Guardrails::Rules.parse_disable(section && section["disable"])
-        rescue Guardrails::Rules::ParseError => e
-          Log.warn(:guardrails, "config_rules_invalid", echo: "[samagotchi:guardrails] config.yml guardrails rules: #{e.message}")
-          @guardrail_failures.add("rules in config.yml", e.message, required: true)
+      @guardrail_rules_mutex.synchronize do
+        stamp = guardrail_rules_stamp
+        if @guardrail_rules.nil? || stamp != @guardrail_rules_stamp
+          @guardrail_failures.drop(:rules)
+          @guardrail_rules = load_guardrail_rules
+          @guardrail_rules_stamp = stamp
         end
-        Guardrails::Rules.new(rules + bundle_guardrail_rules, disable: disable,
-                              enabled: Samagotchi::Config.get("guardrails.enabled") != false)
+        @guardrail_rules
+      end
+    end
+
+    # [path, mtime, size] of config.yml and every installed bundle's
+    # manifest.json and guardrails/ file.
+    def guardrail_rules_stamp
+      require_relative "memory_bundle/provenance"
+      paths = [Samagotchi::ConfigFile.global_path] +
+              Dir[File.join(MemoryBundle::Provenance.bundles_dir, "*", "{manifest.json,guardrails/*}")]
+      paths.compact.sort.map do |path|
+        stat = File.stat(path)
+        [path, stat.mtime.to_r, stat.size]
+      rescue SystemCallError
+        [path]
       end
     end
 
+    def load_guardrail_rules
+      section = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
+      section = section["guardrails"] if section.is_a?(Hash)
+      rules = []
+      disable = []
+      begin
+        raise Guardrails::Rules::ParseError, "guardrails must be a mapping" unless section.nil? || section.is_a?(Hash)
+
+        rules = Guardrails::Rules.parse(section && section["rules"], source: "config")
+        disable = Guardrails::Rules.parse_disable(section && section["disable"])
+      rescue Guardrails::Rules::ParseError => e
+        Log.warn(:guardrails, "config_rules_invalid", echo: "[samagotchi:guardrails] config.yml guardrails rules: #{e.message}")
+        @guardrail_failures.add("rules in config.yml", e.message, required: true, group: :rules)
+      end
+      Guardrails::Rules.new(rules + bundle_guardrail_rules, disable: disable,
+                            enabled: Samagotchi::Config.get("guardrails.enabled") != false)
+    end
+    private :guardrail_rules_stamp, :load_guardrail_rules
+
     # Installed bundles' guardrails/*.yml, by bundle name then file name.
     # A file that is missing, changed since install (sha256) or doesn't
     # parse is a required load failure.
@@ -1224,7 +1265,7 @@ module Samagotchi
       MemoryBundle::Provenance.each_installed_with_guardrails do |bundle_name, data|
         if data[:error]
           Log.warn(:guardrails, "bundle_rules_invalid", echo: "[samagotchi:guardrails] bundle #{bundle_name}: #{data[:error]}", bundle: bundle_name)
-          @guardrail_failures.add("rules (bundle #{bundle_name})", data[:error], required: true)
+          @guardrail_failures.add("rules (bundle #{bundle_name})", data[:error], required: true, group: :rules)
           next
         end
         dir = MemoryBundle::Provenance.new(name: bundle_name).guardrails_dir
@@ -1246,14 +1287,14 @@ module Samagotchi
             rules.concat(Guardrails::Rules.parse(doc["rules"], source: "bundle #{bundle_name}"))
           rescue Guardrails::Rules::ParseError, Psych::Exception => e
             Log.warn(:guardrails, "rules_file_invalid", echo: "[samagotchi:guardrails] #{what}: #{e.message}", bundle: bundle_name, file: basename.to_s)
-            @guardrail_failures.add(what, e.message, required: true)
+            @guardrail_failures.add(what, e.message, required: true, group: :rules)
           end
         end
       end
       rules
     rescue StandardError => e
       Log.error(:guardrails, "bundle_rules_failed", echo: "[samagotchi:guardrails] failed to read installed bundles' rules: #{e.class}: #{e.message}", error: e.class.name)
-      @guardrail_failures.add("bundle rules", "#{e.class}: #{e.message}", required: true)
+      @guardrail_failures.add("bundle rules", "#{e.class}: #{e.message}", required: true, group: :rules)
       rules || []
     end
 
@@ -1327,10 +1368,21 @@ module Samagotchi
 
       # A plugin tool is asked about by its label, as its row shows it.
       label = ToolActivity.plugin_label(verdict.call[:name].to_s, registry: @tools)
-      payload = Guardrails::Approval.payload(verdict, label: label)
+      # verdict.call is the call that will run (a hook may have replaced it).
+      payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call))
       Guardrails::Approval.settle(verdict, open_question(payload), payload[:approval][:scopes])
     end
 
+    # The dry-run diff of an edit/write call for its approval; a preview
+    # that fails only leaves the diff out, it never denies the call.
+    def approval_preview(call)
+      EditPreview.for(call)
+    rescue StandardError => e
+      Log.warn(:guardrails, "edit_preview_failed", error: "#{e.class}: #{e.message}")
+      nil
+    end
+    private :approval_preview
+
     # The conversation as a hook may read it: a frozen array of copied
     # messages, so a hook cannot change what the turn sends or stores.
     def hook_messages(messages)
@@ -1466,45 +1518,24 @@ module Samagotchi
       @question_mutex.synchronize { @pending_question&.dup }
     end
 
-    # Request a structured question from the user. Called from KernelLoop's
-    # turn thread (via dispatch): validates and cleans the model's payload,
-    # then #open_question. Returns a normalized JSON string for the
-    # tool_response.
+    # Ask the model's question (ask_user_question): the kernel's
+    # question_handler, called on the turn thread with the payload
+    # Tools::AskUserQuestion.validate made. Opens it (#open_question) and
+    # returns the answer as JSON for the tool result.
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
     # @return [String] normalized answer JSON
     def request_question(payload)
-      # Strip wire control tokens (<|...|> / stray <|,|>) that can bleed into the
-      # question text when the model wraps the tool call in markup.
-      question = strip_wire_tokens(payload[:question])
-      options = Samagotchi::Tools::AskUserQuestion.normalize_options_lenient(payload[:options])
-      # Fallback for string JSON that lenient missed
-      if options.empty? && payload[:options].is_a?(String)
-        options = Samagotchi::Tools::AskUserQuestion.normalize_options_lenient(payload[:options].to_s)
-      end
-      if question.empty? || options.empty?
-        return JSON.generate({ error: "invalid question", detail: "question and 2-8 options required (got #{options.size})" })
-      end
-      # Dumb-model salvage: allow single option (don't hard error, just render what we have)
-      if options.size == 1
-        # keep as is
-      elsif options.size < 2
-        return JSON.generate({ error: "invalid question", detail: "question and 2-8 options required (got #{options.size})" })
-      end
-      if options.size > 8
-        options = options.first(8)
-      end
-
-      clean_header = strip_wire_tokens(payload[:header])
-      result = open_question(
-        question: question,
-        options: options,
-        header: clean_header.empty? ? nil : clean_header,
-        multi_select: !!payload[:multi_select],
-        allow_freeform: !!payload[:allow_freeform]
-      )
+      result = open_question(**payload.slice(:question, :options, :header),
+                             multi_select: !!payload[:multi_select], allow_freeform: !!payload[:allow_freeform])
+      # Dismissed (the card's dismiss, Esc): an answer of its own, not a
+      # tool failure the model learns to avoid the tool from.
+      result = { dismissed: true, id: result[:id], note: QUESTION_DISMISSED_NOTE } if result.is_a?(Hash) && result[:error] == "no answer"
       result.is_a?(String) ? result : JSON.generate(result)
     end
 
+    QUESTION_DISMISSED_NOTE = "The user dismissed the question without answering. Go on with your best judgement, " \
+                              "or ask in your reply if you can't."
+
     # Open a question for the UIs and wait for its answer. Emits
     # :question_requested, persists it to the session, and BLOCKS until
     # answer_question / cancel_question wakes it (or the turn is cancelled).
@@ -1663,11 +1694,6 @@ module Samagotchi
       end
     end
 
-    def strip_wire_tokens(text)
-      text.to_s.gsub(/<\|[^|]*\|>/, "").gsub(/<\||\|>/, "").strip
-    end
-    private :strip_wire_tokens
-
     def set_question_sync_handler(&block)
       @question_sync_handler = block
     end
@@ -1703,10 +1729,15 @@ module Samagotchi
     # prompt prefix, and the server's KV cache for it, stay stable.
     # @param target [HostRegistry::ModelTarget, nil]
     # @return [String]
+    # The native prompt depends on the thinking level too (Gemma's token,
+    # Qwen's turn preamble): a level change builds it again.
     def system_prompt(target = nil)
-      chat = (target || @host_registry.resolve(@effective_model_name)).entry.chat?
+      target ||= @host_registry.resolve(@effective_model_name)
+      chat = target.entry.chat?
+      level = chat ? nil : thinking_level(target)
       @system_prompts ||= {}
-      @system_prompts[chat] ||= system_prompt_with_index(assist_system_prompt(chat: chat), chat: chat)
+      @system_prompts[[chat, level]] ||= system_prompt_with_index(assist_system_prompt(chat: chat, thinking: level),
+                                                                  chat: chat, thinking: level)
     end
 
     # @return [Session] current session (Engine owns create/resume)
@@ -1876,6 +1907,10 @@ module Samagotchi
         vision = turn_vision(session)
         @kernel.vision = vision if @kernel.respond_to?(:vision=)
         @kernel.sampling = turn_sampling if @kernel.respond_to?(:sampling=)
+        thinking_target = @host_registry.resolve(@effective_model_name)
+        @turn_thinking = [thinking_level(thinking_target), thinking_target]
+        @kernel.thinking = @turn_thinking.first if @kernel.respond_to?(:thinking=)
+        announce_thinking_level(*@turn_thinking)
         refuse_images!(vision) unless image_refs.empty?
         announce_guardrail_failures(on_event)
         # Plugins' slow setup that brings tools (an MCP server's first
@@ -2103,7 +2138,9 @@ module Samagotchi
     def turn_vision(session)
       target = @host_registry.resolve(@effective_model_name)
       VisionContext.new(session_dir: Session.session_dir(session.id, state_dir: session_state_dir),
-                        capability: -> { VisionSupport.for(target, profile: profile, adapter: vision_adapter(target)) })
+                        capability: lambda {
+                          VisionSupport.for(target, profile: profile, adapter: vision_adapter(target), names: model_lookup_names(target))
+                        })
     end
 
     # The effective model's request parameters (hosts: and models:
@@ -2115,6 +2152,72 @@ module Samagotchi
       SamplingSettings::EMPTY
     end
 
+    # The effective model's thinking level (Thinking.resolve), read each turn.
+    def turn_thinking
+      thinking_level(@host_registry.resolve(@effective_model_name))
+    rescue StandardError
+      Thinking::DEFAULT
+    end
+
+    # An effort on a native host, which has no knob for it: said once per
+    # session and host.
+    def announce_thinking_level(level, target)
+      return if target.entry.chat? || Thinking.native(level, profile).honoured
+
+      thinking_notice_once(:unsupported, target, :info,
+                           "#{level} isn't supported by native #{profile.name} on #{target.entry.name}; " \
+                           "thinking stays as the model has it")
+    rescue StandardError
+      nil
+    end
+
+    # Thinking off, and the model thought anyway: logged each time, said
+    # once per session and host.
+    def check_thinking_honoured(event)
+      level, target = @turn_thinking
+      chars = event[:thinking_chars].to_i
+      return unless level == :off && chars.positive? && target
+
+      Log.warn(:model, "thinking_not_honoured", level: level, host: target.entry.name, model: target.bare_model, chars: chars)
+      thinking_notice_once(:not_honoured, target, :warn,
+                           "off wasn't honoured by #{target.bare_model} on #{target.entry.name} " \
+                           "(#{chars} chars of thinking); a sampling: override on the host or model may turn it off " \
+                           "(see Thinking in docs/configuration.md)")
+    rescue StandardError
+      nil
+    end
+
+    # The host refused the level's request fields (gpt-oss can't turn
+    # thinking off) and the chat loop sent the request without them: said
+    # once per session and host, standing in for the not-honoured notice.
+    def thinking_refused(event)
+      _level, target = @turn_thinking
+      return unless target
+
+      Log.warn(:model, "thinking_refused", level: event[:level], host: target.entry.name, model: event[:model],
+                                           detail: event[:detail])
+      (@thinking_notices ||= Set.new) << [@session&.id, target.entry.name, :not_honoured]
+      thinking_notice_once(:refused, target, :warn,
+                           "#{target.entry.name} refused thinking: #{event[:level]} for #{event[:model]} (#{event[:detail]}); " \
+                           "sent without it, so thinking stays as the model has it")
+    rescue StandardError
+      nil
+    end
+
+    def thinking_notice_once(kind, target, level, text)
+      key = [@session&.id, target.entry.name, kind]
+      return unless (@thinking_notices ||= Set.new).add?(key)
+
+      hook_notify(text, level, "thinking")
+    end
+
+    # +target+'s thinking level (Thinking.resolve).
+    def thinking_level(target)
+      Thinking.resolve(target, names: model_lookup_names(target)).first
+    rescue StandardError
+      Thinking::DEFAULT
+    end
+
     def vision_adapter(target)
       target.entry.chat? ? @host_registry.adapter_for(target.entry) : nil
     rescue StandardError
@@ -2174,29 +2277,6 @@ module Samagotchi
       replace_session_messages(@session, clone_messages(checkpoint))
     end
 
-    # Backward-compatible: runs a prompt through the kernel loop without event forwarding.
-    # @param session  [Session]
-    # @param prompt   [String]
-    # @return [String] model response text
-    def process_prompt_through_kernel(session, prompt)
-      result = run_turn(session, prompt)
-      response = result.respond_to?(:text) ? result.text.to_s : result.to_s
-      if response.strip.empty?
-        session.messages << { role: "model", content: "[No response]" }
-        "[No response]"
-      else
-        response
-      end
-    end
-
-    # Public entrypoint for background session workers.
-    # @param session  [Session]
-    # @param prompt   [String]
-    # @return [String] model response
-    def process_background_prompt(session:, prompt:)
-      process_prompt_through_kernel(session, prompt)
-    end
-
     # Clone a messages array (shallow dup of each element).
     # @param messages [Array<Hash>]
     # @return [Array<Hash>]
@@ -2237,6 +2317,12 @@ module Samagotchi
       require_relative "memory_bundle/provenance"
       settings = bundle_settings
       MemoryBundle::Provenance.each_installed_holding_hooks do |bundle_name, data|
+        if data[:error]
+          Log.warn(:hooks, "bundle_manifest_invalid", echo: "[samagotchi:hooks] bundle '#{bundle_name}': #{data[:error]}; its hooks are not loaded",
+                                                      bundle: bundle_name)
+          @guardrail_failures.add("hooks (bundle #{bundle_name})", data[:error], required: false)
+          next
+        end
         bundle_dir = File.join(MemoryBundle::Provenance.bundles_dir, bundle_name)
         hooks_dir = File.join(bundle_dir, "hooks")
         if (data[:trust_level] || "experimental").to_s == "experimental"
@@ -2584,13 +2670,18 @@ module Samagotchi
             event = event.merge(text: delta[:text], thinking: delta[:thinking]) if enrich == :always
           end
         end
+        # The chat loop asked again without the thinking fields: a notice,
+        # not an event of its own.
+        next thinking_refused(event) if event[:type] == :thinking_refused
+
         emit_event(on_event, event)
+        check_thinking_honoured(event) if event[:type] == :generation_completed
       end
     end
 
     def emit_event(on_event, event)
       # Capture used memories synchronously in the turn thread.
-      begin
+      read_names = begin
         capture_used_memory_from_event(event)
       rescue StandardError
         nil
@@ -2609,6 +2700,11 @@ module Samagotchi
       # Persistent subscribers: receive a copy with a locally-monotonic
       # `event_seq`, fan out with per-subscriber error isolation.
       @session_observer.notify(event)
+      # Every memory read, after its tool_call_started: the whole list for
+      # the UIs' memory line, and the names this call read (read_names).
+      return unless read_names
+
+      emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names, read_names: read_names })
     end
 
     # The window as the target's loop would see it (see ChatLoop#context_window:
@@ -2704,9 +2800,11 @@ module Samagotchi
 
     # Only Qwen has an explicit thinking-close marker, so only Qwen can
     # reliably have this preamble parsed back out of its thinking block.
-    def turn_preamble_instruction
+    # With thinking off there is no thinking to begin with it.
+    def turn_preamble_instruction(thinking = nil)
       return "" unless profile.name == "qwen36"
       return "" if Samagotchi::Config.get("thinking.turn_preamble") == false
+      return "" if (thinking || turn_thinking) == :off
 
       "\nTurn preamble: as the very first line of your thinking, write \"TURN: \" followed by a short present-tense action phrase (max 8 words) describing what you are about to do, e.g. \"TURN: reading project config\". Then continue reasoning normally.\n"
     end
@@ -2715,12 +2813,13 @@ module Samagotchi
 
     # @param chat [Boolean] for the chat loop: no tool declarations, call
     #   syntax or turn preamble (its tools go as schemas with each request)
-    def assist_system_prompt(chat: false)
+    # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
+    def assist_system_prompt(chat: false, thinking: nil)
       return chat_system_prompt if chat
 
       declarations = tool_declarations
       hint = tool_call_hint
-      turn_preamble = turn_preamble_instruction
+      turn_preamble = turn_preamble_instruction(thinking)
 
       <<~SYS
         You are Chi (pronounced "chee"), the friendly name for the Samagotchi assistant harness. You have access to the following tools:
@@ -2800,15 +2899,12 @@ module Samagotchi
 
     # @param chat [Boolean] no Gemma thinking token (the chat API's template
     #   decides about thinking)
-    def system_prompt_with_index(base, chat: false)
+    # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
+    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 = if !chat && profile.name == "gemma4" && ENV["THINKING_MODE"] != "false"
-                         "<|think|>\n"
-                       else
-                         ""
-                       end
+      thinking_token = chat ? "" : Thinking.native(thinking || turn_thinking, profile).system_token
       memory_sections = [
         "Project memories:\n#{project_index}",
         "System memories:\n#{system_index}"
@@ -2913,8 +3009,9 @@ module Samagotchi
       @activated_memory_names ||= []
     end
 
-    # System-prompt builders the TerminalUI seeds its conversation from.
-    public :tool_call_hint, :assist_system_prompt, :system_prompt_with_index, :activated_memory_names
+    # The base prompt (specs, plugins' declarations) and the --memory names
+    # the TerminalUI mirrors into its status line.
+    public :assist_system_prompt, :activated_memory_names
 
     def split_memory_scope(raw)
       value = raw.to_s.strip

data/lib/samagotchi/gem_update.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "open3"
+require "rbconfig"
+require "rubygems/package"
+require_relative "version"
+
+module Samagotchi
+  # The gem part of `chi update`: the newest samagotchi on rubygems, and a
+  # `gem install` of it through this Ruby's own gem command (the real
+  # interpreter's bindir, not a shim: the same under mise, rbenv and asdf).
+  #
+  # SAMAGOTCHI_UPDATE_GEM_FILE=<path to a .gem> (hidden, for smokes) makes that
+  # file the newest version and installs it instead.
+  class GemUpdate
+    Error = Class.new(StandardError)
+
+    LATEST_URL = URI("https://rubygems.org/api/v1/versions/samagotchi/latest.json")
+    # Not SAMAGOTCHI_UPDATE_GEM: that is the env form of config update.gem.
+    LOCAL_ENV = "SAMAGOTCHI_UPDATE_GEM_FILE"
+    TIMEOUT = 5
+
+    # source is what `gem install` takes: the gem's name, or a .gem file.
+    Latest = Struct.new(:version, :source, keyword_init: true)
+
+    # Runs a command without a shell; [output, success].
+    class Runner
+      def run(argv)
+        output, status = Open3.capture2e(*argv)
+        [output, status.success?]
+      rescue SystemCallError => e
+        [e.message, false]
+      end
+    end
+
+    # @param fetcher [#call, nil] → the latest.json body (specs)
+    def initialize(env: ENV, fetcher: nil, runner: Runner.new, gem_bin: File.join(RbConfig::CONFIG["bindir"], "gem"))
+      @env = env
+      @fetcher = fetcher || method(:fetch)
+      @runner = runner
+      @gem_bin = gem_bin
+    end
+
+    # @return [Latest]
+    # @raise [Error] when it can't be found out (offline, a bad answer)
+    def latest
+      local = @env[LOCAL_ENV].to_s
+      return Latest.new(version: Gem::Package.new(local).spec.version.to_s, source: local) unless local.empty?
+
+      version = JSON.parse(@fetcher.call.to_s)["version"].to_s
+      raise Error, "rubygems.org answered without a version" if version.empty? || !Gem::Version.correct?(version)
+
+      Latest.new(version: version, source: "samagotchi")
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "#{e.class}: #{e.message}".lines.first.strip
+    end
+
+    def newer?(latest, current = VERSION)
+      Gem::Version.new(latest.version) > Gem::Version.new(current)
+    end
+
+    def install_argv(latest)
+      argv = [@gem_bin, "install", latest.source, "--no-document"]
+      latest.source == "samagotchi" ? argv + ["-v", latest.version] : argv
+    end
+
+    # @return [Array(String, Boolean)] gem's output, success
+    def install(latest)
+      @runner.run(install_argv(latest))
+    end
+
+    private
+
+    def fetch
+      Net::HTTP.start(LATEST_URL.host, LATEST_URL.port, use_ssl: true, open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+        request = Net::HTTP::Get.new(LATEST_URL)
+        request["User-Agent"] = USER_AGENT
+        response = http.request(request)
+        raise Error, "rubygems.org answered #{response.code}" unless response.code == "200"
+
+        response.body
+      end
+    end
+  end
+end