@mastra/code-sdk 1.8.0-alpha.7 → 1.8.0-alpha.9

package/dist/auth/storage.js

@@ -4,7 +4,8 @@ import { githubCopilotOAuthProvider } from "./providers/github-copilot.js";
 import { kimiCodingOAuthProvider } from "./providers/kimi-coding.js";
 import { openaiCodexOAuthProvider } from "./providers/openai-codex.js";
 import { xaiOAuthProvider } from "./providers/xai.js";
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { createHash, randomUUID } from "crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
 //#region src/auth/storage.ts
 /**
@@ -42,6 +43,55 @@ function getOAuthProviders() {
 	return Array.from(oauthProviderRegistry.values());
 }
 /**
+* Mint an account instance id: `${providerId}:${randomUUID()}`.
+*
+* Assigned once, when the account is created, and never derived from
+* credentials. Deriving it from the refresh token (the pre-A13 scheme) looked
+* stable but was not: `persistRefreshedCredential` keeps an entry's key while
+* writing rotated tokens onto it, so every refresh left the id describing a
+* credential the account no longer had — and re-adding that same subscription
+* then failed to match its own entry and registered a second one for it.
+*/
+function mintAccountId(providerId) {
+	return `${providerId}:${randomUUID()}`;
+}
+/**
+* The pre-A13 id scheme: `${providerId}:${sha256(refresh).slice(0,8)}`.
+*
+* No longer used to assign ids, but still needed to recognize registries
+* written before A13 — both to match a re-authorized account onto its existing
+* entry, and to recognize entries whose fields the A13 migration must backfill.
+*/
+function legacyAccountIdFor(providerId, refreshToken) {
+	return `${providerId}:${createHash("sha256").update(refreshToken).digest("hex").slice(0, 8)}`;
+}
+/**
+* Stable identity for the *subscription* behind an account, when the provider
+* exposes one (an account id, an email — anything that survives a refresh and
+* a re-authorization). Used to decide whether an added account is one we
+* already have. Providers whose credentials carry no such identifier return
+* undefined; for those, a re-authorization is indistinguishable from a new
+* account without spending a request.
+*/
+function providerIdentity(provider, creds) {
+	try {
+		const identity = provider?.getAccountIdentity?.(creds);
+		return typeof identity === "string" && identity.length > 0 ? identity : void 0;
+	} catch {
+		return;
+	}
+}
+function isOAuthAccountRecord(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	return v.type === "oauth-account" && typeof v.id === "string" && typeof v.label === "string" && typeof v.addedAt === "string" && typeof v.active === "boolean" && typeof v.refresh === "string" && typeof v.access === "string" && typeof v.expires === "number";
+}
+/** The credential fields of an account record — everything but registry identity. */
+function credentialFieldsOf(record) {
+	const { type: _type, id: _id, label: _label, addedAt: _addedAt, active: _active, identity: _identity, ...creds } = record;
+	return creds;
+}
+/**
 * Credential storage backed by a JSON file.
 */
 var AuthStorage = class {
@@ -65,6 +115,111 @@ var AuthStorage = class {
 		} catch {
 			this.data = {};
 		}
+		this.migrate();
+	}
+	/**
+	* Bring auth.json up to the multi-account registry format. Runs on every
+	* load; saves only when something actually changed.
+	*
+	* 1. A legacy OAuth slot with no registry gets one adopted active entry
+	*    (the slot's tokens stay put — the entry mirrors them).
+	* 2. When the slot's refresh token differs from the active entry's, an
+	*    external writer (older build, another worktree) owns the slot — the
+	*    slot wins and its tokens are adopted onto the active entry.
+	* 3. A registry with no active entry (hand-edited) self-heals to its first
+	*    entry; malformed `accounts:` values are skipped, never fatal.
+	* 4. A registry whose legacy slot disappeared (partial write, an external
+	*    hand-edit) self-heals by mirroring the active entry's tokens back into
+	*    the slot, so `isLoggedIn()`/`getOAuthCredential()` keep agreeing with
+	*    `listAccounts()`. `remove()`/`logout()` clear the registry with the
+	*    slot, so they never leave the shape this heals.
+	*/
+	migrate() {
+		let changed = false;
+		for (const key of Object.keys(this.data)) {
+			const slot = this.data[key];
+			if (!slot || slot.type !== "oauth") continue;
+			const providerId = key;
+			const entries = this.accountEntries(providerId);
+			if (entries.length === 0) {
+				this.adoptSlot(providerId, slot);
+				changed = true;
+				continue;
+			}
+			const active = entries.find((entry) => entry.active);
+			if (!active) {
+				this.data[this.accountKeyFor(entries[0].id)] = {
+					...entries[0],
+					active: true
+				};
+				changed = true;
+				continue;
+			}
+			if (active.refresh !== slot.refresh) {
+				const matching = entries.find((entry) => entry.id !== active.id && entry.refresh === slot.refresh);
+				if (matching) {
+					const { type: _t, ...slotCreds } = slot;
+					this.data[this.accountKeyFor(matching.id)] = {
+						...matching,
+						...slotCreds,
+						type: "oauth-account",
+						active: true
+					};
+					this.data[this.accountKeyFor(active.id)] = {
+						...active,
+						active: false
+					};
+					changed = true;
+				} else {
+					const { type: _type, ...slotCreds } = slot;
+					this.data[this.accountKeyFor(active.id)] = {
+						...active,
+						...slotCreds,
+						type: "oauth-account"
+					};
+					changed = true;
+				}
+			}
+		}
+		const registeredProviders = /* @__PURE__ */ new Set();
+		for (const key of Object.keys(this.data)) {
+			if (!key.startsWith("accounts:")) continue;
+			const providerId = key.slice(9).split(":")[0];
+			if (providerId) registeredProviders.add(providerId);
+		}
+		for (const providerId of registeredProviders) {
+			if (this.data[providerId]?.type === "oauth") continue;
+			const entries = this.accountEntries(providerId);
+			if (entries.length === 0) continue;
+			let active = entries.find((entry) => entry.active);
+			if (!active) {
+				active = entries[0];
+				this.data[this.accountKeyFor(active.id)] = {
+					...active,
+					active: true
+				};
+			}
+			this.data[providerId] = {
+				type: "oauth",
+				...credentialFieldsOf(active)
+			};
+			changed = true;
+		}
+		for (const providerId of registeredProviders) {
+			const provider = getOAuthProvider(providerId);
+			if (!provider?.getAccountIdentity) continue;
+			for (const entry of this.accountEntries(providerId)) {
+				if (entry.identity) continue;
+				const identity = providerIdentity(provider, entry);
+				if (!identity) continue;
+				this.data[this.accountKeyFor(entry.id)] = {
+					...entry,
+					identity
+				};
+				changed = true;
+			}
+		}
+		if (changed) this.save();
 	}
 	/**
 	* Save credentials to disk.
@@ -75,27 +230,45 @@ var AuthStorage = class {
 			recursive: true,
 			mode: 448
 		});
-		writeFileSync(this.authPath, JSON.stringify(this.data, null, 2), "utf-8");
-		chmodSync(this.authPath, 384);
+		const tempPath = `${this.authPath}.${process.pid}.${randomUUID()}.tmp`;
+		try {
+			writeFileSync(tempPath, JSON.stringify(this.data, null, 2), {
+				encoding: "utf-8",
+				mode: 384
+			});
+			chmodSync(tempPath, 384);
+			renameSync(tempPath, this.authPath);
+		} finally {
+			rmSync(tempPath, { force: true });
+		}
 	}
 	/**
-	* Get credential for a provider.
+	* Get credential for a provider. Registry entries (type 'oauth-account')
+	* live under `accounts:` keys and never surface here.
 	*/
 	get(provider) {
-		return this.data[provider] ?? void 0;
+		const cred = this.data[provider];
+		return cred !== void 0 && cred.type !== "oauth-account" ? cred : void 0;
 	}
 	/**
 	* Set credential for a provider.
 	*/
 	set(provider, credential) {
+		this.reload();
 		this.data[provider] = credential;
 		this.save();
 	}
 	/**
-	* Remove credential for a provider.
+	* Remove credential for a provider, including its account registry.
+	* Clearing only the slot would leave the registry behind, and the next
+	* load's migration would heal the slot back from it — resurrecting the
+	* provider the caller just signed out.
 	*/
 	remove(provider) {
+		this.reload();
 		delete this.data[provider];
+		const prefix = this.accountPrefixFor(provider);
+		for (const key of Object.keys(this.data)) if (key.startsWith(prefix)) delete this.data[key];
 		this.save();
 	}
 	/**
@@ -155,53 +328,443 @@ var AuthStorage = class {
 		}
 	}
 	/**
-	* Login to an OAuth provider.
+	* Login to an OAuth provider. Resolves to the registered account record.
+	* Pass `activate: false` to add the account without making it active (the
+	* first account for a provider is always activated — a provider with
+	* accounts must have an active one).
 	*/
-	async login(providerId, callbacks) {
+	async login(providerId, callbacks, opts) {
 		const provider = getOAuthProvider(providerId);
 		if (!provider) throw new Error(`Unknown OAuth provider: ${providerId}`);
 		const credentials = await provider.login(callbacks);
-		this.set(providerId, {
-			type: "oauth",
-			...credentials
-		});
+		return this.addAccount(providerId, credentials, opts);
 	}
 	/**
-	* Logout from a provider.
+	* Logout from a provider: remove the legacy slot and every registered account.
 	*/
 	logout(provider) {
 		this.remove(provider);
 	}
+	accountPrefixFor(providerId) {
+		return `accounts:${providerId}:`;
+	}
+	accountKeyFor(id) {
+		return `accounts:${id}`;
+	}
+	/** Registry entries for a provider in JSON insertion order (malformed values skipped). */
+	accountEntries(providerId) {
+		const prefix = this.accountPrefixFor(providerId);
+		const out = [];
+		for (const [key, value] of Object.entries(this.data)) if (key.startsWith(prefix) && isOAuthAccountRecord(value)) out.push(value);
+		return out;
+	}
+	/** Adopt a legacy slot credential as the registry's first active entry. */
+	adoptSlot(providerId, slot) {
+		const id = mintAccountId(providerId);
+		const provider = getOAuthProvider(providerId);
+		const identity = providerIdentity(provider, slot);
+		const record = {
+			...slot,
+			type: "oauth-account",
+			id,
+			...identity ? { identity } : {},
+			label: `${provider?.name ?? providerId} account 1`,
+			addedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			active: true
+		};
+		this.data[this.accountKeyFor(id)] = record;
+		return record;
+	}
+	/**
+	* Registered OAuth accounts for a provider, in insertion order. Copies —
+	* callers cannot corrupt unsaved storage state by mutating a record.
+	*/
+	listAccounts(providerId) {
+		return this.accountEntries(providerId).map((entry) => ({ ...entry }));
+	}
+	/**
+	* The provider's active registry entry, if a registry exists. A copy.
+	*/
+	getActiveAccount(providerId) {
+		const active = this.accountEntries(providerId).find((entry) => entry.active);
+		return active ? { ...active } : void 0;
+	}
+	/**
+	* Register OAuth credentials as an account for a provider, making it active
+	* unless `activate: false` is passed.
+	*
+	* With `replaceAccountId` (re-authentication of a picked account), the
+	* target entry's tokens are replaced in place — id re-keyed to the new
+	* refresh-token hash, label/position/addedAt preserved — because providers
+	* rotate refresh tokens per authorization, so the picked account's old id
+	* never matches the new token hash. Re-authentication keeps the target's
+	* active state: an inactive account stays inactive and the currently active
+	* account keeps the legacy slot. Otherwise, when the new credentials
+	* hash to an existing entry's id (same refresh token), that entry is
+	* updated in place; a genuinely new account is appended and activated.
+	*
+	* `activate: false` only applies to the plain add path: the new/updated entry
+	* keeps the active state it had, and the previously active account stays
+	* active. The first account of a provider is activated regardless.
+	*/
+	async addAccount(providerId, creds, opts) {
+		this.reload();
+		const entries = this.accountEntries(providerId);
+		if (opts?.replaceAccountId) {
+			const target = entries.find((entry) => entry.id === opts.replaceAccountId);
+			if (!target) throw new Error(`No account ${opts.replaceAccountId} for provider ${providerId}`);
+			const identity = providerIdentity(getOAuthProvider(providerId), creds) ?? target.identity;
+			const legacyId = legacyAccountIdFor(providerId, creds.refresh);
+			const collided = entries.find((entry) => entry.id !== target.id && (identity !== void 0 && entry.identity === identity || entry.id === legacyId || entry.refresh === creds.refresh));
+			const replacement = {
+				...target,
+				...collided ? credentialFieldsOf(collided) : {},
+				...creds,
+				type: "oauth-account",
+				...identity ? { identity } : {},
+				label: opts.label ?? target.label
+			};
+			const rebuilt = {};
+			for (const [key, value] of Object.entries(this.data)) if (key === this.accountKeyFor(target.id)) rebuilt[key] = collided?.active ? {
+				...replacement,
+				active: true
+			} : replacement;
+			else if (collided && key === this.accountKeyFor(collided.id)) continue;
+			else rebuilt[key] = value;
+			this.data = rebuilt;
+			if (target.active === true || collided?.active === true || entries.some((entry) => entry.active && entry.id !== target.id) === false) {
+				const activated = this.activateInMemory(providerId, target.id);
+				if (!activated) throw new Error(`Failed to activate account ${target.id} for provider ${providerId}`);
+				this.save();
+				return activated;
+			}
+			const replacementEntry = this.accountEntries(providerId).find((entry) => entry.id === target.id);
+			if (!replacementEntry) throw new Error(`Failed to store account ${target.id} for provider ${providerId}`);
+			this.save();
+			return replacementEntry;
+		}
+		const provider = getOAuthProvider(providerId);
+		const identity = providerIdentity(provider, creds);
+		const label = opts?.label ?? await provider?.getAccountLabel?.(creds) ?? null;
+		this.reload();
+		const freshEntries = this.accountEntries(providerId);
+		const legacyId = legacyAccountIdFor(providerId, creds.refresh);
+		const existing = (identity ? freshEntries.find((entry) => entry.identity === identity) : void 0) ?? freshEntries.find((entry) => entry.id === legacyId) ?? freshEntries.find((entry) => entry.refresh === creds.refresh);
+		const id = existing?.id ?? mintAccountId(providerId);
+		if (existing) this.data[this.accountKeyFor(id)] = {
+			...existing,
+			...creds,
+			type: "oauth-account",
+			id,
+			...identity ? { identity } : {},
+			active: existing.active
+		};
+		else {
+			const resolvedLabel = label ?? `${provider?.name ?? providerId} account ${freshEntries.length + 1}`;
+			this.data[this.accountKeyFor(id)] = {
+				type: "oauth-account",
+				id,
+				...identity ? { identity } : {},
+				label: resolvedLabel,
+				addedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				active: false,
+				...creds
+			};
+		}
+		if (opts?.activate === false && freshEntries.length > 0 && !existing?.active) {
+			this.save();
+			return { ...this.data[this.accountKeyFor(id)] };
+		}
+		const activated = this.activateInMemory(providerId, id);
+		if (!activated) throw new Error(`Failed to activate account ${id} for provider ${providerId}`);
+		this.save();
+		return activated;
+	}
 	/**
-	* Get API key for a provider, auto-refreshing OAuth tokens if needed.
+	* Activate an account: move the active tokens out of the legacy slot back
+	* into the previously active entry, and the target's tokens into the slot
+	* (never copy — one home per token set). With no `instanceId`, rotate to
+	* the next entry in insertion order, wrapping once to the front; returns
+	* undefined when there is no other entry to rotate to.
 	*/
-	async getApiKey(providerId) {
+	activateAccount(providerId, instanceId) {
+		this.reload();
+		const activated = this.activateInMemory(providerId, instanceId);
+		if (activated) this.save();
+		return activated;
+	}
+	/**
+	* Activate an account in memory only — the caller owns reload/save. Move the
+	* active tokens out of the legacy slot back into the previously active
+	* entry, and the target's tokens into the slot (never copy — one home per
+	* token set). With no `instanceId`, rotate to the next entry in insertion
+	* order, wrapping once to the front; returns undefined when there is no
+	* other entry to rotate to.
+	*/
+	activateInMemory(providerId, instanceId) {
+		const entries = this.accountEntries(providerId);
+		if (entries.length === 0) return void 0;
+		let target;
+		if (instanceId !== void 0) {
+			target = entries.find((entry) => entry.id === instanceId);
+			if (!target) return void 0;
+		} else {
+			if (entries.length <= 1) return void 0;
+			const currentIdx = entries.findIndex((entry) => entry.active);
+			target = (currentIdx >= 0 ? [...entries.slice(currentIdx + 1), ...entries.slice(0, currentIdx)] : [...entries])[0];
+		}
+		if (!target) return void 0;
+		const slot = this.data[providerId];
+		const current = entries.find((entry) => entry.active && entry.id !== target.id);
+		if (current && slot?.type === "oauth") {
+			const { type: _type, ...slotCreds } = slot;
+			this.data[this.accountKeyFor(current.id)] = {
+				...current,
+				...slotCreds,
+				type: "oauth-account",
+				active: false
+			};
+		}
+		this.data[providerId] = {
+			...credentialFieldsOf(target),
+			type: "oauth"
+		};
+		this.data[this.accountKeyFor(target.id)] = {
+			...target,
+			active: true
+		};
+		for (const entry of entries) {
+			if (entry.id === target.id || entry.id === current?.id) continue;
+			if (entry.active) this.data[this.accountKeyFor(entry.id)] = {
+				...entry,
+				active: false
+			};
+		}
+		return {
+			...target,
+			active: true
+		};
+	}
+	/**
+	* Remove an account from the registry. If it was active, the next entry in
+	* insertion order is activated; when it was the last one, the legacy slot
+	* is removed too (full sign-out for that provider).
+	*/
+	removeAccount(providerId, instanceId) {
+		this.reload();
+		const entries = this.accountEntries(providerId);
+		const target = entries.find((entry) => entry.id === instanceId);
+		if (!target) return;
+		const wasActive = target.active;
+		delete this.data[this.accountKeyFor(instanceId)];
+		if (wasActive) {
+			const next = entries[entries.indexOf(target) + 1] ?? entries.find((entry) => entry.id !== instanceId);
+			if (next) {
+				this.data[providerId] = {
+					type: "oauth",
+					...credentialFieldsOf(next)
+				};
+				this.data[this.accountKeyFor(next.id)] = {
+					...next,
+					active: true
+				};
+				for (const entry of entries) {
+					if (entry.id === next.id || entry.id === instanceId) continue;
+					if (entry.active) this.data[this.accountKeyFor(entry.id)] = {
+						...entry,
+						active: false
+					};
+				}
+			} else delete this.data[providerId];
+		}
+		this.save();
+	}
+	/**
+	* Rename an account's label.
+	*/
+	renameAccount(providerId, instanceId, label) {
+		this.reload();
+		const key = this.accountKeyFor(instanceId);
+		const entry = this.data[key];
+		if (!isOAuthAccountRecord(entry)) return;
+		this.data[key] = {
+			...entry,
+			label
+		};
+		this.save();
+	}
+	/**
+	* Persist refreshed credentials for the account that initiated the refresh.
+	* The legacy slot is updated only if that account is still active when the
+	* refresh completes; otherwise a delayed refresh could overwrite a newer
+	* activation.
+	*/
+	persistRefreshedCredential(providerId, instanceId, creds) {
+		this.reload();
+		if (instanceId) {
+			const key = this.accountKeyFor(instanceId);
+			const entry = this.data[key];
+			if (!isOAuthAccountRecord(entry)) return;
+			this.data[key] = {
+				...entry,
+				...creds,
+				type: "oauth-account"
+			};
+			if (entry.active) {
+				const slot = this.data[providerId];
+				this.data[providerId] = slot?.type === "oauth" ? {
+					...slot,
+					...creds,
+					type: "oauth"
+				} : {
+					type: "oauth",
+					...creds
+				};
+			}
+		} else {
+			const slot = this.data[providerId];
+			this.data[providerId] = slot?.type === "oauth" ? {
+				...slot,
+				...creds,
+				type: "oauth"
+			} : {
+				type: "oauth",
+				...creds
+			};
+		}
+		this.save();
+	}
+	/**
+	* Refresh one account instance through the per-instance dedupe map. Used
+	* for sibling refreshes during the rotation walk, so a concurrent
+	* `getApiKey` that reloads storage mid-walk (after the candidate was
+	* activated but before its refresh resolves) joins the same refresh
+	* instead of double-spending a single-use refresh token.
+	*/
+	async refreshInstance(providerId, instanceId, creds) {
+		const provider = getOAuthProvider(providerId);
+		if (!provider) return void 0;
+		const refreshKey = `${providerId}:${instanceId}`;
+		const pending = this.refreshPromises.get(refreshKey);
+		if (pending) return pending;
+		const refresh = (async () => {
+			try {
+				const fresh = await provider.refreshToken(creds);
+				this.persistRefreshedCredential(providerId, instanceId, fresh);
+				return fresh;
+			} catch {
+				return;
+			}
+		})();
+		this.refreshPromises.set(refreshKey, refresh);
+		try {
+			return await refresh;
+		} finally {
+			this.refreshPromises.delete(refreshKey);
+		}
+	}
+	/**
+	* Get a ready-to-use OAuth credential snapshot, auto-refreshing if needed.
+	* A failed refresh leaves the active account unchanged and returns undefined;
+	* the account-rotation processor owns switching so it can persist a visible
+	* account-switch notice with the request that triggered the change.
+	*/
+	async getOAuthCredential(providerId, accountInstanceId) {
+		this.reload();
+		const activeEntry = this.getActiveAccount(providerId);
+		const selectedEntry = accountInstanceId ? this.accountEntries(providerId).find((entry) => entry.id === accountInstanceId) : activeEntry;
+		const slot = this.data[providerId];
+		let credential;
+		if (selectedEntry) {
+			const { type: _type, id: _id, label: _label, addedAt: _addedAt, active: _active, ...accountCredential } = selectedEntry;
+			credential = accountCredential;
+			if (selectedEntry.active && slot?.type === "oauth" && slot.refresh === selectedEntry.refresh) {
+				const { type: _slotType, ...slotCredential } = slot;
+				credential = {
+					...credential,
+					...slotCredential
+				};
+			}
+		} else if (!accountInstanceId && slot?.type === "oauth") credential = slot;
+		if (!credential) return void 0;
+		const provider = getOAuthProvider(providerId);
+		if (!provider) return void 0;
+		const selectedInstanceId = selectedEntry?.id;
+		const toSnapshot = (credentials) => ({
+			type: "oauth",
+			...credentials,
+			accountInstanceId: selectedInstanceId
+		});
+		if (Date.now() < credential.expires) return toSnapshot(credential);
+		if (selectedInstanceId) {
+			const refreshed = await this.refreshInstance(providerId, selectedInstanceId, credential);
+			return refreshed ? toSnapshot(refreshed) : void 0;
+		}
+		const pendingRefresh = this.refreshPromises.get(providerId);
+		const refresh = pendingRefresh ?? (async () => {
+			try {
+				const fresh = await provider.refreshToken(credential);
+				this.persistRefreshedCredential(providerId, void 0, fresh);
+				return fresh;
+			} catch {
+				return;
+			}
+		})();
+		if (!pendingRefresh) this.refreshPromises.set(providerId, refresh);
+		try {
+			const refreshed = await refresh;
+			return refreshed ? toSnapshot(refreshed) : void 0;
+		} finally {
+			if (!pendingRefresh) this.refreshPromises.delete(providerId);
+		}
+	}
+	/** Get API key for a provider, refreshing OAuth tokens if needed. */
+	async getApiKey(providerId, accountInstanceId) {
+		this.reload();
 		const cred = this.data[providerId];
-		if (cred?.type === "api_key") return cred.key;
-		if (cred?.type === "oauth") {
-			const provider = getOAuthProvider(providerId);
-			if (!provider) return;
-			if (Date.now() >= cred.expires) {
-				const pendingRefresh = this.refreshPromises.get(providerId);
-				if (pendingRefresh) return pendingRefresh;
-				const refresh = (async () => {
-					try {
-						const newCreds = await provider.refreshToken(cred);
-						this.set(providerId, {
-							type: "oauth",
-							...newCreds
-						});
-						return provider.getApiKey(newCreds);
-					} catch {
-						return;
-					} finally {
-						this.refreshPromises.delete(providerId);
-					}
-				})();
-				this.refreshPromises.set(providerId, refresh);
-				return refresh;
+		if (accountInstanceId === void 0 && cred?.type === "api_key") return cred.key;
+		const oauth = await this.getOAuthCredential(providerId, accountInstanceId);
+		const provider = oauth ? getOAuthProvider(providerId) : void 0;
+		return oauth && provider ? provider.getApiKey(oauth) : void 0;
+	}
+	/**
+	* Force one refresh of the active OAuth account's tokens, regardless of
+	* expiry. The account-rotation error processor calls this when a provider
+	* rejects a not-yet-expired token (401/403) — server-side clock skew and
+	* refresh-token races surface that way. Returns the fresh access token, or
+	* undefined when the refresh fails or there is no OAuth credential.
+	* Shares the per-instance refresh dedupe with `getApiKey`.
+	*/
+	async forceRefreshActiveAccount(providerId, accountInstanceId) {
+		this.reload();
+		const activeEntry = this.getActiveAccount(providerId);
+		const selectedEntry = accountInstanceId ? this.accountEntries(providerId).find((entry) => entry.id === accountInstanceId) : activeEntry;
+		const slot = this.get(providerId);
+		let cred;
+		if (selectedEntry) {
+			const { type: _type, id: _id, label: _label, addedAt: _addedAt, active: _active, ...accountCredential } = selectedEntry;
+			cred = accountCredential;
+		} else if (!accountInstanceId && slot?.type === "oauth") cred = slot;
+		if (!cred) return void 0;
+		const provider = getOAuthProvider(providerId);
+		if (!provider) return void 0;
+		const refreshKey = selectedEntry ? `${providerId}:${selectedEntry.id}` : providerId;
+		const pending = this.refreshPromises.get(refreshKey);
+		const refresh = pending ?? (async () => {
+			try {
+				const fresh = await provider.refreshToken(cred);
+				this.persistRefreshedCredential(providerId, selectedEntry?.id, fresh);
+				return fresh;
+			} catch {
+				return;
 			}
-			return provider.getApiKey(cred);
+		})();
+		if (!pending) this.refreshPromises.set(refreshKey, refresh);
+		try {
+			const creds = await refresh;
+			return creds ? provider.getApiKey(creds) : void 0;
+		} finally {
+			if (!pending) this.refreshPromises.delete(refreshKey);
 		}
 	}
 };