@adeildo/pi-providers 5.1.0 → 5.3.0

package/src/accounts/policy.ts

@@ -0,0 +1,197 @@
+// What the accounts do when the provider refuses a request, by the settings the user chose.
+import type { FeatureScope } from "@adeildo/pi-kit";
+import type { Credential } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { classifyFailure } from "../errors.ts";
+import { pick } from "../ui/picker.ts";
+import { refreshStatus } from "./actions.ts";
+import { reason } from "./describe.ts";
+import { loginFor } from "./interaction.ts";
+import { nativeOf } from "./lift.ts";
+import { login, loginMethods } from "./login.ts";
+import { LOGIN_KEY, NAME } from "./names.ts";
+import { pin, type Pins } from "./pins.ts";
+import { onAuthFailure, onLimit } from "./settings.ts";
+import type { AccountStore } from "./store.ts";
+import type { Account } from "./types.ts";
+
+export function usageLimitLine(
+	message: { provider: string; stopReason?: string; errorMessage?: string },
+	label: string,
+	note?: string,
+): string | undefined {
+	if (message.stopReason !== "error" || message.errorMessage === undefined) return undefined;
+	if (classifyFailure(message.errorMessage, message.provider).kind !== "usage") return undefined;
+	// The marker stops pi's own retry; the window only resets at the provider.
+	const when = note === undefined ? "" : `, ${note}`;
+	return `${message.provider} · ${label}: usage limit reached${when} (quota exceeded)`;
+}
+
+/** Follows the `accounts.onLimit` policy: ask, switch, or stop, and pins the account it moves to. */
+export async function afterLimit(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	ctx: ExtensionContext,
+	providerId: string,
+	currentId: string,
+	detail: string,
+	limited: Map<string, Set<string>> = new Map(),
+): Promise<{ id: string; credential: Credential } | undefined> {
+	const refused = markLimited(limited, providerId, currentId);
+	const mode = onLimit.get(scope);
+	if (mode === "stop") return undefined;
+
+	const next = nextAccount(store.accounts(providerId), currentId, refused);
+	if (next === undefined) return undefined;
+
+	if (mode === "ask") {
+		const current = store.accounts(providerId).find((entry) => entry.id === currentId);
+		const switchNow = `Switch to ${next.label}`;
+		const always = "Always switch when an account hits its limit";
+		const picked = await pick(ctx, `"${current?.label ?? providerId}" hit its limit`, [
+			switchNow,
+			always,
+			"Stop here",
+		]);
+		if (picked === always) scope.settings.set(onLimit, "switch");
+		else if (picked !== switchNow) return undefined;
+	}
+
+	return switchTo(scope, store, pins, ctx, providerId, next, detail);
+}
+
+/** Follows the `accounts.onAuthFailure` policy: sign in again, switch, or stop. */
+export async function afterAuthFailure(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	ctx: ExtensionContext,
+	providerId: string,
+	currentId: string,
+	detail: string,
+): Promise<{ id: string; credential: Credential } | undefined> {
+	const account = store.accounts(providerId).find((entry) => entry.id === currentId);
+	if (account !== undefined) store.markError(providerId, currentId, "auth", detail);
+
+	const mode = onAuthFailure.get(scope);
+	if (mode === "stop") return undefined;
+
+	const next = nextAccount(store.accounts(providerId), currentId, new Set());
+	if (mode === "switch") {
+		return next === undefined
+			? undefined
+			: switchTo(scope, store, pins, ctx, providerId, next, detail);
+	}
+
+	const again = account === undefined ? undefined : `Sign in to ${account.label} again`;
+	const other = next === undefined ? undefined : `Switch to ${next.label}`;
+	const options: string[] = [];
+	if (again !== undefined) options.push(again);
+	if (other !== undefined) options.push(other);
+	options.push("Stop here");
+	if (options.length === 1) return undefined;
+
+	const title =
+		account === undefined
+			? `${providerId} refused the login`
+			: `${providerId} refused the login of "${account.label}"`;
+	const picked = await pick(ctx, title, options);
+	if (picked === again && account !== undefined) {
+		return await signInAgain(store, ctx, providerId, account, detail);
+	}
+	if (picked === other && next !== undefined) {
+		return switchTo(scope, store, pins, ctx, providerId, next, detail);
+	}
+	return undefined;
+}
+
+/** Runs the provider's own login again, keeping the account's name and its pin. */
+export async function signInAgain(
+	store: AccountStore,
+	ctx: ExtensionContext,
+	providerId: string,
+	account: Account,
+	detail?: string,
+): Promise<{ id: string; credential: Credential } | undefined> {
+	const registered = ctx.modelRegistry.getProvider(providerId);
+	// The native provider, so the login does not pass through the lift and ask for a name again.
+	const provider = registered === undefined ? undefined : nativeOf(registered);
+	if (provider === undefined) return undefined;
+	const method = loginMethods(provider).find(
+		(candidate) => candidate.authType === account.credential.type,
+	);
+	if (method === undefined) {
+		ctx.ui.notify(`${NAME}: ${providerId} has no login for this account`, "warning");
+		return undefined;
+	}
+	const session = await loginFor(
+		ctx,
+		`${providerId} · ${account.label}`,
+		new AbortController().signal,
+	);
+	try {
+		const credential = await login(method, session.interaction);
+		const problem = store.setCredential(providerId, account.id, credential);
+		if (problem !== undefined) {
+			ctx.ui.notify(`${NAME}: ${problem}`, "error");
+			return undefined;
+		}
+		store.clearError(providerId, account.id);
+		const why = detail === undefined ? "" : ` (${detail})`;
+		ctx.ui.notify(`${NAME}: ${providerId} · ${account.label} signed in again${why}`, "info");
+		return { id: account.id, credential };
+	} catch (error) {
+		ctx.ui.notify(`${NAME}: ${reason(error)}`, "error");
+		return undefined;
+	} finally {
+		session.close();
+		ctx.ui.setStatus(LOGIN_KEY, undefined);
+	}
+}
+
+function switchTo(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	ctx: ExtensionContext,
+	providerId: string,
+	next: Account,
+	detail: string,
+): { id: string; credential: Credential } {
+	pin(scope, pins, providerId, next.id);
+	refreshStatus(store, pins, ctx);
+	ctx.ui.notify(`${NAME}: ${providerId} now uses ${next.label} (${detail})`, "warning");
+	return { id: next.id, credential: next.credential };
+}
+
+/** Remembers the accounts that refused in this session, so a switch does not try them again. */
+function markLimited(
+	limited: Map<string, Set<string>>,
+	providerId: string,
+	accountId: string,
+): Set<string> {
+	const refused = limited.get(providerId) ?? new Set<string>();
+	refused.add(accountId);
+	limited.set(providerId, refused);
+	return refused;
+}
+
+/** The account after this one that has not refused yet. */
+function nextAccount(
+	list: readonly Account[],
+	currentId: string,
+	refused: ReadonlySet<string>,
+): Account | undefined {
+	if (list.length === 0) return undefined;
+	const index = list.findIndex((account) => account.id === currentId);
+	// An account removed while it served is no longer in the list, so every account is a candidate.
+	if (index < 0) return list.find((account) => !refused.has(account.id));
+	if (list.length < 2) return undefined;
+	for (let step = 1; step < list.length; step++) {
+		const candidate = list[(index + step) % list.length];
+		if (candidate !== undefined && !refused.has(candidate.id)) return candidate;
+	}
+	return undefined;
+}

package/src/accounts/refresh.ts

@@ -0,0 +1,36 @@
+// Refreshing an account's OAuth token, serialized across pi processes: the provider rotates the
+// refresh token on use, and the disk copy wins when another process already refreshed it.
+import type { Credential, OAuthAuth, OAuthCredential } from "@earendil-works/pi-ai";
+
+import { withLock } from "./lock.ts";
+
+const MARGIN_MS = 5 * 60 * 1000;
+
+export function needsRefresh(credential: Credential | undefined): boolean {
+	return credential?.type === "oauth" && credential.expires <= Date.now() + MARGIN_MS;
+}
+
+/** Where a refresh reads the newest copy and writes its result. */
+export interface Renewal {
+	freshen(id: string): Credential | undefined;
+	save(id: string, credential: Credential): void;
+}
+
+/** Refreshes under the shared lock, keeping what another pi already wrote. */
+export async function refreshAccount(
+	oauth: OAuthAuth,
+	renewal: Renewal,
+	id: string,
+	credential: OAuthCredential,
+	signal: AbortSignal,
+	lockPath?: string,
+): Promise<OAuthCredential> {
+	const work = async (): Promise<OAuthCredential> => {
+		const onDisk = renewal.freshen(id);
+		if (onDisk?.type === "oauth" && !needsRefresh(onDisk)) return onDisk;
+		const fresh = await oauth.refresh(credential, signal);
+		renewal.save(id, fresh);
+		return fresh;
+	};
+	return lockPath === undefined ? await work() : await withLock(lockPath, work);
+}

package/src/accounts/screen.ts

@@ -3,22 +3,21 @@
 import type { FeatureScope, Json, ScreenEntry } from "@adeildo/pi-kit";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+import {
+	type AccountsOf,
+	removeAccount,
+	removeQuestion,
+	renameAccount,
+	useAccount,
+} from "./actions.ts";
 import { activeAccount } from "./active.ts";
-import { STATUS_KEY } from "./names.ts";
-import { pin, type Pins } from "./pins.ts";
+import { kindText } from "./login.ts";
+import type { Pins } from "./pins.ts";
 import type { AccountStore } from "./store.ts";
 import type { Account } from "./types.ts";
 
-/** The value of the choice that means pi's own credential. */
-export const DEFAULT_ACCOUNT = "default";
-export const DEFAULT_LABEL = "pi default";
-
 /** Everything a provider's rows share. The label is the section header. */
-interface ProviderGroup {
-	pi: FeatureScope;
-	store: AccountStore;
-	pins: Pins;
-	providerId: string;
+interface ProviderGroup extends AccountsOf {
 	label: string;
 }
 
@@ -28,61 +27,39 @@ export function accountRows(
 	pins: Pins,
 	ctx: ExtensionContext,
 ): ScreenEntry[] {
-	const rows: ScreenEntry[] = [];
-	for (const providerId of store.providerIds().toSorted()) {
-		const group: ProviderGroup = {
-			pi,
-			store,
-			pins,
-			providerId,
-			label: ctx.modelRegistry.getProviderDisplayName(providerId),
-		};
-		rows.push(
-			defaultRow(group),
-			...store.accounts(providerId).flatMap((account) => accountBlock(group, account)),
-		);
-	}
-	return rows;
-}
-
-/** Pi's own credential, as the first account of the provider. */
-function defaultRow(group: ProviderGroup): ScreenEntry {
-	return {
-		kind: "action",
-		id: `accounts.${group.providerId}.default`,
-		section: group.label,
-		label: DEFAULT_LABEL,
-		description: "The credential of /login, which stays in pi's own store.",
-		text: () => (inUse(group) ? "login, in use" : "login"),
-		indent: 1,
-		run: (ctx) => {
-			group.store.setActive(group.providerId, undefined);
-			pin(group.pi, group.pins, group.providerId, null);
-			refreshStatus(group.store, group.pins, ctx);
-			return `${DEFAULT_LABEL} in use`;
-		},
-	};
+	return store
+		.providerIds()
+		.toSorted()
+		.flatMap((providerId) => {
+			const group: ProviderGroup = {
+				pi,
+				store,
+				pins,
+				providerId,
+				label: ctx.modelRegistry.getProviderDisplayName(providerId),
+			};
+			return store.accounts(providerId).flatMap((account) => accountBlock(group, account));
+		});
 }
 
 /** One account, and its actions, one level deeper. */
 function accountBlock(group: ProviderGroup, account: Account): ScreenEntry[] {
-	const subscription = account.credential.type === "oauth";
+	const kind = kindText(account.credential.type);
+	const last = group.store.accounts(group.providerId).length === 1;
 	return [
 		{
 			kind: "action",
 			id: `accounts.${group.providerId}.${account.id}.use`,
 			section: group.label,
 			label: account.label,
-			description: subscription ? "Saved from a subscription login." : "Saved as an API key.",
-			text: () => {
-				const kind = subscription ? "subscription" : "api key";
-				return inUse(group, account) ? `${kind}, in use` : kind;
-			},
+			description:
+				account.credential.type === "oauth"
+					? "Saved from a subscription login."
+					: "Saved as an API key.",
+			text: () => (inUse(group, account) ? `${kind}, in use` : kind),
 			indent: 1,
 			run: (ctx) => {
-				group.store.setActive(group.providerId, account.id);
-				pin(group.pi, group.pins, group.providerId, account.id);
-				refreshStatus(group.store, group.pins, ctx);
+				useAccount(group, ctx, account.id);
 				return `${account.label} in use`;
 			},
 		},
@@ -97,9 +74,7 @@ function accountBlock(group: ProviderGroup, account: Account): ScreenEntry[] {
 			get: () => account.label,
 			set: (value: Json, ctx) => {
 				if (typeof value !== "string") return "name it";
-				const problem = group.store.rename(group.providerId, account.id, value);
-				if (problem === undefined) refreshStatus(group.store, group.pins, ctx);
-				return problem;
+				return renameAccount(group, ctx, account.id, value);
 			},
 		},
 		{
@@ -109,39 +84,13 @@ function accountBlock(group: ProviderGroup, account: Account): ScreenEntry[] {
 			label: "Remove",
 			description: `Forget the "${account.label}" credential.`,
 			text: () => account.label,
-			confirm: `Remove the ${group.providerId} account "${account.label}"?`,
+			confirm: removeQuestion(group.label, account.label, last),
 			indent: 2,
-			run: (ctx) => {
-				const problem = group.store.remove(group.providerId, account.id);
-				if (problem !== undefined) return problem;
-				if (group.pins.get(group.providerId) === account.id) {
-					pin(group.pi, group.pins, group.providerId, null);
-				}
-				refreshStatus(group.store, group.pins, ctx);
-				return `${account.label} removed`;
-			},
+			run: (ctx) => removeAccount(group, ctx, account.id) ?? `${account.label} removed`,
 		},
 	];
 }
 
-function inUse(group: ProviderGroup, account?: Account): boolean {
-	const active = activeAccount(group.store, group.pins, group.providerId);
-	return account === undefined ? active === undefined : active?.id === account.id;
-}
-
-/** The label of the account the current model uses, or undefined when there is nothing to say. */
-export function accountStatus(
-	store: AccountStore,
-	pins: Pins,
-	ctx: ExtensionContext,
-): string | undefined {
-	const providerId = ctx.model?.provider;
-	if (providerId === undefined) return undefined;
-	if (store.accounts(providerId).length === 0) return undefined;
-	return activeAccount(store, pins, providerId)?.label ?? "pi";
-}
-
-/** Publishes the account next to the model, where every other piece reads it. */
-export function refreshStatus(store: AccountStore, pins: Pins, ctx: ExtensionContext): void {
-	ctx.ui.setStatus(STATUS_KEY, accountStatus(store, pins, ctx));
+function inUse(group: ProviderGroup, account: Account): boolean {
+	return activeAccount(group.store, group.pins, group.providerId)?.id === account.id;
 }

package/src/accounts/settings.ts

@@ -0,0 +1,38 @@
+import { literal, setting } from "@adeildo/pi-kit";
+
+/** What a policy does when the provider will not serve an account. */
+export const WHEN_LIMITED = ["ask", "switch", "stop"] as const;
+export type WhenLimited = (typeof WHEN_LIMITED)[number];
+
+function policy(id: string, label: string, description: string) {
+	return setting<WhenLimited>({
+		id,
+		default: "ask",
+		decoder: literal(...WHEN_LIMITED),
+		ui: {
+			section: "Accounts",
+			label,
+			description,
+			control: {
+				type: "choice",
+				options: [
+					{ value: "ask", label: "ask me first" },
+					{ value: "switch", label: "switch on its own" },
+					{ value: "stop", label: "stop and tell me" },
+				],
+			},
+		},
+	});
+}
+
+export const onLimit = policy(
+	"accounts.onLimit",
+	"When an account hits its limit",
+	"Ask me first, switch on its own, or stop and tell me.",
+);
+
+export const onAuthFailure = policy(
+	"accounts.onAuthFailure",
+	"When a login is refused",
+	"Ask me first, switch to another account, or stop and tell me.",
+);

package/src/accounts/store.ts

@@ -6,8 +6,9 @@ import { dirname, join } from "node:path";
 import { globalSettingsPath, isObject, readSettingsFile, writeSettingsFile } from "@adeildo/pi-kit";
 import type { Credential } from "@earendil-works/pi-ai";
 
+import { FAILURE_KINDS, type FailureKind } from "../errors.ts";
 import { reason } from "./describe.ts";
-import type { Account, AccountsFile, ProviderAccounts } from "./types.ts";
+import type { Account, AccountHealth, AccountsFile, ProviderAccounts } from "./types.ts";
 
 export const ACCOUNTS_FILE = "accounts.json";
 
@@ -15,6 +16,11 @@ export function accountsPath(): string {
 	return join(dirname(globalSettingsPath()), ACCOUNTS_FILE);
 }
 
+/** The file two pi processes take while they refresh the same accounts. */
+export function accountsLockPath(): string {
+	return join(dirname(globalSettingsPath()), "accounts.lock");
+}
+
 /** What an add produced: the account it wrote, or why it did not. */
 export interface Added {
 	account?: Account;
@@ -78,7 +84,7 @@ export class AccountStore {
 
 	rename(providerId: string, id: string, label: string): string | undefined {
 		return this.edit((providers) => {
-			const account = providers[providerId]?.accounts.find((entry) => entry.id === id);
+			const account = find(providers, providerId, id);
 			if (account !== undefined) account.label = label.trim() || account.label;
 		});
 	}
@@ -96,11 +102,54 @@ export class AccountStore {
 	/** Keeps the credential a refresh produced. */
 	setCredential(providerId: string, id: string, credential: Credential): string | undefined {
 		return this.edit((providers) => {
-			const account = providers[providerId]?.accounts.find((entry) => entry.id === id);
+			const account = find(providers, providerId, id);
 			if (account !== undefined) account.credential = credential;
 		});
 	}
 
+	/** Remembers the last refusal of an account, which the picker shows. */
+	markError(
+		providerId: string,
+		id: string,
+		kind: FailureKind,
+		message: string,
+	): string | undefined {
+		return this.editHealth(providerId, id, (health) => {
+			health.lastError = { at: Date.now(), kind, message };
+		});
+	}
+
+	/** Forgets the last refusal, after a sign-in or a request that worked. */
+	clearError(providerId: string, id: string): string | undefined {
+		return this.editHealth(providerId, id, (health) => {
+			delete health.lastError;
+		});
+	}
+
+	/** Remembers that the plan is spent until a time, or forgets it with undefined. */
+	markLimited(providerId: string, id: string, until: number | undefined): string | undefined {
+		return this.editHealth(providerId, id, (health) => {
+			if (until === undefined) delete health.limitedUntil;
+			else health.limitedUntil = until;
+		});
+	}
+
+	private editHealth(
+		providerId: string,
+		id: string,
+		change: (health: AccountHealth) => void,
+	): string | undefined {
+		return this.edit((providers) => {
+			const account = find(providers, providerId, id);
+			if (account === undefined) return;
+			const health = account.health ?? {};
+			change(health);
+			if (health.lastError === undefined && health.limitedUntil === undefined)
+				delete account.health;
+			else account.health = health;
+		});
+	}
+
 	private file(): AccountsFile {
 		if (this.data === undefined) this.reload();
 		return this.data ?? { version: 1, providers: {} };
@@ -117,6 +166,14 @@ export class AccountStore {
 	}
 }
 
+function find(
+	providers: Record<string, ProviderAccounts>,
+	providerId: string,
+	id: string,
+): Account | undefined {
+	return providers[providerId]?.accounts.find((account) => account.id === id);
+}
+
 function readAccounts(path: string): {
 	providers: Record<string, ProviderAccounts>;
 	warnings: string[];
@@ -130,7 +187,9 @@ function readAccounts(path: string): {
 	const providers: Record<string, ProviderAccounts> = {};
 	for (const [providerId, value] of Object.entries(source)) {
 		if (!isObject(value) || !Array.isArray(value.accounts)) continue;
-		const accounts = value.accounts.filter(isAccount);
+		const accounts = value.accounts
+			.map(asAccount)
+			.filter((account): account is Account => account !== undefined);
 		if (accounts.length === 0) continue;
 		providers[providerId] = {
 			accounts,
@@ -149,13 +208,43 @@ function writeAccounts(path: string, data: AccountsFile): string | undefined {
 	}
 }
 
-function isAccount(input: unknown): input is Account {
-	return (
-		isObject(input) &&
-		typeof input.id === "string" &&
-		typeof input.label === "string" &&
-		isCredential(input.credential)
-	);
+function asAccount(input: unknown): Account | undefined {
+	if (!isObject(input)) return undefined;
+	if (
+		typeof input.id !== "string" ||
+		typeof input.label !== "string" ||
+		!isCredential(input.credential)
+	) {
+		return undefined;
+	}
+	const health = readHealth(input.health);
+	return {
+		id: input.id,
+		label: input.label,
+		credential: input.credential,
+		...(health === undefined ? {} : { health }),
+	};
+}
+
+/** Keeps the health fields that decode, so a hand edit cannot break the account. */
+function readHealth(input: unknown): AccountHealth | undefined {
+	if (!isObject(input)) return undefined;
+	const health: AccountHealth = {};
+	const error = input.lastError;
+	if (
+		isObject(error) &&
+		typeof error.at === "number" &&
+		isFailureKind(error.kind) &&
+		typeof error.message === "string"
+	) {
+		health.lastError = { at: error.at, kind: error.kind, message: error.message };
+	}
+	if (typeof input.limitedUntil === "number") health.limitedUntil = input.limitedUntil;
+	return health.lastError === undefined && health.limitedUntil === undefined ? undefined : health;
+}
+
+function isFailureKind(value: unknown): value is FailureKind {
+	return typeof value === "string" && (FAILURE_KINDS as readonly string[]).includes(value);
 }
 
 function isCredential(input: unknown): input is Credential {

package/src/accounts/types.ts

@@ -1,16 +1,31 @@
 import type { Credential } from "@earendil-works/pi-ai";
 
-/** One extra credential with a name. Pi's own credential stays in pi's store, not here. */
+import type { FailureKind } from "../errors.ts";
+
+/** What an account's last failure was, and until when the plan says it is spent. */
+export interface AccountHealth {
+	/** The last refusal, kept so the picker can say the account needs a sign-in. */
+	lastError?: {
+		at: number;
+		kind: FailureKind;
+		message: string;
+	};
+	/** The plan is spent until this unix second, when a reading said so. */
+	limitedUntil?: number;
+}
+
+/** One credential with a name. A provider with accounts serves every request from one of them. */
 export interface Account {
 	/** Stable id, so renaming an account keeps a session pinned to it. */
 	id: string;
 	label: string;
 	credential: Credential;
+	health?: AccountHealth;
 }
 
-/** The extra accounts of one provider, and the one the store prefers. */
+/** The accounts of one provider, and the one a new session starts on. */
 export interface ProviderAccounts {
-	/** The id of the account the store prefers. Absent means pi's own credential. */
+	/** The id of the account the store prefers. Absent means the first one. */
 	active?: string;
 	accounts: Account[];
 }