pwn 0.5.613 → 0.5.617

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

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'time'
+require 'digest'
+
+module PWN
+  module AI
+    module Agent
+      # PWN::AI::Agent::Learning is the self-improvement engine that closes
+      # the pwn-ai feedback loop. It captures task outcomes, mines session
+      # transcripts for durable lessons, promotes successful workflows into
+      # reusable skills, and prunes / consolidates persistent memory so the
+      # agent gets sharper over time instead of accumulating noise.
+      #
+      # Data flows:
+      #   Loop.run --(tool telemetry)--> Metrics.record
+      #   Loop.run --(final answer)----> Learning.auto_reflect (opt-in)
+      #   model    --(tool calls)------> learning_note_outcome / _distill_skill
+      #   PromptBuilder <----------------- Learning.to_context + Metrics.to_context
+      #
+      # Everything is file-backed under ~/.pwn so it survives across REPL
+      # restarts and is shared by every future session.
+      module Learning
+        LEARNING_FILE = File.join(Dir.home, '.pwn', 'learning.jsonl')
+        MAX_MEMORY_ENTRIES = 200
+
+        # Supported Method Parameters::
+        # entry = PWN::AI::Agent::Learning.note_outcome(
+        #   task: 'required - short description of what was attempted',
+        #   success: 'required - Boolean, did the attempt achieve its goal',
+        #   details: 'optional - free-form notes / error / evidence',
+        #   session_id: 'optional - PWN::Sessions id this outcome belongs to',
+        #   tags: 'optional - Array of String labels for later retrieval'
+        # )
+
+        public_class_method def self.note_outcome(opts = {})
+          task    = opts[:task].to_s
+          success = opts[:success] ? true : false
+          raise 'ERROR: task is required' if task.strip.empty?
+
+          entry = {
+            id: Digest::SHA256.hexdigest("#{task}-#{Time.now.to_f}")[0, 12],
+            task: task,
+            success: success,
+            details: opts[:details].to_s[0, 2_000],
+            session_id: opts[:session_id],
+            tags: Array(opts[:tags]).map(&:to_s),
+            timestamp: Time.now.utc.iso8601
+          }
+          FileUtils.mkdir_p(File.dirname(LEARNING_FILE))
+          File.open(LEARNING_FILE, 'a') { |f| f.puts(JSON.generate(entry)) }
+
+          key = :"lesson_#{entry[:id]}"
+          cat = :lesson
+          val = "#{success ? 'SUCCESS' : 'FAILURE'}: #{task} — #{opts[:details].to_s.strip[0, 200]}"
+          PWN::Memory.remember(key: key, value: val, category: cat) if defined?(PWN::Memory)
+
+          entry
+        end
+
+        # Supported Method Parameters::
+        # rows = PWN::AI::Agent::Learning.outcomes(
+        #   limit: 'optional - max entries returned newest-first (default 50)',
+        #   success: 'optional - filter by Boolean outcome',
+        #   tag: 'optional - filter by tag substring'
+        # )
+
+        public_class_method def self.outcomes(opts = {})
+          limit   = opts[:limit] || 50
+          want_ok = opts.key?(:success) ? !opts[:success].nil? && opts[:success] != false : nil
+          tag     = opts[:tag].to_s.downcase
+          return [] unless File.exist?(LEARNING_FILE)
+
+          rows = File.readlines(LEARNING_FILE).map do |l|
+            JSON.parse(l, symbolize_names: true)
+          rescue StandardError
+            nil
+          end
+          rows.compact!
+          rows.select! { |r| r[:success] == want_ok } unless want_ok.nil?
+          rows.select! { |r| Array(r[:tags]).any? { |t| t.to_s.downcase.include?(tag) } } unless tag.empty?
+          rows.reverse.first(limit)
+        end
+
+        # Supported Method Parameters::
+        # stats = PWN::AI::Agent::Learning.stats
+
+        public_class_method def self.stats
+          rows   = outcomes(limit: 10_000)
+          total  = rows.length
+          ok     = rows.count { |r| r[:success] }
+          skills = defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) ? PWN::Skills.keys.length : 0
+          mem    = defined?(PWN::Memory) ? PWN::Memory.load.keys.length : 0
+          {
+            total_outcomes: total,
+            successes: ok,
+            failures: total - ok,
+            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)),
+            extrospection: (Extrospection.stats if defined?(Extrospection))
+          }
+        end
+
+        # Supported Method Parameters::
+        # ctx = PWN::AI::Agent::Learning.to_context(
+        #   limit: 'optional - number of recent outcomes to surface (default 5)'
+        # )
+
+        public_class_method def self.to_context(opts = {})
+          limit = opts[:limit] || 5
+          rows = outcomes(limit: limit)
+          return '' if rows.empty?
+
+          lines = rows.map do |r|
+            flag = r[:success] ? '✓' : '✗'
+            "  #{flag} #{r[:task][0, 100]} (#{r[:timestamp]})"
+          end
+          s = stats
+          hdr = "RECENT OUTCOMES (success_rate=#{(s[:success_rate] * 100).round(1)}% over #{s[:total_outcomes]} attempts)"
+          "#{hdr}\n#{lines.join("\n")}\n\n"
+        end
+
+        # Supported Method Parameters::
+        # skill = PWN::AI::Agent::Learning.distill_skill(
+        #   name: 'required - snake_case name for the new skill',
+        #   session_id: 'optional - PWN::Sessions id to mine (uses its transcript)',
+        #   content: 'optional - explicit markdown body; overrides transcript mining',
+        #   references: 'optional - Array of reference URLs / CWE / CVE / ATT&CK ids'
+        # )
+
+        public_class_method def self.distill_skill(opts = {})
+          name = opts[:name].to_s.gsub(/[^a-z0-9_-]/i, '_')
+          raise 'ERROR: name is required' if name.empty?
+
+          body = opts[:content].to_s
+          body = build_skill_from_session(session_id: opts[:session_id], name: name) if body.strip.empty? && opts[:session_id]
+          raise 'ERROR: content or session_id is required' if body.strip.empty?
+
+          refs = Array(opts[:references]).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+          unless refs.empty?
+            body = "---\nreferences:\n#{refs.map { |r| "  - #{r}" }.join("\n")}\n---\n#{body}" unless body.start_with?("---\n")
+            body = "#{body.rstrip}\n\n## References\n#{refs.map { |r| "- #{r}" }.join("\n")}\n" unless body =~ /^\#{1,3}\s*References\s*$/i
+          end
+
+          dir = skills_dir
+          FileUtils.mkdir_p(dir)
+          path = File.join(dir, "#{name}.md")
+          File.write(path, body)
+          PWN::Config.load_skills(pwn_skills_path: dir) if defined?(PWN::Config) && PWN::Config.respond_to?(:load_skills)
+          note_outcome(task: "distill_skill:#{name}", success: true, details: "Saved #{path}", tags: %w[skill auto])
+          { saved: true, name: name, path: path, bytes: body.bytesize, references: refs }
+        end
+
+        # Supported Method Parameters::
+        # report = PWN::AI::Agent::Learning.reflect(
+        #   session_id: 'required - PWN::Sessions id to analyse',
+        #   dry_run: 'optional - when true, do not write to Memory/Skills (default false)'
+        # )
+        #
+        # 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.
+
+        public_class_method def self.reflect(opts = {})
+          session_id = opts[:session_id]
+          dry_run    = opts[:dry_run] ? true : false
+          raise 'ERROR: session_id is required' if session_id.to_s.empty?
+
+          transcript = PWN::Sessions.load(session_id: session_id)
+          return { session_id: session_id, lessons: [], reason: 'empty transcript' } if transcript.empty?
+
+          lessons = introspective_lessons(transcript: transcript)
+          lessons = heuristic_lessons(transcript: transcript) if lessons.empty?
+
+          saved = []
+          lessons.each do |l|
+            next if l.to_s.strip.empty?
+
+            key = :"reflect_#{session_id}_#{Digest::SHA256.hexdigest(l)[0, 8]}"
+            PWN::Memory.remember(key: key, value: l, category: :lesson) unless dry_run
+            saved << { key: key, lesson: l }
+          end
+          consolidate unless dry_run
+
+          { session_id: session_id, lessons: saved, count: saved.length, dry_run: dry_run }
+        end
+
+        # Supported Method Parameters::
+        # PWN::AI::Agent::Learning.auto_reflect(
+        #   session_id: 'required - id of the just-completed session',
+        #   request: 'optional - original user request (for outcome logging)',
+        #   final: 'optional - final assistant answer (for outcome logging)'
+        # )
+        #
+        # Called by Loop.run when PWN::Env[:ai][:agent][:auto_reflect] is
+        # truthy. Never raises — learning must not break the primary loop.
+
+        public_class_method def self.auto_reflect(opts = {})
+          session_id = opts[:session_id]
+          return unless session_id
+          return unless auto_reflect_enabled?
+
+          note_outcome(
+            task: opts[:request].to_s[0, 120],
+            success: !opts[:final].to_s.strip.empty?,
+            details: opts[:final].to_s[0, 300],
+            session_id: session_id,
+            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
+        end
+
+        # Supported Method Parameters::
+        # removed = PWN::AI::Agent::Learning.consolidate(
+        #   max_entries: 'optional - hard cap on PWN::Memory size (default MAX_MEMORY_ENTRIES)'
+        # )
+        #
+        # Deduplicates near-identical lesson values and prunes the oldest
+        # entries once the cap is exceeded so the injected MEMORY block
+        # stays high-signal.
+
+        public_class_method def self.consolidate(opts = {})
+          cap = opts[:max_entries] || MAX_MEMORY_ENTRIES
+          return { removed: 0 } unless defined?(PWN::Memory)
+
+          mem = PWN::Memory.load
+          seen = {}
+          removed = []
+          mem.each do |k, v|
+            sig = Digest::SHA256.hexdigest(v[:value].to_s.strip.downcase)[0, 16]
+            if seen[sig]
+              removed << k
+            else
+              seen[sig] = k
+            end
+          end
+          removed.each { |k| mem.delete(k) }
+
+          if mem.size > cap
+            sorted = mem.sort_by { |_k, v| v[:timestamp].to_s }
+            drop   = sorted.first(mem.size - cap).map(&:first)
+            drop.each { |k| mem.delete(k) }
+            removed.concat(drop)
+          end
+          PWN::Memory.save(mem: mem)
+          { removed: removed.length, remaining: mem.size }
+        end
+
+        # Supported Method Parameters::
+        # PWN::AI::Agent::Learning.reset
+
+        public_class_method def self.reset
+          FileUtils.rm_f(LEARNING_FILE)
+          { cleared: true }
+        end
+
+        # -------------------------------------------------------------
+        # privates
+        # -------------------------------------------------------------
+
+        private_class_method def self.auto_reflect_enabled?
+          return false unless defined?(PWN::Env) && PWN::Env.is_a?(Hash)
+
+          PWN::Env.dig(:ai, :agent, :auto_reflect) ? true : false
+        rescue StandardError
+          false
+        end
+
+        private_class_method def self.skills_dir
+          if defined?(PWN::Config) && PWN::Config.respond_to?(:pwn_skills_path)
+            PWN::Config.pwn_skills_path
+          else
+            File.join(Dir.home, '.pwn', 'skills')
+          end
+        rescue StandardError
+          File.join(Dir.home, '.pwn', 'skills')
+        end
+
+        private_class_method def self.transcript_text(opts = {})
+          transcript = opts[:transcript] || []
+          transcript.map do |e|
+            "[#{e[:role]}] #{e[:content].to_s.gsub(/\s+/, ' ')[0, 400]}"
+          end.join("\n")
+        end
+
+        private_class_method def self.introspective_lessons(opts = {})
+          transcript = opts[:transcript] || []
+          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::Agent::Introspection.reflect_on(request: req, suppress_pii_warning: true)
+          resp.to_s.lines.map(&:strip).reject(&:empty?).first(5)
+        rescue StandardError
+          []
+        end
+
+        private_class_method def self.heuristic_lessons(opts = {})
+          transcript = opts[:transcript] || []
+          lessons = []
+          transcript.each do |e|
+            c = e[:content].to_s
+            next unless e[:role].to_s == 'tool'
+
+            if c.include?('"success":false') || c.match?(/error|Error|ERROR/)
+              tool = c[/^(\w+) →/, 1] || c[/"error":"([^"]{5,120})"/, 1] || 'tool'
+              lessons << "Avoid repeating failure pattern from #{tool}: #{c[0, 160]}"
+            end
+          end
+          if lessons.empty?
+            asst = transcript.rfind { |e| e[:role].to_s == 'assistant' }
+            lessons << "Approach that worked: #{asst[:content].to_s.strip[0, 200]}" if asst && !asst[:content].to_s.strip.empty?
+          end
+          lessons.uniq.first(5)
+        end
+
+        private_class_method def self.build_skill_from_session(opts = {})
+          session_id = opts[:session_id]
+          name       = opts[:name]
+          transcript = PWN::Sessions.load(session_id: session_id)
+          steps = transcript.select { |e| %w[tool assistant].include?(e[:role].to_s) }
+                            .map { |e| "- **#{e[:role]}**: #{e[:content].to_s.strip[0, 300]}" }
+          user = transcript.find { |e| e[:role].to_s == 'user' }
+          goal = user ? user[:content].to_s.strip[0, 200] : name
+          <<~MD
+            # #{name.tr('_-', ' ').capitalize}
+
+            _Auto-distilled by PWN::AI::Agent::Learning from session `#{session_id}` on #{Time.now.utc.iso8601}._
+
+            ## Goal
+            #{goal}
+
+            ## Observed Procedure
+            #{steps.join("\n")}
+
+            ## Notes
+            Refine this skill by editing #{name}.md under ~/.pwn/skills.
+          MD
+        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::Learning.note_outcome(task: 'nmap sweep 10.0.0.0/24', success: true, details: '12 hosts up')
+              PWN::AI::Agent::Learning.outcomes(limit: 20, success: false)
+              PWN::AI::Agent::Learning.reflect(session_id: sid)              # LLM or heuristic → PWN::Memory
+              PWN::AI::Agent::Learning.auto_reflect(session_id: sid, request: req, final: text)
+              PWN::AI::Agent::Learning.distill_skill(name: 'quick_recon', session_id: sid)
+              PWN::AI::Agent::Learning.consolidate(max_entries: 200)         # dedupe + prune Memory
+              PWN::AI::Agent::Learning.to_context(limit: 5)                  # injected by PromptBuilder
+              PWN::AI::Agent::Learning.stats
+              PWN::AI::Agent::Learning.reset
+
+              Enable end-of-run auto-learning with:
+                PWN::Env[:ai][:agent][:auto_reflect] = true
+
+              #{self}.authors
+          USAGE
+        end
+      end
+    end
+  end
+end

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

@@ -49,6 +49,32 @@ module PWN
           DEFAULT_MAX_ITERS
         end
 
+        private_class_method def self.record_metrics(opts = {})
+          name    = opts[:name]
+          started = opts[:started]
+          raw     = opts[:raw].to_s
+          ok      = raw.include?('"success":true')
+          err     = raw[/"error":"([^"]{1,300})"/, 1]
+          dur     = started ? (Time.now - started) : 0.0
+          Metrics.record(name: name, success: ok, duration: dur, error: err) if defined?(Metrics)
+        rescue StandardError
+          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)
@@ -145,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 = [
@@ -163,13 +190,16 @@ module PWN
             if calls.empty?
               text = msg[:content].to_s
               append_session(session_id: session_id, role: 'assistant', content: text)
+              Learning.auto_reflect(session_id: session_id, request: request, final: text) if defined?(Learning)
               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)
+              name    = tc.dig(:function, :name).to_s
+              entry   = Registry.lookup(name: name)
+              started = Time.now
+              raw     = Dispatch.call(tool_call: tc)
+              record_metrics(name: name, started: started, raw: raw)
               result = Result.condition(content: raw, entry: entry)
 
               on_tool&.call(name, tc.dig(:function, :arguments), result)

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'time'
+
+module PWN
+  module AI
+    module Agent
+      # PWN::AI::Agent::Metrics is the telemetry layer of the pwn-ai
+      # learning loop. Every tool dispatch performed by
+      # PWN::AI::Agent::Loop is recorded here (name, success, duration,
+      # last error) and persisted to ~/.pwn/metrics.json.
+      #
+      # PromptBuilder re-injects a compact effectiveness summary into the
+      # system prompt on every turn, so the model gains awareness of which
+      # tools historically succeed vs. fail on THIS host and can adapt its
+      # tool selection accordingly. This is one half of the closed
+      # feedback loop that lets pwn-ai continuously make itself smarter
+      # (the other half is PWN::AI::Agent::Learning).
+      module Metrics
+        METRICS_FILE = File.join(Dir.home, '.pwn', 'metrics.json')
+
+        # Supported Method Parameters::
+        # metrics = PWN::AI::Agent::Metrics.load
+
+        public_class_method def self.load
+          FileUtils.mkdir_p(File.dirname(METRICS_FILE))
+          return { tools: {}, updated_at: nil } unless File.exist?(METRICS_FILE)
+
+          JSON.parse(File.read(METRICS_FILE), symbolize_names: true)
+        rescue StandardError
+          { tools: {}, updated_at: nil }
+        end
+
+        # Supported Method Parameters::
+        # PWN::AI::Agent::Metrics.save(
+        #   metrics: 'required - Hash returned by .load / mutated in place'
+        # )
+
+        public_class_method def self.save(opts = {})
+          metrics = opts[:metrics] ||= { tools: {} }
+          metrics[:updated_at] = Time.now.utc.iso8601
+          FileUtils.mkdir_p(File.dirname(METRICS_FILE))
+          File.write(METRICS_FILE, JSON.pretty_generate(metrics))
+          metrics
+        end
+
+        # Supported Method Parameters::
+        # PWN::AI::Agent::Metrics.record(
+        #   name: 'required - tool name that was dispatched',
+        #   success: 'required - Boolean, did the handler complete without error',
+        #   duration: 'optional - Float seconds the dispatch took',
+        #   error: 'optional - String error message when success is false'
+        # )
+
+        public_class_method def self.record(opts = {})
+          name     = opts[:name].to_s
+          success  = opts[:success] ? true : false
+          duration = opts[:duration].to_f
+          error    = opts[:error]
+          return if name.empty?
+
+          metrics = load
+          metrics[:tools] ||= {}
+          key = name.to_sym
+          t = metrics[:tools][key] ||= {
+            calls: 0, ok: 0, fail: 0, total_duration: 0.0,
+            last_error: nil, last_at: nil
+          }
+          t[:calls]          += 1
+          t[:ok]             += 1 if success
+          t[:fail]           += 1 unless success
+          t[:total_duration] += duration
+          t[:last_error]      = error.to_s[0, 300] if error && !success
+          t[:last_at]         = Time.now.utc.iso8601
+          save(metrics: metrics)
+          t
+        end
+
+        # Supported Method Parameters::
+        # rows = PWN::AI::Agent::Metrics.summary(
+        #   limit: 'optional - cap number of tools returned (default 25)'
+        # )
+
+        public_class_method def self.summary(opts = {})
+          limit = opts[:limit] || 25
+          tools = load[:tools] || {}
+          rows = tools.map do |name, t|
+            calls = t[:calls].to_i
+            ok    = t[:ok].to_i
+            rate  = calls.positive? ? (ok.to_f / calls).round(3) : 0.0
+            avg   = calls.positive? ? (t[:total_duration].to_f / calls).round(3) : 0.0
+            {
+              name: name.to_s,
+              calls: calls,
+              success_rate: rate,
+              avg_duration: avg,
+              last_error: t[:last_error],
+              last_at: t[:last_at]
+            }
+          end
+          rows.sort_by { |r| [-r[:calls], -r[:success_rate]] }.first(limit)
+        end
+
+        # Supported Method Parameters::
+        # ctx = PWN::AI::Agent::Metrics.to_context(
+        #   limit: 'optional - cap number of tools included (default 8)'
+        # )
+
+        public_class_method def self.to_context(opts = {})
+          limit = opts[:limit] || 8
+          rows = summary(limit: limit)
+          return '' if rows.empty?
+
+          lines = rows.map do |r|
+            err = r[:last_error] ? " last_err=#{r[:last_error][0, 60]}" : ''
+            "  - #{r[:name]}: calls=#{r[:calls]} success=#{(r[:success_rate] * 100).round(1)}% avg=#{r[:avg_duration]}s#{err}"
+          end
+          "TOOL EFFECTIVENESS (historical, adapt tool choice accordingly)\n#{lines.join("\n")}\n\n"
+        end
+
+        # Supported Method Parameters::
+        # PWN::AI::Agent::Metrics.reset
+
+        public_class_method def self.reset
+          FileUtils.rm_f(METRICS_FILE)
+          { tools: {}, updated_at: 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:
+              PWN::AI::Agent::Metrics.record(name: 'shell', success: true, duration: 0.42)
+              PWN::AI::Agent::Metrics.summary(limit: 10)
+              PWN::AI::Agent::Metrics.to_context(limit: 8)   # injected by PromptBuilder
+              PWN::AI::Agent::Metrics.reset
+              PWN::AI::Agent::Metrics.load
+              PWN::AI::Agent::Metrics.save(metrics: hash)
+
+              #{self}.authors
+          USAGE
+        end
+      end
+    end
+  end
+end