kward 0.67.0 → 0.68.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
 
@@ -79,13 +82,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)

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
@@ -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

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
@@ -73,6 +83,7 @@ module Kward
       }
     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 +116,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 +139,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 +149,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 +158,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 +182,37 @@ 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 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)
 
@@ -220,6 +247,10 @@ module Kward
     # 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 +266,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)
@@ -325,17 +357,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 +481,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 +489,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

data/lib/kward/conversation.rb

@@ -4,15 +4,57 @@ require_relative "message_access"
 require_relative "plugin_registry"
 require_relative "prompts"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Mutable transcript and runtime context for one agent session.
+  #
+  # `Conversation` owns message ordering, system prompt refresh, read-before-write
+  # state, memory prompt context, and persistence hooks. It intentionally stores
+  # plain hashes because provider payload builders, session JSONL files, and RPC
+  # normalizers all share the same transcript shape. Use `MessageAccess` when
+  # reading messages so symbol/string key and legacy field compatibility stays in
+  # one place.
+  #
+  # Frontends should not mutate `messages` directly after attaching a
+  # `SessionStore::Session`; use append/compact helpers so persistence callbacks
+  # run and session trees stay consistent.
   class Conversation
     DEFAULT_SYSTEM_MESSAGE = Object.new.freeze
 
-    attr_reader :messages, :read_paths, :workspace_root, :compaction_system_message, :model, :reasoning_effort, :session_memories
-    attr_accessor :on_append, :on_compact, :on_tool_execution, :memory_context, :last_memory_retrieval, :plugin_registry
-
-    def initialize(system_message: DEFAULT_SYSTEM_MESSAGE, messages: [], read_paths: [], on_append: nil, on_compact: nil, on_tool_execution: nil, workspace_root: Dir.pwd, compaction_system_message: DEFAULT_SYSTEM_MESSAGE, model: nil, reasoning_effort: nil, memory_context: nil, session_memories: [], last_memory_retrieval: nil, plugin_registry: nil)
+    # @return [Array<Hash>] ordered transcript entries sent to providers and persisted in sessions
+    attr_reader :messages
+    # @return [Set<String>] resolved paths read by file tools during the active context
+    attr_reader :read_paths
+    # @return [String] canonical workspace root used for prompts and file guardrails
+    attr_reader :workspace_root
+    # @return [Hash, nil] system prompt used when summarizing old context
+    attr_reader :compaction_system_message
+    # @return [String, nil] provider captured for session/runtime prompts
+    attr_reader :provider
+    # @return [String, nil] model id captured for session/runtime prompts
+    attr_reader :model
+    # @return [String, nil] reasoning effort captured for session/runtime prompts
+    attr_reader :reasoning_effort
+    # @return [Array<Hash>] memories scoped to this conversation session
+    attr_reader :session_memories
+    # @return [Proc, nil] persistence callback invoked after appending a message
+    attr_accessor :on_append
+    # @return [Proc, nil] persistence callback invoked after compaction replaces history
+    attr_accessor :on_compact
+    # @return [Proc, nil] callback invoked when a tool execution record should be persisted
+    attr_accessor :on_tool_execution
+    # @return [Proc, nil] callback invoked when runtime metadata should be persisted
+    attr_accessor :on_runtime_update
+    # @return [String, nil] memory prompt context injected into refreshed system messages
+    attr_accessor :memory_context
+    # @return [Hash, nil] metadata for the last memory retrieval attached to the session
+    attr_accessor :last_memory_retrieval
+    # @return [PluginRegistry, nil] registry used to collect plugin prompt context
+    attr_accessor :plugin_registry
+
+    def initialize(system_message: DEFAULT_SYSTEM_MESSAGE, messages: [], read_paths: [], on_append: nil, on_compact: nil, on_tool_execution: nil, on_runtime_update: nil, workspace_root: Dir.pwd, compaction_system_message: DEFAULT_SYSTEM_MESSAGE, provider: nil, model: nil, reasoning_effort: nil, memory_context: nil, session_memories: [], last_memory_retrieval: nil, plugin_registry: nil)
       @workspace_root = ConfigFiles.canonical_workspace_root(workspace_root)
+      @provider = provider
       @model = model
       @reasoning_effort = reasoning_effort
       @plugin_registry = plugin_registry
@@ -36,8 +78,13 @@ module Kward
       @on_append = on_append
       @on_compact = on_compact
       @on_tool_execution = on_tool_execution
+      @on_runtime_update = on_runtime_update
     end
 
+    # Appends a user message and normalizes image attachment syntax.
+    #
+    # `display_content` is transcript/UI text for cases where the model input is
+    # expanded, decorated, or contains encoded attachment content.
     def append_user(content, display_content: nil)
       content = ImageAttachments.content_from_text(content) unless content.is_a?(Array)
       message = { role: "user", content: content }
@@ -63,6 +110,12 @@ module Kward
       @on_tool_execution&.call(tool_call, content)
     end
 
+    # Rebuilds the system message from current config, memory, plugins, and
+    # workspace AGENTS.md state.
+    #
+    # Conversations created with `system_message: nil` keep system prompts
+    # disabled; this preserves tests, compaction summaries, and imported
+    # transcripts that intentionally do not include runtime instructions.
     def refresh_system_message!
       return nil unless @system_message_enabled
 
@@ -74,12 +127,17 @@ module Kward
       replacement
     end
 
-    def update_runtime_context!(model:, reasoning_effort:)
+    def update_runtime_context!(provider: nil, model:, reasoning_effort:)
+      @provider = provider unless provider.to_s.empty?
       @model = model
       @reasoning_effort = reasoning_effort
       refresh_system_message!
     end
 
+    def persist_runtime_context!
+      @on_runtime_update&.call(provider: @provider, model: @model, reasoning_effort: @reasoning_effort)
+    end
+
     def refresh_system_message_if_workspace_agents_changed!
       refresh_system_message! if @system_message_enabled && workspace_agents_mtime != @workspace_agents_mtime
     end
@@ -95,6 +153,13 @@ module Kward
       plugin_registry.prompt_context(context)
     end
 
+    # Replaces most transcript entries with a compaction summary and optional
+    # recent messages to keep.
+    #
+    # Compaction clears read-before-write state because file contents observed
+    # before the summary may no longer be represented exactly in the active
+    # context. Callers that need file mutation after compaction should read files
+    # again through the normal tools.
     def compact!(summary, compaction_summary: false, first_kept_entry_id: nil, tokens_before: nil, from_hook: false, details: {}, keep_messages: [])
       message = if compaction_summary
                   { role: "compactionSummary", summary: summary.to_s }

data/lib/kward/events.rb

@@ -1,4 +1,6 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Frontend-neutral event objects emitted during agent turns.
   module Events
     ReasoningDelta = Struct.new(:delta, keyword_init: true)
     AssistantDelta = Struct.new(:delta, keyword_init: true)

data/lib/kward/export_path.rb

@@ -1,6 +1,8 @@
 require "pathname"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Resolves safe output paths for transcript exports.
   class ExportPath
     def self.resolve(path, workspace_root:, default_path:, session_dir: nil)
       explicit = path.to_s.strip

data/lib/kward/image_attachments.rb

@@ -4,7 +4,9 @@ require "shellwords"
 require "tmpdir"
 require "uri"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Image attachment parsing, validation, encoding, and display helpers.
   module ImageAttachments
     MAX_IMAGE_BYTES = 20 * 1024 * 1024
     MIME_TYPES = {

data/lib/kward/markdown_transcript.rb

@@ -1,6 +1,8 @@
 require_relative "message_access"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Markdown renderer for conversation transcripts.
   class MarkdownTranscript
     def initialize(conversation)
       @conversation = conversation

data/lib/kward/memory/manager.rb

@@ -7,7 +7,9 @@ require_relative "../config_files"
 require_relative "../message_access"
 require_relative "../model/client"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Memory subsystem for core, soft, session, and retrieval state.
   module Memory
     # Manages Kward's opt-in structured memory store.
     #
@@ -35,6 +37,7 @@ module Kward
         )
       end
 
+      # Creates an object for memory storage and retrieval.
       def initialize(config_path: ConfigFiles.config_path, core_path: ConfigFiles.memory_core_path, soft_path: ConfigFiles.memory_soft_path, events_path: ConfigFiles.memory_events_path, now: nil)
         @config_path = config_path
         @core_path = core_path
@@ -299,6 +302,11 @@ module Kward
         @last_retrieval || { "enabled" => enabled?, "core" => [], "soft" => [], "reasons" => [], "message" => "No memory retrieval has run yet." }
       end
 
+      # Formats retrieved memories for system prompt injection.
+      #
+      # Keep this block compact and explicit: it is read by the model, shown in
+      # transcripts, and explained by `/memory why`. Do not include inactive or
+      # forgotten memories here; retrieval already decides the active set.
       def memory_block(retrieval)
         core = Array(retrieval["core"])
         soft = Array(retrieval["soft"])
@@ -330,6 +338,11 @@ module Kward
         lines.join("\n")
       end
 
+      # Infers bounded session/workspace soft memories from a conversation.
+      #
+      # This is best-effort and intentionally conservative. It may use an LLM when
+      # configured, but failures fall back to heuristic text or no-op behavior so
+      # memory summarization never blocks normal session flow.
       def summarize_conversation(conversation, client: nil)
         text = messages_for_summarization(conversation).map { |message| MessageAccess.content(message) }.compact.join("\n")
         existing_texts = Array(conversation.session_memories).map { |memory| memory["text"] }

data/lib/kward/message_access.rb

@@ -1,7 +1,20 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Compatibility reader for persisted conversation message hashes.
+  #
+  # Kward stores transcript entries as plain hashes because model payloads,
+  # JSONL sessions, plugins, and RPC normalizers all need to pass them around
+  # without framework objects. Restored sessions may contain either symbol keys,
+  # string keys, or Tauren-style camelCase aliases. `MessageAccess` centralizes
+  # those lookup rules so callers do not grow one-off compatibility branches.
   module MessageAccess
     module_function
 
+    # Reads a field from a hash-like object using symbol or string keys.
+    #
+    # @param object [#key?, nil] hash-like object to read
+    # @param key [String, Symbol] canonical field name
+    # @return [Object, nil] stored value when present
     def value(object, key)
       return nil unless object.respond_to?(:key?)
       return object[key] if object.key?(key)
@@ -10,14 +23,17 @@ module Kward
       nil
     end
 
+    # @return [String, nil] message role such as `user`, `assistant`, or `tool`
     def role(message)
       value(message, :role)
     end
 
+    # @return [Object, nil] raw message content
     def content(message)
       value(message, :content)
     end
 
+    # @return [String, nil] UI-facing content preserved separately from model input
     def display_content(message)
       value(message, :display_content) || value(message, :displayContent)
     end
@@ -31,11 +47,16 @@ module Kward
     end
 
     def tool_call_id(message)
-      value(message, :tool_call_id)
+      value(message, :tool_call_id) || value(message, :toolCallId)
     end
 
+    def tool_name(message)
+      value(message, :name) || value(message, :toolName)
+    end
+
+    # @return [Array<Hash>] assistant tool calls, or an empty array
     def tool_calls(message)
-      calls = value(message, :tool_calls)
+      calls = value(message, :tool_calls) || value(message, :toolCalls)
       calls.is_a?(Array) ? calls : []
     end
   end

data/lib/kward/message_text.rb

@@ -0,0 +1,45 @@
+require_relative "message_access"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Builds user-visible plain text from persisted conversation messages.
+  #
+  # Conversations may store one value for the model and another value for the UI.
+  # Prompt templates, for example, keep expanded instructions in `content` while
+  # preserving the submitted slash command in `display_content`. This helper keeps
+  # tree navigation, forks, copy/export features, and RPC payloads aligned on the
+  # same visible text rules.
+  module MessageText
+    module_function
+
+    # Returns the plain text a user should see or edit for a message.
+    #
+    # User messages prefer `display_content`/`displayContent` when present. Other
+    # messages, and user messages without display text, are reduced from their
+    # stored content. Array content contributes only textual parts so image and
+    # tool-call blocks do not leak implementation details into editable text.
+    #
+    # @param message [Hash] persisted conversation message
+    # @return [String] stripped visible text
+    def full_text(message)
+      display_content = MessageAccess.display_content(message)
+      return display_content.to_s.strip unless display_content.nil?
+
+      content_text(MessageAccess.content(message)).strip
+    end
+
+    # Converts message content into plain text without applying display-content
+    # overrides.
+    #
+    # @param content [String, Array<Hash>, nil] message content field
+    # @return [String] textual content joined with newlines
+    def content_text(content)
+      case content
+      when Array
+        content.filter_map { |part| MessageAccess.value(part, :text) }.join("\n")
+      else
+        content.to_s
+      end
+    end
+  end
+end

data/lib/kward/model/chat_invocation.rb

@@ -1,4 +1,6 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Thin adapter that invokes the configured model client.
   module ChatInvocation
     module_function