Reorganize file structure: core/, utils/, modes/interactive/components/, modes/interactive/theme/

packages/coding-agent/src/core/tools/bash.ts

@@ -0,0 +1,191 @@
+import { randomBytes } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentTool } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { spawn } from "child_process";
+import { getShellConfig, killProcessTree } from "../../utils/shell.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateTail } from "./truncate.js";
+
+/**
+ * Generate a unique temp file path for bash output
+ */
+function getTempFilePath(): string {
+	const id = randomBytes(8).toString("hex");
+	return join(tmpdir(), `pi-bash-${id}.log`);
+}
+
+const bashSchema = Type.Object({
+	command: Type.String({ description: "Bash command to execute" }),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
+});
+
+interface BashToolDetails {
+	truncation?: TruncationResult;
+	fullOutputPath?: string;
+}
+
+export const bashTool: AgentTool<typeof bashSchema> = {
+	name: "bash",
+	label: "bash",
+	description: `Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,
+	parameters: bashSchema,
+	execute: async (
+		_toolCallId: string,
+		{ command, timeout }: { command: string; timeout?: number },
+		signal?: AbortSignal,
+	) => {
+		return new Promise((resolve, reject) => {
+			const { shell, args } = getShellConfig();
+			const child = spawn(shell, [...args, command], {
+				detached: true,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+
+			// We'll stream to a temp file if output gets large
+			let tempFilePath: string | undefined;
+			let tempFileStream: ReturnType<typeof createWriteStream> | undefined;
+			let totalBytes = 0;
+
+			// Keep a rolling buffer of the last chunk for tail truncation
+			const chunks: Buffer[] = [];
+			let chunksBytes = 0;
+			// Keep more than we need so we have enough for truncation
+			const maxChunksBytes = DEFAULT_MAX_BYTES * 2;
+
+			let timedOut = false;
+
+			// Set timeout if provided
+			let timeoutHandle: NodeJS.Timeout | undefined;
+			if (timeout !== undefined && timeout > 0) {
+				timeoutHandle = setTimeout(() => {
+					timedOut = true;
+					onAbort();
+				}, timeout * 1000);
+			}
+
+			const handleData = (data: Buffer) => {
+				totalBytes += data.length;
+
+				// Start writing to temp file once we exceed the threshold
+				if (totalBytes > DEFAULT_MAX_BYTES && !tempFilePath) {
+					tempFilePath = getTempFilePath();
+					tempFileStream = createWriteStream(tempFilePath);
+					// Write all buffered chunks to the file
+					for (const chunk of chunks) {
+						tempFileStream.write(chunk);
+					}
+				}
+
+				// Write to temp file if we have one
+				if (tempFileStream) {
+					tempFileStream.write(data);
+				}
+
+				// Keep rolling buffer of recent data
+				chunks.push(data);
+				chunksBytes += data.length;
+
+				// Trim old chunks if buffer is too large
+				while (chunksBytes > maxChunksBytes && chunks.length > 1) {
+					const removed = chunks.shift()!;
+					chunksBytes -= removed.length;
+				}
+			};
+
+			// Collect stdout and stderr together
+			if (child.stdout) {
+				child.stdout.on("data", handleData);
+			}
+			if (child.stderr) {
+				child.stderr.on("data", handleData);
+			}
+
+			// Handle process exit
+			child.on("close", (code) => {
+				if (timeoutHandle) {
+					clearTimeout(timeoutHandle);
+				}
+				if (signal) {
+					signal.removeEventListener("abort", onAbort);
+				}
+
+				// Close temp file stream
+				if (tempFileStream) {
+					tempFileStream.end();
+				}
+
+				// Combine all buffered chunks
+				const fullBuffer = Buffer.concat(chunks);
+				const fullOutput = fullBuffer.toString("utf-8");
+
+				if (signal?.aborted) {
+					let output = fullOutput;
+					if (output) output += "\n\n";
+					output += "Command aborted";
+					reject(new Error(output));
+					return;
+				}
+
+				if (timedOut) {
+					let output = fullOutput;
+					if (output) output += "\n\n";
+					output += `Command timed out after ${timeout} seconds`;
+					reject(new Error(output));
+					return;
+				}
+
+				// Apply tail truncation
+				const truncation = truncateTail(fullOutput);
+				let outputText = truncation.content || "(no output)";
+
+				// Build details with truncation info
+				let details: BashToolDetails | undefined;
+
+				if (truncation.truncated) {
+					details = {
+						truncation,
+						fullOutputPath: tempFilePath,
+					};
+
+					// Build actionable notice
+					const startLine = truncation.totalLines - truncation.outputLines + 1;
+					const endLine = truncation.totalLines;
+
+					if (truncation.lastLinePartial) {
+						// Edge case: last line alone > 30KB
+						const lastLineSize = formatSize(Buffer.byteLength(fullOutput.split("\n").pop() || "", "utf-8"));
+						outputText += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). Full output: ${tempFilePath}]`;
+					} else if (truncation.truncatedBy === "lines") {
+						outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${tempFilePath}]`;
+					} else {
+						outputText += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${tempFilePath}]`;
+					}
+				}
+
+				if (code !== 0 && code !== null) {
+					outputText += `\n\nCommand exited with code ${code}`;
+					reject(new Error(outputText));
+				} else {
+					resolve({ content: [{ type: "text", text: outputText }], details });
+				}
+			});
+
+			// Handle abort signal - kill entire process tree
+			const onAbort = () => {
+				if (child.pid) {
+					killProcessTree(child.pid);
+				}
+			};
+
+			if (signal) {
+				if (signal.aborted) {
+					onAbort();
+				} else {
+					signal.addEventListener("abort", onAbort, { once: true });
+				}
+			}
+		});
+	},
+};

packages/coding-agent/src/core/tools/edit.ts

@@ -0,0 +1,270 @@
+import * as os from "node:os";
+import type { AgentTool } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import * as Diff from "diff";
+import { constants } from "fs";
+import { access, readFile, writeFile } from "fs/promises";
+import { resolve as resolvePath } from "path";
+
+/**
+ * Expand ~ to home directory
+ */
+function expandPath(filePath: string): string {
+	if (filePath === "~") {
+		return os.homedir();
+	}
+	if (filePath.startsWith("~/")) {
+		return os.homedir() + filePath.slice(1);
+	}
+	return filePath;
+}
+
+/**
+ * Generate a unified diff string with line numbers and context
+ */
+function generateDiffString(oldContent: string, newContent: string, contextLines = 4): string {
+	const parts = Diff.diffLines(oldContent, newContent);
+	const output: string[] = [];
+
+	const oldLines = oldContent.split("\n");
+	const newLines = newContent.split("\n");
+	const maxLineNum = Math.max(oldLines.length, newLines.length);
+	const lineNumWidth = String(maxLineNum).length;
+
+	let oldLineNum = 1;
+	let newLineNum = 1;
+	let lastWasChange = false;
+
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		const raw = part.value.split("\n");
+		if (raw[raw.length - 1] === "") {
+			raw.pop();
+		}
+
+		if (part.added || part.removed) {
+			// Show the change
+			for (const line of raw) {
+				if (part.added) {
+					const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+					output.push(`+${lineNum} ${line}`);
+					newLineNum++;
+				} else {
+					// removed
+					const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+					output.push(`-${lineNum} ${line}`);
+					oldLineNum++;
+				}
+			}
+			lastWasChange = true;
+		} else {
+			// Context lines - only show a few before/after changes
+			const nextPartIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);
+
+			if (lastWasChange || nextPartIsChange) {
+				// Show context
+				let linesToShow = raw;
+				let skipStart = 0;
+				let skipEnd = 0;
+
+				if (!lastWasChange) {
+					// Show only last N lines as leading context
+					skipStart = Math.max(0, raw.length - contextLines);
+					linesToShow = raw.slice(skipStart);
+				}
+
+				if (!nextPartIsChange && linesToShow.length > contextLines) {
+					// Show only first N lines as trailing context
+					skipEnd = linesToShow.length - contextLines;
+					linesToShow = linesToShow.slice(0, contextLines);
+				}
+
+				// Add ellipsis if we skipped lines at start
+				if (skipStart > 0) {
+					output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+					// Update line numbers for the skipped leading context
+					oldLineNum += skipStart;
+					newLineNum += skipStart;
+				}
+
+				for (const line of linesToShow) {
+					const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+					output.push(` ${lineNum} ${line}`);
+					oldLineNum++;
+					newLineNum++;
+				}
+
+				// Add ellipsis if we skipped lines at end
+				if (skipEnd > 0) {
+					output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+					// Update line numbers for the skipped trailing context
+					oldLineNum += skipEnd;
+					newLineNum += skipEnd;
+				}
+			} else {
+				// Skip these context lines entirely
+				oldLineNum += raw.length;
+				newLineNum += raw.length;
+			}
+
+			lastWasChange = false;
+		}
+	}
+
+	return output.join("\n");
+}
+
+const editSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
+	oldText: Type.String({ description: "Exact text to find and replace (must match exactly)" }),
+	newText: Type.String({ description: "New text to replace the old text with" }),
+});
+
+export const editTool: AgentTool<typeof editSchema> = {
+	name: "edit",
+	label: "edit",
+	description:
+		"Edit a file by replacing exact text. The oldText must match exactly (including whitespace). Use this for precise, surgical edits.",
+	parameters: editSchema,
+	execute: async (
+		_toolCallId: string,
+		{ path, oldText, newText }: { path: string; oldText: string; newText: string },
+		signal?: AbortSignal,
+	) => {
+		const absolutePath = resolvePath(expandPath(path));
+
+		return new Promise<{
+			content: Array<{ type: "text"; text: string }>;
+			details: { diff: string } | undefined;
+		}>((resolve, reject) => {
+			// Check if already aborted
+			if (signal?.aborted) {
+				reject(new Error("Operation aborted"));
+				return;
+			}
+
+			let aborted = false;
+
+			// Set up abort handler
+			const onAbort = () => {
+				aborted = true;
+				reject(new Error("Operation aborted"));
+			};
+
+			if (signal) {
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+
+			// Perform the edit operation
+			(async () => {
+				try {
+					// Check if file exists
+					try {
+						await access(absolutePath, constants.R_OK | constants.W_OK);
+					} catch {
+						if (signal) {
+							signal.removeEventListener("abort", onAbort);
+						}
+						reject(new Error(`File not found: ${path}`));
+						return;
+					}
+
+					// Check if aborted before reading
+					if (aborted) {
+						return;
+					}
+
+					// Read the file
+					const content = await readFile(absolutePath, "utf-8");
+
+					// Check if aborted after reading
+					if (aborted) {
+						return;
+					}
+
+					// Check if old text exists
+					if (!content.includes(oldText)) {
+						if (signal) {
+							signal.removeEventListener("abort", onAbort);
+						}
+						reject(
+							new Error(
+								`Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`,
+							),
+						);
+						return;
+					}
+
+					// Count occurrences
+					const occurrences = content.split(oldText).length - 1;
+
+					if (occurrences > 1) {
+						if (signal) {
+							signal.removeEventListener("abort", onAbort);
+						}
+						reject(
+							new Error(
+								`Found ${occurrences} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`,
+							),
+						);
+						return;
+					}
+
+					// Check if aborted before writing
+					if (aborted) {
+						return;
+					}
+
+					// Perform replacement using indexOf + substring (raw string replace, no special character interpretation)
+					// String.replace() interprets $ in the replacement string, so we do manual replacement
+					const index = content.indexOf(oldText);
+					const newContent = content.substring(0, index) + newText + content.substring(index + oldText.length);
+
+					// Verify the replacement actually changed something
+					if (content === newContent) {
+						if (signal) {
+							signal.removeEventListener("abort", onAbort);
+						}
+						reject(
+							new Error(
+								`No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`,
+							),
+						);
+						return;
+					}
+
+					await writeFile(absolutePath, newContent, "utf-8");
+
+					// Check if aborted after writing
+					if (aborted) {
+						return;
+					}
+
+					// Clean up abort handler
+					if (signal) {
+						signal.removeEventListener("abort", onAbort);
+					}
+
+					resolve({
+						content: [
+							{
+								type: "text",
+								text: `Successfully replaced text in ${path}. Changed ${oldText.length} characters to ${newText.length} characters.`,
+							},
+						],
+						details: { diff: generateDiffString(content, newContent) },
+					});
+				} catch (error: any) {
+					// Clean up abort handler
+					if (signal) {
+						signal.removeEventListener("abort", onAbort);
+					}
+
+					if (!aborted) {
+						reject(error);
+					}
+				}
+			})();
+		});
+	},
+};

packages/coding-agent/src/core/tools/find.ts

@@ -0,0 +1,203 @@
+import type { AgentTool } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { globSync } from "glob";
+import { homedir } from "os";
+import path from "path";
+import { ensureTool } from "../../utils/tools-manager.js";
+import { DEFAULT_MAX_BYTES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
+
+/**
+ * Expand ~ to home directory
+ */
+function expandPath(filePath: string): string {
+	if (filePath === "~") {
+		return homedir();
+	}
+	if (filePath.startsWith("~/")) {
+		return homedir() + filePath.slice(1);
+	}
+	return filePath;
+}
+
+const findSchema = Type.Object({
+	pattern: Type.String({
+		description: "Glob pattern to match files, e.g. '*.ts', '**/*.json', or 'src/**/*.spec.ts'",
+	}),
+	path: Type.Optional(Type.String({ description: "Directory to search in (default: current directory)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of results (default: 1000)" })),
+});
+
+const DEFAULT_LIMIT = 1000;
+
+interface FindToolDetails {
+	truncation?: TruncationResult;
+	resultLimitReached?: number;
+}
+
+export const findTool: AgentTool<typeof findSchema> = {
+	name: "find",
+	label: "find",
+	description: `Search for files by glob pattern. Returns matching file paths relative to the search directory. Respects .gitignore. Output is truncated to ${DEFAULT_LIMIT} results or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,
+	parameters: findSchema,
+	execute: async (
+		_toolCallId: string,
+		{ pattern, path: searchDir, limit }: { pattern: string; path?: string; limit?: number },
+		signal?: AbortSignal,
+	) => {
+		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 {
+					// Ensure fd is available
+					const fdPath = await ensureTool("fd", true);
+					if (!fdPath) {
+						reject(new Error("fd is not available and could not be downloaded"));
+						return;
+					}
+
+					const searchPath = path.resolve(expandPath(searchDir || "."));
+					const effectiveLimit = limit ?? DEFAULT_LIMIT;
+
+					// Build fd arguments
+					const args: string[] = [
+						"--glob", // Use glob pattern
+						"--color=never", // No ANSI colors
+						"--hidden", // Search hidden files (but still respect .gitignore)
+						"--max-results",
+						String(effectiveLimit),
+					];
+
+					// Include .gitignore files (root + nested) so fd respects them even outside git repos
+					const gitignoreFiles = new Set<string>();
+					const rootGitignore = path.join(searchPath, ".gitignore");
+					if (existsSync(rootGitignore)) {
+						gitignoreFiles.add(rootGitignore);
+					}
+
+					try {
+						const nestedGitignores = globSync("**/.gitignore", {
+							cwd: searchPath,
+							dot: true,
+							absolute: true,
+							ignore: ["**/node_modules/**", "**/.git/**"],
+						});
+						for (const file of nestedGitignores) {
+							gitignoreFiles.add(file);
+						}
+					} catch {
+						// Ignore glob errors
+					}
+
+					for (const gitignorePath of gitignoreFiles) {
+						args.push("--ignore-file", gitignorePath);
+					}
+
+					// Pattern and path
+					args.push(pattern, searchPath);
+
+					// Run fd
+					const result = spawnSync(fdPath, args, {
+						encoding: "utf-8",
+						maxBuffer: 10 * 1024 * 1024, // 10MB
+					});
+
+					signal?.removeEventListener("abort", onAbort);
+
+					if (result.error) {
+						reject(new Error(`Failed to run fd: ${result.error.message}`));
+						return;
+					}
+
+					const output = result.stdout?.trim() || "";
+
+					if (result.status !== 0) {
+						const errorMsg = result.stderr?.trim() || `fd exited with code ${result.status}`;
+						// fd returns non-zero for some errors but may still have partial output
+						if (!output) {
+							reject(new Error(errorMsg));
+							return;
+						}
+					}
+
+					if (!output) {
+						resolve({
+							content: [{ type: "text", text: "No files found matching pattern" }],
+							details: undefined,
+						});
+						return;
+					}
+
+					const lines = output.split("\n");
+					const relativized: string[] = [];
+
+					for (const rawLine of lines) {
+						const line = rawLine.replace(/\r$/, "").trim();
+						if (!line) {
+							continue;
+						}
+
+						const hadTrailingSlash = line.endsWith("/") || line.endsWith("\\");
+						let relativePath = line;
+						if (line.startsWith(searchPath)) {
+							relativePath = line.slice(searchPath.length + 1); // +1 for the /
+						} else {
+							relativePath = path.relative(searchPath, line);
+						}
+
+						if (hadTrailingSlash && !relativePath.endsWith("/")) {
+							relativePath += "/";
+						}
+
+						relativized.push(relativePath);
+					}
+
+					// Check if we hit the result limit
+					const resultLimitReached = relativized.length >= effectiveLimit;
+
+					// Apply byte truncation (no line limit since we already have result limit)
+					const rawOutput = relativized.join("\n");
+					const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+
+					let resultOutput = truncation.content;
+					const details: FindToolDetails = {};
+
+					// Build notices
+					const notices: string[] = [];
+
+					if (resultLimitReached) {
+						notices.push(
+							`${effectiveLimit} results limit reached. Use limit=${effectiveLimit * 2} for more, or refine pattern`,
+						);
+						details.resultLimitReached = effectiveLimit;
+					}
+
+					if (truncation.truncated) {
+						notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+						details.truncation = truncation;
+					}
+
+					if (notices.length > 0) {
+						resultOutput += `\n\n[${notices.join(". ")}]`;
+					}
+
+					resolve({
+						content: [{ type: "text", text: resultOutput }],
+						details: Object.keys(details).length > 0 ? details : undefined,
+					});
+				} catch (e: any) {
+					signal?.removeEventListener("abort", onAbort);
+					reject(e);
+				}
+			})();
+		});
+	},
+};

packages/coding-agent/src/core/tools/grep.ts

@@ -0,0 +1,320 @@
+import { createInterface } from "node:readline";
+import type { AgentTool } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { spawn } from "child_process";
+import { readFileSync, type Stats, statSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+import { ensureTool } from "../../utils/tools-manager.js";
+import {
+	DEFAULT_MAX_BYTES,
+	formatSize,
+	GREP_MAX_LINE_LENGTH,
+	type TruncationResult,
+	truncateHead,
+	truncateLine,
+} from "./truncate.js";
+
+/**
+ * Expand ~ to home directory
+ */
+function expandPath(filePath: string): string {
+	if (filePath === "~") {
+		return homedir();
+	}
+	if (filePath.startsWith("~/")) {
+		return homedir() + filePath.slice(1);
+	}
+	return filePath;
+}
+
+const grepSchema = Type.Object({
+	pattern: Type.String({ description: "Search pattern (regex or literal string)" }),
+	path: Type.Optional(Type.String({ description: "Directory or file to search (default: current directory)" })),
+	glob: Type.Optional(Type.String({ description: "Filter files by glob pattern, e.g. '*.ts' or '**/*.spec.ts'" })),
+	ignoreCase: Type.Optional(Type.Boolean({ description: "Case-insensitive search (default: false)" })),
+	literal: Type.Optional(
+		Type.Boolean({ description: "Treat pattern as literal string instead of regex (default: false)" }),
+	),
+	context: Type.Optional(
+		Type.Number({ description: "Number of lines to show before and after each match (default: 0)" }),
+	),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of matches to return (default: 100)" })),
+});
+
+const DEFAULT_LIMIT = 100;
+
+interface GrepToolDetails {
+	truncation?: TruncationResult;
+	matchLimitReached?: number;
+	linesTruncated?: boolean;
+}
+
+export const grepTool: AgentTool<typeof grepSchema> = {
+	name: "grep",
+	label: "grep",
+	description: `Search file contents for a pattern. Returns matching lines with file paths and line numbers. Respects .gitignore. Output is truncated to ${DEFAULT_LIMIT} matches or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Long lines are truncated to ${GREP_MAX_LINE_LENGTH} chars.`,
+	parameters: grepSchema,
+	execute: async (
+		_toolCallId: string,
+		{
+			pattern,
+			path: searchDir,
+			glob,
+			ignoreCase,
+			literal,
+			context,
+			limit,
+		}: {
+			pattern: string;
+			path?: string;
+			glob?: string;
+			ignoreCase?: boolean;
+			literal?: boolean;
+			context?: number;
+			limit?: number;
+		},
+		signal?: AbortSignal,
+	) => {
+		return new Promise((resolve, reject) => {
+			if (signal?.aborted) {
+				reject(new Error("Operation aborted"));
+				return;
+			}
+
+			let settled = false;
+			const settle = (fn: () => void) => {
+				if (!settled) {
+					settled = true;
+					fn();
+				}
+			};
+
+			(async () => {
+				try {
+					const rgPath = await ensureTool("rg", true);
+					if (!rgPath) {
+						settle(() => reject(new Error("ripgrep (rg) is not available and could not be downloaded")));
+						return;
+					}
+
+					const searchPath = path.resolve(expandPath(searchDir || "."));
+					let searchStat: Stats;
+					try {
+						searchStat = statSync(searchPath);
+					} catch (err) {
+						settle(() => reject(new Error(`Path not found: ${searchPath}`)));
+						return;
+					}
+
+					const isDirectory = searchStat.isDirectory();
+					const contextValue = context && context > 0 ? context : 0;
+					const effectiveLimit = Math.max(1, limit ?? DEFAULT_LIMIT);
+
+					const formatPath = (filePath: string): string => {
+						if (isDirectory) {
+							const relative = path.relative(searchPath, filePath);
+							if (relative && !relative.startsWith("..")) {
+								return relative.replace(/\\/g, "/");
+							}
+						}
+						return path.basename(filePath);
+					};
+
+					const fileCache = new Map<string, string[]>();
+					const getFileLines = (filePath: string): string[] => {
+						let lines = fileCache.get(filePath);
+						if (!lines) {
+							try {
+								const content = readFileSync(filePath, "utf-8");
+								lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+							} catch {
+								lines = [];
+							}
+							fileCache.set(filePath, lines);
+						}
+						return lines;
+					};
+
+					const args: string[] = ["--json", "--line-number", "--color=never", "--hidden"];
+
+					if (ignoreCase) {
+						args.push("--ignore-case");
+					}
+
+					if (literal) {
+						args.push("--fixed-strings");
+					}
+
+					if (glob) {
+						args.push("--glob", glob);
+					}
+
+					args.push(pattern, searchPath);
+
+					const child = spawn(rgPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+					const rl = createInterface({ input: child.stdout });
+					let stderr = "";
+					let matchCount = 0;
+					let matchLimitReached = false;
+					let linesTruncated = false;
+					let aborted = false;
+					let killedDueToLimit = false;
+					const outputLines: string[] = [];
+
+					const cleanup = () => {
+						rl.close();
+						signal?.removeEventListener("abort", onAbort);
+					};
+
+					const stopChild = (dueToLimit: boolean = false) => {
+						if (!child.killed) {
+							killedDueToLimit = dueToLimit;
+							child.kill();
+						}
+					};
+
+					const onAbort = () => {
+						aborted = true;
+						stopChild();
+					};
+
+					signal?.addEventListener("abort", onAbort, { once: true });
+
+					child.stderr?.on("data", (chunk) => {
+						stderr += chunk.toString();
+					});
+
+					const formatBlock = (filePath: string, lineNumber: number): string[] => {
+						const relativePath = formatPath(filePath);
+						const lines = getFileLines(filePath);
+						if (!lines.length) {
+							return [`${relativePath}:${lineNumber}: (unable to read file)`];
+						}
+
+						const block: string[] = [];
+						const start = contextValue > 0 ? Math.max(1, lineNumber - contextValue) : lineNumber;
+						const end = contextValue > 0 ? Math.min(lines.length, lineNumber + contextValue) : lineNumber;
+
+						for (let current = start; current <= end; current++) {
+							const lineText = lines[current - 1] ?? "";
+							const sanitized = lineText.replace(/\r/g, "");
+							const isMatchLine = current === lineNumber;
+
+							// Truncate long lines
+							const { text: truncatedText, wasTruncated } = truncateLine(sanitized);
+							if (wasTruncated) {
+								linesTruncated = true;
+							}
+
+							if (isMatchLine) {
+								block.push(`${relativePath}:${current}: ${truncatedText}`);
+							} else {
+								block.push(`${relativePath}-${current}- ${truncatedText}`);
+							}
+						}
+
+						return block;
+					};
+
+					rl.on("line", (line) => {
+						if (!line.trim() || matchCount >= effectiveLimit) {
+							return;
+						}
+
+						let event: any;
+						try {
+							event = JSON.parse(line);
+						} catch {
+							return;
+						}
+
+						if (event.type === "match") {
+							matchCount++;
+							const filePath = event.data?.path?.text;
+							const lineNumber = event.data?.line_number;
+
+							if (filePath && typeof lineNumber === "number") {
+								outputLines.push(...formatBlock(filePath, lineNumber));
+							}
+
+							if (matchCount >= effectiveLimit) {
+								matchLimitReached = true;
+								stopChild(true);
+							}
+						}
+					});
+
+					child.on("error", (error) => {
+						cleanup();
+						settle(() => reject(new Error(`Failed to run ripgrep: ${error.message}`)));
+					});
+
+					child.on("close", (code) => {
+						cleanup();
+
+						if (aborted) {
+							settle(() => reject(new Error("Operation aborted")));
+							return;
+						}
+
+						if (!killedDueToLimit && code !== 0 && code !== 1) {
+							const errorMsg = stderr.trim() || `ripgrep exited with code ${code}`;
+							settle(() => reject(new Error(errorMsg)));
+							return;
+						}
+
+						if (matchCount === 0) {
+							settle(() =>
+								resolve({ content: [{ type: "text", text: "No matches found" }], details: undefined }),
+							);
+							return;
+						}
+
+						// Apply byte truncation (no line limit since we already have match limit)
+						const rawOutput = outputLines.join("\n");
+						const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+
+						let output = truncation.content;
+						const details: GrepToolDetails = {};
+
+						// Build notices
+						const notices: string[] = [];
+
+						if (matchLimitReached) {
+							notices.push(
+								`${effectiveLimit} matches limit reached. Use limit=${effectiveLimit * 2} for more, or refine pattern`,
+							);
+							details.matchLimitReached = effectiveLimit;
+						}
+
+						if (truncation.truncated) {
+							notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+							details.truncation = truncation;
+						}
+
+						if (linesTruncated) {
+							notices.push(
+								`Some lines truncated to ${GREP_MAX_LINE_LENGTH} chars. Use read tool to see full lines`,
+							);
+							details.linesTruncated = true;
+						}
+
+						if (notices.length > 0) {
+							output += `\n\n[${notices.join(". ")}]`;
+						}
+
+						settle(() =>
+							resolve({
+								content: [{ type: "text", text: output }],
+								details: Object.keys(details).length > 0 ? details : undefined,
+							}),
+						);
+					});
+				} catch (err) {
+					settle(() => reject(err as Error));
+				}
+			})();
+		});
+	},
+};

packages/coding-agent/src/core/tools/index.ts

@@ -0,0 +1,31 @@
+export { bashTool } from "./bash.js";
+export { editTool } from "./edit.js";
+export { findTool } from "./find.js";
+export { grepTool } from "./grep.js";
+export { lsTool } from "./ls.js";
+export { readTool } from "./read.js";
+export { writeTool } from "./write.js";
+
+import { bashTool } from "./bash.js";
+import { editTool } from "./edit.js";
+import { findTool } from "./find.js";
+import { grepTool } from "./grep.js";
+import { lsTool } from "./ls.js";
+import { readTool } from "./read.js";
+import { writeTool } from "./write.js";
+
+// Default tools for full access mode
+export const codingTools = [readTool, bashTool, editTool, writeTool];
+
+// All available tools (including read-only exploration tools)
+export const allTools = {
+	read: readTool,
+	bash: bashTool,
+	edit: editTool,
+	write: writeTool,
+	grep: grepTool,
+	find: findTool,
+	ls: lsTool,
+};
+
+export type ToolName = keyof typeof allTools;

packages/coding-agent/src/core/tools/ls.ts

@@ -0,0 +1,144 @@
+import type { AgentTool } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { existsSync, readdirSync, statSync } from "fs";
+import { homedir } from "os";
+import nodePath from "path";
+import { DEFAULT_MAX_BYTES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
+
+/**
+ * Expand ~ to home directory
+ */
+function expandPath(filePath: string): string {
+	if (filePath === "~") {
+		return homedir();
+	}
+	if (filePath.startsWith("~/")) {
+		return homedir() + filePath.slice(1);
+	}
+	return filePath;
+}
+
+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)" })),
+});
+
+const DEFAULT_LIMIT = 500;
+
+interface LsToolDetails {
+	truncation?: TruncationResult;
+	entryLimitReached?: number;
+}
+
+export const lsTool: AgentTool<typeof lsSchema> = {
+	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).`,
+	parameters: lsSchema,
+	execute: async (_toolCallId: string, { path, limit }: { path?: string; limit?: number }, signal?: AbortSignal) => {
+		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 });
+
+			try {
+				const dirPath = nodePath.resolve(expandPath(path || "."));
+				const effectiveLimit = limit ?? DEFAULT_LIMIT;
+
+				// Check if path exists
+				if (!existsSync(dirPath)) {
+					reject(new Error(`Path not found: ${dirPath}`));
+					return;
+				}
+
+				// Check if path is a directory
+				const stat = statSync(dirPath);
+				if (!stat.isDirectory()) {
+					reject(new Error(`Not a directory: ${dirPath}`));
+					return;
+				}
+
+				// Read directory entries
+				let entries: string[];
+				try {
+					entries = readdirSync(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 = statSync(fullPath);
+						if (entryStat.isDirectory()) {
+							suffix = "/";
+						}
+					} catch {
+						// Skip entries we can't stat
+						continue;
+					}
+
+					results.push(entry + suffix);
+				}
+
+				signal?.removeEventListener("abort", onAbort);
+
+				if (results.length === 0) {
+					resolve({ content: [{ type: "text", text: "(empty directory)" }], details: undefined });
+					return;
+				}
+
+				// Apply byte truncation (no line limit since we already have entry limit)
+				const rawOutput = results.join("\n");
+				const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+
+				let output = truncation.content;
+				const details: LsToolDetails = {};
+
+				// Build notices
+				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);
+			}
+		});
+	},
+};

packages/coding-agent/src/core/tools/read.ts

@@ -0,0 +1,198 @@
+import * as os from "node:os";
+import type { AgentTool, ImageContent, TextContent } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { constants } from "fs";
+import { access, readFile } from "fs/promises";
+import { extname, resolve as resolvePath } from "path";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
+
+/**
+ * Expand ~ to home directory
+ */
+function expandPath(filePath: string): string {
+	if (filePath === "~") {
+		return os.homedir();
+	}
+	if (filePath.startsWith("~/")) {
+		return os.homedir() + filePath.slice(1);
+	}
+	return filePath;
+}
+
+/**
+ * Map of file extensions to MIME types for common image formats
+ */
+const IMAGE_MIME_TYPES: Record<string, string> = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".gif": "image/gif",
+	".webp": "image/webp",
+};
+
+/**
+ * Check if a file is an image based on its extension
+ */
+function isImageFile(filePath: string): string | null {
+	const ext = extname(filePath).toLowerCase();
+	return IMAGE_MIME_TYPES[ext] || null;
+}
+
+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" })),
+});
+
+interface ReadToolDetails {
+	truncation?: TruncationResult;
+}
+
+export const readTool: AgentTool<typeof readSchema> = {
+	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.`,
+	parameters: readSchema,
+	execute: async (
+		_toolCallId: string,
+		{ path, offset, limit }: { path: string; offset?: number; limit?: number },
+		signal?: AbortSignal,
+	) => {
+		const absolutePath = resolvePath(expandPath(path));
+		const mimeType = isImageFile(absolutePath);
+
+		return new Promise<{ content: (TextContent | ImageContent)[]; details: ReadToolDetails | undefined }>(
+			(resolve, reject) => {
+				// Check if already aborted
+				if (signal?.aborted) {
+					reject(new Error("Operation aborted"));
+					return;
+				}
+
+				let aborted = false;
+
+				// Set up abort handler
+				const onAbort = () => {
+					aborted = true;
+					reject(new Error("Operation aborted"));
+				};
+
+				if (signal) {
+					signal.addEventListener("abort", onAbort, { once: true });
+				}
+
+				// Perform the read operation
+				(async () => {
+					try {
+						// Check if file exists
+						await access(absolutePath, constants.R_OK);
+
+						// Check if aborted before reading
+						if (aborted) {
+							return;
+						}
+
+						// Read the file based on type
+						let content: (TextContent | ImageContent)[];
+						let details: ReadToolDetails | undefined;
+
+						if (mimeType) {
+							// Read as image (binary)
+							const buffer = await readFile(absolutePath);
+							const base64 = buffer.toString("base64");
+
+							content = [
+								{ type: "text", text: `Read image file [${mimeType}]` },
+								{ type: "image", data: base64, mimeType },
+							];
+						} else {
+							// Read as text
+							const textContent = await readFile(absolutePath, "utf-8");
+							const allLines = textContent.split("\n");
+							const totalFileLines = allLines.length;
+
+							// Apply offset if specified (1-indexed to 0-indexed)
+							const startLine = offset ? Math.max(0, offset - 1) : 0;
+							const startLineDisplay = startLine + 1; // For display (1-indexed)
+
+							// 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)`);
+							}
+
+							// If limit is specified by user, use it; otherwise we'll let truncateHead decide
+							let selectedContent: string;
+							let userLimitedLines: number | undefined;
+							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 (respects both line and byte limits)
+							const truncation = truncateHead(selectedContent);
+
+							let outputText: string;
+
+							if (truncation.firstLineExceedsLimit) {
+								// First line at offset exceeds 30KB - tell model to use bash
+								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 actionable 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, there's more content, but no truncation
+								const endLineDisplay = startLineDisplay + userLimitedLines - 1;
+								const remaining = allLines.length - (startLine + userLimitedLines);
+								const nextOffset = startLine + userLimitedLines + 1;
+
+								outputText = truncation.content;
+								outputText += `\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue]`;
+							} else {
+								// No truncation, no user limit exceeded
+								outputText = truncation.content;
+							}
+
+							content = [{ type: "text", text: outputText }];
+						}
+
+						// Check if aborted after reading
+						if (aborted) {
+							return;
+						}
+
+						// Clean up abort handler
+						if (signal) {
+							signal.removeEventListener("abort", onAbort);
+						}
+
+						resolve({ content, details });
+					} catch (error: any) {
+						// Clean up abort handler
+						if (signal) {
+							signal.removeEventListener("abort", onAbort);
+						}
+
+						if (!aborted) {
+							reject(error);
+						}
+					}
+				})();
+			},
+		);
+	},
+};

packages/coding-agent/src/core/tools/truncate.ts

@@ -0,0 +1,251 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 30KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
+export const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line
+
+export interface TruncationResult {
+	/** The truncated content */
+	content: string;
+	/** Whether truncation occurred */
+	truncated: boolean;
+	/** Which limit was hit: "lines", "bytes", or null if not truncated */
+	truncatedBy: "lines" | "bytes" | null;
+	/** Total number of lines in the original content */
+	totalLines: number;
+	/** Total number of bytes in the original content */
+	totalBytes: number;
+	/** Number of complete lines in the truncated output */
+	outputLines: number;
+	/** Number of bytes in the truncated output */
+	outputBytes: number;
+	/** Whether the last line was partially truncated (only for tail truncation edge case) */
+	lastLinePartial: boolean;
+	/** Whether the first line exceeded the byte limit (for head truncation) */
+	firstLineExceedsLimit: boolean;
+}
+
+export interface TruncationOptions {
+	/** Maximum number of lines (default: 2000) */
+	maxLines?: number;
+	/** Maximum number of bytes (default: 30KB) */
+	maxBytes?: number;
+}
+
+/**
+ * Format bytes as human-readable size.
+ */
+export function formatSize(bytes: number): string {
+	if (bytes < 1024) {
+		return `${bytes}B`;
+	} else if (bytes < 1024 * 1024) {
+		return `${(bytes / 1024).toFixed(1)}KB`;
+	} else {
+		return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	}
+}
+
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+
+	const totalBytes = Buffer.byteLength(content, "utf-8");
+	const lines = content.split("\n");
+	const totalLines = lines.length;
+
+	// Check if no truncation needed
+	if (totalLines <= maxLines && totalBytes <= maxBytes) {
+		return {
+			content,
+			truncated: false,
+			truncatedBy: null,
+			totalLines,
+			totalBytes,
+			outputLines: totalLines,
+			outputBytes: totalBytes,
+			lastLinePartial: false,
+			firstLineExceedsLimit: false,
+		};
+	}
+
+	// Check if first line alone exceeds byte limit
+	const firstLineBytes = Buffer.byteLength(lines[0], "utf-8");
+	if (firstLineBytes > maxBytes) {
+		return {
+			content: "",
+			truncated: true,
+			truncatedBy: "bytes",
+			totalLines,
+			totalBytes,
+			outputLines: 0,
+			outputBytes: 0,
+			lastLinePartial: false,
+			firstLineExceedsLimit: true,
+		};
+	}
+
+	// Collect complete lines that fit
+	const outputLinesArr: string[] = [];
+	let outputBytesCount = 0;
+	let truncatedBy: "lines" | "bytes" = "lines";
+
+	for (let i = 0; i < lines.length && i < maxLines; i++) {
+		const line = lines[i];
+		const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0); // +1 for newline
+
+		if (outputBytesCount + lineBytes > maxBytes) {
+			truncatedBy = "bytes";
+			break;
+		}
+
+		outputLinesArr.push(line);
+		outputBytesCount += lineBytes;
+	}
+
+	// If we exited due to line limit
+	if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+		truncatedBy = "lines";
+	}
+
+	const outputContent = outputLinesArr.join("\n");
+	const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+
+	return {
+		content: outputContent,
+		truncated: true,
+		truncatedBy,
+		totalLines,
+		totalBytes,
+		outputLines: outputLinesArr.length,
+		outputBytes: finalOutputBytes,
+		lastLinePartial: false,
+		firstLineExceedsLimit: false,
+	};
+}
+
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export function truncateTail(content: string, options: TruncationOptions = {}): TruncationResult {
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+
+	const totalBytes = Buffer.byteLength(content, "utf-8");
+	const lines = content.split("\n");
+	const totalLines = lines.length;
+
+	// Check if no truncation needed
+	if (totalLines <= maxLines && totalBytes <= maxBytes) {
+		return {
+			content,
+			truncated: false,
+			truncatedBy: null,
+			totalLines,
+			totalBytes,
+			outputLines: totalLines,
+			outputBytes: totalBytes,
+			lastLinePartial: false,
+			firstLineExceedsLimit: false,
+		};
+	}
+
+	// Work backwards from the end
+	const outputLinesArr: string[] = [];
+	let outputBytesCount = 0;
+	let truncatedBy: "lines" | "bytes" = "lines";
+	let lastLinePartial = false;
+
+	for (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {
+		const line = lines[i];
+		const lineBytes = Buffer.byteLength(line, "utf-8") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline
+
+		if (outputBytesCount + lineBytes > maxBytes) {
+			truncatedBy = "bytes";
+			// Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,
+			// take the end of the line (partial)
+			if (outputLinesArr.length === 0) {
+				const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);
+				outputLinesArr.unshift(truncatedLine);
+				outputBytesCount = Buffer.byteLength(truncatedLine, "utf-8");
+				lastLinePartial = true;
+			}
+			break;
+		}
+
+		outputLinesArr.unshift(line);
+		outputBytesCount += lineBytes;
+	}
+
+	// If we exited due to line limit
+	if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+		truncatedBy = "lines";
+	}
+
+	const outputContent = outputLinesArr.join("\n");
+	const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+
+	return {
+		content: outputContent,
+		truncated: true,
+		truncatedBy,
+		totalLines,
+		totalBytes,
+		outputLines: outputLinesArr.length,
+		outputBytes: finalOutputBytes,
+		lastLinePartial,
+		firstLineExceedsLimit: false,
+	};
+}
+
+/**
+ * Truncate a string to fit within a byte limit (from the end).
+ * Handles multi-byte UTF-8 characters correctly.
+ */
+function truncateStringToBytesFromEnd(str: string, maxBytes: number): string {
+	const buf = Buffer.from(str, "utf-8");
+	if (buf.length <= maxBytes) {
+		return str;
+	}
+
+	// Start from the end, skip maxBytes back
+	let start = buf.length - maxBytes;
+
+	// Find a valid UTF-8 boundary (start of a character)
+	while (start < buf.length && (buf[start] & 0xc0) === 0x80) {
+		start++;
+	}
+
+	return buf.slice(start).toString("utf-8");
+}
+
+/**
+ * Truncate a single line to max characters, adding [truncated] suffix.
+ * Used for grep match lines.
+ */
+export function truncateLine(
+	line: string,
+	maxChars: number = GREP_MAX_LINE_LENGTH,
+): { text: string; wasTruncated: boolean } {
+	if (line.length <= maxChars) {
+		return { text: line, wasTruncated: false };
+	}
+	return { text: line.slice(0, maxChars) + "... [truncated]", wasTruncated: true };
+}

packages/coding-agent/src/core/tools/write.ts

@@ -0,0 +1,95 @@
+import * as os from "node:os";
+import type { AgentTool } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve as resolvePath } from "path";
+
+/**
+ * Expand ~ to home directory
+ */
+function expandPath(filePath: string): string {
+	if (filePath === "~") {
+		return os.homedir();
+	}
+	if (filePath.startsWith("~/")) {
+		return os.homedir() + filePath.slice(1);
+	}
+	return filePath;
+}
+
+const writeSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
+	content: Type.String({ description: "Content to write to the file" }),
+});
+
+export const writeTool: AgentTool<typeof writeSchema> = {
+	name: "write",
+	label: "write",
+	description:
+		"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+	parameters: writeSchema,
+	execute: async (_toolCallId: string, { path, content }: { path: string; content: string }, signal?: AbortSignal) => {
+		const absolutePath = resolvePath(expandPath(path));
+		const dir = dirname(absolutePath);
+
+		return new Promise<{ content: Array<{ type: "text"; text: string }>; details: undefined }>((resolve, reject) => {
+			// Check if already aborted
+			if (signal?.aborted) {
+				reject(new Error("Operation aborted"));
+				return;
+			}
+
+			let aborted = false;
+
+			// Set up abort handler
+			const onAbort = () => {
+				aborted = true;
+				reject(new Error("Operation aborted"));
+			};
+
+			if (signal) {
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+
+			// Perform the write operation
+			(async () => {
+				try {
+					// Create parent directories if needed
+					await mkdir(dir, { recursive: true });
+
+					// Check if aborted before writing
+					if (aborted) {
+						return;
+					}
+
+					// Write the file
+					await writeFile(absolutePath, content, "utf-8");
+
+					// Check if aborted after writing
+					if (aborted) {
+						return;
+					}
+
+					// Clean up abort handler
+					if (signal) {
+						signal.removeEventListener("abort", onAbort);
+					}
+
+					resolve({
+						content: [{ type: "text", text: `Successfully wrote ${content.length} bytes to ${path}` }],
+						details: undefined,
+					});
+				} catch (error: any) {
+					// Clean up abort handler
+					if (signal) {
+						signal.removeEventListener("abort", onAbort);
+					}
+
+					if (!aborted) {
+						reject(error);
+					}
+				}
+			})();
+		});
+	},
+};