pwn 0.5.603 → 0.5.609

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d9cef98cd11c0d946179ae3bee8e726c491ae0328455c8aaef8380fa392c3a8
-  data.tar.gz: 6abdf135e81a2596166ddfae6ec93bb738e8eeeb60ed27a4517f7c061898dff8
+  metadata.gz: 136257739e1b8bd0279eb7d0fe5763237321f9248a944ddd30260e3687fb74d2
+  data.tar.gz: 8a7b62b9c7ae10c5fecfbea6c8868c25d342162a30c5c8e053de93227582a985
 SHA512:
-  metadata.gz: 3be83f533d5311947b2bde851319956aa6cee5c8047e5d8aa5b03768c1db0052fa25211b34e096b0bd7858f8327fd1c02998000fb546624f79718c745f2a2d7f
-  data.tar.gz: e164db59ece4dc7440047008346a10680642a3f647231f23a0330ef87fb3b3556b5147700bcb7f12483c9f8f3c81f2dc291bb23a01eb35db7a604eac5dca7036
+  metadata.gz: 8f8657d28da8b182b93ec5111f759a2a390a4856ea05056e6ef7007da798c12799febad57a21dff3a99486f7c8cc30b844aa1220edfac61adc93ad6ef03c832b
+  data.tar.gz: 3b3f9506e4f8d3fc0ac026d1b46921c79ff4980e4c750d192904e6edbc86cc406475441e5e4987890400aab982410c1d811726189f70700690cbcac14961f036

data/.rubocop_todo.yml

@@ -70,6 +70,7 @@ Metrics/MethodLength:
 Naming/AccessorMethodName:
   Exclude:
     - 'lib/pwn/ai/anthropic.rb'
+    - 'lib/pwn/ai/gemini.rb'
     - 'lib/pwn/ai/grok.rb'
     - 'lib/pwn/ai/ollama.rb'
     - 'lib/pwn/ai/open_ai.rb'

data/Gemfile

@@ -18,7 +18,7 @@ gem 'aws-sdk', '3.3.0'
 gem 'barby', '0.7.0'
 gem 'base32', '0.3.4'
 gem 'bitcoin-ruby', '0.0.20'
-gem 'brakeman', '8.0.4'
+gem 'brakeman', '8.0.5'
 gem 'bson', '5.2.0'
 gem 'bundler', '>=4.0.14'
 gem 'bundler-audit', '>=0.9.3'
@@ -49,8 +49,8 @@ gem 'jwt', '3.2.0'
 gem 'libusb', '0.7.2'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.0'
-gem 'mcp', '0.18.0'
-gem 'meshtastic', '0.0.163'
+gem 'mcp', '0.20.0'
+gem 'meshtastic', '0.0.165'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.24.1'
 gem 'msfrpc-client', '1.1.2'
@@ -77,11 +77,11 @@ gem 'rbvmomi2', '3.10.0'
 gem 'rdoc', '7.0.4'
 gem 'rest-client', '2.1.0'
 gem 'rex', '2.0.13'
-gem 'rmagick', '7.0.3'
+gem 'rmagick', '7.0.4'
 gem 'rqrcode', '3.2.0'
 gem 'rspec', '3.13.2'
 gem 'rtesseract', '3.1.4'
-gem 'rubocop', '1.87.0'
+gem 'rubocop', '1.88.0'
 gem 'rubocop-rake', '0.7.1'
 gem 'rubocop-rspec', '3.10.2'
 gem 'ruby-audio', '1.6.1'
@@ -89,8 +89,8 @@ gem 'ruby-nmap', '1.0.3'
 gem 'ruby-saml', '1.18.1'
 gem 'rvm', '1.11.3.9'
 gem 'savon', '2.17.2'
-gem 'selenium-devtools', '0.148.0'
-gem 'selenium-webdriver', '4.44.0'
+gem 'selenium-devtools', '0.149.0'
+gem 'selenium-webdriver', '4.45.0'
 gem 'slack-ruby-client', '3.1.0'
 gem 'socksify', '1.8.1'
 gem 'spreadsheet', '1.3.5'

data/README.md

@@ -37,7 +37,7 @@ $ cd /opt/pwn
 $ ./install.sh
 $ ./install.sh ruby-gem
 $ pwn
-pwn[v0.5.603]:001 >>> PWN.help
+pwn[v0.5.609]:001 >>> PWN.help
 ```
 
 [![Installing the pwn Security Automation Framework](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/pwn_install.png)](https://youtu.be/G7iLUY4FzsI)
@@ -52,7 +52,7 @@ $ rvm use ruby-4.0.5@pwn
 $ gem uninstall --all --executables pwn
 $ gem install --verbose pwn
 $ pwn
-pwn[v0.5.603]:001 >>> PWN.help
+pwn[v0.5.609]:001 >>> PWN.help
 ```
 
 If you're using a multi-user install of RVM do:
@@ -62,7 +62,7 @@ $ rvm use ruby-4.0.5@pwn
 $ rvmsudo gem uninstall --all --executables pwn
 $ rvmsudo gem install --verbose pwn
 $ pwn
-pwn[v0.5.603]:001 >>> PWN.help
+pwn[v0.5.609]:001 >>> PWN.help
 ```
 
 PWN periodically upgrades to the latest version of Ruby which is reflected in `/opt/pwn/.ruby-version`.  The easiest way to upgrade to the latest version of Ruby from a previous PWN installation is to run the following script:

data/git_commit.sh

@@ -25,8 +25,15 @@ if (( $# == 3 )); then
 
   pwn_autoinc_version
   if [[ $? -ne 0 ]]; then
-    echo 'ERROR: pwn_autoinc_version failed! Investigate and bump pwn version manually.'
-    exit 1
+    echo 'ERROR: pwn_autoinc_version failed! Reinstalling pwn gemset...'
+    rvmsudo ./reinstall_pwn_gemset.sh
+    rvmsudo rake
+    rvmsudo rake install
+    if [[ $? -ne 0 ]]; then
+      echo 'ERROR: Attempt to reinstall pwn gemset failed! Please investigate and fix before trying again.'
+      exit 1
+    fi
+    pwn_autoinc_version
   fi
 
   # Generate RDoc JSONL for fine-tunning LLMs

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PWN
+  module AI
+    module Agent
+      # Tool-call dispatch: takes a single tool_call object (OpenAI shape),
+      # looks up the registered handler, parses args, runs it, and returns a
+      # JSON string suitable for a role:'tool' message.
+      module Dispatch
+        # Supported Method Parameters::
+        # json_str = PWN::AI::Agent::Dispatch.call(
+        #   tool_call: 'required - Hash { id:, type:, function: { name:, arguments: } }'
+        # )
+
+        public_class_method def self.call(opts = {})
+          tool_call = opts[:tool_call]
+          raise 'ERROR: tool_call is required' if tool_call.nil?
+
+          fn   = tool_call[:function] || tool_call['function'] || {}
+          name = (fn[:name] || fn['name']).to_s
+          raw  = fn[:arguments] || fn['arguments'] || '{}'
+
+          entry = Registry.lookup(name: name)
+          return JSON.generate(error: "unknown tool: #{name}") unless entry
+
+          args = parse_args(raw: raw)
+          result = entry.handler.call(args)
+          JSON.generate(success: true, result: result)
+        rescue StandardError => e
+          JSON.generate(
+            success: false,
+            error: "#{e.class}: #{e.message}",
+            backtrace: Array(e.backtrace).first(3)
+          )
+        end
+
+        private_class_method def self.parse_args(opts = {})
+          raw = opts[:raw]
+          case raw
+          when Hash   then symbolize(hash: raw)
+          when String then raw.strip.empty? ? {} : JSON.parse(raw, symbolize_names: true)
+          when nil    then {}
+          else symbolize(hash: raw.to_h)
+          end
+        rescue JSON::ParserError => e
+          raise ArgumentError, "invalid JSON arguments: #{e.message}"
+        end
+
+        private_class_method def self.symbolize(opts = {})
+          hash = opts[:hash] ||= {}
+          hash.each_with_object({}) { |(k, v), m| m[k.to_sym] = v }
+        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:
+              json_str = PWN::AI::Agent::Dispatch.call(
+                tool_call: {
+                  id: 'call_1',
+                  type: 'function',
+                  function: { name: 'shell', arguments: '{"command":"id"}' }
+                }
+              )
+
+              #{self}.authors
+          USAGE
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PWN
+  module AI
+    module Agent
+      # The agent conversation loop:
+      #
+      #   build system prompt → call LLM with tools → if tool_calls: dispatch,
+      #   append role:'tool' results, loop → else: return text.
+      #
+      # This replaces the regex-ReAct in PWN::Plugins::REPL :pwn_ai_hook with
+      # native function-calling. State (memory, skills, sessions) is all
+      # externalised — Loop.run is stateless aside from the messages array it
+      # builds.
+      module Loop
+        DEFAULT_MAX_ITERS = 777
+
+        ENGINE_MODS = {
+          openai: 'PWN::AI::OpenAI',
+          grok: 'PWN::AI::Grok',
+          ollama: 'PWN::AI::Ollama',
+          anthropic: 'PWN::AI::Anthropic',
+          gemini: 'PWN::AI::Gemini'
+        }.freeze
+
+        # Supported Method Parameters::
+        # final = PWN::AI::Agent::Loop.run(
+        #   user_text: 'required - what the human typed',
+        #   session_id: 'optional - PWN::Sessions id (transcript is appended to it)',
+        #   enabled_toolsets: 'optional - subset of Registry.toolsets, or nil for all',
+        #   on_tool: 'optional - ->(name, args, result) callback for live UI'
+        # )
+
+        public_class_method def self.run(opts = {})
+          user_text  = opts[:user_text].to_s
+          session_id = opts[:session_id]
+          on_tool    = opts[:on_tool]
+
+          Registry.discover
+
+          tools    = Registry.definitions(enabled: opts[:enabled_toolsets])
+          messages = [
+            { role: 'system', content: PromptBuilder.build(session_id: session_id) },
+            { role: 'user',   content: user_text }
+          ]
+          append_session(session_id: session_id, role: 'user', content: user_text)
+
+          max_iters.times do |i|
+            msg = call_engine(messages: messages, tools: tools)
+            return '[pwn-ai] engine returned no message' if msg.nil?
+
+            messages << msg
+            calls = Array(msg[:tool_calls])
+
+            if calls.empty?
+              text = msg[:content].to_s
+              append_session(session_id: session_id, role: 'assistant', content: text)
+              return text
+            end
+
+            calls.each do |tc|
+              name   = tc.dig(:function, :name).to_s
+              entry  = Registry.lookup(name: name)
+              raw    = Dispatch.call(tool_call: tc)
+              result = Result.condition(content: raw, entry: entry)
+
+              on_tool&.call(name, tc.dig(:function, :arguments), result)
+
+              messages << {
+                role: 'tool',
+                tool_call_id: tc[:id] || tc['id'] || "call_#{i}",
+                name: name,
+                content: result
+              }
+              append_session(session_id: session_id, role: 'tool', content: "#{name} → #{result[0, 400]}")
+            end
+          end
+
+          '[pwn-ai] iteration budget exhausted'
+        end
+
+        # Supported Method Parameters::
+        # msg = PWN::AI::Agent::Loop.call_engine(
+        #   messages: 'required - OpenAI-format messages array',
+        #   tools: 'optional - OpenAI tools array'
+        # )
+        #
+        # Returns a normalised assistant message hash:
+        #   { role: 'assistant', content: String|nil,
+        #     tool_calls: [ {id:, type:'function', function:{name:, arguments:}} ],
+        #     _native_content: <provider raw>  (when adapter needs round-trip) }
+
+        public_class_method def self.call_engine(opts = {})
+          messages = opts[:messages]
+          tools    = opts[:tools]
+
+          engine = (PWN::Env.dig(:ai, :active) if defined?(PWN::Env)).to_s.downcase.to_sym
+          engine = :openai if engine == :''
+
+          mod_name = ENGINE_MODS[engine]
+          raise "ERROR: Unsupported AI engine for agent loop: #{engine}" unless mod_name
+
+          mod = Object.const_get(mod_name)
+          if mod.respond_to?(:chat_with_tools)
+            puts "MESSAGES:\n#{messages.inspect}\nTOOLS:\n#{tools.inspect}" if Pry.config.pwn_ai_debug
+            normalize_llm(
+              response: mod.chat_with_tools(
+                messages: messages,
+                tools: tools,
+                spinner: true
+              )
+            )
+          else
+            degrade_text_only(mod: mod, messages: messages)
+          end
+        end
+
+        # Supported Method Parameters::
+        # msg = PWN::AI::Agent::Loop.normalize_llm(
+        #   response: 'required - chat_with_tools response Hash from any provider'
+        # )
+
+        public_class_method def self.normalize_llm(opts = {})
+          resp = opts[:response]
+          puts "RESPONSE: #{resp.inspect}" if Pry.config.pwn_ai_debug
+          return nil unless resp.is_a?(Hash)
+
+          msg = resp.dig(:choices, 0, :message) || resp[:assistant_message]
+          return nil unless msg
+
+          out = {
+            role: 'assistant',
+            content: msg[:content],
+            tool_calls: Array(msg[:tool_calls]).map do |tc|
+              {
+                id: tc[:id],
+                type: 'function',
+                function: {
+                  name: tc.dig(:function, :name) || tc[:name],
+                  arguments: tc.dig(:function, :arguments) || tc[:arguments]
+                }
+              }
+            end
+          }
+          # Preserve provider-native content blocks so chat can round-trip
+          # them exactly on the next iteration (e.g. Anthropic requires the
+          # original tool_use block to precede a tool_result).
+          out[:_native_content] = msg[:_native_content] if msg[:_native_content]
+          out
+        end
+
+        private_class_method def self.degrade_text_only(opts = {})
+          mod      = opts[:mod]
+          messages = opts[:messages]
+
+          warn "[pwn-ai] #{mod} has no chat — falling back to text-only (no tool-calling)"
+          sys  = messages.find { |m| m[:role] == 'system' }
+          user = messages.rfind { |m| m[:role] == 'user' }
+          r = mod.chat(request: user[:content], system_role_content: sys&.[](:content), spinner: true)
+          txt = r.is_a?(Hash) ? (r.dig(:choices, -1, :content) || r.dig(:choices, -1, :text)).to_s : r.to_s
+          { role: 'assistant', content: txt, tool_calls: [] }
+        end
+
+        private_class_method def self.max_iters
+          v = (PWN::Env.dig(:ai, :agent, :max_iters) if defined?(PWN::Env))
+          v.to_i.positive? ? v.to_i : DEFAULT_MAX_ITERS
+        rescue StandardError
+          DEFAULT_MAX_ITERS
+        end
+
+        private_class_method def self.append_session(opts = {})
+          session_id = opts[:session_id]
+          return unless session_id && defined?(PWN::Sessions)
+
+          PWN::Sessions.append(session_id: session_id, role: opts[:role], content: opts[:content])
+        rescue StandardError
+          nil
+        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:
+              final = PWN::AI::Agent::Loop.run(
+                user_text: 'what does `id` return on this host?',
+                session_id: PWN::Sessions.create[:id],
+                enabled_toolsets: %w[terminal pwn memory skills],
+                on_tool: ->(name, args, result) { puts "→ \#{name}: \#{result[0,80]}" }
+              )
+
+              Supported engines: #{ENGINE_MODS.keys.join(', ')}
+              Set PWN::Env[:ai][:active] to choose; PWN::Env[:ai][:agent][:max_iters] to bound.
+
+              #{self}.authors
+          USAGE
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module PWN
+  module AI
+    module Agent
+      # Assembles the system prompt for every Loop.run invocation from
+      # durable on-disk state: PWN::Env persona, host environment probe,
+      # PWN::Memory facts, and PWN::Skills index.
+      #
+      # Re-injection IS the persistence mechanism: this is rebuilt fresh on
+      # every user turn, so a memory_remember / skill_create from the prior
+      # turn shows up here with no extra wiring.
+      module PromptBuilder
+        # Supported Method Parameters::
+        # system_prompt = PWN::AI::Agent::PromptBuilder.build(
+        #   session_id: 'optional - PWN::Sessions id to embed in the ENV block'
+        # )
+
+        public_class_method def self.build(opts = {})
+          session_id = opts[:session_id]
+          engine = active_engine
+          base   = (PWN::Env.dig(:ai, engine, :system_role_content) if defined?(PWN::Env)) ||
+                   'You are an offensive-security AI named Sonny operating inside the pwn REPL.'
+
+          "
+            #{base}
+
+            ENVIRONMENT
+              host       : #{host_line}
+              cwd        : #{Dir.pwd}
+              ruby       : #{RUBY_VERSION}
+              pwn        : #{pwn_version}
+              session_id : #{session_id || '(none)'}
+
+            #{memory_block}#{skills_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`
+              for OS commands. Save durable facts with `memory_remember`.
+          "
+        end
+
+        private_class_method def self.active_engine
+          return :openai unless defined?(PWN::Env) && PWN::Env.is_a?(Hash)
+
+          PWN::Env.dig(:ai, :active).to_s.downcase.to_sym
+        rescue StandardError
+          :openai
+        end
+
+        private_class_method def self.host_line
+          `uname -srm 2>/dev/null`.strip
+        rescue StandardError
+          RUBY_PLATFORM
+        end
+
+        private_class_method def self.pwn_version
+          defined?(PWN::VERSION) ? PWN::VERSION : '?'
+        end
+
+        private_class_method def self.memory_block
+          return '' unless defined?(PWN::Memory) && PWN::Memory.respond_to?(:to_context)
+
+          ctx = PWN::Memory.to_context(limit: 25).to_s
+          ctx.strip.empty? ? '' : "MEMORY#{ctx}\n\n"
+        rescue StandardError
+          ''
+        end
+
+        private_class_method def self.skills_block
+          return '' unless defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) && !PWN::Skills.empty?
+
+          lines = PWN::Skills.map do |name, meta|
+            first = meta[:content].to_s.lines.first.to_s.strip
+            first = first[0, 100]
+            "  - #{name}: #{first}"
+          end
+          "SKILLS (call skill_view to read full body)\n#{lines.join("\n")}\n\n"
+        rescue StandardError
+          ''
+        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:
+              system_prompt = PWN::AI::Agent::PromptBuilder.build(session_id: 'abc')
+
+              #{self}.authors
+          USAGE
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module PWN
+  module AI
+    module Agent
+      # Central registry for pwn-ai agent tools.
+      #
+      # Each file under lib/pwn/ai/agent/tools/*.rb calls
+      # +PWN::AI::Agent::Registry.register(...)+ at load time to declare a
+      # JSON-Schema (what the LLM sees) and a handler lambda (what pwn runs).
+      #
+      # Registry.definitions(...) returns the OpenAI-format +tools:+ array;
+      # Registry.lookup(name:) returns the entry for dispatch.
+      #
+      # Import chain (circular-import safe):
+      #   agent/registry.rb        (no deps on tool files)
+      #          ^
+      #   agent/tools/*.rb         (require registry, call .register at top level)
+      #          ^
+      #   agent/loop.rb            (calls Registry.discover then .definitions)
+      module Registry
+        Entry = Struct.new(
+          :name,        # String  - tool name exposed to the model
+          :toolset,     # String  - grouping for enable/disable (terminal, file, pwn, memory…)
+          :schema,      # Hash    - OpenAI function schema {name:, description:, parameters:}
+          :handler,     # Proc    - ->(args_hash) { ... } returning a JSON-serialisable object
+          :check,       # Proc    - -> { bool } gate; tool only advertised when truthy
+          :max_chars,   # Integer - cap on serialised result before it re-enters the convo
+          keyword_init: true
+        )
+
+        @entries = {}
+        @discovered = false
+
+        # Supported Method Parameters::
+        # PWN::AI::Agent::Registry.register(
+        #   name: 'required - tool name exposed to the model',
+        #   toolset: 'required - grouping for enable/disable (terminal, file, pwn, memory…)',
+        #   schema: 'required - OpenAI function schema {name:, description:, parameters:}',
+        #   handler: 'required - ->(args_hash) { ... } returning a JSON-serialisable object',
+        #   check: 'optional - -> { bool } gate; tool only advertised when truthy',
+        #   max_chars: 'optional - cap on serialised result (default 24_000)'
+        # )
+
+        public_class_method def self.register(opts = {})
+          name = opts[:name].to_s
+          raise 'ERROR: name is required' if name.empty?
+          raise 'ERROR: schema is required' unless opts[:schema]
+          raise 'ERROR: handler is required' unless opts[:handler].respond_to?(:call)
+
+          @entries[name] = Entry.new(
+            name: name,
+            toolset: opts[:toolset].to_s,
+            schema: opts[:schema],
+            handler: opts[:handler],
+            check: opts[:check] ||= -> { true },
+            max_chars: opts[:max_chars] ||= 24_000
+          )
+        end
+
+        # Supported Method Parameters::
+        # entry = PWN::AI::Agent::Registry.lookup(
+        #   name: 'required - registered tool name'
+        # )
+
+        public_class_method def self.lookup(opts = {})
+          name = opts[:name]
+          @entries[name.to_s]
+        end
+
+        # Supported Method Parameters::
+        # entries = PWN::AI::Agent::Registry.all
+
+        public_class_method def self.all
+          @entries.values
+        end
+
+        # Supported Method Parameters::
+        # names = PWN::AI::Agent::Registry.toolsets
+
+        public_class_method def self.toolsets
+          @entries.values.map(&:toolset).uniq.sort
+        end
+
+        # Supported Method Parameters::
+        # tools = PWN::AI::Agent::Registry.definitions(
+        #   enabled: 'optional - Array of toolset names to include; nil = all whose check passes'
+        # )
+
+        public_class_method def self.definitions(opts = {})
+          enabled = opts[:enabled]
+          enabled = enabled.map(&:to_s) if enabled
+          @entries.values
+                  .select { |e| (enabled.nil? || enabled.include?(e.toolset)) && safe_check(entry: e) }
+                  .map    { |e| { type: 'function', function: e.schema } }
+        end
+
+        # Supported Method Parameters::
+        # names = PWN::AI::Agent::Registry.discover(
+        #   force: 'optional - re-require tool files even if already discovered (default false)'
+        # )
+
+        public_class_method def self.discover(opts = {})
+          force = opts[:force] ||= false
+          return @entries.keys if @discovered && !force
+
+          tools_dir = File.join(__dir__, 'tools')
+          if Dir.exist?(tools_dir)
+            Dir[File.join(tools_dir, '*.rb')].each do |f|
+              require f
+            rescue StandardError, LoadError => e
+              warn "[pwn-ai] failed to load tool #{File.basename(f)}: #{e.class}: #{e.message}"
+            end
+          end
+          @discovered = true
+          @entries.keys
+        end
+
+        private_class_method def self.safe_check(opts = {})
+          entry = opts[:entry]
+          entry.check.call
+        rescue StandardError
+          false
+        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:
+              PWN::AI::Agent::Registry.discover
+              PWN::AI::Agent::Registry.definitions(enabled: %w[terminal pwn])
+              PWN::AI::Agent::Registry.lookup(name: 'shell')   # => Entry
+              PWN::AI::Agent::Registry.toolsets                # => ["memory","pwn","skills","terminal"]
+              PWN::AI::Agent::Registry.register(name:, toolset:, schema:, handler:)
+
+              #{self}.authors
+          USAGE
+        end
+      end
+    end
+  end
+end