atom-agent 0.3.0 → 1.1.0

package/dist/tools/dir-cache.js

@@ -0,0 +1,207 @@
+// 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}`;
+}
+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

@@ -0,0 +1,149 @@
+// Filesystem executors: read/write/edit. Every mutation snapshots prior
+// bytes first (see snapshots.ts); validation failures return before capture.
+import { promises as fsp } from "node:fs";
+import * as path from "node:path";
+import { capturePriorBytes } from "../snapshots.js";
+import { contentHash, fingerprintKey, readFingerprints } from "./fingerprints.js";
+import { appendOverflow } from "./overflow.js";
+import { getCachedRead, invalidatePath, normalizeReadWindow, setCachedRead } from "./read-cache.js";
+import { invalidateListingsForFile } from "./dir-cache.js";
+import { err, invalidCall, READ_CHAR_CAP, resolveSandbox } from "./shared.js";
+// offset/limit are 1-based line numbers. Output capped at ~64KB.
+export async function readTool(args, cwd = process.cwd()) {
+    try {
+        const r = resolveSandbox(args?.path, cwd);
+        if (r.error || !r.abs)
+            return r.error ?? err("bad path");
+        let st;
+        try {
+            st = await fsp.stat(r.abs);
+        }
+        catch {
+            return err(`no such file or directory: ${args.path}`);
+        }
+        if (st.isDirectory()) {
+            const entries = await fsp.readdir(r.abs, { withFileTypes: true });
+            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");
+        }
+        catch {
+            return err(`cannot read file: ${args.path}`);
+        }
+        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));
+        const limit = Math.max(1, Math.floor(args.limit ?? Number.MAX_SAFE_INTEGER));
+        const window = text.split("\n").slice(offset - 1, offset - 1 + limit);
+        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);
+        }
+        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;
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}
+export async function writeTool(args, cwd = process.cwd()) {
+    try {
+        const r = resolveSandbox(args?.path, cwd);
+        if (r.error || !r.abs)
+            return r.error ?? err("bad path");
+        if (typeof args.content !== "string")
+            return err("content must be a string");
+        // Ticket 01 (/rewind): silent pre-mutation snapshot — every write is
+        // covered regardless of caller, and capture never fails this call.
+        await capturePriorBytes(r.abs, `write ${args.path}`);
+        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) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}
+export async function editTool(args, cwd = process.cwd()) {
+    try {
+        const r = resolveSandbox(args?.path, cwd);
+        if (r.error || !r.abs)
+            return r.error ?? err("bad path");
+        if (typeof args.oldString !== "string" || args.oldString.length === 0) {
+            return err("oldString must be a non-empty string");
+        }
+        if (typeof args.newString !== "string")
+            return err("newString must be a string");
+        let text;
+        try {
+            text = await fsp.readFile(r.abs, "utf8");
+        }
+        catch {
+            return err(`no such file or directory: ${args.path}`);
+        }
+        const key = fingerprintKey(r.abs);
+        const known = readFingerprints.get(key);
+        if (known !== undefined && contentHash(text) !== known) {
+            return invalidCall(`stale read — ${args.path} changed since you last read it. Read it again before editing`);
+        }
+        const count = text.split(args.oldString).length - 1;
+        if (count === 0)
+            return err(`no match for oldString in ${args.path}`);
+        if (count > 1 && !args.replaceAll) {
+            return err(`oldString matches ${count} times in ${args.path}; pass replaceAll=true to replace all`);
+        }
+        const next = args.replaceAll
+            ? text.split(args.oldString).join(args.newString)
+            : text.replace(args.oldString, args.newString);
+        // Ticket 01 (/rewind): silent pre-mutation snapshot (see writeTool).
+        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) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}

package/dist/tools/fingerprints.js

@@ -0,0 +1,33 @@
+// Stale-read fingerprints: readTool records a content hash per resolved
+// path; editTool refuses when the file changed since the model last read
+// it; /rewind restores refresh (or forget) the record per file.
+import { createHash } from "node:crypto";
+// Read-tracking guard: readTool records a sha1 of the full file content per
+// resolved absolute path after each successful FILE read (directory listings
+// are not tracked). editTool refuses when a record exists and the current
+// content hash differs — the file changed since the model last read it
+// (user's editor, git checkout, another tool). Limit: files never read this
+// session have no record, so the guard cannot catch those (e.g. content
+// learned via grep). Successful writeTool/editTool refresh the record so
+// read→write→edit and edit→edit chains never false-refuse; identical
+// rewrites (same hash) never trigger.
+export const readFingerprints = new Map();
+export function fingerprintKey(abs) {
+    return abs;
+}
+export function contentHash(text) {
+    return createHash("sha1").update(text, "utf8").digest("hex");
+}
+// Ticket 01 (/rewind): a restore writes bytes behind these executors, so the
+// caller refreshes (or forgets, on deletion) the stale-read fingerprint per
+// restored file — otherwise the next edit would false-refuse as a stale read.
+export function refreshReadFingerprint(abs, text) {
+    if (typeof abs !== "string" || typeof text !== "string")
+        return;
+    readFingerprints.set(fingerprintKey(abs), contentHash(text));
+}
+export function forgetReadFingerprint(abs) {
+    if (typeof abs !== "string")
+        return;
+    readFingerprints.delete(fingerprintKey(abs));
+}

package/dist/tools/overflow.js

@@ -0,0 +1,76 @@
+// Overflow-to-temp spill for over-cap tool output. Best-effort, never
+// throws; stale spills prune by age on each write.
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+// under the OS temp dir (<tmpdir>/atom-overflow/), every I/O step is
+// best-effort and never throws (null/"" = keep the plain truncation note).
+// Stale spills are pruned by age on each write; the OS reclaims the rest.
+// Under-cap results never touch this path (byte-identical). Scope: byte-cap
+// truncations where the full text is in hand (read, bash, bash_output,
+// webfetch output). Count-cap notes (grep/glob "more than N matches") and
+// prompt-assembly caps (skills, compact, AGENTS.md, history) are unchanged:
+// their heads are already the most-relevant slice and re-query narrows them.
+const OVERFLOW_DIR = "atom-overflow";
+const OVERFLOW_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+let overflowSeq = 0;
+export function overflowDir() {
+    return path.join(os.tmpdir(), OVERFLOW_DIR);
+}
+function pruneOverflowFiles() {
+    try {
+        const dir = overflowDir();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            return; // nothing spilled yet — nothing to prune
+        }
+        const now = Date.now();
+        for (const name of entries) {
+            if (!name.startsWith("overflow-"))
+                continue;
+            try {
+                const p = path.join(dir, name);
+                if (now - fs.statSync(p).mtimeMs > OVERFLOW_MAX_AGE_MS)
+                    fs.rmSync(p, { force: true });
+            }
+            catch {
+                // ignore per-file failures (a stale spill is harmless)
+            }
+        }
+    }
+    catch {
+        // never throw across the tool boundary
+    }
+}
+// Write the FULL over-cap text to a temp file; null when anything fails.
+export function spillOverflow(fullText) {
+    try {
+        if (typeof fullText !== "string" || fullText.length === 0)
+            return null;
+        pruneOverflowFiles();
+        const dir = overflowDir();
+        fs.mkdirSync(dir, { recursive: true });
+        overflowSeq += 1;
+        const name = `overflow-${process.pid}-${Date.now().toString(36)}-${overflowSeq}-${randomBytes(4).toString("hex")}.txt`;
+        const file = path.join(dir, name);
+        fs.writeFileSync(file, fullText, "utf8");
+        return file;
+    }
+    catch {
+        return null;
+    }
+}
+// Head + existing truncation note + followable overflow pointer (or just
+// head + note when the spill fails — never throws, never empty-handed).
+export function appendOverflow(head, truncNote, label, fullText) {
+    const file = spillOverflow(fullText);
+    if (!file)
+        return head + truncNote;
+    return (`${head}${truncNote}\n` +
+        `[overflow: full ${label} (${fullText.length} chars) spilled to ${file} — ` +
+        `use read with offset/limit to page through it]`);
+}

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;
+}