pi-hashline-edit-pro 0.9.4 → 0.9.6

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 RimuruW
+Copyright (c) 2026 RimuruW and Yugimob
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/index.ts

@@ -6,23 +6,20 @@ import { registerReplaceTool } from "./src/replace";
 import { registerReadTool } from "./src/read";
 import { normalizeToLF } from "./src/replace-diff";
 import { getVisibleLines } from "./src/utils";
+import { AUTO_READ_MAX_LINES } from "./src/constants";
 
 export default function (pi: ExtensionAPI): void {
   registerReadTool(pi);
   registerReplaceTool(pi);
 
-  // Disable the built-in `edit` tool so the model uses `replace` instead.
   pi.on("session_start", async (_event, ctx) => {
     const active = pi.getActiveTools();
     pi.setActiveTools(active.filter((t) => t !== "edit"));
   });
 
-  // Auto-read after write state - controlled by PI_HASHLINE_AUTO_READ env var (default: disabled).
-  // Can be toggled at runtime via /toggle-auto-read command.
   const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;
   let autoReadEnabled = autoReadValue === "1" || autoReadValue === "true";
 
-  // Register toggle-auto-read command
   pi.registerCommand("toggle-auto-read", {
     description: "Toggle automatic hashline anchors after write operations",
     handler: async (_args, ctx) => {
@@ -32,7 +29,6 @@ export default function (pi: ExtensionAPI): void {
     },
   });
 
-  // Auto-read after write handler - always registered, but checks the flag
   pi.on("tool_result", async (event, ctx) => {
     if (!autoReadEnabled) return;
     if (event.toolName !== "write" || event.isError) return;
@@ -44,24 +40,20 @@ export default function (pi: ExtensionAPI): void {
       const absolutePath = isAbsolute(filePath) ? filePath : join(ctx.cwd, filePath);
       const content = await readFile(absolutePath, "utf-8");
 
-      // Normalize and compute hashline output
       const normalized = normalizeToLF(content);
       const visibleLines = getVisibleLines(normalized);
 
       if (visibleLines.length === 0) return;
 
-      // Truncate to a reasonable limit to avoid excessive token usage
-      const MAX_LINES = 2000;
-      const truncated = visibleLines.length > MAX_LINES;
-      const displayLines = truncated ? visibleLines.slice(0, MAX_LINES) : visibleLines;
+      const truncated = visibleLines.length > AUTO_READ_MAX_LINES;
+      const displayLines = truncated ? visibleLines.slice(0, AUTO_READ_MAX_LINES) : visibleLines;
 
       const hashes = computeLineHashes(normalized);
       const selectedHashes = hashes.slice(0, displayLines.length);
       const hashlineOutput = formatHashlineRegion(selectedHashes, displayLines);
 
-      // Add pagination hint if truncated
       const paginationHint = truncated
-        ? `\n\n[Showing lines 1-${MAX_LINES} of ${visibleLines.length}. Use offset=${MAX_LINES + 1} to continue.]`
+        ? `\n\n[Showing lines 1-${AUTO_READ_MAX_LINES} of ${visibleLines.length}. Use offset=${AUTO_READ_MAX_LINES + 1} to continue.]`
         : "";
 
       if (hashlineOutput) {
@@ -73,7 +65,6 @@ export default function (pi: ExtensionAPI): void {
         };
       }
     } catch {
-      // Auto-read failure should not affect write result
     }
   });
 
@@ -83,4 +74,4 @@ export default function (pi: ExtensionAPI): void {
       ctx.ui.notify("Hashline Edit mode active", "info");
     });
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
   "repository": {

package/prompts/replace-guidelines.md

@@ -1,3 +1,3 @@
 - Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
-- After a successful `replace`, the returned `--- Anchors ---` block has fresh hashes for nearby follow-up replaces.
-- On `[E_STALE_ANCHOR]`, retry with the `>>>` lines quoted in the error instead of re-reading the whole file.
+- After a successful `replace`, the response text is empty (warnings only). Call `read` to get fresh anchors for follow-up edits.
+- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH from each line into `old_range`, and retry.

package/src/constants.ts

@@ -0,0 +1,5 @@
+export const AUTO_READ_MAX_LINES = 2000;
+export const CHANGED_ANCHOR_TEXT_BUDGET_BYTES = 50 * 1024;
+export const ANCHOR_CONTEXT_LINES = 0;
+export const ANCHOR_MAX_OUTPUT_LINES = 12;
+export const FILE_TYPE_SNIFF_BYTES = 8192;

package/src/file-kind.ts

@@ -1,5 +1,6 @@
 import { open as fsOpen, stat as fsStat } from "fs/promises";
 import { fileTypeFromBuffer } from "file-type";
+import { FILE_TYPE_SNIFF_BYTES } from "./constants";
 
 const IMAGE_MIME_TYPES = new Set<string>([
 	"image/jpeg",
@@ -18,8 +19,6 @@ function isTextLikeMimeType(mimeType: string): boolean {
 	return mimeType.startsWith("text/") || TEXT_LIKE_MIME_TYPES.has(mimeType);
 }
 
-const FILE_TYPE_SNIFF_BYTES = 8192;
-
 export type FileKind =
 	| { kind: "directory" }
 	| { kind: "image"; mimeType: string }
@@ -84,12 +83,6 @@ export async function loadFileKindAndText(
 			};
 		}
 
-		// Non-fatal decode, matching pi's built-in tools: invalid UTF-8 becomes
-		// U+FFFD rather than rejecting the file. The null-byte guard above is the
-		// only signal we treat as binary, so non-UTF-8 text (CP1251, GBK, …) reads
-		// instead of forcing the model to bypass hashline with raw shell edits.
-		// Track fatal-decoder failures separately so a literal, valid U+FFFD in a
-		// UTF-8 file does not get mistaken for lossy decoding.
 		const decoder = new TextDecoder("utf-8");
 		const fatalDecoder = new TextDecoder("utf-8", { fatal: true });
 		let hadUtf8DecodeErrors = false;
@@ -158,4 +151,4 @@ export async function classifyFileKind(filePath: string): Promise<FileKind> {
 		case "text":
 			return { kind: "text" };
 	}
-}
+}

package/src/hashline/apply.ts

@@ -1,4 +1,3 @@
-
 import { throwIfAborted } from "../runtime";
 import { computeLineHashes } from "./hash";
 import {
@@ -13,7 +12,7 @@ import {
 	type BoundaryDuplicationWarning,
 } from "./resolve";
 import { countVisibleLines } from "../utils";
-
+import { ANCHOR_CONTEXT_LINES, ANCHOR_MAX_OUTPUT_LINES } from "../constants";
 
 type LineIndex = {
 	fileLines: string[];
@@ -236,7 +235,6 @@ export function applyHashlineEdits(
 			lastChangedLine: undefined,
 		};
 
-	// Normalize new_lines: [""] to new_lines: [] for deletion.
 	edits = edits.map((edit) =>
 		edit.new_lines.length === 1 &&
 		edit.new_lines[0] === ""
@@ -278,9 +276,6 @@ export function applyHashlineEdits(
 	assertDoesNotEmptyFile(content, result);
 	const changedRange = computeChangedLineRange(content, result);
 
-	// Reconstruct boundary duplication warnings with post-edit hashes.
-	// Use position + occurrence to find the exact surviving line (handles
-	// files with multiple identical lines like several `}` closings).
 	const resultLines = result.split("\n");
 	const resultHashes = computeLineHashes(result);
 	for (const bw of boundaryWarnings) {
@@ -316,9 +311,6 @@ export function applyHashlineEdits(
 }
 
 
-const ANCHOR_CONTEXT_LINES = 0;
-const ANCHOR_MAX_OUTPUT_LINES = 12;
-
 export function computeAffectedLineRange(params: {
 	firstChangedLine: number | undefined;
 	lastChangedLine: number | undefined;
@@ -338,8 +330,6 @@ export function computeAffectedLineRange(params: {
 		return null;
 	}
 
-	// When contextLines is 0, skip the anchor block entirely.
-	// The LLM already knows what it changed and can call read for fresh anchors.
 	if (contextLines === 0) {
 		return null;
 	}
@@ -405,6 +395,7 @@ export function computeChangedLineRange(
 	}
 	if (firstDiff === minLen && original.length === result.length) return null;
 
+
 	let lastOrig = original.length - 1;
 	let lastRes = result.length - 1;
 	while (
@@ -439,5 +430,4 @@ export function computeChangedLineRange(
 	}
 
 	return { firstChangedLine, lastChangedLine };
-}
-
+}

package/src/hashline/hash.ts

@@ -1,11 +1,8 @@
-
 import xxhash from "xxhash-wasm";
 
 
 export const HASH_LENGTH = 3;
-
 export const HASH_PREFIX = "";
-
 export const ANCHOR_LENGTH = HASH_LENGTH;
 
 const HASH_ALPHABET =
@@ -42,27 +39,20 @@ export const HASHLINE_BARE_PREFIX_RE = new RegExp(`^\\s*(${HASH_CHARS_CLASS})│
 
 
 
-// Lazy-initialized xxhash-wasm hasher. Initialization starts at module load
-// time and completes in ~2ms. By the time any tool calls xxh32(), the hasher
-// is ready.
 type Hasher = { h32(input: string, seed?: number): number };
 let hasherPromise: Promise<Hasher> | null = null;
 let hasherSync: Hasher | null = null;
 
 function getHasher(): Hasher {
 	if (hasherSync) return hasherSync;
-	// Fast path won't hit this in practice — the wasm init completes in ~2ms
-	// and no tool call happens at import time. But if it does, throw clearly.
 	throw new Error("xxhash-wasm not initialized yet. This should not happen.");
 }
 
-// Start initialization immediately at module load time.
 hasherPromise = xxhash().then((h) => {
 	hasherSync = h;
 	return h;
 });
 
-// Export for tests that need to await readiness.
 export function ensureHasherReady(): Promise<Hasher> {
 	return hasherPromise!
 }
@@ -108,4 +98,4 @@ export const HASH_FORMAT = {
 };
 
 
-export { HASH_ALPHABET_RE };
+export { HASH_ALPHABET_RE };

package/src/hashline/resolve.ts

@@ -39,9 +39,7 @@ export interface NoopEdit {
 export type HashlineToolEdit = {
 	old_range?: [string, string];
 	new_lines?: string[];
-	/** @deprecated Legacy field — rejected with [E_LEGACY_SHAPE] at validation time. */
 	oldText?: string;
-	/** @deprecated Legacy field — rejected with [E_LEGACY_SHAPE] at validation time. */
 	newText?: string;
 };
 
@@ -136,7 +134,7 @@ function assertEditItem(edit: Record<string, unknown>, index: number): void {
 	const unknownKeys = Object.keys(edit).filter((key) => !ITEM_KEYS.has(key));
 	if (unknownKeys.length > 0) {
 		throw new Error(
-			`[E_BAD_SHAPE] Edit ${index} contains unknown or unsupported fields: ${unknownKeys.join(", ")}.`,
+			`[E_BAD_SHAPE] Edit ${index} contains unknown or unsupported fields: ${unknownKeys.join(", ")}. Each edit takes only { old_range, new_lines }.`,
 		);
 	}
 
@@ -146,7 +144,7 @@ function assertEditItem(edit: Record<string, unknown>, index: number): void {
 		);
 	}
 	if (!("new_lines" in edit)) {
-		throw new Error(`[E_BAD_SHAPE] Edit ${index} requires a "new_lines" field.`);
+		throw new Error(`[E_BAD_SHAPE] Edit ${index} requires a "new_lines" field. Provide the replacement lines (use [] to delete).`);
 	}
 	if ("new_lines" in edit && !isStringArray(edit.new_lines)) {
 		throw new Error(`[E_BAD_SHAPE] Edit ${index} field "new_lines" must be a string array.`);
@@ -164,7 +162,6 @@ export function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
 	for (const [index, edit] of edits.entries()) {
 		assertEditItem(edit as Record<string, unknown>, index);
 
-		// Normalize new_lines: [""] to new_lines: [] for deletion.
 		const replaceLines = hashlineParseText(edit.new_lines ?? null);
 		const normalizedLines =
 			replaceLines.length === 1 && replaceLines[0] === ""
@@ -229,9 +226,6 @@ export function assertNoBareHashPrefixLines(
 }
 
 
-/**
- * Human-readable label for a resolved edit (used in warnings and conflict errors).
- */
 export function describeEdit(edit: ResolvedHashlineEdit): string {
 	return `replace ${edit.old_range[0].hash}-${edit.old_range[1].hash}`;
 }

package/src/prompts.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "fs";
+
+export function loadPrompt(relativePath: string, replacements?: Record<string, string>): string {
+	let content = readFileSync(new URL(relativePath, import.meta.url), "utf-8").trim();
+	if (replacements) {
+		for (const [key, value] of Object.entries(replacements)) {
+			content = content.replaceAll(`{{${key}}}`, value);
+		}
+	}
+	return content;
+}
+
+export function loadPromptGuidelines(relativePath: string): string[] {
+	return readFileSync(new URL(relativePath, import.meta.url), "utf-8")
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.startsWith("- "))
+		.map((line) => line.slice(2));
+}

package/src/read.ts

@@ -8,9 +8,6 @@ import {
 	type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { readFileSync } from "fs";
-import { access as fsAccess } from "fs/promises";
-import { constants } from "fs";
 import { normalizeToLF, stripBom } from "./replace-diff";
 import { loadFileKindAndText } from "./file-kind";
 import { computeLineHashes, formatHashlineRegion } from "./hashline";
@@ -18,28 +15,16 @@ import { resolveToCwd } from "./path-utils";
 import { throwIfAborted } from "./runtime";
 import { getFileSnapshot } from "./snapshot";
 import { getVisibleLines } from "./utils";
+import { loadPrompt, loadPromptGuidelines } from "./prompts";
+import { validateFileAccess, validateFileKind, isTextFile } from "./validation";
 
-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));
+const READ_DESC = loadPrompt("../prompts/read.md", {
+	DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
+	DEFAULT_MAX_BYTES: formatSize(DEFAULT_MAX_BYTES),
+});
+
+const READ_PROMPT_SNIPPET = loadPrompt("../prompts/read-snippet.md");
+const READ_PROMPT_GUIDELINES = loadPromptGuidelines("../prompts/read-guidelines.md");
 
 function normalizePositiveInteger(
 	value: number | undefined,
@@ -151,35 +136,11 @@ export function registerReadTool(pi: ExtensionAPI): void {
 			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}`);
-			}
+			await validateFileAccess(absolutePath, 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.`,
-				);
-			}
+			validateFileKind(file, rawPath);
 
 			if (file.kind === "image") {
 				const builtinRead = createReadTool(ctx.cwd);
@@ -195,9 +156,6 @@ export function registerReadTool(pi: ExtensionAPI): void {
 
 			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 replace tool will
-			// compute when it later validates against this file.
 			const fileHashes = computeLineHashes(normalized);
 			const preview = formatHashlineReadPreview(
 				normalized,
@@ -209,9 +167,6 @@ export function registerReadTool(pi: ExtensionAPI): void {
 			);
 			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.]`
@@ -221,14 +176,10 @@ export function registerReadTool(pi: ExtensionAPI): void {
 				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
@@ -239,4 +190,4 @@ export function registerReadTool(pi: ExtensionAPI): void {
 			};
 		},
 	});
-}
+}

package/src/replace-diff.ts

@@ -85,19 +85,16 @@ export function generateDiffString(
       let linesToShow = raw;
       let skipStart = 0;
       let skipEnd = 0;
-      let skipMiddle = 0; // lines skipped between head and tail context
+      let skipMiddle = 0;
 
       if (!lastWasChange) {
-        // Before a change: show last contextLines only.
         skipStart = Math.max(0, raw.length - contextLines);
         linesToShow = raw.slice(skipStart);
       } else if (nextPartIsChange && raw.length > contextLines * 2) {
-        // Between two changes: show first contextLines + last contextLines with ellipsis in between.
         const tail = raw.slice(-contextLines);
         linesToShow = [...raw.slice(0, contextLines), "__ELLIPSIS__", ...tail];
         skipMiddle = raw.length - contextLines * 2;
       } else if (linesToShow.length > contextLines) {
-        // After a change with no next change nearby: show first contextLines only.
         skipEnd = linesToShow.length - contextLines;
         linesToShow = linesToShow.slice(0, contextLines);
       }
@@ -234,4 +231,4 @@ export function buildCompactHashlineDiffPreview(
     addedLines,
     removedLines,
   };
-}
+}

package/src/replace-normalize.ts

@@ -1,4 +1,3 @@
-
 import { isRecord, hasOwn } from "./utils";
 
 function coerceEditsArray(edits: unknown): unknown {
@@ -21,7 +20,6 @@ export function normalizeReplaceRequest(input: unknown): unknown {
 
 	const record: Record<string, unknown> = { ...input };
 
-	// file_path → path alias.
 	if (typeof record.path !== "string" && typeof record.file_path === "string") {
 		record.path = record.file_path;
 		delete record.file_path;
@@ -29,11 +27,9 @@ export function normalizeReplaceRequest(input: unknown): unknown {
 
 	const hasEditsField = hasOwn(record, "edits");
 
-	// edits-as-JSON-string → array.
 	if (hasEditsField) {
 		record.edits = coerceEditsArray(record.edits);
 	}
 
 	return record;
-}
-
+}

package/src/replace-render.ts

@@ -1,17 +1,9 @@
-/**
- * TUI rendering helpers for the replace tool.
- *
- * Extracted from `src/replace.ts` to separate presentation (color themes, diff
- * formatting, Markdown rendering) from tool execution logic.
- */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { normalizeReplaceRequest } from "./replace-normalize";
 import type { ReplaceRequestParams, HashlineReplaceToolDetails } from "./replace";
 import { isRecord } from "./utils";
 
-// ─── Theme type aliases ─────────────────────────────────────────────────
-
 export type FgTheme = Pick<Theme, "fg">;
 export type CallTheme = Pick<Theme, "fg" | "bold">;
 export type RenderedMarkdownTheme = Pick<
@@ -19,8 +11,6 @@ export type RenderedMarkdownTheme = Pick<
 	"fg" | "bold" | "italic" | "underline" | "strikethrough"
 >;
 
-// ─── Render state ───────────────────────────────────────────────────────
-
 export type ReplacePreview = { diff: string } | { error: string };
 
 export type ReplaceRenderState = {
@@ -29,8 +19,6 @@ export type ReplaceRenderState = {
 	previewGeneration?: number;
 };
 
-// ─── Preview input extraction ───────────────────────────────────────────
-
 
 export function getRenderablePreviewInput(
 	args: unknown,
@@ -53,8 +41,6 @@ export function getRenderablePreviewInput(
 	return request.edits !== undefined ? request : null;
 }
 
-// ─── Diff formatting ────────────────────────────────────────────────────
-
 export function colorDiffLines(lines: string[], theme: FgTheme): string[] {
 	return lines.map((line) => {
 		if (line.startsWith("+") && !line.startsWith("+++")) {
@@ -88,8 +74,6 @@ export function formatResultDiff(diff: string, theme: FgTheme): string {
 	return colorDiffLines(diff.split("\n"), theme).join("\n");
 }
 
-// ─── Edit call formatting ───────────────────────────────────────────────
-
 export function formatEditCall(
 	args: ReplaceRequestParams | undefined,
 	state: ReplaceRenderState,
@@ -118,8 +102,6 @@ export function formatEditCall(
 	return text;
 }
 
-// ─── Result text extraction ─────────────────────────────────────────────
-
 export function getRenderedEditTextContent(result: {
 	content?: Array<{ type: string; text?: string }>;
 }): string | undefined {
@@ -136,8 +118,6 @@ export function extractRenderedWarnings(
 	return text?.match(/(?:^|\n)Warnings:\n[\s\S]*$/)?.[0]?.trimStart();
 }
 
-// ─── Result classification ──────────────────────────────────────────────
-
 export function isAppliedChangedResult(
 	details: HashlineReplaceToolDetails | undefined,
 ): boolean {
@@ -165,7 +145,6 @@ export function buildAppliedChangedResultText(
 
 	return sections.length > 0 ? sections.join("\n\n") : undefined;
 }
-// ─── Markdown rendering ─────────────────────────────────────────────────
 
 function trimEdgeEmptyLines(lines: string[]): string[] {
 	let start = 0;
@@ -272,4 +251,4 @@ export function createRenderedEditMarkdownTheme(theme: RenderedMarkdownTheme) {
 				return theme.fg("mdCodeBlock", line);
 			}),
 	};
-}
+}

package/src/replace-response.ts

@@ -1,4 +1,3 @@
-
 import { generateDiffString } from "./replace-diff";
 import {
 	computeAffectedLineRange,
@@ -6,6 +5,7 @@ import {
 	formatHashlineRegion,
 } from "./hashline";
 import { getVisibleLines } from "./utils";
+import { CHANGED_ANCHOR_TEXT_BUDGET_BYTES } from "./constants";
 
 type ToolResult = {
 	content: Array<{ type: "text"; text: string }>;
@@ -13,9 +13,6 @@ type ToolResult = {
 	details: any;
 };
 
-const CHANGED_ANCHOR_TEXT_BUDGET_BYTES = 50 * 1024;
-
-
 export type ReplaceMetrics = {
 	edits_attempted: number;
 	edits_noop: number;
@@ -45,7 +42,6 @@ type NoopEditEntry = {
 };
 
 
-// ─── Builder inputs ─────────────────────────────────────────────────────
 
 export interface NoopResponseInput {
 	path: string;
@@ -65,7 +61,6 @@ export interface SuccessResponseInput {
 	editMeta: ReplaceMeta;
 }
 
-// ─── Helpers ────────────────────────────────────────────────────────────
 
 
 function countDiffLines(diff: string, marker: "+" | "-"): number {
@@ -118,7 +113,6 @@ function warningsBlockOf(warnings: string[] | undefined): string {
 	return warnings?.length ? `\n\nWarnings:\n${warnings.join("\n")}` : "";
 }
 
-// ─── Builders ───────────────────────────────────────────────────────────
 
 export function buildNoopResponse(input: NoopResponseInput): ToolResult {
 	const {
@@ -190,10 +184,10 @@ export function buildChangedResponse(input: SuccessResponseInput): ToolResult {
 					CHANGED_ANCHOR_TEXT_BUDGET_BYTES
 					? block
 					: "Anchors omitted; use read for subsequent edits.";
-		})()
+			})()
 		: resultLines.length === 0
 			? "File is empty. Use edit to insert content."
-			: ""; // No anchor context → show nothing; LLM can call read for fresh anchors
+			: "";
 	const text = [anchorsBlock, warningsBlock.trimStart()]
 		.filter((section) => section.length > 0)
 		.join("\n\n");
@@ -219,4 +213,4 @@ export function buildChangedResponse(input: SuccessResponseInput): ToolResult {
 			metrics,
 		},
 	};
-}
+}

package/src/replace.ts

@@ -6,8 +6,6 @@ import type {
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { constants } from "fs";
-import { readFileSync } from "fs";
-import { access as fsAccess } from "fs/promises";
 import {
 	detectLineEnding,
 	generateDiffString,
@@ -45,6 +43,8 @@ import {
 	type ReplacePreview,
 	type ReplaceRenderState,
 } from "./replace-render";
+import { loadPrompt, loadPromptGuidelines } from "./prompts";
+import { validateFileAccess, validateFileKind, isTextFile } from "./validation";
 
 
 const hashlineEditNewLinesSchema = Type.Array(Type.String(), {
@@ -87,40 +87,15 @@ export type ReplaceRequestParams = {
 export type HashlineReplaceToolDetails = {
 	diff: string;
 	firstChangedLine?: number;
-	/**
-	 * Post-edit snapshot fingerprint. Surfaced in details only — the LLM no
-	 * longer receives or echoes it. Hosts may use this for UI hints (e.g.
-	 * "file changed since last view"). See plan W2.
-	 */
 	snapshotId?: string;
 	classification?: "noop";
 	structureOutline?: string[];
-	/**
-	 * Phase 2 C — opt-in observability surface for hosts. Never echoed in text.
-	 * Hosts can use it for adoption/regression dashboards.
-	 */
 	metrics?: ReplaceMetrics;
 };
 
-const EDIT_DESC = readFileSync(
-	new URL("../prompts/replace.md", import.meta.url),
-	"utf-8",
-).trim();
-
-const EDIT_PROMPT_SNIPPET = readFileSync(
-	new URL("../prompts/replace-snippet.md", import.meta.url),
-	"utf-8",
-).trim();
-
-
-const EDIT_PROMPT_GUIDELINES = readFileSync(
-	new URL("../prompts/replace-guidelines.md", import.meta.url),
-	"utf-8",
-)
-	.split("\n")
-	.map((line) => line.trim())
-	.filter((line) => line.startsWith("- "))
-	.map((line) => line.slice(2));
+const EDIT_DESC = loadPrompt("../prompts/replace.md");
+const EDIT_PROMPT_SNIPPET = loadPrompt("../prompts/replace-snippet.md");
+const EDIT_PROMPT_GUIDELINES = loadPromptGuidelines("../prompts/replace-guidelines.md");
 const ROOT_KEYS = new Set(["path", "edits"]);
 
 export function assertReplaceRequest(
@@ -143,7 +118,7 @@ export function assertReplaceRequest(
 	);
 	if (unknownRootKeys.length > 0) {
 		throw new Error(
-			`[E_BAD_SHAPE] Edit request contains unknown or unsupported fields: ${unknownRootKeys.join(", ")}.`,
+			`[E_BAD_SHAPE] Edit request contains unknown or unsupported fields: ${unknownRootKeys.join(", ")}. Use only { path, edits }; each edit is { old_range: ["<START>", "<END>"], new_lines: [...] }.`,
 		);
 	}
 
@@ -152,7 +127,7 @@ export function assertReplaceRequest(
 	}
 
 	if (hasOwn(request, "edits") && !Array.isArray(request.edits)) {
-		throw new Error('[E_BAD_SHAPE] Edit request requires an "edits" array when provided.');
+		throw new Error('[E_BAD_SHAPE] Edit request requires an "edits" array when provided. Each edit is { old_range: ["<START>", "<END>"], new_lines: [...] }.');
 	}
 
 }
@@ -190,38 +165,11 @@ async function executeEditPipeline(
 	}
 
 	throwIfAborted(signal);
-	try {
-		await fsAccess(absolutePath, accessMode);
-	} catch (error: unknown) {
-		const code = (error as NodeJS.ErrnoException).code;
-		if (code === "ENOENT") {
-			throw new Error(`File not found: ${path}`);
-		}
-		if (code === "EACCES" || code === "EPERM") {
-			const accessLabel =
-				accessMode & constants.W_OK ? "not writable" : "not readable";
-			throw new Error(`File is ${accessLabel}: ${path}`);
-		}
-		throw new Error(`Cannot access file: ${path}`);
-	}
+	await validateFileAccess(absolutePath, path, accessMode);
 
 	throwIfAborted(signal);
 	const file = await loadFileKindAndText(absolutePath);
-	if (file.kind === "directory") {
-		throw new Error(
-			`Path is a directory: ${path}. Use ls to inspect directories.`,
-		);
-	}
-	if (file.kind === "image") {
-		throw new Error(
-			`Path is an image file: ${path}. Hashline edit only supports text files.`,
-		);
-	}
-	if (file.kind === "binary") {
-		throw new Error(
-			`Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`,
-		);
-	}
+	validateFileKind(file, path);
 
 	throwIfAborted(signal);
 	const { bom, text: rawContent } = stripBom(file.text);
@@ -493,4 +441,4 @@ const editToolDefinition: EditToolDefinition = {
 
 export function registerReplaceTool(pi: ExtensionAPI): void {
 	pi.registerTool(editToolDefinition);
-}
+}

package/src/snapshot.ts

@@ -11,13 +11,6 @@ function formatSnapshotId(canonicalPath: string, info: { mtimeMs: number; size:
   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);

package/src/utils.ts

@@ -1,6 +1,3 @@
-/**
- * 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);
@@ -10,18 +7,12 @@ export function hasOwn(record: Record<string, unknown>, key: string): boolean {
 	return Object.hasOwn(record, key);
 }
 
-/**
- * Return the visible lines of a text (excluding the terminal-newline sentinel).
- */
 export function getVisibleLines(text: string): string[] {
 	if (text.length === 0) return [];
 	const lines = text.split("\n");
 	return text.endsWith("\n") ? lines.slice(0, -1) : lines;
 }
 
-/**
- * Count the visible lines of a text (excluding the terminal-newline sentinel).
- */
 export function countVisibleLines(text: string): number {
 	return getVisibleLines(text).length;
 }

package/src/validation.ts

@@ -0,0 +1,46 @@
+import { constants } from "fs";
+import { access as fsAccess } from "fs/promises";
+import type { LoadedFile } from "./file-kind";
+
+export async function validateFileAccess(
+	absolutePath: string,
+	path: string,
+	accessMode: number = constants.R_OK,
+): Promise<void> {
+	try {
+		await fsAccess(absolutePath, accessMode);
+	} catch (error: unknown) {
+		const code = getErrorCode(error);
+		if (code === "ENOENT") {
+			throw new Error(`File not found: ${path}`);
+		}
+		if (code === "EACCES" || code === "EPERM") {
+			const accessLabel = accessMode & constants.W_OK ? "not writable" : "not readable";
+			throw new Error(`File is ${accessLabel}: ${path}`);
+		}
+		throw new Error(`Cannot access file: ${path}`);
+	}
+}
+
+export function validateFileKind(file: LoadedFile, path: string): void {
+	if (file.kind === "directory") {
+		throw new Error(`Path is a directory: ${path}. Use ls to inspect directories.`);
+	}
+	if (file.kind === "binary") {
+		throw new Error(`Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`);
+	}
+	if (file.kind === "image") {
+		throw new Error(`Path is an image file: ${path}. Hashline edit only supports text files.`);
+	}
+}
+
+export function isTextFile(file: LoadedFile): file is { kind: "text"; text: string; hadUtf8DecodeErrors?: true } {
+	return file.kind === "text";
+}
+
+export function getErrorCode(error: unknown): string | undefined {
+	if (error instanceof Error) {
+		return (error as NodeJS.ErrnoException).code;
+	}
+	return undefined;
+}