opencode-openai-quota 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arturo Buendia
+
+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,293 @@
-# Temporary Holding Version
-
-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.
+<h1 align="center">OpenAI Quota for OpenCode 2</h1>
+
+<p align="center">Codex subscription quota in your OpenCode 2 sidebar — read from your local Codex CLI, with no tokens copied and no inference spent.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencode-openai-quota"><img src="https://img.shields.io/npm/v/opencode-openai-quota?style=flat-square&label=npm&color=cb3837" alt="npm version"></a>
+  <a href="#requirements"><img src="https://img.shields.io/badge/OpenCode-2%20TUI%20plugin-7357d5?style=flat-square" alt="OpenCode 2 TUI plugin"></a>
+  <a href="#how-it-reads-quota"><img src="https://img.shields.io/badge/Quota-local%20Codex%20app--server-159b83?style=flat-square" alt="Quota from the local Codex app-server"></a>
+  <a href="#privacy-and-network-behavior"><img src="https://img.shields.io/badge/Tokens-never%20touched-0b7285?style=flat-square" alt="Tokens are never read"></a>
+</p>
+
+<p align="center"><code>opencode plugin add opencode-openai-quota</code></p>
+
+<p align="center"><a href="#quick-install"><strong>Other install options ↓</strong></a></p>
+
+<p align="center">
+  <img src="docs/assets/quota-preview.svg" alt="Recreation of the OpenCode 2 quota panel showing a 5-hour session window with 68 percent remaining, a weekly window with 9 percent remaining in red, two available banked resets, and the next reported expiration." width="440">
+</p>
+
+<p align="center"><sub>SVG recreation of the panel with example values—not a captured screenshot. Colors come from your theme; balances at or below 25% turn amber and at or below 10% turn red.</sub></p>
+
+## What it does
+
+Adds a small panel to OpenCode 2's sidebar with the OpenAI Codex subscription windows that are active on your machine:
+
+- **Session (5h)** and **Weekly** windows, with the duration derived from the window Codex reports.
+- **Remaining quota**, not used quota. A window with `63% used` renders as `37% remaining`.
+- The **next reset** for each window as a live countdown.
+- **Available banked resets** and their next known expiration.
+- **Freshness**: when the numbers were last read, and an explicit warning when the read failed.
+
+It is a quota panel, not an API billing, usage-credit, token, or cost tracker.
+
+## How it reads quota
+
+This is the part that changed for OpenCode 2. There is no OAuth token handling and no HTTP call to OpenAI:
+
+```
+OpenCode 2 TUI  ──spawn──▶  codex app-server  ──JSON-RPC over stdio──▶  account/rateLimits/read
+```
+
+1. The TUI plugin starts a **short-lived `codex app-server`** process.
+2. It performs the `initialize` handshake, sends `initialized`, then asks for `account/rateLimits/read`.
+3. It closes stdin so Codex exits on its own, and kills the child if it lingers.
+4. The raw payload is normalized defensively: anything missing or malformed is shown as **unavailable** instead of being guessed.
+
+No model turn is created, so **checking the panel never consumes quota**. The plugin never reads `auth.json` or any credential snapshot, and it never sends your token anywhere.
+
+## Requirements
+
+- **OpenCode 2** with the TUI plugin API (`@opencode/plugin/tui`).
+- **Codex CLI** installed and logged in with the ChatGPT account whose quota you want to see:
+
+  ```sh
+  codex --version
+  codex login status
+  ```
+
+  If it is not installed or not logged in, the panel says so instead of showing numbers.
+
+> The panel reports the account signed into your **local Codex CLI**. If OpenCode uses a different OpenAI account, the numbers you see are still correct—for the Codex account, not necessarily the OpenCode one.
+
+## Quick install
+
+One command from npm; the source options below are for development or offline setups.
+
+### Option A — from npm (recommended)
+
+```sh
+opencode plugin add opencode-openai-quota
+```
+
+This installs the package and configures it globally. The server and TUI parts load together, so there is no config file to edit by hand.
+
+```sh
+opencode plugin add opencode-openai-quota@0.3.0   # pin an exact version
+opencode plugin update                            # update every package plugin
+opencode plugin update opencode-openai-quota      # update only this one
+opencode plugin list                              # see what is installed
+opencode plugin remove opencode-openai-quota      # uninstall
+```
+
+If OpenCode is already running, reload with `/reload`. The panel appears in the next session's sidebar.
+
+### Option B — installer script (Windows, from source)
+
+```powershell
+git clone https://github.com/arturobuendia/opencode-openai-quota.git
+cd opencode-openai-quota
+.\install.ps1
+```
+
+The script copies the plugin into OpenCode's global discovery folder:
+
+```text
+<config>/plugins/openai-quota/
+├── index.ts      # server part
+├── tui.tsx       # TUI part
+├── package.json
+├── tsconfig.json
+└── src/          # codex.js, quota.js, refresh.js, index.ts, tui.tsx
+```
+
+`<config>` is `%USERPROFILE%\.config\opencode` on Windows, `~/.config/opencode` (or `$XDG_CONFIG_HOME/opencode`) on macOS/Linux, or the directory selected by `OPENCODE_CONFIG_DIR`.
+
+An existing install is moved to `<config>/openai-quota-backups/` before the copy—never inside `plugins/`, where OpenCode would discover both copies. The script does not touch `opencode.json`, `cli.json`, `auth.json`, or your other plugins.
+
+### Option C — manual, any platform
+
+Copy the same files into the discovery folder:
+
+```sh
+mkdir -p ~/.config/opencode/plugins/openai-quota
+cp -R src index.ts tui.tsx tsconfig.json package.json ~/.config/opencode/plugins/openai-quota/
+```
+
+Or point OpenCode at the checkout from `opencode.json`, which loads both the server and TUI parts of the package:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    "C:/Users/YOU/Projects/opencode-openai-quota"
+  ]
+}
+```
+
+`file:///C:/Users/YOU/Projects/opencode-openai-quota` and relative paths such as `./plugins/openai-quota` are accepted too. Use `cli.json` instead when the TUI talks to a **remote** server and the plugin must run locally:
+
+```json
+{
+  "plugins": ["C:/Users/YOU/Projects/opencode-openai-quota"]
+}
+```
+
+Keep the checkout in place after configuring it. OpenCode reloads plugins when configuration changes; if the panel does not appear, run `/reload`.
+
+### Option D — install with an AI agent
+
+Paste this into any coding agent with shell access. It installs the published package, so no file is copied and no credential is touched.
+
+```text
+Install the "OpenAI Quota for OpenCode 2" plugin on this machine.
+
+Rules for this task:
+- Do not read, print, or copy any OAuth token, auth.json, or credential store.
+- Do not hand-edit opencode.json, cli.json, auth.json, the OpenCode database, or other plugins.
+- Ask before installing system packages or changing PATH.
+- Stop and report instead of guessing when a prerequisite is missing.
+
+Steps:
+1. Check that `opencode --version` reports OpenCode 2. If it is v1 or missing, stop.
+2. Check the Codex CLI with `codex --version`, then `codex login status`. If Codex is
+   missing or not logged in to a ChatGPT account, stop and report what I have to run.
+3. Install the plugin with `opencode plugin add opencode-openai-quota`. If that command
+   fails, report the exact error and stop; do not clone the repository or copy files as a
+   workaround.
+4. Confirm with `opencode plugin list` that the plugin is listed.
+5. Reload OpenCode with `/reload`, or tell me to restart the TUI if the sidebar does not
+   refresh.
+6. Verify: the session sidebar must show an "OpenAI Quota" panel. If it says
+   "Cannot read Codex quota", report the exact message under it and stop.
+
+Finish by reporting the installed version and whether the panel rendered.
+```
+
+The prompt never asks for your token and never hand-edits your configuration. If an agent proposes reading `auth.json` or writing config files directly, it went off-script—stop it and point it back here.
+
+## What appears in the sidebar
+
+```text
+OpenAI Quota
+Updated just now
+
+Session (5h)
+━━━━━━━━━━━━━━━━───────
+68% remaining
+Resets in 4h 12m
+
+Weekly
+━━━────────────────────
+9% remaining
+Resets in 2d 7h
+
+───────────────────────
+2 available banked resets
+Next expires in 9d
+```
+
+- **Window titles** follow the duration Codex reports: `Session (5h)` and `Weekly` for the usual windows, otherwise the generic name plus the real duration.
+- **Balances** are remaining percentages; the bar length follows the value, so a tiny nonzero balance is still visibly nonzero.
+- **Resets** are relative (`in 3d 4h`), recalculated every 30 seconds. A window the service gives no reset time for says `Reset unavailable`.
+- **Banked resets** are manual redemption benefits, separate from automatic resets and purchased credits. The panel shows a genuine `0`, says `Banked resets: unavailable` when the count is missing or malformed, and only shows an expiration when every available reset has a complete, valid timestamp. It never redeems anything. See [OpenAI's reset guide](https://help.openai.com/en/articles/20001498-how-resets-work-in-codex) for the distinctions and offer terms.
+
+### Reading the status line
+
+| Panel content | Meaning |
+| --- | --- |
+| `Updated just now` / `Updated 4m ago` | Time of the last successful read. |
+| `Checking · Updated 4m ago` | A read is running; the previous numbers stay visible. |
+| `Reading Codex…` | First read in progress, nothing to show yet. |
+| `Unavailable` | No successful read yet and none in flight. |
+| `Refresh failed · showing saved data` | The last read failed; the previous good numbers stay on screen. |
+| `Cannot read Codex quota` | No usable numbers yet plus the reason, for example Codex missing from `PATH`, not logged in, or the 15-second timeout. |
+| `Try /quota-refresh` | The suggested next step while nothing is displayed. |
+
+## When it refreshes
+
+- On startup.
+- **7 seconds after a session execution succeeds**, so Codex can publish the new numbers first.
+- Every **2 minutes**, as a safety net.
+- Immediately when a displayed reset time has passed, so a reset window does not sit at 0% until the next poll.
+- The countdown text alone re-renders every **30 seconds**; the panel does not re-read Codex for that.
+
+Automatic attempts respect a **60-second cooldown**, and overlapping requests share a single read instead of starting a second `codex` process. A manual refresh skips the cooldown; reset-triggered and post-execution reads wait for it like any other automatic attempt.
+
+### Manual refresh
+
+- Command palette: **Refresh OpenAI quota** (group **OpenAI quota**).
+- Slash command: **`/quota-refresh`**.
+
+## Privacy and network behavior
+
+- The plugin makes **no HTTP requests of its own** and holds **no credentials**.
+- It does not read `auth.json`, `OPENCODE_AUTH_CONTENT`, or any token file.
+- The only side effect is a local child process per read: `codex app-server`, with a 15-second timeout, stdin closed to let it exit, and a kill if it does not.
+- Codex `stderr` is drained but never rendered, so diagnostics that may contain private data cannot leak into the sidebar.
+- Errors shown in the panel never include tokens or full command output.
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `OPENCODE_QUOTA_CODEX` | `codex` | Command used to start Codex. Point it at another executable or shim. On Windows it runs through the shell, so only use a value you trust. |
+
+## Compatibility
+
+Targets **OpenCode 2** and its built-in TUI plugin API. The published package declares `@opencode/plugin` as a dependency and `@opentui/core`, `@opentui/solid`, and `solid-js` as peers, so OpenCode supplies the rendering runtime and you install nothing by hand. No `engines.opencode` range is declared; older or newer TUI APIs are not guaranteed.
+
+## Troubleshooting
+
+- **No panel:** confirm `opencode plugin list` shows the plugin (or that a source install exists at `<config>/plugins/openai-quota`), then run `/reload`.
+- **`Cannot read Codex quota`:** read the message under it. `codex` missing from `PATH` → install the Codex CLI. Not logged in → run `codex login`. Timeout → the app-server took longer than 15 seconds.
+- **Numbers look wrong:** check which account the local CLI is using with `codex login status`. The panel follows Codex, not OpenCode.
+- **Verify outside OpenCode:** `npm run probe` prints the same snapshot the panel uses, or fails with the underlying reason.
+- **Banked reset expiration says unavailable:** the count can still be right while the detail list is missing, incomplete, or uses an unknown expiration. The plugin never infers an expiration from a normal reset time.
+- **No weekly or no session row:** Codex only returned one window. The plugin shows what exists and never invents the other.
+
+## Development
+
+Node.js **20 or newer** is required for the development scripts. The package has one runtime dependency (`@opencode/plugin`) plus the OpenTUI peers that OpenCode provides.
+
+```sh
+npm test              # offline suite: codex handshake, normalization, refresh, labels
+npm run probe         # one real read through your local codex app-server
+npm run check         # syntax-check the source modules, then run the suite
+npm pack --dry-run    # inspect exactly what would be published
+```
+
+Tests use a synthetic Codex fixture (`test/fake-codex.mjs`) and injected clocks, so they stay offline and never read real credentials.
+
+| Path | Role |
+| --- | --- |
+| `src/index.ts` | Server part. Registers no resources; the work happens in the TUI. |
+| `src/tui.tsx` | Panel, sidebar slot, `/quota-refresh` command, scheduling, and disposal. |
+| `src/codex.js` | Spawns `codex app-server` and runs the JSON-RPC handshake. |
+| `src/quota.js` | Normalizes the payload; formats percentages, bars, and relative times. |
+| `src/refresh.js` | Cooldown and coalescing so only one read runs at a time. |
+| `install.ps1`, `uninstall.ps1` | Source checkout install/removal for the discovery folder. |
+
+## Publishing (maintainers)
+
+```sh
+npm login                        # once per machine
+npm run check                    # also runs automatically via prepublishOnly
+npm version patch|minor|major    # bumps package.json, commits, tags
+npm publish --access public
+git push --follow-tags
+```
+
+The `files` field limits the tarball to `src/`, the two root entrypoints, and `tsconfig.json`; tests, scripts, installers, and assets stay in the repository. Pinned installs keep their version, and `opencode plugin update` moves unpinned ones forward.
+
+## Uninstall
+
+```sh
+opencode plugin remove opencode-openai-quota
+```
+
+If you installed from a source checkout instead, run `.\uninstall.ps1`, which removes only `<config>/plugins/openai-quota`. If you configured a path in `opencode.json`/`cli.json`, delete that entry. Run `/reload` afterwards; backups under `<config>/openai-quota-backups/` are yours to delete.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts"

package/package.json

@@ -1,6 +1,47 @@
-{
-  "name": "opencode-openai-quota",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "opencode-openai-quota",
+  "version": "0.3.1",
+  "description": "OpenAI Codex subscription quota in your OpenCode 2 sidebar, read locally from the Codex CLI.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/tui.tsx"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "tui.tsx",
+    "tsconfig.json"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "openai",
+    "codex",
+    "quota",
+    "tui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arturobuendia/opencode-openai-quota.git"
+  },
+  "homepage": "https://github.com/arturobuendia/opencode-openai-quota#readme",
+  "bugs": {
+    "url": "https://github.com/arturobuendia/opencode-openai-quota/issues"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.2.0"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.6.6",
+    "@opentui/solid": ">=0.6.6",
+    "solid-js": ">=1.9.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "probe": "node scripts/probe.mjs",
+    "check": "node --check src/codex.js && node --check src/quota.js && node --check src/refresh.js && npm test",
+    "prepublishOnly": "npm run check"
+  }
+}

package/src/codex.js

@@ -0,0 +1,98 @@
+import { spawn } from "node:child_process"
+import { createInterface } from "node:readline"
+
+const quoteForShell = (value) => /[\s"]/u.test(value) ? `"${value.replace(/"/g, '""')}"` : value
+
+/**
+ * One short-lived local Codex app-server per refresh.
+ * No credential files are read. No inference turn is created.
+ * The protocol is JSON-lines with an initialize handshake before quota lookup.
+ */
+export async function readCodexRateLimits(options = {}) {
+  const command = options.command ?? process.env.OPENCODE_QUOTA_CODEX ?? "codex"
+  const args = options.args ?? ["app-server"]
+  const timeoutMs = options.timeoutMs ?? 15_000
+  return new Promise((resolve, reject) => {
+    let done = false
+    let initialized = false
+    let child
+    let timer
+    let lines
+    let killTimer
+    const finish = (error, value) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      lines?.close()
+      // End our owned child; it never outlives a refresh.
+      // Closing stdin lets Codex exit gracefully; allow a brief grace period
+      // before killing our owned process (important for Windows .cmd shims).
+      try { child?.stdin?.end() } catch {}
+      killTimer = setTimeout(() => { try { child?.kill() } catch {} }, 800)
+      killTimer.unref?.()
+      if (error) reject(error)
+      else resolve(value)
+    }
+    try {
+      // shell on Windows is needed for common npm/bun codex.cmd shims.
+      // command and args are constant by default; do not set the custom
+      // executable override to arbitrary/untrusted shell text.
+      child = process.platform === "win32"
+        // Windows shell concatenates tokens, so quote paths such as
+        // "C:\Program Files\nodejs\node.exe" and pass no separate args.
+        ? spawn([command, ...args].map(quoteForShell).join(" "), {
+          stdio: ["pipe", "pipe", "pipe"],
+          windowsHide: true,
+          shell: true,
+          env: process.env,
+        })
+        : spawn(command, args, {
+          stdio: ["pipe", "pipe", "pipe"],
+          windowsHide: true,
+          env: process.env,
+        })
+    } catch {
+      finish(new Error("Could not start the Codex CLI. Install Codex and check your PATH."))
+      return
+    }
+    timer = setTimeout(() => finish(new Error(`Codex did not answer in time (${Math.round(timeoutMs / 1000)} s).`)), timeoutMs)
+    // Drain diagnostics but don't expose potentially private stderr content.
+    child.stderr?.resume()
+    child.on("error", () => finish(new Error("Codex CLI not found or not executable. Run: codex --version")))
+    child.on("close", (code) => {
+      if (killTimer) clearTimeout(killTimer)
+      if (!done) finish(new Error(`Codex exited before returning quota (exit ${code ?? "unknown"}). Check: codex login status`))
+    })
+    const send = (value) => {
+      if (done || !child.stdin?.writable) return
+      child.stdin.write(`${JSON.stringify(value)}\n`)
+    }
+    lines = createInterface({ input: child.stdout, crlfDelay: Infinity })
+    lines.on("line", (line) => {
+      if (done || !line.trim()) return
+      let msg
+      try { msg = JSON.parse(line) } catch { return }
+      if (msg.id === 0) {
+        if (msg.error) { finish(new Error("Codex rejected the initialization handshake.")); return }
+        if (!msg.result) { finish(new Error("Codex did not confirm initialize.")); return }
+        initialized = true
+        send({ method: "initialized", params: {} })
+        send({ id: 1, method: "account/rateLimits/read" })
+      } else if (msg.id === 1 && initialized) {
+        if (msg.error) {
+          finish(new Error("Could not read quota. Check that Codex is logged in to a ChatGPT account."))
+          return
+        }
+        finish(null, msg.result)
+      }
+    })
+    send({
+      id: 0,
+      method: "initialize",
+      params: {
+        clientInfo: { name: "opencode_openai_quota", title: "OpenCode OpenAI Quota", version: "0.3.0" },
+        // The rate-limit method is documented as stable; no experimental opt-in needed.
+      },
+    })
+  })
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// OpenCode V2 package entrypoint. No server-side resources are required:
+// its TUI plugin lives in ./tui and runs against Codex installed LOCALLY.
+import { Plugin } from "@opencode/plugin"
+
+export default Plugin.define({
+  id: "openai-quota.server",
+  setup() {},
+})

package/src/quota.js

@@ -0,0 +1,98 @@
+/** Normalizes the official account/rateLimits/read response, never guessing missing figures. */
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null
+const num = (value) => typeof value === "number" && Number.isFinite(value) ? value : null
+const clamp = (value) => Math.min(100, Math.max(0, value))
+
+function asWindow(input) {
+  const data = object(input)
+  const used = num(data?.usedPercent)
+  if (used === null || used < 0 || used > 100) return null
+  const minutes = num(data?.windowDurationMins)
+  const seconds = num(data?.resetsAt)
+  return {
+    usedPercent: used,
+    remainingPercent: clamp(100 - used),
+    windowDurationMins: minutes !== null && minutes > 0 ? minutes : null,
+    resetsAt: seconds !== null && seconds > 0 ? seconds * 1000 : null,
+  }
+}
+
+export function normalizeQuota(payload, now = Date.now()) {
+  const result = object(payload)
+  if (!result) throw new Error("Codex returned an invalid rate-limit payload")
+  const byId = object(result.rateLimitsByLimitId)
+  // Codex can return limits for multiple products. Only show Codex's bucket.
+  const bucket = object(byId?.codex) ?? object(result.rateLimits)
+  if (!bucket) throw new Error("Codex returned no rate limits for this ChatGPT account")
+
+  const a = asWindow(bucket.primary)
+  const b = asWindow(bucket.secondary)
+  if (!a && !b) throw new Error("Codex returned no recognizable usage windows")
+  const windows = [a, b].filter(Boolean)
+  const knownWeekly = windows.find((w) => w.windowDurationMins === 10080) ?? null
+  const session = windows.find((w) => w.windowDurationMins === 300)
+    ?? windows.filter((w) => w !== knownWeekly).reduce((first, current) =>
+      !first || (current.windowDurationMins ?? Infinity) < (first.windowDurationMins ?? Infinity) ? current : first, null)
+  const weekly = knownWeekly ?? (windows.length > 1 ? windows.find((w) => w !== session) : null)
+  // The caller displays the raw duration when it's not one of Codex's usual windows.
+  const credits = object(result.rateLimitResetCredits)
+  const count = num(credits?.availableCount)
+  const bankedAvailable = count !== null && count >= 0 && Number.isInteger(count) ? count : null
+  const detailList = Array.isArray(credits?.credits) ? credits.credits : null
+  let nextExpiration = null
+  if (bankedAvailable !== null && bankedAvailable > 0 && detailList?.length) {
+    const dates = detailList
+      .filter((c) => object(c)?.status === "available")
+      .map((c) => num(c.expiresAt))
+      .filter((v) => v !== null && v > 0)
+    // Details can be capped or incomplete, so don't call this the earliest
+    // expiration unless ALL available credits are described with valid times.
+    if (dates.length === bankedAvailable) nextExpiration = Math.min(...dates) * 1000
+  }
+  return {
+    status: "ok",
+    updatedAt: now,
+    session,
+    weekly,
+    bankedAvailable,
+    nextExpiration,
+  }
+}
+
+export function remainingText(epochMillis, now = Date.now()) {
+  if (epochMillis === null || !Number.isFinite(epochMillis)) return "unavailable"
+  const remaining = Math.max(0, Math.ceil((epochMillis - now) / 60_000))
+  if (remaining === 0) return "now"
+  const days = Math.floor(remaining / 1440)
+  const hours = Math.floor((remaining % 1440) / 60)
+  const minutes = remaining % 60
+  return "in " + [days && `${days}d`, hours && `${hours}h`, (minutes || (!days && !hours)) && `${minutes}m`].filter(Boolean).join(" ")
+}
+
+export function progress(percent, width = 19) {
+  if (!Number.isFinite(percent)) return { filled: "", empty: "─".repeat(width) }
+  const n = Math.max(0, Math.min(width, Math.ceil((percent / 100) * width)))
+  return { filled: "━".repeat(n), empty: "─".repeat(width - n) }
+}
+
+export function durationLabel(window, fallback) {
+  if (!window) return fallback
+  const duration = window.windowDurationMins
+  if (duration === 300) return "Session (5h)"
+  if (duration === 10080) return "Weekly"
+  if (duration && duration % 1440 === 0) return `${fallback} (${duration / 1440}d)`
+  if (duration && duration % 60 === 0) return `${fallback} (${duration / 60}h)`
+  return fallback
+}
+
+/** Friendly UI status, without lying about freshness during a failed read. */
+export function updatedText(updatedAt, now = Date.now()) {
+  if (!Number.isFinite(updatedAt)) return "Never updated"
+  const minutes = Math.max(0, Math.floor((now - updatedAt) / 60_000))
+  if (minutes < 1) return "Updated just now"
+  const days = Math.floor(minutes / 1440)
+  const hours = Math.floor((minutes % 1440) / 60)
+  const mins = minutes % 60
+  const duration = [days && `${days}d`, hours && `${hours}h`, mins && `${mins}m`].filter(Boolean).join(" ")
+  return `Updated ${duration} ago`
+}

package/src/refresh.js

@@ -0,0 +1,21 @@
+/**
+ * Coalesces concurrent quota reads and enforces a minimum time between
+ * automatic attempts. A manual refresh bypasses the cooldown, but never
+ * starts another Codex process while one is running.
+ */
+export function createQuotaRefresher({ read, now = () => Date.now(), cooldownMs = 60_000 }) {
+  let lastAttempt = null
+  let pending = null
+  return {
+    getLastAttempt: () => lastAttempt,
+    refresh({ force = false } = {}) {
+      if (pending) return pending
+      if (!force && lastAttempt !== null && now() - lastAttempt < cooldownMs) {
+        return Promise.resolve(false)
+      }
+      lastAttempt = now()
+      pending = Promise.resolve().then(read).then(() => true).finally(() => { pending = null })
+      return pending
+    },
+  }
+}

package/src/tui.tsx

@@ -0,0 +1,183 @@
+import { Plugin } from "@opencode/plugin/tui"
+import { createSignal, Show } from "solid-js"
+import { readCodexRateLimits } from "./codex.js"
+import { createQuotaRefresher } from "./refresh.js"
+import { durationLabel, normalizeQuota, progress, remainingText, updatedText } from "./quota.js"
+
+type QuotaWindowData = {
+  usedPercent: number
+  remainingPercent: number
+  windowDurationMins: number | null
+  resetsAt: number | null
+}
+type QuotaSnapshot = {
+  updatedAt: number
+  session: QuotaWindowData | null
+  weekly: QuotaWindowData | null
+  bankedAvailable: number | null
+  nextExpiration: number | null
+}
+
+// The TUI plugin executes in the LOCAL terminal. It queries the user's Codex
+// app-server, and never needs the OpenCode OAuth token or a backend RPC server.
+export default Plugin.define({
+  id: "openai-quota.tui",
+  setup(context) {
+    const theme = context.theme
+    const [quota, setQuota] = createSignal<QuotaSnapshot | null>(null)
+    const [error, setError] = createSignal("")
+    const [busy, setBusy] = createSignal(false)
+    const [clock, setClock] = createSignal(Date.now())
+    let disposed = false
+    let eventTimer: ReturnType<typeof setTimeout> | undefined
+
+    async function readQuota() {
+      if (disposed) return
+      setBusy(true)
+      try {
+        const raw = await readCodexRateLimits()
+        const snapshot = normalizeQuota(raw) as QuotaSnapshot
+        if (!disposed) {
+          setQuota(snapshot)
+          setError("")
+          setClock(Date.now())
+        }
+      } catch (cause) {
+        if (!disposed) setError(cause instanceof Error ? cause.message : "Codex quota unavailable")
+      } finally {
+        if (!disposed) setBusy(false)
+      }
+    }
+
+    const refresher = createQuotaRefresher({
+      read: readQuota,
+      cooldownMs: 60_000,
+    })
+
+    function refresh(force = false) {
+      return refresher.refresh({ force }).catch(() => false)
+    }
+
+    function QuotaWindow(props: { window: QuotaWindowData; name: string }) {
+      const percent = () => Math.round(props.window.remainingPercent)
+      const bar = () => progress(props.window.remainingPercent, 23)
+      const fg = () => percent() <= 10 ? "#F87171" : percent() <= 25 ? "#FBBF24" : theme.text.base
+      const resetLabel = () => {
+        const value = remainingText(props.window.resetsAt, clock())
+        return value === "unavailable" ? "Reset unavailable" : `Resets ${value}`
+      }
+      return (
+        <box flexDirection="column" paddingTop={1}>
+          <text fg={theme.text.base}><b>{durationLabel(props.window, props.name)}</b></text>
+          <box flexDirection="row">
+            <text fg={fg()}>{bar().filled}</text>
+            <text fg={theme.text.muted}>{bar().empty}</text>
+          </box>
+          <text fg={fg()}>{percent()}% remaining</text>
+          <text fg={theme.text.muted}>{resetLabel()}</text>
+        </box>
+      )
+    }
+
+    function QuotaPanel() {
+      const snap = quota
+      const label = () => {
+        const data = snap()
+        if (!data) return busy() ? "Reading Codex…" : "Unavailable"
+        return `${busy() ? "Checking · " : ""}${updatedText(data.updatedAt, clock())}`
+      }
+      return (
+        <box flexDirection="column" paddingTop={1} paddingBottom={1}>
+          <text fg={theme.text.base}><b>OpenAI Quota</b></text>
+          <text fg={theme.text.muted}>{label()}</text>
+          <Show when={snap()}>
+            {(snapshot) => (
+              <>
+                <Show when={snapshot().session}>
+                  {(value) => <QuotaWindow window={value()} name="Session" />}
+                </Show>
+                <Show when={snapshot().weekly}>
+                  {(value) => <QuotaWindow window={value()} name="Weekly" />}
+                </Show>
+                <box flexDirection="column" paddingTop={1}>
+                  <text fg={theme.text.muted}>───────────────────────</text>
+                  <text fg={theme.text.base}>
+                    {snapshot().bankedAvailable === null
+                      ? "Banked resets: unavailable"
+                      : `${snapshot().bankedAvailable} available banked resets`}
+                  </text>
+                  <text fg={theme.text.muted}>
+                    {snapshot().nextExpiration
+                      ? `Next expires ${remainingText(snapshot().nextExpiration, clock())}`
+                      : "Next expiration unavailable"}
+                  </text>
+                </box>
+              </>
+            )}
+          </Show>
+          <Show when={Boolean(error())}>
+            <box flexDirection="column" paddingTop={1}>
+              <text fg="#FBBF24">{snap() ? "Refresh failed · showing saved data" : "Cannot read Codex quota"}</text>
+              <Show when={!snap()}>
+                <text fg={theme.text.muted}>{error()}</text>
+                <text fg={theme.text.muted}>Try /quota-refresh</text>
+              </Show>
+            </box>
+          </Show>
+        </box>
+      )
+    }
+
+    const removeSidebar = context.ui.slot({
+      append: "sidebar.content",
+      render: () => <QuotaPanel />,
+    })
+
+    // These commands belong only to this plugin; never shadow other statusline plugins.
+    context.keymap.layer(() => ({
+      mode: "global",
+      commands: [{
+        id: "openai-quota.refresh",
+        title: "Refresh OpenAI quota",
+        group: "OpenAI quota",
+        palette: true,
+        slash: { name: "quota-refresh" },
+        run: () => { void refresh(true) },
+      }],
+    }))
+
+    // Refresh after a completed OpenCode execution. Let Codex publish the new
+    // numbers for a few seconds first, then enforce a one-minute cooldown.
+    const stopExecution = context.data.on("session.execution.succeeded", () => {
+      if (eventTimer) clearTimeout(eventTimer)
+      eventTimer = setTimeout(() => {
+        eventTimer = undefined
+        if (!disposed) void refresh()
+      }, 7_000)
+    })
+
+    // Existing safety net: periodic reads, live relative times, no per-render IO.
+    void refresh()
+    const polling = setInterval(() => { if (!disposed) void refresh() }, 120_000)
+    const ticking = setInterval(() => {
+      if (disposed) return
+      const now = Date.now()
+      setClock(now)
+      const snapshot = quota()
+      // Prevent showing a zero-quota window indefinitely after it resets.
+      if (snapshot && [snapshot.session?.resetsAt, snapshot.weekly?.resetsAt]
+        .some((when) => when !== null && when !== undefined && when <= now)) {
+        void refresh()
+      }
+    }, 30_000)
+
+    return () => {
+      disposed = true
+      clearInterval(polling)
+      clearInterval(ticking)
+      if (eventTimer) clearTimeout(eventTimer)
+      stopExecution()
+      removeSidebar?.()
+    }
+  },
+})

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "@opentui/solid",
+    "allowJs": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  }
+}

package/tui.tsx

@@ -0,0 +1 @@
+export { default } from "./src/tui.tsx"