@oh-my-pi/pi-coding-agent 15.11.3 → 15.11.6

package/src/cli/usage-cli.ts

@@ -7,7 +7,14 @@
  * credentials produced no usage report are listed too, so the output
  * always covers the full credential pool.
  */
-import type { AuthStorage, UsageLimit, UsageReport, UsageUnit } from "@oh-my-pi/pi-ai";
+import {
+	type AuthStorage,
+	resolveUsedFraction,
+	type UsageHistoryEntry,
+	type UsageLimit,
+	type UsageReport,
+	type UsageUnit,
+} from "@oh-my-pi/pi-ai";
 import { formatDuration, formatNumber } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { ModelRegistry } from "../config/model-registry";
@@ -19,6 +26,10 @@ export interface UsageCommandArgs {
 	json?: boolean;
 	provider?: string;
 	redact?: boolean;
+	/** Show recorded usage-limit history instead of a live snapshot. */
+	history?: boolean;
+	/** History window in days (with `history`). */
+	days?: number;
 }
 
 /** Identity slice of a stored credential, for "every account" coverage. */
@@ -139,20 +150,9 @@ function collectIdentityStrings(reports: UsageReport[], accounts: UsageAccountId
 
 type LimitStatus = NonNullable<UsageLimit["status"]>;
 
-function resolveFraction(limit: UsageLimit): number | undefined {
-	const amount = limit.amount;
-	if (amount.usedFraction !== undefined) return amount.usedFraction;
-	if (amount.used !== undefined && amount.limit !== undefined && amount.limit > 0) {
-		return amount.used / amount.limit;
-	}
-	if (amount.unit === "percent" && amount.used !== undefined) return amount.used / 100;
-	if (amount.remainingFraction !== undefined) return Math.max(0, 1 - amount.remainingFraction);
-	return undefined;
-}
-
 function resolveStatus(limit: UsageLimit): LimitStatus {
 	if (limit.status && limit.status !== "unknown") return limit.status;
-	const fraction = resolveFraction(limit);
+	const fraction = resolveUsedFraction(limit);
 	if (fraction === undefined) return "unknown";
 	if (fraction >= 1) return "exhausted";
 	if (fraction >= 0.8) return "warning";
@@ -208,7 +208,7 @@ function describeAmount(limit: UsageLimit): string {
 	} else if (absoluteUnit && amount.remaining !== undefined) {
 		parts.push(`${formatUnitValue(amount.remaining, amount.unit)}${UNIT_SUFFIX[amount.unit]} left`);
 	}
-	const fraction = resolveFraction(limit);
+	const fraction = resolveUsedFraction(limit);
 	if (fraction !== undefined) {
 		parts.push(`${(fraction * 100).toFixed(1)}% used`);
 	} else if (amount.remainingFraction !== undefined) {
@@ -219,7 +219,7 @@ function describeAmount(limit: UsageLimit): string {
 }
 
 function renderBar(limit: UsageLimit): string {
-	const fraction = resolveFraction(limit);
+	const fraction = resolveUsedFraction(limit);
 	if (fraction === undefined) return chalk.dim("·".repeat(BAR_WIDTH));
 	const clamped = Math.min(Math.max(fraction, 0), 1);
 	const filled = Math.round(clamped * BAR_WIDTH);
@@ -325,6 +325,8 @@ function formatAccountHeader(
 	let header = `${icon} ${chalk.bold(redaction?.get(label) ?? label)}`;
 	const planType = report.metadata?.planType;
 	if (typeof planType === "string" && planType) header += chalk.dim(` · plan: ${planType}`);
+	const savedResets = report.resetCredits?.availableCount ?? 0;
+	if (savedResets > 0) header += chalk.cyan(` · ✦ ${savedResets} saved reset${savedResets === 1 ? "" : "s"}`);
 	if (report.fetchedAt && nowMs - report.fetchedAt > 90_000) {
 		header += chalk.dim(` · fetched ${formatDuration(nowMs - report.fetchedAt)} ago`);
 	}
@@ -375,7 +377,7 @@ export function computeProviderWindowStats(reports: UsageReport[]): ProviderWind
 	for (const report of reports) {
 		const accountMax = new Map<string, number>();
 		for (const limit of report.limits) {
-			const fraction = resolveFraction(limit);
+			const fraction = resolveUsedFraction(limit);
 			if (fraction === undefined) continue;
 			const durationMs = limit.window?.durationMs;
 			const key =
@@ -482,6 +484,144 @@ export function formatUsageBreakdown(
 	return lines.join("\n");
 }
 
+const HISTORY_SPARK_WIDTH = 48;
+const SPARK_LEVELS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"] as const;
+
+interface HistorySeries {
+	title: string;
+	/** Snapshots ascending by recordedAt (listUsageHistory order). */
+	entries: UsageHistoryEntry[];
+}
+
+interface HistoryAccount {
+	label: string;
+	series: Map<string, HistorySeries>;
+}
+
+/** Mirror of {@link limitTitle} for history rows (no scope/tier available). */
+function historySeriesTitle(entry: UsageHistoryEntry): string {
+	const label = entry.label;
+	const windowLabel = entry.windowLabel;
+	if (!windowLabel) return label;
+	if (windowLabel.toLowerCase() === "quota window") return label;
+	if (label.toLowerCase().includes(windowLabel.toLowerCase())) return label;
+	return `${label} (${windowLabel})`;
+}
+
+function historyAccountLabel(entry: UsageHistoryEntry): string {
+	return entry.email ?? entry.accountId ?? entry.accountKey;
+}
+
+function historyStatus(fraction: number | undefined, status: UsageHistoryEntry["status"]): LimitStatus {
+	if (status && status !== "unknown") return status;
+	if (fraction === undefined) return "unknown";
+	if (fraction >= 1) return "exhausted";
+	if (fraction >= 0.8) return "warning";
+	return "ok";
+}
+
+/** Peak-per-bucket sparkline over [sinceMs, nowMs]; empty buckets render dim dots. */
+function renderHistorySparkline(entries: UsageHistoryEntry[], sinceMs: number, nowMs: number): string {
+	const span = Math.max(1, nowMs - sinceMs);
+	const buckets: Array<number | undefined> = new Array(HISTORY_SPARK_WIDTH).fill(undefined);
+	for (const entry of entries) {
+		if (entry.usedFraction === undefined) continue;
+		const offset = Math.floor(((entry.recordedAt - sinceMs) / span) * HISTORY_SPARK_WIDTH);
+		const index = Math.min(HISTORY_SPARK_WIDTH - 1, Math.max(0, offset));
+		const prev = buckets[index];
+		buckets[index] = prev === undefined ? entry.usedFraction : Math.max(prev, entry.usedFraction);
+	}
+	return buckets
+		.map(fraction => {
+			if (fraction === undefined) return chalk.dim("·");
+			const clamped = Math.min(Math.max(fraction, 0), 1);
+			const level = SPARK_LEVELS[Math.min(SPARK_LEVELS.length - 1, Math.floor(clamped * SPARK_LEVELS.length))];
+			return STATUS_COLOR[historyStatus(clamped, undefined)](level);
+		})
+		.join("");
+}
+
+/** Identity strings a history rendering could surface — input for {@link buildRedactionMap}. */
+function collectHistoryIdentityStrings(entries: UsageHistoryEntry[]): string[] {
+	const values: string[] = [];
+	for (const entry of entries) {
+		if (entry.email) values.push(entry.email);
+		if (entry.accountId) values.push(entry.accountId);
+		values.push(entry.accountKey);
+	}
+	return values;
+}
+
+/**
+ * Render recorded usage-limit history: per provider, per account, one
+ * peak-per-bucket sparkline per limit window plus latest/peak percentages.
+ */
+export function formatUsageHistory(
+	entries: UsageHistoryEntry[],
+	sinceMs: number,
+	nowMs: number,
+	redaction?: Map<string, string>,
+): string {
+	const providers = new Map<string, Map<string, HistoryAccount>>();
+	for (const entry of entries) {
+		let accounts = providers.get(entry.provider);
+		if (!accounts) {
+			accounts = new Map();
+			providers.set(entry.provider, accounts);
+		}
+		let account = accounts.get(entry.accountKey);
+		if (!account) {
+			account = { label: historyAccountLabel(entry), series: new Map() };
+			accounts.set(entry.accountKey, account);
+		}
+		let series = account.series.get(entry.limitId);
+		if (!series) {
+			series = { title: historySeriesTitle(entry), entries: [] };
+			account.series.set(entry.limitId, series);
+		}
+		// Labels can change across snapshots (provider renames); latest wins.
+		series.title = historySeriesTitle(entry);
+		series.entries.push(entry);
+	}
+
+	const lines: string[] = [];
+	lines.push(
+		`${chalk.bold("Usage history")}${chalk.dim(` · last ${formatDuration(nowMs - sinceMs)} · peak per bucket`)}`,
+	);
+
+	for (const provider of [...providers.keys()].sort((a, b) => a.localeCompare(b))) {
+		const accounts = providers.get(provider) ?? new Map<string, HistoryAccount>();
+		lines.push("");
+		lines.push(
+			`${chalk.bold.cyan(formatProviderName(provider))} ${chalk.dim(`— ${accounts.size} ${accounts.size === 1 ? "account" : "accounts"}`)}`,
+		);
+		const sortedAccounts = [...accounts.values()].sort((a, b) => a.label.localeCompare(b.label));
+		for (const account of sortedAccounts) {
+			lines.push(`  ${chalk.bold(redaction?.get(account.label) ?? account.label)}`);
+			const labelWidth = [...account.series.values()].reduce((max, series) => Math.max(max, series.title.length), 0);
+			const sortedSeries = [...account.series.values()].sort((a, b) => a.title.localeCompare(b.title));
+			for (const series of sortedSeries) {
+				const fractions = series.entries
+					.map(entry => entry.usedFraction)
+					.filter((fraction): fraction is number => fraction !== undefined);
+				const latestEntry = series.entries[series.entries.length - 1];
+				const latestFraction = fractions.length > 0 ? fractions[fractions.length - 1] : undefined;
+				const peakFraction = fractions.length > 0 ? Math.max(...fractions) : undefined;
+				const status = historyStatus(latestFraction, latestEntry?.status);
+				const details: string[] = [];
+				if (latestFraction !== undefined) details.push(`latest ${(latestFraction * 100).toFixed(1)}%`);
+				if (peakFraction !== undefined) details.push(`peak ${(peakFraction * 100).toFixed(1)}%`);
+				details.push(`${series.entries.length} snapshot${series.entries.length === 1 ? "" : "s"}`);
+				lines.push(
+					`      ${STATUS_COLOR[status]("●")} ${series.title.padEnd(labelWidth)}  ${renderHistorySparkline(series.entries, sinceMs, nowMs)}  ${chalk.dim(details.join(" · "))}`,
+				);
+			}
+		}
+	}
+
+	return lines.join("\n");
+}
+
 function collectStoredAccounts(authStorage: AuthStorage): UsageAccountIdentity[] {
 	const accounts: UsageAccountIdentity[] = [];
 	const all = authStorage.getAll();
@@ -541,6 +681,37 @@ function redactReportForJson(
 export async function runUsageCommand(cmd: UsageCommandArgs): Promise<void> {
 	const authStorage = await discoverAuthStorage();
 	try {
+		if (cmd.history) {
+			const days = cmd.days !== undefined && Number.isFinite(cmd.days) && cmd.days > 0 ? cmd.days : 7;
+			const nowMs = Date.now();
+			const sinceMs = nowMs - days * 86_400_000;
+			const entries = authStorage.listUsageHistory({ sinceMs, provider: cmd.provider?.toLowerCase() });
+			const redaction = cmd.redact ? buildRedactionMap(collectHistoryIdentityStrings(entries)) : undefined;
+			if (cmd.json) {
+				const masked = redaction
+					? entries.map(entry => ({
+							...entry,
+							accountKey: redaction.get(entry.accountKey) ?? entry.accountKey,
+							email: maskIdentity(redaction, entry.email),
+							accountId: maskIdentity(redaction, entry.accountId),
+						}))
+					: entries;
+				process.stdout.write(`${JSON.stringify({ generatedAt: nowMs, sinceMs, entries: masked }, null, 2)}\n`);
+				return;
+			}
+			if (entries.length === 0) {
+				const scope = cmd.provider ? ` for provider "${cmd.provider}"` : "";
+				process.stderr.write(
+					chalk.yellow(
+						`No usage history recorded${scope} yet. Snapshots accumulate whenever usage is fetched (TUI footer, /usage, omp usage).\n`,
+					),
+				);
+				process.exitCode = 1;
+				return;
+			}
+			process.stdout.write(`${formatUsageHistory(entries, sinceMs, nowMs, redaction)}\n`);
+			return;
+		}
 		const modelRegistry = new ModelRegistry(authStorage);
 		const reports =
 			(await authStorage.fetchUsageReports({

package/src/commands/usage.ts

@@ -15,6 +15,11 @@ export default class Usage extends Command {
 			description: "Redact account emails/ids (shortest unique prefix) for sharing screenshots",
 			default: false,
 		}),
+		history: Flags.boolean({
+			description: "Show recorded usage-limit history (hourly snapshots) instead of a live snapshot",
+			default: false,
+		}),
+		days: Flags.integer({ char: "d", description: "History window in days (with --history)", default: 7 }),
 	};
 
 	static examples = [
@@ -22,6 +27,7 @@ export default class Usage extends Command {
 		"# Only Anthropic accounts\n  omp usage --provider anthropic",
 		"# Redact account identifiers for screenshots\n  omp usage --redact",
 		"# Machine-readable output\n  omp usage --json",
+		"# Usage-limit trend over the last 30 days\n  omp usage --history --days 30",
 	];
 
 	async run(): Promise<void> {
@@ -30,6 +36,8 @@ export default class Usage extends Command {
 			json: flags.json,
 			provider: flags.provider,
 			redact: flags.redact,
+			history: flags.history,
+			days: flags.days,
 		});
 	}
 }

package/src/commit/model-selection.ts

@@ -48,7 +48,7 @@ export async function resolvePrimaryModel(
 	}
 	return {
 		model,
-		apiKey: modelRegistry.resolver(model.provider, { baseUrl: model.baseUrl, modelId: model.id }),
+		apiKey: modelRegistry.resolver(model),
 		thinkingLevel: resolved?.thinkingLevel,
 	};
 }
@@ -66,10 +66,7 @@ export async function resolveSmolModel(
 		if (apiKey) {
 			return {
 				model: resolvedSmol.model,
-				apiKey: modelRegistry.resolver(resolvedSmol.model.provider, {
-					baseUrl: resolvedSmol.model.baseUrl,
-					modelId: resolvedSmol.model.id,
-				}),
+				apiKey: modelRegistry.resolver(resolvedSmol.model),
 				thinkingLevel: resolvedSmol.thinkingLevel,
 			};
 		}
@@ -83,7 +80,7 @@ export async function resolveSmolModel(
 		if (apiKey) {
 			return {
 				model: candidate,
-				apiKey: modelRegistry.resolver(candidate.provider, { baseUrl: candidate.baseUrl, modelId: candidate.id }),
+				apiKey: modelRegistry.resolver(candidate),
 			};
 		}
 	}

package/src/config/api-key-resolver.ts

@@ -1,4 +1,7 @@
-import type { ApiKeyResolver, AuthStorage } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKeyResolver, AuthStorage, Model } from "@oh-my-pi/pi-ai";
+
+/** Model slice accepted by the model-form `resolver(model, sessionId)` overload. */
+export type ApiKeyResolverModel = Pick<Model<Api>, "provider" | "baseUrl" | "id">;
 
 export interface ApiKeyResolverOptions {
 	/** Session id for credential stickiness; read at resolve time by the caller. */
@@ -26,10 +29,14 @@ export interface ApiKeyResolverRegistry {
 	 * policy: initial → resolve; step (b) → force-refresh same account; step (c)
 	 * → rotate to a sibling credential, then re-resolve.
 	 *
-	 * The resolver is stateless (safe to reuse across requests). Callers that
-	 * need the initial key for a guard can call `resolveApiKeyOnce(resolver)`.
+	 * Two call forms: `resolver(provider, options?)` for provider-scoped keys,
+	 * and `resolver(model, sessionId?)` which derives `baseUrl`/`modelId` from
+	 * the model. The resolver is stateless (safe to reuse across requests).
+	 * Callers that need the initial key for a guard can call
+	 * `resolveApiKeyOnce(resolver)`.
 	 */
 	resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;
+	resolver(model: ApiKeyResolverModel, sessionId?: string): ApiKeyResolver;
 }
 
 /**

package/src/config/keybindings.ts

@@ -137,7 +137,7 @@ export const KEYBINDINGS = {
 	},
 	"app.clipboard.pasteImage": {
 		defaultKeys: getDefaultPasteImageKeys(),
-		description: "Paste image from clipboard",
+		description: "Paste image or text from clipboard",
 	},
 	"app.clipboard.pasteTextRaw": {
 		defaultKeys: ["ctrl+shift+v", "alt+shift+v"],

package/src/config/model-discovery.ts

@@ -5,7 +5,7 @@
  * `discoverModelsByProviderType` with a `DiscoveryContext`; built-in provider
  * discovery lives in pi-catalog's provider-models.
  */
-import type { FetchImpl } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type FetchImpl, withAuth } from "@oh-my-pi/pi-ai";
 import type { Api, Model } from "@oh-my-pi/pi-ai/types";
 import { buildModel } from "@oh-my-pi/pi-catalog/build";
 import {
@@ -97,10 +97,12 @@ export interface DiscoveryContext {
 	/** Injected fetch implementation (tests stub this). */
 	fetch: FetchImpl;
 	/**
-	 * Resolve a provider's API key for `Authorization: Bearer …`. Returns
-	 * undefined when no key is stored or it is a local/no-auth sentinel.
+	 * Resolve a provider's bearer credential for `Authorization: Bearer …`.
+	 * Returns undefined when no key is stored or it is a local/no-auth
+	 * sentinel; otherwise an {@link ApiKey} whose resolver participates in the
+	 * central force-refresh/rotate auth-retry policy on 401/usage-limit.
 	 */
-	getBearerApiKey(provider: string): Promise<string | undefined>;
+	getBearerApiKeyResolver(provider: string): Promise<ApiKey | undefined>;
 }
 
 type OllamaDiscoveredModelMetadata = {
@@ -314,22 +316,26 @@ export async function discoverLlamaCppModels(
 	const baseUrl = normalizeLlamaCppBaseUrl(providerConfig.baseUrl);
 	const modelsUrl = `${baseUrl}/models`;
 
-	const headers: Record<string, string> = { ...(providerConfig.headers ?? {}) };
-	const apiKey = await ctx.getBearerApiKey(providerConfig.provider);
-	if (apiKey) {
-		headers.Authorization = `Bearer ${apiKey}`;
-	}
-
-	const [response, serverMetadata] = await Promise.all([
-		ctx.fetch(modelsUrl, {
-			headers,
-			signal: AbortSignal.timeout(250),
-		}),
-		discoverLlamaCppServerMetadata(ctx, baseUrl, headers),
-	]);
-	if (!response.ok) {
-		throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
-	}
+	const baseHeaders: Record<string, string> = { ...(providerConfig.headers ?? {}) };
+	let headers = baseHeaders;
+	const attempt = async (h: Record<string, string>) => {
+		const [response, metadata] = await Promise.all([
+			ctx.fetch(modelsUrl, {
+				headers: h,
+				signal: AbortSignal.timeout(250),
+			}),
+			discoverLlamaCppServerMetadata(ctx, baseUrl, h),
+		]);
+		if (!response.ok) {
+			throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
+		}
+		headers = h;
+		return [response, metadata] as const;
+	};
+	const apiKey = await ctx.getBearerApiKeyResolver(providerConfig.provider);
+	const [response, serverMetadata] = apiKey
+		? await withAuth(apiKey, key => attempt({ ...baseHeaders, Authorization: `Bearer ${key}` }))
+		: await attempt(baseHeaders);
 	const payload = (await response.json()) as { data?: Array<{ id: string }> };
 	const models = payload.data ?? [];
 	const discovered: Model<Api>[] = [];
@@ -370,19 +376,23 @@ export async function discoverOpenAIModelsList(
 	const baseUrl = normalizeOpenAIModelsListBaseUrl(providerConfig.baseUrl);
 	const modelsUrl = `${baseUrl}/models`;
 
-	const headers: Record<string, string> = { ...(providerConfig.headers ?? {}) };
-	const apiKey = await ctx.getBearerApiKey(providerConfig.provider);
-	if (apiKey) {
-		headers.Authorization = `Bearer ${apiKey}`;
-	}
-
-	const response = await ctx.fetch(modelsUrl, {
-		headers,
-		signal: AbortSignal.timeout(10_000),
-	});
-	if (!response.ok) {
-		throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
-	}
+	const baseHeaders: Record<string, string> = { ...(providerConfig.headers ?? {}) };
+	let headers = baseHeaders;
+	const attempt = async (h: Record<string, string>) => {
+		const res = await ctx.fetch(modelsUrl, {
+			headers: h,
+			signal: AbortSignal.timeout(10_000),
+		});
+		if (!res.ok) {
+			throw new Error(`HTTP ${res.status} from ${modelsUrl}`);
+		}
+		headers = h;
+		return res;
+	};
+	const apiKey = await ctx.getBearerApiKeyResolver(providerConfig.provider);
+	const response = apiKey
+		? await withAuth(apiKey, key => attempt({ ...baseHeaders, Authorization: `Bearer ${key}` }))
+		: await attempt(baseHeaders);
 	const payload = (await response.json()) as { data?: Array<{ id: string }> };
 	const models = payload.data ?? [];
 	const discovered: Model<Api>[] = [];
@@ -435,19 +445,23 @@ export async function discoverProxyModels(
 	const baseUrl = normalizeOpenAIModelsListBaseUrl(providerConfig.baseUrl);
 	const modelsUrl = `${baseUrl}/models`;
 
-	const headers: Record<string, string> = { ...(providerConfig.headers ?? {}) };
-	const apiKey = await ctx.getBearerApiKey(providerConfig.provider);
-	if (apiKey) {
-		headers.Authorization = `Bearer ${apiKey}`;
-	}
-
-	const response = await ctx.fetch(modelsUrl, {
-		headers,
-		signal: AbortSignal.timeout(10_000),
-	});
-	if (!response.ok) {
-		throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
-	}
+	const baseHeaders: Record<string, string> = { ...(providerConfig.headers ?? {}) };
+	let headers = baseHeaders;
+	const attempt = async (h: Record<string, string>) => {
+		const res = await ctx.fetch(modelsUrl, {
+			headers: h,
+			signal: AbortSignal.timeout(10_000),
+		});
+		if (!res.ok) {
+			throw new Error(`HTTP ${res.status} from ${modelsUrl}`);
+		}
+		headers = h;
+		return res;
+	};
+	const apiKey = await ctx.getBearerApiKeyResolver(providerConfig.provider);
+	const response = apiKey
+		? await withAuth(apiKey, key => attempt({ ...baseHeaders, Authorization: `Bearer ${key}` }))
+		: await attempt(baseHeaders);
 	const payload = (await response.json()) as {
 		data?: Array<{ id?: string; name?: string; supported_endpoint_types?: string[] }>;
 	};

package/src/config/model-registry.ts

@@ -57,7 +57,7 @@ import {
 import { isRecord, logger } from "@oh-my-pi/pi-utils";
 import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
 import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
-import { type ApiKeyResolverOptions, createApiKeyResolver } from "./api-key-resolver";
+import { type ApiKeyResolverModel, type ApiKeyResolverOptions, createApiKeyResolver } from "./api-key-resolver";
 import type { ConfigError, ConfigFile } from "./config-file";
 import {
 	DISCOVERY_DEFAULT_MAX_TOKENS,
@@ -1238,9 +1238,10 @@ export class ModelRegistry {
 	#discoveryContext(): DiscoveryContext {
 		return {
 			fetch: this.#fetch,
-			getBearerApiKey: async provider => {
+			getBearerApiKeyResolver: async provider => {
 				const apiKey = await this.getApiKeyForProvider(provider);
-				return apiKey && apiKey !== DEFAULT_LOCAL_TOKEN && apiKey !== kNoAuth ? apiKey : undefined;
+				if (!apiKey || apiKey === DEFAULT_LOCAL_TOKEN || apiKey === kNoAuth) return undefined;
+				return this.resolver(provider);
 			},
 		};
 	}
@@ -1754,12 +1755,24 @@ export class ModelRegistry {
 	}
 
 	/**
-	 * Build an {@link ApiKeyResolver} for this provider, implementing the
-	 * central a/b/c auth-retry policy. Callers that need the initial key for
-	 * a guard can call `resolveApiKeyOnce(resolver)`.
+	 * Build an {@link ApiKeyResolver} implementing the central a/b/c auth-retry
+	 * policy. Accepts a provider id with options, or a model with an optional
+	 * session id (`resolver(model, sessionId)`) which derives `baseUrl`/`modelId`
+	 * from the model. Callers that need the initial key for a guard can call
+	 * `resolveApiKeyOnce(resolver)`.
 	 */
-	resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver {
-		return createApiKeyResolver(this, provider, options);
+	resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;
+	resolver(model: ApiKeyResolverModel, sessionId?: string): ApiKeyResolver;
+	resolver(target: string | ApiKeyResolverModel, optionsOrSessionId?: ApiKeyResolverOptions | string): ApiKeyResolver {
+		const options = typeof optionsOrSessionId === "string" ? { sessionId: optionsOrSessionId } : optionsOrSessionId;
+		if (typeof target === "string") {
+			return createApiKeyResolver(this, target, options);
+		}
+		return createApiKeyResolver(this, target.provider, {
+			...options,
+			baseUrl: target.baseUrl,
+			modelId: target.id,
+		});
 	}
 
 	async #peekApiKeyForProvider(provider: string): Promise<string | undefined> {

package/src/config/model-resolver.ts

@@ -633,18 +633,72 @@ function isSessionInheritedAgentPattern(value: string): boolean {
 	return value === DEFAULT_MODEL_ROLE || value === `${PREFIX_MODEL_ROLE}${DEFAULT_MODEL_ROLE}` || value === "pi/task";
 }
 
-function resolveConfiguredRolePattern(value: string, settings?: Settings): string[] | undefined {
+function shouldInheritDefaultBeforePriority(role: ModelRole): boolean {
+	return role === "smol" || role === "slow" || role === "designer";
+}
+
+function resolveDefaultInheritedPatterns(
+	role: ModelRole,
+	configuredDefault: string | undefined,
+	roleDefaults: string[],
+	settings: Settings | undefined,
+	visited: Set<ModelRole>,
+): string[] {
+	if (!shouldInheritDefaultBeforePriority(role) || !configuredDefault) return [];
+
+	const resolved: string[] = [];
+	for (const pattern of normalizeModelPatternList(configuredDefault)) {
+		const { base: aliasCandidate, level: thinkingLevel } = splitThinkingSuffix(pattern, PREFIX_MODEL_ROLE.length);
+		const aliasRole = getModelRoleAlias(aliasCandidate);
+		if (aliasRole === role) {
+			// Self-alias (e.g. modelRoles.default = "pi/smol") would loop back to the
+			// same unset role; collapse straight to the built-in priority chain.
+			resolved.push(
+				...(thinkingLevel
+					? roleDefaults.map(defaultPattern => `${defaultPattern}:${thinkingLevel}`)
+					: roleDefaults),
+			);
+			continue;
+		}
+		if (aliasRole && !visited.has(aliasRole)) {
+			// Cross-role alias (e.g. modelRoles.default = "pi/slow"): resolve the
+			// target role's patterns now so downstream one-layer expanders see
+			// concrete model patterns instead of another role alias.
+			const recursed = resolveConfiguredRolePattern(pattern, settings, new Set(visited));
+			if (recursed && recursed.length > 0) {
+				resolved.push(...recursed);
+				continue;
+			}
+		}
+		resolved.push(pattern);
+	}
+	return resolved;
+}
+
+function resolveConfiguredRolePattern(
+	value: string,
+	settings?: Settings,
+	visited: Set<ModelRole> = new Set(),
+): string[] | undefined {
 	const normalized = value.trim();
 	if (!normalized) return undefined;
 
 	const { base: aliasCandidate, level: thinkingLevel } = splitThinkingSuffix(normalized, PREFIX_MODEL_ROLE.length);
 	const role = getModelRoleAlias(aliasCandidate);
 	if (!role) return [normalized];
+	if (visited.has(role)) return undefined;
+	visited.add(role);
 
 	const configured = settings?.getModelRole(role)?.trim();
+	const configuredDefault = settings?.getModelRole(DEFAULT_MODEL_ROLE)?.trim();
 	const roleDefaults = normalizeModelPatternList(MODEL_PRIO[role as keyof typeof MODEL_PRIO]);
-	const resolved = configured ? normalizeModelPatternList(configured) : roleDefaults;
-	if (!resolved || resolved.length === 0) {
+	const resolved = configured
+		? normalizeModelPatternList(configured)
+		: resolveDefaultInheritedPatterns(role, configuredDefault, roleDefaults, settings, visited);
+	if (resolved.length === 0) {
+		resolved.push(...roleDefaults);
+	}
+	if (resolved.length === 0) {
 		return undefined;
 	}