Cost Runway Tracker

Cost & Runway Tracker - the low-budget proof

Spend tracking looks trivial until a stale number gates a pipeline. This skill encodes what a real tracker must get right, with the exact failure modes encountered in production.

Ground rules (the traps)

1. "Usage" is NOT balance. The most common bug: reading the key-info endpoint's usage field and calling it "balance". usage is LIFETIME spend. Real balance = total_credits - total_usage. Getting this wrong makes a watchdog report the wrong number forever (verified live).
2. Never trust a stale status file. A treasury file synced weeks ago says CRITICAL while the real balance is healthy - and gating logic reads the file, not the API. Freshness is part of correctness.
3. Assume the key has NO cap until proven. Provider keys default to limit: null. A retry storm spends to zero with no stop. Ask, and if unset, flag it - a cap is a 30-second dashboard change that protects the whole thesis.
4. Runway is a range, not a point. Balance / weekly burn and balance / monthly burn disagree for a reason; report both.

The math

balance     = total_credits - total_usage          (from /credits)
burn_weekly = usage_weekly                          (from /auth/key)
burn_monthly= usage_monthly
runway_weeks= balance / burn_weekly
runway_month= balance / burn_monthly
status      = HEALTHY if balance >= floor else LOW  (floor is YOUR call)

Cache awareness (why panels are cheap)

Repeated identical context is not billed at prompt price. Cache-read is a fraction of the prompt rate:

• flash-class models: cache-read ~50x cheaper than prompt
• frontier models: cache-read ~6-10x cheaper
• A multi-model panel with an identical context pack writes the cache ONCE and reads it N times at the discounted rate - that is the mechanism that makes 5-flagship panels cost pennies.

Evidence: pull the per-model pricing, compute saving = prompt / cache_read, and print the table in every report. The cache carve-out is a deliberate design choice (shared system prompts, shared few-shots), not luck.

The pattern

1. PULL credits      -> total_credits, total_usage
2. PULL key info     -> usage_daily / weekly / monthly, limit, free-tier quota
3. PULL model pricing-> per-model cache rates for the models in use
4. COMPUTE           -> balance, burn, runway (weeks & months), cache savings
5. WRITE             -> fresh status file + human report card + raw json
6. GATE              -> exit 0 healthy / nonzero below floor; fail loudly,
                        never silently skip the check

Failure modes seen in production

• usage (lifetime spend) misread as balance -> watchdog alerts at wrong thresholds forever, and the status file picks the stale value.
• No spend cap -> a bot retry loop burns the whole balance in one incident.
• Cache prices ignored -> "panel is too expensive" conclusion that the numbers disprove.
• Report written only on the happy path -> --json mode forgot to persist the artifacts; every mode must write.

Output

• Live balance, weekly/monthly burn, runway in weeks AND months
• Per-model cache-rate table with the x saving
• Key-limit status (NONE SET is a finding, not a footnote)
• Status file that gating logic actually reads, timestamped fresh

Skill pattern: get the units right (credits vs usage), check the cap, show the cache math. The value is not the Dashboard - it is that the number your pipeline gates on is TRUE.