@llblab/pi-codex-usage 0.3.3

package/AGENTS.md

@@ -0,0 +1,13 @@
+# Agent Notes
+
+- `Statusline-only scope`: Keep this extension zero-configuration and statusline-only.
+  - Trigger: Considering commands, menus, persisted settings, or notification output.
+  - Action: Prefer deleting the surface unless it is required for the optimistic status widget.
+
+- `Optimistic refresh`: Preserve the last good statusline bar during refresh and transient failures.
+  - Trigger: Updating quota polling or error handling.
+  - Action: Do not collapse the bar while a request is in flight; only show `n/a` or `error` after repeated failures or no usable quota.
+
+- `Compact dual bar`: Encode the 5-hour and weekly quota windows in the five-character separated-sextant bar.
+  - Trigger: Changing statusline formatting.
+  - Action: Keep a fixed-width `[xxxxx]` bar where top sextants represent the 5-hour window and bottom sextants represent the weekly window.

package/BACKLOG.md

@@ -0,0 +1,4 @@
+# Backlog
+
+- [ ] `Runtime smoke test` Verify the extension inside a live Pi session against real Codex auth states: usable subscription, missing auth, missing subscription, and transient network failure.
+- [ ] `Statusline polish` Tune the successful-refresh blink duration if the current 150ms redraw feels too visible or too subtle in the Pi footer.

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+- `Fork baseline` Imported `extensions/pi-codex-usage` from `narumiruna/pi-extensions` as a standalone `@llblab/pi-codex-usage` package. Impact: the extension can be installed and maintained independently.
+- `Minimal statusline` Removed command-driven report output and narrowed the extension to a zero-configuration statusline widget. Impact: runtime behavior is automatic while `openai-codex` is active.
+- `Primary quota focus` Ignored additional returned buckets such as Spark-specific limits. Impact: the statusline only represents primary Codex 5-hour and weekly quota windows.
+- `Dual quota bar` Replaced textual percentages with a fixed-width separated-sextant bar. Impact: both 5-hour and weekly remaining quota are encoded in five statusline characters.
+- `Optimistic refresh` Kept the last good bar during refresh and transient failures, with a short successful-redraw blink. Impact: the footer no longer shifts or collapses during polling.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+Copyright (c) 2026 llblab
+
+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,72 @@
+# pi-codex-usage
+
+Minimal zero-configuration Pi extension for showing primary ChatGPT Codex usage limits in the statusline.
+
+This repository is a minimal fork of [`narumiruna/pi-extensions/extensions/pi-codex-usage`](https://github.com/narumiruna/pi-extensions/tree/main/extensions/pi-codex-usage). It keeps the auth and quota-fetching path, but intentionally narrows the interface to the primary Codex 5-hour and weekly windows.
+
+## Start Here
+
+- [Agent Notes](./AGENTS.md)
+- [Backlog](./BACKLOG.md)
+- [Changelog](./CHANGELOG.md)
+
+## Features
+
+- Shows an empty statusline bar immediately, then refreshes every 30 seconds while the active Pi model uses `openai-codex`
+- Statusline output stays compact, with the `codex` label accented and the values muted
+- Additional returned buckets, including Spark-specific limits, are ignored
+- Pi OpenAI Codex provider auth is used first
+- Codex CLI app-server remains available as a fallback
+- Missing auth, subscription, plan, or quota windows are shown as `n/a`, not as an error
+- Successful updates briefly redraw the bar without changing its width
+- Network/provider failures keep the last good bar briefly, then show `error`
+- No commands or configuration are required
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:@llblab/pi-codex-usage
+```
+
+From git:
+
+```bash
+pi install git:github.com/llblab/pi-codex-usage
+```
+
+## Statusline
+
+Normal usage:
+
+```text
+codex [𜺃𜺃𜹣𜹓𜹓]
+```
+
+The five-character bar encodes two ten-step limits at once: the top sextants are the 5-hour limit, and the bottom sextants are the weekly limit.
+
+Unavailable because Codex auth or subscription quota is not available:
+
+```text
+codex n/a
+```
+
+Runtime failure, such as a network or provider error:
+
+```text
+codex error
+```
+
+## Auth
+
+The extension tries usage sources in this order:
+
+1. Pi's `openai-codex` provider auth
+2. `codex app-server --listen stdio://`
+
+OpenAI API keys are not ChatGPT Codex subscription auth and do not expose these quotas.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/index.ts

@@ -0,0 +1,846 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const CODEX_PROVIDER_ID = "openai-codex";
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const REFRESH_INTERVAL_MS = 30 * 1000;
+const REDRAW_BLINK_MS = 150;
+const STATUS_KEY = "codex-usage";
+const MAX_ERROR_BODY_CHARS = 600;
+const STATUS_LABEL_TEXT = "codex";
+const DUAL_BAR_CHARS = [
+	" ",
+	"𜹑",
+	"𜹒",
+	"𜹓",
+	"𜹠",
+	"𜹡",
+	"𜹢",
+	"𜹣",
+	"𜹰",
+	"𜹱",
+	"𜹲",
+	"𜹳",
+	"𜺀",
+	"𜺁",
+	"𜺂",
+	"𜺃",
+];
+
+type UsageSource = "pi-auth" | "codex-app-server";
+type TimeoutHandle = ReturnType<typeof setTimeout> & { unref?: () => void };
+type PiModel = NonNullable<ExtensionContext["model"]>;
+export type CodexUsageModel = Pick<PiModel, "id" | "name" | "provider">;
+
+type QueryUsageOptions = {
+	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 = {
+	snapshots: NormalizedRateLimitSnapshot[];
+};
+
+export type NormalizedRateLimitSnapshot = {
+	limitId: string;
+	primary?: NormalizedRateLimitWindow;
+	secondary?: NormalizedRateLimitWindow;
+};
+
+export type NormalizedRateLimitWindow = {
+	usedPercent: number;
+};
+
+type RateLimitStatusPayload = {
+	rate_limit?: unknown;
+};
+
+type BackendRateLimitDetails = {
+	primary_window?: unknown;
+	secondary_window?: unknown;
+};
+
+type BackendWindowSnapshot = {
+	used_percent?: unknown;
+};
+
+type AppServerRateLimitResponse = {
+	rateLimits?: unknown;
+};
+
+type AppServerRateLimitSnapshot = {
+	limitId?: unknown;
+	primary?: unknown;
+	secondary?: unknown;
+};
+
+type AppServerWindowSnapshot = {
+	usedPercent?: 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 failedRefreshes = 0;
+	let statuslineBlinkTimer: TimeoutHandle | undefined;
+	let statuslineClearTimer: TimeoutHandle | undefined;
+	let statuslineRefreshTimer: TimeoutHandle | undefined;
+	let statuslineRequestId = 0;
+
+	const clearStatuslineTimers = () => {
+		if (statuslineBlinkTimer) clearTimeout(statuslineBlinkTimer);
+		if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
+		if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
+		statuslineBlinkTimer = undefined;
+		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;
+		}, REFRESH_INTERVAL_MS) as TimeoutHandle;
+		statuslineClearTimer.unref?.();
+	};
+
+	const scheduleStatuslineRefresh = (ctx: ExtensionContext) => {
+		if (statuslineRefreshTimer) clearTimeout(statuslineRefreshTimer);
+		statuslineRefreshTimer = setTimeout(() => {
+			void refreshCurrentCodexUsageStatusline(ctx, true);
+		}, REFRESH_INTERVAL_MS) as TimeoutHandle;
+		statuslineRefreshTimer.unref?.();
+	};
+
+	const setUsageStatusline = (
+		ctx: ExtensionContext,
+		report: CodexUsageReport,
+		options: {
+			autoRefresh: boolean;
+			blink: boolean;
+			model: CodexUsageModel | undefined;
+		},
+	) => {
+		if (statuslineBlinkTimer) clearTimeout(statuslineBlinkTimer);
+		if (statuslineClearTimer) clearTimeout(statuslineClearTimer);
+		statuslineBlinkTimer = undefined;
+		statuslineClearTimer = undefined;
+		const text = formatCodexUsageStatusline(report, ctx, options.model);
+		if (options.blink) {
+			ctx.ui.setStatus(STATUS_KEY, formatEmptyStatuslineBar(ctx));
+			statuslineBlinkTimer = setTimeout(() => {
+				ctx.ui.setStatus(STATUS_KEY, text);
+				statuslineBlinkTimer = undefined;
+			}, REDRAW_BLINK_MS) as TimeoutHandle;
+			statuslineBlinkTimer.unref?.();
+		} else {
+			ctx.ui.setStatus(STATUS_KEY, text);
+		}
+		if (options.autoRefresh) scheduleStatuslineRefresh(ctx);
+		else scheduleTemporaryStatuslineClear(ctx);
+	};
+
+	const refreshCurrentCodexUsageStatusline = async (
+		ctx: ExtensionContext,
+		force: boolean,
+		model = ctx.model,
+	) => {
+		if (!isOpenAICodexModel(model)) {
+			clearUsageStatusline(ctx);
+			return;
+		}
+
+		if (!cache) ctx.ui.setStatus(STATUS_KEY, formatEmptyStatuslineBar(ctx));
+		const requestId = statuslineRequestId + 1;
+		statuslineRequestId = requestId;
+		const cached =
+			cache && Date.now() - cache.createdAt < REFRESH_INTERVAL_MS
+				? cache
+				: undefined;
+		if (cached && !force) {
+			setUsageStatusline(ctx, cached.report, {
+				autoRefresh: true,
+				blink: false,
+				model,
+			});
+			return;
+		}
+
+		const result = await queryUsage(ctx, { timeoutMs: DEFAULT_TIMEOUT_MS });
+		if (requestId !== statuslineRequestId) return;
+		if (!isOpenAICodexModel(ctx.model)) {
+			clearUsageStatusline(ctx);
+			return;
+		}
+
+		if (!result.ok) {
+			failedRefreshes += 1;
+			if (!cache || failedRefreshes >= 5) {
+				ctx.ui.setStatus(STATUS_KEY, formatStatuslineProblem(ctx, result.errors));
+			}
+			scheduleStatuslineRefresh(ctx);
+			return;
+		}
+
+		failedRefreshes = 0;
+		cache = { createdAt: Date.now(), report: result.report };
+		setUsageStatusline(ctx, result.report, {
+			autoRefresh: true,
+			blink: cache !== undefined,
+			model,
+		});
+	};
+
+	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, event.model);
+		} else {
+			clearUsageStatusline(ctx);
+		}
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => clearUsageStatusline(ctx));
+}
+
+function isOpenAICodexModel(
+	model: Pick<PiModel, "provider"> | undefined,
+): 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 snapshot = normalizeBackendSnapshot("codex", payload.rate_limit);
+	if (!snapshot) {
+		throw new Error(
+			"Codex usage endpoint returned no displayable rate-limit windows.",
+		);
+	}
+	return { snapshots: [snapshot] };
+}
+
+function normalizeBackendSnapshot(
+	limitId: string,
+	rateLimit: unknown,
+): NormalizedRateLimitSnapshot | undefined {
+	if (rateLimit === null || rateLimit === undefined) return undefined;
+	const details = assertObject(
+		rateLimit,
+		"rate limit",
+	) as BackendRateLimitDetails;
+	const primary = normalizeBackendWindow(details.primary_window);
+	const secondary = normalizeBackendWindow(details.secondary_window);
+	if (!primary && !secondary) return undefined;
+	return { limitId, primary, secondary };
+}
+
+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;
+	return { usedPercent };
+}
+
+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 (snapshots.length === 0) {
+		throw new Error(
+			"codex app-server returned no displayable rate-limit windows.",
+		);
+	}
+
+	return { snapshots };
+}
+
+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 primary = normalizeAppServerWindow(snapshot.primary);
+	const secondary = normalizeAppServerWindow(snapshot.secondary);
+	if (!primary && !secondary) return undefined;
+	return { limitId, primary, secondary };
+}
+
+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 };
+}
+
+function mergeSnapshot(
+	left: NormalizedRateLimitSnapshot,
+	right: NormalizedRateLimitSnapshot,
+): NormalizedRateLimitSnapshot {
+	return {
+		limitId: right.limitId || left.limitId,
+		primary: right.primary ?? left.primary,
+		secondary: right.secondary ?? left.secondary,
+	};
+}
+
+export function formatCodexUsageStatusline(
+	report: CodexUsageReport,
+	ctx: ExtensionContext,
+	_model?: CodexUsageModel,
+): string {
+	const snapshot = selectPrimaryCodexSnapshot(report);
+	if (!snapshot) return formatStatuslineText(ctx, "n/a");
+
+	if (!snapshot.primary && !snapshot.secondary) return formatStatuslineText(ctx, "n/a");
+	return formatStatuslineText(
+		ctx,
+		`[${formatDualLimitBar(snapshot.primary, snapshot.secondary)}]`,
+	);
+}
+
+function formatStatuslineText(ctx: ExtensionContext, value: string): string {
+	const label = ctx.ui.theme.fg("accent", STATUS_LABEL_TEXT);
+	return `${label} ${ctx.ui.theme.fg("muted", value)}`;
+}
+
+function formatEmptyStatuslineBar(ctx: ExtensionContext): string {
+	return formatStatuslineText(ctx, "[\u00a0\u00a0\u00a0\u00a0\u00a0]");
+}
+
+function formatStatuslineProblem(
+	ctx: ExtensionContext,
+	errors: UsageQueryError[],
+): string {
+	const label = ctx.ui.theme.fg("accent", STATUS_LABEL_TEXT);
+	const value = isUnavailable(errors)
+		? ctx.ui.theme.fg("muted", "n/a")
+		: ctx.ui.theme.fg("error", "error");
+	return `${label} ${value}`;
+}
+
+function isUnavailable(errors: UsageQueryError[]): boolean {
+	return errors.some((error) => {
+		const message = error.message.toLowerCase();
+		return (
+			message.includes("no pi openai codex subscription auth") ||
+			message.includes("no displayable rate-limit windows") ||
+			message.includes("returned no displayable rate-limit windows") ||
+			message.includes("returned 401") ||
+			message.includes("returned 403") ||
+			message.includes("unauthorized") ||
+			message.includes("forbidden") ||
+			message.includes("subscription") ||
+			message.includes("no active plan") ||
+			message.includes("plan unavailable") ||
+			message.includes("quota unavailable") ||
+			message.includes("rate limits unavailable")
+		);
+	});
+}
+
+function selectPrimaryCodexSnapshot(
+	report: CodexUsageReport,
+): NormalizedRateLimitSnapshot | undefined {
+	return report.snapshots.find(isPrimaryCodexSnapshot) ?? report.snapshots[0];
+}
+
+function normalizedUsageKey(value: string | undefined): string | undefined {
+	const key = value
+		?.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return key || undefined;
+}
+
+function formatDualLimitBar(
+	primary: NormalizedRateLimitWindow | undefined,
+	secondary: NormalizedRateLimitWindow | undefined,
+): string {
+	const primaryParts = filledTenths(primary);
+	const secondaryParts = filledTenths(secondary);
+	let value = "";
+	for (let index = 0; index < 5; index++) {
+		const leftPart = index * 2 + 1;
+		const rightPart = leftPart + 1;
+		let mask = 0;
+		if (primaryParts >= leftPart) mask |= 1;
+		if (primaryParts >= rightPart) mask |= 2;
+		if (secondaryParts >= leftPart) mask |= 4;
+		if (secondaryParts >= rightPart) mask |= 8;
+		value += DUAL_BAR_CHARS[mask];
+	}
+	return value;
+}
+
+function filledTenths(window: NormalizedRateLimitWindow | undefined): number {
+	if (!window) return 0;
+	return Math.round(remainingPercent(window) / 10);
+}
+
+function remainingPercent(window: NormalizedRateLimitWindow): number {
+	return 100 - clampPercent(window.usedPercent);
+}
+
+function isPrimaryCodexSnapshot(
+	snapshot: NormalizedRateLimitSnapshot,
+): boolean {
+	return normalizedUsageKey(snapshot.limitId) === "codex";
+}
+
+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 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);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@llblab/pi-codex-usage",
+  "version": "0.3.3",
+  "private": false,
+  "description": "Minimal Pi extension that shows primary Codex ChatGPT subscription usage limits.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "codex",
+    "usage",
+    "status"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/llblab/pi-codex-usage.git"
+  },
+  "homepage": "https://github.com/llblab/pi-codex-usage",
+  "bugs": {
+    "url": "https://github.com/llblab/pi-codex-usage/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "check": "node --experimental-strip-types -e \"await import('./index.ts'); console.log('pi-codex-usage: extension import ok')\"",
+    "typecheck": "tsc --noEmit",
+    "pack:dry": "npm pack --dry-run",
+    "validate": "npm run typecheck && npm run check && npm run pack:dry"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "AGENTS.md",
+    "BACKLOG.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest"
+  }
+}