pwn 0.5.708 → 0.5.709

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

@@ -175,19 +175,23 @@ module PWN
 
         public_class_method def self.help
           puts "USAGE:
+            # Run on and return its result
             #{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',
-              engine: 'optional - override engine (Symbol) for teacher-student reflection; defaults to PWN::Env[:ai][:reflect_engine]',
+              engine: 'optional - override engine for THIS reflection only (Symbol/String); defaults to PWN::Env[:ai][:reflect_engine] || :active',
+              model: 'optional - override model on the reflection engine for THIS call only; defaults to PWN::Env[:ai][:reflect_model]',
               spinner: 'optional - Boolean - Display spinner during operation (default: false)',
-              suppress_pii_warning: 'optional - Boolean - Suppress PII Warnings (default: false)'
+              suppress_pii_warning: 'optional - Boolean - Suppress PII Warnings (default: false)',
+              timeout: 'optional - seconds to wait before giving up',
+              temp: 'optional - temp value consumed by #on',
+              quiet: 'optional - quiet value consumed by #on'
             )
 
-            Teacher-student config:
-              PWN::Env[:ai][:reflect_engine] = :anthropic   # execute on :active, critique on :anthropic
-
+            # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "
+          constants.sort
         end
       end
     end

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

@@ -347,18 +347,71 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              PWN::AI::Agent::Registry.discover
-              PWN::AI::Agent::Registry.definitions(enabled: %w[terminal pwn])
-              PWN::AI::Agent::Registry.definitions(relevance: 'nmap sweep 10/8')  # slim (needs :tool_router)
-              PWN::AI::Agent::Registry.rank(query: 'run a shell command')
-              PWN::AI::Agent::Registry.lookup(name: 'shell')   # => Entry
-              PWN::AI::Agent::Registry.toolsets                # => ["memory","pwn","skills","terminal"]
-              PWN::AI::Agent::Registry.register(name:, toolset:, schema:, handler:)
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run register and return its result
+            #{self}.register(
+              name: 'required - tool name exposed to the model',
+              toolset: 'required - grouping for enable/disable (terminal, file, pwn, memory…)',
+              schema: 'required - OpenAI function schema {name:, description:, parameters:}',
+              handler: 'required - ->(args_hash) { ... } returning a JSON-serialisable object',
+              check: 'optional - -> { bool } gate; tool only advertised when truthy',
+              max_chars: 'optional - cap on serialised result (default 24_000)'
+            )
+
+            # Run lookup and return its result
+            #{self}.lookup(
+              name: 'required - registered tool name'
+            )
+
+            # Run all and return its result
+            #{self}.all
+
+            # Run toolsets and return its result
+            #{self}.toolsets
+
+            # Run definitions and return its result
+            #{self}.definitions(
+              enabled: 'optional - Array of toolset names to include; nil = all whose check passes',
+              relevance: 'optional - user request; when set AND :tool_router is enabled, slim to CORE + top-K keyword matches',
+              top_k: 'optional - keyword-ranked tools to keep beyond CORE (default 10)',
+              order: 'optional - preference list forwarded only when this key is present',
+              preference: 'optional - alias of :order; same key-present rule',
+              kind: 'optional - kind value consumed by #definitions',
+              intent: 'optional - intent value consumed by #definitions',
+              core_only: 'optional - core only value consumed by #definitions'
+            )
+
+            # Run preference order and return its result
+            #{self}.preference_order(
+              order: 'optional - Array of tool names; explicit nil/[] disables',
+              preference: 'optional - alias of :order. Explicit key disables Env/DEFAULT fallback'
+            )
+
+            # Run apply preference and return its result
+            #{self}.apply_preference(
+              items: 'required - Array of Entry objects or OpenAI tool hashes',
+              order: 'optional - forwarded to preference_order only when the key is set',
+              preference: 'optional - alias of :order; same key-present rule',
+              entries: 'optional - entries value consumed by #apply_preference'
+            )
+
+            # Run rank and return its result
+            #{self}.rank(
+              query: 'required - user request text',
+              entries: 'optional - Entry pool to rank (default .all)',
+              order: 'optional - preference list forwarded to preference_order',
+              preference: 'optional - preference value consumed by #rank'
+            )
+
+            # Run discover and return its result
+            #{self}.discover(
+              force: 'optional - re-require tool files even if already discovered (default false)'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -105,16 +105,25 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              safe = PWN::AI::Agent::Result.condition(
-                content: json_string,
-                entry: PWN::AI::Agent::Registry.lookup(name: 'shell')
-              )
-              safe = PWN::AI::Agent::Result.redact(content: string)
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run condition and return its result
+            #{self}.condition(
+              content: 'required - String returned by Dispatch.call',
+              entry: 'optional - Registry::Entry (used for max_chars; nil → DEFAULT_MAX)'
+            )
+
+            # Engine-aware default: ollama keeps history inside a tight num_ctx;
+            #{self}.default_max
+
+            # Run redact and return its result
+            #{self}.redact(
+              content: 'required - String to scrub of credential-shaped substrings'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -1331,7 +1331,8 @@ module PWN
           req_toks = request.downcase.scan(/[a-z0-9_]{3,}/).uniq
           fin_toks = final.downcase.scan(/[a-z0-9_]{3,}/).uniq
           overlap  = req_toks.empty? ? 1.0 : (req_toks & fin_toks).length.to_f / req_toks.length
-          score = [score, 0.35].min if overlap < 0.08 && req_toks.length >= 4 && score > 0.35
+          long_analytical = final.length >= 800
+          score = [score, 0.35].min if overlap < 0.08 && req_toks.length >= 4 && score > 0.35 && !long_analytical
           ev_score = ev ? ev[:score].to_f : 0.0
           bad   = trace.count { |t| !semantic_ok(name: 'shell', raw: t.to_s)[:semantic_ok] }
           ratio = trace.empty? ? 0.5 : 1.0 - (bad.to_f / trace.length)
@@ -1729,37 +1730,154 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              # Tier 1 — reward signal
-              PWN::AI::Agent::Reward.judge(request: req, final: text, session_id: sid)     # R1 ORM → {score:, verdict:, rationale:}
-              PWN::AI::Agent::Reward.prm(request: req, session_id: sid)                    # R2 PRM → per-step credit
-              PWN::AI::Agent::Reward.plan_coverage(plan: tasks, final: text, session_id: sid) # soft plan-quality feature
-              PWN::AI::Agent::Reward.sentinel                                              # R3 reward-hacking detector
-              PWN::AI::Agent::Reward.reset_sentinel                                        # wipe corrupt window + distrust
-              PWN::AI::Agent::Reward.warm_sentinel                                         # P10 fill R3 window from Learning outcomes
-              PWN::AI::Agent::Reward.semantic_ok(name: 'shell', raw: json, args: args)     # R4 kills phantom exit≠0 mistakes
-
-              # Tier 5 — preference pairs → DPO
-              PWN::AI::Agent::Reward.record_preference(prompt: p, rejected: r, chosen: c, source: :user_correction)
-              PWN::AI::Agent::Reward.preferences(limit: 100)
-              PWN::AI::Agent::Reward.export_dpo(format: :dpo)                              # W1 → ~/.pwn/finetune/pwn-dpo-*.jsonl (≤40%/source, scrubbed)
-              PWN::AI::Agent::Reward.export_dpo(format: :dpo, balance: false)              # raw dump (diagnostics)
-              PWN::AI::Agent::Reward.scrub_preferences(dry_run: true)                      # P15 ledger hygiene report
-              PWN::AI::Agent::Reward.scrub_preferences                                      # P15 rewrite jsonl (backup first)
-              PWN::AI::Agent::Reward.preference_balance(scrub: true)                       # P15 geometry-aware mix
-
-              # Tier 6 — grounded reward
-              PWN::AI::Agent::Reward.verify_as_reward(final: text)                         # E3 browser-verified reward
-
-              Config (PWN::Env[:ai][:agent]):
-                :verify_as_reward   - Boolean/nil, ground finals via extro_verify (nil=auto)
-                :reward_llm         - Boolean/nil, force ORM/PRM LLM teacher (nil=on for remote engines)
-                :reward_model       - optional cheaper model id for ORM/PRM (nil=active engine default)
-                :reward_llm_timeout - seconds for cheap ORM chat (default 12, clamp 2..30)
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # R1 — LLM Outcome Reward Model
+            #{self}.judge(
+              request: 'required - original user request',
+              final: 'required - assistant final answer',
+              session_id: 'optional - PWN::Sessions id (adds tool trace)',
+              trace: 'optional - Array of tool-result strings (overrides session_id)',
+              commit: 'optional - write score into learning.jsonl / sentinel (default true)',
+              critic_pass: 'optional - critic pass value consumed by #judge',
+              predicted: 'optional - predicted value consumed by #judge',
+              proxy_ok: 'optional - proxy ok value consumed by #judge'
+            )
+
+            # Run promote to success and return its result
+            #{self}.promote_to_success?(
+              orm: 'optional - orm value consumed by #promote_to_success?',
+              verify: 'optional - verify value consumed by #promote_to_success?',
+              critic: 'optional - critic value consumed by #promote_to_success?'
+            )
+
+            # Run prm and return its result
+            #{self}.prm(
+              request: 'required - user goal',
+              session_id: 'optional - session to score in place',
+              trace: 'optional - Array of {name:, args:, result:} or Strings'
+            )
+
+            # Plan-quality soft signal (W3 feature / Learning tag)
+            #{self}.plan_coverage(
+              plan: 'required - Array of task strings or outline text',
+              final: 'required - assistant final answer',
+              request: 'optional - original user request',
+              trace: 'optional - Array of tool-result strings',
+              session_id: 'optional - load trace from session when trace empty'
+            )
+
+            # R3 — Reward-hacking sentinel
+            #{self}.sentinel
+
+            # P4 — scalar 0.0..1.0 haircut applied to Metrics success / Registry β when
+            #{self}.proxy_distrust
+
+            # Run set proxy distrust and return its result
+            #{self}.set_proxy_distrust(
+              gap: 'optional - gap value consumed by #set_proxy_distrust',
+              proxy: 'optional - scheme://proxy_host:port, or tor',
+              judge: 'optional - judge value consumed by #set_proxy_distrust'
+            )
+
+            # Run clear proxy distrust and return its result
+            #{self}.clear_proxy_distrust
+
+            # One-shot: wipe sentinel window + distrust after deploying the
+            #{self}.reset_sentinel
+
+            # P10 — backfill the R3 ring from Learning outcomes so offline/local
+            #{self}.warm_sentinel(
+              limit: 'optional - limit value consumed by #warm_sentinel'
+            )
+
+            # R4 — Structured tool-result classifier
+            #{self}.semantic_ok(
+              name: 'required - tool name',
+              raw: 'required - JSON string returned by Dispatch.call',
+              args: 'optional - the tool call arguments (used for BENIGN_EXIT)'
+            )
+
+            # 2.2 — coarse recoverable shape beside the fingerprint. Paths are
+            #{self}.recoverable_shape(
+              err: 'optional - err value consumed by #recoverable_shape',
+              stderr: 'optional - stderr value consumed by #recoverable_shape',
+              exit_code: 'optional - exit code value consumed by #recoverable_shape'
+            )
+
+            # E3 — verify-as-reward (ground truth without a human)
+            #{self}.verify_as_reward(
+              final: 'optional - final value consumed by #verify_as_reward'
+            )
+
+            # Run record preference and return its result
+            #{self}.record_preference(
+              prompt: 'required - prompt value consumed by #record_preference',
+              rejected: 'required - rejected value consumed by #record_preference',
+              chosen: 'required - chosen value consumed by #record_preference',
+              force: 'optional - force value consumed by #record_preference',
+              source: 'optional - source value consumed by #record_preference (defaults to :unknown))',
+              shape: 'optional - shape value consumed by #record_preference',
+              meta: 'optional - meta value consumed by #record_preference'
+            )
+
+            # Share of `source` among the newest WRITE_SOURCE_WINDOW prefs
+            #{self}.write_source_quota(
+              source: 'optional - source value consumed by #write_source_quota'
+            )
+
+            # P0 — online generator mix report + urgency flags. Controllers
+            #{self}.generator_mix(
+              limit: 'optional - limit value consumed by #generator_mix (defaults to WRITE_SOURCE_WINDOW)'
+            )
+
+            # P0 ops — infer trajectory shape for legacy ledger rows that predate
+            #{self}.infer_shape(
+              row: 'optional - row value consumed by #infer_shape'
+            )
+
+            # P15 — keep only usable preference pairs for balance/export/promote
+            #{self}.usable_preference?(
+              row: 'optional - row value consumed by #usable_preference?'
+            )
+
+            # P15 — one-shot ledger hygiene. Filters in place (rewrite jsonl) or
+            #{self}.scrub_preferences(
+              dry_run: 'optional - dry run value consumed by #scrub_preferences'
+            )
+
+            # P15/P5 — geometry-aware source mix. scrub:true uses usable_preference?
+            #{self}.preference_balance(
+              limit: 'optional - limit value consumed by #preference_balance (defaults to 10_000)',
+              scrub: 'optional - scrub value consumed by #preference_balance'
+            )
+
+            # Run preferences and return its result
+            #{self}.preferences(
+              limit: 'optional - limit value consumed by #preferences (defaults to 500)',
+              source: 'required - source value consumed by #preferences'
+            )
+
+            # Run export dpo and return its result
+            #{self}.export_dpo(
+              format: 'optional - format value consumed by #export_dpo (defaults to :dpo))',
+              out: 'optional - out value consumed by #export_dpo',
+              scrub: 'optional - scrub value consumed by #export_dpo',
+              balance: 'optional - balance value consumed by #export_dpo',
+              source_cap: 'optional - source cap value consumed by #export_dpo'
+            )
+
+            # Run reset and return its result
+            #{self}.reset
+
+            # Weight a judge sample for sentinel / Learning haircuts
+            #{self}.judge_sample_weight(
+              source: 'optional - source value consumed by #judge_sample_weight'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -37,12 +37,15 @@ module PWN
 
         public_class_method def self.help
           puts "USAGE:
-            ai_analysis = PWN::AI::Agent::SAST.analyze(
+            # Run analyze and return its result
+            #{self}.analyze(
               request: 'required - A string containing the source code snippet to be analyzed for SAST antipatterns and vulnerabilities.'
             )
 
+            # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "
+          constants.sort
         end
       end
     end

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

@@ -396,42 +396,78 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              # Define personas (or edit #{AGENTS_FILE} directly)
-              PWN::AI::Agent::Swarm.spawn(
-                name: 'red',
-                role: 'Offensive researcher. Propose the most likely exploit path...',
-                toolsets: %w[terminal pwn memory extrospection],
-                engine: :anthropic
-              )
-
-              # One-shot: ask a persona (creates a swarm if none given)
-              r = PWN::AI::Agent::Swarm.ask(name: 'red', request: 'Enumerate attack surface for target X')
-
-              # Antagonistic feedback loop
-              d = PWN::AI::Agent::Swarm.debate(
-                names: %w[red blue],
-                topic: 'Is CVE-2026-NNNN exploitable on target X?',
-                rounds: 3
-              )
-              puts d[:transcript].map { |t| "\#{t[:name]}: \#{t[:reply][0,200]}" }
-
-              # Fan-out
-              PWN::AI::Agent::Swarm.broadcast(request: 'Summarise findings so far')
-
-              # Inspect / resume cross-session
-              PWN::AI::Agent::Swarm.list
-              PWN::AI::Agent::Swarm.bus_tail(swarm_id: d[:swarm_id], limit: 50)
-
-              Config:
-                PWN::Env[:ai][:agent][:max_depth]  # recursion cap  (default #{DEFAULT_DEPTH})
-                persona[:max_iters]                # per-turn iteration cap (default #{DEFAULT_ITERS})
-                persona[:toolsets]                 # Registry toolset allow-list; omit 'swarm'
-                                                   # to prevent that persona spawning sub-agents.
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Persona registry (~/.pwn/agents.yml)
+            #{self}.personas
+
+            # Run spawn and return its result
+            #{self}.spawn(
+              name: 'required - persona name (snake_case)',
+              role: 'required - system_role_content overlay for this persona',
+              toolsets: 'optional - Array of Registry toolset names',
+              engine: 'optional - :openai / :anthropic / :grok / :gemini / :ollama / :openwebui',
+              max_iters: 'optional - per-turn iteration cap for this persona'
+            )
+
+            # Run retire and return its result
+            #{self}.retire(
+              name: 'optional - binary or identifier name'
+            )
+
+            # Swarm lifecycle & bus
+            #{self}.create(
+              topic: 'optional - topic value consumed by #create'
+            )
+
+            # Run list and return its result
+            #{self}.list
+
+            # Run bus append and return its result
+            #{self}.bus_append(
+              swarm_id: 'required - required, from: required, content: required',
+              to: 'optional - optional (default :all)',
+              from: 'optional - sender account or address to bind as operator',
+              content: 'optional - content value consumed by #bus_append'
+            )
+
+            # Run bus tail and return its result
+            #{self}.bus_tail(
+              swarm_id: 'optional - swarm id value consumed by #bus_tail',
+              limit: 'optional - limit value consumed by #bus_tail'
+            )
+
+            # Core: run a single persona turn under Loop.run
+            #{self}.ask(
+              name: 'required - persona name from ~/.pwn/agents.yml',
+              request: 'required - what to ask/instruct the persona',
+              swarm_id: 'optional - join an existing swarm (created if omitted)',
+              to: 'optional - addressee recorded on the bus (default :all)',
+              on_tool: 'optional - ->(name, args, result) live-UI callback',
+              from: 'optional - sender account or address to bind as operator (defaults to caller_label)',
+              text_only: 'required - text only value consumed by #ask'
+            )
+
+            # Run debate and return its result
+            #{self}.debate(
+              names: 'required - Array of persona names, order = speaking order',
+              topic: 'required - opening question / claim',
+              rounds: 'optional - full passes over names (default 2)',
+              swarm_id: 'optional - join an existing swarm',
+              on_tool: 'optional - ->(name, args, result) live-UI callback'
+            )
+
+            # Run broadcast and return its result
+            #{self}.broadcast(
+              request: 'required - required, names: optional - default all personas',
+              swarm_id: 'optional - swarm id value consumed by #broadcast',
+              names: 'required - Array names value consumed by #broadcast',
+              on_tool: 'optional - on tool value consumed by #broadcast'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end