dsh-ollama-cloud-usage

Readme

# dsh-ollama-cloud-usage

English | [中文](README.zh.md)

DeepSeek Harness plugin that shows the remaining **Ollama Cloud** quota as a Settings section, and lets you enter or replace the Ollama Cloud API key right on that page. The section registers as `settings.section` with id `ollama-quota` and `order: -9`, so it sits directly below the shipped **Account / 账号与余额** entry. (The account page itself declares no child slot, so a plugin cannot append a card inside it; a sibling section is the supported placement.)

## What it shows

| Row | Source field |
| --- | --- |
| Session window remaining | `limits.session.usage` (fraction in `[0, 1]`) |
| Weekly window remaining | `limits.weekly.usage` |
| Per-model request counts | `limits.<window>.models[].request_count` |
| Last-4-weeks cost and period | `activity.cost`, `activity.period` |
| Key source | which credential reference resolved |
| API key editor | `credentials.describe` / `credentials.set` / `credentials.unset` over the DSH Remote |

Data comes from `GET https://ollama.com/api/usage` with `Authorization: Bearer <key>`. That is the endpoint behind the "Cloud usage" panel of `ollama.com/settings`; the local daemon at `127.0.0.1:11434` has no quota route. The response carries no plan label and no reset timestamps.

## Install

From npm:

```sh
dsh plugin --profile <profile> add dsh-ollama-cloud-usage
```

From a checkout:

```sh
npm pack --pack-destination dist
dsh plugin --profile <profile> add "$(pwd)/dist/dsh-ollama-cloud-usage-0.2.0.tgz"
```

The install reconciles `dsh.profile.bundles` and the profile applies the new layer. If the Host row does not appear, restart the app; an updated Client half needs a page refresh (the Desktop app has no client-bundle watcher).

## Custom API key

The section's **API key** card writes to the first credential reference in `keyEnvs` through the shipped `credentials` Remote — the same write path the Models settings section uses. Saving stores the key in `$DSH_HOME/.credentials.yaml` and immediately re-reads the quota; **Clear** removes it.

- The card shows the reference name, whether it is configured, and the source layer (`env`, `file`, …).
- A reference shadowed by a read-only source (a process environment variable) is reported read-only instead of silently writing to the fallback reference.
- The key is never rendered back: the input is always empty, and the snapshot route returns no secret.
- A client without the `credentials` Remote falls back to a manual-configuration hint.

## Configuration

The plugin row reads these fields, all optional:

| Field | Default | Meaning |
| --- | --- | --- |
| `keyEnvs` | `[OLLAMA_CLOUD_API_KEY, OLLAMA_API_KEY]` | credential references tried in order; the first is the one the editor writes |
| `usageUrl` | `https://ollama.com/api/usage` | usage endpoint |
| `refreshMs` | `60000` | snapshot refresh interval, minimum `5000` |
| `timeoutMs` | `15000` | per-request timeout |

Example profile patch entry:

```yaml
- id: ollama-cloud-usage
  config:
    refreshMs: 120000
```

## Credentials

The key is resolved through `ctx.credentials`, so it can live in the process environment, `$DSH_HOME/.env`, or the `refs` section of `$DSH_HOME/.credentials.yaml`:

```yaml
version: 1
refs:
  OLLAMA_CLOUD_API_KEY: <key from https://ollama.com/settings/keys>
```

A missing key is not an error: the section renders the editor and a configuration hint. The key never reaches the browser — the snapshot route returns window fractions, request counts, the activity cost, the reference order, and error labels only.

## Layout

| File | Role |
| --- | --- |
| `index.js` | Host half: credential resolution, `/api/usage` polling, JSON snapshot route |
| `client.js` | Client half: the `settings.section` registration, quota UI, and key editor |
| `cordis.patch.yml` | bundle patch inserting the plugin row |

## Verification

```sh
node --check index.js && node --check client.js
node scripts/verify.mjs
```

`scripts/verify.mjs` drives both halves offline: the Host route paths (healthy, missing key, unauthorized, transport failure, `credentials/updated` refresh) and the Client component rendered against a hook-faithful React stub, including the key editor's describe/save/clear calls, the read-only branch, and locale switching.

## Known Limitations and Deferred Work

- `ollama.com/api/usage` is unofficial but stable; the payload carries no plan name and no reset timestamps, so the page shows window usage only.
- The usage endpoint is polled and refreshed on `credentials/updated`; there is no push channel.
- Only the first reference in `keyEnvs` is editable. Additional references remain configuration-only.