pi-hashline-edit-pro 4.5.3 → 5.0.0

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

package/src/replace-within.ts

@@ -0,0 +1,227 @@
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { constants } from "node:fs";
+import { execPipeline, noteAnchorError, previewFromPipe, previewError, type ReplaceDetails } from "./replace";
+import { commitEdit } from "./commit";
+import { readNormFile, type NormFile } from "./file-reader";
+import { fmtRegion, MAX_HASH_LINES, parseHashRef, resolveAnchorLine, stripAnchorRow, type Anchor } from "./hashline";
+import { withAnchorSession } from "./anchor-registry";
+import { loadP, loadGuide } from "./prompts";
+import {
+  assertReplaceWithinReq,
+  buildReplaceWithinToolSchema,
+  getReplaceWithinInput,
+  normalizeReplaceWithinRequest,
+  type ReplaceWithinReq,
+} from "./payload-contract";
+import { literalEscapeHint, splitLines } from "./utils";
+import { toLF } from "./normalize";
+import { MAX_RANGE_STALE_LINES } from "./constants";
+import {
+  DEFAULT_EDIT_FLAGS,
+  editRenderResultWrapper,
+  editToolBase,
+  queuedEdit,
+  resolveEditTargetWithRequirement,
+  throwIfStrictInput,
+  tryResolveEditTarget,
+  withReplaceWithinPrompts,
+  type EditToolFlags,
+} from "./edit-common";
+import { makeRenderCall, type RPreview, type RRState } from "./replace-render";
+
+interface WithinRefs {
+  from: Anchor;
+  to: Anchor;
+}
+
+export interface WithinPlan {
+  editParams: { remove_from: string; remove_to: string; replacement_lines: string };
+}
+
+function formatWithinRange(start: number, end: number): string {
+  return start === end ? `line ${start}` : `lines ${start}-${end}`;
+}
+
+function offsetLineNumber(rangeLines: string[], offset: number): number {
+  let cursor = 0;
+  for (let index = 0; index < rangeLines.length; index++) {
+    const length = rangeLines[index]!.length;
+    if (offset <= cursor + length) return index + 1;
+    cursor += length + 1;
+  }
+  return rangeLines.length;
+}
+
+function matchOffsets(text: string, oldText: string): number[] {
+  const offsets: number[] = [];
+  let from = 0;
+  for (;;) {
+    const found = text.indexOf(oldText, from);
+    if (found < 0) return offsets;
+    offsets.push(found);
+    from = found + 1;
+  }
+}
+
+function notFoundMessage(displayPath: string, start: number, end: number, fileHashes: string[], fileLines: string[]): string {
+  const rangeLength = end - start + 1;
+  const shownCount = Math.min(rangeLength, MAX_RANGE_STALE_LINES);
+  const shown = fmtRegion(fileHashes.slice(start - 1, start - 1 + shownCount), fileLines.slice(start - 1, start - 1 + shownCount));
+  const more = rangeLength > shownCount ? `\n[The range has ${rangeLength} lines; showing the first ${shownCount}.]` : "";
+  return `[E_SUBSTRING_NOT_FOUND] "replace_old" was not found in ${formatWithinRange(start, end)} of ${displayPath}. Current rows:\n\n${shown}${more}\n\nCopy replace_old exactly from the served row (comparison uses LF breaks and excludes the last line's terminator) and retry.`;
+}
+
+function ambiguousMessage(displayPath: string, start: number, end: number, matchLines: number[]): string {
+  const shownCount = 8;
+  const shown = matchLines.slice(0, shownCount).join(", ");
+  const more = matchLines.length > shownCount ? ` (+${matchLines.length - shownCount} more)` : "";
+  return `[E_SUBSTRING_AMBIGUOUS] "replace_old" occurs ${matchLines.length} times in ${formatWithinRange(start, end)} of ${displayPath} (matching lines ${shown}${more}). Narrow replace_from/replace_to to one line, or extend replace_old so it matches exactly once.`;
+}
+
+export function parseWithinAnchors(req: ReplaceWithinReq): { refs: WithinRefs; warnings: string[] } {
+  const warnings: string[] = [];
+  const from = stripAnchorRow(req.replace_from.trim(), "replace_from entry", warnings);
+  const to = stripAnchorRow(req.replace_to.trim(), "replace_to entry", warnings);
+  return { refs: { from: parseHashRef(from), to: parseHashRef(to) }, warnings };
+}
+
+export function buildReplaceWithinEdit(req: ReplaceWithinReq, refs: WithinRefs, preload: NormFile, displayPath: string): WithinPlan {
+  const fileLines = splitLines(preload.normalized);
+  const fromLine = resolveAnchorLine(refs.from, fileLines, preload.fileHashes, displayPath);
+  const toLine = resolveAnchorLine(refs.to, fileLines, preload.fileHashes, displayPath);
+  const start = Math.min(fromLine, toLine);
+  const end = Math.max(fromLine, toLine);
+  const rangeLines = fileLines.slice(start - 1, end);
+  const rangeText = rangeLines.join("\n");
+  const oldText = toLF(req.replace_old);
+  const offsets = matchOffsets(rangeText, oldText);
+  if (offsets.length === 0) {
+    throw new Error(notFoundMessage(displayPath, start, end, preload.fileHashes, fileLines));
+  }
+  if (offsets.length > 1) {
+    throw new Error(ambiguousMessage(displayPath, start, end, offsets.map((offset) => start - 1 + offsetLineNumber(rangeLines, offset))));
+  }
+  const matchOffset = offsets[0]!;
+  const replacement = rangeText.slice(0, matchOffset) + req.replace_new + rangeText.slice(matchOffset + oldText.length);
+  const startRef = fromLine <= toLine ? refs.from : refs.to;
+  const endRef = fromLine <= toLine ? refs.to : refs.from;
+  return {
+    editParams: {
+      remove_from: startRef.hash,
+      remove_to: endRef.hash,
+      replacement_lines: replacement,
+    },
+  };
+}
+
+export async function replaceWithinPreview(request: unknown, cwd: string, signal?: AbortSignal): Promise<RPreview> {
+  try {
+    const normalized = normalizeReplaceWithinRequest(request);
+    assertReplaceWithinReq(normalized);
+    const req = normalized;
+    const { refs, warnings } = parseWithinAnchors(req);
+    await throwIfStrictInput(warnings);
+    const targetPath = await resolveEditTargetWithRequirement({
+      removeFrom: req.replace_from,
+      removeTo: req.replace_to,
+      providedPath: req.path,
+      cwd,
+    });
+    const preload = await readNormFile(targetPath, cwd, {
+      accessMode: constants.R_OK,
+      maxLines: MAX_HASH_LINES,
+      noPersist: true,
+      allocation: "shadow",
+      signal,
+    });
+    const plan = buildReplaceWithinEdit(req, refs, preload, targetPath);
+    const pipe = await execPipeline(targetPath, plan.editParams, cwd, {
+      accessMode: constants.R_OK,
+      noPersist: true,
+      preloadedNorm: preload,
+      signal,
+    });
+    return previewFromPipe(pipe);
+  } catch (error: unknown) {
+    if (signal?.aborted) throw error;
+    return previewError(error);
+  }
+}
+
+type ReplaceWithinToolDef = ToolDefinition<any, ReplaceDetails, RRState> & { renderShell?: "default" | "self" };
+
+export function buildReplaceWithinToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): ReplaceWithinToolDef {
+  const prompted = withReplaceWithinPrompts({
+    description: loadP("../prompts/replace-within.md"),
+    snippet: loadP("../prompts/replace-within-snippet.md"),
+    guidelines: loadGuide("../prompts/replace-within-guidelines.md"),
+  }, flags);
+  return {
+    name: "replace_within",
+    label: "Replace Within",
+    description: prompted.description,
+    promptSnippet: prompted.snippet,
+    promptGuidelines: prompted.guidelines,
+    ...editToolBase,
+    prepareArguments: normalizeReplaceWithinRequest,
+    parameters: buildReplaceWithinToolSchema(flags.requirePath),
+    renderCall: makeRenderCall(replaceWithinPreview, {
+      getInput: getReplaceWithinInput,
+      toolName: "replace_within",
+      resolveTarget: (input) => (typeof input.replace_from === "string" ? tryResolveEditTarget(input.replace_from, input.replace_to) : undefined),
+    }),
+    renderResult: editRenderResultWrapper,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      return withAnchorSession(ctx, async () => {
+        const normalized = normalizeReplaceWithinRequest(params);
+        assertReplaceWithinReq(normalized);
+        const req = normalized;
+        const { refs, warnings } = parseWithinAnchors(req);
+        await throwIfStrictInput(warnings);
+        const hints = [
+          literalEscapeHint([req.replace_old], "replace_old"),
+          literalEscapeHint([req.replace_new], "replace_new"),
+        ].filter((hint): hint is string => hint !== undefined);
+        const targetPath = await resolveEditTargetWithRequirement({
+          removeFrom: req.replace_from,
+          removeTo: req.replace_to,
+          providedPath: req.path,
+          cwd: ctx.cwd,
+        });
+        return queuedEdit(targetPath, ctx.cwd, signal, async (absolutePath, mutationTargetPath) => {
+          const preload = await readNormFile(targetPath, ctx.cwd, {
+            signal,
+            accessMode: constants.R_OK | constants.W_OK,
+            maxLines: MAX_HASH_LINES,
+          });
+          let plan: WithinPlan;
+          try {
+            plan = buildReplaceWithinEdit(req, refs, preload, targetPath);
+          } catch (error) {
+            await noteAnchorError(preload.absolutePath, error);
+            throw error;
+          }
+          const pipe = await execPipeline(targetPath, plan.editParams, ctx.cwd, {
+            accessMode: constants.R_OK | constants.W_OK,
+            signal,
+            preloadedNorm: preload,
+          });
+          return commitEdit(pipe, {
+            path: pipe.path,
+            absolutePath,
+            mutationTargetPath,
+            editAnchors: [plan.editParams.remove_from, plan.editParams.remove_to],
+            prefixWarnings: [...warnings, ...hints],
+            signal,
+            verb: "replaced",
+            noopNoun: "Replacement",
+          });
+        });
+      });
+    },
+  };
+}
+
+export function regReplaceWithin(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FLAGS): void {
+  pi.registerTool(buildReplaceWithinToolDef(flags));
+}

package/src/replace.ts

@@ -9,7 +9,7 @@ import {
   type LineEnding,
 } from "./replace-diff";
 import { readNormFile, type NormFile } from "./file-reader";
-import { editToolSchema, buildEditToolSchema, type ReqParams, assertReq, normReq } from "./payload-contract";
+import { editToolSchema, buildEditToolSchema, type ReqParams, type RawReqParams, assertReq, normReq } from "./payload-contract";
 import { literalEscapeHint, splitLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { type FileIdentity } from "./fs-write";
@@ -121,17 +121,12 @@ function countLineChanges(
     totalRemovedLines,
   };
 }
-
-export function buildReplaceHEdit(params: ReqParams): { edit: HEdit; warnings: string[] } {
+export function buildReplaceHEdit(params: RawReqParams): { edit: HEdit; warnings: string[] } {
   const editWarnings: string[] = [];
-  const edit = resEdit(
-    {
-      remove_from: params.remove_from,
-      remove_to: params.remove_to,
-      replacement_lines: params.replacement_lines,
-    },
-    editWarnings,
-  );
+  const anchors = { remove_from: params.remove_from, remove_to: params.remove_to };
+  const edit = typeof params.replacement_lines === "string"
+    ? resEdit({ ...anchors, replacement_lines: params.replacement_lines }, editWarnings)
+    : resEdit({ ...anchors, replacement_lines: params.replacement_lines }, editWarnings);
   return { edit, warnings: editWarnings };
 }
 
@@ -148,7 +143,7 @@ function withEndingOverrides(edit: HEdit, overrides: (LineEnding | undefined)[]
 
 export async function execPipeline(
   targetPath: string,
-  params: ReqParams,
+  params: RawReqParams,
   cwd: string,
   options?: ExecPipelineOptions,
 ): Promise<PipelineResult> {
@@ -290,7 +285,7 @@ export function buildToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): ToolDef
         const canonical = normReq(params);
         assertReq(canonical);
         const normalizedParams = canonical;
-        const literalEscape = literalEscapeHint(normalizedParams.replacement_lines, "replacement_lines");
+        const literalEscape = literalEscapeHint([normalizedParams.replacement_lines], "replacement_lines");
         const targetPath = await resolveEditTargetWithRequirement({
           removeFrom: normalizedParams.remove_from,
           removeTo: normalizedParams.remove_to,

package/src/utils.ts

@@ -1,5 +1,7 @@
 import { NUL_CONTENT_MSG, MAX_BYTES } from "./constants";
 import { HASH_CLASS } from "./hashline/alphabet";
+import { splitWithEndings } from "./line-endings";
+import type { LineEnding } from "./normalize";
 
 export function isRec(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -342,24 +344,36 @@ export function decodeStringArray(value: unknown, warnings?: string[], label = "
 	return undefined;
 }
 
-function normalizeLineFieldValue(value: unknown): string[] | undefined {
-	const candidate = typeof value === "string"
-		? value
-		: Array.isArray(value) && value.length === 1 && typeof value[0] === "string"
-			? value[0]
-			: undefined;
-	if (candidate === undefined) return undefined;
-	const decoded = decodeStringArray(candidate);
-	if (decoded !== undefined) return decoded;
-	if (/^\[\s*\]$/.test(stripTrailingMemberCall(stripCodeFence(candidate)))) return [];
-	return [candidate];
+function legacyLinesToText(lines: string[]): string {
+	const decoded = decodeStringArray(lines) ?? lines;
+	const parsedLines: string[] = [];
+	const parsedSeparators: (LineEnding | undefined)[] = [];
+	for (const element of decoded) {
+		const parsed = splitWithEndings(element);
+		const lineCount = element.endsWith("\n") || element.endsWith("\r") ? parsed.lines.length - 1 : parsed.lines.length;
+		for (let index = 0; index < lineCount; index++) {
+			parsedLines.push(parsed.lines[index]!);
+			parsedSeparators.push(parsed.endings[index]);
+		}
+	}
+	let text = "";
+	for (let index = 0; index < parsedLines.length; index++) {
+		const line = parsedLines[index]!;
+		const separator = parsedSeparators[index];
+		text += line;
+		if (separator !== undefined) text += separator;
+		else if (index < parsedLines.length - 1) text += "\n";
+		else if (line === "") text += "\n";
+	}
+	return text;
 }
 
 function normalizeEditLines(record: Record<string, unknown>): void {
 	for (const key of ["replacement_lines", "lines"]) {
-		if (!(key in record)) continue;
-		const lines = normalizeLineFieldValue(record[key]);
-		if (lines !== undefined) record[key] = lines;
+		const value = record[key];
+		if (Array.isArray(value) && value.every((entry): entry is string => typeof entry === "string")) {
+			record[key] = legacyLinesToText(value);
+		}
 	}
 }
 

package/prompts/grep-guidelines.md

@@ -1,2 +0,0 @@
-- `anchor_grep`: hits and `context` rows come back as `lineNumber │ anchor│content` — target them with `replace`/`insert` directly; `lineNumber` enables jump-to-line.
-- `anchor_grep`: binary/image files are skipped silently.