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

package/src/tools/xdev.ts

@@ -0,0 +1,201 @@
+import type { ToolTier } from "@oh-my-pi/pi-agent-core";
+import { parseStreamingJson } from "@oh-my-pi/pi-utils";
+import { type Component, Container, Text } from "../index";
+import type { Theme } from "../theme/theme";
+import { replaceTabs } from "../render/render-utils";
+import type { RenderResultOptions, ToolActivitySummary, ToolRenderer } from "./renderer";
+import { renderDefaultToolExecution } from "./default-renderer";
+import { parseMCPToolName } from "./mcp";
+
+/** Mounted device display callbacks, independent of tool execution state. */
+export interface XdevMountedRenderer {
+	label?: string;
+	renderCall?(...args: Parameters<ToolRenderer["renderCall"]>): unknown;
+	renderResult?(...args: Parameters<ToolRenderer["renderResult"]>): unknown;
+	mergeCallAndResult?: boolean;
+}
+
+/** Mounted tool presentation state supplied by the host's canonical tool map. */
+export interface XdevMountedState {
+	readonly mountedNames: ReadonlySet<string>;
+	readonly tools: ReadonlyMap<string, XdevMountedRenderer>;
+}
+
+function isComponent(value: unknown): value is Component {
+	return typeof value === "object" && value !== null && "render" in value && typeof value.render === "function";
+}
+
+/** Result metadata consumed by delegated device rendering. */
+export interface XdevRenderDispatch {
+	tool: string;
+	mode: "help" | "execute";
+	args?: Record<string, unknown>;
+	tier?: ToolTier;
+	inner?: unknown;
+}
+
+let rendererLookup: ((name: string) => ToolRenderer | undefined) | undefined;
+
+/** Wire the wrapped-renderer lookup. Called once by `renderers.ts`. */
+export function setXdevRendererLookup(lookup: (name: string) => ToolRenderer | undefined): void {
+	rendererLookup = lookup;
+}
+
+/** Decode the (possibly partially streamed) inner args JSON string into display args. */
+function decodeInnerArgs(raw: unknown): Record<string, unknown> {
+	if (typeof raw !== "string" || raw.length === 0) return {};
+	const parsed = parseStreamingJson<Record<string, unknown>>(raw);
+	const args: Record<string, unknown> = parsed && typeof parsed === "object" ? { ...parsed } : {};
+	args.__partialJson = raw;
+	return args;
+}
+
+/** Renderer for a mounted device: the live mounted tool's own render callbacks
+ *  (custom/MCP/image tools carry them) first, then the static built-in renderer
+ *  map keyed by name. */
+function resolveDeviceRenderer(
+	name: string,
+	mounted: XdevMountedRenderer | undefined,
+): XdevMountedRenderer | undefined {
+	if (mounted && (mounted.renderCall || mounted.renderResult)) {
+		return mounted;
+	}
+	return rendererLookup?.(name);
+}
+
+/** Human label for a device write: mounted tool label, else `server/tool` for MCP names. */
+function displayDeviceLabel(name: string, mounted?: { label?: string }): string {
+	if (mounted?.label) return mounted.label;
+	const parsed = parseMCPToolName(name);
+	if (parsed) return `${parsed.serverName}/${parsed.toolName}`;
+	return name;
+}
+/** Salient inner-arg keys for the compact activity line: the verb first, then its object. */
+const ACTIVITY_VERB_KEYS = ["action", "op", "command"] as const;
+const ACTIVITY_OBJECT_KEYS = ["query", "symbol", "path", "file", "pattern", "url", "name"] as const;
+
+/**
+ * Compact `label · verb object` activity summary for a device write, so a
+ * squeezed transcript row reads `LSP · references foo` instead of
+ * `Write · xd://lsp`. Prose payloads (resolution devices, report_issue)
+ * surface their first line instead.
+ */
+export function xdevActivitySummary(
+	name: string,
+	content: unknown,
+	resolveMounted?: (name: string) => XdevMountedRenderer | undefined,
+): ToolActivitySummary {
+	const mounted = resolveMounted?.(name);
+	const args = decodeInnerArgs(content);
+	const pick = (keys: readonly string[]): string | undefined => {
+		for (const key of keys) {
+			const value = args[key];
+			if (typeof value === "string" && value.length > 0) return value.split("\n", 1)[0];
+		}
+		return undefined;
+	};
+	let detail = [pick(ACTIVITY_VERB_KEYS), pick(ACTIVITY_OBJECT_KEYS)].filter(Boolean).join(" ");
+	if (!detail && typeof content === "string" && !content.trimStart().startsWith("{")) {
+		detail = content.trim().split("\n", 1)[0];
+	}
+	return { label: displayDeviceLabel(name, mounted), detail: detail || undefined };
+}
+
+/** Drop the streaming-decode bookkeeping key before showing inner args. */
+function displayDeviceArgs(args: Record<string, unknown>): Record<string, unknown> {
+	const { __partialJson: _partial, ...rest } = args;
+	return rest;
+}
+
+/** Pre-execution card so a streamed `xd://` write does not look like a hung MCP call. */
+function renderQueuedXdevCall(
+	label: string,
+	args: Record<string, unknown>,
+	options: RenderResultOptions,
+	theme: Theme,
+): Component {
+	return renderDefaultToolExecution(
+		{
+			label: `queued ${label}`,
+			args: displayDeviceArgs(args),
+			options: { ...options, isPartial: true, spinnerFrame: undefined },
+		},
+		theme,
+	);
+}
+
+/**
+ * Streaming-safe call preview for an `xd://` write. Until the write actually
+ * executes (`executionStarted` / `tool_execution_start`), show a queued/planning
+ * card so Grok-style think-after-toolcall stalls do not look like a hung
+ * inner tool. `argsComplete` alone is not enough: exclusive writes can sit
+ * complete at `message_end` while an earlier call still runs. Once execution
+ * starts, forward the decoded inner args to the mounted tool's renderer
+ * (session instance first, then the static map). Returns `undefined` (render
+ * nothing) when no renderer produces output.
+ */
+export function renderXdevCall(
+	name: string,
+	content: unknown,
+	options: RenderResultOptions,
+	theme: Theme,
+	resolveMounted?: (name: string) => XdevMountedRenderer | undefined,
+): Component | undefined {
+	const mounted = resolveMounted?.(name);
+	const args = decodeInnerArgs(content);
+	if (!options.executionStarted) {
+		return renderQueuedXdevCall(displayDeviceLabel(name, mounted), args, options, theme);
+	}
+	const renderer = resolveDeviceRenderer(name, mounted);
+	if (renderer?.renderCall) {
+		const rendered = renderer.renderCall(args, options, theme);
+		return isComponent(rendered) ? rendered : undefined;
+	}
+	return renderDefaultToolExecution({ label: mounted?.label ?? name, args, options }, theme);
+}
+
+/** Forward an `xd://` dispatch result to the mounted tool's renderer. */
+export function renderXdevResult(
+	dispatch: XdevRenderDispatch,
+	result: { content: Array<{ type: string; text?: string }>; isError?: boolean },
+	options: RenderResultOptions,
+	theme: Theme,
+	resolveMounted?: (name: string) => XdevMountedRenderer | undefined,
+): Component | undefined {
+	const text = result.content
+		.map(block => (block.type === "text" ? block.text : ""))
+		.filter(Boolean)
+		.join("\n");
+	if (dispatch.mode === "help") {
+		return text ? new Text(theme.fg("toolOutput", replaceTabs(text)), 0, 0) : undefined;
+	}
+	const mounted = resolveMounted?.(dispatch.tool);
+	const renderer = resolveDeviceRenderer(dispatch.tool, mounted);
+	const innerResult = { content: result.content, details: dispatch.inner, isError: result.isError };
+	if (renderer?.renderResult) {
+		const parts: Component[] = [];
+		// Emulate the unmerged call+result topology inside the write block for
+		// renderers that expect a separate call header.
+		if (!renderer.mergeCallAndResult && renderer.renderCall) {
+			const call = renderer.renderCall(dispatch.args ?? {}, { ...options, isPartial: false }, theme);
+			if (isComponent(call)) parts.push(call);
+		}
+		const rendered = renderer.renderResult(innerResult, options, theme, dispatch.args ?? {});
+		if (isComponent(rendered)) parts.push(rendered);
+		if (parts.length === 1) return parts[0];
+		if (parts.length > 1) {
+			const box = new Container();
+			for (const part of parts) box.addChild(part);
+			return box;
+		}
+	}
+	return renderDefaultToolExecution(
+		{
+			label: mounted?.label ?? dispatch.tool,
+			args: dispatch.args ?? {},
+			result: { output: text, isError: result.isError },
+			options,
+		},
+		theme,
+	);
+}

package/src/tui.ts

@@ -52,7 +52,8 @@ import {
 	visibleWidth,
 } from "./utils";
 
-const SEGMENT_RESET = "\x1b[0m";
+/** Full-attribute reset terminating each rendered content row. */
+export const SEGMENT_RESET = "\x1b[0m";
 /**
  * Per-line terminator written after every non-image content row. It closes both
  * SGR state and any in-flight OSC 8 hyperlink so styles/links cannot bleed
@@ -122,8 +123,23 @@ export interface RenderScheduler {
 	scheduleRender(callback: () => void, delayMs: number): RenderTimer;
 }
 
+/** Rows painted by one TUI frame, observed through `TUIOptions.onPaint`. */
+export interface TuiPaint {
+	/** Rows committed above the viewport by this paint (native scrollback). Empty on diff paints and alt-screen paints. */
+	readonly history: readonly string[];
+	/** Complete live viewport after this paint: one prepared (normalized, width-truncated, SGR-coalesced) ANSI string per row. */
+	readonly viewport: readonly string[];
+	/** True when this paint erased scrollback and repainted from row zero (destructive reset or history replay): consumers drop their history copy before applying `history`. */
+	readonly reset: boolean;
+	/** True when `viewport` is an alternate-screen overlay; history is untouched. */
+	readonly alt: boolean;
+	readonly columns: number;
+	readonly rows: number;
+}
+
 export interface TUIOptions {
 	renderScheduler?: RenderScheduler;
+	onPaint?: (paint: TuiPaint) => void;
 }
 /** Physical terminal dimensions supplied to a frame provider. */
 export interface ViewportSize {
@@ -773,6 +789,7 @@ export class TUI extends Container {
 	#debugNextWindowTop = 0;
 	#inputListeners = new Set<InputListener>();
 	#startListeners = new Set<StartListener>();
+	#paintListener: ((paint: TuiPaint) => void) | null;
 
 	/** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
 	onDebug?: () => void;
@@ -905,6 +922,7 @@ export class TUI extends Container {
 		super();
 		this.terminal = terminal;
 		this.#renderScheduler = options?.renderScheduler ?? DEFAULT_RENDER_SCHEDULER;
+		this.#paintListener = options?.onPaint ?? null;
 		this.#showHardwareCursor = showHardwareCursor === undefined ? this.#showHardwareCursor : showHardwareCursor;
 		this.#watchdog = new LoopWatchdog();
 	}
@@ -913,6 +931,11 @@ export class TUI extends Container {
 		return mode === "append" || mode === "rebuild" || mode === "preserve" ? mode : "preserve";
 	}
 
+	/** Install a listener for completed terminal paints. */
+	setPaintListener(listener: ((paint: TuiPaint) => void) | null): void {
+		this.#paintListener = listener;
+	}
+
 	/** Install the product-owned bounded frame provider. */
 	setFrameProvider(provider: TerminalFrameProvider | undefined): void {
 		this.#frameProvider = provider;
@@ -1723,7 +1746,8 @@ export class TUI extends Container {
 		} while (this.#imageBudget.endPass());
 		const viewport = rendered.length > height ? rendered.slice(rendered.length - height) : Array.from(rendered);
 		this.#extractCursorMarkers(viewport);
-		this.#emitAltFrame(this.#prepareLinesArray(viewport, width, this.#altPreparedRows, height), width, height);
+		// The borrowed resize buffer is transient, not a streamable session paint.
+		this.#emitAltFrame(this.#prepareLinesArray(viewport, width, this.#altPreparedRows, height), width, height, false);
 	}
 
 	/**
@@ -2603,6 +2627,15 @@ export class TUI extends Container {
 	#terminalLine(line: PreparedLine): string {
 		return line.terminalContent + (line.hasOsc8 ? LINE_TERMINATOR : SEGMENT_RESET);
 	}
+
+	#notifyPaint(paint: TuiPaint): void {
+		try {
+			this.#paintListener?.(paint);
+		} catch (err) {
+			logger.error("TUI paint listener failed", { err });
+		}
+	}
+
 	#renderProviderFrame(width: number, height: number): void {
 		const provider = this.#frameProvider;
 		if (!provider || width <= 0 || height <= 0) return;
@@ -2773,9 +2806,10 @@ export class TUI extends Container {
 		const pendingAltExit = this.#pendingAltExit;
 		let buffer = this.#paintBeginSequence + pendingAltExit;
 		if (destructiveReset && TERMINAL.imageProtocol === ImageProtocol.Kitty) {
-			// ED2/ED3 erase text cells but leave Kitty graphics visible. A reset is
-			// explicitly destructive, so remove every placement—not only the ones
-			// this TUI tracked—then resend images composed for the clean replay.
+			// A reset is explicitly destructive, so remove every placement—not only
+			// the ones this TUI tracked—then resend images composed for the clean
+			// replay. ED2 below reclaims the rest, but only on terminals that treat
+			// an erase as a graphics clear; the explicit delete covers the others.
 			buffer += encodeKittyDeleteAllImages();
 			// `d=A` spares virtual placements, and erasing the placeholder text it
 			// leaves behind does not remove the prototype either. The ids this
@@ -2789,7 +2823,6 @@ export class TUI extends Container {
 		} else {
 			this.#imageBudget.takePurgeIds();
 		}
-		for (const sequence of this.#imageBudget.takeTransmits()) buffer += sequence;
 		// ED2 MUST precede ED3: tmux implements ED2 by scrolling the live screen
 		// into pane history (so cleared content stays reachable), so erasing
 		// history first would let ED2 refill it with a copy of the old screen —
@@ -2797,7 +2830,16 @@ export class TUI extends Container {
 		// ED2-then-ED3 clears the screen, then wipes history including that
 		// push. On xterm-family terminals the two erases are independent and
 		// the order is irrelevant.
+		//
+		// Both erases MUST precede the image transmits. kitty and Ghostty treat
+		// ED2 as a graphics clear that also frees every image left without a
+		// placement — which is exactly what freshly transmitted data is until
+		// the row carrying its placement is written. Transmitting first let the
+		// erase reclaim the data, so the replay's placements then referenced an
+		// image the terminal no longer had and every inline image vanished
+		// after a settled width resize.
 		if (destructiveReset) buffer += "\x1b[H\x1b[2J\x1b[3J";
+		for (const sequence of this.#imageBudget.takeTransmits()) buffer += sequence;
 		const diffable =
 			geometryStable &&
 			historyRows.length === 0 &&
@@ -2914,6 +2956,16 @@ export class TUI extends Container {
 		this.#forceViewportRepaintOnNextRender = false;
 		this.#hasEverRendered = true;
 		this.#resizeReplaySize = undefined;
+		// Replay-split rows in `prepared.lines` now occupy the physical viewport;
+		// only `preparedHistory.lines` crossed above it into native scrollback.
+		this.#notifyPaint({
+			history: preparedHistory.lines,
+			viewport: prepared.lines,
+			reset: destructiveReset || history?.kind === "replay",
+			alt: false,
+			columns: width,
+			rows: height,
+		});
 		if (history !== undefined) {
 			this.#acceptedHistoryBatchId = history.id;
 			provider?.acknowledgeHistory(history.id);
@@ -3475,7 +3527,7 @@ export class TUI extends Container {
 		} while (this.#imageBudget.endPass());
 		this.#extractCursorMarkers(lines);
 		const prepared = this.#prepareLinesArray(lines, width, this.#altPreparedRows, height);
-		this.#emitAltFrame(prepared, width, height);
+		this.#emitAltFrame(prepared, width, height, true);
 	}
 
 	/**
@@ -3483,7 +3535,7 @@ export class TUI extends Container {
 	 * brackets, a cursor home, and per-row rewrites — never ED3 or any
 	 * native-scrollback byte. The hardware cursor stays hidden here.
 	 */
-	#emitAltFrame(prepared: PreparedLines, width: number, height: number): void {
+	#emitAltFrame(prepared: PreparedLines, width: number, height: number, notifyPaint: boolean): void {
 		// The pass that composed this frame ran with `altScreen`, so the normal
 		// screen's own placements behind it are not treated as retired.
 		this.#imageBudget.limitResidentImages();
@@ -3548,6 +3600,16 @@ export class TUI extends Container {
 		this.#altPreviousLines = prepared.lines;
 		this.#altPreparedRows = prepared.rows;
 		this.#debugPaint = { lines: prepared.lines, windowTop: 0, altScreen: true };
+		if (notifyPaint) {
+			this.#notifyPaint({
+				history: [],
+				viewport: prepared.lines,
+				reset: false,
+				alt: true,
+				columns: width,
+				rows: height,
+			});
+		}
 		this.#fullRedrawCount += 1;
 	}
 }

package/src/utils.ts

@@ -209,6 +209,14 @@ export function padding(n: number): string {
 	return " ".repeat(n);
 }
 
+/** Center a line in a field of `width` columns, truncating when too wide. */
+export function centerLine(line: string, width: number): string {
+	const lineWidth = visibleWidth(line);
+	if (lineWidth >= width) return truncateToWidth(line, width);
+	const left = Math.floor((width - lineWidth) / 2);
+	return padding(left) + line + padding(width - left - lineWidth);
+}
+
 // Grapheme segmenter (shared instance)
 const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });