kward 0.69.1 → 0.71.0

data/doc/workspace-tools.md

@@ -0,0 +1,105 @@
+# Workspace tools
+
+Workspace tools let Kward inspect and change the local project. They are the tools behind prompts such as:
+
+```text
+Find where configuration is loaded.
+Add a focused test for this behavior.
+Run the related test file.
+```
+
+Kward normally chooses these tools itself. You do not need to know their exact names to use them, but understanding the boundaries helps explain why Kward sometimes reads before editing or asks before running broad checks.
+
+## Guardrails
+
+Workspace tools use the active workspace as their boundary. File paths are workspace-relative by default, and file tools are guarded so Kward does not edit arbitrary unread files.
+
+Important behavior:
+
+- Existing files must be read in the current conversation before `write_file` or `edit_file` can change them.
+- Reads are bounded to avoid pulling very large files into context by accident.
+- Edits use exact text replacement, so accidental partial or fuzzy changes fail instead of guessing.
+- Shell commands run as your operating-system user from the workspace. They are powerful and should be treated like commands you run yourself.
+
+## Reading the workspace
+
+### `list_directory`
+
+Lists entries in a workspace-relative directory. Kward uses it to discover project structure before reading specific files.
+
+Arguments:
+
+- `path`: workspace-relative directory.
+
+### `read_file`
+
+Reads a workspace text file. Output is capped, and Kward can continue with line offsets when it needs more detail.
+
+Arguments:
+
+- `path`: workspace-relative file path.
+- `offset`: optional 1-indexed start line.
+- `limit`: optional maximum number of lines.
+
+A successful read marks the resolved file path as read for the conversation, allowing later edits to that file.
+
+### `summarize_file_structure`
+
+Returns a compact outline of classes, modules, methods, and functions in a source file. Kward uses it when a file may be too large to read fully at first.
+
+Arguments:
+
+- `path`: workspace-relative source file path.
+
+This tool saves tokens by letting Kward identify relevant entry points before requesting exact line ranges with `read_file`.
+
+## Changing files
+
+### `write_file`
+
+Writes complete file content. Existing files must be read first. New files can be created when the path is inside the workspace.
+
+Arguments:
+
+- `path`: workspace-relative file path.
+- `content`: complete file content.
+
+Use full writes when replacing generated content or creating a new file. For small edits to existing files, Kward should usually prefer `edit_file`.
+
+### `edit_file`
+
+Applies one or more exact replacements to a file that has already been read.
+
+Arguments:
+
+- `path`: workspace-relative file path.
+- `edits`: array of replacements:
+  - `old_text`: unique exact text to replace.
+  - `new_text`: replacement text.
+
+Each `old_text` must match exactly once, and replacements must not overlap. This keeps edits deterministic and avoids broad fuzzy rewriting.
+
+## Running commands
+
+### `run_shell_command`
+
+Runs a shell command from the workspace root.
+
+Arguments:
+
+- `command`: command to run.
+- `timeout_seconds`: optional timeout, default 30 seconds.
+
+Kward uses shell commands for tests, linters, build checks, and simple repository inspection. Command output is bounded and may be compacted before it is sent back into model context, while the original output remains available in the session record.
+
+## Token behavior
+
+Workspace tools are intentionally incremental:
+
+1. list directories to find likely files,
+2. summarize large source files before reading everything,
+3. read focused line ranges,
+4. make exact edits,
+5. run focused verification commands.
+
+This keeps the model's context window focused on relevant evidence instead of flooding it with entire repositories or long command output.

data/lib/kward/cli/commands.rb

@@ -53,6 +53,7 @@ module Kward
             #{command.call("kward init")}                         Install starter prompts and PRINCIPLES.md
             #{command.call("kward doctor")}                       Check local Kward setup
             #{command.call("kward sysprompt")}                    Inspect the effective system prompt
+            #{command.call("kward openrouter refresh")}           Refresh cached OpenRouter models
             #{command.call("kward pan")}                          Start Pan mode web UI
             #{command.call("kward rpc")}                          Start the experimental JSON-RPC backend
 
@@ -65,6 +66,7 @@ module Kward
             #{command.call("doctor")}                             Check local Kward setup
             #{command.call("sysprompt")} [--raw]                  Inspect the effective system prompt
             #{command.call("stats tokens")} [range] [options]      Export local token telemetry as CSV
+            #{command.call("openrouter refresh|list")}             Refresh or list cached OpenRouter models
             #{command.call("pan")}                                Start Pan mode web UI
             #{command.call("rpc")}                                Run the JSON-RPC backend for UI clients
 
@@ -78,6 +80,7 @@ module Kward
             #{command.call("kward")} #{option.call('"Review this diff"')}
             #{command.call("git diff | kward")} #{option.call('"Review this diff"')}
             #{command.call("kward login openrouter")}
+            #{command.call("kward openrouter refresh")}
             #{command.call("kward stats tokens today --bucket hour")}
 
           Command names take precedence. Anything else is sent as a one-shot prompt.
@@ -126,6 +129,11 @@ module Kward
             description: "Export local token telemetry as CSV.",
             examples: ["kward stats tokens today", "kward stats tokens today --bucket hour", "kward stats tokens week --output tokens.csv"]
           },
+          "openrouter" => {
+            usage: "kward openrouter refresh|list",
+            description: "Refresh or list cached text-capable OpenRouter models available to your API key.",
+            examples: ["kward openrouter refresh", "kward openrouter --refresh", "kward openrouter list"]
+          },
           "pan" => {
             usage: "kward pan",
             description: "Start Pan mode, a minimal LAN web UI with a prompt textarea and transcript.",

data/lib/kward/cli/openrouter_commands.rb

@@ -0,0 +1,55 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Command-line frontend that coordinates terminal interaction, sessions, tools, and model turns.
+  class CLI
+    # OpenRouter cache management commands for the terminal CLI flow.
+    module OpenRouterCommands
+      private
+
+      def handle_openrouter_command(arguments)
+        case arguments
+        when ["refresh"], ["--refresh"]
+          refresh_openrouter_models
+        when ["list"], ["--list"]
+          list_openrouter_models
+        else
+          raise ArgumentError, command_usage("openrouter")
+        end
+      end
+
+      def refresh_openrouter_models
+        cache = OpenRouterModelCache.new(api_key: configured_openrouter_api_key, path: openrouter_models_cache_path)
+        data = cache.refresh
+        count = Array(data["models"]).length
+        @client.reload_config if @client.respond_to?(:reload_config)
+        @prompt.say("Refreshed #{count} OpenRouter text model#{count == 1 ? "" : "s"} for this key.")
+        @prompt.say("Cached at: #{cache.path}")
+      rescue StandardError => e
+        warn e.message
+        exit 1
+      end
+
+      def list_openrouter_models
+        cache = OpenRouterModelCache.new(api_key: configured_openrouter_api_key, path: openrouter_models_cache_path)
+        data = cache.read
+        unless data
+          @prompt.say("No OpenRouter model cache found. Run `kward openrouter refresh` first.")
+          return
+        end
+
+        models = Array(data["models"])
+        lines = ["OpenRouter models cached at #{data["refreshed_at"]}:"]
+        lines.concat(models.map { |model| model["id"].to_s }.reject(&:empty?))
+        @prompt.say(lines.join("\n"))
+      end
+
+      def configured_openrouter_api_key
+        ENV["OPENROUTER_API_KEY"].to_s.empty? ? ConfigFiles.config_value(ConfigFiles.read_config, "openrouter_api_key").to_s : ENV["OPENROUTER_API_KEY"].to_s
+      end
+
+      def openrouter_models_cache_path
+        File.join(File.dirname(ConfigFiles.config_path), "cache", "openrouter_models.json")
+      end
+    end
+  end
+end

data/lib/kward/cli/prompt_interface.rb

@@ -1,3 +1,5 @@
+require "open3"
+
 # Namespace for the Kward CLI agent runtime.
 module Kward
   # Command-line frontend that coordinates terminal interaction, sessions, tools, and model turns.
@@ -13,7 +15,6 @@ module Kward
         prompt_interface = load_prompt_interface
         return unless prompt_interface
 
-        banner_enabled = ConfigFiles.banner_enabled?
         @prompt = prompt_interface.new(
           slash_commands: slash_command_entries,
           overlay_settings: ConfigFiles.overlay_settings,
@@ -22,10 +23,13 @@ module Kward
           busy_help: ConfigFiles.composer_busy_help?,
           attachment_badges: method(:composer_attachment_badges),
           attachment_parser: method(:composer_attachment_parser),
-          banner_pixels: banner_enabled ? Kward::PromptInterface::BANNER_LOGO_PIXELS : nil,
-          banner_message: banner_enabled ? Kward::PromptInterface::BANNER_MESSAGE : nil
+          banner_message: Kward::PromptInterface::BANNER_MESSAGE
         )
-        @prompt.start
+        if @prompt.method(:start).parameters.any? { |kind, name| [:key, :keyreq].include?(kind) && name == :render }
+          @prompt.start(render: false)
+        else
+          @prompt.start
+        end
       end
 
       def load_prompt_interface
@@ -46,9 +50,80 @@ module Kward
         @prompt.respond_to?(:start_stream_block) && @prompt.respond_to?(:write_delta)
       end
 
-      # Writes the visual banner output for the terminal CLI flow.
+      # Writes the startup info screen output for the terminal CLI flow.
       def print_visual_banner
-        @prompt.print_visual_banner if @prompt.respond_to?(:print_visual_banner)
+        return unless @prompt.respond_to?(:print_visual_banner)
+
+        @prompt.print_visual_banner(startup_info_screen)
+      end
+
+      def startup_info_screen
+        [
+          startup_status_line,
+          "",
+          startup_info_line("Workspace", startup_workspace_label),
+          startup_info_line("Branch", startup_branch_value),
+          startup_info_line("Plugins", startup_plugins_value),
+          "",
+          startup_brand_line
+        ].join("\n")
+      end
+
+      def startup_workspace_label
+        root = File.expand_path(current_workspace_root)
+        home = begin
+          Dir.home
+        rescue StandardError
+          nil
+        end
+        if home && (root == home || root.start_with?("#{home}/"))
+          relative = root.delete_prefix(home).sub(%r{\A/}, "")
+          return "~" if relative.empty?
+          return "~/#{relative}" unless relative.include?("/")
+        end
+
+        parent = File.basename(File.dirname(root))
+        name = File.basename(root)
+        parent.empty? || parent == "." ? name : "#{parent}/#{name}"
+      end
+
+      def startup_branch_value
+        git_root = startup_git_root(current_workspace_root)
+        return "not a repository" if git_root.to_s.empty?
+
+        branch = startup_git_output(%w[git branch --show-current], root: git_root)
+        branch = startup_git_output(%w[git rev-parse --short HEAD], root: git_root) if branch.empty?
+        branch.empty? ? "unknown" : branch
+      end
+
+      def startup_plugins_value
+        filenames = plugin_registry.paths.map { |path| File.basename(path) }
+        filenames.empty? ? "none" : filenames.join(", ")
+      end
+
+      def startup_status_line
+        "#{ANSI.colorize("●", :green, enabled: @color_enabled)} Kward v#{Kward::VERSION} is online."
+      end
+
+      def startup_info_line(label, value)
+        "#{ANSI.colorize(label.ljust(12), :gray, enabled: @color_enabled)}#{ANSI.colorize(value, :cyan, enabled: @color_enabled)}"
+      end
+
+      def startup_brand_line
+        ANSI.colorize(Kward::PromptInterface::BANNER_MESSAGE, :bold, enabled: @color_enabled)
+      end
+
+      def startup_git_root(root)
+        startup_git_output(%w[git rev-parse --show-toplevel], root: root)
+      end
+
+      def startup_git_output(command, root:)
+        output, status = Open3.capture2e(*command, chdir: root.to_s)
+        return "" unless status.success?
+
+        output.lines.first.to_s.strip
+      rescue StandardError
+        ""
       end
 
       def prompt_footer_renderer
@@ -103,7 +178,10 @@ module Kward
       def composer_context_window(provider = nil, model = nil)
         provider ||= current_footer_conversation.provider || (@client.respond_to?(:current_provider) ? @client.current_provider : "Codex")
         model ||= current_footer_conversation.model || (@client.respond_to?(:current_model) ? @client.current_model : ModelInfo::DEFAULT_OPENAI_MODEL)
-        ModelInfo.context_window(ModelInfo.provider_label(provider), model)
+        provider = ModelInfo.provider_label(provider)
+        return @client.context_window(provider, model) if @client.respond_to?(:context_window) && @client.method(:context_window).arity != 0
+
+        ModelInfo.context_window(provider, model)
       end
 
       def composer_context_usage(provider, model)

data/lib/kward/cli/rendering.rb

@@ -59,7 +59,7 @@ module Kward
         if prompt_interface?
           print_tool_result(tool_call, content, line_limit: INTERACTIVE_TOOL_OUTPUT_LINE_LIMIT)
         else
-          @prompt.say("\n#{colored("Tool>", *tool_label_styles(content))}\n#{summary}\n")
+          @prompt.say("\n#{colored("Tool>", *tool_label_styles(content))} #{tool_summary_display_text(summary)}\n")
         end
       end
 
@@ -71,7 +71,7 @@ module Kward
           print_block_delta(label, rendered)
           finish_stream_block
         else
-          @prompt.say("\n#{colored("#{transcript_label(label)}>", *label_styles(label))}\n#{rendered}\n")
+          @prompt.say("\n#{colored("#{transcript_label(label)}>", *label_styles(label))} #{rendered}\n")
         end
       end
 
@@ -298,8 +298,9 @@ module Kward
       def print_tool_result(tool_call, content, line_limit: nil)
         summary = tool_result_summary(tool_call, content)
         summary = limit_tool_output_lines(summary, line_limit) if line_limit
+        display_summary = tool_summary_display_text(summary)
         if prompt_interface?
-          summary = summary.end_with?("\n") ? summary : "#{summary}\n"
+          summary = display_summary.end_with?("\n") ? display_summary : "#{display_summary}\n"
           if @prompt.respond_to?(:write_stream_block)
             @prompt.write_stream_block("Tool", summary, finish: true)
           else
@@ -309,18 +310,22 @@ module Kward
           end
         else
           start_stream_block(tool_stream_label(content))
-          print summary
-          puts unless summary.end_with?("\n")
+          print display_summary
+          puts unless display_summary.end_with?("\n")
           $stdout.flush
           @stream_block = nil
         end
       end
 
+      def tool_summary_display_text(summary)
+        summary.to_s.sub("\n", "\n\n")
+      end
+
       def start_stream_block(label)
         return if @stream_block == label
 
         puts if @stream_block
-        puts "\n#{colored("#{transcript_label(label)}>", *label_styles(label))}"
+        print "\n#{colored("#{transcript_label(label)}>", *label_styles(label))} "
         @stream_block = label
       end