pwn 0.5.621 → 0.5.622

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

@@ -16,7 +16,7 @@ module PWN
       #
       # Data flows:
       #   Loop.run --(tool telemetry)--> Metrics.record
-      #   Loop.run --(final answer)----> Learning.auto_reflect (opt-in)
+      #   Loop.run --(final answer)----> Learning.auto_introspect (opt-in)
       #   model    --(tool calls)------> learning_note_outcome / _distill_skill
       #   PromptBuilder <----------------- Learning.to_context + Metrics.to_context
       #
@@ -164,9 +164,9 @@ module PWN
         #   dry_run: 'optional - when true, do not write to Memory/Skills (default false)'
         # )
         #
-        # Uses PWN::AI::Agent::Introspection (when available) to LLM-summarise the
+        # Uses PWN::AI::Agent::Reflect (when available) to LLM-summarise the
         # session into structured lessons. Falls back to a heuristic
-        # extractor when introspection is disabled so learning never stops.
+        # extractor when module_reflection is disabled so learning never stops.
 
         public_class_method def self.reflect(opts = {})
           session_id = opts[:session_id]
@@ -193,19 +193,19 @@ module PWN
         end
 
         # Supported Method Parameters::
-        # PWN::AI::Agent::Learning.auto_reflect(
+        # PWN::AI::Agent::Learning.auto_introspect(
         #   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
+        # Called by Loop.run when PWN::Env[:ai][:agent][:auto_introspect] is
         # truthy. Never raises — learning must not break the primary loop.
 
-        public_class_method def self.auto_reflect(opts = {})
+        public_class_method def self.auto_introspect(opts = {})
           session_id = opts[:session_id]
           return unless session_id
-          return unless auto_reflect_enabled?
+          return unless auto_introspect_enabled?
 
           ok = infer_success(session_id: session_id, final: opts[:final])
           note_outcome(
@@ -218,7 +218,7 @@ module PWN
           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}"
+          warn "[pwn-ai/learning] auto_introspect swallowed: #{e.class}: #{e.message}"
           nil
         end
 
@@ -301,10 +301,10 @@ module PWN
         # privates
         # -------------------------------------------------------------
 
-        private_class_method def self.auto_reflect_enabled?
+        private_class_method def self.auto_introspect_enabled?
           return false unless defined?(PWN::Env) && PWN::Env.is_a?(Hash)
 
-          PWN::Env.dig(:ai, :agent, :auto_reflect) ? true : false
+          PWN::Env.dig(:ai, :agent, :auto_introspect) ? true : false
         rescue StandardError
           false
         end
@@ -314,7 +314,7 @@ module PWN
         # Derive a success signal stronger than "final answer non-empty":
         # look at the tool-failure ratio inside the just-completed turn AND
         # scan the final text for self-reported failure language. Without
-        # this, auto_reflect logs ~100 % success and the negative-feedback
+        # this, auto_introspect logs ~100 % success and the negative-feedback
         # side of the learning loop never fires.
         private_class_method def self.infer_success(opts = {})
           final = opts[:final].to_s
@@ -353,11 +353,11 @@ module PWN
 
         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)
+          return [] unless defined?(PWN::AI::Agent::Reflect)
+          return [] unless defined?(PWN::Env) && PWN::Env.is_a?(Hash) && PWN::Env.dig(:ai, :module_reflection)
 
           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 = PWN::AI::Agent::Reflect.on(request: req, suppress_pii_warning: true)
           resp.to_s.lines.map(&:strip).reject(&:empty?).first(5)
         rescue StandardError
           []
@@ -420,7 +420,7 @@ module PWN
               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.auto_introspect(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
@@ -428,7 +428,7 @@ module PWN
               PWN::AI::Agent::Learning.reset
 
               Enable end-of-run auto-learning with:
-                PWN::Env[:ai][:agent][:auto_reflect] = true
+                PWN::Env[:ai][:agent][:auto_introspect] = true
 
               #{self}.authors
           USAGE

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

@@ -241,7 +241,7 @@ 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)
+              Learning.auto_introspect(session_id: session_id, request: request, final: text) if defined?(Learning)
               return text
             end
 

data/lib/pwn/ai/agent/{introspection.rb → reflect.rb}

@@ -5,14 +5,14 @@ require 'json'
 module PWN
   module AI
     module Agent
-      # PWN::AI::Agent::Introspection is the inward-facing counterpart to
+      # PWN::AI::Agent::Reflect 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.
+      # threat-intel), Reflect 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
+      # This module is gated by `PWN::Env[:ai][:module_reflection]` so that
       # potentially-sensitive local data is never shipped to a remote LLM
       # unless the operator has explicitly opted in via pwn-vault / config.
       #
@@ -21,16 +21,16 @@ module PWN
       # 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
+      module Reflect
         # Supported Method Parameters::
-        # response = PWN::AI::Agent::Introspection.reflect_on(
+        # response = PWN::AI::Agent::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 = {})
+        public_class_method def self.on(opts = {})
           request = opts[:request]
           raise 'ERROR: request must be provided' if request.nil?
 
@@ -42,14 +42,14 @@ module PWN
 
           response = nil
 
-          ai_introspection = PWN::Env[:ai][:introspection]
+          ai_module_reflection = PWN::Env[:ai][:module_reflection]
 
-          if ai_introspection && request.length.positive?
+          if ai_module_reflection && 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
+            warn "AI Reflection 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,
@@ -75,7 +75,7 @@ module PWN
 
         public_class_method def self.help
           puts "USAGE:
-            #{self}.reflect_on(
+            #{self}.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)',

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::Agent::Introspection.reflect_on(
+          PWN::AI::Agent::Reflect.on(
             system_role_content: system_role_content,
             request: request,
             suppress_pii_warning: true

data/lib/pwn/ai/agent/tools/extrospection.rb

@@ -258,7 +258,7 @@ PWN::AI::Agent::Registry.register(
     name: 'extro_auto_toggle',
     description: 'Enable/disable end-of-run auto-extrospection ' \
                  '(PWN::Env[:ai][:agent][:auto_extrospect]). When enabled, ' \
-                 'Learning.auto_reflect ALSO calls Extrospection.auto_' \
+                 'Learning.auto_introspect ALSO calls Extrospection.auto_' \
                  'extrospect after every final answer, so host drift is ' \
                  'captured continuously without an explicit extro_snapshot ' \
                  'call. Omit `enabled` to just read the current state.',

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

@@ -190,13 +190,13 @@ PWN::AI::Agent::Registry.register(
 )
 
 PWN::AI::Agent::Registry.register(
-  name: 'learning_auto_reflect_toggle',
+  name: 'learning_auto_introspect_toggle',
   toolset: 'learning',
   schema: {
-    name: 'learning_auto_reflect_toggle',
+    name: 'learning_auto_introspect_toggle',
     description: 'Enable/disable end-of-run auto-reflection ' \
-                 '(PWN::Env[:ai][:agent][:auto_reflect]). When enabled, ' \
-                 'Loop.run calls Learning.auto_reflect on the session after ' \
+                 '(PWN::Env[:ai][:agent][:auto_introspect]). When enabled, ' \
+                 'Loop.run calls Learning.auto_introspect on the session after ' \
                  'every final answer. Disable during noisy fuzzing loops; ' \
                  're-enable for the summary turn. Omit `enabled` to just ' \
                  'read the current state.',
@@ -214,8 +214,8 @@ PWN::AI::Agent::Registry.register(
     raise 'PWN::Env[:ai] is unavailable or immutable' unless ai.is_a?(Hash) && !ai.frozen?
 
     ai[:agent] = (ai[:agent] || {}).dup if ai[:agent].nil? || ai[:agent].frozen?
-    prev = ai[:agent][:auto_reflect] ? true : false
-    ai[:agent][:auto_reflect] = (args[:enabled] ? true : false) if args.key?(:enabled)
-    { previous: prev, current: ai[:agent][:auto_reflect] ? true : false }
+    prev = ai[:agent][:auto_introspect] ? true : false
+    ai[:agent][:auto_introspect] = (args[:enabled] ? true : false) if args.key?(:enabled)
+    { previous: prev, current: ai[:agent][:auto_introspect] ? true : false }
   }
 )

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

@@ -20,7 +20,7 @@ module PWN
 
           system_role_content = "Being an expert penetration tester skilled in code analysis, debugging, and exploitation while stepping through JavaScript in a Chrome DevTools debugging session:  1. Your sole purpose is to analyze each JavaScript step and generate an Exploit Prediction Scoring System (EPSS) score between 0% - 100%.  The step currently resides in this block of JavaScript:\n```\n#{source_to_review}\n```\n2. If the score is >= 75%, generate a JavaScript proof-of-concept that would allow a threat actor to directly exploit or target a user for exploitation (i.e. no self-exploit).  3. If the EPSS score is >= 75% also provide a code fix. *** If the EPSS score is < 75%, no explanations or summaries - just the EPSS score."
 
-          PWN::AI::Agent::Introspection.reflect_on(
+          PWN::AI::Agent::Reflect.on(
             system_role_content: system_role_content,
             request: request,
             suppress_pii_warning: true

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

@@ -12,7 +12,7 @@ module PWN
       # 4. CVSS score, vector string, and first.org calculator URI
       # 5. CWE category, brief description, and CWE URI
       # 6. Relevant NIST 800-53 control
-      # It leverages the PWN::AI::Agent::Introspection.reflect_on method. Defaults to Jira for existing workflow compatibility.
+      # It leverages the PWN::AI::Agent::Reflect.on method. Defaults to Jira for existing workflow compatibility.
       module VulnGen
         # Supported Method Parameters::
         # ai_analysis = PWN::AI::Agent::VulnGen.analyze(
@@ -60,7 +60,7 @@ module PWN
           6. NIST 800-53 Security Control that is impacted by this vulnerability.
           "
 
-          analysis = PWN::AI::Agent::Introspection.reflect_on(
+          analysis = PWN::AI::Agent::Reflect.on(
             system_role_content: system_role_content,
             request: request,
             suppress_pii_warning: true

data/lib/pwn/ai/agent.rb

@@ -27,7 +27,7 @@ module PWN
       autoload :Learning,      'pwn/ai/agent/learning'
       autoload :Mistakes,      'pwn/ai/agent/mistakes'
       autoload :Extrospection, 'pwn/ai/agent/extrospection'
-      autoload :Introspection, 'pwn/ai/agent/introspection'
+      autoload :Reflect,       'pwn/ai/agent/reflect'
       autoload :Swarm,         'pwn/ai/agent/swarm'
 
       # Display a List of Every PWN::AI Module

data/lib/pwn/ai/open_ai.rb

@@ -250,17 +250,21 @@ module PWN
         end
         messages.push(user_role)
 
-        # `max_tokens` is deprecated on /v1/chat/completions; the unified
-        # parameter is `max_completion_tokens` and works for every chat model
+        # Wire config key `max_tokens` (kept for cross-engine naming parity with
+        # Anthropic/Gemini) to the OpenAI wire-format field `max_completion_tokens`.
+        # OpenAI deprecated the request-body key `max_tokens` on /v1/chat/completions
+        # in favour of `max_completion_tokens`, which works for every chat model
         # including the reasoning family. Don't try to guess per-model caps —
-        # let the server clamp; default to a generous ceiling that the
-        # operator can override via PWN::Env[:ai][:openai][:max_completion_tokens].
-        max_completion_tokens = (engine[:max_completion_tokens] || 16_384).to_i
+        # let the server clamp; default to a generous ceiling that the operator
+        # can override via PWN::Env[:ai][:openai][:max_tokens].
+        # Accept legacy :max_completion_tokens as a one-release alias so existing
+        # pwn.yaml files keep working without a silent clamp to the default.
+        max_tokens = (engine[:max_tokens] || engine[:max_completion_tokens] || 16_384).to_i
 
         http_body = {
           model: model,
           messages: messages,
-          max_completion_tokens: max_completion_tokens
+          max_completion_tokens: max_tokens
         }
         # Reasoning models reject sampler params (temperature, top_p, etc.)
         http_body[:temperature] = temp unless reasoning

data/lib/pwn/config.rb

@@ -29,7 +29,7 @@ module PWN
       env = {
         ai: {
           active: 'grok',
-          introspection: false,
+          module_reflection: false,
           grok: {
             base_uri: 'optional - Base URI for Grok - Use private base OR defaults to https://api.x.ai/v1',
             key: 'required - xAI Grok API Key',
@@ -58,6 +58,7 @@ module PWN
             model: 'optional - OpenAI model to use',
             system_role_content: 'You are an ethically hacking OpenAI agent.',
             temp: 'optional - OpenAI temperature',
+            max_tokens: 'optional - Max output tokens per response (default 16384). Mapped to OpenAI wire param max_completion_tokens.',
             max_prompt_length: 128_000
           },
           ollama: {
@@ -90,9 +91,9 @@ module PWN
             max_iters: 25,
             # Swarm (agent_ask/agent_debate) sub-agent recursion cap
             max_depth: 3,
-            # run PWN::AI::Agent::Learning.auto_reflect after every final answer
-            auto_reflect: true,
-            # also run PWN::AI::Agent::Extrospection.auto_extrospect from auto_reflect
+            # run PWN::AI::Agent::Learning.auto_introspect after every final answer
+            auto_introspect: true,
+            # also run PWN::AI::Agent::Extrospection.auto_extrospect from auto_introspect
             auto_extrospect: false,
             toolsets: nil
             # multi-agent personas : ~/.pwn/agents.yml  (see PWN::AI::Agent::Swarm.help)

data/lib/pwn/plugins/burp_suite.rb

@@ -50,7 +50,7 @@ module PWN
       #   type: 'required - type of history to introspect (:sitemap, :proxy_history, :websocket_history)'
       # )
       private_class_method def self.init_introspection_thread(opts = {})
-        #  if PWN::Env[:ai][:introspection] is true,
+        #  if PWN::Env[:ai][:module_reflection] is true,
         #  spin up Thread to:
         #  1. Periodically call get_proxy_history(burp_obj: burp_obj) method
         #  2. For each entry w/ empty comment,
@@ -65,7 +65,7 @@ module PWN
         type = opts[:type]
         raise "ERROR: type parameter is required and must be one of: #{valid_types.join(', ')}" unless valid_types.include?(type)
 
-        if PWN::Env[:ai][:introspection]
+        if PWN::Env[:ai][:module_reflection]
           introspection_thread_arr = burp_obj[:introspection_threads] ||= []
           introspection_thread = Thread.new do
             get_highlight_color = lambda do |opts = {}|

data/lib/pwn/sast/pom_version.rb

@@ -19,8 +19,8 @@ module PWN
         dir_path = opts[:dir_path]
         git_repo_root_uri = opts[:git_repo_root_uri].to_s.scrub
         result_arr = []
-        ai_introspection = PWN::Env[:ai][:introspection]
-        logger_results = "AI Introspection => #{PWN::Env[:ai][:introspecction]} => "
+        ai_module_reflection = PWN::Env[:ai][:module_reflection]
+        logger_results = "AI Module Reflection => #{PWN::Env[:ai][:module_reflection]} => "
 
         PWN::Plugins::FileFu.recurse_in_dir(dir_path: dir_path) do |entry|
           if File.file?(entry) && File.basename(entry) == 'pom.xml' && entry !~ /test/i

data/lib/pwn/sast/test_case_engine.rb

@@ -63,7 +63,7 @@ module PWN
         git_repo_root_uri = opts[:git_repo_root_uri].to_s.scrub
 
         result_arr = []
-        logger_results = "AI Introspection => #{PWN::Env[:ai][:introspection]} => "
+        logger_results = "AI Module Reflection => #{PWN::Env[:ai][:module_reflection]} => "
 
         PWN::Plugins::FileFu.recurse_in_dir(
           dir_path: dir_path,

data/lib/pwn/sdr/gqrx.rb

@@ -809,7 +809,7 @@ module PWN
             puts "\s\s- A lower `Input rate` value seems counter-intuitive but works well (e.g. ADALM PLUTO ~ 1000000)."
             puts '2. Adjust the :strength_lock parameter.'
             puts '3. Adjust the :precision parameter.'
-            puts '4. Disable AI introspection in PWN::Env'
+            puts '4. Disable AI module_reflection in PWN::Env'
             puts 'Happy scanning!'
             puts '-' * 86
             # print 'Pressing ENTER to begin scan...'

data/lib/pwn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PWN
-  VERSION = '0.5.621'
+  VERSION = '0.5.622'
 end

data/spec/lib/pwn/ai/agent/{introspection_spec.rb → reflect_spec.rb}

@@ -2,14 +2,14 @@
 
 require 'spec_helper'
 
-describe PWN::AI::Agent::Introspection do
+describe PWN::AI::Agent::Reflect do
   it 'should display information for authors' do
-    authors_response = PWN::AI::Agent::Introspection
+    authors_response = PWN::AI::Agent::Reflect
     expect(authors_response).to respond_to :authors
   end
 
   it 'should display information for existing help method' do
-    help_response = PWN::AI::Agent::Introspection
+    help_response = PWN::AI::Agent::Reflect
     expect(help_response).to respond_to :help
   end
 end