pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/tool/scraper.rb

@@ -6,58 +6,43 @@ require 'uri'
 
 module Pikuri
   class Tool
-    # HTTP side of the web tools ({Tool::WEB_SCRAPE} and {Tool::FETCH}):
-    # GET the URL with a real-browser User-Agent, follow redirects, and
-    # hand the response body to {Pikuri::Extractor.extract} with the
-    # response's +Content-Type+ as the hint. HTML/XHTML render via
-    # {Extractor::HTML}, any other +text/*+ type passes through
-    # verbatim, and plug-in extractors extend the set (with pikuri-pdf
-    # registered, +application/pdf+ extracts — by header or by +%PDF-+
-    # magic, so a PDF served under a lying header still works); the
-    # remaining types raise {FetchError} so the LLM observes the
-    # failure instead of receiving an empty rendering.
+    # HTTP side of the web tools ({Tool::WEB_SCRAPE} and {Tool::FETCH}): GET the
+    # URL with a real-browser User-Agent, follow redirects, and hand the body to
+    # {Pikuri::Extractor.extract} with the response +Content-Type+ as the hint.
+    # HTML/XHTML renders via {Extractor::HTML}, other +text/*+ passes through
+    # verbatim, plug-in extractors extend the set (with pikuri-pdf,
+    # +application/pdf+ extracts — by header or +%PDF-+ magic, so a lying header
+    # still works); remaining types raise {FetchError} so the LLM observes the
+    # failure rather than an empty rendering.
     #
-    # Split into a thin HTTP fetch ({.fetch}) and the extraction
-    # wrapper ({.visit}) so tests can drive each piece in isolation and
-    # {Tool::Fetch} can reuse the HTTP half without the extraction
-    # pass. Nothing here knows about the LLM; the tools that wrap this
-    # module own caching and truncation and turn rendered Markdown (or
-    # {FetchError}) into the next observation.
+    # Split into a thin HTTP fetch ({.fetch}) and the extraction wrapper
+    # ({.visit}) so tests drive each in isolation and {Tool::Fetch} can reuse the
+    # HTTP half. Nothing here knows about the LLM — the wrapping tools own
+    # caching, truncation, and turning the result into an observation.
     module Scraper
-      # Raised when a URL cannot be rendered into Markdown text — HTTP
-      # non-2xx, network failure, redirect-loop, missing +Location+,
-      # unsupported content-type, or a parse failure that reads as "try
-      # a different URL" to the LLM. Catching this in
-      # {Tool::WEB_SCRAPE} / {Tool::FETCH} turns the failure into an
-      # +"Error: ..."+ observation; anything else bubbles up so genuine
-      # bugs stay visible.
+      # Raised when a URL can't be rendered to Markdown — HTTP non-2xx, network
+      # failure, redirect loop, missing +Location+, unsupported content-type, or
+      # a parse failure. The web tools rescue this into an +"Error: ..."+
+      # observation; anything else bubbles up so genuine bugs stay visible.
       class FetchError < StandardError; end
 
-      # @return [String] User-Agent sent with each request; many sites
-      #   reject requests with no UA or an obvious bot UA
+      # @return [String] User-Agent sent with each request; many sites reject a
+      #   missing or obviously-bot UA.
       USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' \
                    '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
-      # @return [String] +Accept+ header sent with each request, so
-      #   servers that content-negotiate hand back something we can use:
-      #   rendered HTML first, +application/pdf+ for hosts with a PDF
-      #   extractor registered, then any +text/*+ for the verbatim
-      #   pass-through arm.
+      # @return [String] +Accept+ header, so content-negotiating servers hand
+      #   back something usable: HTML first, then +application/pdf+, then +text/*+.
       ACCEPT = 'text/html,application/xhtml+xml,application/pdf,text/*;q=0.8'
-      # @return [Integer] maximum number of HTTP redirects to follow
-      #   before giving up
+      # @return [Integer] maximum HTTP redirects to follow before giving up.
       MAX_REDIRECTS = 5
-      # @return [Integer] connect timeout in seconds for the underlying
-      #   Faraday request
+      # @return [Integer] connect timeout (s) for the Faraday request.
       OPEN_TIMEOUT = 10
-      # @return [Integer] read timeout in seconds for the underlying
-      #   Faraday request
+      # @return [Integer] read timeout (s) for the Faraday request.
       READ_TIMEOUT = 20
 
-      # @return [Integer] maximum number of characters of an error
-      #   response body to include in a {FetchError} message. The body is
-      #   often a multi-kilobyte HTML challenge page (Cloudflare, WAF
-      #   interstitial, etc.); a short excerpt tells the LLM what kind of
-      #   page came back without flooding the next observation.
+      # @return [Integer] max chars of an error response body in a {FetchError}
+      #   message — enough to show what came back (a Cloudflare/WAF page) without
+      #   flooding the observation.
       ERROR_BODY_EXCERPT = 200
 
       # Result of a successful {Scraper.fetch}: the response body, the
@@ -65,46 +50,30 @@ module Pikuri
       # parameters stripped), and the final URL after redirects.
       Fetched = Data.define(:body, :content_type, :url)
 
-      # Fetch +url+ and render its main content as Markdown.
+      # Fetch +url+ and render its main content as Markdown. No caching — every
+      # call hits the network (wrap it to memoize; {Tool::WebScrape.visit}
+      # does). The output is +strip+'d (leading/trailing blank lines are common
+      # from PDF page-feeds and trailing newlines) but interior whitespace is
+      # preserved (paragraph breaks and code indentation are load-bearing).
       #
-      # No caching here — every call hits the network. Callers that want
-      # to memoize results should wrap this method themselves (see
-      # {Tool::WebScrape.visit}, which does exactly that).
-      #
-      # The extracted output is +String#strip+'d so the LLM never sees
-      # a body that opens or closes with blank lines — common with
-      # extracted PDFs' page-feed whitespace and with text bodies that
-      # carry a trailing newline. Interior whitespace is preserved
-      # because Markdown paragraph breaks and source-code indentation
-      # are load-bearing.
-      #
-      # @param url [String] absolute HTTP(S) URL of the page to download
-      # @return [String] full Markdown representation of the page with
-      #   leading/trailing whitespace trimmed, uncapped otherwise —
-      #   caller is responsible for any size limiting before feeding
-      #   the result back to the LLM
-      # @raise [FetchError] on HTTP non-2xx, network failure, redirect
-      #   loop, a 3xx without a +Location+ header, a response no
-      #   extractor recognizes, or an extraction failure (malformed
-      #   PDF, ...)
+      # @param url [String] absolute HTTP(S) URL
+      # @return [String] Markdown, whitespace-trimmed, otherwise uncapped —
+      #   caller size-limits before feeding the LLM
+      # @raise [FetchError] on HTTP non-2xx, network failure, redirect loop, a
+      #   3xx without +Location+, an unrecognized response, or extraction failure
       def self.visit(url)
         extract(fetch(url)).strip
       end
 
-      # Render a {Fetched} response as Markdown via
-      # {Pikuri::Extractor.extract}, re-raising both extraction failure
-      # modes as {FetchError} — the single exception type the web tools
-      # rescue. The content-type is passed verbatim (including the +""+
-      # of a missing header, which matches no text arm — a body without
-      # transport metadata is refused, not sniffed; only a strong magic
-      # sniff like pikuri-pdf's +%PDF-+ overrides a wrong or missing
-      # header, because such a sniff never misfires on text).
+      # Render a {Fetched} response as Markdown via {Pikuri::Extractor.extract},
+      # re-raising both extraction failure modes as {FetchError}. The
+      # content-type is passed verbatim (including +""+ for a missing header,
+      # which matches no text arm — a body without transport metadata is
+      # refused, not sniffed; only a strong magic sniff like +%PDF-+ overrides).
       #
       # @param fetched [Fetched]
-      # @return [String] Markdown representation produced by the
-      #   matched extractor
-      # @raise [FetchError] when no extractor matches the response's
-      #   content-type, or when extraction fails
+      # @return [String] Markdown from the matched extractor
+      # @raise [FetchError] when no extractor matches, or extraction fails
       def self.extract(fetched)
         Pikuri::Extractor.extract(StringIO.new(fetched.body), content_type: fetched.content_type)
       rescue Pikuri::Extractor::Unsupported
@@ -113,26 +82,17 @@ module Pikuri
         raise FetchError, e.message
       end
 
-      # Download the body of +url+, manually following up to
-      # {MAX_REDIRECTS} redirects. Faraday is configured with no
-      # middleware so behavior here mirrors the rest of the codebase
-      # (see +Tool::Search::DuckDuckGo.search+).
-      #
-      # All recoverable failures — HTTP 4xx/5xx, +Faraday::Error+ network
-      # blips, exhausted redirect budget, 3xx without a +Location+ —
-      # surface as {FetchError} so the caller has a single exception type
-      # to rescue. Error bodies are trimmed to {ERROR_BODY_EXCERPT}
-      # characters with whitespace collapsed, so a Cloudflare-challenge
-      # response doesn't dump kilobytes of inline HTML into the next LLM
-      # observation.
+      # Download +url+, manually following up to {MAX_REDIRECTS} redirects. All
+      # recoverable failures (HTTP 4xx/5xx, +Faraday::Error+, exhausted redirect
+      # budget, 3xx without +Location+) surface as {FetchError}. Error bodies
+      # are trimmed to {ERROR_BODY_EXCERPT} so a challenge page doesn't dump
+      # kilobytes into the observation.
       #
-      # @param url [String] absolute HTTP(S) URL to fetch
-      # @param limit [Integer] redirects remaining; recurses with
-      #   +limit - 1+ on each 3xx
-      # @return [Fetched] body, normalized content-type, and final URL
-      #   after redirects
-      # @raise [FetchError] on non-2xx/3xx responses, network errors,
-      #   redirect-loop exhaustion, or 3xx without a +Location+ header
+      # @param url [String] absolute HTTP(S) URL
+      # @param limit [Integer] redirects remaining; recurses with +limit - 1+ on 3xx
+      # @return [Fetched] body, normalized content-type, final URL
+      # @raise [FetchError] on non-2xx/3xx, network error, redirect-loop
+      #   exhaustion, or 3xx without +Location+
       def self.fetch(url, limit: MAX_REDIRECTS)
         raise FetchError, "too many redirects fetching #{url}" if limit.zero?
 
@@ -169,10 +129,8 @@ module Pikuri
       end
       private_class_method :normalize_content_type
 
-      # Whitespace-collapse +body+ and clip to {ERROR_BODY_EXCERPT}
-      # characters, so the {FetchError} message stays a single readable
-      # line even when the server returned a multi-KB HTML challenge
-      # page.
+      # Whitespace-collapse +body+ and clip to {ERROR_BODY_EXCERPT}, keeping the
+      # {FetchError} message a single readable line.
       #
       # @param body [String, nil]
       # @return [String]

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

@@ -7,44 +7,33 @@ require 'nokogiri'
 module Pikuri
   class Tool
     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
-      # parser against fixture JSON without hitting the network. The
-      # cascade in {Engines#search} owns the final Markdown rendering.
+      # Performs a Brave Search via the official Web Search API, returning hits
+      # as {Result} rows. Split into a thin HTTP fetch (#search) and a pure
+      # parser (.parse) so tests exercise the parser against fixture JSON.
+      # {Engines#search} owns the final Markdown rendering.
       #
-      # 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.
+      # Constructed with its API key (+Brave.new(api_key:)+); {Engines} builds
+      # one only when a Brave key was configured. pikuri reads no key from the
+      # environment (CLAUDE.md "Environment is not a secret store"). Key at
+      # https://api-dashboard.search.brave.com — the free "Data for Search" tier
+      # allows 1 query/sec, ~2k/month.
       #
       # == Privacy posture
       #
-      # Brave's API Privacy Notice retains Search Query Logs for 90 days
-      # (billing / troubleshooting) and states +Brave does not collect any
-      # identifiers that can link a search query to an individual or their
-      # devices+. Brave publicly commits that the Search API does not use
-      # query data to train its own models, and offers Zero Data Retention
-      # — but only on the Enterprise plan, not on the free "Data for
-      # Search" tier pikuri defaults to.
-      #
-      # Bottom line: of pikuri's three providers Brave has the cleanest
-      # API-level posture — no training-on-queries, no IP linkage, capped
-      # 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.
+      # Brave's API notice retains Search Query Logs 90 days and collects no
+      # identifiers linking a query to a person; it publicly commits not to train
+      # on query data, and offers Zero Data Retention — but only on Enterprise,
+      # not the free tier pikuri defaults to. Bottom line: the cleanest
+      # API-level posture of pikuri's three providers (no training, no IP
+      # linkage, capped 90-day retention), but a logged 90-day window on the
+      # cheap tier, so not a ZDR substitute for genuinely sensitive queries.
       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}
+        # @return [Integer] default number of results returned.
         DEFAULT_MAX_RESULTS = 10
-        # @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.
+        # @return [RateLimiter] free-tier Brave caps at 1 req/sec; the 5-minute
+        #   cooldown protects the monthly quota from doomed retries on a 429.
         LIMITER = RateLimiter.new(min_interval: 1.0, cooldown: 300.0)
 
         # @param api_key [String] Brave Search subscription token. Required
@@ -58,33 +47,28 @@ module Pikuri
           @api_key = api_key
         end
 
-        # @return [String] short provider label for {Engines} logging /
-        #   fallback messages.
+        # @return [String] short provider label for {Engines}.
         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
-        # already normalized the query and to wrap this in a result cache.
+        # Fetch results for +query+ as an +Array<Result>+. Throttled to 1/sec and
+        # circuit-broken 5 min on rate-limit/quota (see {LIMITER}). The caller
+        # ({Engines#search}) normalizes the query and wraps this in a 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)
-        # @return [Array<Result>] hits, possibly empty when Brave ran the
-        #   query and matched nothing
-        # @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
-        #   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 search(query, max_results: DEFAULT_MAX_RESULTS)
-          LIMITER.call do
+        # @param max_results [Integer] max entries; Brave's +count+ (1..20)
+        # @param cancellable [Pikuri::Agent::Control::Cancellable] makes
+        #   {LIMITER}'s pacing wait interruptible; see {RateLimiter#call}.
+        # @return [Array<Result>] hits, possibly empty when Brave matched nothing
+        # @raise [Engines::Unavailable] on HTTP 429 or 5xx (the cascade falls
+        #   back), or if {LIMITER} is in cooldown. Other non-2xx (401/403 bad
+        #   key) bubble up as +RuntimeError+.
+        # @raise [RuntimeError] for non-rate-limit HTTP failures, or a
+        #   zero-result response that isn't a recognized empty-results payload.
+        def search(query, max_results: DEFAULT_MAX_RESULTS,
+                   cancellable: Pikuri::Agent::Control::Cancellable::NEVER)
+          LIMITER.call(cancellable: cancellable) do
             response = Faraday.get(
               ENDPOINT,
               { q: query, count: max_results },
@@ -102,24 +86,16 @@ module Pikuri
           end
         end
 
-        # Parse a Brave Web Search JSON response into a list of {Result} rows.
-        # HTML highlight tags (+<strong>+) inside +title+ and +description+
-        # are stripped via Nokogiri so the output is plain text.
-        #
-        # When the response yields zero result nodes, two cases are
-        # distinguished: a genuine "no results" payload (recognized search
-        # shape with empty +mixed.main+/+top+/+side+ — typically a too-narrow
-        # query Brave couldn't match) returns an empty array instead of
-        # raising, so {Engines.search} can render its standard no-results
-        # stub. Anything else (unknown layout, structured error) raises
-        # with a diagnostic so the failure surfaces.
+        # Parse a Brave JSON response into {Result} rows (+<strong>+ highlights
+        # stripped). A genuine "no results" payload (recognized search shape,
+        # empty +mixed.main/top/side+) returns +[]+ so {Engines.search} renders
+        # its stub; any other zero-result shape raises.
         #
         # @param json [String] response body from {ENDPOINT}
-        # @param max_results [Integer] maximum number of result entries
+        # @param max_results [Integer] max entries
         # @return [Array<Result>] hits, possibly empty on a recognized
         #   empty-results payload
-        # @raise [RuntimeError] when the response yields no result entries and
-        #   is not recognized as a genuine empty-results payload
+        # @raise [RuntimeError] on an unrecognized zero-result response
         def self.parse(json, max_results: DEFAULT_MAX_RESULTS)
           data = JSON.parse(json)
           results = Array(data.dig('web', 'results')).take(max_results).filter_map do |r|
@@ -142,11 +118,11 @@ module Pikuri
           results
         end
 
-        # Strip HTML markup (notably +<strong>+ highlights Brave wraps around
-        # query terms in titles and descriptions) and collapse whitespace.
+        # Strip HTML markup (notably the +<strong>+ highlights Brave wraps around
+        # query terms) and collapse whitespace.
         #
-        # @param html [String, nil] raw text from a Brave result field
-        # @return [String] plain text with tags removed; empty string for nil
+        # @param html [String, nil]
+        # @return [String] plain text; empty string for nil
         def self.strip_html(html)
           return '' if html.nil?
 
@@ -154,13 +130,10 @@ module Pikuri
         end
         private_class_method :strip_html
 
-        # True when a parsed response with zero +web.results+ entries looks
-        # like Brave's own "search ran, nothing matched" payload (typically a
-        # too-narrow query) rather than a malformed or error response. The
-        # markers are the recognized +type: "search"+ envelope and an empty
-        # +mixed+ block — Brave populates +mixed.main/top/side+ with whichever
-        # verticals matched, so all three being empty arrays is the canonical
-        # signal that the search itself succeeded but found nothing.
+        # True when a zero-+web.results+ response is Brave's own "ran, matched
+        # nothing" payload, not an error. Markers: the +type: "search"+ envelope
+        # and an empty +mixed+ block (Brave fills +mixed.main/top/side+ with
+        # matched verticals, so all three empty = succeeded-but-found-nothing).
         #
         # @param data [Hash, Object] parsed response
         # @return [Boolean]
@@ -174,13 +147,12 @@ module Pikuri
         end
         private_class_method :genuine_no_results?
 
-        # Build an error message for a parsed response that yielded zero
-        # results. Quotes Brave's +error.detail+ if present, otherwise
-        # truncates the raw body so the caller can see the actual payload.
+        # Build an error message for a zero-result response: quote Brave's
+        # +error.detail+ if present, else a truncated raw body.
         #
         # @param data [Hash, Object] parsed response
         # @param raw [String] raw response body
-        # @return [String] human-readable diagnostic to feed to +raise+
+        # @return [String] diagnostic to feed to +raise+
         def self.diagnose_empty(data, raw)
           if data.is_a?(Hash) && data['error'].is_a?(Hash)
             err = data['error']

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

@@ -7,73 +7,56 @@ require 'uri'
 module Pikuri
   class Tool
     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
-      # the parser against fixture HTML without hitting the network. The
-      # 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.
+      # Performs a DuckDuckGo search by scraping +html.duckduckgo.com+, returning
+      # hits as {Result} rows. Split into a thin HTTP fetch (#search) and a pure
+      # parser (.parse) so tests exercise the parser against fixture HTML.
+      # {Engines#search} owns the final Markdown rendering. Constructed with no
+      # arguments, sharing the uniform +#search+/+#label+ provider shape with the
+      # keyed {Brave} / {Exa}.
       #
       # == Privacy posture
       #
-      # DuckDuckGo's privacy policy states +We don't save your IP address
-      # or any unique identifiers alongside your searches+ and +We have
-      # never sold any personal information+, and they proxy requests on
-      # the user's behalf so downstream content providers can't build a
-      # per-user search history. That part is real — but DDG is mainly a
-      # relay over Bing for web results, so the *query content* still
-      # reaches Microsoft for fulfillment even though DDG strips
-      # identifying info on the way out.
-      #
-      # Bottom line: DDG is a genuine privacy improvement over hitting
-      # Bing directly (your IP isn't tied to the query, no per-user
-      # profile is built on DDG's side), but query content still lands at
-      # 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.
+      # DDG doesn't save your IP or tie a per-user profile to queries, and
+      # proxies requests so downstream providers can't build a search history —
+      # real, but DDG relays web results over Bing, so *query content* still
+      # reaches Microsoft (who has no no-training pledge). Better than Exa for
+      # sensitive queries, worse than Brave; for anything genuinely embarrassing,
+      # don't search the web at all.
       class DuckDuckGo
         # @return [String] HTML search endpoint
         ENDPOINT = 'https://html.duckduckgo.com/html/'
         # @return [String] User-Agent sent with each request; DDG often rejects
-        #   requests with no UA or an obvious bot UA
+        #   a missing or obviously-bot UA.
         USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' \
                      '(KHTML, like Gecko) Chrome/120.0 Safari/537.36'
-        # @return [Integer] default number of results returned, matching smolagents
+        # @return [Integer] default number of results returned.
         DEFAULT_MAX_RESULTS = 10
         # @return [RateLimiter] paces calls (DDG bans IPs that hammer the HTML
-        #   endpoint) and circuit-breaks on {Engines::Unavailable} so a
-        #   soft-block response doesn't get retried for the next 5 minutes
+        #   endpoint) and circuit-breaks 5 min on {Engines::Unavailable}.
         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}).
+        # @return [String] short provider label for {Engines}.
         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
-        # query and to wrap this in a result cache.
+        # Fetch results for +query+ as an +Array<Result>+. Throttled to one every
+        # 2s and circuit-broken 5 min after a soft-block (see {LIMITER}). The
+        # caller ({Engines#search}) normalizes the query and wraps this in a cache.
         #
         # @param query [String] search query (already normalized)
-        # @param max_results [Integer] maximum number of result entries
-        # @return [Array<Result>] hits, possibly empty when DDG ran the
-        #   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
-        #   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 search(query, max_results: DEFAULT_MAX_RESULTS)
-          LIMITER.call do
+        # @param max_results [Integer] max result entries
+        # @param cancellable [Pikuri::Agent::Control::Cancellable] makes
+        #   {LIMITER}'s pacing wait interruptible; see {RateLimiter#call}.
+        # @return [Array<Result>] hits, possibly empty when DDG matched nothing
+        # @raise [Engines::Unavailable] on a soft-block (anomaly/CAPTCHA page) or
+        #   HTTP 429/5xx (the cascade falls back), or if {LIMITER} is in cooldown.
+        # @raise [RuntimeError] on other HTTP failures or an unrecognized
+        #   empty-results layout. A genuine empty-results page is not an error;
+        #   see {.parse}.
+        def search(query, max_results: DEFAULT_MAX_RESULTS,
+                   cancellable: Pikuri::Agent::Control::Cancellable::NEVER)
+          LIMITER.call(cancellable: cancellable) do
             response = Faraday.get(ENDPOINT, { q: query }, { 'User-Agent' => USER_AGENT })
             unless response.success?
               if response.status == 429 || response.status >= 500
@@ -87,28 +70,18 @@ module Pikuri
           end
         end
 
-        # Parse a +html.duckduckgo.com+ result page into a list of {Result}
-        # rows. +<b>+ highlights inside snippets are stripped.
-        #
-        # When the page has zero result nodes, two cases are distinguished:
-        # a genuine "no results" page (narrow query, DDG's own "No results
-        # found" indicator) returns an empty array instead of raising, so
-        # {Engines.search} can render its standard no-results stub.
-        # Anything else (anomaly modal, CAPTCHA, service-unavailable page,
-        # unknown layout) raises with the diagnostic text extracted from
-        # the body, so an IP soft-block is surfaced rather than silently
+        # Parse a +html.duckduckgo.com+ result page into {Result} rows (+<b>+
+        # highlights stripped). On zero result nodes: a genuine "no results" page
+        # returns +[]+ (so {Engines.search} renders its stub); the anomaly/CAPTCHA
+        # modal raises {Engines::Unavailable}; anything else raises {RuntimeError}
+        # (likely a layout change) — so an IP soft-block surfaces rather than
         # masquerading as an empty search.
         #
-        # @param html [String] HTML document body from html.duckduckgo.com
-        # @param max_results [Integer] maximum number of result entries
-        # @return [Array<Result>] hits, possibly empty on a genuine
-        #   no-results page
-        # @raise [Engines::Unavailable] when the page is the DDG
-        #   anomaly/CAPTCHA modal (IP soft-block) — a "try again later" the
-        #   cascade can fall back from.
-        # @raise [RuntimeError] when the page contains no result nodes and is
-        #   not recognized as either a genuine no-results page or the
-        #   anomaly modal (likely a layout change worth surfacing loudly).
+        # @param html [String] HTML from html.duckduckgo.com
+        # @param max_results [Integer] max result entries
+        # @return [Array<Result>] hits, possibly empty on a genuine no-results page
+        # @raise [Engines::Unavailable] on the anomaly/CAPTCHA modal (IP soft-block)
+        # @raise [RuntimeError] on zero results with an unrecognized layout
         def self.parse(html, max_results: DEFAULT_MAX_RESULTS)
           doc = Nokogiri::HTML(html)
           results = doc.css('div.result.web-result').take(max_results).filter_map do |node|
@@ -133,25 +106,22 @@ module Pikuri
           results
         end
 
-        # True when the page contains DDG's anomaly/CAPTCHA modal — i.e. the
-        # IP has been soft-blocked. Used by {.parse} to pick between
-        # {Engines::Unavailable} (recoverable, fall back to another
-        # provider) and {RuntimeError} (unknown layout, surface loudly).
+        # True when the page is DDG's anomaly/CAPTCHA modal (IP soft-blocked).
+        # {.parse} uses it to pick {Engines::Unavailable} (recoverable) over
+        # {RuntimeError} (unknown layout).
         #
-        # @param doc [Nokogiri::HTML::Document] parsed result page
+        # @param doc [Nokogiri::HTML::Document]
         # @return [Boolean]
         def self.anomaly_modal?(doc)
           !!(doc.at_css('.anomaly-modal__title') || doc.at_css('.anomaly-modal__description'))
         end
         private_class_method :anomaly_modal?
 
-        # True when a results page with zero result nodes looks like DDG's own
-        # "no results found" page (narrow query) rather than an anomaly/CAPTCHA
-        # or other non-results layout. Anomaly modal wins: if the modal divs
-        # are present we never treat the page as a genuine empty result, even
-        # if the surrounding text happens to mention "No results".
+        # True when a zero-node page is DDG's own "no results found" page, not an
+        # anomaly/CAPTCHA. Anomaly wins: if the modal divs are present it's never
+        # a genuine empty result, even if the text mentions "No results".
         #
-        # @param doc [Nokogiri::HTML::Document] parsed result page
+        # @param doc [Nokogiri::HTML::Document]
         # @return [Boolean]
         def self.genuine_no_results?(doc)
           return false if doc.at_css('.anomaly-modal__title') || doc.at_css('.anomaly-modal__description')
@@ -161,14 +131,12 @@ module Pikuri
         end
         private_class_method :genuine_no_results?
 
-        # Build an error message for a results page that yielded zero matches.
-        # Recognizes the DDG anomaly modal explicitly and quotes its title and
-        # description; otherwise extracts visible text from the body (with
-        # +<script>+/+<style>+/+<noscript>+ stripped and whitespace collapsed)
-        # and includes a truncated copy so the caller can see what came back.
+        # Build an error message for a zero-match page: quote the DDG anomaly
+        # modal's title/description if present, else a truncated copy of the
+        # body's visible text (+<script>/<style>/<noscript>+ stripped).
         #
-        # @param doc [Nokogiri::HTML::Document] parsed result page
-        # @return [String] human-readable diagnostic to feed to +raise+
+        # @param doc [Nokogiri::HTML::Document]
+        # @return [String] diagnostic to feed to +raise+
         def self.diagnose_empty(doc)
           title = doc.at_css('.anomaly-modal__title')&.text&.strip
           desc  = doc.at_css('.anomaly-modal__description')&.text&.strip
@@ -184,12 +152,12 @@ module Pikuri
         end
         private_class_method :diagnose_empty
 
-        # Decode DuckDuckGo's +//duckduckgo.com/l/?uddg=<encoded>+ redirect wrapper
-        # back to the real target URL.
+        # Decode DDG's +//duckduckgo.com/l/?uddg=<encoded>+ redirect wrapper to
+        # the real target URL.
         #
-        # @param href [String, nil] href as found on the search-result page
-        # @return [String] the decoded target URL, or +href+ unchanged when it is
-        #   not a recognized DDG redirect or cannot be parsed
+        # @param href [String, nil] href from the result page
+        # @return [String] the decoded target, or +href+ unchanged when not a
+        #   recognized DDG redirect or unparseable
         def self.extract_url(href)
           return href if href.nil? || href.empty?