@prometheus-ai/agent 0.5.3 → 0.5.8

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

@@ -1,4 +1,5 @@
 import type { Settings } from "../../config/settings";
+import { CURRENT_SETUP_VERSION } from "../setup-version";
 import type { InteractiveModeContext } from "../types";
 import { glyphSetupScene } from "./scenes/glyph";
 import { providersSetupScene } from "./scenes/providers";
@@ -8,14 +9,14 @@ import { SetupWizardComponent } from "./wizard-overlay";
 
 export type { SetupScene, SetupSceneController, SetupSceneHost, SetupSceneResult } from "./scenes/types";
 
+export { CURRENT_SETUP_VERSION };
+
 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;
@@ -64,9 +65,15 @@ export async function markSetupWizardComplete(
 	await settings.flush();
 }
 
+export interface RunSetupWizardOptions {
+	markComplete?: boolean;
+	playWelcomeIntro?: boolean;
+}
+
 export async function runSetupWizard(
 	ctx: InteractiveModeContext,
 	scenes: readonly SetupScene[] = ALL_SCENES,
+	options: RunSetupWizardOptions = {},
 ): Promise<void> {
 	if (scenes.length === 0) return;
 	const component = new SetupWizardComponent(ctx, scenes);
@@ -75,14 +82,19 @@ export async function runSetupWizard(
 		maxHeight: "100%",
 		anchor: "top-left",
 		margin: 0,
+		fullscreen: true,
 	});
 	try {
 		await component.run();
-		await markSetupWizardComplete(ctx.settings);
+		if (options.markComplete !== false) {
+			await markSetupWizardComplete(ctx.settings);
+		}
 	} finally {
 		component.dispose();
 		ctx.ui.setFocus(component);
 		overlay.hide();
 	}
-	ctx.playWelcomeIntro();
+	if (options.playWelcomeIntro !== false) {
+		ctx.playWelcomeIntro();
+	}
 }

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

@@ -0,0 +1,16 @@
+import type { InteractiveModeContext } from "../types";
+
+export async function runProviderSetupWizard(ctx: InteractiveModeContext): Promise<void> {
+	// Keep the full setup wizard behind the existing cold-start boundary; a static
+	// import here would load provider/OAuth/search/theme setup deps on every TUI startup.
+	const { ALL_SCENES, runSetupWizard } = await import("./index");
+	const providersScene = ALL_SCENES.find(scene => scene.id === "providers");
+	if (!providersScene) {
+		ctx.showError("Provider setup is unavailable.");
+		return;
+	}
+	await runSetupWizard(ctx, [providersScene], {
+		markComplete: false,
+		playWelcomeIntro: false,
+	});
+}

package/src/modes/setup-wizard/scenes/glyph.ts

@@ -1,4 +1,4 @@
-import { type SelectItem, SelectList } from "@prometheus-ai/tui";
+import { type SelectItem, SelectList, type SgrMouseEvent } from "@prometheus-ai/tui";
 import { getSelectListTheme, type SymbolPreset, setSymbolPreset, theme } from "../../theme/theme";
 import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
 
@@ -29,6 +29,8 @@ class GlyphSceneController implements SetupSceneController {
 	#selectList: SelectList;
 	#previewRequest = 0;
 	#committing = false;
+	/** Render line where the select list begins. */
+	#listRowStart = 0;
 
 	constructor(private readonly host: SetupSceneHost) {
 		this.#selectList = new SelectList(GLYPH_ITEMS, GLYPH_ITEMS.length, getSelectListTheme());
@@ -60,12 +62,28 @@ class GlyphSceneController implements SetupSceneController {
 		this.#selectList.handleInput(data);
 	}
 
-	render(width: number): string[] {
-		return [
-			theme.fg("muted", "If a row shows boxes, tofu, or misaligned icons, pick another."),
-			"",
-			...this.#selectList.render(width),
-		];
+	/** Wheel moves the highlight (live preview); hover lights the row under the pointer; click confirms it. */
+	routeMouse(event: SgrMouseEvent, line: number, _col: number): void {
+		if (this.#committing) return;
+		if (event.wheel !== null) {
+			this.#selectList.handleWheel(event.wheel);
+			return;
+		}
+		const index = this.#selectList.hitTest(line - this.#listRowStart);
+		if (event.motion) {
+			this.#selectList.setHoverIndex(index ?? null);
+			return;
+		}
+		if (event.leftClick && index !== undefined) {
+			this.#selectList.clickItem(index);
+		}
+	}
+
+	render(width: number): readonly string[] {
+		const lines = [theme.fg("muted", "If a row shows boxes, tofu, or misaligned icons, pick another."), ""];
+		this.#listRowStart = lines.length;
+		lines.push(...this.#selectList.render(width));
+		return lines;
 	}
 
 	async #commit(preset: SymbolPreset): Promise<void> {

package/src/modes/setup-wizard/scenes/providers.ts

@@ -1,27 +1,28 @@
-import { TabBar } from "@prometheus-ai/tui";
+import { type SgrMouseEvent, TabBar } from "@prometheus-ai/tui";
 import { getTabBarTheme } from "../../shared";
-import { ChannelsTab } from "./channels";
 import { SignInTab } from "./sign-in";
 import type { SetupScene, SetupSceneController, SetupSceneHost, SetupTab } from "./types";
 import { WebSearchTab } from "./web-search";
 
 /**
- * Tabbed connection setup scene. Composes independent panels (model sign-in,
- * web search, channels) behind a {@link TabBar}; the active panel owns
+ * Tabbed "Set up your providers" scene. Composes independent panels (model
+ * sign-in, web search) behind a {@link TabBar}; the active panel owns
  * rendering and input, while modal panels (e.g. an in-flight OAuth login)
  * temporarily suppress tab switching.
  */
 class ProvidersSceneController implements SetupSceneController {
-	title = "Set up your connections";
-	subtitle = "Sign in, pick web search, and configure channels. Press Esc when you're done.";
+	title = "Set up your providers";
+	subtitle = "Sign in and pick a web search provider. Press Esc when you're done.";
 
 	#tabs: SetupTab[];
 	#tabBar: TabBar;
+	/** Lines the tab bar occupied in the last render (body starts one blank line below). */
+	#tabRowCount = 1;
 
 	constructor(host: SetupSceneHost) {
-		this.#tabs = [new SignInTab(host), new WebSearchTab(host), new ChannelsTab(host)];
+		this.#tabs = [new SignInTab(host), new WebSearchTab(host)];
 		this.#tabBar = new TabBar(
-			"Connections",
+			"Providers",
 			this.#tabs.map(tab => ({ id: tab.id, label: tab.label })),
 			getTabBarTheme(),
 		);
@@ -53,8 +54,40 @@ class ProvidersSceneController implements SetupSceneController {
 		tab.handleInput(data);
 	}
 
-	render(width: number): string[] {
-		return [...this.#tabBar.render(width), "", ...this.#activeTab().render(width)];
+	/**
+	 * Hit-test mouse reports against the last render: rows inside the tab bar
+	 * hover/switch tabs (suppressed while the active panel is modal, matching
+	 * keyboard tab cycling); everything else forwards to the active panel at
+	 * panel-local coordinates. Wheel always goes to the panel so scrolling
+	 * works regardless of pointer position.
+	 */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		const tab = this.#activeTab();
+		if (event.wheel === null && line >= 0 && line < this.#tabRowCount) {
+			if (tab.modal) return;
+			const hit = this.#tabBar.tabAt(line, col);
+			if (event.motion) {
+				this.#tabBar.setHoverTab(hit && !hit.muted ? hit.id : null);
+			} else if (event.leftClick && hit) {
+				this.#tabBar.selectTab(hit.id);
+			}
+			return;
+		}
+		if (event.motion) this.#tabBar.setHoverTab(null);
+		const bodyLine = line - this.#tabRowCount - 1;
+		if (tab.routeMouse) {
+			tab.routeMouse(event, bodyLine, col);
+			return;
+		}
+		if (event.wheel !== null && !tab.modal) {
+			tab.handleInput(event.wheel === -1 ? "\x1b[A" : "\x1b[B");
+		}
+	}
+
+	render(width: number): readonly string[] {
+		const tabLines = this.#tabBar.render(width);
+		this.#tabRowCount = tabLines.length;
+		return [...tabLines, "", ...this.#activeTab().render(width)];
 	}
 
 	dispose(): void {
@@ -64,7 +97,7 @@ class ProvidersSceneController implements SetupSceneController {
 
 export const providersSetupScene: SetupScene = {
 	id: "providers",
-	title: "Set up your connections",
-	minVersion: 3,
+	title: "Set up your providers",
+	minVersion: 1,
 	mount: host => new ProvidersSceneController(host),
 };

package/src/modes/setup-wizard/scenes/sign-in.ts

@@ -1,20 +1,12 @@
 import type { AuthStorage } from "@prometheus-ai/ai";
-import type { OAuthProvider } from "@prometheus-ai/ai/utils/oauth/types";
-import { Input, matchesKey, wrapTextWithAnsi } from "@prometheus-ai/tui";
+import { PASTE_CODE_LOGIN_PROVIDERS } from "@prometheus-ai/ai";
+import type { OAuthProvider } from "@prometheus-ai/ai/oauth/types";
+import { Input, matchesKey, type SgrMouseEvent, wrapTextWithAnsi } from "@prometheus-ai/tui";
 import { getAgentDbPath } from "@prometheus-ai/utils";
 import { OAuthSelectorComponent } from "../../components/oauth-selector";
 import { theme } from "../../theme/theme";
 import type { SetupSceneHost, SetupTab } from "./types";
 
-/** Providers whose OAuth flow needs a pasted code/redirect URL rather than a callback server. */
-const CALLBACK_SERVER_PROVIDERS: Partial<Record<OAuthProvider, true>> = {
-	anthropic: true,
-	"openai-codex": true,
-	"gitlab-duo": true,
-	"google-gemini-cli": true,
-	"google-antigravity": true,
-};
-
 function loginUrlLink(url: string): string {
 	return `\x1b]8;;${url}\x07Open login URL\x1b]8;;\x07`;
 }
@@ -43,6 +35,8 @@ export class SignInTab implements SetupTab {
 	#loginAbort: AbortController | undefined;
 	#loggingInProvider: string | undefined;
 	#disposed = false;
+	/** Render line where the provider selector begins. */
+	#selectorRowStart = 2;
 
 	constructor(private readonly host: SetupSceneHost) {
 		this.#authStorage = host.ctx.session.modelRegistry.authStorage;
@@ -76,12 +70,19 @@ export class SignInTab implements SetupTab {
 		this.#selector.handleInput(data);
 	}
 
-	render(width: number): string[] {
+	/** Forward mouse to the provider selector; pointer is inert during an active login or code prompt. */
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		if (this.#loggingInProvider || this.#prompt) return;
+		this.#selector.routeMouse(event, line - this.#selectorRowStart, col);
+	}
+
+	render(width: number): readonly string[] {
 		const lines: string[] = [];
 		if (this.#loggingInProvider) {
 			lines.push(theme.bold(`Signing in to ${this.#loggingInProvider}`));
 		} else {
 			lines.push(theme.fg("muted", "Pick a provider to sign in — you can connect more than one."), "");
+			this.#selectorRowStart = lines.length;
 			lines.push(...this.#selector.render(width));
 		}
 
@@ -119,7 +120,7 @@ export class SignInTab implements SetupTab {
 
 	async #login(providerId: string): Promise<void> {
 		if (this.#loggingInProvider || this.#disposed) return;
-		const useManualInput = CALLBACK_SERVER_PROVIDERS[providerId as OAuthProvider] === true;
+		const useManualInput = PASTE_CODE_LOGIN_PROVIDERS.has(providerId);
 		this.#selector.stopValidation();
 		this.#loggingInProvider = providerId;
 		this.#statusLines = [theme.fg("dim", "Starting OAuth flow…")];

package/src/modes/setup-wizard/scenes/splash.ts

@@ -189,7 +189,7 @@ export function renderSetupSplash(width: number, height: number, elapsedMs: numb
 /** Centered fallback for windows too small to hold the full scene. */
 function renderCompactSplash(width: number, height: number, phase: number, shine: ShineConfig): string[] {
 	const art = height >= 14 ? LARGE_LOGO : PROMETHEUS_LOGO;
-	const content = [...gradientLogo(art, phase, shine), "", theme.bold("Prometheus")];
+	const content = [...gradientLogo(art, phase, shine), "", theme.bold("O h   M y   P i")];
 	const start = Math.max(0, Math.floor((height - content.length) / 2));
 	const lines: string[] = [];
 	for (let y = 0; y < height; y++) {

package/src/modes/setup-wizard/scenes/telegram.ts

@@ -3,6 +3,7 @@ import {
 	DEFAULT_TELEGRAM_WEBHOOK_PATH,
 	normalizeTelegramBotUsername,
 	normalizeWebhookPath,
+	parseTelegramAllowedChatIds,
 	parseTelegramAllowedUserIds,
 	type TelegramGatewayMode,
 } from "../../../cli/gateway-cli";
@@ -25,7 +26,7 @@ import { shortenPath } from "../../../tools/render-utils";
 import { getSelectListTheme, theme } from "../../theme/theme";
 import type { SetupSceneHost, SetupTab } from "./types";
 
-const MAX_VISIBLE = 14;
+const MAX_VISIBLE = 16;
 const PARSE_MODES = ["none", "HTML", "Markdown", "MarkdownV2"] as const;
 
 type TelegramFieldId =
@@ -36,6 +37,7 @@ type TelegramFieldId =
 	| "public-base-url"
 	| "webhook-path"
 	| "allowed-users"
+	| "allowed-chats"
 	| "group-scope"
 	| "thread-scope"
 	| "parse-mode"
@@ -45,7 +47,13 @@ type TelegramFieldId =
 	| "register-webhook"
 	| "finish";
 
-type InputFieldId = "bot-token" | "bot-username" | "public-base-url" | "webhook-path" | "allowed-users";
+type InputFieldId =
+	| "bot-token"
+	| "bot-username"
+	| "public-base-url"
+	| "webhook-path"
+	| "allowed-users"
+	| "allowed-chats";
 
 interface ActiveInput {
 	field: InputFieldId;
@@ -161,6 +169,7 @@ export class TelegramTab implements SetupTab {
 		const publicBaseUrl = this.host.ctx.settings.get("gateway.telegram.publicBaseUrl");
 		const webhookPath = this.host.ctx.settings.get("gateway.telegram.webhookPath") ?? DEFAULT_TELEGRAM_WEBHOOK_PATH;
 		const allowedUsers = this.host.ctx.settings.get("gateway.telegram.allowedUsers");
+		const allowedChats = this.host.ctx.settings.get("gateway.telegram.allowedChats");
 		const groupScope = this.host.ctx.settings.get("gateway.telegram.groupScope");
 		const threadScope = this.host.ctx.settings.get("gateway.telegram.threadScope");
 		const parseMode = this.host.ctx.settings.get("gateway.telegram.parseMode");
@@ -202,7 +211,13 @@ export class TelegramTab implements SetupTab {
 			{
 				value: "allowed-users",
 				label: "Allowed users",
-				description: allowedUsers || "Required before activating Telegram",
+				description:
+					allowedUsers || (allowedChats ? "Optional per-user gate" : "Required before activating Telegram"),
+			},
+			{
+				value: "allowed-chats",
+				label: "Allowed chats",
+				description: allowedChats || "Optional group/channel chat IDs",
 			},
 			{
 				value: "group-scope",
@@ -266,6 +281,7 @@ export class TelegramTab implements SetupTab {
 			case "public-base-url":
 			case "webhook-path":
 			case "allowed-users":
+			case "allowed-chats":
 				this.#startInput(id);
 				return;
 			case "group-scope":
@@ -373,20 +389,18 @@ export class TelegramTab implements SetupTab {
 				}
 				case "allowed-users": {
 					const allowedUsers = parseTelegramAllowedUserIds(value);
-					if (!allowedUsers || allowedUsers.length === 0) {
-						this.#status = [];
-						if (
-							!this.#disableGateway(
-								"Telegram allowlist is empty; add an allowed user and activate Telegram again.",
-							)
-						) {
-							break;
-						}
-					}
 					this.#setAllowedUsers(allowedUsers);
+					this.#disableGatewayIfAllowlistEmpty();
 					this.#status.unshift(theme.fg("success", `${theme.status.success} Telegram allowlist saved`));
 					break;
 				}
+				case "allowed-chats": {
+					const allowedChats = parseTelegramAllowedChatIds(value);
+					this.#setAllowedChats(allowedChats);
+					this.#disableGatewayIfAllowlistEmpty();
+					this.#status.unshift(theme.fg("success", `${theme.status.success} Telegram chat allowlist saved`));
+					break;
+				}
 				default:
 					field satisfies never;
 			}
@@ -414,6 +428,29 @@ export class TelegramTab implements SetupTab {
 		}
 	}
 
+	#setAllowedChats(allowedChats: string[] | undefined): void {
+		const value = allowedChats?.join(", ") ?? undefined;
+		this.host.ctx.settings.set("gateway.telegram.allowedChats", value);
+		const effectiveValue = this.host.ctx.settings.get("gateway.telegram.allowedChats");
+		if (value) {
+			if (effectiveValue !== value) {
+				this.host.ctx.settings.override("gateway.telegram.allowedChats", value);
+			}
+			return;
+		}
+		if (effectiveValue) {
+			this.host.ctx.settings.override("gateway.telegram.allowedChats", "");
+		}
+	}
+
+	#disableGatewayIfAllowlistEmpty(): boolean {
+		if (this.#hasAllowedPrincipal()) return true;
+		this.#status = [];
+		return this.#disableGateway(
+			"Telegram allowlist is empty; add an allowed user or chat and activate Telegram again.",
+		);
+	}
+
 	#setGatewayEnabled(enabled: boolean): boolean {
 		this.host.ctx.settings.set("gateway.telegram.enabled", enabled);
 		if (this.host.ctx.settings.get("gateway.telegram.enabled") !== enabled) {
@@ -525,8 +562,8 @@ export class TelegramTab implements SetupTab {
 			this.host.requestRender();
 			return;
 		}
-		const allowedUsers = this.#requireAllowedUsers();
-		if (!allowedUsers) return;
+		const allowedPrincipals = this.#requireAllowedPrincipals();
+		if (!allowedPrincipals) return;
 
 		await this.#runBusy(async signal => {
 			await deleteTelegramWebhook(token, { dropPendingUpdates: false, signal, fetch: this.deps.fetch });
@@ -538,7 +575,7 @@ export class TelegramTab implements SetupTab {
 			}
 			this.#status = [
 				theme.fg("success", `${theme.status.success} Telegram polling activated`),
-				theme.fg("dim", `Authorized users: ${allowedUsers.length}`),
+				theme.fg("dim", this.#formatAllowedPrincipals(allowedPrincipals)),
 				theme.fg("dim", "Gateway serve will use getUpdates."),
 			];
 		});
@@ -557,8 +594,8 @@ export class TelegramTab implements SetupTab {
 			this.host.requestRender();
 			return;
 		}
-		const allowedUsers = this.#requireAllowedUsers();
-		if (!allowedUsers) return;
+		const allowedPrincipals = this.#requireAllowedPrincipals();
+		if (!allowedPrincipals) return;
 
 		await this.#runBusy(async signal => {
 			const webhookPath = normalizeWebhookPath(this.host.ctx.settings.get("gateway.telegram.webhookPath"));
@@ -578,7 +615,7 @@ export class TelegramTab implements SetupTab {
 			}
 			this.#status = [
 				theme.fg("success", `${theme.status.success} Telegram webhook registered`),
-				theme.fg("dim", `Authorized users: ${allowedUsers.length}`),
+				theme.fg("dim", this.#formatAllowedPrincipals(allowedPrincipals)),
 				theme.fg("dim", `URL: ${info.url || webhookUrl}`),
 				theme.fg("dim", `Pending updates: ${info.pending_update_count}`),
 			];
@@ -627,12 +664,15 @@ export class TelegramTab implements SetupTab {
 		this.host.requestRender();
 	}
 
-	#requireAllowedUsers(): string[] | undefined {
+	#requireAllowedPrincipals(): { users: string[]; chats: string[] } | undefined {
 		try {
 			const allowedUsers = parseTelegramAllowedUserIds(this.host.ctx.settings.get("gateway.telegram.allowedUsers"));
-			if (allowedUsers && allowedUsers.length > 0) return allowedUsers;
+			const allowedChats = parseTelegramAllowedChatIds(this.host.ctx.settings.get("gateway.telegram.allowedChats"));
+			if ((allowedUsers?.length ?? 0) > 0 || (allowedChats?.length ?? 0) > 0) {
+				return { users: allowedUsers ?? [], chats: allowedChats ?? [] };
+			}
 			this.#status = [
-				theme.fg("warning", `${theme.status.pending} Add at least one allowed Telegram user ID first`),
+				theme.fg("warning", `${theme.status.pending} Add at least one allowed Telegram user or chat ID first`),
 			];
 		} catch (error) {
 			this.#status = [theme.fg("error", `${theme.status.error} ${formatError(error)}`)];
@@ -641,6 +681,17 @@ export class TelegramTab implements SetupTab {
 		return undefined;
 	}
 
+	#hasAllowedPrincipal(): boolean {
+		return (
+			(this.host.ctx.settings.get("gateway.telegram.allowedUsers")?.trim().length ?? 0) > 0 ||
+			(this.host.ctx.settings.get("gateway.telegram.allowedChats")?.trim().length ?? 0) > 0
+		);
+	}
+
+	#formatAllowedPrincipals(principals: { users: string[]; chats: string[] }): string {
+		return `Authorized users: ${principals.users.length}; chats: ${principals.chats.length}`;
+	}
+
 	async #refreshSecretStatus(): Promise<void> {
 		const [botToken, webhookSecret] = await Promise.all([
 			readTelegramGatewaySecret("bot-token"),
@@ -665,6 +716,8 @@ export class TelegramTab implements SetupTab {
 				return this.host.ctx.settings.get("gateway.telegram.webhookPath") ?? DEFAULT_TELEGRAM_WEBHOOK_PATH;
 			case "allowed-users":
 				return this.host.ctx.settings.get("gateway.telegram.allowedUsers") ?? "";
+			case "allowed-chats":
+				return this.host.ctx.settings.get("gateway.telegram.allowedChats") ?? "";
 			default:
 				field satisfies never;
 				return "";
@@ -683,6 +736,8 @@ export class TelegramTab implements SetupTab {
 				return "webhook path";
 			case "allowed-users":
 				return "allowed Telegram user IDs";
+			case "allowed-chats":
+				return "allowed Telegram chat IDs";
 			default:
 				field satisfies never;
 				return "value";

package/src/modes/setup-wizard/scenes/theme.ts

@@ -1,4 +1,11 @@
-import { padding, type SelectItem, SelectList, truncateToWidth, visibleWidth } from "@prometheus-ai/tui";
+import {
+	padding,
+	type SelectItem,
+	SelectList,
+	type SgrMouseEvent,
+	truncateToWidth,
+	visibleWidth,
+} from "@prometheus-ai/tui";
 import {
 	enableAutoTheme,
 	getAvailableThemes,
@@ -89,6 +96,8 @@ class ThemeSceneController implements SetupSceneController {
 	#message: string | undefined;
 	#previewRequest = 0;
 	#disposed = false;
+	/** Render line where the select list began, or -1 while it is not shown. */
+	#listRowStart = -1;
 	readonly #originalTheme = getCurrentThemeName();
 	readonly #originalSymbolPreset: SymbolPreset;
 	readonly #originalColorBlindMode: boolean;
@@ -117,7 +126,23 @@ class ThemeSceneController implements SetupSceneController {
 		this.#selectList.handleInput(data);
 	}
 
-	render(width: number): string[] {
+	/** Wheel moves the highlight (live preview); hover lights the row under the pointer; click confirms it. */
+	routeMouse(event: SgrMouseEvent, line: number, _col: number): void {
+		if (event.wheel !== null) {
+			this.#selectList.handleWheel(event.wheel);
+			return;
+		}
+		const index = this.#listRowStart >= 0 ? this.#selectList.hitTest(line - this.#listRowStart) : undefined;
+		if (event.motion) {
+			this.#selectList.setHoverIndex(index ?? null);
+			return;
+		}
+		if (event.leftClick && index !== undefined) {
+			this.#selectList.clickItem(index);
+		}
+	}
+
+	render(width: number): readonly string[] {
 		const lines = [
 			theme.fg("muted", "Theme changes preview live. Nothing is saved until you press Enter."),
 			this.#mode === "all"
@@ -128,8 +153,10 @@ class ThemeSceneController implements SetupSceneController {
 			"",
 		];
 		if (this.#loadingAllThemes) {
+			this.#listRowStart = -1;
 			lines.push(theme.fg("dim", "Loading themes…"));
 		} else {
+			this.#listRowStart = lines.length;
 			lines.push(...this.#selectList.render(width));
 		}
 		if (this.#message) {

package/src/modes/setup-wizard/scenes/types.ts

@@ -1,4 +1,4 @@
-import type { Component } from "@prometheus-ai/tui";
+import type { Component, SgrMouseEvent } from "@prometheus-ai/tui";
 import type { InteractiveModeContext } from "../../types";
 
 export type SetupSceneResult = "done" | "skipped";
@@ -17,6 +17,13 @@ export interface SetupSceneController extends Component {
 	onMount?(): void | Promise<void>;
 	onUnmount?(): void;
 	dispose?(): void;
+	/**
+	 * Route an SGR mouse report (tracking is on while the wizard holds the
+	 * alternate screen). `line`/`col` are 0-based within this controller's
+	 * last rendered output. When absent, the wizard falls back to synthesizing
+	 * arrow keys from wheel notches.
+	 */
+	routeMouse?(event: SgrMouseEvent, line: number, col: number): void;
 }
 
 /**
@@ -31,11 +38,13 @@ export interface SetupTab {
 	 * login). The parent scene MUST NOT switch tabs or finish while modal.
 	 */
 	readonly modal: boolean;
-	render(width: number): string[];
+	render(width: number): readonly string[];
 	handleInput(data: string): void;
 	invalidate(): void;
 	/** Called when the tab becomes active (including initial mount). */
 	onActivate?(): void;
+	/** Mouse routing at tab-local coordinates; see {@link SetupSceneController.routeMouse}. */
+	routeMouse?(event: SgrMouseEvent, line: number, col: number): void;
 	dispose(): void;
 }
 

package/src/modes/setup-wizard/scenes/web-search.ts

@@ -1,4 +1,4 @@
-import { type SelectItem, SelectList, truncateToWidth } from "@prometheus-ai/tui";
+import { type SelectItem, SelectList, type SgrMouseEvent, truncateToWidth } from "@prometheus-ai/tui";
 import { SETTINGS_SCHEMA } from "../../../config/settings-schema";
 import { getSearchProvider, setPreferredSearchProvider } from "../../../web/search/provider";
 import { isSearchProviderPreference, type SearchProviderId } from "../../../web/search/types";
@@ -19,7 +19,8 @@ type Availability = "checking" | boolean;
 /**
  * "Web search" panel: picks the provider the web_search tool should prefer and
  * reports whether the highlighted provider is ready to use given current
- * credentials (env keys or OAuth sign-ins from the Sign in tab).
+ * credentials (env keys or OAuth sign-ins from the Sign in tab) or an
+ * unauthenticated fallback.
  */
 export class WebSearchTab implements SetupTab {
 	readonly id = "web-search";
@@ -30,6 +31,8 @@ export class WebSearchTab implements SetupTab {
 	#availability = new Map<SearchProviderId, Availability>();
 	#status: string[] = [];
 	#disposed = false;
+	/** Render line where the select list begins. */
+	#listRowStart = 0;
 
 	constructor(private readonly host: SetupSceneHost) {
 		this.#list = new SelectList(WEB_SEARCH_ITEMS, MAX_VISIBLE, getSelectListTheme());
@@ -54,6 +57,22 @@ export class WebSearchTab implements SetupTab {
 		this.#list.handleInput(data);
 	}
 
+	/** Wheel moves the highlight; hover lights the row under the pointer; click confirms it. */
+	routeMouse(event: SgrMouseEvent, line: number, _col: number): void {
+		if (event.wheel !== null) {
+			this.#list.handleWheel(event.wheel);
+			return;
+		}
+		const index = this.#list.hitTest(line - this.#listRowStart);
+		if (event.motion) {
+			this.#list.setHoverIndex(index ?? null);
+			return;
+		}
+		if (event.leftClick && index !== undefined) {
+			this.#list.clickItem(index);
+		}
+	}
+
 	invalidate(): void {
 		this.#list.invalidate();
 	}
@@ -62,12 +81,10 @@ export class WebSearchTab implements SetupTab {
 		this.#disposed = true;
 	}
 
-	render(width: number): string[] {
-		const lines = [
-			theme.fg("muted", "Choose the provider the web_search tool should prefer."),
-			"",
-			...this.#list.render(width),
-		];
+	render(width: number): readonly string[] {
+		const lines = [theme.fg("muted", "Choose the provider the web_search tool should prefer."), ""];
+		this.#listRowStart = lines.length;
+		lines.push(...this.#list.render(width));
 		const selected = this.#list.getSelectedItem();
 		if (selected) {
 			lines.push("", ...this.#readinessLines(selected.value).map(line => truncateToWidth(line, width)));
@@ -91,7 +108,7 @@ export class WebSearchTab implements SetupTab {
 			let ready = false;
 			try {
 				const provider = await getSearchProvider(id);
-				ready = await provider.isAvailable(this.host.ctx.session.modelRegistry.authStorage);
+				ready = await provider.isExplicitlyAvailable(this.host.ctx.session.modelRegistry.authStorage);
 			} catch {
 				ready = false;
 			}