kward 0.70.0 → 0.72.0

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/telemetry/logger.rb

@@ -8,13 +8,14 @@ require_relative "../rpc/redactor"
 module Kward
   # Append-only JSONL telemetry logger with secret-conscious error payloads.
   class TelemetryLogger
-    CATEGORIES = %w[tokens performance tools errors].freeze
+    CATEGORIES = %w[tokens performance tools errors compaction].freeze
     ENV_KEYS = {
       "enabled" => "KWARD_LOGGING",
       "tokens" => "KWARD_LOGGING_TOKENS",
       "performance" => "KWARD_LOGGING_PERFORMANCE",
       "tools" => "KWARD_LOGGING_TOOLS",
-      "errors" => "KWARD_LOGGING_ERRORS"
+      "errors" => "KWARD_LOGGING_ERRORS",
+      "compaction" => "KWARD_LOGGING_COMPACTION"
     }.freeze
     DEFAULT_MAX_BYTES = 10 * 1024 * 1024
 
@@ -101,7 +102,8 @@ module Kward
         "tokens" => truthy?(logging["tokens"]),
         "performance" => truthy?(logging["performance"]),
         "tools" => truthy?(logging["tools"]),
-        "errors" => truthy?(logging["errors"])
+        "errors" => truthy?(logging["errors"]),
+        "compaction" => truthy?(logging["compaction"])
       }
     rescue StandardError
       CATEGORIES.each_with_object({ "enabled" => false }) { |category, result| result[category] = false }

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/tool_output_compactor.rb

@@ -0,0 +1,127 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Deterministically trims large tool outputs before they are appended to the
+  # model-facing transcript.
+  #
+  # The original output is still handed to session/tool-execution persistence by
+  # ToolRegistry; this object only decides what the next model call sees. Keep it
+  # conservative: small outputs and short errors are more valuable verbatim than
+  # compacted.
+  class ToolOutputCompactor
+    MIN_BYTES = 12 * 1024
+    ERROR_OUTPUT_MAX_BYTES = 8 * 1024
+    HEAD_LINES = 40
+    TAIL_LINES = 40
+    ERROR_CONTEXT_LINES = 2
+
+    ERROR_PATTERN = /\b(error|fatal|failed|failure|exception|traceback|panic|segmentation fault|assertion)\b/i.freeze
+    TEST_PATTERN = /(^\s*\d+\)\s|\b(\d+\s+(tests?|examples?|runs?|assertions?|failures?|errors?|skips?)|finished in|failures?:|seed\s+\d+)\b)/i.freeze
+    SEARCH_PATTERN = /(^\#{1,6}\s+\S+|^[-*]\s+\S+|\S+:\d+:|https?:\/\/\S+)/.freeze
+
+    def compact(tool_name, content, artifact_id: nil)
+      text = normalize(content)
+      return text unless text.bytesize > MIN_BYTES
+      return text if error_output?(text) && text.bytesize <= ERROR_OUTPUT_MAX_BYTES
+
+      compacted = tool_name.to_s == "run_shell_command" ? compact_shell_output(text) : compact_lines(text)
+      return text if compacted == text
+      return text if compacted.bytesize >= text.bytesize
+
+      artifact_id = yield if artifact_id.nil? && block_given?
+      header = compacted_header(tool_name, text, compacted, artifact_id: artifact_id)
+      candidate = "#{header}\n\n#{compacted}"
+      candidate.bytesize < text.bytesize ? candidate : text
+    end
+
+    private
+
+    def normalize(content)
+      return content unless content.is_a?(String)
+
+      Conversation.normalize_tool_content(content)
+    end
+
+    def error_output?(text)
+      text.match?(ERROR_PATTERN)
+    end
+
+    def compact_shell_output(text)
+      sections = shell_sections(text)
+      return compact_lines(text) if sections.empty?
+
+      sections.map do |heading, body|
+        next heading if body.empty?
+
+        "#{heading}\n#{compact_lines(body)}"
+      end.join("\n")
+    end
+
+    def shell_sections(text)
+      parts = text.split(/\n(?=STDOUT:\n|STDERR:\n)/)
+      return [] if parts.length < 2
+
+      parts.map do |part|
+        heading, body = part.split("\n", 2)
+        [heading, body.to_s]
+      end
+    end
+
+    def compact_lines(text)
+      lines = text.split("\n", -1)
+      selected = selected_line_indexes(lines)
+      return text if selected.length >= lines.length
+
+      render_selected_lines(lines, selected)
+    end
+
+    def selected_line_indexes(lines)
+      indexes = []
+      indexes.concat((0...[HEAD_LINES, lines.length].min).to_a)
+      indexes.concat(priority_context_indexes(lines))
+
+      tail_start = [lines.length - TAIL_LINES, 0].max
+      indexes.concat((tail_start...lines.length).to_a)
+      indexes.uniq.sort
+    end
+
+    def priority_context_indexes(lines)
+      indexes = []
+      lines.each_with_index do |line, index|
+        next unless line.match?(ERROR_PATTERN) || line.match?(TEST_PATTERN) || line.match?(SEARCH_PATTERN)
+
+        first = [index - ERROR_CONTEXT_LINES, 0].max
+        last = [index + ERROR_CONTEXT_LINES, lines.length - 1].min
+        indexes.concat((first..last).to_a)
+      end
+      indexes
+    end
+
+    def render_selected_lines(lines, selected)
+      output = []
+      previous = nil
+      selected.each do |index|
+        if previous && index > previous + 1
+          output << "[... omitted lines #{previous + 2}-#{index} ...]"
+        end
+        output << lines[index]
+        previous = index
+      end
+      output.join("\n")
+    end
+
+    def compacted_header(tool_name, original, compacted, artifact_id: nil)
+      [
+        "[Tool output compacted by Kward: #{original.bytesize} bytes -> #{compacted.bytesize} bytes]",
+        "Tool: #{tool_name}",
+        "Preserved first #{HEAD_LINES} lines, last #{TAIL_LINES} lines, and error/failure/search context.",
+        retrieval_instruction(artifact_id)
+      ].join("\n")
+    end
+
+    def retrieval_instruction(artifact_id)
+      return "Full output is retained outside model context." if artifact_id.to_s.empty?
+
+      "Full output id: #{artifact_id}. Use retrieve_tool_output to inspect it."
+    end
+  end
+end

data/lib/kward/tools/base.rb

@@ -24,8 +24,8 @@ module Kward
             description: @description,
             parameters: {
               type: "object",
-              properties: @properties,
-              required: @required,
+              properties: sorted_properties,
+              required: @required.sort,
               additionalProperties: false
             }
           }
@@ -34,6 +34,12 @@ module Kward
 
       private
 
+      def sorted_properties
+        @properties.keys.sort_by(&:to_s).each_with_object({}) do |key, result|
+          result[key] = @properties[key]
+        end
+      end
+
       # Reads a tool argument while accepting symbol or string keys from restored calls.
       def argument(args, key, default = nil)
         return args[key] if args.key?(key)

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