Files
opencode-greenpt-usage/AGENTS.md
Stéphan Sainléger 9c84473266 new: [opencode-greenpt-usage] track API key consumption per day and model
Show real credit spend and a per-model breakdown under the balance:

- ``src/usage.ts`` (new, pure): idempotent day buckets keyed by message
  id, day/month totals, retention pruning, validated KV serialization.
- Real spend = delta of ``x-credits-remaining`` between two free probes
  (top-ups are not counted as spend), covering every client of the key.
- Per-model detail = reconciliation of local GreenPT assistant messages
  (tokens + estimated cost, marked ``~``), re-run on every refresh and
  on ``session.idle``; last 10 sessions backfilled at startup.
- Buckets persisted in the plugin KV store (90-day window) with new
  options ``trackUsage``, ``usageWindowDays``, ``usageBackfill`` and a
  ``greenpt.usage.reset`` command.
2026-10-19 11:36:45 +02:00

35 lines
1.5 KiB
Markdown

# AGENTS.md
## Project
`opencode-greenpt-usage` — an OpenCode **TUI** plugin (Solid + OpenTUI) that
shows the remaining GreenPT API credit balance in the sidebar. Distributed by
`git clone`; there is no npm publish.
## Commands
```bash
npm install # install dev dependencies
npm test # unit tests (vitest)
npm run typecheck # tsc --noEmit
GREENPT_API_KEY=... npm run test:integration # live API test
```
## Conventions
- The plugin entry is the `default export { id, tui }` in `src/index.tsx`.
Types come from `@opencode-ai/plugin/tui` as **type-only** imports; the
host provides `solid-js` and `@opentui/solid` at runtime.
- The section is registered on the `sidebar_content` slot and is hidden when
no GreenPT credential is present (`showWhenUnavailable` opts into a hint).
- Balance probing must stay **free**: `HEAD /v1/chat/completions` returns
`400` plus `x-credits-remaining`. Never replace it with a billable call.
- Usage accounting lives in `src/usage.ts` (pure) and is consumed by the
balance store: real spend = delta of `x-credits-remaining` between
probes; per-model detail = reconciliation of local OpenCode assistant
messages, idempotent by message id, persisted in the plugin KV store.
- Credential resolution order: `apiKey` option, `GREENPT_API_KEY`, active
OpenCode `auth.json` (`greenpt`, `type: "api"`). No profile-switching
command may leak into this logic.
- No code comments unless functionally required.