@narumitw/pi-usage 0.24.0

package/src/index.ts

@@ -0,0 +1,34 @@
+export {
+	abortError,
+	awaitWithDeadline,
+	errorMessage,
+	fingerprintResolvedAuth,
+	redactUsageError,
+	runWithConcurrency,
+	sanitizeDisplayText,
+	UsageCache,
+} from "./core.js";
+export { formatProviderStates, formatUsageReport, formatUsageStatusline } from "./format.js";
+export { normalizeCodexBackendPayload } from "./providers/codex.js";
+export { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
+export {
+	adapterForProvider,
+	isStaleExtensionContextError,
+	providerIsConfigured,
+	queryProviderUsage,
+	resolveUsageAuth,
+	SUPPORTED_ADAPTERS,
+} from "./query.js";
+export type {
+	ProviderUsageState,
+	ResolvedUsageAuth,
+	UsageBucket,
+	UsageDisplayState,
+	UsageMetric,
+	UsageModel,
+	UsageProviderAdapter,
+	UsageReport,
+	UsageSemantics,
+	UsageSemanticsKind,
+	UsageUnit,
+} from "./types.js";

package/src/providers/codex.ts

@@ -0,0 +1,150 @@
+import { sanitizeDisplayText } from "../core.js";
+import type { CodexBackendPayload, UsageBucket, UsageMetric, UsageReport } from "../types.js";
+
+export function normalizeCodexBackendPayload(
+	payload: CodexBackendPayload,
+	capturedAt: number,
+): UsageReport {
+	const buckets: UsageBucket[] = [];
+	normalizeRateLimitGroup(buckets, "codex", "Codex", payload.rate_limit, false);
+
+	const additional = Array.isArray(payload.additional_rate_limits)
+		? payload.additional_rate_limits
+		: [];
+	for (const item of additional) {
+		const value = asObject(item);
+		const id = asString(value?.metered_feature) ?? asString(value?.limit_name);
+		if (!value || !id) continue;
+		try {
+			normalizeRateLimitGroup(
+				buckets,
+				id,
+				asString(value.limit_name) ?? id,
+				value.rate_limit,
+				true,
+			);
+		} catch {
+			// Optional provider-specific buckets must not hide otherwise useful primary data.
+		}
+	}
+
+	const metrics: UsageMetric[] = [];
+	const credits = asObject(payload.credits);
+	if (credits?.has_credits === true) {
+		if (credits.unlimited === true) {
+			metrics.push({ id: "credits", label: "Credits", value: "unlimited" });
+		} else {
+			const balance = asNumber(credits.balance);
+			if (balance !== undefined) {
+				metrics.push({ id: "credits", label: "Credits", value: balance, unit: "count" });
+			} else {
+				metrics.push({ id: "credits", label: "Credits", value: "available" });
+			}
+		}
+	} else if (credits?.has_credits === false) {
+		metrics.push({ id: "credits", label: "Credits", value: "none" });
+	}
+	const resetCredits = asObject(payload.rate_limit_reset_credits);
+	const resetCount = asNonnegativeInteger(resetCredits?.available_count);
+	if (resetCount !== undefined) {
+		metrics.push({
+			id: "reset-credits",
+			label: "Usage limit resets",
+			value: resetCount,
+			unit: "count",
+		});
+	}
+	if (buckets.length === 0 && metrics.length === 0) {
+		throw new Error("Codex usage endpoint returned no displayable usage data.");
+	}
+
+	const planType = asString(payload.plan_type);
+	return {
+		providerId: "openai-codex",
+		providerName: "OpenAI Codex",
+		capturedAt,
+		source: "codex-pi-auth",
+		semantics: {
+			kind: "consumer-subscription",
+			label: "ChatGPT subscription limits",
+		},
+		buckets,
+		metrics,
+		...(planType ? { notes: [`Plan: ${planType}`] } : {}),
+	};
+}
+
+function normalizeRateLimitGroup(
+	buckets: UsageBucket[],
+	groupId: string,
+	groupLabel: string,
+	raw: unknown,
+	optional: boolean,
+): void {
+	if (raw === undefined || raw === null) return;
+	const details = asObject(raw);
+	if (!details) {
+		if (optional) return;
+		throw new Error("Codex rate limit was not an object.");
+	}
+	addWindow(buckets, groupId, groupLabel, "primary", details.primary_window);
+	addWindow(buckets, groupId, groupLabel, "secondary", details.secondary_window);
+}
+
+function addWindow(
+	buckets: UsageBucket[],
+	groupId: string,
+	groupLabel: string,
+	position: "primary" | "secondary",
+	raw: unknown,
+): void {
+	if (raw === undefined || raw === null) return;
+	const value = asObject(raw);
+	if (!value) throw new Error("Codex rate-limit window was not an object.");
+	const used = asNumber(value.used_percent);
+	if (used === undefined) return;
+	const seconds = asNumber(value.limit_window_seconds);
+	const resetsAt = asNumber(value.reset_at);
+	buckets.push({
+		id: `${groupId}:${position}`,
+		label: position === "primary" ? "Primary limit" : "Secondary limit",
+		groupId,
+		groupLabel,
+		modelKeys: [groupId, groupLabel],
+		used,
+		remaining: 100 - clampPercent(used),
+		limit: 100,
+		unit: "percent",
+		...(seconds !== undefined && seconds > 0 ? { windowMinutes: Math.ceil(seconds / 60) } : {}),
+		...(resetsAt !== undefined ? { resetsAt } : {}),
+	});
+}
+
+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 sanitizeDisplayText(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);
+}
+
+function clampPercent(value: number): number {
+	return Math.min(100, Math.max(0, value));
+}

package/src/providers/openrouter.ts

@@ -0,0 +1,73 @@
+import { sanitizeDisplayText } from "../core.js";
+import type { OpenRouterKeyPayload, UsageBucket, UsageMetric, UsageReport } from "../types.js";
+
+export function normalizeOpenRouterKeyPayload(
+	payload: OpenRouterKeyPayload,
+	capturedAt: number,
+): UsageReport {
+	const data = asObject(payload.data);
+	if (!data) throw new Error("OpenRouter key response data was not an object.");
+
+	const limit = asNonnegativeNumber(data.limit);
+	const remaining = asNonnegativeNumber(data.limit_remaining);
+	const period = asString(data.limit_reset);
+	const totalUsage = asNonnegativeNumber(data.usage);
+	const buckets: UsageBucket[] = [];
+	if (limit !== undefined) {
+		buckets.push({
+			id: "key-limit",
+			label: "Key limit",
+			...(remaining !== undefined ? { used: Math.max(0, limit - remaining), remaining } : {}),
+			limit,
+			unit: "usd",
+			...(period ? { period } : {}),
+		});
+	}
+
+	const metrics: UsageMetric[] = [];
+	addUsageMetric(metrics, "usage-daily", "Usage today", data.usage_daily);
+	addUsageMetric(metrics, "usage-weekly", "Usage this week", data.usage_weekly);
+	addUsageMetric(metrics, "usage-monthly", "Usage this month", data.usage_monthly);
+	addUsageMetric(metrics, "usage-total", "All-time usage", totalUsage);
+	if (buckets.length === 0 && metrics.length === 0) {
+		throw new Error("OpenRouter key response returned no displayable usage data.");
+	}
+
+	const notes: string[] = [];
+	if (data.limit === null) notes.push("No per-key spend cap");
+	else if (limit === undefined) notes.push("Per-key spend cap unavailable");
+	if (data.is_free_tier === true) notes.push("Free-tier API key");
+
+	return {
+		providerId: "openrouter",
+		providerName: "OpenRouter",
+		capturedAt,
+		source: "openrouter-key",
+		semantics: { kind: "api-key", label: "API-key spend limits" },
+		accountLabel: asString(data.label),
+		buckets,
+		metrics,
+		...(notes.length > 0 ? { notes } : {}),
+	};
+}
+
+function addUsageMetric(metrics: UsageMetric[], id: string, label: string, value: unknown): void {
+	const amount = typeof value === "number" ? asNonnegativeNumber(value) : undefined;
+	if (amount === undefined) return;
+	metrics.push({ id, label, value: amount, unit: "usd" });
+}
+
+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 sanitizeDisplayText(value, 80) || undefined;
+}
+
+function asNonnegativeNumber(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
+	return value;
+}

package/src/query.ts

@@ -0,0 +1,313 @@
+import { randomBytes } from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { errorMessage, fingerprintResolvedAuth, redactUsageError } from "./core.js";
+import { normalizeCodexBackendPayload } from "./providers/codex.js";
+import { normalizeOpenRouterKeyPayload } from "./providers/openrouter.js";
+import type {
+	CodexBackendPayload,
+	OpenRouterKeyPayload,
+	PiModel,
+	ResolvedUsageAuth,
+	UsageProviderAdapter,
+	UsageReport,
+} from "./types.js";
+
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const OPENROUTER_KEY_URL = "https://openrouter.ai/api/v1/key";
+const MAX_SUCCESS_BODY_BYTES = 64 * 1024;
+const MAX_ERROR_BODY_BYTES = 4 * 1024;
+
+export const AUTH_FINGERPRINT_SALT = randomBytes(32);
+
+export const SUPPORTED_ADAPTERS: readonly UsageProviderAdapter[] = [
+	{
+		id: "openai-codex",
+		displayName: "OpenAI Codex",
+		semantics: {
+			kind: "consumer-subscription",
+			label: "ChatGPT subscription limits",
+		},
+		async query(auth, signal, timeoutMs) {
+			const payload = await fetchProviderJson(
+				CODEX_USAGE_URL,
+				auth,
+				signal,
+				timeoutMs,
+				"Codex usage endpoint",
+			);
+			return normalizeCodexBackendPayload(payload as CodexBackendPayload, Date.now());
+		},
+	},
+	{
+		id: "openrouter",
+		displayName: "OpenRouter",
+		semantics: { kind: "api-key", label: "API-key spend limits" },
+		async query(auth, signal, timeoutMs) {
+			const payload = await fetchProviderJson(
+				OPENROUTER_KEY_URL,
+				auth,
+				signal,
+				timeoutMs,
+				"OpenRouter key endpoint",
+			);
+			return normalizeOpenRouterKeyPayload(payload as OpenRouterKeyPayload, Date.now());
+		},
+	},
+];
+
+export function adapterForProvider(
+	providerId: string | undefined,
+): UsageProviderAdapter | undefined {
+	return SUPPORTED_ADAPTERS.find((adapter) => adapter.id === providerId);
+}
+
+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 resolveUsageAuth(
+	ctx: ExtensionContext,
+	adapter: UsageProviderAdapter,
+	salt: Uint8Array = AUTH_FINGERPRINT_SALT,
+): Promise<ResolvedUsageAuth | undefined> {
+	if (ctx.model?.provider === adapter.id && !hasOfficialOrigin(ctx.model, adapter.id)) {
+		throw new Error(
+			`${adapter.displayName} usage cannot send a custom provider base URL credential to the official usage endpoint.`,
+		);
+	}
+
+	const model = candidateModels(ctx, adapter.id).find((candidate) =>
+		hasOfficialOrigin(candidate, adapter.id),
+	);
+	if (!model) return undefined;
+	const registry = ctx.modelRegistry as unknown as UsageAuthRegistry;
+	let modelAuth: RequestAuth | undefined;
+	if (ctx.model?.provider === adapter.id && typeof registry.getApiKeyAndHeaders === "function") {
+		const result = await registry.getApiKeyAndHeaders(ctx.model);
+		if (!result.ok) throw new Error(redactUsageError(result.error));
+		if (authorizationFrom(result)) modelAuth = result;
+	}
+	if (typeof registry.getProviderAuth !== "function") {
+		throw new Error("pi-usage requires Pi 0.81.0 or newer to validate resolved provider auth.");
+	}
+	const providerResult = await registry.getProviderAuth(adapter.id);
+	if (
+		providerResult?.auth.baseUrl &&
+		!hasOfficialUrlOrigin(providerResult.auth.baseUrl, adapter.id)
+	) {
+		throw new Error(
+			`${adapter.displayName} usage cannot send a proxy-resolved credential to the official usage endpoint.`,
+		);
+	}
+	const auth = modelAuth ?? providerResult?.auth;
+	if (!auth) return undefined;
+	const authorization = authorizationFrom(auth);
+	if (!authorization) return undefined;
+	const headers = { Authorization: authorization };
+	const secrets = [auth.apiKey, headerValue(auth.headers, "Authorization"), authorization].filter(
+		(value): value is string => Boolean(value),
+	);
+	return {
+		apiKey: auth.apiKey,
+		headers,
+		fingerprint: fingerprintResolvedAuth({ headers }, salt),
+		secrets,
+		model,
+	};
+}
+
+export async function queryProviderUsage(
+	adapter: UsageProviderAdapter,
+	auth: ResolvedUsageAuth,
+	signal: AbortSignal,
+	timeoutMs: number,
+): Promise<UsageReport> {
+	try {
+		return await adapter.query(auth, signal, timeoutMs);
+	} catch (error) {
+		if (isStaleExtensionContextError(error) || isAbortError(error)) throw error;
+		throw new Error(redactUsageError(errorMessage(error), auth.secrets));
+	}
+}
+
+export function providerIsConfigured(ctx: ExtensionContext, providerId: string): boolean {
+	try {
+		return ctx.modelRegistry.getProviderAuthStatus(providerId).configured;
+	} catch {
+		return candidateModels(ctx, providerId).length > 0;
+	}
+}
+
+function candidateModels(ctx: ExtensionContext, providerId: string): PiModel[] {
+	const candidates: PiModel[] = [];
+	const seen = new Set<string>();
+	const add = (model: PiModel | undefined) => {
+		if (!model || model.provider !== providerId) 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 fetchProviderJson(
+	url: string,
+	auth: ResolvedUsageAuth,
+	signal: AbortSignal,
+	timeoutMs: number,
+	description: string,
+): Promise<Record<string, unknown>> {
+	const controller = new AbortController();
+	let timedOut = false;
+	const abortFromCaller = () => controller.abort();
+	if (signal.aborted) controller.abort();
+	else signal.addEventListener("abort", abortFromCaller, { once: true });
+	const timeout = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, timeoutMs);
+	try {
+		const headers = { ...auth.headers };
+		if (!hasHeader(headers, "User-Agent")) headers["User-Agent"] = "pi-usage";
+		const response = await fetch(url, { headers, signal: controller.signal });
+		if (controller.signal.aborted)
+			throw Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
+		const text = await readBoundedResponse(
+			response,
+			response.ok ? MAX_SUCCESS_BODY_BYTES : MAX_ERROR_BODY_BYTES,
+			!response.ok,
+			description,
+		);
+		if (controller.signal.aborted)
+			throw Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
+		if (!response.ok) {
+			throw new Error(
+				`${description} returned ${response.status} ${response.statusText}: ${redactUsageError(text, auth.secrets)}`,
+			);
+		}
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(text) as unknown;
+		} catch (error) {
+			throw new Error(`${description} returned invalid JSON: ${errorMessage(error)}`);
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error(`${description} response was not an object.`);
+		}
+		return parsed as Record<string, unknown>;
+	} catch (error) {
+		if (timedOut) {
+			throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s while fetching usage.`);
+		}
+		if (signal.aborted)
+			throw Object.assign(new Error("Usage query aborted."), { name: "AbortError" });
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+		signal.removeEventListener("abort", abortFromCaller);
+	}
+}
+
+async function readBoundedResponse(
+	response: Response,
+	maxBytes: number,
+	truncateOverflow: boolean,
+	description: string,
+): Promise<string> {
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	let truncated = false;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			const remaining = maxBytes - total;
+			if (value.byteLength > remaining) {
+				if (remaining > 0) chunks.push(value.subarray(0, remaining));
+				total = maxBytes;
+				truncated = true;
+				await reader.cancel();
+				break;
+			}
+			chunks.push(value);
+			total += value.byteLength;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	if (truncated && !truncateOverflow) {
+		throw new Error(`${description} response exceeded ${maxBytes} bytes.`);
+	}
+	const body = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	const text = new TextDecoder().decode(body);
+	return truncated ? `${text}…` : text;
+}
+
+type RequestAuth = {
+	apiKey?: string;
+	headers?: Record<string, string | null>;
+};
+
+type UsageAuthRegistry = {
+	getApiKeyAndHeaders?(
+		model: PiModel,
+	): Promise<({ ok: true } & RequestAuth) | { ok: false; error: string }>;
+	getProviderAuth?(providerId: string): Promise<
+		| {
+				auth: RequestAuth & { baseUrl?: string };
+		  }
+		| undefined
+	>;
+};
+
+function authorizationFrom(auth: RequestAuth): string | undefined {
+	return (
+		headerValue(auth.headers, "Authorization") ??
+		(auth.apiKey ? `Bearer ${auth.apiKey}` : undefined)
+	);
+}
+
+function hasOfficialOrigin(model: PiModel, providerId: string): boolean {
+	return hasOfficialUrlOrigin(model.baseUrl, providerId);
+}
+
+function hasOfficialUrlOrigin(value: string, providerId: string): boolean {
+	const expected = providerId === "openai-codex" ? "https://chatgpt.com" : "https://openrouter.ai";
+	try {
+		return new URL(value).origin === expected;
+	} catch {
+		return false;
+	}
+}
+
+function headerValue(
+	headers: Record<string, string | null> | undefined,
+	name: string,
+): string | undefined {
+	const entry = Object.entries(headers ?? {}).find(
+		([candidate]) => candidate.toLowerCase() === name.toLowerCase(),
+	);
+	return entry?.[1] ?? undefined;
+}
+
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+	return Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());
+}
+
+function isAbortError(error: unknown): boolean {
+	return error instanceof Error && error.name === "AbortError";
+}

package/src/types.ts

@@ -0,0 +1,90 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type PiModel = NonNullable<ExtensionContext["model"]>;
+export type UsageModel = Pick<PiModel, "id" | "name" | "provider">;
+
+export type UsageSemanticsKind = "consumer-subscription" | "api-key" | "project";
+export type UsageUnit = "percent" | "usd" | "count";
+export type UsageDisplayState = "current" | "configured";
+
+export interface UsageSemantics {
+	kind: UsageSemanticsKind;
+	label: string;
+}
+
+export interface UsageBucket {
+	id: string;
+	label: string;
+	groupId?: string;
+	groupLabel?: string;
+	modelKeys?: string[];
+	used?: number;
+	remaining?: number;
+	limit?: number;
+	unit: UsageUnit;
+	period?: string;
+	windowMinutes?: number;
+	resetsAt?: number;
+}
+
+export interface UsageMetric {
+	id: string;
+	label: string;
+	value: number | string;
+	unit?: UsageUnit;
+}
+
+export interface UsageReport {
+	providerId: string;
+	providerName: string;
+	capturedAt: number;
+	source: string;
+	semantics: UsageSemantics;
+	accountLabel?: string;
+	buckets: UsageBucket[];
+	metrics: UsageMetric[];
+	notes?: string[];
+}
+
+export interface ResolvedUsageAuth {
+	apiKey?: string;
+	headers: Record<string, string>;
+	fingerprint: string;
+	secrets: string[];
+	model: PiModel;
+}
+
+export interface UsageProviderAdapter {
+	id: string;
+	displayName: string;
+	semantics: UsageSemantics;
+	query(auth: ResolvedUsageAuth, signal: AbortSignal, timeoutMs: number): Promise<UsageReport>;
+}
+
+export type ProviderUsageState =
+	| {
+			providerId: string;
+			providerName: string;
+			displayState: UsageDisplayState;
+			status: "ready";
+			report: UsageReport;
+	  }
+	| {
+			providerId: string;
+			providerName: string;
+			displayState: UsageDisplayState;
+			status: "unsupported" | "auth-unavailable" | "query-failed";
+			message: string;
+	  };
+
+export type OpenRouterKeyPayload = {
+	data?: unknown;
+};
+
+export type CodexBackendPayload = {
+	plan_type?: unknown;
+	rate_limit?: unknown;
+	additional_rate_limits?: unknown;
+	credits?: unknown;
+	rate_limit_reset_credits?: unknown;
+};