kward 0.81.0 → 0.82.0

data/lib/kward/prompt_interface.rb

@@ -4,6 +4,8 @@ require "pathname"
 require "rbconfig"
 require "thread"
 require_relative "project_files"
+require_relative "image_attachments"
+require_relative "terminal_image_support"
 require_relative "prompt_history"
 require "tty-cursor"
 require "tty-reader"
@@ -68,6 +70,7 @@ module Kward
     FOOTER_REFRESH_INTERVAL = 1.0
     COMPOSER_STATUS_REFRESH_INTERVAL = 1.0
     COMPOSER_MAX_INPUT_ROWS = 6
+    IMAGE_VIEWER_MAX_ROWS = 8
     TRANSCRIPT_BUFFER_LIMIT = 200_000
     BANNER_MESSAGE = Banner::MESSAGE
 
@@ -131,6 +134,9 @@ module Kward
     def initialize(input: $stdin, output: $stdout, slash_commands: [], overlay_settings: nil, project_browser_icon_theme: "off", footer: nil, composer_status: nil, busy_help: true, attachment_badges: nil, attachment_parser: nil, banner_message: nil, tab_keybindings: nil, prompt_history: nil, workspace_root: Dir.pwd, editor_mode: nil, editor_mode_source: nil, editor_auto_indent: true, editor_auto_indent_source: nil, editor_auto_close_pairs: true, editor_auto_close_pairs_source: nil, editor_soft_wrap: true, editor_soft_wrap_source: nil, editor_bar_cursor: true, editor_bar_cursor_source: nil, editor_line_numbers: "absolute", editor_line_numbers_source: nil, diff_view: "auto", diff_view_source: nil, redraw_handler: nil)
       @input_io = input
       @output_io = output
+      # Logical state may change during a child handoff, but only the owner may render.
+      @terminal_owner = :kward
+      @terminal_handoff_mode = nil
       @reader = TTY::Reader.new(input: input, output: output, interrupt: :error)
       @mutex = Mutex.new
       @prompt_history = prompt_history
@@ -178,6 +184,8 @@ module Kward
       @file_editor_open_status = nil
       @file_mention_paths = nil
       @project_browser_state = nil
+      @image_viewer_state = nil
+      @terminal_image_protocol = nil
       @project_browser_restore_after_editor = false
       @editor_state = nil
       @interactive_state = nil
@@ -237,8 +245,8 @@ module Kward
         @started = true
         @asking = true
         disable_editor_mouse_reporting(force: true) unless editor_active?
-        @output_io.print(KEYBOARD_PROTOCOL_ENABLE)
-        @output_io.print(BRACKETED_PASTE_ENABLE)
+        print_output_locked(KEYBOARD_PROTOCOL_ENABLE)
+        print_output_locked(BRACKETED_PASTE_ENABLE)
         render_prompt_locked if render
       end
     end
@@ -247,15 +255,16 @@ module Kward
       @mutex.synchronize do
         return unless @started
 
+        clear_image_viewer_output_locked if image_viewer_active?
         clear_prompt_for_output_locked
         restore_scroll_region_locked
         disable_editor_mouse_reporting(force: true)
-        @output_io.print(BRACKETED_PASTE_RESTORE)
-        @output_io.print(KEYBOARD_PROTOCOL_RESTORE)
+        print_output_locked(BRACKETED_PASTE_RESTORE)
+        print_output_locked(KEYBOARD_PROTOCOL_RESTORE)
         restore_editor_cursor_shape_locked
         set_cursor_visible_locked(true, force: true)
-        @output_io.puts
-        @output_io.flush
+        puts_output_locked
+        flush_output_locked
         @started = false
         restore_console_mode_locked
       end
@@ -281,14 +290,14 @@ module Kward
           @stream_state.finish_block
           render_prompt_after_output_locked
         end
-        @output_io.flush
+        flush_output_locked
       end
     end
 
     def restore_transcript
       start(render: false) unless @started
       @mutex.synchronize do
-        @output_io.print(SYNCHRONIZED_OUTPUT_ENABLE)
+        print_output_locked(SYNCHRONIZED_OUTPUT_ENABLE)
         clear_prompt_for_output_locked unless @rendered_rows.zero? && @last_composer_rows.empty?
         @transcript_buffer.clear
         @transcript_viewport_rows = 0
@@ -303,8 +312,8 @@ module Kward
         @restoring_transcript = false
         width, height = screen_size
         redraw_screen_locked(width: width, height: height)
-        @output_io.print(SYNCHRONIZED_OUTPUT_DISABLE)
-        @output_io.flush
+        print_output_locked(SYNCHRONIZED_OUTPUT_DISABLE)
+        flush_output_locked
       end
     end
 
@@ -343,6 +352,10 @@ module Kward
       @mutex.synchronize { editor_active? }
     end
 
+    def inline_image_protocol
+      @mutex.synchronize { terminal_image_protocol }
+    end
+
     def update_workspace_root(root, prompt_history: nil)
       @mutex.synchronize do
         expanded_root = File.expand_path(root.to_s.empty? ? Dir.pwd : root)
@@ -575,16 +588,21 @@ module Kward
         @interactive_state = nil
         restore_composer_snapshot_locked(snapshot)
         redraw_screen_locked if @started
-        @output_io.flush
+        flush_output_locked
       end
     end
 
-    def with_terminal_handoff(preserve_composer: false)
+    def with_inline_terminal_handoff(&block)
+      with_terminal_handoff(inline: true, &block)
+    end
+
+    def with_terminal_handoff(inline: false)
       start
       input = nil
       output = nil
+      transition = nil
       @mutex.synchronize do
-        if preserve_composer
+        if inline
           handle_resize_locked
           reserve_composer_region_locked
           move_to_transcript_cursor_locked
@@ -593,27 +611,36 @@ module Kward
           restore_scroll_region_locked
         end
         disable_editor_mouse_reporting(force: true)
-        @output_io.print(BRACKETED_PASTE_RESTORE)
-        @output_io.print(KEYBOARD_PROTOCOL_RESTORE)
+        print_output_locked(BRACKETED_PASTE_RESTORE)
+        print_output_locked(KEYBOARD_PROTOCOL_RESTORE)
         restore_editor_cursor_shape_locked
         set_cursor_visible_locked(true, force: true)
-        @output_io.flush
+        flush_output_locked
         restore_console_mode_locked
         input = @input_io
         output = @output_io
+        transition = method(:switch_terminal_handoff_to_exclusive)
+        @terminal_handoff_mode = inline ? :inline : :exclusive
+        @terminal_owner = :child
       end
 
-      yield(input, output)
+      yield(input, output, transition)
     ensure
       @mutex.synchronize do
-        restore_scroll_region_locked if preserve_composer
-        make_room_for_composer_after_handoff_locked if !preserve_composer && @started && @asking
+        @terminal_owner = :kward
+        @terminal_handoff_mode = nil
+        restore_scroll_region_locked
+        print_output_locked(TerminalSequences::SGR_RESET)
         enter_raw_mode_locked
-        @output_io.print(KEYBOARD_PROTOCOL_ENABLE)
-        @output_io.print(BRACKETED_PASTE_ENABLE)
+        print_output_locked(KEYBOARD_PROTOCOL_ENABLE)
+        print_output_locked(BRACKETED_PASTE_ENABLE)
+        disable_editor_mouse_reporting(force: true)
+        restore_editor_cursor_shape_locked(force: true)
+        @cursor_visible = nil
         @last_composer_rows = []
-        render_prompt_locked if @started && @asking
-        @output_io.flush
+        width, height = screen_size
+        with_synchronized_output_locked { redraw_screen_locked(width: width, height: height) }
+        flush_output_locked
       end
     end
 
@@ -851,7 +878,7 @@ module Kward
           @stream_state.finish_block
           restore_composer_cursor_locked
         end
-        @output_io.flush
+        flush_output_locked
       end
     end
 
@@ -873,7 +900,7 @@ module Kward
       end
     end
 
-    def record_transient_terminal_output(text)
+    def record_transient_terminal_output(text, render: true)
       value = text.to_s
       return if value.empty?
 
@@ -883,8 +910,10 @@ module Kward
         @stream_state.finish_block
         width, height = screen_size
         remember_transcript_viewport_locked(height)
+        next unless render
+
         with_synchronized_output_locked { redraw_screen_locked(width: width, height: height) }
-        @output_io.flush
+        flush_output_locked
       end
     end
 
@@ -895,7 +924,7 @@ module Kward
           write_transcript_text_locked(delta.to_s)
           restore_composer_cursor_locked unless @restoring_transcript
         end
-        @output_io.flush unless @restoring_transcript
+        flush_output_locked unless @restoring_transcript
       end
     end
 
@@ -909,7 +938,7 @@ module Kward
       @mutex.synchronize do
         width, height = screen_size
         with_synchronized_output_locked { redraw_screen_locked(width: width, height: height) }
-        @output_io.flush
+        flush_output_locked
       end
     end
 
@@ -931,12 +960,27 @@ module Kward
         @stream_state.reset
         width, height = screen_size
         with_synchronized_output_locked { redraw_screen_locked(width: width, height: height) }
-        @output_io.flush
+        flush_output_locked
       end
     end
 
     private
 
+    def switch_terminal_handoff_to_exclusive
+      @mutex.synchronize do
+        return unless @terminal_owner == :child && @terminal_handoff_mode == :inline
+
+        @terminal_owner = :kward
+        with_synchronized_output_locked do
+          clear_prompt_for_output_locked
+          restore_scroll_region_locked
+        end
+        flush_output_locked
+        @terminal_handoff_mode = :exclusive
+        @terminal_owner = :child
+      end
+    end
+
     def write_transcript_message(message, preserve_composer:)
       @mutex.synchronize do
         text = message.to_s
@@ -958,12 +1002,11 @@ module Kward
           @stream_state.finish_block
           preserve_composer ? restore_composer_cursor_locked : render_prompt_after_output_locked
         end
-        @output_io.flush
+        flush_output_locked
       end
     end
 
     def request_transcript_redraw
-      redraw_screen_locked
       @transcript_redraw_requested = true
     end
 
@@ -973,7 +1016,13 @@ module Kward
         @transcript_redraw_requested = false
         pending
       end
-      @redraw_handler&.call if requested
+      return unless requested
+
+      if @redraw_handler
+        @redraw_handler.call
+      else
+        redraw
+      end
     end
 
     def prompt_workspace_root
@@ -985,6 +1034,8 @@ module Kward
       @file_mention_path_entries_paths = nil
       @file_mention_path_entries = nil
       @project_browser_state = nil
+      @image_viewer_state = nil
+      @terminal_image_protocol = nil
       @project_browser_tree_paths = nil
       @project_browser_tree = nil
       @file_overlay_dismissed_token = nil

data/lib/kward/pty_output_sink.rb

@@ -0,0 +1,45 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Forwards PTY output immediately and optionally keeps a bounded byte copy.
+  #
+  # The runner only depends on the sink's `write` method and optional `flush`
+  # method. Capture is deliberately byte-oriented so PTY chunk boundaries have
+  # no effect on the retained output.
+  class PassthroughPtyOutputSink
+    attr_reader :captured_output
+
+    def initialize(output:, max_capture_bytes: nil)
+      @output = output
+      @max_capture_bytes = max_capture_bytes
+      @captured_output = max_capture_bytes ? +"".b : nil
+      @truncated = false
+    end
+
+    def write(chunk)
+      @output.write(chunk)
+      capture(chunk)
+    end
+
+    def flush
+      @output.flush if @output.respond_to?(:flush)
+    end
+
+    def truncated?
+      @truncated
+    end
+
+    private
+
+    def capture(chunk)
+      return unless @captured_output
+
+      remaining = @max_capture_bytes - @captured_output.bytesize
+      if chunk.bytesize > remaining
+        @captured_output << chunk.byteslice(0, remaining) if remaining.positive?
+        @truncated = true
+      else
+        @captured_output << chunk
+      end
+    end
+  end
+end

data/lib/kward/pty_transcript_normalizer.rb

@@ -0,0 +1,93 @@
+require_relative "ansi"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Reduces safe, line-oriented PTY redraws to transcript-friendly text.
+  class PtyTranscriptNormalizer
+    HORIZONTAL_REDRAW_PATTERN = /\r|\e\[[0-9;]*[CDGK`]/.freeze
+
+    def self.normalize(text)
+      text.split("\n", -1).map do |line|
+        if line.match?(HORIZONTAL_REDRAW_PATTERN)
+          Line.new(line).render
+        else
+          ANSI.sanitize_transcript(line)
+        end
+      end.join("\n")
+    end
+
+    # Applies the horizontal cursor controls accepted by AdaptivePtyOutputSink
+    # without modeling a complete terminal screen.
+    class Line
+      def initialize(text)
+        @text = text
+        @cells = []
+        @cursor = 0
+      end
+
+      def render
+        ANSI.scan_escape_tokens(@text).each do |token|
+          token[:escape] ? apply_escape(token[:text]) : write_text(token[:text])
+        end
+        @cells.join.rstrip
+      end
+
+      private
+
+      def apply_escape(sequence)
+        final = sequence[-1]
+        return set_column(sequence) if final == "G" || final == "`"
+        return move_cursor(sequence, 1) if final == "C"
+        return move_cursor(sequence, -1) if final == "D"
+        return erase_line(sequence) if final == "K"
+      end
+
+      def set_column(sequence)
+        @cursor = [parameter(sequence, default: 1), 1].max - 1
+      end
+
+      def move_cursor(sequence, direction)
+        distance = [parameter(sequence, default: 1), 1].max
+        @cursor = [@cursor + (distance * direction), 0].max
+      end
+
+      def erase_line(sequence)
+        case parameter(sequence, default: 0)
+        when 1
+          fill_to_cursor
+          0.upto(@cursor) { |index| @cells[index] = " " }
+        when 2
+          @cells.clear
+        else
+          @cells.slice!(@cursor..) if @cursor < @cells.length
+        end
+      end
+
+      def parameter(sequence, default:)
+        value = sequence[2...-1].to_s.split(";", 2).first.to_s
+        value.empty? ? default : value.to_i
+      end
+
+      def write_text(text)
+        text.each_char do |character|
+          case character
+          when "\r"
+            @cursor = 0
+          when "\b"
+            @cursor = [@cursor - 1, 0].max
+          when "\t"
+            @cursor = ((@cursor / 8) + 1) * 8
+          else
+            fill_to_cursor
+            @cells[@cursor] = character
+            @cursor += 1
+          end
+        end
+      end
+
+      def fill_to_cursor
+        @cells.concat([" "] * (@cursor - @cells.length)) if @cursor > @cells.length
+      end
+    end
+  end
+end

data/lib/kward/session_catalog.rb

@@ -0,0 +1,87 @@
+require "json"
+require_relative "private_file"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Rebuildable lightweight summaries for persisted session event logs.
+  #
+  # Session JSONL files remain authoritative. Catalog entries are accepted only
+  # while their source fingerprint matches and may be deleted at any time.
+  class SessionCatalog
+    VERSION = 1
+    INDEX_DIRECTORY = ".index"
+    FILENAME = "sessions.json"
+
+    def initialize(session_dir:)
+      @path = File.join(session_dir, INDEX_DIRECTORY, FILENAME)
+      @entries = load_entries
+      @dirty = false
+    end
+
+    def fetch(path)
+      entry = @entries[entry_key(path)]
+      return nil unless entry.is_a?(Hash)
+      return nil unless entry["source"] == fingerprint(path)
+
+      entry["summary"] if entry["summary"].is_a?(Hash)
+    rescue StandardError
+      nil
+    end
+
+    def write(path, summary, fingerprint: self.fingerprint(path))
+      @entries[entry_key(path)] = {
+        "source" => fingerprint,
+        "summary" => summary
+      }
+      @dirty = true
+    end
+
+    def remove(path)
+      @dirty = true if @entries.delete(entry_key(path))
+    end
+
+    def retain(paths)
+      keys = paths.to_h { |path| [entry_key(path), true] }
+      previous_size = @entries.size
+      @entries.delete_if { |key, _entry| !keys[key] }
+      @dirty = true if @entries.size != previous_size
+    end
+
+    def flush
+      return unless @dirty
+
+      PrivateFile.write_json(@path, {
+        "version" => VERSION,
+        "entries" => @entries
+      })
+      @dirty = false
+    rescue StandardError
+      nil
+    end
+
+    def fingerprint(path)
+      stat = File.stat(path)
+      {
+        "size" => stat.size,
+        "inode" => stat.ino,
+        "mtimeSeconds" => stat.mtime.to_i,
+        "mtimeNanoseconds" => stat.mtime.nsec
+      }
+    end
+
+    private
+
+    def load_entries
+      data = JSON.parse(File.read(@path))
+      return {} unless data["version"] == VERSION && data["entries"].is_a?(Hash)
+
+      data["entries"]
+    rescue StandardError
+      {}
+    end
+
+    def entry_key(path)
+      File.basename(path)
+    end
+  end
+end

data/lib/kward/session_store.rb

@@ -9,6 +9,7 @@ require_relative "message_access"
 require_relative "message_text"
 require_relative "private_file"
 require_relative "rpc/tool_event_normalizer"
+require_relative "session_catalog"
 require_relative "tools/tool_call"
 require_relative "workspace"
 
@@ -204,6 +205,7 @@ module Kward
     def initialize(config_dir: ConfigFiles.config_dir, cwd: Dir.pwd)
       @config_dir = config_dir
       @cwd = File.expand_path(cwd)
+      @session_catalog = SessionCatalog.new(session_dir: session_dir)
     end
 
     # @return [String] workspace directory this store lists and creates sessions for
@@ -399,6 +401,8 @@ module Kward
       return false unless unused_session_file?(path)
 
       File.delete(path)
+      @session_catalog.remove(path)
+      @session_catalog.flush
       true
     rescue StandardError
       false
@@ -849,21 +853,43 @@ module Kward
       keep_empty_paths = Array(keep_empty_path).filter_map do |path|
         File.expand_path(path) unless path.to_s.empty?
       end
-      paths = Dir.glob(File.join(session_dir, "*.jsonl")).sort_by { |path| session_file_activity_time(path) }.reverse
-      sessions = []
+      paths = Dir.glob(File.join(session_dir, "*.jsonl"))
+      @session_catalog.retain(paths)
+      return all_recent_sessions(paths, keep_empty_paths: keep_empty_paths) if limit.nil?
+
+      candidates = paths.map do |path|
+        info = cataloged_session_info(path)
+        [path, info, info&.modified_at || session_file_activity_time(path)]
+      end
+      candidates.sort_by! { |_path, _info, modified_at| modified_at }.reverse!
 
-      paths.each do |path|
-        if limit.nil? || sessions.length < limit
-          info = session_info(path)
+      sessions = []
+      candidates.each do |path, cataloged_info, _modified_at|
+        if sessions.length < limit
+          info = cataloged_info || cache_session_info(path)
           next unless info
           next if delete_empty_unnamed_session_info(info, keep_empty_paths: keep_empty_paths)
 
           sessions << info
+        elsif cataloged_info
+          delete_empty_unnamed_session_info(cataloged_info, keep_empty_paths: keep_empty_paths)
         else
           delete_empty_unnamed_session_path(path, keep_empty_paths: keep_empty_paths)
         end
       end
       sessions
+    ensure
+      @session_catalog.flush
+    end
+
+    def all_recent_sessions(paths, keep_empty_paths:)
+      paths.filter_map do |path|
+        info = cataloged_session_info(path) || cache_session_info(path)
+        next unless info
+        next if delete_empty_unnamed_session_info(info, keep_empty_paths: keep_empty_paths)
+
+        info
+      end.sort_by(&:modified_at).reverse
     end
 
     def delete_empty_unnamed_session_info(info, keep_empty_paths: [])
@@ -871,6 +897,7 @@ module Kward
       return true if keep_empty_paths.include?(File.expand_path(info.path))
 
       File.delete(info.path)
+      @session_catalog.remove(info.path)
       true
     rescue StandardError
       false
@@ -895,6 +922,7 @@ module Kward
       return true if keep_empty_paths.include?(File.expand_path(path))
 
       File.delete(path)
+      @session_catalog.remove(path)
       true
     rescue StandardError
       false
@@ -944,6 +972,67 @@ module Kward
       end
     end
 
+    def cataloged_session_info(path)
+      summary = @session_catalog.fetch(path)
+      session_info_from_summary(path, summary) if summary
+    end
+
+    def cache_session_info(path)
+      fingerprint = @session_catalog.fingerprint(path)
+      info = session_info(path)
+      return nil unless info
+
+      current_fingerprint = @session_catalog.fingerprint(path)
+      if fingerprint == current_fingerprint
+        @session_catalog.write(path, session_info_summary(info), fingerprint: current_fingerprint)
+      end
+      info
+    rescue StandardError
+      nil
+    end
+
+    def session_info_summary(info)
+      {
+        "id" => info.id,
+        "cwd" => info.cwd,
+        "createdAt" => info.created_at.utc.iso8601(9),
+        "modifiedAt" => info.modified_at.utc.iso8601(9),
+        "name" => info.name,
+        "firstMessage" => info.first_message,
+        "messageCount" => info.message_count,
+        "provider" => info.provider,
+        "model" => info.model,
+        "reasoningEffort" => info.reasoning_effort,
+        "parentId" => info.parent_id,
+        "parentPath" => info.parent_path
+      }
+    end
+
+    def session_info_from_summary(path, summary)
+      created_at = parse_time(summary["createdAt"])
+      modified_at = parse_time(summary["modifiedAt"])
+      return nil if summary["id"].to_s.empty? || !created_at || !modified_at
+
+      SessionInfo.new(
+        id: summary["id"],
+        path: path,
+        cwd: summary["cwd"].to_s,
+        created_at: created_at,
+        modified_at: modified_at,
+        name: summary["name"],
+        first_message: summary["firstMessage"].to_s,
+        message_count: summary["messageCount"].to_i,
+        provider: summary["provider"],
+        model: summary["model"],
+        reasoning_effort: summary["reasoningEffort"],
+        parent_id: summary["parentId"],
+        parent_path: summary["parentPath"],
+        depth: 0,
+        is_last: true,
+        ancestor_continues: []
+      )
+    end
+
     def session_info(path)
       records = records_from_file(path)
       header = session_header(records, path)