pwn 0.5.708 → 0.5.709

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

@@ -44,7 +44,7 @@ module PWN
       #
       # PromptBuilder re-injects Extrospection.to_context on every turn.
       # Persistence: ~/.pwn/extrospection.json across REPL restarts.
-      module Extrospection
+      module Extrospection # rubocop:disable Metrics/ModuleLength
         EXTRO_FILE = File.join(Dir.home, '.pwn', 'extrospection.json')
         MAX_OBSERVATIONS = 500
         # CLI tools that accept a cheap, non-interactive --version / -V.
@@ -3630,65 +3630,190 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              PWN::AI::Agent::Extrospection.snapshot                          # probe host, persist, return {snapshot:, drift:}
-              PWN::AI::Agent::Extrospection.drift(live: true)                 # what changed vs last snapshot
-              PWN::AI::Agent::Extrospection.observe(source: 'nmap', category: :recon, target: '10.0.0.5', data: '22/tcp open ssh 9.6')
-              PWN::AI::Agent::Extrospection.observe(source: 'gqrx', category: :rf, target: '433.920MHz', data: 'peak -34.2 dBFS bw=200k')
-              PWN::AI::Agent::Extrospection.observations(category: 'recon', target: '10.0.0.5')
-              PWN::AI::Agent::Extrospection.intel(query: 'openssl 3.0', record: true)
-              PWN::AI::Agent::Extrospection.correlate                         # introspection x extrospection findings
-              PWN::AI::Agent::Extrospection.to_context                        # injected by PromptBuilder
-              PWN::AI::Agent::Extrospection.stats
-              PWN::AI::Agent::Extrospection.auto_extrospect(session_id: sid)  # called from Learning.auto_introspect
-              PWN::AI::Agent::Extrospection.snapshot(sections: %i[web])        # opt-in browser probe of web_anchors
-              PWN::AI::Agent::Extrospection.watch(url: 'https://target/api/version')
-              PWN::AI::Agent::Extrospection.rf_tune(freq: '101.1')                 # tune GQRX + RDS → now_playing
-              PWN::AI::Agent::Extrospection.osint(query: '+13125551212', kind: :phone)
-              PWN::AI::Agent::Extrospection.osint(query: '2ABIP-ESP32', kind: :fcc_id)
-              PWN::AI::Agent::Extrospection.osint(query: 'US10123456', kind: :patent)
-              PWN::AI::Agent::Extrospection.osint(query: '1HGCM82633A004352', kind: :vin)
-              PWN::AI::Agent::Extrospection.osint(query: '00:11:22:33:44:55', kind: :mac)
-              PWN::AI::Agent::Extrospection.osint(query: 'W1AW', kind: :callsign)
-              PWN::AI::Agent::Extrospection.osint(query: 'CVE-2021-44228', kind: :cve)
-              PWN::AI::Agent::Extrospection.serial_sense(payload: "ATI\r")
-              PWN::AI::Agent::Extrospection.telecomm(action: :status)
-              PWN::AI::Agent::Extrospection.packet_sense(action: :capture, filter: 'tcp port 443', count: 10)
-              PWN::AI::Agent::Extrospection.vision(file: '/tmp/shot.png', action: :ocr)
-              PWN::AI::Agent::Extrospection.voice_sense(action: :tts, text: 'hello from pwn')
-              PWN::AI::Agent::Extrospection.verify(claim: 'CVE-2026-12345 affects OpenSSL 3.2.1')
-              PWN::AI::Agent::Extrospection.revalidate_memory                  # cron: GC stale PWN::Memory :fact entries
-              PWN::AI::Agent::Extrospection.reset
-
-              PRIMARY use = on-demand sensing (intel / verify / watch / rf_tune / osint /
-              serial_sense / telecomm / packet_sense / vision / voice_sense / observe /
-              rf / web / osint / serial / telecomm / packet / vision / voice).
-              auto_extrospect is OPTIONAL ambient baseline (host/repo/env only - never
-              launches burpsuite/zaproxy/msfconsole/gqrx). Prefer calling sense tools
-              when a question needs the outside world, not after every turn.
-
-              Enable end-of-run ambient baseline with:
-                PWN::Env[:ai][:agent][:auto_extrospect] = true   # sections: AUTO_SECTIONS
-
-              Configure browser-backed :web probe / verify / watch with:
-                PWN::Env[:ai][:agent][:extrospection][:web] =
-                  { anchors: [...], proxy: 'tor', max_anchors: 8, per_page_timeout: 15, screenshot: false, allow_targets: false }
-
-              Configure RF sense (rf_tune) with:
-                PWN::Env[:ai][:agent][:extrospection][:rf] =
-                  { host: '127.0.0.1', port: 7356, settle_secs: 8, ttl: 300 }
-
-              Configure new limbs:
-                PWN::Env[:ai][:agent][:extrospection][:osint]    = { ttl: 86400, api_keys: { shodan: '...', hunter: '...', abuseipdb: '...', virustotal: '...', greynoise: '...', haveibeenpwned: '...', securitytrails: '...', steam: '...' }, social: { max_threads: 16, timeout: 6, sites_file: 'etc/osint/social_sites.json', mastodon_instance: 'mastodon.social' }, bridges: { timeout: 120, amass_passive: true } }
-                PWN::Env[:ai][:agent][:extrospection][:serial]   = { block_dev: '/dev/ttyUSB0', baud: 115200, settle_secs: 1.5 }
-                PWN::Env[:ai][:agent][:extrospection][:telecomm] = { host: '127.0.0.1', port: 8000 }
-                PWN::Env[:ai][:agent][:extrospection][:packet]   = { iface: 'eth0' }
-                PWN::Env[:ai][:agent][:extrospection][:vision]   = { lang: 'eng' }
-                PWN::Env[:ai][:agent][:extrospection][:voice]    = { ttl: 3600 }
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run load and return its result
+            #{self}.load
+
+            # Run save and return its result
+            #{self}.save(
+              store: 'required - Hash returned by .load / mutated in place'
+            )
+
+            # Run snapshot and return its result
+            #{self}.snapshot(
+              persist: 'optional - Boolean, write snapshot to disk & rotate previous (default true)',
+              sections: 'optional - Array subset of [:host, :net, :toolchain, :repo, :env, :rf, :web, :osint, :serial, :telecomm, :packet, :vision, :voice] (default host/net/toolchain/repo/env/rf)'
+            )
+
+            # Run observe and return its result
+            #{self}.observe(
+              source: 'required - where the observation came from (nmap, shodan, burp, cve, human, ...)',
+              data: 'required - the observation payload (String or Hash)',
+              category: 'optional - :recon, :vuln, :intel, :target, :network, :env, :rf, :web, :osint, :serial, :telecomm, :packet, :vision, :voice, :misc (default :misc)',
+              target: 'optional - host/ip/url/asset the observation is about',
+              tags: 'optional - Array of String labels',
+              ttl: 'optional - seconds until this observation is considered stale (default nil = forever)'
+            )
+
+            # Run observations and return its result
+            #{self}.observations(
+              limit: 'optional - max entries newest-first (default 50)',
+              source: 'optional - filter by source substring',
+              category: 'optional - filter by category',
+              target: 'optional - filter by target substring',
+              tag: 'optional - filter by tag substring',
+              fresh_only: 'optional - drop entries whose ttl has expired (default false)'
+            )
+
+            # Run drift and return its result
+            #{self}.drift(
+              live: 'optional - probe host NOW and diff vs stored snapshot (default true). When false, diff stored :snapshot vs stored :previous.'
+            )
+
+            # Run intel and return its result
+            #{self}.intel(
+              query: 'required - keyword / product / CVE id to search external threat-intel for',
+              feeds: 'optional - Array subset of [:nvd, :circl, :exploitdb] (default all)',
+              limit: 'optional - max results per feed (default 5)',
+              record: 'optional - also persist each hit as an observation (default false)'
+            )
+
+            # Run verify and return its result
+            #{self}.verify(
+              claim: 'required - factual claim to fact-check against the live web',
+              kind: 'optional - :cve | :version | :doc | :generic (default auto-detect)',
+              url: 'optional - explicit URL the claim cites (forces kind: :doc)',
+              commit: 'optional - write Mistakes/Memory/observe on refute/confirm (default true)',
+              proxy: 'optional - upstream proxy for TransparentBrowser (e.g. tor) (defaults to web_config[:proxy])',
+              in: 'optional - headless mode against a canonical source for the claim class',
+              confidence: 'optional - confidence value consumed by #verify',
+              evidence: 'required - [{url:, title:, excerpt:, dom_sha:, screenshot:}]',
+              action_taken: 'required - :mistakes_record | :extro_observe | :learning_note | nil }'
+            )
+
+            # Run watch and return its result
+            #{self}.watch(
+              url: 'required - URL to render and fingerprint',
+              selector: 'optional - CSS selector whose innerText to hash (default full body)',
+              ttl: 'optional - seconds until stale (default 7 days)',
+              proxy: 'optional - upstream proxy for TransparentBrowser (defaults to web_config[:proxy])',
+              tags: 'optional - Array tags value consumed by #watch'
+            )
+
+            # Run rf tune and return its result
+            #{self}.rf_tune(
+              freq: 'required - frequency: 101.1, 101.1 FM, 101.100.000, 101_100_000, ...',
+              host: 'optional - GQRX remote-control host (default 127.0.0.1)',
+              port: 'optional - GQRX remote-control port (default 7356)',
+              settle_secs: 'optional - seconds to sample RDS after tune (default 8)',
+              rds: 'optional - force RDS on/off (default: auto when FM broadcast / band-plan decoder=:rds)',
+              demodulator_mode: 'optional - e.g. :WFM_ST, :WFM, :FM, :AM (default from band-plan / FM range)',
+              bandwidth: 'optional - passband Hz string, e.g. 200.000 (default from band-plan)',
+              record: 'optional - also observe(category: :rf) so it hits EXTROSPECTION (default true)',
+              ttl: 'optional - observation TTL seconds (default 300 - radio content is ephemeral)'
+            )
+
+            # OSINT sense organ
+            #{self}.osint(
+              query: 'required - phone, IP, domain, email, person name, FCC ID, patent #, username, VIN, MAC, callsign, ...',
+              kind: 'optional - auto|:ip|:geo|:dns|:whois|:rdap|:crtsh|:bgp|:shodan|:hunter|:phone|:fcc_id|:patent|:person|:username|:github|:wayback|:url|:company|:cik|:openfda|:vital_records|:threat|:vin|:mac|:callsign|:npi|:cve (default :auto)',
+              feeds: 'optional - Array subset of DEFAULT_OSINT_FEEDS (default: auto-selected from kind)',
+              limit: 'optional - max hits per feed (default 5)',
+              record: 'optional - also observe(category: :osint) (default true)',
+              ttl: 'optional - observation TTL seconds (default 86400)',
+              api_keys: 'optional - Hash of {shodan:, hunter:, abuseipdb:, virustotal:, greynoise:, haveibeenpwned:, securitytrails:} overriding PWN::Env / ENV'
+            )
+
+            # Serial sense organ
+            #{self}.serial_sense(
+              block_dev: 'optional - device path (default first ttyUSB/ttyACM or config)',
+              baud: 'optional - baud rate (default 9600)',
+              payload: 'optional - String or byte Array to write (e.g. ATI\\\\r or [0x41,0x54])',
+              settle_secs: 'optional - seconds to read after write (default 1.5)',
+              data_bits: 'optional - optional (default 8)',
+              stop_bits: 'optional - optional (default 1)',
+              parity: 'optional - optional :none|:even|:odd (default :none)',
+              record: 'optional - observe(category: :serial) (default true)',
+              ttl: 'optional - observation TTL (default 600)'
+            )
+
+            # Telecomm sense organ (SIP / VoIP / PSTN via BareSIP)
+            #{self}.telecomm(
+              action: 'optional - :status|:dial|:hangup|:inventory (default :inventory)',
+              target: 'optional - SIP URI / phone number for :dial (e.g. sip:alice@example.com or +13125551212)',
+              host: 'optional - BareSIP HTTP control host (default 127.0.0.1)',
+              port: 'optional - BareSIP HTTP control port (default 8000)',
+              record: 'optional - observe(category: :telecomm) (default true)',
+              ttl: 'optional - observation TTL (default 600)'
+            )
+
+            # Packet sense organ
+            #{self}.packet_sense(
+              action: 'optional - :inventory|:capture|:summarize_pcap (default :inventory)',
+              iface: 'optional - capture interface (default first non-lo or any)',
+              filter: 'optional - BPF filter (e.g. tcp port 443)',
+              count: 'optional - packets to capture (default 20, max 200)',
+              timeout: 'optional - capture seconds (default 5, max 60)',
+              path: 'optional - pcap path for :summarize_pcap',
+              record: 'optional - observe(category: :packet) (default true)',
+              ttl: 'optional - observation TTL (default 600)'
+            )
+
+            # Vision / OCR sense organ
+            #{self}.vision(
+              file: 'required - path to image / screenshot / PDF-page render',
+              action: 'optional - :ocr|:barcode|:inventory (default :ocr when file given, else :inventory)',
+              lang: 'optional - tesseract language (default eng)',
+              record: 'optional - observe(category: :vision) (default true)',
+              ttl: 'optional - observation TTL (default 86400)'
+            )
+
+            # Voice sense organ (TTS / STT / inventory)
+            #{self}.voice_sense(
+              action: 'optional - :inventory|:tts|:stt (default :inventory)',
+              text: 'optional - text to speak for :tts (or text_path:)',
+              text_path: 'optional - path to text file for :tts',
+              audio: 'optional - path to audio file for :stt',
+              out: 'optional - output audio path for :tts (wav)',
+              engine: 'optional - :espeak|:festival|:spd_say|:whisper (auto)',
+              model: 'optional - whisper model (default tiny)',
+              record: 'optional - observe(category: :voice) (default true)',
+              ttl: 'optional - observation TTL (default 3600)'
+            )
+
+            # Run revalidate memory and return its result
+            #{self}.revalidate_memory(
+              limit: 'optional - max :fact entries to check (default 25)',
+              proxy: 'optional - upstream proxy for TransparentBrowser (defaults to web_config[:proxy])',
+              ruby: 'optional - PWN::AI::Agent::Extrospection.revalidate_memory'
+            )
+
+            # Run correlate and return its result
+            #{self}.correlate(
+              limit: 'optional - max findings returned (default 10)'
+            )
+
+            # Run to context and return its result
+            #{self}.to_context(
+              drift_limit: 'optional - max drift lines (default 4)',
+              obs_limit: 'optional - max observation lines (default 4)'
+            )
+
+            # Run stats and return its result
+            #{self}.stats
+
+            # Called by Learning.auto_introspect when
+            #{self}.auto_extrospect(
+              session_id: 'optional - id of the just-completed session (for tagging)'
+            )
+
+            # Run reset and return its result
+            #{self}.reset
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -41,13 +41,16 @@ module PWN
 
         public_class_method def self.help
           puts "USAGE:
-            ai_analysis = PWN::AI::Agent::GQRX.analyze(
+            # Run analyze and return its result
+            #{self}.analyze(
               request: 'required - A string containing the signal data captured by GQRX that you want to analyze. This data should be in a format that can be interpreted by the AI for analysis, such as raw signal data, frequency information, or any relevant metadata associated with the capture.',
               location: 'required - A string containing a city, state, country, or GPS coordinates where the signal data was captured. This information will be used to provide context for the analysis and to determine if the frequency is licensed or unlicensed based on FCC records.'
             )
 
+            # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "
+          constants.sort
         end
       end
     end

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

@@ -51,13 +51,16 @@ module PWN
 
         public_class_method def self.help
           puts "USAGE:
-            ai_analysis = PWN::AI::Agent::HackerOne.analyze(
-              request: 'required - dataset to analyze, such as bounty program details, scope details, or hacktivity details'
+            # Run analyze and return its result
+            #{self}.analyze(
+              request: 'required - dataset to analyze, such as bounty program details, scope details, or hacktivity details',
               type: 'required - type of analysis to perform, such as :bounty_programs, :scope_details, or :hacktivity'
             )
 
+            # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "
+          constants.sort
         end
       end
     end

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

@@ -1771,31 +1771,148 @@ module PWN
         # 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_introspect(session_id: sid, request: req, final: text)
-              PWN::AI::Agent::Learning.distill_skill(name: 'quick_recon', session_id: sid)
-              PWN::AI::Agent::Learning.exemplars_for(request: 'nmap sweep 10/8')  # few-shot for Loop.run
-              PWN::AI::Agent::Learning.export_finetune(format: :sharegpt)        # -> ~/.pwn/finetune/*.jsonl
-              PWN::AI::Agent::Learning.consolidate(max_entries: 200)         # M1 semantic-merge + M3 importance-evict
-              PWN::AI::Agent::Learning.lean!                                 # memory + learning.jsonl prune
-              PWN::AI::Agent::Learning.gc_stores!                            # full ~/.pwn RL lean (mem/learn/mistakes/sessions)
-              PWN::AI::Agent::Learning.prune_outcomes!                       # learning.jsonl gold-keep cap
-              PWN::AI::Agent::Learning.purge_noise                            # one-shot GC of pre-R1 garbage lessons
-              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_introspect] = true
-              # auto_introspect throttles gc_stores! every PRUNE_EVERY_N_APPENDS
-              # outcomes so ~/.pwn stays lean without a manual GC turn.
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run note outcome and return its result
+            #{self}.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',
+              score: 'optional - score value consumed by #note_outcome',
+              judge_source: 'required - judge source value consumed by #note_outcome',
+              predicted: 'optional - predicted value consumed by #note_outcome',
+              confidence: 'optional - confidence value consumed by #note_outcome',
+              engine: 'optional - engine value consumed by #note_outcome'
+            )
+
+            # Run outcomes and return its result
+            #{self}.outcomes(
+              limit: 'optional - max entries returned newest-first (default 50)',
+              success: 'optional - filter by Boolean outcome',
+              tag: 'optional - filter by tag substring'
+            )
+
+            # Run stats and return its result
+            #{self}.stats
+
+            # Run to context and return its result
+            #{self}.to_context(
+              limit: 'optional - number of recent outcomes to surface (default 5)'
+            )
+
+            # Run exemplars for and return its result
+            #{self}.exemplars_for(
+              request: 'required - current user request',
+              limit: 'optional - max exemplar traces to return (default 1)',
+              max_msgs: 'optional - cap on messages per exemplar (default 6)'
+            )
+
+            # Run export finetune and return its result
+            #{self}.export_finetune(
+              format: 'optional - format value consumed by #export_finetune (defaults to :sharegpt))',
+              min_tools: 'optional - min tools value consumed by #export_finetune',
+              min_score: 'optional - min score value consumed by #export_finetune',
+              compress: 'optional - compress value consumed by #export_finetune',
+              out: 'optional - out value consumed by #export_finetune'
+            )
+
+            # Run distill skill and return its result
+            #{self}.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',
+              description: 'optional - description value consumed by #distill_skill'
+            )
+
+            # Fold RL artefacts (mistakes / structured_fix / an explicit lesson)
+            #{self}.update_skill(
+              dry_run: 'optional - dry run value consumed by #update_skill',
+              lesson: 'optional - lesson value consumed by #update_skill',
+              signature: 'optional - signature value consumed by #update_skill',
+              request: 'optional - request value consumed by #update_skill (defaults to opts[:query])',
+              query: 'optional - search query string',
+              name: 'required - binary or identifier name'
+            )
+
+            # Run reflect and return its result
+            #{self}.reflect(
+              session_id: 'required - PWN::Sessions id to analyse',
+              dry_run: 'optional - when true, do not write to Memory/Skills (default false)'
+            )
+
+            # Called by Loop.run when PWN::Env[:ai][:agent][:auto_introspect] is
+            #{self}.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)',
+              inline: 'optional - inline value consumed by #auto_introspect',
+              predicted: 'optional - predicted value consumed by #auto_introspect',
+              plan: 'optional - plan value consumed by #auto_introspect',
+              ts_state: 'optional - ts state value consumed by #auto_introspect'
+            )
+
+            # Run flip last outcome and return its result
+            #{self}.flip_last_outcome(
+              session_id: 'optional - session id value consumed by #flip_last_outcome',
+              reason: 'optional - reason value consumed by #flip_last_outcome'
+            )
+
+            # Run consolidate and return its result
+            #{self}.consolidate(
+              max_entries: 'optional - hard cap on PWN::Memory size (default MAX_MEMORY_ENTRIES)'
+            )
+
+            # Run reset and return its result
+            #{self}.reset
+
+            # One-shot / on-load repair: rewrite tags+details where verdict label
+            #{self}.reconcile_verdict_tags!(
+              dry_run: 'optional - dry run value consumed by #reconcile_verdict_tags!'
+            )
+
+            # Run prune outcomes and return its result
+            #{self}.prune_outcomes!(
+              dry_run: 'optional - Boolean (default false)',
+              max_rows: 'optional - hard cap (default MAX_OUTCOME_ROWS)',
+              retain_days: 'optional - age floor for low-value drop',
+              recent_days: 'optional - always keep newer than this',
+              details_max: 'optional - details max value consumed by #prune_outcomes!',
+              gold_min_score: 'optional - gold min score value consumed by #prune_outcomes!'
+            )
+
+            # Memory lean + outcome prune
+            #{self}.lean!(
+              dry_run: 'optional - dry run value consumed by #lean!',
+              max_entries: 'optional - max entries value consumed by #lean!',
+              max_rows: 'optional - max rows value consumed by #lean!',
+              retain_days: 'optional - retain days value consumed by #lean!',
+              recent_days: 'optional - recent days value consumed by #lean!',
+              details_max: 'optional - details max value consumed by #lean!',
+              gold_min_score: 'optional - gold min score value consumed by #lean!'
+            )
+
+            # One-shot lean across memory + learning + mistakes + sessions
+            #{self}.gc_stores!(
+              dry_run: 'optional - Boolean (default false)',
+              current_session_id: 'optional - never delete this sessions id',
+              max_entries: 'optional - Memory consolidate cap',
+              max_rows: 'optional - learning.jsonl cap',
+              retain_days: 'optional - outcome / session age floor',
+              recent_days: 'optional - recent days value consumed by #gc_stores!',
+              details_max: 'optional - details max value consumed by #gc_stores!',
+              gold_min_score: 'optional - gold min score value consumed by #gc_stores!',
+              max_files: 'optional - max files value consumed by #gc_stores!'
+            )
+
+            # One-shot GC of the pre-R1 garbage: drops every PWN::Memory entry
+            #{self}.purge_noise
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -3071,52 +3071,59 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              final = PWN::AI::Agent::Loop.run(
-                request: '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,1_024]}" },
-                system_role_content: 'You are a helpful assistant that can call tools to answer questions.'
-              )
-              # Live task summaries (default ON): BEFORE each tool *collection*,
-              # on_tool('task', high_level_brief, '') — one-to-many with real tools.
-              # Task lines never carry a result payload (no result row in the TUI).
-              # so repl.rb prints name=task with arg_preview=summary. Also coalesce bursts into
-              # via on_tool only: [ ts → pwn-ai → task ] <brief> (no [pwn-ai/task] prefix)
-              # Toggle via PWN::Env[:ai][:agent]:
-              #   task_summary: true|false
-              #   task_summary_every: 5          # emit every N tools
-              #   task_summary_interval_s: 8.0   # or every N seconds
-              #   task_summary_verbose: false
-
-              Supported engines: #{ENGINE_MODS.keys.join(', ')}
-              Set PWN::Env[:ai][:active] to choose.
-
-              Intent routing (all engines; critical for ollama/openwebui):
-                how-to / usage questions → text-only explanation (no tools, no plan_first)
-                pure prior-turn recall ("what did I just say?") → answer_recall (no tools)
-                pure greeting / light smalltalk → answer_greeting (no tools, no weather echo)
-                live sweeps are host-work goals like any other — pwn-ai does not
-                decide authorization
-              Local-model scaffolding (PWN::Env[:ai][:agent]):
-                :plan_first          - Boolean, plan-then-act pre-pass (default: local engine :ollama/:openwebui)
-                :tool_router         - Boolean/nil, slim Registry.definitions (nil=auto on for ollama)
-                :escalation_persona  - Swarm persona name for frontier corrective hints when stuck
-                :critic              - S3 constitutional critic before every final (Boolean)
-                :red_team_plan       - S4 adversarial plan review after plan_first (Boolean)
-                :counterfactual      - S2 A/B branch on REPEAT_THRESHOLD → DPO pair (Boolean)
-                :hindsight           - C3 HER-relabel failures (Boolean, default true)
-                :policy              - R5 live tabular Q / REINFORCE (Boolean, default true; advisory only)
-                :verify_as_reward    - E3 ground every final via extro_verify (Boolean)
-
-              P28 autonomy: incomplete-final detector refuses mid-goal handoffs.
-              Loop.run keeps CORE_TOOLS until may_finalize? — there is no
-              iteration-budget abort.
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run debug on and return its result
+            #{self}.debug_on?(
+              debug: 'optional - debug value consumed by #debug_on?'
+            )
+
+            # True only when the ask needs a live host/file/browser effect. World-knowledge
+            #{self}.catalog_lookup?(
+              request: 'required - request value consumed by #catalog_lookup?'
+            )
+
+            # Run world knowledge and return its result
+            #{self}.world_knowledge?(
+              request: 'required - request value consumed by #world_knowledge?'
+            )
+
+            # Run needs host work and return its result
+            #{self}.needs_host_work?(
+              request: 'required - request value consumed by #needs_host_work?'
+            )
+
+            # Run ollama wire messages and return its result
+            #{self}.ollama_wire_messages(
+              messages: 'required - in-memory OpenAI-ish messages (may have String args)'
+            )
+
+            # Run openai wire messages and return its result
+            #{self}.openai_wire_messages(
+              messages: 'required - in-memory OpenAI-ish messages (may have Hash args / internal keys)'
+            )
+
+            # Run request intent and return its result
+            #{self}.request_intent(
+              request: 'optional - request value consumed by #request_intent'
+            )
+
+            # Run run and return its result
+            #{self}.run(
+              request: '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',
+              system_role_content: 'optional - override default system prompt (built from session_id if not provided)',
+              debug: 'optional - debug value consumed by #run',
+              from: 'optional - sender account or address to bind as operator',
+              account: 'optional - operator account id to bind',
+              force_tools: 'optional - force tools value consumed by #run'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end