pwn 0.5.615 → 0.5.618

data/lib/pwn/ai/agent/introspection.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PWN
+  module AI
+    module Agent
+      # PWN::AI::Agent::Introspection is the inward-facing counterpart to
+      # PWN::AI::Agent::Extrospection. Where Extrospection looks OUTWARD at
+      # the world the agent operates in (host state, toolchain, network,
+      # threat-intel), Introspection looks INWARD - it lets pwn hand a
+      # request to the active AI engine and reflect on its own artifacts,
+      # transcripts, findings, code, or decisions.
+      #
+      # This module is gated by `PWN::Env[:ai][:introspection]` so that
+      # potentially-sensitive local data is never shipped to a remote LLM
+      # unless the operator has explicitly opted in via pwn-vault / config.
+      #
+      # It is the single choke-point every PWN::AI::Agent::* domain agent
+      # (Assembly, BurpSuite, GQRX, HackerOne, SAST, VulnGen, ...) routes
+      # through when it wants an LLM opinion on locally-produced data, and
+      # it is also what PWN::AI::Agent::Learning.reflect uses to distill
+      # session transcripts into durable PWN::Memory lessons.
+      module Introspection
+        # Supported Method Parameters::
+        # response = PWN::AI::Agent::Introspection.reflect_on(
+        #   request: 'required - String - What you want the AI to reflect on',
+        #   system_role_content: 'optional - context to set up the model behavior for reflection',
+        #   spinner: 'optional - Boolean - Display spinner during operation (default: false)',
+        #   suppress_pii_warning: 'optional - Boolean - Suppress PII Warnings (default: false)'
+        # )
+
+        public_class_method def self.reflect_on(opts = {})
+          request = opts[:request]
+          raise 'ERROR: request must be provided' if request.nil?
+
+          system_role_content = opts[:system_role_content]
+
+          spinner = opts[:spinner] || false
+
+          suppress_pii_warning = opts[:suppress_pii_warning] || false
+
+          response = nil
+
+          ai_introspection = PWN::Env[:ai][:introspection]
+
+          if ai_introspection && request.length.positive?
+            engine = PWN::Env[:ai][:active].to_s.downcase.to_sym
+            valid_ai_engines = PWN::AI.help.reject { |e| e.downcase == :agent }.map(&:downcase)
+            raise "ERROR: Unsupported AI engine. Supported engines are: #{valid_ai_engines}" unless valid_ai_engines.include?(engine)
+
+            warn "AI Introspection is enabled.  Ensure #{engine} has been authorized for use and/or requests are sanitized properly." unless suppress_pii_warning
+            response = PWN::AI::Agent::Loop.run(
+              request: request.chomp,
+              system_role_content: system_role_content,
+              enabled_toolsets: [],
+              spinner: spinner
+            )
+          end
+
+          response
+        rescue StandardError => e
+          raise e
+        end
+
+        # Author(s):: 0day Inc. <support@0dayinc.com>
+
+        public_class_method def self.authors
+          "AUTHOR(S):
+            0day Inc. <support@0dayinc.com>
+          "
+        end
+
+        # Display Usage for this Module
+
+        public_class_method def self.help
+          puts "USAGE:
+            #{self}.reflect_on(
+              request: 'required - String - What you want the AI to reflect on',
+              system_role_content: 'optional - context to set up the model behavior for reflection',
+              spinner: 'optional - Boolean - Display spinner during operation (default: false)',
+              suppress_pii_warning: 'optional - Boolean - Suppress PII Warnings (default: false)'
+            )
+
+            #{self}.authors
+          "
+        end
+      end
+    end
+  end
+end

data/lib/pwn/ai/agent/learning.rb

@@ -100,7 +100,8 @@ module PWN
             success_rate: total.positive? ? (ok.to_f / total).round(3) : 0.0,
             skills_known: skills,
             memory_entries: mem,
-            tool_metrics: (Metrics.summary(limit: 5) if defined?(Metrics))
+            tool_metrics: (Metrics.summary(limit: 5) if defined?(Metrics)),
+            extrospection: (Extrospection.stats if defined?(Extrospection))
           }
         end
 
@@ -160,7 +161,7 @@ module PWN
         #   dry_run: 'optional - when true, do not write to Memory/Skills (default false)'
         # )
         #
-        # Uses PWN::AI::Introspection (when available) to LLM-summarise the
+        # Uses PWN::AI::Agent::Introspection (when available) to LLM-summarise the
         # session into structured lessons. Falls back to a heuristic
         # extractor when introspection is disabled so learning never stops.
 
@@ -211,6 +212,7 @@ module PWN
             tags: %w[auto loop]
           )
           reflect(session_id: session_id)
+          Extrospection.auto_extrospect(session_id: session_id) if defined?(Extrospection)
         rescue StandardError => e
           warn "[pwn-ai/learning] auto_reflect swallowed: #{e.class}: #{e.message}"
           nil
@@ -291,11 +293,11 @@ module PWN
 
         private_class_method def self.introspective_lessons(opts = {})
           transcript = opts[:transcript] || []
-          return [] unless defined?(PWN::AI::Introspection)
+          return [] unless defined?(PWN::AI::Agent::Introspection)
           return [] unless defined?(PWN::Env) && PWN::Env.is_a?(Hash) && PWN::Env.dig(:ai, :introspection)
 
           req = "Analyse this pwn-ai session transcript and emit up to 5 durable, generalizable lessons (one per line, no numbering, imperative voice) that would make future runs faster or more reliable. Focus on tool selection, error recovery, and target-agnostic technique. Ignore trivia.\n\nTRANSCRIPT:\n#{transcript_text(transcript: transcript)}"
-          resp = PWN::AI::Introspection.reflect_on(request: req, suppress_pii_warning: true)
+          resp = PWN::AI::Agent::Introspection.reflect_on(request: req, suppress_pii_warning: true)
           resp.to_s.lines.map(&:strip).reject(&:empty?).first(5)
         rescue StandardError
           []

data/lib/pwn/ai/agent/loop.rb

@@ -61,6 +61,20 @@ module PWN
           nil
         end
 
+        # Stash the active session_id under PWN::Env[:ai][:session_id] so
+        # tool handlers (sessions_current) can discover it without a Pry
+        # dependency. PWN::Env is frozen at the top level but [:ai] is a
+        # nested mutable Hash on all supported config paths — swallow if not.
+        private_class_method def self.expose_current_session(opts = {})
+          sid = opts[:session_id]
+          return unless sid && defined?(PWN::Env) && PWN::Env.is_a?(Hash)
+
+          ai = PWN::Env[:ai]
+          ai[:session_id] = sid if ai.is_a?(Hash) && !ai.frozen?
+        rescue StandardError
+          nil
+        end
+
         private_class_method def self.append_session(opts = {})
           session_id = opts[:session_id]
           return unless session_id && defined?(PWN::Sessions)
@@ -157,6 +171,7 @@ module PWN
           system_role_content = opts[:system_role_content] ||= PWN::AI::Agent::PromptBuilder.build(session_id: session_id)
 
           Registry.discover
+          expose_current_session(session_id: session_id)
 
           tools    = Registry.definitions(enabled: opts[:enabled_toolsets])
           messages = [

data/lib/pwn/ai/agent/prompt_builder.rb

@@ -31,7 +31,7 @@ module PWN
               pwn        : #{pwn_version}
               session_id : #{session_id || '(none)'}
 
-            #{memory_block}#{skills_block}#{learning_block}#{metrics_block}TOOL USE
+            #{memory_block}#{skills_block}#{learning_block}#{metrics_block}#{extrospection_block}TOOL USE
               Use the provided function tools to act on the host. A reply with
               no tool_calls is treated as your FINAL answer to the user.
               Prefer `pwn_eval` for anything in the PWN:: namespace and `shell`
@@ -99,6 +99,15 @@ module PWN
           ''
         end
 
+        private_class_method def self.extrospection_block
+          return '' unless defined?(PWN::AI::Agent::Extrospection)
+
+          ctx = PWN::AI::Agent::Extrospection.to_context.to_s
+          ctx.strip.empty? ? '' : ctx
+        rescue StandardError
+          ''
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors

data/lib/pwn/ai/agent/sast.rb

@@ -16,7 +16,7 @@ module PWN
 
           system_role_content = 'Your sole purpose is to analyze source code snippets and generate an Exploit Prediction Scoring System (EPSS) score between 0% - 100%.  Just generate a score unless score is >= 75% in which a PoC and code fix should also be included.'
 
-          PWN::AI::Introspection.reflect_on(
+          PWN::AI::Agent::Introspection.reflect_on(
             system_role_content: system_role_content,
             request: request,
             suppress_pii_warning: true

data/lib/pwn/ai/agent/swarm.rb

@@ -0,0 +1,437 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require 'time'
+require 'fileutils'
+require 'securerandom'
+
+module PWN
+  module AI
+    module Agent
+      # Native multi-agent orchestration for pwn-ai.
+      #
+      # Swarm replaces the legacy `pwn-irc` mechanism (inspircd + weechat +
+      # PRIVMSG-flattened .chat calls) with first-class sub-agents built on
+      # top of PWN::AI::Agent::Loop.run. Each persona is a full tool-calling
+      # agent — Memory, Skills, Learning, Metrics and Extrospection all
+      # apply — so the self-improvement loop covers the whole swarm.
+      #
+      #   ~/.pwn/agents.yml                    # persona registry
+      #   ~/.pwn/swarm/<swarm_id>/bus.jsonl    # append-only message bus
+      #   ~/.pwn/swarm/<swarm_id>/personas.json# persona -> PWN::Sessions id
+      #
+      # Cross-session / cross-process communication == another pwn-ai (or a
+      # PWN::Cron job) calling Swarm.ask/debate with the same swarm_id and
+      # reading the same bus.jsonl. No daemon required.
+      module Swarm
+        AGENTS_FILE     = File.join(Dir.home, '.pwn', 'agents.yml')
+        SWARM_ROOT      = File.join(Dir.home, '.pwn', 'swarm')
+        DEFAULT_DEPTH   = 3
+        DEFAULT_ITERS   = 25
+        DEFAULT_TAIL    = 12
+        DEFAULT_TOOLSET = %w[terminal pwn memory skills sessions learning
+                             metrics extrospection].freeze
+
+        # ------------------------------------------------------------------
+        # Persona registry (~/.pwn/agents.yml)
+        # ------------------------------------------------------------------
+
+        # Supported Method Parameters::
+        #   personas = PWN::AI::Agent::Swarm.personas
+
+        public_class_method def self.personas
+          return {} unless File.exist?(AGENTS_FILE)
+
+          raw = YAML.safe_load_file(
+            AGENTS_FILE,
+            permitted_classes: [Symbol],
+            aliases: true,
+            symbolize_names: true
+          ) || {}
+          raw.transform_values { |v| normalize_persona(persona: v) }
+        rescue StandardError => e
+          warn "[pwn-ai/swarm] failed to load #{AGENTS_FILE}: #{e.class}: #{e.message}"
+          {}
+        end
+
+        # Supported Method Parameters::
+        #   PWN::AI::Agent::Swarm.spawn(
+        #     name: 'required - persona name (snake_case)',
+        #     role: 'required - system_role_content overlay for this persona',
+        #     toolsets: 'optional - Array of Registry toolset names',
+        #     engine: 'optional - :openai / :anthropic / :grok / :gemini / :ollama',
+        #     max_iters: 'optional - per-turn iteration cap for this persona'
+        #   )
+
+        public_class_method def self.spawn(opts = {})
+          name = opts[:name].to_s
+          raise ArgumentError, 'name is required' if name.strip.empty?
+          raise ArgumentError, 'role is required' if opts[:role].to_s.strip.empty?
+
+          all = personas
+          all[name.to_sym] = normalize_persona(persona: opts)
+          FileUtils.mkdir_p(File.dirname(AGENTS_FILE))
+          File.write(AGENTS_FILE, YAML.dump(deep_stringify(hash: all)))
+          { name: name, persona: all[name.to_sym], file: AGENTS_FILE }
+        end
+
+        # Supported Method Parameters::
+        #   PWN::AI::Agent::Swarm.retire(name: 'required - persona name')
+
+        public_class_method def self.retire(opts = {})
+          name = opts[:name].to_s
+          all  = personas
+          gone = all.delete(name.to_sym)
+          File.write(AGENTS_FILE, YAML.dump(deep_stringify(hash: all))) if gone
+          { name: name, removed: !gone.nil? }
+        end
+
+        # ------------------------------------------------------------------
+        # Swarm lifecycle & bus
+        # ------------------------------------------------------------------
+
+        # Supported Method Parameters::
+        #   swarm = PWN::AI::Agent::Swarm.create(topic: 'optional')
+
+        public_class_method def self.create(opts = {})
+          id  = "#{Time.now.utc.strftime('%Y%m%d_%H%M%S')}_#{SecureRandom.hex(3)}"
+          dir = File.join(SWARM_ROOT, id)
+          FileUtils.mkdir_p(dir)
+          bus_append(swarm_id: id, from: :system, to: :all,
+                     content: "swarm #{id} created: #{opts[:topic] || '(no topic)'}")
+          { swarm_id: id, dir: dir, bus: bus_path(swarm_id: id) }
+        end
+
+        # Supported Method Parameters::
+        #   swarms = PWN::AI::Agent::Swarm.list
+
+        public_class_method def self.list
+          FileUtils.mkdir_p(SWARM_ROOT)
+          Dir.children(SWARM_ROOT).sort.reverse.map do |id|
+            bp = bus_path(swarm_id: id)
+            {
+              swarm_id: id,
+              dir: File.join(SWARM_ROOT, id),
+              messages: File.exist?(bp) ? File.foreach(bp).count : 0,
+              mtime: File.exist?(bp) ? File.mtime(bp).utc.iso8601 : nil
+            }
+          end
+        end
+
+        # Supported Method Parameters::
+        #   PWN::AI::Agent::Swarm.bus_append(
+        #     swarm_id: 'required', from: 'required', content: 'required',
+        #     to: 'optional (default :all)'
+        #   )
+
+        public_class_method def self.bus_append(opts = {})
+          sid = opts[:swarm_id].to_s
+          raise ArgumentError, 'swarm_id is required' if sid.empty?
+
+          FileUtils.mkdir_p(File.join(SWARM_ROOT, sid))
+          entry = {
+            ts: Time.now.utc.iso8601,
+            from: opts[:from].to_s,
+            to: (opts[:to] || :all).to_s,
+            content: opts[:content].to_s
+          }
+          File.open(bus_path(swarm_id: sid), 'a') { |f| f.puts(JSON.generate(entry)) }
+          entry
+        end
+
+        # Supported Method Parameters::
+        #   msgs = PWN::AI::Agent::Swarm.bus_tail(swarm_id: 'required', limit: 12)
+
+        public_class_method def self.bus_tail(opts = {})
+          sid   = opts[:swarm_id].to_s
+          limit = (opts[:limit] || DEFAULT_TAIL).to_i
+          bp    = bus_path(swarm_id: sid)
+          return [] unless File.exist?(bp)
+
+          File.readlines(bp).last(limit).map { |l| JSON.parse(l, symbolize_names: true) }
+        rescue StandardError
+          []
+        end
+
+        # ------------------------------------------------------------------
+        # Core: run a single persona turn under Loop.run
+        # ------------------------------------------------------------------
+
+        # Supported Method Parameters::
+        #   reply = PWN::AI::Agent::Swarm.ask(
+        #     name: 'required - persona name from ~/.pwn/agents.yml',
+        #     request: 'required - what to ask/instruct the persona',
+        #     swarm_id: 'optional - join an existing swarm (created if omitted)',
+        #     to: 'optional - addressee recorded on the bus (default :all)',
+        #     on_tool: 'optional - ->(name, args, result) live-UI callback'
+        #   )
+
+        public_class_method def self.ask(opts = {})
+          name    = opts[:name].to_s
+          persona = personas[name.to_sym]
+          raise ArgumentError, "unknown persona: #{name} (see #{AGENTS_FILE})" unless persona
+
+          sid   = opts[:swarm_id] || create(topic: opts[:request].to_s[0, 60])[:swarm_id]
+          depth = Thread.current[:pwn_swarm_depth] || 0
+          if depth >= max_depth
+            raise "swarm recursion depth #{depth} >= max_depth #{max_depth} " \
+                  '(PWN::Env[:ai][:agent][:max_depth])'
+          end
+
+          bus_append(swarm_id: sid, from: opts[:from] || caller_label,
+                     to: name, content: opts[:request].to_s)
+
+          session_id = persona_session(swarm_id: sid, name: name)
+          sys        = build_persona_prompt(name: name, persona: persona,
+                                            swarm_id: sid, session_id: session_id)
+
+          Thread.current[:pwn_swarm_depth] = depth + 1
+          reply = with_persona_env(persona: persona) do
+            Loop.run(
+              request: opts[:request].to_s,
+              session_id: session_id,
+              enabled_toolsets: persona[:toolsets],
+              system_role_content: sys,
+              on_tool: opts[:on_tool]
+            )
+          end
+
+          bus_append(swarm_id: sid, from: name, to: opts[:to] || :all, content: reply)
+          { swarm_id: sid, name: name, session_id: session_id, reply: reply }
+        ensure
+          Thread.current[:pwn_swarm_depth] = depth
+        end
+
+        # Supported Method Parameters::
+        #   result = PWN::AI::Agent::Swarm.debate(
+        #     names: 'required - Array of persona names, order = speaking order',
+        #     topic: 'required - opening question / claim',
+        #     rounds: 'optional - full passes over names (default 2)',
+        #     swarm_id: 'optional - join an existing swarm',
+        #     on_tool: 'optional - ->(name, args, result) live-UI callback'
+        #   )
+
+        public_class_method def self.debate(opts = {})
+          names = Array(opts[:names]).map(&:to_s)
+          raise ArgumentError, 'names must contain at least 2 personas' if names.length < 2
+
+          topic = opts[:topic].to_s
+          raise ArgumentError, 'topic is required' if topic.strip.empty?
+
+          rounds = (opts[:rounds] || 2).to_i
+          sid    = opts[:swarm_id] || create(topic: topic)[:swarm_id]
+
+          last_speaker = 'moderator'
+          last_msg     = topic
+          transcript   = []
+
+          rounds.times do |r|
+            names.each do |n|
+              req = if r.zero? && n == names.first
+                      topic
+                    else
+                      "@#{last_speaker} said:\n#{last_msg}\n\n" \
+                        'Respond, critique, or advance the objective.'
+                    end
+              res = ask(name: n, request: req, swarm_id: sid,
+                        from: last_speaker, to: n, on_tool: opts[:on_tool])
+              transcript << { round: r + 1, name: n, reply: res[:reply] }
+              last_speaker = n
+              last_msg     = res[:reply]
+            end
+          end
+
+          { swarm_id: sid, rounds: rounds, names: names,
+            transcript: transcript, bus: bus_path(swarm_id: sid) }
+        end
+
+        # Supported Method Parameters::
+        #   result = PWN::AI::Agent::Swarm.broadcast(
+        #     request: 'required', names: 'optional - default all personas',
+        #     swarm_id: 'optional'
+        #   )
+
+        public_class_method def self.broadcast(opts = {})
+          req   = opts[:request].to_s
+          raise ArgumentError, 'request is required' if req.strip.empty?
+
+          names = Array(opts[:names]).map(&:to_s)
+          names = personas.keys.map(&:to_s) if names.empty?
+          sid   = opts[:swarm_id] || create(topic: req[0, 60])[:swarm_id]
+
+          replies = names.to_h do |n|
+            [n, ask(name: n, request: req, swarm_id: sid,
+                    from: 'broadcast', on_tool: opts[:on_tool])[:reply]]
+          end
+          { swarm_id: sid, replies: replies }
+        end
+
+        # ------------------------------------------------------------------
+        # privates
+        # ------------------------------------------------------------------
+
+        private_class_method def self.bus_path(opts = {})
+          File.join(SWARM_ROOT, opts[:swarm_id].to_s, 'bus.jsonl')
+        end
+
+        private_class_method def self.persona_session(opts = {})
+          sid  = opts[:swarm_id].to_s
+          name = opts[:name].to_s
+          map_path = File.join(SWARM_ROOT, sid, 'personas.json')
+          map = File.exist?(map_path) ? JSON.parse(File.read(map_path)) : {}
+          return map[name] if map[name]
+
+          sess = PWN::Sessions.create(
+            title: "swarm:#{sid} persona:#{name}",
+            source: 'pwn-ai-swarm'
+          )
+          map[name] = sess[:id]
+          File.write(map_path, JSON.pretty_generate(map))
+          sess[:id]
+        end
+
+        private_class_method def self.build_persona_prompt(opts = {})
+          name    = opts[:name]
+          persona = opts[:persona]
+          sid     = opts[:swarm_id]
+          base    = PromptBuilder.build(session_id: opts[:session_id])
+
+          bus = bus_tail(swarm_id: sid, limit: DEFAULT_TAIL).map do |m|
+            "  [#{m[:ts]}] #{m[:from]} → #{m[:to]}: #{m[:content].to_s.tr("\n", ' ')[0, 400]}"
+          end.join("\n")
+
+          peers = (personas.keys.map(&:to_s) - [name]).join(', ')
+
+          <<~PROMPT
+            #{base}
+
+            SWARM
+              swarm_id : #{sid}
+              you_are  : #{name}
+              peers    : #{peers.empty? ? '(none)' : peers}
+              depth    : #{Thread.current[:pwn_swarm_depth] || 0} / #{max_depth}
+              (Use agent_ask to delegate to a peer only if strictly necessary
+               and you have the 'swarm' toolset — depth is capped.)
+
+            PERSONA (#{name})
+            #{persona[:role]}
+
+            SWARM BUS (last #{DEFAULT_TAIL} msgs, newest last)
+            #{bus.empty? ? '  (empty)' : bus}
+          PROMPT
+        end
+
+        # Temporarily override PWN::Env[:ai][:active] and
+        # PWN::Env[:ai][:agent][:max_iters] for the duration of a sub-agent
+        # turn, restoring both afterwards even on raise.
+        private_class_method def self.with_persona_env(opts = {})
+          persona = opts[:persona]
+          ai = env_ai
+          return yield unless ai
+
+          agent_h = (ai[:agent] ||= {})
+          prev_active = ai[:active]
+          prev_iters  = agent_h[:max_iters]
+
+          ai[:active]          = persona[:engine].to_s if persona[:engine]
+          agent_h[:max_iters]  = persona[:max_iters]   if persona[:max_iters]
+          yield
+        ensure
+          if ai
+            ai[:active]         = prev_active
+            agent_h[:max_iters] = prev_iters
+          end
+        end
+
+        private_class_method def self.normalize_persona(opts = {})
+          p = opts[:persona] || {}
+          {
+            role: p[:role].to_s,
+            engine: (p[:engine].to_s.empty? ? nil : p[:engine].to_s.downcase.to_sym),
+            toolsets: Array(p[:toolsets]).map(&:to_s).then { |a| a.empty? ? DEFAULT_TOOLSET.dup : a },
+            max_iters: (p[:max_iters] || DEFAULT_ITERS).to_i
+          }
+        end
+
+        private_class_method def self.max_depth
+          v = (PWN::Env.dig(:ai, :agent, :max_depth) if defined?(PWN::Env))
+          v.to_i.positive? ? v.to_i : DEFAULT_DEPTH
+        rescue StandardError
+          DEFAULT_DEPTH
+        end
+
+        private_class_method def self.env_ai
+          return nil unless defined?(PWN::Env) && PWN::Env.is_a?(Hash)
+
+          ai = PWN::Env[:ai]
+          ai.is_a?(Hash) && !ai.frozen? ? ai : nil
+        rescue StandardError
+          nil
+        end
+
+        private_class_method def self.caller_label
+          d = Thread.current[:pwn_swarm_depth] || 0
+          d.zero? ? 'orchestrator' : "depth#{d}"
+        end
+
+        private_class_method def self.deep_stringify(opts = {})
+          h = opts[:hash]
+          case h
+          when Hash  then h.to_h { |k, v| [k.to_s, deep_stringify(hash: v)] }
+          when Array then h.map { |v| deep_stringify(hash: v) }
+          when Symbol then h.to_s
+          else h
+          end
+        end
+
+        # Author(s):: 0day Inc. <support@0dayinc.com>
+
+        public_class_method def self.authors
+          "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+        end
+
+        # Display Usage for this Module
+
+        public_class_method def self.help
+          puts <<~USAGE
+            USAGE:
+              # Define personas (or edit #{AGENTS_FILE} directly)
+              PWN::AI::Agent::Swarm.spawn(
+                name: 'red',
+                role: 'Offensive researcher. Propose the most likely exploit path...',
+                toolsets: %w[terminal pwn memory extrospection],
+                engine: :anthropic
+              )
+
+              # One-shot: ask a persona (creates a swarm if none given)
+              r = PWN::AI::Agent::Swarm.ask(name: 'red', request: 'Enumerate attack surface for target X')
+
+              # Antagonistic feedback loop
+              d = PWN::AI::Agent::Swarm.debate(
+                names: %w[red blue],
+                topic: 'Is CVE-2026-NNNN exploitable on target X?',
+                rounds: 3
+              )
+              puts d[:transcript].map { |t| "\#{t[:name]}: \#{t[:reply][0,200]}" }
+
+              # Fan-out
+              PWN::AI::Agent::Swarm.broadcast(request: 'Summarise findings so far')
+
+              # Inspect / resume cross-session
+              PWN::AI::Agent::Swarm.list
+              PWN::AI::Agent::Swarm.bus_tail(swarm_id: d[:swarm_id], limit: 50)
+
+              Config:
+                PWN::Env[:ai][:agent][:max_depth]  # recursion cap  (default #{DEFAULT_DEPTH})
+                persona[:max_iters]                # per-turn iteration cap (default #{DEFAULT_ITERS})
+                persona[:toolsets]                 # Registry toolset allow-list; omit 'swarm'
+                                                   # to prevent that persona spawning sub-agents.
+
+              #{self}.authors
+          USAGE
+        end
+      end
+    end
+  end
+end