@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/interactive/overlays/decisions.ts

@@ -0,0 +1,300 @@
+import type { DecisionLedgerEntry, DecisionRecord } from "../../domains/session/entries.js";
+import {
+	type Component,
+	Input,
+	matchesKey,
+	type OverlayHandle,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "../../engine/tui.js";
+import { buildHint, showClioOverlayFrame } from "../overlay-frame.js";
+import { clioTheme, GLYPH, rule } from "../theme/index.js";
+
+const DEFAULT_CONTENT_WIDTH = 88;
+
+export const DECISIONS_OVERLAY_WIDTH = DEFAULT_CONTENT_WIDTH + 4;
+
+export interface DecisionSelection {
+	interviewId: string;
+	key: string;
+	label: string;
+	value: string;
+}
+
+/** The operator-authored turn that makes a durable correction visible to the model. */
+export function formatDecisionCorrectionTurn(selection: DecisionSelection, correction: string): string {
+	return `Decision "${selection.label}" (previously: ${selection.value}) is superseded by the operator. New direction: ${correction}. Acknowledge and adjust the plan.`;
+}
+
+export interface OpenDecisionsOverlayOptions {
+	onSupersede: (selection: DecisionSelection) => void;
+	onCorrection: (selection: DecisionSelection, correction: string) => void;
+	onClose: () => void;
+	requestRender?: () => void;
+	now?: () => number;
+}
+
+interface SelectableDecision {
+	interview: DecisionLedgerEntry;
+	decision: DecisionRecord;
+}
+
+function fitLine(text: string, width: number): string {
+	const safeWidth = Math.max(1, Math.floor(width));
+	return visibleWidth(text) <= safeWidth ? text : truncateToWidth(text, safeWidth, "…", true);
+}
+
+function relativeTime(timestamp: string, now: number): string {
+	const value = Date.parse(timestamp);
+	if (!Number.isFinite(value)) return "unknown time";
+	const seconds = Math.max(0, Math.floor((now - value) / 1000));
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	return `${Math.floor(hours / 24)}d ago`;
+}
+
+function selectionFor(row: SelectableDecision): DecisionSelection {
+	return {
+		interviewId: row.interview.interviewId,
+		key: row.decision.key,
+		label: row.decision.label ?? row.decision.key,
+		value: row.decision.value,
+	};
+}
+
+function selectableRows(interviews: ReadonlyArray<DecisionLedgerEntry>): SelectableDecision[] {
+	return interviews.flatMap((interview) => interview.decisions.map((decision) => ({ interview, decision })));
+}
+
+function interviewHeader(interview: DecisionLedgerEntry, width: number, now: number): string[] {
+	const theme = clioTheme();
+	const rounds = `${interview.roundCount} round${interview.roundCount === 1 ? "" : "s"}`;
+	const status =
+		interview.interviewStatus === "complete" ? theme.fg("success", "complete") : theme.fg("warning", "cancelled");
+	const heading = `${theme.fg("accent", relativeTime(interview.endedAt, now))}${theme.fg("dim", " · ")}${theme.fg("muted", rounds)}${theme.fg("dim", " · ")}${status}`;
+	const lines = [fitLine(heading, width)];
+	if (interview.summary) {
+		lines.push(...wrapTextWithAnsi(theme.fg("dim", interview.summary), width).map((line) => fitLine(line, width)));
+	}
+	return lines;
+}
+
+function decisionLines(decision: DecisionRecord, selected: boolean, expanded: boolean, width: number): string[] {
+	const theme = clioTheme();
+	const cursor = selected ? theme.fg("accent", GLYPH.cursor) : " ";
+	const status = decision.status === "active" ? theme.fg("success", GLYPH.ok) : theme.fg("dim", GLYPH.cancelled);
+	const labelText = decision.label ?? decision.key;
+	const label = decision.status === "superseded" ? theme.fg("dim", labelText) : theme.fg("muted", labelText);
+	const value = decision.status === "superseded" ? theme.fg("dim", decision.value) : decision.value;
+	const lines = [fitLine(`${cursor} ${status} ${label}${theme.fg("dim", ":")} ${value}`, width)];
+	if (decision.status === "superseded" && decision.correction) {
+		lines.push(fitLine(`      ${theme.fg("dim", "correction")} ${theme.fg("muted", decision.correction)}`, width));
+	}
+	if (selected && expanded) {
+		if (decision.source_question) {
+			lines.push(
+				...wrapTextWithAnsi(`${theme.fg("dim", "question")} ${theme.fg("muted", decision.source_question)}`, width).map(
+					(line) => fitLine(`      ${line}`, width),
+				),
+			);
+		}
+		lines.push(
+			...wrapTextWithAnsi(`${theme.fg("dim", "answer")} ${theme.fg("muted", decision.value)}`, width).map((line) =>
+				fitLine(`      ${line}`, width),
+			),
+		);
+	}
+	return lines;
+}
+
+export function formatDecisionsOverlayBodyLines(
+	interviews: ReadonlyArray<DecisionLedgerEntry>,
+	selectedIndex = 0,
+	expandedKey: string | null = null,
+	contentWidth = DEFAULT_CONTENT_WIDTH,
+	now = Date.now(),
+): string[] {
+	const width = Math.max(1, Math.floor(contentWidth));
+	const theme = clioTheme();
+	if (interviews.length === 0) {
+		return [
+			...wrapTextWithAnsi(theme.fg("muted", "No interview decisions have been recorded on this branch."), width),
+			"",
+			...wrapTextWithAnsi(theme.fg("dim", "Completed and cancelled ask_user interviews appear here."), width),
+		].map((line) => fitLine(line, width));
+	}
+	const selected = selectableRows(interviews)[selectedIndex];
+	const lines: string[] = [];
+	for (let interviewIndex = 0; interviewIndex < interviews.length; interviewIndex += 1) {
+		const interview = interviews[interviewIndex];
+		if (!interview) continue;
+		if (interviewIndex > 0) lines.push(rule(theme, width));
+		lines.push(...interviewHeader(interview, width, now));
+		if (interview.decisions.length === 0) {
+			lines.push(fitLine(`  ${theme.fg("dim", "No compact decisions were recorded.")}`, width));
+			continue;
+		}
+		for (const decision of interview.decisions) {
+			const isSelected =
+				selected?.interview.interviewId === interview.interviewId && selected.decision.key === decision.key;
+			const rowKey = `${interview.interviewId}:${decision.key}`;
+			lines.push(...decisionLines(decision, isSelected, isSelected && expandedKey === rowKey, width));
+		}
+	}
+	return lines;
+}
+
+class DecisionsOverlayBody implements Component {
+	private selectedIndex = 0;
+	private expandedKey: string | null = null;
+	private correctionInput: Input | null = null;
+	private status = "";
+
+	constructor(
+		private readonly getInterviews: () => ReadonlyArray<DecisionLedgerEntry>,
+		private readonly options: OpenDecisionsOverlayOptions,
+	) {}
+
+	render(width: number): string[] {
+		const interviews = this.readInterviews();
+		const rows = selectableRows(interviews);
+		this.selectedIndex = Math.max(0, Math.min(this.selectedIndex, Math.max(0, rows.length - 1)));
+		const body = formatDecisionsOverlayBodyLines(
+			interviews,
+			this.selectedIndex,
+			this.expandedKey,
+			width,
+			this.options.now?.() ?? Date.now(),
+		);
+		if (this.correctionInput) {
+			const theme = clioTheme();
+			body.push("", fitLine(theme.fg("accent", "New direction"), width));
+			body.push(
+				...this.correctionInput
+					.render(Math.max(1, width))
+					.map((line) =>
+						fitLine(line.startsWith("> ") ? `${theme.fg("accent", `${GLYPH.cursor} `)}${line.slice(2)}` : line, width),
+					),
+			);
+		}
+		if (this.status) body.push("", fitLine(clioTheme().fg("warning", this.status), width));
+		return body;
+	}
+
+	handleInput(data: string): void {
+		if (this.correctionInput) {
+			this.correctionInput.handleInput(data);
+			return;
+		}
+		const rows = selectableRows(this.readInterviews());
+		if (matchesKey(data, "esc")) {
+			this.options.onClose();
+			return;
+		}
+		if (rows.length === 0) return;
+		if (matchesKey(data, "up")) {
+			this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+			this.expandedKey = null;
+			this.requestRender();
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			this.selectedIndex = Math.min(rows.length - 1, this.selectedIndex + 1);
+			this.expandedKey = null;
+			this.requestRender();
+			return;
+		}
+		const selected = rows[this.selectedIndex];
+		if (!selected) return;
+		if (matchesKey(data, "enter") || data === "\n") {
+			const key = `${selected.interview.interviewId}:${selected.decision.key}`;
+			this.expandedKey = this.expandedKey === key ? null : key;
+			this.requestRender();
+			return;
+		}
+		if (matchesKey(data, "s")) {
+			try {
+				this.options.onSupersede(selectionFor(selected));
+				this.status = "Decision superseded.";
+			} catch (error) {
+				this.status = error instanceof Error ? error.message : String(error);
+			}
+			this.requestRender();
+			return;
+		}
+		if (matchesKey(data, "c")) this.beginCorrection(selected);
+	}
+
+	invalidate(): void {
+		this.correctionInput?.invalidate();
+	}
+
+	footerHint(): string {
+		return this.correctionInput
+			? buildHint([{ key: "Enter", verb: "submit" }])
+			: buildHint([
+					{ key: "↑↓", verb: "select" },
+					{ key: "Enter", verb: "expand" },
+					{ key: "s", verb: "supersede" },
+					{ key: "c", verb: "correct" },
+				]);
+	}
+
+	private readInterviews(): ReadonlyArray<DecisionLedgerEntry> {
+		try {
+			return this.getInterviews();
+		} catch (error) {
+			this.status = error instanceof Error ? error.message : String(error);
+			return [];
+		}
+	}
+
+	private beginCorrection(selected: SelectableDecision): void {
+		const input = new Input();
+		input.onSubmit = (value) => {
+			const correction = value.trim();
+			if (correction.length === 0) {
+				this.status = "Enter the operator's new direction.";
+				this.requestRender();
+				return;
+			}
+			try {
+				this.options.onCorrection(selectionFor(selected), correction);
+			} catch (error) {
+				this.status = error instanceof Error ? error.message : String(error);
+				this.requestRender();
+			}
+		};
+		input.onEscape = () => this.options.onClose();
+		this.correctionInput = input;
+		this.status = "";
+		this.requestRender();
+	}
+
+	private requestRender(): void {
+		this.options.requestRender?.();
+	}
+}
+
+/** Mount the settled interview decision board. */
+export function openDecisionsOverlay(
+	tui: TUI,
+	getInterviews: () => ReadonlyArray<DecisionLedgerEntry>,
+	options: OpenDecisionsOverlayOptions,
+): OverlayHandle {
+	const body = new DecisionsOverlayBody(getInterviews, {
+		...options,
+		requestRender: options.requestRender ?? (() => tui.requestRender()),
+	});
+	return showClioOverlayFrame(tui, body, {
+		anchor: "center",
+		width: DECISIONS_OVERLAY_WIDTH,
+		title: () => "Decisions",
+		footerHint: () => body.footerHint(),
+	});
+}

package/src/interactive/overlays/help-reference.ts

@@ -41,17 +41,8 @@ export function openHelpOverlay(
 				// Overlay key actions are deliberately not duplicated here: each
 				// overlay's footer hint is the live source of its keys, and a static
 				// copy would rot exactly like the old SLASH_HOTKEYS table did.
-				detail: () => {
-					const lines = [`# Command: /${ref.name}`, `**Usage:** \`${ref.usage}\``, `**Description:** ${ref.description}`];
-					if (ref.aliases.length > 0) {
-						lines.push(`**Aliases:** ${ref.aliases.map((a) => `/${a}`).join(", ")}`);
-					}
-					return lines;
-				},
+				detail: () => [`# Command: /${ref.name}`, `**Usage:** \`${ref.usage}\``, `**Description:** ${ref.description}`],
 			};
-			if (ref.aliases.length > 0) {
-				item.meta = ref.aliases.join(", ");
-			}
 			return item;
 		});
 
@@ -109,6 +100,20 @@ export function openHelpOverlay(
 				"**Tasks versus runs**: `/tasks` shows the agent's plan steps. Fleet runs are concrete delegated worker executions and remain in this board as recent terminal history.",
 			],
 		},
+		{
+			id: "topic-steering-modes",
+			label: `${"steering modes".padEnd(30)}Interrupt, next slot, or end of turn: when a message lands mid-run`,
+			group: "Topics",
+			detail: () => [
+				"# Steering modes",
+				"While Clio is running, the key that submits a message chooses when it lands. The default is next slot.",
+				"**Next slot** (Enter): the message is delivered between tool batches, mid-run. The agent keeps going and reads it before its next model call.",
+				"**End of turn** (Alt+Enter by default): the message waits until the whole run settles and Clio would hand control back, then starts the next round.",
+				"**Interrupt** (Alt+I by default, or Ctrl+G then i): cancels the in-flight work the way Esc does, including a running bash child, then delivers the message as a fresh prompt. Anything already queued returns to the editor.",
+				"**Interrupt is refused** while an attached dispatch is running (the abort would kill the worker's run with no receipt; steer it with `@<agent>` or cancel it with Esc) and while a permission ask is parked (it is already waiting on you). In both cases the message is queued for the next slot and a notice says why.",
+				"**Alt+Up** restores queued messages to the editor. Workers accept next-slot steering only, through `@<agent>`.",
+			],
+		},
 		{
 			id: "topic-autonomy",
 			label: `${"autonomy & safety net".padEnd(30)}How the autonomy level and the always-on guardrails interact`,

package/src/interactive/overlays/model-selector.ts

@@ -22,6 +22,7 @@ import {
 } from "../../domains/providers/index.js";
 import {
 	type Component,
+	fuzzyFilter,
 	getKeybindings,
 	matchesKey,
 	type OverlayHandle,
@@ -45,6 +46,13 @@ const MODEL_OVERLAY_MAX_WIDTH = 120;
 const MODEL_OVERLAY_TERMINAL_PADDING = 8;
 const VISIBLE_ROWS = 10;
 const MODEL_MIN_WIDTH = 14;
+/**
+ * Every other column pair is separated by an explicit space. The model cell
+ * instead relies on its own padding, so a label that fills the column exactly
+ * butts straight against the ctx figure. The gutter is reserved inside the
+ * model cell, which keeps the header and the rows on the same column stops.
+ */
+const MODEL_COL_GUTTER = 1;
 const CONTEXT_COL_WIDTH = 7;
 const CAPS_COL_WIDTH = 5;
 const TARGET_COL_WIDTH_NARROW = 8;
@@ -549,6 +557,11 @@ function modelColumns(width: number): ModelColumns {
 	};
 }
 
+/** The model cell, always leaving `MODEL_COL_GUTTER` blank columns before ctx. */
+function fitModelCell(text: string, columnWidth: number): string {
+	return fitCell(truncateMiddle(text, Math.max(1, columnWidth - MODEL_COL_GUTTER)), columnWidth);
+}
+
 function fitCell(text: string, width: number, align: "left" | "right" = "left"): string {
 	const clipped = truncateToWidth(text, width, "", true);
 	const pad = " ".repeat(Math.max(0, width - visibleWidth(clipped)));
@@ -577,7 +590,7 @@ function formatModelHeader(width: number): string {
 	const columns = modelColumns(width);
 	let line =
 		`${" ".repeat(SELECTED_PREFIX_WIDTH)}` +
-		`${fitCell("model", columns.modelWidth)}` +
+		`${fitModelCell("model", columns.modelWidth)}` +
 		`${fitCell("ctx", CONTEXT_COL_WIDTH, "right")} ` +
 		`${fitCell("caps", CAPS_COL_WIDTH)}`;
 	if (columns.showTarget) line += ` ${fitCell("target", columns.targetWidth)}`;
@@ -597,7 +610,7 @@ function formatModelRow(row: ModelRow, width: number, selected: boolean): string
 	const health = theme.fg(healthToken(row), row.healthGlyph);
 	const prefix = `${pointer} ${health} ${activeMark(row)} `;
 	const modelLabel = row.model.length > 0 ? row.model : "(no model ids)";
-	const modelCell = fitCell(truncateMiddle(modelLabel, columns.modelWidth), columns.modelWidth);
+	const modelCell = fitModelCell(modelLabel, columns.modelWidth);
 	const model = selected ? theme.style("accent", modelCell, { bold: true }) : theme.fg("muted", modelCell);
 	let line =
 		prefix +
@@ -667,14 +680,18 @@ function formatModelDetail(row: ModelRow, width: number): string[] {
 	];
 }
 
-function matchesQuery(row: ModelRow, query: string): boolean {
-	const tokens = query
-		.toLowerCase()
-		.split(/\s+/)
-		.map((token) => token.trim())
-		.filter(Boolean);
-	if (tokens.length === 0) return true;
-	const haystack = [
+/**
+ * Keep the target-qualified ref ahead of the bare model id. This mirrors
+ * pi-coding-agent's provider-first model-selector search text, so an exact
+ * target/model query ranks ahead of a proxy target carrying that ref as its
+ * model id. Clio's runtime and availability facts remain searchable after the
+ * ranking prefix.
+ */
+function modelSelectorSearchText(row: ModelRow): string {
+	const qualifiedModel = row.model.length > 0 ? `${row.target}/${row.model}` : row.target;
+	return [
+		row.target,
+		qualifiedModel,
 		row.target,
 		row.model,
 		row.runtimeName,
@@ -690,10 +707,11 @@ function matchesQuery(row: ModelRow, query: string): boolean {
 		row.maxTokens,
 		row.authText,
 		row.healthText,
-	]
-		.join(" ")
-		.toLowerCase();
-	return tokens.every((token) => haystack.includes(token));
+	].join(" ");
+}
+
+function filterModelRows(rows: ReadonlyArray<ModelRow>, query: string): ModelRow[] {
+	return fuzzyFilter([...rows], query, modelSelectorSearchText);
 }
 
 function visibleSlice<T>(
@@ -728,7 +746,7 @@ function renderModelOverlayLines(input: {
 	const width = Math.max(1, input.width);
 	const query = input.query.trim();
 	const searching = query.length > 0;
-	const allMatches = input.rows.filter((row) => matchesQuery(row, input.query));
+	const allMatches = filterModelRows(input.rows, input.query);
 	const focusedMatches = allMatches.filter((row) => row.visibleByDefault !== false);
 	const filtered = searching || input.showAll ? allMatches : focusedMatches;
 	const selectableFiltered = filtered.filter((row) => row.selectable).length;
@@ -849,7 +867,7 @@ export class ModelOverlayView implements Component {
 	}
 
 	private filteredRows(): ModelRow[] {
-		const matches = this.rows.filter((row) => matchesQuery(row, this.query));
+		const matches = filterModelRows(this.rows, this.query);
 		if (this.query.trim().length > 0 || this.showAll) return matches;
 		return matches.filter((row) => row.visibleByDefault !== false);
 	}

package/src/interactive/overlays/session-selector.ts

@@ -1,6 +1,7 @@
 import { basename } from "node:path";
 import type { SessionContract, SessionMeta } from "../../domains/session/contract.js";
 import {
+	getKeybindings,
 	Input,
 	matchesKey,
 	type OverlayHandle,
@@ -178,6 +179,14 @@ export function createSessionOverlayBox(
 		closeOverlay();
 	}
 
+	function moveSelectionByPage(direction: -1 | 1): void {
+		const selected = list.getSelectedItem();
+		const currentIndex = selected ? filtered.findIndex((session) => session.id === selected.value) : 0;
+		const targetIndex = currentIndex + direction * VISIBLE_ROWS;
+		list.setSelectedIndex(targetIndex);
+		box.invalidate();
+	}
+
 	function closeOverlay(): void {
 		clearPendingEscape();
 		onClose();
@@ -200,6 +209,15 @@ export function createSessionOverlayBox(
 	}
 
 	function dispatchResolvedInput(data: string): void {
+		const keybindings = getKeybindings();
+		if (keybindings.matches(data, "tui.select.pageUp")) {
+			moveSelectionByPage(-1);
+			return;
+		}
+		if (keybindings.matches(data, "tui.select.pageDown")) {
+			moveSelectionByPage(1);
+			return;
+		}
 		if (matchesKey(data, "up") || matchesKey(data, "down")) {
 			list.handleInput(data);
 			return;