pwn 0.5.675 → 0.5.676

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ed5f171854df678e76d477ad52fee2dd42e1687afc6e950281d2b3e5fe75ab9
-  data.tar.gz: 35712ab0300a98de2dfc52430278088561b84fcd15e4dd70a3c95cd90ccf4645
+  metadata.gz: 65d8aa03f93adc593efbfb8b342885f8ceb815a19a6a8ef8e72c3b0a493a32a5
+  data.tar.gz: eee3d957a5975a105240040cf6bd2f0a44a05d35cbac3240ec252f913cc38c5e
 SHA512:
-  metadata.gz: 563ee1d396728ef91353cfc4e6d82da6b90662d03e55d1c027319203e47a8bd91d9c723a09cda3a6836dc9b1ed380bb3e0bb76d802dd23157ff7c92d52a3958b
-  data.tar.gz: 05e3c313c8262273f5799f24a9359b3cadc5448ccebfc5ae031a99a71865b548d24489208f4b7be6e0d4790485ebcc58d35a3ccdafbfddfecdb27eaddd531b9c
+  metadata.gz: 03f6a8960538e278b4041981a64ad27c4163e3748a11866c559c81da75152644f62b61658f695369f0281832e03d0810f012f47387b3ff4c456ad2df964b365c
+  data.tar.gz: 9b3eec90f64577c1167ae556d713f07f82f1c76d43255a14b7a1b69eaec5cfa2bdd9d99343d0a338aef40d1aa9e6fbd2c4c89d72e9e5d7b35b6a69ab504cdc07

data/bin/pwn_setup

@@ -54,6 +54,11 @@ pwn_driver = PWN::Driver::Parser.new do |options|
              '<Optional - Print the commands that would run, do not execute>') do |o|
     opts[:dry_run] = o
   end
+
+  options.on('--[no-]cron',
+             '<Optional - Enable (default) or disable OS-native persistence of pwn-ai cron jobs>') do |o|
+    opts[:cron] = o
+  end
 end
 pwn_driver.auto_opts_help = false
 pwn_driver.parse!
@@ -65,10 +70,9 @@ begin
   # the worker as running. Skip list/terminal (no host scheduler needed)
   # and dry-run (must not spawn).
   unless opts[:list] || opts[:terminal] || opts[:dry_run]
-    PWN::Setup.ensure_cron(
-      restart: false,
-      dry_run: false
-    )
+    cron_opts = { restart: false, dry_run: false }
+    cron_opts[:enabled] = opts[:cron] unless opts[:cron].nil?
+    PWN::Setup.ensure_cron(**cron_opts)
   end
 
   if opts[:list]
@@ -102,10 +106,9 @@ begin
   # last_run actually advances. Skip list/terminal (no host scheduler
   # needed) and dry-run (must not spawn).
   unless opts[:list] || opts[:terminal] || opts[:dry_run]
-    PWN::Setup.ensure_cron(
-      restart: false,
-      dry_run: false
-    )
+    cron_opts = { restart: false, dry_run: false }
+    cron_opts[:enabled] = opts[:cron] unless opts[:cron].nil?
+    PWN::Setup.ensure_cron(**cron_opts)
   end
   exit status
 rescue Interrupt

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

@@ -460,6 +460,11 @@ module PWN
           return unless session_id
           return unless auto_introspect_enabled?
 
+          # Hermes split: Loop.run is on the stack → defer critic/judge/PRM/HER
+          # onto a daemon thread so the user already has the reply. Specs,
+          # cron, and tools pass through (inline:true or no user-path depth).
+          return TurnFinalizer.defer(opts.merge(inline: true)) if defined?(TurnFinalizer) && !opts[:inline] && TurnFinalizer.should_defer?
+
           t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           stages_run = []
           stages_skipped = []

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

@@ -1875,6 +1875,7 @@ module PWN
           request = opts[:request].to_s
           session_id = opts[:session_id]
           on_tool = opts[:on_tool]
+          TurnFinalizer.enter_user_path! if defined?(TurnFinalizer)
           # Live coalesced "what am I doing" lines for the TUI (not a model tool).
           ts_state = (TaskSummarizer.fresh(request: request) if defined?(TaskSummarizer) && TaskSummarizer.enabled? && Thread.current[:pwn_reflect_depth].to_i.zero?)
           engine = active_engine
@@ -2307,6 +2308,8 @@ module PWN
           maybe_finish_policy(session_id: session_id, proxy_ok: false, ts_state: ts_state)
           task_summary_flush!(state: ts_state, on_tool: on_tool)
           final_msg
+        ensure
+          TurnFinalizer.leave_user_path! if defined?(TurnFinalizer)
         end
 
         # Author(s):: 0day Inc. <support@0dayinc.com>

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

@@ -434,6 +434,21 @@ module PWN
           Thread.current[EP_KEY]
         end
 
+        # Hermes split: snapshot + clear the live episode so Loop.maybe_finish_policy
+        # is a no-op on the user-visible path while TurnFinalizer re-attaches it
+        # on the background review thread.
+
+        public_class_method def self.detach_episode!
+          ep = Thread.current[EP_KEY]
+          Thread.current[EP_KEY] = nil
+          ep
+        end
+
+        public_class_method def self.attach_episode!(opts = {})
+          Thread.current[EP_KEY] = opts[:episode]
+          opts[:episode]
+        end
+
         # ----------------------------------------------------------------
         # Persistence / eval
         # ----------------------------------------------------------------

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

@@ -41,6 +41,9 @@ module PWN
 
           # Heredoc (not a "..." literal): an unescaped "..." inside a
           # double-quoted string is parsed as Range (begin..."...end).
+          # Skills sit in the STATIC prefix (Hermes index) so prompt-cache
+          # breakpoints can pin the persona + SKILLS list; MEMORY/LEARNING
+          # remain in the dynamic tail.
           <<~PROMPT
             #{base}
 
@@ -51,7 +54,7 @@ module PWN
               pwn        : #{pwn_version}
               session_id : #{session_id || '(none)'}
 
-            #{memory_block(limit: b[:memory], request: request)}#{recent_turns_block(session_id: session_id, request: request, limit: b[:recent_turns])}#{skills_block}#{learning_block(limit: b[:learning])}#{mistakes_block(limit: b[:mistakes], request: request)}#{metrics_block(limit: b[:metrics], engine: engine)}#{policy_block if b[:policy].to_i.positive?}#{extrospection_block if b[:extro]}TOOL USE
+            #{skills_block}#{memory_block(limit: b[:memory], request: request)}#{recent_turns_block(session_id: session_id, request: request, limit: b[:recent_turns])}#{learning_block(limit: b[:learning])}#{mistakes_block(limit: b[:mistakes], request: request)}#{metrics_block(limit: b[:metrics], engine: engine)}#{policy_block if b[:policy].to_i.positive?}#{extrospection_block if b[:extro]}TOOL USE
               Use the provided function tools to act on the host via NATIVE
               tool_calls / function calling — never print tool invocations as
               plain text (e.g. do NOT write shell(command="...") as your answer).

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

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module PWN
+  module AI
+    module Agent
+      # Hermes-style prompt-cache breakpoints. The static system prefix +
+      # SKILLS index stay cacheable; dynamic MEMORY / LEARNING / MISTAKES /
+      # METRICS / EXTROSPECTION stay uncached so a turn-local write is not
+      # baked into the prefix.
+      #
+      # Anthropic: system is an array of text blocks; the last static block
+      # carries cache_control: { type: 'ephemeral' }.
+      # OpenAI Chat Completions: two system/developer messages (static then
+      # dynamic) plus prompt_cache_key for cache routing.
+      # xAI Grok Chat Completions: the same message split plus the
+      # x-grok-conv-id request header (sticky server routing).
+      # Gemini generateContent: systemInstruction.parts = [static, dynamic]
+      # so implicit prefix cache can hit the stable head.
+      # Ollama: no-op.
+      module PromptCache
+        STATIC_HEAD = %w[ENVIRONMENT].freeze
+        DYNAMIC_HEADS = [
+          'MEMORY',
+          'RECENT TURNS',
+          'LEARNING',
+          'OPERATOR INBOX',
+          'KNOWN MISTAKES',
+          'KNOWN FIXES',
+          'TOOL EFFECTIVENESS',
+          'POLICY',
+          'EXTROSPECTION',
+          'TOOL USE'
+        ].freeze
+
+        # Supported Method Parameters::
+        # ok = PWN::AI::Agent::PromptCache.enabled?(engine: :anthropic)
+
+        public_class_method def self.enabled?(opts = {})
+          flag = agent_flag(key: :prompt_cache, default: true)
+          return false if flag == false || flag.to_s.match?(/\A(0|false|no|off)\z/i)
+
+          engine = (opts[:engine] || active_engine).to_s.downcase.to_sym
+          supports.include?(engine)
+        rescue StandardError
+          false
+        end
+
+        # Supported Method Parameters::
+        # parts = PWN::AI::Agent::PromptCache.split_system(text: system_prompt)
+        #
+        # → { static: String, dynamic: String, skills: String }
+
+        public_class_method def self.split_system(opts = {})
+          text = opts[:text].to_s
+          return { static: '', dynamic: '', skills: '' } if text.empty?
+
+          dyn_idx = first_dynamic_index(text: text)
+          if dyn_idx.nil?
+            skills = extract_skills(text: text)
+            return { static: text, dynamic: '', skills: skills }
+          end
+
+          static = text[0...dyn_idx].rstrip
+          dynamic = text[dyn_idx..].to_s
+          { static: static, dynamic: dynamic, skills: extract_skills(text: static) }
+        rescue StandardError
+          { static: opts[:text].to_s, dynamic: '', skills: '' }
+        end
+
+        # Supported Method Parameters::
+        # blocks = PWN::AI::Agent::PromptCache.anthropic_system_blocks(text: system_prompt)
+        #
+        # → [ {type:'text', text: static, cache_control:{type:'ephemeral'}},
+        #     {type:'text', text: dynamic} ]  (empty blocks omitted)
+
+        public_class_method def self.anthropic_system_blocks(opts = {})
+          parts = split_system(text: opts[:text])
+          blocks = []
+          unless parts[:static].to_s.strip.empty?
+            blocks << {
+              type: 'text',
+              text: parts[:static],
+              cache_control: { type: 'ephemeral' }
+            }
+          end
+          blocks << { type: 'text', text: parts[:dynamic] } unless parts[:dynamic].to_s.strip.empty?
+          blocks
+        rescue StandardError
+          txt = opts[:text].to_s
+          return [] if txt.strip.empty?
+
+          [{ type: 'text', text: txt }]
+        end
+
+        # Supported Method Parameters::
+        # messages = PWN::AI::Agent::PromptCache.openai_messages(messages: [...])
+        #
+        # Split the first system/developer message into a stable static
+        # prefix and a turn-local dynamic tail so OpenAI / xAI implicit
+        # prefix matching can hit across turns. Does NOT emit Anthropic
+        # cache_control.
+
+        public_class_method def self.openai_messages(opts = {})
+          messages = Array(opts[:messages]).map { |m| m.is_a?(Hash) ? m.dup : m }
+          idx = messages.index do |m|
+            next false unless m.is_a?(Hash)
+
+            %w[system developer].include?((m[:role] || m['role']).to_s)
+          end
+          return messages unless idx
+
+          msg = messages[idx]
+          role = msg[:role] || msg['role']
+          text = (msg[:content] || msg['content']).to_s
+          parts = split_system(text: text)
+          return messages if parts[:static].to_s.strip.empty? || parts[:dynamic].to_s.strip.empty?
+
+          static_msg = msg.dup
+          if static_msg.key?(:content) || !static_msg.key?('content')
+            static_msg[:content] = parts[:static]
+          else
+            static_msg['content'] = parts[:static]
+          end
+
+          dynamic_msg = if msg.key?(:role) || !msg.key?('role')
+                          { role: role, content: parts[:dynamic] }
+                        else
+                          { 'role' => role, 'content' => parts[:dynamic] }
+                        end
+
+          messages[idx, 1] = [static_msg, dynamic_msg]
+          messages
+        rescue StandardError
+          Array(opts[:messages])
+        end
+
+        # Supported Method Parameters::
+        # inst = PWN::AI::Agent::PromptCache.gemini_system_instruction(text: system_prompt)
+        #
+        # → { parts: [{text: static}, {text: dynamic}] }  (empty omitted)
+
+        public_class_method def self.gemini_system_instruction(opts = {})
+          parts = split_system(text: opts[:text])
+          out = []
+          out << { text: parts[:static] } unless parts[:static].to_s.strip.empty?
+          out << { text: parts[:dynamic] } unless parts[:dynamic].to_s.strip.empty?
+          return nil if out.empty?
+
+          { parts: out }
+        rescue StandardError
+          txt = opts[:text].to_s
+          return nil if txt.strip.empty?
+
+          { parts: [{ text: txt }] }
+        end
+
+        # Supported Method Parameters::
+        # key = PWN::AI::Agent::PromptCache.cache_key(text: system_prompt)
+        # key = PWN::AI::Agent::PromptCache.cache_key(key: 'explicit-override')
+        #
+        # Stable OpenAI prompt_cache_key / xAI x-grok-conv-id. Hashes the
+        # static prefix so MEMORY / LEARNING churn does not rotate the key.
+
+        public_class_method def self.cache_key(opts = {})
+          explicit = opts[:key]
+          return explicit.to_s unless explicit.to_s.strip.empty?
+
+          raw = opts[:text].to_s
+          static = raw.empty? ? '' : split_system(text: raw)[:static].to_s
+          static = raw if static.strip.empty?
+          static = 'pwn-ai' if static.strip.empty?
+          "pwn-#{Digest::SHA256.hexdigest(static)[0, 24]}"
+        rescue StandardError
+          'pwn-ai'
+        end
+
+        # Supported Method Parameters::
+        # n = PWN::AI::Agent::PromptCache.cache_marks(blocks: [...])
+
+        public_class_method def self.cache_marks(opts = {})
+          Array(opts[:blocks]).count do |b|
+            next false unless b.is_a?(Hash)
+
+            cc = b[:cache_control] || b['cache_control']
+            cc.is_a?(Hash) && (cc[:type] || cc['type']).to_s == 'ephemeral'
+          end
+        end
+
+        public_class_method def self.supports
+          %i[anthropic openai grok gemini]
+        end
+
+        public_class_method def self.authors
+          "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+        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
+        end
+
+        private_class_method def self.first_dynamic_index(opts = {})
+          text = opts[:text].to_s
+          idxs = DYNAMIC_HEADS.filter_map do |head|
+            i = text.index(/^#{Regexp.escape(head)}\b/)
+            i
+          end
+          idxs.min
+        end
+
+        private_class_method def self.extract_skills(opts = {})
+          text = opts[:text].to_s
+          m = text.match(%r{^SKILLS[^\n]*\n(?:.*\n)*?(?=\n[A-Z][A-Z /]|\z)})
+          m ? m[0] : ''
+        rescue StandardError
+          ''
+        end
+
+        private_class_method def self.active_engine
+          return :openai unless defined?(PWN::Env) && PWN::Env.is_a?(Hash)
+
+          PWN::Env.dig(:ai, :active).to_s.downcase.to_sym
+        rescue StandardError
+          :openai
+        end
+
+        private_class_method def self.agent_flag(opts = {})
+          key = opts[:key]
+          default = opts[:default]
+          return default unless defined?(PWN::Env)
+
+          val = PWN::Env.dig(:ai, :agent, key)
+          val.nil? ? default : val
+        rescue StandardError
+          opts[:default]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module PWN
+  module AI
+    module Agent
+      # Hermes-style post-reply learning. Loop.run returns the user-visible
+      # answer first; Reward / Policy / Curriculum keep running off that path.
+      #
+      # User-visible turn (Loop.run)
+      #   tools, streaming, TaskSummarizer, final text
+      # After the reply is already decided
+      #   TurnFinalizer.defer -> daemon thread
+      #     re-attaches the R5 episode snapshot
+      #     Learning.auto_introspect (critic, Reward.judge, PRM, HER, reflect)
+      #
+      # Default ON during Loop.run (PWN::Env[:ai][:agent][:defer_introspect]).
+      # Direct Learning.auto_introspect calls (specs, cron, tools) stay inline
+      # so existing ORM contracts still get a synchronous return value.
+      module TurnFinalizer
+        MUTEX = Mutex.new
+        THREADS = [] # rubocop:disable Style/MutableConstant
+        MAX_TRACKED = 16
+        DEPTH_KEY = :pwn_turn_finalizer_depth
+        INLINE_KEY = :pwn_turn_finalizer_inline
+        SYNC_KEY = :pwn_turn_finalizer_sync
+
+        # Supported Method Parameters::
+        # PWN::AI::Agent::TurnFinalizer.enter_user_path!
+
+        public_class_method def self.enter_user_path!
+          Thread.current[DEPTH_KEY] = Thread.current[DEPTH_KEY].to_i + 1
+        end
+
+        # Supported Method Parameters::
+        # PWN::AI::Agent::TurnFinalizer.leave_user_path!
+
+        public_class_method def self.leave_user_path!
+          depth = Thread.current[DEPTH_KEY].to_i - 1
+          Thread.current[DEPTH_KEY] = depth.positive? ? depth : 0
+        end
+
+        public_class_method def self.user_path?
+          Thread.current[DEPTH_KEY].to_i.positive?
+        end
+
+        # Supported Method Parameters::
+        # ok = PWN::AI::Agent::TurnFinalizer.should_defer?
+
+        public_class_method def self.should_defer?
+          return false if Thread.current[INLINE_KEY]
+          return false if Thread.current[SYNC_KEY]
+          return false unless user_path?
+
+          flag = agent_flag(key: :defer_introspect, default: true)
+          return false if flag == false || flag.to_s.match?(/\A(0|false|no|off)\z/i)
+
+          true
+        rescue StandardError
+          false
+        end
+
+        # Supported Method Parameters::
+        # result = PWN::AI::Agent::TurnFinalizer.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'
+        # )
+        #
+        # Snapshots the live Policy episode onto this thread, clears it so
+        # Loop.maybe_finish_policy is a no-op, and runs Learning.auto_introspect
+        # on a daemon thread with the episode re-attached.
+
+        public_class_method def self.defer(opts = {})
+          session_id = opts[:session_id]
+          return { skipped: :no_session } if session_id.to_s.strip.empty?
+          return { skipped: :no_learning } unless defined?(Learning)
+
+          episode = nil
+          episode = Policy.detach_episode! if defined?(Policy) && Policy.respond_to?(:detach_episode!)
+
+          payload = {
+            session_id: session_id,
+            request: opts[:request],
+            final: opts[:final],
+            predicted: opts[:predicted],
+            plan: opts[:plan],
+            ts_state: opts[:ts_state],
+            inline: true
+          }
+
+          worker = Thread.new do
+            Thread.current[INLINE_KEY] = true
+            begin
+              Policy.attach_episode!(episode: episode) if defined?(Policy) && Policy.respond_to?(:attach_episode!)
+              Learning.auto_introspect(payload)
+            rescue StandardError => e
+              warn "[pwn-ai/turn_finalizer] background review swallowed: #{e.class}: #{e.message}"
+              nil
+            ensure
+              leftover = defined?(Policy) && Policy.respond_to?(:current_episode) && Policy.current_episode
+              if leftover && Policy.respond_to?(:finish)
+                Policy.finish(
+                  session_id: session_id,
+                  proxy_ok: false,
+                  final: payload[:final],
+                  ts_state: payload[:ts_state]
+                )
+              elsif defined?(Policy) && Policy.respond_to?(:attach_episode!)
+                Policy.attach_episode!(episode: nil)
+              end
+            end
+          end
+          worker.report_on_exception = false
+          begin
+            worker.name = 'pwn-turn-finalizer'
+          rescue StandardError
+            nil
+          end
+          track(thr: worker)
+          { deferred: true, session_id: session_id, thread_id: worker.object_id }
+        rescue StandardError => e
+          warn "[pwn-ai/turn_finalizer] defer swallowed: #{e.class}: #{e.message}"
+          # Never drop the learner — fall back to inline review.
+          opts_inline = opts.merge(inline: true)
+          defined?(Learning) ? Learning.auto_introspect(opts_inline) : { error: e.message }
+        end
+
+        # Supported Method Parameters::
+        # result = PWN::AI::Agent::TurnFinalizer.finalize(
+        #   session_id:, request:, final:, predicted:, plan:, ts_state:,
+        #   should: true|false
+        # )
+        #
+        # Single entry used when a caller wants the Hermes split without
+        # going through Learning.auto_introspect's gate.
+
+        public_class_method def self.finalize(opts = {})
+          return { skipped: :gated } unless opts.fetch(:should, true)
+          return { skipped: :no_learning } unless defined?(Learning)
+
+          if should_defer?
+            defer(opts)
+          else
+            Learning.auto_introspect(opts.merge(inline: true))
+          end
+        rescue StandardError => e
+          warn "[pwn-ai/turn_finalizer] finalize swallowed: #{e.class}: #{e.message}"
+          nil
+        end
+
+        # Supported Method Parameters::
+        # n = PWN::AI::Agent::TurnFinalizer.join_all!(timeout: 15)
+
+        public_class_method def self.join_all!(opts = {})
+          timeout = (opts[:timeout] || 15).to_f
+          list = MUTEX.synchronize do
+            pending = THREADS.dup
+            THREADS.clear
+            pending
+          end
+          list.each do |thr|
+            thr.join(timeout) if thr.alive?
+          rescue StandardError
+            nil
+          end
+          list.length
+        end
+
+        # Supported Method Parameters::
+        # n = PWN::AI::Agent::TurnFinalizer.pending
+
+        public_class_method def self.pending
+          MUTEX.synchronize { THREADS.count(&:alive?) }
+        end
+
+        public_class_method def self.authors
+          "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+        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
+        end
+
+        private_class_method def self.track(opts = {})
+          thr = opts[:thr]
+          MUTEX.synchronize do
+            THREADS.select!(&:alive?)
+            THREADS << thr
+            THREADS.shift&.kill if THREADS.length > MAX_TRACKED
+          end
+        rescue StandardError
+          nil
+        end
+
+        private_class_method def self.agent_flag(opts = {})
+          key = opts[:key]
+          default = opts[:default]
+          return default unless defined?(PWN::Env)
+
+          val = PWN::Env.dig(:ai, :agent, key)
+          val.nil? ? default : val
+        rescue StandardError
+          opts[:default]
+        end
+      end
+    end
+  end
+end

data/lib/pwn/ai/agent.rb

@@ -34,6 +34,8 @@ module PWN
       autoload :TaskSummarizer, 'pwn/ai/agent/task_summarizer'
       autoload :Policy, 'pwn/ai/agent/policy'
       autoload :ToolGuard, 'pwn/ai/agent/tool_guard'
+      autoload :TurnFinalizer, 'pwn/ai/agent/turn_finalizer'
+      autoload :PromptCache, 'pwn/ai/agent/prompt_cache'
 
       # Display a List of Every PWN::AI Module
 

data/lib/pwn/ai/anthropic.rb

@@ -657,7 +657,17 @@ module PWN
           temperature: temp,
           messages: anth_messages
         }
-        http_body[:system] = system_str if system_str && !system_str.empty?
+        if system_str && !system_str.empty?
+          # Hermes-style cache breakpoint on the static system prefix + SKILLS
+          # index. Dynamic MEMORY/LEARNING stay in a second uncached block.
+          if defined?(PWN::AI::Agent::PromptCache) &&
+             PWN::AI::Agent::PromptCache.enabled?(engine: :anthropic)
+            blocks = PWN::AI::Agent::PromptCache.anthropic_system_blocks(text: system_str)
+            http_body[:system] = blocks unless blocks.empty?
+          else
+            http_body[:system] = system_str
+          end
+        end
 
         if opts[:tools] && !opts[:tools].empty?
           http_body[:tools] = opts[:tools].map do |t|

data/lib/pwn/ai/gemini.rb

@@ -179,7 +179,15 @@ module PWN
             maxOutputTokens: opts[:max_tokens] || 8192
           }
         }
-        http_body[:systemInstruction] = { parts: [{ text: system_str }] } if system_str && !system_str.empty?
+        if system_str && !system_str.empty?
+          if defined?(PWN::AI::Agent::PromptCache) &&
+             PWN::AI::Agent::PromptCache.enabled?(engine: :gemini)
+            inst = PWN::AI::Agent::PromptCache.gemini_system_instruction(text: system_str)
+            http_body[:systemInstruction] = inst if inst
+          else
+            http_body[:systemInstruction] = { parts: [{ text: system_str }] }
+          end
+        end
 
         if opts[:tools] && !opts[:tools].empty?
           http_body[:tools] = [{