kward 0.83.0 → 0.85.0

data/lib/kward/plugins/resources.rb

@@ -0,0 +1,206 @@
+require "thread"
+require_relative "../cancellation"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Idempotent cleanup registration owned by a plugin runtime.
+  class PluginDisposable
+    def initialize(resource = nil, &cleanup)
+      raise ArgumentError, "plugin cleanup requires a block or closeable resource" unless cleanup || resource&.respond_to?(:close)
+
+      @resource = resource
+      @cleanup = cleanup
+      @mutex = Mutex.new
+      @disposed = false
+    end
+
+    def disposed?
+      @mutex.synchronize { @disposed }
+    end
+
+    def dispose
+      cleanup = @mutex.synchronize do
+        return false if @disposed
+
+        @disposed = true
+        @cleanup
+      end
+
+      if cleanup
+        cleanup.arity.zero? ? cleanup.call : cleanup.call(@resource)
+      else
+        @resource.close
+      end
+      true
+    end
+  end
+
+  # Cooperative background task owned by a plugin runtime.
+  class PluginTask
+    attr_reader :name, :cancellation
+
+    def initialize(name:, cancellation:, &work)
+      @name = name.to_s.freeze
+      @cancellation = cancellation
+      @work = work
+      @mutex = Mutex.new
+      @thread = nil
+      @result = nil
+      @error = nil
+    end
+
+    def start(&finished)
+      @mutex.synchronize do
+        raise "Plugin task #{name.inspect} has already started" if @thread
+
+        @thread = Thread.new do
+          begin
+            cancellation.raise_if_cancelled!
+            result = @work.arity.zero? ? @work.call : @work.call(cancellation)
+            @mutex.synchronize { @result = result }
+          rescue Cancellation::CancelledError
+            nil
+          rescue StandardError => e
+            @mutex.synchronize { @error = e }
+          ensure
+            finished&.call(self)
+          end
+        end
+        @thread.report_on_exception = false
+      end
+      self
+    end
+
+    def cancel!
+      cancellation.cancel!
+      self
+    end
+
+    def cancelled?
+      cancellation.cancelled?
+    end
+
+    def alive?
+      thread = @mutex.synchronize { @thread }
+      thread&.alive? == true
+    end
+
+    def complete?
+      !alive?
+    end
+
+    def join(timeout = nil)
+      thread = @mutex.synchronize { @thread }
+      thread&.join(timeout)
+      self
+    end
+
+    def result
+      join
+      @mutex.synchronize { @result }
+    end
+
+    def error
+      @mutex.synchronize { @error }
+    end
+  end
+
+  # Owns cleanup callbacks and cooperative background tasks for a plugin or tab.
+  class PluginResources
+    DEFAULT_SHUTDOWN_TIMEOUT = 1.0
+
+    def initialize(name:, warning_sink: nil)
+      @name = name.to_s
+      @warning_sink = warning_sink
+      @mutex = Mutex.new
+      @state = :initialized
+      @tasks = []
+      @disposables = []
+      @next_task_id = 0
+    end
+
+    def activate!
+      @mutex.synchronize do
+        raise "#{@name} resources have already been stopped" if @state == :stopped
+
+        @state = :active
+      end
+      self
+    end
+
+    def background(name: nil, cancellation: nil, &work)
+      raise ArgumentError, "plugin background task requires a block" unless work
+
+      task = @mutex.synchronize do
+        raise "#{@name} background work cannot start before plugin activation" unless @state == :active
+
+        @next_task_id += 1
+        task_name = name.to_s.empty? ? "task-#{@next_task_id}" : name.to_s
+        task_cancellation = Cancellation.new
+        cancellation&.on_cancel { task_cancellation.cancel! }
+        PluginTask.new(name: task_name, cancellation: task_cancellation, &work).tap do |created|
+          @tasks << created
+          created.start { |finished| finish_task(finished) }
+        end
+      end
+      task
+    end
+
+    def on_cleanup(resource = nil, &cleanup)
+      disposable = PluginDisposable.new(resource, &cleanup)
+      @mutex.synchronize do
+        raise "#{@name} resources have already been stopped" if @state == :stopped
+
+        @disposables << disposable
+      end
+      disposable
+    end
+
+    alias manage on_cleanup
+
+    def shutdown(timeout: DEFAULT_SHUTDOWN_TIMEOUT)
+      tasks, disposables = @mutex.synchronize do
+        return self if @state == :stopped
+
+        @state = :stopped
+        [@tasks.dup, @disposables.reverse]
+      end
+
+      tasks.each(&:cancel!)
+      disposables.each { |disposable| dispose(disposable) }
+      join_tasks(tasks, timeout)
+      self
+    end
+
+    private
+
+    def finish_task(task)
+      error = task.error
+      @mutex.synchronize { @tasks.delete(task) }
+      warn("#{@name} background task #{task.name.inspect} failed: #{error.message}") if error
+    end
+
+    def dispose(disposable)
+      disposable.dispose
+    rescue StandardError => e
+      warn("#{@name} cleanup failed: #{e.message}")
+    end
+
+    def join_tasks(tasks, timeout)
+      deadline = monotonic_time + [timeout.to_f, 0].max
+      tasks.each do |task|
+        remaining = deadline - monotonic_time
+        task.join(remaining) if remaining.positive?
+        warn("#{@name} background task #{task.name.inspect} did not stop before shutdown") if task.alive?
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def warn(message)
+      @warning_sink ? @warning_sink.call("Warning: #{message}") : Kernel.warn("Warning: #{message}")
+    end
+  end
+end

data/lib/kward/plugins/turn_request.rb

@@ -0,0 +1,36 @@
+require "securerandom"
+
+module Kward
+  # Immutable, host-dispatched system instructions for one session turn.
+  # Historical records retain the instructions for display, not model replay.
+  class PluginTurnRequest
+    MAX_SYSTEM_BYTES = 65_536
+
+    attr_reader :system, :command, :plugin_id, :id
+
+    def initialize(system:, command:, plugin_id: nil, id: SecureRandom.uuid)
+      unless system.is_a?(String) && system.valid_encoding? && !system.strip.empty? && system.bytesize <= MAX_SYSTEM_BYTES
+        raise ArgumentError, "System instructions must be nonblank text of at most #{MAX_SYSTEM_BYTES} bytes"
+      end
+
+      @system = system.dup.freeze
+      @command = command.to_s.dup.freeze
+      @plugin_id = plugin_id&.to_s&.dup&.freeze
+      @id = id.to_s.dup.freeze
+      freeze
+    end
+
+    def to_s
+      "/#{command} #{system}"
+    end
+
+    def history_message
+      {
+        role: "user",
+        content: "A plugin requested a system-instruction turn. Those instructions are not active in later turns.",
+        display_content: to_s,
+        plugin_system_turn: { id: id, command: command, plugin_id: plugin_id, system: system, scope: "turn" }
+      }
+    end
+  end
+end

data/lib/kward/plugins/ui.rb

@@ -0,0 +1,219 @@
+require_relative "../deep_copy"
+require_relative "../question_contract"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Frontend-neutral structured UI exposed to trusted plugin handlers.
+  #
+  # Frontends provide a small backend that handles blocking requests and
+  # non-blocking events. Unsupported requests fail closed: selection, question,
+  # and input return nil, while confirmation returns false.
+  class PluginUI
+    FEATURES = %i[question select confirm input progress notify].freeze
+    NOTIFICATION_LEVELS = %i[info success warning error].freeze
+    MAX_TEXT_BYTES = 16_384
+    MAX_OPTIONS = 100
+    MAX_ID_BYTES = 128
+
+    # Adapts frontend callbacks to the structured plugin UI contract.
+    class Backend
+      def initialize(capabilities: {}, requester: nil, emitter: nil)
+        @capabilities = FEATURES.to_h { |feature| [feature, capability_enabled?(capabilities, feature)] }.freeze
+        @requester = requester
+        @emitter = emitter
+      end
+
+      attr_reader :capabilities
+
+      def supported?(feature)
+        @capabilities.fetch(feature.to_sym, false)
+      end
+
+      def request(kind, payload, cancellation: nil)
+        return nil unless supported?(kind) && @requester
+
+        @requester.call(kind.to_sym, payload, cancellation: cancellation)
+      end
+
+      def emit(kind, payload)
+        return false unless supported?(kind) && @emitter
+
+        @emitter.call(kind.to_sym, payload)
+        true
+      end
+
+      private
+
+      def capability_enabled?(capabilities, feature)
+        value = capabilities[feature] || capabilities[feature.to_s]
+        value.is_a?(Hash) ? value.fetch(:supported, value.fetch("supported", false)) == true : value == true
+      end
+    end
+
+    def initialize(backend: nil, say_callback: nil, cancellation: nil)
+      @backend = backend || Backend.new
+      @say_callback = say_callback
+      @cancellation = cancellation
+    end
+
+    def capabilities
+      @backend.capabilities.dup.freeze
+    end
+
+    def supported?(feature)
+      @backend.supported?(feature)
+    end
+
+    def question(questions)
+      normalized = QuestionContract.normalize_questions(questions)
+      request(:question, questions: normalized)
+    end
+
+    def select(title, options, message: nil)
+      normalized = normalize_options(options)
+      answer = request(
+        :select,
+        title: required_text(title, "select title"),
+        message: optional_text(message),
+        options: normalized
+      )
+      return nil if answer.nil?
+
+      selected = normalized.find { |option| option[:value] == answer.to_s || option[:label] == answer.to_s }
+      raise ArgumentError, "plugin UI returned an unknown selection" unless selected
+
+      selected[:value]
+    end
+
+    def confirm(title, message = nil, default: false)
+      if message.nil?
+        message = title
+        title = "Confirm"
+      end
+      answer = request(
+        :confirm,
+        title: required_text(title, "confirm title"),
+        message: required_text(message, "confirm message"),
+        default: default == true
+      )
+      answer == true
+    end
+
+    def input(title, placeholder = nil, default: nil)
+      answer = request(
+        :input,
+        title: required_text(title, "input title"),
+        placeholder: optional_text(placeholder),
+        default: optional_text(default)
+      )
+      return nil if answer.nil?
+      raise ArgumentError, "plugin UI input answer must be a string" unless answer.is_a?(String)
+
+      bounded_text(answer, "input answer")
+    end
+
+    def notify(message, level = :info, **options)
+      level = options[:level] if options.key?(:level)
+      level = level.to_sym
+      raise ArgumentError, "unsupported plugin notification level: #{level}" unless NOTIFICATION_LEVELS.include?(level)
+
+      payload = { message: required_text(message, "notification message"), level: level }
+      @say_callback&.call(payload[:message]) unless @backend.emit(:notify, immutable(payload))
+      nil
+    end
+
+    def progress(id = nil, message = nil, percent: nil, done: false, **values)
+      id ||= values[:id]
+      message ||= values[:message]
+      payload = {
+        id: required_text(id, "progress id", max_bytes: MAX_ID_BYTES),
+        message: required_text(message, "progress message"),
+        percent: normalize_percent(percent),
+        done: done == true
+      }.compact
+      unless @backend.emit(:progress, immutable(payload))
+        fallback = payload[:percent] ? "#{payload[:message]} (#{payload[:percent]}%)" : payload[:message]
+        @say_callback&.call(fallback)
+      end
+      nil
+    end
+
+    def with_cancellation(cancellation)
+      self.class.new(backend: @backend, say_callback: @say_callback, cancellation: cancellation)
+    end
+
+    private
+
+    def request(kind, payload)
+      return false if kind == :confirm && !supported?(kind)
+      return nil unless supported?(kind)
+
+      @cancellation&.raise_if_cancelled!
+      answer = @backend.request(kind, immutable(payload), cancellation: @cancellation)
+      @cancellation&.raise_if_cancelled!
+      answer
+    end
+
+    def normalize_options(options)
+      raise ArgumentError, "select options must be an array" unless options.is_a?(Array)
+      unless options.length.between?(1, MAX_OPTIONS)
+        raise ArgumentError, "select requires 1-#{MAX_OPTIONS} options"
+      end
+
+      normalized = options.map.with_index(1) do |option, index|
+        if option.is_a?(Hash)
+          label = option[:label] || option["label"]
+          value = option.key?(:value) ? option[:value] : option.fetch("value", label)
+          description = option[:description] || option["description"]
+          {
+            label: required_text(label, "select option #{index} label"),
+            value: required_text(value, "select option #{index} value"),
+            description: optional_text(description)
+          }.compact
+        else
+          text = required_text(option, "select option #{index}")
+          { label: text, value: text }
+        end
+      end
+      labels = normalized.map { |option| option[:label] }
+      values = normalized.map { |option| option[:value] }
+      raise ArgumentError, "select option labels must be unique" unless labels.uniq.length == labels.length
+      raise ArgumentError, "select option values must be unique" unless values.uniq.length == values.length
+
+      normalized
+    end
+
+    def normalize_percent(percent)
+      return nil if percent.nil?
+
+      number = Float(percent)
+      raise ArgumentError, "progress percent must be between 0 and 100" unless number.between?(0, 100)
+
+      number % 1 == 0 ? number.to_i : number
+    rescue TypeError, ArgumentError
+      raise ArgumentError, "progress percent must be between 0 and 100"
+    end
+
+    def required_text(value, name, max_bytes: MAX_TEXT_BYTES)
+      text = bounded_text(value, name, max_bytes: max_bytes)
+      raise ArgumentError, "#{name} is required" if text.strip.empty?
+
+      text
+    end
+
+    def optional_text(value)
+      value.nil? ? nil : bounded_text(value, "text")
+    end
+
+    def bounded_text(value, name, max_bytes: MAX_TEXT_BYTES)
+      text = value.to_s
+      raise ArgumentError, "#{name} exceeds #{max_bytes} bytes" if text.bytesize > max_bytes
+
+      text.freeze
+    end
+
+    def immutable(value)
+      DeepCopy.freeze(DeepCopy.dup(value))
+    end
+  end
+end

data/lib/kward/prompt_interface/composer_renderer.rb

@@ -1,3 +1,5 @@
+require_relative "../terminal/text"
+
 # Namespace for the Kward CLI agent runtime.
 module Kward
   # Renderer for the editable composer text area.
@@ -35,45 +37,42 @@ module Kward
       end
 
       def compact_composer_layout(width)
-        cursor_line, cursor_col = cursor_logical_position
+        lines, cursor_line, cursor_col = @composer.lines_and_cursor
         prefix = "#{@prompt_label} "
-        line = input_lines[cursor_line] || ""
-        input_width = [width - prefix.length, 1].max
-        visible_start = [[cursor_col - input_width + 1, 0].max, [line.length - input_width, 0].max].min
-        visible = line[visible_start, input_width].to_s
-        row = "#{prefix}#{visible}"[0, width].to_s.ljust(width)
-        [[row], 0, [prefix.length + cursor_col - visible_start, width - 1].min]
+        prefix_width = TerminalText.width(prefix)
+        line = lines[cursor_line] || ""
+        input_width = [width - prefix_width, 1].max
+        layout = TerminalText.wrap(line, width: input_width, cursor: cursor_col)
+        visible = layout[:rows][layout[:cursor_row]].to_s
+        row = visible_ljust(TerminalText.truncate("#{prefix}#{visible}", width), width)
+        [[row], 0, [prefix_width + layout[:cursor_col], width - 1].min]
       end
 
       def input_layout(content_width)
-        cursor_line, cursor_col = cursor_logical_position
+        lines, cursor_line, cursor_col = @composer.lines_and_cursor
         rows = []
         cursor_row = 0
+        cursor_col_in_row = 0
         rendered_row_offset = 0
 
-        input_lines.each_with_index do |line, index|
+        lines.each_with_index do |line, index|
           prefix = input_prefix(index)
-          continuation_prefix = " " * prefix.length
-          available = [content_width - prefix.length, 1].max
-          chunks = line.scan(/.{1,#{available}}/m)
-          chunks = [""] if chunks.empty?
-          if index == cursor_line && cursor_col == line.length && line.length.positive? && (line.length % available).zero?
-            chunks << ""
-          end
+          prefix_width = TerminalText.width(prefix)
+          continuation_prefix = " " * prefix_width
+          available = [content_width - prefix_width, 1].max
+          layout = TerminalText.wrap(line, width: available, cursor: index == cursor_line ? cursor_col : nil)
 
           if index == cursor_line
-            cursor_row = rendered_row_offset + (cursor_col / available)
+            cursor_row = rendered_row_offset + layout[:cursor_row]
+            cursor_col_in_row = prefix_width + layout[:cursor_col]
           end
 
-          chunks.each_with_index do |chunk, chunk_index|
+          layout[:rows].each_with_index do |chunk, chunk_index|
             rows << "#{chunk_index.zero? ? prefix : continuation_prefix}#{chunk}"
           end
-          rendered_row_offset += chunks.length
+          rendered_row_offset += layout[:rows].length
         end
 
-        prefix = input_prefix(cursor_line)
-        available = [content_width - prefix.length, 1].max
-        cursor_col_in_row = prefix.length + (cursor_col % available)
         [rows, cursor_row, cursor_col_in_row]
       end
 
@@ -81,23 +80,28 @@ module Kward
         title = composer_title
         status = cached_composer_status_text
         if status
-          gap = width - 2 - ANSI.strip(title).length - ANSI.strip(status).length
+          gap = width - 2 - TerminalText.width(ANSI.strip(title)) - TerminalText.width(ANSI.strip(status))
           if gap >= 0
             return colored("╭", :primary_green) + title + colored("─" * gap, :primary_green) + status + colored("╮", :primary_green)
           end
         end
         plain_title = ANSI.strip(title)
-        "#{colored("╭", :primary_green)}#{title}#{colored("─" * [width - plain_title.length - 2, 0].max, :primary_green)}#{colored("╮", :primary_green)}"
+        "#{colored("╭", :primary_green)}#{title}#{colored("─" * [width - TerminalText.width(plain_title) - 2, 0].max, :primary_green)}#{colored("╮", :primary_green)}"
       end
 
       def composer_title
         label = composer_title_label
         if @busy && @queued_count.positive?
-          status_composer_text(busy_title("#{label} · #{@queued_count} queued"))
+          status_composer_text(busy_title("#{label} · #{colored("#{@queued_count} queued", :metadata)}"))
         elsif @busy && @steered_count.to_i.positive?
-          status_composer_text(busy_title("#{label} · #{spinner_frame} steering"))
+          status_composer_text(busy_title("#{label} · #{colored(spinner_frame, :activity, :bold)} steering"))
+        elsif @busy && response_arriving?
+          status_composer_text(busy_title("#{label} · #{colored("✦", :activity, :bold)} responding"))
         elsif @busy
-          status_composer_text(busy_title("#{label} · #{spinner_frame} #{@busy_activity}"))
+          status_composer_text(busy_title("#{label} · #{colored(spinner_frame, :activity, :bold)} #{@busy_activity}"))
+        elsif @completion_status
+          completion = colored(@completion_status[:text], @completion_status[:style], :bold)
+          status_composer_text("#{label} · #{completion}")
         else
           status_composer_text(label)
         end
@@ -110,6 +114,8 @@ module Kward
       end
 
       def busy_title(text)
+        elapsed = busy_elapsed_text
+        text = "#{text} · #{colored(elapsed, :metadata)}" if elapsed
         @busy_help ? "#{text} · #{BUSY_HELP_TEXT}" : text
       end
 
@@ -140,7 +146,7 @@ module Kward
         label_left = 4
         @tabs.each_with_index.map do |label, index|
           text = tab_label(label, index)
-          width = ANSI.strip(text).length
+          width = TerminalText.width(ANSI.strip(text))
           slot = {
             left: label_left - 2,
             label_left: label_left,
@@ -185,18 +191,25 @@ module Kward
 
         visible_offset = 0
         last_index = nil
-        text.to_s.scan(/\e\[[0-9;:]*m|./m).each do |part|
+        text.to_s.scan(/\e\[[0-9;:]*m|\X/m).each do |part|
           if part.start_with?("\e")
             index = visible_offset.positive? ? last_index : left
             row[index] = row[index].to_s + part if index&.between?(0, row.length - 1)
             next
           end
 
+          part_width = TerminalText.width(part)
+          if part_width.zero?
+            row[last_index] = row[last_index].to_s + part if last_index
+            next
+          end
+
           index = left + visible_offset
           break if index >= row.length
           row[index] = row[index].to_s.sub(/\A /, "") + part unless index.negative?
+          1.upto(part_width - 1) { |offset| row[index + offset] = "" if (index + offset).between?(0, row.length - 1) }
           last_index = index
-          visible_offset += 1
+          visible_offset += part_width
         end
       end
 
@@ -252,19 +265,10 @@ module Kward
         [[input_cap, height - 3 - overlay_count - footer_count - attachment_count].min, 1].max
       end
 
-      def input_lines
-        lines = composer_input.split("\n", -1)
-        lines.empty? ? [""] : lines
-      end
-
       def input_prefix(_index)
         ""
       end
 
-      def cursor_logical_position
-        @composer.cursor_logical_position
-      end
-
       def image_viewer_preview_rows(height, width: screen_width)
         available_rows = max_project_browser_rows(height, width: width)
         desired_rows = [(IMAGE_VIEWER_MAX_ROWS * image_viewer_zoom).round, 1].max
@@ -276,7 +280,7 @@ module Kward
         preview_rows = image_viewer_preview_rows(height, width: width)
         title = visible_truncate(" Image: #{@image_viewer_state[:display_path]} ", content_width)
         rows = [
-          colored("╭", :primary_green) + title + colored("─" * [width - ANSI.strip(title).length - 2, 0].max, :primary_green) + colored("╮", :primary_green),
+          colored("╭", :primary_green) + title + colored("─" * [width - TerminalText.width(ANSI.strip(title)) - 2, 0].max, :primary_green) + colored("╮", :primary_green),
           image_viewer_graphic_row(width, image_viewer_sequence(width, height))
         ]
         rows.concat(Array.new(preview_rows - 1) { box_content_row("", content_width) })