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

package/src/overlays/usage-row.ts

@@ -1,8 +1,11 @@
-import type { Usage } from "@oh-my-pi/pi-ai";
-import { Container, Spacer } from "../index";
+import type { AssistantMessage, Usage } from "@oh-my-pi/pi-ai";
+import { Container } from "../tui";
+import { Spacer } from "../components/spacer";
 import { formatDuration, formatNumber } from "@oh-my-pi/pi-utils";
 import { theme } from "../theme/theme";
 import { formatMetricRow, MetricRow, type MetricSpec } from "../components/metric";
+import { node, row, span, text } from "../native/describe";
+import type { NativeChild, NativeNode } from "../native/node";
 
 /** Below this the rate is nonsense (cached/instant responses yield absurd tok/s). */
 const MIN_DURATION_MS = 100;
@@ -32,13 +35,84 @@ export function turnElapsedMs(
 	return elapsed > 0 ? Math.round(elapsed) : undefined;
 }
 
-function usageRowSpecs(
-	usage: Usage,
-	durationMs?: number,
-	ttftMs?: number,
-	timestamp?: number,
-	turnElapsedMs?: number,
-): MetricSpec[] {
+/** A finished turn's totals, the native `omp.turn.usage` line under its last answer. */
+export interface TurnUsageSummary {
+	/** Prompt→yield wall time; undefined when either end is unknown. */
+	readonly elapsedMs: number | undefined;
+	/**
+	 * Prompt tokens: input, cache writes and orchestration input. Cache reads
+	 * re-read the context each request, so they stay out (as in the status
+	 * line's total).
+	 */
+	readonly input: number;
+	/** Output tokens, orchestration output included. */
+	readonly output: number;
+	/** Billed cost in dollars. */
+	readonly cost: number;
+}
+
+/**
+ * Sums the requests of a turn. {@link add} returns the turn's summary on the
+ * message that ends the run (any stop but `toolUse`) and starts over.
+ */
+export class TurnUsageTally {
+	#input = 0;
+	#output = 0;
+	#cost = 0;
+
+	/** Drop a partial turn (a new prompt, a fresh run). */
+	reset(): void {
+		this.#input = 0;
+		this.#output = 0;
+		this.#cost = 0;
+	}
+
+	add(message: AssistantMessage, turnStartedAt: number | undefined): TurnUsageSummary | undefined {
+		const { usage } = message;
+		this.#input += usage.input + usage.cacheWrite + (usage.orchestration?.input ?? 0);
+		this.#output += usage.output + (usage.orchestration?.output ?? 0);
+		this.#cost += usage.cost.total;
+		if (message.stopReason === "toolUse") return undefined;
+		const summary =
+			this.#input + this.#output > 0 || this.#cost > 0
+				? {
+						elapsedMs: turnElapsedMs(turnStartedAt, message),
+						input: this.#input,
+						output: this.#output,
+						cost: this.#cost,
+					}
+				: undefined;
+		this.reset();
+		return summary;
+	}
+}
+
+/**
+ * The native turn line: `12.4s · 19K tok · $0.02 this turn` (the time drops
+ * out when unknown, the cost when nothing was billed), and its tooltip with
+ * exact counts.
+ */
+export function formatTurnUsage(summary: TurnUsageSummary): { text: string; title: string } {
+	const tokens = summary.input + summary.output;
+	const cost = summary.cost > 0 ? (summary.cost < 0.005 ? "<$0.01" : `$${summary.cost.toFixed(2)}`) : undefined;
+	const time = summary.elapsedMs === undefined ? undefined : formatDuration(summary.elapsedMs);
+	const text = [time, `${formatNumber(tokens)} tok`, cost].filter(part => part !== undefined).join(" · ");
+	const exact = `${tokens.toLocaleString("en-US")} tokens (${summary.input.toLocaleString("en-US")} in · ${summary.output.toLocaleString("en-US")} out)`;
+	const title = [time, exact, cost].filter(part => part !== undefined).join(" · ");
+	return { text: `${text} this turn`, title: `This turn: ${title}` };
+}
+
+/** Output tokens per second over the whole request; undefined when the duration is too short to mean anything. */
+function usageThroughput(usage: Usage, durationMs: number | undefined): number | undefined {
+	if (!durationMs || durationMs <= MIN_DURATION_MS || usage.output <= 0) return undefined;
+	// TPS over the total request duration — the post-TTFT window undercounts
+	// generation time when reasoning tokens are hidden before the first
+	// visible byte, inflating the rate.
+	return (usage.output / durationMs) * 1000;
+}
+
+/** Every metric except throughput, which the native row declares as a `rate`. */
+function usageRowBaseSpecs(usage: Usage, ttftMs?: number, timestamp?: number, turnElapsedMs?: number): MetricSpec[] {
 	const totalInput = usage.input + usage.cacheWrite;
 	const specs: MetricSpec[] = [];
 	// Lead with the turn's local wall-clock time (down to the second), log-line style.
@@ -61,16 +135,88 @@ function usageRowSpecs(
 	if (ttftMs && ttftMs > 0) {
 		specs.push({ leading: theme.icon.time, value: `${(ttftMs / 1000).toFixed(1)}s` });
 	}
-	if (durationMs && durationMs > MIN_DURATION_MS && usage.output > 0) {
-		// TPS over the total request duration — the post-TTFT window undercounts
-		// generation time when reasoning tokens are hidden before the first
-		// visible byte, inflating the rate.
-		const tokPerSec = (usage.output / durationMs) * 1000;
+	return specs;
+}
+
+function usageRowSpecs(
+	usage: Usage,
+	durationMs?: number,
+	ttftMs?: number,
+	timestamp?: number,
+	turnElapsedMs?: number,
+): MetricSpec[] {
+	const specs = usageRowBaseSpecs(usage, ttftMs, timestamp, turnElapsedMs);
+	const tokPerSec = usageThroughput(usage, durationMs);
+	if (tokPerSec !== undefined) {
 		specs.push({ leading: theme.icon.throughput, value: `${tokPerSec.toFixed(1)}/s` });
 	}
 	return specs;
 }
 
+/** Per-turn usage block: a dim metric strip under the turn; natively a wrapping row with a `rate` for throughput. */
+class UsageRowBlock extends Container {
+	readonly #usage: Usage;
+	readonly #durationMs: number | undefined;
+	readonly #ttftMs: number | undefined;
+	readonly #timestamp: number | undefined;
+	readonly #turnElapsedMs: number | undefined;
+	#nativeNode: NativeNode | undefined;
+
+	constructor(usage: Usage, durationMs?: number, ttftMs?: number, timestamp?: number, turnElapsedMs?: number) {
+		super();
+		this.#usage = usage;
+		this.#durationMs = durationMs;
+		this.#ttftMs = ttftMs;
+		this.#timestamp = timestamp;
+		this.#turnElapsedMs = turnElapsedMs;
+		this.addChild(new Spacer(1));
+		this.addChild(
+			new MetricRow(usageRowSpecs(usage, durationMs, ttftMs, timestamp, turnElapsedMs), {
+				separator: "  ",
+				overflow: "wrap",
+				paddingX: 1,
+				paddingY: 0,
+				style: text => theme.fg("dim", text),
+			}),
+		);
+	}
+
+	/**
+	 * One quiet mono line (`18:02 · Δ 6.2s · in 18.4K · out 640 · cache 12K ·
+	 * ttft 0.9s · 96 tok/s`): worded metrics instead of the ANSI icons, the
+	 * full timestamp in the tooltip, and throughput as a `rate`.
+	 */
+	override describe(): NativeNode {
+		if (this.#nativeNode) return this.#nativeNode;
+		const usage = this.#usage;
+		const parts: string[] = [];
+		const timestamp = this.#timestamp;
+		const stamped = timestamp !== undefined && Number.isFinite(timestamp) && timestamp > 0;
+		if (stamped) parts.push(formatUsageTimestamp(timestamp).slice(11, 16));
+		if (this.#turnElapsedMs !== undefined && this.#turnElapsedMs > 0) {
+			parts.push(`Δ ${formatDuration(Math.round(this.#turnElapsedMs))}`);
+		}
+		parts.push(`in ${formatNumber(usage.input + usage.cacheWrite)}`, `out ${formatNumber(usage.output)}`);
+		if (usage.cacheRead > 0) parts.push(`cache ${formatNumber(usage.cacheRead)}`);
+		if (this.#ttftMs && this.#ttftMs > 0) parts.push(`ttft ${(this.#ttftMs / 1000).toFixed(1)}s`);
+		const children: NativeChild[] = [text([span(parts.join(" · "), "dim")])];
+		const tokPerSec = usageThroughput(usage, this.#durationMs);
+		if (tokPerSec !== undefined) {
+			children.push(
+				text([span(" · ", "dim")]),
+				node("rate", { value: Math.round(tokPerSec * 10) / 10, unit: "tok/s" }),
+			);
+		}
+		this.#nativeNode = row(children, {
+			role: "omp.usage.turn",
+			gap: "none",
+			align: "baseline",
+			...(stamped ? { title: formatUsageTimestamp(timestamp) } : {}),
+		});
+		return this.#nativeNode;
+	}
+}
+
 /** Format the metrics shared by standalone usage blocks and compact tool groups. */
 export function formatUsageRow(
 	usage: Usage,
@@ -102,17 +248,7 @@ export function createUsageRowBlock(
 	timestamp?: number,
 	turnElapsedMs?: number,
 ): Container {
-	const block = new Container();
-	block.addChild(new Spacer(1));
-	block.addChild(
-		new MetricRow(usageRowSpecs(usage, durationMs, ttftMs, timestamp, turnElapsedMs), {
-			separator: "  ",
-			overflow: "wrap",
-			paddingX: 1,
-			paddingY: 0,
-			style: text => theme.fg("dim", text),
-		}),
-	);
+	const block = new UsageRowBlock(usage, durationMs, ttftMs, timestamp, turnElapsedMs);
 	usageRowBlocks.add(block);
 	return block;
 }

package/src/prompt/attachment-chips.ts

@@ -12,6 +12,10 @@ import {
 	visibleWidth,
 } from "../index";
 import { fileHyperlink } from "../render/hyperlink";
+import { registerNativeBlob } from "../native/blobs";
+import { node, row, span } from "../native/describe";
+import { plainText } from "../native/spans";
+import type { DescribeContext, NativeNode } from "../native/node";
 import { convertImageToPng } from "../chat/image-loading";
 import { attachmentSgr } from "./composer-attachments";
 import { cachedImageDimensions, setCachedImageDimensions } from "./image-references";
@@ -29,9 +33,12 @@ const RESET_FG = "\x1b[39m";
  *  (pastes are usually re-encoded JPEG/WebP) convert before transmit — the same pipeline
  *  the transcript uses. `null` = conversion in flight or failed. */
 const kImagePng = Symbol("omp.imagePng");
+/** Content address of the draft image's decoded bytes, registered once for TSP `image` nodes. */
+const kImageBlob = Symbol("omp.imageBlob");
 
 interface ImageContentWithPng extends ImageContent {
 	[kImagePng]?: ImageContent | null;
+	[kImageBlob]?: string;
 }
 
 /**
@@ -50,6 +57,59 @@ export class AttachmentChipsBand implements Component {
 		private readonly requestRender: () => void,
 	) {}
 
+	#native: { chips: readonly ComposerChipDescriptor[]; node: NativeNode } | undefined;
+
+	/**
+	 * A wrapping `row` of chip `card`s (`omp.composer.chip`) titled with the
+	 * buffer token (`<icon> #N`): images and videos show the image itself,
+	 * pastes their leading lines; the caption carries pixel size or line/char
+	 * count. Hidden while nothing is staged.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const chips = this.editor.composerChips();
+		if (this.#native?.chips === chips) return this.#native.node;
+		const cards: NativeNode[] = [];
+		for (const chip of chips) {
+			const icon = theme.symbol(
+				chip.kind === "paste" ? "chip.paste" : chip.kind === "video" ? "chip.video" : "chip.image",
+			);
+			const title = `${icon} #${chip.n}`;
+			let content: NativeNode;
+			let caption: string;
+			if (chip.kind === "paste") {
+				caption = chip.text.lineCount > 1 ? `+${chip.text.lineCount} lines` : `${chip.text.charCount} chars`;
+				content = node("text", {
+					spans: [span(plainText(chip.text.content.split("\n", 4).join("\n")), "muted")],
+					wrap: "none",
+					lines: 4,
+				});
+			} else {
+				const dims = this.#imageDims(chip.image);
+				caption = dims ? `${dims.width}x${dims.height}` : "";
+				const image = chip.image as ImageContentWithPng;
+				const blob = image[kImageBlob] ?? registerNativeBlob(Buffer.from(image.data, "base64"), image.mimeType);
+				image[kImageBlob] = blob;
+				content = node("image", {
+					blob,
+					alt: title,
+					w: dims?.width,
+					h: dims?.height,
+					max: { w: "12ch", h: "4lines" },
+				});
+			}
+			const head =
+				chip.kind !== "paste" && chip.link ? [span(title, "strong", { href: chip.link })] : [span(title, "strong")];
+			const children: NativeNode[] = [content];
+			if (caption) children.push(node("text", { spans: [span(caption, "dim")], wrap: "none" }));
+			cards.push(
+				node("card", { role: "omp.composer.chip", tone: "accent", head }, children, `${chip.kind}:${chip.n}`),
+			);
+		}
+		const described = row(cards, { gap: "sm", wrap: true, role: "omp.composer.chips", hidden: cards.length === 0 });
+		this.#native = { chips, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		const chips = this.editor.composerChips();
 		if (chips.length === 0) return [];

package/src/prompt/composer-attachments.ts

@@ -47,8 +47,10 @@ export function modelChipStyle(label: string, restore = "\x1b[39m\x1b[49m"): str
 /** Every glyph a skill chip may start with, across all symbol presets. */
 const SKILL_ICONS = [...new Set(Object.values(SYMBOL_PRESETS).map(m => m["icon.extensionSkill"]))];
 
-/** Skill names as they appear in chips: word characters and dashes, dots only between segments. */
-const SKILL_NAME_SOURCE = "[\\w-]+(?:\\.[\\w-]+)*";
+/** Skill names as they appear in chips: word characters and dashes, dots only between segments,
+ *  optionally behind one collision namespace (`<namespace>/<name>`). */
+const SKILL_NAME_SEGMENT_SOURCE = "[\\w-]+(?:\\.[\\w-]+)*";
+const SKILL_NAME_SOURCE = `${SKILL_NAME_SEGMENT_SOURCE}(?:/${SKILL_NAME_SEGMENT_SOURCE})?`;
 
 /** Regex source for a chip glyph; word glyphs (ASCII preset) must not continue a preceding word. */
 function glyphSource(icon: string): string {
@@ -214,12 +216,26 @@ export function composerTokenRegex(mentionLabels: Iterable<string>): RegExp {
 
 const VISION_MARKER_REGEX = /\[(Image|Video) #([1-9]\d*)((?:,[^\]\n]*)?)\](?: attachment:\/\/(\2))?/g;
 
-/** Offsets image marker indices, including matching `attachment://` references. */
-export function shiftImageMarkers(text: string, offset: number): string {
-	if (offset === 0) return text;
+/** Marker for the Nth attached image or video preview: `[Image #N, WxH]`, or `[Image #N]` without dims. */
+export function formatVisionMarker(
+	kind: "image" | "video",
+	n: number,
+	dims?: { width: number; height: number },
+): string {
+	const label = `${kind === "video" ? "Video" : "Image"} #${n}`;
+	return dims ? `[${label}, ${dims.width}x${dims.height}]` : `[${label}]`;
+}
+
+/**
+ * Offsets image marker indices, including matching `attachment://` references. With `imageCount`,
+ * markers above it are left alone: like `compactImageMarkers`, they are not this text's attachments.
+ */
+export function shiftImageMarkers(text: string, offset: number, imageCount?: number): string {
+	if (offset === 0 || imageCount === 0) return text;
 	return text.replace(
 		VISION_MARKER_REGEX,
-		(_match, kind: string, idx: string, tail: string, attachmentIdx: string | undefined) => {
+		(match, kind: string, idx: string, tail: string, attachmentIdx: string | undefined) => {
+			if (imageCount !== undefined && Number(idx) > imageCount) return match;
 			const marker = `[${kind} #${Number(idx) + offset}${tail}]`;
 			return attachmentIdx === undefined ? marker : `${marker} attachment://${Number(attachmentIdx) + offset}`;
 		},
@@ -249,8 +265,14 @@ export function collapseImageMarkers(
 /**
  * Drops unreferenced vision attachments from a submission and densely remaps
  * retained image/video markers. Returns `null` when no compaction is needed.
+ * With `byAppearance`, retained markers are also renumbered in the order they first
+ * appear, for editors whose images attach out of order (concurrent path loads).
  */
-export function compactImageMarkers(text: string, imageCount: number): { text: string; keep: number[] } | null {
+export function compactImageMarkers(
+	text: string,
+	imageCount: number,
+	options?: { byAppearance?: boolean },
+): { text: string; keep: number[] } | null {
 	if (imageCount === 0) return null;
 	const referenced = new Set<number>();
 	const scanner = new RegExp(VISION_MARKER_REGEX.source, "g");
@@ -260,8 +282,8 @@ export function compactImageMarkers(text: string, imageCount: number): { text: s
 		const n = Number(match[2]);
 		if (n <= imageCount) referenced.add(n);
 	}
-	if (referenced.size === imageCount) return null;
-	const keep = [...referenced].sort((a, b) => a - b);
+	const keep = options?.byAppearance ? [...referenced] : [...referenced].sort((a, b) => a - b);
+	if (keep.length === imageCount && keep.every((n, i) => n === i + 1)) return null;
 	const remap = new Map<number, number>(keep.map((n, i) => [n, i + 1]));
 	const rewritten = text.replace(
 		VISION_MARKER_REGEX,

package/src/prompt/composer.ts

@@ -16,6 +16,8 @@ import {
 	type ViewportSize,
 } from "../tui";
 import { sliceWithWidth, visibleWidth } from "../utils";
+import type { NativeChild, NativeSurface, NativeSurfaceProvider } from "../native/node";
+import { sameItems } from "../native/memo";
 import { postmortem } from "@oh-my-pi/pi-utils";
 import { CustomEditor } from "./custom-editor";
 import type { WordCompletionMethod } from "./word-completion";
@@ -99,6 +101,13 @@ export interface RuntimeChildrenOptions {
 	 * settled rows it displaces retire to native scrollback.
 	 */
 	readonly transient?: readonly Component[];
+	/**
+	 * Dock order on a TSP terminal (no status strip; the composer carries its
+	 * facts): the native dock stacks HUD pills, the working row and queued messages over
+	 * the composer in its own order, and may add describe-only roots. Defaults
+	 * to the roots below the transcript in render order.
+	 */
+	readonly nativeDock?: readonly Component[];
 }
 
 /** Controls the first terminal paint for a composer that does not already own the terminal. */
@@ -114,7 +123,11 @@ export interface ComposerStartOptions {
 	readonly deferInput?: boolean;
 }
 
-/** Mount slot below the editor: the startup status line, then the session-aware one. */
+/**
+ * Mount slot below the editor: the startup status line, then the session-aware
+ * one. ANSI only: a TSP terminal has no status strip, the composer carries the
+ * status line's facts ({@link StatusLineComponent.describeComposerFacts}).
+ */
 class StatusHost implements Component {
 	#component: Component | undefined;
 
@@ -189,7 +202,7 @@ function rowTargetCandidates(target: Component): ((local: number) => string[]) |
  * It owns the terminal, welcome header, and editor; InteractiveMode later supplies authoritative
  * data and mounts the session-aware runtime children without replacing the visible header.
  */
-export class Composer implements TerminalFrameProvider {
+export class Composer implements TerminalFrameProvider, NativeSurfaceProvider {
 	readonly ui: TUI;
 	#editor: CustomEditor;
 	readonly #header = new Container();
@@ -207,6 +220,7 @@ export class Composer implements TerminalFrameProvider {
 	#headerBefore: readonly Component[] = [];
 	#headerAfter: readonly Component[] = [];
 	#runtimeChildren: readonly Component[] = [];
+	#nativeDock: readonly Component[] | undefined;
 	/** Cache-driven status line shown until {@link setStatusComponent} mounts the session's. */
 	#startupStatus: StatusLineComponent | undefined;
 	#runtimeMounted = false;
@@ -263,6 +277,8 @@ export class Composer implements TerminalFrameProvider {
 	#transientChrome: ReadonlySet<Component> = new Set();
 	#transientChromeFloor: number | undefined;
 	#lastInterruptAt = 0;
+	/** Last described surface; its arrays are reused while their children are unchanged. */
+	#nativeSurface: NativeSurface = { main: [], dock: [] };
 	#started = false;
 	#stopped = false;
 	#transferred = false;
@@ -415,6 +431,41 @@ export class Composer implements TerminalFrameProvider {
 		return { history, viewport: this.#paintHoverBand(mutable, spans) };
 	}
 
+	/**
+	 * Describe the whole surface for a TSP terminal. `main` is the flowing
+	 * document: the header (welcome, extras) and every transcript block as its
+	 * own component child. `dock` is the live chrome below the transcript in
+	 * render order: pending messages, HUDs, the working row, the editor and the
+	 * status line. There is no history/viewport split: retirement, resize
+	 * replay and hover bands are ANSI concerns.
+	 */
+	describeSurface(): NativeSurface {
+		if (!this.#started || this.#stopped) return this.#nativeSurface;
+		const main: NativeChild[] = [...this.#header.children];
+		const dock: NativeChild[] = [];
+		if (!this.#runtimeMounted) {
+			// The bootstrap gap is row spacing; the terminal owns the dock layout.
+			dock.push(this.editor);
+		} else {
+			const roots = this.#runtimeChildren;
+			const transcriptIndex = roots.findIndex(root => root instanceof TranscriptContainer);
+			if (transcriptIndex < 0) {
+				dock.push(...roots);
+			} else {
+				const transcript = roots[transcriptIndex] as TranscriptContainer;
+				main.push(...roots.slice(0, transcriptIndex), ...transcript.nativeBlocks());
+				dock.push(...(this.#nativeDock ?? roots.slice(transcriptIndex + 1)));
+			}
+		}
+		const previous = this.#nativeSurface;
+		const nextMain = sameItems(previous.main, main) ? previous.main : main;
+		const nextDock = sameItems(previous.dock, dock) ? previous.dock : dock;
+		if (nextMain !== previous.main || nextDock !== previous.dock) {
+			this.#nativeSurface = { main: nextMain, dock: nextDock };
+		}
+		return this.#nativeSurface;
+	}
+
 	/**
 	 * Append one below-transcript root's rows to `after`, recording click spans
 	 * for its row targets in `after` coordinates.
@@ -837,6 +888,7 @@ export class Composer implements TerminalFrameProvider {
 		this.#disposeStartupStatus();
 		this.#statusHost.setComponent(component);
 		this.editor.setTopBorderProvider(undefined);
+		this.editor.composerFacts = component;
 	}
 
 	#disposeStartupStatus(): void {
@@ -849,6 +901,7 @@ export class Composer implements TerminalFrameProvider {
 		if (this.#stopped) return;
 		this.#transientChrome = new Set(options.transient);
 		this.#transientChromeFloor = undefined;
+		this.#nativeDock = options.nativeDock;
 		this.ui.removeChild(this.#statusHost);
 		if (this.#runtimeMounted) {
 			for (const child of this.#runtimeChildren) this.ui.removeChild(child);