Files
opencode-greenpt-usage/AGENTS.md
Stéphan Sainléger dadc93a22d chg: [opencode-greenpt-usage] port the TUI plugin to OpenCode 2
V1 TUI modules no longer load: replace ``{ id, tui }`` with
``Plugin.define({ id, setup })``, register the section on
``sidebar.content``, and expose commands through ``context.keymap.layer``.

Move balance, clock and usage state onto ``context.storage.store/memory``
so host subscribers rerender; plugin-created signals stayed stale in the
V2 renderer. Read V2 assistant messages (``type``,
``model.providerID``/``model.id``) and subscribe through ``context.data``.

Configure the package directory in ``cli.json`` instead of the source
file; document the V2 install. Typecheck, 49 unit tests and the live
GreenPT integration test pass, and the sidebar renders the balance.
2026-11-18 23:01:40 +01:00

40 lines
1.8 KiB
Markdown

# AGENTS.md
## Project
`opencode-greenpt-usage` — an OpenCode **2** 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 `Plugin.define({ id: "greenpt.usage", setup })` in
`src/index.tsx` (default export). Types come from `@opencode/plugin/tui` and
`@opencode/plugin/tui/context` as **type-only** imports; the host provides
`solid-js` and `@opentui/*` at runtime.
- The section is registered on the `sidebar.content` slot via
`context.ui.slot({ append: ..., render })`, hidden when no GreenPT credential
is present (`showWhenUnavailable` opts into a hint). Commands use
`context.keymap.layer`; `setup` returns a cleanup that unregisters the slot
and disposes the store.
- 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 (V2 `type: "assistant"`, `model.providerID`/`model.id`),
idempotent by message id, persisted with `context.storage.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 explanatory inline comments; function contract blocks are required.