@khanhicetea/pi-better-tool 0.2.1 → 0.2.2

package/README.md

@@ -1,20 +1,16 @@
 # pi-better-tool
 
-Better built-in tools for the [pi coding agent](https://github.com/earendil-works/pi-mono) — starting with an `edit` override that turns failed edits into recoverable ones.
+Better built-in tools for the [pi coding agent](https://github.com/earendil-works/pi-mono) — starting with an `edit` override that turns many failed edits into recoverable ones.
 
 ## Why
 
-The built-in `edit` tool requires `edits[].oldText` to match **exactly and uniquely**. When it doesn't, the tool fails with a bare error:
+Pi's built-in `edit` requires every `edits[].oldText` to identify one non-overlapping region. When matching fails, this override returns bounded context that can make the next action safer:
 
-```
-Could not find edits[1] in /code/app.go. The oldText must match exactly including all whitespace and newlines.
-```
+- **Ambiguous literal match after a bounded read** — selects an occurrence only when exactly one tracked literal occurrence is fully contained in the newest verified stored-context `read` of the same file.
+- **Other ambiguous matches** — reports bounded occurrence ranges and whole-line prefix/suffix expansions that are unique under edit matching.
+- **Text not found** — reports a bounded closest-region comparison. It gives direct-retry wording only when the exact candidate is unique, sufficiently similar, and meaningfully better than a distinct runner-up.
 
-That failure wastes a whole loop: the model has to `read` the file again, guess a larger context, and retry — sometimes failing again. `pi-better-tool` resolves only ambiguity supported by verified evidence and otherwise returns **recovery context** so the next call succeeds without re-reading:
-
-- **Ambiguous literal match after a bounded read** — when exactly one occurrence was fully visible in the latest successful, byte-verified `read` of the same file, edit selects that occurrence. Its success message reports the selected/read ranges and up to four remaining occurrences with effective prefix/suffix context and retryable snippets.
-- **Other ambiguous matches (2+ occurrences)** — bounded occurrence line numbers plus the **minimum prefix/suffix context** that makes the first few occurrences unique, rendered as ready-to-use `oldText` snippets when they fit safely.
-- **Text not found** — the closest matching region (fuzzy line similarity), a line-by-line comparison against your `oldText`, the exact file bytes to retry with, and likely causes (tabs vs spaces, indentation, case).
+Low-confidence, competing, stale, oversized, or omitted candidates tell the model to read the referenced range instead of retrying blindly.
 
 ## Install
 
@@ -32,14 +28,14 @@ It is also registered in the root `package.json` under `pi.extensions`.
 
 ## Example: ambiguous oldText
 
-```text
+````text
 Found 2 occurrences of the text in dup.go. The text must be unique. Please provide more context to make it unique.
 
 Occurrences:
   1. lines 2-3
   2. lines 6-7
 
-Retry with a disambiguated oldText: pick ONE occurrence below and reuse its snippet exactly. Each snippet already includes the minimum surrounding context that makes it unique:
+Disambiguated oldText candidates are shown below when they fit safely. A fenced snippet can be reused exactly; an omitted snippet must be read from its referenced range first:
 
 Occurrence 1 (lines 2-3) — minimum context: 0 lines before, 1 line after:
 ```
@@ -49,54 +45,82 @@ Occurrence 1 (lines 2-3) — minimum context: 0 lines before, 1 line after:
 func second() {
 ```
 
-Occurrence 2 (lines 6-7) — minimum context: 0 lines before, 0 lines after:
+Tip: only fenced snippets explicitly presented as retryable should be copied into oldText.
+
+No changes were written — the file was not modified.
+````
+
+## Example: competing closest matches
+
+````text
+Could not find the exact text in handlers.ts. The old text must match exactly including all whitespace and newlines.
+
+Closest match in the file: lines 10-12 (~91% line similarity).
+...
+Candidate file content at lines 10-12 is not safe for a direct retry (a distinct candidate at lines 30-32 has a similar heuristic score (~90%)). Read and verify this range before editing.
 ```
-	log()
+function firstHandler() {
+	work();
 }
 ```
 
-Tip: use the snippet byte-for-byte as the new oldText, and make newText the snippet with your change applied (the snippet may span whole lines).
-
 No changes were written — the file was not modified.
-```
+````
 
-## Example: text not found
+Similarity scores are heuristics, not probabilities.
 
-```text
-Could not find the exact text in tabs.go. The old text must match exactly including all whitespace and newlines.
+## Behavior and compatibility
 
-Closest match in the file: lines 3-5 (~91% line similarity).
-Differences vs your oldText (2 of 3 compared lines match):
-  file line 4 differs from your oldText line 2:
-    file:     →tab→fmt.Println("hi")
-    oldText:      fmt.Println("hi")
+The normal matching path follows Pi's built-in edit implementation:
 
-Exact file content at lines 3-5 — retry using this text as oldText (then apply your change to newText):
-```
-func main() {
-	fmt.Println("hi")
-}
-```
+- exact match first, then fuzzy fallback for trailing whitespace, smart quotes, dashes, Unicode compatibility forms, and Unicode spaces
+- uniqueness checked in fuzzy-normalized space
+- all edits matched against the original content rather than applied incrementally
+- overlap and no-change detection
+- CRLF restoration and UTF-8 BOM preservation
+- built-in-compatible success details (`details.diff`, `details.patch`, and `details.firstChangedLine`)
+- no custom renderers, so Pi's built-in edit renderer is inherited
 
-Possible cause:
-- whitespace mismatch: the text matches when ALL whitespace is removed — check tabs vs spaces and indentation width
+Intentional safety/compatibility differences are:
 
-No changes were written — the file was not modified.
-```
+- 1–100 edits are accepted per call; empty batches are rejected by the public schema
+- empty and fuzzy-normalized-empty `oldText` values are rejected
+- invalid UTF-8 and NUL-containing files are rejected rather than silently transcoded
+- conservative stored-read-based selection may resolve repeated literal text
+- self-overlapping string occurrences retain Pi's non-overlapping counting policy
+
+The argument compatibility shim accepts `edits` as an array, JSON string, single edit object, or legacy top-level `oldText`/`newText`. Preparation is pure and idempotent.
+
+### Read-evidence boundary
+
+Read evidence is taken from Pi's active, compaction-aware **stored session context**. Retained-tail messages are handled when the host exposes them. The newest same-file read must have a matching successful result and reproduce built-in read formatting for the current LF-normalized content. Missing, failed, malformed, or stale newest evidence blocks fallback to older intent.
+
+This is not proof of the final provider payload: another extension may remove messages in a `context` hook or rewrite the provider request. CRLF read output is intentionally compared after LF normalization, so this guarantee is content/format verification rather than literal byte identity. BOM-bearing read output is conservatively rejected because edit matching strips the BOM. Fuzzy/Unicode-equivalent ambiguity and highly repetitive files also fail closed.
+
+### Local filesystem and commit guarantees
 
-## Behavior
+This override uses local Node.js filesystem operations. It does **not** inherit an SSH, container, sandbox, or other custom edit backend.
 
-Normal unique-match semantics are **identical** to the built-in `edit` tool. The one intentional extension is conservative read-based selection for repeated literal text:
+All replacements are analyzed before writing, so a matching/overlap/no-change/diagnostic failure starts no write. Immediately before writing, the tool performs a best-effort content and file-identity recheck to catch many external modifications.
 
-- same schema (`path` + `edits[{oldText,newText}]`), including the compatibility shim for models that send `edits` as a JSON string, a single edit object, or legacy top-level `oldText`/`newText`
-- same matching engine ported from pi's `edit-diff.ts`: exact match first, fuzzy fallback (trailing whitespace, smart quotes, dashes, unicode spaces), uniqueness checked in fuzzy-normalized space, all edits matched against the original content, overlap/empty/no-change detection
-- same BOM and CRLF handling
-- same success result shape (`details.diff` / `details.patch` / `details.firstChangedLine`), and no custom renderers — the built-in diff renderer is inherited
-- read-based selection fails closed unless the newest same-file read is still in active context, its stored output exactly matches the current bytes and built-in read formatting, and exactly one complete literal occurrence lies inside the visible range; fuzzy/Unicode-equivalent ambiguity, same-line ambiguity, stale reads, and broad reads containing multiple occurrences still refuse
+The final write is still an in-place filesystem overwrite:
 
-Failure behavior is the other difference: errors carry the recovery context described above, and nothing is written on failure (edits remain atomic).
+- it is not a cross-process lock or race-free compare-and-swap
+- it is not rollback- or crash-safe filesystem atomicity
+- another process can modify the file after the pre-write check
+- a rejected write may leave the file unchanged, partially written, or fully written; inspect it before retrying
 
-Diagnostics degrade gracefully: files over ~2 MB skip the analysis and return the plain built-in-style error; repeated blocks that cannot be disambiguated within 12 context lines get a guidance note instead of snippets. Complete diagnostic output is bounded below pi's 50 KB / 2,000-line tool-output limit. Oversized exact snippets are omitted with a line range instead of being presented as copyable text, and low-confidence or non-unique closest matches require verification before retrying.
+A resolved write is the tool's commit boundary. The extension returns the committed result rather than throwing a post-write cancellation error. A host may still suppress result delivery when cancelling the surrounding tool run; cancellation cannot roll back a completed filesystem write. Temporary-file/rename replacement is deliberately not used because it can replace symlinks, break hard-link semantics, or alter metadata without a carefully defined cross-platform policy.
+
+### Output and resource bounds
+
+Diagnostic text is kept below Pi's 50 KB / 2,000-line tool-output limits. Markdown snippets are added atomically so a fence is never cut; oversized snippets are omitted with read guidance. Success expansion is skipped for oversized files. Closest-match work has explicit query, line, and operation budgets and falls back to concise read guidance when exhausted.
+
+`details.diff` and `details.patch` remain complete for renderer compatibility and are not blindly truncated as diagnostic text.
+
+## Host compatibility
+
+Pi's packaging guidance requires wildcard peer dependencies for Pi core packages. This package follows that guidance rather than bundling Pi. Version 0.2.1 is typechecked and tested against `@earendil-works/pi-coding-agent` 0.82.1; host upgrades should run the read-format, exported-helper, renderer-shape, and session-context compatibility tests.
 
 ## Development
 
@@ -107,7 +131,7 @@ npm test          # vitest only
 
 ## Publishing
 
-From the repository root, verify the package and inspect its tarball before publishing:
+From the repository root:
 
 ```bash
 npm run check --workspace=@khanhicetea/pi-better-tool
@@ -115,8 +139,6 @@ npm pack --dry-run --workspace=@khanhicetea/pi-better-tool
 npm publish --workspace=@khanhicetea/pi-better-tool
 ```
 
-The package is configured for public publishing under the `@khanhicetea` scope. npm authentication is required.
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@khanhicetea/pi-better-tool",
-	"version": "0.2.1",
+	"version": "0.2.2",
 	"description": "Better built-in tools for pi: an edit tool override that returns recovery context (closest match + disambiguation snippets) instead of bare failures",
 	"type": "module",
 	"license": "MIT",

package/src/apply.ts

@@ -1,12 +1,12 @@
 /**
  * Edit matching and application engine.
  *
- * A port of pi's built-in `applyEditsToNormalizedContent` with one key
- * difference: instead of throwing opaque errors, `analyzeEdits` returns a
- * structured failure describing *why* an edit failed, which the diagnostics
- * layer turns into actionable recovery context for the model.
+ * A port of pi's built-in `applyEditsToNormalizedContent`. Instead of throwing
+ * opaque errors, `analyzeEdits` returns a structured failure describing *why*
+ * an edit failed. It also rejects fuzzy-normalized-empty needles and can accept
+ * a conservatively verified literal selection as intentional safety extensions.
  *
- * Matching semantics are kept identical to the built-in tool:
+ * Otherwise matching semantics follow the built-in tool:
  * - exact match first, then fuzzy-normalized fallback (trailing whitespace,
  *   smart quotes, dashes, unicode spaces)
  * - uniqueness is always checked in fully fuzzy-normalized space
@@ -18,10 +18,11 @@ import {
 	countFuzzyOccurrences,
 	findAllOccurrences,
 	getLineSpans,
+	getLogicalLineSpans,
 	lineAt,
 	normalizeForFuzzyMatch,
 	normalizeToLF,
-	splitLinesWithEndings,
+	splitLogicalLinesWithEndings,
 	type LineSpan,
 } from "./text.ts";
 
@@ -42,7 +43,9 @@ export type EditFailure =
 	| {
 			kind: "ambiguous";
 			editIndex: number;
-			/** Offsets of every occurrence, enumerated in fully fuzzy-normalized space. */
+			/** Total non-overlapping occurrences in fully fuzzy-normalized space. */
+			occurrenceCount: number;
+			/** A bounded prefix of occurrence offsets for diagnostics/selection. */
 			occurrenceOffsets: number[];
 	  }
 	| {
@@ -85,6 +88,9 @@ export interface AnalyzeOptions {
 	ambiguousSelections?: ReadonlyMap<number, number>;
 }
 
+/** Avoid materializing unbounded offset arrays for highly repetitive files. */
+const MAX_TRACKED_OCCURRENCE_OFFSETS = 256;
+
 export function normalizeEdits(edits: EditOp[]): EditOp[] {
 	return edits.map((edit) => ({
 		oldText: normalizeToLF(edit.oldText),
@@ -159,7 +165,11 @@ export function analyzeEdits(normalizedContent: string, rawEdits: EditOp[], opti
 		const occurrences = countFuzzyOccurrences(fuzzyBase, edit.oldText);
 		let selectedMatch = matchResult;
 		if (occurrences > 1) {
-			const occurrenceOffsets = findAllOccurrences(fuzzyBase, normalizeForFuzzyMatch(edit.oldText));
+			const occurrenceOffsets = findAllOccurrences(
+				fuzzyBase,
+				normalizeForFuzzyMatch(edit.oldText),
+				MAX_TRACKED_OCCURRENCE_OFFSETS,
+			);
 			const selectedOffset = options.ambiguousSelections?.get(i);
 			if (
 				selectedOffset === undefined ||
@@ -167,7 +177,7 @@ export function analyzeEdits(normalizedContent: string, rawEdits: EditOp[], opti
 			) {
 				return {
 					ok: false,
-					failure: { kind: "ambiguous", editIndex: i, occurrenceOffsets },
+					failure: { kind: "ambiguous", editIndex: i, occurrenceCount: occurrences, occurrenceOffsets },
 				};
 			}
 			selectedMatch = {
@@ -257,10 +267,10 @@ function applyReplacementsPreservingUnchangedLines(
 	baseContent: string,
 	replacements: Replacement[],
 ): string {
-	const originalLines = splitLinesWithEndings(originalContent);
-	const baseLines = getLineSpans(baseContent);
+	const originalLines = splitLogicalLinesWithEndings(originalContent);
+	const baseLines = getLogicalLineSpans(baseContent);
 	if (originalLines.length !== baseLines.length) {
-		throw new Error("Cannot preserve unchanged lines because the base content has a different line count.");
+		throw new Error("Cannot preserve unchanged lines because the base content has a different logical line count.");
 	}
 
 	const groups: Array<InternalLineWindow & { replacements: Replacement[] }> = [];

package/src/diagnostics.ts

@@ -8,10 +8,9 @@
  *   prefix/suffix context expansion that makes that occurrence unique,
  *   rendered as a ready-to-use oldText snippet
  * - not-found oldText  → the closest matching region (fuzzy line similarity),
- *   a per-line comparison, and the exact file bytes to retry with
+ *   an original-text comparison, and exact LF-normalized retry text when safe
  */
 
-import { formatSize, truncateHead } from "@earendil-works/pi-coding-agent";
 import type { EditFailure, EditOp, LineRange } from "./apply.ts";
 import { normalizeEdits } from "./apply.ts";
 import { findClosestRegion, lineSimilarity, probeMatchCauses } from "./similarity.ts";
@@ -41,6 +40,8 @@ const MAX_OUTPUT_LINES = 1_500;
 const MAX_OUTPUT_BYTES = 48 * 1024;
 /** Minimum score at which a unique closest region may be suggested directly. */
 const MIN_DIRECT_RETRY_SCORE = 0.75;
+/** Required separation from a distinct runner-up before direct-retry wording. */
+const MIN_DIRECT_RETRY_GAP = 0.1;
 /** Max non-equal alignment ops rendered. */
 const MAX_DIFF_OPS_SHOWN = 12;
 
@@ -81,22 +82,32 @@ export function formatAutoDisambiguationSuccess(
 	newContent: string,
 	resolutions: AutoDisambiguation[],
 ): string {
-	if (resolutions.length === 0) return baseMessage;
+	if (resolutions.length === 0) return boundCompleteOutput(baseMessage);
 	const lines = [baseMessage, ""];
 	const shownResolutions = resolutions.slice(0, MAX_SUCCESS_RESOLUTIONS);
+	if (newContent.length > MAX_CONTENT_FOR_DIAGNOSTICS) {
+		for (const resolution of shownResolutions) {
+			lines.push(
+				`Auto-disambiguated edits[${resolution.editIndex}] to ${describeLines(resolution.chosenRange.start, resolution.chosenRange.end)} because it was the only occurrence fully contained in the latest verified read of ${describeLines(resolution.readRange.start, resolution.readRange.end)}.`,
+			);
+		}
+		lines.push("Remaining-occurrence snippets were omitted because the edited file exceeds the diagnostic analysis limit.");
+		return boundCompleteOutput(lines.join("\n"));
+	}
 
 	for (const resolution of shownResolutions) {
 		lines.push(
 			`Auto-disambiguated edits[${resolution.editIndex}] to ${describeLines(resolution.chosenRange.start, resolution.chosenRange.end)} because it was the only occurrence fully contained in the latest verified read of ${describeLines(resolution.readRange.start, resolution.readRange.end)}.`,
 		);
 		const oldText = normalizeToLF(resolution.oldText);
-		const offsets = findAllOccurrences(newContent, oldText);
-		if (offsets.length === 0) {
+		const remainingCount = countLiteralOccurrences(newContent, oldText);
+		const offsets = findAllOccurrences(newContent, oldText, MAX_REMAINING_OCCURRENCES);
+		if (remainingCount === 0) {
 			lines.push("No exact occurrences of the original oldText remain after this edit.", "");
 			continue;
 		}
 
-		lines.push(`Remaining exact occurrences of the original oldText (${Math.min(offsets.length, MAX_REMAINING_OCCURRENCES)} shown${offsets.length > MAX_REMAINING_OCCURRENCES ? `, ${offsets.length - MAX_REMAINING_OCCURRENCES} more omitted` : ""}):`);
+		lines.push(`Remaining exact occurrences of the original oldText (${offsets.length} shown${remainingCount > offsets.length ? `, ${remainingCount - offsets.length} more omitted` : ""}):`);
 		const fuzzyContent = normalizeForFuzzyMatch(newContent);
 		const spans = getLineSpans(newContent);
 		for (const [index, offset] of offsets.slice(0, MAX_REMAINING_OCCURRENCES).entries()) {
@@ -119,14 +130,11 @@ export function formatAutoDisambiguationSuccess(
 	if (resolutions.length > shownResolutions.length) {
 		lines.push(`${resolutions.length - shownResolutions.length} more auto-disambiguated edits were applied; details omitted.`);
 	}
-	return lines.join("\n").trimEnd();
+	return boundCompleteOutput(lines.join("\n").trimEnd());
 }
 
 export function formatEditFailure(opts: FormatFailureOptions): string {
-	const message = formatEditFailureUnbounded(opts);
-	const bounded = truncateHead(message, { maxBytes: MAX_OUTPUT_BYTES, maxLines: MAX_OUTPUT_LINES });
-	if (!bounded.truncated) return message;
-	return `${bounded.content}\n\n[Diagnostic output truncated to ${formatSize(bounded.outputBytes)} / ${bounded.outputLines} lines. Any incomplete snippet is not retryable; read the referenced range first.]`;
+	return boundCompleteOutput(formatEditFailureUnbounded(opts));
 }
 
 function formatEditFailureUnbounded(opts: FormatFailureOptions): string {
@@ -156,8 +164,8 @@ function formatEditFailureUnbounded(opts: FormatFailureOptions): string {
 		case "ambiguous": {
 			const head =
 				total === 1
-					? `Found ${failure.occurrenceOffsets.length} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`
-					: `Found ${failure.occurrenceOffsets.length} occurrences of edits[${failure.editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`;
+					? `Found ${failure.occurrenceCount} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`
+					: `Found ${failure.occurrenceCount} occurrences of edits[${failure.editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`;
 			const body =
 				normalizedContent.length <= MAX_CONTENT_FOR_DIAGNOSTICS
 					? formatAmbiguous(opts, failure)
@@ -197,8 +205,8 @@ function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailur
 		const range = rangeFromOffset(fuzzySpans, offset, fuzzyOld.length);
 		lines.push(`  ${i + 1}. ${describeLines(range.start, range.end)}`);
 	});
-	if (failure.occurrenceOffsets.length > listed.length) {
-		lines.push(`  … and ${failure.occurrenceOffsets.length - listed.length} more`);
+	if (failure.occurrenceCount > listed.length) {
+		lines.push(`  … and ${failure.occurrenceCount - listed.length} more`);
 	}
 	lines.push("");
 
@@ -259,6 +267,17 @@ function plural(n: number, noun: string): string {
 	return `${n} ${noun}${n === 1 ? "" : "s"}`;
 }
 
+function countLiteralOccurrences(haystack: string, needle: string): number {
+	if (!needle) return 0;
+	let count = 0;
+	let index = haystack.indexOf(needle);
+	while (index !== -1) {
+		count++;
+		index = haystack.indexOf(needle, index + needle.length);
+	}
+	return count;
+}
+
 /**
  * Find the smallest whole-line context expansion of the occurrence at `range`
  * whose text occurs exactly once in the file (checked in fuzzy space, exactly
@@ -353,9 +372,9 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 				);
 			}
 		} else {
-			lines.push(`Differences vs your oldText (${closest.equalCount} of ${closest.totalOldLines} compared lines match):`);
+			lines.push(`Differences vs your oldText (${closest.equalCount} of ${closest.totalOldLines} compared lines match exactly):`);
 			for (const op of diffOps.slice(0, MAX_DIFF_OPS_SHOWN)) {
-				if (op.type === "changed") {
+				if (op.type === "changed" || op.type === "similar") {
 					lines.push(`  file line ${op.fileLine} differs from your oldText line ${op.oldLine}:`);
 					lines.push(`    file:     ${truncateLine(op.fileText ?? "")}`);
 					lines.push(`    oldText:  ${truncateLine(op.oldText ?? "")}`);
@@ -375,9 +394,12 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 		const candidate = textFromLines(normalizedContent, closest.startLine, closest.endLine);
 		const uniqueCandidate = verifyUniqueSnippet(normalizeForFuzzyMatch(normalizedContent), candidate);
 		const safelyRenderable = isSnippetRenderable(uniqueCandidate ?? candidate);
+		const competitorGap = closest.competitor ? closest.score - closest.competitor.score : Number.POSITIVE_INFINITY;
 		const directRetry =
 			!closest.truncated &&
 			closest.score >= MIN_DIRECT_RETRY_SCORE &&
+			!closest.competitionIncomplete &&
+			competitorGap >= MIN_DIRECT_RETRY_GAP &&
 			uniqueCandidate !== null &&
 			safelyRenderable;
 		if (directRetry) {
@@ -389,6 +411,10 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 			const reasons = [
 				closest.truncated ? "only part of oldText was compared" : undefined,
 				closest.score < MIN_DIRECT_RETRY_SCORE ? "similarity confidence is too low" : undefined,
+				closest.competitionIncomplete ? "the bounded search discarded another competitively scored window" : undefined,
+				competitorGap < MIN_DIRECT_RETRY_GAP && closest.competitor
+					? `a distinct candidate at ${describeLines(closest.competitor.startLine, closest.competitor.endLine)} has a similar heuristic score (~${Math.round(closest.competitor.score * 100)}%)`
+					: undefined,
 				uniqueCandidate === null ? "the candidate is not unique under edit matching" : undefined,
 				!safelyRenderable ? "the exact candidate exceeds the safe output limit" : undefined,
 			].filter((reason): reason is string => reason !== undefined);
@@ -412,8 +438,85 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 }
 
 function truncateLine(line: string): string {
-	const collapsed = line.replace(/\t/g, "→tab→");
-	return collapsed.length > 120 ? `${collapsed.slice(0, 117)}…` : collapsed;
+	const visibleTrailing = line.replace(/[ \t]+$/, (suffix) =>
+		[...suffix].map((char) => (char === "\t" ? "→tab→" : "·")).join(""),
+	);
+	const visible = visibleTrailing.replace(/\t/g, "→tab→");
+	return visible.length > 120 ? `${visible.slice(0, 117)}…` : visible;
+}
+
+/**
+ * Enforce the complete output budget without ever cutting a generated fenced
+ * snippet. Oversized snippets are omitted atomically and clearly marked.
+ */
+function boundCompleteOutput(message: string): string {
+	const source = message.split("\n");
+	const output: string[] = [];
+	let bytes = 0;
+	let omitted = false;
+	const reservedBytes = 512;
+	const maxBodyBytes = MAX_OUTPUT_BYTES - reservedBytes;
+	const maxBodyLines = MAX_OUTPUT_LINES - 3;
+
+	const canAdd = (block: string[]) => {
+		const text = block.join("\n");
+		const addedBytes = Buffer.byteLength(text, "utf8") + (output.length > 0 ? 1 : 0);
+		return output.length + block.length <= maxBodyLines && bytes + addedBytes <= maxBodyBytes;
+	};
+	const add = (block: string[]) => {
+		const text = block.join("\n");
+		bytes += Buffer.byteLength(text, "utf8") + (output.length > 0 ? 1 : 0);
+		output.push(...block);
+	};
+
+	for (let index = 0; index < source.length; index++) {
+		const opener = source[index];
+		if (/^`{3,}$/.test(opener)) {
+			let closing = index + 1;
+			while (closing < source.length && source[closing] !== opener) closing++;
+			if (closing < source.length) {
+				const block = source.slice(index, closing + 1);
+				if (canAdd(block)) add(block);
+				else {
+					omitted = true;
+					const notice = ["[Exact fenced snippet omitted to keep the complete tool output within its byte/line budget.]" ];
+					if (canAdd(notice)) add(notice);
+				}
+				index = closing;
+				continue;
+			}
+		}
+
+		if (canAdd([opener])) {
+			add([opener]);
+			continue;
+		}
+		omitted = true;
+		const available = Math.max(0, maxBodyBytes - bytes - (output.length > 0 ? 1 : 0));
+		if (available > 4 && output.length < maxBodyLines) add([truncateUtf8(opener, available)]);
+		break;
+	}
+
+	if (omitted) {
+		const notice = "[Diagnostic output was bounded. Omitted fenced snippets are not retryable; read the referenced range first.]";
+		if (output.length > 0) output.push("");
+		output.push(notice);
+	}
+	return output.join("\n").trimEnd();
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+	const suffix = "…";
+	const target = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
+	let low = 0;
+	let high = text.length;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if (Buffer.byteLength(text.slice(0, middle), "utf8") <= target) low = middle;
+		else high = middle - 1;
+	}
+	return `${text.slice(0, low)}${suffix}`;
 }
 
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -11,7 +11,12 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerBetterEditTool } from "./tool.ts";
 
 export { registerBetterEditTool, executeBetterEdit, prepareEditArguments, betterEditSchema } from "./tool.ts";
-export type { BetterEditInput } from "./tool.ts";
+export type {
+	BetterEditExecutionOptions,
+	BetterEditInput,
+	BetterEditOperations,
+	BetterEditSuccess,
+} from "./tool.ts";
 export {
 	formatAutoDisambiguationSuccess,
 	formatEditFailure,