Phase 2: Make Provider-Native Usage Windows First-Class #37

New Issue

Closed

opened 2026-05-21 00:49:37 -05:00 by null · 0 comments

null commented

2026-05-21 00:49:37 -05:00

Owner

References: remaining-usage-accuracy-review-plan.md — Phase 2

Summary

Pipeline has a Claude usage scraper, but it stores only one current_pct and one remaining_ms, then weekly messages/tokens/cost. The reference parser captures separate sections for current session, weekly all-model, and weekly Sonnet windows. The single-percent shape cannot represent the target display of independent bars with independent reset times.

The scraper is also opt-in (USAGE_SCRAPER_ENABLED=false) and its results are not wired into the dashboard priority path.

Acceptance Criteria

A Claude /usage sample with current session and all-model weekly windows produces two separate bars with independent reset times
Dashboard prioritizes provider-native windows over local estimates
Scraper remains opt-in operationally, but the API/UI path is ready when enabled

Work

Extend ParsedClaudeUsage and ProviderUsageScrapeResult to include an array of windows: current_session, weekly_all_models, weekly_sonnet, extra_usage
Port the reference parser's section-aware behavior (from parse-claude-usage.py) while keeping Pipeline's broader time parsing tests
Surface provider-native scrape results in the dashboard runtime usage card
Keep scraper opt-in but make API/UI ready for it when enabled

Do Not

Do not make tmux/Claude CLI scraping mandatory for all installs
Do not block the dashboard if provider-native scraping fails
Do not merge weekly_all_models and weekly_sonnet — they answer different questions
Do not use a single first-found percentage when section labels are present

Priority: High
Phase: 2

References: [`remaining-usage-accuracy-review-plan.md`](docs/remaining-usage-accuracy-review-plan.md) — Phase 2 ## Summary Pipeline has a Claude usage scraper, but it stores only one `current_pct` and one `remaining_ms`, then weekly messages/tokens/cost. The reference parser captures separate sections for current session, weekly all-model, and weekly Sonnet windows. The single-percent shape cannot represent the target display of independent bars with independent reset times. The scraper is also opt-in (`USAGE_SCRAPER_ENABLED=false`) and its results are not wired into the dashboard priority path. ## Acceptance Criteria - A Claude `/usage` sample with current session and all-model weekly windows produces **two separate bars** with independent reset times - Dashboard prioritizes provider-native windows over local estimates - Scraper remains opt-in operationally, but the API/UI path is ready when enabled ## Work 1. Extend `ParsedClaudeUsage` and `ProviderUsageScrapeResult` to include an array of windows: `current_session`, `weekly_all_models`, `weekly_sonnet`, `extra_usage` 2. Port the reference parser's section-aware behavior (from `parse-claude-usage.py`) while keeping Pipeline's broader time parsing tests 3. Surface provider-native scrape results in the dashboard runtime usage card 4. Keep scraper opt-in but make API/UI ready for it when enabled ## Do Not - Do not make tmux/Claude CLI scraping mandatory for all installs - Do not block the dashboard if provider-native scraping fails - Do not merge `weekly_all_models` and `weekly_sonnet` — they answer different questions - Do not use a single first-found percentage when section labels are present **Priority:** High **Phase:** 2