@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/cli/completion-gen.ts

@@ -188,10 +188,10 @@ function bashValueBranch(bin: string, v: ValueSource): string {
 		case "enum":
 			return `COMPREPLY=( $(compgen -W "${bashWords(v.values)}" -- "$cur") ); return 0`;
 		case "list":
-			return `_prometheus_comma "${bashWords(v.values)}"; return 0`;
+			return `_omp_comma "${bashWords(v.values)}"; return 0`;
 		case "models":
 			return v.multiple
-				? `_prometheus_comma "$(command ${bin} __complete models 2>/dev/null | cut -f1)"; return 0`
+				? `_omp_comma "$(command ${bin} __complete models 2>/dev/null | cut -f1)"; return 0`
 				: `COMPREPLY=( $(compgen -W "$(command ${bin} __complete models -- "$cur" 2>/dev/null | cut -f1)" -- "$cur") ); return 0`;
 		case "sessions":
 			return `COMPREPLY=( $(compgen -W "$(command ${bin} __complete sessions -- "$cur" 2>/dev/null | cut -f1)" -- "$cur") ); return 0`;
@@ -229,7 +229,7 @@ function generateBash(spec: CompletionSpec): string {
 	parts.push("");
 
 	// Comma-aware static/dynamic list completion helper.
-	parts.push(`_prometheus_comma() {
+	parts.push(`_omp_comma() {
 	local words="$1" realcur prefix
 	realcur="\${cur##*,}"
 	prefix="\${cur%"$realcur"}"
@@ -244,7 +244,7 @@ function generateBash(spec: CompletionSpec): string {
 
 	// Root handler: top-level flags + subcommand names.
 	const subTokens = spec.commands.flatMap(commandTokens).sort();
-	parts.push(`_prometheus_root() {
+	parts.push(`_omp_root() {
 	case "$prev" in
 ${bashFlagCase(bin, spec.root.flags)}
 	esac
@@ -266,7 +266,7 @@ ${bashFlagCase(bin, spec.root.flags)}
 			: fileArg
 				? `COMPREPLY=( $(compgen -f -- "$cur") ); compopt -o filenames`
 				: ":";
-		parts.push(`_prometheus_cmd_${bashFn(c.name)}() {
+		parts.push(`_omp_cmd_${bashFn(c.name)}() {
 	case "$prev" in
 ${bashFlagCase(bin, c.flags)}
 	esac
@@ -282,9 +282,9 @@ ${bashFlagCase(bin, c.flags)}
 	// Dispatcher.
 	const dispatch: string[] = [];
 	for (const c of spec.commands) {
-		dispatch.push(`\t\t${commandTokens(c).join("|")})\n\t\t\t_prometheus_cmd_${bashFn(c.name)}\n\t\t\t;;`);
+		dispatch.push(`\t\t${commandTokens(c).join("|")})\n\t\t\t_omp_cmd_${bashFn(c.name)}\n\t\t\t;;`);
 	}
-	parts.push(`_prometheus() {
+	parts.push(`_omp() {
 	local cur prev cmd i
 	cur="\${COMP_WORDS[COMP_CWORD]}"
 	prev="\${COMP_WORDS[COMP_CWORD-1]}"
@@ -297,10 +297,10 @@ ${bashFlagCase(bin, c.flags)}
 	done
 	case "$cmd" in
 ${dispatch.join("\n")}
-		*) _prometheus_root ;;
+		*) _omp_root ;;
 	esac
 }
-complete -F _prometheus ${bin}`);
+complete -F _omp ${bin}`);
 	parts.push("");
 	return `${parts.join("\n")}\n`;
 }
@@ -331,11 +331,11 @@ function zshAction(v: ValueSource): string {
 		case "enum":
 			return `:value:(${v.values.join(" ")})`;
 		case "list":
-			return ":value:_prometheus_tools";
+			return ":value:_omp_tools";
 		case "models":
-			return v.multiple ? ":models:_prometheus_models_list" : ":model:_prometheus_call models";
+			return v.multiple ? ":models:_omp_models_list" : ":model:_omp_call models";
 		case "sessions":
-			return ":session:_prometheus_call sessions";
+			return ":session:_omp_call sessions";
 		case "file":
 			return ":file:_files";
 		case "dir":
@@ -362,7 +362,7 @@ function zshArgSpec(f: CompletionArg): string {
 
 function generateZsh(spec: CompletionSpec): string {
 	const { bin } = spec;
-	// The `:value:_prometheus_tools` action references this helper; bake its candidates
+	// The `:value:_omp_tools` action references this helper; bake its candidates
 	// from the spec's `list` flag so the generator stays a pure function of its
 	// input (bash/fish read `v.values` inline for the same reason).
 	const listFlag = [...spec.root.flags, ...spec.commands.flatMap(c => c.flags)].find(f => f.value.kind === "list");
@@ -373,7 +373,7 @@ function generateZsh(spec: CompletionSpec): string {
 	parts.push("");
 
 	// Dynamic helpers (single source: `<bin> __complete <kind>` → value<TAB>desc).
-	parts.push(`_prometheus_call() {
+	parts.push(`_omp_call() {
 	local kind=$1
 	local -a items
 	local line
@@ -383,7 +383,7 @@ function generateZsh(spec: CompletionSpec): string {
 	done
 	_describe -t "$kind" "$kind" items
 }
-_prometheus_models_list() {
+_omp_models_list() {
 	local -a items
 	local line
 	for line in "\${(@f)$(command ${bin} __complete models 2>/dev/null)}"; do
@@ -392,12 +392,12 @@ _prometheus_models_list() {
 	done
 	_values -s , 'models' $items
 }
-_prometheus_tools() { _values -s , 'tools' ${toolNames} }`);
+_omp_tools() { _values -s , 'tools' ${toolNames} }`);
 	parts.push("");
 
 	// Subcommand description table.
 	const cmdRows = spec.commands.map(c => `\t\t'${c.name}:${zshDesc(c.description)}'`).join("\n");
-	parts.push(`_prometheus_commands() {
+	parts.push(`_omp_commands() {
 	local -a commands
 	commands=(
 ${cmdRows}
@@ -409,7 +409,7 @@ ${cmdRows}
 	// Per-subcommand argument functions.
 	for (const c of spec.commands) {
 		const specs = ["'(-h --help)'{-h,--help}'[Show help]'", ...c.flags.map(zshFlagSpec), ...c.args.map(zshArgSpec)];
-		parts.push(`_prometheus_cmd_${bashFn(c.name)}() {
+		parts.push(`_omp_cmd_${bashFn(c.name)}() {
 	_arguments -s \\
 		${specs.join(" \\\n\t\t")}
 }`);
@@ -418,16 +418,16 @@ ${cmdRows}
 
 	// Top-level dispatch.
 	const aliasArms = spec.commands
-		.map(c => `\t\t\t${commandTokens(c).join("|")}) _prometheus_cmd_${bashFn(c.name)} ;;`)
+		.map(c => `\t\t\t${commandTokens(c).join("|")}) _omp_cmd_${bashFn(c.name)} ;;`)
 		.join("\n");
 	const rootSpecs = [
 		"'(-h --help)'{-h,--help}'[Show help]'",
 		"'(-v --version)'{-v,--version}'[Show version]'",
 		...spec.root.flags.map(zshFlagSpec),
-		"'1: :_prometheus_commands'",
+		"'1: :_omp_commands'",
 		"'*::arg:->args'",
 	];
-	parts.push(`_prometheus() {
+	parts.push(`_omp() {
 	local curcontext="$curcontext" state line
 	typeset -A opt_args
 	_arguments -C -s \\
@@ -440,13 +440,13 @@ ${aliasArms}
 			;;
 	esac
 }
-# Works both ways: autoloaded from $fpath (file named _prometheus) or eval'd from a
-# startup file. When autoloaded, funcstack[1] is _prometheus and we invoke it; when
+# Works both ways: autoloaded from $fpath (file named _omp) or eval'd from a
+# startup file. When autoloaded, funcstack[1] is _omp and we invoke it; when
 # sourced/eval'd we register it with compdef instead.
-if [ "$funcstack[1]" = "_prometheus" ]; then
-	_prometheus "$@"
+if [ "$funcstack[1]" = "_omp" ]; then
+	_omp "$@"
 else
-	compdef _prometheus ${bin}
+	compdef _omp ${bin}
 fi`);
 	parts.push("");
 	return `${parts.join("\n")}\n`;
@@ -498,7 +498,7 @@ function generateFish(spec: CompletionSpec): string {
 	lines.push("");
 
 	const allTokens = spec.commands.flatMap(commandTokens);
-	lines.push(`function __fish_prometheus_no_subcommand`);
+	lines.push(`function __fish_omp_no_subcommand`);
 	lines.push(`\tfor i in (commandline -opc)`);
 	lines.push(`\t\tif contains -- $i ${allTokens.join(" ")}`);
 	lines.push(`\t\t\treturn 1`);
@@ -508,7 +508,7 @@ function generateFish(spec: CompletionSpec): string {
 	lines.push(`end`);
 	lines.push("");
 
-	const rootCond = "__fish_prometheus_no_subcommand";
+	const rootCond = "__fish_omp_no_subcommand";
 
 	// Subcommand names.
 	for (const c of spec.commands) {

package/src/cli/dry-balance-cli.ts

@@ -1,8 +1,10 @@
 import type {
 	Api,
+	ApiKeyResolver,
 	AssistantMessage,
 	AssistantMessageEvent,
 	AssistantMessageEventStream,
+	AuthCredentialSnapshotEntry,
 	Context,
 	Model,
 	OAuthAccess,
@@ -10,14 +12,14 @@ import type {
 	SimpleStreamOptions,
 } from "@prometheus-ai/ai";
 import { streamSimple } from "@prometheus-ai/ai";
+import type { CanonicalModelVariant } from "@prometheus-ai/catalog/identity";
 import { replaceTabs, truncateToWidth } from "@prometheus-ai/tui";
 import { formatDuration, getProjectDir } from "@prometheus-ai/utils";
 import chalk from "chalk";
-import type { CanonicalModelVariant } from "../config/model-equivalence";
 import { type CanonicalModelQueryOptions, ModelRegistry } from "../config/model-registry";
 import {
 	formatModelString,
-	type ModelMatchPreferences,
+	getModelMatchPreferences,
 	resolveAllowedModels,
 	resolveCliModel,
 	resolveModelRoleValue,
@@ -59,6 +61,12 @@ export interface DryBalanceAuthStorage {
 		options?: DryBalanceAuthOptions,
 	): Promise<OAuthAccess | undefined>;
 	getOAuthAccesses?(provider: string, options?: DryBalanceAuthOptions): Promise<OAuthAccessResolution[]>;
+	/**
+	 * Force-refresh a single credential by id (step (b) of the auth-retry
+	 * policy). The bench re-mints the failing account's token in place on a
+	 * 401 rather than rotating accounts — it is measuring each account.
+	 */
+	forceRefreshCredentialById?(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
 }
 
 export interface DryBalanceModelRegistry {
@@ -152,6 +160,8 @@ export interface DryBalanceDependencies {
 	now?: () => number;
 	stdoutIsTTY?: boolean;
 	stderrIsTTY?: boolean;
+	stdoutColumns?: number;
+	stderrColumns?: number;
 }
 
 type DryBalanceAttemptResult =
@@ -181,6 +191,7 @@ type DryBalanceBenchTarget =
 			ok: true;
 			account: string;
 			accessToken: string;
+			credentialId?: number;
 	  }
 	| {
 			ok: false;
@@ -268,7 +279,7 @@ function isBenchFirstTokenEvent(event: AssistantMessageEvent): boolean {
 }
 
 function resolveBenchMaxTokens(model: Model<Api>): number {
-	return Number.isFinite(model.maxTokens) && model.maxTokens > 0
+	return model.maxTokens !== null && Number.isFinite(model.maxTokens) && model.maxTokens > 0
 		? Math.min(BENCH_MAX_TOKENS, model.maxTokens)
 		: BENCH_MAX_TOKENS;
 }
@@ -310,10 +321,11 @@ function renderBenchStatusLine(
 	}
 }
 
-function createBenchProgressSink(
+export function createBenchProgressSink(
 	total: number,
 	write: (text: string) => void,
 	interactive: boolean,
+	columns: number,
 ): DryBalanceBenchProgressSink {
 	const statuses: DryBalanceBenchProgressStatus[] = Array.from({ length: total }, () => ({ state: "waiting" }));
 	if (!interactive) {
@@ -333,13 +345,21 @@ function createBenchProgressSink(
 	let frame = 0;
 	let lineCount = 0;
 	let timer: NodeJS.Timeout | undefined;
+	const width = Number.isFinite(columns) && columns > 0 ? Math.trunc(columns) : 80;
 	const render = (): void => {
 		const lines = [
 			chalk.bold("bench requests"),
 			...statuses.map((status, index) => renderBenchStatusLine(status, index, total, frame)),
 		];
-		if (lineCount > 0) write(`\x1b[${lineCount}A`);
-		write(`${lines.map(line => `\x1b[2K${line}`).join("\n")}\n`);
+		// Anchor every redraw at column 0 and terminate each row with CRLF: a
+		// bare `\n` only returns to column 0 when the tty performs ONLCR
+		// translation, which is off whenever the terminal is in raw mode — there
+		// the old column-preserving cursor-up staircased each frame into
+		// scrollback. Cap each line to the terminal width so a wrapped row never
+		// desyncs the `\x1b[<n>A` cursor-up from the logical line count.
+		const move = lineCount > 0 ? `\x1b[${lineCount}A` : "";
+		const body = lines.map(line => `\x1b[2K${truncateToWidth(line, width)}`).join("\r\n");
+		write(`${move}\r${body}\r\n`);
 		lineCount = lines.length;
 	};
 	render();
@@ -370,13 +390,23 @@ function createBenchProgressSink(
 async function runBenchRequest(
 	model: Model<Api>,
 	sessionId: string,
-	account: string,
-	accessToken: string,
+	target: Extract<DryBalanceBenchTarget, { ok: true }>,
+	authStorage: DryBalanceAuthStorage,
 	streamFn: DryBalanceStreamSimple,
 	now: () => number,
 ): Promise<DryBalanceBenchResult> {
+	const { account, accessToken, credentialId } = target;
 	const startedAt = now();
 	let firstTokenAt: number | undefined;
+	// Re-mint the cached token on a 401: a peer/broker may have rotated it out
+	// from under our snapshot (Anthropic rotates refresh tokens on every use).
+	// The bench measures one account, so the switch step intentionally declines.
+	const apiKey: ApiKeyResolver = async ({ lastChance, error }) => {
+		if (error === undefined) return accessToken;
+		if (lastChance || credentialId === undefined || !authStorage.forceRefreshCredentialById) return undefined;
+		const refreshed = await authStorage.forceRefreshCredentialById(credentialId);
+		return refreshed.credential.type === "oauth" ? refreshed.credential.access : undefined;
+	};
 	try {
 		const context: Context = {
 			messages: [
@@ -389,7 +419,7 @@ async function runBenchRequest(
 			],
 		};
 		const stream = streamFn(model, context, {
-			apiKey: accessToken,
+			apiKey,
 			sessionId,
 			maxTokens: resolveBenchMaxTokens(model),
 			temperature: 0.2,
@@ -454,7 +484,7 @@ async function resolveBenchTargets(
 		seen.add(key);
 		const account = extractAccount(entry);
 		if (entry.ok) {
-			targets.push({ ok: true, account, accessToken: entry.accessToken });
+			targets.push({ ok: true, account, accessToken: entry.accessToken, credentialId: entry.credentialId });
 		} else {
 			targets.push({ ok: false, account, error: entry.error });
 		}
@@ -465,6 +495,7 @@ async function resolveBenchTargets(
 async function runBenchTargets(
 	model: Model<Api>,
 	targets: DryBalanceBenchTarget[],
+	authStorage: DryBalanceAuthStorage,
 	randomSessionId: () => string,
 	progress: DryBalanceBenchProgressSink | undefined,
 	streamFn: DryBalanceStreamSimple,
@@ -482,14 +513,7 @@ async function runBenchTargets(
 				return result;
 			}
 			progress?.markRunning(index, target.account);
-			const result = await runBenchRequest(
-				model,
-				randomSessionId(),
-				target.account,
-				target.accessToken,
-				streamFn,
-				now,
-			);
+			const result = await runBenchRequest(model, randomSessionId(), target, authStorage, streamFn, now);
 			progress?.complete(index, result);
 			return result;
 		}),
@@ -518,9 +542,7 @@ async function resolveDryBalanceModel(
 	settings: Settings | undefined,
 	randomSessionId: () => string,
 ): Promise<{ model: Model<Api>; warning?: string }> {
-	const preferences: ModelMatchPreferences = {
-		usageOrder: settings?.getStorage()?.getModelUsageOrder(),
-	};
+	const preferences = getModelMatchPreferences(settings);
 	if (modelSelector) {
 		const resolved = resolveCliModel({
 			cliModel: modelSelector,
@@ -792,8 +814,19 @@ export async function runDryBalanceCommand(
 			const progressInteractive = command.flags.json
 				? (deps.stderrIsTTY ?? process.stderr.isTTY === true)
 				: (deps.stdoutIsTTY ?? process.stdout.isTTY === true);
-			progress = createBenchProgressSink(targets.length, progressWrite, progressInteractive);
-			benchResults = await runBenchTargets(model, targets, randomSessionId, progress, streamFn, now);
+			const progressColumns = command.flags.json
+				? (deps.stderrColumns ?? process.stderr.columns ?? 80)
+				: (deps.stdoutColumns ?? process.stdout.columns ?? 80);
+			progress = createBenchProgressSink(targets.length, progressWrite, progressInteractive, progressColumns);
+			benchResults = await runBenchTargets(
+				model,
+				targets,
+				runtime.modelRegistry.authStorage,
+				randomSessionId,
+				progress,
+				streamFn,
+				now,
+			);
 			results = targets.map(target =>
 				target.ok ? { ok: true, account: target.account } : { ok: false, reason: target.error },
 			);

package/src/cli/gallery-cli.ts

@@ -0,0 +1,231 @@
+/**
+ * `prometheus gallery` — render every built-in tool's renderer across its lifecycle.
+ *
+ * For each tool with a registered renderer, the gallery drives a real
+ * {@link ToolExecutionComponent} through four states — streaming arguments,
+ * arguments complete (in progress), success, and failure — and prints the
+ * rendered output to stdout. It exists for visual QA of tool renderers without
+ * having to provoke each state through a live agent session.
+ */
+import type { AgentTool } from "@prometheus-ai/agent-core";
+import type { TUI } from "@prometheus-ai/tui";
+import { getProjectDir } from "@prometheus-ai/utils";
+import { Settings } from "../config/settings";
+import { ToolExecutionComponent } from "../modes/components/tool-execution";
+import { initTheme, theme } from "../modes/theme/theme";
+import { toolRenderers } from "../tools/renderers";
+import { type GalleryFixture, type GalleryResult, galleryFixtures } from "./gallery-fixtures";
+import { captureGalleryScreenshots } from "./gallery-screenshot";
+
+/** Lifecycle states the gallery renders, in display order. */
+export const GALLERY_STATES = ["streaming", "progress", "success", "error"] as const;
+export type GalleryState = (typeof GALLERY_STATES)[number];
+
+const STATE_LABELS: Record<GalleryState, string> = {
+	streaming: "streaming args",
+	progress: "in progress",
+	success: "done",
+	error: "failed",
+};
+
+export interface GalleryCommandArgs {
+	/** Render width in columns (defaults to terminal width, clamped). */
+	width?: number;
+	/** Restrict to a single tool name. */
+	tool?: string;
+	/** Restrict to specific lifecycle states. */
+	states?: GalleryState[];
+	/** Render the expanded variant of each renderer. */
+	expanded?: boolean;
+	/** Strip ANSI styling from the output (useful when redirecting to a file). */
+	plain?: boolean;
+	/** Capture the rendered gallery as PNG screenshot(s) via VHS instead of printing ANSI. */
+	screenshot?: boolean;
+	/** Screenshot output path (single image) or base path (suffixed when split across images). */
+	out?: string;
+	/** Font family for screenshots (must be installed; Nerd Font recommended for icon glyphs). */
+	font?: string;
+	/** Font size in points for screenshots. */
+	fontSize?: number;
+}
+
+/** One tool's rendered lifecycle, as ANSI lines: a leading blank, the section rule, then each state. */
+export interface GallerySection {
+	heading: string;
+	lines: string[];
+}
+
+const GENERIC_ERROR: GalleryResult = {
+	content: [{ type: "text", text: "Error: operation failed" }],
+	isError: true,
+};
+
+/**
+ * Build the fake `AgentTool` the component needs for its label, edit mode, and —
+ * for `customRendered` fixtures — the renderer functions that route it through
+ * the same custom-tool branch production uses (see {@link GalleryFixture}).
+ */
+function fakeToolFor(name: string, fixture: GalleryFixture | undefined): AgentTool | undefined {
+	if (!fixture?.label && !fixture?.editMode && !fixture?.customRendered) return undefined;
+	const tool: Record<string, unknown> = { name, label: fixture.label ?? name, mode: fixture.editMode };
+	if (fixture.customRendered) {
+		const renderer = toolRenderers[fixture.renderer ?? name] as
+			| { renderCall?: unknown; renderResult?: unknown; mergeCallAndResult?: unknown; inline?: unknown }
+			| undefined;
+		if (renderer) {
+			tool.renderCall = renderer.renderCall;
+			tool.renderResult = renderer.renderResult;
+			tool.mergeCallAndResult = renderer.mergeCallAndResult;
+			tool.inline = renderer.inline;
+		}
+	}
+	return tool as unknown as AgentTool;
+}
+
+/** The curated fixture for a tool, or a generic one for registry tools lacking sample data. */
+export function resolveFixture(name: string): GalleryFixture {
+	return (
+		galleryFixtures[name] ??
+		({
+			args: { note: `sample ${name} call` },
+			result: { content: [{ type: "text", text: `${name} completed` }] },
+		} satisfies GalleryFixture)
+	);
+}
+
+/**
+ * Render a single tool/state pair to lines. Builds a fresh component, drives it
+ * to the requested state, settles any async edit preview, then snapshots the
+ * render and stops all animation timers.
+ */
+export async function renderGalleryState(
+	name: string,
+	fixture: GalleryFixture,
+	state: GalleryState,
+	width: number,
+	expanded = false,
+): Promise<readonly string[]> {
+	if (fixture.renderState) {
+		return await fixture.renderState(state, width, expanded);
+	}
+
+	const tool = fakeToolFor(name, fixture);
+	const streamingArgs = state === "streaming" ? (fixture.streamingArgs ?? fixture.args) : fixture.args;
+	// The component only calls `requestRender`/`requestComponentRender` (via
+	// its loader) during a static render; `imageBudget` is consulted solely
+	// when images render, which the gallery disables. A cast avoids
+	// constructing a real terminal.
+	const ui = { requestRender() {}, requestComponentRender() {} } as unknown as TUI;
+	const component = new ToolExecutionComponent(name, streamingArgs, { showImages: false }, tool, ui, getProjectDir());
+	component.setExpanded(expanded);
+
+	if (state !== "streaming") {
+		component.setArgsComplete();
+	}
+	if (state === "success") {
+		component.updateResult(fixture.result, false);
+	} else if (state === "error") {
+		component.updateResult(fixture.errorResult ?? GENERIC_ERROR, false);
+	}
+
+	// Edit-like renderers compute their diff preview off the render path; wait
+	// for it to settle so the snapshot is deterministic instead of racing a tick.
+	await component.whenPreviewSettled();
+
+	const lines = component.render(width);
+	component.stopAnimation();
+	return lines;
+}
+
+function resolveWidth(requested: number | undefined): number {
+	const fallback = process.stdout.columns ?? 100;
+	const width = requested ?? fallback;
+	return Math.max(40, Math.min(200, width));
+}
+
+function sectionRule(label: string, width: number): string {
+	const prefix = `── ${label} `;
+	const fill = Math.max(0, width - prefix.length);
+	return theme.fg("accent", theme.bold(`${prefix}${"─".repeat(fill)}`));
+}
+
+/**
+ * Render each requested tool's lifecycle into ANSI section blocks. The block
+ * layout (leading blank, section rule, then a blank + dim label + body per
+ * state) is shared by the stdout and screenshot paths so both stay identical.
+ */
+async function renderGallerySections(
+	names: string[],
+	states: GalleryState[],
+	width: number,
+	expanded: boolean,
+): Promise<GallerySection[]> {
+	const sections: GallerySection[] = [];
+	for (const name of names) {
+		const fixture = resolveFixture(name);
+		const heading = fixture.label && fixture.label !== name ? `${name} — ${fixture.label}` : name;
+		const lines: string[] = ["", sectionRule(heading, width)];
+		for (const state of states) {
+			lines.push("", theme.fg("dim", `  · ${STATE_LABELS[state]}`));
+			try {
+				for (const line of await renderGalleryState(name, fixture, state, width, expanded)) lines.push(line);
+			} catch (err) {
+				lines.push(theme.fg("error", `  render failed: ${String(err)}`));
+			}
+		}
+		sections.push({ heading, lines });
+	}
+	return sections;
+}
+
+/**
+ * Render the gallery. Iterates the renderer registry (or a single tool),
+ * printing each requested lifecycle state under a labeled section — or, with
+ * `screenshot`, capturing the rendered output as PNG(s) via VHS.
+ */
+export async function runGalleryCommand(args: GalleryCommandArgs): Promise<void> {
+	const settingsInstance = await Settings.init();
+	// Screenshots must carry exact theme RGB regardless of how the invoking
+	// terminal advertises its color support, so force truecolor before the theme
+	// (and therefore every SGR escape it emits) is built.
+	if (args.screenshot) process.env.COLORTERM = "truecolor";
+	await initTheme(
+		false,
+		settingsInstance.get("symbolPreset"),
+		settingsInstance.get("colorBlindMode"),
+		settingsInstance.get("theme.dark"),
+		settingsInstance.get("theme.light"),
+	);
+
+	const width = resolveWidth(args.width);
+	const expanded = args.expanded ?? false;
+	const states = args.states && args.states.length > 0 ? args.states : [...GALLERY_STATES];
+
+	// Renderer-registry tools plus fixture-only tools (no dedicated renderer,
+	// e.g. `report_tool_issue` / custom extension tools) so the gallery covers
+	// the generic fallback + custom-tool branches too.
+	const allNames = Array.from(new Set([...Object.keys(toolRenderers), ...Object.keys(galleryFixtures)])).sort();
+	const names = args.tool ? allNames.filter(name => name === args.tool) : allNames;
+	if (args.tool && names.length === 0) {
+		process.stdout.write(`Unknown tool '${args.tool}'. Known tools: ${allNames.join(", ")}\n`);
+		return;
+	}
+
+	const sections = await renderGallerySections(names, states, width, expanded);
+
+	if (args.screenshot) {
+		const paths = await captureGalleryScreenshots(sections, {
+			width,
+			font: args.font,
+			fontSize: args.fontSize,
+			out: args.out,
+		});
+		process.stdout.write(`${paths.join("\n")}\n`);
+		return;
+	}
+
+	const lines = sections.flatMap(section => section.lines);
+	lines.push("");
+	const text = lines.map(line => (args.plain ? Bun.stripANSI(line) : line)).join("\n");
+	process.stdout.write(`${text}\n`);
+}