pwn 0.5.673 → 0.5.675

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9640ee1c83ff54dc1e10246d519a448d648806e30b35b579284b23708b5b9924
-  data.tar.gz: 2cbd3b2296d32ad6d068d276c3badbfa599065c668bbec7ac58fa2baf84651d7
+  metadata.gz: 2ed5f171854df678e76d477ad52fee2dd42e1687afc6e950281d2b3e5fe75ab9
+  data.tar.gz: 35712ab0300a98de2dfc52430278088561b84fcd15e4dd70a3c95cd90ccf4645
 SHA512:
-  metadata.gz: fa11ac68afcc6cde52bc207526a50cf53283ac59dd89340f25f303329562e7d34c7a02cbd286ca6fe34fffcaa307a9b0e3f9c03c03c89dca3788f9150f702f0a
-  data.tar.gz: c9bd66494f36503ba864a7c97af7d7a77b2d9502a502ed04c897ce08e2e693982efe79a43abc4c12d95e1d4b4b97ea3a1ec6fba61b0711599e025bcc2b19618d
+  metadata.gz: 563ee1d396728ef91353cfc4e6d82da6b90662d03e55d1c027319203e47a8bd91d9c723a09cda3a6836dc9b1ed380bb3e0bb76d802dd23157ff7c92d52a3958b
+  data.tar.gz: 05e3c313c8262273f5799f24a9359b3cadc5448ccebfc5ae031a99a71865b548d24489208f4b7be6e0d4790485ebcc58d35a3ccdafbfddfecdb27eaddd531b9c

data/Gemfile

@@ -49,7 +49,7 @@ gem 'jwt', '3.2.0'
 gem 'libusb', '0.8.0'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
-gem 'mcp', '1.1.0'
+gem 'mcp', '1.2.0'
 gem 'meshtastic', '0.0.173'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.25.0'

data/README.md

@@ -34,7 +34,7 @@ Red teamers, pentesters, and vulnerability researchers get one place to script
 and automate instead of gluing together a pile of separate CLIs.
 
 **In numbers:** 66 `PWN::Plugins` · 48 `PWN::SAST` rules · 90 `PWN::AWS`
-service wrappers · 21 `PWN::WWW` site drivers · 53 `bin/pwn_*` CLI drivers ·
+service wrappers · 22 `PWN::WWW` site drivers · 53 `bin/pwn_*` CLI drivers ·
 6 LLM engines · 13 agent toolsets · 85 LLM-callable tools.
 
 Full page: [What is PWN](documentation/What-is-PWN.md)
@@ -139,7 +139,7 @@ The complete wiki lives in this repo at **[`documentation/Home.md`](documentatio
 | [What is PWN](documentation/What-is-PWN.md) | [`pwn` REPL](documentation/pwn-REPL.md) | [AI / LLM Integration](documentation/AI-Integration.md) | [Plugins (66)](documentation/Plugins.md) |
 | [Why PWN](documentation/Why-PWN.md) | [`pwn-ai` Agent](documentation/pwn-ai-Agent.md) | [Agent Tool Registry](documentation/Agent-Tool-Registry.md) | [SAST (48)](documentation/SAST.md) |
 | [How PWN Works](documentation/How-PWN-Works.md) | [CLI Drivers (53)](documentation/CLI-Drivers.md) | [Memory · Skills · Learning](documentation/Skills-Memory-Learning.md) | [AWS (90)](documentation/AWS.md) |
-| [Installation](documentation/Installation.md) | [Build a Driver](documentation/Drivers.md) | [Mistakes (neg-feedback)](documentation/Mistakes.md) | [WWW (21)](documentation/WWW.md) |
+| [Installation](documentation/Installation.md) | [Build a Driver](documentation/Drivers.md) | [Mistakes (neg-feedback)](documentation/Mistakes.md) | [WWW (22)](documentation/WWW.md) |
 | [General Usage](documentation/General-PWN-Usage.md) | | [Reinforcement Learning](documentation/Reinforcement-Learning.md) | [SDR / Radio](documentation/SDR.md) |
 | [Configuration](documentation/Configuration.md) | | [Extrospection](documentation/Extrospection.md) | [Hardware](documentation/Hardware.md) |
 | [`~/.pwn/` Persistence](documentation/Persistence.md) | | [Swarm (multi-agent)](documentation/Swarm.md) | [Reports](documentation/Reporting.md) |

data/bin/pwn

@@ -51,9 +51,11 @@ begin
     # ------------------------------------------------------------------
     if opts[:setup] == true
       r = PWN::Setup.check
+      PWN::Setup.ensure_cron(restart: false)
       exit(r[:ok] ? 0 : 1)
     else
       PWN::Setup.deps(profile: opts[:setup])
+      PWN::Setup.ensure_cron(restart: false)
     end
   elsif opts[:ai]
     # ------------------------------------------------------------------

data/bin/pwn_ai_red_team

@@ -14,6 +14,10 @@ PWN::Driver::Parser.new do |options|
     opts[:target_model] = m
   end
 
+  options.on('-cCOUNT', '--payload-count=COUNT', '<Optional - Number of LLM-generated payloads per test case (Default 10)>') do |c|
+    opts[:payload_count] = c
+  end
+
   options.on('-rROLE', '--system-role=ROLE', '<Optional - System Prompt Applied to the Target for Every Payload>') do |r|
     opts[:system_role_content] = r
   end
@@ -60,6 +64,7 @@ begin
   target_engine = opts[:target_engine]
   target_model = opts[:target_model]
   system_role_content = opts[:system_role_content]
+  payload_count = (opts[:payload_count] || 10).to_i
 
   max_threads = opts[:max_threads]
   max_threads ||= 5
@@ -80,7 +85,6 @@ begin
       ExcessiveAgency
       InsecureOutputHandling
       Jailbreak
-      ModelDenialOfService
       Overreliance
       PayloadSplitting
       PromptInjection
@@ -115,7 +119,8 @@ begin
     ).scan(
       target_engine: target_engine,
       target_model: target_model,
-      system_role_content: system_role_content
+      system_role_content: system_role_content,
+      payload_count: payload_count
     )
 
     rt_arr.each { |hash_line| mutex.synchronize { results_hash[:data].push(hash_line) } }

data/bin/pwn_setup

@@ -59,6 +59,18 @@ pwn_driver.auto_opts_help = false
 pwn_driver.parse!
 
 begin
+  status = 0
+  # Seed default jobs + start/reuse the in-process scheduler so last_run
+  # actually advances. Do this BEFORE the doctor so `pwn setup` reports
+  # 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
+    )
+  end
+
   if opts[:list]
     PWN::Setup.list_profiles
   elsif opts[:migrate]
@@ -66,7 +78,7 @@ begin
       fix: opts[:fix] || opts[:yes],
       dry_run: opts[:dry_run]
     )
-    exit 1 unless r && r[:after] && r[:after][:incompatible].empty?
+    status = 1 unless r && r[:after] && r[:after][:incompatible].empty?
   elsif opts[:terminal]
     PWN::Setup.terminal(
       yes: opts[:yes],
@@ -83,8 +95,19 @@ begin
     # `pwn setup --check`               → same
     # `pwn setup --check --profile net` → gate ONLY on the :net profile
     r = PWN::Setup.check(profile: opts[:profile])
-    exit 1 unless r[:ok]
+    status = 1 unless r[:ok]
+  end
+
+  # Seed default jobs + start/reuse the in-process scheduler so
+  # 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
+    )
   end
+  exit status
 rescue Interrupt
   puts "\naborted."
   exit 130

data/documentation/Home.md

@@ -2,7 +2,7 @@
 
 > **PWN** (/pōn/) - an open-source offensive-security automation framework and
 > continuous-security-integration platform written in Ruby.
-> 66 plugins · 48 SAST rules · 90 AWS wrappers · 21 WWW drivers · 53 CLI
+> 66 plugins · 48 SAST rules · 90 AWS wrappers · 22 WWW drivers · 53 CLI
 > drivers · 6 LLM engines · a self-improving multi-agent AI · one REPL.
 
 **Repo root:** `/opt/pwn` · **This wiki:** `/opt/pwn/documentation/` ·
@@ -57,7 +57,7 @@
 |   ↳ [Fuzzing](Fuzzing.md) | `Fuzz` · `Sock` · `Packet` |
 |   ↳ [Hardware](Hardware.md) | Serial · BusPirate · MSR206 · Android · BareSIP |
 | [SAST (48 rules)](SAST.md) | Static analysis + test-case engine |
-| [WWW (21 drivers)](WWW.md) | Browser automations for real sites |
+| [WWW (22 drivers)](WWW.md) | Browser automations for real sites |
 | [AWS (90 services)](AWS.md) | Cloud-security enumeration |
 | [SDR](SDR.md) | GQRX · FlipperZero · RFIDler · SonMicro · **Decoder::* (20 protocols + Base/DSP)** · FFI-accelerated DSP |
 | [Blockchain](Blockchain.md) | BTC · ETH helpers |

data/documentation/How-PWN-Works.md

@@ -45,7 +45,7 @@ call, and [Reinforcement Learning](Reinforcement-Learning.md) for how
 
 ## L3 - Capability namespaces (`lib/pwn/*`)
 
-`Plugins` (66) · `SAST` (48) · `WWW` (21) · `AWS` (90) · `SDR` · `Blockchain` ·
+`Plugins` (66) · `SAST` (48) · `WWW` (22) · `AWS` (90) · `SDR` · `Blockchain` ·
 `Bounty` · `Reports` · `FFI` · `Banner` · **`Setup`** · **`Migrate`**. Each is
 a plain module of `public_class_method def self.x(opts = {})` methods -
 callable the same way from the REPL, from `pwn_eval`, or from a driver.

data/documentation/WWW.md

@@ -1,6 +1,6 @@
 # `PWN::WWW` - Site-Specific Browser Automations
 
-21 modules, each a scripted [`TransparentBrowser`](Transparent-Browser.md)
+22 modules, each a scripted [`TransparentBrowser`](Transparent-Browser.md)
 session against a real site: log in, navigate, scrape, submit.
 Source: `lib/pwn/www/*.rb`.
 
@@ -9,6 +9,7 @@ Source: `lib/pwn/www/*.rb`.
 | Category | Modules |
 |---|---|
 | **Bug bounty** | `HackerOne` · `BugCrowd` · `Synack` · `AppCobaltIO` |
+| **Code hosts** | `GitHub` |
 | **Search / OSINT** | `Google` · `Bing` · `DuckDuckGo` · `Torch` · `WaybackMachine` · `Pastebin` · `Checkip` |
 | **Social** | `Twitter` · `Facebook` · `LinkedIn` · `Youtube` · `Pandora` |
 | **Finance / Work** | `CoinbasePro` · `Paypal` · `TradingView` · `Uber` · `Upwork` |
@@ -16,14 +17,24 @@ Source: `lib/pwn/www/*.rb`.
 ## Pattern
 
 ```ruby
-b = PWN::WWW::HackerOne.open(browser_type: :headless,
-                             proxy: 'http://127.0.0.1:8080')
-PWN::WWW::HackerOne.login(browser_obj: b, username: '...', mfa: '...')
-# ... scripted navigation ...
-PWN::WWW::HackerOne.logout(browser_obj: b)
+b = PWN::WWW::GitHub.open(browser_type: :headless,
+                         proxy: 'http://127.0.0.1:8080')
+PWN::WWW::GitHub.login(
+  browser_obj: b,
+  username: '...',
+  password: '...',
+  mfa: '123456'
+)
+# scripted navigation
+PWN::WWW::GitHub.logout(browser_obj: b)
 PWN::Plugins::TransparentBrowser.close(browser_obj: b)
 ```
 
+`login` takes `username`, `password`, and an MFA token (`mfa:` or
+`mfa_token:`). Pass the token string to stay non-interactive, or set
+`mfa: true` to prompt. The browser stays on the post-auth GitHub session
+when the method returns.
+
 Because traffic goes through TransparentBrowser, you can point `proxy:` at
 [BurpSuite](BurpSuite.md) and passively capture every request the automation
 makes.

data/documentation/What-is-PWN.md

@@ -15,7 +15,7 @@ with a **tool-calling AI agent** on top that can run the same methods.
 | `PWN::Plugins::*` | **66** | Wrappers for external and native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, ...) |
 | `PWN::SAST::*` | **48** | Static-analysis rules across C/Java/Go/Python/Ruby/Scala/PHP/TS |
 | `PWN::AWS::*` | **90** | One module per AWS service for cloud enumeration |
-| `PWN::WWW::*` | **21** | Site-specific browser automations (HackerOne, BugCrowd, Google, LinkedIn, ...) |
+| `PWN::WWW::*` | **22** | Site-specific browser automations (HackerOne, BugCrowd, GitHub, Google, LinkedIn, ...) |
 | `PWN::SDR::*` | **6** (+ **20** protocol decoders + Base/DSP) | GQRX, FlipperZero, RFIDler, SonMicro, band tables, `Decoder::{ADSB,POCSAG,RDS,LoRa,...}` |
 | `PWN::FFI::*` | **8** | Native DSP/RF backends: Volk · Liquid · FFTW · RTLSdr · HackRF · AdalmPluto · SoapySDR · Stdio |
 | `PWN::AI::*` | **6** engines | OpenAI, Anthropic, Grok (OAuth device-flow), Gemini, Ollama, Open WebUI |

data/documentation/diagrams/dot/overall-pwn-architecture.dot

@@ -49,7 +49,7 @@ digraph "PWN_Overall_Architecture" {
     style=rounded; color="#047857"; bgcolor="#022c22"; penwidth=2;
     Plugins [label="Plugins\n66 modules",     fillcolor="#6ee7b7"];
     SAST    [label="SAST\n48 rules",          fillcolor="#6ee7b7"];
-    WWW     [label="WWW\n21 site drivers",    fillcolor="#6ee7b7"];
+    WWW     [label="WWW\n22 site drivers",    fillcolor="#6ee7b7"];
     AWS     [label="AWS\n90 services",        fillcolor="#6ee7b7"];
     SDR     [label="SDR\nGQRX · Flipper · RFID\nDecoder::* (20+Base/DSP)", fillcolor="#6ee7b7"];
     Chain   [label="Blockchain\nBTC · ETH",   fillcolor="#6ee7b7"];

data/documentation/diagrams/dot/web-application-testing.dot

@@ -17,7 +17,7 @@ digraph "PWN_Web" {
     color="#047857"; bgcolor="#022c22";
     TB     [label="TransparentBrowser\nheadless · watir · devtools", fillcolor="#6ee7b7"];
     Spider [label="Plugins::Spider\nURI buster",                     fillcolor="#6ee7b7"];
-    WWW    [label="PWN::WWW::*\n21 site drivers",                    fillcolor="#6ee7b7"];
+    WWW    [label="PWN::WWW::*\n22 site drivers",                    fillcolor="#6ee7b7"];
   }
   subgraph cluster_proxy {
     label="Intercept + Scan"; fontcolor="#fde68a"; style=rounded;

data/documentation/diagrams/overall-pwn-architecture.svg

@@ -219,7 +219,7 @@
 <title>WWW</title>
 <path fill="#6ee7b7" stroke="#334155" stroke-width="1.4" d="M495.38,-198.88C495.38,-198.88 436.62,-198.88 436.62,-198.88 430.62,-198.88 424.62,-192.88 424.62,-186.88 424.62,-186.88 424.62,-174.88 424.62,-174.88 424.62,-168.88 430.62,-162.88 436.62,-162.88 436.62,-162.88 495.38,-162.88 495.38,-162.88 501.38,-162.88 507.38,-168.88 507.38,-174.88 507.38,-174.88 507.38,-186.88 507.38,-186.88 507.38,-192.88 501.38,-198.88 495.38,-198.88"/>
 <text xml:space="preserve" text-anchor="middle" x="466" y="-183.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">WWW</text>
-<text xml:space="preserve" text-anchor="middle" x="466" y="-170.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">21 site drivers</text>
+<text xml:space="preserve" text-anchor="middle" x="466" y="-170.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">22 site drivers</text>
 </g>
 <!-- Registry&#45;&gt;WWW -->
 <g id="edge12" class="edge">

data/documentation/diagrams/web-application-testing.svg

@@ -64,7 +64,7 @@
 <title>WWW</title>
 <path fill="#6ee7b7" stroke="#334155" stroke-width="1.3" d="M256.25,-52C256.25,-52 196,-52 196,-52 190,-52 184,-46 184,-40 184,-40 184,-28 184,-28 184,-22 190,-16 196,-16 196,-16 256.25,-16 256.25,-16 262.25,-16 268.25,-22 268.25,-28 268.25,-28 268.25,-40 268.25,-40 268.25,-46 262.25,-52 256.25,-52"/>
 <text xml:space="preserve" text-anchor="middle" x="226.12" y="-36.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">PWN::WWW::*</text>
-<text xml:space="preserve" text-anchor="middle" x="226.12" y="-24.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">21 site drivers</text>
+<text xml:space="preserve" text-anchor="middle" x="226.12" y="-24.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">22 site drivers</text>
 </g>
 <!-- Target&#45;&gt;WWW -->
 <g id="edge3" class="edge">

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

@@ -1063,6 +1063,16 @@ module PWN
         # 3.2 — local models cannot afford auto_introspect (judge+prm+critic+
         # sentinel+extro) on every success. Default :failure_only when local.
         private_class_method def self.should_auto_introspect?(opts = {})
+          kind = (opts[:kind] || Thread.current[:pwn_request_kind]).to_s.to_sym
+          intent = (opts[:intent] || Thread.current[:pwn_request_intent]).to_s.to_sym
+          fails = opts[:turn_fails].is_a?(Hash) ? opts[:turn_fails].values.sum : 0
+          # Cheap answers already returned user-visible text. The post-answer
+          # critic + 12s ORM printed ERROR: Timed out reading data from server
+          # after greetings / takes / questions.
+          return false if %i[greeting howto recall].include?(intent)
+          return false if kind == :statement
+          return false if kind == :question && fails.zero?
+
           return true unless opts[:local]
 
           policy = agent_flag(key: :local_introspect, default: :failure_only).to_s.to_sym

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

@@ -97,7 +97,8 @@ module PWN
                   system_role_content: system_role_content,
                   spinner: spinner,
                   timeout: timeout,
-                  temp: temp
+                  temp: temp,
+                  quiet: opts[:quiet]
                 )
               end
             ensure
@@ -132,6 +133,7 @@ module PWN
           chat_opts[:timeout] = opts[:timeout] unless opts[:timeout].nil?
           chat_opts[:temp] = opts[:temp] unless opts[:temp].nil?
           chat_opts[:model] = opts[:model] unless opts[:model].to_s.empty?
+          chat_opts[:quiet] = opts[:quiet] unless opts[:quiet].nil?
           mod.chat(chat_opts)
         end
 

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

@@ -1157,11 +1157,20 @@ module PWN
                 spinner: false,
                 model: judge_model,
                 timeout: cheap_orm_timeout,
-                temp: CHEAP_ORM_TEMP
+                temp: CHEAP_ORM_TEMP,
+                quiet: true
               )
               text = extract_chat_text(resp: raw)
               return text unless text.strip.empty?
-            rescue StandardError
+
+              # Quiet ReadTimeout now returns nil instead of raising. That
+              # empty response already spent the cheap-ORM budget — do not
+              # immediately fire engine_chat_cheap (second 12s stall).
+              return nil
+            rescue StandardError => e
+              # A 12s ReadTimeout already spent the cheap-ORM budget.
+              return nil if timeout_error?(err: e)
+
               nil
             end
           end
@@ -1191,7 +1200,8 @@ module PWN
             system_role_content: opts[:system_role_content],
             spinner: false,
             timeout: cheap_orm_timeout,
-            temp: CHEAP_ORM_TEMP
+            temp: CHEAP_ORM_TEMP,
+            quiet: true
           }
           model = judge_model
           chat_opts[:model] = model unless model.to_s.empty?
@@ -1200,6 +1210,20 @@ module PWN
           nil
         end
 
+        private_class_method def self.timeout_error?(opts = {})
+          err = opts[:err]
+          return false if err.nil?
+
+          klass = err.class
+          name = klass.name.to_s
+          return true if name.include?('Timeout') || name.include?('ReadTimeout') || name.include?('OpenTimeout')
+          return true if err.message.to_s.match?(/timed out reading|read timeout|open timeout/i)
+
+          false
+        rescue StandardError
+          false
+        end
+
         private_class_method def self.cheap_orm_timeout
           n = agent_flag(key: :reward_llm_timeout, default: CHEAP_ORM_TIMEOUT).to_i
           n = CHEAP_ORM_TIMEOUT if n < 2

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

@@ -566,7 +566,9 @@ module PWN
               request: user,
               system_role_content: system,
               suppress_pii_warning: true,
-              spinner: false
+              spinner: false,
+              timeout: sidecar_timeout,
+              quiet: true
             )
             text = reflect_text(resp: resp)
             return text unless text.to_s.strip.empty?
@@ -846,7 +848,9 @@ module PWN
               request: user,
               system_role_content: system,
               suppress_pii_warning: true,
-              spinner: false
+              spinner: false,
+              timeout: sidecar_timeout,
+              quiet: true
             )
             text = reflect_text(resp: resp)
             return text unless text.to_s.strip.empty?
@@ -896,7 +900,9 @@ module PWN
           r = mod.chat(
             request: opts[:request],
             system_role_content: opts[:system_role_content],
-            spinner: false
+            spinner: false,
+            timeout: sidecar_timeout,
+            quiet: true
           )
           reflect_text(resp: r)
         rescue StandardError => e
@@ -911,6 +917,17 @@ module PWN
           :ollama
         end
 
+        # Kind / plan classification is a sidecar hop. Bound it so a hung
+        # model cannot stall the user's real answer, and stay quiet on timeout.
+        private_class_method def self.sidecar_timeout
+          n = (PWN::Env.dig(:ai, :agent, :sidecar_llm_timeout) if defined?(PWN::Env)).to_i
+          n = 20 if n < 5
+          n = 60 if n > 60
+          n
+        rescue StandardError
+          20
+        end
+
         # Parse JSON array, fenced JSON, or numbered/bulleted plain text.
         #
         # Supported Method Parameters::

data/lib/pwn/ai/anthropic.rb

@@ -362,7 +362,7 @@ module PWN
                        real_config_value?(value: oauth[:bearer_token]) ||
                        real_config_value?(value: oauth[:refresh_token])
 
-        if token.nil? && (oauth_opt_in || !real_config_value?(value: engine[:key]))
+        if token.nil? && (oauth_opt_in || !real_config_value?(value: engine[:key])) && !opts[:non_interactive]
           token = obtain_oauth_bearer_token(oauth)
           using_oauth = true
         end
@@ -372,9 +372,15 @@ module PWN
           using_oauth = false
         end
 
-        token ||= PWN::Plugins::AuthenticationHelper.mask_password(
-          prompt: 'Anthropic API Key (or run PWN::AI::Anthropic.obtain_oauth_bearer_token for Claude Pro/Max OAuth)'
-        )
+        if token.nil?
+          return nil if opts[:non_interactive]
+
+          token = PWN::Plugins::AuthenticationHelper.mask_password(
+            prompt: 'Anthropic API Key (or run PWN::AI::Anthropic.obtain_oauth_bearer_token for Claude Pro/Max OAuth)'
+          )
+        end
+
+        return nil if token.nil?
 
         http_method = if opts[:http_method].nil?
                         :get
@@ -488,6 +494,122 @@ module PWN
         raise e
       end
 
+      # Supported Method Parameters::
+      # usage = PWN::AI::Anthropic.get_plan_usage(
+      #   timeout: 'optional - seconds (default 8)'
+      # )
+      #
+      # Admin Usage API (organizations/usage_report/messages) yields tokens
+      # used; organizations/rate_limits yields the configured ceiling so the
+      # PS1 can show a percent. Individual accounts without an Admin key
+      # return {available:false}. Never prompts for credentials.
+      public_class_method def self.get_plan_usage(opts = {})
+        timeout = opts[:timeout] || 8
+        return { available: false, engine: :anthropic } unless plan_usage_credentials?
+
+        now = Time.now.utc
+        start_of_month = Time.utc(now.year, now.month, 1)
+        report = parse_plan_usage_json(
+          raw: anthropic_rest_call(
+            rest_call: 'organizations/usage_report/messages',
+            params: {
+              starting_at: start_of_month.strftime('%Y-%m-%dT00:00:00Z'),
+              ending_at: now.strftime('%Y-%m-%dT%H:%M:%SZ'),
+              bucket_width: '1d'
+            },
+            timeout: timeout,
+            spinner: false,
+            non_interactive: true
+          )
+        )
+        used_tokens = sum_usage_tokens(report: report)
+
+        limits = parse_plan_usage_json(
+          raw: anthropic_rest_call(
+            rest_call: 'organizations/rate_limits',
+            timeout: timeout,
+            spinner: false,
+            non_interactive: true
+          )
+        )
+        limit_tokens = first_rate_limit(limits: limits)
+
+        normalized = PWN::AI.normalize_plan_usage(
+          used: used_tokens,
+          limit: limit_tokens,
+          source: 'organizations/usage_report',
+          engine: :anthropic
+        )
+        return normalized if normalized[:available]
+
+        { available: false, engine: :anthropic }
+      rescue StandardError
+        { available: false, engine: :anthropic }
+      end
+
+      private_class_method def self.plan_usage_credentials?
+        engine = PWN::Env.dig(:ai, :anthropic) || {}
+        oauth = engine[:oauth].is_a?(Hash) ? engine[:oauth] : {}
+        real_config_value?(value: engine[:key]) ||
+          real_config_value?(value: oauth[:bearer_token]) ||
+          real_config_value?(value: oauth[:refresh_token])
+      end
+
+      private_class_method def self.parse_plan_usage_json(opts = {})
+        raw = opts[:raw]
+        return nil if raw.nil?
+
+        parsed = JSON.parse(raw.to_s, symbolize_names: true)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+
+      private_class_method def self.sum_usage_tokens(opts = {})
+        report = opts[:report]
+        return nil unless report.is_a?(Hash)
+
+        buckets = report[:data] || report[:usage] || []
+        total = 0
+        Array(buckets).each do |bucket|
+          next unless bucket.is_a?(Hash)
+
+          results = bucket[:results] || bucket[:usage] || [bucket]
+          Array(results).each do |row|
+            next unless row.is_a?(Hash)
+
+            %i[
+              uncached_input_tokens
+              input_tokens
+              cache_read_input_tokens
+              cache_creation_input_tokens
+              output_tokens
+            ].each { |k| total += row[k].to_i }
+          end
+        end
+        total.positive? ? total : nil
+      end
+
+      private_class_method def self.first_rate_limit(opts = {})
+        limits = opts[:limits]
+        return nil unless limits.is_a?(Hash)
+
+        Array(limits[:data]).each do |group|
+          next unless group.is_a?(Hash)
+
+          Array(group[:limits]).each do |lim|
+            next unless lim.is_a?(Hash)
+
+            type = lim[:type].to_s
+            next unless type.match?(/tokens_per|input_tokens|output_tokens/)
+
+            v = lim[:value].to_f
+            return v if v.positive?
+          end
+        end
+        nil
+      end
+
       # ----------------------------------------------------------------------
       # Native tool-calling adapter for PWN::AI::Agent::Loop.
       #
@@ -832,6 +954,8 @@ module PWN
         puts "USAGE:
           models = #{self}.get_models
 
+          usage = #{self}.get_plan_usage
+
           # One-time Claude Pro/Max OAuth enrollment (PKCE paste flow):
           bearer = #{self}.obtain_oauth_bearer_token
           # Subsequent runs silently refresh via ai.anthropic.oauth.refresh_token

data/lib/pwn/ai/gemini.rb

@@ -118,6 +118,19 @@ module PWN
         raise e
       end
 
+      # Supported Method Parameters::
+      # usage = PWN::AI::Gemini.get_plan_usage(
+      #   timeout: 'optional - seconds (default 8)'
+      # )
+      #
+      # Gemini Generative Language has no subscription-usage endpoint that
+      # returns used-vs-limit for an API key. Cached-miss / unavailable so
+      # the PS1 shows ∞ unless the operator later injects used/limit.
+      public_class_method def self.get_plan_usage(opts = {})
+        _timeout = opts[:timeout] || 8
+        { available: false, engine: :gemini }
+      end
+
       # ----------------------------------------------------------------------
       # Native tool-calling adapter for PWN::AI::Agent::Loop.
       #
@@ -432,6 +445,8 @@ module PWN
         puts "USAGE:
           models = #{self}.get_models
 
+          usage = #{self}.get_plan_usage
+
           response = #{self}.chat(
             request: 'required - message to Gemini',
             model: 'optional - model to use for text generation (defaults to PWN::Env[:ai][:gemini][:model])',