@narumitw/pi-codex-usage 0.1.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+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,121 @@
+# 📊 pi-codex-usage — Codex Usage Status for Pi
+
+[![npm](https://img.shields.io/npm/v/@narumitw/pi-codex-usage)](https://www.npmjs.com/package/@narumitw/pi-codex-usage) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+`@narumitw/pi-codex-usage` is a native [Pi coding agent](https://pi.dev) extension that adds `/codex-status`, a command for showing ChatGPT Codex subscription usage from inside Pi.
+
+Use it when you want a quick Codex-style usage summary without leaving Pi or requiring Codex CLI to be installed.
+
+## ✨ Features
+
+- Adds a `/codex-status` command to Pi.
+- Shows Codex plan, 5-hour and weekly usage windows, reset times, and credits.
+- Displays additional usage buckets when the Codex backend returns them.
+- 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.
+- Caches results briefly to avoid repeatedly calling the backend.
+- Supports `--refresh` to bypass the in-memory cache.
+- Works as an independently installable npm Pi extension package.
+
+## 📦 Install
+
+```bash
+pi install npm:@narumitw/pi-codex-usage
+```
+
+Try without installing permanently:
+
+```bash
+pi -e npm:@narumitw/pi-codex-usage
+```
+
+Try this package locally from the repository root:
+
+```bash
+pi -e ./extensions/pi-codex-usage
+```
+
+## 🚀 Usage
+
+```text
+/codex-status
+/codex-status --refresh
+/codex-status --no-statusline
+/codex-status --clear-statusline
+/codex-status --timeout 30
+```
+
+Example output:
+
+```text
+  >_ OpenAI Codex Usage
+
+Visit https://chatgpt.com/codex/settings/usage for up-to-date
+information on rate limits and credits
+
+  5h limit:                    [█████████████░░░░░░░] 64% left (resets 13:57)
+  Weekly limit:                [████████████░░░░░░░░] 62% left (resets 14:37)
+  GPT-5.3-Codex-Spark limit:
+  5h limit:                    [████████████████████] 100% left (resets 19:16)
+  Weekly limit:                [████████████████████] 100% left (resets 00:10 on 21 May)
+```
+
+## 📊 Statusline behavior
+
+When the selected Pi model provider is `openai-codex`, `pi-codex-usage` refreshes a compact statusline item automatically:
+
+```text
+codex 59% 5h 61% wk
+```
+
+The statusline value uses the cached usage snapshot and refreshes every five minutes while the current model remains `openai-codex`. Switching away from an OpenAI Codex model clears the item.
+
+Use `/codex-status --no-statusline` for a one-off notification without updating the statusline, or `/codex-status --clear-statusline` to clear the item manually.
+
+## 🔐 Auth behavior
+
+`pi-codex-usage` tries usage sources in this order:
+
+1. Pi's `openai-codex` provider auth through the Pi extension API.
+2. Codex CLI app-server fallback when Pi auth cannot provide usable subscription auth.
+
+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 extension does not read Pi or Codex auth files directly, and it does not expose bearer tokens in error messages.
+
+## 🚧 Limitations
+
+- 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.
+
+## 🗂️ Package layout
+
+```txt
+extensions/pi-codex-usage/
+├── src/
+│   └── codex-usage.ts
+├── README.md
+├── LICENSE
+├── tsconfig.json
+└── package.json
+```
+
+The package exposes its Pi extension through `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/codex-usage.ts"]
+  }
+}
+```
+
+## 🔎 Keywords
+
+Pi extension, Pi coding agent, Codex usage, Codex status, ChatGPT subscription usage, rate limits, TypeScript Pi package, npm Pi extension.
+
+## 📄 License
+
+MIT. See [`LICENSE`](./LICENSE).

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@narumitw/pi-codex-usage",
+	"version": "0.1.12",
+	"description": "Pi extension that shows Codex ChatGPT subscription usage without requiring Codex CLI.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"codex",
+		"usage",
+		"status"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/codex-usage.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check . && npm run typecheck",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.14",
+		"@earendil-works/pi-coding-agent": "0.74.0",
+		"@types/node": "25.6.0",
+		"typescript": "6.0.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/narumiruna/pi-extensions",
+		"directory": "extensions/pi-codex-usage"
+	}
+}

package/src/codex-usage.ts

@@ -0,0 +1,993 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+const COMMAND_NAME = "codex-status";
+const CODEX_PROVIDER_ID = "openai-codex";
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const STATUS_KEY = "codex-usage";
+const USAGE_SETTINGS_URL = "https://chatgpt.com/codex/settings/usage";
+const BAR_SEGMENTS = 20;
+const LIMIT_VALUE_COLUMN = 29;
+const MAX_ERROR_BODY_CHARS = 600;
+const RESET_FOREGROUND = "\x1b[39m";
+
+type UsageSource = "pi-auth" | "codex-app-server";
+type PiModel = NonNullable<ExtensionContext["model"]>;
+
+type QueryUsageOptions = {
+	clearStatusline: boolean;
+	refresh: boolean;
+	statusline: boolean;
+	timeoutMs: number;
+};
+
+type CachedReport = {
+	createdAt: number;
+	report: CodexUsageReport;
+};
+
+type QueryUsageResult =
+	| { ok: true; report: CodexUsageReport }
+	| { ok: false; errors: UsageQueryError[] };
+
+type UsageQueryError = {
+	source: UsageSource;
+	message: string;
+	cause?: unknown;
+};
+
+export type CodexUsageReport = {
+	source: UsageSource;
+	capturedAt: number;
+	planType?: string;
+	snapshots: NormalizedRateLimitSnapshot[];
+};
+
+export type NormalizedRateLimitSnapshot = {
+	limitId: string;
+	limitName?: string;
+	primary?: NormalizedRateLimitWindow;
+	secondary?: NormalizedRateLimitWindow;
+	credits?: NormalizedCredits;
+};
+
+export type NormalizedRateLimitWindow = {
+	usedPercent: number;
+	windowMinutes?: number;
+	resetsAt?: number;
+};
+
+export type NormalizedCredits = {
+	hasCredits: boolean;
+	unlimited: boolean;
+	balance?: string;
+};
+
+type RateLimitStatusPayload = {
+	plan_type?: unknown;
+	rate_limit?: unknown;
+	additional_rate_limits?: unknown;
+	credits?: unknown;
+};
+
+type BackendRateLimitDetails = {
+	primary_window?: unknown;
+	secondary_window?: unknown;
+};
+
+type BackendWindowSnapshot = {
+	used_percent?: unknown;
+	limit_window_seconds?: unknown;
+	reset_at?: unknown;
+};
+
+type BackendAdditionalRateLimit = {
+	limit_name?: unknown;
+	metered_feature?: unknown;
+	rate_limit?: unknown;
+};
+
+type BackendCreditsSnapshot = {
+	has_credits?: unknown;
+	unlimited?: unknown;
+	balance?: unknown;
+};
+
+type AppServerRateLimitResponse = {
+	rateLimits?: unknown;
+	rateLimitsByLimitId?: unknown;
+};
+
+type AppServerRateLimitSnapshot = {
+	limitId?: unknown;
+	limitName?: unknown;
+	primary?: unknown;
+	secondary?: unknown;
+	credits?: unknown;
+	planType?: unknown;
+};
+
+type AppServerWindowSnapshot = {
+	usedPercent?: unknown;
+	windowDurationMins?: unknown;
+	resetsAt?: unknown;
+};
+
+type AppServerCreditsSnapshot = {
+	hasCredits?: unknown;
+	unlimited?: unknown;
+	balance?: unknown;
+};
+
+type RpcResponse = {
+	id?: unknown;
+	result?: unknown;
+	error?: { message?: unknown; code?: unknown };
+};
+
+type PendingRpc = {
+	resolve: (value: unknown) => void;
+	reject: (error: Error) => void;
+};
+
+export default function codexUsage(pi: ExtensionAPI) {
+	let cache: CachedReport | undefined;
+	let statuslineClearTimer: ReturnType<typeof setTimeout> | undefined;
+	let statuslineRefreshTimer: ReturnType<typeof setTimeout> | undefined;
+	let statuslineRequestId = 0;
+
+	const clearStatuslineTimers = () => {
+		if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
+		if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
+		statuslineClearTimer = undefined;
+		statuslineRefreshTimer = undefined;
+	};
+
+	const clearUsageStatusline = (ctx: ExtensionContext) => {
+		statuslineRequestId += 1;
+		clearStatuslineTimers();
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+	};
+
+	const scheduleTemporaryStatuslineClear = (ctx: ExtensionContext) => {
+		if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
+		statuslineClearTimer = setTimeout(() => {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			statuslineClearTimer = undefined;
+		}, CACHE_TTL_MS);
+		statuslineClearTimer.unref?.();
+	};
+
+	const scheduleStatuslineRefresh = (ctx: ExtensionContext) => {
+		if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
+		statuslineRefreshTimer = setTimeout(() => {
+			void refreshCurrentCodexUsageStatusline(ctx, true);
+		}, CACHE_TTL_MS);
+		statuslineRefreshTimer.unref?.();
+	};
+
+	const setUsageStatusline = (
+		ctx: ExtensionContext,
+		report: CodexUsageReport,
+		options: { autoRefresh: boolean },
+	) => {
+		if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
+		statuslineClearTimer = undefined;
+		ctx.ui.setStatus(STATUS_KEY, formatCodexUsageStatusline(report));
+		if (options.autoRefresh) scheduleStatuslineRefresh(ctx);
+		else scheduleTemporaryStatuslineClear(ctx);
+	};
+
+	const refreshCurrentCodexUsageStatusline = async (ctx: ExtensionContext, force: boolean) => {
+		if (!isOpenAICodexModel(ctx.model)) {
+			clearUsageStatusline(ctx);
+			return;
+		}
+
+		const requestId = statuslineRequestId + 1;
+		statuslineRequestId = requestId;
+		const cached = cache && Date.now() - cache.createdAt < CACHE_TTL_MS ? cache : undefined;
+		if (cached && !force) {
+			setUsageStatusline(ctx, cached.report, { autoRefresh: true });
+			return;
+		}
+
+		ctx.ui.setStatus(STATUS_KEY, "codex usage: checking");
+		const result = await queryUsage(ctx, { timeoutMs: DEFAULT_TIMEOUT_MS });
+		if (requestId !== statuslineRequestId) return;
+		if (!isOpenAICodexModel(ctx.model)) {
+			clearUsageStatusline(ctx);
+			return;
+		}
+
+		if (!result.ok) {
+			ctx.ui.setStatus(STATUS_KEY, "codex usage error");
+			scheduleStatuslineRefresh(ctx);
+			return;
+		}
+
+		cache = { createdAt: Date.now(), report: result.report };
+		setUsageStatusline(ctx, result.report, { autoRefresh: true });
+	};
+
+	pi.registerCommand(COMMAND_NAME, {
+		description: "Show Codex ChatGPT subscription usage and rate-limit windows",
+		handler: async (args, ctx) => {
+			const options = parseArgs(args);
+			if (!options.ok) {
+				ctx.ui.notify(options.error, "warning");
+				return;
+			}
+
+			if (options.value.clearStatusline) {
+				clearUsageStatusline(ctx);
+				ctx.ui.notify("Codex usage statusline cleared.", "info");
+				return;
+			}
+
+			const cached = cache && Date.now() - cache.createdAt < CACHE_TTL_MS ? cache : undefined;
+			if (cached && !options.value.refresh) {
+				if (options.value.statusline) {
+					setUsageStatusline(ctx, cached.report, { autoRefresh: isOpenAICodexModel(ctx.model) });
+				}
+				showReport(ctx, cached.report, true);
+				return;
+			}
+
+			let keepStatusline = false;
+			if (options.value.statusline) ctx.ui.setStatus(STATUS_KEY, "codex usage: checking");
+			try {
+				const result = await queryUsage(ctx, options.value);
+				if (!result.ok) {
+					ctx.ui.notify(formatQueryErrors(result.errors), "error");
+					return;
+				}
+
+				cache = { createdAt: Date.now(), report: result.report };
+				if (options.value.statusline) {
+					setUsageStatusline(ctx, result.report, { autoRefresh: isOpenAICodexModel(ctx.model) });
+					keepStatusline = true;
+				}
+				showReport(ctx, result.report, false);
+			} finally {
+				if (options.value.statusline && !keepStatusline) ctx.ui.setStatus(STATUS_KEY, undefined);
+			}
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		if (isOpenAICodexModel(ctx.model)) void refreshCurrentCodexUsageStatusline(ctx, false);
+		else clearUsageStatusline(ctx);
+	});
+
+	pi.on("session_tree", (_event, ctx) => {
+		if (isOpenAICodexModel(ctx.model)) void refreshCurrentCodexUsageStatusline(ctx, false);
+		else clearUsageStatusline(ctx);
+	});
+
+	pi.on("model_select", (event, ctx) => {
+		if (isOpenAICodexModel(event.model)) void refreshCurrentCodexUsageStatusline(ctx, false);
+		else clearUsageStatusline(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => clearUsageStatusline(ctx));
+}
+
+function parseArgs(
+	args: string,
+): { ok: true; value: QueryUsageOptions } | { ok: false; error: string } {
+	const tokens = args.trim().split(/\s+/).filter(Boolean);
+	let clearStatusline = false;
+	let refresh = false;
+	let statusline = true;
+	let timeoutMs = DEFAULT_TIMEOUT_MS;
+
+	for (let index = 0; index < tokens.length; index++) {
+		const token = tokens[index];
+		if (token === "--clear-statusline") {
+			clearStatusline = true;
+			continue;
+		}
+		if (token === "--no-statusline") {
+			statusline = false;
+			continue;
+		}
+		if (token === "--refresh") {
+			refresh = true;
+			continue;
+		}
+		if (token === "--timeout") {
+			const rawValue = tokens[index + 1];
+			if (!rawValue)
+				return { ok: false, error: "Usage: /codex-status [--refresh] [--timeout seconds]" };
+			const parsed = Number(rawValue);
+			if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 120) {
+				return { ok: false, error: "--timeout must be a number of seconds between 1 and 120." };
+			}
+			timeoutMs = Math.round(parsed * 1000);
+			index += 1;
+			continue;
+		}
+		return {
+			ok: false,
+			error: `Unknown option: ${token}. Usage: /codex-status [--refresh] [--no-statusline] [--clear-statusline] [--timeout seconds]`,
+		};
+	}
+
+	return { ok: true, value: { clearStatusline, refresh, statusline, timeoutMs } };
+}
+
+function isOpenAICodexModel(model: ExtensionContext["model"]): boolean {
+	return model?.provider === CODEX_PROVIDER_ID;
+}
+
+async function queryUsage(
+	ctx: ExtensionContext,
+	options: Pick<QueryUsageOptions, "timeoutMs">,
+): Promise<QueryUsageResult> {
+	const errors: UsageQueryError[] = [];
+
+	try {
+		const report = await queryViaPiAuth(ctx, options.timeoutMs);
+		return { ok: true, report };
+	} catch (cause) {
+		errors.push({ source: "pi-auth", message: errorMessage(cause), cause });
+	}
+
+	try {
+		const report = await queryViaCodexAppServer(options.timeoutMs);
+		return { ok: true, report };
+	} catch (cause) {
+		errors.push({ source: "codex-app-server", message: errorMessage(cause), cause });
+	}
+
+	return { ok: false, errors };
+}
+
+async function queryViaPiAuth(
+	ctx: ExtensionContext,
+	timeoutMs: number,
+): Promise<CodexUsageReport> {
+	const auth = await resolvePiCodexAuth(ctx);
+	if (!auth) {
+		throw new Error(
+			"No Pi OpenAI Codex subscription auth was available. Use a Pi OpenAI Codex model or run /login for OpenAI ChatGPT Plus/Pro (Codex).",
+		);
+	}
+
+	const response = await fetchWithTimeout(CODEX_USAGE_URL, { headers: auth.headers }, timeoutMs);
+	const text = await response.text();
+	if (!response.ok) {
+		throw new Error(
+			`Codex usage endpoint returned ${response.status} ${response.statusText}: ${redactErrorBody(text)}`,
+		);
+	}
+
+	const payload = parseJsonObject(text, "Codex usage endpoint response");
+	return normalizeBackendPayload(payload as RateLimitStatusPayload, Date.now(), "pi-auth");
+}
+
+async function resolvePiCodexAuth(
+	ctx: ExtensionContext,
+): Promise<{ headers: Record<string, string> } | undefined> {
+	const models = codexAuthCandidateModels(ctx);
+	const errors: string[] = [];
+
+	for (const model of models) {
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) {
+			errors.push(auth.error);
+			continue;
+		}
+
+		const headers = { ...(auth.headers ?? {}) };
+		if (!hasHeader(headers, "Authorization") && auth.apiKey) {
+			headers.Authorization = `Bearer ${auth.apiKey}`;
+		}
+		if (!hasHeader(headers, "User-Agent")) {
+			headers["User-Agent"] = "pi-codex-usage";
+		}
+		if (hasHeader(headers, "Authorization")) {
+			return { headers };
+		}
+	}
+
+	if (errors.length > 0) {
+		throw new Error(errors.join("; "));
+	}
+	return undefined;
+}
+
+function codexAuthCandidateModels(ctx: ExtensionContext): PiModel[] {
+	const candidates: PiModel[] = [];
+	const seen = new Set<string>();
+	const add = (model: PiModel | undefined) => {
+		if (!model || model.provider !== CODEX_PROVIDER_ID) return;
+		const key = `${model.provider}/${model.id}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		candidates.push(model);
+	};
+
+	add(ctx.model);
+	for (const model of ctx.modelRegistry.getAvailable()) add(model);
+	for (const model of ctx.modelRegistry.getAll()) add(model);
+	return candidates;
+}
+
+async function fetchWithTimeout(
+	url: string,
+	init: RequestInit,
+	timeoutMs: number,
+): Promise<Response> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetch(url, { ...init, signal: controller.signal });
+	} catch (error) {
+		if (controller.signal.aborted) {
+			throw new Error(
+				`Timed out after ${Math.round(timeoutMs / 1000)}s while fetching Codex usage.`,
+			);
+		}
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+async function queryViaCodexAppServer(timeoutMs: number): Promise<CodexUsageReport> {
+	const client = new CodexAppServerClient(timeoutMs);
+	try {
+		await client.start();
+		await client.request("initialize", {
+			clientInfo: {
+				name: "pi_codex_usage",
+				title: "Pi Codex Usage",
+				version: "0.1.0",
+			},
+			capabilities: {
+				experimentalApi: false,
+				requestAttestation: false,
+				optOutNotificationMethods: [],
+			},
+		});
+		client.notify("initialized");
+		const result = await client.request("account/rateLimits/read", undefined);
+		return normalizeAppServerResponse(
+			assertObject(result, "account/rateLimits/read result") as AppServerRateLimitResponse,
+			Date.now(),
+		);
+	} finally {
+		client.dispose();
+	}
+}
+
+class CodexAppServerClient {
+	private child?: ChildProcessWithoutNullStreams;
+	private nextId = 1;
+	private stderr = "";
+	private readonly pending = new Map<number, PendingRpc>();
+	private startPromise?: Promise<void>;
+	private exitError?: Error;
+	private readonly timeoutMs: number;
+
+	constructor(timeoutMs: number) {
+		this.timeoutMs = timeoutMs;
+	}
+
+	start(): Promise<void> {
+		if (this.startPromise) return this.startPromise;
+
+		this.startPromise = new Promise((resolve, reject) => {
+			const child = spawn("codex", ["app-server", "--listen", "stdio://"], {
+				stdio: ["pipe", "pipe", "pipe"],
+			});
+			this.child = child;
+
+			const startupTimeout = setTimeout(() => {
+				reject(
+					new Error(
+						`Timed out after ${Math.round(this.timeoutMs / 1000)}s starting codex app-server.`,
+					),
+				);
+			}, this.timeoutMs);
+
+			child.once("spawn", () => {
+				clearTimeout(startupTimeout);
+				resolve();
+			});
+
+			child.once("error", (error) => {
+				clearTimeout(startupTimeout);
+				reject(new Error(`Failed to start codex app-server: ${error.message}`));
+				this.rejectAll(error);
+			});
+
+			child.once("exit", (code, signal) => {
+				const suffix = this.stderr ? ` stderr: ${redactErrorBody(this.stderr)}` : "";
+				this.exitError = new Error(
+					`codex app-server exited before completing the request (code ${code ?? "unknown"}, signal ${signal ?? "none"}).${suffix}`,
+				);
+				this.rejectAll(this.exitError);
+			});
+
+			child.stderr.setEncoding("utf8");
+			child.stderr.on("data", (chunk: string) => {
+				this.stderr = truncateEnd(this.stderr + chunk, MAX_ERROR_BODY_CHARS);
+			});
+
+			const lines = createInterface({ input: child.stdout });
+			lines.on("line", (line) => this.handleLine(line));
+		});
+
+		return this.startPromise;
+	}
+
+	request(method: string, params: unknown): Promise<unknown> {
+		const child = this.child;
+		if (!child?.stdin.writable) {
+			throw new Error("codex app-server is not running.");
+		}
+		if (this.exitError) throw this.exitError;
+
+		const id = this.nextId++;
+		const payload = params === undefined ? { method, id } : { method, id, params };
+		const response = new Promise<unknown>((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				this.pending.delete(id);
+				reject(
+					new Error(`Timed out after ${Math.round(this.timeoutMs / 1000)}s waiting for ${method}.`),
+				);
+			}, this.timeoutMs);
+
+			this.pending.set(id, {
+				resolve: (value) => {
+					clearTimeout(timeout);
+					resolve(value);
+				},
+				reject: (error) => {
+					clearTimeout(timeout);
+					reject(error);
+				},
+			});
+		});
+
+		child.stdin.write(`${JSON.stringify(payload)}\n`);
+		return response;
+	}
+
+	notify(method: string): void {
+		const child = this.child;
+		if (!child?.stdin.writable) return;
+		child.stdin.write(`${JSON.stringify({ method })}\n`);
+	}
+
+	dispose(): void {
+		for (const [id, pending] of this.pending) {
+			pending.reject(new Error(`codex app-server request ${id} cancelled.`));
+		}
+		this.pending.clear();
+
+		const child = this.child;
+		if (!child) return;
+		child.stdin.end();
+		if (!child.killed) child.kill();
+		this.child = undefined;
+	}
+
+	private handleLine(line: string): void {
+		let parsed: RpcResponse;
+		try {
+			parsed = JSON.parse(line) as RpcResponse;
+		} catch {
+			return;
+		}
+
+		if (typeof parsed.id !== "number") return;
+		const pending = this.pending.get(parsed.id);
+		if (!pending) return;
+		this.pending.delete(parsed.id);
+
+		if (parsed.error) {
+			const message =
+				typeof parsed.error.message === "string" ? parsed.error.message : "unknown error";
+			pending.reject(new Error(`codex app-server request failed: ${message}`));
+			return;
+		}
+
+		pending.resolve(parsed.result);
+	}
+
+	private rejectAll(error: Error): void {
+		for (const pending of this.pending.values()) pending.reject(error);
+		this.pending.clear();
+	}
+}
+
+export function normalizeBackendPayload(
+	payload: RateLimitStatusPayload,
+	capturedAt: number,
+	source: UsageSource,
+): CodexUsageReport {
+	const snapshots: NormalizedRateLimitSnapshot[] = [];
+	const planType = asString(payload.plan_type);
+	const primary = normalizeBackendSnapshot("codex", undefined, payload.rate_limit, payload.credits);
+	if (primary) snapshots.push(primary);
+
+	const additional = Array.isArray(payload.additional_rate_limits)
+		? payload.additional_rate_limits
+		: [];
+	for (const item of additional) {
+		const additionalLimit = assertObject(
+			item,
+			"additional rate limit",
+		) as BackendAdditionalRateLimit;
+		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);
+	}
+
+	if (snapshots.length === 0) {
+		throw new Error("Codex usage endpoint returned no displayable rate-limit windows.");
+	}
+
+	return { source, capturedAt, planType, snapshots };
+}
+
+function normalizeBackendSnapshot(
+	limitId: string,
+	limitName: string | undefined,
+	rateLimit: unknown,
+	credits: unknown,
+): NormalizedRateLimitSnapshot | undefined {
+	if (rateLimit === null || rateLimit === undefined) {
+		const normalizedCredits = normalizeBackendCredits(credits);
+		return normalizedCredits ? { limitId, limitName, credits: normalizedCredits } : undefined;
+	}
+
+	const details = assertObject(rateLimit, "rate limit") as BackendRateLimitDetails;
+	const primary = normalizeBackendWindow(details.primary_window);
+	const secondary = normalizeBackendWindow(details.secondary_window);
+	const normalizedCredits = normalizeBackendCredits(credits);
+
+	if (!primary && !secondary && !normalizedCredits) return undefined;
+	return { limitId, limitName, primary, secondary, credits: normalizedCredits };
+}
+
+function normalizeBackendWindow(value: unknown): NormalizedRateLimitWindow | undefined {
+	if (value === null || value === undefined) return undefined;
+	const window = assertObject(value, "rate-limit window") as BackendWindowSnapshot;
+	const usedPercent = asNumber(window.used_percent);
+	if (usedPercent === undefined) return undefined;
+	const limitSeconds = asNumber(window.limit_window_seconds);
+	const resetsAt = asNumber(window.reset_at);
+	return {
+		usedPercent,
+		windowMinutes: limitSeconds && limitSeconds > 0 ? Math.ceil(limitSeconds / 60) : undefined,
+		resetsAt,
+	};
+}
+
+function normalizeBackendCredits(value: unknown): NormalizedCredits | undefined {
+	if (value === null || value === undefined) return undefined;
+	const credits = assertObject(value, "credits") as BackendCreditsSnapshot;
+	const hasCredits = asBoolean(credits.has_credits);
+	const unlimited = asBoolean(credits.unlimited);
+	if (hasCredits === undefined || unlimited === undefined) return undefined;
+	return { hasCredits, unlimited, balance: asString(credits.balance) };
+}
+
+export function normalizeAppServerResponse(
+	response: AppServerRateLimitResponse,
+	capturedAt: number,
+): CodexUsageReport {
+	const snapshots: NormalizedRateLimitSnapshot[] = [];
+	const addSnapshot = (raw: unknown, fallbackId: string) => {
+		const snapshot = normalizeAppServerSnapshot(raw, fallbackId);
+		if (!snapshot) return;
+		const existingIndex = snapshots.findIndex((item) => item.limitId === snapshot.limitId);
+		if (existingIndex >= 0)
+			snapshots[existingIndex] = mergeSnapshot(snapshots[existingIndex], snapshot);
+		else snapshots.push(snapshot);
+	};
+
+	addSnapshot(response.rateLimits, "codex");
+	if (response.rateLimitsByLimitId && typeof response.rateLimitsByLimitId === "object") {
+		for (const [limitId, raw] of Object.entries(response.rateLimitsByLimitId)) {
+			addSnapshot(raw, limitId);
+		}
+	}
+
+	if (snapshots.length === 0) {
+		throw new Error("codex app-server returned no displayable rate-limit windows.");
+	}
+
+	const planType = asAppServerPlanType(response.rateLimits);
+	return { source: "codex-app-server", capturedAt, planType, snapshots };
+}
+
+function asAppServerPlanType(raw: unknown): string | undefined {
+	if (raw === null || raw === undefined) return undefined;
+	const snapshot = assertObject(
+		raw,
+		"app-server rate-limit snapshot",
+	) as AppServerRateLimitSnapshot;
+	return asString(snapshot.planType);
+}
+
+function normalizeAppServerSnapshot(
+	raw: unknown,
+	fallbackId: string,
+): NormalizedRateLimitSnapshot | undefined {
+	if (raw === null || raw === undefined) return undefined;
+	const snapshot = assertObject(
+		raw,
+		"app-server rate-limit snapshot",
+	) as AppServerRateLimitSnapshot;
+	const limitId = asString(snapshot.limitId) ?? fallbackId;
+	const limitName = asString(snapshot.limitName);
+	const primary = normalizeAppServerWindow(snapshot.primary);
+	const secondary = normalizeAppServerWindow(snapshot.secondary);
+	const credits = normalizeAppServerCredits(snapshot.credits);
+	if (!primary && !secondary && !credits) return undefined;
+	return { limitId, limitName, primary, secondary, credits };
+}
+
+function normalizeAppServerWindow(value: unknown): NormalizedRateLimitWindow | undefined {
+	if (value === null || value === undefined) return undefined;
+	const window = assertObject(value, "app-server rate-limit window") as AppServerWindowSnapshot;
+	const usedPercent = asNumber(window.usedPercent);
+	if (usedPercent === undefined) return undefined;
+	return {
+		usedPercent,
+		windowMinutes: asNumber(window.windowDurationMins),
+		resetsAt: asNumber(window.resetsAt),
+	};
+}
+
+function normalizeAppServerCredits(value: unknown): NormalizedCredits | undefined {
+	if (value === null || value === undefined) return undefined;
+	const credits = assertObject(value, "app-server credits") as AppServerCreditsSnapshot;
+	const hasCredits = asBoolean(credits.hasCredits);
+	const unlimited = asBoolean(credits.unlimited);
+	if (hasCredits === undefined || unlimited === undefined) return undefined;
+	return { hasCredits, unlimited, balance: asString(credits.balance) };
+}
+
+function mergeSnapshot(
+	left: NormalizedRateLimitSnapshot,
+	right: NormalizedRateLimitSnapshot,
+): NormalizedRateLimitSnapshot {
+	return {
+		limitId: right.limitId || left.limitId,
+		limitName: right.limitName ?? left.limitName,
+		primary: right.primary ?? left.primary,
+		secondary: right.secondary ?? left.secondary,
+		credits: right.credits ?? left.credits,
+	};
+}
+
+export function formatCodexUsageReport(report: CodexUsageReport, _cacheAgeMs?: number): string {
+	const lines = [
+		"  >_ OpenAI Codex Usage",
+		"",
+		`Visit ${USAGE_SETTINGS_URL} for up-to-date`,
+		"information on rate limits and credits",
+		"",
+	];
+
+	for (const snapshot of report.snapshots) {
+		const label = snapshot.limitName ?? snapshot.limitId;
+		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 && !snapshot.secondary) {
+			lines.push("  Limits unavailable for this account");
+		}
+	}
+
+	return lines.join("\n");
+}
+
+export function formatCodexUsageStatusline(report: CodexUsageReport): string {
+	const snapshot =
+		report.snapshots.find((item) => item.limitId.toLowerCase() === "codex") ??
+		report.snapshots[0];
+	if (!snapshot) return "codex usage unavailable";
+
+	const parts = ["codex"];
+	if (snapshot.primary) parts.push(`${formatRemainingPercent(snapshot.primary)} 5h`);
+	if (snapshot.secondary) parts.push(`${formatRemainingPercent(snapshot.secondary)} wk`);
+	if (parts.length === 1 && snapshot.credits) parts.push(formatCredits(snapshot.credits));
+	return parts.join(" ");
+}
+
+function formatRemainingPercent(window: NormalizedRateLimitWindow): string {
+	return `${(100 - clampPercent(window.usedPercent)).toFixed(0)}%`;
+}
+
+function showReport(
+	ctx: ExtensionCommandContext,
+	report: CodexUsageReport,
+	fromCache: boolean,
+): void {
+	const text = formatCodexUsageReport(
+		report,
+		fromCache ? Date.now() - report.capturedAt : undefined,
+	);
+	ctx.ui.notify(ctx.hasUI ? brightenInfoNotification(text) : text, "info");
+}
+
+function brightenInfoNotification(text: string): string {
+	return `${RESET_FOREGROUND}${text}`;
+}
+
+function isPrimaryCodexSnapshot(snapshot: NormalizedRateLimitSnapshot): boolean {
+	return snapshot.limitId.toLowerCase() === "codex";
+}
+
+function formatWindowLine(label: string, window: NormalizedRateLimitWindow): string {
+	return `  ${label.padEnd(LIMIT_VALUE_COLUMN)}${formatWindow(window)}`;
+}
+
+function formatWindow(window: NormalizedRateLimitWindow): string {
+	const remaining = 100 - clampPercent(window.usedPercent);
+	const reset = window.resetsAt ? ` (resets ${formatReset(window.resetsAt)})` : "";
+	return `${progressBar(remaining)} ${remaining.toFixed(0)}% left${reset}`;
+}
+
+function progressBar(percentRemaining: number): string {
+	const filled = Math.round((clampPercent(percentRemaining) / 100) * BAR_SEGMENTS);
+	return `[${"█".repeat(filled)}${"░".repeat(BAR_SEGMENTS - filled)}]`;
+}
+
+function formatCredits(credits: NormalizedCredits): string {
+	if (!credits.hasCredits) return "no credits";
+	if (credits.unlimited) return "unlimited credits";
+	const balance = credits.balance?.trim();
+	if (!balance) return "credits available";
+	return `${formatNumber(Number(balance), balance)} credits`;
+}
+
+function formatReset(epochSeconds: number): string {
+	const reset = new Date(epochSeconds * 1000);
+	if (Number.isNaN(reset.getTime())) return "at an unknown time";
+
+	const now = new Date();
+	const time = `${reset.getHours().toString().padStart(2, "0")}:${reset
+		.getMinutes()
+		.toString()
+		.padStart(2, "0")}`;
+	if (reset.toDateString() === now.toDateString()) return time;
+	const day = reset.getDate().toString();
+	const month = reset.toLocaleDateString(undefined, { month: "short" });
+	return `${time} on ${day} ${month}`;
+}
+
+function formatQueryErrors(errors: UsageQueryError[]): string {
+	const lines = ["Unable to read Codex usage."];
+	for (const error of errors) {
+		const source = error.source === "pi-auth" ? "Pi auth direct" : "Codex app-server fallback";
+		lines.push(`- ${source}: ${error.message}`);
+	}
+	lines.push("");
+	lines.push(
+		"Tip: use a Pi OpenAI Codex model or run /login for OpenAI ChatGPT Plus/Pro. If Pi auth is unavailable, install Codex CLI and run codex login for the fallback.",
+	);
+	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);
+}
+
+function clampPercent(value: number): number {
+	if (!Number.isFinite(value)) return 0;
+	return Math.min(100, Math.max(0, value));
+}
+
+function parseJsonObject(text: string, description: string): Record<string, unknown> {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text) as unknown;
+	} catch (error) {
+		throw new Error(`${description} was not valid JSON: ${errorMessage(error)}`);
+	}
+	return assertObject(parsed, description);
+}
+
+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.`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim()) {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : undefined;
+	}
+	return undefined;
+}
+
+function asBoolean(value: unknown): boolean | undefined {
+	return typeof value === "boolean" ? value : undefined;
+}
+
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+	return Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());
+}
+
+function redactErrorBody(body: string): string {
+	return truncateEnd(
+		body
+			.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer <redacted>")
+			.replace(/"access_token"\s*:\s*"[^"]+"/gi, '"access_token":"<redacted>"')
+			.trim(),
+		MAX_ERROR_BODY_CHARS,
+	);
+}
+
+function truncateEnd(value: string, maxChars: number): string {
+	if (value.length <= maxChars) return value;
+	return `${value.slice(0, maxChars - 1)}…`;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}