samagotchi 0.2.0

data/lib/samagotchi/terminal_ui/legacy_surface.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "io/console"
+require_relative "surface"
+
+module Samagotchi
+  class TerminalUI
+    # The REPL's Surface before the live region: plain output where the
+    # cursor is. Only the activity slot is live. It redraws in place by
+    # moving back up over the rows it drew last (ESC[nA), which works only
+    # while nothing else writes below it. The editor slot prints a prompt
+    # for a plain read, and clearing it erases the line Reline drew. The other
+    # slots just print their rows, except status rows set together with the
+    # activity rows (#set_slots): those are the activity block's last rows.
+    class LegacySurface
+      include Surface
+
+      # @param out [IO, nil] nil writes to $stdout as it is at each write
+      #   (specs swap it after the UI is built)
+      def initialize(out: nil)
+        @out = out
+        @activity_shown = false
+        @activity_rows = 0
+      end
+
+      def commit(text)
+        out.puts(text)
+      end
+
+      def set_slot(name, rows)
+        check_slot!(name)
+        case name
+        when :activity then redraw_activity(rows)
+        when :editor
+          out.print(rows.join("\n"))
+          out.flush
+        else lay_out(rows, width: columns).each { |row| out.puts(row) }
+        end
+      end
+
+      def set_slots(**rows_by_slot)
+        return super unless rows_by_slot.key?(:activity)
+
+        activity = rows_by_slot.delete(:activity)
+        status = rows_by_slot.delete(:status)
+        set_slot(:activity, Array(activity) + Array(status))
+        super(**rows_by_slot)
+      end
+
+      def clear_slot(name)
+        check_slot!(name)
+        case name
+        when :activity then erase_activity
+        when :editor
+          out.print("\r\e[2K")
+          out.flush
+          true
+        else false
+        end
+      end
+
+      private
+
+      def out = @out || $stdout
+
+      def columns
+        IO.console&.winsize&.last || 80
+      rescue StandardError
+        80
+      end
+
+      # Pad to the taller of the old and new heights, so rows left over from
+      # a taller frame are blanked.
+      def redraw_activity(rows)
+        move_to_activity_origin
+        row_count = [@activity_rows, rows.length].max
+        padded = rows + Array.new(row_count - rows.length, "")
+        out.print(padded.map { |text| "#{text}\e[0K" }.join("\n"))
+        out.flush
+        @activity_shown = true
+        @activity_rows = row_count
+      end
+
+      def move_to_activity_origin
+        return unless @activity_shown
+
+        out.print("\e[#{@activity_rows - 1}A") if @activity_rows > 1
+        out.print("\r")
+      end
+
+      def erase_activity
+        return false unless @activity_shown
+
+        row_count = @activity_rows
+        row_count = 1 if row_count <= 0
+        out.print("\e[#{row_count - 1}A") if row_count > 1
+        out.print("\r")
+        row_count.times do |index|
+          out.print("\e[0K")
+          out.print("\n") if index < row_count - 1
+        end
+        out.print("\e[#{row_count - 1}A") if row_count > 1
+        out.print("\r")
+        out.flush
+        @activity_shown = false
+        @activity_rows = 0
+        true
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/line_reader.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "reline"
+
+module Samagotchi
+  class TerminalUI
+    # Reads input lines on its own thread, so output keeps rendering while
+    # the user types, and hands each line (nil = Ctrl-D) or Ctrl-C to a sink
+    # (anything with #<<, such as a Thread::Queue); the attached loop and the
+    # REPL both read this way. #reprompt makes it drop the open read and start
+    # again with the current prompt (a question opened or closed); #prefill
+    # starts it again with text already typed in (a failed prompt).
+    class LineReader
+      # Raised into the reader thread; only lands inside a read.
+      class Reprompt < StandardError; end
+      # Ends the reader from inside its read, so Reline restores the terminal.
+      class Stop < StandardError; end
+
+      # @param prompt [#call] -> the prompt for the next read
+      # @param read [#call] (prompt, prefill) -> line (nil = Ctrl-D)
+      # @param prefill [String, nil] typed into the first read
+      def initialize(sink, prompt:, read:, prefill: nil)
+        @sink = sink
+        @prompt = prompt
+        @read = read
+        @current = nil
+        @prefill = prefill
+      end
+
+      # @return [String, nil] the prompt of the read in progress
+      attr_reader :current
+
+      def start
+        # Created masked (threads inherit the mask), so a Reprompt raised
+        # before #run is entered waits for the first read too.
+        Thread.handle_interrupt(Reprompt => :never, Stop => :never) { @thread = Thread.new { run } }
+        @thread.report_on_exception = false
+        self
+      end
+
+      def alive? = @thread&.alive? || false
+      
+      # Drop the open read and start it again with the current prompt.
+      # @param keep_text [Boolean] with what is typed there now
+      # @param prefill [String, nil] with this text instead
+      def reprompt(keep_text: false, prefill: nil)
+        text = keep_text ? typed_text : prefill
+        @prefill = text unless text.to_s.empty?
+        @thread&.raise(Reprompt)
+      end
+      
+      # Type +text+ into the next read (from the sink, between two reads).
+      def prefill_next(text)
+        @prefill = text
+      end
+
+      # @return [String, nil] what the open read holds
+      def typed_text
+        return nil unless $stdin.tty?
+      
+        Reline.line_buffer.to_s
+      rescue StandardError
+        nil
+      end
+
+      # Start the read again with +text+ in it, unless something is typed
+      # there already (that would be lost).
+      # @return [Boolean] whether the text went in
+      def prefill(text)
+        return false unless line_empty?
+
+        @prefill = text
+        reprompt
+        true
+      end
+
+      def stop
+        return unless @thread&.alive?
+
+        @thread.raise(Stop)
+        @thread.join(0.5) || (@thread.kill && @thread.join(0.5))
+      end
+
+      private
+
+      def run
+        # A Reprompt may only interrupt the read itself; one that comes
+        # while a line is being handed over waits for the next read (and
+        # just restarts it). The mask is also inherited from #start.
+        Thread.handle_interrupt(Reprompt => :never, Stop => :never) do
+          loop do
+            @current = @prompt.call
+            prefill = @prefill
+            @prefill = nil
+            line = Thread.handle_interrupt(Reprompt => :immediate, Stop => :immediate) { @read.call(@current, prefill) }
+            @sink << [:line, line]
+            break if line.nil?
+          rescue Reprompt
+            next
+          rescue Interrupt
+            # What the line held at the press (AttachedLoop#note_interrupted_line).
+            @sink << [:interrupt, Thread.current[:interrupted_line]]
+            Thread.current[:interrupted_line] = nil
+          end
+        end
+      rescue Stop
+        nil
+      end
+
+      def line_empty? = typed_text.to_s.strip.empty?
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/live_region.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "screen"
+require_relative "reline_seam"
+
+module Samagotchi
+  class TerminalUI
+    # Opens and closes a live region: a Screen with Reline drawing into it
+    # through RelineSeam. The REPL and attached mode both use one when the
+    # terminal can show it, and fall back to their own plain output otherwise.
+    module LiveRegion
+      module_function
+
+      # @return [Screen, nil] a started Screen with Reline attached, or nil
+      #   when the terminal can't show a live region (output or input not a
+      #   terminal, TERM=dumb, or a Reline the seam doesn't support)
+      def open(out: $stdout, input: $stdin, env: ENV)
+        return unless available?(out: out, input: input, env: env)
+
+        screen = Screen.new(out: out).start
+        RelineSeam.attach(screen)
+        screen
+      end
+
+      # Hand Reline its own drawing back, then close the surface.
+      def close(surface)
+        RelineSeam.detach(surface)
+        surface.close
+      end
+
+      def available?(out:, input:, env:)
+        out.tty? && input.tty? && env["TERM"] != "dumb" && RelineSeam.supported?
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/plain_surface.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "monitor"
+require_relative "surface"
+
+module Samagotchi
+  class TerminalUI
+    # Attached mode's Surface when a live region can't be drawn (output or
+    # input not a terminal, TERM=dumb, or a Reline the seam doesn't support):
+    # append-only output. Committed text and the notes, status and hints rows
+    # print as lines. The activity slot is dropped, because redrawing it in
+    # place needs cursor movement (the turn's lines still print as they end).
+    # The prompt is Reline's (or a plain read's) own, so output may cross it.
+    class PlainSurface
+      include Surface
+
+      # @param out [IO]
+      def initialize(out:)
+        @out = out
+        @lock = Monitor.new
+      end
+
+      def synchronize(&) = @lock.synchronize(&)
+
+      # @return [Integer] terminal width in columns
+      def columns = IO.console&.winsize&.last || 80
+
+      def commit(text)
+        synchronize { @out.puts(text) }
+      end
+
+      def set_slot(name, rows)
+        check_slot!(name)
+        raise ArgumentError, "Reline draws the editor slot" if name == :editor
+        return if name == :activity
+
+        synchronize { lay_out(rows, width: columns).each { |row| @out.puts(row) } }
+      end
+
+      # Nothing printed can be taken back.
+      # @return [false]
+      def clear_slot(name)
+        check_slot!(name)
+        false
+      end
+
+      def close; end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/question_prompt.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative "question_slot"
+
+module Samagotchi
+  class TerminalUI
+    # An ask_user_question prompt as the terminal shows it: the widget as
+    # slot content (#slot), the line it leaves (#summary) and the parsing of
+    # a typed answer ("2", "1,3", "1 3; text", option labels). No I/O:
+    # callers draw the slot and print the messages, and
+    # record the answer (the REPL on its Engine, an attached UI over the
+    # Bridge). An approval (kind "approval") takes only a number, an exact
+    # label, y (the first option, Allow once) or n (the last, Deny), plus
+    # an optional "; reason"; a substring would pick the wrong one ("y" is
+    # in "Deny").
+    class QuestionPrompt
+      # 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?
+      end
+
+      attr_reader :id, :question, :options, :header
+
+      # @param pending [Hash] Engine#pending_question (symbol or string keys)
+      def initialize(pending)
+        field = ->(key) { pending[key] || pending[key.to_s] }
+        @id = field.(:id).to_s
+        @question = field.(:question).to_s
+        @options = Array(field.(:options)).map { |v| v.to_s.strip }.reject(&:empty?)
+        header = field.(:header).to_s.strip
+        @header = header.empty? ? nil : header
+        @multi = !!field.(:multi_select)
+        @free = !!field.(:allow_freeform)
+        @approval = field.(:kind).to_s == "approval"
+      end
+
+      def multi? = @multi
+      def free? = @free
+      def approval? = @approval
+
+      # The widget as slot content, fitted to the rows it gets (QuestionSlot).
+      # @return [QuestionSlot]
+      def slot(paint: ->(text, _code) { text })
+        first, *rest = question.lines.map(&:chomp)
+        keys = options.each_index.map { |idx| (idx + 1).to_s }
+        QuestionSlot.new(header: approval? ? (header || "Approve tool call?") : header,
+                         question: first.to_s, mark: mark, details: rest,
+                         options: keys.zip(options).map { |key, label| QuestionSlot::Option.new(key, label) },
+                         hint: slot_hint, question_code: approval? ? 33 : 94, paint: paint)
+      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
+      def summary(outcome, paint: ->(text, _code) { text })
+        "#{paint.("#{mark}#{question.lines.first.to_s.chomp}", approval? ? 33 : 94)} → #{outcome}"
+      end
+
+      # @param answer [Answer] an accepted one
+      # @return [String] "Banana", "Apple, Cherry; ripe ones", "Deny: use a PR"
+      def answer_text(answer)
+        picked = answer.selected.to_a
+        if approval?
+          choice = picked.first || options.last
+          return answer.freeform ? "#{choice}: #{answer.freeform}" : choice
+        end
+
+        [picked.join(", "), answer.freeform].reject { |part| part.to_s.empty? }.join("; ")
+      end
+
+      # @param raw [String] the typed line, not empty
+      # @return [Answer]
+      def parse(raw)
+        return parse_approval(raw) if approval?
+
+        raw = raw.to_s.strip
+        # "1,3; my text": the first ';' separates the selection from freeform text.
+        sel_part, free_part = raw.include?(";") ? raw.split(";", 2).map(&:strip) : [raw, nil]
+        free_part = nil if free_part&.empty?
+        # Models forget to flag freeform: accept it anyway, with a note.
+        note = free_part && !free? ? "(note: freeform not flagged but accepting '#{free_part}')" : nil
+
+        labels = []
+        sel_part.split(/[,\s]+/).reject(&:empty?).each do |tok|
+          label, error = option_for(tok)
+          return Answer.new(error: error, note: note) if error
+
+          labels << label
+        end
+        labels.uniq!
+
+        return Answer.new(error: "No selection. Try again.", note: note) if labels.empty? && free_part.nil?
+        return Answer.new(error: "This is single-select (pick one). Try again.", note: note) if !multi? && labels.size > 1
+
+        Answer.new(selected: labels, freeform: free_part, note: note)
+      end
+
+      private
+
+      def mark = approval? ? "! " : "? "
+
+      def slot_hint
+        if approval?
+          return "1-#{options.size}, y = #{options.first}, n = #{options.last}; add '; reason' to tell the model why; " \
+                 "Enter alone denies"
+        end
+
+        hint = [multi? ? "Select one or more (e.g. 1,3)" : "Select one (e.g. 2)"]
+        hint << "add '; text' for your own answer" if free?
+        hint << "Enter alone cancels"
+        hint.join("; ")
+      end
+
+      def parse_approval(raw)
+        sel_part, free_part = raw.to_s.strip.split(";", 2).map { |part| part.to_s.strip }
+        free_part = nil if free_part.to_s.empty?
+        return Answer.new(selected: [], freeform: free_part) if sel_part.to_s.empty? && free_part
+
+        label = approval_option(sel_part.to_s)
+        unless label
+          return Answer.new(error: "Answer with 1-#{options.size}, y (#{options.first}) or n (#{options.last}).")
+        end
+
+        Answer.new(selected: [label], freeform: free_part)
+      end
+
+      def approval_option(token)
+        down = token.downcase
+        return options.first if %w[y yes].include?(down)
+        return options.last if %w[n no].include?(down)
+
+        if token.match?(/\A\d+\z/)
+          idx = token.to_i - 1
+          return idx.between?(0, options.size - 1) ? options[idx] : nil
+        end
+        options.find { |o| o.downcase == down }
+      end
+
+      # A number, or an option label (exact or substring, any case).
+      def option_for(tok)
+        if tok.match?(/\A\d+\z/)
+          idx = tok.to_i - 1
+          return [nil, "Invalid choice '#{tok}': pick 1-#{options.size}"] if idx.negative? || idx >= options.size
+
+          return [options[idx], nil]
+        end
+
+        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
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/question_slot.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "reline"
+
+module Samagotchi
+  class TerminalUI
+    # A question's rows as slot content (Surface): laid out afresh for the
+    # rows it gets. With room it shows everything, top down: a header, the
+    # question (wrapped), detail lines, one row per option and a hint row.
+    # When short, rows give way in this order: the hint, the details (and
+    # the question's wrapped rows), the header; then the options fold into
+    # as few packed rows as the width allows. The question's first row and
+    # the options stay to the last.
+    class QuestionSlot
+      # A numbered option shows as "1) Apple", a word as "yes: continue".
+      Option = Struct.new(:key, :label) do
+        def text = key.match?(/\A\d+\z/) ? "#{key}) #{label}" : "#{key}: #{label}"
+      end
+
+      CONTINUE_QUESTION = "The turn ran out of iterations. Continue it?"
+
+      # A continue offer (TurnFlow): what the answers at the ? prompt do.
+      # @param context [Hash, nil] the offer's context (last_model_intent)
+      def self.continue_offer(context = nil, paint: ->(text, _code) { text })
+        intent = (context || {})[:last_model_intent] || (context || {})["last_model_intent"]
+        details = intent.to_s.strip.empty? ? [] : ["  last step: #{intent.to_s.strip.tr("\n", " ")}"]
+        new(question: CONTINUE_QUESTION, mark: "? ", details: details, question_code: 33, paint: paint,
+            options: [Option.new("yes", "continue (Enter alone too)"), Option.new("no", "stop here"),
+                      Option.new("no, <reason>", "stop and tell the model why")])
+      end
+
+      # The line a continue offer leaves in the scrollback.
+      def self.continue_summary(outcome, paint: ->(text, _code) { text })
+        "#{paint.("? #{CONTINUE_QUESTION}", 33)} → #{outcome}"
+      end
+
+      # @param question [String] the first row's text, wrapped when there is room
+      # @param mark [String] its prefix ("? ", "! ")
+      # @param options [Array<Option>] key ("1", "yes") and label
+      # @param paint [#call] (text, code) -> coloured text
+      def initialize(question:, mark:, options:, header: nil, details: [], hint: nil, question_code: 94,
+                     paint: ->(text, _code) { text })
+        @header = header
+        @question = question.to_s
+        @mark = mark
+        @details = details
+        @options = options
+        @hint = hint
+        @question_code = question_code
+        @paint = paint
+      end
+
+      # @param width [Integer]
+      # @param height [Integer, nil] nil: no limit
+      # @return [Array<String>]
+      def fit(width:, height:)
+        width = [width.to_i, 10].max
+        full = layout(width, hint: true, details: true, header: true, folded: false)
+        return full if height.nil? || full.size <= height
+
+        [
+          { hint: false, details: true, header: true, folded: false },
+          { hint: false, details: false, header: true, folded: false },
+          { hint: false, details: false, header: false, folded: false },
+          { hint: false, details: false, header: false, folded: true }
+        ].each do |level|
+          rows = layout(width, **level)
+          return rows if rows.size <= height
+        end
+        layout(width, hint: false, details: false, header: false, folded: true).first([height, 0].max)
+      end
+
+      private
+
+      def layout(width, hint:, details:, header:, folded:)
+        rows = []
+        rows << @paint.(@header, 1) if header && @header
+        question_rows = wrap(@question, width, first: @mark, indent: " " * @mark.size)
+        question_rows = question_rows.first(1) unless details
+        rows.concat(question_rows.map { |row| @paint.(row, @question_code) })
+        rows.concat(@details.map { |row| @paint.(row, @question_code) }) if details
+        rows.concat(folded ? folded_options(width) : @options.map { |o| @paint.("  #{o.text}", 92) })
+        rows << @paint.("  [#{@hint}]", 90) if hint && @hint
+        rows
+      end
+
+      # The options packed into rows of +width+: "  1) Allow once · 2) Deny".
+      def folded_options(width)
+        rows = []
+        line = +""
+        @options.each do |option|
+          item = option.text
+          candidate = line.empty? ? "  #{item}" : "#{line} · #{item}"
+          if !line.empty? && display_width(candidate) > width
+            rows << line
+            line = +"  #{item}"
+          else
+            line = +candidate
+          end
+        end
+        rows << line unless line.empty?
+        rows.map { |row| @paint.(row, 92) }
+      end
+
+      # Word wrap at +width+ columns, the first row after +first+, the others
+      # after +indent+; a word longer than a row is cut.
+      def wrap(text, width, first:, indent:)
+        rows = []
+        line = first.dup
+        words = false
+        text.split(/(?<= )/).each do |word|
+          if words && display_width(line + word.rstrip) > width
+            rows << line.rstrip
+            line = indent.dup
+          end
+          line << word
+          words = true
+          while display_width(line.rstrip) > width
+            head, = Reline::Unicode.take_mbchar_range(line, 0, width, padding: false)
+            rows << head
+            line = +"#{indent}#{line[head.size..]}"
+          end
+        end
+        rows << line.rstrip unless line.strip.empty? && !rows.empty?
+        rows
+      end
+
+      def display_width(text) = Reline::Unicode.calculate_width(text, true)
+    end
+  end
+end