@linxiraos/pi-tui 1.2.1 → 1.3.1

package/src/tools/task.ts

@@ -29,6 +29,8 @@ import {
 	isFeedModelBadgeEnabled,
 	pluralize,
 	previewLine,
+	clipCollapsed,
+	flattenLine,
 	previewWindowRows,
 	replaceTabs,
 	shortenEmbeddedPaths,
@@ -347,7 +349,7 @@ function renderOutputSection(
 		lines.push(
 			`${continuePrefix}  ${theme.fg("warning", theme.status.warning)} ${theme.fg(
 				"dim",
-				truncateToWidth(sanitizeText(warning), 80),
+				clipCollapsed(sanitizeText(warning), 80, expanded),
 			)}`,
 		);
 
@@ -391,7 +393,7 @@ function renderOutputSection(
 		const outputLines = trimmedOutput.split("\n");
 		const previewCount = expanded ? maxExpanded : maxCollapsed;
 		for (const line of outputLines.slice(0, previewCount)) {
-			lines.push(`${continuePrefix}  ${theme.fg("dim", truncateToWidth(replaceTabs(line), 70))}`);
+			lines.push(`${continuePrefix}  ${theme.fg("dim", clipCollapsed(replaceTabs(line), 70, expanded))}`);
 		}
 
 		if (outputLines.length > previewCount) {
@@ -444,7 +446,7 @@ function renderOutputSection(
 	const outputLines = trimmedOutput.split("\n");
 	const previewCount = expanded ? maxExpanded : maxCollapsed;
 	for (const line of outputLines.slice(0, previewCount)) {
-		lines.push(`${continuePrefix}  ${theme.fg("dim", truncateToWidth(replaceTabs(line), 70))}`);
+		lines.push(`${continuePrefix}  ${theme.fg("dim", clipCollapsed(replaceTabs(line), 70, expanded))}`);
 	}
 
 	if (outputLines.length > previewCount) {
@@ -468,7 +470,7 @@ function renderTaskSection(
 	lines.push(`${continuePrefix}${theme.fg("dim", "Task")}`);
 	const taskLines = trimmed.split("\n");
 	for (const line of taskLines.slice(0, maxExpanded)) {
-		lines.push(`${continuePrefix}  ${theme.fg("dim", truncateToWidth(replaceTabs(line), 70))}`);
+		lines.push(`${continuePrefix}  ${theme.fg("dim", replaceTabs(line))}`);
 	}
 	if (taskLines.length > maxExpanded) {
 		lines.push(`${continuePrefix}  ${theme.fg("dim", formatMoreItems(taskLines.length - maxExpanded, "line"))}`);
@@ -1119,7 +1121,7 @@ function renderAgentResult(
 		lines.push(
 			`${continuePrefix}${theme.fg("error", theme.status.aborted)} ${theme.fg(
 				"dim",
-				previewLine(sanitizeText(result.abortReason), 80),
+				clipCollapsed(flattenLine(sanitizeText(result.abortReason)), 80, expanded),
 			)}`,
 		);
 	}
@@ -1211,7 +1213,7 @@ function renderAgentResult(
 		lines.push(
 			`${continuePrefix}${theme.fg("warning", theme.status.warning)} ${theme.fg(
 				"dim",
-				truncateToWidth(sanitizeText(missingCompleteWarning), 80),
+				clipCollapsed(sanitizeText(missingCompleteWarning), 80, expanded),
 			)}`,
 		);
 	}
@@ -1251,7 +1253,7 @@ function renderAgentResult(
 	// Error message
 	if (result.error && (!success || mergeFailed) && (!aborted || result.error !== result.abortReason)) {
 		lines.push(
-			`${continuePrefix}${theme.fg(mergeFailed ? "warning" : "error", previewLine(sanitizeText(result.error), 70))}`,
+			`${continuePrefix}${theme.fg(mergeFailed ? "warning" : "error", clipCollapsed(flattenLine(sanitizeText(result.error)), 70, expanded))}`,
 		);
 	}
 
@@ -2200,6 +2202,10 @@ export interface TaskItem {
 	name?: string;
 	/** Agent type to run this item (e.g. "scout"). Defaults to the spawn policy's default agent. */
 	agent?: string;
+	/** Historical source session selected by the bundled consult agent. */
+	sourceSession?: string;
+	/** Optional model selector override for the historical source session. */
+	model?: string | string[];
 	/** The work; required by the schema. */
 	task?: string;
 	/** How open-ended the work is; required by the schema and the child's sole `auto` thinking classification input. */
@@ -2227,6 +2233,10 @@ export interface TaskParams {
 	name?: string;
 	/** Agent type to spawn (flat form); omitted values resolve from the session spawn policy. */
 	agent?: string;
+	/** Historical source session selected by the bundled consult agent. */
+	sourceSession?: string;
+	/** Optional model selector override for the historical source session. */
+	model?: string | string[];
 	/** The work (flat form). */
 	task?: string;
 	/** How open-ended the work is (flat form); see {@link TaskItem.solutionSpace}. */
@@ -2497,6 +2507,29 @@ export interface SingleResult {
 		attempt: number;
 		errorMessage: string;
 	};
+	/**
+	 * Coarse category of a non-zero exit — `usage-limit`, `auth`,
+	 * `account-policy`, `context-overflow`, `transient`, `aborted`, or
+	 * `unknown`. A parent agent reads this to tell "swap the model" (the first
+	 * three) from "fix the request" instead of parsing provider prose.
+	 */
+	failureClass?: "usage-limit" | "auth" | "account-policy" | "context-overflow" | "transient" | "aborted" | "unknown";
+	/**
+	 * Other models this session could run instead (selectors accepted by the
+	 * task `model` parameter, including `@role` aliases). Empty when nothing
+	 * else is configured or every alternative is already in cooldown.
+	 */
+	fallbackCandidates?: string[];
+	/**
+	 * Set when a caller-supplied `model` replaced the model this run would
+	 * otherwise have used — the audit trail of an agent-driven switch.
+	 */
+	modelChange?: {
+		source: "spawn-param" | "wake-param";
+		/** The model the run would have used without the override, when resolvable. */
+		from?: string;
+		to: string;
+	};
 	/** Output metadata for agent:// URL integration */
 	outputMeta?: { lineCount: number; charCount: number };
 }

package/src/tools/todo.ts

@@ -8,6 +8,7 @@ import type { RenderResultOptions } from "./renderer";
 import type { Theme } from "../theme/theme";
 
 import { renderStatusLine, renderTreeList } from "../render";
+import { wrapTreeLine } from "../render/hanging-wrap";
 import { framedToolCard } from "../render/tool-card";
 
 import { formatErrorDetail, formatMoreItems, PREVIEW_LIMITS, pluralize, replaceTabs } from "../render/render-utils";
@@ -657,7 +658,7 @@ export const todoToolRenderer = {
 			matchByContent.clear();
 		};
 
-		return framedToolCard(uiTheme, () => {
+		return framedToolCard(uiTheme, ({ contentWidth }) => {
 			const { expanded, spinnerFrame } = options;
 			const multiPhase = phases.length > 1;
 			const indent = multiPhase ? "  " : "";
@@ -738,7 +739,7 @@ export const todoToolRenderer = {
 							);
 						})();
 				for (const line of treeLines) {
-					bodyLines.push(`${indent}${line}`);
+					bodyLines.push(...(wrapTreeLine(`${indent}${line}`, contentWidth, uiTheme) ?? [`${indent}${line}`]));
 				}
 			}
 			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();

package/src/tools/wait.ts

@@ -589,7 +589,11 @@ export function createIrcMessageCard(
 	return Object.assign(component, { describe: () => described });
 }
 
-/** One job row: type badge, id + label, terminal-clocked duration (live while running), preview below. */
+/**
+ * One job row on one line: type badge, id + label, terminal-clocked duration
+ * (live while running). The job's output and errors fill the card of the call
+ * that started it (`parksAsBackground`), so the row carries no preview.
+ */
 function describeJob(job: JobSnapshot, isPartial: boolean): NativeNode {
 	const running = job.status === "running" && isPartial;
 	const label = job.label.trim() !== job.id ? plainText(job.label.split(/\r?\n/)[0] ?? "") : "";
@@ -606,39 +610,21 @@ function describeJob(job: JobSnapshot, isPartial: boolean): NativeNode {
 				: job.status === "cancelled"
 					? "warning"
 					: "accent";
-	const artifactError = job.meta?.artifactError ?? job.artifactError;
-	const preview = flattenStructuredPreview(
-		stripTaskResultEnvelope(
-			stripOutputNotice(job.errorText?.trim() || job.resultText?.trim() || "", job.meta).trim(),
-		),
-	);
 	return node(
-		"col",
-		{ role: "zeta.wait.job", tone },
+		"row",
+		{ role: "zeta.wait.job", tone, gap: "sm" },
 		compact([
-			row(
-				compact([
-					node("badge", { text: job.type, tone }),
-					text(spans, { truncate: "end", grow: 1 }),
-					job.status === "running" && job.completionPercent !== undefined
-						? node("progress", {
-								value: job.completionPercent / 100,
-								label: `${job.completionPercent}%`,
-								tone: "accent",
-								title: "Agent's own completion estimate",
-							})
-						: undefined,
-					elapsed(job.durationMs, !running),
-				]),
-				{ gap: "sm" },
-			),
-			artifactError && text([span(formatArtifactErrorNotice(artifactError), "warning")], { wrap: "word" }),
-			preview
-				? text([span(plainText(preview), job.errorText ? "error" : "dim")], {
-						wrap: "word",
-						lines: PREVIEW_LINES_EXPANDED,
+			node("badge", { text: job.type, tone }),
+			text(spans, { truncate: "end", grow: 1 }),
+			job.status === "running" && job.completionPercent !== undefined
+				? node("progress", {
+						value: job.completionPercent / 100,
+						label: `${job.completionPercent}%`,
+						tone: "accent",
+						title: "Agent's own completion estimate",
 					})
 				: undefined,
+			elapsed(job.durationMs, !running),
 		]),
 		job.id,
 	);

package/src/tools/web-search-types.d.ts

@@ -25,6 +25,7 @@ export declare const SEARCH_PROVIDER_LABELS: {
     readonly tavily: "Tavily";
     readonly firecrawl: "Firecrawl";
     readonly brave: "Brave";
+    readonly deepseek: "DeepSeek";
     readonly kimi: "Kimi";
     readonly synthetic: "Synthetic";
     readonly ollama: "Ollama";

package/src/tools/web-search-types.ts

@@ -26,6 +26,7 @@ export const SEARCH_PROVIDER_LABELS = {
 	tavily: "Tavily",
 	firecrawl: "Firecrawl",
 	brave: "Brave",
+	deepseek: "DeepSeek",
 	kimi: "Kimi",
 	synthetic: "Synthetic",
 	ollama: "Ollama",

package/src/tools/web-search.ts

@@ -19,6 +19,7 @@ import {
 	PREVIEW_LIMITS,
 	replaceTabs,
 	truncateToWidth,
+	clipCollapsed,
 } from "../render/render-utils";
 import { tuiText, tuiTextFmt } from "../i18n";
 import { renderStatusLine, renderTreeList, urlHyperlink } from "../render";
@@ -35,7 +36,7 @@ const MAX_COLLAPSED_ITEMS = PREVIEW_LIMITS.COLLAPSED_ITEMS;
 function renderFallbackText(contentText: string, expanded: boolean, theme: Theme): Component {
 	const lines = contentText.split("\n").filter(line => line.trim());
 	const maxLines = expanded ? lines.length : 6;
-	const displayLines = lines.slice(0, maxLines).map(line => truncateToWidth(line.trim(), 110));
+	const displayLines = lines.slice(0, maxLines).map(line => clipCollapsed(line.trim(), 110, expanded));
 	const remaining = lines.length - displayLines.length;
 
 	const headerIcon = formatStatusIcon("warning", theme);

package/src/tools/write.d.ts

@@ -73,6 +73,8 @@ interface WriteStreamingPreviewStateCarrier {
 /** Render context for the write tool: resolves an `xd://`-mounted tool so its live renderer drives device dispatch previews. */
 export interface WriteRenderContext {
     resolveXdevMounted?: (name: string) => XdevMountedRenderer | undefined;
+    /** Original result metadata used only for filesystem link targets. */
+    rawDetails?: unknown;
 }
 /** Render file writes and delegated tool-device calls. */
 export declare const writeToolRenderer: {

package/src/tools/write.ts

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { sanitizeText } from "@linxiraos/pi-utils";
 import type { HighlightStream } from "@linxiraos/pi-natives";
 import type { Component } from "../tui";
 import { fencedCode } from "../components/markdown";
@@ -7,6 +8,7 @@ import { getLanguageFromPath } from "../lang-from-path";
 import { createHighlightStream, highlightCode, type Theme } from "../theme/theme";
 import { fileHyperlink, renderStatusLine } from "../render";
 import { framedToolCard } from "../render/tool-card";
+import { wrapPrefixedLine } from "../render/hanging-wrap";
 import {
 	cachedRenderedString,
 	createRenderedStringCache,
@@ -162,10 +164,12 @@ function describeFigure(figure: ToolFigure | undefined): NativeNode | undefined
 	return { ...md(text, { role: "zeta.tool.write.figure", stream: !figure.closed }), key: "figure" };
 }
 
-/** The written content as numbered code, keyed so it keeps its node as the figure above it comes and goes. */
+/**
+ * The written content as numbered code, highlighted by Tern from the file's path,
+ * keyed so it keeps its node as the figure above it comes and goes.
+ */
 function describeSource(rawPath: string, content: string): NativeNode {
-	const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
-	return { ...code(content, { lang, numbers: true }), key: "source" };
+	return { ...code(content, { path: rawPath || undefined, numbers: true, wrap: true }), key: "source" };
 }
 
 function countLines(text: string): number {
@@ -388,6 +392,15 @@ function formatStreamingContent(
 	return `${bodyText}${spinner}${uiTheme.fg("dim", `… (streaming)`)}`;
 }
 
+function wrapWritePreviewRows(lines: string[], width: number): string[] {
+	return lines.flatMap(line => {
+		const gutter = /^(\x1b\[[0-9;]*m)( *\d+ )(\x1b\[[0-9;]*m)(.*)$/.exec(line);
+		if (!gutter) return line;
+		const prefix = `${gutter[1]}${gutter[2]}${gutter[3]}`;
+		return wrapPrefixedLine(prefix, " ".repeat(Bun.stringWidth(gutter[2]!)), gutter[4] ?? "", width);
+	});
+}
+
 function renderContentPreview(
 	content: string,
 	expanded: boolean,
@@ -424,6 +437,8 @@ function renderContentPreview(
 /** Render context for the write tool: resolves an `xd://`-mounted tool so its live renderer drives device dispatch previews. */
 export interface WriteRenderContext {
 	resolveXdevMounted?: (name: string) => XdevMountedRenderer | undefined;
+	/** Original result metadata used only for filesystem link targets. */
+	rawDetails?: unknown;
 }
 
 /** Process id and operation named by the text after `proc://`. */
@@ -540,6 +555,15 @@ function describeWriteUrl(
 	}
 }
 
+function writeResolvedPath(rawDetails: unknown, fallback: string | undefined): string | undefined {
+	return rawDetails !== null &&
+		typeof rawDetails === "object" &&
+		"resolvedPath" in rawDetails &&
+		typeof rawDetails.resolvedPath === "string"
+		? rawDetails.resolvedPath
+		: fallback;
+}
+
 /** Native write head shared by the call and result: `Write · path · 22 lines`, executable/diagnostics chips. */
 function writeToolHead(
 	rawPath: string,
@@ -553,7 +577,7 @@ function writeToolHead(
 	if (diagnostics) badges.push(diagnostics);
 	return {
 		title: "Write",
-		target: rawPath ? displayPath(rawPath) : undefined,
+		target: rawPath ? sanitizeText(displayPath(rawPath)) : undefined,
 		targetKind: "path",
 		href: fileHref(details?.resolvedPath),
 		meta: lineCount > 0 ? [`${lineCount} line${lineCount === 1 ? "" : "s"}`] : undefined,
@@ -611,7 +635,7 @@ export const writeToolRenderer = {
 			if (xdev.name === REPORT_ISSUE_DEVICE_NAME) return renderReportIssueDeviceCall(args.content, uiTheme);
 			return renderXdevCall(xdev.name, args.content, options, uiTheme, options.renderContext?.resolveXdevMounted);
 		}
-		const filePath = shortenPath(rawPath);
+		const filePath = sanitizeText(shortenPath(rawPath));
 		const lang = rawPath ? (getLanguageFromPath(rawPath) ?? "text") : "text";
 		const langIcon = uiTheme.fg("muted", uiTheme.getLangIcon(lang));
 		const styledPath = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
@@ -639,7 +663,7 @@ export const writeToolRenderer = {
 		const streamingCache = createRenderedStringCache();
 		return framedToolCard(
 			uiTheme,
-			() => {
+			({ contentWidth }) => {
 				const body = content
 					? formatStreamingContent(
 							content,
@@ -660,7 +684,7 @@ export const writeToolRenderer = {
 				while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
 				return {
 					header,
-					sections: bodyLines.length > 0 ? [{ content: bodyLines }] : [],
+					sections: bodyLines.length > 0 ? [{ content: wrapWritePreviewRows(bodyLines, contentWidth) }] : [],
 					phase: "pending",
 					borderColor: "borderMuted",
 				};
@@ -695,14 +719,14 @@ export const writeToolRenderer = {
 		}
 		const rawPath =
 			typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
-		const filePath = shortenPath(rawPath);
+		const filePath = sanitizeText(shortenPath(rawPath));
 		const fileContent = normalizeDisplayText(args?.content);
 		const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
 		const langIcon = uiTheme.fg("muted", uiTheme.getLangIcon(lang));
 		// The header shows the cwd-relative path but links to the absolute path the
 		// write resolved to (args.path may be relative, which would yield a broken
 		// `file://` URI). Falls back to plain text when the result lacks a path.
-		const linkTarget = result.details?.resolvedPath;
+		const linkTarget = writeResolvedPath(options.renderContext?.rawDetails, result.details?.resolvedPath);
 		const styledPath = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
 		const pathDisplay = filePath && linkTarget ? fileHyperlink(linkTarget, styledPath) : styledPath;
 
@@ -743,7 +767,7 @@ export const writeToolRenderer = {
 		const previewCache = createRenderedStringCache();
 		return framedToolCard(
 			uiTheme,
-			() => {
+			({ contentWidth }) => {
 				const { expanded } = options;
 				let body = renderContentPreview(fileContent, expanded, lang, uiTheme, previewCache);
 				if (isPartial && progressText) {
@@ -768,7 +792,7 @@ export const writeToolRenderer = {
 				while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
 				return {
 					header,
-					sections: bodyLines.length > 0 ? [{ content: bodyLines }] : [],
+					sections: bodyLines.length > 0 ? [{ content: wrapWritePreviewRows(bodyLines, contentWidth) }] : [],
 					phase: isPartial ? "partial" : "success",
 					borderColor: "borderMuted",
 				};
@@ -825,7 +849,7 @@ export const writeToolRenderer = {
 		const diagnostics = isPartial ? undefined : result.details?.diagnostics;
 		const tool = writeToolHead(rawPath, fileContent, {
 			madeExecutable: !isPartial && result.details?.madeExecutable === true,
-			resolvedPath: result.details?.resolvedPath,
+			resolvedPath: writeResolvedPath(options.renderContext?.rawDetails, result.details?.resolvedPath),
 			diagnostics,
 		});
 		if (result.isError) return { tool, tone: "error", body: [errorText(resultText(result))] };

package/src/tools/yield.ts

@@ -9,7 +9,7 @@ import { compact, md } from "../native/describe";
 import { OwnerMemo } from "../native/memo";
 import type { NativeChild } from "../native/node";
 import { formatOutputPaneLines, styleToolOutputLine } from "../render/output-pane";
-import { formatExpandHint, sanitizeDisplayLines, truncateToWidth } from "../render/render-utils";
+import { clipCollapsed, formatExpandHint, sanitizeDisplayLines } from "../render/render-utils";
 import type { StatusLineOptions } from "../render/status-line";
 import { plainToolCard, type ToolCardPhase } from "../render/tool-card";
 import type { Theme } from "../theme/theme";
@@ -134,7 +134,7 @@ function dataLines(data: unknown, expanded: boolean, width: number, theme: Theme
 					lines: sanitizeText(data).trimEnd().split("\n"),
 					expanded,
 					collapsedMaxLines: TEXT_ROWS_COLLAPSED,
-					styleLine: line => truncateToWidth(styleToolOutputLine(line, theme), width),
+					styleLine: line => clipCollapsed(styleToolOutputLine(line, theme), width, expanded),
 				},
 				theme,
 			).lines,

package/src/tui.d.ts

@@ -115,9 +115,6 @@ export interface Component {
      * last time.
      */
     render(width: number): readonly string[];
-    /** Inline decision panels must keep displaced settled transcript rows in
-     * native scrollback even when mounted inside a transient editor container. */
-    readonly retireDisplacedTranscript?: boolean;
     /**
      * Describe the component semantically for a Tern Surface Protocol
      * terminal (see `native/node.ts`). Called instead of `render()` when the
@@ -351,6 +348,7 @@ export declare class TUI extends Container {
     overlayStack: {
         component: Component;
         options?: OverlayOptions;
+        /** Focus restored after closing; tracks live focus changes beneath an input-less key holder. */
         preFocus: Component | null;
         hidden: boolean;
         /**
@@ -458,6 +456,16 @@ export declare class TUI extends Container {
         top: number;
         length: number;
     };
+    /**
+     * Rows of native history the last paint left on screen above a mutable
+     * viewport that reached the bottom row, or `undefined` when that paint left
+     * rows free below it (or none happened, or a destructive reset will repaint
+     * from row zero). Rows above a bottom-reaching viewport may already sit in
+     * native scrollback, which a later shrink cannot pull back down.
+     */
+    getFilledHistoryRows(): number | undefined;
+    /** Whether native history holds rows the frame provider committed since the last destructive reset. */
+    hasProviderHistory(): boolean;
     /**
      * Probe for opt-in normal-buffer click capture. The provider is read every
      * frame; while it returns true (and no fullscreen overlay owns the
@@ -507,6 +515,13 @@ export declare class TUI extends Container {
      * overtaking them. No-op unless `previous` owns the held keys.
      */
     replaceHeldFocus(previous: Component, next: Component): void;
+    /**
+     * Register a hook that re-enables terminal modes on every start(). A hook
+     * added while the TUI is already running (a prepaint composer starts it
+     * before the interactive mode wires its controllers) missed that start, so
+     * it runs immediately instead of waiting for a stop/start cycle that may
+     * never come.
+     */
     addStartListener(listener: StartListener): () => void;
     addInputListener(listener: InputListener): () => void;
     removeInputListener(listener: InputListener): void;
@@ -519,6 +534,8 @@ export declare class TUI extends Container {
      */
     resetDisplay(): void;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
+    /** Run `callback` after `delayMs` on the render scheduler's clock, unless the TUI has stopped. */
+    scheduleAfter(delayMs: number, callback: () => void): RenderTimer;
     /**
      * Paint a forced frame synchronously when startup must hand off an already
      * visible component tree before further async initialization. Same as