rinco-pi-hud 1.0.0

package/extensions/hud/telemetry/codex-usage/normalize.ts

@@ -0,0 +1,264 @@
+import { sanitizeCodexText } from "./safety.ts";
+import type {
+	AppServerRateLimitResetCredit,
+	AppServerRateLimitResetCredits,
+	AppServerRateLimitResponse,
+	AppServerRateLimitSnapshot,
+	AppServerWindowSnapshot,
+	BackendAdditionalRateLimit,
+	BackendRateLimitDetails,
+	BackendRateLimitResetCredits,
+	BackendWindowSnapshot,
+	CodexUsageReport,
+	NormalizedRateLimitResetCredit,
+	NormalizedRateLimitResetCredits,
+	NormalizedRateLimitSnapshot,
+	NormalizedRateLimitWindow,
+	RateLimitStatusPayload,
+	UsageSource,
+} from "./types.ts";
+
+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);
+	if (primary) snapshots.push(primary);
+
+	const additional = Array.isArray(payload.additional_rate_limits)
+		? payload.additional_rate_limits
+		: [];
+	for (const item of additional) {
+		const additionalLimit = asObject(item) as BackendAdditionalRateLimit | undefined;
+		if (!additionalLimit) continue;
+		const limitId =
+			asString(additionalLimit.metered_feature) ?? asString(additionalLimit.limit_name);
+		if (!limitId) continue;
+		try {
+			const snapshot = normalizeBackendSnapshot(
+				limitId,
+				asString(additionalLimit.limit_name),
+				additionalLimit.rate_limit,
+			);
+			if (snapshot) snapshots.push(snapshot);
+		} catch {
+			// Optional additional buckets must not hide otherwise usable primary/reset usage.
+		}
+	}
+
+	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, resetCredits };
+}
+
+function normalizeBackendSnapshot(
+	limitId: string,
+	limitName: string | undefined,
+	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, limitName, 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;
+	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 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, optional = false) => {
+		let snapshot: NormalizedRateLimitSnapshot | undefined;
+		try {
+			snapshot = normalizeAppServerSnapshot(raw, fallbackId);
+		} catch (error) {
+			if (optional) return;
+			throw error;
+		}
+		if (!snapshot) return;
+		const resolvedSnapshot = snapshot;
+		const existingIndex = snapshots.findIndex((item) => item.limitId === resolvedSnapshot.limitId);
+		const existing = existingIndex >= 0 ? snapshots[existingIndex] : undefined;
+		if (existingIndex >= 0 && existing)
+			snapshots[existingIndex] = mergeSnapshot(existing, resolvedSnapshot);
+		else snapshots.push(resolvedSnapshot);
+	};
+
+	addSnapshot(response.rateLimits, "codex");
+	const snapshotsByLimitId = asObject(response.rateLimitsByLimitId);
+	if (snapshotsByLimitId) {
+		for (const [limitId, raw] of Object.entries(snapshotsByLimitId)) {
+			if (limitId) addSnapshot(raw, limitId, true);
+		}
+	}
+
+	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,
+		resetCredits,
+	};
+}
+
+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);
+	if (!primary && !secondary) return undefined;
+	return { limitId, limitName, 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,
+		windowMinutes: asNumber(window.windowDurationMins),
+		resetsAt: asNumber(window.resetsAt),
+	};
+}
+
+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,
+): NormalizedRateLimitSnapshot {
+	return {
+		limitId: right.limitId || left.limitId,
+		limitName: right.limitName ?? left.limitName,
+		primary: right.primary ?? left.primary,
+		secondary: right.secondary ?? left.secondary,
+	};
+}
+
+function assertObject(value: unknown, description: string): Record<string, unknown> {
+	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>;
+}
+
+function asString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	return sanitizeCodexText(value, 160) || 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 asNonnegativeInteger(value: unknown): number | undefined {
+	const parsed = asNumber(value);
+	if (parsed === undefined || !Number.isSafeInteger(parsed)) return undefined;
+	return Math.max(0, parsed);
+}

package/extensions/hud/telemetry/codex-usage/query.ts

@@ -0,0 +1,207 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { queryViaCodexAppServer } from "./app-server-client.ts";
+import { normalizeBackendPayload } from "./normalize.ts";
+import { safeCodexErrorMessage } from "./safety.ts";
+import type {
+	CodexUsageReport,
+	PiModel,
+	QueryUsageOptions,
+	QueryUsageResult,
+	RateLimitStatusPayload,
+	UsageQueryError,
+} from "./types.ts";
+
+const CODEX_PROVIDER_ID = "openai-codex";
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const MAX_RESPONSE_BODY_BYTES = 1024 * 1024;
+
+export function isOpenAICodexModel(model: Pick<PiModel, "provider"> | undefined): boolean {
+	return model?.provider === CODEX_PROVIDER_ID;
+}
+
+export function isStaleExtensionContextError(error: unknown): boolean {
+	return (
+		error instanceof Error &&
+		error.message.includes("This extension ctx is stale after session replacement or reload")
+	);
+}
+
+export async function queryUsage(
+	ctx: ExtensionContext,
+	options: Pick<QueryUsageOptions, "timeoutMs">,
+	signal?: AbortSignal,
+): Promise<QueryUsageResult> {
+	const errors: UsageQueryError[] = [];
+
+	try {
+		const report = await queryViaPiAuth(ctx, options.timeoutMs, signal);
+		return { ok: true, report };
+	} catch (cause) {
+		if (isStaleExtensionContextError(cause)) throw cause;
+		errors.push({ source: "pi-auth", message: safeCodexErrorMessage(cause) });
+	}
+
+	try {
+		const report = await queryViaCodexAppServer(options.timeoutMs, signal);
+		return { ok: true, report };
+	} catch (cause) {
+		if (isStaleExtensionContextError(cause)) throw cause;
+		errors.push({ source: "codex-app-server", message: safeCodexErrorMessage(cause) });
+	}
+
+	return { ok: false, errors };
+}
+
+async function queryViaPiAuth(
+	ctx: ExtensionContext,
+	timeoutMs: number,
+	signal?: AbortSignal,
+): 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, text } = await fetchTextWithTimeout(
+		CODEX_USAGE_URL,
+		{ method: "GET", headers: auth.headers, redirect: "error" },
+		timeoutMs,
+		signal,
+	);
+	if (!response.ok) {
+		throw new Error(`Codex usage endpoint returned HTTP ${response.status}.`);
+	}
+	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 = allowedAuthHeaders(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 fetchTextWithTimeout(
+	url: string,
+	init: RequestInit,
+	timeoutMs: number,
+	externalSignal?: AbortSignal,
+): Promise<{ response: Response; text: string }> {
+	const controller = new AbortController();
+	const abortFromExternal = () => controller.abort();
+	if (externalSignal?.aborted) controller.abort();
+	else externalSignal?.addEventListener("abort", abortFromExternal, { once: true });
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetch(url, { ...init, signal: controller.signal });
+		const text = response.ok ? await readResponseText(response, MAX_RESPONSE_BODY_BYTES) : "";
+		return { response, text };
+	} catch (error) {
+		if (controller.signal.aborted) {
+			throw new Error(
+				externalSignal?.aborted
+					? "Codex usage query was cancelled."
+					: `Timed out after ${Math.round(timeoutMs / 1000)}s while fetching Codex usage.`,
+			);
+		}
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+		externalSignal?.removeEventListener("abort", abortFromExternal);
+	}
+}
+
+async function readResponseText(response: Response, maxBytes: number): Promise<string> {
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let size = 0;
+	let text = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > maxBytes) {
+				await reader.cancel("response size limit exceeded");
+				throw new Error("Codex usage response exceeded the size limit.");
+			}
+			text += decoder.decode(value, { stream: true });
+		}
+		return text + decoder.decode();
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+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)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`${description} was not an object.`);
+	}
+	return parsed as Record<string, unknown>;
+}
+
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+	return Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());
+}
+
+function allowedAuthHeaders(source: Record<string, string>): Record<string, string> {
+	const allowed = new Set(["authorization", "chatgpt-account-id", "user-agent", "accept"]);
+	return Object.fromEntries(
+		Object.entries(source).filter(([key]) => allowed.has(key.toLowerCase())),
+	);
+}
+
+function errorMessage(error: unknown): string {
+	return safeCodexErrorMessage(error);
+}

package/extensions/hud/telemetry/codex-usage/safety.ts

@@ -0,0 +1,27 @@
+import { stripVTControlCharacters } from "node:util";
+
+const BEARER_PATTERN = /Bearer\s+[A-Za-z0-9._~+/=-]+/gi;
+const SECRET_FIELD_PATTERN =
+	/("?(?:access[_-]?token|refresh[_-]?token|id[_-]?token|session[_-]?token|client[_-]?secret|api[_-]?key|authorization|password)"?\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi;
+const COOKIE_PATTERN = /((?:set-)?cookie\s*[:=]\s*)[^\r\n]*/gi;
+const SECRET_QUERY_PATTERN =
+	/([?&](?:access_token|refresh_token|id_token|session_token|client_secret|api_key|password)=)[^&#\s]+/gi;
+
+export function sanitizeCodexText(value: unknown, maxChars = 600): string {
+	let text = typeof value === "string" ? value : value instanceof Error ? value.message : String(value);
+	text = stripVTControlCharacters(text.slice(0, Math.max(maxChars * 4, maxChars)))
+		.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+	text = text
+		.replace(BEARER_PATTERN, "Bearer <redacted>")
+		.replace(SECRET_FIELD_PATTERN, "$1<redacted>")
+		.replace(COOKIE_PATTERN, "$1<redacted>")
+		.replace(SECRET_QUERY_PATTERN, "$1<redacted>");
+	return text
+		.replace(/\s+/g, " ")
+		.trim()
+		.slice(0, maxChars);
+}
+
+export function safeCodexErrorMessage(error: unknown): string {
+	return sanitizeCodexText(error instanceof Error ? error.message : error);
+}

package/extensions/hud/telemetry/codex-usage/types.ts

@@ -0,0 +1,137 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type UsageSource = "pi-auth" | "codex-app-server";
+export type PiModel = NonNullable<ExtensionContext["model"]>;
+export type CodexUsageModel = Pick<PiModel, "id" | "name" | "provider">;
+
+export type QueryUsageOptions = {
+	clearStatusline: boolean;
+	refresh: boolean;
+	statusline: boolean;
+	timeoutMs: number;
+};
+
+export type CachedReport = {
+	createdAt: number;
+	report: CodexUsageReport;
+};
+
+export type QueryUsageResult =
+	| { ok: true; report: CodexUsageReport }
+	| { ok: false; errors: UsageQueryError[] };
+
+export type UsageQueryError = {
+	source: UsageSource;
+	message: string;
+	cause?: unknown;
+};
+
+export type CodexUsageReport = {
+	source: UsageSource;
+	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 = {
+	limitId: string;
+	limitName?: string;
+	primary?: NormalizedRateLimitWindow;
+	secondary?: NormalizedRateLimitWindow;
+};
+
+export type NormalizedRateLimitWindow = {
+	usedPercent: number;
+	windowMinutes?: number;
+	resetsAt?: number;
+};
+
+export type RateLimitStatusPayload = {
+	plan_type?: unknown;
+	rate_limit?: unknown;
+	additional_rate_limits?: unknown;
+	rate_limit_reset_credits?: unknown;
+};
+
+export type BackendRateLimitResetCredits = {
+	available_count?: unknown;
+};
+
+export type BackendRateLimitDetails = {
+	primary_window?: unknown;
+	secondary_window?: unknown;
+};
+
+export type BackendWindowSnapshot = {
+	used_percent?: unknown;
+	limit_window_seconds?: unknown;
+	reset_at?: unknown;
+};
+
+export type BackendAdditionalRateLimit = {
+	limit_name?: unknown;
+	metered_feature?: unknown;
+	rate_limit?: unknown;
+};
+
+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 = {
+	limitId?: unknown;
+	limitName?: unknown;
+	primary?: unknown;
+	secondary?: unknown;
+	planType?: unknown;
+};
+
+export type AppServerWindowSnapshot = {
+	usedPercent?: unknown;
+	windowDurationMins?: unknown;
+	resetsAt?: unknown;
+};
+
+export type RpcResponse = {
+	id?: unknown;
+	result?: unknown;
+	error?: { message?: unknown; code?: unknown };
+};
+
+export type PendingRpc = {
+	resolve: (value: unknown) => void;
+	reject: (error: Error) => void;
+};