# UnoRouter Balance — Hermes Desktop Plugin

Statusbar chip for [Hermes Agent](https://hermes-agent.nousresearch.com) Desktop
showing how much UnoRouter credit you have left, plus a popover with the full
breakdown.

## What it shows

Statusbar readout — `left/total (pct%)` of your spendable budget:

```
7.02/10 (70%)
```

Click opens a popover:

- **UnoRouter** heading with a refresh button
- **Available** — total spendable, with a progress bar
- Subscription credit, plan name, time to weekly reset
- Wallet balance, lifetime spend, request count

Hover shows a one-line tip; details live in the popover only.

## Install

1. Create an **access token** (not an `sk-` API key) at
   unorouter.com → Settings → Security → API access.
2. Copy this folder to `$HERMES_HOME/desktop-plugins/unorouter-balance/`.
   - Windows: `%LOCALAPPDATA%\hermes\desktop-plugins\unorouter-balance\`
   - Linux/macOS: `~/.hermes/desktop-plugins/unorouter-balance/`
   - The folder name must match the plugin id.
3. Either paste the token into `DEFAULT_TOKEN` at the top of `plugin.js`, or
   run ⌘K → **UnoRouter: set access token** (persisted per plugin).
4. ⌘K → **Reload desktop plugins**.

The app watches the folder, so later saves hot-reload in place.

## Two credit pools

This trips people up. UnoRouter keeps two separate pools:

| Pool | Source | Expiry |
|---|---|---|
| Subscription credit | weekly delivery on a plan | resets weekly, does **not** carry over |
| Wallet | one-time top-ups | never expires |

`/api/user/self` → `quota` is the **wallet only**. It reads `0` on an active
subscription, so a naive plugin reports "$0.00" to a paying subscriber. This
plugin adds the subscription remainder (`/api/subscription/self`) and shows the
sum, because `billing_preference` is `subscription_first` and the subscription
carries `allow_wallet_overflow: true`.

## API

Both endpoints take the access token as `Authorization: Bearer <token>`.
Quota units: `500000 == $1`.

```
GET /api/user/self          # wallet quota, lifetime spend, request count
GET /api/subscription/self  # subscription credit, next reset, plan title
```

`/api/subscription/self` is **not in the public docs**. It answers 200.
Dead ends: `/api/subscription`, `/api/billing`, `/api/plan` → 404;
`/api/user/subscription`, `/api/user/plan` → 403.

Most failures answer HTTP 200 with `success: false` — check that field, not the
status code. Real 401/403 means a bad or revoked token.

## Refresh

Polls every 5 minutes via React Query (`REFRESH_MS`). Background polling is off
by default, so an unfocused window doesn't tick. Manual refresh: the button in
the popover, or ⌘K → **UnoRouter: refresh balance**.

## Palette commands

- `UnoRouter: refresh balance`
- `UnoRouter: set access token`
- `UnoRouter: open billing page`

## Note on the token

`DEFAULT_TOKEN` in this repo is empty on purpose — don't commit a live token.