@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/tools/read.ts

@@ -6,20 +6,38 @@ import * as path from "node:path";
 import { parseArchivePathCandidates } from "@oh-my-pi/pi-utils/ar";
 import type { Component } from "../tui";
 import { Text } from "../components/text";
-import type { RenderResultOptions, ToolActivityContext, ToolActivitySummary, ToolRenderer } from "./renderer";
+import type {
+	NativeToolHead,
+	NativeToolView,
+	RenderResultOptions,
+	ToolActivityContext,
+	ToolActivitySummary,
+	ToolRenderer,
+} from "./renderer";
+import { ansi, compact, md } from "../native/describe";
+import { base64ImageNode } from "../native/blobs";
+import type { NativeChild, NativeNode } from "../native/node";
+import { fileHref, footnoteText, inlineErrorView, resultText } from "./native-view";
+import { numberedCode } from "./grouped-file-output";
 import { getLanguageFromPath } from "../lang-from-path";
 import type { Theme } from "../theme/theme";
 import { fileHyperlink, renderCodeCell, renderMarkdownCell, renderStatusLine } from "../render";
 import { markFramedBlockComponent } from "../render/output-block";
 import { framedToolCard } from "../render/tool-card";
-import { type ReadUrlToolDetails, renderReadUrlCall, renderReadUrlResult } from "./fetch";
+import {
+	describeReadUrlCall,
+	describeReadUrlResult,
+	type ReadUrlToolDetails,
+	renderReadUrlCall,
+	renderReadUrlResult,
+} from "./fetch";
 import { formatFullOutputReference, formatStyledTruncationWarning, stripOutputNotice } from "./output-meta";
 import { formatBytes, sanitizeDisplayLines, shortenPath, wrapBrackets } from "../render/render-utils";
 
 import type { OutputMeta } from "./output-meta";
 import type { TruncationResult } from "./streaming-output";
-import { renderProcRead, type ProcReadDetails } from "./proc-render";
-import { renderCfgRead, type CfgReadDetails } from "./cfg-render";
+import { describeProcRead, renderProcRead, type ProcReadDetails } from "./proc-render";
+import { describeCfgRead, renderCfgRead, type CfgReadDetails } from "./cfg-render";
 import type { CardToolResult } from "./result-card";
 import { type InternalUrlSchemeSpec, internalUrlSchemeSpec, splitUrlScheme } from "./url-scheme-host";
 
@@ -313,6 +331,102 @@ function formatReadPathLink(
 	return `${linkedPath}${selectorSuffix}`;
 }
 
+function readRawPath(args: ReadRenderArgs | undefined): string {
+	return typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
+}
+
+/**
+ * Native read head (§7.3 read): `Read path:13-36` with the path as the
+ * target (shortened, plus the selector / legacy offset range), a `file://`
+ * link when the fs path is known, and a suffix correction as meta.
+ */
+function readNativeHead(rawPath: string, args: ReadRenderArgs | undefined, details?: ReadToolDetails): NativeToolHead {
+	const split = splitReadRenderPath(rawPath);
+	const suffix = details?.suffixResolution;
+	let target = suffix ? shortenPath(suffix.to) : shortenPath(split.path || rawPath);
+	if (split.sel) target += `:${split.sel}`;
+	if (args?.offset !== undefined || args?.limit !== undefined) {
+		const startLine = args.offset ?? 1;
+		const endLine = args.limit !== undefined ? startLine + args.limit - 1 : "";
+		target += `:${startLine}${endLine ? `-${endLine}` : ""}`;
+	}
+	const meta: string[] = [];
+	if (suffix) meta.push(`corrected from ${shortenPath(suffix.from)}`);
+	if (details?.summary) {
+		const n = details.summary.elidedSpans;
+		meta.push(`summary: ${n} elided span${n === 1 ? "" : "s"}`);
+	}
+	const conflicts = details?.conflictCount ?? 0;
+	return {
+		title: "Read",
+		target: target || "…",
+		targetKind: "path",
+		href: fileHref(details?.resolvedPath ?? details?.displayTarget ?? readSourceFsPath(details)),
+		meta,
+		badges:
+			conflicts > 0 ? [{ text: `${conflicts} conflict${conflicts === 1 ? "" : "s"}`, tone: "warning" }] : undefined,
+	};
+}
+
+/**
+ * The first line a read shows: the selector's (or legacy `offset`'s) range
+ * start, so legacy results without `displayContent` still number from there.
+ */
+function readRangeStart(rawPath: string, args: ReadRenderArgs | undefined): number {
+	const sel = splitReadRenderPath(rawPath).sel;
+	return firstReadSelectorLine(sel) ?? args?.offset ?? 1;
+}
+
+/**
+ * Read content as numbered `code` (no path header: the head names the file).
+ * Numbers come from `lineNumbers` (`displayContent`'s per-line numbers,
+ * `null` for an elided block; runs split with `…` between) when they cover
+ * every line, else count up from `start`.
+ */
+export function readContentCode(
+	content: string,
+	start: number,
+	numbers: readonly (number | null)[] | undefined,
+	lang: string | undefined,
+): NativeNode[] {
+	const lines = content.split("\n");
+	return numberedCode(
+		lines.map((text, i) => ({ n: numbers && numbers.length === lines.length ? numbers[i]! : start + i, text })),
+		{ lang },
+	);
+}
+
+/** An image content block as the read tool emits it (base64 data + mime type). */
+interface ReadImageBlock {
+	type: "image";
+	data: string;
+	mimeType: string;
+}
+
+function isImageBlock(block: { type: string }): block is ReadImageBlock {
+	return (
+		block.type === "image" &&
+		typeof (block as Partial<ReadImageBlock>).data === "string" &&
+		typeof (block as Partial<ReadImageBlock>).mimeType === "string"
+	);
+}
+
+/** Cached `image` node on its content block, so decoding and hashing happen once per block. */
+const kReadImageNode = Symbol("read.imageNode");
+
+interface TaggedReadImageBlock extends ReadImageBlock {
+	[kReadImageNode]?: NativeNode;
+}
+
+/** Native `image` node for a read image: registered blob, alt = displayed path, source pixel size when parseable. */
+function describeReadImage(block: TaggedReadImageBlock, alt: string): NativeNode {
+	const cached = block[kReadImageNode];
+	if (cached) return cached;
+	const described = base64ImageNode(block.data, block.mimeType, { alt: alt || "image", role: "omp.tool.read.image" });
+	block[kReadImageNode] = described;
+	return described;
+}
+
 /** Render file, image, and URL reads in the transcript. */
 export const readToolRenderer = {
 	activitySummary(args: unknown, _context: ToolActivityContext): ToolActivitySummary {
@@ -527,6 +641,87 @@ export const readToolRenderer = {
 			},
 		});
 	},
+	describeCall(args: ReadRenderArgs): NativeToolView {
+		const rawPath = readRawPath(args);
+		const routed = readUrlCard(rawPath);
+		if (routed?.card.detailsKey === "proc") return describeProcRead(routed.target, undefined, undefined);
+		if (routed) return describeCfgRead(splitInternalUrlSel(rawPath).path, undefined, undefined);
+		if (isReadableUrlPath(rawPath)) return describeReadUrlCall({ path: rawPath, raw: args.raw });
+		return { tool: readNativeHead(rawPath, args), inline: true };
+	},
+
+	/**
+	 * Inline (§7.3 read): the head names the file and range; the content
+	 * (numbered from the range start, no path header) is the disclosed body.
+	 * An error shows its message in the head, never behind the disclosure.
+	 */
+	describeResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: ReadToolDetails; isError?: boolean },
+		_options: RenderResultOptions,
+		args?: ReadRenderArgs,
+	): NativeToolView {
+		const details = result.details;
+		const rawPath = readRawPath(args);
+		const routed = readUrlCard(rawPath, details);
+		if (routed?.card.detailsKey === "proc") return describeProcRead(routed.target, result, details?.proc);
+		if (routed) return describeCfgRead(splitInternalUrlSel(rawPath).path, result, details?.cfg);
+		if (details?.kind === "url" || isReadableUrlPath(rawPath)) {
+			return describeReadUrlResult({
+				content: result.content,
+				details: result.details as ReadUrlToolDetails | undefined,
+				isError: result.isError,
+			});
+		}
+
+		if (result.isError) {
+			const message = (resultText(result) || "Unknown error").replace(/^Error:\s*/, "");
+			return inlineErrorView(readNativeHead(rawPath, args, details), message);
+		}
+
+		const suffix = details?.suffixResolution;
+		const head = readNativeHead(rawPath, args, details);
+		const truncation = details?.meta?.truncation;
+		const fallback = details?.truncation;
+		const firstLineTooLong = truncation !== undefined && fallback?.firstLineExceedsLimit === true;
+		const foot = footnoteText(
+			compact([
+				details?.resolvedPath !== undefined && `resolved ${shortenPath(details.resolvedPath)}`,
+				firstLineTooLong &&
+					`First line exceeds ${formatBytes(fallback.outputBytes ?? fallback.totalBytes)} limit${truncation.artifactId ? `. ${formatFullOutputReference(truncation.artifactId)}` : ""}`,
+			]),
+			firstLineTooLong ? { artifactError: details?.meta?.artifactError } : details?.meta,
+		);
+
+		const contentText = details?.displayContent?.text ?? stripOutputNotice(resultText(result), details?.meta);
+		const imageBlock = result.content?.find(isImageBlock);
+		if (imageBlock) {
+			const detailText = contentText.trim();
+			return {
+				tool: head,
+				tone: suffix ? "warning" : undefined,
+				inline: true,
+				body: compact<NativeChild>([
+					describeReadImage(imageBlock, shortenPath(suffix?.to ?? splitReadRenderPath(rawPath).path)),
+					detailText.length > 0 && ansi(detailText),
+					foot,
+				]),
+			};
+		}
+
+		const renderPath = splitReadRenderPath(rawPath);
+		const rawRequested =
+			args?.raw === true || renderPath.sel?.split(":").some(chunk => chunk.toLowerCase() === "raw") === true;
+		const content: NativeChild[] =
+			details?.contentType === "text/markdown" && !rawRequested
+				? [md(contentText)]
+				: readContentCode(
+						contentText,
+						details?.displayContent?.startLine ?? readRangeStart(rawPath, args),
+						details?.displayContent?.lineNumbers,
+						getLanguageFromPath(renderPath.path),
+					);
+		return { tool: head, inline: true, body: compact<NativeChild>([...content, foot]) };
+	},
 	mergeCallAndResult: true,
 } satisfies ToolRenderer<ReadRenderArgs, ReadToolDetails>;
 

package/src/tools/renderer.ts

@@ -3,6 +3,8 @@
  * transcript components. Built-in renderers live beside this file; the
  * coding-agent tools implement the matching `*Details` payloads.
  */
+import type { TspPreview, TspText, TspTone, TspToolProps } from "@oh-my-pi/pi-wire";
+import type { NativeChild } from "../native/node";
 import type { Component } from "../tui";
 import type { Theme } from "../theme/theme";
 
@@ -62,6 +64,54 @@ export interface ToolActivityContext {
 	readonly renderContext?: Record<string, unknown>;
 }
 
+/**
+ * The data head of a tool call (NATIVE_REDESIGN §7.2): what the terminal
+ * draws in the `tool` kind's head. Each fact appears once — a target named
+ * here is never repeated in the body.
+ */
+export interface NativeToolHead {
+	/** The verb ("Bash", "Edit"); defaults to the tool's label. */
+	readonly title?: TspText;
+	/** The primary argument, shown once: command, path, pattern, query. */
+	readonly target?: TspText;
+	readonly targetKind?: TspToolProps["targetKind"];
+	/** Language for `command` targets. */
+	readonly lang?: string;
+	/** `file://` link for path targets. */
+	readonly href?: string;
+	/** Short facts after the target (`+8 −1`, `5 matches · 2 files`). */
+	readonly meta?: readonly TspText[];
+	readonly badges?: TspToolProps["badges"];
+	/** A one-word state note ("timed out", "partial"). */
+	readonly note?: TspText;
+	/** A non-zero exit code (error chip). */
+	readonly exit?: number | null;
+}
+
+/**
+ * A tool's semantic presentation for Tern Surface Protocol terminals.
+ * `ToolExecutionComponent` wraps it in a `tool` node (terminals that list
+ * the kind) or, as the fallback, a `card` (role `omp.tool.<name>`, status,
+ * elapsed timer, collapse): the renderer supplies only the head data and the
+ * body nodes, never frames, padding or width math.
+ */
+export interface NativeToolView {
+	/** The data head; the fallback card's head spans derive from it when {@link head} is absent. */
+	readonly tool?: NativeToolHead;
+	/** Header spans for the fallback card (and the `tool` title when {@link tool} is absent). */
+	readonly head?: TspText;
+	/** Body: sections, never frames. */
+	readonly body?: readonly NativeChild[];
+	/** Tone override; the frame otherwise derives it from the call status. */
+	readonly tone?: TspTone;
+	/** Body clamp while collapsed; `{tail}` keeps the end (terminal output). Defaults to the transcript's preview size. */
+	readonly preview?: TspPreview | { readonly tail: number } | "none";
+	/** Render frameless (`frame:"inline"`): a head line plus a disclosed body. */
+	readonly inline?: boolean;
+	/** Head actions offered on hover (`copy`, `retry`). */
+	readonly tools?: TspToolProps["tools"];
+}
+
 /**
  * A tool's transcript presentation: call preview, result view, and repaint/animation hints.
  * Method signatures are intentionally bivariant so a renderer typed over its own
@@ -76,6 +126,17 @@ export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
 		theme: Theme,
 		args?: TArgs,
 	): Component | undefined;
+	/**
+	 * Semantic call preview for TSP terminals. When a renderer implements the
+	 * describe hooks, the native backend never calls `renderCall`/`renderResult`.
+	 */
+	describeCall?(args: TArgs, options: RenderResultOptions): NativeToolView | undefined;
+	/** Semantic result view for TSP terminals; merged with the call view when {@link mergeCallAndResult}. */
+	describeResult?(
+		result: ToolRenderResult<TDetails>,
+		options: RenderResultContextOptions,
+		args?: TArgs,
+	): NativeToolView | undefined;
 	mergeCallAndResult?: boolean;
 	/** Describes current activity without coupling a renderer to terminal layout. */
 	activitySummary?(args: TArgs, context: ToolActivityContext): ToolActivitySummary;

package/src/tools/report-tool-issue.ts

@@ -1,12 +1,18 @@
 import type { Component } from "../index";
 import type { Theme } from "../theme/theme";
-import { renderDeviceCallPreview } from "./resolve";
+import type { NativeToolView } from "./renderer";
+import { describeDeviceCallPreview, renderDeviceCallPreview } from "./resolve";
 
 /** Call preview for an `xd://report_issue` write. */
 export function renderReportIssueDeviceCall(content: unknown, uiTheme: Theme): Component {
 	return renderDeviceCallPreview("Report Tool Issue", content, uiTheme);
 }
 
+/** Native call preview for an `xd://report_issue` write. */
+export function describeReportIssueDeviceCall(content: unknown): NativeToolView {
+	return describeDeviceCallPreview("Report Tool Issue", content);
+}
+
 /** Device name for automatic tool issue reports. */
 export const REPORT_ISSUE_DEVICE_NAME = "report_issue";
 /** Internal device URL for automatic tool issue reports. */

package/src/tools/resolve.ts

@@ -3,7 +3,13 @@ import type { ToolRenderer } from "./renderer";
 import type { Component } from "../index";
 import { Text } from "../index";
 
-import type { RenderResultOptions } from "./renderer";
+import type { NativeToolView, RenderResultOptions } from "./renderer";
+
+import type { TspSpan } from "@oh-my-pi/pi-wire";
+import { span, text } from "../native/describe";
+import { OwnerMemo } from "../native/memo";
+import { plainText } from "../native/spans";
+import { noteText, toolHead } from "./native-view";
 
 import type { Theme } from "../theme/theme";
 
@@ -47,6 +53,20 @@ export function renderResolutionDeviceCall(device: ResolutionDeviceName, content
 	return renderDeviceCallPreview(title, content, uiTheme, Ellipsis.Omit);
 }
 
+/** Native form of {@link renderResolutionDeviceCall}: `Resolve/Reject/Propose` head with the first content line. */
+export function describeResolutionDeviceCall(device: ResolutionDeviceName, content: unknown): NativeToolView {
+	const title = device === PROPOSE_DEVICE_NAME ? "Propose" : device === REJECT_DEVICE_NAME ? "Reject" : "Resolve";
+	return describeDeviceCallPreview(title, content);
+}
+
+/** Native form of {@link renderDeviceCallPreview}: title head plus the first content line of a pending device write. */
+export function describeDeviceCallPreview(title: string, content: unknown): NativeToolView {
+	const body = typeof content === "string" ? (plainText(content).trim().split("\n")[0] ?? "") : "";
+	return { head: toolHead(title, body || undefined) };
+}
+
+const resolveResultMemo = new OwnerMemo<NativeToolView | undefined>();
+
 /** Render the first content line of a pending device write. */
 export function renderDeviceCallPreview(
 	title: string,
@@ -129,6 +149,48 @@ export const resolveRenderer = {
 		};
 	},
 
+	describeCall(args: Partial<ResolveInvocation>): NativeToolView {
+		const head: TspSpan[] = toolHead("Resolve", args.action);
+		if (args.action) {
+			head.push(
+				span(" "),
+				span(
+					args.action === "apply" ? "proposed → resolved" : "proposed → rejected",
+					args.action === "apply" ? "success" : "warning",
+				),
+			);
+		}
+		const reason = args.reason?.trim();
+		return { head, inline: true, body: reason ? [noteText(reason, "muted", 1)] : undefined };
+	},
+
+	describeResult(result: {
+		content: Array<{ type: string; text?: string }>;
+		details?: ResolveDetails;
+		isError?: boolean;
+	}): NativeToolView | undefined {
+		return resolveResultMemo.get(result, [], () => {
+			const details = result.details;
+			const label = plainText(details?.label ?? "pending action");
+			const reason = plainText(details?.reason?.trim() || "No reason provided");
+			const action = details?.action ?? "apply";
+			const isApply = action === "apply" && !result.isError;
+			const verb = isApply ? "Accept" : action === "apply" ? "Failed" : "Discard";
+			const tone = result.isError ? "error" : isApply ? "success" : "warning";
+			const separatorIndex = label.indexOf(": ");
+			const sourceLabel = separatorIndex > 0 ? label.slice(0, separatorIndex).trim() : undefined;
+			const summaryLabel = separatorIndex > 0 ? label.slice(separatorIndex + 2).trim() : label;
+			const head: TspSpan[] = [span(`${verb}:`, `strong ${tone}`), span(" "), span(summaryLabel)];
+			if (sourceLabel) head.push(span(" "), span(`[${sourceLabel}]`, "strong muted"));
+			return {
+				head,
+				tone,
+				inline: true,
+				body: [text([span(reason, "muted")], { wrap: "word" })],
+			};
+		});
+	},
+
 	inline: true,
 	mergeCallAndResult: true,
 } satisfies ToolRenderer<Partial<ResolveInvocation>, ResolveDetails>;

package/src/tools/streaming-output.ts

@@ -718,6 +718,12 @@ const MAX_PENDING = 10;
 export class TailBuffer {
 	#pending: string[] = [];
 	#pos = 0; // byte count of the currently-held tail (after trims)
+	// `#pending[0]` and its byte count. Clean = well-formed and `#headBytes` is its exact
+	// UTF-8 length (a head compacted from chunks that split a surrogate pair is neither).
+	#headBytes = 0;
+	#headClean = true;
+	// Every chunk after `#pending[0]` is well-formed (no lone surrogates).
+	#restWellFormed = true;
 
 	constructor(readonly maxBytes: number) {}
 
@@ -726,8 +732,7 @@ export class TailBuffer {
 
 		const max = this.maxBytes;
 		if (max === 0) {
-			this.#pending.length = 0;
-			this.#pos = 0;
+			this.#setHead("", 0, true);
 			return;
 		}
 
@@ -736,19 +741,17 @@ export class TailBuffer {
 		// If the incoming chunk alone is >= budget, it fully dominates the tail.
 		if (n >= max) {
 			const { text: t, bytes } = truncateTailBytes(text, max);
-			this.#pending[0] = t;
-			this.#pending.length = 1;
-			this.#pos = bytes;
+			// A chunk of exactly `max` bytes comes back verbatim, lone surrogates included.
+			this.#setHead(t, bytes, t.isWellFormed());
 			return;
 		}
 
-		this.#pos += n;
-
 		if (this.#pending.length === 0) {
-			this.#pending[0] = text;
-			this.#pending.length = 1;
+			this.#setHead(text, n, text.isWellFormed());
 		} else {
+			this.#pos += n;
 			this.#pending.push(text);
+			if (this.#restWellFormed && !text.isWellFormed()) this.#restWellFormed = false;
 			if (this.#pending.length > MAX_PENDING) this.#compact();
 		}
 
@@ -770,9 +773,22 @@ export class TailBuffer {
 
 	// -- private ---------------------------------------------------------------
 
+	/** Replace the whole buffer with a single chunk. */
+	#setHead(text: string, bytes: number, clean: boolean): void {
+		this.#pending[0] = text;
+		this.#pending.length = 1;
+		this.#pos = bytes;
+		this.#headBytes = bytes;
+		this.#headClean = clean;
+		this.#restWellFormed = true;
+	}
+
 	#compact(): void {
 		this.#pending[0] = this.#pending.join("");
 		this.#pending.length = 1;
+		this.#headBytes = this.#pos;
+		this.#headClean = this.#headClean && this.#restWellFormed;
+		this.#restWellFormed = true;
 	}
 
 	#flush(): string {
@@ -783,17 +799,64 @@ export class TailBuffer {
 
 	#trimTo(max: number): void {
 		if (max === 0) {
-			this.#pending.length = 0;
-			this.#pos = 0;
+			this.#setHead("", 0, true);
 			return;
 		}
 		if (this.#pos <= max) return;
 
-		const joined = this.#flush();
-		const { text, bytes } = truncateTailBytes(joined, max);
-		this.#pos = bytes;
-		this.#pending[0] = text;
-		this.#pending.length = 1;
+		// Steady state (one `text()` per appended chunk): the overflow lies inside the
+		// already-trimmed head, so only the head's front is cut and the chunks after it
+		// are kept verbatim instead of re-encoding the whole window. Those chunks must be
+		// well-formed: the full path round-trips them through UTF-8, which rewrites lone
+		// surrogates (and heals pairs split across chunk boundaries).
+		const restBytes = this.#pos - this.#headBytes;
+		if (restBytes < max && this.#restWellFormed) {
+			const head = this.#pending[0];
+			const keep = max - restBytes;
+			const drop = this.#headBytes - keep;
+			if (head.length === this.#headBytes) {
+				// All-ASCII head: byte offsets are char offsets and every byte is a boundary.
+				this.#pending[0] = head.slice(drop);
+				this.#headBytes = keep;
+			} else if (this.#headClean && drop <= keep) {
+				// Walk code points to the first boundary at or after `drop` bytes.
+				let dropped = 0;
+				let index = 0;
+				while (dropped < drop) {
+					const code = head.charCodeAt(index);
+					if (code < 0x80) {
+						dropped += 1;
+						index += 1;
+					} else if (code < 0x800) {
+						dropped += 2;
+						index += 1;
+					} else if (code >= 0xd800 && code <= 0xdbff) {
+						// Well-formed, so a high surrogate always starts a pair.
+						dropped += 4;
+						index += 2;
+					} else {
+						dropped += 3;
+						index += 1;
+					}
+				}
+				this.#pending[0] = head.slice(index);
+				this.#headBytes -= dropped;
+			} else {
+				// A head that already fits comes back verbatim, lone surrogates included.
+				const { text, bytes } = truncateTailBytes(head, keep);
+				this.#pending[0] = text;
+				this.#headBytes = bytes;
+				this.#headClean = text.isWellFormed();
+				this.#pos = this.#headBytes + restBytes;
+				return;
+			}
+			this.#headClean = true;
+			this.#pos = this.#headBytes + restBytes;
+			return;
+		}
+
+		const { text, bytes } = truncateTailBytes(this.#flush(), max);
+		this.#setHead(text, bytes, text.isWellFormed());
 	}
 }