kward 0.68.0 → 0.69.0

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)
@@ -722,6 +757,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 +770,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/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

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

@@ -0,0 +1,202 @@
+require "nokogiri"
+require "uri"
+require_relative "web"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Fetches specific web resources for agent research workflows.
+  class WebFetch
+    DEFAULT_MAX_BYTES = 16 * 1024
+    MAX_MAX_BYTES = 128 * 1024
+    MAX_REDIRECTS = 5
+    HTTP_TIMEOUT_SECONDS = 10
+
+    # Creates a fetcher for web content and raw resources.
+    def initialize(http_client: WebSearch::NetHttpClient.new)
+      @http_client = http_client
+    end
+
+    # Fetches a URL and extracts readable text for human-facing pages.
+    def fetch_content(args)
+      url = args_value(args, "url").to_s.strip
+      return "Error: url is required" if url.empty?
+
+      max_bytes = bounded_max_bytes(args_value(args, "max_bytes") || args_value(args, "maxBytes"))
+      extract = normalize_extract(args_value(args, "extract") || "auto")
+      return "Error: extract must be one of: auto, text, markdown" unless extract
+
+      response = fetch_url(url, max_bytes: max_bytes)
+      return response if response.is_a?(String)
+
+      body = response[:body].to_s
+      content_type = header_value(response[:headers], "content-type")
+      text = extract_readable_text(body, content_type: content_type, mode: extract)
+      text = truncate_bytes(text, max_bytes)
+
+      [
+        "# Fetched content",
+        "- URL: #{response[:url]}",
+        "- Content type: #{content_type.empty? ? "unknown" : content_type}",
+        "- Bytes returned: #{text.bytesize}",
+        "",
+        text.empty? ? "(No readable text extracted.)" : text
+      ].join("\n")
+    rescue StandardError => e
+      "Error: fetch_content failed: #{e.message}"
+    end
+
+    # Fetches a URL and returns bounded raw response content.
+    def fetch_raw(args)
+      url = args_value(args, "url").to_s.strip
+      return "Error: url is required" if url.empty?
+
+      max_bytes = bounded_max_bytes(args_value(args, "max_bytes") || args_value(args, "maxBytes"))
+      accept = args_value(args, "accept").to_s.strip
+      response = fetch_url(url, max_bytes: max_bytes, accept: accept.empty? ? "*/*" : accept)
+      return response if response.is_a?(String)
+
+      body = truncate_bytes(response[:body].to_s, max_bytes)
+      content_type = header_value(response[:headers], "content-type")
+      [
+        "# Fetched raw content",
+        "- URL: #{response[:url]}",
+        "- Content type: #{content_type.empty? ? "unknown" : content_type}",
+        "- Bytes returned: #{body.bytesize}",
+        "",
+        body
+      ].join("\n")
+    rescue StandardError => e
+      "Error: fetch_raw failed: #{e.message}"
+    end
+
+    private
+
+    def fetch_url(url, max_bytes:, accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8")
+      current_url = normalize_url(url)
+      redirects = 0
+
+      loop do
+        response = @http_client.get(current_url, headers: browser_headers(accept))
+        code = response.code.to_i
+        headers = response_headers(response)
+
+        if redirect?(code)
+          return "Error: too many redirects" if redirects >= MAX_REDIRECTS
+
+          location = header_value(headers, "location")
+          return "Error: redirect missing Location header" if location.empty?
+
+          current_url = normalize_url(URI.join(current_url, location).to_s)
+          redirects += 1
+          next
+        end
+
+        return "Error: fetch failed with HTTP #{response.code}" unless code.between?(200, 299)
+
+        body = response.body.to_s
+        body = truncate_bytes(body, max_bytes)
+        return { url: current_url, headers: headers, body: body }
+      end
+    end
+
+    def normalize_url(value)
+      uri = URI.parse(value.to_s.strip)
+      raise "url must use http or https" unless %w[http https].include?(uri.scheme)
+      raise "url host is required" if uri.host.to_s.empty?
+
+      uri.to_s
+    rescue URI::InvalidURIError
+      raise "invalid url"
+    end
+
+    def response_headers(response)
+      return {} unless response.respond_to?(:headers) && response.headers.is_a?(Hash)
+
+      response.headers.transform_keys { |key| key.to_s.downcase }
+    end
+
+    def header_value(headers, key)
+      headers[key.to_s.downcase].to_s
+    end
+
+    def redirect?(code)
+      [301, 302, 303, 307, 308].include?(code)
+    end
+
+    def bounded_max_bytes(value)
+      number = value.to_i
+      number = DEFAULT_MAX_BYTES if number <= 0
+      [number, MAX_MAX_BYTES].min
+    end
+
+    def normalize_extract(value)
+      normalized = value.to_s.strip.downcase
+      %w[auto text markdown].include?(normalized) ? normalized : nil
+    end
+
+    def extract_readable_text(body, content_type:, mode:)
+      return clean_text(body) if mode == "text" || !html_content?(content_type, body)
+
+      document = Nokogiri::HTML(body)
+      document.css("script, style, noscript, svg, nav, footer, form").remove
+      title = document.at_css("title")&.text.to_s.strip
+      root = document.at_css("article") || document.at_css("main") || document.at_css("body") || document
+      parts = []
+      parts << "# #{clean_text(title)}" unless title.empty?
+      root.css("h1, h2, h3, h4, h5, h6, p, li, pre, code, blockquote").each do |node|
+        text = clean_text(node.text)
+        next if text.empty?
+
+        parts << format_html_node(node, text, mode: mode)
+      end
+      parts.uniq.join("\n\n")
+    end
+
+    def html_content?(content_type, body)
+      content_type.to_s.include?("html") || body.to_s.lstrip.start_with?("<!DOCTYPE html", "<html", "<HTML")
+    end
+
+    def format_html_node(node, text, mode:)
+      return text if mode == "text"
+
+      case node.name
+      when /^h([1-6])$/
+        "#{"#" * Regexp.last_match(1).to_i} #{text}"
+      when "li"
+        "- #{text}"
+      when "pre", "code"
+        "```\n#{text}\n```"
+      when "blockquote"
+        "> #{text}"
+      else
+        text
+      end
+    end
+
+    def clean_text(text)
+      text.to_s.gsub(/\s+/, " ").strip
+    end
+
+    def truncate_bytes(text, max_bytes)
+      return text if text.bytesize <= max_bytes
+
+      "#{text.byteslice(0, max_bytes).to_s.scrub}\n... truncated to #{max_bytes} bytes"
+    end
+
+    def browser_headers(accept)
+      {
+        "Accept" => accept,
+        "Accept-Language" => "en-US,en;q=0.9",
+        "User-Agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
+      }
+    end
+
+    def args_value(args, key)
+      return nil unless args.is_a?(Hash)
+      return args[key] if args.key?(key)
+      return args[key.to_sym] if args.key?(key.to_sym)
+
+      nil
+    end
+  end
+end

data/lib/kward/tools/tool_call.rb

@@ -18,6 +18,8 @@ module Kward
       "list_directory" => "list_directory",
       "code_search" => "code_search",
       "web_search" => "web_search",
+      "fetch_content" => "fetch_content",
+      "fetch_raw" => "fetch_raw",
       "read_skill" => "read_skill",
       "ask_user_question" => "ask_user_question"
     }.freeze

data/lib/kward/version.rb

@@ -1,5 +1,5 @@
 # Namespace for the Kward CLI agent runtime.
 module Kward
   # Current gem version.
-  VERSION = "0.68.0"
+  VERSION = "0.69.0"
 end