pi-hashline-edit-pro 0.4.2 → 0.5.1

package/README.md

@@ -13,8 +13,7 @@ The original uses 2-character hashes of a 16-character alphabet, with the hash b
 This fork makes two changes that compound:
 
 1. **Bump hash length to 4 characters** of the 64-char URL-safe base64 alphabet. That gives 24 bits / 16 777 216 buckets. Birthday-paradox collisions are effectively nullified for any realistic file.
-2. **Make the hash occurrence-aware.** The hash for line N is `xxHash32("C{occurrence}:{content}")` where `occurrence` is the running count of that content string earlier in the file. Symbol-only lines use `"S{lineNumber}"` as the discriminator. Two `import {...}` statements at different positions now hash to different values, so the model can target a specific occurrence without resorting to `offset` + a small `limit` window.
-
+2. **Make the hash occurrence-aware.** The hash for line N is `xxHash32("C{occurrence}:{content}")` where `occurrence` is the running count of that content string earlier in the file. Two `import {...}` statements at different positions now hash to different values, so the model can target a specific occurrence without resorting to `offset` + a small `limit` window. All lines — including symbol-only lines like `}` — use the same occurrence-based discrimination.
 ## Installation
 
 From npm:
@@ -33,7 +32,7 @@ pi install /path/to/pi-hashline-edit-pro
 
 ### `read` -- tagged line output
 
-Text files are returned with a `HASH|content` prefix on every line. The line number is not part of the wire format, only the 4-character hash followed by the `|` separator and the line content. Example output for the source below:
+Text files are returned with a `HASH│content` prefix on every line. The line number is not part of the wire format, only the 4-character hash followed by the `│` separator and the line content. Example output for the source below:
 
 ```js
 function hello() {
@@ -44,9 +43,9 @@ function hello() {
 would be returned as:
 
 ```text
-0qH3|function hello() {
-szJr|  console.log("world");
-_zlP|}
+0qH3│function hello() {
+szJr│  console.log("world");
+_zlP│}
 ```
 
 - `HASH` is a 4-character content hash from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `aB3x`).
@@ -60,7 +59,7 @@ Images (JPEG, PNG, GIF, WebP) are passed through as attachments and do not parti
 
 ### `edit` -- hash-anchored modifications
 
-Edits use the `HASH|content` anchors from `read` output to target lines precisely:
+Edits use the `HASH│content` anchors from `read` output to target lines precisely:
 
 ```json
 {
@@ -84,11 +83,11 @@ All edits in a single call validate against the same pre-edit snapshot and apply
 
 ### Chained edits
 
-After a successful edit, the result text contains an `--- Anchors ---` block with fresh `HASH|content` references for the changed region. These can be used directly in the next `edit` call on the same file without a full re-read, provided the next edit targets the same or nearby lines. For distant changes, use `read` first.
+After a successful edit, the result text contains an `--- Anchors ---` block with fresh `HASH│content` references for the changed region. These can be used directly in the next `edit` call on the same file without a full re-read, provided the next edit targets the same or nearby lines. For distant changes, use `read` first.
 
 ### Auto-read after write
 
-After a successful `write`, the extension automatically reads the file and appends a `--- Auto-read (hashline anchors) ---` block to the result. This gives the model immediate `HASH|content` anchors for the newly written file without requiring a separate `read` call. The workflow becomes:
+After a successful `write`, the extension automatically reads the file and appends a `--- Auto-read (hashline anchors) ---` block to the result. This gives the model immediate `HASH│content` anchors for the newly written file without requiring a separate `read` call. The workflow becomes:
 
 1. `write` a file, result includes hashline anchors
 2. `edit` using those anchors directly
@@ -97,27 +96,27 @@ For large files (>2000 lines), the auto-read output is truncated with a paginati
 
 ### Diff for the host
 
-The post-edit diff (with `+`/`-` markers and new `HASH|content` anchors) is exposed to the host UI via `details.diff`. It is intentionally not in the LLM-visible text. The model only needs the fresh anchors in `text` to chain follow-up edits, and re-emitting the diff would cost extra tokens.
+The post-edit diff (with `+`/`-` markers and new `HASH│content` anchors) is exposed to the host UI via `details.diff`. It is intentionally not in the LLM-visible text. The model only needs the fresh anchors in `text` to chain follow-up edits, and re-emitting the diff would cost extra tokens.
 
 ## Design Decisions
 
-- **Stale anchors fail.** A hash mismatch means the file has changed since the last `read`. The error includes fresh `>>> HASH|content` lines for the affected region. The model copies the HASH portion and retries.
+- **Stale anchors fail.** A hash mismatch means the file has changed since the last `read`. The error includes fresh `>>> HASH│content` lines for the affected region. The model copies the HASH portion and retries.
 - **No fallback relocation.** Mismatched anchors are never silently relocated to a "close enough" line. This trades convenience for correctness.
-- **Strict patch content.** If `lines` contains `+HASH|` display prefixes (or `-N   ` diff rows), the edit is rejected with `[E_INVALID_PATCH]`. Bare `HASH|` content (the first 5 chars of a `lines` entry looking like 4 base64 chars + `|`) is also rejected with `[E_BARE_HASH_PREFIX]`. When the suspect's prefix happens to match a real file-line anchor, the error message flags that as strong evidence the model copied an anchor from the read output.
+- **Strict patch content.** If `lines` contains `+HASH│` display prefixes (or `-N   ` diff rows), the edit is rejected with `[E_INVALID_PATCH]`. Bare `HASH│` content (the first 5 chars of a `lines` entry looking like 4 base64 chars + `│`) is also rejected with `[E_BARE_HASH_PREFIX]`. When the suspect's prefix happens to match a real file-line anchor, the error message flags that as strong evidence the model copied an anchor from the read output.
 - **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect and `op: "replace_text"` are rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{op:"replace", start:"<HASH>", end:"<HASH>", lines:[...]}` (or `append`/`prepend` with `pos`).
 - **Atomic writes.** Files are written via temp-file-then-rename to avoid corruption from interrupted writes. Symlink chains are resolved so the target file is updated without replacing the symlink. Hard-linked files are updated in place to preserve the shared inode. File permissions are preserved across atomic renames.
 - **Per-file mutation queue.** Edits queue by the canonical write target, so concurrent edits through different symlink paths still serialize onto the same underlying file.
 
 ## Hashing
 
-Hashes are computed with [xxhashjs](https://github.com/pierrec/js-xxhash) (xxHash32), then mapped to a 4-character string from the URL-safe base64 alphabet `A-Za-z0-9-_`. That's 64 distinct characters, 6 bits per position, 24 bits of entropy per anchor.
+Hashes are computed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32 via WebAssembly), then mapped to a 4-character string from the URL-safe base64 alphabet `A-Za-z0-9-_`. That's 64 distinct characters, 6 bits per position, 24 bits of entropy per anchor.
 
 The alphabet is sized for an LLM consumer. The model tokenizes, it doesn't squint at pixel glyphs, so the human-readability heuristics used by smaller hand-curated alphabets (no G/L/I/O because they look like digits, no vowels so the hash doesn't accidentally spell a word, no hex digits so it can't be confused with `0xFF`) don't apply. The full 64 chars give maximum entropy per character, with case and digits included.
 
-Hashes are occurrence-aware: a discriminator prefix is mixed into the xxHash input before the line content. Symbol-only lines (lone `}`, etc.) use `S{lineNumber}` as the discriminator; content lines use `C{occurrence}` where `occurrence` is the running count of that canonical content earlier in the file. This way:
+Hashes are occurrence-aware: a discriminator prefix is mixed into the xxHash input before the line content. All lines (including symbol-only lines like `}`) use `C{occurrence}` as the discriminator, where `occurrence` is the running count of that canonical content earlier in the file. This way:
 
-- `}` on line 5 and `}` on line 17 hash differently (different `S{...}` prefix).
-- `import { foo } from 'bar';` on line 3 and the same string on line 47 hash differently (different `C{...}` prefix, 1 vs 2).
+- `}` on line 5 and `}` on line 17 hash differently (1st vs 2nd occurrence of `}`).
+- `import { foo } from 'bar';` on line 3 and the same string on line 47 hash differently (1st vs 2nd occurrence).
 
 The runtime always precomputes the full per-line hash array for a file via `computeLineHashes(content)`, then looks up by line number during validation and during `read` / `edit` response formatting. There is no per-line recomputation that could disagree with what the model saw in its last read.
 
@@ -125,7 +124,7 @@ The runtime always precomputes the full per-line hash array for a file via `comp
 
 ### Bare-prefix detector
 
-With the `|` delimiter format, the bare-prefix detector regex `^\s*[A-Za-z0-9_-]{4}|` is highly specific. It only matches lines starting with exactly 4 base64 chars and `|`. This eliminates false positives from common code patterns like `init:`, `data:`, `else:`, etc. The detector rejects edit lines matching this pattern with `[E_BARE_HASH_PREFIX]` to prevent the model from accidentally pasting hash anchors into file content.
+With the `│` delimiter format, the bare-prefix detector regex `^\s*[A-Za-z0-9_\-]{4}│` is highly specific. It only matches lines starting with exactly 4 base64 chars and `│`. This eliminates false positives from common code patterns like `init:`, `data:`, `else:`, etc. The detector rejects edit lines matching this pattern with `[E_BARE_HASH_PREFIX]` to prevent the model from accidentally pasting hash anchors into file content.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Strict hashline read/edit tool override for pi-coding-agent with hash-anchored edits (4-char, 24-bit)",
   "main": "index.ts",
   "repository": {

package/prompts/edit-guidelines.md

@@ -0,0 +1,3 @@
+- Use edit with HASH anchors for all file changes; batch every change to one file into a single edit call.
+- After a successful edit, the returned `--- Anchors ---` block replaces a re-read for nearby follow-up edits.
+- On `[E_STALE_ANCHOR]`, retry with the `>>>` lines quoted in the error instead of re-reading the whole file.

package/prompts/edit-snippet.md

@@ -1 +1 @@
-Edit a text file via HASH anchors from read
+Edit a text file via HASH anchors from read, batching all edits to a file in one call

package/prompts/edit.md

@@ -44,6 +44,7 @@ Rules:
 - `lines` is literal file content. No `HASH│` prefix, no leading `+`/`-` (those are read/diff metadata, not file content). Lines starting with 4 base64 chars + `│` are checked; if detected, the edit is rejected with `[E_BARE_HASH_PREFIX]`. For `.py` files, this becomes a `[W_BARE_HASH_PREFIX]` warning instead (Python syntax like `else:`, `except:` triggers the detector).
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - All edits in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if: two `replace` ranges overlap; two `append`/`prepend` target the same insertion boundary (e.g. two EOF appends on a newline-terminated file); or an `append`/`prepend` falls inside a `replace` range in the same call. Fix: merge into one, use different boundaries, or split into a follow-up `edit` call.
+- When building `replace` ranges, double-check that `start` is on the first line you want changed and `end` is on the last. If two edits would touch the same lines or adjacent lines, merge them into one `replace` with the combined new content.
 - If `lines` matches the current content byte-for-byte, the edit is classified as `Classification: noop` (file unchanged, not an error).
 
 On success (`changed` mode, default), the response text contains an `--- Anchors ---` block with fresh `HASH│content` for the changed region (2 lines of context, capped at ~12 lines / 50 KB). Use those for nearby follow-up edits instead of re-reading. If the response says `Anchors omitted; use read for subsequent edits`, the region was too large — call `read` again. For distant follow-ups, or on any error, call `read` again. `full` and `ranges` modes put previews in `details`; the model only needs what's in the text.

package/prompts/read.md

@@ -22,6 +22,9 @@ File kinds:
 - Images (JPEG, PNG, GIF, WebP) are returned as visual attachments; the HASH-line protocol does not apply.
 - Binary files and directories are rejected with a descriptive error.
 
+Non-UTF-8 bytes:
+- Non-UTF-8 bytes are decoded as U+FFFD. The output is flagged when this happens; editing such a file rewrites it as UTF-8. Recover the original encoding with `iconv` afterwards if it must survive.
+
 Auto-read after write:
 - After a successful `write`, the result includes a `--- Auto-read (hashline anchors) ---` block with `HASH│content` for the written file.
 - Use those anchors directly for `edit` calls without a separate `read`.

package/src/edit.ts

@@ -198,6 +198,15 @@ const EDIT_PROMPT_SNIPPET = readFileSync(
 	"utf-8",
 ).trim();
 
+
+const EDIT_PROMPT_GUIDELINES = readFileSync(
+	new URL("../prompts/edit-guidelines.md", import.meta.url),
+	"utf-8",
+)
+	.split("\n")
+	.map((line) => line.trim())
+	.filter((line) => line.startsWith("- "))
+	.map((line) => line.slice(2));
 const ROOT_KEYS = new Set(["path", "returnMode", "returnRanges", "edits"]);
 
 export function assertEditRequest(
@@ -426,6 +435,7 @@ const editToolDefinition: EditToolDefinition = {
 	description: EDIT_DESC,
 	parameters: hashlineEditToolSchema,
 	promptSnippet: EDIT_PROMPT_SNIPPET,
+	promptGuidelines: EDIT_PROMPT_GUIDELINES,
 	prepareArguments: (args: unknown) =>
 		normalizeEditRequest(args) as EditRequestParams,
 	renderShell: "default",

package/src/hashline/hash.ts

@@ -40,7 +40,7 @@ export const DIFF_MINUS_RE = /^-\s*\d+\s{4}/;
 
 export const HASHLINE_BARE_PREFIX_RE = new RegExp(`^\\s*(${HASH_CHARS_CLASS})│`);
 
-const RE_SIGNIFICANT = /[\p{L}\p{N}]/u;
+
 
 // Lazy-initialized xxhash-wasm hasher. Initialization starts at module load
 // time and completes in ~2ms. By the time any tool calls xxh32(), the hasher
@@ -64,50 +64,35 @@ hasherPromise = xxhash().then((h) => {
 
 // Export for tests that need to await readiness.
 export function ensureHasherReady(): Promise<Hasher> {
-	return hasherPromise!;
+	return hasherPromise!
 }
 
 function xxh32(input: string, seed = 0): number {
 	return getHasher().h32(input, seed) >>> 0;
 }
 
-const SYMBOL_DISCRIMINATOR = (lineNumber: number): string => `S${lineNumber}`;
-const CONTENT_DISCRIMINATOR = (occurrence: number): string => `C${occurrence}`;
+const DISCRIMINATOR = (occurrence: number): string => `C${occurrence}`;
 
 function canonicalizeLine(line: string): string {
 	return line.replace(/\r/g, "").trimEnd();
 }
 
-function isSymbolOnly(canonical: string): boolean {
-	return !RE_SIGNIFICANT.test(canonical);
-}
-
 export function computeLineHashes(content: string): string[] {
 	const lines = content.split("\n");
 	const hashes = new Array<string>(lines.length);
 	const counts = new Map<string, number>();
 	for (let i = 0; i < lines.length; i++) {
-		const lineNumber = i + 1;
 		const canonical = canonicalizeLine(lines[i]!);
-		let discriminator: string;
-		if (isSymbolOnly(canonical)) {
-			discriminator = SYMBOL_DISCRIMINATOR(lineNumber);
-		} else {
-			const occurrence = (counts.get(canonical) ?? 0) + 1;
-			counts.set(canonical, occurrence);
-			discriminator = CONTENT_DISCRIMINATOR(occurrence);
-		}
-		hashes[i] = hashToString(xxh32(`${discriminator}:${canonical}`));
+		const occurrence = (counts.get(canonical) ?? 0) + 1;
+		counts.set(canonical, occurrence);
+		hashes[i] = hashToString(xxh32(`${DISCRIMINATOR(occurrence)}:${canonical}`));
 	}
 	return hashes;
 }
 
 export function computeLineHash(idx: number, line: string): string {
 	const canonical = canonicalizeLine(line);
-	const discriminator = isSymbolOnly(canonical)
-		? SYMBOL_DISCRIMINATOR(idx)
-		: CONTENT_DISCRIMINATOR(1);
-	return hashToString(xxh32(`${discriminator}:${canonical}`));
+	return hashToString(xxh32(`${DISCRIMINATOR(1)}:${canonical}`));
 }
 
 export const HASH_FORMAT = {