@danielbdev/opencode-go-usage 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel
+
+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,102 @@
-# Temporary Holding Version
+# @danielbdev/opencode-go-usage
 
-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.
+An [OpenCode](https://opencode.ai) V2 plugin that shows your **OpenCode Go** subscription usage in the
+session sidebar: the rolling 5-hour window, the weekly window and the monthly window, each with the time
+left until it resets.
+
+## Install
+
+```sh
+opencode plugin add @danielbdev/opencode-go-usage
+```
+
+Requires OpenCode V2. The Go integration must be connected (`/connect` → OpenCode Go).
+
+## What it shows
+
+A `Go usage` section at the top of the sidebar content region, above the context block:
+
+```
+Go usage
+5h 0% · resets in 4h 52m
+wk 2% · resets in 3d 3h
+mo 1% · resets in 24d 20h
+```
+
+`/usage` (or the command palette) opens the same data as a detail dialog and forces a refresh.
+
+## How it works
+
+Two entrypoints in one package:
+
+| Entrypoint | Role |
+| ---------- | ---- |
+| `src/index.ts` (`@opencode/plugin`) | Server plugin. Resolves the `opencode-go` credential, reads the usage endpoint with a 5-minute cache, and publishes the snapshot over RPC. |
+| `src/tui.tsx` (`@opencode/plugin/tui`) | TUI plugin. Renders the sidebar section and the `/usage` command. |
+
+The credential never leaves the server process. The TUI plugin **cannot** read a credential — the
+OpenCode client exposes only `credential.update/activate/remove` — so the split is not a style choice,
+it is the only design that keeps the secret out of the terminal plugin. Only percentages, reset
+instants and status strings cross the RPC boundary.
+
+### Data source
+
+```
+GET https://opencode.ai/inference/go/v1/usage
+Authorization: Bearer <opencode-go key>
+```
+
+```json
+{ "usage": {
+    "rolling": { "status": "ok", "percent": 2, "resetsAt": "2026-10-14T21:25:45.000Z" },
+    "weekly":  { "status": "ok", "percent": 0, "resetsAt": "2026-10-19T00:00:00.000Z" },
+    "monthly": { "status": "ok", "percent": 0, "resetsAt": "2026-11-09T17:09:16.000Z" } } }
+```
+
+This endpoint is **live but undocumented**. Two consequences the code respects:
+
+- The three percentages are **not** monotonic (observed: rolling 2% while weekly and monthly were 0%),
+  so each value is rendered exactly as received and never derived from another window.
+- Because the endpoint can change without notice, every failure degrades to an explicit state
+  (`Usage unavailable: ...`) instead of breaking the TUI.
+
+The plugin mirrors the endpoint exactly; its own 5-minute cache is the only staleness it can add.
+
+## Development
+
+```sh
+npm install
+npm test        # node --test, no build step (Node 24 type stripping)
+npm run typecheck
+```
+
+`src/core/usage.ts` is the only module with logic worth testing and it has no host dependency, so the
+whole model, the parser and the formatters run under plain `node --test`.
+
+This package lives in a monorepo of atomic plugins: each package does one thing and installs alone.
+
+## Releasing
+
+Versions are **independent per package**: touching one plugin never forces a release of another.
+
+```sh
+npm version patch -w @danielbdev/opencode-go-usage   # or minor / major
+npm publish -w @danielbdev/opencode-go-usage --access public
+```
+
+`--access public` is required on every publish: scoped packages default to private.
+
+`npm publish --workspaces` publishes every package at once, but npm refuses to republish a version that
+already exists, so it only fits when every package is bumped together.
+
+The repository root stays at `0.0.0` and is never published; it only holds the workspace configuration.
+`npm version` also needs a version there, or npm crashes while reading the workspace manifest.
+
+## Roadmap
+
+Agent status and a to-do list are planned as **separate packages** in the same repository, not as modes
+of this one — each capability gets its own install.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@danielbdev/opencode-go-usage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenCode V2 plugin that shows the OpenCode Go subscription usage in the session sidebar",
+  "license": "MIT",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-go",
+    "usage",
+    "quota",
+    "sidebar"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/tui.tsx",
+    "./rpc": "./src/rpc.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.4"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.8",
+    "@opentui/solid": ">=0.5.8",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@opencode/client": "^2.0.4",
+    "@opencode/schema": "^2.0.4",
+    "@opencode/theme": "^2.0.4",
+    "@opentui/core": ">=0.5.8",
+    "@opentui/solid": ">=0.5.8",
+    "solid-js": ">=1.9.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/core/usage.test.ts

@@ -0,0 +1,167 @@
+import { test } from "node:test"
+import assert from "node:assert/strict"
+
+import {
+  errorSnapshot,
+  formatPercent,
+  formatReset,
+  formatSummary,
+  formatWindow,
+  parseSnapshot,
+  parseUsage,
+} from "./usage.ts"
+
+const NOW = Date.parse("2026-10-14T20:35:38.000Z")
+
+const LIVE_PAYLOAD = {
+  usage: {
+    rolling: { status: "ok", percent: 2, resetsAt: "2026-10-14T21:25:45.000Z" },
+    weekly: { status: "ok", percent: 0, resetsAt: "2026-10-19T00:00:00.000Z" },
+    monthly: { status: "ok", percent: 0, resetsAt: "2026-11-09T17:09:16.000Z" },
+  },
+}
+
+test("parseUsage reads the three windows from the live payload shape", () => {
+  const snapshot = parseUsage(LIVE_PAYLOAD, NOW)
+
+  assert.equal(snapshot.ok, true)
+  assert.equal(snapshot.error, null)
+  assert.deepEqual(
+    snapshot.windows.map((w) => [w.key, w.percent]),
+    [
+      ["rolling", 2],
+      ["weekly", 0],
+      ["monthly", 0],
+    ],
+  )
+  assert.equal(snapshot.windows[0]?.resetsAt, "2026-10-14T21:25:45.000Z")
+})
+
+test("parseUsage keeps each percent as received and never derives one window from another", () => {
+  const snapshot = parseUsage(LIVE_PAYLOAD, NOW)
+
+  // Observed live: rolling 2% while weekly and monthly were 0%. Not monotonic.
+  assert.equal(snapshot.windows[0]?.percent, 2)
+  assert.equal(snapshot.windows[1]?.percent, 0)
+  assert.equal(snapshot.windows[2]?.percent, 0)
+})
+
+test("parseUsage degrades a missing window to an unknown window instead of throwing", () => {
+  const snapshot = parseUsage({ usage: { rolling: LIVE_PAYLOAD.usage.rolling } }, NOW)
+
+  assert.equal(snapshot.windows.length, 3)
+  assert.equal(snapshot.windows[0]?.percent, 2)
+  assert.equal(snapshot.windows[1]?.percent, null)
+  assert.equal(snapshot.windows[1]?.resetsAt, null)
+  assert.equal(snapshot.ok, true)
+})
+
+test("parseUsage degrades a malformed window to unknown", () => {
+  const snapshot = parseUsage(
+    {
+      usage: {
+        rolling: { status: "ok", percent: "2", resetsAt: 12345 },
+        weekly: null,
+        monthly: { status: "ok", percent: 50, resetsAt: "not-a-date" },
+      },
+    },
+    NOW,
+  )
+
+  assert.equal(snapshot.windows[0]?.percent, null)
+  assert.equal(snapshot.windows[0]?.resetsAt, null)
+  assert.equal(snapshot.windows[1]?.percent, null)
+  assert.equal(snapshot.windows[2]?.percent, 50)
+  assert.equal(snapshot.windows[2]?.resetsAt, null)
+})
+
+test("parseUsage reports an error snapshot for a non-object payload", () => {
+  for (const payload of [null, undefined, "boom", 42, []]) {
+    const snapshot = parseUsage(payload, NOW)
+    assert.equal(snapshot.ok, false)
+    assert.ok(snapshot.error)
+    assert.equal(snapshot.windows.length, 3)
+    assert.equal(snapshot.windows[0]?.percent, null)
+  }
+})
+
+test("formatPercent renders an integer percent or an em dash", () => {
+  assert.equal(formatPercent(2), "2%")
+  assert.equal(formatPercent(0), "0%")
+  assert.equal(formatPercent(100), "100%")
+  assert.equal(formatPercent(null), "—")
+})
+
+test("formatReset renders days, hours and minutes until the reset", () => {
+  const now = Date.parse("2026-10-14T20:35:38.000Z")
+
+  assert.equal(formatReset("2026-10-14T21:25:45.000Z", now), "resets in 50m")
+  assert.equal(formatReset("2026-10-19T00:00:00.000Z", now), "resets in 4d 3h")
+  assert.equal(formatReset("2026-11-09T17:09:16.000Z", now), "resets in 25d 20h")
+})
+
+test("formatReset handles the last minutes, the expired case and unknown input", () => {
+  const now = Date.parse("2026-10-14T20:35:38.000Z")
+
+  assert.equal(formatReset("2026-10-14T20:40:38.000Z", now), "resets in 5m")
+  assert.equal(formatReset("2026-10-14T20:35:00.000Z", now), "resetting")
+  assert.equal(formatReset(null, now), "unknown")
+  assert.equal(formatReset("not-a-date", now), "unknown")
+})
+
+test("formatWindow and formatSummary compose the rendered line", () => {
+  const snapshot = parseUsage(LIVE_PAYLOAD, NOW)
+
+  assert.equal(formatWindow(snapshot.windows[0]!, NOW), "5h 2% · resets in 50m")
+  assert.equal(formatWindow(snapshot.windows[1]!, NOW), "wk 0% · resets in 4d 3h")
+  assert.equal(formatSummary(snapshot, NOW), "GO 5h 2% · wk 0% · mo 0%")
+})
+
+test("formatSummary surfaces the failure state instead of percentages", () => {
+  const snapshot = errorSnapshot("Go integration is not connected", NOW)
+
+  assert.equal(snapshot.ok, false)
+  assert.equal(formatSummary(snapshot, NOW), "GO usage unavailable")
+  assert.equal(formatWindow(snapshot.windows[0]!, NOW), "5h — · unknown")
+})
+
+test("parseSnapshot accepts a snapshot that crossed the RPC boundary", () => {
+  const sent = parseUsage(LIVE_PAYLOAD, NOW)
+  const received = parseSnapshot(JSON.parse(JSON.stringify(sent)))
+
+  assert.notEqual(received, null)
+  assert.equal(received!.ok, true)
+  assert.equal(received!.fetchedAt, NOW)
+  assert.deepEqual(
+    received!.windows.map((w) => w.percent),
+    [2, 0, 0],
+  )
+  assert.equal(received!.windows[0]!.short, "5h")
+  assert.equal(received!.windows[0]!.long, "5h window")
+  assert.equal(formatSummary(received!, NOW), "GO 5h 2% · wk 0% · mo 0%")
+})
+
+test("parseSnapshot rejects anything that is not a snapshot object", () => {
+  for (const value of [null, undefined, "boom", 42, [], {}, { windows: "nope" }]) {
+    assert.equal(parseSnapshot(value), null)
+  }
+})
+
+test("parseSnapshot degrades a malformed window entry instead of throwing", () => {
+  const received = parseSnapshot({
+    fetchedAt: "nope",
+    ok: "yes",
+    error: 7,
+    windows: [{ key: "rolling", short: "5h", long: "5h window", percent: 9 }, null, "x"],
+  })
+
+  assert.notEqual(received, null)
+  assert.equal(received!.ok, false)
+  assert.equal(received!.error, null)
+  assert.equal(received!.fetchedAt, 0)
+  assert.equal(received!.windows.length, 3)
+  assert.equal(received!.windows[0]!.percent, 9)
+  assert.equal(received!.windows[1]!.percent, null)
+  assert.equal(received!.windows[2]!.key, "monthly")
+})
+

package/src/core/usage.ts

@@ -0,0 +1,193 @@
+/**
+ * Pure model and formatting for the OpenCode Go usage windows.
+ *
+ * The payload shape was verified live against
+ * `GET https://opencode.ai/inference/go/v1/usage`:
+ *
+ *   { "usage": { "rolling": { "status": "ok", "percent": 2,
+ *                             "resetsAt": "2026-10-14T21:25:45.000Z" },
+ *                "weekly":  { ... }, "monthly": { ... } } }
+ *
+ * The 5-hour window is named `rolling`. The three percentages are NOT
+ * monotonic (observed: rolling 2% while weekly and monthly were 0%), so every
+ * value is carried through exactly as received and never derived from another
+ * window.
+ *
+ * This module is deliberately free of any host API so it stays testable with
+ * plain `node --test`.
+ */
+
+export const WINDOW_KEYS = ["rolling", "weekly", "monthly"] as const
+
+export type WindowKey = (typeof WINDOW_KEYS)[number]
+
+/** Short label used in the compact status line. */
+const SHORT_LABEL: Record<WindowKey, string> = {
+  rolling: "5h",
+  weekly: "wk",
+  monthly: "mo",
+}
+
+/** Longer label used in the detail view. */
+const LONG_LABEL: Record<WindowKey, string> = {
+  rolling: "5h window",
+  weekly: "Weekly",
+  monthly: "Monthly",
+}
+
+export interface UsageWindow {
+  readonly key: WindowKey
+  readonly short: string
+  readonly long: string
+  /** Integer 0-100 as reported by the endpoint, or null when unavailable. */
+  readonly percent: number | null
+  /** ISO-8601 UTC reset instant, or null when unavailable. */
+  readonly resetsAt: string | null
+  /** Provider-reported status string, or null when unavailable. */
+  readonly status: string | null
+}
+
+export interface UsageSnapshot {
+  readonly fetchedAt: number
+  readonly ok: boolean
+  readonly error: string | null
+  readonly windows: readonly UsageWindow[]
+}
+
+function unknownWindow(key: WindowKey): UsageWindow {
+  return {
+    key,
+    short: SHORT_LABEL[key],
+    long: LONG_LABEL[key],
+    percent: null,
+    resetsAt: null,
+    status: null,
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function readPercent(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null
+}
+
+function readInstant(value: unknown): string | null {
+  if (typeof value !== "string") return null
+  return Number.isNaN(Date.parse(value)) ? null : value
+}
+
+function readStatus(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null
+}
+
+function parseWindow(key: WindowKey, raw: unknown): UsageWindow {
+  if (!isRecord(raw)) return unknownWindow(key)
+  return {
+    key,
+    short: SHORT_LABEL[key],
+    long: LONG_LABEL[key],
+    percent: readPercent(raw.percent),
+    resetsAt: readInstant(raw.resetsAt),
+    status: readStatus(raw.status),
+  }
+}
+
+/** Snapshot for any failure: no windows, an explicit message. */
+export function errorSnapshot(message: string, now: number): UsageSnapshot {
+  return {
+    fetchedAt: now,
+    ok: false,
+    error: message,
+    windows: WINDOW_KEYS.map(unknownWindow),
+  }
+}
+
+/**
+ * Parse an endpoint payload into a snapshot.
+ *
+ * A malformed or missing window degrades to an unknown window. Only a payload
+ * that is not an object at all fails the whole snapshot.
+ */
+export function parseUsage(payload: unknown, now: number): UsageSnapshot {
+  if (!isRecord(payload)) return errorSnapshot("Malformed usage response", now)
+
+  const usage = payload.usage
+  if (!isRecord(usage)) return errorSnapshot("Usage response has no usage object", now)
+
+  return {
+    fetchedAt: now,
+    ok: true,
+    error: null,
+    windows: WINDOW_KEYS.map((key) => parseWindow(key, usage[key])),
+  }
+}
+
+/**
+ * Defensive parse of a snapshot that crossed the RPC boundary.
+ *
+ * Windows are matched positionally to WINDOW_KEYS, so a reordered or missing
+ * entry degrades to an unknown window. Returns null only when the value is not
+ * a snapshot at all.
+ */
+export function parseSnapshot(value: unknown): UsageSnapshot | null {
+  if (!isRecord(value)) return null
+
+  const rawWindows = value.windows
+  if (!Array.isArray(rawWindows)) return null
+
+  return {
+    fetchedAt:
+      typeof value.fetchedAt === "number" && Number.isFinite(value.fetchedAt) ? value.fetchedAt : 0,
+    ok: value.ok === true,
+    error: typeof value.error === "string" && value.error.length > 0 ? value.error : null,
+    windows: WINDOW_KEYS.map((key, index) => parseWindow(key, rawWindows[index])),
+  }
+}
+
+export function formatPercent(percent: number | null): string {
+  return percent === null ? "—" : `${percent}%`
+}
+
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+
+/** Human countdown to a reset instant. */
+export function formatReset(resetsAt: string | null, now: number): string {
+  if (resetsAt === null) return "unknown"
+
+  const target = Date.parse(resetsAt)
+  if (Number.isNaN(target)) return "unknown"
+
+  const remaining = target - now
+  if (remaining <= 0) return "resetting"
+
+  const days = Math.floor(remaining / DAY)
+  const hours = Math.floor((remaining % DAY) / HOUR)
+  const minutes = Math.floor((remaining % HOUR) / MINUTE)
+
+  if (days > 0) return `resets in ${days}d ${hours}h`
+  if (hours > 0) return minutes > 0 ? `resets in ${hours}h ${minutes}m` : `resets in ${hours}h`
+  return `resets in ${minutes}m`
+}
+
+/** One window as a single line, e.g. `5h 2% · resets in 50m`. */
+export function formatWindow(window: UsageWindow, now: number): string {
+  return `${window.short} ${formatPercent(window.percent)} · ${formatReset(window.resetsAt, now)}`
+}
+
+/** One window as a detail row, e.g. `5h window   2%   resets in 50m`. */
+export function formatWindowDetail(window: UsageWindow, now: number): string {
+  return `${window.long.padEnd(10)} ${formatPercent(window.percent).padStart(4)}   ${formatReset(
+    window.resetsAt,
+    now,
+  )}`
+}
+
+/** Compact status line for the TUI slot, e.g. `GO 5h 2% · wk 0% · mo 0%`. */
+export function formatSummary(snapshot: UsageSnapshot, _now: number): string {
+  if (!snapshot.ok) return "GO usage unavailable"
+  return `GO ${snapshot.windows.map((w) => `${w.short} ${formatPercent(w.percent)}`).join(" · ")}`
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+import { Plugin } from "@opencode/plugin"
+
+import { errorSnapshot, parseUsage, type UsageSnapshot } from "./core/usage.ts"
+import { UsageRpc } from "./rpc.ts"
+
+const INTEGRATION_ID = "opencode-go"
+const USAGE_URL = "https://opencode.ai/inference/go/v1/usage"
+const USER_AGENT = "opencode-go-usage/0.1.0"
+
+/** Usage moves slowly; the endpoint is undocumented, so we stay conservative. */
+const REFRESH_MS = 5 * 60_000
+const REQUEST_TIMEOUT_MS = 10_000
+
+/**
+ * Server plugin.
+ *
+ * It owns the whole credential path: the TUI cannot read a credential (the
+ * client exposes only update/activate/remove), so the fetch happens here and
+ * only the resulting snapshot crosses the RPC boundary.
+ */
+export default Plugin.define({
+  id: "opencode-go-usage.server",
+  async setup(ctx) {
+    let snapshot: UsageSnapshot = errorSnapshot("Usage not loaded yet", Date.now())
+    let inFlight: Promise<UsageSnapshot> | null = null
+
+    async function readApiKey(): Promise<string | null> {
+      const connection = await ctx.integration.connection.active(INTEGRATION_ID)
+      if (!connection) return null
+
+      const credential = await ctx.integration.connection.resolve(connection)
+      if (!credential || credential.type !== "key") return null
+
+      // Never log, print, persist or forward this value.
+      return credential.key
+    }
+
+    async function fetchSnapshot(): Promise<UsageSnapshot> {
+      const now = Date.now()
+
+      try {
+        const apiKey = await readApiKey()
+        if (apiKey === null) {
+          return errorSnapshot(`The ${INTEGRATION_ID} integration is not connected`, now)
+        }
+
+        const response = await fetch(USAGE_URL, {
+          headers: {
+            authorization: `Bearer ${apiKey}`,
+            "user-agent": USER_AGENT,
+            accept: "application/json",
+          },
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        })
+
+        if (!response.ok) {
+          return errorSnapshot(`Usage request failed with HTTP ${response.status}`, now)
+        }
+
+        return parseUsage(await response.json(), now)
+      } catch (cause) {
+        const detail = cause instanceof Error ? cause.message : "unknown error"
+        return errorSnapshot(`Usage request failed: ${detail}`, now)
+      }
+    }
+
+    /** Coalesces concurrent refreshes into one request. */
+    async function refresh(): Promise<UsageSnapshot> {
+      if (inFlight) return inFlight
+
+      inFlight = fetchSnapshot()
+      try {
+        snapshot = await inFlight
+      } finally {
+        inFlight = null
+      }
+
+      await registration.events.emit("updated", {
+        fetchedAt: snapshot.fetchedAt,
+        ok: snapshot.ok,
+        error: snapshot.error,
+        windows: snapshot.windows.map((window) => ({ ...window })),
+      })
+      return snapshot
+    }
+
+    const registration = await ctx.rpc.register(UsageRpc, {
+      get: async (input) => {
+        const wantsRefresh = (input as { refresh?: boolean } | undefined)?.refresh === true
+        return wantsRefresh ? await refresh() : snapshot
+      },
+    })
+
+    await refresh()
+
+    const timer = setInterval(() => {
+      void refresh()
+    }, REFRESH_MS)
+
+    return () => {
+      clearInterval(timer)
+    }
+  },
+})

package/src/rpc.ts

@@ -0,0 +1,41 @@
+import { Rpc } from "@opencode/plugin/rpc"
+
+/**
+ * RPC contract shared by the server plugin (producer) and the TUI plugin
+ * (consumer).
+ *
+ * The schemas are intentionally permissive. The snapshot crosses a process and
+ * validation boundary, so the TUI re-parses it defensively with
+ * `parseSnapshot` from `core/usage.ts` instead of trusting a generated type.
+ * No credential ever appears in this contract: the snapshot carries only
+ * percentages, reset instants and status strings.
+ */
+export const UsageRpc = Rpc.define({
+  id: "go-usage",
+  methods: {
+    get: {
+      input: {
+        type: "object",
+        properties: {
+          /** Bypass the refresh interval and re-read the endpoint now. */
+          refresh: { type: "boolean" },
+        },
+        additionalProperties: true,
+      },
+      output: { type: "object", additionalProperties: true },
+    },
+  },
+  events: {
+    updated: {
+      /**
+       * The full snapshot travels in the event payload, so the TUI applies it
+       * directly instead of issuing a second round trip. No properties are
+       * declared: the schema stays permissive on purpose and the consumer
+       * re-parses defensively.
+       */
+      schema: { type: "object", additionalProperties: true },
+    },
+  },
+})
+
+export type UsageRpcDefinition = typeof UsageRpc

package/src/tui.tsx

@@ -0,0 +1,174 @@
+/** @jsxImportSource @opentui/solid */
+import { Plugin } from "@opencode/plugin/tui"
+import { createMemo, createSignal, onCleanup } from "solid-js"
+
+import {
+  errorSnapshot,
+  formatWindow,
+  formatWindowDetail,
+  parseSnapshot,
+  type UsageSnapshot,
+} from "./core/usage.ts"
+import { UsageRpc } from "./rpc.ts"
+
+/** The reset countdown is the only thing that changes between refreshes. */
+const COUNTDOWN_TICK_MS = 30_000
+
+/**
+ * The host publishes a coarse sidebar tree: `sidebar.content` (the sidebar's
+ * content region, which holds the context and MCP blocks) and `sidebar.footer`.
+ * The finer strings in the 2.0.28 bundle (`sidebar.context`, `sidebar.mcp`) are
+ * internal identifiers, not slot paths — anchoring to one of those made the
+ * section disappear.
+ *
+ * There is no sub-slot between the context and MCP blocks, so the only two
+ * positions inside the content region are its start and its end. Usage owns the
+ * top: `prepend` puts it above the context block. The planned agent and to-do
+ * sections take the bottom (`append`, below MCP), so they do not compete with
+ * this one for the same edge.
+ */
+const SIDEBAR_SLOT = "sidebar.content"
+
+interface HudState {
+  snapshot: UsageSnapshot
+  /** Set when the last interaction failed, e.g. the server plugin is absent. */
+  fault: string | null
+}
+
+function initialSnapshot(): UsageSnapshot {
+  return errorSnapshot("Usage not loaded yet", Date.now())
+}
+
+function themeColor(context: Plugin.Context, key: "base" | "muted" | "accent"): string {
+  const text = (context.theme as unknown as { text?: Record<string, string | undefined> } | undefined)
+    ?.text
+  return text?.[key] ?? (key === "muted" ? "gray" : "white")
+}
+
+function detailMessage(snapshot: UsageSnapshot, now: number, fault: string | null): string {
+  if (fault !== null) return fault
+  if (!snapshot.ok && snapshot.error !== null) return snapshot.error
+
+  const rows = snapshot.windows.map((window) => formatWindowDetail(window, now))
+  const fetched = new Date(snapshot.fetchedAt).toISOString().slice(11, 19)
+  return `${rows.join("\n")}\n\nupdated ${fetched} UTC · each window resets on its own schedule`
+}
+
+/**
+ * TUI plugin.
+ *
+ * It never touches the credential: the server plugin resolves it, reads the
+ * endpoint and pushes the resulting snapshot over RPC.
+ */
+export default Plugin.define({
+  id: "opencode-go-usage.tui",
+  async setup(context) {
+    // The RPC lives in the server half. If that half is not loaded the subclient
+    // cannot be built, and the HUD must degrade instead of failing setup.
+    let usage: ReturnType<typeof context.client.rpc<typeof UsageRpc>> | undefined
+    try {
+      usage = context.client.rpc(UsageRpc)
+    } catch {
+      usage = undefined
+    }
+
+    const [state, setState] = context.storage.memory<HudState>("usage", {
+      initial: { snapshot: initialSnapshot(), fault: null },
+    })
+
+    const apply = (value: unknown) => {
+      const parsed = parseSnapshot(value)
+      if (parsed === null) return
+      setState((draft) => {
+        draft.snapshot = parsed
+        draft.fault = null
+      })
+    }
+
+    const pull = async (refresh: boolean) => {
+      if (usage === undefined) {
+        setState((draft) => {
+          draft.fault = "Usage unavailable: the usage plugin is not loaded"
+        })
+        return
+      }
+      try {
+        apply(await usage.get({ refresh }))
+      } catch (cause) {
+        const detail = cause instanceof Error ? cause.message : "unknown error"
+        setState((draft) => {
+          draft.fault = `Usage unavailable: ${detail}`
+        })
+      }
+    }
+
+    void pull(false)
+
+    const stopEvents = (() => {
+      try {
+        return usage?.events.on("updated", (event) => {
+          apply((event as { data?: unknown }).data)
+        })
+      } catch {
+        return undefined
+      }
+    })()
+
+    const UsageSection = () => {
+      const [now, setNow] = createSignal(Date.now())
+      const timer = setInterval(() => setNow(Date.now()), COUNTDOWN_TICK_MS)
+      onCleanup(() => clearInterval(timer))
+
+      const body = createMemo(() => {
+        if (state.fault !== null) return state.fault
+        if (!state.snapshot.ok && state.snapshot.error !== null) return state.snapshot.error
+        return null
+      })
+
+      return (
+        <box flexDirection="column">
+          <text fg={themeColor(context, "base")}>Go usage</text>
+          {body() !== null ? (
+            <text fg={themeColor(context, "muted")}>{body()}</text>
+          ) : (
+            state.snapshot.windows.map((window) => (
+              <text fg={themeColor(context, "muted")}>{formatWindow(window, now())}</text>
+            ))
+          )}
+        </box>
+      )
+    }
+
+    const stopSlot = context.ui.slot({
+      prepend: SIDEBAR_SLOT,
+      render: () => <UsageSection />,
+    })
+
+    context.keymap.layer(() => ({
+      mode: "global",
+      priority: 10,
+      commands: [
+        {
+          id: "opencode-go-usage.usage",
+          title: "OpenCode Go usage",
+          description: "Show the 5h, weekly and monthly Go usage windows",
+          group: "Go usage",
+          palette: true,
+          slash: { name: "usage", aliases: ["go-usage"] },
+          run: async () => {
+            await pull(true)
+            await context.ui.dialog.alert({
+              title: "OpenCode Go usage",
+              message: detailMessage(state.snapshot, Date.now(), state.fault),
+            })
+          },
+        },
+      ],
+    }))
+
+    return () => {
+      stopEvents?.()
+      stopSlot()
+    }
+  },
+})