kward 0.67.1 → 0.68.0

data/lib/kward/prompt_interface/composer_state.rb

@@ -0,0 +1,221 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Interactive terminal UI used by the CLI frontend.
+  class PromptInterface
+    # Mutable text, cursor, history, and overlay state for the composer.
+    class ComposerState
+      # @return [String] editable text currently shown in the composer
+      attr_accessor :input
+      # @return [Integer] cursor offset into `input`
+      attr_accessor :cursor
+      # @return [String] most recently killed text available for yank
+      attr_accessor :kill_buffer
+      # @return [Integer, nil] active history index while navigating history
+      attr_accessor :history_index
+      # @return [String, nil] draft restored after leaving history navigation
+      attr_accessor :history_draft
+      # @return [String, nil] text queued for the next composer prompt
+      attr_accessor :prefill_input
+      # @return [Array<Hash>] pending image/file attachments submitted with the next turn
+      attr_reader :attachments
+      # @return [Array<String>] submitted input history
+      attr_reader :history
+
+      def initialize
+        @input = +""
+        @cursor = 0
+        @attachments = []
+        @kill_buffer = ""
+        @history = []
+        @history_index = nil
+        @history_draft = nil
+        @prefill_input = nil
+      end
+
+      # Removes all pending attachments without changing text input.
+      def clear_attachments
+        @attachments.clear
+      end
+
+      # Adds one attachment unless its source is already pending.
+      def add_attachment(attachment)
+        return false unless attachment.respond_to?(:key?)
+
+        source = attachment[:source_text] || attachment["source_text"] || attachment[:original_path] || attachment["original_path"]
+        return false if source.to_s.empty?
+        return false if @attachments.any? { |item| (item[:source_text] || item["source_text"]).to_s == source.to_s }
+
+        @attachments << attachment
+        true
+      end
+
+      # Removes the most recently added attachment.
+      def remove_last_attachment
+        return false if @attachments.empty?
+
+        @attachments.pop
+        true
+      end
+
+      # Inserts text at the cursor and advances by the inserted length.
+      def insert_string(string)
+        return if string.empty?
+
+        @input = @input[0...@cursor] + string + @input[@cursor..]
+        @cursor += string.length
+      end
+
+      # Deletes one character before the cursor.
+      def delete_before_cursor
+        return false if @cursor.zero?
+
+        @input = @input[0...(@cursor - 1)] + @input[@cursor..]
+        @cursor -= 1
+        true
+      end
+
+      # Deletes one character at the cursor without moving it.
+      def delete_at_cursor
+        return false unless @cursor < @input.length
+
+        @input = @input[0...@cursor] + @input[(@cursor + 1)..]
+        true
+      end
+
+      # Moves the cursor one character left when possible.
+      def move_cursor_left
+        @cursor -= 1 if @cursor.positive?
+      end
+
+      # Moves the cursor one character right when possible.
+      def move_cursor_right
+        @cursor += 1 if @cursor < @input.length
+      end
+
+      # Moves the cursor to the beginning of the input buffer.
+      def move_to_start_of_line
+        @cursor = 0
+      end
+
+      # Moves the cursor to the end of the input buffer.
+      def move_to_end_of_line
+        @cursor = @input.length
+      end
+
+      # Moves the cursor to the previous word boundary.
+      def move_to_previous_word
+        @cursor = previous_word_boundary(@cursor)
+      end
+
+      # Moves the cursor to the next word boundary.
+      def move_to_next_word
+        @cursor = next_word_boundary(@cursor)
+      end
+
+      # Kills the word before the cursor into `kill_buffer`.
+      def delete_word_before_cursor
+        kill_range(previous_word_boundary(@cursor), @cursor)
+      end
+
+      # Kills the word after the cursor into `kill_buffer`.
+      def delete_word_after_cursor
+        kill_range(@cursor, next_word_boundary(@cursor))
+      end
+
+      # Kills all text before the cursor into `kill_buffer`.
+      def kill_line_before_cursor
+        kill_range(0, @cursor)
+      end
+
+      # Kills all text after the cursor into `kill_buffer`.
+      def kill_line_after_cursor
+        kill_range(@cursor, @input.length)
+      end
+
+      # Removes a range, stores it in `kill_buffer`, and moves the cursor to the start.
+      def kill_range(start_index, end_index)
+        return false if start_index == end_index
+
+        @kill_buffer = @input[start_index...end_index].to_s
+        @input = @input[0...start_index].to_s + @input[end_index..].to_s
+        @cursor = start_index
+        true
+      end
+
+      # Inserts the last killed text at the cursor.
+      def yank_kill_buffer
+        insert_string(@kill_buffer.to_s) unless @kill_buffer.to_s.empty?
+      end
+
+      # Finds the start offset of the word before `index`.
+      def previous_word_boundary(index)
+        cursor = index
+        cursor -= 1 while cursor.positive? && word_separator?(@input[cursor - 1])
+        cursor -= 1 while cursor.positive? && !word_separator?(@input[cursor - 1])
+        cursor
+      end
+
+      # Finds the end offset of the word after `index`.
+      def next_word_boundary(index)
+        cursor = index
+        cursor += 1 while cursor < @input.length && word_separator?(@input[cursor])
+        cursor += 1 while cursor < @input.length && !word_separator?(@input[cursor])
+        cursor
+      end
+
+      # Treats whitespace as the only word separator for composer navigation.
+      def word_separator?(char)
+        char.to_s.match?(/\s/)
+      end
+
+      # Replaces the full input buffer and places the cursor at the end.
+      def replace_input(value)
+        @input = value.to_s
+        @cursor = @input.length
+      end
+
+      # Returns `[row, column]` for cursor placement in multi-line input.
+      def cursor_logical_position
+        before_cursor = @input[0...@cursor]
+        [before_cursor.count("\n"), (before_cursor.split("\n", -1).last || "").length]
+      end
+
+      # Stores a submitted input unless it is blank or duplicates the previous entry.
+      def add_history(value)
+        stripped = value.to_s.strip
+        return if stripped.empty?
+        return if @history.last == value
+
+        @history << value
+      end
+
+      # Replaces input with the previous history entry, preserving the draft first.
+      def recall_previous_history
+        return if @history.empty?
+
+        @history_draft = @input if @history_index.nil?
+        @history_index = @history_index.nil? ? @history.length - 1 : [@history_index - 1, 0].max
+        replace_input(@history[@history_index])
+      end
+
+      # Replaces input with the next history entry or restores the saved draft.
+      def recall_next_history
+        return if @history_index.nil?
+
+        if @history_index < @history.length - 1
+          @history_index += 1
+          replace_input(@history[@history_index])
+        else
+          replace_input(@history_draft || "")
+          reset_history_navigation
+        end
+      end
+
+      # Leaves history navigation and clears the saved draft/index state.
+      def reset_history_navigation
+        @history_index = nil
+        @history_draft = nil
+      end
+    end
+  end
+end

data/lib/kward/prompt_interface/key_handler.rb

@@ -0,0 +1,365 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Keyboard sequence dispatcher for composer and overlay input.
+  class PromptInterface
+    # Keyboard sequence handling for the terminal prompt interface.
+    module KeyHandler
+      private
+
+      def read_key(nonblock: false)
+        pending = @pending_keys.shift unless @pending_keys.empty?
+        return pending if pending
+
+        @reader.read_keypress(echo: false, raw: true, nonblock: nonblock)
+      rescue TTY::Reader::InputInterrupt
+        "\x03"
+      rescue IO::WaitReadable, Errno::EAGAIN, Errno::EWOULDBLOCK
+        nil
+      end
+
+      def handle_key(key)
+        return submit_input if key.nil?
+        return if handle_bracketed_paste_key(key)
+
+        csi_result = handle_csi_u_key(key)
+        return csi_result unless csi_result == false
+        return if handle_shift_enter_key(key)
+        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_key(token)
+          end
+        end
+
+        binding_result = handle_composer_key_binding(key)
+        return binding_result unless binding_result == false
+
+        key_name = @reader.console.keys[key]
+        case key_name
+        when :return, :enter
+          submit_input
+        when :backspace
+          delete_before_cursor
+        when :delete
+          delete_at_cursor
+        when :ctrl_d
+          delete_at_cursor_or_exit
+        when :ctrl_c
+          cancel_input_or_interrupt
+        when :ctrl_a
+          move_to_start_of_line
+        when :ctrl_e
+          move_to_end_of_line
+        when :ctrl_b
+          move_cursor_left
+        when :ctrl_f
+          move_cursor_right
+        when :ctrl_w
+          delete_word_before_cursor
+        when :ctrl_u
+          kill_line_before_cursor
+        when :ctrl_k
+          kill_line_after_cursor
+        when :ctrl_y
+          yank_kill_buffer
+        when :ctrl_l
+          redraw_screen_locked
+        when :left
+          move_cursor_left
+        when :right
+          move_cursor_right
+        when :home
+          move_to_start_of_line
+        when :end
+          move_to_end_of_line
+        when :up
+          slash_overlay_visible? ? select_previous_slash_command : recall_previous_history
+        when :down
+          slash_overlay_visible? ? select_next_slash_command : recall_next_history
+        else
+          case key
+          when "\n", "\r"
+            submit_input
+          when "\t"
+            complete_selected_slash_command || insert_key(key)
+          when "\b", "\x7F"
+            delete_before_cursor
+          when "\x04"
+            delete_at_cursor_or_exit
+          when "\x03"
+            cancel_input_or_interrupt
+          when "\e"
+            handle_escape_sequence
+          else
+            insert_key(key)
+          end
+        end
+      end
+
+      def cancel_input_or_interrupt
+        return CANCEL_INPUT if @busy
+
+        raise Interrupt
+      end
+
+      def handle_escape_sequence
+        pending_sequence = read_pending_escape_sequence
+        return true if pending_sequence.empty? && dismiss_slash_overlay
+
+        full_sequence = "\e#{pending_sequence}"
+        sequence = next_key_token(full_sequence)
+        queue_pending_keys(full_sequence[sequence.length..]) if full_sequence.length > sequence.length
+        return true if sequence == "\e" && dismiss_slash_overlay
+        return true if handle_shift_enter_key(sequence)
+
+        binding_result = handle_composer_key_binding(sequence)
+        return binding_result unless binding_result == false
+
+        key_name = @reader.console.keys[sequence]
+        case key_name
+        when :up
+          slash_overlay_visible? ? select_previous_slash_command : recall_previous_history
+        when :down
+          slash_overlay_visible? ? select_next_slash_command : recall_next_history
+        when :left
+          move_cursor_left
+        when :right
+          move_cursor_right
+        when :home
+          move_to_start_of_line
+        when :end
+          move_to_end_of_line
+        when :delete
+          delete_at_cursor
+        end
+        true
+      end
+
+      def handle_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)
+        insert_paste(normalize_paste(content || ""))
+        queue_pending_keys(remaining) if remaining && !remaining.empty?
+        true
+      end
+
+      def normalize_paste(content)
+        content.gsub("\r\n", "\n").gsub("\r", "\n")
+      end
+
+      def handle_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
+        modifier = (match[2] || "1").split(":", 2).first.to_i
+        queue_pending_keys(key[sequence.length..]) if key.length > sequence.length
+
+        case code
+        when 13
+          modifier == 2 ? insert_string("\n") : submit_input
+        when 27
+          dismiss_slash_overlay || false
+        when 8, 127
+          alt_modifier?(modifier) ? delete_word_before_cursor : delete_before_cursor
+          nil
+        when 4
+          delete_at_cursor_or_exit
+        else
+          handle_modified_csi_u_key(code, modifier)
+        end
+      end
+
+      def handle_modified_csi_u_key(code, modifier)
+        return false unless ctrl_modifier?(modifier) || alt_modifier?(modifier)
+
+        normalized_code = code.to_i.chr.downcase.ord rescue code
+        if ctrl_modifier?(modifier)
+          case normalized_code
+          when 97
+            move_to_start_of_line
+          when 98
+            move_cursor_left
+          when 99
+            cancel_input_or_interrupt
+          when 100
+            delete_at_cursor_or_exit
+          when 101
+            move_to_end_of_line
+          when 102
+            move_cursor_right
+          when 104
+            delete_before_cursor
+          when 107
+            kill_line_after_cursor
+          when 108
+            redraw_screen_locked
+          when 117
+            kill_line_before_cursor
+          when 119
+            delete_word_before_cursor
+          when 121
+            yank_kill_buffer
+          else
+            false
+          end
+        elsif alt_modifier?(modifier)
+          case normalized_code
+          when 98
+            move_to_previous_word
+          when 100
+            delete_word_after_cursor
+          when 102
+            move_to_next_word
+          else
+            false
+          end
+        else
+          false
+        end
+      end
+
+      def ctrl_modifier?(modifier)
+        ((modifier.to_i - 1) & 4).positive?
+      end
+
+      def alt_modifier?(modifier)
+        ((modifier.to_i - 1) & 2).positive?
+      end
+
+      def handle_shift_enter_key(key)
+        sequence = shift_enter_sequence_for(key)
+        return false unless sequence
+
+        insert_string("\n")
+        queue_pending_keys(key[sequence.length..]) if key.length > sequence.length
+        true
+      end
+
+      def queue_pending_keys(keys)
+        remaining = keys.to_s
+        until remaining.empty?
+          token = next_key_token(remaining)
+          @pending_keys << token
+          remaining = remaining[token.length..] || ""
+        end
+      end
+
+      def next_key_token(keys)
+        text = keys.to_s
+        text.match(/\A\e\[[0-9;:]*[A-Za-z~]/)&.[](0) ||
+          text.match(/\A\eO[A-Za-z]/)&.[](0) ||
+          shift_enter_sequence_for(text) ||
+          (text.start_with?("\e") && text.length > 1 && alt_key_sequence?(text[1]) ? text[0, 2] : text[0, 1])
+      end
+
+      def alt_key_sequence?(char)
+        char = char.to_s
+        char.match?(/[[:alpha:]]/) || char == "\b" || char == "\x7F"
+      end
+
+      def shift_enter_sequence_for(key)
+        return nil unless key.is_a?(String)
+
+        SHIFT_ENTER_SEQUENCES.find { |sequence| key.start_with?(sequence) }
+      end
+
+      def read_pending_escape_sequence
+        sequence = +""
+        until @pending_keys.empty?
+          sequence << @pending_keys.shift.to_s
+        end
+        while (char = @reader.read_keypress(echo: false, raw: true, nonblock: true))
+          sequence << char.to_s
+        end
+        sequence
+      rescue IO::WaitReadable, Errno::EAGAIN, Errno::EWOULDBLOCK
+        sequence
+      end
+
+      def handle_composer_key_binding(key)
+        case key
+        when "\x01"
+          move_to_start_of_line
+        when "\x02"
+          move_cursor_left
+        when "\x04"
+          delete_at_cursor_or_exit
+        when "\x05"
+          move_to_end_of_line
+        when "\x06"
+          move_cursor_right
+        when "\x0B"
+          kill_line_after_cursor
+        when "\x0C"
+          redraw_screen_locked
+        when "\x15"
+          kill_line_before_cursor
+        when "\x17"
+          delete_word_before_cursor
+        when "\x19"
+          yank_kill_buffer
+        when "\e[D", "\eOD"
+          move_cursor_left
+        when "\e[C", "\eOC"
+          move_cursor_right
+        when "\e[H", "\eOH", "\e[1~", "\e[7~"
+          move_to_start_of_line
+        when "\e[F", "\eOF", "\e[4~", "\e[8~"
+          move_to_end_of_line
+        when "\e[3~"
+          delete_at_cursor
+        when "\eb", "\eB"
+          move_to_previous_word
+        when "\ef", "\eF"
+          move_to_next_word
+        when "\ed", "\eD"
+          delete_word_after_cursor
+        when "\e\b", "\e\x7F"
+          delete_word_before_cursor
+        else
+          handle_modified_ansi_key(key) || false
+        end
+      end
+
+      def handle_modified_ansi_key(key)
+        match = key.to_s.match(/\A\e\[(\d+);(\d+)([CDFH])\z/)
+        if match
+          modifier = match[2].to_i
+          final = match[3]
+          return false unless alt_modifier?(modifier)
+
+          case final
+          when "C"
+            move_to_next_word
+          when "D"
+            move_to_previous_word
+          when "F"
+            move_to_end_of_line
+          when "H"
+            move_to_start_of_line
+          else
+            false
+          end
+        elsif (match = key.to_s.match(/\A\e\[3;(\d+)~\z/))
+          alt_modifier?(match[1].to_i) ? delete_word_after_cursor : delete_at_cursor
+        else
+          false
+        end
+      end
+
+    end
+  end
+end

data/lib/kward/prompt_interface/layout.rb

@@ -0,0 +1,31 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Layout calculations for terminal rows and overlay placement.
+  class PromptInterface
+    # Terminal layout calculations for transcript, overlays, footer, and composer.
+    module Layout
+      private
+
+      def banner_rows(width)
+        @banner.rows(width)
+      end
+
+      def banner_logo_rows
+        @banner.logo_rows(screen_width)
+      end
+
+      def transcript_redraw_row_count(height = screen_height)
+        [[@transcript_viewport_rows, transcript_bottom_row(height)].max, height].min
+      end
+
+      def composer_top_row(height = screen_height)
+        [height - @reserved_rows + 1, 1].max
+      end
+
+      def transcript_bottom_row(height = screen_height)
+        [height - @reserved_rows, 1].max
+      end
+
+    end
+  end
+end