@howaboua/pi-codex-conversion 1.5.9 → 1.5.10

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.5.10
+
+- Added `/codex usage` and a Usage tab for OpenAI Codex subscription limits, with automatic refresh and aligned 5-hour/weekly usage columns.
+- Moved settings links into a dedicated About tab.
+
 ## 1.5.9
 
 - Fixed native Responses compaction replay when provider payloads include in-flight tail items that are not yet persisted in the session branch.

package/README.md

@@ -46,11 +46,12 @@ Use `/codex` to change adapter settings.
 - `/codex fast` — toggle priority service tier for the OpenAI Codex provider
 - `/codex search` — toggle native Codex web search
 - `/codex image` — toggle native Codex image generation
+- `/codex usage` — show Codex subscription usage windows for the active OpenAI Codex model
 - `/codex low`, `/codex medium`, `/codex high` — set Responses API verbosity
 
 Settings are saved globally in `~/.pi/agent/pi-codex-conversion.json`.
 
-The settings UI also has an **Overrides** tab. These options intentionally do not have `/codex ...` command shortcuts:
+The settings UI also has **Usage**, **Overrides**, and **About** tabs. **Usage** refreshes automatically when opened and can be refreshed manually with `r`. Override options intentionally do not have `/codex ...` command shortcuts:
 
 - add only the Pi `apply_patch` tool for GPT/Codex models while keeping Pi's default toolkit, prompt, provider behavior, and compaction flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howaboua/pi-codex-conversion",
-  "version": "1.5.9",
+  "version": "1.5.10",
   "description": "Codex-oriented tool and prompt adapter for pi coding agent",
   "type": "module",
   "repository": {

package/src/codex-settings/command.ts

@@ -8,9 +8,10 @@ import {
 import { syncAdapter } from "../adapter/activation.ts";
 import type { AdapterState } from "../adapter/state.ts";
 import { openCodexSettingsScreen } from "./ui.ts";
+import { fetchCodexUsage, formatCodexUsage } from "./usage.ts";
 
-const CODEX_COMMAND_COMPLETIONS = ["all", "status", "fast", "search", "image", "compact", "low", "medium", "high"] as const;
-const CODEX_USAGE = "Usage: /codex, /codex all, /codex status, /codex fast, /codex search, /codex image, /codex compact, /codex low|medium|high";
+const CODEX_COMMAND_COMPLETIONS = ["all", "status", "fast", "search", "image", "compact", "usage", "low", "medium", "high"] as const;
+const CODEX_USAGE = "Usage: /codex, /codex all, /codex status, /codex fast, /codex search, /codex image, /codex compact, /codex usage, /codex low|medium|high";
 
 export function registerCodexCommand(pi: ExtensionAPI, state: AdapterState, onConfigApplied?: (config: CodexConversionConfig) => void): void {
 	function saveAndApply(ctx: ExtensionContext, nextConfig: CodexConversionConfig): boolean {
@@ -32,6 +33,36 @@ export function registerCodexCommand(pi: ExtensionAPI, state: AdapterState, onCo
 		handler: async (args, ctx) => {
 			state.config = readCodexConversionConfig();
 			const arg = args.trim().toLowerCase();
+			if (arg === "usage") {
+				let usage;
+				try {
+					usage = await fetchCodexUsage(ctx);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					if (!ctx.hasUI) {
+						ctx.ui.notify(message, "error");
+						return;
+					}
+					await openCodexSettingsScreen(ctx, {
+						initialConfig: state.config,
+						initialTab: "usage",
+						initialUsage: { error: message },
+						onChange: (config) => saveAndApply(ctx, config),
+					});
+					return;
+				}
+				if (!ctx.hasUI) {
+					ctx.ui.notify(formatCodexUsage(usage), "info");
+					return;
+				}
+				await openCodexSettingsScreen(ctx, {
+					initialConfig: state.config,
+					initialTab: "usage",
+					initialUsage: usage,
+					onChange: (config) => saveAndApply(ctx, config),
+				});
+				return;
+			}
 			if (arg === "compact") {
 				if (!ctx.hasUI) {
 					ctx.ui.notify(formatCodexSettings(state.config), "info");

package/src/codex-settings/ui.ts

@@ -10,25 +10,41 @@ import {
 	type CodexConversionConfig,
 } from "../adapter/config.ts";
 import { CHANGELOG_URL, DISCORD_URL, GITHUB_URL, ISSUE_URL, openExternalUrl } from "./links.ts";
+import { fetchCodexUsage, formatCodexUsage, type CodexUsageSnapshot } from "./usage.ts";
 
 export interface CodexSettingsScreenOptions {
 	initialConfig: CodexConversionConfig;
 	onChange: (nextConfig: CodexConversionConfig) => boolean;
 	initialTab?: SettingsTab;
+	initialUsage?: CodexUsageSnapshot | { error: string };
+	onRefreshUsage?: () => Promise<CodexUsageSnapshot>;
 }
 
-type SettingsTab = "general" | "compaction" | "overrides";
+type SettingsTab = "general" | "compaction" | "usage" | "overrides" | "about";
 
-const TAB_ORDER: readonly SettingsTab[] = ["general", "compaction", "overrides"];
+const TAB_ORDER: readonly SettingsTab[] = ["general", "compaction", "usage", "overrides", "about"];
 
 export async function openCodexSettingsScreen(ctx: ExtensionContext, options: CodexSettingsScreenOptions): Promise<void> {
 	let draft = { ...options.initialConfig };
 	let activeTab: SettingsTab = options.initialTab ?? "general";
+	let usageState: CodexUsageSnapshot | { error: string } | undefined = options.initialUsage;
+	let usageLoading = false;
+
+	const loadUsage = (requestRender: () => void) => {
+		if (usageLoading) return;
+		usageLoading = true;
+		requestRender();
+		(options.onRefreshUsage ?? (() => fetchCodexUsage(ctx)))()
+			.then((usage) => { usageState = usage; })
+			.catch((error) => { usageState = { error: error instanceof Error ? error.message : String(error) }; })
+			.finally(() => { usageLoading = false; requestRender(); });
+	};
 
 	await ctx.ui.custom<void>((tui, theme, _kb, done) => {
 		let settingsList = createSettingsList(activeTab, draft, options, (nextDraft) => {
 			draft = nextDraft;
 		}, done, () => tui.requestRender());
+		if (activeTab === "usage" && !usageState) loadUsage(() => tui.requestRender());
 
 		const switchTab = () => {
 			const currentIndex = TAB_ORDER.indexOf(activeTab);
@@ -36,6 +52,7 @@ export async function openCodexSettingsScreen(ctx: ExtensionContext, options: Co
 			settingsList = createSettingsList(activeTab, draft, options, (nextDraft) => {
 				draft = nextDraft;
 			}, done, () => tui.requestRender());
+			if (activeTab === "usage" && !usageState) loadUsage(() => tui.requestRender());
 			tui.requestRender();
 		};
 
@@ -47,12 +64,12 @@ export async function openCodexSettingsScreen(ctx: ExtensionContext, options: Co
 					rule(width, theme, "borderMuted"),
 					...(activeTab === "compaction" ? formatCompactionNotes(theme) : []),
 					...(activeTab === "overrides" ? formatOverridesNotes(theme) : []),
+					...(activeTab === "usage" ? formatUsageLines(theme, usageState, usageLoading) : []),
+					...(activeTab === "about" ? formatLinks(theme) : []),
 					"",
-					...settingsList.render(width),
-					rule(width, theme, "borderMuted"),
-					...formatLinks(theme),
+					...(activeTab === "usage" || activeTab === "about" ? [] : settingsList.render(width)),
 					rule(width, theme, "accent"),
-					theme.fg("dim", "  Tab to switch sections · g/c/d/i open links"),
+					theme.fg("dim", formatFooter(activeTab)),
 				].map((line) => truncateToWidth(line, width, "")),
 			invalidate: () => settingsList.invalidate(),
 			handleInput: (data: string) => {
@@ -60,7 +77,11 @@ export async function openCodexSettingsScreen(ctx: ExtensionContext, options: Co
 					switchTab();
 					return;
 				}
-				if (handleLinkKey(data, ctx)) return;
+				if (activeTab === "about" && handleLinkKey(data, ctx)) return;
+				if (activeTab === "usage" && data.toLowerCase() === "r") {
+					loadUsage(() => tui.requestRender());
+					return;
+				}
 				settingsList.handleInput?.(data);
 				tui.requestRender();
 			},
@@ -109,6 +130,8 @@ function createSettingsList(
 }
 
 function buildItems(tab: SettingsTab, draft: CodexConversionConfig): SettingItem[] {
+	if (tab === "usage" || tab === "about") return [];
+
 	if (tab === "compaction") {
 		return [
 			{ id: "responsesCompaction", label: "Responses compaction", currentValue: (draft.responsesCompaction ?? false) ? "on" : "off", values: ["off", "on"] },
@@ -150,7 +173,75 @@ function applySettingChange(id: string, value: string, draft: CodexConversionCon
 
 function formatTabs(activeTab: SettingsTab, theme: Theme): string {
 	const renderTab = (tab: SettingsTab, label: string) => activeTab === tab ? theme.bold(label) : theme.fg("dim", label);
-	return `  ${renderTab("general", "General")}  ${theme.fg("dim", "/")}  ${renderTab("compaction", "Compaction")}  ${theme.fg("dim", "/")}  ${renderTab("overrides", "Overrides")}`;
+	return `  ${renderTab("general", "General")}  ${theme.fg("dim", "/")}  ${renderTab("compaction", "Compaction")}  ${theme.fg("dim", "/")}  ${renderTab("usage", "Usage")}  ${theme.fg("dim", "/")}  ${renderTab("overrides", "Overrides")}  ${theme.fg("dim", "/")}  ${renderTab("about", "About")}`;
+}
+
+function formatFooter(activeTab: SettingsTab): string {
+	if (activeTab === "usage") return "  Tab to switch sections · r refresh";
+	if (activeTab === "about") return "  Tab to switch sections · g/c/d/i open links";
+	return "  Tab to switch sections";
+}
+
+function formatUsageLines(theme: Theme, usageState: CodexUsageSnapshot | { error: string } | undefined, loading: boolean): string[] {
+	if (loading && !usageState) return [theme.fg("dim", "  Loading Codex usage…")];
+	if (!usageState) return [theme.fg("dim", "  Loading Codex usage…")];
+	if ("error" in usageState) return [theme.fg("error", `  ${usageState.error}`), theme.fg("dim", "  Press r to retry.")];
+
+	const rows = usageState.limits.map((limit) => {
+		const primary = usageColumns(limit.primary);
+		const secondary = usageColumns(limit.secondary);
+		return [limit.limitName ?? limit.limitId, primary.bar, primary.percent, primary.reset, secondary.bar, secondary.percent, secondary.reset];
+	});
+	const headers = ["Limit", "5h", "", "Reset", "Weekly", "", "Reset"];
+	const widths = columnWidths([headers, ...rows]);
+	return [
+		`  ${theme.bold(`Codex usage${usageState.planType ? ` · ${usageState.planType}` : ""}`)}${loading ? theme.fg("dim", "  refreshing…") : ""}`,
+		"",
+		formatUsageRow(headers.map((header) => theme.fg("dim", header)), widths),
+		theme.fg("borderMuted", `  ${"─".repeat(widths.reduce((sum, width) => sum + width, 0) + (2 * (widths.length - 1)))}`),
+		...rows.map((row) => formatUsageRow(row, widths)),
+	];
+}
+
+function columnWidths(rows: string[][]): number[] {
+	const columnCount = Math.max(...rows.map((row) => row.length));
+	return Array.from({ length: columnCount }, (_, index) => Math.max(...rows.map((row) => stripAnsi(row[index] ?? "").length)));
+}
+
+function stripAnsi(value: string): string {
+	return value.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function padCell(value: string, width: number): string {
+	return value + " ".repeat(Math.max(0, width - stripAnsi(value).length));
+}
+
+function formatUsageRow(row: string[], widths: number[]): string {
+	return `  ${row.map((cell, index) => padCell(cell, widths[index] ?? 0)).join("  ")}`;
+}
+
+function usageColumns(window: { usedPercent?: number; windowMinutes?: number; resetsAt?: number } | undefined): { bar: string; percent: string; reset: string } {
+	if (!window) return { bar: "—", percent: "", reset: "" };
+	const percent = window.usedPercent === undefined ? undefined : Math.max(0, Math.min(100, window.usedPercent));
+	return {
+		bar: bar(percent),
+		percent: percent === undefined ? "?%" : `${Math.round(percent)}%`,
+		reset: formatResetShort(window.resetsAt),
+	};
+}
+
+function bar(percent: number | undefined): string {
+	if (percent === undefined) return "░░░░░░░░░░";
+	const filled = Math.max(0, Math.min(10, Math.round(percent / 10)));
+	return "█".repeat(filled) + "░".repeat(10 - filled);
+}
+
+function formatResetShort(timestampSeconds: number | undefined): string {
+	if (!timestampSeconds) return "reset ?";
+	const minutes = Math.max(0, Math.round((timestampSeconds * 1000 - Date.now()) / 60000));
+	if (minutes < 90) return `~${minutes}m`;
+	if (minutes < 60 * 48) return `~${Math.round(minutes / 60)}h`;
+	return `~${Math.round(minutes / 1440)}d`;
 }
 
 function formatLinks(theme: Theme): string[] {

package/src/codex-settings/usage.ts

@@ -0,0 +1,151 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+const DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+
+type RuntimeModel = Model<Api>;
+
+export interface CodexUsageWindow {
+	usedPercent?: number;
+	windowMinutes?: number;
+	resetsAt?: number;
+}
+
+export interface CodexUsageLimit {
+	limitId: string;
+	limitName?: string;
+	primary?: CodexUsageWindow;
+	secondary?: CodexUsageWindow;
+}
+
+export interface CodexUsageSnapshot {
+	planType?: string;
+	limits: CodexUsageLimit[];
+	raw: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function numberValue(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+export function buildCodexUsageUrl(): string {
+	return `${DEFAULT_CODEX_BASE_URL}/wham/usage`;
+}
+
+function extractBearerToken(headers: Headers): string | undefined {
+	const authorization = headers.get("authorization")?.trim();
+	const match = authorization?.match(/^Bearer\s+(.+)$/i);
+	return match?.[1]?.trim();
+}
+
+function extractAccountId(token: string): string | undefined {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return undefined;
+		const payload = JSON.parse(Buffer.from(parts[1] ?? "", "base64").toString("utf8")) as unknown;
+		const authClaims = isRecord(payload) ? payload[JWT_CLAIM_PATH] : undefined;
+		const accountId = isRecord(authClaims) ? authClaims.chatgpt_account_id : undefined;
+		return stringValue(accountId);
+	} catch {
+		return undefined;
+	}
+}
+
+async function buildCodexUsageHeaders(ctx: ExtensionContext, model: RuntimeModel): Promise<Headers> {
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) throw new Error(auth.error);
+	const headers = new Headers(model.headers);
+	for (const [key, value] of Object.entries(auth.headers ?? {})) headers.set(key, value);
+	if (auth.apiKey) headers.set("authorization", `Bearer ${auth.apiKey}`);
+	const token = auth.apiKey ?? extractBearerToken(headers);
+	const accountId = token ? extractAccountId(token) : undefined;
+	if (accountId) headers.set("chatgpt-account-id", accountId);
+	headers.set("accept", "application/json");
+	headers.set("originator", "pi");
+	return headers;
+}
+
+function parseWindow(value: unknown): CodexUsageWindow | undefined {
+	if (!isRecord(value)) return undefined;
+	const usedPercent = numberValue(value.used_percent);
+	const limitWindowSeconds = numberValue(value.limit_window_seconds);
+	const windowMinutes = numberValue(value.window_minutes) ?? (limitWindowSeconds === undefined ? undefined : Math.ceil(limitWindowSeconds / 60));
+	const resetsAt = numberValue(value.resets_at) ?? numberValue(value.reset_at);
+	return usedPercent === undefined && windowMinutes === undefined && resetsAt === undefined ? undefined : { usedPercent, windowMinutes, resetsAt };
+}
+
+function parseRateLimit(value: unknown): { primary?: CodexUsageWindow; secondary?: CodexUsageWindow } {
+	if (!isRecord(value)) return {};
+	return {
+		primary: parseWindow(value.primary_window) ?? parseWindow(value.primary),
+		secondary: parseWindow(value.secondary_window) ?? parseWindow(value.secondary),
+	};
+}
+
+export function parseCodexUsagePayload(payload: unknown): CodexUsageSnapshot {
+	const root = isRecord(payload) ? payload : {};
+	const limits: CodexUsageLimit[] = [];
+	const addLimit = (limitId: string, limitName: string | undefined, source: unknown) => {
+		const rateLimit = isRecord(source) && "rate_limit" in source ? source.rate_limit : source;
+		const parsed = parseRateLimit(rateLimit);
+		limits.push({
+			limitId,
+			...(limitName ? { limitName } : {}),
+			...(parsed.primary ? { primary: parsed.primary } : {}),
+			...(parsed.secondary ? { secondary: parsed.secondary } : {}),
+		});
+	};
+	addLimit("codex", undefined, root.rate_limit);
+	if (Array.isArray(root.additional_rate_limits)) {
+		for (const item of root.additional_rate_limits) {
+			if (!isRecord(item)) continue;
+			addLimit(stringValue(item.metered_feature) ?? "additional", stringValue(item.limit_name), item);
+		}
+	}
+	return { planType: stringValue(root.plan_type), limits, raw: payload };
+}
+
+export async function fetchCodexUsage(ctx: ExtensionContext): Promise<CodexUsageSnapshot> {
+	const model = ctx.model;
+	if (!model) throw new Error("No active model selected.");
+	if (model.provider !== "openai-codex") {
+		throw new Error("Codex usage is only available for OpenAI Codex subscription models.");
+	}
+	const response = await fetch(buildCodexUsageUrl(), { method: "GET", headers: await buildCodexUsageHeaders(ctx, model), signal: ctx.signal });
+	const text = await response.text();
+	if (!response.ok) throw new Error(`Usage request failed (${response.status}): ${text || response.statusText}`);
+	return parseCodexUsagePayload(JSON.parse(text));
+}
+
+function formatReset(timestampSeconds: number | undefined): string {
+	if (!timestampSeconds) return "reset unknown";
+	const ms = timestampSeconds * 1000;
+	const minutes = Math.max(0, Math.round((ms - Date.now()) / 60000));
+	return minutes < 90 ? `resets in ~${minutes}m` : `resets ${new Date(ms).toLocaleString()}`;
+}
+
+function formatWindow(label: string, window: CodexUsageWindow | undefined): string | undefined {
+	if (!window) return undefined;
+	const percent = window.usedPercent === undefined ? "?" : `${Math.round(window.usedPercent)}%`;
+	const span = window.windowMinutes ? `${Math.round(window.windowMinutes)}m` : "window";
+	return `${label}: ${percent} used (${span}, ${formatReset(window.resetsAt)})`;
+}
+
+export function formatCodexUsage(snapshot: CodexUsageSnapshot): string {
+	const lines = [`Codex usage${snapshot.planType ? ` (${snapshot.planType})` : ""}:`];
+	for (const limit of snapshot.limits) {
+		const title = limit.limitName ?? limit.limitId;
+		const parts = [formatWindow("5h", limit.primary), formatWindow("weekly", limit.secondary)].filter(Boolean);
+		lines.push(`- ${title}: ${parts.length ? parts.join("; ") : "no usage data"}`);
+	}
+	return lines.join("\n");
+}