kward 0.70.0 → 0.71.0

data/lib/kward/openrouter_model_cache.rb

@@ -0,0 +1,120 @@
+require "digest"
+require "json"
+require "net/http"
+require "time"
+require "uri"
+require_relative "config_files"
+require_relative "private_file"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Fetches and stores the OpenRouter model list available to the configured API key.
+  class OpenRouterModelCache
+    MODELS_URL = URI("https://openrouter.ai/api/v1/models/user")
+    VERSION = 1
+
+    attr_reader :path
+
+    def initialize(api_key:, path: ConfigFiles.openrouter_models_cache_path)
+      @api_key = api_key.to_s
+      @path = File.expand_path(path)
+    end
+
+    def self.model_entry?(entry)
+      return false unless entry.is_a?(Hash)
+
+      architecture = entry["architecture"].is_a?(Hash) ? entry["architecture"] : {}
+      input_modalities = Array(architecture["input_modalities"]).map(&:to_s)
+      output_modalities = Array(architecture["output_modalities"]).map(&:to_s)
+      input_modalities.include?("text") && output_modalities.include?("text")
+    end
+
+    def refresh
+      raise "No OpenRouter API key found. Set OPENROUTER_API_KEY or add openrouter_api_key to your Kward config." if @api_key.empty?
+
+      response = Net::HTTP.start(MODELS_URL.hostname, MODELS_URL.port, use_ssl: true) do |http|
+        http.request(refresh_request)
+      end
+      unless response.is_a?(Net::HTTPSuccess)
+        raise "OpenRouter model refresh failed: #{response.code} #{redact(response.body)}"
+      end
+
+      entries = model_entries(response.body)
+      models = entries.select { |entry| self.class.model_entry?(entry) }.map { |entry| normalize_model(entry) }.uniq { |model| model["id"] }.sort_by { |model| model["id"] }
+      data = cache_data(models)
+      PrivateFile.write_json(@path, data)
+      data
+    end
+
+    def read
+      return nil unless File.exist?(@path)
+
+      data = JSON.parse(File.read(@path))
+      return nil unless data.is_a?(Hash) && data["version"] == VERSION
+
+      data
+    rescue JSON::ParserError
+      nil
+    end
+
+    def models
+      Array(read&.fetch("models", []))
+    end
+
+    def matching_key?
+      data = read
+      return false unless data
+
+      data["api_key_sha256"] == api_key_sha256
+    end
+
+    private
+
+    def refresh_request
+      Net::HTTP::Get.new(MODELS_URL).tap do |request|
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Accept"] = "application/json"
+      end
+    end
+
+    def model_entries(body)
+      data = JSON.parse(body.to_s)
+      entries = data.is_a?(Hash) ? data["data"] || [] : data
+      Array(entries).select { |entry| entry.is_a?(Hash) }
+    rescue JSON::ParserError
+      raise "OpenRouter model refresh returned invalid JSON"
+    end
+
+    def normalize_model(entry)
+      {
+        "provider" => "OpenRouter",
+        "id" => entry.fetch("id").to_s,
+        "name" => entry["name"].to_s.empty? ? entry.fetch("id").to_s : entry["name"].to_s,
+        "contextWindow" => entry["context_length"],
+        "supportedParameters" => Array(entry["supported_parameters"]).map(&:to_s)
+      }.compact
+    end
+
+    def cache_data(models)
+      {
+        "version" => VERSION,
+        "refreshed_at" => Time.now.utc.iso8601,
+        "source" => MODELS_URL.to_s,
+        "filter" => {
+          "input_modalities" => ["text"],
+          "output_modalities" => ["text"]
+        },
+        "api_key_sha256" => api_key_sha256,
+        "models" => models
+      }
+    end
+
+    def api_key_sha256
+      Digest::SHA256.hexdigest(@api_key)
+    end
+
+    def redact(text)
+      text.to_s.gsub(@api_key, "[REDACTED]")
+    end
+  end
+end

data/lib/kward/plugin_registry.rb

@@ -95,7 +95,19 @@ module Kward
       end
     end
 
-    # DSL object yielded by `Kward.plugin` blocks.
+    # Public DSL object yielded by `Kward.plugin` blocks.
+    #
+    # Plugin files normally interact with this object only through a block:
+    #
+    # @example Register a plugin command
+    #   Kward.plugin do |plugin|
+    #     plugin.command "hello", description: "Say hello" do |args, ctx|
+    #       name = args.strip.empty? ? "there" : args.strip
+    #       ctx.say "Hello, #{name}."
+    #     end
+    #   end
+    #
+    # @api public
     class DSL
       # Creates an object for trusted plugin loading and dispatch.
       def initialize(registry, path)
@@ -105,33 +117,53 @@ module Kward
 
       # Registers a slash command.
       #
+      # The command is available in the interactive CLI and through the RPC
+      # command bridge. Command names do not include the leading `/`.
+      #
       # @param name [String, #to_s] command name without the leading slash
       # @param description [String] short text shown in command listings
       # @param argument_hint [String] optional usage hint for arguments
       # @yieldparam args [String] text after the command name
       # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
       def command(name, description: "", argument_hint: "", &block)
         @registry.register_command(name, description: description, argument_hint: argument_hint, path: @path, &block)
       end
 
       # Registers or replaces the custom footer renderer.
       #
+      # Only one footer renderer is active. If multiple plugins register one,
+      # the later renderer replaces the earlier renderer.
+      #
       # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
       def footer(&block)
         @registry.register_footer(path: @path, &block)
       end
 
       # Registers a live transcript event observer.
       #
+      # Observer errors are caught and reported as warnings so a plugin cannot
+      # crash the active turn by raising from an event handler.
+      #
       # @yieldparam event [TranscriptEvent] normalized transcript event
       # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
       def on_transcript_event(&block)
         @registry.register_transcript_event(path: @path, &block)
       end
 
       # Registers prompt context text injected into future system prompts.
       #
+      # Keep this text short and never include secrets. The returned string can
+      # be sent to the active model as part of Kward's system instructions.
+      #
       # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
       def prompt_context(&block)
         @registry.register_prompt_context(path: @path, &block)
       end
@@ -179,11 +211,15 @@ module Kward
       @footer_path = nil
       @transcript_event_handlers = []
       @prompt_context_renderers = []
+      @paths = []
     end
 
     # @return [String, nil] plugin file currently responsible for footer output
     attr_reader :footer_path
 
+    # @return [Array<String>] plugin files successfully loaded by this registry
+    attr_reader :paths
+
     def commands
       @commands.values
     end
@@ -233,6 +269,7 @@ module Kward
       self.class.loading_registry = self
       self.class.loading_path = path
       Kernel.load(path)
+      @paths << path
     rescue StandardError => e
       warn "Warning: skipping Kward plugin #{path}: #{e.message}"
     ensure
@@ -329,6 +366,15 @@ module Kward
     end
   end
 
+  # Registers a trusted local plugin.
+  #
+  # This method is intended for Ruby files loaded from the user plugin
+  # directory. It raises if called outside plugin loading so workspace code
+  # cannot silently mutate Kward's runtime by merely being required.
+  #
+  # @yieldparam plugin [PluginRegistry::DSL] plugin registration DSL
+  # @return [Object, nil] the plugin block result
+  # @api public
   def self.plugin(&block)
     registry = PluginRegistry.loading_registry
     raise "Kward.plugin can only be called while loading a plugin" unless registry

data/lib/kward/prompt_interface/banner.rb

@@ -1,80 +1,45 @@
-require_relative "../ansi"
-require_relative "../resources/avatar_kward_logo"
-require_relative "../resources/pixel_logo"
-
 # Namespace for the Kward CLI agent runtime.
 module Kward
-  # Startup banner logo and message renderer.
+  # Startup banner message renderer.
   class PromptInterface
     # Startup banner rendering data and helpers for the prompt interface.
     class Banner
-      LOGO_WIDTH = 32
-      LOGO_PIXEL_HEIGHT = 32
-      MIN_LOGO_HEIGHT = 4
-      LOGO_PIXELS = Kward::Resources::AvatarKwardLogo::PIXELS
       MESSAGE = "State your business.".freeze
 
-      def initialize(message:, pixels:, screen_height:, minimum_composer_rows: 3)
+      def initialize(message:, screen_height:, minimum_composer_rows: 3)
         @message = message.to_s
-        @pixels = pixels
         @screen_height = screen_height
         @minimum_composer_rows = minimum_composer_rows
-        @logo_cache = {}
       end
 
-      def rows(width)
-        return [] unless visible?(width)
+      def rows(width, message: nil)
+        content = message.nil? ? @message : message.to_s
+        return [] if content.empty? || max_banner_rows <= 0
 
-        rows = []
-        rows.concat(centered_image_rows(width)) if image_visible?(width)
-        rows << align_plain_row(@message, width) unless @message.empty?
-        rows << ""
-        rows
+        visible_lines(content) + [""]
       end
 
-      def logo_rows(width)
-        logo_width, logo_height = logo_dimensions(width)
-        return [] unless @pixels && max_logo_height >= MIN_LOGO_HEIGHT
-
-        key = [logo_width, logo_height]
-        @logo_cache[key] ||= Kward::PixelLogo.half_block_rows_from_pixels(@pixels, width: logo_width, pixel_height: logo_height)
+      def logo_rows(_width)
+        []
       end
 
       private
 
-      def visible?(width)
-        !@message.empty? || image_visible?(width)
-      end
-
-      def image_visible?(width)
-        !logo_rows(width).empty?
-      end
-
-      def centered_image_rows(width)
-        logo_width, = logo_dimensions(width)
-        padding = [[(width - logo_width) / 2, 0].max, width - 1].min
-        logo_rows(width).map { |row| (" " * padding) + row }
-      end
+      def visible_lines(content)
+        lines = content.lines(chomp: true)
+        return lines if lines.length <= max_banner_rows
+        return [lines.last] if max_banner_rows == 1
 
-      def logo_dimensions(width)
-        logo_width = [LOGO_WIDTH, [width - 2, 1].max].min
-        logo_height = [LOGO_PIXEL_HEIGHT, max_logo_height * 2].min
-        [logo_width, logo_height]
+        lines.first(max_banner_rows - 1) + [lines.last]
       end
 
-      def max_logo_height
-        message_rows = @message.empty? ? 0 : 1
-        blank_after_banner = 1
+      def max_banner_rows
         transcript_row = 1
-        reserved_rows = message_rows + blank_after_banner + @minimum_composer_rows + transcript_row
+        blank_after_banner = 1
+        reserved_rows = blank_after_banner + @minimum_composer_rows + transcript_row
         [@screen_height.call - reserved_rows, 0].max
       end
 
-      def align_plain_row(text, width)
-        plain_length = ANSI.strip(text).length
-        padding = [width - plain_length, 0].max / 2
-        (" " * padding) + text.to_s
-      end
     end
   end
 end

data/lib/kward/prompt_interface/composer_controller.rb

@@ -26,14 +26,6 @@ module Kward
         @composer.attachments
       end
 
-      def composer_kill_buffer
-        @composer.kill_buffer
-      end
-
-      def composer_kill_buffer=(value)
-        @composer.kill_buffer = value.to_s
-      end
-
       def insert_key(key)
         return unless key.is_a?(String) && key.length == 1 && key.match?(/[[:print:]]/)
 
@@ -46,8 +38,8 @@ module Kward
         reset_slash_selection
         reset_history_navigation
         @slash_overlay_dismissed_input = nil
-              @composer.insert_string(string)
-            end
+        @composer.insert_string(string)
+      end
 
       def insert_paste(string)
         parsed = parse_attachments(string)
@@ -70,11 +62,11 @@ module Kward
       end
 
       def add_attachment(attachment)
-              @composer.add_attachment(attachment)
-            end
+        @composer.add_attachment(attachment)
+      end
 
       def delete_before_cursor
-              if @composer.cursor.zero?
+        if @composer.cursor.zero?
           remove_last_attachment
           return
         end
@@ -82,48 +74,48 @@ module Kward
         reset_slash_selection
         reset_history_navigation
         @composer.delete_before_cursor
-            end
+      end
 
       def remove_last_attachment
-              return unless @composer.remove_last_attachment
+        return unless @composer.remove_last_attachment
 
         reset_slash_selection
         reset_history_navigation
         @slash_overlay_dismissed_input = nil
-            end
+      end
 
       def delete_at_cursor
-              return unless @composer.cursor < @composer.input.length
+        return unless @composer.cursor < @composer.input.length
 
         reset_slash_selection
         reset_history_navigation
         @slash_overlay_dismissed_input = nil
         @composer.delete_at_cursor
-            end
+      end
 
       def move_cursor_left
-              @composer.move_cursor_left
-            end
+        @composer.move_cursor_left
+      end
 
       def move_cursor_right
-              @composer.move_cursor_right
-            end
+        @composer.move_cursor_right
+      end
 
       def move_to_start_of_line
-              @composer.move_to_start_of_line
-            end
+        @composer.move_to_start_of_line
+      end
 
       def move_to_end_of_line
-              @composer.move_to_end_of_line
-            end
+        @composer.move_to_end_of_line
+      end
 
       def move_to_previous_word
-              @composer.move_to_previous_word
-            end
+        @composer.move_to_previous_word
+      end
 
       def move_to_next_word
-              @composer.move_to_next_word
-            end
+        @composer.move_to_next_word
+      end
 
       def delete_at_cursor_or_exit
         composer_input.empty? ? exit_input : delete_at_cursor
@@ -132,65 +124,46 @@ module Kward
       def delete_word_before_cursor
         reset_slash_selection
         reset_history_navigation
-              @composer.delete_word_before_cursor
-            end
+        @composer.delete_word_before_cursor
+      end
 
       def delete_word_after_cursor
         reset_slash_selection
         reset_history_navigation
-              @composer.delete_word_after_cursor
-            end
+        @composer.delete_word_after_cursor
+      end
 
       def kill_line_before_cursor
         reset_slash_selection
         reset_history_navigation
-              @composer.kill_line_before_cursor
-            end
+        @composer.kill_line_before_cursor
+      end
 
       def kill_line_after_cursor
         reset_slash_selection
         reset_history_navigation
-              @composer.kill_line_after_cursor
-            end
-
-      def kill_range(start_index, end_index)
-              return unless @composer.kill_range(start_index, end_index)
-
-        reset_slash_selection
-        reset_history_navigation
-            end
-
-      def yank_kill_buffer
-              @composer.yank_kill_buffer
-            end
-
-      def previous_word_boundary(index)
-              @composer.previous_word_boundary(index)
+        @composer.kill_line_after_cursor
       end
 
-      def next_word_boundary(index)
-              @composer.next_word_boundary(index)
-      end
-
-      def word_separator?(char)
-        @composer.word_separator?(char)
+      def yank_kill_buffer
+        @composer.yank_kill_buffer
       end
 
       def add_history(value)
-              @composer.add_history(value)
-            end
+        @composer.add_history(value)
+      end
 
       def recall_previous_history
-              @composer.recall_previous_history
-            end
+        @composer.recall_previous_history
+      end
 
       def recall_next_history
-              @composer.recall_next_history
-            end
+        @composer.recall_next_history
+      end
 
       def replace_input(value)
         @composer.replace_input(value)
-            end
+      end
 
       def prefill_input(value)
         @mutex.synchronize do
@@ -199,19 +172,36 @@ module Kward
       end
 
       def reset_history_navigation
-              @composer.reset_history_navigation
-            end
-
+        @composer.reset_history_navigation
+      end
+
+      def prepare_modal_input_locked(label, clear_attachments: false)
+        @prompt_label = label.to_s
+        self.composer_input = ""
+        self.composer_cursor = 0
+        @composer.clear_attachments if clear_attachments
+        @pending_keys.clear
+        @asking = true
+        @busy = false
+        @queued_count = 0
+        reset_history_navigation
+      end
 
       def submit_input
         value = submitted_input
         add_history(composer_input)
+        clear_finished_input_locked(reset_history: true)
+        @output_io.flush
+        value
+      end
+
+      def clear_finished_input_locked(reset_history: false)
         if @busy
           clear_prompt_for_output_locked
           self.composer_input = ""
           self.composer_cursor = 0
           @composer.clear_attachments
-          reset_history_navigation
+          reset_history_navigation if reset_history
           @asking = true
           render_prompt_after_output_locked
         else
@@ -223,8 +213,6 @@ module Kward
           @rendered_rows = 0
           @cursor_rendered_row = 0
         end
-        @output_io.flush
-        value
       end
 
       def submitted_input
@@ -237,22 +225,7 @@ module Kward
       end
 
       def exit_input
-        if @busy
-          clear_prompt_for_output_locked
-          self.composer_input = ""
-          self.composer_cursor = 0
-          @composer.clear_attachments
-          @asking = true
-          render_prompt_after_output_locked
-        else
-          clear_prompt_locked
-          self.composer_input = ""
-          self.composer_cursor = 0
-          @composer.clear_attachments
-          @asking = false
-          @rendered_rows = 0
-          @cursor_rendered_row = 0
-        end
+        clear_finished_input_locked
         @output_io.flush
         EXIT_INPUT
       end

data/lib/kward/prompt_interface/composer_renderer.rb

@@ -85,7 +85,7 @@ module Kward
       end
 
       def composer_title
-        label = @prompt_label.delete_suffix(">")
+        label = composer_title_label
         if @busy && @queued_count.positive?
           status_composer_text(busy_title("#{label} · #{@queued_count} queued"))
         elsif @busy && @steered_count.to_i.positive?
@@ -97,6 +97,12 @@ module Kward
         end
       end
 
+      def composer_title_label
+        return "Search" if @select_state && select_search_active?
+
+        @prompt_label.delete_suffix(">")
+      end
+
       def busy_title(text)
         @busy_help ? "#{text} · #{BUSY_HELP_TEXT}" : text
       end

data/lib/kward/prompt_interface/key_handler.rb

@@ -137,8 +137,17 @@ module Kward
       end
 
       def handle_bracketed_paste_key(key)
+        paste = read_bracketed_paste(key)
+        return false unless paste
+
+        insert_paste(normalize_paste(paste[:content]))
+        queue_pending_keys(paste[:remaining]) if paste[:remaining] && !paste[:remaining].empty?
+        true
+      end
+
+      def read_bracketed_paste(key)
         text = key.to_s
-        return false unless text.start_with?(BRACKETED_PASTE_START)
+        return nil unless text.start_with?(BRACKETED_PASTE_START)
 
         pasted = text[BRACKETED_PASTE_START.length..] || ""
         until pasted.include?(BRACKETED_PASTE_END)
@@ -149,9 +158,7 @@ module Kward
         end
 
         content, remaining = pasted.split(BRACKETED_PASTE_END, 2)
-        insert_paste(normalize_paste(content || ""))
-        queue_pending_keys(remaining) if remaining && !remaining.empty?
-        true
+        { content: content || "", remaining: remaining }
       end
 
       def normalize_paste(content)
@@ -159,13 +166,12 @@ module Kward
       end
 
       def handle_csi_u_key(key)
-        match = key.to_s.match(/\A\e\[(\d+)(?:;([\d:]+))?u/)
-        return false unless match
+        sequence = parse_csi_u_key(key)
+        return false unless sequence
 
-        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
+        code = sequence[:code]
+        modifier = sequence[:modifier]
+        queue_pending_keys(sequence[:remaining]) if sequence[:remaining] && !sequence[:remaining].empty?
 
         case code
         when 13
@@ -182,6 +188,21 @@ module Kward
         end
       end
 
+      def parse_csi_u_key(key)
+        match = key.to_s.match(/\A\e\[(\d+)(?:;([\d:]+))?u/)
+        return nil unless match
+
+        modifiers = match[2].to_s
+        modifier = (modifiers.empty? ? "1" : modifiers).split(":", 2).first.to_i
+        {
+          sequence: match[0],
+          code: match[1].to_i,
+          modifiers: modifiers,
+          modifier: modifier,
+          remaining: key.to_s[match[0].length..]
+        }
+      end
+
       def handle_modified_csi_u_key(code, modifier)
         return false unless ctrl_modifier?(modifier) || alt_modifier?(modifier)
 

data/lib/kward/prompt_interface/layout.rb

@@ -6,8 +6,8 @@ module Kward
     module Layout
       private
 
-      def banner_rows(width)
-        @banner.rows(width)
+      def banner_rows(width, message: nil)
+        @banner.rows(width, message: message)
       end
 
       def banner_logo_rows