pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/trifecta/report.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Trifecta
+    # The result of walking one agent tree: a {Node} with its legs folded — its
+    # own tools unioned with everything propagated up from its sub-agents. What
+    # {Pikuri::Trifecta.walk} returns, mirroring the tree shape so a host can
+    # both classify and display it:
+    #
+    #   report = Pikuri::Trifecta.walk(node)
+    #   report.tree_verdict                  # => :soft
+    #   report.worst_path.map(&:label)       # => ["pikuri-computer", "RESEARCHER"]
+    #   puts report.render                   # the human-readable map
+    #
+    # == Implementation details
+    #
+    # {#verdict} is *derived, never stored*: +Data#with+ would otherwise let a
+    # copy carry a severity that contradicts its own legs. It reads presence
+    # (leg-absence, correct for any level ever added) and matches strength
+    # exhaustively across all three graded axes, so introducing a lattice level
+    # without placing it in the grid raises on the first wiring that reaches it
+    # rather than being silently absorbed into +:soft+.
+    #
+    # Immutable.
+    #
+    # @!attribute [r] label
+    #   @return [String] this agent's name (see {Node#label})
+    # @!attribute [r] legs
+    #   @return [Pikuri::Tool::TrifectaLegs] folded legs — own tools plus
+    #     everything propagated up from {#children}. What {#verdict} reads.
+    # @!attribute [r] tool_legs
+    #   @return [Hash{String=>Pikuri::Tool::TrifectaLegs}] carried through from
+    #     the {Node} so {#render} can print the tools as leaves
+    # @!attribute [r] children
+    #   @return [Array<Report>] one per sub-agent, already walked
+    # @!attribute [r] channel_egress
+    #   @return [Symbol, nil] the parent edge's gate level (see
+    #     {Node#channel_egress})
+    class Report < Data.define(:label, :legs, :tool_legs, :children, :channel_egress)
+      # Verdicts, least to most severe. The only ordering outside
+      # {Pikuri::Tool::TrifectaLegs}.
+      #
+      # @return [Array<Symbol>]
+      SEVERITY = %i[silent soft loud].freeze
+
+      # Closing pointer of {#advisory}. Names the chapter by *slug*, not by
+      # ordinal: book chapters are ordered only by `book/README.md`, so this
+      # path survives a reordering that would silently falsify a number.
+      #
+      # @return [String]
+      FOOTER = 'See book/trifecta-detector.md in this repo.'
+
+      # How dangerous *this node* is — the tree's verdict is {#tree_verdict}.
+      #
+      # +:loud+ needs all three legs at full strength; +:soft+ is any complete
+      # trifecta whose untrusted or egress leg is attenuated; +:silent+ is a
+      # missing leg. Absence of a warning is not evidence of safety: this
+      # reasons about capability presence, not data flow.
+      #
+      # @return [Symbol] +:silent+, +:soft+ or +:loud+
+      # @raise [NoMatchingPatternError] if a lattice level exists that this grid
+      #   does not place — deliberate, so a new level cannot be absorbed silently
+      def verdict
+        return :silent unless legs.private && legs.untrusted != :none && legs.egress?
+
+        case [legs.untrusted, legs.egress_payload_review, legs.egress_destination]
+        in [:hard,     :unreviewed,      :attacker_reachable] then :loud
+        in [:hard,     :unreviewed,      :tool_vouched]       then :soft
+        in [:hard,     :human_reviewed,  :attacker_reachable] then :soft
+        in [:hard,     :human_reviewed,  :tool_vouched]       then :soft
+        in [:weakened, :unreviewed,      :attacker_reachable] then :soft
+        in [:weakened, :unreviewed,      :tool_vouched]       then :soft
+        in [:weakened, :human_reviewed,  :attacker_reachable] then :soft
+        in [:weakened, :human_reviewed,  :tool_vouched]       then :soft
+        end
+      end
+
+      # Root-first path of Reports down to the most severe node in this subtree,
+      # so the caller can both attribute the finding and read its cell:
+      #
+      #   path = report.worst_path
+      #   path.map(&:label).join(' -> ')   # => "pikuri-computer -> RESEARCHER"
+      #   path.last.legs                   # the cell that decided the verdict
+      #
+      # Ties go to the node encountered first in pre-order — the parent over its
+      # own children, since a parent's trifecta is the more actionable finding.
+      #
+      # @return [Array<Report>] never empty; +[self]+ when nothing below is worse
+      def worst_path
+        best = [self]
+        children.each do |child|
+          candidate = [self, *child.worst_path]
+          best = candidate if SEVERITY.index(candidate.last.verdict) > SEVERITY.index(best.last.verdict)
+        end
+        best
+      end
+
+      # @return [Symbol] the most severe {#verdict} anywhere in this subtree
+      def tree_verdict = worst_path.last.verdict
+
+      # The human-readable map: one line per agent and per tool, indented by
+      # depth, with each entry's legs as tags.
+      #
+      #   Trifecta: soft
+      #
+      #   pikuri-computer [:private, :untrusted_hard, :egress_reviewed]
+      #     mail_compose [:private, :egress_reviewed]
+      #     calculator []
+      #     RESEARCHER [gate: human_reviewed] [:untrusted_hard, :egress]
+      #       fetch [:untrusted_hard, :egress]
+      #
+      #   See book/trifecta-detector.md in this repo for ...
+      #
+      # An agent line carries its *folded* legs and a tool line its own, so
+      # propagation shows up as layout: the parent above holds egress that no
+      # tool of its own contributes. Plain text by design — a host wanting color
+      # or width walks this tree itself rather than asking for styled output.
+      #
+      # @return [String] newline-separated, no trailing newline
+      def render
+        [advisory, '', *render_lines].join("\n")
+      end
+
+      # The one-line conclusion: what was found, where, and the leg to break.
+      # Separate from {#render} because a status line wants this without the
+      # tree, and because it is the half that carries *meaning* — the map
+      # deliberately carries only facts.
+      #
+      #   [TRIFECTA: HARD] pikuri-code — private(read, bash) + untrusted(read,
+      #   bash) + egress(bash). An injection in what this agent reads can drive
+      #   an exfiltration. Break a leg: sever egress (a network-off sandbox), or
+      #   privilege-separate the step that reads untrusted content.
+      #   See book/trifecta-detector.md in this repo.
+      #
+      # A clean verdict never says "no trifecta detected". This reasons about
+      # capability presence, so a quiet result is not a clean bill of health —
+      # it under-warns on a single tool that is all three internally, and on
+      # private data staged into a file by one tool and read by another.
+      # Reporting the *finding* names what would tip the wiring over and claims
+      # nothing it cannot support.
+      #
+      # @return [String]
+      def advisory
+        path = worst_path
+        where = path.map(&:label).join(' -> ')
+        legs = path.last.legs
+        return "Trifecta: #{where} — #{presence(legs)}." if tree_verdict == :silent
+
+        "[TRIFECTA: #{tree_verdict == :loud ? 'HARD' : 'soft'}] #{where} — " \
+          "#{attribution(path.last)}. An injection in what this agent reads can drive " \
+          "an exfiltration. Break a leg: #{advice(legs)}. #{FOOTER}"
+      end
+
+      protected
+
+      # @param depth [Integer] indentation level
+      # @return [Array<String>]
+      def render_lines(depth = 0)
+        indent = '  ' * depth
+        gate = channel_egress ? " [gate: #{channel_egress}]" : ''
+        lines = ["#{indent}#{label}#{gate} #{legs.to_tags.inspect}"]
+        tool_legs.each { |name, tool| lines << "#{indent}  #{name} #{tool.to_tags.inspect}" }
+        children.each { |child| lines.concat(child.render_lines(depth + 1)) }
+        lines
+      end
+
+      private
+
+      # @param legs [Pikuri::Tool::TrifectaLegs]
+      # @return [String] e.g. +"2 of 3 legs (private, untrusted); no egress leg found"+
+      def presence(legs)
+        held = { 'private' => legs.private, 'untrusted' => legs.untrusted != :none,
+                 'egress' => legs.egress? }
+        "#{held.count { |_, v| v }} of 3 legs (#{held.select { |_, v| v }.keys.join(', ')}); " \
+          "no #{held.reject { |_, v| v }.keys.join('/')} leg found"
+      end
+
+      # Which tool contributed each leg, so the line names something the reader
+      # can actually go and change.
+      #
+      # @param node [Report]
+      # @return [String]
+      def attribution(node)
+        %i[private untrusted egress].filter_map do |axis|
+          contributors = node.tool_legs.select { |_, l| leg_present?(l, axis) }.keys
+          "#{axis}(#{contributors.join(', ')})" unless contributors.empty?
+        end.join(' + ')
+      end
+
+      # @param legs [Pikuri::Tool::TrifectaLegs]
+      # @param axis [Symbol] +:private+, +:untrusted+ or +:egress+
+      # @return [Boolean]
+      def leg_present?(legs, axis)
+        case axis
+        in :private then legs.private
+        in :untrusted then legs.untrusted != :none
+        in :egress then legs.egress?
+        end
+      end
+
+      # The fix, per cell of the verdict grid — the soft cells want different
+      # answers, which is why this reads the legs rather than the verdict symbol.
+      #
+      # @param legs [Pikuri::Tool::TrifectaLegs]
+      # @return [String]
+      def advice(legs)
+        # A vouched destination is fragile in a way the other attenuations are
+        # not: it survives only while it is the *sole* egress leg, since the
+        # union hardens the whole node the moment one attacker-reachable tool
+        # joins it. Say so, rather than let the soft verdict read as settled.
+        if legs.egress_destination == :tool_vouched
+          return 'sever egress outright — bytes still leave, they merely reach a destination the ' \
+                 'attacker cannot read back, and one attacker-reachable tool re-hardens this node'
+        end
+
+        case [legs.untrusted, legs.egress_payload_review]
+        in [:hard, :unreviewed]
+          'sever egress (a network-off sandbox), or privilege-separate the step that reads untrusted content'
+        in [:hard, _]
+          'privilege-separate the step that reads untrusted content, or declare the workspace trusted ' \
+            'if you vouch for every byte it can reach'
+        in [:weakened, :unreviewed]
+          'sever egress — the untrusted leg is already attenuated by delegation'
+        in [:weakened, _]
+          'both legs are already attenuated; narrow what counts as private, or drop a leg outright'
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/trifecta.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # The lethal-trifecta detector: does one agent simultaneously hold private
+  # data, exposure to attacker-influenceable content, and a way to send bytes
+  # out? Any two legs are fine; all three is the live wire, because an injection
+  # hidden in the untrusted content can drive the exfiltration.
+  #
+  # Build a {Node} tree — the agent, its tools, its sub-agents — and walk it:
+  #
+  #   report = Pikuri::Trifecta.walk(node)
+  #   report.tree_verdict   # => :loud
+  #   puts report.render    # the map a bin script prints
+  #
+  # Nothing here reports itself. Core computes the picture and stops; surfacing
+  # it belongs to whoever has a screen ({Pikuri::Agent#trifecta} is the reader).
+  # A library writing to a log its embedder never asked for is noise, and a
+  # once-per-process guard would be worse than silence in a host that builds
+  # two differently-wired agents: it would report the first and stay quiet
+  # about the second, which reads as coverage.
+  #
+  # == This is a smoke alarm, not a firewall
+  #
+  # It reasons about *capability presence*, never data flow, so it both
+  # over-warns (an egress query too narrow to carry anything) and under-warns
+  # (one tool that is all three internally; private data staged into a file by
+  # one tool and read out by another). It can prove you hold the ingredients. It
+  # can prove neither that you are exploitable nor that you are safe — which is
+  # why nothing here ever blocks execution, and why the absence of a warning is
+  # never reported as an assurance.
+  #
+  # == Implementation details
+  #
+  # {.walk} is a pure function of the tree, so the whole rule set is testable
+  # from hand-built {Node}s with no agent, no LLM and no sandbox probe.
+  #
+  # Two operations move legs between nodes, and their asymmetry is the design:
+  # +max+ in *parallel* (legs meeting at one node, {Pikuri::Tool::TrifectaLegs#|})
+  # and +min+ in *series* (a leg squeezed through a delegation channel,
+  # {Pikuri::Tool::TrifectaLegs#cap_payload_review}). Severity is evaluated at every node
+  # rather than only at the root, and the tree's verdict is the max over all of
+  # them — which localizes a finding to the agent that actually holds it instead
+  # of smearing a sub-agent's danger across its parent.
+  module Trifecta
+    class << self
+      # Assemble the tree for a wired agent: its own tools, plus whatever each
+      # extension contributes ({Pikuri::Agent::Extension#trifecta_contribution}
+      # — legs no tool can declare, and a child per sub-agent persona).
+      #
+      # @param agent [Pikuri::Agent] a *wired* agent (after the bind sweep, so
+      #   dynamically-added tools are present)
+      # @param label [String] name for the root node; defaults to the running
+      #   program, which is what a host wants in a boot banner
+      # @return [Node]
+      def build(agent, label: File.basename($PROGRAM_NAME))
+        # The root node holds +tools+ ONLY. +sub_agent_tools+ are registered for
+        # personas and never reach the parent's LLM — crediting the parent with
+        # them reports the sub-agent quarantine as broken, which is the one
+        # false alarm guaranteed to get this advisory muted, since that
+        # quarantine is the defense the loudest wirings are built around.
+        #
+        # The *hook* gets both, because a persona resolves its +tool_names+
+        # against either list.
+        #
+        # A tool neither list places — registered on the sub-agent pool and
+        # named by no persona — therefore appears nowhere in the tree, and gets
+        # no line of its own. Deliberate: nothing here can call it, so it is the
+        # absence of a capability rather than one, and it can never explain a
+        # verdict. The reverse direction *is* a bug and fails loudly elsewhere —
+        # {Pikuri::SubAgent::Extension#configure} raises on a persona naming an
+        # unregistered tool. See +D_trifecta_map_orphans+.
+        contributions = agent.extensions.filter_map do |ext|
+          if ext.respond_to?(:trifecta_contribution)
+            ext.trifecta_contribution(agent.tools + agent.sub_agent_tools)
+          end
+        end
+
+        tool_legs = agent.tools.to_h { |t| [t.name, t.trifecta_legs] }
+        contributions.each do |contribution|
+          next if contribution.legs == Tool::TrifectaLegs::NONE
+
+          previous = tool_legs[contribution.label] || Tool::TrifectaLegs::NONE
+          tool_legs[contribution.label] = previous | contribution.legs
+        end
+
+        Node.new(label: label, tool_legs: tool_legs,
+                 children: contributions.flat_map(&:children))
+      end
+
+      # Fold a {Node} tree into a {Report} tree: each node's own tools unioned,
+      # then every sub-agent's legs propagated up.
+      #
+      # @param node [Node] root of the tree, usually the main agent
+      # @return [Report] mirrors the input tree, legs folded
+      def walk(node)
+        children = node.children.map { |child| walk(child) }
+        legs = node.tool_legs.values.reduce(Tool::TrifectaLegs::NONE) { |acc, tool| acc | tool }
+        legs = children.reduce(legs) { |acc, child| acc | propagated(child) }
+
+        Report.new(label: node.label, legs: legs, tool_legs: node.tool_legs,
+                   children: children, channel_egress: node.channel_egress)
+      end
+
+      private
+
+      # What +child+ contributes to its parent: untrusted attenuated by the
+      # boundary, egress capped by the gate on the delegation channel.
+      #
+      # The cap is skipped when the child holds private data of its own, and
+      # that precondition is load-bearing rather than a nicety. A child with
+      # file tools can be handed an innocuous approved task, read secrets
+      # *after* the gate, and egress a derivative of bytes no human ever saw —
+      # so the channel no longer bounds what can leave.
+      #
+      # @param child [Report]
+      # @return [Pikuri::Tool::TrifectaLegs]
+      def propagated(child)
+        contribution = child.legs.relabel_inbound
+        return contribution if child.legs.private
+
+        # A child with no recorded edge is treated as ungated: absent evidence
+        # of a gate is not evidence of one.
+        contribution.cap_payload_review(child.channel_egress || :unreviewed)
+      end
+    end
+  end
+end

data/lib/pikuri/url_cache.rb

@@ -4,52 +4,39 @@ require 'digest'
 require 'fileutils'
 
 module Pikuri
-  # On-disk cache for string-keyed text payloads. Used by the bundled tools
-  # to avoid re-fetching the same page or re-issuing the same web-search
-  # query within a TTL window: {Tool::WebScrape.visit} caches the rendered
-  # Markdown for a URL, and {Tool::Search::Engines.search} caches the
-  # rendered result list for a query (the query string itself acts as the
-  # key — keys are SHA-256 hashed, so any opaque string works).
+  # On-disk cache for string-keyed text payloads. The bundled tools use it to
+  # avoid re-fetching within a TTL: {Tool::WebScrape.visit} caches a URL's
+  # rendered Markdown, {Tool::Search::Engines.search} caches a query's result
+  # list (keys are SHA-256 hashed, so any opaque string works).
   #
-  # Each tool wires its own {UrlCache} instance against a dedicated
-  # subdirectory under {ROOT_DIR}, so a +web_search+ query string and a
-  # +web_scrape+ URL string can never collide on the same cache file. There
-  # is no global default singleton — pass a fresh instance to whichever
-  # code needs caching, or use {NULL} to disable caching entirely.
+  # Each tool wires its own instance against a dedicated subdir under {ROOT_DIR},
+  # so a +web_search+ query and a +web_scrape+ URL can't collide on one file.
+  # No global singleton — pass a fresh instance, or {NULL} to disable caching.
   #
-  # One file per entry, named +<sha256>.txt+ under {#initialize}'s +dir+.
-  # Freshness is tracked via the file's mtime; there is no sidecar metadata.
-  # Stale entries are simply overwritten the next time {#fetch} is called
-  # with the same key. To clear the cache, +rm -rf+ the directory.
+  # One file per entry (+<sha256>.txt+), freshness by mtime, no sidecar
+  # metadata; a stale entry is overwritten on the next {#fetch} with that key.
+  # +rm -rf+ the directory to clear it.
   #
-  # Not thread-safe: if two callers race on the same cold key, both compute
-  # and both write the same file. That is the intended tradeoff to keep this
-  # under a few dozen lines — the worst-case cost is a duplicate fetch.
+  # Sharing: +P_shared_benign+ — an instance holds only its TTL and directory,
+  # and every tool that owns one holds it in a class-level constant, so all
+  # agents (and other pikuri processes) hit the same files. If two callers race
+  # on the same cold key, both compute and both write the same bytes — the
+  # accepted tradeoff for keeping this a few dozen lines (worst case: a
+  # duplicate fetch). The cross-agent flow is deliberate: a public URL's content
+  # is nobody's private context.
   class UrlCache
-    # Root directory under which per-tool cache subdirectories live.
-    # Follows the XDG Base Directory spec: +$XDG_CACHE_HOME/pikuri/url_cache+
-    # if the env var is set to a non-empty value, else
-    # +~/.cache/pikuri/url_cache+. Each tool picks its own subdir
-    # (e.g. +"#{ROOT_DIR}/web_scrape"+) so keys from different tools cannot
-    # collide. The directory is created lazily on first cache write; pikuri
-    # does not pre-create it.
+    # Root dir for per-tool cache subdirs, per XDG:
+    # +$XDG_CACHE_HOME/pikuri/url_cache+ or +~/.cache/pikuri/url_cache+. Each
+    # tool picks its own subdir (+"#{ROOT_DIR}/web_scrape"+) so keys can't
+    # collide. Created lazily on first write.
     # @return [String]
-    ROOT_DIR = begin
-      xdg = ENV['XDG_CACHE_HOME']
-      cache_home = xdg && !xdg.empty? ? xdg : File.join(Dir.home, '.cache')
-      File.join(cache_home, 'pikuri', 'url_cache')
-    end.freeze
+    ROOT_DIR = Paths.cache.join('url_cache').to_path
 
-    # Default freshness window: 2 hours, in seconds.
-    #
-    # Long enough to cover a single interactive session — revisiting
-    # a scraped page or re-running a similar search within the same
-    # working window hits the cache. Short enough that resuming the
-    # next day doesn't serve stale news, docs, or search results.
-    # Reference points: opencode keeps no cache, the +pi-web-fetch+
-    # community extension uses 15 minutes, +pi-web-search+ uses 5;
-    # 2 hours sits comfortably above the "single follow-up" window
-    # those numbers are aimed at without holding content across days.
+    # Default freshness window: 2 hours. Long enough to cover an interactive
+    # session (revisiting a page or re-running a search within the working
+    # window hits the cache), short enough that resuming the next day doesn't
+    # serve stale results. (opencode caches nothing; +pi-web-fetch+ uses 15 min,
+    # +pi-web-search+ 5.)
     # @return [Integer]
     DEFAULT_TTL = 2 * 60 * 60
 
@@ -62,13 +49,11 @@ module Pikuri
       @dir = dir
     end
 
-    # Return the cached payload for +url+ if a fresh entry exists, otherwise
-    # yield to compute it, persist the result, and return it.
-    #
-    # The block is only invoked on a miss. If the block raises, no file is
-    # written — errors are not cached.
+    # Return the cached payload for +url+ if fresh, else yield to compute it,
+    # persist, and return. The block runs only on a miss; if it raises, no file
+    # is written (errors aren't cached).
     #
-    # @param url [String] cache key; a URL or any opaque string identifier
+    # @param url [String] cache key; a URL or any opaque string
     # @yieldreturn [String] payload to store and return on a miss
     # @return [String] cached or freshly-computed payload
     def fetch(url)
@@ -94,9 +79,8 @@ module Pikuri
       File.join(@dir, "#{Digest::SHA256.hexdigest(url)}.txt")
     end
 
-    # Null cache: a drop-in replacement that always misses and never
-    # persists. Use this in tests (or anywhere else you want caching off)
-    # without giving up the {UrlCache#fetch} contract.
+    # Null cache: always misses, never persists — a drop-in for tests (or
+    # anywhere caching should be off) keeping the {UrlCache#fetch} contract.
     NULL = Object.new
     # Singleton +fetch+ on {NULL} that mirrors {UrlCache#fetch}'s shape:
     # ignores +_key+, always yields, never persists.

data/lib/pikuri/version.rb

@@ -6,5 +6,5 @@ module Pikuri
   # additions to the public surface (+Pikuri::Tool+ / +Pikuri::Agent+ /
   # listeners / bundled tools), major for breaking changes to that
   # surface or to the +bin/pikuri-*+ CLIs.
-  VERSION = '0.0.7'
+  VERSION = '0.1.0'
 end