kward 0.67.0 → 0.68.0

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

data/lib/kward/prompt_interface/selection_prompt.rb

@@ -0,0 +1,242 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Selection overlay implementation for list-style prompts.
+  class PromptInterface
+    # Selection-list overlay support for prompt choices.
+    module SelectionPrompt
+      private
+
+      def handle_select_key(key)
+        return select_current_choice if key.nil?
+        return if handle_select_bracketed_paste_key(key)
+
+        csi_result = handle_select_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_select_key(token)
+          end
+        end
+
+        key_name = @reader.console.keys[key]
+        case key_name
+        when :return, :enter
+          select_current_choice
+        when :backspace
+          select_delete_before_cursor
+        when :delete
+          select_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
+          select_previous_choice
+        when :down
+          select_next_choice
+        else
+          case key
+          when "\n", "\r"
+            select_current_choice
+          when "\b", "\x7F"
+            select_delete_before_cursor
+          when "\e"
+            handle_select_escape_sequence
+          else
+            select_insert_key(key)
+          end
+        end
+      end
+
+      def handle_select_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
+          select_current_choice
+        when 27
+          SELECT_CANCEL
+        when 8, 127
+          select_delete_before_cursor
+          nil
+        else
+          false
+        end
+      end
+
+      def handle_select_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
+          select_previous_choice
+        when :down
+          select_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_select_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)
+        select_insert_string(normalize_paste(content || ""))
+        queue_pending_keys(remaining) if remaining && !remaining.empty?
+        true
+      end
+
+      def select_current_choice
+        selected_selection_choice || custom_selection_choice || SELECT_CANCEL
+      end
+
+      def custom_selection_choice
+        return nil unless @select_state && @select_state[:custom]
+
+        value = composer_input.strip
+        value.empty? ? nil : value
+      end
+
+      def selected_selection_choice
+        matches = selection_matches
+        return nil if matches.empty?
+
+        matches[selection_index]
+      end
+
+      def select_previous_choice
+        matches = selection_matches
+        return if matches.empty?
+
+        @select_state[:selection_index] = (selection_index - 1) % matches.length
+      end
+
+      def select_next_choice
+        matches = selection_matches
+        return if matches.empty?
+
+        @select_state[:selection_index] = (selection_index + 1) % matches.length
+      end
+
+      def select_insert_key(key)
+        return unless key.is_a?(String) && key.length == 1 && key.match?(/[[:print:]]/)
+
+        select_insert_string(key)
+      end
+
+      def select_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
+        @select_state[:selection_index] = 0 if @select_state
+      end
+
+      def select_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
+        @select_state[:selection_index] = 0 if @select_state
+      end
+
+      def select_delete_at_cursor
+        return unless composer_cursor < composer_input.length
+
+        self.composer_input = composer_input[0...composer_cursor] + composer_input[(composer_cursor + 1)..]
+        @select_state[:selection_index] = 0 if @select_state
+      end
+
+      def selection_matches
+        choices = @select_state ? @select_state[:choices] : []
+        filter = composer_input.downcase.strip
+        matches = filter.empty? ? choices : choices.select { |choice| choice.downcase.include?(filter) }
+        clamp_selection_index(matches.length)
+        matches
+      end
+
+      def selection_index
+        @select_state ? @select_state[:selection_index].to_i : 0
+      end
+
+      def clamp_selection_index(count)
+        return unless @select_state
+
+        @select_state[:selection_index] = 0 if count <= 0
+        @select_state[:selection_index] = count - 1 if count.positive? && selection_index >= count
+      end
+
+      def finish_select_prompt
+        @mutex.synchronize do
+          @select_state = nil
+          clear_prompt_locked
+          self.composer_input = ""
+          self.composer_cursor = 0
+          @asking = false
+          @rendered_rows = 0
+          @cursor_rendered_row = 0
+          @output_io.flush
+        end
+      end
+
+      def selection_overlay_rows(width, height: screen_height)
+        matches = selection_matches
+        lines = [overlay_text_line("↑/↓ select · Enter open · Esc cancel", :muted), overlay_blank_line]
+        if matches.empty?
+          if @select_state && @select_state[:custom] && !composer_input.strip.empty?
+            lines << overlay_choice_line("Use custom: #{composer_input.strip}", selected: true)
+          else
+            lines << overlay_text_line("No matches", :muted)
+          end
+          return overlay_card_rows(selection_overlay_title, lines, width)
+        end
+
+        visible = visible_selection_matches(matches, height: height)
+        start_index = visible[:start]
+        visible[:choices].each_with_index do |choice, offset|
+          index = start_index + offset
+          lines << overlay_choice_line(choice, selected: index == selection_index)
+        end
+        overlay_card_rows(selection_overlay_title, lines, width)
+      end
+
+      def selection_overlay_title
+        title = @select_state && @select_state[:title].to_s
+        title && !title.empty? ? title : "Sessions"
+      end
+
+      def visible_selection_matches(matches, height: screen_height)
+        max_rows = [[height - 7, 1].max, 8].min
+        start = [[selection_index - max_rows + 1, 0].max, [matches.length - max_rows, 0].max].min
+        { start: start, choices: matches[start, max_rows] || [] }
+      end
+
+    end
+  end
+end

data/lib/kward/prompt_interface/slash_overlay.rb

@@ -0,0 +1,102 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Slash-command completion overlay behavior.
+  class PromptInterface
+    # Slash-command completion overlay support.
+    module SlashOverlay
+      private
+
+      def reset_slash_selection
+        @slash_selection_index = 0
+      end
+
+      def dismiss_slash_overlay
+        return false unless slash_overlay_visible?
+
+        @slash_overlay_dismissed_input = composer_input.dup
+        reset_slash_selection
+        true
+      end
+
+      def normalize_slash_commands(commands)
+        commands.map do |command|
+          {
+            name: slash_command_value(command, :name).to_s,
+            description: slash_command_value(command, :description).to_s,
+            argument_hint: slash_command_value(command, :argument_hint).to_s
+          }
+        end.reject { |command| command[:name].empty? }.sort_by { |command| command[:name] }
+      end
+
+      def slash_command_value(command, key)
+        return command[key] if command.respond_to?(:key?) && command.key?(key)
+        return command[key.to_s] if command.respond_to?(:key?) && command.key?(key.to_s)
+        return command.public_send(key) if command.respond_to?(key)
+
+        ""
+      end
+
+      def slash_overlay_visible?
+        composer_input.match?(%r{\A/[^\s/]*\z}) && @slash_overlay_dismissed_input != composer_input && !slash_overlay_matches.empty?
+      end
+
+      def slash_overlay_matches
+        prefix = composer_input.delete_prefix("/").downcase
+        @slash_commands.select { |command| command[:name].downcase.start_with?(prefix) }.first(8)
+      end
+
+      def selected_slash_command
+        return nil unless slash_overlay_visible?
+
+        matches = slash_overlay_matches
+        return nil if matches.empty?
+
+        matches[[@slash_selection_index, matches.length - 1].min]
+      end
+
+      def select_previous_slash_command
+        matches = slash_overlay_matches
+        return if matches.empty?
+
+        @slash_selection_index = (@slash_selection_index - 1) % matches.length
+      end
+
+      def select_next_slash_command
+        matches = slash_overlay_matches
+        return if matches.empty?
+
+        @slash_selection_index = (@slash_selection_index + 1) % matches.length
+      end
+
+      def complete_selected_slash_command
+        command = selected_slash_command
+        return false unless command
+
+        replace_input("/#{command[:name]} ")
+        reset_slash_selection
+        true
+      end
+
+      def slash_overlay_rows(width, height: screen_height)
+        return [] unless slash_overlay_visible?
+
+        visible = visible_slash_overlay_matches(slash_overlay_matches, height: height)
+        start_index = visible[:start]
+        lines = visible[:commands].each_with_index.map do |command, offset|
+          index = start_index + offset
+          hint = command[:argument_hint].empty? ? "" : " #{command[:argument_hint]}"
+          description = command[:description].empty? ? "" : " — #{command[:description]}"
+          overlay_choice_line("/#{command[:name]}#{hint}#{description}", selected: index == @slash_selection_index)
+        end
+        overlay_card_rows("Slash commands", lines, width)
+      end
+
+      def visible_slash_overlay_matches(matches, height: screen_height)
+        max_rows = [[height - 7, 1].max, 8].min
+        start = [[@slash_selection_index - max_rows + 1, 0].max, [matches.length - max_rows, 0].max].min
+        { start: start, commands: matches[start, max_rows] || [] }
+      end
+
+    end
+  end
+end

data/lib/kward/prompt_interface/stream_state.rb

@@ -0,0 +1,65 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Cursor/column state for streamed assistant blocks.
+  class PromptInterface
+    # State object for streamed assistant output blocks.
+    class StreamState
+      attr_reader :block, :col
+
+      def initialize
+        reset
+      end
+
+      def reset
+        @block = nil
+        @col = 0
+        @pending_wrap = false
+      end
+
+      def start_block(label)
+        @block = label
+      end
+
+      def finish_block
+        @block = nil
+      end
+
+      def pending_wrap?
+        @pending_wrap
+      end
+
+      def reset_position_from_rows(rows, width)
+        last_length = rows.empty? ? 0 : ANSI.strip(rows.last).length
+        if last_length >= width
+          @col = 0
+          @pending_wrap = true
+        else
+          @col = last_length
+          @pending_wrap = false
+        end
+      end
+
+      def clear_pending_wrap
+        @col = 0
+        @pending_wrap = false
+      end
+
+      def update_position(text, width:)
+        ANSI.strip(text).each_char do |char|
+          case char
+          when "\n", "\r"
+            @col = 0
+            @pending_wrap = false
+          else
+            @pending_wrap = false
+            @col += 1
+            if @col >= width
+              @col = 0
+              @pending_wrap = true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kward/prompt_interface/transcript_buffer.rb

@@ -0,0 +1,85 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Bounded text buffer for transcript rendering.
+  class PromptInterface
+    # Bounded in-memory transcript buffer used by the prompt interface.
+    class TranscriptBuffer
+      attr_reader :text
+
+      def initialize(limit:)
+        @limit = limit
+        @text = +""
+        @display_rows_cache_width = nil
+        @display_rows_cache_banner_count = nil
+        @display_rows_cache = nil
+      end
+
+      def to_s
+        @text
+      end
+
+      def include?(*arguments)
+        @text.include?(*arguments)
+      end
+
+      def empty?
+        @text.empty?
+      end
+
+      def end_with?(*suffixes)
+        @text.end_with?(*suffixes)
+      end
+
+      def clear
+        @text = +""
+        invalidate_display_rows_cache
+      end
+
+      def append(text)
+        @text << ANSI.sanitize_transcript(text)
+        @text = @text[-@limit, @limit] if @text.length > @limit
+        invalidate_display_rows_cache
+        @text
+      end
+
+      def viewport_text(row_count, width, visual_banner_count:, banner_rows:)
+        viewport_rows(row_count, width, visual_banner_count: visual_banner_count, banner_rows: banner_rows).join("\n")
+      end
+
+      def viewport_rows(row_count, width, visual_banner_count:, banner_rows:)
+        return [] unless row_count.positive?
+
+        rows = display_rows(width, visual_banner_count: visual_banner_count, banner_rows: banner_rows).last(row_count)
+        rows = ([""] * (row_count - rows.length)) + rows if rows.length < row_count
+        rows
+      end
+
+      def display_rows(width, visual_banner_count:, banner_rows:)
+        if @display_rows_cache_width == width && @display_rows_cache_banner_count == visual_banner_count && @display_rows_cache
+          return @display_rows_cache
+        end
+
+        rows = []
+        visual_banner_count.times { rows.concat(banner_rows.call(width)) }
+        rows << "" if visual_banner_count.positive? && @text.empty?
+        rows.concat(text_display_rows(width))
+        @display_rows_cache_width = width
+        @display_rows_cache_banner_count = visual_banner_count
+        @display_rows_cache = rows
+      end
+
+      def text_display_rows(width)
+        @text.split(/\r\n|\r|\n/, -1).flat_map do |line|
+          chunks = ANSI.wrap_visible(line, width)
+          chunks.empty? ? [""] : chunks
+        end
+      end
+
+      def invalidate_display_rows_cache
+        @display_rows_cache_width = nil
+        @display_rows_cache_banner_count = nil
+        @display_rows_cache = nil
+      end
+    end
+  end
+end