pi-agent-flow 1.2.4 → 1.2.5

package/src/batch/fuzzy-edit.ts

@@ -0,0 +1,323 @@
+/**
+ * batch — fuzzy matching and edit application.
+ *
+ * Normalises trailing whitespace to allow inexact text matches, then applies
+ * one or more edits to a file's content while preserving offsets.
+ */
+
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { EditReplacement } from "./constants.js";
+
+// ---------------------------------------------------------------------------
+// Normalisation helpers
+// ---------------------------------------------------------------------------
+
+export function normalizeToLF(text: string): string {
+	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+export function restoreLineEndings(text: string, ending: string): string {
+	return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+
+export function detectLineEnding(content: string): string {
+	const crlfIdx = content.indexOf("\r\n");
+	const lfIdx = content.indexOf("\n");
+	if (lfIdx === -1) return "\n";
+	if (crlfIdx === -1) return "\n";
+	return crlfIdx < lfIdx ? "\r\n" : "\n";
+}
+
+export function stripBom(content: string): { bom: string; text: string } {
+	return content.startsWith("\uFEFF")
+		? { bom: "\uFEFF", text: content.slice(1) }
+		: { bom: "", text: content };
+}
+
+// ---------------------------------------------------------------------------
+// Fuzzy matching
+// ---------------------------------------------------------------------------
+
+function normalizeForMatch(text: string): string {
+	return text
+		.split("\n")
+		.map((line) => line.trimEnd())
+		.join("\n");
+}
+
+function buildPositionMap(original: string): number[] {
+	const normalized = normalizeForMatch(original);
+	const map: number[] = new Array(normalized.length + 1);
+	let oi = 0;
+	let ni = 0;
+
+	while (oi < original.length && ni < normalized.length) {
+		map[ni] = oi;
+		if (original[oi] === normalized[ni]) {
+			oi++;
+			ni++;
+		} else {
+			oi++;
+		}
+	}
+
+	while (ni < normalized.length) {
+		map[ni] = oi;
+		ni++;
+	}
+
+	map[normalized.length] = original.length;
+	return map;
+}
+
+export function fuzzyFindText(
+	content: string,
+	oldText: string,
+): { found: boolean; index: number; matchLength: number; isExact: boolean } {
+	// Try exact match first
+	const exactIndex = content.indexOf(oldText);
+	if (exactIndex !== -1) {
+		return { found: true, index: exactIndex, matchLength: oldText.length, isExact: true };
+	}
+
+	// Try trimmed match, returning original indices
+	const normalizedContent = normalizeForMatch(content);
+	const normalizedOld = normalizeForMatch(oldText);
+	const fuzzyIndex = normalizedContent.indexOf(normalizedOld);
+	if (fuzzyIndex !== -1) {
+		const map = buildPositionMap(content);
+		const originalStart = map[fuzzyIndex];
+		const originalEnd = map[fuzzyIndex + normalizedOld.length];
+		return { found: true, index: originalStart, matchLength: originalEnd - originalStart, isExact: false };
+	}
+
+	return { found: false, index: -1, matchLength: 0, isExact: false };
+}
+
+function countOccurrences(content: string, oldText: string): number {
+	const normalizedContent = normalizeForMatch(content);
+	const normalizedOld = normalizeForMatch(oldText);
+	let count = 0;
+	let pos = 0;
+	while (true) {
+		const idx = normalizedContent.indexOf(normalizedOld, pos);
+		if (idx === -1) break;
+		count++;
+		pos = idx + normalizedOld.length;
+	}
+	return count;
+}
+
+function countExactOccurrences(content: string, oldText: string): number {
+	let count = 0;
+	let pos = 0;
+	while (true) {
+		const idx = content.indexOf(oldText, pos);
+		if (idx === -1) break;
+		count++;
+		pos = idx + oldText.length;
+	}
+	return count;
+}
+
+// ---------------------------------------------------------------------------
+// Edit application
+// ---------------------------------------------------------------------------
+
+function applyFuzzyEdit(
+	content: string,
+	matchIndex: number,
+	matchLength: number,
+	oldText: string,
+	newText: string,
+): string {
+	const before = content.substring(0, matchIndex);
+	const after = content.substring(matchIndex + matchLength);
+	const matched = content.substring(matchIndex, matchIndex + matchLength);
+
+	const matchedLines = matched.split("\n");
+	const oldLines = oldText.split("\n");
+	const newLines = newText.split("\n");
+
+	const resultLines: string[] = [];
+	for (let i = 0; i < newLines.length; i++) {
+		const newLine = newLines[i];
+		const oldLine = oldLines[i] ?? "";
+		const matchedLine = matchedLines[i] ?? "";
+
+		const oldTrailing = oldLine.length - oldLine.trimEnd().length;
+		const matchedTrailing = matchedLine.length - matchedLine.trimEnd().length;
+
+		if (matchedTrailing > oldTrailing) {
+			const extraStart = matchedLine.trimEnd().length + oldTrailing;
+			resultLines.push(newLine + matchedLine.slice(extraStart));
+		} else {
+			resultLines.push(newLine);
+		}
+	}
+
+	return before + resultLines.join("\n") + after;
+}
+
+export function applyEdits(
+	content: string,
+	edits: EditReplacement[],
+	filePath: string,
+): { newContent: string; blocksChanged: number } {
+	const normalizedEdits = edits.map((e) => ({
+		oldText: normalizeToLF(e.f),
+		newText: normalizeToLF(e.r),
+	}));
+
+	// Validate non-empty
+	for (let i = 0; i < normalizedEdits.length; i++) {
+		if (normalizedEdits[i].oldText.length === 0) {
+			throw new Error(`edits[${i}].f (oldText) must not be empty in ${filePath}.`);
+		}
+	}
+
+	const baseContent = content;
+
+	// Match all edits
+	interface MatchResult {
+		editIndex: number;
+		matchIndex: number;
+		matchLength: number;
+		newText: string;
+		oldText: string;
+		isExact: boolean;
+	}
+
+	const matchedEdits: MatchResult[] = [];
+	for (let i = 0; i < normalizedEdits.length; i++) {
+		const edit = normalizedEdits[i];
+		const matchResult = fuzzyFindText(baseContent, edit.oldText);
+
+		if (!matchResult.found) {
+			throw new Error(
+				edits.length === 1
+					? `Could not find the exact text in ${filePath}. The old text must match exactly including all whitespace and newlines.`
+					: `Could not find edits[${i}] in ${filePath}. The f (oldText) must match exactly including all whitespace and newlines.`,
+			);
+		}
+
+		const occurrences = matchResult.isExact
+			? countExactOccurrences(baseContent, edit.oldText)
+			: countOccurrences(baseContent, edit.oldText);
+		if (occurrences > 1) {
+			throw new Error(
+				edits.length === 1
+					? `Found ${occurrences} occurrences of the text in ${filePath}. The text must be unique. Please provide more context to make it unique.`
+					: `Found ${occurrences} occurrences of edits[${i}] in ${filePath}. Each f (oldText) must be unique. Please provide more context to make it unique.`,
+			);
+		}
+
+		matchedEdits.push({
+			editIndex: i,
+			matchIndex: matchResult.index,
+			matchLength: matchResult.matchLength,
+			newText: edit.newText,
+			oldText: edit.oldText,
+			isExact: matchResult.isExact,
+		});
+	}
+
+	// Sort by position (ascending)
+	matchedEdits.sort((a, b) => a.matchIndex - b.matchIndex);
+
+	// Check for overlaps
+	for (let i = 1; i < matchedEdits.length; i++) {
+		const previous = matchedEdits[i - 1];
+		const current = matchedEdits[i];
+		if (previous.matchIndex + previous.matchLength > current.matchIndex) {
+			throw new Error(
+				`edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in ${filePath}. Merge them into one edit or target disjoint regions.`,
+			);
+		}
+	}
+
+	// Apply edits in reverse order to preserve offsets
+	let newContent = baseContent;
+	for (let i = matchedEdits.length - 1; i >= 0; i--) {
+		const edit = matchedEdits[i];
+		if (edit.isExact) {
+			newContent =
+				newContent.substring(0, edit.matchIndex) +
+				edit.newText +
+				newContent.substring(edit.matchIndex + edit.matchLength);
+		} else {
+			newContent = applyFuzzyEdit(
+				newContent,
+				edit.matchIndex,
+				edit.matchLength,
+				edit.oldText,
+				edit.newText,
+			);
+		}
+	}
+
+	if (baseContent === newContent) {
+		throw new Error(
+			edits.length === 1
+				? `No changes made to ${filePath}. The replacement produced identical content.`
+				: `No changes made to ${filePath}. The replacements produced identical content.`,
+		);
+	}
+
+	return {
+		newContent,
+		blocksChanged: matchedEdits.length,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Path validation
+// ---------------------------------------------------------------------------
+
+export function expandTilde(inputPath: string): string {
+	if (inputPath === "~") return os.homedir();
+	if (inputPath.startsWith("~/")) return path.join(os.homedir(), inputPath.slice(2));
+	return inputPath;
+}
+
+export function isWithinDirectory(child: string, parent: string): boolean {
+	if (process.platform === "win32") {
+		const childLower = child.toLowerCase();
+		const parentLower = parent.toLowerCase();
+		if (childLower === parentLower) return true;
+		const sep = path.win32.sep;
+		const prefix = parentLower.endsWith(sep) ? parentLower : parentLower + sep;
+		return childLower.startsWith(prefix);
+	}
+	if (child === parent) return true;
+	if (parent === "/") return child.startsWith("/");
+	return child.startsWith(parent + path.sep);
+}
+
+export async function validatePath(inputPath: string, cwd: string): Promise<string> {
+	const expandedPath = expandTilde(inputPath);
+	return path.resolve(cwd, expandedPath);
+}
+
+// ---------------------------------------------------------------------------
+// Levenshtein distance (used by execute for suggestions)
+// ---------------------------------------------------------------------------
+
+export function levenshtein(a: string, b: string): number {
+	const m = a.length;
+	const n = b.length;
+	const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+	for (let i = 0; i <= m; i++) dp[i][0] = i;
+	for (let j = 0; j <= n; j++) dp[0][j] = j;
+	for (let i = 1; i <= m; i++) {
+		for (let j = 1; j <= n; j++) {
+			dp[i][j] =
+				a[i - 1] === b[j - 1]
+					? dp[i - 1][j - 1]
+					: 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+		}
+	}
+	return dp[m][n];
+}

package/src/batch/index.ts

@@ -0,0 +1,364 @@
+/**
+ * batch — tool definition factory.
+ *
+ * Creates the `batch` and `batch_read` tool instances with schema, argument
+ * preparation, execution, and rendering wired up.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { BatchTheme, FileOpInput } from "./constants.js";
+import { SAFE_FULL_READ_LIMIT, TARGETED_READ_LINE_LIMIT } from "./constants.js";
+import { executeOperations, suggestSimilarFiles } from "./execute.js";
+import { expandTilde, isWithinDirectory } from "./fuzzy-edit.js";
+import {
+	renderBatchCall,
+	renderBatchReadCall,
+	renderBatchResult,
+} from "./render.js";
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const EditOp = Type.Object({
+	f: Type.String({
+		description:
+			"Exact text to find (oldText). Must be unique in the file. All edits matched against original file, not incrementally.",
+	}),
+	r: Type.String({ description: "Replacement text (newText)." }),
+});
+
+const FileOp = Type.Object({
+	o: Type.Union([
+		Type.Literal("read"),
+		Type.Literal("write"),
+		Type.Literal("edit"),
+		Type.Literal("delete"),
+	]),
+	p: Type.String({ description: "Path to the file (relative or absolute)" }),
+	c: Type.Optional(
+		Type.String({
+			description:
+				"Full file content. Creates if new, overwrites if exists. Auto-creates parent dirs. Used with o: 'write'.",
+		}),
+	),
+	e: Type.Optional(
+		Type.Array(EditOp, {
+			description:
+				"One or more targeted replacements matched against the original file, not incrementally.",
+		}),
+	),
+	s: Type.Optional(
+		Type.Number({
+			minimum: 1,
+			description:
+				"1-indexed line number to start reading from (offset). Used with o: 'read'.",
+		}),
+	),
+	l: Type.Optional(
+		Type.Number({
+			minimum: 1,
+			description:
+				"Maximum number of lines to read (limit). Used with o: 'read'.",
+		}),
+	),
+});
+
+export const WeavePatchParams = Type.Object({
+	o: Type.Array(FileOp, {
+		description:
+			"Ordered list of file operations. Executed sequentially. On failure, remaining operations are skipped.",
+	}),
+});
+
+export const BatchReadParams = Type.Object({
+	o: Type.Array(
+		Type.Object({
+			o: Type.Literal("read"),
+			p: Type.String({ description: "Path to the file (relative or absolute)" }),
+			s: Type.Optional(
+				Type.Number({
+					minimum: 1,
+					description:
+						"1-indexed line number to start reading from (offset). Used with o: 'read'.",
+				}),
+			),
+			l: Type.Optional(
+				Type.Number({
+					minimum: 1,
+					description:
+						"Maximum number of lines to read (limit). Used with o: 'read'.",
+				}),
+			),
+		}),
+		{
+			description:
+				"Ordered list of read operations. Executed sequentially. On failure, remaining operations are skipped.",
+		},
+	),
+});
+
+// ---------------------------------------------------------------------------
+// Argument preparation
+// ---------------------------------------------------------------------------
+
+function normalizeOp(raw: Record<string, unknown>): Record<string, unknown> {
+	const op: Record<string, unknown> = {};
+
+	// Map operation type
+	op.o = raw.o ?? raw.op ?? (raw.c != null || raw.content != null ? "write" : (raw.e != null || raw.edits != null ? "edit" : "read"));
+
+	// Map path
+	op.p = raw.p ?? raw.path;
+
+	// Map content
+	if (raw.c !== undefined) op.c = raw.c;
+	else if (raw.content !== undefined) op.c = raw.content;
+
+	// Map edits
+	let editsRaw = raw.e ?? raw.edits;
+	if (typeof editsRaw === "string") {
+		try { editsRaw = JSON.parse(editsRaw); } catch { /* ignore */ }
+	}
+	if (Array.isArray(editsRaw)) {
+		op.e = editsRaw.map((e: unknown) => {
+			if (!e || typeof e !== "object") return e;
+			const edit = e as Record<string, unknown>;
+			return { f: edit.f ?? edit.oldText, r: edit.r ?? edit.newText };
+		});
+	}
+
+	// Map offset / limit
+	if (raw.s !== undefined) op.s = raw.s;
+	else if (raw.offset !== undefined) op.s = raw.offset;
+	if (raw.l !== undefined) op.l = raw.l;
+	else if (raw.limit !== undefined) op.l = raw.limit;
+
+	return op;
+}
+
+function prepareArguments(input: unknown): { o: unknown[] } | unknown {
+	if (!input || typeof input !== "object") return { o: [] };
+
+	const args = input as Record<string, unknown>;
+
+	// Handle legacy top-level format: { path, oldText, newText }
+	if (
+		typeof args.oldText === "string" &&
+		typeof args.newText === "string" &&
+		typeof args.path === "string"
+	) {
+		return {
+			o: [
+				normalizeOp({
+					o: "edit",
+					p: args.path,
+					e: [{ oldText: args.oldText, newText: args.newText }],
+				}),
+			],
+		};
+	}
+
+	// Extract ops array — canonical { o: [...] }, legacy { op: [...] }, legacy { operations: [...] }, or bare array
+	let opsArray: unknown[];
+	if (Array.isArray(args.o)) {
+		opsArray = args.o;
+	} else if (Array.isArray(args.op)) {
+		opsArray = args.op;
+	} else if (Array.isArray(args.operations)) {
+		opsArray = args.operations;
+	} else if (Array.isArray(args)) {
+		opsArray = args;
+	} else if (typeof args.p === "string" || typeof args.path === "string") {
+		// Single-operation shorthand: { p: "...", o: "read" }
+		opsArray = [args];
+	} else {
+		return { o: [] };
+	}
+
+	// Normalize each operation to single-letter form
+	return {
+		o: opsArray.map((op: unknown) => {
+			if (!op || typeof op !== "object") return op;
+			return normalizeOp(op as Record<string, unknown>);
+		}),
+	};
+}
+
+function prepareBatchReadArguments(input: unknown): { o: FileOpInput[] } | unknown {
+	const prepared = prepareArguments(input);
+	const ops = Array.isArray(prepared) ? prepared : (prepared as { o: unknown[] }).o;
+	if (!Array.isArray(ops)) return { o: [] };
+
+	for (const op of ops) {
+		if (!op || typeof op !== "object") continue;
+		const obj = op as Record<string, unknown>;
+		const opType = String(obj.o ?? obj.op ?? "").toLowerCase();
+		if (opType && opType !== "read") {
+			throw new Error(`batch_read only supports read operations. Received: ${opType}`);
+		}
+	}
+	return prepared;
+}
+
+// ---------------------------------------------------------------------------
+// Tool factories
+// ---------------------------------------------------------------------------
+
+export function createBatchReadTool() {
+	return {
+		name: "batch_read",
+		label: "batch_read",
+		description: [
+			"Batch read-only file operations — run multiple read ops in a single call.",
+			"Each operation is independent and executes sequentially in array order; on failure, remaining operations are skipped.",
+			`Full-file reads up to ${SAFE_FULL_READ_LIMIT} lines return raw content; larger full-file reads return a context map for code/infra files or total lines for plain text.`,
+			`Targeted reads with l over ${TARGETED_READ_LINE_LIMIT} are clamped with a continuation warning; a single line over the byte limit still errors.`,
+			"Use `o: \"read\"` with `s` (offset) and `l` (limit) for targeted reading. Prefer this over bash sed/head/tail.",
+			"Best for reading multiple files or sections in one call.",
+		].join("\n"),
+		promptSnippet: "Batch read-only file operations — run multiple read ops in one call",
+		promptGuidelines: [
+			"Use batch_read to perform multiple file reads in a single call rather than separate tool calls.",
+			"Prefer batch_read when reading 2+ files or multiple sections of the same file.",
+			`Small full-file reads (<=${SAFE_FULL_READ_LIMIT} lines) return raw content; larger full-file reads return navigable context maps or line counts.`,
+			`Use targeted reads with s/l around context-map entries; targeted reads are capped at ${TARGETED_READ_LINE_LIMIT} lines.`,
+			"Do not retry the same full-file read when a context map is returned.",
+		],
+		parameters: BatchReadParams,
+		prepareArguments: prepareBatchReadArguments,
+
+		async execute(
+			_toolCallId: string,
+			input: unknown,
+			signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: { cwd: string },
+		) {
+			let prepared: unknown;
+			try {
+				prepared = prepareBatchReadArguments(input);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return {
+					content: [{ type: "text", text: `Error: ${message}` }],
+					isError: true,
+				};
+			}
+
+			const ops = Array.isArray(prepared)
+				? (prepared as FileOpInput[])
+				: (prepared as { o: FileOpInput[] }).o;
+
+			if (!Array.isArray(ops) || ops.length === 0) {
+				return {
+					content: [
+						{ type: "text", text: "Error: o array is required and must not be empty." },
+					],
+					isError: true,
+				};
+			}
+
+			// Defensive validation: reject any non-read operations
+			for (const op of ops) {
+				if (op.o !== "read") {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Error: batch_read only supports read operations. Received ${op.o} for ${op.p}.`,
+							},
+						],
+						isError: true,
+					};
+				}
+			}
+
+			if (signal?.aborted) {
+				return {
+					content: [{ type: "text", text: "Operation aborted." }],
+					isError: true,
+				};
+			}
+
+			const { contentText, results } = await executeOperations(ops, ctx.cwd, signal, {
+				readOptions: { truncate: false, toolName: "batch_read" },
+				includeLimitWarnings: false,
+			});
+
+			return {
+				content: [{ type: "text", text: contentText }],
+				details: { results },
+			};
+		},
+
+		renderCall: (args: Record<string, unknown>, theme: BatchTheme) => renderBatchReadCall(args, theme),
+		renderResult: (result: any, { expanded }: { expanded: boolean }, theme: BatchTheme, args?: Record<string, unknown>) =>
+			renderBatchResult(result, expanded, theme, args),
+	};
+}
+
+export function createBatchTool() {
+	return {
+		name: "batch",
+		label: "batch",
+		description: [
+			"Batch file operations — run multiple read, write, edit, or delete ops in a single call.",
+			"Each operation is independent: edits are matched against the current on-disk file, not against prior operations in the same call.",
+			"Operations execute sequentially in array order; on failure, remaining operations are skipped.",
+			"Use `o: \"read\"` with `s` (offset) and `l` (limit) for targeted reading. Prefer this over bash sed/head/tail.",
+			"Best for cross-cutting changes, multi-file refactors, or mixing reads with writes across several files.",
+		].join("\n"),
+		promptSnippet: "Batch file operations — run multiple read/write/edit/delete ops in one call",
+		promptGuidelines: [
+			"Use batch to perform multiple file operations in a single call rather than separate tool calls.",
+			"Prefer batch when touching 2+ files or mixing creates, edits, reads, and deletes.",
+			"Each operation is independent — edits match the on-disk file, not prior ops in the same call.",
+			"For single-file edits, the edit tool is fine; batch shines for cross-cutting and multi-file work.",
+		],
+		parameters: WeavePatchParams,
+		prepareArguments: prepareArguments,
+
+		async execute(
+			_toolCallId: string,
+			input: unknown,
+			signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: { cwd: string },
+		) {
+			const prepared = prepareArguments(input);
+			// prepareArguments always returns { o: [...] }, but handle
+			// legacy bare arrays for backward compatibility
+			const ops = Array.isArray(prepared)
+				? prepared as FileOpInput[]
+				: (prepared as { o: FileOpInput[] }).o;
+
+			if (!Array.isArray(ops) || ops.length === 0) {
+				return {
+					content: [
+						{ type: "text", text: "Error: o array is required and must not be empty." },
+					],
+					isError: true,
+				};
+			}
+
+			if (signal?.aborted) {
+				return {
+					content: [{ type: "text", text: "Operation aborted." }],
+					isError: true,
+				};
+			}
+
+			const { contentText, results } = await executeOperations(ops, ctx.cwd, signal);
+
+			return {
+				content: [{ type: "text", text: contentText }],
+				details: { results },
+			};
+		},
+
+		renderCall: (args: Record<string, unknown>, theme: BatchTheme) => renderBatchCall(args, theme),
+		renderResult: (result: any, { expanded }: { expanded: boolean }, theme: BatchTheme, args?: Record<string, unknown>) =>
+			renderBatchResult(result, expanded, theme, args),
+	};
+}