gsd-pi 2.74.0-dev.6e23363 → 2.74.0-dev.703eabc

package/packages/pi-coding-agent/src/core/agent-session.ts

@@ -1558,9 +1558,12 @@ export class AgentSession {
 			}
 		}
 
-		this._disconnectFromAgent();
-		await this.abort();
-		this.agent.reset();
+	// #4243: Must call abort() BEFORE _disconnectFromAgent() so that
+	// message_end/agent_end events fire and the #4216 finalization code
+	// can run before we unsubscribe from the event bus.
+	await this.abort();
+	this._disconnectFromAgent();
+	this.agent.reset();
 		// Update cwd to current process directory — auto-mode may have chdir'd
 		// into a worktree since the original session was created.
 		const previousCwd = this._cwd;
@@ -2411,9 +2414,12 @@ export class AgentSession {
 			}
 		}
 
-		this._disconnectFromAgent();
-		await this.abort();
-		this._steeringMessages = [];
+	// #4243: Must call abort() BEFORE _disconnectFromAgent() so that
+	// message_end/agent_end events fire and the #4216 finalization code
+	// can run before we unsubscribe from the event bus.
+	await this.abort();
+	this._disconnectFromAgent();
+	this._steeringMessages = [];
 		this._followUpMessages = [];
 		this._pendingNextTurnMessages = [];
 

package/packages/pi-coding-agent/src/core/chat-controller-ordering.test.ts

@@ -234,7 +234,65 @@ test("chat-controller renders serverToolUse before trailing text matching conten
 	assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent");
 });
 
-test("chat-controller drops provisional pre-tool text for claude-code MCP turns", async () => {
+test("chat-controller replays final message_end content when result adds unstreamed trailing text", async () => {
+	(globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = {
+		fg: (_key: string, text: string) => text,
+		bg: (_key: string, text: string) => text,
+		bold: (text: string) => text,
+		italic: (text: string) => text,
+		truncate: (text: string) => text,
+	};
+
+	const host = createHost();
+	host.getMarkdownThemeWithSettings = () => ({});
+
+	const tool = {
+		type: "toolCall",
+		id: "mcp-end-replay-1",
+		name: "read",
+		mcpServer: "filesystem",
+		arguments: { filePath: "/tmp/demo.txt" },
+	};
+
+	await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any);
+
+	const streamedContent = [
+		tool,
+		{ type: "thinking", thinking: "I am analyzing tool output..." },
+	];
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant(streamedContent),
+			assistantMessageEvent: {
+				type: "thinking_delta",
+				contentIndex: 1,
+				delta: "I am analyzing tool output...",
+				partial: makeAssistant(streamedContent),
+			},
+		} as any,
+	);
+
+	assert.equal(host.chatContainer.children.length, 2, "streaming shows tool + thinking only");
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent");
+	assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent");
+
+	// Final payload includes trailing text that never arrived as message_update.
+	const finalContent = [
+		tool,
+		{ type: "thinking", thinking: "I am analyzing tool output..." },
+		{ type: "text", text: "Correct anything important I missed?" },
+	];
+	await handleAgentEvent(host, { type: "message_end", message: makeAssistant(finalContent) } as any);
+
+	assert.equal(host.chatContainer.children.length, 3, "message_end should replay and include trailing text segment");
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent");
+	assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent");
+	assert.equal(host.chatContainer.children[2]?.constructor?.name, "AssistantMessageComponent");
+});
+
+test("chat-controller keeps pre-tool prose visible until post-tool prose arrives, then prunes it", async () => {
 	(globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = {
 		fg: (_key: string, text: string) => text,
 		bg: (_key: string, text: string) => text,
@@ -273,7 +331,7 @@ test("chat-controller drops provisional pre-tool text for claude-code MCP turns"
 	assert.equal(host.chatContainer.children.length, 1);
 	assert.equal(host.chatContainer.children[0]?.constructor?.name, "AssistantMessageComponent");
 
-	// MCP tool appears; provisional text should be removed from the chat stack.
+	// MCP tool appears; provisional text should remain visible until post-tool prose exists.
 	await handleAgentEvent(
 		host,
 		{
@@ -294,11 +352,16 @@ test("chat-controller drops provisional pre-tool text for claude-code MCP turns"
 			},
 		} as any,
 	);
-	assert.equal(host.chatContainer.children.length, 1, "provisional pre-tool text should be pruned");
-	assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent");
+	assert.equal(host.chatContainer.children.length, 2, "pre-tool prose should remain during tool-only window");
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "AssistantMessageComponent");
+	assert.equal(host.chatContainer.children[1]?.constructor?.name, "ToolExecutionComponent");
 
-	// Final assistant output should render below the tool.
-	const finalContent = [mcpTool, { type: "text", text: "Which missing feature matters most to you?" }];
+	// Post-tool prose arrives: pre-tool prose should now be pruned.
+	const finalContent = [
+		{ type: "text", text: "Let me inspect the workspace first." },
+		mcpTool,
+		{ type: "text", text: "Which missing feature matters most to you?" },
+	];
 	await handleAgentEvent(
 		host,
 		{
@@ -306,7 +369,7 @@ test("chat-controller drops provisional pre-tool text for claude-code MCP turns"
 			message: makeAssistant(finalContent),
 			assistantMessageEvent: {
 				type: "text_delta",
-				contentIndex: 1,
+				contentIndex: 2,
 				delta: "Which missing feature matters most to you?",
 				partial: makeAssistant(finalContent),
 			},
@@ -320,6 +383,389 @@ test("chat-controller drops provisional pre-tool text for claude-code MCP turns"
 	await handleAgentEvent(host, { type: "message_end", message: makeAssistant(finalContent) } as any);
 });
 
+test("chat-controller keeps pre-tool thinking visible for claude-code MCP turns without post-tool prose", async () => {
+	(globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = {
+		fg: (_key: string, text: string) => text,
+		bg: (_key: string, text: string) => text,
+		bold: (text: string) => text,
+		italic: (text: string) => text,
+		truncate: (text: string) => text,
+	};
+
+	const host = createHost();
+	host.getMarkdownThemeWithSettings = () => ({});
+
+	const mcpTool = {
+		type: "toolCall",
+		id: "mcp-tool-thinking-1",
+		name: "read",
+		mcpServer: "filesystem",
+		arguments: { filePath: "/tmp/demo.txt" },
+	};
+
+	await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any);
+
+	const thinkingOnly = [{ type: "thinking", thinking: "I should inspect the workspace." }];
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant(thinkingOnly),
+			assistantMessageEvent: {
+				type: "thinking_delta",
+				contentIndex: 0,
+				delta: "I should inspect the workspace.",
+				partial: makeAssistant(thinkingOnly),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 1);
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "AssistantMessageComponent");
+
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant([thinkingOnly[0], mcpTool]),
+			assistantMessageEvent: {
+				type: "toolcall_end",
+				contentIndex: 1,
+				toolCall: {
+					...mcpTool,
+					externalResult: {
+						content: [{ type: "text", text: "file preview" }],
+						details: {},
+						isError: false,
+					},
+				},
+				partial: makeAssistant([thinkingOnly[0], mcpTool]),
+			},
+		} as any,
+	);
+
+	assert.equal(host.chatContainer.children.length, 2, "thinking should remain visible while only tool output is present");
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "AssistantMessageComponent");
+	assert.equal(host.chatContainer.children[1]?.constructor?.name, "ToolExecutionComponent");
+
+	await handleAgentEvent(host, { type: "message_end", message: makeAssistant([thinkingOnly[0], mcpTool]) } as any);
+});
+
+test("chat-controller keeps pre-tool question text for claude-code MCP when post-tool prose exists", async () => {
+	(globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = {
+		fg: (_key: string, text: string) => text,
+		bg: (_key: string, text: string) => text,
+		bold: (text: string) => text,
+		italic: (text: string) => text,
+		truncate: (text: string) => text,
+	};
+
+	const host = createHost();
+	host.getMarkdownThemeWithSettings = () => ({});
+
+	const mcpTool = {
+		type: "toolCall",
+		id: "mcp-tool-question-1",
+		name: "glob",
+		mcpServer: "filesystem",
+		arguments: { pattern: "**/*" },
+	};
+
+	await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any);
+
+	const questionText = { type: "text", text: "Which file should I inspect?" };
+
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant([questionText]),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 0,
+				delta: questionText.text,
+				partial: makeAssistant([questionText]),
+			},
+		} as any,
+	);
+
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant([questionText, mcpTool]),
+			assistantMessageEvent: {
+				type: "toolcall_end",
+				contentIndex: 1,
+				toolCall: {
+					...mcpTool,
+					externalResult: {
+						content: [{ type: "text", text: "glob output" }],
+						details: {},
+						isError: false,
+					},
+				},
+				partial: makeAssistant([questionText, mcpTool]),
+			},
+		} as any,
+	);
+
+	const postTool = { type: "text", text: "I'll review that next." };
+	const finalContent = [questionText, mcpTool, postTool];
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant(finalContent),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 2,
+				delta: postTool.text,
+				partial: makeAssistant(finalContent),
+			},
+		} as any,
+	);
+
+	assert.equal(host.chatContainer.children.length, 3, "question text should remain alongside MCP tool and post-tool prose");
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "AssistantMessageComponent", "pre-tool question stays visible");
+	assert.equal(host.chatContainer.children[1]?.constructor?.name, "ToolExecutionComponent", "tool renders in the middle");
+	assert.equal(host.chatContainer.children[2]?.constructor?.name, "AssistantMessageComponent", "post-tool prose renders last");
+
+	await handleAgentEvent(host, { type: "message_end", message: makeAssistant(finalContent) } as any);
+});
+
+test("chat-controller prunes orphaned provisional text after claude-code sub-turn shrink when MCP tools appear", async () => {
+	(globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = {
+		fg: (_key: string, text: string) => text,
+		bg: (_key: string, text: string) => text,
+		bold: (text: string) => text,
+		italic: (text: string) => text,
+		truncate: (text: string) => text,
+	};
+
+	const host = createHost();
+	host.getMarkdownThemeWithSettings = () => ({});
+
+	const mcpTool = {
+		type: "toolCall",
+		id: "mcp-tool-shrink-1",
+		name: "glob",
+		mcpServer: "filesystem",
+		arguments: { pattern: "**/*" },
+	};
+
+	await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any);
+
+	// Sub-turn 1: generate longer provisional text content.
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant([{ type: "text", text: "Old provisional preface." }, { type: "text", text: "More old text." }]),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 1,
+				delta: "More old text.",
+				partial: makeAssistant([{ type: "text", text: "Old provisional preface." }, { type: "text", text: "More old text." }]),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 1, "first sub-turn text run should render");
+
+	// Sub-turn 2 starts (content shrink): old component is orphaned by design.
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant([{ type: "text", text: "New provisional text before tool." }]),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 0,
+				delta: "New provisional text before tool.",
+				partial: makeAssistant([{ type: "text", text: "New provisional text before tool." }]),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 2, "shrink keeps prior text until MCP tool context appears");
+
+	// MCP tool appears in sub-turn 2: tool-only windows keep provisional prose visible.
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant([{ type: "text", text: "New provisional text before tool." }, mcpTool]),
+			assistantMessageEvent: {
+				type: "toolcall_end",
+				contentIndex: 1,
+				toolCall: {
+					...mcpTool,
+					externalResult: {
+						content: [{ type: "text", text: "glob output" }],
+						details: {},
+						isError: false,
+					},
+				},
+				partial: makeAssistant([{ type: "text", text: "New provisional text before tool." }, mcpTool]),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 3, "stale text runs are deferred until post-tool prose arrives");
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "AssistantMessageComponent");
+	assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent");
+	assert.equal(host.chatContainer.children[2]?.constructor?.name, "ToolExecutionComponent");
+
+	const finalContent = [mcpTool, { type: "text", text: "Final visible question?" }];
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant(finalContent),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 1,
+				delta: "Final visible question?",
+				partial: makeAssistant(finalContent),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 2);
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent");
+	assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent");
+
+	await handleAgentEvent(host, { type: "message_end", message: makeAssistant(finalContent) } as any);
+});
+
+test("chat-controller prunes orphans from multiple sub-turn shrinks before MCP post-tool prose", async () => {
+	(globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = {
+		fg: (_key: string, text: string) => text,
+		bg: (_key: string, text: string) => text,
+		bold: (text: string) => text,
+		italic: (text: string) => text,
+		truncate: (text: string) => text,
+	};
+
+	const host = createHost();
+	host.getMarkdownThemeWithSettings = () => ({});
+
+	const mcpTool = {
+		type: "toolCall",
+		id: "mcp-tool-multi-shrink-1",
+		name: "glob",
+		mcpServer: "filesystem",
+		arguments: { pattern: "**/*" },
+	};
+
+	await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any);
+
+	// Sub-turn 1: 3 text blocks (merged into one text-run).
+	const subTurn1 = [
+		{ type: "text", text: "First provisional A." },
+		{ type: "text", text: "First provisional B." },
+		{ type: "text", text: "First provisional C." },
+	];
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant(subTurn1),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 2,
+				delta: "First provisional C.",
+				partial: makeAssistant(subTurn1),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 1, "first sub-turn renders 1 text-run");
+
+	// Sub-turn 2 (first shrink 3 → 2 blocks).
+	const subTurn2 = [
+		{ type: "text", text: "Second provisional A." },
+		{ type: "text", text: "Second provisional B." },
+	];
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant(subTurn2),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 1,
+				delta: "Second provisional B.",
+				partial: makeAssistant(subTurn2),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 2, "first shrink appends, keeps prior text as frozen history");
+
+	// Sub-turn 3 (second shrink 2 → 1 block). This is the critical step —
+	// without orphan accumulation, sub-turn 1's orphaned segment would be
+	// dropped from tracking here and later strand in the container.
+	const subTurn3 = [{ type: "text", text: "Third provisional." }];
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant(subTurn3),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 0,
+				delta: "Third provisional.",
+				partial: makeAssistant(subTurn3),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 3, "second shrink appends again, still no prune (no post-tool text)");
+
+	// MCP tool appears — tool-only window still keeps provisional prose visible.
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant([{ type: "text", text: "Third provisional." }, mcpTool]),
+			assistantMessageEvent: {
+				type: "toolcall_end",
+				contentIndex: 1,
+				toolCall: {
+					...mcpTool,
+					externalResult: {
+						content: [{ type: "text", text: "glob output" }],
+						details: {},
+						isError: false,
+					},
+				},
+				partial: makeAssistant([{ type: "text", text: "Third provisional." }, mcpTool]),
+			},
+		} as any,
+	);
+	assert.equal(host.chatContainer.children.length, 4, "tool-only window keeps all three provisional text-runs");
+
+	// Final post-tool text arrives — prune must drop ALL three pre-tool
+	// provisional text-runs across both shrinks, leaving only tool + final text.
+	const finalContent = [mcpTool, { type: "text", text: "Final answer." }];
+	await handleAgentEvent(
+		host,
+		{
+			type: "message_update",
+			message: makeAssistant(finalContent),
+			assistantMessageEvent: {
+				type: "text_delta",
+				contentIndex: 1,
+				delta: "Final answer.",
+				partial: makeAssistant(finalContent),
+			},
+		} as any,
+	);
+	assert.equal(
+		host.chatContainer.children.length,
+		2,
+		"all pre-tool provisional segments from every shrink must be pruned once post-tool prose arrives",
+	);
+	assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent");
+	assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent");
+
+	await handleAgentEvent(host, { type: "message_end", message: makeAssistant(finalContent) } as any);
+});
+
 test("chat-controller pins latest assistant text above editor when tool calls are present", async () => {
 	(globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = {
 		fg: (_key: string, text: string) => text,

package/packages/pi-coding-agent/src/modes/interactive/components/__tests__/tool-execution.test.ts

@@ -48,6 +48,25 @@ function renderToolCollapsed(
 }
 
 describe("ToolExecutionComponent", () => {
+	test("renders framed header with Running status while tool is partial", () => {
+		const rendered = renderToolCollapsed("mcp__demo__do_thing", { ok: true });
+
+		assert.match(rendered, /Tool demo\u00b7do_thing/);
+		assert.match(rendered, /Running/);
+	});
+
+	test("renders framed header with Error status for failed tool result", () => {
+		const rendered = renderTool(
+			"mcp__demo__do_thing",
+			{ ok: true },
+			{ content: [{ type: "text", text: "boom" }], isError: true },
+		);
+
+		assert.match(rendered, /Tool demo\u00b7do_thing/);
+		assert.match(rendered, /Error/);
+		assert.match(rendered, /boom/);
+	});
+
 	test("renders capitalized Claude Code Bash tool names with bash output instead of generic args JSON", () => {
 		const rendered = renderTool(
 			"Bash",

package/packages/pi-coding-agent/src/modes/interactive/components/assistant-message.ts

@@ -1,7 +1,8 @@
 import type { AssistantMessage } from "@gsd/pi-ai";
 import { Container, Markdown, type MarkdownTheme, Spacer, Text } from "@gsd/pi-tui";
 import { getMarkdownTheme, theme } from "../theme/theme.js";
-import { formatTimestamp, type TimestampFormat } from "./timestamp.js";
+import { type TimestampFormat } from "./timestamp.js";
+import { renderChatFrame } from "./chat-frame.js";
 
 export interface ContentRange {
 	startIndex: number;
@@ -89,10 +90,10 @@ export class AssistantMessageComponent extends Container {
 		);
 		const hasTextContent = message.content.some((c) => c.type === "text" && c.text.trim().length > 0);
 		const hasToolContent = message.content.some((c) => c.type === "toolCall" || c.type === "serverToolUse");
-
-		if (hasVisibleContent) {
-			this.contentContainer.addChild(new Spacer(1));
-		}
+		// Claude Code often emits long reasoning blocks ahead of user-visible text/tool
+		// output in the same lifecycle. Keep chat output visible without requiring a
+		// manual thinking toggle every turn.
+		const shouldCapThinking = hasTextContent || hasToolContent || message.provider === "claude-code";
 
 		// Render content in order; non-text/thinking blocks are silently skipped
 		for (let i = 0; i < slice.length; i++) {
@@ -122,7 +123,7 @@ export class AssistantMessageComponent extends Container {
 					});
 					// Keep visible chat output readable when thinking traces are long.
 					// Tool-bearing turns can stream text in a later assistant message.
-					if (hasTextContent || hasToolContent) {
+					if (shouldCapThinking) {
 						thinkingMarkdown.maxLines = 8;
 					}
 					this.contentContainer.addChild(thinkingMarkdown);
@@ -156,10 +157,24 @@ export class AssistantMessageComponent extends Container {
 				}
 			}
 
-			if (message.stopReason && message.timestamp) {
-				const timeStr = formatTimestamp(message.timestamp, this.timestampFormat);
-				this.contentContainer.addChild(new Text(theme.fg("dim", timeStr), 1, 0));
-			}
 		}
 	}
+
+	override render(width: number): string[] {
+		const frameWidth = Math.max(20, width);
+		const contentWidth = Math.max(1, frameWidth - 4);
+		const lines = super.render(contentWidth);
+		const headerLabel = this.lastMessage?.model ? `GSD - ${this.lastMessage.model}` : "GSD";
+		const framed = renderChatFrame(lines, frameWidth, {
+			label: headerLabel,
+			tone: "assistant",
+			timestamp: this.lastMessage?.timestamp,
+			timestampFormat: this.timestampFormat,
+			showTimestamp: this.showMetadata,
+		});
+		if (framed.length === 0) {
+			return framed;
+		}
+		return ["", ...framed];
+	}
 }

package/packages/pi-coding-agent/src/modes/interactive/components/chat-frame.ts

@@ -0,0 +1,67 @@
+import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
+import { theme } from "../theme/theme.js";
+import { formatTimestamp, type TimestampFormat } from "./timestamp.js";
+
+type FrameTone = "assistant" | "user";
+
+function trimOuterBlankLines(lines: string[]): string[] {
+	let start = 0;
+	let end = lines.length;
+	while (start < end && lines[start].trim().length === 0) start++;
+	while (end > start && lines[end - 1].trim().length === 0) end--;
+	return lines.slice(start, end);
+}
+
+export function renderChatFrame(
+	contentLines: string[],
+	width: number,
+	opts: {
+		label: string;
+		tone: FrameTone;
+		timestamp?: number;
+		timestampFormat: TimestampFormat;
+		showTimestamp?: boolean;
+	},
+): string[] {
+	const outerWidth = Math.max(20, width);
+	const contentWidth = Math.max(1, outerWidth - 2); // "│ " + content
+	const borderColor = opts.tone === "user" ? "borderAccent" : "border";
+	const borderMuted = opts.tone === "user" ? "borderMuted" : "borderMuted";
+	const border = (s: string) => theme.fg(borderColor, s);
+	const leftRaw = `• ${opts.label}`;
+	const rightRaw =
+		opts.showTimestamp === false || !opts.timestamp
+			? ""
+			: formatTimestamp(opts.timestamp, opts.timestampFormat);
+
+	const leftBudget = rightRaw
+		? Math.max(1, outerWidth - visibleWidth(rightRaw) - 1)
+		: outerWidth;
+	const left = truncateToWidth(leftRaw, leftBudget, "");
+	const leftStyled =
+		opts.tone === "user"
+			? theme.fg("accent", theme.bold(left))
+			: theme.fg("muted", theme.bold(left));
+	const rightStyled = rightRaw ? theme.fg("dim", rightRaw) : "";
+	const gap =
+		rightRaw.length > 0
+			? Math.max(
+					1,
+					outerWidth - visibleWidth(leftStyled) - visibleWidth(rightStyled),
+				)
+			: Math.max(0, outerWidth - visibleWidth(leftStyled));
+	const headerRow = `${leftStyled}${" ".repeat(gap)}${rightStyled}`;
+	const headerPad = Math.max(0, outerWidth - visibleWidth(headerRow));
+
+	const sourceLines = trimOuterBlankLines(contentLines);
+	const bodyLines = (sourceLines.length > 0 ? sourceLines : [""]).map((line) => {
+		const clipped = truncateToWidth(line, contentWidth, "");
+		return border("│ ") + clipped;
+	});
+
+	return [
+		theme.fg(borderMuted, "─".repeat(outerWidth)),
+		headerRow + " ".repeat(headerPad),
+		...bodyLines,
+	];
+}