Skip to content

Subscription usage reader: OAuth /api/oauth/usage poll with degradation chain #31

Description

@Ryan-Atkinson87

Implement the primary, subscription-mode usage reader against the UsageReader interface (#30):
poll the OAuth usage endpoint and degrade gracefully when it is unavailable.

Spec: §6.2 (Reading usage — subscription mode + volatility caveat), §6.1 (Meters), §15 (Open
item: usage-meter polling cadence — resolution direction is the same ~5-min cached poll).

Acceptance criteria

  • Polls GET https://api.anthropic.com/api/oauth/usage authenticated with the OAuth token from ~/.claude/.credentials.json, header anthropic-beta: oauth-2025-04-20.
  • Parses per-window utilisation + resets_at for five_hour, seven_day, seven_day_opus, seven_day_sonnet, and the extra_usage object (is_enabled, monthly_limit, used_credits, utilization) into the Usage meter model, governing-meter selection, and reader interface #30 meters.
  • Result cached ~5 minutes (per §15 resolution direction); sub-5-minute polling is not done.
  • Graceful degradation chain — never crashes the run: OAuth endpoint → statusLine stdin (rate_limits.five_hour / .seven_day, Claude Code ≥2.1.x) → token-estimation fallback. The active fallback level is recorded on the snapshot.
  • Tolerates endpoint shape changes and unknown meters (carries them through per Usage meter model, governing-meter selection, and reader interface #30), per the §6.2 volatility caveat.
  • Both success and failure paths are explicit (no silent except: pass); a failed read logs and falls back rather than raising.
  • Provider-specific reading stays behind the Claude adapter boundary (Spec §3.3) — the engine talks to UsageReader, not the OAuth endpoint directly.
  • Unit tests cover a normal parse, an endpoint-shape change, and each fallback level.

Depends on: #30
Depends on: #17

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions