@oh-my-pi/pi-tui 18.2.4 → 18.2.5

package/src/chat/background-tan-message.ts

@@ -0,0 +1,35 @@
+import type { BackgroundTanDispatchDetails, CustomMessage } from "./messages";
+import { replaceTabs } from "../render/render-utils";
+import { theme } from "../theme";
+import type { TranscriptBlock } from "../chrome/transcript-container";
+import { TranscriptStatusBlock } from "../chrome/transcript-status";
+
+const TAN_WORK_PREVIEW_LENGTH = 56;
+
+function previewWork(work: string): string {
+	const singleLine = replaceTabs(work).trim().replace(/\s+/g, " ");
+	if (singleLine.length <= TAN_WORK_PREVIEW_LENGTH) return singleLine;
+	return `${singleLine.slice(0, TAN_WORK_PREVIEW_LENGTH - 1)}…`;
+}
+
+/**
+ * Single-line transcript pill for a `/tan` background-dispatch breadcrumb,
+ * styled as a sibling of the "Background job completed" line. The full
+ * system-notice content (the persisted `content`) is for the model only — the
+ * user sees one compact line, not the raw `<system-notice>` block.
+ */
+export function createBackgroundTanDispatchBlock(message: CustomMessage<unknown>): TranscriptBlock {
+	const details = (message as CustomMessage<Partial<BackgroundTanDispatchDetails>>).details;
+	const jobId = details?.jobId ?? "unknown";
+	const work = details?.work ? previewWork(details.work) : undefined;
+	return new TranscriptStatusBlock([
+		{
+			parts: [
+				theme.fg("muted", `${theme.icon.output} Tangent dispatched`),
+				theme.fg("dim", "[task]"),
+				theme.fg("accent", jobId),
+				work ? theme.fg("dim", `${theme.format.dash} ${work}`) : undefined,
+			],
+		},
+	]);
+}

package/src/chat/bash-execution.ts

@@ -0,0 +1,394 @@
+/**
+ * Component for displaying bash command execution with streaming output.
+ */
+
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+import { Image } from "../components/image";
+import type { Loader } from "../components/loader";
+import { Text } from "../components/text";
+import { getImageDimensions, imageFallback, ImageProtocol, TERMINAL } from "../terminal-capabilities";
+import { Container, type TUI } from "../tui";
+import { sanitizeText } from "@oh-my-pi/pi-utils";
+import type { Terminal as XtermTerminalType } from "@oh-my-pi/pi-utils/vterm";
+import { theme } from "../theme/theme";
+import type { OutputArtifactError } from "../tools/streaming-output";
+import type { TruncationMeta } from "../tools/output-meta";
+import { resolveImageOptions } from "../render/render-utils";
+import { OutputPane } from "../render/output-pane";
+import { loadXtermTerminal, readTerminalRows, styleTerminalRow } from "../tools/terminal-output";
+import { getSixelLineMask, isSixelPassthroughEnabled, sanitizeWithOptionalSixelPassthrough } from "../render/sixel";
+import {
+	buildExecutionFrame,
+	buildStatusFooter,
+	clampDisplayLine,
+	type ExecutionStatus,
+	PREVIEW_LINES,
+	resolveExecutionStatus,
+} from "./execution-shared";
+
+const STREAMING_LINE_CAP = PREVIEW_LINES * 5;
+// Minimum interval between processing incoming chunks for display (ms).
+// Chunks arriving faster than this are accumulated and processed in one batch.
+const CHUNK_THROTTLE_MS = 50;
+// Scrollback retained by the PTY replay terminal; bounds memory and the
+// expanded view for long-running commands.
+const PTY_SCROLLBACK_ROWS = 4096;
+// Caps the unwritten PTY chunk backlog while xterm.write drains.
+const MAX_PTY_QUEUE_CHUNKS = 512;
+let nextBashExecutionId = 0;
+
+/** PTY size for `!` commands: the execution frame's inner content area. */
+export function bashPtyViewport(ui: TUI): { cols: number; rows: number } {
+	return {
+		cols: Math.max(20, (ui.terminal?.columns ?? 80) - 2),
+		rows: Math.max(5, (ui.terminal?.rows ?? 24) - 4),
+	};
+}
+
+export class BashExecutionComponent extends Container {
+	#outputLines: string[] = [];
+	#status: ExecutionStatus = "running";
+	#exitCode: number | undefined = undefined;
+	#loader: Loader;
+	#truncation?: TruncationMeta;
+	#artifactError?: OutputArtifactError;
+	#expanded = false;
+	// Post-finalize mutation counter (FinalizableBlock.getTranscriptBlockVersion):
+	// a completed command's block still mutates on expansion toggles, and the
+	// transcript's width-epoch resolution and committed-render bypass must
+	// observe that.
+	#blockVersion = 0;
+	#displayDirty = false;
+	#chunkGate = false;
+	#contentContainer: Container;
+	#outputPane: OutputPane;
+	#headerText: Text;
+	#ui: TUI;
+	// PTY replay state: raw terminal bytes stream into a headless xterm and the
+	// display lines are re-read from its screen+scrollback (same pipeline as
+	// `launch` logs), so color survives and CR/cursor movement render correctly.
+	#ptyMode = false;
+	#ptyTerminal?: XtermTerminalType;
+	#ptyLoadStarted = false;
+	#ptyQueue: string[] = [];
+	#ptyWriting = false;
+	#ptyRefreshQueued = false;
+	#ptyReplayFinalized = false;
+	#images: readonly ImageContent[] = [];
+	#showImages = true;
+	readonly #instanceId = nextBashExecutionId++;
+	readonly #command: string;
+
+	constructor(command: string, ui: TUI, excludeFromContext = false) {
+		super();
+		this.#command = command;
+		this.#ui = ui;
+
+		// Use dim border for excluded-from-context commands (!! prefix)
+		const colorKey = excludeFromContext ? "dim" : "bashMode";
+		const { contentContainer, loader } = buildExecutionFrame(this, ui, colorKey);
+		this.#contentContainer = contentContainer;
+		this.#loader = loader;
+		this.#outputPane = new OutputPane(theme, {
+			expanded: false,
+			collapsedMaxLines: PREVIEW_LINES,
+			edge: "tail",
+			visual: true,
+			paddingX: 1,
+			leadingBlank: true,
+			showHiddenMarker: false,
+			showExpandHint: false,
+			styleLine: line => this.#styleDisplayLine(line),
+		});
+
+		// Command header
+		this.#headerText = new Text(theme.fg(colorKey, theme.bold(`$ ${command}`)), 1, 0);
+		this.#contentContainer.addChild(this.#headerText);
+		this.#contentContainer.addChild(this.#loader);
+	}
+
+	/**
+	 * Transcript finalization contract (see `FinalizableBlock`): the collapsed
+	 * streaming preview rewrites its tail window every chunk, so the block must
+	 * stay out of native scrollback until the command completes.
+	 */
+	isTranscriptBlockFinalized(): boolean {
+		return this.#status !== "running" && (!this.#ptyMode || this.#ptyReplayFinalized);
+	}
+
+	getTranscriptBlockVersion(): number {
+		return this.#blockVersion;
+	}
+
+	/**
+	 * Set whether the output is expanded (shows full output) or collapsed (preview only).
+	 */
+	setExpanded(expanded: boolean): void {
+		if (this.#expanded !== expanded) this.#blockVersion++;
+		this.#expanded = expanded;
+		this.#outputPane.setExpanded(expanded);
+		this.#updateDisplay();
+	}
+
+	override invalidate(): void {
+		super.invalidate();
+		this.#displayDirty = false;
+		this.#updateDisplay();
+	}
+
+	appendOutput(chunk: string): void {
+		if (this.#ptyMode) return;
+		// During high-throughput output (e.g. seq 1 500M), processing every
+		// chunk would saturate the event loop. Instead, accept one chunk per
+		// throttle window and drop the rest — the OutputSink captures everything
+		// for the artifact, and setComplete() replaces with the final output.
+		if (this.#chunkGate) return;
+		this.#chunkGate = true;
+		setTimeout(() => {
+			this.#chunkGate = false;
+		}, CHUNK_THROTTLE_MS);
+
+		const incomingLines = chunk.split("\n");
+		if (this.#outputLines.length > 0 && incomingLines.length > 0) {
+			const lastIndex = this.#outputLines.length - 1;
+			const mergedLines = [`${this.#outputLines[lastIndex]}${incomingLines[0]}`, ...incomingLines.slice(1)];
+			const clampedMergedLines = this.#clampLinesPreservingSixel(mergedLines);
+			this.#outputLines[lastIndex] = clampedMergedLines[0] ?? "";
+			this.#outputLines.push(...clampedMergedLines.slice(1));
+		} else {
+			this.#outputLines.push(...this.#clampLinesPreservingSixel(incomingLines));
+		}
+
+		// Cap stored lines during streaming to avoid unbounded memory growth
+		if (this.#outputLines.length > STREAMING_LINE_CAP) {
+			this.#outputLines = this.#outputLines.slice(-STREAMING_LINE_CAP);
+		}
+
+		this.#displayDirty = true;
+	}
+
+	/** Switch to PTY rendering and feed raw terminal bytes through the vterm replay. */
+	appendPtyChunk(chunk: string): void {
+		if (this.#status !== "running" && !this.#ptyWriting && this.#ptyQueue.length === 0) return;
+		this.#ptyMode = true;
+		this.#ptyReplayFinalized = false;
+		this.#ptyQueue.push(chunk);
+		if (this.#ptyQueue.length > MAX_PTY_QUEUE_CHUNKS) {
+			const firstPending = this.#ptyWriting ? 1 : 0;
+			this.#ptyQueue.splice(firstPending, this.#ptyQueue.length - firstPending - MAX_PTY_QUEUE_CHUNKS);
+			// A dropped chunk can split an in-flight DCS/OSC string; a stray string
+			// terminator is a no-op in the ground state but resynchronizes the parser.
+			this.#ptyQueue[firstPending] = `\u001b\\${this.#ptyQueue[firstPending]}`;
+		}
+		if (!this.#ptyLoadStarted) {
+			this.#ptyLoadStarted = true;
+			void loadXtermTerminal().then(Terminal => {
+				const { cols, rows } = bashPtyViewport(this.#ui);
+				this.#ptyTerminal = new Terminal({
+					cols,
+					rows,
+					disableStdin: true,
+					allowProposedApi: true,
+					scrollback: PTY_SCROLLBACK_ROWS,
+				});
+				this.#drainPtyQueue();
+			});
+		}
+		this.#drainPtyQueue();
+	}
+
+	#drainPtyQueue(): void {
+		const terminal = this.#ptyTerminal;
+		if (!terminal || this.#ptyWriting) return;
+		const chunk = this.#ptyQueue.shift();
+		if (chunk === undefined) {
+			if (this.#status !== "running") this.#finalizePtyOutput();
+			return;
+		}
+		this.#ptyWriting = true;
+		terminal.write(chunk, () => {
+			this.#ptyWriting = false;
+			this.#schedulePtyRefresh();
+			this.#drainPtyQueue();
+		});
+	}
+
+	#schedulePtyRefresh(): void {
+		if (this.#chunkGate) {
+			this.#ptyRefreshQueued = true;
+			return;
+		}
+		this.#chunkGate = true;
+		this.#refreshPtyLines(false);
+		setTimeout(() => {
+			this.#chunkGate = false;
+			if (this.#ptyRefreshQueued) {
+				this.#ptyRefreshQueued = false;
+				this.#schedulePtyRefresh();
+			}
+		}, CHUNK_THROTTLE_MS);
+	}
+
+	/** Re-read display lines from the replay terminal (tail window while streaming). */
+	#refreshPtyLines(full: boolean): void {
+		const terminal = this.#ptyTerminal;
+		if (!terminal) return;
+		const buffer = terminal.buffer.active;
+		const startRow = full ? 0 : Math.max(0, buffer.length - STREAMING_LINE_CAP);
+		const rows = readTerminalRows(terminal, startRow, buffer.length - startRow);
+		while (rows.length > 0 && rows[rows.length - 1] === "") rows.pop();
+		const base = theme.getFgAnsi("muted");
+		this.#outputLines = rows.map(row => (row ? styleTerminalRow(row, base) : ""));
+		this.#displayDirty = true;
+	}
+
+	/** Final full-scrollback read; the terminal is disposed once lines are snapshotted. */
+	#finalizePtyOutput(): void {
+		const terminal = this.#ptyTerminal;
+		if (!terminal) return;
+		this.#refreshPtyLines(true);
+		this.#ptyTerminal = undefined;
+		terminal.dispose();
+		this.#ptyReplayFinalized = true;
+		this.#blockVersion++;
+		this.#updateDisplay();
+		this.#ui.requestComponentRender(this);
+	}
+
+	setComplete(
+		exitCode: number | undefined,
+		cancelled: boolean,
+		options?: {
+			output?: string;
+			truncation?: TruncationMeta;
+			artifactError?: OutputArtifactError;
+			images?: readonly ImageContent[];
+			showImages?: boolean;
+		},
+	): void {
+		this.#exitCode = exitCode;
+		this.#status = resolveExecutionStatus(exitCode, cancelled);
+		this.#truncation = options?.truncation;
+		this.#artifactError = options?.artifactError;
+		this.#images = options?.images ?? [];
+		this.#showImages = options?.showImages ?? true;
+		if (options?.output !== undefined && !this.#ptyMode) {
+			this.#setOutput(options.output);
+		}
+
+		// Stop loader
+		this.#loader.stop();
+		// PTY lines still queued keep draining; the empty-queue drain finalizes.
+		if (this.#ptyMode && !this.#ptyWriting && this.#ptyQueue.length === 0) {
+			this.#finalizePtyOutput();
+		}
+
+		this.#updateDisplay();
+	}
+
+	override render(width: number): readonly string[] {
+		if (this.#displayDirty) {
+			this.#displayDirty = false;
+			this.#updateDisplay();
+		}
+		return super.render(width);
+	}
+
+	#updateDisplay(): void {
+		const availableLines = this.#outputLines;
+
+		// Full output is shown when expanded or when sixel passthrough renders
+		// the raw payload; the collapsed preview shows only the tail window.
+		const sixelLineMask =
+			TERMINAL.imageProtocol === ImageProtocol.Sixel && isSixelPassthroughEnabled()
+				? getSixelLineMask(availableLines)
+				: undefined;
+		const hasSixelOutput = sixelLineMask?.some(Boolean) ?? false;
+		const showingAllLines = this.#expanded || hasSixelOutput;
+		// Only the collapsed preview hides lines; when the full output is shown
+		// the footer must not keep advertising hidden lines / ctrl+o.
+		const hiddenLineCount = showingAllLines ? 0 : Math.max(0, availableLines.length - PREVIEW_LINES);
+		this.#outputPane.configure({ uncapSixel: hasSixelOutput });
+		this.#outputPane.setLines(availableLines);
+
+		// Rebuild content container
+		this.#contentContainer.clear();
+
+		// Command header
+		this.#contentContainer.addChild(this.#headerText);
+
+		// Output
+		if (availableLines.length > 0) this.#contentContainer.addChild(this.#outputPane);
+
+		for (let index = 0; index < this.#images.length; index++) {
+			const image = this.#images[index]!;
+			if (TERMINAL.imageProtocol && this.#showImages) {
+				this.#contentContainer.addChild(
+					new Image(
+						image.data,
+						image.mimeType,
+						{ fallbackColor: text => theme.fg("muted", text) },
+						{
+							...resolveImageOptions(),
+							budget: this.#ui.imageBudget,
+							imageKey: `be${this.#instanceId}:${index}`,
+						},
+					),
+				);
+			} else {
+				const dimensions = getImageDimensions(image.data, image.mimeType) ?? undefined;
+				this.#contentContainer.addChild(
+					new Text(theme.fg("muted", imageFallback(image.mimeType, dimensions)), 1, 0),
+				);
+			}
+		}
+
+		// Loader or status
+		if (this.#status === "running") {
+			this.#contentContainer.addChild(this.#loader);
+		} else {
+			const footer = buildStatusFooter({
+				status: this.#status,
+				exitCode: this.#exitCode,
+				truncation: this.#truncation,
+				artifactError: this.#artifactError,
+				hiddenLineCount,
+				suppressHiddenCount: hasSixelOutput,
+			});
+			if (footer) this.#contentContainer.addChild(footer);
+		}
+	}
+
+	/** PTY replay rows arrive pre-styled (safe SGR + reset); plain lines get muted. */
+	#styleDisplayLine(line: string): string {
+		return this.#ptyMode ? line : theme.fg("muted", line);
+	}
+
+	#clampLinesPreservingSixel(lines: string[]): string[] {
+		if (lines.length === 0) return [];
+		const sixelLineMask = getSixelLineMask(lines);
+		if (!sixelLineMask.some(Boolean)) {
+			return lines.map(clampDisplayLine);
+		}
+		return lines.map((line, index) => (sixelLineMask[index] ? line : clampDisplayLine(line)));
+	}
+
+	#setOutput(output: string): void {
+		const clean = sanitizeWithOptionalSixelPassthrough(output, sanitizeText);
+		this.#outputLines = clean ? this.#clampLinesPreservingSixel(clean.split("\n")) : [];
+	}
+
+	/**
+	 * Get the raw output for creating BashExecutionMessage.
+	 */
+	getOutput(): string {
+		return this.#outputLines.join("\n");
+	}
+
+	/**
+	 * Get the command that was executed.
+	 */
+	getCommand(): string {
+		return this.#command;
+	}
+}

package/src/chat/cache-invalidation-marker.ts

@@ -0,0 +1,94 @@
+import type { Usage } from "@oh-my-pi/pi-ai";
+import { formatNumber } from "@oh-my-pi/pi-utils";
+import { MessageDividerComponent } from "../chrome/message-divider";
+import { theme } from "../theme";
+
+/**
+ * Minimum prefix the previous turn must have READ back from cache before a
+ * collapse on the current turn counts as an invalidation. Filters out tiny
+ * contexts and providers below the cacheable-prefix floor, where a zero
+ * `cacheRead` is expected rather than a reset.
+ */
+const MIN_CACHE_FOOTPRINT = 2048;
+
+/** A prompt-cache invalidation detected from a turn's usage. */
+export interface CacheInvalidation {
+	/** Prompt tokens the cold turn had to (re)process instead of reading from cache. */
+	reprocessedTokens: number;
+}
+
+/**
+ * Decide whether `current` turn lost a *working* prompt cache that `prev` was
+ * reusing.
+ *
+ * The provider reports a warm prefix as `cacheRead`; a model/thinking/tool/
+ * system-prompt change (or a history rewrite) breaks the prefix, so the next
+ * request reads nothing from cache and re-pays for the whole prompt. We flag
+ * only the transition where a demonstrably warm cache goes cold: the previous
+ * turn must have actually READ a meaningful prefix back, and this turn's
+ * `cacheRead` collapsed to zero while it still reprocessed a non-trivial prompt.
+ *
+ * Requiring a prior warm read is deliberate. A turn that merely WROTE the prefix
+ * (`cacheRead` 0) has not proven the cache is live — that is the session's first
+ * request, or a re-write after expiry — so a following cold turn there is
+ * expected, not an invalidation the user caused (e.g. a long-running first tool
+ * call outliving the provider's 5-minute cache TTL surfaced a spurious "cache
+ * miss" right under the opening message). It also collapses a run of consecutive
+ * cold turns to the single marker at the moment the cache actually broke, instead
+ * of repeating the banner on every turn while it re-warms.
+ *
+ * Returns `undefined` (no marker) for the first turn, turns whose predecessor
+ * never read a warm prefix, tiny contexts, turns that reused any cache, and —
+ * crucially — turns on providers with *implicit* best-effort caching. Only an
+ * explicit, prefix-controlled cache (Anthropic / Bedrock `cache_control`)
+ * re-creates the prefix on a cold turn (`cacheWrite > 0`); implicit caches
+ * (Google / OpenAI / Fireworks) report `cacheWrite: 0` and drop `cacheRead` to
+ * zero intermittently as routine propagation noise that self-heals the next
+ * turn, so flagging it would be a false positive.
+ */
+export function detectCacheInvalidation(prev: Usage | undefined, current: Usage): CacheInvalidation | undefined {
+	if (!prev) return undefined;
+	// Only flag a warm→cold transition: the previous turn must have actually read
+	// a meaningful prefix from cache. A write-only predecessor (first request, or
+	// a re-write after expiry) has not proven the cache is live, so a cold turn
+	// behind it is expected — not an invalidation worth surfacing.
+	if (prev.cacheRead < MIN_CACHE_FOOTPRINT) return undefined;
+	// Any cache reuse this turn means the prefix survived (at least partly).
+	if (current.cacheRead > 0) return undefined;
+	// Only an explicit, prefix-controlled cache re-creates the prefix on a cold
+	// turn — Anthropic/Bedrock report that as `cacheWrite`. Implicit best-effort
+	// caches (Google/OpenAI/Fireworks) report `cacheWrite: 0` and drop `cacheRead`
+	// to zero intermittently as propagation noise, not a real invalidation.
+	if (current.cacheWrite <= 0) return undefined;
+	const reprocessedTokens = current.cacheWrite + current.input;
+	if (reprocessedTokens < MIN_CACHE_FOOTPRINT) return undefined;
+	return { reprocessedTokens };
+}
+
+/**
+ * Slim left-aligned divider rendered after an assistant turn whose request lost
+ * the prompt cache. It trails streamed content because usage arrives at message
+ * end, after completed rows may already be in native history.
+ *
+ * Mirrors the compaction divider's banner styling but spans only a short rule
+ * plus label (not the full width) and carries no expandable detail:
+ *
+ *   ────────── ⊘ cache miss · 50.9k tokens
+ */
+export class CacheInvalidationMarkerComponent extends MessageDividerComponent {
+	constructor(info: CacheInvalidation) {
+		super({
+			label: () => {
+				const icon = theme.icon.cacheMiss;
+				const head = icon ? `${icon} cache miss` : "cache miss";
+				const tokens = info.reprocessedTokens;
+				return tokens > 0 ? `${head} ${theme.sep.dot.trim()} ${formatNumber(tokens)} tokens` : head;
+			},
+			labelColor: "muted",
+			ruleColor: "dim",
+			ruleWidth: 10,
+			// Too narrow to frame — preserve the legacy bare label.
+			truncateWhenNarrow: false,
+		});
+	}
+}