oc-usage-limits-plugin 0.0.1 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mynameistito
+
+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

@@ -0,0 +1,118 @@
+# oc-usage-limits-plugin
+
+OpenCode TUI plugin that shows Codex and ZAI usage limits in the sidebar and prompt footer.
+
+## Features
+
+- Adds a `Usage Limits` block under the sidebar `Context` section.
+- Shows current Codex usage windows from OpenAI/Codex auth.
+- Shows current ZAI quota windows from ZAI Coding Plan auth.
+- Adds compact prompt-footer usage when the current session uses an OpenAI or ZAI Coding Plan model.
+- Providers are toggled from `~/.config/opencode/usage-limits.jsonc`.
+- Reads OpenCode-connected credentials first, then falls back to explicit config/env credentials.
+
+## Install
+
+Add the TUI plugin to `~/.config/opencode/tui.json`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["oc-usage-limits-plugin"],
+}
+```
+
+OpenCode TUI plugins are configured in `tui.json`, not `opencode.jsonc`.
+
+Restart OpenCode after changing TUI plugin config.
+
+## Usage Config
+
+Create `~/.config/opencode/usage-limits.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/mynameistito/oc-usage-limits-plugin/main/usage-limits.schema.json",
+  "enabled": true,
+  "refreshIntervalSeconds": 60,
+  "requestTimeoutMs": 10000,
+  "showErrors": true,
+  "providers": {
+    "codex": {
+      "enabled": true,
+      "label": "Codex",
+      "authPath": "~/.codex/auth.json",
+    },
+    "zai": {
+      "enabled": true,
+      "label": "ZAI",
+      "authPath": "~/.local/share/opencode/auth.json",
+      "apiKey": "{env:OC_ZAI_API_KEY}",
+      "authorizationScheme": "raw",
+    },
+  },
+}
+```
+
+Disabled providers are hidden:
+
+```jsonc
+"providers": {
+  "codex": { "enabled": true },
+  "zai": { "enabled": false }
+}
+```
+
+## Credential Lookup
+
+Codex lookup order:
+
+1. OpenCode auth at `~/.local/share/opencode/auth.json`, provider `openai`.
+2. Codex auth file from `authPath`, default `~/.codex/auth.json`.
+
+ZAI lookup order:
+
+1. Config `authPath`, which can point at OpenCode auth JSON or a simple `{ "key": "..." }` / `{ "apiKey": "..." }` JSON file.
+2. OpenCode auth at `~/.local/share/opencode/auth.json`, provider `zai-coding-plan`.
+3. OpenCode auth provider `zai`.
+4. Config `apiKey`, including `{env:OC_ZAI_API_KEY}` references.
+
+## Display
+
+Sidebar rows look like:
+
+```txt
+Usage Limits
+codex
+  5h: 42% used resets 1h 2m
+  weekly: 12% used resets 3d 4h
+ZAI
+  tokens: 18% used resets 2h
+  MCP: 6% used
+```
+
+Prompt footer shows compact usage when the current session model belongs to a supported provider:
+
+```txt
+5h: 42% used resets 1h 2m
+```
+
+Provider mapping:
+
+- OpenCode provider `openai` -> Codex usage.
+- OpenCode provider `zai-coding-plan` -> ZAI token usage.
+
+## Development
+
+```powershell
+bun install
+bun run typecheck
+```
+
+The package exposes a TUI entrypoint at `oc-usage-limits-plugin/tui` for OpenCode's package plugin loader.
+
+## Notes
+
+- The refresh interval defaults to 60 seconds.
+- The effective minimum refresh interval is 15 seconds.
+- Errors are intentionally short and do not include auth tokens or response bodies.

package/dist/index.d.mts

@@ -0,0 +1,8 @@
+//#region src/index.d.ts
+/** OpenCode plugin module exported for the `oc-usage-limits-plugin/tui` entry. */
+declare const _default: {
+  id: string;
+  tui: import("@opencode-ai/plugin/tui").TuiPlugin;
+};
+//#endregion
+export { _default as default };

package/dist/index.mjs

@@ -0,0 +1,848 @@
+import { For, Show, createSignal } from "solid-js";
+import { Fragment, jsx, jsxs } from "@opentui/solid/jsx-runtime";
+import { homedir } from "node:os";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+//#region src/format.ts
+/**
+* Formats a positive duration in seconds into the compact label used by the TUI.
+*
+* Values that are missing, invalid, or already elapsed are displayed as `now`.
+* Positive values are rounded up to the next minute so near-future resets never
+* appear as zero minutes remaining.
+*
+* @param seconds - Duration, in seconds, until the event occurs.
+* @returns A short human-readable duration such as `3m`, `2h 15m`, or `1d 4h`.
+*/
+const duration = (seconds) => {
+	if (seconds === null || !Number.isFinite(seconds) || seconds <= 0) return "now";
+	const minutes = Math.ceil(seconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	const remainder = minutes % 60;
+	if (hours < 24) return remainder === 0 ? `${hours}h` : `${hours}h ${remainder}m`;
+	const days = Math.floor(hours / 24);
+	const hourRemainder = hours % 24;
+	return hourRemainder === 0 ? `${days}d` : `${days}d ${hourRemainder}h`;
+};
+/**
+* Formats a nullable usage percentage for display.
+*
+* @param value - The percentage to render, or `null` when the provider did not
+*   report a percentage.
+* @returns A rounded usage string, or `? used` when usage is unknown.
+*/
+const formatPercent = (value) => value === null ? "? used" : `${Math.round(value)}% used`;
+/**
+* Builds the primary line of text for a usage window in the sidebar panel.
+*
+* @param window - The provider usage window to summarize.
+* @returns A label and percentage pair such as `daily: 42% used`.
+*/
+const windowMainText = (window) => `${window.label}: ${formatPercent(window.usedPercent)}`;
+/**
+* Builds the compact prompt-footer text for the active provider's primary window.
+*
+* @param window - The active provider usage window to summarize.
+* @returns A compact percentage label such as `daily: 42% used`.
+*/
+const bottomWindowMainText = (window) => `${window.label}: ${formatPercent(window.usedPercent)}`;
+/**
+* Formats the reset suffix for a usage window.
+*
+* @param window - The usage window whose reset time should be rendered.
+* @returns A leading-space suffix such as ` resets 12m`, or an empty string when
+*   the provider did not report a reset countdown.
+*/
+const windowResetText = (window) => window.resetAfterSeconds === null ? "" : ` resets ${duration(window.resetAfterSeconds)}`;
+/**
+* Converts a provider-reported rolling-window size into a stable display label.
+*
+* Provider APIs can return slightly imprecise window lengths, so expected
+* windows are matched within a 5% tolerance before falling back to the caller's
+* label.
+*
+* @param seconds - The provider-reported limit window length in seconds.
+* @param fallback - Label to use when the window does not match a known size.
+* @returns A normalized label such as `5h`, `daily`, `weekly`, or `monthly`.
+*/
+const limitLabelForWindow = (seconds, fallback) => {
+	const minutes = Math.ceil(seconds / 60);
+	const roughly = (expected) => minutes >= expected * .95 && minutes <= expected * 1.05;
+	const hour = 60;
+	const day = 24 * hour;
+	if (roughly(5 * hour)) return "5h";
+	if (roughly(day)) return "daily";
+	if (roughly(7 * day)) return "weekly";
+	if (roughly(30 * day)) return "monthly";
+	return fallback;
+};
+//#endregion
+//#region src/components.tsx
+/**
+* Chooses the status-dot color for a usage percentage.
+*
+* @param usedPercent - Percentage consumed, or `null` when unknown.
+* @param theme - Active OpenCode TUI theme.
+* @returns A theme color indicating healthy, warning, error, or unknown usage.
+*/
+const dotColor = (usedPercent, theme) => {
+	if (usedPercent === null) return theme.textMuted;
+	if (usedPercent >= 90) return theme.error;
+	if (usedPercent >= 70) return theme.warning;
+	return theme.success;
+};
+/**
+* Renders the sidebar usage-limits panel.
+*
+* The panel lists every enabled provider, shows loading and stale states, and can
+* optionally display provider fetch errors.
+*
+* @param props - Provider states, error visibility, and active TUI theme.
+* @returns Solid/OpenTUI JSX for the sidebar content slot.
+*/
+const UsageLimitsPanel = (props) => /* @__PURE__ */ jsx(Show, {
+	when: props.states.some((state) => state.status !== "disabled"),
+	children: /* @__PURE__ */ jsxs("box", { children: [/* @__PURE__ */ jsx("text", {
+		fg: props.theme.text,
+		children: /* @__PURE__ */ jsx("b", { children: "Usage Limits" })
+	}), /* @__PURE__ */ jsx(For, {
+		each: props.states,
+		children: (state) => /* @__PURE__ */ jsx(Show, {
+			when: state.status !== "disabled",
+			children: /* @__PURE__ */ jsxs("box", { children: [
+				/* @__PURE__ */ jsxs("text", {
+					fg: props.theme.text,
+					children: [state.label, /* @__PURE__ */ jsxs(Show, {
+						when: state.status === "ready" && state.stale,
+						children: [" ", "stale"]
+					})]
+				}),
+				/* @__PURE__ */ jsx(Show, {
+					when: state.status === "loading",
+					children: /* @__PURE__ */ jsx("text", {
+						fg: props.theme.textMuted,
+						children: " loading..."
+					})
+				}),
+				/* @__PURE__ */ jsx(Show, {
+					when: state.status === "ready",
+					children: /* @__PURE__ */ jsx(For, {
+						each: state.status === "ready" ? state.data.windows : [],
+						children: (window) => /* @__PURE__ */ jsxs("box", {
+							flexDirection: "row",
+							gap: 1,
+							children: [/* @__PURE__ */ jsx("text", {
+								flexShrink: 0,
+								fg: dotColor(window.usedPercent, props.theme),
+								children: "•"
+							}), /* @__PURE__ */ jsxs("text", {
+								fg: props.theme.text,
+								children: [windowMainText(window), /* @__PURE__ */ jsx("span", {
+									style: { fg: props.theme.textMuted },
+									children: windowResetText(window)
+								})]
+							})]
+						})
+					})
+				}),
+				/* @__PURE__ */ jsx(Show, {
+					when: state.status === "error" && props.showErrors,
+					children: /* @__PURE__ */ jsx(Show, {
+						fallback: /* @__PURE__ */ jsxs("text", {
+							fg: props.theme.error,
+							children: [" ", state.status === "error" ? state.message : "error"]
+						}),
+						when: state.status === "error" ? state.previous : void 0,
+						children: (previous) => /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(For, {
+							each: previous().windows,
+							children: (window) => /* @__PURE__ */ jsxs("box", {
+								flexDirection: "row",
+								gap: 1,
+								children: [/* @__PURE__ */ jsx("text", {
+									flexShrink: 0,
+									fg: dotColor(window.usedPercent, props.theme),
+									children: "•"
+								}), /* @__PURE__ */ jsxs("text", {
+									fg: props.theme.text,
+									children: [windowMainText(window), /* @__PURE__ */ jsx("span", {
+										style: { fg: props.theme.textMuted },
+										children: windowResetText(window)
+									})]
+								})]
+							})
+						}), /* @__PURE__ */ jsxs("text", {
+							fg: props.theme.error,
+							children: [" ", state.status === "error" ? state.message : "error"]
+						})] })
+					})
+				})
+			] })
+		})
+	})] })
+});
+/**
+* Renders the compact active-provider usage indicator in the prompt footer.
+*
+* @param props - Active usage window and active TUI theme.
+* @returns Solid/OpenTUI JSX for the prompt footer slot.
+*/
+const BottomUsage = (props) => /* @__PURE__ */ jsx(Show, {
+	when: props.window,
+	children: (window) => /* @__PURE__ */ jsxs("text", {
+		fg: props.theme.text,
+		children: [bottomWindowMainText(window()), /* @__PURE__ */ jsx("span", {
+			style: { fg: props.theme.textMuted },
+			children: windowResetText(window())
+		})]
+	})
+});
+//#endregion
+//#region src/utils.ts
+/**
+* Normalizes an arbitrary number into the inclusive percentage range used by UI.
+*
+* @param value - Provider-reported percentage value.
+* @returns A finite number clamped between `0` and `100`.
+*/
+const clampPercent = (value) => Math.min(100, Math.max(0, Number.isFinite(value) ? value : 0));
+/**
+* Checks whether a value is a plain object-like record.
+*
+* This intentionally excludes arrays because provider API payloads are parsed as
+* `unknown` and object fields are accessed only after this guard succeeds.
+*
+* @param value - Value to narrow.
+* @returns `true` when the value can be safely indexed as a record.
+*/
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const stripTrailingCommas = (input) => {
+	let output = "";
+	let inString = false;
+	let quote = "";
+	let escaped = false;
+	for (let index = 0; index < input.length; index += 1) {
+		const char = input[index];
+		if (inString) {
+			output += char;
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === quote) inString = false;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			inString = true;
+			quote = char;
+			output += char;
+			continue;
+		}
+		if (char === ",") {
+			let lookahead = index + 1;
+			while (/\s/u.test(input[lookahead] ?? "")) lookahead += 1;
+			if (input[lookahead] === "}" || input[lookahead] === "]") continue;
+		}
+		output += char;
+	}
+	return output;
+};
+/**
+* Removes JSONC comments and trailing commas while preserving string contents.
+*
+* The plugin accepts small user-authored config files without adding a JSONC
+* dependency. Both line comments and block comments are stripped, but comment
+* markers inside quoted strings are left untouched.
+*
+* @param input - Raw JSONC text.
+* @returns JSON-compatible text suitable for `JSON.parse`.
+*/
+const stripJsonComments = (input) => {
+	let output = "";
+	let inString = false;
+	let quote = "";
+	let escaped = false;
+	for (let index = 0; index < input.length; index += 1) {
+		const char = input[index];
+		const next = input[index + 1];
+		if (inString) {
+			output += char;
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === quote) inString = false;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			inString = true;
+			quote = char;
+			output += char;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			while (index < input.length && input[index] !== "\n") index += 1;
+			output += "\n";
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			index += 2;
+			while (index < input.length && !(input[index] === "*" && input[index + 1] === "/")) index += 1;
+			index += 1;
+			continue;
+		}
+		output += char;
+	}
+	return stripTrailingCommas(output);
+};
+/**
+* Expands a leading home-directory marker in a filesystem path.
+*
+* @param value - Path that may start with `~`, `~/`, or `~\`.
+* @returns The path with a leading home marker replaced by the user's home path.
+*/
+const expandHome = (value) => value === "~" || value.startsWith("~/") || value.startsWith("~\\") ? path.join(homedir(), value.slice(2)) : value;
+/**
+* Reads and parses a JSON or JSONC file.
+*
+* A leading `~` in the path is expanded before reading. The generic type is a
+* caller-provided assertion; callers should still validate external data before
+* relying on specific fields.
+*
+* @param filePath - Absolute path, relative path, or home-relative path to read.
+* @returns The parsed JSON value typed as `T`.
+*/
+const readJsonFile = async (filePath) => {
+	const raw = await readFile(expandHome(filePath), "utf-8");
+	return JSON.parse(stripJsonComments(raw));
+};
+/**
+* Resolves a config value that may reference an environment variable.
+*
+* Values in the form `{env:NAME}` are replaced with `process.env.NAME`. Any
+* other non-empty string is returned unchanged.
+*
+* @param value - Raw config value or environment reference.
+* @returns The resolved value, unchanged literal, or `undefined` when absent.
+*/
+const resolveEnvReference = (value) => {
+	if (!value) return;
+	const envMatch = /^\{env:(?<name>[^}]+)\}$/iu.exec(value.trim());
+	if (envMatch?.groups?.name) return process.env[envMatch.groups.name];
+	return value;
+};
+/**
+* Fetches a JSON endpoint with a timeout and normalized provider-facing errors.
+*
+* HTTP status codes that commonly matter for auth and quota diagnostics are
+* mapped to stable messages, while successful non-JSON responses are rejected as
+* invalid provider payloads.
+*
+* @param url - Endpoint URL to request.
+* @param init - Fetch options such as method and headers.
+* @param timeoutMs - Timeout in milliseconds when `init.signal` is not supplied.
+* @returns The parsed JSON payload as `unknown` for caller-side validation.
+* @throws {Error} When the response is unsuccessful or cannot be parsed as JSON.
+*/
+const fetchJson = async (url, init, timeoutMs) => {
+	const response = await fetch(url, {
+		...init,
+		signal: init.signal ?? AbortSignal.timeout(timeoutMs)
+	});
+	const body = await response.text();
+	if (!response.ok) {
+		if (response.status === 401) throw new Error("unauthorized");
+		if (response.status === 403) throw new Error("forbidden");
+		if (response.status === 429) throw new Error("rate limited");
+		throw new Error(`HTTP ${response.status}`);
+	}
+	try {
+		return JSON.parse(body);
+	} catch {
+		throw new Error("invalid JSON");
+	}
+};
+//#endregion
+//#region src/config.ts
+/** Default user configuration path for this plugin. */
+const CONFIG_PATH = path.join(homedir(), ".config", "opencode", "usage-limits.jsonc");
+/** Default OpenCode auth path shared by installed providers. */
+const OPENCODE_AUTH_PATH = path.join(homedir(), ".local", "share", "opencode", "auth.json");
+const numericConfigValue = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
+/**
+* Loads the usage-limits plugin configuration from OpenCode's config directory.
+*
+* Missing files, unreadable files, and invalid JSONC all resolve to conservative
+* defaults so the plugin can start without interrupting the TUI. Partial config
+* files are merged with the same defaults.
+*
+* @returns The fully-populated plugin configuration.
+*/
+const loadConfig = async () => {
+	const fallback = {
+		enabled: true,
+		providers: {},
+		refreshIntervalSeconds: 60,
+		requestTimeoutMs: 1e4,
+		showErrors: true
+	};
+	try {
+		const config = await readJsonFile(CONFIG_PATH);
+		return {
+			enabled: config.enabled ?? fallback.enabled,
+			providers: config.providers ?? fallback.providers,
+			refreshIntervalSeconds: numericConfigValue(config.refreshIntervalSeconds, fallback.refreshIntervalSeconds),
+			requestTimeoutMs: numericConfigValue(config.requestTimeoutMs, fallback.requestTimeoutMs),
+			showErrors: config.showErrors ?? fallback.showErrors
+		};
+	} catch {
+		return fallback;
+	}
+};
+/**
+* Loads OpenCode's shared auth file for provider credentials.
+*
+* This file may not exist for every installation or provider. Auth loading is
+* therefore best-effort and returns an empty object when credentials are absent
+* or unreadable.
+*
+* @returns The parsed OpenCode auth payload, or an empty auth object.
+*/
+const loadOpenCodeAuth = async () => {
+	try {
+		return await readJsonFile(OPENCODE_AUTH_PATH);
+	} catch {
+		return {};
+	}
+};
+//#endregion
+//#region src/providers/codex.ts
+/** Default ChatGPT backend base URL used for Codex usage requests. */
+const DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+/**
+* Reads Codex credentials from the Codex CLI auth file.
+*
+* @param authPath - Optional path override. Defaults to `~/.codex/auth.json`.
+* @returns Access token and ChatGPT account ID required by the Codex usage API.
+* @throws {Error} When the auth file is missing or does not contain credentials.
+* @throws {TypeError} When the auth file contains credentials with invalid types.
+*/
+const readCodexAuthFile = async (authPath) => {
+	const auth = await readJsonFile(authPath ?? "~/.codex/auth.json");
+	if (!isRecord(auth) || !isRecord(auth.tokens)) throw new Error("missing Codex auth");
+	const access = auth.tokens.access_token;
+	const accountId = auth.tokens.account_id;
+	if (typeof access !== "string" || typeof accountId !== "string") throw new TypeError("invalid Codex credential types");
+	return {
+		access,
+		accountId
+	};
+};
+/**
+* Converts a raw Codex rate-limit window into the plugin's normalized shape.
+*
+* @param value - Unknown `primary_window` or `secondary_window` payload.
+* @param fallback - Label used when the provider does not report a known window
+*   length.
+* @returns A normalized usage window, or `null` for invalid payloads.
+*/
+const codexWindow = (value, fallback) => {
+	if (!isRecord(value)) return null;
+	const used = typeof value.used_percent === "number" ? clampPercent(value.used_percent) : null;
+	const resetAfter = typeof value.reset_after_seconds === "number" ? value.reset_after_seconds : null;
+	const windowSeconds = typeof value.limit_window_seconds === "number" ? value.limit_window_seconds : 0;
+	const resetAt = typeof value.reset_at === "number" && value.reset_at > 0 ? /* @__PURE__ */ new Date(value.reset_at * 1e3) : null;
+	return {
+		label: windowSeconds > 0 ? limitLabelForWindow(windowSeconds, fallback) : fallback,
+		remainingPercent: used === null ? null : 100 - used,
+		resetAfterSeconds: resetAfter,
+		resetsAt: resetAt,
+		usedPercent: used
+	};
+};
+/**
+* Fetches and normalizes Codex usage limits.
+*
+* Credentials are read from OpenCode auth when available, otherwise from the
+* Codex CLI auth file. The returned windows represent the primary and secondary
+* Codex rate-limit windows reported by ChatGPT's backend API.
+*
+* @param config - Optional Codex provider configuration.
+* @param openCodeAuth - Shared OpenCode auth payload.
+* @param timeoutMs - Request timeout in milliseconds.
+* @returns Normalized Codex usage data.
+* @throws {Error} When credentials are missing or the provider response is invalid.
+*/
+const fetchCodexUsage = async (config, openCodeAuth, timeoutMs) => {
+	const { openai } = openCodeAuth;
+	const credentials = typeof openai?.access === "string" && openai.access.trim() !== "" && typeof openai.accountId === "string" && openai.accountId.trim() !== "" ? {
+		access: openai.access,
+		accountId: openai.accountId
+	} : await readCodexAuthFile(config?.authPath);
+	const payload = await fetchJson(`${(config?.baseUrl ?? DEFAULT_CODEX_BASE_URL).replace(/\/$/u, "")}/wham/usage`, {
+		headers: {
+			Authorization: `Bearer ${credentials.access}`,
+			"ChatGPT-Account-Id": credentials.accountId,
+			"User-Agent": "opencode-usage-limits"
+		},
+		method: "GET"
+	}, timeoutMs);
+	if (!isRecord(payload)) throw new Error("invalid Codex usage");
+	const rateLimit = isRecord(payload.rate_limit) ? payload.rate_limit : void 0;
+	const windows = [codexWindow(rateLimit?.primary_window, "usage"), codexWindow(rateLimit?.secondary_window, "secondary")].filter((item) => item !== null);
+	const resetCredits = isRecord(payload.rate_limit_reset_credits) && typeof payload.rate_limit_reset_credits.available_count === "number" ? payload.rate_limit_reset_credits.available_count : null;
+	return {
+		capturedAt: /* @__PURE__ */ new Date(),
+		id: "codex",
+		label: config?.label ?? "Codex",
+		metadata: { resetCredits },
+		tierName: typeof payload.plan_type === "string" ? payload.plan_type : void 0,
+		windows
+	};
+};
+//#endregion
+//#region src/providers/zai-coding-plan.ts
+/** ZAI Coding Plan quota endpoint used to fetch usage limits. */
+const ZAI_QUOTA_URL = "https://api.z.ai/api/monitor/usage/quota/limit";
+/**
+* Infers the ZAI plan tier from the provider's prompt/time quota total.
+*
+* @param total - Total quota reported by the ZAI time-limit payload.
+* @returns The inferred tier name, or `undefined` when it cannot be inferred.
+*/
+const inferZaiTier = (total) => {
+	if (total === null) return;
+	if (total >= 1400) return "Max";
+	if (total >= 300) return "Pro";
+	if (total > 0) return "Lite";
+};
+/**
+* Extracts a ZAI API key from any supported auth object shape.
+*
+* The plugin accepts both direct `{ key }`/`{ apiKey }` objects and the nested
+* shapes used by OpenCode auth.
+*
+* @param value - Unknown auth payload to inspect.
+* @returns The first recognized API key.
+*/
+const keyFromZaiAuth = (value) => {
+	if (!isRecord(value)) return;
+	if (typeof value.key === "string") return value.key;
+	if (typeof value.apiKey === "string") return value.apiKey;
+	const zaiCodingPlan = value["zai-coding-plan"];
+	if (isRecord(zaiCodingPlan) && typeof zaiCodingPlan.key === "string") return zaiCodingPlan.key;
+	if (isRecord(value.zai) && typeof value.zai.key === "string") return value.zai.key;
+};
+/**
+* Attempts to load a ZAI API key from a configured auth path.
+*
+* Missing or invalid files are ignored so other credential sources can still be
+* tried by the provider adapter.
+*
+* @param authPath - Optional auth file path.
+* @returns A ZAI API key when the file exists and contains one.
+*/
+const readZaiAuthPathKey = async (authPath) => {
+	if (!authPath) return;
+	try {
+		return keyFromZaiAuth(await readJsonFile(authPath));
+	} catch {
+		return;
+	}
+};
+/**
+* Converts one raw ZAI limit entry into a normalized usage window.
+*
+* Token limits become the primary `tokens` quota window. Time limits become an
+* `MCP` count-based window and also expose the total prompt quota used to infer
+* the user's ZAI tier.
+*
+* @param limit - Raw limit object from the ZAI quota API.
+* @returns The normalized window plus any prompt total discovered on the entry.
+*/
+const zaiWindowFromLimit = (limit) => {
+	const usedPercent = typeof limit.percentage === "number" ? clampPercent(limit.percentage) : null;
+	const resetsAt = typeof limit.nextResetTime === "number" ? new Date(limit.nextResetTime) : null;
+	const current = typeof limit.currentValue === "number" ? limit.currentValue : void 0;
+	const total = typeof limit.usage === "number" ? limit.usage : void 0;
+	if (limit.type === "TOKENS_LIMIT") return {
+		promptTotal: null,
+		window: {
+			label: "tokens",
+			remainingPercent: usedPercent === null ? null : 100 - usedPercent,
+			resetAfterSeconds: resetsAt ? Math.max(0, Math.ceil((resetsAt.getTime() - Date.now()) / 1e3)) : null,
+			resetsAt,
+			usedPercent
+		}
+	};
+	if (limit.type === "TIME_LIMIT") return {
+		promptTotal: total ?? null,
+		window: {
+			current,
+			label: "MCP",
+			remainingPercent: usedPercent === null ? null : 100 - usedPercent,
+			resetAfterSeconds: null,
+			resetsAt: null,
+			total,
+			usedPercent
+		}
+	};
+	return {
+		promptTotal: null,
+		window: null
+	};
+};
+/**
+* Fetches and normalizes ZAI Coding Plan usage limits.
+*
+* Credential lookup checks, in order, the configured auth path, OpenCode auth,
+* and a configured literal or environment-backed API key.
+*
+* @param config - Optional ZAI provider configuration.
+* @param openCodeAuth - Shared OpenCode auth payload.
+* @param timeoutMs - Request timeout in milliseconds.
+* @returns Normalized ZAI usage data.
+* @throws {Error} When no API key is available or the provider response is invalid.
+*/
+const fetchZaiCodingPlanUsage = async (config, openCodeAuth, timeoutMs) => {
+	const configuredKey = resolveEnvReference(config?.apiKey);
+	const apiKey = await readZaiAuthPathKey(config?.authPath) ?? keyFromZaiAuth(openCodeAuth) ?? configuredKey;
+	if (!apiKey) throw new Error("missing ZAI key");
+	const payload = await fetchJson(ZAI_QUOTA_URL, {
+		headers: {
+			"Accept-Language": "en-US,en",
+			Authorization: (config?.authorizationScheme ?? "raw") === "bearer" ? `Bearer ${apiKey}` : apiKey,
+			"Content-Type": "application/json"
+		},
+		method: "GET"
+	}, timeoutMs);
+	if (!isRecord(payload) || !isRecord(payload.data) || !Array.isArray(payload.data.limits)) throw new Error("invalid ZAI usage");
+	const windows = [];
+	let promptTotal = null;
+	for (const limit of payload.data.limits) {
+		if (!isRecord(limit) || typeof limit.type !== "string") continue;
+		const usage = zaiWindowFromLimit(limit);
+		if (usage.window) windows.push(usage.window);
+		if (usage.promptTotal !== null) ({promptTotal} = usage);
+	}
+	return {
+		capturedAt: /* @__PURE__ */ new Date(),
+		id: "zai",
+		label: config?.label ?? "ZAI",
+		tierName: inferZaiTier(promptTotal),
+		windows
+	};
+};
+//#endregion
+//#region src/providers.ts
+/**
+* Fetches usage data for a configured provider.
+*
+* This dispatches to the provider-specific adapter while keeping plugin refresh
+* code independent of each provider's authentication and response format.
+*
+* @param id - Provider adapter to fetch.
+* @param config - Optional provider-specific configuration.
+* @param openCodeAuth - Shared OpenCode auth payload.
+* @param timeoutMs - Request timeout in milliseconds.
+* @returns Normalized provider usage data.
+*/
+const fetchProvider = (id, config, openCodeAuth, timeoutMs) => {
+	if (id === "codex") return fetchCodexUsage(config, openCodeAuth, timeoutMs);
+	if (id === "zai") return fetchZaiCodingPlanUsage(config, openCodeAuth, timeoutMs);
+	throw new Error(`unknown provider: ${id}`);
+};
+/**
+* Returns enabled provider configurations in the order they should appear in UI.
+*
+* Providers are opt-in: a provider is included only when its config sets
+* `enabled: true`.
+*
+* @param config - Fully resolved plugin configuration.
+* @returns Tuples of provider IDs and their config objects.
+*/
+const getProviderConfigs = (config) => ["codex", "zai"].flatMap((id) => {
+	const provider = config.providers[id];
+	if (provider?.enabled !== true) return [];
+	return [[id, provider]];
+});
+//#endregion
+//#region src/session.ts
+/**
+* Extracts an OpenCode provider identifier from a session message-like value.
+*
+* OpenCode message shapes have changed over time, so the provider may be present
+* either directly on the message or nested under `message.model`.
+*
+* @param message - Unknown message payload from OpenCode session state.
+* @returns The provider identifier when present.
+*/
+const getProviderFromMessage = (message) => {
+	if (!isRecord(message)) return;
+	if (typeof message.providerID === "string") return message.providerID;
+	if (isRecord(message.model) && typeof message.model.providerID === "string") return message.model.providerID;
+};
+/**
+* Finds the provider currently represented by a session's latest messages.
+*
+* Messages are scanned from newest to oldest so the returned provider reflects
+* the most recent model/provider selection in the active conversation.
+*
+* @param messages - OpenCode session messages.
+* @returns The latest provider identifier, or `undefined` when unavailable.
+*/
+const currentProviderID = (messages) => {
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const providerID = getProviderFromMessage(messages[index]);
+		if (providerID) return providerID;
+	}
+};
+/**
+* Selects the usage window that should be shown in the prompt footer.
+*
+* OpenCode provider IDs are mapped to this plugin's provider IDs, then the most
+* useful window is selected from the current provider state. If the latest fetch
+* failed, the last successful data attached to the error state is used.
+*
+* @param states - Current provider states maintained by the plugin.
+* @param providerID - OpenCode provider identifier for the active session.
+* @returns The best usage window for the active provider, or `null` if none can
+*   be shown.
+*/
+const usageForProvider = (states, providerID) => {
+	let usageID = null;
+	if (providerID === "openai") usageID = "codex";
+	if (providerID === "zai-coding-plan") usageID = "zai";
+	if (!usageID) return null;
+	const state = states.find((item) => item.id === usageID);
+	let data;
+	if (state?.status === "ready") ({data} = state);
+	if (state?.status === "error") data = state.previous;
+	if (!data) return null;
+	if (usageID === "zai") return data.windows.find((window) => window.label === "tokens") ?? data.windows[0] ?? null;
+	return data.windows.find((window) => window.label === "5h") ?? data.windows[0] ?? null;
+};
+//#endregion
+//#region src/plugin.tsx
+/**
+* OpenCode TUI plugin entry point.
+*
+* The plugin periodically loads configuration, fetches enabled provider usage,
+* stores the latest successful result for stale/error fallback, and registers UI
+* slots for both the sidebar panel and prompt-footer indicator.
+*
+* @param api - OpenCode TUI plugin API supplied at plugin initialization.
+*/
+const tui = async (api) => {
+	const [states, setStates] = createSignal([]);
+	const [showErrors, setShowErrors] = createSignal(true);
+	let lastSuccess = /* @__PURE__ */ new Map();
+	let refreshIntervalSeconds = 60;
+	/**
+	* Refreshes configuration and usage data for every enabled provider.
+	*
+	* Existing ready or error states are kept visible while new requests are in
+	* flight. Failed refreshes retain the last successful usage payload so the UI
+	* can still show stale usage alongside the error message.
+	*/
+	const refresh = async () => {
+		const config = await loadConfig();
+		setShowErrors(config.showErrors);
+		({refreshIntervalSeconds} = config);
+		if (!config.enabled) {
+			setStates([]);
+			return;
+		}
+		const effectiveRefreshIntervalSeconds = Math.max(15, refreshIntervalSeconds);
+		const providers = getProviderConfigs(config);
+		const previous = new Map(states().map((state) => [state.id, state]));
+		setStates(providers.map(([id, provider]) => {
+			const label = provider.label ?? (id === "codex" ? "Codex" : "ZAI");
+			const current = previous.get(id);
+			if (current?.status === "ready" || current?.status === "error") return current;
+			return {
+				id,
+				label,
+				status: "loading"
+			};
+		}));
+		const openCodeAuth = await loadOpenCodeAuth();
+		const nextStates = await Promise.all(providers.map(async ([id, provider]) => {
+			const label = provider.label ?? (id === "codex" ? "Codex" : "ZAI");
+			try {
+				const data = await fetchProvider(id, provider, openCodeAuth, config.requestTimeoutMs);
+				lastSuccess.set(id, data);
+				return {
+					data,
+					id,
+					label,
+					stale: false,
+					status: "ready"
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : "usage unavailable";
+				const previousData = lastSuccess.get(id);
+				if (previousData) return {
+					id,
+					label,
+					message,
+					previous: previousData,
+					status: "error"
+				};
+				return {
+					id,
+					label,
+					message,
+					status: "error"
+				};
+			}
+		}));
+		const staleAfterMs = effectiveRefreshIntervalSeconds * 2 * 1e3;
+		setStates(nextStates.map((state) => {
+			if (state.status !== "ready") return state;
+			return {
+				...state,
+				stale: Date.now() - state.data.capturedAt.getTime() > staleAfterMs
+			};
+		}));
+	};
+	await refresh();
+	let disposed = false;
+	let timer;
+	const scheduleRefresh = () => {
+		timer = setTimeout(async () => {
+			await refresh();
+			if (!disposed) scheduleRefresh();
+		}, Math.max(15, refreshIntervalSeconds) * 1e3);
+	};
+	scheduleRefresh();
+	api.lifecycle.onDispose(() => {
+		disposed = true;
+		if (timer) clearTimeout(timer);
+		lastSuccess = /* @__PURE__ */ new Map();
+	});
+	api.slots.register({
+		order: 101,
+		slots: {
+			session_prompt_right(ctx, props) {
+				const providerID = currentProviderID(api.state.session.messages(props.session_id));
+				return /* @__PURE__ */ jsx(BottomUsage, {
+					theme: ctx.theme.current,
+					window: usageForProvider(states(), providerID)
+				});
+			},
+			sidebar_content(ctx) {
+				return /* @__PURE__ */ jsx(UsageLimitsPanel, {
+					showErrors: showErrors(),
+					states: states(),
+					theme: ctx.theme.current
+				});
+			}
+		}
+	});
+};
+//#endregion
+//#region src/index.ts
+/** OpenCode plugin module exported for the `oc-usage-limits-plugin/tui` entry. */
+var src_default = {
+	id: "mynameistito.usage-limits",
+	tui
+};
+//#endregion
+export { src_default as default };

package/examples/usage-limits.jsonc

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://raw.githubusercontent.com/mynameistito/oc-usage-limits-plugin/main/usage-limits.schema.json",
+  "enabled": true,
+  "refreshIntervalSeconds": 60,
+  "requestTimeoutMs": 10000,
+  "showErrors": true,
+  "providers": {
+    "codex": {
+      "enabled": true,
+      "label": "Codex",
+      "authPath": "~/.codex/auth.json",
+    },
+    "zai": {
+      "enabled": true,
+      "label": "ZAI",
+      "authPath": "~/.local/share/opencode/auth.json",
+      "apiKey": "{env:OC_ZAI_API_KEY}",
+      "authorizationScheme": "raw",
+    },
+  },
+}

package/package.json

@@ -1,24 +1,74 @@
 {
   "name": "oc-usage-limits-plugin",
-  "version": "0.0.1",
-  "description": "OpenCode TUI plugin that shows usage limits in the sidebar and prompt footer.",
-  "keywords": ["opencode", "opencode-plugin", "tui", "usage-limits"],
-  "homepage": "https://github.com/mynameistito/oc-usage-limits#readme",
+  "version": "1.0.1",
+  "description": "OpenCode TUI plugin that shows Codex and ZAI usage limits in the sidebar and prompt footer.",
+  "keywords": [
+    "codex",
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "usage-limits",
+    "zai"
+  ],
+  "homepage": "https://github.com/mynameistito/oc-usage-limits-plugin#readme",
   "bugs": {
-    "url": "https://github.com/mynameistito/oc-usage-limits/issues"
+    "url": "https://github.com/mynameistito/oc-usage-limits-plugin/issues"
   },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mynameistito/oc-usage-limits.git"
+    "url": "git+https://github.com/mynameistito/oc-usage-limits-plugin.git"
   },
+  "files": [
+    "dist",
+    "examples",
+    "usage-limits.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
   "exports": {
-    ".": "./index.ts",
-    "./tui": "./index.ts"
+    "./tui": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./schema": "./usage-limits.schema.json"
   },
-  "files": ["index.ts"],
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "changeset": "changeset",
+    "changeset-add": "bun ./scripts/changeset-add.ts",
+    "build": "tsdown",
+    "check": "ultracite check",
+    "knip": "bunx knip@latest",
+    "prepack": "bun run build",
+    "release": "changeset publish",
+    "test": "bun test",
+    "typecheck": "tsgo --noEmit",
+    "version": "changeset version",
+    "fix": "ultracite fix",
+    "prepare": "lefthook install"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@opencode-ai/plugin": "1.17.9",
+    "@opentui/core": "0.4.1",
+    "@opentui/solid": "0.4.1",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.0.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260622.1",
+    "lefthook": "^2.1.9",
+    "oxfmt": "^0.56.0",
+    "oxlint": "^1.71.0",
+    "solid-js": "1.9.12",
+    "tsdown": "^0.22.3",
+    "ultracite": "7.8.3"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.17.9",
+    "@opentui/solid": ">=0.4.1",
+    "solid-js": ">=1.9.12"
   }
 }

package/usage-limits.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/mynameistito/oc-usage-limits-plugin/main/usage-limits.schema.json",
+  "title": "OpenCode Usage Limits Plugin Config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "enabled": { "type": "boolean" },
+    "refreshIntervalSeconds": { "type": "number", "minimum": 15 },
+    "requestTimeoutMs": { "type": "number", "minimum": 1000 },
+    "showErrors": { "type": "boolean" },
+    "providers": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "codex": { "$ref": "#/$defs/provider" },
+        "zai": { "$ref": "#/$defs/provider" }
+      }
+    }
+  },
+  "$defs": {
+    "provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "label": { "type": "string" },
+        "authPath": { "type": "string" },
+        "apiKey": { "type": "string" },
+        "authorizationScheme": { "enum": ["raw", "bearer"] },
+        "baseUrl": { "type": "string" }
+      }
+    }
+  }
+}

package/index.ts

@@ -1,5 +0,0 @@
-const plugin = {
-  id: "mynameistito.usage-limits",
-};
-
-export default plugin;