@oh-my-pi/pi-coding-agent 15.10.10 → 15.10.12

package/src/modes/rpc/rpc-mode.ts

@@ -21,9 +21,11 @@ import {
 } from "../../extensibility/extensions";
 import { type Theme, theme } from "../../modes/theme/theme";
 import type { AgentSession } from "../../session/agent-session";
+import type { EventBus } from "../../utils/event-bus";
 import { initializeExtensions } from "../runtime-init";
 import { isRpcHostToolResult, isRpcHostToolUpdate, RpcHostToolBridge } from "./host-tools";
 import { isRpcHostUriResult, RpcHostUriBridge } from "./host-uris";
+import { RpcSubagentRegistry, readRpcSubagentTranscript } from "./rpc-subagents";
 import type {
 	RpcCommand,
 	RpcExtensionUIRequest,
@@ -35,6 +37,7 @@ import type {
 	RpcHostUriRequest,
 	RpcResponse,
 	RpcSessionState,
+	RpcSubagentSubscriptionLevel,
 } from "./rpc-types";
 
 // Re-export types for consumers
@@ -56,6 +59,47 @@ type RpcOutput = (
 		| object,
 ) => void;
 
+export type RpcSessionChangeCommand = Extract<
+	RpcCommand,
+	{ type: "new_session" } | { type: "switch_session" } | { type: "branch" }
+>;
+
+export type RpcSessionChangeResult =
+	| { type: "new_session"; data: { cancelled: boolean } }
+	| { type: "switch_session"; data: { cancelled: boolean } }
+	| { type: "branch"; data: { text: string; cancelled: boolean } };
+
+export type RpcSessionChangeSession = Pick<AgentSession, "newSession" | "switchSession" | "branch">;
+export type RpcSubagentResetRegistry = Pick<RpcSubagentRegistry, "clear">;
+
+export async function handleRpcSessionChange(
+	session: RpcSessionChangeSession,
+	command: RpcSessionChangeCommand,
+	subagentRegistry?: RpcSubagentResetRegistry,
+): Promise<RpcSessionChangeResult> {
+	switch (command.type) {
+		case "new_session": {
+			const options = command.parentSession ? { parentSession: command.parentSession } : undefined;
+			const cancelled = !(await session.newSession(options));
+			if (!cancelled) subagentRegistry?.clear();
+			return { type: "new_session", data: { cancelled } };
+		}
+
+		case "switch_session": {
+			const cancelled = !(await session.switchSession(command.sessionPath));
+			if (!cancelled) subagentRegistry?.clear();
+			return { type: "switch_session", data: { cancelled } };
+		}
+
+		case "branch": {
+			const result = await session.branch(command.entryId);
+			if (!result.cancelled) subagentRegistry?.clear();
+			return { type: "branch", data: { text: result.selectedText, cancelled: result.cancelled } };
+		}
+	}
+	throw new Error("Unsupported RPC session change command");
+}
+
 function normalizeHostToolDefinitions(tools: RpcHostToolDefinition[]): RpcHostToolDefinition[] {
 	return tools.map((tool, index) => {
 		const name = typeof tool.name === "string" ? tool.name.trim() : "";
@@ -99,6 +143,10 @@ function shouldEmitRpcTitles(): boolean {
 	return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
 
+function isSubagentSubscriptionLevel(value: unknown): value is RpcSubagentSubscriptionLevel {
+	return value === "off" || value === "progress" || value === "events";
+}
+
 export function requestRpcEditor(
 	pendingRequests: Map<string, PendingExtensionRequest>,
 	output: RpcOutput,
@@ -169,6 +217,7 @@ export function requestRpcEditor(
 export async function runRpcMode(
 	session: AgentSession,
 	setToolUIContext?: (uiContext: ExtensionUIContext, hasUI: boolean) => void,
+	eventBus?: EventBus,
 ): Promise<never> {
 	// Signal to RPC clients that the server is ready to accept commands
 	// Suppress terminal notifications: they write \x07 (BEL) or OSC sequences directly to
@@ -201,6 +250,7 @@ export async function runRpcMode(
 	const pendingExtensionRequests = new Map<string, PendingExtensionRequest>();
 	const hostToolBridge = new RpcHostToolBridge(output);
 	const hostUriBridge = new RpcHostUriBridge(output);
+	const subagentRegistry = eventBus ? new RpcSubagentRegistry(eventBus, output) : undefined;
 
 	// Shutdown request flag (wrapped in object to allow mutation with const)
 	const shutdownState = { requested: false };
@@ -507,9 +557,8 @@ export async function runRpcMode(
 			}
 
 			case "new_session": {
-				const options = command.parentSession ? { parentSession: command.parentSession } : undefined;
-				const cancelled = !(await session.newSession(options));
-				return success(id, "new_session", { cancelled });
+				const result = await handleRpcSessionChange(session, command, subagentRegistry);
+				return success(id, result.type, result.data);
 			}
 
 			// =================================================================
@@ -564,6 +613,44 @@ export async function runRpcMode(
 				}
 			}
 
+			case "set_subagent_subscription": {
+				if (!subagentRegistry) {
+					return error(id, "set_subagent_subscription", "Subagent event bus is unavailable");
+				}
+				if (!isSubagentSubscriptionLevel(command.level)) {
+					return error(
+						id,
+						"set_subagent_subscription",
+						`Invalid subagent subscription level: ${String(command.level)}`,
+					);
+				}
+				subagentRegistry.setSubscriptionLevel(command.level);
+				return success(id, "set_subagent_subscription", { level: subagentRegistry.getSubscriptionLevel() });
+			}
+
+			case "get_subagents": {
+				if (!subagentRegistry) {
+					return error(id, "get_subagents", "Subagent event bus is unavailable");
+				}
+				return success(id, "get_subagents", { subagents: subagentRegistry.getSubagents() });
+			}
+
+			case "get_subagent_messages": {
+				if (!subagentRegistry) {
+					return error(id, "get_subagent_messages", "Subagent event bus is unavailable");
+				}
+				try {
+					if (command.fromByte !== undefined && !Number.isFinite(command.fromByte)) {
+						return error(id, "get_subagent_messages", "fromByte must be a finite number");
+					}
+					const sessionFile = subagentRegistry.resolveSessionFile(command);
+					const transcript = await readRpcSubagentTranscript(sessionFile, command.fromByte);
+					return success(id, "get_subagent_messages", transcript);
+				} catch (err) {
+					return error(id, "get_subagent_messages", err instanceof Error ? err.message : String(err));
+				}
+			}
+
 			// =================================================================
 			// Model
 			// =================================================================
@@ -683,14 +770,10 @@ export async function runRpcMode(
 				return success(id, "export_html", { path });
 			}
 
-			case "switch_session": {
-				const cancelled = !(await session.switchSession(command.sessionPath));
-				return success(id, "switch_session", { cancelled });
-			}
-
+			case "switch_session":
 			case "branch": {
-				const result = await session.branch(command.entryId);
-				return success(id, "branch", { text: result.selectedText, cancelled: result.cancelled });
+				const result = await handleRpcSessionChange(session, command, subagentRegistry);
+				return success(id, result.type, result.data);
 			}
 
 			case "get_branch_messages": {
@@ -850,13 +933,15 @@ export async function runRpcMode(
 
 			// Check for deferred shutdown request (idle between commands)
 			await checkShutdownRequested();
-		} catch (e: any) {
-			output(error(undefined, "parse", `Failed to parse command: ${e.message}`));
+		} catch (e: unknown) {
+			const message = e instanceof Error ? e.message : String(e);
+			output(error(undefined, "parse", `Failed to parse command: ${message}`));
 		}
 	}
 
 	// stdin closed — RPC client is gone, exit cleanly
 	hostToolBridge.rejectAllPending("RPC client disconnected before host tool execution completed");
 	hostUriBridge.clear("RPC client disconnected before host URI request completed");
+	subagentRegistry?.dispose();
 	process.exit(0);
 }

package/src/modes/rpc/rpc-subagents.ts

@@ -0,0 +1,265 @@
+import * as fs from "node:fs/promises";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import type { FileEntry, SessionMessageEntry } from "../../session/session-manager";
+import { parseSessionEntries } from "../../session/session-manager";
+import {
+	type AgentProgress,
+	type SubagentEventPayload,
+	type SubagentLifecyclePayload,
+	type SubagentProgressPayload,
+	TASK_SUBAGENT_EVENT_CHANNEL,
+	TASK_SUBAGENT_LIFECYCLE_CHANNEL,
+	TASK_SUBAGENT_PROGRESS_CHANNEL,
+} from "../../task";
+import type { EventBus } from "../../utils/event-bus";
+import type {
+	RpcSubagentEventFrame,
+	RpcSubagentFrame,
+	RpcSubagentMessagesResult,
+	RpcSubagentSnapshot,
+	RpcSubagentSubscriptionLevel,
+} from "./rpc-types";
+
+export interface RpcSubagentTranscriptSelector {
+	subagentId?: string;
+	sessionFile?: string;
+	fromByte?: number;
+}
+
+type RpcSubagentOutput = (frame: RpcSubagentFrame) => void;
+
+const MAX_RETAINED_TRANSCRIPT_REFERENCES = 256;
+
+function isSessionMessageEntry(entry: FileEntry): entry is SessionMessageEntry {
+	return entry.type === "message";
+}
+
+function statusFromLifecycle(status: SubagentLifecyclePayload["status"]): AgentProgress["status"] {
+	return status === "started" ? "running" : status;
+}
+
+function isTerminalLifecycleStatus(status: SubagentLifecyclePayload["status"]): boolean {
+	return status !== "started";
+}
+
+function hasSameOwner(
+	payload: Pick<SubagentLifecyclePayload | SubagentProgressPayload, "parentToolCallId" | "sessionFile">,
+	snapshot: RpcSubagentSnapshot,
+): boolean {
+	if (payload.parentToolCallId !== undefined && snapshot.parentToolCallId !== undefined) {
+		return payload.parentToolCallId === snapshot.parentToolCallId;
+	}
+	if (payload.sessionFile !== undefined && snapshot.sessionFile !== undefined) {
+		return payload.sessionFile === snapshot.sessionFile;
+	}
+	return true;
+}
+
+function addPruned(set: Set<string>, value: string, maxSize: number): void {
+	set.delete(value);
+	set.add(value);
+	while (set.size > maxSize) {
+		const oldest = set.keys().next();
+		if (oldest.done) break;
+		set.delete(oldest.value);
+	}
+}
+
+export async function readRpcSubagentTranscript(sessionFile: string, fromByte = 0): Promise<RpcSubagentMessagesResult> {
+	let startByte = Number.isFinite(fromByte) ? Math.max(0, Math.trunc(fromByte)) : 0;
+	const file = Bun.file(sessionFile);
+	let size: number;
+	try {
+		({ size } = await fs.stat(sessionFile));
+	} catch (err) {
+		if (!isEnoent(err)) throw err;
+		return {
+			sessionFile,
+			fromByte: startByte,
+			nextByte: startByte,
+			reset: false,
+			entries: [],
+			messages: [],
+		};
+	}
+	let reset = false;
+	if (startByte > size) {
+		startByte = 0;
+		reset = true;
+	}
+
+	const text = startByte >= size ? "" : await file.slice(startByte).text();
+	const lastNewline = text.lastIndexOf("\n");
+	const completeText = lastNewline >= 0 ? text.slice(0, lastNewline + 1) : "";
+	const entries = completeText.length > 0 ? parseSessionEntries(completeText) : [];
+	const nextByte = startByte + Buffer.byteLength(completeText, "utf8");
+
+	return {
+		sessionFile,
+		fromByte: startByte,
+		nextByte,
+		reset,
+		entries,
+		messages: entries.filter(isSessionMessageEntry).map(entry => entry.message),
+	};
+}
+
+export class RpcSubagentRegistry {
+	#subagents = new Map<string, RpcSubagentSnapshot>();
+	#transcriptSessionFilesBySubagentId = new Map<string, string>();
+	#staleSubagentIds = new Set<string>();
+	#unsubscribers: Array<() => void> = [];
+	#output: RpcSubagentOutput;
+	#subscriptionLevel: RpcSubagentSubscriptionLevel = "off";
+
+	constructor(eventBus: EventBus, output: RpcSubagentOutput) {
+		this.#output = output;
+		this.#unsubscribers.push(
+			eventBus.on(TASK_SUBAGENT_LIFECYCLE_CHANNEL, data => {
+				this.handleLifecycle(data as SubagentLifecyclePayload);
+			}),
+			eventBus.on(TASK_SUBAGENT_PROGRESS_CHANNEL, data => {
+				this.handleProgress(data as SubagentProgressPayload);
+			}),
+			eventBus.on(TASK_SUBAGENT_EVENT_CHANNEL, data => {
+				this.handleEvent(data as SubagentEventPayload);
+			}),
+		);
+	}
+
+	dispose(): void {
+		for (const unsubscribe of this.#unsubscribers) unsubscribe();
+		this.#unsubscribers = [];
+		this.#subagents.clear();
+		this.#transcriptSessionFilesBySubagentId.clear();
+		this.#staleSubagentIds.clear();
+	}
+
+	clear(): void {
+		for (const subagentId of this.#subagents.keys()) {
+			addPruned(this.#staleSubagentIds, subagentId, MAX_RETAINED_TRANSCRIPT_REFERENCES);
+		}
+		for (const subagentId of this.#transcriptSessionFilesBySubagentId.keys()) {
+			addPruned(this.#staleSubagentIds, subagentId, MAX_RETAINED_TRANSCRIPT_REFERENCES);
+		}
+		this.#subagents.clear();
+		this.#transcriptSessionFilesBySubagentId.clear();
+	}
+
+	setSubscriptionLevel(level: RpcSubagentSubscriptionLevel): void {
+		this.#subscriptionLevel = level;
+	}
+
+	getSubscriptionLevel(): RpcSubagentSubscriptionLevel {
+		return this.#subscriptionLevel;
+	}
+
+	getSubagents(): RpcSubagentSnapshot[] {
+		return [...this.#subagents.values()].sort((a, b) => a.index - b.index || a.id.localeCompare(b.id));
+	}
+
+	#rememberTranscriptSession(subagentId: string, sessionFile: string | undefined): void {
+		if (!sessionFile) return;
+		this.#transcriptSessionFilesBySubagentId.delete(subagentId);
+		this.#transcriptSessionFilesBySubagentId.set(subagentId, sessionFile);
+		while (this.#transcriptSessionFilesBySubagentId.size > MAX_RETAINED_TRANSCRIPT_REFERENCES) {
+			const oldest = this.#transcriptSessionFilesBySubagentId.keys().next();
+			if (oldest.done) break;
+			this.#transcriptSessionFilesBySubagentId.delete(oldest.value);
+		}
+	}
+
+	#hasTranscriptSessionFile(sessionFile: string): boolean {
+		for (const snapshot of this.#subagents.values()) {
+			if (snapshot.sessionFile === sessionFile) return true;
+		}
+		for (const transcriptSessionFile of this.#transcriptSessionFilesBySubagentId.values()) {
+			if (transcriptSessionFile === sessionFile) return true;
+		}
+		return false;
+	}
+
+	handleLifecycle(payload: SubagentLifecyclePayload): void {
+		const existing = this.#subagents.get(payload.id);
+		if (existing && !hasSameOwner(payload, existing)) return;
+		if (!existing && payload.status !== "started") return;
+		if (payload.status === "started") {
+			this.#staleSubagentIds.delete(payload.id);
+		}
+		const sessionFile = payload.sessionFile ?? existing?.sessionFile;
+		const snapshot: RpcSubagentSnapshot = {
+			id: payload.id,
+			index: payload.index,
+			agent: payload.agent,
+			agentSource: payload.agentSource,
+			description: payload.description ?? existing?.description,
+			status: statusFromLifecycle(payload.status),
+			task: existing?.task,
+			assignment: existing?.assignment,
+			sessionFile,
+			parentToolCallId: payload.parentToolCallId ?? existing?.parentToolCallId,
+			lastUpdate: Date.now(),
+			progress: existing?.progress,
+		};
+		this.#rememberTranscriptSession(payload.id, sessionFile);
+		if (isTerminalLifecycleStatus(payload.status)) {
+			this.#subagents.delete(payload.id);
+		} else {
+			this.#subagents.set(payload.id, snapshot);
+		}
+		if (this.#subscriptionLevel !== "off") {
+			this.#output({ type: "subagent_lifecycle", payload });
+		}
+	}
+
+	handleProgress(payload: SubagentProgressPayload): void {
+		const progress = payload.progress;
+		if (this.#staleSubagentIds.has(progress.id)) return;
+		const existing = this.#subagents.get(progress.id);
+		if (!existing) return;
+		if (!hasSameOwner(payload, existing)) return;
+		const sessionFile = payload.sessionFile ?? existing?.sessionFile;
+		this.#rememberTranscriptSession(progress.id, sessionFile);
+		this.#subagents.set(progress.id, {
+			id: progress.id,
+			index: payload.index,
+			agent: payload.agent,
+			agentSource: payload.agentSource,
+			description: progress.description ?? existing?.description,
+			status: progress.status,
+			task: payload.task,
+			assignment: payload.assignment,
+			sessionFile,
+			lastUpdate: Date.now(),
+			parentToolCallId: payload.parentToolCallId ?? existing?.parentToolCallId,
+			progress,
+		});
+		if (this.#subscriptionLevel !== "off") {
+			this.#output({ type: "subagent_progress", payload });
+		}
+	}
+
+	handleEvent(payload: SubagentEventPayload): void {
+		if (this.#staleSubagentIds.has(payload.id)) return;
+		if (this.#subscriptionLevel !== "events") return;
+		this.#output({ type: "subagent_event", payload } satisfies RpcSubagentEventFrame);
+	}
+
+	resolveSessionFile(selector: RpcSubagentTranscriptSelector): string {
+		if (selector.subagentId) {
+			const snapshot = this.#subagents.get(selector.subagentId);
+			const sessionFile = snapshot?.sessionFile ?? this.#transcriptSessionFilesBySubagentId.get(selector.subagentId);
+			if (!sessionFile) {
+				throw new Error(`Unknown subagent or session file unavailable: ${selector.subagentId}`);
+			}
+			return sessionFile;
+		}
+
+		if (selector.sessionFile) {
+			if (this.#hasTranscriptSessionFile(selector.sessionFile)) return selector.sessionFile;
+			throw new Error("Unknown subagent session file");
+		}
+
+		throw new Error("get_subagent_messages requires subagentId or sessionFile");
+	}
+}

package/src/modes/rpc/rpc-types.ts

@@ -9,7 +9,14 @@ import type { CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
 import type { Effort, ImageContent, Model } from "@oh-my-pi/pi-ai";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ContextUsage } from "../../extensibility/extensions/types";
-import type { SessionStats } from "../../session/agent-session";
+import type { AgentSessionEvent, SessionStats } from "../../session/agent-session";
+import type { FileEntry } from "../../session/session-manager";
+import type {
+	AgentProgress,
+	SubagentEventPayload,
+	SubagentLifecyclePayload,
+	SubagentProgressPayload,
+} from "../../task";
 import type { TodoPhase } from "../../tools/todo";
 
 // ============================================================================
@@ -30,6 +37,9 @@ export type RpcCommand =
 	| { id?: string; type: "set_todos"; phases: TodoPhase[] }
 	| { id?: string; type: "set_host_tools"; tools: RpcHostToolDefinition[] }
 	| { id?: string; type: "set_host_uri_schemes"; schemes: RpcHostUriSchemeDefinition[] }
+	| { id?: string; type: "set_subagent_subscription"; level: RpcSubagentSubscriptionLevel }
+	| { id?: string; type: "get_subagents" }
+	| { id?: string; type: "get_subagent_messages"; subagentId?: string; sessionFile?: string; fromByte?: number }
 
 	// Model
 	| { id?: string; type: "set_model"; provider: string; modelId: string }
@@ -104,6 +114,32 @@ export interface RpcHandoffResult {
 	savedPath?: string;
 }
 
+export type RpcSubagentSubscriptionLevel = "off" | "progress" | "events";
+
+export interface RpcSubagentSnapshot {
+	id: string;
+	index: number;
+	agent: string;
+	agentSource: AgentProgress["agentSource"];
+	description?: string;
+	status: AgentProgress["status"];
+	task?: string;
+	assignment?: string;
+	sessionFile?: string;
+	lastUpdate: number;
+	progress?: AgentProgress;
+	parentToolCallId?: string;
+}
+
+export interface RpcSubagentMessagesResult {
+	sessionFile: string;
+	fromByte: number;
+	nextByte: number;
+	reset: boolean;
+	entries: FileEntry[];
+	messages: AgentMessage[];
+}
+
 // ============================================================================
 // RPC Responses (stdout)
 // ============================================================================
@@ -123,6 +159,27 @@ export type RpcResponse =
 	| { id?: string; type: "response"; command: "set_todos"; success: true; data: { todoPhases: TodoPhase[] } }
 	| { id?: string; type: "response"; command: "set_host_tools"; success: true; data: { toolNames: string[] } }
 	| { id?: string; type: "response"; command: "set_host_uri_schemes"; success: true; data: { schemes: string[] } }
+	| {
+			id?: string;
+			type: "response";
+			command: "set_subagent_subscription";
+			success: true;
+			data: { level: RpcSubagentSubscriptionLevel };
+	  }
+	| {
+			id?: string;
+			type: "response";
+			command: "get_subagents";
+			success: true;
+			data: { subagents: RpcSubagentSnapshot[] };
+	  }
+	| {
+			id?: string;
+			type: "response";
+			command: "get_subagent_messages";
+			success: true;
+			data: RpcSubagentMessagesResult;
+	  }
 
 	// Model
 	| {
@@ -212,6 +269,29 @@ export type RpcResponse =
 	// Error response (any command can fail)
 	| { id?: string; type: "response"; command: string; success: false; error: string };
 
+// ============================================================================
+// Subagent Events (stdout)
+// ============================================================================
+
+export interface RpcSubagentLifecycleFrame {
+	type: "subagent_lifecycle";
+	payload: SubagentLifecyclePayload;
+}
+
+export interface RpcSubagentProgressFrame {
+	type: "subagent_progress";
+	payload: SubagentProgressPayload;
+}
+
+export interface RpcSubagentEventFrame {
+	type: "subagent_event";
+	payload: SubagentEventPayload;
+}
+
+export type RpcSubagentFrame = RpcSubagentLifecycleFrame | RpcSubagentProgressFrame | RpcSubagentEventFrame;
+
+export type RpcSessionEventFrame = AgentSessionEvent | RpcSubagentFrame;
+
 // ============================================================================
 // Extension UI Events (stdout)
 // ============================================================================

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

@@ -65,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);
@@ -79,11 +85,15 @@ export async function runSetupWizard(
 	});
 	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

@@ -60,7 +60,7 @@ class GlyphSceneController implements SetupSceneController {
 		this.#selectList.handleInput(data);
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		return [
 			theme.fg("muted", "If a row shows boxes, tofu, or misaligned icons, pick another."),
 			"",

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

@@ -52,7 +52,7 @@ class ProvidersSceneController implements SetupSceneController {
 		tab.handleInput(data);
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		return [...this.#tabBar.render(width), "", ...this.#activeTab().render(width)];
 	}
 

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

@@ -68,7 +68,7 @@ export class SignInTab implements SetupTab {
 		this.#selector.handleInput(data);
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		const lines: string[] = [];
 		if (this.#loggingInProvider) {
 			lines.push(theme.bold(`Signing in to ${this.#loggingInProvider}`));

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

@@ -117,7 +117,7 @@ class ThemeSceneController implements SetupSceneController {
 		this.#selectList.handleInput(data);
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		const lines = [
 			theme.fg("muted", "Theme changes preview live. Nothing is saved until you press Enter."),
 			this.#mode === "all"

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

@@ -31,7 +31,7 @@ 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). */

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

@@ -63,7 +63,7 @@ export class WebSearchTab implements SetupTab {
 		this.#disposed = true;
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		const lines = [
 			theme.fg("muted", "Choose the provider the web_search tool should prefer."),
 			"",

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

@@ -116,7 +116,7 @@ export class SetupWizardComponent implements Component {
 		this.#activeScene?.handleInput?.(data);
 	}
 
-	render(width: number): string[] {
+	render(width: number): readonly string[] {
 		const safeWidth = Math.max(1, width);
 		const height = Math.max(1, this.ctx.ui.terminal.rows);
 		let lines: string[];