pwn 0.5.708 → 0.5.710

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

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

@@ -357,12 +357,111 @@ module PWN
         end
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              PWN::AI::Agent::ToolGuard.placeholder?(text: '...')
-              PWN::AI::Agent::ToolGuard.coerce_args(args: { value: 'id' }, required: %w[command])
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run present and return its result
+            #{self}.present?(
+              value: 'required - integer or string to pack/encode'
+            )
+
+            # Run placeholder and return its result
+            #{self}.placeholder?(
+              text: 'optional - text value consumed by #placeholder?'
+            )
+
+            # Run bashism and return its result
+            #{self}.bashism?(
+              text: 'optional - text value consumed by #bashism?'
+            )
+
+            # Run shell bash and return its result
+            #{self}.shell_bash?
+
+            # Run shell name and return its result
+            #{self}.shell_name
+
+            # Run protect http and return its result
+            #{self}.protect_http!
+
+            # Run protect core constants and return its result
+            #{self}.protect_core_constants!
+
+            # Coerce common wrong keys onto the first required schema field
+            #{self}.coerce_args(
+              args: 'optional - args value consumed by #coerce_args',
+              required: 'optional - Array required value consumed by #coerce_args'
+            )
+
+            # Run invalid payload and return its result
+            #{self}.invalid_payload(
+              hint: 'optional - hint value consumed by #invalid_payload',
+              shell: 'optional - shell value consumed by #invalid_payload (defaults to shell_name)'
+            )
+
+            # Run host load and return its result
+            #{self}.host_load
+
+            # Conservative wall-clock seconds for shell / pwn_eval
+            #{self}.deadline_s(
+              kind: 'optional - kind value consumed by #deadline_s',
+              timeout: 'optional - seconds to wait before giving up (defaults to opts[:timeout_s])',
+              timeout_s: 'optional - timeout s value consumed by #deadline_s'
+            )
+
+            # Run reset timeout budget and return its result
+            #{self}.reset_timeout_budget
+
+            # Run reset timeout budget and return its result
+            #{self}.reset_timeout_budget!
+
+            # Run mutation count and return its result
+            #{self}.mutation_count
+
+            # Run payload spent and return its result
+            #{self}.payload_spent
+
+            # Run note timeout and return its result
+            #{self}.note_timeout!(
+              timeout: 'optional - seconds to wait before giving up'
+            )
+
+            # Run next timeout and return its result
+            #{self}.next_timeout(
+              timeout: 'optional - seconds to wait before giving up',
+              spent: 'optional - spent value consumed by #next_timeout'
+            )
+
+            # Timeout policy (loop-law, not a skill):
+            #{self}.timeout_lesson(
+              tool: 'required - tool value consumed by #timeout_lesson',
+              timeout: 'required - seconds to wait before giving up'
+            )
+
+            # Run timeout result and return its result
+            #{self}.timeout_result(
+              timeout: 'required - seconds to wait before giving up',
+              tool: 'optional - tool value consumed by #timeout_result',
+              payload: 'optional - payload value consumed by #timeout_result',
+              task: 'optional - task value consumed by #timeout_result',
+              stdout: 'optional - stdout value consumed by #timeout_result',
+              stderr: 'optional - stderr value consumed by #timeout_result',
+              shell: 'required - shell value consumed by #timeout_result (defaults to shell_name)'
+            )
+
+            # Run timeout prior count and return its result
+            #{self}.timeout_prior_count(
+              tool: 'optional - tool value consumed by #timeout_prior_count'
+            )
+
+            # Run refuse copied persist and return its result
+            #{self}.refuse_copied_persist?(
+              name: 'optional - binary or identifier name',
+              args: 'optional - args value consumed by #refuse_copied_persist?'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -31,7 +31,14 @@ PWN::AI::Agent::Registry.register(
       limit: args[:limit] || 12,
       exclude_session_id: exclude,
       include_current: args[:include_current] == true
-    )
+    ).tap do |hits|
+      sid = exclude.to_s
+      next if sid.empty? || !defined?(PWN::Plugins::ArtifactRegistry)
+
+      artifacts = PWN::Plugins::ArtifactRegistry.list(session_id: sid)
+      hits[:artifacts] = artifacts if hits.is_a?(Hash)
+      hits << { artifacts: artifacts } if hits.is_a?(Array) && artifacts.any?
+    end
   }
 )
 

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

@@ -41,13 +41,16 @@ module PWN
 
         public_class_method def self.help
           puts "USAGE:
-            ai_analysis = PWN::AI::Agent::TransparentBrowser.analyze(
+            # Run analyze and return its result
+            #{self}.analyze(
               request: 'required - current step in the JavaScript debugging session to analyze',
               source_to_review: 'required - the block of JavaScript code in which the current step resides'
             )
 
+            # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "
+          constants.sort
         end
       end
     end

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

@@ -180,27 +180,47 @@ module PWN
         end
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              # Called from Learning.auto_introspect when Loop.run is on the
-              # stack. You almost never invoke this directly.
-              PWN::AI::Agent::TurnFinalizer.defer(
-                session_id: sid,
-                request: req,
-                final: text,
-                plan: plan,
-                ts_state: ts
-              )
-
-              # Specs / cron that need the learner to finish before assert:
-              PWN::AI::Agent::TurnFinalizer.join_all!(timeout: 15)
-
-              Toggle via PWN::Env[:ai][:agent][:defer_introspect]
-                true  (default) — Hermes split: learn after the reply
-                false           — legacy inline auto_introspect
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run enter user path and return its result
+            #{self}.enter_user_path!
+
+            # Run leave user path and return its result
+            #{self}.leave_user_path!
+
+            # Run user path and return its result
+            #{self}.user_path?
+
+            # Run should defer and return its result
+            #{self}.should_defer?
+
+            # Run defer and return its result
+            #{self}.defer(
+              session_id: 'required - PWN::Sessions id',
+              request: 'optional - original user request',
+              final: 'optional - user-visible final answer',
+              predicted: 'optional - W3 predicted score',
+              plan: 'optional - tangible-task plan',
+              ts_state: 'optional - TaskSummarizer state'
+            )
+
+            # Run finalize and return its result
+            #{self}.finalize(
+              session_id: 'optional - request:, final:, predicted:, plan:, ts_state:',
+              should: 'optional - should value consumed by #finalize'
+            )
+
+            # Run join all and return its result
+            #{self}.join_all!(
+              timeout: 'optional - seconds to wait before giving up'
+            )
+
+            # Run pending and return its result
+            #{self}.pending
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
 
         private_class_method def self.track(opts = {})

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

@@ -89,14 +89,17 @@ module PWN
 
         public_class_method def self.help
           puts "USAGE:
-            ai_analysis = #{self}.analyze(
-              request: 'required - high level description of vulnerability discovered (e.g. \"Discovered a SQLi vulnerability in /login\"',
+            # Run analyze and return its result
+            #{self}.analyze(
+              request: 'required - high level description of vulnerability discovered (e.g. Discovered a SQLi vulnerability in /login',
               markup_type: 'optional - specify the type of markup to generate :jira|:markdown|:html|:confluence|:xml (default: :jira)',
-              output_path: 'optional - full path to save the generated report as .md (e.g. /home/claw/reports/sqli-finding.md)'
+              output_path: 'optional - path to save the generated markdown report'
             )
 
+            # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "
+          constants.sort
         end
       end
     end

data/lib/pwn/ai/agent.rb

@@ -47,6 +47,10 @@ module PWN
       end
 
       public_class_method def self.help
+        puts "USAGE:
+          # Display a List of Every PWN::AI Module
+          #{self}.authors
+        "
         constants.sort
       end
     end