@selesai/code 0.1.4 → 0.1.6

package/dist/extensions/pi-subagents/src/runs/shared/long-running-guard.ts

@@ -0,0 +1,175 @@
+import type { ResolvedControlConfig } from "../../shared/types.ts";
+
+interface LongRunningNoticeMetrics {
+	startedAt: number;
+	now: number;
+	turns: number;
+	tokens: number;
+}
+
+type LongRunningTriggerReason = "time_threshold" | "turn_threshold" | "token_threshold";
+
+interface FailedMutatingAttempt {
+	tool: string;
+	path?: string;
+	error: string;
+	ts: number;
+}
+
+interface MutatingFailureState {
+	consecutiveFailures: number;
+	lastFailureAt?: number;
+	recentFailures: FailedMutatingAttempt[];
+	lastMutatingPath?: string;
+	repeatedPathFailures: number;
+}
+
+const MUTATING_BASH_PATTERNS = [
+	/(^|[;&|()\s])rm\s+/,
+	/(^|[;&|()\s])mv\s+/,
+	/(^|[;&|()\s])cp\s+/,
+	/(^|[;&|()\s])mkdir\s+/,
+	/(^|[;&|()\s])touch\s+/,
+	/(^|[;&|()\s])git\s+apply\b/,
+	/(^|[;&|()\s])patch\s+/,
+	/(^|[;&|()\s])sed\s+[^\n;&|]*\s-i\b/,
+	/(^|[;&|()\s])perl\s+[^\n;&|]*\s-pi\b/,
+	/(^|[;&|()]|\n)\s*tee\s+[^|&;]+/,
+	/\b(writeFile|writeFileSync|appendFile|appendFileSync)\b/,
+	/\bwrite_text\s*\(/,
+	/\bopen\s*\([^)]*,\s*["'][wa]/,
+];
+
+const MUTATING_FAILURE_HINTS = [
+	"failed",
+	"error",
+	"no exact match",
+	"did not match",
+	"malformed",
+	"rejected",
+	"unable",
+	"cannot",
+	"could not",
+];
+
+export function resolveCurrentPath(toolName: string | undefined, args: Record<string, unknown> | undefined): string | undefined {
+	if (!toolName || !args) return undefined;
+	const direct = ["path", "file", "filename", "target", "cwd"];
+	for (const key of direct) {
+		const value = args[key];
+		if (typeof value === "string" && value.trim()) return value.trim();
+	}
+	if (toolName === "bash") {
+		const command = typeof args.command === "string" ? args.command : undefined;
+		if (!command) return undefined;
+		const redirect = command.match(/(?:>|>>|tee\s+)(\S+)/);
+		if (redirect?.[1]) return redirect[1];
+	}
+	return undefined;
+}
+
+function hasUnquotedFileRedirection(command: string): boolean {
+	let inSingle = false;
+	let inDouble = false;
+	for (let i = 0; i < command.length; i++) {
+		const char = command[i]!;
+		if (char === "'" && !inDouble) {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (char === '"' && !inSingle) {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (inSingle || inDouble) continue;
+		if (char !== ">") continue;
+		if (command[i - 1] === "-") continue;
+		const isDouble = command[i + 1] === ">";
+		let cursor = i + (isDouble ? 2 : 1);
+		while (cursor < command.length && /\s/.test(command[cursor]!)) cursor++;
+		if (cursor >= command.length) continue;
+		const targetStart = command[cursor]!;
+		if (targetStart === "&" || targetStart === "|" || targetStart === ";") continue;
+		if (targetStart === "(" || targetStart === ")") continue;
+		return true;
+	}
+	return false;
+}
+
+export function isMutatingBashCommand(command: string): boolean {
+	return hasUnquotedFileRedirection(command) || MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
+}
+
+export function isMutatingTool(toolName: string | undefined, args: Record<string, unknown> | undefined): boolean {
+	if (!toolName) return false;
+	if (toolName === "edit" || toolName === "write") return true;
+	if (toolName !== "bash") return false;
+	const command = typeof args?.command === "string" ? args.command : "";
+	if (!command.trim()) return false;
+	return isMutatingBashCommand(command);
+}
+
+export function didMutatingToolFail(text: string): boolean {
+	const lowered = text.toLowerCase();
+	return MUTATING_FAILURE_HINTS.some((hint) => lowered.includes(hint));
+}
+
+export function nextLongRunningTrigger(
+	config: ResolvedControlConfig,
+	metrics: LongRunningNoticeMetrics,
+): LongRunningTriggerReason | undefined {
+	if (metrics.now - metrics.startedAt >= config.activeNoticeAfterMs) return "time_threshold";
+	if (config.activeNoticeAfterTurns !== undefined && metrics.turns >= config.activeNoticeAfterTurns) return "turn_threshold";
+	if (config.activeNoticeAfterTokens !== undefined && metrics.tokens >= config.activeNoticeAfterTokens) return "token_threshold";
+	return undefined;
+}
+
+export function resetMutatingFailureState(state: MutatingFailureState): void {
+	state.consecutiveFailures = 0;
+	state.lastFailureAt = undefined;
+	state.recentFailures = [];
+	state.lastMutatingPath = undefined;
+	state.repeatedPathFailures = 0;
+}
+
+export function createMutatingFailureState(): MutatingFailureState {
+	return {
+		consecutiveFailures: 0,
+		recentFailures: [],
+		repeatedPathFailures: 0,
+	};
+}
+
+export function recordMutatingFailure(
+	state: MutatingFailureState,
+	input: FailedMutatingAttempt,
+	windowMs: number,
+): void {
+	if (state.lastFailureAt === undefined || input.ts - state.lastFailureAt > windowMs) {
+		state.consecutiveFailures = 0;
+		state.recentFailures = [];
+		state.repeatedPathFailures = 0;
+		state.lastMutatingPath = undefined;
+	}
+	state.lastFailureAt = input.ts;
+	state.consecutiveFailures += 1;
+	if (input.path && state.lastMutatingPath === input.path) {
+		state.repeatedPathFailures += 1;
+	} else if (input.path) {
+		state.lastMutatingPath = input.path;
+		state.repeatedPathFailures = 1;
+	}
+	state.recentFailures.push(input);
+	if (state.recentFailures.length > 3) state.recentFailures.shift();
+}
+
+export function shouldEscalateMutatingFailures(state: MutatingFailureState, threshold: number): boolean {
+	return state.consecutiveFailures >= threshold || state.repeatedPathFailures >= threshold;
+}
+
+export function summarizeRecentMutatingFailures(state: MutatingFailureState): string | undefined {
+	if (state.recentFailures.length === 0) return undefined;
+	return state.recentFailures
+		.map((entry) => `${entry.tool}${entry.path ? `(${entry.path})` : ""}: ${entry.error}`)
+		.join(" | ");
+}

package/dist/extensions/pi-subagents/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -0,0 +1,365 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir, getProjectConfigDir } from "../../shared/utils.ts";
+
+const CACHE_VERSION = 1;
+const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
+const GENERIC_GLOBAL_CONFIG_PATH = path.join(os.homedir(), ".config", "mcp", "mcp.json");
+const IMPORT_PATHS = {
+	cursor: [path.join(os.homedir(), ".cursor", "mcp.json")],
+	"claude-code": [
+		path.join(os.homedir(), ".claude", "mcp.json"),
+		path.join(os.homedir(), ".claude.json"),
+		path.join(os.homedir(), ".claude", "claude_desktop_config.json"),
+	],
+	"claude-desktop": [path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json")],
+	codex: [path.join(os.homedir(), ".codex", "config.json")],
+	windsurf: [path.join(os.homedir(), ".windsurf", "mcp.json")],
+	vscode: [".vscode/mcp.json"],
+} as const;
+
+type ToolPrefix = "server" | "none" | "short";
+type ImportKind = keyof typeof IMPORT_PATHS;
+
+interface ServerEntry {
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+	url?: string;
+	headers?: Record<string, string>;
+	auth?: "oauth" | "bearer" | false;
+	bearerToken?: string;
+	bearerTokenEnv?: string;
+	exposeResources?: boolean;
+	excludeTools?: string[];
+	directTools?: boolean | string[];
+}
+
+interface McpConfig {
+	mcpServers: Record<string, ServerEntry>;
+	imports?: ImportKind[];
+	settings?: {
+		toolPrefix?: ToolPrefix;
+		directTools?: boolean;
+	};
+}
+
+interface CachedTool {
+	name?: string;
+}
+
+interface CachedResource {
+	uri?: string;
+	name?: string;
+}
+
+interface ServerCacheEntry {
+	configHash?: string;
+	tools?: CachedTool[];
+	resources?: CachedResource[];
+	cachedAt?: number;
+}
+
+interface MetadataCache {
+	version: number;
+	servers: Record<string, ServerCacheEntry>;
+}
+
+export function resolveMcpDirectToolNames(mcpDirectTools: string[] | undefined, cwd = process.cwd()): string[] {
+	if (!mcpDirectTools?.length) return [];
+
+	try {
+		const config = loadMcpConfig(cwd);
+		const cache = loadMetadataCache();
+		if (!cache) return [];
+		return resolveDirectToolNames(config, cache, getToolPrefix(config.settings?.toolPrefix), mcpDirectTools);
+	} catch {
+		return [];
+	}
+}
+
+function loadMetadataCache(): MetadataCache | null {
+	const cachePath = path.join(getAgentDir(), "mcp-cache.json");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+	} catch {
+		return null;
+	}
+
+	if (!parsed || typeof parsed !== "object") return null;
+	const raw = parsed as Record<string, unknown>;
+	if (raw.version !== CACHE_VERSION || !raw.servers || typeof raw.servers !== "object" || Array.isArray(raw.servers)) {
+		return null;
+	}
+	return raw as unknown as MetadataCache;
+}
+
+function loadMcpConfig(cwd: string): McpConfig {
+	let config: McpConfig = { mcpServers: {} };
+	for (const sourcePath of getConfigPaths(cwd)) {
+		const loaded = readConfig(sourcePath);
+		if (!loaded) continue;
+		config = mergeConfigs(config, expandImports(loaded, cwd));
+	}
+	return config;
+}
+
+function getConfigPaths(cwd: string): string[] {
+	const piGlobalPath = path.join(getAgentDir(), "mcp.json");
+	const projectPath = path.resolve(cwd, ".mcp.json");
+	const projectPiPath = path.resolve(getProjectConfigDir(cwd), "mcp.json");
+	const sources: string[] = [];
+	if (GENERIC_GLOBAL_CONFIG_PATH !== piGlobalPath) sources.push(GENERIC_GLOBAL_CONFIG_PATH);
+	sources.push(piGlobalPath);
+	if (projectPath !== piGlobalPath) sources.push(projectPath);
+	if (projectPiPath !== piGlobalPath && projectPiPath !== projectPath) sources.push(projectPiPath);
+	return sources;
+}
+
+function readConfig(configPath: string): McpConfig | null {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+	} catch {
+		return null;
+	}
+	return validateConfig(parsed);
+}
+
+function validateConfig(raw: unknown): McpConfig {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { mcpServers: {} };
+	const obj = raw as Record<string, unknown>;
+	const servers = obj.mcpServers ?? obj["mcp-servers"] ?? {};
+	return {
+		mcpServers: servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {},
+		imports: Array.isArray(obj.imports) ? obj.imports.filter((value): value is ImportKind => isImportKind(value)) : undefined,
+		settings: obj.settings && typeof obj.settings === "object" && !Array.isArray(obj.settings)
+			? obj.settings as McpConfig["settings"]
+			: undefined,
+	};
+}
+
+function mergeConfigs(base: McpConfig, next: McpConfig): McpConfig {
+	const imports = [...(base.imports ?? []), ...(next.imports ?? [])];
+	return {
+		mcpServers: { ...base.mcpServers, ...next.mcpServers },
+		imports: imports.length ? [...new Set(imports)] : undefined,
+		settings: next.settings ? { ...base.settings, ...next.settings } : base.settings,
+	};
+}
+
+function expandImports(config: McpConfig, cwd: string): McpConfig {
+	if (!config.imports?.length) return config;
+
+	const importedServers: Record<string, ServerEntry> = {};
+	for (const importKind of config.imports) {
+		const importPath = resolveImportPath(importKind, cwd);
+		if (!importPath) continue;
+		let imported: unknown;
+		try {
+			imported = JSON.parse(fs.readFileSync(importPath, "utf-8"));
+		} catch {
+			continue;
+		}
+		for (const [name, definition] of Object.entries(extractServers(imported, importKind))) {
+			if (!importedServers[name]) importedServers[name] = definition;
+		}
+	}
+
+	return {
+		imports: config.imports,
+		settings: config.settings,
+		mcpServers: { ...importedServers, ...config.mcpServers },
+	};
+}
+
+function resolveImportPath(importKind: ImportKind, cwd: string): string | null {
+	for (const candidate of IMPORT_PATHS[importKind]) {
+		const fullPath = candidate.startsWith(".") ? path.resolve(cwd, candidate) : candidate;
+		if (fs.existsSync(fullPath)) return fullPath;
+	}
+	return null;
+}
+
+function extractServers(config: unknown, kind: ImportKind): Record<string, ServerEntry> {
+	if (!config || typeof config !== "object" || Array.isArray(config)) return {};
+	const obj = config as Record<string, unknown>;
+	const servers = kind === "cursor" || kind === "windsurf" || kind === "vscode"
+		? obj.mcpServers ?? obj["mcp-servers"]
+		: obj.mcpServers;
+	return servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {};
+}
+
+function resolveDirectToolNames(config: McpConfig, cache: MetadataCache, prefix: ToolPrefix, envOverride: string[]): string[] {
+	const names: string[] = [];
+	const seenNames = new Set<string>();
+	const { servers: selectedServers, tools: selectedTools } = parseSelections(envOverride);
+
+	for (const [serverName, definition] of Object.entries(config.mcpServers)) {
+		const serverCache = cache.servers[serverName];
+		if (!isServerCacheValid(serverCache, definition)) continue;
+
+		const toolFilter = selectedServers.has(serverName)
+			? true
+			: selectedTools.get(serverName);
+		if (!toolFilter) continue;
+
+		for (const tool of Array.isArray(serverCache.tools) ? serverCache.tools : []) {
+			if (typeof tool?.name !== "string" || !tool.name) continue;
+			if (toolFilter !== true && !toolFilter.has(tool.name)) continue;
+			if (isToolExcluded(tool.name, serverName, prefix, definition.excludeTools)) continue;
+			const prefixedName = formatToolName(tool.name, serverName, prefix);
+			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
+			seenNames.add(prefixedName);
+			names.push(prefixedName);
+		}
+
+		if (definition.exposeResources === false) continue;
+		for (const resource of Array.isArray(serverCache.resources) ? serverCache.resources : []) {
+			if (typeof resource?.name !== "string" || !resource.name || typeof resource.uri !== "string" || !resource.uri) continue;
+			const baseName = `get_${resourceNameToToolName(resource.name)}`;
+			if (toolFilter !== true && !toolFilter.has(baseName)) continue;
+			if (isToolExcluded(baseName, serverName, prefix, definition.excludeTools)) continue;
+			const prefixedName = formatToolName(baseName, serverName, prefix);
+			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
+			seenNames.add(prefixedName);
+			names.push(prefixedName);
+		}
+	}
+
+	return names;
+}
+
+function parseSelections(selections: string[]): { servers: Set<string>; tools: Map<string, Set<string>> } {
+	const servers = new Set<string>();
+	const tools = new Map<string, Set<string>>();
+	for (let item of selections) {
+		item = item.replace(/\/+$/, "");
+		if (item.includes("/")) {
+			const [server, tool] = item.split("/", 2);
+			if (server && tool) {
+				if (!tools.has(server)) tools.set(server, new Set());
+				tools.get(server)!.add(tool);
+			} else if (server) {
+				servers.add(server);
+			}
+		} else if (item) {
+			servers.add(item);
+		}
+	}
+	return { servers, tools };
+}
+
+function isServerCacheValid(entry: ServerCacheEntry | undefined, definition: ServerEntry): entry is ServerCacheEntry {
+	if (!entry || entry.configHash !== computeMcpServerHash(definition)) return false;
+	if (!entry.cachedAt || typeof entry.cachedAt !== "number") return false;
+	return Date.now() - entry.cachedAt <= CACHE_MAX_AGE_MS;
+}
+
+export function computeMcpServerHash(definition: ServerEntry): string {
+	const identity: Record<string, unknown> = {
+		command: definition.command,
+		args: definition.args,
+		env: interpolateEnvRecord(definition.env),
+		cwd: resolveConfigPath(definition.cwd),
+		url: definition.url,
+		headers: interpolateEnvRecord(definition.headers),
+		auth: definition.auth,
+		bearerToken: resolveBearerToken(definition),
+		bearerTokenEnv: definition.bearerTokenEnv,
+		exposeResources: definition.exposeResources,
+		excludeTools: definition.excludeTools,
+	};
+	return createHash("sha256").update(stableStringify(identity)).digest("hex");
+}
+
+function getToolPrefix(value: unknown): ToolPrefix {
+	return value === "none" || value === "short" || value === "server" ? value : "server";
+}
+
+function isImportKind(value: unknown): value is ImportKind {
+	return typeof value === "string" && Object.hasOwn(IMPORT_PATHS, value);
+}
+
+function getServerPrefix(serverName: string, mode: ToolPrefix): string {
+	if (mode === "none") return "";
+	if (mode === "short") {
+		const short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+		return short || "mcp";
+	}
+	return serverName.replace(/-/g, "_");
+}
+
+function formatToolName(toolName: string, serverName: string, prefix: ToolPrefix): string {
+	const serverPrefix = getServerPrefix(serverName, prefix);
+	return serverPrefix ? `${serverPrefix}_${toolName}` : toolName;
+}
+
+function isToolExcluded(toolName: string, serverName: string, prefix: ToolPrefix, excludeTools: unknown): boolean {
+	if (!Array.isArray(excludeTools) || excludeTools.length === 0) return false;
+	const candidates = new Set([
+		normalizeToolName(toolName),
+		normalizeToolName(formatToolName(toolName, serverName, prefix)),
+		normalizeToolName(formatToolName(toolName, serverName, "server")),
+		normalizeToolName(formatToolName(toolName, serverName, "short")),
+	]);
+	return excludeTools.some((excluded) => typeof excluded === "string" && candidates.has(normalizeToolName(excluded)));
+}
+
+function normalizeToolName(value: string): string {
+	return value.replace(/-/g, "_");
+}
+
+function resourceNameToToolName(name: string): string {
+	let result = name
+		.replace(/[^a-zA-Z0-9]/g, "_")
+		.replace(/_+/g, "_")
+		.replace(/^_+/, "")
+		.replace(/_+$/, "")
+		.toLowerCase();
+	if (!result || /^\d/.test(result)) result = `resource${result ? `_${result}` : ""}`;
+	return result;
+}
+
+function interpolateEnvRecord(values: Record<string, string> | undefined): Record<string, string> | undefined {
+	if (!values || typeof values !== "object" || Array.isArray(values)) return undefined;
+	const resolved: Record<string, string> = {};
+	for (const [key, value] of Object.entries(values)) {
+		if (typeof value === "string") resolved[key] = interpolateEnvVars(value);
+	}
+	return resolved;
+}
+
+function interpolateEnvVars(value: string): string {
+	return value
+		.replace(/\$\{(\w+)\}/g, (_, name: string) => process.env[name] ?? "")
+		.replace(/\$env:(\w+)/g, (_, name: string) => process.env[name] ?? "");
+}
+
+function resolveConfigPath(value: string | undefined): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const resolved = interpolateEnvVars(value);
+	if (resolved === "~") return os.homedir();
+	if (resolved.startsWith("~/") || resolved.startsWith("~\\")) return path.join(os.homedir(), resolved.slice(2));
+	return resolved;
+}
+
+function resolveBearerToken(definition: Pick<ServerEntry, "bearerToken" | "bearerTokenEnv">): string | undefined {
+	if (typeof definition.bearerToken === "string") return interpolateEnvVars(definition.bearerToken);
+	return typeof definition.bearerTokenEnv === "string" ? process.env[definition.bearerTokenEnv] : undefined;
+}
+
+function stableStringify(value: unknown): string {
+	if (value === null || value === undefined || typeof value !== "object") {
+		const serialized = JSON.stringify(value);
+		return serialized === undefined ? "undefined" : serialized;
+	}
+	if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+	const obj = value as Record<string, unknown>;
+	return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(",")}}`;
+}

package/dist/extensions/pi-subagents/src/runs/shared/model-fallback.ts

@@ -0,0 +1,141 @@
+import type { ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
+import type { Usage } from "../../shared/types.ts";
+
+export type { AvailableModelInfo };
+
+interface ModelAttemptSummary {
+	model: string;
+	success: boolean;
+	exitCode?: number | null;
+	error?: string;
+	usage?: Usage;
+}
+
+export function splitThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
+	const colonIdx = model.lastIndexOf(":");
+	if (colonIdx === -1) return { baseModel: model, thinkingSuffix: "" };
+	return {
+		baseModel: model.substring(0, colonIdx),
+		thinkingSuffix: model.substring(colonIdx),
+	};
+}
+
+/** Sentinel model value requesting that a subagent inherit the parent session's model. */
+export const INHERIT_MODEL = "inherit";
+
+/** Minimal shape of the parent session's in-memory model (`ctx.model`). */
+export interface ParentModel {
+	provider: string;
+	id: string;
+}
+
+/**
+ * Resolve the `--model` override passed to a spawned subagent.
+ *
+ * When no model is requested (`undefined`, `false`, empty, or the `"inherit"`
+ * sentinel), the child must inherit the parent session's *in-memory* model
+ * (`provider/id`) instead of being left to resolve its own model. Without an
+ * explicit `provider/id`, the child falls back to the global
+ * `~/.pi/agent/settings.json` default, which is shared across every open PI
+ * session — so a different session that last changed its model in the TUI would
+ * silently contaminate this session's subagents (see issue #266). Passing an
+ * explicit `provider/id` keeps each session's children isolated to that
+ * session's model.
+ *
+ * An explicitly requested model string is resolved via {@link resolveModelCandidate}.
+ */
+export function resolveSubagentModelOverride(
+	requestedModel: string | boolean | undefined,
+	parentModel: ParentModel | undefined,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string | undefined {
+	const trimmed = typeof requestedModel === "string" ? requestedModel.trim() : "";
+	const explicit = trimmed && trimmed !== INHERIT_MODEL ? trimmed : undefined;
+	if (explicit === undefined) {
+		return parentModel ? `${parentModel.provider}/${parentModel.id}` : undefined;
+	}
+	return resolveModelCandidate(explicit, availableModels, preferredProvider);
+}
+
+export function resolveModelCandidate(
+	model: string | undefined,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string | undefined {
+	if (!model) return undefined;
+	if (model.includes("/")) return model;
+	if (!availableModels || availableModels.length === 0) return model;
+
+	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
+	const matches = availableModels.filter((entry) => entry.id === baseModel);
+	if (preferredProvider) {
+		const preferredMatch = matches.find((entry) => entry.provider === preferredProvider);
+		if (preferredMatch) return `${preferredMatch.fullId}${thinkingSuffix}`;
+	}
+	if (matches.length !== 1) return model;
+	return `${matches[0]!.fullId}${thinkingSuffix}`;
+}
+
+export function buildModelCandidates(
+	primaryModel: string | undefined,
+	fallbackModels: string[] | undefined,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string[] {
+	const seen = new Set<string>();
+	const candidates: string[] = [];
+	for (const raw of [primaryModel, ...(fallbackModels ?? [])]) {
+		if (!raw) continue;
+		const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
+		if (!normalized || seen.has(normalized)) continue;
+		seen.add(normalized);
+		candidates.push(normalized);
+	}
+	return candidates;
+}
+
+const RETRYABLE_MODEL_FAILURE_PATTERNS = [
+	/rate\s*limit/i,
+	/too many requests/i,
+	/\b429\b/,
+	/quota/i,
+	/billing/i,
+	/credit/i,
+	/auth(?:entication)?/i,
+	/unauthori[sz]ed/i,
+	/forbidden/i,
+	/api key/i,
+	/token expired/i,
+	/invalid key/i,
+	/provider.*unavailable/i,
+	/model.*unavailable/i,
+	/model.*disabled/i,
+	/model.*not found/i,
+	/unknown model/i,
+	/overloaded/i,
+	/service unavailable/i,
+	/temporar(?:ily)? unavailable/i,
+	/connection refused/i,
+	/fetch failed/i,
+	/network error/i,
+	/socket hang up/i,
+	/upstream/i,
+	/timed? out/i,
+	/timeout/i,
+	/\b502\b/,
+	/\b503\b/,
+	/\b504\b/,
+];
+
+export function isRetryableModelFailure(error: string | undefined): boolean {
+	if (!error) return false;
+	return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
+}
+
+export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
+	const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
+	return nextModel
+		? `[fallback] ${attempt.model} failed: ${failure}. Retrying with ${nextModel}.`
+		: `[fallback] ${attempt.model} failed: ${failure}.`;
+}