@wahack/pi-coding-agent 15.11.0

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

@@ -0,0 +1,339 @@
+import type { CompactionSettings } from "@oh-my-pi/pi-agent-core/compaction";
+import { effectiveReserveTokens, estimateTokens, resolveThresholdTokens } from "@oh-my-pi/pi-agent-core/compaction";
+import type { Model } from "@oh-my-pi/pi-ai";
+import { countTokens } from './stubs/natives/index.ts';
+import { formatNumber } from "@oh-my-pi/pi-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;
+}
+
+const EMPTY_STRING_PARTS: readonly string[] = [];
+const EMPTY_TOOLS: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">> = [];
+
+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 systemPromptParts = session.systemPrompt ?? EMPTY_STRING_PARTS;
+	const tools = session.agent?.state?.tools ?? EMPTY_TOOLS;
+	return countTokens(systemPromptParts) + estimateToolSchemaTokens(tools);
+}
+
+/**
+ * Shared helper for the four non-message token totals used by
+ * `computeContextBreakdown` (/context panel). Keep this category split stable:
+ * the status-line fast path intentionally uses the equivalent collapsed total
+ * in `computeNonMessageTokens`.
+ */
+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,360 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { ToolCall } from "@oh-my-pi/pi-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 blockquote block: a maximal run of `>`-prefixed lines from markdown. */
+export interface QuoteBlock {
+	/** Block body with each line's `>` marker (and one optional space) removed. */
+	text: string;
+}
+
+/** A drillable block within an assistant message, in document order. */
+export type MessageBlock = ({ kind: "code" } & CodeBlock) | ({ kind: "quote" } & QuoteBlock);
+
+/** 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 id (e.g. "msg:1", "msg:1:code:0", "msg:1:quote: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 OPEN_FENCE_RE = /^```([^\n]*)$/;
+const CLOSE_FENCE_RE = /^```/;
+const QUOTE_LINE_RE = /^>(.*)$/;
+
+/**
+ * Split assistant markdown into drillable blocks — fenced code and `>`-quoted
+ * runs — in document order. Fences mask their bodies, so a `>` line inside a
+ * code block is never mistaken for a quote. An unclosed fence is treated as
+ * ordinary text, matching the fenced-block grammar.
+ */
+export function extractBlocks(text: string): MessageBlock[] {
+	const blocks: MessageBlock[] = [];
+	const lines = text.split("\n");
+	let quote: string[] | undefined;
+	const flushQuote = () => {
+		if (quote) {
+			blocks.push({ kind: "quote", text: quote.join("\n") });
+			quote = undefined;
+		}
+	};
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!;
+		const open = OPEN_FENCE_RE.exec(line);
+		if (open) {
+			let close = -1;
+			for (let k = i + 1; k < lines.length; k++) {
+				if (CLOSE_FENCE_RE.test(lines[k]!)) {
+					close = k;
+					break;
+				}
+			}
+			if (close !== -1) {
+				flushQuote();
+				blocks.push({ kind: "code", lang: open[1].trim(), code: lines.slice(i + 1, close).join("\n") });
+				i = close;
+				continue;
+			}
+		}
+
+		const quoted = QUOTE_LINE_RE.exec(line);
+		if (quoted) {
+			// Strip the `>` marker plus one optional following space.
+			quote ??= [];
+			quote.push(quoted[1].startsWith(" ") ? quoted[1].slice(1) : quoted[1]);
+		} else {
+			flushQuote();
+		}
+	}
+	flushQuote();
+	return blocks;
+}
+
+/** Extract fenced code blocks from assistant markdown, in document order. */
+export function extractCodeBlocks(text: string): CodeBlock[] {
+	return extractBlocks(text)
+		.filter((b): b is { kind: "code" } & CodeBlock => b.kind === "code")
+		.map(b => ({ lang: b.lang, code: b.code }));
+}
+
+/** Extract `>`-quoted blocks from assistant markdown, in document order. */
+export function extractQuoteBlocks(text: string): QuoteBlock[] {
+	return extractBlocks(text)
+		.filter((b): b is { kind: "quote" } & QuoteBlock => b.kind === "quote")
+		.map(b => ({ text: b.text }));
+}
+
+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, " ");
+}
+
+/** "<n> lines · <c> code · <q> quote" — omitting block kinds that are absent. */
+function blockSummaryHint(text: string, codeCount: number, quoteCount: number): string {
+	const parts = [pluralLines(text)];
+	if (codeCount > 0) parts.push(`${codeCount} code`);
+	if (quoteCount > 0) parts.push(`${quoteCount} quote`);
+	return parts.join(" · ");
+}
+
+/** Build the target node for one assistant message: a leaf when it has no
+ * drillable blocks, otherwise a group exposing the full message plus each
+ * fenced code block and `>`-quoted block (de-prefixed) as a child target. */
+function messageTarget(text: string, rank: number): CopyTarget {
+	const id = `msg:${rank}`;
+	const label = firstLine(text);
+	const blocks = extractBlocks(text);
+	const messageCopy = rank === 1 ? "Copied last message to clipboard" : "Copied message to clipboard";
+
+	if (blocks.length === 0) {
+		return { id, label, hint: pluralLines(text), preview: text, content: text, copyMessage: messageCopy };
+	}
+
+	// The message node itself copies the full message; each block is a child
+	// copy target you can drill into, kept in document order.
+	const children: CopyTarget[] = [];
+	const codeBlocks: CodeBlock[] = [];
+	const quoteBlocks: QuoteBlock[] = [];
+	for (const block of blocks) {
+		if (block.kind === "code") {
+			const j = codeBlocks.length;
+			codeBlocks.push(block);
+			children.push({
+				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`,
+			});
+		} else {
+			const j = quoteBlocks.length;
+			quoteBlocks.push(block);
+			children.push({
+				id: `${id}:quote:${j}`,
+				label: `Quote ${j + 1}`,
+				hint: pluralLines(block.text),
+				preview: block.text,
+				content: block.text,
+				copyMessage: `Copied quote block ${j + 1} to clipboard`,
+			});
+		}
+	}
+
+	if (codeBlocks.length > 1) {
+		const combined = codeBlocks.map(b => b.code).join("\n\n");
+		children.push({
+			id: `${id}:all`,
+			label: `All ${codeBlocks.length} blocks`,
+			hint: pluralLines(combined),
+			preview: combined,
+			content: combined,
+			copyMessage: `Copied ${codeBlocks.length} code blocks to clipboard`,
+		});
+	}
+	if (quoteBlocks.length > 1) {
+		const combined = quoteBlocks.map(b => b.text).join("\n\n");
+		children.push({
+			id: `${id}:all-quotes`,
+			label: `All ${quoteBlocks.length} quotes`,
+			hint: pluralLines(combined),
+			preview: combined,
+			content: combined,
+			copyMessage: `Copied ${quoteBlocks.length} quote blocks to clipboard`,
+		});
+	}
+
+	const hint = blockSummaryHint(text, codeBlocks.length, quoteBlocks.length);
+	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;
+}