@sayknow-cli/coding-agent 0.3.6 → 0.3.7

package/src/modes/components/tree-selector.ts

@@ -135,6 +135,14 @@ class TreeList implements Component {
 		return this.#filteredNodes.length - 1;
 	}
 
+	#clampSelectedIndex(): void {
+		if (this.#filteredNodes.length === 0) {
+			this.#selectedIndex = 0;
+			return;
+		}
+		this.#selectedIndex = Math.max(0, Math.min(this.#selectedIndex, this.#filteredNodes.length - 1));
+	}
+
 	#flattenTree(roots: SessionTreeNode[]): FlatNode[] {
 		const result: FlatNode[] = [];
 		this.#toolCallMap.clear();
@@ -333,12 +341,11 @@ class TreeList implements Component {
 			return true;
 		});
 
-		// Try to preserve cursor on the same node, or find nearest visible ancestor
+		// Try to preserve cursor on the same node, or keep the index in range.
 		if (this.#lastSelectedId) {
 			this.#selectedIndex = this.#findNearestVisibleIndex(this.#lastSelectedId);
-		} else if (this.#selectedIndex >= this.#filteredNodes.length) {
-			// Clamp index if out of bounds
-			this.#selectedIndex = Math.max(0, this.#filteredNodes.length - 1);
+		} else {
+			this.#clampSelectedIndex();
 		}
 
 		// Update lastSelectedId to the actual selection (may have changed due to parent walk)
@@ -710,16 +717,29 @@ class TreeList implements Component {
 	}
 
 	handleInput(keyData: string): void {
+		const moveSelection = (delta: number, wrap: boolean): void => {
+			if (this.#filteredNodes.length === 0) return;
+			if (wrap) {
+				const next = this.#selectedIndex + delta;
+				this.#selectedIndex =
+					next < 0 ? this.#filteredNodes.length - 1 : next >= this.#filteredNodes.length ? 0 : next;
+			} else {
+				this.#selectedIndex += delta;
+				this.#clampSelectedIndex();
+			}
+			this.#lastSelectedId = this.#filteredNodes[this.#selectedIndex]?.node.entry.id ?? this.#lastSelectedId;
+		};
+
 		if (matchesKey(keyData, "up")) {
-			this.#selectedIndex = this.#selectedIndex === 0 ? this.#filteredNodes.length - 1 : this.#selectedIndex - 1;
+			moveSelection(-1, true);
 		} else if (matchesKey(keyData, "down")) {
-			this.#selectedIndex = this.#selectedIndex === this.#filteredNodes.length - 1 ? 0 : this.#selectedIndex + 1;
+			moveSelection(1, true);
 		} else if (matchesKey(keyData, "left")) {
 			// Page up
-			this.#selectedIndex = Math.max(0, this.#selectedIndex - this.maxVisibleLines);
+			moveSelection(-this.maxVisibleLines, false);
 		} else if (matchesKey(keyData, "right")) {
 			// Page down
-			this.#selectedIndex = Math.min(this.#filteredNodes.length - 1, this.#selectedIndex + this.maxVisibleLines);
+			moveSelection(this.maxVisibleLines, false);
 		} else if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
 			const selected = this.#filteredNodes[this.#selectedIndex];
 			if (selected && this.onSelect) {

package/src/modes/components/two-column-body.ts

@@ -0,0 +1,36 @@
+import { type Component, padding, truncateToWidth, visibleWidth } from "@sayknow-cli/tui";
+import { theme } from "../theme/theme";
+
+export class TwoColumnBody implements Component {
+	constructor(
+		private readonly leftPane: Component,
+		private readonly rightPane: Component,
+		private readonly maxHeight: number,
+	) {}
+
+	render(width: number): string[] {
+		const leftWidth = Math.floor(width * 0.5);
+		const separatorText = theme.fg("dim", ` ${theme.boxSharp.vertical} `);
+		const separatorWidth = width - leftWidth > 3 ? visibleWidth(separatorText) : 0;
+		const separator = separatorWidth > 0 ? separatorText : "";
+		const rightWidth = Math.max(0, width - leftWidth - separatorWidth);
+		const leftLines = this.leftPane.render(leftWidth);
+		const rightLines = this.rightPane.render(rightWidth);
+		const lineCount = Math.min(this.maxHeight, Math.max(leftLines.length, rightLines.length));
+		const out: string[] = [];
+
+		for (let i = 0; i < lineCount; i++) {
+			const left = truncateToWidth(leftLines[i] ?? "", leftWidth);
+			const leftPadded = left + padding(Math.max(0, leftWidth - visibleWidth(left)));
+			const right = truncateToWidth(rightLines[i] ?? "", rightWidth);
+			out.push(leftPadded + separator + right);
+		}
+
+		return out;
+	}
+
+	invalidate(): void {
+		this.leftPane.invalidate?.();
+		this.rightPane.invalidate?.();
+	}
+}

package/src/modes/components/welcome.ts

@@ -15,6 +15,12 @@ export interface LspServerInfo {
 }
 
 export type WelcomeLogoMode = "unicode" | "square" | "ascii";
+export interface WelcomeComponentOptions {
+	getViewportRows?: () => number | undefined;
+	getReservedBottomRows?: (termWidth: number) => number;
+	changelogMarkdown?: string;
+	collapseChangelog?: boolean;
+}
 
 /**
  * Sayknow-CLI launch surface: a blue-gradient SAYKNOW wordmark, compact
@@ -32,6 +38,7 @@ export class WelcomeComponent implements Component {
 		private recentSessions: RecentSession[] = [],
 		private lspServers: LspServerInfo[] = [],
 		private readonly logoMode: WelcomeLogoMode = "unicode",
+		private readonly options: WelcomeComponentOptions = {},
 	) {}
 
 	invalidate(): void {}
@@ -52,6 +59,11 @@ export class WelcomeComponent implements Component {
 			}
 			requestRender();
 		}, INTRO_TICK_MS);
+		this.#animTimer.unref?.();
+	}
+
+	dispose(): void {
+		this.#stopAnimation();
 	}
 
 	#stopAnimation(): void {
@@ -76,15 +88,20 @@ export class WelcomeComponent implements Component {
 	}
 
 	render(termWidth: number): string[] {
-		// Box dimensions track the live viewport so wide terminals feel intentionally full-screen.
-		const boxWidth = Math.max(0, termWidth - 2);
+		const boxWidth = Math.max(0, termWidth);
 		if (boxWidth < 4) {
 			return [];
 		}
+
+		const targetRows = this.#targetRows(termWidth);
+		if (targetRows !== undefined && targetRows <= 0) {
+			return [];
+		}
+		const targetContentRows = targetRows === undefined ? undefined : Math.max(0, targetRows - 2);
 		const dualContentWidth = boxWidth - 3; // 3 = │ + │ + │
-		const preferredLeftCol = 36;
-		const minLeftCol = 18; // wordmark plus Sayknow identity labels
-		const minRightCol = 20;
+		const preferredLeftCol = 40;
+		const minLeftCol = 20; // wordmark plus Sayknow identity labels
+		const minRightCol = 24;
 		const modelPill = this.#pill(theme.icon.model || "model", this.modelName, "statusLineModel");
 		const providerPill = this.#pill(theme.icon.package || "provider", this.providerName, "statusLinePath");
 		const logoLines = this.#logoLines();
@@ -130,24 +147,23 @@ export class WelcomeComponent implements Component {
 			...identityTail,
 		];
 
-		// Right column separator
-		const separatorWidth = Math.max(0, rightCol - 2); // padding on each side
-		const separator = ` ${theme.fg("dim", theme.boxRound.horizontal.repeat(separatorWidth))}`;
+		const buildSeparator = (columnWidth: number): string =>
+			` ${theme.fg("dim", theme.boxRound.horizontal.repeat(Math.max(0, columnWidth - 2)))}`;
+
+		const rightColumnWidth = showRightColumn ? rightCol : leftCol;
+		const separator = buildSeparator(rightColumnWidth);
+		const changelogBudget = Math.max(1, Math.min(6, Math.floor((targetContentRows ?? 18) * 0.3)));
 
-		// Recent sessions content
 		const sessionLines: string[] = [];
 		if (this.recentSessions.length === 0) {
 			sessionLines.push(` ${theme.fg("dim", t("welcome.noSessions"))}`);
 		} else {
-			// Reserve width for the bullet prefix (" • ") and the trailing " (timeAgo)"
-			// so the relative time is never the part that gets truncated. The name
-			// absorbs whatever space is left.
 			const bulletPrefix = ` ${theme.md.bullet} `;
 			const prefixWidth = visibleWidth(bulletPrefix);
 			for (const session of this.recentSessions.slice(0, 3)) {
 				const timeSuffixRaw = ` (${session.timeAgo})`;
 				const timeWidth = visibleWidth(timeSuffixRaw);
-				const nameBudget = Math.max(1, rightCol - prefixWidth - timeWidth);
+				const nameBudget = Math.max(1, rightColumnWidth - prefixWidth - timeWidth);
 				const nameVis = visibleWidth(session.name);
 				const name = nameVis > nameBudget ? truncateToWidth(session.name, nameBudget) : session.name;
 				sessionLines.push(
@@ -156,12 +172,11 @@ export class WelcomeComponent implements Component {
 			}
 		}
 
-		// LSP servers content
 		const lspLines: string[] = [];
 		if (this.lspServers.length === 0) {
 			lspLines.push(` ${theme.fg("dim", t("welcome.noLsp"))}`);
 		} else {
-			for (const server of this.lspServers) {
+			for (const server of this.lspServers.slice(0, 4)) {
 				const icon =
 					server.status === "ready"
 						? theme.styledSymbol("status.success", "success")
@@ -179,8 +194,11 @@ export class WelcomeComponent implements Component {
 			return ` ${theme.fg("accent", cmd)}${pad}${theme.fg("muted", desc)}`;
 		};
 
-		// Right column
 		const rightLines = [
+			"",
+			` ${theme.bold(theme.fg("accent", "What's New"))}`,
+			...this.#whatsNewLines(rightColumnWidth, changelogBudget),
+			separator,
 			` ${theme.bold(theme.fg("accent", t("welcome.workflows")))}`,
 			wf("/deep-interview", t("welcome.wf.deepInterview")),
 			wf("/ralplan", t("welcome.wf.ralplan")),
@@ -210,7 +228,12 @@ export class WelcomeComponent implements Component {
 			"",
 		];
 
-		// Border characters (dim)
+		const contentRows =
+			targetContentRows ??
+			(showRightColumn ? Math.max(leftLines.length, rightLines.length) : leftLines.length + rightLines.length);
+		const outputRows = targetRows === undefined ? Math.max(3, contentRows + 2) : targetRows;
+		const bodyRows = Math.max(0, outputRows - 2);
+
 		const hChar = theme.boxRound.horizontal;
 		const h = theme.fg("dim", hChar);
 		const v = theme.fg("dim", theme.boxRound.vertical);
@@ -220,8 +243,6 @@ export class WelcomeComponent implements Component {
 		const br = theme.fg("dim", theme.boxRound.bottomRight);
 
 		const lines: string[] = [];
-
-		// Top border with embedded title
 		const title = ` ${APP_NAME} · Sayknow-CLI v${this.version} `;
 		const titlePrefixRaw = hChar.repeat(3);
 		const titleStyled = theme.fg("dim", titlePrefixRaw) + theme.fg("muted", title);
@@ -233,22 +254,32 @@ export class WelcomeComponent implements Component {
 			const afterTitle = titleSpace - titleVisLen;
 			lines.push(tl + titleStyled + theme.fg("dim", hChar.repeat(afterTitle)) + tr);
 		}
+		if (outputRows === 1) {
+			return lines;
+		}
 
-		// Content rows
-		const maxRows = showRightColumn ? Math.max(leftLines.length, rightLines.length) : leftLines.length;
-		for (let i = 0; i < maxRows; i++) {
-			const left = this.#fitToWidth(leftLines[i] ?? "", leftCol);
-			if (showRightColumn) {
-				const right = this.#fitToWidth(rightLines[i] ?? "", rightCol);
+		if (showRightColumn) {
+			const leftBlock = this.#fitBlock(leftLines, bodyRows, "center");
+			const rightBlock = this.#fitBlock(rightLines, bodyRows, "top");
+			for (let i = 0; i < bodyRows; i++) {
+				const left = this.#fitToWidth(leftBlock[i] ?? "", leftCol);
+				const right = this.#fitToWidth(rightBlock[i] ?? "", rightCol);
 				lines.push(v + left + v + right + v);
-			} else {
-				lines.push(v + left + v);
 			}
-		}
-		// Bottom border
-		if (showRightColumn) {
 			lines.push(bl + h.repeat(leftCol) + theme.fg("dim", theme.boxSharp.teeUp) + h.repeat(rightCol) + br);
 		} else {
+			const compactLeftLines =
+				bodyRows < 14
+					? [
+							this.#centerText(theme.bold(theme.fg("accent", "SKC Forge")), leftCol),
+							this.#centerText(this.#loadingLine(), leftCol),
+							this.#centerText(modelPill, leftCol),
+						]
+					: leftLines;
+			const singleBlock = this.#fitBlock([...compactLeftLines, separator, ...rightLines], bodyRows, "top");
+			for (let i = 0; i < bodyRows; i++) {
+				lines.push(v + this.#fitToWidth(singleBlock[i] ?? "", leftCol) + v);
+			}
 			lines.push(bl + h.repeat(leftCol) + br);
 		}
 
@@ -274,6 +305,110 @@ export class WelcomeComponent implements Component {
 		}
 		return str + padding(width - visLen);
 	}
+	#targetRows(termWidth: number): number | undefined {
+		const viewportRows = this.options.getViewportRows?.();
+		if (typeof viewportRows !== "number" || !Number.isFinite(viewportRows) || viewportRows <= 0) {
+			return undefined;
+		}
+		const reservedRows = Math.max(0, Math.floor(this.options.getReservedBottomRows?.(termWidth) ?? 0));
+		return Math.max(0, Math.floor(viewportRows) - reservedRows);
+	}
+
+	#loadingLine(): string {
+		const frames = theme.spinnerFrames;
+		const elapsed = this.#animStart == null ? 0 : performance.now() - this.#animStart;
+		const frame = frames.length > 0 ? (frames[Math.floor(elapsed / 100) % frames.length] ?? "*") : "*";
+		const label = this.#animStart == null ? "ready" : "warming workspace";
+		return `${theme.fg("warning", frame)} ${theme.fg("muted", label)}`;
+	}
+
+	#fitBlock(lines: string[], rows: number, align: "top" | "center"): string[] {
+		if (rows <= 0) return [];
+		const clipped =
+			lines.length > rows
+				? rows === 1
+					? [theme.fg("dim", " …")]
+					: [...lines.slice(0, rows - 1), theme.fg("dim", " …")]
+				: lines;
+		const missingRows = rows - clipped.length;
+		if (missingRows <= 0) return clipped;
+		const topPad = align === "center" ? Math.floor(missingRows / 2) : 0;
+		const bottomPad = missingRows - topPad;
+		return [...Array.from({ length: topPad }, () => ""), ...clipped, ...Array.from({ length: bottomPad }, () => "")];
+	}
+
+	#whatsNewLines(width: number, maxItems: number): string[] {
+		const changelog = this.options.changelogMarkdown?.trim();
+		if (!changelog) {
+			return [` ${theme.fg("dim", "Ready for your next prompt")}`];
+		}
+
+		const version = this.#latestChangelogVersion(changelog);
+		if (this.options.collapseChangelog) {
+			return [
+				` ${theme.fg("muted", `Updated to v${version}`)}`,
+				` ${theme.fg("dim", `Use ${theme.bold("/changelog")} for details`)}`,
+			];
+		}
+
+		const itemLimit = Math.max(1, Math.floor(maxItems));
+		const items = this.#changelogItems(changelog);
+		if (items.length === 0) {
+			return [
+				` ${theme.fg("muted", `Updated to v${version}`)}`,
+				` ${theme.fg("dim", `Use ${theme.bold("/changelog")} for details`)}`,
+			];
+		}
+
+		const prefix = ` ${theme.md.bullet} `;
+		const textWidth = Math.max(1, width - visibleWidth(prefix));
+		const visibleItems = items.slice(0, itemLimit).map(item => {
+			const text = visibleWidth(item) > textWidth ? truncateToWidth(item, textWidth) : item;
+			return `${theme.fg("dim", prefix)}${theme.fg("muted", text)}`;
+		});
+		if (items.length > visibleItems.length) {
+			visibleItems.push(` ${theme.fg("dim", `… ${theme.bold("/changelog")} for full notes`)}`);
+		}
+		return visibleItems;
+	}
+
+	#latestChangelogVersion(markdown: string): string {
+		const versionMatch = markdown.match(/##\s+\[?(\d+\.\d+\.\d+)\]?/);
+		return versionMatch?.[1] ?? this.version;
+	}
+
+	#changelogItems(markdown: string): string[] {
+		const items: string[] = [];
+		let inFence = false;
+		for (const rawLine of markdown.split(/\r?\n/)) {
+			const line = rawLine.trim();
+			if (line.startsWith("```")) {
+				inFence = !inFence;
+				continue;
+			}
+			if (inFence || !line || /^#{1,6}\s+/.test(line) || /^-{3,}$/.test(line)) {
+				continue;
+			}
+			const withoutBullet = line
+				.replace(/^[-*]\s+/, "")
+				.replace(/^\d+\.\s+/, "")
+				.replace(/^>\s*/, "");
+			const cleaned = this.#stripMarkdown(withoutBullet);
+			if (cleaned) items.push(cleaned);
+		}
+		return items;
+	}
+
+	#stripMarkdown(text: string): string {
+		return text
+			.replace(/`([^`]+)`/g, "$1")
+			.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+			.replace(/\*\*([^*]+)\*\*/g, "$1")
+			.replace(/__([^_]+)__/g, "$1")
+			.replace(/\*([^*]+)\*/g, "$1")
+			.replace(/[_~]/g, "")
+			.trim();
+	}
 
 	#pill(icon: string, text: string, color: ThemeColor): string {
 		return `${theme.fg("borderMuted", "[")} ${theme.fg(color, icon)} ${theme.fg("muted", text)} ${theme.fg(

package/src/modes/controllers/command-controller.ts

@@ -556,6 +556,29 @@ export class CommandController {
 		showMarkdownPanel(this.ctx, "Keyboard Shortcuts", hotkeys);
 	}
 
+	handleHelpCommand(): void {
+		const sessionNewKey = this.ctx.keybindings.getDisplayString("app.session.new") || "/new";
+		const markdown = [
+			"**Beginner actions**",
+			"",
+			"| Action | How |",
+			"|---|---|",
+			`| Start a fresh session | \`${sessionNewKey}\` or \`/new\` |`,
+			"| Resume another session | `/resume` |",
+			"| Show session details | `/session info` |",
+			"| Delete current session | `/session delete` |",
+			"| Select a model | `/model` or `Ctrl+L` |",
+			"| Show all shortcuts | `?` on an empty prompt or `/hotkeys` |",
+			"",
+			"**Finding commands**",
+			"",
+			"- Type `/` to browse slash commands, then use arrows and Enter/Tab.",
+			"- Type `#` to browse prompt actions like starting a session, pasting an image, or moving the cursor.",
+			"- Type `!` for shell commands and `$` for Python snippets.",
+		].join("\n");
+		showMarkdownPanel(this.ctx, "SKC Help", markdown);
+	}
+
 	handleToolsCommand(): void {
 		const tools = buildToolsMarkdown({ tools: this.ctx.session.agent.state.tools });
 		showMarkdownPanel(this.ctx, "Available Tools", tools);
@@ -1253,17 +1276,18 @@ export class CommandController {
 	async handleContributionPrepCommand(customInstructions?: string): Promise<void> {
 		this.ctx.editor.setText("");
 		try {
-			const result = await this.ctx.session.prepareContributionPrep({ customInstructions, spawnWorker: true });
+			const result = await this.ctx.session.prepareContributionPrep({ customInstructions, spawnWorker: false });
 			this.ctx.showStatus(
 				[
 					"Contribution prep artifacts written.",
 					`Manifest: ${result.manifestPath}`,
 					`Worker prompt: ${result.workerPromptPath}`,
+					"Open the worker prompt from a separate terminal to keep this TUI session stable.",
 				].join("\n"),
 			);
 			this.ctx.chatContainer.addChild(
 				new Text(
-					`${theme.fg("accent", `${theme.status.success} Contribution prep ready`)}\nManifest: ${result.manifestPath}`,
+					`${theme.fg("accent", `${theme.status.success} Contribution prep ready`)}\nWorker prompt: ${result.workerPromptPath}`,
 					1,
 					1,
 				),

package/src/modes/controllers/event-controller.ts

@@ -138,6 +138,7 @@ export class EventController {
 			this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
 			this.ctx.retryEscapeHandler = undefined;
 		}
+		this.ctx.retryEscapePrimed = false;
 		if (this.ctx.retryLoader) {
 			this.ctx.retryLoader.stop();
 			this.ctx.retryLoader = undefined;
@@ -241,6 +242,7 @@ export class EventController {
 			this.ctx.retryLoader = undefined;
 			this.ctx.statusContainer.clear();
 		}
+		this.ctx.retryEscapePrimed = false;
 		this.#cancelIdleCompaction();
 		this.ctx.updateEditorBorderColor();
 		this.ctx.ensureLoadingAnimation();
@@ -768,6 +770,7 @@ export class EventController {
 		if (!this.ctx.retryEscapeHandler) {
 			this.ctx.retryEscapeHandler = this.ctx.editor.onEscape;
 		}
+		this.ctx.retryEscapePrimed = false;
 		let escPressed = false;
 		this.ctx.editor.onEscape = () => {
 			if (!escPressed) {
@@ -818,6 +821,7 @@ export class EventController {
 			this.ctx.retryLoader = undefined;
 			this.ctx.statusContainer.clear();
 		}
+		this.ctx.retryEscapePrimed = false;
 		if (!event.success) {
 			this.ctx.showError(`Retry failed after ${event.attempt} attempts: ${event.finalError || "Unknown error"}`);
 		}

package/src/modes/controllers/extension-ui-controller.ts

@@ -618,7 +618,8 @@ export class ExtensionUiController {
 		const listChromeRows = dialogOptions?.outline === true ? HOOK_SELECTOR_OUTLINE_ROWS : 0;
 		// Reserve rows for the inline custom-input editor so opening it doesn't
 		// push the scrollable title past the viewport into terminal scrollback.
-		const inlineInputRows = dialogOptions?.customInput ? HOOK_SELECTOR_INLINE_INPUT_ROWS : 0;
+		const inlineInputRows =
+			dialogOptions?.customInput || dialogOptions?.clarificationInput ? HOOK_SELECTOR_INLINE_INPUT_ROWS : 0;
 		const availableTitleRows =
 			this.ctx.ui.terminal.rows - scrollOptionRows - listChromeRows - inlineInputRows - HOOK_SELECTOR_CHROME_ROWS;
 		const scrollTitleRows =
@@ -660,7 +661,10 @@ export class ExtensionUiController {
 				tui: this.ctx.ui,
 				// Share the main prompt editor's autocomplete provider so the
 				// inline "Other (type your own)" editor supports `@` file links.
-				autocompleteProvider: dialogOptions?.customInput ? this.ctx.editor.getAutocompleteProvider() : undefined,
+				autocompleteProvider:
+					dialogOptions?.customInput || dialogOptions?.clarificationInput
+						? this.ctx.editor.getAutocompleteProvider()
+						: undefined,
 				outline: dialogOptions?.outline,
 				wrapFocused: dialogOptions?.wrapFocused,
 				scrollTitleRows,
@@ -676,6 +680,18 @@ export class ExtensionUiController {
 							},
 						}
 					: undefined,
+				clarificationInput: dialogOptions?.clarificationInput
+					? {
+							optionLabel: dialogOptions.clarificationInput.optionLabel,
+							allowEmpty: dialogOptions.clarificationInput.allowEmpty,
+							onSubmit: text => {
+								const optionLabel = dialogOptions.clarificationInput?.optionLabel;
+								this.hideHookSelector();
+								dialogOptions.clarificationInput?.onSubmit(text);
+								finish(optionLabel);
+							},
+						}
+					: undefined,
 			},
 		);
 		// Detach (not dispose) the reusable editor before mounting the transient hook UI, so the