@adeildo/pi-providers 5.1.0 → 5.3.0

package/README.md

@@ -1,82 +1,83 @@
-# @adeildo/pi-providers
+<h1 align="center">@adeildo/pi-providers</h1>
 
-[![npm](https://img.shields.io/npm/v/@adeildo/pi-providers)](https://www.npmjs.com/package/@adeildo/pi-providers)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@adeildo/pi-providers"><img src="https://img.shields.io/npm/v/@adeildo/pi-providers" alt="npm"></a>
+  <a href="https://pi.dev"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffelipeadeildo%2Fpi-harness%2Fmain%2Fpackage.json&query=%24.devDependencies%5B%22%40earendil-works%2Fpi-coding-agent%22%5D&label=pi%20SDK&color=6E56CF" alt="pi SDK"></a>
+</p>
 
-Two features for the providers [Pi](https://pi.dev) talks to. `subscription` bills Anthropic requests to your Claude plan. `accounts` keeps several logins per provider and moves to the next one when a limit hits.
+<p align="center">
+  <strong>The plan you already pay for, and more than one login per provider.</strong><br>
+  Bill Anthropic requests to your Claude plan, and keep several accounts with a switch to the next one when a limit hits.
+</p>
 
-```bash
-pi install npm:@adeildo/pi-providers
-```
-
-It also comes in [`@adeildo/pi-harness`](../harness), with the rest of the pieces.
+<p align="center"><code>pi install npm:@adeildo/pi-providers</code></p>
 
-## subscription
+## Claude plan
 
-With a Claude Pro or Max plan connected through `/login anthropic`, Pi's requests count as paid extra usage. With `subscription` they come out of the plan, the way Claude Code's do.
+With a Claude Pro or Max plan connected through `/login anthropic`, Pi's requests count as extra usage, billed by the token. This makes them come out of the plan, the way Claude Code's own requests do.
 
 > [!WARNING]
-> This makes Pi introduce itself to Anthropic as Claude Code. Using your subscription from anything other than Claude Code may break Anthropic's terms. It is on once the package is installed, so decide whether you accept that risk. To turn it off, switch the extension off in `pi config`, or set `"features": { "subscription": { "enabled": false } }` in the settings file below.
+> It does that by introducing Pi to Anthropic as Claude Code, and using a subscription from anything other than Claude Code may break Anthropic's terms. It is on as soon as you install the package. To say no to that: switch the extension off in `pi config`, or set `"features": { "subscription": { "enabled": false } }` in the settings file below.
 
-Pi already sends Claude Code's identity with an OAuth token. Anthropic checks two more things before it bills a request to the plan:
+Pi already sends Claude Code's identity when the token is an OAuth one. Anthropic checks two more things before it bills the request to the plan:
 
 1. The user agent has to read `claude-cli/<version> (external, cli)`.
-2. The first `system` block has to be a billing attribution line, with nothing Claude Code would not send. So pi's own prompt moves to the start of the first user message, wrapped in `<system-instructions>`. The model still reads it there and follows it.
+2. The first `system` block has to be the billing attribution, with nothing Claude Code would not send. Pi's own prompt moves to the start of the first user message, wrapped in `<system-instructions>`, where the model still reads it.
 
-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 registered under another name is billed to its own plan. Requests with an API key go out untouched.
+Any provider that speaks the Anthropic Messages API with an OAuth token gets this, not only the one named `anthropic`, so a second account under another name is billed to its own plan. A request with an API key goes out untouched.
 
-Pi warns about extra usage on every Anthropic OAuth session. Once the plan pays, turn the warning off in `~/.pi/agent/settings.json`:
+Pi warns about extra usage in every Anthropic OAuth session. Once the plan pays, that warning is wrong, and `warnings.anthropicExtraUsage` in `~/.pi/agent/settings.json` turns it off.
 
 ```json
 { "warnings": { "anthropicExtraUsage": false } }
 ```
 
-When a request comes back with `400 claude_code_version_too_old`, raise the version Pi reports:
-
-```json
-{ "subscription": { "claudeCodeVersion": "2.1.280" } }
-```
+Anthropic answers `400 claude_code_version_too_old` when it considers the version too old for a newer model, and `subscription.claudeCodeVersion` raises the version Pi reports.
 
-## accounts
+## 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.
+Pi keeps one credential per provider, the one `/login` wrote. This keeps several, each with a name. Once a provider has an account, its accounts are all it has: every request, refresh and plan reading comes from the account in use, and there is no unnamed credential behind them.
 
 ```text
-/accounts anthropic
+/accounts            the accounts of the current model's provider
+/accounts anthropic  the accounts of another one
 ```
 
-It 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. Each account shows its kind:
+The list shows each account, the one in use and what its plan has left, and fills the plans in as they arrive. `enter` uses an account, here and in the sessions that start after, `r` renames it in place, `d` removes it after asking, and `a` or the last row adds one. Adding asks for a name and runs the login Pi already has, so there is no OAuth of its own here. The first account of a provider brings Pi's own login along under a name you choose, since from then on only accounts are read.
+
+A `/login` for a provider that already has accounts asks where the credential goes, replacing an account or becoming a new one, and closing that dialog still keeps it as a new account under the provider's name. Pi keeps its own copy too, because it decides which providers are logged in before any extension starts; that copy is renewed from an account and never read for a request. Each account shows its kind:
 
-| Kind    | Is                                                                    |
-| ------- | --------------------------------------------------------------------- |
-| `login` | The credential of `/login`, which cannot be copied out of `auth.json` |
-| `oauth` | A subscription token, billed to its own plan                          |
-| `key`   | An API key                                                            |
+| Kind    | Is                                           |
+| ------- | -------------------------------------------- |
+| `oauth` | A subscription token, billed to its own plan |
+| `key`   | An API key                                   |
 
-`alt+a` switches the account of the current model's provider, and the Providers tab of `Alt+S` lists the accounts to choose, rename or remove. 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.
+`alt+a` switches the account of the current model's provider for this session, and the Providers tab of `Alt+S` lists them too. The account in use sits next to the model, and its plan's windows below the editor, read again whenever a model of another provider is picked. An account whose credential the provider refused says `sign in again`, and `enter` on it in `/accounts` signs in again under the same name. The session remembers the choice, so a resume or a fork comes back to the same 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:
+When a provider refuses a request for a quota or a rate limit and that provider has another account, `accounts.onLimit` decides what happens:
 
-| Value    | Does                                                                       |
-| -------- | -------------------------------------------------------------------------- |
-| `ask`    | Opens a dialog, with the option to always switch from then on. The default |
-| `switch` | Moves to the next account on its own                                       |
-| `stop`   | Leaves the error in front of you                                           |
+| Value    | Does                                                                      |
+| -------- | ------------------------------------------------------------------------- |
+| `ask`    | Opens a dialog, with an option to always switch from then on. The default |
+| `switch` | Moves to the next account 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. Only the chat streams move: image generation, classifier calls and deferred responses still use pi's own credential.
+Only a limit that arrives before anything was shown switches, so a retry never repeats output you already saw. Only chat streams move: image generation, classifier calls and deferred responses use the account in use, and surface their errors as they are.
+
+A quota belongs to the account, so an account that refused is skipped until it answers again, and the same dialog is not asked twice in a session. A credential the provider refuses instead opens `accounts.onAuthFailure`, whose dialog can run the provider's own login again under the same account, keeping its name and the session pin.
 
 ## Settings
 
 In `~/.pi/agent/extensions/pi-harness/settings.json`:
 
-| Key                              | Default     | Does                                                                                                   |
-| -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
-| `subscription.claudeCodeVersion` | `"2.1.280"` | The Claude Code version Pi reports. Anthropic will not serve newer models to versions it considers old |
-| `accounts.onLimit`               | `"ask"`     | What a quota or rate limit does when another account exists: `"ask"`, `"switch"` or `"stop"`           |
-
-## Credit
+| Key                              | Default     | Does                                                                                           |
+| -------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| `subscription.claudeCodeVersion` | `"2.1.280"` | The version Pi reports. Anthropic will not serve newer models to a version it considers old    |
+| `accounts.onLimit`               | `"ask"`     | What a quota or a rate limit does when another account exists: `"ask"`, `"switch"` or `"stop"` |
+| `accounts.onAuthFailure`         | `"ask"`     | What a refused credential does: `"ask"` (sign in again or switch), `"switch"` or `"stop"`      |
 
-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.
+The Claude plan billing comes 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.
 
-## License
+Several accounts per provider, with a switch to the next one when a limit hits, follow [pi-multiprovider](https://github.com/monotykamary/pi-multiprovider) by monotykamary, also MIT. This one keeps them inside pi's own login, with no OAuth of its own.
 
-[MIT](LICENSE)
+Part of [pi-harness](https://github.com/felipeadeildo/pi-harness), which brings every piece in one install.

package/package.json

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

package/src/accounts/actions.ts

@@ -0,0 +1,94 @@
+// What can be done to an account from any dialog, and the status that follows it: the settings screen,
+// /accounts and a login's adoption all go through here.
+import type { Credential } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { activeAccount } from "./active.ts";
+import { NAME, STATUS_KEY } from "./names.ts";
+import { pin, type Pins } from "./pins.ts";
+import type { AccountStore } from "./store.ts";
+import type { Account } from "./types.ts";
+
+/** One provider's accounts, as the actions reach them. */
+export interface AccountsOf {
+	pi: ExtensionAPI;
+	store: AccountStore;
+	pins: Pins;
+	providerId: string;
+}
+
+/** Asks for a name, keeping the suggestion when the answer is empty. */
+export async function askName(
+	ctx: ExtensionContext,
+	title: string,
+	suggestion: string,
+): Promise<string> {
+	return (await ctx.ui.input(title, suggestion))?.trim() || suggestion;
+}
+
+/** Stores a new account, saying why when it could not. */
+export function saveAccount(
+	ctx: ExtensionContext,
+	store: AccountStore,
+	providerId: string,
+	label: string,
+	credential: Credential,
+): Account | undefined {
+	const added = store.add(providerId, label, credential);
+	if (added.account === undefined) ctx.ui.notify(`${NAME}: ${added.problem}`, "error");
+	return added.account;
+}
+
+/** Makes an account the one in use, in this session and in the ones that start after it. */
+export function useAccount(of: AccountsOf, ctx: ExtensionContext, accountId: string): void {
+	of.store.setActive(of.providerId, accountId);
+	pin(of.pi, of.pins, of.providerId, accountId);
+	refreshStatus(of.store, of.pins, ctx);
+}
+
+/** Renames an account, answering with a problem or undefined. */
+export function renameAccount(
+	of: AccountsOf,
+	ctx: ExtensionContext,
+	accountId: string,
+	label: string,
+): string | undefined {
+	const problem = of.store.rename(of.providerId, accountId, label);
+	if (problem === undefined) refreshStatus(of.store, of.pins, ctx);
+	return problem;
+}
+
+/** Removes an account; a session pinned to it goes back to the store's choice. */
+export function removeAccount(
+	of: AccountsOf,
+	ctx: ExtensionContext,
+	accountId: string,
+): string | undefined {
+	const problem = of.store.remove(of.providerId, accountId);
+	if (problem !== undefined) return problem;
+	if (of.pins.get(of.providerId) === accountId) of.pins.delete(of.providerId);
+	refreshStatus(of.store, of.pins, ctx);
+	return undefined;
+}
+
+/** What removing an account asks, saying so when it is the last one the provider has. */
+export function removeQuestion(provider: string, label: string, last: boolean): string {
+	if (!last) return `Remove the ${provider} account "${label}"?`;
+	return `Remove "${label}"? It is the last ${provider} account, so ${provider} goes back to pi's own /login.`;
+}
+
+/** 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;
+	return activeAccount(store, pins, providerId)?.label;
+}
+
+/** 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/active.ts

@@ -4,16 +4,15 @@ 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.
+ * The account a request uses: the session pin, else the store's choice, else the first account. A
+ * provider with accounts always has one in use; undefined means it has none.
  */
 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);
+	const accounts = store.accounts(providerId);
+	const wanted = pins.get(providerId) ?? store.active(providerId)?.id;
+	return accounts.find((account) => account.id === wanted) ?? accounts[0];
 }

package/src/accounts/adopt.ts

@@ -0,0 +1,70 @@
+// What happens after a provider login: the credential gets a name, either replacing an account or
+// becoming a new one, and the session moves to it.
+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 { pick } from "../ui/picker.ts";
+import { type AccountsOf, askName, saveAccount, useAccount } from "./actions.ts";
+import { activeAccount } from "./active.ts";
+import { NAME } from "./names.ts";
+import type { Pins } from "./pins.ts";
+import type { AccountStore } from "./store.ts";
+import type { Account } from "./types.ts";
+
+/**
+ * Pi's login just produced a credential; ask where it belongs and keep it. Pi's own copy is no
+ * account, so a login that went nowhere would be lost: closing the dialog keeps it as a new account
+ * under the provider's name, which `/accounts` can rename or remove.
+ */
+export async function adoptAccount(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	ctx: ExtensionContext,
+	providerId: string,
+	credential: Credential,
+): Promise<void> {
+	const provider = ctx.modelRegistry.getProviderDisplayName(providerId);
+	const of: AccountsOf = { pi: scope, store, pins, providerId };
+	const current = activeAccount(store, pins, providerId)?.id;
+	const choices: { account: Account | undefined; label: string }[] = store
+		.accounts(providerId)
+		.map((account) => ({
+			account,
+			label: `Replace ${account.label}${account.id === current ? " (in use)" : ""}`,
+		}));
+	choices.push({ account: undefined, label: "New account" });
+
+	const picked = ctx.hasUI
+		? await pick(
+				ctx,
+				`Keep this ${provider} login as`,
+				choices.map((choice) => choice.label),
+			)
+		: undefined;
+	const choice = choices.find((candidate) => candidate.label === picked);
+
+	if (choice?.account !== undefined) {
+		const problem = store.setCredential(providerId, choice.account.id, credential);
+		if (problem !== undefined) {
+			ctx.ui.notify(`${NAME}: ${problem}`, "error");
+			return;
+		}
+		store.clearError(providerId, choice.account.id);
+		keep(of, ctx, provider, choice.account);
+		return;
+	}
+
+	// A closed dialog asks nothing more, and the login keeps the provider's name.
+	let label = provider;
+	if (choice !== undefined) label = await askName(ctx, `Name this ${provider} account`, provider);
+	const added = saveAccount(ctx, store, providerId, label, credential);
+	if (added !== undefined) keep(of, ctx, provider, added);
+}
+
+/** Moves the session to the account the login belongs to. */
+function keep(of: AccountsOf, ctx: ExtensionContext, provider: string, account: Account): void {
+	useAccount(of, ctx, account.id);
+	ctx.ui.notify(`${NAME}: ${provider} now uses ${account.label}`, "info");
+}

package/src/accounts/attach.ts

@@ -0,0 +1,195 @@
+// Joining a provider to the session: which account a request uses, where a refreshed token goes, and
+// what quota each account reported.
+import type { FeatureScope } from "@adeildo/pi-kit";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { loginScreen as openLogin } from "../ui/login.ts";
+import type { Quota } from "../usage/quota.ts";
+import { noteUsage, resetNote, usageOf, worstWindow } from "../usage/read.ts";
+import type { AccountUsage, UsageMap } from "../usage/types.ts";
+import { refreshStatus } from "./actions.ts";
+import { activeAccount } from "./active.ts";
+import { adoptAccount } from "./adopt.ts";
+import { reason } from "./describe.ts";
+import { type AccountCredential, liftProvider, nativeOf, type AccountSession } from "./lift.ts";
+import type { Pins } from "./pins.ts";
+import { afterAuthFailure, afterLimit } from "./policy.ts";
+import { type Renewal, needsRefresh, refreshAccount } from "./refresh.ts";
+import { accountsLockPath, type AccountStore } from "./store.ts";
+import type { Account } from "./types.ts";
+
+/** What the session learns while it runs. */
+export interface Watch {
+	limited: Map<string, Set<string>>;
+	usage: UsageMap;
+	quota: Quota;
+}
+
+export function attachProvider(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	watch: Watch,
+	ctx: ExtensionContext,
+	providerId: string,
+): void {
+	// A pin with no account left behind it injects nothing, so re-registering 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, watch, ctx, providerId)),
+	);
+}
+
+function sessionFor(
+	scope: FeatureScope,
+	store: AccountStore,
+	pins: Pins,
+	watch: Watch,
+	ctx: ExtensionContext,
+	providerId: string,
+): AccountSession {
+	return {
+		resolve: () => requestOf(activeAccount(store, pins, providerId)),
+		subscription: () =>
+			requestOf(store.accounts(providerId).find((account) => account.credential.type === "oauth")),
+		save: (id, credential) => void store.setCredential(providerId, id, credential),
+		served: (id) => {
+			watch.limited.get(providerId)?.delete(id);
+			store.clearError(providerId, id);
+			store.markLimited(providerId, id, undefined);
+		},
+		adopt: (credential) => adoptAccount(scope, store, pins, ctx, providerId, credential),
+		loginScreen: (label, signal) => openLogin(ctx, label, signal),
+		freshen: (id) => renewalFor(store, providerId).freshen(id),
+		lockPath: accountsLockPath,
+		noteUsage: (id, headers) =>
+			noteUsage(watch.usage, providerId, id, watch.quota.fromHeaders(providerId, headers)),
+		afterLimit: async (currentId, detail) => {
+			const reading = await readingFor(watch, store, ctx, providerId, currentId);
+			const until = worstWindow(reading)?.window.resetsAt;
+			if (until !== undefined) store.markLimited(providerId, currentId, until);
+			return await afterLimit(
+				scope,
+				store,
+				pins,
+				ctx,
+				providerId,
+				currentId,
+				withReset(detail, reading),
+				watch.limited,
+			);
+		},
+		afterAuthFailure: (currentId, detail) =>
+			afterAuthFailure(scope, store, pins, ctx, providerId, currentId, detail),
+	};
+}
+
+/** An account as a request carries it. */
+function requestOf(account: Account | undefined): AccountCredential | undefined {
+	return account === undefined ? undefined : { id: account.id, credential: account.credential };
+}
+
+function withReset(detail: string, usage: AccountUsage | undefined): string {
+	const note = resetNote(usage);
+	return note === undefined ? detail : `${detail} · ${note}`;
+}
+
+/** The reading already known: the live one, else the endpoint's. */
+export function knownReading(
+	watch: Watch,
+	providerId: string,
+	accountId: string,
+): AccountUsage | undefined {
+	return usageOf(watch.usage, providerId, accountId) ?? watch.quota.read(providerId, accountId);
+}
+
+/** Reads every account's plan of a provider, so the footer and the dialogs find their quota ready. */
+export async function readPlans(
+	store: AccountStore,
+	watch: Watch,
+	ctx: ExtensionContext,
+	providerId: string | undefined,
+): Promise<void> {
+	if (!ctx.hasUI || providerId === undefined || !store.has(providerId)) return;
+	await Promise.all(
+		store
+			.accounts(providerId)
+			.map((account) => readingFor(watch, store, ctx, providerId, account.id)),
+	);
+}
+
+/** Reads a provider's plans in the background, and draws the account again once they are in. */
+export function showPlans(
+	store: AccountStore,
+	pins: Pins,
+	watch: Watch,
+	ctx: ExtensionContext,
+	providerId: string | undefined,
+): void {
+	void readPlans(store, watch, ctx, providerId).then(() => refreshStatus(store, pins, ctx));
+}
+
+/** The best reading for an account: the live one, else the endpoint's, fetched when there is none. */
+export async function readingFor(
+	watch: Watch,
+	store: AccountStore,
+	ctx: ExtensionContext,
+	providerId: string,
+	accountId: string,
+): Promise<AccountUsage | undefined> {
+	const known = knownReading(watch, providerId, accountId);
+	if (known !== undefined) return known;
+	const token = await planToken(store, ctx, providerId, accountId);
+	return await watch.quota.ensure(providerId, accountId, token);
+}
+
+/** The token that can read a plan, refreshed when it has expired. */
+async function planToken(
+	store: AccountStore,
+	ctx: ExtensionContext,
+	providerId: string,
+	accountId: string,
+): Promise<string | undefined> {
+	const account = store.accounts(providerId).find((entry) => entry.id === accountId);
+	const credential = account?.credential;
+	if (account === undefined || credential?.type !== "oauth") return undefined;
+	if (!needsRefresh(credential)) return credential.access;
+
+	const registered = ctx.modelRegistry.getProvider(providerId);
+	const oauth = registered === undefined ? undefined : nativeOf(registered).auth.oauth;
+	if (oauth === undefined) return undefined;
+	try {
+		const fresh = await refreshAccount(
+			oauth,
+			renewalFor(store, providerId),
+			account.id,
+			credential,
+			new AbortController().signal,
+			accountsLockPath(),
+		);
+		return fresh.access;
+	} catch (error) {
+		store.markError(providerId, account.id, "auth", reason(error));
+		return undefined;
+	}
+}
+
+/** The store side of a refresh: the newest copy, and where to save the result. */
+function renewalFor(store: AccountStore, providerId: string): Renewal {
+	return {
+		freshen: (id) => {
+			store.reload();
+			return store.accounts(providerId).find((account) => account.id === id)?.credential;
+		},
+		save: (id, credential) => void store.setCredential(providerId, id, credential),
+	};
+}