agent-recon 1.0.1

package/README.md

@@ -0,0 +1,182 @@
+# Agent Recon™
+
+**Real-time observability for AI coding agents.**
+
+Monitor every tool call, security event, token cost, and session in real time.
+Know exactly what your AI agent is doing.
+
+[![npm](https://img.shields.io/npm/v/agent-recon)](https://www.npmjs.com/package/agent-recon)
+[![License](https://img.shields.io/badge/license-Source--Available-blue)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20WSL-brightgreen)]()
+
+🔒 **Security classification** — regex + LLM-powered risk analysis on every tool call
+📊 **Token cost tracking** — per-session spend with multi-model support
+🧠 **AI-powered insights** — prompt coaching, hallucination detection, session narratives
+🌐 **Cross-platform** — Windows, macOS, Linux, WSL, tmux, VS Code
+🔌 **Agent-agnostic architecture** — Claude Code v1, Cursor/Copilot/Windsurf in v1.1
+
+→ **[View landing page](https://www.agent-recon.net)** | **[Installation guide](INSTALL.md)** | **[Pricing](https://www.agent-recon.net#pricing)**
+
+## Quick Start
+
+### Option A — Install via npm
+
+```bash
+npm install -g agent-recon
+agent-recon install
+```
+
+The guided installer detects your platform, registers hooks, and starts the server.
+See [INSTALL.md](INSTALL.md) for prerequisites, troubleshooting, and alternative methods.
+
+### Option B — From source
+
+```bash
+cd server && npm install && cd ..
+node server/start.js
+```
+
+### Open the dashboard
+Visit **http://localhost:3131** in your browser.
+
+### Start Claude Code
+Run any `claude` command from this project directory. Hook events will stream to the dashboard instantly.
+
+---
+
+## How It Works
+
+```
+Claude Code Agent(s)
+     │  hook fires → stdin JSON
+     ▼
+.claude/hooks/send-event.py  ──HTTP POST──▶  server/server.js (port 3131)
+                                                      │
+                                              WebSocket broadcast
+                                                      ▼
+                                           public/index.html (browser)
+                                         icons · sounds · live feed
+```
+
+Every hook registered in `.claude/settings.json` is wired to `send-event.py`, which runs asynchronously (never blocking Claude) and forwards the payload to the local server. The server stores up to 1 000 events in memory and fans them out to every connected browser tab via WebSocket. Late-joining tabs receive the full event history on connect.
+
+---
+
+## Event Categories & Sounds
+
+| Icon | Category | Hook Events | Sound |
+|------|----------|-------------|-------|
+| 🚀 | Session | SessionStart, SessionEnd | Rising arpeggio / falling tone |
+| 💬 | Prompt | UserPromptSubmit | Soft ping |
+| ⚡ | Bash | PreToolUse (Bash) | Quick click |
+| ✍️ | Write | PreToolUse (Write) | Soft click |
+| ✏️ | Edit | PreToolUse (Edit/MultiEdit) | Soft click |
+| 👁️ | Read | PreToolUse (Read) | Soft click |
+| 🔍 | Search | PreToolUse (Glob/Grep) | Soft click |
+| 🌐 | Web | PreToolUse (WebFetch/WebSearch) | Soft click |
+| 🔧 | Tool | PreToolUse (other) | Soft click |
+| ✅ | Done | PostToolUse | Short positive beep |
+| ❌ | Failure | PostToolUseFailure | Low buzz |
+| 🤖 | Subagent | SubagentStart, SubagentStop | Spawn/resolve chime |
+| 🔔 | Notify | Notification | Bell tone |
+| 🏆 | Complete | Stop, TaskCompleted | Success chord |
+| ⚠️ | Idle | TeammateIdle | Pulsed alert |
+| 🗜️ | Compact | PreCompact | Soft tone |
+
+---
+
+## Dashboard Features
+
+- **Timeline view** — chronological feed, newest at top with slide-in animation
+- **Swimlane view** — one column per `session_id` for multi-agent observation
+- **Category filter** — click any badge in the stats bar to isolate a category
+- **Session filter** — dropdown to focus on a single agent session
+- **Sound controls** — mute toggle + volume slider; all tones synthesized via Web Audio API (no audio files)
+- **Expandable cards** — click any card to reveal the full raw JSON payload
+- **Auto-reconnect** — dashboard reconnects automatically if the server restarts
+- **History on join** — opening a new tab replays all stored events immediately
+
+---
+
+## Windows Notes
+
+The hook command in `.claude/settings.json` is:
+```
+python .claude/hooks/send-event.py
+```
+If `python` is not on your PATH, replace it with the full path to your Python 3 executable, e.g.:
+```
+C:\Python312\python.exe .claude/hooks/send-event.py
+```
+The forwarder uses only Python standard library modules — no `pip install` required.
+
+---
+
+## WSL + tmux Support
+
+Claude Code running inside WSL (including inside a **tmux** session) can stream events to the same dashboard.
+
+### How it works
+
+```
+WSL tmux session
+  Claude Code Agent
+       │  hook fires → stdin JSON
+       ▼
+~/.claude/hooks/send-event-wsl.py  ──HTTP POST──▶  Windows host IP:3131
+                                                          │
+                                                  (same server.js)
+                                                          ▼
+                                               browser dashboard
+```
+
+Events from WSL show a green **WSL** badge in the dashboard so you can distinguish them from Windows-side sessions.
+
+### Quick Setup
+
+**1 — On Windows**, start the Agent Recon™ server as usual:
+```powershell
+cd C:\ProjectGreatLoop\agent-recon\server
+node start.js
+```
+
+**2 — Inside WSL**, run the setup script once:
+```bash
+bash /mnt/c/ProjectGreatLoop/agent-recon/setup-wsl.sh
+```
+
+This script:
+- Copies `send-event-wsl.py` to `~/.claude/hooks/`
+- Creates `~/.claude/settings.json` with all 13 hook registrations
+- Verifies the Windows host is reachable
+
+**3 — Start Claude** in any WSL directory (plain shell or tmux):
+```bash
+tmux new-session -s work
+claude
+```
+
+Events will stream to `http://localhost:3131` on Windows immediately.
+
+### How the WSL forwarder finds the Windows host
+
+It reads the `nameserver` from `/etc/resolv.conf` (the WSL2 virtual gateway). If that fails it falls back to `ip route show default`. The server accepts connections from all RFC 1918 private ranges (10.x, 172.16-31.x, 192.168.x) in addition to loopback.
+
+---
+
+## File Structure
+
+```
+├── .claude/
+│   ├── hooks/
+│   │   ├── send-event.py          # Windows hook forwarder (stdlib only)
+│   │   └── send-event-wsl.py      # WSL hook forwarder (auto-detects host IP)
+│   └── settings.json              # Hook registrations for Windows Claude
+├── server/
+│   ├── package.json
+│   └── server.js                  # Express HTTP + WebSocket server (port 3131)
+├── public/
+│   └── index.html                 # Single-file dashboard SPA
+├── setup-wsl.sh                   # One-time WSL setup script
+└── README.md
+```

package/SECURITY.md

@@ -0,0 +1,63 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+**Do NOT open a public GitHub issue for security vulnerabilities.**
+
+Please report vulnerabilities by email to **security@agent-recon.net**. Include as much detail as
+possible: affected component, reproduction steps, potential impact, and any suggested fixes.
+
+A PGP key is available upon request for encrypted communication.
+
+## Response Commitments
+
+| Stage | Timeline |
+|-------|----------|
+| Acknowledge receipt | Within 24 hours |
+| Triage and severity assessment | Within 72 hours |
+| Coordinated disclosure window | 90 days from initial report |
+
+Professional tier license holders receive priority triage for security reports.
+
+## Scope
+
+The following vulnerability classes are in scope:
+
+- Remote code execution (RCE)
+- SQL injection (SQLite)
+- Credential exposure (API keys, license keys, secrets in logs)
+- Authentication / authorization bypass
+- Cross-site scripting (XSS) in the dashboard
+- Hook script injection (malicious payloads via event data)
+- WebSocket hijacking or unauthorized access
+- SQLite database corruption via crafted events
+
+## Out of Scope
+
+- Social engineering attacks against maintainers or users
+- Denial-of-service against the localhost-only service
+- Issues requiring physical access to the machine
+- UI cosmetic issues (layout, styling, typos)
+- Vulnerabilities in third-party dependencies (please report these upstream to the relevant project)
+
+## Coordinated Disclosure
+
+We follow a 90-day coordinated disclosure policy:
+
+1. Reporter sends vulnerability details to security@agent-recon.net.
+2. We acknowledge within 24 hours and triage within 72 hours.
+3. We work on a fix and coordinate a release timeline with the reporter.
+4. After the fix is released (or after 90 days, whichever comes first), the reporter may publicly
+   disclose the vulnerability.
+5. We will credit the reporter in the release notes unless they prefer to remain anonymous.
+
+## Credit
+
+Reporters who follow this responsible disclosure process will be credited by name (or handle) in the
+release notes for the version containing the fix. If you prefer anonymity, let us know in your
+initial report.
+
+## Related Documents
+
+- [SECURITY-AUDIT.md](SECURITY-AUDIT.md) -- Security audit results and findings
+- [SECURITY-RULES.md](SECURITY-RULES.md) -- Security rule definitions and classification

package/TERMS.md

@@ -0,0 +1,233 @@
+# Agent Recon™ — Terms of Service
+
+**Effective Date:** March 2026
+**Provider:** PNW Great Loop LLC
+**Product:** Agent Recon™
+
+---
+
+> Agent Recon™ is an independent product and is not affiliated with, endorsed
+> by, or sponsored by Anthropic PBC. Claude, Claude Code, and the Anthropic
+> name and logo are trademarks of Anthropic PBC. Agent Recon™ is a trademark
+> of PNW Great Loop LLC.
+
+---
+
+## 1. Acceptance of Terms
+
+By purchasing a license, creating an account, or using any paid features of
+Agent Recon™ ("Service"), you ("Customer") agree to these Terms of Service
+("Terms"). These Terms apply to all paid transactions processed through the
+Agent Recon™ storefront. Use of the free Community tier is governed by the
+End User License Agreement (EULA.md).
+
+## 2. Service Description
+
+Agent Recon™ is a locally-installed observability dashboard for AI coding
+agent sessions. The Service includes:
+- Software distributed via npm and direct download
+- License key provisioning and validation
+- Software updates during the subscription period
+- Priority support (Professional tier)
+
+The Service does NOT include:
+- LLM API access (the Customer supplies their own API key(s))
+- Hosting or cloud infrastructure (the software runs locally)
+- Guaranteed uptime for the license validation endpoint (graceful offline
+  degradation is built in)
+
+## 3. Payment Processor
+
+All payments are processed by Lemonsqueezy (or a successor payment processor
+designated by the Provider). By making a purchase, the Customer also agrees
+to Lemonsqueezy's terms of service and privacy policy.
+
+The Provider does not directly store credit card numbers, bank account
+details, or other payment credentials. All payment data is handled by
+the payment processor.
+
+## 4. Pricing and Billing
+
+### 4.1 Current Pricing
+
+| Tier | Monthly | Annual | Annual Savings |
+|------|---------|--------|----------------|
+| Personal | $9.99/month | $84/year | 30% |
+| Professional | $29/month | $279/year | 20% |
+
+Prices are in US dollars (USD) and exclude applicable taxes.
+
+### 4.2 Billing Cycle
+
+- **Monthly subscriptions** are billed on the same day each month.
+- **Annual subscriptions** are billed on the same date each year.
+- Billing begins on the date of purchase.
+
+### 4.3 Auto-Renewal
+
+Subscriptions automatically renew at the end of each billing cycle unless
+cancelled before the renewal date. The Customer will be charged the
+then-current price at renewal.
+
+### 4.4 Price Changes
+
+The Provider may change pricing at any time. Price changes take effect at
+the next renewal cycle, not mid-cycle. The Provider will notify the Customer
+of price changes at least thirty (30) days before the renewal date via:
+- Email to the address associated with the Customer's account, AND
+- A notice in the Software's update mechanism or on the Provider's website
+
+If the Customer does not agree to the new pricing, they may cancel before
+the next renewal date.
+
+## 5. Refund Policy
+
+### 5.1 Fourteen-Day Money-Back Guarantee
+
+The Customer may request a full refund within fourteen (14) days of the
+initial purchase date, no questions asked. This applies to both monthly
+and annual subscriptions.
+
+### 5.2 Refund Process
+
+To request a refund, contact license@agent-recon.net with the order number
+or license key. Refunds are processed through the original payment method
+within five (5) to ten (10) business days.
+
+### 5.3 Renewal Refunds
+
+Refunds for auto-renewal charges may be requested within seven (7) days of
+the renewal charge date.
+
+### 5.4 Exceptions
+
+Refunds are not available:
+- After the applicable refund period has expired
+- If the license key has been shared with or transferred to another party
+- For complimentary (free) license keys
+
+## 6. Subscription Cancellation
+
+### 6.1 How to Cancel
+
+The Customer may cancel at any time through:
+- The account dashboard on the Provider's website
+- Email to license@agent-recon.net
+
+### 6.2 Effect of Cancellation
+
+- **Monthly subscriptions:** Access continues until the end of the current
+  billing period. No further charges are made.
+- **Annual subscriptions:** Access continues until the end of the annual
+  billing period. No partial refunds are issued for unused months beyond
+  the 14-day refund window.
+- Upon expiration, the installation reverts to Community tier functionality.
+  No Customer data is deleted.
+
+### 6.3 Reactivation
+
+A cancelled subscription may be reactivated at any time by purchasing a new
+license. The previously cached license key will be replaced.
+
+## 7. Taxes
+
+The Customer is responsible for all applicable taxes (sales tax, VAT, GST,
+or other taxes) imposed by their jurisdiction. The payment processor may
+collect and remit taxes where required by law. Displayed prices may or may
+not include tax depending on the Customer's location.
+
+## 8. Data Handling
+
+### 8.1 Local Data
+
+Agent Recon™ runs locally on the Customer's machine. All session data, event
+logs, and LLM analysis results are stored in a local SQLite database on the
+Customer's machine. The Provider does not have access to this data.
+
+### 8.2 Telemetry Data
+
+The optional telemetry system collects minimal, non-identifying data as
+described in PRIVACY.md. The Customer may opt out at any time.
+
+### 8.3 Payment Data
+
+Payment and account data is handled by the payment processor (Lemonsqueezy)
+and is subject to their privacy policy. The Provider stores only:
+- Email address (for license key delivery and support)
+- License key and tier information
+- Transaction history (dates, amounts, invoice numbers)
+
+### 8.4 Data Deletion
+
+The Customer may request deletion of their account and associated data by
+contacting license@agent-recon.net. Telemetry data can be deleted via the
+self-service data deletion endpoint (see PRIVACY.md).
+
+## 9. Account Security
+
+The Customer is responsible for maintaining the confidentiality of their
+license key. The Customer must notify the Provider promptly if they become
+aware of unauthorized use of their license key.
+
+## 10. Intellectual Property
+
+Agent Recon™, including its name, logo, documentation, and software, is the
+intellectual property of PNW Great Loop LLC. These Terms do not grant any
+rights to the Provider's trademarks or intellectual property except the
+limited license to use the Software as described in the EULA.
+
+## 11. Disclaimer of Warranties
+
+THE SERVICE IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTY OF ANY
+KIND. THE PROVIDER DOES NOT WARRANT THAT THE SERVICE WILL BE UNINTERRUPTED,
+ERROR-FREE, OR SECURE. SEE THE EULA (SECTION 8) FOR THE COMPLETE WARRANTY
+DISCLAIMER.
+
+## 12. Limitation of Liability
+
+THE PROVIDER'S TOTAL AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THESE
+TERMS SHALL NOT EXCEED THE AMOUNT PAID BY THE CUSTOMER IN THE TWELVE (12)
+MONTHS PRECEDING THE CLAIM. SEE THE EULA (SECTION 9) FOR THE COMPLETE
+LIABILITY LIMITATION.
+
+## 13. Indemnification
+
+The Customer agrees to indemnify and hold harmless PNW Great Loop LLC from
+any claims, damages, losses, or expenses (including reasonable attorney fees)
+arising from the Customer's use of the Service or violation of these Terms.
+
+## 14. Modifications to Terms
+
+The Provider may update these Terms at any time. Material changes will be
+communicated at least thirty (30) days in advance via email or the Provider's
+website. Continued use of the Service after changes take effect constitutes
+acceptance of the revised Terms.
+
+## 15. Governing Law
+
+These Terms shall be governed by and construed in accordance with the laws
+of the State of Washington, United States, without regard to its conflict of
+law provisions. Any dispute shall be resolved in the state or federal courts
+located in Washington State.
+
+## 16. Severability
+
+If any provision of these Terms is held to be unenforceable or invalid,
+that provision shall be modified to the minimum extent necessary, and the
+remaining provisions shall continue in full force.
+
+## 17. Entire Agreement
+
+These Terms, together with the EULA, LICENSE, LICENSE-COMMERCIAL, and
+PRIVACY.md, constitute the entire agreement between the parties regarding
+the Service.
+
+## 18. Contact
+
+PNW Great Loop LLC
+Email: license@agent-recon.net
+Web: https://www.agent-recon.net
+
+---
+
+*Attorney review recommended before commercial distribution.*