Phase 2: analysis layer (analyze.js), cache guard, log hygiene

- analyze.js: burn rate, weekly reconstruction, cycle stagger, rotation
  rank, underspend alerts, log prune with weekly archive
- logger.js: getCachedRun(maxAgeMinutes) — skip probing if recent data exists
- monitor.js: cache guard at wake — 20-min dedup, zero extra API calls
- test.js: fix type assertion for gemini-api/xai-api providers (+5 passing);
  add 14 new tests for cache guard and analyze.js (162 total, all green)
- docs/analyze.md: usage reference

Co-authored-by: Hannibal Smith <hannibal@trentuna.com>

2026-04-05 04:49:05 +00:00

2.2 KiB

Raw Blame History

analyze.js — Token Monitor Analysis CLI

Reads accumulated JSONL logs from ~/.logs/token-monitor/ and produces burn rates, weekly stats, reset schedule, and rotation recommendations.

Usage

node analyze.js                         # full report (default)
node analyze.js --burn-rate             # burn rate per account only
node analyze.js --weekly                # weekly budget reconstruction
node analyze.js --stagger               # reset schedule (next 48h)
node analyze.js --rotation              # rotation recommendation only
node analyze.js --json                  # JSON output (all sections)
node analyze.js --provider team-nadja   # filter to one provider
node analyze.js --prune                 # prune logs older than 30 days
node analyze.js --prune --dry-run       # dry run — show what would be pruned

Output sections

Burn Rate — delta analysis of 7d utilization over time, projected exhaustion at current rate. Requires ≥ 2 data points per provider.

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 (status=rejected).

Rotation Recommendation — ranked provider list. Rules in priority order:

Invalid key → bottom (unusable)
Maxed/rejected → deprioritize; soonest reset wins tiebreaker
Dormant → reserve for cycle staggering
Active: rank by headroom (1 - utilization_7d)

Underspend Alerts — active accounts with ≥ 40% of 5h window unused and < 2h until reset. These tokens expire unused — boost them.

Log format

Input: ~/.logs/token-monitor/YYYY-MM-DD.jsonl — one JSON object per line.

Pruned archives: ~/.logs/token-monitor/weeks/YYYY-WNN.json — weekly aggregates with peak/avg utilization and sample counts.

Cadence

Logs are written by monitor.js at each Vigilio wake (max once per 20 minutes — cache guard prevents double-logging within a session). Expected: ~15–20 data points/day per active provider, ~100–140/week.

At target cadence, log footprint is < 1MB/month. --prune trims files older than 30 days after archiving them into weekly summaries.

2.2 KiB Raw Blame History Unescape Escape