kward 0.84.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,4 +1,4 @@
-require_relative "../terminal_text"
+require_relative "../terminal/text"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward

data/lib/kward/prompt_interface/composer_state.rb

@@ -1,6 +1,6 @@
 require_relative "../text_boundary"
 require_relative "../text_matcher"
-require_relative "../terminal_text"
+require_relative "../terminal/text"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward

data/lib/kward/prompt_interface/editor/controller.rb

@@ -1,5 +1,5 @@
 require "fileutils"
-require_relative "../../scratchpad_languages"
+require_relative "scratchpad_languages"
 require_relative "runner"
 
 # Namespace for the Kward CLI agent runtime.

data/lib/kward/prompt_interface/editor/runner.rb

@@ -1,4 +1,4 @@
-require_relative "../../scratchpad_runner"
+require_relative "scratchpad_runner"
 require_relative "runner_state"
 
 # Namespace for the Kward CLI agent runtime.

data/lib/kward/prompt_interface/editor/state.rb

@@ -1,4 +1,4 @@
-require_relative "../../editor_mode"
+require_relative "editor_mode"
 require_relative "../../text_boundary"
 require_relative "buffer"
 require_relative "file_marker"

data/lib/kward/prompt_interface/layout.rb

@@ -19,7 +19,7 @@ module Kward
       end
 
       def transcript_bottom_row(height = screen_height)
-        [height - @reserved_rows, 1].max
+        [height - @reserved_rows - TRANSCRIPT_COMPOSER_GAP_ROWS, 1].max
       end
 
     end

data/lib/kward/prompt_interface/overlay_renderer.rb

@@ -1,4 +1,4 @@
-require_relative "../terminal_text"
+require_relative "../terminal/text"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward

data/lib/kward/prompt_interface/plugin_ui_requests.rb

@@ -0,0 +1,82 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  class PromptInterface
+    # Terminal implementations of the frontend-neutral plugin UI requests.
+    module PluginUIRequests
+      def request_plugin_ui(kind, payload, cancellation: nil)
+        cancellation&.raise_if_cancelled!
+        result = case kind.to_sym
+                 when :question then ask_user_question(payload.fetch(:questions))
+                 when :select then request_plugin_select(payload)
+                 when :confirm then request_plugin_confirmation(payload)
+                 when :input then request_plugin_input(payload)
+                 else raise ArgumentError, "unsupported plugin UI request: #{kind}"
+                 end
+        cancellation&.raise_if_cancelled!
+        result
+      end
+
+      private
+
+      def request_plugin_select(payload)
+        options = payload.fetch(:options)
+        labels = options.map { |option| plugin_option_text(option) }
+        selected = with_plugin_ui_modal_state do
+          select(payload[:message] || "Choose an option", labels, title: payload.fetch(:title))
+        end
+        return nil if selected.nil?
+
+        option = options[labels.index(selected)]
+        option && option.fetch(:value)
+      end
+
+      def request_plugin_confirmation(payload)
+        yes = { label: "Yes", description: "Continue." }
+        no = { label: "No", description: "Cancel." }
+        answers = ask_user_question([
+          {
+            header: payload.fetch(:title),
+            question: payload.fetch(:message),
+            options: payload[:default] ? [yes, no] : [no, yes]
+          }
+        ])
+        return false unless answers
+
+        answers.first[:answer].to_s.casecmp?("yes")
+      end
+
+      def request_plugin_input(payload)
+        with_plugin_ui_modal_state do
+          @mutex.synchronize do
+            self.composer_input = payload[:default].to_s
+            self.composer_cursor = composer_input.length
+            @composer.prefill_input = nil
+            @composer.clear_attachments
+            @pending_keys.clear
+            @busy = false
+            @asking = true
+          end
+          label = payload[:placeholder].to_s.empty? ? payload.fetch(:title) : "#{payload.fetch(:title)} · #{payload[:placeholder]}"
+          answer = ask("#{label}>")
+          answer.is_a?(String) ? answer : nil
+        end
+      end
+
+      def with_plugin_ui_modal_state
+        saved_state = @mutex.synchronize do
+          state = begin_question_prompt_state
+          @question_prompt_active = true
+          state
+        end
+        yield
+      ensure
+        finish_question_prompt(saved_state) if saved_state
+      end
+
+      def plugin_option_text(option)
+        description = option[:description].to_s
+        description.empty? ? option.fetch(:label) : "#{option.fetch(:label)} — #{description}"
+      end
+    end
+  end
+end

data/lib/kward/prompt_interface/runtime_state.rb

@@ -108,13 +108,18 @@ module Kward
       end
 
       def refresh_footer_text_locked
-        @cached_footer_text = @footer.call.to_s.gsub(/\s+/, " ").strip
+        @cached_footer_text = call_footer([screen_width - 4, 1].max).to_s.gsub(/\s+/, " ").strip
       rescue StandardError
         @cached_footer_text = ""
       ensure
         @last_footer_refresh = monotonic_now
       end
 
+      def call_footer(max_width)
+        arity = @footer.respond_to?(:arity) ? @footer.arity : @footer.method(:call).arity
+        arity.zero? ? @footer.call : @footer.call(max_width)
+      end
+
       def cached_composer_status_text
         return nil unless @composer_status
 

data/lib/kward/prompt_interface/screen.rb

@@ -118,10 +118,16 @@ module Kward
         old_top = [height - old_reserved_rows + 1, 1].max
         @reserved_rows = new_reserved_rows
         new_top = composer_top_row(height)
-        print_output_locked(TerminalSequences.scroll_region(1, transcript_bottom_row(height)))
+        new_bottom = transcript_bottom_row(height)
+        print_output_locked(TerminalSequences.scroll_region(1, new_bottom))
         clear_screen_rows_locked(old_top, new_top - 1) if new_top > old_top
+        clear_screen_rows_locked(new_bottom + 1, new_top - 1) if old_reserved_rows.positive? && new_bottom < new_top - 1
         @last_composer_rows = []
-        redraw_transcript_locked(width: width, height: height) if redraw_transcript && new_reserved_rows < old_reserved_rows
+        if redraw_transcript && @stream_state.block && new_reserved_rows > old_reserved_rows
+          @transcript_viewport_rows = [@transcript_viewport_rows, new_bottom].min
+        end
+        should_redraw_transcript = redraw_transcript && (new_reserved_rows < old_reserved_rows || @stream_state.block)
+        redraw_transcript_locked(width: width, height: height) if should_redraw_transcript && new_reserved_rows != old_reserved_rows
       end
 
       def handle_resize_locked
@@ -139,6 +145,7 @@ module Kward
         @reserved_rows = 0
         @last_width = current_width
         @last_height = current_height
+        @last_footer_refresh = nil if current_width != old_width
         if interactive_active_locked?
           @interactive_state[:controller].resize(width: interactive_canvas_width(current_width))
         end