pwn 0.5.613 → 0.5.615

data/documentation/pwn-REPL.md

@@ -0,0 +1,33 @@
+# The pwn REPL
+
+The `pwn` command launches a Pry-based interactive Ruby shell with the entire `PWN` namespace pre-loaded.
+
+## Starting
+
+```bash
+pwn
+pwn[v0.5.613]:001 >>>
+```
+
+## Key Features
+
+- Direct access to every `PWN::` constant and plugin.
+- Tab completion for classes and methods.
+- Multi-line support.
+- Easy prototyping of security workflows.
+- `PWN.help` and inspection of any object.
+
+## Useful REPL Commands
+
+```
+pwn[v0.5.613]:001 >>> PWN::Plugins.constants.sort
+pwn[v0.5.613]:001 >>> PWN::Plugins::BurpSuite.methods(false).sort
+pwn[v0.5.613]:001 >>> PWN::SAST.constants
+pwn[v0.5.613]:001 >>> pwn-ai
+```
+
+See:
+- [pwn-ai Agent](pwn-ai-Agent.md) — the killer feature inside the REPL
+- [General Usage](General-PWN-Usage.md)
+
+[[Diagrams]]

data/documentation/pwn-ai-Agent.md

@@ -0,0 +1,43 @@
+# pwn-ai Autonomous Agent
+
+The most powerful way to use PWN is via the `pwn-ai` command inside the REPL.
+
+## Activation
+
+```bash
+pwn[v0.5.613]:001 >>> pwn-ai
+[*] pwn-ai agent TUI activated...
+>
+```
+
+## Capabilities
+
+- Natural language instruction of complex multi-step security tasks.
+- Full tool calling access to:
+  - All `PWN::Plugins` (BurpSuite preferred, TransparentBrowser, NmapIt, Shodan, Metasploit, etc.)
+  - `PWN::SAST`
+  - `PWN::Reports`
+  - Shell execution
+  - Memory recall / remember
+  - Skill usage and distillation
+  - Learning / introspection loop
+- Persistent context across interactions via memory and skills.
+
+## Tips
+
+- Use `SHIFT+ENTER` to insert newlines.
+- `ENTER` submits the prompt.
+- Type `back` or `exit` to return to normal REPL.
+- Example prompt:
+  ```
+  Scan https://target with NmapIt + TransparentBrowser (via BurpSuite), 
+  run relevant SAST if source present, exploit any findings, generate report.
+  ```
+
+## Self-Improvement
+
+Successful workflows can be distilled into reusable **Skills** (see [Skills-Memory-Learning](Skills-Memory-Learning.md)).
+
+See also [AI Integration](AI-Integration.md).
+
+[[Diagrams]]

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

@@ -0,0 +1,377 @@
+# 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))
+          }
+        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::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)
+        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::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.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,18 @@ 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
+
         private_class_method def self.append_session(opts = {})
           session_id = opts[:session_id]
           return unless session_id && defined?(PWN::Sessions)
@@ -163,13 +175,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