samagotchi 0.2.0

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require_relative "../served_model"
+require_relative "../image_store"
+
+module Samagotchi
+  class TerminalUI
+    # Line formatting shared by the REPL and the attached view: colour, the
+    # `tool>` line, elapsed durations. Pure apart from reading whether
+    # $stdout is a colour terminal.
+    module Formatting
+      def format_tool_activity_line(activity, duration_ms: nil)
+        params = activity[:params].to_s.strip
+        params_suffix = params.empty? ? "" : " #{paint(params, 90)}"
+        status = activity[:status].to_s
+        status_color = status == "ok" ? 32 : 31
+        elapsed_suffix = duration_ms.nil? ? "" : " (#{format_elapsed_duration(duration_ms)})"
+        "#{paint('tool>', 36)} #{activity[:action]} (#{activity[:tool]}#{params_suffix}): #{paint(status, status_color)}#{elapsed_suffix}"
+      end
+
+      # "[image shot.png 1280×800 · ~1.3k tokens]", dim: a turn's image.
+      def format_image_line(ref)
+        paint("[image #{ImageRef.label(ImageStore.symbolize(ref))}]", 90)
+      end
+
+      # " → image 1280×800" after a tool line whose tool read an image.
+      def format_tool_image_suffix(images)
+        refs = Array(images).map { |ref| ImageStore.symbolize(ref) }
+        return "" if refs.empty?
+
+        " #{paint(refs.map { |ref| "→ image #{ref[:width]}×#{ref[:height]}" }.join(", "), 90)}"
+      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
+      # more. +updated+: a card shown again under its id.
+      # @param card [Hash] title:, source:, body:, level:, actions:
+      # @param width [Integer, nil] columns (#card_width by default)
+      def card_block(card, updated: false, width: nil)
+        width = [(width || card_width).to_i, 24].max
+        rail = paint("│", 90)
+        title = card[:title].to_s
+        title += " (updated)" if updated
+        source = card[:source].to_s
+        head = paint("┌ #{title}", card[:level].to_s == "warn" ? 33 : 1)
+        head += paint(" · #{source}", 90) unless source.empty?
+        lines = [head]
+        wrap_plain(strip_markdown(card[:body].to_s), width - 2).each { |line| lines << (line.empty? ? rail : "#{rail} #{line}") }
+        Array(card[:actions]).each do |action|
+          command = action[:command].to_s
+          label = action[:label].to_s
+          line = "#{rail} #{paint("→ #{command}", 36)}"
+          line += paint("  #{label}", 90) unless label.empty? || label == command
+          lines << line
+        end
+        lines << paint("└", 90)
+        lines.join("\n")
+      end
+
+      # A card body's markdown made plain, cheaply (there is no terminal
+      # markdown): **x** and __x__ are x, backticks and code fences go, and
+      # so do headings' #s. Lists stay as they are.
+      def strip_markdown(text)
+        text.gsub(/^[ \t]*```.*(?:\n|\z)/, "")
+            .gsub(/^[ \t]{0,3}\#{1,6}[ \t]+/, "")
+            .gsub(/\*\*(.+?)\*\*/, '\1')
+            .gsub(/__(.+?)__/, '\1')
+            .delete("`")
+      end
+
+      # The columns a card is wrapped to: the terminal's (a view with a
+      # surface asks it).
+      def card_width
+        surface = instance_variable_defined?(:@screen) ? @screen : instance_variable_get(:@surface)
+        surface.respond_to?(:columns) ? surface.columns : (IO.console&.winsize&.last || 80)
+      end
+
+      # +text+ wrapped at word boundaries to +width+ columns, its own line
+      # breaks kept (a blank line stays blank), a word longer than a line
+      # split. Trailing blank lines dropped.
+      def wrap_plain(text, width)
+        width = [width, 8].max
+        lines = text.gsub("\r\n", "\n").rstrip.split("\n", -1).flat_map do |raw|
+          raw = raw.rstrip
+          next [""] if raw.empty?
+
+          indent = raw[/\A */]
+          out = []
+          line = +""
+          raw.split(/ +/).reject(&:empty?).each do |word|
+            while word.length > width - indent.length
+              out << "#{indent}#{line}".rstrip unless line.empty?
+              line = +""
+              out << "#{indent}#{word[0, width - indent.length]}"
+              word = word[(width - indent.length)..]
+            end
+            if !line.empty? && indent.length + line.length + 1 + word.length > width
+              out << "#{indent}#{line}"
+              line = +""
+            end
+            line << (line.empty? ? word : " #{word}")
+          end
+          out << "#{indent}#{line}" unless line.empty?
+          out
+        end
+        text.strip.empty? ? [] : lines
+      end
+
+      private
+
+      # The recap shown on return: dim, one "recap>" block, noting how many
+      # turns came since it was written.
+      def recap_block(text, turns_since: 0)
+        n = turns_since.to_i
+        note = if n == 1 then " (before the last turn)"
+               elsif n > 1 then " (before the last #{n} turns)"
+               else ""
+               end
+        text.to_s.strip.lines.map(&:chomp).each_with_index.map do |line, i|
+          paint(i.zero? ? "recap#{note}> #{line}" : line, 90)
+        end.join("\n")
+      end
+
+      RECAP_OFF_TEXT = "recap is off (recap: false in config.yml, or SAMAGOTCHI_RECAP_ENABLED=false)"
+
+      # What /recap says (the REPL's words, attached mode's too): the saved
+      # recap, then what came of asking for a new one.
+      # @param saved [Hash, nil] {text:, turns_since:}
+      # @param request [Symbol, String, nil] IdleRecap#request_now's answer
+      def recap_command_text(enabled:, saved: nil, request: nil, min_user_turns: nil)
+        return RECAP_OFF_TEXT unless enabled
+
+        saved = saved&.transform_keys(&:to_sym)
+        lines = []
+        lines << recap_block(saved[:text], turns_since: saved[:turns_since]) if saved
+        lines << case request&.to_sym
+                 when :started, :in_flight then "writing a recap…"
+                 when :nothing_new then saved ? "(nothing new since this recap)" : "no recap yet: nothing to recap"
+                 when :too_short then "no recap yet: it needs at least #{min_user_turns} user turns"
+                 when :busy then saved ? nil : "no recap yet: a turn is running; one is written once the session is idle"
+                 when :failed then "(could not ask for a recap)"
+                 end
+        lines.compact.join("\n")
+      end
+
+      # ── The status line (the REPL's, and attached mode's idle one) ────────
+
+      # SAMAGOTCHI_STATUS_LINE=off hides it.
+      def status_line_enabled?
+        value = ENV.fetch(STATUS_LINE_ENV, STATUS_LINE_ON).to_s.strip.downcase
+        !(value.empty? || value == STATUS_LINE_OFF || value == "0" || value == "false")
+      end
+
+      # @return [Array<String>] the "status> a | b" row, cut to +width+
+      def status_rows(segments, width)
+        return [] if segments.empty? || width <= 0
+
+        row = cap_preview_text("status> #{segments.join(' | ')}", width)
+        [color_output? ? paint(row, 90) : row]
+      end
+
+      # Longest asked-for name the status line keeps next to a served one.
+      STATUS_ASKED_MAX = 24
+
+      # +served+ / +served_for+: the model the server said it served for the
+      # name asked (see Engine#served_model); shown first when it's another
+      # model.
+      def status_model_text(model, default_model, served: nil, served_for: nil)
+        if ServedModel.differs?(served_for, served)
+          asked = model.to_s.length > STATUS_ASKED_MAX ? "#{model.to_s[0, STATUS_ASKED_MAX - 1]}…" : model
+          return "model=#{served} (served; asked #{asked})"
+        end
+        return "model=#{model}" if default_model.nil? || model == default_model
+
+        "model=#{model} (default: #{default_model})"
+      end
+
+      # @param server [Hash, nil] the server's own numbers ({ctx_pct:, prompt_tokens:, ...})
+      # @param estimate [Hash, nil] the kernel's estimate ({est_pct:, bucket:})
+      def status_context_text(server: nil, estimate: nil)
+        return format_server_context_segment(server) if server.is_a?(Hash)
+        return "" unless estimate.is_a?(Hash)
+
+        pct = format("%.1f", estimate[:est_pct].to_f)
+        bucket = estimate[:bucket].to_s
+        return "ctx=#{pct}%" if bucket.empty?
+
+        "ctx=#{pct}% (#{bucket})"
+      end
+
+      def format_server_context_segment(status)
+        pct = status[:ctx_pct]
+        base = pct ? "ctx=#{format('%.1f', pct)}%" : "ctx=srv"
+
+        tokens = []
+        prompt_tokens = status[:prompt_tokens]
+        completion_tokens = status[:completion_tokens]
+        total_tokens = status[:total_tokens]
+        tokens << "p=#{prompt_tokens}" if prompt_tokens
+        tokens << "c=#{completion_tokens}" if completion_tokens
+        tokens << "t=#{total_tokens}" if total_tokens
+
+        return base if tokens.empty?
+
+        "#{base} (#{tokens.join(' ')})"
+      end
+
+      # @param label [String] "mem" for the used memories, "muted" for the
+      #   session's --mute list
+      def status_memory_text(names, limit, label: "mem")
+        names = Array(names)
+        return "" if names.empty?
+
+        visible = names.first(limit)
+        suffix = names.length > visible.length ? ", +#{names.length - visible.length}" : ""
+        "#{label}: #{visible.join(', ')}#{suffix}"
+      end
+
+      def cap_preview_text(text, width)
+        return "" if width <= 0
+
+        value = text.to_s
+        value.length > width ? value[0, width] : value
+      end
+
+      # Render the analytics snapshot as a compact, user-facing report. Raw event
+      # logs (debug-only) are intentionally excluded; this surface is for the REPL.
+      def format_session_metrics(snapshot)
+        return "(no metrics yet)" unless snapshot.is_a?(Hash)
+
+        # A symbol locally; a string when the snapshot came over the Bridge.
+        token_src = snapshot[:token_source]&.to_s
+        token_src_label = case token_src
+                          when "server" then "server-reported"
+                          when "estimate" then "estimated (chars/4)"
+                          else "n/a"
+                          end
+
+        lines = []
+        lines << "turns:            #{snapshot[:turns]}"
+        lines << "tool calls:       #{snapshot[:tool_calls_total]} (#{snapshot[:tool_errors]} errors)"
+        unless snapshot[:tool_calls_by_tool].to_a.empty?
+          by_tool = snapshot[:tool_calls_by_tool].sort_by { |_k, v| -v }
+          lines << "  by tool:        #{by_tool.map { |k, v| "#{k}=#{v}" }.join(", ")}"
+        end
+        lines << "iterations:       #{snapshot[:iterations_total]}"
+        lines << "tokens in/out:    #{snapshot[:tokens_in]}/#{snapshot[:tokens_out]} (total #{snapshot[:tokens_total]}, #{token_src_label})"
+        lines << "gen latency (ms): #{snapshot[:gen_latency_ms]}"
+        lines << "cancellations:    #{snapshot[:cancellations]}"
+        lines << "retries:          #{snapshot[:retries]}"
+        if snapshot[:context_window_tokens]
+          lines << "context window:   #{snapshot[:context_window_tokens]} tokens (#{snapshot[:context_window_source]})"
+        end
+        lines << "prompt profile:   #{snapshot[:profile]} (#{snapshot[:profile_source]})" if snapshot[:profile]
+        if snapshot[:served_model]
+          asked = snapshot[:served_model_for]
+          note = ServedModel.differs?(asked, snapshot[:served_model]) ? " (asked for #{asked})" : ""
+          lines << "served model:     #{snapshot[:served_model]}#{note}"
+        end
+        lines.join("\n")
+      end
+
+      def format_elapsed_duration(duration_ms)
+        duration_ms = duration_ms.to_f
+        return "" if duration_ms.negative?
+        return "#{duration_ms.round}ms" if duration_ms < 500
+
+        seconds = duration_ms / 1000
+        return "#{seconds.round(1)}s" if seconds < 10
+        return "#{seconds.round}s" if seconds < 60
+
+        total_seconds = seconds.round
+        "#{total_seconds / 60}m #{format('%02d', total_seconds % 60)}s"
+      end
+
+      def paint(text, code)
+        return text unless color_output?
+
+        "\e[#{code}m#{text}\e[0m"
+      end
+
+      def color_output?
+        return false unless $stdout.tty?
+        return false if ENV.key?("NO_COLOR")
+
+        ENV.fetch("TERM", "") != "dumb"
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/image_input.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../image_store"
+
+module Samagotchi
+  class TerminalUI
+    # `@path` in a typed prompt: each token that names an existing image
+    # file (by its bytes) becomes one of the turn's images. The prompt text
+    # stays as typed; a token that isn't an image (a source file, a missing
+    # path, an email address) is just text.
+    #
+    #   @shot.png  @~/Desktop/a.jpg  @"my shot.png"  @'my shot.png'
+    module ImageInput
+      # An @ at the start or after whitespace, then a quoted or bare path.
+      TOKEN_RE = /(?:\A|(?<=\s))@(?:"([^"]+)"|'([^']+)'|(\S+))/
+
+      # @return [Array<Hash>] {path:} per image, in order, each path once
+      def self.extract(text, cwd: Dir.pwd)
+        text.to_s.scan(TOKEN_RE).filter_map do |quoted_double, quoted_single, bare|
+          raw = quoted_double || quoted_single || bare.sub(/[,.;:!?)\]]+\z/, "")
+          path = expand(raw, cwd)
+          path if path && ImageStore.image_file?(path)
+        end.uniq.map { |path| { path: path } }
+      end
+
+      def self.expand(raw, cwd)
+        return nil if raw.empty?
+
+        File.expand_path(raw, cwd)
+      rescue ArgumentError # ~unknown_user
+        nil
+      end
+      private_class_method :expand
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/input_support.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "reline"
+
+require_relative "../memory_paths"
+require_relative "../tools/memory"
+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).
+    #
+    # Included for private use; it keeps state in @next_input_prefill and
+    # reads @no_default_input.
+    module InputSupport
+      PROMPT_HISTORY_ENV = "SAMAGOTCHI_HISTORY_FILE"
+      XDG_STATE_HOME_ENV = "XDG_STATE_HOME"
+      PROMPT_HISTORY_FILE = "history.json"
+      PROMPT_HISTORY_STATE_DIR = "samagotchi"
+      PROMPT_HISTORY_LIMIT = 20
+      DEFAULT_INPUT_ENV = "SAMAGOTCHI_DEFAULT_INPUT"
+      AT_PATH_COMPLETION_PREFIX = "@"
+      MEMORY_COMPLETION_PREFIX = "#"
+      AT_PATH_COMPLETION_MAX_CANDIDATES = 200
+
+      private
+
+      # The /commands Tab offers: the session's registry, the REPL's own
+      # among them.
+      def slash_commands = command_registry.completions(:repl)
+
+      def command_registry = @commands&.registry || SessionCommands.builtin_registry
+
+      # Whether a new session's first read gets the default input
+      # (SAMAGOTCHI_DEFAULT_INPUT); --no-default-input says no.
+      def default_input_wanted? = !@no_default_input
+
+      # One read at the main prompt. In multiline mode Enter submits, while
+      # Meta+Enter/Alt+Enter inserts a newline on terminals that emit that
+      # distinct sequence (for example kitty); Tab completes; a queued prefill
+      # is typed in first.
+      # @return [String, nil] the line, nil on Ctrl-D
+      def read_prompt_line(prompt)
+        input = with_scoped_at_path_completion do
+          with_next_input_prefill do
+            Reline.readmultiline(prompt, true) { true }
+          end
+        end
+        return nil if input.nil?
+
+        input.gsub(/\r\n?|\n\z/, "\n").strip
+      end
+
+      def with_scoped_at_path_completion
+        previous_completion_proc = Reline.completion_proc
+        previous_autocompletion = Reline.autocompletion
+        Reline.autocompletion = true
+        Reline.completion_proc = method(:assist_path_completion_candidates).to_proc
+        yield
+      ensure
+        Reline.completion_proc = previous_completion_proc
+        Reline.autocompletion = previous_autocompletion
+      end
+
+      def assist_path_completion_candidates(word)
+        token = word.to_s
+        return [] if token.empty?
+
+        if token.start_with?("/")
+          return build_slash_completion_candidates(token)
+        end
+
+        if token.start_with?(AT_PATH_COMPLETION_PREFIX)
+          path_fragment = token.delete_prefix(AT_PATH_COMPLETION_PREFIX)
+          return build_project_path_completion_candidates(path_fragment)
+        end
+
+        if token.start_with?(MEMORY_COMPLETION_PREFIX)
+          memory_fragment = token.delete_prefix(MEMORY_COMPLETION_PREFIX)
+          return build_memory_completion_candidates(memory_fragment)
+        end
+
+        []
+      end
+
+      def build_slash_completion_candidates(slash_fragment)
+        fragment = slash_fragment.to_s.strip
+        return [] unless fragment.start_with?("/")
+
+        begin
+          buf = Reline.line_buffer.to_s
+          unless buf.empty?
+            return [] unless buf.lstrip.start_with?("/")
+          end
+        rescue StandardError
+          nil
+        end
+
+        lowered = fragment.downcase
+        return slash_commands.dup if lowered == "/"
+
+        slash_commands.select { |cmd| cmd.start_with?(lowered) }
+      rescue StandardError
+        []
+      end
+
+      def build_project_path_completion_candidates(path_fragment)
+        fragment = path_fragment.to_s.tr("\\", "/")
+        return [] if fragment.start_with?("/")
+        return [] if fragment.split("/").include?("..")
+
+        dir_part = ""
+        entry_prefix = fragment
+
+        if fragment.include?("/")
+          dir_part = fragment.sub(%r{[^/]*\z}, "")
+          entry_prefix = fragment.split("/").last.to_s
+        end
+
+        base_dir = dir_part.empty? ? Dir.pwd : File.expand_path(dir_part, Dir.pwd)
+        return [] unless path_within_cwd?(base_dir)
+        return [] unless File.directory?(base_dir)
+
+        entries = Dir.children(base_dir).sort
+        entries.reject! { |entry| entry.start_with?(".") } unless entry_prefix.start_with?(".")
+        matches = entries.select { |entry| entry.start_with?(entry_prefix) }
+
+        matches.first(AT_PATH_COMPLETION_MAX_CANDIDATES).map do |entry|
+          relative_path = "#{dir_part}#{entry}".tr("\\", "/")
+          absolute_path = File.join(base_dir, entry)
+          relative_path = "#{relative_path}/" if File.directory?(absolute_path)
+          "#{AT_PATH_COMPLETION_PREFIX}#{relative_path}"
+        end
+      rescue StandardError
+        []
+      end
+
+      def path_within_cwd?(path)
+        expanded = File.expand_path(path)
+        cwd = Dir.pwd
+        expanded == cwd || expanded.start_with?("#{cwd}#{File::SEPARATOR}")
+      end
+
+      def build_memory_completion_candidates(memory_fragment)
+        fragment = memory_fragment.to_s.strip.tr("\\", "/")
+        candidates = memory_completion_entries
+        return candidates.map { |entry| entry[:token] } if fragment.empty?
+
+        candidates.filter_map do |entry|
+          entry[:token] if entry[:token].delete_prefix(MEMORY_COMPLETION_PREFIX).start_with?(fragment)
+        end
+      end
+
+      def memory_completion_entries
+        grouped = Hash.new { |hash, key| hash[key] = [] }
+
+        each_memory_completion_entry do |scope, name|
+          grouped[name] << scope unless grouped[name].include?(scope)
+        end
+
+        grouped.sort_by do |name, scopes|
+          [memory_scope_sort_key(scopes.min_by { |scope| memory_scope_sort_key(scope) }), name]
+        end.flat_map do |name, scopes|
+          scopes = scopes.sort_by { |scope| [memory_scope_sort_key(scope), scope] }
+          if scopes.length == 1
+            [{ token: "#{MEMORY_COMPLETION_PREFIX}#{name}", scope: scopes.first, name: name }]
+          else
+            scopes.map do |scope|
+              { token: "#{MEMORY_COMPLETION_PREFIX}#{scope}/#{name}", scope: scope, name: name }
+            end
+          end
+        end
+      end
+
+      def memory_scope_sort_key(scope)
+        scope == "project" ? 0 : 1
+      end
+
+      def each_memory_completion_entry
+        memory_completion_dirs.each do |scope, dir|
+          next unless File.directory?(dir)
+
+          Dir.glob(File.join(dir, "*.md")).sort.each do |path|
+            name = File.basename(path, ".md")
+            next if name.empty? || name == Tools::MEMORY_INDEX
+
+            yield scope, name
+          end
+        end
+      rescue StandardError
+        []
+      end
+
+      def memory_completion_dirs
+        {
+          "project" => File.expand_path(MemoryPaths.project_dir, Dir.pwd),
+          "system" => File.expand_path(MemoryPaths.system_dir)
+        }
+      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?
+
+        File.join(xdg_state_home, PROMPT_HISTORY_STATE_DIR, PROMPT_HISTORY_FILE)
+      end
+
+      def xdg_state_home
+        configured = ENV[XDG_STATE_HOME_ENV].to_s.strip
+        return configured unless configured.empty?
+
+        File.join(Dir.home, ".local", "state")
+      end
+
+      def load_persistent_history
+        entries = load_history_entries_from_disk
+        entries.last(PROMPT_HISTORY_LIMIT).each { |entry| Reline::HISTORY << entry }
+      rescue StandardError
+        nil
+      end
+
+      def persist_recent_history(input)
+        entries = normalize_history_entries(load_history_entries_from_disk)
+        entries << input
+        trimmed_entries = entries.last(PROMPT_HISTORY_LIMIT)
+        path = history_file_path
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(trimmed_entries) + "\n")
+      rescue StandardError
+        nil
+      end
+
+      def load_history_entries_from_disk
+        path = history_file_path
+        return [] unless File.file?(path)
+
+        raw = File.read(path)
+        parsed = JSON.parse(raw)
+        normalize_history_entries(parsed)
+      rescue JSON::ParserError
+        normalize_history_entries(raw.to_s.lines.map(&:chomp))
+      rescue StandardError
+        []
+      end
+
+      def normalize_history_entries(entries)
+        Array(entries).map { |entry| entry.to_s.gsub(/\r\n?/, "\n").strip }.reject(&:empty?)
+      end
+
+      # The text as given ("Please " keeps its space); a blank one is none.
+      def queue_input_prefill(text)
+        return if text.to_s.strip.empty?
+
+        @next_input_prefill = text.to_s
+      end
+
+      def queue_default_input
+        default = default_input_text
+        queue_input_prefill(default) if default
+      end
+
+      # @return [String, nil] the default input for a new session's first
+      #   read, if it gets one
+      def default_input_text
+        return nil unless default_input_wanted?
+
+        default = ENV.fetch(DEFAULT_INPUT_ENV, nil)
+        return nil if default.nil? || default.strip.empty?
+
+        default
+      end
+
+      def consume_input_prefill
+        value = @next_input_prefill
+        @next_input_prefill = nil
+        value
+      end
+
+      def with_next_input_prefill
+        prefill = consume_input_prefill
+        return yield if prefill.nil? || prefill.empty?
+
+        previous_hook = Reline.pre_input_hook
+        inserted = false
+        Reline.pre_input_hook = proc do
+          unless inserted
+            Reline.insert_text(prefill)
+            inserted = true
+          end
+          previous_hook.call if previous_hook
+        end
+        begin
+          yield
+        ensure
+          # Restore only what we replaced: a method-level ensure also ran on the
+          # no-prefill early return and reset the hook to nil, dropping the
+          # Engine activity hook (with_activity_hook) after the first prompt.
+          Reline.pre_input_hook = previous_hook
+        end
+      end
+    end
+  end
+end