pi-hashline-edit-pro 0.15.5 → 0.16.0

package/index.ts

@@ -4,6 +4,7 @@ import { join, isAbsolute } from "path";
 import { initHasher } from "./src/hashline";
 import { regReplace } from "./src/replace";
 import { regReplaceFlat } from "./src/replace-flat";
+import { regReplaceUndo } from "./src/replace-undo";
 import { regRead, fmtReadPreview } from "./src/read";
 import { toLF, stripBOM } from "./src/replace-diff";
 import { visLines } from "./src/utils";
@@ -22,7 +23,7 @@ export default function (pi: ExtensionAPI): void {
   // Register the bulk-mode replace tool by default. The session_start handler
   // will re-register with the correct mode from the persisted config.
   regReplace(pi);
-
+  regReplaceUndo(pi);
   const debugValue = process.env.PI_HASHLINE_DEBUG;
   // Initial auto-read from env var; session_start overrides with persisted value
   const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "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-bulk.md

@@ -94,9 +94,7 @@ Rules:
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - All changes in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
 - If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
-- The `hash_range_inclusive` is inclusive — the entire span from the first anchor through the second anchor is deleted and replaced with `content_lines`. The old lines in that span are gone. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
-On success, the response text is empty (or contains only warnings if present). {{AUTO_READ_GUIDANCE}}
-
+On success, the response text shows the line change summary (e.g. "Added 3 line(s), removed 1 line(s).") plus any warnings if present. {{AUTO_READ_GUIDANCE}}
 ⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
 
 Wrong: To replace lines 2-3 in this function:
@@ -129,3 +127,5 @@ Error recovery:
 - `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
+
+**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/prompts/replace-flat.md

@@ -79,7 +79,8 @@ Rules:
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
 - The `hash_range_inclusive` is inclusive — the entire span from the first anchor through the second anchor is deleted and replaced with `content_lines`. The old lines in that span are gone. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
-On success, the response text is empty (or contains only warnings if present). {{AUTO_READ_GUIDANCE}}
+- `hash_range_inclusive` and `content_lines` must be native JSON values, not JSON strings. Do not serialize them — pass them as a proper array and array of strings respectively.
+On success, the response text shows the line change summary (e.g. "Added 3 line(s), removed 1 line(s).") plus any warnings if present. {{AUTO_READ_GUIDANCE}}
 
 ⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
 
@@ -112,3 +113,5 @@ Error recovery:
 - `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
+
+**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/prompts/replace.md

@@ -142,7 +142,8 @@ Rules:
 - All changes in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
 - If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
 - The `hash_range_inclusive` is inclusive — the entire span from the first anchor through the second anchor is deleted and replaced with `content_lines`. The old lines in that span are gone. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
-On success, the response text is empty (or contains only warnings if present). {{AUTO_READ_GUIDANCE}}
+- `changes` (in bulk mode), `hash_range_inclusive`, and `content_lines` must be native JSON values, not JSON strings. Do not serialize them — pass them as proper arrays and strings.
+On success, the response text shows the line change summary (e.g. "Added 3 line(s), removed 1 line(s).") plus any warnings if present. {{AUTO_READ_GUIDANCE}}
 
 ⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
 
@@ -176,3 +177,5 @@ Error recovery:
 - `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
+
+**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/src/file-reader.ts

@@ -1,58 +1,60 @@
 import { constants } from "fs";
 import { lineHashes } from "./hashline";
 import { loadFileKindAndText, type LFile } from "./file-kind";
+import { resolveTarget } from "./fs-write";
 import { toCwd } from "./path-utils";
 import { detectEnding, toLF, stripBOM } from "./replace-diff";
 import { abortIf } from "./runtime";
 import { assertText, valAccess } from "./validation";
 
 export interface NormFile {
-	absolutePath: string;
-	normalized: string;
-	bom: string;
-	originalEnding: "\r\n" | "\n";
-	fileHashes: string[];
-	hadUtf8DecodeErrors: boolean;
+  absolutePath: string;
+  normalized: string;
+  bom: string;
+  originalEnding: "\r\n" | "\n";
+  fileHashes: string[];
+  hadUtf8DecodeErrors: boolean;
 }
 
 export async function readNormFile(
-	path: string,
-	cwd: string,
-	signal: AbortSignal | undefined,
-	accessMode: number = constants.R_OK,
-	preloadedFile?: LFile,
-	maxLines?: number,
+  path: string,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  accessMode: number = constants.R_OK,
+  preloadedFile?: LFile,
+  maxLines?: number,
 ): Promise<NormFile> {
-	const absolutePath = toCwd(path, cwd);
+  const absolutePath = toCwd(path, cwd);
+  const resolvedPath = await resolveTarget(absolutePath);
 
-	abortIf(signal);
-	await valAccess(absolutePath, path, accessMode);
+  abortIf(signal);
+  await valAccess(resolvedPath, path, accessMode);
 
-	abortIf(signal);
-	const file = preloadedFile ?? (await loadFileKindAndText(absolutePath));
-	assertText(file, path);
+  abortIf(signal);
+  const file = preloadedFile ?? (await loadFileKindAndText(resolvedPath));
+  assertText(file, path);
 
-	abortIf(signal);
-	const { bom, text: rawContent } = stripBOM(file.text);
-	const originalEnding = detectEnding(rawContent);
-	const normalized = toLF(rawContent);
+  abortIf(signal);
+  const { bom, text: rawContent } = stripBOM(file.text);
+  const originalEnding = detectEnding(rawContent);
+  const normalized = toLF(rawContent);
 
-	if (maxLines !== undefined) {
-		const lineCount = normalized.split("\n").length;
-		if (lineCount > maxLines) {
-			throw new Error(
-				`[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
-			);
-		}
-	}
+  if (maxLines !== undefined) {
+    const lineCount = normalized.split("\n").length;
+    if (lineCount > maxLines) {
+      throw new Error(
+        `[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
+      );
+    }
+  }
 
-	const fileHashes = await lineHashes(normalized, absolutePath);
-	return {
-		absolutePath,
-		normalized,
-		bom,
-		originalEnding,
-		fileHashes,
-		hadUtf8DecodeErrors: file.hadUtf8DecodeErrors === true,
-	};
+  const fileHashes = await lineHashes(normalized, resolvedPath);
+  return {
+    absolutePath: resolvedPath,
+    normalized,
+    bom,
+    originalEnding,
+    fileHashes,
+    hadUtf8DecodeErrors: file.hadUtf8DecodeErrors === true,
+  };
 }

package/src/replace-normalize.ts

@@ -13,34 +13,56 @@ function tryParseJSON<T>(value: unknown, guard: (v: unknown) => v is T): T | und
  * Coerces an array of edit items: JSON-string items → objects,
  * JSON-string content_lines → string arrays. Shared by the `changes`
  * and `edits` normalization branches.
+ * Returns a warning if any item was a JSON string.
  */
-function coerceEditArray(items: unknown[]): unknown[] {
-  return items
-    .map((item: unknown) => tryParseJSON(item, isRec) ?? item)
+function coerceEditArray(items: unknown[]): { result: unknown[]; warnings: string[] } {
+  const warnings: string[] = [];
+  const result = items
+    .map((item: unknown) => {
+      if (typeof item === "string") {
+        const parsed = tryParseJSON(item, isRec);
+        if (parsed) {
+          warnings.push("Edit item was passed as a JSON string instead of a native object. Use native JSON values, not serialized strings.");
+          return parsed;
+        }
+      }
+      return item;
+    })
     .map((change: unknown) => {
       if (!isRec(change)) return change;
       if (typeof change.content_lines !== "string") return change;
       const parsed = tryParseJSON(change.content_lines, (v): v is string[] =>
         Array.isArray(v) && v.every((i) => typeof i === "string"),
       );
-      return parsed ? { ...change, content_lines: parsed } : change;
+      if (parsed) {
+        warnings.push("content_lines was passed as a JSON string inside an edit item. Use a native array of strings.");
+        return { ...change, content_lines: parsed };
+      }
+      return change;
     });
+  return { result, warnings };
 }
 
 /**
  * Normalizes a field from `from` to `to`: JSON-string arrays → real arrays,
  * single objects → wrapped in array. Shared by the `changes` and `edits`
  * normalization branches.
+ * Returns a warning if the field was a JSON string.
  */
 function normalizeField(
   record: Record<string, unknown>,
   from: string,
   to: string,
-): void {
-  if (!has(record, from)) return;
+): string | undefined {
+  if (!has(record, from)) return undefined;
   const raw = tryParseJSON(record[from], Array.isArray) ?? record[from];
+  const wasString = typeof record[from] === "string" && raw !== record[from];
   if (Array.isArray(raw)) {
-    record[to] = coerceEditArray(raw);
+    const { result, warnings } = coerceEditArray(raw);
+    record[to] = result;
+    if (warnings.length > 0) {
+      return warnings.join(" ");
+    }
   } else {
     const single =
       typeof raw === "string"
@@ -48,9 +70,19 @@ function normalizeField(
         : isRec(raw)
           ? raw
           : undefined;
-    if (single) record[to] = coerceEditArray([single]);
+    if (single) {
+      const { result, warnings } = coerceEditArray([single]);
+      record[to] = result;
+      if (warnings.length > 0) {
+        return warnings.join(" ");
+      }
+    }
   }
   if (from !== to) delete record[from];
+  if (wasString) {
+    return `Field "${from}" was passed as a JSON string instead of a native array. Use native JSON values, not serialized strings.`;
+  }
+  return undefined;
 }
 
 export function normReq(input: unknown): unknown {
@@ -59,25 +91,36 @@ export function normReq(input: unknown): unknown {
   }
 
   const record: Record<string, unknown> = { ...input };
+  const warnings: string[] = [];
 
   if (typeof record.path !== "string" && typeof record.file_path === "string") {
     record.path = record.file_path;
     delete record.file_path;
   }
 
-  normalizeField(record, "changes", "changes");
-  normalizeField(record, "edits", "changes");
+  const w1 = normalizeField(record, "changes", "changes");
+  if (w1) warnings.push(w1);
+  const w2 = normalizeField(record, "edits", "changes");
+  if (w2) warnings.push(w2);
 
   // Handle flat format: hash_range_inclusive and content_lines at top level
   // (no changes array). Wrap them into a single-element changes array.
   if (!Array.isArray(record.changes) && has(record, "hash_range_inclusive") && has(record, "content_lines")) {
-    const hri = tryParseJSON(record.hash_range_inclusive, (v): v is string[] =>
+    const hriRaw = record.hash_range_inclusive;
+    const hri = tryParseJSON(hriRaw, (v): v is string[] =>
       Array.isArray(v) && v.length === 2 && v.every((i) => typeof i === "string")
-    ) ?? record.hash_range_inclusive;
+    ) ?? hriRaw;
+    if (typeof hriRaw === "string" && hri !== hriRaw) {
+      warnings.push("hash_range_inclusive was passed as a JSON string instead of a native array. Use native JSON values.");
+    }
 
-    const cl = tryParseJSON(record.content_lines, (v): v is string[] =>
+    const clRaw = record.content_lines;
+    const cl = tryParseJSON(clRaw, (v): v is string[] =>
       Array.isArray(v) && v.every((i) => typeof i === "string")
-    ) ?? record.content_lines;
+    ) ?? clRaw;
+    if (typeof clRaw === "string" && cl !== clRaw) {
+      warnings.push("content_lines was passed as a JSON string instead of a native array. Use native JSON values.");
+    }
 
     if (Array.isArray(hri) && Array.isArray(cl)) {
       record.changes = [{ hash_range_inclusive: hri, content_lines: cl }];
@@ -86,6 +129,9 @@ export function normReq(input: unknown): unknown {
     }
   }
 
+  if (warnings.length > 0) {
+    (record as Record<string, unknown>)._normWarnings = warnings;
+  }
+
   return record;
 }
-

package/src/replace-response.ts

@@ -148,11 +148,14 @@ export function buildChanged(input: SuccessInput): TResult {
   const removedLines = cntDiff(diffResult.diff, "-");
   const warningsBlock = warnBlock(warnings);
   const successPrefix = `Successfully replaced in ${path}.`;
+  const lineSummary = addedLines > 0 || removedLines > 0
+    ? ` Added ${addedLines} line(s), removed ${removedLines} line(s).`
+    : "";
   const text = resultLines.length === 0
     ? "File is empty. Use replace to insert content."
     : warningsBlock
-      ? `${successPrefix}${warningsBlock}`
-      : successPrefix;
+      ? `${successPrefix}${lineSummary}${warningsBlock}`
+      : `${successPrefix}${lineSummary}`;
 
   const metrics = buildM({
     classification: "applied",

package/src/replace-undo.ts

@@ -0,0 +1,122 @@
+import { readFile } from "fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { getUndo, clearUndo } from "./undo-store";
+import { loadHashStore, saveHashStore } from "./hash-store";
+import { resolveTarget, writeAtomic } from "./fs-write";
+import { toCwd } from "./path-utils";
+import { toLF, stripBOM, genDiff, restoreEndings } from "./replace-diff";
+
+function cntDiff(diff: string, marker: "+" | "-"): number {
+  if (!diff) return 0;
+  let count = 0;
+  for (const line of diff.split("\n")) {
+    if (
+      line.startsWith(marker) &&
+      !line.startsWith(`${marker}${marker}${marker}`)
+    ) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+export function regReplaceUndo(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "last_replace_undo",
+    label: "Undo Last Replace",
+    description:
+      "Undo the last replace operation on a file, reverting it to its previous state. " +
+      "Use this when a replace produced incorrect results (e.g., wrong content, duplicated lines, broken syntax). " +
+      "After undoing, call `read` to get fresh anchors for a corrected replace.",
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Path to the file to undo the last replace on",
+      }),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const path = params.path;
+      const absolutePath = toCwd(path, ctx.cwd);
+      const mutationTargetPath = await resolveTarget(absolutePath);
+
+      const undo = getUndo(mutationTargetPath);
+      if (!undo) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No undo history for ${path}. There is no previous replace to revert.`,
+            },
+          ],
+          isError: true,
+          details: {},
+        };
+      }
+
+      return withFileMutationQueue(mutationTargetPath, async () => {
+        // Read current file content to compute diff against the pre-replace state
+        let currentNormalized = "";
+        try {
+          const currentRaw = await readFile(mutationTargetPath, "utf-8");
+          const { text: currentStripped } = stripBOM(currentRaw);
+          currentNormalized = toLF(currentStripped);
+        } catch {
+          // File may have been deleted; treat as empty
+          currentNormalized = "";
+        }
+
+        // Compute diff: old = pre-replace (undo.content), new = current
+        const diffResult = genDiff(undo.content, currentNormalized, 0);
+        const linesAddedByReplace = cntDiff(diffResult.diff, "+");
+        const linesRemovedByReplace = cntDiff(diffResult.diff, "-");
+
+        // Write the pre-edit content back to the file
+        await writeAtomic(
+          mutationTargetPath,
+          undo.bom + restoreEndings(undo.content, undo.originalEnding),
+        );
+
+        // Restore the hash store snapshot so the next read returns the same hashes
+        const store = await loadHashStore();
+        store.snapshots[mutationTargetPath] = {
+          content: undo.content,
+          hashes: undo.hashes,
+        };
+        await saveHashStore(store);
+
+        // Clear undo so a second call without an intervening replace is a no-op
+        clearUndo(mutationTargetPath);
+
+        const parts: string[] = [
+          `Undone last replace on ${path}.`,
+        ];
+        if (linesAddedByReplace > 0 || linesRemovedByReplace > 0) {
+          parts.push(
+            `Removed ${linesAddedByReplace} line(s) that were added and restored ${linesRemovedByReplace} line(s) that were removed.`,
+          );
+        }
+        parts.push(
+          "File reverted to previous state. Call `read` to get fresh anchors for follow-up edits.",
+        );
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: parts.join("\n"),
+            },
+          ],
+          details: {
+            metrics: {
+              added_lines: linesRemovedByReplace,
+              removed_lines: linesAddedByReplace,
+              classification: "applied" as const,
+            },
+          },
+        };
+      });
+    },
+  });
+}

package/src/replace.ts

@@ -44,6 +44,7 @@ import {
 } from "./replace-render";
 import { loadP, loadGuide } from "./prompts";
 import { readAutoReadSync } from "./config";
+import { saveUndo } from "./undo-store";
 
 const contentLinesSchema = Type.Array(Type.String(), {
   description:
@@ -168,6 +169,7 @@ export async function execPipeline(
   );
 
   const absolutePath = toCwd(path, cwd);
+  const resolvedPath = await resolveTarget(absolutePath);
   const resolved = resEdits(toolEdits);
   const anchorResult = applyEdits(
     originalNormalized,
@@ -199,7 +201,7 @@ export async function execPipeline(
   }
 
   // Compute stable result hashes using hash-aware preservation
-  const resultHashes = await lineHashes(result, absolutePath, {
+  const resultHashes = await lineHashes(result, resolvedPath, {
     content: originalNormalized,
     hashes: originalHashes,
     removedHashes,
@@ -437,6 +439,7 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
             }],
           })
         : normReq(params);
+      const normWarnings = (canonical as Record<string, unknown>)._normWarnings as string[] | undefined;
       const normalizedParams = canonical as { path: string; changes: HTEdit[] };
       const path = normalizedParams.path;
       const absolutePath = toCwd(path, ctx.cwd);
@@ -469,6 +472,10 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
             ? normalizedParams.changes.length
             : 0;
 
+        if (normWarnings) {
+          warnings.push(...normWarnings);
+        }
+
         if (originalNormalized === result) {
           const noopSnapshotId = (await fileSnap(absolutePath)).snapshotId;
           return buildNoop({
@@ -494,6 +501,12 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
           absolutePath,
           bom + restoreEndings(result, originalEnding),
         );
+        saveUndo(mutationTargetPath, {
+          content: originalNormalized,
+          bom,
+          originalEnding,
+          hashes: originalHashes,
+        });
         const updatedSnapshotId = (await fileSnap(absolutePath))
           .snapshotId;
 

package/src/undo-store.ts

@@ -0,0 +1,35 @@
+/**
+ * In-memory undo store for the last_replace_undo tool.
+ *
+ * Before each successful replace, the pre-edit file state (normalized content,
+ * BOM, original line ending, and hashes) is saved keyed by absolute path.
+ * The undo tool reads this entry, restores the file, and clears the entry.
+ *
+ * Only the most recent replace per file is tracked — calling undo twice
+ * without an intervening replace will produce "no undo history".
+ */
+
+export interface UndoEntry {
+  /** Normalized (LF) content before the edit */
+  content: string;
+  /** BOM prefix that was stripped from the original file */
+  bom: string;
+  /** Original line ending detected before the edit */
+  originalEnding: "\r\n" | "\n";
+  /** Hash array for the pre-edit content */
+  hashes: string[];
+}
+
+const undoMap = new Map<string, UndoEntry>();
+
+export function saveUndo(path: string, entry: UndoEntry): void {
+  undoMap.set(path, entry);
+}
+
+export function getUndo(path: string): UndoEntry | undefined {
+  return undoMap.get(path);
+}
+
+export function clearUndo(path: string): void {
+  undoMap.delete(path);
+}