@heyhuynhgiabuu/pi-pretty 0.6.26 → 0.6.28

package/src/tools/read.ts

@@ -1,7 +1,8 @@
 /* pi-pretty: read tool -- file reading with syntax highlighting and inline image support. */
 
-import { basename, dirname } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { getReadmePath } from "@earendil-works/pi-coding-agent";
 import {
 	BG_BASE,
 	BG_ERROR,
@@ -14,13 +15,24 @@ import {
 	termWidth,
 } from "../config.js";
 import { normalizeLineEndings, shortPath } from "../helpers.js";
-import { fillToolBackground, renderFileContent, renderToolError } from "../render.js";
+import { fillToolBackground, fillToolBody, renderFileContent, renderToolError } from "../render.js";
 import { resolveTextCtor } from "../tui-text.js";
 import type { ReadDetails, RenderCtxLike, SdkToolDef, TextContent, ThemeLike } from "../types.js";
 import { wrapExecuteWithMetrics } from "./metrics.js";
 
 type Result = AgentToolResult<Record<string, unknown>>;
 
+function getPiDocsLabel(filePath: string, cwd: string): string | undefined {
+	const packageRoot = dirname(getReadmePath());
+	const relativePath = relative(resolve(packageRoot), resolve(cwd, filePath));
+	if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+		return undefined;
+	}
+
+	const label = relativePath.split(sep).join("/");
+	return label === "README.md" || label.startsWith("docs/") || label.startsWith("examples/") ? label : undefined;
+}
+
 function getSkillName(filePath: string, content: string): string | undefined {
 	if (basename(filePath) !== "SKILL.md") return undefined;
 
@@ -54,6 +66,7 @@ export function registerReadTool(
 	_fffService: unknown,
 	sdkTool: SdkToolDef,
 	TextComp?: new (t?: string, x?: number, y?: number) => { setText(v: string): void },
+	renderContent: typeof renderFileContent = renderFileContent,
 ): void {
 	const TC = resolveTextCtor(TextComp);
 	const home = process.env.HOME ?? "";
@@ -63,6 +76,9 @@ export function registerReadTool(
 		label: "Read",
 		description: sdkTool.description ?? "Read file contents",
 		parameters: sdkTool.parameters,
+		promptSnippet: sdkTool.promptSnippet,
+		promptGuidelines: sdkTool.promptGuidelines,
+		constrainedSampling: sdkTool.constrainedSampling,
 		renderShell: "self",
 
 		execute: wrapExecuteWithMetrics(async (tid, params, sig, _upd, ctx: ExtensionContext) => {
@@ -100,17 +116,18 @@ export function registerReadTool(
 
 			const path = String(args.path ?? "");
 			const label = theme.fg("error", theme.bold("→ read"));
-			text.setText(fillToolBackground(`\n${TOOL_RESULT_INDENT}${label} ${theme.fg("toolTitle", path)}`, BG_ERROR));
+			text.setText(fillToolBackground(`\n${TOOL_RESULT_INDENT}${label} ${theme.fg("toolTitle", path)}\n`, BG_ERROR));
 			return text;
 		},
 
 		renderResult(result: Result, _opt: unknown, theme: ThemeLike, ctx: RenderCtxLike) {
 			resolveBaseBackground(theme);
 
+			const renderToken = nextReadRenderToken(ctx);
 			const text = ctx.lastComponent ?? new TC("", 0, 0);
 
 			if (ctx.isError) {
-				text.setText(fillToolBackground(renderToolError(getText(result) || "Error", theme), BG_ERROR));
+				text.setText(renderToolError(getText(result) || "Error", theme));
 				return text;
 			}
 
@@ -121,7 +138,8 @@ export function registerReadTool(
 			// or unsupported by the terminal.
 			if (d?._type === "readImage") {
 				const note = getText(result);
-				text.setText(note ? fillToolBackground(note, BG_BASE) : "");
+				// Keep fallback text visually separated from the preceding tool row.
+				text.setText(note ? fillToolBody(`\n${note}`, BG_BASE) : "");
 				return text;
 			}
 
@@ -137,12 +155,16 @@ export function registerReadTool(
 				if (!ctx.expanded) {
 					if (skillName) {
 						const header = renderSkillHeader(skillName, false, theme);
-						text.setText(fillToolBackground(`\n${TOOL_RESULT_INDENT}${header}`, BG_BASE));
+						text.setText(fillToolBody(`\n${TOOL_RESULT_INDENT}${header}\n`, BG_BASE));
 						return text;
 					}
+					const docsLabel = getPiDocsLabel(filePath, cwd);
+					const title = docsLabel
+						? `${theme.fg("toolTitle", theme.bold("→ read docs"))} ${theme.fg("toolTitle", docsLabel)}`
+						: `${theme.fg("toolTitle", theme.bold("→ read"))} ${theme.fg("toolTitle", p2)}`;
 					text.setText(
-						fillToolBackground(
-							`\n${TOOL_RESULT_INDENT}${theme.fg("toolTitle", theme.bold("→ read"))} ${theme.fg("toolTitle", p2)}${theme.fg("dim", off2)}\n${TOOL_RESULT_INDENT}${FG_DIM}${total} lines — ctrl+o to expand${RST}\n`,
+						fillToolBody(
+							`\n${TOOL_RESULT_INDENT}${title}${theme.fg("dim", off2)} ${FG_DIM}${total} lines — ctrl+o to expand${RST}`,
 							BG_BASE,
 						),
 					);
@@ -150,19 +172,34 @@ export function registerReadTool(
 				}
 				const maxShow = lines.length;
 				const show = lines.slice(0, maxShow);
-				const nw = Math.max(3, String((d.offset || 0) + total).length);
+				const offset = d.offset || 0;
+				const nw = Math.max(3, String(offset + total).length);
 				const gw = nw + 3;
 				const cw = Math.max(1, tw - gw);
 
 				const header = skillName
 					? renderSkillHeader(skillName, true, theme)
 					: `${theme.fg("toolTitle", theme.bold("→ read"))} ${theme.fg("toolTitle", p2)}${theme.fg("dim", off2)}`;
-				const out: string[] = ["", `${TOOL_RESULT_INDENT}${header}`];
+				const highlightRequest: ReadHighlightRequest = {
+					content: d.content,
+					filePath: d.filePath,
+					offset,
+					maxLines: maxShow,
+					width: cw,
+				};
+				const cachedHighlight = getCachedReadHighlight(ctx, highlightRequest);
+				if (cachedHighlight !== undefined) {
+					const highlighted = buildHighlightedRead(cachedHighlight, header, skillName, offset, nw, tw);
+					text.setText(fillToolBody(highlighted, BG_BASE));
+					return text;
+				}
+
+				const out: string[] = ["", `${TOOL_RESULT_INDENT}${header}`, ""];
 				out.push(`${TOOL_RESULT_INDENT}${FG_RULE}${"─".repeat(tw - 1)}${RST}`);
 				for (let i = 0; i < show.length; i++) {
-					const ln = (d.offset || 0) + i + 1;
+					const ln = offset + i + 1;
 					const code = show[i] ?? "";
-					const display = code.length > cw ? code.slice(0, Math.max(0, cw - 1)) + `${FG_DIM}›${RST}` : code;
+					const display = code.length > cw ? `${code.slice(0, Math.max(0, cw - 1))}${FG_DIM}›${RST}` : code;
 					const lineNo = String(ln);
 					out.push(
 						`${TOOL_RESULT_INDENT}${FG_LNUM}${" ".repeat(Math.max(0, nw - lineNo.length))}${lineNo}${RST} ${FG_RULE}│${RST} ${display}${RST}`,
@@ -171,27 +208,18 @@ export function registerReadTool(
 				if (total > maxShow) {
 					out.push(`${TOOL_RESULT_INDENT}${FG_DIM}… ${total - maxShow} more lines (${total} total)${RST}`);
 				}
-				out.push("");
 				const rendered = out.join("\n");
-				text.setText(fillToolBackground(rendered, BG_BASE));
-				(ctx as any).state._rt = rendered;
+				text.setText(fillToolBody(rendered, BG_BASE));
 
-				// Async syntax highlighting via Shiki
-				renderFileContent(d.content, d.filePath, d.offset || 0, maxShow, cw)
+				// Async syntax highlighting via Shiki. The component is reused across
+				// expansion changes, so stale work must not restore an older view.
+				renderContent(d.content, d.filePath, offset, maxShow, cw)
 					.then((hl) => {
-						const padded = hl
-							.split("\n")
-							.map((line, index) => {
-								const lineNo = String((d.offset || 0) + index + 1);
-								return `${TOOL_RESULT_INDENT}${FG_LNUM}${" ".repeat(Math.max(0, nw - lineNo.length))}${lineNo}${RST} ${FG_RULE}│${RST} ${line}${RST}`;
-							})
-							.join("\n");
-						const divider = skillName
-							? `${TOOL_RESULT_INDENT}${FG_RULE}${"─".repeat(Math.max(1, tw - 1))}${RST}\n`
-							: "";
-						const rendered = `\n${TOOL_RESULT_INDENT}${header}\n${divider}${padded}\n`;
-						text.setText(fillToolBackground(rendered, BG_BASE));
-						(ctx as any).state._rt = rendered;
+						if (!isCurrentReadRender(ctx, renderToken)) return;
+						setCachedReadHighlight(ctx, highlightRequest, hl);
+						const highlighted = buildHighlightedRead(hl, header, skillName, offset, nw, tw);
+						text.setText(fillToolBody(highlighted, BG_BASE));
+						ctx.invalidate?.();
 					})
 					.catch(() => {});
 
@@ -200,7 +228,7 @@ export function registerReadTool(
 
 			const fc = result.content?.[0];
 			text.setText(
-				fillToolBackground(
+				fillToolBody(
 					`${TOOL_RESULT_INDENT}${theme.fg("dim", fc && "text" in fc ? String(fc.text).slice(0, 120) : "done")}`,
 					BG_BASE,
 				),
@@ -210,6 +238,73 @@ export function registerReadTool(
 	} as unknown as ToolDefinition<any, any, any>);
 }
 
+const READ_RENDER_TOKEN = "__piPrettyReadRenderToken";
+const READ_HIGHLIGHT_CACHE = "__piPrettyReadHighlightCache";
+
+type ReadHighlightRequest = {
+	content: string;
+	filePath: string;
+	offset: number;
+	maxLines: number;
+	width: number;
+};
+
+type ReadHighlightCache = ReadHighlightRequest & {
+	highlighted: string;
+};
+
+function nextReadRenderToken(ctx: RenderCtxLike): number {
+	const state = ctx.state;
+	const token = typeof state[READ_RENDER_TOKEN] === "number" ? state[READ_RENDER_TOKEN] + 1 : 1;
+	state[READ_RENDER_TOKEN] = token;
+	return token;
+}
+
+function isCurrentReadRender(ctx: RenderCtxLike, token: number): boolean {
+	return ctx.state[READ_RENDER_TOKEN] === token;
+}
+
+function getCachedReadHighlight(ctx: RenderCtxLike, request: ReadHighlightRequest): string | undefined {
+	const cache = ctx.state[READ_HIGHLIGHT_CACHE] as ReadHighlightCache | undefined;
+	if (!cache) return undefined;
+	if (
+		cache.content !== request.content ||
+		cache.filePath !== request.filePath ||
+		cache.offset !== request.offset ||
+		cache.maxLines !== request.maxLines ||
+		cache.width !== request.width
+	) {
+		return undefined;
+	}
+	return cache.highlighted;
+}
+
+function setCachedReadHighlight(ctx: RenderCtxLike, request: ReadHighlightRequest, highlighted: string): void {
+	ctx.state[READ_HIGHLIGHT_CACHE] = {
+		...request,
+		highlighted,
+	} satisfies ReadHighlightCache;
+}
+
+function buildHighlightedRead(
+	highlighted: string,
+	header: string,
+	skillName: string | undefined,
+	offset: number,
+	nw: number,
+	tw: number,
+): string {
+	const padded = highlighted
+		.split("\n")
+		.map((line, index) => {
+			const lineNo = String(offset + index + 1);
+			return `${TOOL_RESULT_INDENT}${FG_LNUM}${" ".repeat(Math.max(0, nw - lineNo.length))}${lineNo}${RST} ${FG_RULE}│${RST} ${line}${RST}`;
+		})
+		.join("\n");
+	const divider = skillName ? `${TOOL_RESULT_INDENT}${FG_RULE}${"─".repeat(Math.max(1, tw - 1))}${RST}\n` : "";
+	return `\n${TOOL_RESULT_INDENT}${header}\n\n${divider}${padded}`;
+}
+
 function getText(result: Result): string {
 	return (
 		((result.content ?? []) as TextContent[])

package/src/types.ts

@@ -2,8 +2,9 @@
  * pi-pretty shared types.
  */
 
-import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
-import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { ConstrainedSamplingConfig, ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { AgentToolResult, CustomEditor } from "@earendil-works/pi-coding-agent";
+import type { FffInitOptions } from "./fff.js";
 
 // ---------------------------------------------------------------------------
 // Re-export FFF types needed by tools
@@ -29,9 +30,11 @@ export interface ThemeLike {
 
 export interface RenderCtxLike {
 	lastComponent?: ComponentLike;
+	toolCallId?: string;
 	isError?: boolean;
-	state: Record<string, string | undefined>;
+	state: Record<string, unknown>;
 	expanded?: boolean;
+	invalidate?: () => void;
 }
 
 export interface TextLike {
@@ -133,6 +136,9 @@ export interface SdkToolDef {
 	description?: string;
 	label?: string;
 	parameters?: unknown;
+	promptSnippet?: string;
+	promptGuidelines?: string[];
+	constrainedSampling?: false | ConstrainedSamplingConfig;
 	execute: (...args: any[]) => Promise<AgentToolResult<any>>;
 }
 
@@ -168,7 +174,7 @@ export interface FffServiceWithCursor extends FffServiceLike {
 
 /** FFF lifecycle interface (used by session lifecycle code). */
 export interface FffService extends FffServiceWithCursor {
-	ensureFinder(cwd: string): Promise<void>;
+	ensureFinder(cwd: string, options?: FffInitOptions): Promise<void>;
 	destroy(): void;
 	isModuleLoaded(): boolean;
 	tryLoadModule(): Promise<boolean>;
@@ -183,6 +189,8 @@ export interface CursorStore {
 // DI
 // ---------------------------------------------------------------------------
 
+export type CustomEditorConstructor = new (...args: ConstructorParameters<typeof CustomEditor>) => CustomEditor;
+
 export interface PiPrettyDeps {
 	sdk?: SdkTools;
 	TextComponent?: new (text?: string, x?: number, y?: number) => ComponentLike;
@@ -191,4 +199,6 @@ export interface PiPrettyDeps {
 	 * to the package export. Injectable so tests can verify against the exact
 	 * class instance they construct rows from. */
 	assistantMessageComponent?: unknown;
+	/** Host CustomEditor class for the live prompt icon; defaults to the package export. */
+	customEditorClass?: CustomEditorConstructor;
 }