@maxiaochao/pi-toolkit 0.11.6 → 0.11.8

package/packages/openai-account-pool/src/login-slot.ts

@@ -0,0 +1,158 @@
+import type { AuthEvent, AuthInfoLink, AuthPrompt, OAuthDeviceCodeInfo, ProviderAuthInteraction } from "@earendil-works/pi-ai";
+
+/**
+ * One OAuth login inside pi's single editor slot.
+ *
+ * pi hands extensions one slot below the chat: `ui.select` puts the editor back when it closes,
+ * so a selector opened while the login dialog is mounted takes the dialog down with it, and every
+ * later auth step renders into a component nobody can see. The Codex flow hits exactly that, as it
+ * asks for the login method first and shows the sign-in URL and the manual-code input afterwards.
+ *
+ * The slot therefore mounts the dialog lazily and steps out of it around every selector, and keeps
+ * auth events in the order the provider emitted them.
+ */
+
+/** The part of pi's login dialog this module drives. */
+export interface LoginDialog {
+	/** Aborts when the user cancels inside the dialog. */
+	readonly signal: AbortSignal;
+	showAuth(url: string, instructions?: string): void;
+	showDeviceCode(info: OAuthDeviceCodeInfo): void;
+	showInfo(message: string, links?: readonly AuthInfoLink[]): void;
+	showProgress(message: string): void;
+	showWaiting(message: string): void;
+	showManualInput(message: string): Promise<string>;
+	showPrompt(message: string, placeholder?: string): Promise<string>;
+}
+
+export interface LoginSlotUi {
+	/**
+	 * Mounts a login dialog in the slot and reports it together with the callback that takes it
+	 * down again. Resolves once the slot has been handed back.
+	 */
+	mount(register: (dialog: LoginDialog, close: () => void) => void): Promise<unknown>;
+	/** Shows a selector in the same slot. Resolves to undefined when the user cancels. */
+	select(message: string, options: readonly string[], signal?: AbortSignal): Promise<string | undefined>;
+}
+
+const CANCELLED = "Login cancelled";
+
+/** A prompt can lose its race, e.g. a manual code while the callback server wins. */
+function withCancellation<T>(answer: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+	if (!signal) return answer;
+	if (signal.aborted) return Promise.reject(new Error(CANCELLED));
+	let onAbort: (() => void) | undefined;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		onAbort = () => reject(new Error(CANCELLED));
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	return Promise.race([answer, aborted]).finally(() => {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	});
+}
+
+export class LoginSlot {
+	private readonly aborter = new AbortController();
+	private dialog: LoginDialog | undefined;
+	private opening: Promise<LoginDialog> | undefined;
+	private hide: (() => void) | undefined;
+	private dismissed: Promise<unknown> = Promise.resolve();
+	/** Serializes everything that needs the slot to itself. Never rejects. */
+	private queue: Promise<void> = Promise.resolve();
+	private readonly ui: LoginSlotUi;
+
+	constructor(ui: LoginSlotUi) {
+		this.ui = ui;
+	}
+
+	/** What `oauth.login()` is called with. */
+	get interaction(): ProviderAuthInteraction {
+		return {
+			signal: this.aborter.signal,
+			prompt: (request) => this.prompt(request),
+			notify: (event) => this.notify(event),
+		};
+	}
+
+	/** Gives the slot back once the login is over. */
+	async close(): Promise<void> {
+		await this.queue;
+		await this.unmount();
+	}
+
+	private enqueue<T>(task: () => Promise<T>): Promise<T> {
+		const running = this.queue.then(task);
+		this.queue = running.then(
+			() => undefined,
+			() => undefined,
+		);
+		return running;
+	}
+
+	private open(): Promise<LoginDialog> {
+		if (this.opening) return this.opening;
+		let ready: (dialog: LoginDialog) => void = () => {};
+		let failed: (error: unknown) => void = () => {};
+		const shown = new Promise<LoginDialog>((resolve, reject) => {
+			ready = resolve;
+			failed = reject;
+		});
+		this.dismissed = this.ui
+			.mount((dialog, close) => {
+				// Cancelling inside the dialog cancels the login, the same key `/login` honours.
+				dialog.signal.addEventListener("abort", () => this.aborter.abort(), { once: true });
+				this.dialog = dialog;
+				this.hide = close;
+				ready(dialog);
+			})
+			.catch((error: unknown) => {
+				failed(error);
+			});
+		this.opening = shown;
+		return shown;
+	}
+
+	private async unmount(): Promise<void> {
+		const hide = this.hide;
+		const dismissed = this.dismissed;
+		this.dialog = undefined;
+		this.opening = undefined;
+		this.hide = undefined;
+		this.dismissed = Promise.resolve();
+		hide?.();
+		await dismissed;
+	}
+
+	private async prompt(request: AuthPrompt): Promise<string> {
+		if (request.type === "select") return withCancellation(this.select(request), request.signal);
+		// Wait for the events that arrived before this prompt, so the dialog reads in order.
+		await this.queue;
+		const dialog = await this.open();
+		const answer =
+			request.type === "manual_code" ? dialog.showManualInput(request.message) : dialog.showPrompt(request.message, request.placeholder);
+		return withCancellation(answer, request.signal);
+	}
+
+	private select(request: AuthPrompt & { type: "select" }): Promise<string> {
+		return this.enqueue(async () => {
+			await this.unmount();
+			const labels = request.options.map((option) => option.label);
+			const chosen = await this.ui.select(request.message, labels, request.signal);
+			const index = chosen === undefined ? -1 : labels.indexOf(chosen);
+			if (index < 0) throw new Error(CANCELLED);
+			return request.options[index].id;
+		});
+	}
+
+	private notify(event: AuthEvent): void {
+		void this.enqueue(async () => {
+			const dialog = await this.open();
+			if (event.type === "auth_url") dialog.showAuth(event.url, event.instructions);
+			else if (event.type === "device_code") {
+				dialog.showDeviceCode(event);
+				dialog.showWaiting("等待浏览器完成授权…");
+			} else if (event.type === "info") dialog.showInfo(event.message, event.links);
+			else dialog.showProgress(event.message);
+		}).catch(() => undefined);
+	}
+}

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

@@ -0,0 +1,176 @@
+/**
+ * Pure decisions: what a failure proves, which account to use next, and whether this request may
+ * still switch accounts. Nothing here reads files or the network, so every rule is testable.
+ *
+ * Classification reads structured evidence only. pi's Codex adapter formats a plain HTTP 429 with
+ * the same "You have hit your ChatGPT usage limit" text as a real subscription limit, so matching
+ * the user-facing message would switch accounts on ordinary rate limiting.
+ */
+
+export type FailureKind =
+	/** The subscription's own limit is reached: the only automatic quota switch. */
+	| "quota"
+	/** The stored authorization is proven invalid; the account needs re-authorizing. */
+	| "auth_invalid"
+	/** Authentication was rejected once; the same account may be repaired first. */
+	| "auth_retry"
+	/** Rate limiting, network trouble or a server-side blip: retry the same account. */
+	| "transient"
+	| "cancelled"
+	/** A definite error that another account would not fix. */
+	| "fatal"
+	| "unknown";
+
+export interface ProviderErrorBody {
+	code?: unknown;
+	type?: unknown;
+	message?: unknown;
+	plan_type?: unknown;
+	resets_at?: unknown;
+	resets_in_seconds?: unknown;
+}
+
+export interface FailureEvidence {
+	status?: number;
+	body?: ProviderErrorBody;
+	cancelled?: boolean;
+	/** Set when the failure came from the OAuth token exchange rather than the model request. */
+	oauthRefresh?: { invalidGrant: boolean };
+	/** Transport-level failure such as DNS, reset connection or timeout. */
+	networkFailure?: boolean;
+	/** Model the request was for; quota without plan-level evidence is scoped to it. */
+	modelId?: string;
+}
+
+export interface Classification {
+	kind: FailureKind;
+	/** Short, non-secret reason for status output and state records. */
+	reason: string;
+	/** Cooldown scope: the whole account, or `model:<id>` when the evidence is not plan-level. */
+	scope: string;
+	/** Server-stated reset time in epoch ms, or null when the server stated none. */
+	serverResetAtMs: number | null;
+}
+
+export const ACCOUNT_SCOPE = "account";
+const MAX_RESET_HORIZON_MS = 30 * 24 * 60 * 60 * 1_000;
+
+function errorCode(body: ProviderErrorBody | undefined): string {
+	const code = typeof body?.code === "string" ? body.code : "";
+	if (code) return code.toLowerCase();
+	return typeof body?.type === "string" ? body.type.toLowerCase() : "";
+}
+
+/** Only a field that is finite and lands in a plausible window counts as a reset time. */
+export function serverResetAtMs(body: ProviderErrorBody | undefined, now: number): number | null {
+	const inWindow = (value: number) => value > now - 24 * 60 * 60 * 1_000 && value < now + MAX_RESET_HORIZON_MS;
+	if (typeof body?.resets_at === "number" && Number.isFinite(body.resets_at)) {
+		// The Codex error reports epoch seconds.
+		const candidate = body.resets_at * 1_000;
+		if (inWindow(candidate)) return candidate;
+	}
+	if (typeof body?.resets_in_seconds === "number" && Number.isFinite(body.resets_in_seconds) && body.resets_in_seconds >= 0) {
+		const candidate = now + body.resets_in_seconds * 1_000;
+		if (inWindow(candidate)) return candidate;
+	}
+	return null;
+}
+
+export function classifyFailure(evidence: FailureEvidence, now: number): Classification {
+	const scopeForModel = evidence.modelId ? `model:${evidence.modelId}` : ACCOUNT_SCOPE;
+	const plain = (kind: FailureKind, reason: string): Classification => ({ kind, reason, scope: scopeForModel, serverResetAtMs: null });
+
+	if (evidence.cancelled) return plain("cancelled", "cancelled");
+
+	if (evidence.oauthRefresh) {
+		// A network problem during the token exchange says nothing about the authorization.
+		return evidence.oauthRefresh.invalidGrant ? plain("auth_invalid", "invalid_grant") : plain("transient", "oauth_refresh_unavailable");
+	}
+	if (evidence.networkFailure) return plain("transient", "network_failure");
+
+	const code = errorCode(evidence.body);
+	const status = evidence.status;
+
+	if (code === "usage_limit_reached") {
+		// A plan-level limit is shared by every model; without that evidence stay model-scoped.
+		const planLevel = typeof evidence.body?.plan_type === "string" && evidence.body.plan_type.length > 0;
+		return {
+			kind: "quota",
+			reason: "usage_limit_reached",
+			scope: planLevel ? ACCOUNT_SCOPE : scopeForModel,
+			serverResetAtMs: serverResetAtMs(evidence.body, now),
+		};
+	}
+	if (code === "invalid_grant" || code === "invalid_token" || code === "token_revoked") return plain("auth_invalid", code);
+	if (code === "rate_limit_exceeded") return plain("transient", "rate_limit_exceeded");
+	// usage_not_included means the plan does not cover this model at all; another account is a guess.
+	if (code === "usage_not_included") return plain("fatal", "usage_not_included");
+	if (code === "context_length_exceeded") return plain("fatal", "context_length_exceeded");
+
+	if (status === 401) return plain("auth_retry", "unauthorized");
+	if (status === 429) return plain("transient", "http_429");
+	if (status !== undefined && status >= 500) return plain("transient", `http_${status}`);
+	if (status === 403) return plain("fatal", "http_403");
+	if (status !== undefined && status >= 400) return plain("fatal", `http_${status}`);
+
+	return plain("unknown", "unknown_error");
+}
+
+export interface AccountAvailability {
+	id: string;
+	ordinal: number;
+	/** Why the account cannot be used now; undefined means usable. */
+	unavailable?: { reason: string; untilMs: number | null; serverResetAtMs: number | null };
+	/** The account is usable but should be probed under a lease, after a cooldown ended. */
+	needsProbe: boolean;
+	authInvalid: boolean;
+}
+
+export interface SelectionInput {
+	accounts: AccountAvailability[];
+	/** Sticky preference of this process: keep using the account that currently works. */
+	preferredId?: string;
+	/** Accounts this logical request already tried, so no account is tried twice. */
+	attemptedIds: readonly string[];
+}
+
+/**
+ * Sticky selection: stay on the preferred account while it works, otherwise take the next usable
+ * account in the order they were added. Recovered accounts become candidates again.
+ */
+export function selectAccount(input: SelectionInput): AccountAvailability | undefined {
+	const attempted = new Set(input.attemptedIds);
+	const usable = input.accounts.filter((account) => !attempted.has(account.id) && !account.unavailable && !account.authInvalid);
+	const preferred = usable.find((account) => account.id === input.preferredId);
+	if (preferred) return preferred;
+	return [...usable].sort((left, right) => left.ordinal - right.ordinal)[0];
+}
+
+export type FailoverAction =
+	/** Try the next account for this same request. */
+	| "failover"
+	/** Re-read and refresh the current account once, then retry it. */
+	| "repair"
+	/** Finish the request with the provider's error. */
+	| "stop";
+
+export interface FailoverInput {
+	classification: Classification;
+	/** Text, thinking or a tool call already reached the caller, so nothing may be replayed. */
+	emittedOutput: boolean;
+	/** Another untried, usable account exists for this request. */
+	hasRemainingCandidate: boolean;
+	/** The current account already used its one authentication repair. */
+	repairUsed: boolean;
+}
+
+export function decideFailover(input: FailoverInput): { action: FailoverAction; reason: string } {
+	const { kind } = input.classification;
+	if (kind === "cancelled") return { action: "stop", reason: "cancelled" };
+	if (kind === "transient" || kind === "fatal" || kind === "unknown") return { action: "stop", reason: kind };
+	if (kind === "auth_retry" && !input.repairUsed) return { action: "repair", reason: "authentication_repair" };
+	// Everything below is quota or a proven authorization problem.
+	if (input.emittedOutput) return { action: "stop", reason: "output_already_delivered" };
+	if (!input.hasRemainingCandidate) return { action: "stop", reason: "pool_exhausted" };
+	return { action: "failover", reason: input.classification.reason };
+}