kward 0.67.1 → 0.69.0

data/lib/kward/cli_transcript_formatter.rb

@@ -1,8 +1,11 @@
 require "base64"
 require_relative "image_attachments"
 require_relative "message_access"
+require_relative "message_text"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Formats conversation messages for terminal transcript display.
   module CLITranscriptFormatter
     module_function
 
@@ -11,13 +14,20 @@ module Kward
       return direct.to_s unless direct.to_s.empty?
 
       content = MessageAccess.content(message)
-      return "" unless content.is_a?(Array)
+      if content.is_a?(Array)
+        text = content.filter_map do |part|
+          type = MessageAccess.value(part, :type)
+          next unless ["thinking", "reasoning"].include?(type)
+
+          MessageAccess.value(part, :thinking) || MessageAccess.value(part, :reasoning) || MessageAccess.value(part, :text)
+        end.join("\n")
+        return text unless text.empty?
+      end
 
-      content.filter_map do |part|
-        type = MessageAccess.value(part, :type)
-        next unless ["thinking", "reasoning"].include?(type)
+      response_items(message).filter_map do |item|
+        next unless MessageAccess.value(item, :type) == "reasoning"
 
-        MessageAccess.value(part, :thinking) || MessageAccess.value(part, :reasoning) || MessageAccess.value(part, :text)
+        response_item_text(MessageAccess.value(item, :summary)).empty? ? response_item_text(MessageAccess.value(item, :content)) : response_item_text(MessageAccess.value(item, :summary))
       end.join("\n")
     end
 
@@ -30,6 +40,18 @@ module Kward
       end
     end
 
+    def assistant_content_text(message)
+      text = content_text(MessageAccess.content(message))
+      return text unless text.empty?
+
+      response_items(message).filter_map do |item|
+        next unless MessageAccess.value(item, :type) == "message"
+        next if MessageAccess.value(item, :phase).to_s == "commentary"
+
+        response_item_text(MessageAccess.value(item, :content))
+      end.join
+    end
+
     def display_text(message)
       display_content = MessageAccess.display_content(message)
       return display_content.to_s unless display_content.nil?
@@ -79,13 +101,7 @@ module Kward
     end
 
     def full_text(message)
-      content = MessageAccess.content(message)
-      text = if content.is_a?(Array)
-               content.filter_map { |part| MessageAccess.value(part, :text) }.join("\n")
-             else
-               content.to_s
-             end
-      text.strip
+      MessageText.full_text(message)
     end
 
     def content_part_text(part)
@@ -99,6 +115,18 @@ module Kward
       end
     end
 
+    def response_items(message)
+      MessageAccess.response_items(message)
+    end
+
+    def response_item_text(parts)
+      Array(parts).filter_map do |part|
+        next unless part.is_a?(Hash)
+
+        MessageAccess.value(part, :text) || MessageAccess.value(part, :refusal)
+      end.join
+    end
+
     def image_part_reference(part)
       data = MessageAccess.value(part, :data)
       path = MessageAccess.value(part, :path)

data/lib/kward/clipboard.rb

@@ -2,6 +2,7 @@ require "base64"
 require "open3"
 require "rbconfig"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Best-effort local clipboard writer used by explicit user copy commands.
   class Clipboard

data/lib/kward/compaction/file_operation_tracker.rb

@@ -1,8 +1,11 @@
 require_relative "../message_access"
 require_relative "../tools/tool_call"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Conversation compaction settings, planning, and summary generation.
   module Compaction
+    # Tracks file operations while preparing compaction summaries.
     class FileOperationTracker
       def call(messages, previous_details: {})
         read_files = Array(path_values(previous_details, "read_files", :read_files))

data/lib/kward/compactor.rb

@@ -2,15 +2,23 @@ require "json"
 require_relative "model/chat_invocation"
 require_relative "compaction/file_operation_tracker"
 require_relative "config_files"
+require_relative "message_access"
 require_relative "prompts"
 require_relative "tools/tool_call"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Conversation compaction settings, planning, and summary generation.
   module Compaction
+    # Compaction support object used by conversation summarization.
     class Error < StandardError; end
+    # Compaction support object used by conversation summarization.
     class NothingToCompact < Error; end
+    # Compaction support object used by conversation summarization.
     class AlreadyCompacted < Error; end
+    # Compaction support object used by conversation summarization.
     class Cancelled < Error; end
+    # Compaction support object used by conversation summarization.
     class SummarizationFailed < Error; end
 
     PreparationResult = Struct.new(
@@ -28,6 +36,7 @@ module Kward
 
     Cut = Struct.new(:first_kept_index, :messages_to_summarize, :turn_prefix_messages, :split_turn, :preserved_messages, :preserved_start_index, keyword_init: true)
 
+    # Interactive settings menu actions mixed into the CLI frontend.
     class Settings
       DEFAULT_ENABLED = true
       DEFAULT_RESERVE_TOKENS = 16_384
@@ -35,6 +44,7 @@ module Kward
 
       attr_reader :enabled, :reserve_tokens, :keep_recent_tokens, :context_window
 
+      # Creates an object for conversation compaction.
       def initialize(enabled: DEFAULT_ENABLED, reserve_tokens: DEFAULT_RESERVE_TOKENS, keep_recent_tokens: DEFAULT_KEEP_RECENT_TOKENS, context_window: nil)
         @enabled = enabled != false
         @reserve_tokens = positive_integer(reserve_tokens, DEFAULT_RESERVE_TOKENS)
@@ -64,6 +74,7 @@ module Kward
       end
     end
 
+    # Compaction support object used by conversation summarization.
     class TokenEstimator
       def estimate_tokens(text)
         (text.to_s.length / 4.0).ceil
@@ -169,9 +180,11 @@ module Kward
       end
     end
 
+    # Compaction support object used by conversation summarization.
     class ConversationSerializer
       TOOL_RESULT_LIMIT = 2_000
 
+      # Creates an object for conversation compaction.
       def initialize(tool_result_summarizer: nil)
         @tool_result_summarizer = tool_result_summarizer
       end
@@ -288,28 +301,27 @@ module Kward
       end
 
       def message_role(message)
-        message["role"] || message[:role]
+        MessageAccess.role(message)
       end
 
       def message_content(message)
-        message["content"] || message[:content]
+        MessageAccess.content(message)
       end
 
       def message_summary(message)
-        message["summary"] || message[:summary] || message_content(message)
+        MessageAccess.summary(message) || message_content(message)
       end
 
       def message_name(message)
-        message["name"] || message[:name]
+        MessageAccess.tool_name(message)
       end
 
       def message_tool_call_id(message)
-        message["tool_call_id"] || message[:tool_call_id]
+        MessageAccess.tool_call_id(message)
       end
 
       def message_tool_calls(message)
-        value = message["tool_calls"] || message[:tool_calls]
-        value.is_a?(Array) ? value : []
+        MessageAccess.tool_calls(message)
       end
 
       def tool_call_id(tool_call)
@@ -350,9 +362,11 @@ module Kward
       end
     end
 
+    # Compaction support object used by conversation summarization.
     class CutPointFinder
       VALID_CUT_ROLES = ["user", "assistant", "bash", "custom", "branchSummary"].freeze
 
+      # Creates an object for conversation compaction.
       def initialize(estimator: TokenEstimator.new)
         @estimator = estimator
       end
@@ -431,7 +445,9 @@ module Kward
       end
     end
 
+    # Compaction support object used by conversation summarization.
     class Preparation
+      # Creates an object for conversation compaction.
       def initialize(conversation:, settings: Settings.new, estimator: TokenEstimator.new, cut_point_finder: CutPointFinder.new(estimator: estimator), file_operation_tracker: FileOperationTracker.new)
         @conversation = conversation
         @settings = settings
@@ -466,7 +482,7 @@ module Kward
           kept_messages: kept_messages,
           turn_prefix_messages: cut.turn_prefix_messages,
           split_turn: cut.split_turn,
-          tokens_before: @estimator.context_tokens(@conversation.messages),
+          tokens_before: @estimator.context_tokens(@conversation.context_messages),
           previous_summary: previous_entry ? compaction_summary(previous_entry) : nil,
           file_ops: file_ops,
           settings: @settings
@@ -521,6 +537,7 @@ module Kward
       end
     end
 
+    # Compaction support object used by conversation summarization.
     class PromptBuilder
       SYSTEM_PROMPT = <<~PROMPT.strip.freeze
         You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.
@@ -673,6 +690,7 @@ module Kward
         Be concise. Focus only on what is needed to understand and continue from the kept suffix. Preserve exact file paths, commands, class names, module names, method names, constants, spec names, migration names, and error messages.
       PROMPT
 
+      # Creates an object for conversation compaction.
       def initialize(serializer: ConversationSerializer.new)
         @serializer = serializer
       end
@@ -728,7 +746,9 @@ module Kward
       end
     end
 
+    # Compaction support object used by conversation summarization.
     class Summarizer
+      # Creates an object for conversation compaction.
       def initialize(client:, prompt_builder: PromptBuilder.new)
         @client = client
         @prompt_builder = prompt_builder
@@ -785,6 +805,7 @@ module Kward
     end
   end
 
+  # Compaction support object used by conversation summarization.
   class Compactor
     Result = Struct.new(:summary, :old_message_count, :new_message_count, :first_kept_entry_id, :tokens_before, :details, keyword_init: true)
     NothingToCompact = Compaction::NothingToCompact
@@ -795,6 +816,7 @@ module Kward
     AUTO_COMPACTION_GUARD_RATIO = 0.10
     AUTO_COMPACTION_EXTRA_GUARD_CAP = 12_000
 
+    # Creates an object for conversation compaction.
     def initialize(conversation:, client:, tool_result_summarizer: nil, settings: nil, summarizer: nil)
       @conversation = conversation
       @client = client
@@ -844,7 +866,7 @@ module Kward
       context_window ||= @settings.context_window
       return nil unless context_window
 
-      context_tokens ||= Compaction::TokenEstimator.new.context_tokens(@conversation.messages)
+      context_tokens ||= Compaction::TokenEstimator.new.context_tokens(@conversation.context_messages)
       reserve_tokens = auto_compaction_reserve_tokens(context_window: context_window.to_i)
       return nil unless context_tokens.to_i > context_window.to_i - reserve_tokens
 

data/lib/kward/config_files.rb

@@ -5,9 +5,19 @@ require_relative "private_file"
 require_relative "prompts/templates"
 require_relative "skills/registry"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Resolves Kward configuration, cache, memory, prompt, skill, and plugin
   # paths, and reads/writes the JSON config file used by the CLI and RPC server.
+  #
+  # This module is the configuration boundary, not a runtime settings cache.
+  # Most methods read the filesystem each time so CLI commands and RPC reloads can
+  # observe edits made outside the process. Callers that need caching should own
+  # invalidation explicitly, as `Client#reload_config` does for provider state.
+  #
+  # Keep path decisions here. Higher-level code should ask `ConfigFiles` for
+  # config, prompt, skill, plugin, cache, memory, and session locations instead of
+  # reconstructing `~/.kward` paths independently.
   module ConfigFiles
     MAX_SKILL_FILE_BYTES = 100_000
     MAX_PROMPT_FILE_BYTES = 32 * 1024
@@ -67,12 +77,14 @@ module Kward
         "sessions" => {
           "auto_resume" => false
         },
+        "enforce_workspace_agents_file" => false,
         "tools" => {
           "workspace_guardrails" => true
         }
       }
     end
 
+    # Performs ensure default config for configuration file and path handling.
     def ensure_default_config!(path = config_path)
       path = File.expand_path(path)
       return false if File.exist?(path)
@@ -105,7 +117,9 @@ module Kward
     # Reads the JSON config file.
     #
     # Missing files are treated as an empty config. Invalid JSON raises a
-    # user-facing error that includes the file path.
+    # user-facing error that includes the file path. This method does not merge
+    # defaults; callers should apply feature-specific defaults at the point where
+    # behavior is decided.
     #
     # @param path [String] config file path
     # @return [Hash] parsed config object
@@ -126,6 +140,7 @@ module Kward
       PrivateFile.write_json(path, config)
     end
 
+    # Merges top-level config values and writes the updated config privately.
     def update_config(values, path = config_path)
       raise "Config values must be an object" unless values.is_a?(Hash)
 
@@ -135,6 +150,7 @@ module Kward
       config
     end
 
+    # Removes a top-level config key when it exists.
     def delete_config_key(key, path = config_path)
       config = read_config(path)
       existed = config.key?(key.to_s)
@@ -143,6 +159,7 @@ module Kward
       existed
     end
 
+    # Returns the first present non-empty string value among several config keys.
     def config_value(config, *keys)
       keys.each do |key|
         text = presence(config[key])
@@ -166,26 +183,43 @@ module Kward
       settings
     end
 
+    # Returns whether the composer should show busy-state keyboard help.
     def composer_busy_help?(config = read_config)
       composer = config["composer"].is_a?(Hash) ? config["composer"] : {}
       composer["busy_help"] != false
     end
 
+    # Returns whether the terminal startup banner should be displayed.
     def banner_enabled?(config = read_config)
       banner = config["banner"].is_a?(Hash) ? config["banner"] : {}
       banner["enabled"] != false
     end
 
+    # Returns whether file tools must stay inside the active workspace root.
     def workspace_guardrails_enabled?(config = read_config)
       tools = config["tools"].is_a?(Hash) ? config["tools"] : {}
       tools["workspace_guardrails"] != false
     end
 
+    # Returns whether new frontends should resume the last active session automatically.
     def session_auto_resume_enabled?(config = read_config)
       sessions = config["sessions"].is_a?(Hash) ? config["sessions"] : {}
       sessions["auto_resume"] == true
     end
 
+    # Returns whether workspace AGENTS.md contents should be injected directly
+    # instead of a compact read-when-relevant instruction.
+    def enforce_workspace_agents_file?(config = read_config)
+      config["enforce_workspace_agents_file"] == true
+    end
+
+    # Returns the nested web-search config object, or an empty config when absent.
+    def web_search_config(config = read_config)
+      value = config["web_search"]
+      value.is_a?(Hash) ? value : {}
+    end
+
+    # Validates and persists terminal overlay settings.
     def update_overlay_settings(values)
       raise "Overlay settings must be an object" unless values.is_a?(Hash)
 
@@ -209,17 +243,34 @@ module Kward
       overlay_settings(config)
     end
 
-    # Reads global agent instructions from the config directory.
+    # Reads global principle instructions from the config directory.
+    #
+    # `PRINCIPLES.md` is preferred. `AGENTS.md` remains a backwards-compatible
+    # alias for existing installations.
     #
     # @return [String, nil] prompt text, or nil when absent/too large
     def agents_prompt
-      path = File.join(config_dir, "AGENTS.md")
-      read_prompt_file(path, "Kward prompt file")
+      path = config_principles_path
+      return read_prompt_file(path, "Kward principles file") if File.exist?(path)
+
+      read_prompt_file(config_agents_path, "Kward AGENTS.md alias")
+    end
+
+    def config_principles_path
+      File.join(config_dir, "PRINCIPLES.md")
+    end
+
+    def config_agents_path
+      File.join(config_dir, "AGENTS.md")
     end
 
     # Builds persona prompt text from default, workspace, model, reasoning,
     # time-of-day, weekday, and suffix config entries.
     #
+    # Persona resolution is intentionally data-driven so users can edit config
+    # without plugin code. Keep new persona selectors additive and deterministic;
+    # prompt construction depends on stable ordering.
+    #
     # @param workspace_root [String] active workspace root
     # @param model [String, nil] active model name
     # @param reasoning_effort [String, nil] active reasoning effort
@@ -235,6 +286,7 @@ module Kward
       text
     end
 
+    # Returns the label of the persona selected by default/workspace/model rules.
     def active_persona_label(workspace_root:, model: nil, config: read_config)
       personas = config["personas"]
       return nil unless personas.is_a?(Hash)
@@ -267,22 +319,30 @@ module Kward
 
       characters = crew_characters(personas)
       entries = []
-
-      add_persona_entry(entries, "default", resolved_persona_text(personas["default"], characters: characters))
+      active_persona = { layer: "default", value: personas["default"], name: nil }
 
       workspaces = personas["workspaces"]
       if workspaces.is_a?(Hash)
         root = canonical_workspace_root(workspace_root)
         workspaces.each do |path, key|
           if canonical_workspace_root(path) == root
-            add_persona_entry(entries, "workspace", resolved_persona_text(key, characters: characters), name: path)
+            active_persona = { layer: "workspace", value: key, name: path }
             break
           end
         end
       end
 
       models = personas["models"]
-      add_persona_entry(entries, "model", resolved_persona_text(models[model.to_s], characters: characters), name: model.to_s) if models.is_a?(Hash) && !model.to_s.empty?
+      if models.is_a?(Hash) && !model.to_s.empty? && models.key?(model.to_s)
+        active_persona = { layer: "model", value: models[model.to_s], name: model.to_s }
+      end
+
+      add_persona_entry(
+        entries,
+        active_persona.fetch(:layer),
+        resolved_persona_text(active_persona.fetch(:value), characters: characters),
+        name: active_persona[:name]
+      )
 
       modifiers = personas["persona_modifiers"]
       if modifiers.is_a?(Hash)
@@ -304,10 +364,17 @@ module Kward
 
       entries
     end
+
+    def workspace_agents_path(workspace_root)
+      File.join(canonical_workspace_root(workspace_root), "AGENTS.md")
+    end
+
+    def workspace_agents_file?(workspace_root)
+      File.exist?(workspace_agents_path(workspace_root))
+    end
+
     def workspace_agents_prompt(workspace_root)
-      root = canonical_workspace_root(workspace_root)
-      path = File.join(root, "AGENTS.md")
-      read_prompt_file(path, "workspace AGENTS.md")
+      read_prompt_file(workspace_agents_path(workspace_root), "workspace AGENTS.md")
     end
 
     def read_prompt_file(path, label)
@@ -325,17 +392,6 @@ module Kward
       nil
     end
 
-    def workspace_config(workspace_root, config = read_config)
-      workspaces = config["workspaces"]
-      return nil unless workspaces.is_a?(Hash)
-
-      root = canonical_workspace_root(workspace_root)
-      workspaces.each do |path, entry|
-        return entry if canonical_workspace_root(path) == root
-      end
-      nil
-    end
-
     def canonical_workspace_root(path)
       expanded = File.expand_path(path.to_s.empty? ? Dir.pwd : path.to_s)
       File.directory?(expanded) ? File.realpath(expanded) : expanded
@@ -460,7 +516,6 @@ module Kward
     # @return [Array<String>] sorted plugin file paths
     def plugin_paths
       plugins_root = plugin_dir
-      warn_legacy_plugin_dir(plugins_root)
       return [] unless Dir.exist?(plugins_root)
 
       Dir.glob(File.join(plugins_root, "*.rb")).sort
@@ -469,17 +524,6 @@ module Kward
       []
     end
 
-    def warn_legacy_plugin_dir(plugins_root)
-      config_path = ENV["KWARD_CONFIG_PATH"]
-      return if config_path.to_s.empty?
-
-      legacy_root = File.expand_path(File.join(File.dirname(config_path), "plugins"))
-      return if legacy_root == File.expand_path(plugins_root)
-      return unless Dir.exist?(legacy_root)
-
-      warn "Warning: ignoring Kward plugins in #{legacy_root}; plugins are only loaded from #{File.expand_path(plugins_root)}"
-    end
-
     # Lists prompt templates exposed as slash commands.
     #
     # @param reserved_commands [Array<String>] command names unavailable to templates