Resolve merge conflicts

2026-09-24 16:02:55 +08:00 · 2026-02-23 20:12:28 +01:00
parent 3bade78c16 0e76652f28
commit ae62fff98d
298 changed files with 15340 additions and 5719 deletions
@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test"
 import path from "path"
 import { BashTool } from "../../src/tool/bash"
 import { Instance } from "../../src/project/instance"
+import { Filesystem } from "../../src/util/filesystem"
 import { tmpdir } from "../fixture/fixture"
 import type { PermissionNext } from "../../src/permission/next"
 import { Truncate } from "../../src/tool/truncation"
@@ -388,7 +389,7 @@ describe("tool.bash truncation", () => {
        const filepath = (result.metadata as any).outputPath
        expect(filepath).toBeTruthy()

-        const saved = await Bun.file(filepath).text()
+        const saved = await Filesystem.readText(filepath)
        const lines = saved.trim().split("\n")
        expect(lines.length).toBe(lineCount)
        expect(lines[0]).toBe("1")
@@ -0,0 +1,496 @@
+import { describe, test, expect } from "bun:test"
+import path from "path"
+import fs from "fs/promises"
+import { EditTool } from "../../src/tool/edit"
+import { Instance } from "../../src/project/instance"
+import { tmpdir } from "../fixture/fixture"
+import { FileTime } from "../../src/file/time"
+
+const ctx = {
+  sessionID: "test-edit-session",
+  messageID: "",
+  callID: "",
+  agent: "build",
+  abort: AbortSignal.any([]),
+  messages: [],
+  metadata: () => {},
+  ask: async () => {},
+}
+
+describe("tool.edit", () => {
+  describe("creating new files", () => {
+    test("creates new file when oldString is empty", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "newfile.txt")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const edit = await EditTool.init()
+          const result = await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "",
+              newString: "new content",
+            },
+            ctx,
+          )
+
+          expect(result.metadata.diff).toContain("new content")
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("new content")
+        },
+      })
+    })
+
+    test("creates new file with nested directories", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "nested", "dir", "file.txt")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const edit = await EditTool.init()
+          await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "",
+              newString: "nested file",
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("nested file")
+        },
+      })
+    })
+
+    test("emits add event for new files", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "new.txt")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const { Bus } = await import("../../src/bus")
+          const { File } = await import("../../src/file")
+          const { FileWatcher } = await import("../../src/file/watcher")
+
+          const events: string[] = []
+          const unsubEdited = Bus.subscribe(File.Event.Edited, () => events.push("edited"))
+          const unsubUpdated = Bus.subscribe(FileWatcher.Event.Updated, () => events.push("updated"))
+
+          const edit = await EditTool.init()
+          await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "",
+              newString: "content",
+            },
+            ctx,
+          )
+
+          expect(events).toContain("edited")
+          expect(events).toContain("updated")
+          unsubEdited()
+          unsubUpdated()
+        },
+      })
+    })
+  })
+
+  describe("editing existing files", () => {
+    test("replaces text in existing file", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "existing.txt")
+      await fs.writeFile(filepath, "old content here", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const edit = await EditTool.init()
+          const result = await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "old content",
+              newString: "new content",
+            },
+            ctx,
+          )
+
+          expect(result.output).toContain("Edit applied successfully")
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("new content here")
+        },
+      })
+    })
+
+    test("throws error when file does not exist", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "nonexistent.txt")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const edit = await EditTool.init()
+          await expect(
+            edit.execute(
+              {
+                filePath: filepath,
+                oldString: "old",
+                newString: "new",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow("not found")
+        },
+      })
+    })
+
+    test("throws error when oldString equals newString", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "content", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const edit = await EditTool.init()
+          await expect(
+            edit.execute(
+              {
+                filePath: filepath,
+                oldString: "same",
+                newString: "same",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow("identical")
+        },
+      })
+    })
+
+    test("throws error when oldString not found in file", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "actual content", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const edit = await EditTool.init()
+          await expect(
+            edit.execute(
+              {
+                filePath: filepath,
+                oldString: "not in file",
+                newString: "replacement",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow()
+        },
+      })
+    })
+
+    test("throws error when file was not read first (FileTime)", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "content", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const edit = await EditTool.init()
+          await expect(
+            edit.execute(
+              {
+                filePath: filepath,
+                oldString: "content",
+                newString: "modified",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow("You must read file")
+        },
+      })
+    })
+
+    test("throws error when file has been modified since read", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "original content", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          // Read first
+          FileTime.read(ctx.sessionID, filepath)
+
+          // Wait a bit to ensure different timestamps
+          await new Promise((resolve) => setTimeout(resolve, 100))
+
+          // Simulate external modification
+          await fs.writeFile(filepath, "modified externally", "utf-8")
+
+          // Try to edit with the new content
+          const edit = await EditTool.init()
+          await expect(
+            edit.execute(
+              {
+                filePath: filepath,
+                oldString: "modified externally",
+                newString: "edited",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow("modified since it was last read")
+        },
+      })
+    })
+
+    test("replaces all occurrences with replaceAll option", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "foo bar foo baz foo", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const edit = await EditTool.init()
+          await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "foo",
+              newString: "qux",
+              replaceAll: true,
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("qux bar qux baz qux")
+        },
+      })
+    })
+
+    test("emits change event for existing files", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "original", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const { Bus } = await import("../../src/bus")
+          const { File } = await import("../../src/file")
+          const { FileWatcher } = await import("../../src/file/watcher")
+
+          const events: string[] = []
+          const unsubEdited = Bus.subscribe(File.Event.Edited, () => events.push("edited"))
+          const unsubUpdated = Bus.subscribe(FileWatcher.Event.Updated, () => events.push("updated"))
+
+          const edit = await EditTool.init()
+          await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "original",
+              newString: "modified",
+            },
+            ctx,
+          )
+
+          expect(events).toContain("edited")
+          expect(events).toContain("updated")
+          unsubEdited()
+          unsubUpdated()
+        },
+      })
+    })
+  })
+
+  describe("edge cases", () => {
+    test("handles multiline replacements", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "line1\nline2\nline3", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const edit = await EditTool.init()
+          await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "line2",
+              newString: "new line 2\nextra line",
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("line1\nnew line 2\nextra line\nline3")
+        },
+      })
+    })
+
+    test("handles CRLF line endings", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "line1\r\nold\r\nline3", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const edit = await EditTool.init()
+          await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "old",
+              newString: "new",
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("line1\r\nnew\r\nline3")
+        },
+      })
+    })
+
+    test("throws error when oldString equals newString", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "content", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const edit = await EditTool.init()
+          await expect(
+            edit.execute(
+              {
+                filePath: filepath,
+                oldString: "",
+                newString: "",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow("identical")
+        },
+      })
+    })
+
+    test("throws error when path is directory", async () => {
+      await using tmp = await tmpdir()
+      const dirpath = path.join(tmp.path, "adir")
+      await fs.mkdir(dirpath)
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, dirpath)
+
+          const edit = await EditTool.init()
+          await expect(
+            edit.execute(
+              {
+                filePath: dirpath,
+                oldString: "old",
+                newString: "new",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow("directory")
+        },
+      })
+    })
+
+    test("tracks file diff statistics", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "line1\nline2\nline3", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const edit = await EditTool.init()
+          const result = await edit.execute(
+            {
+              filePath: filepath,
+              oldString: "line2",
+              newString: "new line a\nnew line b",
+            },
+            ctx,
+          )
+
+          expect(result.metadata.filediff).toBeDefined()
+          expect(result.metadata.filediff.file).toBe(filepath)
+          expect(result.metadata.filediff.additions).toBeGreaterThan(0)
+        },
+      })
+    })
+  })
+
+  describe("concurrent editing", () => {
+    test("serializes concurrent edits to same file", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "0", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          FileTime.read(ctx.sessionID, filepath)
+
+          const edit = await EditTool.init()
+
+          // Two concurrent edits
+          const promise1 = edit.execute(
+            {
+              filePath: filepath,
+              oldString: "0",
+              newString: "1",
+            },
+            ctx,
+          )
+
+          // Need to read again since FileTime tracks per-session
+          FileTime.read(ctx.sessionID, filepath)
+
+          const promise2 = edit.execute(
+            {
+              filePath: filepath,
+              oldString: "0",
+              newString: "2",
+            },
+            ctx,
+          )
+
+          // Both should complete without error (though one might fail due to content mismatch)
+          const results = await Promise.allSettled([promise1, promise2])
+          expect(results.some((r) => r.status === "fulfilled")).toBe(true)
+        },
+      })
+    })
+  })
+})
@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test"
 import path from "path"
 import { ReadTool } from "../../src/tool/read"
 import { Instance } from "../../src/project/instance"
+import { Filesystem } from "../../src/util/filesystem"
 import { tmpdir } from "../fixture/fixture"
 import { PermissionNext } from "../../src/permission/next"
 import { Agent } from "../../src/agent/agent"
@@ -201,10 +202,10 @@ describe("tool.read truncation", () => {
  test("truncates large file by bytes and sets truncated metadata", async () => {
    await using tmp = await tmpdir({
      init: async (dir) => {
-        const base = await Bun.file(path.join(FIXTURES_DIR, "models-api.json")).text()
+        const base = await Filesystem.readText(path.join(FIXTURES_DIR, "models-api.json"))
        const target = 60 * 1024
        const content = base.length >= target ? base : base.repeat(Math.ceil(target / base.length))
-        await Bun.write(path.join(dir, "large.json"), content)
+        await Filesystem.write(path.join(dir, "large.json"), content)
      },
    })
    await Instance.provide({
@@ -213,8 +214,8 @@ describe("tool.read truncation", () => {
        const read = await ReadTool.init()
        const result = await read.execute({ filePath: path.join(tmp.path, "large.json") }, ctx)
        expect(result.metadata.truncated).toBe(true)
-        expect(result.output).toContain("Output truncated at")
-        expect(result.output).toContain("bytes")
+        expect(result.output).toContain("Output capped at")
+        expect(result.output).toContain("Use offset=")
      },
    })
  })
@@ -232,7 +233,8 @@ describe("tool.read truncation", () => {
        const read = await ReadTool.init()
        const result = await read.execute({ filePath: path.join(tmp.path, "many-lines.txt"), limit: 10 }, ctx)
        expect(result.metadata.truncated).toBe(true)
-        expect(result.output).toContain("File has more lines")
+        expect(result.output).toContain("Showing lines 1-10 of 100")
+        expect(result.output).toContain("Use offset=11")
        expect(result.output).toContain("line0")
        expect(result.output).toContain("line9")
        expect(result.output).not.toContain("line10")
@@ -269,6 +271,10 @@ describe("tool.read truncation", () => {
      fn: async () => {
        const read = await ReadTool.init()
        const result = await read.execute({ filePath: path.join(tmp.path, "offset.txt"), offset: 10, limit: 5 }, ctx)
+        expect(result.output).toContain("10: line10")
+        expect(result.output).toContain("14: line14")
+        expect(result.output).not.toContain("9: line10")
+        expect(result.output).not.toContain("15: line15")
        expect(result.output).toContain("line10")
        expect(result.output).toContain("line14")
        expect(result.output).not.toContain("line0")
@@ -295,6 +301,40 @@ describe("tool.read truncation", () => {
    })
  })

+  test("allows reading empty file at default offset", async () => {
+    await using tmp = await tmpdir({
+      init: async (dir) => {
+        await Bun.write(path.join(dir, "empty.txt"), "")
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const read = await ReadTool.init()
+        const result = await read.execute({ filePath: path.join(tmp.path, "empty.txt") }, ctx)
+        expect(result.metadata.truncated).toBe(false)
+        expect(result.output).toContain("End of file - total 0 lines")
+      },
+    })
+  })
+
+  test("throws when offset > 1 for empty file", async () => {
+    await using tmp = await tmpdir({
+      init: async (dir) => {
+        await Bun.write(path.join(dir, "empty.txt"), "")
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const read = await ReadTool.init()
+        await expect(read.execute({ filePath: path.join(tmp.path, "empty.txt"), offset: 2 }, ctx)).rejects.toThrow(
+          "Offset 2 is out of range for this file (0 lines)",
+        )
+      },
+    })
+  })
+
  test("does not mark final directory page as truncated", async () => {
    await using tmp = await tmpdir({
      init: async (dir) => {
@@ -326,7 +366,7 @@ describe("tool.read truncation", () => {
      fn: async () => {
        const read = await ReadTool.init()
        const result = await read.execute({ filePath: path.join(tmp.path, "long-line.txt") }, ctx)
-        expect(result.output).toContain("...")
+        expect(result.output).toContain("(line truncated to 2000 chars)")
        expect(result.output.length).toBeLessThan(3000)
      },
    })
@@ -351,6 +391,9 @@ describe("tool.read truncation", () => {
        expect(result.metadata.truncated).toBe(false)
        expect(result.attachments).toBeDefined()
        expect(result.attachments?.length).toBe(1)
+        expect(result.attachments?.[0]).not.toHaveProperty("id")
+        expect(result.attachments?.[0]).not.toHaveProperty("sessionID")
+        expect(result.attachments?.[0]).not.toHaveProperty("messageID")
      },
    })
  })
@@ -365,6 +408,9 @@ describe("tool.read truncation", () => {
        expect(result.attachments).toBeDefined()
        expect(result.attachments?.length).toBe(1)
        expect(result.attachments?.[0].type).toBe("file")
+        expect(result.attachments?.[0]).not.toHaveProperty("id")
+        expect(result.attachments?.[0]).not.toHaveProperty("sessionID")
+        expect(result.attachments?.[0]).not.toHaveProperty("messageID")
      },
    })
  })
@@ -421,3 +467,40 @@ describe("tool.read loaded instructions", () => {
    })
  })
 })
+
+describe("tool.read binary detection", () => {
+  test("rejects text extension files with null bytes", async () => {
+    await using tmp = await tmpdir({
+      init: async (dir) => {
+        const bytes = Buffer.from([0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x00, 0x77, 0x6f, 0x72, 0x6c, 0x64])
+        await Bun.write(path.join(dir, "null-byte.txt"), bytes)
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const read = await ReadTool.init()
+        await expect(read.execute({ filePath: path.join(tmp.path, "null-byte.txt") }, ctx)).rejects.toThrow(
+          "Cannot read binary file",
+        )
+      },
+    })
+  })
+
+  test("rejects known binary extensions", async () => {
+    await using tmp = await tmpdir({
+      init: async (dir) => {
+        await Bun.write(path.join(dir, "module.wasm"), "not really wasm")
+      },
+    })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const read = await ReadTool.init()
+        await expect(read.execute({ filePath: path.join(tmp.path, "module.wasm") }, ctx)).rejects.toThrow(
+          "Cannot read binary file",
+        )
+      },
+    })
+  })
+})
@@ -1,6 +1,7 @@
 import { describe, test, expect, afterAll } from "bun:test"
 import { Truncate } from "../../src/tool/truncation"
 import { Identifier } from "../../src/id/id"
+import { Filesystem } from "../../src/util/filesystem"
 import fs from "fs/promises"
 import path from "path"

@@ -9,7 +10,7 @@ const FIXTURES_DIR = path.join(import.meta.dir, "fixtures")
 describe("Truncate", () => {
  describe("output", () => {
    test("truncates large json file by bytes", async () => {
-      const content = await Bun.file(path.join(FIXTURES_DIR, "models-api.json")).text()
+      const content = await Filesystem.readText(path.join(FIXTURES_DIR, "models-api.json"))
      const result = await Truncate.output(content)

      expect(result.truncated).toBe(true)
@@ -69,7 +70,7 @@ describe("Truncate", () => {
    })

    test("large single-line file truncates with byte message", async () => {
-      const content = await Bun.file(path.join(FIXTURES_DIR, "models-api.json")).text()
+      const content = await Filesystem.readText(path.join(FIXTURES_DIR, "models-api.json"))
      const result = await Truncate.output(content)

      expect(result.truncated).toBe(true)
@@ -88,7 +89,7 @@ describe("Truncate", () => {
      expect(result.outputPath).toBeDefined()
      expect(result.outputPath).toContain("tool_")

-      const written = await Bun.file(result.outputPath).text()
+      const written = await Filesystem.readText(result.outputPath!)
      expect(written).toBe(lines)
    })

@@ -139,21 +140,21 @@ describe("Truncate", () => {
      const oldTimestamp = Date.now() - 10 * DAY_MS
      const oldId = Identifier.create("tool", false, oldTimestamp)
      oldFile = path.join(Truncate.DIR, oldId)
-      await Bun.write(Bun.file(oldFile), "old content")
+      await Filesystem.write(oldFile, "old content")

      // Create a recent file (3 days ago)
      const recentTimestamp = Date.now() - 3 * DAY_MS
      const recentId = Identifier.create("tool", false, recentTimestamp)
      recentFile = path.join(Truncate.DIR, recentId)
-      await Bun.write(Bun.file(recentFile), "recent content")
+      await Filesystem.write(recentFile, "recent content")

      await Truncate.cleanup()

      // Old file should be deleted
-      expect(await Bun.file(oldFile).exists()).toBe(false)
+      expect(await Filesystem.exists(oldFile)).toBe(false)

      // Recent file should still exist
-      expect(await Bun.file(recentFile).exists()).toBe(true)
+      expect(await Filesystem.exists(recentFile)).toBe(true)
    })
  })
 })
@@ -46,6 +46,9 @@ describe("tool.webfetch", () => {
            expect(result.attachments?.[0].type).toBe("file")
            expect(result.attachments?.[0].mime).toBe("image/png")
            expect(result.attachments?.[0].url.startsWith("data:image/png;base64,")).toBe(true)
+            expect(result.attachments?.[0]).not.toHaveProperty("id")
+            expect(result.attachments?.[0]).not.toHaveProperty("sessionID")
+            expect(result.attachments?.[0]).not.toHaveProperty("messageID")
          },
        })
      },
@@ -0,0 +1,341 @@
+import { describe, test, expect } from "bun:test"
+import path from "path"
+import fs from "fs/promises"
+import { WriteTool } from "../../src/tool/write"
+import { Instance } from "../../src/project/instance"
+import { tmpdir } from "../fixture/fixture"
+
+const ctx = {
+  sessionID: "test-write-session",
+  messageID: "",
+  callID: "",
+  agent: "build",
+  abort: AbortSignal.any([]),
+  messages: [],
+  metadata: () => {},
+  ask: async () => {},
+}
+
+describe("tool.write", () => {
+  describe("new file creation", () => {
+    test("writes content to new file", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "newfile.txt")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          const result = await write.execute(
+            {
+              filePath: filepath,
+              content: "Hello, World!",
+            },
+            ctx,
+          )
+
+          expect(result.output).toContain("Wrote file successfully")
+          expect(result.metadata.exists).toBe(false)
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("Hello, World!")
+        },
+      })
+    })
+
+    test("creates parent directories if needed", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "nested", "deep", "file.txt")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await write.execute(
+            {
+              filePath: filepath,
+              content: "nested content",
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("nested content")
+        },
+      })
+    })
+
+    test("handles relative paths by resolving to instance directory", async () => {
+      await using tmp = await tmpdir()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await write.execute(
+            {
+              filePath: "relative.txt",
+              content: "relative content",
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(path.join(tmp.path, "relative.txt"), "utf-8")
+          expect(content).toBe("relative content")
+        },
+      })
+    })
+  })
+
+  describe("existing file overwrite", () => {
+    test("overwrites existing file content", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "existing.txt")
+      await fs.writeFile(filepath, "old content", "utf-8")
+
+      // First read the file to satisfy FileTime requirement
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const { FileTime } = await import("../../src/file/time")
+          FileTime.read(ctx.sessionID, filepath)
+
+          const write = await WriteTool.init()
+          const result = await write.execute(
+            {
+              filePath: filepath,
+              content: "new content",
+            },
+            ctx,
+          )
+
+          expect(result.output).toContain("Wrote file successfully")
+          expect(result.metadata.exists).toBe(true)
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("new content")
+        },
+      })
+    })
+
+    test("returns diff in metadata for existing files", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "old", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const { FileTime } = await import("../../src/file/time")
+          FileTime.read(ctx.sessionID, filepath)
+
+          const write = await WriteTool.init()
+          const result = await write.execute(
+            {
+              filePath: filepath,
+              content: "new",
+            },
+            ctx,
+          )
+
+          // Diff should be in metadata
+          expect(result.metadata).toHaveProperty("filepath", filepath)
+          expect(result.metadata).toHaveProperty("exists", true)
+        },
+      })
+    })
+  })
+
+  describe("file permissions", () => {
+    test("sets file permissions when writing sensitive data", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "sensitive.json")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await write.execute(
+            {
+              filePath: filepath,
+              content: JSON.stringify({ secret: "data" }),
+            },
+            ctx,
+          )
+
+          // On Unix systems, check permissions
+          if (process.platform !== "win32") {
+            const stats = await fs.stat(filepath)
+            expect(stats.mode & 0o777).toBe(0o644)
+          }
+        },
+      })
+    })
+  })
+
+  describe("content types", () => {
+    test("writes JSON content", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "data.json")
+      const data = { key: "value", nested: { array: [1, 2, 3] } }
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await write.execute(
+            {
+              filePath: filepath,
+              content: JSON.stringify(data, null, 2),
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(JSON.parse(content)).toEqual(data)
+        },
+      })
+    })
+
+    test("writes binary-safe content", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "binary.bin")
+      const content = "Hello\x00World\x01\x02\x03"
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await write.execute(
+            {
+              filePath: filepath,
+              content,
+            },
+            ctx,
+          )
+
+          const buf = await fs.readFile(filepath)
+          expect(buf.toString()).toBe(content)
+        },
+      })
+    })
+
+    test("writes empty content", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "empty.txt")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await write.execute(
+            {
+              filePath: filepath,
+              content: "",
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe("")
+
+          const stats = await fs.stat(filepath)
+          expect(stats.size).toBe(0)
+        },
+      })
+    })
+
+    test("writes multi-line content", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "multiline.txt")
+      const lines = ["Line 1", "Line 2", "Line 3", ""].join("\n")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await write.execute(
+            {
+              filePath: filepath,
+              content: lines,
+            },
+            ctx,
+          )
+
+          const content = await fs.readFile(filepath, "utf-8")
+          expect(content).toBe(lines)
+        },
+      })
+    })
+
+    test("handles different line endings", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "crlf.txt")
+      const content = "Line 1\r\nLine 2\r\nLine 3"
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await write.execute(
+            {
+              filePath: filepath,
+              content,
+            },
+            ctx,
+          )
+
+          const buf = await fs.readFile(filepath)
+          expect(buf.toString()).toBe(content)
+        },
+      })
+    })
+  })
+
+  describe("error handling", () => {
+    test("throws error for paths outside project", async () => {
+      await using tmp = await tmpdir()
+      const outsidePath = "/etc/passwd"
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          await expect(
+            write.execute(
+              {
+                filePath: outsidePath,
+                content: "test",
+              },
+              ctx,
+            ),
+          ).rejects.toThrow()
+        },
+      })
+    })
+  })
+
+  describe("title generation", () => {
+    test("returns relative path as title", async () => {
+      await using tmp = await tmpdir()
+      const filepath = path.join(tmp.path, "src", "components", "Button.tsx")
+      await fs.mkdir(path.dirname(filepath), { recursive: true })
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const write = await WriteTool.init()
+          const result = await write.execute(
+            {
+              filePath: filepath,
+              content: "export const Button = () => {}",
+            },
+            ctx,
+          )
+
+          expect(result.title).toEndWith(path.join("src", "components", "Button.tsx"))
+        },
+      })
+    })
+  })
+})