kward 0.67.1 → 0.69.0

data/lib/kward/tools/ask_user_question.rb

@@ -1,8 +1,13 @@
+require_relative "../question_contract"
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for structured clarification questions to the user.
     class AskUserQuestion < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(prompt:)
         @prompt = prompt
         super(
@@ -42,6 +47,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         return "Error: ask_user_question requires interactive prompt support." unless @prompt.respond_to?(:ask_user_question)
 
@@ -67,40 +73,22 @@ module Kward
       end
 
       def validated_questions(args)
-        questions = argument(args, :questions)
-        return "Error: ask_user_question requires questions." unless questions.is_a?(Array)
-        return "Error: ask_user_question requires 1 to 4 questions." unless questions.length.between?(1, 4)
-
-        questions.map.with_index(1) do |question, index|
-          return "Error: question #{index} must be an object." unless question.respond_to?(:key?)
-          return "Error: question #{index} uses unsupported multiSelect." if question.key?("multiSelect") || question.key?(:multiSelect)
-
-          text = question_value(question, :question).to_s.strip
-          header = question_value(question, :header).to_s.strip
-          options = question_value(question, :options)
-          return "Error: question #{index} requires question and header." if text.empty? || header.empty?
-          return "Error: question #{index} requires 2 to 4 options." unless options.is_a?(Array) && options.length.between?(2, 4)
-
-          normalized_options = options.map.with_index(1) do |option, option_index|
-            return "Error: question #{index} option #{option_index} must be an object." unless option.respond_to?(:key?)
-            return "Error: question #{index} option #{option_index} uses unsupported preview." if option.key?("preview") || option.key?(:preview)
-
-            label = question_value(option, :label).to_s.strip
-            description = question_value(option, :description).to_s.strip
-            return "Error: question #{index} option #{option_index} requires label and description." if label.empty? || description.empty?
-
-            { label: label, description: description }
-          end
-
-          { question: text, header: header, options: normalized_options }
-        end
+        QuestionContract.normalize_questions(argument(args, :questions))
+      rescue ArgumentError => e
+        "Error: #{tool_error_message(e.message)}."
       end
 
-      def question_value(object, key)
-        return object[key] if object.key?(key)
-        return object[key.to_s] if object.key?(key.to_s)
-
-        nil
+      def tool_error_message(message)
+        case message
+        when "questions must be an array"
+          "ask_user_question requires questions"
+        when "ui/question requires 1-4 questions"
+          "ask_user_question requires 1 to 4 questions"
+        else
+          message.gsub("2-4", "2 to 4")
+                 .gsub("multiSelect is unsupported", "uses unsupported multiSelect")
+                 .gsub("preview is unsupported", "uses unsupported preview")
+        end
       end
     end
   end

data/lib/kward/tools/base.rb

@@ -1,8 +1,13 @@
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Base class for model-callable tools and their JSON schemas.
     class Base
+      # @return [String] function name exposed to the model
       attr_reader :name
 
+      # Creates a tool schema definition shared by all concrete tool wrappers.
       def initialize(name, description, properties: {}, required: [])
         @name = name
         @description = description
@@ -10,6 +15,7 @@ module Kward
         @required = required
       end
 
+      # Returns the strict JSON schema advertised to model providers.
       def schema
         {
           type: "function",
@@ -28,6 +34,7 @@ module Kward
 
       private
 
+      # 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)
         return args[key.to_s] if args.key?(key.to_s)
@@ -35,6 +42,7 @@ module Kward
         default
       end
 
+      # Detects successful AGENTS.md writes so callers can refresh prompt context.
       def agents_file_changed?(workspace, path, result)
         result.to_s.start_with?("Wrote ", "Edited ") && File.basename(path.to_s) == "AGENTS.md" && workspace.resolved_path(path) == File.join(workspace.root.to_s, "AGENTS.md")
       rescue StandardError

data/lib/kward/tools/code_search.rb

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Package lookup and GitHub repository cache/search implementation.
     class CodeSearch < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(code_search:)
         @code_search = code_search
         super(
@@ -56,6 +60,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         cancellation&.raise_if_cancelled!
         @code_search.call(args)

data/lib/kward/tools/edit_file.rb

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for exact block replacement edits.
     class EditFile < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -28,6 +32,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, conversation, cancellation: nil)
         path = argument(args, :path, "")
         edits = argument(args, :edits, [])

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

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for listing workspace directory entries.
     class ListDirectory < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -13,6 +17,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         @workspace.list_directory(argument(args, :path, "."))
       end

data/lib/kward/tools/read_file.rb

@@ -1,8 +1,12 @@
 require_relative "base"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for bounded workspace file reads.
     class ReadFile < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -17,6 +21,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, conversation, cancellation: nil)
         path = argument(args, :path, "")
         offset = argument(args, :offset)

data/lib/kward/tools/read_skill.rb

@@ -1,9 +1,13 @@
 require_relative "base"
 require_relative "../config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for reading configured skill instructions.
     class ReadSkill < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize
         super(
           "read_skill",
@@ -16,6 +20,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         name = argument(args, :name, "")
         path = argument(args, :path)

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,22 +12,52 @@ 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"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Exposes local workspace, search, skill, and interaction tools to the model
-  # and dispatches approved tool calls into the active conversation.
+  # and dispatches tool calls into the active conversation.
+  #
+  # `ToolRegistry` is the boundary between model-requested function calls and
+  # Ruby tool objects. It owns schema exposure and transcript persistence for
+  # tool results; individual tools own validation and side effects. Keep frontend
+  # policy outside this class by passing dependencies such as `workspace` and
+  # `prompt` from CLI or RPC setup.
+  #
+  # A tool may exist in `@tools` but not be advertised in `schemas`. This allows
+  # restored transcripts or compatibility callers to dispatch known tools while
+  # config and frontend capability checks decide what the model can request next.
+  #
+  # Tool schemas are the strict output contract advertised to models and clients.
+  # Incoming calls are intentionally more tolerant: extra fields are ignored by
+  # individual tools, and legacy-compatible shapes are accepted where already
+  # supported. Required fields and invalid required values should still return
+  # explicit tool errors.
   class ToolRegistry
     # Tool schemas advertised to the model for the current frontend and config.
     #
-    # @return [Array<Hash>]
+    # @return [Array<Hash>] tool schemas currently advertised to the model
     attr_reader :schemas
 
-    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)
+    # Builds tool objects and the schema list for the current frontend/config.
+    #
+    # @param workspace [Workspace] filesystem/shell boundary used by local tools
+    # @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, 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
@@ -37,6 +69,10 @@ module Kward
     # Executes a model-requested tool call and appends the result to the
     # conversation transcript.
     #
+    # Unknown tools are recorded as tool results instead of raising. That keeps
+    # the conversation valid for the model and lets the assistant recover by
+    # choosing an advertised tool on the next turn.
+    #
     # @param tool_call [Hash] model tool call payload
     # @param conversation [Conversation] active conversation
     # @return [String] tool output content appended to the conversation
@@ -72,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
@@ -81,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/run_shell_command.rb

@@ -1,9 +1,13 @@
 require_relative "base"
 require_relative "../workspace"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Tool wrapper for bounded shell commands in the workspace.
     class RunShellCommand < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -17,6 +21,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         command = argument(args, :command, "")
         timeout_seconds = argument(args, :timeout_seconds, Workspace::DEFAULT_COMMAND_TIMEOUT_SECONDS)

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

@@ -7,7 +7,9 @@ require "pathname"
 require "uri"
 require_relative "../../config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Package lookup and GitHub repository cache/search implementation.
   class CodeSearch
     DEFAULT_MAX_RESULTS = 10
     MAX_MAX_RESULTS = 50
@@ -21,6 +23,7 @@ module Kward
     ECOSYSTEMS = %w[rubygems npm pypi crates go].freeze
     ACTIONS = %w[package_search github_search repo_clone repo_search repo_read list_cache refresh_cache clear_cache].freeze
 
+    # Creates an object for code search and repository cache operations.
     def initialize(cache_root: nil, http_client: NetHttpClient.new, git_runner: GitRunner.new, max_output_bytes: MAX_OUTPUT_BYTES)
       @cache_root = File.expand_path(cache_root || ConfigFiles.code_search_cache_dir)
       @http_client = http_client
@@ -46,6 +49,7 @@ module Kward
       "Error: code_search failed: #{redact(e.message)}"
     end
 
+    # HTTP adapter used by code search registry/package lookups.
     class NetHttpClient
       def get_json(url, headers: {})
         JSON.parse(get_text(url, headers: headers.merge("Accept" => "application/json")))
@@ -65,6 +69,7 @@ module Kward
       end
     end
 
+    # Git command adapter used by repository cache operations.
     class GitRunner
       def run(*args, chdir: nil)
         command = ["git", *args]
@@ -410,6 +415,7 @@ module Kward
       text[%r{https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:\.git)?}]
     end
 
+    # Returns GitHub API headers, including an optional token when configured.
     def github_headers
       token = ENV["GITHUB_TOKEN"] || ENV["GH_TOKEN"]
       token.to_s.empty? ? {} : { "Authorization" => "Bearer #{token}" }
@@ -422,6 +428,7 @@ module Kward
       nil
     end
 
+    # Returns a cache file path relative to the cloned repository root.
     def relative_path(root, path)
       Pathname.new(path).relative_path_from(Pathname.new(root)).to_s
     end

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

@@ -5,7 +5,9 @@ require "nokogiri"
 require "uri"
 require_relative "../../config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Live web-search implementation with provider fallbacks.
   class WebSearch
     DEFAULT_MAX_RESULTS = 5
     MAX_MAX_RESULTS = 20
@@ -27,11 +29,12 @@ module Kward
       "https://search.inetol.net",
       "https://searx.tiekoetter.com"
     ].freeze
-    PROVIDERS = %w[auto exa perplexity gemini legacy duckduckgo].freeze
+    PROVIDERS = %w[auto exa perplexity gemini duckduckgo].freeze
 
     Result = Struct.new(:title, :url, :excerpt, :provider, keyword_init: true)
     SearchResponse = Struct.new(:answer, :results, :provider, :note, keyword_init: true)
 
+    # Creates an object for web search provider operations.
     def initialize(http_client: NetHttpClient.new, searxng_instances: PUBLIC_SEARXNG_INSTANCES, max_output_bytes: MAX_OUTPUT_BYTES, config: nil)
       @http_client = http_client
       @searxng_instances = searxng_instances
@@ -61,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
 
@@ -92,8 +95,8 @@ module Kward
                        perplexity_search(query, options)
                      when "gemini"
                        gemini_search(query, options)
-                     when "legacy"
-                       legacy_search(query, options)
+                     when "duckduckgo"
+                       duckduckgo_provider_search(query, options)
                      end
           return [response, errors.empty? ? nil : errors.join("; ")] if successful_response?(response)
           errors << "#{provider}: no results"
@@ -105,6 +108,7 @@ module Kward
       [nil, errors.join("; ")]
     end
 
+    # Returns the configured provider fallback order for a query.
     def provider_order(provider)
       case provider
       when "auto"
@@ -113,10 +117,10 @@ module Kward
           order << "perplexity" if api_key("perplexity")
           order << "gemini" if api_key("gemini")
         end
-        order << "legacy"
+        order << "duckduckgo"
         order
       when "duckduckgo"
-        ["legacy"]
+        ["duckduckgo"]
       else
         [provider]
       end
@@ -352,15 +356,15 @@ module Kward
       SearchResponse.new(answer: answer, results: results, provider: "gemini")
     end
 
-    def legacy_search(query, options)
-      legacy_query = query_with_domain_filter(query, options[:domain_filter])
-      results, error = legacy_search_query(legacy_query, options[:max_results], options[:recency_filter])
+    def duckduckgo_provider_search(query, options)
+      duckduckgo_query = query_with_domain_filter(query, options[:domain_filter])
+      results, error = duckduckgo_provider_query(duckduckgo_query, options[:max_results], options[:recency_filter])
       raise error if results.empty? && error
 
-      SearchResponse.new(answer: "", results: results, provider: results.first&.provider || "legacy", note: error)
+      SearchResponse.new(answer: "", results: results, provider: results.first&.provider || "duckduckgo", note: error)
     end
 
-    def legacy_search_query(query, max_results, recency_filter)
+    def duckduckgo_provider_query(query, max_results, recency_filter)
       begin
         duckduckgo_results = duckduckgo_search(query, max_results, recency_filter)
         return [duckduckgo_results, nil] unless duckduckgo_results.empty?
@@ -576,6 +580,7 @@ module Kward
       text
     end
 
+    # Returns browser-like headers used for HTML search fallbacks.
     def browser_headers(accept)
       {
         "Accept" => accept,
@@ -604,19 +609,16 @@ module Kward
     end
 
     def web_config
-      value = config["web_search"] || config["webSearch"] || config["web_research"] || config["webResearch"] || {}
-      value.is_a?(Hash) ? value : {}
+      ConfigFiles.web_search_config(config)
     end
 
     def config_value(key)
       snake = key.to_s
       camel = snake.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
       prefixed = "web_search_#{snake}"
-      legacy_prefixed = "web_research_#{snake}"
       return web_config[snake] if web_config.key?(snake)
       return web_config[camel] if web_config.key?(camel)
       return config[prefixed] if config.key?(prefixed)
-      return config[legacy_prefixed] if config.key?(legacy_prefixed)
       return config[snake] if config.key?(snake)
       return config[camel] if config.key?(camel)
 
@@ -711,8 +713,9 @@ module Kward
       { "day" => "d", "week" => "w", "month" => "m", "year" => "y" }[filter]
     end
 
+    # 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)
@@ -739,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