samagotchi 0.3.0 → 0.4.0

data/lib/samagotchi/send_command.rb

@@ -4,6 +4,7 @@ require_relative "session"
 require_relative "session_manager"
 require_relative "context_quote"
 require_relative "reply_wait"
+require_relative "image_store"
 
 module Samagotchi
   # `chi send`: put text into sessions as the user's message, the same as
@@ -19,16 +20,23 @@ module Samagotchi
     # No live worker this long while waiting: it died before it could mark
     # the session (a worker takes well under a second to start).
     WORKER_GONE_AFTER = 5
+    # The Bridge's cap on one turn's images (Bridge::MAX_TURN_IMAGES).
+    MAX_IMAGES = 20
 
     USAGE = <<~TEXT
-      Usage: chi send [-m TEXT] (ID|PREFIX)...
-             chi send --new [--dir DIR] [--model M] [-m TEXT]
-             chi send --wait [--timeout S] [-m TEXT] (--new | ID)
+      Usage: chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...
+             chi send --new [--dir DIR] [--model M] [-m TEXT] [--image PATH]...
+             chi send --wait [--timeout S] [-m TEXT] [--image PATH]... (--new | ID)
              chi send --wait [--timeout S] ID
         Sends a message to each session, as if typed in it: a turn starts,
         or a running one picks it up. A stopped session's worker starts.
         -m TEXT     the message; stdin, when piped too, goes above it as a
                     quote (context); without -m, stdin is the message
+        --image PATH
+                    an image sent with the message (png, jpeg, gif, webp;
+                    others converted, large ones downscaled); repeat for
+                    more, up to 20. Needs text too (-m or stdin) and a
+                    model that sees images
         --new       start a new session with the message instead, as the
                     web does, and print its id
         --dir DIR   (--new) its folder, the project it belongs to; default
@@ -65,6 +73,11 @@ module Samagotchi
       # With --wait stdout is the answer alone.
       @info = options[:wait] ? @stderr : @stdout
       prompt = compose(utf8(read_stdin), utf8(options[:message]))
+      # Before the wait-only case, which would drop the images.
+      if prompt.nil? && !options[:images].empty?
+        usage_error("--image needs a message: pass -m TEXT or pipe it in")
+        return 2
+      end
       return run_wait_only(options) if prompt.nil? && options[:wait] && !options[:new]
       unless prompt
         usage_error("no message: pass -m TEXT or pipe it in")
@@ -76,6 +89,7 @@ module Samagotchi
         @stderr.puts("chi send: #{e.message}")
         return 1
       end
+      return 2 unless ingest_images(options[:images])
 
       return run_new(prompt, options) if options[:new]
       return run_wait(prompt, options) if options[:wait]
@@ -91,12 +105,14 @@ module Samagotchi
         deliver(id, prompt)
       end
       results.all? ? 0 : 1
+    ensure
+      FileUtils.rm_rf(@image_dir) if @image_dir
     end
 
     private
 
     def parse
-      options = { ids: [] }
+      options = { ids: [], images: [] }
       until @argv.empty?
         arg = @argv.shift
         case arg
@@ -110,6 +126,8 @@ module Samagotchi
         when "--dir", "--model"
           options[arg.delete_prefix("--").to_sym] = @argv.shift or return usage_error("#{arg} needs a value")
         when /\A--(dir|model)=(.*)\z/m then options[Regexp.last_match(1).to_sym] = Regexp.last_match(2)
+        when "--image" then options[:images] << (@argv.shift or return usage_error("#{arg} needs a value"))
+        when /\A--image=(.*)\z/m then options[:images] << Regexp.last_match(1)
         when "--wait" then options[:wait] = true
         when "--timeout" then options[:timeout] = @argv.shift or return usage_error("#{arg} needs a value")
         when /\A--timeout=(.*)\z/ then options[:timeout] = Regexp.last_match(1)
@@ -127,6 +145,7 @@ module Samagotchi
         return usage_error("--timeout takes seconds") unless options[:timeout]&.positive?
       end
       return usage_error("--wait takes one session") if options[:wait] && options[:ids].uniq.size > 1
+      return usage_error("at most #{MAX_IMAGES} images") if options[:images].size > MAX_IMAGES
       return new_options(options) if options[:new]
       %i[dir model].each { |key| return usage_error("--#{key} needs --new") if options[key] }
       return usage_error("give session ids") if options[:ids].empty?
@@ -180,18 +199,27 @@ module Samagotchi
 
     # A worker session like the web start page's: saved as running with the
     # message before its worker spawns, so lists and the web show it at
-    # once. The full id, so a script can pass it on. The model name isn't
-    # checked here (nor in the web): a wrong one fails in the worker.
+    # once. The full id, so a script can pass it on. Only the model's host
+    # is checked here (in spawn_session, as in the web): a wrong model id
+    # fails in the worker.
     # @return [Integer] the exit status
     def run_new(prompt, options)
+      images = !@images.empty?
       begin
-        session = SessionManager.spawn_session(prompt: prompt, working_directory: options[:dir],
-                                               model_name: options[:model], state_dir: @state_dir)
+        # With images the web's way: idle (the message names it in the
+        # lists), the images copied in, then the message as a turn.
+        start = images ? { prompt: nil, title: prompt } : { prompt: prompt }
+        session = SessionManager.spawn_session(**start, working_directory: options[:dir],
+                                                        model_name: options[:model], state_dir: @state_dir)
       rescue StandardError => e
         error_line("chi send: could not start a session: #{e.message}")
         return 1
       end
-      @info.puts("#{session.id}  started")
+      if images
+        return 1 unless deliver_new(session, prompt)
+      else
+        @info.puts("#{session.id}  started")
+      end
       return 0 unless options[:wait]
 
       wait_for_reply(session.id, cursor: nil, baseline: { messages: session.messages.size, question_id: nil },
@@ -269,21 +297,56 @@ module Samagotchi
       0
     end
 
+    # A new idle session's first turn, with the images. Its worker's Bridge
+    # first: deliver_turn wakes a worker when none owns the session yet,
+    # and the spawned one takes its lock only once it runs.
+    # @return [Boolean] whether the message was queued
+    def deliver_new(session, prompt)
+      dir = Session.session_dir(session.id, state_dir: @state_dir)
+      result = nil
+      begin
+        refs = copy_images(dir)
+        if BridgeClient.wait_for(session.id, session_dir: dir, timeout: SessionManager::TURN_BRIDGE_WAIT)
+          result = SessionManager.deliver_turn(session.id, prompt: prompt, client_id: CLIENT_ID, images: refs,
+                                                           state_dir: @state_dir)
+        end
+      rescue StandardError => e
+        @info.puts("#{session.id}  failed: #{e.message}")
+        return false
+      end
+      # Kept, not deleted: it holds the images, and the message shows as
+      # its preview; the user can attach and send it again.
+      unless result
+        @info.puts("#{session.id}  failed: its worker did not start; the session is kept (chi --attach #{session.id})")
+        return false
+      end
+      unless result[:status] == :accepted
+        @info.puts("#{session.id}  failed: #{result.dig(:ack, "detail") || "could not queue it"}")
+        return false
+      end
+
+      @info.puts("#{session.id}  started#{with_images}")
+      true
+    end
+
     # @return [Boolean] whether the message was queued
     def deliver(id, prompt)
       short = id[0, 8]
       owner = SessionManager.session_owner(id, state_dir: @state_dir)
       running = owner && Session.load(id, state_dir: @state_dir).status == Session::STATUS_RUNNING
-      result = SessionManager.deliver_turn(id, prompt: prompt, client_id: CLIENT_ID, state_dir: @state_dir)
+      refs = copy_images(Session.session_dir(id, state_dir: @state_dir))
+      result = SessionManager.deliver_turn(id, prompt: prompt, client_id: CLIENT_ID, images: refs, state_dir: @state_dir)
       unless result[:status] == :accepted
         @info.puts("#{short}  failed: #{result.dig(:ack, "detail") || "could not queue it"}")
         return false
       end
 
+      # A busy worker runs a message with images as its own next turn
+      # rather than merging it into the running one.
       note = if owner.nil? then " (started its worker)"
-             elsif running then " (the running turn picks it up)"
+             elsif running then refs.empty? ? " (the running turn picks it up)" : " (runs after the current turn)"
              end
-      @info.puts("#{short}  sent#{note}")
+      @info.puts("#{short}  sent#{with_images}#{note}")
       true
     rescue SessionManager::OwnedByTUI
       @info.puts("#{short}  refused: it is open in a chi REPL; messages need attached mode")
@@ -293,6 +356,38 @@ module Samagotchi
       false
     end
 
+    # Each --image read, converted and downscaled once, into a scratch
+    # session dir; each target then gets copies of the stored files. A file
+    # that can't be sent stops everything before anything is sent.
+    # @return [Boolean] false after the error line
+    def ingest_images(paths)
+      @images = []
+      return true if paths.empty?
+
+      @image_dir = Dir.mktmpdir("chi-send-images")
+      @images = paths.map { |path| ImageStore.ingest(@image_dir, path: path) }
+      true
+    rescue ImageStore::Error => e
+      error_line("chi send: #{e.message}")
+      false
+    end
+
+    # The images' files copied into a session dir, as the refs a turn takes.
+    def copy_images(session_dir)
+      @images.map do |ref|
+        ImageStore.copy_file(ref, from: @image_dir, to: session_dir)
+        { file: ref[:file], name: ref[:name] }
+      end
+    end
+
+    def with_images
+      case @images.size
+      when 0 then ""
+      when 1 then " with 1 image"
+      else " with #{@images.size} images"
+      end
+    end
+
     # The text as UTF-8 whatever the locale says: with no LANG/LC_* (an app
     # started from Finder, launchd) stdin reads as US-ASCII and ARGV as
     # binary. Invalid bytes become U+FFFD rather than an error.

data/lib/samagotchi/session_commands.rb

@@ -15,8 +15,10 @@ module Samagotchi
   # the Engine and its TurnFlow; the host prints the result's output and
   # runs a continue turn when asked to (#run never runs a turn).
   #
-  # /stats, /recap and /exit are the UI's own: they are in the registry
-  # (local: for Tab and help) but #run never runs them.
+  # /stats, /recap, /exit, /quit, /archive and /detach are the terminal
+  # UIs' own: they are in the registry (local:) for Tab and help, and so
+  # both TUIs read the same words (Registry#lookup_local gives the entry,
+  # its id says what to do), but #run never runs them.
   class SessionCommands
     MODEL_COMMAND = "/model"
     MODELS_COMMAND = "/models"
@@ -30,6 +32,8 @@ module Samagotchi
     SHELL_BANG_PREFIX = "!"
     RESERVED_MODEL_ARGS = %w[clear default none off].freeze
     ALIAS_USAGE = "usage /model <model> --alias <name> [--default]"
+    # /exit --delete: delete the session on the way out.
+    EXIT_DELETE_FLAG = "--delete"
 
     # @!attribute status [Symbol] :ok, or :error when the line was refused
     # @!attribute output [String, nil] what to tell the user
@@ -66,13 +70,28 @@ module Samagotchi
       registry.register(HELP_COMMAND, "list the commands, the bundles' too", anytime: true) { |_text| reply(help_listing) }
       registry.register("/stats", "show the session's stats", local: true)
       registry.register("/recap", "show the session's recap", local: true)
-      registry.register("/exit", "leave (--delete also deletes the session)", local: true)
-      registry.register("/archive", "leave and archive the session: hidden from the lists, kept for good", local: true)
-      registry.register("/quit", "leave, like /exit", local: true, uis: [:attached])
-      registry.register("/detach", "leave and keep the worker running", local: true, uis: [:attached])
+      # Bare `exit` too; any case; --delete after it.
+      registry.register("/exit", "leave (--delete also deletes the session)", local: true,
+                                                                              match: exit_match("/?exit"))
+      registry.register("/quit", "leave, like /exit", id: :exit, local: true, match: exit_match("/quit"))
+      registry.register("/archive", "leave and archive the session: hidden from the lists, kept for good", local: true,
+                                                                                                          match: ->(text) { text.casecmp?("/archive") })
+      # The REPL owns its session: it answers /detach with a note, and doesn't offer it.
+      registry.register("/detach", "leave and keep the worker running", local: true, uis: [:attached],
+                                                                        match: ->(text) { text.casecmp?("/detach") })
       registry
     end
 
+    # @param word [String] the regexp source of the exit word
+    def self.exit_match(word)
+      pattern = /\A#{word}(?:\s+#{EXIT_DELETE_FLAG})?\z/i
+      ->(text) { text.match?(pattern) }
+    end
+    private_class_method :exit_match
+
+    # @return [Boolean] an exit line (/exit, /quit, exit) that deletes the session too
+    def self.delete_on_exit?(line) = line.to_s.split.last.to_s.casecmp?(EXIT_DELETE_FLAG)
+
     # The built-ins alone, for callers without an Engine (an attached TUI
     # before its snapshot names the session's commands, specs).
     # @return [Commands::Registry] frozen
@@ -277,15 +296,18 @@ module Samagotchi
     def model(text)
       output, switched = model_command(text)
       reply(output, changed: switched ? [:model] : [])
+    rescue ModelProfile::MissingModel => e
+      # A model qualified with an unknown host: nothing switched.
+      reply(e.message, status: :error)
     end
 
     # @return [Array(String, Boolean)] the message, and whether the model changed
     def model_command(input)
       suffix = input.delete_prefix(MODEL_COMMAND).strip
       if suffix.empty?
-        return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}", false] if model_name == @default_model
+        return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}#{thinking_note}", false] if model_name == @default_model
 
-        return ["runtime model: #{model_name}#{model_note("default: #{@default_model}")}#{served_note}#{sampling_note}", false]
+        return ["runtime model: #{model_name}#{model_note("default: #{@default_model}")}#{served_note}#{sampling_note}#{thinking_note}", false]
       end
 
       # Parse flags: --default and --alias <name> / --alias=<name> (tolerant order)
@@ -420,6 +442,14 @@ module Samagotchi
       ""
     end
 
+    # "; thinking: off (models: qwen)" when the model has a level set.
+    def thinking_note
+      summary = @engine.respond_to?(:thinking_summary) ? @engine.thinking_summary : nil
+      summary ? "; thinking: #{summary}" : ""
+    rescue StandardError
+      ""
+    end
+
     # " (default: x, profile=qwen36, name)": +extra+ and the prompt profile,
     # which a chat host's model doesn't have (its loop uses none); "" when
     # there is neither.

data/lib/samagotchi/session_manager.rb

@@ -148,7 +148,7 @@ module Samagotchi
       sd = state_dir || Session.default_state_dir
       session = Session.new_session(
         mode: mode,
-        model_name: model_name || Samagotchi::ModelProfile.required_model_name,
+        model_name: Samagotchi::ModelProfile.check_host!(Samagotchi::ModelProfile.required_model_name(model_name)),
         working_directory: working_directory || Dir.pwd,
         preloaded_memory_names: memories,
         muted_memory_names: muted_memories,
@@ -697,21 +697,6 @@ module Samagotchi
       true
     end
 
-    # Wait for a session to reach a terminal state (completed, error, stopped).
-    # Returns true if the session finished, false if the timeout elapsed.
-    def self.wait_for_session(session_id, timeout: 30, state_dir: nil)
-      sd = state_dir || Session.default_state_dir
-      elapsed = 0
-      while elapsed < timeout
-        session = Session.load(session_id, state_dir: sd)
-        return true if %w[completed error stopped].include?(session.status)
-
-        sleep(0.5)
-        elapsed += 0.5
-      end
-      false
-    end
-
     # Run the session loop inside the forked process.
     # This is the entry point called by Process.spawn.
     #

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -31,19 +31,9 @@ module Samagotchi
       include Formatting
       include InputSupport
 
-      STATS_COMMAND = "/stats"
-      RECAP_COMMAND = "/recap"
       PROMPT = "> "
-      # Detach and leave the worker up.
-      DETACH_COMMANDS = %w[/detach].freeze
-      # Detach and ask the worker to exit (bare `exit` too, as in the REPL).
-      EXIT_COMMANDS = %w[/exit /quit].freeze
-      # After an exit command: delete the session once the worker has gone.
-      DELETE_FLAG = "--delete"
       # How long /exit --delete waits for the worker to let go.
       DELETE_WAIT = 10
-      # Leave, and archive the session (hidden from the lists, kept for good).
-      ARCHIVE_COMMAND = "/archive"
       # A second Ctrl-C at an empty idle prompt within this many seconds detaches.
       DETACH_WINDOW = 2.0
       DETACH_HINT = "Ctrl-D to detach, /exit stops the worker"
@@ -269,23 +259,26 @@ module Samagotchi
 
         text = line.strip
         return answer_question(text) if @question
-        # Before the continue offer: neither is an answer to it.
-        return submit(nil) if DETACH_COMMANDS.include?(text.downcase)
-        return exit_worker if exit_command?(text)
-        return exit_and_delete if exit_command?(text.delete_suffix(DELETE_FLAG).rstrip) && text.end_with?(" #{DELETE_FLAG}")
-        return exit_and_archive if text.casecmp?(ARCHIVE_COMMAND)
-        command = text.split(/\s+/, 2).first
+
+        # The terminal's own commands (SessionCommands registers them, the
+        # REPL reads the same words). Before the continue offer: the
+        # leaving ones are no answer to it.
+        local = command_registry.lookup_local(text)&.id
+        return submit(nil) if local == :detach
+        return SessionCommands.delete_on_exit?(text) ? exit_and_delete : exit_worker if local == :exit
+        return exit_and_archive if local == :archive
+
         if @continue_offer
-          return answer_continue(text) unless command_registry.command?(text) || [STATS_COMMAND, RECAP_COMMAND].include?(command)
+          return answer_continue(text) unless local || command_registry.command?(text)
 
           # Not an answer: the read left no echo, so show what ran.
           echo_answer(text)
         end
         return if text.empty?
 
-        if command == STATS_COMMAND
+        if local == :stats
           show_stats
-        elsif command == RECAP_COMMAND
+        elsif local == :recap
           show_recap
         elsif command_registry.command?(text)
           # The history keeps !cmds, as the REPL's does (prompts: #send_prompt).
@@ -314,8 +307,6 @@ module Samagotchi
         detach(exit_failed_line(e.message))
       end
 
-      def exit_command?(text) = EXIT_COMMANDS.include?(text.downcase) || text.casecmp?("exit")
-
       # /exit --delete: the worker exits as for /exit, then the session is
       # deleted. When the worker stays up (another UI, queued input, ...),
       # nothing is deleted.
@@ -498,12 +489,10 @@ module Samagotchi
 
       def send_prompt(text)
         persist_recent_history(text)
-        # #memory shorthand becomes words the model reads, as in the REPL.
-        prompt = normalize_model_input(text)
         images = attach_images(text)
         return if images.nil?
 
-        options = { prompt: prompt, client_id: @client_id }
+        options = { prompt: text, client_id: @client_id }
         options[:no_interrupt] = true if @no_interrupt
         options[:images] = images unless images.empty?
         reply = @client.post_turn(**options)
@@ -595,6 +584,13 @@ module Samagotchi
         # What was typed at the prompt waits for the question to close.
         @set_aside = @reader&.typed_text unless @question
         @question = QuestionPrompt.new(pending)
+        # An edit's diff goes above, into the scrollback, once per question
+        # (a join gets it from the snapshot and may get the event too).
+        unless @previewed_id == @question.id
+          @previewed_id = @question.id
+          preview = @question.preview_lines(paint: method(:paint))
+          @screen.commit(preview.join("\n")) unless preview.empty?
+        end
         # The prompt first, so the choices never show under the typed text.
         sync_prompt(keep_text: false)
         @screen.set_slot(:notes, @question.slot(paint: method(:paint)))
@@ -1063,7 +1059,7 @@ module Samagotchi
         params_suffix = params.empty? ? "" : " #{paint(params, 90)}"
         status = part[:status].to_s
         "#{paint('tool>', 36)} #{part[:tool]}#{params_suffix}: #{paint(status, status_color(status))}" \
-          "#{format_tool_image_suffix(part[:images])}"
+          "#{format_tool_image_suffix(part[:images])}#{format_tool_diff_suffix(part[:diff])}"
       end
     end
   end

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -55,10 +55,13 @@ module Samagotchi
         when :tool_call_started
           @tool_started_at[tool_call_key(event)] = @clock.call
           @view.tool_call_feedback_started(event)
+        when :used_memories_updated
+          @view.used_memories_updated(event) if @view.respond_to?(:used_memories_updated)
         when :tool_call_completed
           @view.clear_generation_retry
           @view.tool_call_feedback_completed(event)
-          render_streamed_tool_activity(event[:activity], duration_ms: tool_duration_ms(event), images: event[:images])
+          render_streamed_tool_activity(event[:activity], duration_ms: tool_duration_ms(event), images: event[:images],
+                                                          diff: event[:diff])
         when :generation_completed, :generation_cancelled, :tool_dispatch_started
           @view.generation_feedback_finished
         when :pending_input_merged
@@ -104,7 +107,8 @@ module Samagotchi
       # @param event [Hash] :hook_notice event or a snapshot part with
       #   hook:, text:, level:
       def self.hook_notice_line(event)
-        label = event[:hook].to_s[/\(bundle (.+)\)\z/, 1] || "hook"
+        # chi's own notices name themselves with a bare word (thinking).
+        label = event[:hook].to_s[/\(bundle (.+)\)\z/, 1] || event[:hook].to_s[/\A[a-z][a-z0-9-]*\z/] || "hook"
         text = event[:text].to_s
         text = "warning: #{text}" if event[:level].to_s == "warn"
         "#{label}> #{text}"
@@ -162,12 +166,13 @@ module Samagotchi
 
 private
 
-      def render_streamed_tool_activity(activity, duration_ms:, images: nil)
+      def render_streamed_tool_activity(activity, duration_ms:, images: nil, diff: nil)
         return if activity.nil?
 
         @streamed_tool_activity[tool_activity_key(activity)] += 1
         line = @view.format_tool_activity_line(activity, duration_ms: duration_ms)
         line += @view.format_tool_image_suffix(images) if images&.any?
+        line += @view.format_tool_diff_suffix(diff) if diff
         @view.print_line(line)
       end
 

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -50,6 +50,15 @@ module Samagotchi
         " #{paint(refs.map { |ref| "→ image #{ref[:width]}×#{ref[:height]}" }.join(", "), 90)}"
       end
 
+      # An edit/write row's change, after the row: " +3 −1" (green, red).
+      # +diff+ is EditPreview's hash, symbol or string keys (SSE, snapshot).
+      def format_tool_diff_suffix(diff)
+        return "" unless diff.is_a?(Hash)
+
+        get = ->(key) { diff[key] || diff[key.to_s] }
+        " #{paint("+#{get.(:added).to_i}", 32)} #{paint("\u2212#{get.(:removed).to_i}", 31)}"
+      end
+
       # A card (Engine#show_card) as a framed block: the title and its
       # source, the body as wrapped plain text (no terminal markdown), and
       # one `→ <command>` line per action, the label after it when it says

data/lib/samagotchi/terminal_ui/input_support.rb

@@ -11,10 +11,10 @@ require_relative "../session_commands"
 module Samagotchi
   class TerminalUI
     # Input the REPL and the attached TUI share: the persistent prompt
-    # history, Tab completion (/commands, @path in the cwd, #memory), the
-    # #memory shorthand rewrite, multiline reads at the main prompt, and a
-    # one-shot prefill of the next read (the default input, a prompt given
-    # back after a failed turn).
+    # history, Tab completion (/commands, @path in the cwd, #memory, which
+    # inserts #name and the model reads it as typed), multiline reads at the
+    # main prompt, and a one-shot prefill of the next read (the default
+    # input, a prompt given back after a failed turn).
     #
     # Included for private use; it keeps state in @next_input_prefill and
     # reads @no_default_input.
@@ -204,21 +204,6 @@ module Samagotchi
         }
       end
 
-      def normalize_model_input(input)
-        input.to_s.gsub(/(^|[^\w\/])#((?:project|system)\/)?([a-zA-Z0-9][a-zA-Z0-9_-]*)/) do
-          prefix = Regexp.last_match(1)
-          scoped = Regexp.last_match(2).to_s
-          name = Regexp.last_match(3)
-          scope = scoped.delete_suffix("/")
-          normalized = if scope.empty?
-                         "memory \"#{name}\""
-                       else
-                         "memory \"#{name}\" in #{scope} scope"
-                       end
-          "#{prefix}#{normalized}"
-        end
-      end
-
       def history_file_path
         explicit = ENV[PROMPT_HISTORY_ENV].to_s.strip
         return explicit unless explicit.empty?

data/lib/samagotchi/terminal_ui/question_prompt.rb

@@ -14,6 +14,8 @@ module Samagotchi
     # an optional "; reason"; a substring would pick the wrong one ("y" is
     # in "Deny").
     class QuestionPrompt
+      DIFF_CODES = { "+" => 32, "-" => 31, "@" => 2, "\\" => 2 }.freeze
+
       # A parsed answer. +error+ set: re-ask. +note+: print, then accept.
       Answer = Struct.new(:selected, :freeform, :error, :note, keyword_init: true) do
         def ok? = error.nil?
@@ -24,6 +26,8 @@ module Samagotchi
       # @param pending [Hash] Engine#pending_question (symbol or string keys)
       def initialize(pending)
         field = ->(key) { pending[key] || pending[key.to_s] }
+        approval = field.(:approval)
+        @preview = approval.is_a?(Hash) ? (approval[:preview] || approval["preview"]) : nil
         @id = field.(:id).to_s
         @question = field.(:question).to_s
         @options = Array(field.(:options)).map { |v| v.to_s.strip }.reject(&:empty?)
@@ -49,6 +53,34 @@ module Samagotchi
                          hint: slot_hint, question_code: approval? ? 33 : 94, paint: paint)
       end
 
+      # The most diff lines #preview_lines prints; the web shows them all.
+      PREVIEW_LINES = 40
+
+      # An edit/write approval's dry-run diff (approval.preview, symbol or
+      # string keys: nested keys are strings after a reload or SSE), as
+      # lines to print above the slot: coloured +/-, dim @@, cut at
+      # PREVIEW_LINES. [] for none.
+      def preview_lines(paint: ->(text, _code) { text })
+        preview = @preview
+        return [] unless preview.is_a?(Hash)
+
+        get = ->(key) { preview[key] || preview[key.to_s] }
+        return [paint.("this edit would fail: #{get.(:error)}", 33)] if get.(:error)
+        return [paint.("diff not shown: #{get.(:skipped)}", 2)] if get.(:skipped)
+
+        lines = get.(:text).to_s.split("\n")
+        return [] if lines.empty?
+
+        # TextDiff's own cut note ("… N more lines") counts toward the rest.
+        cut = lines.last.to_s[/\A… (\d+) more lines\z/, 1]
+        lines.pop if cut
+        hidden = [lines.size - PREVIEW_LINES, 0].max + cut.to_i
+        shown = lines.first(PREVIEW_LINES).map { |line| paint.(line, diff_code(line)) }
+        shown.unshift(paint.("new file", 2)) if get.(:new_file)
+        shown << paint.("… #{hidden} more lines (full diff on the web)", 2) if hidden.positive?
+        shown
+      end
+
       # The one line that stays in the scrollback once the question closes:
       # the question and what became of it.
       # @param outcome [String] the answer (#answer_text) or what closed it
@@ -148,6 +180,9 @@ module Samagotchi
         found = options.find { |o| o.downcase == tok.downcase || o.downcase.include?(tok.downcase) }
         found ? [found, nil] : [nil, "Unknown option '#{tok}'. Use numbers 1-#{options.size} or exact labels."]
       end
+
+      # "+" green, "-" red, "@@" and "\ No newline" dim, context plain.
+      def diff_code(line) = DIFF_CODES.fetch(line[0], 0)
     end
   end
 end