pikuri-core 0.0.7 → 0.1.0

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

@@ -7,23 +7,47 @@ module Pikuri
     module Search
       # Thread-safe pacing + circuit-breaker wrapper for a search provider.
       #
-      # +#call { ... }+ enforces a minimum interval between consecutive
-      # invocations of the block (sleeping if the previous one was too
-      # recent), and watches for {Engines::Unavailable} raised by the
-      # block: when that happens, a cooldown deadline is recorded and
-      # further calls within the window raise {Engines::Unavailable}
-      # immediately without invoking the block. This stops a provider
-      # that has been rate-limited or bot-blocked from being hammered
-      # with retries.
+      # +#call { ... }+ enforces a minimum interval between block invocations
+      # (sleeping if the previous was too recent) and watches for
+      # {Engines::Unavailable}: on one, a cooldown deadline is recorded and
+      # further calls within the window raise {Engines::Unavailable} immediately
+      # without running the block — so a rate-limited or bot-blocked provider
+      # isn't hammered with retries.
       #
-      # The mutex is held across the block, so concurrent callers
-      # serialize — matching the behavior {DuckDuckGo} has always
-      # required to keep its IP-spacing throttle correct under
-      # concurrent agents.
+      # Uses wall-clock {Time.now}, not monotonic: the intervals (1s–5min) are
+      # well above any NTP step, and {Time.now} keeps tests fakeable with
+      # Timecop.
       #
-      # Uses wall-clock {Time.now} rather than the monotonic clock; the
-      # intervals here are 1s–5min, well above any realistic NTP step,
-      # and {Time.now} keeps tests trivially fakeable with Timecop.
+      # == Sharing
+      #
+      # +P_shared_locked+, and sharing is *mandatory*: a limiter must be scoped
+      # to the resource it protects, which here is one egress IP and one API
+      # key's quota — never one agent. Hence each provider holds its limiter in
+      # a class-level constant, so every agent in the VM queues behind the same
+      # one. Per-agent limiters would let ten agents fire ten simultaneous
+      # requests from one IP and earn exactly the ban this class exists to
+      # avoid. (Contrast {Pikuri::Agent::Listener::RateLimited}, which paces one
+      # renderer's repaints and is therefore per listener chain.)
+      #
+      # Two consequences of that scope, both correct and both surprising:
+      #
+      # * **It is a global queue, not just a pacer.** The mutex is held across
+      #   the block — the HTTP call included — so ten agents searching at once
+      #   serialize, with no timeout and no queue position. +cancellable:+
+      #   covers the *pacing wait*, which is what the lock holder is doing; a
+      #   caller still parked in +Mutex#synchronize+ waiting to acquire cannot
+      #   observe its own cancel. It does still benefit, because every agent
+      #   that cancels releases early and drains the queue faster. Making the
+      #   acquisition itself interruptible means polling +Mutex#try_lock+ with
+      #   explicit +lock+/+unlock+ — deliberately not built for a
+      #   three-concurrent-agent case nothing has yet.
+      # * **The circuit breaker is global too.** One agent tripping the
+      #   provider's soft-block puts every other agent into the same cooldown.
+      #   Right, because the block is IP-wide and the others were blocked
+      #   anyway — but from the host's side nine agents lose a provider for
+      #   something the tenth did.
+      #
+      # Thread-safe.
       class RateLimiter
         # @param min_interval [Float] minimum seconds between consecutive
         #   block invocations. {#call} sleeps if a previous call was more
@@ -39,20 +63,30 @@ module Pikuri
           @cooldown_until = nil
         end
 
-        # Run the given block subject to throttle and cooldown rules.
+        # Run the block subject to the throttle and cooldown rules, with the
+        # mutex held (only one block runs at a time per limiter). If it raises
+        # {Engines::Unavailable}, cooldown is armed and the exception re-raised;
+        # any other exception bubbles up without arming cooldown.
         #
-        # The block is invoked with the mutex held, so concurrent calls
-        # serialize: only one block runs at a time per limiter instance.
-        # If the block raises {Engines::Unavailable}, the cooldown is
-        # armed and the exception is re-raised. Any other exception
-        # bubbles up without arming cooldown — only "try again later"
-        # signals from the provider are treated as backoff triggers.
+        # The pacing wait happens *through* +cancellable+, so the calling agent
+        # can abandon it on a user cancel. It is a per-call argument rather than
+        # constructor state because one limiter serves every agent in the VM
+        # (see +== Sharing+) while a token belongs to one of them — and it is
+        # always a real token, defaulting to
+        # {Pikuri::Agent::Control::Cancellable::NEVER} rather than +nil+, so
+        # there is one wait path instead of two.
         #
-        # @yieldreturn [Object] block's return value is passed through
+        # @param cancellable [Pikuri::Agent::Control::Cancellable] waited
+        #   through instead of +Kernel#sleep+.
+        # @yieldreturn [Object] passed through
         # @return [Object] whatever the block returned
-        # @raise [Engines::Unavailable] either re-raised from the block,
-        #   or raised directly when the limiter is currently in cooldown
-        def call
+        # @raise [Engines::Unavailable] re-raised from the block, or raised
+        #   directly when the limiter is in cooldown
+        # @raise [Pikuri::Agent::Control::Cancellable::Cancelled] if
+        #   +cancellable+ trips before or during the pacing wait; the block does
+        #   not run and the mutex is released, so the agents queued behind this
+        #   one advance immediately.
+        def call(cancellable: Pikuri::Agent::Control::Cancellable::NEVER)
           @mutex.synchronize do
             now = Time.now
             if @cooldown_until && now < @cooldown_until
@@ -62,7 +96,7 @@ module Pikuri
 
             if @last_call_at
               elapsed = now - @last_call_at
-              sleep_for(@min_interval - elapsed) if elapsed < @min_interval
+              cancellable.sleep(@min_interval - elapsed) if elapsed < @min_interval
             end
             @last_call_at = Time.now
 
@@ -75,17 +109,6 @@ module Pikuri
           end
         end
 
-        # Sleep for +seconds+. Isolated as a private method so tests can
-        # override it on a single instance (typically to advance a frozen
-        # Timecop clock by the same amount) without monkey-patching the
-        # global +sleep+.
-        #
-        # @param seconds [Float] non-negative duration to sleep
-        # @return [void]
-        def sleep_for(seconds)
-          sleep(seconds)
-        end
-        private :sleep_for
       end
     end
   end

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

@@ -3,26 +3,21 @@
 module Pikuri
   class Tool
     module Search
-      # A single search hit produced by a {Tool::Search} provider
-      # ({DuckDuckGo}, {Brave}, {Exa}). Providers return +Array<Result>+
-      # from +.parse+ / +.search+; {Engines.search} concatenates the
-      # rows into the smolagents-style Markdown the LLM sees.
-      #
-      # Splitting structure from rendering keeps the three providers
-      # interchangeable — they only have to agree on these three fields
-      # (provider-specific extras like relevance scores or published
-      # dates are discarded today, which is fine because no caller uses
-      # them).
+      # A single search hit from a {Tool::Search} provider ({DuckDuckGo},
+      # {Brave}, {Exa}). Providers return +Array<Result>+; {Engines.search}
+      # concatenates them into the smolagents-style Markdown the LLM sees.
+      # Structure split from rendering keeps the providers interchangeable —
+      # they need only agree on these three fields (provider extras like scores
+      # or dates are discarded, since no caller uses them).
       #
       # @!attribute [r] url
       #   @return [String] absolute URL of the hit
       # @!attribute [r] title
-      #   @return [String] plain-text title, with provider-specific
-      #     highlight markup ({Brave}'s +<strong>+, {DuckDuckGo}'s
-      #     +<b>+) already stripped
+      #   @return [String] plain-text title, provider highlight markup
+      #     ({Brave}'s +<strong>+, {DuckDuckGo}'s +<b>+) already stripped
       # @!attribute [r] body
-      #   @return [String] plain-text snippet, possibly empty (e.g. an
-      #     {Exa} navigational result with no highlights)
+      #   @return [String] plain-text snippet, possibly empty (an {Exa}
+      #     navigational result with no highlights)
       Result = Data.define(:url, :title, :body)
     end
   end

data/lib/pikuri/tool/trifecta_legs.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # Which of the lethal trifecta's three legs a tool contributes — private
+    # data in, attacker-influenceable content in, bytes out. A tool declares its
+    # legs in its own constructor, where every collaborator that decides them
+    # (workspace, sandbox, confirmer) is already a kwarg:
+    #
+    #   super(name: 'read', ..., trifecta_legs: Tool::TrifectaLegs.new(
+    #     private:   fs.private?,
+    #     untrusted: fs.trusted? ? :none : :hard,
+    #     egress_payload_review: :no_egress))
+    #
+    # {Pikuri::Trifecta} unions these across an agent's tools and folds in its
+    # sub-agents to decide whether all three legs are live at one node.
+    #
+    # == Implementation details
+    #
+    # Three axes are graded rather than boolean, and this class is the only
+    # place their ordering lives: {#|} takes the per-axis +max+ (legs meeting at
+    # one node), {#cap_payload_review} the +min+ (a leg squeezed through a
+    # delegation channel), and {#relabel_inbound} applies the one fixed demotion
+    # a sub-agent boundary buys. Nothing else may compare levels — the verdict
+    # reads presence and top-ness only (see {Pikuri::Trifecta::Report#verdict}).
+    #
+    # The egress leg is *two* axes because they are orthogonal: an unreviewed
+    # query to a vouched engine and a human-reviewed send to an attacker's inbox
+    # are different animals, and neither dominates the other. Both carry
+    # +:no_egress+ at the bottom and the constructor keeps them coherent, so the
+    # leg is present on both or on neither ({#egress?} is the canonical read).
+    #
+    # Immutable.
+    #
+    # @!attribute [r] private
+    #   @return [Boolean] reads data that may be sensitive. The framework cannot
+    #     know this — sensitivity is a property of the data, not of the tool — so
+    #     the user declares it on the workspace/corpus and the tool inherits it.
+    # @!attribute [r] untrusted
+    #   @return [Symbol] +:none+, +:weakened+ (reached this agent through a
+    #     sub-agent, whose summarization relays an injected instruction as a
+    #     reported fact) or +:hard+ (verbatim into this agent's context).
+    # @!attribute [r] egress_payload_review
+    #   Answers: did a human see the bytes that leave?
+    #
+    #   @return [Symbol] +:no_egress+, +:human_reviewed+ (the payload *is* the
+    #     reviewed artifact — a compose window, an editable task string) or
+    #     +:unreviewed+, which covers both no human at all and a human who saw
+    #     only a proxy: approving +curl+ approves a program, and the bytes it
+    #     sends are computed after the click.
+    # @!attribute [r] egress_destination
+    #   Answers: if an injection hijacks the model, can it reach the attacker?
+    #
+    #   @return [Symbol] +:no_egress+; +:attacker_reachable+ — the caller picks
+    #     the host, *or* a fixed sink republishes what it receives (a hard-coded
+    #     +gist.github.com+ POST is pinned and world-readable, so pinning alone
+    #     buys nothing); or +:tool_vouched+, declarable iff the caller cannot
+    #     choose the destination, that destination does not republish, and the
+    #     request is not attacker-readable in flight or at rest. Unverifiable by
+    #     the framework: like +private+, it is a declaration it inherits.
+    class TrifectaLegs < Data.define(:private, :untrusted, :egress_payload_review, :egress_destination)
+      # Danger order, least to most: +max+ is union at a node, +min+ is the cap
+      # through a delegation channel.
+      #
+      # @return [Array<Symbol>]
+      UNTRUSTED_ORDER = %i[none weakened hard].freeze
+
+      # @return [Array<Symbol>] danger order, least to most (see {UNTRUSTED_ORDER})
+      EGRESS_REVIEW_ORDER = %i[no_egress human_reviewed unreviewed].freeze
+
+      # @return [Array<Symbol>] danger order, least to most (see {UNTRUSTED_ORDER})
+      EGRESS_DESTINATION_ORDER = %i[no_egress tool_vouched attacker_reachable].freeze
+
+      # @param private [Boolean]
+      # @param untrusted [Symbol] one of {UNTRUSTED_ORDER}
+      # @param egress_payload_review [Symbol] one of {EGRESS_REVIEW_ORDER}
+      # @param egress_destination [Symbol, nil] one of {EGRESS_DESTINATION_ORDER};
+      #   omit to derive — +:no_egress+ without a leg, else the pessimistic
+      #   +:attacker_reachable+, so silence never buys the softer grade.
+      # @raise [ArgumentError] on a level outside its lattice, or on the two
+      #   egress axes disagreeing about whether the leg exists at all — a typo'd
+      #   level would otherwise read as a missing leg, the one failure mode this
+      #   detector exists to refuse.
+      def initialize(private:, untrusted:, egress_payload_review:, egress_destination: nil)
+        egress_destination ||= egress_payload_review == :no_egress ? :no_egress : :attacker_reachable
+        check!(untrusted, UNTRUSTED_ORDER, 'untrusted')
+        check!(egress_payload_review, EGRESS_REVIEW_ORDER, 'egress review')
+        check!(egress_destination, EGRESS_DESTINATION_ORDER, 'egress destination')
+        unless (egress_payload_review == :no_egress) == (egress_destination == :no_egress)
+          raise ArgumentError, 'egress axes disagree on whether the leg exists: ' \
+                               "#{egress_payload_review.inspect} / #{egress_destination.inspect}"
+        end
+
+        super(private: private, untrusted: untrusted, egress_payload_review: egress_payload_review,
+              egress_destination: egress_destination)
+      end
+
+      # Union: the strongest value on each axis wins.
+      #
+      #   read_legs | bash_legs   # what an agent holding both ends up with
+      #
+      # @param other [TrifectaLegs]
+      # @return [TrifectaLegs]
+      def |(other)
+        # Per-axis, so web_search (unreviewed, vouched) beside a compose tool
+        # (reviewed, attacker-reachable) scores a cell neither occupies. Pairing
+        # them up instead would be data flow, which this detector refuses to
+        # model; over-warning is the declared bias.
+        TrifectaLegs.new(
+          private: private || other.private,
+          untrusted: [untrusted, other.untrusted].max_by { UNTRUSTED_ORDER.index(_1) },
+          egress_payload_review: [egress_payload_review, other.egress_payload_review]
+            .max_by { EGRESS_REVIEW_ORDER.index(_1) },
+          egress_destination: [egress_destination, other.egress_destination]
+            .max_by { EGRESS_DESTINATION_ORDER.index(_1) }
+        )
+      end
+
+      # @return [Boolean] whether this contributes an egress leg at all. The
+      #   canonical presence read, since both egress axes encode absence.
+      def egress? = egress_payload_review != :no_egress
+
+      # These legs as they reach a *parent* across a sub-agent boundary: +:hard+
+      # untrusted demotes to +:weakened+, the other three axes are identity.
+      #
+      # The boundary filters *instructions*, not *content* — a faithful summary
+      # preserves the page's facts but has no reason to adopt an out-of-band
+      # imperative, so an injection arrives as a reported fact rather than as a
+      # command. Private data survives intact (a summary of a secret still
+      # contains the secret), and egress survives because the parent can simply
+      # ask the child to send the thing.
+      #
+      # @return [TrifectaLegs]
+      def relabel_inbound
+        # Saturating, not one-rung-down: :weakened stays :weakened. Decrementing
+        # per hop would launder a grandchild's untrusted content to :none at
+        # depth three — two summarizers are no more instruction-resistant than
+        # one, and that is the structural claim this design refuses to make.
+        with(untrusted: untrusted == :hard ? :weakened : untrusted)
+      end
+
+      # These legs with the *review* axis capped at what the delegation channel
+      # itself allows — +min+ in series, the counterpart to {#|}'s +max+ in
+      # parallel.
+      #
+      # A child's egress cannot exceed the channel feeding it: when the only
+      # bytes crossing into the child are a task string a human approved, even a
+      # fully poisoned child can send nothing else. That holds *only* while the
+      # child has no private data of its own, so {Pikuri::Trifecta.walk} owns the
+      # precondition and this method is the mechanical +min+.
+      #
+      # {#egress_destination} is deliberately untouched: a gate bounds *what*
+      # leaves and *who saw it*, never who can read it back.
+      #
+      # @param channel_level [Symbol] one of {EGRESS_REVIEW_ORDER}
+      # @return [TrifectaLegs] with the leg gone entirely when the channel
+      #   carries no egress at all
+      # @raise [ArgumentError] on a level outside the lattice
+      def cap_payload_review(channel_level)
+        check!(channel_level, EGRESS_REVIEW_ORDER, 'egress review')
+        capped = [egress_payload_review, channel_level].min_by { EGRESS_REVIEW_ORDER.index(_1) }
+        return with(egress_payload_review: capped) unless capped == :no_egress
+
+        with(egress_payload_review: :no_egress, egress_destination: :no_egress)
+      end
+
+      # Symbols naming the legs actually present, in the vocabulary the docs and
+      # the rendered tree use. Absent legs are omitted, so a leg-free tool
+      # yields +[]+ rather than three +:none+ entries.
+      #
+      #   TrifectaLegs.new(private: true, untrusted: :hard,
+      #                    egress_payload_review: :no_egress).to_tags
+      #   # => [:private, :untrusted_hard]
+      #
+      # @return [Array<Symbol>]
+      def to_tags
+        tags = []
+        tags << :private if private
+        tags << :"untrusted_#{untrusted}" unless untrusted == :none
+        tags << egress_tag if egress?
+        tags
+      end
+
+      private
+
+      # @return [Symbol] +:egress+ at full strength, with +_reviewed+ /
+      #   +_vouched+ appended per attenuated axis, so the four cells name
+      #   themselves without a lookup table
+      def egress_tag
+        parts = ['egress']
+        parts << 'reviewed' if egress_payload_review == :human_reviewed
+        parts << 'vouched' if egress_destination == :tool_vouched
+        parts.join('_').to_sym
+      end
+
+      # @raise [ArgumentError] unless +value+ is a level of the +order+ lattice
+      def check!(value, order, name)
+        raise ArgumentError, "unknown #{name} level: #{value.inspect}" unless order.include?(value)
+      end
+
+      # @return [TrifectaLegs] no legs at all
+      NONE = new(private: false, untrusted: :none, egress_payload_review: :no_egress)
+
+      # What an *undeclared* tool is presumed to hold: hostile on every axis the
+      # framework could have determined for itself. Silence from a tool author is
+      # not evidence of safety.
+      #
+      # It stops short of +private: true+ deliberately — that axis is the user's
+      # to declare, and assuming it would make every wiring loud, turning a
+      # warn-only advisory into noise and getting it muted.
+      #
+      # @return [TrifectaLegs]
+      ASSUMED = new(private: false, untrusted: :hard, egress_payload_review: :unreviewed,
+                    egress_destination: :attacker_reachable)
+    end
+  end
+end

data/lib/pikuri/tool/web_scrape.rb

@@ -2,67 +2,45 @@
 
 module Pikuri
   class Tool
-    # Truncation policy and Tool spec for the +web_scrape+ tool. The actual
-    # scraping lives in {Tool::Scraper}; 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.
+    # Truncation policy and Tool spec for the +web_scrape+ tool. Scraping lives
+    # in {Tool::Scraper}; this wrapper applies a character cap and exposes the
+    # result 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.
+      # @return [Integer] default character cap on the Markdown from {.visit}.
+      #   Sized to cover most post-readability article bodies in full on the
+      #   first call, so the LLM doesn't re-request and duplicate the prefix in
+      #   its context. Genuinely long pages still get cut, and the marker invites
+      #   a deliberate larger call.
       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.
+      # @return [Integer] hard ceiling on {.visit}'s +max_chars+; requests above
+      #   it are clamped silently so the LLM can't dump an arbitrarily large page.
       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.
+      # On-disk cache for {.visit}. A method so specs can swap {UrlCache::NULL}.
       #
       # @return [UrlCache, #fetch]
       CACHE = UrlCache.new(ttl: UrlCache::DEFAULT_TTL, dir: "#{UrlCache::ROOT_DIR}/web_scrape")
-      # Accessor for {CACHE}; specs override this to swap in
-      # {UrlCache::NULL} or an isolated cache.
+      # Accessor for {CACHE}; specs swap in {UrlCache::NULL} or an isolated cache.
       #
       # @return [UrlCache, #fetch]
       def self.cache
         CACHE
       end
 
-      # Fetch +url+ via {Tool::Scraper} and truncate the rendered
-      # Markdown to +max_chars+ characters.
+      # Fetch +url+ via {Tool::Scraper} and truncate the rendered Markdown to
+      # +max_chars+. The full Markdown is cached on disk keyed by URL (repeat
+      # visits skip the network and extraction); +max_chars+ is *not* in the key
+      # (values share one entry, truncation runs after the lookup).
+      # {Scraper::FetchError} is caught outside +cache.fetch+ and returned as
+      # +"Error: ..."+ (so the LLM can retry a different URL) — never persisted;
+      # other exceptions bubble up.
       #
-      # 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
+      # @param url [String] absolute HTTP(S) URL
+      # @param max_chars [Integer] Markdown cap, clamped to +[1, {MAX_MAX_CHARS}]+;
+      #   default {DEFAULT_MAX_CHARS}. Over the cap, output is cut with a marker.
+      # @return [String] Markdown, 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.visit(url) }
@@ -71,12 +49,11 @@ module Pikuri
         "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.
+      # Cut +markdown+ to at most +max_chars+, appending a marker with the
+      # original length when truncation happens.
       #
       # @param markdown [String] full Markdown text
-      # @param max_chars [Integer] character cap; assumed already clamped
+      # @param max_chars [Integer] cap; assumed already clamped
       # @return [String]
       def self.truncate(markdown, max_chars)
         return markdown if markdown.length <= max_chars
@@ -87,9 +64,12 @@ module Pikuri
       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.
+    # Webpage download + Markdown conversion tool — a thin wrapper over
+    # {Tool::WebScrape.visit} in OpenAI tool-call shape.
+    #
+    # Sharing: +P_shared_benign+ — as {Tool::FETCH}: no per-agent state, but
+    # {WebScrape::CACHE} is process-wide and on disk, so one agent's scrape
+    # answers another's within the TTL. See {Pikuri::UrlCache}.
     #
     # @return [Tool]
     WEB_SCRAPE = new(
@@ -115,7 +95,11 @@ module Pikuri
       },
       execute: ->(url:, max_chars: WebScrape::DEFAULT_MAX_CHARS) {
         WebScrape.visit(url, max_chars: max_chars)
-      }
+      },
+      # Exactly {TrifectaLegs::ASSUMED}, and the archetype it was named for: the
+      # page is authored by whoever runs the site, and the model picks the URL,
+      # so the request is itself an outbound channel.
+      trifecta_legs: Pikuri::Tool::TrifectaLegs::ASSUMED
     )
   end
 end