atom-agent 1.4.0 → 1.5.0

package/dist/config.js

@@ -23,6 +23,13 @@
 //   deprecated alias for "auto")
 // - maxToolSteps: 5–100 (tool rounds per turn)
 // - compactPct: 50–95 (auto-compact percent of verified window)
+// - compactAuto: boolean (real-usage auto-compact master switch, default on;
+//   false disables AUTO-compaction only — manual /compact always works)
+// - compactReserve: reserved output buffer in tokens for the usable-limit
+//   calculation (usable = verified window − reserve; clamped 4096–100000,
+//   mirroring src/overflow.ts OVERFLOW_RESERVE_MIN/MAX — kept literal here
+//   so config.ts has no runtime import of overflow.ts, which itself reads
+//   config at runtime)
 // - telemetry: {enabled?: boolean} (local observability recording, default on)
 // - extensions: {enabled?: string[], disabled?: string[]} (per-extension
 //   enable/disable patterns over the extension name, `*`/`?` globs; disabled
@@ -122,6 +129,9 @@ function parseLevel(filePath, label) {
     const ranged = [
         { key: "maxToolSteps", min: 5, max: 100 },
         { key: "compactPct", min: 50, max: 95 },
+        // Reserve buffer bounds mirror overflow.ts (literals, not imports — see
+        // the header note on the import direction).
+        { key: "compactReserve", min: 4096, max: 100000 },
     ];
     for (const { key, min, max } of ranged) {
         const v = data[key];
@@ -140,6 +150,15 @@ function parseLevel(filePath, label) {
         }
         config[key] = clamped;
     }
+    const compactAuto = data["compactAuto"];
+    if (compactAuto !== undefined) {
+        if (typeof compactAuto === "boolean") {
+            config.compactAuto = compactAuto;
+        }
+        else {
+            bad("compactAuto", "must be a boolean");
+        }
+    }
     const network = data["network"];
     if (network !== undefined) {
         const parsed = parseNetworkPolicy(network);

package/dist/context-manager.js

@@ -30,6 +30,7 @@
 // re-architecting call sites. No cache state lives here yet by design.
 import { contextWindowFor } from "./context-windows.js";
 import { loadAtomConfig } from "./config.js";
+import { mediaWireChars } from "./media.js";
 // ---- Units ----
 // Shared chars-per-token estimator (opencode's 4ch/token preflight
 // heuristic). Floors to whole tokens; never used for billed spend, only for
@@ -41,12 +42,15 @@ export function estimateTokensForChars(chars) {
 }
 // Deterministic size of one message: string content counts as-is, anything
 // else counts stringified; assistant tool_calls and tool ids count too (they
-// ride on every POST). History chars = the sum over all messages.
+// ride on every POST). Media descriptor tokens (`[media:<id> <mime> <bytes>B]`,
+// see src/media.ts) additionally count their deterministic base64 wire cost
+// (ceil(bytes*4/3)) — history text stays small while the load stays honest.
+// History chars = the sum over all messages.
 export function messageChars(m) {
     let n = 0;
     const content = m.content;
     if (typeof content === "string") {
-        n += content.length;
+        n += content.length + mediaWireChars(content);
     }
     else if (content !== null && content !== undefined) {
         n += JSON.stringify(content).length;

package/dist/extensions.js

@@ -792,6 +792,12 @@ export async function loadExtensions(opts = {}) {
         invalidate(message) {
             staleMessage = message;
             generation += 1;
+            // Staged notices belong to the dead lineage: drop them here, or the
+            // next render drain would print pre-switch notices into the NEW
+            // session's transcript (stale async content behind a newer commit).
+            // Fresh session_start handlers re-notify via their new API.
+            // (Mirrors disposeUI below, which drops them on teardown.)
+            notifications.length = 0;
             // A dialog awaiting input across a session switch resolves safely:
             // reject with the stale message (never hangs, never fulfills into
             // the wrong session). Visible segments/widgets persist keyed by

package/dist/file-diffs.js

@@ -0,0 +1,108 @@
+// Per-turn file-diff records (ticket 06) for the compaction summary's
+// Relevant Files section.
+//
+// Each completed turn records which files it actually touched; the records
+// accumulate across turns under the session's `metadata.filediffs` key and
+// feed the summary's files section through compact.ts's existing
+// format/fit helpers (read-only — this module never changes summary output).
+//
+// WIRING CONTRACT (for the conductor follow-up; App.tsx untouched here):
+// - AFTER each completed turn commits (failed/cancelled turns are rolled
+//   back and never recorded), call `collectTurnFileDiffs(turnMessages)`
+//   with that turn's committed messages (passing the whole turn slice is
+//   safe — only assistant tool_calls are inspected; capture never changes
+//   tool behavior).
+// - When the result is non-empty, accumulate and persist:
+//     const prev = readFileDiffs(session.metadata?.["filediffs"]);
+//     const merged = mergeFileDiffs(prev, turn);
+//     updateSession(id, {
+//       metadata: { ...session.metadata, [FILE_DIFFS_METADATA_KEY]: serializeFileDiffs(merged) },
+//     });
+// - On session switch/restore, rehydrate with
+//   `readFileDiffs(next.metadata?.["filediffs"])` (missing key reads as
+//   empty; malformed values degrade to empty without failing the load).
+// - At compaction time, pass the accumulated record straight into the
+//   existing `formatTouchedFiles` / `fitSummaryWithFiles` /
+//   `fitSummaryWithFilesAndGoal` helpers from compact.ts.
+//
+// Vocabulary: this module reuses compact.ts's TouchedFiles shape
+// ({ read, modified }) — no competing file-tracking vocabulary. A path both
+// read and written lands in modified only (the write implies the read).
+// The `metadata.todos` key (ticket 05) is never read or written here.
+import { collectTouchedFiles } from "./compact.js";
+// Namespace inside the generic Session.metadata record (ticket 01).
+export const FILE_DIFFS_METADATA_KEY = "filediffs";
+export function emptyFileDiffs() {
+    return { read: [], modified: [] };
+}
+function isStringList(value) {
+    return (Array.isArray(value) && value.every((v) => typeof v === "string"));
+}
+// Collect one turn's change record from its committed messages. Write/edit-
+// style tool outcomes land in modified, read-style outcomes in read
+// (insertion order, unique, modified-wins); unparseable arguments are
+// skipped. Turns with no file changes produce an empty record — never
+// spurious entries. Pure observer: tool behavior is untouched.
+export function collectTurnFileDiffs(turnMessages) {
+    if (!Array.isArray(turnMessages))
+        return emptyFileDiffs();
+    const collected = collectTouchedFiles(turnMessages);
+    // Defensive copy: callers must never alias compact.ts internals.
+    return { read: [...collected.read], modified: [...collected.modified] };
+}
+// Accumulate one turn's record into the session-scoped record. Insertion
+// order is preserved, entries stay unique, and a path promoted from read to
+// modified (read in an earlier turn, written later) ends in modified only.
+// Neither input is mutated; the result is a fresh record.
+export function mergeFileDiffs(accumulated, turn) {
+    const base = readFileDiffs(accumulated);
+    const next = readFileDiffs(turn);
+    const read = [...base.read];
+    const modified = [...base.modified];
+    for (const p of next.read) {
+        if (!modified.includes(p) && !read.includes(p))
+            read.push(p);
+    }
+    for (const p of next.modified) {
+        const at = read.indexOf(p);
+        if (at >= 0)
+            read.splice(at, 1);
+        if (!modified.includes(p))
+            modified.push(p);
+    }
+    return { read, modified };
+}
+// Tolerant read of the `metadata.filediffs` value: missing keys read as
+// empty, and malformed values (wrong shape, non-string entries) degrade to
+// the valid subset — or empty — WITHOUT failing the session load. Always
+// returns a fresh record.
+export function readFileDiffs(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return emptyFileDiffs();
+    }
+    const record = value;
+    const rawRead = isStringList(record["read"]) ? record["read"] : [];
+    const rawModified = isStringList(record["modified"])
+        ? record["modified"]
+        : [];
+    const read = [];
+    const modified = [];
+    for (const raw of rawModified) {
+        const p = raw.trim();
+        if (p.length > 0 && !modified.includes(p))
+            modified.push(p);
+    }
+    const modifiedSet = new Set(modified);
+    for (const raw of rawRead) {
+        const p = raw.trim();
+        if (p.length === 0 || modifiedSet.has(p) || read.includes(p))
+            continue;
+        read.push(p);
+    }
+    return { read, modified };
+}
+// JSON-safe snapshot for `metadata.filediffs` persistence via the existing
+// updateSession/getSession APIs (no schema edits). Fresh copy every call.
+export function serializeFileDiffs(diffs) {
+    return readFileDiffs(diffs);
+}

package/dist/kilo.js

@@ -253,7 +253,7 @@ function readKiloCache(hasKey, now = Date.now()) {
     return slot.status;
 }
 // Manual refresh path: clears the discovery cache so the next fetch hits
-// `/models` again (used by `/models refresh` and provider switches).
+// `/model refresh` again (used by the refresh path and provider switches).
 export function clearKiloModelsCache() {
     kiloModelsCache.clear();
 }

package/dist/local-discovery.js

@@ -21,7 +21,7 @@
 // exposes them (llama-server meta.n_ctx_train -> contextLength). Nothing is
 // fabricated. Unreachable/malformed servers yield ok:false, never throw —
 // discovery failures are isolated per provider and silent by default (the
-// TUI surfaces them only via /models).
+// TUI surfaces them only via /model).
 //
 // Concurrency: createLocalDiscovery() owns one in-flight promise per scope
 // ("all" or one provider id), so overlapping refresh calls share work and
@@ -59,7 +59,7 @@ export function emptyLocalSnapshot() {
         version: 0,
     };
 }
-// One-line human summary for /models output (counts only, no transcript spam).
+// One-line human summary for /model refresh output (counts only, no transcript spam).
 export function summarizeLocalSnapshot(snap) {
     const parts = LOCAL_PROVIDER_IDS.map((id) => {
         const r = snap.results[id];

package/dist/media.js

@@ -0,0 +1,276 @@
+// Vision input (image attachments) for the harness.
+//
+// Scope (deliberate): PNG, JPEG, GIF, WebP only — the same four OpenCode
+// passes as image media. PDF, AVIF, BMP, audio, video, and other binaries
+// are rejected with an actionable convert-first error, never silently.
+// No resize/re-encode dependency (zero-dep policy): oversize images are
+// rejected with guidance instead of downscaled.
+//
+// Design (blast-radius minimal):
+// - History/transcript/session stay plain strings. The `read` tool stores
+//   image bytes under ~/.atom/media/ and returns a short descriptor token
+//   `[media:<id> <mime> <bytes>B]`. The TUI renders it as one text line;
+//   session.json stays small; /resume keeps working.
+// - Expansion happens at exactly one point per POST kind (openai-chat in
+//   zen.ts, anthropic-messages + gemini-generate in adapters.ts), which
+//   resolve descriptor tokens into provider-native image blocks. Missing
+//   files (pruned, deleted home) degrade to a text placeholder — never a
+//   crash, never a dropped turn.
+// - Compaction/summarization and text-only-model fallback use strip mode:
+//   descriptors become `[image: <name>]` prose markers, so the summarizer
+//   never pays for pixels.
+// - Context accounting stays honest: messageChars adds the deterministic
+//   base64 wire cost (ceil(bytes*4/3)) per descriptor — see
+//   mediaWireChars Bash in context-manager.ts.
+import { randomBytes } from "node:crypto";
+import { promises as fsp } from "node:fs";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomDir } from "./auth.js";
+export const SUPPORTED_IMAGE_MIMES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+]);
+// Ingest cap per image (raw bytes). Over it the read tool refuses with
+// guidance instead of downscaling (no image codec dependency).
+export const MEDIA_MAX_BYTES = 8 * 1024 * 1024;
+// Stored media older than this is pruned best-effort on the next media
+// write (fail-open — pruning never breaks reads).
+export const MEDIA_PRUNE_AFTER_MS = 7 * 24 * 3600 * 1000;
+export const MEDIA_DIRNAME = "media";
+// Descriptor token embedded in tool results / history text:
+// `[media:<id> <mime> <bytes>B]`, e.g. `[media:k3xq9z image/png 41204B]`.
+export const MEDIA_RE = /\[media:([A-Za-z0-9_-]{1,64}) ([a-z]+\/[a-z0-9.+-]+) (\d+)B\]/g;
+export function mediaDescriptor(id, mime, bytes) {
+    return `[media:${id} ${mime} ${bytes}B]`;
+}
+// Magic-byte sniff over the file head. Returns the image mime when the
+// bytes are a supported image, else null (caller falls through to the
+// text path or the unsupported-binary error).
+export function sniffImageMime(head) {
+    const b = head;
+    const n = b.length;
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (n >= 8 &&
+        b[0] === 0x89 &&
+        b[1] === 0x50 &&
+        b[2] === 0x4e &&
+        b[3] === 0x47 &&
+        b[4] === 0x0d &&
+        b[5] === 0x0a &&
+        b[6] === 0x1a &&
+        b[7] === 0x0a) {
+        return "image/png";
+    }
+    // JPEG: FF D8 FF
+    if (n >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) {
+        return "image/jpeg";
+    }
+    // GIF: "GIF87a" / "GIF89a"
+    if (n >= 6 &&
+        b[0] === 0x47 &&
+        b[1] === 0x49 &&
+        b[2] === 0x46 &&
+        b[3] === 0x38 &&
+        (b[4] === 0x37 || b[4] === 0x39) &&
+        b[5] === 0x61) {
+        return "image/gif";
+    }
+    // WebP: "RIFF" + 4 size bytes + "WEBP"
+    if (n >= 12 &&
+        b[0] === 0x52 &&
+        b[1] === 0x49 &&
+        b[2] === 0x46 &&
+        b[3] === 0x46 &&
+        b[8] === 0x57 &&
+        b[9] === 0x45 &&
+        b[10] === 0x42 &&
+        b[11] === 0x50) {
+        return "image/webp";
+    }
+    return null;
+}
+// True when the head looks like a PDF (%PDF magic). PDFs are rejected as
+// vision input with convert-first guidance (see unsupportedBinaryError).
+export function sniffPdf(head) {
+    return (head.length >= 4 &&
+        head[0] === 0x25 &&
+        head[1] === 0x50 &&
+        head[2] === 0x44 &&
+        head[3] === 0x46);
+}
+// Actionable error for binaries the harness cannot send as vision input.
+// Never throws; the model gets conversion guidance it can act on via bash.
+export function unsupportedBinaryError(filePath, kind, sizeBytes) {
+    const size = typeof sizeBytes === "number" ? ` (${sizeBytes} bytes)` : "";
+    if (kind === "pdf") {
+        return (`Error: cannot read ${filePath}${size} as vision input — PDFs are not supported. ` +
+            `Convert it first: export pages as PNG (e.g. \`pdftoppm -png ${filePath} page\`) and read the PNG, ` +
+            `or extract text (e.g. \`pdftotext ${filePath} -\`) and read that instead.`);
+    }
+    return (`Error: cannot read ${filePath}${size} — unsupported binary (only PNG, JPEG, GIF, WebP images ` +
+        `are read as vision input). Convert it to a supported image or extract its text first, then read that.`);
+}
+export function oversizeImageError(filePath, sizeBytes) {
+    const mb = (MEDIA_MAX_BYTES / (1024 * 1024)).toFixed(0);
+    return (`Error: ${filePath} is ${sizeBytes} bytes (over the ${mb} MiB image cap) — downscale it ` +
+        `first (e.g. with Python PIL or ImageMagick) and read the smaller file.`);
+}
+export function mediaDir(home) {
+    return path.join(atomDir(home), MEDIA_DIRNAME);
+}
+function mediaId() {
+    return `${Date.now().toString(36)}${randomBytes(6).toString("hex")}`;
+}
+export async function saveMedia(raw, mime, name, home) {
+    const dir = mediaDir(home);
+    try {
+        await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        // fail-open: write below still attempted
+    }
+    const id = mediaId();
+    try {
+        await fsp.writeFile(path.join(dir, `${id}.bin`), raw);
+        await fsp.writeFile(path.join(dir, `${id}.json`), JSON.stringify({ mime, name, bytes: raw.length }));
+    }
+    catch {
+        // fail-open: descriptor still returned; POST lowering degrades to a
+        // placeholder when the files are unreadable.
+    }
+    pruneMedia(dir);
+    return { id };
+}
+export function loadMedia(id, home) {
+    try {
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(id))
+            return null;
+        const dir = mediaDir(home);
+        const metaRaw = fs.readFileSync(path.join(dir, `${id}.json`), "utf8");
+        const meta = JSON.parse(metaRaw);
+        if (typeof meta.mime !== "string" || !SUPPORTED_IMAGE_MIMES.has(meta.mime))
+            return null;
+        const raw = fs.readFileSync(path.join(dir, `${id}.bin`));
+        return {
+            mime: meta.mime,
+            name: typeof meta.name === "string" ? meta.name : id,
+            bytes: raw.length,
+            base64: raw.toString("base64"),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// Delete stored media older than MEDIA_PRUNE_AFTER_MS. Fire-and-forget,
+// best-effort, never throws (called without await).
+function pruneMedia(dir) {
+    try {
+        const cutoff = Date.now() - MEDIA_PRUNE_AFTER_MS;
+        void fsp
+            .readdir(dir)
+            .then(async (entries) => {
+            for (const e of entries) {
+                if (!e.endsWith(".bin") && !e.endsWith(".json"))
+                    continue;
+                const p = path.join(dir, e);
+                try {
+                    const st = await fsp.stat(p);
+                    if (st.mtimeMs < cutoff)
+                        await fsp.rm(p, { force: true });
+                }
+                catch {
+                    // per-file fail-open
+                }
+            }
+        })
+            .catch(() => { });
+    }
+    catch {
+        // fail-open
+    }
+}
+// ---- Descriptor helpers (pure, no I/O) -----------------------------------
+// Deterministic wire cost of the descriptors in a string: base64 inflates
+// raw bytes by exactly 4/3. Used by messageChars so context accounting
+// stays honest.
+export function mediaWireChars(content) {
+    let n = 0;
+    MEDIA_RE.lastIndex = 0;
+    let m;
+    while ((m = MEDIA_RE.exec(content)) !== null) {
+        const bytes = Number(m[3]);
+        if (Number.isFinite(bytes) && bytes > 0)
+            n += Math.ceil(bytes / 3) * 4;
+    }
+    MEDIA_RE.lastIndex = 0;
+    return n;
+}
+export function hasMediaRefs(content) {
+    MEDIA_RE.lastIndex = 0;
+    const hit = MEDIA_RE.test(content);
+    MEDIA_RE.lastIndex = 0;
+    return hit;
+}
+// Strip mode: descriptors become prose markers. Used for compaction /
+// summarization POSTs and the text-only-model fallback retry.
+export function stripMedia(content) {
+    MEDIA_RE.lastIndex = 0;
+    const out = content.replace(MEDIA_RE, (_tok, _id, mime) => `[image omitted: ${mime}]`);
+    MEDIA_RE.lastIndex = 0;
+    return out;
+}
+// Server-authoritative image rejection: a 400 naming image/vision input
+// means this model/deployment takes no images — the caller retries once
+// with media stripped (mirrors the reasoning-effort knob precedent).
+export function isImageRejection(errText) {
+    if (!/image|vision|multimodal|media|picture/i.test(errText))
+        return false;
+    return /not supported|unsupported|does not support|do not support|cannot (read|see|view|process|accept)|invalid image|no.*vision|vision.*not|400/i.test(errText);
+}
+export function resolveMediaRefs(content, home) {
+    const media = [];
+    MEDIA_RE.lastIndex = 0;
+    const text = content.replace(MEDIA_RE, (_tok, id, _mime, _bytes) => {
+        const loaded = loadMedia(id, home);
+        if (!loaded) {
+            media.push({ ok: false, id });
+            return `[image unavailable: ${id}]`;
+        }
+        media.push({ ok: true, id, mime: loaded.mime, name: loaded.name, base64: loaded.base64 });
+        return `[image: ${loaded.name}]`;
+    });
+    MEDIA_RE.lastIndex = 0;
+    return { text, media };
+}
+export function historyHasMedia(history) {
+    for (const m of history) {
+        const c = m.content;
+        if (typeof c === "string" && hasMediaRefs(c))
+            return true;
+    }
+    return false;
+}
+// OpenAI-chat lowering for one message content: string in, string out when
+// no descriptors are present (byte-identical — existing payload tests hold),
+// else a text + image_url parts array. System role always strips.
+export function lowerOpenAIContent(role, content, mode = "send", home) {
+    if (!hasMediaRefs(content))
+        return content;
+    if (mode === "strip" || role === "system")
+        return stripMedia(content);
+    const { text, media } = resolveMediaRefs(content, home);
+    const parts = [{ type: "text", text }];
+    for (const m of media) {
+        if (!m.ok)
+            continue; // placeholder already inline in text
+        parts.push({
+            type: "image_url",
+            image_url: { url: `data:${m.mime};base64,${m.base64}` },
+        });
+    }
+    return parts;
+}

package/dist/overflow.js

@@ -0,0 +1,140 @@
+// Real-usage overflow trigger (ticket 02) — the auto-compaction decision
+// based on the provider's REAL reported token usage against each model's
+// usable limit (verified window minus a reserved output buffer), instead of
+// a fixed percentage estimate.
+//
+// Formula: usable = verified window − reserved; overflow when the last
+// POST's real total tokens (total_tokens, else prompt + completion + cache
+// read + cache write) >= usable.
+//
+// Honesty rules (same as the footer segment in context-windows.ts):
+// - Models with NO verified window never auto-fire (usable is undefined —
+//   a window is never invented, a percentage never fabricated).
+// - No real usage reported yet → no fire (nothing estimated).
+// - auto=false disables auto-compaction only; manual /compact is untouched
+//   (it never consults this module).
+//
+// This module is pure + testable: config/env reads go through the same
+// precedence as compactPct (env > atom.json > default). It imports
+// context-windows (metadata) and config (file fallback) at runtime only,
+// plus the Usage TYPE (erased at compile — no zen.js runtime cycle).
+// Compaction MECHANICS (summary, tail split, swap) stay in compact.ts,
+// owned by later tickets — this module only decides WHEN auto fires.
+import { loadAtomConfig } from "./config.js";
+import { contextWindowFor } from "./context-windows.js";
+// ---- Reserved output buffer ----
+// Default buffer kept free for the next generation (~20k tokens: one
+// summary-sized compaction output plus headroom for the reply that follows).
+export const OVERFLOW_RESERVE_DEFAULT = 20_000;
+// The buffer always fits at least one full summary-sized generation
+// (mirrors COMPACT_SUMMARY_MAX_TOKENS in compact.ts) — a smaller buffer
+// could not even emit the compaction summary it is reserving for.
+export const OVERFLOW_RESERVE_MIN = 4096;
+// Upper bound keeps the usable limit positive on the smallest verified
+// window (200K); per-model, the reserve is additionally capped at
+// window−1 so usable never drops below 1 token.
+export const OVERFLOW_RESERVE_MAX = 100_000;
+function clampReserve(n) {
+    const floored = Math.floor(n);
+    if (!Number.isFinite(floored))
+        return OVERFLOW_RESERVE_DEFAULT;
+    return Math.min(Math.max(floored, OVERFLOW_RESERVE_MIN), OVERFLOW_RESERVE_MAX);
+}
+// Reserved output buffer in tokens. Precedence: env ATOM_COMPACT_RESERVE
+// (tokens, e.g. "20000", clamped to [MIN, MAX]) → atom.json compactReserve
+// → default; invalid/unset falls through.
+export function compactReserveTokens() {
+    const raw = process.env.ATOM_COMPACT_RESERVE;
+    if (raw !== undefined) {
+        const text = raw.trim();
+        if (/^\d+(\.\d+)?$/.test(text)) {
+            const n = Number(text);
+            if (Number.isFinite(n))
+                return clampReserve(n);
+        }
+    }
+    const file = loadAtomConfig().config.compactReserve;
+    if (file !== undefined)
+        return clampReserve(file);
+    return OVERFLOW_RESERVE_DEFAULT;
+}
+// Auto-compaction master switch. Precedence: env ATOM_COMPACT_AUTO
+// (1/true/yes/on → on; 0/false/no/off → off) → atom.json compactAuto → on.
+// False disables AUTO-compaction only; manual /compact never reads this.
+export function compactAutoEnabled() {
+    const raw = process.env.ATOM_COMPACT_AUTO;
+    if (raw !== undefined) {
+        const text = raw.trim().toLowerCase();
+        if (["1", "true", "yes", "y", "on"].includes(text))
+            return true;
+        if (["0", "false", "no", "n", "off"].includes(text))
+            return false;
+    }
+    const file = loadAtomConfig().config.compactAuto;
+    if (file !== undefined)
+        return file;
+    return true;
+}
+// ---- Real total tokens ----
+// The last POST's real reported total: total_tokens when the provider sent
+// it, else the sum of the reported parts (prompt + completion + separately-
+// reported cache read/write — prompt_tokens is already cache-inclusive for
+// exclusive-cache providers, so providers that report cache separately need
+// the extra terms to count cached context). Undefined when nothing usable
+// was reported (absent fields mean "not reported", never zero).
+export function realTotalTokens(usage) {
+    if (!usage)
+        return undefined;
+    const t = usage.total_tokens;
+    if (typeof t === "number" && Number.isFinite(t))
+        return Math.max(0, Math.floor(t));
+    let seen = false;
+    let sum = 0;
+    const parts = [usage.prompt_tokens, usage.completion_tokens, usage.cacheReadTokens, usage.cacheWriteTokens];
+    for (const v of parts) {
+        if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
+            seen = true;
+            sum += Math.floor(v);
+        }
+    }
+    return seen ? sum : undefined;
+}
+// ---- Usable limit + decision ----
+// Usable limit for a model: verified window minus the reserved buffer, or
+// undefined when the model has no verified window (never invented). The
+// reserve is capped per-model at window−1 so usable stays >= 1.
+export function usableLimitFor(model, reserveOverride) {
+    const window = contextWindowFor(model);
+    if (window === undefined)
+        return undefined;
+    const reserve = typeof reserveOverride === "number" && Number.isFinite(reserveOverride)
+        ? clampReserve(reserveOverride)
+        : compactReserveTokens();
+    return Math.max(1, window - Math.min(reserve, window - 1));
+}
+// Honest percent of the verified window consumed by the last POST's real
+// total, or undefined when the window is unknown or nothing was reported
+// (never fabricated — same rule as formatTokenSegment's bare `token: NK`).
+export function realUsagePct(usage, model) {
+    const window = contextWindowFor(model);
+    if (window === undefined)
+        return undefined;
+    const total = realTotalTokens(usage);
+    if (total === undefined)
+        return undefined;
+    return Math.round((100 * total) / window);
+}
+// Auto-compact trigger: true only when auto is on, the model has a verified
+// window, real usage was reported, and real total >= usable limit.
+export function shouldAutoCompactReal(model, usage, opts) {
+    const auto = opts?.auto ?? compactAutoEnabled();
+    if (!auto)
+        return false;
+    const usable = usableLimitFor(model, opts?.reserve);
+    if (usable === undefined)
+        return false;
+    const total = realTotalTokens(usage);
+    if (total === undefined)
+        return false;
+    return total >= usable;
+}

package/dist/policy.js

@@ -43,6 +43,14 @@ export function decidePolicy(name, args, ctx) {
         return { kind: "allow", via: "skill-grant" };
     return { kind: "prompt" };
 }
+export function decideApproval(name, args, ctx, preview = null) {
+    const outcome = decidePolicy(name, args, ctx);
+    if (outcome.kind === "deny")
+        return { decision: "deny", via: "deny", preview };
+    if (outcome.kind === "allow")
+        return { decision: "allow", via: outcome.via, preview };
+    return { decision: "prompt", via: "prompt", preview };
+}
 // ---- 2. Skill-grant trust boundary ----
 // Approval-gated tools: the dangerous capabilities a grant can unlock
 // (shell, filesystem mutation; network/process execution ride bash).