pi-hashline-edit-pro 0.4.2 → 0.4.3

package/README.md

@@ -33,7 +33,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 +44,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 +60,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 +84,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,20 +97,20 @@ 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.
 
@@ -125,7 +125,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.4.3",
   "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/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",