@schlenkr/ragents 0.1.0

package/packages/agent/src/core/tools/edit.ts

@@ -0,0 +1,222 @@
+import { createHash } from "node:crypto";
+import type { AgentTool } from "@aicontainer/agent-core";
+import { constants } from "fs";
+import { access as fsAccess, readFile as fsReadFile, writeFile as fsWriteFile } from "fs/promises";
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+import { applyEditsToNormalizedContent, detectLineEnding, type Edit, generateDiffString, generateUnifiedPatch, normalizeToLF, restoreLineEndings, stripBom } from "./edit-diff.ts";
+import { withFileMutationQueue } from "./file-mutation-queue.ts";
+import { resolveToCwd } from "./path-utils.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+
+const replaceEditSchema = Type.Object(
+	{
+		oldText: Type.String({
+			description:
+				"Exact text for one targeted replacement. It must be unique in the original file unless occurrence, nearLine or replaceAll is set, and must not overlap with any other edits[].oldText in the same call.",
+		}),
+		newText: Type.String({ description: "Replacement text for this targeted edit." }),
+		occurrence: Type.Optional(
+			Type.Number({
+				description:
+					"1-based index of the occurrence to replace when oldText is not unique. A failed edit lists all occurrences with their line numbers, so pick the index from that list.",
+			}),
+		),
+		nearLine: Type.Optional(
+			Type.Number({
+				description:
+					"1-based line number near the intended occurrence. The occurrence closest to it wins; a tie is an error.",
+			}),
+		),
+		replaceAll: Type.Optional(
+			Type.Boolean({
+				description:
+					"Replace every occurrence of oldText. Cannot be combined with occurrence or nearLine, and must not be used to change only some of them.",
+			}),
+		),
+	},
+	{},
+);
+
+const editSchema = Type.Object(
+	{
+		path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
+		expectedHash: Type.Optional(Type.String({
+			description: "SHA-256 from the latest read. The edit is rejected if the file changed since that read.",
+			pattern: "^[a-f0-9]{64}$",
+		})),
+		edits: Type.Array(replaceEditSchema, {
+			description:
+				"One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.",
+		}),
+	},
+	{},
+);
+
+export type EditToolInput = Static<typeof editSchema>;
+type LegacyEditToolInput = EditToolInput & {
+	oldText?: unknown;
+	newText?: unknown;
+};
+
+export interface EditToolDetails {
+	/** Display-oriented diff of the changes made */
+	diff: string;
+	/** Standard unified patch of the changes made */
+	patch: string;
+	/** Line number of the first change in the new file (for editor navigation) */
+	firstChangedLine?: number;
+	contentHash: string;
+}
+
+/**
+ * Pluggable operations for the edit tool.
+ * Override these to delegate file editing to remote systems (for example SSH).
+ */
+export interface EditOperations {
+	/** Read file contents as a Buffer */
+	readFile: (absolutePath: string) => Promise<Buffer>;
+	/** Write content to a file */
+	writeFile: (absolutePath: string, content: string) => Promise<void>;
+	/** Check if file is readable and writable (throw if not) */
+	access: (absolutePath: string) => Promise<void>;
+}
+
+const defaultEditOperations: EditOperations = {
+	readFile: (path) => fsReadFile(path),
+	writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
+	access: (path) => fsAccess(path, constants.R_OK | constants.W_OK),
+};
+
+export interface EditToolOptions {
+	/** Custom operations for file editing. Default: local filesystem */
+	operations?: EditOperations;
+}
+
+function prepareEditArguments(input: unknown): EditToolInput {
+	if (!input || typeof input !== "object") {
+		return input as EditToolInput;
+	}
+
+	const args = input as Record<string, unknown>;
+
+	// Some models (Opus 4.6, GLM-5.1) send edits as a JSON string instead of an array
+	if (typeof args.edits === "string") {
+		try {
+			const parsed = JSON.parse(args.edits);
+			if (Array.isArray(parsed)) args.edits = parsed;
+		} catch {}
+	}
+
+	const legacy = args as LegacyEditToolInput;
+	if (typeof legacy.oldText !== "string" || typeof legacy.newText !== "string") {
+		return args as EditToolInput;
+	}
+
+	const edits = Array.isArray(legacy.edits) ? [...legacy.edits] : [];
+	edits.push({ oldText: legacy.oldText, newText: legacy.newText });
+	const { oldText: _oldText, newText: _newText, ...rest } = legacy;
+	return { ...rest, edits } as EditToolInput;
+}
+
+function validateEditInput(input: EditToolInput): { path: string; edits: Edit[] } {
+	if (!Array.isArray(input.edits) || input.edits.length === 0) {
+		throw new Error("Edit tool input is invalid. edits must contain at least one replacement.");
+	}
+	return { path: input.path, edits: input.edits };
+}
+
+export function createEditToolDefinition(
+	cwd: string,
+	options?: EditToolOptions,
+): ToolDefinition<typeof editSchema, EditToolDetails | undefined> {
+	const ops = options?.operations ?? defaultEditOperations;
+	return {
+		name: "edit",
+		label: "edit",
+		description:
+			"Edit a single file using exact text replacement. Pass expectedHash from the latest read so the edit is rejected if the file changed meanwhile. Every edits[].oldText must match a unique, non-overlapping region of the original file, or be anchored with occurrence, nearLine or replaceAll. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes.",
+		promptSnippet:
+			"Make precise file edits with exact text replacement, including multiple disjoint edits in one call",
+		promptGuidelines: [
+			"Use edit for precise changes (edits[].oldText must match exactly)",
+			"When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls",
+			"Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.",
+			"Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
+			"If oldText is not unique, the error lists every occurrence with its line number. Pick one with occurrence (1-based) or nearLine instead of padding oldText with more context, and use replaceAll only when every occurrence must change.",
+			"Pass expectedHash from the latest read so an edit cannot overwrite a file that changed since you inspected it.",
+		],
+		parameters: editSchema,
+		renderShell: "self",
+		prepareArguments: prepareEditArguments,
+		async execute(_toolCallId, input: EditToolInput, signal?: AbortSignal, _onUpdate?, _ctx?) {
+			const { path, edits } = validateEditInput(input);
+			const absolutePath = resolveToCwd(path, cwd);
+
+			return withFileMutationQueue(absolutePath, async () => {
+				// Do not reject from an abort event listener here: that would release the
+				// mutation queue while an in-flight filesystem operation may still finish.
+				// Checking signal.aborted after each await observes the same aborts while
+				// keeping the queue locked until the current operation has settled.
+				const throwIfAborted = (): void => {
+					if (signal?.aborted) throw new Error("Operation aborted");
+				};
+
+				throwIfAborted();
+
+				// Check if file exists.
+				try {
+					await ops.access(absolutePath);
+				} catch (error: unknown) {
+					throwIfAborted();
+					const errorMessage =
+						error instanceof Error && "code" in error ? `Error code: ${error.code}` : String(error);
+					throw new Error(`Could not edit file: ${path}. ${errorMessage}.`);
+				}
+				throwIfAborted();
+
+				// Read the file.
+				const buffer = await ops.readFile(absolutePath);
+				const currentHash = createHash("sha256").update(buffer).digest("hex");
+				if (input.expectedHash && input.expectedHash !== currentHash) {
+					throw new Error(`Could not edit ${path}: stale read. Expected SHA-256 ${input.expectedHash}, current SHA-256 ${currentHash}. Read the file again before editing.`);
+				}
+				const rawContent = buffer.toString("utf-8");
+				throwIfAborted();
+
+				// Strip BOM before matching. The model will not include an invisible BOM in oldText.
+				const { bom, text: content } = stripBom(rawContent);
+				const originalEnding = detectLineEnding(content);
+				const normalizedContent = normalizeToLF(content);
+				const { baseContent, newContent, replacementCount } = applyEditsToNormalizedContent(
+					normalizedContent,
+					edits,
+					path,
+				);
+				throwIfAborted();
+
+				const finalContent = bom + restoreLineEndings(newContent, originalEnding);
+				await ops.writeFile(absolutePath, finalContent);
+				throwIfAborted();
+				const contentHash = createHash("sha256").update(finalContent).digest("hex");
+
+				const diffResult = generateDiffString(baseContent, newContent);
+				const patch = generateUnifiedPatch(path, baseContent, newContent);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Successfully replaced ${replacementCount} block(s) in ${path}. New content SHA-256: ${contentHash}.`,
+						},
+					],
+					details: { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine, contentHash },
+				};
+			});
+		},
+
+	};
+}
+
+export function createEditTool(cwd: string, options?: EditToolOptions): AgentTool<typeof editSchema> {
+	return wrapToolDefinition(createEditToolDefinition(cwd, options));
+}

package/packages/agent/src/core/tools/file-mutation-queue.ts

@@ -0,0 +1,61 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const fileMutationQueues = new Map<string, Promise<void>>();
+let registrationQueue = Promise.resolve();
+
+function isMissingPathError(error: unknown): boolean {
+	return (
+		typeof error === "object" &&
+		error !== null &&
+		"code" in error &&
+		(error.code === "ENOENT" || error.code === "ENOTDIR")
+	);
+}
+
+async function getMutationQueueKey(filePath: string): Promise<string> {
+	const resolvedPath = resolve(filePath);
+	try {
+		return await realpath(resolvedPath);
+	} catch (error) {
+		if (isMissingPathError(error)) {
+			return resolvedPath;
+		}
+		throw error;
+	}
+}
+
+/**
+ * Serialize file mutation operations targeting the same file.
+ * Operations for different files still run in parallel.
+ */
+export async function withFileMutationQueue<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+	const registration = registrationQueue.then(async () => {
+		const key = await getMutationQueueKey(filePath);
+		const currentQueue = fileMutationQueues.get(key) ?? Promise.resolve();
+
+		let releaseNext!: () => void;
+		const nextQueue = new Promise<void>((resolveQueue) => {
+			releaseNext = resolveQueue;
+		});
+		const chainedQueue = currentQueue.then(() => nextQueue);
+		fileMutationQueues.set(key, chainedQueue);
+
+		return { key, currentQueue, chainedQueue, releaseNext };
+	});
+	registrationQueue = registration.then(
+		() => undefined,
+		() => undefined,
+	);
+
+	const { key, currentQueue, chainedQueue, releaseNext } = await registration;
+	await currentQueue;
+	try {
+		return await fn();
+	} finally {
+		releaseNext();
+		if (fileMutationQueues.get(key) === chainedQueue) {
+			fileMutationQueues.delete(key);
+		}
+	}
+}

package/packages/agent/src/core/tools/index.ts

@@ -0,0 +1,130 @@
+export {
+	type BashOperations,
+	type BashSpawnContext,
+	type BashSpawnHook,
+	type BashToolDetails,
+	type BashToolInput,
+	type BashToolOptions,
+	createBashTool,
+	createBashToolDefinition,
+	createLocalBashOperations,
+} from "./bash.ts";
+export {
+	createEditTool,
+	createEditToolDefinition,
+	type EditOperations,
+	type EditToolDetails,
+	type EditToolInput,
+	type EditToolOptions,
+} from "./edit.ts";
+export { withFileMutationQueue } from "./file-mutation-queue.ts";
+export {
+	createReadTool,
+	createReadToolDefinition,
+	type ReadOperations,
+	type ReadToolDetails,
+	type ReadToolInput,
+	type ReadToolOptions,
+} from "./read.ts";
+export {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	type TruncationOptions,
+	type TruncationResult,
+	truncateHead,
+	truncateLine,
+	truncateTail,
+} from "./truncate.ts";
+export {
+	createWriteTool,
+	createWriteToolDefinition,
+	type WriteOperations,
+	type WriteToolInput,
+	type WriteToolOptions,
+} from "./write.ts";
+
+import type { AgentTool } from "@aicontainer/agent-core";
+import type { ToolDefinition } from "../extensions/types.ts";
+import { type BashToolOptions, createBashTool, createBashToolDefinition } from "./bash.ts";
+import { createEditTool, createEditToolDefinition, type EditToolOptions } from "./edit.ts";
+import { createReadTool, createReadToolDefinition, type ReadToolOptions } from "./read.ts";
+import { createWriteTool, createWriteToolDefinition, type WriteToolOptions } from "./write.ts";
+
+export type Tool = AgentTool<any>;
+export type ToolDef = ToolDefinition<any, any>;
+export type ToolName = "read" | "bash" | "edit" | "write";
+export const allToolNames: Set<ToolName> = new Set(["read", "bash", "edit", "write"]);
+
+export interface ToolsOptions {
+	read?: ReadToolOptions;
+	bash?: BashToolOptions;
+	write?: WriteToolOptions;
+	edit?: EditToolOptions;
+}
+
+export function createToolDefinition(toolName: ToolName, cwd: string, options?: ToolsOptions): ToolDef {
+	switch (toolName) {
+		case "read":
+			return createReadToolDefinition(cwd, options?.read);
+		case "bash":
+			return createBashToolDefinition(cwd, options?.bash);
+		case "edit":
+			return createEditToolDefinition(cwd, options?.edit);
+		case "write":
+			return createWriteToolDefinition(cwd, options?.write);
+		default:
+			throw new Error(`Unknown tool name: ${toolName}`);
+	}
+}
+
+export function createTool(toolName: ToolName, cwd: string, options?: ToolsOptions): Tool {
+	switch (toolName) {
+		case "read":
+			return createReadTool(cwd, options?.read);
+		case "bash":
+			return createBashTool(cwd, options?.bash);
+		case "edit":
+			return createEditTool(cwd, options?.edit);
+		case "write":
+			return createWriteTool(cwd, options?.write);
+		default:
+			throw new Error(`Unknown tool name: ${toolName}`);
+	}
+}
+
+export function createCodingToolDefinitions(cwd: string, options?: ToolsOptions): ToolDef[] {
+	return [
+		createReadToolDefinition(cwd, options?.read),
+		createBashToolDefinition(cwd, options?.bash),
+		createEditToolDefinition(cwd, options?.edit),
+		createWriteToolDefinition(cwd, options?.write),
+	];
+}
+
+export function createAllToolDefinitions(cwd: string, options?: ToolsOptions): Record<ToolName, ToolDef> {
+	return {
+		read: createReadToolDefinition(cwd, options?.read),
+		bash: createBashToolDefinition(cwd, options?.bash),
+		edit: createEditToolDefinition(cwd, options?.edit),
+		write: createWriteToolDefinition(cwd, options?.write),
+	};
+}
+
+export function createCodingTools(cwd: string, options?: ToolsOptions): Tool[] {
+	return [
+		createReadTool(cwd, options?.read),
+		createBashTool(cwd, options?.bash),
+		createEditTool(cwd, options?.edit),
+		createWriteTool(cwd, options?.write),
+	];
+}
+
+export function createAllTools(cwd: string, options?: ToolsOptions): Record<ToolName, Tool> {
+	return {
+		read: createReadTool(cwd, options?.read),
+		bash: createBashTool(cwd, options?.bash),
+		edit: createEditTool(cwd, options?.edit),
+		write: createWriteTool(cwd, options?.write),
+	};
+}

package/packages/agent/src/core/tools/output-accumulator.ts

@@ -0,0 +1,222 @@
+import { randomBytes } from "node:crypto";
+import { createWriteStream, type WriteStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult, truncateTail } from "./truncate.ts";
+
+export interface OutputAccumulatorOptions {
+	maxLines?: number;
+	maxBytes?: number;
+	tempFilePrefix?: string;
+}
+
+export interface OutputSnapshot {
+	content: string;
+	truncation: TruncationResult;
+	fullOutputPath?: string;
+}
+
+function defaultTempFilePath(prefix: string): string {
+	const id = randomBytes(8).toString("hex");
+	return join(tmpdir(), `${prefix}-${id}.log`);
+}
+
+function byteLength(text: string): number {
+	return Buffer.byteLength(text, "utf-8");
+}
+
+/**
+ * Incrementally tracks streaming output with bounded memory.
+ *
+ * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded
+ * tail for display snapshots, and opens a temp file when the full output needs
+ * to be preserved.
+ */
+export class OutputAccumulator {
+	private readonly maxLines: number;
+	private readonly maxBytes: number;
+	private readonly maxRollingBytes: number;
+	private readonly tempFilePrefix: string;
+	private readonly decoder = new TextDecoder();
+
+	private rawChunks: Buffer[] = [];
+	private tailText = "";
+	private tailBytes = 0;
+	private tailStartsAtLineBoundary = true;
+	private totalRawBytes = 0;
+	private totalDecodedBytes = 0;
+	private completedLines = 0;
+	private totalLines = 0;
+	private currentLineBytes = 0;
+	private hasOpenLine = false;
+	private finished = false;
+
+	private tempFilePath: string | undefined;
+	private tempFileStream: WriteStream | undefined;
+
+	constructor(options: OutputAccumulatorOptions = {}) {
+		this.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+		this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+		this.maxRollingBytes = Math.max(this.maxBytes * 2, 1);
+		this.tempFilePrefix = options.tempFilePrefix ?? "agent-output";
+	}
+
+	append(data: Buffer): void {
+		if (this.finished) {
+			throw new Error("Cannot append to a finished output accumulator");
+		}
+
+		this.totalRawBytes += data.length;
+		this.appendDecodedText(this.decoder.decode(data, { stream: true }));
+
+		if (this.tempFileStream || this.shouldUseTempFile()) {
+			this.ensureTempFile();
+			this.tempFileStream?.write(data);
+		} else if (data.length > 0) {
+			this.rawChunks.push(data);
+		}
+	}
+
+	finish(): void {
+		if (this.finished) {
+			return;
+		}
+		this.finished = true;
+		this.appendDecodedText(this.decoder.decode());
+		if (this.shouldUseTempFile()) {
+			this.ensureTempFile();
+		}
+	}
+
+	snapshot(options: { persistIfTruncated?: boolean } = {}): OutputSnapshot {
+		const tailTruncation = truncateTail(this.getSnapshotText(), {
+			maxLines: this.maxLines,
+			maxBytes: this.maxBytes,
+		});
+		const truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes;
+		const truncatedBy = truncated
+			? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes ? "bytes" : "lines"))
+			: null;
+		const truncation: TruncationResult = {
+			...tailTruncation,
+			truncated,
+			truncatedBy,
+			totalLines: this.totalLines,
+			totalBytes: this.totalDecodedBytes,
+			maxLines: this.maxLines,
+			maxBytes: this.maxBytes,
+		};
+
+		if (options.persistIfTruncated && truncation.truncated) {
+			this.ensureTempFile();
+		}
+
+		return {
+			content: truncation.content,
+			truncation,
+			fullOutputPath: this.tempFilePath,
+		};
+	}
+
+	async closeTempFile(): Promise<void> {
+		if (!this.tempFileStream) {
+			return;
+		}
+
+		const stream = this.tempFileStream;
+		this.tempFileStream = undefined;
+
+		await new Promise<void>((resolve, reject) => {
+			const onError = (error: Error) => {
+				stream.off("finish", onFinish);
+				reject(error);
+			};
+			const onFinish = () => {
+				stream.off("error", onError);
+				resolve();
+			};
+			stream.once("error", onError);
+			stream.once("finish", onFinish);
+			stream.end();
+		});
+	}
+
+	getLastLineBytes(): number {
+		return this.currentLineBytes;
+	}
+
+	private appendDecodedText(text: string): void {
+		if (text.length === 0) {
+			return;
+		}
+
+		const bytes = byteLength(text);
+		this.totalDecodedBytes += bytes;
+		this.tailText += text;
+		this.tailBytes += bytes;
+		if (this.tailBytes > this.maxRollingBytes * 2) {
+			this.trimTail();
+		}
+
+		let newlines = 0;
+		let lastNewline = -1;
+		for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) {
+			newlines++;
+			lastNewline = i;
+		}
+		if (newlines === 0) {
+			this.currentLineBytes += bytes;
+			this.hasOpenLine = true;
+		} else {
+			this.completedLines += newlines;
+			const tail = text.slice(lastNewline + 1);
+			this.currentLineBytes = byteLength(tail);
+			this.hasOpenLine = tail.length > 0;
+		}
+		this.totalLines = this.completedLines + (this.hasOpenLine ? 1 : 0);
+	}
+
+	private trimTail(): void {
+		const buffer = Buffer.from(this.tailText, "utf-8");
+		if (buffer.length <= this.maxRollingBytes) {
+			this.tailBytes = buffer.length;
+			return;
+		}
+
+		let start = buffer.length - this.maxRollingBytes;
+		while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {
+			start++;
+		}
+
+		this.tailStartsAtLineBoundary = start === 0 ? this.tailStartsAtLineBoundary : buffer[start - 1] === 0x0a;
+		this.tailText = buffer.subarray(start).toString("utf-8");
+		this.tailBytes = byteLength(this.tailText);
+	}
+
+	private getSnapshotText(): string {
+		if (this.tailStartsAtLineBoundary) {
+			return this.tailText;
+		}
+
+		const firstNewline = this.tailText.indexOf("\n");
+		return firstNewline === -1 ? this.tailText : this.tailText.slice(firstNewline + 1);
+	}
+
+	private shouldUseTempFile(): boolean {
+		return (
+			this.totalRawBytes > this.maxBytes || this.totalDecodedBytes > this.maxBytes || this.totalLines > this.maxLines
+		);
+	}
+
+	private ensureTempFile(): void {
+		if (this.tempFilePath) {
+			return;
+		}
+		this.tempFilePath = defaultTempFilePath(this.tempFilePrefix);
+		this.tempFileStream = createWriteStream(this.tempFilePath);
+		for (const chunk of this.rawChunks) {
+			this.tempFileStream.write(chunk);
+		}
+		this.rawChunks = [];
+	}
+}