From 8ced108f7450f5a29f7b33e93a1d38b36e0bf366 Mon Sep 17 00:00:00 2001 From: "B.A. Baracus" Date: Mon, 6 Apr 2026 02:26:51 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20README=20overhaul=20=E2=80=94=20add=20a?= =?UTF-8?q?nalyze.js,=20wake=20integration,=20Quick=20start,=20fix=20provi?= =?UTF-8?q?der=20table=20and=20architecture?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Six changes: - Add ## Quick start block (monitor.js, analyze.js, token-status.sh) - Add ## Analysis section with all 8 analyze.js subcommands and output descriptions - Add ## Wake integration section — token-status.sh docs, output format, cache guard note - Provider support table: add google-gemini and xai-* rows - Architecture block: add analyze.js, gemini.js, xai.js, docs/analyze.md - Related: add token-status.sh as first item, fix issue link to trentuna/token-monitor#1 164/164 tests pass. --- README.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 799e9fa..b839eb7 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,14 @@ Modular LLM API quota and usage visibility tool. Extracts rate-limit and usage d **Why it exists:** team-vigilio hit its 7-day rate limit (9+ days of 429s). api-ateam ran out of credit mid-session. We kept flying blind. This tool surfaces quota health before the failure. +## Quick start + +```bash +node monitor.js # run now — human-readable output + log +node analyze.js # analyze accumulated logs — burn rates, rotation +~/os/token-status.sh # what Vigilio's wake prompt sees (automated path) +``` + ## Usage ```bash @@ -14,6 +22,29 @@ node monitor.js --provider team-nadja # single provider node monitor.js --no-log # suppress log file write ``` +## Analysis + +```bash +node analyze.js # full report +node analyze.js --burn-rate # burn rate per account +node analyze.js --weekly # weekly budget reconstruction +node analyze.js --stagger # reset schedule (next 48h) +node analyze.js --rotation # rotation recommendation +node analyze.js --json # JSON output (all sections) +node analyze.js --provider team-nadja # filter to one provider +node analyze.js --prune [--dry-run] # archive and prune logs > 30 days +``` + +**Burn Rate** — delta analysis of 7d utilization over time, projected exhaustion at current rate. + +**Reset Schedule** — providers resetting within the next 48 hours, sorted ascending by time to reset. + +**Weekly Reconstruction** — peak and average 7d utilization per provider per ISO week. Shows exhaustion events. + +**Rotation Recommendation** — ranked provider list by headroom, deprioritizing maxed/rejected/invalid-key accounts. + +**Underspend Alerts** — active accounts with ≥ 40% of 5h window unused and < 2h until reset. + ## Example output ``` @@ -80,6 +111,8 @@ Overall: 1 CRITICAL, 3 OK, 3 UNKNOWN | team-vigilio, team-ludo, team-molto, team-nadja, team-buio | Anthropic Teams (direct) | 5h/7d utilization (0–100%), status, reset countdown, severity | | shelley-proxy | Shelley/exe.dev proxy | Token headroom, request headroom, per-call USD cost | | api-ateam | Anthropic API (pay-per-use) | Key validity only — no billing API exists | +| google-gemini | Gemini API (free tier) | Quota violation detail, retry delay, key validity | +| xai-face, xai-amy, xai-murdock, xai-ba, xai-vigilio | xAI/Grok | Request/token remaining counts, rate limit status | ## Severity levels @@ -124,14 +157,19 @@ grep '"team-vigilio"' ~/.logs/token-monitor/*.jsonl | \ ``` monitor.js — CLI entrypoint, orchestrates probes +analyze.js — analysis CLI (burn rates, weekly, stagger, rotation) providers/ index.js — reads ~/.pi/agent/models.json, returns typed provider list anthropic-teams.js — unified schema parser (oat01 keys, all team-* providers) anthropic-api.js — pay-per-use (api03 keys) — reports "no billing data" shelley-proxy.js — classic schema + Exedev-Gateway-Cost header + gemini.js — Gemini API (free tier, quota via response body) + xai.js — x.ai/Grok (rate-limit headers) logger.js — JSONL log to ~/.logs/token-monitor/ report.js — human-readable summary + severity logic test.js — test suite (run: node test.js) +docs/ + analyze.md — analysis CLI full reference ``` ## How to add a new provider @@ -152,6 +190,30 @@ The tool makes one minimal API call per provider to extract headers: ## Related +- `~/os/token-status.sh` — wake-prompt integration (calls monitor.js, formats for beat.sh) - `~/projects/provider-check/` — predecessor (liveness only, no quota depth) - `~/.pi/agent/models.json` — provider configuration source -- Forgejo issue: trentuna/a-team#91 +- Forgejo issue: trentuna/token-monitor#1 + +## Wake integration + +`~/os/token-status.sh` is the automated interface. It runs `monitor.js --json` +and formats the output into a compact summary block for injection into +Vigilio's wake prompt via `beat.sh`. + +```bash +# Manual invocation (same as what the wake prompt sees) +~/os/token-status.sh + +# Output format: +## Token Economics +Anthropic Teams (5 seats): + team-vigilio ✗ MAXED 7d:100% resets 23h + team-molto ✓ 5h:32% 7d:45% resets 4h + ... +→ Current recommendation: use team-molto | avoid team-vigilio +``` + +File location: `~/os/token-status.sh` +Called by: `~/os/beat.sh` (Vigilio wake script) +Uses: `monitor.js --json` with 20-minute cache guard (won't double-probe within a session)