@oh-my-pi/pi-coding-agent 15.9.67 → 15.10.1

package/src/cli/gallery-screenshot.ts

@@ -0,0 +1,279 @@
+/**
+ * Render `omp gallery` output to PNG screenshots via VHS.
+ *
+ * ANSI escapes are invisible to anything that can only read raw bytes (e.g.
+ * agents), so `--screenshot` drives the rendered gallery through a real virtual
+ * terminal (VHS + ttyd + ffmpeg) and writes the captured frame to disk. The
+ * gallery is pre-rendered to truecolor ANSI in this process — where the user's
+ * theme and symbol preset are correct — then `cat`'d inside VHS so the captured
+ * pixels match exactly what the live TUI would draw.
+ *
+ * VHS is a hard dependency of this path: if it is not installed we fail loudly
+ * rather than degrade to a lossy fallback.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $which } from "@oh-my-pi/pi-utils";
+import { theme } from "../modes/theme/theme";
+import type { GallerySection } from "./gallery-cli";
+
+/** Nerd Font family so the gallery's icon glyphs (PUA) render instead of tofu. */
+export const DEFAULT_SCREENSHOT_FONT = "JetBrainsMono Nerd Font";
+export const DEFAULT_SCREENSHOT_FONT_SIZE = 18;
+
+/** Inner padding (px) VHS leaves around the terminal grid. */
+const PADDING = 14;
+const LINE_HEIGHT = 1.0;
+/**
+ * Upper-bound cell metrics relative to font size. Real monospace cells are
+ * smaller, so over-provisioning the canvas guarantees the gallery never
+ * soft-wraps (too few columns) or scrolls off the top (too few rows). The slack
+ * shows up only as a modest background margin, which is harmless for review.
+ */
+const CELL_WIDTH_RATIO = 0.65;
+const CELL_HEIGHT_RATIO = 1.5;
+/** Keep each image well under headless-Chromium's tall-canvas limits. */
+const MAX_IMAGE_HEIGHT_PX = 8000;
+
+export interface GalleryScreenshotOptions {
+	/** Gallery render width in columns (matches the ANSI line width). */
+	width: number;
+	/** VHS `FontFamily`. */
+	font?: string;
+	/** VHS `FontSize`. */
+	fontSize?: number;
+	/**
+	 * Output destination. When omitted, PNGs land in a fresh temp directory.
+	 * With multiple images the path is suffixed (`name-01.png`, `name-02.png`).
+	 */
+	out?: string;
+}
+
+/**
+ * Capture the gallery sections as one or more PNGs and return their absolute
+ * paths. Tall galleries are split across images so no single capture exceeds
+ * the terminal-canvas height limit.
+ */
+export async function captureGalleryScreenshots(
+	sections: GallerySection[],
+	options: GalleryScreenshotOptions,
+): Promise<string[]> {
+	const vhs = $which("vhs");
+	if (!vhs) {
+		throw new Error(
+			"`omp gallery --screenshot` requires VHS, which is not installed. " +
+				"Install it (e.g. `brew install vhs`, or see https://github.com/charmbracelet/vhs) and retry.",
+		);
+	}
+
+	const font = options.font ?? DEFAULT_SCREENSHOT_FONT;
+	const fontSize = options.fontSize ?? DEFAULT_SCREENSHOT_FONT_SIZE;
+	const cellHeight = fontSize * Math.max(LINE_HEIGHT, 1) * CELL_HEIGHT_RATIO;
+	const cellWidth = fontSize * CELL_WIDTH_RATIO;
+	const rowBudget = Math.max(40, Math.floor((MAX_IMAGE_HEIGHT_PX - 2 * PADDING) / cellHeight) - 2);
+	const chunks = chunkGallerySections(sections, rowBudget);
+	const themeJson = buildVhsTheme();
+
+	const baseDir = options.out
+		? path.dirname(path.resolve(options.out))
+		: fs.mkdtempSync(path.join(os.tmpdir(), "omp-gallery-"));
+	await fs.promises.mkdir(baseDir, { recursive: true });
+
+	const outPaths: string[] = [];
+	for (let i = 0; i < chunks.length; i++) {
+		if (chunks.length > 1) {
+			process.stderr.write(`Rendering gallery screenshot ${i + 1}/${chunks.length}…\n`);
+		}
+		const outPng = resolveScreenshotOutputPath(options.out, baseDir, i, chunks.length);
+		const lines = chunks[i].flatMap(section => section.lines);
+		await renderChunk({ vhs, lines, outPng, font, fontSize, cellWidth, cellHeight, width: options.width, themeJson });
+		outPaths.push(outPng);
+	}
+	return outPaths;
+}
+
+interface RenderChunkArgs {
+	vhs: string;
+	lines: string[];
+	outPng: string;
+	font: string;
+	fontSize: number;
+	cellWidth: number;
+	cellHeight: number;
+	width: number;
+	themeJson: string;
+}
+
+async function renderChunk(args: RenderChunkArgs): Promise<void> {
+	const rows = args.lines.length;
+	const widthPx = Math.ceil(args.width * args.cellWidth) + 2 * PADDING;
+	const heightPx = Math.ceil((rows + 2) * args.cellHeight) + 2 * PADDING;
+
+	const dir = path.dirname(args.outPng);
+	const stem = path.basename(args.outPng, path.extname(args.outPng));
+	const ansiPath = path.join(dir, `.${stem}.ansi`);
+	const tapePath = path.join(dir, `.${stem}.tape`);
+	const gifPath = path.join(dir, `.${stem}.gif`);
+
+	// CRLF so each gallery line is its own terminal row regardless of how the
+	// captured shell handles bare LF.
+	await Bun.write(ansiPath, `${args.lines.join("\r\n")}\r\n`);
+	await Bun.write(
+		tapePath,
+		buildTape({
+			gifPath,
+			outPng: args.outPng,
+			ansiPath,
+			widthPx,
+			heightPx,
+			font: args.font,
+			fontSize: args.fontSize,
+			themeJson: args.themeJson,
+		}),
+	);
+
+	try {
+		const result = await Bun.$`${args.vhs} ${tapePath}`.quiet().nothrow();
+		if (result.exitCode !== 0 || !(await Bun.file(args.outPng).exists())) {
+			const detail = result.stderr.toString().trim() || result.stdout.toString().trim();
+			throw new Error(`VHS failed to render the gallery screenshot${detail ? `: ${detail.slice(-600)}` : ""}`);
+		}
+	} finally {
+		await Promise.all([
+			fs.promises.rm(ansiPath, { force: true }),
+			fs.promises.rm(tapePath, { force: true }),
+			fs.promises.rm(gifPath, { force: true }),
+		]);
+	}
+}
+
+interface TapeArgs {
+	gifPath: string;
+	outPng: string;
+	ansiPath: string;
+	widthPx: number;
+	heightPx: number;
+	font: string;
+	fontSize: number;
+	themeJson: string;
+}
+
+function buildTape(args: TapeArgs): string {
+	// `Output` (a throwaway GIF) is mandatory for VHS to record; the screenshot
+	// is captured from the final visible frame. Setup is hidden so the typed
+	// `cat` command and shell prompt never appear in the capture, and a trailing
+	// `sleep` keeps the shell from drawing a fresh prompt under the output.
+	const shellCommand = `clear; cat ${shellSingleQuote(args.ansiPath)}; sleep 120`;
+	return `${[
+		`Output ${JSON.stringify(args.gifPath)}`,
+		`Set Width ${args.widthPx}`,
+		`Set Height ${args.heightPx}`,
+		`Set FontFamily ${JSON.stringify(args.font)}`,
+		`Set FontSize ${args.fontSize}`,
+		`Set Padding ${PADDING}`,
+		`Set LineHeight ${LINE_HEIGHT}`,
+		`Set Theme ${args.themeJson}`,
+		"Hide",
+		`Type ${JSON.stringify(shellCommand)}`,
+		"Enter",
+		"Sleep 1.2s",
+		"Show",
+		"Sleep 400ms",
+		`Screenshot ${JSON.stringify(args.outPng)}`,
+	].join("\n")}\n`;
+}
+
+/**
+ * Build the VHS terminal theme. Only background/foreground/cursor matter: the
+ * gallery emits truecolor (`38;2`/`48;2`) escapes, so the 16-color palette is
+ * never consulted — it is filler to satisfy VHS's theme schema.
+ */
+function buildVhsTheme(): string {
+	const background = parseAnsiRgb(theme.getBgAnsi("statusLineBg")) ?? (theme.isLight ? "#ffffff" : "#1a1a1a");
+	const foreground = theme.isLight ? "#1a1a1a" : "#d4d4d4";
+	const selection = theme.isLight ? "#c8d6ff" : "#404862";
+	return JSON.stringify({
+		name: "omp-gallery",
+		background,
+		foreground,
+		cursor: foreground,
+		selection,
+		black: "#000000",
+		red: "#ff5555",
+		green: "#50fa7b",
+		yellow: "#f1fa8c",
+		blue: "#6272ff",
+		magenta: "#ff79c6",
+		cyan: "#8be9fd",
+		white: "#bfbfbf",
+		brightBlack: "#4d4d4d",
+		brightRed: "#ff6e6e",
+		brightGreen: "#69ff94",
+		brightYellow: "#ffffa5",
+		brightBlue: "#8aa0ff",
+		brightMagenta: "#ff92df",
+		brightCyan: "#a4ffff",
+		brightWhite: "#ffffff",
+	});
+}
+
+/** Extract `#rrggbb` from a truecolor SGR escape (`…38;2;r;g;b…` / `…48;2;…`). */
+function parseAnsiRgb(ansi: string): string | undefined {
+	const match = /[34]8;2;(\d+);(\d+);(\d+)/.exec(ansi);
+	if (!match) return undefined;
+	const hex = (value: string) => Number(value).toString(16).padStart(2, "0");
+	return `#${hex(match[1])}${hex(match[2])}${hex(match[3])}`;
+}
+
+/** POSIX single-quote a path for embedding in the VHS shell command. */
+function shellSingleQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Resolve a chunk's PNG path. A single image keeps the bare name (or the exact
+ * `out`); multiple images gain a zero-padded `-NN` suffix so they sort and never
+ * collide.
+ */
+export function resolveScreenshotOutputPath(
+	out: string | undefined,
+	baseDir: string,
+	index: number,
+	total: number,
+): string {
+	if (total === 1) {
+		return out ? path.resolve(out) : path.join(baseDir, "gallery.png");
+	}
+	const suffix = String(index + 1).padStart(2, "0");
+	if (out) {
+		const resolved = path.resolve(out);
+		const ext = path.extname(resolved) || ".png";
+		const stem = path.basename(resolved, ext);
+		return path.join(path.dirname(resolved), `${stem}-${suffix}${ext}`);
+	}
+	return path.join(baseDir, `gallery-${suffix}.png`);
+}
+
+/**
+ * Group whole tool sections into chunks that stay under `rowBudget` rows. A
+ * single section larger than the budget gets its own (taller) image rather than
+ * being split mid-renderer.
+ */
+export function chunkGallerySections(sections: GallerySection[], rowBudget: number): GallerySection[][] {
+	const chunks: GallerySection[][] = [];
+	let current: GallerySection[] = [];
+	let currentRows = 0;
+	for (const section of sections) {
+		const rows = section.lines.length;
+		if (current.length > 0 && currentRows + rows > rowBudget) {
+			chunks.push(current);
+			current = [];
+			currentRows = 0;
+		}
+		current.push(section);
+		currentRows += rows;
+	}
+	if (current.length > 0) chunks.push(current);
+	return chunks.length > 0 ? chunks : [[]];
+}

package/src/cli-commands.ts

@@ -22,6 +22,7 @@ export const commands: CommandEntry[] = [
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
 	{ name: "dry-balance", load: () => import("./commands/dry-balance").then(m => m.default) },
 	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
+	{ name: "gallery", load: () => import("./commands/gallery").then(m => m.default) },
 	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
 	{ name: "install", load: () => import("./commands/install").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },

package/src/commands/gallery.ts

@@ -0,0 +1,52 @@
+/**
+ * Render every built-in tool's renderer across its lifecycle states.
+ */
+import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { GALLERY_STATES, type GalleryState, runGalleryCommand } from "../cli/gallery-cli";
+
+export default class Gallery extends Command {
+	static description = "Preview tool renderers across streaming, in-progress, success, and failure states";
+
+	static flags = {
+		tool: Flags.string({ char: "t", description: "Render a single tool by name" }),
+		state: Flags.string({
+			char: "s",
+			description: "Render only the given lifecycle state(s)",
+			options: [...GALLERY_STATES],
+			multiple: true,
+		}),
+		width: Flags.integer({ char: "w", description: "Render width in columns" }),
+		expanded: Flags.boolean({
+			char: "e",
+			description: "Render the expanded variant of each renderer",
+			default: false,
+		}),
+		plain: Flags.boolean({ description: "Strip ANSI styling from the output", default: false }),
+		screenshot: Flags.boolean({
+			description:
+				"Capture the rendered output as PNG screenshot(s) via VHS instead of printing ANSI (requires vhs)",
+			default: false,
+		}),
+		out: Flags.string({
+			char: "o",
+			description: "Screenshot output path (with --screenshot); suffixed per image when split across multiple",
+		}),
+		font: Flags.string({ description: "Screenshot font family (default: JetBrainsMono Nerd Font)" }),
+		"font-size": Flags.integer({ description: "Screenshot font size in points (default: 18)" }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Gallery);
+		await runGalleryCommand({
+			tool: flags.tool,
+			states: flags.state as GalleryState[] | undefined,
+			width: flags.width,
+			expanded: flags.expanded,
+			plain: flags.plain,
+			screenshot: flags.screenshot,
+			out: flags.out,
+			font: flags.font,
+			fontSize: flags["font-size"],
+		});
+	}
+}

package/src/commands/launch.ts

@@ -2,7 +2,7 @@
  * Root command for the coding agent CLI.
  */
 
-import { THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
+import { THINKING_EFFORTS } from "@oh-my-pi/pi-ai/effort";
 import { APP_NAME } from "@oh-my-pi/pi-utils";
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import { parseArgs } from "../cli/args";

package/src/commit/analysis/conventional.ts

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import analysisSystemPrompt from "../../commit/prompts/analysis-system.md" with { type: "text" };
@@ -14,7 +14,7 @@ const ConventionalAnalysisTool = createConventionalAnalysisTool(
 
 export interface ConventionalAnalysisInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	contextFiles?: Array<{ path: string; content: string }>;
 	userContext?: string;

package/src/commit/analysis/summary.ts

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple, validateToolCall } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
@@ -19,7 +19,7 @@ const SummaryTool = {
 
 export interface SummaryInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	commitType: string;
 	scope: string | null;

package/src/commit/changelog/generate.ts

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple, validateToolCall } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
@@ -25,7 +25,7 @@ export const changelogTool = {
 
 export interface ChangelogPromptInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	changelogPath: string;
 	isPackageChangelog: boolean;

package/src/commit/changelog/index.ts

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { logger } from "@oh-my-pi/pi-utils";
 import { CHANGELOG_CATEGORIES } from "../../commit/types";
 import * as git from "../../utils/git";
@@ -15,7 +15,7 @@ const DEFAULT_MAX_DIFF_CHARS = 120_000;
 export interface ChangelogFlowInput {
 	cwd: string;
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	stagedFiles: string[];
 	dryRun: boolean;

package/src/commit/map-reduce/index.ts

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { $env } from "@oh-my-pi/pi-utils";
 import { parseFileDiffs } from "../../commit/git/diff";
 import type { ConventionalAnalysis } from "../../commit/types";
@@ -21,10 +21,10 @@ export interface MapReduceSettings {
 
 export interface MapReduceInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	smolModel: Model<Api>;
-	smolApiKey: string;
+	smolApiKey: ApiKey;
 	smolThinkingLevel?: ThinkingLevel;
 	diff: string;
 	stat: string;

package/src/commit/map-reduce/map-phase.ts

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, AssistantMessage, Message, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, AssistantMessage, Message, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import fileObserverSystemPrompt from "../../commit/prompts/file-observer-system.md" with { type: "text" };
@@ -18,7 +18,7 @@ const RETRY_BACKOFF_MS = 1000;
 
 export interface MapPhaseInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	files: FileDiff[];
 	config?: {

package/src/commit/map-reduce/reduce-phase.ts

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import reduceSystemPrompt from "../../commit/prompts/reduce-system.md" with { type: "text" };
@@ -12,7 +12,7 @@ const ReduceTool = createConventionalAnalysisTool("Synthesize file observations
 
 export interface ReducePhaseInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	observations: FileObservation[];
 	stat: string;

package/src/commit/model-selection.ts

@@ -1,5 +1,6 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
+import type { ApiKeyResolverRegistry } from "../config/api-key-resolver";
 import { MODEL_ROLE_IDS } from "../config/model-registry";
 import {
 	type ModelLookupRegistry,
@@ -12,13 +13,19 @@ import MODEL_PRIO from "../priority.json" with { type: "json" };
 
 export interface ResolvedCommitModel {
 	model: Model<Api>;
-	apiKey: string;
+	/**
+	 * Resolver for the model's bearer: re-resolves on 401 / usage-limit so the
+	 * whole commit pipeline (analysis, map/reduce, changelog) inherits the
+	 * central force-refresh + account-rotation policy.
+	 */
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 }
 
-type CommitModelRegistry = ModelLookupRegistry & {
-	getApiKey: (model: Model<Api>) => Promise<string | undefined>;
-};
+type CommitModelRegistry = ModelLookupRegistry &
+	ApiKeyResolverRegistry & {
+		getApiKey: (model: Model<Api>) => Promise<string | undefined>;
+	};
 
 export async function resolvePrimaryModel(
 	override: string | undefined,
@@ -38,20 +45,32 @@ export async function resolvePrimaryModel(
 	if (!apiKey) {
 		throw new Error(`No API key available for model ${model.provider}/${model.id}`);
 	}
-	return { model, apiKey, thinkingLevel: resolved?.thinkingLevel };
+	return {
+		model,
+		apiKey: modelRegistry.resolver(model.provider, { baseUrl: model.baseUrl }),
+		thinkingLevel: resolved?.thinkingLevel,
+	};
 }
 
 export async function resolveSmolModel(
 	settings: Settings,
 	modelRegistry: CommitModelRegistry,
 	fallbackModel: Model<Api>,
-	fallbackApiKey: string,
+	fallbackApiKey: ApiKey,
 ): Promise<ResolvedCommitModel> {
 	const available = modelRegistry.getAvailable();
 	const resolvedSmol = resolveRoleSelection(["smol"], settings, available, modelRegistry);
 	if (resolvedSmol?.model) {
 		const apiKey = await modelRegistry.getApiKey(resolvedSmol.model);
-		if (apiKey) return { model: resolvedSmol.model, apiKey, thinkingLevel: resolvedSmol.thinkingLevel };
+		if (apiKey) {
+			return {
+				model: resolvedSmol.model,
+				apiKey: modelRegistry.resolver(resolvedSmol.model.provider, {
+					baseUrl: resolvedSmol.model.baseUrl,
+				}),
+				thinkingLevel: resolvedSmol.thinkingLevel,
+			};
+		}
 	}
 
 	const matchPreferences = { usageOrder: settings.getStorage()?.getModelUsageOrder() };
@@ -59,7 +78,12 @@ export async function resolveSmolModel(
 		const candidate = parseModelPattern(pattern, available, matchPreferences, { modelRegistry }).model;
 		if (!candidate) continue;
 		const apiKey = await modelRegistry.getApiKey(candidate);
-		if (apiKey) return { model: candidate, apiKey };
+		if (apiKey) {
+			return {
+				model: candidate,
+				apiKey: modelRegistry.resolver(candidate.provider, { baseUrl: candidate.baseUrl }),
+			};
+		}
 	}
 
 	return { model: fallbackModel, apiKey: fallbackApiKey };

package/src/commit/pipeline.ts

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { getProjectDir, logger, prompt } from "@oh-my-pi/pi-utils";
 import { ModelRegistry } from "../config/model-registry";
 import { Settings } from "../config/settings";
@@ -145,10 +145,10 @@ async function generateAnalysis(input: {
 	contextFiles: Array<{ path: string; content: string }>;
 	userContext?: string;
 	primaryModel: Model<Api>;
-	primaryApiKey: string;
+	primaryApiKey: ApiKey;
 	primaryThinkingLevel?: ThinkingLevel;
 	smolModel: Model<Api>;
-	smolApiKey: string;
+	smolApiKey: ApiKey;
 	smolThinkingLevel?: ThinkingLevel;
 	commitSettings: {
 		mapReduceEnabled: boolean;
@@ -206,7 +206,7 @@ async function generateSummaryWithRetry(input: {
 	analysis: ConventionalAnalysis;
 	stat: string;
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	userContext?: string;
 }): Promise<{ summary: string }> {

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

@@ -0,0 +1,58 @@
+import type { ApiKeyResolver, AuthStorage } from "@oh-my-pi/pi-ai";
+
+export interface ApiKeyResolverOptions {
+	/** Session id for credential stickiness; read at resolve time by the caller. */
+	sessionId?: string;
+	/** Provider base URL hint forwarded to the auth-storage cascade. */
+	baseUrl?: string;
+}
+
+/**
+ * Minimal slice of `ModelRegistry` the resolver needs. Typed structurally so
+ * narrower registry shells (e.g. the commit pipeline's `CommitModelRegistry`)
+ * can build resolvers without depending on the full class.
+ */
+export interface ApiKeyResolverRegistry {
+	getApiKeyForProvider(
+		provider: string,
+		sessionId?: string,
+		options?: { baseUrl?: string; forceRefresh?: boolean; signal?: AbortSignal },
+	): Promise<string | undefined>;
+	authStorage: Pick<AuthStorage, "rotateSessionCredential">;
+	/**
+	 * Build an {@link ApiKeyResolver} implementing the central a/b/c auth-retry
+	 * 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)`.
+	 */
+	resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;
+}
+
+/**
+ * Default implementation of {@link ApiKeyResolverRegistry.resolver}.
+ * Also usable standalone for structural registries that don't carry the method.
+ */
+export function createApiKeyResolver(
+	registry: Pick<ApiKeyResolverRegistry, "getApiKeyForProvider" | "authStorage">,
+	provider: string,
+	options: ApiKeyResolverOptions = {},
+): ApiKeyResolver {
+	const { sessionId, baseUrl } = options;
+	return async ({ lastChance, error, signal }) => {
+		if (error === undefined) {
+			return registry.getApiKeyForProvider(provider, sessionId, { baseUrl });
+		}
+		if (lastChance) {
+			// Account constraint (401 / usage / account-rate-limit): rotate to a
+			// sibling credential. We do NOT honor any retry-after here — if a
+			// sibling exists we switch immediately; the precise no-sibling backoff
+			// is owned by `markUsageLimitReached` (default + server usage-report
+			// reset) and the outer whole-turn retry layer.
+			await registry.authStorage.rotateSessionCredential(provider, sessionId, { error, signal });
+			return registry.getApiKeyForProvider(provider, sessionId, { baseUrl });
+		}
+		return registry.getApiKeyForProvider(provider, sessionId, { baseUrl, forceRefresh: true, signal });
+	};
+}