gsd-pi 2.6.0 → 2.7.0

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

@@ -0,0 +1,139 @@
+export {
+	type BashOperations,
+	type BashSpawnContext,
+	type BashSpawnHook,
+	type BashToolDetails,
+	type BashToolInput,
+	type BashToolOptions,
+	bashTool,
+	createBashTool,
+} from "./bash.js";
+export {
+	createEditTool,
+	type EditOperations,
+	type EditToolDetails,
+	type EditToolInput,
+	type EditToolOptions,
+	editTool,
+} from "./edit.js";
+export {
+	createFindTool,
+	type FindOperations,
+	type FindToolDetails,
+	type FindToolInput,
+	type FindToolOptions,
+	findTool,
+} from "./find.js";
+export {
+	createGrepTool,
+	type GrepOperations,
+	type GrepToolDetails,
+	type GrepToolInput,
+	type GrepToolOptions,
+	grepTool,
+} from "./grep.js";
+export {
+	createLsTool,
+	type LsOperations,
+	type LsToolDetails,
+	type LsToolInput,
+	type LsToolOptions,
+	lsTool,
+} from "./ls.js";
+export {
+	createReadTool,
+	type ReadOperations,
+	type ReadToolDetails,
+	type ReadToolInput,
+	type ReadToolOptions,
+	readTool,
+} from "./read.js";
+export {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	type TruncationOptions,
+	type TruncationResult,
+	truncateHead,
+	truncateLine,
+	truncateTail,
+} from "./truncate.js";
+export {
+	createWriteTool,
+	type WriteOperations,
+	type WriteToolInput,
+	type WriteToolOptions,
+	writeTool,
+} from "./write.js";
+
+import type { AgentTool } from "@gsd/pi-agent-core";
+import { type BashToolOptions, bashTool, createBashTool } from "./bash.js";
+import { createEditTool, editTool } from "./edit.js";
+import { createFindTool, findTool } from "./find.js";
+import { createGrepTool, grepTool } from "./grep.js";
+import { createLsTool, lsTool } from "./ls.js";
+import { createReadTool, type ReadToolOptions, readTool } from "./read.js";
+import { createWriteTool, writeTool } from "./write.js";
+
+/** Tool type (AgentTool from pi-ai) */
+export type Tool = AgentTool<any>;
+
+// Default tools for full access mode (using process.cwd())
+export const codingTools: Tool[] = [readTool, bashTool, editTool, writeTool];
+
+// Read-only tools for exploration without modification (using process.cwd())
+export const readOnlyTools: Tool[] = [readTool, grepTool, findTool, lsTool];
+
+// All available tools (using process.cwd())
+export const allTools = {
+	read: readTool,
+	bash: bashTool,
+	edit: editTool,
+	write: writeTool,
+	grep: grepTool,
+	find: findTool,
+	ls: lsTool,
+};
+
+export type ToolName = keyof typeof allTools;
+
+export interface ToolsOptions {
+	/** Options for the read tool */
+	read?: ReadToolOptions;
+	/** Options for the bash tool */
+	bash?: BashToolOptions;
+}
+
+/**
+ * Create coding tools configured for a specific working directory.
+ */
+export function createCodingTools(cwd: string, options?: ToolsOptions): Tool[] {
+	return [
+		createReadTool(cwd, options?.read),
+		createBashTool(cwd, options?.bash),
+		createEditTool(cwd),
+		createWriteTool(cwd),
+	];
+}
+
+/**
+ * Create read-only tools configured for a specific working directory.
+ */
+export function createReadOnlyTools(cwd: string, options?: ToolsOptions): Tool[] {
+	return [createReadTool(cwd, options?.read), createGrepTool(cwd), createFindTool(cwd), createLsTool(cwd)];
+}
+
+/**
+ * Create all tools configured for a specific working directory.
+ */
+export function createAllTools(cwd: string, options?: ToolsOptions): Record<ToolName, Tool> {
+	return {
+		read: createReadTool(cwd, options?.read),
+		bash: createBashTool(cwd, options?.bash),
+		edit: createEditTool(cwd),
+		write: createWriteTool(cwd),
+		grep: createGrepTool(cwd),
+		find: createFindTool(cwd),
+		ls: createLsTool(cwd),
+	};
+}

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

@@ -0,0 +1,170 @@
+import type { AgentTool } from "@gsd/pi-agent-core";
+import { type Static, Type } from "@sinclair/typebox";
+import { existsSync, readdirSync, statSync } from "fs";
+import nodePath from "path";
+import { resolveToCwd } from "./path-utils.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 (e.g., SSH).
+ */
+export interface LsOperations {
+	/** Check if path exists */
+	exists: (absolutePath: string) => Promise<boolean> | boolean;
+	/** Get file/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;
+}
+
+export function createLsTool(cwd: string, options?: LsToolOptions): AgentTool<typeof lsSchema> {
+	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).`,
+		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 });
+
+				(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 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);
+					}
+				})();
+			});
+		},
+	};
+}
+
+/** Default ls tool using process.cwd() - for backwards compatibility */
+export const lsTool = createLsTool(process.cwd());

package/packages/pi-coding-agent/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/packages/pi-coding-agent/src/core/tools/read.ts

@@ -0,0 +1,222 @@
+import type { AgentTool } from "@gsd/pi-agent-core";
+import type { ImageContent, TextContent } from "@gsd/pi-ai";
+import { type Static, Type } from "@sinclair/typebox";
+import { constants } from "fs";
+import { access as fsAccess, readFile as fsReadFile } from "fs/promises";
+import { formatDimensionNote, resizeImage } from "../../utils/image-resize.js";
+import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
+import { resolveReadPath } from "./path-utils.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 (e.g., 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/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;
+}
+
+export function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema> {
+	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.`,
+		parameters: readSchema,
+		execute: async (
+			_toolCallId: string,
+			{ path, offset, limit }: { path: string; offset?: number; limit?: number },
+			signal?: AbortSignal,
+		) => {
+			const absolutePath = resolveReadPath(path, cwd);
+
+			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 ops.access(absolutePath);
+
+							// Check if aborted before reading
+							if (aborted) {
+								return;
+							}
+
+							const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(absolutePath) : undefined;
+
+							// Read the file based on type
+							let content: (TextContent | ImageContent)[];
+							let details: ReadToolDetails | undefined;
+
+							if (mimeType) {
+								// Read as image (binary)
+								const buffer = await ops.readFile(absolutePath);
+								const base64 = buffer.toString("base64");
+
+								if (autoResizeImages) {
+									// Resize image if needed
+									const resized = await resizeImage({ type: "image", data: base64, mimeType });
+									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 {
+									const textNote = `Read image file [${mimeType}]`;
+									content = [
+										{ type: "text", text: textNote },
+										{ type: "image", data: base64, mimeType },
+									];
+								}
+							} else {
+								// Read as text
+								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 (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 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);
+							}
+						}
+					})();
+				},
+			);
+		},
+	};
+}
+
+/** Default read tool using process.cwd() - for backwards compatibility */
+export const readTool = createReadTool(process.cwd());