pikuri 0.0.1

data/lib/pikuri/tool/skill_catalog.rb

@@ -0,0 +1,376 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Pikuri
+  class Tool
+    # Discovery + validation of *skills* — Markdown files with YAML
+    # frontmatter that the agent loads on demand via {Tool::Skill}.
+    #
+    # A skill is a directory containing a +SKILL.md+ file. The frontmatter
+    # declares the skill's +name+ and +description+; everything in the
+    # directory (helper scripts, reference notes, templates) is treated as
+    # sidecar content the LLM can pull in via the regular +read+ tool
+    # after loading the skill. Pikuri implements the
+    # {https://agentskills.io/specification Agent Skills standard}
+    # leniently — invalid frontmatter is warned about but the skill
+    # still loads, except a missing +description+ which is fatal (no
+    # description means the LLM has no signal for when to invoke it).
+    #
+    # == Catalog vs. tool
+    #
+    # {SkillCatalog} owns the *discovery* layer: where skills live, how
+    # the frontmatter is parsed, what wins on a name collision. The
+    # {Tool::Skill} tool is the *loading* layer: it receives a catalog at
+    # construction and looks names up against it when the LLM invokes
+    # +skill+. The two are paired by {Agent} — see
+    # {Agent#initialize} for the auto-registration rule (non-empty
+    # catalog ⇒ +Tool::Skill+ is appended to the tool list and the
+    # catalog's prompt block is appended to the system prompt).
+    #
+    # == The seam
+    #
+    # {SkillCatalog} is an abstract base with two bundled
+    # implementations: {Empty} (the +EMPTY+ singleton, used by
+    # +pikuri-chat+ and as the default for any caller that doesn't have a
+    # filesystem story) and {Bundled} (the on-disk scanner). The seam
+    # lets future hosts (e.g. an in-editor pikuri reading skills from a
+    # virtual filesystem, or a synthetic test catalog) swap in without
+    # touching {Tool::Skill} or {Agent}.
+    class SkillCatalog
+      # Frontmatter +name+ cap per the Agent Skills standard.
+      MAX_NAME_LENGTH = 64
+
+      # Frontmatter +description+ cap per the Agent Skills standard.
+      MAX_DESCRIPTION_LENGTH = 1024
+
+      # The three skill directories pikuri scans, in precedence order.
+      # +.pikuri+ first (the user's own pikuri-specific skills),
+      # +.claude+ second (so existing Claude Code skills travel along
+      # for free), +.agents+ last (the cross-harness convention PI also
+      # honors). Same names are used for both global roots
+      # (under +~/+) and project roots (relative to CWD, walked up).
+      SKILL_DIR_NAMES = ['.pikuri/skills', '.claude/skills', '.agents/skills'].freeze
+
+      LOGGER = Pikuri.logger_for('Skills')
+      private_constant :LOGGER
+
+      # A loaded skill record. Holds everything the catalog discovers
+      # and the tool needs to satisfy a load: +name+ and +description+
+      # for the catalog's prompt block, +location+ (absolute path to
+      # the +SKILL.md+) so the LLM can reference sidecars relative to
+      # +File.dirname(location)+, and +body+ (the SKILL.md content
+      # below the frontmatter) returned verbatim when the tool fires.
+      #
+      # Bodies are eager-loaded at scan time even though only
+      # +name+/+description+/+location+ end up in the prompt — skill
+      # files are small, eager loading keeps the tool's hot path
+      # IO-free, and there is no fault tolerance requirement that
+      # warrants the complexity of lazy I/O.
+      Skill = Data.define(:name, :description, :location, :body)
+
+      # Skills available to the LLM, in stable insertion order (which
+      # equals the order they were discovered, which equals precedence).
+      #
+      # @return [Array<Skill>]
+      # @raise [NotImplementedError] in the abstract base
+      def list
+        raise NotImplementedError, "#{self.class}#list must be implemented"
+      end
+
+      # Look up a skill by name.
+      #
+      # @param name [String]
+      # @return [Skill, nil]
+      # @raise [NotImplementedError] in the abstract base
+      def get(name)
+        raise NotImplementedError, "#{self.class}#get must be implemented"
+      end
+
+      # @return [Boolean] true when {#list} is empty. {Agent} keys its
+      #   auto-wiring (system-prompt augmentation + +Tool::Skill+
+      #   registration) off this — empty catalog ⇒ no surface change.
+      def empty?
+        list.empty?
+      end
+
+      # System-prompt block advertising every loaded skill to the LLM.
+      # Follows the Agent Skills standard's XML shape (PI uses the same
+      # one) so a skill folder authored against any compliant harness
+      # renders consistently here.
+      #
+      # Returns +""+ for an empty catalog so callers can unconditionally
+      # concatenate without an +if+. The leading +\n\n+ separates the
+      # block from whatever the caller's static system prompt ends with.
+      #
+      # @return [String]
+      def format_for_prompt
+        return '' if empty?
+
+        lines = [
+          '',
+          '',
+          'The following skills provide specialized instructions for specific tasks.',
+          "Use the `skill` tool with the skill's name to load its full instructions.",
+          '',
+          '<available_skills>'
+        ]
+        list.each do |skill|
+          lines << '  <skill>'
+          lines << "    <name>#{escape_xml(skill.name)}</name>"
+          lines << "    <description>#{escape_xml(skill.description)}</description>"
+          lines << "    <location>#{escape_xml(skill.location)}</location>"
+          lines << '  </skill>'
+        end
+        lines << '</available_skills>'
+        lines.join("\n")
+      end
+
+      private
+
+      def escape_xml(str)
+        str.gsub('&', '&amp;')
+           .gsub('<', '&lt;')
+           .gsub('>', '&gt;')
+           .gsub('"', '&quot;')
+           .gsub("'", '&apos;')
+      end
+
+      # Null-object catalog. The +EMPTY+ constant is the singleton
+      # instance used as the default for {Agent#initialize}; constructing
+      # additional instances is harmless but pointless.
+      class Empty < SkillCatalog
+        # @return [Array<Skill>] always empty
+        def list
+          [].freeze
+        end
+
+        # @return [nil]
+        def get(_name)
+          nil
+        end
+      end
+
+      # Shared singleton for the no-skills case. Frozen.
+      EMPTY = Empty.new.freeze
+
+      # On-disk catalog: eager-scans the given +roots+ at construction
+      # and freezes itself. Use {.discover} to build one against
+      # pikuri's conventional locations; pass +roots:+ directly in
+      # tests so collision and ordering behavior can be exercised
+      # without staging dirs under +~/+.
+      #
+      # == Precedence
+      #
+      # +roots+ is processed left to right. The *first* skill seen for
+      # a given name wins; later occurrences are dropped with a warning
+      # logged through +Pikuri.logger_for('Skills')+. Callers that want
+      # "project beats global" pass project roots first.
+      #
+      # == Validation
+      #
+      # The Agent Skills standard is enforced leniently. A missing
+      # +description+ is the only hard failure (the skill is skipped);
+      # name/dir mismatch, oversized name/description, invalid name
+      # characters, malformed YAML — all log warnings and the skill
+      # still loads with whatever could be salvaged. Skills without
+      # a YAML frontmatter block at all are skipped silently (the file
+      # is presumably not meant as a skill).
+      class Bundled < SkillCatalog
+        # Build a catalog from pikuri's conventional discovery roots:
+        # project skills (walked from +cwd+ up to the git root or
+        # filesystem root) take precedence over global skills (under
+        # the user's home directory). Within each tier, the order in
+        # {SKILL_DIR_NAMES} applies (+.pikuri+ ➜ +.claude+ ➜ +.agents+).
+        #
+        # Non-existent directories are skipped silently; the loaded
+        # set is whatever existed at construction time.
+        #
+        # @param cwd [String, Pathname] working directory whose
+        #   ancestor chain is searched for project skill roots.
+        # @return [Bundled]
+        def self.discover(cwd: Dir.pwd)
+          new(roots: discover_project_roots(cwd: cwd) + discover_global_roots)
+        end
+
+        # Project roots walked from +cwd+ upwards, stopping at the
+        # nearest ancestor containing +.git+ (inclusive) or at the
+        # filesystem root. The deepest directory's roots appear first,
+        # so closer-to-CWD skills win on name collisions.
+        #
+        # @param cwd [String, Pathname]
+        # @return [Array<String>] absolute paths to existing dirs
+        def self.discover_project_roots(cwd:)
+          results = []
+          current = File.expand_path(cwd.to_s)
+          loop do
+            SKILL_DIR_NAMES.each do |sub|
+              candidate = File.join(current, sub)
+              results << candidate if File.directory?(candidate)
+            end
+
+            # Stop *after* processing the git root — git roots are
+            # natural project boundaries; ancestors above are someone
+            # else's project.
+            break if File.directory?(File.join(current, '.git'))
+
+            parent = File.dirname(current)
+            break if parent == current # filesystem root
+
+            current = parent
+          end
+          results
+        end
+
+        # Global roots under the user's home directory.
+        #
+        # @return [Array<String>] absolute paths to existing dirs
+        def self.discover_global_roots
+          home = Dir.home
+          SKILL_DIR_NAMES.map { |sub| File.join(home, sub) }
+                         .select { |dir| File.directory?(dir) }
+        end
+
+        # @param roots [Array<String, Pathname>] skill directories in
+        #   precedence order — first occurrence of a given skill name
+        #   wins.
+        # @return [Bundled]
+        def initialize(roots:)
+          super()
+          @skills = {}
+          roots.each { |root| scan_root(root.to_s) }
+          @skills.freeze
+          @list = @skills.values.freeze
+          freeze
+        end
+
+        # @return [Array<Skill>]
+        def list
+          @list
+        end
+
+        # @param name [String]
+        # @return [Skill, nil]
+        def get(name)
+          @skills[name]
+        end
+
+        private
+
+        def scan_root(root)
+          return unless File.directory?(root)
+
+          Dir.children(root).sort.each do |entry|
+            skill_dir = File.join(root, entry)
+            next unless File.directory?(skill_dir)
+
+            skill_md = File.join(skill_dir, 'SKILL.md')
+            next unless File.file?(skill_md)
+
+            skill = parse_skill(skill_md, parent_dir_name: entry)
+            next if skill.nil?
+
+            existing = @skills[skill.name]
+            if existing
+              LOGGER.warn(
+                "skill name '#{skill.name}' at #{skill_md} is shadowed by " \
+                "earlier entry at #{existing.location}"
+              )
+            else
+              @skills[skill.name] = skill
+            end
+          end
+        end
+
+        # Read +path+ and return a {Skill}, or +nil+ if the file is
+        # unusable (no frontmatter, no description, unreadable). Warnings
+        # for soft violations are logged but do not block loading.
+        def parse_skill(path, parent_dir_name:)
+          raw = File.read(path)
+          frontmatter, body = split_frontmatter(raw)
+
+          if frontmatter.nil?
+            LOGGER.warn("#{path}: no YAML frontmatter; skipped")
+            return nil
+          end
+
+          description = frontmatter['description'].to_s.strip
+          if description.empty?
+            LOGGER.warn("#{path}: missing required 'description'; skipped")
+            return nil
+          end
+
+          name = (frontmatter['name'] || parent_dir_name).to_s
+          validate_name(name, parent_dir_name: parent_dir_name, path: path)
+          validate_description(description, path: path)
+
+          Skill.new(
+            name: name,
+            description: description,
+            location: path,
+            body: body
+          )
+        rescue Errno::ENOENT, Errno::EACCES => e
+          LOGGER.warn("#{path}: #{e.class}: #{e.message}; skipped")
+          nil
+        end
+
+        # Split a SKILL.md into +[frontmatter_hash, body_string]+.
+        # Returns +[nil, raw]+ when there is no detectable frontmatter
+        # block. On YAML parse failure, logs a warning and returns
+        # +[{}, body]+ so the caller can still observe an empty
+        # frontmatter (which trips the "missing description" path
+        # below and discards the skill).
+        def split_frontmatter(content)
+          normalized = content.gsub(/\r\n?/, "\n")
+          return [nil, normalized] unless normalized.start_with?("---\n")
+
+          end_marker = normalized.index("\n---", 4)
+          return [nil, normalized] unless end_marker
+
+          yaml_str = normalized[4...end_marker]
+          body = normalized[(end_marker + 4)..].to_s
+          body = body.sub(/\A\n/, '')
+
+          parsed =
+            begin
+              YAML.safe_load(yaml_str) || {}
+            rescue Psych::SyntaxError => e
+              LOGGER.warn("frontmatter YAML parse error: #{e.message}")
+              {}
+            end
+          parsed = {} unless parsed.is_a?(Hash)
+
+          [parsed, body]
+        end
+
+        def validate_name(name, parent_dir_name:, path:)
+          if name != parent_dir_name
+            LOGGER.warn("#{path}: skill name '#{name}' does not match parent directory '#{parent_dir_name}'")
+          end
+          if name.length > MAX_NAME_LENGTH
+            LOGGER.warn("#{path}: skill name exceeds #{MAX_NAME_LENGTH} chars (#{name.length})")
+          end
+          unless /\A[a-z0-9-]+\z/.match?(name)
+            LOGGER.warn("#{path}: skill name '#{name}' contains invalid characters " \
+                        "(allowed: lowercase a-z, 0-9, hyphens)")
+          end
+          if name.start_with?('-') || name.end_with?('-')
+            LOGGER.warn("#{path}: skill name '#{name}' starts or ends with a hyphen")
+          end
+          return unless name.include?('--')
+
+          LOGGER.warn("#{path}: skill name '#{name}' contains consecutive hyphens")
+        end
+
+        def validate_description(description, path:)
+          return unless description.length > MAX_DESCRIPTION_LENGTH
+
+          LOGGER.warn(
+            "#{path}: description exceeds #{MAX_DESCRIPTION_LENGTH} chars (#{description.length})"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/tool/sub_agent.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # The +sub_agent+ tool, expressed as a {Tool} subclass: instantiating
+    # +Tool::SubAgent.new(parent_agent)+ produces a tool whose
+    # {Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's,
+    # so ruby_llm sees nothing special about it. When the model calls it,
+    # the closure inside +execute+ spawns a fresh {Agent} that runs its
+    # own Thought / Tool-call / Observation loop on a clean message
+    # history, then returns only the sub-agent's final assistant message
+    # back as the parent's next observation.
+    #
+    # The sub-agent reuses the parent's +transport+, +system_prompt+,
+    # +context_window_cap+, and +name+ (as its hierarchical prefix), so
+    # it shares the same persona, hits the same server, and inherits the
+    # same context-window cap without re-probing. Its tool list is a
+    # snapshot of the parent's {Agent#tools} taken at construction —
+    # {Agent#allow_sub_agent} only appends the sub-agent tool to its own
+    # +@tools+ *after* this snapshot, so the sub-agent's tool list never
+    # contains itself (recursion guard).
+    #
+    # Its listener list comes from the parent's {Agent#listeners} via
+    # {Agent::ListenerList#for_sub_agent}, which forwards to each
+    # listener's own +for_sub_agent+ hook: +Terminal+ swaps to a padded
+    # fresh instance, +TokenLog+ resets its snapshot, +StepLimit+ picks
+    # +max_steps:+ out of the params, and listeners without the hook
+    # ({Agent::Listener::InMemoryMessageList}, …) are shared by reference so
+    # structured capture and other stateful renderers flow continuously.
+    #
+    # All parent state is captured by value at construction — the closure
+    # does not chase +parent_agent+ mutations later. The one piece of
+    # mutable state is a monotonic counter used to generate sub-agent ids:
+    # +"sub_agent 0"+, +"sub_agent 1"+, ... at the top level; nested
+    # children of +"sub_agent 0"+ are +"sub_agent 0_0"+, +"sub_agent 0_1"+,
+    # ... — the +"sub_agent "+ prefix appears once at the top and the
+    # underscore-separated counter chain records depth.
+    class SubAgent < Tool
+      # Description shown to the LLM. Follows the opencode-shape (summary
+      # + +Usage:+ bullets) prescribed by the project's tool-description
+      # convention.
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Delegate a self-contained task to a fresh sub-agent that runs its own Thought / Tool-call / Observation loop on a clean conversation, returning only its final assistant message.
+
+        Usage:
+        - Use to isolate side-quests — research, multi-step lookups, exploratory tool use — so intermediate observations do not clutter your own context.
+        - The sub-agent has your tools minus `sub_agent` itself, so it cannot recurse.
+        - It shares your system prompt — persona, tool-use conventions, and output format carry over. Do NOT re-explain who you are or how to use tools.
+        - It cannot see your conversation. Put ALL task-specific context inside `task`; the sub-agent has zero memory of what came before.
+      DESC
+
+      # @param parent_agent [Agent] the calling agent. Read for its
+      #   {Agent#transport}, {Agent#system_prompt}, {Agent#tools},
+      #   {Agent#listeners}, {Agent#context_window_cap}, and {Agent#name}.
+      # @param max_steps [Integer] step budget for each sub-agent run,
+      #   forwarded as the +max_steps:+ kwarg to
+      #   {Agent::ListenerList#for_sub_agent} (consumed by
+      #   {Agent::Listener::StepLimit#for_sub_agent}).
+      # @return [SubAgent]
+      def initialize(parent_agent, max_steps: 10)
+        transport      = parent_agent.transport
+        system_prompt  = parent_agent.system_prompt
+        sub_tools      = parent_agent.tools.dup
+        listeners      = parent_agent.listeners
+        context_window = parent_agent.context_window_cap
+        parent_name    = parent_agent.name
+        sub_counter    = 0
+
+        super(
+          name: 'sub_agent',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :task,
+                              'Self-contained instructions for the sub-agent, ' \
+                              'e.g. "Find the populations of Reykjavik and ' \
+                              'Helsinki in 2024 and report both numbers." ' \
+                              'It has no access to the parent conversation, ' \
+                              'so include all necessary context.'
+          },
+          execute: lambda { |task:|
+            idx = sub_counter
+            sub_counter += 1
+            sub_name = parent_name.empty? ? "sub_agent #{idx}" : "#{parent_name}_#{idx}"
+
+            sub = Agent.new(
+              transport: transport,
+              system_prompt: system_prompt,
+              tools: sub_tools,
+              listeners: listeners.for_sub_agent(max_steps: max_steps, name: sub_name),
+              context_window: context_window,
+              name: sub_name
+            )
+            sub.run_loop(user_message: task)
+            sub.last_assistant_content
+          }
+        )
+      end
+    end
+  end
+end

data/lib/pikuri/tool/web_scrape.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # Truncation policy and Tool spec for the +web_scrape+ tool. The actual
+    # scraping lives in {Tool::Scraper::Simple}; this module is a thin
+    # wrapper that picks the scraper, applies a character cap so the LLM
+    # doesn't drown in long-form content, and exposes the result to the
+    # agent loop in OpenAI tool-call shape.
+    module WebScrape
+      # @return [Integer] default character cap on the Markdown returned
+      #   by {.visit}. Sized to cover most post-readability article bodies
+      #   in full on the first call, so the LLM doesn't have to re-request
+      #   with a larger cap and pollute its context with the same prefix
+      #   twice. ~5K tokens at the typical char/token ratio — light even
+      #   for small local models. The genuinely long pages (long Wikipedia
+      #   entries, multi-section docs) still get cut, and the truncation
+      #   marker invites a deliberate larger {.visit} call when needed.
+      DEFAULT_MAX_CHARS = 20_000
+
+      # @return [Integer] hard ceiling on the +max_chars+ argument to
+      #   {.visit}. Requests above this are clamped silently so the LLM
+      #   cannot dump an arbitrarily large page into the conversation.
+      MAX_MAX_CHARS = 100_000
+
+      # On-disk cache used by {.visit} to memoize fetched pages. Defined
+      # as a method so specs can swap it for an isolated cache or
+      # {UrlCache::NULL} without touching the shared instance.
+      #
+      # @return [UrlCache, #fetch]
+      CACHE = UrlCache.new(ttl: UrlCache::DEFAULT_TTL, dir: "#{UrlCache::ROOT_DIR}/web_scrape")
+      def self.cache
+        CACHE
+      end
+
+      # Fetch +url+ via {Tool::Scraper::Simple} and truncate the rendered
+      # Markdown to +max_chars+ characters.
+      #
+      # The full extracted Markdown is cached on disk via {.cache}, keyed
+      # by URL, so repeat visits within the cache TTL skip the network
+      # and the extraction pass entirely. +max_chars+ is not part of the
+      # cache key — different values for the same URL share one entry,
+      # and truncation runs after the cache lookup.
+      #
+      # {Tool::Scraper::FetchError} (HTTP non-2xx, network failure,
+      # redirect-loop, missing +Location+ header) is caught and returned
+      # as +"Error: ..."+ in the calculator-style convention so the agent
+      # loop feeds the failure back to the model as the next observation
+      # instead of crashing — the LLM can then try a different URL or
+      # search again. The rescue lives outside {.cache}'s +fetch+ block,
+      # so failure strings are never persisted: a retry on the next call
+      # hits the network again. Other exceptions (parser bugs in our own
+      # code) bubble up unchanged.
+      #
+      # @param url [String] absolute HTTP(S) URL of the page to download
+      # @param max_chars [Integer] character cap on the returned Markdown.
+      #   Clamped to +[1, {MAX_MAX_CHARS}]+; defaults to
+      #   {DEFAULT_MAX_CHARS}. When the full page exceeds the cap, output
+      #   is cut and a marker noting the original length is appended.
+      # @return [String] Markdown representation of the page, possibly
+      #   truncated, or +"Error: ..."+ on a recoverable fetch failure
+      def self.visit(url, max_chars: DEFAULT_MAX_CHARS)
+        max_chars = max_chars.clamp(1, MAX_MAX_CHARS)
+        markdown = cache.fetch(url) { Scraper::Simple.visit(url) }
+        truncate(markdown, max_chars)
+      rescue Scraper::FetchError => e
+        "Error: #{e.message}"
+      end
+
+      # Cut +markdown+ to at most +max_chars+ characters, appending a
+      # marker describing the original length when truncation actually
+      # happens. Returns +markdown+ unchanged if it already fits.
+      #
+      # @param markdown [String] full Markdown text
+      # @param max_chars [Integer] character cap; assumed already clamped
+      # @return [String]
+      def self.truncate(markdown, max_chars)
+        return markdown if markdown.length <= max_chars
+
+        "#{markdown[0, max_chars]}\n\n" \
+          "... [truncated at #{max_chars} of #{markdown.length} chars; " \
+          'call again with a larger `max_chars` to see more]'
+      end
+    end
+
+    # Webpage download + Markdown conversion tool. Thin wrapper over
+    # {Tool::WebScrape.visit} that exposes it to the agent loop in OpenAI
+    # tool-call shape.
+    #
+    # @return [Tool]
+    WEB_SCRAPE = new(
+      name: 'web_scrape',
+      description: <<~DESC,
+        Scrapes the rendered webpage, PDF, or text file at the given URL and returns its main content as Markdown.
+
+        Usage:
+        - Use for HTML pages or PDFs where you want readable content — readability extraction strips nav, sidebars, and boilerplate.
+        - For raw textual payloads (JSON, CSV, robots.txt, source files), use fetch instead — it returns bytes verbatim, while web_scrape would corrupt them with a Markdown pass.
+        - A Single Page App may return very little or no content. Do NOT retry with a larger max_chars; try a different URL instead.
+      DESC
+      parameters: Parameters.build { |p|
+        p.required_string :url,
+                          'Absolute URL of the webpage to scrape, including ' \
+                          'the scheme, e.g. "https://example.com/article".'
+        p.optional_integer :max_chars,
+                           'Maximum number of characters of Markdown to ' \
+                           'return. Defaults to 20000; hard-capped at ' \
+                           '100000. When the page is longer than this, ' \
+                           'output is cut and a marker reports the full ' \
+                           'length.'
+      },
+      execute: ->(url:, max_chars: WebScrape::DEFAULT_MAX_CHARS) {
+        WebScrape.visit(url, max_chars: max_chars)
+      }
+    )
+  end
+end

data/lib/pikuri/tool/web_search.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # Namespace marker matching the file path. The actual search
+    # orchestration lives in {Tool::Search::Engines}; this file owns only
+    # the LLM-facing {Tool::WEB_SEARCH} constant below.
+    module WebSearch; end
+
+    # Web-search tool exposed to the agent loop in OpenAI tool-call shape.
+    # Calls {Tool::Search::Engines.search}, which cascades through whichever
+    # providers are configured (DuckDuckGo always, Brave when its API key is
+    # present) in random order, falling back on temporary-unavailability
+    # errors. Providers return structured {Tool::Search::Result} rows;
+    # +Engines.search+ renders the winning provider's rows into the
+    # smolagents-style Markdown shape the LLM sees, so the format stays
+    # stable regardless of which provider ran.
+    #
+    # @return [Tool]
+    WEB_SEARCH = new(
+      name: 'web_search',
+      description: <<~DESC,
+        Searches the web for a query and returns the top results as a Markdown list of titles, URLs, and short snippets.
+
+        Usage:
+        - Use this to find candidate URLs, then call web_scrape on the most promising one(s) for full content. Snippets alone rarely answer a question.
+      DESC
+      parameters: Parameters.build { |p|
+        p.required_string :query,
+                          'The search query, e.g. "BigDecimal precision Ruby".'
+        p.optional_integer :max_results,
+                           'Maximum number of result entries to return. ' \
+                           'Defaults to 10; most providers cap this at 20.'
+      },
+      execute: ->(query:, max_results: 10) { Search::Engines.search(query, max_results: max_results) }
+    )
+  end
+end