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

package/src/tools/bash.ts

@@ -18,7 +18,16 @@ import {
 	stripRawOutputArtifactNotice,
 	stripTrailingNotice,
 } from "./output-meta";
-import type { RenderResultOptions, ToolRenderer } from "./renderer";
+import type {
+	NativeToolHead,
+	NativeToolView,
+	RenderResultContextOptions,
+	RenderResultOptions,
+	ToolRenderer,
+} from "./renderer";
+import { ansi, compact, keyed } from "../native/describe";
+import type { NativeChild } from "../native/node";
+import { footnoteText, resultText } from "./native-view";
 
 /** Default collapsed shell output preview height. */
 export const BASH_DEFAULT_PREVIEW_LINES = DEFAULT_TERMINAL_PREVIEW_LINES;
@@ -130,19 +139,51 @@ function unescapePartialJsonString(value: string): string {
 	return output;
 }
 
-function extractPartialBashEnv(partialJson: string | undefined): Record<string, string> | undefined {
+// One-slot memo: every render path over one streamed args object (call
+// preview, result header, repaint) asks for the same buffer.
+let lastPartialEnvJson: string | undefined;
+let lastPartialEnv: Readonly<Record<string, string>> | undefined;
+
+function extractPartialBashEnv(partialJson: string | undefined): Readonly<Record<string, string>> | undefined {
 	if (!partialJson) return undefined;
+	if (partialJson === lastPartialEnvJson) return lastPartialEnv;
+	let env: Record<string, string> | undefined;
 	const envStart = partialJson.search(/"env"\s*:\s*\{/u);
-	if (envStart === -1) return undefined;
-	const objectStart = partialJson.indexOf("{", envStart);
-	if (objectStart === -1) return undefined;
-	const envBody = partialJson.slice(objectStart + 1);
-	const env: Record<string, string> = {};
-	const matcher = /"([A-Za-z_][A-Za-z0-9_]*)"\s*:\s*"((?:\\.|[^"\\])*)(?:"|$)/gu;
-	for (const match of envBody.matchAll(matcher)) {
-		env[match[1]!] = unescapePartialJsonString(match[2]!);
+	const objectStart = envStart === -1 ? -1 : partialJson.indexOf("{", envStart);
+	if (objectStart !== -1) {
+		// Scan only the env object: stop at its closing brace (outside strings)
+		// so the keys that follow it are not read as env assignments.
+		let objectEnd = partialJson.length;
+		let depth = 0;
+		for (let i = objectStart + 1; i < partialJson.length; i++) {
+			const ch = partialJson.charCodeAt(i);
+			if (ch === 0x22) {
+				// Skip the string body, honoring escapes; an unterminated string runs to the end.
+				for (i++; i < partialJson.length; i++) {
+					const inner = partialJson.charCodeAt(i);
+					if (inner === 0x5c) i++;
+					else if (inner === 0x22) break;
+				}
+			} else if (ch === 0x7b || ch === 0x5b) {
+				depth++;
+			} else if (ch === 0x7d || ch === 0x5d) {
+				if (depth === 0) {
+					objectEnd = i;
+					break;
+				}
+				depth--;
+			}
+		}
+		const envBody = partialJson.slice(objectStart + 1, objectEnd);
+		const matcher = /"([A-Za-z_][A-Za-z0-9_]*)"\s*:\s*"((?:\\.|[^"\\])*)(?:"|$)/gu;
+		for (const match of envBody.matchAll(matcher)) {
+			env ??= {};
+			env[match[1]!] = unescapePartialJsonString(match[2]!);
+		}
 	}
-	return Object.keys(env).length > 0 ? env : undefined;
+	lastPartialEnvJson = partialJson;
+	lastPartialEnv = env ? Object.freeze(env) : undefined;
+	return lastPartialEnv;
 }
 
 function formatWallTimeSeconds(wallTimeMs: number): string {
@@ -229,6 +270,122 @@ export function formatBashCommandLines(args: BashRenderArgs, uiTheme: Theme): st
 	return highlightedLines.map((line, i) => (i === 0 ? `${prefix}${line}` : line));
 }
 
+/**
+ * Plain (unstyled) command line for native views: `cd <dir> && NAME="…" <command>`,
+ * built from the same decoded display args (incl. streamed `__partialJson` env) as the ANSI path.
+ */
+export function formatBashCommandText(args: BashRenderArgs): string {
+	const displayWorkdir = formatToolWorkingDirectory(args.cwd, getProjectDir());
+	const envAssignments = formatBashEnvAssignments(getBashEnvForDisplay(args));
+	const parts: string[] = [];
+	if (displayWorkdir) parts.push(`cd ${displayWorkdir} &&`);
+	if (envAssignments) parts.push(envAssignments);
+	parts.push(args.command || "…");
+	return parts.join(" ");
+}
+
+/** Bash output with the LLM-facing notices (background, exit, wall time, artifact, truncation) removed. */
+function stripBashNotices(
+	rawOutput: string,
+	details: BashToolDetails | undefined,
+): { text: string; artifactId?: string } {
+	const withoutBackground =
+		details?.async?.state === "running"
+			? stripTrailingNotice(rawOutput, formatBackgroundNotice(details.async.jobId))
+			: rawOutput;
+	const strippedOutput = stripOutputNotice(withoutBackground, details?.meta);
+	const withoutExit =
+		details?.exitCode === undefined
+			? strippedOutput
+			: stripTrailingNotice(strippedOutput, formatExitCodeNotice(details.exitCode));
+	const withoutWall =
+		details?.wallTimeMs === undefined
+			? withoutExit
+			: stripTrailingNotice(withoutExit, formatWallTimeNotice(details.wallTimeMs));
+	return stripRawOutputArtifactNotice(withoutWall);
+}
+/** `Wall: 1.20s`, `Timeout: 30s`, … metadata parts shown under bash output. */
+function bashStatsParts(
+	details: BashToolDetails | undefined,
+	contextTimeout: number | undefined,
+	artifactId: string | undefined,
+	isError: boolean,
+): string[] {
+	const timeoutDisabled = details?.timeoutDisabled === true || contextTimeout === 0;
+	const timeoutSeconds = timeoutDisabled ? undefined : (details?.timeoutSeconds ?? contextTimeout);
+	const requestedTimeoutSeconds = details?.requestedTimeoutSeconds;
+	const wallTimeMs = details?.wallTimeMs;
+	const statsParts: string[] = [];
+	if (details?.async?.state === "running") {
+		statsParts.push(`Backgrounded: ${details.async.jobId}`);
+	}
+	if (details?.service) {
+		const service = details.service;
+		statsParts.push(`Service: ${service.name}`, `State: ${service.state}`);
+		statsParts.push(`Ready: ${service.ready ? "yes" : service.timedOut ? "timed out" : "no"}`);
+		if (service.pid !== undefined) statsParts.push(`PID: ${service.pid}`);
+	}
+	if (wallTimeMs !== undefined) {
+		statsParts.push(`Wall: ${formatWallTimeSeconds(wallTimeMs)}s`);
+	}
+	if (timeoutDisabled) {
+		statsParts.push("Timeout: disabled");
+	}
+	if (typeof timeoutSeconds === "number") {
+		statsParts.push(
+			requestedTimeoutSeconds !== undefined && requestedTimeoutSeconds !== timeoutSeconds
+				? `Timeout: ${timeoutSeconds}s (requested ${requestedTimeoutSeconds}s clamped)`
+				: `Timeout: ${timeoutSeconds}s`,
+		);
+	}
+	if (artifactId) {
+		statsParts.push(`Artifact: ${artifactId}`);
+	}
+	if (isError && typeof details?.exitCode === "number") {
+		statsParts.push(`Exit: ${details.exitCode}`);
+	}
+	return statsParts;
+}
+
+/**
+ * Native head facts of a shell call: title, the command once (`cd`/env
+ * prefix included), a `background` badge for a backgrounded job, the
+ * `exit N` chip and a `timed out` note only when the deadline hit.
+ */
+function shellToolHead(
+	title: string,
+	command: string,
+	details: BashToolDetails | undefined,
+	settled: boolean,
+): NativeToolHead {
+	const exit = settled && details?.exitCode !== undefined && details.exitCode !== 0 ? details.exitCode : undefined;
+	return {
+		title,
+		target: command,
+		targetKind: "command",
+		lang: "bash",
+		badges:
+			details?.async?.state === "running"
+				? [{ text: "background", title: `Backgrounded as job ${details.async.jobId}` }]
+				: undefined,
+		exit,
+		note: settled && details?.timedOut === true ? "timed out" : undefined,
+	};
+}
+
+/** The quiet final line's facts under shell output: service state and the full-output artifact. */
+function shellFootParts(details: BashToolDetails | undefined, artifactId: string | undefined): string[] {
+	const parts: string[] = [];
+	const service = details?.service;
+	if (service) {
+		parts.push(`Service ${service.name}`, service.state);
+		parts.push(service.ready ? "ready" : service.timedOut ? "ready timed out" : "not ready");
+		if (service.pid !== undefined) parts.push(`PID ${service.pid}`);
+	}
+	if (artifactId) parts.push(`Artifact ${artifactId}`);
+	return parts;
+}
+
 function toBashRenderArgs<TArgs>(args: TArgs | undefined, config: ShellRendererConfig<TArgs>): BashRenderArgs {
 	return {
 		command: config.resolveCommand?.(args),
@@ -243,8 +400,12 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 	return {
 		renderCall(args: TArgs, options: RenderResultOptions, uiTheme: Theme): Component {
 			const renderArgs = toBashRenderArgs(args, config);
-			const cmdLines = formatBashCommandLines(renderArgs, uiTheme);
+			// Highlighting the whole (possibly still-streaming) command is the
+			// expensive part: defer it to the first paint, once per component,
+			// so a rebuild that is replaced before painting never pays for it.
+			let cmdLines: string[] | undefined;
 			return framedToolCard(uiTheme, () => {
+				cmdLines ??= formatBashCommandLines(renderArgs, uiTheme);
 				const header =
 					config.showHeader === false
 						? undefined
@@ -275,7 +436,7 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 			args?: TArgs,
 		): Component {
 			const renderArgs = toBashRenderArgs(args, config);
-			const cmdLines = args ? formatBashCommandLines(renderArgs, uiTheme) : undefined;
+			let cmdLines: string[] | undefined;
 			const isError = result.isError === true;
 			const isPartial = options.isPartial === true;
 			const success = !isPartial && !isError;
@@ -342,58 +503,17 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					) {
 						return cachedSnapshot;
 					}
-					const withoutBackground =
-						details?.async?.state === "running"
-							? stripTrailingNotice(rawOutput, formatBackgroundNotice(details.async.jobId))
-							: rawOutput;
-					const strippedOutput = stripOutputNotice(withoutBackground, details?.meta);
-					const withoutExit =
-						details?.exitCode === undefined
-							? strippedOutput
-							: stripTrailingNotice(strippedOutput, formatExitCodeNotice(details.exitCode));
-					const withoutWall =
-						details?.wallTimeMs === undefined
-							? withoutExit
-							: stripTrailingNotice(withoutExit, formatWallTimeNotice(details.wallTimeMs));
-					const rawOutputArtifact = stripRawOutputArtifactNotice(withoutWall);
+					const rawOutputArtifact = stripBashNotices(rawOutput, details);
 					const output = rawOutputArtifact.text;
 					const displayOutput = output.trimEnd();
 					const showingFullOutput = expanded && renderContext?.isFullOutput === true;
 
-					// Build truncation warning
-					const timeoutDisabled = details?.timeoutDisabled === true || renderContext?.timeout === 0;
-					const timeoutSeconds = timeoutDisabled ? undefined : (details?.timeoutSeconds ?? renderContext?.timeout);
-					const requestedTimeoutSeconds = details?.requestedTimeoutSeconds;
-					const wallTimeMs = details?.wallTimeMs;
-					const statsParts: string[] = [];
-					if (details?.async?.state === "running") {
-						statsParts.push(`Backgrounded: ${details.async.jobId}`);
-					}
-					if (details?.service) {
-						const service = details.service;
-						statsParts.push(`Service: ${service.name}`, `State: ${service.state}`);
-						statsParts.push(`Ready: ${service.ready ? "yes" : service.timedOut ? "timed out" : "no"}`);
-						if (service.pid !== undefined) statsParts.push(`PID: ${service.pid}`);
-					}
-					if (wallTimeMs !== undefined) {
-						statsParts.push(`Wall: ${formatWallTimeSeconds(wallTimeMs)}s`);
-					}
-					if (timeoutDisabled) {
-						statsParts.push("Timeout: disabled");
-					}
-					if (typeof timeoutSeconds === "number") {
-						statsParts.push(
-							requestedTimeoutSeconds !== undefined && requestedTimeoutSeconds !== timeoutSeconds
-								? `Timeout: ${timeoutSeconds}s (requested ${requestedTimeoutSeconds}s clamped)`
-								: `Timeout: ${timeoutSeconds}s`,
-						);
-					}
-					if (rawOutputArtifact.artifactId) {
-						statsParts.push(`Artifact: ${rawOutputArtifact.artifactId}`);
-					}
-					if (isError && typeof details?.exitCode === "number") {
-						statsParts.push(`Exit: ${details.exitCode}`);
-					}
+					const statsParts = bashStatsParts(
+						details,
+						renderContext?.timeout,
+						rawOutputArtifact.artifactId,
+						isError,
+					);
 					const timeoutLine =
 						statsParts.length > 0
 							? uiTheme.fg(
@@ -438,7 +558,11 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 							{
 								// Viewport-sized tail window in every state — streaming and final
 								// render identically; only ctrl+o uncaps.
-								content: capPreviewLines(cmdLines ?? [], uiTheme, { expanded }),
+								content: capPreviewLines(
+									args ? (cmdLines ??= formatBashCommandLines(renderArgs, uiTheme)) : [],
+									uiTheme,
+									{ expanded },
+								),
 							},
 							{ label: uiTheme.fg("toolTitle", "Output"), content: outputLines },
 						],
@@ -466,6 +590,53 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 				},
 			);
 		},
+		describeCall(args: TArgs, options: RenderResultOptions): NativeToolView {
+			const command = formatBashCommandText(toBashRenderArgs(args, config));
+			// The command shows once, in the head; the body is only the output.
+			return {
+				tool: shellToolHead(config.resolveTitle(args, options), command, undefined, false),
+				preview: { tail: BASH_DEFAULT_PREVIEW_LINES },
+			};
+		},
+
+		describeResult(
+			result: {
+				content: Array<{ type: string; text?: string }>;
+				details?: BashToolDetails;
+				isError?: boolean;
+			},
+			options: RenderResultContextOptions & { renderContext?: BashRenderContext },
+			args?: TArgs,
+		): NativeToolView {
+			const details = result.details;
+			const renderContext = options.renderContext;
+			const isError = result.isError === true;
+			const isPartial = options.isPartial === true;
+			const rawOutput = renderContext?.output ?? resultText(result);
+			const stripped = stripBashNotices(rawOutput, details);
+			const output = stripped.text.trimEnd();
+			const expanded = renderContext?.expanded ?? options.expanded;
+			const showingFullOutput = expanded && renderContext?.isFullOutput === true;
+			const command = formatBashCommandText(toBashRenderArgs(args, config));
+			const previewLines = renderContext?.previewLines ?? BASH_DEFAULT_PREVIEW_LINES;
+			// Wall time is the head timer, the timeout a note only when hit, the exit a head chip:
+			// what is left (service state, artifact, truncation) is one quiet final line.
+			const meta = details?.meta;
+			const body: NativeChild[] = compact([
+				output.trim().length > 0 &&
+					keyed(ansi(output, { follow: isPartial, role: "omp.tool.bash.output" }), "output"),
+				footnoteText(shellFootParts(details, stripped.artifactId), {
+					...meta,
+					truncation: showingFullOutput ? undefined : meta?.truncation,
+				}),
+			]);
+			return {
+				tool: shellToolHead(config.resolveTitle(args, options), command, details, !isPartial),
+				body,
+				tone: !isPartial && isError && details?.timedOut === true ? "warning" : undefined,
+				preview: { tail: previewLines },
+			};
+		},
 		mergeCallAndResult: true,
 		inline: true,
 	} satisfies ToolRenderer<TArgs, BashToolDetails>;

package/src/tools/cfg-render.ts

@@ -16,8 +16,11 @@ import {
 } from "../render/render-utils";
 import { highlightCode, type Theme } from "../theme/theme";
 import { parseCfgUrl } from "./cfg-url";
-import type { RenderResultOptions } from "./renderer";
+import type { NativeToolView, RenderResultOptions } from "./renderer";
 import { card, type CardToolResult, firstText, safe } from "./result-card";
+import { code, compact, span, text } from "../native/describe";
+import { plainText } from "../native/spans";
+import { errorView, toolHead } from "./native-view";
 
 /** Summary of a `cfg://` read, attached to read tool details. */
 export interface CfgReadDetails {
@@ -77,6 +80,68 @@ export function renderCfgRead(
 	}, options);
 }
 
+/** TSP view of `read cfg://…`: path and counts in the head, the listing as YAML. */
+export function describeCfgRead(
+	url: string,
+	result: CardToolResult | undefined,
+	details: CfgReadDetails | undefined,
+): NativeToolView {
+	const description = (details?.path ?? parseCfgUrl(url)?.segments.join(".")) || "all settings";
+	const meta: string[] = [];
+	if (details) {
+		meta.push(details.count === 1 ? "1 setting" : `${details.count} settings`);
+		if (details.modified) meta.push(`${details.modified} modified`);
+	}
+	if (result?.isError) return errorView("Config", firstText(result) || "Settings read failed.", description, ...meta);
+	const head = toolHead("Config", description, ...meta);
+	if (!result) return { head };
+	const listing = plainText(safe(firstText(result).trimEnd()));
+	return {
+		head,
+		body: listing ? [code(listing, { lang: "yaml" })] : undefined,
+		preview: { lines: PREVIEW_LIMITS.COLLAPSED_ITEMS },
+	};
+}
+
+/** TSP view of `write cfg://…[/save]`: scope/outcome in the head, then `previous → value`. */
+export function describeCfgWrite(
+	url: string,
+	content: string | undefined,
+	result: CardToolResult | undefined,
+	details: CfgWriteDetails | undefined,
+): NativeToolView {
+	const target = parseCfgUrl(url);
+	const path = details?.path ?? target?.segments.join(".");
+	const save = details?.save ?? target?.save ?? false;
+	if (result?.isError) return errorView("Config", firstText(result) || "Settings write failed.", path);
+	const head = toolHead("Config", path);
+	head.push(span(" "), span(save ? "persist" : "session", save ? "accent strong" : "muted"));
+	if (details?.outcome === "declined") head.push(span(" "), span("declined", "warning strong"));
+	if (details?.outcome === "unchanged") head.push(span(" "), span("unchanged", "muted"));
+	const next = span(plainText(details?.value ?? content?.trim() ?? "…"), "toolOutput");
+	const change = details
+		? [span(plainText(details.previous), "dim"), span(" → ", "dim"), next]
+		: [span("→ ", "dim"), next];
+	return {
+		head,
+		tone: details?.outcome === "declined" ? "warning" : undefined,
+		body: compact([
+			text(change, { wrap: "word" }),
+			details?.effective !== undefined
+				? text(
+						[
+							span(
+								`still ${plainText(details.effective)}: a higher-precedence layer overrides the saved value`,
+								"warning",
+							),
+						],
+						{ wrap: "word" },
+					)
+				: undefined,
+		]),
+	};
+}
+
 /** Render `write cfg://…[/save]`: the proposed value while pending, then the approved/declined change. */
 export function renderCfgWrite(
 	url: string,

package/src/tools/debug.ts

@@ -11,7 +11,11 @@ import {
 	TRUNCATE_LENGTHS,
 	truncateToWidth,
 } from "../render/render-utils";
-import type { RenderResultOptions, ToolRenderer } from "./renderer";
+import type { NativeToolView, RenderResultOptions, ToolRenderer, ToolRenderResult } from "./renderer";
+import { ansi, kv } from "../native/describe";
+import type { NativeChild } from "../native/node";
+import { OwnerMemo } from "../native/memo";
+import { errorView, noteText, resultText, toolHead } from "./native-view";
 
 /** Display fields captured from a debugger session. */
 export interface DebugSessionSnapshot {
@@ -115,6 +119,68 @@ function summarizeDebugCall(args: DebugRenderArgs): string {
 	return action;
 }
 
+/** Untruncated `[action, target]` for native heads; mirrors {@link summarizeDebugCall}'s field precedence. */
+function debugCallParts(args: DebugRenderArgs | undefined, fallbackAction: string): [string, string | undefined] {
+	const action = (args?.action ?? fallbackAction).replaceAll("_", " ");
+	if (!args) return [action, undefined];
+	const target =
+		args.program ||
+		(args.file && args.line !== undefined ? `${args.file}:${args.line}` : undefined) ||
+		args.function ||
+		args.expression ||
+		args.command ||
+		args.memory_reference ||
+		args.instruction_reference ||
+		args.data_id ||
+		args.name ||
+		undefined;
+	return [action, target];
+}
+
+function describeDebugResult(
+	result: ToolRenderResult<DebugToolDetails>,
+	args: DebugRenderArgs | undefined,
+): NativeToolView {
+	const [action, target] = debugCallParts(args, result.details?.action ?? "debug");
+	const output = resultText(result);
+	if (result.isError) return errorView("Debug", output || "Debug failed", action, target);
+	const snapshot = result.details?.snapshot;
+	const body: NativeChild[] = [];
+	let sessionRows = 0;
+	if (snapshot) {
+		const location = formatLocation(snapshot);
+		const rows: [string, string | undefined][] = [
+			["Session", snapshot.id],
+			["Adapter", snapshot.adapter],
+			["Status", snapshot.status],
+			["CWD", snapshot.cwd],
+			["Program", snapshot.program],
+			["Stop reason", snapshot.stopReason],
+			["Frame", snapshot.frameName],
+			["Instruction pointer", snapshot.instructionPointerReference],
+			["Location", location ?? undefined],
+			[
+				"Configuration",
+				snapshot.needsConfigurationDone ? "pending configurationDone; set breakpoints, then continue." : undefined,
+			],
+			["Exit code", snapshot.exitCode !== undefined ? String(snapshot.exitCode) : undefined],
+		];
+		const grid = kv(rows);
+		if (grid) {
+			body.push(grid);
+			sessionRows = rows.filter(([, value]) => value).length;
+		}
+	}
+	body.push(output ? ansi(output) : noteText("No output"));
+	return {
+		head: toolHead("Debug", action, target),
+		body,
+		preview: { lines: sessionRows + PREVIEW_LIMITS.COLLAPSED_LINES },
+	};
+}
+
+const debugResultMemo = new OwnerMemo<NativeToolView | undefined>();
+
 /** Renders debugger calls and captured execution snapshots. */
 export const debugToolRenderer = {
 	animatedPartialResult: true,
@@ -162,6 +228,17 @@ export const debugToolRenderer = {
 			};
 		});
 	},
+	describeCall(args: DebugRenderArgs): NativeToolView {
+		const [action, target] = debugCallParts(args, "request");
+		return { head: toolHead("Debug", action, target) };
+	},
+	describeResult(
+		result: ToolRenderResult<DebugToolDetails>,
+		_options: RenderResultOptions,
+		args?: DebugRenderArgs,
+	): NativeToolView | undefined {
+		return debugResultMemo.get(result, [], () => describeDebugResult(result, args));
+	},
 	mergeCallAndResult: true,
 	inline: true,
 } satisfies ToolRenderer<DebugRenderArgs, DebugToolDetails>;

package/src/tools/default-renderer.ts

@@ -1,12 +1,15 @@
 import type { Component } from "../index";
 import { isRecord } from "@oh-my-pi/pi-utils";
-import type { RenderResultOptions } from "./renderer";
+import type { NativeToolHead, NativeToolView, RenderResultOptions } from "./renderer";
+import { ansi } from "../native/describe";
+import { noteText } from "./native-view";
 import type { Theme } from "../theme/theme";
 import { formatOutputPaneLines, styleToolOutputLine } from "../render/output-pane";
 import { renderStatusLine, type StatusLineOptions } from "../render/status-line";
 import { plainToolCard, type ToolCardPhase } from "../render/tool-card";
 import { truncateToWidth } from "../render/render-utils";
 import {
+	describeJsonTree,
 	formatArgsInline,
 	JSON_TREE_MAX_DEPTH_COLLAPSED,
 	JSON_TREE_MAX_DEPTH_EXPANDED,
@@ -159,6 +162,37 @@ export function formatDefaultToolExecution(
 	return [renderStatusLine(snapshot.status, uiTheme), ...snapshot.body].join("\n");
 }
 
+/** Inline args summary budget in characters (a data cap, not a width). */
+const NATIVE_ARGS_SUMMARY_CHARS = 160;
+/** Result text kept for the native card body. */
+const NATIVE_RESULT_MAX_CHARS = 64 * 1024;
+
+/**
+ * TSP view of the generic fallback card: the tool label with a one-line args
+ * summary as the head target; the result as a JSON tree or raw `ansi` output.
+ */
+export function describeDefaultToolExecution(input: DefaultToolRenderInput): NativeToolView {
+	const { result } = input;
+	const args = isRecord(input.args) ? input.args : undefined;
+	const summary =
+		args && Object.keys(args).length > 0
+			? formatArgsInline(args, NATIVE_ARGS_SUMMARY_CHARS, { characterBudget: true })
+			: undefined;
+	const tool: NativeToolHead = { title: input.label, target: summary || undefined, targetKind: "text" };
+	if (!result) return { tool };
+	const output = result.output.trimEnd().slice(0, NATIVE_RESULT_MAX_CHARS);
+	const tone = result.skipped ? "info" : result.isError ? "error" : undefined;
+	if (!output) return { tool, tone, body: [noteText("(no output)")] };
+	if (output.startsWith("{") || output.startsWith("[")) {
+		try {
+			return { tool, tone, body: [describeJsonTree(JSON.parse(output))] };
+		} catch {
+			// Not JSON: shown as raw output below.
+		}
+	}
+	return { tool, tone, body: [ansi(output)] };
+}
+
 /** Render the generic fallback as the state-tinted card used by direct custom tools. */
 export function renderDefaultToolExecution(input: DefaultToolRenderInput, uiTheme: Theme): Component {
 	return plainToolCard(