@prometheus-ai/agent 0.5.0

package/src/modes/utils/context-usage.ts

@@ -0,0 +1,335 @@
+import type { CompactionSettings } from "@prometheus-ai/agent-core/compaction";
+import { effectiveReserveTokens, estimateTokens, resolveThresholdTokens } from "@prometheus-ai/agent-core/compaction";
+import type { Model } from "@prometheus-ai/ai";
+import { countTokens } from "@prometheus-ai/natives";
+import { formatNumber } from "@prometheus-ai/utils";
+import type { Skill } from "../../extensibility/skills";
+import type { AgentSession } from "../../session/agent-session";
+import type { Tool } from "../../tools";
+import type { theme as Theme } from "../theme/theme";
+
+const GRID_COLS = 20;
+const GRID_ROWS = 10;
+const GRID_CELLS = GRID_COLS * GRID_ROWS;
+const GRID_GUTTER = "   ";
+
+const CELL_FILLED = "⛁";
+const CELL_FILLED_MESSAGES = "⛃";
+const CELL_FREE = "⛶";
+const CELL_BUFFER = "⛝";
+
+type CategoryId = "systemPrompt" | "systemContext" | "systemTools" | "skills" | "messages";
+
+interface CategoryInfo {
+	id: CategoryId;
+	label: string;
+	tokens: number;
+	color: "accent" | "warning" | "success" | "userMessageText" | "customMessageLabel";
+	glyph: string;
+}
+
+export interface ContextBreakdown {
+	model: Model | undefined;
+	contextWindow: number;
+	categories: CategoryInfo[];
+	usedTokens: number;
+	autoCompactBufferTokens: number;
+	freeTokens: number;
+}
+
+export function estimateSkillsTokens(skills: readonly Skill[]): number {
+	const fragments: string[] = [];
+	for (const skill of skills) {
+		// "- name: description\n" wire framing tokenizes ~identically to the
+		// concatenated form, so encode each piece separately and sum.
+		fragments.push(skill.name, skill.description);
+	}
+	return countTokens(fragments);
+}
+
+export function estimateToolSchemaTokens(
+	tools: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>,
+): number {
+	const fragments: string[] = [];
+	for (const tool of tools) {
+		fragments.push(tool.name, tool.description);
+		try {
+			fragments.push(JSON.stringify(tool.parameters ?? {}));
+		} catch {
+			// Schema may contain functions or cycles; ignore.
+		}
+	}
+	return countTokens(fragments);
+}
+
+/**
+ * Compute just the NON-MESSAGE token total: system prompt (with its skills
+ * section subtracted, since skills are tokenized separately) + system context
+ * (the rest of the system-prompt array) + tools + skills.
+ *
+ * Exposed so callers like `StatusLineComponent` can cache the non-message
+ * total separately from the message total. Non-message inputs (skills,
+ * tools, system prompt) change rarely; the message list grows on every
+ * streaming turn. Splitting the two lets the caller refresh each on its own
+ * cadence — non-message recomputed only when the inputs identity changes,
+ * messages walked incrementally as new entries append.
+ */
+export function computeNonMessageTokens(session: AgentSession): number {
+	const parts = computeNonMessageBreakdown(session);
+	return parts.systemPromptTokens + parts.systemContextTokens + parts.toolsTokens + parts.skillsTokens;
+}
+
+/**
+ * Shared helper for the four non-message token totals. Single source of truth
+ * for both `computeNonMessageTokens` (status-line incremental cache) and
+ * `computeContextBreakdown` (/context panel). The split avoids drift between
+ * the two surfaces — they MUST report the same numbers.
+ */
+function computeNonMessageBreakdown(session: AgentSession): {
+	skillsTokens: number;
+	toolsTokens: number;
+	systemContextTokens: number;
+	systemPromptTokens: number;
+} {
+	const skillsTokens = estimateSkillsTokens(session.skills ?? []);
+	const toolsTokens = estimateToolSchemaTokens(session.agent?.state?.tools ?? []);
+	const systemPromptParts = session.systemPrompt ?? [];
+	const systemContextTokens = countTokens(systemPromptParts.slice(1));
+	const systemPromptTokens = Math.max(0, countTokens(systemPromptParts[0] ?? "") - skillsTokens);
+	return { skillsTokens, toolsTokens, systemContextTokens, systemPromptTokens };
+}
+
+/**
+ * Compute a breakdown of estimated context usage by category for the active
+ * session and model.
+ */
+export function computeContextBreakdown(session: AgentSession): ContextBreakdown {
+	const model = session.model;
+	const contextWindow = model?.contextWindow ?? 0;
+
+	let messagesTokens = 0;
+	const convo = session.messages;
+	if (convo) {
+		for (const message of convo) {
+			messagesTokens += estimateTokens(message);
+		}
+	}
+
+	// The rendered system prompt already contains the skill descriptions and the
+	// markdown tool descriptions. To present a non-overlapping breakdown:
+	//   System prompt = total system prompt text - skills section (tool descriptions stay)
+	//   Tools         = JSON tool schema sent separately on the wire
+	//   Skills        = the skill list embedded in the system prompt
+	//   Messages      = conversation messages
+	const { skillsTokens, toolsTokens, systemContextTokens, systemPromptTokens } = computeNonMessageBreakdown(session);
+
+	const categories: CategoryInfo[] = [
+		{ id: "systemPrompt", label: "System prompt", tokens: systemPromptTokens, color: "accent", glyph: CELL_FILLED },
+		{ id: "systemTools", label: "System tools", tokens: toolsTokens, color: "warning", glyph: CELL_FILLED },
+		{
+			id: "systemContext",
+			label: "System context",
+			tokens: systemContextTokens,
+			color: "customMessageLabel",
+			glyph: CELL_FILLED,
+		},
+		{ id: "skills", label: "Skills", tokens: skillsTokens, color: "success", glyph: CELL_FILLED },
+		{
+			id: "messages",
+			label: "Messages",
+			tokens: messagesTokens,
+			color: "userMessageText",
+			glyph: CELL_FILLED_MESSAGES,
+		},
+	];
+
+	const usedTokens = categories.reduce((sum, c) => sum + c.tokens, 0);
+
+	let autoCompactBufferTokens = 0;
+	if (contextWindow > 0) {
+		const compactionSettings = session.settings.getGroup("compaction") as CompactionSettings;
+		if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
+			const threshold = resolveThresholdTokens(contextWindow, compactionSettings);
+			autoCompactBufferTokens = Math.max(0, contextWindow - threshold);
+		} else {
+			autoCompactBufferTokens = 0;
+		}
+		// Even when fully disabled, fall back to a sensible reserve floor for display.
+		if (autoCompactBufferTokens === 0 && compactionSettings.enabled) {
+			autoCompactBufferTokens = effectiveReserveTokens(contextWindow, compactionSettings);
+		}
+	}
+	autoCompactBufferTokens = Math.min(autoCompactBufferTokens, Math.max(0, contextWindow - usedTokens));
+
+	const freeTokens = Math.max(0, contextWindow - usedTokens - autoCompactBufferTokens);
+
+	return {
+		model,
+		contextWindow,
+		categories,
+		usedTokens,
+		autoCompactBufferTokens,
+		freeTokens,
+	};
+}
+
+interface CellSpec {
+	glyph: string;
+	color: "accent" | "warning" | "success" | "userMessageText" | "customMessageLabel" | "muted" | "dim";
+}
+
+function planCells(breakdown: ContextBreakdown): CellSpec[] {
+	const cells: CellSpec[] = [];
+	const window = breakdown.contextWindow;
+
+	if (window <= 0) {
+		for (let i = 0; i < GRID_CELLS; i++) {
+			cells.push({ glyph: CELL_FREE, color: "dim" });
+		}
+		return cells;
+	}
+
+	const tokensPerCell = window / GRID_CELLS;
+
+	const ratioCells = (tokens: number): number => {
+		if (tokens <= 0) return 0;
+		return Math.max(1, Math.round(tokens / tokensPerCell));
+	};
+
+	const categoryCounts = breakdown.categories.map(category => ({
+		category,
+		count: ratioCells(category.tokens),
+	}));
+
+	let bufferCount = ratioCells(breakdown.autoCompactBufferTokens);
+
+	let usedCount = categoryCounts.reduce((sum, c) => sum + c.count, 0);
+
+	// Prevent the visualization from over-running the grid.
+	const maxUsable = GRID_CELLS - bufferCount;
+	if (usedCount > maxUsable) {
+		// Scale categories proportionally down to fit.
+		let overflow = usedCount - maxUsable;
+		// Trim from the largest categories first to preserve visibility for small ones.
+		const order = [...categoryCounts].sort((a, b) => b.count - a.count);
+		for (const entry of order) {
+			while (overflow > 0 && entry.count > 1) {
+				entry.count -= 1;
+				overflow -= 1;
+			}
+		}
+		usedCount = categoryCounts.reduce((sum, c) => sum + c.count, 0);
+		if (usedCount + bufferCount > GRID_CELLS) {
+			bufferCount = Math.max(0, GRID_CELLS - usedCount);
+		}
+	}
+
+	for (const { category, count } of categoryCounts) {
+		for (let i = 0; i < count; i++) {
+			cells.push({ glyph: category.glyph, color: category.color });
+		}
+	}
+
+	const freeCount = Math.max(0, GRID_CELLS - cells.length - bufferCount);
+	for (let i = 0; i < freeCount; i++) {
+		cells.push({ glyph: CELL_FREE, color: "dim" });
+	}
+	for (let i = 0; i < bufferCount; i++) {
+		cells.push({ glyph: CELL_BUFFER, color: "warning" });
+	}
+
+	// Pad to exactly GRID_CELLS in case rounding undershot.
+	while (cells.length < GRID_CELLS) {
+		cells.push({ glyph: CELL_FREE, color: "dim" });
+	}
+	return cells.slice(0, GRID_CELLS);
+}
+
+function percentString(part: number, whole: number, fractionDigits = 1): string {
+	if (whole <= 0) return "0%";
+	const pct = (part / whole) * 100;
+	if (pct > 0 && pct < 0.05) return "<0.1%";
+	return `${pct.toFixed(fractionDigits)}%`;
+}
+
+function buildLegendLines(breakdown: ContextBreakdown, theme: typeof Theme): string[] {
+	const lines: string[] = [];
+	const { model, contextWindow, categories, usedTokens, autoCompactBufferTokens, freeTokens } = breakdown;
+
+	const modelName = model?.name ?? model?.id ?? "no model";
+	const modelId = model?.id ?? "unknown";
+	const windowLabel = formatNumber(contextWindow).toLowerCase();
+
+	lines.push(theme.bold(`${modelName}`) + theme.fg("dim", ` (${windowLabel} context)`));
+	lines.push(theme.fg("muted", `${modelId}[${windowLabel}]`));
+	lines.push(
+		`${theme.bold(formatNumber(usedTokens))}${theme.fg("dim", `/${windowLabel} tokens`)}` +
+			theme.fg("muted", ` (${percentString(usedTokens, contextWindow)})`),
+	);
+	lines.push("");
+	lines.push(theme.fg("muted", "Estimated usage by category"));
+
+	for (const category of categories) {
+		const dot = theme.fg(category.color, category.glyph);
+		const label = category.label;
+		const tokens = formatNumber(category.tokens);
+		const pct = percentString(category.tokens, contextWindow);
+		lines.push(`${dot} ${label}: ${theme.bold(tokens)} ${theme.fg("dim", `tokens (${pct})`)}`);
+	}
+
+	const freeDot = theme.fg("dim", CELL_FREE);
+	lines.push(
+		`${freeDot} Free space: ${theme.bold(formatNumber(freeTokens))} ${theme.fg("dim", `(${percentString(freeTokens, contextWindow)})`)}`,
+	);
+
+	if (autoCompactBufferTokens > 0) {
+		const bufferDot = theme.fg("warning", CELL_BUFFER);
+		lines.push(
+			`${bufferDot} Autocompact buffer: ${theme.bold(formatNumber(autoCompactBufferTokens))} ${theme.fg(
+				"dim",
+				`tokens (${percentString(autoCompactBufferTokens, contextWindow)})`,
+			)}`,
+		);
+	}
+
+	return lines;
+}
+
+/**
+ * Render a colorful context-usage panel as ANSI text. Output is a series of
+ * lines pairing the grid (left) with the legend (right).
+ */
+export function renderContextUsage(breakdown: ContextBreakdown, theme: typeof Theme): string {
+	if (breakdown.contextWindow <= 0) {
+		return theme.fg("muted", "Context usage is unavailable: no model is selected for this session.");
+	}
+
+	const cells = planCells(breakdown);
+	const legend = buildLegendLines(breakdown, theme);
+
+	const totalLines = Math.max(GRID_ROWS, legend.length);
+	const lines: string[] = [];
+
+	for (let row = 0; row < totalLines; row++) {
+		let gridSegment = "";
+		if (row < GRID_ROWS) {
+			const rowCells: string[] = [];
+			for (let col = 0; col < GRID_COLS; col++) {
+				const cell = cells[row * GRID_COLS + col];
+				rowCells.push(theme.fg(cell.color, cell.glyph));
+			}
+			gridSegment = rowCells.join(" ");
+		} else {
+			// Pad with blanks the same visible width as a grid row so legend lines
+			// past the grid stay aligned with their column.
+			const blank = " ".repeat(GRID_COLS * 2 - 1);
+			gridSegment = blank;
+		}
+
+		const legendSegment = legend[row] ?? "";
+		const line = legendSegment.length > 0 ? `${gridSegment}${GRID_GUTTER}${legendSegment}` : gridSegment;
+		lines.push(line);
+	}
+
+	return lines.join("\n");
+}

package/src/modes/utils/copy-targets.ts

@@ -0,0 +1,254 @@
+import type { AgentMessage } from "@prometheus-ai/agent-core";
+import type { ToolCall } from "@prometheus-ai/ai";
+
+/** A fenced code block extracted from assistant markdown. */
+export interface CodeBlock {
+	/** Info string after the opening fence (language id), trimmed. */
+	lang: string;
+	/** Block body with the trailing newline stripped. */
+	code: string;
+}
+
+/** A runnable command found in the transcript. */
+export interface LastCommand {
+	kind: "bash" | "eval";
+	code: string;
+	/** Highlight language: "bash" for bash, "python"/"javascript" for eval. */
+	language: string;
+}
+
+/**
+ * A node in the `/copy` picker tree. Leaves carry `content` (placed on the
+ * clipboard) plus `copyMessage` (the status shown afterwards); groups carry
+ * `children` to drill into.
+ */
+export interface CopyTarget {
+	/** Stable identifier (e.g. "msg:1", "msg:1:code:0", "msg:1:all", "cmd:1"). */
+	id: string;
+	label: string;
+	/** Dim annotation: line/block counts, language, or tool name. */
+	hint?: string;
+	/** Full text rendered in the preview pane. */
+	preview: string;
+	/** Highlight language for code/command previews (undefined = plain/markdown). */
+	language?: string;
+	/** Leaf: text copied to the clipboard. */
+	content?: string;
+	/** Leaf: status message shown after copying. */
+	copyMessage?: string;
+	/** Group: nested targets to drill into. */
+	children?: CopyTarget[];
+}
+
+/** Minimal session surface needed to assemble copy targets (eases testing). */
+export interface CopySource {
+	readonly messages: readonly AgentMessage[];
+	getLastVisibleHandoffText(): string | undefined;
+}
+
+/** Cap on how many recent assistant messages the picker lists. */
+const MAX_MESSAGES = 50;
+
+const CODE_BLOCK_RE = /^```([^\n]*)\n([\s\S]*?)^```/gm;
+
+/** Extract fenced code blocks from assistant markdown, in document order. */
+export function extractCodeBlocks(text: string): CodeBlock[] {
+	const blocks: CodeBlock[] = [];
+	for (const match of text.matchAll(CODE_BLOCK_RE)) {
+		blocks.push({ lang: match[1].trim(), code: match[2].replace(/\n$/, "") });
+	}
+	return blocks;
+}
+
+function extractEvalCode(args: unknown): { code: string; language: string } | undefined {
+	if (!args || typeof args !== "object") return undefined;
+	const cells = (args as { cells?: unknown }).cells;
+	if (!Array.isArray(cells)) return undefined;
+
+	const codeBlocks: string[] = [];
+	let language = "python";
+	let languageResolved = false;
+	for (const cell of cells) {
+		if (!cell || typeof cell !== "object") continue;
+		const code = (cell as { code?: unknown }).code;
+		if (typeof code !== "string" || code.length === 0) continue;
+		codeBlocks.push(code);
+		if (!languageResolved) {
+			language = (cell as { language?: unknown }).language === "js" ? "javascript" : "python";
+			languageResolved = true;
+		}
+	}
+
+	return codeBlocks.length > 0 ? { code: codeBlocks.join("\n\n"), language } : undefined;
+}
+
+function commandFromToolCall(tc: ToolCall): LastCommand | undefined {
+	if (tc.name === "bash" && typeof tc.arguments.command === "string") {
+		return { kind: "bash", code: tc.arguments.command, language: "bash" };
+	}
+	if (tc.name === "eval") {
+		const evalResult = extractEvalCode(tc.arguments);
+		if (evalResult) return { kind: "eval", code: evalResult.code, language: evalResult.language };
+	}
+	return undefined;
+}
+
+/** Walk the transcript backwards for the most recent bash command or eval code. */
+export function extractLastCommand(messages: readonly AgentMessage[]): LastCommand | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role !== "assistant") continue;
+		const toolCalls = msg.content.filter((c): c is ToolCall => c.type === "toolCall");
+		for (let j = toolCalls.length - 1; j >= 0; j--) {
+			const command = commandFromToolCall(toolCalls[j]!);
+			if (command) return command;
+		}
+	}
+	return undefined;
+}
+
+/** Concatenated visible text of an assistant message, or undefined when empty. */
+function assistantText(msg: AgentMessage): string | undefined {
+	if (msg.role !== "assistant") return undefined;
+	let text = "";
+	for (const content of msg.content) {
+		if (content.type === "text") text += content.text;
+	}
+	return text.trim() || undefined;
+}
+
+function pluralLines(text: string): string {
+	const count = text.length === 0 ? 0 : text.split("\n").length;
+	return `${count} line${count === 1 ? "" : "s"}`;
+}
+
+function blockHint(block: CodeBlock): string {
+	const lines = pluralLines(block.code);
+	return block.lang ? `${block.lang} · ${lines}` : lines;
+}
+
+/** First non-empty line, whitespace-collapsed, used as a message label. */
+function firstLine(text: string): string {
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed) return trimmed.replace(/\s+/g, " ");
+	}
+	return text.trim().replace(/\s+/g, " ");
+}
+
+/** Build the target node for one assistant message: a leaf when it has no code
+ * blocks, otherwise a group exposing the full message, each block, and "all". */
+function messageTarget(text: string, rank: number): CopyTarget {
+	const id = `msg:${rank}`;
+	const label = firstLine(text);
+	const blocks = extractCodeBlocks(text);
+	const hint = blocks.length > 0 ? `${pluralLines(text)} · ${blocks.length} code` : pluralLines(text);
+	const messageCopy = rank === 1 ? "Copied last message to clipboard" : "Copied message to clipboard";
+
+	if (blocks.length === 0) {
+		return { id, label, hint, preview: text, content: text, copyMessage: messageCopy };
+	}
+
+	// The message node itself copies the full message; its code blocks are
+	// child copy targets you can expand into.
+	const children: CopyTarget[] = blocks.map((block, j) => ({
+		id: `${id}:code:${j}`,
+		label: `Block ${j + 1}`,
+		hint: blockHint(block),
+		preview: block.code,
+		language: block.lang || undefined,
+		content: block.code,
+		copyMessage: `Copied code block ${j + 1} to clipboard`,
+	}));
+	if (blocks.length > 1) {
+		const combined = blocks.map(b => b.code).join("\n\n");
+		children.push({
+			id: `${id}:all`,
+			label: `All ${blocks.length} blocks`,
+			hint: pluralLines(combined),
+			preview: combined,
+			content: combined,
+			copyMessage: `Copied ${blocks.length} code blocks to clipboard`,
+		});
+	}
+
+	return { id, label, hint, preview: text, content: text, copyMessage: messageCopy, children };
+}
+
+function commandTitle(command: LastCommand): string {
+	return command.kind === "bash" ? "Bash command" : "Eval code";
+}
+
+function commandTarget(command: LastCommand, rank: number): CopyTarget {
+	const title = commandTitle(command);
+	return {
+		id: `cmd:${rank}`,
+		label: firstLine(command.code) || title,
+		hint: `${command.kind} · ${pluralLines(command.code)}`,
+		preview: command.code,
+		language: command.language,
+		content: command.code,
+		copyMessage: `Copied ${command.kind === "bash" ? "bash command" : "eval code"} to clipboard`,
+	};
+}
+
+/**
+ * Assemble the unified `/copy` target tree: recent assistant messages
+ * (most recent first, each drillable into its code blocks), runnable command
+ * targets interleaved after the assistant message that issued them, and a
+ * fresh-handoff fallback when no assistant message exists yet.
+ */
+export function buildCopyTargets(source: CopySource): CopyTarget[] {
+	const targets: CopyTarget[] = [];
+	const pendingCommands: LastCommand[] = [];
+	let messageRank = 0;
+	let commandRank = 0;
+
+	const appendCommands = (commands: readonly LastCommand[]) => {
+		for (const command of commands) {
+			commandRank += 1;
+			targets.push(commandTarget(command, commandRank));
+		}
+	};
+
+	for (let i = source.messages.length - 1; i >= 0 && messageRank < MAX_MESSAGES; i--) {
+		const msg = source.messages[i];
+		if (msg.role !== "assistant") continue;
+
+		const toolCalls = msg.content.filter((c): c is ToolCall => c.type === "toolCall");
+		const commands: LastCommand[] = [];
+		for (let j = toolCalls.length - 1; j >= 0; j--) {
+			const command = commandFromToolCall(toolCalls[j]!);
+			if (command) commands.push(command);
+		}
+
+		const text = assistantText(msg);
+		if (!text) {
+			pendingCommands.push(...commands);
+			continue;
+		}
+
+		messageRank += 1;
+		targets.push(messageTarget(text, messageRank));
+		appendCommands(pendingCommands);
+		appendCommands(commands);
+		pendingCommands.length = 0;
+	}
+
+	if (messageRank === 0) {
+		const handoff = source.getLastVisibleHandoffText();
+		if (handoff) {
+			targets.unshift({
+				id: "handoff",
+				label: "Handoff context",
+				hint: pluralLines(handoff),
+				preview: handoff,
+				content: handoff,
+				copyMessage: "Copied handoff context to clipboard",
+			});
+		}
+		appendCommands(pendingCommands);
+	}
+
+	return targets;
+}

package/src/modes/utils/hotkeys-markdown.ts

@@ -0,0 +1,60 @@
+import type { AppKeybinding, KeybindingsManager } from "../../config/keybindings";
+
+export interface HotkeysMarkdownBindings {
+	keybindings: Pick<KeybindingsManager, "getDisplayString">;
+}
+
+function appKey(bindings: HotkeysMarkdownBindings, action: AppKeybinding): string {
+	return bindings.keybindings.getDisplayString(action) || "Disabled";
+}
+
+export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string {
+	return [
+		"**Navigation**",
+		"| Key | Action |",
+		"|-----|--------|",
+		"| `Arrow keys` | Move cursor / browse history (Up when empty) |",
+		"| `Option+Left/Right` | Move by word |",
+		"| `Ctrl+A` / `Home` / `Cmd+Left` | Start of line |",
+		"| `Ctrl+E` / `End` / `Cmd+Right` | End of line |",
+		"",
+		"**Editing**",
+		"| Key | Action |",
+		"|-----|--------|",
+		"| `Enter` | Send message |",
+		"| `Shift+Enter` / `Alt+Enter` | New line |",
+		"| `Ctrl+W` / `Option+Backspace` | Delete word backwards |",
+		"| `Ctrl+U` | Delete to start of line |",
+		"| `Ctrl+K` | Delete to end of line |",
+		`| \`${appKey(bindings, "app.clipboard.copyLine")}\` | Copy current line |`,
+		`| \`${appKey(bindings, "app.clipboard.copyPrompt")}\` | Copy whole prompt |`,
+		"",
+		"**Other**",
+		"| Key | Action |",
+		"|-----|--------|",
+		"| `Tab` | Path completion / accept autocomplete |",
+		`| \`${appKey(bindings, "app.interrupt")}\` | Cancel autocomplete / interrupt active work |`,
+		`| \`${appKey(bindings, "app.clear")}\` | Clear editor (first) / exit (second) |`,
+		`| \`${appKey(bindings, "app.exit")}\` | Exit (when editor is empty) |`,
+		`| \`${appKey(bindings, "app.suspend")}\` | Suspend to background |`,
+		`| \`${appKey(bindings, "app.display.reset")}\` | Reset terminal display |`,
+		`| \`${appKey(bindings, "app.thinking.cycle")}\` | Cycle thinking level |`,
+		`| \`${appKey(bindings, "app.model.cycleForward")}\` | Cycle role models (slow/default/smol) |`,
+		`| \`${appKey(bindings, "app.model.cycleBackward")}\` | Cycle role models (backward) |`,
+		`| \`${appKey(bindings, "app.model.selectTemporary")}\` | Select model (temporary) |`,
+		`| \`${appKey(bindings, "app.model.select")}\` | Select model (set roles) |`,
+		`| \`${appKey(bindings, "app.plan.toggle")}\` | Toggle plan mode |`,
+		`| \`${appKey(bindings, "app.history.search")}\` | Search prompt history |`,
+		`| \`${appKey(bindings, "app.tools.expand")}\` | Toggle tool output expansion |`,
+		`| \`${appKey(bindings, "app.thinking.toggle")}\` | Toggle thinking block visibility |`,
+		`| \`${appKey(bindings, "app.editor.external")}\` | Edit message in external editor |`,
+		`| \`${appKey(bindings, "app.clipboard.pasteImage")}\` | Paste image from clipboard |`,
+		`| \`${appKey(bindings, "app.stt.toggle")}\` | Toggle speech-to-text recording |`,
+		"| `#` | Open prompt actions |",
+		"| `/` | Slash commands |",
+		"| `!` | Run bash command |",
+		"| `!!` | Run bash command (excluded from context) |",
+		"| `$` | Run Python in shared kernel |",
+		"| `$$` | Run Python (excluded from context) |",
+	].join("\n");
+}

package/src/modes/utils/keybinding-matchers.ts

@@ -0,0 +1,51 @@
+import { getKeybindings, matchesKey } from "@prometheus-ai/tui";
+
+/**
+ * Match the coding-agent interrupt key.
+ *
+ * Interactive mode installs a keybinding manager that exposes `app.interrupt`
+ * globally, but some isolated component tests still run with only TUI
+ * keybindings registered. In that case, fall back to raw Escape matching.
+ */
+export function matchesAppInterrupt(data: string): boolean {
+	const keybindings = getKeybindings();
+	const interruptKeys = keybindings.getKeys("app.interrupt");
+	if (interruptKeys.length > 0) {
+		return keybindings.matches(data, "app.interrupt");
+	}
+	return matchesKey(data, "escape") || matchesKey(data, "esc");
+}
+
+/** Match the generic selector cancel keybinding. */
+export function matchesSelectCancel(data: string): boolean {
+	return getKeybindings().matches(data, "tui.select.cancel");
+}
+
+/** Match the generic selector up-navigation keybinding. */
+export function matchesSelectUp(data: string): boolean {
+	return getKeybindings().matches(data, "tui.select.up");
+}
+
+/** Match the generic selector down-navigation keybinding. */
+export function matchesSelectDown(data: string): boolean {
+	return getKeybindings().matches(data, "tui.select.down");
+}
+
+/** Match the generic selector page-up keybinding. */
+export function matchesSelectPageUp(data: string): boolean {
+	return getKeybindings().matches(data, "tui.select.pageUp");
+}
+
+/** Match the generic selector page-down keybinding. */
+export function matchesSelectPageDown(data: string): boolean {
+	return getKeybindings().matches(data, "tui.select.pageDown");
+}
+
+export function matchesAppExternalEditor(data: string): boolean {
+	const keybindings = getKeybindings();
+	const externalEditorKeys = keybindings.getKeys("app.editor.external");
+	if (externalEditorKeys.length > 0) {
+		return keybindings.matches(data, "app.editor.external");
+	}
+	return matchesKey(data, "ctrl+g");
+}