@narumitw/pi-codex-usage 0.14.0 → 0.15.0

package/README.md

@@ -9,8 +9,10 @@ Use it when you want a quick Codex-style usage summary without leaving Pi or req
 ## ✨ Features
 
 - Adds a `/codex-status` command to Pi.
-- Shows Codex plan, 5-hour and weekly usage windows, reset times, and credits.
+- Shows Codex usage windows, reset times, credits, and earned usage-limit resets.
+- Labels each window from its reported duration (for example, 5-hour or weekly).
 - Displays additional usage buckets when the Codex backend returns them.
+- Reads the authoritative available reset count from the current Codex usage contract.
 - Automatically shows a compact statusline item while the current Pi model uses `openai-codex`.
 - Uses Pi's own OpenAI Codex subscription auth first.
 - Falls back to `codex app-server --listen stdio://` only when Pi auth is unavailable.
@@ -59,6 +61,8 @@ information on rate limits and credits
   GPT-5.3-Codex-Spark limit:
   5h limit:                    [████████████████████] 100% left (resets 19:16)
   Weekly limit:                [████████████████████] 100% left (resets 00:10 on 21 May)
+
+  Usage limit resets:          2 available
 ```
 
 ## 📊 Statusline behavior
@@ -70,7 +74,7 @@ codex 59% 5h 61% wk
 codex spark 100% 5h 100% wk
 ```
 
-`@narumitw/pi-statusline` adds the default `📊` icon unless configured otherwise. The statusline value uses the cached usage snapshot and refreshes every five minutes while the current model remains `openai-codex`.
+`@narumitw/pi-statusline` adds the default `📊` icon unless configured otherwise. The statusline value uses the cached usage snapshot and refreshes every five minutes while the current model remains `openai-codex`. Window labels come from the duration reported by Codex, with 5-hour/weekly fallbacks for older responses that omit it.
 When the selected model has its own returned usage bucket, such as `gpt-5.3-codex-spark`, the statusline switches to that bucket instead of the default `codex` bucket.
 Switching away from an OpenAI Codex model clears the item.
 
@@ -85,6 +89,8 @@ Use `/codex-status --no-statusline` for a one-off notification without updating
 
 This means Codex CLI is optional. Users who already use a Pi OpenAI Codex model or have logged in to Pi with ChatGPT Plus/Pro subscription auth can use the direct Pi-auth path.
 
+The direct `/wham/usage` response can include the snake_case `rate_limit_reset_credits` summary. Current Codex app-server responses expose the same authoritative count as camelCase `rateLimitResetCredits` and may also include capped detail rows. The extension accepts both forms and keeps the compact statusline focused on rate-limit windows.
+
 The extension does not read Pi or Codex auth files directly, and it does not expose bearer tokens in error messages.
 
 ## 🚧 Limitations
@@ -92,6 +98,7 @@ The extension does not read Pi or Codex auth files directly, and it does not exp
 - OpenAI API keys are not ChatGPT Codex subscription auth and do not expose this quota.
 - Usage data is a snapshot. Statusline and command results are cached for five minutes unless `--refresh` is used.
 - The fallback path requires Codex CLI to be installed and logged in.
+- `/codex-status` reports earned usage-limit resets but does not redeem them.
 
 ## 🗂️ Package layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-codex-usage",
-	"version": "0.14.0",
+	"version": "0.15.0",
 	"description": "Pi extension that shows Codex ChatGPT subscription usage without requiring Codex CLI.",
 	"type": "module",
 	"license": "MIT",

package/src/codex-usage.ts

@@ -1,19 +1,6 @@
-import type {
-	ExtensionAPI,
-	ExtensionCommandContext,
-	ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
-import {
-	formatCodexUsageReport,
-	formatCodexUsageStatusline,
-	formatQueryErrors,
-	showReport,
-} from "./format.js";
-import {
-	isOpenAICodexModel,
-	isStaleExtensionContextError,
-	queryUsage,
-} from "./query.js";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { formatCodexUsageStatusline, formatQueryErrors, showReport } from "./format.js";
+import { isOpenAICodexModel, isStaleExtensionContextError, queryUsage } from "./query.js";
 import type {
 	CachedReport,
 	CodexUsageModel,
@@ -34,7 +21,11 @@ interface CommandArgumentCompletion {
 
 const COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = [
 	{ value: "--refresh", label: "--refresh", description: "Refresh usage instead of cached data" },
-	{ value: "--no-statusline", label: "--no-statusline", description: "Do not update the statusline" },
+	{
+		value: "--no-statusline",
+		label: "--no-statusline",
+		description: "Do not update the statusline",
+	},
 	{
 		value: "--clear-statusline",
 		label: "--clear-statusline",
@@ -192,8 +183,7 @@ export default function codexUsage(pi: ExtensionAPI) {
 				}
 
 				let keepStatusline = false;
-				const statuslineStarted =
-					options.value.statusline && setStatuslineValue(ctx, "checking");
+				const statuslineStarted = options.value.statusline && setStatuslineValue(ctx, "checking");
 				try {
 					const result = await queryUsage(ctx, options.value);
 					if (!result.ok) {
@@ -333,6 +323,8 @@ export type {
 	CodexUsageModel,
 	CodexUsageReport,
 	NormalizedCredits,
+	NormalizedRateLimitResetCredit,
+	NormalizedRateLimitResetCredits,
 	NormalizedRateLimitSnapshot,
 	NormalizedRateLimitWindow,
 } from "./types.js";

package/src/format.ts

@@ -31,13 +31,20 @@ export function formatCodexUsageReport(report: CodexUsageReport, _cacheAgeMs?: n
 		if (!isPrimaryCodexSnapshot(snapshot)) {
 			lines.push(`  ${label} limit:`);
 		}
-		if (snapshot.primary) lines.push(formatWindowLine("5h limit:", snapshot.primary));
-		if (snapshot.secondary) lines.push(formatWindowLine("Weekly limit:", snapshot.secondary));
+		if (snapshot.primary) lines.push(formatWindowLine(snapshot.primary, "5h"));
+		if (snapshot.secondary) lines.push(formatWindowLine(snapshot.secondary, "weekly"));
 		if (!snapshot.primary && !snapshot.secondary) {
 			lines.push("  Limits unavailable for this account");
 		}
 	}
 
+	if (report.resetCredits) {
+		if (report.snapshots.length > 0) lines.push("");
+		lines.push(
+			`  ${"Usage limit resets:".padEnd(LIMIT_VALUE_COLUMN)}${report.resetCredits.availableCount} available`,
+		);
+	}
+
 	return lines.join("\n");
 }
 
@@ -49,8 +56,16 @@ export function formatCodexUsageStatusline(
 	if (!snapshot) return "usage unavailable";
 
 	const parts = [formatStatuslinePrefix(snapshot)];
-	if (snapshot.primary) parts.push(`${formatRemainingPercent(snapshot.primary)} 5h`);
-	if (snapshot.secondary) parts.push(`${formatRemainingPercent(snapshot.secondary)} wk`);
+	if (snapshot.primary) {
+		parts.push(
+			`${formatRemainingPercent(snapshot.primary)} ${formatWindowLabel(snapshot.primary, "5h", true)}`,
+		);
+	}
+	if (snapshot.secondary) {
+		parts.push(
+			`${formatRemainingPercent(snapshot.secondary)} ${formatWindowLabel(snapshot.secondary, "weekly", true)}`,
+		);
+	}
 	if (parts.length === 1 && snapshot.credits) parts.push(formatCredits(snapshot.credits));
 	return parts.join(" ");
 }
@@ -171,10 +186,34 @@ function isPrimaryCodexSnapshot(snapshot: NormalizedRateLimitSnapshot): boolean
 	);
 }
 
-function formatWindowLine(label: string, window: NormalizedRateLimitWindow): string {
+function formatWindowLine(
+	window: NormalizedRateLimitWindow,
+	fallback: "5h" | "weekly",
+): string {
+	const label = `${formatWindowLabel(window, fallback, false)} limit:`;
 	return `  ${label.padEnd(LIMIT_VALUE_COLUMN)}${formatWindow(window)}`;
 }
 
+function formatWindowLabel(
+	window: NormalizedRateLimitWindow,
+	fallback: "5h" | "weekly",
+	compact: boolean,
+): string {
+	const minutes = window.windowMinutes;
+	if (!minutes || !Number.isFinite(minutes) || minutes <= 0) {
+		return compact && fallback === "weekly" ? "wk" : capitalize(fallback);
+	}
+	if (minutes === 10_080) return compact ? "wk" : "Weekly";
+	if (minutes % 10_080 === 0) return `${minutes / 10_080}w`;
+	if (minutes % 1_440 === 0) return `${minutes / 1_440}d`;
+	if (minutes % 60 === 0) return `${minutes / 60}h`;
+	return `${minutes}m`;
+}
+
+function capitalize(value: string): string {
+	return `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}`;
+}
+
 function formatWindow(window: NormalizedRateLimitWindow): string {
 	const remaining = 100 - clampPercent(window.usedPercent);
 	const reset = window.resetsAt ? ` (resets ${formatReset(window.resetsAt)})` : "";
@@ -222,37 +261,6 @@ export function formatQueryErrors(errors: UsageQueryError[]): string {
 	return lines.join("\n");
 }
 
-function formatPlanType(planType: string): string {
-	const key = planType
-		.replace(/([a-z])([A-Z])/g, "$1_$2")
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, "_");
-	if (key === "pro_lite" || key === "prolite") return "Pro Lite";
-	if (key === "team" || key === "self_serve_business_usage_based" || key === "business") {
-		return "Business";
-	}
-	if (key === "enterprise_cbp_usage_based") return "Enterprise";
-
-	const normalized = planType
-		.replace(/([a-z])([A-Z])/g, "$1 $2")
-		.replace(/[_-]+/g, " ")
-		.trim();
-	if (!normalized) return planType;
-	return normalized
-		.split(/\s+/)
-		.map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
-		.join(" ");
-}
-
-function formatDuration(milliseconds: number): string {
-	const seconds = Math.max(0, Math.round(milliseconds / 1000));
-	if (seconds < 60) return `${seconds}s`;
-	const minutes = Math.round(seconds / 60);
-	if (minutes < 60) return `${minutes}m`;
-	const hours = Math.round(minutes / 60);
-	return `${hours}h`;
-}
-
 function formatNumber(value: number, fallback: string): string {
 	if (!Number.isFinite(value)) return fallback;
 	return new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 }).format(value);

package/src/normalize.ts

@@ -1,14 +1,19 @@
 import type {
 	AppServerCreditsSnapshot,
+	AppServerRateLimitResetCredit,
+	AppServerRateLimitResetCredits,
 	AppServerRateLimitResponse,
 	AppServerRateLimitSnapshot,
 	AppServerWindowSnapshot,
 	BackendAdditionalRateLimit,
 	BackendCreditsSnapshot,
 	BackendRateLimitDetails,
+	BackendRateLimitResetCredits,
 	BackendWindowSnapshot,
 	CodexUsageReport,
 	NormalizedCredits,
+	NormalizedRateLimitResetCredit,
+	NormalizedRateLimitResetCredits,
 	NormalizedRateLimitSnapshot,
 	NormalizedRateLimitWindow,
 	RateLimitStatusPayload,
@@ -29,27 +34,30 @@ export function normalizeBackendPayload(
 		? payload.additional_rate_limits
 		: [];
 	for (const item of additional) {
-		const additionalLimit = assertObject(
-			item,
-			"additional rate limit",
-		) as BackendAdditionalRateLimit;
+		const additionalLimit = asObject(item) as BackendAdditionalRateLimit | undefined;
+		if (!additionalLimit) continue;
 		const limitId =
 			asString(additionalLimit.metered_feature) ?? asString(additionalLimit.limit_name);
 		if (!limitId) continue;
-		const snapshot = normalizeBackendSnapshot(
-			limitId,
-			asString(additionalLimit.limit_name),
-			additionalLimit.rate_limit,
-			undefined,
-		);
-		if (snapshot) snapshots.push(snapshot);
+		try {
+			const snapshot = normalizeBackendSnapshot(
+				limitId,
+				asString(additionalLimit.limit_name),
+				additionalLimit.rate_limit,
+				undefined,
+			);
+			if (snapshot) snapshots.push(snapshot);
+		} catch {
+			// Optional additional buckets must not hide otherwise usable primary/reset usage.
+		}
 	}
 
-	if (snapshots.length === 0) {
-		throw new Error("Codex usage endpoint returned no displayable rate-limit windows.");
+	const resetCredits = normalizeBackendRateLimitResetCredits(payload.rate_limit_reset_credits);
+	if (snapshots.length === 0 && !resetCredits) {
+		throw new Error("Codex usage endpoint returned no displayable usage data.");
 	}
 
-	return { source, capturedAt, planType, snapshots };
+	return { source, capturedAt, planType, snapshots, resetCredits };
 }
 
 function normalizeBackendSnapshot(
@@ -95,13 +103,27 @@ function normalizeBackendCredits(value: unknown): NormalizedCredits | undefined
 	return { hasCredits, unlimited, balance: asString(credits.balance) };
 }
 
+function normalizeBackendRateLimitResetCredits(
+	value: unknown,
+): NormalizedRateLimitResetCredits | undefined {
+	const resetCredits = asObject(value) as BackendRateLimitResetCredits | undefined;
+	const availableCount = asNonnegativeInteger(resetCredits?.available_count);
+	return availableCount === undefined ? undefined : { availableCount };
+}
+
 export function normalizeAppServerResponse(
 	response: AppServerRateLimitResponse,
 	capturedAt: number,
 ): CodexUsageReport {
 	const snapshots: NormalizedRateLimitSnapshot[] = [];
-	const addSnapshot = (raw: unknown, fallbackId: string) => {
-		const snapshot = normalizeAppServerSnapshot(raw, fallbackId);
+	const addSnapshot = (raw: unknown, fallbackId: string, optional = false) => {
+		let snapshot: NormalizedRateLimitSnapshot | undefined;
+		try {
+			snapshot = normalizeAppServerSnapshot(raw, fallbackId);
+		} catch (error) {
+			if (optional) return;
+			throw error;
+		}
 		if (!snapshot) return;
 		const existingIndex = snapshots.findIndex((item) => item.limitId === snapshot.limitId);
 		if (existingIndex >= 0)
@@ -110,18 +132,26 @@ export function normalizeAppServerResponse(
 	};
 
 	addSnapshot(response.rateLimits, "codex");
-	if (response.rateLimitsByLimitId && typeof response.rateLimitsByLimitId === "object") {
-		for (const [limitId, raw] of Object.entries(response.rateLimitsByLimitId)) {
-			addSnapshot(raw, limitId);
+	const snapshotsByLimitId = asObject(response.rateLimitsByLimitId);
+	if (snapshotsByLimitId) {
+		for (const [limitId, raw] of Object.entries(snapshotsByLimitId)) {
+			if (limitId) addSnapshot(raw, limitId, true);
 		}
 	}
 
-	if (snapshots.length === 0) {
-		throw new Error("codex app-server returned no displayable rate-limit windows.");
+	const resetCredits = normalizeAppServerRateLimitResetCredits(response.rateLimitResetCredits);
+	if (snapshots.length === 0 && !resetCredits) {
+		throw new Error("codex app-server returned no displayable usage data.");
 	}
 
 	const planType = asAppServerPlanType(response.rateLimits);
-	return { source: "codex-app-server", capturedAt, planType, snapshots };
+	return {
+		source: "codex-app-server",
+		capturedAt,
+		planType,
+		snapshots,
+		resetCredits,
+	};
 }
 
 function asAppServerPlanType(raw: unknown): string | undefined {
@@ -172,6 +202,49 @@ function normalizeAppServerCredits(value: unknown): NormalizedCredits | undefine
 	return { hasCredits, unlimited, balance: asString(credits.balance) };
 }
 
+function normalizeAppServerRateLimitResetCredits(
+	value: unknown,
+): NormalizedRateLimitResetCredits | undefined {
+	const resetCredits = asObject(value) as AppServerRateLimitResetCredits | undefined;
+	const availableCount = asNonnegativeInteger(resetCredits?.availableCount);
+	if (availableCount === undefined) return undefined;
+
+	const rawCredits = resetCredits?.credits;
+	if (!Array.isArray(rawCredits)) return { availableCount };
+
+	const credits = rawCredits
+		.map(normalizeAppServerRateLimitResetCredit)
+		.filter((credit): credit is NormalizedRateLimitResetCredit => credit !== undefined)
+		.slice(0, availableCount);
+	if (rawCredits.length > 0 && credits.length === 0 && availableCount > 0) {
+		return { availableCount };
+	}
+	return { availableCount, credits };
+}
+
+function normalizeAppServerRateLimitResetCredit(
+	value: unknown,
+): NormalizedRateLimitResetCredit | undefined {
+	const credit = asObject(value) as AppServerRateLimitResetCredit | undefined;
+	const id = asString(credit?.id);
+	if (!id) return undefined;
+
+	const normalized: NormalizedRateLimitResetCredit = { id };
+	const resetType = asString(credit?.resetType);
+	const status = asString(credit?.status);
+	const grantedAt = asNumber(credit?.grantedAt);
+	const expiresAt = asNumber(credit?.expiresAt);
+	const title = asString(credit?.title);
+	const description = asString(credit?.description);
+	if (resetType !== undefined) normalized.resetType = resetType;
+	if (status !== undefined) normalized.status = status;
+	if (grantedAt !== undefined) normalized.grantedAt = grantedAt;
+	if (expiresAt !== undefined) normalized.expiresAt = expiresAt;
+	if (title !== undefined) normalized.title = title;
+	if (description !== undefined) normalized.description = description;
+	return normalized;
+}
+
 function mergeSnapshot(
 	left: NormalizedRateLimitSnapshot,
 	right: NormalizedRateLimitSnapshot,
@@ -186,9 +259,13 @@ function mergeSnapshot(
 }
 
 function assertObject(value: unknown, description: string): Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		throw new Error(`${description} was not an object.`);
-	}
+	const object = asObject(value);
+	if (!object) throw new Error(`${description} was not an object.`);
+	return object;
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
 	return value as Record<string, unknown>;
 }
 
@@ -208,3 +285,9 @@ function asNumber(value: unknown): number | undefined {
 function asBoolean(value: unknown): boolean | undefined {
 	return typeof value === "boolean" ? value : undefined;
 }
+
+function asNonnegativeInteger(value: unknown): number | undefined {
+	const parsed = asNumber(value);
+	if (parsed === undefined || !Number.isSafeInteger(parsed)) return undefined;
+	return Math.max(0, parsed);
+}

package/src/types.ts

@@ -31,6 +31,22 @@ export type CodexUsageReport = {
 	capturedAt: number;
 	planType?: string;
 	snapshots: NormalizedRateLimitSnapshot[];
+	resetCredits?: NormalizedRateLimitResetCredits;
+};
+
+export type NormalizedRateLimitResetCredits = {
+	availableCount: number;
+	credits?: NormalizedRateLimitResetCredit[];
+};
+
+export type NormalizedRateLimitResetCredit = {
+	id: string;
+	resetType?: string;
+	status?: string;
+	grantedAt?: number;
+	expiresAt?: number;
+	title?: string;
+	description?: string;
 };
 
 export type NormalizedRateLimitSnapshot = {
@@ -58,6 +74,11 @@ export type RateLimitStatusPayload = {
 	rate_limit?: unknown;
 	additional_rate_limits?: unknown;
 	credits?: unknown;
+	rate_limit_reset_credits?: unknown;
+};
+
+export type BackendRateLimitResetCredits = {
+	available_count?: unknown;
 };
 
 export type BackendRateLimitDetails = {
@@ -86,6 +107,22 @@ export type BackendCreditsSnapshot = {
 export type AppServerRateLimitResponse = {
 	rateLimits?: unknown;
 	rateLimitsByLimitId?: unknown;
+	rateLimitResetCredits?: unknown;
+};
+
+export type AppServerRateLimitResetCredits = {
+	availableCount?: unknown;
+	credits?: unknown;
+};
+
+export type AppServerRateLimitResetCredit = {
+	id?: unknown;
+	resetType?: unknown;
+	status?: unknown;
+	grantedAt?: unknown;
+	expiresAt?: unknown;
+	title?: unknown;
+	description?: unknown;
 };
 
 export type AppServerRateLimitSnapshot = {