@victor-software-house/pi-multicodex 1.0.9 → 1.0.11

package/README.md

@@ -69,11 +69,59 @@ Current direction:
 
 Current next step:
 
-- mirror the existing codex usage footer style, including support for displaying both reset countdowns
-- debounce expensive refresh work during rapid model cycling
-- move each reset countdown next to its matching usage period
-- add live preview to the `/multicodex-footer` panel before locking the final style
-- 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/package.json

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

package/status.ts

@@ -23,6 +23,8 @@ 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 SEGMENT_SEPARATOR = "·";
 const FIVE_HOUR_LABEL = "5h:";
 const SEVEN_DAY_LABEL = "7d:";
 
@@ -139,25 +141,48 @@ function usedToDisplayPercent(
 	return mode === "left" ? left : clampPercent(100 - left);
 }
 
-function formatPercent(
-	ctx: ExtensionContext,
+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 formatSeparator(ctx: ExtensionContext): string {
+	return ctx.ui.theme.fg("muted", SEGMENT_SEPARATOR);
+}
+
+function getUsageSeverityToken(
 	displayPercent: number | undefined,
 	mode: PercentDisplayMode,
-): string {
+): "success" | "thinkingMedium" | "warning" | "error" | "dim" {
 	if (typeof displayPercent !== "number" || Number.isNaN(displayPercent)) {
-		return ctx.ui.theme.fg("muted", UNKNOWN_PERCENT);
+		return "dim";
 	}
 
-	const text = `${Math.round(clampPercent(displayPercent))}% ${mode}`;
 	if (mode === "left") {
-		if (displayPercent <= 10) return ctx.ui.theme.fg("error", text);
-		if (displayPercent <= 25) return ctx.ui.theme.fg("warning", text);
-		return ctx.ui.theme.fg("success", text);
+		if (displayPercent <= 10) return "error";
+		if (displayPercent <= 25) return "warning";
+		if (displayPercent <= 50) return "thinkingMedium";
+		return "success";
 	}
 
-	if (displayPercent >= 90) return ctx.ui.theme.fg("error", text);
-	if (displayPercent >= 75) return ctx.ui.theme.fg("warning", text);
-	return ctx.ui.theme.fg("success", text);
+	if (displayPercent >= 90) return "error";
+	if (displayPercent >= 75) return "warning";
+	if (displayPercent >= 50) return "thinkingMedium";
+	return "success";
+}
+
+function formatPercent(
+	displayPercent: number | undefined,
+	mode: PercentDisplayMode,
+): string {
+	if (typeof displayPercent !== "number" || Number.isNaN(displayPercent)) {
+		return UNKNOWN_PERCENT;
+	}
+
+	return `${Math.round(clampPercent(displayPercent))}% ${mode}`;
 }
 
 function formatResetCountdown(resetAt: number | undefined): string | undefined {
@@ -191,20 +216,23 @@ function formatUsageSegment(
 	showReset: boolean,
 	preferences: FooterPreferences,
 ): string {
+	const displayPercent = usedToDisplayPercent(
+		usedPercent,
+		preferences.usageMode,
+	);
 	const parts = [
-		`${ctx.ui.theme.fg("dim", label)}${formatPercent(
-			ctx,
-			usedToDisplayPercent(usedPercent, preferences.usageMode),
-			preferences.usageMode,
-		)}`,
+		`${label}${formatPercent(displayPercent, preferences.usageMode)}`,
 	];
 	if (showReset) {
 		const countdown = formatResetCountdown(resetAt);
 		if (countdown) {
-			parts.push(ctx.ui.theme.fg("dim", `(↺${countdown})`));
+			parts.push(`(↺${countdown})`);
 		}
 	}
-	return parts.join(" ");
+	return ctx.ui.theme.fg(
+		getUsageSeverityToken(displayPercent, preferences.usageMode),
+		parts.join(" "),
+	);
 }
 
 export function isManagedModel(model: MaybeModel): boolean {
@@ -218,14 +246,10 @@ export function formatActiveAccountStatus(
 	preferences: FooterPreferences,
 ): string {
 	const accountText = preferences.showAccount
-		? ctx.ui.theme.fg("muted", accountEmail)
+		? ctx.ui.theme.fg("text", 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(" ");
 	}
@@ -247,16 +271,18 @@ export function formatActiveAccountStatus(
 		preferences,
 	);
 
+	const usageSegments = [fiveHour, sevenDay].filter(Boolean);
+	const usageText = usageSegments.join(` ${formatSeparator(ctx)} `);
 	const leading =
 		preferences.order === "account-first"
-			? [ctx.ui.theme.fg("dim", "Codex"), accountText]
-			: [ctx.ui.theme.fg("dim", "Codex")];
+			? [formatBrand(ctx), accountText, usageText]
+			: [formatBrand(ctx), usageText];
 	const trailing =
 		preferences.order === "account-first" ? [] : [accountText].filter(Boolean);
 
-	return [...leading, fiveHour, sevenDay, ...trailing]
+	return [...leading, ...trailing]
 		.filter(Boolean)
-		.join(" ");
+		.join(` ${formatSeparator(ctx)} `);
 }
 
 function getBooleanLabel(value: boolean): string {
@@ -498,7 +524,7 @@ export function createUsageStatusController(accountManager: AccountManager) {
 		draft: FooterPreferences,
 	): string {
 		const previewText =
-			getStatusText(ctx, draft) ?? ctx.ui.theme.fg("dim", "Codex loading...");
+			getStatusText(ctx, draft) ?? `${formatBrand(ctx)} ${formatLoading(ctx)}`;
 		return `${theme.fg("dim", "Preview")}: ${previewText}`;
 	}