@victor-software-house/pi-multicodex 1.0.3 → 1.0.6

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 kim0
+Copyright (c) 2026 Victor Software House
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,14 +2,14 @@
 
 ![MultiCodex](./assets/multicodex.png)
 
-`@victor-software-house/pi-multicodex` is a pi extension for rotating multiple ChatGPT Codex OAuth accounts when using the `openai-codex-responses` API.
+`@victor-software-house/pi-multicodex` is a pi extension that rotates multiple ChatGPT Codex OAuth accounts for the `openai-codex-responses` API.
 
-Current behavior:
+## What it does
 
-- rotates on quota and rate-limit failures
+- rotates accounts on quota and rate-limit failures
 - prefers untouched accounts when usage data is available
 - otherwise prefers the account whose weekly window resets first
-- stays focused on Codex only
+- keeps the implementation focused on Codex account rotation
 
 ## Install
 
@@ -21,7 +21,7 @@ Restart `pi` after installation.
 
 ## Local development
 
-This repo uses `mise` to pin tool versions and `pnpm` for dependency management.
+This repo uses `mise` to pin tools and `pnpm` for dependency management.
 
 ```bash
 mise install
@@ -51,21 +51,31 @@ pi -e ./index.ts
   - Select an account manually for the current session.
 - `/multicodex-status`
   - Show account state and cached usage information.
+- `/multicodex-footer`
+  - Open an interactive panel to configure footer fields and ordering.
 
-## Status
+## Project direction
 
-This package is being turned into an independent fork with deliberate breaking changes.
+This project is maintained as its own package and release line.
 
 Current direction:
 
 - package name: `@victor-software-house/pi-multicodex`
-- hard break from previous storage compatibility
 - Codex-only scope
-- independent implementation roadmap tracked in `fork-plan.md`
+- local state stored at `~/.pi/agent/codex-accounts.json`
+- internal logic split into focused modules
+- current roadmap tracked in `ROADMAP.md`
 
-## Release validation
+Current next step:
+
+- add active-account usage visibility in pi for this extension's managed Codex accounts
+- mirror the existing codex usage footer style, including support for displaying both reset countdowns
+- show footer usage only when the selected model uses the `multicodex` provider override
+- show the active account identifier beside the 5h and 7d usage metrics
+- configure footer fields and ordering through an interactive panel
+- refresh the footer from the active managed account without polling aggressively
 
-Local development uses pnpm, but published package output must remain npm-compatible.
+## Release validation
 
 Minimum release checks:
 
@@ -74,22 +84,34 @@ pnpm check
 npm pack --dry-run
 ```
 
-Recommended release flow:
+Release flow:
 
-1. For the first publish of a brand-new package, publish manually from a trusted local machine.
-2. After the package exists on npm, configure npm trusted publishing for `.github/workflows/publish.yml`.
-3. Publish subsequent releases by pushing a matching `v*` git tag.
+1. Prepare the release locally.
+2. Commit the version bump.
+3. Create and push a matching `v*` tag.
+4. Let GitHub Actions publish through trusted publishing.
 
-Bootstrap publish:
+Prepare locally:
 
 ```bash
-npm run publish:dry -- <version>
-npm publish --access public --otp=<code>
+npm run release:prepare -- <version>
 ```
 
-Trusted publishing flow after bootstrap:
+The helper updates `package.json` with `bun pm pkg set` and then runs the release checks.
+
+Example:
 
 ```bash
+git add package.json
+git commit -m "release: v<version>"
 git tag v<version>
-git push origin v<version>
+git push origin main --tags
 ```
+
+Do not use local `npm publish` for normal releases in this repo.
+
+## Acknowledgment
+
+This project descends from earlier MultiCodex work. Thanks to the original creator for the starting point that made this package possible.
+
+The active-account usage footer work also draws on ideas from `calesennett/pi-codex-usage`. Thanks to its author for the reference implementation and footer design.

package/abort-utils.ts

@@ -0,0 +1,24 @@
+export function createLinkedAbortController(
+	signal?: AbortSignal,
+): AbortController {
+	const controller = new AbortController();
+	if (signal?.aborted) {
+		controller.abort();
+		return controller;
+	}
+
+	signal?.addEventListener("abort", () => controller.abort(), { once: true });
+	return controller;
+}
+
+export function createTimeoutController(
+	signal: AbortSignal | undefined,
+	timeoutMs: number,
+): { controller: AbortController; clear: () => void } {
+	const controller = createLinkedAbortController(signal);
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	return {
+		controller,
+		clear: () => clearTimeout(timeout),
+	};
+}

package/account-manager.ts

@@ -0,0 +1,262 @@
+import {
+	type OAuthCredentials,
+	refreshOpenAICodexToken,
+} from "@mariozechner/pi-ai/oauth";
+import { isAccountAvailable, pickBestAccount } from "./selection";
+import {
+	type Account,
+	loadStorage,
+	type StorageData,
+	saveStorage,
+} from "./storage";
+import { type CodexUsageSnapshot, getNextResetAt } from "./usage";
+import { fetchCodexUsage } from "./usage-client";
+
+const USAGE_CACHE_TTL_MS = 5 * 60 * 1000;
+const USAGE_REQUEST_TIMEOUT_MS = 10 * 1000;
+const QUOTA_COOLDOWN_MS = 60 * 60 * 1000;
+
+type WarningHandler = (message: string) => void;
+
+function getErrorMessage(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	return typeof error === "string" ? error : JSON.stringify(error);
+}
+
+export class AccountManager {
+	private data: StorageData;
+	private usageCache = new Map<string, CodexUsageSnapshot>();
+	private warningHandler?: WarningHandler;
+	private manualEmail?: string;
+
+	constructor() {
+		this.data = loadStorage();
+	}
+
+	private save(): void {
+		saveStorage(this.data);
+	}
+
+	getAccounts(): Account[] {
+		return this.data.accounts;
+	}
+
+	getAccount(email: string): Account | undefined {
+		return this.data.accounts.find((a) => a.email === email);
+	}
+
+	setWarningHandler(handler?: WarningHandler): void {
+		this.warningHandler = handler;
+	}
+
+	addOrUpdateAccount(email: string, creds: OAuthCredentials): void {
+		const existing = this.getAccount(email);
+		const accountId =
+			typeof creds.accountId === "string" ? creds.accountId : undefined;
+		if (existing) {
+			existing.accessToken = creds.access;
+			existing.refreshToken = creds.refresh;
+			existing.expiresAt = creds.expires;
+			if (accountId) {
+				existing.accountId = accountId;
+			}
+		} else {
+			this.data.accounts.push({
+				email,
+				accessToken: creds.access,
+				refreshToken: creds.refresh,
+				expiresAt: creds.expires,
+				accountId,
+			});
+		}
+		this.setActiveAccount(email);
+		this.save();
+	}
+
+	getActiveAccount(): Account | undefined {
+		const manual = this.getManualAccount();
+		if (manual) return manual;
+		if (this.data.activeEmail) {
+			return this.getAccount(this.data.activeEmail);
+		}
+		return this.data.accounts[0];
+	}
+
+	getManualAccount(): Account | undefined {
+		if (!this.manualEmail) return undefined;
+		const account = this.getAccount(this.manualEmail);
+		if (!account) {
+			this.manualEmail = undefined;
+			return undefined;
+		}
+		return account;
+	}
+
+	hasManualAccount(): boolean {
+		return Boolean(this.manualEmail);
+	}
+
+	setActiveAccount(email: string): void {
+		this.data.activeEmail = email;
+		this.save();
+	}
+
+	setManualAccount(email: string): void {
+		const account = this.getAccount(email);
+		if (!account) return;
+		this.manualEmail = email;
+		account.lastUsed = Date.now();
+	}
+
+	clearManualAccount(): void {
+		this.manualEmail = undefined;
+	}
+
+	getAvailableManualAccount(options?: {
+		excludeEmails?: Set<string>;
+		now?: number;
+	}): Account | undefined {
+		const manual = this.getManualAccount();
+		if (!manual) return undefined;
+		const now = options?.now ?? Date.now();
+		if (!isAccountAvailable(manual, now)) return undefined;
+		if (options?.excludeEmails?.has(manual.email)) return undefined;
+		return manual;
+	}
+
+	markExhausted(email: string, until: number): void {
+		const account = this.getAccount(email);
+		if (account) {
+			account.quotaExhaustedUntil = until;
+			this.save();
+		}
+	}
+
+	getCachedUsage(email: string): CodexUsageSnapshot | undefined {
+		return this.usageCache.get(email);
+	}
+
+	async refreshUsageForAccount(
+		account: Account,
+		options?: { force?: boolean; signal?: AbortSignal },
+	): Promise<CodexUsageSnapshot | undefined> {
+		const cached = this.usageCache.get(account.email);
+		const now = Date.now();
+		if (
+			cached &&
+			!options?.force &&
+			now - cached.fetchedAt < USAGE_CACHE_TTL_MS
+		) {
+			return cached;
+		}
+
+		try {
+			const token = await this.ensureValidToken(account);
+			const usage = await fetchCodexUsage(token, account.accountId, {
+				signal: options?.signal,
+				timeoutMs: USAGE_REQUEST_TIMEOUT_MS,
+			});
+			this.usageCache.set(account.email, usage);
+			return usage;
+		} catch (error) {
+			this.warningHandler?.(
+				`Multicodex: failed to fetch usage for ${account.email}: ${getErrorMessage(
+					error,
+				)}`,
+			);
+			return undefined;
+		}
+	}
+
+	async refreshUsageForAllAccounts(options?: {
+		force?: boolean;
+		signal?: AbortSignal;
+	}): Promise<void> {
+		const accounts = this.getAccounts();
+		await Promise.all(
+			accounts.map((account) => this.refreshUsageForAccount(account, options)),
+		);
+	}
+
+	async refreshUsageIfStale(
+		accounts: Account[],
+		options?: { signal?: AbortSignal },
+	): Promise<void> {
+		const now = Date.now();
+		const stale = accounts.filter((account) => {
+			const cached = this.usageCache.get(account.email);
+			return !cached || now - cached.fetchedAt >= USAGE_CACHE_TTL_MS;
+		});
+		if (stale.length === 0) return;
+		await Promise.all(
+			stale.map((account) =>
+				this.refreshUsageForAccount(account, { force: true, ...options }),
+			),
+		);
+	}
+
+	async activateBestAccount(options?: {
+		excludeEmails?: Set<string>;
+		signal?: AbortSignal;
+	}): Promise<Account | undefined> {
+		const now = Date.now();
+		this.clearExpiredExhaustion(now);
+		const accounts = this.data.accounts;
+		await this.refreshUsageIfStale(accounts, options);
+
+		const selected = pickBestAccount(accounts, this.usageCache, {
+			excludeEmails: options?.excludeEmails,
+			now,
+		});
+		if (selected) {
+			this.setActiveAccount(selected.email);
+		}
+		return selected;
+	}
+
+	async handleQuotaExceeded(
+		account: Account,
+		options?: { signal?: AbortSignal },
+	): Promise<void> {
+		const usage = await this.refreshUsageForAccount(account, {
+			force: true,
+			signal: options?.signal,
+		});
+		const now = Date.now();
+		const resetAt = getNextResetAt(usage);
+		const fallback = now + QUOTA_COOLDOWN_MS;
+		const until = resetAt && resetAt > now ? resetAt : fallback;
+		this.markExhausted(account.email, until);
+	}
+
+	private clearExpiredExhaustion(now: number): void {
+		let changed = false;
+		for (const account of this.data.accounts) {
+			if (account.quotaExhaustedUntil && account.quotaExhaustedUntil <= now) {
+				account.quotaExhaustedUntil = undefined;
+				changed = true;
+			}
+		}
+		if (changed) {
+			this.save();
+		}
+	}
+
+	async ensureValidToken(account: Account): Promise<string> {
+		if (Date.now() < account.expiresAt - 5 * 60 * 1000) {
+			return account.accessToken;
+		}
+
+		const result = await refreshOpenAICodexToken(account.refreshToken);
+		account.accessToken = result.access;
+		account.refreshToken = result.refresh;
+		account.expiresAt = result.expires;
+		const accountId =
+			typeof result.accountId === "string" ? result.accountId : undefined;
+		if (accountId) {
+			account.accountId = accountId;
+		}
+		this.save();
+		return account.accessToken;
+	}
+}

package/browser.ts

@@ -0,0 +1,34 @@
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+
+export async function openLoginInBrowser(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	url: string,
+): Promise<void> {
+	let command: string;
+	let args: string[];
+
+	if (process.platform === "darwin") {
+		command = "open";
+		args = [url];
+	} else if (process.platform === "win32") {
+		command = "cmd";
+		args = ["/c", "start", "", url];
+	} else {
+		command = "xdg-open";
+		args = [url];
+	}
+
+	try {
+		await pi.exec(command, args);
+	} catch (error) {
+		ctx.ui.notify(
+			"Could not open a browser automatically. Please open the login URL manually.",
+			"warning",
+		);
+		console.warn("[multicodex] Failed to open browser:", error);
+	}
+}

package/commands.ts

@@ -0,0 +1,150 @@
+import { loginOpenAICodex } from "@mariozechner/pi-ai/oauth";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import type { AccountManager } from "./account-manager";
+import { openLoginInBrowser } from "./browser";
+import type { createUsageStatusController } from "./status";
+import { formatResetAt, isUsageUntouched } from "./usage";
+
+function getErrorMessage(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	return typeof error === "string" ? error : JSON.stringify(error);
+}
+
+export function registerCommands(
+	pi: ExtensionAPI,
+	accountManager: AccountManager,
+	statusController: ReturnType<typeof createUsageStatusController>,
+): void {
+	pi.registerCommand("multicodex-login", {
+		description: "Login to an OpenAI Codex account for the rotation pool",
+		handler: async (
+			args: string,
+			ctx: ExtensionCommandContext,
+		): Promise<void> => {
+			const email = args.trim();
+			if (!email) {
+				ctx.ui.notify(
+					"Please provide an email/identifier: /multicodex-login my@email.com",
+					"error",
+				);
+				return;
+			}
+
+			try {
+				ctx.ui.notify(
+					`Starting login for ${email}... Check your browser.`,
+					"info",
+				);
+
+				const creds = await loginOpenAICodex({
+					onAuth: ({ url }) => {
+						void openLoginInBrowser(pi, ctx, url);
+						ctx.ui.notify(`Please open this URL to login: ${url}`, "info");
+						console.log(`[multicodex] Login URL: ${url}`);
+					},
+					onPrompt: async ({ message }) => (await ctx.ui.input(message)) || "",
+				});
+
+				accountManager.addOrUpdateAccount(email, creds);
+				ctx.ui.notify(`Successfully logged in as ${email}`, "info");
+			} catch (error) {
+				ctx.ui.notify(`Login failed: ${getErrorMessage(error)}`, "error");
+			}
+		},
+	});
+
+	pi.registerCommand("multicodex-use", {
+		description: "Switch active Codex account for this session",
+		handler: async (
+			_args: string,
+			ctx: ExtensionCommandContext,
+		): Promise<void> => {
+			const accounts = accountManager.getAccounts();
+			if (accounts.length === 0) {
+				ctx.ui.notify(
+					"No accounts logged in. Use /multicodex-login first.",
+					"warning",
+				);
+				return;
+			}
+
+			const options = accounts.map(
+				(account) =>
+					account.email +
+					(account.quotaExhaustedUntil &&
+					account.quotaExhaustedUntil > Date.now()
+						? " (Quota)"
+						: ""),
+			);
+			const selected = await ctx.ui.select("Select Account", options);
+			if (!selected) return;
+
+			const email = selected.split(" ")[0];
+			accountManager.setManualAccount(email);
+			ctx.ui.notify(`Switched to ${email}`, "info");
+		},
+	});
+
+	pi.registerCommand("multicodex-status", {
+		description: "Show all Codex accounts and active status",
+		handler: async (
+			_args: string,
+			ctx: ExtensionCommandContext,
+		): Promise<void> => {
+			await accountManager.refreshUsageForAllAccounts();
+			const accounts = accountManager.getAccounts();
+			if (accounts.length === 0) {
+				ctx.ui.notify(
+					"No accounts logged in. Use /multicodex-login first.",
+					"warning",
+				);
+				return;
+			}
+
+			const active = accountManager.getActiveAccount();
+			const options = accounts.map((account) => {
+				const usage = accountManager.getCachedUsage(account.email);
+				const isActive = active?.email === account.email;
+				const quotaHit =
+					account.quotaExhaustedUntil &&
+					account.quotaExhaustedUntil > Date.now();
+				const untouched = isUsageUntouched(usage) ? "untouched" : null;
+				const tags = [
+					isActive ? "active" : null,
+					quotaHit ? "quota" : null,
+					untouched,
+				]
+					.filter(Boolean)
+					.join(", ");
+				const suffix = tags ? ` (${tags})` : "";
+				const primaryUsed = usage?.primary?.usedPercent;
+				const secondaryUsed = usage?.secondary?.usedPercent;
+				const primaryReset = usage?.primary?.resetAt;
+				const secondaryReset = usage?.secondary?.resetAt;
+				const primaryLabel =
+					primaryUsed === undefined ? "unknown" : `${Math.round(primaryUsed)}%`;
+				const secondaryLabel =
+					secondaryUsed === undefined
+						? "unknown"
+						: `${Math.round(secondaryUsed)}%`;
+				const usageSummary = `5h ${primaryLabel} reset:${formatResetAt(primaryReset)} | weekly ${secondaryLabel} reset:${formatResetAt(secondaryReset)}`;
+				return `${isActive ? "•" : " "} ${account.email}${suffix} - ${usageSummary}`;
+			});
+
+			await ctx.ui.select("MultiCodex Accounts", options);
+		},
+	});
+
+	pi.registerCommand("multicodex-footer", {
+		description: "Configure the MultiCodex usage footer",
+		handler: async (
+			_args: string,
+			ctx: ExtensionCommandContext,
+		): Promise<void> => {
+			await statusController.openPreferencesPanel(ctx);
+		},
+	});
+}

package/extension.ts

@@ -0,0 +1,63 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+import { AccountManager } from "./account-manager";
+import { registerCommands } from "./commands";
+import { handleNewSessionSwitch, handleSessionStart } from "./hooks";
+import { buildMulticodexProviderConfig, PROVIDER_ID } from "./provider";
+import { createUsageStatusController } from "./status";
+
+export default function multicodexExtension(pi: ExtensionAPI) {
+	const accountManager = new AccountManager();
+	const statusController = createUsageStatusController(accountManager);
+	let lastContext: ExtensionContext | undefined;
+
+	accountManager.setWarningHandler((message) => {
+		if (lastContext) {
+			lastContext.ui.notify(message, "warning");
+		}
+	});
+
+	pi.registerProvider(
+		PROVIDER_ID,
+		buildMulticodexProviderConfig(accountManager),
+	);
+
+	registerCommands(pi, accountManager, statusController);
+
+	pi.on("session_start", (_event: unknown, ctx: ExtensionContext) => {
+		lastContext = ctx;
+		handleSessionStart(accountManager);
+		statusController.startAutoRefresh();
+		void (async () => {
+			await statusController.loadPreferences(ctx);
+			await statusController.refreshFor(ctx);
+		})();
+	});
+
+	pi.on(
+		"session_switch",
+		(event: { reason?: string }, ctx: ExtensionContext) => {
+			lastContext = ctx;
+			if (event.reason === "new") {
+				handleNewSessionSwitch(accountManager);
+			}
+			void statusController.refreshFor(ctx);
+		},
+	);
+
+	pi.on("turn_end", (_event: unknown, ctx: ExtensionContext) => {
+		lastContext = ctx;
+		void statusController.refreshFor(ctx);
+	});
+
+	pi.on("model_select", (_event: unknown, ctx: ExtensionContext) => {
+		lastContext = ctx;
+		void statusController.refreshFor(ctx);
+	});
+
+	pi.on("session_shutdown", (_event: unknown, ctx: ExtensionContext) => {
+		statusController.stopAutoRefresh(ctx);
+	});
+}

package/hooks.ts

@@ -0,0 +1,22 @@
+import type { AccountManager } from "./account-manager";
+
+async function refreshAndActivateBestAccount(
+	accountManager: AccountManager,
+): Promise<void> {
+	await accountManager.refreshUsageForAllAccounts({ force: true });
+	const manual = accountManager.getAvailableManualAccount();
+	if (manual) return;
+	if (accountManager.hasManualAccount()) {
+		accountManager.clearManualAccount();
+	}
+	await accountManager.activateBestAccount();
+}
+
+export function handleSessionStart(accountManager: AccountManager): void {
+	if (accountManager.getAccounts().length === 0) return;
+	void refreshAndActivateBestAccount(accountManager);
+}
+
+export function handleNewSessionSwitch(accountManager: AccountManager): void {
+	void refreshAndActivateBestAccount(accountManager);
+}