pi-hashline-edit-pro 4.0.1 → 4.2.0

package/src/hashline/apply.ts

@@ -1,4 +1,4 @@
-import { abortIf, splitLines } from "../utils";
+import { abortIf, clipLine, splitLines } from "../utils";
 import { _lineHashesPure } from "./hash";
 import {
 	valEdit,
@@ -52,7 +52,7 @@ type NoopSpan = {
 	loc: string;
 	currentContent: string;
 };
-function assertNotEmpty(originalContent: string, result: string): void {
+export function assertNotEmpty(originalContent: string, result: string): void {
 	if (originalContent.length > 0 && result.length === 0) {
 		throw new Error(
 			"[E_WOULD_EMPTY] A replace cannot empty a non-empty file. Use `write` to clear the file."
@@ -148,6 +148,122 @@ function assemble(
 	return content.slice(0, span.start) + span.replacement + content.slice(span.end);
 }
 
+export interface PlannedEdit {
+  resolved: RHEdit;
+  warnings: string[];
+  autoFixes?: AutoFix[];
+}
+
+
+function throwStrictBoundaryDedup(edit: HEdit, boundaryDups: BDup[], resolved: RHEdit): never {
+  const startLine = resolved.hash_bounds[0].line;
+  const endLine = resolved.hash_bounds[1].line;
+  const range = startLine === endLine ? `line ${startLine}` : `lines ${startLine}-${endLine}`;
+  const seen = new Set<number>();
+  for (const dup of boundaryDups) seen.add(dup.replacementLineIndex);
+  const removed = [...seen].sort((a, b) => a - b).map((index) => `replacement_lines line ${index + 1}: ${clipLine(edit.content_lines[index] ?? "")}`);
+  throw new Error(`[E_BOUNDARY_STRICT] Strict boundary dedup rejects this edit: ${seen.size} replacement line(s) re-include edge lines (${range}). ${removed.join("; ")}. Resend without those lines.`);
+}
+export function planEdit(
+  content: string,
+  edit: HEdit,
+  precomputedHashes: string[],
+  options?: {
+    filePath?: string;
+    servedHashes?: ReadonlyMap<string, string>;
+    skipBoundaryDedup?: boolean;
+    strictBoundaryDedup?: boolean;
+    signal?: AbortSignal;
+  },
+): PlannedEdit {
+  const signal = options?.signal;
+  abortIf(signal);
+  const lineIndex = buildIdx(content);
+  const fileHashes = precomputedHashes;
+  const warnings: string[] = [];
+
+  const rangeFixed = swapReversedRanges(edit, fileHashes, warnings);
+  const prefixFixed = stripDiffPrefixes(
+    stripBarePrefixes(rangeFixed, fileHashes, warnings),
+    warnings,
+  );
+
+  const { resolved: initialResolved, mismatches, boundaryDups } = valEdit(
+    prefixFixed,
+    lineIndex.fileLines,
+    fileHashes,
+    warnings,
+    signal,
+  );
+  if (mismatches.length || !initialResolved) {
+    const feedback = fmtMismatchWithHashes(
+      mismatches,
+      lineIndex.fileLines,
+      fileHashes,
+      options?.filePath,
+    );
+    throw new AnchorMismatchError(feedback.text, feedback.hashes, feedback.servedMap);
+  }
+
+  warnUnicodeEsc(prefixFixed, warnings);
+
+  if (options?.strictBoundaryDedup === true && boundaryDups.length > 0) {
+    throwStrictBoundaryDedup(prefixFixed, boundaryDups, initialResolved);
+  }
+  let resolved = initialResolved;
+  let autoFixes: AutoFix[] | undefined;
+  if (boundaryDups.length > 0 && !(options?.skipBoundaryDedup === true)) {
+    autoFixes = [];
+    const correctedEdit: HEdit = {
+      ...prefixFixed,
+      content_lines: [...prefixFixed.content_lines],
+    };
+    const seen = new Set<number>();
+    const uniqueDups: BDup[] = [];
+    for (const dup of boundaryDups) {
+      if (seen.has(dup.replacementLineIndex)) continue;
+      seen.add(dup.replacementLineIndex);
+      uniqueDups.push(dup);
+    }
+    const dupsByIndex = uniqueDups.sort(
+      (a, b) => b.replacementLineIndex - a.replacementLineIndex,
+    );
+    for (const dup of dupsByIndex) {
+      const idx = dup.replacementLineIndex;
+      if (idx < 0 || idx >= correctedEdit.content_lines.length) continue;
+      const removed = correctedEdit.content_lines.splice(idx, 1)[0];
+      autoFixes.push({ kind: dup.kind, removedLine: removed, removedLineIndex: idx });
+    }
+    const correctedResult = valEdit(
+      correctedEdit,
+      lineIndex.fileLines,
+      fileHashes,
+      warnings,
+      signal,
+    );
+    if (correctedResult.mismatches.length || !correctedResult.resolved) {
+      const feedback = fmtMismatchWithHashes(
+        correctedResult.mismatches,
+        lineIndex.fileLines,
+        fileHashes,
+        options?.filePath,
+      );
+      throw new AnchorMismatchError(feedback.text, feedback.hashes, feedback.servedMap);
+    }
+    resolved = correctedResult.resolved;
+  }
+
+  if (options?.servedHashes) {
+    abortIf(signal);
+    assertRangeServed(resolved, lineIndex.fileLines, fileHashes, options.servedHashes, options?.filePath);
+  }
+
+  return {
+    resolved,
+    warnings,
+    ...(autoFixes ? { autoFixes } : {}),
+  };
+}
 export function applyEdit(
 	content: string,
 	edit: HEdit,
@@ -156,6 +272,7 @@ export function applyEdit(
 	filePath?: string,
 	servedHashes?: ReadonlyMap<string, string>,
 	skipBoundaryDedup?: boolean,
+	strictBoundaryDedup?: boolean,
 	): {
 	content: string;
 	firstChangedLine: number | undefined;
@@ -164,88 +281,15 @@ export function applyEdit(
 	noopEdit?: NEdit;
 	autoFixes?: AutoFix[];
 } {
-	abortIf(signal);
-
-	const lineIndex = buildIdx(content);
-	if (precomputedHashes === undefined) {
-		throw new Error("[E_BAD_SHAPE] applyEdit requires the file's allocated anchors; derive them via lineHashes(content, path) first.");
-	}
-	const fileHashes = precomputedHashes;
-	const warnings: string[] = [];
-
-	const rangeFixed = swapReversedRanges(edit, fileHashes, warnings);
-	const prefixFixed = stripDiffPrefixes(
-		stripBarePrefixes(rangeFixed, fileHashes, warnings),
-		warnings,
-	);
-
-	const { resolved: initialResolved, mismatches, boundaryDups } = valEdit(
-		prefixFixed,
-		lineIndex.fileLines,
-		fileHashes,
-		warnings,
-		signal,
-	);
-	if (mismatches.length || !initialResolved) {
-		const feedback = fmtMismatchWithHashes(
-			mismatches,
-			lineIndex.fileLines,
-			fileHashes,
-			filePath,
-		);
-		throw new AnchorMismatchError(feedback.text, feedback.hashes, feedback.servedMap);
-	}
-
-	warnUnicodeEsc(prefixFixed, warnings);
-
-	let resolved = initialResolved;
-	let autoFixes: AutoFix[] | undefined;
-	if (boundaryDups.length > 0 && !skipBoundaryDedup) {
-		autoFixes = [];
-		const correctedEdit: HEdit = {
-			...prefixFixed,
-			content_lines: [...prefixFixed.content_lines],
-		};
-		const seen = new Set<number>();
-		const uniqueDups: BDup[] = [];
-		for (const dup of boundaryDups) {
-			if (seen.has(dup.replacementLineIndex)) continue;
-			seen.add(dup.replacementLineIndex);
-			uniqueDups.push(dup);
-		}
-		const dupsByIndex = uniqueDups.sort(
-			(a, b) => b.replacementLineIndex - a.replacementLineIndex,
-		);
-		for (const dup of dupsByIndex) {
-			const idx = dup.replacementLineIndex;
-			if (idx < 0 || idx >= correctedEdit.content_lines.length) continue;
-			const removed = correctedEdit.content_lines.splice(idx, 1)[0];
-			autoFixes.push({ kind: dup.kind, removedLine: removed, removedLineIndex: idx });
-		}
-		const correctedResult = valEdit(
-			correctedEdit,
-			lineIndex.fileLines,
-			fileHashes,
-			warnings,
-			signal,
-		);
-		if (correctedResult.mismatches.length || !correctedResult.resolved) {
-			const feedback = fmtMismatchWithHashes(
-				correctedResult.mismatches,
-				lineIndex.fileLines,
-				fileHashes,
-				filePath,
-			);
-			throw new AnchorMismatchError(feedback.text, feedback.hashes, feedback.servedMap);
-		}
-		resolved = correctedResult.resolved;
-	}
-
-	if (servedHashes) {
-		abortIf(signal);
-		assertRangeServed(resolved, lineIndex.fileLines, fileHashes, servedHashes, filePath);
-	}
-
+  abortIf(signal);
+  if (precomputedHashes === undefined) {
+    throw new Error("[E_BAD_SHAPE] applyEdit requires the file's allocated anchors; derive them via lineHashes(content, path) first.");
+  }
+  const planned = planEdit(content, edit, precomputedHashes, { filePath, servedHashes, skipBoundaryDedup, strictBoundaryDedup, signal });
+  const lineIndex = buildIdx(content);
+  const warnings = planned.warnings;
+  const resolved = planned.resolved;
+  const autoFixes = planned.autoFixes;
 	const spanResult = resToSpan(resolved, content, lineIndex);
 	if (spanResult.kind === "noop") {
 		return {

package/src/hashline/index.ts

@@ -43,7 +43,10 @@ export {
 export {
 	buildIdx,
 	applyEdit,
+	planEdit,
+	type PlannedEdit,
 	fmtRegion,
 	fmtRow,
 	changedRange,
+	assertNotEmpty,
 } from "./apply";

package/src/hashline/resolve.ts

@@ -1,6 +1,7 @@
 import { abortIf, rejectUnknownFields, firstNonEmptyIndex, lastNonEmptyIndex, clipLine, getCached } from "../utils";
-import { HASH_SEP, HASH_RUN, stripRowPrefix, canon } from "./hash";
 import { parseHashRef, parseText, type Anchor } from "./parse";
+import { HASH_SEP, stripRowPrefix, canon } from "./hash";
+import { HASH_RUN } from "./alphabet";
 import { NEW_CONTENT_NOT_ARRAY_MSG, MAX_RANGE_STALE_LINES } from "../constants";
 import { contentChecksum } from "./hasher";
 import { hashSource } from "./hash";
@@ -97,7 +98,7 @@ export function fmtMismatchWithHashes(
   if (notFound.length > 0) {
     const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
     out.push(
-      `[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. The file changed since read. Call read() for fresh anchors.`
+      `[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. The file changed since read. Call read()${filePath ? ` on ${filePath}` : ""} for fresh anchors.`
     );
     for (const m of notFound) {
       const ctx = m.context;
@@ -536,8 +537,8 @@ export function assertRangeServed(
       : `${mismatchLines.length} of ${rangeLength} line(s) in the replaced range (lines ${startLine}-${endLine})${location} do not match`;
   const capHint =
     rangeLength > shownLength
-      ? `\n\n[The range has ${rangeLength} lines; showing the first ${shownLength}. Call read() with offset=${startLine + shownLength} to see the rest.]`
-      : "";
+      ? `\n\n[The range has ${rangeLength} lines; showing the first ${shownLength}. Call read()${filePath ? ` on ${filePath}` : ""} with offset=${startLine + shownLength} to see the rest.]`
+      : "\n\nRetry with the fresh anchors above without a read.";
   const message =
     `[E_RANGE_STALE] ${mismatchText} what was shown. Nothing was modified. Current range with fresh anchors:\n\n${rows.join("\n")}${capHint}`;
   throw new RangeStaleError(message, shownHashes, shownMap);

package/src/insert.ts

@@ -3,76 +3,72 @@ import { Type } from "typebox";
 import { constants } from "fs";
 import { execPipeline, type ReqParams, type ReplaceDetails, previewFromPipe, previewError } from "./replace";
 import { commitEdit } from "./commit";
+import { batchMemberFor, executeBatchMember, noteBatchFailure } from "./batch";
 import { readNormFile, type NormFile } from "./file-reader";
-import { MAX_HASH_LINES, parseHashRef, resolveAnchorLine, type Anchor } from "./hashline";
+import { MAX_HASH_LINES, parseHashRef, resEdit, resolveAnchorLine, type Anchor, type HEdit } from "./hashline";
 import { stripAnchorRow } from "./hashline/resolve";
 import { loadP, loadGuide } from "./prompts";
-import { normReq } from "./payload-contract";
-import { decodeStringArray, isRec, rejectUnknownFields, splitLines } from "./utils";
+import { assertInsertReq, normReq, type InsertReq } from "./payload-contract";
+import { decodeStringArray, isRec, splitLines } from "./utils";
 import { clearBoundaryBypass } from "./boundary-bypass";
-import { resolveEditTarget } from "./edit-common";
+import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper, resolveEditTargetWithRequirement, throwIfStrictInput, withInsertPrompts, DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-common";
 import type { RPreview, RRState } from "./replace-render";
-import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper } from "./edit-common";
+export { assertInsertReq, type InsertReq };
 
-const INSERT_KS = new Set(["anchor", "direction", "lines"]);
+const insertAnchorSchema = Type.String({
+  description:
+    'Bare 4-char anchor from a read 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.',
+});
 
-export interface InsertReq {
-  anchor: string;
-  direction: "before" | "after";
-  lines: string[];
-}
+const insertDirectionSchema = Type.Union(
+  [Type.Literal("after"), Type.Literal("before")],
+  { description: '"after" or "before"' },
+);
 
-export function assertInsertReq(request: unknown): asserts request is InsertReq {
-  if (!isRec(request)) {
-    throw new Error("[E_BAD_SHAPE] Insert request must be an object.");
-  }
-  rejectUnknownFields(request, INSERT_KS, "Insert request");
-  if (typeof request.anchor !== "string" || request.anchor.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Insert request requires an "anchor" string (4-char anchor from read output).');
-  }
-  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.');
+const insertLinesSchema = Type.Array(
+  Type.String({
+    description: "One line to insert; never embed \\n inside an element.",
+  }),
+  {
+    description: 'One string per line; [""] is 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.",
+});
 
 const insertToolSchema = Type.Object(
   {
-    anchor: Type.String({
-      description:
-        'Bare 4-char anchor from a read 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.',
-    }),
-    direction: Type.Union(
-      [
-        Type.Literal("after"),
-        Type.Literal("before"),
-      ],
-      { description: '"after" or "before"' },
-    ),
-    lines: Type.Array(
-      Type.String({
-        description:
-          "One line to insert; never embed \\n inside an element.",
-      }),
-      {
-        description:
-          'One string per line; [""] is a blank line; never include the anchor line.',
-      }
-    ),
+    anchor: insertAnchorSchema,
+    direction: insertDirectionSchema,
+    lines: insertLinesSchema,
   },
   { additionalProperties: false },
 );
 
-function parseInsertAnchor(raw: string): { ref: Anchor; warnings: string[] } {
+export function buildInsertToolSchema(requirePath: boolean): typeof insertToolSchema {
+  if (!requirePath) return insertToolSchema;
+  return Type.Object(
+    {
+      path: insertPathRequiredSchema,
+      anchor: insertAnchorSchema,
+      direction: insertDirectionSchema,
+      lines: insertLinesSchema,
+    },
+    { additionalProperties: false },
+  ) as typeof insertToolSchema;
+}
+
+export function parseInsertAnchor(raw: string): { ref: Anchor; warnings: string[] } {
   const trimmedAnchor = raw.trim();
   const warnings: string[] = [];
   const anchorText = stripAnchorRow(trimmedAnchor, "anchor entry", warnings);
   return { ref: parseHashRef(anchorText), warnings };
 }
 
-function buildInsertEdit(
+export function buildInsertEdit(
   req: InsertReq,
   preload: NormFile,
   ref: Anchor,
@@ -97,17 +93,28 @@ function buildInsertEdit(
 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);
-      if (expanded) normalized.lines = expanded;
+      if (expanded) {
+        previewFixes.push('[W_BAD_SHAPE] Unwrapped JSON array syntax from a lines element.');
+        normalized.lines = expanded;
+      }
     }
     assertInsertReq(normalized);
-    const { ref } = parseInsertAnchor(normalized.anchor);
-    const targetPath = resolveEditTarget(normalized.anchor);
+    const previewReq = normalized as InsertReq;
+    const { ref, warnings: previewAnchorWarnings } = parseInsertAnchor(previewReq.anchor);
+    await throwIfStrictInput([...previewFixes, ...previewAnchorWarnings]);
+    const targetPath = await resolveEditTargetWithRequirement({
+      anchor: previewReq.anchor,
+      providedPath: previewReq.path,
+      cwd,
+    });
     const preload = await readNormFile(targetPath, cwd, {
       accessMode: constants.R_OK,
       maxLines: MAX_HASH_LINES,
       noPersist: true,
+      allocation: "shadow",
       signal,
     });
     const { editParams } = buildInsertEdit(normalized, preload, ref, targetPath);
@@ -151,15 +158,20 @@ function getInsertInput(args: unknown): { path?: string; anchor?: string; direct
 
 type InsertToolDef = ToolDefinition<any, ReplaceDetails, RRState> & { renderShell?: "default" | "self" };
 
-export function buildInsertToolDef(): InsertToolDef {
+export function buildInsertToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): InsertToolDef {
+  const prompted = withInsertPrompts({
+    description: loadP("../prompts/insert.md"),
+    snippet: loadP("../prompts/insert-snippet.md"),
+    guidelines: loadGuide("../prompts/insert-guidelines.md"),
+  }, flags);
   return {
     name: "insert",
     label: "Insert",
-    description: loadP("../prompts/insert.md"),
-    promptSnippet: loadP("../prompts/insert-snippet.md"),
-    promptGuidelines: loadGuide("../prompts/insert-guidelines.md"),
+    description: prompted.description,
+    promptSnippet: prompted.snippet,
+    promptGuidelines: prompted.guidelines,
     ...editToolBase,
-    parameters: insertToolSchema,
+    parameters: buildInsertToolSchema(flags.requirePath),
     renderCall: editRenderCallWrapper(insertPreview, getInsertInput, "insert"),
     renderResult: editRenderResultWrapper,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -174,37 +186,78 @@ export function buildInsertToolDef(): InsertToolDef {
       }
       assertInsertReq(canonical);
       const req = canonical;
-      const targetPath = resolveEditTarget(req.anchor);
-      const { ref, warnings: anchorWarnings } = parseInsertAnchor(req.anchor);
+      const targetPath = await resolveEditTargetWithRequirement({
+        anchor: req.anchor,
+        providedPath: req.path,
+        cwd: ctx.cwd,
+      }).catch((error: unknown) => {
+        const member = batchMemberFor(_toolCallId);
+        if (member) noteBatchFailure(member, error);
+        throw error;
+      });
+      let ref: Anchor;
+      let anchorWarnings: string[];
+      try {
+        ({ ref, warnings: anchorWarnings } = parseInsertAnchor(req.anchor));
+        await throwIfStrictInput([...anchorWarnings, ...insertWarnings]);
+      } catch (error) {
+        const member = batchMemberFor(_toolCallId);
+        if (member) noteBatchFailure(member, error);
+        throw error;
+      }
       return queuedEdit(targetPath, ctx.cwd, signal, async (absolutePath, mutationTargetPath) => {
+        const member = batchMemberFor(_toolCallId);
         const preload = await readNormFile(targetPath, ctx.cwd, {
           signal,
           accessMode: constants.R_OK | constants.W_OK,
           maxLines: MAX_HASH_LINES,
         });
         const { editParams, anchorLine } = buildInsertEdit(req, preload, ref, targetPath);
-        const pipe = await execPipeline(targetPath, editParams, ctx.cwd, {
-          accessMode: constants.R_OK | constants.W_OK,
-          signal,
-          preloadedNorm: preload,
-          skipBoundaryDedup: true,
-        });
-        return commitEdit(pipe, {
-          path: pipe.path,
-          absolutePath,
+        if (!member) {
+          const pipe = await execPipeline(targetPath, editParams, ctx.cwd, {
+            accessMode: constants.R_OK | constants.W_OK,
+            signal,
+            preloadedNorm: preload,
+            skipBoundaryDedup: true,
+          });
+          return commitEdit(pipe, {
+            path: pipe.path,
+            absolutePath,
+            mutationTargetPath,
+            signal,
+            verb: "inserted",
+            noopNoun: "Insertion",
+            foldedAnchorLines: anchorLine === undefined ? 0 : 1,
+            prefixWarnings: [...anchorWarnings, ...insertWarnings],
+            onApplied: () => clearBoundaryBypass(mutationTargetPath),
+          });
+        }
+        let hedit: HEdit;
+        const resWarnings: string[] = [];
+        try {
+          hedit = resEdit(editParams, resWarnings);
+        } catch (error) {
+          noteBatchFailure(member, error);
+          throw error;
+        }
+        return executeBatchMember({
+          kind: "insert",
+          member,
+          targetPath,
           mutationTargetPath,
+          cwd: ctx.cwd,
           signal,
-          verb: "inserted",
-          noopNoun: "Insertion",
-          foldedAnchorLines: anchorLine === undefined ? 0 : 1,
-          prefixWarnings: [...anchorWarnings, ...insertWarnings],
-          onApplied: () => clearBoundaryBypass(mutationTargetPath),
+          hedit,
+          extraWarnings: [...anchorWarnings, ...insertWarnings, ...resWarnings],
+          skipBoundaryDedup: true,
+          strictBoundaryDedup: false,
+          foldedLines: anchorLine === undefined ? 0 : 1,
         });
       });
     },
   };
 }
 
-export function regInsert(pi: ExtensionAPI): void {
-  pi.registerTool(buildInsertToolDef());
+export function regInsert(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FLAGS): void {
+  pi.registerTool(buildInsertToolDef(flags));
 }

package/src/payload-contract.ts

@@ -21,6 +21,10 @@ const removeToSchema = Type.String({
   description:
     "Bare 4-char anchor from a read row (the text before the `│` separator), never the row content. Marks the LAST line to remove (inclusive)",
 });
+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.",
+});
 
 export const editToolSchema = Type.Object(
   {
@@ -31,19 +35,35 @@ export const editToolSchema = Type.Object(
   { additionalProperties: false },
 );
 
+export function buildEditToolSchema(requirePath: boolean): typeof editToolSchema {
+  if (!requirePath) return editToolSchema;
+  return Type.Object(
+    {
+      path: pathRequiredSchema,
+      remove_from: removeFromSchema,
+      remove_to: removeToSchema,
+      replacement_lines: replacementLinesSchema,
+    },
+    { additionalProperties: false },
+  ) as typeof editToolSchema;
+}
+
 export type ReqParams = {
+  path?: string;
   remove_from: string;
   remove_to: string;
   replacement_lines: string[];
 };
 
-const ROOT_KS = new Set(["remove_from", "remove_to", "replacement_lines"]);
-
+const ROOT_KS = new Set(["path", "remove_from", "remove_to", "replacement_lines"]);
 export function assertReq(request: unknown): asserts request is ReqParams {
   if (!isRec(request)) {
     throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
   }
   rejectUnknownFields(request, ROOT_KS, "Edit request");
+  if (request.path !== undefined && typeof request.path !== "string") {
+    throw new Error('[E_BAD_SHAPE] Edit request field "path" must be a string when provided.');
+  }
   if (
     typeof request.remove_from !== "string" ||
     typeof request.remove_to !== "string" ||
@@ -89,3 +109,31 @@ export function getPreviewInput(args: unknown): { path?: string; remove_from: st
     replacement_lines: normalized.replacement_lines as string[],
   };
 }
+
+const INSERT_KS = new Set(["path", "anchor", "direction", "lines"]);
+
+export interface InsertReq {
+  path?: string;
+  anchor: string;
+  direction: "before" | "after";
+  lines: string[];
+}
+
+export function assertInsertReq(request: unknown): asserts request is InsertReq {
+  if (!isRec(request)) {
+    throw new Error("[E_BAD_SHAPE] Insert request must be an object.");
+  }
+  rejectUnknownFields(request, INSERT_KS, "Insert request");
+  if (request.path !== undefined && typeof request.path !== "string") {
+    throw new Error('[E_BAD_SHAPE] Insert request field "path" must be a string when provided.');
+  }
+  if (typeof request.anchor !== "string" || request.anchor.length === 0) {
+    throw new Error('[E_BAD_SHAPE] Insert request requires an "anchor" string (4-char anchor from read output).');
+  }
+  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.');
+  }
+}