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

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/config/keybindings.ts

@@ -21,6 +21,7 @@ interface AppKeybindings {
 	"app.clear": true;
 	"app.exit": true;
 	"app.suspend": true;
+	"app.display.reset": true;
 	"app.thinking.cycle": true;
 	"app.thinking.toggle": true;
 	"app.model.cycleForward": true;
@@ -86,6 +87,10 @@ export const KEYBINDINGS = {
 		defaultKeys: "ctrl+z",
 		description: "Suspend application",
 	},
+	"app.display.reset": {
+		defaultKeys: "ctrl+l",
+		description: "Reset terminal display",
+	},
 	"app.thinking.cycle": {
 		defaultKeys: "shift+tab",
 		description: "Cycle thinking level",
@@ -103,7 +108,7 @@ export const KEYBINDINGS = {
 		description: "Cycle to previous model",
 	},
 	"app.model.select": {
-		defaultKeys: "ctrl+l",
+		defaultKeys: "alt+m",
 		description: "Select model",
 	},
 	"app.model.selectTemporary": {
@@ -216,6 +221,7 @@ const KEYBINDING_NAME_MIGRATIONS = {
 	clear: "app.clear",
 	exit: "app.exit",
 	suspend: "app.suspend",
+	displayReset: "app.display.reset",
 	cycleThinkingLevel: "app.thinking.cycle",
 	cycleModelForward: "app.model.cycleForward",
 	cycleModelBackward: "app.model.cycleBackward",
@@ -444,7 +450,6 @@ function migrateKeybindingsConfigFile(agentDir: string): void {
 
 const FOLLOW_UP_KEYBINDING: AppKeybinding = "app.message.followUp";
 const WINDOWS_FOLLOW_UP_FALLBACK_KEY: KeyId = "ctrl+q";
-
 function keyListIncludes(keys: KeyId | KeyId[] | undefined, target: KeyId): boolean {
 	if (keys === undefined) return false;
 	const keyList = Array.isArray(keys) ? keys : [keys];
@@ -525,10 +530,14 @@ export class KeybindingsManager extends TuiKeybindingsManager {
 
 	getKeys(keybinding: Keybinding): KeyId[] {
 		const keys = super.getKeys(keybinding);
-		if (keybinding !== FOLLOW_UP_KEYBINDING) return keys;
-		if (this.#userBindings[FOLLOW_UP_KEYBINDING] !== undefined) return keys;
-		if (!userBindingClaimsKey(this.#userBindings, WINDOWS_FOLLOW_UP_FALLBACK_KEY, FOLLOW_UP_KEYBINDING)) return keys;
-		return removeKey(keys, WINDOWS_FOLLOW_UP_FALLBACK_KEY);
+		if (keybinding === FOLLOW_UP_KEYBINDING) {
+			if (this.#userBindings[FOLLOW_UP_KEYBINDING] !== undefined) return keys;
+			if (!userBindingClaimsKey(this.#userBindings, WINDOWS_FOLLOW_UP_FALLBACK_KEY, FOLLOW_UP_KEYBINDING)) {
+				return keys;
+			}
+			return removeKey(keys, WINDOWS_FOLLOW_UP_FALLBACK_KEY);
+		}
+		return keys;
 	}
 
 	getResolvedBindings(): KeybindingsConfig {

package/src/config/model-equivalence.ts

@@ -58,7 +58,7 @@ const EMPTY_COMPILED_EQUIVALENCE: CompiledEquivalenceConfig = {
 };
 const kModelResolutionCache = Symbol("model-equivalence.resolutionCache");
 interface CompiledEquivalenceConfigWithCache extends CompiledEquivalenceConfig {
-	[kModelResolutionCache]?: WeakMap<Model<Api>, ResolvedCanonicalModel>;
+	[kModelResolutionCache]?: Map<string, ResolvedCanonicalModel>;
 }
 const FAMILY_EXTRACTION_PATTERNS = [
 	/(?:^|[/:._-])((?:claude|gemini|gpt|grok|glm|qwen|minimax|kimi|deepseek|llama|gemma|nova|mistral|ministral|pixtral|codestral|devstral|magistral|ernie|doubao|seed|aion|olmo|molmo|nemotron|palmyra|command|codex|coder|o[1345])[-a-z0-9.]+)(?::|$)/i,
@@ -128,10 +128,18 @@ function normalizeCanonicalIdKey(canonicalId: string): string {
 	return canonicalId.trim().toLowerCase();
 }
 
+function getCanonicalSuffixAliasKey(candidate: string): string {
+	return PENALTY_HAS_UPPERCASE.test(candidate) ? normalizeCanonicalIdKey(candidate) : candidate;
+}
+
 export function formatCanonicalVariantSelector(model: Model<Api>): string {
 	return `${model.provider}/${model.id}`;
 }
 
+function getModelResolutionCacheKey(model: Model<Api>): string {
+	return `${model.provider}\0${model.id}`;
+}
+
 function buildOverrideMap(overrides: Record<string, string> | undefined): Map<string, string> {
 	const result = new Map<string, string>();
 	if (!overrides) {
@@ -159,13 +167,24 @@ function buildExclusionSet(exclusions: readonly string[] | undefined): Set<strin
 	return result;
 }
 
+const compiledEquivalenceCache = new WeakMap<ModelEquivalenceConfig, CompiledEquivalenceConfig>();
 function compileEquivalenceConfig(config: ModelEquivalenceConfig | undefined): CompiledEquivalenceConfig {
+	if (config) {
+		const cached = compiledEquivalenceCache.get(config);
+		if (cached) {
+			return cached;
+		}
+	}
 	const overrides = buildOverrideMap(config?.overrides);
 	const exclude = buildExclusionSet(config?.exclude);
 	if (overrides.size === 0 && exclude.size === 0) {
 		return EMPTY_COMPILED_EQUIVALENCE;
 	}
-	return { overrides, exclude };
+	const compiled: CompiledEquivalenceConfig = { overrides, exclude };
+	if (config) {
+		compiledEquivalenceCache.set(config, compiled);
+	}
+	return compiled;
 }
 
 function addCanonicalCandidate(candidates: Set<string>, candidate: string): void {
@@ -277,7 +296,7 @@ function expandCompactSeriesMinorVersions(candidate: string): string[] {
 // safely return the same instance. Cap keeps memory bounded under adversarial
 // model-id churn.
 const QUALIFIED_NAMESPACE_SUFFIX_CACHE = new Map<string, string[]>();
-const QUALIFIED_NAMESPACE_SUFFIX_CACHE_CAP = 256;
+const QUALIFIED_NAMESPACE_SUFFIX_CACHE_CAP = 4096;
 function getQualifiedNamespaceSuffixes(candidate: string): string[] {
 	const cached = QUALIFIED_NAMESPACE_SUFFIX_CACHE.get(candidate);
 	if (cached !== undefined) {
@@ -670,7 +689,7 @@ function expandHeavyCanonicalCandidates(normalized: string, queue: string[]): vo
 // is unused — kept for signature stability). The returned array is consumed via
 // `.filter` at every callsite, so sharing the cached instance is safe.
 const HEURISTIC_CANDIDATES_CACHE = new Map<string, string[]>();
-const HEURISTIC_CANDIDATES_CACHE_CAP = 256;
+const HEURISTIC_CANDIDATES_CACHE_CAP = 4096;
 function getHeuristicCanonicalCandidates(modelId: string, _officialIds?: ReadonlySet<string>): string[] {
 	const cached = HEURISTIC_CANDIDATES_CACHE.get(modelId);
 	if (cached !== undefined) {
@@ -728,10 +747,10 @@ function getPreferredFallbackCanonicalCandidate(modelId: string, candidates: rea
 
 function resolveCanonicalIdForModel(
 	model: Model<Api>,
+	selector: string,
 	equivalence: CompiledEquivalenceConfig,
 	referenceData: CanonicalReferenceData,
 ): ResolvedCanonicalModel {
-	const selector = formatCanonicalVariantSelector(model);
 	const normalizedSelector = normalizeSelectorKey(selector);
 
 	if (equivalence.overrides.has(normalizedSelector)) {
@@ -753,9 +772,12 @@ function resolveCanonicalIdForModel(
 	}
 
 	const heuristicCandidates = getHeuristicCanonicalCandidates(model.id, referenceData.officialIds);
-	const officialMatches = new Set(heuristicCandidates.filter(candidate => referenceData.officialIds.has(candidate)));
+	const officialMatches = new Set<string>();
 	for (const candidate of heuristicCandidates) {
-		const aliased = referenceData.suffixAliases.get(normalizeCanonicalIdKey(candidate));
+		if (referenceData.officialIds.has(candidate)) {
+			officialMatches.add(candidate);
+		}
+		const aliased = referenceData.suffixAliases.get(getCanonicalSuffixAliasKey(candidate));
 		if (aliased) {
 			officialMatches.add(aliased);
 		}
@@ -814,17 +836,18 @@ export function buildCanonicalModelIndex(
 	const compiledWithCache = compiledEquivalence as CompiledEquivalenceConfigWithCache;
 	let modelCache = compiledWithCache[kModelResolutionCache];
 	if (!modelCache) {
-		modelCache = new WeakMap<Model<Api>, ResolvedCanonicalModel>();
+		modelCache = new Map<string, ResolvedCanonicalModel>();
 		compiledWithCache[kModelResolutionCache] = modelCache;
 	}
 
 	for (const model of models) {
-		let canonical = modelCache.get(model);
+		const selector = formatCanonicalVariantSelector(model);
+		const cacheKey = getModelResolutionCacheKey(model);
+		let canonical = modelCache.get(cacheKey);
 		if (!canonical) {
-			canonical = resolveCanonicalIdForModel(model, compiledEquivalence, referenceData);
-			modelCache.set(model, canonical);
+			canonical = resolveCanonicalIdForModel(model, selector, compiledEquivalence, referenceData);
+			modelCache.set(cacheKey, canonical);
 		}
-		const selector = formatCanonicalVariantSelector(model);
 		const variant: CanonicalModelVariant = {
 			canonicalId: canonical.id,
 			selector,

package/src/config/model-id-affixes.ts

@@ -4,34 +4,49 @@ const MODEL_ID_SEGMENT_PATTERN = /[a-z0-9.:-]+/g;
 const MODEL_FAMILY_PREFIX_PATTERN =
 	/^(claude|gemini|gpt|grok|glm|qwen|deepseek|kimi|mimo|doubao|ernie|gpt-oss|gemma|minimax|step|command|jamba|llama|o[1345])/i;
 
-function hasDigit(value: string): boolean {
-	return /\d/.test(value);
+function normalizeModelIdWhitespace(value: string): string {
+	return value.trim().replace(/\s+/g, " ");
 }
 
+/** Ordering for model-like segments: longest first, ties broken lexicographically. */
 function compareSegmentPreference(left: string, right: string): number {
-	if (left.length !== right.length) {
-		return right.length - left.length;
-	}
-	return left.localeCompare(right);
+	return left.length !== right.length ? right.length - left.length : left.localeCompare(right);
 }
 
 export function getModelLikeIdSegments(modelId: string): string[] {
-	const normalized = normalizeModelIdWhitespace(modelId).toLowerCase();
-	if (!normalized) return [];
-	const segments = (normalized.match(MODEL_ID_SEGMENT_PATTERN) ?? []).filter(
-		segment => MODEL_FAMILY_PREFIX_PATTERN.test(segment) && hasDigit(segment),
-	);
-	const unique = [...new Set(segments)];
-	unique.sort(compareSegmentPreference);
-	return unique;
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return [];
+	const segments = new Set<string>();
+	for (const segment of matches) {
+		if (MODEL_FAMILY_PREFIX_PATTERN.test(segment) && /\d/.test(segment)) segments.add(segment);
+	}
+	return [...segments].sort(compareSegmentPreference);
 }
 
 export function getLongestModelLikeIdSegment(modelId: string): string | undefined {
-	return getModelLikeIdSegments(modelId)[0];
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return undefined;
+	let best: string | undefined;
+	for (const segment of matches) {
+		if (
+			MODEL_FAMILY_PREFIX_PATTERN.test(segment) &&
+			/\d/.test(segment) &&
+			(best === undefined || compareSegmentPreference(segment, best) < 0)
+		) {
+			best = segment;
+		}
+	}
+	return best;
 }
 
-function normalizeModelIdWhitespace(value: string): string {
-	return value.trim().replace(/\s+/g, " ");
+function hasBracketAffixMarker(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code === 91 || code === 93 || code === 0x3010 || code === 0x3011) {
+			return true;
+		}
+	}
+	return false;
 }
 
 /**
@@ -39,18 +54,20 @@ function normalizeModelIdWhitespace(value: string): string {
  * upstream model id, e.g.
  *   "[Kiro] claude-opus-4-8"                -> "claude-opus-4-8"
  *   "[gcli转] gemini-3.1-pro-preview [假流]" -> "gemini-3.1-pro-preview"
+ *
+ * Candidates are returned most-stripped first: both ends, then leading-only, then trailing-only.
  */
 export function getBracketStrippedModelIdCandidates(modelId: string): string[] {
+	if (!hasBracketAffixMarker(modelId)) return [];
 	const normalized = normalizeModelIdWhitespace(modelId);
 	if (!normalized) return [];
 
-	const candidates = new Set<string>();
-	const withoutLeading = normalizeModelIdWhitespace(normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, ""));
+	const strippedLeading = normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, "");
+	const withoutLeading = normalizeModelIdWhitespace(strippedLeading);
 	const withoutTrailing = normalizeModelIdWhitespace(normalized.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
-	const withoutBoth = normalizeModelIdWhitespace(
-		normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, "").replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""),
-	);
+	const withoutBoth = normalizeModelIdWhitespace(strippedLeading.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
 
+	const candidates = new Set<string>();
 	for (const candidate of [withoutBoth, withoutLeading, withoutTrailing]) {
 		if (candidate && candidate !== normalized) {
 			candidates.add(candidate);

package/src/config/model-registry.ts

@@ -1,27 +1,19 @@
 import * as path from "node:path";
+import { registerCustomApi, unregisterCustomApis } from "@oh-my-pi/pi-ai/api-registry";
+import { readModelCache } from "@oh-my-pi/pi-ai/model-cache";
+import { createModelManager, type ModelManagerOptions, type ModelRefreshStrategy } from "@oh-my-pi/pi-ai/model-manager";
+import { enrichModelThinking } from "@oh-my-pi/pi-ai/model-thinking";
+import { getBundledModels, getBundledProviders } from "@oh-my-pi/pi-ai/models";
 import {
-	type Api,
-	type AssistantMessageEventStream,
-	type Context,
-	createModelManager,
-	enrichModelThinking,
-	getBundledModels,
-	getBundledProviders,
 	googleAntigravityModelManagerOptions,
 	googleGeminiCliModelManagerOptions,
-	type Model,
-	type ModelManagerOptions,
-	type ModelRefreshStrategy,
 	openaiCodexModelManagerOptions,
 	PROVIDER_DESCRIPTORS,
-	readModelCache,
-	registerCustomApi,
-	type SimpleStreamOptions,
-	type ThinkingConfig,
 	UNK_CONTEXT_WINDOW,
 	UNK_MAX_TOKENS,
-	unregisterCustomApis,
-} from "@oh-my-pi/pi-ai";
+} from "@oh-my-pi/pi-ai/provider-models";
+import type { Api, Context, Model, SimpleStreamOptions, ThinkingConfig } from "@oh-my-pi/pi-ai/types";
+import type { AssistantMessageEventStream } from "@oh-my-pi/pi-ai/utils/event-stream";
 
 // Sentinel for local-only OAuth token (LM Studio, vLLM) — declared inline to avoid loading
 // any provider module at startup. Must match `DEFAULT_LOCAL_TOKEN` in oauth/lm-studio.ts.
@@ -2609,6 +2601,14 @@ export class ModelRegistry {
 		}
 		return true;
 	}
+
+	/**
+	 * Clear all cooldown suppressions recorded via {@link suppressSelector}.
+	 * Used to reset retry-fallback cooldown state without a full {@link refresh}.
+	 */
+	clearSuppressedSelectors(): void {
+		this.#suppressedSelectors.clear();
+	}
 }
 
 /**