@illuminis/comprism 0.1.4 → 0.1.6

package/out/machine/executor/files.d.ts

@@ -0,0 +1,2 @@
+import { RunResult } from "./shell";
+export declare function performFileAction(root: string, name: string, a: Record<string, unknown>): RunResult;

package/out/machine/executor/files.js

@@ -0,0 +1,590 @@
+"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.performFileAction = performFileAction;
+/**
+ * The file actions, on a real filesystem.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D1 to D16 and E6 to E8.
+ *
+ * The same twelve actions the browser performs, with the same refusals, against
+ * a real disk. **The refusals are the part worth reading**: an ambiguous edit,
+ * a path outside the project, a credentials file. An executor that reads and
+ * 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",
+    ".turbo", ".cache", "target", "vendor", ".idea", "Pods", ".gradle",
+    ".terraform", ".serverless", "site-packages",
+]);
+const TEXT_EXT = new Set([
+    "ts", "tsx", "js", "jsx", "mjs", "cjs", "py", "rb", "go", "rs", "java", "kt",
+    "swift", "c", "h", "cc", "cpp", "hpp", "cs", "php", "sh", "bash", "zsh",
+    "sql", "html", "css", "scss", "less", "json", "jsonc", "yaml", "yml", "toml",
+    "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();
+    if (!lower.includes("."))
+        return ["makefile", "dockerfile", "gitignore"].includes(lower);
+    return TEXT_EXT.has(lower.split(".").pop());
+}
+function ok(content, summary) {
+    return { content, summary: summary ?? content.split("\n")[0].slice(0, 200) };
+}
+function fail(content) {
+    return { content, isError: true, summary: content.slice(0, 200) };
+}
+/** 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;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (out.length >= limit)
+            return;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            // 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, all);
+        }
+        else if (e.isFile()) {
+            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 = "";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                out += ".*";
+                i += 1;
+                if (pattern[i + 1] === "/")
+                    i += 1;
+            }
+            else
+                out += "[^/]*";
+        }
+        else if (ch === "?")
+            out += "[^/]";
+        else
+            out += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    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;
+    let n = 0, at = haystack.indexOf(needle);
+    while (at !== -1) {
+        n += 1;
+        at = haystack.indexOf(needle, at + needle.length);
+    }
+    return n;
+}
+function performFileAction(root, name, a) {
+    const realRoot = fs.realpathSync(root);
+    try {
+        switch (name) {
+            case "read_file": {
+                const rel = String(a.path ?? "");
+                if ((0, paths_1.isSecret)(rel)) {
+                    return fail(`Refused: ${rel} holds credentials, and credentials are never read into a prompt.`);
+                }
+                const p = (0, paths_1.resolveInside)(realRoot, rel, true);
+                if (!isText(path.basename(p))) {
+                    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.`);
+                }
+                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);
+                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) {
+                    // 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 {
+                    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 = 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 = 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);
+                let rx;
+                try {
+                    rx = new RegExp(String(a.pattern ?? ""), a.case_sensitive ? "" : "i");
+                }
+                catch (e) {
+                    return fail(`That is not a valid regular expression: ${e.message}`);
+                }
+                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) {
+                    const leaf = path.basename(rel);
+                    if (!isText(leaf) || (0, paths_1.isSecret)(leaf))
+                        continue;
+                    if (globRx && !globRx.test(rel) && !globAnywhere?.test(rel))
+                        continue;
+                    let text;
+                    try {
+                        text = fs.readFileSync(path.join(realRoot, rel), "utf8");
+                    }
+                    catch {
+                        continue;
+                    }
+                    const lines = text.split("\n");
+                    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 {
+                            const from = Math.max(0, i - context), to = Math.min(lines.length, i + context + 1);
+                            hits.push(`${rel}:${i + 1}:\n${lines.slice(from, to).join("\n")}`);
+                        }
+                    }
+                }
+                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
+            // cannot come down the ordinary write, and a person who asked for a deck
+            // wants it in the folder they are standing in rather than behind a link.
+            //
+            // Deliberately NOT offered to the model. It is issued by the loop after
+            // `make_document`, in the same way the project's instruction file is read
+            // without the model asking. A model that could write arbitrary bytes into
+            // a repository would be a way to put something in a file that no diff
+            // shows and nobody reviews.
+            case "write_bytes": {
+                const rel = String(a.path ?? "");
+                if (a.base64 === undefined || a.base64 === null) {
+                    return fail(`Refused, and nothing was written: write_bytes was called for ${rel} with no content.`);
+                }
+                const p = (0, paths_1.resolveInside)(realRoot, rel, false);
+                fs.mkdirSync(path.dirname(p), { recursive: true });
+                const replaced = fs.existsSync(p);
+                const bytes = Buffer.from(String(a.base64), "base64");
+                fs.writeFileSync(p, bytes);
+                return ok(`${replaced ? "Replaced" : "Saved"} ${rel} (${bytes.length.toLocaleString()} bytes).`, `${replaced ? "replaced" : "saved"} ${rel}`);
+            }
+            case "write_file": {
+                const rel = String(a.path ?? "");
+                // A call that arrives WITHOUT content is a malformed call, not a request
+                // for an empty file. Treating the two as the same is how a whole study
+                // was lost on 11 September 2026: three of four builds saved a blank page,
+                // this returned "ok", and nobody found out until the files were measured.
+                // The model was not at fault - it was told the write succeeded, and on one
+                // run it tried three times and was told so three times.
+                //
+                // An empty file is still reachable, deliberately, with content: "".
+                if (a.content === undefined || a.content === null) {
+                    return fail(`Refused, and nothing was written: write_file was called for ${rel} with no content at all. Send the file's full text in "content". To create a genuinely empty file, pass an empty string.`);
+                }
+                const p = (0, paths_1.resolveInside)(realRoot, rel, false);
+                fs.mkdirSync(path.dirname(p), { recursive: true });
+                const content = String(a.content);
+                // Whether this REPLACED something is checked before the write, because
+                // afterwards there is nothing left to tell from. Writing no longer stops
+                // to ask, so saying which of the two happened is the only way a person
+                // 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}`), facts }
+                    : { ...ok(`Created ${rel} (${size}).`, `created ${rel}`), facts };
+            }
+            case "edit_file": {
+                const rel = String(a.path ?? "");
+                const p = (0, paths_1.resolveInside)(realRoot, rel, true);
+                const text = fs.readFileSync(p, "utf8");
+                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) {
+                    return fail(`Refused: that text appears ${n} times in ${rel}, so it is not clear which one you mean. Include more surrounding lines to make the target unique.`);
+                }
+                // Missing replacement text used to DELETE the matched section and report
+                // "edited". Worse than the write case, because it destroys work that was
+                // already there. Deleting a section on purpose still works, with
+                // new_text set to an empty string.
+                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.`);
+                }
+                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 ?? "");
+                const p = (0, paths_1.resolveInside)(realRoot, rel, true);
+                const edits = a.edits ?? [];
+                let next = fs.readFileSync(p, "utf8");
+                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.`);
+                    }
+                    // Same rule as edit_file, checked before anything is written, so a bad
+                    // edit halfway down a list cannot leave the file half changed.
+                    const to = edits[i].new_text;
+                    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));
+                }
+                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");
+                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 ?? "");
+                fs.mkdirSync((0, paths_1.resolveInside)(realRoot, rel, false), { recursive: true });
+                return ok(`Created ${rel}.`, `created ${rel}`);
+            }
+            case "delete_file": {
+                const rel = String(a.path ?? "");
+                fs.unlinkSync((0, paths_1.resolveInside)(realRoot, rel, true));
+                return ok(`Deleted ${rel}.`, `deleted ${rel}`);
+            }
+            case "move_file": {
+                const rel = String(a.path ?? ""), to = String(a.to ?? "");
+                const from = (0, paths_1.resolveInside)(realRoot, rel, true);
+                const dest = (0, paths_1.resolveInside)(realRoot, to, false);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.renameSync(from, dest);
+                return ok(`Moved ${rel} to ${to}.`, `moved ${rel}`);
+            }
+            default:
+                return fail(`This client cannot do that: ${name}`);
+        }
+    }
+    catch (err) {
+        // 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 ?? ""}`);
+        if (e.code === "EACCES")
+            return fail(`Permission denied: ${a.path ?? ""}`);
+        return fail(`This action could not be completed: ${e.message}`);
+    }
+}

package/out/machine/executor/git.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Reading the repository, and recording work in it.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items D23 to D27.
+ *
+ * **Pushing is the only thing here that sends anything anywhere**, and it is
+ * the only one the server has to have allowed first. Pull requests, reviews,
+ * checks and releases are not git operations at all: they go through GitHub's
+ * own API, on the server, because they need the tenant's credential and that
+ * must never be sent to a client.
+ *
+ * So the split is by what each thing needs. A push needs the repository, which
+ * is here. A pull request needs the credential, which is there.
+ *
+ * Every command goes through `runCommand`, so the folder boundary, the trimmed
+ * environment, the timeout and the output cap all apply here too rather than
+ * being reimplemented for git.
+ */
+import { RunResult, ShellOptions } from "./shell";
+export declare function gitStatus(opts: ShellOptions): Promise<RunResult>;
+export declare function gitDiff(opts: ShellOptions & {
+    path?: string;
+    staged?: boolean;
+}): Promise<RunResult>;
+export declare function gitLog(opts: ShellOptions & {
+    path?: string;
+    limit?: number;
+}): Promise<RunResult>;
+export declare function gitBranch(name: string, opts: ShellOptions): Promise<RunResult>;
+export declare function gitCommit(message: string, opts: ShellOptions & {
+    paths?: string[];
+}): Promise<RunResult>;
+/** Send commits to the remote.
+ *
+ *  Reached only after the server has allowed it: the branch is one the person
+ *  named for this repository, it is not a branch the project is built from, and
+ *  they have just confirmed it. This function does not re-decide any of that,
+ *  and it must not: a client that could decide whether it may publish is a
+ *  client that could grant itself permission.
+ *
+ *  **There is no force push and there is no upstream rewrite.** Not as an
+ *  option, not behind a flag. Everything on the remote stays recoverable by
+ *  whoever is working from it.
+ */
+export declare function gitPush(branch: string, opts: ShellOptions & {
+    createRemote?: boolean;
+}): Promise<RunResult>;