pi-opencode-gs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Soto
+
+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,148 @@
-# Temporary Holding Version
+# pi-opencode-gs
 
-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.
+OpenCode Go subscription usage in [Gentle Shell](https://github.com/Gentleman-Programming/gentle-shell): the
+`/gentle:usage` panel behind `alt+u`, the usage segment in the status bar, and the DeepSeek peak/off-peak
+pricing window OpenCode Go bills at double rate.
+
+Gentle Shell ships built-in usage readers for Codex, Claude and NaN Cloud. This package registers OpenCode Go
+through the `gentle-pi:usage-source/v1` event, so the shell treats it exactly like a built-in provider and owns
+the refresh schedule.
+
+## Requirements
+
+- Gentle Shell with a `usage-source` capable version
+- Pi `>= 0.85`, Node `>= 22.19`
+- An `opencode-go` provider configured in Pi, with its API key stored as usual (`auth.json` or `OPENCODE_API_KEY`)
+
+## Install
+
+```sh
+# Standalone Gentle Shell (the usual case)
+gentle-shell install npm:pi-opencode-gs
+
+# Gentle Shell linked to an existing pi home
+gentle-shell --link install npm:pi-opencode-gs
+
+# Plain Pi
+pi install npm:pi-opencode-gs
+
+# From a checkout
+gentle-shell install ./pi-opencode-gs
+```
+
+Plain Pi has no listener for the event, so the extension is a no-op there. Reload (`/reload`) or restart, then
+send one message with an `opencode-go/*` model and open `alt+u`.
+
+## What you see
+
+The panel, one row per window, with the schedule on the provider line:
+
+```text
+✿ Subscriptions
+  opencode-go · peak 20m · updated just now
+    go 5h     ▰▱▱▱▱▱▱▱ 12% · resets in 1h 42m
+    go week   ▰▰▰▱▱▱▱▱ 37% · resets in 1d 20h
+    go month  ▰▰▰▰▰▰▰▰ 96% · resets in 4d 0h
+```
+
+Labels are lowercase, the way the panel writes everything else. The header text is plain — `peak 20m` while
+peak, `off-peak 1hr 30m` otherwise — so red stays reserved for a window that is nearly spent. The percentages are
+what the endpoint answered at the last refresh, never an average or an estimate, and `r` refreshes them.
+
+While a peak window runs, one line sits under the editor:
+
+```text
+peak · 2× deepseek · until 04:00
+```
+
+`peak` is amber, the rest is dim, and `until` is the clock time the window ends in the machine's own timezone —
+`until Mon 01:00` when that instant falls on another local date. The line appears and disappears on its own at the
+boundary: the package arms one timer to the exact transition and never polls. Nothing is drawn in off-peak, and
+nothing is drawn until a refresh proves the `opencode-go` provider is logged in — the session model is irrelevant.
+
+## The peak schedule
+
+OpenCode Go publishes two peak windows for DeepSeek V4.1 Flash and V4 Pro, billed at twice the off-peak rate on
+input, output and cached reads:
+
+| Window | UTC | Days |
+| --- | --- | --- |
+| Peak 1 | 01:00-04:00 | Monday through Friday |
+| Peak 2 | 06:00-10:00 | Monday through Friday |
+
+Everything else is off-peak, including both weekend days in full. The published contract names weekends only;
+no holiday calendar is assumed, so a national holiday is billed as a normal weekday.
+
+## Configuration
+
+| Variable | Effect |
+| --- | --- |
+| `PI_OPENCODE_GO_USAGE_DEBUG` | Set to any value to log why a refresh produced no snapshot, by fixed code only |
+
+## How it works
+
+One authenticated, read-only `GET` to a fixed route:
+
+```
+https://opencode.ai/zen/go/v1/usage
+```
+
+It answers with three windows, each a used percentage and a reset instant:
+
+```json
+{ "usage": {
+  "rolling": { "status": "ok", "percent": 12, "resetsAt": "2026-11-07T19:45:51.000Z" },
+  "weekly":  { "status": "ok", "percent": 37, "resetsAt": "2026-11-09T00:00:00.000Z" },
+  "monthly": { "status": "ok", "percent": 96, "resetsAt": "2026-11-24T21:47:15.000Z" }
+} }
+```
+
+The read is all or nothing: a payload missing a window, or carrying a status other than `ok` or
+`rate-limited`, yields no snapshot at all, so a depleted subscription never looks less used than it is. Gentle
+Shell keeps the last valid snapshot through a failed refresh and shows its generic "fetch failed" note beside it.
+
+The endpoint does not report how long its windows are, so `5h`, `week` and `month` are display durations (the
+month is nominally 30 days). They only drive the label, the meter and the ordering; the percentage and the reset
+time always come from the server.
+
+## Security
+
+This package handles a credential, so its behaviour is deliberately narrow:
+
+- **One destination, hardcoded.** The only URL literal in the source is the usage route. No configuration,
+  argument or environment variable can point the bearer anywhere else.
+- **No redirects.** `redirect: "error"` plus a post-response check, so a `3xx` cannot replay the token.
+- **Read-only.** Only `GET`. No disk writes, no settings or auth file changes, no shell, no `eval`.
+- **The key never leaves the header.** It is not part of the returned snapshot, so it cannot reach the panel,
+  the sidebar, a log or a session file. Diagnostics report fixed codes only.
+- **No runtime dependencies, no install scripts.** Installing the package executes nothing.
+- **Defensive parsing.** The payload is foreign JSON: every field is checked, validated and rebuilt, never
+  merged into an existing object. Labels are rejected if they carry control characters.
+
+## Known limits
+
+- **The subscription tier is not shown, because it cannot be read.** The usage route publishes percentages only,
+  and `go`, `go plus` and `go teams` live behind the console's session cookie. No tier is displayed rather than a
+  guessed one.
+- **The peak line is not in the status bar.** That line belongs to the shell's own chrome, which exposes no slot
+  for a third party; the line therefore lives in the widget row under the editor, and Integrations is left alone.
+- **The schedule rides the provider line, not a note under the rows.** The panel's per-provider note slot is
+  reserved for NaN's quota disclaimer and the fetch-failed note, so the schedule goes into `plan`, between the
+  provider name and `updated …`.
+- **The panel schedule is as fresh as the last refresh**, exactly like the quota percentages. The widget line is
+  not: it appears and disappears from its own timer at the boundary.
+- **The endpoint is outside OpenCode's published OpenAPI**, so its shape may change; an unknown shape is
+  rejected rather than displayed.
+- **It reflects the subscription, not this session.** Usage you spend in the OpenCode CLI counts too.
+
+## Development
+
+```sh
+npm run verify   # tsc --noEmit, then node --test
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+This is a community package: it is not an official Gentle Shell or OpenCode release.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "pi-opencode-gs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OpenCode Go subscription usage for Gentle Shell, with DeepSeek peak/off-peak pricing awareness",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jonathan Soto",
+  "keywords": [
+    "pi-package",
+    "gentle-shell",
+    "opencode",
+    "opencode-go",
+    "usage",
+    "quota",
+    "deepseek",
+    "peak"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "check": "tsc --noEmit",
+    "verify": "npm run check && npm test",
+    "prepublishOnly": "npm run verify"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.5.2",
+    "@types/node": "^22.19.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/extension.ts

@@ -0,0 +1,139 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { PEAK_WIDGET_KEY, panelSchedule, peakWidgetLine } from "./labels.ts";
+import { peakStateAt } from "./peak.ts";
+import { PROVIDER, fetchOpenCodeGoUsage, type FailureReason, type ProviderUsage } from "./usage.ts";
+
+/**
+ * Registers OpenCode Go with Gentle Shell and keeps the DeepSeek peak schedule
+ * in view.
+ *
+ * Two surfaces, two different contracts:
+ *
+ * - The usage source feeds the status bar's usage segment and the
+ *   `/gentle:usage` panel. The panel prints `plan` between the provider name and
+ *   its `updated …` note, so the peak schedule always rides there, peak or not.
+ * - The widget line above the editor is this extension's own row. It appears only
+ *   while the opencode-go provider is usable AND the schedule is peak, whatever
+ *   the session model is; every other combination clears it.
+ *
+ * Nothing here polls: Gentle Shell owns the refresh schedule for the source, and
+ * the only timer is one that re-arms itself at the next schedule boundary so the
+ * widget appears and disappears with the window.
+ */
+
+const TRANSITION_MARGIN_MS = 1_000;
+const PENDING_NOTE = "opencode-go · press r to fetch";
+
+interface PeakContext {
+	ui?: { setWidget?(key: string, content: string[] | undefined): void };
+}
+
+export default function (pi: ExtensionAPI): void {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let lastContext: PeakContext | undefined;
+	// Unknown until a fetch proves the provider is logged in, so nothing is drawn
+	// on a session whose key is missing.
+	let providerReady = false;
+
+	/**
+	 * The source's plan field: the schedule, always, whatever the session model is
+	 * and whether the window is peak or off-peak. The window labels are left exactly
+	 * as read, so the panel's rows keep their plain `go 5h`, `go week`, `go month`
+	 * names. The instant the shell passes is the fetch's own, so a refresh from the
+	 * panel and the widget cannot disagree about which window is running.
+	 */
+	const withPlan = (usage: ProviderUsage, now: number): ProviderUsage => ({
+		...usage,
+		plan: panelSchedule(peakStateAt(now), now),
+	});
+
+	const clearTimer = (): void => {
+		if (timer === undefined) return;
+		clearTimeout(timer);
+		timer = undefined;
+	};
+
+	/**
+	 * Writes the single peak widget line and clears it for every other combination,
+	 * then re-arms the boundary timer. The session model is irrelevant: provider
+	 * readiness and the peak window are the only gates.
+	 */
+	const sync = (ctx: PeakContext | undefined, now = Date.now()): void => {
+		lastContext = ctx ?? lastContext;
+		const setWidget = ctx?.ui?.setWidget;
+		clearTimer();
+		if (!providerReady) {
+			setWidget?.(PEAK_WIDGET_KEY, undefined);
+			return;
+		}
+		const state = peakStateAt(now);
+		if (state.kind === "peak") {
+			setWidget?.(PEAK_WIDGET_KEY, [peakWidgetLine(state, now)]);
+		} else {
+			setWidget?.(PEAK_WIDGET_KEY, undefined);
+		}
+		// One timer to the exact boundary: the line appears and disappears when the
+		// schedule does, not on the next turn, and nothing here polls.
+		const delay = Math.max(TRANSITION_MARGIN_MS, state.until - now + TRANSITION_MARGIN_MS);
+		timer = setTimeout(() => sync(lastContext), delay);
+		// Never hold the process open for a schedule that changes in hours.
+		(timer as { unref?: () => void }).unref?.();
+	};
+
+	/**
+	 * The readiness gate: only `missing-key` proves the provider is unusable.
+	 * Timeouts, network errors and malformed responses say nothing about whether
+	 * the key is present, so they leave readiness exactly as it was.
+	 */
+	const markReady = (ready: boolean): void => {
+		if (ready === providerReady) return;
+		providerReady = ready;
+		// A readiness change must appear without waiting for the next turn.
+		sync(lastContext);
+	};
+
+	const sourceFetch = async (
+		apiKey: string | undefined,
+		fetchFn: typeof fetch,
+		now: number,
+	): Promise<ProviderUsage | undefined> => {
+		const usage = await fetchOpenCodeGoUsage(apiKey, fetchFn, now, {
+			report: (reason: FailureReason) => {
+				if (reason === "missing-key") markReady(false);
+			},
+		});
+		if (usage) markReady(true);
+		return usage ? withPlan(usage, now) : undefined;
+	};
+
+	const register = (): void => {
+		// Re-registering replaces the source, so this is safe on every session start
+		// and keeps the extension's load order irrelevant.
+		pi.events.emit("gentle-pi:usage-source/v1", {
+			schema: "gentle-pi.usage-source/v1",
+			provider: PROVIDER,
+			pendingNote: PENDING_NOTE,
+			fetch: sourceFetch,
+		});
+	};
+
+	// Register at load and again on every session start: either load order works,
+	// and a session switch re-targets the same provider.
+	register();
+
+	pi.on("session_start", (_event, ctx) => {
+		register();
+		sync(ctx as PeakContext | undefined);
+	});
+
+	pi.on("model_select", (_event, ctx) => sync(ctx as PeakContext | undefined));
+
+	// A turn can cross a boundary; the next one re-reads the clock.
+	pi.on("turn_end", (_event, ctx) => sync(ctx as PeakContext | undefined));
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		clearTimer();
+		(ctx as PeakContext | undefined)?.ui?.setWidget?.(PEAK_WIDGET_KEY, undefined);
+	});
+}

package/src/labels.ts

@@ -0,0 +1,52 @@
+/**
+ * The strings Gentle Shell paints for the OpenCode Go peak schedule.
+ *
+ * Two surfaces, two different freedoms:
+ *
+ * - The usage panel prints `ProviderUsage.plan` inside its own muted role and
+ *   never sanitizes it, so the header is plain text: the schedule rides there
+ *   unconditionally, and red stays reserved for near-limit quota inside the
+ *   panel. The panel already prints ` · ` before that field, so the field itself
+ *   carries no leading separator.
+ * - The widget line is this extension's own row above the editor, so it paints
+ *   itself: `peak` is amber while DeepSeek is peak-priced, and every escape is
+ *   closed with `\x1b[0m` so nothing leaks into neighbouring rows. Off-peak has
+ *   no widget line at all.
+ *
+ * The panel's window labels stay untouched: the rows read `go 5h`, `go week`,
+ * `go month`, with the schedule only on the provider line.
+ *
+ * Nothing here reads a clock; every function takes the instant it must describe.
+ */
+
+import { formatBoundaryClock, formatPeakState, type PeakState } from "./peak.ts";
+
+/** The key this extension owns in pi's widget map. */
+export const PEAK_WIDGET_KEY = "opencode-go-peak-widget";
+
+const AMBER = "\x1b[33m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+/**
+ * The schedule the panel prints on its provider line, between the provider name
+ * and the `updated …` note: `off-peak 3hr 20m`.
+ *
+ * The panel inserts its own ` · ` before this field, so the field never starts
+ * with one: a leading separator here would render as a doubled ` ·  · `.
+ */
+export function panelSchedule(state: PeakState, now: number): string {
+	return formatPeakState(state, now);
+}
+
+/**
+ * The single widget line, shown only while DeepSeek is peak-priced:
+ * `peak · 2× deepseek · until 04:00`. There is no off-peak variant; the caller
+ * clears the widget instead. The boundary is rendered in the machine's own
+ * timezone: `timeZone` is not passed here, only by unit tests that call
+ * `formatBoundaryClock` directly.
+ */
+export function peakWidgetLine(state: PeakState, now: number): string {
+	const clock = formatBoundaryClock(state.until, now);
+	return `${AMBER}peak${DIM} · 2× deepseek · until ${clock}${RESET}`;
+}

package/src/peak.ts

@@ -0,0 +1,159 @@
+/**
+ * OpenCode Go's DeepSeek pricing schedule.
+ *
+ * OpenCode Go publishes two peak windows for its two DeepSeek models, and bills
+ * them at double the off-peak rate. The windows are stated in UTC and only on
+ * weekdays; every other hour, and both weekend days in full, are off-peak.
+ *
+ * ```
+ * Peak 1  01:00-04:00 UTC   Monday through Friday
+ * Peak 2  06:00-10:00 UTC   Monday through Friday
+ * ```
+ *
+ * Nothing here reads a clock: every function takes the instant it must reason
+ * about, so the panel and the bar never disagree and the schedule is testable
+ * without freezing time.
+ */
+
+/** The two published peak windows, in UTC hours, half-open (`start <= t < end`). */
+const PEAK_WINDOWS = [
+	{ startHour: 1, endHour: 4 },
+	{ startHour: 6, endHour: 10 },
+] as const;
+
+/**
+ * How far ahead to look for the next transition. A Friday evening can put the
+ * next window three days out; the extra margin keeps the search correct without
+ * ever approximating the answer.
+ */
+const DAYS_AHEAD = 9;
+
+const MS_PER_DAY = 86_400_000;
+const MINUTE_MS = 60_000;
+
+export type PeakKind = "peak" | "off-peak";
+
+export interface PeakState {
+	kind: PeakKind;
+	/** The instant this state ends, in epoch milliseconds. */
+	until: number;
+}
+
+/**
+ * The peak-priced model ids, matched leniently on purpose: the published ids
+ * drift in punctuation (`v4.1-flash`, `v4-flash`, a `-high` reasoning suffix),
+ * but the pricing contract is the family, not the spelling.
+ */
+const DEEPSEEK_PEAK_PRICING = /^deepseek-v4(?:\.1)?[-._]?(?:flash|pro)/i;
+
+/**
+ * True when this model id belongs to the peak-priced DeepSeek family. The test is
+ * provider-independent on purpose: the schedule follows the model, so the same id
+ * served by any provider earns the same peak reading.
+ */
+export function deepseekPeakPricing(modelId: string | undefined): boolean {
+	if (typeof modelId !== "string") return false;
+	return DEEPSEEK_PEAK_PRICING.test(modelId);
+}
+
+function isUtcWeekday(ts: number): boolean {
+	const day = new Date(ts).getUTCDay();
+	return day !== 0 && day !== 6;
+}
+
+/** The schedule predicate itself, evaluated at one instant. */
+function isPeakInstant(ts: number): boolean {
+	if (!isUtcWeekday(ts)) return false;
+	const date = new Date(ts);
+	const minute = date.getUTCHours() * 60 + date.getUTCMinutes();
+	return PEAK_WINDOWS.some(({ startHour, endHour }) => minute >= startHour * 60 && minute < endHour * 60);
+}
+
+/**
+ * Every instant that could be a transition, before filtering. Weekends produce
+ * candidates too; they are dropped by the transition test in `nextTransition`,
+ * which is what keeps a Saturday 01:00 from being reported as a change.
+ */
+function candidateInstants(now: number): number[] {
+	const date = new Date(now);
+	const year = date.getUTCFullYear();
+	const month = date.getUTCMonth();
+	const day = date.getUTCDate();
+	const instants: number[] = [];
+	for (let offset = 0; offset <= DAYS_AHEAD; offset++) {
+		for (const { startHour, endHour } of PEAK_WINDOWS) {
+			instants.push(Date.UTC(year, month, day + offset, startHour));
+			instants.push(Date.UTC(year, month, day + offset, endHour));
+		}
+	}
+	return instants;
+}
+
+/**
+ * The next instant at which the schedule actually flips. A candidate counts only
+ * when the predicate disagrees across it by one millisecond, so the answer is the
+ * end of the current state whether that state is a peak window or an off-peak gap
+ * that spans a weekend.
+ */
+export function nextTransition(now: number): number {
+	let next = now + DAYS_AHEAD * MS_PER_DAY;
+	for (const instant of candidateInstants(now)) {
+		if (instant <= now || instant >= next) continue;
+		if (isPeakInstant(instant - 1) !== isPeakInstant(instant)) next = instant;
+	}
+	return next;
+}
+
+/** Whether `now` falls in a peak window, and when that answer changes. */
+export function peakStateAt(now: number): PeakState {
+	if (!Number.isFinite(now)) return { kind: "off-peak", until: 0 };
+	return { kind: isPeakInstant(now) ? "peak" : "off-peak", until: nextTransition(now) };
+}
+
+/**
+ * A compact remaining time, in the same shape the shell uses for quota resets.
+ * Rounds up, so a live window never reads as already over.
+ */
+export function formatCountdown(milliseconds: number): string {
+	if (!Number.isFinite(milliseconds) || milliseconds <= 0) return "now";
+	const minutes = Math.ceil(milliseconds / MINUTE_MS);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	const restMinutes = minutes % 60;
+	if (hours < 24) return restMinutes === 0 ? `${hours}hr` : `${hours}hr ${restMinutes}m`;
+	const days = Math.floor(hours / 24);
+	const restHours = hours % 24;
+	return restHours === 0 ? `${days}d` : `${days}d ${restHours}hr`;
+}
+
+/**
+ * The next transition as a local clock: `04:00` on the same local date, or
+ * `Mon 01:00` when the boundary falls on another one. The instant the schedule
+ * actually ends is printed, never a countdown. `timeZone` is optional so a test
+ * can pin the locale without freezing the machine's clock.
+ */
+export function formatBoundaryClock(until: number, now: number, timeZone?: string): string {
+	if (!Number.isFinite(until) || !Number.isFinite(now)) return "now";
+	const boundary = new Date(until);
+	const clock = new Intl.DateTimeFormat("en-US", {
+		hour: "2-digit",
+		minute: "2-digit",
+		hour12: false,
+		timeZone,
+	}).format(boundary);
+	const localDate = (instant: Date): string =>
+		new Intl.DateTimeFormat("en-US", { year: "numeric", month: "2-digit", day: "2-digit", timeZone }).format(
+			instant,
+		);
+	if (localDate(boundary) === localDate(new Date(now))) return clock;
+	const weekday = new Intl.DateTimeFormat("en-US", { weekday: "short", timeZone }).format(boundary);
+	return `${weekday} ${clock}`;
+}
+
+/**
+ * `peak 20m` or `off-peak 3hr 20m`: the state, then the time left in it, with no
+ * word between and no colour.
+ */
+export function formatPeakState(state: PeakState, now: number): string {
+	return `${state.kind} ${formatCountdown(state.until - now)}`;
+}

package/src/usage.ts

@@ -0,0 +1,224 @@
+/**
+ * OpenCode Go subscription usage, read from the read-only endpoint the OpenCode
+ * console itself uses: `GET /zen/go/v1/usage`, authenticated with the same API
+ * key Pi already holds for the `opencode-go` provider.
+ *
+ * The endpoint answers three windows and reports each as a used percentage plus
+ * a reset instant. It does not publish how long a window is, so the spans below
+ * are display durations: they drive the label, the meter width and the ordering
+ * the shell draws, never the percentage or the reset time.
+ */
+
+export const PROVIDER = "opencode-go";
+
+/** The only URL this package can reach. There is no configuration for it. */
+export const USAGE_URL = "https://opencode.ai/zen/go/v1/usage";
+
+/** Matches Gentle Shell's own default provider window. */
+export const REQUEST_TIMEOUT_MS = 10_000;
+
+/** Opt-in diagnostics: fixed reason codes only, never a key or an error text. */
+export const DEBUG_ENV = "PI_OPENCODE_GO_USAGE_DEBUG";
+
+/** The row name: the panel prints `<limit name> <window label>` per line, lowercased
+ * to match the panel's own lowercase voice. */
+const LIMIT_NAME = "go";
+
+const HOUR = 3600;
+const DAY = 24 * HOUR;
+
+/**
+ * The endpoint's three windows. The month is approximated at 30 days because no
+ * length is published for it; a calendar month is not always 30 days.
+ */
+const WINDOWS = [
+	{ key: "rolling", label: "5h", seconds: 5 * HOUR },
+	{ key: "weekly", label: "week", seconds: 7 * DAY },
+	{ key: "monthly", label: "month", seconds: 30 * DAY },
+] as const;
+
+/**
+ * The two statuses the endpoint is known to answer with. Anything else is
+ * treated as a malformed payload rather than guessed at, because the shell
+ * keeps its last good snapshot and a wrong number is worse than none.
+ */
+const KNOWN_STATUSES: ReadonlySet<string> = new Set(["ok", "rate-limited"]);
+
+/** A full ISO 8601 instant, with an explicit offset or `Z`. */
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * Mirrors the `UsageWindow` Gentle Shell validates a registered source against.
+ * Declared here because that type lives in a private module of gentle-pi, so a
+ * contract drift shows up as the shell discarding this source rather than as a
+ * failed import in this package.
+ */
+export interface UsageWindow {
+	label: string;
+	usedPercent: number;
+	windowSeconds: number;
+	resetAt: number | null;
+}
+
+/** Mirrors `UsageLimit`. */
+export interface UsageLimit {
+	name: string;
+	windows: UsageWindow[];
+	limitReached: boolean;
+	scope?: "provider";
+}
+
+/**
+ * Mirrors the `ProviderUsage` shape the same contract validates. The `plan` field
+ * stays because the shell's contract has it; this source never fills it, since the
+ * usage route publishes percentages only.
+ */
+export interface ProviderUsage {
+	provider: string;
+	plan: string | undefined;
+	limits: UsageLimit[];
+	fetchedAt: number;
+}
+
+/** Why a refresh produced nothing. A fixed code, never a message. */
+export type FailureReason =
+	| "missing-key"
+	| "timeout"
+	| "network"
+	| "redirect"
+	| `http-${number}`
+	| "invalid-json"
+	| "unexpected-shape"
+	| `unexpected-shape:${string}`;
+
+export interface FetchOptions {
+	timeoutMs?: number;
+	/** Diagnostics sink; receives a fixed reason code only. */
+	report?: (reason: FailureReason) => void;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * One window, or `undefined` when anything about it is untrustworthy. Fields are
+ * read and rebuilt one by one, never merged, so a hostile payload cannot reach
+ * this object.
+ */
+function parseWindow(value: unknown, label: string, windowSeconds: number): UsageWindow | undefined {
+	if (!isRecord(value)) return undefined;
+	if (typeof value.status !== "string" || !KNOWN_STATUSES.has(value.status)) return undefined;
+	const percent = value.percent;
+	if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0 || percent > 100) return undefined;
+	if (typeof value.resetsAt !== "string" || !ISO_INSTANT.test(value.resetsAt)) return undefined;
+	const resetAt = Date.parse(value.resetsAt);
+	if (!Number.isFinite(resetAt)) return undefined;
+	return { label, usedPercent: percent, windowSeconds, resetAt };
+}
+
+function readUsage(payload: unknown): Record<string, unknown> | undefined {
+	if (!isRecord(payload) || !isRecord(payload.usage)) return undefined;
+	return payload.usage;
+}
+
+/**
+ * Converts one `/zen/go/v1/usage` payload into the windows Gentle Shell draws,
+ * or `undefined` when the payload is not exactly the expected shape.
+ *
+ * All or nothing on purpose: a snapshot missing one window would make a depleted
+ * subscription look less used than it is, and the shell already keeps the last
+ * valid snapshot through a failed read.
+ */
+export function parseOpenCodeGoUsage(payload: unknown, now: number): ProviderUsage | undefined {
+	if (!Number.isFinite(now)) return undefined;
+	const usage = readUsage(payload);
+	if (!usage) return undefined;
+	const windows: UsageWindow[] = [];
+	for (const { key, label, seconds } of WINDOWS) {
+		const window = parseWindow(usage[key], label, seconds);
+		if (!window) return undefined;
+		windows.push(window);
+	}
+	const limitReached =
+		windows.some((window) => window.usedPercent >= 100) ||
+		WINDOWS.some(({ key }) => (usage[key] as { status?: unknown }).status === "rate-limited");
+	return {
+		provider: PROVIDER,
+		plan: undefined,
+		limits: [{ name: LIMIT_NAME, windows, limitReached, scope: "provider" }],
+		fetchedAt: now,
+	};
+}
+
+function defaultReport(reason: FailureReason): void {
+	if (process.env[DEBUG_ENV]) console.error(`[pi-opencode-gs] ${reason}`);
+}
+
+interface RequestResult {
+	usage?: ProviderUsage;
+	reason?: FailureReason;
+}
+
+async function requestUsage(
+	apiKey: string | undefined,
+	fetchFn: typeof fetch,
+	now: number,
+	timeoutMs: number,
+): Promise<RequestResult> {
+	if (typeof apiKey !== "string" || apiKey.length === 0) return { reason: "missing-key" };
+	const signal = AbortSignal.timeout(timeoutMs);
+	let response: Response;
+	try {
+		response = await fetchFn(USAGE_URL, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+			cache: "no-store",
+			// A redirect could replay the bearer to another origin.
+			redirect: "error",
+			signal,
+		});
+	} catch {
+		return { reason: signal.aborted ? "timeout" : "network" };
+	}
+	// Defense in depth: a fetch implementation that follows redirects anyway must
+	// not deliver a body read from anywhere but this route.
+	if (response.redirected || (response.url && response.url !== USAGE_URL)) return { reason: "redirect" };
+	if (!response.ok) return { reason: `http-${response.status}` };
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch {
+		return { reason: signal.aborted ? "timeout" : "invalid-json" };
+	}
+	if (!isRecord(payload) || !isRecord(payload.usage)) return { reason: "unexpected-shape" };
+	const usage = parseOpenCodeGoUsage(payload, now);
+	if (!usage) {
+		const missing = WINDOWS.find(({ key }) => !isRecord((payload.usage as Record<string, unknown>)[key]));
+		return { reason: missing ? `unexpected-shape:${missing.key}` : "unexpected-shape" };
+	}
+	return { usage };
+}
+
+/**
+ * Fetches one usage snapshot, or `undefined` when there is nothing trustworthy to
+ * show. The key is used in the `Authorization` header and returned nowhere else;
+ * failures resolve to `undefined` and report only a fixed reason code.
+ */
+export async function fetchOpenCodeGoUsage(
+	apiKey: string | undefined,
+	fetchFn: typeof fetch,
+	now: number,
+	options: FetchOptions = {},
+): Promise<ProviderUsage | undefined> {
+	const { timeoutMs = REQUEST_TIMEOUT_MS, report = defaultReport } = options;
+	const { usage, reason } = await requestUsage(apiKey, fetchFn, now, timeoutMs);
+	if (reason) {
+		try {
+			report(reason);
+		} catch {
+			// Diagnostics never break a refresh.
+		}
+	}
+	return usage;
+}