kward 0.71.0 → 0.73.0

data/lib/kward/session_store.rb

@@ -178,6 +178,9 @@ module Kward
     # @return [String] workspace directory this store lists and creates sessions for
     attr_reader :cwd
 
+    # @return [String] configuration directory containing session and tab files
+    attr_reader :config_dir
+
     # Creates a new empty session file for the store's workspace directory.
     #
     # Parent fields record clone/fork ancestry; they do not imply live coupling
@@ -285,6 +288,7 @@ module Kward
         session_memories: memory_state["sessionMemories"],
         last_memory_retrieval: memory_state["lastRetrieval"]
       )
+      restore_tool_output_artifacts(records, conversation)
       conversation.mark_last_entry_compaction! if latest_record_type(records) == "compaction"
       session = Session.new(
         store: self,
@@ -561,6 +565,46 @@ module Kward
       records.reverse.find { |record| record["type"] == "memory_state" } || { "sessionMemories" => [], "lastRetrieval" => nil }
     end
 
+    def restore_tool_output_artifacts(records, conversation)
+      tool_names = tool_message_names_by_id(records)
+      records.each do |record|
+        next unless record["type"] == "tool_execution_end"
+
+        content = record.dig("result", "content")
+        next if content.nil?
+
+        tool_name = tool_names[record["toolCallId"].to_s] || raw_tool_name(record["toolName"])
+        next if tool_name.to_s.empty?
+
+        conversation.restore_tool_output_artifact(
+          tool_name: tool_name,
+          content: content,
+          created_at: parse_time(record["timestamp"])
+        )
+      end
+    end
+
+    def tool_message_names_by_id(records)
+      records.each_with_object({}) do |record, names|
+        next unless record["type"] == "message"
+
+        message = record["message"]
+        next unless message.is_a?(Hash) && message_role(message) == "tool"
+
+        tool_call_id = message_tool_call_id(message).to_s
+        names[tool_call_id] = message_name(message) unless tool_call_id.empty? || message_name(message).to_s.empty?
+      end
+    end
+
+    def raw_tool_name(name)
+      {
+        "bash" => "run_shell_command",
+        "edit" => "edit_file",
+        "read" => "read_file",
+        "write" => "write_file"
+      }.fetch(name.to_s, name.to_s)
+    end
+
     def session_runtime(records, header)
       result = {
         "provider" => header["provider"],

data/lib/kward/session_tree_nodes.rb

@@ -0,0 +1,136 @@
+require_relative "message_access"
+require_relative "message_text"
+require_relative "tools/tool_call"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Shared traversal helpers for persisted session trees.
+  #
+  # Frontends own their final labels or payloads. This class owns only the
+  # frontend-neutral mechanics needed by both terminal and RPC tree views:
+  # active-path lookup, hidden tool-call-only assistant nodes, visible-node
+  # flattening, and assistant tool-call lookup by id.
+  class SessionTreeNodes
+    def initialize(roots:, current_leaf: nil)
+      @roots = roots
+      @current_leaf = current_leaf
+    end
+
+    def active_path
+      by_id = entries_by_id
+      ids = []
+      entry = by_id[@current_leaf.to_s]
+      seen = {}
+      while entry && !seen[entry["id"].to_s]
+        seen[entry["id"].to_s] = true
+        ids << entry["id"].to_s
+        entry = by_id[entry["parentId"].to_s]
+      end
+      ids
+    end
+
+    def visible_roots
+      @roots.flat_map { |root| visible_nodes(root) }
+    end
+
+    def contains_active_path?(node, active_path)
+      stack = [node]
+      seen = {}
+      until stack.empty?
+        current = stack.pop
+        next if seen[current.object_id]
+
+        seen[current.object_id] = true
+        entry_id = (current[:source]["entry"] || {})["id"].to_s
+        return true if active_path.include?(entry_id)
+
+        stack.concat(current[:children])
+      end
+      false
+    end
+
+    def tool_calls
+      @roots.each_with_object({}) do |root, calls|
+        stack = [root]
+        seen = {}
+        until stack.empty?
+          node = stack.pop
+          next if seen[node.object_id]
+
+          seen[node.object_id] = true
+          entry = node["entry"] || {}
+          message = entry["message"]
+          if entry["type"] == "message" && message.is_a?(Hash) && MessageAccess.role(message) == "assistant"
+            MessageAccess.tool_calls(message).each { |tool_call| calls[ToolCall.id(tool_call).to_s] = tool_call }
+          end
+          stack.concat(Array(node["children"]))
+        end
+      end
+    end
+
+    def self.truncate_text(text)
+      normalized = text.to_s.gsub(/\s+/, " ").strip
+      normalized.length > 120 ? "#{normalized.slice(0, 117)}..." : normalized
+    end
+
+    private
+
+    def visible_nodes(node)
+      results = {}
+      stack = [[node, false, {}]]
+
+      until stack.empty?
+        current, visited, seen = stack.pop
+        node_key = current.object_id
+        next if seen[node_key]
+
+        if visited
+          children = Array(current["children"]).flat_map { |child| results[child.object_id] || [] }
+          results[node_key] = if hidden_entry?(current["entry"] || {})
+                                children
+                              else
+                                [{ source: current, children: children }]
+                              end
+        else
+          branch_seen = seen.merge(node_key => true)
+          stack << [current, true, seen]
+          Array(current["children"]).reverse_each { |child| stack << [child, false, branch_seen] unless branch_seen[child.object_id] }
+        end
+      end
+
+      results[node.object_id] || []
+    end
+
+    def hidden_entry?(entry)
+      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) && MessageAccess.role(message) == "assistant"
+
+      content = MessageAccess.content(message)
+      content_tool_calls = content.is_a?(Array) && content.any? { |part| MessageAccess.value(part, :type) == "toolCall" }
+      (content_tool_calls && !text_content?(content)) || (!MessageAccess.tool_calls(message).empty? && MessageText.full_text(message).empty?)
+    end
+
+    def text_content?(content)
+      Array(content).any? { |part| MessageAccess.value(part, :type) == "text" && MessageAccess.value(part, :text).to_s.strip != "" }
+    end
+
+    def entries_by_id
+      @roots.each_with_object({}) do |root, map|
+        stack = [root]
+        seen = {}
+        until stack.empty?
+          node = stack.pop
+          next if seen[node.object_id]
+
+          seen[node.object_id] = true
+          entry = node["entry"] || {}
+          map[entry["id"].to_s] = entry unless entry["id"].to_s.empty?
+          stack.concat(Array(node["children"]))
+        end
+      end
+    end
+  end
+end

data/lib/kward/session_tree_renderer.rb

@@ -1,7 +1,7 @@
 require_relative "message_access"
 require_relative "message_text"
+require_relative "session_tree_nodes"
 require_relative "session_tree_tool_display"
-require_relative "tools/tool_call"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -13,13 +13,14 @@ module Kward
     end
 
     def items
-      active_path = session_tree_active_path(@roots, @current_leaf_id)
-      tool_calls_by_id = session_tree_tool_calls(@roots)
-      visible_roots = @roots.flat_map { |root| visible_session_tree_nodes(root) }
+      tree_nodes = SessionTreeNodes.new(roots: @roots, current_leaf: @current_leaf_id)
+      active_path = tree_nodes.active_path
+      tool_calls_by_id = tree_nodes.tool_calls
+      visible_roots = tree_nodes.visible_roots
       multiple_roots = visible_roots.length > 1
       result = []
 
-      stack = visible_roots.sort_by { |root| session_tree_contains_active_path?(root, active_path) ? 0 : 1 }.each_with_index.map do |root, index|
+      stack = visible_roots.sort_by { |root| tree_nodes.contains_active_path?(root, active_path) ? 0 : 1 }.each_with_index.map do |root, index|
         [root, multiple_roots ? 1 : 0, multiple_roots, multiple_roots, index == visible_roots.length - 1, [], multiple_roots]
       end.reverse
 
@@ -33,7 +34,7 @@ module Kward
           label: session_tree_label(entry, node[:source], prefix, active_path.include?(entry["id"].to_s), tool_calls_by_id)
         }
 
-        children = node[:children].sort_by { |child| session_tree_contains_active_path?(child, active_path) ? 0 : 1 }
+        children = node[:children].sort_by { |child| tree_nodes.contains_active_path?(child, active_path) ? 0 : 1 }
         multiple_children = children.length > 1
         child_indent = if multiple_children
                          indent + 1
@@ -55,52 +56,6 @@ module Kward
 
     private
 
-    def visible_session_tree_nodes(node)
-      results = {}
-      stack = [[node, false, {}]]
-
-      until stack.empty?
-        current, visited, seen = stack.pop
-        node_key = current.object_id
-        next if seen[node_key]
-
-        if visited
-          children = Array(current["children"]).flat_map { |child| results[child.object_id] || [] }
-          results[node_key] = if hidden_session_tree_entry?(current["entry"] || {})
-                                children
-                              else
-                                [{ source: current, children: children }]
-                              end
-        else
-          branch_seen = seen.merge(node_key => true)
-          stack << [current, true, seen]
-          Array(current["children"]).reverse_each { |child| stack << [child, false, branch_seen] unless branch_seen[child.object_id] }
-        end
-      end
-
-      results[node.object_id] || []
-    end
-
-    def hidden_session_tree_entry?(entry)
-      return false if @current_leaf_id && entry["id"].to_s == @current_leaf_id.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| session_tree_content_part_value(part, :type) == "toolCall" }
-      (content_tool_calls && !session_tree_text_content?(content)) || (!message_tool_calls(message).empty? && full_message_text(message).empty?)
-    end
-
-    def session_tree_text_content?(content)
-      Array(content).any? { |part| session_tree_content_part_value(part, :type) == "text" && session_tree_content_part_value(part, :text).to_s.strip != "" }
-    end
-
-    def session_tree_content_part_value(part, key)
-      MessageAccess.value(part, key)
-    end
-
     def session_tree_label(entry, node, prefix, active_path, tool_calls_by_id)
       label = node["label"] || entry["resolvedLabel"]
       label = label.to_s.strip
@@ -152,70 +107,6 @@ module Kward
       end.join
     end
 
-    def session_tree_contains_active_path?(node, active_path)
-      stack = [node]
-      seen = {}
-      until stack.empty?
-        current = stack.pop
-        next if seen[current.object_id]
-
-        seen[current.object_id] = true
-        entry_id = (current[:source]["entry"] || {})["id"].to_s
-        return true if active_path.include?(entry_id)
-
-        stack.concat(current[:children])
-      end
-      false
-    end
-
-    def session_tree_active_path(roots, leaf_id)
-      by_id = session_tree_entries_by_id(roots)
-      ids = []
-      entry = by_id[leaf_id.to_s]
-      seen = {}
-      while entry && !seen[entry["id"].to_s]
-        seen[entry["id"].to_s] = true
-        ids << entry["id"].to_s
-        entry = by_id[entry["parentId"].to_s]
-      end
-      ids
-    end
-
-    def session_tree_entries_by_id(roots)
-      roots.each_with_object({}) do |root, map|
-        stack = [root]
-        seen = {}
-        until stack.empty?
-          node = stack.pop
-          next if seen[node.object_id]
-
-          seen[node.object_id] = true
-          entry = node["entry"] || {}
-          map[entry["id"].to_s] = entry unless entry["id"].to_s.empty?
-          stack.concat(Array(node["children"]))
-        end
-      end
-    end
-
-    def session_tree_tool_calls(roots)
-      roots.each_with_object({}) do |root, tool_calls|
-        stack = [root]
-        seen = {}
-        until stack.empty?
-          node = stack.pop
-          next if seen[node.object_id]
-
-          seen[node.object_id] = true
-          entry = node["entry"] || {}
-          message = entry["message"]
-          if entry["type"] == "message" && message.is_a?(Hash) && message_role(message) == "assistant"
-            message_tool_calls(message).each { |tool_call| tool_calls[tool_call_id(tool_call).to_s] = tool_call }
-          end
-          stack.concat(Array(node["children"]))
-        end
-      end
-    end
-
     def session_tree_tool_display(message, tool_calls_by_id)
       tool_call = tool_calls_by_id[session_tree_message_tool_call_id(message).to_s]
       return SessionTreeToolDisplay.label(tool_call) if tool_call
@@ -233,12 +124,11 @@ module Kward
     end
 
     def display_message_text(message)
-      truncate_session_tree_text(full_message_text(message))
+      SessionTreeNodes.truncate_text(full_message_text(message))
     end
 
     def truncate_session_tree_text(text)
-      normalized = text.to_s.gsub(/\s+/, " ").strip
-      normalized.length > 120 ? "#{normalized.slice(0, 117)}..." : normalized
+      SessionTreeNodes.truncate_text(text)
     end
 
     def full_message_text(message)
@@ -249,10 +139,6 @@ module Kward
       MessageAccess.role(message)
     end
 
-    def message_content(message)
-      MessageAccess.content(message)
-    end
-
     def message_name(message)
       MessageAccess.name(message)
     end
@@ -261,13 +147,5 @@ module Kward
       MessageAccess.tool_call_id(message)
     end
 
-    def message_tool_calls(message)
-      MessageAccess.tool_calls(message)
-    end
-
-    def tool_call_id(tool_call)
-      ToolCall.id(tool_call)
-    end
-
   end
 end

data/lib/kward/tab_store.rb

@@ -0,0 +1,47 @@
+require "digest"
+require "json"
+require_relative "config_files"
+require_relative "private_file"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Persists the terminal UI's open session tabs per workspace.
+  class TabStore
+    def initialize(config_dir: ConfigFiles.config_dir, cwd: Dir.pwd)
+      @config_dir = config_dir
+      @cwd = File.expand_path(cwd)
+    end
+
+    def load
+      return { "session_paths" => [], "active_index" => 0 } unless File.file?(path)
+
+      data = JSON.parse(File.read(path))
+      paths = Array(data["session_paths"]).map(&:to_s).reject(&:empty?)
+      labels = Array(data["labels"]).map(&:to_s)
+      active_index = data["active_index"].to_i
+      { "session_paths" => paths, "labels" => labels, "active_index" => active_index }
+    rescue JSON::ParserError
+      { "session_paths" => [], "active_index" => 0 }
+    end
+
+    def save(session_paths:, active_index:, labels: [])
+      paths = Array(session_paths).map(&:to_s).reject(&:empty?)
+      PrivateFile.write_json(path, {
+        "cwd" => @cwd,
+        "session_paths" => paths,
+        "labels" => Array(labels).map(&:to_s),
+        "active_index" => [[active_index.to_i, 0].max, [paths.length - 1, 0].max].min
+      })
+    end
+
+    def path
+      File.join(@config_dir, "tabs", "#{workspace_key}.json")
+    end
+
+    private
+
+    def workspace_key
+      Digest::SHA256.hexdigest(@cwd)[0, 24]
+    end
+  end
+end

data/lib/kward/terminal_keys.rb

@@ -0,0 +1,84 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Terminal input key byte sequences grouped by semantic key.
+  module TerminalKeys
+    CTRL_SPACE = "\x00".freeze
+    CTRL_A = "\x01".freeze
+    CTRL_B = "\x02".freeze
+    CTRL_C = "\x03".freeze
+    CTRL_D = "\x04".freeze
+    CTRL_E = "\x05".freeze
+    CTRL_F = "\x06".freeze
+    CTRL_K = "\x0B".freeze
+    CTRL_L = "\x0C".freeze
+    CTRL_N = "\x0E".freeze
+    CTRL_P = "\x10".freeze
+    CTRL_Q = "\x11".freeze
+    CTRL_R = "\x12".freeze
+    CTRL_S = "\x13".freeze
+    CTRL_T = "\x14".freeze
+    CTRL_U = "\x15".freeze
+    CTRL_V = "\x16".freeze
+    CTRL_W = "\x17".freeze
+    CTRL_X = "\x18".freeze
+    CTRL_Y = "\x19".freeze
+    CTRL_Z = "\x1A".freeze
+
+    RETURN = ["\n", "\r"].freeze
+    BACKSPACE = ["\b", "\x7F"].freeze
+    TAB = ["\t", "\e[9u", "\e[9;1u", "\e[27;1;9~"].freeze
+
+    LEFT = ["\e[D", "\eOD"].freeze
+    RIGHT = ["\e[C", "\eOC"].freeze
+    UP = ["\e[A", "\eOA"].freeze
+    DOWN = ["\e[B", "\eOB"].freeze
+    HOME = ["\e[H", "\eOH", "\e[1~", "\e[7~"].freeze
+    END_KEY = ["\e[F", "\eOF", "\e[4~", "\e[8~"].freeze
+    DELETE = ["\e[3~"].freeze
+    PAGE_UP = ["\e[5~"].freeze
+    PAGE_DOWN = ["\e[6~"].freeze
+
+    SHIFT_TAB = ["\e[Z", "\e[1;2Z", "\e[9;2u", "\e[27;2;9~", "\e[1;2I"].freeze
+    CTRL_TAB = ["\e[9;5u", "\e[27;5;9~", "\e[1;5I"].freeze
+    CTRL_SHIFT_TAB = ["\e[9;6u", "\e[27;6;9~", "\e[1;6I", "\e[1;6Z"].freeze
+    SHIFT_ENTER = ["\e[13;2u", "\e[13;2~", "\e[27;2;13~", "\e\r", "\e\n"].freeze
+
+    ALT_LEFT = ["\e[1;3D", "\e[3D"].freeze
+    ALT_RIGHT = ["\e[1;3C", "\e[3C"].freeze
+    ALT_UP = ["\e[1;3A", "\e[3A"].freeze
+    ALT_DOWN = ["\e[1;3B", "\e[3B"].freeze
+
+    SHIFT_LEFT = ["\e[1;2D", "\e[2D"].freeze
+    SHIFT_RIGHT = ["\e[1;2C", "\e[2C"].freeze
+    SHIFT_UP = ["\e[1;2A", "\e[2A"].freeze
+    SHIFT_DOWN = ["\e[1;2B", "\e[2B"].freeze
+
+    CTRL_LEFT = ["\e[1;5D", "\e[5D"].freeze
+    CTRL_RIGHT = ["\e[1;5C", "\e[5C"].freeze
+    CTRL_UP = ["\e[1;5A", "\e[5A"].freeze
+    CTRL_DOWN = ["\e[1;5B", "\e[5B"].freeze
+
+    ALT_SHIFT_LEFT = ["\e[1;4D", "\e[4D"].freeze
+    ALT_SHIFT_RIGHT = ["\e[1;4C", "\e[4C"].freeze
+    ALT_SHIFT_UP = ["\e[1;4A", "\e[4A"].freeze
+    ALT_SHIFT_DOWN = ["\e[1;4B", "\e[4B"].freeze
+
+    CTRL_SHIFT_RIGHT = ["\e[1;6C", "\e[6C"].freeze
+    CTRL_SHIFT_UP = ["\e[1;6A", "\e[6A"].freeze
+    CTRL_SHIFT_DOWN = ["\e[1;6B", "\e[6B"].freeze
+
+    CTRL_T_CSI_U = "\e[116;5u".freeze
+    CTRL_W_CSI_U = "\e[119;5u".freeze
+    CTRL_NUMBER_TAB_PATTERN = /\A\e\[((?:49)|(?:5[0-7]));5u\z/.freeze
+
+    CSI_U_PATTERN = /\A\e\[(\d+)((?:;[\d:]*)*)u/.freeze
+    MODIFIED_CURSOR_PATTERN = /\A\e\[(\d+);(\d+)([CDFH])\z/.freeze
+    MODIFIED_DELETE_PATTERN = /\A\e\[3;(\d+)~\z/.freeze
+    UP_PATTERN = /\A\e\[[0-9;:]*A\z/.freeze
+    DOWN_PATTERN = /\A\e\[[0-9;:]*B\z/.freeze
+    RIGHT_PATTERN = /\A\e\[[0-9;:]*C\z/.freeze
+    LEFT_PATTERN = /\A\e\[[0-9;:]*D\z/.freeze
+    CSI_KEY_PATTERN = /\A\e\[[0-9;:]*[A-Za-z~]/.freeze
+    SS3_KEY_PATTERN = /\A\eO[A-Za-z]/.freeze
+  end
+end

data/lib/kward/terminal_sequences.rb

@@ -0,0 +1,42 @@
+require "base64"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Terminal control escape sequence builders.
+  module TerminalSequences
+    KEYBOARD_PROTOCOL_ENABLE = "\e[>25u".freeze
+    KEYBOARD_PROTOCOL_RESTORE = "\e[<u".freeze
+    BRACKETED_PASTE_ENABLE = "\e[?2004h".freeze
+    BRACKETED_PASTE_RESTORE = "\e[?2004l".freeze
+    BRACKETED_PASTE_START = "\e[200~".freeze
+    BRACKETED_PASTE_END = "\e[201~".freeze
+    SYNCHRONIZED_OUTPUT_ENABLE = "\e[?2026h".freeze
+    SYNCHRONIZED_OUTPUT_DISABLE = "\e[?2026l".freeze
+    CURSOR_SHOW = "\e[?25h".freeze
+    CURSOR_HIDE = "\e[?25l".freeze
+    CURSOR_SHAPE_DEFAULT = "\e[0 q".freeze
+    CURSOR_SHAPE_BAR = "\e[6 q".freeze
+    MOUSE_REPORTING_ENABLE = "\e[?1003h\e[?1006h".freeze
+    MOUSE_REPORTING_DISABLE = "\e[?1006l\e[?1003l".freeze
+    SGR_INVERSE = "\e[7m".freeze
+    SGR_INVERSE_OFF = "\e[27m".freeze
+
+    module_function
+
+    def scroll_region(top, bottom)
+      "\e[#{top};#{bottom}r"
+    end
+
+    def restore_scroll_region
+      "\e[r"
+    end
+
+    def move_to(row, col)
+      "\e[#{row};#{col}H"
+    end
+
+    def osc52(text)
+      "\e]52;c;#{Base64.strict_encode64(text.to_s)}\a"
+    end
+  end
+end

data/lib/kward/text_boundary.rb

@@ -0,0 +1,25 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Small text navigation helpers shared by composer and editor buffers.
+  module TextBoundary
+    module_function
+
+    def previous_word_boundary(text, index)
+      cursor = index.to_i
+      cursor -= 1 while cursor.positive? && word_separator?(text[cursor - 1])
+      cursor -= 1 while cursor.positive? && !word_separator?(text[cursor - 1])
+      cursor
+    end
+
+    def next_word_boundary(text, index)
+      cursor = index.to_i
+      cursor += 1 while cursor < text.length && word_separator?(text[cursor])
+      cursor += 1 while cursor < text.length && !word_separator?(text[cursor])
+      cursor
+    end
+
+    def word_separator?(char)
+      char.to_s.match?(/\s/)
+    end
+  end
+end

data/lib/kward/tools/context_budget_stats.rb

@@ -0,0 +1,54 @@
+require_relative "base"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Model-callable tool wrappers and their argument schemas.
+  module Tools
+    # Reports approximate context budget savings for the current process.
+    class ContextBudgetStats < Base
+      def initialize(context_budget_meter: nil)
+        @context_budget_meter = context_budget_meter
+        super(
+          "context_budget_stats",
+          "Return approximate per-session context budget savings from tool output compaction and deduplication.",
+          properties: {},
+          required: []
+        )
+      end
+
+      def call(_args, conversation, cancellation: nil)
+        cancellation&.raise_if_cancelled!
+        meter = conversation.respond_to?(:context_budget_meter) ? conversation.context_budget_meter : @context_budget_meter
+        return "Error: context budget stats are unavailable" unless meter
+
+        snapshot = meter.snapshot
+        lines = [
+          "# Context budget stats",
+          "- Calls: #{snapshot.calls}",
+          "- Original bytes: #{snapshot.original_bytes}",
+          "- Returned bytes: #{snapshot.returned_bytes}",
+          "- Saved bytes: #{snapshot.saved_bytes}",
+          "- Estimated tokens saved: #{estimated_tokens(snapshot.saved_bytes)}"
+        ]
+        lines.concat(tool_breakdown_lines(snapshot.tool_breakdown))
+        lines.join("\n")
+      end
+
+      private
+
+      def tool_breakdown_lines(tool_breakdown)
+        return [] if tool_breakdown.empty?
+
+        lines = ["", "## By tool"]
+        tool_breakdown.sort_by { |tool, data| [-data[:savedBytes], tool] }.each do |tool, data|
+          lines << "- #{tool}: #{data[:calls]} call(s), #{data[:savedBytes]} bytes saved, #{data[:returnedBytes]}/#{data[:originalBytes]} bytes returned"
+        end
+        lines
+      end
+
+      def estimated_tokens(bytes)
+        (bytes.to_i / 4.0).ceil
+      end
+    end
+  end
+end