fix: preserve files during fuzzy edits (#51)

Author: agent-think[bot]

.changeset/quiet-files-stay.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/computer": patch
+---
+
+Preserve untargeted file content when the `edit` tool falls back to fuzzy matching.

docs/09_tool_interface.md

@@ -219,7 +219,9 @@ The schema is:
 }
 ```
 
-Every `oldText` must identify one unique, non-overlapping range in the original content. The tool applies the batch atomically, preserves the byte order mark, line ending style, and file mode, and returns a unified patch plus `firstChangedLine`.
+Every `oldText` must identify one unique, non-overlapping range in the original content. Exact matching is tried first. If that misses, the tool can locate the range after NFKC normalization, trailing-whitespace trimming, and common quote, dash, and space folding. Fuzzy normalization is lookup-only: the replacement is spliced into the original text, so content outside the matched range stays unchanged and the returned diff describes the bytes written. A fuzzy match whose normalized boundary cannot map unambiguously to the source is rejected; copy a larger exact range in that case.
+
+The tool applies the batch atomically, preserves the byte order mark, line ending style, and file mode, and returns a unified patch plus `firstChangedLine`.
 
 `edit`, `write`, and `delete` share locks through the store's stable `lockIdentity`. Every `WorkspaceFileStore` over the same `workspace.fs` uses the same identity, including adapters created by separate `createAITools()` calls. A write cannot land between edit's read and write phases, while unrelated workspaces and paths remain independent. Recursive deletion also locks the whole subtree, so mutations to ancestors or descendants cannot interleave with it.
 

packages/computer/README.md

@@ -295,9 +295,11 @@ next call to avoid transferring the same bytes again. Eligible image and
 PDF bytes are captured once during the bounded tool execution and returned
 as AI SDK `file` model output without re-reading the file. SVG source remains
 text. `ls`, `find`, and `grep` pass pagination through to the storage layer
-and return `nextOffset` when more results exist. File mutations share
-locks across tool sets for the same workspace, and recursive deletion
-excludes mutations throughout its subtree. See
+and return `nextOffset` when more results exist. `edit` falls back to
+Unicode- and whitespace-tolerant matching while splicing replacements into
+the original text, so untargeted content stays byte-for-byte unchanged. File
+mutations share locks across tool sets for the same workspace, and recursive
+deletion excludes mutations throughout its subtree. See
 [`docs/09_tool_interface.md`](../../docs/09_tool_interface.md).
 
 ## Git

packages/computer/src/tools/ai.test.ts

@@ -386,6 +386,27 @@ describe("createAITools filesystem tools", () => {
     );
   });
 
+  it("preserves untargeted bytes when an edit uses fuzzy matching", async () => {
+    const workspace = makeWorkspace();
+    const tools = createAITools({ workspace });
+    const original = "The spec says “must” — not optional.  \nlet target = 1;\n";
+    await workspace.fs.mkdir("/workspace", { recursive: true });
+    await workspace.fs.writeFile("/workspace/notes.md", original);
+
+    const result = await executeTool(tools.edit, {
+      path: "/workspace/notes.md",
+      edits: [{ oldText: "let target = 1; ", newText: "let target = 2;" }],
+    });
+
+    await expect(workspace.fs.readFile("/workspace/notes.md", "utf8")).resolves.toBe(
+      original.replace("let target = 1;", "let target = 2;"),
+    );
+    expect(result).toMatchObject({
+      diff: expect.not.stringContaining('The spec says "must" - not optional.'),
+      patch: expect.stringContaining("+let target = 2;"),
+    });
+  });
+
   it("paginates ls results and reports a continuation offset", async () => {
     const workspace = makeWorkspace();
     await workspace.fs.mkdir("/workspace", { recursive: true });

packages/computer/src/tools/fs/edit-diff.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import { applyEditsToNormalizedContent, fuzzyFindText } from "./edit-diff.js";
+
+const path = "/workspace/notes.md";
+
+describe("fuzzy edit source mapping", () => {
+  it("preserves every byte outside the fuzzy-matched span", () => {
+    const original =
+      "The spec says “must” — not optional.  \n" +
+      "ligature: file; fraction: ½; space: a b\n" +
+      "let target = 1;\n";
+
+    expect(
+      applyEditsToNormalizedContent(
+        original,
+        [{ oldText: "let target = 1; ", newText: "let target = 2;" }],
+        path,
+      ),
+    ).toEqual({
+      baseContent: original,
+      newContent: original.replace("let target = 1;", "let target = 2;"),
+    });
+  });
+
+  it("mixes exact and fuzzy edits in original-content coordinates", () => {
+    const original = "keep “this” — unchanged  \nconst exact = 1;\nconst fuzzy = 2;\n";
+
+    expect(
+      applyEditsToNormalizedContent(
+        original,
+        [
+          { oldText: "const exact = 1;", newText: "const exact = 3;" },
+          { oldText: "const fuzzy = 2;", newText: "const fuzzy = 4;" },
+        ],
+        path,
+      ).newContent,
+    ).toBe("keep “this” — unchanged  \nconst exact = 3;\nconst fuzzy = 4;\n");
+  });
+
+  it("maps a complete NFKC expansion back to its source character", () => {
+    expect(
+      applyEditsToNormalizedContent(
+        "const value = fi;\n",
+        [{ oldText: "fi", newText: "pair" }],
+        path,
+      ).newContent,
+    ).toBe("const value = pair;\n");
+  });
+
+  it("maps a complete combining sequence and preserves supplementary characters", () => {
+    const original = "const café = 1; // 🙂\n";
+
+    expect(
+      applyEditsToNormalizedContent(
+        original,
+        [{ oldText: "const café = 1;", newText: "const cafe = 2;" }],
+        path,
+      ).newContent,
+    ).toBe("const cafe = 2; // 🙂\n");
+  });
+
+  it("rejects a match that ends inside an NFKC expansion", () => {
+    expect(() =>
+      applyEditsToNormalizedContent("const value = fi;\n", [{ oldText: "f", newText: "x" }], path),
+    ).toThrow(/ambiguous Unicode-normalization or trimmed-whitespace boundary/);
+  });
+
+  it("rejects a fuzzy edit when normalization makes multiple matches ambiguous", () => {
+    expect(() =>
+      applyEditsToNormalizedContent(
+        "const value = 1;\nconst value = 1;\n",
+        [{ oldText: "const value = 1; ", newText: "updated" }],
+        path,
+      ),
+    ).toThrow(/Found 2 occurrences/);
+  });
+
+  it("uses a later safe match when an earlier normalized occurrence has an unsafe boundary", () => {
+    expect(
+      applyEditsToNormalizedContent("fi\nf\n", [{ oldText: "f", newText: "x" }], path).newContent,
+    ).toBe("fi\nx\n");
+  });
+
+  it("rejects a match that starts inside an NFKC expansion", () => {
+    expect(() =>
+      applyEditsToNormalizedContent("const value = fi;\n", [{ oldText: "i", newText: "x" }], path),
+    ).toThrow(/ambiguous Unicode-normalization or trimmed-whitespace boundary/);
+  });
+
+  it("preserves trailing whitespace adjacent to a fuzzy span", () => {
+    expect(
+      applyEditsToNormalizedContent(
+        "const value = 1;  ",
+        [{ oldText: "const value = 1;", newText: "const value = 2;" }],
+        path,
+      ).newContent,
+    ).toBe("const value = 2;  ");
+  });
+
+  it("preserves trailing whitespace before a fuzzy span that starts with a newline", () => {
+    expect(
+      applyEditsToNormalizedContent(
+        "header   \nfoo “x”;\n",
+        [{ oldText: '\nfoo "x";', newText: '\nfoo "y";' }],
+        path,
+      ).newContent,
+    ).toBe('header   \nfoo "y";\n');
+  });
+
+  it("does not treat an exact match as a fuzzy duplicate", () => {
+    expect(
+      applyEditsToNormalizedContent(
+        "foo();  \nfoo();\n",
+        [{ oldText: "foo();\n", newText: "bar();\n" }],
+        path,
+      ).newContent,
+    ).toBe("foo();  \nbar();\n");
+  });
+
+  it("preserves trailing whitespace after a multiline fuzzy span", () => {
+    expect(
+      applyEditsToNormalizedContent(
+        "first line\nsecond line  \nafter  \n",
+        [{ oldText: "first line\nsecond line", newText: "combined" }],
+        path,
+      ).newContent,
+    ).toBe("combined  \nafter  \n");
+  });
+
+  it("replaces a fuzzy match that ends at EOF after an earlier trimmed line", () => {
+    expect(
+      applyEditsToNormalizedContent(
+        "keep trailing spaces   \ntarget value",
+        [{ oldText: "target value", newText: "updated" }],
+        path,
+      ).newContent,
+    ).toBe("keep trailing spaces   \nupdated");
+  });
+
+  it("rejects a fuzzy edit when grapheme-local NFKC differs from whole-string NFKC", () => {
+    expect(() =>
+      applyEditsToNormalizedContent(
+        "ㄱᅡ value\n",
+        [{ oldText: "가 value", newText: "updated" }],
+        path,
+      ),
+    ).toThrow(/ambiguous Unicode-normalization or trimmed-whitespace boundary/);
+  });
+
+  it("replaces an entire grapheme even when whole-string NFKC composes it", () => {
+    expect(
+      applyEditsToNormalizedContent("Ångstrom\n", [{ oldText: "Å", newText: "A" }], path)
+        .newContent,
+    ).toBe("Angstrom\n");
+  });
+
+  it("maps fuzzy matches after supplementary characters", () => {
+    const content = "🙂 before; const value = 1; after\n";
+    const match = fuzzyFindText(content, "const value = 1;");
+
+    expect(match).toMatchObject({
+      found: true,
+      index: content.indexOf("const value"),
+      matchLength: "const value = 1;".length,
+      usedFuzzyMatch: true,
+    });
+  });
+});