@heyhuynhgiabuu/pi-pretty 0.5.2 → 0.6.0

package/src/tools/grep.ts

@@ -0,0 +1,99 @@
+/* pi-pretty: grep tool -- FFF-backed text search with SDK fallback. */
+
+import { type ToolDefinition, type ExtensionAPI, type ExtensionContext, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { SdkToolDef, GrepDetails, FffServiceWithCursor, TextContent, ThemeLike, RenderCtxLike } from "../types.js";
+import { resolveBaseBackground, MAX_PREVIEW_LINES, BG_BASE, BG_ERROR, FG_DIM, RST } from "../config.js";
+import { shortPath, normalizeLineEndings } from "../helpers.js";
+import { wrapExecuteWithMetrics } from "./metrics.js";
+import { renderToolError, renderToolMetrics, fillToolBackground } from "../render.js";
+import { fffFormatGrepText } from "../fff-helpers.js";
+
+type Result = AgentToolResult<Record<string, unknown>>;
+
+export function registerGrepTool(
+	pi: ExtensionAPI,
+	cwd: string,
+	fffService: FffServiceWithCursor | null | undefined,
+	sdkTool: SdkToolDef,
+	TextComp?: new (t?: string, x?: number, y?: number) => { setText(v: string): void },
+): void {
+	const T = TextComp ?? (() => { const m = require("@earendil-works/pi-tui") as { Text: new (t?: string, x?: number, y?: number) => { setText(v: string): void } }; return m.Text; })();
+	const home = process.env.HOME ?? "";
+
+	pi.registerTool({
+		name: "grep",
+		label: "Grep",
+		description: sdkTool.description ?? "Search file contents by pattern",
+		parameters: sdkTool.parameters,
+		renderShell: "self",
+
+		execute: wrapExecuteWithMetrics(async (tid, params, sig, _upd, ctx: ExtensionContext) => {
+			const p = params as any;
+			const pattern = String(p.pattern ?? "");
+			const path = p.path ? String(p.path) : undefined;
+			const glob = p.glob ? String(p.glob) : undefined;
+			const context = typeof p.context === "number" ? p.context : 0;
+			const limit = typeof p.limit === "number" ? p.limit : 200;
+			const literal = p.literal === true;
+
+			if (fffService?.isAvailable && !path && !glob) {
+				try {
+					const fff = fffService.getFinder();
+					if (!fff) throw new Error("FFF finder not available");
+					const effectiveLimit = Math.max(1, limit);
+					const grepResult = fff.grep(pattern, { pageSize: effectiveLimit, mode: literal ? "plain" : "regex", beforeContext: context, afterContext: context });
+					if (grepResult.ok) {
+						const grep = grepResult.value;
+						const items = grep.items.slice(0, effectiveLimit);
+						const cursorStore = fffService.getCursorStore();
+						const notices: string[] = [];
+						if (fffService.partialIndex) notices.push("Warning: partial file index");
+						if (items.length >= effectiveLimit) notices.push(`${effectiveLimit} limit reached`);
+						if (grep.regexFallbackError) notices.push(`Regex failed: ${grep.regexFallbackError}, used literal match`);
+						if (grep.nextCursor) {
+							const cursorId = cursorStore.store(grep.nextCursor);
+							notices.push(`More results available: cursor="${cursorId}"`);
+						}
+						const text = appendNotices(fffFormatGrepText(items, effectiveLimit), notices);
+						return { content: [{ type: "text" as const, text }], details: { _type: "grepResult", text, pattern, matchCount: items.length } as GrepDetails };
+					}
+				} catch { /* fall through */ }
+			}
+
+			const result = await sdkTool.execute(tid, p, sig, undefined, ctx) as Result;
+			for (const c of (result.content ?? []) as any[]) { if (c.type === "text") c.text = normalizeLineEndings(c.text); }
+			const tc = ((result.content ?? []) as TextContent[]).filter((c) => c.type === "text").map((c) => c.text).join("\n") ?? "";
+			result.details = { _type: "grepResult", text: tc, pattern, matchCount: tc ? tc.trim().split("\n").filter(Boolean).length : 0 } as GrepDetails;
+			return result;
+		}),
+
+		renderCall(args: any, theme: ThemeLike, ctx: RenderCtxLike) {
+			resolveBaseBackground(theme);
+			const text = ctx.lastComponent ?? new T("", 0, 0);
+			const p = args.path ? ` ${theme.fg("muted", `in ${shortPath(cwd, home, String(args.path))}`)}` : "";
+			const lit = args.literal ? ` ${theme.fg("dim", "[literal]")}` : "";
+			text.setText(fillToolBackground(`\n  ${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", String(args.pattern ?? ""))}${p}${lit}`, ctx.isError ? BG_ERROR : undefined));
+			return text;
+		},
+
+		renderResult(result: Result, _opt: unknown, theme: ThemeLike, ctx: RenderCtxLike) {
+			resolveBaseBackground(theme);
+			const text = ctx.lastComponent ?? new T("", 0, 0);
+			if (ctx.isError) { text.setText(renderToolError(((result.content ?? []) as TextContent[]).filter((c) => c.type === "text").map((c) => c.text).join("\n") || "Error", theme)); return text; }
+			const d = result.details as GrepDetails | undefined;
+			if (d?._type === "grepResult" && d.text) {
+				const lines = d.text.split("\n");
+				const maxShow = ctx.expanded ? lines.length : Math.min(lines.length, MAX_PREVIEW_LINES);
+				const preview = lines.slice(0, maxShow).map(l => `  ${l}`).join("\n");
+				const more = lines.length > maxShow ? `\n${FG_DIM}  ... ${lines.length - maxShow} more lines${RST}` : "";
+				text.setText(fillToolBackground(`  ${FG_DIM}${d.matchCount} matches${RST}${renderToolMetrics(result)}\n${preview}${more}`));
+				return text;
+			}
+			const fc = result.content?.[0];
+			text.setText(fillToolBackground(`  ${theme.fg("dim", fc && "text" in fc ? String(fc.text).slice(0, 120) : "no matches")}`));
+			return text;
+		},
+	} as unknown as ToolDefinition<any, any, any>);
+}
+
+function appendNotices(text: string, notices: string[]): string { return notices.length ? `${text}\n\n[${notices.join(". ")}]` : text; }

package/src/tools/ls.ts

@@ -0,0 +1,66 @@
+/* pi-pretty: ls tool -- directory listing with styled output. */
+
+import { type ToolDefinition, type ExtensionAPI, type ExtensionContext, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { SdkToolDef, LsDetails, TextContent, ComponentLike, ThemeLike, RenderCtxLike } from "../types.js";
+import { resolveBaseBackground, termWidth, MAX_PREVIEW_LINES, BG_BASE, BG_ERROR, FG_DIM, RST } from "../config.js";
+import { wrapExecuteWithMetrics } from "./metrics.js";
+import { renderTree, renderToolError, renderToolMetrics, fillToolBackground } from "../render.js";
+
+type Result = AgentToolResult<Record<string, unknown>>;
+
+export function registerLsTool(
+	pi: ExtensionAPI,
+	_cwd: string,
+	_fffService: unknown,
+	sdkTool: SdkToolDef,
+	TextComp?: new (t?: string, x?: number, y?: number) => { setText(v: string): void },
+): void {
+	const TC = TextComp ?? (() => {
+		const { Text } = require("@earendil-works/pi-tui") as { Text: new (t?: string, x?: number, y?: number) => { setText(v: string): void } };
+		return Text;
+	})();
+
+	pi.registerTool({
+		name: "ls",
+		label: "List",
+		description: sdkTool.description ?? "List directory contents",
+		parameters: sdkTool.parameters,
+		renderShell: "self",
+
+		execute: wrapExecuteWithMetrics(async (tid, params, sig, _upd, ctx: ExtensionContext) => {
+			const result = await sdkTool.execute(tid, params, sig, undefined, ctx) as Result;
+			const tc = getText(result);
+			result.details = { _type: "lsResult", text: tc, path: String((params as any).path ?? ""), entryCount: tc ? tc.trim().split("\n").filter(Boolean).length : 0 } as LsDetails;
+			return result;
+		}),
+
+		renderCall(args: any, theme: ThemeLike, ctx: RenderCtxLike) {
+			resolveBaseBackground(theme);
+			
+			const text = ctx.lastComponent ?? new TC("", 0, 0);
+			const p = String(args.path ?? ".");
+			text.setText(fillToolBackground(`\n  ${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", p)}`, ctx.isError ? BG_ERROR : undefined));
+			return text;
+		},
+
+		renderResult(result: Result, _opt: unknown, theme: ThemeLike, ctx: RenderCtxLike) {
+			resolveBaseBackground(theme);
+			
+			const text = ctx.lastComponent ?? new TC("", 0, 0);
+			if (ctx.isError) { text.setText(renderToolError(getText(result) || "Error", theme)); return text; }
+			const d = result.details as LsDetails | undefined;
+			if (d?._type === "lsResult" && d.text) {
+				const rendered = renderTree(d.text, d.path).split("\n").map(l => `  ${l}`).join("\n");
+				text.setText(fillToolBackground(`  ${FG_DIM}${d.entryCount} entries${RST}${renderToolMetrics(result)}\n${rendered}`));
+				return text;
+			}
+			const fc = result.content?.[0];
+			text.setText(fillToolBackground(`  ${theme.fg("dim", fc && "text" in fc ? String(fc.text).slice(0, 120) : "done")}`));
+			return text;
+		},
+	} as unknown as ToolDefinition<any, any, any>);
+}
+
+function getText(result: Result): string {
+	return ((result.content ?? []) as TextContent[]).filter((c) => c.type === "text").map((c) => c.text).join("\n") ?? "";
+}

package/src/tools/metrics.ts

@@ -0,0 +1,40 @@
+/**
+ * pi-pretty: tool metrics wrapper — elapsed time + output size.
+ *
+ * Wraps execute functions to record performance metadata in result.details.
+ */
+
+import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ELAPSED_KEY, CHARS_KEY } from "../helpers.js";
+
+type ExecuteFn = (
+	tid: string,
+	params: any,
+	sig: AbortSignal | undefined,
+	_upd: unknown,
+	ctx: ExtensionContext,
+) => Promise<AgentToolResult<Record<string, unknown>>>;
+
+export function wrapExecuteWithMetrics(execute: ExecuteFn): ExecuteFn {
+	return async (tid, params, sig, upd, ctx) => {
+		const start = performance.now();
+		const result = await execute(tid, params, sig, upd, ctx);
+		const elapsedMs = performance.now() - start;
+		const details = (result.details ?? {}) as Record<string, unknown>;
+		details[ELAPSED_KEY] = elapsedMs;
+		details[CHARS_KEY] = getOutputCharCount(result);
+		(result as { details: Record<string, unknown> }).details = details;
+		return result;
+	};
+}
+
+function getOutputCharCount(result: AgentToolResult<unknown>): number {
+	const content = result.content;
+	if (!Array.isArray(content)) return 0;
+	let length = 0;
+	for (const block of content) {
+		if (block.type !== "text") continue;
+		length += String(block.text ?? "").replace(/\r/g, "").length;
+	}
+	return length;
+}

package/src/tools/multi-grep.ts

@@ -0,0 +1,171 @@
+/* pi-pretty: multi_grep tool -- FFF-backed multi-pattern search with ripgrep/SDK fallback. */
+
+import { type ToolDefinition, type ExtensionAPI, type ExtensionContext, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { SdkToolDef, GrepDetails, FffServiceWithCursor, TextContent, ComponentLike, ThemeLike, RenderCtxLike } from "../types.js";
+import { resolveBaseBackground, MAX_PREVIEW_LINES, BG_BASE, BG_ERROR, FG_DIM, RST } from "../config.js";
+import { shortPath, normalizeLineEndings } from "../helpers.js";
+import { wrapExecuteWithMetrics } from "./metrics.js";
+import { renderToolError, renderToolMetrics, fillToolBackground } from "../render.js";
+import { fffFormatGrepText } from "../fff-helpers.js";
+import { parseMultiGrepConstraints } from "../multi-grep-fallback.js";
+import type { MultiGrepFallback } from "../types.js";
+
+type Result = AgentToolResult<Record<string, unknown>>;
+
+const noopFallback: MultiGrepFallback = async () => ({ text: "", matchCount: 0, limitReached: false });
+
+export function registerMultiGrepTool(
+	pi: ExtensionAPI,
+	cwd: string,
+	fffService: FffServiceWithCursor | null | undefined,
+	sdkGrepTool?: SdkToolDef,
+	ripgrepFallback: MultiGrepFallback = noopFallback,
+	TextComp?: new (t?: string, x?: number, y?: number) => { setText(v: string): void },
+): void {
+	const TC = TextComp ?? (() => {
+		const { Text } = require("@earendil-works/pi-tui") as { Text: new (t?: string, x?: number, y?: number) => { setText(v: string): void } };
+		return Text;
+	})();
+	const home = process.env.HOME ?? "";
+
+	pi.registerTool({
+		name: "multi_grep",
+		label: "Multi Grep",
+		description: "Search file contents using multiple patterns (OR logic)",
+	parameters: Type.Object({
+			patterns: Type.Array(Type.String()),
+			path: Type.Optional(Type.String()),
+			constraints: Type.Optional(Type.String()),
+			context: Type.Optional(Type.Number()),
+			limit: Type.Optional(Type.Number()),
+		}),
+		renderShell: "self",
+
+		execute: wrapExecuteWithMetrics(async (tid, params, sig, _upd, ctx: ExtensionContext) => {
+			const p = params as any;
+			const patterns = Array.isArray(p.patterns) ? p.patterns.map(String) : [String(p.patterns ?? "")];
+
+			// Guard: empty patterns
+			if (!patterns.length || (patterns.length === 1 && !patterns[0])) {
+				return { content: [{ text: "patterns array must have at least 1 element", type: "text" as const }], details: { _type: "grepResult" } as GrepDetails };
+			}
+
+			// Guard: aborted signal
+			if (sig?.aborted) {
+				return { content: [{ text: "Aborted", type: "text" as const }], details: { _type: "grepResult" } as GrepDetails };
+			}
+			const constraintsStr = p.constraints ? String(p.constraints) : undefined;
+			const context = typeof p.context === "number" ? p.context : undefined;
+			const effectiveLimit = typeof p.limit === "number" ? p.limit : 200;
+			const alternationPattern = patterns.length === 1 ? patterns[0] : patterns.join("|");
+
+			const hasNativeConstraints = Boolean(constraintsStr);
+			const parsedConstraints = constraintsStr ? parseMultiGrepConstraints(constraintsStr) : null;
+			const requestedConstraints = parsedConstraints?.ok ? constraintsStr : undefined;
+			let effectivePath = p.path ? String(p.path) : undefined;
+			const requestedPath = parsedConstraints?.ok ? parsedConstraints.tokens[0] : undefined;
+			if (requestedPath && !effectivePath) effectivePath = requestedPath;
+
+			// 1. FFF multiGrep (no constraints AND no path)
+			if (fffService?.isAvailable && !hasNativeConstraints && !effectivePath) {
+				try {
+					const fff = fffService.getFinder();
+					if (!fff) throw new Error("FFF finder not available");
+					const grepResult = fff.multiGrep({
+						patterns,
+						pageSize: effectiveLimit,
+						smartCase: !shouldIgnoreCase(patterns),
+						beforeContext: context ?? 0,
+						afterContext: context ?? 0,
+					});
+					if (grepResult.ok) {
+						const grep = grepResult.value;
+						const items = grep.items.slice(0, effectiveLimit);
+						const cursorStore = fffService.getCursorStore();
+						const notices: string[] = [];
+						if (fffService.partialIndex) notices.push("Warning: partial file index");
+						if (items.length >= effectiveLimit) notices.push(`${effectiveLimit} limit reached`);
+						if (grep.nextCursor) {
+							const cursorId = cursorStore.store(grep.nextCursor);
+							notices.push(`More results available: cursor="${cursorId}"`);
+						}
+						const text = appendNotices(fffFormatGrepText(items, effectiveLimit), notices);
+						return { content: [{ type: "text" as const, text }], details: { _type: "grepResult", text, pattern: alternationPattern, matchCount: items.length } as GrepDetails };
+					}
+					// FFF failure -> return error directly
+					return { content: [{ type: "text" as const, text: grepResult.error || "multi_grep failed" }], details: { _type: "grepResult", text: "", pattern: alternationPattern, matchCount: 0 } as GrepDetails };
+				} catch { /* fall through */ }
+			}
+
+			// 2. Ripgrep fallback
+			if (requestedConstraints || !sdkGrepTool) {
+				try {
+					const pathBacked = Boolean(requestedConstraints && requestedPath && !Boolean(p.path) && !requestedConstraints.includes("*") && !requestedConstraints.includes("?"));
+			const constraintsForRg = pathBacked ? undefined : requestedConstraints;
+					const notices: string[] = [];
+					if (!fffService?.isAvailable) notices.push("FFF unavailable, used ripgrep fallback");
+					else if (hasNativeConstraints) notices.push("Used ripgrep fallback for constrained search");
+					else notices.push("Used ripgrep fallback");
+
+					const rgResult = await ripgrepFallback({
+						cwd, patterns, path: effectivePath, constraints: constraintsForRg,
+						ignoreCase: shouldIgnoreCase(patterns), context, limit: effectiveLimit, signal: sig,
+					});
+					const text = normalizeLineEndings(rgResult.text) || "No matches found";
+					if (rgResult.limitReached) notices.push(`${effectiveLimit} limit reached`);
+					return { content: [{ type: "text" as const, text: appendNotices(text, notices) }], details: { _type: "grepResult", text, pattern: alternationPattern, matchCount: rgResult.matchCount } as GrepDetails };
+				} catch (error: unknown) {
+					return { content: [{ type: "text" as const, text: `multi_grep error: ${error instanceof Error ? error.message : String(error)}` }], details: { _type: "grepResult", text: "", pattern: alternationPattern, matchCount: 0 } as GrepDetails };
+				}
+			}
+
+			// 3. SDK grep fallback
+			try {
+				const notices: string[] = [];
+				if (!fffService?.isAvailable) notices.push("FFF unavailable, used SDK grep fallback");
+				const result = await sdkGrepTool.execute(tid, { pattern: alternationPattern, path: effectivePath, ignoreCase: shouldIgnoreCase(patterns), context, limit: effectiveLimit }, sig, null, ctx) as Result;
+				const tc = getText(result);
+				result.content = [{ type: "text" as const, text: appendNotices(tc, notices) }];
+				result.details = { _type: "grepResult", text: tc, pattern: alternationPattern, matchCount: tc ? tc.trim().split("\n").filter(Boolean).length : 0 } as GrepDetails;
+				return result;
+			} catch (error: unknown) {
+				return { content: [{ type: "text" as const, text: `multi_grep error: ${error instanceof Error ? error.message : String(error)}` }], details: { _type: "grepResult", text: "", pattern: alternationPattern, matchCount: 0 } as GrepDetails };
+			}
+		}),
+
+		renderCall(args: any, theme: ThemeLike, ctx: RenderCtxLike) {
+			resolveBaseBackground(theme);
+			
+			const text = ctx.lastComponent ?? new TC("", 0, 0);
+			const pats = (Array.isArray(args.patterns) ? args.patterns.map(String) : [String(args.patterns ?? "")]);
+			const label = pats.length > 2 ? `${pats[0]}, ${pats[1]}, +${pats.length - 2}` : pats.join(", ");
+			const p = args.path ? ` ${theme.fg("muted", `in ${shortPath(cwd, home, String(args.path))}`)}` : "";
+			text.setText(fillToolBackground(`\n  ${theme.fg("toolTitle", theme.bold("mgrep"))} ${theme.fg("accent", label)}${p}`, ctx.isError ? BG_ERROR : undefined));
+			return text;
+		},
+
+		renderResult(result: Result, _opt: unknown, theme: ThemeLike, ctx: RenderCtxLike) {
+			resolveBaseBackground(theme);
+			
+			const text = ctx.lastComponent ?? new TC("", 0, 0);
+			if (ctx.isError) { text.setText(renderToolError(getText(result) || "Error", theme)); return text; }
+			const d = result.details as GrepDetails | undefined;
+			if (d?._type === "grepResult" && d.text) {
+				const lines = d.text.split("\n");
+				const maxShow = ctx.expanded ? lines.length : Math.min(lines.length, MAX_PREVIEW_LINES);
+				const preview = lines.slice(0, maxShow).map(l => `  ${l}`).join("\n");
+				const more = lines.length > maxShow ? `\n${FG_DIM}  ... ${lines.length - maxShow} more lines${RST}` : "";
+				text.setText(fillToolBackground(`  ${FG_DIM}${d.matchCount} matches${RST}${renderToolMetrics(result)}\n${preview}${more}`));
+				return text;
+			}
+			const fc = result.content?.[0];
+			text.setText(fillToolBackground(`  ${theme.fg("dim", fc && "text" in fc ? String(fc.text).slice(0, 120) : "no matches")}`));
+			return text;
+		},
+	} as unknown as ToolDefinition<any, any, any>);
+}
+
+function shouldIgnoreCase(patterns: string[]): boolean { return !patterns.some((p) => /[A-Z]/.test(p)); }
+function appendNotices(text: string, notices: string[]): string { return notices.length ? `${text}\n\n[${notices.join(". ")}]` : text; }
+function getText(result: Result): string { return ((result.content ?? []) as TextContent[]).filter((c) => c.type === "text").map((c) => c.text).join("\n") ?? ""; }

package/src/tools/read.ts

@@ -0,0 +1,112 @@
+/* pi-pretty: read tool -- file reading with syntax highlighting and inline image support. */
+
+import { type ToolDefinition, type ExtensionAPI, type ExtensionContext, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { SdkToolDef, ReadDetails, TextContent, ComponentLike, ThemeLike, RenderCtxLike } from "../types.js";
+import { resolveBaseBackground, termWidth, MAX_PREVIEW_LINES, BG_BASE, BG_ERROR, FG_DIM, RST } from "../config.js";
+import { shortPath, normalizeLineEndings } from "../helpers.js";
+import { wrapExecuteWithMetrics } from "./metrics.js";
+import { renderFindResults, renderToolError, renderToolMetrics, fillToolBackground } from "../render.js";
+
+// Simple terminal image support check
+function isImageTerminal(): boolean {
+	const term = (process.env.TERM_PROGRAM ?? process.env.TERM ?? "").toLowerCase();
+	const proto = (process.env.PRETTY_IMAGE_PROTOCOL ?? "").toLowerCase();
+	if (proto === "kitty" || proto === "iterm2") return true;
+	if (proto === "none") return false;
+	return ["ghostty", "kitty", "iterm.app", "wezterm", "mintty"].some((t) => term.includes(t)) || process.env.LC_TERMINAL === "iTerm2";
+}
+
+type Result = AgentToolResult<Record<string, unknown>>;
+
+export function registerReadTool(
+	pi: ExtensionAPI,
+	cwd: string,
+	_fffService: unknown,
+	sdkTool: SdkToolDef,
+	TextComp?: new (t?: string, x?: number, y?: number) => { setText(v: string): void },
+): void {
+	const TC = TextComp ?? (() => {
+		const { Text } = require("@earendil-works/pi-tui") as { Text: new (t?: string, x?: number, y?: number) => { setText(v: string): void } };
+		return Text;
+	})();
+	const home = process.env.HOME ?? "";
+
+	pi.registerTool({
+		name: "read",
+		label: "Read",
+		description: sdkTool.description ?? "Read file contents",
+		parameters: sdkTool.parameters,
+		renderShell: "self",
+
+		execute: wrapExecuteWithMetrics(async (tid, params, sig, _upd, ctx: ExtensionContext) => {
+			const p = params as any;
+			const result = await sdkTool.execute(tid, p, sig, undefined, ctx) as Result;
+
+			const imageBlock = (result.content as any[])?.find((c: any) => c.type === "image");
+			if (imageBlock) {
+				result.details = { _type: "readImage", filePath: String(p.path ?? ""), data: imageBlock.data, mimeType: imageBlock.mimeType ?? "image/png" } as ReadDetails;
+				return result;
+			}
+
+			const tc = normalizeLineEndings(getText(result));
+			result.details = { _type: "readFile", filePath: String(p.path ?? ""), content: tc, offset: typeof p.offset === "number" ? p.offset : 0, lineCount: tc ? tc.split("\n").length : 0 } as ReadDetails;
+			return result;
+		}),
+
+		renderCall(args: any, theme: ThemeLike, ctx: RenderCtxLike) {
+			resolveBaseBackground(theme);
+			
+			const text = ctx.lastComponent ?? new TC("", 0, 0);
+			const p = shortPath(cwd, home, String(args.path ?? ""));
+			const off = typeof args.offset === "number" ? `:${args.offset}` : "";
+			text.setText(fillToolBackground(`\n  ${theme.fg("toolTitle", theme.bold("read"))} ${theme.fg("accent", p)}${theme.fg("dim", off)}`, ctx.isError ? BG_ERROR : undefined));
+			return text;
+		},
+
+		renderResult(result: Result, _opt: unknown, theme: ThemeLike, ctx: RenderCtxLike) {
+			resolveBaseBackground(theme);
+			
+			const text = ctx.lastComponent ?? new TC("", 0, 0);
+
+			if (ctx.isError) { text.setText(renderToolError(getText(result) || "Error", theme)); return text; }
+
+			const d = result.details as ReadDetails | undefined;
+
+			// Image rendering
+			if (d?._type === "readImage") {
+				if ((ctx as any).showImages && isImageTerminal()) {
+					try {
+						const T = require("@earendil-works/pi-tui").Text as new (t?: string, x?: number, y?: number) => ComponentLike;
+						const img = new T("", 0, 0);
+						if (d.mimeType.startsWith("image/svg")) {
+							img.setText(d.data);
+						} else {
+							const pngData = (require("@earendil-works/pi-coding-agent") as any).convertToPng?.(d.data) ?? d.data;
+							img.setText(`\x1b_Ga=T,f=100,m=${d.mimeType === "image/png" ? "1" : "0"};${pngData}\x1b\\\\`);
+						}
+						return img;
+					} catch { /* fall through */ }
+				}
+				const fc = result.content?.[0];
+				text.setText(fillToolBackground(`  ${theme.fg("dim", fc && "text" in fc ? String(fc.text).slice(0, 80) : `[image: ${d.filePath}]`)}`));
+				return text;
+			}
+
+			// File content
+			if (d?._type === "readFile" && d.content) {
+				const rendered = renderFindResults(d.content).split("\n").map(l => `  ${l}`).join("\n");
+				text.setText(fillToolBackground(rendered));
+				(ctx as any).state._rt = rendered;
+				return text;
+			}
+
+			const fc = result.content?.[0];
+			text.setText(fillToolBackground(`  ${theme.fg("dim", fc && "text" in fc ? String(fc.text).slice(0, 120) : "done")}`));
+			return text;
+		},
+	} as unknown as ToolDefinition<any, any, any>);
+}
+
+function getText(result: Result): string {
+	return ((result.content ?? []) as TextContent[]).filter((c) => c.type === "text").map((c) => c.text).join("\n") ?? "";
+}