kward 0.76.0 → 0.78.0

data/lib/kward/tools/base.rb

@@ -3,11 +3,22 @@ module Kward
   # Model-callable tool wrappers and their argument schemas.
   module Tools
     # Base class for model-callable tools and their JSON schemas.
+    #
+    # Concrete built-in tools initialize this class with their model-facing name,
+    # description, and strict argument schema, then implement `call` to perform
+    # the operation. Tool execution is coordinated by {Kward::ToolRegistry}.
+    #
+    # @api public
     class Base
       # @return [String] function name exposed to the model
       attr_reader :name
 
       # Creates a tool schema definition shared by all concrete tool wrappers.
+      #
+      # @param name [String] function name exposed to the model
+      # @param description [String] model-facing description of the operation
+      # @param properties [Hash] JSON Schema properties keyed by argument name
+      # @param required [Array<String, Symbol>] required argument names
       def initialize(name, description, properties: {}, required: [])
         @name = name
         @description = description
@@ -16,6 +27,9 @@ module Kward
       end
 
       # Returns the strict JSON schema advertised to model providers.
+      #
+      # @return [Hash] function schema with additional properties disabled
+      # @api public
       def schema
         {
           type: "function",

data/lib/kward/tools/code_search.rb

@@ -37,7 +37,11 @@ module Kward
             },
             path: {
               type: "string",
-              description: "Repo-relative path."
+              description: "Repo-relative path; inferred from GitHub blob URLs when omitted."
+            },
+            ref: {
+              type: "string",
+              description: "Git branch, tag, or commit; inferred from GitHub blob URLs when omitted."
             },
             start_line: {
               type: "integer",
@@ -63,7 +67,9 @@ module Kward
       # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         cancellation&.raise_if_cancelled!
-        @code_search.call(args)
+        return @code_search.call(args) unless cancellation
+
+        @code_search.call(args, cancellation: cancellation)
       end
     end
   end

data/lib/kward/tools/fetch_content.rb

@@ -12,7 +12,7 @@ module Kward
         @web_fetch = web_fetch
         super(
           "fetch_content",
-          "Fetch a specific URL and extract readable bounded content.",
+          "Fetch a specific URL and extract readable bounded content, including links and simple tables.",
           properties: {
             url: {
               type: "string",
@@ -34,7 +34,9 @@ module Kward
 
       # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
-        @web_fetch.fetch_content(args)
+        return @web_fetch.fetch_content(args) unless cancellation
+
+        @web_fetch.fetch_content(args, cancellation: cancellation)
       end
     end
   end

data/lib/kward/tools/fetch_raw.rb

@@ -33,7 +33,9 @@ module Kward
 
       # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
-        @web_fetch.fetch_raw(args)
+        return @web_fetch.fetch_raw(args) unless cancellation
+
+        @web_fetch.fetch_raw(args, cancellation: cancellation)
       end
     end
   end

data/lib/kward/tools/registry.rb

@@ -22,6 +22,7 @@ require_relative "search/web"
 require_relative "search/web_fetch"
 require_relative "tool_call"
 require_relative "../mcp/server_config"
+require_relative "../permissions/policy"
 require_relative "../telemetry/logger"
 require_relative "../tool_output_compactor"
 require_relative "../workspace"
@@ -46,11 +47,12 @@ module Kward
   # individual tools, and legacy-compatible shapes are accepted where already
   # supported. Required fields and invalid required values should still return
   # explicit tool errors.
+  # @api public
   class ToolRegistry
     # Tool schemas advertised to the model for the current frontend and config.
     #
     # @return [Array<Hash>] tool schemas currently advertised to the model
-    attr_reader :schemas, :writer_id
+    attr_reader :schemas
 
     # Builds tool objects and the schema list for the current frontend/config.
     #
@@ -63,7 +65,7 @@ module Kward
     # @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, allowed_tool_names: nil, write_lock: nil, writer_id: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, hook_manager: nil, hook_context: 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, allowed_tool_names: nil, tool_output_compactor: ToolOutputCompactor.new, telemetry_logger: TelemetryLogger.new, context_budget_meter: nil, mcp_clients: nil, tool_approval: nil, approval_for_allowed_tools: false, permission_policy: nil, hook_manager: nil, hook_context: nil)
       @workspace = workspace
       @prompt = prompt
       @web_search = web_search
@@ -73,12 +75,12 @@ module Kward
       @web_search_enabled = web_search_enabled
       @ask_user_question_enabled = ask_user_question_enabled
       @allowed_tool_names = allowed_tool_names&.map(&:to_s)
-      @write_lock = write_lock
-      @writer_id = writer_id
       @tool_output_compactor = tool_output_compactor
       @telemetry_logger = telemetry_logger
       @context_budget_meter = context_budget_meter
       @tool_approval = tool_approval
+      @approval_for_allowed_tools = approval_for_allowed_tools == true
+      @permission_policy = permission_policy || Permissions::Policy.from_config(ConfigFiles.read_config)
       @hook_manager = hook_manager
       @hook_context = hook_context
       @mcp_clients = if mcp_clients
@@ -115,12 +117,25 @@ module Kward
                              hook_denied_content(before_tool, "tool call denied: #{name}")
                            elsif before_tool.approval_required? && hook_approval_denied?(before_tool, tool_call, name, args, cancellation)
                              hook_denied_content(before_tool, "tool call approval denied: #{name}")
-                           elsif mutation_tool?(name) && !write_lock_owned?
-                             "Workspace write denied: another worker owns the write lock."
-                           elsif tool_approval_denied?(tool_call, name, args, cancellation)
-                             "Declined: tool execution denied by user: #{name}"
                            else
-                             execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
+                             permission_decision = @permission_policy.decision_for(name, args, source: source_for_tool(tool))
+                             if permission_decision.denied?
+                               "Declined: #{permission_decision.reason}: #{name}"
+                             elsif permission_decision.approval_required?
+                               approval = permission_approval_result(tool_call, name, args, cancellation)
+                               if approval == :allow_for_session
+                                 @permission_policy.allow_for_session!(name)
+                                 execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
+                               elsif approval == true
+                                 execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
+                               else
+                                 approval_denied_content(approval, name)
+                               end
+                             elsif @approval_for_allowed_tools && tool_approval_denied?(tool_call, name, args, cancellation)
+                               "Declined: tool execution denied by user: #{name}"
+                             else
+                               execute_tool_with_hooks(tool, name, args, tool_call, conversation, cancellation)
+                             end
                            end
                          else
                            "Unknown tool: #{name}"
@@ -148,6 +163,14 @@ module Kward
       model_content
     end
 
+    # Returns frontend discovery metadata for a tool name.
+    #
+    # Unknown names return metadata with an unknown source rather than raising,
+    # which lets RPC clients render restored or unsupported tool calls safely.
+    #
+    # @param name [String, #to_s] exposed tool name
+    # @return [Hash] source, display name, and optional MCP identity
+    # @api public
     def metadata_for(name)
       tool = @tools[name.to_s]
       return unknown_tool_metadata(name) unless tool
@@ -179,6 +202,8 @@ module Kward
 
     def source_for_tool(tool)
       case tool
+      when Tools::MCPTool
+        "mcp"
       when Tools::WebSearch, Tools::FetchContent, Tools::FetchRaw
         "web"
       when Tools::ReadSkill
@@ -415,20 +440,23 @@ module Kward
       (metadata[:source] || metadata["source"]).to_s == "mcp"
     end
 
-    def mutation_tool?(name)
-      ToolCall.write_lock_required?(name)
+    def permission_approval_result(tool_call, name, args, cancellation)
+      return false unless @tool_approval
+
+      @tool_approval.call(tool_call: tool_call, name: name, args: args, cancellation: cancellation)
     end
 
-    def tool_approval_denied?(tool_call, name, args, cancellation)
-      return false unless @tool_approval
+    def approval_denied_content(approval, name)
+      message = approval[:denied_message] if approval.is_a?(Hash)
+      return "Declined: #{message}" unless message.to_s.empty?
 
-      @tool_approval.call(tool_call: tool_call, name: name, args: args, cancellation: cancellation) == false
+      "Declined: tool execution denied by user: #{name}"
     end
 
-    def write_lock_owned?
-      return true unless @write_lock
+    def tool_approval_denied?(tool_call, name, args, cancellation)
+      return false unless @tool_approval
 
-      @write_lock.owned_by?(@writer_id)
+      @tool_approval.call(tool_call: tool_call, name: name, args: args, cancellation: cancellation) == false
     end
 
     def build_tools

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

@@ -1,4 +1,4 @@
-require "cgi"
+require "cgi/escape"
 require "fileutils"
 require "json"
 require "net/http"
@@ -33,7 +33,10 @@ module Kward
       @max_output_bytes = max_output_bytes
     end
 
-    def call(args)
+    def call(args = nil, cancellation: nil, **keyword_args)
+      args ||= keyword_args
+      cancellation&.raise_if_cancelled!
+      @cancellation = cancellation
       action = value(args, "action").to_s
       return "Error: action must be one of: #{ACTIONS.join(", ")}" unless ACTIONS.include?(action)
 
@@ -47,6 +50,8 @@ module Kward
       when "refresh_cache" then refresh_cache(args)
       when "clear_cache" then clear_cache(args)
       end
+    rescue Cancellation::CancelledError
+      raise
     rescue StandardError => e
       "Error: code_search failed: #{redact(e.message)}"
     end
@@ -129,13 +134,16 @@ module Kward
       query = value(args, "query").to_s
       return "Error: query is required" if query.strip.empty?
 
-      path, = ensure_repo(repo, refresh: false)
+      path, revision = synchronized_repo(repo, value(args, "ref") || repo[:requested_ref])
       max_results = bounded_max_results(value(args, "max_results"))
       context = bounded_integer(value(args, "context_lines"), DEFAULT_CONTEXT_LINES, 0, 5)
       matches = search_files(path, query, max_results: max_results, context_lines: context)
-      return "Error: no matches found in #{repo[:full_name]}" if matches.empty?
+      if matches.empty?
+        suffix = revision == "unknown" ? "" : " at #{revision}"
+        return "Error: no matches found in #{repo[:full_name]}#{suffix}"
+      end
 
-      lines = ["# Code search", "- Repository: #{repo[:full_name]}", "- Query: #{query}", ""]
+      lines = ["# Code search", "- Repository: #{repo[:full_name]}", "- Revision: #{revision}", "- Query: #{query}", ""]
       matches.each do |match|
         lines << "## #{match[:path]}:#{match[:line]}"
         lines << "```"
@@ -148,10 +156,10 @@ module Kward
     def repo_read(args)
       repo = require_repo(args)
       return repo if repo.is_a?(String)
-      file = value(args, "path") || value(args, "file")
+      file = value(args, "path") || value(args, "file") || repo[:requested_path]
       return "Error: path is required" if file.to_s.empty?
 
-      root, = ensure_repo(repo, refresh: false)
+      root, revision = synchronized_repo(repo, value(args, "ref") || repo[:requested_ref])
       target = safe_existing_path(root, file.to_s)
       return "Error: path is not a file: #{file}" unless File.file?(target)
       return "Error: file is too large: #{file}" if File.size(target) > MAX_FILE_BYTES
@@ -161,7 +169,7 @@ module Kward
       lines = File.readlines(target, chomp: true)
       selected = lines.drop(start_line - 1).first(line_count)
       numbered = selected.each_with_index.map { |line, index| "#{start_line + index}: #{line}" }
-      truncate((["# Code read", "- Repository: #{repo[:full_name]}", "- Path: #{file}", ""] + numbered).join("\n"))
+      truncate((["# Code read", "- Repository: #{repo[:full_name]}", "- Revision: #{revision}", "- Path: #{file}", ""] + numbered).join("\n"))
     rescue ArgumentError => e
       "Error: #{e.message}"
     end
@@ -231,10 +239,7 @@ module Kward
       path = cache_path(repo)
       FileUtils.mkdir_p(@cache_root, mode: 0o700)
       if Dir.exist?(File.join(path, ".git"))
-        if refresh
-          @git_runner.run("fetch", "--depth", "1", "origin", chdir: path)
-          @git_runner.run("reset", "--hard", "FETCH_HEAD", chdir: path)
-        end
+        synchronize_checkout(path) if refresh
         return [path, false]
       end
 
@@ -243,11 +248,35 @@ module Kward
       [path, true]
     end
 
+    def synchronized_repo(repo, ref)
+      path = cache_path(repo)
+      lock_path = "#{path}.lock"
+      FileUtils.mkdir_p(@cache_root, mode: 0o700)
+      File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        path, created = ensure_repo(repo, refresh: false)
+        synchronize_checkout(path, ref: ref) unless created && ref.to_s.empty?
+        revision = @git_runner.run("rev-parse", "HEAD", chdir: path).strip
+        revision = "unknown" if revision.empty?
+        [path, revision]
+      end
+    end
+
+    def synchronize_checkout(path, ref: nil)
+      if ref.to_s.empty?
+        @git_runner.run("fetch", "--depth", "1", "origin", chdir: path)
+      else
+        @git_runner.run("fetch", "--depth", "1", "origin", ref.to_s, chdir: path)
+      end
+      @git_runner.run("reset", "--hard", "FETCH_HEAD", chdir: path)
+    end
+
     def search_files(root, query, max_results:, context_lines:)
       matches = []
       base = File.realpath(root)
       scanned = 0
       Dir.glob(File.join(root, "**", "*"), File::FNM_DOTMATCH).sort.each do |path|
+        @cancellation&.raise_if_cancelled!
         next if matches.length >= max_results || scanned >= MAX_SCANNED_FILES
         next if skip_search_path?(base, path)
 
@@ -327,7 +356,12 @@ module Kward
       return nil unless owner.match?(%r{\A[A-Za-z0-9_.-]+\z}) && name.match?(%r{\A[A-Za-z0-9_.-]+\z})
 
       full_name = "#{owner}/#{name}"
-      { full_name: full_name, html_url: "https://github.com/#{full_name}", clone_url: "https://github.com/#{full_name}.git" }
+      result = { full_name: full_name, html_url: "https://github.com/#{full_name}", clone_url: "https://github.com/#{full_name}.git" }
+      if parts[2] == "blob" && parts.length >= 5
+        result[:requested_ref] = parts[3]
+        result[:requested_path] = parts[4..].join("/")
+      end
+      result
     rescue URI::InvalidURIError
       nil
     end

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

@@ -1,9 +1,10 @@
-require "cgi"
+require "cgi/escape"
 require "json"
 require "net/http"
 require "nokogiri"
 require "uri"
 require_relative "../../config_files"
+require_relative "../../http"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -49,7 +50,9 @@ module Kward
       true
     end
 
-    def search(args)
+    def search(args = nil, cancellation: nil, **keyword_args)
+      args ||= keyword_args
+      cancellation&.raise_if_cancelled!
       queries = args_value(args, "queries")
       return "Error: queries must be an array with 1-#{MAX_QUERIES} strings" unless valid_queries?(queries)
 
@@ -60,36 +63,44 @@ module Kward
       provider = normalize_provider(provider_value)
       return "Error: provider must be one of: #{PROVIDERS.join(", ")}" unless provider
 
+      recency_value = args_value(args, "recency_filter") || args_value(args, "recencyFilter")
+      recency = normalize_recency(recency_value)
+      return "Error: recency_filter must be one of: day, week, month, year" if recency_value && !recency
+
       options = {
         max_results: max_results,
-        recency_filter: normalize_recency(args_value(args, "recency_filter") || args_value(args, "recencyFilter")),
+        recency_filter: recency,
         domain_filter: normalize_domain_filter(args_value(args, "domain_filter") || args_value(args, "domainFilter")),
         provider: provider
       }
 
-      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."]
+      sections = ["# Web search"]
       failures = []
-      any_results = false
+      succeeded = 0
 
       queries.each do |query|
-        response, error = search_query(query, options)
-        any_results = true if successful_response?(response)
+        cancellation&.raise_if_cancelled!
+        response, error = search_query(query, options, cancellation: cancellation)
+        succeeded += 1 if successful_response?(response)
         failures << "#{query}: #{error}" if error && !successful_response?(response)
         sections << format_query_results(query, response, error)
       end
 
-      unless any_results
+      if succeeded.zero?
         return "Error: web_search found no results\n#{failures.map { |failure| "- #{failure}" }.join("\n")}".strip
       end
 
+      sections.insert(1, "- Queries: #{queries.length}\n- Succeeded: #{succeeded}\n- Failed: #{queries.length - succeeded}")
+      sections.insert(2, "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.")
       truncate_output(sections.join("\n\n"))
     end
 
     private
 
-    def search_query(query, options)
+    def search_query(query, options, cancellation: nil)
       errors = []
       provider_order(options[:provider]).each do |provider|
+        cancellation&.raise_if_cancelled!
         begin
           response = case provider
                      when "exa"
@@ -514,7 +525,7 @@ module Kward
         lines << answer
       end
 
-      results = response.results || []
+      results = unique_results(response.results || [])
       unless results.empty?
         lines << "Sources:" unless answer.empty?
         results.each_with_index do |result, index|
@@ -527,6 +538,25 @@ module Kward
       lines.join("\n")
     end
 
+    def unique_results(results)
+      seen = {}
+      results.each_with_object([]) do |result, unique|
+        url = clean_result_url(result.url)
+        uri = URI.parse(url)
+        next unless %w[http https].include?(uri.scheme) && uri.host
+
+        uri.fragment = nil
+        key = uri.to_s
+        next if seen[key]
+
+        seen[key] = true
+        result.url = key
+        unique << result
+      rescue URI::InvalidURIError
+        next
+      end
+    end
+
     def answer_from_results(results)
       results.filter_map do |result|
         excerpt = result.excerpt.to_s.strip
@@ -590,7 +620,7 @@ module Kward
       {
         "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",
+        "User-Agent" => Http.user_agent,
         "Sec-Fetch-Dest" => "document",
         "Sec-Fetch-Mode" => "navigate",
         "Sec-Fetch-Site" => "none",
@@ -720,14 +750,14 @@ module Kward
 
     # HTTP adapter used by web-search providers and fallbacks.
     class NetHttpClient
-      Response = Struct.new(:code, :body, :headers, keyword_init: true)
+      Response = Struct.new(:code, :body, :headers, :truncated, keyword_init: true)
 
-      def initialize(user_agent: nil)
+      def initialize(user_agent: Http.user_agent)
         @user_agent = user_agent
       end
 
-      def get(url, headers: {})
-        request(url, Net::HTTP::Get, headers: headers)
+      def get(url, headers: {}, max_bytes: nil)
+        request(url, Net::HTTP::Get, headers: headers, max_bytes: max_bytes)
       end
 
       def get_json(url, headers: {})
@@ -756,15 +786,28 @@ module Kward
 
       private
 
-      def request(url, request_class, headers: {})
+      def request(url, request_class, headers: {}, max_bytes: nil)
         uri = URI.parse(url)
         Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: HTTP_TIMEOUT_SECONDS, read_timeout: HTTP_TIMEOUT_SECONDS) do |http|
           http_request = request_class.new(uri)
           http_request["User-Agent"] = @user_agent if @user_agent
           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, headers: response.each_header.to_h)
+          response = nil
+          body = +""
+          truncated = false
+          http.request(http_request) do |http_response|
+            response = http_response
+            http_response.read_body do |chunk|
+              if max_bytes && body.bytesize + chunk.bytesize > max_bytes
+                body << chunk.byteslice(0, max_bytes - body.bytesize)
+                truncated = true
+                break
+              end
+              body << chunk
+            end
+          end
+          Response.new(code: response.code, body: body, headers: response.each_header.to_h, truncated: truncated)
         end
       end