@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/tools/mcp.ts

@@ -88,30 +88,22 @@ function renderMarkdownMCPResult(
 	const markdown = new Markdown(trimmedOutput, 0, 0, getMarkdownTheme(), {
 		color: text => theme.fg("toolOutput", text),
 	});
+	// Args tree and output pane rows are spinner-invariant; rebuild only on
+	// expansion or width change instead of every animated frame.
+	let bodyMemo: { expanded: boolean; width: number; lines: readonly string[] } | undefined;
 	return plainToolCard(
 		theme,
 		({ contentWidth }) => {
 			const isError = result.isError ?? result.details?.isError ?? false;
 			const title = result.details ? `${result.details.serverName}/${result.details.mcpToolName}` : "MCP";
-			const body: string[] = [];
-			if (options.expanded && args && Object.keys(args).length > 0) {
-				body.push(...buildMcpArgsSection(args, theme));
+			if (bodyMemo === undefined || bodyMemo.expanded !== options.expanded || bodyMemo.width !== contentWidth) {
+				bodyMemo = {
+					expanded: options.expanded,
+					width: contentWidth,
+					lines: buildMarkdownMcpBody(markdown, truncationWarning, options.expanded, contentWidth, theme, args),
+				};
 			}
-
-			const rendered = markdown.render(Math.max(1, contentWidth));
-			body.push(
-				...formatOutputPaneLines(
-					{
-						lines: rendered,
-						expanded: options.expanded,
-						collapsedMaxLines: 4,
-						expandedMaxLines: 12,
-						showExpandHintWhenUncapped: true,
-					},
-					theme,
-				).lines,
-			);
-			if (truncationWarning) body.push(truncationWarning);
+			const body = bodyMemo.lines;
 			const status: StatusLineOptions = options.isPartial
 				? {
 						icon: options.spinnerFrame !== undefined ? "running" : "pending",
@@ -129,10 +121,47 @@ function renderMarkdownMCPResult(
 				applyBg: false,
 			};
 		},
-		{ paddingX: 0, paddingY: 0 },
+		{
+			paddingX: 0,
+			paddingY: 0,
+			onInvalidate: () => (bodyMemo = undefined),
+			onReleaseRenderCaches: () => {
+				bodyMemo = undefined;
+				markdown.releaseRenderCaches();
+			},
+		},
 	);
 }
 
+function buildMarkdownMcpBody(
+	markdown: Markdown,
+	truncationWarning: string | null,
+	expanded: boolean,
+	contentWidth: number,
+	theme: Theme,
+	args: Record<string, unknown> | undefined,
+): string[] {
+	const body: string[] = [];
+	if (expanded && args && Object.keys(args).length > 0) {
+		body.push(...buildMcpArgsSection(args, theme));
+	}
+	const rendered = markdown.render(Math.max(1, contentWidth));
+	body.push(
+		...formatOutputPaneLines(
+			{
+				lines: rendered,
+				expanded,
+				collapsedMaxLines: 4,
+				expandedMaxLines: 12,
+				showExpandHintWhenUncapped: true,
+			},
+			theme,
+		).lines,
+	);
+	if (truncationWarning) body.push(truncationWarning);
+	return body;
+}
+
 /**
  * Render MCP tool result.
  */
@@ -165,6 +194,8 @@ export function renderMCPResult(
 	if (trimmedOutput && renderMarkdownResults && !isJsonOutput) {
 		return renderMarkdownMCPResult(result, trimmedOutput, truncationWarning, options, theme, args);
 	}
+	// `expanded`, args and output are fixed for this card; only width varies the body.
+	let bodyMemo: { width: number; lines: readonly string[] } | undefined;
 	return plainToolCard(
 		theme,
 		({ contentWidth }) => {
@@ -180,61 +211,72 @@ export function renderMCPResult(
 					? { icon: "error", title }
 					: { iconOverride: theme.styledSymbol("tool.mcp", "accent"), title };
 			const phase: ToolCardPhase = options.isPartial ? "partial" : isError ? "error" : "success";
-			const body: string[] = [];
-
-			// Args section (when expanded)
-			if (expanded && args && typeof args === "object" && Object.keys(args).length > 0) {
-				body.push(...buildMcpArgsSection(args, theme));
+			if (bodyMemo === undefined || bodyMemo.width !== contentWidth) {
+				bodyMemo = { width: contentWidth, lines: buildMcpResultBody(contentWidth) };
 			}
+			return { status, phase, body: bodyMemo.lines, applyBg: false };
+		},
+		{
+			paddingX: 0,
+			paddingY: 0,
+			onInvalidate: () => (bodyMemo = undefined),
+			onReleaseRenderCaches: () => (bodyMemo = undefined),
+		},
+	);
 
-			// Output section. The body and spill metadata are normalized before
-			// component selection so the opt-in Markdown path can use its own renderer.
+	function buildMcpResultBody(contentWidth: number): string[] {
+		const body: string[] = [];
+		// Args section (when expanded)
+		if (expanded && args && typeof args === "object" && Object.keys(args).length > 0) {
+			body.push(...buildMcpArgsSection(args, theme));
+		}
 
-			if (!trimmedOutput) {
-				body.push(theme.fg("dim", "(no output)"));
-				return { status, phase, body, applyBg: false };
-			}
+		// Output section. The body and spill metadata are normalized before
+		// component selection so the opt-in Markdown path can use its own renderer.
 
-			// Preserve the existing structured JSON renderer regardless of the
-			// Markdown preference; JSON trees remain more useful than styled source.
-			if (isJsonOutput) {
-				const maxDepth = expanded ? JSON_TREE_MAX_DEPTH_EXPANDED : JSON_TREE_MAX_DEPTH_COLLAPSED;
-				const maxLines = expanded ? JSON_TREE_MAX_LINES_EXPANDED : JSON_TREE_MAX_LINES_COLLAPSED;
-				const maxScalarLen = expanded ? JSON_TREE_SCALAR_LEN_EXPANDED : JSON_TREE_SCALAR_LEN_COLLAPSED;
-				const tree = renderJsonTreeLines(parsedOutput, theme, maxDepth, maxLines, maxScalarLen);
-
-				if (tree.lines.length > 0) {
-					body.push(...tree.lines);
-					if (!expanded) {
-						body.push(formatExpandHint(theme, expanded, true));
-					} else if (tree.truncated) {
-						body.push(theme.fg("dim", "…"));
-					}
-					if (truncationWarning) body.push(truncationWarning);
-					return { status, phase, body, applyBg: false };
+		if (!trimmedOutput) {
+			body.push(theme.fg("dim", "(no output)"));
+			return body;
+		}
+
+		// Preserve the existing structured JSON renderer regardless of the
+		// Markdown preference; JSON trees remain more useful than styled source.
+		if (isJsonOutput) {
+			const maxDepth = expanded ? JSON_TREE_MAX_DEPTH_EXPANDED : JSON_TREE_MAX_DEPTH_COLLAPSED;
+			const maxLines = expanded ? JSON_TREE_MAX_LINES_EXPANDED : JSON_TREE_MAX_LINES_COLLAPSED;
+			const maxScalarLen = expanded ? JSON_TREE_SCALAR_LEN_EXPANDED : JSON_TREE_SCALAR_LEN_COLLAPSED;
+			const tree = renderJsonTreeLines(parsedOutput, theme, maxDepth, maxLines, maxScalarLen);
+
+			if (tree.lines.length > 0) {
+				body.push(...tree.lines);
+				if (!expanded) {
+					body.push(formatExpandHint(theme, expanded, true));
+				} else if (tree.truncated) {
+					body.push(theme.fg("dim", "…"));
 				}
+				if (truncationWarning) body.push(truncationWarning);
+				return body;
 			}
+		}
 
-			// Raw text output, capped to the first rows with an expand hint while collapsed.
-			body.push(
-				...formatOutputPaneLines(
-					{
-						lines: trimmedOutput.split("\n"),
-						expanded,
-						collapsedMaxLines: 4,
-						expandedMaxLines: 12,
-						styleLine: line => truncateToWidth(styleToolOutputLine(line, theme), contentWidth),
-						showExpandHintWhenUncapped: true,
-					},
-					theme,
-				).lines,
-			);
-
-			if (truncationWarning) body.push(truncationWarning);
-			return { status, phase, body, applyBg: false };
-		},
-		{ paddingX: 0, paddingY: 0 },
-	);
+		// Raw text output, capped to the first rows with an expand hint while collapsed.
+		body.push(
+			...formatOutputPaneLines(
+				{
+					lines: trimmedOutput.split("\n"),
+					expanded,
+					collapsedMaxLines: 4,
+					expandedMaxLines: 12,
+					styleLine: line => truncateToWidth(styleToolOutputLine(line, theme), contentWidth),
+					showExpandHintWhenUncapped: true,
+				},
+				theme,
+			).lines,
+		);
+
+		if (truncationWarning) body.push(truncationWarning);
+		return body;
+	}
 }
 
 /** Visible MCP argument entries (streaming/intent bookkeeping keys dropped). */
@@ -273,7 +315,8 @@ export function describeMCPResult(
 	_options: RenderResultOptions,
 	args?: Record<string, unknown>,
 ): NativeToolView | undefined {
-	return mcpResultMemo.get(result, [renderMarkdownResults, JSON.stringify(args ?? null)], () => {
+	// Callers allocate a fresh args object per streamed delta, so identity is a sound dep.
+	return mcpResultMemo.get(result, [renderMarkdownResults, args], () => {
 		const textContent = (result.content ?? [])
 			.filter(block => block.type === "text")
 			.map(block => block.text ?? "")

package/src/tools/native-view.d.ts

@@ -72,6 +72,53 @@ export declare function truncationNotice(meta: OutputMeta | undefined): NativeNo
  * truncation / artifact-capture notice from `meta`; undefined when empty.
  */
 export declare function footnoteText(parts: readonly string[], meta?: OutputMeta): NativeNode | undefined;
+/** Drawn lines of a run's input (command, cell code) before its "N more lines" button. */
+export declare const RUN_INPUT_PREVIEW_LINES = 6;
+/**
+ * What a run's foot names: `running` (live clock), `background` (an async job
+ * outlives the call), and the settled outcomes. A failure with an exit code
+ * reads `exit N`; without one, `Failed`.
+ */
+export type RunState = "running" | "background" | "done" | "failed" | "cancelled" | "timed-out";
+/** Inputs of {@link runFoot}. */
+export interface RunFootInput {
+    readonly state: RunState;
+    /** Exit code of a `failed` run; a non-zero code names the state `exit N`. */
+    readonly exitCode?: number;
+    /** Milliseconds run so far (`running`) or in total; the time is omitted when undefined. */
+    readonly elapsedMs?: number;
+    /** Quiet facts (job id, service state, artifact), muted and ` · `-joined. */
+    readonly facts?: readonly string[];
+    /** Truncation / artifact-capture notices, appended to the facts in `warning`. */
+    readonly meta?: OutputMeta;
+}
+/**
+ * The foot line of a run box (`zeta.run.foot`): the state word in its tone,
+ * the run time (a live clock while running, frozen once settled) and the
+ * quiet facts. Glyphs are the terminal's styling, never text.
+ */
+export declare function runFoot(input: RunFootInput): NativeNode;
+/** A run's input section: the command or cell source, clamped to {@link RUN_INPUT_PREVIEW_LINES}. */
+export declare function runInput(source: string, p: {
+    role: string;
+    lang: string;
+    wrap: boolean;
+}): NativeNode;
+/** A run's terminal output: follows its tail, clamped to the last `previewLines` lines while folded. */
+export declare function runOutput(output: string, p: {
+    role: string;
+    previewLines: number;
+    key?: string;
+}): NativeNode;
+/**
+ * One run as one box (`zeta.run`): input, output, status lines and foot in
+ * order. `tone` tints the box: `error` for a failed run, `warning` for a
+ * timed-out one.
+ */
+export declare function runBox(children: readonly (NativeChild | undefined | false)[], p: {
+    key: string;
+    tone?: TspTone;
+}): NativeNode;
 /** A diagnostic's severity glyph: `x-circle` error, `warn` warning, `info`, `lightbulb` hint, in the severity tone. */
 export declare function diagnosticGlyph(severity: ParsedDiagnostic["severity"]): NativeNode;
 /**

package/src/tools/native-view.ts

@@ -6,7 +6,7 @@
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { TspSpan, TspText, TspTone } from "@linxiraos/pi-wire";
-import { code, keyed, node, row, span, text } from "../native/describe";
+import { ansi, code, compact, keyed, node, row, span, text } from "../native/describe";
 import type { NativeChild, NativeNode } from "../native/node";
 import { type ParsedDiagnostic, parseDiagnosticMessage, shortenPath } from "../render/render-utils";
 import { plainText } from "../native/spans";
@@ -192,6 +192,107 @@ export function footnoteText(parts: readonly string[], meta?: OutputMeta): Nativ
 	};
 }
 
+/** Drawn lines of a run's input (command, cell code) before its "N more lines" button. */
+export const RUN_INPUT_PREVIEW_LINES = 6;
+
+/**
+ * What a run's foot names: `running` (live clock), `background` (an async job
+ * outlives the call), and the settled outcomes. A failure with an exit code
+ * reads `exit N`; without one, `Failed`.
+ */
+export type RunState = "running" | "background" | "done" | "failed" | "cancelled" | "timed-out";
+
+const RUN_STATE: Record<RunState, { readonly word: string; readonly tone: TspTone }> = {
+	running: { word: "Running", tone: "pending" },
+	background: { word: "In background", tone: "pending" },
+	done: { word: "Done", tone: "success" },
+	failed: { word: "Failed", tone: "error" },
+	cancelled: { word: "Cancelled", tone: "muted" },
+	"timed-out": { word: "Timed out", tone: "warning" },
+};
+
+/** Inputs of {@link runFoot}. */
+export interface RunFootInput {
+	readonly state: RunState;
+	/** Exit code of a `failed` run; a non-zero code names the state `exit N`. */
+	readonly exitCode?: number;
+	/** Milliseconds run so far (`running`) or in total; the time is omitted when undefined. */
+	readonly elapsedMs?: number;
+	/** Quiet facts (job id, service state, artifact), muted and ` · `-joined. */
+	readonly facts?: readonly string[];
+	/** Truncation / artifact-capture notices, appended to the facts in `warning`. */
+	readonly meta?: OutputMeta;
+}
+
+/**
+ * The foot line of a run box (`zeta.run.foot`): the state word in its tone,
+ * the run time (a live clock while running, frozen once settled) and the
+ * quiet facts. Glyphs are the terminal's styling, never text.
+ */
+export function runFoot(input: RunFootInput): NativeNode {
+	const failedWithCode = input.state === "failed" && input.exitCode !== undefined && input.exitCode !== 0;
+	const state = failedWithCode
+		? { word: `exit ${input.exitCode}`, tone: RUN_STATE.failed.tone }
+		: RUN_STATE[input.state];
+	const facts = (input.facts ?? []).map(fact => plainText(fact).trim()).filter(fact => fact.length > 0);
+	const notices: string[] = [];
+	if (input.meta?.truncation) notices.push(formatTruncationMetaNotice(input.meta.truncation, input.meta.source));
+	if (input.meta?.artifactError) notices.push(formatArtifactErrorNotice(input.meta.artifactError));
+	const factSpans: TspSpan[] = [];
+	if (facts.length > 0) factSpans.push(span(facts.join(" · "), "muted"));
+	for (const notice of notices) {
+		if (factSpans.length > 0) factSpans.push(span(" · ", "muted"));
+		factSpans.push(span(notice, "warning"));
+	}
+	const ms = input.elapsedMs === undefined ? undefined : Math.max(0, Math.round(input.elapsedMs));
+	const time =
+		ms === undefined
+			? undefined
+			: node(
+					"elapsed",
+					input.state === "running"
+						? { role: "zeta.run.time", age: ms, format: "short" }
+						: { role: "zeta.run.time", age: ms, stopped: ms, format: "short" },
+					undefined,
+					"time",
+				);
+	return node(
+		"row",
+		{ role: "zeta.run.foot", gap: "sm", align: "center" },
+		compact<NativeNode>([
+			keyed(text([span(state.word)], { role: "zeta.run.state", tone: state.tone }), "state"),
+			time,
+			factSpans.length > 0 && keyed(text(factSpans, { role: "zeta.run.facts", wrap: "word" }), "facts"),
+		]),
+		"foot",
+	);
+}
+
+/** A run's input section: the command or cell source, clamped to {@link RUN_INPUT_PREVIEW_LINES}. */
+export function runInput(source: string, p: { role: string; lang: string; wrap: boolean }): NativeNode {
+	return keyed(
+		code(source.trimEnd(), { role: p.role, lang: p.lang, wrap: p.wrap, preview: { lines: RUN_INPUT_PREVIEW_LINES } }),
+		"input",
+	);
+}
+
+/** A run's terminal output: follows its tail, clamped to the last `previewLines` lines while folded. */
+export function runOutput(output: string, p: { role: string; previewLines: number; key?: string }): NativeNode {
+	return keyed(ansi(output, { role: p.role, follow: true, preview: { lines: p.previewLines } }), p.key ?? "output");
+}
+
+/**
+ * One run as one box (`zeta.run`): input, output, status lines and foot in
+ * order. `tone` tints the box: `error` for a failed run, `warning` for a
+ * timed-out one.
+ */
+export function runBox(
+	children: readonly (NativeChild | undefined | false)[],
+	p: { key: string; tone?: TspTone },
+): NativeNode {
+	return node("col", { role: "zeta.run", gap: "none", tone: p.tone }, compact(children), p.key);
+}
+
 /** Diagnostic rows shown before `+N more`. */
 const DIAGNOSTIC_ROWS = 5;
 

package/src/tools/output-meta.d.ts

@@ -84,12 +84,22 @@ export interface LimitsMeta {
         reached: number;
         suggestion: number;
     };
-    /** `unit` may be absent in sessions persisted before it was recorded. */
+    /**
+     * `unit` may be absent in sessions persisted before it was recorded. `lines` is
+     * the first-to-last range of cut lines, and `selectorBase` the target a
+     * `:raw:<line>-<line>` selector reads one of them whole from (an artifact's
+     * `artifact://<id>` stands in when absent).
+     */
     columnTruncated?: {
         maxColumn: number;
         unit?: "bytes" | "chars";
         artifactId?: string;
         artifactElidedBytes?: number;
+        lines?: {
+            first: number;
+            last: number;
+        };
+        selectorBase?: string;
     };
 }
 /**

package/src/tools/output-meta.ts

@@ -63,8 +63,20 @@ export interface LimitsMeta {
 	/** `suggestion` is omitted when the tool is already at its hard cap, so no larger usable limit exists to advise. */
 	resultLimit?: { reached: number; suggestion?: number };
 	headLimit?: { reached: number; suggestion: number };
-	/** `unit` may be absent in sessions persisted before it was recorded. */
-	columnTruncated?: { maxColumn: number; unit?: "bytes" | "chars"; artifactId?: string; artifactElidedBytes?: number };
+	/**
+	 * `unit` may be absent in sessions persisted before it was recorded. `lines` is
+	 * the first-to-last range of cut lines, and `selectorBase` the target a
+	 * `:raw:<line>-<line>` selector reads one of them whole from (an artifact's
+	 * `artifact://<id>` stands in when absent).
+	 */
+	columnTruncated?: {
+		maxColumn: number;
+		unit?: "bytes" | "chars";
+		artifactId?: string;
+		artifactElidedBytes?: number;
+		lines?: { first: number; last: number };
+		selectorBase?: string;
+	};
 }
 
 /**
@@ -329,7 +341,15 @@ export function formatOutputNotice(meta: OutputMeta | undefined): string {
 		// a resumed legacy session renders "… 768 undefined" and stripOutputNotice
 		// stops matching the persisted "… 768 chars" text.
 		let columnNotice = `Some lines truncated to ${c.maxColumn} ${c.unit ?? "chars"}`;
-		if (c.artifactId != null) {
+		// An artifact cut to a head/tail sample renumbers its lines, so only a complete one names a line.
+		const selectorBase =
+			c.selectorBase ?? (c.artifactId != null && !c.artifactElidedBytes ? `artifact://${c.artifactId}` : undefined);
+		if (c.lines && selectorBase !== undefined) {
+			// One line per selector: a span of cut lines can exceed what one read returns.
+			const { first, last } = c.lines;
+			columnNotice += `. Use ${selectorBase}:raw:${first}-${first} to read line ${first} whole`;
+			if (last > first) columnNotice += `; cut lines run to line ${last}, each read the same way`;
+		} else if (c.artifactId != null) {
 			columnNotice += `. ${formatFullOutputReference(c.artifactId, c.artifactElidedBytes)}`;
 		}
 		parts.push(columnNotice);

package/src/tools/read.ts

@@ -600,6 +600,11 @@ export const readToolRenderer = {
 		let cachedWidth: number | undefined;
 		let cachedExpanded: boolean | undefined;
 		let cachedLines: string[] | undefined;
+		const dropCache = () => {
+			cachedWidth = undefined;
+			cachedExpanded = undefined;
+			cachedLines = undefined;
+		};
 		return markFramedBlockComponent({
 			render: (width: number) => {
 				const expanded = options.expanded;
@@ -634,11 +639,8 @@ export const readToolRenderer = {
 				cachedExpanded = expanded;
 				return cachedLines;
 			},
-			invalidate: () => {
-				cachedWidth = undefined;
-				cachedExpanded = undefined;
-				cachedLines = undefined;
-			},
+			invalidate: dropCache,
+			releaseRenderCaches: dropCache,
 		});
 	},
 	describeCall(args: ReadRenderArgs): NativeToolView {

package/src/tools/renderer.d.ts

@@ -25,6 +25,14 @@ export interface RenderResultOptions {
      * Streamed `xd://` previews stay queued until this is set.
      */
     executionStarted?: boolean;
+    /**
+     * Milliseconds since this call began executing (`tool_execution_start`),
+     * or its total once settled; undefined before it starts. Native describe
+     * hooks only.
+     */
+    elapsedMs?: number;
+    /** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
+    cancelled?: boolean;
 }
 /** Render options for a result, plus the tool-specific context the transcript threads through. */
 export type RenderResultContextOptions = RenderResultOptions & {
@@ -39,6 +47,18 @@ export interface ToolRenderResult<TDetails = unknown> {
     details?: TDetails;
     isError?: boolean;
 }
+/**
+ * A fence a tool call draws under its card, as assistant Markdown draws that
+ * fence. Any fence language may be named (`svg`, `mermaid`, `obj`); the
+ * transcript draws only those it draws as figures in assistant text.
+ */
+export interface ToolFigure {
+    readonly lang: string;
+    /** The body so far. */
+    readonly source: string;
+    /** No more of the body arrives. */
+    readonly closed: boolean;
+}
 /**
  * Per-renderer opt-in for a full viewport replay when the first result
  * replaces a painted pending-call render. A predicate receives the painted
@@ -73,6 +93,8 @@ export interface NativeToolHead {
     readonly targetKind?: TspToolProps["targetKind"];
     /** Language for `command` targets. */
     readonly lang?: string;
+    /** The raw command line the head's Copy command button copies (set implicitly by a `command` target). */
+    readonly command?: string;
     /** `file://` link for path targets. */
     readonly href?: string;
     /** Short facts after the target (`+8 −1`, `5 matches · 2 files`). */
@@ -99,10 +121,15 @@ export interface NativeToolView {
     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. */
+    /**
+     * Body clamp while collapsed; `{tail}` keeps the end (terminal output). Defaults to the transcript's preview size.
+     * `children`: the body stays whole while collapsed and its own `ansi`/`code` previews clamp instead.
+     */
     readonly preview?: TspPreview | {
         readonly tail: number;
-    } | "none";
+    } | "none" | "children";
+    /** Starts expanded whatever the transcript's expand state (the todo checklist); the user can still fold it. */
+    readonly open?: boolean;
     /** Render frameless (`frame:"inline"`): a head line plus a disclosed body. */
     readonly inline?: boolean;
     /** Head actions offered on hover (`copy`, `retry`). */
@@ -125,6 +152,14 @@ export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
     /** 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;
+    /**
+     * The fence a call draws under its card (a `.svg` being written, as its
+     * image): growing while the args stream, closed once they are final; none
+     * after an error. `result` is undefined until the call has one. Rendered
+     * TUI only, and only fences the terminal draws as figures; native views put
+     * their drawing in their describe hooks.
+     */
+    figure?(args: TArgs, result: ToolRenderResult<TDetails> | undefined, options: RenderResultOptions): ToolFigure | undefined;
     /** Describes current activity without coupling a renderer to terminal layout. */
     activitySummary?(args: TArgs, context: ToolActivityContext): ToolActivitySummary;
     /** Render without background box, inline in the response flow */

package/src/tools/renderer.ts

@@ -26,6 +26,14 @@ export interface RenderResultOptions {
 	 * Streamed `xd://` previews stay queued until this is set.
 	 */
 	executionStarted?: boolean;
+	/**
+	 * Milliseconds since this call began executing (`tool_execution_start`),
+	 * or its total once settled; undefined before it starts. Native describe
+	 * hooks only.
+	 */
+	elapsedMs?: number;
+	/** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
+	cancelled?: boolean;
 }
 
 /** Render options for a result, plus the tool-specific context the transcript threads through. */
@@ -38,6 +46,19 @@ export interface ToolRenderResult<TDetails = unknown> {
 	isError?: boolean;
 }
 
+/**
+ * A fence a tool call draws under its card, as assistant Markdown draws that
+ * fence. Any fence language may be named (`svg`, `mermaid`, `obj`); the
+ * transcript draws only those it draws as figures in assistant text.
+ */
+export interface ToolFigure {
+	readonly lang: string;
+	/** The body so far. */
+	readonly source: string;
+	/** No more of the body arrives. */
+	readonly closed: boolean;
+}
+
 /**
  * Per-renderer opt-in for a full viewport replay when the first result
  * replaces a painted pending-call render. A predicate receives the painted
@@ -77,6 +98,8 @@ export interface NativeToolHead {
 	readonly targetKind?: TspToolProps["targetKind"];
 	/** Language for `command` targets. */
 	readonly lang?: string;
+	/** The raw command line the head's Copy command button copies (set implicitly by a `command` target). */
+	readonly command?: string;
 	/** `file://` link for path targets. */
 	readonly href?: string;
 	/** Short facts after the target (`+8 −1`, `5 matches · 2 files`). */
@@ -104,8 +127,13 @@ export interface NativeToolView {
 	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";
+	/**
+	 * Body clamp while collapsed; `{tail}` keeps the end (terminal output). Defaults to the transcript's preview size.
+	 * `children`: the body stays whole while collapsed and its own `ansi`/`code` previews clamp instead.
+	 */
+	readonly preview?: TspPreview | { readonly tail: number } | "none" | "children";
+	/** Starts expanded whatever the transcript's expand state (the todo checklist); the user can still fold it. */
+	readonly open?: boolean;
 	/** Render frameless (`frame:"inline"`): a head line plus a disclosed body. */
 	readonly inline?: boolean;
 	/** Head actions offered on hover (`copy`, `retry`). */
@@ -138,6 +166,18 @@ export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
 		args?: TArgs,
 	): NativeToolView | undefined;
 	mergeCallAndResult?: boolean;
+	/**
+	 * The fence a call draws under its card (a `.svg` being written, as its
+	 * image): growing while the args stream, closed once they are final; none
+	 * after an error. `result` is undefined until the call has one. Rendered
+	 * TUI only, and only fences the terminal draws as figures; native views put
+	 * their drawing in their describe hooks.
+	 */
+	figure?(
+		args: TArgs,
+		result: ToolRenderResult<TDetails> | undefined,
+		options: RenderResultOptions,
+	): ToolFigure | undefined;
 	/** Describes current activity without coupling a renderer to terminal layout. */
 	activitySummary?(args: TArgs, context: ToolActivityContext): ToolActivitySummary;
 	/** Render without background box, inline in the response flow */