pi-chatgpt-pool 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Levine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# pi-chatgpt-pool
+
+Pool several ChatGPT accounts in [pi](https://github.com/earendil-works/pi) using OpenAI's Sign in with ChatGPT. You pick one model, and each request goes to a signed-in account. When an account hits a rate limit or its usage limit, pi retries the request on the next account.
+
+## Install
+
+```bash
+pi install npm:pi-chatgpt-pool
+```
+
+Requires pi 0.99.1 or later. The plugin uses pi's own Sign in with ChatGPT flow, which 0.99.0 shipped without.
+
+## Set up accounts
+
+Run `/chatgpt-pool` and choose **+ Add account**, or add them directly:
+
+```text
+/chatgpt-pool add personal
+/chatgpt-pool add work
+/login
+```
+
+`/login` lists each account as `ChatGPT (<label>)`. Sign in to each one with a different ChatGPT account. Then pick a pooled model:
+
+```text
+/model chatgpt/gpt-5.6-sol
+```
+
+The pool offers the ChatGPT subscription models: the OpenAI models that pi also lists for OpenAI Codex, such as `gpt-6.1-sol` and `gpt-5.6-sol`. New models appear when pi's catalog adds them. Pooled models show up once you've added at least one account. Each account also shows up as its own provider (`chatgpt-1`, `chatgpt-2`, ...) if you want to pin one.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/chatgpt-pool` | Open the pool: each account's usage, reset times, and banked resets. Pick an account to spend a reset, clear its limit, or remove it |
+| `/chatgpt-pool add <label>` | Add an account slot. Sign in to it with `/login` |
+| `/chatgpt-pool remove <label>` | Remove an account. Run `/logout` for it first to delete its token |
+| `/chatgpt-pool spend <label>` | Spend one banked reset on that account, after you confirm |
+| `/chatgpt-pool strategy <name>` | Set the routing strategy: `fill-first`, `round-robin`, `least-used`, or `use-it-or-lose-it` |
+| `/chatgpt-pool reset` | Forget recorded limits, for example after a limit clears early |
+
+The command autocompletes its actions and account labels. The footer shows `chatgpt: <account>` while a pooled model is selected, plus how many accounts are limited and when the next one comes back.
+
+`/chatgpt-pool` and `spend` need the interactive UI; in `--print` or `--mode json` they stop with an error instead of spending anything. From a shell, use pi's own commands:
+
+```bash
+pi auth check --provider chatgpt-1     # is this account signed in?
+pi --list-models chatgpt               # pooled models
+pi --model chatgpt/gpt-5.6-sol         # start pi on the pool
+```
+
+Accounts are stored in `~/.pi/agent/chatgpt-pool.json`. Tokens are stored by pi in `~/.pi/agent/auth.json`.
+
+## Strategies
+
+A conversation stays on the same account while it works, so prompt caching and reasoning replay keep working. The strategy decides where each new conversation starts, and which account a limited conversation moves to.
+
+| Strategy | New conversations go to |
+| --- | --- |
+| Fill first (default) | The first ready account, in the order you added them |
+| Round robin | The next account in turn, so load spreads evenly |
+| Least used | The account with the lowest usage % |
+| Use it or lose it | The account whose usage window resets soonest, so its remaining quota isn't wasted |
+
+Choose one from the **Strategy** row in `/chatgpt-pool`, or run `/chatgpt-pool strategy <name>`. It's saved in `chatgpt-pool.json`, and the round-robin position is shared across pi sessions. Least used and use it or lose it read usage from ChatGPT, cached for 5 minutes; accounts whose usage can't be read go last.
+
+## How failover works
+
+- When an account hits a limit, the plugin reads the reset time from the 429 response (`resets_at` in the body, `retry-after`, or the rate-limit reset headers) and skips that account until then. If the response has no reset time, it waits 1 minute for a rate limit or 1 hour for a usage limit.
+- The next request goes to the first ready account in the current strategy's order.
+- Reset times are saved in `chatgpt-pool.json`, so they survive restarts.
+- If every account is signed out or limited, the request fails with a message pointing to `/chatgpt-pool`.
+
+## Banked resets
+
+ChatGPT gives some accounts reset credits that clear a usage limit early. `/chatgpt-pool` shows how many each account has banked and how many apply right now.
+
+The plugin never spends one on its own. Pick the account in `/chatgpt-pool`, or run `/chatgpt-pool spend <label>`. It picks the credit that expires first and asks you to confirm. It warns you when ChatGPT reports nothing to reset.
+
+Usage and banked resets come from ChatGPT's `backend-api/wham` endpoints, the same ones the Codex CLI uses.
+
+## Releasing
+
+```bash
+npm version patch   # or minor / major: bumps package.json, commits, and tags
+git push --follow-tags
+```
+
+Pushing a `v*` tag runs `.github/workflows/publish.yml`. It checks that the tag matches `package.json`, runs the type check and tests, publishes to npm with provenance through npm trusted publishing, and creates a GitHub release with generated notes.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pi-chatgpt-pool",
+  "version": "0.1.0",
+  "description": "Pool several Sign in with ChatGPT accounts in pi, with routing strategies, failover, and banked resets",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "openai",
+    "chatgpt",
+    "oauth",
+    "failover"
+  ],
+  "license": "MIT",
+  "author": "Justin Levine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jal-co/pi-chatgpt-pool.git"
+  },
+  "homepage": "https://github.com/jal-co/pi-chatgpt-pool#readme",
+  "bugs": {
+    "url": "https://github.com/jal-co/pi-chatgpt-pool/issues"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.99.1",
+    "@earendil-works/pi-coding-agent": "^0.99.1",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,463 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getSupportedThinkingLevels, type Api, type Model, type Provider } from "@earendil-works/pi-ai";
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
+import { BorderedLoader, type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+	type Account,
+	isStrategy,
+	limitCooldown,
+	nextAccountId,
+	orderAccounts,
+	parseResetAt,
+	pickAccount,
+	STRATEGIES,
+	type Strategy,
+	type UsageSnapshot,
+} from "./pool.ts";
+import { fetchUsage, spendReset, type Usage } from "./usage.ts";
+
+const POOL_PROVIDER = "chatgpt";
+const STATUS_KEY = "chatgpt-pool";
+const CHATGPT_COMPAT = {
+	supportsLongCacheRetention: false,
+	supportsExplicitPromptCacheMode: false,
+	supportsMaxOutputTokens: false,
+};
+
+function configPath(): string {
+	return join(getAgentDir(), "chatgpt-pool.json");
+}
+
+type PoolConfig = { strategy: Strategy; rotation: number; accounts: Account[] };
+const USAGE_TTL_MS = 5 * 60 * 1000;
+
+function loadConfig(): PoolConfig {
+	if (!existsSync(configPath())) return { strategy: "fill-first", rotation: 0, accounts: [] };
+	const raw = JSON.parse(readFileSync(configPath(), "utf8"));
+	return {
+		strategy: isStrategy(raw.strategy ?? "") ? raw.strategy : "fill-first",
+		rotation: Number.isInteger(raw.rotation) ? raw.rotation : 0,
+		accounts: raw.accounts ?? [],
+	};
+}
+
+function saveConfig(config: PoolConfig): void {
+	mkdirSync(dirname(configPath()), { recursive: true });
+	writeFileSync(configPath(), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+function snapshotOf(usage: Usage): UsageSnapshot | undefined {
+	if (usage.windows.length === 0) return undefined;
+	return {
+		usedPercent: usage.limitReached ? 100 : Math.max(...usage.windows.map((w) => w.usedPercent)),
+		resetsAt: Math.min(...usage.windows.map((w) => w.resetsAt)),
+	};
+}
+
+type ResetListener = (accountId: string, resetsAt: number) => void;
+
+function limitAwareFetch(accountId: string, onReset: ResetListener, base: typeof fetch = fetch): typeof fetch {
+	return async (input, init) => {
+		const response = await base(input, init);
+		if (response.status === 429) {
+			const resetsAt = parseResetAt(response.headers, await response.clone().text(), Date.now());
+			if (resetsAt !== undefined) onReset(accountId, resetsAt);
+		}
+		return response;
+	};
+}
+
+function subscriptionModels(providers: readonly Provider[]): Model<Api>[] {
+	const openai = providers.find((provider) => provider.id === "openai");
+	if (!openai) throw new Error("pi-chatgpt-pool needs pi's built-in openai provider");
+	const codex = new Set(providers.find((provider) => provider.id === "openai-codex")?.getModels().map((model) => model.id));
+	return openai.getModels().filter((model) => codex.has(model.id));
+}
+
+function accountProvider(openai: Provider, account: Account, onReset: ResetListener): Provider {
+	const name = `ChatGPT (${account.label})`;
+	const signIn = openai.auth.oauth;
+	if (!signIn) throw new Error("pi's openai provider has no Sign in with ChatGPT flow; update pi to 0.99.1 or later");
+	const models: Model<Api>[] = subscriptionModels(builtinProviders()).map((model) => ({
+		...model,
+		provider: account.id,
+		compat: { ...model.compat, ...CHATGPT_COMPAT },
+	}));
+	return {
+		id: account.id,
+		name,
+		baseUrl: openai.baseUrl,
+		auth: { oauth: { ...signIn, name } },
+		getModels: () => models,
+		stream: (model, context, options) => openai.stream(model, context, options),
+		streamSimple: (model, context, options) =>
+			openai.streamSimple(model, context, { ...options, fetch: limitAwareFetch(account.id, onReset, options?.fetch) }),
+	};
+}
+
+function formatWindow(seconds: number): string {
+	if (seconds % 604800 === 0) return seconds === 604800 ? "weekly" : `${seconds / 604800}-week`;
+	if (seconds % 3600 === 0) return `${seconds / 3600}h`;
+	return `${Math.round(seconds / 60)}m`;
+}
+
+function formatReset(at: number): string {
+	const date = new Date(at);
+	const time = date.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
+	return date.toDateString() === new Date().toDateString()
+		? `at ${time}`
+		: `${date.toLocaleDateString([], { weekday: "short", month: "short", day: "numeric" })} at ${time}`;
+}
+
+export default function chatgptPool(pi: ExtensionAPI) {
+	const providers = builtinProviders();
+	const openai = providers.find((provider) => provider.id === "openai");
+	if (!openai) throw new Error("pi-chatgpt-pool needs pi's built-in openai provider");
+
+	let { strategy, accounts } = loadConfig();
+	const update = (change: (config: PoolConfig) => PoolConfig) => {
+		const next = change(loadConfig());
+		saveConfig(next);
+		({ strategy, accounts } = next);
+		return next;
+	};
+	const usageCache = new Map<string, { snapshot: UsageSnapshot; at: number }>();
+
+	const rememberUsage = (accountId: string, usage: Usage) => {
+		const snapshot = snapshotOf(usage);
+		if (snapshot) usageCache.set(accountId, { snapshot, at: Date.now() });
+	};
+
+	const freshUsage = async (ctx: ExtensionContext, signal?: AbortSignal) => {
+		if (strategy !== "least-used" && strategy !== "use-it-or-lose-it") return new Map<string, UsageSnapshot>();
+		await Promise.all(
+			accounts.map(async (account) => {
+				const cached = usageCache.get(account.id);
+				if (cached && Date.now() - cached.at < USAGE_TTL_MS) return;
+				const token = await ctx.modelRegistry.getApiKeyForProvider(account.id).catch(() => undefined);
+				if (!token || signal?.aborted) return;
+				await fetchUsage(token).then((usage) => rememberUsage(account.id, usage), () => undefined);
+			}),
+		);
+		return new Map([...usageCache].map(([id, entry]) => [id, entry.snapshot]));
+	};
+	const reportedResets = new Map<string, number>();
+	const onReset: ResetListener = (accountId, resetsAt) => reportedResets.set(accountId, resetsAt);
+
+	const setResetsAt = (accountId: string, resetsAt: number | undefined) => {
+		update((config) => ({
+			...config,
+			accounts: config.accounts.map((account) => (account.id === accountId ? { ...account, resetsAt } : account)),
+		}));
+	};
+
+	const isUsable = (ctx: ExtensionContext, accountId: string, modelId: string) => {
+		const account = accounts.find((candidate) => candidate.id === accountId);
+		const model = ctx.modelRegistry.find(accountId, modelId);
+		return (account?.resetsAt ?? 0) <= Date.now() && !!model && ctx.modelRegistry.hasConfiguredAuth(model);
+	};
+
+	for (const account of accounts) pi.registerProvider(accountProvider(openai, account, onReset));
+
+	let lastRouted: string | undefined;
+	const updateStatus = (ctx: ExtensionContext, provider = ctx.model?.provider) => {
+		if (provider !== POOL_PROVIDER) return ctx.ui.setStatus(STATUS_KEY, undefined);
+		const now = Date.now();
+		const active = accounts.find((account) => account.id === lastRouted);
+		const limited = accounts.filter((account) => (account.resetsAt ?? 0) > now);
+		const parts = [`chatgpt: ${active?.label ?? "pool"}`];
+		if (limited.length > 0) {
+			const next = Math.min(...limited.map((account) => account.resetsAt ?? now));
+			parts.push(`${limited.length} limited, next back ${formatReset(next)}`);
+		}
+		ctx.ui.setStatus(STATUS_KEY, parts.join(" · "));
+	};
+
+	pi.on("session_start", (_event, ctx) => updateStatus(ctx));
+	pi.on("model_select", (event, ctx) => updateStatus(ctx, event.model.provider));
+
+	let pooledModelsRegistered = false;
+	const registerPooledModels = () => {
+		if (pooledModelsRegistered || accounts.length === 0) return;
+		pooledModelsRegistered = true;
+		for (const model of subscriptionModels(providers)) registerPooledModel(model);
+	};
+
+	const registerPooledModel = (model: Model<Api>) =>
+		pi.registerVirtualModel({
+			provider: POOL_PROVIDER,
+			id: model.id,
+			name: `${model.name} (ChatGPT pool)`,
+			thinkingLevels: getSupportedThinkingLevels(model),
+			contextWindow: model.contextWindow,
+			maxTokens: model.maxTokens,
+			input: model.input,
+			async route(request, ctx) {
+				const sticky = (request.failed ?? request.previous)?.model.provider;
+				const usable = (id: string) => isUsable(ctx, id, model.id);
+				const keepSticky = sticky !== undefined && usable(sticky);
+				const usage = keepSticky ? new Map<string, UsageSnapshot>() : await freshUsage(ctx, request.signal);
+				const rotation =
+					!keepSticky && sticky === undefined && strategy === "round-robin"
+						? update((config) => ({ ...config, rotation: config.rotation + 1 })).rotation - 1
+						: 0;
+				const ordered = keepSticky ? accounts : orderAccounts(accounts, strategy, usage, rotation);
+				const account = pickAccount(ordered, usable, sticky);
+				const routed = account && ctx.modelRegistry.find(account.id, model.id);
+				if (!routed) {
+					throw new Error(
+						accounts.length === 0
+							? "No ChatGPT accounts in the pool. Run /chatgpt-pool to add one, then /login."
+							: "Every ChatGPT account in the pool is signed out or limited. Run /chatgpt-pool to see reset times and banked resets.",
+					);
+				}
+				if (lastRouted !== routed.provider) {
+					lastRouted = routed.provider;
+					updateStatus(ctx);
+				}
+				return { model: routed, thinkingLevel: request.thinkingLevel };
+			},
+		});
+
+	registerPooledModels();
+
+	pi.on("message_end", (event, ctx) => {
+		const message = event.message;
+		if (message.role !== "assistant" || message.stopReason !== "error") return;
+		const account = accounts.find((candidate) => candidate.id === message.provider);
+		const reported = account && reportedResets.get(account.id);
+		if (account) reportedResets.delete(account.id);
+		const cooldown = limitCooldown(message.errorMessage);
+		if (!account || (cooldown === undefined && reported === undefined)) return;
+		setResetsAt(account.id, reported ?? Date.now() + (cooldown ?? 0));
+		updateStatus(ctx);
+		if (ctx.model?.provider !== POOL_PROVIDER) return;
+		if (!pickAccount(accounts, (id) => isUsable(ctx, id, message.model), undefined)) return;
+		return {
+			message: {
+				...message,
+				errorMessage: `ChatGPT account "${account.label}" is rate limited; switching to another account in the pool.`,
+			},
+		};
+	});
+
+	type AccountStatus = { account: Account; signedIn: boolean; usage?: Usage; error?: string };
+
+	const loadStatuses = (ctx: ExtensionContext, signal?: AbortSignal): Promise<AccountStatus[]> =>
+		Promise.all(
+			accounts.map(async (account): Promise<AccountStatus> => {
+				const token = await ctx.modelRegistry.getApiKeyForProvider(account.id).catch(() => undefined);
+				if (!token || signal?.aborted) return { account, signedIn: !!token };
+				try {
+					const usage = await fetchUsage(token);
+					rememberUsage(account.id, usage);
+					const limitedUntil = usage.limitReached ? Math.max(...usage.windows.map((w) => w.resetsAt)) : undefined;
+					if (limitedUntil !== account.resetsAt && (usage.limitReached || (account.resetsAt ?? 0) > Date.now())) {
+						setResetsAt(account.id, limitedUntil);
+					}
+					return { account, signedIn: true, usage };
+				} catch (error) {
+					return { account, signedIn: true, error: error instanceof Error ? error.message : String(error) };
+				}
+			}),
+		);
+
+	const withLoader = <T>(ctx: ExtensionContext, message: string, work: (signal?: AbortSignal) => Promise<T>) => {
+		if (ctx.mode !== "tui") return work();
+		return ctx.ui.custom<T | undefined>((tui, theme, _keybindings, done) => {
+			const loader = new BorderedLoader(tui, theme, message);
+			loader.onAbort = () => done(undefined);
+			work(loader.signal).then(done, () => done(undefined));
+			return loader;
+		});
+	};
+
+	const describe = ({ account, signedIn, usage, error }: AccountStatus): string => {
+		const limitedUntil = account.resetsAt && account.resetsAt > Date.now() ? account.resetsAt : undefined;
+		if (!signedIn) return `${account.label}  ·  not signed in, run /login and pick ChatGPT (${account.label})`;
+		const state = limitedUntil ? `limited until ${formatReset(limitedUntil)}` : "ready";
+		if (!usage) return `${account.label}  ·  ${state}  ·  usage unavailable${error ? ` (${error})` : ""}`;
+		const windows = usage.windows.map(
+			(w) => `${formatWindow(w.windowSeconds)} ${Math.round(w.usedPercent)}%, resets ${formatReset(w.resetsAt)}`,
+		);
+		const banked =
+			usage.banked === 0
+				? "no banked resets"
+				: `${usage.banked} banked${usage.usableNow > 0 ? `, ${usage.usableNow} usable now` : ""}`;
+		return [account.label, state, ...windows, banked].join("  ·  ");
+	};
+
+	const findAccount = (label: string) =>
+		accounts.find((candidate) => candidate.label === label || candidate.id === label);
+
+	const addAccount = (ctx: ExtensionContext, label: string) => {
+		if (findAccount(label)) return ctx.ui.notify(`There is already an account named "${label}".`, "warning");
+		const account = { id: nextAccountId(loadConfig().accounts), label };
+		update((config) => ({ ...config, accounts: [...config.accounts, account] }));
+		registerPooledModels();
+		pi.registerProvider(accountProvider(openai, account, onReset));
+		ctx.ui.notify(`Added ChatGPT (${label}). Run /login and pick it to sign in.`, "info");
+	};
+
+	const removeAccount = (ctx: ExtensionContext, account: Account) => {
+		update((config) => ({ ...config, accounts: config.accounts.filter((candidate) => candidate.id !== account.id) }));
+		pi.unregisterProvider(account.id);
+		updateStatus(ctx);
+		ctx.ui.notify(
+			`Removed ChatGPT (${account.label}). Its token stays in auth.json under ${account.id} until you remove it.`,
+			"info",
+		);
+	};
+
+	const spend = async (ctx: ExtensionContext, account: Account, known?: Usage) => {
+		const token = await ctx.modelRegistry.getApiKeyForProvider(account.id);
+		if (!token) return ctx.ui.notify(`ChatGPT (${account.label}) is not signed in.`, "warning");
+		const usage = known ?? (await withLoader(ctx, `Checking ${account.label}...`, () => fetchUsage(token)));
+		if (!usage) return;
+		const credit = [...usage.credits].sort(
+			(a, b) => (a.expiresAt ?? Number.POSITIVE_INFINITY) - (b.expiresAt ?? Number.POSITIVE_INFINITY),
+		)[0];
+		if (!credit) return ctx.ui.notify(`ChatGPT (${account.label}) has no banked resets.`, "info");
+		const warning =
+			usage.usableNow === 0 ? " ChatGPT reports nothing to reset right now, so this may not change anything." : "";
+		const confirmed = await ctx.ui.confirm(
+			`Spend a banked reset on ${account.label}?`,
+			`Uses "${credit.title}"${credit.expiresAt ? `, expiring ${formatReset(credit.expiresAt)}` : ""}. ${usage.banked} banked in total.${warning}`,
+		);
+		if (!confirmed) return ctx.ui.notify("No reset spent.", "info");
+		const outcome = await spendReset(token, credit.id);
+		if (outcome === "reset") setResetsAt(account.id, undefined);
+		updateStatus(ctx);
+		ctx.ui.notify(
+			{
+				reset: `Spent a banked reset. ChatGPT (${account.label}) is ready again.`,
+				nothing_to_reset: `ChatGPT (${account.label}) had nothing to reset, so no reset was spent.`,
+				no_credit: `ChatGPT (${account.label}) has no banked resets left.`,
+				already_redeemed: "That reset was already spent.",
+			}[outcome],
+			outcome === "reset" ? "info" : "warning",
+		);
+	};
+
+	const setStrategy = (ctx: ExtensionContext, next: Strategy) => {
+		update((config) => ({ ...config, strategy: next }));
+		ctx.ui.notify(`${STRATEGIES[next]}.`, "info");
+	};
+
+	const chooseStrategy = async (ctx: ExtensionContext) => {
+		const labels = Object.values(STRATEGIES).map((text) => (text === STRATEGIES[strategy] ? `${text} (current)` : text));
+		const picked = await ctx.ui.select("Routing strategy for new conversations", labels);
+		const next = Object.keys(STRATEGIES).find((_key, index) => labels[index] === picked);
+		if (next && isStrategy(next)) setStrategy(ctx, next);
+	};
+
+	const openPool = async (ctx: ExtensionContext) => {
+		const statuses = await withLoader(ctx, "Checking ChatGPT accounts...", (signal) => loadStatuses(ctx, signal));
+		if (!statuses) return;
+		updateStatus(ctx);
+		const addOption = "+ Add account";
+		const strategyOption = `Strategy: ${STRATEGIES[strategy].split(":")[0]}`;
+		const options = [...statuses.map(describe), addOption, strategyOption];
+		const picked = await ctx.ui.select("ChatGPT pool", options);
+		if (!picked) return;
+		if (picked === strategyOption) return chooseStrategy(ctx);
+		if (picked === addOption) {
+			const label = (await ctx.ui.input("Label for the new ChatGPT account", "work"))?.trim();
+			if (label) addAccount(ctx, label);
+			return;
+		}
+		const status = statuses[options.indexOf(picked)];
+		const actions = [
+			...(status.usage && status.usage.banked > 0 ? [`Spend a banked reset (${status.usage.banked} banked)`] : []),
+			...(status.account.resetsAt && status.account.resetsAt > Date.now() ? ["Clear recorded limit"] : []),
+			"Remove from pool",
+		];
+		const action = await ctx.ui.select(`ChatGPT (${status.account.label})`, actions);
+		if (!action) return;
+		if (action.startsWith("Spend")) return spend(ctx, status.account, status.usage);
+		if (action === "Clear recorded limit") {
+			setResetsAt(status.account.id, undefined);
+			updateStatus(ctx);
+			return ctx.ui.notify(`ChatGPT (${status.account.label}) is back in rotation.`, "info");
+		}
+		if (await ctx.ui.confirm(`Remove ${status.account.label}?`, "It will no longer be used by the pool.")) {
+			removeAccount(ctx, status.account);
+		}
+	};
+
+	const SUBCOMMANDS = [
+		{ value: "add", label: "add", description: "Add an account slot" },
+		{ value: "remove", label: "remove", description: "Remove an account" },
+		{ value: "spend", label: "spend", description: "Spend a banked reset, after confirming" },
+		{ value: "reset", label: "reset", description: "Forget recorded limits" },
+		{ value: "strategy", label: "strategy", description: "Choose how new conversations pick an account" },
+	];
+
+	pi.registerCommand("chatgpt-pool", {
+		description: "Manage pooled ChatGPT accounts: usage, banked resets, strategy, add, remove, spend, reset",
+		getArgumentCompletions(prefix) {
+			const [action, ...rest] = prefix.split(" ");
+			if (rest.length === 0) return SUBCOMMANDS.filter((item) => item.value.startsWith(action));
+			if (action === "strategy") {
+				return Object.entries(STRATEGIES)
+					.filter(([name]) => name.startsWith(rest.join(" ")))
+					.map(([name, description]) => ({ value: `strategy ${name}`, label: name, description }));
+			}
+			if (action !== "remove" && action !== "spend") return null;
+			const partial = rest.join(" ");
+			return accounts
+				.filter((account) => account.label.startsWith(partial))
+				.map((account) => ({ value: `${action} ${account.label}`, label: account.label, description: account.id }));
+		},
+		async handler(args, ctx) {
+			const [action = "", ...rest] = args.trim().split(/\s+/);
+			const label = rest.join(" ");
+
+			if (action === "add") {
+				if (!label) return ctx.ui.notify("Usage: /chatgpt-pool add <label>", "warning");
+				return addAccount(ctx, label);
+			}
+
+			if (action === "remove") {
+				const account = findAccount(label);
+				if (!account) return ctx.ui.notify(`No pooled account named "${label}"`, "warning");
+				return removeAccount(ctx, account);
+			}
+
+			if (action === "reset") {
+				update((config) => ({ ...config, accounts: config.accounts.map(({ id, label }) => ({ id, label })) }));
+				updateStatus(ctx);
+				return ctx.ui.notify("Cleared recorded limits. Every signed-in account is back in rotation.", "info");
+			}
+
+			if (action === "strategy") {
+				if (isStrategy(label)) return setStrategy(ctx, label);
+				if (label || !ctx.hasUI) {
+					return ctx.ui.notify(`Usage: /chatgpt-pool strategy <${Object.keys(STRATEGIES).join(" | ")}>`, "warning");
+				}
+				return chooseStrategy(ctx);
+			}
+
+			if (!ctx.hasUI) {
+				throw new Error(
+					"/chatgpt-pool needs the interactive UI to show usage or spend a banked reset. Use `pi auth check --provider chatgpt-1` to check an account from a script.",
+				);
+			}
+
+			if (action === "spend") {
+				const account = findAccount(label);
+				if (!account) return ctx.ui.notify("Usage: /chatgpt-pool spend <label>", "warning");
+				return spend(ctx, account);
+			}
+
+			if (action) return ctx.ui.notify(`Unknown action "${action}". Use add, remove, spend, reset, or strategy.`, "warning");
+			if (accounts.length === 0) {
+				const label = (await ctx.ui.input("No ChatGPT accounts yet. Label for the first one", "personal"))?.trim();
+				if (label) addAccount(ctx, label);
+				return;
+			}
+			await openPool(ctx);
+		},
+	});
+}

package/src/pool.ts

@@ -0,0 +1,118 @@
+export type Account = { id: string; label: string; resetsAt?: number };
+
+const USAGE_LIMIT = /usage.?limit|subscription_sharing_usage_limit_exceeded|insufficient_quota|quota/i;
+const RATE_LIMIT = /rate.?limit|too many requests|\b429\b/i;
+
+export const USAGE_COOLDOWN_MS = 60 * 60 * 1000;
+export const RATE_COOLDOWN_MS = 60 * 1000;
+
+export function limitCooldown(errorMessage: string | undefined): number | undefined {
+	if (!errorMessage) return undefined;
+	if (USAGE_LIMIT.test(errorMessage)) return USAGE_COOLDOWN_MS;
+	if (RATE_LIMIT.test(errorMessage)) return RATE_COOLDOWN_MS;
+	return undefined;
+}
+
+const DURATION_PART = /(\d+(?:\.\d+)?)(ms|h|m|s)/g;
+const DURATION_MS = new Map([
+	["h", 3_600_000],
+	["m", 60_000],
+	["s", 1000],
+	["ms", 1],
+]);
+
+function parseDurationMs(value: string): number | undefined {
+	if (/^\d+(\.\d+)?$/.test(value)) return Number(value) * 1000;
+	let total = 0;
+	let matched = "";
+	for (const [part, amount, unit] of value.matchAll(DURATION_PART)) {
+		total += Number(amount) * (DURATION_MS.get(unit) ?? 0);
+		matched += part;
+	}
+	return matched === value ? total : undefined;
+}
+
+function secondsOrMs(value: number): number {
+	return value < 1e12 ? value * 1000 : value;
+}
+
+export function parseResetAt(headers: Headers, body: string, now: number): number | undefined {
+	const candidates: number[] = [];
+	const addIn = (ms: number | undefined) => {
+		if (ms !== undefined && Number.isFinite(ms) && ms > 0) candidates.push(now + ms);
+	};
+	const addAt = (at: number) => {
+		if (Number.isFinite(at) && at > now) candidates.push(at);
+	};
+
+	const retryAfterMs = headers.get("retry-after-ms");
+	if (retryAfterMs) addIn(Number(retryAfterMs));
+
+	const retryAfter = headers.get("retry-after")?.trim();
+	if (retryAfter) {
+		if (/^\d+(\.\d+)?$/.test(retryAfter)) addIn(Number(retryAfter) * 1000);
+		else addAt(Date.parse(retryAfter));
+	}
+
+	for (const [name, value] of headers) {
+		if (name.startsWith("x-ratelimit-reset") || /^x-codex-.*reset-after-seconds$/.test(name)) {
+			addIn(parseDurationMs(value.trim()));
+		} else if (/^x-codex-.*reset-at$/.test(name)) {
+			addAt(secondsOrMs(Number(value)));
+		}
+	}
+
+	const match = body.match(/"resets_at"\s*:\s*(\d+(?:\.\d+)?)/);
+	if (match) addAt(secondsOrMs(Number(match[1])));
+	const inSeconds = body.match(/"resets_in_seconds"\s*:\s*(\d+(?:\.\d+)?)/);
+	if (inSeconds) addIn(Number(inSeconds[1]) * 1000);
+
+	return candidates.length > 0 ? Math.max(...candidates) : undefined;
+}
+
+export function pickAccount(
+	accounts: readonly Account[],
+	isUsable: (id: string) => boolean,
+	sticky: string | undefined,
+): Account | undefined {
+	const usable = accounts.filter((account) => isUsable(account.id));
+	return usable.find((account) => account.id === sticky) ?? usable[0];
+}
+
+export function nextAccountId(accounts: readonly Account[]): string {
+	const highest = Math.max(0, ...accounts.map((account) => Number(account.id.split("-").pop()) || 0));
+	return `chatgpt-${highest + 1}`;
+}
+
+export const STRATEGIES = {
+	"fill-first": "Fill first: use accounts in order, save the later ones for when the first runs out",
+	"round-robin": "Round robin: start each new conversation on the next account",
+	"least-used": "Least used: start new conversations on the account with the lowest usage",
+	"use-it-or-lose-it": "Use it or lose it: prefer the account whose usage window resets soonest",
+};
+export type Strategy = keyof typeof STRATEGIES;
+export type UsageSnapshot = { usedPercent: number; resetsAt: number };
+
+export function isStrategy(value: string): value is Strategy {
+	return Object.hasOwn(STRATEGIES, value);
+}
+
+export function orderAccounts(
+	accounts: readonly Account[],
+	strategy: Strategy,
+	usage: ReadonlyMap<string, UsageSnapshot>,
+	rotation: number,
+): Account[] {
+	if (strategy === "fill-first" || accounts.length === 0) return [...accounts];
+	if (strategy === "round-robin") {
+		const start = rotation % accounts.length;
+		return [...accounts.slice(start), ...accounts.slice(0, start)];
+	}
+	const known = accounts.filter((account) => usage.has(account.id) && (usage.get(account.id)?.usedPercent ?? 100) < 100);
+	const rest = accounts.filter((account) => !known.includes(account));
+	const key = (account: Account) => {
+		const snapshot = usage.get(account.id);
+		return strategy === "least-used" ? (snapshot?.usedPercent ?? 100) : (snapshot?.resetsAt ?? Number.POSITIVE_INFINITY);
+	};
+	return [...known.sort((a, b) => key(a) - key(b)), ...rest];
+}

package/src/usage.ts

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto";
+
+const BACKEND = "https://chatgpt.com/backend-api/wham";
+
+type Window = { used_percent: number; limit_window_seconds: number; reset_at: number };
+type UsageResponse = {
+	rate_limit?: { limit_reached?: boolean; primary_window?: Window | null; secondary_window?: Window | null } | null;
+	rate_limit_reset_credits?: { available_count?: number; applicable_available_count?: number } | null;
+};
+type CreditsResponse = {
+	credits: { id: string; status: string; title?: string | null; expires_at?: string | null }[];
+};
+type ConsumeResponse = { code: "reset" | "nothing_to_reset" | "no_credit" | "already_redeemed" };
+
+export type UsageWindow = { usedPercent: number; windowSeconds: number; resetsAt: number };
+export type Usage = {
+	limitReached: boolean;
+	windows: UsageWindow[];
+	banked: number;
+	usableNow: number;
+	credits: { id: string; title: string; expiresAt?: number }[];
+};
+export type SpendOutcome = ConsumeResponse["code"];
+
+function accountIdFromToken(token: string): string | undefined {
+	const payload = token.split(".")[1];
+	if (!payload) return undefined;
+	try {
+		return JSON.parse(Buffer.from(payload, "base64url").toString("utf8"))["https://api.openai.com/auth"]
+			?.chatgpt_account_id;
+	} catch {
+		return undefined;
+	}
+}
+
+async function backend<T>(token: string, path: string, init: RequestInit = {}): Promise<T> {
+	const headers = new Headers({ authorization: `Bearer ${token}`, "content-type": "application/json" });
+	const accountId = accountIdFromToken(token);
+	if (accountId) headers.set("chatgpt-account-id", accountId);
+	const response = await fetch(`${BACKEND}/${path}`, { ...init, headers, signal: AbortSignal.timeout(15_000) });
+	if (!response.ok) {
+		const body = await response.text().catch(() => "");
+		throw new Error(`ChatGPT ${path} failed (${response.status})${body ? `: ${body.slice(0, 200)}` : ""}`);
+	}
+	return response.json();
+}
+
+function toWindow(window: Window | null | undefined): UsageWindow[] {
+	if (!window) return [];
+	return [{ usedPercent: window.used_percent, windowSeconds: window.limit_window_seconds, resetsAt: window.reset_at * 1000 }];
+}
+
+export async function fetchUsage(token: string): Promise<Usage> {
+	const [usage, credits] = await Promise.all([
+		backend<UsageResponse>(token, "usage"),
+		backend<CreditsResponse>(token, "rate-limit-reset-credits"),
+	]);
+	const limit = usage.rate_limit;
+	return {
+		limitReached: limit?.limit_reached === true,
+		windows: [...toWindow(limit?.primary_window), ...toWindow(limit?.secondary_window)],
+		banked: usage.rate_limit_reset_credits?.available_count ?? 0,
+		usableNow: usage.rate_limit_reset_credits?.applicable_available_count ?? 0,
+		credits: credits.credits
+			.filter((credit) => credit.status === "available")
+			.map((credit) => ({
+				id: credit.id,
+				title: credit.title || "Reset",
+				expiresAt: credit.expires_at ? Date.parse(credit.expires_at) : undefined,
+			})),
+	};
+}
+
+export async function spendReset(token: string, creditId: string): Promise<SpendOutcome> {
+	const response = await backend<ConsumeResponse>(token, "rate-limit-reset-credits/consume", {
+		method: "POST",
+		body: JSON.stringify({ redeem_request_id: randomUUID(), credit_id: creditId }),
+	});
+	return response.code;
+}