@xzzpig/pi-starline 0.5.1 → 0.7.1

package/extensions/starline/index.ts

@@ -11,42 +11,51 @@ import {
 	type ExtensionStatusColorMode,
 	type ExtensionStatusPlacement,
 	ensureConfigExists,
-	type FooterSegmentsConfig,
 	type GitBranchConfig,
 	type IconMode,
 	loadConfig,
 	type MouseConfig,
 	type PathDisplayConfig,
 	type PolishedTuiConfig,
-	type SeparatorStyle,
 	saveColorSourcesPatch,
 	saveContextStylePatch,
 	saveExtensionStatusColorMode,
 	saveExtensionStatusPlacement,
-	saveFooterFormatPatch,
-	saveFooterSegmentsPatch,
 	saveGitBranchPatch,
 	saveIconsModePatch,
 	saveMousePatch,
 	savePathDisplayPatch,
-	saveSeparatorPatch,
+	savePillSegmentsPatch,
 	saveUiFeaturesPatch,
 	type UiFeaturesConfig,
 } from "./config";
+import { setActiveContextSnapshot } from "./context-live";
 import {
 	getStarlineEditorBaseFactory,
 	isStarlineEditorFactory,
 	markEditorFactory,
 } from "./editor-factory-marker";
 import { installFooter } from "./footer";
-import { buildSessionDurationLabel, invalidateUsageTotalsCache } from "./format";
-import { emptyGitStatus, readGitHost, readGitStatus } from "./git";
+import {
+	buildSessionDurationLabel,
+	compactionFailureNotice,
+	invalidateUsageTotalsCache,
+	resolveSessionStartEpoch,
+} from "./format";
+import { emptyGitStatus } from "./git";
+import { setActiveGitStatus } from "./git-live";
 import { LiveContextController } from "./live-context";
+import { forgetLiveSession, installLiveSessionCapture } from "./live-session";
+import { LiveTpsController } from "./live-tps";
 import { installMouseFeaturesOn } from "./mouse";
 import { getMouseEventsApi } from "./mouse/api-consumer";
 import { setActiveEditor } from "./mouse/editor-mouse";
-import { readPackageVersionResult } from "./package-version";
+import { installSharedPillMouse } from "./mouse/fork-pill-mouse";
 import { installPasteCollapse } from "./paste-collapse";
+import { setModelSwitcher } from "./pill-actions";
+import { publishPillApi } from "./pill-api";
+import { setPillBubbleAnimation } from "./pill-bubble";
+import { probeProject } from "./project-probe";
 import {
 	createProjectRefreshScheduler,
 	type ScheduleProjectRefreshOptions,
@@ -54,13 +63,22 @@ import {
 	startProjectRefreshInterval,
 } from "./project-refresh";
 import { applyProjectRefreshToState } from "./project-state";
-import { readRuntimeInfo } from "./runtime";
+import { installNativeQueueRowHiding } from "./queue-rows";
 import { installSelectorBorderStyle } from "./selector-border";
 import { SessionLifecycle } from "./session-lifecycle";
 import { registerStarlineSettingsCommand } from "./settings-command";
 import { createInitialState, type FooterState, syncState } from "./state";
+import {
+	createSubagentFleet,
+	type EventBusLike,
+	getActiveSubagentFleet,
+	SUBAGENT_TOOL_NAME,
+	setActiveSubagentFleet,
+} from "./subagent-fleet";
+import { TurnClock } from "./turn-clock";
 import { PolishedEditor, WrappedPolishedEditor } from "./ui";
 import { installUserMessageStyle } from "./user-message";
+import { setWorkingIndicator } from "./working-indicator";
 
 type EditorFactory = NonNullable<Parameters<ExtensionContext["ui"]["setEditorComponent"]>[0]>;
 
@@ -79,8 +97,21 @@ function isTuiContext(ctx: ExtensionContext): boolean {
 	}
 }
 
+/**
+ * How long a pill's bubble takes to unfold from the pill: long enough to read as
+ * growing out of it, short enough never to be waited on.
+ */
+const BUBBLE_ANIMATION_MS = 60;
+
 export default function (pi: ExtensionAPI) {
+	// Published before anything else so a bridge that registers in `session_start`
+	// finds it, whichever order the extensions were loaded in.
+	publishPillApi();
+
 	const state: FooterState = createInitialState(emptyGitStatus());
+	// The git pill's bubble reads the same object the footer draws from, so a
+	// click costs no extra \`git status\`.
+	setActiveGitStatus(state);
 	const sessionLifecycle = new SessionLifecycle();
 
 	let currentConfig: PolishedTuiConfig = loadConfig();
@@ -101,13 +132,29 @@ export default function (pi: ExtensionAPI) {
 	let disposePasteCollapse: (() => void) | undefined;
 	let disposeMouse: (() => void) | undefined;
 	let lastTuiCtx: ExtensionContext | undefined;
+	let cleanupSessionCapture: (() => void) | undefined;
+	let cleanupQueueRows: (() => void) | undefined;
 
 	const refresh = () => {
 		if (sessionLifecycle.isCurrent()) requestFooterRender?.();
 	};
 	const liveContext = new LiveContextController(sessionLifecycle, refresh);
+	const liveTps = new LiveTpsController();
+	const turnClock = new TurnClock();
 	const getActiveTheme = () => activeTheme;
 	const getCurrentConfig = () => currentConfig;
+	/**
+	 * The session's own header, or nothing. Read through a guard because this runs on
+	 * whatever `sessionManager` the running Pi build provides — the header is where a
+	 * resumed session keeps its original start time.
+	 */
+	const readSessionHeader = (ctx: ExtensionContext): { timestamp?: string } | undefined => {
+		try {
+			return ctx.sessionManager.getHeader() ?? undefined;
+		} catch {
+			return undefined;
+		}
+	};
 	const getThinkingLevel = () =>
 		sessionLifecycle.isCurrent() ? pi.getThinkingLevel() : ("off" as const);
 	const syncFooterState = (ctx: ExtensionContext) =>
@@ -122,39 +169,15 @@ export default function (pi: ExtensionAPI) {
 	type ProjectRefreshTarget = { cwd: string; generation: number };
 	const refreshProjectState = async ({ cwd, generation }: ProjectRefreshTarget) => {
 		if (!sessionLifecycle.isCurrent(generation)) return;
-		const gitCommitConfig = currentConfig.gitCommit;
-		const gitMetricsConfig = currentConfig.gitMetrics;
-		const segments = currentConfig.footerSegments;
-		const fmt = currentConfig.footerFormat;
-		// Enable optional probes when the segment is on OR a custom footerFormat
-		// references the relevant variable. Mirrors the session-duration timer
-		// pattern so format-only users still get data.
-		const formatNeedsTag = /\$\{?(?:git_tag|tag)\b/.test(fmt);
-		const formatNeedsCommit = /\$\{?(?:git_commit|commit)\b/.test(fmt);
-		const formatNeedsMetrics = /\$\{?(?:git_metrics|git_added|git_deleted)\b/.test(fmt);
-		const formatNeedsPackage = /\$\{?(?:package|package_version)\b/.test(fmt);
-		const wantExactTag =
-			((segments.gitCommit || formatNeedsCommit) && gitCommitConfig.showTag) || formatNeedsTag;
-		const wantMetrics = segments.gitMetrics || formatNeedsMetrics;
-		const wantPackage = segments.packageVersion || formatNeedsPackage;
-		const [git, runtime, packageVersion, gitHost] = await Promise.all([
-			readGitStatus(cwd, {
-				readExactTag: wantExactTag,
-				readMetrics: wantMetrics,
-				ignoreSubmodules: gitMetricsConfig.ignoreSubmodules,
-			}),
-			readRuntimeInfo(cwd),
-			wantPackage ? readPackageVersionResult(cwd) : Promise.resolve(undefined),
-			currentConfig.gitHostIcon ? readGitHost(cwd) : Promise.resolve(undefined),
-		]);
+		// A bar with no git pill reads no git: `probeProject` answers an empty
+		// status rather than starting `git status` and `git stash list` every
+		// interval.
+		const probe = await probeProject(cwd, currentConfig);
 		if (!sessionLifecycle.isCurrent(generation)) return;
 		lastProjectCwd = applyProjectRefreshToState(state, {
 			cwd,
 			previousCwd: lastProjectCwd,
-			git,
-			gitHost,
-			runtime,
-			packageVersion,
+			...probe,
 		});
 	};
 
@@ -187,18 +210,11 @@ export default function (pi: ExtensionAPI) {
 		lastDurationLabel = "";
 		const timer = setInterval(() => {
 			if (!sessionLifecycle.isCurrent()) return;
-			const segments = currentConfig.footerSegments;
-			const formatNeedsTimer =
-				currentConfig.footerFormat &&
-				/\$\{?(?:time|session_duration|duration)\b/.test(currentConfig.footerFormat);
-			if (
-				!(
-					currentConfig.features.statusLine &&
-					(segments.sessionDuration || segments.time || formatNeedsTimer)
-				)
-			)
+			const shown = currentConfig.pill.segments;
+			const wantsTime = shown.includes("time");
+			if (!(currentConfig.features.statusLine && (wantsTime || shown.includes("sessionDuration"))))
 				return;
-			if (segments.time || formatNeedsTimer) {
+			if (wantsTime) {
 				refresh();
 				return;
 			}
@@ -237,6 +253,73 @@ export default function (pi: ExtensionAPI) {
 		disposeMouse = undefined;
 	};
 
+	/**
+	 * Capture the live `AgentSession` so the queue bubble can list what is waiting.
+	 * The context only carries a boolean; the messages are on the session, and one
+	 * wrapper on its `prompt` is enough to hold the instance. See `live-session.ts`.
+	 */
+	const installSessionCapture = () => {
+		cleanupSessionCapture?.();
+		cleanupSessionCapture = installLiveSessionCapture();
+	};
+
+	const uninstallSessionCapture = () => {
+		cleanupSessionCapture?.();
+		cleanupSessionCapture = undefined;
+		forgetLiveSession();
+	};
+
+	/**
+	 * Pi's own `Steering:` rows above the editor are the same information the queue
+	 * pill carries, so they are hidden exactly while the pill is on screen. The
+	 * predicate is read on every queue update, so `/starline` changes apply without
+	 * a restart.
+	 */
+	const queuePillCarriesTheQueue = () =>
+		currentConfig.features.statusLine && currentConfig.pill.segments.includes("queue");
+
+	const installQueueRowHiding = () => {
+		cleanupQueueRows?.();
+		cleanupQueueRows = installNativeQueueRowHiding(queuePillCarriesTheQueue);
+	};
+
+	const uninstallQueueRowHiding = () => {
+		cleanupQueueRows?.();
+		cleanupQueueRows = undefined;
+	};
+
+	/**
+	 * Follow what pi-subagents is running, for the `subagents` pill. Its public RPC
+	 * answers on `pi.events`; without the package nothing answers and the pill
+	 * stays off. One request now picks up runs restored with the session.
+	 */
+	const installSubagentFleet = () => {
+		const bus = (pi as { events?: EventBusLike }).events;
+		if (!bus) return;
+		const fleet = createSubagentFleet(bus, { onChange: refresh });
+		setActiveSubagentFleet(fleet);
+		fleet.refresh();
+	};
+
+	/**
+	 * The model pill's picker switches through `pi`, which actions do not get.
+	 * A scoped model that pins a thinking level brings it along, as ctrl+p does.
+	 */
+	const installModelSwitcher = () => {
+		setModelSwitcher(async ({ model, thinkingLevel }) => {
+			const switched = await pi.setModel(model as Parameters<typeof pi.setModel>[0]);
+			if (switched && thinkingLevel) {
+				pi.setThinkingLevel(thinkingLevel as Parameters<typeof pi.setThinkingLevel>[0]);
+			}
+			return switched;
+		});
+	};
+
+	/** A foreground run starts with no event of its own, only the tool call. */
+	const refreshFleetForTool = (event: { toolName?: string }) => {
+		if (event.toolName === SUBAGENT_TOOL_NAME) getActiveSubagentFleet()?.refresh();
+	};
+
 	/**
 	 * Register Starline's mouse features with the `pi-mouse-events` extension.
 	 *
@@ -260,7 +343,12 @@ export default function (pi: ExtensionAPI) {
 			warnMouseApiMissing();
 			return;
 		}
-		disposeMouse = installMouseFeaturesOn(api, ctx, { getConfig: getCurrentConfig });
+		const disposeFeatures = installMouseFeaturesOn(api, ctx, { getConfig: getCurrentConfig });
+		const disposePillMouse = installSharedPillMouse(api);
+		disposeMouse = () => {
+			disposePillMouse();
+			disposeFeatures();
+		};
 	};
 
 	let mouseApiWarned = false;
@@ -309,22 +397,7 @@ export default function (pi: ExtensionAPI) {
 		const sessionTheme = ctx.ui.theme;
 		const factory = ((tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => {
 			syncHardwareCursor(tui);
-			const editor = new PolishedEditor(
-				tui,
-				theme,
-				keybindings,
-				sessionTheme,
-				getCurrentConfig,
-				() => ({
-					modelLabel: state.modelLabel,
-					modelId: state.modelId,
-					modelName: state.modelName,
-					providerLabel: state.providerLabel,
-					sessionName: ctx.sessionManager.getSessionName() ?? "",
-				}),
-				getThinkingLevel,
-				() => getActiveExtensionStatuses(),
-			);
+			const editor = new PolishedEditor(tui, theme, keybindings, sessionTheme, getCurrentConfig);
 			applyPasteCollapse(editor);
 			// Nothing on Pi's renderer points at the live editor, and the
 			// extension API hands out the factory rather than what it built — so
@@ -345,20 +418,7 @@ export default function (pi: ExtensionAPI) {
 			syncHardwareCursor(tui);
 			const base = baseFactory(tui, theme, keybindings);
 			applyPasteCollapse(base);
-			const wrapped = new WrappedPolishedEditor(
-				base,
-				sessionTheme,
-				getCurrentConfig,
-				() => ({
-					modelLabel: state.modelLabel,
-					modelId: state.modelId,
-					modelName: state.modelName,
-					providerLabel: state.providerLabel,
-					sessionName: ctx.sessionManager.getSessionName() ?? "",
-				}),
-				getThinkingLevel,
-				() => getActiveExtensionStatuses(),
-			);
+			const wrapped = new WrappedPolishedEditor(base, sessionTheme, getCurrentConfig);
 			// Two references, because these are two different objects here: the
 			// wrapper is what gets mounted and hit-tested, while the draft's
 			// visual lines live on the base editor it delegates to.
@@ -414,6 +474,10 @@ export default function (pi: ExtensionAPI) {
 		installedEditorFactory = undefined;
 		editorInstallMode = "none";
 		editorInstalled = false;
+		// Pi only clears the indicator it handed to the editor it is replacing, and
+		// this editor is on its way out; leaving the stale reference behind would
+		// keep a spinner in the footer forever.
+		setWorkingIndicator(undefined);
 		// Pi rebuilds the editor from whatever factory is now in place, and that
 		// one is not ours. Leaving the old instance registered would point the
 		// wheel patch at an editor no longer on screen.
@@ -432,6 +496,8 @@ export default function (pi: ExtensionAPI) {
 				getActiveExtensionStatuses = fn ?? (() => new Map());
 			},
 			getLiveContext: () => liveContext.get(),
+			getLiveTps: () => liveTps.value(),
+			getTurnTiming: () => turnClock.timing(),
 			getThinkingLevel,
 		});
 		footerInstalled = true;
@@ -484,6 +550,11 @@ export default function (pi: ExtensionAPI) {
 		currentConfig = loadConfig();
 		syncFooterState(ctx);
 		stopProjectRefresh();
+		installSessionCapture();
+		installQueueRowHiding();
+		installSubagentFleet();
+		installModelSwitcher();
+		setPillBubbleAnimation(currentConfig.pill.bubbleAnimation ? BUBBLE_ANIMATION_MS : 0);
 		applyConfiguredUi(ctx);
 		installMouseFeatures(ctx);
 		refresh();
@@ -505,7 +576,14 @@ export default function (pi: ExtensionAPI) {
 		sessionLifecycle.shutdown();
 		try {
 			uninstallMouse();
+			uninstallSessionCapture();
+			uninstallQueueRowHiding();
+			setActiveSubagentFleet(undefined);
+			setActiveGitStatus(undefined);
+			setActiveContextSnapshot(undefined);
+			setModelSwitcher(undefined);
 			uninstallPrototypePatches();
+			setWorkingIndicator(undefined);
 			stopSessionTimer();
 			stopProjectRefresh();
 			requestFooterRender = undefined;
@@ -544,7 +622,11 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
 		sessionLifecycle.start();
 		liveContext.clear();
-		state.sessionStartEpoch = Date.now();
+		liveTps.clear();
+		turnClock.clear();
+		// A resumed session keeps its original header, and reporting the moment this
+		// process attached to it would make the elapsed-time segment read 0s forever.
+		state.sessionStartEpoch = resolveSessionStartEpoch(readSessionHeader(ctx));
 		invalidateUsageTotalsCache();
 		lastProjectCwd = undefined;
 		installUi(ctx);
@@ -567,27 +649,21 @@ export default function (pi: ExtensionAPI) {
 					: undefined,
 			};
 		},
-		setFooterSegments(patch: Partial<FooterSegmentsConfig>) {
-			currentConfig = saveFooterSegmentsPatch(patch);
-		},
-		setFooterFormat(value: string) {
-			currentConfig = saveFooterFormatPatch(value);
-		},
 		setIconMode(mode: IconMode) {
 			currentConfig = saveIconsModePatch(mode);
 		},
 		setContextStyle(style: ContextStyle) {
 			currentConfig = saveContextStylePatch(style);
 		},
-		setSeparator(separator: SeparatorStyle) {
-			currentConfig = saveSeparatorPatch(separator);
-		},
 		setPathDisplay(patch: Partial<PathDisplayConfig>) {
 			currentConfig = savePathDisplayPatch(patch);
 		},
 		setGitBranch(patch: Partial<GitBranchConfig>) {
 			currentConfig = saveGitBranchPatch(patch);
 		},
+		setPillSegments(segments: readonly string[]) {
+			currentConfig = savePillSegmentsPatch(segments);
+		},
 		getActiveExtensionStatuses() {
 			return getActiveExtensionStatuses();
 		},
@@ -613,6 +689,8 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_shutdown", async (_event, ctx) => {
 		liveContext.clear();
+		liveTps.clear();
+		turnClock.clear();
 		cleanupUi(ctx);
 	});
 
@@ -623,10 +701,14 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("agent_start", (event, ctx) => {
 		liveContext.clear();
+		// The window resets per run; the value it already measured stays on the pill.
+		liveTps.beginTurn();
+		turnClock.begin();
 		syncInteractiveState(event, ctx);
 	});
 	pi.on("agent_end", (event, ctx) => {
 		liveContext.clear();
+		turnClock.end();
 		syncInteractiveAndProjectState(event, ctx);
 	});
 	pi.on("model_select", (event, ctx) => {
@@ -637,6 +719,7 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_info_changed", syncInteractiveState);
 	pi.on("message_update", (event) => {
 		liveContext.update(event.message);
+		if (liveTps.observe(event.assistantMessageEvent)) refresh();
 	});
 	pi.on("message_end", (event, ctx) => {
 		// Pi notifies extensions before persisting a successful message, so retain its live
@@ -646,18 +729,32 @@ export default function (pi: ExtensionAPI) {
 			(event.message.stopReason === "error" || event.message.stopReason === "aborted")
 		) {
 			liveContext.clear();
+		} else if (event.message.role === "assistant") {
+			// The stream's `done` event never reaches an extension, so the output count
+			// has to be closed here, where the finished message arrives with its usage.
+			liveTps.complete(event.message.usage?.output ?? 0);
 		}
 		syncInteractiveAndProjectStateWithUsage(event, ctx);
 	});
 	pi.on("tool_execution_start", (event, ctx) => {
 		liveContext.clear();
+		refreshFleetForTool(event);
 		syncInteractiveState(event, ctx);
 	});
-	pi.on("tool_execution_end", syncInteractiveAndProjectState);
+	pi.on("tool_execution_end", (event, ctx) => {
+		refreshFleetForTool(event);
+		syncInteractiveAndProjectState(event, ctx);
+	});
 	pi.on("session_compact", (event, ctx) => {
 		liveContext.clear();
 		syncInteractiveAndProjectStateWithUsage(event, ctx);
 	});
+	// Pi emits this and draws nothing for it: a failed compaction late in a long
+	// session otherwise looks like the agent forgetting the conversation.
+	pi.on("session_compact_failed", (event, ctx) => {
+		const notice = compactionFailureNotice(event);
+		if (notice) ctx.ui.notify(notice, "error");
+	});
 	pi.on("session_tree", (event, ctx) => {
 		liveContext.clear();
 		syncInteractiveAndProjectStateWithUsage(event, ctx);

package/extensions/starline/live-session.ts

@@ -0,0 +1,164 @@
+/**
+ * The live `AgentSession`, for the two things the extension context does not
+ * expose: the queued messages themselves, and the thinking-level switch.
+ *
+ * `ctx.hasPendingMessages()` is a boolean, but the data behind it is public on
+ * `AgentSession` (`pendingMessageCount`, `getSteeringMessages()`,
+ * `getFollowUpMessages()`), and so are the thinking-level getters and setters.
+ * What is missing is a reference to the instance — the extension context carries
+ * the session manager, not the session.
+ *
+ * So this captures the instance from any method the footer already reaches:
+ * `getContextUsage()` runs on every render, and `prompt()` covers a queue that
+ * existed before Starline loaded. Two wrappers, registered through the same
+ * prototype-patch registry the mouse layer uses, gone the moment the session
+ * ends. The upstream fix is a `pendingMessages` field on the extension context,
+ * at which point this file can be deleted.
+ */
+
+import { AgentSession } from "@earendil-works/pi-coding-agent";
+import { installPrototypePatch } from "./prototype-patch-registry";
+
+export type PendingMessages = {
+	steering: readonly string[];
+	followUp: readonly string[];
+};
+
+type QueuedMessageSource = {
+	getSteeringMessages?: () => unknown;
+	getFollowUpMessages?: () => unknown;
+	getAvailableThinkingLevels?: () => unknown;
+	setThinkingLevel?: (level: string) => unknown;
+	readonly thinkingLevel?: string;
+};
+
+let liveSession: QueuedMessageSource | undefined;
+
+/**
+ * Record the receiver of a patched method. Two methods are wrapped because the
+ * queue needs the session before the first prompt too, and the footer asks for
+ * context usage on every render.
+ */
+function captureVia(
+	method: "prompt" | "getContextUsage",
+	adapter: "agent-session-capture-prompt" | "agent-session-capture-usage",
+): () => void {
+	try {
+		return installPrototypePatch(
+			AgentSession.prototype,
+			method,
+			adapter,
+			({ predecessor, receiver, args }) => {
+				liveSession = receiver as QueuedMessageSource;
+				return Reflect.apply(predecessor, receiver, args);
+			},
+		);
+	} catch {
+		return () => {};
+	}
+}
+
+/**
+ * Wrap the two `AgentSession` methods that put the instance in hand. Returns a
+ * disposer; a Pi build without them simply captures nothing and
+ * `readPendingMessages()` stays undefined.
+ */
+export function installLiveSessionCapture(): () => void {
+	const disposers = [
+		captureVia("prompt", "agent-session-capture-prompt"),
+		captureVia("getContextUsage", "agent-session-capture-usage"),
+	];
+	return () => {
+		for (const dispose of disposers) dispose();
+		forgetLiveSession();
+	};
+}
+
+export function forgetLiveSession(): void {
+	liveSession = undefined;
+}
+
+/**
+ * What is queued right now: steering messages first, then follow-ups, the same
+ * order Pi hands them to the agent. Undefined when the session was never seen or
+ * this build does not expose the getters.
+ */
+export function readPendingMessages(): PendingMessages | undefined {
+	const session = liveSession;
+	if (!session) return undefined;
+	try {
+		const steering = session.getSteeringMessages?.();
+		const followUp = session.getFollowUpMessages?.();
+		if (!Array.isArray(steering) || !Array.isArray(followUp)) return undefined;
+		return {
+			steering: steering.filter((message): message is string => typeof message === "string"),
+			followUp: followUp.filter((message): message is string => typeof message === "string"),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+export type ThinkingCycle = { from: string; to: string };
+
+export type ThinkingLevels = {
+	/** Levels the model supports, in Pi's order, without "off". */
+	levels: string[];
+	/** The session's level now; "" when it does not say. */
+	current: string;
+};
+
+/**
+ * The levels the thinking pill can switch between.
+ *
+ * "off" is filtered out on purpose: the thinking pill only exists while thinking
+ * is on, so a choice that removes its own pill would be a surprise and leave no
+ * way back from the same place. Returns undefined when the session was never
+ * seen, cannot set the level, or the model has nothing to choose from.
+ */
+export function readThinkingLevels(): ThinkingLevels | undefined {
+	const session = liveSession;
+	if (!session) return undefined;
+	try {
+		const readLevels = session.getAvailableThinkingLevels;
+		if (typeof readLevels !== "function" || typeof session.setThinkingLevel !== "function") {
+			return undefined;
+		}
+		const levels = readLevels.call(session);
+		if (!Array.isArray(levels)) return undefined;
+		const usable = levels.filter(
+			(level): level is string => typeof level === "string" && level !== "off",
+		);
+		if (usable.length === 0) return undefined;
+		const current = typeof session.thinkingLevel === "string" ? session.thinkingLevel : "";
+		return { levels: usable, current };
+	} catch {
+		return undefined;
+	}
+}
+
+/** Switch the live session to `level`. False when it could not be done. */
+export function setThinkingLevel(level: string): boolean {
+	const session = liveSession;
+	const setLevel = session?.setThinkingLevel;
+	if (!session || typeof setLevel !== "function") return false;
+	try {
+		setLevel.call(session, level);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Step to the next level `readThinkingLevels` offers, wrapping around. This is
+ * the keyboard path; a click opens the list instead.
+ */
+export function cycleThinkingLevel(): ThinkingCycle | undefined {
+	const read = readThinkingLevels();
+	if (!read) return undefined;
+	const index = read.levels.indexOf(read.current);
+	const to = read.levels[(index + 1) % read.levels.length];
+	if (!to || !setThinkingLevel(to)) return undefined;
+	return { from: read.current || to, to };
+}