@illuminis/comprism 0.1.2 → 0.1.4

package/out/executor/diagnostics.js

@@ -0,0 +1,181 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDiagnostics = readDiagnostics;
+/**
+ * `read_diagnostics` in a terminal (manual 5.11): the project's own checker
+ * for the language of the changed file, run without installing anything.
+ *
+ * TypeScript's `tsc` for `.ts` and `.tsx`, Pyright for `.py`, each only when it
+ * is installed in the project or on this machine. When neither is, the result
+ * says the file could not be checked, so the agent never reads silence as
+ * "correct". One language at a time; others are added the same way.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const paths_1 = require("./paths");
+const shell_1 = require("./shell");
+const self_1 = require("../lib/self");
+/** A program from the project's own node_modules, walking up, then the PATH. */
+function findTool(root, name) {
+    const exts = process.platform === "win32" ? [".cmd", ".exe", ""] : [""];
+    for (let dir = root;; dir = path.dirname(dir)) {
+        for (const e of exts) {
+            const p = path.join(dir, "node_modules", ".bin", name + e);
+            if (fs.existsSync(p))
+                return p;
+        }
+        if (path.dirname(dir) === dir)
+            break;
+    }
+    for (const d of (process.env.PATH ?? "").split(path.delimiter)) {
+        for (const e of exts) {
+            const p = path.join(d, name + e);
+            try {
+                if (fs.statSync(p).isFile())
+                    return p;
+            }
+            catch { /* not here */ }
+        }
+    }
+    return null;
+}
+function slashed(p) {
+    return p.split(path.sep).join("/");
+}
+/** TypeScript's own script in the project's node_modules, walking up. Run
+ *  with Node directly, so no `.cmd` launcher is involved on Windows. */
+function findScript(root, parts) {
+    for (let dir = root;; dir = path.dirname(dir)) {
+        const p = path.join(dir, "node_modules", ...parts);
+        if (fs.existsSync(p))
+            return p;
+        if (path.dirname(dir) === dir)
+            return null;
+    }
+}
+/** A tool as a program and its first arguments. */
+function launcher(root, name, script) {
+    // The ready to run program cannot run another script, so it uses the
+    // project's own launcher, which the project's own Node runs.
+    const js = (0, self_1.isStandalone)() ? null : findScript(root, script);
+    if (js)
+        return [process.execPath, [js]];
+    const tool = findTool(root, name);
+    if (!tool)
+        return null;
+    if (process.platform === "win32" && /\.(cmd|bat)$/i.test(tool))
+        return ["cmd.exe", ["/d", "/c", tool]];
+    return [tool, []];
+}
+async function typescript(root, file, opts) {
+    const found0 = launcher(root, "tsc", ["typescript", "bin", "tsc"]);
+    if (!found0)
+        return null;
+    const [tsc, pre] = found0;
+    const hasConfig = fs.existsSync(path.join(root, "tsconfig.json"));
+    const args = hasConfig ? ["--noEmit", "--pretty", "false", "-p", "."]
+        : ["--noEmit", "--pretty", "false", "--strict", ...(file ? [file] : [])];
+    const r = await (0, shell_1.runProgram)(tsc, [...pre, ...args], { ...opts, root, timeoutMs: 120_000 });
+    const found = [];
+    for (const line of r.content.split("\n")) {
+        const m = /^(.+?)\((\d+),(\d+)\): (error|warning) (TS\d+: .*)$/.exec(line.trim());
+        if (m)
+            found.push({ file: slashed(path.relative(root, path.resolve(root, m[1]))), line: Number(m[2]),
+                col: Number(m[3]), severity: m[4], text: m[5] });
+    }
+    return found;
+}
+async function pyright(root, file, opts) {
+    const found0 = launcher(root, "pyright", ["pyright", "index.js"]);
+    if (!found0)
+        return null;
+    const [tool, pre] = found0;
+    const r = await (0, shell_1.runProgram)(tool, [...pre, "--outputjson", ...(file ? [file] : [])], { ...opts, root, timeoutMs: 120_000 });
+    const text = r.content.replace(/^exit -?\d+\n\n/, "");
+    try {
+        const data = JSON.parse(text.slice(text.indexOf("{")));
+        return (data.generalDiagnostics ?? []).map((d) => ({
+            file: slashed(path.relative(root, String(d.file))), line: Number(d.range?.start?.line ?? 0) + 1,
+            col: Number(d.range?.start?.character ?? 0) + 1, severity: String(d.severity), text: String(d.message),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function readDiagnostics(root, rel, severity, opts) {
+    const realRoot = fs.realpathSync(root);
+    const file = rel ? slashed(path.relative(realRoot, (0, paths_1.resolveInside)(realRoot, rel, true))) : null;
+    const ext = (file ?? "").toLowerCase().split(".").pop() ?? "";
+    const kinds = file ? (["ts", "tsx", "mts", "cts"].includes(ext) ? ["ts"] : ext === "py" ? ["py"] : [])
+        : ["ts", "py"];
+    if (!kinds.length) {
+        return { content: `No checker is set up for .${ext} files, so ${file} could not be checked. `
+                + "Run the tests instead, and do not assume it is correct.", summary: "could not check",
+            facts: { checked: 0 } };
+    }
+    const found = [];
+    const missing = [];
+    let ran = 0;
+    for (const kind of kinds) {
+        const got = kind === "ts" ? await typescript(realRoot, file, opts) : await pyright(realRoot, file, opts);
+        if (got === null) {
+            missing.push(kind === "ts" ? "TypeScript's checker (tsc)" : "Pyright");
+            continue;
+        }
+        ran += 1;
+        // The changed file's own problems first, then what the change broke
+        // elsewhere: a wrong return type shows up where the function is used.
+        found.push(...got.filter((p) => !file || p.file === file), ...got.filter((p) => file && p.file !== file));
+    }
+    if (!ran) {
+        return {
+            content: `${missing.join(" and ")} ${missing.length > 1 ? "are" : "is"} not installed here, so `
+                + `${file ?? "the project"} could not be checked. Run the tests instead, and do not claim the code is correct.`,
+            summary: "could not check", facts: { checked: 0 },
+        };
+    }
+    const wanted = severity === "all" ? found : found.filter((p) => p.severity === (severity || "error"));
+    const errors = found.filter((p) => p.severity === "error").length;
+    const lines = wanted.slice(0, 50).map((p) => `${p.file}:${p.line}:${p.col} ${p.severity} ${p.text}`);
+    if (wanted.length > 50)
+        lines.push(`[... ${wanted.length - 50} more left out]`);
+    return {
+        content: lines.length ? lines.join("\n") : `No ${severity === "all" ? "problems" : "errors"} in ${file ?? "the project"}.`,
+        summary: `${errors} errors`,
+        facts: { checked: 1, errors, warnings: found.length - errors },
+    };
+}

package/out/executor/files.js

@@ -46,12 +46,16 @@ exports.performFileAction = performFileAction;
  * writes is easy; one that refuses correctly is the one somebody can leave
  * running.
  */
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const paths_1 = require("./paths");
 const MAX_FILE_CHARS = 60_000;
 const MAX_RESULTS = 200;
 const MAX_MAP_PATHS = 2_000;
+/** Beyond this a file asked for whole is read as its first lines (manual 5.4). */
+const MAX_WHOLE_LINES = 2_000;
 const SKIP_DIRS = new Set([
     "node_modules", ".git", "dist", "build", "out", ".next", ".nuxt", ".venv",
     "venv", "env", "__pycache__", ".pytest_cache", ".mypy_cache", "coverage",
@@ -65,6 +69,8 @@ const TEXT_EXT = new Set([
     "ini", "cfg", "conf", "md", "mdx", "txt", "rst", "csv", "tsv", "xml", "svg",
     "vue", "svelte", "astro", "graphql", "gql", "proto", "lock", "prisma", "tf",
     "r", "jl", "lua", "pl", "ex", "exs",
+    // Logs are the commonest large text file a person asks about (manual 6.13).
+    "log",
 ]);
 function isText(name) {
     const lower = name.toLowerCase();
@@ -78,7 +84,13 @@ function ok(content, summary) {
 function fail(content) {
     return { content, isError: true, summary: content.slice(0, 200) };
 }
-function walk(dir, root, out, limit) {
+/** A project path as the agent sees it: forward slashes on every system.
+ *  Windows would otherwise hand back `src\math.py`, which no pattern the model
+ *  writes will ever match (manual 5.2). */
+function slashed(rel) {
+    return rel.split(path.sep).join("/");
+}
+function walk(dir, root, out, limit, all = false) {
     if (out.length >= limit)
         return;
     let entries;
@@ -93,19 +105,89 @@ function walk(dir, root, out, limit) {
             return;
         const full = path.join(dir, e.name);
         if (e.isDirectory()) {
-            if (SKIP_DIRS.has(e.name))
+            // Git's own folder is never project content, even when asked for all.
+            if (e.name === ".git" || (!all && SKIP_DIRS.has(e.name)))
                 continue;
             // Not followed. A link pointing outside the project would otherwise pull
             // the whole machine into a file map, and `resolveInside` would never see
             // it because nobody asked for that path by name.
             if (e.isSymbolicLink())
                 continue;
-            walk(full, root, out, limit);
+            walk(full, root, out, limit, all);
         }
         else if (e.isFile()) {
-            out.push(path.relative(root, full));
+            out.push(slashed(path.relative(root, full)));
+        }
+    }
+}
+/** Paths the service said to leave out of a search or listing, because a
+ *  `deny` rule covers them (manual 4.11). The service decides; this only skips
+ *  them, so nothing from a denied folder is read. The service still removes
+ *  anything that slips through from what comes back. */
+function denied(rel, exclude) {
+    if (!Array.isArray(exclude) || exclude.length === 0)
+        return false;
+    return exclude.some((raw) => {
+        const pattern = String(raw);
+        const base = pattern.endsWith("/**") ? pattern.slice(0, -3) : null;
+        if (base !== null && (rel === base || rel.startsWith(`${base}/`)))
+            return true;
+        return globToRegExp(pattern).test(rel);
+    });
+}
+/** What git itself would call this project's files: tracked, plus new files
+ *  that `.gitignore` does not exclude. Git reads every ignore file, nested and
+ *  global, so nothing here reimplements its rules. Null outside a repository,
+ *  or when git is not installed, and the plain walk is used instead. */
+function gitFiles(dir, root) {
+    let listed;
+    try {
+        // An argument list, never a shell string (COMMON.md, Windows quoting).
+        listed = (0, child_process_1.execFileSync)("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+            cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 64 * 1024 * 1024, windowsHide: true,
+        });
+    }
+    catch {
+        return null;
+    }
+    const out = [];
+    for (const rel of listed.split("\0")) {
+        if (!rel)
+            continue;
+        // Dependency and build folders stay out even if someone committed them.
+        if (rel.split("/").some((part) => SKIP_DIRS.has(part)))
+            continue;
+        const full = path.join(dir, rel);
+        // A tracked file that was deleted, or a link, is not a file to read.
+        try {
+            if (!fs.lstatSync(full).isFile())
+                continue;
         }
+        catch {
+            continue;
+        }
+        out.push(slashed(path.relative(root, full)));
+    }
+    return out;
+}
+/** The files under `dir` a search looks at. Ignored files, dependency folders
+ *  and build output are left out unless `all` is asked for (manual 5.2). */
+function projectFiles(dir, root, limit, all) {
+    // A search limited to one file searches that file (manual 5.3).
+    try {
+        if (fs.statSync(dir).isFile())
+            return [slashed(path.relative(root, dir))];
+    }
+    catch {
+        return [];
     }
+    const listed = all ? null : gitFiles(dir, root);
+    if (listed)
+        return listed.sort().slice(0, limit);
+    const out = [];
+    walk(dir, root, out, limit, all);
+    return out.sort();
 }
 function globToRegExp(pattern) {
     let out = "";
@@ -128,6 +210,43 @@ function globToRegExp(pattern) {
     }
     return new RegExp(`^${out}$`);
 }
+/** What each file held when the agent last read or wrote it, by real path, so
+ *  an edit whose target has gone can say the file changed since it was read
+ *  (manual 5.6). Only a fingerprint is kept, never the text. */
+const seen = new Map();
+function fingerprint(text) {
+    return (0, crypto_1.createHash)("sha256").update(text).digest("hex");
+}
+/** Lines taken out and put in by replacing `from` with `to`. */
+function linesIn(text) {
+    if (!text)
+        return 0;
+    return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+}
+/** Lines really taken out and put in: lines the edit repeated unchanged at
+ *  either end, for context, are not counted as changed (manual 5.6). */
+function trimmedCounts(from, to) {
+    const a = from.replace(/\n$/, "").split("\n");
+    const b = to.replace(/\n$/, "").split("\n");
+    if (!from)
+        return [0, linesIn(to)];
+    if (!to)
+        return [linesIn(from), 0];
+    let head = 0;
+    while (head < a.length && head < b.length && a[head] === b[head])
+        head += 1;
+    let tail = 0;
+    while (tail < a.length - head && tail < b.length - head
+        && a[a.length - 1 - tail] === b[b.length - 1 - tail])
+        tail += 1;
+    return [a.length - head - tail, b.length - head - tail];
+}
+function lineCounts(from, to) {
+    const [removed, added] = trimmedCounts(from, to);
+    return { changed: 1, lines_removed: removed, lines_added: added };
+}
+const STALE = (rel) => `Refused, and nothing was written: the file changed since it was read. ${rel} no longer holds that text, `
+    + "so somebody or something else edited it. Read it again and edit what is there now.";
 function countOf(haystack, needle) {
     if (!needle)
         return 0;
@@ -152,40 +271,89 @@ function performFileAction(root, name, a) {
                     const size = fs.statSync(p).size;
                     return fail(`${rel} is not a text file (${size.toLocaleString()} bytes). Reading it would be noise rather than context.`);
                 }
-                let body = fs.readFileSync(p, "utf8");
+                const whole = fs.readFileSync(p, "utf8");
+                seen.set(p, fingerprint(whole));
+                const lines = whole.split("\n");
+                // A file ending in a newline has no line after it.
+                if (lines.length > 1 && lines[lines.length - 1] === "")
+                    lines.pop();
+                const total = lines.length;
                 const offset = Number(a.offset ?? 0), limit = Number(a.limit ?? 0);
-                if (offset > 0 || limit > 0) {
-                    const lines = body.split("\n");
-                    const from = Math.max(0, offset > 0 ? offset - 1 : 0);
-                    body = lines.slice(from, limit > 0 ? from + limit : undefined).join("\n");
-                }
+                const ranged = offset > 0 || limit > 0;
+                // Small files are read whole. A large one asked for whole gets its
+                // first lines and is told how to reach the rest, so a 5,000 line file
+                // never lands in the conversation entire (manual 5.4).
+                const large = total > MAX_WHOLE_LINES || whole.length > MAX_FILE_CHARS;
+                const from = Math.min(Math.max(0, offset > 0 ? offset - 1 : 0), total);
+                let to = ranged ? (limit > 0 ? Math.min(total, from + limit) : total)
+                    : large ? Math.min(total, MAX_WHOLE_LINES) : total;
+                let body = lines.slice(from, to).join("\n");
                 if (body.length > MAX_FILE_CHARS) {
-                    body = `${body.slice(0, MAX_FILE_CHARS)}\n\n[... truncated. Use offset and limit to read further.]`;
+                    // Cut on a line, so the range reported is the range given.
+                    let size = 0, kept = from;
+                    while (kept < to && size + lines[kept].length + 1 <= MAX_FILE_CHARS) {
+                        size += lines[kept].length + 1;
+                        kept += 1;
+                    }
+                    to = Math.max(kept, from + 1);
+                    body = lines.slice(from, to).join("\n");
+                }
+                const n = (x) => x.toLocaleString("en-US");
+                if (to < total || from > 0) {
+                    body += `\n\n[Lines ${n(from + 1)} to ${n(to)} of ${n(total)}. `
+                        + "Use grep to find what you need, then offset and limit to read just those lines.]";
                 }
-                return ok(body, `read ${rel}`);
+                return {
+                    content: body,
+                    summary: `read ${rel} lines ${n(from + 1)} to ${n(to)} of ${n(total)}`,
+                    facts: { lines_from: total ? from + 1 : 0, lines_to: to, lines_total: total },
+                };
             }
             case "list_dir": {
                 const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
+                const here = slashed(path.relative(realRoot, p));
                 const rows = fs.readdirSync(p, { withFileTypes: true })
+                    .filter((e) => !denied(here ? `${here}/${e.name}` : e.name, a.exclude))
                     .map((e) => (e.isDirectory() ? `${e.name}/` : e.name)).sort();
                 return ok(rows.join("\n") || "(empty)", `${rows.length} entries`);
             }
             case "file_map": {
                 const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
-                const found = [];
-                walk(p, realRoot, found, MAX_MAP_PATHS);
-                found.sort();
-                const note = found.length >= MAX_MAP_PATHS
-                    ? `\n\n[... stopped at ${MAX_MAP_PATHS} paths. Map a subfolder for the rest.]` : "";
-                return ok(found.join("\n") + note, `${found.length} files`);
+                const found = projectFiles(p, realRoot, Number.MAX_SAFE_INTEGER, Boolean(a.include_ignored))
+                    .filter((f) => !denied(f, a.exclude));
+                const shown = found.slice(0, MAX_MAP_PATHS);
+                const note = found.length > shown.length
+                    ? `\n\n[... ${found.length - shown.length} more paths left out. Map a subfolder for the rest.]` : "";
+                return {
+                    content: shown.join("\n") + note, summary: `${found.length} files`,
+                    facts: { files: shown.length, left_out: found.length - shown.length },
+                };
             }
             case "glob": {
                 const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
-                const found = [];
-                walk(p, realRoot, found, MAX_MAP_PATHS);
-                const rx = globToRegExp(String(a.pattern ?? ""));
-                const hits = found.filter((f) => rx.test(f)).slice(0, MAX_RESULTS);
-                return ok(hits.join("\n") || "(no matches)", `${hits.length} files`);
+                const found = projectFiles(p, realRoot, Number.MAX_SAFE_INTEGER, Boolean(a.include_ignored))
+                    .filter((f) => !denied(f, a.exclude));
+                const pattern = String(a.pattern ?? "");
+                const rx = globToRegExp(pattern);
+                // A bare name pattern ("calc.py", "*.py") means anywhere in the
+                // project, the way a person reads it, not only the top folder.
+                const anywhere = pattern.includes("/") ? null : globToRegExp(`**/${pattern}`);
+                const all = found.filter((f) => rx.test(f) || Boolean(anywhere?.test(f)));
+                // Newest first, as the tool description promises.
+                const mtime = (f) => { try {
+                    return fs.statSync(path.join(realRoot, f)).mtimeMs;
+                }
+                catch {
+                    return 0;
+                } };
+                const hits = all.map((f) => [f, mtime(f)])
+                    .sort((x, y) => y[1] - x[1]).slice(0, MAX_RESULTS).map(([f]) => f);
+                const note = all.length > hits.length
+                    ? `\n\n[... ${all.length - hits.length} more files left out. Narrow the pattern.]` : "";
+                return {
+                    content: (hits.join("\n") || "(no matches)") + note, summary: `${all.length} files`,
+                    facts: { files: hits.length, left_out: all.length - hits.length },
+                };
             }
             case "grep": {
                 const p = (0, paths_1.resolveInside)(realRoot, String(a.path ?? ""), true);
@@ -196,18 +364,22 @@ function performFileAction(root, name, a) {
                 catch (e) {
                     return fail(`That is not a valid regular expression: ${e.message}`);
                 }
-                const globRx = a.glob ? globToRegExp(String(a.glob)) : null;
-                const files = [];
-                walk(p, realRoot, files, MAX_MAP_PATHS);
+                const globText = a.glob ? String(a.glob) : "";
+                const globRx = globText ? globToRegExp(globText) : null;
+                const globAnywhere = globText && !globText.includes("/") ? globToRegExp(`**/${globText}`) : null;
+                const files = projectFiles(p, realRoot, Number.MAX_SAFE_INTEGER, Boolean(a.include_ignored))
+                    .filter((f) => !denied(f, a.exclude));
                 const context = Math.max(0, Math.min(Number(a.context_lines ?? 0), 5));
                 const hits = [];
+                // Every match is counted, even past the cap, so the agent is told how
+                // many it did not see and can narrow the search (manual 5.3).
+                let matches = 0;
+                const matchedFiles = new Set();
                 for (const rel of files) {
-                    if (hits.length >= MAX_RESULTS)
-                        break;
                     const leaf = path.basename(rel);
                     if (!isText(leaf) || (0, paths_1.isSecret)(leaf))
                         continue;
-                    if (globRx && !globRx.test(rel))
+                    if (globRx && !globRx.test(rel) && !globAnywhere?.test(rel))
                         continue;
                     let text;
                     try {
@@ -217,9 +389,13 @@ function performFileAction(root, name, a) {
                         continue;
                     }
                     const lines = text.split("\n");
-                    for (let i = 0; i < lines.length && hits.length < MAX_RESULTS; i += 1) {
+                    for (let i = 0; i < lines.length; i += 1) {
                         if (!rx.test(lines[i]))
                             continue;
+                        matches += 1;
+                        matchedFiles.add(rel);
+                        if (hits.length >= MAX_RESULTS)
+                            continue;
                         if (context === 0)
                             hits.push(`${rel}:${i + 1}:${lines[i]}`);
                         else {
@@ -228,8 +404,15 @@ function performFileAction(root, name, a) {
                         }
                     }
                 }
-                const note = hits.length >= MAX_RESULTS ? `\n\n[... stopped at ${MAX_RESULTS} matches. Narrow the search.]` : "";
-                return ok(hits.join("\n") + note || "(no matches)", `${hits.length} matches`);
+                const leftOut = matches - hits.length;
+                const note = leftOut > 0
+                    ? `\n\n[Showing ${hits.length} of ${matches.toLocaleString("en-US")} matches in ${matchedFiles.size} files; ${leftOut.toLocaleString("en-US")} left out. Narrow the pattern, the folder or the glob.]`
+                    : "";
+                return {
+                    content: (hits.join("\n") || "(no matches)") + note,
+                    summary: `${matches} matches`,
+                    facts: { matches: hits.length, left_out: leftOut, files: matchedFiles.size },
+                };
             }
             // Bytes rather than text, and the ONLY caller is the server writing a
             // document it just built. A Word file, a deck or a PDF is not text, so it
@@ -275,11 +458,21 @@ function performFileAction(root, name, a) {
                 // watching knows that a file they already had was just replaced. "wrote"
                 // reads identically in both cases and hides exactly the one that matters.
                 const replaced = fs.existsSync(p);
+                const lineCount = content.split("\n").length - (content.endsWith("\n") ? 1 : 0);
+                if (replaced && fs.readFileSync(p, "utf8") === content) {
+                    seen.set(p, fingerprint(content));
+                    return {
+                        content: `No change: ${rel} already holds exactly this. Nothing was written.`,
+                        summary: `no change ${rel}`, facts: { changed: 0, created: 0, lines: lineCount },
+                    };
+                }
                 fs.writeFileSync(p, content, "utf8");
+                seen.set(p, fingerprint(content));
                 const size = `${content.length.toLocaleString()} characters`;
+                const facts = { changed: 1, created: replaced ? 0 : 1, lines: lineCount };
                 return replaced
-                    ? ok(`Rewrote ${rel}, replacing what was there (${size}).`, `rewrote ${rel}`)
-                    : ok(`Created ${rel} (${size}).`, `created ${rel}`);
+                    ? { ...ok(`Rewrote ${rel}, replacing what was there (${size}).`, `rewrote ${rel}`), facts }
+                    : { ...ok(`Created ${rel} (${size}).`, `created ${rel}`), facts };
             }
             case "edit_file": {
                 const rel = String(a.path ?? "");
@@ -288,6 +481,10 @@ function performFileAction(root, name, a) {
                 const oldText = String(a.old_text ?? "");
                 const n = countOf(text, oldText);
                 if (n === 0) {
+                    // Read before, and different now: somebody else changed it.
+                    const before = seen.get(p);
+                    if (before && before !== fingerprint(text))
+                        return fail(STALE(rel));
                     return fail(`Refused: that exact text is not in ${rel}. Read the file again — whitespace and indentation have to match exactly.`);
                 }
                 if (n > 1) {
@@ -300,8 +497,19 @@ function performFileAction(root, name, a) {
                 if (a.new_text === undefined || a.new_text === null) {
                     return fail(`Refused, and nothing was changed: edit_file was called for ${rel} with no replacement text. Send "new_text". To delete the matched section, pass an empty string.`);
                 }
-                fs.writeFileSync(p, text.replace(oldText, String(a.new_text)), "utf8");
-                return ok(`Edited ${rel}.`, `edited ${rel}`);
+                const newText = String(a.new_text);
+                if (newText === oldText) {
+                    return {
+                        content: `No change: the replacement is the same as the text already in ${rel}. Nothing was written.`,
+                        summary: `no change ${rel}`, facts: { changed: 0 },
+                    };
+                }
+                // A function as the replacement, so a `$` in the new text is written
+                // as a `$` and never read as a pattern.
+                const next = text.replace(oldText, () => newText);
+                fs.writeFileSync(p, next, "utf8");
+                seen.set(p, fingerprint(next));
+                return { ...ok(`Edited ${rel}.`, `edited ${rel}`), facts: lineCounts(oldText, newText) };
             }
             case "multi_edit": {
                 const rel = String(a.path ?? "");
@@ -311,6 +519,11 @@ function performFileAction(root, name, a) {
                 for (let i = 0; i < edits.length; i += 1) {
                     const from = String(edits[i].old_text ?? "");
                     const n = countOf(next, from);
+                    if (n === 0 && i === 0) {
+                        const before = seen.get(p);
+                        if (before && before !== fingerprint(next))
+                            return fail(STALE(rel));
+                    }
                     if (n !== 1) {
                         return fail(`Refused, and nothing was changed: edit ${i + 1} of ${edits.length} matches ${n} times in ${rel}. Every edit has to match exactly once.`);
                     }
@@ -320,10 +533,24 @@ function performFileAction(root, name, a) {
                     if (to === undefined || to === null) {
                         return fail(`Refused, and nothing was changed: edit ${i + 1} of ${edits.length} for ${rel} has no replacement text. Send "new_text". To delete the matched section, pass an empty string.`);
                     }
-                    next = next.replace(from, String(to));
+                    next = next.replace(from, () => String(to));
+                }
+                const original = fs.readFileSync(p, "utf8");
+                if (next === original) {
+                    return {
+                        content: `No change: those edits leave ${rel} exactly as it was. Nothing was written.`,
+                        summary: `no change ${rel}`, facts: { changed: 0 },
+                    };
                 }
                 fs.writeFileSync(p, next, "utf8");
-                return ok(`Applied ${edits.length} edits to ${rel}.`, `${edits.length} edits`);
+                seen.set(p, fingerprint(next));
+                const counted = edits.map((e) => trimmedCounts(String(e.old_text ?? ""), String(e.new_text ?? "")));
+                const removed = counted.reduce((t, c) => t + c[0], 0);
+                const added = counted.reduce((t, c) => t + c[1], 0);
+                return {
+                    ...ok(`Applied ${edits.length} edits to ${rel}.`, `${edits.length} edits`),
+                    facts: { changed: 1, lines_removed: removed, lines_added: added },
+                };
             }
             case "create_dir": {
                 const rel = String(a.path ?? "");
@@ -348,8 +575,11 @@ function performFileAction(root, name, a) {
         }
     }
     catch (err) {
-        if (err instanceof paths_1.OutsideWorkspace)
-            return fail(err.message);
+        // The whole refusal, path and real location included, however long the
+        // path (manual 2.4). An ordinary failure summary stops at 200 characters.
+        if (err instanceof paths_1.OutsideWorkspace) {
+            return { content: err.message, isError: true, summary: err.message.slice(0, 2000) };
+        }
         const e = err;
         if (e.code === "ENOENT")
             return fail(`No such file: ${a.path ?? ""}`);