@adeildo/pi-providers 4.0.0 → 5.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@adeildo/pi-providers)](https://www.npmjs.com/package/@adeildo/pi-providers)
 
-Provider features for [Pi](https://pi.dev). It has one, `subscription`.
+Provider features for [Pi](https://pi.dev). It has two, `subscription` and `accounts`.
 
 ```bash
 pi install npm:@adeildo/pi-providers
@@ -37,6 +37,7 @@ In `~/.pi/agent/extensions/pi-harness/settings.json`:
 | Key                              | Default     | Does                                                                                                    |
 | -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
 | `subscription.claudeCodeVersion` | `"2.1.280"` | The Claude Code version Pi reports. Anthropic won't serve newer models to versions it considers too old |
+| `accounts.onLimit`               | `"ask"`     | What a quota or rate limit does when another account exists: `"ask"`, `"switch"`, or `"stop"`           |
 
 When a request comes back with `400 claude_code_version_too_old`, raise the version:
 
@@ -44,6 +45,31 @@ When a request comes back with `400 claude_code_version_too_old`, raise the vers
 { "subscription": { "claudeCodeVersion": "2.1.280" } }
 ```
 
+## accounts
+
+Pi keeps one credential per provider: the one `/login` wrote. `accounts` keeps more. The credential of `/login` stays as `pi default`, and every other account is an extra credential with a name.
+
+```
+/accounts anthropic
+```
+
+Picks the provider and its login method, asks for a name, and runs the login Pi already has, so no OAuth lives in this package. An account shows a short kind:
+
+- `login` is the credential of `/login`, which cannot be copied out of `auth.json`.
+- `oauth` is a subscription token, billed to its own plan.
+- `key` is an API key.
+
+Switch the account:
+
+- `alt+a` picks the account of the current model's provider.
+- The Providers tab of `Alt+S` lists the accounts: choose the one to use, rename one, or remove one.
+
+When a request is refused for a quota or a rate limit, and another account of that provider exists, `accounts.onLimit` decides what happens: `ask` opens a dialog, with the option to always switch from then on; `switch` moves on its own; `stop` leaves the error in front of you. Only a limit that arrives before anything was shown switches, so the retry never repeats output you already saw.
+
+The account in use shows next to the model. The session remembers its choice, so a resume or a fork comes back with the same one, and `pi default` is what a request uses until you choose another.
+
+Only the chat streams are lifted. Image generation, classifier calls and deferred responses of the provider still use pi's own credential.
+
 ## Credit
 
 The idea and the fingerprint come from [pi-claude-max](https://github.com/bradennss/pi-claude-max) by Braden Lamb, MIT. This is a rewrite. It reads the version from settings, carries pi's cache breakpoints over instead of dropping the one-hour TTL, moves every system block after the identity instead of only the second, and checks for an OAuth token instead of the provider name.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adeildo/pi-providers",
-	"version": "4.0.0",
+	"version": "5.0.0",
 	"description": "Provider features for Pi. Bills Anthropic OAuth requests to the Claude Pro or Max plan instead of extra usage.",
 	"keywords": [
 		"anthropic",
@@ -37,11 +37,12 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@adeildo/pi-kit": "4.0.0"
+		"@adeildo/pi-kit": "5.0.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-coding-agent": "*"
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
 	},
 	"pi": {
 		"extensions": [

package/src/accounts/active.ts

@@ -0,0 +1,19 @@
+// The one place that answers which account a request uses.
+import type { Pins } from "./pins.ts";
+import type { AccountStore } from "./store.ts";
+import type { Account } from "./types.ts";
+
+/**
+ * The account a request uses: the session pin, else the store's choice, else none, which means pi's
+ * own credential. A request never falls back to "the first account", so adding one does not take
+ * over a session by itself.
+ */
+export function activeAccount(
+	store: AccountStore,
+	pins: Pins,
+	providerId: string,
+): Account | undefined {
+	const pinned = pins.has(providerId) ? pins.get(providerId) : store.active(providerId)?.id;
+	if (pinned === null || pinned === undefined) return undefined;
+	return store.accounts(providerId).find((account) => account.id === pinned);
+}

package/src/accounts/describe.ts

@@ -0,0 +1,3 @@
+export function reason(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/accounts/feature.ts

@@ -0,0 +1,279 @@
+import { defineFeature, literal, setting } from "@adeildo/pi-kit";
+import type { FeatureScope } from "@adeildo/pi-kit";
+import type { Credential, Provider } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+
+import { activeAccount } from "./active.ts";
+import { reason } from "./describe.ts";
+import { interactionFor } from "./interaction.ts";
+import { liftProvider, nativeOf, type AccountSession } from "./lift.ts";
+import { login, loginMethods, type LoginMethod } from "./login.ts";
+import { LOGIN_KEY, NAME, STATUS_KEY } from "./names.ts";
+import { pin, replay, type Pins } from "./pins.ts";
+import { accountRows, DEFAULT_ACCOUNT, DEFAULT_LABEL, refreshStatus } from "./screen.ts";
+import { AccountStore } from "./store.ts";
+import type { Account } from "./types.ts";
+
+/** What happens when an account hits the limit of its plan. */
+export const WHEN_LIMITED = ["ask", "switch", "stop"] as const;
+export type WhenLimited = (typeof WHEN_LIMITED)[number];
+
+export const onLimit = setting<WhenLimited>({
+	id: "accounts.onLimit",
+	default: "ask",
+	decoder: literal(...WHEN_LIMITED),
+	ui: {
+		section: "Accounts",
+		label: "When an account hits its limit",
+		description: "Ask me first, switch on its own, or stop and tell me.",
+		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 accounts = defineFeature({
+	id: "accounts",
+	description: "Use more than one credential of the same provider",
+	tab: "Providers",
+	settings: [onLimit],
+	setup(scope) {
+		const store = new AccountStore();
+		const pins: Pins = new Map();
+
+		scope.screen.rows((ctx) => accountRows(scope, store, pins, ctx));
+		scope.on("model_select", (_event, ctx) => refreshStatus(store, pins, ctx));
+		scope.on("session_shutdown", (_event, ctx) => ctx.ui.setStatus(STATUS_KEY, undefined));
+
+		scope.onSessionStart((ctx) => {
+			for (const warning of store.reload()) scope.warn(warning);
+			pins.clear();
+			for (const [provider, account] of replay(ctx.sessionManager.getBranch())) {
+				pins.set(provider, account);
+			}
+			for (const providerId of new Set([...store.providerIds(), ...pins.keys()])) {
+				lift(scope, store, pins, ctx, providerId);
+			}
+			refreshStatus(store, pins, ctx);
+		});
+
+		scope.registerShortcut(Key.alt("a"), {
+			description: `${NAME}: pick the account of the current provider`,
+			handler: (ctx) => pickAccount(scope, store, pins, ctx),
+		});
+
+		scope.registerCommand("accounts", {
+			description: `${NAME}: add an account for a provider`,
+			handler: (args, ctx) => addAccount(scope, store, pins, args, ctx),
+		});
+	},
+});
+
+function sessionFor(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	ctx: ExtensionContext,
+	providerId: string,
+): AccountSession {
+	return {
+		resolve: () => {
+			const account = activeAccount(store, pins, providerId);
+			return account === undefined ? undefined : { id: account.id, credential: account.credential };
+		},
+		save: (id, credential) => void store.setCredential(providerId, id, credential),
+		afterLimit: (currentId, detail) =>
+			afterLimit(scope, store, pins, ctx, providerId, currentId, detail),
+	};
+}
+
+/** 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,
+): Promise<{ id: string; credential: Credential } | undefined> {
+	const mode = onLimit.get(scope);
+	if (mode === "stop") return undefined;
+
+	const next = nextAccount(store.accounts(providerId), currentId);
+	if (next === undefined) return undefined;
+
+	if (mode === "ask") {
+		const once = `Switch to ${next.label}`;
+		const always = "Always switch when an account hits its limit";
+		const picked = await ctx.ui.select(`"${currentId}" hit its limit`, [once, always, "Stop here"]);
+		if (picked === always) scope.settings.set(onLimit, "switch");
+		else if (picked !== once) return undefined;
+	}
+
+	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 };
+}
+
+/** The account after this one in the list, so a limit moves on instead of repeating. */
+function nextAccount(list: readonly Account[], currentId: string): Account | undefined {
+	if (list.length < 2) return undefined;
+	const index = list.findIndex((account) => account.id === currentId);
+	return list[(index + 1) % list.length];
+}
+
+function lift(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	ctx: ExtensionContext,
+	providerId: string,
+): void {
+	// A pin with no account left behind it injects nothing, so re-registering it would only cost a
+	// model-registry rebuild.
+	if (!store.has(providerId)) return;
+
+	// `getProvider` returns the lifted provider once we registered one, so unwrap it before wrapping
+	// again. After a `/reload` it returns the built-in one, which is unwrapped too.
+	const provider = ctx.modelRegistry.getProvider(providerId);
+	if (provider === undefined) {
+		scope.warn(`no provider "${providerId}", so its accounts do nothing`);
+		return;
+	}
+	scope.registerProvider(
+		liftProvider(nativeOf(provider), sessionFor(scope, store, pins, ctx, providerId)),
+	);
+}
+
+async function pickAccount(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	ctx: ExtensionContext,
+): Promise<void> {
+	if (!ctx.hasUI) {
+		scope.warn("no dialog to pick an account");
+		return;
+	}
+
+	const providerId = ctx.model?.provider;
+	if (providerId === undefined) {
+		ctx.ui.notify(`${NAME}: no model selected`, "warning");
+		return;
+	}
+	const entries = store.accounts(providerId);
+	if (entries.length === 0) {
+		ctx.ui.notify(`${NAME}: ${providerId} has no extra account yet`, "info");
+		return;
+	}
+
+	const current = activeAccount(store, pins, providerId)?.id ?? DEFAULT_ACCOUNT;
+	const choices = [
+		{ id: DEFAULT_ACCOUNT, label: DEFAULT_LABEL, kind: "login" },
+		...entries.map((account) => ({
+			id: account.id,
+			label: account.label,
+			kind: account.credential.type === "oauth" ? "oauth" : "key",
+		})),
+	];
+	const options = choices.map((choice, index) => {
+		const here = choice.id === current ? " ✓" : "";
+		return `${index + 1}  ${choice.label} (${choice.kind})${here}`;
+	});
+
+	const picked = await ctx.ui.select(`Account for ${providerId}`, options);
+	const index = picked === undefined ? -1 : options.indexOf(picked);
+	if (index < 0) return;
+
+	const choice = choices[index];
+	if (choice === undefined) return;
+	pin(scope, pins, providerId, choice.id === DEFAULT_ACCOUNT ? null : choice.id);
+	refreshStatus(store, pins, ctx);
+	ctx.ui.notify(`${NAME}: ${providerId} uses ${choice.label}`, "info");
+}
+
+async function addAccount(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	args: string,
+	ctx: ExtensionContext,
+): Promise<void> {
+	if (!ctx.hasUI) {
+		scope.warn("no dialog to add an account");
+		return;
+	}
+
+	const providerId = args.trim() || (await pickProvider(ctx));
+	if (providerId === undefined) return;
+	const provider = ctx.modelRegistry.getProvider(providerId);
+	if (provider === undefined) {
+		ctx.ui.notify(`${NAME}: no provider "${providerId}"`, "error");
+		return;
+	}
+	const method = await pickMethod(ctx, provider);
+	if (method === undefined) return;
+
+	const label =
+		(await ctx.ui.input(`Name this ${providerId} account`, providerId))?.trim() || providerId;
+	try {
+		const credential = await login(
+			method,
+			interactionFor(ctx, providerId, new AbortController().signal),
+		);
+		const added = store.add(providerId, label, credential);
+		if (added.account === undefined) {
+			ctx.ui.notify(`${NAME}: ${added.problem}`, "error");
+			return;
+		}
+		store.setActive(providerId, added.account.id);
+		pin(scope, pins, providerId, added.account.id);
+		// The first account of a provider was not lifted at session start, so lift it now.
+		if (store.accounts(providerId).length === 1) lift(scope, store, pins, ctx, providerId);
+		refreshStatus(store, pins, ctx);
+		ctx.ui.notify(`${NAME}: ${providerId} account "${label}" added`, "info");
+	} catch (error) {
+		ctx.ui.notify(`${NAME}: ${reason(error)}`, "error");
+	} finally {
+		ctx.ui.setStatus(LOGIN_KEY, undefined);
+	}
+}
+
+async function pickProvider(ctx: ExtensionContext): Promise<string | undefined> {
+	const candidates: string[] = [];
+	for (const providerId of new Set(ctx.modelRegistry.getAll().map((model) => model.provider))) {
+		const provider = ctx.modelRegistry.getProvider(providerId);
+		if (provider !== undefined && loginMethods(provider).length > 0) candidates.push(providerId);
+	}
+	const list = candidates.toSorted();
+	if (list.length === 0) {
+		ctx.ui.notify(`${NAME}: no provider offers a login`, "warning");
+		return undefined;
+	}
+	if (list.length === 1) return list[0];
+	return await ctx.ui.select("Provider", list);
+}
+
+async function pickMethod(
+	ctx: ExtensionContext,
+	provider: Provider,
+): Promise<LoginMethod | undefined> {
+	const methods = loginMethods(provider);
+	if (methods.length === 0) {
+		ctx.ui.notify(`${NAME}: ${provider.id} has no login method`, "warning");
+		return undefined;
+	}
+	if (methods.length === 1) return methods[0];
+
+	const labels = methods.map((method) => method.label);
+	const picked = await ctx.ui.select(`${provider.id} login`, labels);
+	return methods.find((method) => method.label === picked);
+}

package/src/accounts/interaction.ts

@@ -0,0 +1,60 @@
+// The provider's own login asks for a code, a URL or a choice. These dialogs answer for it, so no
+// OAuth and no key prompt live in this package.
+import type { AuthEvent, ProviderAuthInteraction } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { LOGIN_KEY } from "./names.ts";
+
+export function interactionFor(
+	ctx: ExtensionContext,
+	label: string,
+	signal: AbortSignal,
+): ProviderAuthInteraction {
+	return {
+		signal,
+		async prompt(prompt) {
+			if (prompt.type === "select") {
+				const options = prompt.options.map((option) => option.label);
+				const picked = await ctx.ui.select(prompt.message, options, { signal: prompt.signal });
+				if (picked === undefined) throw new Error(`${label}: login cancelled`);
+				return prompt.options.find((option) => option.label === picked)?.id ?? picked;
+			}
+			const value = await ctx.ui.input(prompt.message, prompt.placeholder, {
+				signal: prompt.signal,
+			});
+			if (value === undefined) throw new Error(`${label}: login cancelled`);
+			return value;
+		},
+		notify(event) {
+			show(ctx, event);
+		},
+	};
+}
+
+function show(ctx: ExtensionContext, event: AuthEvent): void {
+	switch (event.type) {
+		case "info":
+			ctx.ui.notify(withLinks(event.message, event.links), "info");
+			break;
+		case "auth_url":
+			ctx.ui.notify(
+				withLinks(event.instructions ?? "Open this URL to sign in", [{ url: event.url }]),
+				"info",
+			);
+			break;
+		case "device_code":
+			ctx.ui.notify(`Enter ${event.userCode} at ${event.verificationUri}`, "info");
+			break;
+		case "progress":
+			ctx.ui.setStatus(LOGIN_KEY, event.message);
+			break;
+	}
+}
+
+function withLinks(
+	message: string,
+	links: readonly { url: string; label?: string }[] | undefined,
+): string {
+	if (links === undefined || links.length === 0) return message;
+	return `${message} ${links.map((link) => link.label ?? link.url).join(" ")}`;
+}

package/src/accounts/lift.ts

@@ -0,0 +1,331 @@
+// A provider with accounts is re-registered with its stream wrapped: each request resolves the
+// credential of the active account and injects it, so one provider keeps one model list. The auth
+// methods of the native provider do the work, so this file never speaks OAuth.
+import {
+	defaultProviderAuthContext,
+	lazyStream,
+	type Api,
+	type ApiStreamOptions,
+	type AssistantMessage,
+	type AssistantMessageEvent,
+	type AssistantMessageEventStream,
+	type Credential,
+	type Model,
+	type ModelAuth,
+	type OAuthAuth,
+	type OAuthCredential,
+	type Provider,
+	type ProviderAuth,
+	type ProviderEnv,
+	type ProviderHeaders,
+	type SimpleStreamOptions,
+	type StreamOptions,
+	type TranscriptContext,
+} from "@earendil-works/pi-ai";
+
+/** The account the next request uses, and where a refreshed token is kept. */
+export interface AccountSession {
+	resolve(): { id: string; credential: Credential } | undefined;
+	save(id: string, credential: Credential): void;
+	/** The account to try after this one hit a limit, or undefined to surface the error. */
+	afterLimit(
+		currentId: string,
+		detail: string,
+	): Promise<{ id: string; credential: Credential } | undefined>;
+}
+
+/** The native provider behind a lifted one, so lifting twice wraps the same object. */
+const NATIVE = Symbol.for("pi-providers.accounts.native");
+
+/** The provider a lifted one came from, or the provider itself. */
+export function nativeOf(provider: Provider): Provider {
+	return (provider as { [NATIVE]?: Provider })[NATIVE] ?? provider;
+}
+
+export function liftProvider(provider: Provider, session: AccountSession): Provider {
+	// Every method is delegated by hand, not by spread: the native may keep methods on a prototype,
+	// and a copied method would lose its `this`. One refresh runs per account at a time.
+	const refreshing = new Map<string, Promise<OAuthCredential>>();
+	const getAllModels = provider.getAllModels;
+	const refreshModels = provider.refreshModels;
+	const filterModels = provider.filterModels;
+	const filterAllModels = provider.filterAllModels;
+	const fetchDeferred = provider.fetchDeferred;
+	const cancelDeferred = provider.cancelDeferred;
+	const generateImages = provider.generateImages;
+	const classify = provider.classify;
+
+	const lifted: Provider = {
+		id: provider.id,
+		name: provider.name,
+		...(provider.baseUrl === undefined ? {} : { baseUrl: provider.baseUrl }),
+		...(provider.headers === undefined ? {} : { headers: provider.headers }),
+		auth: liftedAuth(provider, session),
+		getModels: () => provider.getModels(),
+		...(getAllModels === undefined ? {} : { getAllModels: () => getAllModels() }),
+		...(refreshModels === undefined ? {} : { refreshModels: (context) => refreshModels(context) }),
+		...(filterModels === undefined
+			? {}
+			: { filterModels: (models, credential) => filterModels(models, credential) }),
+		...(filterAllModels === undefined
+			? {}
+			: { filterAllModels: (models, credential) => filterAllModels(models, credential) }),
+		stream<T extends Api>(
+			model: Model<T>,
+			context: TranscriptContext,
+			options?: ApiStreamOptions<T>,
+		) {
+			return accountStream(provider, session, refreshing, "stream", model, context, options);
+		},
+		streamSimple(model, context, options) {
+			return accountStream(provider, session, refreshing, "streamSimple", model, context, options);
+		},
+		...(fetchDeferred === undefined
+			? {}
+			: { fetchDeferred: (model, handle, options) => fetchDeferred(model, handle, options) }),
+		...(cancelDeferred === undefined
+			? {}
+			: { cancelDeferred: (model, handle, options) => cancelDeferred(model, handle, options) }),
+		...(generateImages === undefined
+			? {}
+			: { generateImages: (model, context, options) => generateImages(model, context, options) }),
+		...(classify === undefined
+			? {}
+			: { classify: (model, context, options) => classify(model, context, options) }),
+	};
+	Object.defineProperty(lifted, NATIVE, { value: provider, enumerable: false });
+	return lifted;
+}
+
+type Options = StreamOptions;
+
+function accountStream(
+	provider: Provider,
+	session: AccountSession,
+	refreshing: Map<string, Promise<OAuthCredential>>,
+	kind: "stream" | "streamSimple",
+	model: Model<Api>,
+	context: TranscriptContext,
+	options?: Options,
+): AssistantMessageEventStream {
+	const first = session.resolve();
+	if (first === undefined) return call(provider, kind, model, context, options ?? {});
+
+	const settled = options ?? {};
+	return lazyStream(model, async () =>
+		attempts(provider, session, refreshing, kind, model, context, settled, first),
+	);
+}
+
+/** One account may serve a limit that another one does not have. */
+const MAX_ATTEMPTS = 3;
+
+// A quota or a rate limit belongs to the account, so another one can serve. A busy server cannot.
+const LIMIT_PATTERN = /quota|rate[ _-]?limit|too many requests|usage limit|429/i;
+
+async function* attempts(
+	provider: Provider,
+	session: AccountSession,
+	refreshing: Map<string, Promise<OAuthCredential>>,
+	kind: "stream" | "streamSimple",
+	model: Model<Api>,
+	context: TranscriptContext,
+	options: Options,
+	first: { id: string; credential: Credential },
+): AsyncGenerator<AssistantMessageEvent> {
+	let account = first;
+
+	for (let attempt = 1; ; attempt++) {
+		// oxlint-disable-next-line no-await-in-loop -- an attempt starts only after the one before it.
+		const resolved = await resolveAuth(provider, session, refreshing, account, options.signal);
+		const withAuth = applyAuth(resolved, model, options);
+		const source = call(provider, kind, withAuth.model, context, withAuth.options);
+
+		// Hold the events until something is visible: a retry on another account must not repeat a
+		// message the caller already saw.
+		const buffered: AssistantMessageEvent[] = [];
+		let output = false;
+		let failure: AssistantMessage | undefined;
+		let thrown: unknown;
+		try {
+			// oxlint-disable-next-line no-await-in-loop -- a stream is read one event at a time.
+			for await (const event of source) {
+				if (isContent(event)) {
+					if (!output) {
+						output = true;
+						yield* buffered;
+						buffered.length = 0;
+					}
+					yield event;
+					continue;
+				}
+				if (event.type === "error") failure = event.error;
+				if (output) yield event;
+				else buffered.push(event);
+			}
+		} catch (error) {
+			thrown = error;
+		}
+
+		if (!output && attempt < MAX_ATTEMPTS && failure !== undefined) {
+			const text = failure.errorMessage;
+			if (text !== undefined && LIMIT_PATTERN.test(text)) {
+				// oxlint-disable-next-line no-await-in-loop -- the answer comes from the user.
+				const next = await session.afterLimit(account.id, text);
+				if (next !== undefined) {
+					account = next;
+					continue;
+				}
+			}
+		}
+
+		yield* buffered;
+		if (thrown !== undefined) throw thrown;
+		return;
+	}
+}
+
+function isContent(event: AssistantMessageEvent): boolean {
+	return event.type !== "start" && event.type !== "done" && event.type !== "error";
+}
+
+function call(
+	provider: Provider,
+	kind: "stream" | "streamSimple",
+	model: Model<Api>,
+	context: TranscriptContext,
+	options: Options,
+): AssistantMessageEventStream {
+	if (kind === "streamSimple")
+		return provider.streamSimple(model, context, options as SimpleStreamOptions);
+	return provider.stream(model, context, options as ApiStreamOptions<Api>);
+}
+
+interface ResolvedAuth {
+	auth: ModelAuth;
+	env?: ProviderEnv;
+}
+
+async function resolveAuth(
+	provider: Provider,
+	session: AccountSession,
+	refreshing: Map<string, Promise<OAuthCredential>>,
+	account: { id: string; credential: Credential },
+	signal: AbortSignal | undefined,
+): Promise<ResolvedAuth> {
+	const abort = signal ?? new AbortController().signal;
+	if (account.credential.type === "oauth") {
+		const oauth = provider.auth.oauth;
+		if (oauth === undefined) return { auth: {} };
+		const fresh = await refreshToken(
+			oauth,
+			session,
+			refreshing,
+			account.id,
+			account.credential,
+			abort,
+		);
+		return { auth: await oauth.toAuth(fresh) };
+	}
+
+	const apiKey = provider.auth.apiKey;
+	if (apiKey === undefined) return { auth: {} };
+	const resolved = await apiKey.resolve({
+		ctx: defaultProviderAuthContext(),
+		credential: account.credential,
+		signal: abort,
+	});
+	return resolved === undefined ? { auth: {} } : { auth: resolved.auth, env: resolved.env };
+}
+
+// Pi refreshes its own token under the store lock, five minutes early. Ours is ours to refresh, and
+// one refresh per account is shared, so two requests cannot rotate the token twice.
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+
+async function refreshToken(
+	oauth: OAuthAuth,
+	session: AccountSession,
+	refreshing: Map<string, Promise<OAuthCredential>>,
+	accountId: string,
+	credential: OAuthCredential,
+	signal: AbortSignal,
+): Promise<OAuthCredential> {
+	if (credential.expires > Date.now() + REFRESH_MARGIN_MS) return credential;
+
+	const inFlight = refreshing.get(accountId);
+	if (inFlight !== undefined) return await inFlight;
+
+	const task = oauth.refresh(credential, signal).then((fresh) => {
+		session.save(accountId, fresh);
+		return fresh;
+	});
+	refreshing.set(accountId, task);
+	try {
+		return await task;
+	} finally {
+		refreshing.delete(accountId);
+	}
+}
+
+function applyAuth(
+	resolved: ResolvedAuth,
+	model: Model<Api>,
+	options: Options,
+): { model: Model<Api>; options: Options } {
+	const next: Options = { ...options };
+	if (resolved.auth.apiKey === undefined) delete next.apiKey;
+	else next.apiKey = resolved.auth.apiKey;
+
+	const headers = mergeHeaders(options.headers, resolved.auth.headers);
+	if (headers === undefined) delete next.headers;
+	else next.headers = headers;
+
+	if (resolved.env === undefined && options.env === undefined) delete next.env;
+	else next.env = { ...options.env, ...resolved.env };
+
+	return {
+		model:
+			resolved.auth.baseUrl === undefined ? model : { ...model, baseUrl: resolved.auth.baseUrl },
+		options: next,
+	};
+}
+
+function mergeHeaders(
+	base: ProviderHeaders | undefined,
+	override: ProviderHeaders | undefined,
+): ProviderHeaders | undefined {
+	if (base === undefined && override === undefined) return undefined;
+	const merged: ProviderHeaders = { ...base };
+	for (const [name, value] of Object.entries(override ?? {})) {
+		const lower = name.toLowerCase();
+		for (const existing of Object.keys(merged)) {
+			if (existing.toLowerCase() === lower) delete merged[existing];
+		}
+		merged[name] = value;
+	}
+	return merged;
+}
+
+// The runtime reads auth from the provider, so it has to report configured when an account exists,
+// even though the credential itself is injected into the request by `accountStream`. Reporting the
+// account's own type keeps `isUsingOAuth` honest, which is what bills a subscription request.
+function liftedAuth(provider: Provider, session: AccountSession): ProviderAuth {
+	const original = provider.auth.apiKey;
+	const login = original?.login;
+	return {
+		apiKey: {
+			name: original?.name ?? `${provider.name} accounts`,
+			...(login === undefined ? {} : { login: (interaction) => login(interaction) }),
+			async check(input) {
+				const account = session.resolve();
+				if (account !== undefined) return { type: account.credential.type, source: "account" };
+				return original?.check?.(input);
+			},
+			async resolve(input) {
+				if (session.resolve() !== undefined) return { auth: {}, source: "account" };
+				return original?.resolve(input);
+			},
+		},
+		...(provider.auth.oauth === undefined ? {} : { oauth: provider.auth.oauth }),
+	};
+}

package/src/accounts/login.ts

@@ -0,0 +1,41 @@
+import type {
+	AuthType,
+	Credential,
+	Provider,
+	ProviderAuthInteraction,
+} from "@earendil-works/pi-ai";
+
+/** One way a provider can log in, named the way its own login dialog names it. */
+export interface LoginMethod {
+	provider: Provider;
+	authType: AuthType;
+	label: string;
+}
+
+/** Every way this provider logs in, OAuth first. */
+export function loginMethods(provider: Provider): LoginMethod[] {
+	const methods: LoginMethod[] = [];
+	const oauth = provider.auth.oauth;
+	if (oauth !== undefined) {
+		methods.push({ provider, authType: "oauth", label: oauth.loginLabel ?? oauth.name });
+	}
+	const apiKey = provider.auth.apiKey;
+	if (apiKey?.login !== undefined)
+		methods.push({ provider, authType: "api_key", label: apiKey.name });
+	return methods;
+}
+
+/** Runs the provider's own login, so the OAuth flow and the key prompt both stay pi's. */
+export async function login(
+	method: LoginMethod,
+	interaction: ProviderAuthInteraction,
+): Promise<Credential> {
+	if (method.authType === "oauth") {
+		const oauth = method.provider.auth.oauth;
+		if (oauth === undefined) throw new Error(`${method.provider.id} has no OAuth login`);
+		return await oauth.login(interaction);
+	}
+	const apiKey = method.provider.auth.apiKey;
+	if (apiKey?.login === undefined) throw new Error(`${method.provider.id} has no key login`);
+	return await apiKey.login(interaction);
+}

package/src/accounts/names.ts

@@ -0,0 +1,11 @@
+// Written into session files and into pi's status line, so these names stay stable.
+export const NAME = "pi-providers";
+
+/** The session entry that pins an account for the branch. */
+export const SESSION_ENTRY = `${NAME}:accounts`;
+
+/** What the look reads for the account the current model uses. */
+export const STATUS_KEY = `${NAME}:account`;
+
+/** The status while a provider login runs. */
+export const LOGIN_KEY = `${NAME}:login`;

package/src/accounts/pins.ts

@@ -0,0 +1,58 @@
+// The account a session uses lives in the session file, so a resume or a fork comes back with the
+// account it had. The store holds the default; a pin here only overrides it for one branch.
+import { isObject } from "@adeildo/pi-kit";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { SESSION_ENTRY } from "./names.ts";
+
+/** The account pinned for a provider. `null` means the credential pi itself has. */
+export type Pins = Map<string, string | null>;
+
+export type PinEntry =
+	| { kind: "account"; provider: string; account: string }
+	| { kind: "default"; provider: string };
+
+export function record(pi: ExtensionAPI, entry: PinEntry): void {
+	pi.appendEntry(SESSION_ENTRY, entry);
+}
+
+/** Pins the account for the rest of the session, and writes it into the session file. */
+export function pin(
+	pi: ExtensionAPI,
+	pins: Pins,
+	providerId: string,
+	accountId: string | null,
+): void {
+	pins.set(providerId, accountId);
+	record(
+		pi,
+		accountId === null
+			? { kind: "default", provider: providerId }
+			: { kind: "account", provider: providerId, account: accountId },
+	);
+}
+
+/** The pins a branch recorded, newest winning. */
+export function replay(branch: readonly unknown[]): Pins {
+	const pins: Pins = new Map();
+	for (const item of branch) {
+		const entry = pinEntry(item);
+		if (entry === undefined) continue;
+		if (entry.kind === "default") pins.set(entry.provider, null);
+		else pins.set(entry.provider, entry.account);
+	}
+	return pins;
+}
+
+function pinEntry(item: unknown): PinEntry | undefined {
+	if (!isObject(item) || item.type !== "custom" || item.customType !== SESSION_ENTRY)
+		return undefined;
+	const data = item.data;
+	if (!isObject(data)) return undefined;
+	const provider = typeof data.provider === "string" ? data.provider : undefined;
+	if (provider === undefined) return undefined;
+	if (data.kind === "default") return { kind: "default", provider };
+	if (data.kind === "account" && typeof data.account === "string")
+		return { kind: "account", provider, account: data.account };
+	return undefined;
+}

package/src/accounts/screen.ts

@@ -0,0 +1,147 @@
+// The Accounts rows of the settings screen, one tree per provider: the accounts, and under each one
+// what can be done to it. Adding stays on `/accounts`, which needs the provider's login dialogs.
+import type { FeatureScope, Json, ScreenEntry } from "@adeildo/pi-kit";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { activeAccount } from "./active.ts";
+import { STATUS_KEY } from "./names.ts";
+import { pin, 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;
+	label: string;
+}
+
+export function accountRows(
+	pi: FeatureScope,
+	store: AccountStore,
+	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`;
+		},
+	};
+}
+
+/** One account, and its actions, one level deeper. */
+function accountBlock(group: ProviderGroup, account: Account): ScreenEntry[] {
+	const subscription = account.credential.type === "oauth";
+	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;
+			},
+			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);
+				return `${account.label} in use`;
+			},
+		},
+		{
+			kind: "value",
+			id: `accounts.${group.providerId}.${account.id}.label`,
+			section: group.label,
+			label: "Rename",
+			description: "What this account is called in the picker.",
+			control: { type: "text" },
+			indent: 2,
+			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;
+			},
+		},
+		{
+			kind: "action",
+			id: `accounts.${group.providerId}.${account.id}.remove`,
+			section: group.label,
+			label: "Remove",
+			description: `Forget the "${account.label}" credential.`,
+			text: () => account.label,
+			confirm: `Remove the ${group.providerId} account "${account.label}"?`,
+			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`;
+			},
+		},
+	];
+}
+
+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));
+}

package/src/accounts/store.ts

@@ -0,0 +1,167 @@
+// The extra accounts live beside the settings, one file for every provider. Pi's own credential is
+// not copied here: it stays in pi's store, and is what a request uses when no account is chosen.
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+
+import { globalSettingsPath, isObject, readSettingsFile, writeSettingsFile } from "@adeildo/pi-kit";
+import type { Credential } from "@earendil-works/pi-ai";
+
+import { reason } from "./describe.ts";
+import type { Account, AccountsFile, ProviderAccounts } from "./types.ts";
+
+export const ACCOUNTS_FILE = "accounts.json";
+
+export function accountsPath(): string {
+	return join(dirname(globalSettingsPath()), ACCOUNTS_FILE);
+}
+
+/** What an add produced: the account it wrote, or why it did not. */
+export interface Added {
+	account?: Account;
+	problem?: string;
+}
+
+export class AccountStore {
+	private readonly path: string;
+	private data: AccountsFile | undefined;
+
+	constructor(path: string = accountsPath()) {
+		this.path = path;
+	}
+
+	/** Reads the file again, for another pi's write or a hand edit. */
+	reload(): string[] {
+		const read = readAccounts(this.path);
+		this.data = { version: 1, providers: read.providers };
+		return read.warnings;
+	}
+
+	/** The providers with at least one account. */
+	providerIds(): string[] {
+		return Object.keys(this.file().providers);
+	}
+
+	accounts(providerId: string): Account[] {
+		return this.file().providers[providerId]?.accounts ?? [];
+	}
+
+	has(providerId: string): boolean {
+		return this.accounts(providerId).length > 0;
+	}
+
+	/** The account the store prefers. Without one the feature keeps pi's own credential. */
+	active(providerId: string): Account | undefined {
+		const entry = this.file().providers[providerId];
+		if (entry?.active === undefined) return undefined;
+		return entry.accounts.find((account) => account.id === entry.active);
+	}
+
+	add(providerId: string, label: string, credential: Credential): Added {
+		const account: Account = { id: randomUUID(), label: label.trim() || providerId, credential };
+		const problem = this.edit((providers) => {
+			const entry = providers[providerId] ?? { accounts: [] };
+			entry.accounts.push(account);
+			providers[providerId] = entry;
+		});
+		return problem === undefined ? { account } : { problem };
+	}
+
+	remove(providerId: string, id: string): string | undefined {
+		return this.edit((providers) => {
+			const entry = providers[providerId];
+			if (entry === undefined) return;
+			entry.accounts = entry.accounts.filter((account) => account.id !== id);
+			if (entry.active === id) delete entry.active;
+			if (entry.accounts.length === 0) delete providers[providerId];
+		});
+	}
+
+	rename(providerId: string, id: string, label: string): string | undefined {
+		return this.edit((providers) => {
+			const account = providers[providerId]?.accounts.find((entry) => entry.id === id);
+			if (account !== undefined) account.label = label.trim() || account.label;
+		});
+	}
+
+	/** Sets the account the store prefers, or clears the choice with undefined. */
+	setActive(providerId: string, id: string | undefined): string | undefined {
+		return this.edit((providers) => {
+			const entry = providers[providerId];
+			if (entry === undefined) return;
+			if (id === undefined) delete entry.active;
+			else if (entry.accounts.some((account) => account.id === id)) entry.active = id;
+		});
+	}
+
+	/** 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);
+			if (account !== undefined) account.credential = credential;
+		});
+	}
+
+	private file(): AccountsFile {
+		if (this.data === undefined) this.reload();
+		return this.data ?? { version: 1, providers: {} };
+	}
+
+	/** Reads, changes and writes, so another pi's write since the last read is not lost. */
+	private edit(change: (providers: Record<string, ProviderAccounts>) => void): string | undefined {
+		const read = readAccounts(this.path);
+		const warning = read.warnings[0];
+		if (warning !== undefined) return warning;
+		change(read.providers);
+		this.data = { version: 1, providers: read.providers };
+		return writeAccounts(this.path, this.data);
+	}
+}
+
+function readAccounts(path: string): {
+	providers: Record<string, ProviderAccounts>;
+	warnings: string[];
+} {
+	const file = readSettingsFile(path);
+	if (file.warnings.length > 0) return { providers: {}, warnings: file.warnings };
+
+	const source = file.data.providers;
+	if (!isObject(source)) return { providers: {}, warnings: [] };
+
+	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);
+		if (accounts.length === 0) continue;
+		providers[providerId] = {
+			accounts,
+			...(typeof value.active === "string" ? { active: value.active } : {}),
+		};
+	}
+	return { providers, warnings: [] };
+}
+
+function writeAccounts(path: string, data: AccountsFile): string | undefined {
+	try {
+		writeSettingsFile(path, data, { mode: 0o600 });
+		return undefined;
+	} catch (error) {
+		return reason(error);
+	}
+}
+
+function isAccount(input: unknown): input is Account {
+	return (
+		isObject(input) &&
+		typeof input.id === "string" &&
+		typeof input.label === "string" &&
+		isCredential(input.credential)
+	);
+}
+
+function isCredential(input: unknown): input is Credential {
+	if (!isObject(input)) return false;
+	if (input.type === "oauth")
+		return typeof input.access === "string" && typeof input.refresh === "string";
+	if (input.type === "api_key") return input.key === undefined || typeof input.key === "string";
+	return false;
+}

package/src/accounts/types.ts

@@ -0,0 +1,21 @@
+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. */
+export interface Account {
+	/** Stable id, so renaming an account keeps a session pinned to it. */
+	id: string;
+	label: string;
+	credential: Credential;
+}
+
+/** The extra accounts of one provider, and the one the store prefers. */
+export interface ProviderAccounts {
+	/** The id of the account the store prefers. Absent means pi's own credential. */
+	active?: string;
+	accounts: Account[];
+}
+
+export type AccountsFile = {
+	version: 1;
+	providers: Record<string, ProviderAccounts>;
+};

package/src/index.ts

@@ -1,10 +1,14 @@
 import { createApp } from "@adeildo/pi-kit";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
+import { accounts } from "./accounts/feature.ts";
+import { NAME } from "./accounts/names.ts";
 import { subscription } from "./subscription/feature.ts";
 
+export { accounts, onLimit, WHEN_LIMITED, type WhenLimited } from "./accounts/feature.ts";
+export { accountsPath, AccountStore } from "./accounts/store.ts";
 export { claudeCodeVersion, subscription } from "./subscription/feature.ts";
 
 export default function piProviders(pi: ExtensionAPI): void {
-	createApp(pi, { name: "pi-providers" }).use(subscription).build();
+	createApp(pi, { name: NAME }).use(subscription).use(accounts).build();
 }

package/src/subscription/billing.ts

@@ -1,6 +1,3 @@
-// How Claude Code tells Anthropic who it is. A request is billed to the Claude plan when it
-// carries Claude Code's user agent and a first system block with a billing attribution, which ends
-// in three characters of the first user message hashed with the version and a salt.
 import { createHash } from "node:crypto";
 
 export const CLAUDE_CODE_IDENTITY = "You are Claude Code, Anthropic's official CLI for Claude.";

package/src/subscription/feature.ts

@@ -1,6 +1,3 @@
-// Bills Anthropic OAuth requests to the Claude Pro/Max plan instead of extra usage. It acts on any
-// provider that speaks the Anthropic Messages API with an OAuth token, not only the one named
-// `anthropic`, so a second account under another name gets the same treatment.
 import { defineFeature, isObject, matching, setting } from "@adeildo/pi-kit";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
@@ -12,7 +9,7 @@ export const claudeCodeVersion = setting({
 	default: "2.1.280",
 	decoder: matching(/^\d+\.\d+\.\d+$/, "a Claude Code version like 2.1.280"),
 	ui: {
-		group: "Providers",
+		section: "Anthropic subscription",
 		label: "Claude Code version",
 		description:
 			"The Claude Code version pi reports to Anthropic. Anthropic refuses newer models to versions it considers too old.",
@@ -22,6 +19,7 @@ export const claudeCodeVersion = setting({
 export const subscription = defineFeature({
 	id: "subscription",
 	description: "Bill Anthropic OAuth requests to the Claude plan instead of extra usage",
+	tab: "Providers",
 	settings: [claudeCodeVersion],
 	setup(scope) {
 		scope.on("before_provider_headers", (event, ctx) => {

package/src/subscription/payload.ts

@@ -1,7 +1,3 @@
-// Rewrites the request pi builds for an Anthropic OAuth token. Anthropic's billing classifier reads
-// `system`, and any text there that Claude Code would not send costs extra usage. So `system` keeps
-// the attribution and the identity, and pi's prompt moves into the first user message, where the
-// model still follows it.
 import { isObject } from "@adeildo/pi-kit";
 
 import { billingAttribution, CLAUDE_CODE_IDENTITY } from "./billing.ts";
@@ -62,8 +58,7 @@ function prependInstructions(messages: readonly unknown[], moved: readonly TextB
 		.join("\n\n");
 	if (text === "") return [...messages];
 
-	// The moved prompt takes over the cache breakpoint pi put on it, so the request keeps the same
-	// number of breakpoints and the prompt stays cached on its own.
+	// The moved prompt takes over pi's cache breakpoint, so the breakpoint count stays the same.
 	const cacheControl = moved.findLast((block) => block.cache_control !== undefined)?.cache_control;
 	const instructions: TextBlock = {
 		type: "text",