@shanepadgett/tau-agent 0.1.0

package/extensions/patch/executor.ts

@@ -0,0 +1,355 @@
+import { access, mkdir, readFile, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { applyChunksWithRanges, countLogicalLines, UpdateChunkApplyError } from "./matcher.ts";
+import { type PatchFailure, type PatchOperation, parsePatch } from "./parser.ts";
+
+export interface ApplyPatchChange {
+	sectionIndex: number;
+	kind: PatchOperation["type"];
+	path: string;
+	move?: { from: string; to: string };
+	linesAdded: number;
+	linesRemoved: number;
+	snapshotRanges?: Array<{ startLine: number; endLine: number }>;
+}
+
+export interface ApplyPatchSummary {
+	status: "completed" | "partial" | "failed";
+	changes: ApplyPatchChange[];
+	failures: PatchFailure[];
+	totalSections: number;
+}
+
+export interface ApplyPatchStats {
+	added: string[];
+	replaced: string[];
+	updated: string[];
+	deleted: string[];
+	moved: Array<{ from: string; to: string }>;
+	linesAdded: number;
+	linesRemoved: number;
+	completedOperations: number;
+}
+
+export function deriveStats(summary: ApplyPatchSummary): ApplyPatchStats {
+	const added: string[] = [];
+	const replaced: string[] = [];
+	const updated: string[] = [];
+	const deleted: string[] = [];
+	const moved: Array<{ from: string; to: string }> = [];
+	let linesAdded = 0;
+	let linesRemoved = 0;
+	for (const c of summary.changes) {
+		if (c.kind === "add") added.push(c.path);
+		else if (c.kind === "replace") replaced.push(c.path);
+		else if (c.kind === "delete") deleted.push(c.path);
+		else {
+			updated.push(c.move?.to ?? c.path);
+			if (c.move) moved.push(c.move);
+		}
+		linesAdded += c.linesAdded;
+		linesRemoved += c.linesRemoved;
+	}
+	return {
+		added,
+		replaced,
+		updated,
+		deleted,
+		moved,
+		linesAdded,
+		linesRemoved,
+		completedOperations: summary.changes.length,
+	};
+}
+
+interface StagedMutation {
+	change: ApplyPatchChange;
+	commit(): Promise<void>;
+}
+
+// lean: resolve(cwd,path) without realpath collapse; OK for typical working trees without symlinked dirs;
+// upgrade to realpath ancestor walk when symlink-based dedup collisions appear
+function resolvePath(cwd: string, rawPath: string): string {
+	const input = rawPath.trim();
+	if (!input) throw new Error("Path must not be empty.");
+	return isAbsolute(input) ? resolve(input) : resolve(cwd, input);
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw new Error("Operation aborted");
+}
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function readUtf8(path: string, displayPath: string): Promise<string> {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		const message = error instanceof Error && "code" in error ? `Error code: ${error.code}` : String(error);
+		throw new Error(`Could not read file: ${displayPath}. ${message}.`);
+	}
+}
+
+async function assertExistingFile(path: string, displayPath: string): Promise<void> {
+	if (!(await pathExists(path))) throw new Error(`Path does not exist: ${displayPath}`);
+	const info = await stat(path);
+	if (!info.isFile()) throw new Error(`Expected a file: ${displayPath}`);
+}
+
+async function removeEmptyParentDirs(cwd: string, startDir: string): Promise<void> {
+	let current = resolve(startDir);
+	const root = resolve(cwd);
+	while (current !== root) {
+		const rel = relative(root, current);
+		if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return;
+		try {
+			await rmdir(current);
+		} catch {
+			return;
+		}
+		current = dirname(current);
+	}
+}
+
+async function stageWholeFile(
+	cwd: string,
+	op: Extract<PatchOperation, { type: "add" | "replace" }>,
+): Promise<StagedMutation> {
+	const target = resolvePath(cwd, op.path);
+	let linesRemoved = 0;
+	if (await pathExists(target)) {
+		linesRemoved = countLogicalLines(await readUtf8(target, op.path));
+	}
+	const lineCount = countLogicalLines(op.content);
+	return {
+		change: {
+			sectionIndex: op.sectionIndex,
+			kind: op.type,
+			path: op.path,
+			linesAdded: op.linesAdded,
+			linesRemoved,
+			snapshotRanges: lineCount > 0 ? [{ startLine: 1, endLine: Math.min(lineCount, 120) }] : undefined,
+		},
+		async commit() {
+			await mkdir(dirname(target), { recursive: true });
+			await writeFile(target, op.content, "utf8");
+		},
+	};
+}
+
+async function stageDelete(cwd: string, op: Extract<PatchOperation, { type: "delete" }>): Promise<StagedMutation> {
+	const target = resolvePath(cwd, op.path);
+	await assertExistingFile(target, op.path);
+	const current = await readUtf8(target, op.path);
+	return {
+		change: {
+			sectionIndex: op.sectionIndex,
+			kind: "delete",
+			path: op.path,
+			linesAdded: 0,
+			linesRemoved: countLogicalLines(current),
+		},
+		async commit() {
+			await unlink(target);
+			await removeEmptyParentDirs(cwd, dirname(target));
+		},
+	};
+}
+
+async function stageUpdate(cwd: string, op: Extract<PatchOperation, { type: "update" }>): Promise<StagedMutation> {
+	const source = resolvePath(cwd, op.path);
+	await assertExistingFile(source, op.path);
+	const current = await readUtf8(source, op.path);
+	const result = op.chunks.length > 0 ? applyChunksWithRanges(current, op.chunks) : undefined;
+	const next = result?.content ?? current;
+	const moveTarget = op.movePath ? resolvePath(cwd, op.movePath) : undefined;
+
+	if (!moveTarget || moveTarget === source) {
+		return {
+			change: {
+				sectionIndex: op.sectionIndex,
+				kind: "update",
+				path: op.path,
+				linesAdded: op.linesAdded,
+				linesRemoved: op.linesRemoved,
+				snapshotRanges: result?.snapshotRanges,
+			},
+			async commit() {
+				await writeFile(source, next, "utf8");
+			},
+		};
+	}
+
+	const movePath = op.movePath;
+	if (!movePath) throw new Error("Move target path is missing.");
+	if (await pathExists(moveTarget)) {
+		throw new Error(
+			`move target already exists: ${movePath}. Move targets must be unused to avoid overwriting existing files.`,
+		);
+	}
+	return {
+		change: {
+			sectionIndex: op.sectionIndex,
+			kind: "update",
+			path: movePath,
+			move: { from: op.path, to: movePath },
+			linesAdded: op.linesAdded,
+			linesRemoved: op.linesRemoved,
+			snapshotRanges: result?.snapshotRanges,
+		},
+		async commit() {
+			await mkdir(dirname(moveTarget), { recursive: true });
+			await writeFile(moveTarget, next, "utf8");
+			await unlink(source);
+			await removeEmptyParentDirs(cwd, dirname(source));
+		},
+	};
+}
+
+function collectDupPathFailures(cwd: string, operations: PatchOperation[]): PatchFailure[] {
+	const pathSections = new Map<string, number[]>();
+	const displayPaths = new Map<string, string>();
+
+	for (const op of operations) {
+		const paths = [resolvePath(cwd, op.path)];
+		if (op.type === "update" && op.movePath) paths.push(resolvePath(cwd, op.movePath));
+
+		for (const p of paths) {
+			const existing = pathSections.get(p) ?? [];
+			existing.push(op.sectionIndex);
+			pathSections.set(p, existing);
+			if (!displayPaths.has(p)) displayPaths.set(p, op.path);
+		}
+	}
+
+	const failures: PatchFailure[] = [];
+	for (const [canonical, sections] of pathSections) {
+		if (sections.length <= 1) continue;
+		const display = displayPaths.get(canonical) ?? canonical;
+		for (const sectionIndex of sections) {
+			failures.push({
+				phase: "apply",
+				sectionIndex,
+				path: display,
+				message: `conflicting operations for path: ${display} (sections ${sections.join(", ")}). Use Add File or Replace File for whole-file writes, or split dependent changes into separate patches.`,
+			});
+		}
+	}
+	return failures;
+}
+
+function withMutationQueuePaths<T>(paths: string[], fn: () => Promise<T>): Promise<T> {
+	const unique = Array.from(new Set(paths)).sort();
+	let current = fn;
+	for (const path of unique.reverse()) {
+		const next = current;
+		current = () => withFileMutationQueue(path, next);
+	}
+	return current();
+}
+
+export async function applyPatch(
+	cwd: string,
+	input: string,
+	signal?: AbortSignal,
+	onProgress?: (summary: ApplyPatchSummary) => void | Promise<void>,
+): Promise<ApplyPatchSummary> {
+	throwIfAborted(signal);
+	const { operations, parseFailures, totalSections } = parsePatch(input);
+
+	if (operations.length === 0) {
+		const summary: ApplyPatchSummary = {
+			status: "failed",
+			changes: [],
+			failures: parseFailures,
+			totalSections: totalSections || 1,
+		};
+		await onProgress?.(summary);
+		return summary;
+	}
+
+	const dupFailures = collectDupPathFailures(cwd, operations);
+	const initialFailures = [...parseFailures, ...dupFailures];
+	const blockedSections = new Set(initialFailures.map((failure) => failure.sectionIndex));
+	const runnableOperations = operations.filter((op) => !blockedSections.has(op.sectionIndex));
+
+	const queuePaths = runnableOperations.flatMap((op) => {
+		const paths = [resolvePath(cwd, op.path)];
+		if (op.type === "update" && op.movePath) paths.push(resolvePath(cwd, op.movePath));
+		return paths;
+	});
+
+	return withMutationQueuePaths(queuePaths, async () => {
+		const staged: StagedMutation[] = [];
+		const failures: PatchFailure[] = [...initialFailures];
+
+		for (const op of runnableOperations) {
+			try {
+				if (op.type === "add" || op.type === "replace") staged.push(await stageWholeFile(cwd, op));
+				else if (op.type === "delete") staged.push(await stageDelete(cwd, op));
+				else staged.push(await stageUpdate(cwd, op));
+			} catch (error) {
+				if (error instanceof Error && error.message === "Operation aborted") throw error;
+				const failure: PatchFailure = {
+					phase: "apply",
+					sectionIndex: op.sectionIndex,
+					path: op.path,
+					kind: op.type,
+					message: error instanceof Error ? error.message : String(error),
+				};
+				if (error instanceof UpdateChunkApplyError) {
+					failure.chunkIndex = error.chunkIndex;
+					failure.totalChunks = error.totalChunks;
+					failure.contextHint = error.contextHint;
+				}
+				failures.push(failure);
+			}
+		}
+
+		if (staged.length === 0) {
+			const summary: ApplyPatchSummary = { status: "failed", changes: [], failures, totalSections };
+			await onProgress?.(summary);
+			return summary;
+		}
+
+		throwIfAborted(signal);
+
+		const changes: ApplyPatchChange[] = [];
+		for (const mutation of staged) {
+			try {
+				await mutation.commit();
+				changes.push(mutation.change);
+				await onProgress?.({ status: "partial", changes: [...changes], failures: [...failures], totalSections });
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				failures.push({
+					phase: "apply",
+					sectionIndex: mutation.change.sectionIndex,
+					path: mutation.change.path,
+					kind: mutation.change.kind,
+					message,
+				});
+				const status = changes.length === 0 ? "failed" : "partial";
+				const summary: ApplyPatchSummary = {
+					status,
+					changes: [...changes],
+					failures: [...failures],
+					totalSections,
+				};
+				await onProgress?.(summary);
+				return summary;
+			}
+		}
+
+		const status: ApplyPatchSummary["status"] = failures.length > 0 ? "partial" : "completed";
+		return { status, changes, failures, totalSections };
+	});
+}

package/extensions/patch/index.ts

@@ -0,0 +1,170 @@
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { emitTauEvent } from "../../shared/events.js";
+import { createToolRowStateStore } from "../../shared/tool-row-state.js";
+import { type ApplyPatchSummary, applyPatch } from "./executor.ts";
+import { renderPatchCall, renderPatchResult } from "./render.ts";
+import { formatPatchSummary } from "./summary.ts";
+
+const SUPPRESSED_TOOLS = new Set(["edit", "write"]);
+
+const patchParams = Type.Object({
+	input: Type.String({
+		description: [
+			'Pass the full patch as this input string. Tool call arguments must be exactly { "input": "*** Begin Patch\\n...\\n*** End Patch" }; never put the patch text in a JSON object key.',
+			"",
+			"Apply one structured multi-file patch. Put the full patch text in this field.",
+			"",
+			"ENVELOPE",
+			"*** Begin Patch",
+			"[one or more file sections]",
+			"*** End Patch",
+			"",
+			"Patch marker lines may have leading/trailing whitespace. File content starts after the patch prefix and keeps the remaining text exactly.",
+			"Malformed envelopes fail the whole patch. Section parse, match, duplicate-path, missing-file, and move-target errors fail those sections while independent valid sections still apply.",
+			"",
+			"SECTIONS",
+			"*** Add File: <path>        whole-file write; only + lines become content; may overwrite",
+			"*** Replace File: <path>    whole-file write reported as replacement; only + lines become content",
+			"*** Update File: <path>     contextual edit of an existing file",
+			"*** Move to: <new-path>     optional, first line after Update File header, before any hunks; target must not exist",
+			"*** Delete File: <path>     removes an existing file; must be the only line in its section",
+			"",
+			"UPDATE HUNKS",
+			"@@ or @@ <context line>      optional chunk marker; context marker moves the search cursor after that existing line",
+			" context line               space prefix; old and new text",
+			"-removed line               removed old text",
+			"+added line                 added new text",
+			"*** End of File             optional EOF-sensitive match / append marker",
+			"",
+			"RULES",
+			"- One section per touched path per patch.",
+			"- Read files before writing Update File patches so context and removed lines match current content.",
+			"- Use context body lines for positional inserts. A pure + update chunk appends to EOF.",
+			"- Unanchored repeated matches use the first forward match.",
+			"- The @@ context marker is not changed by the hunk. To change that line, include it as a -/+ body line.",
+			"- Fuzzy matching tolerates minor trailing whitespace, smart quote/dash, and Unicode-space differences; context body lines are kept from the original file.",
+			"- If a match fails, read the current file content and retry with corrected lines.",
+			"",
+			"EXAMPLE",
+			"*** Begin Patch",
+			"*** Add File: src/new-module.ts",
+			'+export const version = "1.0.0";',
+			"*** Replace File: src/generated.ts",
+			"+export const generated = true;",
+			"*** Update File: src/config.ts",
+			" export const PORT = 3000;",
+			"-export const DEBUG = false;",
+			"+export const DEBUG = true;",
+			"*** Update File: src/old-name.ts",
+			"*** Move to: src/new-name.ts",
+			" const handler = () => {}",
+			"-module.exports = handler;",
+			"+export default handler;",
+			"*** Delete File: src/deprecated.ts",
+			"*** End Patch",
+		].join("\n"),
+	}),
+});
+
+function createPatchTool(rowState: ReturnType<typeof createToolRowStateStore>) {
+	return defineTool<typeof patchParams, ApplyPatchSummary>({
+		name: "patch",
+		label: "Patch",
+		description:
+			"Apply a multi-file patch to create, edit, move, and delete files. Use it as the default for hand-authored file mutations across one or many files, including large writes; use shell commands or scripts when they express mechanical bulk changes with fewer tokens and less risk. Invalid sections fail independently when possible.",
+		promptSnippet: "Apply multi-file patches to create, edit, move, and delete files",
+		promptGuidelines: [
+			'Call patch with arguments shaped exactly as { "input": "*** Begin Patch\\n...\\n*** End Patch" }. Do not put the patch body in a JSON key.',
+			"Use patch as the default for hand-authored file mutations: creates, replacements, updates, moves, and deletes across one or many files, including large writes.",
+			"Use shell commands or scripts when they are the lower-token, clearer, safer representation of mechanical bulk work: copying template trees, moving many files, running generators, or applying repeated transforms. Inspect generated, copied, or scripted results before hand-editing them.",
+			"Use one envelope: *** Begin Patch, one or more sections, then *** End Patch.",
+			"Use one section per touched path. Include adds, replaces, updates, deletes, and moves together when possible; retry failed sections separately when needed.",
+			"Before writing Update File patches, read every file you need to touch so context and removed lines match current content.",
+			"In Update File hunks, one leading prefix is syntax: space for context, - for removed text, + for added text. The rest of the line is file text.",
+			"Use context body lines for positional inserts. A pure + update chunk appends to EOF.",
+			"Unanchored repeated matches use the first forward match. Anchor hunks on distinctive nearby lines when matching could be ambiguous; avoid lone braces or generic repeated lines.",
+			"The @@ context marker moves the search cursor after that existing line; the marker line itself is not changed by the hunk.",
+			"Move targets must not already exist.",
+			"If a match fails, read the current file content and retry with corrected lines.",
+		],
+		parameters: patchParams,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const input = params.input.replace(/\r\n/g, "\n").trim();
+			const summary = await applyPatch(ctx.cwd, input, signal, async (progress) => {
+				await onUpdate?.({
+					content: [{ type: "text", text: formatPatchSummary(progress) }],
+					details: progress,
+				});
+			});
+
+			return {
+				content: [{ type: "text", text: formatPatchSummary(summary) }],
+				details: summary,
+			};
+		},
+
+		renderCall(args, theme, context) {
+			return renderPatchCall(args as { input?: string }, theme, {
+				expanded: context.expanded,
+				executionStarted: context.executionStarted,
+				isPartial: context.isPartial,
+				lastComponent: context.lastComponent,
+				rowState,
+				rowId: context.toolCallId,
+				invalidate: context.invalidate,
+			});
+		},
+
+		renderResult(result, options, theme, context) {
+			return renderPatchResult(result, { expanded: options.expanded }, theme, {
+				expanded: options.expanded,
+				args: context.args as { input?: string },
+				lastComponent: context.lastComponent,
+				rowState,
+				rowId: context.toolCallId,
+				invalidate: context.invalidate,
+			});
+		},
+	});
+}
+
+export default function patchExtension(pi: ExtensionAPI): void {
+	const rowState = createToolRowStateStore(pi, "patch.tool-row-state");
+	pi.registerTool(createPatchTool(rowState));
+
+	// AgentToolResult has no isError field, so execute returns are always treated as success.
+	// Override via tool_result to flag partial/failed patches as errors for the model and UI.
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.toolName !== "patch") return;
+		const summary = event.details as ApplyPatchSummary | undefined;
+		if (summary) {
+			emitTauEvent(pi, "tau:file-mutation.applied", {
+				source: "patch",
+				toolCallId: event.toolCallId,
+				cwd: ctx.cwd,
+				status: summary.status,
+				changes: summary.changes.map((change) => ({
+					path: change.path,
+					kind: change.kind,
+					move: change.move,
+					linesAdded: change.linesAdded,
+					linesRemoved: change.linesRemoved,
+					snapshotRanges: change.snapshotRanges,
+				})),
+			});
+		}
+		if (!summary || summary.status === "completed") return;
+		return { isError: true };
+	});
+
+	pi.on("session_start", () => {
+		rowState.clear();
+		const active = new Set(pi.getActiveTools());
+		active.add("patch");
+		for (const tool of SUPPRESSED_TOOLS) active.delete(tool);
+		pi.setActiveTools([...active]);
+	});
+}