@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/interactive/permission-overlay.ts

@@ -1,25 +1,37 @@
-import type { Component } from "../engine/tui.js";
-import { buildResponsiveHint } from "./overlay-frame.js";
+import type { ActionClass } from "../domains/safety/action-classifier.js";
+import type { AutonomyExposure } from "../domains/safety/autonomy.js";
+import {
+	classifyDecisionPresentation,
+	type DecisionPresentation,
+	decisionFactsForPermission,
+} from "../domains/safety/decision-presentation.js";
+import type { Component, OverlayOptions, TUI } from "../engine/tui.js";
+import { fitHintEntries } from "./overlay-frame.js";
+import { permissionHintEntries } from "./permission-hint.js";
+import type { ClioToken } from "./theme/index.js";
 
 export { type AskAxis, askAxis } from "../domains/safety/approval-axis.js";
 export { describeCallTarget, sanitizeCallTargetText } from "../domains/safety/call-target.js";
+export { permissionHintEntries } from "./permission-hint.js";
 
 export interface ApprovalRequestView {
 	requestId: string;
 	tool: string;
-	actionClass: string;
+	actionClass: ActionClass;
 	axis: { kind: "net"; ruleId: string } | { kind: "autonomy"; level: string };
 	origin: { kind: "main" } | { kind: "worker"; agentId: string; runId: string };
+	/** Admission-normalized exposure. Caller prose never supplies presentation fields. */
+	exposure?: AutonomyExposure;
 	reason: string;
 	/** Typed, sanitized multi-line artifact that this one approval authorizes. */
 	artifact?: { kind: "dispatch-plan"; text: string };
 	/**
-	 * One-line preview of the call's object: the command for bash, the path
-	 * for file tools, else a compact args preview. The operator is deciding
-	 * whether to allow this exact call, so the overlay must show what the
-	 * call will touch, not just the tool name. Main-agent asks derive it from
-	 * the parked call's args; worker escalations carry it in the escalation
-	 * payload. Absent only when nothing meaningful is derivable.
+	 * One-line preview of the call's allowlisted object fields. The operator is
+	 * deciding whether to allow this exact call, so the overlay must show what
+	 * the call will touch, not just the tool name. Unlisted fields appear only as
+	 * type-and-size summaries. Main-agent asks derive it from the parked call's
+	 * args; worker escalations carry it in the escalation payload. Absent only
+	 * when nothing meaningful is derivable.
 	 */
 	target?: string;
 	queueDepth?: number;
@@ -29,6 +41,44 @@ const PERMISSION_OVERLAY_CONTENT_WIDTH = 78;
 
 export const PERMISSION_OVERLAY_WIDTH = PERMISSION_OVERLAY_CONTENT_WIDTH + 4;
 
+/**
+ * Place a permission frame immediately above the live composer in both TUI
+ * modes. The editor grows with wrapped and multiline drafts, while the footer
+ * can add notice rows, so their rendered heights are the bottom dock rather
+ * than a fixed clearance. Regular mode preserves terminal scrollback and may
+ * leave that dock above the viewport bottom when the transcript is short.
+ * Recompute its viewport row on every frame so draft changes and terminal
+ * resizes move the dialog with the composer.
+ */
+export function permissionOverlayPlacement(
+	tui: Pick<TUI, "mode" | "render">,
+	editor: Pick<Component, "render">,
+	footer: Pick<Component, "render">,
+): OverlayOptions {
+	const margin = { bottom: 0 };
+	return {
+		anchor: "bottom-center",
+		margin,
+		visible: (termWidth, termHeight) => {
+			const dockHeight = editor.render(termWidth).length + footer.render(termWidth).length;
+			if (tui.mode === "fullscreen") {
+				margin.bottom = dockHeight;
+				return true;
+			}
+
+			const baseHeight = tui.render(termWidth).length;
+			const composerTop = Math.max(0, baseHeight - dockHeight);
+			const viewportStart = Math.max(0, baseHeight - termHeight);
+			const composerViewportRow = composerTop - viewportStart;
+			margin.bottom =
+				composerViewportRow >= 0 && composerViewportRow < termHeight
+					? Math.max(0, termHeight - composerViewportRow)
+					: dockHeight;
+			return true;
+		},
+	};
+}
+
 class PermissionOverlayBody implements Component {
 	constructor(private readonly view: ApprovalRequestView) {}
 
@@ -89,46 +139,41 @@ function wrapArtifactLine(value: string, max: number): string[] {
 	return lines;
 }
 
-function axisLabel(axis: ApprovalRequestView["axis"], style: ApprovalRequestView["origin"]["kind"]): string {
-	if (axis.kind === "net") return `safety-net rail ${axis.ruleId}`;
-	return style === "worker" ? `autonomy level ${axis.level}` : `autonomy level (${axis.level})`;
+export function permissionDecisionPresentation(view: ApprovalRequestView): DecisionPresentation {
+	return classifyDecisionPresentation(
+		decisionFactsForPermission({
+			tool: view.tool,
+			actionClass: view.actionClass,
+			axis:
+				view.axis.kind === "net"
+					? { kind: "safety-net", ruleId: view.axis.ruleId }
+					: { kind: "autonomy", level: view.axis.level },
+			origin: view.origin,
+			...(view.exposure !== undefined ? { exposure: view.exposure } : {}),
+		}),
+	);
 }
 
-function askedBy(view: ApprovalRequestView): string {
-	if (view.origin.kind === "worker") {
-		return `worker ${view.origin.agentId} (run ${view.origin.runId}), ${axisLabel(view.axis, "worker")}`;
-	}
-	return axisLabel(view.axis, "main");
+export function permissionOverlayTitle(view: ApprovalRequestView): string {
+	return permissionDecisionPresentation(view).title;
 }
 
-export function permissionOverlayTitle(): string {
-	return "Allow this action once?";
+export function permissionOverlayTone(view: ApprovalRequestView): ClioToken {
+	return permissionDecisionPresentation(view).semanticToken;
 }
 
 /**
- * The footer for a box `innerWidth` columns wide inside its borders.
- *
- * At 40 columns the old positional elider removed `[s] stop turn` and left
- * "allow once" and an ambiguous "close" in front of an operator trying to
- * refuse. The key kept working, so the layout was hiding a live safety action.
- * This surface used to answer that with three hand-written width tiers; it now
- * states the same policy as data. Allow and stop are marked critical, Esc is
- * marked droppable, and `fitHintEntries` shortens every label before it drops
- * anything, which reproduces the three tiers exactly.
+ * The footer for a box `innerWidth` columns wide inside its borders. The
+ * three columns the bottom border spends on `─ ` and the trailing space come
+ * off the top, which is what `buildResponsiveHint` does for every other frame.
  */
-export const permissionOverlayHint = buildResponsiveHint(
-	[
-		{ key: "Enter", verb: "allow once", short: "allow", critical: true },
-		{ key: "s", verb: "stop turn", short: "stop", critical: true },
-	],
-	{ key: "Esc", verb: "close", critical: false },
-);
-
-const SAFETY_SENTENCES: ReadonlyArray<string> = [
-	"Parked until you decide; allow or deny applies to this call only.",
-	"Stopping the turn denies it and ends the run, so nothing asks again.",
-	"Hard-blocked actions remain blocked.",
-];
+export function permissionOverlayHint(innerWidth: number, composerHasDraft = false): string {
+	return fitHintEntries(permissionHintEntries(composerHasDraft), innerWidth - 3);
+}
+
+function actionConsequence(presentation: DecisionPresentation, id: "deny" | "stop"): string {
+	return presentation.requiredActions.find((action) => action.id === id)?.consequence ?? "";
+}
 
 /**
  * The overlay's body, laid out for the width the frame gives it.
@@ -140,15 +185,15 @@ const SAFETY_SENTENCES: ReadonlyArray<string> = [
  */
 export function permissionOverlayLines(view: ApprovalRequestView, width: number): string[] {
 	const content = Math.max(8, Math.floor(width));
+	const presentation = permissionDecisionPresentation(view);
 	// The parked call is awaiting a decision, not blocked: the raw rejection
 	// short ("<tool> blocked: <class>") is never rendered here because its
 	// wording contradicts the ask. Tool, Target, Action, and the asking axis
 	// carry everything the operator needs to decide.
 	const lines = [
-		field("Tool: ", view.tool, content),
+		field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
 		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
-		field("Action: ", view.actionClass, content),
-		field("Asked by: ", askedBy(view), content),
+		...wrapSentence(`Requested by: ${presentation.requestedByCopy}`, content),
 		...(view.artifact !== undefined
 			? [
 					"",
@@ -157,7 +202,12 @@ export function permissionOverlayLines(view: ApprovalRequestView, width: number)
 				]
 			: []),
 		"",
-		...SAFETY_SENTENCES.flatMap((sentence) => wrapSentence(sentence, content)),
+		...wrapSentence(`Approval: ${presentation.authorizationCopy}`, content),
+		...wrapSentence(`Consequence: ${presentation.consequenceCopy}`, content),
+		...wrapSentence(presentation.reversibilityCopy, content),
+		...wrapSentence(`Deny: ${actionConsequence(presentation, "deny")}`, content),
+		...wrapSentence(`Stop: ${actionConsequence(presentation, "stop")}`, content),
+		...wrapSentence("Hard-blocked actions remain blocked.", content),
 	];
 	if (view.queueDepth !== undefined && view.queueDepth > 1) {
 		lines.splice(lines.indexOf(""), 0, `1 of ${view.queueDepth} parked`);

package/src/interactive/renderers/tool-execution.ts

@@ -13,6 +13,7 @@
  */
 
 import { sanitizeCallTargetText } from "../../domains/safety/call-target.js";
+import { redactSecretString, redactToolArgs } from "../../domains/safety/redaction.js";
 import { formatSize } from "../../engine/truncate.js";
 import { visibleWidth, wrapTextWithAnsi } from "../../engine/tui.js";
 import { classifyResourceRead, toolPresentationPolicy } from "../../tools/presentation.js";
@@ -22,7 +23,10 @@ import { clioTheme, formatCompactMs, GLYPH } from "../theme/index.js";
 import { renderDiffLines } from "./diff.js";
 import { tryRenderJson, tryRenderXml } from "./structured.js";
 
-export { classifyResourceRead };
+// The argument projection lives in the safety domain so the worker tool seam
+// scrubs by the same rules; re-exported here because this renderer is where
+// callers and tests have always reached for it.
+export { classifyResourceRead, redactToolArgs };
 
 const theme = clioTheme();
 const dim = (text: string): string => theme.fg("dim", text);
@@ -127,52 +131,6 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-const SECRET_KEY_RE =
-	/(?:api[-_]?key|access[-_]?key|auth(?:orization)?|credential|password|private[-_]?key|secret|token)/iu;
-const ENV_KEY_RE = /^env(?:ironment)?$/iu;
-const SECRET_STRING_RE = /(https?:\/\/[^\s/@]+:)[^\s/@]+@/giu;
-const SECRET_URL_PARAM_RE =
-	/([?&](?:api[-_]?key|access[-_]?token|auth(?:orization)?|credential|password|secret|token)[^=\s]*=)[^&#\s]+/giu;
-const SECRET_ASSIGNMENT_RE =
-	/(?<![A-Z0-9_])((?:[A-Z0-9_]*(?:ACCESS|API|AUTH|CREDENTIAL|KEY|PASS(?:WORD)?|PRIVATE|SECRET|TOKEN)[A-Z0-9_]*)=)[^\s;&|]+/giu;
-const SECRET_FLAG_RE =
-	/(--?(?:[a-z0-9-]*(?:api[-_]?key|access[-_]?token|auth(?:orization)?|credential|password|secret|token)[a-z0-9-]*))(=|\s+)([^\s;&|]+)/giu;
-
-function redactSecretString(value: string): string {
-	return value
-		.replace(SECRET_STRING_RE, "$1[redacted]@")
-		.replace(SECRET_URL_PARAM_RE, "$1[redacted]")
-		.replace(SECRET_ASSIGNMENT_RE, "$1[redacted]")
-		.replace(SECRET_FLAG_RE, "$1$2[redacted]");
-}
-
-function redactEnvironmentValue(value: unknown, depth: number): unknown {
-	if (depth > 8) return "[redacted nested values]";
-	if (typeof value === "string") return "[redacted]";
-	if (Array.isArray(value)) return value.map((item) => redactEnvironmentValue(item, depth + 1));
-	if (!isPlainObject(value)) return value;
-	const out: Record<string, unknown> = {};
-	for (const [childKey, childValue] of Object.entries(value)) {
-		out[childKey] = redactEnvironmentValue(childValue, depth + 1);
-	}
-	return out;
-}
-
-/** Project tool arguments for display only; execution and receipts retain the original values. */
-export function redactToolArgs(value: unknown, key = "", depth = 0): unknown {
-	if (SECRET_KEY_RE.test(key)) return "[redacted]";
-	if (ENV_KEY_RE.test(key)) return redactEnvironmentValue(value, depth);
-	if (typeof value === "string") return redactSecretString(value);
-	if (depth > 8) return "[redacted nested values]";
-	if (Array.isArray(value)) return value.map((item) => redactToolArgs(item, key, depth + 1));
-	if (!isPlainObject(value)) return value;
-	const out: Record<string, unknown> = {};
-	for (const [childKey, childValue] of Object.entries(value)) {
-		out[childKey] = redactToolArgs(childValue, childKey, depth + 1);
-	}
-	return out;
-}
-
 function readStringField(args: unknown, key: string): string | null {
 	if (!isPlainObject(args)) return null;
 	const value = args[key];
@@ -389,6 +347,10 @@ function offloadPathOf(finished: ToolExecutionFinished): string | null {
 	return isPlainObject(resultSize) ? stringField(resultSize, "offloadPath") : null;
 }
 
+function offloadFileMissing(finished: ToolExecutionFinished): boolean {
+	return finished.resultSummary?.offloadFileMissing === true;
+}
+
 function shownBytesOf(finished: ToolExecutionFinished): number | null {
 	const observation = observationOf(finished);
 	const fromObservation = numberField(observation, "shownBytes");
@@ -468,7 +430,12 @@ function ledgerTail(finished: ToolExecutionFinished): { facts: string; offload:
 	const offloadPath = executed ? offloadPathOf(finished) : null;
 	return {
 		facts: parts.length > 0 ? dim(` · ${parts.join(" · ")}`) : "",
-		offload: offloadPath !== null ? dim(` · full: ${offloadPath}`) : "",
+		offload:
+			offloadPath === null
+				? ""
+				: offloadFileMissing(finished)
+					? dim(" · full: gone after the 14-day retention sweep")
+					: dim(` · full: ${offloadPath}`),
 	};
 }
 
@@ -1072,7 +1039,10 @@ function renderOutputMeta(
 function renderOutputFooter(finished: ToolExecutionFinished, width: number, isError: boolean): string[] {
 	const out: string[] = [];
 	const offloadPath = isNonExecutedOutcome(finished.outcome) ? null : offloadPathOf(finished);
-	if (offloadPath !== null) out.push(...indentAndWrap(`${yellow("full output")}  ${offloadPath}`, width, isError));
+	if (offloadPath !== null) {
+		const pointer = offloadFileMissing(finished) ? "gone after the 14-day retention sweep" : offloadPath;
+		out.push(...indentAndWrap(`${yellow("full output")}  ${pointer}`, width, isError));
+	}
 	const hint =
 		stringField(resultSizeOf(finished), "followUpHint") ?? stringField(finished.resultSummary ?? null, "followUpHint");
 	if (hint !== null) out.push(...indentAndWrap(`${dim("next")}  ${hint}`, width, isError));

package/src/interactive/session-last-turn.ts

@@ -17,6 +17,7 @@
  * back off replayed thinking text.
  */
 
+import { type ResponseModelIdObservation, responseModelIdObservationFromRecord } from "../core/response-model-id.js";
 import { rawDurationMs } from "../core/timers.js";
 import { extractReasoningTokens } from "../domains/session/context-accounting.js";
 import type { MessageEntry, SessionEntry, SessionUsageDefaults } from "../domains/session/index.js";
@@ -133,6 +134,10 @@ export function lastTurnSummaryFromLedger(
 	let toolErrorCount = 0;
 	let targetId = turn.targetId;
 	let modelId = turn.modelId;
+	let responseModelIdObservation: ResponseModelIdObservation = {
+		state: "legacy-difference-only",
+		differingModelId: null,
+	};
 
 	for (const row of turn.rows) {
 		const record = payloadRecord(row.payload);
@@ -148,7 +153,8 @@ export function lastTurnSummaryFromLedger(
 		const reason = stopReasonOf(record.stopReason);
 		if (reason && reason !== "stop") stopReason = reason;
 		targetId = targetId ?? nonEmptyString(record, "provider", "api");
-		modelId = modelId ?? nonEmptyString(record, "responseModel", "model");
+		modelId = modelId ?? nonEmptyString(record, "model");
+		responseModelIdObservation = responseModelIdObservationFromRecord(record, "legacy-difference-only");
 		const usage = payloadRecord(record.usage);
 		if (!usage) continue;
 		inputTokens += positiveNumber(usage.input);
@@ -177,6 +183,7 @@ export function lastTurnSummaryFromLedger(
 		stopReason,
 		watchdogPeak: 0,
 		truncated: false,
+		responseModelIdObservation,
 	};
 	if (sawReasoning) {
 		summary.reasoningTokens = reasoningTokens;

package/src/interactive/session-usage-reseed.ts

@@ -14,6 +14,11 @@
  * only the sink wiring between that fold and the observability projection.
  */
 
+import {
+	addResponseModelIdObservationCount,
+	emptyResponseModelIdObservationCounts,
+	type ResponseModelIdObservationCounts,
+} from "../core/response-model-id.js";
 import { ledgerUsageCalls, type SessionEntry, type SessionUsageDefaults } from "../domains/session/index.js";
 import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
 
@@ -22,7 +27,7 @@ export interface SessionUsageSink {
 	resetSession(): void;
 	recordTokens(
 		providerId: string,
-		modelId: string,
+		attributedModelId: string,
 		tokens: number,
 		costUsd?: number,
 		breakdown?: {
@@ -35,6 +40,10 @@ export interface SessionUsageSink {
 			apiCalls?: number;
 		},
 		costProvenance?: never,
+		modelIdFacts?: {
+			requestedModelIds: ReadonlyArray<string>;
+			responseModelIdObservationCounts: Readonly<ResponseModelIdObservationCounts>;
+		},
 	): void;
 }
 
@@ -61,14 +70,31 @@ export function reseedSessionUsageFromLedger(
 	sink.resetSession();
 	const scoped = filterEntriesToActivePath(entries, activeLeafTurnId ?? undefined);
 	for (const call of ledgerUsageCalls(scoped, defaults)) {
-		sink.recordTokens(call.providerId, call.modelId, call.totalTokens, call.costUsd, {
-			input: call.input,
-			output: call.output,
-			cacheRead: call.cacheRead,
-			cacheWrite: call.cacheWrite,
-			reasoningTokens: call.reasoningTokens,
-			totalTokens: call.totalTokens,
-			apiCalls: call.apiCalls ?? 1,
-		});
+		const responseModelIdObservationCounts = emptyResponseModelIdObservationCounts();
+		addResponseModelIdObservationCount(
+			responseModelIdObservationCounts,
+			call.responseModelIdObservation,
+			call.apiCalls ?? 1,
+		);
+		sink.recordTokens(
+			call.providerId,
+			call.attributedModelId,
+			call.totalTokens,
+			call.costUsd,
+			{
+				input: call.input,
+				output: call.output,
+				cacheRead: call.cacheRead,
+				cacheWrite: call.cacheWrite,
+				reasoningTokens: call.reasoningTokens,
+				totalTokens: call.totalTokens,
+				apiCalls: call.apiCalls ?? 1,
+			},
+			undefined,
+			{
+				requestedModelIds: [call.requestedModelId],
+				responseModelIdObservationCounts,
+			},
+		);
 	}
 }

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 };
+}