kward 0.67.0 → 0.68.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/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

@@ -13,15 +13,42 @@ require_relative "search/web"
 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
 
+    # 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 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)
       @workspace = workspace
       @prompt = prompt
@@ -37,6 +64,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

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
@@ -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,6 +713,7 @@ 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)
 

data/lib/kward/tools/tool_call.rb

@@ -1,6 +1,14 @@
 require "json"
+require_relative "../message_access"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Reads and normalizes model tool-call hashes.
+  #
+  # Tool calls arrive from several providers and may be restored from session
+  # files. This module keeps provider/string/symbol compatibility in one place
+  # and exposes small helpers used by the agent loop, tool registry, transcript
+  # formatters, and RPC event normalizers.
   module ToolCall
     TOOL_NAME_MAP = {
       "read_file" => "read",
@@ -8,6 +16,7 @@ module Kward
       "write_file" => "write",
       "run_shell_command" => "bash",
       "list_directory" => "list_directory",
+      "code_search" => "code_search",
       "web_search" => "web_search",
       "read_skill" => "read_skill",
       "ask_user_question" => "ask_user_question"
@@ -15,19 +24,27 @@ module Kward
 
     module_function
 
+    # @return [String, nil] provider tool-call id
     def id(tool_call)
       value(tool_call, :id)
     end
 
+    # @return [String, nil] requested tool/function name
     def name(tool_call)
       value(function(tool_call), :name)
     end
 
+    # Returns the short name used in compact UI labels.
+    #
+    # @return [String] display label such as `read`, `edit`, or `bash`
     def display_name(tool_call)
       raw_name = name(tool_call)
       normalized_name(raw_name) || raw_name || "unknown_tool"
     end
 
+    # Parses the requested tool arguments.
+    #
+    # @return [Hash] decoded argument object, or an empty hash for invalid JSON
     def arguments(tool_call)
       parse_arguments(raw_arguments(tool_call))
     end
@@ -44,6 +61,10 @@ module Kward
       TOOL_NAME_MAP[name.to_s]
     end
 
+    # Converts provider argument payloads into hashes.
+    #
+    # Providers normally send JSON strings, while tests and compatibility callers
+    # may pass hashes directly.
     def parse_arguments(arguments)
       return {} if arguments.nil? || (arguments.respond_to?(:empty?) && arguments.empty?)
       return arguments if arguments.is_a?(Hash)
@@ -53,6 +74,9 @@ module Kward
       {}
     end
 
+    # Recursively converts snake_case hash keys to camelCase symbols.
+    #
+    # @return [Hash] camelized copy of `args`
     def camelize_args(args)
       return {} unless args.is_a?(Hash)
 
@@ -62,11 +86,7 @@ module Kward
     end
 
     def value(object, key)
-      return nil unless object.respond_to?(:key?)
-      return object[key] if object.key?(key)
-      return object[key.to_s] if object.key?(key.to_s)
-
-      nil
+      MessageAccess.value(object, key)
     end
 
     def camelize_value(item)

data/lib/kward/tools/web_search.rb

@@ -1,8 +1,13 @@
 require_relative "base"
+require_relative "search/web"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Model-callable tool wrappers and their argument schemas.
   module Tools
+    # Live web-search implementation with provider fallbacks.
     class WebSearch < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(web_search:)
         @web_search = web_search
         super(
@@ -22,7 +27,7 @@ module Kward
             },
             provider: {
               type: "string",
-              enum: %w[auto exa perplexity gemini legacy duckduckgo],
+              enum: Kward::WebSearch::PROVIDERS,
               description: "Provider override; default auto."
             },
             recency_filter: {
@@ -40,6 +45,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         @web_search.search(args)
       end

data/lib/kward/tools/write_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 guarded full-file writes.
     class WriteFile < Base
+      # Builds the tool schema and stores the execution dependency.
       def initialize(workspace:)
         @workspace = workspace
         super(
@@ -16,6 +20,7 @@ module Kward
         )
       end
 
+      # Executes the tool and returns model-facing output text.
       def call(args, conversation, cancellation: nil)
         path = argument(args, :path, "")
         content = argument(args, :content, "")

data/lib/kward/transcript_export.rb

@@ -1,7 +1,9 @@
 require "cgi"
 require_relative "markdown_transcript"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Serializes conversations for transcript export formats.
   class TranscriptExport
     SUPPORTED_FORMATS = ["markdown", "html"].freeze
 

data/lib/kward/version.rb

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