@maxiaochao/pi-toolkit 0.11.7 → 0.11.8

package/packages/openai-account-pool/src/store.ts

@@ -0,0 +1,259 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { acquireFileLock, type FileLockOptions } from "./lock.ts";
+
+/** The model provider the pool serves. Requests keep using `openai-codex/<model>`. */
+export const MAIN_PROVIDER_ID = "openai-codex";
+/** Prefix of the per-account storage keys. These are credential-store keys, not providers. */
+export const POOL_ENTRY_PREFIX = "pi-openai-account-pool/";
+export const STATE_DIRECTORY_NAME = "openai-account-pool";
+export const STATE_SCHEMA_VERSION = 1;
+
+export type AuthEntry = Record<string, unknown>;
+export type AuthEntries = Record<string, AuthEntry>;
+
+export interface TransactionResult<TValue, TResult> {
+	/** Returned only to write; omit it to leave the file untouched. */
+	value?: TValue;
+	result: TResult;
+}
+
+export function authPathFor(agentDir: string): string {
+	return join(agentDir, "auth.json");
+}
+
+export function poolStatePathFor(agentDir: string): string {
+	return join(agentDir, STATE_DIRECTORY_NAME, "state.json");
+}
+
+/** Stable storage key for one account, derived from the provider's own account id. */
+export function poolEntryKey(accountId: string): string {
+	return `${POOL_ENTRY_PREFIX}${createHash("sha256").update(accountId).digest("hex").slice(0, 16)}`;
+}
+
+export function isPoolEntryKey(key: string): boolean {
+	return key.startsWith(POOL_ENTRY_PREFIX);
+}
+
+function parseAuthEntries(text: string, path: string): AuthEntries {
+	const content = text.replace(/^\uFEFF/, "");
+	if (content.trim() === "") return {};
+	const parsed = JSON.parse(content) as unknown;
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		throw new Error(`Invalid ${path}: expected a JSON object.`);
+	}
+	for (const [key, value] of Object.entries(parsed)) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			throw new Error(`Invalid ${path}: credential "${key}" is not an object.`);
+		}
+	}
+	return parsed as AuthEntries;
+}
+
+export async function readAuthEntries(authPath: string): Promise<AuthEntries> {
+	let text: string;
+	try { text = await readFile(authPath, "utf8"); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+		throw error;
+	}
+	return parseAuthEntries(text, authPath);
+}
+
+/** Replacing a symlink or a non-file would write outside the agent directory or corrupt state. */
+async function assertReplaceableFile(path: string): Promise<void> {
+	let identity;
+	try { identity = await lstat(path); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+		throw error;
+	}
+	if (!identity.isFile()) throw new Error(`Refusing to replace ${path}: it is not a regular file.`);
+}
+
+async function writeTextAtomic(path: string, text: string): Promise<void> {
+	const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(text, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	try { await rename(temporary, path); }
+	catch (error) {
+		await unlink(temporary).catch(() => {});
+		throw error;
+	}
+}
+
+/**
+ * Read-modify-write of `auth.json` under the lock pi uses. Returning `value` replaces the whole
+ * file in one atomic rename, which is what lets one transaction add an account and update the
+ * main entry together. Unrelated provider entries must be carried over by the caller.
+ */
+export async function withAuthTransaction<T>(
+	authPath: string,
+	run: (entries: AuthEntries) => Promise<TransactionResult<AuthEntries, T>> | TransactionResult<AuthEntries, T>,
+	options: FileLockOptions = {},
+): Promise<T> {
+	await mkdir(dirname(authPath), { recursive: true, mode: 0o700 });
+	const lock = await acquireFileLock(authPath, options);
+	try {
+		await assertReplaceableFile(authPath);
+		const { value, result } = await run(await readAuthEntries(authPath));
+		if (value !== undefined) {
+			await lock.verifyHeld();
+			// Match pi's own formatting so concurrent writers produce comparable files.
+			await writeTextAtomic(authPath, JSON.stringify(value, null, 2));
+		}
+		return result;
+	} finally {
+		await lock.release();
+	}
+}
+
+/** Why an account is unavailable right now. Non-secret; shared across pi processes. */
+export interface AccountCooldown {
+	reason: string;
+	/** Pool generation this evidence belongs to; older evidence never outranks a newer login. */
+	generation: number;
+	/** Server-stated reset time in epoch ms, or null when the server did not state one. */
+	serverResetAtMs: number | null;
+	/** Local backoff before the next probe. Not a claimed quota reset time. */
+	probeAfterMs: number | null;
+	recordedAtMs: number;
+}
+
+/** One server-reported quota window. Non-secret: a percentage is not a credential. */
+export interface UsageWindow {
+	usedPercent: number;
+	/** Window length the server reported, which is what tells the five-hour one from the weekly one. */
+	windowSeconds?: number;
+	/** Server-stated reset time in epoch ms. Absent when the server stated none. */
+	resetAtMs?: number;
+}
+
+/** Quota as of the last successful wham/usage lookup for this account. */
+export interface AccountUsage {
+	/** Codex's primary window, the rolling five-hour one. */
+	primary?: UsageWindow;
+	/** Codex's secondary window, the weekly one. */
+	secondary?: UsageWindow;
+	/** Explicit backend decision, when returned by wham/usage. */
+	allowed?: boolean;
+	limitReached?: boolean;
+	plan?: string;
+	observedAtMs: number;
+}
+
+export interface AccountStateRecord {
+	/** Keyed by cooldown scope: "account" or `model:<id>`. */
+	cooldowns: Record<string, AccountCooldown>;
+	/** Last live usage observation, so a used-up account can still state its reset. */
+	usage?: AccountUsage;
+	/** Generation whose credential was proven invalid; re-authorizing bumps past it. */
+	authInvalidGeneration?: number;
+	/** When that proof was recorded, so an older request's success cannot clear it. */
+	authInvalidAtMs?: number;
+	/** Bounded lease so only one process probes a recovered account. */
+	probeLease?: { owner: string; untilMs: number };
+}
+
+/** Who is currently changing pool membership. Keeps enrollment, off and removal exclusive. */
+export interface EnrollmentLeaseRecord {
+	owner: string;
+	processId: number;
+	purpose: string;
+	startedAtMs: number;
+	expiresAtMs: number;
+}
+
+export interface PoolStateFile {
+	schemaVersion: number;
+	policy: "sticky";
+	accounts: Record<string, AccountStateRecord>;
+	/** Account the user picked by hand. Outranks the per-process sticky choice while usable. */
+	preferredAccountId?: string;
+	/** Account that most recently completed a model request successfully. */
+	currentAccountId?: string;
+	enrollment?: EnrollmentLeaseRecord;
+}
+
+export function emptyPoolState(): PoolStateFile {
+	return { schemaVersion: STATE_SCHEMA_VERSION, policy: "sticky", accounts: {} };
+}
+
+function parsePoolState(text: string, path: string): PoolStateFile {
+	const content = text.replace(/^\uFEFF/, "");
+	if (content.trim() === "") return emptyPoolState();
+	const parsed = JSON.parse(content) as Partial<PoolStateFile> | null;
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		throw new Error(`Invalid ${path}: expected a JSON object.`);
+	}
+	if (parsed.schemaVersion !== STATE_SCHEMA_VERSION) {
+		throw new Error(`Unsupported ${path}: schemaVersion ${String(parsed.schemaVersion)} is not ${STATE_SCHEMA_VERSION}.`);
+	}
+	if (typeof parsed.accounts !== "object" || parsed.accounts === null || Array.isArray(parsed.accounts)) {
+		throw new Error(`Invalid ${path}: "accounts" must be an object.`);
+	}
+	const state: PoolStateFile = { schemaVersion: STATE_SCHEMA_VERSION, policy: "sticky", accounts: parsed.accounts as Record<string, AccountStateRecord> };
+	if (parsed.preferredAccountId !== undefined) {
+		if (typeof parsed.preferredAccountId !== "string" || parsed.preferredAccountId === "") {
+			throw new Error(`Invalid ${path}: "preferredAccountId" must be a non-empty string.`);
+		}
+		state.preferredAccountId = parsed.preferredAccountId;
+	}
+	if (parsed.currentAccountId !== undefined) {
+		if (typeof parsed.currentAccountId !== "string" || parsed.currentAccountId === "") {
+			throw new Error(`Invalid ${path}: "currentAccountId" must be a non-empty string.`);
+		}
+		state.currentAccountId = parsed.currentAccountId;
+	}
+	const enrollment = parsed.enrollment;
+	if (enrollment) {
+		if (
+			typeof enrollment.owner !== "string" ||
+			typeof enrollment.processId !== "number" ||
+			typeof enrollment.purpose !== "string" ||
+			typeof enrollment.expiresAtMs !== "number" ||
+			typeof enrollment.startedAtMs !== "number"
+		) {
+			throw new Error(`Invalid ${path}: "enrollment" is malformed.`);
+		}
+		state.enrollment = enrollment;
+	}
+	return state;
+}
+
+export async function readPoolState(statePath: string): Promise<PoolStateFile> {
+	let text: string;
+	try { text = await readFile(statePath, "utf8"); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return emptyPoolState();
+		throw error;
+	}
+	return parsePoolState(text, statePath);
+}
+
+/** Short transaction for the non-secret cooldown/probe state. Never holds across a model stream. */
+export async function withPoolStateTransaction<T>(
+	statePath: string,
+	run: (state: PoolStateFile) => Promise<TransactionResult<PoolStateFile, T>> | TransactionResult<PoolStateFile, T>,
+	options: FileLockOptions = {},
+): Promise<T> {
+	await mkdir(dirname(statePath), { recursive: true, mode: 0o700 });
+	const lock = await acquireFileLock(statePath, options);
+	try {
+		await assertReplaceableFile(statePath);
+		const { value, result } = await run(await readPoolState(statePath));
+		if (value !== undefined) {
+			await lock.verifyHeld();
+			await writeTextAtomic(statePath, `${JSON.stringify(value, null, 2)}\n`);
+		}
+		return result;
+	} finally {
+		await lock.release();
+	}
+}

package/packages/openai-account-pool/src/usage.ts

@@ -0,0 +1,291 @@
+import { accountLabel, ensureFreshAccountCredential, type PoolAccount } from "./auth.ts";
+import { recordUsage } from "./availability.ts";
+import type { AccountStateRecord, AccountUsage, PoolStateFile, UsageWindow } from "./store.ts";
+
+/** ChatGPT's read-only Codex quota endpoint. Private and not guaranteed stable. */
+export const CODEX_USAGE_ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
+
+const MAX_RESET_HORIZON_MS = 30 * 24 * 60 * 60 * 1_000;
+const ONE_DAY_MS = 24 * 60 * 60 * 1_000;
+const MAX_USAGE_BODY_BYTES = 256 * 1024;
+const DEFAULT_USAGE_TIMEOUT_MS = 10_000;
+const EXHAUSTED_PERCENT = 100;
+const MILLISECOND_EPOCH_FLOOR = 1e10;
+
+function finite(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function resetAtMs(raw: number | undefined, now: number): number | undefined {
+	if (raw === undefined || raw <= 0) return undefined;
+	const candidate = raw > MILLISECOND_EPOCH_FLOOR ? raw : raw * 1_000;
+	return candidate > now - ONE_DAY_MS && candidate < now + MAX_RESET_HORIZON_MS ? candidate : undefined;
+}
+
+function normalizeWindow(value: unknown, now: number): UsageWindow | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const raw = value as Record<string, unknown>;
+	const used = finite(raw.used_percent) ?? finite(raw.usedPercent);
+	if (used === undefined) return undefined;
+	const seconds = finite(raw.limit_window_seconds) ?? finite(raw.window_seconds) ?? finite(raw.windowSeconds);
+	const minutes = finite(raw.window_minutes) ?? finite(raw.windowMinutes);
+	const reset = resetAtMs(finite(raw.reset_at) ?? finite(raw.resetAt), now);
+	return {
+		usedPercent: Math.max(0, Math.min(100, used)),
+		...(seconds !== undefined && seconds > 0
+			? { windowSeconds: Math.round(seconds) }
+			: minutes !== undefined && minutes > 0
+				? { windowSeconds: Math.round(minutes * 60) }
+				: {}),
+		...(reset !== undefined ? { resetAtMs: reset } : {}),
+	};
+}
+
+/** Normalizes one wham/usage response into the non-secret state we persist. */
+export function normalizeUsageResponse(value: unknown, now: number): AccountUsage {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Codex usage response is not an object.");
+	const raw = value as Record<string, unknown>;
+	const rateLimit = typeof raw.rate_limit === "object" && raw.rate_limit !== null ? (raw.rate_limit as Record<string, unknown>) : undefined;
+	if (!rateLimit) throw new Error("Codex usage response has no rate_limit object.");
+	const primary = normalizeWindow(rateLimit.primary_window, now);
+	const secondary = normalizeWindow(rateLimit.secondary_window, now);
+	const allowed = typeof rateLimit.allowed === "boolean" ? rateLimit.allowed : undefined;
+	const limitReached = typeof rateLimit.limit_reached === "boolean" ? rateLimit.limit_reached : undefined;
+	const plan = typeof raw.plan_type === "string" && /^[a-z0-9_-]{1,32}$/i.test(raw.plan_type) ? raw.plan_type : undefined;
+	if (!primary && !secondary && allowed === undefined && limitReached === undefined) {
+		throw new Error("Codex usage response contains no usable quota data.");
+	}
+	return {
+		...(primary ? { primary } : {}),
+		...(secondary ? { secondary } : {}),
+		...(allowed !== undefined ? { allowed } : {}),
+		...(limitReached !== undefined ? { limitReached } : {}),
+		...(plan ? { plan } : {}),
+		observedAtMs: now,
+	};
+}
+
+async function readJsonBounded(response: Response): Promise<unknown> {
+	if (!response.body) return JSON.parse("");
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > MAX_USAGE_BODY_BYTES) throw new Error("Codex usage response is too large.");
+			chunks.push(value);
+		}
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+	return JSON.parse(new TextDecoder().decode(Buffer.concat(chunks)));
+}
+
+/** Fetches live quota for one account. Tokens are used only in request headers and never returned. */
+export async function fetchAccountUsage(input: {
+	credential: Record<string, unknown>;
+	accountId: string;
+	now?: () => number;
+	fetch?: typeof globalThis.fetch;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+}): Promise<AccountUsage> {
+	const access = typeof input.credential.access === "string" ? input.credential.access : undefined;
+	if (!access) throw new Error("Codex account has no access token.");
+	const controller = new AbortController();
+	const abort = () => controller.abort(input.signal?.reason);
+	if (input.signal?.aborted) abort();
+	else input.signal?.addEventListener("abort", abort, { once: true });
+	const timer = setTimeout(() => controller.abort(new Error("usage_timeout")), input.timeoutMs ?? DEFAULT_USAGE_TIMEOUT_MS);
+	try {
+		const response = await (input.fetch ?? globalThis.fetch)(CODEX_USAGE_ENDPOINT, {
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${access}`,
+				"ChatGPT-Account-Id": input.accountId,
+				Accept: "application/json",
+			},
+			signal: controller.signal,
+		});
+		if (!response.ok) throw new Error(`Codex usage request failed (${response.status}).`);
+		const now = (input.now ?? (() => Date.now()))();
+		return normalizeUsageResponse(await readJsonBounded(response), now);
+	} finally {
+		clearTimeout(timer);
+		input.signal?.removeEventListener("abort", abort);
+	}
+}
+
+function sanitizeWindow(value: unknown): UsageWindow | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const raw = value as Partial<UsageWindow>;
+	if (typeof raw.usedPercent !== "number" || !Number.isFinite(raw.usedPercent)) return undefined;
+	const seconds = finite(raw.windowSeconds);
+	const reset = finite(raw.resetAtMs);
+	return {
+		usedPercent: Math.max(0, Math.min(100, raw.usedPercent)),
+		...(seconds !== undefined ? { windowSeconds: seconds } : {}),
+		...(reset !== undefined ? { resetAtMs: reset } : {}),
+	};
+}
+
+export function storedUsage(record: AccountStateRecord | undefined): AccountUsage | undefined {
+	const raw = record?.usage;
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const observedAtMs = finite(raw.observedAtMs);
+	if (observedAtMs === undefined) return undefined;
+	const primary = sanitizeWindow(raw.primary);
+	const secondary = sanitizeWindow(raw.secondary);
+	const allowed = typeof raw.allowed === "boolean" ? raw.allowed : undefined;
+	const limitReached = typeof raw.limitReached === "boolean" ? raw.limitReached : undefined;
+	const plan = typeof raw.plan === "string" ? raw.plan : undefined;
+	if (!primary && !secondary && allowed === undefined && limitReached === undefined) return undefined;
+	return {
+		...(primary ? { primary } : {}),
+		...(secondary ? { secondary } : {}),
+		...(allowed !== undefined ? { allowed } : {}),
+		...(limitReached !== undefined ? { limitReached } : {}),
+		...(plan ? { plan } : {}),
+		observedAtMs,
+	};
+}
+
+export function usageAvailable(usage: AccountUsage): boolean {
+	if (usage.allowed === false || usage.limitReached === true) return false;
+	if (usage.allowed === true && usage.limitReached === false) return true;
+	return ![usage.primary, usage.secondary].some((window) => window && window.usedPercent >= EXHAUSTED_PERCENT);
+}
+
+/**
+ * Refreshes accounts sequentially. Used by `/codex_pool status`, and only when every local account
+ * is unavailable before a model request. A failed account is reported but never blocks the rest.
+ */
+export async function refreshPoolUsage(input: {
+	authPath: string;
+	statePath: string;
+	accounts: readonly PoolAccount[];
+	refresh: (credential: Record<string, unknown>, signal?: AbortSignal) => Promise<Record<string, unknown>>;
+	now?: () => number;
+	fetch?: typeof globalThis.fetch;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+}): Promise<UsageRefreshResult[]> {
+	const results: UsageRefreshResult[] = [];
+	for (const account of [...input.accounts].sort((left, right) => left.ordinal - right.ordinal)) {
+		try {
+			const observedAtMs = (input.now ?? (() => Date.now()))();
+			const fresh = await ensureFreshAccountCredential({
+				authPath: input.authPath,
+				account,
+				refresh: (credential) => input.refresh(credential, input.signal),
+				signal: input.signal,
+				now: input.now,
+			});
+			const usage = await fetchAccountUsage({
+				credential: fresh.credential,
+				accountId: account.id,
+				now: input.now,
+				fetch: input.fetch,
+				signal: input.signal,
+				timeoutMs: input.timeoutMs,
+			});
+			// The request start is the latest instant this response can safely disprove. A quota
+			// failure recorded while the response was in flight must survive it.
+			usage.observedAtMs = observedAtMs;
+			await recordUsage({ statePath: input.statePath, account, usage, clearQuotaCooldowns: usageAvailable(usage) });
+			results.push({ account, usage });
+		} catch {
+			if (input.signal?.aborted) throw input.signal.reason ?? new Error("Request was aborted");
+			results.push({ account, error: "usage_unavailable" });
+		}
+	}
+	return results;
+}
+
+export interface UsageRefreshResult {
+	account: PoolAccount;
+	usage?: AccountUsage;
+	error?: string;
+}
+
+export interface ReadyEstimate {
+	accountId: string;
+	readyAtMs: number;
+}
+
+export function accountReadyAtMs(input: { record: AccountStateRecord | undefined; account: PoolAccount; now: number; modelId?: string }): number | undefined {
+	const { record, account, now } = input;
+	const future = (candidate: number | null | undefined): number | undefined =>
+		typeof candidate === "number" && candidate > now ? candidate : undefined;
+	const scopes = new Set(["account", ...(input.modelId ? [`model:${input.modelId}`] : [])]);
+	const cooldowns = Object.entries(record?.cooldowns ?? {})
+		.filter(([scope, cooldown]) => scopes.has(scope) && cooldown.generation === account.generation)
+		.map(([, cooldown]) => cooldown);
+	const stated = cooldowns.map((cooldown) => future(cooldown.serverResetAtMs));
+	if (cooldowns.length > 0 && stated.some((candidate) => candidate === undefined)) return undefined;
+	const usage = storedUsage(record);
+	const windows = [usage?.primary, usage?.secondary].filter((window): window is UsageWindow => !!window);
+	const exhaustedWindows = windows.filter((window) => window.usedPercent >= EXHAUSTED_PERCENT);
+	const explicitlyBlocked = usage?.allowed === false || usage?.limitReached === true;
+	const blockingWindows = exhaustedWindows.length > 0 ? exhaustedWindows : explicitlyBlocked ? windows : [];
+	const exhausted = blockingWindows.map((window) => future(window.resetAtMs));
+	if (explicitlyBlocked && blockingWindows.length === 0) return undefined;
+	if (blockingWindows.length > 0 && exhausted.some((candidate) => candidate === undefined)) return undefined;
+	// Every active limit must have reset before the account is usable. The later reset wins both
+	// across model/account cooldowns and across the primary/secondary quota windows.
+	const candidates = [...stated, ...exhausted].filter((candidate): candidate is number => candidate !== undefined);
+	return candidates.length > 0 ? Math.max(...candidates) : undefined;
+}
+
+export function soonestReady(input: { accounts: readonly PoolAccount[]; state: PoolStateFile; now: number; modelId?: string }): ReadyEstimate | undefined {
+	let best: ReadyEstimate | undefined;
+	for (const account of input.accounts) {
+		const record = input.state.accounts[account.id];
+		if (record?.authInvalidGeneration === account.generation) continue;
+		const readyAtMs = accountReadyAtMs({ record, account, now: input.now, modelId: input.modelId });
+		if (readyAtMs === undefined) continue;
+		if (!best || readyAtMs < best.readyAtMs) best = { accountId: account.id, readyAtMs };
+	}
+	return best;
+}
+
+function clockText(atMs: number): string {
+	const at = new Date(atMs);
+	return `${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}`;
+}
+
+export function formatRecovery(atMs: number, now: number): string {
+	const minutes = Math.max(1, Math.round((atMs - now) / 60_000));
+	if (minutes < 60) return `约 ${minutes} 分钟后（${clockText(atMs)}）`;
+	const hours = Math.floor(minutes / 60);
+	const rest = minutes % 60;
+	if (hours < 24) return `约 ${hours} 小时${rest > 0 ? ` ${rest} 分钟` : ""}后（${clockText(atMs)}）`;
+	return `约 ${Math.floor(hours / 24)} 天 ${hours % 24} 小时后（${clockText(atMs)}）`;
+}
+
+function windowName(window: UsageWindow, fallback: string): string {
+	if (window.windowSeconds === undefined) return fallback;
+	const hours = window.windowSeconds / 3_600;
+	if (hours >= 24 && hours % 24 === 0) return `${hours / 24} 天`;
+	return Number.isInteger(hours) ? `${hours} 小时` : fallback;
+}
+
+export function describeUsage(usage: AccountUsage | undefined, now = Date.now()): string | undefined {
+	if (!usage) return undefined;
+	const parts: string[] = [];
+	const describe = (window: UsageWindow, fallback: string) =>
+		`${windowName(window, fallback)}已用 ${Math.round(window.usedPercent)}%${window.resetAtMs ? `，${formatRecovery(window.resetAtMs, now)}重置` : ""}`;
+	if (usage.primary) parts.push(describe(usage.primary, "5 小时"));
+	if (usage.secondary) parts.push(describe(usage.secondary, "7 天"));
+	return parts.length > 0 ? parts.join("；") : undefined;
+}
+
+export function describeSoonestReady(input: { accounts: readonly PoolAccount[]; state: PoolStateFile; now: number; modelId?: string }): string | undefined {
+	const estimate = soonestReady(input);
+	if (!estimate) return undefined;
+	const account = input.accounts.find((candidate) => candidate.id === estimate.accountId);
+	return `最早可用：${formatRecovery(estimate.readyAtMs, input.now)}，${account ? accountLabel(account) : "某个账号"}`;
+}

package/packages/openai-account-pool/tests/command-completions.mjs

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+
+import { codexPoolArgumentCompletions } from "../src/command-completions.ts";
+
+assert.deepEqual(codexPoolArgumentCompletions("sta"), [{ value: "status", label: "status" }]);
+assert.deepEqual(codexPoolArgumentCompletions("status"), [], "an exact subcommand must let Enter submit immediately");
+assert.deepEqual(codexPoolArgumentCompletions("use"), [], "every exact subcommand must hide its identical completion");
+assert.deepEqual(codexPoolArgumentCompletions("use 2"), [], "account arguments are not subcommand completions");
+
+console.log("Command completion tests passed");