pi-hashline-edit-pro 4.5.2 → 5.0.0

package/src/hashline/resolve.ts

@@ -1,8 +1,8 @@
 import { abortIf, rejectUnknownFields, clipLine, decodeStringArray, assertNoNul } from "../utils";
-import { parseHashRef, parseTextWithSeparators, type Anchor } from "./parse";
+import { parseHashRef, parsePayloadText, parseTextWithSeparators, type Anchor, type ParsedText } from "./parse";
 import { HASH_SEP, stripRowPrefix, lineChecksum, type RowPrefixKind } from "./hash";
 import { HASH_RUN } from "./alphabet";
-import { NEW_CONTENT_NOT_ARRAY_MSG, MAX_RANGE_STALE_LINES } from "../constants";
+import { NEW_CONTENT_NOT_ARRAY_MSG, NEW_CONTENT_NOT_STRING_MSG, MAX_RANGE_STALE_LINES } from "../constants";
 import type { LineEnding } from "../normalize";
 
 export type RAnchor = {
@@ -18,6 +18,7 @@ export type HEdit = {
 export type RHEdit = {
   content_lines: string[];
   hash_bounds: [RAnchor, RAnchor];
+  content_separators?: (LineEnding | undefined)[];
 };
 
 interface HMismatch {
@@ -37,6 +38,12 @@ export type HTEdit = {
   remove_to: string;
 };
 
+export type HTPayloadEdit = {
+  replacement_lines: string;
+  remove_from: string;
+  remove_to: string;
+};
+
 function resAnchorFromMap(
 	ref: Anchor,
 	hashIndex: Map<string, number[]>,
@@ -115,30 +122,57 @@ export function fmtMismatchWithHashes(
 
 const ITEM_KS = new Set(["replacement_lines", "remove_from", "remove_to"]);
 
+function assertBounds(edit: Record<string, unknown>): void {
+	if ("remove_from" in edit && typeof edit.remove_from !== "string") {
+		throw new Error(
+			`[E_BAD_SHAPE] Field "remove_from" must be an anchor string (4-char anchor).`,
+		);
+	}
+	if ("remove_to" in edit && typeof edit.remove_to !== "string") {
+		throw new Error(
+			`[E_BAD_SHAPE] Field "remove_to" must be an anchor string (4-char anchor).`,
+		);
+	}
+	if (typeof edit.remove_from !== "string" || typeof edit.remove_to !== "string") {
+		throw new Error(
+			`[E_BAD_SHAPE] The edit requires "remove_from" and "remove_to" anchor strings (4-char anchors from read output).`,
+		);
+	}
+}
+
 function assertItem(edit: Record<string, unknown>): void {
-  rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { replacement_lines, remove_from, remove_to }.");
+	rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { replacement_lines, remove_from, remove_to }.");
+	assertBounds(edit);
+	if (!("replacement_lines" in edit)) {
+		throw new Error(`[E_BAD_SHAPE] The edit requires a "replacement_lines" array (use [] to delete).`);
+	}
+	if (!Array.isArray(edit.replacement_lines) || edit.replacement_lines.some((line) => typeof line !== "string")) {
+		throw new Error(NEW_CONTENT_NOT_ARRAY_MSG);
+	}
+}
 
-  if ("remove_from" in edit && typeof edit.remove_from !== "string") {
-    throw new Error(
-      `[E_BAD_SHAPE] Field "remove_from" must be an anchor string (4-char anchor).`,
-    );
-  }
-  if ("remove_to" in edit && typeof edit.remove_to !== "string") {
-    throw new Error(
-      `[E_BAD_SHAPE] Field "remove_to" must be an anchor string (4-char anchor).`,
-    );
-  }
-  if (!("replacement_lines" in edit)) {
-    throw new Error(`[E_BAD_SHAPE] The edit requires a "replacement_lines" array (use [] to delete).`);
-  }
-  if (!Array.isArray(edit.replacement_lines) || edit.replacement_lines.some((line) => typeof line !== "string")) {
-    throw new Error(NEW_CONTENT_NOT_ARRAY_MSG);
-  }
-  if (typeof edit.remove_from !== "string" || typeof edit.remove_to !== "string") {
-    throw new Error(
-      `[E_BAD_SHAPE] The edit requires "remove_from" and "remove_to" anchor strings (4-char anchors from read output).`,
-    );
-  }
+function assertPayloadItem(edit: Record<string, unknown>): void {
+	rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { replacement_lines, remove_from, remove_to }.");
+	assertBounds(edit);
+	if (!("replacement_lines" in edit)) {
+		throw new Error(`[E_BAD_SHAPE] The edit requires a "replacement_lines" string (use "" to delete).`);
+	}
+	if (typeof edit.replacement_lines !== "string") {
+		throw new Error(NEW_CONTENT_NOT_STRING_MSG);
+	}
+}
+
+function resolveParsedEdit(removeFrom: string, removeTo: string, parsed: ParsedText, warnings?: string[]): HEdit {
+	const replaceLines = parsed.lines;
+	assertNoNul(replaceLines);
+	const bounds = [removeFrom, removeTo].map((ref) => {
+		return stripAnchorRow(ref.trim(), "remove_from/remove_to entry", warnings);
+	}) as [string, string];
+	return {
+		content_lines: replaceLines,
+		hash_bounds: [parseHashRef(bounds[0]), parseHashRef(bounds[1])],
+		...(parsed.separators.some((separator) => separator !== undefined) ? { content_separators: parsed.separators } : {}),
+	};
 }
 
 export const ANCHOR_ROW_RE = new RegExp(`^([+-]?)(${HASH_RUN})│`);
@@ -160,20 +194,14 @@ export function stripAnchorRow(
 	return match[2]!;
 }
 
-export function resEdit(edit: HTEdit, warnings?: string[]): HEdit {
-  assertItem(edit as Record<string, unknown>);
-
-  const parsed = parseTextWithSeparators(decodeStringArray(edit.replacement_lines, warnings) ?? edit.replacement_lines);
-  const replaceLines = parsed.lines;
-  assertNoNul(replaceLines);
-  const bounds = [edit.remove_from, edit.remove_to].map((ref) => {
-    return stripAnchorRow(ref.trim(), "remove_from/remove_to entry", warnings);
-  }) as [string, string];
-  return {
-    content_lines: replaceLines,
-    hash_bounds: [parseHashRef(bounds[0]), parseHashRef(bounds[1])],
-    ...(parsed.separators.some((separator) => separator !== undefined) ? { content_separators: parsed.separators } : {}),
-  };
+export function resEdit(edit: HTEdit | HTPayloadEdit, warnings?: string[]): HEdit {
+	if (typeof edit.replacement_lines === "string") {
+		assertPayloadItem(edit as unknown as Record<string, unknown>);
+		return resolveParsedEdit(edit.remove_from, edit.remove_to, parsePayloadText(edit.replacement_lines), warnings);
+	}
+	assertItem(edit as Record<string, unknown>);
+	const parsed = parseTextWithSeparators(decodeStringArray(edit.replacement_lines, warnings) ?? edit.replacement_lines);
+	return resolveParsedEdit(edit.remove_from, edit.remove_to, parsed, warnings);
 }
 
 function warnUnicodeEsc(
@@ -288,6 +316,7 @@ export function valEdit(
 		resolved: {
 			content_lines: edit.content_lines,
 			hash_bounds: [startResolved, endResolved],
+			...(edit.content_separators !== undefined ? { content_separators: edit.content_separators } : {}),
 		},
 		mismatches,
 	};

package/src/insert.ts

@@ -1,43 +1,38 @@
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { constants } from "node:fs";
-import { execPipeline, type ReqParams, type ReplaceDetails, previewFromPipe, previewError } from "./replace";
+import { execPipeline, type ReplaceDetails, previewFromPipe, previewError } from "./replace";
 import { commitEdit } from "./commit";
 import { batchMemberFor, ensureBatchBase, executeBatchMember, noteBatchFailure } from "./batch";
 import { readNormFile, type NormFile } from "./file-reader";
-import { MAX_HASH_LINES, parseHashRef, parseTextWithSeparators, resEdit, resolveAnchorLine, type Anchor, type HEdit, type StripWarningLocation } from "./hashline";
+import { MAX_HASH_LINES, parseHashRef, parsePayloadText, resEdit, resolveAnchorLine, type Anchor, type HEdit, type HTEdit, type StripWarningLocation } from "./hashline";
 import type { LineEnding } from "./normalize";
 import { stripAnchorRow } from "./hashline/resolve";
 import { withAnchorSession } from "./anchor-registry";
 import { loadP, loadGuide } from "./prompts";
 import { assertInsertReq, normReq, type InsertReq } from "./payload-contract";
-import { decodeStringArray, isRec, literalEscapeHint, splitLines } from "./utils";
+import { isRec, literalEscapeHint, splitLines } from "./utils";
 import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper, resolveEditTargetWithRequirement, throwIfStrictInput, withInsertPrompts, DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-common";
 import type { RPreview, RRState } from "./replace-render";
 export { assertInsertReq, type InsertReq };
 
 const insertAnchorSchema = Type.String({
   description:
-    'Bare 4-char anchor from a served anchor│content row (the text before the `│` separator), never the row content. A pasted diff row or `anchor│` prefix is stripped with a warning. The anchor line is preserved; lines go after or before it.',
+    "4-char anchor of the line to insert next to (never the row content). A pasted diff row is stripped with a warning; the anchor line is preserved.",
 });
 
 const insertDirectionSchema = Type.Union(
   [Type.Literal("after"), Type.Literal("before")],
   { description: '"after" or "before"' },
 );
-
-const insertLinesSchema = Type.Array(
-  Type.String({
-    description: "One line to insert. A real line break (\\n, \\r\\n, or \\r) splits it into lines and sets their endings.",
-  }),
-  {
-    description: 'One string per line; [""] is a blank line; never include the anchor line.',
-  }
-);
+const insertLinesSchema = Type.String({
+  description:
+    'The exact text to insert. "" inserts nothing, "\\n" is one blank line, and a trailing line break sets the last line\'s ending instead of adding a blank line. Never include the anchor line.',
+});
 
 const insertPathRequiredSchema = Type.String({
   description:
-    "Path to the file the anchor was served for; required and must match anchor ownership. The anchor still resolves the target.",
+    "Path to the file the anchor was served for; required and must match anchor ownership.",
 });
 
 const insertToolSchema = Type.Object(
@@ -74,12 +69,12 @@ export function buildInsertEdit(
   preload: NormFile,
   ref: Anchor,
   path: string,
-): { editParams: ReqParams; anchorLine: string | undefined; contentSeparators: (LineEnding | undefined)[] } {
-  const parsed = parseTextWithSeparators(req.lines);
+): { editParams: HTEdit; anchorLine: string | undefined; contentSeparators: (LineEnding | undefined)[] } {
+  const parsed = parsePayloadText(req.lines);
   const fileLines = splitLines(preload.normalized);
   const line = resolveAnchorLine(ref, fileLines, preload.fileHashes, path);
   const anchorLine = preload.normalized.length === 0 ? undefined : fileLines[line - 1];
-  const editParams: ReqParams = {
+  const editParams: HTEdit = {
     remove_from: ref.hash,
     remove_to: ref.hash,
     replacement_lines:
@@ -104,15 +99,10 @@ function insertStripWarning(anchorLine: string | undefined, direction: "before"
 export async function insertPreview(request: unknown, cwd: string, signal?: AbortSignal): Promise<RPreview> {
   try {
     const normalized = normReq(request);
-    const previewFixes: string[] = [];
-    if (isRec(normalized)) {
-      const expanded = decodeStringArray(normalized.lines, previewFixes, "lines");
-      if (expanded) normalized.lines = expanded;
-    }
     assertInsertReq(normalized);
     const previewReq = normalized as InsertReq;
     const { ref, warnings: previewAnchorWarnings } = parseInsertAnchor(previewReq.anchor);
-    await throwIfStrictInput([...previewFixes, ...previewAnchorWarnings]);
+    await throwIfStrictInput(previewAnchorWarnings);
     const targetPath = await resolveEditTargetWithRequirement({
       anchor: previewReq.anchor,
       providedPath: previewReq.path,
@@ -125,13 +115,14 @@ export async function insertPreview(request: unknown, cwd: string, signal?: Abor
       allocation: "shadow",
       signal,
     });
-    const { editParams, anchorLine } = buildInsertEdit(normalized, preload, ref, targetPath);
+    const { editParams, anchorLine, contentSeparators } = buildInsertEdit(normalized, preload, ref, targetPath);
     const pipe = await execPipeline(targetPath, editParams, cwd, {
       accessMode: constants.R_OK,
       noPersist: true,
       preloadedNorm: preload,
       signal,
       stripWarning: insertStripWarning(anchorLine, normalized.direction),
+      endingOverrides: contentSeparators,
     });
     return previewFromPipe(pipe);
   } catch (error: unknown) {
@@ -140,7 +131,7 @@ export async function insertPreview(request: unknown, cwd: string, signal?: Abor
   }
 }
 
-function getInsertInput(args: unknown): { path?: string; anchor?: string; direction?: "before" | "after"; lines?: string[] } | null {
+function getInsertInput(args: unknown): { path?: string; anchor?: string; direction?: "before" | "after"; lines?: string } | null {
   let normalized: unknown;
   try {
     normalized = normReq(args);
@@ -151,8 +142,7 @@ function getInsertInput(args: unknown): { path?: string; anchor?: string; direct
   if (
     typeof normalized.anchor !== "string" ||
     (normalized.direction !== "before" && normalized.direction !== "after") ||
-    !Array.isArray(normalized.lines) ||
-    normalized.lines.some((line) => typeof line !== "string")
+    typeof normalized.lines !== "string"
   ) {
     return null;
   }
@@ -160,7 +150,7 @@ function getInsertInput(args: unknown): { path?: string; anchor?: string; direct
     ...(typeof normalized.path === "string" ? { path: normalized.path } : {}),
     anchor: normalized.anchor as string,
     direction: normalized.direction as "before" | "after",
-    lines: normalized.lines as string[],
+    lines: normalized.lines,
   };
 }
 
@@ -185,14 +175,10 @@ export function buildInsertToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): I
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       return withAnchorSession(ctx, async () => {
         const canonical = normReq(params);
-        const insertWarnings: string[] = [];
-        if (isRec(canonical)) {
-          const expanded = decodeStringArray(canonical.lines, insertWarnings, "lines");
-          if (expanded) canonical.lines = expanded;
-        }
         assertInsertReq(canonical);
         const req = canonical;
-        const literalEscape = literalEscapeHint(req.lines, "lines");
+        const insertWarnings: string[] = [];
+        const literalEscape = literalEscapeHint([req.lines], "lines");
         if (literalEscape !== undefined) insertWarnings.push(literalEscape);
         const targetPath = await resolveEditTargetWithRequirement({
           anchor: req.anchor,
@@ -253,6 +239,7 @@ export function buildInsertToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): I
             signal,
             preloadedNorm: preload,
             stripWarning: insertStripWarning(anchorLine, req.direction),
+            endingOverrides: contentSeparators,
           });
           return commitEdit(pipe, {
             path: pipe.path,

package/src/payload-contract.ts

@@ -1,29 +1,24 @@
 import { Type } from "typebox";
-import { isRec, normalizeRequest, rejectUnknownFields, assertNoNul } from "./utils";
+import { isRec, normalizeFilePath, normalizeRequest, rejectUnknownFields, assertNoNul } from "./utils";
+import { LINES_NOT_STRING_MSG, NEW_CONTENT_NOT_STRING_MSG } from "./constants";
 
-const replacementLinesSchema = Type.Array(
-  Type.String({
-    description:
-      "One replacement line. A real line break (\\n, \\r\\n, or \\r) splits it into lines and sets their endings.",
-  }),
-  {
-    description:
-      "One string per line. Use [] to delete the range; [\"\"] is a single blank line.",
-  },
-);
+const replacementLinesSchema = Type.String({
+  description:
+    'The exact text to write in place of the removed range. "" deletes the range, "\\n" is one blank line, and a trailing line break sets the last line\'s ending instead of adding a blank line.',
+});
 
 const removeFromSchema = Type.String({
   description:
-    "Bare 4-char anchor from a served anchor│content row (the text before the `│` separator), never the row content. Marks the FIRST line to remove (inclusive)",
+    "4-char anchor of the FIRST line to remove (never the row content).",
 });
 
 const removeToSchema = Type.String({
   description:
-    "Bare 4-char anchor from a served anchor│content row (the text before the `│` separator), never the row content. Marks the LAST line to remove (inclusive)",
+    "4-char anchor of the LAST line to remove.",
 });
 const pathRequiredSchema = Type.String({
   description:
-    "Path to the file the anchors were served for; required and must match anchor ownership. Anchors still resolve the target.",
+    "Path to the file the anchors were served for; required and must match anchor ownership.",
 });
 
 export const editToolSchema = Type.Object(
@@ -52,7 +47,14 @@ export type ReqParams = {
   path?: string;
   remove_from: string;
   remove_to: string;
-  replacement_lines: string[];
+  replacement_lines: string;
+};
+
+export type RawReqParams = {
+  path?: string;
+  remove_from: string;
+  remove_to: string;
+  replacement_lines: string | string[];
 };
 
 const ROOT_KS = new Set(["path", "remove_from", "remove_to", "replacement_lines"]);
@@ -66,20 +68,21 @@ export function assertReq(request: unknown): asserts request is ReqParams {
   }
   if (
     typeof request.remove_from !== "string" ||
-    typeof request.remove_to !== "string" ||
-    !Array.isArray(request.replacement_lines) ||
-    request.replacement_lines.some((line) => typeof line !== "string")
+    typeof request.remove_to !== "string"
   ) {
     throw new Error(
-      '[E_BAD_SHAPE] Edit request requires "remove_from", "remove_to", and "replacement_lines" (array of strings, one per line; use [] to delete).',
+      '[E_BAD_SHAPE] Edit request requires "remove_from" and "remove_to" anchor strings and a "replacement_lines" string with the exact text to write.',
     );
   }
-  assertNoNul(request.replacement_lines);
+  if (typeof request.replacement_lines !== "string") {
+    throw new Error(NEW_CONTENT_NOT_STRING_MSG);
+  }
+  assertNoNul([request.replacement_lines]);
 }
 
 export { normalizeRequest as normReq } from "./utils";
 
-export function getPreviewInput(args: unknown): { path?: string; remove_from: string; remove_to: string; replacement_lines: string[] } | null {
+export function getPreviewInput(args: unknown): { path?: string; remove_from: string; remove_to: string; replacement_lines: string } | null {
   let normalized: unknown;
   try {
     normalized = normalizeRequest(args);
@@ -90,8 +93,7 @@ export function getPreviewInput(args: unknown): { path?: string; remove_from: st
   if (
     typeof normalized.remove_from !== "string" ||
     typeof normalized.remove_to !== "string" ||
-    !Array.isArray(normalized.replacement_lines) ||
-    normalized.replacement_lines.some((line) => typeof line !== "string")
+    typeof normalized.replacement_lines !== "string"
   ) {
     return null;
   }
@@ -99,7 +101,7 @@ export function getPreviewInput(args: unknown): { path?: string; remove_from: st
     ...(typeof normalized.path === "string" ? { path: normalized.path } : {}),
     remove_from: normalized.remove_from as string,
     remove_to: normalized.remove_to as string,
-    replacement_lines: normalized.replacement_lines as string[],
+    replacement_lines: normalized.replacement_lines,
   };
 }
 
@@ -109,7 +111,7 @@ export interface InsertReq {
   path?: string;
   anchor: string;
   direction: "before" | "after";
-  lines: string[];
+  lines: string;
 }
 
 export function assertInsertReq(request: unknown): asserts request is InsertReq {
@@ -126,10 +128,10 @@ export function assertInsertReq(request: unknown): asserts request is InsertReq
   if (request.direction !== "before" && request.direction !== "after") {
     throw new Error('[E_BAD_SHAPE] Insert request "direction" must be "before" or "after".');
   }
-  if (!Array.isArray(request.lines) || request.lines.some((line) => typeof line !== "string")) {
-    throw new Error('[E_BAD_SHAPE] Insert request requires "lines" as an array of strings, one element per line.');
+  if (typeof request.lines !== "string") {
+    throw new Error(LINES_NOT_STRING_MSG);
   }
-  assertNoNul(request.lines);
+  assertNoNul([request.lines]);
 }
 
 const TRANSFER_KEYS = new Set(["path", "source_from", "source_to", "insert_after"]);
@@ -159,3 +161,128 @@ export function assertTransferReq(request: unknown): asserts request is Transfer
     throw new Error('[E_BAD_SHAPE] Copy/move request requires an "insert_after" string (4-char anchor from read output).');
   }
 }
+
+const WITHIN_KS = new Set(["path", "replace_from", "replace_to", "replace_old", "replace_new"]);
+
+export interface ReplaceWithinReq {
+  path?: string;
+  replace_from: string;
+  replace_to: string;
+  replace_old: string;
+  replace_new: string;
+}
+
+export function assertReplaceWithinReq(request: unknown): asserts request is ReplaceWithinReq {
+  if (!isRec(request)) {
+    throw new Error("[E_BAD_SHAPE] Replace-within request must be an object.");
+  }
+  rejectUnknownFields(request, WITHIN_KS, "Replace-within request");
+  if (request.path !== undefined && typeof request.path !== "string") {
+    throw new Error('[E_BAD_SHAPE] Replace-within request field "path" must be a string when provided.');
+  }
+  for (const key of ["replace_from", "replace_to", "replace_old", "replace_new"] as const) {
+    if (typeof (request as Record<string, unknown>)[key] !== "string") {
+      throw new Error(`[E_BAD_SHAPE] Replace-within request requires a "${key}" string.`);
+    }
+  }
+  const within = request as unknown as ReplaceWithinReq;
+  if (within.replace_from.length === 0 || within.replace_to.length === 0) {
+    throw new Error('[E_BAD_SHAPE] Replace-within request requires non-empty "replace_from" and "replace_to" anchors.');
+  }
+  if (within.replace_old.length === 0) {
+    throw new Error('[E_BAD_SHAPE] Replace-within request field "replace_old" must be a non-empty string holding the exact text to find.');
+  }
+  assertNoNul([within.replace_new]);
+}
+
+const WITHIN_ANCHOR_ALIASES: Array<[string, "replace_from" | "replace_to"]> = [
+  ["replace_from", "replace_from"],
+  ["remove_from", "replace_from"],
+  ["from", "replace_from"],
+  ["replace_to", "replace_to"],
+  ["remove_to", "replace_to"],
+  ["to", "replace_to"],
+];
+
+export function normalizeReplaceWithinRequest(input: unknown): unknown {
+  if (!isRec(input)) return input;
+  const record: Record<string, unknown> = { ...input };
+  normalizeFilePath(record);
+  for (const [alias, canonical] of WITHIN_ANCHOR_ALIASES) {
+    if (typeof record[canonical] !== "string" && typeof record[alias] === "string") {
+      record[canonical] = record[alias];
+    }
+    if (alias !== canonical) delete record[alias];
+  }
+  return record;
+}
+
+export function getReplaceWithinInput(args: unknown): { path?: string; replace_from: string; replace_to: string; replace_old: string; replace_new: string } | null {
+  let normalized: unknown;
+  try {
+    normalized = normalizeReplaceWithinRequest(args);
+  } catch {
+    return null;
+  }
+  if (!isRec(normalized)) return null;
+  if (
+    typeof normalized.replace_from !== "string" ||
+    typeof normalized.replace_to !== "string" ||
+    typeof normalized.replace_old !== "string" ||
+    typeof normalized.replace_new !== "string"
+  ) {
+    return null;
+  }
+  return {
+    ...(typeof normalized.path === "string" ? { path: normalized.path } : {}),
+    replace_from: normalized.replace_from,
+    replace_to: normalized.replace_to,
+    replace_old: normalized.replace_old,
+    replace_new: normalized.replace_new,
+  };
+}
+
+const replaceWithinFromSchema = Type.String({
+  description:
+    "4-char anchor of the FIRST line of the range searched (never the row content).",
+});
+const replaceWithinToSchema = Type.String({
+  description:
+    "4-char anchor of the LAST line of the range searched; same as replace_from for a single line.",
+});
+const replaceWithinOldSchema = Type.String({
+  description:
+    "The exact text to find inside the selected line(s), copied from the served row. It must occur exactly once; the text around it is left untouched. Matching uses LF line breaks and excludes the last line's terminator.",
+});
+const replaceWithinNewSchema = Type.String({
+  description:
+    'The exact replacement for the matched text. "" deletes the match, "\\n" inserts one blank line, and a trailing line break sets the last line\'s ending instead of adding a blank line; the rest of the range is kept byte-for-byte.',
+});
+const replaceWithinPathRequiredSchema = Type.String({
+  description:
+    "Path to the file the anchors were served for; required and must match anchor ownership.",
+});
+
+export const replaceWithinToolSchema = Type.Object(
+  {
+    replace_from: replaceWithinFromSchema,
+    replace_to: replaceWithinToSchema,
+    replace_old: replaceWithinOldSchema,
+    replace_new: replaceWithinNewSchema,
+  },
+  { additionalProperties: true },
+);
+
+export function buildReplaceWithinToolSchema(requirePath: boolean): typeof replaceWithinToolSchema {
+  if (!requirePath) return replaceWithinToolSchema;
+  return Type.Object(
+    {
+      path: replaceWithinPathRequiredSchema,
+      replace_from: replaceWithinFromSchema,
+      replace_to: replaceWithinToSchema,
+      replace_old: replaceWithinOldSchema,
+      replace_new: replaceWithinNewSchema,
+    },
+    { additionalProperties: true },
+  ) as typeof replaceWithinToolSchema;
+}

package/src/replace-render.ts

@@ -81,7 +81,7 @@ export function highlightBatchRefs(text: string, theme: FgT): string {
 }
 
 export function fmtCall(
-  args: { path?: string; remove_from?: string; remove_to?: string; anchor?: string; source_from?: string; source_to?: string; insert_after?: string } | undefined,
+  args: { path?: string; remove_from?: string; remove_to?: string; anchor?: string; source_from?: string; source_to?: string; insert_after?: string; replace_from?: string; replace_to?: string } | undefined,
   state: RRState,
   expanded: boolean,
   theme: CallT,
@@ -89,7 +89,7 @@ export function fmtCall(
 ): string {
   const previewPath = state.preview && "path" in state.preview ? state.preview.path : undefined;
   const path = args?.path ?? state.resolvedPath ?? previewPath;
-  const anchorFallback = typeof args?.remove_from === "string" && typeof args?.remove_to === "string" ? `${args.remove_from}→${args.remove_to}` : typeof args?.anchor === "string" ? args.anchor : typeof args?.source_from === "string" && typeof args?.insert_after === "string" ? `${args.source_from}→${args.insert_after}` : undefined;
+  const anchorFallback = typeof args?.remove_from === "string" && typeof args?.remove_to === "string" ? `${args.remove_from}→${args.remove_to}` : typeof args?.anchor === "string" ? args.anchor : typeof args?.source_from === "string" && typeof args?.insert_after === "string" ? `${args.source_from}→${args.insert_after}` : typeof args?.replace_from === "string" && typeof args?.replace_to === "string" ? `${args.replace_from}→${args.replace_to}` : undefined;
   const pathDisplay =
     typeof path === "string" && path.length > 0
       ? theme.fg("accent", path)
@@ -272,9 +272,9 @@ export function reuseMarkdown(context: any, content: string, theme: any): Markdo
 export function makeRenderCall(
 	preview: (args: unknown, cwd: string, signal?: AbortSignal) => Promise<RPreview>,
   options: {
-    getInput?: (args: unknown) => { path?: string; remove_from?: string; remove_to?: string; anchor?: string; source_from?: string; source_to?: string; insert_after?: string } | null;
+    getInput?: (args: unknown) => { path?: string; remove_from?: string; remove_to?: string; anchor?: string; source_from?: string; source_to?: string; insert_after?: string; replace_from?: string; replace_to?: string } | null;
     toolName?: string;
-    resolveTarget?: (input: { remove_from?: string; remove_to?: string; anchor?: string; source_from?: string; source_to?: string; insert_after?: string }) => string | undefined;
+    resolveTarget?: (input: { remove_from?: string; remove_to?: string; anchor?: string; source_from?: string; source_to?: string; insert_after?: string; replace_from?: string; replace_to?: string }) => string | undefined;
   } = {},
 ) {
 	const getInput = options.getInput ?? getPreviewInput;

package/src/replace-response.ts

@@ -2,6 +2,7 @@ import type { NEdit } from "./hashline";
 import type { ReplaceDetails } from "./replace";
 import { genDiff, genPatch, type DiffSpan } from "./replace-diff";
 import { visLines, clipLine } from "./utils";
+import { fidelityHints } from "./edit-fidelity";
 
 export type TResult = {
 	content: Array<{ type: "text"; text: string }>;
@@ -139,7 +140,8 @@ export function buildChanged(input: SuccessInput, verb = "replaced", diffContext
   const diffResult = genDiff(originalNormalized, result, diffContextLines, resultHashes, originalHashes, undefined, spans);
   const addedLines = editMeta.addedLines;
   const removedLines = editMeta.removedLines;
-  const { warnings: noticeWarnings, hints } = splitNotices(warnings);
+  const fidelity = fidelityHints(originalNormalized, result, spans);
+  const { warnings: noticeWarnings, hints } = splitNotices(fidelity.length > 0 ? [...(warnings ?? []), ...fidelity] : warnings);
   const noticesBlock = `${warnBlock(noticeWarnings)}${hintBlock(hints)}`;
   const successPrefix = `Successfully ${verb} in ${path}.`;
   const lineSummary = addedLines > 0 || removedLines > 0