pi-zen 0.1.0

package/src/edit-diff.ts

@@ -0,0 +1,169 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { RowPalette } from "./tool-row.ts";
+
+/** One line of a compact diff. */
+export type DiffLine =
+	| {
+			readonly kind: "added" | "removed" | "context";
+			/** The line's text, as it appears in the file. */
+			readonly text: string;
+			/** Line number in the file after the edit. */
+			readonly number: number;
+	  }
+	| {
+			readonly kind: "omission";
+			/** How many source lines the diff is not showing here. */
+			readonly hidden: number;
+			/** Whether the omission removes only context or enforces the collapsed-view budget. */
+			readonly reason: "context" | "budget";
+	  };
+
+/** Lines of unchanged context kept on each side of a change. */
+const CONTEXT = 1;
+
+/** Most lines a collapsed diff will show before it defers to the expanded view. */
+export const MAX_DIFF_LINES = 8;
+
+const HUNK = /^@@\s+-\d+(?:,\d+)?\s+\+(\d+)/;
+const ELLIPSIS = "…";
+const INDENT = "  ";
+
+type Entry = {
+	readonly kind: "added" | "removed" | "context";
+	readonly text: string;
+	readonly number: number;
+};
+
+function parsePatch(patch: string): Entry[] {
+	const entries: Entry[] = [];
+	let line = 0;
+
+	for (const raw of patch.split("\n")) {
+		const hunk = HUNK.exec(raw);
+		if (hunk?.[1] !== undefined) {
+			line = Number.parseInt(hunk[1], 10);
+			continue;
+		}
+		// File headers and the no-newline marker are not part of the change.
+		if (raw.startsWith("+++") || raw.startsWith("---") || raw.startsWith("\\")) continue;
+		if (line === 0) continue;
+
+		const body = raw.slice(1);
+		if (raw.startsWith("+")) {
+			entries.push({ kind: "added", text: body, number: line });
+			line += 1;
+		} else if (raw.startsWith("-")) {
+			// A removed line is numbered where it used to sit, so the pair reads together.
+			entries.push({ kind: "removed", text: body, number: line });
+		} else if (raw.startsWith(" ")) {
+			entries.push({ kind: "context", text: body, number: line });
+			line += 1;
+		}
+	}
+
+	return entries;
+}
+
+/**
+ * Reduce a unified patch to the lines worth reading.
+ *
+ * Every changed line is kept, with one line of context on each side of a change
+ * group. Context the patch carried but the eye does not need becomes a single
+ * omission marker, so two changes far apart in a file stay two change groups
+ * rather than one wall of unchanged code.
+ *
+ * @param patch - A standard unified patch.
+ * @returns The lines to render, in file order.
+ */
+export function compactDiff(patch: string): DiffLine[] {
+	const entries = parsePatch(patch);
+	const keep = entries.map((entry) => entry.kind !== "context");
+	entries.forEach((entry, index) => {
+		if (entry.kind === "context") return;
+		for (let offset = 1; offset <= CONTEXT; offset += 1) {
+			if (index - offset >= 0) keep[index - offset] = true;
+			if (index + offset < entries.length) keep[index + offset] = true;
+		}
+	});
+
+	const lines: DiffLine[] = [];
+	let hidden = 0;
+	for (const [index, entry] of entries.entries()) {
+		if (keep[index] !== true) {
+			hidden += 1;
+			continue;
+		}
+		if (hidden > 0) {
+			lines.push({ kind: "omission", hidden, reason: "context" });
+			hidden = 0;
+		}
+		lines.push(entry);
+	}
+
+	if (lines.length <= MAX_DIFF_LINES) return lines;
+
+	// Keep both ends: the opening identifies the change and the tail shows where
+	// it landed. The expanded renderer remains the complete source of truth.
+	const visibleLines = MAX_DIFF_LINES - 1;
+	const leadingCount = Math.ceil(visibleLines / 2);
+	const trailingCount = Math.floor(visibleLines / 2);
+	const leading = lines.slice(0, leadingCount);
+	const trailing = lines.slice(lines.length - trailingCount);
+	const omitted = lines.slice(leadingCount, lines.length - trailingCount);
+	const budgetHidden = omitted.reduce((total, line) => total + (line.kind === "omission" ? line.hidden : 1), 0);
+	return [...leading, { kind: "omission", hidden: budgetHidden, reason: "budget" }, ...trailing];
+}
+
+function markerOf(line: DiffLine): string {
+	if (line.kind === "added") return "+";
+	if (line.kind === "removed") return "-";
+	if (line.kind === "omission") return ELLIPSIS;
+	return " ";
+}
+
+function colorOf(line: DiffLine): "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext" {
+	if (line.kind === "added") return "toolDiffAdded";
+	if (line.kind === "removed") return "toolDiffRemoved";
+	return "toolDiffContext";
+}
+
+/**
+ * Render a compact diff under a collapsed edit row.
+ *
+ * The gutter is as wide as the largest line number, so the code column starts in
+ * the same place on every line. A line too long for the terminal is truncated
+ * rather than wrapped, because a wrapped diff stops looking like one.
+ *
+ * @param lines - The lines from `compactDiff`.
+ * @param width - Visible terminal width.
+ * @param palette - Theme slice used to color the diff.
+ * @returns One string per line, none wider than `width`.
+ */
+export function renderDiff(lines: readonly DiffLine[], width: number, palette: RowPalette): string[] {
+	if (lines.length === 0) return [];
+
+	let gutter = 1;
+	for (const line of lines) {
+		if (line.kind !== "omission") gutter = Math.max(gutter, String(line.number).length);
+	}
+
+	const rendered: string[] = [];
+	for (const line of lines) {
+		// The marker and the number are aligned as one token, so the digits line up
+		// however wide the numbers get and the marker leans in from the left.
+		const number = line.kind === "omission" ? "" : String(line.number);
+		const prefix = INDENT + (markerOf(line) + number).padStart(gutter + 1, " ") + " ";
+		const room = width - visibleWidth(prefix);
+		if (room <= 0) continue;
+
+		const text =
+			line.kind === "omission"
+				? line.reason === "context"
+					? `${line.hidden} unchanged`
+					: `${line.hidden} more lines`
+				: truncateToWidth(line.text, room, ELLIPSIS);
+		rendered.push(palette.fg(colorOf(line), prefix + text));
+	}
+	return rendered;
+}

package/src/editor-rail.ts

@@ -0,0 +1,68 @@
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+
+/** Glyph drawn in the editor's left padding in place of Pi's horizontal frame. */
+export const RAIL_GLYPH = "┃";
+
+/**
+ * Smallest editor padding the rail can occupy: one column for the glyph and one
+ * for the gap before the text. Pi's editor keeps its own layout maths, so the
+ * rail only ever overwrites padding columns that are already blank.
+ */
+export const MIN_RAIL_PADDING = 2;
+
+/** Paints the rail glyph, normally with the editor's current border color. */
+export type RailPaint = (glyph: string) => string;
+
+function isFrameRow(row: string): boolean {
+	return stripTerminalSequences(row).startsWith("─");
+}
+
+function carriesScrollHint(row: string): boolean {
+	const plain = stripTerminalSequences(row);
+	return plain.includes("↑") || plain.includes("↓");
+}
+
+function railBodyRow(row: string, paddingX: number, paint: RailPaint): string {
+	const indent = " ".repeat(paddingX);
+	if (!row.startsWith(indent)) return row;
+	return paint(RAIL_GLYPH) + " ".repeat(paddingX - 1) + row.slice(paddingX);
+}
+
+/**
+ * Rewrite the rows Pi's editor rendered into the Zen presentation: the two
+ * horizontal frame rows disappear and the input gains a single left rail.
+ *
+ * Frame rows that carry a scroll hint (`─── ↑ 3 more ───`) are kept, because
+ * they report content the editor is hiding. Body rows keep their exact visible
+ * width, so cursor geometry, the hardware cursor marker, selection, and
+ * wrapping stay identical to the base editor. Rows below the bottom frame
+ * (the autocomplete list) pass through untouched.
+ *
+ * @param rows - Rows returned by the base editor's `render`.
+ * @param paddingX - The editor's current horizontal padding.
+ * @param paint - Styles the rail glyph.
+ * @returns The rows to render. Returned unchanged when the padding is too small
+ * for a rail or when the rows do not look like Pi's framed editor.
+ */
+export function applyRail(rows: readonly string[], paddingX: number, paint: RailPaint): string[] {
+	if (paddingX < MIN_RAIL_PADDING || rows.length < 2) return [...rows];
+
+	const frames: number[] = [];
+	for (const [index, row] of rows.entries()) {
+		if (isFrameRow(row)) frames.push(index);
+	}
+
+	const top = frames.at(0);
+	const bottom = frames.at(-1);
+	if (top !== 0 || bottom === undefined || bottom <= top) return [...rows];
+
+	const railed: string[] = [];
+	for (const [index, row] of rows.entries()) {
+		if (index === top || index === bottom) {
+			if (carriesScrollHint(row)) railed.push(row);
+			continue;
+		}
+		railed.push(index > bottom ? row : railBodyRow(row, paddingX, paint));
+	}
+	return railed;
+}

package/src/markdown-compaction.ts

@@ -0,0 +1,40 @@
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+
+/**
+ * Collapse runs of blank lines down to one, leaving fenced code untouched.
+ *
+ * Pi's markdown renderer adds its own spacing after headings, paragraphs, and
+ * lists, so a model that also emits double blank lines produces a transcript
+ * with holes in it. Code fences keep every blank line, because there the
+ * spacing is content.
+ *
+ * @param markdown - The markdown about to be rendered.
+ * @returns The same markdown with no run of more than one blank line.
+ */
+export function squeezeBlankLines(markdown: string): string {
+	const lines = markdown.split("\n");
+	const kept: string[] = [];
+	let fence: string | undefined;
+
+	for (const line of lines) {
+		const marker = FENCE.exec(line)?.[1];
+		if (fence === undefined) {
+			if (marker !== undefined) {
+				fence = marker;
+				kept.push(line);
+				continue;
+			}
+		} else {
+			// A closing fence must be at least as long as the one that opened it.
+			if (marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length) fence = undefined;
+			kept.push(line);
+			continue;
+		}
+
+		const blank = line.trim() === "";
+		if (blank && kept.at(-1)?.trim() === "") continue;
+		kept.push(line);
+	}
+
+	return kept.join("\n");
+}

package/src/silent-header.ts

@@ -0,0 +1,15 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container } from "@earendil-works/pi-tui";
+
+/**
+ * Remove the startup header.
+ *
+ * This covers the logo and the key-hint banner. The loaded-resource listing and
+ * package-update notices are decided by the `quietStartup` setting before
+ * extensions run, so a fully silent startup still wants `quietStartup: true`.
+ *
+ * @param ctx - The session's extension context.
+ */
+export function installBlankHeader(ctx: ExtensionContext): void {
+	ctx.ui.setHeader(() => new Container());
+}

package/src/thinking-tail.ts

@@ -0,0 +1,51 @@
+const FENCE = /^\s{0,3}(?:`{3,}|~{3,})/;
+
+/** Lines retained on terminals with enough vertical room. */
+export const DEFAULT_THINKING_TAIL_LINES = 8;
+
+/** Lines retained when the terminal is short. */
+export const SHORT_THINKING_TAIL_LINES = 5;
+
+/** A terminal at or below this height gets the shorter reasoning tail. */
+export const SHORT_TERMINAL_ROWS = 24;
+
+/**
+ * Choose a reasoning-tail budget from the terminal's current height.
+ *
+ * @param terminalRows - Current terminal rows, or undefined outside a measurable TTY.
+ * @returns The number of streaming reasoning lines to retain.
+ */
+export function thinkingTailLineBudget(terminalRows: number | undefined): number {
+	return terminalRows !== undefined && terminalRows <= SHORT_TERMINAL_ROWS
+		? SHORT_THINKING_TAIL_LINES
+		: DEFAULT_THINKING_TAIL_LINES;
+}
+
+/**
+ * Keep only the end of a reasoning block while it is still streaming.
+ *
+ * Reasoning is worth reading, but a block that grows without limit pushes the
+ * rest of the turn off the screen and scrolls while you read it. Holding it to a
+ * fixed number of lines keeps the transcript still: the block stays the same
+ * height and the newest sentence stays where your eye already is. Once the block
+ * settles it is shown whole, because by then it is history rather than motion.
+ *
+ * @param markdown - The reasoning text so far.
+ * @param maxLines - How many lines to keep.
+ * @returns The last `maxLines` lines, marked as a tail when anything was cut.
+ */
+export function thinkingTail(markdown: string, maxLines: number): string {
+	if (maxLines <= 0) return "";
+
+	const lines = markdown.split("\n");
+	if (lines.length <= maxLines) return markdown;
+
+	const tail = lines.slice(lines.length - maxLines);
+	// Cutting into a code fence would leave the renderer with an unclosed one, so
+	// an odd number of fences in the tail gets an opener of its own.
+	let fences = 0;
+	for (const line of tail) if (FENCE.test(line)) fences += 1;
+	if (fences % 2 === 1) tail.unshift("```");
+
+	return ["…", ...tail].join("\n");
+}

package/src/tool-output.ts

@@ -0,0 +1,184 @@
+/** Added and removed line counts for an edit. */
+export type EditChangeCount = {
+	/** Lines the edit added. */
+	readonly added: number;
+	/** Lines the edit removed. */
+	readonly removed: number;
+};
+
+/**
+ * Count the lines a unified patch adds and removes.
+ *
+ * @param patch - The `patch` field of an edit result.
+ * @returns Added and removed line counts, both zero for an empty patch.
+ */
+export function countPatchChanges(patch: string): EditChangeCount {
+	let added = 0;
+	let removed = 0;
+
+	for (const line of patch.split("\n")) {
+		if (line.startsWith("+++") || line.startsWith("---")) continue;
+		if (line.startsWith("+")) added++;
+		else if (line.startsWith("-")) removed++;
+	}
+
+	return { added, removed };
+}
+
+/**
+ * Count the hunks in a unified patch.
+ *
+ * @param patch - The `patch` field of an edit result.
+ * @returns The number of hunk headers in the patch.
+ */
+export function countPatchHunks(patch: string): number {
+	let hunks = 0;
+	for (const line of patch.split("\n")) if (line.startsWith("@@ ")) hunks += 1;
+	return hunks;
+}
+
+/**
+ * Render an edit's line counts the way diffs read.
+ *
+ * @param change - Added and removed line counts.
+ * @returns A string such as `+8 −3`, or undefined when nothing changed.
+ */
+export function formatEditChange(change: EditChangeCount): string | undefined {
+	if (change.added === 0 && change.removed === 0) return undefined;
+	return `+${change.added} −${change.removed}`;
+}
+
+/**
+ * Count the matches in grep output.
+ *
+ * Ripgrep prints `path:line:text` per match, so lines carrying a line number
+ * are matches and context lines are not.
+ *
+ * @param output - Text the grep tool returned.
+ * @returns The number of matching lines.
+ */
+export function countMatchLines(output: string): number {
+	let matches = 0;
+	for (const line of output.split("\n")) {
+		if (/:\d+:/.test(line)) matches++;
+	}
+	return matches;
+}
+
+/**
+ * Count the non-empty lines of output, for tools that print one result per line.
+ *
+ * @param output - Text the tool returned.
+ * @returns The number of non-empty lines.
+ */
+export function countResultLines(output: string): number {
+	let lines = 0;
+	for (const line of output.split("\n")) {
+		if (line.trim() !== "") lines++;
+	}
+	return lines;
+}
+
+/** Node appends the syscall and path to errno messages; the row already names the path. */
+const ERRNO_PATH_CLAUSE =
+	/,\s*(?:access|open|stat|lstat|scandir|read|write|unlink|mkdir|rmdir|copyfile|rename)\s+'[^']*'\s*$/;
+
+/**
+ * Pick the line that tells the user what went wrong.
+ *
+ * A node errno message repeats the path the row already shows, so that clause is
+ * dropped to leave room for the part that explains the failure.
+ *
+ * @param output - Text the failed tool returned.
+ * @returns The first non-empty line, or undefined when the output is blank.
+ */
+export function firstActionableLine(output: string): string | undefined {
+	for (const line of output.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed !== "") return trimmed.replace(ERRNO_PATH_CLAUSE, "");
+	}
+	return undefined;
+}
+
+const BASH_STATUS = /^Command (?:exited with code (\d+)|aborted|timed out after (\S+) seconds)$/;
+
+/**
+ * Summarise why a bash call failed.
+ *
+ * Pi appends its own status sentence to the command output — an exit code, an
+ * abort, or a timeout — so the status is the last line, and the first line of
+ * output is what explains it.
+ *
+ * @param output - Text the failed bash call returned.
+ * @returns A short reason such as `exit 1 · error TS2345: ...`, or undefined
+ * when the call produced nothing at all.
+ */
+export function bashFailureSummary(output: string): string | undefined {
+	const lines = output
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line !== "");
+	const last = lines.at(-1);
+	const status = last === undefined ? null : BASH_STATUS.exec(last);
+	if (status === null) return lines.at(0);
+
+	const code = status[1];
+	const timeout = status[2];
+	const label = code !== undefined ? `exit ${code}` : timeout !== undefined ? `timeout ${timeout}s` : "aborted";
+	const first = lines.at(0);
+	if (first === undefined || first === last || first === "(no output)") return label;
+	return `${label} · ${first}`;
+}
+
+/**
+ * Reduce a shell command to its first line, so a heredoc or a multi-line
+ * pipeline still occupies one transcript row.
+ *
+ * @param command - The command that was run.
+ * @returns The first non-empty line, with a marker when more lines follow.
+ */
+export function commandHead(command: string): string {
+	const lines = command.split("\n").filter((line) => line.trim() !== "");
+	const head = lines.at(0)?.trim() ?? "";
+	return lines.length > 1 ? `${head} …` : head;
+}
+
+/**
+ * Format an elapsed duration for a tool row.
+ *
+ * @param elapsedMs - Milliseconds the tool ran.
+ * @returns A short duration such as `240ms`, `2.1s`, or `3m04s`.
+ */
+export function formatDuration(elapsedMs: number): string {
+	if (elapsedMs < 1_000) return `${Math.max(0, Math.round(elapsedMs))}ms`;
+	if (elapsedMs < 60_000) return `${(elapsedMs / 1_000).toFixed(1)}s`;
+	const minutes = Math.floor(elapsedMs / 60_000);
+	const seconds = Math.round((elapsedMs % 60_000) / 1_000);
+	return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+}
+
+/**
+ * Whether a tool returned a picture.
+ *
+ * A collapsed row cannot show an image, so it says one is there and leaves the
+ * showing to the expanded view.
+ *
+ * @param content - Content blocks from the tool result.
+ * @returns True when any block is an image.
+ */
+export function hasImage(content: readonly { readonly type: string }[]): boolean {
+	return content.some((block) => block.type === "image");
+}
+
+/**
+ * Pull the text a tool returned out of its content blocks.
+ *
+ * @param content - Content blocks from the tool result.
+ * @returns The concatenated text, ignoring image blocks.
+ */
+export function textOf(content: readonly { readonly type: string; readonly text?: string }[]): string {
+	return content
+		.filter((block) => block.type === "text")
+		.map((block) => block.text ?? "")
+		.join("");
+}

package/src/tool-row.ts

@@ -0,0 +1,124 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** The slice of Pi's theme a tool row needs to paint itself. */
+export type RowPalette = {
+	readonly fg: (color: ThemeColor, text: string) => string;
+};
+
+/** Where a tool call has got to. */
+export type RowOutcome =
+	| { readonly kind: "running" }
+	| { readonly kind: "settled" }
+	| { readonly kind: "failed"; readonly reason: string | undefined };
+
+/** The thing a tool acted on. */
+export type RowSubject = {
+	/** Path, command, or pattern. */
+	readonly text: string;
+	/** Which end survives truncation: paths keep their end, commands their start. */
+	readonly keep: "start" | "end";
+};
+
+/** Short outcome detail such as `+8 −3` or `2.1s`. */
+export type RowDetail = {
+	/** The detail text. */
+	readonly text: string;
+	/** `attention` for detail the user may need to act on, such as truncation. */
+	readonly emphasis: "quiet" | "attention";
+};
+
+/** One collapsed tool row. */
+export type ToolRow = {
+	/** Present-tense action, lower case, at most five columns. */
+	readonly verb: string;
+	/** What the tool acted on. */
+	readonly subject: RowSubject;
+	/** Outcome detail, when it adds something. */
+	readonly detail: RowDetail | undefined;
+	/** Where the call has got to. */
+	readonly outcome: RowOutcome;
+};
+
+/** Marker for a pending or settled row. */
+export const ROW_MARKER = "-";
+
+/** Marker for a row whose tool failed. */
+export const FAILED_MARKER = "✗";
+
+const VERB_WIDTH = 5;
+/** Between the verb column and the subject. */
+const GAP = " ";
+/** Before an outcome detail, which needs more separation than the subject. */
+const DETAIL_GAP = "  ";
+const ELLIPSIS = "…";
+const MIN_SUBJECT_WIDTH = 12;
+const MIN_DETAIL_WIDTH = 10;
+
+function elide(subject: RowSubject, max: number): string {
+	if (max <= 0) return "";
+	if (visibleWidth(subject.text) <= max) return subject.text;
+	if (subject.keep === "start") return truncateToWidth(subject.text, max, ELLIPSIS);
+
+	const kept = max - visibleWidth(ELLIPSIS);
+	if (kept <= 0) return ELLIPSIS.slice(0, max);
+	return ELLIPSIS + subject.text.slice(subject.text.length - kept);
+}
+
+function markerColor(outcome: RowOutcome): ThemeColor {
+	return outcome.kind === "failed" ? "error" : "dim";
+}
+
+function detailFor(row: ToolRow): { readonly text: string; readonly color: ThemeColor } | undefined {
+	if (row.outcome.kind === "failed") {
+		const reason = row.outcome.reason;
+		return reason === undefined ? undefined : { text: reason, color: "error" };
+	}
+	if (row.detail === undefined) return undefined;
+	return { text: row.detail.text, color: row.detail.emphasis === "attention" ? "warning" : "dim" };
+}
+
+/**
+ * Format one collapsed tool row.
+ *
+ * The verb column is fixed so consecutive rows align. As the row narrows the
+ * subject shrinks first, then the detail is truncated, and a detail left with no
+ * useful room is dropped so the subject stays readable.
+ *
+ * @param row - The row to format.
+ * @param width - Visible terminal width.
+ * @param palette - Theme slice used to color the row.
+ * @returns One line, never wider than `width`.
+ */
+export function formatToolRow(row: ToolRow, width: number, palette: RowPalette): string {
+	if (width <= 0) return "";
+
+	const marker = row.outcome.kind === "failed" ? FAILED_MARKER : ROW_MARKER;
+	const verb = row.verb.padEnd(VERB_WIDTH, " ");
+	const prefixWidth = visibleWidth(marker) + 1 + visibleWidth(verb) + GAP.length;
+	const detail = detailFor(row);
+
+	let subjectBudget = width - prefixWidth;
+	let detailText: string | undefined;
+	if (detail !== undefined) {
+		// The detail may claim what is left once the subject keeps its floor. A
+		// truncated failure reason still says what went wrong, so it is worth a
+		// shorter subject; a detail with no room at all is dropped instead.
+		const wanted = visibleWidth(detail.text);
+		const subjectNeed = Math.min(visibleWidth(row.subject.text), MIN_SUBJECT_WIDTH);
+		const available = Math.max(0, subjectBudget - DETAIL_GAP.length - subjectNeed);
+		const granted = Math.min(wanted, available);
+		if (granted === wanted || granted >= MIN_DETAIL_WIDTH) {
+			detailText = truncateToWidth(detail.text, granted, ELLIPSIS);
+			subjectBudget -= visibleWidth(detailText) + DETAIL_GAP.length;
+		}
+	}
+
+	const subject = elide(row.subject, subjectBudget);
+	let line = palette.fg(markerColor(row.outcome), marker) + " " + palette.fg("text", verb) + GAP;
+	line += palette.fg(row.outcome.kind === "running" ? "dim" : "muted", subject);
+	if (detailText !== undefined && detail !== undefined) {
+		line += DETAIL_GAP + palette.fg(detail.color, detailText);
+	}
+	return line;
+}

package/src/working-indicator.ts

@@ -0,0 +1,29 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+
+/** Frame interval that gives the four-frame pulse roughly one calm second per cycle. */
+export const QUIET_INTERVAL_MS = 240;
+
+/**
+ * Replace Pi's spinner with a single dot that swells and fades.
+ *
+ * Frames are rendered verbatim by Pi, so they are colored here from the theme
+ * that is active when the indicator is installed.
+ *
+ * @param ui - The session's UI context.
+ */
+export function installQuietIndicator(ui: ExtensionUIContext): void {
+	const theme = ui.theme;
+	ui.setWorkingIndicator({
+		frames: [theme.fg("dim", "·"), theme.fg("dim", "•"), theme.fg("muted", "●"), theme.fg("dim", "•")],
+		intervalMs: QUIET_INTERVAL_MS,
+	});
+}
+
+/**
+ * Restore Pi's default spinner.
+ *
+ * @param ui - The session's UI context.
+ */
+export function restoreDefaultIndicator(ui: ExtensionUIContext): void {
+	ui.setWorkingIndicator();
+}