pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/tool/web_search.rb

@@ -2,18 +2,38 @@
 
 module Pikuri
   class Tool
-    # Builder for the LLM-facing web-search tool. The search orchestration
-    # lives in {Tool::Search::Engines}; this module owns only the {.build}
-    # factory that wires a configured {Search::Engines} into a {Tool}.
+    # Builder for the LLM-facing web-search tool. Orchestration lives in
+    # {Tool::Search::Engines}; this owns only the {.build} factory wiring a
+    # configured {Search::Engines} into a {Tool}.
     #
-    # Unlike the stateless bundled tools (+CALCULATOR+ / +WEB_SCRAPE+ /
-    # +FETCH+, shared value constants), web_search is *host-configured*:
-    # the paid providers (Brave / Exa) join the cascade only when the host
-    # passes their API key, so the tool is built per-wiring — like
-    # {Code::Bash} — rather than handed out as a single shared constant.
-    # pikuri reads no key from the environment; the host supplies them (the
-    # bundled +bin/+ examples load a JSON config file by convention). See
-    # CLAUDE.md "Environment is not a secret store".
+    # Unlike the stateless bundled tools (shared value constants), web_search is
+    # *host-configured*: the paid providers (Brave/Exa) join the cascade only
+    # when the host passes their key, so it's built per-wiring (like
+    # {Code::Bash}), not a shared constant. pikuri reads no key from the
+    # environment — the host supplies them (CLAUDE.md "Environment is not a
+    # secret store").
+    #
+    # == Sharing
+    #
+    # +P_shared_locked+, and the interesting case: build one per agent or share
+    # one — it makes no difference to the throttling, because the pacing state
+    # is neither per agent nor per instance. Each provider's limiter is a
+    # class-level constant ({Search::DuckDuckGo::LIMITER} and friends), so all
+    # ten agents queue behind the same one. That is the only correct scope:
+    # what it protects is the egress IP and the API key's quota, and neither is
+    # per agent.
+    #
+    # What *is* per instance is trivial — the provider list and a
+    # last-logged-set memo, which can only duplicate an INFO line. The result
+    # cache ({Engines::CACHE}) is class-level as well, so one agent's search
+    # answers another's within the TTL.
+    #
+    # The consequence a host should plan for is latency, not corruption: see
+    # {Search::RateLimiter} for the serialization and the shared circuit
+    # breaker. Which is why this is the one bundled tool that opts into the
+    # per-call {Tool::ExecuteContext} (see {Pikuri::Tool}'s +== Cancellation+):
+    # an agent queued behind another agent's pacing wait can abandon it, even
+    # though the tool itself may be shared.
     module WebSearch
       # Description shown to the LLM, opencode-shape (summary + +Usage:+).
       #
@@ -25,20 +45,32 @@ module Pikuri
         - Use this to find candidate URLs, then call web_scrape on the most promising one(s) for full content. Snippets alone rarely answer a question.
       DESC
 
-      # Build the +web_search+ tool. It calls {Search::Engines#search},
-      # which cascades through DuckDuckGo (always) plus whichever keyed
-      # providers were configured, in random order, falling back on
-      # temporary-unavailability errors and rendering the winning
-      # provider's rows into a stable Markdown shape.
+      # Build the +web_search+ tool. Calls {Search::Engines#search}, which
+      # cascades the selected providers in random order, falling back on
+      # unavailability and rendering the winner's rows to a stable Markdown
+      # shape.
+      #
+      #   WebSearch.build                                          # DuckDuckGo alone
+      #   WebSearch.build(brave_key: 'BSA...')                     # DuckDuckGo + Brave
+      #   WebSearch.build(engines: [:brave], brave_key: 'BSA...')  # Brave alone
       #
-      # @param brave_key [String, nil] Brave Search API key; when present
-      #   (non-blank) Brave joins the cascade. Get one at
-      #   https://api-dashboard.search.brave.com.
-      # @param exa_key [String, nil] Exa API key; when present (non-blank)
-      #   Exa joins the cascade. Get one at https://exa.ai.
+      # @param engines [Array<String, Symbol>, nil] engine names to use —
+      #   +duckduckgo+, +brave+, +exa+. +nil+ selects DuckDuckGo plus every
+      #   engine whose key is supplied. Order carries no preference; see
+      #   {Search::Engines.resolve}.
+      # @param brave_key [String, nil] Brave key
+      #   (https://api-dashboard.search.brave.com).
+      # @param exa_key [String, nil] Exa key (https://exa.ai).
       # @return [Tool] the +web_search+ tool in OpenAI tool-call shape
-      def self.build(brave_key: nil, exa_key: nil)
-        engines = Search::Engines.new(brave_key: brave_key, exa_key: exa_key)
+      # @raise [ArgumentError] on an unusable selection: an empty or repeated
+      #   +engines+ list, an unknown engine name, or an engine named without
+      #   its key.
+      def self.build(engines: nil, brave_key: nil, exa_key: nil)
+        # Validated here as well as inside the cascade, so a mis-wired host is
+        # refused at the call it actually wrote even if this stops constructing
+        # the cascade eagerly.
+        Search::Engines.resolve(engines: engines, brave_key: brave_key, exa_key: exa_key)
+        cascade = Search::Engines.new(engines: engines, brave_key: brave_key, exa_key: exa_key)
         Tool.new(
           name: 'web_search',
           description: DESCRIPTION,
@@ -49,9 +81,53 @@ module Pikuri
                                'Maximum number of result entries to return. ' \
                                'Defaults to 10; most providers cap this at 20.'
           },
-          execute: ->(query:, max_results: 10) { engines.search(query, max_results: max_results) }
+          # +wants_context:+ opts in to the per-call {Tool::ExecuteContext}, so
+          # a shared instance still honours whichever agent is waiting.
+          wants_context: true,
+          execute: lambda { |query:, max_results: 10, context:|
+            cascade.search(query, max_results: max_results, cancellable: context.cancellable)
+          },
+          # Snippets are written by whoever ranks for the query, and the query
+          # string itself leaves the machine — a search is an outbound channel
+          # even though nothing is "sent". Nobody reviews that query, hence
+          # +:unreviewed+; the whole difference from {FETCH} is the destination.
+          #
+          # +:tool_vouched+ against the three clauses: the caller supplies a
+          # query, never a host, and the engine set is this file's own
+          # ({Search::Engines::ENGINE_NAMES}); a search engine does not
+          # republish the queries it receives; and the request rides TLS to a
+          # party with no relationship to the attacker. A host picks from that
+          # closed list of three and cannot extend it, so the destination is
+          # still *this code* choosing, not the model.
+          #
+          # It is not a claim that the leg is harmless. A secret can still be
+          # pushed out inside a query — it just cannot be read back, and only
+          # while this stays the agent's sole egress leg.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs.new(
+            private: false, untrusted: :hard,
+            egress_payload_review: :unreviewed, egress_destination: :tool_vouched
+          )
         )
       end
+
+      # Build the +web_search+ tool from a config file's +search:+ block, the
+      # host-facing shortcut for {build}:
+      #
+      #   # ~/.pikuri-examples-config.yaml
+      #   search:
+      #     brave_key: BSA...
+      #     engines: [brave]
+      #
+      #   c.add_tool Pikuri::Tool::WebSearch.from_h(examples_config['search'])
+      #
+      # @param config [Hash{String, Symbol => Object}, nil] the +search:+ block;
+      #   +nil+ (an absent key) yields the DuckDuckGo-only default.
+      # @return [Tool] the +web_search+ tool in OpenAI tool-call shape
+      # @raise [ArgumentError] as {build}, plus on a malformed block; see
+      #   {Search::Engines.config_from_h}.
+      def self.from_h(config)
+        build(**Search::Engines.config_from_h(config))
+      end
     end
   end
 end

data/lib/pikuri/tool.rb

@@ -5,45 +5,90 @@ require 'ruby_llm'
 module Pikuri
   # A tool the LLM can request via OpenAI-style tool calling.
   #
-  # {Tool} is a plain value object: +name+, +description+, +parameters+,
-  # and an +execute+ Proc that produces the observation. Pikuri's own
-  # code talks to this surface (the bundled tools, the sub-agent factory,
-  # the +Agent+ constructor); the conversion to ruby_llm's runtime shape
-  # happens at exactly one named seam — {#to_ruby_llm_tool} — which the
-  # +Agent+ calls when wiring tools into the underlying +RubyLLM::Chat+.
-  #
-  # Bundled tool implementations live under +lib/tool/+ and are required
-  # explicitly by the scripts that use them; +lib/tool.rb+ itself only
-  # introduces the {Tool} class and {Tool::Parameters} machinery.
+  # A plain value object — +name+, +description+, +parameters+, and an
+  # +execute+ Proc that produces the observation. Pikuri's code talks to this
+  # surface; conversion to ruby_llm's runtime shape happens at exactly one seam,
+  # {#to_ruby_llm_tool}, which the +Agent+ calls when wiring tools into the
+  # +RubyLLM::Chat+. Bundled implementations live under +lib/tool/+ and are
+  # required explicitly by the scripts that use them.
   #
   # == Validation ordering
   #
-  # Pikuri's {Parameters#validate} — DidYouMean suggestions, type coercion,
-  # all-errors-collected — is what the LLM must see when it emits bad
-  # arguments, not ruby_llm's keyword-presence checker. The synthetic
-  # class produced by {#to_ruby_llm_tool} defines +execute(**args)+: the
-  # keyrest signature makes +RubyLLM::Tool#validate_keyword_arguments+
-  # no-op (it bails out at the +accepts_extra_keywords+ check), so
-  # pikuri's validator runs inside {#run} before any user code does.
+  # Pikuri's {Parameters#validate} (DidYouMean suggestions, type coercion,
+  # all-errors-collected) is what the LLM must see on bad arguments, not
+  # ruby_llm's keyword-presence checker. The synthetic class from
+  # {#to_ruby_llm_tool} defines +execute(**args)+: the keyrest signature makes
+  # +RubyLLM::Tool#validate_keyword_arguments+ no-op, so pikuri's validator runs
+  # inside {#run} before any user code.
   #
   # == Error handling convention
   #
-  # Tools split failures into two buckets:
-  #
-  # * *Recoverable* failures — anything the LLM can react to by retrying with
-  #   different inputs (bad arguments, HTTP 4xx/5xx, network blips, search
-  #   provider rate-limits, division by zero in the calculator, ...). These
-  #   come back as a +"Error: <message>"+ String and become the next
-  #   observation; the model sees them and self-corrects on the following
-  #   turn instead of crashing the agent loop.
-  # * *Bugs* in pikuri's own code (parser regressions, schema misuse,
-  #   misconfigured clients, ...). These keep raising. The LLM cannot fix
-  #   them; a human needs to.
-  #
-  # Argument-validation failures from {Parameters#validate} are caught by
-  # {#run} and turned into +"Error: ..."+ observations. The +execute+ Proc
-  # owns the rest — it should follow the same convention internally for
-  # tool-specific recoverable failures, and let bugs raise.
+  # * *Recoverable* failures (bad arguments, HTTP 4xx/5xx, network blips,
+  #   rate-limits, division by zero, ...) come back as +"Error: <message>"+
+  #   Strings and become the next observation, so the model self-corrects.
+  # * *Bugs* in pikuri's own code (parser regressions, schema misuse, ...) keep
+  #   raising — the LLM can't fix them.
+  #
+  # {#run} catches {Parameters#validate} failures into +"Error: ..."+; the
+  # +execute+ Proc follows the same convention for its own recoverable failures
+  # and lets bugs raise.
+  #
+  # == Sharing: may one instance serve two agents?
+  #
+  # {Pikuri::Agent} is thread-unsafe, so a host running ten agents in one VM
+  # serializes each agent's own calls — usually a thread apiece. That makes
+  # "may a second agent have this tool?" and "is this reachable from two
+  # threads?" one question. Every tool answers it, as a +Sharing:+ tail or a
+  # +== Sharing+ section, naming one posture:
+  #
+  # * *P_stateless* — no mutable state. Share freely.
+  # * *P_shared_locked* — process-wide mutable state under a lock. Sharing is
+  #   intended, and for anything pacing a shared *external* resource it is
+  #   mandatory: a per-agent {Search::RateLimiter} would let ten agents fire
+  #   ten simultaneous requests from one IP and earn the ban it exists to
+  #   avoid.
+  # * *P_shared_benign* — unprotected process-wide state whose race is
+  #   harmless; the doc names the race ({Pikuri::UrlCache}: both callers
+  #   compute a cold key and write identical bytes).
+  # * *P_one_agent* — agent-scoped state, so exactly one agent. It needs no
+  #   lock because its only caller is that agent, whose calls are already
+  #   serialized; wire it twice and you lose that for free. And the first
+  #   failure isn't a race but a correctness bug — agent A would read agent B's
+  #   facts single-threaded too.
+  #
+  # +P_one_agent+ is a fine answer, not a defect: most of what a tool knows is
+  # one conversation's business. Nothing enforces it, so the doc *is* the
+  # contract. The two axes stay independent — a {Skill::Activation} locks *and*
+  # is per-agent, so "thread-safe" is no licence to share.
+  #
+  # A +Tool+ is a value object holding a +Proc+, so its posture is its
+  # collaborators': each tool names the one that owns the state, which is also
+  # where any lock lives.
+  #
+  # The one way to break the premise from outside pikuri: ruby_llm's
+  # +tool_concurrency+ config (default +false+) makes +Chat+ run a tool batch on
+  # threads, so a *single* agent would enter its own +P_one_agent+ tools
+  # concurrently. Leave it off.
+  #
+  # == Cancellation
+  #
+  # A tool that *waits* can opt into being interrupted: pass
+  # +wants_context: true+ and take a +context:+ keyword, then wait through
+  # {Pikuri::Agent::Control::Cancellable#sleep} on the {ExecuteContext} handed
+  # in.
+  #
+  #   wants_context: true,
+  #   execute: ->(query:, context:) { backend.search(query, cancellable: context.cancellable) }
+  #
+  # Opt-in rather than universal because most tools have nothing to cancel, and
+  # because a token only reaches *waits* — a tool blocked in IO (a Faraday read,
+  # +Subprocess#wait+) stays uninterruptible however many tokens it holds.
+  #
+  # Per *call*, not per construction, and that is the point: {#to_ruby_llm_tool}
+  # mints a fresh wrapper per agent, so even a +P_shared_locked+ tool shared by
+  # ten agents honours whichever one is actually waiting. The context is always
+  # a real object ({ExecuteContext.default}, whose cancellation never trips,
+  # when the host wired none), so an +execute+ never nil-checks it.
   class Tool
     # @return [String] function name advertised to the LLM
     attr_reader :name
@@ -57,60 +102,90 @@ module Pikuri
     #   LLM
     attr_reader :parameters
 
-    # @return [Proc] callable invoked once arguments have been validated;
-    #   receives validated keyword arguments and returns the observation.
-    #   The usual return is a +String+; tools that want to deliver
-    #   multimodal observations (e.g. {Pikuri::Workspace::Read} on a
-    #   PNG) may instead return a +RubyLLM::Content+ with attachments,
-    #   which +RubyLLM::Chat#handle_tool_calls+ accepts via its
-    #   +content_like?+ check and the per-provider Media formatters turn
-    #   into the right image / document blocks inside +tool_result+.
+    # @return [Proc] callable invoked with validated keyword arguments,
+    #   returning the observation — usually a +String+, or a +RubyLLM::Content+
+    #   with attachments for multimodal observations (e.g.
+    #   {Pikuri::Workspace::Read} on a PNG), which +RubyLLM::Chat+ turns into
+    #   the right image/document blocks.
     attr_reader :execute
 
+    # @return [Tool::TrifectaLegs] which lethal-trifecta legs this tool
+    #   contributes, for {Pikuri::Trifecta}
+    attr_reader :trifecta_legs
+
     # @param name [String] function name advertised to the LLM
     # @param description [String] human-readable description used by the LLM
     #   to decide when to call the tool
     # @param parameters [Tool::Parameters] declared schema
-    # @param execute [Proc] callable invoked with validated keyword arguments
-    #   that returns either a +String+ observation or a +RubyLLM::Content+
-    #   (for multimodal observations — see {#execute}). Recoverable failures
-    #   should be returned as +"Error: <message>"+ Strings rather than raised
-    #   — see "Error handling convention" above.
+    # @param execute [Proc] callable invoked with validated keyword arguments,
+    #   returning a +String+ or +RubyLLM::Content+ (see {#execute}). Recoverable
+    #   failures return +"Error: <message>"+ rather than raise.
+    # @param trifecta_legs [Tool::TrifectaLegs] legs this tool contributes.
+    #   Compute them here rather than at a later resolution pass: construction
+    #   *is* wiring time, since every collaborator that decides a leg (the
+    #   workspace, the sandbox, the confirmer) is already a kwarg of the tool
+    #   that uses it. Defaults to {TrifectaLegs::ASSUMED} — an undeclared tool is
+    #   presumed hostile on both axes the framework could have determined.
+    # @param wants_context [Boolean] when +true+, {#run} additionally passes a
+    #   +context:+ keyword carrying this call's {ExecuteContext} — so +execute+
+    #   must declare one. Declared rather than inferred from the Proc, and both
+    #   halves are mandatory, so either without the other is an +ArgumentError+
+    #   on the first call rather than a silent +nil+.
     # @return [Tool]
-    def initialize(name:, description:, parameters:, execute:)
+    def initialize(name:, description:, parameters:, execute:,
+                   trifecta_legs: TrifectaLegs::ASSUMED, wants_context: false)
       @name = name
       @description = description
       @parameters = parameters
       @execute = execute
+      @trifecta_legs = trifecta_legs
+      @wants_context = wants_context
     end
 
-    # Validate +args+ against {#parameters} and forward them as keyword
-    # arguments to {#execute}. Validation failures are caught and rendered
-    # as +"Error: <message>"+ Strings so the agent loop can feed them back
-    # to the LLM as the next observation; everything else bubbles up.
+    # @return [Boolean] whether {#run} hands +execute+ a +context:+ keyword
+    #   carrying the {ExecuteContext} for this call. Declared at construction,
+    #   never inferred from the Proc's signature — see the +== Cancellation+
+    #   section.
+    attr_reader :wants_context
+
+    # Validate +args+ against {#parameters} and forward them as kwargs to
+    # {#execute}. Validation failures come back as +"Error: <message>"+ Strings
+    # for the next observation; everything else bubbles up.
     #
     # @param args [Hash] raw arguments supplied by the LLM
-    # @return [String, RubyLLM::Content] tool observation. Validation
-    #   failures always come back as +"Error: ..."+ Strings; the success
-    #   shape is whatever the +execute+ Proc returns (typically a String,
-    #   or a +RubyLLM::Content+ for multimodal observations).
-    def run(args)
+    # @param context [ExecuteContext] this invocation's environment, forwarded
+    #   as a +context:+ keyword only when {#wants_context}. Never part of
+    #   +args+ — the LLM cannot supply it, since {Parameters#validate} refuses
+    #   unknown keys. Positional against the house style on purpose: give this
+    #   method *any* keyword and Ruby 3 re-reads the bare hash in
+    #   +run('text' => 'hi')+ as keywords, so +args+ arrives empty at every
+    #   existing call site.
+    # @return [String, RubyLLM::Content] tool observation — validation failures
+    #   always +"Error: ..."+; success is whatever +execute+ returns.
+    def run(args, context = ExecuteContext.default)
       validated = @parameters.validate(args)
-      @execute.call(**validated)
+      if @wants_context
+        @execute.call(**validated, context: context)
+      else
+        @execute.call(**validated)
+      end
     rescue Tool::Parameters::ValidationError => e
       "Error: #{e.message}"
     end
 
-    # Build a synthetic +RubyLLM::Tool+ subclass that wraps this Tool. The
-    # subclass is what +RubyLLM::Chat#with_tool+ accepts: ruby_llm
-    # instantiates it (+tool.new+) and routes tool calls through
-    # +instance.call(args)+, which lands in +#execute(**args)+ and
-    # delegates back to {#run} on this instance.
+    # Build a synthetic +RubyLLM::Tool+ subclass wrapping this Tool — what
+    # +RubyLLM::Chat#with_tool+ accepts. ruby_llm instantiates it and routes
+    # tool calls through +#execute(**args)+, which delegates to {#run}.
+    #
+    # A wrapper is per *agent* even when this +Tool+ is shared between several,
+    # which is what lets it close over one agent's cancellation token.
     #
+    # @param context [ExecuteContext] passed to {#run} on every call; see the
+    #   +== Cancellation+ section.
     # @return [Class] anonymous +RubyLLM::Tool+ subclass
-    def to_ruby_llm_tool
+    def to_ruby_llm_tool(context: ExecuteContext.default)
       pikuri_tool = self
-      schema      = @parameters.to_h
+      schema      = @parameters.to_openai
       tool_name   = @name
       tool_desc   = @description
 
@@ -119,7 +194,7 @@ module Pikuri
         params(schema)
 
         define_singleton_method(:name) { tool_name }
-        define_method(:execute) { |**args| pikuri_tool.run(args) }
+        define_method(:execute) { |**args| pikuri_tool.run(args, context) }
       end
     end
   end

data/lib/pikuri/trifecta/contribution.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Trifecta
+    # What an extension adds to the tree, returned from
+    # {Pikuri::Agent::Extension#trifecta_contribution}. Two independent things,
+    # either of which may be empty:
+    #
+    #   # a sub-agent extension: one child per persona, nothing of its own
+    #   Contribution.new(legs: Pikuri::Tool::TrifectaLegs::NONE, children: nodes)
+    #
+    #   # an MCP extension: legs no tool can declare, no children
+    #   Contribution.new(label: '(mcp)', legs: assumed_with_private, children: [])
+    #
+    # Needed because two things in the tree are invisible to per-tool tagging:
+    # a sub-agent is a whole node the tools cannot describe, and a foreign tool
+    # surface (MCP) arrives as raw +RubyLLM::Tool+ subclasses with no leg
+    # surface at all.
+    #
+    # Immutable.
+    #
+    # @!attribute [r] label
+    #   @return [String] name of the row these +legs+ appear under in the
+    #     report, parenthesized to mark it as not-a-tool. It is what
+    #     {Pikuri::Trifecta::Report#attribution} points the reader at, so it
+    #     has to name the surface they can actually go and change — two
+    #     extensions declaring under one label would blame each other's
+    #     wiring.
+    # @!attribute [r] legs
+    #   @return [Pikuri::Tool::TrifectaLegs] legs this extension adds to the
+    #     node it is wired into, over and above that node's own tools
+    # @!attribute [r] children
+    #   @return [Array<Node>] child nodes this extension introduces
+    class Contribution < Data.define(:label, :legs, :children)
+      # @param label [String] row name for +legs+; ignored when they are +NONE+
+      # @param legs [Pikuri::Tool::TrifectaLegs]
+      # @param children [Array<Node>]
+      def initialize(label: '(extension)', legs: Pikuri::Tool::TrifectaLegs::NONE, children: [])
+        super
+      end
+    end
+  end
+end

data/lib/pikuri/trifecta/node.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Trifecta
+    # One agent in the tree the detector walks: the main agent at the root, a
+    # persona per sub-agent below it. Assembled from a wired +Agent+ (its tools
+    # plus every extension's
+    # {Pikuri::Agent::Extension#trifecta_contribution}), and hand-built in
+    # specs — which is the point of carrying plain data rather than live
+    # objects:
+    #
+    #   Node.new(label: 'demo',
+    #            tool_legs: { 'read' => read_legs },
+    #            children: [Node.new(label: 'RESEARCHER',
+    #                                tool_legs: { 'fetch' => fetch_legs },
+    #                                channel_egress: :human_reviewed)])
+    #
+    # Immutable.
+    #
+    # @!attribute [r] label
+    #   @return [String] name shown in the report — the binary/agent name at the
+    #     root, the persona name for a sub-agent
+    # @!attribute [r] tool_legs
+    #   @return [Hash{String=>Pikuri::Tool::TrifectaLegs}] this agent's own
+    #     tools, in wiring order. The per-tool breakdown is kept rather than
+    #     pre-unioned so the rendered tree can show *which* tool contributes a
+    #     leg instead of a bare total.
+    # @!attribute [r] children
+    #   @return [Array<Node>] sub-agents this agent can dispatch to
+    # @!attribute [r] channel_egress
+    #   @return [Symbol, nil] how much egress the delegation channel *from the
+    #     parent* permits, on the {Pikuri::Tool::TrifectaLegs} review axis —
+    #     +:human_reviewed+ when a human gates the hand-off, +:unreviewed+
+    #     otherwise. A property of the edge, stored on the child
+    #     because every child has exactly one parent edge; +nil+ at the root,
+    #     which has none.
+    class Node < Data.define(:label, :tool_legs, :children, :channel_egress)
+      # @param label [String]
+      # @param tool_legs [Hash{String=>Pikuri::Tool::TrifectaLegs}]
+      # @param children [Array<Node>]
+      # @param channel_egress [Symbol, nil]
+      def initialize(label:, tool_legs: {}, children: [], channel_egress: nil)
+        super
+      end
+    end
+  end
+end