pi-hashline-edit-pro 0.2.0

package/src/read.ts

@@ -0,0 +1,256 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	createReadTool,
+	formatSize,
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	truncateHead,
+	type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { readFileSync } from "fs";
+import { access as fsAccess } from "fs/promises";
+import { constants } from "fs";
+import { normalizeToLF, stripBom } from "./edit-diff";
+import { loadFileKindAndText } from "./file-kind";
+import { computeLineHashes, formatHashlineRegion } from "./hashline";
+import { resolveToCwd } from "./path-utils";
+import { throwIfAborted } from "./runtime";
+import { getFileSnapshot } from "./snapshot";
+
+const READ_DESC = readFileSync(
+	new URL("../prompts/read.md", import.meta.url),
+	"utf-8",
+)
+	.replaceAll("{{DEFAULT_MAX_LINES}}", String(DEFAULT_MAX_LINES))
+	.replaceAll("{{DEFAULT_MAX_BYTES}}", formatSize(DEFAULT_MAX_BYTES))
+	.trim();
+
+const READ_PROMPT_SNIPPET = readFileSync(
+	new URL("../prompts/read-snippet.md", import.meta.url),
+	"utf-8",
+).trim();
+
+const READ_PROMPT_GUIDELINES = readFileSync(
+	new URL("../prompts/read-guidelines.md", import.meta.url),
+	"utf-8",
+)
+	.split("\n")
+	.map((line) => line.trim())
+	.filter((line) => line.startsWith("- "))
+	.map((line) => line.slice(2));
+
+function normalizePositiveInteger(
+	value: number | undefined,
+	name: "offset" | "limit",
+): number | undefined {
+	if (value === undefined) {
+		return undefined;
+	}
+
+	if (!Number.isInteger(value) || value < 1) {
+		throw new Error(`Read request field "${name}" must be a positive integer.`);
+	}
+
+	return value;
+}
+
+function getPreviewLines(text: string): string[] {
+	if (text.length === 0) {
+		return [];
+	}
+
+	const lines = text.split("\n");
+	return text.endsWith("\n") ? lines.slice(0, -1) : lines;
+}
+
+export function formatHashlineReadPreview(
+	text: string,
+	options: { offset?: number; limit?: number },
+	precomputedHashes?: string[],
+): { text: string; truncation?: TruncationResult; nextOffset?: number } {
+	const allLines = getPreviewLines(text);
+	const totalLines = allLines.length;
+	const startLine = normalizePositiveInteger(options.offset, "offset") ?? 1;
+	if (totalLines === 0) {
+		if (startLine === 1) {
+			return {
+				text: "File is empty. Use edit with prepend or append and omit pos to insert content.",
+			};
+		}
+
+		return {
+			text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use edit with prepend or append and omit pos to insert content.`,
+		};
+	}
+
+	if (startLine > totalLines) {
+		return {
+			text: `Offset ${startLine} is beyond end of file (${totalLines} lines total). Use offset=1 to read from the start, or offset=${totalLines} to read the last line.`,
+		};
+	}
+
+	const limit = normalizePositiveInteger(options.limit, "limit");
+	const endIdx = limit
+		? Math.min(startLine - 1 + limit, totalLines)
+		: totalLines;
+	const selected = allLines.slice(startLine - 1, endIdx);
+	// The runtime precomputes the full per-line hash array so the model sees
+	// hashes consistent with what validation will compare against. Callers that
+	// already have one (the read tool, chained-edit tests) can pass it in;
+	// otherwise we recompute here for the visible window — acceptable for
+	// preview formatting because the hashes themselves are identical regardless
+	// of which slice of the file we look at.
+	const allHashes = precomputedHashes ?? computeLineHashes(text);
+	const selectedHashes = allHashes.slice(startLine - 1, endIdx);
+	const formatted = formatHashlineRegion(selectedHashes, selected);
+
+	const truncation = truncateHead(formatted);
+	if (truncation.firstLineExceedsLimit) {
+		return {
+			text: `[Line ${startLine} exceeds ${formatSize(truncation.maxBytes)}. Hashline output requires full lines; cannot compute hashes for a truncated preview.]`,
+			truncation,
+		};
+	}
+
+	let preview = truncation.content;
+	let nextOffset: number | undefined;
+	if (truncation.truncated) {
+		const endLineDisplay = startLine + truncation.outputLines - 1;
+		nextOffset = endLineDisplay + 1;
+		if (truncation.truncatedBy === "lines") {
+			preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
+		} else {
+			preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines} (${formatSize(truncation.maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
+		}
+	} else if (endIdx < totalLines) {
+		nextOffset = endIdx + 1;
+		preview += `\n\n[Showing lines ${startLine}-${endIdx} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
+	}
+
+	return {
+		text: preview,
+		truncation: truncation.truncated ? truncation : undefined,
+		...(nextOffset !== undefined ? { nextOffset } : {}),
+	};
+}
+
+export function registerReadTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "read",
+		label: "Read",
+		description: READ_DESC,
+		promptSnippet: READ_PROMPT_SNIPPET,
+		promptGuidelines: READ_PROMPT_GUIDELINES,
+		parameters: Type.Object({
+			path: Type.String({
+				description: "Path to the file to read (relative or absolute)",
+			}),
+			offset: Type.Optional(
+				Type.Integer({
+					minimum: 1,
+					description: "Line number to start reading from (1-indexed)",
+				}),
+			),
+			limit: Type.Optional(
+				Type.Integer({
+					minimum: 1,
+					description: "Maximum number of lines to read",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const rawPath = params.path;
+			const absolutePath = resolveToCwd(rawPath, ctx.cwd);
+
+			throwIfAborted(signal);
+			try {
+				await fsAccess(absolutePath, constants.R_OK);
+			} catch (error: unknown) {
+				const code =
+					error instanceof Error
+						? (error as NodeJS.ErrnoException).code
+						: undefined;
+				if (code === "ENOENT") {
+					throw new Error(`File not found: ${rawPath}`);
+				}
+				if (code === "EACCES" || code === "EPERM") {
+					throw new Error(`File is not readable: ${rawPath}`);
+				}
+				throw new Error(`Cannot access file: ${rawPath}`);
+			}
+
+			throwIfAborted(signal);
+			const file = await loadFileKindAndText(absolutePath);
+			if (file.kind === "directory") {
+				throw new Error(
+					`Path is a directory: ${rawPath}. Use ls to inspect directories.`,
+				);
+			}
+
+			if (file.kind === "binary") {
+				throw new Error(
+					`Path is a binary file: ${rawPath} (${file.description}). Hashline read only supports text files and supported images.`,
+				);
+			}
+
+			if (file.kind === "image") {
+				const builtinRead = createReadTool(ctx.cwd);
+				const executeBuiltinRead = builtinRead.execute as unknown as (
+					toolCallId: string,
+					input: typeof params,
+					abortSignal: typeof signal,
+					onUpdate: typeof _onUpdate,
+					context: typeof ctx,
+				) => ReturnType<typeof builtinRead.execute>;
+				return executeBuiltinRead(_toolCallId, params, signal, _onUpdate, ctx);
+			}
+
+			throwIfAborted(signal);
+			const normalized = normalizeToLF(stripBom(file.text).text);
+			// Compute hashes once for the whole file so the per-line anchors the
+			// model sees here are byte-identical to what the edit tool will
+			// compute when it later validates against this file.
+			const fileHashes = computeLineHashes(normalized);
+			const preview = formatHashlineReadPreview(
+				normalized,
+				{
+					offset: params.offset,
+					limit: params.limit,
+				},
+				fileHashes,
+			);
+			const snapshot = await getFileSnapshot(absolutePath);
+
+			// Invalid UTF-8 bytes are decoded as U+FFFD, matching Pi's built-in
+			// tools. Warn only when the decoder reported invalid bytes; a literal,
+			// valid U+FFFD in a UTF-8 file should not be treated as lossy decoding.
+			const previewText =
+				file.hadUtf8DecodeErrors === true
+					? `${preview.text}\n\n[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]`
+					: preview.text;
+
+			return {
+				content: [{ type: "text", text: previewText }],
+				details: {
+					truncation: preview.truncation,
+					// snapshotId remains in details for host UI (e.g. "file changed since
+					// last view"). It is NOT echoed in text — the LLM no longer needs it.
+					snapshotId: snapshot.snapshotId,
+					...(preview.nextOffset !== undefined
+						? { nextOffset: preview.nextOffset }
+						: {}),
+					// Phase 2 C — host-only observability. Truncated reads usually mean
+					// a follow-up read with `offset = next_offset` is coming.
+					metrics: {
+						truncated: !!preview.truncation,
+						...(preview.nextOffset !== undefined
+							? { next_offset: preview.nextOffset }
+							: {}),
+					},
+				},
+			};
+		},
+	});
+}

package/src/runtime.ts

@@ -0,0 +1,3 @@
+export function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new Error("Operation aborted");
+}

package/src/snapshot.ts

@@ -0,0 +1,29 @@
+import { stat } from "fs/promises";
+import { resolveMutationTargetPath } from "./fs-write";
+
+export type SnapshotInfo = {
+  snapshotId: string;
+  mtimeMs: number;
+  size: number;
+};
+
+function formatSnapshotId(canonicalPath: string, info: { mtimeMs: number; size: number }): string {
+  return `v1|${canonicalPath}|${info.mtimeMs}|${info.size}`;
+}
+
+/**
+ * Stat the file and return its current snapshot fingerprint.
+ *
+ * The snapshot is exposed only via `details.snapshotId` for host UIs (e.g.
+ * "file changed since last view"). It is no longer used to reject edits or
+ * surfaced in tool text — the LLM does not need to track it.
+ */
+export async function getFileSnapshot(absolutePath: string): Promise<SnapshotInfo> {
+  const canonicalPath = await resolveMutationTargetPath(absolutePath);
+  const stats = await stat(canonicalPath);
+  return {
+    snapshotId: formatSnapshotId(canonicalPath, stats),
+    mtimeMs: stats.mtimeMs,
+    size: stats.size,
+  };
+}

package/src/utils.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared type guards and utility helpers.
+ */
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function hasOwn(record: Record<string, unknown>, key: string): boolean {
+	return Object.hasOwn(record, key);
+}