kward 0.67.1 → 0.69.0

data/lib/kward/conversation.rb

@@ -4,23 +4,78 @@ 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 durable transcript entries, excluding runtime system prompt state
+    attr_reader :messages
+    # @return [Hash, nil] current system prompt included when building provider request context
+    attr_reader :system_message
+    # @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 [Proc, nil] callback invoked when the system prompt runtime state changes
+    attr_accessor :on_system_message_change
+    # @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
+    # @return [String, nil] plugin prompt context used in the current system prompt
+    attr_reader :last_plugin_prompt_context
+
+    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
       @messages = []
+      restored_system_message, transcript_messages = split_system_message(messages)
       if system_message.equal?(DEFAULT_SYSTEM_MESSAGE)
-        system_message = messages.any? { |message| MessageAccess.role(message) == "system" } ? nil : Prompts.system_message(workspace_root: @workspace_root, model: @model, reasoning_effort: @reasoning_effort, memory_context: memory_context, plugin_context: plugin_prompt_context)
+        if restored_system_message
+          system_message = restored_system_message
+        else
+          @last_plugin_prompt_context = plugin_prompt_context
+          system_message = Prompts.system_message(workspace_root: @workspace_root, model: @model, reasoning_effort: @reasoning_effort, memory_context: memory_context, plugin_context: @last_plugin_prompt_context)
+        end
       end
-      @system_message_enabled = !!(system_message || messages.find { |message| MessageAccess.role(message) == "system" })
+      @system_message = system_message
+      @system_message_enabled = !@system_message.nil?
       if compaction_system_message.equal?(DEFAULT_SYSTEM_MESSAGE)
         compaction_system_message = @system_message_enabled ? Prompts.system_message(workspace_root: @workspace_root, include_workspace_personality: false, model: @model, reasoning_effort: @reasoning_effort) : nil
       end
@@ -30,14 +85,19 @@ module Kward
       @memory_context = memory_context
       @session_memories = Array(session_memories)
       @last_memory_retrieval = last_memory_retrieval
-      @messages << system_message unless system_message.nil?
-      @messages.concat(messages)
+      @messages.concat(transcript_messages)
       @read_paths = Set.new(read_paths)
       @on_append = on_append
       @on_compact = on_compact
       @on_tool_execution = on_tool_execution
+      @on_runtime_update = on_runtime_update
+      @on_system_message_change = nil
     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,23 +123,40 @@ module Kward
       @on_tool_execution&.call(tool_call, content)
     end
 
+    # @return [Array<Hash>] provider request context: current system prompt plus durable transcript
+    def context_messages
+      @system_message ? [@system_message] + @messages : @messages.dup
+    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
 
-      replacement = Prompts.system_message(workspace_root: @workspace_root, model: @model, reasoning_effort: @reasoning_effort, memory_context: @memory_context, plugin_context: plugin_prompt_context)
-      index = @messages.index { |message| MessageAccess.role(message) == "system" }
-      index ? @messages[index] = replacement : @messages.unshift(replacement)
+      @last_plugin_prompt_context = plugin_prompt_context
+      replacement = Prompts.system_message(workspace_root: @workspace_root, model: @model, reasoning_effort: @reasoning_effort, memory_context: @memory_context, plugin_context: @last_plugin_prompt_context)
+      @system_message = replacement
+      @on_system_message_change&.call(replacement)
       @compaction_system_message = Prompts.system_message(workspace_root: @workspace_root, include_workspace_personality: false, model: @model, reasoning_effort: @reasoning_effort)
       @workspace_agents_mtime = workspace_agents_mtime
       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 +172,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 }
@@ -107,7 +191,7 @@ module Kward
         message[:from_hook] = from_hook
         message[:details] = details || {}
       end
-      @messages = @messages.select { |item| MessageAccess.role(item) == "system" }
+      @messages = []
       @messages << message
       @messages.concat(Array(keep_messages))
       @read_paths.clear
@@ -132,6 +216,19 @@ module Kward
 
     private
 
+    def split_system_message(messages)
+      system_message = nil
+      transcript_messages = []
+      Array(messages).each do |message|
+        if MessageAccess.role(message) == "system" && system_message.nil?
+          system_message = message
+        elsif MessageAccess.role(message) != "system"
+          transcript_messages << message
+        end
+      end
+      [system_message, transcript_messages]
+    end
+
     def workspace_agents_mtime
       path = File.join(@workspace_root, "AGENTS.md")
       File.exist?(path) ? File.mtime(path) : nil

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.
     #
@@ -21,6 +23,7 @@ module Kward
       DEFAULT_SOFT_TTL_DAYS = 60
       DEFAULT_SOFT_CONFIDENCE = 0.65
       EMOTIONAL_PATTERN = /\b(love|loves|romantic|intimate|dependency|depend on me|need me|flirty|crush)\b/i
+      MEMORY_DUPLICATE_STOPWORDS = Set.new(%w[a an and as at for in of on or that the this to with])
 
       # Details for the most recent retrieval, used by `/memory why`.
       attr_reader :last_retrieval
@@ -35,6 +38,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
@@ -145,10 +149,20 @@ module Kward
       # @param ttl_days [Integer, nil] time-to-live in days
       # @return [Hash] stored memory record
       def add_soft(text, scope: "global", tags: [], confidence: DEFAULT_SOFT_CONFIDENCE, ttl_days: DEFAULT_SOFT_TTL_DAYS, source: "manual")
+        normalized_scope = clean_scope(scope)
+        normalized_text = clean_text(normalize_memory_text(text))
+        raise ArgumentError, "Memory text cannot be empty" if normalized_text.empty?
+        raise ArgumentError, "Refusing to persist emotional or dependency-forming memory automatically" if source == "inferred" && unsafe_soft_text?(normalized_text)
+
+        existing = soft_memories.find do |item|
+          item["scope"] == normalized_scope && duplicate_memory_text?(normalized_text, [item["text"]])
+        end
+        return existing if existing
+
         record = {
           "id" => next_id("soft", soft_memories(include_inactive: true).map { |item| item["id"] }),
-          "text" => clean_text(normalize_memory_text(text)),
-          "scope" => clean_scope(scope),
+          "text" => normalized_text,
+          "scope" => normalized_scope,
           "tags" => clean_tags(tags),
           "confidence" => [[confidence.to_f, 0.0].max, 1.0].min,
           "hits" => 0,
@@ -159,8 +173,6 @@ module Kward
           "source" => source,
           "status" => "active"
         }
-        raise ArgumentError, "Memory text cannot be empty" if record["text"].empty?
-        raise ArgumentError, "Refusing to persist emotional or dependency-forming memory automatically" if source == "inferred" && unsafe_soft_text?(record["text"])
 
         append_soft(record)
         append_event("add", event_ref(record, layer: "soft"))
@@ -229,16 +241,20 @@ module Kward
       end
 
       def list(include_inactive: false)
-        { "core" => core_memories, "soft" => soft_memories(include_inactive: include_inactive) }
+        soft = soft_memories(include_inactive: include_inactive)
+        soft = deduplicate_soft_records(soft) unless include_inactive
+        { "core" => core_memories, "soft" => soft }
       end
 
       def hierarchy(workspace_root: Dir.pwd, include_inactive: false)
         workspace = workspace_scope(workspace_root)
         core = core_memories
+        soft = soft_memories(include_inactive: include_inactive)
+        soft = deduplicate_soft_records(soft) unless include_inactive
         {
           "global_core" => core.select { |item| item["scope"] == "global" },
           "workspace_core" => core.select { |item| item["scope"] == workspace },
-          "workspace_soft" => soft_memories(include_inactive: include_inactive).select { |item| item["scope"] == workspace }
+          "workspace_soft" => soft.select { |item| item["scope"] == workspace }
         }
       end
 
@@ -268,8 +284,7 @@ module Kward
         core_reasons = core.map { |item| reason_for(item, layer: "core", score: 1.0, reasons: ["scope match", "core memories are preferred"]) }
 
         soft_records_all = soft_memories(include_inactive: true)
-        soft_scored = soft_records_all.filter_map do |item|
-          next unless item["status"] == "active"
+        soft_scored = deduplicate_soft_records(soft_records_all.select { |item| item["status"] == "active" }).filter_map do |item|
           next unless item["scope"] == workspace
           next if expired?(item)
 
@@ -299,6 +314,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 +350,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"] }
@@ -341,14 +366,118 @@ module Kward
       def infer_soft_from_text(text, workspace_root: Dir.pwd, client: nil, existing_texts: [])
         candidates = heuristic_candidates(text)
         existing_set = Set.new(existing_texts.map { |t| normalize_for_comparison(t) })
+        scope = workspace_scope(workspace_root)
+        workspace_scopes = [scope, clean_scope("workspace:#{workspace_root}")].uniq
+        workspace_soft_texts = soft_memories.select { |memory| workspace_scopes.include?(memory["scope"]) }.map { |memory| memory["text"] }
         candidates.filter_map do |candidate|
-          summarized = summarize_text(candidate, client: client)
+          summarized = normalize_inferred_memory_text(summarize_text(candidate, client: client), source_text: candidate)
           normalized = normalize_for_comparison(summarized)
           # Skip if this text already exists in provided list or existing soft memories
           next if existing_set.include?(normalized)
-          next if soft_memories.any? { |m| normalize_for_comparison(m["text"]) == normalized }
+          next if duplicate_memory_text?(summarized, existing_texts)
+          next if duplicate_memory_text?(summarized, workspace_soft_texts)
+
+          record = add_soft(summarized, scope: scope, tags: ["workflow"], confidence: 0.55, source: "inferred")
+          workspace_soft_texts << record["text"]
+          record
+        end
+      end
+
+      def normalize_inferred_memory_text(text, source_text: nil)
+        normalized = normalize_memory_text(text)
+        source = source_text.to_s
+        first_person_source = source.match?(/\b(?:i|we|my|our)\b/i)
+
+        if first_person_source
+          normalized = normalized.sub(/\AThe\s+\w+\s+(prefers|likes|uses|usually|always|wants|believes|thinks|avoids)\b/i) do
+            "The user #{Regexp.last_match(1).downcase}"
+          end
+          normalized = normalized.sub(/\AI\s+(?:(usually|always)\s+)?(prefer|like|use|want|believe|think|avoid)\b/i) do
+            adverb = Regexp.last_match(1)
+            verb = third_person_verb(Regexp.last_match(2))
+            ["The user", adverb&.downcase, verb].compact.join(" ")
+          end
+          normalized = normalized.sub(/\AWe\s+(?:(usually|always)\s+)?(prefer|like|use|want|believe|think|avoid)\b/i) do
+            adverb = Regexp.last_match(1)
+            verb = third_person_verb(Regexp.last_match(2))
+            ["The user", adverb&.downcase, verb].compact.join(" ")
+          end
+          normalized = normalized.sub(/\AMy\s+/i, "The user's ")
+          normalized = normalized.sub(/\AOur\s+/i, "The user's ")
+        end
+
+        clean_text(normalized)
+      end
+
+      def third_person_verb(verb)
+        word = verb.to_s.downcase
+        return word if ["usually", "always"].include?(word)
+        return "uses" if word == "use"
+
+        word.end_with?("s") ? word : "#{word}s"
+      end
+
+      def duplicate_memory_text?(text, existing_texts)
+        candidate = memory_duplicate_key(text)
+        candidate_tokens = memory_duplicate_tokens(text)
+        Array(existing_texts).any? do |existing|
+          existing_key = memory_duplicate_key(existing)
+          next true if existing_key == candidate
+
+          existing_tokens = memory_duplicate_tokens(existing)
+          next false if candidate_tokens.empty? || existing_tokens.empty?
+
+          overlap = (candidate_tokens & existing_tokens).length
+          union = (candidate_tokens | existing_tokens).length
+          union.positive? && overlap.to_f / union >= 0.8
+        end
+      end
+
+      def memory_duplicate_key(text)
+        normalized = normalize_for_comparison(text).downcase
+        normalized = normalized.sub(/\Ai\s+(?:(usually|always)\s+)?(prefer|like|use|want|believe|think|avoid)\b/i) do
+          ["the user", Regexp.last_match(1)&.downcase, third_person_verb(Regexp.last_match(2))].compact.join(" ")
+        end
+        normalized = normalized.sub(/\Awe\s+(?:(usually|always)\s+)?(prefer|like|use|want|believe|think|avoid)\b/i) do
+          ["the user", Regexp.last_match(1)&.downcase, third_person_verb(Regexp.last_match(2))].compact.join(" ")
+        end
+        normalized = normalized.sub(/\Amy\s+/i, "the user's ")
+        normalized = normalized.sub(/\Aour\s+/i, "the user's ")
+        normalized.tr("“”‘’", "\"\"''")
+      end
+
+      def memory_duplicate_tokens(text)
+        memory_duplicate_key(text).scan(/[a-z0-9_\-']{3,}/).filter_map do |term|
+          token = memory_duplicate_token(term)
+          token unless MEMORY_DUPLICATE_STOPWORDS.include?(token)
+        end.uniq
+      end
+
+      def memory_duplicate_token(term)
+        case term
+        when "uses", "using"
+          "use"
+        when "prefers", "preferring"
+          "prefer"
+        when "avoids", "avoiding"
+          "avoid"
+        else
+          term.sub(/\A(.{4,})s\z/, '\\1')
+        end
+      end
+
+      def deduplicate_soft_records(records)
+        seen = []
+        records.each_with_object([]) do |record, deduplicated|
+          scope = record["scope"]
+          text = record["text"]
+          duplicate = seen.any? do |seen_record|
+            seen_record["scope"] == scope && duplicate_memory_text?(text, [seen_record["text"]])
+          end
+          next if duplicate
 
-          add_soft(summarized, scope: workspace_scope(workspace_root), tags: ["workflow"], confidence: 0.55, source: "inferred")
+          seen << record
+          deduplicated << record
         end
       end
 
@@ -391,16 +520,17 @@ module Kward
             You are a memory text reformulation assistant. Your task is to transform user-generated text into proper third-person descriptive memory statements.
 
             Rules:
-            - Convert first-person statements ("I like", "we prefer") to third-person ("The captain likes", "The user prefers")
+            - Convert first-person statements ("I like", "we prefer") to third-person ("The user likes", "The user prefers")
             - Remove conversational filler, preambles, and action descriptions
             - Keep only the factual preference or fact
-            - Use "The captain" or "The user" as the subject for personal preferences
+            - Always use "The user" as the subject for personal preferences
+            - Do not use persona-specific names, titles, roles, or nicknames
             - Preserve workflow-related technical preferences as-is
             - Keep the text concise (under 100 characters)
             - If the text is already a good memory statement, return it unchanged
 
             Examples:
-            - "I like to eat the most important meal today: steak" → "The captain likes eating steak"
+            - "I like to eat the most important meal today: steak" → "The user likes eating steak"
             - "We should prefer TDD for this project" → "Prefer TDD for this project"
             - "Remember that the user prefers minitest" → "The user prefers minitest"
             - "But first we need to remember that we are using TDD" → "Use TDD"

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,12 +47,23 @@ 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
+
+    # @return [Array<Hash>] provider-native Responses output items, or an empty array
+    def response_items(message)
+      items = value(message, :response_items) || value(message, :responseItems)
+      items.is_a?(Array) ? items : []
+    end
   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