@wahack/pi-coding-agent 15.11.0

package/src/modes/components/welcome.ts

@@ -0,0 +1,493 @@
+import {
+	type Component,
+	padding,
+	replaceTabs,
+	TERMINAL,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from './stubs/tui/index.ts';
+import { APP_NAME } from "@oh-my-pi/pi-utils";
+import { theme } from "../../modes/theme/theme";
+import tipsText from "./tips.txt" with { type: "text" };
+
+/** Tips embedded at build time, one per line; blanks dropped. */
+const TIPS: readonly string[] = tipsText
+	.split("\n")
+	.map(line => line.trim())
+	.filter(line => line.length > 0);
+
+/**
+ * Fixed number of session rows in the welcome box so its height stays stable
+ * across recent-session updates.
+ */
+export const WELCOME_SESSION_SLOTS = 4;
+
+/**
+ * Fixed number of LSP-server rows, for the same reason. Overflow is sliced so
+ * the box height is constant regardless of how many servers a project has.
+ */
+export const WELCOME_LSP_SLOTS = 4;
+
+export function renderWelcomeTip(tip: string, boxWidth: number): string[] {
+	const label = "Tip: ";
+	const labelWidth = visibleWidth(label);
+	const bodyBudget = boxWidth - 1 - labelWidth; // 1 = leading indent
+	if (bodyBudget < 8) return [];
+
+	const wrappedBody = wrapTextWithAnsi(replaceTabs(tip), bodyBudget);
+	if (wrappedBody.length === 0) return [];
+
+	const encoding = TERMINAL.trueColor ? "ansi-16m" : "ansi-256";
+	const purple = Bun.color("#b48cff", encoding) ?? "";
+	const lightBlue = Bun.color("#9ccfff", encoding) ?? "";
+	const italic = "\x1b[3m";
+	const dim = "\x1b[2m";
+	const reset = "\x1b[0m";
+	const continuationIndent = padding(labelWidth);
+
+	return wrappedBody.map((body, index) =>
+		index === 0
+			? ` ${italic}${purple}${label}${dim}${lightBlue}${body}${reset}`
+			: ` ${italic}${continuationIndent}${dim}${lightBlue}${body}${reset}`,
+	);
+}
+
+export interface RecentSession {
+	name: string;
+	timeAgo: string;
+}
+
+export interface LspServerInfo {
+	name: string;
+	status: "ready" | "error" | "connecting" | "available";
+	fileTypes: string[];
+}
+
+/**
+ * Premium welcome screen with block-based OMP logo and two-column layout.
+ */
+export class WelcomeComponent implements Component {
+	#animStart: number | null = null;
+	#animTimer: ReturnType<typeof setInterval> | null = null;
+	/** Tip chosen once per instance so re-renders (intro, LSP updates) don't shuffle it. */
+	readonly #tip: string | undefined = TIPS.length > 0 ? TIPS[Math.floor(Math.random() * TIPS.length)] : undefined;
+	// Render cache: the welcome box is the first transcript-area component, so
+	// returning a stable array reference keeps the whole frame prefix stable.
+	// Bypassed while the intro animation runs (every frame differs).
+	#cachedWidth = -1;
+	#cachedLines: string[] | undefined;
+
+	constructor(
+		private readonly version: string,
+		private modelName: string,
+		private providerName: string,
+		private recentSessions: RecentSession[] = [],
+		private lspServers: LspServerInfo[] = [],
+	) {}
+
+	invalidate(): void {
+		this.#cachedWidth = -1;
+		this.#cachedLines = undefined;
+	}
+
+	/**
+	 * Play a one-shot intro that sweeps the gradient through every phase
+	 * before settling on the resting frame. Safe to call multiple times —
+	 * subsequent calls reset and replay.
+	 */
+	playIntro(requestRender: () => void): void {
+		this.#stopAnimation();
+		this.#animStart = performance.now();
+		requestRender();
+		this.#animTimer = setInterval(() => {
+			const elapsed = performance.now() - (this.#animStart ?? 0);
+			if (elapsed >= INTRO_MS) {
+				this.#stopAnimation();
+			}
+			requestRender();
+		}, INTRO_TICK_MS);
+	}
+
+	#stopAnimation(): void {
+		if (this.#animTimer != null) {
+			clearInterval(this.#animTimer);
+			this.#animTimer = null;
+		}
+		this.#animStart = null;
+		// The settled (resting) frame differs from the last intro frame.
+		this.invalidate();
+	}
+
+	setModel(modelName: string, providerName: string): void {
+		this.modelName = modelName;
+		this.providerName = providerName;
+		this.invalidate();
+	}
+
+	setRecentSessions(sessions: RecentSession[]): void {
+		this.recentSessions = sessions;
+		this.invalidate();
+	}
+
+	setLspServers(servers: LspServerInfo[]): void {
+		this.lspServers = servers;
+		this.invalidate();
+	}
+
+	render(termWidth: number): readonly string[] {
+		const animating = this.#animStart != null;
+		if (!animating && this.#cachedLines && this.#cachedWidth === termWidth) {
+			return this.#cachedLines;
+		}
+		const lines = this.#renderLines(termWidth);
+		if (animating) {
+			this.#cachedLines = undefined;
+			this.#cachedWidth = -1;
+		} else {
+			this.#cachedLines = lines;
+			this.#cachedWidth = termWidth;
+		}
+		return lines;
+	}
+
+	#renderLines(termWidth: number): string[] {
+		// Box dimensions - responsive with max width and small-terminal support
+		const maxWidth = 100;
+		const boxWidth = Math.min(maxWidth, Math.max(0, termWidth - 2));
+		if (boxWidth < 4) {
+			return [];
+		}
+		const dualContentWidth = boxWidth - 3; // 3 = │ + │ + │
+		const preferredLeftCol = 26;
+		const minLeftCol = 12; // logo width
+		const minRightCol = 20;
+		const leftMinContentWidth = Math.max(
+			minLeftCol,
+			visibleWidth("Welcome back!"),
+			visibleWidth(this.modelName),
+			visibleWidth(this.providerName),
+		);
+		const desiredLeftCol = Math.min(preferredLeftCol, Math.max(minLeftCol, Math.floor(dualContentWidth * 0.35)));
+		const dualLeftCol =
+			dualContentWidth >= minRightCol + 1
+				? Math.min(desiredLeftCol, dualContentWidth - minRightCol)
+				: Math.max(1, dualContentWidth - 1);
+		const dualRightCol = Math.max(1, dualContentWidth - dualLeftCol);
+		const showRightColumn = dualLeftCol >= leftMinContentWidth && dualRightCol >= minRightCol;
+		const leftCol = showRightColumn ? dualLeftCol : boxWidth - 2;
+		const rightCol = showRightColumn ? dualRightCol : 0;
+
+		// Logo: pick a frame from the intro animation if active, else the resting frame.
+		const logoColored = this.#currentLogoFrame();
+
+		// Left column - centered content
+		const leftLines = [
+			"",
+			this.#centerText(theme.bold("Welcome back!"), leftCol),
+			"",
+			...logoColored.map(l => this.#centerText(l, leftCol)),
+			"",
+			this.#centerText(theme.fg("muted", this.modelName), leftCol),
+			this.#centerText(theme.fg("borderMuted", this.providerName), leftCol),
+		];
+
+		// Right column separator
+		const separatorWidth = Math.max(0, rightCol - 2); // padding on each side
+		const separator = ` ${theme.fg("dim", theme.boxRound.horizontal.repeat(separatorWidth))}`;
+
+		// Recent sessions content
+		const sessionLines: string[] = [];
+		if (this.recentSessions.length === 0) {
+			sessionLines.push(` ${theme.fg("dim", "No recent sessions")}`);
+		} 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, WELCOME_SESSION_SLOTS)) {
+				const timeSuffixRaw = ` (${session.timeAgo})`;
+				const timeWidth = visibleWidth(timeSuffixRaw);
+				const nameBudget = Math.max(1, rightCol - prefixWidth - timeWidth);
+				const nameVis = visibleWidth(session.name);
+				const name = nameVis > nameBudget ? truncateToWidth(session.name, nameBudget) : session.name;
+				sessionLines.push(
+					`${theme.fg("dim", bulletPrefix)}${theme.fg("muted", name)}${theme.fg("dim", timeSuffixRaw)}`,
+				);
+			}
+		}
+		// Pad to the fixed slot count so the box height doesn't depend on session count.
+		while (sessionLines.length < WELCOME_SESSION_SLOTS) {
+			sessionLines.push("");
+		}
+
+		// LSP servers content
+		const lspLines: string[] = [];
+		if (this.lspServers.length === 0) {
+			lspLines.push(` ${theme.fg("dim", "No LSP servers")}`);
+		} else {
+			for (const server of this.lspServers.slice(0, WELCOME_LSP_SLOTS)) {
+				const icon =
+					server.status === "ready"
+						? theme.styledSymbol("status.enabled", "success")
+						: server.status === "available"
+							? theme.styledSymbol("status.enabled", "dim")
+							: server.status === "connecting"
+								? theme.styledSymbol("status.pending", "muted")
+								: theme.styledSymbol("status.error", "error");
+				const exts = server.fileTypes.slice(0, 3).join(" ");
+				lspLines.push(` ${icon} ${theme.fg("muted", server.name)} ${theme.fg("dim", exts)}`);
+			}
+		}
+		// Pad to the fixed slot count so the box height doesn't depend on server count.
+		while (lspLines.length < WELCOME_LSP_SLOTS) {
+			lspLines.push("");
+		}
+
+		// Right column
+		const rightLines = [
+			` ${theme.bold(theme.fg("accent", "Tips"))}`,
+			` ${theme.fg("dim", "?")}${theme.fg("muted", " for keyboard shortcuts")}`,
+			` ${theme.fg("dim", "#")}${theme.fg("muted", " for prompt actions")}`,
+			` ${theme.fg("dim", "/")}${theme.fg("muted", " for commands")}`,
+			` ${theme.fg("dim", "!")}${theme.fg("muted", " to run bash")}`,
+			` ${theme.fg("dim", "$")}${theme.fg("muted", " to run python")}`,
+			separator,
+			` ${theme.bold(theme.fg("accent", "LSP Servers"))}`,
+			...lspLines,
+			separator,
+			` ${theme.bold(theme.fg("accent", "Recent sessions"))}`,
+			...sessionLines,
+			"",
+		];
+
+		// Border characters (dim)
+		const hChar = theme.boxRound.horizontal;
+		const h = theme.fg("dim", hChar);
+		const v = theme.fg("dim", theme.boxRound.vertical);
+		const tl = theme.fg("dim", theme.boxRound.topLeft);
+		const tr = theme.fg("dim", theme.boxRound.topRight);
+		const bl = theme.fg("dim", theme.boxRound.bottomLeft);
+		const br = theme.fg("dim", theme.boxRound.bottomRight);
+
+		const lines: string[] = [];
+
+		// Top border with embedded title
+		const title = ` ${APP_NAME} v${this.version} `;
+		const titlePrefixRaw = hChar.repeat(3);
+		const titleStyled = theme.fg("dim", titlePrefixRaw) + theme.fg("muted", title);
+		const titleVisLen = visibleWidth(titlePrefixRaw) + visibleWidth(title);
+		const titleSpace = boxWidth - 2;
+		if (titleVisLen >= titleSpace) {
+			lines.push(tl + truncateToWidth(titleStyled, titleSpace) + tr);
+		} else {
+			const afterTitle = titleSpace - titleVisLen;
+			lines.push(tl + titleStyled + theme.fg("dim", hChar.repeat(afterTitle)) + tr);
+		}
+
+		// 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);
+				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 {
+			lines.push(bl + h.repeat(leftCol) + br);
+		}
+
+		// Randomly picked tip, rendered directly beneath the box.
+		lines.push(...this.#renderTip(boxWidth));
+
+		return lines;
+	}
+
+	/**
+	 * Render the per-instance tip line: a purple "Tip:" label followed by the
+	 * tip body in dimmed light blue, the whole line italicized. Returns `[]`
+	 * when no tip is available or the box is too narrow to be useful.
+	 */
+	#renderTip(boxWidth: number): string[] {
+		if (!this.#tip) return [];
+		return renderWelcomeTip(this.#tip, boxWidth);
+	}
+
+	/** Center text within a given width */
+	#centerText(text: string, width: number): string {
+		const visLen = visibleWidth(text);
+		if (visLen >= width) {
+			return truncateToWidth(text, width);
+		}
+		const leftPad = Math.floor((width - visLen) / 2);
+		const rightPad = width - visLen - leftPad;
+		return padding(leftPad) + text + padding(rightPad);
+	}
+
+	/** Fit string to exact width with ANSI-aware truncation/padding */
+	#fitToWidth(str: string, width: number): string {
+		const visLen = visibleWidth(str);
+		if (visLen > width) {
+			const ellipsis = "…";
+			const ellipsisWidth = visibleWidth(ellipsis);
+			const maxWidth = Math.max(0, width - ellipsisWidth);
+			let truncated = "";
+			let currentWidth = 0;
+			let inEscape = false;
+			for (const char of str) {
+				if (char === "\x1b") inEscape = true;
+				if (inEscape) {
+					truncated += char;
+					if (char === "m") inEscape = false;
+				} else if (currentWidth < maxWidth) {
+					truncated += char;
+					currentWidth++;
+				}
+			}
+			return `${truncated}${ellipsis}`;
+		}
+		return str + padding(width - visLen);
+	}
+
+	/** Pick the logo frame for the current intro phase, or the resting frame. */
+	#currentLogoFrame(): readonly string[] {
+		if (this.#animStart == null) return REST_FRAME;
+		const elapsed = performance.now() - this.#animStart;
+		if (elapsed >= INTRO_MS) return REST_FRAME;
+		return introLogoFrame(elapsed / INTRO_MS);
+	}
+}
+
+export const PI_LOGO = ["▀██████████▀", " ╘██    ██  ", "  ██    ██  ", "  ██    ██  ", " ▄██▄  ▄██▄ "];
+
+/** Multi-stop palette for the diagonal gradient. */
+const GRADIENT_STOPS: ReadonlyArray<readonly [number, number, number]> = [
+	[255, 92, 200], // hot pink
+	[200, 110, 255], // violet
+	[120, 130, 255], // periwinkle
+	[60, 200, 255], // bright cyan
+	[120, 255, 220], // mint
+];
+
+/** 256-color ramp fallback when truecolor isn't available. */
+const GRADIENT_RAMP_256 = [199, 171, 135, 99, 75, 51, 87];
+
+/** Half-width of the shine highlight band, expressed in gradient-t units. */
+const SHINE_HALF_WIDTH = 0.18;
+
+export interface ShineConfig {
+	/** Overall opacity of the shine overlay, in [0, 1]. */
+	strength: number;
+	/** Center of the shine band along the diagonal, in [0, 1]. */
+	pos: number;
+}
+
+/**
+ * Resolve the gradient SGR foreground escape for a normalized position `t`
+ * (0..1) along the diagonal, compositing the optional sliding shine highlight.
+ * Shared by {@link gradientLogo} and the setup splash so both stay
+ * color-identical (truecolor when available, 256-color ramp otherwise).
+ */
+export function gradientEscape(t: number, shine?: ShineConfig): string {
+	const shineStrength = shine && shine.strength > 0 ? shine.strength : 0;
+	const shinePos = shine ? shine.pos : 0;
+	if (TERMINAL.trueColor) {
+		// 5-stop palette widens the visible color range and avoids the
+		// deep-blue valley a naive HSL lerp falls into.
+		const stops = GRADIENT_STOPS;
+		const seg = t * (stops.length - 1);
+		const i = Math.min(stops.length - 2, Math.floor(seg));
+		const f = seg - i;
+		const a = stops[i];
+		const b = stops[i + 1];
+		let r = a[0] + (b[0] - a[0]) * f;
+		let g = a[1] + (b[1] - a[1]) * f;
+		let bl = a[2] + (b[2] - a[2]) * f;
+		if (shineStrength > 0) {
+			const dist = Math.abs(t - shinePos);
+			const intensity = Math.max(0, 1 - dist / SHINE_HALF_WIDTH) * shineStrength;
+			if (intensity > 0) {
+				r += (255 - r) * intensity;
+				g += (255 - g) * intensity;
+				bl += (255 - bl) * intensity;
+			}
+		}
+		return `\x1b[38;2;${Math.round(r)};${Math.round(g)};${Math.round(bl)}m`;
+	}
+	const ramp = GRADIENT_RAMP_256;
+	let idx = Math.min(ramp.length - 1, Math.max(0, Math.floor(t * (ramp.length - 1) + 0.5)));
+	if (shineStrength > 0) {
+		const dist = Math.abs(t - shinePos);
+		const intensity = Math.max(0, 1 - dist / SHINE_HALF_WIDTH) * shineStrength;
+		// Promote to the brightest ramp slot when the shine band peaks here.
+		if (intensity > 0.5) idx = ramp.length - 1;
+	}
+	return `\x1b[38;5;${ramp[idx]}m`;
+}
+
+/**
+ * Apply a multi-stop diagonal gradient (bottom-left → top-right) plus an
+ * optional sliding shine band across multi-line art. `phase` (0..1) shifts the
+ * gradient along the diagonal, wrapping at 1. When `shine` is provided, a soft
+ * white highlight is composited on top, centered at `shine.pos`.
+ */
+export function gradientLogo(lines: readonly string[], phase = 0, shine?: ShineConfig): string[] {
+	const reset = "\x1b[0m";
+	const rows = lines.length;
+	const cols = Math.max(...lines.map(l => l.length));
+	// span+1 so `base` stays strictly < 1: avoids the wrap-around at the
+	// far corner mapping back to t=0 (hot pink) on the resting frame.
+	const span = Math.max(1, cols + rows - 1);
+	return lines.map((line, y) => {
+		let result = "";
+		for (let x = 0; x < line.length; x++) {
+			const char = line[x];
+			if (char === " ") {
+				result += char;
+				continue;
+			}
+			// Diagonal: bottom-left (x=0, y=rows-1) → top-right (x=cols-1, y=0)
+			const base = (x + (rows - 1 - y)) / span;
+			const t = (((base + phase) % 1) + 1) % 1;
+			result += gradientEscape(t, shine) + char + reset;
+		}
+		return result;
+	});
+}
+
+/** Total length of the intro animation. */
+const INTRO_MS = 3000;
+/** Render cadence during the intro (~30fps). */
+const INTRO_TICK_MS = 33;
+/** Number of full gradient rotations the sweep performs before settling. */
+const INTRO_SWEEPS = 2.5;
+/** Number of times the shine highlight crosses the diagonal across the intro. */
+const INTRO_SHINE_TRAVERSALS = 3;
+
+/**
+ * Logo frame for a normalized intro progress in [0, 1).
+ *
+ * Ease-out cubic so the spin decelerates into the resting state. The gradient
+ * sweeps backward through INTRO_SWEEPS full rotations (`eased == 1` → phase =
+ * 0 = resting frame) while the shine traverses the diagonal at a steady pace,
+ * decoupled from the gradient phase so the two layers parallax; its strength
+ * fades with the same ease-out curve so the highlight is gone by the resting
+ * frame.
+ */
+function introLogoFrame(progress: number): string[] {
+	const eased = 1 - (1 - progress) ** 3;
+	const phase = ((((1 - eased) * INTRO_SWEEPS) % 1) + 1) % 1;
+	const shinePos = (((progress * INTRO_SHINE_TRAVERSALS) % 1) + 1) % 1;
+	const shineStrength = (1 - eased) ** 1.5;
+	return gradientLogo(PI_LOGO, phase, { strength: shineStrength, pos: shinePos });
+}
+
+/** Resting gradient frame, cached for re-renders outside of the intro. */
+const REST_FRAME = gradientLogo(PI_LOGO, 0);

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

@@ -0,0 +1,105 @@
+import { prompt } from "@oh-my-pi/pi-utils";
+import btwUserPrompt from "../../prompts/system/btw-user.md" with { type: "text" };
+import { BtwPanelComponent } from "../components/btw-panel";
+import type { InteractiveModeContext } from "../types";
+
+interface BtwRequest {
+	component: BtwPanelComponent;
+	abortController: AbortController;
+	question: string;
+}
+
+export class BtwController {
+	#activeRequest: BtwRequest | undefined;
+
+	constructor(private readonly ctx: InteractiveModeContext) {}
+
+	hasActiveRequest(): boolean {
+		return this.#activeRequest !== undefined;
+	}
+
+	handleEscape(): boolean {
+		if (!this.#activeRequest) return false;
+		this.#closeActiveRequest({ abort: this.#activeRequest.abortController.signal.aborted === false });
+		return true;
+	}
+
+	dispose(): void {
+		this.#closeActiveRequest({ abort: true });
+	}
+
+	async start(question: string): Promise<void> {
+		const trimmedQuestion = question.trim();
+		if (!trimmedQuestion) {
+			this.ctx.showStatus("Usage: /btw <question>");
+			return;
+		}
+
+		const model = this.ctx.session.model;
+		if (!model) {
+			this.ctx.showError("No active model available for /btw.");
+			return;
+		}
+
+		this.#closeActiveRequest({ abort: true });
+
+		const request: BtwRequest = {
+			component: new BtwPanelComponent({ question: trimmedQuestion, tui: this.ctx.ui }),
+			abortController: new AbortController(),
+			question: trimmedQuestion,
+		};
+		this.ctx.btwContainer.clear();
+		this.ctx.btwContainer.addChild(request.component);
+		this.ctx.ui.requestRender();
+		this.#activeRequest = request;
+		void this.#runRequest(request);
+	}
+
+	async #runRequest(request: BtwRequest): Promise<void> {
+		try {
+			const promptText = prompt.render(btwUserPrompt, { question: request.question });
+			const { replyText } = await this.ctx.session.runEphemeralTurn({
+				promptText,
+				onTextDelta: delta => {
+					if (this.#isActiveRequest(request)) {
+						request.component.appendText(delta);
+					}
+				},
+				signal: request.abortController.signal,
+			});
+
+			if (!this.#isActiveRequest(request)) {
+				return;
+			}
+			if (replyText) {
+				request.component.setAnswer(replyText);
+			}
+			request.component.markComplete();
+		} catch (error) {
+			if (!this.#isActiveRequest(request)) {
+				return;
+			}
+			if (request.abortController.signal.aborted) {
+				request.component.markAborted();
+				return;
+			}
+			request.component.markError(error instanceof Error ? error.message : String(error));
+		}
+	}
+
+	#closeActiveRequest(options: { abort: boolean }): void {
+		const request = this.#activeRequest;
+		if (!request) return;
+		this.#activeRequest = undefined;
+		if (options.abort) {
+			request.abortController.abort();
+		}
+		request.component.close();
+		this.ctx.btwContainer.clear();
+		this.ctx.ui.requestRender();
+	}
+
+	#isActiveRequest(request: BtwRequest): boolean {
+		return this.#activeRequest === request;
+	}
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Shared helpers for /mcp and /ssh command controllers.
+ *
+ * Captures argument parsing, source grouping, and chat-message rendering that
+ * was duplicated between mcp-command-controller and ssh-command-controller.
+ * Intentionally kept narrow: subcommand routing, help text, success/error
+ * wording, and add-flow logic stay in the per-controller files because they
+ * diverge in workflow.
+ */
+import { Text } from './stubs/tui/index.ts';
+import type { SourceMeta } from "../../capability/types";
+import { shortenPath } from "../../tools/render-utils";
+import { DynamicBorder } from "../components/dynamic-border";
+import { TranscriptBlock } from "../components/transcript-container";
+import { parseCommandArgs } from "../shared";
+import type { InteractiveModeContext } from "../types";
+
+export type ScopeValue = "project" | "user";
+
+export type ScopeFlagResult = { ok: true; scope: ScopeValue } | { ok: false; error: string };
+
+/**
+ * Validate the value following a `--scope` flag.
+ */
+export function readScopeFlag(value: string | undefined): ScopeFlagResult {
+	if (!value || (value !== "project" && value !== "user")) {
+		return { ok: false, error: "Invalid --scope value. Use project or user." };
+	}
+	return { ok: true, scope: value };
+}
+
+export type RemoveArgs = { name: string | undefined; scope: ScopeValue };
+
+export type ParseRemoveResult = { ok: true; value: RemoveArgs } | { ok: false; error: string };
+
+/**
+ * Parse the argument tail of `/<cmd> remove <name> [--scope project|user]`.
+ *
+ * `rest` is the text after the subcommand keyword. The caller is responsible
+ * for emitting the command-specific "<entity> name required" usage hint when
+ * `value.name` is undefined.
+ */
+export function parseRemoveArgs(rest: string): ParseRemoveResult {
+	const tokens = parseCommandArgs(rest);
+
+	let name: string | undefined;
+	let scope: ScopeValue = "project";
+	let i = 0;
+
+	if (tokens.length > 0 && !tokens[0].startsWith("-")) {
+		name = tokens[0];
+		i = 1;
+	}
+
+	while (i < tokens.length) {
+		const token = tokens[i];
+		if (token === "--scope") {
+			const r = readScopeFlag(tokens[i + 1]);
+			if (!r.ok) return { ok: false, error: r.error };
+			scope = r.scope;
+			i += 2;
+			continue;
+		}
+		return { ok: false, error: `Unknown option: ${token}` };
+	}
+
+	return { ok: true, value: { name, scope } };
+}
+
+/**
+ * Group capability-loaded items by their source provider+path, yielding each
+ * group with a display-ready `shortPath`.
+ */
+export function* groupBySource<T>(
+	items: Iterable<T>,
+	getSource: (item: T) => SourceMeta,
+): Iterable<{ providerName: string; shortPath: string; items: T[] }> {
+	const groups = new Map<string, T[]>();
+	for (const item of items) {
+		const src = getSource(item);
+		const key = `${src.providerName}|${src.path}`;
+		let group = groups.get(key);
+		if (!group) {
+			group = [];
+			groups.set(key, group);
+		}
+		group.push(item);
+	}
+	for (const [key, grouped] of groups) {
+		const sepIdx = key.indexOf("|");
+		yield {
+			providerName: key.slice(0, sepIdx),
+			shortPath: shortenPath(key.slice(sepIdx + 1)),
+			items: grouped,
+		};
+	}
+}
+
+/**
+ * Render a message block (DynamicBorder / Text / DynamicBorder) into the chat
+ * container and request a render.
+ */
+export function showCommandMessage(ctx: InteractiveModeContext, text: string): void {
+	const block = new TranscriptBlock();
+	block.addChild(new DynamicBorder());
+	block.addChild(new Text(text, 1, 1));
+	block.addChild(new DynamicBorder());
+	ctx.present(block);
+}