@lenylvt/pi-coding-agent 0.64.0

package/src/core/tools/ls.ts

@@ -0,0 +1,233 @@
+import type { AgentTool } from "@lenylvt/pi-agent-core";
+import { Text } from "@lenylvt/pi-tui";
+import { type Static, Type } from "@sinclair/typebox";
+import { existsSync, readdirSync, statSync } from "fs";
+import nodePath from "path";
+import { keyHint } from "../../modes/interactive/components/keybinding-hints.js";
+import type { ToolDefinition, ToolRenderResultOptions } from "../extensions/types.js";
+import { resolveToCwd } from "./path-utils.js";
+import { getTextOutput, invalidArgText, shortenPath, str } from "./render-utils.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+import { DEFAULT_MAX_BYTES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
+
+const lsSchema = Type.Object({
+	path: Type.Optional(Type.String({ description: "Directory to list (default: current directory)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of entries to return (default: 500)" })),
+});
+
+export type LsToolInput = Static<typeof lsSchema>;
+
+const DEFAULT_LIMIT = 500;
+
+export interface LsToolDetails {
+	truncation?: TruncationResult;
+	entryLimitReached?: number;
+}
+
+/**
+ * Pluggable operations for the ls tool.
+ * Override these to delegate directory listing to remote systems (for example SSH).
+ */
+export interface LsOperations {
+	/** Check if path exists */
+	exists: (absolutePath: string) => Promise<boolean> | boolean;
+	/** Get file or directory stats. Throws if not found. */
+	stat: (absolutePath: string) => Promise<{ isDirectory: () => boolean }> | { isDirectory: () => boolean };
+	/** Read directory entries */
+	readdir: (absolutePath: string) => Promise<string[]> | string[];
+}
+
+const defaultLsOperations: LsOperations = {
+	exists: existsSync,
+	stat: statSync,
+	readdir: readdirSync,
+};
+
+export interface LsToolOptions {
+	/** Custom operations for directory listing. Default: local filesystem */
+	operations?: LsOperations;
+}
+
+function formatLsCall(
+	args: { path?: string; limit?: number } | undefined,
+	theme: typeof import("../../modes/interactive/theme/theme.js").theme,
+): string {
+	const rawPath = str(args?.path);
+	const path = rawPath !== null ? shortenPath(rawPath || ".") : null;
+	const limit = args?.limit;
+	const invalidArg = invalidArgText(theme);
+	let text = `${theme.fg("toolTitle", theme.bold("ls"))} ${path === null ? invalidArg : theme.fg("accent", path)}`;
+	if (limit !== undefined) {
+		text += theme.fg("toolOutput", ` (limit ${limit})`);
+	}
+	return text;
+}
+
+function formatLsResult(
+	result: {
+		content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+		details?: LsToolDetails;
+	},
+	options: ToolRenderResultOptions,
+	theme: typeof import("../../modes/interactive/theme/theme.js").theme,
+	showImages: boolean,
+): string {
+	const output = getTextOutput(result, showImages).trim();
+	let text = "";
+	if (output) {
+		const lines = output.split("\n");
+		const maxLines = options.expanded ? lines.length : 20;
+		const displayLines = lines.slice(0, maxLines);
+		const remaining = lines.length - maxLines;
+		text += `\n${displayLines.map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+		if (remaining > 0) {
+			text += `${theme.fg("muted", `\n... (${remaining} more lines,`)} ${keyHint("app.tools.expand", "to expand")})`;
+		}
+	}
+
+	const entryLimit = result.details?.entryLimitReached;
+	const truncation = result.details?.truncation;
+	if (entryLimit || truncation?.truncated) {
+		const warnings: string[] = [];
+		if (entryLimit) warnings.push(`${entryLimit} entries limit`);
+		if (truncation?.truncated) warnings.push(`${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit`);
+		text += `\n${theme.fg("warning", `[Truncated: ${warnings.join(", ")}]`)}`;
+	}
+	return text;
+}
+
+export function createLsToolDefinition(
+	cwd: string,
+	options?: LsToolOptions,
+): ToolDefinition<typeof lsSchema, LsToolDetails | undefined> {
+	const ops = options?.operations ?? defaultLsOperations;
+	return {
+		name: "ls",
+		label: "ls",
+		description: `List directory contents. Returns entries sorted alphabetically, with '/' suffix for directories. Includes dotfiles. Output is truncated to ${DEFAULT_LIMIT} entries or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,
+		promptSnippet: "List directory contents",
+		parameters: lsSchema,
+		async execute(
+			_toolCallId,
+			{ path, limit }: { path?: string; limit?: number },
+			signal?: AbortSignal,
+			_onUpdate?,
+			_ctx?,
+		) {
+			return new Promise((resolve, reject) => {
+				if (signal?.aborted) {
+					reject(new Error("Operation aborted"));
+					return;
+				}
+
+				const onAbort = () => reject(new Error("Operation aborted"));
+				signal?.addEventListener("abort", onAbort, { once: true });
+
+				(async () => {
+					try {
+						const dirPath = resolveToCwd(path || ".", cwd);
+						const effectiveLimit = limit ?? DEFAULT_LIMIT;
+
+						// Check if path exists.
+						if (!(await ops.exists(dirPath))) {
+							reject(new Error(`Path not found: ${dirPath}`));
+							return;
+						}
+
+						// Check if path is a directory.
+						const stat = await ops.stat(dirPath);
+						if (!stat.isDirectory()) {
+							reject(new Error(`Not a directory: ${dirPath}`));
+							return;
+						}
+
+						// Read directory entries.
+						let entries: string[];
+						try {
+							entries = await ops.readdir(dirPath);
+						} catch (e: any) {
+							reject(new Error(`Cannot read directory: ${e.message}`));
+							return;
+						}
+
+						// Sort alphabetically, case-insensitive.
+						entries.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+
+						// Format entries with directory indicators.
+						const results: string[] = [];
+						let entryLimitReached = false;
+						for (const entry of entries) {
+							if (results.length >= effectiveLimit) {
+								entryLimitReached = true;
+								break;
+							}
+
+							const fullPath = nodePath.join(dirPath, entry);
+							let suffix = "";
+							try {
+								const entryStat = await ops.stat(fullPath);
+								if (entryStat.isDirectory()) suffix = "/";
+							} catch {
+								// Skip entries we cannot stat.
+								continue;
+							}
+							results.push(entry + suffix);
+						}
+
+						signal?.removeEventListener("abort", onAbort);
+
+						if (results.length === 0) {
+							resolve({ content: [{ type: "text", text: "(empty directory)" }], details: undefined });
+							return;
+						}
+
+						const rawOutput = results.join("\n");
+						// Apply byte truncation. There is no separate line limit because entry count is already capped.
+						const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+						let output = truncation.content;
+						const details: LsToolDetails = {};
+						// Build actionable notices for truncation and entry limits.
+						const notices: string[] = [];
+						if (entryLimitReached) {
+							notices.push(`${effectiveLimit} entries limit reached. Use limit=${effectiveLimit * 2} for more`);
+							details.entryLimitReached = effectiveLimit;
+						}
+						if (truncation.truncated) {
+							notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+							details.truncation = truncation;
+						}
+						if (notices.length > 0) {
+							output += `\n\n[${notices.join(". ")}]`;
+						}
+
+						resolve({
+							content: [{ type: "text", text: output }],
+							details: Object.keys(details).length > 0 ? details : undefined,
+						});
+					} catch (e: any) {
+						signal?.removeEventListener("abort", onAbort);
+						reject(e);
+					}
+				})();
+			});
+		},
+		renderCall(args, theme, context) {
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			text.setText(formatLsCall(args, theme));
+			return text;
+		},
+		renderResult(result, options, theme, context) {
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			text.setText(formatLsResult(result as any, options, theme, context.showImages));
+			return text;
+		},
+	};
+}
+
+export function createLsTool(cwd: string, options?: LsToolOptions): AgentTool<typeof lsSchema> {
+	return wrapToolDefinition(createLsToolDefinition(cwd, options));
+}
+
+/** Default ls tool using process.cwd() for backwards compatibility. */
+export const lsToolDefinition = createLsToolDefinition(process.cwd());
+export const lsTool = createLsTool(process.cwd());

package/src/core/tools/path-utils.ts

@@ -0,0 +1,94 @@
+import { accessSync, constants } from "node:fs";
+import * as os from "node:os";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+const NARROW_NO_BREAK_SPACE = "\u202F";
+function normalizeUnicodeSpaces(str: string): string {
+	return str.replace(UNICODE_SPACES, " ");
+}
+
+function tryMacOSScreenshotPath(filePath: string): string {
+	return filePath.replace(/ (AM|PM)\./g, `${NARROW_NO_BREAK_SPACE}$1.`);
+}
+
+function tryNFDVariant(filePath: string): string {
+	// macOS stores filenames in NFD (decomposed) form, try converting user input to NFD
+	return filePath.normalize("NFD");
+}
+
+function tryCurlyQuoteVariant(filePath: string): string {
+	// macOS uses U+2019 (right single quotation mark) in screenshot names like "Capture d'écran"
+	// Users typically type U+0027 (straight apostrophe)
+	return filePath.replace(/'/g, "\u2019");
+}
+
+function fileExists(filePath: string): boolean {
+	try {
+		accessSync(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function normalizeAtPrefix(filePath: string): string {
+	return filePath.startsWith("@") ? filePath.slice(1) : filePath;
+}
+
+export function expandPath(filePath: string): string {
+	const normalized = normalizeUnicodeSpaces(normalizeAtPrefix(filePath));
+	if (normalized === "~") {
+		return os.homedir();
+	}
+	if (normalized.startsWith("~/")) {
+		return os.homedir() + normalized.slice(1);
+	}
+	return normalized;
+}
+
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export function resolveToCwd(filePath: string, cwd: string): string {
+	const expanded = expandPath(filePath);
+	if (isAbsolute(expanded)) {
+		return expanded;
+	}
+	return resolvePath(cwd, expanded);
+}
+
+export function resolveReadPath(filePath: string, cwd: string): string {
+	const resolved = resolveToCwd(filePath, cwd);
+
+	if (fileExists(resolved)) {
+		return resolved;
+	}
+
+	// Try macOS AM/PM variant (narrow no-break space before AM/PM)
+	const amPmVariant = tryMacOSScreenshotPath(resolved);
+	if (amPmVariant !== resolved && fileExists(amPmVariant)) {
+		return amPmVariant;
+	}
+
+	// Try NFD variant (macOS stores filenames in NFD form)
+	const nfdVariant = tryNFDVariant(resolved);
+	if (nfdVariant !== resolved && fileExists(nfdVariant)) {
+		return nfdVariant;
+	}
+
+	// Try curly quote variant (macOS uses U+2019 in screenshot names)
+	const curlyVariant = tryCurlyQuoteVariant(resolved);
+	if (curlyVariant !== resolved && fileExists(curlyVariant)) {
+		return curlyVariant;
+	}
+
+	// Try combined NFD + curly quote (for French macOS screenshots like "Capture d'écran")
+	const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+	if (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {
+		return nfdCurlyVariant;
+	}
+
+	return resolved;
+}

package/src/core/tools/read.ts

@@ -0,0 +1,269 @@
+import type { AgentTool } from "@lenylvt/pi-agent-core";
+import type { ImageContent, TextContent } from "@lenylvt/pi-ai";
+import { Text } from "@lenylvt/pi-tui";
+import { type Static, Type } from "@sinclair/typebox";
+import { constants } from "fs";
+import { access as fsAccess, readFile as fsReadFile } from "fs/promises";
+import { keyHint } from "../../modes/interactive/components/keybinding-hints.js";
+import { getLanguageFromPath, highlightCode } from "../../modes/interactive/theme/theme.js";
+import { formatDimensionNote, resizeImage } from "../../utils/image-resize.js";
+import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
+import type { ToolDefinition, ToolRenderResultOptions } from "../extensions/types.js";
+import { resolveReadPath } from "./path-utils.js";
+import { getTextOutput, invalidArgText, replaceTabs, shortenPath, str } from "./render-utils.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
+
+const readSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+	offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+});
+
+export type ReadToolInput = Static<typeof readSchema>;
+
+export interface ReadToolDetails {
+	truncation?: TruncationResult;
+}
+
+/**
+ * Pluggable operations for the read tool.
+ * Override these to delegate file reading to remote systems (for example SSH).
+ */
+export interface ReadOperations {
+	/** Read file contents as a Buffer */
+	readFile: (absolutePath: string) => Promise<Buffer>;
+	/** Check if file is readable (throw if not) */
+	access: (absolutePath: string) => Promise<void>;
+	/** Detect image MIME type, return null or undefined for non-images */
+	detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+}
+
+const defaultReadOperations: ReadOperations = {
+	readFile: (path) => fsReadFile(path),
+	access: (path) => fsAccess(path, constants.R_OK),
+	detectImageMimeType: detectSupportedImageMimeTypeFromFile,
+};
+
+export interface ReadToolOptions {
+	/** Whether to auto-resize images to 2000x2000 max. Default: true */
+	autoResizeImages?: boolean;
+	/** Custom operations for file reading. Default: local filesystem */
+	operations?: ReadOperations;
+}
+
+function formatReadCall(
+	args: { path?: string; file_path?: string; offset?: number; limit?: number } | undefined,
+	theme: typeof import("../../modes/interactive/theme/theme.js").theme,
+): string {
+	const rawPath = str(args?.file_path ?? args?.path);
+	const path = rawPath !== null ? shortenPath(rawPath) : null;
+	const offset = args?.offset;
+	const limit = args?.limit;
+	const invalidArg = invalidArgText(theme);
+	let pathDisplay = path === null ? invalidArg : path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+	if (offset !== undefined || limit !== undefined) {
+		const startLine = offset ?? 1;
+		const endLine = limit !== undefined ? startLine + limit - 1 : "";
+		pathDisplay += theme.fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+	}
+	return `${theme.fg("toolTitle", theme.bold("read"))} ${pathDisplay}`;
+}
+
+function trimTrailingEmptyLines(lines: string[]): string[] {
+	let end = lines.length;
+	while (end > 0 && lines[end - 1] === "") {
+		end--;
+	}
+	return lines.slice(0, end);
+}
+
+function formatReadResult(
+	args: { path?: string; file_path?: string; offset?: number; limit?: number } | undefined,
+	result: { content: (TextContent | ImageContent)[]; details?: ReadToolDetails },
+	options: ToolRenderResultOptions,
+	theme: typeof import("../../modes/interactive/theme/theme.js").theme,
+	showImages: boolean,
+): string {
+	const rawPath = str(args?.file_path ?? args?.path);
+	const output = getTextOutput(result as any, showImages);
+	const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
+	const renderedLines = lang ? highlightCode(replaceTabs(output), lang) : output.split("\n");
+	const lines = trimTrailingEmptyLines(renderedLines);
+	const maxLines = options.expanded ? lines.length : 10;
+	const displayLines = lines.slice(0, maxLines);
+	const remaining = lines.length - maxLines;
+	let text = `\n${displayLines.map((line) => (lang ? replaceTabs(line) : theme.fg("toolOutput", replaceTabs(line)))).join("\n")}`;
+	if (remaining > 0) {
+		text += `${theme.fg("muted", `\n... (${remaining} more lines,`)} ${keyHint("app.tools.expand", "to expand")})`;
+	}
+
+	const truncation = result.details?.truncation;
+	if (truncation?.truncated) {
+		if (truncation.firstLineExceedsLimit) {
+			text += `\n${theme.fg("warning", `[First line exceeds ${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit]`)}`;
+		} else if (truncation.truncatedBy === "lines") {
+			text += `\n${theme.fg("warning", `[Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${truncation.maxLines ?? DEFAULT_MAX_LINES} line limit)]`)}`;
+		} else {
+			text += `\n${theme.fg("warning", `[Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)]`)}`;
+		}
+	}
+	return text;
+}
+
+export function createReadToolDefinition(
+	cwd: string,
+	options?: ReadToolOptions,
+): ToolDefinition<typeof readSchema, ReadToolDetails | undefined> {
+	const autoResizeImages = options?.autoResizeImages ?? true;
+	const ops = options?.operations ?? defaultReadOperations;
+	return {
+		name: "read",
+		label: "read",
+		description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,
+		promptSnippet: "Read file contents",
+		promptGuidelines: ["Use read to examine files instead of cat or sed."],
+		parameters: readSchema,
+		async execute(
+			_toolCallId,
+			{ path, offset, limit }: { path: string; offset?: number; limit?: number },
+			signal?: AbortSignal,
+			_onUpdate?,
+			_ctx?,
+		) {
+			const absolutePath = resolveReadPath(path, cwd);
+			return new Promise<{ content: (TextContent | ImageContent)[]; details: ReadToolDetails | undefined }>(
+				(resolve, reject) => {
+					if (signal?.aborted) {
+						reject(new Error("Operation aborted"));
+						return;
+					}
+					let aborted = false;
+					const onAbort = () => {
+						aborted = true;
+						reject(new Error("Operation aborted"));
+					};
+					signal?.addEventListener("abort", onAbort, { once: true });
+
+					(async () => {
+						try {
+							// Check if file exists and is readable.
+							await ops.access(absolutePath);
+							if (aborted) return;
+							const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(absolutePath) : undefined;
+							let content: (TextContent | ImageContent)[];
+							let details: ReadToolDetails | undefined;
+							if (mimeType) {
+								// Read image as binary.
+								const buffer = await ops.readFile(absolutePath);
+								const base64 = buffer.toString("base64");
+								if (autoResizeImages) {
+									// Resize image if needed before sending it back to the model.
+									const resized = await resizeImage({ type: "image", data: base64, mimeType });
+									if (!resized) {
+										content = [
+											{
+												type: "text",
+												text: `Read image file [${mimeType}]\n[Image omitted: could not be resized below the inline image size limit.]`,
+											},
+										];
+									} else {
+										const dimensionNote = formatDimensionNote(resized);
+										let textNote = `Read image file [${resized.mimeType}]`;
+										if (dimensionNote) textNote += `\n${dimensionNote}`;
+										content = [
+											{ type: "text", text: textNote },
+											{ type: "image", data: resized.data, mimeType: resized.mimeType },
+										];
+									}
+								} else {
+									content = [
+										{ type: "text", text: `Read image file [${mimeType}]` },
+										{ type: "image", data: base64, mimeType },
+									];
+								}
+							} else {
+								// Read text content.
+								const buffer = await ops.readFile(absolutePath);
+								const textContent = buffer.toString("utf-8");
+								const allLines = textContent.split("\n");
+								const totalFileLines = allLines.length;
+								// Apply offset if specified. Convert from 1-indexed input to 0-indexed array access.
+								const startLine = offset ? Math.max(0, offset - 1) : 0;
+								const startLineDisplay = startLine + 1;
+								// Check if offset is out of bounds.
+								if (startLine >= allLines.length) {
+									throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+								}
+								let selectedContent: string;
+								let userLimitedLines: number | undefined;
+								// If limit is specified by the user, honor it first. Otherwise truncateHead decides.
+								if (limit !== undefined) {
+									const endLine = Math.min(startLine + limit, allLines.length);
+									selectedContent = allLines.slice(startLine, endLine).join("\n");
+									userLimitedLines = endLine - startLine;
+								} else {
+									selectedContent = allLines.slice(startLine).join("\n");
+								}
+								// Apply truncation, respecting both line and byte limits.
+								const truncation = truncateHead(selectedContent);
+								let outputText: string;
+								if (truncation.firstLineExceedsLimit) {
+									// First line alone exceeds the byte limit. Point the model at a bash fallback.
+									const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
+									outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
+									details = { truncation };
+								} else if (truncation.truncated) {
+									// Truncation occurred. Build an actionable continuation notice.
+									const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+									const nextOffset = endLineDisplay + 1;
+									outputText = truncation.content;
+									if (truncation.truncatedBy === "lines") {
+										outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
+									} else {
+										outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
+									}
+									details = { truncation };
+								} else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
+									// User-specified limit stopped early, but the file still has more content.
+									const remaining = allLines.length - (startLine + userLimitedLines);
+									const nextOffset = startLine + userLimitedLines + 1;
+									outputText = `${truncation.content}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+								} else {
+									// No truncation and no remaining user-limited content.
+									outputText = truncation.content;
+								}
+								content = [{ type: "text", text: outputText }];
+							}
+
+							if (aborted) return;
+							signal?.removeEventListener("abort", onAbort);
+							resolve({ content, details });
+						} catch (error: any) {
+							signal?.removeEventListener("abort", onAbort);
+							if (!aborted) reject(error);
+						}
+					})();
+				},
+			);
+		},
+		renderCall(args, theme, context) {
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			text.setText(formatReadCall(args, theme));
+			return text;
+		},
+		renderResult(result, options, theme, context) {
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			text.setText(formatReadResult(context.args, result as any, options, theme, context.showImages));
+			return text;
+		},
+	};
+}
+
+export function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema> {
+	return wrapToolDefinition(createReadToolDefinition(cwd, options));
+}
+
+/** Default read tool using process.cwd() for backwards compatibility. */
+export const readToolDefinition = createReadToolDefinition(process.cwd());
+export const readTool = createReadTool(process.cwd());

package/src/core/tools/render-utils.ts

@@ -0,0 +1,64 @@
+import * as os from "node:os";
+import type { ImageContent, TextContent } from "@lenylvt/pi-ai";
+import { getCapabilities, getImageDimensions, imageFallback } from "@lenylvt/pi-tui";
+import stripAnsi from "strip-ansi";
+import { sanitizeBinaryOutput } from "../../utils/shell.js";
+
+export function shortenPath(path: unknown): string {
+	if (typeof path !== "string") return "";
+	const home = os.homedir();
+	if (path.startsWith(home)) {
+		return `~${path.slice(home.length)}`;
+	}
+	return path;
+}
+
+export function str(value: unknown): string | null {
+	if (typeof value === "string") return value;
+	if (value == null) return "";
+	return null;
+}
+
+export function replaceTabs(text: string): string {
+	return text.replace(/\t/g, "   ");
+}
+
+export function normalizeDisplayText(text: string): string {
+	return text.replace(/\r/g, "");
+}
+
+export function getTextOutput(
+	result: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> } | undefined,
+	showImages: boolean,
+): string {
+	if (!result) return "";
+
+	const textBlocks = result.content.filter((c) => c.type === "text");
+	const imageBlocks = result.content.filter((c) => c.type === "image");
+
+	let output = textBlocks.map((c) => sanitizeBinaryOutput(stripAnsi(c.text || "")).replace(/\r/g, "")).join("\n");
+
+	const caps = getCapabilities();
+	if (imageBlocks.length > 0 && (!caps.images || !showImages)) {
+		const imageIndicators = imageBlocks
+			.map((img) => {
+				const mimeType = img.mimeType ?? "image/unknown";
+				const dims =
+					img.data && img.mimeType ? (getImageDimensions(img.data, img.mimeType) ?? undefined) : undefined;
+				return imageFallback(mimeType, dims);
+			})
+			.join("\n");
+		output = output ? `${output}\n${imageIndicators}` : imageIndicators;
+	}
+
+	return output;
+}
+
+export type ToolRenderResultLike<TDetails> = {
+	content: (TextContent | ImageContent)[];
+	details: TDetails;
+};
+
+export function invalidArgText(theme: { fg: (name: any, text: string) => string }): string {
+	return theme.fg("error", "[invalid arg]");
+}