@bacnh85/pi-model-tools 0.2.0 → 0.3.0

package/README.md

@@ -53,6 +53,8 @@ a family is detected; everything degrades gracefully to a no-op otherwise.
 | **Read-on-guessed-path blocking** | Blocks `read` on a non-existent code-file path, suggests `find` first |
 | **Prompt-aware first-tool hints** | Forces the correct first tool: `bash`-first for RUN/BUILD/EXECUTE tasks, `bash` git-clone-first for analyze-a-repo-URL tasks, and `find`-first for bare-filename reads. Targeted (only fires on matching intent) and applied to all detected families. |
 | **Error categorization** | Classifies tool errors and injects recovery hints on the next turn |
+| **Edit mismatch repair** | Strips `read`-tool truncation notices (`[Showing lines … Use offset=N to continue.]`, etc.) that models copy into `edit` oldText — the documented root cause of "Could not find the exact text" failures. On a match failure, retries once with whitespace-tolerant matching (copying the file's real indentation); on unresolvable matches, enriches the error with the nearest numbered region. Always on. |
+| **`apply_patch` tool** | A Codex-style V4D diff/patch tool: emit only `@@` context + `-`/`+` change lines instead of large verbatim oldText blocks. Robust for multi-line/multi-file edits across all models. DeepSeek/GLM get steering to prefer it for non-trivial edits. |
 
 ### DeepSeek V4 only (verbose steering the Flash model needs)
 
@@ -65,6 +67,39 @@ a family is detected; everything degrades gracefully to a no-op otherwise.
 
 ## Installation
 
+## `apply_patch` — diff-based editing
+
+`apply_patch` is a Codex-style V4D patch tool. Instead of reproducing a large
+verbatim `oldText` block (where weaker models drift on indentation/quotes),
+you emit only the changed lines plus a little surrounding context:
+
+```
+*** Begin Patch
+*** Update File: src/foo.ts
+@@ export function foo() {
+-  return 1;
++  return 2;
+*** End Patch
+```
+
+Rules:
+- `*** Add File: <path>` — one `+` line per content line (creates the file).
+- `*** Delete File: <path>` — no payload lines.
+- `*** Update File: <path>` — hunks; also `*** Update File: <old> → <new>` to rename.
+- Each Update hunk starts with a `@@ <unchanged context line>` anchor, then
+  `-` removed lines and `+` added lines. Leading-space context lines (` `) are
+  also accepted.
+- Context+removed must match **uniquely** in the file (diverges from Codex's
+  first-match for safety, matching `edit`'s philosophy). Add more context lines
+  if a match is ambiguous.
+- Matching is progressive-fuzzy (exact → strip-trailing-ws → strip-both-ws →
+  Unicode-normalize), so minor whitespace/Unicode differences still apply.
+
+DeepSeek and GLM are steered to prefer `apply_patch` for multi-line/multi-hunk
+edits; Claude/OpenAI keep using `edit` (they're already reliable with it).
+
+## Installation
+
 ```bash
 pi install npm:@bacnh85/pi-model-tools
 ```

package/extensions/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname, resolve as resolvePath } from "node:path";
 import {
   createBashToolDefinition,
@@ -9,7 +10,9 @@ import {
   createLsToolDefinition,
   createReadToolDefinition,
   createWriteToolDefinition,
+  defineTool,
 } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import {
   isRecord,
   detectFamily,
@@ -21,6 +24,16 @@ import {
   blockDangerousEnabled,
 } from "./lib/model-detection.ts";
 import { repairToolArguments, type RepairKind } from "./lib/tool-input-repair.ts";
+import {
+  stripReadContamination,
+  computeRetryEdit,
+  nearestBlock,
+  parseFailedEditIndex,
+  isEditMismatchError,
+  stripBom as stripBomStr,
+  normalizeToLF,
+} from "./lib/edit-repair.ts";
+import { parsePatch, applyPatchToFiles, PatchParseError } from "./lib/apply-patch.ts";
 import { stripReasoningContent, cleanLeakedContentFromMessages } from "./lib/reasoning-content.ts";
 import {
   looksLikeCodePath,
@@ -39,6 +52,7 @@ import {
   runTaskFirstToolHint,
   readUncertainPathHint,
   githubCloneFirstToolHint,
+  applyPatchPreferenceGuidance,
   selectionGuidanceEnabled,
   strictSerenaEnabled,
   superPowerModeEnabled,
@@ -60,14 +74,55 @@ function appendReadNote(result: any, note: unknown) {
   return { ...result, content: [...(Array.isArray(result?.content) ? result.content : []), { type: "text", text: note }] };
 }
 
+// Strip read-tool contamination notices from an edit's oldText fields. Mutates
+// in place and reports whether anything changed.
+function decontaminateEditArgs(args: any): boolean {
+  if (!isRecord(args)) return false;
+  const hasOld = Array.isArray(args.edits)
+    ? args.edits.some((e: any) => isRecord(e) && typeof e.oldText === "string")
+    : typeof args.oldText === "string";
+  if (!hasOld) return false;
+  let changed = false;
+  const clean = (s: string): string => {
+    const r = stripReadContamination(s);
+    if (r.changed) changed = true;
+    return r.text;
+  };
+  if (Array.isArray(args.edits)) {
+    for (const e of args.edits) if (isRecord(e) && typeof e.oldText === "string") e.oldText = clean(e.oldText);
+  }
+  if (typeof args.oldText === "string") args.oldText = clean(args.oldText);
+  return changed;
+}
+
+// Locate the file, read it, and report its (BOM-stripped, LF-normalized)
+// content for trim-tolerant retry. Returns null on any I/O problem.
+async function readFileForRetry(filePath: string, cwd: string): Promise<string | null> {
+  const abs = resolvePath(cwd, filePath);
+  try {
+    const buf = await readFile(abs);
+    return normalizeToLF(stripBomStr(buf.toString("utf-8")));
+  } catch {
+    return null;
+  }
+}
+
 function wrapToolDefinition(base: any, factory: (cwd: string) => any, shouldRepair: () => boolean, onRepair: (toolName: string, repairs: readonly RepairKind[]) => void): any {
   return {
     ...base,
     prepareArguments(args: unknown) {
       let prepared = base.prepareArguments ? base.prepareArguments(args as never) : args;
-      if (!shouldRepair()) return prepared;
-      const repaired = repairToolArguments(base.name, base.parameters, prepared);
-      if (repaired.repaired) { onRepair(base.name, repaired.repairs); prepared = repaired.args; }
+      if (shouldRepair()) {
+        const repaired = repairToolArguments(base.name, base.parameters, prepared);
+        if (repaired.repaired) { onRepair(base.name, repaired.repairs); prepared = repaired.args; }
+      }
+      // Strip read-tool contamination from edit oldText (always on — it's a
+      // safe, deterministic fix for the documented mismatch root cause).
+      if (base.name === "edit" && isRecord(prepared)) {
+        if (decontaminateEditArgs(prepared)) {
+          onRepair(base.name, ["read-notice-stripped"]);
+        }
+      }
       return base.name === "read" ? addReadDefaults(prepared) : prepared;
     },
     async execute(toolCallId: string, params: any, signal: AbortSignal | undefined, onUpdate: any, ctx: any) {
@@ -75,8 +130,51 @@ function wrapToolDefinition(base: any, factory: (cwd: string) => any, shouldRepa
       const freshDef = factory(cwd);
       const readNote = base.name === "read" && isRecord(params) ? params.__mtReadNote : undefined;
       if (isRecord(params)) delete params.__mtReadNote;
-      const result = await freshDef.execute(toolCallId, params, signal, onUpdate, ctx);
-      return base.name === "read" ? appendReadNote(result, readNote) : result;
+
+      if (base.name !== "edit") {
+        const result = await freshDef.execute(toolCallId, params, signal, onUpdate, ctx);
+        return base.name === "read" ? appendReadNote(result, readNote) : result;
+      }
+
+      // edit: try once; on a match-failure, retry once with trim-tolerant
+      // matching (copying actual file bytes) before giving up with a richer
+      // error that shows the nearest region.
+      try {
+        const result = await freshDef.execute(toolCallId, params, signal, onUpdate, ctx);
+        return result;
+      } catch (err: any) {
+        const message: string = err?.message ? String(err.message) : "";
+        if (!isEditMismatchError(message)) throw err;
+
+        const filePath = typeof params?.path === "string" ? params.path : "";
+        if (!filePath) throw err;
+        const fileContent = await readFileForRetry(filePath, cwd);
+        if (fileContent === null) throw err;
+
+        const edits: { oldText: string; newText: string }[] = Array.isArray(params?.edits) && params.edits.length > 0
+          ? params.edits
+          : (typeof params?.oldText === "string" ? [{ oldText: params.oldText, newText: params.newText }] : []);
+        if (edits.length === 0) throw err;
+
+        const retry = computeRetryEdit(fileContent, edits, parseFailedEditIndex(message));
+        if (retry) {
+          // Rebuild oldText from the file's real bytes (real indentation) so the
+          // core exact matcher succeeds; keep the model's newText as-is.
+          const fixedParams = { ...params };
+          if (Array.isArray(fixedParams.edits)) fixedParams.edits = retry.fixedEdits;
+          else fixedParams.oldText = retry.fixedEdits[0].oldText;
+          onRepair(base.name, ["trim-match-retry"]);
+          return await freshDef.execute(toolCallId, fixedParams, signal, onUpdate, ctx);
+        }
+
+        // Unresolvable: enrich the error with the nearest region so the model
+        // can copy verbatim on the next turn. categorizeToolError checks
+        // edit_mismatch before rate_limit/timeout for the edit tool, so a snippet
+        // containing 'timeout'/'429' cannot misclassify this.
+        const failing = edits[Math.min(parseFailedEditIndex(message), edits.length - 1)];
+        const nearest = failing ? nearestBlock(fileContent, stripReadContamination(failing.oldText).text) : "";
+        throw new Error(nearest ? `${message}\n\n${nearest}` : message);
+      }
     },
   };
 }
@@ -117,6 +215,51 @@ export default function (pi: ExtensionAPI) {
     }));
   }
 
+  // ── apply_patch: Codex-style diff/patch tool (robust for weak models) ──
+  pi.registerTool(defineTool({
+    name: "apply_patch",
+    label: "apply_patch",
+    description: [
+      "Apply a Codex-style V4D patch to edit one or more files. Emit only changed lines plus a little surrounding context (a small diff), which is easier to get right than reproducing a large verbatim block. Supported sections: `*** Add File: <path>` (only `+` lines), `*** Delete File: <path>` (no payload), `*** Update File: <path>` or `*** Update File: <old> → <new>` (rename). Inside an Update section, each hunk is preceded by a `@@` anchor line whose text is an unchanged context line, then `-` removed lines and `+` added lines. Leading-space context lines (` `) are also allowed. Context+removed must match UNIQUELY in the file. Wrap the whole patch in `*** Begin Patch` ... `*** End Patch`.",
+      "",
+      "Example:",
+      "*** Begin Patch", "*** Update File: src/foo.ts", "@@ export function foo()", "-  return 1", "+  return 2", "*** End Patch",
+    ].join("\n"),
+    promptSnippet: "Apply a diff/patch to edit one or more files (Codex V4D format)",
+    promptGuidelines: [
+      "Use apply_patch for multi-line or multi-file edits: emit a small diff (context + -/+ lines) instead of reproducing large verbatim oldText blocks.",
+      "Each Update hunk needs a unique anchor: include enough unchanged context lines so the context+removed block matches exactly once in the file.",
+      "For a single tiny one-line replacement, edit is fine; for anything larger or spanning multiple files, prefer apply_patch.",
+    ],
+    parameters: Type.Object({ patch: Type.String({ description: "The V4D patch text, wrapped in *** Begin Patch ... *** End Patch." }) }),
+    renderShell: "self",
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const cwd = ctx?.cwd || process.cwd();
+      let parsed;
+      try {
+        parsed = parsePatch(params.patch);
+      } catch (err) {
+        const msg = err instanceof PatchParseError ? err.message : String(err);
+        return { content: [{ type: "text", text: `Invalid patch: ${msg}` }], isError: true, details: undefined };
+      }
+      try {
+        const res = await applyPatchToFiles(parsed, cwd);
+        const summary = res.files.map((f) => {
+          if (f.kind === "add") return `Added ${f.path}`;
+          if (f.kind === "delete") return `Deleted ${f.path}`;
+          return `Updated ${f.path}`;
+        }).join("\n");
+        const exactness = res.exact ? "" : "\nNote: some hunks matched via fuzzy (whitespace/Unicode) normalization.";
+        return {
+          content: [{ type: "text", text: `${summary}${exactness}` }],
+          details: { diff: res.diff, files: res.files.map((f) => f.path) },
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }], isError: true, details: undefined };
+      }
+    },
+  }));
+
   // ── /model-tools-status ──
   pi.registerCommand("model-tools-status", {
     description: "Show pi-model-tools configuration, detected family, repair stats, and error history.",
@@ -201,6 +344,13 @@ export default function (pi: ExtensionAPI) {
       if (readHint) systemPrompt = `${systemPrompt}\n\n${readHint}`;
     }
 
+    // apply_patch preference — DeepSeek V4 Flash only (GLM is better with exact-match
+    // edit; apply_patch context anchors confuse it and it lacks agentic fallback).
+    if (activeFamily === "deepseek-v4") {
+      const patchHint = applyPatchPreferenceGuidance(activeForHint);
+      if (patchHint) systemPrompt = `${systemPrompt}\n\n${patchHint}`;
+    }
+
     // DeepSeek-only: Super Power Mode + verbose selection guidance (DeepSeek V4
     // needs the full steering block; GLM reaches 100% with prompt-aware hints alone).
     if (activeFamily === "deepseek-v4") {

package/extensions/lib/apply-patch.ts

@@ -0,0 +1,375 @@
+/**
+ * apply-patch.ts — Codex-style V4D patch parser + applier for the `apply_patch`
+ * tool. The model emits only `@@` context + `-`/`+` change lines (a small diff),
+ * which is far easier for weaker models to reproduce verbatim than a large
+ * str_replace oldText block.
+ *
+ * Format (mirrors OpenAI Codex `apply_patch`):
+ *   *** Begin Patch
+ *   *** Add File: path/to/new.txt
+ *   +content line 1
+ *   +content line 2
+ *   *** Delete File: path/to/old.txt
+ *   *** Update File: path/to/existing.ts
+ *   @@ context line (unchanged, for anchoring)
+ *   -removed line
+ *   +added line
+ *    unchanged context line (leading space preserved)
+ *   *** Update File: a.ts → b.ts   (rename)
+ *   *** End Patch
+ *
+ * Divergence from Codex: context+removed blocks must match UNIQUELY (Codex
+ * takes the first match). Silent wrong-location edits are worse than a clear
+ * error, and this matches pi's own `edit` philosophy.
+ */
+
+import { readFile, writeFile, unlink } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { generateUnifiedPatch, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+export type FileOpKind = "add" | "delete" | "update";
+
+export interface Hunk {
+  /** Ordered lines: context (with leading space stripped) + removed + added. */
+  context: string[];
+  removed: string[];
+  added: string[];
+}
+
+export interface FileOp {
+  kind: FileOpKind;
+  path: string;
+  /** For update-with-rename: the new path. */
+  movePath?: string;
+  hunks: Hunk[];
+}
+
+export interface ParsedPatch {
+  ops: FileOp[];
+}
+
+export class PatchParseError extends Error {}
+
+// ── Parser ──
+
+function stripLeadingSpace(line: string): string {
+  // In an update hunk, every payload line begins with a marker: ' ', '-', '+'.
+  // A literal leading space is the "context" marker and is part of the content.
+  return line.length > 0 ? line.slice(1) : "";
+}
+
+export function parsePatch(patch: string): ParsedPatch {
+  const lines = patch.split("\n");
+  const ops: FileOp[] = [];
+  let i = 0;
+
+  // Optional *** Begin Patch header.
+  if (i < lines.length && lines[i].trim() === "*** Begin Patch") i++;
+
+  let current: FileOp | null = null;
+  const finalize = () => { if (current) { ops.push(current); current = null; } };
+
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    if (trimmed === "*** End Patch") { finalize(); break; }
+    if (trimmed === "*** Begin Patch") continue;
+
+    if (trimmed.startsWith("*** ")) {
+      finalize();
+      current = parseFileHeader(trimmed);
+      continue;
+    }
+
+    if (!current) {
+      if (trimmed.length === 0) continue; // tolerate blank lines between ops
+      throw new PatchParseError(`Unexpected patch line outside a file section: ${JSON.stringify(line)}`);
+    }
+
+    // `@@ <text>` introduces a new hunk; the text after `@@ ` is the anchor
+    // context line. A bare `@@` just flushes/separates hunks.
+    if (line.startsWith("@@")) {
+      if (current.kind === "add") throw new PatchParseError("'@@' is invalid in an *** Add File section");
+      current.hunks.push({ context: [], removed: [], added: [] });
+      const anchor = line.slice(2);
+      if (anchor.startsWith(" ")) {
+        current.hunks[current.hunks.length - 1].context.push(anchor.slice(1));
+      } else if (anchor.length > 0) {
+        // tolerate `@@text` with no space
+        current.hunks[current.hunks.length - 1].context.push(anchor);
+      }
+      continue;
+    }
+
+    // Payload lines only valid inside update/add.
+    if (current.kind === "delete") {
+      throw new PatchParseError(`*** Delete File sections must not contain payload lines: ${JSON.stringify(line)}`);
+    }
+
+    if (line.startsWith("+")) {
+      // Add-File payload ('+' lines) and Update added-lines share this path;
+      // content is the text after the '+' marker.
+      current.hunks.push({ context: [], removed: [], added: [stripLeadingSpace(line)] });
+      continue;
+    }
+    if (line.startsWith("-")) {
+      if (current.kind === "add") throw new PatchParseError(`'-' lines are invalid in an *** Add File section`);
+      current.hunks.push({ context: [], removed: [], added: [] });
+      current.hunks[current.hunks.length - 1].removed.push(stripLeadingSpace(line));
+      continue;
+    }
+    // In an Add section, a blank line is a literal empty content line.
+    if (current.kind === "add" && line === "") {
+      current.hunks.push({ context: [], removed: [], added: [""] });
+      continue;
+    }
+    // Any other line in an Update section is context. Models frequently omit
+    // the leading-space context marker, so be lenient: treat the line verbatim.
+    // (In an Add section, only '+' lines are valid — anything else is an error.)
+    if (current.kind === "add") {
+      throw new PatchParseError(`Invalid Add File payload line (expected '+'): ${JSON.stringify(line)}`);
+    }
+    if (line.startsWith(" ")) {
+      current.hunks.push({ context: [], removed: [], added: [] });
+      current.hunks[current.hunks.length - 1].context.push(stripLeadingSpace(line));
+    } else {
+      current.hunks.push({ context: [], removed: [], added: [] });
+      current.hunks[current.hunks.length - 1].context.push(line);
+    }
+    continue;
+  }
+
+  finalize();
+  if (ops.length === 0) throw new PatchParseError("Patch contains no file operations.");
+  return { ops };
+}
+
+function parseFileHeader(header: string): FileOp {
+  // *** Add File: path   /   *** Delete File: path   /   *** Update File: path [→ newPath]
+  const addMatch = header.match(/^\*\*\* Add File:\s*(.+)$/);
+  if (addMatch) return { kind: "add", path: addMatch[1].trim(), hunks: [] };
+  const delMatch = header.match(/^\*\*\* Delete File:\s*(.+)$/);
+  if (delMatch) return { kind: "delete", path: delMatch[1].trim(), hunks: [] };
+  const updMatch = header.match(/^\*\*\* Update File:\s*(.+?)(?:\s*(?:->|→)\s*(.+))?$/);
+  if (updMatch) {
+    return { kind: "update", path: updMatch[1].trim(), movePath: updMatch[2]?.trim(), hunks: [] };
+  }
+  throw new PatchParseError(`Unrecognized file header: ${JSON.stringify(header)}`);
+}
+
+// ── Hunk assembly: collapse the marker-stream into ordered hunk groups ──
+
+interface AssembledHunk {
+  /** Lines before the first `-`/`+`: pure context (anchor). */
+  context: string[];
+  /** Removed + added payload, in emission order. */
+  removed: string[];
+  added: string[];
+}
+
+/** Merge adjacent context/removed/added markers into coherent hunks. */
+function assembleHunks(raw: Hunk[]): AssembledHunk[] {
+  const out: AssembledHunk[] = [];
+  let cur: AssembledHunk = { context: [], removed: [], added: [] };
+  let started = false;
+  const flush = () => {
+    if (started) out.push(cur);
+    cur = { context: [], removed: [], added: [] };
+    started = false;
+  };
+  for (const h of raw) {
+    if (h.context.length) {
+      if (started && (cur.removed.length || cur.added.length)) flush();
+      cur.context.push(...h.context);
+    }
+    if (h.removed.length || h.added.length) {
+      started = true;
+      cur.removed.push(...h.removed);
+      cur.added.push(...h.added);
+    }
+  }
+  if (started) out.push(cur);
+  return out;
+}
+
+// ── seekSequence: Codex's progressive fuzzy matcher (4 passes) ──
+
+function normalizeAscii(s: string): string {
+  return s.trim()
+    .replace(/[\u2010-\u2015\u2212]/g, "-")
+    .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+    .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+    .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
+}
+
+function eqExact(a: string, b: string) { return a === b; }
+function eqRstrip(a: string, b: string) { return a.trimEnd() === b.trimEnd(); }
+function eqTrim(a: string, b: string) { return a.trim() === b.trim(); }
+function eqUnicode(a: string, b: string) { return normalizeAscii(a) === normalizeAscii(b); }
+
+/**
+ * Count matches of `pattern` lines within `lines`, trying progressively
+ * lenient equality. Returns count and first start index under the strictest
+ * pass that yields any match.
+ */
+export function seekSequence(lines: string[], pattern: string[]): { count: number; firstIndex: number; exact: boolean } {
+  if (pattern.length === 0) return { count: 0, firstIndex: -1, exact: true };
+  if (pattern.length > lines.length) return { count: 0, firstIndex: -1, exact: true };
+  for (const eq of [eqExact, eqRstrip, eqTrim, eqUnicode]) {
+    let count = 0;
+    let firstIndex = -1;
+    for (let i = 0; i <= lines.length - pattern.length; i++) {
+      let ok = true;
+      for (let j = 0; j < pattern.length; j++) {
+        if (!eq(lines[i + j], pattern[j])) { ok = false; break; }
+      }
+      if (ok) {
+        count++;
+        if (firstIndex === -1) firstIndex = i;
+      }
+    }
+    if (count > 0) return { count, firstIndex, exact: eq === eqExact };
+  }
+  return { count: 0, firstIndex: -1, exact: true };
+}
+
+// ── Applier ──
+
+function stripBom(s: string): string { return s.startsWith("\uFEFF") ? s.slice(1) : s; }
+function normalizeLF(s: string): string { return s.replace(/\r\n/g, "\n").replace(/\r/g, "\n"); }
+function detectLineEnding(content: string): "\r\n" | "\n" {
+  const crlf = content.indexOf("\r\n");
+  const lf = content.indexOf("\n");
+  if (lf === -1) return "\n";
+  if (crlf === -1) return "\n";
+  return crlf < lf ? "\r\n" : "\n";
+}
+function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string {
+  return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+
+/** Resolve a patch path the same way pi's built-in tools do: relative paths
+ * resolve under cwd, absolute paths are honored anywhere. (pi's resolveToCwd
+ * does NOT restrict absolute paths to cwd; matching that behavior keeps
+ * apply_patch compatible with edits the model references by absolute path.) */
+function resolvePathLikePi(p: string, cwd: string): string {
+  const expanded = p.startsWith("~") ? (process.env.HOME ?? "") + p.slice(1) : p;
+  return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+}
+
+export interface AppliedFile {
+  path: string;
+  /** For updates: the before/after content for diffing. */
+  before?: string;
+  after?: string;
+  kind: FileOpKind;
+}
+
+export interface ApplyResult {
+  files: AppliedFile[];
+  /** false if any hunk matched only via fuzzy (non-exact) pass. */
+  exact: boolean;
+  /** Unified diff string across all updated files. */
+  diff: string;
+}
+
+/**
+ * Apply a parsed patch's ops to the filesystem under cwd. Requires unique
+ * context+removed matches for every update hunk. Returns per-file before/after
+ * and a combined unified diff.
+ */
+export async function applyPatchToFiles(parsed: ParsedPatch, cwd: string): Promise<ApplyResult> {
+  let exact = true;
+  const files: AppliedFile[] = [];
+  const diffParts: string[] = [];
+  const applied: string[] = [];
+
+  for (const op of parsed.ops) {
+    const abs = resolvePathLikePi(op.path, cwd);
+    try {
+      if (op.kind === "delete") {
+        const before = await withFileMutationQueue(abs, async () => {
+          const raw = await readOptional(abs);
+          if (raw === undefined) throw new Error(`Cannot delete (not found): ${op.path}`);
+          await unlink(abs);
+          return raw;
+        });
+        files.push({ path: op.path, before, after: "", kind: "delete" });
+        applied.push(op.path);
+        continue;
+      }
+
+      if (op.kind === "add") {
+        const content = op.hunks.map((h) => h.added.join("\n")).join("\n");
+        await withFileMutationQueue(abs, async () => {
+          if ((await readOptional(abs)) !== undefined) throw new Error(`Cannot add (already exists): ${op.path}`);
+          await writeFile(abs, content, "utf-8");
+        });
+        files.push({ path: op.path, before: "", after: content, kind: "add" });
+        applied.push(op.path);
+        continue;
+      }
+
+      // update
+      const destAbs = op.movePath ? resolvePathLikePi(op.movePath, cwd) : abs;
+      const { before, after } = await withFileMutationQueue(destAbs, async () => {
+        const raw = await readOptional(abs);
+        if (raw === undefined) throw new Error(`Cannot update (not found): ${op.path}`);
+        const bom = raw.startsWith("\uFEFF") ? "\uFEFF" : "";
+        const ending = detectLineEnding(stripBom(raw));
+        const beforeContent = normalizeLF(stripBom(raw));
+        const hunks = assembleHunks(op.hunks);
+
+        let work = beforeContent.split("\n");
+        const newHunks: { start: number; removedLen: number; added: string[] }[] = [];
+
+        for (const h of hunks) {
+          const anchor = [...h.context, ...h.removed];
+          const { count, firstIndex, exact: hExact } = seekSequence(work, anchor);
+          if (!hExact) exact = false;
+          if (count === 0) throw new Error(`Hunk context not found in ${op.path}. Ensure context lines match the file.`);
+          if (count > 1) throw new Error(`Hunk context is ambiguous (${count} matches) in ${op.path}. Add more surrounding context lines to make it unique.`);
+          const removedStart = firstIndex + h.context.length;
+          newHunks.push({ start: removedStart, removedLen: h.removed.length, added: h.added });
+        }
+
+        for (const h of [...newHunks].sort((a, b) => b.start - a.start)) {
+          work = [...work.slice(0, h.start), ...h.added, ...work.slice(h.start + h.removedLen)];
+        }
+
+        const afterContent = work.join("\n");
+        if (op.movePath && op.movePath !== op.path) {
+          if ((await readOptional(destAbs)) !== undefined) throw new Error(`Cannot rename onto existing file: ${op.movePath}`);
+          const outContent = bom + restoreLineEndings(afterContent, ending);
+          await unlink(abs);
+          await writeFile(destAbs, outContent, "utf-8");
+        } else {
+          const outContent = bom + restoreLineEndings(afterContent, ending);
+          await writeFile(abs, outContent, "utf-8");
+        }
+        return { before: beforeContent, after: afterContent };
+      });
+
+      files.push({ path: op.movePath ?? op.path, before, after, kind: "update" });
+      diffParts.push(generateUnifiedPatch(op.movePath ?? op.path, before, after));
+      applied.push(op.movePath ?? op.path);
+    } catch (err) {
+      // Report any files already applied before this op failed, so the model
+      // doesn't blindly re-apply the whole patch (and hit mismatches).
+      const appliedNote = applied.length > 0 ? ` (already applied: ${applied.join(", ")})` : "";
+      throw new Error(`${err instanceof Error ? err.message : String(err)}${appliedNote}`);
+    }
+  }
+
+  return { files, exact, diff: diffParts.join("\n").trimEnd() };
+}
+
+async function readOptional(abs: string): Promise<string | undefined> {
+  try {
+    const buf = await readFile(abs);
+    return buf.toString("utf-8");
+  } catch {
+    return undefined;
+  }
+}

package/extensions/lib/edit-repair.ts

@@ -0,0 +1,163 @@
+/**
+ * edit-repair.ts — helpers that harden the built-in `edit` tool against the
+ * two documented failure modes for weaker models:
+ *
+ *  1. read-tool contamination: `read` appends truncation/continuation notices
+ *     to file content; models copy them into oldText, where they don't exist
+ *     in the file → every match (exact and fuzzy) fails.
+ *  2. leading-whitespace drift: pi's matcher normalizes trailing whitespace
+ *     only; Codex's seek_sequence also tolerates leading-ws differences.
+ *
+ * Pure + testable. The wiring (prepareArguments/execute) lives in index.ts.
+ */
+
+/** Strip a UTF-8 BOM if present. */
+export function stripBom(content: string): string {
+  return content.startsWith("\uFEFF") ? content.slice(1) : content;
+}
+
+/** Normalize CRLF/CR to LF. */
+export function normalizeToLF(text: string): string {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+/**
+ * The exact read-tool notice patterns that contaminate oldText
+ * (see pi-coding-agent dist/core/tools/read.js).
+ * Each is anchored on its distinctive shape so it cannot match real source.
+ */
+const READ_CONTAMINATION_PATTERNS: RegExp[] = [
+  // [Showing lines A-B of C (50KB limit). Use offset=N to continue.]
+  /\n{1,2}\[Showing lines \d+-\d+ of \d+(?: \([^)]+\))?\.\s*Use offset=\d+ to continue\.\]/g,
+  // [N more lines in file. Use offset=N to continue.]
+  /\n{1,2}\[\d+ more lines in file\.\s*Use offset=\d+ to continue\.\]/g,
+  // [Line X is SIZE, exceeds 50KB limit. Use bash: sed -n ...]
+  /\n\[Line \d+ is [^,]+, exceeds [^\]]+ limit\.[^\]]*\]/g,
+];
+
+/**
+ * Strip read-tool contamination notices from an oldText string.
+ * Returns the cleaned text and whether anything changed.
+ * Safe: these notice shapes never legitimately appear inside matched source.
+ */
+export function stripReadContamination(text: string): { text: string; changed: boolean } {
+  let changed = false;
+  let out = text;
+  for (const re of READ_CONTAMINATION_PATTERNS) {
+    const next = out.replace(re, "");
+    if (next !== out) changed = true;
+    out = next;
+  }
+  return { text: out, changed };
+}
+
+function splitLines(content: string): string[] {
+  return content.length === 0 ? [] : content.split("\n");
+}
+
+/**
+ * Count contiguous block matches of oldText in content, tolerating
+ * per-line leading+trailing whitespace differences (Codex seek_sequence pass 3).
+ * Returns the number of matches and the start line of the first match.
+ */
+export function findTrimMatch(content: string, oldText: string): { count: number; firstIndex: number } {
+  const fileLines = splitLines(content).map((l) => l.trim());
+  const patternLines = splitLines(oldText).map((l) => l.trim());
+  // Drop a single trailing empty pattern line so a stray trailing newline in
+  // oldText doesn't break an otherwise-exact block match.
+  if (patternLines.length > 1 && patternLines[patternLines.length - 1] === "") patternLines.pop();
+  if (patternLines.length === 0 || patternLines.length > fileLines.length) return { count: 0, firstIndex: -1 };
+
+  let count = 0;
+  let firstIndex = -1;
+  for (let i = 0; i <= fileLines.length - patternLines.length; i++) {
+    let ok = true;
+    for (let j = 0; j < patternLines.length; j++) {
+      if (fileLines[i + j] !== patternLines[j]) { ok = false; break; }
+    }
+    if (ok) {
+      count++;
+      if (firstIndex === -1) firstIndex = i;
+    }
+  }
+  return { count, firstIndex };
+}
+
+/**
+ * Extract the ACTUAL file bytes for a matched block (with real indentation),
+ * given the content and the 0-based start line + block length. Used to rebuild
+ * oldText from the file so the core matcher's exact pass succeeds.
+ */
+export function fileBytesForBlock(content: string, startLine: number, blockLen: number): string {
+  const lines = splitLines(content);
+  return lines.slice(startLine, startLine + blockLen).join("\n");
+}
+
+/**
+ * Compute a retry edit set after a trim-tolerant re-match. Returns the rebuilt
+ * edits (oldText taken from the file's real bytes so the core exact matcher
+ * succeeds) when there is exactly one trim match, otherwise null. Pure/testable
+ * — the orchestration (read file, catch throw, retry) lives in index.ts.
+ *
+ * IMPORTANT: blockLen drops a single trailing empty line to stay in sync with
+ * findTrimMatch, which pops one trailing empty pattern line before matching.
+ */
+export function computeRetryEdit(fileContent: string, edits: { oldText: string; newText: string }[], failIdx: number): { fixedEdits: { oldText: string; newText: string }[] } | null {
+  const idx = Math.min(failIdx, edits.length - 1);
+  const failing = edits[idx];
+  const oldText = typeof failing?.oldText === "string" ? failing.oldText : "";
+  if (!oldText) return null;
+  const decontaminated = stripReadContamination(oldText).text;
+  const { count, firstIndex } = findTrimMatch(fileContent, decontaminated);
+  if (count !== 1) return null;
+  const patternLines = decontaminated.split("\n");
+  if (patternLines.length > 1 && patternLines[patternLines.length - 1] === "") patternLines.pop();
+  const realOld = fileBytesForBlock(fileContent, firstIndex, patternLines.length);
+  const fixedEdits = edits.map((e, i) => i === idx ? { ...e, oldText: realOld } : e);
+  return { fixedEdits };
+}
+
+/**
+ * Return a numbered snippet of the file region most similar to oldText, to help
+ * the model self-correct on an unresolvable mismatch. Picks the window with the
+ * most overlapping (trimmed) lines.
+ */
+export function nearestBlock(content: string, oldText: string, ctx = 6): string {
+  const fileLines = splitLines(content);
+  const patternSet = new Set(splitLines(oldText).map((l) => l.trim()).filter((l) => l.length > 0));
+  if (patternSet.size === 0 || fileLines.length === 0) return "";
+
+  const window = Math.max(ctx, Math.min(40, fileLines.length));
+  let bestStart = 0;
+  let bestScore = -1;
+  for (let i = 0; i <= fileLines.length - window; i++) {
+    let score = 0;
+    for (let j = 0; j < window; j++) {
+      if (patternSet.has(fileLines[i + j].trim())) score++;
+    }
+    if (score > bestScore) { bestScore = score; bestStart = i; }
+  }
+
+  const width = String(fileLines.length).length;
+  const start = Math.max(0, bestStart - 1);
+  const end = Math.min(fileLines.length, bestStart + window + 1);
+  const shown = fileLines.slice(start, end).map((l, idx) => {
+    const num = String(start + idx + 1).padStart(width, " ");
+    return `${num} | ${l}`;
+  });
+  return `Nearest matching region (lines ${start + 1}-${end}):\n${shown.join("\n")}`;
+}
+
+/**
+ * Parse the failing edit index from an edit-tool error message.
+ * Returns the 0-based index, or 0 when it can't be determined (single-edit).
+ */
+export function parseFailedEditIndex(message: string): number {
+  const m = message.match(/edits\[(\d+)\]/i);
+  return m ? Number(m[1]) : 0;
+}
+
+/** True if an error message/result indicates an edit match failure. */
+export function isEditMismatchError(message: string): boolean {
+  return /could not find|oldtext must match exactly|found \d+ occurrences|text must be unique|provide more context to make it unique/i.test(message);
+}

package/extensions/lib/guidance.ts

@@ -93,6 +93,24 @@ export function deepSeekSelectionGuidance(activeTools: readonly string[]): strin
   return result;
 }
 
+// ── apply_patch preference hint (DeepSeek/GLM) ──
+
+/**
+ * When apply_patch is available, tell weaker models to prefer it over edit for
+ * anything beyond a single tiny replacement. Returns undefined if the tool is
+ * not active so it never misdirects. Gated to DeepSeek/GLM by the caller (see
+ * index.ts before_agent_start), since Claude/OpenAI are already reliable with edit.
+ */
+export function applyPatchPreferenceGuidance(activeTools: readonly string[]): string | undefined {
+  if (!activeTools.includes("apply_patch")) return undefined;
+  return [
+    "apply_patch (preferred for non-trivial edits):",
+    "  • For multi-line, multi-hunk, or multi-file edits, emit a small V4D diff (context + -/+ lines) via apply_patch instead of reproducing large verbatim oldText blocks — far fewer match failures.",
+    "  • Each Update hunk must anchor on enough unchanged context that the context+removed block matches UNIQUELY in the file.",
+    "  • Keep using edit for a single tiny one-line exact replacement.",
+  ].join("\n");
+}
+
 // ── Prompt-aware first-tool hints ──
 
 /**

package/extensions/lib/shell-helpers.ts

@@ -133,9 +133,13 @@ export function categorizeToolError(toolName: string, errorResult: unknown): Err
   const text = (isRecord(errorResult) && Array.isArray(errorResult.content)
     ? errorResult.content.map((p) => isRecord(p) && typeof p.text === "string" ? p.text : "").join("\n")
     : String(errorResult ?? "")).toLowerCase();
+  // Edit mismatch is checked before rate_limit/timeout because an enriched edit error may
+  // append a nearest-region file snippet containing 'timeout'/'429'/'rate limit'
+  // strings (e.g. `const timeout = 5000;`, `if (status === 429)`), which would
+  // otherwise misclassify as timeout/rate_limit and give the wrong recovery hint.
+  if (toolName === "edit" && /could not find (?:edits|the exact text)|old ?text must match exactly|found \d+ occurrences|(?:old)?text must be unique|provide more context to make it unique/i.test(text)) return { category: "edit_mismatch", toolName, hint: "Edit requires exact unique matching. Read a narrow range, copy oldText verbatim, include surrounding lines." };
   if (/rate limit|429|too many requests|exceeded.*limit/i.test(text)) return { category: "rate_limit", toolName, hint: "Rate-limited. Wait before retrying or simplify the request." };
   if (/timed? ?out|timeout/i.test(text)) return { category: "timeout", toolName, hint: "Timed out. Use simpler inputs or reduce scope." };
-  if (/could not find edits|oldtext must match exactly|found \d+ occurrences|(?:old)?text must be unique|provide more context to make it unique/i.test(text)) return { category: "edit_mismatch", toolName, hint: "Edit requires exact unique matching. Read a narrow range, copy oldText verbatim, include surrounding lines." };
   if (/validation failed|invalid_type|required|missing.*(field|argument|property)/i.test(text)) return { category: "validation", toolName, hint: "Invalid arguments. Provide all required fields with correct types." };
   if (/enoent|no such file or directory|(?:file|path) not found/i.test(text)) return { category: "path_not_found", toolName, hint: "Path missing or guessed. Discover the exact path with find first." };
   if (/no such tool|unknown tool|is not a function|tool\s+\S+\s+(?:was\s+)?not found/i.test(text)) return { category: "tool_not_found", toolName, hint: "Use only exact Pi tool names. Never invent names like read_file." };

package/extensions/lib/tool-input-repair.ts

@@ -9,7 +9,7 @@
 import { Compile } from "typebox/compile";
 import { isRecord } from "./model-detection.ts";
 
-export type RepairKind = "path-markdown-autolink" | "optional-null" | "json-string" | "empty-object-array" | "bare-string-array" | "json-object-wrapped-array" | "top-level-json-string";
+export type RepairKind = "path-markdown-autolink" | "optional-null" | "json-string" | "empty-object-array" | "bare-string-array" | "json-object-wrapped-array" | "top-level-json-string" | "read-notice-stripped" | "trim-match-retry";
 
 export type RepairResult = {
   args: unknown;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@bacnh85/pi-model-tools",
-    "version": "0.2.0",
-    "description": "Unified tool-wrapping, argument repair, reasoning management, DeepSeek V4 guidance + Super Power Mode, and defensive leak-cleaning for DeepSeek V4 and GLM model families from any provider.",
+    "version": "0.3.0",
+    "description": "Unified tool-wrapping, argument repair, reasoning management, DeepSeek V4 guidance + Super Power Mode, defensive leak-cleaning, edit mismatch repair (read-notice stripping + trim-tolerant retry), and a Codex-style apply_patch diff tool for DeepSeek V4 and GLM model families from any provider.",
     "type": "module",
     "license": "MIT",
     "publishConfig": {
@@ -27,7 +27,10 @@
         "super-power",
         "selection-guidance",
         "agent-tools",
-        "reasoning"
+        "reasoning",
+        "apply-patch",
+        "diff-edit",
+        "edit-repair"
     ],
     "scripts": {
         "test": "node --import tsx --test extensions/test/unit/*.test.ts",