pwn 0.5.708 → 0.5.709

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

@@ -651,29 +651,139 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              PWN::AI::Agent::Metrics.record(name: 'shell', success: true, duration: 0.42, engine: :ollama)
-              PWN::AI::Agent::Metrics.summary(limit: 10, engine: :ollama)
-              PWN::AI::Agent::Metrics.to_context(limit: 8, engine: :ollama)   # injected by PromptBuilder
-              PWN::AI::Agent::Metrics.ucb(name: 'shell')                 # C1 exploration bonus
-              PWN::AI::Agent::Metrics.thompson(name: 'shell')            # C1 Beta(ok+1,fail+1) sample
-              PWN::AI::Agent::Metrics.advantage(name: 'shell')           # C1 local − global (P20 judge-blended)
-              PWN::AI::Agent::Metrics.record_judge(name: 'shell', score: 0.8) # P20 ORM→metrics
-              PWN::AI::Agent::Metrics.judge_rate(name: 'shell')         # P20 mean ORM
-              PWN::AI::Agent::Metrics.effective_rate(name: 'shell')     # P20 proxy⋈judge
-              PWN::AI::Agent::Metrics.changepoints(within_secs: 3600)    # E1 CUSUM regime changes
-              PWN::AI::Agent::Metrics.record_calibration(predicted: 0.8, actual: 1.0, brier: 0.04, engine: :ollama)
-              PWN::AI::Agent::Metrics.calibration(engine: :ollama)       # W3 Brier / overconfidence
-              PWN::AI::Agent::Metrics.scale_prediction(predicted: 0.87) # temperature-scale before Policy/UI
-              PWN::AI::Agent::Metrics.scoreboard                        # tool_ok vs task_ok vs judge_ok
-              PWN::AI::Agent::Metrics.health_line
-              PWN::AI::Agent::Metrics.reset
-              PWN::AI::Agent::Metrics.load
-              PWN::AI::Agent::Metrics.save(metrics: hash)
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run load and return its result
+            #{self}.load
+
+            # Run save and return its result
+            #{self}.save(
+              metrics: 'required - Hash returned by .load / mutated in place'
+            )
+
+            # Run record and return its result
+            #{self}.record(
+              name: 'required - tool name that was dispatched',
+              success: 'required - Boolean, did the handler complete without error',
+              duration: 'optional - Float seconds the dispatch took',
+              error: 'optional - String error message when success is false',
+              engine: 'optional - Symbol/String AI engine that chose this tool (segments telemetry)'
+            )
+
+            # Run summary and return its result
+            #{self}.summary(
+              limit: 'optional - cap number of tools returned (default 25)',
+              engine: 'optional - only that engine\\s sub-bucket (falls back to global when absent)'
+            )
+
+            # Run to context and return its result
+            #{self}.to_context(
+              limit: 'optional - cap number of tools included (default 8)',
+              engine: 'optional - restrict to one engine\\s telemetry'
+            )
+
+            # P4 helper — Registry.rank calls this so β·advantage is scaled down
+            #{self}.proxy_trust
+
+            # Run ucb and return its result
+            #{self}.ucb(
+              name: 'optional - binary or identifier name',
+              c: 'optional - c value consumed by #ucb'
+            )
+
+            # Run thompson and return its result
+            #{self}.thompson(
+              name: 'optional - binary or identifier name'
+            )
+
+            # Run advantage and return its result
+            #{self}.advantage(
+              name: 'optional - binary or identifier name'
+            )
+
+            # Run prm advantage and return its result
+            #{self}.prm_advantage(
+              name: 'optional - binary or identifier name'
+            )
+
+            # Run prm n and return its result
+            #{self}.prm_n(
+              name: 'optional - binary or identifier name'
+            )
+
+            # P18 — called by Reward.prm after session annotate so live routing
+            #{self}.record_step_reward(
+              name: 'required - binary or identifier name',
+              reward: 'optional - reward value consumed by #record_step_reward'
+            )
+
+            # P20 — fold ORM judge (0..1) into per-tool telemetry so UCB /
+            #{self}.record_judge(
+              name: 'required - binary or identifier name',
+              score: 'optional - score value consumed by #record_judge',
+              confidence: 'optional - confidence value consumed by #record_judge',
+              source: 'optional - source value consumed by #record_judge'
+            )
+
+            # P1 — mean judge confidence for a tool (nil when no samples)
+            #{self}.judge_confidence(
+              name: 'optional - binary or identifier name'
+            )
+
+            # Mean judge score for a tool (nil when no ORM samples yet)
+            #{self}.judge_rate(
+              name: 'optional - binary or identifier name'
+            )
+
+            # Blended success rate: when proxy_distrust > 0 and judge samples
+            #{self}.effective_rate(
+              name: 'optional - binary or identifier name'
+            )
+
+            # Run changepoints and return its result
+            #{self}.changepoints(
+              cause: 'optional - :env_drift and does NOT count toward [REPEATING].',
+              within_secs: 'optional - within secs value consumed by #changepoints'
+            )
+
+            # W3 — plan_first emits p(success); Loop.run calls this with the
+            #{self}.record_calibration(
+              engine: 'optional - engine value consumed by #record_calibration (defaults to :global))',
+              brier: 'optional - brier value consumed by #record_calibration',
+              predicted: 'optional - predicted value consumed by #record_calibration',
+              actual: 'optional - actual value consumed by #record_calibration'
+            )
+
+            # Run calibration and return its result
+            #{self}.calibration(
+              engine: 'required - engine value consumed by #calibration'
+            )
+
+            # Run calibration green and return its result
+            #{self}.calibration_green?(
+              engine: 'optional - engine value consumed by #calibration_green?'
+            )
+
+            # Run scale prediction and return its result
+            #{self}.scale_prediction(
+              predicted: 'optional - predicted value consumed by #scale_prediction',
+              engine: 'optional - engine value consumed by #scale_prediction'
+            )
+
+            # Run scoreboard and return its result
+            #{self}.scoreboard(
+              engine: 'optional - engine value consumed by #scoreboard'
+            )
+
+            # Run health line and return its result
+            #{self}.health_line
+
+            # 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/mistakes.rb

@@ -843,23 +843,132 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              PWN::AI::Agent::Mistakes.record(tool: 'shell', error: 'nmpa: command not found', args: '{"command":"nmpa -sV"}')
-              PWN::AI::Agent::Mistakes.top(limit: 10, unresolved_only: true)
-              PWN::AI::Agent::Mistakes.find(signature: 'abc123def456')
-              PWN::AI::Agent::Mistakes.for_tool(tool: 'shell')
-              PWN::AI::Agent::Mistakes.resolve(signature: 'abc123def456', fix: 'binary is spelled `nmap`, not `nmpa`')
-              PWN::AI::Agent::Mistakes.correction_hint(tool: 'shell', error: err)  # inline self-correct
-              PWN::AI::Agent::Mistakes.to_context(limit: 6)                        # injected by PromptBuilder
-              PWN::AI::Agent::Mistakes.correction?(request: "no that's wrong")
-              PWN::AI::Agent::Mistakes.check_user_correction(request: req, session_id: sid)
-              PWN::AI::Agent::Mistakes.signature(tool: 'shell', error: err)
-              PWN::AI::Agent::Mistakes.operator_inbox(limit: 12)
-              PWN::AI::Agent::Mistakes.reset
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run load and return its result
+            #{self}.load
+
+            # Run save and return its result
+            #{self}.save(
+              store: 'optional - store value consumed by #save'
+            )
+
+            # Run signature and return its result
+            #{self}.signature(
+              tool: 'required - tool/component name that failed',
+              error: 'required - raw error text (will be normalised)'
+            )
+
+            # Run find and return its result
+            #{self}.find(
+              signature: 'optional - exact signature to fetch',
+              tool: 'optional - with error:, compute signature and fetch',
+              error: 'optional - raw error text (used with tool:)'
+            )
+
+            # Run for tool and return its result
+            #{self}.for_tool(
+              tool: 'required - tool name',
+              unresolved_only: 'optional - default false'
+            )
+
+            # Run record and return its result
+            #{self}.record(
+              tool: 'required - tool/component that produced the failure',
+              error: 'required - error text / message',
+              args: 'optional - args that triggered it (stored truncated as sample)',
+              session_id: 'optional - PWN::Sessions id',
+              source: 'optional - :tool | :user_correction | :loop | :model | :heuristic (default :tool)',
+              force: 'optional - force value consumed by #record',
+              meta: 'optional - meta value consumed by #record',
+              cause: 'optional - cause value consumed by #record (defaults to :self))',
+              shape: 'optional - shape value consumed by #record',
+              needs_code_change: 'optional - needs code change value consumed by #record'
+            )
+
+            # Run resolve and return its result
+            #{self}.resolve(
+              signature: 'required - mistake signature (from mistakes_list / .top)',
+              fix: 'required - what to do INSTEAD next time',
+              structured: 'optional - structured value consumed by #resolve',
+              clear_needs_code_change: 'optional - clear needs code change value consumed by #resolve'
+            )
+
+            # Run top and return its result
+            #{self}.top(
+              limit: 'optional - max rows (default 10)',
+              unresolved_only: 'optional - default true',
+              practiceable_only: 'optional - practiceable only value consumed by #top'
+            )
+
+            # Run extinguish and return its result
+            #{self}.extinguish!(
+              signature: 'optional - signature value consumed by #extinguish!',
+              shape: 'optional - shape value consumed by #extinguish!',
+              force: 'optional - force value consumed by #extinguish!'
+            )
+
+            # Auto-resolve parked items that already have a known extinguish recipe
+            #{self}.extinguish_parked!(
+              limit: 'optional - limit value consumed by #extinguish_parked!',
+              dry_run: 'optional - dry run value consumed by #extinguish_parked!'
+            )
+
+            # Run park and return its result
+            #{self}.park(
+              signature: 'required - signature value consumed by #park',
+              reason: 'optional - reason value consumed by #park'
+            )
+
+            # Operator inbox: parked / needs_code_change / needs_human scars that
+            #{self}.operator_inbox(
+              limit: 'optional - limit value consumed by #operator_inbox'
+            )
+
+            # Run to context and return its result
+            #{self}.to_context(
+              limit: 'optional - limit value consumed by #to_context (defaults to 6)',
+              request: 'optional - request value consumed by #to_context',
+              include_open: 'optional - include open value consumed by #to_context',
+              full: 'optional - full value consumed by #to_context'
+            )
+
+            # Run correction hint and return its result
+            #{self}.correction_hint(
+              tool: 'required - tool that just failed',
+              error: 'required - raw error it failed with'
+            )
+
+            # Run correction and return its result
+            #{self}.correction?(
+              request: 'optional - request value consumed by #correction?'
+            )
+
+            # Run check user correction and return its result
+            #{self}.check_user_correction(
+              request: 'required - the incoming user message',
+              session_id: 'optional - session to inspect for the previous answer'
+            )
+
+            # Run lean and return its result
+            #{self}.lean!(
+              dry_run: 'optional - Boolean (default false)',
+              max_resolved_kept: 'optional - cap on resolved-with-fix records',
+              resolved_min_age_days: 'optional - age before resolved count=1 may drop'
+            )
+
+            # Run reset and return its result
+            #{self}.reset
+
+            # Age-weighted count for [REPEATING] threshold — a ×8 signature from
+            #{self}.effective_count(
+              mistake: 'optional - mistake value consumed by #effective_count',
+              signature: 'optional - signature value consumed by #effective_count'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -67,15 +67,31 @@ module PWN
         end
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              PWN::AI::Agent::OpenGoal.begin!(request: '...', session_id: '...')
-              PWN::AI::Agent::OpenGoal.current
-              PWN::AI::Agent::OpenGoal.resume?(request: 'continue')
-              PWN::AI::Agent::OpenGoal.clear!
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run goal file and return its result
+            #{self}.goal_file
+
+            # Run current and return its result
+            #{self}.current
+
+            # Run begin and return its result
+            #{self}.begin!(
+              request: 'required - request value consumed by #begin!',
+              session_id: 'optional - session id value consumed by #begin!'
+            )
+
+            # Run clear and return its result
+            #{self}.clear!
+
+            # Run resume and return its result
+            #{self}.resume?(
+              request: 'optional - request value consumed by #resume?'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -665,24 +665,164 @@ module PWN
         end
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              PWN::AI::Agent::Policy.begin_episode(session_id:, request:, kind:, engine:)
-              PWN::AI::Agent::Policy.observe_step(action: 'shell', ok: true, duration: 0.2)
-              PWN::AI::Agent::Policy.finish(session_id:, score: 0.8, verdict: :solved)
-              PWN::AI::Agent::Policy.q(state:, action:)
-              PWN::AI::Agent::Policy.advantage(state:, action:)   # Registry.rank term
-              PWN::AI::Agent::Policy.recommend(actions: %w[shell pwn_eval])
-              PWN::AI::Agent::Policy.evaluate(limit: 100)
-              PWN::AI::Agent::Policy.stats
-              PWN::AI::Agent::Policy.episode_budget_met?
-              PWN::AI::Agent::Policy.to_context
-              PWN::AI::Agent::Policy.lean!(dry_run: true)
-              PWN::AI::Agent::Policy.warmup!(limit: 200)
-              PWN::AI::Agent::Policy.reset
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Feature → discrete state
+            #{self}.state(
+              kind: 'optional - statement|question|autonomous_goal|…',
+              request: 'optional - user text / active English task',
+              last_action: 'optional - previous tool name',
+              fails: 'optional - in-turn failure count',
+              engine: 'optional - active engine',
+              request_kind: 'optional - request kind value consumed by #state',
+              task: 'optional - task value consumed by #state',
+              ts_state: 'optional - ts state value consumed by #state',
+              final: 'optional - final value consumed by #state',
+              score: 'optional - score value consumed by #state',
+              last: 'optional - last value consumed by #state',
+              fail_n: 'optional - fail n value consumed by #state'
+            )
+
+            # Run cold and return its result
+            #{self}.cold?
+
+            # Run warm and return its result
+            #{self}.warm?
+
+            # True once live returns, warmup-replayed trajectories, or a
+            #{self}.episode_budget_met?
+
+            # Episode / environment loop
+            #{self}.begin_episode(
+              session_id: 'optional - PWN::Sessions id (defaults to ep_)',
+              request: 'optional - user request',
+              kind: 'optional - request kind',
+              intent: 'optional - Loop.request_intent',
+              engine: 'optional - active engine',
+              ts_state: 'optional - TaskSummarizer state hash'
+            )
+
+            # Run observe step and return its result
+            #{self}.observe_step(
+              session_id: 'optional - must match begin_episode when set',
+              action: 'required - tool name',
+              ok: 'required - Boolean, Reward.semantic_ok',
+              duration: 'optional - Float seconds',
+              ts_state: 'optional - TaskSummarizer state',
+              request: 'optional - used if episode was not begun',
+              kind: 'optional - kind value consumed by #observe_step',
+              engine: 'optional - engine value consumed by #observe_step'
+            )
+
+            # Run finish and return its result
+            #{self}.finish(
+              session_id: 'optional - active episode id',
+              score: 'optional - Reward.judge 0..1 (training target)',
+              verdict: 'optional - solved|partial|wrong|refused',
+              proxy_ok: 'optional - Boolean fallback when no judge score',
+              ts_state: 'optional - ts state value consumed by #finish',
+              final: 'optional - final value consumed by #finish',
+              confidence: 'optional - confidence value consumed by #finish'
+            )
+
+            # Value-based update (Q-learning) + policy-gradient (REINFORCE)
+            #{self}.update_q!(
+              transition: 'required - Hash with :state :action :reward :next_state :terminal (defaults to opts)'
+            )
+
+            # Run update pg and return its result
+            #{self}.update_pg!(
+              state: 'required - state value consumed by #update_pg!',
+              action: 'required - action value consumed by #update_pg!',
+              advantage: 'required - scalar G_t − V(s)'
+            )
+
+            # Run q and return its result
+            #{self}.q(
+              state: 'optional - state value consumed by #q',
+              action: 'optional - action value consumed by #q'
+            )
+
+            # Run value and return its result
+            #{self}.value(
+              state: 'optional - state value consumed by #value'
+            )
+
+            # Q(s,a) − V(s). Unknown / cold-start pairs return 0 so rank is unchanged
+            #{self}.advantage(
+              state: 'optional - state value consumed by #advantage (defaults to current_state)',
+              action: 'optional - action value consumed by #advantage'
+            )
+
+            # Run recommend and return its result
+            #{self}.recommend(
+              state: 'optional - default current episode state',
+              actions: 'required - Array of tool names',
+              epsilon: 'optional - explore probability (default EPSILON)'
+            )
+
+            # Run current state and return its result
+            #{self}.current_state
+
+            # Run current episode and return its result
+            #{self}.current_episode
+
+            # Hermes split: snapshot + clear the live episode so Loop.maybe_finish_policy
+            #{self}.detach_episode!
+
+            # Run attach episode and return its result
+            #{self}.attach_episode!(
+              episode: 'optional - episode value consumed by #attach_episode!'
+            )
+
+            # Persistence / eval
+            #{self}.load
+
+            # Run save and return its result
+            #{self}.save(
+              table: 'optional - table value consumed by #save (defaults to load)'
+            )
+
+            # Run trajectories and return its result
+            #{self}.trajectories(
+              limit: 'optional - limit value consumed by #trajectories'
+            )
+
+            # Run stats and return its result
+            #{self}.stats
+
+            # Replay stored trajectories under the current Q table
+            #{self}.evaluate(
+              limit: 'optional - limit value consumed by #evaluate'
+            )
+
+            # Run to context and return its result
+            #{self}.to_context(
+              limit: 'optional - limit value consumed by #to_context'
+            )
+
+            # Run lean and return its result
+            #{self}.lean!(
+              dry_run: 'optional - dry run value consumed by #lean!'
+            )
+
+            # Run reset and return its result
+            #{self}.reset
+
+            # Run enabled and return its result
+            #{self}.enabled?
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+
+            # Replay stored trajectories into Q so a cold table is not empty advice
+            #{self}.warmup!(
+              limit: 'optional - limit value consumed by #warmup!'
+            )
+
+            # Run maybe warmup and return its result
+            #{self}.maybe_warmup!
+          "
+          constants.sort
         end
 
         # ----------------------------------------------------------------

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

@@ -199,8 +199,10 @@ module PWN
           eval_s = ToolGuard.deadline_s(kind: :eval) if defined?(ToolGuard)
           shell_s = ToolGuard.deadline_s(kind: :shell) if defined?(ToolGuard)
           load_line = "load1=#{snap[:load1]} ncpu=#{snap[:ncpu]} mem_avail_mb=#{snap[:mem_avail_mb]}"
+          doc = (PWN::Plugins::Doctor.host_summary if defined?(PWN::Plugins::Doctor))
           "#{load_line} pwn_eval/shell timeout = conservative seconds for this host " \
-            "(defaults eval=#{eval_s || 20}s shell=#{shell_s || 30}s, clamped)."
+            "(defaults eval=#{eval_s || 20}s shell=#{shell_s || 30}s, clamped). " \
+            "#{doc}"
         rescue StandardError
           'load unknown — pass a conservative timeout on pwn_eval/shell anyway.'
         end
@@ -359,16 +361,24 @@ module PWN
         # Display Usage for this Module
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              system_prompt = PWN::AI::Agent::PromptBuilder.build(session_id: 'abc', request: 'nmap sweep 10/8')
-              PWN::AI::Agent::PromptBuilder.budget   # => {memory:, metrics:, mistakes:, learning:, extro:}
-
-              Override per-engine via:
-                PWN::Env[:ai][:ollama][:prompt_budget] = { memory: 4, extro: false }
-
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run build and return its result
+            #{self}.build(
+              session_id: 'optional - PWN::Sessions id to embed in the ENV block',
+              request: 'optional - user request; enables relevance-ranked MEMORY when provided',
+              thin: 'optional - thin value consumed by #build',
+              mode: 'optional - mode value consumed by #build',
+              expand_harness: 'optional - expand harness value consumed by #build',
+              stuck: 'optional - stuck value consumed by #build'
+            )
+
+            # Run budget and return its result
+            #{self}.budget
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
       end
     end

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

@@ -197,19 +197,50 @@ module PWN
         end
 
         public_class_method def self.help
-          puts <<~USAGE
-            USAGE:
-              parts  = PWN::AI::Agent::PromptCache.split_system(text: system_prompt)
-              blocks = PWN::AI::Agent::PromptCache.anthropic_system_blocks(text: system_prompt)
-              msgs   = PWN::AI::Agent::PromptCache.openai_messages(messages: [...])
-              inst   = PWN::AI::Agent::PromptCache.gemini_system_instruction(text: system_prompt)
-              key    = PWN::AI::Agent::PromptCache.cache_key(text: system_prompt)
-              # Engine chat_with_tools uses the helpers automatically when
-              # PWN::Env[:ai][:agent][:prompt_cache] is truthy (default).
-
-              Toggle via PWN::Env[:ai][:agent][:prompt_cache]
-              #{self}.authors
-          USAGE
+          puts "USAGE:
+            # Run enabled and return its result
+            #{self}.enabled?(
+              engine: 'optional - engine value consumed by #enabled?'
+            )
+
+            # Run split system and return its result
+            #{self}.split_system(
+              text: 'required - text value consumed by #split_system'
+            )
+
+            # Run anthropic system blocks and return its result
+            #{self}.anthropic_system_blocks(
+              text: 'required - text value consumed by #anthropic_system_blocks'
+            )
+
+            # Run openai messages and return its result
+            #{self}.openai_messages(
+              messages: 'required - Array messages value consumed by #openai_messages'
+            )
+
+            # Run gemini system instruction and return its result
+            #{self}.gemini_system_instruction(
+              text: 'required - text value consumed by #gemini_system_instruction'
+            )
+
+            # Run cache key and return its result
+            #{self}.cache_key(
+              key: 'optional - key value consumed by #cache_key',
+              text: 'optional - text value consumed by #cache_key'
+            )
+
+            # Run cache marks and return its result
+            #{self}.cache_marks(
+              blocks: 'optional - Array blocks value consumed by #cache_marks'
+            )
+
+            # Run supports and return its result
+            #{self}.supports
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
         end
 
         private_class_method def self.first_dynamic_index(opts = {})