File Tools

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.NoSuchFileException;
import java.nio.file.Path;
import java.util.Comparator;

public class PathConfinement {
    static final class Workspace {
        final Path root;
        Workspace(Path root) throws IOException { this.root = root.toRealPath(); }

        Path resolve(String userPath) throws IOException {
            if (userPath == null || userPath.isBlank()) throw new IllegalArgumentException("empty path");
            Path p = root.resolve(userPath).normalize();          // an absolute userPath replaces root here
            if (!p.startsWith(root)) throw new SecurityException("outside the workspace: " + userPath);
            Path existing = p;                                     // the deepest part that exists decides
            while (!Files.exists(existing, LinkOption.NOFOLLOW_LINKS)) existing = existing.getParent();
            Path real;
            try {
                real = existing.toRealPath();                      // follows every symbolic link
            } catch (NoSuchFileException e) {
                throw new SecurityException("dangling symbolic link: " + userPath);
            }
            if (!real.startsWith(root)) throw new SecurityException("leaves the workspace through a symbolic link: " + userPath);
            return p;
        }
    }

    static void deleteTree(Path p) throws IOException {
        try (var s = Files.walk(p)) { for (Path q : s.sorted(Comparator.reverseOrder()).toList()) Files.delete(q); }
    }

    public static void main(String[] args) throws IOException {
        Path base = Files.createTempDirectory("confine");
        Path rootDir = Files.createDirectories(base.resolve("demo"));
        Files.createDirectories(base.resolve("demo-secrets"));
        Files.writeString(base.resolve("demo-secrets/key.txt"), "secret");
        Files.createDirectories(rootDir.resolve("src"));
        Files.createSymbolicLink(rootDir.resolve("link"), base.resolve("demo-secrets"));
        Files.createSymbolicLink(rootDir.resolve("dangling"), base.resolve("nowhere.txt"));
        Workspace ws = new Workspace(rootDir);

        String[] paths = {"src/Main.java", "./src/../README.md", "new/dir/App.java", "../demo-secrets/key.txt",
                          "/etc/passwd", "src/../../demo/src", "link/key.txt", "dangling", ""};
        for (String p : paths) {
            String result;
            try { result = "ok       " + ws.root.relativize(ws.resolve(p)); }
            catch (RuntimeException e) { result = "rejected " + e.getMessage(); }
            System.out.printf("%-26s %s%n", "\"" + p + "\"", result);
        }
        String sibling = base.resolve("demo-secrets/key.txt").toString();
        System.out.println("string prefix check accepts the sibling: " + sibling.startsWith(ws.root.toString()));
        System.out.println("Path.startsWith accepts the sibling:     " + Path.of(sibling).startsWith(ws.root));
        deleteTree(base);
    }
}

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.IntStream;

public class ReadTool {
    static String read(Path file, String display, int offset, int limit) throws IOException {
        List<String> lines = Files.readAllLines(file);
        if (offset < 1) throw new IllegalArgumentException("offset starts at 1, got " + offset);
        if (lines.isEmpty()) return "(" + display + " is empty)";
        if (offset > lines.size())
            throw new IllegalArgumentException("offset " + offset + " is past the end of " + display + " (" + lines.size() + " lines)");
        int end = Math.min(lines.size(), offset - 1 + limit);
        StringBuilder sb = new StringBuilder();
        for (int i = offset - 1; i < end; i++) sb.append(String.format("%5d| %s\n", i + 1, lines.get(i)));
        if (end < lines.size())
            sb.append("[lines ").append(offset).append('-').append(end).append(" of ").append(lines.size())
              .append(" in ").append(display).append("; continue with offset=").append(end + 1).append("]\n");
        return sb.toString();
    }

    public static void main(String[] args) throws IOException {
        Path dir = Files.createTempDirectory("read");
        Path file = dir.resolve("Main.java");
        Files.writeString(file, IntStream.rangeClosed(1, 12).mapToObj(i -> i == 1 ? "public class Main {"
            : i == 12 ? "}" : "    // line " + i).collect(Collectors.joining("\n", "", "\n")));
        System.out.print(read(file, "Main.java", 1, 4));
        System.out.println("---");
        System.out.print(read(file, "Main.java", 10, 4));
        System.out.println("---");
        for (int offset : new int[] {0, 40}) {
            try { read(file, "Main.java", offset, 4); }
            catch (IllegalArgumentException e) { System.out.println("error: " + e.getMessage()); }
        }
        Files.delete(file);
        Files.delete(dir);
    }
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.CharacterCodingException;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Comparator;
import java.util.Locale;

public class SafeRead {
    static final int MAX_LINE = 120;

    /** Rejects files that are not text, then streams only the requested lines. */
    static String read(Path file, String display, int offset, int limit) throws IOException {
        byte[] head;
        try (InputStream in = Files.newInputStream(file)) { head = in.readNBytes(8000); }
        for (byte b : head) if (b == 0) return "error: " + display + " looks binary (NUL byte in the first 8000 bytes); not shown\n";
        var decoder = StandardCharsets.UTF_8.newDecoder()
            .onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT);
        StringBuilder sb = new StringBuilder();
        long total = 0;
        try (BufferedReader r = new BufferedReader(new java.io.InputStreamReader(Files.newInputStream(file), decoder))) {
            for (String line; (line = r.readLine()) != null; ) {
                total++;
                if (total < offset || total >= offset + limit) continue;
                if (line.length() > MAX_LINE) line = line.substring(0, MAX_LINE) + "... [" + line.length() + " characters]";
                sb.append(String.format("%5d| %s\n", total, line));
            }
        } catch (CharacterCodingException e) {
            return "error: " + display + " is not valid UTF-8 (" + e.getClass().getSimpleName() + ")\n";
        }
        return sb + String.format(Locale.ROOT, "[%s: %,d bytes, %,d line%s; shown %d-%d]\n",
            display, Files.size(file), total, total == 1 ? "" : "s", offset, Math.min(total, offset + limit - 1));
    }

    public static void main(String[] args) throws IOException {
        Path dir = Files.createTempDirectory("safe");
        StringBuilder log = new StringBuilder();
        for (int i = 1; i <= 50_000; i++) log.append("2026-10-03 INFO request ").append(i).append(" served\n");
        Files.writeString(dir.resolve("server.log"), log);
        Files.writeString(dir.resolve("bundle.min.js"), "var a=1;" + "x=x+1;".repeat(2000) + "\n");
        Files.write(dir.resolve("logo.png"), new byte[] {(byte) 0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n', 0, 0, 0, 13});
        Files.write(dir.resolve("notes.txt"), "café\n".getBytes(StandardCharsets.ISO_8859_1));
        for (String name : new String[] {"server.log", "bundle.min.js", "logo.png", "notes.txt"})
            System.out.print(read(dir.resolve(name), name, 1, 2));
        try (var s = Files.walk(dir)) { for (Path p : s.sorted(Comparator.reverseOrder()).toList()) Files.delete(p); }
    }
}

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.nio.file.attribute.PosixFilePermissions;
import java.util.Comparator;
import java.util.HashSet;
import java.util.Set;

public class WriteTool {
    static final Set<Path> readFiles = new HashSet<>();               // filled by the read tool

    static String write(Path root, String path, String content) throws IOException {
        Path file = root.resolve(path).normalize();
        if (Files.isDirectory(file)) throw new IllegalArgumentException(path + " is a directory");
        boolean exists = Files.exists(file);
        if (exists && !readFiles.contains(file))
            throw new IllegalStateException(path + " exists; read it before overwriting it");
        if (exists && Files.readString(file).equals(content)) return "unchanged " + path;
        long oldLines = exists ? Files.readString(file).lines().count() : 0;
        Files.createDirectories(file.getParent());
        Path tmp = Files.createTempFile(file.getParent(), ".loop-", ".tmp");   // same directory, same file system
        Files.writeString(tmp, content);
        Files.setPosixFilePermissions(tmp, exists ? Files.getPosixFilePermissions(file)        // keep the old mode,
                                                  : PosixFilePermissions.fromString("rw-r--r--")); // not the temp file's rw-------
        Files.move(tmp, file, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
        long newLines = content.lines().count();
        return (exists ? "overwrote " + path + " (" + oldLines + " -> " + newLines + " lines)" : "created " + path + " (" + newLines + " lines)");
    }

    static void attempt(Path root, String path, String content) {
        try { System.out.println(write(root, path, content)); }
        catch (Exception e) { System.out.println("error: " + e.getMessage()); }
    }

    public static void main(String[] args) throws IOException {
        Path root = Files.createTempDirectory("write");
        Files.writeString(root.resolve("README.md"), "# Demo\n");
        Files.writeString(root.resolve("run.sh"), "#!/bin/sh\necho hi\n");
        Files.setPosixFilePermissions(root.resolve("run.sh"), PosixFilePermissions.fromString("rwxr-xr-x"));

        attempt(root, "src/main/java/App.java", "class App {\n    public static void main(String[] a) {}\n}\n");
        attempt(root, "README.md", "# Demo\n\nA demo project.\n");
        readFiles.add(root.resolve("README.md"));
        attempt(root, "README.md", "# Demo\n\nA demo project.\n");
        attempt(root, "README.md", "# Demo\n\nA demo project.\n");
        attempt(root, "src", "oops");
        readFiles.add(root.resolve("run.sh"));
        attempt(root, "run.sh", "#!/bin/sh\necho hello\n");
        for (String f : new String[] {"run.sh", "src/main/java/App.java"})
            System.out.println(f + " permissions: " + PosixFilePermissions.toString(Files.getPosixFilePermissions(root.resolve(f))));
        try (var s = Files.list(root.resolve("src/main/java"))) { System.out.println("files in src/main/java: " + s.map(p -> p.getFileName().toString()).toList()); }
        try (var s = Files.walk(root)) { for (Path p : s.sorted(Comparator.reverseOrder()).toList()) Files.delete(p); }
    }
}

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;

public class EditTool {
    static String edit(Path file, String oldString, String newString, boolean replaceAll) throws IOException {
        if (oldString.isEmpty()) throw new IllegalArgumentException("oldString is empty; use write_file to create a file");
        if (oldString.equals(newString)) throw new IllegalArgumentException("oldString and newString are identical");
        String content = Files.readString(file);
        List<Integer> lines = new ArrayList<>();                   // line number of every match
        for (int i = content.indexOf(oldString); i >= 0; i = content.indexOf(oldString, i + oldString.length()))
            lines.add((int) content.substring(0, i).chars().filter(c -> c == '\n').count() + 1);
        if (lines.isEmpty())
            throw new IllegalArgumentException("oldString not found in " + file.getFileName());
        if (lines.size() > 1 && !replaceAll)
            throw new IllegalArgumentException("oldString matches " + lines.size() + " times (lines " + lines
                + "); include more surrounding lines to make it unique, or set replaceAll to true");
        String updated = replaceAll ? content.replace(oldString, newString)
                                    : content.substring(0, content.indexOf(oldString)) + newString
                                      + content.substring(content.indexOf(oldString) + oldString.length());
        Files.writeString(file, updated);
        return "replaced " + lines.size() + (lines.size() == 1 ? " occurrence" : " occurrences") + " at lines " + lines;
    }

    static void attempt(Path file, String oldString, String newString, boolean replaceAll) {
        try { System.out.println(edit(file, oldString, newString, replaceAll)); }
        catch (Exception e) { System.out.println("error: " + e.getMessage()); }
    }

    public static void main(String[] args) throws IOException {
        Path dir = Files.createTempDirectory("edit");
        Path file = dir.resolve("Counter.java");
        Files.writeString(file, """
            class Counter {
                int count;
                void inc() { count++; }
                void reset() { count = 0; }
                int get() { return count; }
            }
            """);
        attempt(file, "void inc() { count++; }", "void inc() { count += 1; }", false);
        attempt(file, "void dec()", "void decrement()", false);
        attempt(file, "count", "total", false);
        attempt(file, "    int count;\n    void inc()", "    int count;\n\n    void inc()", false);
        attempt(file, "count", "total", true);
        attempt(file, "total", "total", false);
        System.out.print(Files.readString(file));
        Files.delete(file);
        Files.delete(dir);
    }
}

import java.util.List;
import java.util.Locale;

public class ClosestLines {
    static double similarity(String a, String b) {                // 1 - edit distance / longer length
        int[] prev = new int[b.length() + 1], cur = new int[b.length() + 1];
        for (int j = 0; j <= b.length(); j++) prev[j] = j;
        for (int i = 1; i <= a.length(); i++) {
            cur[0] = i;
            for (int j = 1; j <= b.length(); j++)
                cur[j] = Math.min(Math.min(cur[j - 1] + 1, prev[j] + 1), prev[j - 1] + (a.charAt(i - 1) == b.charAt(j - 1) ? 0 : 1));
            int[] t = prev; prev = cur; cur = t;
        }
        return 1.0 - (double) prev[b.length()] / Math.max(1, Math.max(a.length(), b.length()));
    }

    static String visible(String s) { return s.replace("\t", "\\t"); }          // a tab shows as \t, unlike spaces
    static String squash(String s) { return s.strip().replaceAll("\\s+", " "); }

    static String notFound(List<String> fileLines, String oldString) {
        List<String> want = oldString.lines().toList();
        int bestAt = -1;
        double best = 0;
        for (int start = 0; start + want.size() <= fileLines.size(); start++) {
            double score = 0;
            for (int k = 0; k < want.size(); k++) score += similarity(squash(fileLines.get(start + k)), squash(want.get(k)));
            score /= want.size();
            if (score > best) { best = score; bestAt = start; }
        }
        if (best < 0.6) return "oldString not found, and no similar lines exist; read the file again\n";
        boolean whitespaceOnly = best == 1.0;
        String where = want.size() == 1 ? "line " + (bestAt + 1) : "lines " + (bestAt + 1) + "-" + (bestAt + want.size());
        StringBuilder sb = new StringBuilder("oldString not found. Closest match at " + where
            + (whitespaceOnly ? " (differs only in whitespace)" : String.format(Locale.ROOT, " (%.0f%% similar)", best * 100)) + ":\n");
        for (int k = 0; k < want.size(); k++) sb.append(String.format("%5d| %s\n", bestAt + k + 1, visible(fileLines.get(bestAt + k))));
        sb.append("your oldString:\n");
        for (String w : want) sb.append("     | ").append(visible(w)).append('\n');
        return sb.toString();
    }

    public static void main(String[] args) {
        List<String> file = List.of("public class Hello {", "    public static void main(String[] args) {",
            "        System.out.println(\"hi\");", "    }", "}");
        System.out.print(notFound(file, "\tpublic static void main(String[] args) {\n\t\tSystem.out.println(\"hi\");"));
        System.out.print(notFound(file, "System.out.prinltn(\"hi\");"));
        System.out.print(notFound(file, "import java.util.List;"));
    }
}

import java.io.IOException;
import java.nio.charset.MalformedInputException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.HexFormat;

public class LineEndings {
    record Decoded(String text, boolean bom, boolean crlf) {}
    static final String BOM = "";

    static Decoded load(Path file) throws IOException {
        String raw = Files.readString(file);                        // strict UTF-8: throws on invalid bytes
        boolean bom = raw.startsWith(BOM);
        if (bom) raw = raw.substring(1);
        boolean crlf = raw.contains("\r\n");
        return new Decoded(crlf ? raw.replace("\r\n", "\n") : raw, bom, crlf);
    }

    static void store(Path file, Decoded original, String text) throws IOException {
        String out = original.crlf() ? text.replace("\n", "\r\n") : text;
        Files.writeString(file, (original.bom() ? BOM : "") + out);
    }

    static void editFile(Path file, String oldString, String newString) throws IOException {
        Decoded d = load(file);
        if (!d.text().contains(oldString)) throw new IllegalArgumentException("oldString not found");
        store(file, d, d.text().replace(oldString, newString));
    }

    public static void main(String[] args) throws IOException {
        HexFormat hex = HexFormat.ofDelimiter(" ");
        Path dir = Files.createTempDirectory("eol");
        Path win = dir.resolve("Win.java");
        Files.writeString(win, "class Win {\r\n    int a;\r\n}\r\n");
        String naive = Files.readString(win);
        System.out.println("naive contains \"class Win {\\n    int a;\": " + naive.contains("class Win {\n    int a;"));
        System.out.println("naive starts with \"class\": " + naive.startsWith("class"));
        Decoded d = load(win);
        System.out.println("bom=" + d.bom() + " crlf=" + d.crlf() + " normalized contains it: " + d.text().contains("class Win {\n    int a;"));
        editFile(win, "    int a;\n", "    int a;\n    int b;\n");
        System.out.println("after edit: " + hex.formatHex(Files.readAllBytes(win)));

        Path latin = dir.resolve("Latin.java");
        Files.write(latin, "// café\nclass Latin {}\n".getBytes(StandardCharsets.ISO_8859_1));
        try {
            editFile(latin, "class Latin", "class Latin1");
        } catch (MalformedInputException e) {
            System.out.println("Latin.java: " + e.getClass().getSimpleName() + " (input length " + e.getInputLength() + "); file left unchanged: "
                + hex.formatHex(Files.readAllBytes(latin), 0, 8));
        }
        Files.delete(win);
        Files.delete(latin);
        Files.delete(dir);
    }
}

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HashMap;
import java.util.HexFormat;
import java.util.Map;

public class StaleFiles {
    static final class FileTracker {
        private final Map<Path, String> seen = new HashMap<>();     // file -> hash of the content the model saw

        static String hash(Path file) throws IOException {
            try {
                byte[] d = MessageDigest.getInstance("SHA-256").digest(Files.readAllBytes(file));
                return HexFormat.of().formatHex(d, 0, 6);
            } catch (NoSuchAlgorithmException e) { throw new IllegalStateException(e); }
        }
        void markRead(Path file) throws IOException { seen.put(file, hash(file)); }
        void checkFresh(Path file) throws IOException {
            String before = seen.get(file);
            if (before == null) throw new IllegalStateException(file.getFileName() + " has not been read in this session; read it first");
            String now = hash(file);
            if (!now.equals(before))
                throw new IllegalStateException(file.getFileName() + " changed on disk since it was read (" + before + " -> " + now + "); read it again");
        }
    }

    static final FileTracker tracker = new FileTracker();

    static String read(Path file) throws IOException { tracker.markRead(file); return Files.readString(file); }

    static String edit(Path file, String oldString, String newString) throws IOException {
        tracker.checkFresh(file);
        String content = Files.readString(file);
        if (!content.contains(oldString)) throw new IllegalArgumentException("oldString not found");
        Files.writeString(file, content.replace(oldString, newString));
        tracker.markRead(file);                                     // the model knows the result of its own edit
        return "edited " + file.getFileName() + ", now " + FileTracker.hash(file);
    }

    static void attempt(String label, Path file, String o, String n) {
        try { System.out.println(label + ": " + edit(file, o, n)); }
        catch (Exception e) { System.out.println(label + ": error: " + e.getMessage()); }
    }

    public static void main(String[] args) throws IOException {
        Path dir = Files.createTempDirectory("stale");
        Path file = dir.resolve("Config.java");
        Files.writeString(file, "class Config { int port = 8080; }\n");
        attempt("edit without reading", file, "8080", "9090");
        read(file);
        attempt("edit after reading", file, "8080", "9090");
        attempt("second edit", file, "9090", "9191");
        Files.writeString(file, "class Config { int port = 7070; }\n");   // the user changes the file in an editor
        attempt("edit after an outside change", file, "9191", "9292");
        System.out.print("model reads again: " + read(file));
        attempt("edit after reading again", file, "7070", "9292");
        Files.delete(file);
        Files.delete(dir);
    }
}

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Comparator;
import java.util.List;
import java.util.Set;

public class ListTool {
    static final Set<String> IGNORED = Set.of(".git", "node_modules", "target", "build", ".idea");
    static final int MAX_ENTRIES = 12;

    static int entries;

    static void list(Path dir, int depth, int maxDepth, StringBuilder out) throws IOException {
        List<Path> children;
        try (var s = Files.list(dir)) {
            children = s.sorted(Comparator.comparing((Path p) -> !Files.isDirectory(p)).thenComparing(p -> p.getFileName().toString())).toList();
        }
        for (Path child : children) {
            String name = child.getFileName().toString();
            boolean isDir = Files.isDirectory(child);
            if (entries == MAX_ENTRIES) { out.append("  ".repeat(depth)).append("... more entries not shown\n"); entries++; return; }
            if (entries > MAX_ENTRIES) return;
            entries++;
            if (isDir && IGNORED.contains(name)) { out.append("  ".repeat(depth)).append(name).append("/ (ignored)\n"); continue; }
            out.append("  ".repeat(depth)).append(name).append(isDir ? "/" : "").append('\n');
            if (isDir && depth + 1 < maxDepth) list(child, depth + 1, maxDepth, out);
            else if (isDir) {
                long n;
                try (var s = Files.list(child)) { n = s.count(); }
                out.append("  ".repeat(depth + 1)).append("(").append(n).append(n == 1 ? " entry" : " entries").append(" not shown, depth limit)\n");
            }
        }
    }

    public static void main(String[] args) throws IOException {
        Path root = Files.createTempDirectory("list");
        for (String f : new String[] {"pom.xml", "README.md", "src/main/java/demo/App.java", "src/main/java/demo/Util.java",
                "src/test/java/demo/AppTest.java", "target/classes/demo/App.class", ".git/HEAD", "node_modules/x/index.js"}) {
            Files.createDirectories(root.resolve(f).getParent());
            Files.writeString(root.resolve(f), "");
        }
        for (int maxDepth : new int[] {2, 5}) {
            StringBuilder out = new StringBuilder();
            entries = 0;
            list(root, 0, maxDepth, out);
            System.out.println("depth " + maxDepth + ":");
            System.out.print(out);
        }
        try (var s = Files.walk(root)) { for (Path p : s.sorted(Comparator.reverseOrder()).toList()) Files.delete(p); }
    }
}

import java.io.IOException;
import java.nio.file.FileSystems;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.PathMatcher;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Set;

public class GlobTool {
    static final Set<String> IGNORED = Set.of(".git", "node_modules", "target", "build");

    static List<String> glob(Path root, String pattern, int limit) throws IOException {
        PathMatcher matcher = FileSystems.getDefault().getPathMatcher("glob:" + pattern);
        List<String> hits = new ArrayList<>();
        Files.walkFileTree(root, new SimpleFileVisitor<>() {
            @Override public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes a) {
                return !dir.equals(root) && IGNORED.contains(dir.getFileName().toString()) ? FileVisitResult.SKIP_SUBTREE : FileVisitResult.CONTINUE;
            }
            @Override public FileVisitResult visitFile(Path file, BasicFileAttributes a) {
                Path rel = root.relativize(file);
                if (matcher.matches(rel)) hits.add(rel.toString());
                return FileVisitResult.CONTINUE;
            }
        });
        hits.sort(null);
        if (hits.size() <= limit) return hits;
        List<String> shown = new ArrayList<>(hits.subList(0, limit));
        shown.add("(" + (hits.size() - limit) + " more)");
        return shown;
    }

    public static void main(String[] args) throws IOException {
        Path root = Files.createTempDirectory("glob");
        for (String f : new String[] {"Main.java", "pom.xml", "README.md", "src/main/java/demo/App.java",
                "src/main/java/demo/Util.java", "src/test/java/demo/AppTest.java", "target/generated/Gen.java"}) {
            Files.createDirectories(root.resolve(f).getParent());
            Files.writeString(root.resolve(f), "");
        }
        for (String pattern : new String[] {"*.java", "**/*.java", "**.java", "src/**/*Test.java", "{pom.xml,README.md}", "src/*/java/*.java"})
            System.out.printf("%-20s %s%n", pattern, glob(root, pattern, 3));
        try (var s = Files.walk(root)) { for (Path p : s.sorted(Comparator.reverseOrder()).toList()) Files.delete(p); }
    }
}

import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Comparator;
import java.util.List;
import java.util.Set;
import java.util.regex.Pattern;
import java.util.regex.PatternSyntaxException;

public class GrepTool {
    static final Set<String> IGNORED = Set.of(".git", "node_modules", "target", "build");

    static String grep(Path root, String regex, boolean ignoreCase, int maxMatches) throws IOException {
        Pattern p;
        try {
            p = Pattern.compile(regex, ignoreCase ? Pattern.CASE_INSENSITIVE : 0);
        } catch (PatternSyntaxException e) {
            return "error: invalid regex: " + e.getDescription() + " near index " + e.getIndex() + "\n";
        }
        List<Path> files;
        try (var s = Files.walk(root)) {
            files = s.filter(Files::isRegularFile)
                .filter(f -> root.relativize(f).getNameCount() == 1 || !IGNORED.contains(root.relativize(f).getName(0).toString()))
                .sorted().toList();
        }
        StringBuilder out = new StringBuilder();
        int matches = 0, skippedBinary = 0;
        for (Path f : files) {
            byte[] head;
            try (InputStream in = Files.newInputStream(f)) { head = in.readNBytes(8000); }
            boolean binary = false;
            for (byte b : head) binary |= b == 0;
            if (binary) { skippedBinary++; continue; }
            List<String> lines = Files.readAllLines(f);
            for (int i = 0; i < lines.size(); i++) {
                if (!p.matcher(lines.get(i)).find()) continue;
                if (++matches <= maxMatches) out.append(root.relativize(f)).append(':').append(i + 1).append(": ").append(lines.get(i).strip()).append('\n');
            }
        }
        int more = matches - maxMatches;
        if (more > 0) out.append("[").append(more).append(more == 1 ? " more match" : " more matches").append(" not shown; narrow the pattern]\n");
        if (matches == 0) out.append("no matches\n");
        if (skippedBinary > 0) out.append("[").append(skippedBinary).append(skippedBinary == 1 ? " binary file" : " binary files").append(" skipped]\n");
        return out.toString();
    }

    public static void main(String[] args) throws IOException {
        Path root = Files.createTempDirectory("grep");
        Files.createDirectories(root.resolve("src/demo"));
        Files.createDirectories(root.resolve("target"));
        Files.writeString(root.resolve("src/demo/App.java"), "class App {\n    // TODO: parse args\n    void run() { log(\"start\"); }\n    // todo: exit code\n}\n");
        Files.writeString(root.resolve("src/demo/Util.java"), "class Util {\n    static void log(String s) { System.out.println(s); }\n}\n");
        Files.writeString(root.resolve("target/App.java"), "// TODO: generated copy\n");
        Files.write(root.resolve("src/demo/icon.bin"), new byte[] {'T', 'O', 'D', 'O', 0, 1, 2});
        System.out.print(grep(root, "TODO", false, 10));
        System.out.println("---");
        System.out.print(grep(root, "todo", true, 10));
        System.out.println("---");
        System.out.print(grep(root, "\\blog\\(", false, 1));
        System.out.println("---");
        System.out.print(grep(root, "log(", false, 10));
        System.out.print(grep(root, "FIXME", false, 10));
        try (var s = Files.walk(root)) { for (Path q : s.sorted(Comparator.reverseOrder()).toList()) Files.delete(q); }
    }
}

import java.util.ArrayList;
import java.util.List;

public class UnifiedDiff {
    /** Line diff by longest common subsequence; ops are ' ', '-', '+' with the line. */
    static List<String> ops(List<String> a, List<String> b) {
        int[][] lcs = new int[a.size() + 1][b.size() + 1];
        for (int i = a.size() - 1; i >= 0; i--)
            for (int j = b.size() - 1; j >= 0; j--)
                lcs[i][j] = a.get(i).equals(b.get(j)) ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
        List<String> out = new ArrayList<>();
        int i = 0, j = 0;
        while (i < a.size() || j < b.size()) {
            if (i < a.size() && j < b.size() && a.get(i).equals(b.get(j))) { out.add(" " + a.get(i)); i++; j++; }
            else if (i < a.size() && (j == b.size() || lcs[i + 1][j] >= lcs[i][j + 1])) out.add("-" + a.get(i++));
            else out.add("+" + b.get(j++));
        }
        return out;
    }

    static String unifiedDiff(String path, String before, String after, int context) {
        List<String> ops = ops(before.lines().toList(), after.lines().toList());
        StringBuilder sb = new StringBuilder("--- a/" + path + "\n+++ b/" + path + "\n");
        int k = 0;
        while (k < ops.size()) {
            if (ops.get(k).charAt(0) == ' ') { k++; continue; }
            int start = Math.max(0, k - context), end = k;           // grow the hunk while changes are close together
            while (end < ops.size()) {
                int next = end;
                while (next < ops.size() && ops.get(next).charAt(0) == ' ') next++;
                if (next == ops.size() || next - end > 2 * context) { end = Math.min(ops.size(), end + context); break; }
                while (next < ops.size() && ops.get(next).charAt(0) != ' ') next++;
                end = next;
            }
            int oldStart = 1, newStart = 1;
            for (int x = 0; x < start; x++) { if (ops.get(x).charAt(0) != '+') oldStart++; if (ops.get(x).charAt(0) != '-') newStart++; }
            int oldLen = 0, newLen = 0;
            for (int x = start; x < end; x++) { if (ops.get(x).charAt(0) != '+') oldLen++; if (ops.get(x).charAt(0) != '-') newLen++; }
            sb.append("@@ -").append(oldLen == 0 ? oldStart - 1 : oldStart).append(',').append(oldLen)   // an empty side names the line before
              .append(" +").append(newLen == 0 ? newStart - 1 : newStart).append(',').append(newLen).append(" @@\n");
            for (int x = start; x < end; x++) sb.append(ops.get(x)).append('\n');
            k = end;
        }
        return sb.toString();
    }

    public static void main(String[] args) {
        StringBuilder before = new StringBuilder(), after = new StringBuilder();
        for (int i = 1; i <= 20; i++) {
            String line = "    int f" + i + "() { return " + i + "; }";
            before.append(line).append('\n');
            if (i == 3) after.append("    // first change\n");
            if (i == 16) { after.append("    int f16() { return 160; }\n"); continue; }
            after.append(line).append('\n');
        }
        System.out.print(unifiedDiff("src/F.java", before.toString(), after.toString(), 3));
    }
}

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.io.IOException;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.RecordComponent;
import java.lang.reflect.Type;
import java.nio.ByteBuffer;
import java.nio.charset.CharacterCodingException;
import java.nio.charset.StandardCharsets;
import java.nio.file.FileSystems;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.NoSuchFileException;
import java.nio.file.Path;
import java.nio.file.PathMatcher;
import java.nio.file.StandardCopyOption;
import java.nio.file.attribute.PosixFilePermissions;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.Duration;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Comparator;
import java.util.Deque;
import java.util.HashMap;
import java.util.HexFormat;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.FutureTask;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.function.Consumer;
import java.util.regex.Pattern;

public class FileToolsProject {
    static final ObjectMapper JSON = new ObjectMapper();

    // ---------------- Project 21: messages ----------------
    sealed interface Message permits SystemMessage, UserMessage, AssistantMessage, ToolMessage {}
    record SystemMessage(String text) implements Message {}
    record UserMessage(String text) implements Message {}
    record ToolCall(String id, String name, String arguments) {}
    record AssistantMessage(String text, List<ToolCall> toolCalls) implements Message {
        AssistantMessage {
            text = text == null ? "" : text;
            toolCalls = toolCalls == null ? List.of() : List.copyOf(toolCalls);
        }
        static AssistantMessage text(String text) { return new AssistantMessage(text, List.of()); }
        static AssistantMessage calls(ToolCall... calls) { return new AssistantMessage("", List.of(calls)); }
    }
    record ToolMessage(String callId, String name, String content, boolean isError) implements Message {}

    // ---------------- Project 21: the model side ----------------
    record ToolSpec(String name, String description, JsonNode parameters) {}
    record ModelResponse(AssistantMessage message, int promptTokens, int completionTokens) {}

    @FunctionalInterface
    interface ModelClient {
        ModelResponse chat(List<Message> messages, List<ToolSpec> tools) throws Exception;
    }

    /** Replays canned replies in order and estimates tokens as characters / 4. */
    static final class ScriptedModel implements ModelClient {
        private final Deque<AssistantMessage> replies;
        final List<List<Message>> requests = new ArrayList<>();
        ScriptedModel(AssistantMessage... replies) { this.replies = new ArrayDeque<>(List.of(replies)); }
        @Override public ModelResponse chat(List<Message> messages, List<ToolSpec> tools) {
            requests.add(List.copyOf(messages));
            AssistantMessage reply = replies.poll();
            if (reply == null) throw new IllegalStateException("script has no reply for request " + requests.size());
            int prompt = messages.stream().mapToInt(ScriptedModel::chars).sum() / 4;
            return new ModelResponse(reply, prompt, chars(reply) / 4);
        }

        static int chars(Message m) {
            return switch (m) {
                case SystemMessage s -> s.text().length();
                case UserMessage u -> u.text().length();
                case AssistantMessage a -> a.text().length()
                        + a.toolCalls().stream().mapToInt(c -> c.name().length() + c.arguments().length()).sum();
                case ToolMessage t -> t.content().length();
            };
        }
    }


    // ---------------- Project 21: tools ----------------
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.RECORD_COMPONENT)
    @interface Param {
        String value() default "";
        boolean optional() default false;
    }

    @FunctionalInterface
    interface ToolFunction<A> { String apply(A args) throws Exception; }

    interface Tool {
        String name();
        String description();
        JsonNode schema();
        String run(JsonNode args) throws Exception;
        default boolean readOnly() { return false; }
        default ToolSpec spec() { return new ToolSpec(name(), description(), schema()); }

        /** A tool whose arguments are a record; the schema comes from the record's components. */
        static <A extends Record> Tool of(String name, String description, boolean readOnly, Class<A> type, ToolFunction<A> fn) {
            JsonNode schema = Schemas.forRecord(type);
            return new Tool() {
                public String name() { return name; }
                public String description() { return description; }
                public JsonNode schema() { return schema; }
                public boolean readOnly() { return readOnly; }
                public String run(JsonNode args) throws Exception { return fn.apply(JSON.treeToValue(args, type)); }
            };
        }
    }

    static final class Schemas {
        static ObjectNode forRecord(Class<? extends Record> type) {
            ObjectNode schema = JSON.createObjectNode().put("type", "object");
            ObjectNode properties = schema.putObject("properties");
            ArrayNode required = JSON.createArrayNode();
            for (RecordComponent c : type.getRecordComponents()) {
                ObjectNode p = forType(c.getGenericType());
                Param param = c.getAnnotation(Param.class);
                if (param != null && !param.value().isEmpty()) p.put("description", param.value());
                properties.set(c.getName(), p);
                if (param == null || !param.optional()) required.add(c.getName());
            }
            schema.set("required", required);
            schema.put("additionalProperties", false);
            return schema;
        }

        @SuppressWarnings("unchecked")
        static ObjectNode forType(Type t) {
            ObjectNode n = JSON.createObjectNode();
            if (t instanceof ParameterizedType p && p.getRawType() == List.class)
                return n.put("type", "array").set("items", forType(p.getActualTypeArguments()[0]));
            Class<?> c = (Class<?>) t;
            if (c == String.class) n.put("type", "string");
            else if (c == int.class || c == Integer.class || c == long.class || c == Long.class) n.put("type", "integer");
            else if (c == double.class || c == Double.class) n.put("type", "number");
            else if (c == boolean.class || c == Boolean.class) n.put("type", "boolean");
            else if (c.isEnum()) {
                ArrayNode values = n.put("type", "string").putArray("enum");
                for (Object k : c.getEnumConstants()) values.add(k.toString());
            } else if (c.isRecord()) return forRecord((Class<? extends Record>) c);
            else throw new IllegalArgumentException("no schema for " + c);
            return n;
        }

        static List<String> validate(JsonNode schema, JsonNode value) {
            List<String> errors = new ArrayList<>();
            check(schema, value, "arguments", errors);
            return errors;
        }

        private static void check(JsonNode s, JsonNode v, String path, List<String> errors) {
            String type = s.path("type").asText();
            boolean ok = switch (type) {
                case "object" -> v.isObject();
                case "array" -> v.isArray();
                case "string" -> v.isTextual();
                case "integer" -> v.isIntegralNumber();
                case "number" -> v.isNumber();
                case "boolean" -> v.isBoolean();
                default -> true;
            };
            if (!ok) { errors.add(path + ": expected " + type + ", got " + kind(v)); return; }
            if (s.has("enum")) {
                boolean found = false;
                for (JsonNode e : s.get("enum")) found |= e.equals(v);
                if (!found) errors.add(path + ": must be one of " + s.get("enum"));
            }
            if (v.isObject()) {
                for (JsonNode r : s.path("required"))
                    if (!v.has(r.asText())) errors.add(path + ": missing required property '" + r.asText() + "'");
                for (Map.Entry<String, JsonNode> e : v.properties()) {
                    JsonNode ps = s.path("properties").get(e.getKey());
                    if (ps != null) check(ps, e.getValue(), path + "." + e.getKey(), errors);
                    else if (!s.path("additionalProperties").asBoolean(true)) errors.add(path + ": unknown property '" + e.getKey() + "'");
                }
            }
            if (v.isArray() && s.has("items"))
                for (int i = 0; i < v.size(); i++) check(s.get("items"), v.get(i), path + "[" + i + "]", errors);
        }

        static String kind(JsonNode v) {
            return v.isNull() ? "null" : v.isTextual() ? "string" : v.isIntegralNumber() ? "integer"
                    : v.isNumber() ? "number" : v.isBoolean() ? "boolean" : v.isArray() ? "array" : "object";
        }
    }

    static final class ToolRegistry {
        private final Map<String, Tool> tools = new LinkedHashMap<>();
        private final Duration timeout;
        private final int maxOutputChars;

        ToolRegistry(Duration timeout, int maxOutputChars) {
            this.timeout = timeout;
            this.maxOutputChars = maxOutputChars;
        }

        ToolRegistry register(Tool tool) { tools.put(tool.name(), tool); return this; }
        List<ToolSpec> specs() { return tools.values().stream().map(Tool::spec).toList(); }
        boolean isReadOnly(ToolCall call) { Tool t = tools.get(call.name()); return t != null && t.readOnly(); }

        /** Never throws: every problem becomes an error result that the model can read. */
        ToolMessage execute(ToolCall call) {
            Tool tool = tools.get(call.name());
            if (tool == null)
                return result(call, true, "unknown tool '" + call.name() + "'. Available tools: " + String.join(", ", tools.keySet()));
            JsonNode args;
            try {
                args = JSON.readTree(call.arguments() == null || call.arguments().isBlank() ? "{}" : call.arguments());
            } catch (JsonProcessingException e) {
                return result(call, true, "arguments are not valid JSON: " + e.getOriginalMessage());
            }
            List<String> problems = Schemas.validate(tool.schema(), args);
            if (!problems.isEmpty()) return result(call, true, "invalid arguments: " + String.join("; ", problems));
            FutureTask<String> task = new FutureTask<>(() -> tool.run(args));
            Thread.ofVirtual().name("tool-" + call.name()).start(task);
            try {
                return result(call, false, task.get(timeout.toMillis(), TimeUnit.MILLISECONDS));
            } catch (TimeoutException e) {
                task.cancel(true);
                return result(call, true, "timed out after " + timeout.toMillis() + " ms");
            } catch (ExecutionException e) {
                Throwable cause = e.getCause();
                return result(call, true, cause.getClass().getSimpleName() + ": " + cause.getMessage());
            } catch (InterruptedException e) {
                task.cancel(true);
                Thread.currentThread().interrupt();
                return result(call, true, "interrupted");
            }
        }

        private ToolMessage result(ToolCall call, boolean isError, String content) {
            return new ToolMessage(call.id(), call.name(), truncate(content == null ? "" : content, maxOutputChars), isError);
        }

        /** Keeps whole lines from the head and the tail, about maxChars / 2 characters each. */
        static String truncate(String text, int maxChars) {
            if (text.length() <= maxChars) return text;
            int budget = maxChars / 2;
            String[] lines = text.split("\n", -1);
            int head = 0, used = 0;
            while (head < lines.length && used + lines[head].length() + 1 <= budget) used += lines[head++].length() + 1;
            int tail = lines.length;
            used = 0;
            while (tail > head && used + lines[tail - 1].length() + 1 <= budget) used += lines[--tail].length() + 1;
            int omitted = tail - head;
        String marker = "[... " + omitted + (omitted == 1 ? " line" : " lines") + " omitted, " + text.length() + " characters in total ...]";
            if (head == 0 && tail == lines.length)              // one huge line: cut characters instead
                return text.substring(0, budget) + "\n" + marker + "\n" + text.substring(text.length() - budget);
            List<String> out = new ArrayList<>(Arrays.asList(lines).subList(0, head));
            out.add(marker);
            out.addAll(Arrays.asList(lines).subList(tail, lines.length));
            return String.join("\n", out);
        }
    }

    // ---------------- Project 21: the agent ----------------
    enum StopReason { COMPLETED, MAX_STEPS, MAX_TOKENS, CANCELLED }
    record AgentResult(StopReason stopReason, String finalText, int steps, int tokens) {}
    record AgentConfig(String systemPrompt, int maxSteps, int maxTokens) {}

    interface AgentListener {
        default void onAssistant(AssistantMessage message) {}
        default void onToolCall(ToolCall call) {}
        default void onToolResult(ToolMessage result) {}
        default void onStop(AgentResult result) {}
    }

    static final class Agent {
        private final ModelClient model;
        private final ToolRegistry tools;
        private final AgentConfig config;
        private final List<Message> messages = new ArrayList<>();
        private final List<AgentListener> listeners = new CopyOnWriteArrayList<>();
        private volatile boolean cancelled;

        Agent(ModelClient model, ToolRegistry tools, AgentConfig config) {
            this.model = model;
            this.tools = tools;
            this.config = config;
            messages.add(new SystemMessage(config.systemPrompt()));
        }

        Agent addListener(AgentListener listener) { listeners.add(listener); return this; }
        void cancel() { cancelled = true; }
        List<Message> messages() { return Collections.unmodifiableList(messages); }

        AgentResult run(String task) throws Exception {
            cancelled = false;
            messages.add(new UserMessage(task));
            int steps = 0, tokens = 0;
            while (true) {
                if (cancelled) return stop(StopReason.CANCELLED, "", steps, tokens);
                if (steps >= config.maxSteps()) return stop(StopReason.MAX_STEPS, "", steps, tokens);
                if (tokens >= config.maxTokens()) return stop(StopReason.MAX_TOKENS, "", steps, tokens);
                ModelResponse response = model.chat(List.copyOf(messages), tools.specs());
                steps++;
                tokens += response.promptTokens() + response.completionTokens();
                AssistantMessage reply = response.message();
                messages.add(reply);
                listeners.forEach(l -> l.onAssistant(reply));
                if (reply.toolCalls().isEmpty()) return stop(StopReason.COMPLETED, reply.text(), steps, tokens);
                for (ToolMessage result : runTools(reply.toolCalls())) messages.add(result);
            }
        }

        private List<ToolMessage> runTools(List<ToolCall> calls) {
            List<ToolMessage> results = new ArrayList<>();
            if (calls.size() > 1 && !cancelled && calls.stream().allMatch(tools::isReadOnly)) {
                calls.forEach(c -> listeners.forEach(l -> l.onToolCall(c)));
                List<Future<ToolMessage>> futures = new ArrayList<>();
                try (ExecutorService pool = Executors.newVirtualThreadPerTaskExecutor()) {
                    for (ToolCall c : calls) futures.add(pool.submit(() -> tools.execute(c)));
                }                                                   // close() waits for every call
                for (Future<ToolMessage> f : futures) results.add(f.resultNow());
                results.forEach(r -> listeners.forEach(l -> l.onToolResult(r)));
                return results;
            }
            for (ToolCall c : calls) {                              // one at a time, in order
                listeners.forEach(l -> l.onToolCall(c));
                ToolMessage r = cancelled ? new ToolMessage(c.id(), c.name(), "cancelled before it ran", true) : tools.execute(c);
                results.add(r);
                listeners.forEach(l -> l.onToolResult(r));
            }
            return results;
        }

        private AgentResult stop(StopReason reason, String text, int steps, int tokens) {
            AgentResult result = new AgentResult(reason, text, steps, tokens);
            listeners.forEach(l -> l.onStop(result));
            return result;
        }
    }
    // ---------------- Project 22: file tools ----------------
    static final class Workspace {
        final Path root;
        Workspace(Path root) throws IOException { this.root = root.toRealPath(); }

        Path resolve(String userPath) throws IOException {
            if (userPath == null || userPath.isBlank()) throw new IllegalArgumentException("empty path");
            Path p = root.resolve(userPath).normalize();
            if (!p.startsWith(root)) throw new SecurityException("outside the workspace: " + userPath);
            Path existing = p;
            while (!Files.exists(existing, LinkOption.NOFOLLOW_LINKS)) existing = existing.getParent();
            Path real;
            try { real = existing.toRealPath(); }
            catch (NoSuchFileException e) { throw new SecurityException("dangling symbolic link: " + userPath); }
            if (!real.startsWith(root)) throw new SecurityException("leaves the workspace through a symbolic link: " + userPath);
            return p;
        }

        String rel(Path p) { return root.relativize(p).toString(); }
    }

    record ReadArgs(@Param("File path relative to the workspace root") String path,
                    @Param(value = "First line to show, starting at 1", optional = true) Integer offset,
                    @Param(value = "Maximum number of lines to show", optional = true) Integer limit) {}
    record WriteArgs(@Param("File path relative to the workspace root") String path,
                     @Param("The complete content of the file") String content) {}
    record EditArgs(@Param("File path relative to the workspace root") String path,
                    @Param("Exact text to replace, copied from the file without line numbers") String oldString,
                    @Param("Replacement text") String newString,
                    @Param(value = "Replace every occurrence instead of exactly one", optional = true) Boolean replaceAll) {}
    record ListArgs(@Param(value = "Directory relative to the workspace root; default .", optional = true) String path,
                    @Param(value = "Depth limit; default 3", optional = true) Integer depth) {}
    record GlobArgs(@Param("Glob pattern for relative paths, for example src/**/*.java") String pattern) {}
    record GrepArgs(@Param("Java regular expression") String pattern,
                    @Param(value = "Case-insensitive search", optional = true) Boolean ignoreCase) {}

    static final class FileTools {
        static final Set<String> IGNORED = Set.of(".git", "node_modules", "target", "build", ".idea");
        private final Workspace ws;
        private final Map<Path, String> seen = new HashMap<>();      // file -> hash of the content the model saw
        private final Consumer<String> diffs;                        // unified diffs of every change, for the user

        FileTools(Workspace ws, Consumer<String> diffs) { this.ws = ws; this.diffs = diffs; }

        List<Tool> tools() {
            return List.of(
                Tool.of("read_file", "Read a text file. Lines are numbered; use offset and limit for long files.", true,
                    ReadArgs.class, a -> read(a.path(), a.offset() == null ? 1 : a.offset(), a.limit() == null ? 200 : a.limit())),
                Tool.of("write_file", "Create a file, or replace a whole file that was read before.", false,
                    WriteArgs.class, a -> write(a.path(), a.content())),
                Tool.of("edit_file", "Replace exact text in a file that was read before. oldString must occur once unless replaceAll is true.", false,
                    EditArgs.class, a -> edit(a.path(), a.oldString(), a.newString(), Boolean.TRUE.equals(a.replaceAll()))),
                Tool.of("list_files", "Show a directory tree without build output and version control directories.", true,
                    ListArgs.class, a -> list(a.path() == null ? "." : a.path(), a.depth() == null ? 3 : a.depth())),
                Tool.of("glob", "List files whose relative path matches a glob pattern.", true,
                    GlobArgs.class, a -> glob(a.pattern())),
                Tool.of("grep", "Search file contents with a regular expression; prints path:line: text.", true,
                    GrepArgs.class, a -> grep(a.pattern(), Boolean.TRUE.equals(a.ignoreCase()))));
        }

        private record Text(String body, boolean bom, boolean crlf) {}

        private Text load(Path f) throws IOException {
            byte[] bytes = Files.readAllBytes(f);
            for (int i = 0; i < Math.min(bytes.length, 8000); i++)
                if (bytes[i] == 0) throw new IOException(ws.rel(f) + " looks binary; not shown");
            String raw;
            try { raw = StandardCharsets.UTF_8.newDecoder().decode(ByteBuffer.wrap(bytes)).toString(); }
            catch (CharacterCodingException e) { throw new IOException(ws.rel(f) + " is not valid UTF-8"); }
            boolean bom = raw.startsWith("\uFEFF");
            if (bom) raw = raw.substring(1);
            boolean crlf = raw.contains("\r\n");
            return new Text(crlf ? raw.replace("\r\n", "\n") : raw, bom, crlf);
        }

        private void store(Path f, Text old, String body) throws IOException {
            String out = (old.bom() ? "\uFEFF" : "") + (old.crlf() ? body.replace("\n", "\r\n") : body);
            Files.createDirectories(f.getParent());
            Path tmp = Files.createTempFile(f.getParent(), ".loop-", ".tmp");
            Files.writeString(tmp, out);
            Files.setPosixFilePermissions(tmp, Files.exists(f) ? Files.getPosixFilePermissions(f) : PosixFilePermissions.fromString("rw-r--r--"));
            Files.move(tmp, f, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
            seen.put(f, hash(f));
        }

        private static String hash(Path f) throws IOException {
            try { return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(Files.readAllBytes(f)), 0, 6); }
            catch (NoSuchAlgorithmException e) { throw new IllegalStateException(e); }
        }

        private void checkFresh(Path f) throws IOException {
            String before = seen.get(f);
            if (before == null) throw new IllegalStateException(ws.rel(f) + " has not been read yet; read it first");
            if (!before.equals(hash(f))) throw new IllegalStateException(ws.rel(f) + " changed on disk since it was read; read it again");
        }

        String read(String path, int offset, int limit) throws IOException {
            Path f = ws.resolve(path);
            if (Files.isDirectory(f)) throw new IllegalArgumentException(path + " is a directory; use list_files");
            List<String> lines = load(f).body().lines().toList();
            seen.put(f, hash(f));
            if (lines.isEmpty()) return "(empty file)";
            if (offset < 1 || offset > lines.size()) throw new IllegalArgumentException("offset must be between 1 and " + lines.size());
            int end = Math.min(lines.size(), offset - 1 + limit);
            StringBuilder sb = new StringBuilder();
            for (int i = offset - 1; i < end; i++) {
                String line = lines.get(i);
                if (line.length() > 500) line = line.substring(0, 500) + "... [" + line.length() + " characters]";
                sb.append(String.format("%5d| %s\n", i + 1, line));
            }
            if (end < lines.size())
                sb.append("[lines ").append(offset).append('-').append(end).append(" of ").append(lines.size())
                  .append("; continue with offset=").append(end + 1).append("]\n");
            return sb.toString();
        }

        String write(String path, String content) throws IOException {
            Path f = ws.resolve(path);
            if (Files.isDirectory(f)) throw new IllegalArgumentException(path + " is a directory");
            Text old = new Text("", false, false);
            if (Files.exists(f)) { checkFresh(f); old = load(f); }
            boolean created = !Files.exists(f);
            store(f, old, content);
            diffs.accept(unifiedDiff(ws.rel(f), old.body(), content));
            return (created ? "created " : "replaced ") + ws.rel(f) + " (" + content.lines().count() + " lines)";
        }

        String edit(String path, String oldString, String newString, boolean replaceAll) throws IOException {
            Path f = ws.resolve(path);
            checkFresh(f);
            if (oldString.isEmpty()) throw new IllegalArgumentException("oldString is empty; use write_file to create a file");
            if (oldString.equals(newString)) throw new IllegalArgumentException("oldString and newString are identical");
            Text t = load(f);
            String body = t.body();
            int count = 0;
            for (int i = body.indexOf(oldString); i >= 0; i = body.indexOf(oldString, i + oldString.length())) count++;
            if (count == 0) throw new IllegalArgumentException("oldString not found in " + ws.rel(f) + hint(body, oldString));
            if (count > 1 && !replaceAll)
                throw new IllegalArgumentException("oldString matches " + count + " times in " + ws.rel(f) + "; add surrounding lines to make it unique, or set replaceAll");
            int first = body.indexOf(oldString);
            String updated = replaceAll ? body.replace(oldString, newString)
                                        : body.substring(0, first) + newString + body.substring(first + oldString.length());
            store(f, t, updated);
            diffs.accept(unifiedDiff(ws.rel(f), body, updated));
            long line = body.substring(0, first).chars().filter(c -> c == '\n').count() + 1;
            return "edited " + ws.rel(f) + ": " + count + (count == 1 ? " replacement" : " replacements") + ", first at line " + line;
        }

        /** Points at a line that matches the first line of oldString except for whitespace. */
        private static String hint(String body, String oldString) {
            String want = oldString.lines().findFirst().orElse("").strip().replaceAll("\\s+", " ");
            List<String> lines = body.lines().toList();
            for (int i = 0; i < lines.size(); i++)
                if (!want.isEmpty() && lines.get(i).strip().replaceAll("\\s+", " ").equals(want))
                    return "; line " + (i + 1) + " matches except for whitespace (the file indents it with "
                        + indent(lines.get(i)) + ", oldString with " + indent(oldString) + ")";
            return "; read the file again and copy the text exactly";
        }

        private static String indent(String line) {
            int spaces = 0, tabs = 0;
            for (char c : line.toCharArray()) { if (c == ' ') spaces++; else if (c == '\t') tabs++; else break; }
            String s = (spaces > 0 ? spaces + (spaces == 1 ? " space" : " spaces") : "") + (spaces > 0 && tabs > 0 ? " and " : "")
                + (tabs > 0 ? tabs + (tabs == 1 ? " tab" : " tabs") : "");
            return s.isEmpty() ? "no indentation" : s;
        }

        String list(String path, int depth) throws IOException {
            StringBuilder out = new StringBuilder();
            listInto(ws.resolve(path), 0, depth, out);
            return out.isEmpty() ? "(empty directory)" : out.toString();
        }

        private void listInto(Path dir, int level, int depth, StringBuilder out) throws IOException {
            List<Path> children;
            try (var s = Files.list(dir)) {
                children = s.sorted(Comparator.comparing((Path p) -> !Files.isDirectory(p)).thenComparing(p -> p.getFileName().toString())).toList();
            }
            for (Path c : children) {
                String name = c.getFileName().toString();
                boolean isDir = Files.isDirectory(c);
                if (isDir && IGNORED.contains(name)) continue;
                out.append("  ".repeat(level)).append(name).append(isDir ? "/" : "").append('\n');
                if (isDir && level + 1 < depth) listInto(c, level + 1, depth, out);
            }
        }

        String glob(String pattern) throws IOException {
            PathMatcher matcher = FileSystems.getDefault().getPathMatcher("glob:" + pattern);
            try (var s = Files.walk(ws.root)) {
                List<String> hits = s.filter(Files::isRegularFile).map(ws::rel)
                    .filter(r -> !IGNORED.contains(Path.of(r).getName(0).toString()))
                    .filter(r -> matcher.matches(Path.of(r))).sorted().toList();
                return hits.isEmpty() ? "no files match " + pattern : String.join("\n", hits);
            }
        }

        String grep(String regex, boolean ignoreCase) throws IOException {
            Pattern p = Pattern.compile(regex, ignoreCase ? Pattern.CASE_INSENSITIVE : 0);
            List<Path> files;
            try (var s = Files.walk(ws.root)) {
                files = s.filter(Files::isRegularFile).filter(f -> !IGNORED.contains(ws.root.relativize(f).getName(0).toString())).sorted().toList();
            }
            StringBuilder out = new StringBuilder();
            int matches = 0;
            for (Path f : files) {
                List<String> lines;
                try { lines = load(f).body().lines().toList(); } catch (IOException e) { continue; }   // binary or not UTF-8
                for (int i = 0; i < lines.size(); i++)
                    if (p.matcher(lines.get(i)).find() && ++matches <= 50)
                        out.append(ws.rel(f)).append(':').append(i + 1).append(": ").append(lines.get(i).strip()).append('\n');
            }
            if (matches > 50) out.append("[").append(matches - 50).append(" more matches not shown]\n");
            return matches == 0 ? "no matches for " + regex : out.toString();
        }
    }

    /** A unified diff with 3 lines of context, from a longest-common-subsequence line diff. */
    static String unifiedDiff(String path, String before, String after) {
        List<String> a = before.lines().toList(), b = after.lines().toList();
        int[][] lcs = new int[a.size() + 1][b.size() + 1];
        for (int i = a.size() - 1; i >= 0; i--)
            for (int j = b.size() - 1; j >= 0; j--)
                lcs[i][j] = a.get(i).equals(b.get(j)) ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
        List<String> ops = new ArrayList<>();
        for (int i = 0, j = 0; i < a.size() || j < b.size(); ) {
            if (i < a.size() && j < b.size() && a.get(i).equals(b.get(j))) { ops.add(" " + a.get(i)); i++; j++; }
            else if (i < a.size() && (j == b.size() || lcs[i + 1][j] >= lcs[i][j + 1])) ops.add("-" + a.get(i++));
            else ops.add("+" + b.get(j++));
        }
        StringBuilder sb = new StringBuilder("--- a/" + path + "\n+++ b/" + path + "\n");
        for (int k = 0; k < ops.size(); ) {
            if (ops.get(k).charAt(0) == ' ') { k++; continue; }
            int start = Math.max(0, k - 3), end = k;
            while (true) {
                int next = end;
                while (next < ops.size() && ops.get(next).charAt(0) == ' ') next++;
                if (next == ops.size() || next - end > 6) { end = Math.min(ops.size(), end + 3); break; }
                while (next < ops.size() && ops.get(next).charAt(0) != ' ') next++;
                end = next;
            }
            int oldStart = 1, newStart = 1, oldLen = 0, newLen = 0;
            for (int x = 0; x < start; x++) { if (ops.get(x).charAt(0) != '+') oldStart++; if (ops.get(x).charAt(0) != '-') newStart++; }
            for (int x = start; x < end; x++) { if (ops.get(x).charAt(0) != '+') oldLen++; if (ops.get(x).charAt(0) != '-') newLen++; }
            sb.append("@@ -").append(oldLen == 0 ? oldStart - 1 : oldStart).append(',').append(oldLen)
              .append(" +").append(newLen == 0 ? newStart - 1 : newStart).append(',').append(newLen).append(" @@\n");
            for (int x = start; x < end; x++) sb.append(ops.get(x)).append('\n');
            k = end;
        }
        return sb.toString();
    }
    // ---------------- end of Project 22 ----------------

    static ToolCall call(String id, String name, String json) { return new ToolCall(id, name, json); }

    public static void main(String[] args) throws Exception {
        Path root = Files.createTempDirectory("p22");
        Files.createDirectories(root.resolve("src/main/java/demo"));
        Files.writeString(root.resolve("pom.xml"), "<project><artifactId>demo</artifactId></project>\n");
        Files.writeString(root.resolve("src/main/java/demo/Greeter.java"), """
            package demo;

            public class Greeter {
                static String greet(String name) {
                    return "Hello " + name;
                }
            }
            """);
        Workspace ws = new Workspace(root);
        List<String> diffs = new ArrayList<>();
        ToolRegistry registry = new ToolRegistry(Duration.ofSeconds(10), 4000);
        new FileTools(ws, diffs::add).tools().forEach(registry::register);

        String file = "src/main/java/demo/Greeter.java";
        ScriptedModel model = new ScriptedModel(
            AssistantMessage.calls(call("c1", "glob", "{\"pattern\": \"**/*.java\"}")),
            AssistantMessage.calls(call("c2", "read_file", "{\"path\": \"" + file + "\"}")),
            AssistantMessage.calls(call("c3", "edit_file", "{\"path\": \"" + file + "\", \"oldString\": \"\\treturn \\\"Hello \\\" + name;\", \"newString\": \"\\treturn \\\"Hello, \\\" + name + \\\".\\\";\"}")),
            AssistantMessage.calls(call("c4", "edit_file", "{\"path\": \"" + file + "\", \"oldString\": \"        return \\\"Hello \\\" + name;\", \"newString\": \"        return \\\"Hello, \\\" + name + \\\".\\\";\"}")),
            AssistantMessage.calls(call("c5", "write_file", "{\"path\": \"src/test/java/demo/GreeterTest.java\", \"content\": \"package demo;\\n\\nclass GreeterTest {\\n    // expects Hello, Ada.\\n}\\n\"}")),
            AssistantMessage.calls(call("c6", "grep", "{\"pattern\": \"greet\\\\(\"}")),
            AssistantMessage.text("Greeter.greet now returns \"Hello, NAME.\" and a test file was added."));

        Agent agent = new Agent(model, registry, new AgentConfig("You are a coding agent.", 10, 100_000));
        agent.addListener(new AgentListener() {
            public void onToolCall(ToolCall c) { System.out.println("> " + c.name() + " " + c.arguments().replace("\n", "\\n").replace("\t", "\\t")); }
            public void onToolResult(ToolMessage r) {
                r.content().lines().limit(8).forEach(l -> System.out.println((r.isError() ? "  ! " : "  ") + l));
            }
            public void onStop(AgentResult r) { System.out.println("[" + r.stopReason() + " after " + r.steps() + " steps] " + r.finalText()); }
        });
        agent.run("Make Greeter.greet return \"Hello, NAME.\" and add a test file.");
        System.out.println("--- diffs shown to the user");
        diffs.forEach(System.out::print);
        try (var s = Files.walk(root)) { for (Path p : s.sorted(Comparator.reverseOrder()).toList()) Files.delete(p); }
    }
}