pikuri-core 0.0.6 → 0.0.7

data/lib/pikuri/sanitizer.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # Renders attacker-controlled text safe to display, and reports *why*
+  # it was unsafe.
+  #
+  # Every string an LLM composes is untrusted: a bash command, a tool
+  # observation echoed back to the user, a description it wrote for a
+  # confirmation prompt. A model that is broken — or, far more likely,
+  # being driven by a prompt injection — can embed bytes that a terminal
+  # acts on rather than prints: a carriage return that overwrites the
+  # line the user just read, an ESC that recolors or repositions, a
+  # backspace that erases, a bidirectional override that reorders text so
+  # it reads differently than it runs, a zero-width character that hides
+  # in plain sight, or a Cyrillic +а+ masquerading as a Latin +a+. The
+  # whole point of a confirmation prompt collapses if the bytes the user
+  # approves are not the bytes that execute.
+  #
+  # {.sanitize} is the one chrome-independent primitive every renderer
+  # (terminal, TUI, web) routes through. It does two things and returns
+  # both as a {Result}:
+  #
+  # 1. *Neutralize* — make the dangerous bytes visible without changing
+  #    structure. Control bytes become +\xNN+, bidi/zero-width codepoints
+  #    become +\u{NNNN}+, tab becomes +\t+. Newlines are preserved
+  #    (multi-line commands are normal). This is *faithful, not
+  #    beautifying*: it never collapses runs of whitespace or rewrites a
+  #    tab to a space, because the user must see exactly what they are
+  #    approving — a Makefile's leading tab stays visibly a tab. A web
+  #    chrome composes +html_escape(sanitize(s).text)+; the HTML layer is
+  #    the caller's, not ours.
+  # 2. *Warn* — return a {Warning} per category detected, each a semantic
+  #    record (kind + offending tokens + a plain-English explanation).
+  #    Presentation is the chrome's: a terminal renders these bold yellow,
+  #    a web client a banner. The {Warning} carries no color or markup.
+  #
+  # == Scope (deliberately closed)
+  #
+  # Detection covers the *invisibility / cursor-control / reordering*
+  # attack classes completely, because each is a finite, enumerable set
+  # of codepoints: C0 controls, C1 controls (a second ANSI introducer on
+  # some emulators), DEL, the bidi overrides, and the zero-width
+  # characters. On top of that, {.sanitize} flags *mixed-script tokens* —
+  # a single word combining letters from Latin + Cyrillic + Greek, which
+  # is the signature of a homoglyph spoof and has near-zero false
+  # positives on real text (humans do not weld two alphabets inside one
+  # word; +café+ is all-Latin, +Москва+ all-Cyrillic, only +Pаypal+ mixes).
+  #
+  # Two confusable classes are explicitly *out of scope*, because
+  # detecting them needs Unicode confusables tables and produces heavy
+  # false positives on legitimate multilingual text:
+  #
+  # * *Whole-script* homoglyphs — an entirely-Cyrillic string that merely
+  #   looks Latin (no mixing to detect).
+  # * *Single-symbol* confusables — the Greek question mark +;+ (U+037E)
+  #   that looks like a semicolon, full-width forms, the division slash.
+  #
+  # "Solid" here means complete on the classes above, not exhaustive over
+  # all of Unicode.
+  module Sanitizer
+    # One reason a piece of text was flagged, ready for a chrome to
+    # render however it surfaces warnings (bold yellow line, web banner).
+    #
+    # * +kind+ — a {Symbol} category: +:backspace+, +:control_bytes+,
+    #   +:bidi+, +:zero_width+, or +:mixed_script+.
+    # * +offenders+ — the distinct offending tokens, in first-seen order:
+    #   the escaped forms (+"\\x1b"+, +"\\u{202e}"+) for byte categories,
+    #   the raw tokens (+"Pаypal"+) for +:mixed_script+.
+    # * +explanation+ — a one-line, chrome-agnostic English summary of
+    #   what the bytes can do.
+    Warning = Data.define(:kind, :offenders, :explanation)
+
+    # The output of {Sanitizer.sanitize}.
+    #
+    # * +text+ — the neutralized string, safe to print literally.
+    # * +warnings+ — {Array}<{Warning}>, empty when nothing was flagged.
+    Result = Data.define(:text, :warnings)
+
+    # Bidirectional-override codepoints: the explicit LRO/RLO/PDF/LRE/RLE
+    # set plus the isolate set (LRI/RLI/FSI/PDI). Reordering attacks.
+    BIDI_OVERRIDES = [*0x202a..0x202e, *0x2066..0x2069].freeze
+
+    # Zero-width and invisible codepoints: ZWSP, ZWNJ, ZWJ, and the BOM /
+    # zero-width no-break space.
+    ZERO_WIDTH = [0x200b, 0x200c, 0x200d, 0xfeff].freeze
+
+    # Codepoints {.sanitize} rewrites: C0 controls including tab (U+0009)
+    # but *excluding* newline (U+000A, which passes through untouched),
+    # C1 controls + DEL (U+007F–009F), the zero-width set, and the bidi
+    # overrides. Newline is the one control character a faithful render
+    # must keep, so the C0 range is split around it.
+    SUSPECT = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u200b-\u200d\u202a-\u202e\u2066-\u2069\ufeff]/
+
+    # The three Latin-confusable scripts whose mixing inside one token
+    # signals a homoglyph spoof. Punctuation, digits and spaces are the
+    # +Common+ script and match none of these, so they never count toward
+    # the "two distinct scripts" threshold.
+    CONFUSABLE_SCRIPTS = { 'Latin' => /\p{Latin}/, 'Cyrillic' => /\p{Cyrillic}/, 'Greek' => /\p{Greek}/ }.freeze
+
+    # Neutralize +text+ for literal display and report what was flagged.
+    #
+    # @param text [String] attacker-controlled text (an LLM-composed
+    #   command, description, or tool observation), e.g.
+    #   +"echo hi\rrm -rf /"+
+    # @return [Result] the neutralized +text+ plus an {Array}<{Warning}>
+    #   (empty when clean)
+    def self.sanitize(text)
+      backspace  = false
+      control    = []
+      bidi       = []
+      zero_width = []
+
+      clean = text.gsub(SUSPECT) do |ch|
+        cp = ch.ord
+        if cp == 0x09
+          '\\t'
+        elsif cp == 0x08
+          backspace = true
+          '\\x08'
+        elsif BIDI_OVERRIDES.include?(cp)
+          format('\\u{%04x}', cp).tap { |t| bidi << t }
+        elsif ZERO_WIDTH.include?(cp)
+          format('\\u{%04x}', cp).tap { |t| zero_width << t }
+        else
+          format('\\x%02x', cp).tap { |t| control << t }
+        end
+      end
+
+      Result.new(text: clean, warnings: warnings_for(backspace, control, bidi, zero_width, mixed_script_tokens(text)))
+    end
+
+    # Tokens (whitespace-delimited runs) that combine letters from two or
+    # more of {CONFUSABLE_SCRIPTS} — the homoglyph-spoof signature.
+    #
+    # @param text [String]
+    # @return [Array<String>] distinct offending tokens, first-seen order
+    def self.mixed_script_tokens(text)
+      text.split(/\s+/).reject(&:empty?).select do |token|
+        CONFUSABLE_SCRIPTS.count { |_name, re| token.match?(re) } >= 2
+      end.uniq
+    end
+
+    # Assemble one {Warning} per non-empty category, in a stable order
+    # (most-deceptive first).
+    #
+    # @return [Array<Warning>]
+    def self.warnings_for(backspace, control, bidi, zero_width, mixed)
+      out = []
+      if backspace
+        out << Warning.new(kind: :backspace, offenders: ['\\x08'],
+                           explanation: 'Backspace characters present — the model may be trying to visually erase ' \
+                                        'part of the text after you have read it.')
+      end
+      unless bidi.empty?
+        out << Warning.new(kind: :bidi, offenders: bidi.uniq,
+                           explanation: "Bidirectional-override characters present (#{bidi.uniq.join(' ')}) — these " \
+                                        'can reorder how text is displayed so it reads differently than it runs.')
+      end
+      unless zero_width.empty?
+        out << Warning.new(kind: :zero_width, offenders: zero_width.uniq,
+                           explanation: "Zero-width / invisible characters present (#{zero_width.uniq.join(' ')}) — " \
+                                        'the text may contain characters you cannot see.')
+      end
+      unless control.empty?
+        out << Warning.new(kind: :control_bytes, offenders: control.uniq,
+                           explanation: "Non-printable control bytes present (#{control.uniq.join(' ')}) — in a " \
+                                        'terminal these can move the cursor, change colors, or hide output.')
+      end
+      unless mixed.empty?
+        out << Warning.new(kind: :mixed_script, offenders: mixed,
+                           explanation: "Mixed-script tokens present (#{mixed.join(', ')}) — letters from different " \
+                                        "alphabets are combined within one word, a classic homoglyph spoof (e.g. " \
+                                        "Cyrillic 'а' standing in for Latin 'a').")
+      end
+      out
+    end
+    private_class_method :warnings_for
+  end
+end

data/lib/pikuri/tool/parameters.rb

@@ -68,6 +68,36 @@ module Pikuri
         add(name, 'string', description, required: false)
       end
 
+      # Add a required +array+-of-+string+ property — JSON-Schema
+      # +{type: 'array', items: {type: 'string'}}+. The LLM sends a
+      # native JSON array in the tool-call arguments (the shape its
+      # training data overwhelmingly uses for list-valued parameters),
+      # so there is no in-band encoding for it to get wrong.
+      # The value must arrive as an Array — no
+      # JSON-encoded-array-in-a-string fallback. Element coercion
+      # mirrors the scalar fields' one documented leniency, in
+      # reverse: Integers and finite Floats are converted to their
+      # +to_s+ form (a model emitting +["Fix issue 12", 42]+ meant a
+      # string list — the conversion is unambiguous), while booleans,
+      # +nil+, and nested structures are rejected — those signal a
+      # genuinely wrong call shape, not a representational quirk.
+      # An empty array is type-valid; rejecting it (if the tool needs
+      # at least one element) is the tool's job, with a tool-specific
+      # error message.
+      #
+      # @param name [Symbol] property name
+      # @param description [String] human-readable description shown to the LLM
+      # @return [self]
+      def required_string_array(name, description)
+        @properties[name] = {
+          type: 'array',
+          items: { type: 'string' },
+          description: description
+        }
+        @required << name.to_s
+        self
+      end
+
       # Add a required +integer+ property. Accepts Integers, Floats with a
       # zero fractional part (e.g. +1.0+), and base-10 numeric Strings (after
       # trimming) that resolve to whole numbers; rejects everything else.
@@ -260,9 +290,35 @@ module Pikuri
           coerce_number(value)
         when 'boolean'
           coerce_boolean(value)
+        when 'array'
+          coerce_string_array(value)
+        end
+      end
+
+      def coerce_string_array(value)
+        raise CoercionError, "must be an array of strings (got #{value.class}: #{value.inspect})" unless value.is_a?(Array)
+
+        value.each_with_index.map do |element, i|
+          case element
+          when String
+            element
+          when Integer
+            element.to_s
+          when Float
+            raise CoercionError, array_element_message(i, element) unless element.finite?
+
+            element.to_s
+          else
+            raise CoercionError, array_element_message(i, element)
+          end
         end
       end
 
+      def array_element_message(index, element)
+        "must be an array of strings (element #{index} is #{element.class}: #{element.inspect}; " \
+          'numbers are auto-converted, other types are not)'
+      end
+
       def coerce_boolean(value)
         return value if value == true || value == false
 
@@ -341,7 +397,14 @@ module Pikuri
 
       def missing_required_message(name, schema)
         enum_part = schema[:enum] ? ", one of: #{schema[:enum].map { |v| "`#{v}`" }.join(', ')}" : ''
-        "Missing required parameter `#{name}` (#{schema[:type]}#{enum_part}): #{schema[:description]}"
+        "Missing required parameter `#{name}` (#{type_label(schema)}#{enum_part}): #{schema[:description]}"
+      end
+
+      # Human/LLM-facing label for a property's type in error messages:
+      # +"array of strings"+ for array properties, the bare JSON-Schema
+      # type name otherwise.
+      def type_label(schema)
+        schema[:items] ? "array of #{schema[:items][:type]}s" : schema[:type]
       end
 
       def unknown_key_error(unknown)
@@ -366,7 +429,7 @@ module Pikuri
           *@properties.map { |name, prop|
             req = @required.include?(name.to_s) ? 'required' : 'optional'
             enum_part = prop[:enum] ? ", one of: #{prop[:enum].map { |v| "`#{v}`" }.join(', ')}" : ''
-            "  - `#{name}` (#{prop[:type]}, #{req}#{enum_part}): #{prop[:description]}"
+            "  - `#{name}` (#{type_label(prop)}, #{req}#{enum_part}): #{prop[:description]}"
           }
         ].join("\n")
       end

data/lib/pikuri/tool/search/brave.rb

@@ -9,13 +9,17 @@ module Pikuri
     module Search
       # Performs a Brave Search via the official Web Search API and returns
       # the hits as a list of {Result} rows. Split into a thin HTTP fetch
-      # (#search) and a pure parser (#parse) so tests can exercise the
+      # (#search) and a pure parser (.parse) so tests can exercise the
       # parser against fixture JSON without hitting the network. The
-      # cascade in {Engines.search} owns the final Markdown rendering.
+      # cascade in {Engines#search} owns the final Markdown rendering.
       #
-      # Requires a Brave Search API key. Get one at
-      # https://api-dashboard.search.brave.com — the free "Data for Search"
-      # tier allows 1 query/sec and ~2k queries/month.
+      # A class constructed with the API key it should use
+      # (+Brave.new(api_key:)+); {Engines} builds one only when a Brave key
+      # was configured and then drives it through the same +#search+ /
+      # +#label+ interface as every other provider. pikuri reads no key
+      # from the environment (see CLAUDE.md "Environment is not a secret
+      # store"). Get a key at https://api-dashboard.search.brave.com — the
+      # free "Data for Search" tier allows 1 query/sec and ~2k queries/month.
       #
       # == Privacy posture
       #
@@ -32,49 +36,59 @@ module Pikuri
       # 90-day retention by default, real ZDR if you pay for it. Still a
       # logged 90-day window on the cheap tier, so not a substitute for
       # ZDR for genuinely sensitive queries.
-      module Brave
+      class Brave
         # @return [String] Web Search endpoint
         ENDPOINT = 'https://api.search.brave.com/res/v1/web/search'
         # @return [Integer] default number of results returned, matching
         #   {DuckDuckGo::DEFAULT_MAX_RESULTS}
         DEFAULT_MAX_RESULTS = 10
-        # @return [String] env var holding the API key; +X-Subscription-Token+
-        ENV_KEY = 'BRAVE_SEARCH_API_KEY'
         # @return [RateLimiter] free-tier Brave caps at 1 req/sec; the
         #   5-minute cooldown protects the limited monthly quota from
         #   being burned on doomed retries when a 429 hits.
         LIMITER = RateLimiter.new(min_interval: 1.0, cooldown: 300.0)
 
+        # @param api_key [String] Brave Search subscription token. Required
+        #   and non-blank: pikuri reads no key from the environment — the
+        #   host supplies it ({Engines} only constructs a Brave when a key
+        #   was configured).
+        # @raise [ArgumentError] if +api_key+ is blank
+        def initialize(api_key:)
+          raise ArgumentError, 'Brave Search API key is blank' if api_key.to_s.strip.empty?
+
+          @api_key = api_key
+        end
+
+        # @return [String] short provider label for {Engines} logging /
+        #   fallback messages.
+        def label
+          'Brave'
+        end
+
         # Fetch results for +query+ and return them as an +Array<Result>+.
         # Calls are throttled to one per second and circuit-broken for 5
         # minutes on rate-limit / quota-exhausted responses; see {LIMITER}.
-        # The caller (typically {Engines.search}) is expected to have
+        # The caller (typically {Engines#search}) is expected to have
         # already normalized the query and to wrap this in a result cache.
         #
         # @param query [String] search query (already normalized)
         # @param max_results [Integer] maximum number of result entries;
         #   passed through as Brave's +count+ (1..20)
-        # @param api_key [String] Brave Search subscription token; defaults to
-        #   the {ENV_KEY} environment variable
         # @return [Array<Result>] hits, possibly empty when Brave ran the
         #   query and matched nothing
-        # @raise [ArgumentError] if no API key is available
         # @raise [Engines::Unavailable] when Brave returns HTTP 429
         #   (rate limit / quota exhausted) or 5xx — "try again later"
-        #   responses the cascade in {Engines.search} can fall back
+        #   responses the cascade in {Engines#search} can fall back
         #   from. Also raised immediately if {LIMITER} is in cooldown.
         #   Other non-2xx (e.g. 401/403 from a bad API key) bubble up as
         #   +RuntimeError+ so config problems stay visible.
         # @raise [RuntimeError] for non-rate-limit HTTP failures or when the
         #   response shape contains no results.
-        def self.search(query, max_results: DEFAULT_MAX_RESULTS, api_key: ENV.fetch(ENV_KEY, nil))
-          raise ArgumentError, "Brave Search API key not set (#{ENV_KEY})" if api_key.to_s.strip.empty?
-
+        def search(query, max_results: DEFAULT_MAX_RESULTS)
           LIMITER.call do
             response = Faraday.get(
               ENDPOINT,
               { q: query, count: max_results },
-              { 'X-Subscription-Token' => api_key, 'Accept' => 'application/json' }
+              { 'X-Subscription-Token' => @api_key, 'Accept' => 'application/json' }
             )
             unless response.success?
               if response.status == 429 || response.status >= 500
@@ -84,7 +98,7 @@ module Pikuri
               raise "Brave Search request failed: #{response.status} #{response.body}"
             end
 
-            parse(response.body, max_results: max_results)
+            self.class.parse(response.body, max_results: max_results)
           end
         end
 

data/lib/pikuri/tool/search/duckduckgo.rb

@@ -9,9 +9,14 @@ module Pikuri
     module Search
       # Performs a DuckDuckGo search by scraping +html.duckduckgo.com+ and
       # returns the hits as a list of {Result} rows. Split into a thin HTTP
-      # fetch (#search) and a pure parser (#parse) so tests can exercise
+      # fetch (#search) and a pure parser (.parse) so tests can exercise
       # the parser against fixture HTML without hitting the network. The
-      # cascade in {Engines.search} owns the final Markdown rendering.
+      # cascade in {Engines#search} owns the final Markdown rendering.
+      #
+      # A class (constructed with no arguments) so it shares the uniform
+      # provider shape with the keyed {Brave} / {Exa}: {Engines} holds a
+      # list of provider *instances* and calls +#search+ / +#label+ on each
+      # without caring which is which.
       #
       # == Privacy posture
       #
@@ -30,7 +35,7 @@ module Pikuri
       # Microsoft, who has no comparable no-training pledge. Better than
       # Exa for sensitive queries, worse than Brave; for anything
       # genuinely embarrassing, don't search the web at all.
-      module DuckDuckGo
+      class DuckDuckGo
         # @return [String] HTML search endpoint
         ENDPOINT = 'https://html.duckduckgo.com/html/'
         # @return [String] User-Agent sent with each request; DDG often rejects
@@ -44,10 +49,16 @@ module Pikuri
         #   soft-block response doesn't get retried for the next 5 minutes
         LIMITER = RateLimiter.new(min_interval: 2.0, cooldown: 300.0)
 
+        # @return [String] short provider label for {Engines} logging /
+        #   fallback messages. Uniform across providers (see {Brave#label}).
+        def label
+          'DuckDuckGo'
+        end
+
         # Fetch results for +query+ and return them as an +Array<Result>+.
         # Calls are throttled to one every 2s and circuit-broken for 5 minutes
         # after a soft-block; see {LIMITER}. The caller (typically
-        # {Engines.search}) is expected to have already normalized the
+        # {Engines#search}) is expected to have already normalized the
         # query and to wrap this in a result cache.
         #
         # @param query [String] search query (already normalized)
@@ -56,12 +67,12 @@ module Pikuri
         #   query and matched nothing
         # @raise [Engines::Unavailable] when DDG soft-blocks the IP
         #   (anomaly/CAPTCHA page) or returns HTTP 429/5xx — i.e. "try again
-        #   later" responses the cascade in {Engines.search} can fall
+        #   later" responses the cascade in {Engines#search} can fall
         #   back from. Also raised immediately if {LIMITER} is in cooldown.
         # @raise [RuntimeError] if the HTTP call fails for other reasons or
         #   the empty-results page is in an unrecognized layout. A genuine
         #   empty-results page is *not* an error; see {.parse}.
-        def self.search(query, max_results: DEFAULT_MAX_RESULTS)
+        def search(query, max_results: DEFAULT_MAX_RESULTS)
           LIMITER.call do
             response = Faraday.get(ENDPOINT, { q: query }, { 'User-Agent' => USER_AGENT })
             unless response.success?
@@ -72,7 +83,7 @@ module Pikuri
               raise "DuckDuckGo request failed: #{response.status} #{response.body}"
             end
 
-            parse(response.body, max_results: max_results)
+            self.class.parse(response.body, max_results: max_results)
           end
         end
 

data/lib/pikuri/tool/search/engines.rb

@@ -2,20 +2,31 @@
 
 module Pikuri
   class Tool
-    # Namespace for the web-search stack used by {Tool::WEB_SEARCH}: per-
+    # Namespace for the web-search stack used by {Tool::WebSearch}: per-
     # provider modules ({DuckDuckGo}, {Brave}, {Exa}), the {Result} value
     # object they all return, the cross-provider {Engines} cascade with
     # its on-disk cache, and the shared {RateLimiter} a provider can wire
     # in to back off when a quota header says so.
     module Search
-      # Search-orchestration entry point: the cascade across configured
+      # Search-orchestration object: the cascade across configured
       # providers, the result cache, and the {Unavailable} protocol marker
-      # the cascade uses to fall back. The LLM-facing tool itself
-      # ({Tool::WEB_SEARCH}) lives in +lib/tool/web_search.rb+ and calls
-      # into {.search} below. Each {Tool::Search} provider module
+      # the cascade uses to fall back. The LLM-facing tool itself is built
+      # by {Tool::WebSearch.build}, which constructs one of these and wires
+      # its {#search} into a {Tool}. Each {Tool::Search} provider module
       # ({DuckDuckGo}, {Brave}, {Exa}) raises {Unavailable} when it wants
       # the cascade to try the next one.
-      module Engines
+      #
+      # == Provider keys are constructor config, not environment
+      #
+      # Brave and Exa are paid and need an API key; DuckDuckGo needs none.
+      # An {Engines} is constructed with the keys it should use
+      # (+brave_key:+ / +exa_key:+, both optional) — pikuri reads no key
+      # from the environment, so the only providers in the cascade are
+      # DuckDuckGo plus whichever keyed providers the host actually
+      # configured. The host sources those keys however it likes (the
+      # bundled +bin/+ examples load a JSON config file by convention); see
+      # CLAUDE.md "Environment is not a secret store".
+      class Engines
         # Subsystem logger; set its level with +PIKURI_LOG_ENGINES+
         # (e.g. +PIKURI_LOG_ENGINES=debug+) or the global +PIKURI_LOG+.
         #
@@ -24,40 +35,54 @@ module Pikuri
 
         # Raised by a provider when it is temporarily unavailable (rate-limited,
         # bot-blocked, quota-exhausted, or otherwise saying "try again later"
-        # rather than "your request is wrong"). The cascade in {Engines.search}
+        # rather than "your request is wrong"). The cascade in {#search}
         # catches this and tries the next provider; any other exception bubbles
         # up unchanged so genuine bugs and config errors stay visible.
         class Unavailable < StandardError; end
 
-        # All providers that are currently configured. {DuckDuckGo} is always
-        # available (no API key needed); {Brave} and {Exa} each join the
-        # list when their API token is present in the environment. Recomputed
-        # on every call so a process picks up a newly-set token without a
-        # restart.
-        #
-        # @return [Array<Module>] +Tool::Search::*+ provider modules, each
-        #   exposing +.search(query, max_results:)+ → +Array<Result>+
-        def self.providers
-          list = [DuckDuckGo]
-          list << Brave unless ENV[Brave::ENV_KEY].to_s.strip.empty?
-          list << Exa unless ENV[Exa::ENV_KEY].to_s.strip.empty?
-          list
-        end
-
-        # On-disk cache used by {.search} to memoize answered queries.
-        # Defined as a method so specs can swap it for an isolated cache
-        # or {UrlCache::NULL} without touching the shared instance.
+        # Process-shared on-disk cache backing {#search}'s default. Kept at
+        # class level (not per-instance) so every engine dedupes answered
+        # queries into one directory; the constructor's +cache:+ parameter
+        # injects a different store for tests. Exposed as a method so specs
+        # can swap it for {UrlCache::NULL} without touching the instance.
         #
         # @return [UrlCache, #fetch]
         CACHE = UrlCache.new(ttl: UrlCache::DEFAULT_TTL, dir: "#{UrlCache::ROOT_DIR}/web_search")
-        # Accessor for {CACHE}; specs override this to swap in
-        # {UrlCache::NULL} or an isolated cache.
+        # Accessor for {CACHE}, used as the constructor's +cache:+ default;
+        # specs override this to swap in {UrlCache::NULL}.
         #
         # @return [UrlCache, #fetch]
         def self.cache
           CACHE
         end
 
+        # Builds the provider cascade once: {DuckDuckGo} always (no key
+        # needed), plus {Brave} / {Exa} when their key was supplied
+        # (non-blank). Each keyed provider is constructed with its key, so
+        # from here on every provider is just an object answering +#search+
+        # / +#label+ — the cascade in {#search} treats them uniformly.
+        #
+        # @param brave_key [String, nil] Brave Search subscription token;
+        #   non-blank ⇒ Brave joins the cascade. +nil+/blank ⇒ not configured.
+        # @param exa_key [String, nil] Exa API key; non-blank ⇒ Exa joins the
+        #   cascade. +nil+/blank ⇒ not configured.
+        # @param cache [UrlCache, #fetch] result store memoizing answered
+        #   queries; defaults to the process-shared {.cache}.
+        # @return [Engines]
+        def initialize(brave_key: nil, exa_key: nil, cache: self.class.cache)
+          @providers = [DuckDuckGo.new]
+          @providers << Brave.new(api_key: brave_key) unless brave_key.to_s.strip.empty?
+          @providers << Exa.new(api_key: exa_key) unless exa_key.to_s.strip.empty?
+          @cache = cache
+          @last_logged_providers = nil
+        end
+
+        # The provider instances this engine cascades across, in
+        # declaration order (the cascade itself shuffles them per call).
+        #
+        # @return [Array<#search, #label>] configured provider instances
+        attr_reader :providers
+
         # Run +query+ through the configured providers in random order, falling
         # back to the next one each time a provider raises {Unavailable}. The
         # shuffle spreads load so a single provider isn't always hit first
@@ -68,13 +93,13 @@ module Pikuri
         # +Array<Result>+ is rendered into smolagents-style Markdown here
         # (+"## Search Results"+ header, then +[title](url)\nbody+ entries
         # joined by blank lines; an empty array becomes +"No results found."+),
-        # and the rendered Markdown is cached on disk via {.cache}, keyed by
-        # the cleaned query. A cache hit short-circuits the cascade entirely
-        # (and benefits whichever provider would have answered next time too
-        # — once a query is cached, the cooldown state of the original
-        # answering provider no longer matters). +max_results+ is not part
-        # of the cache key, so callers passing a non-default value may get
-        # a result rendered with the previously-cached size.
+        # and the rendered Markdown is cached on disk via {#initialize}'s
+        # +cache:+, keyed by the cleaned query. A cache hit short-circuits the
+        # cascade entirely (and benefits whichever provider would have
+        # answered next time too — once a query is cached, the cooldown state
+        # of the original answering provider no longer matters). +max_results+
+        # is not part of the cache key, so callers passing a non-default value
+        # may get a result rendered with the previously-cached size.
         #
         # If every provider reports temporary unavailability, returns an
         # +"Error: ..."+ string instead of raising — same convention as
@@ -88,7 +113,7 @@ module Pikuri
         # @return [String] Markdown-formatted result list, or +"Error: ..."+
         #   when all providers are exhausted
         # @raise [ArgumentError] if the query is empty after normalization
-        def self.search(query, max_results:)
+        def search(query, max_results:)
           cleaned = query.to_s.strip.gsub(/\s+/, ' ')
           raise ArgumentError, 'query is empty' if cleaned.empty?
 
@@ -96,7 +121,7 @@ module Pikuri
           log_providers(current_providers)
 
           hit = true
-          result = cache.fetch(cleaned) do
+          result = @cache.fetch(cleaned) do
             hit = false
             failures = []
             results = nil
@@ -106,7 +131,7 @@ module Pikuri
               chosen = provider
               break
             rescue Unavailable => e
-              failures << "#{provider.name.split('::').last} (#{e.message})"
+              failures << "#{provider.label} (#{e.message})"
             end
             # Raise so {UrlCache#fetch} does NOT persist the all-unavailable
             # message — otherwise that string would block every future search
@@ -115,7 +140,7 @@ module Pikuri
             chosen or raise Unavailable, "all search providers temporarily unavailable: #{failures.join('; ')}"
 
             LOGGER.info do
-              "engine=#{chosen.name.split('::').last} query=#{cleaned.inspect} results=#{results.size}"
+              "engine=#{chosen.label} query=#{cleaned.inspect} results=#{results.size}"
             end
             render(results)
           end
@@ -125,6 +150,8 @@ module Pikuri
           "Error: #{e.message}"
         end
 
+        private
+
         # Render an +Array<Result>+ into the smolagents-style Markdown the
         # LLM consumes: +"## Search Results"+ header, then +[title](url)\nbody+
         # entries joined by blank lines. An empty array becomes the
@@ -133,30 +160,26 @@ module Pikuri
         #
         # @param results [Array<Result>] hits from the winning provider
         # @return [String] Markdown-formatted result list
-        def self.render(results)
+        def render(results)
           return "## Search Results\n\nNo results found." if results.empty?
 
           "## Search Results\n\n" + results.map { |r| "[#{r.title}](#{r.url})\n#{r.body}" }.join("\n\n")
         end
-        private_class_method :render
 
         # Emit an INFO log line listing the currently-available providers,
-        # but only when the set differs from the last one we logged.
-        # {.providers} is recomputed on every {.search} call so a process
-        # picks up newly-set API keys without a restart; the memo here
-        # keeps the log to one line per distinct configuration rather
-        # than one per search.
+        # but only when the set differs from the last one this engine
+        # logged. The memo keeps the log to one line per distinct
+        # configuration rather than one per search.
         #
-        # @param current [Array<Module>] providers returned by {.providers}
+        # @param current [Array<#label>] providers returned by {#providers}
         # @return [void]
-        def self.log_providers(current)
+        def log_providers(current)
           return if @last_logged_providers == current
 
           @last_logged_providers = current
-          names = current.map { |p| p.name.split('::').last }.join(', ')
+          names = current.map(&:label).join(', ')
           LOGGER.info("engines available: #{names}")
         end
-        private_class_method :log_providers
       end
     end
   end