pwn 0.5.707 → 0.5.709

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

@@ -177,7 +177,16 @@ module PWN
             v[:confidence] = [v[:confidence].to_f, ground[:confidence].to_f].max if ground[:confidence]
           end
 
-          v[:success] = v[:score] >= 0.6
+          v[:success] = promote_to_success?(
+            orm: v[:source].to_s != 'heuristic' && v[:score].to_f >= 0.6,
+            verify: if ground.nil?
+                      nil
+                    else
+                      ground[:verdict] == :confirmed
+                    end,
+            critic: opts.key?(:critic_pass) ? opts[:critic_pass] : nil
+          )
+          v[:needs_spot_check] = v[:success] && v[:score].to_f >= 0.85 && (rand < 0.05)
           v[:engine] = eng
           # W3 — write Brier on every judged turn so overconfidence can
           # throttle max_iters/critic even when plan_first never fired.
@@ -195,9 +204,16 @@ module PWN
           { score: 0.5, verdict: :unknown, rationale: "judge error: #{e.class}", success: !final.strip.empty?, error: e.message, confidence: 0.2, source: :error }
         end
 
-        # ----------------------------------------------------------------
-        # R2 — Process Reward Model (per-step credit assignment)
-        # ----------------------------------------------------------------
+        public_class_method def self.promote_to_success?(opts = {})
+          flags = []
+          flags << (opts[:orm] ? true : false) unless opts[:orm].nil?
+          flags << (opts[:verify] ? true : false) unless opts[:verify].nil?
+          flags << (opts[:critic] ? true : false) unless opts[:critic].nil?
+          return false if flags.empty?
+          return flags.first if flags.length == 1
+
+          flags.count(true) >= 2
+        end
 
         # Supported Method Parameters::
         # steps = PWN::AI::Agent::Reward.prm(
@@ -1315,12 +1331,16 @@ 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)
           score = ((score * 0.85) + (ratio * 0.15)).round(3)
-          score = score.round(2).clamp(0.0, 0.9)
+          score = [score, 0.45].min if overlap >= 0.4 && ev_score < 0.55
+          score = [score, 0.45].min if ratio <= 0.15
+          score = [score, 0.70].min
+          score = score.round(2).clamp(0.0, 0.70)
           verdict = if score >= 0.6 then :solved
                     elsif score >= 0.3 then :partial
                     else :wrong
@@ -1710,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

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

@@ -1808,42 +1808,171 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              state = PWN::AI::Agent::TaskSummarizer.fresh(request: 'ship task briefs to execs')
-              plan = PWN::AI::Agent::TaskSummarizer.plan(request: state[:request], state: state)
-              text = PWN::AI::Agent::TaskSummarizer.emit_plan!(state: state)
-              # → "Goal: ...\nTangible tasks (N) — each may use many tools:\n  task 1/N: ...\n  task 2/N: ..."
-              # UI: on_tool.call('task', text, '')  # full text, no truncation
-              # One task brief for a whole tool collection (one-to-many):
-              pre = PWN::AI::Agent::TaskSummarizer.about_to(
-                tools: [{ name: 'shell' }, { name: 'pwn_eval' }],
-                state: state
-              )
-              # → "task k/N: <english> — via shell, pwn_eval (search+eval-ruby)"
-              ctx = PWN::AI::Agent::TaskSummarizer.plan_context(state: state)
-              focus = PWN::AI::Agent::TaskSummarizer.active_task_prompt(state: state)
-              # then real tools print on their own lines; record! stays silent by default
-              PWN::AI::Agent::TaskSummarizer.record!(
-                state: state,
-                name: 'shell',
-                args: 'ls',
-                result: '{success:true}'
-              )
-              line = PWN::AI::Agent::TaskSummarizer.flush!(state: state)  # optional closing brief
-              PWN::AI::Agent::TaskSummarizer.enabled?
-              PWN::AI::Agent::TaskSummarizer.verbose?
-              PWN::AI::Agent::TaskSummarizer.llm_plan_enabled?
-              PWN::AI::Agent::TaskSummarizer.unify_plan!(state: state, outline: plan_text)
-              PWN::AI::Agent::TaskSummarizer.tool_jargon_task?(item: '`shell`')
-              PWN::AI::Agent::TaskSummarizer.relevance_query(state: state, request: state[:request])
-              PWN::AI::Agent::TaskSummarizer.apply_prm_advancement!(state: state, rewards: [1, 1], intents: ['search'])
-              PWN::AI::Agent::TaskSummarizer.parse_outline_tasks(outline: plan_text)
-              PWN::AI::Agent::TaskSummarizer.every_n
-              PWN::AI::Agent::TaskSummarizer.interval_s
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run enabled and return its result
+            #{self}.enabled?
+
+            # Run verbose and return its result
+            #{self}.verbose?
+
+            # LLM plan generation is on by default. Set
+            #{self}.llm_plan_enabled?
+
+            # Run every n and return its result
+            #{self}.every_n
+
+            # Run interval s and return its result
+            #{self}.interval_s
+
+            # Per-run state (also safe for nested/swarm if callers keep their own hash)
+            #{self}.fresh(
+              request: 'optional - original user goal string'
+            )
+
+            # Every request gets a task compass. There is no request type
+            #{self}.needs_task_breakdown?
+
+            # Request → ordered tangible tasks (each may map to many tools)
+            #{self}.plan(
+              request: 'required - user goal string',
+              state: 'optional - fresh() hash to mutate',
+              tasks: 'optional - Array injected plan array (tests)',
+              llm_tasks: 'optional - injected LLM task array (tests)'
+            )
+
+            # Format the full plan as the task-summary body (shown in entirety)
+            #{self}.format_plan(
+              tasks: 'required - Array of task strings',
+              request: 'optional - goal string'
+            )
+
+            # Run emit plan and return its result
+            #{self}.emit_plan!(
+              state: 'required - state value consumed by #emit_plan!',
+              request: 'required - request value consumed by #emit_plan!'
+            )
+
+            # Prefer Reflect when module_reflection is on (teacher engine / gated)
+            #{self}.chat_for_plan(
+              request: 'required - user goal to decompose'
+            )
+
+            # Parse JSON array, fenced JSON, or numbered/bulleted plain text
+            #{self}.parse_llm_tasks(
+              raw: 'required - raw LLM response text'
+            )
+
+            # Thin offline fallback when the LLM is disabled or unavailable
+            #{self}.fallback_decompose(
+              goal: 'required - user goal string'
+            )
+
+            # Back-compat alias used by older call sites / specs
+            #{self}.heuristic_decompose(
+              goal: 'required - user goal string'
+            )
+
+            # High-level brief for a collection of impending tool calls
+            #{self}.about_to(
+              tools: 'optional - array of {name:, args:} or bare names',
+              name: 'optional - single tool name (legacy one-tool path)',
+              args: 'optional - single tool args (ignored for brief content)',
+              request: 'optional - goal text',
+              state: 'optional - fresh() hash'
+            )
+
+            # Active plain-English plan item (and index/n) for Loop / model steering
+            #{self}.active_task(
+              state: 'required - fresh() hash',
+              messages: 'optional - messages value consumed by #active_task'
+            )
+
+            # Remaining English work units that lack tool-result evidence
+            #{self}.unfinished_tasks(
+              state: 'required - fresh() hash',
+              messages: 'optional - Loop message array for extra coverage'
+            )
+
+            # True while a multi-step English plan still has uncovered work
+            #{self}.plan_open?(
+              state: 'required - fresh() hash',
+              messages: 'optional - Loop message array'
+            )
+
+            # Short block for engine messages: full plan + focus on active English task
+            #{self}.plan_context(
+              state: 'required - fresh() hash'
+            )
+
+            # Build a Registry/tool-router relevance string from English tasks
+            #{self}.relevance_query(
+              state: 'optional - fresh() hash',
+              request: 'optional - original user goal fallback'
+            )
+
+            # Inject / refresh the active-task focus into Loop messages when plan_idx changes
+            #{self}.active_task_prompt(
+              state: 'required - fresh() hash',
+              force: 'optional - Boolean re-emit even if idx unchanged',
+              messages: 'optional - messages value consumed by #active_task_prompt',
+              request: 'optional - request value consumed by #active_task_prompt'
+            )
+
+            # Pull the operators original ask out of curriculum / critic / GOAL+PLAN
+            #{self}.canonical_request(
+              request: 'required - raw user or wrapper string'
+            )
+
+            # True when a candidate plan item is tool jargon (e.g. `shell`,
+            #{self}.tool_jargon_task?(
+              item: 'required - candidate task string'
+            )
+
+            # Parse a plan_first / red_team surviving outline into tangible tasks
+            #{self}.parse_outline_tasks(
+              outline: 'required - free-text plan outline'
+            )
+
+            # After S4 red_team / plan_first: optionally rewrite ts_state[:plan]
+            #{self}.unify_plan!(
+              state: 'required - fresh() hash',
+              outline: 'required - plan_first text and/or red_team hint',
+              source: 'optional - :plan_first|:red_team|:merged (default :merged)'
+            )
+
+            # Advance or hold plan_idx from an R2 step batch
+            #{self}.apply_prm_advancement!(
+              state: 'required - fresh() hash',
+              rewards: 'required - Array of -1|0|1 (batch order)',
+              intents: 'optional - Array of intent verb strings for the batch',
+              names: 'optional - Array tool names in the batch',
+              result: 'optional - latest tool result string',
+              mistake: 'optional - truthy when a mistake fingerprint hit this batch'
+            )
+
+            # Record a completed tool. Does NOT emit task lines with results
+            #{self}.record!(
+              state: 'required - fresh() hash',
+              name: 'required - tool name',
+              args: 'optional - tool args',
+              result: 'optional - tool result string'
+            )
+
+            # Optional progress / done line (verbose or flush). Still plain English;
+            #{self}.emit!(
+              state: 'required - fresh() hash',
+              final: 'optional - Boolean closing brief (default: false)'
+            )
+
+            # Run flush and return its result
+            #{self}.flush!(
+              state: 'required - fresh() hash'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end