samagotchi 0.3.0 → 0.4.0

data/lib/samagotchi/thinking.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Samagotchi
+  # How much a model thinks: one level per model, host or run, mapped to each
+  # backend's own switch. The one place that knows the mapping.
+  #
+  #   off      thinking off where the backend can do it
+  #   low, medium, high   the effort a chat host is asked for
+  #   default  chi sends nothing: the provider's or template's own default
+  #
+  # Order (#resolve): --thinking / SAMAGOTCHI_THINKING_LEVEL, then
+  # models.<key>.thinking, hosts.<name>.thinking, thinking.level in
+  # config.yml, then default.
+  module Thinking
+    LEVELS = %i[off low medium high default].freeze
+    EFFORTS = %i[low medium high].freeze
+    DEFAULT = :default
+
+    # Gemma 4 turns thinking on with this token at the start of the system prompt.
+    GEMMA_THINK_TOKEN = "<|think|>\n"
+    # An empty thought after the Qwen assistant cue: the model answers at once
+    # (what the server's own template does with enable_thinking false).
+    QWEN_EMPTY_THOUGHT = "<think>\n\n</think>\n\n"
+
+    # What a native prompt gets for a level: the text before the system
+    # prompt, the text after the assistant cue, and whether the level means
+    # anything there (low/medium/high have no native knob).
+    Native = Data.define(:system_token, :prefill, :honoured)
+
+    module_function
+
+    # A configured value as a level; nil when unset or not a level (that
+    # warns once, naming +where+). YAML reads an unquoted `off` as false,
+    # which is :off; true (`on`) isn't a level.
+    # @return [Symbol, nil]
+    def level(value, where)
+      return nil if value.nil?
+      return :off if value == false || value.to_s.strip.downcase == "false"
+
+      text = value.to_s.strip.downcase
+      return text.to_sym if LEVELS.include?(text.to_sym)
+
+      hint = value == true || %w[true on].include?(text) ? "; `on` isn't one, `default` leaves it to the model" : ""
+      ConfigFile.warn_once "Warning: #{where}: thinking must be one of #{LEVELS.join(', ')}#{hint}; ignored"
+      nil
+    end
+
+    # The level for +target+ and where it came from ("--thinking",
+    # "models: qwen", "hosts.work", "thinking.level"; nil for the default).
+    # @param target [HostRegistry::ModelTarget]
+    # @param names [Array<String>, nil] the model's lookup names (Engine#model_lookup_names)
+    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @return [Array(Symbol, String|nil)]
+    def resolve(target, names: nil, models: nil)
+      global, origin = global_level
+      return [global, origin == :cli ? "--thinking" : "SAMAGOTCHI_THINKING_LEVEL"] if global && %i[cli env].include?(origin)
+
+      models ||= begin
+        ConfigFile.model_settings
+      rescue StandardError
+        {}
+      end
+      names ||= [target.model, target.bare_model]
+      key, value = ConfigFile.model_setting(names, :thinking, models: models)
+      return [value, "models: #{key}"] if key
+
+      host = target.entry.respond_to?(:thinking) ? target.entry.thinking : nil
+      return [host, "hosts.#{target.entry.name}"] if host
+      return [global, "thinking.level"] if global
+
+      [DEFAULT, nil]
+    end
+
+    # thinking.level as a level and its origin (:cli, :env, :file), or nil.
+    def global_level
+      raw, origin = Config.get_with_origin("thinking.level")
+      return nil if origin == :default
+
+      where = { cli: "--thinking", env: "SAMAGOTCHI_THINKING_LEVEL" }.fetch(origin, "thinking.level")
+      value = level(raw, where)
+      value ? [value, origin] : nil
+    rescue StandardError
+      nil
+    end
+
+    # Request fields for an OpenAI-style chat host. off sends both switches
+    # (the template's enable_thinking and the OpenAI-style reasoning_effort
+    # "none"): llama.cpp, Splash and OpenRouter each honour one of them.
+    # An effort goes as reasoning_effort (llama.cpp ignores it). default
+    # sends nothing.
+    # @return [Hash] frozen
+    def chat_fields(level)
+      case level
+      when :off then { chat_template_kwargs: { enable_thinking: false }.freeze, reasoning_effort: "none" }.freeze
+      when *EFFORTS then { reasoning_effort: level.to_s }.freeze
+      else {}.freeze
+      end
+    end
+
+    # The native prompt's switch for +level+ under +profile+.
+    # @param profile [ModelProfile]
+    # @return [Native]
+    def native(level, profile)
+      off = level == :off
+      honoured = !EFFORTS.include?(level)
+      case profile&.name
+      when "gemma4" then Native.new(system_token: off ? "" : GEMMA_THINK_TOKEN, prefill: "", honoured: honoured)
+      when "qwen36" then Native.new(system_token: "", prefill: off ? QWEN_EMPTY_THOUGHT : "", honoured: honoured)
+      else Native.new(system_token: "", prefill: "", honoured: level == DEFAULT)
+      end
+    end
+  end
+end

data/lib/samagotchi/tool_runner.rb

@@ -4,6 +4,8 @@ require_relative "tool_activity"
 require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
+require_relative "edit_preview"
+require_relative "tools/tool_path"
 
 module Samagotchi
   # The single per-call path both loops use: the tool_call_started and
@@ -17,6 +19,10 @@ module Samagotchi
     # that returns many screenshots can't flood the context).
     MAX_IMAGES_PER_RESULT = 4
 
+    # file_before for a call that isn't an edit/write, or won't run.
+    NOT_AN_EDIT = Object.new.freeze
+    private_constant :NOT_AN_EDIT
+
     # @param kernel [KernelLoop] read lazily: Engine sets its hooks after
     #   the kernel is built.
     def initialize(kernel)
@@ -29,7 +35,9 @@ module Samagotchi
     #   shown_params: the params line the live row showed, and shown_label:
     #   its label ("chrome: screenshot"), only for a tool that isn't built in
     #   (the loops save them with the result, so a reload without the plugin
-    #   shows the same row)
+    #   shows the same row), and diff: what an edit/write changed in its
+    #   file (EditPreview.change; also on tool_call_completed, never in the
+    #   model's output)
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       # The gate runs first, so tool_call_started shows the call that runs.
@@ -45,7 +53,9 @@ module Samagotchi
       # The ask comes after tool_call_started: the UI shows the tool line,
       # then the approval under it.
       settle_ask(verdict) if verdict.ask?
+      before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
       result = verdict.deny? ? denied(call, verdict) : dispatch(call)
+      diff = file_change(call, before)
       result = approved(result, verdict) if verdict.allow? && verdict.decided_by
       result, images = attach_images(call, result) if result[:images]
 
@@ -61,17 +71,40 @@ module Samagotchi
       completed = { type: :tool_call_completed, iteration: iteration, call_count: call_count, call_index: call_index,
                     tool: call[:name], output: capped, output_truncated: truncated, activity: result[:activity] }
       completed[:images] = images if images&.any?
+      completed[:diff] = diff if diff
       emit(on_stream_event, completed)
 
       run = { output: output, capped_output: capped, truncated: truncated, activity: result[:activity] }
       run[:images] = images if images&.any?
       run[:shown_params] = params if params && plugin_tool?(call[:name])
       run[:shown_label] = label if label
+      run[:diff] = diff if diff
       run
     end
 
     private
 
+    # edit/write only: the file just before the call runs. The row diffs it
+    # with the file after, whatever the result says, so an edit that fails
+    # after writing still shows its change and one that wrote nothing shows
+    # none.
+    def file_before(call)
+      return NOT_AN_EDIT unless EditPreview.tool?(call[:name])
+
+      EditPreview.snapshot(Tools::ToolPath.normalize(call[:path]))
+    rescue StandardError
+      NOT_AN_EDIT
+    end
+
+    def file_change(call, before)
+      return nil if before.equal?(NOT_AN_EDIT)
+
+      EditPreview.change(before, EditPreview.snapshot(Tools::ToolPath.normalize(call[:path])))
+    rescue StandardError => e
+      Log.warn(:turn, "edit_diff_failed", tool: call[:name], error: "#{e.class}: #{e.message}")
+      nil
+    end
+
     # A tool's output can hold bytes that aren't UTF-8 (`printf '\xff'`, a
     # binary file). They become "?" here, before the output reaches the
     # conversation, the events and the saved session: JSON.generate raises

data/lib/samagotchi/tools/ask_user_question.rb

@@ -19,30 +19,50 @@ module Samagotchi
 
       def self.name        = NAME
 
-      # Direct invocation (used in specs / headless fallback).
-      # When a blocking handler is not injected, return an instructional error so the
-      # model falls back to plain text rather than hanging.
-      def self.call(question, options: nil, header: nil, multi_select: nil, allow_freeform: nil)
-        question = question.to_s.strip
-        return "Error: question is required" if question.empty?
-
-        opts = normalize_options(options)
-        return "Error: options must be an array of 2-8 non-empty strings" if opts.nil?
-
-        header = header.to_s.strip
-        header = nil if header.empty?
-        ms = to_bool(multi_select)
-        af = to_bool(allow_freeform)
-
-        payload = {
+      QUESTION_REQUIRED_ERROR = "Error: ask_user_question requires 'question'"
+
+      # The tool result for a wrong number of options.
+      def self.options_count_error(count)
+        "Error: ask_user_question requires 2-8 options (got #{count}). Provide e.g. options=[\"Cats\",\"Dogs\"]"
+      end
+
+      # The one check of a model's ask_user_question call (the kernel runs it
+      # before the question opens). Dumb-model tolerant: options may be a JSON
+      # string or bracket noise, a single option is salvaged, missing options
+      # are read from the call's content, booleans may be strings; wire control
+      # tokens are stripped from the question and header.
+      # @param call [Hash] the tool call (question:/content:, options:, header:,
+      #   multi_select:, allow_freeform:)
+      # @return [Hash, String] the payload {question:, options:, header:,
+      #   multi_select:, allow_freeform:} (no header key when empty), or the
+      #   plain-text error the model gets as the tool result
+      def self.validate(call)
+        question = strip_wire_tokens(call[:question] || call[:content])
+        return QUESTION_REQUIRED_ERROR if question.empty?
+
+        options = normalize_options_lenient(call[:options])
+        options = normalize_options_lenient(call[:content].to_s) if options.empty? && call[:content]
+        return options_count_error(options.size) if options.empty? || options.size > 8
+
+        header = strip_wire_tokens(call[:header])
+        {
           question: question,
-          options: opts,
-          header: header,
-          multi_select: ms,
-          allow_freeform: af
+          options: options,
+          header: (header unless header.empty?),
+          multi_select: to_bool(call[:multi_select]),
+          allow_freeform: to_bool(call[:allow_freeform])
         }.compact
+      end
+
+      # Booleans the way models send them (Gemma passes "true"/"false").
+      def self.to_bool(value)
+        return value if value == true || value == false
 
-        JSON.pretty_generate(payload)
+        %w[1 true yes on].include?(value.to_s.strip.downcase)
+      end
+
+      def self.strip_wire_tokens(text)
+        text.to_s.gsub(/<\|[^|]*\|>/, "").gsub(/<\||\|>/, "").strip
       end
 
       # Normalize options param: accept Array or JSON string; strip, reject empty.
@@ -135,18 +155,6 @@ module Samagotchi
 
         arr.map { |v| sanitize_option(v) }.reject { |v| v.nil? || v.empty? }
       end
-
-      def self.to_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
-      end
-      private_class_method :to_bool
     end
   end
 end

data/lib/samagotchi/tools/edit.rb

@@ -22,9 +22,25 @@ module Samagotchi
 
       def self.call(content, path:, start_line: nil, end_line: nil)
         path = ToolPath.normalize(path)
+        result = apply(content, path: path, start_line: start_line, end_line: end_line)
+        return result if result.is_a?(String)
+
+        updated, message = result
+        File.write(path, updated)
+        message
+      rescue => e
+        "Error: #{e.message}"
+      end
+
+      # The edit without the write: [updated, message] or "Error: …", with
+      # exactly the strings call returns. +read+ reads the file, so a dry run
+      # (EditPreview) can reuse a copy it already has; each mode keeps its own
+      # check order (exact: tags first; range: file not found first).
+      def self.apply(content, path:, start_line: nil, end_line: nil, read: ->(p) { File.read(p) })
+        path = ToolPath.normalize(path)
 
         if range_requested?(start_line, end_line)
-          return call_range_mode(content, path: path, start_line: start_line, end_line: end_line)
+          return apply_range_mode(content, path: path, start_line: start_line, end_line: end_line, read: read)
         end
 
         old_text = extract_tag(content, "old")
@@ -35,7 +51,7 @@ module Samagotchi
         return "Error: <old> block is empty" if old_text.empty?
         return "Error: file not found: #{path}" unless File.exist?(path)
 
-        source = File.read(path)
+        source = read.(path)
         count  = count_occurrences(source, old_text)
 
         return "Error: old text not found in #{path}" if count == 0
@@ -43,13 +59,12 @@ module Samagotchi
 
         idx     = source.index(old_text)
         updated = source[0, idx] + new_text + source[idx + old_text.length..]
-        File.write(path, updated)
-        "Edited #{path}: replaced #{old_text.bytesize} bytes with #{new_text.bytesize} bytes"
+        [updated, "Edited #{path}: replaced #{old_text.bytesize} bytes with #{new_text.bytesize} bytes"]
       rescue => e
         "Error: #{e.message}"
       end
 
-      def self.call_range_mode(content, path:, start_line:, end_line:)
+      def self.apply_range_mode(content, path:, start_line:, end_line:, read:)
         return "Error: file not found: #{path}" unless File.exist?(path)
 
         new_text = extract_tag(content, "new")
@@ -59,7 +74,7 @@ module Samagotchi
         return start_num if start_num.is_a?(String)
         return "Error: start_line must be provided for range edits" if start_num.nil?
 
-        source = File.read(path)
+        source = read.(path)
         lines = source.lines
         total_lines = lines.length
 
@@ -102,15 +117,14 @@ module Samagotchi
         # first suffix line isn't concatenated onto the last replacement line.
         normalized = (!new_text.empty? && !suffix.empty? && !new_text.end_with?("\n")) ? new_text + "\n" : new_text
         updated = prefix + normalized + suffix
-        File.write(path, updated)
 
         replaced_lines = (end_value - start_num) + 1
         new_line_count = new_text.lines.length
-        "Edited #{path}: replaced lines #{start_num}-#{end_value} (#{replaced_lines} lines) with #{new_line_count} lines#{clamp_note}"
+        [updated, "Edited #{path}: replaced lines #{start_num}-#{end_value} (#{replaced_lines} lines) with #{new_line_count} lines#{clamp_note}"]
       rescue => e
         "Error: #{e.message}"
       end
-      private_class_method :call_range_mode
+      private_class_method :apply_range_mode
 
       # Count non-overlapping literal occurrences of +needle+ in +haystack+.
       def self.count_occurrences(haystack, needle)

data/lib/samagotchi/tools/write.rb

@@ -14,6 +14,10 @@ module Samagotchi
       def self.name        = NAME
 
       def self.call(content, path:)
+        # A native call without content/text arrives as nil; check before
+        # touching the file, or File.write(path, nil) would empty it.
+        return "Error: missing content" unless content.is_a?(String)
+
         path = ToolPath.normalize(path)
         FileUtils.mkdir_p(File.dirname(path))
         File.write(path, content)

data/lib/samagotchi/turn_flow.rb

@@ -143,9 +143,19 @@ module Samagotchi
       @checkpoint = nil
     end
 
-    # A reminder turn ran. The checkpoint stays only for a pending offer.
+    # A reminder turn is about to run: a pending continue offer goes, as for
+    # a new prompt (the partial turn stays), so a later "no" can't roll the
+    # reminder's exchange back with it.
+    # @return [Boolean] whether an offer was pending
+    def before_reminder_turn
+      offered = awaiting_continue?
+      @offer = nil
+      offered
+    end
+
+    # A reminder turn ran: the rollback window closes.
     def after_reminder_turn
-      @checkpoint = nil unless awaiting_continue?
+      @checkpoint = nil
     end
 
     private