# 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

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