kward 0.68.0 → 0.69.1

data/lib/kward/rpc/session_tree_rows.rb

@@ -34,7 +34,12 @@ module Kward
         multiple_roots = visible_roots.length > 1
         result = []
 
-        walk = lambda do |node, indent, just_branched, show_connector, is_last, gutters, virtual_root_child|
+        stack = visible_roots.sort_by { |root| tree_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
+
+        until stack.empty?
+          node, indent, just_branched, show_connector, is_last, gutters, virtual_root_child = stack.pop
           entry = node[:source]["entry"] || {}
           entry_id = entry["id"].to_s
           formatted = tree_entry_display(entry, tool_calls_by_id)
@@ -66,14 +71,10 @@ module Kward
                          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)
+          children.each_with_index.reverse_each do |child, index|
+            stack << [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
 
@@ -83,7 +84,9 @@ module Kward
         by_id = tree_entries_by_id(roots)
         ids = []
         current = by_id[leaf_id.to_s]
-        while current
+        seen = {}
+        while current && !seen[current["id"].to_s]
+          seen[current["id"].to_s] = true
           ids << current["id"].to_s
           current = by_id[current["parentId"].to_s]
         end
@@ -93,8 +96,12 @@ module Kward
       def 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"]))
@@ -103,10 +110,29 @@ module Kward
       end
 
       def visible_tree_nodes(node)
-        children = Array(node["children"]).flat_map { |child| visible_tree_nodes(child) }
-        return children if hidden_tree_entry?(node["entry"] || {})
+        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_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
 
-        [{ source: node, children: children }]
+        results[node.object_id] || []
       end
 
       def hidden_tree_entry?(entry)
@@ -126,15 +152,30 @@ module Kward
       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) }
+        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 tree_tool_calls(roots)
         roots.each_with_object({}) do |root, tool_calls_by_id|
           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"

data/lib/kward/rpc/transcript_normalizer.rb

@@ -61,6 +61,7 @@ module Kward
 
       def normalize_assistant_message(message)
         content = reasoning_first_content(normalize_content(ToolCall.value(message, :content), preserve_thinking: true))
+        content = response_item_content(message) if text_content_empty?(content)
         reasoning = normalize_reasoning_summary(message)
         content.unshift(reasoning) if reasoning && !thinking_content?(content)
         tool_calls(message).each do |tool_call|
@@ -154,6 +155,52 @@ module Kward
         summary.to_s.empty? ? nil : { type: "thinking", thinking: summary.to_s }
       end
 
+      def response_item_content(message)
+        response_items(message).filter_map do |item|
+          next unless item.is_a?(Hash)
+
+          case ToolCall.value(item, :type).to_s
+          when "reasoning"
+            thinking = reasoning_item_text(item)
+            { type: "thinking", thinking: thinking } unless thinking.empty?
+          when "message"
+            next if ToolCall.value(item, :phase).to_s == "commentary"
+
+            text = response_message_item_text(item)
+            { type: "text", text: text } unless text.empty?
+          end
+        end
+      end
+
+      def response_items(message)
+        items = ToolCall.value(message, :response_items) || ToolCall.value(message, :responseItems)
+        items.is_a?(Array) ? items : []
+      end
+
+      def reasoning_item_text(item)
+        summary = ToolCall.value(item, :summary)
+        content = ToolCall.value(item, :content)
+        response_text_parts(summary).empty? ? response_text_parts(content).join("\n\n") : response_text_parts(summary).join("\n\n")
+      end
+
+      def response_message_item_text(item)
+        response_text_parts(ToolCall.value(item, :content)).join
+      end
+
+      def response_text_parts(parts)
+        Array(parts).filter_map do |part|
+          next unless part.is_a?(Hash)
+
+          ToolCall.value(part, :text) || ToolCall.value(part, :refusal)
+        end.map(&:to_s)
+      end
+
+      def text_content_empty?(content)
+        Array(content).all? do |part|
+          !part.is_a?(Hash) || !["text", "thinking"].include?(ToolCall.value(part, :type).to_s) || ToolCall.value(part, :text).to_s.empty? && ToolCall.value(part, :thinking).to_s.empty?
+        end
+      end
+
       def thinking_content?(content)
         content.any? { |part| thinking_content_part?(part) }
       end

data/lib/kward/session_store.rb

@@ -1,4 +1,5 @@
 require "fileutils"
+require "digest"
 require "json"
 require "securerandom"
 require "time"
@@ -28,7 +29,7 @@ module Kward
     VERSION = 2
     LAST_SESSION_FILENAME = "last_session.json"
 
-    SessionInfo = Struct.new(:id, :path, :cwd, :created_at, :modified_at, :name, :first_message, :message_count, :parent_id, :parent_path, :depth, :is_last, :ancestor_continues, keyword_init: true)
+    SessionInfo = Struct.new(:id, :path, :cwd, :created_at, :modified_at, :name, :first_message, :message_count, :provider, :model, :reasoning_effort, :parent_id, :parent_path, :depth, :is_last, :ancestor_continues, keyword_init: true)
 
     # Live handle that attaches persistence callbacks to a conversation.
     #
@@ -77,6 +78,8 @@ module Kward
         conversation.on_compact = lambda { |message| compact(message) }
         conversation.on_tool_execution = lambda { |tool_call, content| append_tool_execution(tool_call, content) }
         conversation.on_runtime_update = lambda { |provider:, model:, reasoning_effort:| update_runtime(provider: provider, model: model, reasoning_effort: reasoning_effort) }
+        conversation.on_system_message_change = lambda { |system_message| append_system_prompt_snapshot(system_message, reason: "changed") }
+        append_system_prompt_snapshot(conversation.system_message, reason: "attach")
         self
       end
 
@@ -99,6 +102,11 @@ module Kward
         @store.append_record(@path, RPC::ToolEventNormalizer.new(tool_call, content: content).execution_record)
       end
 
+      # Persists the current system prompt as audit metadata when it changes.
+      def append_system_prompt_snapshot(system_message, reason: "changed")
+        @store.append_system_prompt_snapshot(@path, system_message, reason: reason)
+      end
+
       # Persists the session memory snapshot used when the session is restored.
       def update_memory_state(session_memories:, last_retrieval: nil)
         @store.append_record(@path, {
@@ -427,12 +435,39 @@ module Kward
       end
     end
 
+    def append_system_prompt_snapshot(path, system_message, reason: "changed")
+      content = MessageAccess.content(system_message).to_s
+      return if content.empty?
+      return if latest_system_prompt_hash(records_from_file(path)) == system_prompt_hash(content)
+
+      append_record(path, {
+        type: "system_prompt",
+        timestamp: Time.now.utc.iso8601(3),
+        reason: reason.to_s,
+        hash: system_prompt_hash(content),
+        content: content
+      })
+    end
+
     def self.safe_cwd(cwd)
       "--#{File.expand_path(cwd).sub(%r{\A[/\\]}, "").gsub(%r{[/\\:]}, "-")}--"
     end
 
     private
 
+    def latest_system_prompt_hash(records)
+      records.reverse_each do |record|
+        next unless record["type"] == "system_prompt"
+
+        return record["hash"].to_s unless record["hash"].to_s.empty?
+      end
+      nil
+    end
+
+    def system_prompt_hash(content)
+      "sha256:#{Digest::SHA256.hexdigest(content.to_s)}"
+    end
+
     def resolve_session_path(path)
       expanded = path.to_s.start_with?("~/") ? File.join(Dir.home, path.to_s[2..]) : path.to_s
       resolved = File.expand_path(expanded, @cwd)
@@ -557,7 +592,11 @@ module Kward
         next unless node
 
         parent = nodes[entry["parentId"].to_s]
-        parent ? parent["children"] << node : roots << node
+        if parent && !parent.equal?(node)
+          parent["children"] << node unless parent["children"].include?(node)
+        else
+          roots << node unless roots.include?(node)
+        end
       end
       roots
     end
@@ -722,6 +761,7 @@ module Kward
 
       messages = restored_messages(records)
       name = session_name(records)
+      runtime = session_runtime(records, header)
       first_message = messages.find { |message| ["user", "compactionSummary"].include?(message_role(message)) }
       stats = File.stat(path)
 
@@ -734,6 +774,9 @@ module Kward
         name: name,
         first_message: first_message ? message_text(first_message) : "",
         message_count: messages.count { |message| ["user", "assistant", "tool", "toolResult", "compactionSummary"].include?(message_role(message)) },
+        provider: runtime["provider"],
+        model: runtime["model"],
+        reasoning_effort: runtime["reasoningEffort"],
         parent_id: header["parentId"],
         parent_path: header["parentPath"],
         depth: 0,

data/lib/kward/session_tree_renderer.rb

@@ -19,7 +19,12 @@ module Kward
       multiple_roots = visible_roots.length > 1
       result = []
 
-      walk = lambda do |node, indent, just_branched, show_connector, is_last, gutters, virtual_root_child|
+      stack = visible_roots.sort_by { |root| session_tree_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
+
+      until stack.empty?
+        node, indent, just_branched, show_connector, is_last, gutters, virtual_root_child = stack.pop
         entry = node[:source]["entry"] || {}
         display_indent = multiple_roots ? [indent - 1, 0].max : indent
         prefix = session_tree_visual_prefix(display_indent, gutters, show_connector && !virtual_root_child, is_last, !node[:children].empty?)
@@ -40,25 +45,40 @@ module Kward
         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)
+        children.each_with_index.reverse_each do |child, index|
+          stack << [child, child_indent, multiple_children, multiple_children, index == children.length - 1, child_gutters, false]
         end
       end
 
-      visible_roots.sort_by { |root| session_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
 
     private
 
     def visible_session_tree_nodes(node)
-      children = Array(node["children"]).flat_map { |child| visible_session_tree_nodes(child) }
-      return children if hidden_session_tree_entry?(node["entry"] || {})
+      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
 
-      [{ source: node, children: children }]
+      results[node.object_id] || []
     end
 
     def hidden_session_tree_entry?(entry)
@@ -132,15 +152,28 @@ module Kward
     end
 
     def session_tree_contains_active_path?(node, active_path)
-      entry_id = (node[:source]["entry"] || {})["id"].to_s
-      active_path.include?(entry_id) || node[:children].any? { |child| session_tree_contains_active_path?(child, 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]
-      while entry
+      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
@@ -150,8 +183,12 @@ module Kward
     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"]))
@@ -162,8 +199,12 @@ module Kward
     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"

data/lib/kward/starter_pack_installer.rb

@@ -11,9 +11,9 @@ require_relative "config_files"
 module Kward
   # Installs Kward's starter prompt/instruction files into the user config dir.
   class StarterPackInstaller
-    VERSION = "v1.0.0"
+    VERSION = "v1.0.1"
     ARCHIVE_URL = "https://codeload.github.com/kaiwood/kward-starter-pack/tar.gz/refs/tags/#{VERSION}".freeze
-    ALLOWED_FILES = ["AGENTS.md"].freeze
+    ALLOWED_FILES = ["PRINCIPLES.md"].freeze
     ALLOWED_PREFIXES = ["prompts/", "skills/"].freeze
     Result = Struct.new(:installed, :skipped, keyword_init: true)
 

data/lib/kward/tools/fetch_content.rb

@@ -0,0 +1,41 @@
+require_relative "base"
+require_relative "search/web_fetch"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Model-callable tool wrappers and their argument schemas.
+  module Tools
+    # Fetches a specific URL and extracts readable page content.
+    class FetchContent < Base
+      # Builds the tool schema and stores the execution dependency.
+      def initialize(web_fetch:)
+        @web_fetch = web_fetch
+        super(
+          "fetch_content",
+          "Fetch a specific URL and extract readable bounded content.",
+          properties: {
+            url: {
+              type: "string",
+              description: "HTTP or HTTPS URL to fetch."
+            },
+            max_bytes: {
+              type: "integer",
+              description: "Maximum returned content bytes; default 16384, max 131072."
+            },
+            extract: {
+              type: "string",
+              enum: %w[auto text markdown],
+              description: "Extraction mode; default auto."
+            }
+          },
+          required: ["url"]
+        )
+      end
+
+      # Executes the tool and returns model-facing output text.
+      def call(args, _conversation, cancellation: nil)
+        @web_fetch.fetch_content(args)
+      end
+    end
+  end
+end

data/lib/kward/tools/fetch_raw.rb

@@ -0,0 +1,40 @@
+require_relative "base"
+require_relative "search/web_fetch"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Model-callable tool wrappers and their argument schemas.
+  module Tools
+    # Fetches bounded raw content from a specific URL.
+    class FetchRaw < Base
+      # Builds the tool schema and stores the execution dependency.
+      def initialize(web_fetch:)
+        @web_fetch = web_fetch
+        super(
+          "fetch_raw",
+          "Fetch bounded raw content from a specific URL.",
+          properties: {
+            url: {
+              type: "string",
+              description: "HTTP or HTTPS URL to fetch."
+            },
+            max_bytes: {
+              type: "integer",
+              description: "Maximum returned content bytes; default 16384, max 131072."
+            },
+            accept: {
+              type: "string",
+              description: "Optional HTTP Accept header."
+            }
+          },
+          required: ["url"]
+        )
+      end
+
+      # Executes the tool and returns model-facing output text.
+      def call(args, _conversation, cancellation: nil)
+        @web_fetch.fetch_raw(args)
+      end
+    end
+  end
+end

data/lib/kward/tools/registry.rb

@@ -2,6 +2,8 @@ require_relative "../config_files"
 require_relative "ask_user_question"
 require_relative "code_search"
 require_relative "edit_file"
+require_relative "fetch_content"
+require_relative "fetch_raw"
 require_relative "list_directory"
 require_relative "read_file"
 require_relative "read_skill"
@@ -10,6 +12,7 @@ require_relative "web_search"
 require_relative "write_file"
 require_relative "search/code"
 require_relative "search/web"
+require_relative "search/web_fetch"
 require_relative "tool_call"
 require_relative "../workspace"
 
@@ -45,14 +48,16 @@ module Kward
     # @param prompt [Object, nil] interactive prompt bridge; must implement
     #   `ask_user_question` before that tool is advertised
     # @param web_search [WebSearch] live web search implementation
+    # @param web_fetch [WebFetch] specific URL fetch implementation
     # @param code_search [CodeSearch] public source/package search implementation
     # @param web_search_enabled [Boolean, nil] override for web search exposure
     # @param skills [Array<ConfigFiles::Skill>, nil] override discovered skills
     # @param ask_user_question_enabled [Boolean, nil] override question exposure
-    def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil)
+    def initialize(workspace: Workspace.new, prompt: nil, web_search: WebSearch.new, web_fetch: WebFetch.new, code_search: CodeSearch.new, web_search_enabled: nil, skills: nil, ask_user_question_enabled: nil)
       @workspace = workspace
       @prompt = prompt
       @web_search = web_search
+      @web_fetch = web_fetch
       @code_search = code_search
       @skills = skills
       @web_search_enabled = web_search_enabled
@@ -103,7 +108,7 @@ module Kward
       tools = @tools.values_at(
         "list_directory", "read_file", "write_file", "edit_file", "run_shell_command", "code_search"
       )
-      tools << @tools["web_search"] if web_search_available?
+      tools.concat(@tools.values_at("web_search", "fetch_content", "fetch_raw")) if web_search_available?
       tools << @tools["read_skill"] if skills_available?
       tools << @tools["ask_user_question"] if ask_user_question_available?
       tools
@@ -112,6 +117,8 @@ module Kward
     def all_tools
       core_tools + [
         Tools::WebSearch.new(web_search: @web_search),
+        Tools::FetchContent.new(web_fetch: @web_fetch),
+        Tools::FetchRaw.new(web_fetch: @web_fetch),
         Tools::ReadSkill.new,
         Tools::AskUserQuestion.new(prompt: @prompt)
       ]

data/lib/kward/tools/search/web.rb

@@ -64,7 +64,7 @@ module Kward
         provider: provider
       }
 
-      sections = ["# Web search"]
+      sections = ["# Web search", "Use fetch_content with a result URL to verify human-readable pages, or fetch_raw for specs, JSON, YAML, XML, and other machine-readable resources."]
       failures = []
       any_results = false
 
@@ -715,7 +715,7 @@ module Kward
 
     # HTTP adapter used by web-search providers and fallbacks.
     class NetHttpClient
-      Response = Struct.new(:code, :body, keyword_init: true)
+      Response = Struct.new(:code, :body, :headers, keyword_init: true)
 
       def get(url, headers: {})
         request(url, Net::HTTP::Get, headers: headers)
@@ -742,7 +742,7 @@ module Kward
           headers.each { |key, value| http_request[key] = value }
           yield http_request if block_given?
           response = http.request(http_request)
-          Response.new(code: response.code, body: response.body)
+          Response.new(code: response.code, body: response.body, headers: response.each_header.to_h)
         end
       end
     end