samagotchi 0.2.0 → 0.4.0

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

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,
@@ -36,17 +38,27 @@ module Samagotchi
             label: label,
             command: targets&.command,
             paths: targets && !targets.paths.empty? ? targets.paths : nil,
+            # No command or path (an MCP tool): its arguments, as the question.
+            args: args_for_card(targets),
             cwd: targets&.cwd,
             repo_root: targets&.repo_root,
             branch: verdict.context&.branch(targets&.cwd || verdict.context.cwd),
             rule: verdict.rule,
             source: verdict.source,
             reason: verdict.reason,
-            scopes: scopes
+            scopes: scopes,
+            preview: preview
           }.compact
         }
       end
 
+      def args_for_card(targets)
+        return nil if targets.nil? || targets.command || !targets.paths.empty?
+
+        text = Approval.args_text(targets.args, limit: ARGS_CHARS)
+        text.empty? ? nil : text
+      end
+
       # Settle +verdict+ from open_question's result.
       # @param answer [Hash, String] {selected_indices:, freeform:} or {error:}
       # @param scopes [Array<String>] the offered scopes, in option order
@@ -103,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(", "))
@@ -118,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/guardrails/scratch_writes.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "protected_paths"
+require_relative "../memory_paths"
+
+module Samagotchi
+  module Guardrails
+    # A `chi scratch` session saves nothing: write and edit on a file under
+    # the memories folder (system and project memories, overlays, index.md)
+    # are denied. (memory_write itself refuses in a scratch session, with a
+    # shorter answer: Engine.) Reading them is fine. execute can still
+    # write there (as with ProtectedPaths).
+    class ScratchWrites
+      REASON = "scratch session: nothing is saved"
+      RULE = "scratch-session"
+
+      # @param memories_dir [#call] the memories folder (MemoryPaths.system_dir),
+      #   read per call like the memory tools do
+      def initialize(memories_dir: -> { MemoryPaths.system_dir })
+        @memories_dir = memories_dir
+      end
+
+      # Vote on +verdict+.
+      def check(verdict)
+        return verdict unless writes_memory?(verdict)
+
+        verdict.deny!(REASON, rule: RULE, source: ProtectedPaths::SOURCE, decided_by: "core")
+      end
+
+      private
+
+      def writes_memory?(verdict)
+        targets = verdict.targets
+        return false unless targets && %w[write edit].include?(targets.tool)
+
+        targets.paths.any? { |path| ProtectedPaths.within?(ProtectedPaths.real(path), @memories_dir.call) }
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails.rb

@@ -6,6 +6,7 @@ require_relative "guardrails/targets"
 require_relative "guardrails/approval"
 require_relative "guardrails/approvals"
 require_relative "guardrails/protected_paths"
+require_relative "guardrails/scratch_writes"
 require_relative "guardrails/load_failures"
 require_relative "guardrails/rules"
 require_relative "guardrails/gate"

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,11 @@ 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;
+    # 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, 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
@@ -86,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])
+                              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)
@@ -116,10 +119,6 @@ module Samagotchi
       nil
     end
 
-    def entry_names
-      @entries.keys
-    end
-
     def default_entry
       @entries["default"] || @entries.values.first
     end
@@ -148,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_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/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")