pi-tian-edit-safe 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 TianZuo555
+
+Algorithmic lineage (not code) adapted from opencode (MIT, Copyright (c) 2025 opencode),
+which itself draws from cline diff-apply (MIT) and gemini-cli editCorrector (Apache-2.0).
+See NOTICES.md for attribution. This project contains no code from maka-agent
+(which carries no license); only the design philosophy (strict ambiguity handling,
+full-span verification) is reproduced from scratch.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICES.md

@@ -0,0 +1,34 @@
+# Dependency attribution. none required at runtime beyond what pi bundles,
+# but recorded for completeness.
+
+## opencode
+- Source: https://github.com/sst/opencode  (`packages/opencode/src/tool/edit.ts`)
+- License: MIT, Copyright (c) 2025 opencode
+- Used for: algorithmic reference for the line-trimmed, whitespace-normalized,
+  escape-normalized fuzzy strategies and the `isDisproportionateMatch` heuristic.
+  Re-implemented from scratch; no code copied verbatim.
+
+## pi-coding-agent
+- Source: https://github.com/earendil-works/pi  (`core/tools/edit-diff.ts`)
+- License: MIT
+- Used for: the unicode punctuation normalization table (smart quotes, dash
+  variants, special spaces, NFKC) behind the `unicode` fuzzy strategy. Applied
+  span-only here (comparison never rewrites file bytes), unlike upstream's
+  whole-content normalize-and-restore pipeline.
+
+## cline
+- Source: https://github.com/cline/cline  (evals/diff-edits/diff-apply)
+- License: MIT
+- Used for: original upstream diff-apply concepts (via opencode).
+
+## gemini-cli
+- Source: https://github.com/google-gemini/gemini-cli  (editCorrector)
+- License: Apache-2.0
+- Used for: original upstream edit-correction concepts (via opencode).
+
+## maka-agent
+- Source: https://github.com/Maka-Agent/maka-agent
+- License: NONE (all rights reserved) — NOT used as a code source.
+- Used for: design philosophy only (strict ambiguity handling, full-span
+  verification, hard gates before fuzzy matching, throw-on-ambiguity
+  orchestration). Reproduced from scratch without referencing its source code.

package/README.md

@@ -0,0 +1,123 @@
+# pi-edit-safe
+
+A drop-in replacement for the **pi coding agent**'s built-in `edit` tool, with a
+stricter matcher that refuses to silently edit the wrong place — and a call shape
+that weaker models can actually use.
+
+> Exposes **one** call shape — `{path, edits: [...]}`, always an array, even for a
+> single replacement — so the model has nothing to choose per call. Multi-edit
+> applies **in order** (sequential), the contract models assume from multi-edit
+> tools elsewhere, instead of pi's all-against-the-original-file semantic.
+>
+> The looser shapes models emit anyway are still folded onto that form before
+> validation, so a stray legacy call is normalized rather than rejected — they
+> are just not advertised.
+
+Install: `npm:pi-tian-edit-safe` · npm package `pi-tian-edit-safe` · workspace `packages/pi-edit-safe`
+
+## Call shape
+
+One shape, always an array:
+
+```jsonc
+// single change — still a one-element array:
+{ "path": "src/a.ts", "edits": [
+	{ "oldText": "const x = 1;", "newText": "const x = 2;" }
+] }
+
+// several changes, applied in order, top to bottom:
+{ "path": "src/a.ts", "edits": [
+	{ "oldText": "...", "newText": "..." },
+	{ "oldText": "...", "newText": "..." }
+] }
+```
+
+`path` and `edits` are both required and `edits` has `minItems: 1`. Nothing else
+is advertised to the model.
+
+### Tolerated but not advertised
+
+`prepareArguments` runs **before** schema validation (per pi's extension
+contract) and folds these onto the canonical form: `file_path`/`filePath`/`filename`
+for `path`; `old_string`/`new_string`, `oldString`/`newString`, `old_str`/`new_str`
+for the pair (per entry or top-level); top-level `oldText`/`newText` shorthand;
+`edits` as a JSON **string**; and `edits` as a single object.
+
+This keeps old resumed sessions and off-contract calls working without widening
+the public schema. Exact duplicate entries are rejected loudly. When a later edit
+fails because an earlier edit in the same call rewrote its target, the error says
+exactly that.
+
+## Design stance
+
+| Decision | typical fuzzy edit tools | **pi-edit-safe** |
+|---|---|---|
+| Partial-signal strategies (first/last-line anchor) | yes | **none** |
+| On ambiguity | fall through to next candidate | **throw immediately** |
+| Fuzzy candidate validation | per-candidate similarity threshold | **full-span structural equality + exactly-one + occurs-once** |
+| Overlapping exact matches | often missed | **caught** (overlap-aware counting) |
+| Unicode punctuation drift (smart quotes, em dash, NBSP) | varies | **strict `unicode` strategy**, span-only |
+| Untouched bytes | may be normalized whole-file | **never touched** (slice + verbatim splice) |
+| Line endings | whole-file normalize/restore | **span-boundary only**; mixed-ending files never flattened |
+| `newText` write | `String.replace` (`$&` hazard) | **slice-join** (literal) |
+| Multi-edit semantics | all edits vs the original file | **sequential, in order** |
+| Call shapes offered to the model | varies | **exactly one** (`edits[]`) |
+
+Fuzzy matching only ever *locates a span*. The replacement is spliced in
+verbatim — it is never re-indented or rewritten.
+
+## Matching order
+
+1. **Exact**, never gated, counted overlap-aware (`aa` in `aaa` is ambiguous, not unique).
+2. If exact fails, hard gates: ≥5 non-space chars, no NUL byte, ≤1M chars, ≤50k lines.
+3. Increasingly tolerant **full-span** strategies: line-trimmed → unicode
+   punctuation → collapsed whitespace → escape-normalized.
+4. More than one candidate for a strategy → **throw**. Never falls through from
+   ambiguity to a looser matcher.
+5. Splice verbatim. Uniform LF/CRLF files adapt the replacement's newlines;
+   mixed-ending files take it as-is.
+6. Apply all entries in memory, in order, then write once — a later failure
+   leaves the file unchanged.
+
+## Result details
+
+Returns pi's built-in `EditToolDetails` shape (`diff`, `patch`,
+`firstChangedLine`) alongside a `edits[]` array of per-edit provenance
+(`matchedVia`, `startLine`, `endLine`).
+
+Because pi resolves renderer inheritance **per slot**
+(`toolDefinition.renderCall ?? builtInToolDefinition.renderCall`), this override
+deliberately defines neither `renderCall` nor `renderResult`, and so inherits
+pi's streaming diff preview and final diff rendering for free.
+
+The diff is computed against the **real bytes** on both sides. pi's built-in
+diffs its LF-normalized view instead, which is why the two disagree on
+mixed-line-ending files (see bench case 11).
+
+## Disable
+
+```bash
+PI_EDIT_SAFE_DISABLE=1 pi   # falls back to the built-in edit
+```
+
+## Tests and A/B bench
+
+```bash
+npm test -w pi-tian-edit-safe    # 45 unit tests (Node's built-in runner)
+npm run bench -w pi-tian-edit-safe
+```
+
+The bench imports pi's **actual shipped** `edit-diff.js` functions and composes
+them exactly as `dist/core/tools/edit.js` does, then runs the same 12
+(file, edits) cases through both pipelines and reports every divergence,
+including "canary" lines that must stay byte-identical.
+
+These are deterministic corruption regressions. They are **not** a model-level
+eval — no cross-model pass@1 / token / retry benchmark exists for this tool yet.
+
+## Attribution
+
+Fuzzy-strategy concepts adapted from opencode (MIT, via cline MIT and
+gemini-cli Apache-2.0); the unicode normalization table mirrors pi's own
+normalizer (MIT), applied span-only. Design philosophy reproduced
+independently. See [NOTICES.md](./NOTICES.md).

package/index.ts

@@ -0,0 +1,134 @@
+// pi extension: override the built-in `edit` tool with a stricter, full-span
+// matcher. The model-facing contract is ONE call shape — {path, edits: [...]},
+// always an array, even for a single replacement — so there is no per-call
+// choice to get wrong. Multi-edit applies IN ORDER (sequential), the contract
+// models assume from multi-edit tools elsewhere.
+//
+// Looser shapes models emit anyway (top-level oldText/newText, alias field
+// names, stringified arrays, a bare edit object) are folded onto the canonical
+// form by prepareArguments BEFORE validation. They are accepted for robustness
+// and older resumed sessions, but deliberately NOT advertised in the schema.
+//
+// Quick try:   pi -e ./packages/pi-edit-safe
+// Disable:     PI_EDIT_SAFE_DISABLE=1 pi   (falls back to the built-in edit)
+//
+// Result shape note: pi resolves built-in renderer inheritance per slot
+// (`toolDefinition.renderCall ?? builtInToolDefinition.renderCall`), so this
+// override deliberately defines NEITHER renderCall nor renderResult and instead
+// returns the built-in `EditToolDetails` shape ({ diff, patch, firstChangedLine }).
+// That inherits pi's streaming diff preview and final diff rendering for free.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	generateDiffString,
+	generateUnifiedPatch,
+	withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { applyEdits } from "./lib/edit-replace.ts";
+import { prepareEditArguments } from "./lib/prepare-arguments.ts";
+
+const parameters = Type.Object({
+	path: Type.String({
+		description: "Path to the file to edit (relative or absolute).",
+	}),
+	edits: Type.Array(
+		Type.Object({
+			oldText: Type.String({
+				description:
+					"Exact text to find. Must be unique in the file at the time this edit applies.",
+			}),
+			newText: Type.String({
+				description: "Replacement text, written verbatim.",
+			}),
+		}),
+		{
+			minItems: 1,
+			description:
+				"One or more replacements, applied in order, first to last. Use a single-element array for a single change. Each oldText is matched against the file as already changed by the previous edits in this call.",
+		},
+	),
+});
+
+export default function editSafeExtension(pi: ExtensionAPI): void {
+	// Kill switch: if set, do not register and let the built-in edit remain active.
+	if (process.env.PI_EDIT_SAFE_DISABLE === "1") return;
+
+	pi.registerTool({
+		name: "edit", // same name as the built-in → overrides it
+		label: "edit (strict)",
+		description:
+			"Replace text in a file. Pass path and edits: [{oldText, newText}, ...] — always an array, even for a single change. Edits apply in order, one after another, each matched against the already-updated text. Each oldText must match the file and be unique; small whitespace/indentation, unicode-punctuation, or escape drift is tolerated only when the match is unambiguous. newText is written verbatim. On failure the error explains why so you can re-read the file and retry.",
+		parameters,
+		// Fold the looser shapes models emit (alias keys, stringified arrays, a bare
+		// edit object, top-level oldText/newText) onto the canonical {path, edits[]}
+		// form BEFORE schema validation. The public schema stays strict: `edits` is
+		// the only advertised way to call this tool, so the model has one shape to
+		// learn and no choice to make. Normalization exists only so a stray legacy
+		// shape — including tool calls stored in older resumed sessions — still
+		// works instead of hard-failing validation.
+		prepareArguments: (args: unknown) => prepareEditArguments(args) as Static<typeof parameters>,
+		promptGuidelines: [
+			"Prefer `edit` for targeted changes and `write` only for new files or full rewrites.",
+			"Always pass `edits` as an array — use a one-element array for a single change. Edits apply in order, top to bottom.",
+			"Each oldText must be unique in the file; include surrounding lines to disambiguate when needed.",
+			"On an edit failure, re-read the file before retrying — the error usually means your context was stale or the match was ambiguous.",
+		],
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			// Re-normalize defensively: the prepareArguments hook already ran on
+			// current pi versions, and normalization is idempotent.
+			const { path, edits } = prepareEditArguments(params);
+			if (!path) {
+				throw new Error(`edit: missing "path" — pass the file to edit`);
+			}
+			const abs = resolve(ctx.cwd, path);
+
+			// Read, match, and write all inside the mutation queue so no other
+			// pi-side mutation can interleave between our read and our write.
+			return withFileMutationQueue(abs, async () => {
+				const throwIfAborted = () => {
+					if (signal?.aborted) throw new Error("Operation aborted");
+				};
+				throwIfAborted();
+
+				let source: string;
+				try {
+					source = await readFile(abs, "utf-8");
+				} catch (err) {
+					throw new Error(
+						`edit: cannot read "${path}" (${(err as NodeJS.ErrnoException).message}). Use the write tool to create a new file.`,
+					);
+				}
+				throwIfAborted();
+
+				const { content, edits: outcomes } = applyEdits(source, edits, path);
+				await writeFile(abs, content, "utf-8");
+
+				const summary = outcomes
+					.map((o, i) => `  ${i + 1}. ${o.matchedVia} match → lines ${o.startLine}-${o.endLine}`)
+					.join("\n");
+
+				// Diff against the real bytes on both sides. This matcher never
+				// normalizes the file, so `source` IS the base content — unlike
+				// pi's built-in, which diffs its LF-normalized view.
+				const { diff, firstChangedLine } = generateDiffString(source, content);
+				const patch = generateUnifiedPatch(path, source, content);
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Edited ${path} (${outcomes.length} replacement${outcomes.length > 1 ? "s, applied in order" : ""}):\n${summary}`,
+						},
+					],
+					// Built-in EditToolDetails shape (diff/patch/firstChangedLine) so
+					// pi's inherited renderer and SDK/ACP consumers keep working;
+					// `edits` carries the extra strict-matcher provenance.
+					details: { path: abs, diff, patch, firstChangedLine, edits: outcomes },
+				};
+			});
+		},
+	});
+}

package/lib/edit-replace.ts

@@ -0,0 +1,475 @@
+// edit-replace.ts — strict, fault-tolerant multi-edit string replacement.
+//
+// Algorithmic concepts (line-trimmed / whitespace-normalized / escape-normalized
+// fuzzy strategies, isDisproportionate heuristic) adapted from opencode's MIT
+// edit.ts, which traces to cline (MIT) and gemini-cli (Apache-2.0). The unicode
+// punctuation mapping mirrors pi's own fuzzy normalizer (MIT), applied here
+// span-only. Re-implemented from scratch. See NOTICES.md.
+//
+// DESIGN PHILOSOPHY (reproduced independently from the maka-agent project, which
+// is unlicensed and was NOT used as a code source):
+//   1. Exact match first, no gating. Large files edit fine with an exact snippet.
+//   2. Fuzzy matching is gated (min length, binary, size) and ONLY locates a span;
+//      the replacement is written VERBATIM. Fuzzy never re-indents or rewrites.
+//   3. Every fuzzy candidate must be a FULL-span structural match, must be the
+//      single candidate, and must occur exactly once. Any ambiguity THROWS rather
+//      than falling through to a looser strategy. "Better to fail loudly than to
+//      silently edit the wrong place."
+//   4. No partial-signal strategies (no first/last-line anchoring, no similarity
+//      thresholds). Those are the documented cause of wrong-location edits in
+//      upstream projects.
+//   5. Line endings are handled at the span boundary, never whole-file: a fuzzy
+//      span never captures the trailing \r of a CRLF pair, newText is converted
+//      only when the file's endings are uniform, and untouched terminators are
+//      never rewritten (mixed files stay mixed).
+//   6. Multi-edit calls apply SEQUENTIALLY, in order — each oldText is matched
+//      against the result of the previous edits, the contract models assume
+//      from multi-edit tools elsewhere (pi's built-in instead matches all edits
+//      against the original file). Disjoint edits behave identically under both;
+//      dependent edits work here, duplicates are rejected loudly, and failures
+//      caused by an earlier edit in the same call say so.
+
+export type MatchStrategy = "exact" | "line-trimmed" | "unicode" | "whitespace" | "escape";
+
+export interface EditRequest {
+	oldText: string;
+	newText: string;
+}
+
+export interface EditOutcome {
+	/** Which strategy located oldText. */
+	matchedVia: MatchStrategy;
+	/** 1-based first line of the matched span, in the content the edit was
+	 * applied to (the original file for edit 1; for later edits, the text as
+	 * already changed by the previous edits in the call). */
+	startLine: number;
+	/** 1-based last line (inclusive) of the matched span, same reference. */
+	endLine: number;
+}
+
+/** Machine-readable failure codes for every error this module throws. */
+export type EditErrorCode =
+	| "no-edits"
+	| "invalid-edit"
+	| "duplicate-edit"
+	| "empty-old-text"
+	| "no-op-edit"
+	| "too-short"
+	| "binary"
+	| "too-large"
+	| "not-unique"
+	| "ambiguous"
+	| "disproportionate"
+	| "not-found"
+	| "no-changes";
+
+/** Every failure this module throws, tagged with a machine-readable code.
+ *
+ * `code` is assigned in the constructor body rather than declared as a
+ * TypeScript parameter property: parameter properties emit real code, so they
+ * are rejected by Node's type-stripping loader (and every other strip-only
+ * transform). This package ships uncompiled TypeScript, so it must stay within
+ * erasable-syntax-only constructs. */
+export class EditError extends Error {
+	readonly code: EditErrorCode;
+
+	constructor(message: string, code: EditErrorCode) {
+		super(message);
+		this.name = "EditError";
+		this.code = code;
+	}
+}
+
+export interface ApplyResult {
+	content: string;
+	edits: EditOutcome[];
+}
+
+// Fuzzy is O(n) per pass over the whole source; gate it to text-sized inputs.
+const MIN_FUZZY_OLD_TEXT_LENGTH = 5;
+const MAX_FUZZY_SOURCE_CHARS = 1_000_000;
+const MAX_FUZZY_SOURCE_LINES = 50_000;
+
+/**
+ * Apply one or more edits to `source`, SEQUENTIALLY: each edit's `oldText` is
+ * matched against the content as already changed by the previous edits in the
+ * same call — the contract models assume from multi-edit tools elsewhere.
+ * Disjoint edits produce exactly the same bytes as matching everything against
+ * the original file; dependent edits (a later oldText targeting an earlier
+ * newText's output) work instead of erroring.
+ *
+ * @throws when any oldText is missing, ambiguous (not unique), empty, identical
+ *   to its newText, an exact duplicate of an earlier edit, too short for a safe
+ *   fuzzy match, on a binary/too-large file, or when the result is identical to
+ *   the source.
+ */
+export function applyEdits(source: string, edits: EditRequest[], where: string): ApplyResult {
+	if (!Array.isArray(edits) || edits.length === 0) {
+		throw new EditError(
+			`edit: no edits provided for ${where} — pass oldText/newText for a single replacement, or edits: [{oldText, newText}, ...] for several`,
+			"no-edits",
+		);
+	}
+
+	// Validate shape and reject exact duplicates up front. Models sometimes emit
+	// the same edit twice; under sequential application a duplicate could even
+	// apply twice (when newText still contains oldText), so fail loudly instead.
+	const seen = new Set<string>();
+	for (let i = 0; i < edits.length; i++) {
+		const e = edits[i];
+		if (!e || typeof e.oldText !== "string" || typeof e.newText !== "string") {
+			throw new EditError(
+				`edit ${i + 1}: each edit needs string oldText and newText fields in ${where}`,
+				"invalid-edit",
+			);
+		}
+		const key = JSON.stringify([e.oldText, e.newText]);
+		if (seen.has(key)) {
+			throw new EditError(
+				`edit ${i + 1} is an exact duplicate of an earlier edit in ${where}; remove it (each replacement is applied once)`,
+				"duplicate-edit",
+			);
+		}
+		seen.add(key);
+	}
+
+	let content = source;
+	const outcomes: EditOutcome[] = new Array(edits.length);
+	for (let i = 0; i < edits.length; i++) {
+		const { oldText, newText } = edits[i];
+		const editWhere = edits.length === 1 ? where : `${where} (edit ${i + 1} of ${edits.length})`;
+		if (oldText === "") {
+			throw new EditError(`edit ${i + 1}: oldText must not be empty in ${where}`, "empty-old-text");
+		}
+		if (oldText === newText) {
+			throw new EditError(`edit ${i + 1}: no changes to apply in ${where} (oldText === newText)`, "no-op-edit");
+		}
+
+		let span: { start: number; end: number; via: MatchStrategy };
+		try {
+			span = resolveSpan(content, oldText, editWhere);
+		} catch (err) {
+			throw withSequentialHint(err, source, oldText, i);
+		}
+
+		outcomes[i] = {
+			matchedVia: span.via,
+			startLine: lineOf(content, span.start),
+			endLine: lineOf(content, span.end - 1),
+		};
+		content = content.slice(0, span.start) + toFileLineEndings(newText, content) + content.slice(span.end);
+	}
+
+	// A fuzzy span can equal newText even when oldText !== newText (drifted
+	// oldText, file already in the desired state). A silent no-op write would
+	// hide the model's stale context — fail loudly instead.
+	if (content === source) {
+		throw new EditError(
+			`edit: no changes were produced in ${where} — the file already matches the requested result; re-read it before retrying`,
+			"no-changes",
+		);
+	}
+
+	return { content, edits: outcomes };
+}
+
+/** When a later edit fails because an EARLIER edit in the same call rewrote its
+ * target (or introduced new matches), say so — a bare "not found" would send the
+ * model re-reading a file that never contained the problem. */
+function withSequentialHint(err: unknown, source: string, oldText: string, index: number): unknown {
+	if (index === 0 || !(err instanceof EditError)) return err;
+	if (err.code === "not-found" && countOccurrences(source, oldText) > 0) {
+		return new EditError(
+			`${err.message}; note: edits apply in order, and an earlier edit in this call already changed this text — write oldText against the updated content, or merge the edits into one`,
+			err.code,
+		);
+	}
+	if ((err.code === "not-unique" || err.code === "ambiguous") && countOccurrences(source, oldText) <= 1) {
+		return new EditError(
+			`${err.message}; note: edits apply in order, and an earlier edit's newText introduced additional matches — merge or reorder the edits`,
+			err.code,
+		);
+	}
+	return err;
+}
+
+/** Resolve a single oldText to a unique [start, end) span, exact then guarded fuzzy. */
+function resolveSpan(source: string, oldText: string, where: string): { start: number; end: number; via: MatchStrategy } {
+	// Exact match first — never gated. Occurrences are counted overlap-aware:
+	// "aa" in "aaa" is ambiguous (positions 0 and 1), not a unique match.
+	const exactCount = countOccurrences(source, oldText);
+	if (exactCount === 1) {
+		const idx = source.indexOf(oldText);
+		return { start: idx, end: idx + oldText.length, via: "exact" };
+	}
+	if (exactCount > 1) {
+		throw new EditError(`oldText is not unique in ${where} (${exactCount} exact matches); provide more context`, "not-unique");
+	}
+
+	// Exact failed → fuzzy. Apply hard gates up front.
+	if (oldText.trim().length < MIN_FUZZY_OLD_TEXT_LENGTH) {
+		throw new EditError(
+			`oldText is too short for a non-exact match in ${where}; provide a longer, exact snippet`,
+			"too-short",
+		);
+	}
+	if (source.indexOf("\0") !== -1) {
+		throw new EditError(`refusing a non-exact match in ${where}: file looks binary (contains a NUL byte); re-read and pass exact text`, "binary");
+	}
+	if (source.length > MAX_FUZZY_SOURCE_CHARS || countOccurrences(source, "\n") + 1 > MAX_FUZZY_SOURCE_LINES) {
+		throw new EditError(`refusing a non-exact match in ${where}: file is too large to fuzzy-match safely; re-read and pass exact text`, "too-large");
+	}
+
+	// Ordered by increasing tolerance. `effectiveFind` is what the strategy
+	// semantically matched against, used for the disproportion guard (the escape
+	// strategy legitimately expands a 1-line "a\nb\nc" oldText to 3 real lines).
+	const strategies: Array<{ via: MatchStrategy; find: (c: string, f: string) => string[]; effectiveFind: string }> = [
+		{ via: "line-trimmed", find: lineTrimmedSpans, effectiveFind: oldText },
+		{ via: "unicode", find: unicodePunctuationSpans, effectiveFind: oldText },
+		{ via: "whitespace", find: whitespaceNormalizedSpans, effectiveFind: oldText },
+		{ via: "escape", find: escapeNormalizedSpans, effectiveFind: unescapeText(oldText) },
+	];
+
+	for (const { via, find, effectiveFind } of strategies) {
+		const candidates = dedupe(find(source, oldText).filter((c) => c.length > 0 && source.includes(c)));
+		if (candidates.length === 0) continue; // this strategy found nothing → try the next
+		if (candidates.length > 1) {
+			throw new EditError(`oldText matched ${candidates.length} different ${via} candidates in ${where}; provide more context to disambiguate`, "ambiguous");
+		}
+		const span = candidates[0];
+		// Must occur exactly once as a string too.
+		if (source.indexOf(span) !== source.lastIndexOf(span)) {
+			throw new EditError(`oldText matched a ${via} span that occurs more than once in ${where}; provide more context to disambiguate`, "ambiguous");
+		}
+		if (isDisproportionate(span, effectiveFind)) {
+			throw new EditError(`refusing ${via} match in ${where}: the matched span is much larger than oldText; re-read and pass exact text`, "disproportionate");
+		}
+		const start = source.indexOf(span);
+		let end = start + span.length;
+		// Strategies split on \n, so in a CRLF file the last matched line carries
+		// its \r into the span. That \r belongs to the file's line terminator:
+		// leave it in place, or the splice would turn \r\n into a bare \n.
+		if (source[end - 1] === "\r" && source[end] === "\n") end -= 1;
+		return { start, end, via };
+	}
+
+	throw new EditError(`oldText not found in ${where}; it must match the file's text including whitespace and indentation`, "not-found");
+}
+
+// --- fuzzy strategies: each returns ORIGINAL substrings (never normalized) ---
+
+/**
+ * Shared line-block walker: match `find` against consecutive whole lines of
+ * `content` using `sameLine`, returning the ORIGINAL substring for each match.
+ * If `find` ends with a newline, the span must include the file's newline after
+ * the last matched line (EOF without one is not a faithful match → skip).
+ */
+function lineBlockSpans(
+	content: string,
+	find: string,
+	sameLine: (fileLine: string, findLine: string) => boolean,
+): string[] {
+	const out: string[] = [];
+	const lines = content.split("\n");
+	const findEndsWithNewline = find.endsWith("\n");
+	const search = find.split("\n");
+	if (search.length > 0 && search[search.length - 1] === "") search.pop();
+	if (search.length === 0) return out;
+
+	for (let i = 0; i <= lines.length - search.length; i++) {
+		let ok = true;
+		for (let j = 0; j < search.length; j++) {
+			if (!sameLine(lines[i + j], search[j])) {
+				ok = false;
+				break;
+			}
+		}
+		if (!ok) continue;
+
+		let start = 0;
+		for (let k = 0; k < i; k++) start += lines[k].length + 1;
+		let end = start;
+		for (let k = 0; k < search.length; k++) {
+			end += lines[i + k].length;
+			if (k < search.length - 1) end += 1;
+		}
+		if (findEndsWithNewline) {
+			const lastLine = i + search.length - 1;
+			if (lastLine >= lines.length - 1) continue;
+			end += 1;
+		}
+		out.push(content.slice(start, end));
+	}
+	return out;
+}
+
+/** Match line-by-line after trimming each line. Handles indentation/trailing-ws drift. */
+function lineTrimmedSpans(content: string, find: string): string[] {
+	return lineBlockSpans(content, find, (a, b) => a.trim() === b.trim());
+}
+
+/**
+ * Unicode punctuation mapping (mirrors pi's fuzzy normalizer): smart quotes,
+ * unicode dashes, and special spaces collapse to their ASCII equivalents, plus
+ * NFKC. Used for COMPARISON only — matched spans keep their original bytes.
+ */
+function normalizeUnicodePunctuation(text: string): string {
+	return text
+		.normalize("NFKC")
+		// Smart single quotes → '
+		.replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+		// Smart double quotes → "
+		.replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+		// Hyphen/dash variants and minus → -
+		.replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
+		// NBSP and other special spaces → regular space
+		.replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
+}
+
+/** Match after mapping unicode punctuation to ASCII (per line, trimmed). The
+ * drift the model most often gets wrong in prose/markdown: “ ” vs ", — vs -, NBSP. */
+function unicodePunctuationSpans(content: string, find: string): string[] {
+	return lineBlockSpans(
+		content,
+		find,
+		(a, b) => normalizeUnicodePunctuation(a).trim() === normalizeUnicodePunctuation(b).trim(),
+	);
+}
+
+/** Match after collapsing all runs of whitespace to a single space. */
+function whitespaceNormalizedSpans(content: string, find: string): string[] {
+	const out: string[] = [];
+	const norm = (t: string) => t.replace(/\s+/g, " ").trim();
+	const findEndsWithNewline = find.endsWith("\n");
+	const findLines = find.split("\n");
+	if (findEndsWithNewline) findLines.pop();
+	if (findLines.length === 0) return out;
+	const want = norm(findLines.join("\n"));
+	if (want === "") return out;
+	const lines = content.split("\n");
+
+	// When oldText ends with a newline, the span must include the file's newline
+	// after the last matched line — and must NOT absorb a following
+	// whitespace-only line (norm() would treat its bytes as invisible).
+	const push = (i: number, count: number) => {
+		const block = lines.slice(i, i + count).join("\n");
+		if (findEndsWithNewline) {
+			if (i + count - 1 >= lines.length - 1) return; // EOF: no newline to include
+			out.push(block + "\n");
+		} else {
+			out.push(block);
+		}
+	};
+
+	if (findLines.length === 1) {
+		// Single-line oldText matches whole lines only. A multi-line oldText must
+		// never collapse onto one physical line (would be a wrong-location edit).
+		for (let i = 0; i < lines.length; i++) {
+			if (norm(lines[i]) === want) push(i, 1);
+		}
+	} else {
+		for (let i = 0; i <= lines.length - findLines.length; i++) {
+			const block = lines.slice(i, i + findLines.length).join("\n");
+			if (norm(block) === want) push(i, findLines.length);
+		}
+	}
+	return out;
+}
+
+/** Unescape common escape sequences (\n \t \\ etc.) written literally. */
+function unescapeText(str: string): string {
+	return str.replace(/\\(n|t|r|'|"|`|\\|\n|\$)/g, (m, ch: string) => {
+		switch (ch) {
+			case "n": return "\n";
+			case "t": return "\t";
+			case "r": return "\r";
+			case "'": return "'";
+			case '"': return '"';
+			case "`": return "`";
+			case "\\": return "\\";
+			case "\n": return "\n";
+			case "$": return "$";
+			default: return m;
+		}
+	});
+}
+
+/** Match after unescaping common escape sequences in oldText. */
+function escapeNormalizedSpans(content: string, find: string): string[] {
+	const out: string[] = [];
+	const want = unescapeText(find);
+	if (content.includes(want)) out.push(want);
+	// CRLF variant of the direct match: the unescaped \n may correspond to \r\n
+	// in the file. The returned span keeps the file's original bytes.
+	if (want.includes("\n") && content.includes("\r\n")) {
+		const wantCRLF = want.replace(/\n/g, "\r\n");
+		if (wantCRLF !== want && content.includes(wantCRLF)) out.push(wantCRLF);
+	}
+	const lines = content.split("\n");
+	const findLines = want.split("\n");
+	for (let i = 0; i <= lines.length - findLines.length; i++) {
+		const block = lines.slice(i, i + findLines.length).join("\n");
+		// Compare with the block's CRLF pairs normalized (they are file line
+		// terminators, not content); the pushed span keeps the original bytes.
+		if (unescapeText(block.replace(/\r\n/g, "\n")) === want) out.push(block);
+	}
+	return out;
+}
+
+// --- helpers ---
+
+/** Defense-in-depth guard. The curated strategies above all match a span whose
+ * line count equals the effective find's, so this rarely fires today — it exists
+ * to reject any future partial-signal strategy (first/last-line anchoring) that
+ * could balloon a span, which is the documented cause of wrong-location edits
+ * upstream. */
+export function isDisproportionate(span: string, find: string): boolean {
+	const oldLines = find.split("\n").length;
+	const spanLines = span.split("\n").length;
+	if (spanLines >= Math.max(oldLines + 3, oldLines * 2)) return true;
+	if (oldLines === 1) return false;
+	return span.trim().length > Math.max(find.trim().length + 500, find.trim().length * 4);
+}
+
+/** Overlap-aware occurrence count: advances one char at a time, so "aa" occurs
+ * twice in "aaa". Anything else would silently pick one of two valid positions. */
+function countOccurrences(haystack: string, needle: string): number {
+	if (needle === "") return 0;
+	let count = 0;
+	let idx = haystack.indexOf(needle);
+	while (idx !== -1) {
+		count++;
+		idx = haystack.indexOf(needle, idx + 1);
+	}
+	return count;
+}
+
+function dedupe(arr: string[]): string[] {
+	return [...new Set(arr)];
+}
+
+function lineOf(source: string, index: number): number {
+	let line = 1;
+	for (let i = 0; i < index && i < source.length; i++) {
+		if (source[i] === "\n") line++;
+	}
+	return line;
+}
+
+/**
+ * Convert the replacement's line endings to the file's style, but only when the
+ * file is uniform: CRLF-only files get newText's LF → CRLF, LF-only files get
+ * newText's stray CRLF → LF. Mixed-ending files (and files with no newlines)
+ * take newText verbatim — guessing would rewrite bytes the model never asked for.
+ */
+function toFileLineEndings(text: string, source: string): string {
+	const hasCRLF = source.includes("\r\n");
+	const hasBareLF = /(?<!\r)\n/.test(source);
+	if (hasCRLF && !hasBareLF) {
+		return text.replace(/\r?\n/g, "\r\n");
+	}
+	if (hasBareLF && !hasCRLF) {
+		return text.replace(/\r\n/g, "\n");
+	}
+	return text;
+}

package/lib/prepare-arguments.ts

@@ -0,0 +1,78 @@
+// Input-shape normalizer: maps the call shapes models actually emit onto the
+// canonical {path, edits[]} form BEFORE schema validation. Weaker models
+// pattern-match field names and shapes from other tools they saw in training
+// (Claude Code's old_string/new_string + file_path, opencode's
+// oldString/newString), send `edits` as a JSON string, send a single object
+// instead of an array, or skip the array entirely and pass top-level
+// oldText/newText. All of those are unambiguous — accept them.
+//
+// This function never throws: anything unrecognized passes through so schema
+// validation / applyEdits can report a precise error.
+
+import type { EditRequest } from "./edit-replace.ts";
+
+const PATH_KEYS = ["path", "file_path", "filePath", "filename"];
+const OLD_KEYS = ["oldText", "old_text", "oldString", "old_string", "old_str"];
+const NEW_KEYS = ["newText", "new_text", "newString", "new_string", "new_str"];
+
+function firstString(obj: Record<string, unknown>, keys: string[]): string | undefined {
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === "string") return value;
+	}
+	return undefined;
+}
+
+/** Map one edit-like object to {oldText, newText}, or undefined if it has no
+ * recognizable old/new pair. */
+function toEditEntry(value: unknown): EditRequest | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const obj = value as Record<string, unknown>;
+	const oldText = firstString(obj, OLD_KEYS);
+	const newText = firstString(obj, NEW_KEYS);
+	if (oldText === undefined || newText === undefined) return undefined;
+	return { oldText, newText };
+}
+
+export interface PreparedEditArguments {
+	path?: string;
+	edits: EditRequest[];
+}
+
+/** Normalize raw tool-call arguments to {path, edits[]}. Idempotent: canonical
+ * input maps to itself, so it is safe to run both as the prepareArguments hook
+ * and again defensively inside execute(). */
+export function prepareEditArguments(raw: unknown): PreparedEditArguments {
+	const obj = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+	const path = firstString(obj, PATH_KEYS);
+
+	// Some models send edits as a JSON string instead of an array (pi's own
+	// built-in works around the same behavior).
+	let rawEdits = obj.edits;
+	if (typeof rawEdits === "string") {
+		try {
+			rawEdits = JSON.parse(rawEdits);
+		} catch {
+			rawEdits = undefined;
+		}
+	}
+	// A single {oldText, newText} object instead of a one-element array.
+	if (rawEdits && typeof rawEdits === "object" && !Array.isArray(rawEdits)) {
+		rawEdits = [rawEdits];
+	}
+
+	const edits: EditRequest[] = [];
+	if (Array.isArray(rawEdits)) {
+		for (const entry of rawEdits) {
+			// Keep unmappable entries as-is so applyEdits rejects them with a
+			// precise "edit N needs string oldText/newText" error.
+			edits.push(toEditEntry(entry) ?? (entry as EditRequest));
+		}
+	}
+
+	// Top-level oldText/newText shorthand (with or without an edits array).
+	const top = toEditEntry(obj);
+	if (top) edits.push(top);
+
+	return { path, edits };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "pi-tian-edit-safe",
+  "version": "0.1.0",
+  "description": "A stricter edit tool for the pi coding agent: full-span match verification, throw-on-ambiguity, verbatim replacement, and a weak-model-friendly call shape.",
+  "type": "module",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "edit-tool"
+  ],
+  "author": "Tian Zuo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TianZuo555/pi-tian-extensions.git",
+    "directory": "packages/pi-edit-safe"
+  },
+  "homepage": "https://github.com/TianZuo555/pi-tian-extensions#pi-edit-safe",
+  "bugs": {
+    "url": "https://github.com/TianZuo555/pi-tian-extensions/issues"
+  },
+  "files": [
+    "index.ts",
+    "lib",
+    "NOTICES.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "bench": "node --experimental-strip-types bench/ab.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}