pwn 0.5.615 → 0.5.617

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+require 'pwn/cron'
+
+# Thin wrappers around PWN::Cron so the model can schedule, inspect, run,
+# enable/disable and remove recurring pwn-ai jobs (~/.pwn/cron/jobs.yml).
+# Jobs may carry a pwn-ai `prompt`, a `ruby` snippet, or an external
+# `script` path; system-cron installation is opt-in via :install_crontab.
+
+PWN::AI::Agent::Registry.register(
+  name: 'cron_list',
+  toolset: 'cron',
+  schema: {
+    name: 'cron_list',
+    description: 'List all pwn-ai cron jobs from ~/.pwn/cron/jobs.yml ' \
+                 '(id, name, schedule, enabled, last_run, last_status).',
+    parameters: { type: 'object', properties: {}, required: [] }
+  },
+  check: -> { defined?(PWN::Cron) },
+  handler: lambda { |_args|
+    PWN::Cron.list.map do |id, job|
+      {
+        id: id,
+        name: job[:name],
+        schedule: job[:schedule],
+        enabled: job[:enabled],
+        delivery: job[:delivery],
+        prompt: job[:prompt].to_s[0, 120],
+        ruby: job[:ruby].to_s[0, 120],
+        script: job[:script],
+        last_run: job[:last_run],
+        last_status: job[:last_status]
+      }
+    end
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'cron_create',
+  toolset: 'cron',
+  schema: {
+    name: 'cron_create',
+    description: 'Create a scheduled pwn-ai job. Provide exactly one of ' \
+                 'prompt (sent to the active AI engine), ruby (evaluated ' \
+                 'in-process), or script (external path). Set ' \
+                 'install_crontab:true to also append a system crontab ' \
+                 'entry that invokes PWN::Cron.run for this job id.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Human-friendly job name (default job-<id>).' },
+        schedule: {
+          type: 'string',
+          description: 'Cron expression, e.g. "0 * * * *". Required when ' \
+                       'install_crontab is true; otherwise informational.'
+        },
+        prompt: { type: 'string', description: 'pwn-ai prompt to run against the active engine.' },
+        ruby: { type: 'string', description: 'Ruby snippet evaluated in TOPLEVEL_BINDING.' },
+        script: { type: 'string', description: 'Path to an external executable script.' },
+        delivery: { type: 'string', enum: %w[log stdout], default: 'log' },
+        enabled: { type: 'boolean', default: true },
+        install_crontab: {
+          type: 'boolean',
+          default: false,
+          description: 'Also append a `crontab -l` entry that runs this job id via pwn.'
+        }
+      },
+      required: %w[schedule]
+    }
+  },
+  check: -> { defined?(PWN::Cron) },
+  handler: lambda { |args|
+    PWN::Cron.create(
+      name: args[:name],
+      schedule: args[:schedule],
+      prompt: args[:prompt],
+      ruby: args[:ruby],
+      script: args[:script],
+      delivery: args[:delivery],
+      enabled: args.fetch(:enabled, true),
+      install_crontab: args[:install_crontab]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'cron_run',
+  toolset: 'cron',
+  schema: {
+    name: 'cron_run',
+    description: 'Execute a cron job immediately by id (or name) and ' \
+                 'return { job:, result:, duration:, status: }. Updates ' \
+                 'last_run / last_status in jobs.yml.',
+    parameters: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Job id or job name.' }
+      },
+      required: %w[id]
+    }
+  },
+  check: -> { defined?(PWN::Cron) },
+  handler: lambda { |args|
+    PWN::Cron.run(id: args[:id])
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'cron_enable',
+  toolset: 'cron',
+  schema: {
+    name: 'cron_enable',
+    description: 'Set enabled:true on a cron job by id.',
+    parameters: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: %w[id]
+    }
+  },
+  check: -> { defined?(PWN::Cron) },
+  handler: lambda { |args|
+    { id: args[:id], job: PWN::Cron.enable(id: args[:id]) }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'cron_disable',
+  toolset: 'cron',
+  schema: {
+    name: 'cron_disable',
+    description: 'Set enabled:false on a cron job by id.',
+    parameters: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: %w[id]
+    }
+  },
+  check: -> { defined?(PWN::Cron) },
+  handler: lambda { |args|
+    { id: args[:id], job: PWN::Cron.disable(id: args[:id]) }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'cron_remove',
+  toolset: 'cron',
+  schema: {
+    name: 'cron_remove',
+    description: 'Delete a cron job by id from ~/.pwn/cron/jobs.yml. ' \
+                 'Does NOT scrub any system crontab entry — remove that ' \
+                 'manually with `crontab -e` if install_crontab was used.',
+    parameters: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: %w[id]
+    }
+  },
+  check: -> { defined?(PWN::Cron) },
+  handler: lambda { |args|
+    { id: args[:id], removed: PWN::Cron.remove(id: args[:id]) }
+  }
+)

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

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+require 'pwn/ai/agent/extrospection'
+
+# Expose the OUTWARD-facing half of the pwn-ai learning feedback loop to
+# the model. Where the `learning_*` / `metrics_*` tools are INTROSPECTIVE
+# (self-telemetry, own outcomes, own transcripts), the `extro_*` tools are
+# EXTROSPECTIVE: they probe, record and reason about the WORLD the agent
+# operates in — host state, toolchain versions, network posture, repo
+# drift, recon findings, and external threat-intel — and correlate that
+# world-state back against introspective failures. Together they close
+# BOTH halves of the feedback loop.
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_snapshot',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_snapshot',
+    description: 'Capture a fingerprint of the OUTSIDE world (host, kernel, ' \
+                 'distro, network interfaces, listening ports, toolchain ' \
+                 'binary versions, pwn repo HEAD, ruby/engine env) and ' \
+                 'persist it to ~/.pwn/extrospection.json. Returns ' \
+                 '{snapshot:, drift:} where drift is the delta vs the ' \
+                 'PREVIOUS snapshot. Run at the start of an engagement and ' \
+                 'after any host change so extro_drift / extro_correlate ' \
+                 'have a baseline.',
+    parameters: {
+      type: 'object',
+      properties: {
+        persist: { type: 'boolean', default: true, description: 'Write to disk & rotate previous baseline.' },
+        sections: { type: 'array', items: { type: 'string', enum: %w[host net toolchain repo env] }, description: 'Subset of probes to run (default all).' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Extrospection) },
+  handler: lambda { |args|
+    o = {}
+    o[:persist]  = args[:persist]  if args.key?(:persist)
+    o[:sections] = args[:sections] if args.key?(:sections)
+    PWN::AI::Agent::Extrospection.snapshot(o)
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_drift',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_drift',
+    description: 'Diff the current host/toolchain/network/repo state ' \
+                 'against the last persisted snapshot. Returns ' \
+                 '{changed:[], added:[], removed:[]} with dotted-path keys ' \
+                 '(e.g. "toolchain.nmap", "net.listening", "repo.head"). ' \
+                 'Use to detect when the environment moved under you ' \
+                 'between sessions before trusting introspective metrics.',
+    parameters: {
+      type: 'object',
+      properties: {
+        live: { type: 'boolean', default: true, description: 'true = probe NOW vs stored snapshot; false = stored snapshot vs stored previous.' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Extrospection) },
+  handler: lambda { |args|
+    o = {}
+    o[:live] = args[:live] if args.key?(:live)
+    PWN::AI::Agent::Extrospection.drift(o)
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_observe',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_observe',
+    description: 'Record a fact about the OUTSIDE world (recon finding, ' \
+                 'service banner, target fingerprint, CVE match, network ' \
+                 'topology note). This is the extrospective analogue of ' \
+                 'learning_note_outcome — it persists WHAT YOU SAW rather ' \
+                 'than HOW YOU PERFORMED. Observations are re-injected into ' \
+                 'every future system prompt via the EXTROSPECTION block.',
+    parameters: {
+      type: 'object',
+      properties: {
+        source: { type: 'string', description: 'Where it came from (nmap, shodan, burp, cve, human, ...).' },
+        data: { type: 'string', description: 'The observation itself.' },
+        category: { type: 'string', enum: %w[recon vuln intel target network env misc], default: 'misc' },
+        target: { type: 'string', description: 'Host / IP / URL / asset the observation is about.' },
+        tags: { type: 'array', items: { type: 'string' } },
+        ttl: { type: 'integer', description: 'Seconds until stale (omit = forever).' }
+      },
+      required: %w[source data]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Extrospection) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Extrospection.observe(
+      source: args[:source],
+      data: args[:data],
+      category: args[:category],
+      target: args[:target],
+      tags: args[:tags],
+      ttl: args[:ttl]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_observations',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_observations',
+    description: 'Query recorded external observations from ' \
+                 '~/.pwn/extrospection.json (the read-side of ' \
+                 'extro_observe). Filter by source / category / target / ' \
+                 'tag; newest-first. Use to recall recon findings and ' \
+                 'threat-intel captured in prior sessions.',
+    parameters: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', default: 50 },
+        source: { type: 'string' },
+        category: { type: 'string' },
+        target: { type: 'string' },
+        tag: { type: 'string' },
+        fresh_only: { type: 'boolean', default: false, description: 'Drop entries whose TTL has expired.' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Extrospection) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Extrospection.observations(
+      limit: args[:limit] || 50,
+      source: args[:source],
+      category: args[:category],
+      target: args[:target],
+      tag: args[:tag],
+      fresh_only: args[:fresh_only]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_intel',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_intel',
+    description: 'Query external threat-intelligence feeds (NVD CVE API, ' \
+                 'CIRCL CVE-Search, local searchsploit / Exploit-DB) for a ' \
+                 'keyword, product, or CVE id. Best-effort: any feed that ' \
+                 'is unreachable degrades to []. Set record:true to also ' \
+                 'persist each hit as an :intel observation so ' \
+                 'extro_correlate can match it against installed toolchain ' \
+                 'versions on this host.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Keyword / product+version / CVE-YYYY-NNNN.' },
+        feeds: { type: 'array', items: { type: 'string', enum: %w[nvd circl exploitdb] } },
+        limit: { type: 'integer', default: 5 },
+        record: { type: 'boolean', default: false }
+      },
+      required: %w[query]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Extrospection) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Extrospection.intel(
+      query: args[:query],
+      feeds: args[:feeds],
+      limit: args[:limit],
+      record: args[:record]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_correlate',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_correlate',
+    description: 'THE join between introspection and extrospection. ' \
+                 'Cross-references (a) Metrics tools with <50 % success ' \
+                 'against toolchain drift / missing binaries, (b) Learning ' \
+                 'failures against host/net/repo drift on the same day, ' \
+                 '(c) recorded :intel observations against installed ' \
+                 'component versions. Returns actionable findings so the ' \
+                 'agent can distinguish "I did it wrong" from "the world ' \
+                 'changed under me".',
+    parameters: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', default: 10 }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Extrospection) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Extrospection.correlate(limit: args[:limit] || 10)
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_stats',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_stats',
+    description: 'Return world-awareness metrics: snapshot age & ' \
+                 'fingerprint, observation count, drift counts ' \
+                 '(changed/added/removed since previous), toolchain bins ' \
+                 'present, listening-port count. The extrospective ' \
+                 'counterpart to learning_stats.',
+    parameters: { type: 'object', properties: {}, required: [] }
+  },
+  check: -> { defined?(PWN::AI::Agent::Extrospection) },
+  handler: ->(_args) { PWN::AI::Agent::Extrospection.stats }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_reset',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_reset',
+    description: 'Wipe ~/.pwn/extrospection.json (snapshot, previous ' \
+                 'baseline, and ALL recorded observations). Use when ' \
+                 'moving to a new engagement / target scope so stale recon ' \
+                 'and drift stop polluting the EXTROSPECTION prompt block. ' \
+                 'IRREVERSIBLE — must pass confirm:true.',
+    parameters: {
+      type: 'object',
+      properties: {
+        confirm: { type: 'boolean', description: 'Must be true to actually reset.' }
+      },
+      required: %w[confirm]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Extrospection) },
+  handler: lambda { |args|
+    raise ArgumentError, 'refusing to reset extrospection without confirm:true' unless args[:confirm] == true
+
+    before = PWN::AI::Agent::Extrospection.stats
+    PWN::AI::Agent::Extrospection.reset
+    { reset: true, cleared: before, file: PWN::AI::Agent::Extrospection::EXTRO_FILE }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'extro_auto_toggle',
+  toolset: 'extrospection',
+  schema: {
+    name: 'extro_auto_toggle',
+    description: 'Enable/disable end-of-run auto-extrospection ' \
+                 '(PWN::Env[:ai][:agent][:auto_extrospect]). When enabled, ' \
+                 'Learning.auto_reflect ALSO calls Extrospection.auto_' \
+                 'extrospect after every final answer, so host drift is ' \
+                 'captured continuously without an explicit extro_snapshot ' \
+                 'call. Omit `enabled` to just read the current state.',
+    parameters: {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean', description: 'Desired state. Omit to only query.' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::Env) && PWN::Env.is_a?(Hash) },
+  handler: lambda { |args|
+    ai = PWN::Env[:ai]
+    raise 'PWN::Env[:ai] is unavailable or immutable' unless ai.is_a?(Hash) && !ai.frozen?
+
+    ai[:agent] = (ai[:agent] || {}).dup if ai[:agent].nil? || ai[:agent].frozen?
+    prev = ai[:agent][:auto_extrospect] ? true : false
+    ai[:agent][:auto_extrospect] = (args[:enabled] ? true : false) if args.key?(:enabled)
+    { previous: prev, current: ai[:agent][:auto_extrospect] ? true : false }
+  }
+)

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

@@ -111,3 +111,111 @@ PWN::AI::Agent::Registry.register(
     )
   }
 )
+
+PWN::AI::Agent::Registry.register(
+  name: 'learning_outcomes',
+  toolset: 'learning',
+  schema: {
+    name: 'learning_outcomes',
+    description: 'Query recorded task outcomes from ~/.pwn/learning.jsonl ' \
+                 '(the read-side of learning_note_outcome). Filter by ' \
+                 'success and/or tag substring; returns newest-first.',
+    parameters: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', default: 50, description: 'Max entries returned newest-first.' },
+        success: { type: 'boolean', description: 'Filter: only successes (true) or only failures (false). Omit for both.' },
+        tag: { type: 'string', description: 'Filter: substring match against outcome tags.' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Learning) },
+  handler: lambda { |args|
+    o = { limit: args[:limit] || 50 }
+    o[:success] = args[:success] if args.key?(:success)
+    o[:tag]     = args[:tag]     if args.key?(:tag)
+    PWN::AI::Agent::Learning.outcomes(o)
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'learning_consolidate',
+  toolset: 'learning',
+  schema: {
+    name: 'learning_consolidate',
+    description: 'Deduplicate near-identical PWN::Memory lesson entries and ' \
+                 'prune the oldest ones once max_entries is exceeded, so the ' \
+                 'injected MEMORY block in every system prompt stays ' \
+                 'high-signal. Returns { removed:, remaining: }.',
+    parameters: {
+      type: 'object',
+      properties: {
+        max_entries: { type: 'integer', default: 200, description: 'Hard cap on PWN::Memory size after consolidation.' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Learning) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Learning.consolidate(max_entries: args[:max_entries])
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'learning_reset',
+  toolset: 'learning',
+  schema: {
+    name: 'learning_reset',
+    description: 'Wipe ~/.pwn/learning.jsonl (all recorded task outcomes and ' \
+                 'their success_rate). Use for a clean slate after major ' \
+                 'refactors or when dev-experiment noise has polluted the ' \
+                 'outcome history. IRREVERSIBLE — must pass confirm:true.',
+    parameters: {
+      type: 'object',
+      properties: {
+        confirm: { type: 'boolean', description: 'Must be true to actually reset.' }
+      },
+      required: %w[confirm]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Learning) },
+  handler: lambda { |args|
+    raise ArgumentError, 'refusing to reset learning without confirm:true' unless args[:confirm] == true
+
+    before = PWN::AI::Agent::Learning.outcomes(limit: 100_000).length
+    PWN::AI::Agent::Learning.reset
+    { reset: true, outcomes_cleared: before, file: PWN::AI::Agent::Learning::LEARNING_FILE }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'learning_auto_reflect_toggle',
+  toolset: 'learning',
+  schema: {
+    name: 'learning_auto_reflect_toggle',
+    description: 'Enable/disable end-of-run auto-reflection ' \
+                 '(PWN::Env[:ai][:agent][:auto_reflect]). When enabled, ' \
+                 'Loop.run calls Learning.auto_reflect on the session after ' \
+                 'every final answer. Disable during noisy fuzzing loops; ' \
+                 're-enable for the summary turn. Omit `enabled` to just ' \
+                 'read the current state.',
+    parameters: {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean', description: 'Desired state. Omit to only query.' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::Env) && PWN::Env.is_a?(Hash) },
+  handler: lambda { |args|
+    ai = PWN::Env[:ai]
+    raise 'PWN::Env[:ai] is unavailable or immutable' unless ai.is_a?(Hash) && !ai.frozen?
+
+    ai[:agent] = (ai[:agent] || {}).dup if ai[:agent].nil? || ai[:agent].frozen?
+    prev = ai[:agent][:auto_reflect] ? true : false
+    ai[:agent][:auto_reflect] = (args[:enabled] ? true : false) if args.key?(:enabled)
+    { previous: prev, current: ai[:agent][:auto_reflect] ? true : false }
+  }
+)

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

@@ -73,3 +73,30 @@ PWN::AI::Agent::Registry.register(
     { forgotten: args[:key] }
   }
 )
+
+PWN::AI::Agent::Registry.register(
+  name: 'memory_clear',
+  toolset: 'memory',
+  schema: {
+    name: 'memory_clear',
+    description: 'Wipe ALL persistent memory (~/.pwn/memory.json) — every ' \
+                 'fact, preference, lesson and env entry. Use only for a ' \
+                 'poisoned-context reset. IRREVERSIBLE — must pass ' \
+                 'confirm:true.',
+    parameters: {
+      type: 'object',
+      properties: {
+        confirm: { type: 'boolean', description: 'Must be true to actually clear.' }
+      },
+      required: %w[confirm]
+    }
+  },
+  check: -> { defined?(PWN::Memory) },
+  handler: lambda { |args|
+    raise ArgumentError, 'refusing to clear memory without confirm:true' unless args[:confirm] == true
+
+    before = PWN::Memory.load.keys.length
+    PWN::Memory.clear
+    { cleared: true, entries_removed: before, file: PWN::Memory::MEMORY_FILE }
+  }
+)

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+require 'pwn/ai/agent/metrics'
+
+# Direct access to the per-tool telemetry store (~/.pwn/metrics.json).
+# `learning_stats` already surfaces a compact metrics blob, but the model
+# needs a way to (a) pull the full table without dragging outcome/skill/
+# memory counts along, and (b) RESET stale telemetry after a broken tool
+# is fixed — otherwise a historical 0 %-success row actively mis-teaches
+# tool selection on every future turn.
+
+PWN::AI::Agent::Registry.register(
+  name: 'metrics_summary',
+  toolset: 'metrics',
+  schema: {
+    name: 'metrics_summary',
+    description: 'Return per-tool telemetry from ~/.pwn/metrics.json ' \
+                 '(name, calls, success_rate, avg_duration, last_error, ' \
+                 'last_at) sorted by call volume. Lighter-weight than ' \
+                 'learning_stats when you only need tool effectiveness.',
+    parameters: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', default: 25, description: 'Max tool rows to return.' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Metrics) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Metrics.summary(limit: args[:limit] || 25)
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'metrics_reset',
+  toolset: 'metrics',
+  schema: {
+    name: 'metrics_reset',
+    description: 'Wipe ~/.pwn/metrics.json (all per-tool call/success/duration ' \
+                 'counters). Use after fixing a previously-broken tool so its ' \
+                 'stale 0 %-success rate stops steering the agent away from ' \
+                 'it. IRREVERSIBLE — must pass confirm:true.',
+    parameters: {
+      type: 'object',
+      properties: {
+        confirm: { type: 'boolean', description: 'Must be true to actually reset.' }
+      },
+      required: %w[confirm]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Metrics) },
+  handler: lambda { |args|
+    raise ArgumentError, 'refusing to reset metrics without confirm:true' unless args[:confirm] == true
+
+    before = PWN::AI::Agent::Metrics.summary(limit: 1_000).length
+    PWN::AI::Agent::Metrics.reset
+    { reset: true, tools_cleared: before, file: PWN::AI::Agent::Metrics::METRICS_FILE }
+  }
+)