pwn 0.5.720 → 0.5.722

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd0d654d48c9ead7f9a92893f88443e1cfd7cd9a867c53cb2ffc25cbb60fe27
-  data.tar.gz: 3960e8501cbd0139184cd0981569a28a4f9b37e47ddddeb5dab001b2d0eefb1b
+  metadata.gz: 31f54d1cd6a7bfbc4cef3bcc989650930b1b31bbf2bbc47654b20d6f20158775
+  data.tar.gz: 50bfda31eecd4b99d17324a8c4c548f14b8df10561c183f27bc9e7157c8f88bf
 SHA512:
-  metadata.gz: defca7be52f6960bbaa318f5e40e4927cafa8a1e679ce27dd8e74b73feae4b89a9766b725a5731b2e2fa5a8e93c58a2fa3622f0c37df6b0355bf6b12e9affbae
-  data.tar.gz: 29de8ee9497ec7004c4752ddaf3fc359016c6007368e051e891e191ad18bf069a3a44d32aa73ed480dc60cb30bba46551efa2f636009b8d50752e0101917900b
+  metadata.gz: 3a43118f36da1f9712dbfb908b5f0c9d4650d3bfde63239240d7c9cefcc50d29d78468e14e9cd9bf44f9fdba5df971b48659b348619dc79a7e17667028930025
+  data.tar.gz: 867d72ec34f85caaf18fa5abeb38b466d5663c1361becf17cb4af87115dd0d45411527b0f5616dd54874c241544416fb0b9427f16476248ed38a864b3951daef

data/etc/default_skills/pwn/ai/agent/learning/SKILL.md

@@ -34,6 +34,8 @@ PWN::AI::Agent::Learning.note_outcome(opts)
 ## Public methods
 
 - `note_outcome`
+- `consistency_check`
+- `disputed_save`
 - `outcomes`
 - `stats`
 - `to_context`

data/etc/default_skills/pwn/ai/agent/loop/SKILL.md

@@ -28,11 +28,12 @@ Class methods take `(opts = {})` and read `opts`.
 
 ```ruby
 PWN::AI::Agent::Loop.help
-PWN::AI::Agent::Loop.debug_on(opts)
+PWN::AI::Agent::Loop.evidence_satisfied(opts)
 ```
 
 ## Public methods
 
+- `evidence_satisfied`
 - `debug_on`
 - `catalog_lookup`
 - `world_knowledge`
@@ -46,6 +47,7 @@ PWN::AI::Agent::Loop.debug_on(opts)
 - `help`
 - `catalog_lookup?`
 - `debug_on?`
+- `evidence_satisfied?`
 - `needs_host_work?`
 - `world_knowledge?`
 
@@ -59,5 +61,5 @@ PWN::AI::Agent::Loop.debug_on(opts)
 
 ## Verification
 
-`PWN::AI::Agent::Loop.respond_to?(:debug_on)` after the
+`PWN::AI::Agent::Loop.respond_to?(:evidence_satisfied)` after the
 module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/ai/agent/metrics/SKILL.md

@@ -36,7 +36,9 @@ PWN::AI::Agent::Metrics.load(opts)
 - `load`
 - `save`
 - `record`
+- `append_jsonl`
 - `summary`
+- `snapshot`
 - `to_context`
 - `proxy_trust`
 - `ucb`

data/etc/default_skills/pwn/ai/agent/mistakes/SKILL.md

@@ -37,6 +37,7 @@ PWN::AI::Agent::Mistakes.load(opts)
 - `save`
 - `signature`
 - `error_class`
+- `family`
 - `find`
 - `for_tool`
 - `record`
@@ -48,6 +49,7 @@ PWN::AI::Agent::Mistakes.load(opts)
 - `operator_inbox`
 - `to_context`
 - `correction_hint`
+- `note_hint_outcome`
 - `correction`
 - `check_user_correction`
 - `lean`

data/etc/default_skills/pwn/ai/agent/registry/SKILL.md

@@ -42,8 +42,11 @@ PWN::AI::Agent::Registry.register(opts)
 - `apply_preference`
 - `rank`
 - `discover`
+- `eager_load`
+- `selftest`
 - `authors`
 - `help`
+- `eager_load!`
 
 ## Source
 

data/etc/default_skills/pwn/ai/agent/tool_guard/SKILL.md

@@ -61,6 +61,7 @@ PWN::AI::Agent::ToolGuard.present(opts)
 - `refuse_copied_persist`
 - `scope_refusal`
 - `policy_decision`
+- `scope_check`
 - `rfc1918`
 - `ip_in_cidr`
 - `command_class`
@@ -81,6 +82,7 @@ PWN::AI::Agent::ToolGuard.present(opts)
 - `refuse_copied_persist?`
 - `reset_timeout_budget!`
 - `rfc1918?`
+- `scope_check!`
 - `shell_bash?`
 
 ## Source

data/etc/default_skills/pwn/ai/agent/turn_finalizer/SKILL.md

@@ -43,9 +43,11 @@ PWN::AI::Agent::TurnFinalizer.enter_user_path(opts)
 - `pending`
 - `arbitrate`
 - `evidence_ledger`
+- `evidence_satisfied`
 - `authors`
 - `help`
 - `enter_user_path!`
+- `evidence_satisfied?`
 - `join_all!`
 - `leave_user_path!`
 - `should_defer?`

data/etc/default_skills/pwn/plugins/artifact_registry/SKILL.md

@@ -38,6 +38,7 @@ PWN::Plugins::ArtifactRegistry.required_bins(opts)
 - `list`
 - `get`
 - `read_page`
+- `put`
 - `authors`
 - `help`
 

data/etc/default_skills/pwn/plugins/exploit_dev/SKILL.md

@@ -52,6 +52,8 @@ PWN::Plugins::ExploitDev.required_bins(opts)
 - `gadgets`
 - `fmtstr`
 - `io`
+- `scaffold`
+- `from_crash`
 - `authors`
 - `help`
 

data/etc/default_skills/pwn/plugins/gdb/SKILL.md

@@ -42,6 +42,7 @@ PWN::Plugins::GDB.required_bins(opts)
 - `breakpoints`
 - `crash_info`
 - `debug_session`
+- `ptrace_preflight`
 - `authors`
 - `help`
 

data/etc/default_skills/pwn/plugins/jobs/SKILL.md

@@ -35,6 +35,7 @@ PWN::Plugins::Jobs.required_bins(opts)
 
 - `required_bins`
 - `start`
+- `watch`
 - `status`
 - `tail`
 - `result`

data/etc/default_skills/pwn/plugins/preflight_checker/SKILL.md

@@ -37,6 +37,7 @@ PWN::Plugins::PreflightChecker.required_bins(opts)
 - `bin`
 - `require_bin`
 - `route`
+- `capability_coverage`
 - `pick`
 - `cap_net_raw`
 - `require_cap_net_raw`

data/etc/default_skills/pwn/plugins/process_tube/SKILL.md

@@ -43,6 +43,8 @@ PWN::Plugins::ProcessTube.required_bins(opts)
 - `expect`
 - `stream`
 - `reap_orphans`
+- `list`
+- `kill`
 - `authors`
 - `help`
 

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

@@ -52,7 +52,8 @@ module PWN
             args = expand_vault_args(args: args)
           end
           if defined?(Engagement)
-            denied = Engagement.deny_if_out_of_scope(args: args, command: blob)
+            denied = ToolGuard.scope_check!(args: args, command: blob) if defined?(ToolGuard) && ToolGuard.respond_to?(:scope_check!)
+            denied ||= Engagement.deny_if_out_of_scope(args: args, command: blob)
             return JSON.generate(denied) if denied
           end
           if defined?(ToolGuard) && ToolGuard.respond_to?(:policy_decision)
@@ -71,6 +72,15 @@ module PWN
               error: 'refused: memory_remember/skills_update text copied from last tool output'
             )
           end
+          if blob.match?(/open_sockraw|sockraw/) && defined?(PWN::Plugins::PreflightChecker) &&
+             PWN::Plugins::PreflightChecker.respond_to?(:cap_net_raw?) && !PWN::Plugins::PreflightChecker.cap_net_raw?
+            return JSON.generate(
+              success: false,
+              error: 'capability missing CAP_NET_RAW',
+              substitute: 'PWN::Plugins::Packet.tcp_connect_scan',
+              code: 'CAP_DENY'
+            )
+          end
           result = entry.handler.call(args)
           result = ToolGuard.quarantine_output(text: result) if defined?(ToolGuard) && result.is_a?(String) && ToolGuard.respond_to?(:quarantine_output)
           note_taint(text: result)
@@ -343,8 +353,8 @@ module PWN
           return :store if STORE_TOOLS.include?(name)
 
           blob = argv_blob(args: opts[:args])
-          return :browse if blob.match?(BROWSE_ARGV_RX)
           return :write if blob.match?(WRITE_ARGV_RX)
+          return :browse if blob.match?(BROWSE_ARGV_RX)
           return :eval if name == 'pwn_eval'
 
           :read
@@ -381,7 +391,7 @@ module PWN
 
         private_class_method def self.note_taint(opts = {})
           text = opts[:text].to_s
-          grams = text.scan(/.{12,}/).first(20)
+          grams = text.scan(/.{24,}/).first(20)
           store = Thread.current[:pwn_taint] ||= []
           grams.each { |g| store << g[0, 64] }
           store.shift while store.length > 200
@@ -393,10 +403,10 @@ module PWN
           return false if mode == 'off'
 
           blob = opts[:args].inspect
-          return false if blob.length < 12
+          return false if blob.length < 24
           return false if opts[:args].is_a?(Hash) && (opts[:args][:taint_ack] == true || opts[:args]['taint_ack'] == true)
 
-          hit = Array(Thread.current[:pwn_taint]).any? { |g| g.length >= 12 && blob.include?(g) }
+          hit = Array(Thread.current[:pwn_taint]).any? { |g| g.length >= 24 && blob.include?(g) }
           return false unless hit
           return false unless blob.match?(/curl |bash -c|sh -c|\|\s*sh\b/i)
 

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

@@ -26,6 +26,7 @@ module PWN
       # restarts and is shared by every future session.
       module Learning
         LEARNING_FILE      = File.join(Dir.home, '.pwn', 'learning.jsonl')
+        DISPUTED_FILE      = File.join(Dir.home, '.pwn', 'learning', 'disputed.jsonl')
         LESSONS_FILE       = File.join(Dir.home, '.pwn', 'lessons.json')
         FINETUNE_DIR       = File.join(Dir.home, '.pwn', 'finetune')
         # P0 — post-answer introspect must not train "stop early" while
@@ -138,6 +139,12 @@ module PWN
             entry[:success] = true
             success = true
           end
+          check = consistency_check(details: details, success: success, rationale: opts[:rationale])
+          if check == :disputed
+            entry[:status] = 'disputed'
+            disputed_save(entry: entry)
+            return entry
+          end
           FileUtils.mkdir_p(File.dirname(LEARNING_FILE))
           File.open(LEARNING_FILE, 'a') { |f| f.puts(JSON.generate(entry)) }
           maybe_prune_outcomes!
@@ -159,6 +166,22 @@ module PWN
           entry
         end
 
+        public_class_method def self.consistency_check(opts = {})
+          details = "#{opts[:details]} #{opts[:rationale]}"
+          success = opts[:success]
+          return :disputed if details.match?(/\bPASS\b/) && success == false
+          return :disputed if details.match?(/\bFAIL\b/) && success == true && !details.match?(/\bPASS\b/)
+
+          :ok
+        end
+
+        public_class_method def self.disputed_save(opts = {})
+          entry = opts[:entry] || {}
+          FileUtils.mkdir_p(File.dirname(DISPUTED_FILE))
+          File.open(DISPUTED_FILE, 'a') { |f| f.puts(JSON.generate(entry)) }
+          entry
+        end
+
         # Supported Method Parameters::
         # rows = PWN::AI::Agent::Learning.outcomes(
         #   limit: 'optional - max entries returned newest-first (default 50)',
@@ -196,11 +219,21 @@ module PWN
           jmean  = total.positive? ? weighted_judge_mean(rows: rows) : nil
           distrust = 0.0
           distrust = Reward.proxy_distrust.to_f.clamp(0.0, 1.0) if defined?(Reward) && Reward.respond_to?(:proxy_distrust)
+          orm = rows.select { |r| r[:judge_source].to_s != 'heuristic' && r[:source].to_s != 'heuristic' }
+          heur = rows.select { |r| r[:judge_source].to_s == 'heuristic' || r[:source].to_s == 'heuristic' }
+          orm_n = orm.length
+          heur_n = heur.length
+          orm_ok = orm.count { |r| r[:success] == true }
+          heur_ok = heur.count { |r| r[:success] == true }
           {
             total_outcomes: total,
             successes: ok,
             failures: total - ok,
             success_rate: raw,
+            success_rate_orm: orm_n.positive? ? (orm_ok.to_f / orm_n).round(3) : 0.0,
+            success_rate_heur: heur_n.positive? ? (heur_ok.to_f / heur_n).round(3) : 0.0,
+            orm_n: orm_n,
+            heur_n: heur_n,
             adjusted_success_rate: discount_success_rate(proxy: raw, judge: jmean, distrust: distrust),
             proxy_distrust: distrust,
             skills_known: skills,
@@ -227,6 +260,12 @@ module PWN
           fails = prefer_primary_tasks(rows: outcomes(limit: 200, success: false))
           fails = fails.reject { |r| r[:status].to_s == 'conflicted' }
           fails = fails.reject { |r| r[:verifier_verdict].to_s == 'pass' }
+          fails = fails.reject { |r| r[:details].to_s.match?(/\bPASS\b/) && r[:success] == true }
+          fails = fails.select do |r|
+            v = r[:verdict].to_s
+            v == 'wrong' || v == 'refused' || (r[:score].to_f < 0.3 && !r[:details].to_s.match?(/\bPASS\b/)) || r[:success] == false
+          end
+          fails = fails.reject { |r| r[:success] == true }
           # Do not mirror the same ids under both headings — that doubled the
           # failure signal and made RECENT OUTCOMES == RECENT FAILURES when the
           # last N attempts all failed (the injected block looked "stuck").
@@ -260,7 +299,7 @@ module PWN
           d   = s[:proxy_distrust].to_f
           rate = d > 0.05 ? s[:adjusted_success_rate] : s[:success_rate]
           tag  = d > 0.05 ? ' adj' : ''
-          hdr = "RECENT OUTCOMES (success_rate=#{(rate.to_f * 100).round(1)}%#{tag}#{" judge_mean=#{jm}" if jm} over #{s[:total_outcomes]} attempts)"
+          hdr = "RECENT OUTCOMES (success_rate=#{(rate.to_f * 100).round(1)}%#{tag} success=orm:#{(s[:success_rate_orm].to_f * 100).round(1)}%(#{s[:orm_n]}) / heur:#{(s[:success_rate_heur].to_f * 100).round(1)}%(#{s[:heur_n]})#{" judge_mean=#{jm}" if jm} over #{s[:total_outcomes]} attempts)"
           out = "#{hdr}\n#{rows.map(&fmt).join("\n")}\n"
           out += "RECENT FAILURES (learn from these — do not repeat)\n#{fails.map(&fmt).join("\n")}\n" unless fails.empty?
           "#{out}\n"
@@ -2065,6 +2104,18 @@ module PWN
               include_demoted: 'optional - include demoted lessons (defaults to false)'
             )
 
+            # Refuse PASS+success:false rows; they go to the disputed queue.
+            #{self}.consistency_check(
+              details: 'optional - details string that may contain PASS/FAIL',
+              rationale: 'optional - judge rationale text',
+              success: 'required - boolean success flag'
+            )
+
+            # Append a disputed outcome to ~/.pwn/learning/disputed.jsonl.
+            #{self}.disputed_save(
+              entry: 'required - Hash of the disputed learning row'
+            )
+
             # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "

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

@@ -64,6 +64,18 @@ module PWN
           unsatisfied incomplete_final empty_final evidence_final
         ].freeze
 
+        public_class_method def self.evidence_satisfied?(opts = {})
+          messages = Array(opts[:messages] || opts[:trace])
+          text = opts[:text].to_s
+          if defined?(TurnFinalizer) && TurnFinalizer.respond_to?(:arbitrate)
+            row = TurnFinalizer.arbitrate(request: opts[:request].to_s, messages: messages, paths: [])
+            return true if row[:complete] && row[:unmet].empty? && row[:ledger].any? { |_p, v| v[:write] && v[:read] }
+          end
+          write_or_read_evidenced?(messages: messages) && !text.strip.empty?
+        rescue StandardError
+          false
+        end
+
         public_class_method def self.debug_on?(opts = {})
           return true if opts[:debug]
           return true if defined?(PWN::Plugins::Log) && PWN::Plugins::Log.debug_enabled?
@@ -394,6 +406,7 @@ module PWN
         # the original request → force synthesis. English tasks are an advisory
         # compass only — an open verify tail must not block a finished ask.
         # The original request is the completion signal.
+
         private_class_method def self.evidence_enough_to_finalize?(opts = {})
           messages = Array(opts[:messages])
           turn_fails = opts[:turn_fails] || {}
@@ -595,7 +608,7 @@ module PWN
             request: request,
             messages: opts[:messages]
           )
-          return true if need == :write && !write_verified?(effects: effects)
+          return true if need == :write && !write_verified?(effects: effects, request: request, messages: opts[:messages])
           return true if need == :browse && !effects.include?(:browse)
           return true if need == :any && !effects.intersect?(%i[write browse eval])
 
@@ -607,10 +620,27 @@ module PWN
         private_class_method def self.write_verified?(opts = {})
           effects = Array(opts[:effects])
           idx = effects.index(:write)
-          return false if idx.nil?
+          if idx
+            tail = effects[(idx + 1)..] || []
+            return true if tail.intersect?(%i[read eval])
+          end
 
-          tail = effects[(idx + 1)..] || []
-          tail.intersect?(%i[read eval])
+          saw_write_argv = false
+          Array(opts[:messages]).each do |msg|
+            next unless msg.is_a?(Hash)
+
+            if msg[:role].to_s == 'assistant' && defined?(Dispatch)
+              Array(msg[:tool_calls]).each do |tc|
+                blob = Dispatch.send(:argv_blob, args: tc.dig(:function, :arguments) || tc.dig('function', 'arguments'))
+                saw_write_argv = true if blob.to_s.match?(Dispatch::WRITE_ARGV_RX)
+              end
+            elsif saw_write_argv && msg[:role].to_s == 'tool'
+              fx = stamped_effect(content: msg[:content])
+              return true if %i[read eval].include?(fx)
+            end
+          end
+
+          false
         rescue StandardError
           false
         end
@@ -875,6 +905,7 @@ module PWN
         end
 
         private_class_method def self.may_finalize?(opts = {})
+          return true if evidence_satisfied?(messages: opts[:messages], text: opts[:text], request: opts[:request])
           return false if incomplete_final?(text: opts[:text], last_iter: false)
           return false if request_unsatisfied?(
             request: opts[:request],
@@ -1145,6 +1176,16 @@ module PWN
           false
         end
 
+        private_class_method def self.session_tool_budget(opts = {})
+          name = opts[:name].to_s
+          result = opts[:result].to_s
+          return 16_384 if name.match?(/decompile|binary_triage|artifact_read|exploitdev/)
+          return 16_384 if name == 'pwn_eval' && result.match?(/r2 |objdump|xxd |pdf\b|afl-/)
+          return 16_384 if name == 'shell' && result.match?(/objdump|xxd|radare|r2 |disassembl/)
+
+          1_024
+        end
+
         # E1 — did the environment change under this tool? If Metrics CUSUM
         # tripped for it in the last hour AND Extrospection.drift shows a
         # toolchain/net/repo change, blame the WORLD not the AGENT.
@@ -1678,6 +1719,7 @@ module PWN
             }
             # Ollama + abliterated / weak chat-templates often ignore tools: and
             # answer in prose (or print shell(...) as text). Force native
+
             # tool_calls until at least one tool result is already in history;
             # after that, auto so the model can emit a real final answer.
             # Respect explicit PWN::Env[:ai][:ollama][:tool_choice] override.
@@ -1705,10 +1747,6 @@ module PWN
           end
         end
 
-        # 3.1 — sliding-window history compaction for local models.
-        # Keep: system, original user, PLAN assistant (if any), last K tool
-        # pairs (assistant+tool), and the most recent assistant. Stale tool
-        # bodies are truncated to history_tool_max_chars.
         private_class_method def self.session_chat_history(opts = {})
           return [] unless defined?(PWN::Sessions) && PWN::Sessions.respond_to?(:to_llm_messages)
 
@@ -1831,15 +1869,15 @@ module PWN
 
         private_class_method def self.spill_tool_body(opts = {})
           text = opts[:text].to_s
-          digest = Digest::SHA256.hexdigest(text)[0, 16]
-          dir = HISTORY_SPILL_DIR
+          digest = Digest::SHA256.hexdigest(text)
+          dir = File.join(Dir.home, '.pwn', 'artifacts', 'transcripts', (Thread.current[:pwn_session_id] || 'default').to_s)
           FileUtils.mkdir_p(dir)
-          path = File.join(dir, "#{digest}.txt")
+          path = File.join(dir, "#{digest[0, 12]}.txt")
           File.binwrite(path, text) unless File.file?(path)
           head = text.byteslice(0, 2_048).to_s
           tail = text.bytesize > 3_072 ? text.byteslice(-1_024, 1_024).to_s : ''
           mid = tail.empty? ? '' : "\n...\n#{tail}"
-          "#{head}#{mid}\n[compacted path=#{path} sha256=#{digest} bytes=#{text.bytesize}]"
+          "#{head}#{mid}\n[compacted path=#{path} sha256=#{digest} bytes=#{text.bytesize} ref=#{path}]"
         rescue StandardError
           "[compacted bytes=#{opts[:text].to_s.bytesize}]"
         end
@@ -3002,17 +3040,21 @@ module PWN
                 text: text
               )
                 turn_fails['unsatisfied'] += 1
-                unmet = completion_unmet(request: request, messages: messages)
-                warn "[pwn-ai/loop] original request not evidenced on iter=#{i} unmet=#{unmet.join(',')}; continuing"
-                debug_progress(msg: "bounce unsatisfied unmet=#{unmet.join(',')} snippet=#{debug_snippet(text: text)}")
-                messages << {
-                  role: 'user',
-                  content: "[pwn-ai] The original request is not evidenced yet. unmet=#{unmet.join(',')} " \
-                           'Keep calling CORE_TOOLS (shell, pwn_eval) until that request is ' \
-                           'done or a tool returned failure evidence. pwn-ai does not decide ' \
-                           'authorization. Do not declare completion from a listing or a refusal.'
-                }
-                next
+                if turn_fails['unsatisfied'] >= 2 && evidence_satisfied?(request: request, messages: messages, text: text)
+                  debug_progress(msg: 'nag cap: evidence_satisfied after 2 bounces')
+                else
+                  unmet = completion_unmet(request: request, messages: messages)
+                  warn "[pwn-ai/loop] original request not evidenced on iter=#{i} unmet=#{unmet.join(',')}; continuing"
+                  debug_progress(msg: "bounce unsatisfied unmet=#{unmet.join(',')} snippet=#{debug_snippet(text: text)}")
+                  messages << {
+                    role: 'user',
+                    content: "[pwn-ai] The original request is not evidenced yet. unmet=#{unmet.join(',')} " \
+                             'Keep calling CORE_TOOLS (shell, pwn_eval) until that request is ' \
+                             'done or a tool returned failure evidence. pwn-ai does not decide ' \
+                             'authorization. Do not declare completion from a listing or a refusal.'
+                  }
+                  next
+                end
               end
               debug_progress(msg: "final accepted chars=#{text.to_s.length}")
               quiet_debug_tui!(reason: 'final')
@@ -3094,7 +3136,7 @@ module PWN
               append_session(
                 session_id: session_id,
                 role: 'tool',
-                content: "#{name} → #{result[0, 1_024]}"
+                content: "#{name} → #{result[0, session_tool_budget(name: name, result: result)]}"
               )
             end
 
@@ -3163,8 +3205,6 @@ module PWN
           "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
         end
 
-        # Display Usage for this Module
-
         public_class_method def self.help
           puts "USAGE:
             # Run debug on and return its result
@@ -3172,6 +3212,14 @@ module PWN
               debug: 'optional - debug value consumed by #debug_on?'
             )
 
+            # True when write-then-readback evidence satisfies the original request.
+            #{self}.evidence_satisfied?(
+              messages: 'optional - Array of role/content hashes',
+              trace: 'optional - alias for messages',
+              text: 'optional - final answer text',
+              request: 'optional - original request'
+            )
+
             # True only when the ask needs a live host/file/browser effect. World-knowledge
             #{self}.catalog_lookup?(
               request: 'required - request value consumed by #catalog_lookup?'

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

@@ -99,9 +99,32 @@ module PWN
             bump(bucket: e, success: success, duration: duration, error: error)
           end
           save(metrics: metrics)
+          append_jsonl(opts.merge(name: name, success: success, duration: duration, error: error, engine: engine))
           t
         end
 
+        public_class_method def self.append_jsonl(opts = {})
+          path = File.join(Dir.home, '.pwn', 'logs', 'tool_metrics.jsonl')
+          FileUtils.mkdir_p(File.dirname(path))
+          row = {
+            ts: Time.now.utc.iso8601,
+            session: Thread.current[:pwn_session_id],
+            tool: opts[:name],
+            latency_ms: (opts[:duration].to_f * 1000).round,
+            timeout_used: opts[:timeout],
+            outcome: opts[:success] ? 'ok' : 'err',
+            error_class: opts[:error].to_s.split(':').first,
+            bytes_out: opts[:bytes_out].to_i
+          }
+          File.open(path, 'a') do |f|
+            f.flock(File::LOCK_EX)
+            f.puts(JSON.generate(row))
+          end
+          row
+        rescue StandardError
+          nil
+        end
+
         # Supported Method Parameters::
         # rows = PWN::AI::Agent::Metrics.summary(
         #   limit: 'optional - cap number of tools returned (default 25)',
@@ -133,6 +156,19 @@ module PWN
               .sort_by { |r| [-r[:calls], -r[:success_rate]] }.first(limit)
         end
 
+        public_class_method def self.snapshot(opts = {})
+          _day = opts[:day]
+          learn = defined?(Learning) ? Learning.stats : {}
+          {
+            success_rate: learn[:success_rate],
+            success_rate_orm: learn[:success_rate_orm],
+            success_rate_heur: learn[:success_rate_heur],
+            brier: (learn.dig(:calibration, :brier) if learn.is_a?(Hash)),
+            proxy_distrust: learn[:proxy_distrust],
+            tools: summary(limit: 8)
+          }
+        end
+
         # Supported Method Parameters::
         # ctx = PWN::AI::Agent::Metrics.to_context(
         #   limit: 'optional - cap number of tools included (default 8)',
@@ -664,11 +700,22 @@ module PWN
             #{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',
+              duration: 'optional - Float seconds the dispatch took (wall time)',
               error: 'optional - String error message when success is false',
               engine: 'optional - Symbol/String AI engine that chose this tool (segments telemetry)'
             )
 
+            # Append one JSONL telemetry row under ~/.pwn/logs/tool_metrics.jsonl.
+            #{self}.append_jsonl(
+              name: 'required - tool name',
+              success: 'optional - Boolean outcome',
+              duration: 'optional - Float seconds the dispatch took (wall time)',
+              error: 'optional - error string',
+              engine: 'optional - engine name',
+              timeout: 'optional - timeout used',
+              bytes_out: 'optional - output byte count'
+            )
+
             # Run summary and return its result
             #{self}.summary(
               limit: 'optional - cap number of tools returned (default 25)',
@@ -780,6 +827,11 @@ module PWN
             # Run reset and return its result
             #{self}.reset
 
+            # Snapshot success rates per judge source for the LEARNING block.
+            #{self}.snapshot(
+              day: 'optional - reserved day key for rotation'
+            )
+
             # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "