small-scripts/specs/agent-subscriptions.spec.md

agent-subscriptions

Purpose

Show live subscription usage percentages for each AI provider used by the agent runtimes system (Anthropic OAuth, MiniMax).

Usage

agent-subscriptions [OPTIONS]

Options:
  -n, --dryrun    Show what would be probed without making API calls
  -h, --help      Show this help message and exit

Behaviour

1. Read the Anthropic OAuth token from ~/dev/claude/secrets/anthropic/api_key (whole-file Bearer token).
2. Probe Anthropic subscription usage:
   • First attempt: GET https://api.anthropic.com/v1/models with Authorization: Bearer <token> — zero token cost; reads anthropic-ratelimit-unified-5h-utilization and anthropic-ratelimit-unified-7d-utilization response headers.
   • If headers absent, fall back: POST https://api.anthropic.com/v1/messages with model claude-haiku-4-5-20251001, max_tokens=1, message "hi" — same headers on response (or on the HTTPError if 429).
   • Values are fractions (0.0–1.0); multiply by 100 for percentage.
3. Read the MiniMax API key from ~/dev/claude/projects/agent-runtime-secrets/providers/minimax/v1/provider.sops.env via sops --decrypt --output-type dotenv (key: ANTHROPIC_AUTH_TOKEN). Uses SOPS_AGE_KEY_FILE=~/dev/claude/secrets/sops/provider-age-key.txt.
4. Probe MiniMax subscription usage:
   • GET https://www.minimax.io/v1/token_plan/remains with Authorization: Bearer <key> and User-Agent: curl/7.88.1 (minimax.io blocks Python-urllib).
   • Extract category_remains[] where category == "text_generation".
   • five_hour = current_interval_usage_count / current_interval_total_count × 100
   • seven_day = current_weekly_usage_count / current_weekly_total_count × 100
5. Display a formatted table. Each provider shows two rows (5-hour and 7-day windows). If a provider probe fails, display UNAVAILABLE for that provider's rows.
6. Colour-code the percentage column:
   • < 60%: green
   • 60–80%: yellow
   • ≥ 80%: red

Dryrun behaviour

Prints what it would probe without reading credential files or making HTTP calls:

[dryrun] Would probe:
  Anthropic  — ~/dev/claude/secrets/anthropic/api_key (Bearer OAuth token)
               GET https://api.anthropic.com/v1/models
  MiniMax    — ~/dev/claude/projects/agent-runtime-secrets/providers/minimax/v1/provider.sops.env (SOPS)
               GET https://www.minimax.io/v1/token_plan/remains

Output format

Agent Subscription Usage
========================

Provider     Window      Usage
-----------  ----------  --------
Anthropic    5-hour      23.4%
Anthropic    7-day       41.2%
MiniMax      5-hour      12.1%
MiniMax      7-day        8.3%

Percentage column is ANSI-coloured (green/yellow/red) when output is a TTY. No colour when piped.

Edge cases

• If the Anthropic token file does not exist, print UNAVAILABLE for both Anthropic rows and continue.
• If SOPS decryption fails (missing key file, wrong key, sops not installed), print UNAVAILABLE for both MiniMax rows and continue.
• If an API call fails for any reason, print UNAVAILABLE for that provider's rows and continue.
• If a utilization header is present for only one window, display N/A for the missing window.
• Exit 0 even if some providers are unavailable (the tool is informational).

Examples

agent-subscriptions            # live probe
agent-subscriptions --dryrun   # preview only
agent-subscriptions --help     # usage