atom-agent 1.0.0 → 1.2.0

package/dist/telemetry.js

@@ -436,6 +436,8 @@ export function summarizeTelemetry(sessions) {
         compactionUsage: {},
         compactionReported: false,
         retries: 0,
+        cacheHits: 0,
+        repetitionHits: 0,
         outcomes: emptyOutcomes(),
         byTool: [],
         avgModelLatencyMs: null,
@@ -465,6 +467,14 @@ export function summarizeTelemetry(sessions) {
                         agg.usageReported = true;
                 }
                 agg.retries += typeof t.retryCount === "number" ? t.retryCount : 0;
+                if (t.loop) {
+                    if (typeof t.loop.cacheHits === "number" && t.loop.cacheHits > 0) {
+                        agg.cacheHits += Math.floor(t.loop.cacheHits);
+                    }
+                    if (typeof t.loop.repetitionHits === "number" && t.loop.repetitionHits > 0) {
+                        agg.repetitionHits += Math.floor(t.loop.repetitionHits);
+                    }
+                }
                 if (Array.isArray(t.modelCalls)) {
                     for (const m of t.modelCalls) {
                         agg.modelCalls += 1;
@@ -782,6 +792,51 @@ export class TelemetryRecorder {
             // never throw
         }
     }
+    // Attach the loop-harness per-turn rollup (LoopStats from the agent loop,
+    // wired via AgenticOpts.onLoopStats in the App). Merges onto the open turn;
+    // later reports overwrite (the loop reports once, but a retry-safe merge
+    // keeps the newest). No-op when disabled, unknown turn, or bad input.
+    // Never throws. Safe to call before endTurn (success path) — endTurn keeps
+    // turn.loop intact; failed/cancelled turns keep it too (what was attempted).
+    recordLoopStats(turnId, summary) {
+        try {
+            if (!this.enabled || !turnId)
+                return;
+            const turn = this.openTurns.get(turnId);
+            if (!turn)
+                return;
+            if (typeof summary !== "object" || summary === null)
+                return;
+            const s = summary;
+            const num = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+            const signed = (v) => typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : undefined;
+            const loop = {
+                cacheHits: num(s["cacheHits"]) ?? 0,
+                repetitionHits: num(s["repetitionHits"]) ?? 0,
+                failures: num(s["failures"]) ?? 0,
+                truncations: num(s["truncationNotices"] ?? s["truncations"]) ?? 0,
+                contextGrowthChars: signed(s["contextGrowthChars"]) ?? 0,
+                loopDurationMs: num(s["durationMs"] ?? s["loopDurationMs"]) ?? 0,
+            };
+            const bottleneck = s["bottleneck"];
+            const bName = typeof bottleneck?.["name"] === "string" ? bottleneck["name"] : undefined;
+            const bMs = num(bottleneck?.["durationMs"] ?? bottleneck?.["ms"] ?? s["bottleneckMs"]) ?? undefined;
+            if (bName && bName.length > 0) {
+                loop.bottleneckName = bName.slice(0, 80);
+                if (bMs !== undefined)
+                    loop.bottleneckMs = bMs;
+            }
+            else if (typeof s["bottleneckName"] === "string" && s["bottleneckName"].length > 0) {
+                loop.bottleneckName = s["bottleneckName"].slice(0, 80);
+                if (bMs !== undefined)
+                    loop.bottleneckMs = bMs;
+            }
+            turn.loop = loop;
+        }
+        catch {
+            // never throw
+        }
+    }
     upsertIteration(turn, step, modelCallId, toolCallId) {
         try {
             let iter = turn.iterations.find((i) => i.step === step);

package/dist/tools/dir-cache.js

@@ -0,0 +1,214 @@
+// Fast directory enumeration for search tools (grep/glob).
+//
+// Problem (measured): every grep/glob recursively walked the repo and
+// stated every entry — ~360ms per glob and ~2s per grep on a 3000-file
+// tree, paid on EVERY call. Two fixes, both behavior-preserving:
+//
+// 1. git fast path: `git ls-files` (tracked) + `--others --exclude-standard`
+//    (untracked, non-ignored) lists the same tree without recursion and
+//    skips ignored build output. Verified: both spellings emit paths
+//    relative to the working directory they run in. Untracked source files
+//    ARE included (no "new file invisible" regression); SKIP_DIRS segments
+//    (node_modules/.git) are filtered after, so the "never searched"
+//    contract holds even for tracked junk. Any failure (non-git dir, no git
+//    binary, timeout) falls back to the recursive walker byte-identically.
+// 2. mtime-checked listing cache + exact invalidation: a cached listing is
+//    reused only while the directory mtime is unchanged, AND every
+//    in-process mutation path invalidates (write/edit drop ancestor listings
+//    — nested creates don't move the parent mtime, so mtime alone is NOT
+//    enough; any bash execution clears all — a command can touch anything).
+//    Only out-of-process edits (user's editor between calls) stay TTL-bound
+//    (15s), documented and accepted: all tool-driven flows are exact.
+//
+// Deliberate non-goal: no ripgrep binary dependency. Measured `rg --files`
+// spawn alone costs ~80ms on Windows — slower than the walker on typical
+// repos — with regex-dialect and hidden/ignore parity risks. Revisit only if
+// walker numbers stay slow after this (they don't — see benchmarks).
+//
+// Kill switch: ATOM_FAST_LIST=0 forces the legacy walker every time.
+// Best-effort throughout; never throws across the tool boundary.
+import { execFile } from "node:child_process";
+import { promises as fsp } from "node:fs";
+import * as path from "node:path";
+import { SKIP_DIRS } from "./shared.js";
+const LISTING_TTL_MS = 15_000;
+const LISTING_MAX_ENTRIES = 50;
+const GIT_TIMEOUT_MS = 15_000;
+const listingCache = new Map();
+const cacheStats = { hits: 0, misses: 0, stores: 0, gitUses: 0, walkerUses: 0 };
+export function fastListEnabled() {
+    const raw = process.env.ATOM_FAST_LIST;
+    if (raw === undefined)
+        return true;
+    const v = raw.trim().toLowerCase();
+    return !(v === "0" || v === "false" || v === "no" || v === "off");
+}
+// Recursive walker (legacy contract): cwd-relative posix paths, SKIP_DIRS
+// pruned, files only. Used directly when the fast path is off/unavailable.
+export async function walkFiles(absDir, cwd, out) {
+    const entries = await fsp.readdir(absDir, { withFileTypes: true });
+    for (const e of entries) {
+        if (SKIP_DIRS.has(e.name))
+            continue;
+        const full = path.join(absDir, e.name);
+        if (e.isDirectory()) {
+            await walkFiles(full, cwd, out);
+        }
+        else if (e.isFile()) {
+            out.push(path.relative(cwd, full).split(path.sep).join("/"));
+        }
+    }
+}
+function gitFile(args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, { cwd, timeout: GIT_TIMEOUT_MS, windowsHide: true }, (err, stdout) => {
+            if (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
+            resolve(typeof stdout === "string" ? stdout : String(stdout ?? ""));
+        });
+    });
+}
+function toCwdRel(absDir, cwd, dirRel) {
+    const prefix = path.relative(cwd, absDir).split(path.sep).join("/");
+    if (!prefix || prefix === ".")
+        return dirRel;
+    return `${prefix}/${dirRel}`;
+}
+// Public for the ripgrep adapter: rg emits dir-relative paths, but the
+// enumerated contract (and therefore outputs) is cwd-relative — which may
+// climb out of the tree (`../../..`) when the search dir sits outside cwd.
+// Exported so both paths share the one mapping (never duplicated logic).
+export function rgRelToCwdRel(absDir, cwd, dirRel) {
+    return toCwdRel(absDir, cwd, dirRel);
+}
+function filterSkipped(relPaths) {
+    return relPaths.filter((rel) => {
+        if (!rel)
+            return false;
+        for (const seg of rel.split("/")) {
+            if (SKIP_DIRS.has(seg))
+                return false;
+        }
+        return true;
+    });
+}
+// Git enumeration: tracked + untracked-non-ignored in ONE invocation, as
+// cwd-relative posix paths. Verified: both spellings emit paths relative to
+// the directory git runs in. Outside a repo (or no git binary) the command
+// fails and this returns null — the caller falls back to the walker.
+async function gitListFiles(absDir, cwd) {
+    let raw;
+    try {
+        raw = await gitFile(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], absDir);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const seen = new Set();
+        const out = [];
+        for (const entry of raw.split("\0")) {
+            if (!entry)
+                continue;
+            const rel = toCwdRel(absDir, cwd, entry.split(path.sep).join("/"));
+            if (!seen.has(rel)) {
+                seen.add(rel);
+                out.push(rel);
+            }
+        }
+        return filterSkipped(out);
+    }
+    catch {
+        return null;
+    }
+}
+async function dirMtimeMs(absDir) {
+    try {
+        return (await fsp.stat(absDir)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+// List files under absDir as cwd-relative posix paths (walkFiles contract).
+// Fast path: mtime-validated cache → git enumeration → walker fallback.
+// Walker results cache too (the mtime check is equally valid for them).
+export async function listFiles(absDir, cwd) {
+    const key = `${cwd}\n${absDir}`;
+    if (fastListEnabled()) {
+        const mtime = await dirMtimeMs(absDir);
+        const hit = listingCache.get(key);
+        if (hit && mtime !== null && hit.mtimeMs === mtime && Date.now() - hit.storedAt < LISTING_TTL_MS) {
+            // LRU refresh.
+            listingCache.delete(key);
+            listingCache.set(key, hit);
+            cacheStats.hits += 1;
+            return [...hit.entries];
+        }
+        cacheStats.misses += 1;
+        const git = await gitListFiles(absDir, cwd);
+        if (git !== null) {
+            cacheStats.gitUses += 1;
+            storeListing(key, git, mtime);
+            return [...git];
+        }
+    }
+    cacheStats.walkerUses += 1;
+    const out = [];
+    await walkFiles(absDir, cwd, out);
+    if (fastListEnabled()) {
+        storeListing(key, out, await dirMtimeMs(absDir));
+    }
+    return out;
+}
+function storeListing(key, entries, mtimeMs) {
+    try {
+        listingCache.delete(key);
+        while (listingCache.size >= LISTING_MAX_ENTRIES) {
+            const oldest = listingCache.keys().next();
+            if (oldest.done)
+                break;
+            listingCache.delete(oldest.value);
+        }
+        listingCache.set(key, { entries: [...entries], mtimeMs: mtimeMs ?? -1, storedAt: Date.now() });
+        cacheStats.stores += 1;
+    }
+    catch {
+        // cache failures never break search
+    }
+}
+export function clearDirListingCache() {
+    listingCache.clear();
+}
+// Drop every listing whose directory is the file itself or an ancestor of it
+// (a mutation inside the tree can change the listing). Called by write/edit
+// next to the read-cache invalidation. Never throws.
+export function invalidateListingsForFile(absFilePath) {
+    try {
+        if (typeof absFilePath !== "string" || absFilePath.length === 0)
+            return;
+        const target = path.resolve(absFilePath);
+        for (const key of [...listingCache.keys()]) {
+            const splitAt = key.indexOf("\n");
+            const absDir = splitAt >= 0 ? key.slice(splitAt + 1) : key;
+            if (target === absDir || target.startsWith(absDir + path.sep)) {
+                listingCache.delete(key);
+            }
+        }
+    }
+    catch {
+        // never throw across the tool boundary
+    }
+}
+export function getDirListingStats() {
+    return { ...cacheStats, size: listingCache.size };
+}
+export function resetDirListingStats() {
+    cacheStats.hits = 0;
+    cacheStats.misses = 0;
+    cacheStats.stores = 0;
+    cacheStats.gitUses = 0;
+    cacheStats.walkerUses = 0;
+}

package/dist/tools/filesystem.js

@@ -5,7 +5,9 @@ import * as path from "node:path";
 import { capturePriorBytes } from "../snapshots.js";
 import { contentHash, fingerprintKey, readFingerprints } from "./fingerprints.js";
 import { appendOverflow } from "./overflow.js";
-import { err, invalidCall, READ_CHAR_CAP, resolveSandbox } from "./shared.js";
+import { getCachedRead, invalidatePath, normalizeReadWindow, setCachedRead } from "./read-cache.js";
+import { invalidateListingsForFile } from "./dir-cache.js";
+import { err, invalidCall, READ_CHAR_CAP, resolveSandbox, truncateHead } from "./shared.js";
 // offset/limit are 1-based line numbers. Output capped at ~64KB.
 export async function readTool(args, cwd = process.cwd()) {
     try {
@@ -24,6 +26,21 @@ export async function readTool(args, cwd = process.cwd()) {
             const lines = entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
             return `Directory listing for ${args.path}:\n${lines.join("\n")}`;
         }
+        // Read-cache fast path: same abs + window + unchanged mtime/size skips
+        // disk I/O. The stored hash refreshes the stale-read fingerprint so
+        // read→read→edit chains keep working without re-hashing.
+        const { offset: normOffset, limit: normLimit } = normalizeReadWindow(args.offset, args.limit);
+        try {
+            const statInfo = { mtimeMs: st.mtimeMs ?? 0, size: st.size ?? 0 };
+            const hit = getCachedRead(r.abs, normOffset, normLimit, statInfo);
+            if (hit) {
+                readFingerprints.set(fingerprintKey(r.abs), hit.hash);
+                return hit.result;
+            }
+        }
+        catch {
+            // cache lookup never breaks reads
+        }
         let text;
         try {
             text = await fsp.readFile(r.abs, "utf8");
@@ -31,7 +48,8 @@ export async function readTool(args, cwd = process.cwd()) {
         catch {
             return err(`cannot read file: ${args.path}`);
         }
-        readFingerprints.set(fingerprintKey(r.abs), contentHash(text));
+        const hash = contentHash(text);
+        readFingerprints.set(fingerprintKey(r.abs), hash);
         if (text.length === 0)
             return "";
         const offset = Math.max(1, Math.floor(args.offset ?? 1));
@@ -40,7 +58,15 @@ export async function readTool(args, cwd = process.cwd()) {
         let out = window.map((line, i) => `${offset + i}: ${line}`).join("\n");
         if (out.length > READ_CHAR_CAP) {
             const full = out;
-            out = appendOverflow(full.slice(0, READ_CHAR_CAP), "\n[truncated: output exceeded 64KB]", "file output", full);
+            const t = truncateHead(full, READ_CHAR_CAP, "\n[truncated: output exceeded 64KB]");
+            out = appendOverflow(t.head, t.note, "file output", full);
+        }
+        try {
+            const statInfo = { mtimeMs: st.mtimeMs ?? 0, size: st.size ?? 0 };
+            setCachedRead(r.abs, normOffset, normLimit, out, statInfo, hash);
+        }
+        catch {
+            // cache store never breaks reads
         }
         return out;
     }
@@ -61,6 +87,13 @@ export async function writeTool(args, cwd = process.cwd()) {
         await fsp.mkdir(path.dirname(r.abs), { recursive: true });
         await fsp.writeFile(r.abs, args.content, "utf8");
         readFingerprints.set(fingerprintKey(r.abs), contentHash(args.content));
+        try {
+            invalidatePath(r.abs);
+            invalidateListingsForFile(r.abs);
+        }
+        catch {
+            // cache invalidation never breaks writes
+        }
         return `Wrote ${Buffer.byteLength(args.content, "utf8")} bytes to ${args.path}`;
     }
     catch (e) {
@@ -102,6 +135,13 @@ export async function editTool(args, cwd = process.cwd()) {
         await capturePriorBytes(r.abs, `edit ${args.path}`);
         await fsp.writeFile(r.abs, next, "utf8");
         readFingerprints.set(key, contentHash(next));
+        try {
+            invalidatePath(r.abs);
+            invalidateListingsForFile(r.abs);
+        }
+        catch {
+            // cache invalidation never breaks edits
+        }
         return `Edited ${args.path}: replaced ${args.replaceAll ? count : 1} occurrence(s)`;
     }
     catch (e) {

package/dist/tools/read-cache.js

@@ -0,0 +1,160 @@
+// Read-through cache for file reads: repeated `read` calls for the same
+// path+window skip disk I/O when the file hasn't changed. Correctness first:
+//
+// - Key: absolute path + offset + limit (different windows are different keys).
+// - Validation: file mtimeMs + size checked on every hit (one stat, cheap).
+//   A mismatch → miss → re-read + re-store. External edits can never serve
+//   stale bytes beyond a stat race.
+// - Invalidation: write/edit/delete paths call invalidatePath(abs) — the
+//   write/edit executors do this, so read→write→read chains never go stale.
+//   A global version bump (invalidateAll) covers tree-wide mutations.
+// - Scope: successes only (errors never cache — a transient ENOENT must not
+//   poison later reads). Directory listings never cache (readdir is already
+//   cheap and highly mutable).
+// - Bounds: LRU cap (default 100 entries) + TTL (default 30s). Disable with
+//   ATOM_READ_CACHE=0. All best-effort, never throws.
+//
+// Measurable win: explore loops re-read the same files (read after grep,
+// re-read before edit, parallel batches reading shared context). Each hit
+// saves a full readFile + split + 64KB-format pass.
+//
+// Stats (for loop instrumentation + tests): hits, misses, stores, invalidations.
+import * as path from "node:path";
+const DEFAULT_MAX_ENTRIES = 100;
+const DEFAULT_TTL_MS = 30_000;
+const cache = new Map();
+const stats = { hits: 0, misses: 0, stores: 0, invalidations: 0, size: 0 };
+function cacheEnabled() {
+    const raw = process.env.ATOM_READ_CACHE;
+    if (raw === undefined)
+        return true;
+    const v = raw.trim().toLowerCase();
+    return !(v === "0" || v === "false" || v === "no" || v === "off");
+}
+function ttlMs() {
+    const raw = process.env.ATOM_READ_CACHE_TTL_MS;
+    if (raw !== undefined) {
+        const n = Number(raw.trim());
+        if (Number.isFinite(n) && n > 0)
+            return Math.min(Math.floor(n), 300_000);
+    }
+    return DEFAULT_TTL_MS;
+}
+function maxEntries() {
+    const raw = process.env.ATOM_READ_CACHE_MAX;
+    if (raw !== undefined) {
+        const n = Number(raw.trim());
+        if (Number.isFinite(n) && n > 0)
+            return Math.min(Math.floor(n), 1000);
+    }
+    return DEFAULT_MAX_ENTRIES;
+}
+export function readCacheKey(abs, offset, limit) {
+    return `${abs}\n${offset}\n${limit}`;
+}
+export function normalizeReadWindow(offset, limit) {
+    const o = typeof offset === "number" && Number.isFinite(offset) ? Math.max(1, Math.floor(offset)) : 1;
+    const l = typeof limit === "number" && Number.isFinite(limit)
+        ? Math.max(1, Math.floor(limit))
+        : Number.MAX_SAFE_INTEGER;
+    return { offset: o, limit: l };
+}
+// Lookup by absolute path + window. `stat` must be the fresh
+// {mtimeMs, size} of the file (the caller already stats before reading).
+// Returns the cached {result, hash} on hit, null on miss. Never throws.
+export function getCachedRead(abs, offset, limit, stat) {
+    if (!cacheEnabled()) {
+        stats.misses += 1;
+        return null;
+    }
+    const key = readCacheKey(abs, offset, limit);
+    const entry = cache.get(key);
+    if (!entry) {
+        stats.misses += 1;
+        return null;
+    }
+    if (Date.now() - entry.storedAt > ttlMs()) {
+        cache.delete(key);
+        stats.size = cache.size;
+        stats.misses += 1;
+        return null;
+    }
+    if (entry.mtimeMs !== stat.mtimeMs || entry.size !== stat.size) {
+        cache.delete(key);
+        stats.size = cache.size;
+        stats.misses += 1;
+        return null;
+    }
+    // LRU refresh: re-insert so the oldest key stays evictable first.
+    cache.delete(key);
+    cache.set(key, entry);
+    stats.hits += 1;
+    return { result: entry.result, hash: entry.hash };
+}
+// Store a successful file-read result. Never throws; evicts oldest first.
+export function setCachedRead(abs, offset, limit, result, stat, hash) {
+    try {
+        if (!cacheEnabled() || typeof result !== "string")
+            return;
+        const key = readCacheKey(abs, offset, limit);
+        cache.delete(key);
+        while (cache.size >= maxEntries()) {
+            const oldest = cache.keys().next();
+            if (oldest.done)
+                break;
+            cache.delete(oldest.value);
+        }
+        cache.set(key, { result, hash, mtimeMs: stat.mtimeMs, size: stat.size, storedAt: Date.now() });
+        stats.size = cache.size;
+        stats.stores += 1;
+    }
+    catch {
+        // cache failures never break reads
+    }
+}
+// Drop every entry for one absolute path (all windows). Called by
+// write/edit/delete paths. Never throws.
+export function invalidatePath(abs) {
+    try {
+        const prefix = `${abs}\n`;
+        let dropped = 0;
+        for (const key of [...cache.keys()]) {
+            if (key === abs || key.startsWith(prefix)) {
+                cache.delete(key);
+                dropped += 1;
+            }
+        }
+        // Also match callers that pass a relative display path: compare resolved
+        // basenames as a fallback so nothing obviously stale survives.
+        if (dropped === 0 && typeof abs === "string") {
+            const resolved = path.resolve(abs);
+            const resolvedPrefix = `${resolved}\n`;
+            for (const key of [...cache.keys()]) {
+                if (key === resolved || key.startsWith(resolvedPrefix)) {
+                    cache.delete(key);
+                    dropped += 1;
+                }
+            }
+        }
+        if (dropped > 0)
+            stats.invalidations += dropped;
+        stats.size = cache.size;
+    }
+    catch {
+        // never throw across the tool boundary
+    }
+}
+export function clearReadCache() {
+    cache.clear();
+    stats.size = 0;
+}
+export function getReadCacheStats() {
+    return { ...stats, size: cache.size };
+}
+export function resetReadCacheStats() {
+    stats.hits = 0;
+    stats.misses = 0;
+    stats.stores = 0;
+    stats.invalidations = 0;
+    stats.size = cache.size;
+}

package/dist/tools/registry.js

@@ -375,6 +375,85 @@ export function describeToolCall(name, args) {
             return `⚙ ${name}`;
     }
 }
+// Shared byte cap for approve-time file reads (preview + BEFORE capture).
+export const APPROVAL_PREVIEW_MAX_BYTES = 1_000_000;
+// Extension → highlight family (see ui/highlight.ts). Conservative: only
+// extensions we are confident about; everything else stays null (plain).
+const PREVIEW_LANG_BY_EXT = {
+    ts: "c",
+    tsx: "c",
+    mts: "c",
+    cts: "c",
+    js: "c",
+    jsx: "c",
+    mjs: "c",
+    cjs: "c",
+    go: "c",
+    rs: "c",
+    java: "c",
+    c: "c",
+    h: "c",
+    hh: "c",
+    cc: "c",
+    cpp: "c",
+    hpp: "c",
+    cs: "c",
+    swift: "c",
+    kt: "c",
+    kts: "c",
+    php: "c",
+    py: "py",
+    pyi: "py",
+    rb: "py",
+    sh: "sh",
+    bash: "sh",
+    zsh: "sh",
+    json: "data",
+    jsonc: "data",
+    yaml: "data",
+    yml: "data",
+    toml: "data",
+};
+export function previewLangFromPath(p) {
+    const base = p.split(/[\\/]/).pop() ?? p;
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || dot === base.length - 1)
+        return null;
+    return PREVIEW_LANG_BY_EXT[base.slice(dot + 1).toLowerCase()] ?? null;
+}
+export function previewDiffForApproval(name, args, cwd = process.cwd()) {
+    try {
+        if (name === "edit") {
+            const a = args;
+            if (typeof a.oldString !== "string" || typeof a.newString !== "string")
+                return null;
+            const p = typeof a.path === "string" ? a.path : null;
+            return { oldText: a.oldString, newText: a.newString, lang: p ? previewLangFromPath(p) : null, path: p };
+        }
+        if (name === "write") {
+            const a = args;
+            if (typeof a.content !== "string" || typeof a.path !== "string" || a.path.length === 0) {
+                return null;
+            }
+            let oldText = null;
+            try {
+                const abs = path.resolve(cwd, a.path);
+                const st = fs.statSync(abs);
+                if (st.isFile() && st.size <= APPROVAL_PREVIEW_MAX_BYTES) {
+                    oldText = fs.readFileSync(abs, "utf8");
+                }
+            }
+            catch {
+                oldText = null;
+            }
+            return { oldText, newText: a.content, lang: previewLangFromPath(a.path), path: a.path };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 // OpenAI-style function schemas sent as `tools` on the chat POST.
 export const TOOL_DEFINITIONS = [
     {
@@ -495,6 +574,7 @@ export const TOOL_DEFINITIONS = [
                 "runInBackground=true for servers/watchers/slow builds, then poll with bash_output. " +
                 "WHEN NOT to use: never for reading/writing/searching files; never destructive or exfiltrating without explicit user approval; " +
                 "don't assume a TTY. " +
+                "Shell is cmd.exe on Windows (use dir; quote paths containing spaces) and POSIX sh elsewhere — the env block names it; never probe with ls/pwd/whoami. " +
                 "Foreground returns JSON {exitCode, stdout, stderr, timedOut, ...} (streams truncate with pointers). " +
                 "Background returns {backgroundTaskId, ...} immediately; the process keeps running detached. " +
                 "PRIVILEGED: no sandbox beyond cwd+timeout.",