kward 0.67.1 → 0.68.0

data/lib/kward/rpc/session_manager.rb

@@ -1,4 +1,3 @@
-require "base64"
 require "securerandom"
 require "thread"
 require "time"
@@ -13,6 +12,8 @@ require_relative "../events"
 require_relative "../export_path"
 require_relative "../memory/manager"
 require_relative "../message_access"
+require_relative "../message_text"
+require_relative "../session_tree_tool_display"
 require_relative "../model/model_info"
 require_relative "../plugin_registry"
 require_relative "../prompts/commands"
@@ -23,17 +24,36 @@ require_relative "../tools/tool_call"
 require_relative "../tools/registry"
 require_relative "../transcript_export"
 require_relative "../workspace"
+require_relative "attachment_normalizer"
+require_relative "config_manager"
 require_relative "prompt_bridge"
 require_relative "runtime_payloads"
+require_relative "session_metrics"
+require_relative "session_tree"
+require_relative "session_tree_rows"
 require_relative "tool_event_normalizer"
 require_relative "transcript_normalizer"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # JSON-RPC backend namespace used by UI clients.
   module RPC
+    # Owns RPC-visible session lifecycle, async turn queues, and frontend events.
+    #
+    # `Server` handles JSON-RPC framing/dispatch; `SessionManager` handles the
+    # product state behind those methods. It creates/resumes `SessionStore`
+    # sessions, builds agents with RPC prompt bridges, serializes turn events for
+    # clients, coordinates cancellation and follow-up queues, and integrates
+    # memory/plugin hooks for RPC sessions.
+    #
+    # Keep JSON-RPC wire shape normalization in the `RPC::*Normalizer` classes,
+    # persistence in `SessionStore`, and model/tool behavior in `Agent` and
+    # `ToolRegistry`. This class should coordinate those pieces rather than own
+    # their low-level mechanics.
     class SessionManager
       RECENT_EVENT_LIMIT = 1_000
-      RPC_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024
-      RPC_IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"].freeze
+      RPC_ATTACHMENT_MAX_BYTES = AttachmentNormalizer::MAX_BYTES
+      RPC_IMAGE_MIME_TYPES = AttachmentNormalizer::IMAGE_MIME_TYPES
       STREAMING_BEHAVIORS = ["newTurn", "followUp", "steer"].freeze
       FOOTER_REFRESH_INTERVAL = 1.0
       WORKER_STOP = Object.new.freeze
@@ -41,17 +61,32 @@ module Kward
       RpcSession = Struct.new(:id, :workspace_root, :store, :session, :conversation, :agent, :tool_registry, :prompt, :plugin_output, :queue, :worker, :running_turn_id, :footer_worker, :last_footer_text, keyword_init: true)
       Turn = Struct.new(:id, :session_id, :input, :display_input, :status, :cancel_requested, :cancellation, :created_at, :started_at, :finished_at, :events, :next_sequence, :error, :streaming_behavior, :plugin_command_name, :plugin_arguments, :steering, keyword_init: true)
 
-      def initialize(server:, client: Client.new, config_dir: ConfigFiles.config_dir, context_usage: ContextUsage.new, session_trash: SessionTrash.new)
+      # Creates an object for RPC session lifecycle and turn coordination.
+      def initialize(
+        server:,
+        client: Client.new,
+        config_dir: ConfigFiles.config_dir,
+        config_manager: ConfigManager.new(config_path: File.join(config_dir, "config.json")),
+        context_usage: ContextUsage.new,
+        session_trash: SessionTrash.new
+      )
         @server = server
         @client = client
         @config_dir = config_dir
+        @config_manager = config_manager
         @context_usage = context_usage
+        @session_metrics = SessionMetrics.new(context_usage: context_usage)
         @session_trash = session_trash
         @sessions = {}
         @turns = {}
         @mutex = Mutex.new
       end
 
+      # Creates a new RPC session or resumes the remembered session when allowed.
+      #
+      # Returns the normalized session payload expected by RPC clients. The RPC
+      # session id is separate from the persisted session id so one persisted file
+      # can be closed and reopened by different client connections.
       def create_session(workspace_root: Dir.pwd, name: nil, resume_last: false)
         workspace_root = validate_workspace_root(workspace_root)
         store = SessionStore.new(config_dir: @config_dir, cwd: workspace_root)
@@ -61,7 +96,7 @@ module Kward
         end
 
         conversation = new_conversation(workspace_root: workspace_root)
-        session = store.create(model: conversation.model, reasoning_effort: conversation.reasoning_effort)
+        session = store.create(provider: conversation.provider, model: conversation.model, reasoning_effort: conversation.reasoning_effort)
         session.rename(name) unless name.to_s.strip.empty?
         session.attach(conversation)
         rpc_session = build_rpc_session(store, session, conversation, workspace_root)
@@ -80,6 +115,7 @@ module Kward
         session, conversation = store.load(
           location[:path],
           workspace: configured_workspace(root),
+          provider: current_model[:provider],
           model: current_model_id,
           reasoning_effort: current_reasoning_effort
         )
@@ -102,12 +138,14 @@ module Kward
              .map { |info| session_info_payload(info, workspace_root: root) }
       end
 
+      # Renames the persisted session attached to an RPC session id.
       def rename_session(session_id:, name:)
         rpc_session = fetch_session(session_id)
         rpc_session.session.rename(name)
         session_payload(rpc_session)
       end
 
+      # Creates an independent copy of the current conversation branch.
       def clone_session(session_id:)
         source = fetch_session(session_id)
         session, conversation = source.store.create_independent_from_conversation(source.conversation, parent_session: source.session)
@@ -118,6 +156,7 @@ module Kward
         session_payload(rpc_session)
       end
 
+      # Compacts an RPC session and emits start/end events for UI progress.
       def compact_session(session_id:, custom_instructions: "")
         rpc_session = fetch_session(session_id)
         emit_session_event(rpc_session, "compactionStart", {})
@@ -135,10 +174,11 @@ module Kward
         raise e
       end
 
+      # Lists user-message entries that can be used as fork points.
       def fork_messages(session_id:)
         rpc_session = fetch_session(session_id)
         {
-          messages: tree_entries(rpc_session).filter_map do |record|
+          messages: session_tree_helper(rpc_session).entries.filter_map do |record|
             message = record["message"]
             next unless message.is_a?(Hash) && message_role(message) == "user"
 
@@ -147,10 +187,12 @@ module Kward
         }
       end
 
+      # Creates a new session from history before the selected user message.
       def fork_session(session_id:, entry_id:)
         source = fetch_session(session_id)
-        entries = tree_entries(source)
-        resolved_entry_id = resolve_tree_entry_id(entries, entry_id)
+        tree = session_tree_helper(source)
+        entries = tree.entries
+        resolved_entry_id = tree.resolve_entry_id(entry_id, entries: entries)
         selected_index = entries.index { |record| record["id"].to_s == resolved_entry_id.to_s }
         selected = selected_index && entries[selected_index]
         raise ArgumentError, "Unknown fork entryId: #{entry_id}" unless selected
@@ -160,6 +202,7 @@ module Kward
 
         session, conversation = source.store.create_independent_from_messages(
           entries[0...selected_index].filter_map { |record| record["message"] },
+          provider: source.conversation.provider,
           model: source.conversation.model,
           reasoning_effort: source.conversation.reasoning_effort,
           parent_session: source.session
@@ -175,28 +218,32 @@ module Kward
         }
       end
 
+      # Returns the flattened session tree rows consumed by RPC clients.
       def session_tree(session_id:)
         rpc_session = fetch_session(session_id)
         { items: flatten_session_tree(rpc_session) }
       end
 
+      # Persists a label override for one tree entry.
       def set_tree_label(session_id:, entry_id:, label: nil)
         rpc_session = fetch_session(session_id)
         rpc_session.session.append_label_change(entry_id, label)
         { ok: true }
       end
 
+      # Moves the active branch to a tree entry, optionally summarizing abandoned history.
       def navigate_tree(session_id:, entry_id:, summarize: false, custom_instructions: nil)
         rpc_session = fetch_session(session_id)
-        entries = tree_entries(rpc_session)
-        resolved_entry_id = resolve_tree_entry_id(entries, entry_id)
+        tree = session_tree_helper(rpc_session)
+        entries = tree.entries
+        resolved_entry_id = tree.resolve_entry_id(entry_id, entries: entries)
         entry = rpc_session.store.session_entry(rpc_session.session.path, resolved_entry_id)
         raise ArgumentError, "Unknown tree entryId: #{entry_id}" unless entry
 
-        raise ArgumentError, "Tree entry is not selectable: #{entry_id}" unless selectable_tree_entry?(entry)
+        raise ArgumentError, "Tree entry is not selectable: #{entry_id}" unless tree.selectable_entry?(entry)
 
         message = entry["message"]
-        user_entry = user_tree_entry?(entry)
+        user_entry = tree.user_entry?(entry)
         target_leaf = user_entry ? entry["parentId"] : entry["id"]
         editor_text = user_entry ? full_message_text(message) : nil
         previous_leaf = rpc_session.session.leaf_id
@@ -217,6 +264,7 @@ module Kward
         }.compact
       end
 
+      # Exports the current transcript in markdown or JSON format.
       def export_session(session_id:, path: nil, format: nil)
         rpc_session = fetch_session(session_id)
         format = export_format(format)
@@ -226,6 +274,7 @@ module Kward
         { path: path, format: format }
       end
 
+      # Deletes the backing session file through the configured trash strategy.
       def delete_session(session_id:)
         rpc_session = fetch_session(session_id)
         path = rpc_session.session.path
@@ -234,12 +283,14 @@ module Kward
         { deleted: deleted, path: path }
       end
 
+      # Stops workers and removes an RPC session from the live session map.
       def close_session(session_id:)
         rpc_session = fetch_session(session_id)
         close_rpc_session(rpc_session)
         { closed: true }
       end
 
+      # Closes idle empty sessions left behind by UI lifecycle transitions.
       def cleanup_unused_sessions
         rpc_sessions = @mutex.synchronize { @sessions.values.dup }
         rpc_sessions.reverse_each do |rpc_session|
@@ -250,11 +301,18 @@ module Kward
         { closed: true }
       end
 
+      # Returns the normalized transcript for the active RPC session.
       def transcript(session_id:)
         rpc_session = fetch_session(session_id)
         { session: session_payload(rpc_session), messages: TranscriptNormalizer.new(rpc_session.conversation.messages).normalize }
       end
 
+      # Queues or starts an async model turn for an RPC session.
+      #
+      # `streaming_behavior` controls busy-session behavior: create a new turn,
+      # queue a follow-up, or steer the running turn when the active provider
+      # supports native steering. The returned turn id is used for status,
+      # cancellation, and event replay.
       def start_turn(session_id:, input:, streaming_behavior: nil, attachments: [])
         rpc_session = fetch_session(session_id)
         normalized_attachments = normalize_attachments(attachments)
@@ -439,13 +497,30 @@ module Kward
         normalize_model(provider: provider, id: model, model: model, contextWindow: context_window, current: true)
       end
 
+      def session_model(rpc_session)
+        current = current_model
+        provider = rpc_session.conversation.provider || current[:provider]
+        model = rpc_session.conversation.model || current[:id]
+        reasoning_effort = rpc_session.conversation.reasoning_effort || current_reasoning_effort
+        reasoning_effort = nil unless ModelInfo.reasoning_supported?(provider, model)
+        context_window = current[:contextWindow] if provider == current[:provider] && model == current[:id]
+        normalize_model(
+          provider: provider,
+          id: model,
+          model: model,
+          reasoningEffort: reasoning_effort,
+          contextWindow: context_window,
+          current: true
+        )
+      end
+
       def in_flight_steer_supported?
         supports_in_flight_steer?
       end
 
       def runtime_state(session_id:)
         rpc_session = fetch_session(session_id)
-        model = current_model
+        model = session_model(rpc_session)
         compaction_settings = self.compaction_settings
         auto_compaction_reserve_tokens = compaction_reserve_tokens(
           context_window: model[:contextWindow],
@@ -459,7 +534,7 @@ module Kward
           steering_supported: supports_in_flight_steer?,
           auto_compaction_reserve_tokens: auto_compaction_reserve_tokens,
           active_persona_label: active_persona_label(rpc_session),
-          message_count: message_count(rpc_session.conversation),
+          message_count: @session_metrics.message_count(rpc_session.conversation),
           pending_count: pending_turn_count(rpc_session.id),
           compaction_enabled: compaction_settings.enabled,
           workspace_guardrails_enabled: workspace_guardrails_enabled?
@@ -469,8 +544,8 @@ module Kward
       def runtime_stats(session_id:)
         rpc_session = fetch_session(session_id)
         session = session_payload(rpc_session)
-        counts = message_stats(rpc_session.conversation)
-        model = current_model
+        counts = @session_metrics.message_stats(rpc_session.conversation)
+        model = session_model(rpc_session)
         compaction_settings = self.compaction_settings
         auto_compaction_reserve_tokens = compaction_reserve_tokens(
           context_window: model[:contextWindow],
@@ -481,7 +556,7 @@ module Kward
           counts: counts,
           model: model,
           auto_compaction_reserve_tokens: auto_compaction_reserve_tokens,
-          context_usage: context_usage(rpc_session, model),
+          context_usage: @session_metrics.context_usage(rpc_session, model, client: @client),
           compaction_enabled: compaction_settings.enabled
         )
       end
@@ -529,6 +604,7 @@ module Kward
       def new_conversation(workspace_root: Dir.pwd)
         Conversation.new(
           workspace_root: workspace_root,
+          provider: (@client.current_provider if @client.respond_to?(:current_provider)),
           model: (@client.current_model if @client.respond_to?(:current_model)),
           reasoning_effort: (@client.current_reasoning_effort if @client.respond_to?(:current_reasoning_effort)),
           plugin_registry: plugin_registry
@@ -540,8 +616,7 @@ module Kward
         reasoning_effort = current_reasoning_effort
         sessions = @mutex.synchronize { @sessions.values }
         sessions.each do |rpc_session|
-          rpc_session.conversation.update_runtime_context!(model: model, reasoning_effort: reasoning_effort)
-          rpc_session.session.update_runtime(model: model, reasoning_effort: reasoning_effort)
+          rpc_session.conversation.update_runtime_context!(provider: current_model[:provider], model: model, reasoning_effort: reasoning_effort)
         end
       end
 
@@ -621,42 +696,6 @@ module Kward
         @mutex.synchronize { @sessions.values.count { |rpc_session| rpc_session.workspace_root == workspace_root } }
       end
 
-      def message_count(conversation)
-        conversation.messages.count { |message| message_role(message) != "system" }
-      end
-
-      def context_usage(rpc_session, model)
-        context_parts = if @client.respond_to?(:current_context_parts)
-                          @client.current_context_parts(rpc_session.conversation.messages, rpc_session.tool_registry.schemas)
-                        else
-                          { provider: model[:provider], model: model[:id], messages: rpc_session.conversation.messages, tools: rpc_session.tool_registry.schemas }
-                        end
-        @context_usage.call(
-          provider: model[:provider],
-          model: model[:id],
-          context_window: model[:contextWindow],
-          context_parts: context_parts
-        )
-      end
-
-      def message_stats(conversation)
-        conversation.messages.each_with_object({ userMessages: 0, assistantMessages: 0, toolCalls: 0, toolResults: 0, totalMessages: 0 }) do |message, counts|
-          role = message_role(message)
-          next if role == "system"
-
-          counts[:totalMessages] += 1
-          case role
-          when "user"
-            counts[:userMessages] += 1
-          when "assistant"
-            counts[:assistantMessages] += 1
-            counts[:toolCalls] += tool_calls(message).length
-          when "tool", "toolResult"
-            counts[:toolResults] += 1
-          end
-        end
-      end
-
       def tool_calls(message)
         MessageAccess.tool_calls(message)
       end
@@ -669,24 +708,15 @@ module Kward
         MessageAccess.content(message)
       end
 
-      def tree_entries(rpc_session)
-        rpc_session.store.session_entries(rpc_session.session.path)
-      end
-
-      def resolve_tree_entry_id(entries, entry_id)
-        id = entry_id.to_s
-        return id if entries.any? { |record| record["id"].to_s == id }
-
-        match = id.match(/\Amessage:(\d+)\z/)
-        return entries[match[1].to_i]&.dig("id") if match
-
-        id
+      def session_tree_helper(rpc_session)
+        SessionTree.new(rpc_session)
       end
 
       def reload_rpc_session(rpc_session)
         session, conversation = rpc_session.store.load(
           rpc_session.session.path,
           workspace: configured_workspace(rpc_session.workspace_root),
+          provider: current_model[:provider],
           model: current_model_id,
           reasoning_effort: current_reasoning_effort
         )
@@ -700,242 +730,19 @@ module Kward
       def flatten_session_tree(rpc_session)
         roots = rpc_session.store.session_tree(rpc_session.session.path)
         current_leaf = rpc_session.session.leaf_id || rpc_session.store.current_leaf(rpc_session.session.path)
-        active_path = tree_active_path(roots, current_leaf)
-        tool_calls_by_id = tree_tool_calls(roots)
-        visible_roots = roots.flat_map { |root| visible_tree_nodes(root, current_leaf) }
-        multiple_roots = visible_roots.length > 1
-        result = []
-
-        walk = lambda do |node, indent, just_branched, show_connector, is_last, gutters, virtual_root_child|
-          entry = node[:source]["entry"] || {}
-          entry_id = entry["id"].to_s
-          formatted = tree_entry_display(entry, tool_calls_by_id)
-          display_indent = multiple_roots ? [indent - 1, 0].max : indent
-          result << {
-            entryId: entry_id,
-            parentId: entry["parentId"],
-            role: formatted[:role],
-            text: formatted[:text],
-            current: !current_leaf.to_s.empty? && entry_id == current_leaf.to_s,
-            depth: display_indent,
-            isLast: is_last,
-            ancestorContinues: gutters.map { |gutter| gutter[:show] },
-            activePath: active_path.include?(entry_id),
-            selectable: selectable_tree_entry?(entry),
-            label: node[:source]["label"] || entry["resolvedLabel"],
-            labelTimestamp: node[:source]["labelTimestamp"],
-            prefix: tree_prefix(display_indent, gutters, show_connector && !virtual_root_child, is_last, !node[:children].empty?)
-          }.compact
-
-          children = node[:children].sort_by { |child| tree_contains_active_path?(child, active_path) ? 0 : 1 }
-          multiple_children = children.length > 1
-          child_indent = if multiple_children
-                           indent + 1
-                         elsif just_branched && indent.positive?
-                           indent + 1
-                         else
-                           indent
-                         end
-          connector_position = [display_indent - 1, 0].max
-          child_gutters = show_connector && !virtual_root_child ? gutters + [{ position: connector_position, show: !is_last }] : gutters
-          children.each_with_index do |child, index|
-            walk.call(child, child_indent, multiple_children, multiple_children, index == children.length - 1, child_gutters, false)
-          end
-        end
-
-        visible_roots.sort_by { |root| tree_contains_active_path?(root, active_path) ? 0 : 1 }.each_with_index do |root, index|
-          walk.call(root, multiple_roots ? 1 : 0, multiple_roots, multiple_roots, index == visible_roots.length - 1, [], multiple_roots)
-        end
-        result
-      end
-
-      def user_tree_entry?(entry)
-        message = entry["message"]
-        message.is_a?(Hash) && message_role(message) == "user"
-      end
-
-      def selectable_tree_entry?(entry)
-        !entry["id"].to_s.empty? && ["message", "compaction", "branch_summary"].include?(entry["type"])
-      end
-
-      def nearest_visible_parent_by_id(user_entries, entries)
-        user_ids = user_entries.map { |entry| entry["id"].to_s }.to_h { |id| [id, true] }
-        by_id = entries.to_h { |entry| [entry["id"].to_s, entry] }
-        user_entries.each_with_object({}) do |entry, parents|
-          parent_id = entry["parentId"]
-          while parent_id && by_id[parent_id.to_s] && !user_ids[parent_id.to_s]
-            parent_id = by_id[parent_id.to_s]["parentId"]
-          end
-          parents[entry["id"].to_s] = user_ids[parent_id.to_s] ? parent_id.to_s : nil
-        end
-      end
-
-      def active_path_ids(entries, leaf_id)
-        by_id = entries.to_h { |entry| [entry["id"].to_s, entry] }
-        ids = []
-        current = by_id[leaf_id.to_s]
-        while current
-          ids << current["id"].to_s
-          current = by_id[current["parentId"].to_s]
-        end
-        ids
-      end
-
-      def tree_active_path(roots, leaf_id)
-        by_id = tree_entries_by_id(roots)
-        ids = []
-        current = by_id[leaf_id.to_s]
-        while current
-          ids << current["id"].to_s
-          current = by_id[current["parentId"].to_s]
-        end
-        ids
-      end
-
-      def tree_entries_by_id(roots)
-        roots.each_with_object({}) do |root, map|
-          stack = [root]
-          until stack.empty?
-            node = stack.pop
-            entry = node["entry"] || {}
-            map[entry["id"].to_s] = entry unless entry["id"].to_s.empty?
-            stack.concat(Array(node["children"]))
-          end
-        end
-      end
-
-      def visible_tree_nodes(node, current_leaf)
-        children = Array(node["children"]).flat_map { |child| visible_tree_nodes(child, current_leaf) }
-        return children if hidden_tree_entry?(node["entry"] || {}, current_leaf)
-
-        [{ source: node, children: children }]
-      end
-
-      def hidden_tree_entry?(entry, current_leaf)
-        return false if current_leaf && entry["id"].to_s == current_leaf.to_s
-        return false unless entry["type"] == "message"
-
-        message = entry["message"]
-        return false unless message.is_a?(Hash) && message_role(message) == "assistant"
-
-        content = message_content(message)
-        content_tool_calls = content.is_a?(Array) && content.any? { |part| ToolCall.value(part, :type) == "toolCall" }
-        (content_tool_calls && !tree_text_content?(content)) || (!tool_calls(message).empty? && full_message_text(message).empty?)
-      end
-
-      def tree_text_content?(content)
-        Array(content).any? { |part| ToolCall.value(part, :type) == "text" && ToolCall.value(part, :text).to_s.strip != "" }
-      end
-
-      def tree_contains_active_path?(node, active_path)
-        entry_id = (node[:source]["entry"] || {})["id"].to_s
-        active_path.include?(entry_id) || node[:children].any? { |child| tree_contains_active_path?(child, active_path) }
-      end
-
-      def tree_tool_calls(roots)
-        roots.each_with_object({}) do |root, tool_calls_by_id|
-          stack = [root]
-          until stack.empty?
-            node = stack.pop
-            entry = node["entry"] || {}
-            message = entry["message"]
-            if entry["type"] == "message" && message.is_a?(Hash) && message_role(message) == "assistant"
-              tool_calls(message).each { |tool_call| tool_calls_by_id[ToolCall.id(tool_call).to_s] = tool_call }
-            end
-            stack.concat(Array(node["children"]))
-          end
-        end
-      end
-
-      def tree_entry_display(entry, tool_calls_by_id = {})
-        case entry["type"]
-        when "message"
-          message = entry["message"] || {}
-          role = message_role(message).to_s
-          return { role: "tool", text: format_tool_result(message, tool_calls_by_id) } if ["tool", "toolResult"].include?(role)
-          return { role: role.empty? ? "message" : role, text: display_message_text(message) }
-        when "compaction"
-          return { role: "compaction", text: display_message_text(entry["message"] || {}) }
-        when "branch_summary"
-          return { role: "summary", text: truncate_tree_text(entry["summary"]) }
-        end
-
-        { role: entry["type"].to_s.empty? ? "entry" : entry["type"].to_s, text: entry["type"].to_s }
-      end
-
-      def tree_prefix(display_indent, gutters, show_connector, is_last, foldable)
-        return "" if display_indent.to_i <= 0
-
-        connector_position = show_connector ? display_indent - 1 : -1
-        (0...(display_indent * 3)).map do |index|
-          level = index / 3
-          position = index % 3
-          gutter = gutters.find { |candidate| candidate[:position] == level }
-
-          if gutter
-            position.zero? && gutter[:show] ? "│" : " "
-          elsif show_connector && level == connector_position
-            if position.zero?
-              is_last ? "└" : "├"
-            elsif position == 1
-              foldable ? "⊟" : "─"
-            else
-              " "
-            end
-          else
-            " "
-          end
-        end.join
-      end
-
-      def format_tool_result(message, tool_calls_by_id)
-        tool_call = tool_calls_by_id[tree_message_tool_call_id(message).to_s]
-        return format_tool_call(tool_call) if tool_call
-
-        name = tree_message_tool_name(message).to_s
-        name = "tool" if name.empty?
-        "[#{name}]"
-      end
-
-      def tree_message_tool_call_id(message)
-        MessageAccess.tool_call_id(message) || ToolCall.value(message, :toolCallId)
-      end
-
-      def tree_message_tool_name(message)
-        MessageAccess.name(message) || ToolCall.value(message, :toolName)
-      end
-
-      def format_tool_call(tool_call)
-        name = ToolCall.display_name(tool_call)
-        args = ToolCall.arguments(tool_call)
-        case name
-        when "read"
-          path = args["path"] || args[:path] || args["file_path"] || args[:file_path]
-          offset = args["offset"] || args[:offset]
-          limit = args["limit"] || args[:limit]
-          display = path.to_s
-          if offset || limit
-            start_line = offset || 1
-            end_line = limit ? start_line.to_i + limit.to_i - 1 : nil
-            display += ":#{start_line}#{end_line ? "-#{end_line}" : ""}"
-          end
-          "[read: #{display}]"
-        when "write", "edit"
-          path = args["path"] || args[:path] || args["file_path"] || args[:file_path]
-          "[#{name}: #{path}]"
-        when "bash"
-          command = (args["command"] || args[:command]).to_s.gsub(/[\n\t]/, " ").strip
-          "[bash: #{command.length > 50 ? "#{command.slice(0, 50)}..." : command}]"
-        else
-          serialized = JSON.dump(args)
-          "[#{name}: #{serialized.length > 40 ? "#{serialized.slice(0, 40)}..." : serialized}]"
-        end
+        tree = session_tree_helper(rpc_session)
+        SessionTreeRows.new(
+          roots: roots,
+          current_leaf: current_leaf,
+          selectable: ->(entry) { tree.selectable_entry?(entry) }
+        ).rows
       end
 
       def summarize_branch(rpc_session, from_id:, to_id:, custom_instructions: nil)
-        entries = tree_entries(rpc_session)
-        active = active_path_ids(entries, from_id)
-        target = active_path_ids(entries, to_id)
+        tree = session_tree_helper(rpc_session)
+        entries = tree.entries
+        active = tree.active_path_ids(entries, from_id)
+        target = tree.active_path_ids(entries, to_id)
         target_lookup = target.to_h { |id| [id, true] }
         abandoned = active.reject { |id| target_lookup[id] }
         messages = entries.select { |entry| abandoned.include?(entry["id"].to_s) }.filter_map { |entry| entry["message"] }
@@ -959,13 +766,7 @@ module Kward
       end
 
       def full_message_text(message)
-        content = message["content"] || message[:content]
-        text = if content.is_a?(Array)
-                 content.filter_map { |part| part["text"] || part[:text] }.join("\n")
-               else
-                 content.to_s
-               end
-        text.strip
+        MessageText.full_text(message)
       end
 
       def supports_in_flight_steer?
@@ -1012,42 +813,7 @@ module Kward
       end
 
       def normalize_attachments(attachments)
-        return [] if attachments.nil?
-        raise ArgumentError, "attachments must be an array" unless attachments.is_a?(Array)
-
-        attachments.map { |attachment| normalize_attachment(attachment) }
-      end
-
-      def normalize_attachment(attachment)
-        raise ArgumentError, "attachment must be an object" unless attachment.is_a?(Hash)
-
-        type = ToolCall.value(attachment, :type).to_s
-        raise ArgumentError, "Unsupported attachment type: #{type.empty? ? "unknown" : type}" unless type == "image"
-
-        mime_type = normalize_attachment_mime_type(ToolCall.value(attachment, :mimeType) || ToolCall.value(attachment, :mime_type) || ToolCall.value(attachment, :media_type))
-        raise ArgumentError, "Unsupported image MIME type: #{mime_type.empty? ? "unknown" : mime_type}" unless RPC_IMAGE_MIME_TYPES.include?(mime_type)
-
-        data = ToolCall.value(attachment, :data).to_s
-        raise ArgumentError, "Image attachment data must be valid base64" if data.empty?
-        raise ArgumentError, "Image attachment data must be raw base64" if data.start_with?("data:")
-        declared_size = ToolCall.value(attachment, :sizeBytes) || ToolCall.value(attachment, :size_bytes)
-        raise ArgumentError, "Image attachment is too large" if declared_size && declared_size.to_i > RPC_ATTACHMENT_MAX_BYTES
-
-        decoded_size = Base64.strict_decode64(data).bytesize
-        raise ArgumentError, "Image attachment is too large" if decoded_size > RPC_ATTACHMENT_MAX_BYTES
-
-        result = { type: "image", data: data, mimeType: mime_type }
-        name = ToolCall.value(attachment, :name)
-        result[:alt] = name.to_s unless name.to_s.empty?
-        result
-      rescue ArgumentError => e
-        raise e if e.message.start_with?("Unsupported", "Image attachment", "attachment")
-
-        raise ArgumentError, "Image attachment data must be valid base64"
-      end
-
-      def normalize_attachment_mime_type(mime_type)
-        mime_type.to_s.downcase
+        AttachmentNormalizer.new(max_bytes: RPC_ATTACHMENT_MAX_BYTES, mime_types: RPC_IMAGE_MIME_TYPES).normalize(attachments)
       end
 
       def plugin_registry
@@ -1058,6 +824,11 @@ module Kward
         PromptCommands::BUILTIN_RESERVED_COMMAND_NAMES + ConfigFiles.prompt_templates(reserved_commands: PromptCommands::BUILTIN_RESERVED_COMMAND_NAMES).map(&:command)
       end
 
+      # Wires together the per-RPC-session runtime objects.
+      #
+      # This is the RPC counterpart to the CLI interactive setup: attach plugin
+      # context, create a prompt bridge for UI questions/footer output, advertise
+      # tools with the workspace guardrail policy, and build the shared `Agent`.
       def build_rpc_session(store, session, conversation, workspace_root)
         conversation.plugin_registry ||= plugin_registry if conversation.respond_to?(:plugin_registry)
         id = SecureRandom.uuid
@@ -1093,11 +864,11 @@ module Kward
       end
 
       def workspace_guardrails_enabled?
-        ConfigFiles.workspace_guardrails_enabled?(ConfigFiles.read_config(config_path))
+        @config_manager.workspace_guardrails_enabled?
       end
 
       def session_auto_resume_enabled?
-        ConfigFiles.session_auto_resume_enabled?(ConfigFiles.read_config(config_path))
+        @config_manager.session_auto_resume_enabled?
       end
 
       def config_path
@@ -1200,6 +971,11 @@ module Kward
         rpc_session.worker = nil if rpc_session.worker == Thread.current
       end
 
+      # Executes one queued turn and emits normalized RPC events.
+      #
+      # This method is intentionally the only place that calls `Agent#ask` for RPC
+      # turns. Keep event translation near this boundary so CLI rendering and RPC
+      # protocol details do not leak into `Agent`.
       def run_turn(rpc_session, turn)
         rpc_session.running_turn_id = turn.id
         turn.steering = build_steering(turn) if supports_in_flight_steer? && !turn.plugin_command_name