opencode-providers-balances 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pavel Romanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# opencode-providers-balances
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/opencode-providers-balances.svg?color=blue)](https://www.npmjs.com/package/opencode-providers-balances)
+[![license](https://img.shields.io/github/license/fibit/opencode-providers-balances)](LICENSE)
+
+> Show provider account balances in the OpenCode TUI sidebar.
+
+An OpenCode **TUI** plugin. It renders only in the terminal interface; the web
+client is not supported.
+
+Providers live entirely in configuration — the plugin ships with no built-in
+provider data. List them under the plugin's `options.providers` and each one
+renders as a row in the `sidebar.content` slot, refreshed every 5 minutes. A
+failed refresh keeps the last-known value and marks it stale with `!`.
+
+## Features
+
+- Any number of providers, configured in `opencode.jsonc` — no code changes.
+- Declarative response parsing: `jsonPath`, `prefix`, `prefixFrom`, `require`.
+- Keys resolved from the OpenCode credential store, config, or environment.
+- Hidden rows for providers without a resolvable key or numeric value.
+
+## Prerequisites
+
+- OpenCode **V2** (the plugin API is beta).
+- A key for each provider you configure — via `/connect`, `opencode.jsonc`, or
+  an environment variable.
+
+## Install
+
+Add the plugin to `~/.config/opencode/opencode.jsonc` and configure providers:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-providers-balances",
+      "options": {
+        "refreshMinutes": 5,
+        "providers": [
+          {
+            "id": "deepseek",
+            "label": "DeepSeek",
+            "url": "https://api.deepseek.com/user/balance",
+            "integration": "deepseek",
+            "require": { "path": "is_available", "equals": true },
+            "jsonPath": "balance_infos.0.total_balance",
+            "prefixFrom": { "path": "balance_infos.0.currency", "map": { "USD": "$" } }
+          },
+          {
+            "id": "openrouter",
+            "label": "OpenRouter",
+            "url": "https://openrouter.ai/api/v1/credits",
+            "integration": "openrouter",
+            "jsonPath": "data.total_credits",
+            "prefix": "$"
+          },
+          {
+            "id": "aitunnel",
+            "label": "AITUNNEL",
+            "url": "https://api.aitunnel.ru/v1/aitunnel/balance",
+            "configProvider": "aitunnel",
+            "jsonPath": "balance",
+            "prefix": "₽"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+Restart the TUI (or `opencode service restart`) after changing the config.
+
+## Usage
+
+Once installed, the sidebar shows a bold **Balances** heading and one row per
+provider:
+
+```
+Balances
+• DeepSeek $10.01
+• OpenRouter $0.00
+• AITUNNEL ₽17779.49
+```
+
+Each row is `•` normally, or `!` when the last refresh failed but a previous
+value is kept.
+
+The three examples show the common shapes: an **integration** key with a
+currency-derived prefix (DeepSeek), an **integration** key with a fixed prefix
+(OpenRouter), and a **custom provider** key from the config with a ruble
+balance (AITUNNEL).
+
+## Configuration
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `refreshMinutes` | number | `5` | Minutes between refreshes (minimum 1). |
+| `disable` | string[] | `[]` | Provider ids to hide (convenience). |
+| `providers` | object[] | `[]` | Providers to display. Empty or missing means no panel. |
+
+### Provider fields
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `id` | yes | Stable id; used for `disable` and as the base of the default env var (sanitized — see `env`). |
+| `label` | yes | Sidebar label. |
+| `url` | yes | Balance endpoint. |
+| `jsonPath` | no | Dot path into the JSON body. Numeric segments index arrays, e.g. `balance_infos.0.total_balance`. The value must be a number (or numeric string) and is formatted with two decimals. |
+| `prefix` | no | Fixed string prepended to the value (e.g. `"$"`, `"€"`, `"₽"`). |
+| `prefixFrom` | no | Derive the prefix from a value: `{ path, map, fallback? }`, e.g. `{ "path": "currency", "map": { "USD": "$" } }`. Takes precedence over `prefix`. |
+| `require` | no | Gate the row: `{ path, equals }`; hidden unless the value at `path` strictly equals `equals`. |
+| `authScheme` | no | Authorization scheme, default `Bearer`. |
+| `env` | no | Env var holding the key, default `<SANITIZED_ID>_API_KEY` — the id uppercased with runs of non-alphanumerics turned into `_` (e.g. `router-ai` → `ROUTER_AI_API_KEY`). |
+| `key` | no | Literal key (discouraged — prefer env/integration). |
+| `integration` | no | Id in the V2 SQLite `credential` table. |
+| `configProvider` | no | Provider id in `opencode.jsonc` whose `settings.apiKey` to use. |
+
+### Key resolution
+
+For each provider, the key is taken from the first source that has one:
+
+1. `key` in the provider spec (literal — discouraged)
+2. an integration in the OpenCode V2 SQLite credential store (`integration`)
+3. the matching provider's `settings.apiKey` in `opencode.jsonc` (`configProvider`)
+4. an environment variable (`env`, default `<ID>_API_KEY`)
+
+## Notes
+
+- A provider whose key cannot be resolved is hidden rather than shown as stale.
+- A malformed spec (e.g. a `jsonPath` that resolves to a non-number) hides that
+  row instead of failing the plugin.
+- OpenAI's prepaid balance is not exposed via API, so it cannot be shown.
+- RouterAI's `/credits` value is billed in rubles, hence `₽`. AITUNNEL's
+  `/balance` is also in rubles.
+- A provider configured directly in `opencode.jsonc` (not via `/connect`) uses
+  `configProvider` — see the AITUNNEL example.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run typecheck
+```
+
+Runtime dependencies (`@opencode/plugin`, `@opentui/solid`, `solid-js`) are
+provided by OpenCode and declared as `peerDependencies`; they are installed
+locally only for type-checking.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/index.ts

@@ -0,0 +1,7 @@
+import { Plugin } from "@opencode/plugin"
+
+// Server-side entrypoint. All behavior lives in the TUI entrypoint (./tui).
+export default Plugin.define({
+  id: "providers-balances",
+  setup() {},
+})

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "opencode-providers-balances",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "OpenCode TUI plugin that shows provider account balances in the session sidebar. Providers are configured entirely in opencode.jsonc.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode2",
+    "balance",
+    "usage",
+    "quota",
+    "sidebar",
+    "tui"
+  ],
+  "license": "MIT",
+  "author": "Pavel Romanov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fibit/opencode-providers-balances.git"
+  },
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./tui": "./tui.tsx"
+  },
+  "files": [
+    "index.ts",
+    "providers.ts",
+    "tui.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-strip-types test.mjs",
+    "typecheck": "tsc --noEmit --skipLibCheck --module esnext --moduleResolution bundler --target esnext --jsx preserve --jsxImportSource @opentui/solid index.ts tui.tsx providers.ts"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": "beta",
+    "@opentui/core": ">=0.5.8",
+    "@opentui/solid": ">=0.5.8",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "beta",
+    "@opentui/core": ">=0.5.8",
+    "@opentui/solid": ">=0.5.8",
+    "solid-js": "1.9.12",
+    "typescript": "^5.9.0"
+  }
+}

package/providers.ts

@@ -0,0 +1,573 @@
+/**
+ * Balance fetching for the opencode-providers-balances plugin.
+ *
+ * Holds the core logic: declarative formatting, key resolution, and the
+ * balance fetch. No OpenTUI/JSX imports here, so it is safe to import from
+ * both the server and TUI entrypoints.
+ *
+ * Provider definitions live entirely in plugin options (opencode.jsonc); this
+ * file contains no built-in provider data.
+ */
+
+import { readFileSync, existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { join, resolve } from "node:path"
+import { createRequire } from "node:module"
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_REFRESH_MINUTES = 5
+const FETCH_TIMEOUT_MS = 10_000
+const KEY_CACHE_MS = 60_000
+const CONFIG_CACHE_MS = 60_000
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ProviderKey = string
+
+export interface Provider {
+  /** Stable id, also the render/state key. */
+  id: ProviderKey
+  /** Sidebar label. */
+  label: string
+  /** Balance endpoint. */
+  url: string
+  /** Authorization scheme; defaults to `Bearer`. */
+  authScheme?: string
+  /** Environment variable holding the key. */
+  env: string
+  /** Integration id in the V2 SQLite credential store, when applicable. */
+  integration?: string
+  /** Provider id in `opencode.jsonc` whose `settings.apiKey` to use. */
+  configProvider?: string
+  /** Literal key supplied via options (discouraged). */
+  literalKey?: string
+  /** Turn a response body into the display value, or null when unavailable. */
+  format: (body: unknown) => string | null
+}
+
+/**
+ * Declarative provider spec accepted from plugin options. A spec is turned
+ * into a formatter from three optional rules:
+ *   - `require`    gate: return null unless path === equals.
+ *   - `jsonPath`   dot path into the body (numeric segments index arrays).
+ *   - `prefix` / `prefixFrom`   fixed or value-derived display prefix.
+ */
+export interface ProviderConfig {
+  /** Stable id; also the base of the default env var and the `disable` key. */
+  id: string
+  /** Sidebar label. */
+  label: string
+  /** Balance endpoint. */
+  url: string
+  /** Authorization scheme; defaults to `Bearer`. */
+  authScheme?: string
+  /** Env var holding the key; defaults to `<SANITIZED_ID>_API_KEY`. */
+  env?: string
+  /** Literal key (discouraged — prefer env/integration). */
+  key?: string
+  /** Integration id in the V2 SQLite `credential` table. */
+  integration?: string
+  /** Provider id in `opencode.jsonc` whose `settings.apiKey` to use. */
+  configProvider?: string
+  /** Dot path into the JSON body; numeric segments index arrays. */
+  jsonPath?: string
+  /** Fixed string prepended to the value (e.g. `"$"`, `"€"`, `"₽"`). */
+  prefix?: string
+  /** Derive the prefix from a body value; takes precedence over `prefix`. */
+  prefixFrom?: { path: string; map: Record<string, string>; fallback?: string }
+  /** Gate the row: hide it unless the value at `path` strictly equals `equals`. */
+  require?: { path: string; equals: unknown }
+}
+
+export interface BalancesOptions {
+  /** Providers to display; empty or missing means no panel. */
+  providers?: ProviderConfig[]
+  /** Provider ids to hide. */
+  disable?: string[]
+  /** Minutes between refreshes (minimum 1). */
+  refreshMinutes?: number
+}
+
+/** Result of fetching one provider in a refresh cycle. */
+export interface FetchResult {
+  /** Display value; empty when unavailable. */
+  value: string
+  /** True when the provider is configured but the last refresh failed. */
+  stale: boolean
+  /**
+   * True when the provider must not be rendered: no usable key, a failed
+   * `require` gate, or a response with no numeric value. Distinguishing this
+   * from `stale` keeps an intentionally unavailable provider from showing a
+   * previous balance marked stale.
+   */
+  hidden: boolean
+}
+
+export interface BalanceState {
+  value: string
+  stale: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Declarative formatting
+// ---------------------------------------------------------------------------
+
+/** Read a dot path from a JSON body; numeric segments index arrays. */
+export function jsonPathGet(body: unknown, path: string): unknown {
+  let cur: unknown = body
+  for (const part of path.split(".")) {
+    if (cur == null || typeof cur !== "object") return undefined
+    cur = Array.isArray(cur) ? cur[Number(part)] : (cur as Record<string, unknown>)[part]
+  }
+  return cur
+}
+
+/**
+ * Coerce a value to a finite number, or null. Only a real number or a non-blank
+ * numeric string counts; `null`, booleans, arrays, objects and blank strings are
+ * rejected rather than coerced (so `Number(null) === 0` can't masquerade as a
+ * zero balance).
+ */
+function num(v: unknown): number | null {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null
+  if (typeof v === "string") {
+    const t = v.trim()
+    if (!t) return null
+    const n = Number(t)
+    return Number.isFinite(n) ? n : null
+  }
+  return null
+}
+
+/** Build a formatter from the declarative rules in a spec. */
+function buildFormatter(spec: ProviderConfig): (body: unknown) => string | null {
+  return (body) => {
+    if (spec.require && jsonPathGet(body, spec.require.path) !== spec.require.equals) return null
+    if (!spec.jsonPath) return null
+    const n = num(jsonPathGet(body, spec.jsonPath))
+    if (n == null) return null
+    let prefix = spec.prefix ?? ""
+    if (spec.prefixFrom) {
+      const raw = jsonPathGet(body, spec.prefixFrom.path)
+      prefix = spec.prefixFrom.map[String(raw)] ?? spec.prefixFrom.fallback ?? ""
+    }
+    return `${prefix}${n.toFixed(2)}`
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config access (opencode.jsonc)
+// ---------------------------------------------------------------------------
+
+let configCache: { at: number; data: Record<string, unknown> | null } | null = null
+
+/**
+ * Root directories OpenCode uses for global state, honoring the XDG base
+ * directories exactly like OpenCode's own `roots()`: `$XDG_CONFIG_HOME` and
+ * `$XDG_DATA_HOME`, falling back to `~/.config` and `~/.local/share` when unset
+ * or empty.
+ */
+export function opencodeRoots(app = "opencode"): { config: string; data: string } {
+  const home = homedir()
+  const configHome = process.env.XDG_CONFIG_HOME || join(home, ".config")
+  const dataHome = process.env.XDG_DATA_HOME || join(home, ".local", "share")
+  return { config: join(configHome, app), data: join(dataHome, app) }
+}
+
+/**
+ * Candidate global config files in precedence order, honoring OpenCode's
+ * `OPENCODE_CONFIG` (explicit file) and `OPENCODE_CONFIG_DIR` (config directory
+ * override) before the XDG-derived default.
+ */
+export function configFilePaths(): string[] {
+  const dir = process.env.OPENCODE_CONFIG_DIR || opencodeRoots().config
+  const files = ["opencode.jsonc", "opencode.json"].map((name) => join(dir, name))
+  const explicit = process.env.OPENCODE_CONFIG
+  return explicit ? [explicit, ...files] : files
+}
+
+function readConfig(): Record<string, unknown> | null {
+  const now = Date.now()
+  if (configCache && now - configCache.at < CONFIG_CACHE_MS) return configCache.data
+  let data: Record<string, unknown> | null = null
+  const inline = process.env.OPENCODE_CONFIG_CONTENT
+  if (inline) {
+    try {
+      data = parseJsonc(inline)
+    } catch {}
+  }
+  if (!data) {
+    for (const p of configFilePaths()) {
+      if (!existsSync(p)) continue
+      try {
+        data = parseJsonc(readFileSync(p, "utf8"))
+        break
+      } catch {}
+    }
+  }
+  configCache = { at: now, data }
+  return data
+}
+
+/**
+ * Parse JSONC: strip line/block comments and trailing commas, then hand the
+ * result to `JSON.parse`. Comments and commas inside string values are left
+ * intact. Only `"` delimits strings, matching JSONC.
+ */
+export function parseJsonc(raw: string): Record<string, unknown> {
+  return JSON.parse(stripTrailingCommas(stripComments(raw))) as Record<string, unknown>
+}
+
+/** Remove line and block comments, ignoring any that appear inside strings. */
+function stripComments(raw: string): string {
+  let out = ""
+  let inString = false
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i]
+    const next = raw[i + 1]
+    if (inString) {
+      out += ch
+      if (ch === "\\") {
+        out += next ?? ""
+        i++
+      } else if (ch === '"') {
+        inString = false
+      }
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      out += ch
+      continue
+    }
+    if (ch === "/" && next === "/") {
+      while (i < raw.length && raw[i] !== "\n") i++
+      out += "\n"
+      continue
+    }
+    if (ch === "/" && next === "*") {
+      i += 2
+      while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/")) i++
+      i++
+      continue
+    }
+    out += ch
+  }
+  return out
+}
+
+/** Drop commas that precede a closing brace/bracket, ignoring string values. */
+function stripTrailingCommas(s: string): string {
+  let out = ""
+  let inString = false
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]
+    if (inString) {
+      out += ch
+      if (ch === "\\") {
+        out += s[i + 1] ?? ""
+        i++
+      } else if (ch === '"') {
+        inString = false
+      }
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      out += ch
+      continue
+    }
+    if (ch === ",") {
+      let j = i + 1
+      while (j < s.length && /\s/.test(s[j])) j++
+      if (s[j] === "}" || s[j] === "]") continue
+    }
+    out += ch
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Key resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Read this plugin's own options from `opencode.jsonc`.
+ *
+ * OpenCode V2 beta delivers plugin options to the server entrypoint but not to
+ * the TUI entrypoint, so the TUI falls back to reading them from the config.
+ */
+export function loadOptionsFromConfig(selfHints: string[] = ["opencode-providers-balances"]): BalancesOptions {
+  const cfg = readConfig()
+  const entries = cfg?.plugins
+  if (!Array.isArray(entries)) return {}
+  for (const entry of entries) {
+    if (Array.isArray(entry)) {
+      if (matchesSelf(entry[0], selfHints)) return (entry[1] ?? {}) as BalancesOptions
+    } else if (entry && typeof entry === "object") {
+      const obj = entry as Record<string, unknown>
+      if (matchesSelf(obj.package, selfHints)) return (obj.options ?? {}) as BalancesOptions
+    }
+  }
+  return {}
+}
+
+function matchesSelf(spec: unknown, hints: string[]): boolean {
+  if (typeof spec !== "string") return false
+  const norm = spec.replace(/\\/g, "/").toLowerCase()
+  return hints.some((h) => norm.includes(h.toLowerCase()))
+}
+
+// --- SQLite credential store (V2) ------------------------------------------
+
+/** Lazily resolve a SQLite driver across Bun and Node. */
+function loadSqlite(): { open: (path: string) => unknown } | null {
+  const bun = tryRequire("bun:sqlite")
+  if (bun?.Database) {
+    return { open: (p) => new bun.Database(p, { readonly: true }) }
+  }
+  const node = tryRequire("node:sqlite")
+  if (node?.DatabaseSync) {
+    return { open: (p) => new node.DatabaseSync(p, { readOnly: true }) }
+  }
+  return null
+}
+
+function tryRequire(mod: string): any {
+  const attempts: Array<() => unknown> = [
+    () => (import.meta as any).require?.(mod),
+    () => (globalThis as any).require?.(mod),
+    () => createRequire(import.meta.url)(mod),
+    () => (Function("return require")() as any)(mod),
+  ]
+  for (const attempt of attempts) {
+    try {
+      const result = attempt()
+      if (result) return result
+    } catch {}
+  }
+  return null
+}
+
+/** Stored credential keys by integration id, cached briefly. */
+let keyCache: { at: number; keys: Record<string, string> } | null = null
+
+function allIntegrationKeys(): Record<string, string> {
+  const now = Date.now()
+  if (keyCache && now - keyCache.at < KEY_CACHE_MS) return keyCache.keys
+  keyCache = { at: now, keys: readAllCredentials() }
+  return keyCache.keys
+}
+
+/** Path to the SQLite credential store, or null when no persistent DB is used. */
+export function databasePath(): string | null {
+  const override = process.env.OPENCODE_DB
+  const dataDir = opencodeRoots().data
+  if (override) return override === ":memory:" ? null : resolve(dataDir, override)
+  return join(dataDir, "opencode.db")
+}
+
+function readAllCredentials(): Record<string, string> {
+  const path = databasePath()
+  if (!path || !existsSync(path)) return {}
+  const driver = loadSqlite()
+  if (!driver) return {}
+  let db: any
+  try {
+    db = driver.open(path)
+    const rows = runQuery(db, "SELECT integration_id, value FROM credential") as Array<{
+      integration_id?: unknown
+      value?: unknown
+    }>
+    const out: Record<string, string> = {}
+    for (const row of rows ?? []) {
+      const id = row?.integration_id != null ? String(row.integration_id) : ""
+      const key = row?.value != null ? extractKey(JSON.parse(String(row.value))) : null
+      if (id && key) out[id] = key
+    }
+    return out
+  } catch {
+    return {}
+  } finally {
+    try {
+      db?.close?.()
+    } catch {}
+  }
+}
+
+/** Run a query against either the Bun or Node SQLite driver. */
+function runQuery(db: any, sql: string): unknown[] {
+  try {
+    const stmt = typeof db.query === "function" ? db.query(sql) : db.prepare(sql)
+    return stmt.all()
+  } catch {
+    return []
+  }
+}
+
+function extractKey(v: unknown): string | null {
+  if (!v) return null
+  if (typeof v === "string") return v.trim() || null
+  if (typeof v === "object") {
+    for (const field of ["key", "token", "apiKey", "value"]) {
+      const s = (v as Record<string, unknown>)[field]
+      if (typeof s === "string" && s.trim()) return s.trim()
+    }
+  }
+  return null
+}
+
+/** Resolve a provider's key from the first source that has one. */
+function keyForProvider(p: Provider): string | null {
+  if (p.literalKey?.trim()) return p.literalKey.trim()
+  if (p.integration) {
+    const k = allIntegrationKeys()[p.integration]
+    if (k) return k
+  }
+  if (p.configProvider) {
+    const cfg = readConfig()
+    const providers = cfg?.providers as Record<string, any> | undefined
+    const k = extractKey(providers?.[p.configProvider]?.settings?.apiKey)
+    if (k) return k
+  }
+  return process.env[p.env]?.trim() || null
+}
+
+// ---------------------------------------------------------------------------
+// Provider construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a conventional, settable env var name from a provider id:
+ * uppercase, runs of characters that are not `A-Z0-9` collapsed to `_`, and a
+ * leading `_` added when the result would otherwise start with a digit. So
+ * `router-ai` -> `ROUTER_AI_API_KEY` rather than `ROUTER-AI_API_KEY`.
+ */
+function defaultEnvVar(id: string): string {
+  const base = id
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+  const safe = base === "" ? "PROVIDER" : /^[0-9]/.test(base) ? `_${base}` : base
+  return `${safe}_API_KEY`
+}
+
+/** Convert a declarative spec into an executable provider. */
+function toProvider(spec: ProviderConfig): Provider {
+  return {
+    id: spec.id,
+    label: spec.label,
+    url: spec.url,
+    authScheme: spec.authScheme,
+    env: spec.env ?? defaultEnvVar(spec.id),
+    integration: spec.integration,
+    configProvider: spec.configProvider,
+    literalKey: spec.key,
+    format: buildFormatter(spec),
+  }
+}
+
+/**
+ * Build executable providers from configuration. Duplicate ids keep the last
+ * spec; `disable` removes ids. An empty or missing list yields no providers.
+ */
+export function buildProviders(options?: BalancesOptions): Provider[] {
+  const disabled = new Set(options?.disable ?? [])
+  const seen = new Set<string>()
+  const ordered: Provider[] = []
+  const specs = options?.providers ?? []
+  for (const spec of specs) {
+    if (!spec?.id || disabled.has(spec.id)) continue
+    if (seen.has(spec.id)) {
+      // Last spec wins; replace in place to preserve position.
+      const idx = ordered.findIndex((p) => p.id === spec.id)
+      ordered[idx] = toProvider(spec)
+    } else {
+      seen.add(spec.id)
+      ordered.push(toProvider(spec))
+    }
+  }
+  return ordered
+}
+
+// ---------------------------------------------------------------------------
+// Fetching
+// ---------------------------------------------------------------------------
+
+export async function fetchProvider(p: Provider): Promise<FetchResult> {
+  const key = keyForProvider(p)
+  // Hidden rather than stale when unconfigured.
+  if (!key) return { value: "", stale: false, hidden: true }
+
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const scheme = p.authScheme ?? "Bearer"
+    const res = await fetch(p.url, {
+      headers: { Authorization: `${scheme} ${key}` },
+      signal: ctrl.signal,
+    })
+    if (!res.ok) return { value: "", stale: true, hidden: false }
+    const value = p.format(await res.json())
+    // A response that parses but yields no value hides the row; it is not a
+    // failed fetch, so it must not resurface as a stale balance.
+    return value ? { value, stale: false, hidden: false } : { value: "", stale: false, hidden: true }
+  } catch {
+    return { value: "", stale: true, hidden: false }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Merge fresh results into state. Successful values replace; a failed refresh
+ * keeps the previous value marked stale; a hidden provider is removed.
+ */
+export function collect(
+  state: Map<ProviderKey, BalanceState>,
+  providers: Provider[],
+  results: FetchResult[],
+): void {
+  providers.forEach((p, i) => {
+    const fresh = results[i]
+    if (!fresh || fresh.hidden) {
+      state.delete(p.id)
+      return
+    }
+    if (fresh.value) {
+      state.set(p.id, { value: fresh.value, stale: false })
+      return
+    }
+    const prev = state.get(p.id)
+    if (prev?.value) state.set(p.id, { value: prev.value, stale: true })
+    else state.delete(p.id)
+  })
+}
+
+/** One renderable balance line: a provider that currently has a value. */
+export interface BalanceRow {
+  id: ProviderKey
+  label: string
+  value: string
+  stale: boolean
+}
+
+/** Providers with a current value, in provider order. */
+export function balanceRows(state: Map<ProviderKey, BalanceState>, providers: Provider[]): BalanceRow[] {
+  const rows: BalanceRow[] = []
+  for (const p of providers) {
+    const s = state.get(p.id)
+    if (!s?.value) continue
+    rows.push({ id: p.id, label: p.label, value: s.value, stale: s.stale })
+  }
+  return rows
+}
+
+export function renderRows(state: Map<ProviderKey, BalanceState>, providers: Provider[]): string[] {
+  return balanceRows(state, providers).map((r) => `${r.stale ? "!" : "•"} ${r.label} ${r.value}`)
+}

package/tui.tsx

@@ -0,0 +1,86 @@
+/** @jsxImportSource @opentui/solid */
+import { Plugin } from "@opencode/plugin/tui"
+import { createSignal, For } from "solid-js"
+import {
+  balanceRows,
+  buildProviders,
+  collect,
+  DEFAULT_REFRESH_MINUTES,
+  fetchProvider,
+  loadOptionsFromConfig,
+  type BalanceRow,
+  type BalanceState,
+  type BalancesOptions,
+  type Provider,
+  type ProviderKey,
+} from "./providers"
+
+/** Resolve options, falling back to opencode.jsonc when the context gives none. */
+function resolveOptions(contextOptions: unknown): BalancesOptions {
+  const fromContext = (contextOptions ?? {}) as BalancesOptions
+  if (Array.isArray(fromContext.providers) && fromContext.providers.length > 0) return fromContext
+  const fromConfig = loadOptionsFromConfig()
+  return {
+    ...fromConfig,
+    ...fromContext,
+    providers: fromContext.providers ?? fromConfig.providers,
+    refreshMinutes: fromContext.refreshMinutes ?? fromConfig.refreshMinutes,
+    disable: fromContext.disable ?? fromConfig.disable,
+  }
+}
+
+export default Plugin.define({
+  id: "providers-balances.tui",
+  setup(context) {
+    const options = resolveOptions(context.options)
+    const providers: Provider[] = buildProviders(options)
+    const refreshMs = Math.max(1, options.refreshMinutes ?? DEFAULT_REFRESH_MINUTES) * 60_000
+
+    const state = new Map<ProviderKey, BalanceState>()
+    const [rows, setRows] = createSignal<BalanceRow[]>([])
+    const [loading, setLoading] = createSignal(providers.length > 0)
+    let stopped = false
+
+    async function refresh() {
+      const results = await Promise.all(providers.map((p) => fetchProvider(p)))
+      if (stopped) return
+      collect(state, providers, results)
+      setRows(balanceRows(state, providers))
+      setLoading(false)
+    }
+
+    const unregister = context.ui.slot({
+      append: "sidebar.content",
+      // Show a placeholder during the first fetch, then either the rows or
+      // nothing at all (never a bare heading).
+      render: () => {
+        const list = rows()
+        if (!list.length && !loading()) return null
+        return (
+          <text>
+            <b>Balances</b>
+            <For each={list}>
+              {(r) => (
+                <span style={{ fg: r.stale ? context.theme.text.feedback.warning.base : context.theme.text.base }}>
+                  {`\n${r.stale ? "!" : "•"} ${r.label} ${r.value}`}
+                </span>
+              )}
+            </For>
+            {loading() && !list.length ? "\n…" : ""}
+          </text>
+        )
+      },
+    })
+
+    // Register first, then fetch in the background: a slow or unreachable
+    // endpoint must not delay setup or the first render.
+    void refresh()
+    const timer = setInterval(() => void refresh(), refreshMs)
+
+    return () => {
+      stopped = true
+      clearInterval(timer)
+      unregister()
+    }
+  },
+})