@victor-software-house/pi-multicodex 1.0.8 → 1.0.10

package/README.md

@@ -69,12 +69,59 @@ Current direction:
 
 Current next step:
 
-- make MultiCodex own the normal `openai-codex` path directly
-- auto-import pi's existing `openai-codex` auth when it is new or changed
-- mirror the existing codex usage footer style, including support for displaying both reset countdowns
-- show the active account identifier beside the 5h and 7d usage metrics
-- keep footer configuration in an interactive panel
-- tighten footer updates so account switches and quota rotation are reflected immediately
+- refine the footer color palette with small visual adjustments only
+- document the account-rotation behavior contract explicitly
+- improve the `/multicodex-use` and `/multicodex-status` everyday UX
+
+## Behavior contract
+
+The current runtime behavior is:
+
+### Account selection priority
+
+1. Use the manual account selected with `/multicodex-use` when it is still available.
+2. Otherwise clear the stale manual override and select the best available managed account.
+3. Best-account selection prefers:
+   - untouched accounts with usage data
+   - then the account whose weekly reset window ends first
+   - then a random available account as fallback
+
+### Quota exhaustion semantics
+
+- Quota and rate-limit style failures are detected from provider error text.
+- When a request fails before any output is streamed, MultiCodex marks that account exhausted and retries on another account.
+- Exhaustion lasts until the next known reset time.
+- If usage data does not provide a reset time, exhaustion falls back to a 1 hour cooldown.
+
+### Retry policy
+
+- MultiCodex retries account rotation up to 5 times for a single request.
+- Retries only happen for quota/rate-limit style failures that occur before output is forwarded.
+- Once output has started streaming, the original error is surfaced instead of rotating.
+
+### Manual override behavior
+
+- `/multicodex-use <identifier>` sets the manual account override immediately.
+- `/multicodex-use` with no argument opens the account picker and sets the selected manual override.
+- Manual override is session-local state.
+- Manual override clears automatically when the selected account is no longer available or when it hits quota during rotation.
+
+### Usage cache and refresh rules
+
+- Usage is cached in memory for 5 minutes per account.
+- Footer updates render cached usage immediately and refresh in the background when needed.
+- Rapid `model_select` changes debounce background refresh work so non-Codex model switching clears the footer immediately.
+
+### Error classification
+
+Quota rotation currently treats these error classes as interchangeable:
+
+- HTTP `429`
+- `quota`
+- `usage limit`
+- `rate limit`
+- `too many requests`
+- `limit reached`
 
 ## Release validation
 

package/account-manager.ts

@@ -18,6 +18,7 @@ const USAGE_REQUEST_TIMEOUT_MS = 10 * 1000;
 const QUOTA_COOLDOWN_MS = 60 * 60 * 1000;
 
 type WarningHandler = (message: string) => void;
+type StateChangeHandler = () => void;
 
 function getErrorMessage(error: unknown): string {
 	if (error instanceof Error) return error.message;
@@ -29,6 +30,7 @@ export class AccountManager {
 	private usageCache = new Map<string, CodexUsageSnapshot>();
 	private warningHandler?: WarningHandler;
 	private manualEmail?: string;
+	private stateChangeHandlers = new Set<StateChangeHandler>();
 
 	constructor() {
 		this.data = loadStorage();
@@ -38,6 +40,19 @@ export class AccountManager {
 		saveStorage(this.data);
 	}
 
+	private notifyStateChanged(): void {
+		for (const handler of this.stateChangeHandlers) {
+			handler();
+		}
+	}
+
+	onStateChange(handler: StateChangeHandler): () => void {
+		this.stateChangeHandlers.add(handler);
+		return () => {
+			this.stateChangeHandlers.delete(handler);
+		};
+	}
+
 	getAccounts(): Account[] {
 		return this.data.accounts;
 	}
@@ -82,7 +97,6 @@ export class AccountManager {
 			});
 		}
 		this.setActiveAccount(email);
-		this.save();
 	}
 
 	getActiveAccount(): Account | undefined {
@@ -111,6 +125,7 @@ export class AccountManager {
 	setActiveAccount(email: string): void {
 		this.data.activeEmail = email;
 		this.save();
+		this.notifyStateChanged();
 	}
 
 	setManualAccount(email: string): void {
@@ -118,10 +133,13 @@ export class AccountManager {
 		if (!account) return;
 		this.manualEmail = email;
 		account.lastUsed = Date.now();
+		this.notifyStateChanged();
 	}
 
 	clearManualAccount(): void {
+		if (!this.manualEmail) return;
 		this.manualEmail = undefined;
+		this.notifyStateChanged();
 	}
 
 	getImportedAccount(): Account | undefined {
@@ -173,6 +191,7 @@ export class AccountManager {
 		if (account) {
 			account.quotaExhaustedUntil = until;
 			this.save();
+			this.notifyStateChanged();
 		}
 	}
 
@@ -201,6 +220,7 @@ export class AccountManager {
 				timeoutMs: USAGE_REQUEST_TIMEOUT_MS,
 			});
 			this.usageCache.set(account.email, usage);
+			this.notifyStateChanged();
 			return usage;
 		} catch (error) {
 			this.warningHandler?.(
@@ -283,6 +303,7 @@ export class AccountManager {
 		}
 		if (changed) {
 			this.save();
+			this.notifyStateChanged();
 		}
 	}
 
@@ -301,6 +322,7 @@ export class AccountManager {
 			account.accountId = accountId;
 		}
 		this.save();
+		this.notifyStateChanged();
 		return account.accessToken;
 	}
 }

package/extension.ts

@@ -54,7 +54,7 @@ export default function multicodexExtension(pi: ExtensionAPI) {
 
 	pi.on("model_select", (_event: unknown, ctx: ExtensionContext) => {
 		lastContext = ctx;
-		void statusController.refreshFor(ctx);
+		statusController.scheduleModelSelectRefresh(ctx);
 	});
 
 	pi.on("session_shutdown", (_event: unknown, ctx: ExtensionContext) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@victor-software-house/pi-multicodex",
-	"version": "1.0.8",
+	"version": "1.0.10",
 	"description": "Codex account rotation extension for pi",
 	"license": "MIT",
 	"type": "module",

package/status.ts

@@ -21,7 +21,9 @@ const STATUS_KEY = "multicodex-usage";
 const SETTINGS_KEY = "pi-multicodex";
 const SETTINGS_FILE = path.join(os.homedir(), ".pi", "agent", "settings.json");
 const REFRESH_INTERVAL_MS = 60_000;
+const MODEL_SELECT_REFRESH_DEBOUNCE_MS = 250;
 const UNKNOWN_PERCENT = "--";
+const BRAND_LABEL = "Codex";
 const FIVE_HOUR_LABEL = "5h:";
 const SEVEN_DAY_LABEL = "7d:";
 
@@ -138,13 +140,21 @@ function usedToDisplayPercent(
 	return mode === "left" ? left : clampPercent(100 - left);
 }
 
+function formatBrand(ctx: ExtensionContext): string {
+	return ctx.ui.theme.fg("muted", BRAND_LABEL);
+}
+
+function formatLoading(ctx: ExtensionContext): string {
+	return ctx.ui.theme.fg("muted", "loading...");
+}
+
 function formatPercent(
 	ctx: ExtensionContext,
 	displayPercent: number | undefined,
 	mode: PercentDisplayMode,
 ): string {
 	if (typeof displayPercent !== "number" || Number.isNaN(displayPercent)) {
-		return ctx.ui.theme.fg("muted", UNKNOWN_PERCENT);
+		return ctx.ui.theme.fg("dim", UNKNOWN_PERCENT);
 	}
 
 	const text = `${Math.round(clampPercent(displayPercent))}% ${mode}`;
@@ -172,6 +182,40 @@ function formatResetCountdown(resetAt: number | undefined): string | undefined {
 	return `${seconds}s`;
 }
 
+function shouldShowReset(
+	preferences: FooterPreferences,
+	window: Exclude<ResetWindowMode, "both">,
+): boolean {
+	if (!preferences.showReset) return false;
+	return (
+		preferences.resetWindow === "both" || preferences.resetWindow === window
+	);
+}
+
+function formatUsageSegment(
+	ctx: ExtensionContext,
+	label: string,
+	usedPercent: number | undefined,
+	resetAt: number | undefined,
+	showReset: boolean,
+	preferences: FooterPreferences,
+): string {
+	const parts = [
+		`${ctx.ui.theme.fg("dim", label)}${formatPercent(
+			ctx,
+			usedToDisplayPercent(usedPercent, preferences.usageMode),
+			preferences.usageMode,
+		)}`,
+	];
+	if (showReset) {
+		const countdown = formatResetCountdown(resetAt);
+		if (countdown) {
+			parts.push(ctx.ui.theme.fg("muted", `(↺${countdown})`));
+		}
+	}
+	return parts.join(" ");
+}
+
 export function isManagedModel(model: MaybeModel): boolean {
 	return model?.provider === PROVIDER_ID;
 }
@@ -186,59 +230,36 @@ export function formatActiveAccountStatus(
 		? ctx.ui.theme.fg("muted", accountEmail)
 		: undefined;
 	if (!usage) {
-		return [
-			ctx.ui.theme.fg("dim", "Codex"),
-			accountText,
-			ctx.ui.theme.fg("dim", "loading..."),
-		]
+		return [formatBrand(ctx), accountText, formatLoading(ctx)]
 			.filter(Boolean)
 			.join(" ");
 	}
 
-	const fiveHour = `${ctx.ui.theme.fg("dim", FIVE_HOUR_LABEL)}${formatPercent(
+	const fiveHour = formatUsageSegment(
 		ctx,
-		usedToDisplayPercent(usage.primary?.usedPercent, preferences.usageMode),
-		preferences.usageMode,
-	)}`;
-	const sevenDay = `${ctx.ui.theme.fg("dim", SEVEN_DAY_LABEL)}${formatPercent(
+		FIVE_HOUR_LABEL,
+		usage.primary?.usedPercent,
+		usage.primary?.resetAt,
+		shouldShowReset(preferences, "5h"),
+		preferences,
+	);
+	const sevenDay = formatUsageSegment(
 		ctx,
-		usedToDisplayPercent(usage.secondary?.usedPercent, preferences.usageMode),
-		preferences.usageMode,
-	)}`;
-	const fiveHourReset = preferences.showReset
-		? formatResetCountdown(usage.primary?.resetAt)
-		: undefined;
-	const sevenDayReset = preferences.showReset
-		? formatResetCountdown(usage.secondary?.resetAt)
-		: undefined;
-	const resetText =
-		preferences.resetWindow === "5h"
-			? fiveHourReset
-				? ctx.ui.theme.fg("dim", `(${FIVE_HOUR_LABEL}↺${fiveHourReset})`)
-				: undefined
-			: preferences.resetWindow === "7d"
-				? sevenDayReset
-					? ctx.ui.theme.fg("dim", `(${SEVEN_DAY_LABEL}↺${sevenDayReset})`)
-					: undefined
-				: [
-						fiveHourReset
-							? ctx.ui.theme.fg("dim", `(${FIVE_HOUR_LABEL}↺${fiveHourReset})`)
-							: undefined,
-						sevenDayReset
-							? ctx.ui.theme.fg("dim", `(${SEVEN_DAY_LABEL}↺${sevenDayReset})`)
-							: undefined,
-					]
-						.filter(Boolean)
-						.join(" ") || undefined;
+		SEVEN_DAY_LABEL,
+		usage.secondary?.usedPercent,
+		usage.secondary?.resetAt,
+		shouldShowReset(preferences, "7d"),
+		preferences,
+	);
 
 	const leading =
 		preferences.order === "account-first"
-			? [ctx.ui.theme.fg("dim", "Codex"), accountText]
-			: [ctx.ui.theme.fg("dim", "Codex")];
+			? [formatBrand(ctx), accountText]
+			: [formatBrand(ctx)];
 	const trailing =
 		preferences.order === "account-first" ? [] : [accountText].filter(Boolean);
 
-	return [...leading, fiveHour, sevenDay, resetText, ...trailing]
+	return [...leading, fiveHour, sevenDay, ...trailing]
 		.filter(Boolean)
 		.join(" ");
 }
@@ -315,10 +336,17 @@ function applyPreferenceChange(
 
 export function createUsageStatusController(accountManager: AccountManager) {
 	let refreshTimer: ReturnType<typeof setInterval> | undefined;
+	let modelSelectTimer: ReturnType<typeof setTimeout> | undefined;
 	let activeContext: ExtensionContext | undefined;
 	let refreshInFlight = false;
 	let queuedRefresh = false;
 	let preferences: FooterPreferences = DEFAULT_PREFERENCES;
+	let livePreviewPreferences: FooterPreferences | undefined;
+
+	accountManager.onStateChange(() => {
+		if (!activeContext) return;
+		renderCachedStatus(activeContext, livePreviewPreferences ?? preferences);
+	});
 
 	function clearStatus(ctx?: ExtensionContext): void {
 		ctx?.ui.setStatus(STATUS_KEY, undefined);
@@ -328,6 +356,42 @@ export function createUsageStatusController(accountManager: AccountManager) {
 		preferences = await loadFooterPreferences();
 	}
 
+	function getStatusText(
+		ctx: ExtensionContext,
+		preferencesOverride?: FooterPreferences,
+	): string | undefined {
+		if (!ctx.hasUI) return undefined;
+		if (!isManagedModel(ctx.model)) return undefined;
+
+		const activeAccount = accountManager.getActiveAccount();
+		if (!activeAccount) {
+			return ctx.ui.theme.fg("warning", "Multicodex no active account");
+		}
+
+		return formatActiveAccountStatus(
+			ctx,
+			activeAccount.email,
+			accountManager.getCachedUsage(activeAccount.email),
+			preferencesOverride ?? preferences,
+		);
+	}
+
+	function renderCachedStatus(
+		ctx: ExtensionContext,
+		preferencesOverride?: FooterPreferences,
+	): void {
+		if (!ctx.hasUI) return;
+		if (!isManagedModel(ctx.model)) {
+			clearStatus(ctx);
+			return;
+		}
+
+		const text = getStatusText(ctx, preferencesOverride);
+		if (text) {
+			ctx.ui.setStatus(STATUS_KEY, text);
+		}
+	}
+
 	async function updateStatus(ctx: ExtensionContext): Promise<void> {
 		if (!ctx.hasUI) return;
 		if (!isManagedModel(ctx.model)) {
@@ -335,6 +399,8 @@ export function createUsageStatusController(accountManager: AccountManager) {
 			return;
 		}
 
+		renderCachedStatus(ctx, livePreviewPreferences ?? preferences);
+
 		let activeAccount = accountManager.getActiveAccount();
 		if (!activeAccount) {
 			await accountManager.syncImportedOpenAICodexAuth();
@@ -354,7 +420,12 @@ export function createUsageStatusController(accountManager: AccountManager) {
 			cachedUsage;
 		ctx.ui.setStatus(
 			STATUS_KEY,
-			formatActiveAccountStatus(ctx, activeAccount.email, usage, preferences),
+			formatActiveAccountStatus(
+				ctx,
+				activeAccount.email,
+				usage,
+				livePreviewPreferences ?? preferences,
+			),
 		);
 	}
 
@@ -377,6 +448,19 @@ export function createUsageStatusController(accountManager: AccountManager) {
 		}
 	}
 
+	function scheduleModelSelectRefresh(ctx: ExtensionContext): void {
+		activeContext = ctx;
+		renderCachedStatus(ctx, livePreviewPreferences ?? preferences);
+		if (modelSelectTimer) {
+			clearTimeout(modelSelectTimer);
+		}
+		modelSelectTimer = setTimeout(() => {
+			modelSelectTimer = undefined;
+			void refreshFor(ctx);
+		}, MODEL_SELECT_REFRESH_DEBOUNCE_MS);
+		modelSelectTimer.unref?.();
+	}
+
 	function startAutoRefresh(): void {
 		if (refreshTimer) clearInterval(refreshTimer);
 		refreshTimer = setInterval(() => {
@@ -391,6 +475,11 @@ export function createUsageStatusController(accountManager: AccountManager) {
 			clearInterval(refreshTimer);
 			refreshTimer = undefined;
 		}
+		if (modelSelectTimer) {
+			clearTimeout(modelSelectTimer);
+			modelSelectTimer = undefined;
+		}
+		livePreviewPreferences = undefined;
 		clearStatus(ctx ?? activeContext);
 		activeContext = undefined;
 		queuedRefresh = false;
@@ -408,11 +497,23 @@ export function createUsageStatusController(accountManager: AccountManager) {
 		}
 	}
 
+	function renderPreviewLabel(
+		ctx: ExtensionContext,
+		theme: ExtensionCommandContext["ui"]["theme"],
+		draft: FooterPreferences,
+	): string {
+		const previewText =
+			getStatusText(ctx, draft) ?? `${formatBrand(ctx)} ${formatLoading(ctx)}`;
+		return `${theme.fg("dim", "Preview")}: ${previewText}`;
+	}
+
 	async function openPreferencesPanel(
 		ctx: ExtensionCommandContext,
 	): Promise<void> {
 		await loadPreferences(ctx);
 		let draft = preferences;
+		livePreviewPreferences = draft;
+		renderCachedStatus(ctx, livePreviewPreferences);
 
 		await ctx.ui.custom((_tui, theme, _kb, done) => {
 			const container = new Container();
@@ -429,14 +530,20 @@ export function createUsageStatusController(accountManager: AccountManager) {
 					0,
 				),
 			);
+			const previewText = new Text(renderPreviewLabel(ctx, theme, draft), 1, 0);
+			container.addChild(previewText);
 
 			const settingsList = new SettingsList(
 				createSettingsItems(draft),
-				7,
+				9,
 				getSettingsListTheme(),
 				(id: string, newValue: string) => {
 					draft = applyPreferenceChange(draft, id, newValue);
+					livePreviewPreferences = draft;
 					settingsList.updateValue(id, newValue);
+					previewText.setText(renderPreviewLabel(ctx, theme, draft));
+					container.invalidate();
+					renderCachedStatus(ctx, draft);
 				},
 				() => done(undefined),
 				{ enableSearch: true },
@@ -451,6 +558,7 @@ export function createUsageStatusController(accountManager: AccountManager) {
 		});
 
 		preferences = draft;
+		livePreviewPreferences = undefined;
 		await persistFooterPreferences(preferences);
 		await refreshFor(ctx);
 	}
@@ -459,6 +567,7 @@ export function createUsageStatusController(accountManager: AccountManager) {
 		loadPreferences,
 		openPreferencesPanel,
 		refreshFor,
+		scheduleModelSelectRefresh,
 		startAutoRefresh,
 		stopAutoRefresh,
 		getPreferences: () => preferences,