@oh-my-pi/pi-coding-agent 15.5.15 → 15.7.0

package/src/modes/interactive-mode.ts

@@ -35,6 +35,7 @@ import {
 import { APP_NAME, adjustHsv, getProjectDir, hsvToRgb, isEnoent, logger, postmortem, prompt } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { KeybindingsManager } from "../config/keybindings";
+import { MODEL_ROLES, type ModelRole } from "../config/model-registry";
 import { isSettingsInitialized, Settings, settings } from "../config/settings";
 import type {
 	ExtensionUIContext,
@@ -57,7 +58,7 @@ import planModeApprovedPrompt from "../prompts/system/plan-mode-approved.md" wit
 import planModeCompactInstructionsPrompt from "../prompts/system/plan-mode-compact-instructions.md" with {
 	type: "text",
 };
-import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import type { AgentSession, AgentSessionEvent, ResolvedRoleModel } from "../session/agent-session";
 import { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import { getRecentSessions } from "../session/session-manager";
@@ -80,7 +81,7 @@ import { DynamicBorder } from "./components/dynamic-border";
 import type { EvalExecutionComponent } from "./components/eval-execution";
 import type { HookEditorComponent } from "./components/hook-editor";
 import type { HookInputComponent } from "./components/hook-input";
-import type { HookSelectorComponent } from "./components/hook-selector";
+import type { HookSelectorComponent, HookSelectorSlider } from "./components/hook-selector";
 import { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
 import { WelcomeComponent, type LspServerInfo as WelcomeLspServerInfo } from "./components/welcome";
@@ -115,7 +116,14 @@ import {
 	onThemeChange,
 	theme,
 } from "./theme/theme";
-import type { CompactionQueuedMessage, InteractiveModeContext, SubmittedUserInput, TodoItem, TodoPhase } from "./types";
+import type {
+	CompactionQueuedMessage,
+	InteractiveModeContext,
+	InteractiveModeInitOptions,
+	SubmittedUserInput,
+	TodoItem,
+	TodoPhase,
+} from "./types";
 import { UiHelpers } from "./utils/ui-helpers";
 
 const HINT_SHIMMER_PALETTE: ShimmerPalette = {
@@ -324,8 +332,6 @@ export class InteractiveMode implements InteractiveModeContext {
 	#eventBus?: EventBus;
 	#eventBusUnsubscribers: Array<() => void> = [];
 	#welcomeComponent?: WelcomeComponent;
-	#todoClosingTimeout?: NodeJS.Timeout;
-	#todoClosingState: "idle" | "playing" | "done" = "idle";
 
 	constructor(
 		session: AgentSession,
@@ -369,7 +375,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.ui.requestRender(true);
 		};
 		this.editor.onAutocompleteUpdate = () => {
-			this.ui.requestRender();
+			this.ui.requestRender(false, { allowUnknownViewportMutation: true });
 		};
 		this.#syncEditorMaxHeight();
 		this.#resizeHandler = () => {
@@ -432,7 +438,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#observerRegistry = new SessionObserverRegistry();
 	}
 
-	async init(): Promise<void> {
+	playWelcomeIntro(): void {
+		this.#welcomeComponent?.playIntro(() => this.ui.requestRender());
+	}
+	async init(options: InteractiveModeInitOptions = {}): Promise<void> {
 		if (this.isInitialized) return;
 
 		this.keybindings = logger.time("InteractiveMode.init:keybindings", () => KeybindingsManager.create());
@@ -490,7 +499,9 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.ui.addChild(new Spacer(1));
 			this.ui.addChild(this.#welcomeComponent);
 			this.ui.addChild(new Spacer(1));
-			this.#welcomeComponent.playIntro(() => this.ui.requestRender());
+			if (!options.suppressWelcomeIntro) {
+				this.playWelcomeIntro();
+			}
 
 			// Add changelog if provided
 			if (this.#changelogMarkdown) {
@@ -1035,28 +1046,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	#renderTodoList(): void {
 		this.todoContainer.clear();
 		const phases = this.todoPhases.filter(phase => phase.tasks.length > 0);
-		if (phases.length === 0) {
-			this.#stopTodoClosingAnimation();
-			this.#todoClosingState = "idle";
-			return;
-		}
-
-		// When every visible task is completed or abandoned, fold the panel
-		// away with a brief celebratory animation (see
-		// #startTodoClosingAnimation). State machine guards against replaying
-		// on every re-render once the animation has finished.
-		const allClosed = phases.every(phase =>
-			phase.tasks.every(t => t.status === "completed" || t.status === "abandoned"),
-		);
-		if (allClosed) {
-			if (this.#todoClosingState === "done") return;
-			if (this.#todoClosingState === "idle") this.#startTodoClosingAnimation(phases);
-			return;
-		}
-		// Any open task here means the close animation is no longer applicable.
-		this.#stopTodoClosingAnimation();
-		this.#todoClosingState = "idle";
-
+		if (phases.length === 0) return;
 		const indent = "  ";
 		const hook = theme.tree.hook;
 		const lines = ["", indent + theme.bold(theme.fg("accent", "Todos"))];
@@ -1098,87 +1088,6 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.todoContainer.addChild(new Text(lines.join("\n"), 1, 0));
 	}
 
-	/**
-	 * Play a short "all done" close animation: a celebratory bright frame,
-	 * a brief dim transition, then a row-by-row vertical collapse until the
-	 * panel is empty. Triggered from #renderTodoList exactly once per
-	 * open-to-all-closed transition; #todoClosingState gates re-entry.
-	 *
-	 * While playing, the animator owns the panel container; #renderTodoList
-	 * returns early. Subsequent renders with state === "done" keep the
-	 * panel hidden until a fresh open task flips state back to "idle".
-	 */
-	#startTodoClosingAnimation(phases: TodoPhase[]): void {
-		this.#stopTodoClosingAnimation();
-		this.#todoClosingState = "playing";
-
-		const indent = "  ";
-		const hook = theme.tree.hook;
-		const snapshot: string[] = ["", `${indent}Todos ${theme.status.success}`];
-		for (let i = 0; i < phases.length; i++) {
-			const phase = phases[i];
-			snapshot.push(`${indent}${hook} ${formatPhaseDisplayName(phase.name, i + 1)}`);
-			for (let j = 0; j < phase.tasks.length; j++) {
-				const task = phase.tasks[j];
-				const mark = task.status === "abandoned" ? theme.status.aborted : theme.status.success;
-				const prefix = `${indent}${j === 0 ? hook : " "} `;
-				snapshot.push(`${prefix}${mark} ${task.content}`);
-			}
-		}
-
-		// Frame schedule (tint, drop-from-bottom, hold-ms). Frame 0 holds long
-		// enough for the user to actually read the final checkmarks before the
-		// fade starts; later frames fade and progressively drop rows from the
-		// bottom for the collapse effect. Total runtime ≈ 1.4s.
-		const frames = [
-			{ tint: "success" as const, drop: 0, holdMs: 900 },
-			{ tint: "success" as const, drop: 0, holdMs: 150 },
-			{ tint: "muted" as const, drop: 1, holdMs: 90 },
-			{ tint: "muted" as const, drop: 2, holdMs: 90 },
-			{ tint: "dim" as const, drop: 3, holdMs: 80 },
-			{ tint: "dim" as const, drop: 4, holdMs: 80 },
-		];
-
-		let frameIdx = 0;
-		const tick = (): void => {
-			if (this.#todoClosingState !== "playing") return;
-			if (frameIdx >= frames.length) {
-				this.todoContainer.clear();
-				this.#stopTodoClosingAnimation();
-				this.#todoClosingState = "done";
-				this.ui.requestRender();
-				return;
-			}
-			const { tint, drop, holdMs } = frames[frameIdx];
-			const visibleCount = Math.max(0, snapshot.length - drop);
-			this.todoContainer.clear();
-			if (visibleCount > 0) {
-				const visible = snapshot.slice(0, visibleCount);
-				const painted = visible.map((line, idx) => {
-					if (idx === 1) {
-						// Header row gets a bold flourish on the opening tick.
-						const colored = theme.fg(tint, line);
-						return frameIdx === 0 ? theme.bold(colored) : colored;
-					}
-					return theme.fg(tint, line);
-				});
-				this.todoContainer.addChild(new Text(painted.join("\n"), 1, 0));
-			}
-			this.ui.requestRender();
-			frameIdx++;
-			this.#todoClosingTimeout = setTimeout(tick, holdMs);
-		};
-
-		tick();
-	}
-
-	#stopTodoClosingAnimation(): void {
-		if (this.#todoClosingTimeout) {
-			clearTimeout(this.#todoClosingTimeout);
-			this.#todoClosingTimeout = undefined;
-		}
-	}
-
 	async #loadTodoList(): Promise<void> {
 		this.todoPhases = this.session.getTodoPhases();
 		this.#renderTodoList();
@@ -1702,6 +1611,20 @@ export class InteractiveMode implements InteractiveModeContext {
 		}
 	}
 
+	async #applyPlanExecutionModel(entry: ResolvedRoleModel | undefined): Promise<void> {
+		if (!entry) return;
+		try {
+			await this.session.applyRoleModel(entry);
+			this.statusLine.invalidate();
+			this.updateEditorBorderColor();
+			this.showStatus(`Continuing with ${entry.role}: ${entry.model.name || entry.model.id}`);
+		} catch (error) {
+			this.showWarning(
+				`Could not switch to the ${entry.role} model: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
 	async #approvePlan(
 		planContent: string,
 		options: {
@@ -1710,6 +1633,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			title: string;
 			preserveContext?: boolean;
 			compactBeforeExecute?: boolean;
+			executionModel?: ResolvedRoleModel;
 		},
 	): Promise<void> {
 		await renameApprovedPlanFile({
@@ -1791,6 +1715,8 @@ export class InteractiveMode implements InteractiveModeContext {
 			return;
 		}
 
+		await this.#applyPlanExecutionModel(options.executionModel);
+
 		// Approved plans land in a fresh (or compacted) session whose first user-visible
 		// turn is the synthetic plan-approved prompt — that path bypasses the
 		// input-controller's title generation. Seed an auto-name from the plan title
@@ -2106,13 +2032,38 @@ export class InteractiveMode implements InteractiveModeContext {
 			contextUsage?.percent != null
 				? `Approve and keep context (${contextUsage.percent.toFixed(1)}%)`
 				: "Approve and keep context";
+
+		// Model-tier slider: let the operator pick which configured role model
+		// (smol/default/slow/…) executes the approved plan. Left/right move it from
+		// any list position. Hidden when fewer than two role models resolve — a lone
+		// tier is no choice. `selectedTierIndex` tracks the live slider position.
+		const cycle = this.session.getRoleModelCycle(this.session.settings.get("cycleOrder"));
+		let selectedTierIndex = cycle?.currentIndex ?? 0;
+		const slider: HookSelectorSlider | undefined =
+			cycle && cycle.models.length > 1
+				? {
+						caption: "continue with",
+						index: cycle.currentIndex,
+						segments: cycle.models.map(entry => ({
+							label: entry.role,
+							color: MODEL_ROLES[entry.role as ModelRole]?.color,
+							detail: entry.model.name || entry.model.id,
+						})),
+						onChange: index => {
+							selectedTierIndex = index;
+						},
+					}
+				: undefined;
+		const helpText = slider ? `${this.#getPlanReviewHelpText()}  ◂/▸ model` : this.#getPlanReviewHelpText();
+
 		const choice = await this.showHookSelector(
 			"Plan mode - next step",
 			["Approve and execute", "Approve and compact context", keepContextLabel, "Refine plan"],
 			{
-				helpText: this.#getPlanReviewHelpText(),
+				helpText,
 				onExternalEditor: () => void this.#openPlanInExternalEditor(planFilePath),
 			},
+			{ slider },
 		);
 
 		if (choice === "Approve and execute" || choice === "Approve and compact context" || choice === keepContextLabel) {
@@ -2123,12 +2074,21 @@ export class InteractiveMode implements InteractiveModeContext {
 					this.showError(`Plan file not found at ${planFilePath}`);
 					return;
 				}
+				// Capture the operator's tier choice and hand it to #approvePlan, which
+				// applies it AFTER #exitPlanMode. #exitPlanMode restores
+				// #planModePreviousModelState (the model from before plan mode), so
+				// applying the slider choice any earlier would be silently reverted —
+				// the bug that made "continue with slow" keep executing on the default
+				// model. Deferred application also survives newSession()/compaction.
+				const executionModel =
+					cycle && selectedTierIndex !== cycle.currentIndex ? cycle.models[selectedTierIndex] : undefined;
 				await this.#approvePlan(latestPlanContent, {
 					planFilePath,
 					finalPlanFilePath,
 					title: details.title,
 					preserveContext: choice !== "Approve and execute",
 					compactBeforeExecute: choice === "Approve and compact context",
+					executionModel,
 				});
 			} catch (error) {
 				this.showError(
@@ -2311,7 +2271,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.ui.requestRender(true);
 		};
 		nextEditor.onAutocompleteUpdate = () => {
-			this.ui.requestRender();
+			this.ui.requestRender(false, { allowUnknownViewportMutation: true });
 		};
 		nextEditor.setMaxHeight(this.#computeEditorMaxHeight());
 		if (this.historyStorage) {
@@ -2904,8 +2864,9 @@ export class InteractiveMode implements InteractiveModeContext {
 		title: string,
 		options: string[],
 		dialogOptions?: ExtensionUIDialogOptions,
+		extra?: { slider?: HookSelectorSlider },
 	): Promise<string | undefined> {
-		return this.#extensionUiController.showHookSelector(title, options, dialogOptions);
+		return this.#extensionUiController.showHookSelector(title, options, dialogOptions, extra);
 	}
 
 	hideHookSelector(): void {

package/src/modes/internal-url-autocomplete.ts

@@ -0,0 +1,143 @@
+/**
+ * Autocomplete for internal-url schemes (skill://, rule://, omp://, local://,
+ * memory://, agent://, artifact://) while composing a prompt.
+ *
+ * Detection here MUST stay in sync with the generic URL-scheme trigger in the
+ * TUI editor (`packages/tui/src/components/editor.ts`); the editor fires the
+ * popup, this module decides whether there are candidates to show.
+ */
+import type { AutocompleteItem } from "@oh-my-pi/pi-tui";
+import { InternalUrlRouter } from "../internal-urls/router";
+
+/** Upper bound on candidates surfaced in the dropdown. */
+const MAX_URL_SUGGESTIONS = 25;
+
+/**
+ * A URL token ending at the cursor: a known internal scheme followed by one or
+ * two slashes and the partially typed host/path. The boundary/rest character
+ * classes mirror the editor trigger so both agree on what counts as a token.
+ */
+const URL_TOKEN_RE = /(?:^|[\s"'`(<=])([a-z][a-z0-9+.-]*:\/{1,2}[^\s"'`()<>]*)$/i;
+const SCHEME_SPLIT_RE = /^([a-z][a-z0-9+.-]*):\/{1,2}(.*)$/i;
+
+export interface InternalUrlContext {
+	/** Lowercased scheme (e.g. `local`). */
+	scheme: string;
+	/** Text typed after the slashes so far (host + path); may be empty. */
+	query: string;
+	/** Exact buffer token from its boundary to the cursor (the completion prefix). */
+	token: string;
+}
+
+// Subsequence fuzzy match: `hum` matches `humanizer`, `lp` matches `local-plan`.
+function fuzzyMatch(query: string, target: string): boolean {
+	if (query.length === 0) return true;
+	if (query.length > target.length) return false;
+	let q = 0;
+	for (let t = 0; t < target.length && q < query.length; t += 1) {
+		if (query[q] === target[t]) q += 1;
+	}
+	return q === query.length;
+}
+
+// Higher is better: exact > prefix > substring > scattered subsequence.
+function fuzzyScore(query: string, target: string): number {
+	if (query.length === 0) return 1;
+	if (target === query) return 100;
+	if (target.startsWith(query)) return 80;
+	if (target.includes(query)) return 60;
+	let q = 0;
+	let gaps = 0;
+	let last = -1;
+	for (let t = 0; t < target.length && q < query.length; t += 1) {
+		if (query[q] === target[t]) {
+			if (last >= 0 && t - last > 1) gaps += 1;
+			last = t;
+			q += 1;
+		}
+	}
+	if (q !== query.length) return 0;
+	return Math.max(1, 40 - gaps * 5);
+}
+
+/**
+ * Detect a completable internal-url token immediately before the cursor.
+ * Returns `null` when the text is not a `scheme://` token whose scheme is
+ * registered with a completion-capable handler.
+ */
+export function extractInternalUrlContext(textBeforeCursor: string): InternalUrlContext | null {
+	const tokenMatch = URL_TOKEN_RE.exec(textBeforeCursor);
+	if (!tokenMatch) return null;
+	const token = tokenMatch[1]!;
+	const parts = SCHEME_SPLIT_RE.exec(token);
+	if (!parts) return null;
+	const scheme = parts[1]!.toLowerCase();
+	if (!InternalUrlRouter.instance().completionSchemes().includes(scheme)) return null;
+	return { scheme, query: parts[2] ?? "", token };
+}
+
+/**
+ * Suggestions for the internal-url token ending at the cursor, or `null` when
+ * the text is not such a token or no candidate matches the typed query.
+ */
+export async function getInternalUrlSuggestions(
+	textBeforeCursor: string,
+): Promise<{ items: AutocompleteItem[]; prefix: string } | null> {
+	const ctx = extractInternalUrlContext(textBeforeCursor);
+	if (!ctx) return null;
+
+	const candidates = await InternalUrlRouter.instance().complete(ctx.scheme, ctx.query);
+	if (!candidates || candidates.length === 0) return null;
+
+	const query = ctx.query.toLowerCase();
+	const scored: Array<{ item: AutocompleteItem; score: number }> = [];
+	for (const candidate of candidates) {
+		const target = candidate.value.toLowerCase();
+		if (!fuzzyMatch(query, target)) continue;
+		scored.push({
+			item: {
+				value: `${ctx.scheme}://${candidate.value}`,
+				label: candidate.label ?? candidate.value,
+				...(candidate.description ? { description: candidate.description } : {}),
+			},
+			score: fuzzyScore(query, target),
+		});
+	}
+	if (scored.length === 0) return null;
+
+	scored.sort((a, b) => b.score - a.score);
+	return {
+		items: scored.slice(0, MAX_URL_SUGGESTIONS).map(entry => entry.item),
+		prefix: ctx.token,
+	};
+}
+
+/** Whether `prefix` (the token a completion was offered for) is an internal-url token. */
+export function isInternalUrlPrefix(prefix: string): boolean {
+	return extractInternalUrlContext(prefix) !== null;
+}
+
+/**
+ * Replace the internal-url token with the selected candidate, appending a
+ * trailing space (matching `@` file-reference behavior) so the user can keep
+ * typing.
+ */
+export function applyInternalUrlCompletion(
+	lines: string[],
+	cursorLine: number,
+	cursorCol: number,
+	item: AutocompleteItem,
+	prefix: string,
+): { lines: string[]; cursorLine: number; cursorCol: number } {
+	const currentLine = lines[cursorLine] || "";
+	const beforePrefix = currentLine.slice(0, cursorCol - prefix.length);
+	const afterCursor = currentLine.slice(cursorCol);
+	const insert = `${item.value} `;
+	const newLines = [...lines];
+	newLines[cursorLine] = beforePrefix + insert + afterCursor;
+	return {
+		lines: newLines,
+		cursorLine,
+		cursorCol: beforePrefix.length + insert.length,
+	};
+}

package/src/modes/orchestrate.ts

@@ -0,0 +1,36 @@
+import orchestrateNotice from "../prompts/system/orchestrate-notice.md" with { type: "text" };
+import { createGradientHighlighter } from "./gradient-highlight";
+
+/**
+ * "orchestrate" keyword support.
+ *
+ * Typing the standalone word in the input editor paints it with a cool
+ * teal→violet gradient ({@link highlightOrchestrate}); submitting a message that
+ * mentions it appends a hidden {@link ORCHESTRATE_NOTICE} that switches the model
+ * into multi-agent orchestration mode. Matching is word-bounded and
+ * case-insensitive, so "orchestrated"/"orchestrating" never trigger either
+ * behavior. Replaces the former `/orchestrate` slash command.
+ */
+
+// Detection: standalone keyword, any case. Non-global so `.test` stays stateless.
+const ORCHESTRATE_WORD = /\borchestrate\b/i;
+
+/** Hidden system notice appended after a user message that mentions "orchestrate". */
+export const ORCHESTRATE_NOTICE: string = orchestrateNotice.trim();
+
+/** Whether `text` contains the standalone keyword "orchestrate" (any case). */
+export function containsOrchestrate(text: string): boolean {
+	return ORCHESTRATE_WORD.test(text);
+}
+
+/**
+ * Highlight every standalone "orchestrate" in `text` for editor display with a
+ * cool teal→violet gradient (hue 150..280), visually distinct from ultrathink's
+ * full-spectrum rainbow.
+ */
+export const highlightOrchestrate: (text: string) => string = createGradientHighlighter({
+	probe: /orchestrate/i,
+	highlight: /\borchestrate\b/gi,
+	stops: 14,
+	hue: t => 150 + t * 130,
+});

package/src/modes/prompt-action-autocomplete.ts

@@ -8,6 +8,11 @@ import {
 import { formatKeyHints, type KeybindingsManager } from "../config/keybindings";
 import { isSettingsInitialized, settings } from "../config/settings";
 import { applyEmojiCompletion, getEmojiSuggestions, isEmojiPrefix, tryEmojiInlineReplace } from "./emoji-autocomplete";
+import {
+	applyInternalUrlCompletion,
+	getInternalUrlSuggestions,
+	isInternalUrlPrefix,
+} from "./internal-url-autocomplete";
 
 interface PromptActionDefinition {
 	id: string;
@@ -128,6 +133,9 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			}
 		}
 
+		const urlSuggestions = await getInternalUrlSuggestions(textBeforeCursor);
+		if (urlSuggestions) return urlSuggestions;
+
 		if (!isSettingsInitialized() || settings.get("emojiAutocomplete")) {
 			const emojiSuggestions = getEmojiSuggestions(textBeforeCursor);
 			if (emojiSuggestions) return emojiSuggestions;
@@ -170,6 +178,10 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			};
 		}
 
+		if (isInternalUrlPrefix(prefix)) {
+			return applyInternalUrlCompletion(lines, cursorLine, cursorCol, item, prefix);
+		}
+
 		if (isEmojiPrefix(prefix)) {
 			return applyEmojiCompletion(lines, cursorLine, cursorCol, item, prefix);
 		}

package/src/modes/setup-wizard/index.ts

@@ -0,0 +1,88 @@
+import type { Settings } from "../../config/settings";
+import type { InteractiveModeContext } from "../types";
+import { glyphSetupScene } from "./scenes/glyph";
+import { providersSetupScene } from "./scenes/providers";
+import { themeSetupScene } from "./scenes/theme";
+import type { SetupScene } from "./scenes/types";
+import { SetupWizardComponent } from "./wizard-overlay";
+
+export type { SetupScene, SetupSceneController, SetupSceneHost, SetupSceneResult } from "./scenes/types";
+
+export const ALL_SCENES = [
+	providersSetupScene,
+	glyphSetupScene,
+	themeSetupScene,
+] as const satisfies readonly SetupScene[];
+
+export const CURRENT_SETUP_VERSION = ALL_SCENES.reduce((max, scene) => Math.max(max, scene.minVersion), 0);
+
+export interface SetupSceneSelectionOptions {
+	resuming?: boolean;
+	isTTY?: boolean;
+	skipEnv?: string;
+	setupWizardEnabled?: boolean;
+	force?: boolean;
+}
+
+function setupSkipEnvEnabled(value: string | undefined): boolean {
+	if (value === undefined) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+export async function selectSetupScenes(
+	storedVersion: number,
+	scenes: readonly SetupScene[],
+	ctx?: InteractiveModeContext,
+	options: SetupSceneSelectionOptions = {},
+): Promise<SetupScene[]> {
+	const isTTY = options.isTTY ?? (process.stdin.isTTY && process.stdout.isTTY);
+	if (!isTTY) return [];
+	if (!options.force) {
+		if (options.resuming) return [];
+		if (setupSkipEnvEnabled(options.skipEnv ?? Bun.env.OMP_SKIP_SETUP)) return [];
+		if (options.setupWizardEnabled === false) return [];
+	}
+
+	const selected: SetupScene[] = [];
+	for (const scene of scenes) {
+		if (!options.force && scene.minVersion <= storedVersion) continue;
+		if (scene.shouldRun) {
+			if (!ctx) continue;
+			if (!(await scene.shouldRun(ctx))) continue;
+		}
+		selected.push(scene);
+	}
+	return selected;
+}
+
+export async function markSetupWizardComplete(
+	settings: Settings,
+	version: number = CURRENT_SETUP_VERSION,
+): Promise<void> {
+	settings.set("setupVersion", version);
+	await settings.flush();
+}
+
+export async function runSetupWizard(
+	ctx: InteractiveModeContext,
+	scenes: readonly SetupScene[] = ALL_SCENES,
+): Promise<void> {
+	if (scenes.length === 0) return;
+	const component = new SetupWizardComponent(ctx, scenes);
+	const overlay = ctx.ui.showOverlay(component, {
+		width: "100%",
+		maxHeight: "100%",
+		anchor: "top-left",
+		margin: 0,
+	});
+	try {
+		await component.run();
+		await markSetupWizardComplete(ctx.settings);
+	} finally {
+		component.dispose();
+		ctx.ui.setFocus(component);
+		overlay.hide();
+	}
+	ctx.playWelcomeIntro();
+}