kward 0.67.1 → 0.69.0

data/lib/kward/prompt_interface/question_prompt.rb

@@ -0,0 +1,328 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Structured question overlay used by ask_user_question.
+  class PromptInterface
+    # Structured question overlay used by the ask-user-question tool.
+    module QuestionPrompt
+      private
+
+      def ask_single_user_question(question, index, total)
+        @mutex.synchronize do
+          @prompt_label = "Answer>"
+          self.composer_input = ""
+          self.composer_cursor = 0
+          @pending_keys.clear
+          @asking = true
+          @busy = false
+          @queued_count = 0
+          @question_state = {
+            question: question[:question] || question["question"],
+            header: question[:header] || question["header"],
+            options: question[:options] || question["options"],
+            selection_index: 0,
+            index: index,
+            total: total
+          }
+          reset_history_navigation
+          render_prompt_locked
+        end
+
+        loop do
+          key = read_key(nonblock: true)
+          result = nil
+          @mutex.synchronize do
+            if key.nil?
+              resized = handle_resize_locked
+              footer_refreshed = tick_footer_locked
+              render_prompt_locked if resized || footer_refreshed
+            else
+              result = handle_question_key(key)
+              render_prompt_locked unless result.is_a?(Hash) || result == SELECT_CANCEL
+            end
+          end
+
+          return result if result.is_a?(Hash) || result == SELECT_CANCEL
+
+          sleep 0.02 if key.nil?
+        end
+      end
+
+      def begin_question_prompt_state
+        {
+          prompt_label: @prompt_label,
+          input: composer_input,
+          cursor: composer_cursor,
+          asking: @asking,
+          busy: @busy,
+          queued_count: @queued_count,
+          steered_count: @steered_count,
+          pending_keys: @pending_keys.dup,
+          select_state: @select_state
+        }
+      end
+
+      def finish_question_prompt(saved_state)
+        @mutex.synchronize do
+          @question_state = nil
+          @select_state = saved_state[:select_state]
+          @prompt_label = saved_state[:prompt_label]
+          self.composer_input = saved_state[:input]
+          self.composer_cursor = saved_state[:cursor]
+          @asking = saved_state[:asking]
+          @busy = saved_state[:busy]
+          @queued_count = saved_state[:queued_count]
+          @steered_count = saved_state[:steered_count]
+          @pending_keys = saved_state[:pending_keys]
+          render_prompt_locked if @started && @asking
+          @output_io.flush
+        end
+      end
+
+      def handle_question_key(key)
+        return if handle_question_bracketed_paste_key(key)
+
+        csi_result = handle_question_csi_u_key(key)
+        return csi_result unless csi_result == false
+
+        if key.is_a?(String) && key.length > 1
+          token = next_key_token(key)
+          if token.length < key.length
+            queue_pending_keys(key[token.length..])
+            return handle_question_key(token)
+          end
+        end
+
+        key_name = @reader.console.keys[key]
+        case key_name
+        when :return, :enter
+          current_question_answer
+        when :backspace
+          question_delete_before_cursor
+        when :delete
+          question_delete_at_cursor
+        when :left
+          self.composer_cursor -= 1 if composer_cursor.positive?
+        when :right
+          self.composer_cursor += 1 if composer_cursor < composer_input.length
+        when :home
+          self.composer_cursor = 0
+        when :end
+          self.composer_cursor = composer_input.length
+        when :up
+          question_previous_choice
+        when :down
+          question_next_choice
+        else
+          case key
+          when "\n", "\r"
+            current_question_answer
+          when "\b", "\x7F"
+            question_delete_before_cursor
+          when "\e"
+            handle_question_escape_sequence
+          else
+            question_insert_key(key)
+          end
+        end
+      end
+
+      def handle_question_csi_u_key(key)
+        match = key.to_s.match(/\A\e\[(\d+)(?:;([\d:]+))?u/)
+        return false unless match
+
+        sequence = match[0]
+        code = match[1].to_i
+        queue_pending_keys(key[sequence.length..]) if key.length > sequence.length
+
+        case code
+        when 13
+          current_question_answer
+        when 27
+          SELECT_CANCEL
+        when 8, 127
+          question_delete_before_cursor
+          nil
+        else
+          false
+        end
+      end
+
+      def handle_question_escape_sequence
+        sequence = read_pending_escape_sequence
+        return SELECT_CANCEL if sequence.empty?
+
+        key_name = @reader.console.keys["\e#{sequence}"]
+        case key_name
+        when :up
+          question_previous_choice
+        when :down
+          question_next_choice
+        when :left
+          self.composer_cursor -= 1 if composer_cursor.positive?
+        when :right
+          self.composer_cursor += 1 if composer_cursor < composer_input.length
+        end
+        true
+      end
+
+      def handle_question_bracketed_paste_key(key)
+        text = key.to_s
+        return false unless text.start_with?(BRACKETED_PASTE_START)
+
+        pasted = text[BRACKETED_PASTE_START.length..] || ""
+        until pasted.include?(BRACKETED_PASTE_END)
+          chunk = @reader.read_keypress(echo: false, raw: true)
+          break if chunk.nil?
+
+          pasted << chunk.to_s
+        end
+
+        content, remaining = pasted.split(BRACKETED_PASTE_END, 2)
+        question_insert_string(normalize_paste(content || ""))
+        queue_pending_keys(remaining) if remaining && !remaining.empty?
+        true
+      end
+
+      def current_question_answer
+        choice = selected_question_choice
+        return nil unless choice
+
+        if choice[:custom]
+          answer = composer_input.strip
+          return nil if answer.empty?
+
+          { question: current_question_text, answer: answer, custom: true }
+        else
+          { question: current_question_text, answer: choice[:label], custom: false }
+        end
+      end
+
+      def selected_question_choice
+        choices = question_choices
+        return nil if choices.empty?
+
+        choices[question_selection_index]
+      end
+
+      def question_choices
+        options = Array(@question_state ? @question_state[:options] : []).map do |option|
+          { label: (option[:label] || option["label"]).to_s, description: (option[:description] || option["description"]).to_s }
+        end
+        choices = options + [{ label: "Type something.", description: composer_input.strip, custom: true }]
+        clamp_question_selection_index(choices.length)
+        choices
+      end
+
+      def current_question_text
+        (@question_state && @question_state[:question]).to_s
+      end
+
+      def question_selection_index
+        @question_state ? @question_state[:selection_index].to_i : 0
+      end
+
+      def clamp_question_selection_index(count)
+        return unless @question_state
+
+        @question_state[:selection_index] = 0 if count <= 0
+        @question_state[:selection_index] = count - 1 if count.positive? && question_selection_index >= count
+      end
+
+      def question_previous_choice
+        choices = question_choices
+        return if choices.empty?
+
+        @question_state[:selection_index] = (question_selection_index - 1) % choices.length
+      end
+
+      def question_next_choice
+        choices = question_choices
+        return if choices.empty?
+
+        @question_state[:selection_index] = (question_selection_index + 1) % choices.length
+      end
+
+      def question_insert_key(key)
+        return unless key.is_a?(String) && key.length == 1 && key.match?(/[[:print:]]/)
+
+        question_insert_string(key)
+      end
+
+      def question_insert_string(string)
+        return if string.empty?
+
+        self.composer_input = composer_input[0...composer_cursor] + string + composer_input[composer_cursor..]
+        self.composer_cursor += string.length
+        @question_state[:selection_index] = question_choices.length - 1 if @question_state
+      end
+
+      def question_delete_before_cursor
+        return unless composer_cursor.positive?
+
+        self.composer_input = composer_input[0...(composer_cursor - 1)] + composer_input[composer_cursor..]
+        self.composer_cursor -= 1
+        @question_state[:selection_index] = question_choices.length - 1 if @question_state && !composer_input.empty?
+      end
+
+      def question_delete_at_cursor
+        return unless composer_cursor < composer_input.length
+
+        self.composer_input = composer_input[0...composer_cursor] + composer_input[(composer_cursor + 1)..]
+        @question_state[:selection_index] = question_choices.length - 1 if @question_state && !composer_input.empty?
+      end
+
+      def question_composer_layout(width, height = screen_height)
+        content_width = [width - 4, 1].max
+        overlay_rows = active_overlay_rows(width, height: height)
+        rows = overlay_rows + [top_border(width), box_content_row("", content_width), bottom_border(width)]
+        return [rows, question_custom_cursor_row, question_custom_cursor_col(width)] if selected_question_choice&.fetch(:custom, false)
+
+        [rows, overlay_rows.length + 1, 2]
+      end
+
+      def question_overlay_rows(width)
+        title = "Question #{@question_state[:index]}/#{@question_state[:total]} · #{@question_state[:header]}"
+        lines = [
+          overlay_text_line(@question_state[:question].to_s, :bold),
+          overlay_text_line("↑/↓ select · Enter choose · Esc cancel", :muted),
+          overlay_blank_line
+        ]
+        question_choices.each_with_index do |choice, index|
+          selected = index == question_selection_index
+          lines << overlay_choice_line(choice_text(choice, selected: selected), selected: selected)
+        end
+        overlay_card_rows(title, lines, width)
+      end
+
+      def question_custom_cursor_row
+        4 + question_choices.index { |choice| choice[:custom] }.to_i
+      end
+
+      def question_custom_cursor_col(width)
+        card_width = overlay_card_width(width)
+        left_padding = overlay_left_padding(width, card_width)
+        custom_prefix = selected_question_choice&.fetch(:custom, false) || !composer_input.empty? ? "Type something: " : "Type something."
+        visible_before_cursor = display_question_input(composer_input[0...composer_cursor])
+        [[left_padding + 2 + 2 + custom_prefix.length + visible_before_cursor.length, width - 1].min, 0].max
+      end
+
+      def choice_text(choice, selected: false)
+        if choice[:custom]
+          if selected || !composer_input.empty?
+            "Type something: #{display_question_input(composer_input)}"
+          else
+            "Type something."
+          end
+        else
+          description = choice[:description].empty? ? "" : " — #{choice[:description]}"
+          "#{choice[:label]}#{description}"
+        end
+      end
+
+      def display_question_input(value)
+        value.to_s.gsub(/\s+/, " ")
+      end
+
+    end
+  end
+end

data/lib/kward/prompt_interface/runtime_state.rb

@@ -0,0 +1,59 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Runtime metadata shown in the prompt footer and status UI.
+  class PromptInterface
+    # Runtime footer, model, persona, and session state shown by the prompt interface.
+    module RuntimeState
+      private
+
+      def reset_spinner_locked
+        @spinner_frame_index = 0
+        @last_spinner_tick = monotonic_now
+      end
+
+      def normalize_busy_activity(activity)
+        text = activity.to_s.gsub(/\s+/, " ").strip
+        text.empty? ? "streaming" : text
+      end
+
+      def tick_spinner_locked
+        return false unless @busy && @queued_count.zero? && @started && @asking
+
+        now = monotonic_now
+        elapsed = now - @last_spinner_tick
+        return false if elapsed < SPINNER_INTERVAL
+
+        steps = (elapsed / SPINNER_INTERVAL).floor
+        @spinner_frame_index = (@spinner_frame_index + steps) % SPINNER_FRAMES.length
+        @last_spinner_tick += steps * SPINNER_INTERVAL
+        true
+      end
+
+      def spinner_frame
+        SPINNER_FRAMES[@spinner_frame_index % SPINNER_FRAMES.length]
+      end
+
+      def tick_footer_locked
+        return false unless @footer && @started && @asking
+
+        now = monotonic_now
+        elapsed = now - @last_footer_refresh
+        return false if elapsed < FOOTER_REFRESH_INTERVAL
+
+        steps = (elapsed / FOOTER_REFRESH_INTERVAL).floor
+        @last_footer_refresh += steps * FOOTER_REFRESH_INTERVAL
+        true
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+
+      def colored(text, *styles)
+        ANSI.colorize(text, *styles, enabled: @color_enabled)
+      end
+
+    end
+  end
+end

data/lib/kward/prompt_interface/screen.rb

@@ -0,0 +1,186 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Terminal screen lifecycle and escape-sequence management.
+  class PromptInterface
+    # Terminal screen control and escape-sequence helpers.
+    module Screen
+      private
+
+      def enter_raw_mode_locked
+        return unless @input_io.respond_to?(:tty?) && @input_io.tty?
+        return unless @input_io.respond_to?(:console_mode) && @input_io.respond_to?(:console_mode=)
+        return if @raw_mode_active
+
+        @original_console_mode = @input_io.console_mode
+        raw_mode = @input_io.console_mode.raw
+        raw_mode.echo = false
+        @input_io.console_mode = raw_mode
+        @raw_mode_active = true
+      rescue StandardError
+        @original_console_mode = nil
+        @raw_mode_active = false
+      end
+
+      def restore_console_mode_locked
+        return unless @raw_mode_active
+
+        @input_io.console_mode = @original_console_mode if @original_console_mode
+      ensure
+        @original_console_mode = nil
+        @raw_mode_active = false
+      end
+
+      def with_synchronized_output_locked
+        if @restoring_transcript || @synchronized_output_depth.positive?
+          yield
+          return
+        end
+
+        synchronized = true
+        @synchronized_output_depth += 1
+        @output_io.print(SYNCHRONIZED_OUTPUT_ENABLE)
+        yield
+      ensure
+        if synchronized
+          @synchronized_output_depth -= 1
+          @output_io.print(SYNCHRONIZED_OUTPUT_DISABLE) if @synchronized_output_depth.zero?
+        end
+      end
+
+      def hide_cursor_for_transcript_output_locked
+        return unless @started && @asking
+
+        set_cursor_visible_locked(false)
+      end
+
+      def render_cursor_visibility_locked
+        visible = !(@question_state && !selected_question_choice&.fetch(:custom, false))
+        set_cursor_visible_locked(visible)
+      end
+
+      def set_cursor_visible_locked(visible, force: false)
+        return if !force && @cursor_visible == visible
+
+        @output_io.print(visible ? CURSOR_SHOW : CURSOR_HIDE)
+        @cursor_visible = visible
+      end
+
+      def reserve_composer_region_locked(width: screen_width, height: screen_height)
+        rows, = composer_layout(width, height)
+        ensure_scroll_region_locked(rows.length, width: width, height: height)
+      end
+
+      def ensure_scroll_region_locked(row_count, redraw_transcript: true, width: screen_width, height: screen_height)
+        new_reserved_rows = [[row_count, 1].max, [height - 1, 1].max].min
+        return if @reserved_rows == new_reserved_rows && @last_height == height
+
+        old_reserved_rows = @reserved_rows
+        rows_to_clear = [old_reserved_rows, new_reserved_rows].max
+        @reserved_rows = new_reserved_rows
+        @output_io.print("\e[1;#{transcript_bottom_row(height)}r")
+        clear_composer_region_locked(rows_to_clear, height: height)
+        redraw_transcript_locked(width: width, height: height) if redraw_transcript && new_reserved_rows < old_reserved_rows
+      end
+
+      def handle_resize_locked
+        current_width, current_height = screen_size
+        return false if current_width == @last_width && current_height == @last_height
+
+        old_width = @last_width
+        old_height = @last_height
+        old_reserved_rows = @reserved_rows
+        restore_scroll_region_locked
+        rows_to_clear = resize_prompt_clear_rows(old_width, current_width, old_reserved_rows)
+        clear_resized_composer_region_locked(old_height, current_height, rows_to_clear)
+        @reserved_rows = 0
+        @last_width = current_width
+        @last_height = current_height
+        redraw_screen_locked(width: current_width, height: current_height)
+        true
+      end
+
+      def restore_scroll_region_locked
+        @output_io.print("\e[r")
+        @reserved_rows = 0
+      end
+
+      def render_composer_rows_locked(rows, height: screen_height)
+        top = composer_top_row(height)
+        max_rows = [@last_composer_rows.length, rows.length].max
+        rows_to_clear = [@reserved_rows - rows.length, 0].max
+
+        max_rows.times do |index|
+          row = rows[index]
+          previous = @last_composer_rows[index]
+          next if row == previous
+
+          move_to_screen(top + index, 1)
+          @output_io.print(TTY::Cursor.clear_line)
+          @output_io.print(row) unless row.to_s.empty?
+        end
+
+        rows.length.upto(rows.length + rows_to_clear - 1) do |index|
+          move_to_screen(top + index, 1)
+          @output_io.print(TTY::Cursor.clear_line)
+        end
+
+        @last_composer_rows = rows.dup
+      end
+
+      def clear_composer_region_locked(rows_to_clear = nil, height: screen_height)
+        rows_to_clear ||= [@reserved_rows, @rendered_rows].max
+        clear_bottom_rows_locked(height, rows_to_clear)
+        @last_composer_rows = []
+      end
+
+      def resize_prompt_clear_rows(old_width, current_width, old_reserved_rows)
+        return old_reserved_rows unless old_reserved_rows.positive?
+
+        return old_reserved_rows unless current_width < old_width
+
+        wrapped_rows_per_row = ((old_width - 1) / current_width) + 1
+        old_reserved_rows * wrapped_rows_per_row
+      end
+
+      def clear_resized_composer_region_locked(old_height, current_height, rows_to_clear)
+        return unless rows_to_clear.positive?
+
+        old_top = [old_height - rows_to_clear + 1, 1].max
+        current_top = [current_height - rows_to_clear + 1, 1].max
+        clear_screen_rows_locked([old_top, current_top].min, current_height)
+      end
+
+      def clear_bottom_rows_locked(height, rows_to_clear)
+        return unless rows_to_clear.positive?
+
+        bottom = height
+        top = [bottom - rows_to_clear + 1, 1].max
+        clear_screen_rows_locked(top, bottom)
+      end
+
+      def clear_screen_rows_locked(top, bottom)
+        top.upto(bottom) do |row|
+          move_to_screen(row, 1)
+          @output_io.print(TTY::Cursor.clear_line)
+        end
+      end
+
+      def move_to_screen(row, col)
+        @output_io.print("\e[#{row};#{col}H")
+      end
+
+      def screen_size
+        [screen_width, screen_height]
+      end
+
+      def screen_width
+        [TTY::Screen.width, 1].max
+      end
+
+      def screen_height
+        [TTY::Screen.height, 2].max
+      end
+
+    end
+  end
+end