@danielbdev/opencode-go-usage 0.1.2 → 0.1.4

package/README.md

@@ -18,11 +18,14 @@ A `Go usage` section at the top of the sidebar content region, above the context
 
 ```
 Go usage
-5h 0% · resets in 4h 52m
-wk 2% · resets in 3d 3h
-mo 1% · resets in 24d 20h
+5h 2% · resets in 50m
+wk 0% · resets in 4d 3h
+mo 0% · resets in 25d 20h
 ```
 
+A window whose provider status is anything other than `ok` renders that status after the countdown, so
+an exhausted or over-limit window is visible instead of showing a bare percentage.
+
 `/usage` (or the command palette) opens the same data as a detail dialog and forces a refresh.
 
 ## How it works
@@ -31,7 +34,7 @@ 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/index.ts` (`@opencode/plugin`) | Server plugin. Resolves the `opencode-go` credential, reads the usage endpoint with a 5-minute cache, re-reads once a settled turn has moved usage, 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
@@ -60,7 +63,9 @@ This endpoint is **live but undocumented**. Two consequences the code respects:
 - 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.
+The plugin mirrors the endpoint exactly. The 5-minute cache bounds how stale a background reading can
+be; a settled turn re-reads sooner, throttled to at most one read per minute so rapid turns cannot hammer
+the endpoint.
 
 ## Security
 
@@ -127,6 +132,10 @@ The workflow checks that the tag matches the version in the manifest, so a misty
 instead of publishing the wrong thing. It runs the tests and the typecheck before publishing, and npm
 attaches a provenance attestation automatically because the repository and the package are public.
 
+After a successful publish the workflow opens a **release page for the tag**, with notes generated from the
+commits since the previous release. That is where "what changed in this version" gets answered; edit the
+notes afterwards when the generated list is broader than the package being released.
+
 Versions are **independent per package**: touching one plugin never forces a release of another.
 
 The repository root stays at `0.0.0` and is never published; it only holds the workspace configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielbdev/opencode-go-usage",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "OpenCode V2 plugin that shows the OpenCode Go subscription usage in the session sidebar",
   "license": "MIT",

package/src/core/resync.test.ts

@@ -0,0 +1,42 @@
+import { test } from "node:test"
+import assert from "node:assert/strict"
+
+import { createResyncGate } from "./resync.ts"
+
+const MINUTE = 60_000
+
+test("the gate opens on the first call and then holds for the whole window", () => {
+  let clock = 1_000_000
+  const allow = createResyncGate(MINUTE, () => clock)
+
+  assert.equal(allow(), true)
+
+  clock += MINUTE - 1
+  assert.equal(allow(), false)
+})
+
+test("the gate reopens once the window has elapsed", () => {
+  let clock = 1_000_000
+  const allow = createResyncGate(MINUTE, () => clock)
+
+  assert.equal(allow(), true)
+
+  clock += MINUTE
+  assert.equal(allow(), true)
+
+  // ...and closes again immediately after opening
+  assert.equal(allow(), false)
+})
+
+test("a burst of settled turns opens the gate exactly once", () => {
+  let clock = 1_000_000
+  const allow = createResyncGate(MINUTE, () => clock)
+
+  const openedAt: number[] = []
+  for (let turn = 0; turn < 10; turn++) {
+    if (allow()) openedAt.push(turn)
+    clock += 100 // turns settling back to back
+  }
+
+  assert.deepEqual(openedAt, [0])
+})

package/src/core/resync.ts

@@ -0,0 +1,21 @@
+/**
+ * Gate for the settled-turn resync.
+ *
+ * A turn that settled is when usage actually moves, so it is the signal worth
+ * re-reading on. The endpoint is undocumented and reports only three windows, so
+ * the read is gated rather than free: `allow()` returns true at most once per
+ * `minMs` and false for every turn in between.
+ *
+ * It lives here, next to the model, so the gate is testable without a host. The
+ * clock is injectable for the same reason.
+ */
+export function createResyncGate(minMs: number, now: () => number = Date.now): () => boolean {
+  let lastAllowed = Number.NEGATIVE_INFINITY
+
+  return () => {
+    const at = now()
+    if (at - lastAllowed < minMs) return false
+    lastAllowed = at
+    return true
+  }
+}

package/src/core/usage.test.ts

@@ -1,14 +1,19 @@
 import { test } from "node:test"
 import assert from "node:assert/strict"
 
+import pkg from "../../package.json" with { type: "json" }
+
 import {
   errorSnapshot,
   formatPercent,
   formatReset,
-  formatSummary,
+  formatStatus,
   formatWindow,
+  formatWindowDetail,
   parseSnapshot,
   parseUsage,
+  USER_AGENT,
+  type UsageWindow,
 } from "./usage.ts"
 
 const NOW = Date.parse("2026-10-14T20:35:38.000Z")
@@ -85,6 +90,15 @@ test("parseUsage reports an error snapshot for a non-object payload", () => {
   }
 })
 
+test("parseUsage carries the provider status through untouched", () => {
+  const snapshot = parseUsage(
+    { usage: { rolling: { status: "overage", percent: 100, resetsAt: "2026-10-14T21:25:45.000Z" } } },
+    NOW,
+  )
+
+  assert.equal(snapshot.windows[0]?.status, "overage")
+})
+
 test("formatPercent renders an integer percent or an em dash", () => {
   assert.equal(formatPercent(2), "2%")
   assert.equal(formatPercent(0), "0%")
@@ -109,19 +123,44 @@ test("formatReset handles the last minutes, the expired case and unknown input",
   assert.equal(formatReset("not-a-date", now), "unknown")
 })
 
-test("formatWindow and formatSummary compose the rendered line", () => {
+test("formatWindow and formatWindowDetail 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%")
+  assert.equal(formatWindowDetail(snapshot.windows[0]!, NOW), "5h window    2%   resets in 50m")
 })
 
-test("formatSummary surfaces the failure state instead of percentages", () => {
+test("formatStatus stays silent in the steady state and surfaces anything else", () => {
+  // `ok` is the steady state, so it adds nothing to the line.
+  assert.equal(formatStatus("ok"), "")
+  assert.equal(formatStatus(null), "")
+  assert.equal(formatStatus(""), " ()")
+
+  // Any other status is unknown territory on an undocumented endpoint: show it
+  // verbatim rather than guessing a friendlier wording.
+  assert.equal(formatStatus("overage"), " (overage)")
+  assert.equal(formatStatus("exceeded"), " (exceeded)")
+})
+
+test("formatWindow and formatWindowDetail surface a non-ok provider status", () => {
+  const window: UsageWindow = {
+    key: "rolling",
+    short: "5h",
+    long: "5h window",
+    percent: 100,
+    resetsAt: "2026-10-14T21:25:45.000Z",
+    status: "overage",
+  }
+
+  assert.equal(formatWindow(window, NOW), "5h 100% · resets in 50m (overage)")
+  assert.equal(formatWindowDetail(window, NOW), "5h window  100%   resets in 50m (overage)")
+})
+
+test("an error snapshot renders as an unknown window, not fabricated 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")
 })
 
@@ -138,7 +177,6 @@ test("parseSnapshot accepts a snapshot that crossed the RPC boundary", () => {
   )
   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", () => {
@@ -165,3 +203,8 @@ test("parseSnapshot degrades a malformed window entry instead of throwing", () =
   assert.equal(received!.windows[2]!.key, "monthly")
 })
 
+test("USER_AGENT tracks the published package version", () => {
+  // Guards the drift a hardcoded literal invites: bump the manifest without
+  // touching the constant and this fails before the package is published.
+  assert.equal(USER_AGENT, `opencode-go-usage/${pkg.version}`)
+})

package/src/core/usage.ts

@@ -17,6 +17,17 @@
  * plain `node --test`.
  */
 
+/**
+ * User agent sent to the usage endpoint.
+ *
+ * The version travels with the request so a provider-side failure is
+ * attributable to a build. It stays a literal deliberately: `usage.test.ts`
+ * pins it to `package.json`, so a release bump fails the suite before publish
+ * (bump this line alongside the manifest) instead of adding a JSON import to
+ * the server plugin's load path.
+ */
+export const USER_AGENT = "opencode-go-usage/0.1.4"
+
 export const WINDOW_KEYS = ["rolling", "weekly", "monthly"] as const
 
 export type WindowKey = (typeof WINDOW_KEYS)[number]
@@ -173,9 +184,24 @@ export function formatReset(resetsAt: string | null, now: number): string {
   return `resets in ${minutes}m`
 }
 
+/**
+ * Provider status that qualifies the percentage, e.g. ` (overage)`.
+ *
+ * `ok` is the steady state and renders as nothing, so the common line is
+ * unchanged. Any other non-null status is surfaced verbatim: the endpoint is
+ * undocumented, so a status is the only signal that a window needs attention and
+ * it is not ours to reinterpret.
+ */
+export function formatStatus(status: string | null): string {
+  return status === null || status === "ok" ? "" : ` (${status})`
+}
+
 /** 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)}`
+  return `${window.short} ${formatPercent(window.percent)} · ${formatReset(
+    window.resetsAt,
+    now,
+  )}${formatStatus(window.status)}`
 }
 
 /** One window as a detail row, e.g. `5h window   2%   resets in 50m`. */
@@ -183,11 +209,5 @@ 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(" · ")}`
+  )}${formatStatus(window.status)}`
 }

package/src/index.ts

@@ -1,16 +1,19 @@
 import { Plugin } from "@opencode/plugin"
 
-import { errorSnapshot, parseUsage, type UsageSnapshot } from "./core/usage.ts"
+import { createResyncGate } from "./core/resync.ts"
+import { errorSnapshot, parseUsage, USER_AGENT, 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
 
+/** A settled turn moves usage; re-read on that signal, at most once per minute. */
+const RESYNC_MIN_MS = 60_000
+
 /**
  * Server plugin.
  *
@@ -75,12 +78,20 @@ export default Plugin.define({
         inFlight = null
       }
 
-      await registration.events.emit("updated", {
-        fetchedAt: snapshot.fetchedAt,
-        ok: snapshot.ok,
-        error: snapshot.error,
-        windows: snapshot.windows.map((window) => ({ ...window })),
-      })
+      // Publishing must not fail the refresh: the snapshot is already read, and
+      // `refresh()` is awaited by setup and fired-and-forgotten by the interval,
+      // where a rejection would surface as an unhandled rejection.
+      try {
+        await registration.events.emit("updated", {
+          fetchedAt: snapshot.fetchedAt,
+          ok: snapshot.ok,
+          error: snapshot.error,
+          windows: snapshot.windows.map((window) => ({ ...window })),
+        })
+      } catch {
+        // Subscribers are optional; the caller still gets the fresh snapshot.
+      }
+
       return snapshot
     }
 
@@ -97,7 +108,25 @@ export default Plugin.define({
       void refresh()
     }, REFRESH_MS)
 
+    // A settled turn is when usage actually moves, and the cache lives in this
+    // half, so the trigger belongs here: the refreshed snapshot goes out over
+    // `updated` and the TUI keeps working unchanged. The gate keeps quick
+    // successive turns from hammering an undocumented endpoint.
+    const controller = new AbortController()
+    const allowed = createResyncGate(RESYNC_MIN_MS)
+
+    void (async () => {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        if (event.type !== "session.execution.succeeded") continue
+        if (!allowed()) continue
+        void refresh()
+      }
+    })().catch(() => {
+      // A closed subscription is not a reason to fail the plugin.
+    })
+
     return () => {
+      controller.abort()
       clearInterval(timer)
     }
   },