@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/interactive/overlays/skills-hub.ts

@@ -1,28 +1,74 @@
 import type {
+	LibraryDiscoveryResult,
+	LibraryEntry,
+	LibraryEntryKind,
+	LibraryInstallPlan,
+	LibraryRequirementStatus,
 	MarketplaceDiscoveryResult,
 	MarketplaceSkill,
 	ResourceList,
 	Skill,
 } from "../../domains/resources/index.js";
-import { discoverMarketplaceSkills, MARKETPLACE_UNCONFIGURED } from "../../domains/resources/index.js";
+import {
+	classifyLibraryRequirements,
+	discoverLibrary,
+	discoverMarketplaceSkills,
+	installLibraryPlan,
+	libraryEntryInstalled,
+	libraryEntryPin,
+	libraryEntryRef,
+	libraryInstallPath,
+	MARKETPLACE_UNCONFIGURED,
+	planLibraryInstall,
+} from "../../domains/resources/index.js";
 import type { OverlayHandle, TUI } from "../../engine/tui.js";
 import type { NoticeLevel } from "../command-output.js";
 import { clioTheme, GLYPH } from "../theme/index.js";
-import { type ListOverlayItem, openListOverlay } from "./list-overlay.js";
+import type { LibraryInstallConfirmSubject } from "./library-install-confirm.js";
+import { openLibraryInstallConfirmOverlay } from "./library-install-confirm.js";
+import { type ListOverlayItem, type ListOverlayTab, openListOverlay } from "./list-overlay.js";
 
 /**
- * The Skills Hub: one multipane surface for every skill Clio can reach.
- * Installed skills group by scope, marketplace rows come from the same local
- * marketplace lookup the installer and `/skill <name>` resolve through, Enter
- * inserts the invocation into the editor, and `i` installs in place. The hub
- * lists nothing the resolver cannot resolve; when the lookup is empty the hub
- * says so and names the remedy instead of drawing an inventory.
+ * The Skills Hub: one multipane surface for every resource Clio can reach.
+ *
+ * The Skills tab is the original view. Installed skills group by scope,
+ * marketplace rows come from the same local marketplace lookup the installer
+ * and `/skill <name>` resolve through, Enter inserts the invocation into the
+ * editor, and `i` installs in place. The hub lists nothing the resolver cannot
+ * resolve; when the lookup is empty the hub says so and names the remedy
+ * instead of drawing an inventory.
+ *
+ * The Agents, Prompts, and Fleets tabs are the interactive half of the resource
+ * library. Their rows come from the same `discoverLibrary()` the CLI's
+ * `library list --kind` reads, their install runs the same plan-then-write pair
+ * `library add` runs behind the same confirmation the `--yes` gate expresses,
+ * and their requirement gate is the same classifier. Nothing here reaches
+ * around the library domain into a private path.
  */
 
 const GROUP_PROJECT = "Project";
 const GROUP_USER = "User";
 const GROUP_MARKETPLACE = "Marketplace";
 const GROUP_DIAGNOSTICS = "Diagnostics";
+const GROUP_INSTALLED = "Installed";
+const GROUP_AVAILABLE = "Available";
+
+/** The hub's tabs, in the order ←/→ walks them. `skill` is the original view. */
+export const LIBRARY_TABS: ReadonlyArray<{ id: LibraryEntryKind; label: string }> = [
+	{ id: "skill", label: "Skills" },
+	{ id: "agent", label: "Agents" },
+	{ id: "prompt", label: "Prompts" },
+	{ id: "fleet", label: "Fleets" },
+];
+
+export const SKILLS_HUB_TITLE = "Skills Hub";
+
+/** Row id prefix for a library row, which is how an action tells the tabs apart. */
+export const LIBRARY_ROW_PREFIX = "library:";
+
+export function isLibraryTab(value: string): value is LibraryEntryKind {
+	return LIBRARY_TABS.some((tab) => tab.id === value);
+}
 
 /** @internal exported for contract tests */
 export const SKILLS_HUB_EMPTY =
@@ -37,6 +83,50 @@ export interface SkillsHubDeps {
 	onClose: () => void;
 	/** Injectable for tests; defaults to the local marketplace the installer uses. */
 	discoverMarketplace?: () => MarketplaceDiscoveryResult;
+	/** Tab the hub opens on. `/skills` opens on Skills, `/library <kind>` on that kind. */
+	initialTab?: LibraryEntryKind;
+	/** Injectable for tests; defaults to the discovery `library list` reads. */
+	discoverLibrary?: () => LibraryDiscoveryResult;
+	/** Injectable for tests; defaults to the classifier `library add` gates on. */
+	classifyRequirements?: (entry: LibraryEntry, catalog: ReadonlyArray<LibraryEntry>) => LibraryRequirementStatus;
+	/** Injectable for tests; defaults to the planner `library add` prints from. */
+	planInstall?: (entry: LibraryEntry) => LibraryInstallPlan;
+	/** Injectable for tests; defaults to the writer `library add --yes` runs. */
+	installPlan?: (plan: LibraryInstallPlan) => void;
+	/** Injectable for tests; defaults to the pin-and-destination check the domain owns. */
+	entryInstalled?: (entry: LibraryEntry) => boolean;
+	/** Injectable for tests; defaults to the recorded pin for this entry. */
+	entryPin?: (entry: LibraryEntry) => { sha256: string; sourceUrl: string } | undefined;
+	/**
+	 * The confirmation gate. Resolves true only when the operator accepted, and
+	 * nothing is written before it does. Defaults to the framed confirmation
+	 * overlay, which is the TUI spelling of `library add`'s `--yes`.
+	 */
+	confirmInstall?: (subject: LibraryInstallConfirmSubject) => Promise<boolean>;
+	/** Opens the `/fleet run` approval preview for an installed fleet. */
+	openFleetRun?: (name: string) => void;
+}
+
+/** Row and action context for one library tab, resolved once per rebuild. */
+interface LibraryTabContext {
+	discovery: LibraryDiscoveryResult;
+	installed: (entry: LibraryEntry) => boolean;
+	pin: (entry: LibraryEntry) => { sha256: string; sourceUrl: string } | undefined;
+	unresolved: (entry: LibraryEntry) => LibraryEntry[];
+}
+
+/**
+ * The composer text or the surface a `use` on this entry leads to.
+ *
+ * A fleet has no composer spelling because its `use` opens the `/fleet run`
+ * approval preview instead, so this returns null for one and the caller routes
+ * it there.
+ */
+export function libraryUseInvocation(entry: Pick<LibraryEntry, "kind" | "name">): string | null {
+	if (entry.kind === "fleet") return null;
+	if (entry.kind === "agent") return `/run ${entry.name} `;
+	if (entry.kind === "prompt") return `/${entry.name} `;
+	return `/skill ${entry.name} `;
 }
 
 function groupForScope(scope: string): string {
@@ -170,8 +260,159 @@ export function buildDiagnosticItems(
 	return items;
 }
 
+/** @internal exported for contract tests */
+export function libraryRowId(entry: Pick<LibraryEntry, "kind" | "name">): string {
+	return `${LIBRARY_ROW_PREFIX}${libraryEntryRef(entry)}`;
+}
+
+/**
+ * One kind's rows: the same columns the Skills tab shows where they apply, plus
+ * the requirements this entry still needs.
+ *
+ * The requires column carries the names rather than a count, because the names
+ * are what the refusal will say and what the second confirmation will install.
+ * It renders in the warning token: an entry with an unmet requirement is
+ * listable and readable but not installable on its own.
+ *
+ * @internal exported for contract tests
+ */
+export function buildLibraryItems(kind: LibraryEntryKind, context: LibraryTabContext): ListOverlayItem[] {
+	const theme = clioTheme();
+	return context.discovery.entries
+		.filter((entry) => entry.kind === kind)
+		.map((entry) => {
+			const installed = context.installed(entry);
+			const pin = context.pin(entry);
+			const unresolved = context.unresolved(entry).map(libraryEntryRef);
+			const metaParts: string[] = [entry.origin];
+			if (entry.version) metaParts.push(`v${entry.version}`);
+			metaParts.push(installed ? "installed" : "available");
+			metaParts.push(pin ? `pin ${pin.sha256.slice(0, 8)}` : "unpinned");
+			if (unresolved.length > 0) metaParts.push(theme.fg("warning", `requires ${unresolved.join(", ")}`));
+			return {
+				id: libraryRowId(entry),
+				label: entry.name,
+				meta: metaParts.join(" · "),
+				group: installed ? GROUP_INSTALLED : GROUP_AVAILABLE,
+				detail: () => {
+					const use = libraryUseInvocation(entry);
+					const lines = [
+						`# ${entry.name}`,
+						`**Kind:** ${entry.kind}`,
+						`**Use:** ${use === null ? "`Enter` opens the /fleet run approval preview" : `\`${use.trim()}\``}`,
+						`**State:** ${installed ? "installed" : "available"}${pin ? ` · pinned ${pin.sha256.slice(0, 12)}` : " · unpinned"}`,
+						`**Destination:** \`${libraryInstallPath(entry)}\``,
+						`**Source:** \`${entry.sourceUrl}\``,
+						`**Origin:** ${entry.origin}`,
+					];
+					if ((entry.requires ?? []).length > 0) {
+						lines.push(`**Requires:** ${(entry.requires ?? []).join(", ")}`);
+					}
+					if (unresolved.length > 0) {
+						lines.push(`**Unresolved:** ${unresolved.join(", ")}`, "", "Press `i` twice to install them with it.");
+					} else if (!installed) {
+						lines.push("", "**Install now:** press `i`");
+					}
+					lines.push("", "---", "", entry.description);
+					return lines;
+				},
+			};
+		});
+}
+
+/**
+ * Diagnostic rows for a library tab. `discoverLibrary` drops an entry whose
+ * requirements are missing, malformed, or cyclic and records why; a tab that
+ * silently omitted those would be the inventory this hub refuses to draw.
+ *
+ * @internal exported for contract tests
+ */
+export function buildLibraryDiagnosticItems(discovery: LibraryDiscoveryResult): ListOverlayItem[] {
+	const theme = clioTheme();
+	return discovery.diagnostics
+		.filter((message) => message !== MARKETPLACE_UNCONFIGURED)
+		.map((message, index) => ({
+			id: `library-diagnostic-${index}`,
+			label: `${theme.fg("warning", GLYPH.warnInline)} ${message}`,
+			meta: "library",
+			group: GROUP_DIAGNOSTICS,
+			detail: () => ["# Library diagnostic", `**Message:** ${message}`],
+		}));
+}
+
+/** What one attempted library install did, in the terms the hub reports it. */
+export type LibraryInstallOutcome =
+	| { status: "installed"; refs: string[] }
+	| { status: "cancelled" }
+	| { status: "refused"; unresolved: string[] }
+	| { status: "already-installed" }
+	| { status: "failed"; message: string };
+
+/** The library domain calls one install needs, resolved before it runs. */
+export interface LibraryInstallRunner {
+	discovery: LibraryDiscoveryResult;
+	classify: (entry: LibraryEntry, catalog: ReadonlyArray<LibraryEntry>) => LibraryRequirementStatus;
+	plan: (entry: LibraryEntry) => LibraryInstallPlan;
+	write: (plan: LibraryInstallPlan) => void;
+	installed: (entry: LibraryEntry) => boolean;
+	confirm: (subject: LibraryInstallConfirmSubject) => Promise<boolean>;
+}
+
+/**
+ * Install one library entry through the same sequence `library add` runs.
+ *
+ * The order is the CLI's order and the refusals are the CLI's refusals: an
+ * entry with an unmet requirement is refused by name and nothing is planned, a
+ * plan is built and shown before anything is written, and the writes happen
+ * only after the confirmation resolves true. A cancelled confirmation is a run
+ * in which no file changed.
+ *
+ * @internal exported for contract tests
+ */
+export async function runLibraryInstall(
+	entry: LibraryEntry,
+	runner: LibraryInstallRunner,
+	options: { withRequirements: boolean },
+): Promise<LibraryInstallOutcome> {
+	if (runner.installed(entry)) return { status: "already-installed" };
+	let requirements: LibraryRequirementStatus;
+	let plans: LibraryInstallPlan[];
+	try {
+		requirements = runner.classify(entry, runner.discovery.entries);
+		if (requirements.unsatisfied.length > 0 && !options.withRequirements) {
+			return { status: "refused", unresolved: requirements.unsatisfied.map(libraryEntryRef) };
+		}
+		plans = [...(options.withRequirements ? requirements.unsatisfied : []), entry].map(runner.plan);
+	} catch (error) {
+		return { status: "failed", message: error instanceof Error ? error.message : String(error) };
+	}
+	const accepted = await runner.confirm({
+		entryRef: libraryEntryRef(entry),
+		writes: plans.map((plan) => ({ ref: libraryEntryRef(plan.entry), path: plan.path, sha256: plan.sha256 })),
+		requirements: options.withRequirements ? requirements.unsatisfied.map(libraryEntryRef) : [],
+		satisfied: requirements.satisfied.map(libraryEntryRef),
+	});
+	if (!accepted) return { status: "cancelled" };
+	const written: string[] = [];
+	try {
+		for (const plan of plans) {
+			runner.write(plan);
+			written.push(libraryEntryRef(plan.entry));
+		}
+	} catch (error) {
+		return { status: "failed", message: error instanceof Error ? error.message : String(error) };
+	}
+	return { status: "installed", refs: written };
+}
+
 export function openSkillsHub(tui: TUI, deps: SkillsHubDeps): OverlayHandle {
 	const discoverMarketplace = deps.discoverMarketplace ?? (() => discoverMarketplaceSkills());
+	const readLibrary = deps.discoverLibrary ?? (() => discoverLibrary());
+	const classify = deps.classifyRequirements ?? classifyLibraryRequirements;
+	const plan = deps.planInstall ?? planLibraryInstall;
+	const write = deps.installPlan ?? installLibraryPlan;
+	const installed = deps.entryInstalled ?? libraryEntryInstalled;
+	const pin = deps.entryPin ?? libraryEntryPin;
 
 	// Rebuilt rather than mutated in place: the view memoizes its frame on the row
 	// set, so a spliced array leaves an installed skill drawn as installable.
@@ -186,27 +427,170 @@ export function openSkillsHub(tui: TUI, deps: SkillsHubDeps): OverlayHandle {
 		];
 	};
 
+	// One discovery pass feeds all three library tabs. The tab bar asks every tab
+	// for its rows on each rebuild, and four independent catalog reads per
+	// keystroke would be four answers to the same question.
+	let libraryCache: LibraryTabContext | null = null;
+	const libraryContext = (): LibraryTabContext => {
+		if (libraryCache) return libraryCache;
+		const discovery = readLibrary();
+		libraryCache = {
+			discovery,
+			installed,
+			pin,
+			unresolved: (entry) => {
+				try {
+					return classify(entry, discovery.entries).unsatisfied;
+				} catch {
+					// A requirement that will not resolve is already a diagnostic row on
+					// this tab; a row that cannot answer the question reports none rather
+					// than taking the whole rebuild down.
+					return [];
+				}
+			},
+		};
+		return libraryCache;
+	};
+	const invalidateLibrary = (): void => {
+		libraryCache = null;
+	};
+
+	const buildLibraryRows = (kind: LibraryEntryKind): ListOverlayItem[] => {
+		const context = libraryContext();
+		return [...buildLibraryItems(kind, context), ...buildLibraryDiagnosticItems(context.discovery)];
+	};
+
+	const entryForRow = (item: ListOverlayItem): LibraryEntry | undefined => {
+		if (!item.id.startsWith(LIBRARY_ROW_PREFIX)) return undefined;
+		const ref = item.id.slice(LIBRARY_ROW_PREFIX.length);
+		return libraryContext().discovery.entries.find((candidate) => libraryEntryRef(candidate) === ref);
+	};
+
+	const tabs: ListOverlayTab[] = LIBRARY_TABS.map((tab) => ({
+		id: tab.id,
+		label: tab.label,
+		items: tab.id === "skill" ? buildRows : () => buildLibraryRows(tab.id),
+	}));
+
 	let closed = false;
 	let installInFlight = false;
-	const handle = openListOverlay(tui, {
-		title: "Skills",
-		items: buildRows(),
+	/**
+	 * The row whose requirements were just refused. A second `i` on that row is
+	 * the install-with-requirements offer, so the refusal names what is missing
+	 * before any confirmation lists what would be written.
+	 */
+	let pendingWithRequirements: string | null = null;
+
+	const columns = (): number => (typeof process.stdout.columns === "number" ? process.stdout.columns : 100);
+
+	// eslint-disable-next-line prefer-const -- the confirmation closure needs the handle it is opened from.
+	let handle: ReturnType<typeof openListOverlay>;
+
+	const confirmInstall =
+		deps.confirmInstall ??
+		((subject: LibraryInstallConfirmSubject): Promise<boolean> =>
+			new Promise<boolean>((resolve) => {
+				handle.setHidden(true);
+				const settle = (accepted: boolean): void => {
+					if (!closed) {
+						handle.setHidden(false);
+						handle.focus();
+					}
+					resolve(accepted);
+				};
+				const confirmation = openLibraryInstallConfirmOverlay(tui, {
+					subject,
+					columns: columns(),
+					onAccept: () => {
+						settle(true);
+						confirmation.hide();
+					},
+					onCancel: () => {
+						settle(false);
+						confirmation.hide();
+					},
+				});
+			}));
+
+	const useEntry = (entry: LibraryEntry): void => {
+		if (!installed(entry)) {
+			deps.notice("warn", `${libraryEntryRef(entry)} is not installed; press i to install it`);
+			return;
+		}
+		if (entry.kind === "fleet") {
+			deps.openFleetRun?.(entry.name);
+			return;
+		}
+		const invocation = libraryUseInvocation(entry);
+		if (invocation === null) return;
+		deps.setEditorText(invocation);
+		deps.onClose();
+	};
+
+	const installEntry = (entry: LibraryEntry): void => {
+		const ref = libraryEntryRef(entry);
+		const withRequirements = pendingWithRequirements === ref;
+		installInFlight = true;
+		void (async () => {
+			const outcome = await runLibraryInstall(
+				entry,
+				{ discovery: libraryContext().discovery, classify, plan, write, installed, confirm: confirmInstall },
+				{ withRequirements },
+			);
+			installInFlight = false;
+			if (outcome.status === "refused") {
+				pendingWithRequirements = ref;
+				deps.notice("error", `${ref} needs ${outcome.unresolved.join(", ")}; press i again to install them with it`);
+				return;
+			}
+			pendingWithRequirements = null;
+			if (outcome.status === "already-installed") deps.notice("info", `${ref} is already installed`);
+			else if (outcome.status === "cancelled") deps.notice("info", `${ref}: cancelled; nothing was written`);
+			else if (outcome.status === "failed") deps.notice("error", `library install failed: ${outcome.message}`);
+			else deps.notice("success", `installed ${outcome.refs.join(", ")}`);
+			// An install that lands after the hub closed has nothing to redraw.
+			if (!closed && outcome.status === "installed") {
+				invalidateLibrary();
+				handle.refreshTabs();
+			}
+		})();
+	};
+
+	handle = openListOverlay(tui, {
+		title: SKILLS_HUB_TITLE,
+		items: [],
+		tabs,
+		...(deps.initialTab ? { activeTabId: deps.initialTab } : {}),
+		onTabChange: () => {
+			pendingWithRequirements = null;
+		},
 		filterable: true,
 		layout: "split",
 		emptyMessage: SKILLS_HUB_EMPTY,
 		hints: [
-			{ key: "Enter", verb: "invoke" },
+			{ key: "Enter", verb: "use" },
 			{ key: "i", verb: "install" },
 		],
 		onSelect: (item) => {
 			if (item.group === GROUP_DIAGNOSTICS) return;
+			const entry = entryForRow(item);
+			if (entry) {
+				useEntry(entry);
+				return;
+			}
 			const name = item.id.startsWith("marketplace:") ? item.id.slice("marketplace:".length) : item.id;
 			deps.setEditorText(`/skill ${name} `);
 			deps.onClose();
 		},
 		actions: {
 			i: (item) => {
-				if (!item.id.startsWith("marketplace:") || installInFlight) return;
+				if (installInFlight) return;
+				const entry = entryForRow(item);
+				if (entry) {
+					installEntry(entry);
+					return;
+				}
+				if (!item.id.startsWith("marketplace:")) return;
 				const name = item.id.slice("marketplace:".length);
 				installInFlight = true;
 				void (async () => {
@@ -218,8 +602,10 @@ export function openSkillsHub(tui: TUI, deps: SkillsHubDeps): OverlayHandle {
 						deps.notice("error", `skill install failed: ${err instanceof Error ? err.message : String(err)}`);
 					} finally {
 						installInFlight = false;
-						// An install that lands after the hub closed has nothing to redraw.
-						if (!closed) handle.setItems(buildRows());
+						if (!closed) {
+							invalidateLibrary();
+							handle.refreshTabs();
+						}
 					}
 				})();
 			},

package/src/interactive/side-question.ts

@@ -0,0 +1,171 @@
+/**
+ * `/btw`: one model round beside the session, never inside it.
+ *
+ * A fleet run briefs its workers from the transcript, so every question the
+ * operator asks mid-run to orient themselves ("which file did that land in
+ * again?") becomes context the workers inherit. This round reads the compiled
+ * history the next turn would send and answers into an overlay; nothing it
+ * produces reaches the session JSONL, the transcript panel, the context ledger,
+ * or the task board, and it never becomes a turn.
+ *
+ * The call goes through the same `src/engine/ai.ts` stream seam compaction uses
+ * for its summarization call, which is what keeps this outside the turn state
+ * machine without adding an engine seam of its own. Tools are never sent.
+ */
+
+import { stream } from "../engine/ai.js";
+import type { AgentMessage, EngineModel, Usage } from "../engine/types.js";
+
+/**
+ * The whole system prompt for the round. The session's own compiled prompt is
+ * deliberately not reused: it carries the working agreement for a turn that
+ * edits files and calls tools, and this round does neither.
+ */
+export const SIDE_QUESTION_SYSTEM_PROMPT = [
+	"You are answering a side question from the operator of a coding session.",
+	"The conversation above is read-only context. Answer the question directly and briefly.",
+	"Do not continue the conversation, do not propose edits, and do not call tools.",
+].join(" ");
+
+/** Default output budget for the round. A side question wants an answer, not an essay. */
+export const SIDE_QUESTION_MAX_TOKENS = 2048;
+
+export interface SideQuestionUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoning: number;
+	totalTokens: number;
+	costUsd: number;
+}
+
+export interface SideQuestionInput {
+	/** Live model the next turn would use, taken from the session's active runtime. */
+	model: EngineModel;
+	/**
+	 * The compiled message history the next turn would send. Treated as
+	 * read-only: the round copies it and appends its own user message to the
+	 * copy, so the live agent's message list is never mutated.
+	 */
+	messages: ReadonlyArray<AgentMessage>;
+	question: string;
+	apiKey?: string;
+	signal?: AbortSignal;
+	maxTokens?: number;
+	/** Streamed answer text, delivered as the provider produces it. */
+	onDelta?: (partialText: string) => void;
+}
+
+/**
+ * One out-of-turn round against the session's live runtime. `/btw` and
+ * `/handoff` are both this: read the compiled history the next turn would see,
+ * append one instruction, send no tools, and never touch the turn state
+ * machine. Only the system prompt and the appended message differ.
+ */
+export interface OutOfTurnRoundInput extends Omit<SideQuestionInput, "question"> {
+	systemPrompt: string;
+	/** The one message appended to the read-only copy of the history. */
+	userText: string;
+}
+
+export interface SideQuestionResult {
+	text: string;
+	usage: SideQuestionUsage | null;
+	/** True when the operator cancelled the round with Esc or Ctrl+C. */
+	aborted: boolean;
+}
+
+function positive(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function sideQuestionUsage(raw: unknown): SideQuestionUsage | null {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const usage = raw as Partial<Usage> & { reasoning?: number };
+	const input = positive(usage.input);
+	const output = positive(usage.output);
+	const cacheRead = positive(usage.cacheRead);
+	const cacheWrite = positive(usage.cacheWrite);
+	const totalTokens = positive(usage.totalTokens) || input + output + cacheRead + cacheWrite;
+	if (totalTokens === 0) return null;
+	return {
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		reasoning: positive(usage.reasoning),
+		totalTokens,
+		costUsd: positive(usage.cost?.total),
+	};
+}
+
+function textFromMessage(message: unknown): string {
+	if (!message || typeof message !== "object" || !("content" in message)) return "";
+	const content = (message as { content: unknown }).content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter(
+			(block): block is { type: "text"; text: string } =>
+				!!block &&
+				typeof block === "object" &&
+				(block as { type?: unknown }).type === "text" &&
+				typeof (block as { text?: unknown }).text === "string",
+		)
+		.map((block) => block.text)
+		.join("");
+}
+
+/**
+ * Run the side-question round. Resolves with the answer, the provider usage
+ * (which is still real money and is reported to `/cost`), and whether the
+ * operator aborted it. Provider failures reject; the caller renders the reason
+ * in the overlay.
+ */
+export async function runSideQuestion(input: SideQuestionInput): Promise<SideQuestionResult> {
+	const { question, ...rest } = input;
+	return runOutOfTurnRound({ ...rest, systemPrompt: SIDE_QUESTION_SYSTEM_PROMPT, userText: question });
+}
+
+/** The shared round. See {@link OutOfTurnRoundInput}. */
+export async function runOutOfTurnRound(input: OutOfTurnRoundInput): Promise<SideQuestionResult> {
+	const options: Record<string, unknown> = { maxTokens: input.maxTokens ?? SIDE_QUESTION_MAX_TOKENS };
+	if (input.apiKey !== undefined) options.apiKey = input.apiKey;
+	if (input.signal !== undefined) options.signal = input.signal;
+
+	const context = {
+		systemPrompt: input.systemPrompt,
+		messages: [
+			...input.messages,
+			{ role: "user", content: [{ type: "text", text: input.userText }], timestamp: Date.now() },
+		],
+	};
+
+	const events = stream(
+		input.model,
+		context as unknown as Parameters<typeof stream>[1],
+		options as unknown as Parameters<typeof stream>[2],
+	);
+
+	let text = "";
+	for await (const event of events) {
+		if (event.type === "text_delta") {
+			text = textFromMessage(event.partial);
+			input.onDelta?.(text);
+			continue;
+		}
+		if (event.type === "done") {
+			const answer = textFromMessage(event.message).trim();
+			return { text: answer, usage: sideQuestionUsage((event.message as { usage?: unknown }).usage), aborted: false };
+		}
+		if (event.type === "error") {
+			const failed = event.error as { stopReason?: unknown; usage?: unknown; errorMessage?: unknown };
+			if (event.reason === "aborted" || failed.stopReason === "aborted" || input.signal?.aborted === true) {
+				return { text: text.trim(), usage: sideQuestionUsage(failed.usage), aborted: true };
+			}
+			throw new Error(typeof failed.errorMessage === "string" ? failed.errorMessage : "side question failed");
+		}
+	}
+	return { text: text.trim(), usage: null, aborted: input.signal?.aborted === true };
+}